深度揭秘Claude Code架构：51万行源码背后的AI Agent工程实践

今天（2026年3月31日），Anthropic再次因为打包流程的低级失误，将其最新版Claude Code（v2.1.88）的完整前端与客户端源码暴露在了npm仓库中。继前几天Mythos模型文档外泄后的又一次严重OpSec事故。

但对于整个大模型应用层的开发者和行业研究者来说，这份源码是一份毫无保留的、价值极高的前沿AI Agent工程架构白皮书。

以下是对Claude Code底层架构、调度机制、记忆系统及安全策略的详细技术拆解。

一、不仅仅是一个CLI工具

从目录结构（src/下约40个一级模块）可以看出，Claude Code的复杂度远超目前市面上开源的常规单体Agent。

技术栈选型

• 语言：TypeScript
• 运行时：Bun（性能更激进）
• CLI框架：Commander
• 终端渲染：React + Ink（出人意料的选择）

为什么一个命令行工具要用React？

源码中的screens/REPL.tsx（高达5005行）给出了答案：在大模型流式输出（Streaming）和多工具并发执行的场景下，终端UI的状态管理变得极其复杂。采用声明式的React配合极简的Zustand风格自定义Store，是应对这种高频局部刷新的最佳工程实践。

两种运行形态

• 交互式REPL模式：通过Ink驱动前端终端UI，主要面向人类开发者
• 无头/SDK模式：完全剥离UI，支持JSON流式输出，为嵌入IDE或CI/CD流程埋下伏笔

二、Prompt Cache工程学

这是整份源码中最具技术含量的部分。

分段缓存架构

Anthropic的Prompt Cache机制采用前缀匹配（Prefix Matching）。Claude Code设计了严密的分段缓存架构：

• 静态段（全局可缓存）：包含模型身份介绍、安全规则、代码风格限制、工具使用基础指南
• 动态分界线：硬编码了特殊标记SYSTEM_PROMPT_DYNAMIC_BOUNDARY
• 动态段（会话级缓存/不缓存）：包含CWD、Git状态、MCP指令、用户配置等高频变化数据

防止缓存穿透的兜底工作

• 确定性排序：工具描述严格按字母表排序
• 哈希路径映射：配置文件路径使用基于内容的哈希值，避免每次注入路径不同破坏缓存
• 状态外置：Agent列表被从工具描述中剥离，转移到了消息附件（Attachments）中

仅状态外置这一项，就减少了约10.2%的Cache Creation Tokens消耗。

三、Tools与流式并发执行

Claude Code内置了超过40种工具，其工具系统架构采用高度模块化的工厂模式（Factory Pattern）。

按需加载的ToolSearch机制

当工具数量超过阈值时，非核心工具被标记为defer_loading: true。模型在当前Prompt中看不到这些工具的具体定义，只知道有一个ToolSearch工具。当模型认为自己需要额外能力时，必须先调用ToolSearch去动态加载。

StreamingToolExecutor

• 协调器（toolOrchestration.ts）将工具调用请求分区为并发批次和串行批次
• 并发安全的工具（如同时读取多个不相关文件）被并行触发
• 非并发安全的工具（如先后修改同一个代码文件）则严格串行
• 超大结果集设有maxResultSizeChars预算，防止撑爆上下文窗口

四、解决上下文污染的Fork机制

单体Agent存在一个致命缺陷：试错过程会产生大量垃圾上下文，迅速污染主对话。

Coordinator-Workers架构

• Coordinator（协调者）：剥夺了直接操作文件的权限，只保留Agent、SendMessage、TaskStop三个工具
• Workers（执行者）：携带具体工具描述被派生出来

Fork继承机制

当需要进行大范围代码探索时，Coordinator会Fork出Explore Agent。这个子Agent会继承父对话的缓存（共享Prompt Cache以节约成本），但其探索动作完全在隔离的上下文中进行。探索结束后，只通过XML格式<task-notification>将提炼好的关键结论传回给Coordinator。

五、Agent Swarm并发机制

源码展示了更具野心的并发多Agent架构——Swarm（Teammate）集群。

in_process_teammate

主进程可以平行唤醒多个Agent同时执行不同任务。Anthropic的解法极为优雅：

• Leader权限桥接：所有Teammate子进程都不允许直接向用户弹窗请求权限，统一由Leader处理
• 终端布局自动化：集成了iTerm2和Terminal.app的AppleScript控制指令，自动切分窗格为每个子Agent分配独立输出视窗

六、Dream记忆架构

令人意外的是，Claude Code的记忆系统（memdir/模块）极其复古且务实，完全基于本地文件系统。

KAIROS助手模式

这是一个尚未正式发布的长期运行（Daemon）模式。在KAIROS模式下：

• 记忆系统采用类似人类日志的追加模式（写入logs/YYYY/MM/YYYY-MM-DD.md）
• 到了夜间或闲置时间，后台会唤醒名为Dream（做梦）的离线任务Agent
• 这个Agent负责对白天的流水账日志进行总结、蒸馏，提取固化到结构化的长期主题文件中

这种从短期日志到长期记忆的异步整合机制，绕开了向量检索的召回率痛点。

七、权限收敛与安全

Claude Code采用了一套多层权限收敛架构：

• 文件/网络沙箱
• 危险操作（如git push –force）的硬编码拦截
• 工具级别的校验

Auto Mode Classifier

当用户开启自动模式时，系统使用了一个侧查询（Side Query）机制：后台静默调用一个更小、更便宜的LLM，让它输出Allow或Deny的决策。这种”用小AI监管大AI”的动态权限系统，比传统的静态拦截规则要灵活得多。

八、一些小彩蛋

卧底模式（Undercover Mode）

针对员工在开源或公共仓库工作的场景，系统默认开启且无法强制关闭。要求模型Do not blow your cover，并强制剥离所有由AI生成的免责声明或代号痕迹。

Buddy System（电子宠物）

源码中包含了一个隐藏的电子宠物系统：

// 18种物种: duck, goose, blob, cat, dragon, octopus, owl, penguin...
// 5种稀有度: common(60%), uncommon(25%), rare(10%), epic(4%), legendary(1%)
// 属性: DEBUGGING, PATIENCE, CHAOS, WISDOM, SNARK
// 配件: crown, tophat, propeller, halo, wizard, beanie, tinyduck
// 1%概率shiny

九、我们能学到什么？

从Claude Code的底层设计可以看出：

• 大模型应用层创业，单纯依靠拼凑Prompt、堆砌向量数据库的时代已经结束
• 真正的壁垒建立在Token成本的极致抠门（Prompt Cache优化）
• 对多状态机协同的流式调度（Coordinator与Fork机制）
• 对用户意图容错与安全干预的平衡（YOLO Classifier）
• 对宿主操作系统深度的文件流集成

Claude Code展示出的工程化水平，已经为2026年的AI助理产品树立了一个全新的技术标杆。

相关阅读：

• Claude Code源代码意外泄露事件
• 国内AI大模型Coding Plan对比
• Claude Code突然开源