Claude Code 源码深度解析
前言
写作动机
2026 年，AI 编程助手从"玩具"变成了"生产力工具"。Cursor、Copilot、Windsurf 等产品竞相迭代，但它们大多是黑盒。你可以用它们写代码，却无法理解它们如何决定该调用哪个工具、如何管理上下文窗口、如何在安全和自由之间取得平衡。
2026 年 3 月 31 日前后，Claude Code 的完整源码通过 npm 分发包 2.1.88 里的 source map 意外泄露。51 万行 TypeScript 代码（整仓含测试口径，详见第 1 章）、40+ 工具、80+ 命令、完整的 MCP 协议集成、多 Agent 协调系统——一个生产级 AI 编程助手的内部实现第一次完整地暴露在开发者面前。
当我第一次读到这份源码时，我意识到：这可能是理解"AI Agent 系统应该如何设计"的最佳教材。不是因为它完美无缺，而是因为它是真正在生产环境中被大量开发者日常使用的系统，每一个设计决策背后都有真实的工程权衡。
这个专栏讲什么
本专栏不是 Claude Code 的使用手册——官方文档已经做得很好了。
本专栏关注的是为什么：
- 为什么启动时要并行预读 Keychain 和 MDM 配置？
- 为什么工具执行用 async generator 而不是 Promise.all？
- 为什么权限系统要设计七种模式？
- 为什么一个 MCP 客户端要写到约 25 个文件、超过 40 万字符？
- 为什么 Remote Control 桥接的 JWT 要在过期前主动续期？
我们会从入口 cli.tsx 和 main.tsx 的第一行开始，沿着代码的执行路径，逐层深入每一个子系统。每一章聚焦一个核心模块，先讲设计意图，再看代码实现，最后总结可迁移的设计模式。
本专栏读者
- AI 应用开发者：想构建自己的 Agent 系统，需要参考成熟的架构设计
- 前端/全栈工程师：对 React + Ink 终端 UI、TypeScript 大型项目架构感兴趣
- 框架设计者：想了解工具编排、权限模型、协议集成的最佳实践
- 技术爱好者：好奇"AI 编程助手的内部到底是什么样的"
本专栏的组织
本专栏分为七个部分，按照 Claude Code 的执行路径从外到内组织：
第一部分：开篇（第 1 章）——Claude Code 解决的是什么问题，以及为什么值得读它的实现。
第二部分：启动与核心循环（第 2-5 章）——从 main.tsx 启动到 Agent 循环的完整链路。这是整个系统的骨架。
第三部分：工具系统（第 6-8 章）——40+ 工具的类型系统、编排引擎和核心实现。工具是 Agent 与世界交互的桥梁。
第四部分：权限与安全（第 9-10 章）——七种模式的权限模型和 Bash 沙箱。这是 Claude Code 区别于"玩具 Agent"的关键。
第五部分：协议与集成（第 11-13 章）——MCP 协议、Remote Control 桥接、LSP。Claude Code 不是孤岛，它是一个生态系统的节点。
第六部分：Agent 进阶（第 14-16 章）——多 Agent 协调、Skill 插件、上下文压缩。这些是 Claude Code 的"高级技巧"。
第七部分：终端 UI 与工程实践（第 17-18 章）——React + Ink 终端 UI 的架构，以及贯穿本专栏的设计模式总结。
各章大体遵循 "设计意图 → 源码实现 → 可迁移模式" 的三段式结构。你可以按顺序阅读获得完整理解，也可以直接跳到感兴趣的章节——每章开头都有背景介绍。
源码版本与获取方式
本专栏基于 Claude Code 2026.3.31 源码快照分析，对应 npm 包
@anthropic-ai/claude-code@2.1.88（2026-03-30 22:36 UTC 发布，即北京时间 3 月 31 日）
随包分发的 source map（cli.js.map）所还原出的 TypeScript 源码树。这个版本随后从 npm
下架，下一版 2.1.89（2026-03-31 23:32 UTC 发布）起不再带 source map。
先把话说清楚：这份源码今天已经拿不到了
这个专栏必须在开头交代清楚，否则你会白白浪费时间去找：
1. github.com/anthropics/claude-code 里没有本专栏剖析的产品源码。
那个仓库是 Claude Code 的 issue 跟踪、文档、示例与插件仓库，内容是 CHANGELOG.md、
README.md、examples/、plugins/、.claude-plugin/ 和几个 issue 运维脚本；
2026-09-09 起又多了一个 mods/ 目录，放的是几个内置 hooks 插件的 TypeScript 源码，
对应当前版本，不是本专栏讲的核心代码（截至 2026-09-25 实测共 1434 个文件，其中
mods/ 占 1203 个）。它不包含 src/，更没有 main.tsx。clone 它对照本专栏，
一行都对不上。
2. npm 上也已经拿不到 source map 了。
2.1.88 已从 npm 下架，按版本号查询返回 404。相邻的 2.1.89 可以拉下来解开自己验证：整包只有 19 个文件，
主体是一个 13MB、16824 行的压缩后 cli.js，外加 vendor 目录下的 ripgrep 与
audio-capture 二进制。没有任何 .map 文件，cli.js 末尾也没有
sourceMappingURL 注释：
npm view @anthropic-ai/claude-code@2.1.88 version # E404：已下架
curl -sSL $(npm view @anthropic-ai/claude-code@2.1.89 dist.tarball) -o cc.tgz
tar tzf cc.tgz # 19 个文件
tar xzf cc.tgz package/cli.js
grep -c sourceMappingURL package/cli.js # 0所以本专栏的定位是：替你读过源码。 本专栏的代码引用都标注了文件路径（部分还给出行号）， 它们指向的是上述快照的目录结构，用于说明"这段逻辑在系统里的位置"， 而不是让你去 clone 一份对照——那条路今天走不通，本专栏不会假装它走得通。
那么怎么读这个专栏才有效？
- 主线：跟着正文引用的代码片段读。所有关键实现本专栏都直接给出了源码， 不需要你手上有完整仓库。
- 想验证行为：装一个当前版本的 Claude Code，用它跑一遍正文描述的流程。 架构级的设计——工具编排、权限分级、上下文压缩、MCP 集成——从 2026.3 至今 大体稳定，多数行为可以复现；具体细节以你手上的版本为准。
- 想看真实产物：解包上面那个
cli.js。它是压缩后的单文件，读不了原始结构， 但工具名、命令名、提示词模板、错误文案这些字符串都还在里面，可以用来交叉印证 本专栏对工具集与命令集的描述。 - 官方文档：https://code.claude.com/docs/en/overview 是行为与配置的权威来源， 与本专栏的"内部实现"视角互补。
由于 Claude Code 在持续迭代（截至 2026-09-25，npm registry 上已列出 524 个版本）， 部分代码细节必然与最新版本有差异，但核心架构设计相对稳定。凡是本专栏能确认已经变化的地方， 相应章节都会给出说明。
代码引用的约定
正因为你无法自己 clone 一份对照，本专栏更有义务把引用规则讲清楚。正文里代码块顶部的标注：
// 源码文件：src/Tool.ts指的是该逻辑在上述快照目录结构中的位置。关于这些代码块：
它们是节选，不是原文粘贴。 为了让主干逻辑读得完，正文通常会删去完整的泛型与 类型参数、省略防御性分支与遥测调用、把多行签名压成一行，并补上中文注释。
但常量的值、报错信息的文本、字段名与方法名，一律按原文引用。 这些是理解系统行为的 锚点，改写它们等于制造错误答案。
还有一点必须坦白：本专栏的代码引用无法由读者独立复核——原因见上面那个警告框。
因此凡是能在公开渠道交叉印证的地方，本专栏都会尽量给出印证路径，例如工具名与命令名
可以在 npm 包的 cli.js 里 grep 到，权限与配置行为可以用当前版本的 Claude Code
实际跑一遍。读到与你的观察不一致的地方，请以你的观察为准，并欢迎反馈。
感谢 Anthropic 团队构建了 Claude Code 这样精妙的系统。本专栏的分析基于曾经公开流出的源码快照，仅用于教育和技术研究目的。