Langgraph on 男娘教主

从 Session、Context Compaction、Tracer 理解 Agent Harness 工程化

Sun, 20 Sep 2026 07:52:49 +0800

W7-D5：从 Session、Context Compaction、Tracer 理解 Agent Harness 工程化

这一天开始，我感觉自己学的东西开始从“LangGraph API”慢慢变成了真正的工程代码。

前面学 LangGraph 的时候，我更关注：

一个节点怎么写？一个 State 怎么传？一个 Send 怎么并发？一个 interrupt 怎么暂停？

但 Agent 真正跑起来以后，很快会遇到另一类问题：

程序重启了，之前的对话怎么办？
对话越来越长，模型上下文装不下怎么办？
Agent 明明执行了很多步骤，但出了问题以后根本不知道哪里慢、哪里炸？
这些能力如果都塞进 Agent 主逻辑，代码最后会变成什么样？

所以 Day5 做的，其实不是“再学三个 Python 类”。

而是在学习一个更重要的问题：

怎么把一个 Agent 从“能跑”，逐渐变成“可以长期运行、可以维护、可以排查问题”的系统。

Day5 的三个模块分别是：

模块	类比	解决的问题
Session Store	游戏存档	重启以后状态不丢
Context Compaction	行李超重打包	长任务不会因为上下文越来越大而爆掉
Tracer	外卖配送轨迹	出问题以后知道谁调用了谁、花了多久、哪里失败

而整个 Harness 的整体设计里，它们分别属于第 3、4、5 个模块。

一、先不要看代码：我先建立整个系统的骨架

先把它画出来。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


 Agent / LangGraph
 │
 ┌────────────────┼────────────────┐
 │ │ │
 ▼ ▼ ▼
 Session Store Compaction Tracer
 存全量历史 生成模型视图 记录执行过程
 │ │ │
 ▼ ▼ ▼
 JSONL / 内存 历史摘要 span
 │ │ │
 └────────────────┼────────────────┘
 ▼
 LLM / Agent 执行

这里有一个非常重要的思想：

这三个模块并不是 Agent 的“业务逻辑”

例如：

1
2
3
4
5


Agent：
 分析舆情
 调用搜索工具
 判断结果
 生成回答

这是业务逻辑。

而：

1
2
3
4
5
6
7
8


Session：
 把执行状态存下来

Compaction：
 控制发给模型的上下文

Tracer：
 记录执行过程

属于基础设施能力。

也就是：

Agent 负责“做什么”，Harness 负责“让它能够稳定地做”。

这个思路非常重要。

因为如果这些东西全部写进 Agent：

1
2
3
4
5
6
7
8
9


def agent():
 # 先读历史
 # 判断是不是太长
 # 如果太长就压缩
 # 调模型
 # 记录耗时
 # 记录异常
 # 把状态保存
 # ...

最后 Agent 会越来越胖。

以后想：

换存储方式
换压缩策略
换日志系统
删除 Trace
增加监控

都会直接碰业务代码。

这就是工程化最核心的问题之一：

把容易变化的基础设施能力，从核心业务逻辑里拆出去。

二、第一个模块：Session Store

2.1 Session 到底是什么？

先不要管 Python。

假设你正在和 Agent 聊天。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


用户：
 帮我分析今天的舆情

Agent：
 好

用户：
 再按照昨天那个格式整理

Agent：
 好，我记得

这里 Agent 为什么知道“昨天那个格式”？

因为它需要历史状态。

如果程序运行到一半：

1
2


进程退出
服务器重启

内存中的：

1

messages = [...]

没了。

那么下一次启动：

1
2
3
4
5


用户：
 按照昨天的格式整理

Agent：
 什么格式？

这就是 Session Store 要解决的问题。

可以直接把它理解成：

游戏存档点。

代码注释本身就是这么定义的：打到一半关机，下次读档还在原来的位置。

三、SessionStore 的第一个工程问题：存在哪里？

代码：

1
2
3
4
5
6


class SessionStore:

 def __init__(self, path=None):
 self.path = path
 self.bad_lines = 0
 self._mem = {}

这里最重要的不是 Python 语法。

而是这个设计：

1

path=None

和：

1

path="session.jsonl"

代表两种后端。

内存模式

1

SessionStore(None)

数据：

1

Python 内存

程序一退出：

1

数据没了

适合：

1
2
3


测试
临时任务
单次运行

文件模式

1

SessionStore("session.jsonl")

数据：

1

文件

程序重启：

1

还能读回来

这就是第一个非常典型的工程化思维：

调用方只关心“我能不能保存”，不应该关心你底层到底是内存、文件还是数据库。

以后：

1
2
3
4
5


JSONL
 ↓
SQLite
 ↓
PostgreSQL

如果上层接口没变：

1
2
3


session.append(...)
session.load(...)
session.messages(...)

调用方就不用跟着一起重写。

这就是：

抽象接口，隔离实现。

四、JSONL 是什么？

这一段第一次看到的时候容易懵。

JSON：

1
2
3
4


{
 "thread_id": "123",
 "messages": []
}

JSONL 就是：

一行一个 JSON。

例如：

1
2
3
4


{"thread_id":"123","seq":0,"messages":[...]}
{"thread_id":"123","seq":1,"messages":[...]}
{"thread_id":"123","seq":2,"messages":[...]}
{"thread_id":"456","seq":0,"messages":[...]}

它有一个特点：

特别适合追加。

因为新增一轮消息时，不需要重新把整个文件改一遍，只需要：

1

在文件末尾再写一行

这也就对应代码里的：

1

with open(self.path, "a", encoding="utf-8") as f:

这里的：

1

"a"

就是 append：

追加。

五、为什么这里选择 append-only？

append-only 的意思就是：

历史记录只增加，不修改。

例如：

1
2
3
4


第1轮
第2轮
第3轮
第4轮

不会写成：

1
2
3


第1轮被修改
第2轮被修改
第3轮被修改

而是：

1
2
3
4


第1轮
第2轮
第3轮
第4轮

一直往后追加。

为什么？

因为它对崩溃更友好。

假设正在写：

1

第4轮

程序突然：

1

断电

最坏情况：

1

第4轮坏了

但是：

1
2
3


第1轮
第2轮
第3轮

还在。

而如果你每次都：

1

把整个历史文件重新写一遍

那么中途崩溃，就可能直接把整个文件破坏。

所以这个设计本质上是在做：

把“修改旧数据”的风险，变成“追加新数据”的风险。

这是非常典型的工程化取舍。

六、SessionStore 怎么恢复数据？

看这个函数：

1

def _read_all(self):

它做的事情其实非常简单：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


文件
 ↓
一行一行读取
 ↓
JSON 解析
 ↓
取 thread_id
 ↓
按照 thread_id 分组
 ↓
得到：

{
 "thread1": [记录1, 记录2],
 "thread2": [记录1, 记录2]
}

核心代码：

1

out.setdefault(tid, []).append(rec)

这里的：

1

setdefault

可以先理解成：

如果这个 key 没有，就先创建一个空列表。

例如第一次看到：

1

tid = "A"

相当于：

1

out["A"] = []

然后：

1

append(rec)

所以最终：

1
2
3
4


{
 "A": [rec1, rec2, rec3],
 "B": [rec1, rec2]
}

七、为什么读取坏行不直接报错？

这里是一个很重要的工程思维。

代码：

1
2
3
4
5
6


try:
 rec = json.loads(line)
 tid = rec["thread_id"]
except (json.JSONDecodeError, KeyError, TypeError):
 self.bad_lines += 1
 continue

如果文件中间有一行：

1

