HITL on Renxin's Blog

第十二话｜Run 停了之后怎样接着跑：checkpoint、审批绑定与幂等恢复

Mon, 14 Sep 2026 00:00:00 +0000

C11 结尾留下一个问题：三种模式都能在当前进程里让 Run 停下来，进入 WAITING_FOR_USER（等待用户确认）。Trace 里看得到状态、看得到等待原因。但一退出进程，这些东西全跟着内存一起没了。第二天用户回来说「确认」，你手上只剩一句话，和一个空终端——对应哪份纲领、哪个动作、恢复到哪一步，全不知道。

这篇文章用一段能真正跑起来的跨进程实验回答它。先把结论的一句话版本放在这里，读完正文再回来看会更容易懂：

恢复一个 Run 时，真正要防的是三件事：找错对象、重复执行、以及失败时一点痕迹都不留。 对应的三招分别是：把「批准了什么」冻成快照、给动作一个幂等键、把每次拒绝都写进 Trace。整篇文章就是把这个一句话结论，拆成能跑的代码逐条验证。

一、当前 Run 的返回，不保证明天能回到同一份状态

先回看 C11 的场景。一个最小 Runtime 收到 LLM 输出的 write_brief proposal（提案），它不确定能不能执行，于是挂起当前 Run 并返回 WAITING_FOR_USER（等待用户）：

brief_id="brief-1"
status="WAITING_FOR_USER"
waiting_reason="unsafe_action:write_brief"

单进程里，只要程序不退出，brief_id 还在内存里，下次调 handle("confirm","brief-1") 就能接着走。但实际使用场景不是这样的——用户在 IDE 里点一次运行，Agent 停下来等人决策，然后用户可能关掉终端、下班、第二天再回来看。此时：

原进程已退出。
内存里的 brief_id、waiting_reason、已经走到哪一步——全都消失。
用户的「确认」成了一句话孤儿。

C11 的 return 只保证当前调用的控制权交回给你，不保证换一个进程还能找回同一个 Run。

LangGraph 用 checkpointer + interrupt() 解决这个问题：挂起时把完整状态写进持久化后端，恢复时相同 thread_id 读出状态、从中断节点开头重跑。这是能力层的参考——它证明了「跨进程恢复」是可行的。但 LangGraph 的 checkpointer 是框架替你管的黑盒，本文要拆开看：你要自己管多少东西，为什么只存一个 run_id 不够，以及怎样把审批绑到具体版本上。

二、正常主路径：一个 Run 的生命线靠两样东西跨进程传递

先从正常路径走一遍——不做故障注入，走整条 start → approve → resume 时间线。关键机制只有两个：

SQLite 持久化 checkpoints。 同一个 run_id 在不同进程里打开同一份 .db 文件，读到的是同一个持久 Run 的状态和 Trace（审计日志）。
新 resume 调用推进同一个 Run，不创建一个新的。 start run-1 创建了一个持久 Run。进程退出后再开一个新进程，再执行 resume run-1——这是一次新的恢复调用，但它读到的、推进的，是 SQLite 中同一个 run_id=run-1 的记录，不是重新 start 一个新 Run。

用一张时序图把这条主线跑通：

%%{init: {'theme':'neutral'}}%%
sequenceDiagram
 autonumber
 participant C as Client
 participant R as Runtime
 participant DB as SQLite
 participant GW as Action Gateway

 Note over C,DB: 进程 A
 C->>R: start run-1
 R->>DB: INSERT checkpoint
(run-1, WAITING_FOR_USER)
 R-->>C: run_id=run-1, proposal_hash

 C->>R: approve run-1 --proposal-hash 
 R->>DB: UPDATE status=APPROVED
save approval_request_id + approval_hash
 R-->>C: approved

 Note over C,GW: 进程退出

 Note over C,GW: 进程 B（新进程）
 C->>R: resume run-1
 R->>DB: SELECT run_id=run-1
校验 request_id + proposal_hash
 R->>GW: execute(write_draft, args)
 GW-->>R: 写入成功（幂等键保护）
 R->>DB: UPDATE status=COMPLETED
 R-->>C: executed

虚线标出进程边界，但 run_id 不变——跨进程恢复的是同一个持久 Run 的状态，不是「重新创建一个」。图中 Action Gateway 是动作准入与副作用执行的统一入口，沿用 C11 的同一个概念：Runtime 校验完审批绑定后，把动作交给它执行；demo 里它物理上就是 Store 的 resume 方法内部那几行写入逻辑，不是独立进程，生产系统才会把它拆成独立组件。

动手跑一下：

# GYA 仓库 clone 下来后，进到 c12-durable-resume/python
# 进程 A
cd python
python3 main.py --db /tmp/c12.db --output /tmp/c12-draft.txt start run-1
python3 main.py --db /tmp/c12.db --output /tmp/c12-draft.txt show-trace run-1
# 从 JSON 输出复制 proposal_hash
python3 main.py --db /tmp/c12.db --output /tmp/c12-draft.txt approve run-1 --proposal-hash '<hash>'

# --- 退出终端、下班、第二天回来 ---

# 进程 B
python3 main.py --db /tmp/c12.db --output /tmp/c12-draft.txt resume run-1
python3 main.py --db /tmp/c12.db --output /tmp/c12-draft.txt show-trace run-1

Java 侧同语义（GYA-Java 仓库根目录下执行）：

./gradlew :c12-durable-resume:run --no-daemon \
 --args='/tmp/c12-java.db /tmp/c12-java-draft.txt start run-1'
# ... approve ...
./gradlew :c12-durable-resume:run --no-daemon \
 --args='/tmp/c12-java.db /tmp/c12-java-draft.txt resume run-1'

正常路径下，show-trace 的 Trace 链为：

checkpoint_saved（保存检查点） → proposal_recorded（记录提案）
→ proposal_verified（提案验证通过） → approval_recorded（记录审批）
→ proposal_verified（恢复时再次验证） → resume_started（开始恢复）
→ action_executed（动作已执行）

两端的 proposal_hash 同为 2bba1bb36ae552812b4b9e0d730249a3447adfc3ed100e0f4d92e3a8c28e7573（对「action + args + output」三者一起哈希得到的值，output 取 /tmp/c12-draft.txt）。这条 Trace 链里反复出现的 proposal_verified，就是恢复时那道「拿现在对当时」的检查在打点。

三、关键机制：批准的那一刻，把「批准了什么」冻成两份快照

第二节走完正常路径时，runs 表里其实只发生了一件事，理解它就理解了整个恢复协议：

