文档驱动开发规范

在生成代码或修复 bug 时，先看官方文档与示例，再动手实现。

⚠️ 核心强制要求

必须查文档的场景

• 落地新功能、接第三方库 API、或排查 API 报错时，先查官方文档

• 遇到 AttributeError / TypeError / 版本变更不确定时，必须验证 API 定义与示例

• 对项目自带封装的内部 API，可酌情跳过

Agent 执行步骤

• 停止猜测：明确要查的 API/模块名称和版本

• 查阅文档：优先使用 Context7 获取官方文档；若不可用再用 DuckDuckGo 搜索官方来源并二次核验

• 基于文档实现：依据文档的参数、返回值和示例实现或修复代码

MCP 调用基线（文档查阅场景）

• 文档/API 问题优先使用 Context7 ，最新公告或入口信息再使用 DuckDuckGo

• 单轮最多调用一种外部服务；确需多工具时串行并说明理由

• 查询保持最小必要（关键词、结果数、时间窗、tokens）

• 发生 429/限流时，退避 20 秒并缩小范围后重试

• 输出中附“工具调用简报”（工具、输入摘要、参数、时间、来源、重试）

• 默认离线优先，不上传敏感信息，遵守 robots/ToS 与隐私约束

AI Agent 行为要求

问题识别

问题类型 特征 处理方式

API 不存在 AttributeError: 'X' has no attribute 'Y'

查找正确的 API

参数错误 TypeError: unexpected keyword argument

查找正确的参数

行为异常 结果不符合预期 查找正确的用法

版本问题 某版本后 API 变更 查找版本差异

收集错误信息

必须收集：

• 完整的错误堆栈

• 相关代码片段

• 使用的库/框架版本

基于文档实现（禁止猜测）

错误：基于猜测实现

index.query(question, top_k=10) # 可能参数名不对

正确：基于文档实现

查阅文档后确认正确的参数名

index.query(question, similarity_top_k=10)

修复后验证

• 运行测试确认修复

• 检查是否引入新问题

• 验证在不同场景下的表现

参考资料

• references/api-verification.md

• API 验证流程详细说明（问题识别、文档查阅、实施修复）

• references/search-strategy.md

• 文档搜索策略与提问指引

• references/mcp-usage-rules.md

• MCP 调用规则（工具选择、速率限制、安全边界、失败降级与可追溯输出）