Claude Code 源码阅读 Phase 1：Agent Loop 最小闭环阅读稿

总览程序员视角的执行流程图

Agent Loop 主循环

消息协议泳道图

前言为什么要读这份源码

阅读 Claude Code 源码，并不是要把 50w+ 行代码全部消化掉。我们真正要学习的是它作为 AI Coding Agent 的核心思想：

这一阶段重点不放在前端 UI，也不放在终端渲染，而是放在模型编排、工具调用、消息结构、上下文处理这些 AI 应用核心机制上。

Phase 1Agent 最小闭环

学习目标

Phase 1 先只追求 Agent 最小闭环：

用户 messages
  |
  v
调用模型
  |
  v
assistant 返回 text 或 tool_use
  |
  +-- 如果是 text，结束
  |
  +-- 如果是 tool_use，本地执行工具
        |
        v
      把 tool_result 作为新 message 放回 messages
        |
        v
      继续下一轮模型调用

这条闭环是 Claude Code 最核心的 AI 编排逻辑。后面的权限系统、上下文压缩、subagent、hook、任务队列，本质上都是围绕这条主线增加工程能力。

本阶段核心源码

• src/query.ts
• src/services/tools/toolOrchestration.ts
• src/utils/messages.ts
• src/services/api/claude.ts

1源码地图：先知道 query.ts 里有什么

query.ts 的顶层结构

src/query.ts 的结构可以先这样记：

src/query.ts:129-168    yieldMissingToolResultBlocks() 辅助函数
src/query.ts:181-185    isWithheldMaxOutputTokens() 辅助函数
src/query.ts:187-205    QueryParams 类型
src/query.ts:210-223    State 类型
src/query.ts:225-245    query() 外层包装器
src/query.ts:247-1741   queryLoop() 主循环

也就是说，query.ts 的主体几乎全是 queryLoop()。

阅读策略

不要逐行硬啃 queryLoop 的 1500 行。
先按 Agent Loop 主线分段读。
compact、fallback、hook、token budget 这些支线先知道位置和作用，后续再深挖。

2Phase 1 主线地图

query(params)
  |
  v
queryLoop(params)
  |
  v
State 初始化
  |
  v
while (true)
  |
  v
messagesForQuery = getMessagesAfterCompactBoundary(state.messages)
  |
  v
上下文处理：budget / snip / microcompact / collapse / autocompact
  |
  v
deps.callModel(messagesForQuery, tools, systemPrompt, ...)
  |
  v
assistantMessages.push(message)
  |
  v
从 assistant content 中提取 tool_use -> toolUseBlocks
  |
  +-- 没有 tool_use --> return completed
  |
  +-- 有 tool_use
        |
        v
      runTools(toolUseBlocks, ...)
        |
        v
      toolResults.push(user/tool_result)
        |
        v
      state.messages =
        messagesForQuery + assistantMessages + toolResults
        |
        v
      continue 下一轮

3入口层：从 query(params) 进入 Agent Loop

QueryParams：启动 Agent Loop 的参数包

位置：src/query.ts:187-205

export type QueryParams = {
  messages: Message[]
  systemPrompt: SystemPrompt
  userContext: { [k: string]: string }
  systemContext: { [k: string]: string }
  canUseTool: CanUseToolFn
  toolUseContext: ToolUseContext
  fallbackModel?: string
  querySource: QuerySource
  maxOutputTokensOverride?: number
  maxTurns?: number
  skipCacheWrite?: boolean
  taskBudget?: { total: number }
  deps?: QueryDeps
}

QueryParams 不是用户最新输入的一句话，而是启动一次 agent loop 需要的完整参数包。

最关键的三个字段

• messages：当前对话历史，不是单条 prompt。
• canUseTool：工具权限判断函数。模型只能请求工具，是否允许执行由本地 runtime 决定。
• toolUseContext：工具执行上下文，包含工具列表、权限状态、abortController、agentId 等运行环境。

为什么不能只传用户一句话？

如果只是一次普通 API 调用，可能只需要：

std::string prompt = "帮我读一下 src/query.ts";

但 Agent Loop 不一样。它要继续工作时，还需要知道：

之前聊了什么？
当前 system prompt 是什么？
当前有哪些工具？
这些工具能不能用？
现在是什么权限模式？
当前是不是 subagent？
最多能跑几轮？
之前有没有 compact？

所以它更像：