用户点「批准」的那一刻，程序把「批准了什么」冻结下来。 冻结两份：一份是「批准的是哪一次请求」，一份是「批准的是哪个动作」。这里说的「动作」不是只有 action 名字——它包含三样：做什么（action）、带什么参数（args）、写到哪（output 路径）。三者一起被哈希，缺一个「批准」就不完整。之后无论隔了多久、换了几个进程，恢复时都拿「现在是什么」去对「当时批准的是什么」，对不上就拒绝。

先把这两个「对不上就拒」的检查看成一个动作，感受一下它的逻辑，再去看字段名会清楚很多：

恢复时问自己两句话：
1. 现在这个 request，还是不是我批准的那个？
2. 现在这个动作（做什么 + 带什么参数 + 写到哪），还是不是我批准的那个版本？
 任何一句答「不是」→ 拒绝，不执行。

落到 SQLite 里，就是下面这组「当前值 vs 批准值」的对照。左边是每次读取时重新算出来的「现在」，右边是批准那一刻冻结的「当时」：

检查	现在的值（恢复时重算）	批准时冻结的值	对不上就报错
请求对不对	`request_id`	`approval_request_id`	`approval_request_mismatch`
动作版本对不对	重算 action/args/output 的 SHA-256	`approval_hash`	`proposal_hash_mismatch`
写到哪对不对	本次传入的 `--output`	表中冻结的 `output`	`output_mismatch`

注意 proposal_hash 不在这张表里单独出现——它是 start 时算好、随提案一起存进去的原始哈希，属于「这个 Run 本来要做什么」的一部分，而「批准时冻结」的那份快照叫 approval_hash。两个 hash 名字像，但角色不同：proposal_hash 是「提案长这样」，approval_hash 是「你批准的就是这样」。第二节 CLI 里让你手动传的那个 --proposal-hash，就是拿「现在」去核对「提案」用的；而防「批准后被篡改」靠的是 approval_hash，第四节实验二会单独验证它。

特别说明为什么 output 要进哈希：如果它不进，「批准写 A 文件」这件事就没被锁住，恢复时换成「写 B 文件」照样能通过审批校验——output 这个副作用目标就成了一处没人管的缝。把它和 action、args 一起哈希，三样里动任何一个，重算的 hash 都会变，对不上冻结的 approval_hash 就拒。

除此之外还有两个字段，解决的不是「对不对」，而是「找得到、别重做」：

run_id + status：新进程靠它定位到哪一行、停在哪一步。这是「找得到」的最低要求。
executed：动作有没有已经做过。做完后重复 resume 直接返回 already_completed，不重写文件。

状态本身只有四个合法值：

状态	中文含义	合法来源	合法出口
`WAITING_FOR_USER`	等待用户	`start`	`approve` / `reject`
`APPROVED`	已批准	`approve`	`resume`
`REJECTED`	已拒绝	`reject`	终止
`COMPLETED`	已完成	`resume` 完成动作后	重复恢复 → `already_completed`

这四张状态加两组快照，就是整个 checkpoint 的全部内容。两组快照守不守得住，用篡改实验直接验；executed 兜底守不守得住，用重放实验验。

四、旧审批为什么不能放行新的 request 或新参数

上一节把「批准时冻两份快照」立起来了。现在直接篡改数据库，看这层保护到底拦不拦得住。三个实验各回答「防找错对象」里的一个问题。

实验一：批准之后，把 request 换成另一个。 正常 start → approve，然后直接改 SQLite，把 request_id 从 approval:run-1 改成 approval:run-2——模拟「用户批准的是 A，恢复时却拿着 B 来要执行」。中间那行 UPDATE 就是这次篡改本身：

python3 main.py --db /tmp/c12-exp1.db --output /tmp/c12-exp1.txt start run-1
python3 main.py --db /tmp/c12-exp1.db --output /tmp/c12-exp1.txt approve run-1 \
 --proposal-hash 'af45d70539c0998f4e3071d23e5501ccd207fb1dd5fa1d3d758307d84b74a8b9'
sqlite3 /tmp/c12-exp1.db \
 "UPDATE runs SET request_id='approval:run-2' WHERE run_id='run-1';"
python3 main.py --db /tmp/c12-exp1.db --output /tmp/c12-exp1.txt resume run-1
# → approval_request_mismatch

resume 发现现在的 request_id 不等于批准时冻结的 approval_request_id，拒绝。动作没执行，文件没创建。

实验二：把动作内容偷偷换掉，还顺手把 hash 也改成新的。 这是更狡猾的篡改——不只是改 args，还重新算一个和篡改内容配套的 proposal_hash，让「提案」这一层看起来自洽。但批准时冻结的 approval_hash 还是篡改前的旧值，改不了：

# 先正常 start + approve
python3 main.py --db /tmp/c12-exp2.db --output /tmp/c12-exp2.txt start run-1
python3 main.py --db /tmp/c12-exp2.db --output /tmp/c12-exp2.txt approve run-1 \
 --proposal-hash 'bd3de4cee4ccf82fb98239c875d50dac6455907c76e67cd267949412d08cfe0c'

# 篡改者算好篡改内容的新 hash（output 是 start 时冻结的 /tmp/c12-exp2.txt）
python3 -c "
import hashlib,json
malicious=json.dumps({'action':'write_draft','args':{'content':'unauthorized change'},'output':'/tmp/c12-exp2.txt'},sort_keys=True,separators=(',',':'))
print(hashlib.sha256(malicious.encode()).hexdigest())
"
# → f92f11517a438bc7384f1486dd4f98e8613dccb0cf760946cb3da118051108a0

# 把 args 和 proposal_hash 一起换成篡改版
sqlite3 /tmp/c12-exp2.db \
 "UPDATE runs SET args='{\"content\":\"unauthorized change\"}',
 proposal_hash='f92f11517a438bc7384f1486dd4f98e8613dccb0cf760946cb3da118051108a0'
 WHERE run_id='run-1';"
python3 main.py --db /tmp/c12-exp2.db --output /tmp/c12-exp2.txt resume run-1
# → proposal_hash_mismatch

恢复时重算当前动作的 hash，得到 f92f1151...，它确实和篡改后的 proposal_hash 一致——但和批准时冻结的 approval_hash（bd3de4ce...）不一致，于是拒绝。这个实验单独证明的是：approval_hash 是一道独立的锁。篡改者可以把 proposal_hash 改得再自洽，也过不了「和你批准的那个版本一致」这一关。

实验三：换一个输出路径。 既然 output 已经进了 proposal，那「写到哪里」也是被批准的一部分。恢复时故意传一个不同的 --output，等于篡改副作用目标，同样被拦：

python3 main.py --db /tmp/c12-exp1.db --output /tmp/c12-other.txt resume run-1
# → output_mismatch

这一条和实验一、实验二本质相同——output 和 request_id、action/args 一样，都是「批准了什么」的一部分，动了任何一个都过不了恢复时的核对。

