← 返回文章列表

从设计者的角度理解源码--Agent Loop到底是不是状态机?

Agent Loop 是不是状态机 一个没有 phase 字段的状态机,靠什么运转 引言 关于 Claude Code 的 query(),流传最广的一句定性是"它是一个状态机"。讲得再细一点,会说它有若干"Continue Site",每次转移到下一轮都带着一个 transition.reason

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 里塞了一坨,不像状态图。

三层叠起来,很容易得出一个错误结论:这不是状态机,只是一个带状态变量的循环。

但把形式要件一条条对上去,会发现问题不在"缺了什么",而在"为什么有些东西不需要存":

状态机要件教科书写法这里的落地
状态集合 Senum Phase程序计数器 + State(位置隐式,数据显式)
输入字母表 Σevent流式增量 / tool_result / hook 结果 / AbortSignal
转移函数 δswitch6 个显式 continue + 1 个底部回边
守卫guardhasAttemptedReactiveCompact、maxOutputTokensRecoveryCount
终止状态halt10 个 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位置为什么又转一圈
1collapse_drain_retry:1888413,先把折叠排空
2reactive_compact_retry:1959413,压缩历史
3max_output_tokens_escalate:2039输出被截断,调高上限
4max_output_tokens_recovery:2071输出被截断,追加"接着写"
5stop_hook_blocking:2148stop hook 报了错,塞回去改
6token_budget_continuation:2196预算还剩,推模型继续
7next_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 了"行号(隐式)
② 跨轮字段整个 queryturnCount、hasAttemptedReactiveCompactState
③ 单轮局部变量只有一轮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,"先比较再交换"。和状态机无关,但后面那篇会用到——工具系统用它防文件冲突。

下一篇:七台状态机,一根水管 —— 主干和旁支怎么共存,以及"消息"为什么是唯一的水管。

评论