first commit
This commit is contained in:
闫旭隆
338
开发流程指南.md
Normal file
338
开发流程指南.md
Normal file
@ -0,0 +1,338 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user