{"thread_id":"123"

它不是完整 JSON。

普通程序可能：

1
2
3


报错
→ 整个 Session 不能读
→ Agent 整个挂掉

但这里的设计是：

1
2
3
4
5
6
7


坏这一行
 ↓
记录 bad_lines
 ↓
跳过
 ↓
继续读取后面的数据

也就是：

局部损坏，不要扩大成整个系统不可用。

这是非常典型的容错设计。

八、append 里还有一个容易被忽略的东西：fsync

代码：

1
2


f.flush()
os.fsync(f.fileno())

第一次看到特别容易觉得：

不就是写文件吗？

其实这里是在解决：

“我写成功了”和“数据真的已经落到持久化介质”是不是一回事？

简单理解：

1
2
3
4
5
6
7


Python
 ↓
操作系统缓冲区
 ↓
文件系统
 ↓
存储设备

flush() 更接近：

把 Python/文件对象里的缓冲往操作系统推。

fsync() 则是：

请求操作系统把这个文件的数据同步到持久化存储。

所以这里的思想是：

宁愿每次写慢一点，也希望 Session 的持久化可靠性更高。

代码注释也明确写了：这是以每次写更慢为代价来换取更强的持久化保障。

九、为什么要保存 `ts / thread_id / seq / messages / meta`？

最终写入的结构：

1
2
3
4
5
6
7


rec = {
 "ts": time.time(),
 "thread_id": thread_id,
 "seq": self._count(thread_id),
 "messages": list(messages),
 "meta": dict(meta or {}),
}

可以把它理解成：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


ts
↓
什么时候存的

thread_id
↓
属于哪个会话

seq
↓
这个会话的第几次快照

messages
↓
真正的数据

meta
↓
额外信息

这里值得注意：

1

messages = list(messages)

不是直接把原列表对象塞进去，而是复制一层。

同理：

1

dict(meta or {})

也复制了一层。

这背后的工程意图可以理解为：

Session 保存的是“这一时刻的快照”，而不是把调用方未来还会修改的容器直接绑进来。

十、Session Store 的公开 API 为什么这么设计？

代码最后有：

1
2
3
4
5
6


append()
load()
latest()
messages()
list_threads()
delete()

可以画成：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


append
 ↓
保存一份快照

load
 ↓
拿到这个会话全部快照

latest
 ↓
只拿最后一份

messages
 ↓
只拿最后一份里的 messages

list_threads
 ↓
有哪些会话

delete
 ↓
删除一个会话

这里有一个很典型的代码组织方式：

底层能力少，上层 API 组合。

比如：

1
2
3


def latest(self, thread_id):
 rs = self.load(thread_id)
 return rs[-1] if rs else None

它没有重新实现“怎么读文件”。

而是直接使用：

1

load()

所以：

1
2
3
4
5


load()
 ↓
latest()
 ↓
messages()

是一层一层建立起来的。

这就是为什么代码会比“每个函数自己重新读取文件”更容易维护。

十一、delete 为什么这么麻烦？

前面说：

append-only。

那为什么删除还要重新写文件？

因为你不能从一个文本文件中间：

1

把 thread-A 的几行直接擦掉

所以做法变成：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


原文件
 ↓
读取全部数据
 ↓
删掉指定 thread
 ↓
写到临时文件
 ↓
os.replace()
 ↓
替换原文件

代码：

1
2
3
4
5
6


tmp = self.path + ".tmp"

with open(tmp, "w", encoding="utf-8") as f:
 ...

os.replace(tmp, self.path)

重点不是 .tmp。

重点是：

1

os.replace()

它的目标是让外部尽量只看到两种状态：

1

旧文件

或者：

1

新文件

而不是：

1

写到一半的破文件

所以这里体现的是另一个工程化关键词：

原子性。

十二、SessionStore 的整体流程

把这一整个类压缩成一张图：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


 SessionStore
 │
 ┌───────────┴───────────┐
 │ │
 path=None path=x.jsonl
 │ │
 _mem 文件
 │ │
 └───────────┬───────────┘
 │
 append()
 │
 ▼
 快照 rec
 │
 ┌─────────┼─────────┐
 ▼ ▼ ▼
 ts thread_id messages
 │ │ │
 └─────────┼─────────┘
 ▼
 JSONL
 │
 ▼
 load()
 │
 ▼
 latest()
 │
 ▼
 messages()

现在再看 SessionStore，就不容易迷路了。

十三、第二个模块：Context Compaction

Session 有了以后，新的问题出现了。

假设 Agent 执行了：

1
2
3
4
5


第1轮
第2轮
第3轮
...
第100轮

Session 说：

没问题，我全部给你保存。

但是模型说：

等一下，我上下文不是无限的。

于是：

1
2
3


Session Store
 ↓
保存了全部历史

并不等于：

1

LLM 每次都要看到全部历史

这就是 Context Compaction。

十四、Compaction 到底在干什么？

代码注释用了一个很好理解的比喻：

1

行李箱超重

假设：

1

你有 40 件衣服

但是飞机：

1

只允许带 10 件

最粗暴的方法：

1

直接扔掉 30 件

问题：

你以后可能还需要那 30 件。

另一种方法：

1
2
3
4
5
6


写一张清单：

5件外套
3件衬衫
2件裤子
...

然后：

1
2
3


只带最近最重要的东西
+
一张早期历史摘要

这就是压缩。

代码文件也明确把它定义成：

压缩是“投影”，不是“销毁”。原始消息仍然保存在 SessionStore 中。

十五、这里有一个特别重要的工程决策

问题：

压缩后的消息，要不要直接覆盖 Session？

答案：

不要。

采用：

1
2
3


存全量
+
读时压缩

也就是：

1
2
3
4
5
6
7


Session
 ↓
原始历史
 ↓
Compactor
 ↓
给 LLM 的历史视图

而不是：

1
2
3
4
5


Session
 ↓
压缩
 ↓
保存压缩版

为什么？

因为：

1
2
3
4
5
6
7
8


今天：
max_messages = 20

明天：
max_messages = 10

后天：
max_messages = 50

如果原始数据没了：

1

20 → 10

以后就回不来了。

如果原始数据一直保存：

1
2
3
4
5


原始历史
 ↓
不同 Compaction 策略
 ↓
不同模型视图

随时可以重新计算。

这其实就是一个非常重要的工程模式：

原始数据和派生数据分开。

可以把它理解成：

1
2
3
4
5
6
7


Source of Truth
 ↓
 原始历史

Projection
 ↓
 当前需要的视图

这也是这三个文件里非常重要的一条设计思想。

十六、`needs_compaction()` 为什么这么简单？

代码：

1
2


def needs_compaction(self, messages):
 return len(messages) > self.max_messages

现在我们只按：

1

消息条数

判断。

比如：

1

max_messages = 20

那么：

1
2


20 条 → 不压
21 条 → 压

但是这里也留下了一个非常重要的工程问题：

消息条数 ≠ Token 数。

例如：

1
2


消息1：
“好”

只有很少内容。

但另一条：

1
2


消息2：
10000 字符的大段代码

依然只算：

1

1 条消息

所以以后更真实的生产设计，触发条件可能应该是：

1
2
3
4
5


消息条数
+
Token 数
+
工具结果大小

这里代码自己的注释其实也已经意识到这个问题。

这就是一个非常好的工程学习方式：

不是看到现有代码就结束，而是继续问：这个设计在哪种情况下会失效？

十七、为什么 `maybe_compact()` 不直接返回原消息？

代码：

1
2


if not self.needs_compaction(messages):
 return None

这一点特别值得学。

很多初学者会写：

1
2


if 不需要压缩:
 return messages

但这里选择：

1

return None

为什么？

因为调用方可以明确区分：

1
2
3
4
5


None
→ 没有发生压缩

list
→ 真的产生了新的压缩视图

这其实是在设计一个更清晰的函数契约：

1
2
3
4
5


返回 None：
 没变化

返回 list：
 有新结果

这比：

1

无论有没有压缩都返回一个 list

更容易让上层判断发生了什么。

十八、system 消息为什么单独拿出来？

代码：

1
2
3
4


head, body = [], list(messages)

if self.keep_system and body and _role(body[0]) == "system":
 head, body = [body[0]], body[1:]

这里是在做：

1
2
3
4
5
6
7


system
 ↓
单独保存

其他消息
 ↓
参与压缩

因为 system 通常承担：

1
2
3
4
5


角色设定
系统约束
行为规则
工具规则
输出格式

如果把它当普通历史消息一起删掉，整个 Agent 的行为边界可能变化。

所以工程上经常会看到：

1
2
3
4


系统级数据
用户历史
工具历史
当前上下文

分层处理。

十九、整个压缩核心其实就是这几行

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


cut = max(0, len(body) - self.keep_recent)

cut = _safe_cut(body, cut)

old, recent = body[:cut], body[cut:]

summary = self._summarize(old, summarize)

return (
 head
 + [{"role": "system", "content": f"[历史摘要] {summary}"}]
 + recent
)

翻译成人话：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


先算：

我准备留下最近多少条？

↓

剩下的是旧历史

↓

检查切分位置安全不安全

↓

旧历史做摘要

↓

最终：

system
+
历史摘要
+
最近 K 条

可以画成：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


原始消息

system
1
2
3
4
5
6
7
8
9
10
11
12

 ↓

 cut
 │
 ▼

system | old old old old | recent recent

 ↓

system | summary | recent recent

二十、这里出现了一个真正的坑：tool 消息不能随便切

这是这份代码里最值得我记住的一点之一。

Agent 的消息不只是：

1
2


user
assistant

还可能有：

1
2
3


assistant 发起 tool call
 ↓
tool 返回结果

它们实际上是一个逻辑整体。

例如：

1
2
3
4
5


assistant:
 我要调用 search

tool:
 search 返回结果

如果你压缩的时候变成：

1
2


tool:
 search 返回结果

但是：

1

assistant 发起调用

被删掉了。

那模型拿到的就是一个：

孤儿 tool 结果。

所以：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


def _safe_cut(messages, cut):
 cut = max(0, min(cut, len(messages)))

 while (
 cut > 0
 and cut < len(messages)
 and _is_tool_result(messages[cut])
 ):
 cut -= 1

 return cut

它的思想非常简单：

如果切点正好落在 tool 结果上，就往前退。

也就是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


准备在这里切：

assistant(tool_calls)
tool(result)
↑
切点

不安全

↓

往前退

这就是工程化和“只是会写列表切片”的区别。

普通程序员可能想：

1

messages[-6:]

工程代码会继续问：

这样切有没有违反上层协议？

这就是非常重要的思维。

二十一、`_summarize()` 为什么接受一个 `summarize` 参数？

代码：

1
2
3


def _summarize(self, old, summarize):
 if summarize is not None:
 return summarize(old)

这里其实是在做：

依赖注入。

意思是：

1
2
3
4
5


Compactor 不负责决定“到底用哪个 LLM”。

它只规定：

“你给我一个 summarize 函数，我调用它。”

所以以后可以传：

1

summarize = my_llm_summarizer

也可以：

1

summarize = test_summarizer

或者：

1

summarize = mock_summarizer

这样：

1

Compactor

不需要知道：

1
2
3
4
5


OpenAI
Claude
本地模型
LangChain
LangGraph

都是什么。

这就是：

让模块依赖“接口/能力”，而不是依赖具体实现。

二十二、为什么默认摘要不是 LLM？

代码里面还提供了一个无 LLM 的版本：

1
2
3
4
5


roles = {}

for m in old:
 r = _role(m)
 roles[r] = roles.get(r, 0) + 1

最后得到类似：

1
2


已折叠 16 条早期消息
(assistantx8, userx8)

这其实是一个很好的工程设计。

为什么？

因为：

1

核心逻辑

和：

1

真正调用 LLM 的能力

被分开了。

这样测试的时候：

1
2
3


不用 API
不用网络
不用模型

一样可以验证：

1
2
3
4


有没有触发压缩
有没有减少消息数量
有没有保留 system
有没有破坏 tool 边界

这是非常典型的：

把外部依赖隔离出去，先测试自己的逻辑。

二十三、这里有一个我在最新版代码里发现的问题

当前代码：

1
2
3
4


summary = self._summarize(old, summarize)

self.compactions += 1
self.last_summary = summarize

从前面的变量命名和最后返回结果来看，代码意图明显是：

1

self.last_summary = summary

而当前写的是：

1

self.last_summary = summarize

这意味着：

如果没有传 summarize：

1

summarize = None

那么：

1

last_summary = None

即使刚刚已经生成了摘要。

如果传了 summarize：

那么：

1

last_summary

保存的是：

1

函数对象

而不是：

1

摘要结果

所以这不是语法错误，而是一个非常典型的：

“代码能运行，但是状态语义错了”的 Bug。

这其实比语法错误更值得学习。

因为工程里最危险的问题之一就是：

1
2
3


程序没炸
测试可能也没炸
但是状态已经错了

二十四、第三个模块：Tracer

Session 解决：

1

历史在哪里？

Compaction 解决：

1

历史太长怎么办？

但是现在还有一个问题：

Agent 出问题以后，我怎么知道到底发生了什么？

例如：

1
2
3
4
5
6
7
8
9


Agent
 ↓
LLM
 ↓
Tool A
 ↓
Tool B
 ↓
Tool C

最终：

1

失败

你只知道：

1

失败了

但不知道：

1
2
3
4


哪个慢？
哪个炸？
谁调用了谁？
到底执行到了哪一步？

Tracer 就是干这个的。

代码把它比喻成：

外卖配送轨迹。你能看到“接单 → 到店 → 配送 → 送达”，Tracer 则给 Agent 的每一步记录开始、耗时、成功与否。

二十五、Tracer 和 Audit 有什么区别？

这两个特别容易混。

可以这样记：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


Audit：
 谁做了什么？
 为什么做？
 能不能追责？

Trace：
 运行到了哪里？
 花了多久？
 谁调用了谁？
 哪里失败？

也就是：

1
2
3
4
5


Audit
 = 决策/行为记录

Trace
 = 执行链路记录

所以：

Audit 更偏安全、审计。

Trace 更偏性能、排障、可观测性。

二十六、Tracer 最核心的概念：Span

一个 span 可以先理解成：

一次函数/步骤执行的记录。

例如：

1
2
3
4
5
6
7


{
 "span_id": "s1",
 "parent_id": null,
 "name": "agent",
 "ms": 100,
 "ok": true
}

意思：

1
2
3


agent 这一步
执行了 100ms
成功了

如果 agent 又调用了：

1

tool

那么：

1
2
3
4
5


{
 "span_id": "s2",
 "parent_id": "s1",
 "name": "tool"
}

意思：

1

tool 是 agent 的孩子

于是就形成：

1
2
3
4
5


agent
 ├── tool-A
 ├── tool-B
 │ └── helper
 └── tool-C

这就是 Trace 树。

二十七、这里第一次遇到装饰器

你之前没有专门学过装饰器，所以这里单独补。

最简单的装饰器其实就是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


def log_call(fn):

 def wrapper(*args, **kwargs):
 print("开始")

 result = fn(*args, **kwargs)

 print("结束")

 return result

 return wrapper

然后：

1
2
3


@log_call
def add(a, b):
 return a + b

它实际上相当于：

1
2
3
4


def add(a, b):
 return a + b

add = log_call(add)

所以：

1
2
3
4
5
6
7
8
9


原函数
 ↓
交给装饰器
 ↓
获得 wrapper
 ↓
以后调用 add
 ↓
实际上调用 wrapper

这就是装饰器。

二十八、为什么 Tracer 特别适合用装饰器？

因为我们不想每个节点都写：

1
2
3
4
5
6


start = time.perf_counter()

try:
 ...
finally:
 ...

例如：

1
2
3
4
5
6
7
8


def node_a():
 ...

def node_b():
 ...

def node_c():
 ...

如果每个函数都手写 Trace：

1
2
3
4
5
6
7
8


node_a
 写一遍

node_b
 再写一遍

node_c
 再写一遍

太重复了。

所以变成：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


@tracer.trace()
def node_a():
 ...

@tracer.trace()
def node_b():
 ...

@tracer.trace()
def node_c():
 ...

业务函数不用关心 Trace。

这就是：

横切关注点。

业务逻辑：

1

我到底做什么

Trace：

1

我怎么记录你怎么做

两者分开。

二十九、把当前 Tracer 的装饰器拆开

代码核心：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


def trace(self, name=None):

 def deco(fn):

 label = name or getattr(fn, "__name__", "anonymous")

 @functools.wraps(fn)
 def wrapper(*a, **kw):
 ...
 
 return wrapper

 return deco

这里有三层：

1
2
3
4
5


trace()
 ↓
deco(fn)
 ↓
wrapper(*a, **kw)

第一次看到非常绕。

实际上可以这样理解：

第一层

1

trace(name=None)

是：

我准备制作一个“装饰器”。

第二层

1

deco(fn)

是真正接收到：

原来的那个函数。

第三层

1

wrapper(*a, **kw)

是真正以后执行的函数。

所以：

1
2
3


@tracer.trace()
def foo():
 pass

相当于：

1
2
3
4
5
6
7


tracer.trace()
 ↓
 deco
 ↓
 foo
 ↓
 wrapper

三十、`*a, **kw` 是什么？

这一句：

1

def wrapper(*a, **kw):

意思是：

不管原函数接收什么参数，我都先接住。

例如原函数：

1

def foo(x):

可以。

原函数：

1

def foo(x, y):

也可以。

原函数：

1

def foo(x, y, name="a"):

也可以。

所以包装器不需要知道每个业务函数到底有几个参数。

这里：

1

*a

接收：

1

位置参数

这里：

1

**kw

接收：

1

关键字参数

然后：

1

fn(*a, **kw)

再把它原样交给原函数。

三十一、`functools.wraps` 为什么要写？

代码：

1
2


@functools.wraps(fn)
def wrapper(*a, **kw):

装饰器一个常见问题是：

1
2
3


原来的函数名字
原来的 docstring
原来的元信息

可能被 wrapper 覆盖掉。

wraps 可以帮助 wrapper 保留原函数的元信息。

对现在学习阶段来说，记一句即可：

写装饰器时，通常把 functools.wraps 一起写上。

它属于装饰器的工程规范，而不仅仅是为了“能运行”。

三十二、Tracer 为什么先取 parent？

代码：

1
2
3


parent = _current.get()

parent_id = parent["span_id"] if parent else None

意思：

看看“现在是不是已经有一个 Trace 在执行”。

如果没有：

1

parent = None

那么当前 span 是根节点。

如果有：

1

parent = 某个外层 span

那么：

1

parent_id = parent["span_id"]

当前这个 span 就知道：

我是谁的孩子。

三十三、这就是 `contextvars`

代码：

1
2
3
4


_current = contextvars.ContextVar(
 "current_span",
 default=None
)

它保存的是：

当前执行上下文中的 span。

然后：

1

_current.set(holder)

就是：

把当前 span 设置成我。

之后内部再调用一个被 Trace 包住的函数：

1

parent = _current.get()

就能读到：

当前外层是谁。

于是：

1
2
3
4
5


parent
 ↓
child
 ↓
grandchild

自然就串起来了。

三十四、为什么不用一个普通的全局变量？

如果简单写：

1

current_span = None

单线程可能看不出问题。

但真实 Agent 系统可能是：

1
2
3
4


请求 A
请求 B
请求 C
同时执行

如果大家都共用：

1

current_span

就可能出现：

1
2
3
4
5


A 的 Trace
 被 B 改掉

B 的 Trace
 又被 C 改掉

于是父子关系串线。

contextvars 就是专门为这种：

上下文相关、并发场景下需要隔离的数据

设计的。

所以这里实际上不是“为了炫一个 Python API”。

而是：

因为系统未来会并发，所以现在不使用一个简单但不安全的全局变量。

这就是设计和 API 的区别。

三十五、Tracer 最关键的一段：try / except / finally

代码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


try:
 out = fn(*a, **kw)
 return out

except Exception as e:
 ok, err = False, f"{type(e).__name__}: {e}"
 raise

finally:
 _current.reset(token)

 self.record(
 label,
 ms=(time.perf_counter() - t0) * 1000,
 ok=ok,
 err=err,
 parent_id=parent_id,
 span_id=holder["span_id"],
 )

这一段值得仔细学。

三十六、为什么 `return out` 不能漏？

假设：

1
2


def foo():
 return {"x": 1}

Tracer 包装以后：

1
2


def wrapper():
 out = foo()

如果后面没有：

1

return out

那么：

1

wrapper()

得到的就是：

1

None

原函数明明返回了：

1

{"x": 1}

结果被装饰器吃掉了。

这就是为什么注释里专门写：

1

return out

因为：

一个装饰器应该在增加能力的同时保持原函数的行为。

这是工程上非常重要的原则：

非侵入式增强。

三十七、为什么异常要 `raise`？

代码：

1
2
3


except Exception as e:
 ok, err = False, ...
 raise

很多初学者会觉得：

都捕获了，为什么还要再抛？

因为 Trace 的职责是：

1

记录异常

而不是：

1

吞掉异常

比如业务代码：

1

raise ValueError("参数错误")

Tracer 应该：

1
2
3
4
5
6


记录：
 ok = False
 err = ValueError...

然后：
 异常继续抛出去

所以：

1
2
3
4
5


Tracer：
 我负责记录

业务：
 我负责处理异常

职责不能混在一起。

三十八、为什么日志放到 `finally`？

因为：

1

finally

无论：

1
2
3


成功
失败
return

最终都会执行。

所以：

1

return out

之后：

1

finally

仍然会先完成 Trace 记录，再真正返回。

这样：

1
2
3
4
5
6
7
8
9


成功
 ↓
record

失败
 ↓
record
 ↓
继续抛异常

两条路径都能留下记录。

这就是为什么：

1
2
3


try
except
finally

这里其实已经不是简单语法题了。

它是在实现一个工程保证：

无论业务成功还是失败，都尽量记录一次执行结果。

三十九、为什么 `_current.reset(token)` 也必须做？

之前：

1

token = _current.set(holder)

相当于：

1
2


当前上下文：
旧值 → holder

那么结束以后：

1

_current.reset(token)

就是：

1

恢复原来的上下文

否则下一次执行的时候：

1

旧 span

可能还残留。

所以这是另一种工程思维：

设置了上下文，就必须负责恢复上下文。

很像：

1
2
3
4
5


打开资源
 ↓
使用
 ↓
关闭资源

四十、Tracer 怎么得到父子树？

每条 span 都保存：

1
2
3
4
5
6
7
8
9


{
 "span_id": ...,
 "parent_id": ...,
 "name": ...,
 "ms": ...,
 "ok": ...,
 "err": ...,
 "ts": ...
}

所以：

1
2
3
4
5


s1
├── s2
├── s3
│ └── s4
└── s5

其实不是提前存了一棵树。

而是：

每个节点只保存“我的父亲是谁”。

最后：

1

children.setdefault(s["parent_id"], []).append(s)

把：

1

parent_id

重新组织成：

1

树

这叫：

扁平记录，树形重建。

这是一种很常见的数据设计。

因为写入的时候：

1

每条 span 独立

比较简单。

真正展示的时候：

1

再组装成树

比较灵活。

四十一、为什么 `total_ms()` 只统计顶层 span？

代码：

1
2
3
4
5
6
7
8


return round(
 sum(
 s["ms"]
 for s in self.spans
 if s["parent_id"] is None
 ),
 3
)

为什么不把所有 span 都加起来？

假设：

1
2
3


agent 100ms
 ├── tool 30ms
 └── llm 50ms

如果全加：

1

100 + 30 + 50 = 180ms

但实际上：

1

用户看到的总执行时间

更接近：

1

100ms

因为：

1
2


tool
llm

已经包含在 agent 的执行时间里面。

所以：

统计指标必须先定义语义，再写代码。

这也是工程化非常重要的一点。

不是：

1

能算出来

就代表：

1

这个数字有意义

四十二、把三个模块连起来

现在把整个流程画出来。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38


 Agent / LangGraph
 │
 │
 ▼
 SessionStore
 │
 保存全量历史
 │
 ▼
 session.messages()
 │
 ▼
 ContextCompactor
 │
 ┌────────┴─────────┐
 │ │
 不超过阈值 超过阈值
 │ │
 ▼ ▼
 原消息 摘要 + 最近消息
 │ │
 └────────┬─────────┘
 ▼
 LLM
 │
 ▼
 Agent 执行
 │
 ▼
 Tracer
 │
 ┌─────────────┼─────────────┐
 ▼ ▼ ▼
 name ms ok
 │ │ │
 └─────────────┼─────────────┘
 ▼
 Trace Tree

所以现在可以把三者记成一句话：

Session 管“数据有没有”，Compaction 管“这次给模型看多少”，Tracer 管“这次到底发生了什么”。

四十三、真正的工程化思维：不是“我会不会写这个类”

我觉得 Day5 最应该学的，其实不是：

1
2
3
4
5


json
os
time
contextvars
functools

而是下面这个思考顺序。

第一步：先找失败场景

不要问：

我要写一个 Session 类。

先问：

如果 Agent 重启，会发生什么？

于是得到：

1

需要持久化

不要问：

我要写一个 Compactor。

先问：

如果对话越来越长，会发生什么？

于是得到：

1

需要压缩

不要问：

我要写一个 Tracer。

先问：

Agent 出问题以后，我怎么排查？

于是得到：

1

需要 Trace

四十四、第二步：给每个模块划边界

Session

负责：

1
2
3


保存
读取
删除

不负责：

1
2
3


摘要
LLM
模型调用

Compactor

负责：

1
2
3


决定什么时候压
怎么切
怎么摘要

不负责：

1

保存原始历史

Tracer

负责：

1

记录执行

不负责：

1

改变业务结果

边界越清楚：

1
2
3


模块之间越容易替换
测试越容易写
出错越容易定位

四十五、第三步：定义“不变量”

工程代码真正重要的，不只是“正常情况下怎么跑”。

而是：

什么事情无论如何都不能发生？

这三个模块里，其实有很多这样的“不变量”。

Session

1

不能因为坏一行，导致整个历史不可读

Compaction

1

不能把 assistant.tool_calls 和 tool result 拆开

Tracer

1

不能因为记录日志，改变业务函数返回值

Tracer

1

不能因为 Trace 出错，让业务逻辑一起失败

Compaction

1

不能为了压缩，把原始 Session 数据永久删掉

一旦开始用：

“这个系统必须永远保证什么？”

去看代码。

你就开始进入工程思维了。

四十六、第四步：再考虑异常

继续拿三个模块举例。

Session

如果文件坏了一行：

1
2


跳过
继续恢复

Delete

如果重写过程中挂了：

1
2
3


临时文件
+
原子替换

Tracer

如果日志落盘失败：

1
2


except OSError:
 pass

为什么？

因为：

日志系统不能反过来杀死主业务。

Tracer

如果业务抛异常：

1

raise

为什么？

因为：

Trace 不能吞掉业务错误。

这些都是非常典型的：

失败隔离。

四十七、第五步：再考虑“以后会不会变”

这就是为什么这里大量使用：

1
2
3
4


path
summarize
parent_id
contextvars

例如：

Session

今天：

1

JSONL

以后：

1

SQLite

Compactor

今天：

1

规则摘要

以后：

1

LLM 摘要

Tracer

今天：

1

JSONL

以后：

1

真正的 Observability 系统

好的工程代码不是：

“今天刚好能跑。”

而是：

在合理范围内，为未来变化预留替换点。

四十八、这三个文件里我最值得记住的 8 个工程设计

1. 原始数据和派生数据分开

1
2
3
4
5
6
7


Session
 ↓
原始历史

Compaction
 ↓
模型视图

2. append-only 优先

1

新增记录

比：

1

修改旧记录

更容易处理崩溃。

3. 局部失败不要扩大

1

坏一行

不应该变成：

1

整个 Session 不能恢复

4. 基础设施不能改变业务语义

Tracer：

1

记录业务函数

不能：

1

修改业务函数返回值

5. 业务异常不能被基础设施吞掉

1

raise

必须保留。

6. 依赖注入

1

summarize=...

意味着：

1

逻辑和具体 LLM 解耦

7. 原子替换

1
2
3


tmp
↓
os.replace

避免中间态破坏真实文件。

8. 先定义指标含义再计算

1

total_ms()

没有简单地：

1

所有 span 全加

而是只加：

1

root span

因为“总耗时”有明确的业务语义。

四十九、三个文件的最新版代码

下面代码保持你上传的三个最新版文件内容不变，方便以后复习时直接对照。

`session.py`

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151


"""SessionStore —— 会话状态持久化(Harness 模块③)

类比: 游戏存档点。
 打到一半关机, 下次读档还在原地 —— 这就是 session 的作用。
 没有它, 每次打开都是新游戏: 第一关重来。

★ 三个必须回答的设计问题:
 1) 存哪? 内存 / JSONL 文件 / SQLite ...
 -> 同一个接口, 换后端不改调用方
 2) 怎么存? append-only(只追加, 不改旧行)
 -> 崩溃安全: 写到一半挂了, 前面的行仍然完整可读
 3) 存什么? 每轮的消息快照 + 元数据(ts / seq / meta)

★ 核心决策(面试会问): 压缩后存, 还是存全量、读时再压?
 答案: 存全量, 读时压(投影)。
 理由: 压缩策略是会变的。今天 max=20, 明天想改成 10 —— 存全量还能改,
 存压缩版就永久丢了。
 类比: 数据库的 WAL(先如实记日志) + 视图(按需投影)。
"""
from __future__ import annotations

import json
import os
import time


class SessionStore:
 """会话状态持久化。thread_id -> 一串快照。"""

 def __init__(self, path=None):
 self.path = path
 self.bad_lines = 0
 self._mem = {}

 def _read_all(self):
 if self.path is None:
 return {k: list(v) for k, v in self._mem.items()}

 out = {}

 if not os.path.exists(self.path):
 return out

 with open(self.path, encoding="utf-8") as f:
 for line in f:
 line = line.strip()

 if not line:
 continue

 try:
 rec = json.loads(line)
 tid = rec["thread_id"]

 except (json.JSONDecodeError, KeyError, TypeError):
 self.bad_lines += 1
 continue

 out.setdefault(tid, []).append(rec)

 return out

 def _count(self, thread_id):
 if self.path is None:
 return len(self._mem.get(thread_id, []))

 n = 0

 if not os.path.exists(self.path):
 return 0

 with open(self.path, encoding="utf-8") as f:
 for line in f:
 line = line.strip()

 if not line:
 continue

 try:
 if json.loads(line)["thread_id"] == thread_id:
 n += 1
 except Exception:
 pass

 return n

 def append(self, thread_id, messages, meta=None):
 rec = {
 "ts": time.time(),
 "thread_id": thread_id,
 "seq": self._count(thread_id),
 "messages": list(messages),
 "meta": dict(meta or {}),
 }

 if self.path is None:
 self._mem.setdefault(thread_id, []).append(rec)
 return rec

 d = os.path.dirname(os.path.abspath(self.path))

 if d:
 os.makedirs(d, exist_ok=True)

 tail_complete = True

 if os.path.exists(self.path) and os.path.getsize(self.path) > 0:
 with open(self.path, "rb") as fr:
 fr.seek(-1, os.SEEK_END)
 tail_complete = fr.read(1) == b"\n"

 with open(self.path, "a", encoding="utf-8") as f:
 if not tail_complete:
 f.write("\n")

 f.write(json.dumps(rec, ensure_ascii=False) + "\n")
 f.flush()
 os.fsync(f.fileno())

 return rec

 def load(self, thread_id):
 return self._read_all().get(thread_id, [])

 def latest(self, thread_id):
 rs = self.load(thread_id)
 return rs[-1] if rs else None

 def messages(self, thread_id):
 rec = self.latest(thread_id)
 return list(rec["messages"]) if rec else []

 def list_threads(self):
 return sorted(self._read_all().keys())

 def delete(self, thread_id):
 if self.path is None:
 self._mem.pop(thread_id, None)
 return

 data = self._read_all()
 data.pop(thread_id, None)

 tmp = self.path + ".tmp"

 with open(tmp, "w", encoding="utf-8") as f:
 for recs in data.values():
 for r in recs:
 f.write(json.dumps(r, ensure_ascii=False) + "\n")

 os.replace(tmp, self.path)

`compact.py`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93


"""ContextCompactor —— 上下文压缩(Harness 模块④)

类比: 行李箱超重。
 要带 40 件衣服上飞机, 航空公司只让带 10 件。两种做法:
 (a) 直接扔掉 30 件 -> 你会忘事(不可逆丢失)
 (b) 写张清单"带了 5 件外套 3 件衬衫…", 实物少带 -> 摘要
 压缩就是 (b)。

★ 关键陷阱: assistant.tool_calls 和它对应的 tool 结果是一对, 不能拆开!
 类比: 你不能只寄出"问路的话"却不寄"对方的回答" —— 很多 API 会直接 400。
 真实踩过的坑: 删旧消息时把 assistant 的 tool_calls 删了、留下 tool 结果,
 模型收到"孤儿 tool 结果" -> 报错。
 修法: 切分点如果正好落在 tool 消息上, 就往前退到发起它的 assistant 消息。

★ 压缩是"投影"不是"销毁": 原始消息仍在 SessionStore 里(存全量)。
 好处: 改策略(max 20 -> 10)不用回填历史; 压缩算错也不会不可逆。
"""

from __future__ import annotations

from regex import R

def _role(m):
 return m.get("role") or m.get("type") or "?"

def _is_tool_result(m):
 return _role(m) =="tool"

def _safe_cut(messages,cut):
 """★ 把切分点往前挪, 保证不把 assistant.tool_calls 和 tool 结果拆开"""
 cut = max(0,min(cut,len(messages)))

 while cut>0 and cut <len(messages) and _is_tool_result(messages[cut]):
 cut -=1

 return cut


class ContextCompactor:
 def __init__(self,max_messages=20,keep_recent=6,keep_system=True):
 self.max_messages = max_messages
 self.keep_recent = keep_recent
 self.keep_system = keep_system
 self.compactions = 0
 self.last_summary = None

 def needs_compaction(self,messages):
 return len(messages)> self.max_messages

 def maybe_compact(self,messages,summarize=None):
 if not self.needs_compaction(messages):
 return None 

 head,body =[],list(messages)

 if self.keep_system and body and _role(body[0]) =="system":
 head,body=[body[0]],body[1:]

 cut =max(0,len(body) - self.keep_recent)
 cut=_safe_cut(body,cut)

 if cut ==0:
 return None

 old, recent = body[:cut], body[cut:]
 summary=self._summarize(old,summarize)

 self.compactions+=1
 self.last_summary=summarize

 return head + [
 {
 "role": "system",
 "content": f"[历史摘要] {summary}"
 }
 ] + recent

 def _summarize(self,old,summarize):
 if summarize is not None:
 return summarize(old)

 roles ={}

 for m in old:
 r=_role(m)
 roles[r] =roles.get(r,0)+1

 detail = ", ".join(
 f"{k}x{v}"
 for k, v in sorted(roles.items())
 )

 return f"已折叠 {len(old)} 条早期消息 ({detail})"

`trace.py`

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153


"""Tracer —— 调用链追踪(Harness 模块⑤)

类比: 外卖配送轨迹。
 点外卖能看到: 商家接单 -> 骑手到店 -> 配送中 -> 已送达。
 Tracer 给 Agent 的每一步盖一个"开始 / 结束 / 耗时 / 成功没有"。

★ 和审计日志(audit)的区别 —— 两者都要, 不能互相替代:
 audit : 谁做了什么【决策】(安全视角, 用于追责/合规)
 trace : 每一步花了多久、成功没有、谁调用了谁(性能/排障视角)
 一句话: audit 回答"该不该做", trace 回答"为什么慢 / 为什么炸"。

★ 关键陷阱(踩过): 装饰器把返回值吃掉 -> 图直接报错。
 因为 LangGraph 节点必须返回 dict, 装饰器里少写一句 return 就变成返回 None。
 修法: try 里 return out, finally 里记日志 —— 两者互不干扰。
"""
from __future__ import annotations

import contextvars
import functools
import json
import os
import time

_current = contextvars.ContextVar("current_span", default=None)


class Tracer:
 def __init__(self, path=None):
 self.path = path
 self.spans = []
 self._seq = 0

 def _next_seq(self):
 self._seq += 1
 return self._seq

 def new_span_id(self):
 return f"s{self._next_seq()}"

 def record(self, name, *, ms, ok, err=None, parent_id=None, span_id=None):
 span = {
 "span_id": span_id or self.new_span_id(),
 "parent_id": parent_id,
 "name": name,
 "ms": round(float(ms), 3),
 "ok": bool(ok),
 "err": err,
 "ts": time.time(),
 }

 self.spans.append(span)

 if self.path:
 d = os.path.dirname(os.path.abspath(self.path))

 if d:
 os.makedirs(d, exist_ok=True)

 try:
 with open(self.path, "a", encoding="utf-8") as f:
 f.write(
 json.dumps(span, ensure_ascii=False) + "\n"
 )
 except OSError:
 pass

 return span

 def trace(self, name=None):
 def deco(fn):
 label = name or getattr(fn, "__name__", "anonymous")

 @functools.wraps(fn)
 def wrapper(*a, **kw):
 parent = _current.get()
 parent_id = parent["span_id"] if parent else None

 holder = {
 "span_id": self.new_span_id(),
 "name": label
 }

 token = _current.set(holder)
 t0 = time.perf_counter()

 ok, err = True, None

 try:
 out = fn(*a, **kw)
 return out

 except Exception as e:
 ok, err = False, f"{type(e).__name__}: {e}"
 raise

 finally:
 _current.reset(token)

 self.record(
 label,
 ms=(time.perf_counter() - t0) * 1000,
 ok=ok,
 err=err,
 parent_id=parent_id,
 span_id=holder["span_id"]
 )

 return wrapper

 return deco

 def summary(self):
 children = {}

 for s in self.spans:
 children.setdefault(
 s["parent_id"],
 []
 ).append(s)

 lines = []

 def walk(pid, depth):
 for s in children.get(pid, []):
 mark = "OK " if s["ok"] else "ERR"
 extra = f" <- {s['err']}" if s["err"] else ""

 lines.append(
 f"{' ' * depth}"
 f"{mark} "
 f"{s['name']} "
 f"{s['ms']}ms"
 f"{extra}"
 )

 walk(s["span_id"], depth + 1)

 walk(None, 0)
 return "\n".join(lines)

 def total_ms(self):
 return round(
 sum(
 s["ms"]
 for s in self.spans
 if s["parent_id"] is None
 ),
 3
 )

 def clear(self):
 self.spans.clear()
 self._seq = 0

五十、最后重新理解一下：“工程化”到底是什么？

以前我可能会把工程化理解成：

1
2
3
4
5


目录规范
命名规范
class
日志
测试

现在理解得更准确一点。

工程化并不是：

把代码写得更复杂。

而是：

面对真实运行环境中的失败、变化、并发、维护问题，提前设计边界和保护机制。

比如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


程序重启
 ↓
Session

上下文过长
 ↓
Compaction

数据压坏
 ↓
跳过坏行

删除过程崩溃
 ↓
tmp + os.replace

日志系统失败
 ↓
不能影响主流程

业务函数异常
 ↓
Trace 记录后继续 raise

嵌套调用
 ↓
parent_id

未来换摘要模型
 ↓
summarize 注入

你会发现：

工程代码很多时候不是在写“正常情况”。

而是在写：

1
2
3
4
5


如果坏了怎么办？
如果未来变了怎么办？
如果并发了怎么办？
如果中途退出怎么办？
如果一个模块挂了怎么办？

这才是今天真正应该带走的东西。

五十一、Day5 我现在真正学到的，不是三个类

可以最后把今天压缩成这一张图：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


 “Agent 怎么长期稳定运行？”
 │
 ┌─────────────────┼─────────────────┐
 │ │ │
 ▼ ▼ ▼
 数据问题 上下文问题 排障问题
 │ │ │
 ▼ ▼ ▼
 Session Store Compaction Tracer
 │ │ │
 ▼ ▼ ▼
 存全量 读时压 记执行
 │ │ │
 └─────────────────┼─────────────────┘
 ▼
 Agent Harness

真正的工程思维则是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


先发现问题
 ↓
定义模块边界
 ↓
定义不变量
 ↓
选择数据结构
 ↓
考虑失败场景
 ↓
隔离外部依赖
 ↓
保留替换空间
 ↓
最后才是写代码

所以以后再看到一个陌生的工程文件，我不能只问：

“这个函数是干嘛的？”

还应该继续问：

“它防的是哪个问题？”

再继续：

“如果删掉这段，会坏在哪里？”

再继续：

“为什么不使用更简单的写法？”

最后：

“这个模块和其他模块之间，边界在哪里？”

这应该就是我这一阶段真正要练的东西。

五十二、复习时我只需要记住这 12 句话

Session 是存档，不是 Agent 业务逻辑。
原始历史尽量保存，压缩属于派生视图。
append-only 的价值是降低修改历史数据带来的崩溃风险。
坏一条数据，不应该让整个系统一起死。
Compaction 不是删除历史，而是减少这次送给模型的数据。
消息条数不等于 Token 数。
tool call 和 tool result 不能随便拆。
装饰器本质是“用一个 wrapper 包住原函数”。
Tracer 必须透传原函数返回值。
记录异常和处理异常是两回事，所以要 raise。
contextvars 是为了让嵌套、并发执行下的上下文不串线。
工程化真正关注的是：失败、边界、变化和可维护性。

反思循环：Critique-Revise，让 Agent 自己检查、修改，再决定要不要继续

Wed, 16 Sep 2026 14:35:03 +0800

W7-Day3｜反思循环：Critique-Revise，让 Agent 自己检查、修改，再决定要不要继续

昨天是 Supervisor：一个 Agent 负责调度，多个 Worker 负责执行。

今天把昨天的 reviewer 往前再推进一步：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


generator
 ↓
critic
 ↓
┌───────────────┬────────────────┬─────────────────┐
│ 达标 │ 次数用尽 │ 质量回退 │
│ score >= 8 │ revise >= 3 │ score 下降 │
│ ↓ │ ↓ │ ↓ │
│ END │ END │ END │
└───────────────┴────────────────┴─────────────────┘
 ↑
 未达标
 ↓
 reviser
 ↓
 critic
 ↓
 循环

今天的核心不是“让模型多改几遍”。

而是：

让模型的评审结果进入程序控制流，再由程序决定继续修改还是结束。

所以今天实际上是在做一个完整的：

1

评审 → 修改 → 再评审 → 决定是否继续

一、先看今天的 State

今天的 State：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


class RState(MessagesState):
 topic: str
 draft: str
 score: int
 issues: list[str]
 revise_count: int

 # 每轮评审轨迹
 trajectory: Annotated[list, operator.add]

 # 历史最优稿
 best_draft: str
 best_score: int

如果使用最终版本，还会增加硬伤字段：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


class RState(MessagesState):
 topic: str
 draft: str
 score: int
 issues: list[str]
 fatal_issues: list[str]
 revise_count: int
 trajectory: Annotated[list, operator.add]
 best_draft: str
 best_score: int

所以 State 可以先理解成：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


messages → 工作历史
topic → 当前任务
draft → 当前文章
score → 当前评分
issues → 当前普通问题
fatal_issues → 当前硬伤
revise_count → 已经修改几次
trajectory → 历史评审轨迹
best_draft → 历史最优稿
best_score → 历史最高分

这里和之前学习 State 时的理解是一致的：

State 不是“变量大杂烩”，每一个字段都应该承担明确职责。

二、为什么今天不直接让 `critic` 返回一句话

最简单的 critic 可能写成：

1

文章还可以，但是第二段缺少例子，结尾也比较仓促。

对人来说没问题。

但是程序马上会遇到几个问题：

1
2
3
4


到底多少分？
是否达标？
有什么问题？
应该继续改吗？

如果返回自由文本，程序就还要自己从文本里猜。

于是今天改成结构化输出：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


class Critique(BaseModel):
 score: int = Field(
 ge=1,
 le=10,
 description="1-10分，8分及以上达标",
 )

 issues: list[str] = Field(
 default_factory=list,
 description="软问题，影响分数",
 )

 passed: bool = Field(
 description="是否达标",
 )

最终版本再增加：

1
2
3
4
5
6
7


fatal_issues: list[str] = Field(
 default_factory=list,
 description=(
 "硬伤：编造/无来源的具体数据、事实错误、违规内容。"
 "只要非空，无论多少分都不达标"
 ),
)

于是模型的输出不再只是：

1

一段话

而变成：

1
2
3
4


score
issues
fatal_issues
passed

这样程序才能继续处理。

所以这里形成了一个非常重要的链：

1
2
3
4
5
6
7
8
9


LLM
 ↓
结构化输出
 ↓
State
 ↓
条件边
 ↓
控制流

三、先看 `Critique`

代码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


class Critique(BaseModel):
 """② 强制 critic 输出可判断的结果，而不是一段自由文本"""

 score: int = Field(
 ge=1,
 le=10,
 description="1-10分，8分及以上达标",
 )

 issues: list[str] = Field(
 default_factory=list,
 description="软问题，影响分数",
 )

 fatal_issues: list[str] = Field(
 default_factory=list,
 description=(
 "硬伤：编造/无来源的具体数据、事实错误、违规内容。"
 "只要非空，无论多少分都不达标"
 ),
 )

 passed: bool = Field(
 description="是否达标",
 )

这里的几个字段并不是同一种东西。

`score`

1

score: int

代表：

当前稿件的总体评分。

并且通过：

1
2


ge=1
le=10

把合法范围限制在：

1

1 ~ 10

也就是说，模型不能正常返回：

1

score = 15

`issues`

1

issues: list[str]

代表：

普通问题。

例如：

1
2
3


第二段缺少案例
结论过于仓促
表达略显重复

它们的特点是：

1
2
3
4
5


发现问题
 ↓
修改
 ↓
可能解决

所以这是一个软问题集合。

`fatal_issues`

1

fatal_issues: list[str]

这里和 issues 不一样。

例如：

1
2
3
4


编造统计数据
事实错误
无来源的具体事实
违规内容

这类问题不能简单用：

1

“多写一点”

解决。

所以它单独成为一个硬门槛。

`passed`

1

passed: bool

这个字段看起来很有用。

但今天后来会发现：

不能直接相信模型自己给出的 passed。

因为它也是模型输出的。

真正控制程序的最终判断，还是应该由程序自己做。

后面会再看。

四、为什么 `score` 还要手动校验

结构化输出并不意味着所有业务约束都自动解决。

例如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


def _parse_critique(raw) -> Critique:
 """手动校验：json_mode 不保证数值范围"""

 if not isinstance(raw, Critique):
 raw = Critique.model_validate(raw)

 if not (1 <= int(raw.score) <= 10):
 raise ValueError(
 f"score 越界: {raw.score}"
 )

 return raw

这里其实是两层校验。

第一层：

1

Critique

负责定义结构。

第二层：

1

_parse_critique()

负责程序自己的业务检查。

可以理解为：

1
2
3
4
5
6
7


模型输出
 ↓
结构化解析
 ↓
程序二次校验
 ↓
真正进入 State

所以：

Schema 是第一道门，程序逻辑是第二道门。

五、先看 `generator`

代码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


def generator(state: RState) -> dict:
 """初稿"""

 r = llm.invoke(
 f"请写一篇约200字的中文短文，"
 f"主题：{state['topic']}。只输出正文。"
 )

 draft = str(r.content)

 print(
 f"[generator] 初稿 {len(draft)}字"
 )

 return {
 "draft": draft,
 "revise_count": 0,
 "best_draft": draft,
 "best_score": 0,
 }

它其实非常简单。

输入：

1

State

读取：

1

state["topic"]

生成：

1

draft

然后返回：

1
2
3
4
5
6


{
 "draft": draft,
 "revise_count": 0,
 "best_draft": draft,
 "best_score": 0,
}

为什么初始化 `best_draft`

因为从系统角度看，初稿也是一个候选版本。

例如：

1

v1 = 7分

后面可能：

1
2


v2 = 8分
v3 = 7分

那么最终需要知道：

1

历史最好的是 v2

所以从第一轮开始，就应该有：

1
2


best_draft = draft
best_score = 0

第一次 critic 之后再真正更新最佳分数。

六、再看 `JUDGE_SYS`

代码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


JUDGE_SYS = """你是严格但公正的中文写作评审。

评分维度：
① 观点清晰度
② 论据支撑
③ 结构层次
④ 表达流畅

评分标准：
8分及以上为达标。

issues 必须写「具体可改的问题」，
不要写「可以更好」这类空话。

issues 最多3条，
每条不超过15字。

输出格式：
只输出一个 JSON 对象，形如：

{
 "score": 7,
 "issues": [
 "第2段缺少具体例子",
 "结论过于仓促"
 ],
 "fatal_issues": [],
 "passed": false
}
"""

这一部分是：

告诉 critic 应该如何评价。

这里其实包含三层信息。

第一层：

1

评什么

例如：

1
2
3
4


观点
论据
结构
表达

第二层：

1

怎么给分

例如：

1

8分以上达标

第三层：

1

输出什么结构

例如：

1
2
3
4
5
6


{
 "score": 7,
 "issues": [],
 "fatal_issues": [],
 "passed": false
}

于是模型输出就有了一个固定接口。

七、critic 节点到底做什么

先看主体：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


def critic(state: RState) -> dict:
 """评审：打分+列问题。同时更新轨迹与最优稿"""

 judge = llm.with_structured_output(
 Critique,
 method="json_mode",
 )

 prompt = (
 f"{JUDGE_SYS}\n\n"
 f"文稿:\n{state['draft']}"
 )

 ...

这里其实可以拆成：

1
2
3
4
5
6
7


当前 State
 ↓
取 draft
 ↓
交给 critic
 ↓
得到 Critique

八、为什么这里重新调用 `with_structured_output`

1
2
3
4


judge = llm.with_structured_output(
 Critique,
 method="json_mode",
)

这个 judge 和普通的：

1

llm

区别在于：

1
2
3
4
5
6
7


普通 llm
 ↓
自由文本

judge
 ↓
按照 Critique 结构输出

所以从角色上可以理解成：

1
2
3
4
5
6
7


llm
 ↓
生成 / 修改文章

judge
 ↓
评价文章

即使底层使用的是同一个模型，也可以通过不同的输出契约，把它变成不同角色。

九、为什么这里用 `json_mode`

之前已经实测过几条结构化输出路径。

默认：

1

with_structured_output(Critique)

在当前环境走到了 json_schema，不支持。

function_calling 又遇到了：

1

Thinking mode does not support this tool_choice

最后使用：

1

method="json_mode"

所以今天的代码：

1
2
3
4


judge = llm.with_structured_output(
 Critique,
 method="json_mode",
)

这里真正值得记住的是：

接口名字一样，不代表底层协议路径一样。

以后遇到模型兼容问题，不能简单理解成：

1

“这个模型不支持结构化输出”

而应该进一步问：

1

到底是哪一种结构化输出方式不支持？

十、critic 为什么要尝试三次

代码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


c = None

for attempt in range(3):
 try:
 c = _parse_critique(
 judge.invoke(prompt)
 )
 break

 except Exception as e:
 print(
 f"[warn] 第 {attempt + 1} 次评审解析失败: "
 f"{type(e).__name__}: {str(e)[:80]}"
 )

这里处理的是：

1
2
3


调用失败
解析失败
字段不符合预期

而不是评分逻辑本身。

所以：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


第一次失败
 ↓
重试

第二次失败
 ↓
重试

第三次失败
 ↓
进入保守兜底

十一、为什么解析失败以后不能默认“通过”

代码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


if c is None:
 c = Critique(
 score=1,
 issues=["评审解析失败，无法判断"],
 fatal_issues=[],
 passed=False,
 )

 print(
 "[warn] 三次都失败 → "
 "保守判定为不达标"
 )

这里采用的是：

宁可多改一轮，也不能因为评审失败就直接放行。

如果解析失败还继续：

1
2


score = 8
passed = True

那就会变成：

1
2
3


没有得到有效评审
 ↓
却被当成通过

这属于非常危险的默认行为。

所以这里是：

1
2
3
4
5


无法判断
 ↓
保守处理
 ↓
不通过

十二、为什么 `passed` 不是程序最终事实来源

代码：

1
2
3
4
5
6
7
8
9


passed_by_code = c.score >= PASS_SCORE

if passed_by_code != c.passed:
 print(
 f"[warn] 模型说 passed={c.passed}，"
 f"但 score={c.score} 对照阈值 "
 f"{PASS_SCORE} 应为 {passed_by_code}"
 f" → 以程序的判定为准"
 )

这里非常值得理解。

假设：

1
2
3


模型：
score = 8
passed = True

如果：

1

PASS_SCORE = 11

程序自己计算：

1
2
3


8 >= 11
↓
False

于是：

1
2


模型：True
程序：False

这时候程序不去争论模型为什么这么判断。

直接：

1
2
3


程序阈值
 ↓
作为控制流事实

所以：

模型给的是判断建议，程序给的是执行规则。

十三、把“模型判断”和“程序判断”彻底拆开

现在可以画成：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


 critic
 │
 ┌───────┴────────┐
 ↓ ↓
 模型判断 程序判断
 passed=True score >= threshold
 │ │
 │ ↓
 │ 控制流
 │
 └────→ 仅用于交叉检查

这其实是 Agent 系统里一个非常重要的思想：

不要让模型自己返回一个 approved=True，然后程序看到 True 就无条件执行。

因为：

1

approved

本身也是模型产生的数据。

十四、critic 如何更新 `best_draft`

代码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


score = int(c.score)

best_score = state.get(
 "best_score",
 0,
)

best_draft = state.get(
 "best_draft",
 "",
)

if score > best_score:
 best_score = score
 best_draft = state["draft"]

这里就是：

1
2
3
4
5
6
7


当前分数
 ↓
和历史最高分比较
 ↓
如果更高
 ↓
更新 best

例如：

1
2
3
4
5
6
7
8


第1轮 7
best = 7

第2轮 8
best = 8

第3轮 7
best 仍然 = 8

所以：

1

draft

和：

1

best_draft

是两个不同概念。

1
2
3
4
5


draft
 = 当前正在修改的版本

best_draft
 = 到目前为止历史最好版本

十五、为什么这个机制很重要

因为 Self-Refine 并不是单调优化。

可能：

1

7 → 8 → 7

如果没有 best_draft：

1

最终 = 7

有了以后：

1

最终 = 历史最佳 8

所以它实际上给循环增加了一层：

回退保护。

可以理解成：

1
2
3
4
5
6
7
8
9


当前版本
 ↓
如果更好
 ↓
保存

如果更差
 ↓
保留历史最优

这和 Git、checkpoint、best model 等很多工程思想其实是同一类思路：

不要只记住“现在是什么”，还要记住“最好是什么”。

十六、critic 为什么要记录 `trajectory`

代码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


entry = dict(
 round=len(state.get("trajectory", [])),
 score=score,
 issues=c.issues,
 fatal_issues=c.fatal_issues,
 draft_len=len(state["draft"]),
 draft_head=(
 state["draft"][:60]
 .replace("\n", " ")
 ),
)

这里保存：

1
2
3
4
5
6


第几轮
多少分
有什么问题
有什么硬伤
稿子多长
稿子开头

然后：

1
2
3
4
5
6
7
8
9


return {
 "score": score,
 "issues": c.issues,
 "fatal_issues": c.fatal_issues,
 "trajectory": [entry],
 "best_score": best_score,
 "best_draft": best_draft,
 ...
}

这里最容易忽略的是：

1

trajectory: Annotated[list, operator.add]

这意味着：

1
2


不是覆盖
而是追加

所以：

1
2
3
4
5
6
7
8


第1轮
→ [entry1]

第2轮
→ [entry1, entry2]

第3轮
→ [entry1, entry2, entry3]

这就是为什么最后可以打印：

1

7 → 8 → 7

而不是只能看到最后一次评分。

十七、为什么 `trajectory` 要用 reducer

如果没有：

1

Annotated[list, operator.add]

State 更新更接近：

1
2
3
4
5


旧 trajectory
 ↓
新 trajectory
 ↓
覆盖

那就很难保留完整轨迹。

现在通过：

1

operator.add

表达：

每次节点返回一个新的历史片段，把它追加进旧历史。

所以：

1

trajectory

实际上是一个典型的：

State 累积字段。

十八、critic 最终返回的 State 更新

完整看：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


return {
 "score": score,
 "issues": c.issues,
 "fatal_issues": c.fatal_issues,
 "trajectory": [entry],
 "best_score": best_score,
 "best_draft": best_draft,
 "messages": [
 (
 "assistant",
 f"[评审] {score} 分 | "
 f"问题: {c.issues} | "
 f"硬伤: {c.fatal_issues}"
 )
 ],
}

注意它没有返回：

1

draft

因为：

1

critic 不负责修改文章

它只负责：

1

评审

所以 State 中：

1

draft

仍然是当前稿子。

下一步：

1

route

决定要不要进入：

1

reviser

这就是很清楚的职责边界：

1
2
3
4
5
6
7
8


generator
 → 生成

critic
 → 评价

reviser
 → 修改

十九、再看 `reviser`

代码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


def reviser(state: RState) -> dict:
 """按评审意见重写"""

 r = llm.invoke(
 "请根据评审意见改进以下文稿，"
 "保持主题不变、篇幅相近，"
 "只输出改进后的正文。\n\n"

 f"原稿:\n{state['draft']}\n\n"

 f"评审意见:\n{state['issues']}"
 )

 draft = str(r.content)

 n = (
 state.get("revise_count", 0)
 + 1
 )

 print(
 f"[reviser] 第{n}次修改，"
 f"新稿{len(draft)}字"
 f"(原 {len(state['draft'])}字)"
 )

 return {
 "draft": draft,
 "revise_count": n,
 }

它和 critic 的区别非常明显。

critic：

1
2
3
4
5
6
7
8


输入：
draft

输出：
score
issues
fatal_issues
trajectory

reviser：

1
2
3
4
5
6
7


输入：
draft
issues

输出：
new draft
revise_count

所以：

1
2
3
4
5
6
7


critic
 ↓
结构化意见

reviser
 ↓
新的文章

二十、为什么 reviser 不带完整历史

代码：

1
2


f"原稿:\n{state['draft']}\n\n"
f"评审意见:\n{state['issues']}"

没有把：

1
2
3
4
5


第一轮 draft
第一轮 issues
第二轮 draft
第二轮 issues
...

全部塞进去。

而是只给：

1
2
3


当前稿
+
当前意见

因此每轮都像：

1
2
3
4
5


上一版
+
这一轮建议
 ↓
下一版

这样做的直接目的：

不让上下文随着迭代不断膨胀。

但也会带来一个特点：

reviser 做的是“重写”，不是“打补丁”。

所以才会出现：

模型为了满足当前意见，可能顺手重写很多内容。

这也是今天观察到的一个真实问题：

Prompt 里说“篇幅相近”，并不等于模型一定会严格遵守。

二十一、为什么 `revise_count` 要自己加

代码：

1
2
3
4


n = (
 state.get("revise_count", 0)
 + 1
)

这里记录：

reviser 节点实际执行了多少次。

比如：

1
2
3
4
5
6


generator
→ critic
→ reviser
→ critic
→ reviser
→ critic

那么：

1

revise_count = 2

注意：

1
2
3


critic 次数
≠
reviser 次数

如果第一次 critic 是检查初稿：

1

critic = 1

那么：

1

reviser = critic - 1

在正常完整路径下可以大致这样理解。

二十二、真正控制循环的是 `route_after_critic`

代码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


def route_after_critic(
 state: RState,
) -> Literal["reviser", "end"]:

 score = state["score"]
 count = state.get("revise_count", 0)
 traj = state.get("trajectory", [])
 fatal = state.get("fatal_issues") or []

 if count >= MAX_REVISE:
 return "end"

 if fatal:
 return "reviser"

 if score >= PASS_SCORE:
 return "end"

 if (
 STALL_STOP
 and len(traj) >= 2
 and traj[-1]["score"]
 < traj[-2]["score"]
 ):
 return "end"

 return "reviser"

这个函数其实就是：

今天整个图最核心的控制器。

可以翻译成人话：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


修改次数到了吗？
 ↓
 是 → END

存在硬伤吗？
 ↓
 是 → reviser

分数达标了吗？
 ↓
 是 → END

这一轮变差了吗？
 ↓
 是 → END

否则
 ↓
 reviser

二十三、为什么条件顺序很重要

注意：

1
2
3
4
5


if count >= MAX_REVISE:
 return "end"

if fatal:
 return "reviser"

这不是随便排列的。

因为假设：

1

fatal_issues 一直存在

那么如果没有：

1

MAX_REVISE

系统可能：

1
2
3
4
5
6
7
8
9


reviser
→
critic
→
reviser
→
critic
→
...

无限循环。

所以：

成本上限必须能够最终把循环截断。

这就是 MAX_REVISE 的真正意义：

1
2


不是质量规则
而是成本规则

二十四、为什么 `MAX_REVISE` 必须存在

Self-Refine 如果只有：

1
2
3


没达到标准
 ↓
继续修改

理论上可以：

1

无限继续

例如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


critic
 ↓
reviser
 ↓
critic
 ↓
reviser
 ↓
critic
 ↓
...

每一轮都要调用模型。

所以：

1

MAX_REVISE = 3

本质是在声明：

系统最多允许自动修改几次。

这不是“模型觉得够了”。

而是：

程序给模型设置了硬边界。

二十五、为什么不能用 `<=` 检测停滞

原本容易写：

1

traj[-1]["score"] <= traj[-2]["score"]

意思是：

1
2
3


没有提高
 ↓
停

但这样会误杀一种情况：

前几轮没有变好。

但不能因此推导：

1

以后也不会变好

所以改成：

1

traj[-1]["score"] < traj[-2]["score"]

只在：

1

7 → 6

这种真正变差的时候停。

于是两个出口开始分工：

1
2
3
4
5


score 下降
 → STALL_STOP

修改次数达到上限
 → MAX_REVISE

可以把它们分别理解成：

1
2
3


质量保护
+
成本保护

二十六、为什么这两个条件测试时会互相掩盖

假设：

1

7 → 8 → 7

原本想测试：

1

MAX_REVISE = 3

但是第三轮分数：

1

7 < 8

已经触发了：

1

STALL_STOP

于是直接：

1

END

最终：

1

revise_count = 2

根本没走到：

1

MAX_REVISE = 3

所以：

一个机制是否正确，不能只看最终“停了”。

因为你还要知道：

到底是哪一个出口让它停下来的？

二十七、所以 `forced` 模式是干什么的

代码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


MODE = (
 sys.argv[1]
 if len(sys.argv) > 1
 else "normal"
)

FORCED = MODE == "forced"

PASS_SCORE = (
 11
 if FORCED
 else 8
)

STALL_STOP = (
 not FORCED
 and os.getenv("STALL", "1") != "0"
)

普通模式：

1
2


PASS_SCORE = 8
STALL_STOP = True

forced 模式：

1
2


PASS_SCORE = 11
STALL_STOP = False

而评分合法范围只有：

1

1 ~ 10

所以：

1
2


最高只能 10
目标是 11

意味着：

这一轮不可能因为“达标”结束。

同时：

1

STALL_STOP = False

又关闭了停滞出口。

这样剩下的主要出口就只剩：

1

MAX_REVISE

于是才能干净地测试：

1

次数用尽

这就是今天很重要的测试思想：

测试一个出口时，把其他出口尽量关掉。

二十八、为什么不能单纯依赖 LLM 运行来测试条件边

因为：

1
2
3


调用 LLM
+
测试条件边

成本高，而且结果有随机性。

但是：

1

route_after_critic(state)

其实是纯逻辑。

给它：

1
2
3
4
5
6
7
8


{
 "score": 7,
 "revise_count": 1,
 "trajectory": [
 {"score": 7},
 {"score": 7},
 ],
}

就可以直接得到：

1

reviser

完全不需要调用模型。

所以可以写：

1
2
3
4
5
6
7
8
9


def mk(score, count, scores):
 return {
 "score": score,
 "revise_count": count,
 "trajectory": [
 {"score": s}
 for s in scores
 ],
 }

二十九、直接测试“平局”这个特殊情况

例如：

1
2
3
4
5
6
7
8
9


(
 "★ 平局(验证 < 的那行)",
 mk(
 7,
 1,
 [7, 7],
 ),
 "reviser",
)

现在：

1
2


上一轮 = 7
这一轮 = 7

使用：

1

<

那么：

1
2
3


7 < 7
↓
False

所以：

1
2
3


不会触发停滞
↓
reviser

但如果代码写成：

1

<=

则：

1
2
3
4
5


7 <= 7
↓
True
↓
end

所以这一条测试是非常好的：

可证伪测试。

因为错误版本必然失败。

三十、`test_router.py` 为什么可以做到 0 成本

完整逻辑：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


fail = 0

print(f"[STALL_STOP={stall}]")

for name, st, expect in cases:
 got = rg.route_after_critic(st)

 ok = got == expect

 print(
 f"{'✅' if ok else '❌'} "
 f"{name}: "
 f"期望 {expect}, "
 f"实际 {got}"
 )

 fail += (not ok)

print(
 f"\n"
 f"{'全部通过' if not fail else f'{fail} 项失败'}"
)

没有：

1

llm.invoke(...)

没有：

1

API

所以：

1
2


0 token
0 调用费用

但仍然可以验证：

1
2
3
4
5
6


达标出口
次数出口
停滞出口
平局
正常进步
单轮场景

这就是今天开始形成的一个很重要的习惯：

纯函数逻辑优先用确定性测试，不要拿 LLM 运行充当单元测试。

三十一、但单测全绿也不代表整个图一定正确

这里还有一层。

你现在测试的是：

1

route_after_critic()

假设：

1

7/7 全部通过

说明：

这个函数在这些输入下是对的。

但还不能推出：

线上 Graph 一定按这个函数运行。

因为还存在：

1
2
3


函数正确
 ↓
接线错误

比如真实构图：

1
2
3
4
5
6
7
8


builder.add_conditional_edges(
 "critic",
 route_after_critic,
 {
 "reviser": "reviser",
 "end": END,
 },
)

如果这里写错了，单独的 route_after_critic() 即使 100% 正确，线上依然可能错误。

所以：

1

函数层

和：

1

接线层

不是一回事。

三十二、再看构图

代码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


def build_graph():
 builder = StateGraph(RState)

 builder.add_node(
 "generator",
 generator,
 )

 builder.add_node(
 "critic",
 critic,
 )

 builder.add_node(
 "reviser",
 reviser,
 )

 builder.add_edge(
 START,
 "generator",
 )

 builder.add_edge(
 "generator",
 "critic",
 )

 builder.add_conditional_edges(
 "critic",
 route_after_critic,
 {
 "reviser": "reviser",
 "end": END,
 },
 )

 builder.add_edge(
 "reviser",
 "critic",
 )

 return builder.compile()

先看固定边：

1
2
3
4
5


START
 ↓
generator
 ↓
critic

这部分没有选择。

三十三、然后是最核心的条件边

1
2
3
4
5
6
7
8


builder.add_conditional_edges(
 "critic",
 route_after_critic,
 {
 "reviser": "reviser",
 "end": END,
 },
)

可以拆成：

1
2
3
4
5
6
7
8
9


critic
 ↓
route_after_critic
 ↓
返回一个字符串
 ↓
查 path_map
 ↓
真正去哪个节点

也就是：

1
2
3
4
5
6
7
8
9


critic
 ↓
route_after_critic(state)
 ↓
┌────────────┬─────────────┐
│ "reviser" │ "end" │
└─────┬──────┴──────┬──────┘
 ↓ ↓
 reviser END

所以：

模型本身并没有直接调用 reviser()。

模型产生的是数据：

1
2
3


score
issues
...

程序再根据这些数据决定：

1

reviser

还是：

1

END

三十四、最后一条边：`reviser → critic`

代码：

1
2
3
4


builder.add_edge(
 "reviser",
 "critic",
)

这条边就是整个循环真正闭合的地方。

没有它：

1
2
3
4
5
6
7


generator
 ↓
critic
 ↓
reviser
 ↓
结束

那就只能修改一次。

有了它：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


generator
 ↓
critic
 ↓
reviser
 ↓
critic
 ↓
reviser
 ↓
critic
 ↓
...

再由：

1

route_after_critic()

决定什么时候退出。

因此可以把：

1
2
3
4


builder.add_edge(
 "reviser",
 "critic",
)

理解成：

反思循环的回边。

三十五、把整个图重新画一次

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


 ┌──────────────┐
 │ generator │
 │ 生成初稿 │
 └──────┬───────┘
 ↓
 ┌──────────────┐
 │ critic │
 │ score │
 │ issues │
 │ fatal_issues │
 └──────┬───────┘
 ↓
 ┌─────────────────────┐
 │ route_after_critic │
 └─────────┬───────────┘
 ┌────┴────┐
 │ │
 ↓ ↓
 reviser END
 │
 ↓
 critic
 │
 └────────────→ ...

所以今天整个图真正的循环关系其实就是：

1
2
3
4
5
6
7


critic
 ↓
条件边
 ↓
reviser
 ↓
critic

三十六、初始化 State

代码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


INITIAL = {
 "topic": "为什么 Agent 需要记忆系统",

 "draft": "",
 "score": 0,
 "issues": [],
 "fatal_issues": [],
 "revise_count": 0,

 "trajectory": [],

 "best_draft": "",
 "best_score": 0,
}

这里提前把 State 的字段初始化好。

例如：

1

draft = ""

意味着：

现在还没有初稿。

1

score = 0

意味着：

现在还没有评审。

1

trajectory = []

意味着：

现在还没有任何历史。

1

revise_count = 0

意味着：

还没有进行修改。

这和 Day2 的 State 初始化思想一样：

节点运行时如果需要读取某个字段，就应该提前让这个字段有明确初始状态。

三十七、完整运行：先启动 Graph

代码：

1

graph = build_graph()

这里做的事情就是：

1
2
3
4
5
6
7
8
9


State Schema
 +
节点
 +
边
 ↓
compile()
 ↓
可执行 Graph

所以 build_graph() 负责的是：

定义图的结构。

而：

1

graph.stream(...)

才是真正运行。

三十八、为什么这里同时拿 `updates` 和 `values`

代码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


for mode, chunk in graph.stream(
 INITIAL,
 stream_mode=["updates", "values"],
):

 if mode == "updates":
 for node_name in chunk:
 chain.append(node_name)

 elif mode == "values":
 final_state = chunk

这里一次运行同时拿两类信息：

1
2
3
4
5
6
7


updates
 ↓
节点更新了什么

values
 ↓
当前完整 State

今天真正需要两个东西：

1
2
3
4
5


第一：
节点到底怎么走？

第二：
最后 State 是什么？

于是：

1
2
3
4
5
6
7


updates
→
流转链

values
→
最终状态

这样避免为了拿不同信息而重新运行第二次。

三十九、为什么“同一次运行”很重要

LLM 是动态系统。

比如：

1
2
3
4
5


第一次运行：
7 → 8 → 7

第二次运行：
7 → 8

这两个结果可能完全不同。

因此不能：

1
2
3


第一次运行拿轨迹
+
第二次运行拿最终 State

然后假设：

1

它们属于同一个实验

实际上不是。

所以现在：

1
2
3
4


graph.stream(
 INITIAL,
 stream_mode=["updates", "values"],
)

一次运行同时拿：

1
2
3


updates
+
values

这样：

所有观察数据都来自同一次实验。

这是测试动态 Agent 时非常重要的一点。

四十、最后怎么输出分数轨迹

代码：

1
2
3
4
5
6
7
8


traj = out["trajectory"]

for t in traj:
 print(
 f"第 {t['round']} 轮: "
 f"{t['score']} 分, "
 f"{t['draft_len']} 字"
 )

于是：

1
2
3


第 0 轮：7 分，243 字
第 1 轮：8 分，400 字
第 2 轮：7 分，645 字

这些信息就能让人真正看到：

1

系统到底发生了什么

而不是只知道：

1

程序最后 END 了

这也是为什么：

1

trajectory

不仅是业务数据，也是非常重要的：

调试数据。

四十一、今天一个非常值得注意的现象：分数提高，不代表内容一定变好

例如：

1

7 → 8

表面上看：

1

变好了

但是实际可能是：

1
2
3
4
5
6
7


critic 要求“增加数据”
 ↓
reviser 编了一个数据
 ↓
文本形式更具体
 ↓
评分提高

所以：

1

score ↑

不能自动推出：

1

真实质量 ↑

这就是今天最重要的发现之一：

Self-Refine 会优化评分标准，但评分标准如果不能覆盖真实质量，就可能被“钻空子”。

四十二、这就是为什么需要硬门槛

把：

1

score

和：

1

fatal_issues

分开之后，逻辑变成：

1
2
3
4
5
6
7
8
9


score = 9
fatal = []
 ↓
可以通过

score = 9
fatal = ["数据无来源"]
 ↓
不能通过

所以：

1

score

是：

软质量指标

而：

1

fatal_issues

是：

硬约束

两个不能互相替代。

四十三、但当前 `fatal_issues` 这条数据流要特别注意

原始 Day3 代码已经有：

1
2
3


class Critique(BaseModel):
 ...
 fatal_issues: list[str]

路由也有：

1

fatal = state.get("fatal_issues") or []

但如果 RState 没有：

1

fatal_issues: list[str]

同时 critic() 也没有：

1

"fatal_issues": c.fatal_issues

那么这条链就没有真正接通：

1
2
3
4
5
6
7


Critique
 ↓
fatal_issues
 X
State
 ↓
route

所以这里一定要分清：

代码里写了这个名字，不等于这个字段真的参与了 State 流动。

完整接通以后才应该是：

1
2
3
4
5
6
7
8
9


Critique.fatal_issues
 ↓
critic()
 ↓
State.fatal_issues
 ↓
route_after_critic()
 ↓
控制流

这也是今天特别重要的一类工程问题：

定义 ≠ 数据流 ≠ 控制流。

四十四、把今天的 Data-flow 单独画出来

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


topic
 ↓
generator
 ↓
draft
 ↓
critic
 ↓
┌───────────────────────┐
│ score │
│ issues │
│ fatal_issues │
│ trajectory │
│ best_score │
│ best_draft │
└───────────┬───────────┘
 ↓
 State
 ↓
 reviser
 ↓
 new draft
 ↓
 critic

这里主要关注：

数据产生以后去了哪里。

四十五、再把 Control-flow 单独画出来

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


critic
 ↓
route_after_critic
 │
 ├── count >= MAX_REVISE
 │ ↓
 │ END
 │
 ├── fatal
 │ ↓
 │ reviser
 │
 ├── score >= PASS_SCORE
 │ ↓
 │ END
 │
 ├── score 下降
 │ ↓
 │ END
 │
 └── 其他
 ↓
 reviser

所以：

1

Data-flow

告诉我们：

发生了什么。

而：

1

Control-flow

告诉我们：

接下来去哪。

这两个概念今天需要彻底分开。

四十六、今天最值得记住的整体模型

以前容易把 Self-Refine 想成：

1
2
3
4
5
6
7


模型
 ↓
修改
 ↓
模型
 ↓
修改

现在应该理解成：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


 State
 │
 ↓
 ┌───────┐
 │ critic│
 └───┬───┘
 │
 产生结构化评审数据
 │
 ↓
 route_after_critic
 │
 ┌──────────┼───────────┐
 ↓ ↓ ↓
 END reviser END
 │
 ↓
 draft
 │
 └────→ critic

真正的核心不是：

1

模型自己反思

而是：

模型产生结构化判断，State 保存判断，程序根据判断控制循环。

四十七、最终可以把 Day3 压缩成四个概念

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


① Critique
 → 结构化评价

② Revise
 → 根据评价重写

③ Route
 → 决定继续还是结束

④ Guard
 → 防止无限循环、质量回退和硬伤放行

于是：

1
2
3
4
5
6
7


Critique
 ↓
State
 ↓
Route
 ↓
Revise / END

这就是今天整张图的骨架。

四十八、完整代码

下面只保留 Day3 的核心代码，省略 import 部分。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


# ══════════ 0. 配置 ══════════

MODEL_NAME = "deepseek-v4-flash"
BASE_URL = "https://api.deepseek.com"
API_KEY = os.getenv("DEEPSEEK_API_KEY")

MODE = sys.argv[1] if len(sys.argv) > 1 else "normal"
FORCED = MODE == "forced"

PASS_SCORE = 11 if FORCED else 8
MAX_REVISE = 3

STALL_STOP = (
 not FORCED
 and os.getenv("STALL", "1") != "0"
)

llm = ChatOpenAI(
 model=MODEL_NAME,
 base_url=BASE_URL,
 api_key=API_KEY,
 temperature=0,
)

这里主要是运行配置：

1
2
3
4


MODE
PASS_SCORE
MAX_REVISE
STALL_STOP

其中：

1

PASS_SCORE

决定多少分可以结束。

1

MAX_REVISE

决定最多改几次。

1

STALL_STOP

决定是否启用质量回退出口。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


# ══════════ 1. Critique + State ══════════

class Critique(BaseModel):
 score: int = Field(
 ge=1,
 le=10,
 description="1-10分，8分及以上达标",
 )

 issues: list[str] = Field(
 default_factory=list,
 description="软问题，影响分数",
 )

 fatal_issues: list[str] = Field(
 default_factory=list,
 description=(
 "硬伤：编造/无来源数据、"
 "事实错误、违规内容。"
 "只要非空，无论多少分都不达标"
 ),
 )

 passed: bool = Field(
 description="是否达标",
 )


class RState(MessagesState):
 topic: str
 draft: str
 score: int
 issues: list[str]
 fatal_issues: list[str]
 revise_count: int

 trajectory: Annotated[
 list,
 operator.add,
 ]

 best_draft: str
 best_score: int

这一块定义：

1
2
3


模型评价的数据结构
+
Graph 运行的数据状态

两者不要混淆。

1
2
3
4
5


Critique
 → 模型一次评审的结果

RState
 → 整个循环长期保存的状态

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


# ══════════ 2. generator ══════════

def generator(state: RState) -> dict:

 r = llm.invoke(
 f"请写一篇约200字的中文短文，"
 f"主题：{state['topic']}。"
 f"只输出正文。"
 )

 draft = str(r.content)

 return {
 "draft": draft,
 "revise_count": 0,
 "best_draft": draft,
 "best_score": 0,
 }

这里：

1
2
3
4
5


topic
 ↓
LLM
 ↓
draft

同时初始化：

1
2
3


revise_count
best_draft
best_score

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39


# ══════════ 3. critic ══════════

JUDGE_SYS = """你是严格但公正的中文写作评审。

评分维度：
① 观点清晰度
② 论据支撑
③ 结构层次
④ 表达流畅

评分标准：
8分及以上为达标。

issues 最多3条，
每条不超过15字。

输出格式：
只输出一个 JSON 对象，形如：

{
 "score": 7,
 "issues": ["第二段缺少具体例子"],
 "fatal_issues": [],
 "passed": false
}
"""


def _parse_critique(raw) -> Critique:

 if not isinstance(raw, Critique):
 raw = Critique.model_validate(raw)

 if not (1 <= int(raw.score) <= 10):
 raise ValueError(
 f"score 越界:{raw.score}"
 )

 return raw

这一块：

1
2
3
4
5


Prompt
+
Schema
+
程序校验

共同组成 critic 的输入输出契约。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88


def critic(state: RState) -> dict:

 judge = llm.with_structured_output(
 Critique,
 method="json_mode",
 )

 prompt = (
 f"{JUDGE_SYS}\n\n"
 f"文稿:\n{state['draft']}"
 )

 c = None

 for attempt in range(3):
 try:
 c = _parse_critique(
 judge.invoke(prompt)
 )
 break
 except Exception as e:
 print(
 f"[warn] 第{attempt + 1}次评审解析失败"
 )

 if c is None:
 c = Critique(
 score=1,
 issues=[
 "评审解析失败，无法判断"
 ],
 fatal_issues=[],
 passed=False,
 )

 passed_by_code = (
 c.score >= PASS_SCORE
 )

 if passed_by_code != c.passed:
 print(
 "[warn] 模型 passed "
 "与程序阈值不一致"
 )

 score = int(c.score)

 best_score = state.get(
 "best_score",
 0,
 )

 best_draft = state.get(
 "best_draft",
 "",
 )

 if score > best_score:
 best_score = score
 best_draft = state["draft"]

 entry = {
 "round": len(
 state.get(
 "trajectory",
 [],
 )
 ),
 "score": score,
 "issues": c.issues,
 "fatal_issues": c.fatal_issues,
 "draft_len": len(
 state["draft"]
 ),
 "draft_head": (
 state["draft"][:60]
 .replace("\n", " ")
 ),
 }

 return {
 "score": score,
 "issues": c.issues,
 "fatal_issues": c.fatal_issues,
 "trajectory": [entry],
 "best_score": best_score,
 "best_draft": best_draft,
 }

这一块是今天最重要的节点。

它完整做：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


读取 draft
 ↓
调用 critic
 ↓
解析结构化结果
 ↓
业务校验
 ↓
程序重新计算 passed
 ↓
更新 best
 ↓
追加 trajectory
 ↓
写回 State

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


# ══════════ 4. reviser ══════════

def reviser(state: RState) -> dict:

 r = llm.invoke(
 "请根据评审意见改进以下文稿。"
 "保持主题不变，只输出改进后的正文。\n\n"
 f"原稿:\n{state['draft']}\n\n"
 f"普通问题:\n{state['issues']}\n\n"
 f"硬伤:\n"
 f"{state.get('fatal_issues') or []}"
 )

 draft = str(r.content)

 n = (
 state.get(
 "revise_count",
 0,
 )
 + 1
 )

 return {
 "draft": draft,
 "revise_count": n,
 }

这里和 critic 完全相反：

1
2
3
4
5
6
7
8
9


critic
 ↓
产生评价

reviser
 ↓
消费评价
 ↓
产生新稿

所以：

一个节点负责观察，一个节点负责修改。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


# ══════════ 5. 条件边 ══════════

def route_after_critic(
 state: RState,
) -> Literal[
 "reviser",
 "end",
]:

 score = state["score"]

 count = state.get(
 "revise_count",
 0,
 )

 traj = state.get(
 "trajectory",
 [],
 )

 fatal = state.get(
 "fatal_issues"
 ) or []

 if count >= MAX_REVISE:
 return "end"

 if fatal:
 return "reviser"

 if score >= PASS_SCORE:
 return "end"

 if (
 STALL_STOP
 and len(traj) >= 2
 and traj[-1]["score"]
 < traj[-2]["score"]
 ):
 return "end"

 return "reviser"

这是控制流核心。

注意这里没有：

1

llm.invoke(...)

所以它本质上是：

纯函数控制器。

这也是为什么它非常适合单元测试。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46


# ══════════ 6. 构图 ══════════

def build_graph():

 builder = StateGraph(RState)

 builder.add_node(
 "generator",
 generator,
 )

 builder.add_node(
 "critic",
 critic,
 )

 builder.add_node(
 "reviser",
 reviser,
 )

 builder.add_edge(
 START,
 "generator",
 )

 builder.add_edge(
 "generator",
 "critic",
 )

 builder.add_conditional_edges(
 "critic",
 route_after_critic,
 {
 "reviser": "reviser",
 "end": END,
 },
 )

 builder.add_edge(
 "reviser",
 "critic",
 )

 return builder.compile()

这部分就是把前面的代码真正组成 Graph：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


START
 ↓
generator
 ↓
critic
 ↓
route
 ├── END
 └── reviser
 ↓
 critic

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


# ══════════ 7. INITIAL ══════════

INITIAL = {
 "topic": "为什么 Agent 需要记忆系统",
 "draft": "",
 "score": 0,
 "issues": [],
 "fatal_issues": [],
 "revise_count": 0,
 "trajectory": [],
 "best_draft": "",
 "best_score": 0,
}

这是图真正运行前的初始 State。

整个循环中的所有数据，最后都是围绕这里不断更新。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


# ══════════ 8. 运行 ══════════

graph = build_graph()

chain = []
final_state = None

for mode, chunk in graph.stream(
 INITIAL,
 stream_mode=[
 "updates",
 "values",
 ],
):

 if mode == "updates":

 for node_name in chunk:
 chain.append(node_name)

 elif mode == "values":

 final_state = chunk

这里的重点不是语法，而是：

1
2
3
4
5


updates
 → 看图怎么走

values
 → 看 State 变成什么

一次运行同时观察：

1
2
3


Control-flow
+
State

这样才可以把：

1

程序到底走了哪？

和：

1

State 最后变成了什么？

对应起来。

总结

今天的图表面上只是：

1
2
3
4


generator
→ critic
→ reviser
→ critic

但真正需要掌握的是里面的四层关系：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


第一层：Critique
 LLM 负责评价

第二层：State
 保存评价结果和历史

第三层：Route
 程序根据 State 决定下一步

第四层：Guard
 防止无限循环、质量回退和硬伤放行

最终就变成：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


 State
 │
 ↓
 ┌───────┐
 │ critic│
 └───┬───┘
 │
 结构化评价结果
 │
 ↓
 route_after_critic
 │
 ┌──────┴──────┐
 ↓ ↓
 reviser END
 │
 ↓
 critic
 │
 └──────────→ ...

所以今天真正理解的不是：

“Self-Refine 就是让模型自己修改。”

而是：

“LLM 负责产生评价，State 负责保存评价，程序负责决定控制流，停止条件负责限制自主循环。”

而今天最需要记住的一个工程规律是：

模型输出可以参与决策，但最终的控制权应该落在程序定义的边界上。

Supervisor 模式：让一个 Agent 负责调度，多个 Worker 负责执行

Tue, 15 Sep 2026 07:16:45 +0800

W7-Day2｜Supervisor 模式：让一个 Agent 负责调度，多个 Worker 负责执行

昨天主要是在画 Supervisor 模式的图，今天开始真正把它写成代码。

今天的 Demo 是一个 Supervisor + 3 个 Worker 的多 Agent 流程：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


 ┌──────────────┐
 │ supervisor │
 │ 决定下一步 │
 └──────┬───────┘
 │
 ┌─────────────┼─────────────┐
 ▼ ▼ ▼
 researcher writer reviewer
 │ │ │
 └─────────────┴─────────────┘
 │
 ▼
 supervisor
 │
 FINISH → END

三个 Worker 分工：

1
2
3


researcher → 查资料
writer → 写文章
reviewer → 审文章

最重要的不是“有三个 Agent”，而是：

Worker 负责执行，Supervisor 负责决定下一步。

所以实际运行不是一条固定流水线：

1

researcher → writer → reviewer

而是一个循环：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


supervisor
 ↓
researcher
 ↓
supervisor
 ↓
writer
 ↓
supervisor
 ↓
reviewer
 ↓
supervisor
 ↓
FINISH
 ↓
END

Worker 干完以后必须重新回到 Supervisor。

一、先看今天的 State

今天的 State：

1
2
3


class SuperState(MessagesState):
 next: str
 rounds: int

在 MessagesState 自带的 messages 之外，又增加两个字段：

1
2
3


messages → 工作内容和历史
next → Supervisor 的下一步决策
rounds → 已经循环多少次

这三个字段的职责并不一样。

messages：数据流

它保存整个任务的上下文。

例如：

1
2
3
4
5
6
7


用户：写一篇 LangGraph 介绍

researcher：
LangGraph 是……

writer：
LangGraph 是一个……

Worker 每次都是从这里读取前面的工作结果。

next：控制流

例如：

1

next = "writer"

表示：

下一步执行 writer。

所以 next 是给图的控制逻辑看的，而不是业务内容。

rounds：安全控制

Supervisor 是循环：

1

Supervisor → Worker → Supervisor → Worker → ...

所以必须记录轮数，防止模型一直循环。

二、为什么要有两个 LLM 变量

代码：

1
2


llm = make_llm()
router_llm = make_llm()

当前它们使用的是同一个模型，但职责不同：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


llm
 ↓
Worker
 ↓
真正干活


router_llm
 ↓
Supervisor
 ↓
决定下一步

Worker 的任务是：

1

查资料 / 写文章 / 审稿

Supervisor 的任务是：

1

现在应该找谁？

虽然都是 LLM，但从系统设计上已经是两个不同角色。

三、MEMBERS：为什么专门维护一个名单

1
2
3
4
5


MEMBERS = [
 "researcher",
 "writer",
 "reviewer"
]

这个列表相当于 Supervisor 的“花名册”。

后面很多代码都依赖它：

1
2
3
4
5
6
7


Supervisor 能选择谁
 ↓
条件边能连接到谁
 ↓
Worker 的名字是否合法
 ↓
Worker 回边连接给谁

所以它最好成为：

单一事实来源。

以后增加：

1

"fact_checker"

就应该优先改这里，而不是到程序各处手写名字。

四、Route：Supervisor 怎么把“思考结果”交给程序

接下来：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


class Route(BaseModel):
 next: Literal[
 "researcher",
 "writer",
 "reviewer",
 "FINISH"
 ]

 reason: str = Field(
 default="",
 description="一句话理由, 方便调试"
 )

这里解决的是一个核心问题：

模型说完“下一步该谁”以后，程序怎么可靠地拿到这个答案？

不能让模型随便返回一句：

1

我觉得现在应该让 writer 处理一下……

而是约束成：

1
2
3
4


{
 "next": "writer",
 "reason": "researcher 已经完成资料整理"
}

其中真正影响图运行的是：

1

decision.next

而 reason 主要用于调试。

因此这里形成了一条链：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


LLM
 ↓
结构化输出
 ↓
Route
 ↓
decision.next
 ↓
State["next"]
 ↓
条件边
 ↓
真正执行哪个节点

五、为什么最后用 `json_mode`

最开始写：

1

router_llm.with_structured_output(Route)

但实际跑 DeepSeek 时，默认路径触发了 json_schema，返回：

1

This response_format type is unavailable now

后来又试了：

1

method="function_calling"

结果变成：

1

Thinking mode does not support this tool_choice

最后通过探针验证，当前环境真正可用的是：

1
2
3
4


router = router_llm.with_structured_output(
 Route,
 method="json_mode"
)

所以今天这里真正学到的并不是“DeepSeek 不支持结构化输出”。

而是：

同一个结构化输出接口，底层可能走完全不同的协议路径。

可以画成：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


with_structured_output
 │
 ├── json_schema
 │ ↓
 │ 当前环境不支持
 │
 ├── function_calling
 │ ↓
 │ thinking mode 拒绝 tool_choice
 │
 └── json_mode
 ↓
 可用

所以以后遇到这类兼容问题，先写一个最小 Probe，确认模型实际支持什么，不要凭印象猜。

六、Worker 为什么用工厂函数创建

这部分源码初看有一点绕：

1
2
3
4
5
6
7
8
9


def make_worker(name, tools, prompt):
 agent = create_react_agent(
 llm,
 tools,
 prompt=prompt
 )

 def node(state):
 ...

它其实是在做一件事：

把“创建 Worker”这件事封装成一个模板。

然后：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


worker_nodes = {
 "researcher": make_worker(
 "researcher",
 [web_search],
 WORKER_PROMPTS["researcher"]
 ),

 "writer": make_worker(
 "writer",
 [],
 WORKER_PROMPTS["writer"]
 ),

 "reviewer": make_worker(
 "reviewer",
 [],
 WORKER_PROMPTS["reviewer"]
 ),
}

最终得到三个不同的 Worker：

1
2
3


researcher
writer
reviewer

它们本质上结构类似，只是：

1
2
3


名字不同
Prompt 不同
工具不同

所以这里的工厂函数主要是为了：

避免重复写三遍几乎一样的 Worker 创建代码。

七、三个 Worker 为什么职责不同

Prompt：

1
2
3
4
5


WORKER_PROMPTS = {
 "researcher": "你是研究员……",
 "writer": "你是写手……",
 "reviewer": "你是审稿人……",
}

工具：

1
2
3


researcher → web_search
writer → 无工具
reviewer → 无工具

于是职责就很清楚：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


researcher
 ↓
产生资料

writer
 ↓
消费资料，产生文章

reviewer
 ↓
消费文章，产生审稿结果

这里实际上已经有一个很清楚的数据加工链：

1
2
3
4
5
6
7


原始任务
 ↓
资料
 ↓
文章
 ↓
评审结果

Supervisor 只是负责控制这个加工链什么时候进入下一阶段。

八、真正执行 Worker 时，State 是怎么进去的

Worker 的核心代码：

1
2
3


result = agent.invoke({
 "messages": state["messages"]
})

这里特别容易误解。

它不是：

1

把整个 LangGraph State 原封不动塞给 Agent

而是：

1
2
3
4
5


LangGraph State
 │
 └── state["messages"]
 ↓
 Worker Agent

所以 Worker 真正拿到的核心数据是：

当前 State 中的消息历史。

如果此时 State 是：

1
2
3


messages:
 用户要求
 researcher 结果

那么 writer 就可以根据这些内容继续工作。

九、Worker 干完以后为什么还要重新包装一次消息

Worker 内部 Agent 最后得到：

1
2


last = result["messages"][-1]
text = str(last.content)

接着：

1
2
3
4
5
6
7
8


return {
 "messages": [
 HumanMessage(
 content=f"[{name} 交活]\n{text}",
 name=name
 )
 ]
}

这一步非常重要。

因为 Worker 内部的最终结果不能只停留在它自己的 Agent 里。

它必须进入 LangGraph 的 State。

于是：

1
2
3
4
5
6
7


Worker 内部
 ↓
生成结果
 ↓
包装为 HumanMessage
 ↓
写回 State.messages

同时增加：

1

name=name

于是 Supervisor 下一轮就知道：

1

这是 researcher 交来的

而不是只能看到一条匿名消息。

十、这里可以第一次把“逻辑流”和“数据流”放在一起看

现在完整看一次 researcher：

逻辑流

1
2
3
4
5
6
7


supervisor
 ↓
decision.next = researcher
 ↓
条件边
 ↓
researcher

这是：

决定谁执行。

数据流

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


State.messages
 ↓
researcher Agent
 ↓
web_search
 ↓
研究结果
 ↓
HumanMessage(name="researcher")
 ↓
写回 State.messages

这是：

决定执行时拿什么，执行后留下什么。

两条流最后重新汇合：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


 State
 ┌───────────────┐
 │ messages │
 │ next │
 │ rounds │
 └───────┬───────┘
 │
 ┌───────────▼───────────┐
 │ supervisor │
 │ 决定 next │
 └───────────┬───────────┘
 │
 控制流
 │
 ▼
 Worker
 │
 数据流
 │
 ▼
 写回 messages
 │
 └────→ supervisor

这是今天我认为理解 Supervisor 最重要的一张图。

十一、Supervisor 节点到底在做什么

源码核心：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


def supervisor_node(state):
 rounds = state.get("rounds", 0) + 1

 if rounds > MAX_ROUNDS:
 return {
 "next": "FINISH",
 "rounds": rounds,
 ...
 }

 msgs = [
 SystemMessage(
 content=SUPERVISOR_PROMPT
 )
 ] + state["messages"]

 decision = router.invoke(msgs)

 return {
 "next": decision.next,
 "rounds": rounds,
 }

可以拆成四步。

第一步：计算轮数

1

rounds += 1

第二步：检查是否超限

如果已经超限：

1

直接 FINISH

连 LLM 都不再调用。

这是为了避免已经知道要结束了，还白花一轮模型费用。

第三步：把“Supervisor 的规则 + 当前消息历史”交给 LLM

1
2
3


msgs = [
 SystemMessage(content=SUPERVISOR_PROMPT)
] + state["messages"]

模型看到：

1
2
3


自己的职责
+
前面的工作历史

第四步：把模型决定写回 State

1
2
3
4


return {
 "next": decision.next,
 "rounds": rounds,
}

所以 Supervisor 这一轮的作用其实非常简单：

读取 State → 决定下一步 → 修改 State。

十二、条件边：模型只负责“说去哪”，图负责“真的去”

路由函数：

1
2
3
4
5
6
7
8


def route_from_supervisor(state):
 nxt = state.get("next") or "FINISH"

 return (
 nxt
 if nxt in MEMBERS or nxt == "FINISH"
 else "FINISH"
 )

然后：

1
2
3
4
5


builder.add_conditional_edges(
 "supervisor",
 route_from_supervisor,
 path_map
)

完整过程其实是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


Supervisor LLM
 ↓
"writer"
 ↓
state["next"]
 ↓
route_from_supervisor()
 ↓
"writer"
 ↓
path_map
 ↓
writer 节点

所以一个非常值得记住的边界是：

LLM 做决策，Graph 执行决策。

模型不是直接调用：

1

writer()

它只是在 State 中留下：

1

next = "writer"

然后 LangGraph 根据图结构真正执行 writer。

十三、为什么 Worker 必须回 Supervisor

这里：

1
2
3
4
5


for name in MEMBERS:
 builder.add_edge(
 name,
 "supervisor"
 )

实际上是整个模式的循环核心。

形成：

1
2
3


researcher ─┐
writer ─┼──→ supervisor
reviewer ─┘

如果没有这组回边：

1
2
3
4
5


supervisor
 ↓
researcher
 ↓
结束

那么 Worker 做完以后，就没有人继续判断下一步。

所以 Supervisor 模式真正的图形是：

1
2
3


Supervisor → Worker
 ↑ │
 └────────┘

直到：

1

Supervisor → FINISH → END

十四、把一次完整运行串起来

现在假设模型做出了一个比较理想的路径：

1
2
3
4
5
6
7
8


supervisor
→ researcher
→ supervisor
→ writer
→ supervisor
→ reviewer
→ supervisor
→ FINISH

状态变化可以粗略理解为：

初始

1
2
3
4
5
6
7
8


messages:
 用户要求

next:
 ""

rounds:
 0

Supervisor 第一次

1
2


next = researcher
rounds = 1

researcher 执行

1
2
3


messages:
 用户要求
 researcher 交活

Supervisor 第二次

读取：

1
2


用户要求
researcher 结果

决定：

1
2


next = writer
rounds = 2

writer 执行

1
2
3
4


messages:
 用户要求
 researcher 结果
 writer 文章

Supervisor 第三次

决定：

1
2


next = reviewer
rounds = 3

reviewer 执行

1
2
3
4
5


messages:
 用户要求
 researcher 结果
 writer 文章
 reviewer 意见

Supervisor 最后决定

1

next = FINISH

于是：

1
2
3


FINISH
 ↓
END

整个过程中：

1

messages

越来越丰富。

而：

1

next

负责控制当前应该去哪。

这就是今天最核心的：

数据流在 State 中积累，控制流围绕 State 动态前进。

十五、为什么要加 MAX_ROUNDS

Supervisor 本质上是动态循环。

例如 reviewer 可能说：

1

文章需要修改

于是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


reviewer
 ↓
writer
 ↓
reviewer
 ↓
writer
 ↓
reviewer
……

如果没有限制，模型可以一直绕下去。

所以：

1

MAX_ROUNDS = 8

相当于：

给模型的自主决策设置一道硬上限。

而且今天特意做了 fallback 模式：

1

MAX_ROUNDS = 1

让流程进入：

1
2
3
4


supervisor
→ researcher
→ supervisor
→ 强制 FINISH

这样才能真正证明兜底逻辑生效，而不是只看代码说“应该能生效”。

十六、今天的一个重要调试经验：两次运行不能拿来互相证明

之前的思路是：

1
2
3
4
5
6
7


stream()
 ↓
拿流转链

invoke()
 ↓
拿最终 State

然后：

1
2


第一次：4 轮
第二次：6 轮

再拿两者比较。

问题是：

它们根本不是同一次运行。

LLM 是动态的，所以即使：

1

temperature = 0

也不能把两个独立运行当成同一个实验。

最后改成：

1
2
3
4


for mode, chunk in graph.stream(
 INITIAL,
 stream_mode=["updates", "values"]
):

于是一次运行同时得到：

1
2


updates → 流程链
values → State 快照

这样才能比较：

1

这一次运行到底发生了什么。

这个思路其实比 Supervisor 本身还通用：

验证动态系统时，尽量让观察数据来自同一次实验。

十七、今天还有一个特别隐蔽的测试坑：空集合

比如：

1
2


for m in delivered:
 assert m.name in MEMBERS

如果：

1

delivered = []

那么：

1
2
3
4
5


循环执行 0 次
↓
assert 执行 0 次
↓
程序不报错

于是你会产生一种错觉：

“检查通过了。”

实际上：

根本没有检查。

所以正确做法是：

1
2
3
4


assert delivered

for m in delivered:
 assert m.name in MEMBERS

先证明：

1

确实存在需要验证的数据

再检查数据是否合法。

这就是今天说的“真空真”。

十八、验证器也可能看错地方

今天还有一个反例。

原本检测工具是否真的被调用，写成：

1
2
3
4


called = any(
 "真身被调用" in str(m.content)
 for m in out["messages"]
)

结果：

1

❌ 工具没有调用

但实际上工具真的调用了。

因为：

1

print(...)

走的是：

1

stdout

而：

1

return ...

才会进入：

1

ToolMessage

也就是：

1
2
3
4
5
6
7
8
9


print
 ↓
终端

return
 ↓
ToolMessage
 ↓
State.messages

这是两条完全不同的数据通道。

所以后面才改成：

1
2
3


CALLS
+
ToolMessage

两个证据一起看。

这个例子让我今天对测试又多了一层认识：

验证器本身也必须建立在正确的数据通道上。

十九、今天最终形成的理解

以前看到这种代码，容易先被很多 API 吓到：

1
2
3
4
5
6
7
8


StateGraph
add_node
add_edge
add_conditional_edges
with_structured_output
create_react_agent
HumanMessage
MessagesState

但今天把它还原成系统以后，其实就是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


 State
 ┌──────────┼──────────┐
 │ │ │
 messages next rounds
 │ │ │
 │ │ │
 ▼ ▼ ▼
 数据流 控制流 安全控制
 │ │
 └────┬─────┘
 ▼
 Supervisor
 │
 决定 next
 │
 ▼
 条件边
 │
 ▼
 Worker
 │
 干自己的活
 │
 ▼
 结果重新写入 State
 │
 └────→ Supervisor

所以今天我真正理解的，不只是：

“Supervisor 可以调度多个 Agent。”

而是：

Supervisor 是一个不断读取 State、修改 State，并依据 State 决定下一跳的动态控制器。

而整个系统可以分成两条主线：

1
2
3
4
5


控制流：
Supervisor → next → 条件边 → Worker → Supervisor

数据流：
messages → Worker → 工作结果 → messages

这两条流最后都通过 State 汇合。

以后再看类似的多 Agent 代码，我觉得可以先问自己两个问题：

第一：谁决定下一步？

第二：上一阶段产生的数据，是通过什么字段传给下一阶段的？

先找到这两个答案，源码就不会再是一堆孤立的 API。

完整 Demo

下面保留今天最终版本的核心代码。

为了方便之后复习，完整 Demo 放在文章最后；省略 import、包安装和断言代码，正文重点放在运行机制和代码结构。

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329


MODEL_NAME = "deepseek-chat"
BASE_URL = "https://api.deepseek.com"
API_KEY = os.getenv("DEEPSEEK_API_KEY")

MODE = sys.argv[1] if len(sys.argv) > 1 else "normal"
MAX_ROUNDS = 1 if MODE == "fallback" else 8
FAULT = os.getenv("FAULT") or None

MEMBERS = [
 "researcher",
 "writer",
 "reviewer"
]


def make_llm(temperature: float = 0):
 return ChatOpenAI(
 model=MODEL_NAME,
 base_url=BASE_URL,
 api_key=API_KEY,
 temperature=temperature,
 )


llm = make_llm()
router_llm = make_llm()


class SuperState(MessagesState):
 next: str
 rounds: int


class Route(BaseModel):
 next: Literal[
 "researcher",
 "writer",
 "reviewer",
 "FINISH"
 ]
 reason: str = Field(
 default="",
 description="一句话理由，方便调试"
 )


router = router_llm.with_structured_output(
 Route,
 method="json_mode"
)


@tool
def web_search(query: str) -> str:
 print(f">>> [web_search] query={query!r}")

 return (
 f"[模拟检索结果] 关于「{query}」："
 "LangGraph 是用于构建有状态多步 Agent 的框架；"
 "核心包括 StateGraph、条件边和持久化能力。"
 )


WORKER_PROMPTS = {
 "researcher": (
 "你是研究员。用 web_search 查资料，"
 "把关键要点整理成 2-3 条，不要写完整文章。"
 ),

 "writer": (
 "你是写手。把对话历史里 researcher "
 "交的资料整合成一篇 300 字左右的中文文章。"
 "只写文章，不要写评论或修改意见。"
 ),

 "reviewer": (
 "你是审稿人。检查上一位 writer 写的文章，"
 "指出事实性、结构、表达上的具体问题。"
 "如果文章已经可以定稿，明确说「可以定稿」。"
 ),
}


def make_worker(name: str, tools: list, prompt: str):
 agent = create_react_agent(
 llm,
 tools,
 prompt=prompt
 )

 def node(state: SuperState) -> dict:
 result = agent.invoke({
 "messages": state["messages"]
 })

 last = result["messages"][-1]
 text = str(last.content)

 if FAULT == "no_deliver":
 return {
 "messages": []
 }

 msg_name = (
 None
 if FAULT == "no_name"
 else name
 )

 return {
 "messages": [
 HumanMessage(
 content=f"[{name} 交活]\n{text}",
 name=msg_name
 )
 ]
 }

 node.__name__ = name
 return node


worker_nodes = {
 "researcher": make_worker(
 "researcher",
 [web_search],
 WORKER_PROMPTS["researcher"]
 ),

 "writer": make_worker(
 "writer",
 [],
 WORKER_PROMPTS["writer"]
 ),

 "reviewer": make_worker(
 "reviewer",
 [],
 WORKER_PROMPTS["reviewer"]
 ),
}


SUPERVISOR_PROMPT = """
你是写作工作室的主编(supervisor)，手下三位成员：

- researcher：负责查资料，只交资料要点，不写正文
- writer：负责把资料整合成一篇结构清晰的中文文章
- reviewer：负责审稿，指出文章的问题

你的职责：每一步只决定“下一步交给谁”。
不要替任何成员干活，不要自己写文章。

标准流程：
researcher 拿资料
→ writer 成稿
→ reviewer 审稿
→ 若有重大问题，可以回 writer 修改
→ 都满意后输出 FINISH

判断依据：
看历史里带名的交活消息。

已经交过活的不必重复派。

只输出一个 JSON 对象，例如：

{
 "next": "researcher",
 "reason": "还没有资料"
}

next 只能是：
researcher / writer / reviewer / FINISH
"""


def supervisor_node(state: SuperState) -> dict:
 rounds = state.get("rounds", 0) + 1

 if rounds > MAX_ROUNDS:
 return {
 "next": "FINISH",
 "rounds": rounds,
 "messages": [
 (
 "assistant",
 f"【已达最大轮数 {MAX_ROUNDS}，强制结束】"
 )
 ],
 }

 msgs = [
 SystemMessage(
 content=SUPERVISOR_PROMPT
 )
 ] + state["messages"]

 decision = router.invoke(msgs)

 print(
 f"[supervisor] round={rounds} "
 f"next={decision.next} "
 f"({decision.reason})"
 )

 return {
 "next": decision.next,
 "rounds": rounds,
 }


def route_from_supervisor(state: SuperState):
 nxt = state.get("next") or "FINISH"

 return (
 nxt
 if nxt in MEMBERS or nxt == "FINISH"
 else "FINISH"
 )


def build_graph():
 builder = StateGraph(SuperState)

 builder.add_node(
 "supervisor",
 supervisor_node
 )

 for name, node in worker_nodes.items():
 builder.add_node(
 name,
 node
 )

 builder.add_edge(
 START,
 "supervisor"
 )

 path_map = {
 member: member
 for member in MEMBERS
 }

 path_map["FINISH"] = END

 builder.add_conditional_edges(
 "supervisor",
 route_from_supervisor,
 path_map
 )

 for name in MEMBERS:
 builder.add_edge(
 name,
 "supervisor"
 )

 return builder.compile()


INITIAL = {
 "messages": [
 (
 "user",
 "写一篇 300 字介绍 LangGraph 的文章，"
 "要求有事实依据"
 )
 ],
 "next": "",
 "rounds": 0,
}


def main():
 graph = build_graph()

 chain = []
 final_state = None

 for mode, chunk in graph.stream(
 INITIAL,
 stream_mode=["updates", "values"]
 ):
 if mode == "updates":
 for node_name in chunk:
 chain.append(node_name)

 elif mode == "values":
 final_state = chunk

 out = final_state

 print(
 "\n[流转链]",
 " → ".join(chain)
 )

 print("\n=== 成品 ===")
 print(
 str(
 out["messages"][-1].content
 )[:400]
 )

 print(
 f"[结果] "
 f"next={out['next']} "
 f"rounds={out['rounds']}"
 )

 mermaid = graph.get_graph().draw_mermaid()

 with open(
 "w7_supervisor_topology.md",
 "w",
 encoding="utf-8"
 ) as f:
 f.write(
 "```mermaid\n"
 + mermaid
 + "\n```\n"
 )


if __name__ == "__main__":
 main()

MemoryGraph + HITL 审批 + 长期记忆端到端验证复盘

Sun, 13 Sep 2026 13:53:21 +0800

LangGraph W6-D6：Checkpoint、HITL 与长期记忆的一次端到端实验

本节目标：把前面学习过的几个能力真正串起来：

checkpoint 持久化：让 Agent 可以跨进程恢复会话

HITL 人工审批：让危险操作执行前需要人工确认

长期记忆：让信息真正脱离某一次会话保存

可验证性：不只看 Agent 说了什么，而是直接检查外部世界的真实状态

这一节对我来说，没有特别多新的 LangGraph API。

真正变化的是：

开始把前面学过的几个机制放到同一个完整系统里思考。

以前更关注的是：

1
2
3


这个 API 怎么用？
这个节点怎么写？
这个图怎么跑？

这一节开始需要进一步问：

1
2
3
4
5


状态保存在哪里？
这个动作为什么允许执行？
人工审批到底停在哪里？
重新启动以后怎么继续？
最后到底有没有真的改变外部世界？

所以最终形成的 Agent 不再只是：

1
2
3
4
5


用户
 ↓
模型
 ↓
工具

而逐渐变成：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


用户
 ↓
Agent 决策
 ↓
判断风险
 ↓
必要时人工审批
 ↓
执行工具
 ↓
改变外部世界
 ↓
验证真实结果

一、为什么 Agent 有了工具以后，需要“审批”？

前面的 Agent 已经可以：

调用工具
保存状态
恢复上下文
跨进程继续执行

但是工具能力越强，另一个问题就越明显：

如果 Agent 可以直接修改外部世界怎么办？

例如：

1
2
3
4


删除文件
发送邮件
修改数据库
写入长期记忆

这些操作和普通查询有一个很重要的区别：

1
2
3
4
5


查询
 ↓
读取外部世界
 ↓
通常没有副作用

而：

1
2
3
4
5


写入 / 删除 / 修改
 ↓
改变外部世界
 ↓
产生副作用

所以真正需要控制的不是：

Agent 能不能调用工具。

而是：

Agent 提出的工具调用，什么时候可以真正执行。

因此可以增加一层权限控制：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


 Agent 决策
 │
 判断工具风险
 │
 ┌──────────┴──────────┐
 │ │
 安全工具 危险工具
 │ │
 直接执行 interrupt
 │
 人工确认
 │
 Command(resume)
 │
 执行工具

这里的 HITL 并不是单纯“弹一个确认框”。

它实际上是在控制：

1

Control Flow

也就是：

这条执行路径到底有没有资格继续往下走。

二、这一天最大的提升：验证方式发生了变化

之前学习 HITL 时，我很自然会用：

1

print("删除文件")

作为工具执行证据。

如果看到：

1

删除文件

就说明工具执行了。

如果没看到：

1

删除文件

就认为工具没有执行。

但这个验证方式其实比较弱。

因为：

1

日志 ≠ 真实状态

日志可能：

漏掉
打错
被误导
只能说明某段代码走到了，而不能完全证明外部状态正确

所以这一节开始把验证标准升级成：

不要只看 Agent 说了什么，也不要只看日志，直接检查外部世界。

例如长期记忆：

批准：

1

alice@x.com

应该存在。

拒绝：

1

X99

不应该存在。

于是最终的验证：

1
2


assert any("alice@x.com" in t for t in texts)
assert not any("X99" in t for t in texts)

这里验证的已经不是：

1

工具有没有打印？

而是：

1
2
3
4
5
6
7


批准
 ↓
外部数据真的发生变化

拒绝
 ↓
外部数据真的没有发生变化

这也是我这一天对测试理解比较明显的一次变化：

1
2
3
4
5
6
7


过程证据
 ↓
日志、print、next、消息数

结果证据
 ↓
直接读取外部数据

如果任务本身有一个明确的外部结果，直接检查结果通常更有说服力。

三、Checkpoint 记忆和长期记忆不是一回事

这是今天最容易混淆的地方之一。

之前已经学过 checkpoint，因此很容易产生一个直觉：

checkpoint 能保存以前的信息，那它是不是就是长期记忆？

不是。

1. checkpoint 保存的是一次执行过程的状态

这一节使用：

1

SqliteSaver

保存 checkpoint。

并且通过：

1

thread_id

区分不同会话。

例如：

1

thread = alice-1

这个槽位里保存：

1
2
3
4
5


消息
状态
执行位置
暂停点
……

因此 checkpoint 更像：

这个 Agent 的某一次会话，现在执行到哪里，以及之前发生过什么。

例如：

1
2
3
4
5
6
7
8


第一次

用户：
我的邮箱是 alice@x.com

 ↓

checkpoint 保存

下一次：

1
2
3
4
5
6
7
8


用户：
我的邮箱是什么？

 ↓

使用同一个 thread_id
 ↓
恢复原来的会话状态

四、长期记忆又是什么？

这次实验另外使用：

1

w6d6_long_term_mem.json

作为一个最小化的长期记忆库。

它和 checkpoint 最大的区别是：

它不属于某一个 thread。

例如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


alice-1
 │
 └──────┐
 ↓
 长期记忆库
 ↑
 │
 ┌──────┘
 │
carol-1

Alice 的会话写进去的信息，Carol 的新会话也可以查询。

所以可以先简单理解成：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


 Agent Memory
 │
 ┌───────────┴───────────┐
 │ │
 checkpoint long-term memory
 │ │
 会话状态 长期信息
 │ │
 thread_id user_id
 │ │
 当前上下文 跨会话访问

因此：

1

checkpoint

解决的是：

这一次 Agent 执行过程如何保存和恢复？

而：

1

long-term memory

解决的是：

这个用户的信息如何脱离某一次会话长期保存？

五、为什么必须专门设计一个“新 thread”来验证长期记忆？

假设：

1
2


Alice
thread_id = alice-1

已经告诉 Agent：

1

我的邮箱是 alice@x.com

然后还是：

1

thread_id = alice-1

再问：

1

我的邮箱是什么？

如果答对了：

1

alice@x.com

我们其实不能确定到底是谁提供了这个答案。

可能是：

1
2
3
4
5


checkpoint
 ↓
恢复了之前的对话
 ↓
模型知道邮箱

也可能是：

1
2
3


long-term memory
 ↓
查询出了邮箱

所以真正的测试应该是：

1
2
3
4
5


Alice
 ↓
alice-1
 ↓
保存邮箱

然后：

1
2
3
4
5
6
7


Carol
 ↓
carol-1
 ↓
一个全新的 checkpoint
 ↓
询问邮箱

如果 Carol 仍然能找到：

1

alice@x.com

才能证明：

1

信息来自 long-term memory

而不是 Alice 的 checkpoint。

所以这个实验实际上是在主动把两个概念隔离开：

1
2
3


同 thread
 ↓
验证 checkpoint

1
2
3


新 thread
 ↓
验证 long-term memory

这是这次实验设计里比较重要的一点。

六、为什么不能所有工具都需要审批？

如果所有工具一律审批：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


搜索资料
 ↓
请批准

查询天气
 ↓
请批准

读取长期记忆
 ↓
请批准

Agent 虽然安全，但是基本没法正常使用。

所以更合理的方式是：

1
2
3
4
5
6
7
8


工具
 ↓
判断是否产生副作用
 ↓
┌───────────────┴───────────────┐
安全 危险
 ↓ ↓
直接执行 人工审批

这次实验把：

1

remember_fact

定义为危险工具。

而：

1

search_memory

是只读工具。

所以：

1
2
3


DANGEROUS = {
 "remember_fact"
}

真正的思想不是“把某个工具名字记进一个集合”。

而是：

不同工具应该有不同的权限等级。

现在使用硬编码只是为了完成实验。

未来真正工程化以后，可以继续发展成：

1
2
3
4
5
6
7


Tool Registry
 ↓
Tool Metadata
 ↓
Permission System
 ↓
判断是否需要人工审批

七、HITL 到底停在哪里？

这一节重新使用了：

1

interrupt()

它最大的特点是：

暂停发生在节点内部。

例如：

1
2
3
4
5
6
7
8
9


approve 节点
 ↓
读取模型提出的工具调用
 ↓
interrupt()
 ↓
图暂停
 ↓
保存 checkpoint

代码核心：

1
2
3
4


answer = interrupt({
 "question": f"模型想执行 {todo}，批准吗？",
 "options": ["approve", "reject"],
})

执行到这里以后，不会继续往下执行。

之后等待：

1

Command(resume="approve")

或者：

1

Command(resume="reject")

再恢复。

八、interrupt() 和 interrupt_before 的区别

这一部分之前已经学过，这次放到实际审批场景里理解会更加直观。

interrupt()

位置：

1

节点内部

例如：

1
2
3
4
5
6
7


approve 节点
 ↓
判断金额
 ↓
金额 > 10000
 ↓
interrupt()

适合动态业务逻辑。

interrupt_before

位置：

1

节点边界

例如：

1
2
3


A
 ↓
B

可以在进入 B 之前暂停。

所以可以先记空间关系：

1
2
3
4
5


interrupt()
 = 节点里面停

interrupt_before
 = 节点前面停

九、阶段 A：先验证 SqliteSaver 的跨进程持久化

这一阶段故意把事情做得非常简单。

不加审批，不加长期记忆。

只验证：

换一个进程以后，同一个 thread 能不能恢复之前的状态？

实验：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


write
 ↓
保存 Alice 的邮箱

read
 ↓
新进程
同 thread
询问邮箱

other
 ↓
新 thread
询问邮箱

这里真正重要的代码只有几个部分。

首先：

1
2
3
4
5
6


conn = sqlite3.connect(
 DB,
 check_same_thread=False
)

saver = SqliteSaver(conn)

然后编译：

1

graph = build_graph(saver)

真正把 checkpoint 接进图：

1

return b.compile(checkpointer=saver)

之后：

1
2
3
4
5


cfg = {
 "configurable": {
 "thread_id": THREAD
 }
}

最后：

1
2
3
4


graph.invoke(
 {"messages": [("user", question)]},
 cfg
)

所以这里需要把三个东西串起来：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


SqliteSaver
 ↓
保存 checkpoint


thread_id
 ↓
告诉系统保存/读取哪个会话


config
 ↓
invoke 时把这个身份传进去

并不是：

“SQLite 自动让所有会话共享记忆。”

而是：

SQLite 保存 checkpoint，而 thread_id 决定你正在访问哪个 checkpoint 槽位。

十、阶段 B：在危险工具前加入 HITL

阶段 B 开始真正把 HITL 接进控制流。

整体：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


START
 ↓
decide
 ↓
有没有 tool_calls？
 ↓
approve
 ↓
人工确认
 ↓
tools
 ↓
summarize
 ↓
END

关键点是：

1

模型不是直接执行工具

而是：

1
2
3
4
5
6
7
8
9


模型
 ↓
提出 tool_call
 ↓
审批节点
 ↓
决定是否放行
 ↓
ToolNode

所以真正控制危险动作的，不是模型本身。

而是：

1

图的控制流

十一、拒绝时为什么不能随便返回一条 AIMessage？

这一节里遇到一个非常值得记录的坑。

最直觉的写法可能是：

1
2
3
4
5
6


if answer == "reject":
 return {
 "messages": [
 AIMessage(content="已取消")
 ]
 }

但是模型已经产生了：

1
2


AIMessage
 └── tool_calls

这意味着后面需要有与这些 tool_calls 对应的工具消息回执。

也就是：

1
2
3
4
5
6
7


AIMessage
 └── tool_call_id = abc

 ↓

ToolMessage
 └── tool_call_id = abc

因此拒绝时最终返回：

1
2
3
4


ToolMessage(
 content="用户拒绝执行本次调用",
 tool_call_id=tc["id"]
)

这个坑让我更清楚地意识到：

tool call 不是模型的一句普通文本，而是一套消息协议。

模型声明：

1

我要调用工具 X

那么后续消息历史中就需要有与之对应的回执。

十二、阶段 C：长期记忆 + HITL + 跨进程

阶段 C 才是真正的端到端实验。

同时存在：

1
2
3
4
5
6
7


SQLite
 ↓
checkpoint / 会话状态

JSON
 ↓
long-term memory / 长期信息

同时存在两个工具：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


search_memory
 ↓
只读
 ↓
安全
 ↓
直接执行


remember_fact
 ↓
写入
 ↓
有副作用
 ↓
需要审批

因此完整的流程变成：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


用户
 ↓
decide
 ↓
判断 tool_calls
 ↓
是否包含危险工具？
 ├── 否 → tools
 │
 └── 是 → approve
 ↓
 interrupt
 ↓
 人工 approve/reject
 ↓
 tools / END
 ↓
 summarize
 ↓
 END

十三、这次实验最终怎么证明“系统真的正确”？

实验设计了两条路径。

路径一：批准

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


Alice
 ↓
记住：我是 Alice，邮箱 alice@x.com
 ↓
remember_fact
 ↓
interrupt
 ↓
approve
 ↓
真正写入长期记忆

最终检查：

1

alice@x.com

存在。

路径二：拒绝

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


Bob
 ↓
记住：我的工号是 X99
 ↓
remember_fact
 ↓
interrupt
 ↓
reject
 ↓
工具不能真正执行

最终检查：

1

X99

不存在。

因此：

1
2
3


assert any("alice@x.com" in t for t in texts)

assert not any("X99" in t for t in texts)

这两条断言实际上证明了两件不同的事：

1

批准路径确实产生了副作用

以及：

1

拒绝路径没有产生副作用

十四、这一节让我对 Agent 的理解发生了什么变化？

如果只总结 API：

1
2
3
4
5


SqliteSaver
interrupt
Command
ToolNode
ToolMessage

那么以后很容易又变成“看过，但不会真正串起来”。

现在我更倾向于从四层理解：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


第一层：State
 ↓
当前 Agent 有什么状态？
状态保存在哪里？


第二层：Control Flow
 ↓
下一步允许进入哪个节点？


第三层：Permission
 ↓
这个动作有没有资格真正执行？


第四层：Verification
 ↓
外部世界最后到底有没有发生变化？

所以一个成熟一点的 Agent，不应该只问：

“模型能不能调用工具？”

而应该继续问：

1
2
3
4
5
6
7
8
9


谁决定调用？
↓
谁允许执行？
↓
执行前能不能暂停？
↓
暂停后能不能恢复？
↓
执行后怎么证明真的发生了？

十五、W6-D6 的几个核心结论

1. checkpoint ≠ long-term memory

checkpoint：

1

保存一次执行过程

long-term memory：

1

保存脱离某次会话的长期信息

2. thread_id 是会话隔离的重要标识

1
2
3
4
5
6
7


thread A
 ↓
A 的 checkpoint

thread B
 ↓
B 的 checkpoint

换 thread 才能真正测试：

1

“这个信息是不是来自长期记忆”

3. HITL 本质上是在控制执行路径

不是：

1

工具 + 一个确认弹窗

而是：

1
2
3
4
5
6
7


模型提出动作
 ↓
路由判断
 ↓
危险操作进入审批
 ↓
批准才能继续

4. tool call 是消息协议的一部分

模型产生：

1

tool_calls

以后，历史消息必须满足对应的回填关系。

所以拒绝时不能随便伪造一条 AIMessage 结束。

5. 验证不能只看日志

更强的验证方式：

1

查看真实外部状态

例如：

1

assert ...

直接检查长期记忆库。

总结：从“Agent 能运行”到“Agent 可以被控制”

W6-D6 表面上是在组合：

1
2
3
4
5


Checkpoint
+
HITL
+
Long-term Memory

但我觉得真正重要的是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


Agent 能运行
 ↓
Agent 能保存状态
 ↓
Agent 能跨进程恢复
 ↓
Agent 能调用工具
 ↓
Agent 可以被人工控制
 ↓
Agent 的副作用能够被验证

所以今天真正学到的不是：

“怎么让 Agent 记住东西。”

而是：

当 Agent 开始拥有改变外部世界的能力以后，状态管理、权限控制和可验证性必须一起考虑。

最终可以把今天的 Agent 理解成：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


用户
 ↓
模型决策
 ↓
判断动作
 ↓
权限控制
 ↓
人工审批（必要时）
 ↓
执行工具
 ↓
修改外部世界
 ↓
验证真实结果

这也是我目前对 W6-D6 最核心的理解：

Agent 一旦拥有改变世界的能力，就必须同时拥有状态管理、权限控制和可验证性。

附：W6-D6 完整实验代码

下面保留本节三阶段完整代码。

这里不是为了让文章变成长篇代码教程，而是为了方便以后复习时，直接从代码入口开始画执行流程，再回到前面的概念解释。

阶段 A：SqliteSaver 跨进程持久化

运行方式：

1
2
3


python w6d6_a_persist.py write
python w6d6_a_persist.py read
python w6d6_a_persist.py other

完整代码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168


"""W6-D6 阶段A: 把图接上 SqliteSaver —— 跨【进程】持久化
用法(三次运行, 三个独立进程):
 python w6d6_a_persist.py write # ① 让 agent 记住邮箱
 python w6d6_a_persist.py read # ② 新进程问邮箱 ← 同 thread
 python w6d6_a_persist.py other # ③ 反例: 换个 thread 问 ← 应该不知道
"""

import os
import sys
import sqlite3
from typing import Annotated, TypedDict

from dotenv import load_dotenv
load_dotenv(override=True)

from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages
from langgraph.checkpoint.sqlite import SqliteSaver
from langchain_openai import ChatOpenAI


DB = "memory_agent.db"


# ══════ 1. State ══════
class S(TypedDict):
 messages: Annotated[list, add_messages]


# ══════ 2. 节点 ══════
# 这里只做最小占位图，只为了验证持久化机制。

_llm = ChatOpenAI(
 model="deepseek-v4-flash",
 api_key=os.getenv("DEEPSEEK_API_KEY"),
 base_url="https://api.deepseek.com",
 temperature=0,
)


def agent_node(state: S) -> dict:
 return {
 "messages": [
 _llm.invoke(state["messages"])
 ]
 }


# ══════ 3. 构图 ══════

def build_graph(saver):
 b = StateGraph(S)

 b.add_node("agent", agent_node)

 b.add_edge(START, "agent")
 b.add_edge("agent", END)

 return b.compile(
 checkpointer=saver
 )


# ══════ 4. 主流程 ══════

def main(mode: str):

 # ① 打开 SQLite
 conn = sqlite3.connect(
 DB,
 check_same_thread=False
 )

 saver = SqliteSaver(conn)

 if hasattr(saver, "setup"):
 saver.setup()

 graph = build_graph(saver)

 # ② thread_id 决定会话槽位
 THREAD = (
 "alice-1.2"
 if mode != "other"
 else "bob-1.2"
 )

 cfg = {
 "configurable": {
 "thread_id": THREAD
 }
 }

 # ③ 三种输入
 if mode == "write":

 question = (
 "记住：我叫 Alice，"
 "邮箱是 alice@x.com。"
 "只回复'已记住'。"
 )

 elif mode == "read":

 question = "我的邮箱是什么？"

 else:

 question = "我的邮箱是什么？"

 # ④ invoke 时必须传 config
 out = graph.invoke(
 {
 "messages": [
 ("user", question)
 ]
 },
 cfg
 )

 print(
 f"\n[{mode}] "
 f"thread_id = {THREAD}"
 )

 print(
 "回复:",
 out["messages"][-1].content
 )

 # ⑤ 使用客观量检查状态
 st = graph.get_state(cfg)

 n = len(
 st.values["messages"]
 )

 for i in st.values["messages"]:
 try:
 print(
 "第条消息是:",
 i.content,
 sep="\n"
 )
 except Exception as e:
 print(
 "出错啦",
 e
 )

 print(
 f"[算的] state 里共 {n} 条消息 "
 f"next={st.next}"
 )

 conn.close()

 return n


if __name__ == "__main__":
 mode = (
 sys.argv[1]
 if len(sys.argv) > 1
 else "read"
 )

 main(mode)

阶段 B：危险工具审批 + 跨进程恢复

运行方式：

1
2
3
4
5
6


python w6d6_b_hitl.py ask
python w6d6_b_hitl.py status
python w6d6_b_hitl.py yes

python w6d6_b_hitl.py ask2
python w6d6_b_hitl.py no

完整代码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418


"""W6-D6 阶段B: 危险操作审批 + 【跨进程】续批

用法(五条命令, 五个独立进程):
 python w6d6_b_hitl.py ask
 python w6d6_b_hitl.py status
 python w6d6_b_hitl.py yes
 python w6d6_b_hitl.py ask2
 python w6d6_b_hitl.py no
"""

import os
import sys
import sqlite3
from typing import Annotated, TypedDict

from dotenv import load_dotenv
load_dotenv(override=True)

from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages
from langgraph.checkpoint.sqlite import SqliteSaver
from langgraph.prebuilt import ToolNode
from langgraph.types import interrupt, Command
from langchain_core.tools import tool
from langchain_core.messages import AIMessage
from langchain_openai import ChatOpenAI


DB = "memory_agent.db"


# ══════ 1. 危险工具 ══════

def delete_file(path: str) -> str:
 """
 危险操作。
 演示版不真正删除文件，只打印工具执行证据。
 """

 print(
 f">>> 工具真身执行: 删除 {path}"
 )

 return f"文件已删除: {path}"


class S(TypedDict):
 messages: Annotated[list, add_messages]


# ══════ 2. 两个 LLM ══════

_llm_kwargs = dict(
 model="deepseek-v4-flash",
 api_key=os.getenv("DEEPSEEK_API_KEY"),
 base_url="https://api.deepseek.com",
 temperature=0,
)

llm_decide = (
 ChatOpenAI(**_llm_kwargs)
 .bind_tools([delete_file])
)

llm_summarize = ChatOpenAI(
 **_llm_kwargs
)


# ══════ 3. 四个节点 ══════

def decide(state: S) -> dict:

 ai_msg = llm_decide.invoke(
 state["messages"]
 )

 print(
 f"[decide] "
 f"tool_calls={len(ai_msg.tool_calls)}"
 )

 return {
 "messages": [ai_msg]
 }


def approve(state: S) -> dict:

 last = state["messages"][-1]

 if not (
 isinstance(last, AIMessage)
 and last.tool_calls
 ):
 return {}

 tc = last.tool_calls[0]

 print(
 "[approve] "
 "从存档里读到的待审参数:",
 tc["args"]
 )

 answer = interrupt({
 "question": (
 f"模型想删除 "
 f"{tc['args']['path']}，批准吗？"
 ),
 "options": [
 "approve",
 "reject"
 ],
 })

 print(
 "[approve] 收到回答:",
 repr(answer)
 )

 if answer == "reject":

 return {
 "messages": [
 AIMessage(
 content=(
 "已取消删除，"
 "本次未执行任何操作。"
 )
 )
 ]
 }

 return {}


def summarize(state: S) -> dict:

 ai_msg = llm_summarize.invoke(
 state["messages"]
 )

 print(
 "[summarize] 收口完成"
 )

 return {
 "messages": [ai_msg]
 }


# ══════ 4. 路由 ══════

def route_after_decide(state: S):

 last = state["messages"][-1]

 if (
 isinstance(last, AIMessage)
 and last.tool_calls
 ):
 return "approve"

 return END


def route_after_approve(state: S):

 last = state["messages"][-1]

 if (
 isinstance(last, AIMessage)
 and last.tool_calls
 ):
 return "tools"

 return END


# ══════ 5. 构图 ══════

def build_graph(saver):

 b = StateGraph(S)

 b.add_node(
 "decide",
 decide
 )

 b.add_node(
 "approve",
 approve
 )

 b.add_node(
 "tools",
 ToolNode([delete_file])
 )

 b.add_node(
 "summarize",
 summarize
 )

 b.add_edge(
 START,
 "decide"
 )

 b.add_conditional_edges(
 "decide",
 route_after_decide,
 {
 "approve": "approve",
 END: END
 }
 )

 b.add_conditional_edges(
 "approve",
 route_after_approve,
 {
 "tools": "tools",
 END: END
 }
 )

 b.add_edge(
 "tools",
 "summarize"
 )

 b.add_edge(
 "summarize",
 END
 )

 return b.compile(
 checkpointer=saver
 )


# ══════ 6. thread 对应关系 ══════

THREAD_OF = {

 "ask":
 "hitl-alice",

 "status":
 "hitl-alice",

 "yes":
 "hitl-alice",

 "ask2":
 "hitl-bob",

 "no":
 "hitl-bob",
}


ASK_TEXT = (
 "请删除 /tmp/report.txt"
)


# ══════ 7. 查看 checkpoint ══════

def peek(graph, cfg, tag):

 st = graph.get_state(cfg)

 msgs = (
 st.values.get(
 "messages",
 []
 )
 or []
 )

 print(
 f"\n[{tag}] "
 f"next={st.next} "
 f"消息数={len(msgs)}"
 )

 for i, m in enumerate(msgs):

 head = (
 str(m.content)
 .replace("\n", "")
 [:40]
 )

 tc = getattr(
 m,
 "tool_calls",
 None
 )

 print(
 f" [{i}] "
 f"{type(m).__name__:12s} "
 f"{head!r}"
 )

 return st


# ══════ 8. 主流程 ══════

def main(mode: str):

 conn = sqlite3.connect(
 DB,
 check_same_thread=False
 )

 saver = SqliteSaver(conn)

 if hasattr(saver, "setup"):
 saver.setup()

 graph = build_graph(saver)

 THREAD = THREAD_OF[mode]

 cfg = {
 "configurable": {
 "thread_id": THREAD
 }
 }

 print(
 f"[{mode}] "
 f"thread_id = {THREAD} "
 f"(PID={os.getpid()})"
 )

 if mode in ("ask", "ask2"):

 graph.invoke(
 {
 "messages": [
 ("user", ASK_TEXT)
 ]
 },
 cfg
 )

 print(
 "→ 图已停在审批点，"
 "本进程即将退出"
 )

 elif mode == "status":

 print(
 "→ 纯读模式："
 "只从 sqlite 读取暂停现场"
 )

 elif mode == "yes":

 out = graph.invoke(
 Command(
 resume="approve"
 ),
 cfg
 )

 print(
 "→ 最终回复:",
 out["messages"][-1].content
 )

 elif mode == "no":

 out = graph.invoke(
 Command(
 resume="reject"
 ),
 cfg
 )

 print(
 "→ 最终回复:",
 out["messages"][-1].content
 )

 else:

 print(
 f"未知模式: {mode}"
 )

 sys.exit(1)

 peek(
 graph,
 cfg,
 mode
 )

 conn.close()


if __name__ == "__main__":

 main(
 sys.argv[1]
 if len(sys.argv) > 1
 else "status"
 )

阶段 C：长期记忆 + HITL + 跨会话验证

运行方式：

1
2
3
4
5
6
7
8
9


python w6d6_c_e2e.py remember
python w6d6_c_e2e.py yes
python w6d6_c_e2e.py recall

python w6d6_c_e2e.py bob
python w6d6_c_e2e.py no

python w6d6_c_e2e.py carol
python w6d6_c_e2e.py verify

完整代码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673


"""W6-D6 阶段C: 跨会话记忆 + 审批 端到端

七个独立进程:
 remember
 yes
 recall
 bob
 no
 carol
 verify
"""

import os
import sys
import json
import time
import sqlite3

from typing import (
 Annotated,
 TypedDict
)

from dotenv import load_dotenv
load_dotenv(override=True)

from langchain_core.messages import (
 AIMessage,
 SystemMessage,
 ToolMessage
)

from langgraph.graph import (
 StateGraph,
 START,
 END
)

from langgraph.graph.message import (
 add_messages
)

from langgraph.checkpoint.sqlite import (
 SqliteSaver
)

from langgraph.prebuilt import (
 ToolNode
)

from langgraph.types import (
 interrupt,
 Command
)

from langchain_core.tools import tool
from langchain_openai import ChatOpenAI


DB = "memory_agent.db"

MEM = (
 "w6d6_long_term_mem.json"
)


# ══════ 1. 长期记忆库 ══════

def _load_mem() -> list:

 if not os.path.exists(MEM):
 return []

 with open(
 MEM,
 "r",
 encoding="utf-8"
 ) as f:

 return json.load(f)


def _save_mem(items: list) -> None:

 with open(
 MEM,
 "w",
 encoding="utf-8"
 ) as f:

 json.dump(
 items,
 f,
 ensure_ascii=False,
 indent=2
 )


# ══════ 2. 两个工具 ══════

@tool
def search_memory(query: str) -> str:

 """
 安全·只读。
 在长期记忆库里检索。
 """

 items = _load_mem()

 print(
 f">>> [安全工具] "
 f"检索 {query!r}"
 f"→ 库里共 {len(items)} 条"
 )

 if not items:
 return "长期记忆是空的"

 return (
 "长期记忆库内容:\n"
 + "\n".join(
 f"- {it['text']}"
 for it in items
 )
 )


@tool
def remember_fact(text: str) -> str:

 """
 危险·写入。
 写入长期记忆库。
 执行前需要人工审批。
 """

 items = _load_mem()

 items.append({
 "text": text,
 "ts": time.time()
 })

 _save_mem(items)

 print(
 ">>> [危险工具真身] "
 f"已写入长期记忆: {text}"
 )

 return f"已记住：{text}"


# ══════ 3. 危险工具名单 ══════

DANGEROUS = {
 "remember_fact"
}


class S(TypedDict):
 messages: Annotated[
 list,
 add_messages
 ]


# ══════ 4. 两个 LLM ══════

_llm_kwargs = dict(
 model="deepseek-v4-flash",
 api_key=os.getenv(
 "DEEPSEEK_API_KEY"
 ),
 base_url=(
 "https://api.deepseek.com"
 ),
 temperature=0,
)


llm_decide = (
 ChatOpenAI(**_llm_kwargs)
 .bind_tools(
 [
 search_memory,
 remember_fact
 ],
 parallel_tool_calls=False
 )
)


llm_summarize = ChatOpenAI(
 **_llm_kwargs
)


SYS = (
 "你是一个带长期记忆的助手。规则:\n"
 "1. 用户说『记住：X』时，你必须"
 "立即调用 remember_fact 工具把 X 写进长期记忆库；\n"
 "2. 用户询问之前记录的信息时，"
 "如果上下文里没有答案，必须调用 search_memory；\n"
 "3. 工具完成后，用一句简短中文总结结果。"
)


# ══════ 5. 节点 ══════

def decide(state: S) -> dict:

 ai_msg = llm_decide.invoke(
 state["messages"]
 )

 names = [
 tc["name"]
 for tc in ai_msg.tool_calls
 ]

 print(
 "[decide] "
 f"tool_calls={len(ai_msg.tool_calls)} "
 f"{names}"
 )

 return {
 "messages": [ai_msg]
 }


def approve(state: S) -> dict:

 last = state["messages"][-1]

 if not (
 isinstance(last, AIMessage)
 and last.tool_calls
 ):
 return {}

 todo = [
 tc["name"]
 for tc in last.tool_calls
 ]

 print(
 "[approve] "
 f"待审批的工具调用：{todo}"
 )

 answer = interrupt({
 "question": (
 f"模型想执行 {todo}，批准吗？"
 ),
 "options": [
 "approve",
 "reject"
 ],
 })

 print(
 "[approve] 收到回答:",
 repr(answer)
 )

 if answer == "reject":

 return {
 "messages": [
 ToolMessage(
 content=(
 "用户拒绝执行本次调用，"
 "已取消"
 ),
 tool_call_id=tc["id"]
 )
 for tc in last.tool_calls
 ]
 }

 return {}


def summarize(state: S) -> dict:

 ai_msg = llm_summarize.invoke(
 state["messages"]
 )

 print(
 "[summarize] 收口完成"
 )

 return {
 "messages": [ai_msg]
 }


# ══════ 6. 路由 ══════

def route_after_decide(state: S):

 last = state["messages"][-1]

 if not (
 isinstance(last, AIMessage)
 and last.tool_calls
 ):
 return END

 if any(
 tc["name"] in DANGEROUS
 for tc in last.tool_calls
 ):
 return "approve"

 return "tools"


def route_after_approve(state: S):

 last = state["messages"][-1]

 if (
 isinstance(last, AIMessage)
 and last.tool_calls
 ):
 return "tools"

 return END


# ══════ 7. 构图 ══════

def build_graph(saver):

 b = StateGraph(S)

 b.add_node(
 "decide",
 decide
 )

 b.add_node(
 "approve",
 approve
 )

 b.add_node(
 "tools",
 ToolNode(
 [
 search_memory,
 remember_fact
 ]
 )
 )

 b.add_node(
 "summarize",
 summarize
 )

 b.add_edge(
 START,
 "decide"
 )

 b.add_conditional_edges(
 "decide",
 route_after_decide,
 {
 "approve": "approve",
 "tools": "tools",
 END: END
 }
 )

 b.add_conditional_edges(
 "approve",
 route_after_approve,
 {
 "tools": "tools",
 END: END
 }
 )

 b.add_edge(
 "tools",
 "summarize"
 )

 b.add_edge(
 "summarize",
 END
 )

 return b.compile(
 checkpointer=saver
 )


# ══════ 8. thread 对应关系 ══════

THREAD_OF = {

 "remember":
 "alice-1",

 "yes":
 "alice-1",

 "status":
 "alice-1",

 "recall":
 "alice-1",

 "bob":
 "bob-1",

 "no":
 "bob-1",

 "carol":
 "carol-1",
}


# ══════ 9. 查看 checkpoint ══════

def peek(graph, cfg, tag):

 st = graph.get_state(cfg)

 msgs = (
 st.values.get(
 "messages",
 []
 )
 or []
 )

 print(
 f"\n[{tag}] "
 f"next={st.next} "
 f"消息数={len(msgs)}"
 )

 for i, m in enumerate(msgs):

 head = (
 str(m.content)
 .replace("\n", " ")
 [:44]
 )

 tc = getattr(
 m,
 "tool_calls",
 None
 )

 print(
 f" [{i}] "
 f"{type(m).__name__:14s} "
 f"{head!r}"
 + (
 f" tool_calls={tc}"
 if tc
 else ""
 )
 )

 return st


# ══════ 10. 最终验证 ══════

def verify():

 items = _load_mem()

 print(
 "长期记忆库当前内容："
 )

 for it in items:
 print(
 " -",
 it["text"]
 )

 if not items:
 print(" (空)")

 texts = [
 it["text"]
 for it in items
 ]

 assert any(
 "alice@x.com" in t
 for t in texts
 ), (
 "❌ alice 的邮箱不在库里"
 )

 assert not any(
 "X99" in t
 for t in texts
 ), (
 "❌ bob 的工号在库里"
 )

 print(
 "\n✅ 断言通过："
 "批准的那条在库里，"
 "拒绝的那条不在库里"
 )


# ══════ 11. 测试输入 ══════

FIRST_ASK = {

 "remember":
 "记住：我是 Alice，邮箱 alice@x.com",

 "bob":
 "记住：我的工号是 X99",

 "carol":
 "我不记得之前存过什么了，"
 "帮我查一下长期记忆库里有没有关于邮箱的记录",
}


# ══════ 12. 主流程 ══════

def main(mode: str):

 if mode == "verify":
 return verify()

 conn = sqlite3.connect(
 DB,
 check_same_thread=False
 )

 saver = SqliteSaver(conn)

 if hasattr(saver, "setup"):
 saver.setup()

 graph = build_graph(saver)

 THREAD = THREAD_OF[mode]

 cfg = {
 "configurable": {
 "thread_id": THREAD
 }
 }

 print(
 f"[{mode}] "
 f"thread_id = {THREAD} "
 f"(PID={os.getpid()})"
 )

 if mode in FIRST_ASK:

 graph.invoke(
 {
 "messages": [
 SystemMessage(
 content=SYS
 ),
 (
 "user",
 FIRST_ASK[mode]
 )
 ]
 },
 cfg
 )

 print(
 f"→ [{mode}] 本轮结束"
 )

 elif mode == "status":

 print(
 "→ 纯读模式："
 "只从 sqlite 读取暂停现场"
 )

 elif mode == "yes":

 out = graph.invoke(
 Command(
 resume="approve"
 ),
 cfg
 )

 print(
 "→ 最终回复:",
 out["messages"][-1].content
 )

 elif mode == "no":

 out = graph.invoke(
 Command(
 resume="reject"
 ),
 cfg
 )

 print(
 "→ 最终回复:",
 out["messages"][-1].content
 )

 elif mode == "recall":

 out = graph.invoke(
 {
 "messages": [
 (
 "user",
 "我的邮箱是什么？"
 )
 ]
 },
 cfg
 )

 print(
 "→ 最终回复:",
 out["messages"][-1].content
 )

 else:

 print(
 f"未知模式: {mode}"
 )

 sys.exit(1)

 peek(
 graph,
 cfg,
 mode
 )

 conn.close()


if __name__ == "__main__":

 main(
 sys.argv[1]
 if len(sys.argv) > 1
 else "status"
 )

最后留给自己的复习入口

以后重新看 W6-D6，我不准备从 API 名字开始背，而是先问自己：

1
2
3
4
5
6
7
8


1. Checkpoint 保存的到底是什么？
2. thread_id 为什么必须一致？
3. 为什么换 thread 才能证明长期记忆？
4. interrupt 到底停在哪里？
5. resume 之后是怎么继续的？
6. 为什么危险工具需要审批？
7. 为什么拒绝 tool_call 时需要 ToolMessage？
8. 为什么最后要直接检查长期记忆文件？

如果这几个问题能够重新顺着代码画出：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


START
 ↓
decide
 ↓
route
 ↓
approve
 ↓
interrupt
 ↓
resume
 ↓
tools
 ↓
summarize
 ↓
END

那么这一节才算真正重新掌握。

W6-D6 的核心不是“让 Agent 记住”，而是理解：Agent 一旦拥有改变世界的能力，就必须同时拥有状态管理、权限控制和可验证性。

从有状态 Agent 到生产级工作流

Sun, 13 Sep 2026 13:47:06 +0800

LangGraph W6 周总结：从有状态 Agent 到生产级工作流

这一周主要学习 LangGraph 的状态管理、人工介入、流程恢复以及任务拆分能力。

如果说 W5 学习的是：

如何让 Agent 按照图结构运行

那么 W6 学习的是：

如何让 Agent 像一个真正的产品一样长期运行，并且在关键节点接受控制。

这一周几个核心关键词：

Checkpoint：保存 Agent 每一步状态
Persistence：让状态跨进程保存
HITL（Human In The Loop）：让人参与 Agent 决策
Time Travel：基于历史状态恢复执行
Subgraph：拆分复杂 Agent
Send：动态并行任务分发

一、W5 无状态 Agent vs W6 有状态 Agent

之前的 Agent：

1
2
3
4
5


用户输入
 ↓
Agent运行
 ↓
返回结果

一次运行结束，状态消失。

但是实际产品需要：

例如：

用户：

帮我记录一下，我喜欢喝咖啡。

下一次：

我喜欢喝什么？

Agent 需要知道之前的信息。

所以需要：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


第一次运行

State
 ↓
Checkpoint保存


第二次运行

读取Checkpoint
 ↓
恢复State
 ↓
继续执行

LangGraph 通过 checkpoint 机制实现状态保存。

二、Checkpoint：Agent 的历史快照

Checkpoint 可以理解为：

每执行完一个节点，对当前 State 保存一次快照。

例如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32


START

 ↓

agent节点

State:
{
 messages:[
 "用户问题"
 ]
}


保存 checkpoint


 ↓


tool节点

State:
{
 messages:[
 "用户问题",
 "tool结果"
 ]
}


再次保存 checkpoint

所以 checkpoint 不只是保存最终结果，而是保存：

当前 state
当前执行位置
thread 信息

这也是后面：

resume
update_state
time travel

的基础。

三、MemorySaver 和 SqliteSaver

MemorySaver

之前学习：

1
2
3
4
5


memory = MemorySaver()

graph = builder.compile(
 checkpointer=memory
)

特点：

保存到内存
程序关闭后消失

适合：

学习
测试

SqliteSaver

生产环境需要落盘。

例如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


from langgraph.checkpoint.sqlite import SqliteSaver


checkpointer = SqliteSaver.from_conn_string(
 "agent.db"
)


graph = builder.compile(
 checkpointer=checkpointer
)

区别：

	MemorySaver	SqliteSaver
存储位置	内存	数据库
重启恢复	❌	✅
适合	测试	生产

四、thread_id：实现多用户隔离

LangGraph 使用 config 区分不同会话。

例如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


config = {
 "configurable":{
 "thread_id":"user_001"
 }
}


graph.invoke(
 input,
 config=config
)

不同 thread：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


user_001

checkpoint A
checkpoint B


user_002

checkpoint C
checkpoint D

它们互相不会影响。

所以：

thread_id 本质是一个会话隔离标识。

五、HITL：让 Agent 停下来等待人确认

Agent 最大的问题：

能力越强，风险越高。

例如：

普通回答：

1
2
3


用户问题
 ↓
LLM回答

风险低。

但是：

1
2
3
4
5
6
7
8
9


用户请求删除文件

 ↓

Agent调用工具

 ↓

删除执行

如果 Agent 判断错误，会造成真实损失。

所以需要：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


Agent决定

 ↓

暂停

 ↓

人确认

 ↓

继续执行

这就是 HITL。

六、interrupt() 和 interrupt_before 的区别

这是本周重点验收。

interrupt_before

在 compile 时指定：

1
2
3


graph = builder.compile(
 interrupt_before=["tools"]
)

作用：

在进入某个节点之前暂停。

流程：

1
2
3
4
5
6
7
8
9


agent

 ↓

暂停

 ↓

tools

它控制的是：

节点之间。

interrupt()

写在节点内部：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


from langgraph.types import interrupt


def approval_node(state):

 answer = interrupt(
 "是否允许执行?"
 )

 return {
 "result":answer
 }

流程：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


进入节点

 ↓

执行到 interrupt()

 ↓

暂停

 ↓

等待恢复

它控制的是：

节点内部。

核心区别：

	interrupt_before	interrupt()
位置	节点外部	节点内部
控制粒度	节点级	代码级
适合	固定审批点	动态判断

七、Command(resume)：恢复暂停的 Agent

暂停后：

需要通过：

1
2
3


Command(
 resume=True
)

恢复。

例如：

1
2
3
4
5
6


graph.invoke(
 Command(
 resume=True
 ),
 config=config
)

含义：

告诉 LangGraph：

人已经做出决定，继续执行。

八、审批三态设计

实际生产不是简单 yes/no。

通常有三种：

1. 放行

1

resume=True

继续执行。

2. 拒绝

1

resume=False

Agent 根据拒绝原因重新规划。

例如：

删除文件：

1
2
3
4
5


用户拒绝

↓

换成备份文件

3. 修改参数

人工直接修改 state：

1
2
3
4
5
6


graph.update_state(
 config,
 {
 "path":"new_file.txt"
 }
)

然后继续执行。

这比简单批准更加接近真实系统。

九、Time Travel：回到过去重新执行

因为 LangGraph 保存 checkpoint。

所以可以：

查看历史：

1
2
3


history = graph.get_state_history(
 config
)

找到旧 checkpoint：

1
2
3
4
5


checkpoint_1

checkpoint_2

checkpoint_3

然后：

从旧状态重新运行。

应用场景：

例如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


Agent:

发送邮件

↓

发现参数错误


回到发送前

↓

修改参数

↓

重新执行

这就是 Agent 的调试能力。

十、Subgraph：拆分复杂 Agent

复杂 Agent 不应该全部写在一个图。

例如：

1
2
3
4
5
6
7


主Agent

├── 搜索Agent
│
├── 分析Agent
│
└── 写作Agent

LangGraph 可以：

先编译子图：

1

subgraph = child_builder.compile()

然后：

作为节点加入：

1
2
3
4


builder.add_node(
 "research",
 subgraph
)

最终形成：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


parent

 ↓

research

 ↓

 research.search

 research.analyze

子图解决：

大 Agent 拆分和复用问题。

十一、Send：动态任务并行

普通 edge：

但是很多任务天然适合并行。

例如：

搜索多个关键词：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


关键词:

python
langgraph
agent


同时搜索

 ↓


汇总结果

使用 Send：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


from langgraph.types import Send


def dispatch(state):

 return [
 Send(
 "worker",
 {
 "keyword":k
 }
 )
 for k in state["keywords"]
 ]

产生：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


dispatch

 ├── worker(python)

 ├── worker(langgraph)

 └── worker(agent)


 ↓


 join

这就是：

Map-Reduce 模式。

十二、本周完成能力总结

知识层

✅ 理解 checkpoint：

每个节点执行后的 state 快照。

✅ 理解 MemorySaver 和 SqliteSaver：

内存保存 vs 数据库存储。

✅ 理解 thread_id：

不同会话通过 thread_id 隔离。

✅ 理解 HITL：

Agent 在关键节点暂停，让人参与决策。

✅ 理解：

1
2
3
4
5


interrupt()

vs

interrupt_before

区别：

节点内部暂停 vs 节点边界暂停。

✅ 理解 Send：

动态产生多个并行任务。

十三、W6 最大收获

之前：

1

Agent = 调用LLM完成任务

现在：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


生产级Agent=

状态保存

+

人工控制

+

错误恢复

+

任务拆分

+

并行执行

真正可用的 Agent，不只是会回答问题。

而是：

在复杂环境中，可以暂停、恢复、修改、追踪，并且安全执行任务。

这也是 LangGraph 和普通 Chain 最大的区别。

W6 完成后，Agent 开发进入了一个新的阶段：

从「能运行」

进入：

「可控制、可恢复、可维护」。

LangGraph 总览

Sat, 12 Sep 2026 05:47:58 +0800

LangGraph 总览：从会用 API 到理解 Agent Runtime

这篇不是 LangGraph API 速查表。

目标不是记住：
1
2
3
StateGraph(...)
Send(...)
interrupt(...)
而是建立这样一种能力：

看到一个 Agent 需求，能够解释为什么这样建图、状态怎么流、控制流怎么走、为什么需要某个机制，以及不用它会发生什么。

LangGraph 真正值得学习的，不是 API 数量，而是 Agent Runtime 的运行模型和系统设计方法。

一、先回答：LangGraph 到底解决什么问题？

最容易形成的错误理解是：

LangGraph = 一个比 LangChain 更复杂的框架。

更准确地说：

1
2
3
4
5
6
7
8


LangChain
解决：
“模型、Prompt、Tool、Retriever 怎么组合？”

LangGraph
解决：
“一个有状态、会分支、会循环、会暂停、
会恢复、会并行的 Agent 系统怎么运行？”

所以：

1
2
3
4
5


Chain
→ 描述一条处理流水线

Graph
→ 描述一个运行中的状态系统

这也是为什么 LangGraph 会出现：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


State
Node
Edge
Reducer
Checkpoint
HITL
Subgraph
Send
Supervisor
Harness

这些东西看起来分散，实际上都在回答同一个问题：

Agent 在运行过程中，状态和控制权到底如何流动？

二、先建立 LangGraph Runtime 心智模型

以后学习任何 LangGraph API，都先把下面这张图放在脑子里：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


 ┌───────────────┐
 │ State │
 └───────┬───────┘
 │
 ↓
 ┌─────────┐
 │ Node │
 └────┬────┘
 │
 State Update
 │
 ↓
 ┌─────────┐
 │ Reducer │
 └────┬────┘
 │
 ↓
 Updated State
 │
 ↓
 ┌─────────┐
 │ Edge │
 └────┬────┘
 │
 ┌─────────┴─────────┐
 ↓ ↓
 Node A Node B

这里有一个极其重要的区分：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


Node
→ 我做什么？

Edge
→ 下一步去哪？

State
→ 系统现在知道什么？

Reducer
→ 新状态怎么与旧状态合并？

这四个概念如果没有分清，后面学 Send、Subgraph、HITL、Supervisor 都会变成背 API。

三、State：不是“参数”，而是 Agent 的运行时状态

例如：

1
2
3
4
5
6
7
8


class State:
 messages
 summary
 retrieved
 tool_result
 user_id
 approval
 next_step

不要把它理解成：

“为了让函数传参数方便。”

更应该理解：

State = 整个 Agent 在某一时刻掌握的运行事实。

因此：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


Node
↓
读取 State

Node
↓
产生 State Update

Runtime
↓
合并 State

下一个 Node
↓
继续读取

于是第一个深度问题就出现了：

为什么不能随便往 State 里塞字段？

因为每一个字段都会成为：

节点之间的共享契约
Reducer 的输入
Checkpoint 的内容
子图的接口
调试时的事实来源

所以 State Schema 本质上是在设计 Agent 的共享内存模型。

四、Node：不是“一个函数”，而是职责边界

最简单的 Node：

1
2


def node(state):
 return {"result": "..."}

但真正重要的问题是：

为什么这个逻辑应该成为 Node？

好的 Node 通常拥有清晰职责：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


route_node
→ 决定下一步

compress_node
→ 压缩上下文

memory_node
→ 读写记忆

agent_node
→ 让模型做决策

tool_node
→ 执行工具

所以不要问：

“这里怎么写一个 Node？”

应该先问：

这里有没有一个独立的职责边界？

五、Edge：控制流到底怎么走

普通 Edge：

1

A → B

Conditional Edge：

1
2
3


 ┌→ B
A ─────┤
 └→ C

这里真正值得理解的是：

谁决定下一步？

可能是：

1
2
3


Python 规则
↓
Router

也可能：

1
2
3
4
5


LLM
↓
结构化输出
↓
Router

所以 Conditional Edge 本质不是一个 API。

它表达的是：

系统的决策点。

六、State Flow 和 Control Flow 必须分开理解

这是理解 LangGraph 最重要的分界之一。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


State Flow
──────────
“数据怎么走？”

State
↓
Node
↓
State Update
↓
Reducer
↓
New State

而：

1
2
3
4
5
6
7
8
9


Control Flow
────────────
“程序接下来做什么？”

Node
↓
Edge
↓
Next Node

于是很多概念可以重新定位：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


State / Reducer
→ 数据流

Edge / Conditional Edge / Send
→ 控制流

Checkpoint
→ 时间维度

HITL
→ 控制权

Subgraph
→ 执行边界

Harness
→ 系统边界

这是以后理解复杂 LangGraph 最重要的一张地图。

七、Reducer：为什么 State Update 不是简单赋值

例如：

1

messages: Annotated[list, add_messages]

它表达的不是：

messages 是一个 list。

而是：

messages 的更新方式由 reducer 决定。

因此：

1
2
3
4
5
6
7


旧 State
+
Node Update
↓
Reducer
↓
新 State

所以：

1

return {"messages": new_messages}

并不一定意味着：

1

messages = new_messages

可能是：

1

messages = merge(old_messages, new_messages)

这也是为什么你之前的压缩场景容易出问题。

所以学习 Reducer 时最应该问：

这个字段的更新语义是什么？

而不是只记：

1

Annotated[..., ...]

八、ToolNode + ReAct：Agent 为什么其实是一张循环图

一个典型 Agent：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


START
 ↓
Agent
 ↓
需要 Tool？
 ├── No → END
 └── Yes
 ↓
 Tool
 ↓
 Agent

这时应该开始建立一个重要认识：

Agent 不是一个 LLM。

Agent 是：

1
2
3
4
5
6
7
8
9


LLM
+
State
+
Tool
+
Routing
+
Loop

所以“Agent 能力”实际上是一套运行机制。

九、Stream：不是打字机，而是观察 Runtime

你已经学过：

1
2
3
4


updates
values
messages
events

不要只记：

messages 可以实现打字机。

更应该理解：

Stream 是观察 Graph Execution 的接口。

所以：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


updates
→ 哪个节点更新了什么？

values
→ 当前完整 State 是什么？

messages
→ LLM 消息怎么产生？

events
→ 更底层的运行过程是什么？

所以 Stream 和 W7 的 Trace 其实是一条连续的能力：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


Stream
↓
观察运行
↓
Trace
↓
工程化记录运行
↓
Eval
↓
衡量运行质量

十、Checkpoint：Agent 为什么开始“记得过去”

没有 Checkpointer：

1
2
3
4
5
6
7


Run
↓
State
↓
END
↓
结束

有 Checkpointer：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


Run
↓
State
↓
Checkpoint
↓
继续
↓
Checkpoint
↓
继续

所以真正重要的不是：

“SqliteSaver 是一个保存状态的东西。”

而是：

Checkpoint 让 Agent 的执行过程变成了可恢复的状态历史。

于是你才能拥有：

1
2
3
4
5
6


恢复
多会话
调试历史
HITL 暂停
时间旅行
重新执行

所以：

Checkpoint 是 Agent 从“一次性程序”走向“持续运行系统”的关键。

十一、thread_id：Graph 和 Session 是两回事

同一张 Graph：

1
2
3
4


 Graph
 / | \
 / | \
 thread A thread B thread C

Graph 是：

流程定义。

thread_id 是：

某个具体会话/运行实例的身份。

因此：

1

Graph ≠ Session

这是工程化 Agent 必须掌握的概念。

十二、HITL：真正解决的是什么？

interrupt() 不应该记成：

“一个暂停 API。”

真正的问题是：

Agent 的自主性和系统的安全性怎么平衡？

例如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


Agent
 ↓
“我要删文件”
 ↓
风险判断
 ↓
interrupt
 ↓
Human
 ├── approve
 ├── reject
 └── modify
 ↓
resume

因此 HITL 实际上解决：

1
2
3


Agent autonomy
 ↕
Human control

随着 Agent 权限增加，人类控制的重要性也会上升。

十三、interrupt() 和 interrupt_before：区别不在名字

应该问：

暂停点发生在哪里？

1
2
3
4
5


interrupt()
→ 节点执行过程中主动暂停

interrupt_before
→ 节点边界之前暂停

所以以后碰到 HITL，不要只问：

“哪个 API 好用？”

而应该先问：

我的审批点是一个动态执行逻辑，还是一个固定节点边界？

十四、Time Travel：为什么历史状态不是日志，而是可执行资产

假设：

1

A → B → C → D

拥有历史 Checkpoint 后，可以：

1
2
3


A → B → C
 ├→ D
 └→ E

所以历史状态不再只是：

“发生过什么。”

它变成：

“可以从这里重新运行什么。”

这使得：

调试
恢复
实验
审批
分支执行

成为可能。

十五、Subgraph：不是“把图塞进去”

简单说：

Subgraph = 把一套独立的 Graph 执行逻辑作为另一个 Graph 的组成部分。

例如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


Parent Graph
│
├── Planning
│
├── Memory Subgraph
│ ├── Search
│ ├── Rank
│ └── Summarize
│
└── Agent

更深的理解是：

Subgraph 是模块化的执行边界。

因此必须继续追问：

1
2
3
4
5
6


父图 State 怎么进入子图？
子图结果怎么回父图？
config 怎么透传？
thread_id 怎么处理？
checkpoint 属于谁？
失败边界在哪里？

这才是 Subgraph 的深度。

十六、Send：真正解决的是动态 fan-out

你现在已经学过 Send，接下来最重要的是忘掉：

1

Send("worker", payload)

这个语法。

先想任务：

1
2
3
4
5
6


topics = [
 Python,
 Go,
 Rust,
 Java
]

需要：

1
2
3
4


 ┌── Worker(Python)
 ├── Worker(Go)
Input ───────┼── Worker(Rust)
 └── Worker(Java)

这是：

动态 fan-out。

也就是说：

运行时，根据当前数据决定到底创建多少个执行分支。

十七、为什么不能普通 Conditional Edge？

普通 Conditional Edge 更接近：

1
2
3


A
├── B
└── C

它表达：

从几个已经定义好的路径里选一个。

而 Send：

1
2
3
4
5


A
↓
运行时得到 N 个 item
↓
创建 N 个 worker execution

表达的是：

动态生成执行实例。

因此：

1
2
3
4
5


Conditional Edge
→ 选择路径

Send
→ 动态产生多个执行任务

不要把 Send 理解成：

“更灵活的 Conditional Edge。”

它们解决的是不同的问题。

十八、为什么 worker 拿不到 `state["messages"]`？

这里最关键的是理解：

Graph State 和 Send Payload 不是一个概念。

例如：

1
2
3
4


[
 Send("worker", {"topic": "Python"}),
 Send("worker", {"topic": "Go"}),
]

你实际上是在说：

1
2
3
4
5


Graph Runtime
↓
创建 worker execution
↓
这个 execution 收到指定 payload

所以：

1
2
3


原始 Graph State
≠
某个 Send task 的输入

因此 worker 为什么拿不到：

1

state["messages"]

不能简单回答：

“因为 Send 不传。”

真正应该解释：

Worker 的输入边界由当前图的 State Schema、Send payload 以及状态合并机制共同决定；Send 是在创建动态执行任务，而不是简单把整个原始 State 做一次函数参数复制。

这个答案才开始接近 Runtime 层。

十九、Send 之后，状态怎么回来？

这是 Send 最重要的问题。

假设：

1
2
3
4
5
6
7
8


Worker A
→ {"results": ["A"]}

Worker B
→ {"results": ["B"]}

Worker C
→ {"results": ["C"]}

问题：

最后 State 到底是什么？

不是 Send 决定。

而是：

1
2
3
4
5
6
7


Worker Updates
↓
State Schema
↓
Reducer / Channel Semantics
↓
Merged State

所以：

1
2
3
4
5


Send
负责 fan-out

Reducer
负责 fan-in 的数据合并

这两个概念必须放在一起理解。

二十、Join：不是一定存在一个 `join()` API

所谓 Join，本质是：

多个并行执行完成后，进入一个聚合点。

例如：

1
2
3
4


 ┌── Worker A ──┐
 ├── Worker B ──┤
Fan-out ─────┼── Worker C ──┼──→ Aggregate
 └── Worker D ──┘

所以 Join 实际上是：

一个同步/聚合点。

因此看到 Send，你必须立刻问：

“这些分支最终在哪里汇合？”

二十一、并行为什么不是“免费加速”

假设：

1

100 个 worker

并发可能降低 wall-clock time。

但同时增加：

1
2
3
4
5
6


模型调用数
Token 成本
并发资源
限流风险
错误数量
状态合并复杂度

所以：

能并行 ≠ 应该并行。

真正的工程判断是：

1
2
3
4
5


任务能否拆分？
任务之间是否独立？
并行收益是否大于协调成本？
失败是否可接受？
结果是否需要保持顺序？

二十二、并行为什么会出现顺序问题？

因为：

1
2
3
4


A
B
C
D

并发执行后可能：

1
2
3
4


C 完成
A 完成
D 完成
B 完成

所以如果业务需要顺序，就必须明确设计：

1
2
3


结果是否带 index？
Reducer 是否保证顺序？
Join 如何排序？

这说明：

并发改变的不只是速度，也改变执行顺序语义。

二十三、Worker 失败怎么办？

Parallel Execution 必须考虑失败策略：

1
2
3
4


A ✅
B ✅
C ❌
D ✅

可能有：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


策略 1
→ 全部失败

策略 2
→ partial result

策略 3
→ 只 retry C

策略 4
→ fallback

策略 5
→ 超过失败阈值后整体终止

所以以后看到 Send：

一定顺手问 Failure Semantics。

这才开始进入真正的 Runtime Engineering。

二十四、Map-Reduce：Send 背后的更高层抽象

可以把 Send 理解成：

1
2
3
4
5
6
7
8
9


 Map
 ↓
 ┌─────────┼─────────┐
 ↓ ↓ ↓
 W1 W2 W3
 ↓ ↓ ↓
 └─────────┼─────────┘
 ↓
 Reduce

所以：

1
2
3
4
5
6
7
8


Send
→ Map

Worker
→ Parallel Execution

Reducer / Aggregator
→ Reduce

这时候你就不再是在记“LangGraph 的一个 API”。

你在理解：

动态任务编排。

二十五、Multi-Agent：什么时候应该拆 Agent？

多 Agent 不是：

“任务复杂，所以多加几个 Agent。”

真正应该问：

1
2
3
4
5
6


职责是否天然不同？
工具是否不同？
上下文是否不同？
是否可以并行？
是否需要独立循环？
是否存在明确的角色边界？

如果没有：

单 Agent 很可能更简单。

所以：

Multi-Agent 的第一能力不是“会搭 Supervisor”，而是“会判断什么时候不需要 Multi-Agent”。

二十六、Supervisor：谁负责调度？

典型结构：

1
2
3
4
5
6
7
8
9


 Supervisor
 / | \
 ↓ ↓ ↓
 Researcher Writer Critic
 \ | /
 \ | /
 Supervisor
 ↓
 FINISH

Supervisor 的本质：

控制器。

它负责：

选 Worker
读取结果
决定下一步
判断是否结束

因此要继续问：

Worker 怎么反馈？

Supervisor 怎么知道已经完成？

什么情况下 FINISH？

如果 Worker 失败呢？

如果 Supervisor 无限循环怎么办？

二十七、Reflection：其实就是一个受控循环

1
2
3
4
5
6
7
8
9


Generate
 ↓
Critic
 ↓
Good enough?
 ├── Yes → END
 └── No → Revise
 ↓
 Generate

所以 Reflection 的真正本质是：

1
2
3
4
5


Loop
+
Evaluation
+
Conditional Exit

因此一定要有：

1

MAX_REVISE

否则：

1
2
3
4
5
6


Generate
→ Critic
→ Revise
→ Critic
→ Revise
→ ...

变成成本黑洞。

二十八、Harness：Agent 为什么不是一个 LLM

一个真正的 Agent 系统：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


 LLM
 ↓
 Agent Core
 ↓
┌─────────────────────────────┐
│ Harness │
│ │
│ Tool Registry │
│ Permission Gate │
│ Session Store │
│ Context Compaction │
│ Trace │
└─────────────────────────────┘

LLM 是：

决策能力。

Harness 是：

运行环境。

所以：

Agent 的工程能力，不等于 Prompt 能力。

二十九、Tool Registry：工具多了以后怎么办？

工具越来越多：

1
2
3
4
5


tool1
tool2
tool3
...
tool50

如果全部直接给 Agent：

1
2
3
4


工具发现困难
schema 混乱
权限混乱
冲突增加

所以 Tool Registry 管的是：

1
2
3
4
5


注册
发现
Schema
冲突
权限声明

从：

“调用工具”

升级成：

“管理工具生态”。

三十、Permission Gate：为什么权限不应该写进 Tool？

例如：

1

delete_file()

Tool 应该只关心：

如何删除。

不应该负责：

当前 Agent 有没有权限删除。

所以：

1
2
3
4
5
6
7
8
9


Agent
↓
Tool Registry
↓
Permission Gate
↓
HITL
↓
Tool

这叫：

职责分离。

三十一、Session Store：Session 和 Memory 不是同一个东西

可以简单这样理解：

1
2
3
4
5


Memory
→ Agent 记得什么

Session
→ 当前用户/任务的运行上下文

所以：

1
2


thread_id
SqliteSaver

在 W6 是持久化机制，

到了 Harness，则成为：

Session Store 的基础。

三十二、Context Compaction：为什么 Agent 越聊越长反而越危险？

如果：

1

messages = 1,000 条

全部塞进模型：

1
2
3
4


Context ↑
Cost ↑
Latency ↑
Noise ↑

所以：

1
2
3
4
5


Old Context
↓
Summary
+
Recent Messages

这和你之前做的 MemoryManager 直接连起来：

1
2
3
4
5
6
7


W3 Memory
↓
W5 MemoryGraph
↓
W6 Persistence
↓
W7 Context Compaction

你的路线不是知识点堆积，而是在不断：

把旧能力提升为更高层的系统抽象。

三十三、Trace：能运行 ≠ 能解释

如果一个 Agent 失败：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


User
 ↓
Supervisor
 ↓
Worker A
 ↓
Tool
 ↓
Worker B
 ↓
Critic
 ↓
Fail

你需要知道：

1
2
3
4
5
6


哪个节点慢？
调用了几次 LLM？
哪个 Tool 出错？
为什么选 Worker A？
为什么进入循环？
哪里消耗最多 Token？

所以 Trace 是：

把 Agent 的运行过程变成可解释、可分析的记录。

它最终会与：

1
2
3
4


Eval
Observability
Debugging
Cost Analysis

连接起来。

三十四、把整个 LangGraph 压缩成五层

以后忘记某个 API 时，先找它属于哪一层。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58


Layer 1：Flow
────────────────────
State
Node
Edge
Conditional
Loop

解决：
“Agent 怎么走？”


Layer 2：Execution
────────────────────
ToolNode
Reducer
Stream
Events

解决：
“Agent 怎么执行？”


Layer 3：Runtime
────────────────────
Checkpoint
thread_id
Persistence
HITL
Recovery

解决：
“Agent 怎么长期运行？”


Layer 4：Orchestration
────────────────────
Subgraph
Send
Map-Reduce
Multi-Agent
Supervisor
Reflection

解决：
“复杂任务怎么拆、并行、协作？”


Layer 5：Engineering
────────────────────
Tool Registry
Permission Gate
Session Store
Compaction
Trace

解决：
“怎么把 Agent 做成工程系统？”

三十五、以后每学一个知识点，固定回答这 10 个问题

这是你以后学习 LangGraph 最重要的模板。

① 它是什么？

先定义。

② 它解决什么问题？

没有它会怎样？

③ 为什么需要它？

为什么普通 Python / Chain 不够？

④ 它改变的是 State 还是 Control Flow？

这是核心分类。

⑤ Runtime 在这里做了什么？

它不是一个 API 调用就结束了。

⑥ 它和什么概念容易混淆？

主动找边界。

⑦ 为什么不用更简单的机制？

这是设计判断。

⑧ 正常情况怎么走？

画执行流。

⑨ 异常情况怎么走？

考虑：

1
2
3
4
5


failure
retry
timeout
partial result
recovery

⑩ 并发 / 顺序 / 成本 / 权限怎么办？

从 Demo 进入工程系统。

三十六、真正的 LangGraph 学习等级

不要再用：

“我学完 W6 了。”

判断自己有没有学会。

可以用这五级：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32


Level 1
API
会写

↓


Level 2
Mechanism
知道为什么能跑

↓


Level 3
Design
知道为什么这样设计

↓


Level 4
System
能组合成完整 Agent

↓


Level 5
Engineering Judgment
知道什么时候该用、什么时候不该用，
失败时怎么办，成本和边界在哪里

你的目标应该是：

至少把核心知识做到 Level 4，重要知识做到 Level 5。

三十七、真正会 LangGraph 的标准

以后有人问：

“你懂 LangGraph 吗？”

真正能证明你懂，不是：

“我会 StateGraph、Send、interrupt。”

而是你能解释：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


为什么需要 Graph？

State 怎么设计？

Node 如何拆职责？

Edge 怎么决定控制流？

Reducer 怎么定义状态更新语义？

Checkpoint 如何让执行可恢复？

HITL 如何改变控制权？

Subgraph 如何建立执行边界？

Send 为什么能动态 fan-out？

并行结果怎么 fan-in？

失败怎么处理？

什么时候单 Agent 足够？

什么时候需要 Multi-Agent？

Supervisor 为什么需要？

Harness 为什么存在？

能把这些问题连成一条因果链，你才算真正理解 LangGraph。

三十八、最终记住这一句话

LangGraph 不只是“把 Agent 画成图”。

它是在给 Agent 建立一套：

状态模型 + 控制流模型 + 执行模型 + 持久化模型 + 人机协作模型 + 并行模型 + Agent 编排模型。

API 只是这些模型暴露出来的操作入口。

所以以后看到：

1

Send(...)

不要先问：

“这个怎么写？”

先问：

它正在解决哪个 Runtime 问题？

它改变了什么执行语义？

为什么普通 Edge 不够？

任务的数据从哪里来、到哪里去？

并行后怎么合并？

失败怎么办？

什么时候根本不应该使用它？

当你开始习惯这么思考时，你学到的就不再只是 LangGraph。

而是在学习：

Agent Runtime / Workflow Orchestration / Agent System Design。

子图与 Send

Sat, 12 Sep 2026 04:13:55 +0800

子图与 Send

把图当零件，把任务动态派出去

这一天学的是 W6-D5，主题只有两个：

子图（Subgraph）：把一整张图当成一个零件，装进另一张图。 Send：一个节点根据运行时的数据，动态派出 N 份独立任务。

一开始看起来这两个知识点没有太大关系，但实际实验下来，它们都在解决同一个工程问题：

当一个 LangGraph 开始变复杂时，怎么把复杂性拆开，同时又让任务能够动态扩展？

子图负责拆复杂度，Send 负责扩任务。

一、子图：把一整张图当成一个节点

以前学 LangGraph 时，直觉上会把节点理解成：

1

START → nodeA → nodeB → nodeC → END

每个节点就是一项工作。

但当逻辑越来越复杂时，一个节点里面可能又有很多步骤。这个时候，可以把一整张小图封装起来：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


父图
START
 ↓
entry
 ↓
inner
 ↓
parent_end
 ↓
END

其中：

1

inner

并不是普通函数，而是一整张已经编译好的子图。

因此可以把子图理解成：

把一台复杂机器先独立制造、独立测试，然后把它作为一个标准零件装进另一台机器。

这样做有三个直接好处：

1. 复用

一张子图可以被多个地方使用。

2. 隔离

子图拥有自己的内部 State 和执行过程，父图不需要知道它内部每一步怎么做。

3. 分层

复杂逻辑可以收进子图，父图只需要关心：

“这个零件输入什么，输出什么？”

二、一个最小的子图实验

先单独定义子图：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


class SubState(TypedDict):
 text: str
 result: str


def shout(state: SubState) -> dict:
 return {"result": state["text"].upper() + "!"}


sub_b = StateGraph(SubState)
sub_b.add_node("shout", shout)
sub_b.add_edge(START, "shout")
sub_b.add_edge("shout", END)

subgraph = sub_b.compile()

这里最重要的一点是：

1

subgraph = sub_b.compile()

编译之后，subgraph 才可以作为父图里的节点使用。

父图：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


class ParentState(TypedDict):
 text: str
 result: str
 final: str


def entry(state: ParentState) -> dict:
 return {"text": state["text"].strip()}


def parent_end(state: ParentState) -> dict:
 return {"final": "父图收到: " + state["result"]}


p = StateGraph(ParentState)

p.add_node("entry", entry)
p.add_node("inner", subgraph)
p.add_node("parent_end", parent_end)

p.add_edge(START, "entry")
p.add_edge("entry", "inner")
p.add_edge("inner", "parent_end")
p.add_edge("parent_end", END)

parent = p.compile()

真正把子图装进去的只有这一行：

1

p.add_node("inner", subgraph)

所以可以记成：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


父图
START
 ↓
entry
 ↓
┌───────────────┐
│ inner │ ← 整张子图
│ ↓ │
│ shout │
└───────────────┘
 ↓
parent_end
 ↓
END

三、子图不是“看起来像一层”，而是真的有层级

这次实验里最值得注意的，不是代码能跑，而是怎么证明：

inner 真的包含了 shout，而不是只是在父图里有一个叫 inner 的普通节点。

开启：

1

subgraphs=True

之后，拿到的事件中出现了类似：

1
2
3
4


(
 ('inner:e7b812b0-ca7d-1088-81ae-c15b84d74fd3',),
 {'shout': {'result': 'HI!'}}
)

这里有两个非常关键的证据。

第一：

1

('inner:xxxx',)

说明当前事件带有子图的命名空间。

第二：

1

{'shout': {'result': 'HI!'}}

shout 是子图内部节点的名字。

所以：

“非空命名空间 + 子图内部独有的节点名”

比简单地判断：

1

"inner" in str(event)

更有证明力。

四、这次让我意识到：断言“绿了”不等于验证成功

这是 D5 一个比代码本身更重要的收获。

比如之前写：

1

assert any("inner" in str(ev) for ev in raw)

它确实可能变绿。

但这个断言的问题是：

1

inner

本来就是我自己给父图节点起的名字。

所以即使子图内部的 shout 完全没有暴露出来，这个断言也可能变绿。

也就是说：

断言通过，不代表它证明了我要证明的东西。

这是一种典型的“假绿”。

真正好的验证应该问：

如果实现是错的，这条断言还有可能通过吗？

如果答案是“有可能”，那这条断言就还不够强。

五、我给自己总结了一条“判据强度阶梯”

1
2
3
4
5
6
7
8
9


精确值比较
 ↓
结构化集合比较
 ↓
计数 / 长度
 ↓
子串包含
 ↓
只判断非空

例如：

1

assert result == "HELLO!"

通常比：

1

assert "HELLO" in str(result)

更有证明力。

又比如并行结果：

1

assert sorted(actual) == sorted(expected)

比：

1

assert actual == expected

更合理。

因为并行执行下：

完成顺序通常不能成为业务正确性的判断条件。

所以这次 D5 又强化了一个以后写测试时很重要的习惯：

不要问“这条断言能不能绿”，而要问“它能排除哪些错误实现”。

六、Send：一个节点动态派 N 份活

子图解决的是“拆”。

Send 解决的是“派”。

假设有：

1
2
3
4
5
6


topics = [
 "RAG",
 "Agent记忆",
 "多Agent",
 "MCP",
]

目标是：

每个 topic 都交给一个 worker 单独处理。

这时候可以：

1

Send("worker", {"topic": t})

再配合：

1

for t in state["topics"]

动态产生：

1
2
3
4


Send("worker", {"topic": "RAG"})
Send("worker", {"topic": "Agent记忆"})
Send("worker", {"topic": "多Agent"})
Send("worker", {"topic": "MCP"})

最终形成：

1
2
3
4
5
6
7


 ┌── worker(RAG) ──────┐
 │ │
topics ── router ─┼── worker(Agent记忆) ─┤
 │ ├──→ join
 ├── worker(多Agent) ───┤
 │ │
 └── worker(MCP) ──────┘

这里最关键的一点：

N 是运行时由数据决定的。

不是写死：

1
2
3


A → B
A → C
A → D

而是：

1
2
3


topics 有几条
 ↓
就派几份任务

所以可以用一句话记：

普通条件边更像“固定分岔”，Send 更像“看订单有多少行就派多少工人”。

七、Send 最容易理解错的地方：worker 的 state 到底是什么？

这是我这次真正卡住的地方。

假设主 State：

1
2
3
4


class MapState(TypedDict):
 topics: list[str]
 results: Annotated[list[str], add]
 summary: str

这里定义的是：

1
2
3


topics
results
summary

那么问题来了：

为什么 worker 可以写：

1

topic = state["topic"]

明明 MapState 根本没有：

1

topic

这个字段？

答案是：

Send 并不是给原来的 MapState 增加一个 topic 字段。

这是整个 Send 机制最容易混淆的地方。

八、Send 不修改主 State，而是给一次节点执行提供输入

例如：

1

Send("worker", {"topic": "RAG"})

这里：

1

{"topic": "RAG"}

不是：

1
2
3
4
5
6


{
 "topics": [...],
 "results": [...],
 "summary": ...,
 "topic": "RAG"
}

它也不会跑进：

1

state["topics"]

里面。

更准确的理解是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


主 State
{
 topics: [...]
 results: [...]
 summary: ...
}
 │
 │ router 计算
 ↓
Send
 │
 ├── 任务 1 → {"topic": "RAG"}
 ├── 任务 2 → {"topic": "Agent记忆"}
 ├── 任务 3 → {"topic": "多Agent"}
 └── 任务 4 → {"topic": "MCP"}

到了 worker：

1
2


def worker(state: dict) -> dict:
 topic = state["topic"]

这里的 state 指的是：

这一次 Send 任务传给 worker 的输入字典。

也就是：

1

{"topic": "RAG"}

而不是原来的：

1

MapState

九、于是两个 `state` 其实根本不是一个东西

这是以后看 LangGraph 代码时非常值得警惕的一点。

例如：

1
2


def route_to_workers(state: MapState):
 ...

这里的：

1

state

是父图当前的完整 State。

所以：

1

state["topics"]

可以取到。

但：

1
2


def worker(state: dict):
 ...

这里的：

1

state

是 Send 提供给这一次 worker 执行的数据。

所以：

1

state["topic"]

可以取到。

虽然变量都叫：

1

state

但它们不是同一个东西。

以后为了防止自己混淆，我甚至可以主动写成：

1
2
3
4
5
6
7
8
9


def route_to_workers(map_state: MapState):
 return [
 Send("worker", {"topic": t})
 for t in map_state["topics"]
 ]


def worker(worker_input: dict):
 topic = worker_input["topic"]

这样从变量名上就能直接看出来：

1
2
3
4
5
6
7


map_state
 ↓
主 State

worker_input
 ↓
某一次 Send 的输入

十、Send 的 payload 是“任务输入”，不是 State 字段更新

所以这一条应该牢牢记住：

1

Send("worker", {"topic": t})

里面：

1

{"topic": t}

是：

这个 worker 本次执行要拿到的数据。

而不是：

给主 State 增加一个 topic 字段。

这也是为什么 worker 想拿什么上下文，就必须在 Send 时考虑进去。

例如 worker 需要：

1
2
3
4


topic
user_id
检索范围
某些配置

那么这些需要的东西就要在任务输入里体现出来。

十一、为什么 Send 和普通边不是一回事

这次还踩到了一个很典型的坑。

最开始容易想写：

1

g.add_edge("distributor", "worker")

然后希望：

1
2
3
4
5


distributor
 ↓
Send(...)
 ↓
worker

但这混淆了两个职责。

可以先用一个非常实用的心智模型理解：

Node 负责干活，路由负责决定下一步去哪。

普通节点返回的是：

1

dict

例如：

1

return {"results": [r]}

这是：

“我做完了，这些是我对 State 的更新。”

而路由函数返回：

1

list[Send]

代表的是：

“下一步要派这些任务出去。”

所以最终形成：

1
2
3
4
5


Node
 ↓
返回数据
 ↓
State 更新

而：

1
2
3
4
5


Router
 ↓
返回 Send
 ↓
动态产生下一批任务

这两个职责不能混为一谈。

十二、推荐的 Send 结构

因此最终使用的是：

1
2
3


def distributor(state: MapState) -> dict:
 print(f"[distributor] 扇出 {len(state['topics'])} 份活")
 return {}

真正负责动态派工的是：

1
2
3
4
5


def route_to_workers(state: MapState) -> list[Send]:
 return [
 Send("worker", {"topic": t})
 for t in state["topics"]
 ]

构图：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


g.add_edge(START, "distributor")

g.add_conditional_edges(
 "distributor",
 route_to_workers,
 ["worker"],
)

g.add_edge("worker", "join")
g.add_edge("join", END)

这里的职责就非常清楚：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


distributor
 │
 │ 干准备工作
 ↓
route_to_workers
 │
 │ 动态计算 N
 ↓
Send × N
 │
 ↓
worker × N
 │
 ↓
reducer
 │
 ↓
join

十三、Reducer：并行结果怎么重新汇总？

4 个 worker 会分别产生：

1
2
3
4


{"results": ["RAG 完成"]}
{"results": ["Agent记忆 完成"]}
{"results": ["多Agent 完成"]}
{"results": ["MCP 完成"]}

如果 results 是普通字段，多份更新会发生冲突。

所以定义：

1

results: Annotated[list[str], add]

意思可以先理解成：

多个 worker 更新这个字段时，用 add 把它们合并。

最终得到：

1
2
3
4
5
6


[
 "RAG 完成",
 "Agent记忆 完成",
 "多Agent 完成",
 "MCP 完成",
]

因此 Send 这条链的完整逻辑是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


一份 State
 ↓
动态扇出
 ↓
N 份独立任务
 ↓
N 个 worker
 ↓
N 个结果
 ↓
Reducer 汇聚
 ↓
一个统一结果

这实际上就是经典的：

Map → Reduce

十四、一个很容易踩的 Reducer 坑

results 已经有：

1

Annotated[list[str], add]

所以 join 不应该再写：

1

return {"results": state["results"]}

因为这相当于：

已经有这一批结果了，我再把同一批结果交一次。

于是可能变成：

1
2
3
4
5


4 条
 ↓
再加一次自己
 ↓
8 条

因此 join 只需要读取：

1

state["results"]

然后产出另外一个字段：

1
2
3


return {
 "summary": " | ".join(sorted(state["results"]))
}

十五、为什么并行结果不能直接比较顺序？

这次实验还暴露了另一个很重要的测试问题。

错误倾向：

1

assert out["results"] == expected

因为 worker 是并行运行的。

哪一个 worker 先完成，并没有业务上的必要保证。

所以更合理的是：

1

assert sorted(out["results"]) == sorted(expected)

这表达的意思是：

我只关心有没有这四个结果，不关心谁先回来。

这也是一个很重要的工程原则：

不要把没有业务意义的执行顺序写进断言。

否则今天绿，明天可能突然红，而代码实际上完全没坏。

十六、并行到底有没有真的发生？不能靠“看起来快”

这次实验故意让：

1
2
3


def do_work(topic):
 time.sleep(1)
 return f"{topic} 完成"

有 4 个任务。

串行：

1
2


1s + 1s + 1s + 1s
≈ 4s

并行：

1
2
3
4


任务1 ─┐
任务2 ─┤
任务3 ─┤ → 大约同时等待 1s
任务4 ─┘

所以实测：

1
2
3


串行 ≈ 4.00s
并行 ≈ 1.02s
加速比 ≈ 3.93x

这比一句：

“看起来快很多。”

有意义得多。

十七、一个很重要的测试设计教训：门槛也需要验证

之前使用：

1

assert speedup > 2.0

看起来合理，但实际跑出来：

1

3.93x

于是发现：

2.0x 这个门槛其实太松。

假如实际只跑出了：

1

2.1x

这个断言照样会绿。

但 4 个任务的理想情况明明接近：

1

4x

所以：

一个测试阈值不能只是“差不多够用”，还要问它能不能排除明显的错误实现。

这和前面的：

1

"inner" in str(event)

其实是同一种问题。

表面上是两个完全不同的 bug，底层却是同一种思维错误：

判据太松，错误实现也可能通过。

十八、因此我现在更倾向于这样设计并行实验

如果单任务耗时是自己控制的：

1

time.sleep(1)

而且任务数量是：

1

4

那么理论上：

1
2


串行 ≈ 4s
四路并行 ≈ 1s

此时直接检查并行耗时：

1

assert par < 1.5

反而比：

1

assert speedup > 2.0

更直接。

因为这里已经知道单任务耗时。

但如果是真实系统，任务耗时本身不确定，那么绝对值阈值就不够稳定，这时才更适合做：

1

speedup = serial / parallel

再配合一个合理阈值。

所以：

测试阈值不是越严越好，而是在“误报”和“漏报”之间取舍。

十九、这次实验还让我看到 Send 的真正价值

不要把 Send 简单记成：

“Send 可以并行，所以更快。”

这个说法太粗。

真正重要的是：

Send 允许工作量 N 随运行时数据变化。

例如：

1

topics = ["RAG", "MCP"]

派：

1

2 个 worker

如果变成：

1

topics = ["RAG", "MCP", "Memory", "Agent", "Tools"]

就可以动态派：

1

5 个 worker

所以 Send 的核心价值不是“固定并行 4 个任务”。

而是：

数据有多少份工作，就动态生成多少份执行任务。

这才是它和固定条件边真正拉开差距的地方。

二十、这次 D5 最终形成了一套统一心智模型

现在可以把整个 D5 压缩成这张图：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


 主 State
 │
 │
 ┌──────▼──────┐
 │ Router │
 └──────┬──────┘
 │
 根据数据计算 N
 │
 ┌──────────┼──────────┐
 ↓ ↓ ↓
 Send(A) Send(B) Send(C)
 ↓ ↓ ↓
 worker worker worker
 │ │ │
 └──────────┼──────────┘
 ↓
 reducer
 ↓
 join

而子图是另一条维度：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


父图
│
├── entry
│
├── inner
│ │
│ ├── shout
│ ├── ...
│ └── END
│
└── parent_end

所以可以用两句话记：

子图 = 把复杂逻辑封装成零件。

Send = 把运行时出现的多份工作动态派出去。

二十一、D5 最终复盘

这一天真正值得留下来的不是几个 API，而是下面这几层理解。

第一层：会用

知道：

1

p.add_node("inner", subgraph)

可以把子图装进父图。

知道：

1

Send("worker", {"topic": t})

可以动态创建任务。

第二层：知道数据怎么走

主 State：

1
2
3


topics
results
summary

经过 router：

1
2
3


topics
 ↓
Send payload

进入 worker：

1

{"topic": "..."}

worker 完成：

1

{"results": [...]}

Reducer：

1
2
3


多个 results
 ↓
一个 results

join：

1
2
3


results
 ↓
summary

第三层：理解 State 的边界

最容易产生错觉的是：

1

state

这个名字。

但：

1

router(state)

里的 state

和：

1

worker(state)

里的 state

不一定是同一个 State。

变量叫 state，不代表它一定是整张图的共享 State。

在 Send 场景里：

1

Send("worker", {"topic": t})

里的 payload 就是这次 worker 执行的输入数据。

所以：

1

worker_input["topic"]

拿到的是 Send 给这一份任务的数据，而不是主 State 新增的字段。

第四层：真正开始理解“验证设计”

这次最重要的额外收获，可能甚至不是 LangGraph。

而是：

“程序跑通”和“我证明它正确”是两回事。

例如：

1

assert "inner" in str(ev)

程序可以绿。

但不代表真的证明了子图内部存在。

例如：

1

assert speedup > 2.0

程序可以绿。

但不代表并发度足够。

所以以后写实验时，我需要问自己：

1
2
3
4
5
6
7


我要证明什么？
 ↓
什么现象只能由“正确实现”产生？
 ↓
错误实现有没有可能也出现这个现象？
 ↓
如果能，当前判据就不够强。

这其实比“会写断言”更重要。

二十二、最后把 D5 压缩成一张脑图

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


 LangGraph D5
 │
 ┌──────────────┴──────────────┐
 ↓ ↓
 子图 Send
 │ │
 图 → 零件 数据 → N 份任务
 │ │
 独立构建/测试 动态扇出
 │ │
 装入父图 worker × N
 │ │
 隔离/分层 ↓
 │ reducer
 ↓ │
 父图 ← 子图结果 ↓
 join

最后只记三句话：

子图是封装复杂度。

Send 是动态扩展执行任务。

Reducer 是把并行产生的多个结果重新汇成一个 State。

而贯穿整个实验的第四句话是：

“全绿”不是证据，能排除错误实现的判据才是证据。

从让图停下来，到回到过去

Thu, 10 Sep 2026 09:54:52 +0800

W6-D4 · 从让图停下来，到回到过去

D3 学的是：

怎么让图停下来问人。

D4 是同一天的第二份代码。

今天不再往 HITL 上堆新按钮，而是顺着 D3 往前走一步：
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
D3：
图停下来
↓
人回答
↓
从 checkpoint 继续

D4：
图已经有 checkpoint
↓
我能不能自己挑一个过去的 checkpoint？
↓
从那里重新跑？
答案是：

可以。

这就是 LangGraph 的 Time Travel。

一、先看今天到底学什么

今天的实验故意不用 LLM。

因为我真正想验证的不是：

“模型会说什么。”

而是：

“到底哪些节点被重新执行了？”

所以把图简化成：

1
2
3
4
5
6
7
8
9


START
 ↓
 A
 ↓
 B
 ↓
 C
 ↓
 END

完整跑一次以后，LangGraph 会留下多个 checkpoint。

于是我现在可以：

1
2
3
4
5


历史：

START → A → B → C → END
 ↑
 这个 checkpoint

然后从这里重新跑：

1
2
3
4
5


checkpoint
 ↓
 B
 ↓
 C

A 不应该再跑。

这就是今天最重要的验证目标。

二、完整代码先看一遍

今天的实验代码很短。

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293


"""W6-D4：时间旅行 —— Replay + Fork"""

import io
import contextlib

from typing import Annotated, TypedDict

from langgraph.graph import (
 StateGraph,
 START,
 END,
)

from langgraph.graph.message import add_messages
from langgraph.checkpoint.memory import MemorySaver


class T(TypedDict):
 messages: Annotated[list, add_messages]

 # 普通字段：
 # 专门用来测试“改档以后未来会不会发生变化”
 way: str


def step_a(state: T) -> dict:
 print("→ A 执行")

 return {
 "messages": [
 ("ai", "A 完成")
 ]
 }


def step_b(state: T) -> dict:
 way = (
 state.get("way")
 or "默认方式"
 )

 print(
 f"→ B 执行 ({way})"
 )

 return {
 "messages": [
 ("ai", f"B 完成 ({way})")
 ]
 }


def step_c(state: T) -> dict:
 print("→ C 执行")

 return {
 "messages": [
 ("ai", "C 完成")
 ]
 }


builder = StateGraph(T)

builder.add_node("a", step_a)
builder.add_node("b", step_b)
builder.add_node("c", step_c)

builder.add_edge(START, "a")
builder.add_edge("a", "b")
builder.add_edge("b", "c")
builder.add_edge("c", END)

graph = builder.compile(
 checkpointer=MemorySaver()
)


cfg = {
 "configurable": {
 "thread_id": "tt-1"
 }
}


# ① 先完整跑一遍
log = io.StringIO()

with contextlib.redirect_stdout(log):
 r0 = graph.invoke(
 {
 "messages": [
 (
 "user",
 "完整跑一遍 A B C"
 )
 ]
 },
 cfg,
 )

print(
 "原始跑完：",
 log.getvalue()
 .replace("\n", " | ")
 .strip()
)

print(
 "原始消息数：",
 len(r0["messages"])
)


# ② 查看历史 checkpoint
snaps = list(
 graph.get_state_history(cfg)
)

for i, s in enumerate(snaps):

 cid = (
 s.config[
 "configurable"
 ][
 "checkpoint_id"
 ]
 )

 print(
 f"#{i} "
 f"cid={cid[:8]} "
 f"next={s.next} "
 f"消息数="
 f"{len(s.values['messages'])}"
 )


# ③ 找到：
# A 已完成
# B 还没执行
#
# 也就是：
#
# next == ("b",)

target = next(
 s
 for s in snaps
 if s.next == ("b",)
)

tcid = (
 target.config[
 "configurable"
 ][
 "checkpoint_id"
 ]
)


# ④ Replay
#
# None = 不传新输入
# target.config = 从这个 checkpoint 开始

log2 = io.StringIO()

with contextlib.redirect_stdout(log2):

 r_replay = graph.invoke(
 None,
 target.config,
 )

txt_replay = log2.getvalue()

print(
 "回放日志：",
 txt_replay
 .replace("\n", " | ")
 .strip()
)


# ⑤ Fork
#
# 从同一个历史 checkpoint
# 修改 way

new_cfg = graph.update_state(
 target.config,
 {
 "way": "另一种方式"
 },
)

log3 = io.StringIO()

with contextlib.redirect_stdout(log3):

 r_fork = graph.invoke(
 None,
 new_cfg,
 )

txt_fork = log3.getvalue()

print(
 "分叉日志：",
 txt_fork
 .replace("\n", " | ")
 .strip()
)


# ⑥ 断言
#
# Replay：
# B / C 必须出现
# A 必须不能出现

assert (
 "→ B 执行 (默认方式)"
 in txt_replay
)

assert (
 "→ C 执行"
 in txt_replay
)

assert (
 "→ A 执行"
 not in txt_replay
)


# Fork：
# B 应该读到修改后的 way

assert (
 "→ B 执行 (另一种方式)"
 in txt_fork
)

assert (
 "→ A 执行"
 not in txt_fork
)


# 不要检查 messages[-1]
# 因为最后一条消息是 C。
#
# 应该检查 B 那条消息。

fork_text = " | ".join(
 str(m.content)
 for m in r_fork["messages"]
)

assert (
 "B 完成 (另一种方式)"
 in fork_text
)


# 原 checkpoint 还应该存在
snaps_after = list(
 graph.get_state_history(cfg)
)

cids_after = [
 s.config[
 "configurable"
 ][
 "checkpoint_id"
 ]
 for s in snaps_after
]

assert tcid in cids_after

assert (
 len(snaps_after)
 > len(snaps)
)


print(
 "✅ 时间旅行实验通过"
)

先不要急着理解每一行。

只看：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


完整运行
 ↓
保存 checkpoint
 ↓
找到 B 前面的 checkpoint
 ↓
Replay
 ↓
Fork
 ↓
断言

这就是今天的骨架。

三、第一块：为什么实验故意不用 LLM？

1
2


def step_a(state):
 print("→ A 执行")

1
2


def step_b(state):
 print("→ B 执行")

1
2


def step_c(state):
 print("→ C 执行")

这里没有模型，没有 API，没有随机性。

因为我要证明：

“Replay 到底跳过了哪些节点？”

如果 B/C 出现，A 没出现，我就能比较干净地证明：

1
2


B、C 重跑
A 没重跑

官方对 Replay 的定义也是：从历史 checkpoint 重新执行后续节点，checkpoint 之前的节点不重新执行。

所以今天这个实验越简单越好。

四、第二块：为什么需要 `way`？

1
2
3


class T(TypedDict):
 messages: Annotated[list, add_messages]
 way: str

A/C 不关心 way。

只有 B：

1
2
3
4


way = (
 state.get("way")
 or "默认方式"
)

然后打印：

1

→ B 执行 (默认方式)

这样我以后修改：

1

way = "另一种方式"

就可以观察：

未来的 B 有没有真的发生变化。

所以：

1

way

不是业务需求。

它只是一个：

“改档到底有没有影响未来”的实验开关。

五、第三块：第一次完整运行，制造历史

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


graph.invoke(
 {
 "messages": [
 (
 "user",
 "完整跑一遍 A B C"
 )
 ]
 },
 cfg,
)

先让它完整跑：

1
2
3
4
5
6
7


A
↓
B
↓
C
↓
END

这一跑非常重要。

因为：

没有历史，就没有时间旅行。

现在 checkpoint 历史里应该已经保存了多个状态。

六、第四块：`get_state_history()` = 打开存档列表

1
2
3


snaps = list(
 graph.get_state_history(cfg)
)

这就是今天第一个新 API。

它的意思：

把这个 thread 的历史 checkpoint 全拿出来。

当前 LangGraph 文档说明，历史是按新 → 旧返回的。

所以：

1

index = 0

不是最早。

反而是：

最新。

这就是一个特别容易记反的坑。

七、第五块：每个 checkpoint 只先看三个东西

1
2
3


s.config
s.values
s.next

这三个东西是今天最重要的。

可以直接记：

1
2
3
4
5
6
7
8


.config
→ 钥匙

.values
→ 内容

.next
→ 待办

官方 StateSnapshot 也是这样定义的：.values 是当前状态值，.next 是下一步要执行的节点，.config 是读取该快照时使用的配置。

八、`next` 是今天挑档的关键

假设时间线：

1
2
3
4
5
6
7
8
9


START
 ↓
 A
 ↓
 B
 ↓
 C
 ↓
END

某个 checkpoint：

1
2


A 已经完成
B 还没开始

它的：

1

s.next

就是：

1

("b",)

这句话其实非常好懂：

下一步该执行 B。

所以我想：

“如果我要从 B 开始重跑，那就找 next == ("b",) 的 checkpoint。”

于是：

1
2
3
4
5


target = next(
 s
 for s in snaps
 if s.next == ("b",)
)

这就是：

挑档。

九、为什么 `next == ()` 的档不要选？

如果：

1

s.next == ()

意思是：

已经没有下一步。

也就是：

1
2
3
4
5
6
7


A
↓
B
↓
C
↓
END

已经全部完成。

这个 checkpoint 拿来 replay：

1
2
3
4


graph.invoke(
 None,
 s.config
)

不会有什么可执行的东西。

所以：

挑 checkpoint 时，先看 next。

想重跑 B/C：

1
2
3


找：

next == ("b",)

十、这里再回头看 D3：其实你早就在用“时间旅行”

D3 的：

1
2
3


Command(
 resume="approve"
)

当时我是：

让 LangGraph 自动找到应该恢复的 checkpoint。

D4 做的只是：

1
2
3


把 checkpoint 历史列表打开
↓
自己选哪一档

所以可以这样理解：

1
2
3
4
5


D3：
自动读档

D4：
手动选档

这就是为什么 D4 看起来像新知识，但其实和 D3 是一条线。

十一、第六块：Replay

真正关键的一行：

1
2
3
4


r_replay = graph.invoke(
 None,
 target.config,
)

这里：

1

None

非常重要。

它表示：

不传新的输入。

而：

1

target.config

表示：

从 target 这个 checkpoint 开始。

所以整句话就是：

“把存档读到这里，从这里继续玩。”

官方文档的 Replay 示例也是 graph.invoke(None, checkpoint.config)；checkpoint 之前的节点不会重新执行，之后的节点重新执行。

十二、今天最重要的问题：怎么证明真的只重跑 B/C？

这里不能只看：

1
2


→ B 执行
→ C 执行

因为：

A 也可能偷偷跑过。

所以我专门设计三个断言：

1
2
3
4
5


assert "→ B 执行 (默认方式)" in txt_replay

assert "→ C 执行" in txt_replay

assert "→ A 执行" not in txt_replay

前两个证明：

B/C 确实执行了。

第三个最关键：

A 没执行。

所以今天最值钱的结论其实是：

“没有发生什么”，也是证据。

这和普通“跑通代码”的区别很大。

十三、消息数为什么还能作为第二层证据？

如果目标 checkpoint：

1

messages = 2

里面是：

1
2


Human
A

Replay 后：

1
2
3
4


Human
A
B
C

所以：

1

2 → 4

这可以作为第二层证据。

也就是说：

1
2
3
4
5


日志：
没有 A，只有 B/C

消息：
2 → 4

两边都支持：

这是真 Replay，不是从头跑。

十四、第七块：Fork

Replay 是：

1
2
3


过去是什么
↓
原样重新走

Fork 是：

1
2
3
4
5


过去是什么
↓
我改一点
↓
看看另一条未来

代码：

1
2
3
4
5
6


new_cfg = graph.update_state(
 target.config,
 {
 "way": "另一种方式"
 },
)

注意：

这里的 target.config 是过去的存档钥匙。

然后 update_state() 在这个历史点上改 state，并返回新的 config。

官方文档明确说明，update_state() 不会覆盖原来的 checkpoint，而是创建新的分支；之后再用这个新 config invoke(None, new_cfg) 继续执行。

十五、Fork 为什么能改变未来？

原来：

1
2
3
4
5


A
 ↓
B（默认方式）
 ↓
C

改完以后：

1
2
3
4
5


A
 ↓
B（另一种方式）
 ↓
C

因为 B 每次都会读：

1

state["way"]

所以：

改变过去的 state，未来节点就会看到新的值。

这就是 Fork 最核心的意思。

不是：

“把历史改掉。”

而是：

“从这个历史点长出另一条未来。”

十六、这里为什么一定使用 `new_cfg`？

不要这样：

1
2
3
4
5
6
7
8
9


graph.update_state(
 target.config,
 {"way": "另一种方式"}
)

graph.invoke(
 None,
 target.config,
)

而要：

1
2
3
4
5
6
7
8
9


new_cfg = graph.update_state(
 target.config,
 {"way": "另一种方式"},
)

graph.invoke(
 None,
 new_cfg,
)

因为：

1
2
3
4
5


target.config
→ 原来的过去

new_cfg
→ 新分支的钥匙

可以理解成：

1
2
3
4
5


旧 checkpoint
 │
 ├── 原分支
 │
 └── new_cfg → 新分支

十七、今天真正坑我的地方：断言也会写错

这一次非常值得单独记录。

原本写了：

1
2
3
4


assert (
 "另一种方式"
 in r_fork["messages"][-1].content
)

结果红了。

一开始我以为：

“难道 Fork 没生效？”

但看日志：

1
2


→ B 执行 (另一种方式)
→ C 执行

已经明确证明：

Fork 生效了。

真正的问题是：

1

r_fork["messages"][-1]

最后一条是：

1

C

而不是：

1

B

所以：

断言检查错地方了。

这件事让我重新意识到：

AssertionError 不等于业务代码有 bug。

首先要排查三件事：

1
2
3
4
5


① 机制错了？

② 断言写错了？

③ 验证目标本身就错了？

这次属于：

第三种。

十八、而且我后来又连续猜错了

第一轮：

messages[-1] 看错了。

这个判断是对的。

然后我又直接猜了一版字符串断言。

结果又红。

接着猜：

“是不是中文全角括号？”

还是错。

最后把字符串真正打印出来，再看字符：

1

repr(text)

发现真正的问题是：

多了两个空格。

这次才真正找到原因。

所以今天留下了一条非常值钱的纪律：

不要猜字符串为什么不相等，把“真身”打印出来。

例如：

1
2
3
4
5


print(
 repr(
 r_fork["messages"][2].content
 )
)

必要时甚至可以：

1
2
3
4
5
6


print(
 [
 hex(ord(c))
 for c in text
 ]
)

机器算出来的东西，比肉眼看：

1

B完成(另一种方式)

可靠得多。

十九、所以断言最好断结构，不要硬编码整句话

例如：

1
2
3
4


assert (
 r_fork.get("way")
 == "另一种方式"
)

这种结构断言比较稳。

如果还想证明：

B 真的使用了这个值。

再加行为断言：

1
2
3
4
5
6
7
8
9


assert (
 "→ B 执行"
 in txt_fork
)

assert (
 "另一种方式"
 in txt_fork
)

于是：

1
2
3
4
5


结构证据：
state 已经改了

行为证据：
B 真读到了修改后的值

两个一起才完整。

二十、最终的 8 项验证在证明什么？

这次实验不是“写几个 assert 装样子”。

每一个断言都对应一个机制。

Replay

1

B 出现

→ B 确实重跑。

1

C 出现

→ C 确实重跑。

1

A 不出现

→ A 没重跑。

1

消息数只增加 2

→ 确实只是补上 B/C。

Fork

1

B 读到“另一种方式”

→ 修改真的影响未来。

1

A 不出现

→ 没有从头跑。

1

原 checkpoint 还存在

→ 没有覆盖历史。

1

checkpoint 数量增加

→ 新分支真的产生了。

所以：

断言不是为了证明“程序没报错”，而是为了证明“机制就是我以为的机制”。

二十一、Time Travel 的两个玩法

现在终于可以把今天的两个 API 摆在一起。

	Replay	Fork
做什么	原样回放	改状态后再走
API	`invoke(None, old_config)`	`update_state()` → `invoke(None, new_config)`
前置节点	不重跑	不重跑
后续节点	重跑	重跑
原历史	保留	保留
用途	调试 / 复现	what-if / 替代方案

官方也是这么定义 Replay 与 Fork 的。

类比 RPG：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


Replay：
读档重玩


Fork：
读档
+
开修改器
+
再玩一遍

二十二、这就是 D4 和 D3 的连接

现在回头看 D3。

D3：

1
2
3
4
5
6
7


interrupt()
 ↓
checkpoint
 ↓
Command(resume)
 ↓
继续

D4：

1
2
3
4
5
6
7


get_state_history()
 ↓
看到所有 checkpoint
 ↓
自己挑一个
 ↓
invoke(None, target.config)

所以：

D3 是自动选档。

D4 是手动选档。

这也是为什么我现在觉得 Time Travel 没有那么神秘。

它只是把：

1

“框架替我找哪份存档”

变成：

1

“我自己决定回到哪份存档”

二十三、最后一个边界：回档不是撤销现实世界

这个必须单独记。

如果一个工具已经：

1

真的删除文件

然后我回到删除之前的 checkpoint。

这不代表：

1

文件自动恢复。

Time Travel 管的是：

Agent 的状态和决策历史。

不是：

现实世界的副作用。

所以：

1
2
3


回档
≠
撤销真实操作

这也是为什么生产系统里，Time Travel 和：

1
2
3


idempotency
side effect
compensation

必须分开考虑。

二十四、今天真正要记的其实只有这一张图

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


 D3
 │
 interrupt + resume
 │
 ▼
 自动找到 checkpoint
 │
 ▼
 继续


 D4
 │
 get_state_history()
 │
 ▼
 打开历史存档列表
 │
 ▼
 挑档
 / \
 / \
 Replay Fork
 │ │
 │ update_state()
 │ │
 │ ▼
 │ 新分支
 │ │
 └──────┬─────────┘
 ▼
 invoke(None)
 │
 ▼
 重跑后半段

再压缩成一句：

D3 是自动读档，D4 是手动读档。

二十五、今天的收尾复习卡

我只需要记住 5 个东西

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


thread_id
→ 哪条历史


checkpoint_id
→ 哪一帧


snapshot.next
→ 下一步该谁


Replay
→ 原样读档


Fork
→ 改档后长出另一条未来

再记一个验证原则：

“B/C 出现”证明它们跑了；“A 没出现”才证明它没有从头跑。

最后再记今天最真实的一课：

断言失败以后，不要立刻改断言。

先问：
1
2
3
机制错了吗？
断言错了吗？
验证目标错了吗？
这次真正让我翻车的，不是 LangGraph，而是我自己写了一个未经验证的断言。

二十六、完整源码

下面这份就是今天的最终学习版。

我把你原来的实验保留了下来，只修正了那个会因为检查 messages[-1] 而误报的断言，并把失败信息尽量写得更容易排查。

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855


"""
W6-D4 实验：Time Travel
=======================

目标：

1. 完整运行 A → B → C
2. 查看历史 checkpoint
3. 找到 next == ("b",) 的 checkpoint
4. Replay：
 - B 重跑
 - C 重跑
 - A 不重跑
5. Fork：
 - 修改 way
 - B 使用新的 way
 - A 不重跑
6. 验证：
 - 原 checkpoint 仍然存在
 - checkpoint 总数增加

注意：

这个实验故意不用 LLM。

因为今天真正要验证的是：
“到底哪些节点被重新执行”。

确定性越高，证据越干净。
"""

import io
import contextlib

from typing import Annotated, TypedDict

from langgraph.graph import (
 StateGraph,
 START,
 END,
)

from langgraph.graph.message import (
 add_messages,
)

from langgraph.checkpoint.memory import (
 MemorySaver,
)


# ============================================================
# 1. State
# ============================================================

class T(TypedDict):

 # 消息历史
 messages: Annotated[
 list,
 add_messages,
 ]

 # 普通字段。
 #
 # 专门用于：
 # “修改历史 state 后，
 # 未来节点是不是会看到新值？”
 way: str


# ============================================================
# 2. A 节点
# ============================================================

def step_a(state: T) -> dict:

 # 这句 print 是实验判据。
 #
 # Replay 时：
 #
 # 如果这里再次出现，
 # 就说明 A 被重新执行了。
 print(
 "→ A 执行"
 )

 return {
 "messages": [
 (
 "ai",
 "A 完成",
 )
 ]
 }


# ============================================================
# 3. B 节点
# ============================================================

def step_b(state: T) -> dict:

 # 默认情况下：
 #
 # way = ""
 #
 # 所以显示“默认方式”。
 #
 # Fork 后：
 #
 # update_state()
 # 把 way 改成“另一种方式”
 #
 # 那么 B 就会看到新值。
 way = (
 state.get("way")
 or "默认方式"
 )

 print(
 f"→ B 执行 ({way})"
 )

 return {
 "messages": [
 (
 "ai",
 f"B 完成 ({way})",
 )
 ]
 }


# ============================================================
# 4. C 节点
# ============================================================

def step_c(state: T) -> dict:

 print(
 "→ C 执行"
 )

 return {
 "messages": [
 (
 "ai",
 "C 完成",
 )
 ]
 }


# ============================================================
# 5. 构建图
# ============================================================

builder = StateGraph(T)

builder.add_node(
 "a",
 step_a,
)

builder.add_node(
 "b",
 step_b,
)

builder.add_node(
 "c",
 step_c,
)


# ------------------------------------------------------------
# 图结构：
#
# START → A → B → C → END
# ------------------------------------------------------------

builder.add_edge(
 START,
 "a",
)

builder.add_edge(
 "a",
 "b",
)

builder.add_edge(
 "b",
 "c",
)

builder.add_edge(
 "c",
 END,
)


# ============================================================
# 6. 编译
# ============================================================
#
# checkpointer 是 Time Travel 的基础。
#
# 没有 checkpoint：
# 就没有历史可以选。
#

graph = builder.compile(
 checkpointer=MemorySaver()
)


# ============================================================
# 7. thread_id
# ============================================================
#
# thread_id：
# “我是哪条历史？”
#

cfg = {
 "configurable": {
 "thread_id": "tt-1"
 }
}


# ============================================================
# 8. 第一次完整运行
# ============================================================
#
# 先把 A/B/C 全部跑一遍，
# 制造出后面可以回去看的历史。
#

print(
 "\n" + "=" * 60
)

print(
 "第一次运行："
 "完整执行 A → B → C"
)

print(
 "=" * 60
)


log = io.StringIO()

with contextlib.redirect_stdout(
 log
):

 r0 = graph.invoke(
 {
 "messages": [
 (
 "user",
 "完整跑一遍 A B C",
 )
 ],

 # 初始化 way
 "way": "",
 },
 cfg,
 )


print(
 "原始跑完：",
 log.getvalue()
 .replace("\n", " | ")
 .strip(),
)


# 预期：
#
# Human
# A
# B
# C
#
# = 4 条消息

print(
 "原始消息数：",
 len(
 r0["messages"]
 ),
)


# ============================================================
# 9. 查看全部 checkpoint
# ============================================================
#
# get_state_history()
# 返回这一条 thread 的历史。
#
# 当前 LangGraph 是：
# 新 → 旧
#

print(
 "\n" + "=" * 60
)

print(
 "历史 checkpoint："
 "新 → 旧"
)

print(
 "=" * 60
)


snaps = list(
 graph.get_state_history(
 cfg
 )
)


print(
 "checkpoint 数量：",
 len(snaps),
)


for i, s in enumerate(
 snaps
):

 # ------------------------------------------
 # config
 #
 # 里面有：
 #
 # thread_id
 # checkpoint_id
 # ------------------------------------------

 cid = (
 s.config[
 "configurable"
 ][
 "checkpoint_id"
 ]
 )

 # ------------------------------------------
 # next
 #
 # 下一步该执行谁
 # ------------------------------------------

 next_nodes = s.next

 # ------------------------------------------
 # values
 #
 # 当前 state 内容
 # ------------------------------------------

 message_count = len(
 s.values[
 "messages"
 ]
 )

 print(
 f"#{i} "
 f"cid={cid[:8]} "
 f"next={next_nodes} "
 f"消息数={message_count}"
 )


# ============================================================
# 10. 找目标 checkpoint
# ============================================================
#
# 我想：
#
# A 不重跑
# B/C 重跑
#
# 所以我要找：
#
# next == ("b",)
#
# 这意味着：
#
# A 已完成
# B 还没执行
#

target = next(
 s
 for s in snaps
 if s.next == ("b",)
)


target_checkpoint_id = (
 target.config[
 "configurable"
 ][
 "checkpoint_id"
 ]
)


print(
 "\n目标 checkpoint：",
 target_checkpoint_id[:8],
)

print(
 "目标 next：",
 target.next,
)

print(
 "目标消息数：",
 len(
 target.values[
 "messages"
 ]
 ),
)


# ============================================================
# 11. Replay
# ============================================================
#
# 关键：
#
# invoke(None, target.config)
#
# None：
# 不提供新输入
#
# target.config：
# 从这一个 checkpoint 开始
#

print(
 "\n" + "=" * 60
)

print(
 "Replay："
 "从 B 前面的 checkpoint 继续"
)

print(
 "=" * 60
)


log2 = io.StringIO()

with contextlib.redirect_stdout(
 log2
):

 r_replay = graph.invoke(
 None,

 target.config,
 )


txt_replay = (
 log2.getvalue()
)


print(
 "回放日志：",
 txt_replay
 .replace("\n", " | ")
 .strip(),
)


print(
 "回放后消息数：",
 len(
 r_replay[
 "messages"
 ]
 ),
)


# ============================================================
# 12. Replay 断言
# ============================================================
#
# 这部分是今天最重要的。
#
# 不是：
# “看起来像 replay”
#
# 而是：
# “用断言证明 replay”
#

print(
 "\n" + "=" * 60
)

print(
 "Replay 断言"
)

print(
 "=" * 60
)


# B 必须重跑
assert (
 "→ B 执行 (默认方式)"
 in txt_replay
), (
 "B 没有重跑"
)


# C 必须重跑
assert (
 "→ C 执行"
 in txt_replay
), (
 "C 没有重跑"
)


# ------------------------------------------------------------
# ★ 最关键
#
# A 不能重跑。
#
# 如果出现：
#
# → A 执行
#
# 就说明这不是我们想验证的 replay。
# ------------------------------------------------------------

assert (
 "→ A 执行"
 not in txt_replay
), (
 "A 竟然重跑了："
 "这说明没有从目标 checkpoint replay"
)


# ------------------------------------------------------------
# 消息数：
#
# 原来：
#
# 2
#
# Replay B/C：
#
# +2
#
# 最终：
#
# 4
# ------------------------------------------------------------

expected_count = (
 len(
 target.values[
 "messages"
 ]
 )
 + 2
)

assert (
 len(
 r_replay[
 "messages"
 ]
 )
 == expected_count
), (
 "Replay 消息数量不符合预期："
 f"expected={expected_count}, "
 f"actual={len(r_replay['messages'])}"
)


print(
 "✅ Replay 断言通过"
)


# ============================================================
# 13. Fork
# ============================================================
#
# 从同一个历史 checkpoint：
#
# 修改 way
#
# 原来：
# 默认方式
#
# 新分支：
# 另一种方式
#

print(
 "\n" + "=" * 60
)

print(
 "Fork："
 "修改过去，再发展新的未来"
)

print(
 "=" * 60
)


new_cfg = graph.update_state(
 target.config,
 {
 "way": "另一种方式"
 },
)


new_checkpoint_id = (
 new_cfg[
 "configurable"
 ][
 "checkpoint_id"
 ]
)


print(
 "原 checkpoint：",
 target_checkpoint_id[:8],
)

print(
 "新 checkpoint：",
 new_checkpoint_id[:8],
)


# ============================================================
# 14. 从 fork 后的新 config 继续
# ============================================================

log3 = io.StringIO()

with contextlib.redirect_stdout(
 log3
):

 r_fork = graph.invoke(
 None,
 new_cfg,
 )


txt_fork = (
 log3.getvalue()
)


print(
 "分叉日志：",
 txt_fork
 .replace("\n", " | ")
 .strip(),
)


# ============================================================
# 15. Fork 断言
# ============================================================

print(
 "\n" + "=" * 60
)

print(
 "Fork 断言"
)

print(
 "=" * 60
)


# ------------------------------------------------------------
# B 必须看到修改后的 way
# ------------------------------------------------------------

assert (
 "→ B 执行 (另一种方式)"
 in txt_fork
), (
 "B 没有读取到 fork 后的新值"
)


# ------------------------------------------------------------
# A 不应该重新执行
# ------------------------------------------------------------

assert (
 "→ A 执行"
 not in txt_fork
), (
 "A 不应该因为 fork 又重跑"
)


# ------------------------------------------------------------
# 不要写：
#
# r_fork["messages"][-1]
#
# 因为最后一条消息是 C。
#
# 我要验证的是：
# B 那一条消息
# ------------------------------------------------------------

fork_text = " | ".join(
 str(
 message.content
 )
 for message
 in r_fork["messages"]
)


assert (
 "B 完成 (另一种方式)"
 in fork_text
), (
 "Fork 结果中没有找到 "
 "B 使用新 way 的证据："
 f"{fork_text!r}"
)


print(
 "✅ Fork 断言通过"
)


# ============================================================
# 16. 验证原历史仍然存在
# ============================================================
#
# Fork：
#
# 不是覆盖原历史
#
# 而是：
#
# 从过去长出新分支
#

snaps_after = list(
 graph.get_state_history(
 cfg
 )
)


checkpoint_ids_after = [
 s.config[
 "configurable"
 ][
 "checkpoint_id"
 ]

 for s in snaps_after
]


# 原 checkpoint 必须还存在
assert (
 target_checkpoint_id
 in checkpoint_ids_after
), (
 "原 checkpoint 消失了"
)


# Fork 后应该出现更多 checkpoint
assert (
 len(snaps_after)
 >
 len(snaps)
), (
 "Fork 没有产生新的 checkpoint"
)


# ============================================================
# 17. 最终结果
# ============================================================

print(
 "\n" + "=" * 60
)

print(
 "✅ Time Travel 实验全部通过"
)

print(
 "Replay："
 "B/C 重跑，A 没重跑"
)

print(
 "Fork："
 "B 使用新 way，原历史仍然存在"
)

print(
 "=" * 60
)

二十六、最后收成一张卡

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42


W6-D4
────────────────────────

D3：
自动恢复 checkpoint

D4：
手动挑 checkpoint


get_state_history()
 ↓
 存档列表

snap.next
 ↓
 下一步是谁

snap.config
 ↓
 这份存档的钥匙

invoke(None, snap.config)
 ↓
 Replay

update_state(...)
 ↓
 Fork

Replay：
原样重跑未来

Fork：
改档后重跑未来


最重要的验证：

B 出现 ✅
C 出现 ✅
A 不出现 ✅

还有今天额外学到的一条：

断言失败，不要马上改断言。

先问：

机制错了？断言错了？还是验证目标错了？

这一天真正收尾的地方，不是：

1

✅ 8 个断言全绿

而是：

我开始知道，连“验证代码”本身也需要被验证。

D3 学的是：

让图停下来问人。

D4 学的是：

既然图会存档，那我就可以自己挑过去，重新走未来。

到这里，W6 前四天其实已经连成一条线：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


存档
 ↓
停下来
 ↓
人干预
 ↓
改状态
 ↓
回到过去
 ↓
重新走未来

这就是这一天的新知识，也是 HITL 这一章的真正收尾。

让图停下来问人

Wed, 09 Sep 2026 11:06:52 +0800

让图停下来问人

今天终于把 LangGraph 的 HITL 串起来了。

前面一直觉得 interrupt()、Command(resume)、update_state、checkpoint 是几个分散的 API，直到把代码跑通后才发现，它们其实只是在解决三个问题：
1
2
3
什么时候停？
停下来以后怎么继续？
人能不能修改下一步？
这篇不展开讲理论，直接从代码看。

一、先看最终流程

今天的代码最后是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


START
 ↓
decide
 ↓
approve
 ↓
tools
 ↓
audit
 ↓
summarize
 ↓
END

其中：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


decide
→ 模型决定要调用什么工具

approve
→ 人审批

tools
→ 真正执行

audit
→ 记录“这是审批人改的”

summarize
→ 最后总结，而且没有工具权限

今天还有一个额外实验：

1
2
3
4
5
6
7


checkpoint
 ↓
get_state_history()
 ↓
挑历史存档
 ↓
Replay / Fork

二、为什么 `decide` 和 `approve` 必须拆开？

先看：

1
2
3


def decide(state):
 ai_msg = llm.invoke(state["messages"])
 return {"messages": [ai_msg]}

它只做一件事：

让模型产生 tool_calls，然后先写进 state。

例如：

1
2
3


AIMessage
└── tool_calls
 └── delete_file("/tmp/a.txt")

下一步才进入：

1
2


def approve(state):
 answer = interrupt(...)

这里有一个非常容易踩坑的地方：

interrupt() 恢复时，所在节点会重新执行。

所以不能：

1
2
3


def agent(state):
 ai_msg = llm.invoke(...)
 answer = interrupt(...)

因为第一次执行到 interrupt() 时，还没 return，ai_msg 还没进入 state。

所以要拆成：

1
2
3
4
5


decide
→ 先落 state

approve
→ 再 interrupt

这样人暂停时，state 里已经有完整的 AIMessage.tool_calls。

三、`interrupt()` 到底怎么恢复？

第一次：

1
2
3
4
5


approve
 ↓
interrupt()
 ↓
暂停

人回答：

1

Command(resume="approve")

恢复以后不是简单地从 interrupt() 下一行继续，而是：

1
2
3
4
5
6
7
8
9


approve
 ↓
重新执行节点
 ↓
再次来到 interrupt()
 ↓
这次得到 "approve"
 ↓
继续

所以：

1
2


[approve]
[approve]

出现两次是正常的。

这也意味着：

interrupt() 前面最好不要放不可安全重跑的副作用。

四、三态审批：`approve / reject / edit`

现在人不只是：

1
2


approve
reject

还可以：

1

edit

例如模型原本准备：

1

delete_file("/tmp/a.txt")

人说：

1

edit

然后图外：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


st = graph.get_state(cfg)

last = st.values["messages"][-1]

fixed = AIMessage(
 id=last.id,
 content=last.content,
 tool_calls=new_tool_calls,
)

graph.update_state(
 cfg,
 {
 "messages": [fixed],
 "audit_note": "审批人把 a.txt 改成了 old.txt",
 },
)

这里最重要的是：

1

id=last.id

因为 add_messages 会按照 message id 更新消息。

保留原 id：

1

原消息 → 替换

不保留：

1

原消息 + 新消息

所以：

改消息时，记得保留原 id。

五、为什么 `edit` 没有自己的分支？

代码其实是：

1
2
3
4
5
6
7
8


if answer == "reject":
 return {
 "messages": [
 AIMessage(content="已取消删除")
 ]
 }

return {}

没有：

1

if answer == "edit":

因为真正的“修改参数”已经在：

1

graph.update_state(...)

里完成了。

所以：

1
2
3
4
5
6
7
8
9


reject
→ 拦住

approve
→ 放行

edit
→ 图外已经修改
→ 放行

approve 是审批闸门，不是编辑器。

六、为什么还要 `audit`？

人把：

1

/tmp/a.txt

改成：

1

/tmp/old.txt

这个动作发生在图外。

模型如果不知道这个变化，就可能觉得：

“为什么我刚才突然删了 old.txt？”

所以：

1

audit_note

专门记录：

1

审批人主动把删除目标改成了 /tmp/old.txt

然后 audit 把它重新放进消息历史。

所以：

1
2
3


audit
=
给模型补上“为什么参数发生变化”的上下文

这就是我这里说的：

治叙事。

七、为什么 `summarize` 不绑定工具？

如果最后还是：

1

llm.bind_tools(...)

模型有可能：

1
2
3
4
5
6
7


工具执行
 ↓
模型
 ↓
又产生 tool_calls
 ↓
再执行

单靠提示词：

1

不要重试

属于软约束。

所以最后换成：

1

llm_summarize = ChatOpenAI(...)

不绑定工具。

于是：

1
2
3
4
5
6
7


tools
 ↓
audit
 ↓
summarize
 ↓
END

最后这个模型根本没有工具可以调用。

Prompt 是说明书，不是锁。

八、`thread_id` 和 `checkpoint_id` 终于分清了

这个是我这次口述里答错的地方。

不要再把两个 id 混在一起。

1
2
3
4
5


thread_id
=
我是谁
=
哪个存档槽

1
2
3
4
5


checkpoint_id
=
我在哪一帧
=
这个槽里的哪个 checkpoint

可以记成：

1
2


thread_id → 账户号
checkpoint_id → 交易流水号

所以：

身份是 thread_id，时间是 checkpoint_id。

九、`interrupt_before` 和 `interrupt()` 也不要混

两者最大的区别不是“谁能修改 state”。

真正应该分两个维度：

	`interrupt_before`	`interrupt()`
停在哪里	节点边界	节点内部
`resume` 传值	❌	✅
`update_state`	✅	✅
恢复	`invoke(None, config)`	`Command(resume=value)`

所以：

1
2
3
4


interrupt_before
→ 没有 resume 通道
≠
不能 update_state

这一点一定要记住。

十、`.values / .next / .config`

执行：

1

st = graph.get_state(cfg)

以后，先看三个东西：

1
2
3


st.values
st.next
st.config

我现在的记法：

1
2
3
4
5
6
7
8


.values
→ 内容

.next
→ 下一步

.config
→ 这份状态的定位信息

尤其是：

1

st.next

它是判断图有没有结束的好工具：

1
2
3
4
5


next != ()
→ 还有工作

next == ()
→ 已结束

例如：

1
2
3


interrupt_before["tools"]

next == ("tools",)

说明：

agent 已经跑完，tools 还没跑。

而：

1
2
3


interrupt() 写在 agent 内

next == ("agent",)

说明：

agent 本身还没结束。

十一、checkpoint 为什么能变成“时间旅行”？

有了：

1

checkpointer = MemorySaver()

每个线程会保存历史 checkpoint。

于是：

1

graph.get_state_history(config)

就可以拿到存档列表。

然后：

1

snap.config

可以作为这份存档的钥匙。

所以：

1
2
3
4


graph.invoke(
 None,
 snap.config,
)

就是：

从这个历史 checkpoint 继续。

这就是 Replay。

十二、怎么证明真的只重跑了 B/C？

不能只说：

“我看日志。”

应该写断言：

1
2
3


assert "→ B 执行" in txt_replay
assert "→ C 执行" in txt_replay
assert "→ A 执行" not in txt_replay

最关键的是：

1

A 没出现。

因为：

1

B 出现 + C 出现

只能证明它们跑了。

而：

1

A 没出现

才能证明：

没有从头跑。

这也是今天我最想留下来的一个工程习惯：

不仅验证“应该发生什么”，还要验证“不应该发生什么”。

十三、Replay 和 Fork

Replay：

1
2
3
4


graph.invoke(
 None,
 target.config,
)

意思：

原样读档。

Fork：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


new_cfg = graph.update_state(
 target.config,
 {
 "way": "另一种方式"
 },
)

graph.invoke(
 None,
 new_cfg,
)

意思：

改档后，再发展一条新的未来。

所以：

1
2
3
4
5


Replay
= 读档重玩

Fork
= 读档 + 改属性 + 重玩

而且原来的 checkpoint 还在。

十四、今天最终记住这 8 句话

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


1. checkpointer = HITL / checkpoint 的存档基础

2. thread_id = 哪个 thread / 哪个存档槽

3. checkpoint_id = 这个 thread 的哪一帧

4. interrupt_before = 节点边界哨卡

5. interrupt() = 节点内部对话

6. resume = 图内传值
 update_state = 图外改档

7. replay = 原样从历史 checkpoint 继续

8. fork = 修改历史 state 后产生另一条未来

再加一句验证原则：

日志里“没有 A”，和“出现 B/C”一样重要。

十五、完整源码

下面这份就是今天的核心实验代码。

为了学习方便，我把注释写得比较详细，但业务逻辑本身尽量保持简单。

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572


"""
W6-D4：LangGraph HITL
三态审批 + 改参 + 审计留痕 + 结构收口

学习目标：

1. interrupt()
2. Command(resume=...)
3. update_state()
4. tool_calls 改参
5. audit
6. 无工具 summarize
"""

import os

from dotenv import load_dotenv

load_dotenv(override=True)


from typing import Annotated, TypedDict

from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages
from langgraph.checkpoint.memory import MemorySaver
from langgraph.prebuilt import ToolNode
from langgraph.types import interrupt, Command

from langchain_core.tools import tool
from langchain_core.messages import AIMessage, HumanMessage
from langchain_openai import ChatOpenAI


# ============================================================
# 1. 工具
# ============================================================

@tool
def delete_file(path: str) -> str:
 """
 演示工具。

 不真的删除文件，只打印执行结果。
 """

 print(f">>> 工具真身执行：删除 {path}")

 return f"文件已删除：{path}"


# ============================================================
# 2. State
# ============================================================

class S(TypedDict):

 # 对话历史
 #
 # add_messages 会负责消息的追加 / 更新。
 messages: Annotated[list, add_messages]

 # 普通字段：
 # 专门记录审批人的操作。
 audit_note: str


# ============================================================
# 3. 两个 LLM
# ============================================================

_common = {
 "model": os.getenv(
 "DEEPSEEK_MODEL",
 "deepseek-v4-flash",
 ),
 "api_key": os.getenv(
 "DEEPSEEK_API_KEY",
 ),
 "base_url": os.getenv(
 "DEEPSEEK_BASE_URL",
 "https://api.deepseek.com",
 ),
 "temperature": 0,
}


# 决策模型：
# 有工具。
llm_decide = ChatOpenAI(
 **_common
).bind_tools(
 [delete_file]
)


# 收口模型：
# 没有工具。
#
# 这样最后只能总结，
# 不能再次产生 tool_calls。
llm_summarize = ChatOpenAI(
 **_common
)


# ============================================================
# 4. decide
# ============================================================

def decide(state: S) -> dict:
 """
 决策官。

 只负责：
 让模型决定要不要调用工具。

 注意：
 这里不能先 interrupt，
 因为 AIMessage 需要先 return，
 才会真正进入 state。
 """

 ai_msg = llm_decide.invoke(
 state["messages"]
 )

 print(
 "[decide] tool_calls =",
 len(ai_msg.tool_calls),
 )

 return {
 "messages": [ai_msg]
 }


# ============================================================
# 5. approve
# ============================================================

def approve(state: S) -> dict:
 """
 审批官。

 读取上一条 AIMessage，
 找到模型准备执行的 tool_call，
 然后问人。
 """

 last = state["messages"][-1]

 if not (
 isinstance(last, AIMessage)
 and last.tool_calls
 ):
 return {}

 tc = last.tool_calls[0]

 print(
 "[approve] 待审批参数：",
 tc["args"],
 )

 # interrupt 第一次运行会暂停。
 #
 # resume 后这个节点会重新执行，
 # 再次来到这里时，
 # interrupt() 会直接返回 resume 值。
 answer = interrupt(
 {
 "question": (
 f"模型想删除 "
 f"{tc['args']['path']}，"
 f"批准吗？"
 ),
 "options": [
 "approve",
 "reject",
 "edit",
 ],
 }
 )

 # reject：
 # 返回一条没有 tool_calls 的消息。
 #
 # 后面路由看到没有 tool_calls，
 # 就会 END。
 if answer == "reject":

 return {
 "messages": [
 AIMessage(
 content=(
 "已取消删除，"
 "本次未执行任何操作。"
 )
 )
 ]
 }

 # approve / edit：
 #
 # 两者都直接放行。
 #
 # edit 真正修改参数的动作，
 # 已经在图外 update_state() 完成。
 return {}


# ============================================================
# 6. audit
# ============================================================

def audit(state: S) -> dict:
 """
 把人工修改重新注入消息历史。

 解决：
 “为什么实际参数和原来不一样？”
 """

 note = state.get(
 "audit_note",
 "",
 )

 if not note:
 return {}

 print(
 "[audit]",
 note,
 )

 return {
 "messages": [
 HumanMessage(
 content=(
 f"【审批人操作记录】{note}。"
 "这是审批人主动、有意做出的决定，"
 "已获批准执行。"
 "这不是错误，无需重试，"
 "请直接总结实际结果。"
 )
 )
 ],

 # 用完清空
 "audit_note": "",
 }


# ============================================================
# 7. summarize
# ============================================================

def summarize(state: S) -> dict:
 """
 收口。

 这里故意使用没有绑定工具的 LLM。
 """

 ai_msg = llm_summarize.invoke(
 state["messages"]
 )

 print(
 "[summarize] tool_calls = 0"
 )

 return {
 "messages": [ai_msg]
 }


# ============================================================
# 8. decide 后的路由
# ============================================================

def route_after_decide(state: S):

 last = state["messages"][-1]

 if (
 isinstance(last, AIMessage)
 and last.tool_calls
 ):
 return "approve"

 return END


# ============================================================
# 9. approve 后的路由
# ============================================================

def route_after_approve(state: S):

 last = state["messages"][-1]

 if (
 isinstance(last, AIMessage)
 and last.tool_calls
 ):
 return "tools"

 return END


# ============================================================
# 10. 构图
# ============================================================

builder = StateGraph(S)

builder.add_node(
 "decide",
 decide,
)

builder.add_node(
 "approve",
 approve,
)

builder.add_node(
 "tools",
 ToolNode([delete_file]),
)

builder.add_node(
 "audit",
 audit,
)

builder.add_node(
 "summarize",
 summarize,
)


# START → decide

builder.add_edge(
 START,
 "decide",
)


# decide → approve / END

builder.add_conditional_edges(
 "decide",
 route_after_decide,
 {
 "approve": "approve",
 END: END,
 },
)


# approve → tools / END

builder.add_conditional_edges(
 "approve",
 route_after_approve,
 {
 "tools": "tools",
 END: END,
 },
)


# tools → audit → summarize → END

builder.add_edge(
 "tools",
 "audit",
)

builder.add_edge(
 "audit",
 "summarize",
)

builder.add_edge(
 "summarize",
 END,
)


# ============================================================
# 11. 编译
# ============================================================

graph = builder.compile(
 checkpointer=MemorySaver()
)


# ============================================================
# 12. C 场景：edit
# ============================================================

cfg = {
 "configurable": {
 "thread_id": "w6-d4-edit",
 }
}


# ------------------------------------------------------------
# 第一次运行
#
# 图会走到：
#
# START
# ↓
# decide
# ↓
# approve
# ↓
# interrupt
#
# 然后暂停。
# ------------------------------------------------------------

graph.invoke(
 {
 "messages": [
 (
 "user",
 "帮我删除 /tmp/a.txt",
 )
 ],
 "audit_note": "",
 },
 cfg,
)


# ============================================================
# 13. 查看暂停时的 state
# ============================================================

st = graph.get_state(cfg)

print("\n当前 next =", st.next)

print(
 "当前消息数量 =",
 len(st.values["messages"]),
)

last = st.values["messages"][-1]

print(
 "当前 tool_calls =",
 last.tool_calls,
)


# ============================================================
# 14. 修改 pending tool_call
# ============================================================

new_tool_calls = [
 {
 **tc,

 # 只修改 path，
 # 其它参数保留。
 "args": {
 **tc["args"],
 "path": "/tmp/old.txt",
 },
 }
 for tc in last.tool_calls
]


# ------------------------------------------------------------
# ★ 关键：
# 必须保留原来的 message id。
#
# 表示：
# “更新刚才那条消息”
#
# 而不是：
# “新增一条消息”
# ------------------------------------------------------------

fixed = AIMessage(
 id=last.id,
 content=last.content,
 tool_calls=new_tool_calls,
)


# ============================================================
# 15. 改档 + 写审计
# ============================================================

graph.update_state(
 cfg,
 {
 "messages": [fixed],

 "audit_note": (
 "审批人把删除目标从 "
 "/tmp/a.txt 改成了 "
 "/tmp/old.txt"
 ),
 },
)


# ============================================================
# 16. resume
# ============================================================
#
# edit 已经体现在 state 里。
#
# resume("edit") 只是告诉 approve：
# “人的答案是 edit。”
#
# 然后 approve 放行。
# ============================================================

result = graph.invoke(
 Command(
 resume="edit"
 ),
 cfg,
)


print(
 "\n最终结果：",
 result["messages"][-1].content,
)


# ============================================================
# 17. 最终验收
# ============================================================

final_state = graph.get_state(cfg)

print(
 "\n最终 next =",
 final_state.next,
)

print(
 "最后一条 tool_calls =",
 getattr(
 final_state.values["messages"][-1],
 "tool_calls",
 None,
 ),
)

# 理论上的最终状态应该：
#
# next == ()
#
# 表示图结束。

四十三、这一篇我以后真正需要回看的地方

不用重新读全文。

直接看这张：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


┌──────────────────────────────────────┐
│ D3 / D4 速查 │
├──────────────────────────────────────┤
│ thread_id = 哪个会话 / 存档槽 │
│ checkpoint_id = 哪一帧 │
│ │
│ interrupt_before = 节点前哨卡 │
│ interrupt() = 节点内部问人 │
│ │
│ resume = 图内传值 │
│ update_state = 图外改档 │
│ │
│ values = state 内容 │
│ next = 下一步 │
│ config = 定位这份快照的钥匙 │
│ │
│ Replay = 原样读档 │
│ Fork = 改档后产生新未来 │
└──────────────────────────────────────┘

以及最重要的两个判据：

1
2
3
4
5


# 图有没有结束？
state.next == ()

# Replay 是不是从头跑了？
assert "→ A 执行" not in replay_log

这就够了。

以后忘了，就回来查；不用重新学一遍。

给图装上存档系统

Tue, 08 Sep 2026 13:29:58 +0800

W6-D1/D2 · 给图装上存档系统：Checkpointer、thread_id 与 SqliteSaver

零、先看清我们要补的三个缺口

W5 结束时你手里有一张能跑的图：会路由、会调工具、会压缩记忆。但它有个致命属性——每次 invoke 都从空 state 开始，跑完 state 就丢。

W5 里你其实已经撞过这个缺口三次，只是当时没有合适的工具补它：

现象	你当时怎么绕的	真正的缺口
D1 的 `turns` 累加实验：第二次要把上次输出手动喂回去才继续涨	手动传 state	图不记得上次跑过什么
D6 的 `memory_store = {}` 能跨轮记住"美式咖啡"	靠进程内全局变量碰巧还活着	记忆住在图外面，进程一关就没
D6 的 agent 能直接"记住/删除"东西，没人拦	没做，反正单agent	没有让图中途停下来问人的位置

类比：W5 的图像一台每次开机都重置的计算器——算完结果抄走，内存清空。W6 是给它装上存档系统 + 确认按钮 + 多开窗口，让它从"玩具"变成"产品"。

W6 的三件事对着这三个缺口：记住过去（Checkpointer 持久化，D1–D2）、敢问人（HITL 审批，D3–D4）、能拆能并行（子图 + Send，D5 起）。今天开篇讲第一件：给图装上存档系统。

一、先搞清一件事：checkpoint ≠ 记忆库

这是学 Checkpointer 之前必须先钉死的区分，否则后面所有用法都会长歪。

1.1 记忆其实分三层

层	是什么	谁在管	例子
① 模型上下文窗口	这一轮模型"看得见"什么	你手动拼	W3 的 buffer 取最近 N 条塞进 prompt
② 会话状态存档	这个会话跑到哪、state 是什么	框架（checkpointer）	今天按 thread_id 存的 checkpoint
③ 长期事实库	真正"学到"的知识	你的 LTM	W3 的 Chroma 落盘

W3 的短期 buffer 属于 ①——它是你给模型喂话的"原料"；今天的 checkpointer 属于 ②——它管的是"整个会话的状态怎么跨轮恢复"；W3 的 Chroma 属于 ③——跨会话的长期知识。

它们不是替代关系。今天的 checkpointer 并没有取代你的短期记忆，它取代的是你"手动跨轮攒消息"那一整套动作。

1.2 checkpoint 和记忆库的正面对比

	checkpoint（今天）	记忆库（W3 的 Chroma）
存什么	整张图的 state：messages 全列表、counter、summary、任何字段	提炼出的重要事实（“用户喜欢美式咖啡”）
粒度	会话级——一个对话的完整现场	跨会话级——长期知识，任何会话都能查
类比	游戏存档（整个游戏现场：等级、背包、剧情）	现实笔记本（你记下来的重要事情）
生命周期	跟着会话走（thread_id）	独立持久存储

一句话区分：checkpoint 回答"我们刚才聊到哪了"，记忆库回答"这个用户我们了解多少"。

⚠️ 最常见的误解就是把 checkpoint 当长期记忆用——指望它跨会话检索用户信息。它做不到，也不该做。会话现场和长期知识是两码事。

1.3 那 W3 的 buffer 和 checkpoint 到底差在哪

你可能会问：W3 那个全局 buffer 不也能跨轮记住"小明"吗？能，但它是你在应用层"模拟"出来的。 三个字的差别——隔离 + 抽象：

维度	W3 buffer（全局变量）	checkpointer + thread_id
归属层	应用层，你的类里	图运行层，LangGraph 引擎里
存的内容	一份消息列表（你自己 `add` 进去的）	整个图的 state 快照（messages + 所有字段 + 跑到哪一步）
会话隔离	❌ 全局一份，谁用都是它	✅ 每个 thread_id 一份，互不干扰
跨 invoke 记住	靠进程活着 + 你手动 add	框架按 thread_id 自动续档
进程重启	没了	MemorySaver 也没了；换一行 SqliteSaver 就落盘
落盘成本	自己写 load/save、管文件路径	换一个 saver 实现，图代码不动

单进程单用户时，两者效果一样——W3 的 buffer 本质上是在"假装整个进程只有一个会话"。一旦要多会话、要重启、要断点恢复，手搓版就撑不住了。

类比：W3 的 buffer 是你手边一本公用笔记本——一个人记没问题，两个人同时用就串行，进程一关本子烧了。checkpointer 是游戏存档槽——每个玩家有自己的档，读自己的档就记得上次玩到哪；不选存档就接不上。MemorySaver 是"内存卡"，想长久保存就换"硬盘卡"（SqliteSaver），游戏机（图代码）不用改。

二、接入只差一行：`compile(checkpointer=...)`

先看那个最痛的场景：

1
2


graph.invoke({"messages": [("user", "我叫小明，记住我")]})
graph.invoke({"messages": [("user", "我叫什么？")]}) # ❌ 不记得

每次 invoke 都从空 state 开始 → 跑完丢弃。图是一台"无状态函数"，像 f(x) = y：输入相同，它不记得上一次。

Checkpointer 的答案：在图执行过程中，每个节点跑完后自动存一份 state 快照（checkpoint）。下一次 invoke 不是从零开始，而是从上次的 checkpoint 续跑：

1
2


无 checkpoint: invoke → 跑 → 结果 → 【state 丢掉】
有 checkpoint: invoke → 每个节点后存 checkpoint → 下次从存档续跑

接线方式只有一行：

1
2
3
4


from langgraph.checkpoint.memory import MemorySaver

checkpointer = MemorySaver() # ① 注意是实例，不是类名
graph = builder.compile(checkpointer=checkpointer) # ② 编译时传入

图拓扑一行都不用改——节点、边、reducer 全不变。checkpoint 是后台自动行为，不需要你手动"存"。

两个必须记住的细节：

你 W5 学的 Annotated[list, add_messages] reducer 依然生效。checkpoint 保存的是"reducer 合并后"的 state——messages 该追加还是追加，存档里存的是追加完的结果。
保存粒度是"每个节点执行后"。所以每个节点边界都留了一个存档点，将来能回放每一步（W6-D4 的时间旅行就靠这个）。

图拓扑在概念上多了一层看不见的"后台存档"：

1
2
3


START → agent ⇄ tools（循环）→ END
 │
 └─ 后台：每个节点跑完 → 按 thread_id 存一份 checkpoint

三、`thread_id`：存档槽位编号

同一张图可能服务很多会话。图怎么知道这次续的是哪个对话？靠 config 里的 thread_id：

1
2


config = {"configurable": {"thread_id": "demo-1"}} # 会话身份证
graph.invoke({"messages": [...]}, config) # 每次 invoke 都要带

类比：游戏机的存档槽。1 号槽存"小明会话"，2 号槽存"小红会话"。不带槽位号 = 每次开新档，永远失忆；每次带同一个号 = 接续存档。

两个最容易踩的失忆原因（表现一样，根因不同，要会分辨）：

换了一个 thread_id——等于主动开了个新档，当然是空的。这是设计行为，不是 bug。
完全忘了传 config——某些版本会直接报错要求 thread_id，某些版本当成新会话处理。判断方法：跑一次看它是抛错还是失忆，别猜。

四、四组对照实验：怎么证明它真的记住了

D1 的核心不是"接上一行代码"，而是设计证据链——光看"第二次答出小明"是不够的，那可能是模型从当前问题里瞎猜的。真正的铁证是 get_state 里的消息总数。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68


"""W6-D1: 给 W5 的 ReAct 图接上 MemorySaver —— 让图记住过去"""
import os
from typing import Annotated, TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages
from langgraph.prebuilt import ToolNode, tools_condition
from langgraph.checkpoint.memory import MemorySaver
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI

# ── 1. 原样复用 W5-D3 的 ReAct 图 ──
class AgentState(TypedDict):
 messages: Annotated[list, add_messages]

@tool
def add(a: int, b: int) -> int:
 """计算两个整数之和"""
 return a + b

@tool
def multiply(a: int, b: int) -> int:
 """计算两数之积"""
 return a * b

llm = ChatOpenAI(
 model="deepseek-chat",
 base_url="https://api.deepseek.com",
 api_key=os.getenv("DEEPSEEK_API_KEY"),
).bind_tools([add, multiply])

def agent_node(state: AgentState) -> dict:
 return {"messages": [llm.invoke(state["messages"])]}

# 工厂函数：同一份拓扑，想编译几次编译几次（下面要对照组）
def build():
 b = StateGraph(AgentState)
 b.add_node("agent", agent_node)
 b.add_node("tools", ToolNode([add, multiply]))
 b.add_edge(START, "agent")
 b.add_conditional_edges("agent", tools_condition)
 b.add_edge("tools", "agent")
 return b

# ── 2. 关键差异：同一张图，编译成两个版本 ──
graph_cp = build().compile(checkpointer=MemorySaver()) # 有存档
graph_nocp = build().compile() # 无存档（对照组）

# ── 3. 验证 1：有 checkpoint + 同一 thread_id → 跨 invoke 记忆 ──
config = {"configurable": {"thread_id": "demo-1"}}
r1 = graph_cp.invoke({"messages": [("user", "我叫小明，记住我")]}, config)
print("第一次:", r1["messages"][-1].content)

r2 = graph_cp.invoke({"messages": [("user", "我叫什么名字？")]}, config)
print("第二次:", r2["messages"][-1].content) # 应该能答出"小明"

# ── 4. 验证 2：读档确认——消息真的在累加（这是铁证，不是看回答猜）──
state = graph_cp.get_state(config)
print("消息总数:", len(state.values["messages"])) # 期望 ≥ 4 = 2 次提问 + 2 次回答

# ── 5. 验证 3：换一个 thread_id → 开新档 → 失忆 ──
config2 = {"configurable": {"thread_id": "demo-2"}} # 换槽位
r3 = graph_cp.invoke({"messages": [("user", "我叫什么名字？")]}, config2)
print("换 thread:", r3["messages"][-1].content) # 答不出小明

# ── 6. 验证 4：无 checkpoint 的图，永远从零开始 ──
graph_nocp.invoke({"messages": [("user", "我叫小明")]})
g2 = graph_nocp.invoke({"messages": [("user", "我叫什么？")]})
print("无cp版消息数:", len(g2["messages"])) # 期望 = 2（只有这一轮的提问+回答）

四组证据各自的职责：

验证	证明什么	为什么不能只看它
第二次答出"小明"	跨 invoke 记忆可能生效	模型也可能从问句里瞎猜
`get_state` 消息总数 ≥ 4	✅ 铁证：上一次的消息真的留在 state 里被续上了	—
换 thread_id 答不出	隔离生效：存档是按槽位分的	—
无 cp 版消息数 = 2	没有存档机制 → 每次全新开局	—

如果"答出小明"但消息总数只有 2，说明记忆是假的——模型在编，state 里根本没有历史。这就是为什么验证 2 才是关键：让代码自己说话，别靠回答猜。

💡 顺带说个"数字洁癖"：≥ 4 是推算出来的（2 问 + 2 答）。如果模型中途调了工具，会变成 5、6、7……所以跑完以 get_state 的实测值为准。推算用来设计实验，实测用来下结论。

4.1 亲眼看到"每个节点后存一份"

“每节点存快照"这句话是概念，用 D4 学过的 stream 能把它变成眼见为实——stream 每吐一次，就代表有一个节点刚跑完，也就意味着刚存了一份 checkpoint：

1
2


for event in graph_cp.stream({"messages": [("user", "再聊一句")]}, config):
 print("节点跑完:", list(event.keys()))

跑之前先读一次 len(get_state(config).values["messages"])，跑完再读一次——数字的增长量，就是这一轮新增的消息数。存档点数量 ≈ 这一轮经过的节点数。

这一步的价值在于把"后台自动存档"从黑盒变成可观测：你能数出它存了几份，而不是相信文档说它存了。

五、一张图，两个用户：会话隔离

D1 证明了"能续档”，D2 第一课是"分档"——同一张图，thread_id 就是柜子号，checkpoint 按它分桶存储：

1
2


graph.invoke(..., {"configurable": {"thread_id": "alice-001"}}) → 读写 alice 的桶
graph.invoke(..., {"configurable": {"thread_id": "bob-001"}}) → 读写 bob 的桶

两份会话共用同一套节点逻辑，但 state 快照各存各的——Alice 说的"我喜欢猫"不会漏进 Bob 的上下文。这就是多用户 Agent 服务的最小模型：每个用户一个 thread_id。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


"""W6-D2：thread_id 多会话隔离 —— 一张图，两个用户，互不干扰"""
# （构图部分与 D1 完全相同：State / 工具 / agent_node / builder）

graph = builder.compile(checkpointer=MemorySaver()) # 编译时只传一次 checkpointer

alice = {"configurable": {"thread_id": "alice-001"}}
bob = {"configurable": {"thread_id": "bob-001"}}

graph.invoke({"messages": [("user", "我叫爱丽丝，我喜欢猫")]}, alice)
graph.invoke({"messages": [("user", "我是鲍勃")]}, bob)

# 各自问自己的信息
r_a = graph.invoke({"messages": [("user", "我叫什么？我喜欢什么？")]}, alice)
r_b = graph.invoke({"messages": [("user", "我叫什么？我喜欢什么？")]}, bob)
print("Alice 记得:", r_a["messages"][-1].content) # 应答出：爱丽丝 / 猫
print("Bob 记得:", r_b["messages"][-1].content) # 应答出：鲍勃（不知道猫）

判定标准（三种结果三种根因）：

现象	判定	根因
Alice 答出"爱丽丝、猫"，Bob 只答出"鲍勃"、不知道猫	✅ 隔离成功	—
Bob 也知道猫	❌	两个 invoke 用了同一个 thread_id（最常见）
两个都失忆	❌	invoke 时忘了带 config

Bob 不知道猫不是 bug，是隔离成功。 这句话是这一节唯一要记住的。

六、从内存到磁盘：SqliteSaver 与重启恢复

MemorySaver 存在内存里——进程一关，存档全没。它是练习版。真正跨进程靠 SqliteSaver：存进 SQLite 文件，关掉程序再打开，对话还在。

6.1 save / load 两个脚本

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


"""W6-D2：SqliteSaver 落盘 + 重启恢复（save 与 load 分两次运行）"""
# （构图部分与前面完全相同，到 builder 为止，先不要 compile）

from langgraph.checkpoint.sqlite import SqliteSaver

def save():
 """第一次运行：写入会话"""
 with SqliteSaver.from_conn_string("checkpoints.db") as saver:
 graph = builder.compile(checkpointer=saver)
 cfg = {"configurable": {"thread_id": "persist-1"}}
 graph.invoke({"messages": [("user", "我叫小明，住在北京")]}, cfg)
 print("已写入会话")

def load():
 """关掉进程后再运行：读回存档"""
 with SqliteSaver.from_conn_string("checkpoints.db") as saver:
 graph = builder.compile(checkpointer=saver)
 cfg = {"configurable": {"thread_id": "persist-1"}}
 r = graph.invoke({"messages": [("user", "我叫什么？住哪？")]}, cfg)
 print("重启后回复:", r["messages"][-1].content) # 应答出 小明 / 北京

if __name__ == "__main__":
 save() # 第一次跑这个
 # load() # 然后注释掉 save、打开这行，重启进程再跑

重启恢复成功 = W6 第一道硬门槛过了：数据真的躺在磁盘上，不是靠进程"活着"装的。

6.2 三个版本的坑（提前打预防针）

同步 / 异步别混用。不同 LangGraph 版本里，SqliteSaver.from_conn_string() 返回的东西不一样——有的是同步上下文管理器（with + graph.invoke），有的是异步的（async with + await graph.ainvoke）。混用会抛 TypeError。判断方法：看你的版本报不报错、或让 IDE 提示你它是不是 AsyncContextManager。两种写法不要出现在同一个文件里。
两个脚本的 .db 路径要一致。相对路径是相对运行时的 cwd——在 W6/ 里跑和在项目根跑，会生成两个不同的 db 文件，“写入成功却读不到"多半是这个原因。
ImportError → pip install aiosqlite。SqliteSaver 底层依赖它。

6.3 MemorySaver vs SqliteSaver

	MemorySaver	SqliteSaver
存哪	内存	SQLite 文件
进程重启	❌ 全丢	✅ 可恢复
用途	练习 / 单进程验证	本地持久化 / 生产起步
切换成本	—	只换 saver，图代码不动

💡 “今天不落盘"是选了一个内存后端，不是设计上限。 saver 是个接口——现在插内存卡，明天插硬盘卡（SqliteSaver），将来插网络存储（PostgresSaver），游戏机（图代码）始终不用改。

七、读档三件套：`get_state` / `get_state_history` / `update_state`

落盘跑通后，把这三个 API 一起验掉——它们是你"查看和干预存档"的手，也是 W6-D3 HITL 的底层零件。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


def inspect():
 with SqliteSaver.from_conn_string("checkpoints.db") as saver:
 graph = builder.compile(checkpointer=saver)
 cfg = {"configurable": {"thread_id": "persist-1"}}

 # ① get_state：读当前存档
 state = graph.get_state(cfg)
 print("消息总数:", len(state.values["messages"])) # 应 > 2
 print("下一步节点:", state.next) # 正常跑完应为空

 # ② get_state_history：看存档时间线（新 → 旧）
 print("历史 checkpoint 时间线:")
 for i, snap in enumerate(graph.get_state_history(cfg)):
 cid = snap.config["configurable"]["checkpoint_id"]
 n = len(snap.values["messages"])
 print(f" #{i} checkpoint_id={cid[:8]} 消息数={n}")

 # ③ update_state：从图外面改档（人注入，不是节点返回）
 graph.update_state(cfg, {"messages": [("user", "顺便记住：我喜欢喝美式咖啡")]})

 # ④ 验证注入真的被 agent 感知
 r = graph.invoke({"messages": [("user", "我喜欢喝什么？")]}, cfg)
 print("注入后回复:", r["messages"][-1].content) # 应答出 美式咖啡

三个 API 各自的用场：

API	回答什么问题	类比
`get_state`	当前这局会话的现场：到哪了、攒了多少消息	读当前档
`get_state_history`	这局会话的所有存档点（时间线，新→旧）	看所有存档记录
`update_state`	从图外面直接改 state	用修改器改档

state.next 是什么：图"下一步要执行的节点”。正常跑完是空的；图被中断过（比如 HITL 停下来等人）它才非空——所以它是判断"图是不是卡在半路"的探针。

7.1 `update_state` vs 节点返回 dict：外部改档 vs 内部改档

这是这一节最值得想清楚的一组对照：

1
2


节点 return {"messages": [...]} → 内部改档：流水线工人自己填工单
graph.update_state(cfg, {...}) → 外部改档：车间主任从外面改工单

两者最终都是"更新 state”，但发起方不同：一个是节点在执行中自己更新，一个是人在图外面干预。正因为有"外部改档"这个能力，W6-D3 的 HITL 才成立——agent 跑到一半停下来（此时 state.next 非空），人用 update_state 塞进指令或修正，agent 再继续。

八、踩坑记（对着自查）

#	坑	解法
1	🔴 以为 checkpoint 就是长期记忆库	它是会话现场快照；长期知识仍然要向量库（W3 的 Chroma）
2	🔴 第二次 invoke 忘了带 config / thread_id 写错	表现都是"失忆"。带同一个 `thread_id` 才能续档
3	🔴 同步 / 异步 saver 混用	`with` 配 `invoke`，`async with` 配 `ainvoke`，二选一不混写
4	⚠️ `MemorySaver` 传成类名	要实例：`compile(checkpointer=MemorySaver())`
5	⚠️ 改完 builder 没重新 compile	图是编译产物，改了必须重编
6	⚠️ 两个脚本 `.db` 路径不一致	相对路径看 cwd；save/load 用同一个路径
7	⚠️ f-string 里嵌套同型引号	`f"...{d["k"]}..."` 只在 Python 3.12+ 合法（PEP 701）；通用写法是先取变量再拼
8	⚠️ 只靠"答对了"判断记忆生效	答对可能是模型编的。看 `get_state` 的消息总数才是铁证
9	⚠️ 以为换了 saver 要改图代码	不用。saver 是接口实现，图拓扑一行不动

九、速查卡片（复习直接看这）

接线三件套：

1
2
3


from langgraph.checkpoint.memory import MemorySaver # 或 .sqlite 的 SqliteSaver
graph = builder.compile(checkpointer=MemorySaver()) # 编译期接入
graph.invoke(payload, {"configurable": {"thread_id": "会话ID"}}) # 运行期带槽位

存档相关 API：

调用	用途
`graph.get_state(cfg)`	读当前存档；`state.values` 是 state、`state.next` 是待执行节点
`graph.get_state_history(cfg)`	存档时间线，每个节点边界一份，新→旧
`graph.update_state(cfg, {...})`	外部改档（HITL 底层零件）

一句话速记：

checkpoint 回答"聊到哪了"，记忆库回答"了解多少"
thread_id = 存档槽位，换号 = 开新档 = 失忆（这是设计，不是 bug）
每个节点跑完存一份 → 能回放每一步（时间旅行的前提）
内部改档靠节点 return，外部改档靠 update_state

十、一句话总结 + 下一篇预告

W5 的图是无状态函数——每次 invoke 从空 state 开始、跑完就丢；W6 用 Checkpointer 给它装上存档：编译期 compile(checkpointer=...) 一行接入，运行期靠 thread_id 区分会话，框架在每个节点执行后自动存 state 快照，下次带同一个 thread_id 就续档。MemorySaver 存内存（进程一关就没），SqliteSaver 落盘（重启可恢复），换 saver 不动图代码。而验证"它真的记住了"不能看回答——要看 get_state 里的消息总数：那是消息被真正续上的铁证。

下一站是 W6-D3 的 HITL（让 Agent 停下来问人）。它正好搭在今天这三个零件上：图中断时 state.next 非空 → 人介入 → 用 update_state 把指令改进去 → agent 接着跑。今天你学会了"读档和改档"，明天就是"什么时候该停下来改"。

魔鬼代言人：如果跑通重启恢复之后你冒出"这不就是把 messages 存进数据库吗，我自己用 pickle 也能存"的念头——技术上没错，你自己存确实能跨进程。但你要自己解决三件事：按会话分桶（thread_id）、每个步骤留快照（历史回放）、外部安全改档（update_state 的语义与并发）。框架把这三件事做成了接口，你只写业务。判断一个抽象值不值，不是看它能不能被手搓替代，而是看它替你挡掉了多少种你还没想到的失败方式。

自查三问（能答上 = 真懂了）：① 第二次 invoke 答出了"小明"，但 get_state 显示消息总数是 2——记忆是真的吗？为什么？② 换 thread_id 和忘带 config，表现一样吗？根因有什么不同？③ update_state 和节点 return {...} 都在改 state，区别在哪，各用在什么场景？

记忆管理画成图

Mon, 07 Sep 2026 15:34:25 +0800

W5-D6 · 记忆管理成图：把 W3 的 MemoryManager 翻译成一张状态图

零、先立骨架

D1–D5 你攒了一堆零件：图怎么建（D1）、图怎么自己选路（D2）、工具循环怎么进图（D3）、图怎么被观察（D4）、state 怎么上安检（D5）。今天把它们装成 W5 的毕业设计——把 W3 手写的 MemoryManager 类翻译成一张 LangGraph 图。

先说清楚这篇文章的定位：这是一份**“先跑通"的项目代码**。记忆库用进程内 dict 顶着（W3 你用的 Chroma 落盘暂时没搬进来），召回匹配也是玩具级的子串——这些实现细节后面都会换，不必当最终架构。今天真正值钱的，是同一套记忆逻辑，从"类的 if/else"变成"图的节点与边"之后，你要怎么想、怎么写、怎么排雷。

目标形态一句话：原来 MemoryManager 里的"什么时候写长期、什么时候压缩、什么时候就普通聊"这些 if 判断，全部外置成一个 route 节点 + 三条条件边；三个记忆组件变成三个独立节点；对话循环变成 ReAct agent 子图。

先给总图，后面每一块都对着它讲：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


 START
 │
 ▼
 route_node ← 原来 MemoryManager 里的 if/else 决策
 │
 ┌─────────┼──────────┐
 ▼ ▼ ▼
 long_node compress_node short_node ← 三条记忆路径 = 原来三个组件
 │ │ │
 │ summary 写入 │
 │ recent 窗口更新 │
 └────┬────┴────┬─────┘
 ▼ ▼
 agent_node（ReAct） ← 原来 ChatSession 的对话循环
 │
 tools_condition
 ╱ ╲
 有 tool_calls 无 → END
 ▼
 tools_node（save / recall 长期记忆）
 │
 └──→ 回 agent（循环）

类比：W3 的 MemoryManager 是手动接线板——所有线路在类内部用 if 接好，想加一条新线路得拆开面板重新焊；今天的图是模块化配电箱——每个记忆策略是一个独立开关，想加新策略就加一个开关、拉一条线，主线路（agent）完全不用动。

一、先看原版：W3 你写的 MemoryManager 长什么样

图不是凭空来的，它是你 W3 代码的"翻译”。原版长这样（memory/memory_manager.py）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


class MemoryManager:
 def __init__(self, window=8, max_tokens=2000, keep=4, llm=None):
 self.stm = ShortTermMemory(window=window, maxtokens=max_tokens) # 短期
 self.ltm = LongTermMemory() # 长期（Chroma 向量库）
 self.keep, self.max_tokens, self.llm = keep, max_tokens, llm

 def add(self, msg: dict, persist: bool = False):
 self.stm.add(msg) # 永远进短期
 if persist and msg.get("role") == "user": # 只有明确要记的才落长期
 self.ltm.add_fact(msg["content"], fid=_fid(msg["content"]))

 def get_context(self, query: str = None) -> list[dict]:
 base = self.stm.context() # 取滑动窗口
 if not query:
 return base
 facts = self.ltm.recall(query, k=3) # 有 query 才召回长期
 if not facts:
 return base
 facts_msg = {"role": "system", "content": "已知用户长期事实：" + "|".join(facts)}
 # 拼成：系统提示 + 长期事实 + 窗口消息
 return sys_msgs + [facts_msg] + others

 def maybe_compress(self, llm=None): # 超阈值自动压缩
 msgs = _auto_compress(self.stm.buffer, llm, max_tokens=self.max_tokens, keep=self.keep)
 if msgs is not self.stm.buffer: # 真的压了才写回 buffer
 self.stm.buffer = msgs
 return self.stm.buffer

三个方法背后是三条决策线，全埋在类内部：

W3 方法	内部在做什么决策	靠什么触发
`add`	这条消息要不要落长期？	调用方手动传 `persist=True`
`get_context`	这次对话要不要召回长期事实？	有没有传 `query`
`maybe_compress`	窗口超没超阈值、要不要压缩？	压缩函数内部的阈值检查

问题就在这里：决策逻辑是"散在类方法里的 if"。想加一种新记忆策略（比如"语义缓存"），你得改 MemoryManager 的内部逻辑；想看清楚"一条消息进来到底走了哪条路"，没有任何可视化——只能靠 print。

今天的图，就是把这些隐式的 if，变成显式的节点和边。

二、翻译方案：类 → 图，四组一一对应

对照表先立起来，写代码时心里一直默念这张：

W3 类实现	W5 图实现	变化
`add` / `get_context` / `maybe_compress` 方法体	`short_node` / `long_node` / `compress_node` 节点	方法调用 → 图节点
方法里的 if 分支	`route_node` + 条件边	决策逻辑 → 独立路由
`self.stm.buffer`（短期窗口）	`state["messages"]` + `state["recent"]`	实例属性 → state 字段
`self.ltm`（Chroma）	`memory_store` dict + 两个工具	库 → 工具（实现可换回 Chroma）
ChatSession 的对话循环	`agent_node` + `tools_node` 回边	手写循环 → ReAct 子图

翻译后最大的收益（也是整张图的设计思想）：

记忆选择被"外置"成路由决策。想换路由策略（规则路由 / 多 LLM 投票路由），只改 route_node 一个函数。
每条路径是独立节点。加新记忆策略 = 加节点 + 加边，其他节点一行不动。
agent 是通用的。它不关心记忆怎么来的，只看到 messages + summary + retrieved——记忆的细节被隔离在图的上半部分。这就是关注点分离。

三、State 设计：五个字段，谁是"档案"谁是"窗口"

图要跑，先定义工单长什么样。D5 你刚学过 Pydantic state + reducer，今天直接实战：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


from typing import Annotated, Any
from pydantic import BaseModel, Field
from langgraph.graph.message import add_messages

class MemoryState(BaseModel):
 messages: Annotated[list[Any], add_messages] = Field(default_factory=list) # 完整历史
 recent: list[Any] = Field(default_factory=list) # 压缩产物：当前窗口（无 reducer）
 summary: str = Field(default="", description="压缩后保留的历史摘要")
 retrieved: list[str] = Field(default_factory=list, description="长期记忆召回内容")
 memory_path: str = Field(default="", description="本次走的路径: short/long/compress")

逐个看，五个字段三种角色：

3.1 `messages`：完整档案（只能追加）

挂了 add_messages reducer——D3 学过的"聊天记录本"，只许往下加页。它存的是从图出生到现在的全部消息，是"完整档案"。

3.2 `recent`：当前窗口（可以整体覆盖）——今天最关键的字段

普通字段，没有 reducer → last write wins，后写的整体覆盖旧值。

为什么必须单开一个 recent？直接看坑：

⚠️ 压缩陷阱（D6 最坑的点，提前打预防针）：你第一反应肯定是"压缩 = 把 messages 裁成最近 4 条"，于是 compress_node 里写 return {"messages": recent}——不生效。因为 messages 带 reducer，框架把你返回的 4 条理解成"追加到旧历史后面"，历史一条没少，压缩等于没压。想"换血"（覆盖），必须用无 reducer 的字段。recent 就是为这个存在的。

一句话分工：messages 当完整档案只许追加，recent 当压缩后的当前窗口可以整体换血。agent 读窗口、state 存档案——压缩 = 给窗口换血，不销毁档案。

3.3 `summary` / `memory_path`：普通字段，一次写入

summary：压缩节点把"旧消息的浓缩"写进来，agent 组装上下文时读它。
memory_path：route 节点的输出——本次走了 short / long / compress 哪条路。它是给边当"路标"用的（见第五节构图）。

3.4 `retrieved`：预留位（本版先空着）

清单最初的设计是 long_node 直接调检索、把结果填进 retrieved，agent 读 state 就拿得到长期记忆。但本版改走了另一条更"Agent 味"的路线：存什么、取什么由 agent 自己调 recall_long_term 工具决定（见 5.4），所以 retrieved 字段这一版不会被填充——它是为"图内直连检索"那条路线留的口子。字段留着不碍事，后面想换路线直接用它。

四、长期记忆：dict 顶班 + 两个工具

W3 的长期记忆是 Chroma 向量库。今天为了先跑通，用一个进程内共享的 dict 顶班，对外只暴露两个工具：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


memory_store = {} # {关键词: 内容} —— 玩具级记忆库，正式版换回 W3 的 Chroma

@tool
def save_long_term(key: str, content: str) -> str:
 """把重要信息存入长期记忆。当用户说'记住...'或提到个人偏好时调用。"""
 memory_store[key] = content
 return f"已记住: {key} = {content}"

@tool
def recall_long_term(query: str) -> str:
 """从长期记忆检索信息。当用户询问之前提过的事实/偏好时调用。
 query 请传 1~3 个关键词（如"咖啡、预算"），不要传完整问句。"""
 kws = [w for w in query.replace(",", " ").replace("，", " ").split() if w]
 hits = []
 for k, v in memory_store.items():
 if any(kw in k or kw in v for kw in kws) or query in k or query in v:
 hits.append(f"{k}: {v}")
 return "\n".join(hits) if hits else "(长期记忆中没有相关内容)"

两个设计点要讲清楚：

① 为什么"存/取"要做成工具，而不是节点里直接写 dict？ 因为"要不要存、存什么、拿什么来查"是模型在对话里才能判断的——它看到"记住我喜欢喝美式咖啡"才知道该调 save_long_term。做成工具，就是让模型自己决定调用时机，这正是 D3 你搭的 ReAct 循环最擅长的活。

② 匹配为什么写得这么"笨"？ 玩具级 dict 没有向量，只能子串匹配。中文没有空格分词，所以让模型传短关键词（description 里写死了），再对每个关键词做子串包含。模型偶尔还是会传整句——没关系，那正是第七节要讲的一个坑，有兜底。正式版直接换回你 W3 的 Chroma 语义检索，这个笨匹配就退休了。

工具声明完，绑模型：

1
2
3
4
5
6


llm = ChatOpenAI(
 model="deepseek-chat",
 base_url="https://api.deepseek.com",
 api_key=os.getenv("DEEPSEEK_API_KEY") or os.getenv("OPENAI_API_KEY"),
)
llm_with_tools = llm.bind_tools([save_long_term, recall_long_term])

注意这里准备两个 llm：裸 llm 给 route 和 compress 做纯文本判断；llm_with_tools 只给 agent 用——agent 才需要"会调工具"的能力，路由和压缩让它瞎调工具反而添乱。

五、四个节点逐块拆

5.1 `route_node`：把 if/else 搬进一个独立节点

W3 的决策散在三个方法里，今天统一收口到一个节点。它读 state、输出一个 memory_path：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


def route_node(state: MemoryState) -> dict:
 # 规则优先：消息超阈值直接压缩（确定性，不赌模型心情；也是 W3 maybe_compress 的阈值语义）
 if len(state.messages) > 10:
 return {"memory_path": "compress"}

 # 其余交给 LLM 语义判断：要长期记忆，还是普通对话？
 prompt = f"""判断这段对话最需要哪种记忆处理，只输出一个词：
- long: 用户明确要求记住信息(说'记住...')，或询问之前提过的事实/偏好
- short: 普通对话，无需特殊处理
对话历史:
{fmt(state.messages[-4:])}"""
 decision = llm.invoke(prompt).content.strip().lower()
 if "long" in decision:
 return {"memory_path": "long"}
 return {"memory_path": "short"}

这里有个刻意的设计取舍，值得停下来讲：为什么 compress 用规则（len > 10）、long/short 用 LLM？

压缩有客观阈值——超过 10 条就该压，这是确定性的，用规则既稳又省钱（少一次 LLM 调用）。而且这恰好还原了 W3 的行为：maybe_compress 本来就是靠阈值触发压缩的。
long / short 是语义判断——“记住…“和"询问以前的事"没有硬性规则可写，只能交给 LLM。

💡 如果你的目标是"让 LLM 全权决定走哪条路”（连 compress 也让它判），把上面的规则行删掉、prompt 里加回 compress 分支即可。但测试某条路径时别依赖 LLM 路由碰运气——先用规则锁死路径验证节点逻辑，验证完再放开。先测确定性，再测智能性，这个顺序第七节还会再出现。

fmt 是给 LLM 看历史的小工具，把消息对象摊成纯文本（有的消息没 content 就退回 str）：

1
2
3
4
5


def fmt(msgs) -> str:
 return "\n".join(
 m.content if hasattr(m, "content") and m.content else str(m)
 for m in msgs
 )

5.2 三条记忆路径：short / long / compress

short_node —— 最朴素，但想清楚它为什么存在：

1
2
3


def short_node(state: MemoryState) -> dict:
 """普通对话：消息已在 messages 自然累加，recent 同步为当前窗口"""
 return {"recent": state.messages[-6:], "memory_path": "short"}

普通对话不需要任何处理，但它干了件重要的事：把 recent 窗口同步成最近 6 条。为什么？因为 agent 读的是 state.recent or state.messages（见 5.4）——如果走 short 却不更新 recent，recent 会一直是空，agent 每次都退回读全量 messages。窗口机制就形同虚设。每条路径都要让 agent 拿到的"窗口视图"是新鲜的。

long_node —— 只打标，不干活：

1
2
3


def long_node(state: MemoryState) -> dict:
 """长期记忆路径：真正的'存什么/取什么'由 agent 调工具完成，这里只标记路径"""
 return {"memory_path": "long"}

它只写 memory_path，什么都不做。这不是偷懒，是职责划分：route 决定"这次对话需要启用长期记忆处理”（走 long 这条路），但具体存哪条、查什么，是 agent 看到消息内容后才能决定的——所以落库/召回全部下放给 agent 的工具调用。记住：路由只负责"要不要走这条路"，不负责"路上干什么"。

compress_node —— 压缩的正解：

1
2
3
4
5
6
7
8
9


def compress_node(state: MemoryState) -> dict:
 """压缩：旧消息 → LLM 摘要；裁剪结果写进 recent（普通字段），不碰 messages"""
 if len(state.messages) <= 4:
 return {"recent": state.messages, "summary": state.summary, "memory_path": "compress"}
 old, recent = state.messages[:-4], state.messages[-4:]
 sp = (f"把以下对话压缩成一句摘要，保留关键事实(人名/偏好/结论):\n{fmt(old)}\n"
 f"(已有摘要:{state.summary or '无'})")
 new_summary = llm.invoke(sp).content.strip()
 return {"recent": recent, "summary": new_summary, "memory_path": "compress"}

对照第三节的坑看这段，逻辑就通了：

消息 ≤ 4 条：没得压，原样把窗口给 recent。
超过 4 条：old = 前面的旧消息，recent = 最后 4 条。
旧消息交 LLM 压成一句摘要（带上已有的 summary 一起压——这是增量压缩，不是每次都从零开始，摘要会越滚越全）。
关键：裁剪结果写进 recent（普通字段，整体覆盖），绝不返回 {"messages": ...}。这样 messages 档案完好，agent 的窗口换成了新鲜 4 条 + 一句摘要。

5.3 一个隐藏小坑：为什么要保留 `summary` 原值返回

compress_node 的"消息不够压"分支里，summary 写的是 state.summary（原值）。这不是废话——state 更新是局部更新：节点返回什么，什么才被写进 state。如果这个分支不写 summary，且之前某轮已经压出过摘要，state 里的 summary 并不会丢（没节点动它就不变）。但显式写回来是"声明式"的好习惯：让每个节点的返回 dict 完整表达"我这条路径结束时这几个字段应该是什么"，读代码的人不用去猜 state 的来龙去脉。

5.4 `agent_node`：把窗口 + 摘要 + 记忆拼给模型

三条路径最终都汇进 agent。它把 state 里准备好的东西组装成上下文，交给绑了工具的模型：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


def agent_node(state: MemoryState) -> dict:
 # 读窗口：压缩过就用 recent（裁剪后的 4 条），没压缩过退回全量 messages
 window = state.recent if state.recent else state.messages

 ctx = []
 if state.summary: # 压缩摘要 → system
 ctx.append(("system", f"历史摘要:{state.summary}"))
 if state.retrieved: # 长期记忆直连召回结果 → system（本版预留）
 ctx.append(("system", f"长期记忆:\n{'，'.join(state.retrieved)}"))
 ctx.extend(window)

 # 兜底闸：工具已经调过 3 次还没收敛 → 强制作答，别再烧 API
 tool_turns = [m for m in state.messages if getattr(m, "type", "") == "tool"]
 if len(tool_turns) >= 3:
 ctx.append(("user", "请基于已有工具结果直接给出最终答案；若没有查到，就如实说没查到，不要再调用工具。"))

 return {"messages": [llm_with_tools.invoke(ctx)]}

四行组装逻辑，每行一个知识点：

window = state.recent if state.recent else state.messages——agent 永远只读窗口，不读档案。压缩后读 recent（4 条 + 摘要），没压缩读全量。这就是第三节"reducer 不让裁 messages"的完整闭环：不裁档案，只换窗口。
summary / retrieved 以 ("system", ...) 元组形式插在窗口前面——让模型先看到"历史摘要"“长期记忆"这些背景，再看窗口里的实时对话。元组 ("role", content) 是 LangChain 的轻量消息写法，和 BaseMessage 混排没问题。
兜底闸写在 ctx 组装之后：数 state.messages 里已经有多少条 type == "tool" 的 ToolMessage，超过 3 条就把"直接作答"指令塞进去。这条是第七节"工具空转"坑的防御——工具调用必须有轮数上限，“查不到"必须成为可接受的答案。
返回值 {"messages": [ai]}——走 reducer 追加，完整历史继续涨。agent 只负责"回答 + 可能发起工具调用”，工具执行是下一个节点的事。

5.5 构图：边把一切串起来

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


builder = StateGraph(MemoryState)
builder.add_node("route", route_node)
builder.add_node("short", short_node)
builder.add_node("long", long_node)
builder.add_node("compress", compress_node)
builder.add_node("agent", agent_node)
builder.add_node("tools", ToolNode([save_long_term, recall_long_term]))

builder.add_edge(START, "route")
builder.add_conditional_edges(
 "route",
 lambda s: s.memory_path, # 路由函数：读 memory_path 当路标
 {"short": "short", "long": "long", "compress": "compress"},
)
for n in ["short", "long", "compress"]:
 builder.add_edge(n, "agent") # 三路径都汇入 agent
builder.add_conditional_edges("agent", tools_condition) # 有 tool_calls → tools，否则 END
builder.add_edge("tools", "agent") # 工具执行完回 agent

memory_graph = builder.compile()

两处"图会自己走"的精髓：

route 的条件边：路由函数 lambda s: s.memory_path 读 state 里的 memory_path 字段——short_node 之类刚写进去的值，立刻被当作下一步的路线。这就是 D2 学的"边看数据选路”，今天的路由函数甚至不用自己算，节点已经把答案写进 state 了，边只需要读。
agent ↔ tools 回边：agent 发起 tool_calls → tools_condition 判"有"→ 去 tools → ToolNode 自动执行并回填 ToolMessage → 回 agent 再看结果 → 直到模型不再要工具 → END。这就是 D3 那张 ReAct 图原样嵌了进来。整张图 = 上半截记忆决策（route → 三路径）+ 下半截对话循环（agent ↔ tools），中间用 agent 焊死。

六、完整可跑代码（含四组测试）

前面是逐块拆解，这一节把全部拼成一份能整体复制的文件。结构：state → 工具与 LLM → 节点 → 构图 → 测试。跑 python memory_graph.py 即可。

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139


"""W5-D6 项目日：MemoryManager(类) → MemoryManagerGraph(图)
目标：先跑通。记忆库用进程内 dict（玩具级），正式版换 W3 的 Chroma。"""
import os
from typing import Annotated, Any
from pydantic import BaseModel, Field
from langchain_openai import ChatOpenAI
from langchain_core.tools import tool
from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages
from langgraph.prebuilt import ToolNode, tools_condition

# ══════════ 1. State：档案(messages) 与 窗口(recent) 分开 ══════════
class MemoryState(BaseModel):
 messages: Annotated[list[Any], add_messages] = Field(default_factory=list) # 完整历史，只追加
 recent: list[Any] = Field(default_factory=list) # 当前窗口（无 reducer → 可整体覆盖）
 summary: str = Field(default="", description="压缩后保留的历史摘要")
 retrieved: list[str] = Field(default_factory=list, description="长期记忆召回内容(预留)")
 memory_path: str = Field(default="", description="本次走的路径: short/long/compress")

# ══════════ 2. 长期记忆：dict 顶班 + 两个工具 ══════════
memory_store = {} # {关键词: 内容}；正式版换回 W3 的 Chroma 向量检索

@tool
def save_long_term(key: str, content: str) -> str:
 """把重要信息存入长期记忆。当用户说'记住...'或提到个人偏好时调用。"""
 memory_store[key] = content
 return f"已记住: {key} = {content}"

@tool
def recall_long_term(query: str) -> str:
 """从长期记忆检索信息。当用户询问之前提过的事实/偏好时调用。
 query 请传 1~3 个关键词（如'咖啡、预算'），不要传完整问句。"""
 kws = [w for w in query.replace(",", " ").replace("，", " ").split() if w]
 hits = [f"{k}: {v}" for k, v in memory_store.items()
 if any(kw in k or kw in v for kw in kws) or query in k or query in v]
 return "\n".join(hits) if hits else "(长期记忆中没有相关内容)"

llm = ChatOpenAI(
 model="deepseek-chat",
 base_url="https://api.deepseek.com",
 api_key=os.getenv("DEEPSEEK_API_KEY") or os.getenv("OPENAI_API_KEY"),
)
llm_with_tools = llm.bind_tools([save_long_term, recall_long_term]) # 只有 agent 用它

# ══════════ 3. 工具函数 ══════════
def fmt(msgs) -> str:
 """消息对象摊成纯文本，给 LLM 看"""
 return "\n".join(
 m.content if hasattr(m, "content") and m.content else str(m)
 for m in msgs
 )

# ══════════ 4. route：规则管压缩，LLM 管 long/short ══════════
def route_node(state: MemoryState) -> dict:
 if len(state.messages) > 10: # 规则优先：超阈值必压缩（确定性）
 return {"memory_path": "compress"}
 prompt = f"""判断这段对话最需要哪种记忆处理，只输出一个词：
- long: 用户明确要求记住信息(说'记住...')，或询问之前提过的事实/偏好
- short: 普通对话，无需特殊处理
对话历史:
{fmt(state.messages[-4:])}"""
 decision = llm.invoke(prompt).content.strip().lower()
 if "long" in decision:
 return {"memory_path": "long"}
 return {"memory_path": "short"}

# ══════════ 5. 三条记忆路径 ══════════
def short_node(state: MemoryState) -> dict:
 """普通对话：recent 同步为当前窗口"""
 return {"recent": state.messages[-6:], "memory_path": "short"}

def long_node(state: MemoryState) -> dict:
 """长期路径：只打标；真正的存/取由 agent 调工具完成"""
 return {"memory_path": "long"}

def compress_node(state: MemoryState) -> dict:
 """压缩：旧消息 → LLM 摘要；裁剪写 recent，绝不返回 messages（reducer 会追加）"""
 if len(state.messages) <= 4:
 return {"recent": state.messages, "summary": state.summary, "memory_path": "compress"}
 old, recent = state.messages[:-4], state.messages[-4:]
 sp = (f"把以下对话压缩成一句摘要，保留关键事实(人名/偏好/结论):\n{fmt(old)}\n"
 f"(已有摘要:{state.summary or '无'})")
 new_summary = llm.invoke(sp).content.strip()
 return {"recent": recent, "summary": new_summary, "memory_path": "compress"}

# ══════════ 6. agent：窗口 + 摘要 + 工具轮数闸 ══════════
def agent_node(state: MemoryState) -> dict:
 window = state.recent if state.recent else state.messages # 只读窗口
 ctx = []
 if state.summary:
 ctx.append(("system", f"历史摘要:{state.summary}"))
 if state.retrieved:
 ctx.append(("system", f"长期记忆:\n{'，'.join(state.retrieved)}"))
 ctx.extend(window)
 tool_turns = [m for m in state.messages if getattr(m, "type", "") == "tool"]
 if len(tool_turns) >= 3: # 工具调过 3 次还不收敛 → 强制作答
 ctx.append(("user", "请基于已有工具结果直接给出最终答案；若没有查到，就如实说没查到，不要再调用工具。"))
 return {"messages": [llm_with_tools.invoke(ctx)]}

# ══════════ 7. 构图 ══════════
builder = StateGraph(MemoryState)
builder.add_node("route", route_node)
builder.add_node("short", short_node)
builder.add_node("long", long_node)
builder.add_node("compress", compress_node)
builder.add_node("agent", agent_node)
builder.add_node("tools", ToolNode([save_long_term, recall_long_term]))

builder.add_edge(START, "route")
builder.add_conditional_edges("route", lambda s: s.memory_path,
 {"short": "short", "long": "long", "compress": "compress"})
for n in ["short", "long", "compress"]:
 builder.add_edge(n, "agent")
builder.add_conditional_edges("agent", tools_condition)
builder.add_edge("tools", "agent")

memory_graph = builder.compile()
print("✅ 图编译成功")

# ══════════ 8. 四组测试 ══════════
if __name__ == "__main__":
 # 测试 A：compress —— 12 条超阈值，规则锁死压缩路径
 r1 = memory_graph.invoke({"messages": [("user", f"第{i}句闲聊内容{i}") for i in range(12)]})
 print("\n[A compress] 路径:", r1["memory_path"])
 print(" 压缩后 recent 消息数:", len(r1["recent"]), "| 摘要:", (r1.get("summary") or "")[:40])

 # 测试 B：long 记住（落库）
 r2 = memory_graph.invoke({"messages": [("user", "记住我喜欢喝美式咖啡")]})
 print("\n[B 记住] 路径:", r2["memory_path"], "| 记忆库:", memory_store)

 # 测试 C：long 召回（跨轮验证——同进程内 dict 共享）
 r3 = memory_graph.invoke({"messages": [("user", "我喜欢喝什么咖啡？")]})
 print("[C 召回] 路径:", r3["memory_path"])
 for m in r3["messages"][-2:]:
 m.pretty_print()

 # 测试 D：short 普通对话
 r4 = memory_graph.invoke({"messages": [("user", "你好，简单介绍下你自己")]})
 print("\n[D short] 路径:", r4["memory_path"], "| 回复:", r4["messages"][-1].content[:30])

每个测试验证什么，跑之前心里要有数：

测试	输入	期望路径	验证点
A	塞 12 条闲聊（超 10 条阈值）	compress	规则触发压缩：recent 裁到 4 条、summary 非空
B	“记住我喜欢喝美式咖啡”	long	agent 自主调 `save_long_term`，记忆落库
C	“我喜欢喝什么咖啡？”	long	跨轮召回：agent 调 `recall_long_term` 命中 B 存的偏好并答出
D	“你好，简单介绍下你自己”	short	普通路径：窗口透传、正常回答

其中 C 是 D6 最硬的验收——B、C 连着跑、C 能答出"美式咖啡"，才证明长期记忆真的跨轮工作了，而不只是路由打了个标。

七、三场真实故障，三个沉淀下来的习惯

代码不是一次写对的。跑这张图时，几乎每个难点都会以"报错"或"卡住"的形式咬你一口。下面三场按从最坑到次坑排列，每场都是一次"现象 → 归因 → 让代码说话 → 沉淀习惯"的完整排查。

7.1 故障一：`KeyError: 'summary'` —— 键不存在，不是值为空

现象：测试 A 跑完，访问 r1["summary"] 抛 KeyError。

第一反应（错）：是不是压缩没生成摘要？summary 是空字符串？

真相：报错信息说得很清楚——r1 这个最终 state 字典里根本没有 summary 这个键，不是值为空，是键不存在。为什么？看谁在写 summary：只有 compress_node 写它。而这次运行 route 判成了别的路径，compress_node 根本没执行，summary 从头到尾没有任何节点写过。

为什么"默认值 "" 没兜住"：state 里声明了 summary: str = ""，理论上字段应该存在。但 LangGraph 对"从未被任何节点更新过的字段"的最终输出处理，和你预期的并不总是一致（具体行为和版本有关）。结论只有一个：不要赌键一定存在。

沉淀的习惯①：访问 state 字段用 .get() 兜底，排查缺失键先打印 keys()。

1
2
3


print("r1 keys:", r1.keys()) # 让代码自己说话：到底有哪些键
print("路径:", r1["memory_path"]) # 大概率是 short → 证实 compress 没走
print("摘要:", r1.get("summary", "")[:40]) # 键不存在返回 ""，不报错

.get() 是防御式取值的标配，打印 keys() 是排查 state 缺失键的第一动作——这两个习惯从今天起刻进肌肉记忆。

7.2 故障二：压缩"裁不动" —— 想替换 messages，reducer 不让你替换

现象：compress_node 返回 {"messages": recent}，想"把历史裁成最近 4 条"，结果历史还在涨，压缩等于没压。

根因：第三节那个坑的实战版——messages 挂了 add_messages reducer，LangGraph 的规则是：带 reducer 的字段，节点返回的新值会追加到旧值后面，而不是替换。你想"换成这 4 条"，框架理解成"把这 4 条追加到旧历史后面"。

解法：加一个无 reducer 的普通字段 recent。普通字段是整体覆盖（last write wins），compress_node 把裁剪结果写进 recent，agent 读 state.recent or state.messages。这就是 D5 学的"覆盖 vs 追加"在真实项目里的第一次实战：messages 当"完整档案"只能追加，recent 当"当前窗口"可以整体换血。

沉淀的习惯②：动"带 reducer 的字段"之前，先问自己——我要的是追加还是替换？ 要追加（消息历史、日志）直接写；要替换（窗口、快照、结果）单开一个无 reducer 的字段，别跟 reducer 对着干。

7.3 故障三：图"卡住" —— 长期记忆查不到，模型反复空转

现象：测试 C（召回"我喜欢喝什么咖啡"）跑很久不结束，像死锁。invoke 是同步的，没跑完就不会打印下一行。

真相：不是死锁，是模型在空转。看 B 测试的落库结果——key 是模型自己编的（比如"咖啡偏好"），value 是"用户喜欢喝美式咖啡"。到 C 测试，模型要召回，它调 recall_long_term 时 query 是现场编的，很可能是完整问句。而旧的匹配逻辑是整句 query in value：

1

"我喜欢喝什么咖啡" in "用户喜欢喝美式咖啡" → False

查不到 → 模型不甘心 → 换个 query 再查 → 还是查不到 → 再换……每转一圈都是一次真 API 请求，几秒一圈，多转几圈就是几十秒。这就是你看到的"卡住"。“查不到"对模型来说也是一种结果，但它不认——它会反复试。

三个层次的修法（本版代码里全用了）：

引导模型传关键词：recall_long_term 的 docstring 写明"query 请传 1~3 个关键词”，模型照着描述调工具，传"咖啡"就命中了。
匹配放宽：关键词拆分 + 双向子串包含，query 里带点杂质也能命中。
加轮数闸：agent_node 里数 ToolMessage 条数，调过 3 次还收敛不了就强制作答，明说"没查到就说没查到"。工具调用必须有上限，“查不到"必须成为可接受的最终答案——这是生产级 Agent 的标准动作，今天这版只是把标准提前用上了。

沉淀的习惯③：凡是"工具可能查不到结果"的场景，把"查不到"当成一等公民来设计——给它一个明确的返回文案、给模型一条"查不到就直说"的退路、给整个循环一道轮数闸。

八、踩坑记（汇总，对着自查）

#	坑	一句话解法
1	🔴 压缩想 `return {"messages": recent}` 裁历史	带 reducer 的字段只会追加不会替换——裁剪写无 reducer 的 `recent`，agent 读窗口
2	🔴 `KeyError` 访问 state 字段	节点没执行 = 键不存在 ≠ 值为空。用 `.get()` 兜底，先 `print(r.keys())` 定位
3	🔴 工具查不到 → 模型反复重查"卡住”	查不到也是结果。docstring 引导关键词 + 拆词匹配 + 工具轮数闸（≥3 次强制作答）
4	⚠️ 测试 compress 依赖 LLM 路由碰运气	别赌模型心情——先用规则锁路径验证节点逻辑，再放开给 LLM（先确定性，后智能性）
5	⚠️ 收口消息用裸 dict 混进消息列表	收口指令要用与上下文一致的类型：`("user", "...")` 元组或 `HumanMessage`，别用裸 dict
6	⚠️ 想一把梭写出完美版	分步走：先 route 三路通 → 再加 long 记忆 → 再加 compress → 最后接 agent 工具
7	⚠️ 全部记忆逻辑塞 agent 一个节点	路由负责"走哪条路"，节点负责"路上干什么"，agent 只负责"回答+调工具"——职责别揉在一起
8	⚠️ 忘了 route 的兜底 if/else	LLM 输出可能飘成别的词——`if "long" in decision` + 最后 fallback 到 short

九、速查卡片（复习直接看这）

五字段语义：

字段	reducer?	角色	谁写	谁读
`messages`	✅ 追加	完整档案	agent / ToolNode	route 数条数、compress 裁切
`recent`	❌ 覆盖	当前窗口	short / compress	agent
`summary`	❌ 覆盖	历史摘要	compress	agent
`retrieved`	❌ 覆盖	长期记忆直连结果（预留）	本版无人写	agent
`memory_path`	❌ 覆盖	路径路标	route / 三路径	条件边

边清单：

1
2
3
4
5


START → route
route ──(memory_path)──→ short | long | compress 条件边，读 state 字段当路标
short / long / compress → agent 三路径汇合
agent ──(tools_condition)──→ tools | END 有 tool_calls 就调，否则结束
tools → agent 回边（ReAct 循环）

一行一句口诀：

压缩 = 给窗口换血（recent），不销毁档案（messages）
路由 = 只决定走哪条路；路上的活交给节点和 agent 工具
测试带 LLM 的图：先锁死路径验证逻辑，再放开让模型决策
工具调用：有上限，“查不到"是合法答案

十、一句话总结 + 下一篇预告

W3 的 MemoryManager 用 if/else 在类内部调度记忆，今天把它翻译成了一张图：决策外置成 route 节点 + 条件边，三条记忆路径是三个独立节点，对话循环是嵌在底部的 ReAct 子图——agent 完全不感知记忆细节，只看到 messages + summary + retrieved，加新记忆策略只需加一个节点、拉一条边。而今天真正的收获，是三个坑沉淀出的三种习惯：.get() 兜底与 keys() 排查、别跟 reducer 对着干（要替换就单开普通字段）、给工具调用装上轮数闸。

图形态的记忆管理还有一个 W3 类实现给不了的福利，清单里那句提示其实是全文的钩子：给这张图挂一个 checkpointer，跨会话持久化就一行搞定——graph.compile(checkpointer=...)。W3 你得自己把 buffer 落盘，W6 学了 Checkpointer 之后，图的中间状态（包括压缩到一半的 summary）都能自动保存、断点续跑。这就是"记忆管理成图"这条路的下一站。

魔鬼代言人：如果跑通之后你冒出"这不就是把我 W3 的类换个写法吗，图也没多神奇"的念头——你的感觉一半是对的。今天的图，三条路径都是线性的、汇进 agent 就结束了，确实没比类强到哪去。图的发力点在两个你还没碰到的地方：一是可观测性（D4 的 stream 能让你亲眼看到每条消息走了哪条路，类做不到）；二是 checkpointer 之后的状态持久化与中断恢复（W6 的主题，类想做到得自己写全套）。今天先把"翻译"做对，这两个优势等 W6 回来验收。

自查三问（能答上 = 真懂了）：① 为什么压缩不能直接返回 {"messages": recent}？② recent 和 messages 各是什么角色，agent 读哪个？③ 长期记忆"查不到"时，图靠哪三层机制不空转？

Langgraph on 男娘教主

从 Session、Context Compaction、Tracer 理解 Agent Harness 工程化

W7-D5：从 Session、Context Compaction、Tracer 理解 Agent Harness 工程化

一、先不要看代码：我先建立整个系统的骨架

这三个模块并不是 Agent 的“业务逻辑”

二、第一个模块：Session Store

2.1 Session 到底是什么？

三、SessionStore 的第一个工程问题：存在哪里？

内存模式

文件模式

四、JSONL 是什么？

五、为什么这里选择 append-only？

六、SessionStore 怎么恢复数据？

七、为什么读取坏行不直接报错？

八、append 里还有一个容易被忽略的东西：fsync

九、为什么要保存 ts / thread_id / seq / messages / meta？

十、Session Store 的公开 API 为什么这么设计？

十一、delete 为什么这么麻烦？

十二、SessionStore 的整体流程

十三、第二个模块：Context Compaction

十四、Compaction 到底在干什么？

十五、这里有一个特别重要的工程决策

十六、needs_compaction() 为什么这么简单？

十七、为什么 maybe_compact() 不直接返回原消息？

十八、system 消息为什么单独拿出来？

十九、整个压缩核心其实就是这几行

二十、这里出现了一个真正的坑：tool 消息不能随便切

二十一、_summarize() 为什么接受一个 summarize 参数？

二十二、为什么默认摘要不是 LLM？

二十三、这里有一个我在最新版代码里发现的问题

如果没有传 summarize：

如果传了 summarize：

二十四、第三个模块：Tracer

二十五、Tracer 和 Audit 有什么区别？

二十六、Tracer 最核心的概念：Span

二十七、这里第一次遇到装饰器

二十八、为什么 Tracer 特别适合用装饰器？

二十九、把当前 Tracer 的装饰器拆开

第一层

第二层

第三层

三十、*a, **kw 是什么？

三十一、functools.wraps 为什么要写？

三十二、Tracer 为什么先取 parent？

三十三、这就是 contextvars

三十四、为什么不用一个普通的全局变量？

三十五、Tracer 最关键的一段：try / except / finally

三十六、为什么 return out 不能漏？

三十七、为什么异常要 raise？

三十八、为什么日志放到 finally？

三十九、为什么 _current.reset(token) 也必须做？

四十、Tracer 怎么得到父子树？

四十一、为什么 total_ms() 只统计顶层 span？

四十二、把三个模块连起来

四十三、真正的工程化思维：不是“我会不会写这个类”

第一步：先找失败场景

四十四、第二步：给每个模块划边界

Session

Compactor

Tracer

四十五、第三步：定义“不变量”

Session

Compaction

Tracer

Tracer

Compaction

四十六、第四步：再考虑异常

Session

Delete

Tracer

Tracer

四十七、第五步：再考虑“以后会不会变”

Session

Compactor

Tracer

四十八、这三个文件里我最值得记住的 8 个工程设计

1. 原始数据和派生数据分开

2. append-only 优先

3. 局部失败不要扩大

4. 基础设施不能改变业务语义

九、为什么要保存 `ts / thread_id / seq / messages / meta`？

十六、`needs_compaction()` 为什么这么简单？

十七、为什么 `maybe_compact()` 不直接返回原消息？

二十一、`_summarize()` 为什么接受一个 `summarize` 参数？

三十、`*a, **kw` 是什么？

三十一、`functools.wraps` 为什么要写？

三十三、这就是 `contextvars`

三十六、为什么 `return out` 不能漏？

三十七、为什么异常要 `raise`？

三十八、为什么日志放到 `finally`？

三十九、为什么 `_current.reset(token)` 也必须做？

四十一、为什么 `total_ms()` 只统计顶层 span？

`session.py`

`compact.py`

`trace.py`

二、为什么今天不直接让 `critic` 返回一句话

三、先看 `Critique`

`score`

`issues`

`fatal_issues`

`passed`

四、为什么 `score` 还要手动校验

五、先看 `generator`

为什么初始化 `best_draft`

六、再看 `JUDGE_SYS`

八、为什么这里重新调用 `with_structured_output`

九、为什么这里用 `json_mode`

十二、为什么 `passed` 不是程序最终事实来源

十四、critic 如何更新 `best_draft`

十六、critic 为什么要记录 `trajectory`

十七、为什么 `trajectory` 要用 reducer

十九、再看 `reviser`

二十一、为什么 `revise_count` 要自己加

二十二、真正控制循环的是 `route_after_critic`

二十四、为什么 `MAX_REVISE` 必须存在

二十五、为什么不能用 `<=` 检测停滞

二十七、所以 `forced` 模式是干什么的

三十、`test_router.py` 为什么可以做到 0 成本

三十四、最后一条边：`reviser → critic`

三十八、为什么这里同时拿 `updates` 和 `values`

四十三、但当前 `fatal_issues` 这条数据流要特别注意