这是「Claude Code 代码全景解析」专题的第 01 篇。在本系列中，我们将逐层拆解 Anthropic 官方 AI 编程助手 Claude Code 的完整源码，从终端渲染到多 Agent 编排，从 Tool 系统设计到 MCP 生态集成，带你一览当前工业级 AI Agent 的工程全貌。
一、泄露事件背景
1.1 发现过程
2026 年 3 月 31 日，安全研究员 Chaofan Shou（@Fried_rice） 在 Twitter/X 上发布了一条令人震惊的消息：Anthropic 官方 CLI 工具 Claude Code 的完整源码，竟然完整地躺在 npm 仓库的公开包中。消息一经发出，迅速在技术圈引发轩然大波。
这不是传统的「服务器被黑」或「内部人员泄密」，而是一次极其隐蔽、却因为一个常见的构建配置疏忽所导致的供应链泄露。
1.2 npm Sourcemap 泄露机制
问题的根源在于 JavaScript Source Map（.map 文件）。
现代前端/Node.js 项目在构建 TypeScript 或打包 JavaScript 时，工具链（如 Webpack、Vite、Bun）会生成 .map 文件，用于将压缩后的生产代码映射回原始源码，方便调试。这些 .map 文件本质上是一个 JSON，其中有一个关键字段叫 sourcesContent——它直接内嵌了所有原始源文件的完整文本内容。
{
"version": 3,
"sources": ["../src/main.tsx", "../src/QueryEngine.ts", "..."],
"sourcesContent": [
"// 完整的原始源码内容...",
"..."
],
"mappings": "AAAA,SAAS,OAAO..."
}正常情况下，发布到 npm 的生产包应该：
- 在
.npmignore中排除*.map；或 - 在构建配置中禁用 sourcemap 生成。
但 Claude Code 的发布流程中遗漏了这一步。使用 Bun 构建时，sourcemap 默认开启，且未被忽略，于是整个 src/ 目录的 2000 多个源文件被原封不动地打包进了 npm 包。任何人只需要下载 npm 包、解压、查看 .map 文件，就能拿到完整的 TypeScript 源码。
1.3 事件时间线
flowchart LR
A[2026-03-31
Chaofan Shou 发现] --> B[推文传播
技术圈震动]
B --> C[社区备份
GitHub 镜像仓库]
C --> D[Anthropic 撤包
修复构建配置]
D --> E[社区持续分析
架构解读与复现]目前，社区维护的备份仓库地址为：
https://github.com/yasasbanukaofficial/claude-code该仓库大小约 9.7 MB，包含 2200+ 个源文件，Star 数已突破 2600+，足见开发者对这份源码的关注度。
二、源码性质与边界
在深入阅读之前，必须清醒地认识这份源码的性质和局限性。它不是一份官方开源项目，而是一次「意外的快照」。
2.1 这不是官方开源
- 无开源许可证：仓库本身没有附带 OSI 认可的开源协议，Anthropic 也从未声明将其开源。
- 还原性质：社区仓库是基于 npm sourcemap 还原出的源码快照，文件结构、命名、注释均保持原始状态，但无法保证 100% 完整无损。
- 无持续维护：官方不会对这个仓库提供任何更新、补丁或技术支持。
2.2 适合做什么
尽管不是正式开源，这份源码仍然是当前工业级 AI Agent 工程实现的绝佳学习材料：
| 适用场景 | 说明 |
|---|---|
| 架构学习 | 学习如何将 LLM、Tool 系统、终端 UI、多 Agent 编排整合为一个 CLI 产品 |
| 工程借鉴 | 参考其目录组织、模块拆分、错误处理、状态管理等工程实践 |
| 协议研究 | 深入理解 Claude Code 如何实现 MCP（Model Context Protocol）客户端 |
| 交互设计 | 研究其基于 React + Ink 的终端渲染方案，以及如何设计人机协作的交互流程 |
| 安全分析 | 了解其对权限控制、命令沙箱、敏感信息过滤的实现思路 |
2.3 不适合做什么
| 不适用场景 | 说明 |
|---|---|
| 直接复刻商用 | 法律风险高，且缺少官方后端 API 支持 |
| 指望 100% 可运行 | 缺少私有配置、后端服务、模型密钥等，本地无法直接启动完整功能 |
| 获取私有后端逻辑 | 源码主要是 CLI 侧逻辑，Anthropic 的服务器端推理、模型调度、数据存储等不在其中 |
| 追踪最新版本 | 泄露的是某一历史版本的快照，后续官方版本的改动无法从该仓库获知 |
一句话总结：把它当作一本「活的架构参考书」，而不是一个可以直接 fork 跑起来的开源项目。
三、代码库概览
3.1 规模与体量
# 仓库统计
总大小：约 9.7 MB
src/ 下源文件：2200+ 个
核心入口 main.tsx：803 KB（单文件！）
QueryEngine.ts：46 KB
Tool.ts：29 KB值得注意的是，main.tsx 这个单文件达到了 803 KB。在现代前端工程中，如此庞大的入口文件极其罕见。这说明 Claude Code 的主入口承担了大量初始化逻辑——从命令行参数解析、配置加载、OAuth 认证、MCP 预取、到 React/Ink 终端渲染的启动，全部集中于此。这种「重入口」设计在 CLI 工具中并不多见，也为我们后续分析其启动流程提供了丰富的素材。
3.2 核心目录结构
src/
├── main.tsx # CLI 入口：Commander.js + React/Ink 终端渲染
├── QueryEngine.ts # 核心 LLM 查询引擎：管理对话循环、Tool 调用
├── Tool.ts # Tool 抽象基类与类型定义
├── tools/ # 40+ 内置 Tool 实现（Bash、File、LSP、Web 等）
├── services/ # 业务服务层（MCP、API、策略限制、远程配置等）
├── components/ # React/Ink 终端 UI 组件（439 个文件）
├── utils/ # 工具函数（599 个文件，规模最大）
├── commands/ # 斜杠命令系统（293 个文件）
├── hooks/ # React Hooks（107 个文件）
├── ink/ # 终端渲染底层（101 个文件）
├── skills/ # Skill 系统（可复用的能力模块）
├── buddy/ # BUDDY 终端宠物系统（彩蛋）
├── assistant/ # KAIROS 主动助手模式
├── coordinator/ # 多 Agent 协调模式
├── state/ # 全局状态管理
├── types/ # TypeScript 类型定义
└── context/ # 上下文管理（用户、系统、统计等）从这个目录结构可以看出，Claude Code 绝非一个简单的「命令行聊天工具」。它是一个高度工程化的终端应用，具备完整的 UI 组件体系、模块化的 Tool 生态、多层次的 Agent 协作机制，以及丰富的可扩展接口。
四、阅读策略与路线图
面对 2200+ 文件、80 万行级别的入口文件，盲目翻阅只会事倍功半。以下是我建议的阅读策略。
4.1 第一层：先看主干骨架
不要一上来就陷入某个 Tool 的实现细节。先建立整体认知：
main.tsx—— 理解程序如何启动。关注：CommanderCommand的命令行参数解析init与initializeTelemetryAfterTrust的初始化序列renderAndRun如何启动 Ink 渲染循环- 各种 prefetch（MCP、Keychain、AWS/GCP 凭证）的并行加载策略
QueryEngine.ts—— 理解「对话循环」的主轴。关注：- 如何构造 message 历史并发送给 Anthropic API
ToolUseBlockParam与ToolResultBlockParam的往返流程- 流式响应（streaming）的处理机制
Tool.ts+tools/—— 理解「Agent 如何行动」。关注：Tool抽象接口的定义（输入 schema、执行函数、权限控制）BashTool、FileReadTool、LspTool等核心 Tool 的实现模式- Tool 的注册与发现机制（
getTools()）
4.2 第二层：再看核心循环
建立骨架认知后，深入核心交互循环：
flowchart TD
A[用户输入] --> B[QueryEngine 构造请求]
B --> C[调用 Anthropic API]
C --> D[流式接收响应]
D --> E{响应类型}
E -->|文本| F[渲染到终端]
E -->|Tool Use| G[执行对应 Tool]
G --> H[生成 Tool Result]
H --> B
F --> I[等待下一轮输入]这个「请求 → 流式响应 → Tool 调用 → 结果回传 → 再请求」的循环，就是 Claude Code 的核心工作模式。读透这一环，就理解了 80% 的运行机制。
4.3 第三层：最后看扩展能力
在掌握主干后，再按需深入扩展模块：
| 模块 | 文件/目录 | 研究价值 |
|---|---|---|
| MCP 客户端 | services/mcp/ | 学习如何实现 MCP 协议，连接外部服务器 |
| LSP 集成 | tools/LspTool/ | 理解 AI 如何与语言服务器交互 |
| 多 Agent / Swarm | tools/AgentTool/、utils/swarm/ | 研究多 Agent 任务分派与协作 |
| Skill 系统 | skills/、utils/skills/ | 学习可复用能力的模块化设计 |
| BUDDY 系统 | buddy/ | 看一个 CLI 工具如何做「情感化设计」 |
| 权限与安全 | utils/permissions/ | 研究命令沙箱、权限模式、拒绝追踪 |
4.4 阅读路线图
flowchart LR
subgraph 第一周 [建立全局认知]
A1[main.tsx
启动流程]
A2[QueryEngine.ts
对话循环]
A3[Tool.ts + tools/
Tool 体系]
end
subgraph 第二周 [深入核心机制]
B1[components/
终端 UI]
B2[services/mcp/
MCP 客户端]
B3[utils/permissions/
权限系统]
end
subgraph 第三周 [探索高级特性]
C1[tools/AgentTool/
多 Agent]
C2[skills/
Skill 系统]
C3[buddy/
彩蛋系统]
end
A1 --> A2 --> A3 --> B1 --> B2 --> B3 --> C1 --> C2 --> C3五、前置知识
要充分理解 Claude Code 的源码，建议具备以下基础：
5.1 终端与命令行
- 熟悉 Unix Shell（Bash/Zsh）的基本操作
- 理解进程、管道、PTY（伪终端）的概念
- 了解 ANSI 转义序列在终端渲染中的作用
5.2 TypeScript / React 基础
- 掌握 TypeScript 高级类型（泛型、条件类型、映射类型）
- 熟悉 React 的函数组件、Hooks、Context 等概念
- 重点：了解 Ink 框架——这是一个用 React 在终端中渲染 UI 的库，Claude Code 的整个界面都建立在其上
5.3 AI Agent 基本概念
- 理解 ReAct（Reasoning + Acting） 范式：LLM 不仅生成文本，还能决定调用外部工具
- 熟悉 Tool Use / Function Calling 的基本流程：模型输出 Tool 调用指令 → 程序执行 → 结果回传给模型
- 了解 MCP（Model Context Protocol）：Anthropic 提出的开放协议，用于标准化 AI 与外部数据源的连接
如果你已经使用过 Claude Code、Cursor、Copilot Chat 等 AI 编程工具，那么你对这些概念已经有了直观的体感，源码阅读会更加顺畅。
六、小结
Claude Code 的源码泄露是一次意外，但也是一次难得的学习机会。这份 2200+ 文件、近 10MB 的代码库，凝聚了 Anthropic 团队在 AI Agent 工程化上的深度思考——从终端渲染的每一帧，到多 Agent 协作的复杂状态机，再到 MCP 生态的开放连接。
在本专题的后续文章中，我们将沿着「主干 → 核心循环 → 扩展能力」的路线，逐层拆解这套系统的工程细节。下一篇，我们将从 main.tsx 的启动流程 开始，看看一个终端 AI Agent 如何从命令行参数一路走到 Ink 渲染循环的启动。
参考链接：