Claude Code 总架构：输入 → Prompt → API → Tool → State 全链路

一句话定位：Claude Code 是一个以 AsyncGenerator 驱动的 turn-loop Agent 运行时，通过「消息压缩管线 → 模型流式调用 → 工具并发执行 → 状态回写」的无限循环实现自主编程。

调研时间：2026-06-22
依据版本：泄露源码包（2026-03-31 npm source maps，约 1900 文件 / 512K+ 行）
CLI 版本：未实测（需 v2.1.154+），仅源码 + 文档分析
官方文档：code.claude.com/docs（截至 2026-06）

证据等级汇总

日常类比

把 Claude Code 想象成一个自助餐厅的智能服务员：

• 顾客（用户）说”我要吃川菜”
• 服务员（queryLoop）先看菜单（system prompt），然后去厨房下单（API 调用）
• 厨房回复”需要先切菜”（tool_use），服务员就去切菜（工具执行）
• 切完菜把结果送回厨房，厨房继续做菜
• 如果桌子太满了（context 超限），服务员会收走空盘子（compact）
• 这个循环一直持续到菜上齐（模型不再请求工具）

类比边界：真实系统中”服务员”是异步流式的，可以同时切多道菜（并发工具执行），且有复杂的权限系统决定哪些菜能做。

五层架构模型

graph TB
    subgraph L1["Layer 1: CLI / 入口"]
        CLI[CLI Parser] --> Bootstrap[Bootstrap]
        SDK[SDK / Desktop] --> Bootstrap
    end

    subgraph L2["Layer 2: 会话管理"]
        Bootstrap --> ProcessInput[processUserInput]
        ProcessInput --> |"slash cmd"| SlashCmd[Slash Commands]
        ProcessInput --> |"bash"| BashCmd[Bash Mode]
        ProcessInput --> |"text"| QueryEntry[query() 入口]
    end

    subgraph L3["Layer 3: 核心循环 queryLoop"]
        QueryEntry --> CompressPipeline[消息压缩管线]
        CompressPipeline --> APICall[callModel 流式调用]
        APICall --> ToolDispatch[工具分发]
        ToolDispatch --> |"needsFollowUp"| CompressPipeline
        ToolDispatch --> |"完成"| StopHooks[Stop Hooks]
    end

    subgraph L4["Layer 4: 基础设施"]
        Permissions[权限系统]
        Compact[Compact 服务]
        Memory[Memory 系统]
        Analytics[Analytics / OTel]
    end

    subgraph L5["Layer 5: 多 Agent"]
        Coordinator[Coordinator Mode]
        Swarm[Swarm / Teams]
        Subagent[Subagent / AgentTool]
        Workflow[Dynamic Workflow]
    end

    ToolDispatch --> Permissions
    CompressPipeline --> Compact
    QueryEntry --> Memory
    APICall --> Analytics
    ToolDispatch --> L5

各层职责 [源码]

核心循环：queryLoop 详解

query.ts 的 queryLoop 是整个系统的心脏——一个 AsyncGenerator<StreamEvent | Message, Terminal> 在 while(true) 中运行 [源码]：

┌─────────────────────────────────────────────────────────┐
│                    queryLoop (while true)                 │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  1. 消息压缩管线                                         │
│     snip → microcompact → contextCollapse → autocompact  │
│                                                          │
│  2. 组装 system prompt + 附件                            │
│     fullSystemPrompt + attachments + memory prefetch     │
│                                                          │
│  3. 调用模型 (deps.callModel)                            │
│     流式接收 assistant 消息 + tool_use blocks            │
│                                                          │
│  4. 工具执行                                             │
│     StreamingToolExecutor (并发) 或 runTools (串行)       │
│                                                          │
│  5. 循环决策                                             │
│     needsFollowUp? → 组合新 messages → continue          │
│     !needsFollowUp? → stopHooks → return Terminal        │
│                                                          │
│  错误恢复路径:                                           │
│     prompt_too_long → reactive compact → retry           │
│     max_output_tokens → escalate 64K → recovery ×3      │
│     model_fallback → 切换 fallback model                 │
│                                                          │
└─────────────────────────────────────────────────────────┘

关键伪代码（精简自 query.ts）[源码]

async function* queryLoop(params) {
  let state = { messages, turnCount: 1, ... }
  while (true) {
    // Phase 1: 压缩
    messages = snip(messages)          // 历史裁剪
    messages = microcompact(messages)  // 工具结果精简
    messages = collapse(messages)      // 上下文折叠
    messages = autocompact(messages)   // 全量摘要压缩

    // Phase 2: 调用模型
    for await (const msg of callModel(messages, systemPrompt, tools)) {
      yield msg  // 流式输出给 UI
      if (msg has tool_use) toolUseBlocks.push(...)
    }

    // Phase 3: 判断是否需要继续
    if (!needsFollowUp) {
      yield* handleStopHooks(...)
      return { reason: 'completed' }
    }

    // Phase 4: 执行工具
    for await (const result of runTools(toolUseBlocks)) {
      yield result
      toolResults.push(result)
    }

    // Phase 5: 组合下一轮消息
    state.messages = [...messages, ...assistantMsgs, ...toolResults]
    state.turnCount++
  }
}

