Skip to content

Latest commit

 

History

History
349 lines (259 loc) · 11.5 KB

deepresearch-complete-guide.md

File metadata and controls

349 lines (259 loc) · 11.5 KB

DeepResearch 完整复刻指南

本文档是 DeepResearch 工作流在当前项目中的完整复刻指南，包含配置说明、工作流结构、关键节点配置和使用说明。

项目概述

DeepResearch 是一个多智能体研究工作流，源自 deer-flow 项目。本指南说明如何在前端界面配置该工作流，实现完整的研究计划生成、执行和报告生成流程。

复刻程度

总体复刻程度：95%+

已完全复刻的功能

  • ✅ 所有核心节点（coordinator, planner, researcher, coder, reporter 等）
  • ✅ 完整的路由逻辑（planner_router, human_feedback_router, research_team）
  • ✅ 循环执行逻辑（loop_condition_node）
  • ✅ 状态管理（plan_iterations, max_plan_iterations, current_plan）
  • ✅ 中断和人工反馈（human_input）
  • ✅ 工具集成（web_search, code_interpreter）

架构差异

  • ⚠️ 动态路由 vs 静态条件边：当前项目使用 router_node 处理路由，而非节点直接返回 Command 对象
    • 影响：需要预先定义所有路由分支
    • 解决方案：使用 router_node 实现等价功能

工作流结构

START
  ↓
coordinator (初始化状态: max_plan_iterations=3, plan_iterations=0)
  ↓
background_investigator (可选，背景调研)
  ↓
planner (生成研究计划，plan_iterations += 1)
  ↓
planner_router (路由决策)
  ├─→ reporter (max_iterations: plan_iterations >= max_plan_iterations)
  ├─→ reporter (direct_report: has_enough_context == true)
  └─→ human_feedback (needs_review: has_enough_context == false)
        ↓
      human_feedback_router (用户输入路由)
        ├─→ research_team (accepted: 用户输入 [ACCEPTED])
        └─→ planner (edit_plan: 其他情况，循环回到 planner)
              ↓
research_team (路由到执行节点)
  ├─→ researcher (step_type == 'research')
  │     ↓
  │   researcher_loop_check
  │     ├─ continue_loop (loop_back) → research_team
  │     └─ exit_loop → reporter
  │
  ├─→ coder (step_type == 'processing')
  │     ↓
  │   coder_loop_check
  │     ├─ continue_loop (loop_back) → research_team
  │     └─ exit_loop → reporter
  │
  └─→ planner (所有步骤完成)
        ↓
reporter (生成最终报告)
  ↓
END

核心节点配置

1. coordinator (agent)

功能：处理用户输入和澄清

配置要点：

  • 初始化状态：context.max_plan_iterations = 3, context.plan_iterations = 0
  • 处理用户澄清（最多 3 轮）
  • 存储澄清后的主题到 context.clarified_research_topic

systemPrompt 关键部分：

IMPORTANT - Initialize context:
- Set context.max_plan_iterations = 3 (default, can be configured)
- Set context.plan_iterations = 0
- Store the clarified topic in context.clarified_research_topic.

2. planner (agent)

功能：生成研究计划

配置要点：

  • 每次调用时增加 context.plan_iterations += 1
  • 生成包含步骤的计划，存储到 context.current_plan
  • 计划包含 has_enough_context 字段

systemPrompt 关键部分：

IMPORTANT:
- Store the plan in context.current_plan as a dictionary
- Increment context.plan_iterations by 1 each time this node is called
- Set context.max_plan_iterations = 3 if it is not already set
- If has_enough_context is true, the plan is complete and ready for execution
- If has_enough_context is false, the plan needs human review
- Each step must have execution_res field (initially null/empty)

计划格式：

{
  "title": "Research Title",
  "thought": "Research description",
  "steps": [
    {
      "title": "Step 1",
      "description": "Step description",
      "step_type": "research",
      "need_search": true,
      "execution_res": null
    }
  ],
  "has_enough_context": false
}

3. planner_router (router_node)

功能：根据计划状态路由到不同节点

路由规则（按优先级）：

  1. max_iterations (优先级 0) → reporter

    • 条件：context.get('plan_iterations', 0) >= context.get('max_plan_iterations', 3)
    • 说明：达到最大迭代次数，直接生成报告

  2. direct_report (优先级 1) → reporter

    • 条件：context.get('current_plan', {}).get('has_enough_context', False) == True
    • 说明：计划已有足够上下文，直接生成报告

  3. needs_review (优先级 2) → human_feedback

    • 条件：not context.get('current_plan', {}).get('has_enough_context', False)
    • 说明：计划需要人工审核

默认路由：needs_review

4. human_feedback (human_input)

功能：人工审核计划

配置要点：

  • interrupt_before: true - 在执行前中断等待用户输入
  • 提示用户输入 [ACCEPTED] 或 [EDIT_PLAN] 后跟编辑内容

5. human_feedback_router (router_node)

功能：根据用户输入路由

路由规则：

  1. accepted (优先级 0) → research_team

    • 条件：len(messages) > 0 and '[ACCEPTED]' in str(messages[-1].content)
    • 说明：用户接受计划，直接执行

  2. edit_plan (优先级 1) → planner

    • 条件：True (默认)
    • 说明：用户编辑计划，重新规划

6. research_team (router_node)

功能：路由到执行节点（researcher/coder）

