Anthropic 的 AI 编码代理：架构、模式与内部机制
在线阅读 claude-code-from-source.com
本仓库仅用于教学。 它不包含 Claude Code 的任何源代码，哪怕一行也没有。所有代码块都是原创伪代码，用来说明架构模式。目标是帮助工程师理解生产级 AI 代理是如何构建的，而不是复制或传播专有软件。
当 Anthropic 在 npm 上发布 Claude Code 时，.js.map 源码映射里包含了 sourcesContent 字段，其中带有完整的原始 TypeScript。此书正是基于这些内容，对其架构进行研究后，把其中的模式、取舍和设计决策提炼成一套任何工程师都能学习的技术叙述。
全书共 18 章，分为 7 个部分。 印刷等价约 400 页。
每一章都有分层深度：面向技术负责人的叙述主线、面向实现者的深挖部分，以及一个 “应用到实践中” 的结尾，用来提炼可迁移的模式，方便你直接拿去改造自己的系统。图示使用 Mermaid 绘制，并可在 GitHub 上原生渲染。
- 构建 agentic 系统的资深工程师 - 借鉴这些模式，理解取舍，并在自己的技术栈里实现
- 评估架构的技术负责人 - 即使不看每段代码，也能跟着叙事理解全貌
- 任何想了解生产级 AI 工具底层如何运作的人
在代理开始思考之前，进程必须先存在。
| # | 章节 | 你将学到什么 |
|---|---|---|
| 1 | AI 代理的架构 | 6 个关键抽象、数据流、权限系统、构建系统 |
| 2 | 快速启动 - 引导管线 | 5 阶段初始化、模块级 I/O 并行、信任边界 |
| 3 | 状态 - 双层架构 | 引导单例、AppState 存储、粘性锁存器、成本跟踪 |
| 4 | 与 Claude 对话 - API 层 | 多提供方客户端、提示缓存、流式传输、错误恢复 |
代理的心跳：流式输出、执行、观察、重复。
| # | 章节 | 你将学到什么 |
|---|---|---|
| 5 | 代理循环 | query.ts 深挖、4 层压缩、错误恢复、token 预算 |
| 6 | 工具 - 从定义到执行 | Tool 接口、14 步管线、权限系统 |
| 7 | 并发工具执行 | 分区算法、流式执行器、投机执行 |
一个代理很强大。多个代理协同工作，则会产生变革性效果。
| # | 章节 | 你将学到什么 |
|---|---|---|
| 8 | 生成子代理 | AgentTool、15 步 runAgent 生命周期、内置代理类型 |
| 9 | Fork 代理与提示缓存 | 字节级相同前缀技巧、缓存共享、成本优化 |
| 10 | 任务、协调与群体 | 任务状态机、协调器模式、群体消息传递 |
没有记忆的代理，会永远重复同样的错误。
| # | 章节 | 你将学到什么 |
|---|---|---|
| 11 | 记忆 - 跨会话学习 | 基于文件的记忆、4 类分类法、LLM 回忆、陈旧性 |
| 12 | 可扩展性 - Skills 与 Hooks | 两阶段技能加载、生命周期 hooks、快照安全 |
用户看到的一切，都要经过这一层。
| # | 章节 | 你将学到什么 |
|---|---|---|
| 13 | 终端 UI | 自定义 Ink 分支、渲染管线、双缓冲、对象池 |
| 14 | 输入与交互 | 按键解析、快捷键、组合键支持、vim 模式 |
代理触及的不只是 localhost。
| # | 章节 | 你将学到什么 |
|---|---|---|
| 15 | MCP - 通用工具协议 | 8 种传输、MCP 的 OAuth、工具包装 |
| 16 | 远程控制与云端执行 | Bridge v1/v2、CCR、上游代理 |
要把一切加速到足以让人感觉不到机器。
| # | 章节 | 你将学到什么 |
|---|---|---|
| 17 | 性能 - 每一毫秒和每一个 token 都重要 | 启动、上下文窗口、提示缓存、渲染、搜索 |
| 18 | 尾声 - 我们学到了什么 | 5 个架构赌注、哪些能迁移、代理正在走向何方 |
如果你只读这一节：
- 把 AsyncGenerator 作为代理循环 - 产出 Messages，返回类型是 Terminal，天然支持背压和取消
- 投机式工具执行 - 在模型流式输出期间就启动只读工具，不必等响应结束
- 并发安全批处理 - 按安全性对工具分区，读取并行执行，写入串行执行
- 用 fork 代理共享缓存 - 并行子代理共享字节级相同的提示前缀，节省约 95% 的输入 token
- 4 层上下文压缩 - snip、microcompact、collapse、autocompact，层层递进
- 带 LLM 回忆的文件式记忆 - Sonnet 侧向查询选择相关记忆，而不是做关键词匹配
- 两阶段技能加载 - 启动时只加载 frontmatter，调用时再加载完整内容
- 用粘性锁存器保持缓存稳定 - 一旦发送过 beta header，就不要在会话中途取消
- 槽位预留 - 默认 8K 输出上限，命中后提升到 64K（在 99% 的请求里节省上下文）
- Hooks 配置快照 - 启动时冻结，防止运行时注入攻击
源码是从 npm 源码映射中提取的。36 个 AI 代理分四个阶段分析了近两千个 TypeScript 文件：
- 探索：6 个并行代理阅读了源码树中的每一个文件
- 分析：12 个代理写出了 494KB 的原始技术文档
- 写作：15 个代理把所有内容重写成叙述性章节
- 审校与修订：3 位编辑审校者提出了 900 行反馈；3 个修订代理完成了全部修改
从源码提取到最终修订版成书，整个过程大约耗时 6 小时。
本仓库不包含 Claude Code 的任何源代码。 所有代码块都是原创伪代码，使用了不同的变量名，用来说明架构模式。未包含任何专有提示词、内部常量或精确函数实现。这个项目完全出于教学目的，帮助工程师理解生产级 AI 编码代理背后的设计模式。
“NO'REILLY” 封面只是一个用于说明的恶搞/梗图，与真实的 O'Reilly Media 无关。这个项目与 O'Reilly Media 没有任何关联。那只螃蟹就是一只螃蟹。
这是一份独立分析。Claude Code 是 Anthropic 的产品。本书与 Anthropic 无关联，也未获其认可或赞助。