Anthropic AI 编程智能体的架构、模式与内部运作
Read online at claude-code-from-source.com
Note
本项目为 claude-code-from-source 的简体中文翻译版本。感谢原文作者 Alejandro Balderas 提供如此详尽且具启发性的研究与分析内容。
本项目纯粹用于教育目的。 不包含 Claude Code 的任何源码——一行都没有。所有代码块皆为原创伪代码，使用不同的变量名称，用以说明架构模式。目标是帮助工程师理解生产环境的 AI 智能体是如何构建的，而非复制或散布专有软件。
当 Anthropic 将 Claude Code 发布到 npm 时，.js.map 源码映射（Source Map）中包含了 sourcesContent 字段，内含完整的原始 TypeScript 源码。本书即是研究该架构后的成果，将其中的模式、取舍与设计决策提炼为任何工程师都能学习的技术叙事。
横跨 7 大篇章，共 18 个章节。 印刷版约 400 页。
每个章节都具备分层深度：为技术领导者设计的叙事主线、为实现者准备的深入剖析段落，以及结尾的**「实践应用」**区块——从中提取可迁移的模式，供你应用于自己的系统中。图表使用 Mermaid 绘制，可在 GitHub 上原生渲染。
- 正在构建智能体系统的资深工程师 —— 借鉴这些模式、理解其取舍、在自己的技术栈中实现
- 评估架构的技术领导者 —— 跟着叙事走，不必逐行阅读每个代码块
- 任何好奇生产环境 AI 工具实际如何运作的人 —— 深入引擎盖下探究
在智能体能思考之前，进程必须先存在。
| # | 章节 | 你将学到 |
|---|---|---|
| 1 | AI 智能体的架构 | 六大关键抽象、数据流、权限系统、构建系统 |
| 2 | 快速启动——启动引导管线 | 五阶段初始化、模块级 I/O 并行、信任边界 |
| 3 | 状态——双层架构 | 启动引导单例、AppState 存储、粘性闩锁、成本追踪 |
| 4 | 与 Claude 对话——API 层 | 多供应商客户端、提示缓存、流式传输、错误恢复 |
智能体的心跳：流式传输、行动、观察、重复。
| # | 章节 | 你将学到 |
|---|---|---|
| 5 | 智能体循环 | query.ts 深入剖析、四层压缩、错误恢复、token 预算 |
| 6 | 工具——从定义到执行 | 工具接口、14 步管线、权限系统 |
| 7 | 并行工具执行 | 分割算法、流式执行器、推测性执行 |
一个智能体很强大。多个智能体协同工作则能带来变革。
| # | 章节 | 你将学到 |
|---|---|---|
| 8 | 产生子智能体 | AgentTool、15 步 runAgent 生命周期、内置智能体类型 |
| 9 | 分叉智能体与提示缓存 | 字节级相同前缀技巧、缓存共享、成本优化 |
| 10 | 任务、协调与集群 | 任务状态机、协调者模式、集群消息传递 |
没有记忆的智能体会永远犯同样的错误。
| # | 章节 | 你将学到 |
|---|---|---|
| 11 | 记忆——跨对话学习 | 基于文件的记忆、四类分类法、LLM 召回、过期处理 |
| 12 | 可扩展性——技能与钩子 | 两阶段技能加载、生命周期钩子、快照安全性 |
用户看到的一切都通过这一层。
| # | 章节 | 你将学到 |
|---|---|---|
| 13 | 终端 UI | 自定义 Ink 分支、渲染管线、双缓冲、对象池 |
| 14 | 输入与交互 | 按键解析、按键绑定、组合键支持、Vim 模式 |
智能体的触及范围超越了 localhost。
| # | 章节 | 你将学到 |
|---|---|---|
| 15 | MCP——通用工具协议 | 八种传输方式、MCP OAuth、工具包装 |
| 16 | 远程控制与云端执行 | Bridge v1/v2、CCR、上游代理 |
让一切快到人类察觉不到背后的机制。
| # | 章节 | 你将学到 |
|---|---|---|
| 17 | 性能——每一毫秒和每一个 Token 都重要 | 启动、上下文窗口、提示缓存、渲染、搜索 |
| 18 | 结语——我们学到了什么 | 五个架构赌注、可迁移的知识、智能体的未来方向 |
如果你只读一个段落：
- AsyncGenerator 作为智能体循环 —— 产出 Messages、带类型的 Terminal 返回值、自然的背压与取消机制
- 推测性工具执行 —— 在模型流式传输期间就启动只读工具，无需等到响应完成
- 并行安全的批处理 —— 按安全性分区工具，读取并行执行，写入序列化
- 分叉智能体实现缓存共享 —— 并行子智能体共享字节相同的提示前缀，节省约 95% 的输入 token
- 四层上下文压缩 —— 裁剪、微压缩、折叠、自动压缩——每一层都比上一层更轻量
- 文件式记忆搭配 LLM 召回 —— Sonnet 侧查询选择相关记忆，而非关键字匹配
- 两阶段技能加载 —— 启动时仅加载前置数据，调用时才加载完整内容
- 粘性闩锁确保缓存稳定性 —— 一旦发送 beta 头部，就不再在会话中途取消
- 槽位保留 —— 默认 8K 输出上限，命中时升级到 64K（在 99% 的请求中节省上下文）
- 钩子配置快照 —— 启动时冻结，防止运行时注入攻击
源码从 npm 源码映射中提取。36 个 AI 智能体分四个阶段分析了近两千个 TypeScript 文件：
- 探索：6 个并行智能体读取了源码树中的每一个文件
- 分析：12 个智能体撰写了 494KB 的原始技术文档
- 写作：15 个智能体从零开始将所有内容重写为叙事章节
- 审阅与修订：3 位编辑审阅者产出 900 行反馈；3 个修订智能体应用了所有修正
整个过程——从源码提取到最终修订完成——大约耗时 6 小时。
本仓库不包含 Claude Code 的任何源码。 所有代码块皆为原创伪代码，使用不同的变量名称，用以说明架构模式。不包含任何专有提示文字、内部常量或精确的函数实现。本项目纯粹出于教育目的——帮助工程师理解生产环境 AI 编程智能体背后的设计模式。
「NO'REILLY」封面仅为戏仿/迷因，用于说明目的。本项目与 O'Reilly Media 无任何关联。那只螃蟹就只是一只螃蟹。
这是一份独立分析。Claude Code 是 Anthropic 的产品。本书与 Anthropic 无关联、未获其背书、亦未受其赞助。