深扒 Claude Code 源码（〇·总纲）：一个生产级 LLM Agent 的工程全景

标的：一份从 Claude Code 官方发布包 source map 逆向还原的源码树（约对应 v2.0.5x，前沿模型 Claude Opus 4.6）。本系列剖析的是 Claude Code 这个工具本身的工程实现，而非还原者的工作；还原树的真实性与缺口在文末附录单列。

本系列共 5 篇，本篇是总纲，给出全景与评估；后续 4 篇逐子系统深挖，每个论点都带 file:line 证据。

执行摘要

Claude Code 是把"与不可靠的大模型协作"这件事做成生产级 CLI 产品的少数实现之一。它的工程重心不在"调用模型"，而在围绕模型的一整圈现实难点：长会话的 token 溢出、模型对工具的滥用与绕过、prompt cache 命中率（直接等于钱和延迟）、终端冷启动体感、终端渲染性能、以及面向数百万用户的灰度/实验/熔断能力。这份代码用大量精巧且偏执的工程把这些难点逐个啃下，代价是复杂度已逼近单人可掌握的上限。

本系列基于对该源码树（约 2077 文件、46 万行 TypeScript）的两轮分析与 14 个子系统的逐一深挖。核心发现可概括为六条贯穿性的工程主张：

一切为 prompt cache 让路。工具池排序去重、beta header 的 sticky latch、system prompt 三件套的固定前缀、fork 子代理的字节级消息复用——多处看似过度设计的代码，根因都是"保住服务端缓存断点不失效"。
安全模型是 fail-closed + 敌对思维。工具能力位默认按"有写、不可并行"对待；Bash 用 tree-sitter AST 解析命令、降级前先查 deny 防绕过；sed 模拟编辑字段从模型 schema 中抹除防权限绕过。假设的威胁是"模型会想方设法越界"。
上下文压缩是五套机制而非一套，各管一段（snip / microcompact / context-collapse / autocompact / reactive-compact），在会话循环每轮的固定位置按序触发。这是 agent 能长时间干活的命门。
启动性能精算到毫秒。模块求值期就并行 fire MDM/keychain 子进程与 import 重叠、按需付费的 fast-path 分流、把 OpenTelemetry 的 ~400KB 推迟到首帧后。
三层开关体系：bun:bundle 的 feature()（编译期 DCE，管"代码存不存在"）+ GrowthBook（运行期灰度/A-B）+ Statsig 式动态配置（秒级熔断）。三者按时间尺度分工。
内部与外部构建未做干净隔离。USER_TYPE==='ant'、"external"==='ant' 的死分支散布全身，靠构建期 define + DCE 切版本——这是组织约束渗进代码结构，也是这份"内部构建反编译"能暴露出大量内部机制的原因。

关于来源与方法

这份源码哪来的。 Claude Code 官方以 Bun 打包发布，产物里 552 个文件尾部保留了内联 source map（base64）。还原者解码 source map 还原出带原始注释、JSDoc 的源文件，再为无法恢复的私有/原生模块补写兼容 shim，使项目能 bun install + bun run dev 跑起来。

为何可信。 解码出的源文件含 React Compiler 编译痕迹（_c()、$[n] memo cache）——这是反编译产物的指纹，无法手工伪造；代码内含无法编造的内部标识符（OAuth CLIENT_ID、数百个 tengu_* 遥测事件名、计费头 cch=00000 引用 bun-anthropic 的 Attestation.zig）、指向 Anthropic 内部系统的引用（服务端 renderer.py 路径、内部 issue 号、Statsig 控制台 URL）。判定：真实的 source-map 还原，非 AI 仿造，且还原的是带 ant 专属逻辑的内部构建。

本系列怎么生成的。 通过多 agent 工作流并行通读子系统：先做高层测绘 + 一轮独立复核，再为每个子系统派一个 agent 深挖并产出对应章节，全部要求 file:line 证据。

可信度声明。 系列描述的是这份还原树所呈现的实现。还原树与官方线上版本可能有差异：依赖版本是还原者用镜像重建的、原生能力被 shim 降级、部分 ant-only 模块因编译期 DCE 从 source map 中缺失而无法还原。涉及缺口处文末附录已标注。

