← 返回文章列表

从设计者的角度理解源码--ClaudeCode中的状态机们

Claude Code 的状态机们 Claude Code 里那么多状态机,凭什么不打架 引言 有一个说法流传很广,听起来像技术事实,其实是错觉: "Claude Code 里有好几个状态机,它们共用一个 LLM 大脑。" 这句话让人联想到一个共享内存:几台机器读写同一块区域,靠加锁互斥。 但物理上

Claude Code 的状态机们

Claude Code 里那么多状态机,凭什么不打架

引言

有一个说法流传很广,听起来像技术事实,其实是错觉:

"Claude Code 里有好几个状态机,它们共用一个 LLM 大脑。"

这句话让人联想到一个共享内存:几台机器读写同一块区域,靠加锁互斥。

但物理上不存在这个共享区。

LLM 是一个纯函数——输入 messages 数组,输出 tokens。它不记得上一轮说了什么,每次调用你都得把全部前情提要重新塞进去一遍。

所以所谓"共用大脑",真相是:一台没有记忆的公用计算器,加 N 个各带上下文的调用方。

不打架的根源不是锁,是根本没有共享。 这句话是理解整个架构的起点。下面分四层把它铺开:有几台机器、各自活多久、怎么组装在一起、各自往哪里投影。


一、一共几台机器,各自能活多久

先把机器数清。全仓带状态字段的东西,一共七台:

主干(十分钟级)
└─ queryLoop                     隐式状态:位置 + 10 个字段

工具层(秒 ~ 分钟)
├─ StreamingToolExecutor        四态
│   └─ toolExecution / EditTool  管道,无状态
└─ 后台任务 ×N    pending → running → completed
    ↑ 能活过 queryLoop:主循环收工了,它还在跑

旁挂 AppState —— 不是一台机器,是个容器,里面套着四台
└─ 推测(2 态)· 插件安装(4 态)· 收件箱(3 态)· MCP 客户端(5 态)
#机器状态取值能活多久
1queryLoop隐式(位置 + State)十分钟级
2StreamingToolExecutorqueued / executing / completed / yielded分钟级
3后台任务 ×Npending / running / completed / failed / killed跨轮,可长于主循环
4推测idle / active秒级
5插件安装pending / installing / installed / failed分钟级
6收件箱消息pending / processing / processed轮次级
7MCP 客户端connected / failed / needs-auth / pending / disabled会话级

这里有个反直觉的地方:活得最久的不是主循环。 queryLoop 一轮轮结束,后台任务还在跑。能跨过整个对话轮次继续存活的,除了它就是 AppState 里那几台(MCP 连接、插件安装)——只是后者的时间单位是「会话」,不是「轮次」。第六节的三类旁支,正好可以对上这张表:七台 = 1 台主干 + 1 台搬运工 + 3 台内容源头 + 2 台纯内部。

(另有一个命令队列,按 now / next / later 排序,但它只排队、没有状态流转,不计在这七台里。)

这里有个容易搞错的地方:EditTool 不是状态机。 它没有任何状态变量,全部是 const;所有失败都是 throw(出口边),没有回边;它一口气跑完,中间不停。

它需要知道的"这个文件上次读的是什么时间",存在外面的 readFileState 里:

// src/tools/FileEditTool/FileEditTool.ts:452-465
const lastWriteTime = getFileModificationTime(absoluteFilePath)
const lastRead = readFileState.get(absoluteFilePath)
if (!lastRead || lastWriteTime > lastRead.timestamp) {
  throw new Error(FILE_UNEXPECTEDLY_MODIFIED_ERROR)
}

这是 CAS(比较并交换),乐观并发控制。是并发控制,不是状态机。

真正的判据只有一条:状态机能停在某个可观测状态、等外部事件;过程则从头跑到尾、中间不停。 EditTool 的 await 是在等 IO,不是在等事件,而且它的暂停外部看不见——没人知道它现在到第几步了。

于是规律浮现出来:越往外越像状态机,越往里越像管道,分界线是"时间跨度"。 EditTool 活在毫秒级,一件小事一口气做完;toolExecution 活在秒级,中间会停一次等权限;StreamingToolExecutor 活在分钟级,要等并发、要保序、要被界面观测;queryLoop 活在十分钟级,要等 API、等人、要能中断。时间跨度一到需要"停下来等"的量级,管道就不够用了。


二、调用有四种,缓存只有一份