两个实验（加第三个）合起来，正好对应第三节那张「当前值 vs 批准值」表。下面这张表把三种设计放在一起，看漏掉哪一份快照会放行哪种篡改：

设计	批准后替换 request_id	批准后替换 action/args 或 output	结论
只绑 `run_id`	误放行	误放行	不可接受
只存 `proposal_hash`	误放行（request 变了但 action 没变）	拒绝	只覆盖一半
`approval_request_id` + `approval_hash` 双绑 + 恢复时重算	拒绝	拒绝	覆盖全部

边界要说清：这套保护假设 SQLite 是可信存储。能同时改写 proposal 和 approval 两行记录的人，等于已经攻破了数据库，本文不防。本文防的是更常见的场景：批准之后、恢复之前，request 或 action/args/output 被人不经过审批地偷偷换掉——双绑 + 恢复时重算，能在这条边界内守住。

五、完成后的重复调用与故障窗口是两种重放

第四节解决了「找错对象」。现在解决三件事里的第二件——重复执行：同一个 resume 被调两次，怎么保证动作只做一次。

这里其实有两个不同的「再调一次」，别混在一起：一次是动作已经完整做完之后的重放，一次是动作做到一半进程就挂了的重放。前者有 executed 标记兜底，后者才是真正麻烦的地方。

场景一：正常完成后重复 resume。 文件已创建，checkpoint 已更新为 COMPLETED，用户再调一次 resume run-1：

python3 main.py --db /tmp/c12.db --output /tmp/c12-draft.txt resume run-1
# → already_completed

程序看到 executed=1，直接返回，不再写文件。Trace 记一条 action_replayed，文件修改时间不变。

场景二：故障窗口恢复——文件已创建，checkpoint 还没更新成 COMPLETED。 这才是协议最痛的一刻：动作本身有副作用（写文件），而「记下动作已完成」这个操作本身是另一步，两步之间有一道缝。缝里挂了，数据库以为没做，文件其实已经写了。先把这道缝画出来：

%%{init: {'theme':'neutral'}}%%
stateDiagram-v2
 [*] --> WAITING: start
 WAITING --> APPROVED: approve ✓
 WAITING --> REJECTED: reject ✗
 APPROVED --> COMPLETED: resume → 写文件 + 写 checkpoint

 note right of APPROVED
 故障窗口在此：
 文件已创建、checkpoint 未更新
 重试 → recovered / output_conflict
 end note

这张图只有三条实线状态转换（图中用短名 WAITING/APPROVED/REJECTED/COMPLETED 分别对应 WAITING_FOR_USER（等待用户）/APPROVED（已批准）/REJECTED（已拒绝）/COMPLETED（已完成））——其余场景（未批准恢复、proposal 被替换、request 被替换、重复审批、完成后重复恢复、内容冲突）都不发生状态转换，直接抛异常并在 Trace 中留 proposal_rejected、resume_rejected、transition_rejected 或 action_conflict 事件。

关系说清楚后，回到那行最要命的位置：

action_executed (文件已写入)
 ↓ 此刻崩溃（进程挂了、断电、kill -9）
STATUS != COMPLETED (checkpoint 还没来得及更新)

新进程启动后，resume 看到 status=APPROVED、executed=0，于是按正常流程准备写文件——但 FileExistsError（Python）或 FileAlreadyExistsException（Java）告诉它：文件已经在了。

此时不是直接覆写，而是比较内容：

except FileExistsError:
 if self.output.read_text(encoding="utf-8") != content:
 raise ValueError("output_conflict")
 recovered = True

如果内容相同 → 返回 recovered，Trace 留 action_recovered，更新 executed=1、status=COMPLETED，文件修改时间不变。

如果内容不同 → 返回 output_conflict，Trace 留 action_conflict，附带同维度的两份内容摘要——expected_content_hash（本应写入的内容的 SHA-256）和 existing_content_hash（已存在文件内容的 SHA-256），原文件不被覆盖。这是在说：同一个幂等键（文件路径）被另一个来源写了不同的内容——这不是故障恢复，是冲突。

测试里用 fail_after_action=True 精确注入这个窗口：文件创建后立即抛 RuntimeError("simulated_crash_after_action")，不执行后续的 checkpoint 更新。新实例恢复时不容错地命中 recovered 路径。

六、动手跑一遍：从 CLI 到失败路径全遍历

本节是完整的运行指南。核心只有一句话：这里的 write_draft proposal 是固定的测试夹具，代替上任上游 LLM 的输出，所以不需要 API Key。 它只输出 "approved technical brief" 这一句话到指定文件；不碰 drafts/、published/ 或 my-blog 目录。

Python 3.11+（标准库 sqlite3）

# 在 GYA 仓库 clone 下来的根目录下
cd c12-durable-resume/python

# 1. 运行全部测试
PYTHONPYCACHEPREFIX=/private/tmp/c12-pycache python3 -B -m unittest -v
# 10/10 通过

# 2. 正常主路径
python3 main.py --db /tmp/c12.db --output /tmp/c12-draft.txt start run-1
# → {"run_id":"run-1","status":"WAITING_FOR_USER",...}

python3 main.py --db /tmp/c12.db --output /tmp/c12-draft.txt show-trace run-1
# 复制 proposal_hash 字段值

python3 main.py --db /tmp/c12.db --output /tmp/c12-draft.txt approve run-1 \
 --proposal-hash '2bba1bb36ae552812b4b9e0d730249a3447adfc3ed100e0f4d92e3a8c28e7573'

# 模拟换新进程：直接调 resume
python3 main.py --db /tmp/c12.db --output /tmp/c12-draft.txt resume run-1
# → "result":"executed"

cat /tmp/c12-draft.txt
# → approved technical brief

python3 main.py --db /tmp/c12.db --output /tmp/c12-draft.txt resume run-1
# → "result":"already_completed"

失败路径

# 未批准恢复
python3 main.py --db /tmp/c12.db --output /tmp/c12-draft.txt start run-2
python3 main.py --db /tmp/c12.db --output /tmp/c12-draft.txt resume run-2
# → approval_required

# 批准时 hash 不一致
python3 main.py --db /tmp/c12.db --output /tmp/c12-draft.txt approve run-2 \
 --proposal-hash '0000000000000000000000000000000000000000000000000000000000000000'
# → proposal_hash_mismatch

# 拒绝后再次批准
python3 main.py --db /tmp/c12.db --output /tmp/c12-draft.txt reject run-2 \
 --proposal-hash '2bba1bb36ae552812b4b9e0d730249a3447adfc3ed100e0f4d92e3a8c28e7573'
