架构总览

前面几十课分别拆开讲了启动、系统提示词、工具、MCP、技能、状态与 UI。这一课要做相反的事：把这些局部机制重新接回一张整体图，让你能从一次用户输入出发，顺着代码把整套系统跑通。

你可以把 Claude Code 看成六层串接的系统：启动层决定会话如何建立，UI 层承接交互，状态层保存长期上下文，查询层驱动与模型的往返，工具层执行副作用，服务层负责 API / MCP / 压缩等外部连接。

该 ASCII 图映射了每个主要组件及其与其他组件的关系。 自上而下地阅读：用户的击键向下流过每一层，直到到达 API，然后响应通过工具和 UI 向上冒泡。

现在让我们跟踪单个用户消息 - 比如说 "refactor this function" — 贯穿整个堆栈。 每个编号的步骤都映射到源树中的实际代码。

启动顺序经过精心编排，以最大限度地缩短首次渲染时间。 三类工作尽早并行进行：

QueryEngine （在后来的重构中引入）提取什么是整体的 ask() 函数到拥有完整对话生命周期的类中。 每个对话会话存在一个实例。

说明发动机拥有

class QueryEngine {
  private config: QueryEngineConfig       // tools, commands, mcpClients, model, ...
  private mutableMessages: Message[]       // full conversation history (grows each turn)
  private abortController: AbortController  // shared with all tools in this session
  private permissionDenials: SDKPermissionDenial[]  // accumulated for SDK result
  private totalUsage: NonNullableUsage     // token counts across all turns
  private readFileState: FileStateCache   // snapshot of files read this session
  private discoveredSkillNames: Set<string> // skills seen in this turn (for telemetry)
  private loadedNestedMemoryPaths: Set<string> // CLAUDE.md files already injected
}

SubmitMessage() — 回合生命周期

每次致电 submitMessage() 是一个异步生成器 SDKMessage 事件。 每回合的顺序：

query() 循环——迭代剖析

// query.ts — simplified loop skeleton
async function* queryLoop(params) {
  let state = { messages, turnCount: 1, autoCompactTracking, ... }
  const config = buildQueryConfig()   // snapshot env/statsig state

  while (true) {
    // 1. Optionally start skill/job prefetch (async, consumes settled results only)
    // 2. Send streaming API request via deps.sendRequest()
    for await (const event of streamEvents) {
      yield event  // passes text deltas directly to REPL
      if (event.type === 'tool_use') collectToolUse(event)
    }

    // 3. Check stop reason
    if (stopReason === 'end_turn') return 'success'

    // 4. Execute tools (StreamingToolExecutor — parallel where possible)
    for await (const result of runTools(toolUseBlocks, canUseTool, context)) {
      yield result
    }

    // 5. Token budget / compact checks → may compact and continue
    // 6. Append tool_results to messages, increment turnCount, loop
  }
}

克劳德可以调用的每项能力都是 Tool。 工具系统故意扁平化——没有工具层次结构，只有注册表功能 getAllBaseTools() in tools.ts 返回权威列表。

工具接口（Tool.ts）

// Simplified Tool interface
interface Tool {
  name: string                                         // must be stable (used in Statsig cache key)
  description: string                                  // injected into system prompt
  inputSchema: ZodSchema                             // validation before call()
  isEnabled(): boolean                               // feature-gate / env check
  call(input, context: ToolUseContext):               // async generator
    AsyncGenerator<ToolProgressData, ToolResult>
  renderToolResult(result, context): React.ReactNode  // Ink UI rendering
}

ToolUseContext — 工具通向世界的窗口

每个工具调用都会收到一个 ToolUseContext 将工具可能需要的所有内容捆绑在一起，而不将其耦合到全局状态：

功能门控工具

许多工具是有条件包含的 feature() 标志（Bun 捆绑时死代码消除）或环境变量。 这使工具列表对于 Anthropic 的提示缓存键保持确定性：

// tools.ts — feature gate pattern
const SleepTool =
  feature('PROACTIVE') || feature('KAIROS')
    ? require('./tools/SleepTool/SleepTool.js').SleepTool
    : null

// getAllBaseTools() filters nulls from the array
// NOTE: this list is synced to Statsig console for prompt cache invalidation

Claude Code 有一个两层状态模型。 了解使用哪一层来做什么对于理解代码库至关重要。

关键设计原则： bootstrap/state.ts 是模块级单例（普通 JS 对象），而 AppState 是 React 上下文。 这种分离意味着查询引擎和工具可以在不导入 React 的情况下访问会话身份，而 UI 可以根据任何 AppState 更改进行反应式重新渲染。

// bootstrap/state.ts — the singleton shape (partial)
type State = {
  originalCwd: string
  projectRoot: string
  totalCostUSD: number
  totalAPIDuration: number
  cwd: string
  modelUsage: { [modelName: string]: ModelUsage }
  mainLoopModelOverride: ModelSetting | undefined
  isInteractive: boolean
  sessionId: SessionId
  sdkBetas: BetaMessageStreamParams['betas']
  hookRegistry: RegisteredHookMatcher[]
  meter: Meter | undefined
  tokenBudgetInfo: { remainingTokens: number; ... }
  // ... ~40 more fields, all process-lifetime
}

