文档驱动开发规范
在生成代码或修复 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 调用规则（工具选择、速率限制、安全边界、失败降级与可追溯输出）