python3 main.py --db /tmp/c12.db --output /tmp/c12-draft.txt approve run-2 \
 --proposal-hash '2bba1bb36ae552812b4b9e0d730249a3447adfc3ed100e0f4d92e3a8c28e7573'
# → approval_not_pending
python3 main.py --db /tmp/c12.db --output /tmp/c12-draft.txt resume run-2
# → approval_rejected

# 内容冲突
echo "different content" > /tmp/c12-draft.txt
python3 main.py --db /tmp/c12.db --output /tmp/c12-draft.txt start run-3
python3 main.py --db /tmp/c12.db --output /tmp/c12-draft.txt approve run-3 \
 --proposal-hash '2bba1bb36ae552812b4b9e0d730249a3447adfc3ed100e0f4d92e3a8c28e7573'
python3 main.py --db /tmp/c12.db --output /tmp/c12-draft.txt resume run-3
# → output_conflict
cat /tmp/c12-draft.txt
# → different content（原内容未被覆盖）

批准后 request/proposal 替换与故障窗口恢复这两条路径涉及直接改 SQLite 或注入崩溃，不便用 CLI 逐条演示，改由单元测试覆盖（见第四节和第五节的 sqlite3 篡改命令，以及 test_main.py 里的 test_post_approval_request_replacement_is_rejected、test_post_approval_storage_tampering_is_rejected、test_crash_after_file_creation_is_recovered_without_rewrite）。完整命令见第四节实验一/实验二，故障窗口恢复的注入点见第五节。测试定位方式：

# 批准后替换 request_id → 恢复被拒
python3 -B -m unittest test_main.DurableResumeTest.test_post_approval_request_replacement_is_rejected -v

# 批准后同时替换 args + proposal_hash → 恢复被拒
python3 -B -m unittest test_main.DurableResumeTest.test_post_approval_storage_tampering_is_rejected -v

# 文件创建后注入崩溃 → 恢复返回 recovered，不重写文件
python3 -B -m unittest test_main.DurableResumeTest.test_crash_after_file_creation_is_recovered_without_rewrite -v

Java 21

Java 版本在 GYA-Java 仓库，用仓库根的 Gradle Wrapper，需要指定 JDK 21。Java CLI 使用位置参数而非 --proposal-hash 选项：

export JAVA_HOME=/Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home

# 在 GYA-Java 仓库 clone 下来的根目录下
./gradlew :c12-durable-resume:test --no-daemon
# BUILD SUCCESSFUL, 10/10 通过

# output 统一用 /tmp/c12-draft.txt，与 Python 侧一致，保证两端 proposal_hash 相等
./gradlew :c12-durable-resume:run --no-daemon \
 --args='/tmp/c12-java.db /tmp/c12-draft.txt start run-1'
./gradlew :c12-durable-resume:run --no-daemon \
 --args='/tmp/c12-java.db /tmp/c12-draft.txt show-trace run-1'
# 复制 proposal_hash，传给 approve 的五个位置参数的第 5 位：
./gradlew :c12-durable-resume:run --no-daemon \
 --args='/tmp/c12-java.db /tmp/c12-draft.txt approve run-1 2bba1bb36ae552812b4b9e0d730249a3447adfc3ed100e0f4d92e3a8c28e7573'
./gradlew :c12-durable-resume:run --no-daemon \
 --args='/tmp/c12-java.db /tmp/c12-draft.txt resume run-1'

两端的 Trace 遵循同一份事件语义约定：

checkpoint_saved → proposal_recorded
→ proposal_verified → approval_recorded
→ proposal_verified → resume_started
→ action_executed | action_recovered

负向路径按原因产生 proposal_rejected、resume_rejected、transition_rejected 或 action_conflict。Python 和 Java 的 JSON 字段顺序不要求一致，但事件语义、原因和先后关系一致，两端 proposal_hash 完全相等。

常见坑

Gradle 提示 JDK 25 不兼容。 错误信息为 IllegalArgumentException: 25.0.3。本机默认 JDK 是 25，Gradle 8.14.2 不兼容。确认 JAVA_HOME 指向 JDK 21 即可：

export JAVA_HOME=$(/usr/libexec/java_home -v 21)

Python 找不到 sqlite3 模块。 Python 需编译时带 SQLite 支持，绝大多数发行版和 macOS 自带——如果报 ModuleNotFoundError: No module named '_sqlite3'，用包管理器重新安装带 sqlite 支持的 Python。

七、从本地文件幂等走向生产副作用

SQLite 的 BEGIN; ...; COMMIT 只保证数据库内部的原子性。resume 里「创建文件 → 更新 checkpoint」这两步，不在同一个事务里——文件系统是数据库外面的世界。

本文的解法是业务幂等键：文件路径 output 就是幂等键——它同时是 proposal 里被哈希锁定的不可变部分（第三节），也是执行时判断「是否已经写过」的依据。FileExistsError（Python）/ FileAlreadyExistsException（Java）只表示目标已存在，不是去重——demo 在捕获异常后显式比较内容：相同时视为 recovered，不同时回绝 output_conflict 并在 Trace 中记录 expected_content_hash（本应写入内容的 SHA-256）和 existing_content_hash（已存在文件内容的 SHA-256），两者对同一份字节内容做摘要、可直接对照。关键条件是：

创建使用 CREATE_NEW / "x" 模式——已存在时抛异常，不会静默覆盖。
内容不同时显式回绝 output_conflict——不是说「已存在就是成功」。

生产系统要补的东西跟这篇 demo 没有本质冲突，但代价不同。下面这张表里的「生产系统」一列，是超出本文验证范围的设计候选，不是已跑通的实现——本文只证明左边「本文 demo」一列：

维度	本文 demo	生产系统（设计候选，未验证）
幂等键来源	固定文件路径（`CREATE_NEW`）+ 纳入 proposal 哈希	业务幂等键（订单号、消息 ID）+ 目标系统去重
恢复策略	文件内容比较	outbox + inbox 模式、目标端幂等写入 + 查询
审批记录	SQLite 单库（可信边界）	审计日志表 + 分布式锁 + 签名/加密（防篡改）
多实例竞争	不涉及（本地单实例，无并发）	`SELECT ... FOR UPDATE` 或乐观锁
审批超时/取消	不涉及	过期策略 + 补偿

核心判断是：SQLite 事务只管得了数据库内部。 它不能包住「把文件写出去」这个副作用。一条 INSERT 和一次 os.write() 之间，隔着一道事务边界。本文只证明了这一层本地文件幂等——CREATE_NEW 加内容比对，能在「文件已存在」时区分「上次已成功」和「内容冲突」。至于跨系统、跨进程、跨服务的端到端 exactly-once，涉及目标端去重、分布式事务或 outbox 等本文没有实现的机制，不在这里下结论。右侧每个候选方案具体怎么落地、在哪些场景失效，是后续工程化扩展的话题，本文不展开。

