从Claude Code泄露源码看工程架构：第一章——导读

这一次，我们终于能把 Claude Code 拆开看了

2026 年 3 月 31 日凌晨，安全研究员 Chaofan Shou 在 X 上发了一条很短的消息：Claude Code source code has been leaked via a map file in their npm registry。

事情的起点并不复杂。@anthropic-ai/claude-code 2.1.88 这个版本里，包进去了一个不该出现在生产包里的 cli.js.map。顺着这个 Source Map，社区很快摸到了对应的 TypeScript 源码。不是模型权重，不是训练数据，也不是 Anthropic 后端的核心系统，而是 Claude Code 这套客户端和 Agent 外壳本身。

我觉得这件事最值得看的地方，恰好也在这里。

过去大家聊 Claude Code，经常只能围着现象打转：为什么它能在终端里连续干活？为什么它既能改文件、跑命令，又没有彻底失控？为什么它能把工具、权限、上下文、多 Agent、IDE 集成这些东西缝在一起，而且还真能跑起来？现在，源码摊开了，很多问题终于不用靠猜。

这个系列的文章，就是想把这件事讲清楚。

1. 先说清边界：这次泄露了什么，没有泄露什么

这次公开出来的，主要是 Claude Code 的应用层实现，也就是我们平时真正接触到的那一层：CLI 入口、React Ink 界面、QueryEngine、工具系统、权限控制、记忆机制、MCP 接入、多 Agent 调度、IDE 桥接，等等。

没有公开出来的，是 Claude 模型本身最核心的那部分能力：模型权重、训练数据、后端推理基础设施。这些东西并不在这次事件里。

换句话说，这不是一次把"模型内部秘密"全部掀开的泄露；它更像是把一套成熟 AI Agent 产品的工程骨架突然摆在了桌面上。

而对工程视角的读者来说，这个骨架已经很有价值了。

2. 为什么这套源码值得认真看

如果你只是把 Claude Code 理解成"一个会调用大模型 API 的命令行工具"，那看源码时大概率会有点意外。因为它真正难的地方，不在于把 prompt 发出去，而在于把一个会聊天的模型，改造成一个能长期执行任务的终端代理。

这里面至少有几件事，几乎每一件都绕不开工程细节：

它怎么组织一次完整的 Agent 循环，决定什么时候继续问模型，什么时候停下来执行工具。
它怎么给 40 多个工具接上统一的注册、鉴权、执行和结果回填链路。
它怎么处理权限，避免模型一句话就直接把危险命令落到用户机器上。
它怎么在上下文窗口有限的前提下，维护跨会话记忆和工作状态。
它怎么把 IDE、终端、MCP 服务和多 Agent 协作塞进同一套运行框架里。

这些问题，单靠产品演示视频是看不出来的。只有进源码，你才会发现：所谓"AI Agent 体验"，背后其实是一层一层的壳，把模型包成了一个能工作的系统。

我自己最关心的，也正是这件事：Claude Code 到底是怎么把"大模型"变成"工程工具"的。

3. 这系列的文章准备回答什么

这套系列不会把 50 多万行代码从头抄一遍。那样没有意义。更现实的做法，是沿着几条真正重要的主线，把结构一点点拆出来。

所以后面的文章，重点会围着下面这些问题展开：

Claude Code 的启动链路是什么样的？从 CLI 入口到 REPL，再到真正进入 Agent 循环，中间经过了哪些层。
一次请求是怎么跑完的？用户输入、模型响应、工具调用、结果回填，这条链怎么串起来。
工具系统是怎么搭起来的？为什么它能同时容纳文件编辑、命令执行、网页访问、任务分派这些完全不同的能力。
权限系统怎么工作？哪些地方是硬闸门，哪些地方只是软提示。
多 Agent 协作为什么没有把上下文搅烂？任务怎么拆，结果怎么收，主代理又怎么保持可控。
MCP 接入层为什么重要？它到底解决的是"协议兼容"问题，还是"能力扩展"问题。
整个项目的目录结构和模块边界是怎么安排的？哪些目录一看就知道这是核心骨架，哪些更像适配层和外围设施。

你会发现，这些问题都很具体。因为真正有用的源码分析，不是喊一句"架构很先进"，而是把关键连接点一个个找出来。

如果你想深入阅读完整的源码，也可将该系列文章作为项目的脉络梳理，依据这条脉络阅读，可以事半功倍。

4. 目标读者画像

本系列面向以下技术群体：

读者类型	核心诉求	预期收获
高级开发者	深入理解大型 AI 辅助编程工具的内部架构	掌握复杂系统的模块化设计方法
架构师	学习 CLI 工具的分层设计与边界控制	获得可复用的架构模式和设计原则
研究者	研究多 Agent 协作系统和工具调用框架	获取工业级实现的参考案例
开源贡献者	准备参与 Claude Code 或类似项目的代码贡献	建立全局架构心智模型，降低上手成本

5. 这系列的文章怎么读

如果你只是想先抓住全局，我建议按这个顺序读：

这基本就是一条从外到内的路线。

先看整体目录和模块分层，知道仓库是怎么摆的；再看程序从哪里起跑；接着看一次真实请求怎样在系统里流动；最后再拆工具、权限、多 Agent 和 MCP 这些真正决定产品能力上限的部分。

如果你更偏工程实现，可以直接从《一次请求的完整生命周期与流式执行引擎设计》开始。那篇最接近"Claude Code 到底怎么跑起来"的核心问题。

如果你更偏安全视角，那就优先看《权限系统的四道闸门与纵深防御机制》和《MCP 接入层设计》。这两块最能看出 Anthropic 在"给模型放权"这件事上，到底有多谨慎，也能看出它哪里做得细，哪里还留着工程上的妥协。

5. 为什么这事不只是八卦和炒作

源码泄露当然有新闻性，但如果只把它当成一场热闹，能留下来的东西其实不多。

我更在意的是另一层：Claude Code 把很多原本散落在论文、Demo 和创业项目里的想法，做成了一套真的能交付给用户的系统。它未必每个设计都新，也未必每个实现都漂亮，但它足够完整。完整到你可以顺着目录树往下走，看到一个生产级 AI Agent 产品到底由哪些零件拼出来。

这很少见。

更少见的是，它不是一个专门拿来"展示架构理念"的教学项目，而是一套真正在服务真实用户的商业产品。正因为如此，里面很多设计不是"最优雅"的，而是"能落地"的。对工程分析来说，这种东西反而更有参考价值。

6. 带着重点阅读

读这组文章时，你可以重点带着这几个判断去看

第一，Claude Code 的核心不只是模型调用，而是围绕模型搭起来的执行系统。

第二，真正决定体验上限的，往往不是 prompt 写得多花，而是工具、权限、状态和上下文怎么编排。

第三，所谓"AI 原生应用"的门槛，很多时候不在模型层，而在外面那层厚厚的工程壳。

如果后面的源码能把这三件事说明白，这组文章就算没有白写。

7. 最后说一句

这套系列只讨论已经公开传播后的技术线索和工程实现，不提供泄露文件的获取方式，也不鼓励传播原始代码包。我们关心的是架构分析，不是二次分发。

如果你准备开始读正文，最合适的第一站就是《从Claude Code泄露源码看工程架构：项目架构总览与分层设计哲学》。先把地图摊开，后面再往每一条链路里钻，会轻松很多。