前言

写作动机

2026 年，AI 编程助手从"玩具"变成了"生产力工具"。Cursor、Copilot、Windsurf 争相涌现，但它们大多是黑盒。你可以用它们写代码，却无法理解它们如何决定该调用哪个工具、如何管理上下文窗口、如何在安全和自由之间取得平衡。

2026 年 3 月，Claude Code 的完整源码通过 npm 分发包的 source map 意外泄露。51 万行 TypeScript 代码、40+ 工具、80+ 命令、完整的 MCP 协议集成、多 Agent 协调系统——一个生产级 AI 编程助手的内部实现第一次完整地暴露在开发者面前。

当我第一次读到这份源码时，我意识到：这可能是理解"AI Agent 系统应该如何设计"的最佳教材。不是因为它完美无缺，而是因为它是真正在生产环境中被数百万开发者使用的系统，每一个设计决策背后都有真实的工程权衡。

这本书讲什么

本书不是 Claude Code 的使用手册——官方文档已经做得很好了。

本书关注的是为什么：

• 为什么启动时要并行预读 Keychain 和 MDM 配置？
• 为什么工具执行用 async generator 而不是 Promise.all？
• 为什么权限系统要设计五种模式？
• 为什么 MCP 客户端代码有 12 万行？
• 为什么 IDE Bridge 要用 JWT 而不是简单的 token？

我们会从 main.tsx 的第一行开始，沿着代码的执行路径，逐层深入每一个子系统。每一章聚焦一个核心模块，先讲设计意图，再看代码实现，最后总结可迁移的设计模式。

本书读者

• AI 应用开发者：想构建自己的 Agent 系统，需要参考成熟的架构设计
• 前端/全栈工程师：对 React + Ink 终端 UI、TypeScript 大型项目架构感兴趣
• 框架设计者：想了解工具编排、权限模型、协议集成的最佳实践
• 技术爱好者：好奇"AI 编程助手的内部到底是什么样的"

本书的组织

全书分为七个部分，按照 Claude Code 的执行路径从外到内组织：

第一部分：启动与核心循环（第 2-5 章）——从 main.tsx 启动到 Agent 循环的完整链路。这是整个系统的骨架。

第二部分：工具系统（第 6-8 章）——40+ 工具的类型系统、编排引擎和核心实现。工具是 Agent 与世界交互的桥梁。

第三部分：权限与安全（第 9-10 章）——五级权限模型和 Bash 沙箱。这是 Claude Code 区别于"玩具 Agent"的关键。

第四部分：协议与集成（第 11-13 章）——MCP 协议、IDE Bridge、LSP。Claude Code 不是孤岛，它是一个生态系统的节点。

第五部分：Agent 进阶（第 14-16 章）——多 Agent 协调、Skill 插件、上下文压缩。这些是 Claude Code 的"高级技巧"。

第六部分：终端 UI 与工程实践（第 17-18 章）——React + Ink 终端 UI 的架构，以及贯穿全书的设计模式总结。

每章遵循 "设计意图 → 源码实现 → 可迁移模式" 的三段式结构。你可以按顺序阅读获得完整理解，也可以直接跳到感兴趣的章节——每章开头都有背景介绍。

阅读建议

建议将 Claude Code 源码 clone 到本地，边读边翻阅对应的源文件。本书所有代码引用都标注了文件路径和行号，你可以直接跳转到源码中验证。

git clone https://github.com/anthropics/claude-code.git

不需要能运行它——理解架构不依赖于运行环境。

源码版本

本书基于 Claude Code 2026.3.31 源码快照分析，对应通过 npm 分发包 source map 泄露的生产版本。由于 Claude Code 在持续迭代，部分代码细节可能与你看到的最新版本有差异，但核心架构设计相对稳定。

感谢 Anthropic 团队构建了 Claude Code 这样精妙的系统。本书的分析基于公开可获取的源码快照，仅用于教育和技术研究目的。