八、回到开头的那三个洞

这篇文章从头到尾只做了一件事：在 C11 证明「当前 Run 能停」之后，证明「同一个 Run 跨进程还能安全地继续」。它不靠框架、不用 API Key、不扯分布式——只靠 SQLite 单库 + 两组快照 + 本地文件幂等键。把开头的结论收回来，三个洞各有一个明确的堵法：

找错对象。 批准那一刻冻结 approval_request_id（批准的是哪次请求）和 approval_hash（批准的是哪个动作，含 action/args/output）两份快照，恢复时拿「现在」去对「当时」，对不上就拒——第四节的实验一、实验二、实验三分别验证了这两份快照各自挡得住什么。
重复执行。 正常重放靠 executed 标记兜底；最痛的那道缝（文件写了、checkpoint 没写）靠文件幂等键兜底——第五节的两个场景分别验证。
无声失败。 每次拒绝都在 Trace 里留一条带 reason 的事件，附上被拒的原始输入（尝试的决定、提交的 hash、当前的 request/action/output），审计时能还原「拒了什么、为什么拒」。

三件事讲完，这套恢复协议在本地单实例、无并发竞争的边界内是自洽的：一份 SQLite、一个待执行动作、一个用户在操作，恢复靠「换一个新进程、打开同一份 .db」来完成——这跟「进程会退出、第二天再回来」的场景正好对上。往边界外走一步——多个 Agent 拆成不同角色协同，一个用户批准了 Agent A 的请求，Agent B 怎么知道？同一个 run_id 跨 Agent 传递会不会串？这份「冻快照 + 幂等键 + Trace」的协议，在多 Agent 世界里还能不能原样成立，是下一篇要回答的问题。

参考资料

正文引用的来源，按首次出现顺序排列：

LangGraph. Interrupts. https://docs.langchain.com/oss/python/langgraph/interrupts
LangGraph. Persistence. https://docs.langchain.com/oss/python/langgraph/persistence
SQLite. Transaction. https://www.sqlite.org/lang_transaction.html
SQLite. Atomic Commit. https://www.sqlite.org/atomiccommit.html

配套 Python 与 Java 实现在 GYA 仓库与 GYA-Java 仓库的 c12-durable-resume 目录，按 README 的命令跑，不复制这篇文章里零散的代码块。

第十一话｜Agent 为什么会停下来：从模型信号到 Runtime 状态迁移

Sat, 04 Jul 2026 00:00:00 +0000

给一个 Agent 下达这样的任务：根据给定主题和本地资料，整理一份有依据的技术文章创作纲领，然后停下来等用户确认；确认之前，不生成正文草稿。

在 Codex、WorkBuddy 这类产品里，这个任务的表现可以直接观察到：它检索、读资料、写出一份纲领，然后停下，把纲领和一句「是否继续」摆在你面前；你回复之后，它接着往下做。

停这件事看起来理所当然，其实需要解释。模型的输出是一段文本或一段 JSON。它在里面写「请确认」四个字，不会让 Python 的 while 循环条件变成 False，也不会让 Java 的线程进入等待。语言表达能力，和程序控制流，是两码事。

上一话把问题停在「下一步到底由谁拍板」。这个问题的答案里有一类决定和工具动作不同：工具动作有对应的执行路径，而「停下来等用户」没有对应动作可执行——它要求的是一次状态变化。模型已经说了「请确认」，程序为什么不像往常那样继续循环？

整篇只回答这一件事：模型只产生候选信号，Runtime 才拥有状态迁移权。 前面所有的机制、对照、证据，最后都汇到这句话上。

一、「请确认」不是指令

先回答第一个问题：模型说出「请确认」，为什么本身不能停掉任何东西？

先看两个最短的版本。它们跑同一个模型、同一个任务，唯一的区别是循环里有没有一处处理等待信号。

缺陷版：

while True:
 decision = model.decide()
 print(decision)
 # 没有处理 REQUEST_USER_INPUT：它只是一行被打印出来的输出

正确版：

while state.status is RunStatus.RUNNING:
 decision = controller.decide(state)
 transition = runtime.handle(decision, state)
 if transition.status is RunStatus.WAITING_FOR_USER:
 return transition

差别只有一个分支。缺陷版把决定当数据打印出来，控制流继续；正确版把决定交给 Runtime，由 Runtime 迁移状态、再由调度循环按状态退出。

把这两个版本放回真实 demo 上，用同一批离线夹具各跑三种控制器，输出是这样的（数字取自本仓库 traces/offline-python-normal.log 与 traces/offline-python-naive.log，Java 侧逐字段一致）。为了不在一开始就淹没在代号里，先只看两列最要紧的：最终状态，和「草稿到底写没写出来」。

模式	最终状态	草稿写出
缺陷版 react	还在跑（RUNNING）	否
缺陷版 plan_and_execute	报完成（COMPLETED）	否
缺陷版 workflow	报完成（COMPLETED）	否
正确版 react	等用户（WAITING_FOR_USER）	否
正确版 plan_and_execute	等用户（WAITING_FOR_USER）	否
正确版 workflow	等用户（WAITING_FOR_USER）	否

一张表就能看懂差别：正确版三种模式都停在「等用户」，缺陷版没有一行停对——要么还在跑，要么更糟，报了个「完成」却没写出任何东西。

缺陷版那两种走法，各自说不上停：

react 把预算耗光了（一路反复读资料读到 8 步用尽），状态停在 RUNNING，但日志里却有一个「说过要等」的标记。
plan_and_execute 越过了等待点，一路走到 write_draft（写草稿），被准入检查拦下，然后以 COMPLETED 收场——一份没有被写出来的草稿配一个完成状态。

第二种走法值得单独看一眼：它既没有写任何东西，也没有停下来，最后还报了个完成。这就是「没有写入不等于已经暂停」的最小复现。缺陷版里那个「说过要等」的标记只是一个数据记录，它记录「模型说过要等」，不记录「循环已经退出」。

结论落在这一步：语言表达本身不能暂停程序。能被处理的，是被 Runtime 识别出来的结构化信号。

二、停下来的那一刻，长什么样

上一节证明了「信号不能自动停程序」。这一节反过来问：当程序真的停下来时，我们凭什么说它停了？换句话说，什么是「停」的判据。

status == WAITING_FOR_USER（状态标记为等用户）本身不构成证明。它只说明 Runtime 写了一个值；写值的那一刻，和「写完之后没有新调用」，是两件事。要证明停，得看等待之后有没有新的调用发生。

判据写成函数是这样：

