deepagents----/开发流程指南.md

Deep Research System - 开发流程指南

框架： DeepAgents (LangChain) | 最后更新： 2025-10-31

---

🎯 开发优先级

Phase 1: 基础架构 (Day 1-2)

目标: 搭建项目基础，配置开发环境

环境配置：

• 激活虚拟环境：conda activate deep_research_env
• 创建 requirements.txt（见开发文档）
• 安装依赖：pip install -r requirements.txt
• 验证DeepAgents安装：python -c "import deepagents; print('OK')"

项目结构：

• 创建目录结构（按开发文档 "项目结构" 章节）
• 创建 .env 文件（复制 .env.example）
• 配置 .gitignore（包含 .env）

核心工具实现：

• 创建 src/config.py（LLM配置和环境变量加载）
• 创建 src/tools/search_tools.py（实现 batch_internet_search）
• 测试 API 连接（DashScope + Tavily）

验收标准:

• ✅ import deepagents 成功
• ✅ API能成功调用（测试搜索功能）
• ✅ 批量搜索工具能真正并行执行（使用ThreadPoolExecutor）

代码审查: 完成后调用 code-reviewer 审查工具实现和配置文件

---

Phase 2: SubAgent实现 (Day 3-5)

目标: 实现6个SubAgent的配置和系统提示词

• 创建 src/agents/subagents.py
• 实现 6个SubAgent配置（intent-analyzer, search-orchestrator, source-validator, content-analyzer, confidence-evaluator, report-generator）
• 编写单元测试验证配置格式

验收标准: 所有SubAgent使用正确字段名（system_prompt 不是 prompt），system_prompt足够详细，配置格式符合DeepAgents规范

代码审查: ⚠️ 必须审查 - SubAgent配置是核心组件

---

Phase 3: 主Agent (Day 6-7)

目标: 实现ResearchCoordinator主Agent

• 创建 src/agents/coordinator.py
• 编写ResearchCoordinator系统提示词
• 集成SubAgent配置
• 测试整体流程（单次迭代）
• 调试迭代逻辑（多轮迭代）

验收标准: 主Agent能正确调用所有SubAgent，迭代逻辑正确，虚拟文件系统正常工作

代码审查: ⚠️ 必须审查 - 主Agent是系统核心

---

Phase 4: CLI和打磨 (Day 8-10)

目标: 实现命令行界面和用户体验优化

• 实现CLI命令（research, config, history, resume）
• 实现进度显示 (Rich库)
• 完善错误处理和降级策略
• 编写用户文档

验收标准: 所有CLI命令功能正常，进度显示实时更新，错误信息友好

代码审查: 完成后整体审查

---

🔄 开发工作流与代码审查

开发-审查循环

开发阶段性功能 → 代码审查 → 修正问题 → 继续开发下一阶段

何时触发代码审查

触发时机	审查范围	优先级
完成Phase任务	整个Phase的所有文件	🔴 必须
实现关键组件	SubAgent配置、主Agent、工具实现	🔴 必须
重大重构	受影响的所有文件	🔴 必须
修复复杂bug	修改的文件	🟡 建议

如何使用代码审查子agent

调用审查

# 在主Claude Code窗口中
/task code-reviewer

# 然后提供上下文
"""
我刚完成了 Phase 2 的 SubAgent 配置，请审查以下文件：
1. src/agents/subagents.py - 6个SubAgent的配置
2. src/tools/search_tools.py - batch_internet_search工具

请检查是否符合DeepAgents框架规范和开发文档
"""

审查报告包含

• ✅ 正确实现的部分
• ⚠️ 需要改进的部分（带建议代码）
• ❌ 必须修复的错误（带正确写法）
• 优先级标识（🔴高 / 🟡中 / 🟢低）

处理审查结果

🔴 高优先级（必须修复）

• 立即修复，这些通常是框架规范错误
• 修复后建议再次审查确认

🟡 中优先级（建议改进）

• 评估是否影响功能
• 如果影响代码质量，建议修复

🟢 低优先级（可选优化）

• 记录到TODO列表
• 在时间允许时优化

代码审查子agent的能力边界

✅ 子agent会做的

1. 详细审查 - 对照DeepAgents源码和开发文档检查
2. 提供建议 - 指出问题、提供修改建议和示例
3. 有限修正（需征得同意）- 格式问题、拼写错误、简单API错误

❌ 子agent不会做的

1. 大规模重构 - 保持代码所有权
2. 改变架构设计 - 架构决策由你主导
3. 添加新功能 - 只审查不扩展
4. 未经确认的修改 - 尊重开发决策

---

📊 进度管理（给Claude Code主窗口）

重要区分：

• 本节内容是给 Claude Code 主窗口看的，用于管理开发Deep Research System的任务
• 使用 Claude Code 的 TodoWrite 工具
• 不要与 DeepAgents 框架内部的 write_todos 工具混淆（那是给 ResearchCoordinator 主Agent用的）