版本定位

线索	取值	来源
前沿模型	Claude Opus 4.6	`src/constants/prompts.ts:118`
模型族 ID	`claude-opus-4-6` / `claude-sonnet-4-6` / `claude-haiku-4-5-20251001`	`prompts.ts:121`
版本注释	`2.0.53-dev.20251124`、`v2.1.70`、`v2.1.83`	datadog.ts / toolSearch.ts / officialMarketplaceGcs.ts
SDK	`@anthropic-ai/[email protected]`、`[email protected]`	`bun.lock`
迁移版本	`CURRENT_MIGRATION_VERSION = 11`（含 `migrateSonnet45ToSonnet46`）	`src/migrations/`
占位版本号	`999.0.0-restored`（真实发布号未保留）	`package.json`

综合判断：对应 Claude Code 2.x 线，约 2.0.5x，2025 年 11 月前后的内部构建。

整体架构

进程入口                       会话内核                          下游服务
─────────                     ─────────                        ─────────
bootstrap-entry.ts            QueryEngine.submitMessage         services/api  (4 provider)
  │ 注入 MACRO 宏               │                                services/mcp  (7 传输)
  ▼                            ▼                                services/oauth
entrypoints/cli.tsx           query.ts :: queryLoop()           services/analytics (双发遥测)
  │ fast-path 分流             （显式状态机 while(true)）          services/compact (5 套压缩)
  │ (version 零导入)            每轮固定顺序:                      services/lsp / plugins
  ▼                            预算→snip→microcompact            services/policyLimits
main.tsx                       →collapse→autocompact
  │ Commander + preAction      →组装 system prompt
  │ init() 时序                →callModel 流式 ──────────────▶  Anthropic API
  ▼                            →工具调度(并发≤10 / 流式执行)
replLauncher → <App><REPL/>    →拼回 tool_result → 下一轮
  │                                  │
  ▼                                  ▼
src/ink (魔改 Ink fork)        tools/ (51 工具, buildTool 工厂)
cell 双缓冲 + 纯 TS Yoga       │  权限管线: zod→validateInput→
差分渲染 + kitty/SGR           │  hooks→canUseTool→call→落盘
                              └─ Bash: tree-sitter AST 安全引擎
                                 Agent: fork/teammate/worktree/remote 四路径

横切层: utils/ (574 文件) —— settings 五源合并 / permissions 引擎 / auth / 消息模型
开关层: feature()(编译期 DCE) + GrowthBook(运行期灰度) + Statsig(秒级熔断)
扩展层: bridge(Remote Control) / coordinator+swarm(多 agent) / skills / plugins / memdir(自动记忆)

两条主数据流：

启动流（冷启动体感优先）：bootstrap-entry 注入构建宏 → cli.tsx 按成本递增分流（--version 零导入最优先）→ 确认是交互会话才动态加载 ~790KB 的 main.tsx → preAction 汇合模块级并行预热（MDM/keychain）后跑 init() → 信任门控 showSetupScreens（信任建立后才初始化遥测、应用危险 env）→ 首帧 render → startDeferredPrefetches 把剩余预热塞进"用户开始打字"的窗口。
会话流（正确性 + 成本优先）：用户消息经 QueryEngine 处理斜杠命令/附件 → queryLoop 状态机每轮做预算裁剪与多级压缩 → 组装带稳定缓存前缀的 system prompt → 流式调模型 → 收集 tool_use 按并发安全性分批执行 → tool_result 拼回，直到无工具调用，经 stop hooks / token budget 检查后终止。

关于本系列

后续 4 篇按"入口 → 内核 → 工具/安全 → 服务 → UI → 扩展 → 治理"展开，每篇可独立阅读：

（一）启动、会话循环与上下文压缩：启动链路与启动性能 · 核心会话循环与查询状态机 · 五套压缩机制
（二）工具系统、Bash 安全、API 与 MCP：工具抽象与执行管线 · Bash 安全与权限引擎 · API 客户端与请求构造 · MCP 集成
（三）配置权限、认证与终端 UI 渲染：配置体系与权限引擎 · 认证与秘钥存储 · 终端 UI 渲染管线
（四）多 Agent、Remote Control、记忆与遥测：多 Agent 编排 · Remote Control 与远程会话 · 系统提示/持久化/记忆 · 遥测与特性开关体系