路由规则（按优先级）：

  1. researcher (优先级 0) → researcher

    • 条件：找到第一个未完成步骤，且 step_type == 'research'
    • 表达式：len([s for s in context.get('current_plan', {}).get('steps', []) if not s.get('execution_res')]) > 0 and [s for s in context.get('current_plan', {}).get('steps', []) if not s.get('execution_res')][0].get('step_type') == 'research'

  2. coder (优先级 1) → coder

    • 条件：找到第一个未完成步骤，且 step_type == 'processing'
    • 表达式：len([s for s in context.get('current_plan', {}).get('steps', []) if not s.get('execution_res')]) > 0 and [s for s in context.get('current_plan', {}).get('steps', []) if not s.get('execution_res')][0].get('step_type') == 'processing'

  3. planner (优先级 2) → planner

    • 条件：所有步骤完成或没有步骤
    • 表达式：not context.get('current_plan', {}).get('steps', []) or all(s.get('execution_res') for s in context.get('current_plan', {}).get('steps', []))

默认路由：planner

7. researcher (agent)

功能：执行研究任务

工具配置：

  • web_search - 网页搜索（已包含网页内容获取）

systemPrompt 关键部分：

After completing the research, store the findings in context.current_plan.steps[<current_step_index>].execution_res.

8. coder (agent)

功能：执行代码分析

工具配置：

  • code_interpreter - Python 代码执行

systemPrompt 关键部分：

After completing the analysis, store the results in context.current_plan.steps[<current_step_index>].execution_res.

9. loop_condition_node (researcher_loop_check / coder_loop_check)

功能：检查计划是否完成

配置：

  • conditionType: "while"
  • condition: any(not s.get('execution_res') for s in context.get('current_plan', {}).get('steps', []))
  • maxIterations: 20

边配置：

  • continue_loop (loop_back) → research_team
  • exit_loop → reporter

10. reporter (agent)

功能：生成最终报告

systemPrompt 关键部分：

Use the information from context.current_plan.steps[].execution_res to create the final report.

The report should include:
1. Executive Summary
2. Key Findings
3. Detailed Analysis
4. Conclusions
5. Key Citations (all references at the end)

状态管理

关键状态字段

字段 类型 说明 初始化位置
context.max_plan_iterations int 最大计划迭代次数 coordinator
context.plan_iterations int 当前计划迭代次数 coordinator (初始化为 0)
context.current_plan dict 当前研究计划 planner
context.current_plan.steps[] list 计划步骤列表 planner
context.current_plan.steps[].execution_res str 步骤执行结果 researcher/coder
context.clarified_research_topic str 澄清后的研究主题 coordinator

状态更新流程

  1. coordinator → 初始化 max_plan_iterations=3, plan_iterations=0
  2. planner → 每次调用 plan_iterations += 1，生成 current_plan
  3. researcher/coder → 更新 current_plan.steps[].execution_res
  4. loop_condition_node → 检查所有步骤是否完成

工具配置

可用工具

工具ID 实际工具 说明
web_search TavilyTools.web_search_using_tavily 网页搜索（已包含网页内容获取）
code_interpreter PythonTools.run_python_code Python 代码执行

工具配置格式

{
  "tools": {
    "builtin": ["web_search", "code_interpreter"]
  }
}

使用说明

1. 加载图配置

图配置文件：docs/deepresearch-complete-graph.json

可以直接在前端界面加载该 JSON 文件，或使用图构建器手动创建节点和边。

2. 配置要点

  1. 状态初始化：确保 coordinator 节点正确初始化状态
  2. 路由配置：确保所有 router_node 的路由规则正确配置
  3. 循环控制：设置合理的 maxIterations 防止无限循环
  4. 工具配置：确保所需工具已注册并可用

3. 测试验证

  • ✅ 测试完整工作流执行
  • ✅ 验证 planner_router 的 3 个路由分支
  • ✅ 验证 human_feedback_router 的 2 个路由分支
  • ✅ 验证 research_team 的路由逻辑
  • ✅ 验证循环逻辑（researcher/coder → loop_check → research_team）
  • ✅ 验证中断和恢复功能

架构差异说明

动态路由 vs 静态条件边

Deer-Flow 实现：

  • 节点可以直接返回 Command(goto="...") 对象
  • 路由决策在节点执行时动态决定

当前项目实现：

  • 使用 router_node 处理路由决策
  • 路由规则在配置时预先定义
  • 功能等价，但实现方式不同

影响：

  • 需要预先定义所有可能的路由分支
  • 无法实现基于 agent 输出内容的完全动态路由
  • 但通过 router_node 可以实现等价功能

解决方案

使用 router_node 处理复杂的路由逻辑：

  • planner_router - 处理 planner 的 3 个路由分支
  • human_feedback_router - 处理用户输入路由
  • research_team - 处理执行节点路由

能力验证

✅ 已支持的能力

  1. 复杂条件表达式 - 支持嵌套对象访问、列表推导式等
  2. Loop Back 边 - 支持可视化编辑和手动路径调整
  3. 状态上下文访问 - 支持在条件表达式中访问复杂对象
  4. 中断和恢复 - 支持 human_input 节点的中断功能
  5. 多规则路由 - 支持 router_node 的多规则路由

⚠️ 限制

  1. 条件表达式 - 不支持 next() 函数，需要使用列表推导式替代
  2. 动态路由 - 无法实现完全基于 agent 输出内容的动态路由
  3. 工具名称 - 需要使用项目定义的工具ID（如 code_interpreter 而非 python_repl）

参考资源

总结

DeepResearch 工作流已成功复刻到当前项目，复刻程度达到 95%+。所有核心功能都已实现，包括完整的路由逻辑、循环执行、状态管理和工具集成。通过使用 router_node 处理路由决策，实现了与原始实现等价的功能。