消息压缩管线

Claude Code 的上下文管理是四级递进的 [源码]：

Autocompact 的阈值计算 [源码]：effectiveContextWindow - 13K buffer，连续失败 3 次后熔断。

与 LangGraph 对比

AppState：全局状态单例

bootstrap/state.ts 定义了一个 80+ 字段的全局状态对象 [源码]，核心域：

AppState
├── 项目身份: cwd, projectRoot, sessionId
├── 模型配置: mainLoopModel, effortValue, advisorModel
├── 权限: toolPermissionContext (mode + rules)
├── 计费: totalCostUSD, modelUsage (per-model buckets)
├── 遥测: OpenTelemetry meter/counter/tracer
├── Agent: agentColorMap, sessionCreatedTeams
├── Prompt 缓存: afkModeHeaderLatched, fastModeHeaderLatched (sticky-on)
├── MCP: clients, tools, resources
├── 任务: taskStates (Map<id, TaskState>)
└── Skill: invokedSkills (Map, 跨 compaction 保留)

设计亮点：Prompt 缓存的 “sticky-on latch” 模式——beta header 一旦激活就不再关闭，避免反复切换导致服务端 prompt cache 被 bust（约 20K tokens/次）。

Feature Flag 系统：编译时 DCE

Claude Code 使用 bun:bundle 的 feature() 宏实现编译时死代码消除 [源码]：

import { feature } from 'bun:bundle'

// 编译时求值，false 分支被完全剔除
const reactiveCompact = feature('REACTIVE_COMPACT')
  ? require('./services/compact/reactiveCompact.js')
  : null

这意味着存在至少两种构建产物：

• ant build（Anthropic 内部）：大部分 flag 为 true
• external build（公开版）：flag 为 false，相关代码从 bundle 中消失

已识别 50+ 个 feature flag，按功能域分类：

运行时 flag：除编译时 DCE 外，还有 GrowthBook（远程配置平台）提供的运行时 flag，通过 getFeatureValue_CACHED_MAY_BE_STALE() 读取。

Task 类型系统

Task.ts 定义了 7 种任务类型 [源码]：

tasks.ts 使用 feature flag 条件加载 [源码]：

• WORKFLOW_SCRIPTS → LocalWorkflowTask（泄露包中仅有引用，实现缺失）[引用]
• MONITOR_TOOL → MonitorMcpTask

模块依赖表

数据流全链路

sequenceDiagram
    participant User
    participant PUI as processUserInput
    participant QL as queryLoop
    participant Compress as 压缩管线
    participant API as claude.ts
    participant Tools as toolOrchestration
    participant Perm as permissions

    User->>PUI: 输入文本/图片/slash命令
    PUI->>PUI: 分流(slash/bash/text)
    PUI->>PUI: 执行 UserPromptSubmit hooks
    PUI->>QL: messages + shouldQuery=true

    loop while(true)
        QL->>Compress: snip → micro → collapse → auto
        Compress-->>QL: 压缩后 messages
        QL->>API: callModel(messages, prompt, tools)
        API-->>QL: stream assistant + tool_use blocks

        alt 无 tool_use
            QL->>QL: handleStopHooks
            QL-->>User: return Terminal
        else 有 tool_use
            QL->>Tools: runTools / StreamingToolExecutor
            Tools->>Perm: hasPermissionsToUseTool
            Perm-->>Tools: allow/deny/ask
            Tools-->>QL: tool results
            QL->>QL: messages += assistant + results
        end
    end

局限性

• 泄露源码版本：2026-03-31，距今约 3 个月。Dynamic Workflow、Ultracode 等新功能在泄露后发布，源码中仅有 stub [引用]
• 编译时 DCE：外部 build 中大量模块被剔除，泄露包是 source maps 还原，可能包含 ant-only 代码
• 未实测：本文所有结论基于静态代码分析，未在本地 CLI 验证运行时行为
• GrowthBook 配置不可见：运行时 feature flag 的实际值取决于远程配置，无法从源码确定
• API 层细节：claude.ts 3420 行中大量是错误处理和遥测，核心调用逻辑约 200 行

下一步

• 工具循环精读 — 工具选择、执行、权限、Hook、结果回写
• 多 Agent 编排 — Swarm / Coordinator / Workflow
• System Prompt 分层 — 优先级逻辑、Skills、泄露对照
• Dynamic Workflow + Ultracode — 编排外置、JS 脚本机制