既然要"轮流借用计算器",得先分清谁在借。先定两个词:持有长期会话、一轮轮往下推的那条线,这里叫主干;其余一次性发出、不负责延续会话的调用,叫旁支。

类型谁messages 来源命中父缓存
主循环queryLoop自有,持续增长—
子代理 / fork 压缩AgentTool、reactive compact继承父快照,独立增长必须
单次旁支调用sideQuery(20+ 种 querySource)现造,一次不
后回合 forkpromptSuggestion、sideQuestion、awaySummary继承父快照必须

第三、四行都是"旁支",但性质完全不同:一个现造上下文发一次就走,一个必须精确复用父上下文。差别全在最后一列。

为什么"命中父缓存"这一列这么要命? 因为 prompt cache 是前缀匹配的,cache key 由五样组成:system prompt、tools、model、messages 前缀、thinking 配置。任何一样不同,就整段不命中,代价是全量重新 prefill。

所以代码里有一个专门的数据结构来锁住这五样:

// src/utils/forkedAgent.ts:55 附近
/**
 * Parameters that must be identical between the fork and parent API requests
 * to share the parent's prompt cache.
 */
export type CacheSafeParams = {
  systemPrompt: SystemPrompt
  userContext: { [k: string]: string }
  systemContext: { [k: string]: string }
  toolUseContext: ToolUseContext
  forkContextMessages: Message[]
}

更精细的一处在缓存标记的放置上:

// src/services/api/claude.ts:3418
const markerIndex = skipCacheWrite ? messages.length - 2 : messages.length - 1

正常路径打最后一条消息,skipCacheWrite 时挪到倒数第二条。注释解释得很干脆——那是最后一个共享前缀点,写入是服务端的无操作合并,分支不会在缓存里留下自己的尾部。

翻译成人话:这类旁支只读父缓存,不在缓存里留脚印。因为它是 fire-and-forget 的,对话永远不会被再读一次,写进缓存纯属浪费 KV 页面。

还有一颗隐形地雷:给旁支设 maxOutputTokens 会导致 budget_tokens 被 clamp,而 thinking 配置是 cache key 的一部分——缓存直接失效。注释原话是"Only set this when cache sharing is not a goal",只在不需要共享缓存时才这么干。

最后一个优雅的细节:主循环每轮结束时把缓存钥匙写进 lastCacheSafeParams 这个全局槽位(src/utils/forkedAgent.ts:95 附近),后回合的旁支直接来取。主干把钥匙挂在门口,旁支自己来拿,调用方不用层层传参。


三、它们靠什么连在一起

知道有谁在借,下一个问题是它们怎么装在一起。答案不是一种方式,是四种:

组装方式代码样子谁暂停谁
yield* 子生成器yield* handleStopHooks(...)双向
持有对象 + 拉取for await (const r of executor.getResults())外层拉内层
全局 store 订阅useAppState(s => s.xxx)互不阻塞
消息介质messages 数组完全不阻塞

第一种最容易被误认为"方法调用",但它不是。普通方法调用的输出通道是独立的——返回值;而 yield* 是输出通道合并:子生成器 yield 出来的东西直接出现在父生成器的输出流里,调用方根本分辨不出是谁吐的。这就是 handleStopHooks 能顺手往 UI 推消息(src/query.ts:2097),而 query() 不用管它吐了什么的原因。

父能杀子,子杀不了父

"外部停,子也停"对;反过来不成立:

// src/query.ts:513
const terminal = yield* queryLoop(params, consumedCommandUuids)
//              ↑ 子生成器在这里 return 了,值赋给 terminal
for (const uuid of consumedCommandUuids) {
  notifyCommandLifecycle(uuid, 'completed')   // ← 父还在跑
}
return terminal

queryLoop 已经结束了,父生成器还在收尾。因为 yield* 的返回值会变成一个表达式值,父拿到后继续往下走。

所以生死关系是单向的:父能杀子,子杀不了父。 父 .return() 会让子被级联关闭,父抛异常会在 yield* 处传给子,而子正常 return 只是把值交给父。

这个不对称有一条实用推论:清理逻辑必须写在子生成器内部。 因为父可能比子先死,父的 finally 等不到那一天。代码里对应的写法是:

// src/query.ts:651
using pendingMemoryPrefetch = startRelevantMemoryPrefetch(...)

using 的语义是:无论这个生成器怎么退出(正常返回、抛异常、被外部 .return()),资源释放一定会执行。这不是风格问题,是结构化并发的硬要求。