// state/AppStateStore.ts — the React state shape (partial)
type AppState = DeepImmutable<{
  settings: SettingsJson
  mainLoopModel: ModelSetting
  toolPermissionContext: ToolPermissionContext
  messages: Message[]
  mcpClients: MCPServerConnection[]
  agentDefinitions: AgentDefinitionsResult
  speculation: SpeculationState
  fileHistory: FileHistoryState
  plugins: LoadedPlugin[]
  tasks: TaskState | null
  // ... ~50 more fields
}>

Claude Code 中的“会话”是具有唯一 UUID 的持久对话。 会话作为 JSONL 转录文件存储在 ~/.claude/projects/<cwd-hash>/<session-id>.jsonl.

会话生命周期

// Startup: generate or restore session ID
getSessionId()          // reads bootstrap/state.ts
registerSession()        // registers in concurrent sessions tracking
countConcurrentSessions() // used for display in status bar

// During conversation:
recordTranscript(messages)   // enqueues write (lazy 100ms JSONL flush)
flushSessionStorage()         // forced flush (EAGER_FLUSH env / cowork)
cacheSessionTitle()           // first user message → title for resume UI

// Resume path (--continue / --resume):
loadTranscriptFromFile()      // reads JSONL back into Message[]
processResumedConversation()  // validates + replays into initial messages

MCP（模型上下文协议）服务器连接为 MCPServerConnection 里面装着的物体 AppState.mcpClients。 它们在第一个查询之前初始化并传递到每个 ToolUseContext.

MCP 工具是 not in getAllBaseTools() - 它们在会话启动时与基本工具一起动态添加 getMcpToolsCommandsAndResources()。 这就是 MCP 工具名称可能与基本工具名称冲突的原因：重复数据删除发生在加载时。

每个工具调用都会经过 canUseTool() 执行前。 这个单一功能是所有权限决策的架构瓶颈。

// The permission gate — called by query.ts before runTools()
const wrappedCanUseTool: CanUseToolFn = async (
  tool, input, toolUseContext, assistantMessage, toolUseID, forceDecision
) => {
  const result = await canUseTool(tool, input, toolUseContext, ...)
  if (result.behavior !== 'allow') {
    // Track for SDK result reporting
    this.permissionDenials.push({ tool_name, tool_use_id, tool_input })
  }
  return result
}

当对话增长到足以威胁模型的上下文窗口时，Claude Code 会触发自动压缩。 这对用户来说是透明的。

钩子允许用户在特定的生命周期点注入 shell 命令或回调。 它们配置在 settings.json 并在启动时捕获一次（不可变快照模式）。

代码库有两个不同的共享运行时路径 QueryEngine 但它们的 UI 和启动行为有显着差异：

The AgentTool 启用递归执行：Claude 可以生成子代理，每个子代理都有自己的 QueryEngine 实例和受限工具集。

在集群模式下（ENABLE_AGENT_SWARMS=true），代理通过 Unix Domain Socket (UDS) 消息服务器进行通信，该服务器于 setup.ts。 每个代理注册 TeamCreateTool 并可以通过以下方式将消息发送回协调器 SendMessageTool.

一切都在一起 - 从冷启动到流响应的完整时间表：

1. 异步生成器线程

从 API 到 UI 的整个数据流是一个异步生成器链。 query() yields StreamEvents, QueryEngine.submitMessage() yields SDKMessages，并且 REPL 消耗它们。 这使得真正的流式传输无需回调或事件总线。

2. 死代码消除通过 feature()

Bun 的捆绑时间 feature('FLAG_NAME') 从编译的二进制文件中完全删除禁用的功能分支。 这意味着每个构建的工具列表都是确定的（对于 Anthropic 的提示缓存键很重要），并且禁用的功能会增加零运行时开销。

3. 缓存预热以应对延迟

关键路径（系统提示、工具、命令、模型功能）均在设置/启动期间并行预热。 当用户提交第一个提示时，几乎所有昂贵的 I/O 都已经完成。 模式：触发异步工作，丢弃承诺，并记录/缓存结果。

4. 不可变的AppState + 可变的引导/状态

React 状态是不可变的（DeepImmutable）以防止意外突变并启用 React 的变更检测。 但是会话级常量（cwd、sessionId、model）存在于一个普通的模块单例中，该单例故意不是 React 状态——这些值由查询引擎深处的非 React 代码访问。

5. 的 isBareMode() 快速路径

每一个昂贵的启动操作都由 if (!isBareMode())。 此单个标志（无头运行时为 true）会跳过 React、Ink、UDS 消息传递、插件预取、延迟预取和所有仅交互式设置。 无头执行几乎变成纯粹的计算。

6. 并行子流程投资

代码库不是顺序 I/O，而是尽早触发子进程和异步操作，并让它们与 JavaScript 执行并行运行。 startMdmRawRead() and startKeychainPrefetch() 两者都会在 135ms 模块图完成评估之前触发。 当使用其结果的代码运行时，它们通常已经完成。