下面先给出读完全系列后的横向评估，便于带着问题进入细节。

综合工程评估

把 14 个子系统横向打通后，有六组主题反复出现，它们才是这份代码真正的"设计哲学"。

主题一：prompt cache 是隐形的第一设计约束

几乎每个子系统都为缓存稳定性付出过非直觉的代价。assembleToolPool 宁可写更复杂的"内置工具排序作前缀、MCP 工具接其后、再 uniqBy"也不做扁平排序，只为不让 MCP 工具插进内置工具之间击穿服务端缓存断点；beta header 用 sticky latch 锁住会话内不变；fork 子代理用 buildForkedMessages 让所有兄弟产生字节相同的请求前缀；ToolSearch 延迟加载使 deferred 工具 schema 只在被发现后才进 prompt。这是 LLM 产品独有的工程引力：缓存命中率直接换算成 token 成本与首 token 延迟，于是它从"优化项"上升为"架构约束"，反过来塑造了数据结构的顺序与不可变性。这是这份代码给同类产品最值得抄的一课。

主题二：安全是 fail-closed 加敌对威胁模型

工具层 TOOL_DEFAULTS 把 isConcurrencySafe/isReadOnly/isDestructive 全默认 false——开发者忘了声明，系统就保守当作"有写、不可并行"，绝不会把写操作误判成可并行。Bash 权限引擎把命令解析成 tree-sitter AST，遇命令替换/控制流这类"太复杂"的就降级询问，但降级前先查 deny 规则防止有人用复杂语法绕过禁令；剥离 LD_*/DYLD_*/PATH 劫持变量；sed 被模拟成文件编辑且其 _simulatedSedEdit 字段从模型可见 schema 中 omit 掉防绕权限；UNC 路径跳过文件操作防 NTLM 凭据外泄；PowerShell 反用微软 Constrained Language Mode 类型白名单。难得的是它诚实：shouldUseSandbox 的 excludedCommands 注释直言"这不是安全边界"。整套设计假设的对手不是外部攻击者，而是"会越界的模型自己"——这正是 agent 时代的新威胁模型，多数框架在这块还是裸奔。

主题三：长会话 token 管理是 agent 的命门

五套压缩机制（snip / microcompact / context-collapse / autocompact / reactive-compact）分别解决不同问题：定时清旧 tool_result、折叠可恢复上下文、主动按窗口阈值压缩（有效窗口减 13k buffer、连续 3 次失败熔断）、被动接 413 prompt-too-long 错误恢复。compact_boundary 之后 QueryEngine 还会 splice 掉边界前消息释放内存。这套机制的存在与精细程度，是"能交付的 agent"与"演示级 agent"的分水岭——后者通常只有"超长就截断"。代价是 queryLoop 成了 1700 余行的状态机。

主题四：启动性能被当成一等功能

cli.tsx 的 fast-path 按"成本递增"排序，--version 一条做到零模块加载（高频被 CI/包管理器探测）；main.tsx 顶部用 ES 模块求值顺序让 startMdmRawRead/startKeychainPrefetch 的子进程与 ~135ms 的 import 在墙钟上重叠（keychain 预热专门省掉两次顺序 security spawn 的 ~65ms）；OpenTelemetry 的 ~400KB 与 gRPC 的 ~700KB 全靠动态 import 推迟；startDeferredPrefetches 精确缝在首帧 render 之后。注释里甚至有具体省时数据。对一个每天被敲无数次的 CLI，这种偏执是合理的投资。

主题五：三层开关支撑灰度，但把死分支留给了代码