def is_run_suspended(result: ModeResult) -> bool:
 state = result.final_state
 model_delta, tool_delta = state.calls_after_wait()
 return (
 state.status is RunStatus.WAITING_FOR_USER
 and state.pending is not None
 and model_delta == 0
 and tool_delta == 0
 )

四个条件同时成立才算停：状态是 WAITING_FOR_USER、留了 pending request（待处理的请求）、等待之后没有新的模型调用、没有新的工具尝试。缺陷版会在这条判据上失败——这正是测试发现它的方式，而不是只证明正确版能通过。

「等待之后」要算得出来，得在迁移的同一刻做快照：

def snapshot_wait(self) -> None:
 self.model_calls_at_wait = self.model_calls
 self.tool_attempts_at_wait = self.tool_attempts

这不是可有可无的一行。如果只在循环结束时同步计数，等待后的增量就会被算成全部调用——判据看起来还在测，其实已经失效。这个缺陷在重构时出现过一次，被测试逮住。

判据要落到一组断言上才算验收。这次 Python 与 Java 各 20 项测试，覆盖的是同一批语义：

验收断言	落在哪里
等待后模型调用数不再增加	`client.calls` 在迁移之后不再变化
等待后业务工具尝试数不再增加	`tool_attempts` 在迁移之后不再变化
受保护写入没有被尝试	`write_draft` 从未成功落库
pending request 完整	`request_id` / `question` / `state_before` 都在
方法已返回调用方	调度循环以 `run_exited` 结束，不是预算耗尽
非法等待信号被拒	缺失状态下 `REQUEST_USER_INPUT` 不产生迁移

一次等待在 Trace 里留下五类事件，按顺序出现：

signal_received ← 信号由谁产生（signal_source）
runtime_validated ← Runtime 是否接受（runtime_decision）
state_transition ← state_before → state_after
pending_recorded ← pending_request_id
run_exited ← Scheduler 退出当前 Run

三个信号来源产生的都是这同一个序列，类型和顺序一致。真正回答「停了吗」的是最后一个事件：run_exited 而非 budget_exhausted。前者是调度器主动退出，后者是把预算用完了。

到这里，我们已经知道「停」长什么样、怎么判。但还没说：谁有资格做那个把状态改掉的动作？

三、Agent 内部，谁有资格让 Run 停

这一节回答的是全文最关键的一处分工：Agent 的模型、Runtime、调度器、界面四层，各自能做什么、不能做什么。

把角色摆到后端工程师熟悉的位置上，整条链只有四层：

层	负责什么	不负责什么
模型	根据当前上下文提出动作、结束、或请求用户输入	不改变程序状态、不停止循环、不执行任何动作
Runtime	解析模型输出，校验这条信号在当前状态是否合法，决定状态迁移	不生成内容、不选业务动作
Scheduler / Agent Loop	按 Runtime 给出的状态决定继续循环还是退出当前 Run	不解释模型语义、不做合法性判断
UI / Continuation	展示问题、接收用户输入、创建下一次执行	不修改状态、不推断用户想要什么

换成后端里已有的说法：模型的输出是一条消息（或一个领域事件）；Runtime 是消费者 + 状态机；Scheduler 是任务调度器；UI 是等待外部命令的入口。消息本身不会被执行，它要被消费、被解释、被判断，才产生后果。

链上只有一个位置能写 status，就是 Runtime。其余三层都可以提请求，但提请求和改状态是两回事。

这不是某一家的实现偏好，Anthropic 把它写进了 Messages API 的接口契约：每个响应都带一个 stop_reason 字段，说明模型为什么结束生成；调用方检查这个字段，再决定是原样使用、继续对话、重试，还是回退到别的模型。字段的取值里没有任何一个是「程序已暂停」——tool_use 的含义是「我在调工具，你去执行」，end_turn 的含义是「我说完了」。模型交出的是一个原因码，怎么处理由外层决定。

同一份契约在 pause_turn 上表现得更清楚：服务端工具循环达到迭代上限时，响应会带 pause_turn 返回。这不是进程被挂起，而是调用方拿到一段没处理完的响应，需要把它原样发回去让模型接着跑。

把四层串起来，数据流是这样：

模型生成候选决定
 ↓
Runtime 解析决定类型
 ↓
Runtime 检查当前状态是否允许这条决定
 ↓
状态从 RUNNING 迁移到 WAITING_FOR_USER
 ↓
记录 pending request
 ↓
Scheduler 看到 WAITING，退出当前 Run
 ↓
UI 展示问题
 ↓
用户提交下一条输入
 ↓
新的 Run / continuation 根据关联标识继续

