本文檔系統闡述 DeerFlow 中 Planner 的職責邊界、端到端執行流程、關鍵節點設計、數據結構、容錯與人審機制，以及與研究/編碼子代理的協同方式。面向開發與運維讀者，幫助快速理解與調優 Planner 相關鏈路。
時序圖（Sequence Diagram）
1. 角色與職責
- 協調器
coordinator：識別用戶請求類型；將研究類問題通過工具信號handoff_to_planner路由給 Planner；必要時在規劃前觸發“背景檢索”。 - 規劃器
planner：依據嚴格的規劃提示詞與結構化輸出模式，產出Plan（包含步驟、類型與是否需要檢索等元數據）。 - 人審
human_feedback：對Plan進行人工把關；支持接受或要求修改。 - 研究者
researcher：執行research類型步驟（檢索/爬取/RAG）。 - 工程師
coder：執行processing類型步驟（計算/編程/數據加工）。 - 報告器
reporter：將已收集的信息與分析組織成最終報告。
2. 工作流與時序
- User → Coordinator：用戶提出研究類問題（任意語言，保持同語回復）。
- Coordinator → Tool Call：LLM 綁定
handoff_to_planner工具。若判斷為研究請求，則調用該工具（可攜帶locale、research_topic）。 - 可選 Background Investigation：當啟用
enable_background_investigation=true時，協調器先進入background_investigator節點進行“輕量背景檢索”，將結果拼入 Planner 提示（作為額外用戶消息）。 - Planner：在“結構化輸出”模式下生成
PlanJSON。若has_enough_context=true，直接跳轉 Reporter；否則轉到人審。 - Human Feedback（中斷）：向外部發出 “Please Review the Plan.” 的可恢復中斷；等待
[ACCEPTED]或[EDIT_PLAN]開頭的回執。 - Research Team：當被接受后，進入
research_team協作執行；依據首個未完成步驟的step_type，轉給researcher或coder節點，并循環直至步驟完成或回到 Planner 迭代。 - Reporter：按設定的報告風格，組織生成最終報告內容并返回。
3. 核心數據結構
- Plan（
src/prompts/planner_model.py）locale: string：輸出語言；繼承用戶輸入或由 Coordinator 傳入。has_enough_context: boolean：嚴格判定當前是否信息充足。為 true 時可跳過研究直接成稿。thought: string：對用戶需求的復述與規劃思路。title: string：任務標題。steps: Step[]：最多max_step_num個步驟（默認 3）。
- Step
need_search: boolean：是否需要外部檢索/抓取。title: string，description: string：步驟名與需采集/處理的具體數據點。step_type: "research" | "processing"：研究或加工；決定路由至researcher/coder。execution_res?: string：步驟執行產出，由執行節點回填。
4. 關鍵節點實現要點
-
Coordinator（
src/graph/nodes.py）- 使用
get_llm_by_type(AGENT_LLM_MAP["coordinator"])綁定handoff_to_planner工具； - 若工具被調用，則路由至
planner或（在啟用背景檢索時）background_investigator； - 工具參數中的
locale、research_topic會覆蓋當前狀態。
- 使用
-
Background Investigator（可選）
- 依據
SELECTED_SEARCH_ENGINE（Tavily 或其它）執行簡要檢索； - 將結果拼入 Planner 的輸入消息，提高初次規劃質量與召回范圍。
- 依據
-
Planner
- 采用結構化輸出（JSON Mode）；basic 模式直接
with_structured_output(Plan)，其它模式走流式拼接； - 對 JSON 做
repair_json_output + json.loads容錯； - 分支：
has_enough_context=true：校驗為Plan對象，goto=reporter；- 否則：將“原始 JSON 字符串”暫存到
current_plan，goto=human_feedback。
- 采用結構化輸出（JSON Mode）；basic 模式直接
-
Human Feedback（中斷）
- 僅接受以下前綴的回執：
[ACCEPTED]：通過；[EDIT_PLAN]：攜帶修改意見，回到 Planner 迭代；
- 其它值將拋出類型錯誤，避免不明狀態。
- 僅接受以下前綴的回執：
-
Researcher / Coder
- Researcher：
need_search=true的research步驟，提供“檢索工具 + 爬取工具 +（可選）RAG 本地檢索工具”； - Coder：
processing步驟，負責統計、計算、程序化分析與結構化數據產出； - 兩者將執行結果寫回
execution_res，并將觀察結果納入observations供后續步驟使用。
- Researcher：
-
Reporter
- 根據
report_style（如 academic/popular_science）生成成稿； - 添加表格/引用提示，規范輸出格式與引用規范。
- 根據
5. 配置項與默認值
max_plan_iterations：默認 1；超過即直接進入 Reporter，避免無限循環。max_step_num：默認 3；Planner 必須在限定步數內覆蓋關鍵信息面。max_search_results：默認 3；影響檢索結果數量與速度。enable_deep_thinking：默認 false；啟用后 Planner 選用“reasoning”類模型。enable_background_investigation（State 層）：默認 true；可關閉以縮短首輪延遲。AGENT_RECURSION_LIMIT（env）：研究/編碼子代理的遞歸深度，默認 25，非法值自動回落。
6. 容錯與兜底
- JSON 解析失敗：
- 首次失敗：
goto=__end__（防止無效循環）； - 非首次失敗：
goto=reporter（使用已有信息成稿）。
- 首次失敗：
- 規劃超限：當
plan_iterations >= max_plan_iterations，直接goto=reporter。 - 無工具調用：Coordinator 未調用任何工具 → 終止執行（
__end__），寫日志排查提示詞或模型配置。
7. 設計原則與最佳實踐
- 嚴格的“上下文充足性”判定：寧缺毋濫，缺數據則規劃下一步收集；
- 研究/加工解耦：
research僅采集與溯源，不做計算；processing僅做計算與結構化加工，不做外網檢索；
- 逐步累積
observations，在后續步驟與 Reporter 復用； - 對外提供明確的人審接口，確保關鍵節點的質量把關與可控性。
8. 參考 Plan 模板（含 processing）
{"locale": "zh-CN","has_enough_context": false,"thought": "對用戶研究需求的簡要復述與拆解思路","title": "主題名稱","steps": [{"need_search": true,"title": "歷史沿革與核心研發方向","description": "收集公司成立背景、階段性技術演進、關鍵研發里程碑、投入強度。","step_type": "research"},{"need_search": true,"title": "現有技術能力與指標","description": "采集架構方案、團隊構成、專利與測評、典型案例等定量+定性信息。","step_type": "research"},{"need_search": true,"title": "同行對比與趨勢","description": "與同賽道 3–5 家進行橫向對比；收集專家/媒體/投研觀點。","step_type": "research"},{"need_search": false,"title": "指標歸并與結構化輸出","description": "將采集信息做指標口徑統一、表格化對比、評分與結論歸納。","step_type": "processing"}]
}
9. 人審回執格式
- 接受執行（繼續）：
[ACCEPTED] 按當前 Plan 執行。
- 需要修改（回到 Planner）：
[EDIT_PLAN] 請在步驟 3 后新增 1 步 processing：用于指標歸并、橫向表格對比與評分輸出。
10. 與業務落地的建議
- 在
description中顯式列出“首選信息源清單”（官網/企信/專利/測評/投研等）與“指標口徑”； - 結合
resources注入本地資料，強制researcher先用本地檢索工具； - 根據需求切換
report_style（如學術體 vs. 通俗體），確保對外輸出一致性。
。)
)