Claude Code 源码架构全解剖

00全景架构：六层结构

先建立一个整体的心智模型，后面每一章都是对其中一层的放大。

Claude Code 本质上是一个「把 React 渲染到终端的前端」+「一个 while(true) 的 agent 引擎」+「一套工具执行器」。所有花哨的功能（斜杠命令、Skills、MCP、子 agent）最终都收敛为两种东西：注入对话的文本，或模型可调用的工具。

01一条消息的一生 ★

这是全文的主线。从你按下一个键，到回复完整出现，共 12 站。每一站在后面的章节里都有对应的放大详解。

02启动流程：进程启动 → REPL 出现

从 claude 命令敲下到界面出现，分为轻量引导、重量主流程、初始化钩子、渲染挂载四个阶段。

2.1 两级入口设计

真正的进程入口是 entrypoints/cli.tsx:302 的 void main()。这个文件是一个刻意「轻量」的引导层——所有 import 都用动态 import()，这样 claude --version 之类的快速路径几乎零模块加载就能返回。它按顺序检查一堆特殊 flag（--version、MCP server 模式、daemon、后台会话管理、remote 桥接……），都不命中才加载 800KB 的 main.tsx：

entrypoints/cli.tsx:288-297
// No special flags detected — 进入重量级主流程
const { startCapturingEarlyInput } = await import('../utils/earlyInput.js');
startCapturingEarlyInput();          // 缓存用户在加载期间提前敲的键
const { main: cliMain } = await import('../main.js');
await cliMain();

2.2 main.tsx：commander 解析与模式判定

参数解析用 @commander-js/extra-typings（commander 的类型增强版），在 main.tsx:884 的 run() 里链式定义所有 flag，主命令处理器在 main.tsx:1006。此前 main.tsx:800-803 先判定交互性：

main.tsx:800-803
const hasPrintFlag = cliArgs.includes('-p') || cliArgs.includes('--print');
const isNonInteractive = hasPrintFlag || hasInitOnlyFlag || hasSdkUrl || !process.stdout.isTTY;

commander 的 preAction hook（main.tsx:907）在任何 action 之前执行：init()（配置系统、CA 证书、OAuth 账户信息、代理、预连接 API 的 TCP+TLS）→ runMigrations()（版本号 11，比对 migrationVersion 跑一批配置迁移）→ 加载企业远端托管设置。

2.3 setup()：会话初始化

主命令 action 里调 setup.ts:56，关键步骤按顺序：Node ≥18 检查 → setCwd()（一切依赖 cwd 的代码之前必须先设，setup.ts:161）→ hooks 配置快照 → worktree 创建（--worktree 可能 chdir）→ session memory 初始化 → 预取斜杠命令 → logEvent('tengu_started') 遥测信标 → bypassPermissions 安全校验（禁止 root、要求容器隔离，setup.ts:396-442）。

2.4 交互模式：Ink 挂载

print 模式（-p）的区别：分叉在 main.tsx:2585。不创建 Ink root（否则 patchConsole 会吞掉输出）、跳过信任对话框（视为可信直接应用全部环境变量）、MCP 在启动路径同步连接（交互模式则交给 REPL 内的 hook 增量连接）、执行引擎换成 cli/print.js 的 runHeadless（main.tsx:2827），按 --output-format 输出后直接退出。

2.5 settings 五层体系

定义在 utils/settings/constants.ts:7 的 SETTING_SOURCES，顺序即优先级（后者覆盖前者）：

合并在 utils/settings/settings.ts:645 的 loadSettingsFromDisk()：以插件 settings 为最低优先级基底，按序用 lodash mergeWith 深合并；policy 层内部「first source wins」（远端 > MDM > managed-settings.json）。

2.6 CLAUDE.md 什么时候被读