%%{init: {'theme':'neutral'}}%%
flowchart TB
 M["模型
只提出决定"] -->|"决策"| R["Runtime
解析 → 校验 → 迁移"]
 R -->|"CONTINUE"| M
 R -->|"WAITING_FOR_USER"| S["Scheduler
退出当前 Run"]
 S --> U["UI / Continuation
展示问题、接收输入"]
 U -.->|"下一次 Run"| M

最后一步「根据关联标识继续」在这里只做到单进程的程度，跨进程的部分留到下一话。

信号要能被识别，得先有一个共同的格式

三种来源共同遵守的格式，是四种决定类型：

class DecisionType(Enum):
 EXECUTE_TOOL = "EXECUTE_TOOL"
 REQUEST_USER_INPUT = "REQUEST_USER_INPUT"
 FINISH = "FINISH"
 FAIL = "FAIL"

模型、Planner、Workflow 产出的都是同一个结构，而不是执行结果：

@dataclass
class ControlDecision:
 type: DecisionType
 action: Optional[str] = None
 args: Optional[Dict[str, Any]] = None
 question: Optional[str] = None
 reason: Optional[str] = None

字段的可选性是刻意的。REQUEST_USER_INPUT 用 question，EXECUTE_TOOL 用 action 和 args；某一类里字段缺失是正常输入，不应该在解析阶段就崩，校验属于 Runtime 的职责。

调度循环的形状因此变得很平：

while state.status is RunStatus.RUNNING:
 decision = controller.decide(state)
 transition = runtime.handle(decision, state)
 if transition.kind in {"SUSPEND", "COMPLETE", "FAIL"}:
 break

controller.decide() 只提出决定；runtime.handle() 才拥有状态迁移权。这句分工是后面所有代码的前提，它把「谁让 Run 停」从模型和模式里移出来，交给了一个有名字的组件。

runtime.handle() 内部按五个动作走：

%%{init: {'theme':'neutral'}}%%
flowchart TB
 A["原始输出"] --> B["1-2 解析 + 类型校验
解析失败即明确失败"]
 B --> C["3 状态前置条件校验
当前状态是否允许这条决定"]
 C -->|"不满足"| D["拒绝并记账"]
 C -->|"满足"| E["4 迁移状态 + 记录 pending request"]
 E --> F["5 返回 transition
Scheduler 据此决定是否退出"]

第 3 步是新增的一层，也是这里唯一需要做取舍的地方：模型请求等待时，Runtime 要不要校验它此刻有没有等待的对象？如果只做类型校验，模型可以在任何时刻宣称「我要等用户」，而那时根本不存在被等待的东西。所以 REQUEST_USER_INPUT 在纲领生成之前一律拒绝：

if decision.type is DecisionType.REQUEST_USER_INPUT:
 if not state.brief_created:
 return "wait_signal_without_pending_object"
 if not (decision.question or "").strip():
 return "wait_signal_without_question"
 return None

非法的等待信号不会悄悄过去：rejected_signals（被拒信号数）加一，Run 转成明确失败。合法的等待信号则走完整的迁移，留下 pending request：

self._pending_seq += 1
pending = PendingRequest(
 request_id=f"approval_{self._pending_seq:03d}",
 question=(decision.question or "").strip(),
 state_before=state_before,
)
state.pending = pending
state.status = RunStatus.WAITING_FOR_USER
state.snapshot_wait()

state_before 记下迁移前的状态，question 记下要问用户什么，request_id 是用户回来时用来关联的标识。三者一起构成「这一次等待是谁、为了什么、从哪个状态发起」。

这也正好对上 OpenAI Agents SDK 的用法：那里批准一项工具调用的方式是围绕 interruptions 展开的——运行中断后，结果里带回一个待处理数组和一份可恢复的状态，批准就是在这个状态上做的决定。两种写法用词不同，位置一样：改状态的那一步在框架（Runtime）里，不在模型输出里。

四、等待信号从哪来

现在回到上一节开头埋下的问题：模型不是唯一会提「要停」的角色。同一个 Runtime 入口，等待信号可以来自三个地方。三种控制器共用同一套工具、同一个 ActionGateway、同一个 Runtime，差异只留在「谁产生信号」这一处。

ReAct：模型每次看到工具结果后重新提出一条决定。等待信号由模型自己在上下文里提出，比如输出 {"type": "REQUEST_USER_INPUT", "question": "纲领已生成，是否继续写正文？"}。Runtime 认出来就停。
计划步：Planner 一次生成整份计划，其中一步是等待。Executor 执行到那一步，把它原样交给 Runtime。计划可以声明等待点，但计划文本本身没有暂停能力。
Workflow 节点：节点序列写在代码里，等待是其中固定的一站。节点内部的内容仍然由模型生成，代码固定的是「走到哪个节点」。

三种来源最后汇入同一个入口：

%%{init: {'theme':'neutral'}}%%
flowchart LR
 R["ReAct
模型提出"] --> RT["Runtime.handle()
接收 ControlDecision"]
 P["计划步
Planner 写入计划"] --> RT
 W["Workflow 节点
代码固定位置"] --> RT
 RT --> ST["RunState
RUNNING → WAITING_FOR_USER"]
 ST --> SC["Scheduler
退出当前 Run"]

这就是三种模式在这篇文章里真正的位置：它们是「信号来源」，不是「三种对等的 Agent 设计」。谁先提不重要，重要的是提信号和停程序是两件事——无论信号来自模型、计划还是代码，改状态的那一步都在 Runtime。

三个来源的模型调用次数本来就不同，这一点在输出里也如实保留：正确版 react 是 5 次，plan_and_execute 和 workflow 各 1 次。决策粒度不同，调用次数就不该被凑成一个数。

两条补充，都是旧版说错、这次改对的，不影响主线：

关于「模型能不能主动请求确认」，这次跑了一组真实实验：deepseek-v4-flash，6 次，日志在 traces/live-run-1..6.log。结果是这 6 次里没有一次产出可被 Runtime 解释的等待决定——3 次把 8 步预算耗在反复读同一份资料上，另外 3 次的输出无法解析（模型把决定多包了一层 {"type":"json_object","content":{...}} 信封，Runtime 只认顶层的 type，认不出就判失败）。这段证据的强度有明确边界：它只说明在指定模型、提示词、工具协议和输入下模型没有产生预期结构，不能推广成「模型不会请求确认」。同一个服务端在 temperature=0 下输出并不可复现：这 6 次里预算耗尽 3 次、解析失败 3 次，两次分批运行的分布还不同。

关于 ReAct 的旧结论也要改：之前把「绕圈」归因为「每一步只拿到当前观察，看不到任务整体」，这与代码不符——每次请求传入的是完整的观察累积历史，不是最新一条。当前能写的只有：在本次模型、提示词、动作协议和 8 步预算下，模型连续重复读取了同一份资料；Trace 证明了重复行为，不足以把原因唯一归结为 ReAct 模式。

另外两处旧版的不实也一并纠正：Planner 的提示词曾硬编码「先读 material_1，再读 material_2」，而 ReAct 必须自己从工具结果里发现顺序，那不是对等的比较——现在三个控制器拿到同一份初始清单，只知道有哪些资料、不知道先读哪一份；Workflow 曾有一个假分支——代码无条件读取第二份资料，却在 Trace 里标成「读到线索之后触发的分支」，现在第 3 个节点做真实判断，没有线索就不读第二份，branch_taken 如实记为 false。

三种实现可以组合，它们不在同一个对立面上：Workflow 固定阶段，ReAct 在阶段内部按线索选资料，Planner 负责跨子任务的覆盖。组合之后，「停」这件事仍然只有 Runtime 一处负责。

五、为什么不能只用一个布尔值

前面一直在用 status 这个枚举。这一节讲为什么它必须是枚举，不能是 waiting=true 这样的布尔。

状态本身是枚举：

class RunStatus(Enum):
 RUNNING = "RUNNING"
 WAITING_FOR_USER = "WAITING_FOR_USER"
 COMPLETED = "COMPLETED"
 FAILED = "FAILED"

用布尔 waiting=true 表示等待，会丢掉两件需要区分的事：一是「等待」和「完成」「失败」是并列的终态关系，布尔表达不了；二是标记为真和调度退出是两步，布尔把两步压成一步，就再也分不出「标记了但还在跑」这种状态。缺陷版 plan_and_execute 那一行正是这个压缩的后果：它有个「说过要等」的标记，状态却一路跑到了「完成」。

回到那张表补全字段，现在这些代号已经都有中文含义了：

模式	terminal_reason （结束原因）	status （状态）	waiting_marker （说过要等）	model_calls （模型调用）	tool_attempts （工具尝试）	rejected_actions （被拦动作）
缺陷版 react	budget_exhausted	RUNNING	true	8	4	0
缺陷版 plan_and_execute	completed	COMPLETED	true	1	5	1
缺陷版 workflow	completed	COMPLETED	true	1	4	0
正确版 react	wait_suspended	WAITING_FOR_USER	false	5	4	0
正确版 plan_and_execute	wait_suspended	WAITING_FOR_USER	false	1	4	0
正确版 workflow	wait_suspended	WAITING_FOR_USER	false	1	4	0

正确版三行的其余字段完全相同：pending_request_id=approval_001、draft_written=false、approval_granted=false、model_calls_after_wait=0、tool_calls_after_wait=0。

waiting_marker=true 在那三行缺陷版里都是一个数据标记，它记录「模型说过要等」，不记录「循环已经退出」——正是布尔值把这两件事压成一个所付出的代价。

六、和「动作能不能执行」是两回事

最容易和「暂停」混起来的机制是动作准入。这一节把两个问题的边界切开。

	Action Gateway	Runtime
回答的问题	这个动作能不能执行	当前 Run 要不要继续
检查时机	副作用发生之前	每条决定之后
拒绝的后果	这个动作不执行，Run 可以继续	状态迁移，调度可能退出
拦住之后	一次动作被挡	与「已暂停」无关

受保护写入的检查就在写入之前：

def _write_draft(self, args: dict, state: RunState) -> str:
 if not state.approval_granted:
 return "blocked_by_action_gateway"
 ...
 state.draft_written = True
 self.store.save_draft("draft_1", content)
 return "draft_written"

未获批直接返回，不碰 store。这条检查把「写不进去」办到了，但它对「Run 停不停」一句话也没说。缺陷版 plan_and_execute 那一行就是证据：rejected_actions=1，写入被拦住了，循环继续跑到 completed。

Codex 的官方文档把这两种控制分开，用词几乎一样：沙盒模式定义的是「模型生成的命令在技术上可以做哪些操作」，审批策略定义的是「Codex 在执行某项操作之前必须何时停下来询问用户」。文档里那句话可以直接搬过来——沙盒定义技术边界，审批策略决定越界前何时必须停止并询问用户。前者对应 Gateway，后者才对应 Run 的继续与停止。

七、这些产品，其实都这么做

前面把机制讲完了，这一节把视角拉远：这些机制不是我们自说自话，几个主流框架的文档描述的是同一件事。

产品上的现象是清楚的：这些 Agent 会结束当前回合并把问题展示给用户，用户输入之后可以开启后续执行。这说明它们存在某种回合终止与 continuation 机制。

这一段能写到什么强度，取决于有没有官方来源。Codex 是有文档的：审批策略是运行配置，取 on-request 表示默认在沙盒内工作、需要越界时询问；approvals_reviewer 的默认值是 "user"，即审批请求路由到用户，也可以设为 auto_review 由审查智能体处理。这说明「停下来问谁」是运行时配置的一部分，而不是模型自身的能力开关。

OpenAI Agents SDK 的文档把暂停这一步写得最直白：当一次工具调用需要审批时，SDK 暂停这次运行，返回待处理项，之后可以从同一个 RunState 恢复。暂停的执行者是 SDK，不是模型——分工和前面一致，只是它把 Runtime 的角色交给了框架。

LangGraph 的 interrupt 走的是同一路线，并且把持久化的一环显式化：在节点里调用 interrupt 之后，图执行在调用点挂起，状态由持久化层保存并无限期等待，恢复时用同一 thread_id 重新调用图。文档同时说明，恢复时整个节点会从头重跑，interrupt 之前的代码会再执行一次。这条细节很有用——它说明「挂着的那一步」和「恢复时怎么重放」是两个要分开设计的约束。

从这些来源能推出来的，只到这里：被观察到的产品行为，与官方框架文档描述的「运行时暂停 + 携带状态恢复」是同一类机制。 再往下不能推：

不能写它们内部一定用了某个类、某张表或某个具体状态机；
不能写 WorkBuddy 与 Codex 的实现相同——WorkBuddy 这一段只有可观察行为，没有可引用的实现契约；
不能把框架文档的接口承诺当成产品内部实现的证明。文档承诺的是「怎么用」，不是「里面怎么写的」。

这条边界不是保守，是证据强度决定的：官方文档能证明「这套机制存在且被这样描述」，证明不了「这个产品内部就是那样实现的」。

八、停只是前半场

三种来源都在同一处收尾：纲领生成，Run 进入 WAITING_FOR_USER，本次调用返回。Trace 里能看到状态、看到等待原因、看到哪些动作被拒绝，唯独看不到一件东西——这次调用退出之后，谁记得有一份纲领在等确认。

单进程里 return 退出的是当前这一次函数调用。pending、brief_id、已经走到哪一步，全在内存里，程序一退就没了。用户几分钟后回来，或者进程中途重启，系统凭什么找到对应的纲领、对应到哪一次等待、恢复到哪个进度？

这一步不是加一行持久化就能收尾的，它牵出四个互相牵连的问题：

等待请求怎么存下来，重启之后还能按标识找回来；
审批结果绑定到哪个对象——是这次 Run，还是被批准的那个具体动作；
恢复之后怎样保证不重复产生副作用；
重复审批、超时、用户直接取消，各自该走到哪个状态。

Anthropic 那句 pause_turn 的语义在这里反过来读也成立：调用方必须把没处理完的内容原样发回去才能接着跑。也就是说，「恢复」不是自动发生的，它需要有人带着上下文重新发起。

下一话接着讲：Run 停下来之后，怎样把状态存到进程之外，又怎样安全地接着跑。

参考资料

正文引用到的来源，按首次出现顺序排列：

Anthropic. Stop reasons and fallback. https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons
Anthropic. How tool use works. https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/how-tool-use-works
OpenAI. Guardrails and human review. https://developers.openai.com/api/docs/guides/agents/guardrails-approvals
OpenAI Agents SDK. Human-in-the-loop. https://openai.github.io/openai-agents-js/guides/human-in-the-loop
OpenAI. Codex: Agent approvals & security. https://developers.openai.com/codex/agent-approvals-security
OpenAI. Codex: Sandbox. https://developers.openai.com/codex/concepts/sandboxing
LangChain. Plan-and-Execute Agents. https://www.langchain.com/blog/planning-agents
LangGraph. Workflows and agents. https://docs.langchain.com/oss/python/langgraph/workflows-agents
LangGraph. Interrupts. https://docs.langchain.com/oss/python/langgraph/interrupts
Yao et al., 2022. ReAct: Synergizing Reasoning and Acting in Language Models. arXiv:2210.03629. https://arxiv.org/abs/2210.03629

配套 Python 与 Java 实现在 GYA 与 GYA-Java 两个仓库的 c11-suspend-protocol 目录，按 README 的命令跑。