QueryParams params = {
    .messages = 当前完整对话历史,
    .systemPrompt = 系统提示词,
    .userContext = 用户环境信息,
    .systemContext = 系统环境信息,
    .canUseTool = 工具权限判断函数,
    .toolUseContext = 工具运行环境,
    .querySource = 这次 query 来自哪里,
    .maxTurns = 最大循环轮数,
};
query(params);

query()：外层包装器

位置：src/query.ts:225-245

export async function* query(
  params: QueryParams,
): AsyncGenerator<
  | StreamEvent
  | RequestStartEvent
  | Message
  | TombstoneMessage
  | ToolUseSummaryMessage,
  Terminal
> {
  const consumedCommandUuids: string[] = []
  const terminal = yield* queryLoop(params, consumedCommandUuids)

  for (const uuid of consumedCommandUuids) {
    notifyCommandLifecycle(uuid, 'completed')
  }
  return terminal
}

query() 是一个异步生成器函数。它运行过程中可以多次 yield 中间事件，最后 return terminal。

这里的 Terminal 不是终端窗口，而是"这次 query 为什么结束"，例如：

completed
model_error
aborted_tools
max_turns

核心代码

const terminal = yield* queryLoop(params, consumedCommandUuids)

query() 把 queryLoop() 产生的所有中间事件原样转发出去。
queryLoop() 正常结束后，query() 拿到它的 return 值 terminal。

C++ 协程类比

using QueryEvent = std::variant<
    StreamEvent,
    RequestStartEvent,
    Message,
    TombstoneMessage,
    ToolUseSummaryMessage
>;

AsyncGenerator<QueryEvent, Terminal> query(QueryParams params) {
    std::vector<std::string> consumedCommandUuids;

    Terminal terminal =
        co_yield_from queryLoop(params, consumedCommandUuids);

    for (const std::string& uuid : consumedCommandUuids) {
        notifyCommandLifecycle(uuid, "completed");
    }

    co_return terminal;
}

4状态层：State 和 while(true) 如何驱动多轮循环

State：每一轮循环之间传递的状态

位置：src/query.ts:210-223

type 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
}

QueryParams 是外部传入的初始参数。

State 是 queryLoop() 内部 while(true) 每一轮之间传递的可变状态。

Phase 1 最重要的是

• messages
• toolUseContext

因为 agent loop 每一轮最核心的变化就是：

messages 变长，或者被 compact 后替换；
toolUseContext 可能因为工具执行而更新。

例子

第一轮：
messages = [
  user: "读一下 src/query.ts"
]

模型返回：
assistant: tool_use Read(src/query.ts)

本地工具执行：
user/tool_result: "文件内容是..."

第二轮：
messages = [
  user: "读一下 src/query.ts",
  assistant: tool_use Read(src/query.ts),
  user/tool_result: "文件内容是..."
]

初始化 State

位置：src/query.ts:271-286

let state: State = {
  messages: params.messages,
  toolUseContext: params.toolUseContext,
  maxOutputTokensOverride: params.maxOutputTokensOverride,
  autoCompactTracking: undefined,
  stopHookActive: undefined,
  maxOutputTokensRecoveryCount: 0,
  hasAttemptedReactiveCompact: false,
  turnCount: 1,
  pendingToolUseSummary: undefined,
  transition: undefined,
}

这一步把外部参数里的 messages 和 toolUseContext 放入内部状态。

源码注释说：

Continue sites write `state = { ... }` instead of 9 separate assignments.

也就是说后面进入下一轮时，不是单独改字段，而是整体构造新 state：

state = {
  messages: newMessages,
  toolUseContext: newContext,
  ...
}
continue

这个风格让每个 continue 分支都明确表达：下一轮到底带着什么状态继续。

while(true)：Agent Loop 正式开始

位置：src/query.ts:312-327

