Claude Code 源码深度解析之 Harness Engineering 上篇:如何从用户输入进入运行时主循环

很多人谈 agent 时，喜欢把重点放在 prompt 或模型能力上。

但如果你认真看 Claude Code 的源码，会发现它下了很多功夫在 harness engineering 上：把模型、工具、权限、状态、流式输出、恢复机制、会话生命周期，全都装进一个可运行的工程壳里。

这篇上篇先回答一个更基础的问题：Claude Code 是怎么把用户输入一步步送进运行时主循环的？

系列回顾：

• Claude Code 源码深度解析之架构总览：它如何成为一套 agent runtime
  

• Claude Code 源码深度解析之：agent loop 主链路

先解释几个会反复出现的术语

• 模型调用：可以粗略理解成一次向 Claude API 发请求。很多人会把它直接等同于“一次 query”，但在 Claude Code 里两者并不完全一样。
• turn：一次回合。模型产出内容、可能调用工具、工具结果被回填，再决定是否继续，这一整段更接近一个 turn。
• tool_use：模型在回复里发出的“请调用某个工具”的结构化请求，不是普通文本。
• transcript：会话的持久化运行记录，不只是当前传给模型的 messages，还包括恢复和重放所需的关键轨迹。
• harness：围绕模型建立起来的运行时框架。它处理的往往不是“模型会不会回答”，而是“这个系统能不能稳定跑下去”。

什么叫 harness engineering

你可以把它理解成：围绕模型建立一套可执行、可控、可恢复、可扩展的运行时框架。

模型本身主要负责推理；Claude Code 负责决定什么时候发请求、这次请求带哪些上下文、能调用哪些能力、工具结果如何回填、权限怎样放行或拦截，以及会话如何被记录、压缩和恢复。真正把系统撑起来的是这些模型外的工程机制。

一张图看懂 Claude Code 的 runtime harness

这张图的重点在于：Claude Code 不会让模型“裸跑”。 它会先处理输入，再装配会话，再进入主循环。后面很多你在源码里看到的复杂逻辑，本质上都是围绕这条链展开的。

先把入口边界画完整：用户输入不会直接进入 queryLoop

在 Claude Code 里，用户输入通常不会直接掉进 query.ts。在真正进入 queryLoop 之前，还有一段明确的输入预处理链。

这里的 query.ts 可以先粗略理解成 Claude Code 的主循环内核：它负责驱动每一轮请求如何进入模型、何时执行工具、出现错误后如何恢复，以及在什么条件下继续或结束当前回合。

如果再说得更准确一点：query() 本身并不等于一次单独的 LLM call。底层的 callModel() 才更接近“单次模型请求”；query() 包住的则是一个可能包含多次模型调用、工具执行、结果回填和状态推进的运行时闭环。

而 queryLoop 则是 query.ts 里面那条真正按轮推进的核心循环：它会在每一轮里整理上下文、发起模型请求、处理 tool_use、回填工具结果，并根据 hooks、budget 和错误恢复逻辑决定下一步怎么走。

以 QueryEngine.submitMessage() 为例，它首先会调用 processUserInput()，把原始输入转换成系统真正能消费的消息和控制信号。这个阶段做的事情并不少：

• 解析输入类型：区分普通 prompt、slash 命令、bash 命令、桥接消息、带图片的多模态输入。
• 处理附件与图片：提取 attachment、规范化 image blocks、必要时做 resize/downsample，并把元数据补成 isMeta 消息。
• 执行输入期 hooks：UserPromptSubmit hooks 可以附加上下文、阻断请求，或者直接阻止 continuation。
• 决定是否进入主循环：本地 slash 命令、某些本地处理路径会返回 shouldQuery: false，这类输入根本不会进入 queryLoop。
• 回传入口期控制信号：例如 allowedTools、model override、resultText，这些都会影响后续会话装配。

可以把这条链理解成：

raw user input                                            // 原始用户输入  -> processUserInput                                     // 输入预处理  -> messagesFromUserInput + shouldQuery + allowedTools + model override  // 生成消息与控制信号  -> transcript persistence                               // 先写入 transcript  -> session/tool context assembly                        // 再做会话装配  -> query()                                              // 进入运行时闭环

这里的 transcript 可以先简单理解成会话的持久化运行记录。它不只是当前传给模型的 messages，还承担了记录用户输入、assistant 输出、工具结果和恢复边界的作用，所以在真正进入 query() 之前先写入 transcript，核心是为了让这次会话可追踪、可恢复。

把这个边界讲清楚很有必要，因为 Claude Code 的 harness 会先经过一层输入规范化、局部执行和准入判断，之后才进入 agent loop。

QueryEngine 负责会话装配，但不是唯一入口

QueryEngine 依然很重要，不过它更像会话层的 harness 封装，并不是整个系统唯一的 runtime 入口。

先解释一下“会话装配”这个说法。它不是简单地拼几个参数，而是把这一轮运行需要的上下文、能力和状态准备齐：这次对话已有的 messages、可用工具列表、system prompt、当前会话的权限语义，以及恢复和持久化相关的状态，都会在这里被整合到一起。

来看 submitMessage() 的实际签名：

