DeerFlow 多 Agent 协调实战教程 · 目录与导读
从 0 到 1，用伪代码重走一遍「多 agent 框架是怎么搭起来的」。 每一步都不只告诉你「做了什么」，更告诉你「当时有哪几条路、各自的代价、为什么最后走了这条路」。
一、这个教程在讲什么
一句话结论：DeerFlow 的精华不是某个模型、某个 prompt，而是**「一群 agent 怎么协调」这件事被显式地设计成了工程问题**——协调有契约（Plan）、有载体（状态图）、有调度（Supervisor）、有带宽管理（上下文压缩）、有容错（重规划/检查点）。这套东西，比「换更强的模型」更能决定一个 agent 系统能不能真正落地。
我们会一起做一件事：假设你手里只有 LangGraph 的空壳，怎么一步步把一个多 agent 协调系统造出来。全程用伪代码表达，每个关键决策点都展开「思考的分叉」。
二、先厘清一个容易踩的坑：有两个「deer-flow」
网上搜 deer-flow，会搜到两个完全不相干的项目：
| 项目 | 语言/栈 | 是什么 | 本教程是否涉及 |
|---|---|---|---|
| ByteDance / deer-flow | Python + LangGraph/LangChain | 字节开源的 Deep Research / SuperAgent 编排框架 | ✅ 全部讲它 |
| 某个 Java 流式编排引擎 | Java + Spring | 一个带 @JobTask、cron、nodeId 的工作流调度框架 | ❌ 完全无关 |
如果你看到讲 @JobTask、cron 表达式、FlowContext 的 deer-flow 文章，那是 Java 那个，跟我们要讲的 agent 框架没有任何关系。字节的 deer-flow 仓库是 github.com/bytedance/deer-flow，MIT 协议。
三、DeerFlow 有两条线，本教程都覆盖
| 版本 | 定位 | 核心架构 | 对应章节 |
|---|---|---|---|
1.x（main-1.x 分支） | Deep Research 深度研究 | Coordinator → Planner → 研究团队(Researcher/Coder) → Reporter，LangGraph 状态图 | 第 1~9 章 |
2.0（main 分支） | SuperAgent harness 超级智能体编排 | Lead Agent + 动态子 agent + 沙箱 + 记忆 | 第 10 章 |
为什么重点讲 1.x 的协调机制：1.x 的「Planner 出 Plan → Supervisor 派活 → Worker 执行 → Reporter 汇总」是最干净的「多 agent 协调」教学标本——角色边界清晰、协调契约明确、每一条设计决策都能反推出来。2.0 把它泛化成通用 harness，是同一套思想的「去特化」。先把 1.x 吃透，再看 2.0 会非常顺。
四、章节地图
| 章 | 主题 | 核心问题 |
|---|---|---|
| 01 | 为什么需要多 agent | 一个 agent 扛不住吗？上下文窗口这个物理上限怎么破 |
| 02 | 角色的诞生 | 拆成几个角色？每个角色干什么？单一职责 vs 通用 agent |
| 03 | 协调的契约：Plan | agent 之间靠什么「对表」？为什么是结构化计划而非来回聊天 |
| 04 | 状态图：用什么承载协调 | 用 if-else？用消息队列？为什么 DeerFlow 选状态图 |
| 05 | 调度循环：Supervisor 派活 | 谁来分配任务？顺序还是并行？为什么要有 Supervisor |
| 06 | Worker 的内心戏：ReAct | 一个研究员 agent 内部是怎么跑的 |
| 07 | 上下文管理：通信带宽 | agent 之间传什么？怎么防止「传话失真」（附真实 issue） |
| 08 | Human-in-the-Loop | 为什么要把「人」插进协调链路里 |
| 09 | 容错与重规划 | 出错了怎么办？重试该重试什么？ |
| 10 | 从 1.x 到 2.0 | 固定流水线为什么会「不够用」，harness 怎么抽象 |
| 11 | 可复用的协调设计清单 | 把所有决策点收拢成一张表，给你造自己的框架用 |
五、阅读建议
- 按顺序读。每一章都建立在上一章的「为什么」之上，跳着读会丢上下文。
- 伪代码不要扫一眼就过。每个伪代码块都对应一个真实的架构决策，读的时候问自己：这里如果换成我的写法，会出什么问题？
- 每章末尾有「思考题 + 参考答案」。参考答案不是标准答案，是「一种站得住脚的推导」，你完全可以反驳它——反驳本身就是在建立自己的判断。
- 遇到「为什么选这个」的地方，先停下来自己想 30 秒，再看我的推导。这样收获最大。
六、几个贯穿全文的关键约定
- 伪代码语言：用接近 Python 的写法（因为 DeerFlow 是 Python 生态），但你（Go 程序员）完全可以在脑子里自动翻译成 Go。关键不在语法，在数据结构和控制流。
- 「协调」的定义：本教程里，「协调」专指多个 agent 之间如何分工、对表、传递信息、汇总结果，不指单个 agent 内部的推理。
- 结论先行：每章开头给一句结论，后面再展开推导——照你的阅读习惯来。
准备好了吗？我们从最反直觉的一个问题开始：为什么非要多 agent 不可？