claude code泄露源码下载链接：https://pan.quark.cn/s/0d7de09e7e06

Claude Code Sourcemap 项目架构分析.pdf 链接：https://pan.quark.cn/s/64dcc2b2ab25

最近读了一份关于 `Claude Code Sourcemap` 的项目架构分析，感觉很有启发。它表面上像是在分析一个 CLI 工具，但真正拆开后会发现，Claude Code 并不是传统意义上的“命令行程序”，而更像是一个运行在终端里的 Agent Runtime。

## 1. 先说结论：CLI 只是入口

这个项目的分析对象并不是官方 monorepo，而是从 npm 发布包和 sourcemap 中还原出来的源码结构。因此它更适合作为“产品运行机制研究”，而不是官方源码目录解读。

从整体结构看，CLI 只是启动入口。真正核心的是：

- 消息驱动的对话循环
- 工具调用与权限控制
- 上下文压缩与恢复
- 插件、Skill、MCP 扩展系统
- 子代理与后台任务
- 会话持久化与远程控制能力

换句话说，它不是“输入命令，执行命令”的工具，而是一个围绕模型、工具、消息和状态构建的 Agent 平台。

## 2. 架构主线：启动、交互、执行、扩展

Claude Code 的架构可以粗略分成几层。

第一层是启动层。`cli.tsx` 负责最外层入口，优先处理 `--version` 等快速路径，并通过动态 import 降低冷启动成本。`main.tsx` 则更像总装配中心，负责参数解析、配置加载、MCP 初始化、commands/tools/agents 准备，以及选择 interactive、headless、remote 等运行模式。

第二层是交互层。交互模式使用 React + Ink 构建终端 UI，核心界面并不是简单聊天框，而是包含输入、消息列表、权限弹窗、任务状态、通知等能力的完整终端应用。与此同时，headless 和 SDK 模式并没有另起一套逻辑，而是复用同一套 query/tool/message 基础设施，只是输入输出适配不同。

第三层是执行核心，也就是 QueryEngine 和 query loop。用户输入会被转成消息，系统会组装 system prompt、用户上下文、工具定义，再调用 Claude API 的流式接口。如果模型返回 tool_use，系统会执行工具、回填 tool_result，然后继续下一轮模型调用。这就是典型的 Agent loop。

## 3. Tool 才是真正的能力核心

我觉得最值得学习的是它对 Tool 的设计。这里的 Tool 不是一个简单函数，而是一个包含 schema、权限、安全属性、UI 渲染、结果转换、日志记录等信息的统一协议对象。

比如 BashTool 不只是执行 shell 命令，还要判断命令是否只读、是否危险、是否需要 sandbox、输出如何裁剪。FileEditTool 也不只是改文件，还要做路径规范化、旧文本校验、外部修改检测、diff 记录等。

这说明 Claude Code 的工具系统关注的不只是“能不能执行”，更关注“是否安全、是否可解释、是否能被恢复和审计”。

## 4. 扩展系统不是单点设计

Claude Code 的扩展能力不是只靠插件完成，而是多套机制叠加：

- Command：用户显式触发的斜杠命令
- Skill：Markdown 驱动的专业工作流或提示词能力
- Plugin：可分发的能力包，可包含命令、技能、Agent、Hook、MCP 等
- MCP：外部工具、资源、Prompt 的协议接入层

这几套机制最后都会被统一映射到系统内部的 command、tool、resource 或 skill 中。也就是说，扩展系统并不是外挂，而是运行时架构的一部分。

## 5. 长会话能力来自持久化和压缩

另一个关键点是 session 的设计。Claude Code 并不把一次运行看成短暂进程，而是把会话当成长期对象处理。

它会持久化 transcript、compact boundary、agent metadata、file history 等信息。上下文过长时，也不是简单“总结一下”，而是通过 microcompact、autocompact、reactive compact 等机制，把长会话重写成更短但仍可继续工作的状态。

这也是 Agent 工具和普通聊天机器人的重要区别：普通聊天重视回复，Agent Runtime 更重视连续执行。

## 6. 我的学习收获

读完这个架构后，我最大的感受是：成熟的 AI 编程工具，复杂度并不主要在 UI，而在 runtime orchestration。

真正难的地方包括：

- 如何稳定启动并支持多运行模式
- 如何把模型输出转成安全工具调用
- 如何管理权限、上下文和状态
- 如何让插件、MCP、Skill 这些扩展机制统一工作
- 如何让长会话可恢复、可压缩、可审计

如果以后要设计自己的 AI Agent 工具，我会优先借鉴这几个思路：

1. 先定义统一消息模型，而不是先写 UI。
2. Tool 要设计成协议对象，而不是普通函数。
3. 扩展能力要尽早抽象，不要后期硬塞。
4. 长会话一定要有 transcript、compact 和 resume 机制。
5. CLI、Web、SDK 可以共用核心 runtime，只换 IO 适配层。

总的来说，Claude Code 的价值不只在于“能帮你写代码”，更在于它展示了一种 Agent 产品的工程化形态：以消息为中心，以工具为能力边界，以扩展系统连接外部世界，以持久化和压缩支撑长期任务。对于想理解 AI 编程工具架构的人来说，这份分析很值得细读。