Anthropic Claude Code 源码架构深度解析:构建 AI 编程代理的核心工程实践
Claude Code 是 Anthropic 推出的 AI 编程助手,能够在终端中自主完成文件读取、代码修改和命令执行等复杂任务。基于其 v2.1.88 版本的反编译源码分析显示,该系统采用 Bun 作为运行时,结合 TypeScript、React(Ink 渲染)以及 MCP 协议,构建了一套高度工程化的 AI 代理架构。其核心设计涵盖统一流式接口、分层安全机制、精细的上下文管理及缓存优化策略,为构建高性能 AI 编程工具提供了重要的技术参考。
| 技术层次 | 技术选型 | 核心作用 |
|---|---|---|
| 运行时 | Bun | 提供更快的启动速度与编译期 Dead Code Elimination |
| 开发语言 | TypeScript | 保证类型安全与代码可维护性 |
| UI 渲染 | React + Ink | 实现终端内的交互式界面渲染 |
| Schema 验证 | Zod v4 | 确保数据结构的安全校验 |
| 扩展协议 | MCP | 实现 Model Context Protocol 标准化扩展 |
| 打包工具 | esbuild | 高效的代码打包与构建 |
Claude Code 技术栈概览
系统在整体架构上分为五层,底层通过手写的 mini-Redux 管理约 250 个字段的单一状态对象(AppState),向上依次支撑服务层、工具执行层、会话引擎层和用户交互层。这种分层设计确保了逻辑的清晰隔离,同时支持 REPL 交互模式与 Headless SDK 模式的核心逻辑复用,两者在进入 QueryEngine 后共用同一套处理流程。
01核心主循环:AsyncGenerator 驱动的状态机
系统的核心文件 query.ts 实现了一个基于 AsyncGenerator 的统一数据流接口。通过 `async function*` 定义,系统能够将 API 调用、模型输出和工具执行统一为一个流式管道。这种设计天然支持流式输出,允许模型每产生一个 token 就立刻 yield 给上层,同时利用背压机制自然控制生产消费速率,有效防止内存溢出。多层 generator 可以通过 `yield*` 无缝组合,使得子 Agent 的输出能直接穿透至顶层,实现透明的层级调用。
- 上下文压缩管道
按优先级依次执行:应用工具结果预算(将超大结果写磁盘)、历史裁剪、微压缩(折叠已完成的工具调用)、上下文折叠及自动压缩(超出窗口时生成摘要)。 - 调用模型 API
通过流式 SSE 获取消息,并实时 yield 给上层展示。 - 工具执行编排
依据并发安全性将工具调用分组:并发组最多 10 个工具并行运行,串行组强制按顺序执行写操作。 - 循环控制
根据是否存在 tool_use block 或是否达到 maxTurns 决定继续下一轮或结束循环。
02工具系统:安全优先的并发编排
Claude Code 内置了 60+ 个工具,涵盖文件操作、代码搜索、Shell 执行及 Agent 调度等。所有工具均实现统一的 Tool 接口,核心设计遵循“Fail-Closed”安全原则。默认情况下,工具被设定为非并发安全、非只读且具有破坏性潜质,开发者必须显式声明工具的安全性属性。这种默认保守策略大幅降低了误操作风险。在执行层面,工具编排器通过 partitionToolCalls() 将调用划分为并发组和串行组,并发工具的上下文修改会在整组执行完毕后统一合并,以防止竞态条件。
03上下文管理:五层递进式压缩机制
为应对长对话导致的 Token 溢出问题,系统实现了按代价从低到高排列的五层压缩机制。这种多级策略确保了在不调用 API 的情况下尽可能保留上下文信息。
五层压缩策略详解
低成本策略
无 API 调用,本地处理
- 工具结果预算:超过阈值的工具结果写入磁盘,原位替换为文件引用,对模型透明。
- 历史裁剪:直接删除最早的历史记录,保留受保护的尾部对话。
- 微压缩:将已完成的 tool_use 和 tool_result 对折叠为一条摘要消息。
高成本策略
涉及 API 调用或复杂计算
- 上下文折叠:识别重复段落(如多次读取同一文件)并替换为投影式摘要,原始数据保留可展开。
- 自动压缩:当 Token 数接近窗口上限时,Fork 子 Agent 生成摘要替换历史。设有连续失败 3 次的熔断机制。
04Prompt Cache:精细化的缓存工程化
系统通过多层机制最大化 Prompt Cache 命中率,以降低延迟和成本。System Prompt 被切分为最多 4 个块,其中静态内容(如工具说明)配置为 'global' scope 实现跨用户共享,而动态内容(如 git status)则不缓存。此外,工具 Schema 在 Session 开始时计算并锁定,防止因 A/B 测试配置翻转导致缓存失效。
- Beta Header 粘性锁定:Fast Mode、Auto Mode 等 beta header 在 Session 内首次发送后持续发送,避免因变动改变 cache key。
- TTL 资格锁定:是否启用 1 小时 TTL 的判断在初始化时锁定,防止 mid-session 用量状态翻转破坏缓存。
- 单点 Cache Break:每次 API 请求仅在最后一条消息上打 cache_control 标记,防止中间 KV pages 无法释放。
- Cache Break 监测:系统自动对比调用前后的快照,若 cache_read_input_tokens 下降显著则判定为缓存意外失效并生成 diff 报告。
05特色工程设计:编译期开关与 Agent 隔离
该工程采用了独特的 Feature Flag 机制,利用 bun:bundle 的 feature() API 在编译时求值。esbuild 在打包时会彻底删除 false 分支的代码,从而实现同一份源码通过不同构建配置生成功能差异化的内外部版本。所有 Flag 均使用 tengu_ 前缀加随机词对命名,以防止功能泄露。
在 Agent 架构方面,系统支持递归调用。主 Agent 可通过 AgentTool 启动子 Agent,子 Agent 拥有独立的上下文沙箱(createSubagentContext)。关键的安全隔离设计在于,子 Agent 的 setAppState 被定义为 no-op,使其无法修改父级状态,从而保证了并发安全。同时,所有层级共用同一个 query() 核心函数,兼顾了代码复用与逻辑一致性。
当前文章无评论,是时候发表评论了