不是启动时，而是第一次组装请求时惰性读取（memoize 缓存整个会话）。utils/claudemd.ts:790 的 getMemoryFiles 按 Managed → User（~/.claude/CLAUDE.md + rules/*.md）→ Project（从 cwd 向上遍历到根，每层试 CLAUDE.md 和 .claude/CLAUDE.md）的顺序扫描；context.ts:155 的 getUserContext 把它拼进 userContext.claudeMd。注意：CLAUDE.md 不进 system prompt，而是拼在消息数组最前面（第 3 章详述）。

03Agentic 主循环：query.ts

整个产品的心脏。1729 行的 query.ts 里是一个 while(true)，每次迭代 = 一次「调模型 + 执行工具」的回合。

3.1 三层调用栈

调用关系
用户输入
 └─ QueryEngine.submitMessage()   [QueryEngine.ts:209]  会话经理：输入处理、落盘、SDK 协议、maxTurns/预算
     └─ query()                   [query.ts:219]        薄壳生成器
         └─ queryLoop()           [query.ts:241]        真正的 while(true) 主循环

三者都是 async generator，用 yield 把消息一块块流式吐出去。分工是：QueryEngine 管「会话生命周期」（transcript 落盘、usage 累计、把内部消息转成 SDK 协议、maxTurns/maxBudgetUsd 检查），queryLoop 管「干活」。前者可以换外壳（REPL / headless / SDK），后者不变。

签名值得细看——输入输出类型就是整个引擎的契约：

query.ts:219-228
export async function* query(params: QueryParams): AsyncGenerator<
  StreamEvent | RequestStartEvent | Message | TombstoneMessage | ToolUseSummaryMessage, // yield 的类型
  Terminal  // return 的终止原因：completed / aborted / max_turns / blocking_limit …
>

循环不用递归而用 while(true) + 可变 State 对象（query.ts:204-217，携带 messages、turnCount、autoCompactTracking 等）。「再来一轮」就是给 state 赋新值然后 continue（query.ts:1715-1727），避免真递归的栈增长。

3.2 一轮迭代的完整步骤

needsFollowUp（有没有工具调用）是唯一的「是否再来一轮」判据。这就是 agent「自主多步工作」的全部秘密——没有任何计划器，只是模型不停要工具、循环不停喂结果。

3.3 System Prompt 是怎么拼出来的

入口在 utils/queryContext.ts:44 的 fetchSystemPromptParts，并行取三样：

优先级链在 utils/systemPrompt.ts:41：override > coordinator > agent > custom > default，最后还能追加 appendSystemPrompt（QueryEngine.ts:321-325）。

3.4 中断（ESC）与 abort signal

信号源是 toolUseContext.abortController。ESC → UI 的 useCancelRequest（hooks/useCancelRequest.ts:87）→ abortController.abort('user-cancel')。这个 signal 被传给 API 调用（query.ts:664，SDK 抛 APIUserAbortError）和所有工具。循环在三个检查点响应：流式中（不再接收新工具）、API 流结束后（query.ts:1015）、工具执行后（query.ts:1485）。

04工具系统

一个工具 = 执行逻辑 + 权限判断 + 给模型的说明书 + 终端 UI 渲染，全部塞在一个对象里。

4.1 Tool 接口（Tool.ts:362-695）

4.2 注册表：谁被启用（tools.ts）

三层条件：① 编译期——feature() 是打包期常量，false 的 require() 整块被摇树删除（内部构建才有 REPLTool 等）；② 运行期全量池 getAllBaseTools()（tools.ts:193-251），按环境变量/特性开关条件展开；③ 按权限过滤 getTools()（tools.ts:271）——被整条 deny 的工具在模型看到之前就剔除。合并 MCP 工具时内置工具保持连续前缀且分别排序——因为服务端在最后一个内置工具后放缓存断点，乱序会击穿 prompt cache（tools.ts:345-389）。

4.3 校验失败怎么让模型重试

两阶段校验都不抛异常，而是把错误包成 is_error: true 的 tool_result 回给模型，模型下一轮看到就能修正参数：

services/tools/toolExecution.ts:615（阶段1：Zod）
const parsedInput = tool.inputSchema.safeParse(input)
if (!parsedInput.success) {
  return [{ message: createUserMessage({
    content: [{ type: 'tool_result', is_error: true, tool_use_id: toolUseID,
      content: `<tool_use_error>InputValidationError: ${errorContent}</tool_use_error>` }],
  })}]
}
// 阶段2：tool.validateInput()（如 Edit 的"必须先 Read"）失败同样包成 tool_use_error

源码注释直言：「模型其实不太擅长生成合法输入」，所以这层反馈闭环很关键。

4.4 四个代表性工具

runAgent.ts:748
for await (const message of query({
  messages: initialMessages,
  systemPrompt: agentSystemPrompt,   // agent 定义自己的 prompt + 环境信息
  toolUseContext: agentToolUseContext, // 隔离的上下文（异步 agent 有独立 abortController）
  maxTurns, ...
})) { yield message }

05权限系统

「模型想做 X，允许吗？」的完整判定链，插在每个工具真正执行之前。

5.1 四种权限模式

5.2 规则匹配：Bash(npm:*) 是怎么生效的

规则解析成三型（tools/BashTool/bashPermissions.ts）：prefix（npm:* → 命中 npm install 但不命中 npms）、exact（完整命令相等）、wildcard（通配）。两个防绕过设计：

• 复合命令拆分：ls && rm -rf 被拆成子命令逐个检查，不能靠第一个安全命令蒙混。
• 环境变量剥离白名单：FOO=bar git push 剥离前缀再匹配，但 LD_PRELOAD、NODE_OPTIONS 等能执行代码的变量绝不剥离。

5.3 弹窗怎么从后台循环冒泡到 UI

这是引擎和 UI 之间最精巧的握手——一个 Promise + 队列：

06API 层：请求组装、流式、缓存、重试

services/api/ 三个文件各司其职：client.ts 管认证，claude.ts 管请求与流，withRetry.ts 管失败。

6.1 四条认证路径

services/api/client.ts:88 getAnthropicClient()
if CLAUDE_CODE_USE_BEDROCK  → AnthropicBedrock   // AWS（Bearer token 或 AK/SK）
if CLAUDE_CODE_USE_FOUNDRY  → AnthropicFoundry   // Azure
if CLAUDE_CODE_USE_VERTEX   → AnthropicVertex    // GCP
else                        → Anthropic          // 第一方
// 第一方内部再二选一：
apiKey:    isClaudeAISubscriber() ? null : getAnthropicApiKey(),   // API key（env > keychain > helper 脚本）
authToken: isClaudeAISubscriber() ? oauthTokens.accessToken : undefined  // 订阅走 OAuth，请求前自动刷新

全部用官方 SDK，不自封 fetch（唯一的 wrapper 只注入 request-id 和 debug 日志）。OAuth 登录走 PKCE + 本地 localhost 回调监听（services/oauth/index.ts:32）。

6.2 SSE 流式消费

发起在 claude.ts:1822：messages.create({stream:true}).withResponse()——拿原始 Response 是为了读 request_id 和在退出时手动 cancel socket 防泄漏。刻意不用 SDK 的 BetaMessageStream，因为它对每个 input_json_delta 跑 partialParse 是 O(n²)，CLI 自己拼字符串。事件循环（claude.ts:1940-2299）：

另有两套看门狗：90 秒无 chunk 主动 abort（idle watchdog），相邻事件间隔 >30s 记 stall 日志。流式彻底失败时降级到非流式请求（max_tokens 上限降到 64000）。

6.3 Prompt Caching：断点打在哪

API 限制每请求最多 4 个 cache_control 断点（源码注释警告「别再加，否则 400」）。策略：

1. System prompt 分块（utils/api.ts:321）：按 SYSTEM_PROMPT_DYNAMIC_BOUNDARY 切开——边界前的静态段打 global scope 缓存（跨会话、跨用户共享！），动态段不缓存。有 MCP 工具时退回 org 级（MCP 工具 per-user，没法全局共享）。
2. 消息断点恰好一个（claude.ts:3063）：打在最后一条消息的最后一个 content block 上。每轮请求的「新增部分」就成了下轮的缓存前缀。
3. tool_result 的 cache_reference：配合 cache-editing beta 做「增量删除已缓存的旧工具结果」（见第 7 章）。

beta 头有「sticky latch」机制：某个 beta 一旦发出就整个 session 持续发——中途 toggle 会改变服务端 cache key，炸掉几万 token 的缓存。

6.4 重试与降级（withRetry.ts）

• 退避：有 retry-after 头就听它的；否则 min(500 × 2^(attempt-1), 32s) + 0~25% 抖动，最多重试 10 次（withRetry.ts:530,52）。
• 429：API key 用户重试；订阅用户不重试（限流几个小时，重试没意义）。
• 529 过载：只有前台请求源重试（后台如标题生成直接放弃，避免容量雪崩时重试放大）；连续 3 次触发模型 fallback（抛 FallbackTriggeredError 切换到 fallbackModel）。
• 401：清 API key 缓存 / 强制刷新 OAuth token 后重试。
• 400 上下文超限：从错误消息里解析出上限，动态下调 max_tokens 重试。

6.5 成本统计

usage 从 message_start + message_delta 合并（>0 才覆盖，防止 0 值冲掉真值）。calculateUSDCost（utils/modelCost.ts:177）= 输入 + 输出 + cache 读 + cache 写 + web 搜索次数，按模型查价目表；addToTotalSessionCost（cost-tracker.ts:278）按模型累计并喂 OpenTelemetry，会话结束存入 project config，resume 时恢复。token 估算兜底：文本按 length / 4，图片固定按 2000 token 计。

07上下文压缩：三级机制

上下文窗口是有限的，Claude Code 用「全量摘要 + 微清理 + API 侧管理」三级手段续命。

7.1 Auto-compact：全量摘要压缩

还有被动压缩：API 真的返回 prompt-too-long 时，query.ts:1119 做一次抢救性压缩再重试。

7.2 Microcompact：微清理

如果距上条消息间隔太久（服务端缓存已过期、前缀反正要重写），趁机把旧的工具输出替换成 '[Old tool result content cleared]'——只清 Read/Bash/Grep 等可再生工具的结果（microCompact.ts:253,41）。另有 cache-editing 变体：不改本地消息，而是发 cache_edits 指令让服务端从 KV 缓存里增量删除旧工具结果。

7.3 API 侧原生 context management

请求体带 context_management.edits（apiMicrocompact.ts:64）：clear_thinking 策略对所有用户生效（空闲超 1 小时只保留最后一轮 thinking）；clear_tool_uses（内部实验）在输入超 18 万 token 时让服务端清到 4 万。另外每请求最多 100 个媒体项，超了静默丢最老的图片。

08终端 UI：fork 版 Ink

不是 npm 上的 ink 包，而是 Anthropic 深度改造的 fork（src/ink/），React 是真 React，「浏览器」被换成了终端渲染引擎。

8.1 渲染原理：React → ANSI

渲染管线
React 组件
 → react-reconciler(自定义 HostConfig)     ink/reconciler.ts:331 createInstance
 → 自建虚拟 DOM (ink-box / ink-text)       ink/dom.ts:20
 → Yoga 排版引擎（flexbox 算坐标）          ink/render-node-to-output.ts:436
 → 单元格屏幕缓冲 Screen（字符+颜色+样式）    ink/screen.ts
 → 前后帧逐格 diff → 最小 ANSI 补丁          ink/log-update.ts:308 diffEach
 → write(stdout)                          ~60fps 节流（ink.tsx:213）

关键在最后两步：不是每帧重画整屏，而是像 React 的 DOM diff 一样只更新变化的终端单元格——这就是流式输出不闪屏的原因。fork 版还加了 upstream Ink 没有的：alt-screen 全屏、鼠标追踪、文本选择、OSC8 超链接、双缓冲。

8.2 组件树

从 root 到输入框
<App>                        components/App.tsx —— 只挂 3 个 Context Provider
 └ <REPL>                    screens/REPL.tsx:572 —— 5005 行的主屏幕
    └ <FullscreenLayout>     布局骨架，分槽位
       ├ scrollable: <Messages>(虚拟滚动) + <SpinnerWithVerb> + <PromptInput>
       ├ overlay:    权限确认层（toolPermissionOverlay）
       ├ modal:      居中模态（/model /status …）
       └ bottom:     粘性底栏

状态分三层：全局 AppState store（useSyncExternalStore 风格，存权限上下文/MCP/后台任务）；消息列表在 REPL 组件的本地 useState（流式临时态 streamingToolUses、abortController 也在这）；外加十来个小 Context（通知、模态、排队消息）。

8.3 关键渲染细节

• 流式文本：单独用 <StreamingMarkdown> 渲染，与已完成消息分开，避免每个 token 重排整个列表（Messages.tsx:703）。
• 工具结果折叠：<MessageResponse> 画 ⎿ 缩进符，用 overflowY="hidden" 限高实现折叠，Ctrl+O 展开。
• bash 模式：在输入框开头敲 ! 触发 getModeFromInput 切模式（PromptInput.tsx:854）；plan mode 不是输入前缀而是权限模式，Shift+Tab 循环切换（PromptInput.tsx:1518）。
• 斜杠补全：useTypeahead hook + 命令/文件/频道多种 trigger；菜单打开时回车先接受补全而不是发消息。
• ESC 中断：语义键 chat:cancel（useCancelRequest.ts:87,164）→ 清空权限队列 → abortController.abort('user-cancel')。没有任务在跑时 ESC 改为弹出排队命令；双击 Ctrl+C 才退出程序。

09扩展生态：七种机制，两种本质

所有扩展最终收敛为两类：「注入对话的文本」或「模型可调用的工具」。Hooks 是唯一的例外——它绕过模型，由 harness 直接执行。

9.1 一张总表

所有磁盘自定义内容走同一个加载器 utils/markdownConfigLoader.ts:297：合并 managed > user（~/.claude）> project（.claude）三来源，能放扩展的五个目录是 commands / agents / output-styles / skills / workflows。

9.2 Hooks：exit code 的语义

支持 27 种事件（PreToolUse / PostToolUse / Stop / UserPromptSubmit / SessionStart / PreCompact……），hook 本体有四种后端：shell 命令、LLM prompt 评估、HTTP POST、子 agent 验证。hook 输入 JSON 走 stdin，影响主流程的方式：

9.3 Skills 的两种执行方式

SkillTool 的描述里不含 skill 全文，只有「名字+简述」清单（预算约占上下文 1%）。调用时（SkillTool.ts:622）分两路：inline（默认）——把 SKILL.md 渲染后作为 meta user 消息直接注入当前对话，「加载技能」本质上就是「贴一段说明书」；fork——起独立上下文的子 agent 跑，只回传最终结果。frontmatter 支持参数替换（$1/$ARGUMENTS）、${CLAUDE_SKILL_DIR}、内联 shell 执行（MCP 来源的 skill 出于安全禁止）。

9.4 MCP 工具的动态包装

客户端用官方 @modelcontextprotocol/sdk，transport 覆盖 stdio（子进程）/ SSE / Streamable HTTP / WebSocket / in-process。连上后 tools/list 拉工具列表，对每个工具动态生成一个 Tool 对象（client.ts:1767-1988）：名字 = mcp__server__tool，inputSchema 直接用 server 给的 JSON Schema，isReadOnly 等读 server 的 annotations。MCP 的 prompts 则被包装成 /server:prompt 斜杠命令。OAuth 用 step-up 模式：先看到 403 再触发认证刷新。

10文件索引速查

按「我想看 X」检索，路径相对 restored-src/src/。