while (true) {
  let { toolUseContext } = state
  const {
    messages,
    autoCompactTracking,
    maxOutputTokensRecoveryCount,
    hasAttemptedReactiveCompact,
    maxOutputTokensOverride,
    pendingToolUseSummary,
    stopHookActive,
    turnCount,
  } = state

while(true) 不是死循环 bug，而是 Agent Loop 的核心结构：

只要模型还在请求 tool_use，就继续循环；
直到模型没有 tool_use，才 completed。

toolUseContext 用 let，因为本轮内部可能重新赋值。

其他字段用 const，本轮内通常不直接改；如果需要进入下一轮，会整体重建 state。

5上下文层：模型这一轮到底看到哪些 messages

messagesForQuery：本轮模型输入的工作副本

位置：src/query.ts:371-373

let messagesForQuery = [...getMessagesAfterCompactBoundary(messages)]

let tracking = autoCompactTracking

这里要分清：

messages
= state.messages，完整历史 / 当前长期状态

messagesForQuery
= 本轮模型实际输入的工作副本

messagesForQuery 后面会继续被裁剪、压缩、预算处理。

getMessagesAfterCompactBoundary()

定义位置：src/utils/messages.ts:4643-4656

export function getMessagesAfterCompactBoundary<
  T extends Message | NormalizedMessage,
>(messages: T[], options?: { includeSnipped?: boolean }): T[] {
  const boundaryIndex = findLastCompactBoundaryIndex(messages)
  const sliced = boundaryIndex === -1 ? messages : messages.slice(boundaryIndex)
  if (!options?.includeSnipped && feature('HISTORY_SNIP')) {
    const { projectSnippedView } =
      require('../services/compact/snipProjection.js') as typeof import('../services/compact/snipProjection.js')
    return projectSnippedView(sliced as Message[]) as T[]
  }
  return sliced
}

它的作用：

如果没有 compact boundary，返回全部 messages。
如果有 compact boundary，只返回最后一个 boundary 之后的消息。

查找 boundary 的函数在 src/utils/messages.ts:4618-4629：

export function findLastCompactBoundaryIndex<
  T extends Message | NormalizedMessage,
>(messages: T[]): number {
  for (let i = messages.length - 1; i >= 0; i--) {
    const message = messages[i]
    if (message && isCompactBoundaryMessage(message)) {
      return i
    }
  }
  return -1
}

上下文处理流水线

从 src/query.ts:375-549，代码连续做了几类上下文处理。

它们都在处理同一个对象：messagesForQuery

可以理解成流水线：

state.messages
  |
  v
getMessagesAfterCompactBoundary
  |
  v
messagesForQuery
  |
  +-> applyToolResultBudget
  |
  +-> HISTORY_SNIP
  |
  +-> microcompact
  |
  +-> contextCollapse
  |
  v
最终本轮发给模型的 messagesForQuery

applyToolResultBudget：限制工具结果大小

位置：src/query.ts:375-400

messagesForQuery = await applyToolResultBudget(
  messagesForQuery,
  toolUseContext.contentReplacementState,
  persistReplacements
    ? records =>
        void recordContentReplacement(
          records,
          toolUseContext.agentId,
        ).catch(logError)
    : undefined,
  new Set(
    toolUseContext.options.tools
      .filter(t => !Number.isFinite(t.maxResultSizeChars))
      .map(t => t.name),
  ),
)

解决的问题：

工具结果可能很大。
比如 Read 读了一个 5MB 文件，或者 Grep 返回几万行。
如果完整放入下一轮 messages，模型上下文会爆。

所以它专门处理 tool_result 的体积。

HISTORY_SNIP：裁剪历史视图

位置：src/query.ts:402-416

let snipTokensFreed = 0
if (feature('HISTORY_SNIP')) {
  queryCheckpoint('query_snip_start')
  const snipResult = snipModule!.snipCompactIfNeeded(messagesForQuery)
  messagesForQuery = snipResult.messages
  snipTokensFreed = snipResult.tokensFreed
  if (snipResult.boundaryMessage) {
    yield snipResult.boundaryMessage
  }
  queryCheckpoint('query_snip_end')
}

作用：

模型调用前进一步减少 messagesForQuery。
它偏向"裁剪模型看到的历史视图"。

microcompact：小粒度压缩

位置：src/query.ts:418-432

const microcompactResult = await deps.microcompact(
  messagesForQuery,
  toolUseContext,
  querySource,
)
messagesForQuery = microcompactResult.messages
const pendingCacheEdits = feature('CACHED_MICROCOMPACT')
  ? microcompactResult.compactionInfo?.pendingCacheEdits
  : undefined

microcompact 是 autocompact 之前的小粒度上下文压缩/整理。

contextCollapse：折叠上下文视图

位置：src/query.ts:434-453

if (feature('CONTEXT_COLLAPSE') && contextCollapse) {
  const collapseResult = await contextCollapse.applyCollapsesIfNeeded(
    messagesForQuery,
    toolUseContext,
    querySource,
  )
  messagesForQuery = collapseResult.messages
}

它不是简单删除，也不一定是生成一个大 summary，而是在读取时把上下文投影成折叠后的视图。

autocompact：兜底的大型自动压缩

位置：src/query.ts:455-549

const fullSystemPrompt = asSystemPrompt(
  appendSystemContext(systemPrompt, systemContext),
)

const { compactionResult, consecutiveFailures } = await deps.autocompact(
  messagesForQuery,
  toolUseContext,
  {
    systemPrompt,
    userContext,
    systemContext,
    toolUseContext,
    forkContextMessages: messagesForQuery,
  },
  querySource,
  tracking,
  snipTokensFreed,
)

如果成功：src/query.ts:534-542

const postCompactMessages = buildPostCompactMessages(compactionResult)

for (const message of postCompactMessages) {
  yield message
}

messagesForQuery = postCompactMessages

如果失败：src/query.ts:542-549

} else if (consecutiveFailures !== undefined) {
  tracking = {
    ...(tracking ?? { compacted: false, turnId: '', turnCounter: 0 }),
    consecutiveFailures,
  }
}