Claude Code 主窗口使用 TodoWrite 工具

开发开始时：

TodoWrite([
    {"content": "Phase 1: 基础架构", "status": "in_progress", "activeForm": "搭建基础架构"},
    {"content": "Phase 2: SubAgent实现", "status": "pending", "activeForm": "实现SubAgent"},
    {"content": "Phase 3: 主Agent", "status": "pending", "activeForm": "实现主Agent"},
    {"content": "Phase 4: CLI和打磨", "status": "pending", "activeForm": "实现CLI"}
])

Phase完成时：

TodoWrite([
    {"content": "Phase 1: 基础架构", "status": "completed", "activeForm": "搭建基础架构"},
    {"content": "Phase 2: SubAgent实现", "status": "in_progress", "activeForm": "实现SubAgent"},
    ...
])

代码审查集成到进度管理

TodoWrite([
    {"content": "实现SubAgent配置", "status": "completed", "activeForm": "实现SubAgent配置"},
    {"content": "代码审查 - SubAgent配置", "status": "in_progress", "activeForm": "审查SubAgent配置"},
    {"content": "修复审查发现的问题", "status": "pending", "activeForm": "修复审查问题"},
    {"content": "实现主Agent", "status": "pending", "activeForm": "实现主Agent"}
])

---

⚠️ 关键注意事项

1. DeepAgents框架理解

核心原则：

• 主Agent不是传统Python程序流程控制
• 通过系统提示词引导LLM自主决策
• 通过文件读写实现状态管理

错误示例（Python循环）：

# ❌ 错误：不要这样写
while not finished:
    search_results = search()
    if validate(search_results):
        finished = True

正确方式（系统提示词引导）：

# ✅ 正确：在system_prompt中描述逻辑
system_prompt = """
读取 /iteration_decision.json：
- 如果 decision="FINISH" → 生成报告
- 如果 decision="CONTINUE" → 回到搜索步骤
"""

2. 虚拟文件系统

关键理解：

• 文件存储在 state["files"] 字典中
• 主Agent和SubAgent共享同一个files对象
• 文件路径必须以 / 开头

正确使用：

# ✅ 正确的文件路径
write_file("/search_queries.json", content)
read_file("/iteration_1/sources.json")

# ❌ 错误的文件路径
write_file("search_queries.json", content)  # 缺少前导 /

3. 迭代控制

关键理解：

• 不使用Python while循环
• 系统提示词描述"如果...则..."逻辑
• LLM读取 iteration_decision.json 自主判断下一步

实现方式：

# SubAgent (confidence-evaluator) 写入决策文件
{
  "decision": "CONTINUE",  # 或 "FINISH"
  "current_iteration": 2,
  "reason": "置信度未达标，需要继续搜索"
}

# 主Agent在system_prompt中被引导读取这个文件并决策
# LangGraph会持续调用主Agent直到它决定结束

4. 并行搜索

关键理解：

• 使用ThreadPoolExecutor实现真正的并发
• 不是简单的串行循环调用

实现要点：

# ✅ 正确：使用ThreadPoolExecutor
with ThreadPoolExecutor(max_workers=5) as executor:
    results = executor.map(search_single, queries)

# ❌ 错误：串行调用
for query in queries:
    result = search(query)  # 不是并行

5. 置信度计算

严格遵守公式：

置信度 = (来源可信度 × 50%) + (交叉验证 × 30%) + (时效性 × 20%)

来源可信度: Tier1=0.95, Tier2=0.80, Tier3=0.65, Tier4=0.45 (平均值)
交叉验证: 1源=0.4, 2-3源=0.7, 4+源=1.0, 有矛盾-0.3
时效性: <6月=1.0, 6-12月=0.9, 1-2年=0.7, 2-3年=0.5, >3年=0.3

实现建议：

• 在 confidence-evaluator 的 system_prompt 中详细说明公式
• 让LLM按步骤计算，而不是创建独立工具

6. 错误处理原则

降级运行优先：

• 部分失败不应导致整体失败
• 5个查询中2个失败 → 使用3个成功的继续
• 单个来源提取失败 → 不影响其他来源

重试策略：

• 自动重试2-3次（指数退避）
• 超时：降低并行度重试
• API限流：等待30秒后重试

---

📚 相关文档

• 开发文档: 开发文档_V1.md - 技术实现细节
• 需求文档: 需求文档_V1.md - 产品需求和业务逻辑
• 代码审查agent: .claude/agents/code-reviewer.md - 审查规范

---

🎯 成功标准

代码质量

• 所有代码通过 code-reviewer 审查
• 符合DeepAgents框架规范
• 与开发文档完全一致
• 有适当的错误处理

功能完整性

• 所有Phase完成并测试通过
• 三种深度模式正常工作
• 迭代逻辑正确执行
• 报告生成符合规范

用户体验

• CLI命令响应快速
• 进度显示实时更新
• 错误信息清晰友好
• 配置简单直观

---

文档版本： 1.0 | 最后更新： 2025-10-31