Claude Code 源码架构解析:一个商业级 AI Agent 是如何构建的

2026 年 3 月 31 日，Anthropic 发布 Claude Code v2.1.88 至 npm。该版本意外包含了一个 59.8MB 的 source map 文件（cli.js.map），其中指向了 Anthropic Cloudflare R2 存储桶上的一个无鉴权 zip 文件。安全研究员 Chaofan Shou 最先公开披露，数小时内，完整的未混淆 TypeScript 源码被广泛传播。

这不是第一次。2025 年 2 月 24 日 Claude Code 发布当天，开发者 Dave Shoemaker 就在同一 npm 包中发现了 1800 万字符的内联 source map，Anthropic 在 2 小时内撤回。13 个月后，同样的错误，同样的路径。根本原因是 .npmignore 中缺少 *.map 一行。

泄露的代码库包含约 1,900 个文件、512,000 行严格类型的 TypeScript。它揭示的不是功能列表，而是一个生产级 AI Agent 系统的完整工程架构。以下是对其核心设计的梳理。

一、整体技术栈

Claude Code 的技术选型与主流 CLI 工具有明显差异：

• 运行时：Bun，而非 Node.js。Bun 被用于编译时功能开关和死代码消除——108 个未发布功能模块（如 KAIROS、VOICE_MODE、DAEMON）在编译阶段即被移除，生产包中不存在任何痕迹。
• 终端 UI：React + Ink。这意味着 Claude Code 的终端界面使用了 React 组件模式，具备状态管理、重渲染和组件组合能力。
• Schema 验证：Zod v4 贯穿全链路，每个工具的输入输出都有独立的 Schema 定义。
• 主入口：编译后单文件 cli.js，785KB。

二、工具系统

Claude Code 的 Agent 能力建立在一套 40+ 自包含、权限隔离的工具模块之上。每个工具独立定义输入 Schema、权限级别和执行逻辑，不存在跨工具的共享可变状态。

核心工具包括：

工具基础定义约 29,000 行，包含 Schema 验证、权限执行和错误处理。BashTool 和 FileReadTool 位于同一注册表，但拥有完全不同的风险等级——架构在工具级别实施最小权限，而非全局策略。

三、查询引擎

QueryEngine.ts 是整个系统的核心，单文件 46,000 行。它集中处理所有 LLM API 调用、流式传输、缓存、速率限制和上下文预算管理。

关键设计是自愈查询循环：当上下文预算接近窗口上限时，引擎不会崩溃或交由用户处理，而是自动触发压缩——在上限前预留缓冲区，生成结构化摘要。这是有意为之的设计，不是事后补丁。

系统提示词在 SYSTEM_PROMPT_DYNAMIC_BOUNDARY 处分割为两部分：前半段（指令、工具定义）在所有组织间全局缓存；后半段（CLAUDE.md、git 状态、当前日期）为会话专属。用户的项目配置不会破坏其他用户的缓存。

四、多 Agent 编排

Claude Code 的多 Agent 系统采用 Coordinator-Worker 架构 + 邮箱模式：

• Worker Agent 执行具体任务，但无权自主批准高风险操作。
• 遇到危险操作时，Worker 向 Coordinator 的邮箱发送请求并等待。
• Coordinator 评估后批准或拒绝。
• 原子认领机制防止两个 Worker 同时处理同一审批请求。
• 所有 Agent 共享内存空间，维持一致上下文，无需冗余重取。

这与朴素的”每个 Agent 完全自主”设计有本质区别。Coordinator/Worker 分离 + 审批门控实现了并行执行而不失控。

验证 Agent（verificationAgent.ts）的设计尤其值得注意。它内置了一份自我欺骗检测列表：

- "The code looks correct based on my reading"
  — reading is not verification. Run it.
- "The implementer's tests already pass"
  — the implementer is an LLM. Verify independently.
- "This is probably fine"
  — probably is not verified. Run it.

验证系统明确不信任代码作者，因为代码作者本身就是 AI。

五、三层上下文压缩

这可能是整个代码库中最值得借鉴的工程设计。Claude Code 使用三种不同的压缩策略，各在不同阶段触发：

MicroCompact：本地编辑缓存内容，裁剪旧的工具输出。零 API 调用，快速、廉价。