失败时不改 messagesForQuery，只更新失败计数，避免后续无限重试。

几种上下文处理的区别

同步 messagesForQuery 到 toolUseContext

位置：src/query.ts:551-555

toolUseContext = {
  ...toolUseContext,
  messages: messagesForQuery,
}

这一步不是更新 state.messages。

它只是把本轮处理后的模型输入上下文同步到当前 toolUseContext，让后面的工具执行、权限判断、hook、subagent 等逻辑能看到本轮实际使用的 messages。

6模型层：调用模型并提取 tool_use

初始化本轮临时容器

位置：src/query.ts:557-564

const assistantMessages: AssistantMessage[] = []
const toolResults: (UserMessage | AttachmentMessage)[] = []
const toolUseBlocks: ToolUseBlock[] = []
let needsFollowUp = false

这四个变量是 Agent Loop 主线的关键。

重要协议：

assistant 产生 tool_use。
本地 runtime 执行工具。
工具结果作为 user message 中的 tool_result 回填给模型。

调模型前准备

位置：src/query.ts:566-586

const useStreamingToolExecution = config.gates.streamingToolExecution
let streamingToolExecutor = useStreamingToolExecution
  ? new StreamingToolExecutor(
      toolUseContext.options.tools,
      canUseTool,
      toolUseContext,
    )
  : null

const appState = toolUseContext.getAppState()
const permissionMode = appState.toolPermissionContext.mode
let currentModel = getRuntimeMainLoopModel({
  permissionMode,
  mainLoopModel: toolUseContext.options.mainLoopModel,
  exceeds200kTokens:
    permissionMode === 'plan' &&
    doesMostRecentAssistantMessageExceed200k(messagesForQuery),
})

这里还没有真正调用模型，只是在准备：

• 是否启用 StreamingToolExecutor
• 本轮实际使用哪个模型 currentModel
• 当前权限模式 permissionMode

调用模型：deps.callModel

位置：src/query.ts:661-719

let attemptWithFallback = true

while (attemptWithFallback) {
  attemptWithFallback = false
  try {
    let streamingFallbackOccured = false
    for await (const message of deps.callModel({
      messages: prependUserContext(messagesForQuery, userContext),
      systemPrompt: fullSystemPrompt,
      thinkingConfig: toolUseContext.options.thinkingConfig,
      tools: toolUseContext.options.tools,
      signal: toolUseContext.abortController.signal,
      options: {
        async getToolPermissionContext() {
          const appState = toolUseContext.getAppState()
          return appState.toolPermissionContext
        },
        model: currentModel,
        fallbackModel,
        querySource,
        ...
      },
    })) {
      ...
    }
  } catch (innerError) {
    ...
  }
}

这里有两个循环，不要混：

外层 while(true)：agent loop。
内层 while(attemptWithFallback)：当前这一轮模型调用的 fallback 重试。

for await (const message of deps.callModel(...)) {

if (!withheld) {
  yield yieldMessage
}

if (message.type === 'assistant') {
  assistantMessages.push(message)

  const msgToolUseBlocks = message.message.content.filter(
    content => content.type === 'tool_use',
  ) as ToolUseBlock[]
  if (msgToolUseBlocks.length > 0) {
    toolUseBlocks.push(...msgToolUseBlocks)
    needsFollowUp = true
  }

  if (
    streamingToolExecutor &&
    !toolUseContext.abortController.signal.aborted
  ) {
    for (const toolBlock of msgToolUseBlocks) {
      streamingToolExecutor.addTool(toolBlock, message)
    }
  }
}

这就是模型输出到本地 runtime 的关键转折点：

模型说：我想调用工具。
本地 runtime 记录下来：待会儿我来执行。

if (!needsFollowUp) {

!needsFollowUp
= 模型这一轮没有请求工具
= 不需要 runTools
= agent loop 可以结束

return { reason: 'completed' }