四、为什么主循环没有 phase,工具执行器却有四个状态

同样叫"状态机",显式程度差别很大。挑三台最有代表性的对比:

机器状态怎么表示为什么
queryLoop隐式(代码位置编码)单线程、线性推进,每轮只有一条路径
StreamingToolExecutor显式四态枚举并发、乱序完成、需要保序
AppState判别联合多订阅者、需要响应式

规律很清楚:并发度越高、外部可观测性要求越强,状态就越要被显式命名;单线程顺序推演的地方,控制流本身就是最好的状态编码。

(queryLoop 为什么不需要 phase,上一篇拆过,这里不重复。)

工具执行器只有四个枚举值,看起来价值有限——顶多算个统一调度器。这个判断对了一半:它确实不生产 message 的内容,内容是 runToolUse 和各个 Tool 产的。但它做了三件 AOP 做不了的事:顺序、时机、补全。而顺序的全部实现,就是一个 break:

// src/services/tools/StreamingToolExecutor.ts:597
for (const tool of this.tools) {
  // ① 进度:无条件立即产出(打破顺序)
  while (tool.pendingProgress.length > 0) yield { message: tool.pendingProgress.shift()! }

  // ② 交过了:跳过
  if (tool.status === 'yielded') continue

  // ③ 已完成:交出结果,标记 yielded
  if (tool.status === 'completed' && tool.results) {
    tool.status = 'yielded'
    for (const message of tool.results) yield { message }
  }
  // ④ 遇到"正在执行且不安全"的工具 → 停住,不往后扫
  else if (tool.status === 'executing' && !tool.isConcurrencySafe) break
}

第 ④ 条那句"停住不往后扫"就是保序的全部实现:前面那个还没跑完,后面的一律不许先交。没有 status,这一行写不出来——你怎么知道"前面那个还没完"?

completed 和 yielded 之所以必须分开,也是同一个原因。一个工具可能早就跑完了,但前面那个还没完,它得排队等着被交出去。没有 yielded,它会被重复产出无数遍——每次扫描都看到它 completed,每次都交一次。

所以状态数量从来不由复杂度决定,而是由"要回答几个问题"决定。这里只需回答三个:能开始了吗(queued + 别人是否 executing)、完事了吗(completed)、交出去了吗(yielded)。三个问题,四个状态,刚好。 加第五个状态没有对应的问题。


五、真正的分界:谁服务于模型,谁服务于人

到这里,最关键的判断标准可以说了。

系统里主要的两个观察者是模型和人。服务模型的,流进 messages;服务人的,流进 AppState。两根基本独立的水管,偶尔有交叉——AppState 里的权限模式也会被工具读来决定能不能跑,但它主要的消费者仍是界面。

AppState 那根水管的核心只有二十行:

// src/state/store.ts
setState: (updater) => {
  const prev = state
  const next = updater(prev)
  if (Object.is(next, prev)) return        // 没变,什么都不做
  state = next
  onChange?.({ newState: next, oldState: prev })
  for (const listener of listeners) listener()    // 挨个通知订阅者
}

存下来、比一比、喊一声。它没有返回值、不调用任何人、也不知道谁在听。读取端用选择器订阅一片数据(src/state/AppState.tsx:162 的 useSyncExternalStore),只有自己关心的那片变了才重渲染。

最能说明问题的是 MCP token 过期这条链路。某个 MCP 服务器的凭证失效,工具调用抛 McpAuthError,于是 toolExecution 顺手改了一下全局状态(src/services/tools/toolExecution.ts:1827 附近):

if (error instanceof McpAuthError) {
  toolUseContext.setAppState(prevState => {
    // 把这台 MCP 客户端从 'connected' 改成 'needs-auth'
    return { ...prevState, mcp: { ...prevState.mcp, clients: updatedClients } }
  })
}

注意它没有 return 错误、没有抛异常、没有 yield 消息——它只是改了 store 里的一个字段。 然后 store 广播,/mcp 界面里某个早就订阅了 s.mcp.clients 的组件自己醒过来,显示"需要重新授权"。全程主循环毫不知情,它只知道这次工具调用失败了。

假设没有 store,toolExecution 就得持有 /mcp 界面的引用,于是工具执行层依赖 UI 组件层,UI 组件层依赖渲染树——底下三层全被绑死,而且方向反了:底层工具居然要认识上层界面。以后想加第二个显示 MCP 状态的地方,就得改工具层。

