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

#### 调用审查

```python
# 在主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循环）：
```python
# ❌ 错误：不要这样写
while not finished:
    search_results = search()
    if validate(search_results):
        finished = True
```

**正确方式**（系统提示词引导）：
```python
# ✅ 正确：在system_prompt中描述逻辑
system_prompt = """
读取 /iteration_decision.json：
- 如果 decision="FINISH" → 生成报告
- 如果 decision="CONTINUE" → 回到搜索步骤
"""
```

### 2. 虚拟文件系统

**关键理解**：
- 文件存储在 `state["files"]` 字典中
- 主Agent和SubAgent共享同一个files对象
- 文件路径必须以 `/` 开头

**正确使用**：
```python
# ✅ 正确的文件路径
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` 自主判断下一步

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

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

### 4. 并行搜索

**关键理解**：
- 使用`ThreadPoolExecutor`实现真正的并发
- 不是简单的串行循环调用

**实现要点**：
```python
# ✅ 正确：使用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