LangGraph 设计与实现

深入 LangGraph 的源码与架构。

你按文档写完一个图，它跑起来了。然后问题开始出现：两个并行节点同时写同一个字段，最后留下的是哪一个？在人工审批处中断，几小时后恢复，状态从哪里捞回来？子图里的节点和父图重名会怎样？为什么明明加了循环，它跑到第 25 步就停了？

这些答案都不在文档里，在 Channel、Pregel 超步和 Checkpoint 三维寻址里。本专栏以 LangGraph 1.1.6 源码为解剖对象，把这三样东西拆开。

flowchart TB
  SG[StateGraph<br/>add_node · add_edge · 条件边] -->|compile| CG[CompiledStateGraph]
  CG --> P
  subgraph P [Pregel 执行引擎 · 一个超步]
    direction LR
    T1[tick 计划<br/>prepare_next_tasks] --> T2[执行任务]
    T2 --> T3[apply_writes 更新<br/>Reducer 合并]
    T3 --> T4[after_tick<br/>版本追踪]
  end
  P <--> CH[Channels<br/>状态的真正住处]
  P --> CK[Checkpoint<br/>三维寻址 · 时间旅行]
  CK --> HIL[interrupt<br/>人机协作 / 恢复]
  P -.动态并行.-> SEND[Send]
  P -.命名空间隔离.-> SUB[子图]

为什么要理解 Pregel。 LangGraph 的执行模型不是"依次调用节点"，而是借自 Google Pregel 的超步（superstep）模型：一个超步里所有任务并行跑，跑完统一 apply_writes。上面那些让人困惑的行为——并发写谁赢、循环为什么会停、恢复时从哪继续——全都是这个模型的直接推论。不理解它，你只能靠试。

读完你能做到什么

预测并发写的结果。 Channel 是什么、Reducer 怎么合并、apply_writes 的更新算法与版本追踪机制（第4章 Channel、第6章 Pregel 引擎）。
看懂一次 graph.invoke() 的完整旅程。 四层架构、Channel 的读写路径、PregelLoop 这个状态机的每一步，以及 max_steps 与 recursion_limit 两个停止条件的区别（第2章架构总览、第7章任务调度）。
把状态可靠地存下来、再捞回去。 Checkpoint 的数据结构与三维寻址、序列化体系、几种持久化模式，以及生产环境里真正要注意的地方（第8章 Checkpoint）。
做出能中断、能恢复、能改主意的人机协作流程。 interrupt() 到底做了什么、interrupt_before/after 的差别、用 Command 恢复并改写状态（第9章中断、第10章 Command）。
组织大图。 子图嵌套与命名空间隔离、用 Send 做动态扇出（数量在运行时才知道的并行）（第11章子图、第12章 Send）。
调试与观测。 几种流式模式各自吐什么、Runtime 与 Store 提供了哪些可挂载点（第13章流式输出、第14章 Runtime、第15章 Store）。

这个专栏的讲法

从 API 讲到算法。 add_node 有五重重载、compile() 到底把 StateGraph 变成了什么、prepare_next_tasks 的任务准备算法长什么样 —— 一路从你每天写的那几行，追到引擎内部真正执行的那几行。

每章带「设计决策分析」与「常见陷阱」。 图构建那章直接列出常见误解与最佳实践，Checkpoint 那章写明生产里的注意事项。这些是文档不会写、而你迟早会踩的部分。

最后落回工程。 预构建组件怎么用、多 Agent 编排有哪些成型模式（第16章预构建、第17章多 Agent 模式、第18章设计模式）。

适合谁读

已经在用 LangGraph、但遇到"行为不符合直觉"的开发者。 这个专栏就是为解释那些行为写的。
从 LangChain 进阶到复杂工作流的工程师。 链是线性的，图是有状态的，两者的心智模型不同。
多 Agent 系统的架构师。 子图、Send、Checkpoint 是搭多 Agent 的三块地基。

不适合：只想照着教程搭一个 demo 的读者 —— 官方文档更快。这里讲的是它内部为什么这样运作。

源码版本

本专栏基于 LangGraph 1.1.6 和 langgraph-checkpoint 4.0.1 源码分析：

仓库	版本	Git Commit
langchain-ai/langgraph	1.1.6	`c3ba590`

git clone https://github.com/langchain-ai/langgraph.git
cd langgraph && git checkout 1.1.6

核心代码在 libs/langgraph/ 和 libs/checkpoint/ 目录下。原先这里只给了 git clone 而没有 checkout——读者拿到的是 HEAD，和正文引用的行号对不上，这是一次真实的漏写。

版权声明

欢迎分享本专栏的链接。引用少量内容用于评论、教学或研究时，请署名 杨艺韬 并附上原文链接。

LangGraph 设计与实现

读完你能做到什么

这个专栏的讲法

适合谁读

目录

第一部分：开篇

第二部分：图定义与状态

第三部分：执行引擎

第四部分：持久化与控制流

第五部分：高级特性

第六部分：运行时与集成

第七部分：总结

源码版本

版权声明