filename.py
【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno
Status:PASS/FAIL
Description:What the test does and what was observed.
Result:Summary of success/failure.
### 3.4 Cookbook 结构检查器：可自动化的模式约束 `./scripts/validate.sh` 中针对 cookbook 运行了一个专门的结构检查器，其实现位于 [cookbook/scripts/check_cookbook_pattern.py](https://link.gitcode.com/i/5d9d3cd5a8d32a884bb7682ad8a7f462)。从源码看，它用 AST 解析并强制以下可教学的模式： - 模块顶部必须有 docstring（`missing_docstring`）； - 除下划线前缀的支持模块外，必须包含 `if __name__ == "__main__":` 执行门（`missing_main_gate`）； - 必须存在以 `# ---` 或 `# ===` 风格 banner 注释划分的分节，且"Create ..."分节必须出现在"Run ..."分节之前（`missing_create_section`、`missing_run_section`、`section_order`）； - Python 源码中不允许出现 emoji 字符（`emoji_not_allowed`，正则范围为 `\U0001F300-\U0001FAFF`）。 这意味着 cookbook 不仅是可运行的示例，还是被 CI 级校验器守护的"模式样板"。 ## 四、代码位置索引：快速定位核心模块 文档给出了一张精确的代码地图，与仓库实际布局一一对应： | 模块 | 位置 | |------|------| | 核心 Agent 代码 | `libs/agno/agno/agent/` | | Teams | `libs/agno/agno/team/` | | Workflows | `libs/agno/agno/workflow/` | | Tools | `libs/agno/agno/tools/` | | Models | `libs/agno/agno/models/` | | Knowledge/RAG | `libs/agno/agno/knowledge/` | | Memory | `libs/agno/agno/memory/` | | Learning | `libs/agno/agno/learn/` | | 数据库适配器 | `libs/agno/agno/db/` | | 向量数据库 | `libs/agno/agno/vectordb/` | | 测试 | `libs/agno/tests/` | 例如，`agent/` 目录下实际包含 `agent.py`、`protocol.py`、`factory.py`、`remote.py` 以及 `_run.py`、`_session.py`、`_storage.py` 等支撑模块；`learn/` 目录下包含 `machine.py`（LearningMachine）、`config.py`、`schemas.py`、`stores/` 等，正好对应 cookbook 中 `learning=True` 背后的实现层。 ## 五、编码模式：五条必须遵守的核心规则 文档将详细模式放在 `.cursorrules` 中，但提炼了五条关键规则： - **绝不在循环中创建 Agent**——应复用 Agent 以提升性能； - **使用 `output_schema` 获取结构化响应**——该参数在 [agent.py](https://link.gitcode.com/i/731dfdd5caf7e437ef25bafedef11348) 中定义为 `Optional[Union[Type[BaseModel], Dict[str, Any]]]`，并在第 315 行注释说明"为 True 时，模型的响应会被转换为 output_schema"； - **生产环境用 PostgreSQL，SQLite 仅用于开发**； - **从单 Agent 开始，确有必要时再扩展**（scale up only when needed）； - **同步与异步并存**——所有公开方法都必须同时提供同步与异步两个变体（例如 [agent.py](https://link.gitcode.com/i/5da7a321fad12ce1c9ae66206e65f3c5) 中的 `print_response` 与第 1279 行的 `aprint_response` 一一对应）。 ## 六、运行代码：cookbook 与测试的标准命令 **运行 cookbook：** ```bash .venvs/demo/bin/python cookbook/<folder>/<file>.py运行测试：
source .venv/bin/activate pytest libs/agno/tests/ # 运行某个具体的测试文件 pytest libs/agno/tests/unit/test_agent.py七、实现新功能的四步流程
文档给出了实现功能的固定顺序：
- 先在
specs/中查找设计文档——若存在则必须遵循； - 参考既有模式——找到类似代码并沿用其约定；
- 创建 cookbook——每个模式都应有对应的示例；
- 更新 implementation.md——标记已完成的工作。
八、提交代码前的强制门槛：format.sh 与 validate.sh
在推送代码或创建 PR 之前，必须运行以下脚本且保证零错误：
# 先激活虚拟环境 source .venv/bin/activate # 格式化所有代码（ruff format） ./scripts/format.sh # 校验所有代码（ruff check、mypy） ./scripts/validate.sh从脚本源码可以进一步了解它们到底做了什么：
- scripts/format.sh 对
libs/agno、libs/agnoctl、libs/agno_infra与cookbook四个目标依次执行ruff format与ruff check --select I --fix（import 排序自动修复）；若系统未安装ruff，会回退使用.venv/bin/ruff，否则提示先运行./scripts/dev_setup.sh。 - scripts/validate.sh 对
libs/agno与libs/agnoctl执行ruff check与mypy（分别使用各自pyproject.toml中的配置），对cookbook执行ruff check与check_cookbook_pattern.py模式检查；脚本头部注释明确说明"任一失败即返回非零退出码，可安全用于 CI 门禁"，且agno_infra不在开发 venv 中、由独立 CI 任务校验。
九、PR 规范：标题格式、描述模板与 GitHub 操作技巧
9.1 PR 标题格式（三选一）
type: description—— 例如feat: add workflow serialization[type] description—— 例如[feat] add workflow serializationtype-kebab-case—— 例如feat-workflow-serialization
合法类型：feat、fix、cookbook、test、refactor、chore、style、revert、release。
9.2 PR 描述
必须遵循仓库 PR 模板，包含：变更摘要、变更类型（bug fix、新功能等）、已完成的检查清单项、额外的上下文说明。
9.3 GitHub 操作避坑：gh pr edit的替代方案
文档记录了一个实际运维经验：gh pr edit可能因经典 projects 相关的 GraphQL 错误而失败，此时应直接调用 API：
# 更新 PR body gh api repos/agno-agi/agno/pulls/<PR_NUMBER> -X PATCH -f body="<PR_BODY>" # 或从文件读取 body gh api repos/agno-agi/agno/pulls/<PR_NUMBER> -X PATCH -f body="$(cat /path/to/body.md)"【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