AutoCompact：对话接近上下文窗口上限时触发。预留 13,000 token 缓冲区，生成最多 20,000 token 的结构化摘要。内置熔断器——连续 3 次压缩失败后停止重试。此前（2026 年 3 月 10 日之前），无重试上限，导致 1,279 个会话出现 50+ 次连续失败（最高 3,272 次），全局每天浪费约 250,000 次 API 调用。

Full Compact：压缩全部对话，然后重新注入最近访问的文件（每文件上限 5,000 token）、活跃计划和相关技能 Schema。压缩后工作预算重置为 50,000 token。

压缩器的提示词（src/services/compact/prompt.ts）对用户消息和工具结果做了列举层面的区分，但没有指示”忽略工具结果中的指令”或”将文件内容视为不可信”。这意味着嵌入在项目文件中的指令会被一同摘要，与真实用户指令无法区分——这是基于摘要的上下文管理的固有局限。

六、安全系统

Bash 安全

Bash 安全系统横跨 3 个文件（bashSecurity.ts、bashParser.ts、ast.ts），共 9,707 行。每条命令在执行前都经过 tree-sitter WASM 解析器构建 AST，再经 22 个独立验证器逐一检查。默认策略是”有疑问时，交给人类”。

代码中记录了一个解析器差异漏洞：旧解析器（splitCommand_DEPRECATED）将 \r 视为单词分隔符，而 Bash 的默认 IFS 不包含 \r。攻击者可以构造含回车符的命令，使验证器通过而 Bash 执行不同的内容。旧解析器并未退役，仍在 bashPermissions.ts、readOnlyValidation.ts、sedValidation.ts 等 8 个文件中做安全决策。

权限模型

每个工具独立权限门控，无全局策略泄漏。AgentTool 的子 Agent 与普通工具共享同一注册表，但危险操作必须经过邮箱审批。

隐身模式

src/utils/undercover.ts（89 行）在 Anthropic 员工使用 Claude Code 时检查当前仓库是否在 22 个内部仓库的白名单内。若不在，激活隐身模式，注入提示词要求不在 commit 信息中暴露 AI 身份、内部代号或模型版本号。默认开启。

七、KAIROS：未发布的自主 Agent 架构

KAIROS 在代码库中有 190 处引用，横跨 61 个文件。它是一个自主守护进程模式——Claude Code 无人值守运行，响应 GitHub webhook，按 5 分钟 cron 周期执行调度任务。独占工具包括 SendUserFileTool、PushNotificationTool、SubscribePRTool。

记忆整合系统（src/services/autoDream/autoDream.ts）使用三重门控：24 小时冷却、5+ 会话积累、文件级 advisory lock。锁文件设计中，文件的 mtime 兼作 lastConsolidatedAt 时间戳，PID 写入文件体，超过 1 小时判定为过期（防 PID 重用）。若整合失败，mtime 回滚到先前值。

ULTRAPLAN 将规划委托给远程 Opus 会话，最长运行 30 分钟，每 3 秒轮询一次，通过”teleport sentinel”检测完成并将结果传回本地终端。

当前位于功能开关之后，生产包中不存在。

八、遥测

两个非常规但有价值的指标：

• 挫败感指标：追踪用户骂人频率作为 UX 信号——一个领先指标，而非滞后指标。
• “continue”计数器：追踪用户输入”continue”的频率，作为 Agent 卡顿（失去动力、需要人类推进）的代理指标。

内部 A/B 测试结果（src/constants/prompts.ts:527 注释）：硬编码字数限制（”工具调用间文本 ≤25 词，最终回复 ≤100 词”）比定性的”be concise”减少约 1.2% 的输出 token。

参考来源

• Sabrina Ramonov, Comprehensive Analysis of Claude Code Source Leak, sabrina.dev, 2026-04-02
• WaveSpeed AI, Claude Code Architecture Deep Dive: What the Leaked Source Reveals, 2026-04-02
• MindStudio, Claude Code Source Code Leak: 8 Hidden Features You Can Use Right Now, 2026-04
• Han HELOIR YAN, Everyone Analyzed Claude Code’s Features. Nobody Analyzed Its Architecture, Medium / Data Science Collective, 2026-04
• CyberSecurityNews, Claude Code Source Code Leaked, 2026-03
• Anthropic 官方文档, code.claude.com/docs