两种通信方式的差别,可以一句话概括:yield* 是打电话,我知道在跟谁说;store 是广播电台,我只管喊,谁听随缘。 代价是后者无法追溯因果——你只能靠 onChange 和日志去还原是谁改的。所以它只用来传"界面要显示什么",绝不用来传"模型该做什么"。


六、谁在往对话里送消息,谁一句话都不说

把所有旁支归一次类:

类别例子对 message 的贡献
A 类:搬运工StreamingToolExecutor格式层(顺序、时机、补全)
B 类:内容源头推测、收件箱、后台任务内容本身
C 类:纯内部插件安装进度、MCP 连接状态零

这一类很少见,最典型的就是它,而且很特殊:内容不是它产的,但秩序是它维持的。它还是协议的守门人——工具名不存在、工具被中断时,它凭空造一条 tool_result,因为 API 有一条铁律:每个 tool_use 必须有且只有一个 tool_result 配对,少一个整个请求就非法。

B 类三个例子的驱动方式完全不同。后台任务是被推的:任务成功或失败时,各 Task 组件调用 enqueuePendingNotification({ value: message, mode: 'task-notification' }) 排进命令队列,下一轮被消费。收件箱是被拉的:附件采集时筛出 status === 'pending' 的消息(src/utils/attachments.ts:3610),变成 attachment 进而变成 user 消息,然后标记为 processed 防止重复取走。推测是预先算的:用户还没发消息,它先猜、先算、先把消息造出来,命中时直接拼进上下文(src/services/PromptSuggestion/speculation.ts:363 附近)。

加上同步返回的工具结果,一共四种时间模式,走同一根水管:同步、推、拉、预。

而它们的共同结构是:某个状态变化,放出一条 message,进入 messages。这几类都不直接写 messages 数组,都是往某个队伍里放,由主循环在合适的时机取走——这也是它们能作为"旁支"存在的原因,它们不碰主循环的状态,只往投递口放东西。

C 类为什么一个字都不放?因为插件装到哪一步了,模型完全不需要知道。这条规则可以概括成:过程不进 messages,后果进。

最能说明这条规则的是 MCP 的 needs-auth。状态本身走界面那条线,但如果这次工具调用因此失败,失败会以 tool_result 加 is_error 的形式走进 messages。状态不进,状态导致的后果进。


七、模型看到的是叙事,不是状态

最后一层,也最容易讲错。

消息层常被称作"翻译器"。更准的词是投影:翻译追求一一对应的保真,投影是把高维结构压到低维平面,必然有损,而且可以选择损失什么。状态机有十个字段、若干计数器、守卫条件,而 LLM 只能读文本,不可能全投,必须取舍。

投影面有四个,不止 messages:历史走 normalizeMessagesForAPI;环境(cwd、git、CLAUDE.md、日期)走 system prompt 和 userContext;增量事实(todo、文件改动、预算、日期变化)走 attachment 转成的 <system-reminder>;动作空间走工具注册表。

第四个最容易被忽略。模型感知到的"状态",一半是"我在什么局面",另一半是"我能做什么"。工具 schema 就是动作空间的投影——选择哪些工具可见,等于改变了模型能走哪条边。极端例子是计划模式下把写入类工具从列表里摘掉,模型感知到的不是"你被禁止写入",而是"世界上没有写入这回事"。这比任何提示词都硬。

同一份失败也要给三个读者各翻译一遍:给代码的是 transition.reason 这样的枚举值,存在 State 里;给模型的是 tool_result 加 is_error 加一段错误文字,存在 messages 里;给人的是屏幕上的红色卡片。不是共享一份原因,是各翻译一份。 这就是既不互相干扰、又能各自协作的实现方式。

403 被挡在模型视野之外

判断一个错误走哪条路,标准只有一条:模型自己能不能读懂。

工具失败走 messages,因为模型读懂了能改策略。而 403 走的是另一条路——它被翻译成一张给用户看的卡片,然后在序列化时被过滤掉:

// src/utils/messages.ts:2551 附近的过滤器
if (
  _.type === 'progress' ||
  (_.type === 'system' && !isSystemLocalCommandMessage(_)) ||
  isSyntheticApiErrorMessage(_)        // 403 / 413 / 429 的错误卡片
) {
  return false                          // 永远不发给模型
}

背后的原则是:错误不能委托给已经失败的那个组件去处理。 你没法让连不上的模型来处理"连不上"。

