LangGraph 源码学习总结 3-单结点图的执行分析

把 LangGraph 的“三步”一次看个够

——从官方文档、示例到源码的完整拆解

一、Pregel 的“三步”模型

官方给出的执行模型如下，关键模型是 Plan、Execution、Update.核心概念有 Actors、Channels

"""Pregel manages the runtime behavior for LangGraph applications.

## Overview

Pregel combines [**actors**](https://en.wikipedia.org/wiki/Actor_model)
and **channels** into a single application.
**Actors** read data from channels and write data to channels.
Pregel organizes the execution of the application into multiple steps,
following the **Pregel Algorithm**/**Bulk Synchronous Parallel** model.

Each step consists of three phases:

- **Plan**: Determine which **actors** to execute in this step. For example,
    in the first step, select the **actors** that subscribe to the special
    **input** channels; in subsequent steps,
    select the **actors** that subscribe to channels updated in the previous step.
- **Execution**: Execute all selected **actors** in parallel,
    until all complete, or one fails, or a timeout is reached. During this
    phase, channel updates are invisible to actors until the next step.
- **Update**: Update the channels with the values written by the **actors**
    in this step.

Repeat until no **actors** are selected for execution, or a maximum number of
steps is reached.

## Actors

An **actor** is a `PregelNode`.
It subscribes to channels, reads data from them, and writes data to them.
It can be thought of as an **actor** in the Pregel algorithm.
`PregelNodes` implement LangChain's
Runnable interface.

## Channels

Channels are used to communicate between actors (`PregelNodes`).
Each channel has a value type, an update type, and an update function – which
takes a sequence of updates and
modifies the stored value. Channels can be used to send data from one chain to
another, or to send data from a chain to itself in a future step. LangGraph
provides a number of built-in channels:

### Basic channels: LastValue and Topic

- `LastValue`: The default channel, stores the last value sent to the channel,
   useful for input and output values, or for sending data from one step to the next
- `Topic`: A configurable PubSub Topic, useful for sending multiple values
   between *actors*, or for accumulating output. Can be configured to deduplicate
   values, and/or to accumulate values over the course of multiple steps.

### Advanced channels: Context and BinaryOperatorAggregate

- `Context`: exposes the value of a context manager, managing its lifecycle.
  Useful for accessing external resources that require setup and/or teardown. eg.
  `client = Context(httpx.Client)`
- `BinaryOperatorAggregate`: stores a persistent value, updated by applying
   a binary operator to the current value and each update
   sent to the channel, useful for computing aggregates over multiple steps. eg.
  `total = BinaryOperatorAggregate(int, operator.add)`

LangGraph 把一次图计算拆成无限循环的三步，直到没有任务可跑或达到步数上限：

1. Plan（选节点）
   看哪些通道的值在上轮被改过，把订阅这些通道的节点挑出来。
2. Execution（跑节点）
   并发执行被选中的节点；节点读通道、算结果、把“写请求”攒进自己的 writes 列表，但此时并不真正写回通道。
3. Update（落数据）
   等本轮所有节点跑完，一次性把 writes 里的 (channel, value) 写进通道，并更新 checkpoint 版本号。

下一轮再拿新的通道版本重新做 Plan，如此往复。

二、示例验证——单节点图

代码只有 11 行，却完整走了一遍三步：

from langgraph.channels import EphemeralValue
from langgraph.pregel import Pregel, Channel

node1 = (
    Channel.subscribe_to("a")   # 订阅通道 a
    | (lambda x: x + x)         # 业务逻辑
    | Channel.write_to("b")     # 写通道 b
)
app = Pregel(
    nodes={"node1": node1},
    channels={"a": EphemeralValue(str), "b": EphemeralValue(str)},
    input_channels=["a"],
    output_channels=["b"],
)
print(app.invoke({"a": "foo"}))     # → {'b': 'foofoo'}

Plan：首轮只有 a 被外部输入更新 → 选中 node1。
Execution：node1 算出 "foofoo"，把 ("b", "foofoo") 塞进自己的 writes。
Update：apply_writes 把 writes 真正写进通道 b，checkpoint 版本号刷新。
下一轮 Plan 发现没有任何通道再被更新，循环结束，返回 {'b': 'foofoo'}。

三、源码级定位

1. Plan
   .venv/lib/python3.12/site-packages/langgraph/pregel/algo.py
prepare_next_tasks(...)

   • 先处理上轮残留的 pending_sends（PUSH 任务）
   • 再根据 updated_channels + trigger_to_nodes 快速圈出本轮被触发的节点（PULL 任务）

2. Execution
   .venv/lib/python3.12/site-packages/langgraph/pregel/runner.py
PregelRunner.tick(...)

   • 并发跑任务，回调 commit(task, exc) 把每个任务产生的原始 writes 缓存起来
   • 本身不碰通道，只负责“跑完并收集写请求”

3. Update
   仍在 algo.py —— apply_writes(checkpoint, channels, tasks, None)

   • 由 SyncPregelLoop / AsyncPregelLoop 在 下一轮开头 调用
   • 一次性把所有 writes 应用到通道，更新版本号，完成真正的“通道更新”

四、总结

官方文档、示例、源码三者互相印证：
Plan 决定谁跑，Execution 只算不写，Update 集中落盘 ，最终借鉴Pregel、BSP模型实现图的额执行。