Agent Loop 是不是状态机
一个没有
phase字段的状态机,靠什么运转
引言
关于 Claude Code 的 query(),流传最广的一句定性是"它是一个状态机"。讲得再细一点,会说它有若干"Continue Site",每次转移到下一轮都带着一个 transition.reason 字段。
但这个定性对不上代码。
src/query.ts 里搜不到 phase,也搜不到 stage;State 的类型定义是十个字段,全是数据,没有一个是"我现在处于什么状态"的判别式;主循环是 while (true) 加一长串顺序执行的语句,没有 switch。
于是一个自然的怀疑是:这个词是不是被用松了。
我的判断是没有被用松,但话得说准:
它的状态从来没有被完整写下来——有一半信息由顺序执行本身携带,所以没人需要把它写成变量。
而它的转移不是被外部事件触发的,是被模型说服的。
这篇文章把这个判断拆开,从最容易被讲玄的那个词开始。
一、它看着像普通循环,其实要件一个不缺
第一眼看上去,这套代码根本不像状态机。原因有三层。
伪装一:主循环是 while (true),不是 switch (state)。 教科书里的状态机长这样:
while (true) {
switch (state.phase) {
case 'idle': ...
case 'running': ...
}
}
而它的主循环是这样的:
// src/query.ts:657
while (true) {
...压缩检查...
...调用模型...
...执行工具...
...错误恢复...
state = next
}
没有 switch,阶段之间靠的是"代码往下走"。
伪装二:没有 phase 字段。 状态机的标配是一个"我现在在哪"的判别式,它没有。
伪装三:State 长得像个缓冲区。 十个字段里,除了 transition 是元信息,其余全是数据(messages、各种计数器、待处理的 Promise)。这看起来像 useState 里塞了一坨,不像状态图。
三层叠起来,很容易得出一个错误结论:这不是状态机,只是一个带状态变量的循环。
但把形式要件一条条对上去,会发现问题不在"缺了什么",而在"为什么有些东西不需要存":
| 状态机要件 | 教科书写法 | 这里的落地 |
|---|---|---|
| 状态集合 S | enum Phase | 程序计数器 + State(位置隐式,数据显式) |
| 输入字母表 Σ | event | 流式增量 / tool_result / hook 结果 / AbortSignal |
| 转移函数 δ | switch | 6 个显式 continue + 1 个底部回边 |
| 守卫 | guard | hasAttemptedReactiveCompact、maxOutputTokensRecoveryCount |
| 终止状态 | halt | 10 个 return { reason } |
| 输出 | — | yield 出去的事件流 |
六条要件一条不缺。关键在于第一行:状态集合不是不存在,是其中一半从来没有被写下来——因为顺序执行已经替它记着了。 "我现在在第几阶段"由代码位置表达,"我走到这一步时带着什么"由 State 表达。
这个拆分有一个立刻可见的后果。如果状态真的全在变量里,那 State 应该能表达"我此刻在等模型"这件事——但它不能,State 里没有任何字段能说出这句话,因为这件事由 PC 停在 callModel 那一行来表达。反过来,位置也不知道"我已经压缩过三次",因为每轮都回到同一个位置,位置对累积信息无能为力。
这两类信息各自负责一类问题,谁也替代不了谁。 后面几节要展开的,就是它们各自长什么样、怎么配合、代价是什么。
二、七个 continue,每个都配着四件事
Continue Site 常被讲得很玄,其实它就是一个 continue 关键字所在的位置。continue 干的事只有一件:把执行位置送回循环体顶部。它没有记忆、没有快照、不做任何"保存"。
真正有内容的是它周围的四件事。以 collapse_drain_retry 这一处为例:
// src/query.ts:1872-1888
const next: State = {
messages: drained.messages,
// ...另外 9 个字段
transition: {
reason: 'collapse_drain_retry',
committed: drained.committed,
},
}
state = next // 换记事本
continue // 跳回顶部
拆开看,四件事各回答一个问题:守卫回答"该不该走这条路",state = next 回答"带着什么走",transition.reason 回答"为什么走",continue 回答"走到哪去"。
四问凑齐,才是一次完整的状态转移。少任何一个都会出问题:少守卫就是无限循环;少新状态就是原地打转,重试了但什么都没变;少原因就是出了问题说不清怎么来的;少回边就不是循环了。
这四件事之所以必须挤在同一个地方,是因为它们必须原子。换状态和标记原因如果分开写——先 state = next,过二十行再补 transition——中间那段代码看到的就是一个"新状态 + 旧原因"的组合,而这个组合在语义上不存在。transition 记录的是"我是怎么到这一步的",一旦和新状态错位,它记录的就不是这次转移,而是上一次的。
还要说明一点容易被误解的地方:transition 是单槽,不是历史。它的类型是 Continue | undefined,每轮 state = next 都会把它整个覆盖。所以从它身上只能读到"上一跳为什么来",读不到"这一路都怎么来的"。想还原完整路径得靠日志和 transcript,这个字段不承担那个职责——它只服务两个具体用途:做守卫(state.transition?.reason !== 'collapse_drain_retry',全仓只有这一处读它),以及给测试做断言。
7 个转换点,和两类不算站点的东西
会替换 State 的转换点一共 7 个:
| # | transition.reason | 位置 | 为什么又转一圈 |
|---|---|---|---|
| 1 | collapse_drain_retry | :1888 | 413,先把折叠排空 |
| 2 | reactive_compact_retry | :1959 | 413,压缩历史 |
| 3 | max_output_tokens_escalate | :2039 | 输出被截断,调高上限 |
| 4 | max_output_tokens_recovery | :2071 | 输出被截断,追加"接着写" |
| 5 | stop_hook_blocking | :2148 | stop hook 报了错,塞回去改 |
| 6 | token_budget_continuation | :2196 | 预算还剩,推模型继续 |
| 7 | next_turn | :2651 | 模型要求调用工具 |
第 7 个是回边但不是显式 continue:它在 while 底部,执行到底自然回到顶部。
流传的"8 种""9 种"里多出来的,都不是站点。
第一类是自环。 "模型降级重试"(主模型过载)走的是内层循环:
// src/query.ts:1243
let attemptWithFallback = true
try {
while (attemptWithFallback) {
attemptWithFallback = false
try { ...callModel... }
catch (innerError) {
attemptWithFallback = true
continue // :1645,属于内层 while
}
}
}
它不产生新 State,不经过任何 Continue Site。从状态图看这是 δ(s, fallback) = s。自环意味着"状态没变,只是重试",回边意味着"状态换了,进入下一轮"——混在一起数,就会把 7 数成 8。
第二类是被误计的回流。 "工具权限重试""子智能体结果注入""记忆更新触发"这三种没有自己的代码位置,全部搭 next_turn 的顺风车:权限被拒产出一条 tool_result,子 agent 的结果就是一次工具调用的返回值,记忆更新变成一条 attachment,三者走的是同一条边。
这是把"原因"和"地点"混为一谈。去北京的理由有一百种,但火车站只有一个。
区分它有实际后果:想加一个新的工具结果来源,不需要新站点;想加一条新的恢复路径(比如超时重试),必须新站点,因为要换状态。
三、走到第几步,不需要任何变量
要理解为什么有些阶段信息不需要写成变量,得先知道 PC 是什么。
程序运行时,CPU 里有个寄存器叫 PC(Program Counter),存着"当前执行到哪条指令"。它是硬件自带的,每个程序一个,不用声明、不用更新。"我现在在第几阶段"这个信息天然就在里面,不花一行代码。
这就是"位置免费"的字面意思。但要说清:这个性质属于所有顺序程序,不是这个系统的设计。
需要先划一条边界,否则容易读出一个并不存在的设计——没有任何一处代码在读取"我在第几行",所有守卫读的都是数据。位置只是"在那里",并且因为顺序执行而必然携带了阶段信息。作者没有把状态存进位置,他只是没有把位置已经表达过的东西再抄进变量。
所以更准确的说法不是"位置是这里最便宜的状态",而是"有些状态根本不需要被创建"。
字节码里看得见的回边
跑一段结构同构的 JS:
function f(log) {
let i = 0
while (i < 2) { log('A'); log('B'); i++ }
}
node --print-bytecode 出来的真实结果(V8 20.20.2):
@ 7 : JumpIfFalse [25] (→ @32) // 条件不成立 → 跳出 ← 出口边
@ 12 : CallUndefinedReceiver1 // log('A')
@ 19 : CallUndefinedReceiver1 // log('B')
@ 25 : Inc [5]
@ 28 : JumpLoop [26], [0], [6] (→ @2) // ★ 回边 ★
@ 33 : Return
@ 28 那行是 JumpLoop ... (→ @2),字面意思就是"把 PC 设回 @2"。回边在机器层不是一个比喻,是一条指令。
对比一下账单:i 的维护需要三条指令——Ldar r0 读、"Inc 加、Star0 写回;而"我在第几步"一条都不需要,JumpLoop 本身就是维护。这就是"免费"和"付费"的实际差别。
有两个常见的疑问,都指向同一个区分。
"地址是十六进制数字,不是状态变量吧?" 对,但它不是变量。反过来更准确:变量才是"有名字的地址"。字节码里的 r0 是寄存器槽位编号,i 这个名字运行时根本不存在,只活在源码和调试信息里。真正的区别只有一条——PC 由硬件自动维护,变量要由指令手动维护。
"地址会变吧?" 会,实测同一段代码跑两次:
第 1 次:0x38258b3636a8 @ 2 ... JumpLoop [26] (0x38258b3636a8 @ 2)
第 2 次:0x3f17970236a8 @ 2 ... JumpLoop [26] (0x3f17970236a8 @ 2)
绝对地址每次都不同(操作系统做地址随机化),但指令里写的是相对偏移 [26],不是绝对地址。代码里没有任何地方写死地址,所以地址变了不影响行为。语义依赖的是"谁在谁后面"这个拓扑,不是具体数值。
于是状态实际上分了三层:
| 层 | 活多久 | 例子 | 存在哪 |
|---|---|---|---|
| ① 代码位置 | 整个循环 | "现在走到阶段 5 了" | 行号(隐式) |
| ② 跨轮字段 | 整个 query | turnCount、hasAttemptedReactiveCompact | State |
| ③ 单轮局部变量 | 只有一轮 | needsFollowUp | 函数里的 let |
一次完整的状态,是这三层的组合。第三层最容易被忽略,却是下一节的关键。
四、同一个位置,可能是两种完全不同的处境
光看"走到哪"不够,还得看"手里拿着什么"。两者合起来才是完整的处境——本文把这种组合叫做一"格"。三个递进的例子能说明为什么必须两个一起看。
第一个例子说明光看位置不够。 模型刚回答完,代码走到同一个位置,但这里其实是两个格:
// src/query.ts:1817
if (!needsFollowUp) { // 模型说"我说完了"
yield* handleStopHooks(...) // 能跑停止钩子
return { reason: 'completed' }
}
...执行工具... // 只能在这里执行工具
站在 needsFollowUp === true 的格里能执行工具,但不能跑停止钩子——那段代码压根不会执行。站在 false 的格里能跑钩子、查预算、结束,但没有工具可执行。
"跑停止钩子"这个能力不是随时可用的,它只属于后者。而劈开这两个格的那个变量,是单轮的局部变量,根本不在 State 里。所以格不等于状态位,有些格由一轮就死的变量决定。
第二个例子说明光看数据也不够。 一个 413 来了,它本身一模一样,但能做什么取决于你之前走过哪些格:还没试过压缩,可以排空折叠、压缩、重来;已经压缩过了,什么都做不了,直接报错退出。
守卫写在两处——state.transition?.reason !== 'collapse_drain_retry'(src/query.ts:1865)和 hasAttemptedReactiveCompact。同一个错误,一次是"可救",一次是"绝症"。差别不在错误本身,在你站在哪一格。
第三个例子是两个格打架。 假设你已经在"压缩过了"的格,然后模型回答完,stop hook 把你拦住了。这时候代码要做一个选择:进入这个新格,要不要把"压缩过了"的记号擦掉?
直觉是擦掉,重新开始。真实答案是不能擦:
// src/query.ts:2140 附近
hasAttemptedReactiveCompact, // 原样传下去,故意不重置
注释把后果写得很白:重置为 false 曾导致无限循环——compact → 仍然过长 → 错误 → stop hook 阻塞 → compact,如此往复,消耗数千次 API 调用。
原因是擦掉之后,你在新格里会再次尝试压缩,但上下文一个字都没变,压缩注定还是失败,然后 stop hook 又拦住你,你又擦掉,又压缩。冲突时,"压缩过了别再压缩"这条规则赢。
而谁赢这件事,代码里没有任何机制保证,是靠人写注释记住的。
所以"我在哪一格"不是一个行号,它包含"我之前走过哪些格"。格与格之间不是独立的:你在上一格留下的记号,会否决你在下一格的想法。
三个例子连起来看,其实给了同一条判据:判断状态,不能只问"现在是什么",还得问"刚才发生过什么"。 前者查位置和数据,后者只能查数据——而且得是那个被刻意保留下来的数据。这也是为什么 hasAttemptedReactiveCompact 那行"故意不重置"的代码,比它看上去的份量重得多:它是这类"跨格记忆"最典型的一处。同类的还有 autoCompactTracking——压缩的失败计数也靠跨轮携带,用来在连试三次后熔断。
五、它随时会停下来,所以不能写成状态表
如果只是"作者偷懒没写 phase",这套设计不值得讨论。真正的约束有两条。
第一条是 yield 要求可挂起。 教科书里 δ 是同步、立即返回的纯函数。而这里一次转移要 await 四分钟的 API 调用,还要边生成边把 token 流出去。所以 δ 不能是表驱动的纯函数,只能是可挂起的协程。
顺序代码天然把阶段编码在控制流位置里,而协程让这个位置可以被暂停——生成器的栈帧因此同时承担"状态存储"和"挂起点"两个职责。这也是它不用 xstate 那类库的原因:显式化之后,每个 phase 都得拆成不能 yield 的函数,流式能力和取消语义都会丢。
第二条更根本:状态机被降级了。 传统状态机是决策者,自己想清楚该做什么;这里的状态机不决定做什么,它只记住走到哪了,决策外包给了 LLM。
所以你读代码会看到一个荒诞的比例:State 的类型定义 47 行,循环体 2000 行。这个比例本身就是答案。
转移里那十件事,按性质也只有三种:查(压缩检查、预算检查、错误恢复、停止钩子)、干(调模型、流式工具、工具执行)、收(注入上下文、组装并循环)。五查三干两收,就这些。
值得留意的是这三类各自的归宿。"查"全部落在守卫里,它们不改变状态,只决定走不走;"干"全部落在转移动作里,它们是真正有副作用的部分;"收"落在状态重写上,负责把这一轮的产物整理进下一轮的记事本。
换句话说,那十步看起来是一条流水线,其实分属三个不同的挂载点,只是被摊平在同一层代码里了。用状态图来画,它们会分散到边上、边内和点上三个位置;用顺序代码来写,它们只能排成一列。这就是为什么它读起来像流水线,本质上却是状态图。
六、不写 phase 要付的代价
"位置免费"不是白拿。
代价一:状态不可命名。 位置编码的状态没法打日志、没法断言、没法单测。所以哪里需要可观测,哪里就必须付费把它提出来。transition.reason 就是给位置编码的阶段买的一张收据。
代价二:状态不可序列化。 进程一死就没了。这也解释了一个设计选择:为什么 Claude Code 没有 checkpointer。因为能存快照的系统,一定把状态全部数据化了;这里有一半状态在 PC 里,PC 不能序列化,所以它从一开始就没打算做快照恢复,恢复靠 transcript 重放。
代价三:改代码顺序等于改状态机。 位置编码的系统里,代码排版就是架构图。把"预算检查"挪到"错误恢复"前面,状态机就变了,编译器一句话都不会说。
代价四:注释会漂移。 这条有实证:State 的类型定义里是 10 个字段,但文件头注释(src/query.ts:26)和 State 的文档注释(:427)都写着"所有 9 个字段在 continue 站点一次性更新"。差的那一个是 transition——显然是后加的字段,注释没跟上。
这不影响功能,但它精准说明了这个系统的软肋:靠契约和注释维持的地方,就是会漂移的地方。
四条代价有一个共同点:它们不来自某个失误,而来自"阶段交给位置表达"这件事本身的固有代价。 前面说"位置免费",现在该补一句——它免费的是当下,收钱的是未来:当下少写十个变量,未来就要多写十段注释、多背十条纪律。而这里之所以接受这笔账,是因为没有更好的选择:yield 要求可挂起,显式的状态表会失去流式与取消语义。
七、外面还有一层壳:QueryEngine
讲到这里,主角一直是 queryLoop。但它不是最外层。
往上走还有 QueryEngine(src/QueryEngine.ts:252)。它自己的注释把定位写得很清楚:query() 的上层包装器,负责构建 system prompt、处理用户输入(含斜杠命令)、管理 transcript 持久化、把内部消息映射成 SDK 格式、处理预算与轮次限制。
注意最后那半句的分工声明——"query.ts 的 query() 函数则负责:实际的 API 调用循环、tool use 的编排和执行、流式消息产出"。
所以它并不是循环的中枢——它是循环外面的一层壳,真正的调度在它下面一层。
但它并不是无关的。它参与纠错的方式很特别:记住循环够不着的东西。
| 层 | 记住什么 | 活多久 |
|---|---|---|
QueryEngine | 对话历史、拒绝记录、累计用量、文件读缓存 | 整个会话 |
query() | 一次提问内的消息流、命令生命周期 | 一次提问 |
queryLoop() | 一轮的 State、守卫、transition | 一轮 |
三个层次的关键差别在寿命。queryLoop 一轮结束就换掉整个 State;query() 一次提问结束就把控制权交回去;只有 QueryEngine 的 mutableMessages 是真正贯穿整个会话的。
在这个壳上,有两个很具体的纠错动作。
一是把拒绝攒起来,最后一次性交代(QueryEngine.ts:382-415)。它在 canUseTool 外面又包了一层,凡是返回值不是 allow 的,都记进 this.permissionDenials,最终随结果一起交出去。注释解释了为什么不直接塞进原函数——"保持原始函数纯净"。观察不一定立刻用,可以先攒着。
二是补上上一轮漏掉的那次批准(QueryEngine.ts:596-613)。场景是这样的:上一轮用户点了"总是允许",但这个批准在下一轮初始化时还没落地。于是在开头补应用一次,并且用 hasHandledOrphanedPermission 保证每个引擎生命周期只补一次。
第二个动作特别值得看一眼。它的形状和 Continue Site 里那些守卫一模一样:凡是要自动补做一次的事,都必须自带一个"已经补过"的记号。 否则补做本身就会变成新的死循环。
八、Continue 就是一次反思,而且这个模式能搬走
回头看第二节那四件事。把它们换成另一种说法,一个通用模式就浮出来了:
- 观察:守卫判断,拿到反馈,看还有没有招
- 改造:
state = next,换掉这次尝试的状态 - 记录:
transition.reason,写下"为什么回来" - 重来:
continue,回到起点再试一次
观察 → 改造 → 记录 → 重来。 这就是反思。
这套循环里其实同时跑着三个这样的环,代价依次递增:
最内环是模型自省。 工具失败的结果原封不动递回给模型,代码一句话不说。模型读到"退出码 1",下一轮自己换个命令。这个环最便宜——没有额外 API 调用,也没有额外提示词。
中间环是代码纠正。 413 了,代码替模型决定压缩历史;输出被截断了,代码替它调高上限或者追加一句"接着写"。模型甚至不知道发生过这些事——它只看到上下文突然变短了,或者自己的话被续上了。
最外环是人纠正。 权限被拒,或者计划被驳回,决定权交回给用户。这个环最贵:要等人。
三个环的分工不是偶然的。能自己改的自己改,改不了的让代码改,代码也改不了的才找人。 越往外,响应越慢、成本越高,但权威越大。
这套东西之所以能搬走,是因为它对语言和框架毫无要求。它只要三样东西:一个循环、一个可以整体替换的状态、一个"为什么回来"的记号。 有了这三样,同样的形状会出现在任何地方——编译器的语法错误恢复(跳过一段 token,重新同步,继续解析)、数据库的死锁重试(回滚,换个隔离级别,重来)、网络重连(换线路,退避,重试)、CI 失败重跑(修掉失败的那一步,从头再来)。
而它唯一真正的门槛,是对"重试"这个词的理解:
重试时如果不换状态,那不叫反思,叫空转。
原地重试一百次,结果一模一样,只是账单在涨——这就是活锁。所以每个 Continue Site 都必须同时做两件事:换状态,和记下为什么换。少任何一件,这个环就会退化成空转。
这也是为什么第二节那个"四件事"的清单值得记住:它不是这套代码的实现细节。任何反思系统,至少得有这四样。
可迁移的设计原则
绕了一大圈,收拢成一句:
判断是不是状态机,看的不是有没有
enum,是"位置与数据合起来是否决定能力"。而状态放哪,看它需不需要跨界。
具体的判断流程:
你在写一个循环,纠结要不要引入 phase 变量时,先问三层:
1. 这个信息,能不能靠"代码走到哪"表达?
→ 能。那就别写变量(免费)。顺序本身就是状态编码。
2. 它要不要跨一轮活下来?
→ 要。提成字段(付费),否则每轮回到同一点就丢了。
3. 它要不要跨函数、跨进程、跨机器?
→ 要。不仅提成字段,还得可序列化。此时必须放弃"位置即状态"。
反过来的检查表:
· 状态数 = 要回答的问题数,不是复杂度
· 每个状态转移,凑齐四问:守卫 / 新状态 / 原因 / 回边
· 有回边的地方,必须有守卫,否则就是活锁
· 自环 ≠ 回边,数的时候别混
还有一条更实用的:
如果你发现一个"状态机"里 90% 的代码都在转移内部,那它其实是"记忆型"状态机——决策不在它手里。
这时候别硬套 FSM 的形式,要去问:真正做决策的是谁? 大概率是模型、是人、或者某个外部服务。
知识补习
- PC(Program Counter):CPU 里存"当前指令地址"的寄存器。顺序执行时自动递增,跳转指令会改写它。它是免费的、隐式的、硬件维护的状态。
- 结构化程序定理(Böhm–Jacobi, 1966):任何流程图都能只用"顺序、选择、循环"三种结构表达,不需要
goto,也不需要状态变量。"顺序"本身就是一种状态编码。 - 位置无关代码(PIC):用相对偏移而非绝对地址的指令编码。让代码在内存任意位置都能正确执行,也是 ASLR 的前提。
- Harel statechart:UML 状态图的理论基础,在 FSM 上加了三个能力:层次(子状态机)、并发(正交区域)、动作挂载点(entry / exit / transition action)。Claude Code 把十个步骤全挂在了 transition action 上。
- 协程帧(generator frame):生成器被挂起时,它的 PC 和局部变量会被搬到堆上保存。所以协程已经把"位置"变成了付费项——这也解释了为什么不需要再为
phase付第二次费。 - 活锁(livelock):系统一直在动,但永远不前进。比死锁隐蔽,因为它不报错、不阻塞,只是永远转圈,同时持续消耗资源。
- 乐观并发控制 / CAS:Compare-And-Swap,"先比较再交换"。和状态机无关,但后面那篇会用到——工具系统用它防文件冲突。
下一篇:七台状态机,一根水管 —— 主干和旁支怎么共存,以及"消息"为什么是唯一的水管。
评论