feature()（编译期 DCE）决定"代码进不进二进制"、GrowthBook（运行期）决定"功能对谁开"、Statsig 式动态配置决定"出事怎么秒级关"。KAIROS 是三层协作的样例：feature('KAIROS') 决定 assistant 子系统是否进 bundle，tengu_kairos gate 决定本会话是否启用，setKairosActive 再反馈给遥测富化。这套体系让数百万用户的灰度、A-B、成本调参、紧急熔断成为可能。但代价显著：feature('KAIROS') 散布 150 余处、TRANSCRIPT_CLASSIFIER 110 处，全是对外恒假、被 DCE 抹除却在源码里清晰可读的死分支；对应的 ant-only 模块整体从外部构建剥离，这也是还原树出现结构性缺口（如 src/assistant/gate.ts 缺失）的根因。

主题六：复杂度与跨平台是两处真实的张力

复杂度逼近上限。单文件动辄几千行（bashPermissions.ts 2621、messages.ts 5512、sessionStorage.ts 5105、auth.ts 2002），加上五套压缩、四 provider、七种 MCP 传输、四条子代理派生路径、三层开关——能在脑中装下全貌的人极少，新人上手成本高。很多设计是真实世界打磨出的补丁叠补丁（Windows mtime 假阳性回退、tree-sitter 影子模式、各种 GrowthBook kill-switch），是长寿产品的宿命而非缺陷，但它让代码不"漂亮"。
跨平台是二等公民。秘钥存储只有 macOS 走 Keychain，Linux/Windows 直接明文落 ~/.claude/.credentials.json（且留着 TODO: add libsecret、Windows 无 DPAPI/Credential Manager）。这是清晰可见的安全短板，也说明 macOS 之外的平台关照不足。

总评

从软件工程角度，这是一套把"和不可靠 LLM 协作"的每个现实难点都正面啃下的硬核实现：会话状态机、压缩工程、工具安全、缓存偏执、启动性能、终端渲染、远程驱动、多 agent 编排，几乎每一块都体现了"为真实用户在敌对输入与长会话下不崩"所需的工程量。它的优秀是被现实磨出来的，而非设计得漂亮；它的复杂度也诚实地反映了一个事实——做能用的 agent demo 很容易，做敢交付的 agent 要多一个数量级的工程。它既是范本，也是警示。

附录：还原真实性与缺口

真实性判定：真实的 source-map 还原，非 AI 仿造。 三类硬证据：

反编译指纹：解码内联 source map 得到带 import/JSDoc/类型注释的源文件，且含 React Compiler 编译形态（_c()、$[n] memo cache）——326 个 UI 文件呈此形态，是 post-compiler 代码经 source map 还原的铁证。
不可伪造的内部标识符：OAuth CLIENT_ID = 9d1c250a-...、数百 tengu_* 事件名、cch=00000 引用 bun-anthropic 的 Attestation.zig、指向服务端 renderer.py 与内部 issue 号的注释。
复核佐证：552 个文件携带可解码内联 map；git 仅 8 commit、降级层为作者后续人工层叠加于真实还原产物之上。

缺口分三类：

类型	表现	例子
私有/原生模块 shim	`shims/` 7 包提供降级实现	Chrome MCP / Computer Use（截图返空白 JPEG、输入 no-op）、`color-diff-napi`（Rust syntect+bat → highlight.js TS 移植）、`image-processor.node`（实为 13 字节 placeholder）
官方外部构建自带桩	发布包阶段即被替换的 `ant`-only 实现	`src/moreright/useMoreRight.tsx`（map 自述 “Stub for external builds”）、`src/assistant/*`（KAIROS DCE 剥离）、`MonitorTool`/`WorkflowTool` 的 `null` 桩、18 个内部命令的 74 字节统一桩
还原者人工补写	source map 无内容、作者补的占位	`agents-platform`（自述"无法从 source map 恢复"）、`query/transitions.ts`（退化为恒等函数，导致它导出的 `Terminal`/`Continue` 类型不存在、严格 typecheck 会失败）

实践结论：这份还原树对研究 Claude Code 内部实现价值很高（会话循环、工具权限、压缩策略、MCP/OAuth、Remote Control 协议、多 agent 编排都基本完整可读）；但不可当作可信赖的生产源码——依赖是镜像重建的、原生能力被 shim、类型层信息有缺失、且夹带大量 ant-only 死分支。

本系列由多 agent 工作流通读源码生成，各章 file:line 引用指向上述还原树。下一篇进入会话内核：启动链路、查询状态机与五套上下文压缩。