文档驱动开发规范

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

---

⚠️ 核心强制要求

必须查文档的场景

• 落地新功能、接第三方库 API、或排查 API 报错时，先查官方文档
• 遇到 AttributeError / TypeError / 版本变更不确定时，必须验证 API 定义与示例
• 对项目自带封装的内部 API，可酌情跳过

Agent 执行步骤

1. 停止猜测：明确要查的 API/模块名称和版本
2. 查阅文档：优先使用 Context7 获取官方文档；若不可用再用 DuckDuckGo 搜索官方来源并二次核验
3. 基于文档实现：依据文档的参数、返回值和示例实现或修复代码

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 调用规则（工具选择、速率限制、安全边界、失败降级与可追溯输出）