// src/QueryEngine.tsasync *submitMessage(  prompt: string | ContentBlockParam[],  options?: { uuid?: string; isMeta?: boolean },): AsyncGenerator<SDKMessage, void, unknown> {

它做的事情主要包括：

• 承接输入预处理后的消息与控制信号，必要时短路本地路径。
• 把 messagesFromUserInput 先写入 transcript，保证即使 API 尚未返回、进程中途退出，也可以从“用户输入已被接受”的时点恢复会话。
• **组装 systemPrompt、userContext、systemContext**。
• **构造 ToolUseContext**，把工具、命令、MCP、AppState、缓存、预算等能力装配进来。
• **包装 canUseTool**，把权限拒绝记录、headless/SDK 语义接到工具执行链路上。
• 维护会话级状态，例如 transcript 持久化、file history、累计 usage、permission denials。

但这里有一个重要边界要讲清：**QueryEngine 不是 Claude Code 的唯一入口。**

在 SDK 或 headless 路径里，它确实承担了会话层入口的角色；而在交互式 REPL 路径里，UI 侧仍然会直接驱动 query()。Claude Code 的分层更接近下面这样：

• 入口层：REPL、CLI、SDK 各自有自己的接入方式。
• 会话层：QueryEngine 负责其中一部分入口的会话装配与状态持有。
• 执行内核：query.ts 的 queryLoop 负责真正的 runtime 推进。

这个区分能避免把 QueryEngine 误读成“整个 harness 的全部”。

如果把两条主要入口并排来看，关系会更清楚一些：交互式 REPL 不会直接把输入塞进 queryLoop，而是先经过提交处理和输入预处理，再由 onQuery() 接到 query()；SDK / headless 则会先经过 QueryEngine.submitMessage()，在完成输入预处理与会话装配后再进入同一个 query()。

更贴源码的理解大概是：

• 输入层先做预处理与短路判断。
• 会话层再决定本轮要带着什么上下文和权限进入执行。
• 执行层最后由 queryLoop 推动模型、工具和恢复逻辑往前走。

进入执行内核：query.ts 的 queryLoop

如果只挑一个文件来理解 Claude Code 的 harness，可以先看 src/query.ts，尤其是里面的 queryLoop。

Claude Code 的核心在于维护一个可持续推进的回合状态机。这里的“状态机”不是教科书里的那种形式化定义，而是说：系统每完成一步，就会根据当前消息、工具执行结果、停止条件和错误恢复状态，决定下一步往哪里走。

从 query.ts 里的 loop-local State 就能看出这一点：

// src/query.tstype State = {  messages: Message[]  toolUseContext: ToolUseContext  autoCompactTracking: AutoCompactTrackingState | undefined  maxOutputTokensRecoveryCount: number  hasAttemptedReactiveCompact: boolean  maxOutputTokensOverride: number | undefined  pendingToolUseSummary: Promise<ToolUseSummaryMessage | null> | undefined  stopHookActive: boolean | undefined  turnCount: number  transition: Continue | undefined}

这个状态在驱动整个回合的推进。queryLoop 每次迭代大致都会做这些事：

• 整理本轮输入：取 compact boundary 之后的消息，应用 tool result budget、snip、microcompact、context collapse、autocompact。
• 发起模型请求：把 messages、systemPrompt、userContext、tools、taskBudget 等交给 callModel()。
• 处理流式响应：持续接收 assistant blocks、收集 tool_use、在需要时启动 StreamingToolExecutor。
• 执行工具并回填结果：把 tool_result 重新变成后续轮次的输入，而不是只留在 UI 上展示。
• 做恢复与重试：处理 prompt-too-long、max_output_tokens、model fallback、streaming fallback。
• 决定回合是否结束：检查 stop hooks、token budget、maxTurns、abort 状态，以及是否还需要 follow-up。

所以更准确地说，Claude Code 的 harness 重心落在 queryLoop 这个持续演化的 runtime 上，而不只是 QueryEngine 外面包一层工程代码。

这里也顺手交代一下上下篇的组织方式：上篇基本沿着 Claude Code 的主运行链往下讲，从输入预处理、会话装配一路走到 queryLoop；下篇再把这条主链里的关键机制拆开来看，比如 ToolUseContext、权限、工具执行、stop hooks、budget 和 recovery。也就是说，下篇各节更多是围绕主链做展开，并不都是严格按时间顺序发生的步骤。

源码锚点

如果你想顺着上篇这条主运行链自己跟一遍源码，基本可以按这个顺序看：

• src/screens/REPL.tsx
• src/utils/handlePromptSubmit.ts
• src/utils/processUserInput/processUserInput.ts
• src/QueryEngine.ts
• src/query.ts

上篇小结

如果把上篇压缩成一句话，可以这样理解：Claude Code 的 harness 先把用户输入变成系统可消费的消息和控制信号，再由 QueryEngine 或 REPL 路径完成会话装配，最后把一切交给 queryLoop 这个持续推进的执行内核。

到这里为止，主运行链已经比较清楚了。下篇会先从 ToolUseContext 这个运行时容器开始，再往下看：进入主循环之后，这些能力是怎么被权限、工具执行器、stop hooks、budget、compact、recovery 和 transcript 共同治理的。