而工具异常之所以能被模型看见,靠的是一个字的差别——runToolUse 的兜底 catch 里写的是 yield 而不是 throw(src/services/tools/toolExecution.ts:583 附近):

} catch (error) {
  yield {
    message: createUserMessage({
      content: [{ type: 'tool_result', content: `<tool_use_error>${detailedError}</tool_use_error>`,
                  is_error: true, tool_use_id: toolUse.id }],
    }),
  }
}

throw 会让循环崩掉,yield 让异常降级成一条消息。把 throw 换成 yield,就是把事故变成情报。 在此之前它是个异常,在此之后它是模型能读到的一段文字。

反过来,模型并没有跳转权。它输出内容块,代码把它解析成数据变化(比如 needsFollowUp = true),守卫判断后位置才移动。LLM 永远没法直接说"跳到第 8 步",它连 PC 在哪都不知道。LLM 提建议,代码拍板,光标是代码的领地。 整个系统的可控性,全部来自这一条。


可迁移的设计原则

收拢成三句话:

① 多台状态机共存,靠的不是加锁,是"不共享"。
② 谁要往水管里放东西,取决于"它的后果会不会改变另一端"。
③ 投影必须是有损的,且损失要刻意选择。

展开成一张检查表:

你要在一个系统里放几台状态机时:

  1. 给每台机器定"时间尺度"
     · 毫秒级 → 写成过程(管道),别搞状态机
     · 秒级 → 管道 + 一个等待点
     · 分钟以上、会并发、要被观测 → 才值得是状态机

  2. 判断它该往哪根水管放东西
     · 后果会改变模型的下一步 → messages
     · 后果只改变人的屏幕     → 全局 store
     · 两者都要 → 两条投影线,各写一份,别想着复用

  3. 组装方式按耦合度选
     · 需要共享输出流 → yield*(记得:父能杀子,子停父不停)
     · 需要并行拉取   → 持有对象 + 消费队列
     · 只需通知       → store 订阅

  4. 跨界就要买票
     · 状态要不要跨轮 / 跨函数 / 跨机器?
     · 要跨,就必须数据化、可序列化,放弃"位置即状态"

  5. 有多个读者时,别共享一份原因
     · 给代码的:枚举值
     · 给模型的:自然语言
     · 给人的:人话

还有一条我认为最容易被忽略的:

统一封装,最能暴露设计水平的地方不是"统一了什么",是"在哪里开了口子"。

工具执行器的封装里就有一个硬编码的特判:只有 Bash 的错误才连带取消兄弟工具。因为命令之间有隐式依赖——mkdir 失败了,后面的 cd 就没意义。而 Read、WebFetch 失败不影响别人。

这条特判破坏了"统一",但它是必要的。 好的封装不是消灭例外,是把例外写在明面上。


知识补习

  • 纯函数与"无状态服务":LLM 每次调用都是独立的,上下文靠调用方每次重传。所以"共享大脑"这种说法,在工程上等于"共享一个纯函数"——没有共享状态可言。
  • Prompt Cache 的前缀匹配:服务端缓存的是 prefill 阶段算好的 KV 矩阵,key 由 system prompt + tools + model + messages 前缀 + thinking 配置组成。任何一样变了就整段失效,重建成本是全量重新 prefill。这就是为什么"前缀稳定"比"内容少一点"重要得多。
  • 结构化并发(structured concurrency):子任务的生命周期不能超过父任务。yield* 委托、.return() 级联关闭,都属于这个范式。和"到处 fire-and-forget"相比,它保证不会泄漏。
  • Mealy 机 vs Moore 机:Moore 机的输出只取决于状态,Mealy 机的输出取决于转移。Claude Code 的循环是典型的 Mealy——大量信息在"转移过程中"被 yield 出去,而不是挂在某个状态上。
  • CAS(Compare-And-Swap):先比较再交换。EditTool 用它防文件冲突:比较 mtime,一致才写盘。这是乐观并发控制,和状态机是两回事。
  • 控制面 / 数据面分离:数据面走业务数据,控制面走"怎么处理数据"的信令。代码里明确把 13 种协议消息挡在 LLM 上下文之外,就是这条原则。
  • 判别联合(discriminated union):用 { status: 'x' } 这样的标签字段区分多种形态,配合 TypeScript 的穷尽检查,可以让"非法状态不可表示"。这是状态机在类型系统层面最廉价的一种落地方式。

上一篇:Agent Loop 是不是状态机 —— 那个没有 phase 字段的状态机,靠什么撑起来。

评论