A3 · LangGraph 状态图、持久化与 HITL
掌握确定性 Workflow、显式状态管理，以及跨进程跨重启的 Checkpoint 与人工中断
本模块产出：langgraph-adapter、商品上架状态图、Approval Center · 对应总课表：第 10–11 周
原程序员基础版内容
2026-07-21 起整体迁移程序员进阶版，程序员基础版不再教授。学习目标与验收标准与修订前完全一致，只是不再属于程序员基础版毕业要求。
学前自测
1. 你已经用 Mastra Workflow 做过商品上架流程。显式状态图相比它多了什么？
多的是状态本身成为一等公民：State 有 Schema、有 Reducer 决定怎么合并更新、每个节点的输入输出都能独立测试、整张图可以可视化。代价是样板代码更多。什么时候值得付这个代价，是这个模块要建立的判断力。
2. Reducer 是什么？为什么状态更新需要它而不能直接赋值？
Reducer 定义某个状态字段收到新值时怎么合并。需要它是因为并行分支会同时更新同一个字段，直接赋值会互相覆盖。比如两个并行节点各自往 messages 追加一条，Reducer 定义成追加就都保留，定义成覆盖就丢一条。并行场景下这是正确性问题，不是风格问题。
3. Checkpoint 和你在程序员基础版第 7 周做的 Mastra Snapshot，本质区别在哪？
本质相同，都是把执行状态持久化以支持恢复。差别在粒度和显式程度：Checkpointer 是每个超级步之后自动落盘，且支持 time travel（回到任意历史 checkpoint 重新走）。time travel 是 Snapshot 通常不提供的能力，它让调试和「改一个中间状态重跑」成为可能。
4. Checkpoint Schema 升级了，老的 checkpoint 还能恢复吗？
不做迁移就不能，而且失败方式很难看：反序列化出一个字段缺失的状态，然后在某个节点里报 undefined 错误。生产系统必须有 Checkpoint Schema Migration，和数据库迁移同等对待。这是这个模块里最容易被忽略、上线后最疼的一条。
第一部分：LangGraph 状态图
学习目标
掌握确定性 Workflow 和显式状态管理。
课程内容
- State
- Reducer
- Node
- Edge
- Conditional Edge
- Parallel Branch
- Loop
- Subgraph
- Input / Output Schema
- Error Node
- Retry Node
- Interrupt
- Stream
- Graph Visualization
状态图与 Checkpoint
实施任务
实现日本电商商品上架 Workflow：
抓取商品
→ 结构化
→ 市场分析
→ 竞品检索
→ 利润计算
→ 定价建议
→ 日语内容
→ 合规检查
→ 人工审批
→ 创建上架草稿验收标准
- 每个节点有强类型输入输出
- 节点可独立测试
- 支持条件分支和并行
- 中间状态可查看
- 失败节点可单独重试
第二部分：持久化与 HITL
学习目标
让 Workflow 可跨进程、跨重启运行。
课程内容
- Checkpointer
- Thread
- Checkpoint
- Resume
- Interrupt
- Approval
- Rejection
- Compensation
- Time Travel
- Replay
- Idempotency
- Durable Execution
- Timeout
- Dead Letter
- Side-effect Node 的幂等与两阶段提交
- Checkpoint Schema Migration
- Replay / fork 与统一 Session Event 的映射
实施任务
- 高风险工具前暂停
- Web Console 审批
- 审批后从原节点恢复
- 服务重启后继续执行
- 支持拒绝和修改后重试
验收标准
- 审批请求有超时时间
- 审批人和操作人可审计
- 服务重启不丢任务
- 重放不会产生重复副作用
- Checkpoint 升级、损坏和并发恢复有故障注入测试
- LangGraph 事件可转换为统一
AgentEvent与 OTel Span
动手挑战
做一次 time travel 调试，然后故意把 checkpoint 弄坏。
第一部分：time travel。让上架流程跑到定价节点，记下 checkpoint id。然后回到市场分析之后的那个 checkpoint，手工把利润率改成一个极端值，从那里重跑。观察后续节点的行为，验证：改中间状态重跑，比从头跑一遍快多少、省多少 Token？
第二部分：破坏性测试。三种坏法各试一次：
- 给 State 加一个必填字段，然后恢复一个旧 checkpoint
- 手工把 checkpoint 记录截断一半
- 两个进程同时恢复同一个 thread
三种情况你的系统分别是崩溃、静默出错、还是明确报错？静默出错是最坏的结果，因为它会带着错误状态继续跑完整个流程，产生看起来正常实际错误的业务结果。把三种都改成明确失败，这个模块的生产级要求就达到了。
Agent OS 里程碑
完成 langgraph-adapter 与 Approval Center。
学后自测
1. 你的上架流程里，哪些节点有副作用？两阶段提交怎么做的？
有副作用的通常是创建草稿、发通知、写外部系统。两阶段做法是：第一阶段只做可回滚的准备（生成草稿内容但不提交），checkpoint 落盘后第二阶段才真正提交，并带幂等键。不这么做的话，「副作用已执行但 checkpoint 未落盘」这个窗口一崩溃就会重复执行。
2. 审批超时了应该怎么处理？三种策略各适合什么场景？
自动拒绝（适合高风险操作，宁可不做）、自动通过（只适合低风险且有事后追溯的场景，慎用）、升级给上级（适合有明确责任链的组织）。选哪个是业务决策不是技术决策，但你必须让它可配置，并且审计日志要记录是人批的还是超时策略批的。
3. 什么情况下你会建议团队不要用 LangGraph，改用普通代码？
流程步骤固定、没有分支、不需要恢复、不需要人工中断的时候。这种场景下状态图带来的样板代码是纯负担。能主动说出框架的不适用场景，比会用框架更能证明判断力。
本模块作业
packages/adapter-langgraph/扩展：完整状态图 + Checkpointer + 事件映射- 商品上架状态图，每个节点可独立测试
- Approval Center：审批、拒绝、修改后重试、超时策略
- 三类破坏性测试：Schema 升级、checkpoint 损坏、并发恢复
docs/langgraph-vs-mastra.md：与程序员基础版第 7 周 Mastra Workflow 的对照报告
面试考点
这个模块对应面试里的状态编排与可靠性考察，在有复杂业务流程的团队权重很高。
- 「LangGraph 和 Mastra Workflow 你选哪个？」：拿对照报告答。核心差异是显式状态加 time travel 对比更轻的样板代码。给出你的选择场景边界，不要说哪个更好。
- 「并行分支同时改一个字段会怎样？」：答 Reducer。这题是 LangGraph 的经典考点，答不上来说明只跑过教程没做过并行。
- 「服务重启后流程怎么继续？」：答 Checkpointer 加 thread id 加幂等。重点讲副作用节点的两阶段提交，这是把答案从中级拉到 Senior 的地方。
- 「你踩过 checkpoint 的什么坑？」：讲 Schema 迁移。绝大多数候选人没经历过这个，能讲清楚会被记住。
- 「人工审批怎么设计？」：答 interrupt 加持久化加超时策略，并强调超时策略是业务决策、审计要区分人批和自动批。
复习与延伸
官方文档
本仓库对应源码
packages/adapter-langgraph/src/graph.ts：StateGraph 适配参考实现packages/adapter-langgraph/src/graph.test.ts：节点独立测试的写法