DeerFlow 阶段课 · 导读

基线：deer-flow-2.1，tag v2.1.0，提交 345f08be00c8a9495079b732a39b46aa9af1584e。 路径相对 $DEERFLOW_SRC。 已有 00～03 是总览；本卷是源码深入课，按阶段 0～9 逐层拆开。

为什么要有阶段卷

总览回答“系统由什么组成”，阶段卷回答“下一步代码怎样走、事实归谁、失败后从哪里恢复”。两者不是替代关系：

读法	适合解决的问题
overview.md	第一次知道目录、对象和边界
run-lifecycle.md	先获得完整生命周期直觉
core-mechanisms.md、engineering.md	按主题补齐上下文、工具、模型和工程
本卷阶段 0～9	沿源码主链逐段建立可验证的因果关系

一条贯穿全卷的大脉络

阶段0  认识目录、配置与信任边界
  ↓
阶段1  HTTP 接单 → pending → running → terminal
  ↓
阶段2  组装 LangGraph：模型 + 工具 + middleware
  ↓
阶段3  决定模型这一轮看见什么
  ↓
阶段4  决定模型能做什么，以及在哪儿做
  ↓
阶段5  决定调用哪个模型、用哪套凭据与推理参数
  ↓
阶段6  记录、恢复、审计并证明交付
  ↓
阶段7  把同一引擎接到多渠道、多 Agent、扩展与调度
  ↓
阶段8  用测试、边界和排障守住前七层
  ↓
阶段9  自己完成一个端到端改造

一句话主线：

start_run → pending → try_start/running → make_lead_agent → astream → journal/checkpoint → delivery receipt → terminal。

每篇的固定读法

每篇都尽量回答四个问题：

1. 这一步拥有什么事实？
2. 谁有资格修改这个事实？
3. 失败时哪一个 journal、checkpoint 或 receipt 能证明做到哪一步？
4. 哪些已经发生的副作用绝不能重做？

阶段地图

阶段	主题	进入前应知道	完成后应能做
0	环境与源码地图	Python/Node 基础	解释 harness/app 边界与端口职责
1	入口与 Run 生命周期	HTTP、异步任务	画出 pending→running→terminal
2	Agent 装配与 LangGraph 循环	LangGraph 基本概念	说出 middleware 的装配顺序
3	上下文与记忆	token 与消息格式	区分 prompt、checkpoint、memory
4	工具与 Sandbox	工具调用协议	追踪一次工具执行到隔离环境
5	模型接入与 Provider 适配	provider API	解释白名单、推理档位与适配器
6	持久化与恢复	状态机、事务	从 journal 判断该补哪一步
7	扩展渠道与多 Agent	插件/消息渠道	复用同一 Run 接单口扩展入口
8	工程化与故障排查	测试、日志	用测试和证据定位故障层
9	毕业设计	前九阶段	完成一个可审计的源码改造

建议节奏

• 第一遍只读“源码主线”和“可观察链路”，建立因果。
• 第二遍做每篇实验，至少观察一个状态、一个事件或一个失败分支。
• 第三遍回答自测题，并用源码坐标验证，而不是背结论。
• 每完成一个阶段，在纸上补一句：“这一步的事实源是 ____，失败恢复点是 ____。”

全卷完成标准

你应当能够不看总览，独立解释：

• 为什么 start_run() 是唯一接单口，try_start() 又为什么必须再做一次状态迁移；
• Agent 装配时哪些东西属于“配置”，哪些东西只能由服务端注入；
• 上下文、checkpoint、journal、memory 四种“记住”的区别；
• 工具为什么必须穿过 middleware 和 sandbox，而不是直接调用宿主 shell；
• Run 中断、租约丢失、交付失败和进程重启分别由哪一层收尾；
• 渠道、定时任务和子 Agent 为什么共享同一套 Run 语义。

阶段 0 开始时不要急着读 worker 的每个分支。先建立“谁拥有事实”的坐标系。