源码分析
当你在 Claude Code 终端输入一条消息时,内部到底发生了什么?
基于 @anthropic-ai/claude-code 2.1.88 发布包(npm 发布包,该版本后已从 npm 历史中移除),通过 source map 逆向还原 → 路径统计 → 语义分层 → 交叉验证,解剖一个包含 1,902 个源文件、43 个工具、97 个命令的工业级 agent harness 系统。
从这里开始
专题深化
阅读路径
不同背景的读者,关注点不同。选择适合自己的起点:
路径一:用户视角
想理解"Claude Code 为什么这样运行"——为什么工具会被拒绝、为什么长会话突然压缩、为什么某些命令不可见。
路径二:Agent 构建者
想从工业级 agent 系统中提炼可复用的设计模式——query loop、tool governance、context compact、memory 闭环。
- 架构地图 — 从六层结构建立全局认知
- 运行时流程 — 理解 query loop 心跳与状态机
- 工具平面 — 理解工具注册、治理和执行模型
- 记忆系统 — 理解 compact 五层策略和长会话连续性
- Coordinator 编排 — 理解多 Worker 编排模式
路径三:逆向研究者
想完整理解这个系统的能力边界和演进方向——从主干到实验外沿。
通用建议
无论哪条路径,都建议配合 可视化地图 一起使用——文档解释"为什么这样设计",可视化回答"在哪里、怎么连"。
和官方资料怎么配合读
官方资料更适合确认功能定义、支持边界和最小示例;这里的源码分析更适合回答系统如何组织、为什么这样约束,以及哪些模式值得迁移到自己的 Agent 工程。
建议按这个顺序读:
- 先用官方文档确认能力原语和当前边界
- 再读 研究方法 建立阅读框架
- 然后进入 运行时流程 与 工具平面
- 再用 工程落地清单 把这些能力重组为执行路线
- 最后把 记忆系统、Coordinator 编排 和 MCP 与 Bridge 当作可迁移的工程样本
这样可以避免两种常见误读:一是把官方最小示例当成完整系统设计,二是把单个源码快照里的局部信号误读成长期产品承诺。
关键发现
Claude Code 不是一个简单的 LLM 套壳命令行工具。从 source map 逆向还原出来的 1,902 个源文件揭示了一个精心设计的 agent harness 系统——模型只是系统中的一个不稳定部件,围绕它的是一套完整的外循环编排:
- query loop 是心跳:一个
while(true)循环(query.ts第 241-1728 行),驱动"采样 → 工具 → 权限 → 恢复/继续/停止"的持续循环 - 工具是受管接口而非裸函数:43 个工具通过
Tool.ts统一注册,每个工具声明readonly、concurrencySafe、sandboxed等接口特征,运行前经过四层治理 - 上下文不是无限的:五层压缩策略(Micro → TimeBased → APISide → SessionMemory → Full)在 ~93% token 阈值时自动触发
- 记忆不只在 transcript 中:CLAUDE.md、memdir、SessionMemory、daily logs 等外化工件共同维护跨会话连续性
- 安全不是附加层:权限模式、规则匹配、Hook 拦截、OS 级沙箱从架构上嵌入执行路径
- 子代理不是"另开一个 agent":6 种内建子代理各有独立工具集和隔离策略
四条运行时不变量
按目录结构阅读源码,得到的是功能清单。真正撑起系统运行时秩序的,是四条同时成立的不变量——理解这些比理解任何单个模块都重要:
| 不变量 | 含义 | 维护模块 |
|---|---|---|
| 轨迹拓扑不能破 | tool_use 不能悬空、thinking block 不能在错误边界被切断、错误恢复不能暴露半成品状态 | query.ts 恢复图 |
| 缓存前缀不能漂 | 模型已经看过的内容在后续轮次中命运被冻结,工具顺序、子代理前缀都围绕这条约束收敛 | toolResultStorage.ts / microCompact.ts |
| 能力面不能一次性敞开 | 工具、MCP、skill 不是全部预加载,而是分层暴露、延迟发现、按时机激活 | Tool.ts / ToolSearchTool / loadSkillsDir.ts |
| 连续性不能只寄托在 transcript 上 | 真正稳定的连续性分散在 CLAUDE.md、memdir、SessionMemory、daily logs 等外化工件上 | attachments.ts / memdir/* / SessionMemory/* |
值得迁移到你自己 agent 设计里的,不是某个具体函数,而是它在替哪条不变量付账。
对 agent 开发者的启示
Claude Code 的源码不只是一个产品实现,更是一份 Agent Harness 工程模式 的参考样本。以下是从源码中可以直接借鉴的设计原则:
| 原则 | Claude Code 的实践 | 对应源码证据 |
|---|---|---|
| 模型当不稳定部件 | 所有工具默认 isReadOnly=false、isConcurrencySafe=false,不信任模型判断 | src/Tool.ts 第 362-480 行 |
| Query Loop 是心跳 | while(true) 循环驱动,7 个 continue + 1 个 return 出口 | src/query.ts 第 307-1728 行 |
| 工具是受管接口 | 权限模式 → 规则匹配 → Hook 拦截 → 沙箱约束四层治理 | src/utils/permissions/ + src/hooks/ + src/utils/sandbox/ |
| 上下文是工作内存 | 五层压缩策略(Micro → TimeBased → APISide → SessionMemory → Full),~93% 阈值触发 | src/services/compact/ |
| 错误路径就是主路径 | prompt too long → 自动 compact → 恢复继续;max_tokens → 重试 + recovery 计数 | query.ts 中 maxOutputTokensRecoveryCount |
| 验证必须独立 | 内建 verificationAgent,不让实现者自己给自己打分 | src/tools/AgentTool/built-in/ |
源码中的认知科学
Claude Code 的设计不纯粹是工程决策,部分设计深受认知科学影响(这是 Anthropic Character Lead Amanda Askell 的贡献):
- 记忆过滤:系统不机械存储所有对话,而是只记"出人预料"的信息——这是认知科学中的朝向反应(orienting response)
- 避免习得性无助:系统同时记录成功和失败,而不是只记错误——防止 AI 变得过度谨慎
- 渐进式信任:新用户从受限权限开始逐步建立信任——模仿人类社交中的信任机制
可视化入口
readonly / parallel-safe / sandboxed / deferred 等接口特征标签,比纯文档更直观。证据体系
一手证据
| 证据文件 | 作用 | 核心信息 |
|---|---|---|
package.json | 发布边界 | 版本 2.1.88、bin 入口 cli.js、Node ≥ 18 |
cli.js.map | 源码路径索引 | 1902 个 ../src/ 用户源文件,47 个顶层模块 |
sdk-tools.d.ts | 工具契约 | 工具 schema、输入输出类型定义 |
vendor/ | 跨平台运行时依赖 | ripgrep(代码搜索)、audio-capture(语音输入) |
统计口径说明
| 指标 | 当前口径 | 需要避免的误读 |
|---|---|---|
| 1902 个用户源码文件 | cli.js.map 中所有 ../src/ 路径的去重结果 | 不是仓库里"你能直接看到的 TS 文件数" |
| 47 个顶层模块 | ../src/ 第一段路径归一化后的分桶,混合了目录和单文件入口 | 不是 47 个物理目录 |
| 43 个工具实体 | ../src/tools/ 第一段路径归一化后的分桶,包含 shared、testing、utils 等基础设施桶 | 不是 43 个都能被用户直接点名调用的工具 |
| 97 个命令入口 | ../src/commands/ 第一段路径归一化后的分桶,并排除 createMovedToPluginCommand、init、init-verifiers 三个内部 wiring 入口 | 不是 97 个都默认对普通用户可见的 slash 命令 |
证据分层
| 层级 | 含义 | 例子 |
|---|---|---|
| 直接证据 | 可以直接回到发布包路径、类型声明或配置项 | package.json、cli.js.map、sdk-tools.d.ts |
| 语义聚类 | 基于路径分布做的结构重组,用于帮助理解 | 六层架构、五主题骨架、七组命令分组 |
| 解释性判断 | 对工程意图、成熟度或设计哲学的归纳 | 为什么默认最严格、为什么把权限视为边界系统 |
阅读时最重要的原则是:直接证据优先,其次才是聚类和解释。
项目结构图
flowchart LR
Package["claudecode/package<br/>v2.1.88"]
Package --> Pkg["package.json<br/>发布边界"]
Package --> Readme["README.md<br/>产品定位"]
Package --> Map["cli.js.map<br/>1902 源码路径"]
Package --> Schema["sdk-tools.d.ts<br/>工具契约"]
Package --> Vendor["vendor/<br/>ripgrep + audio-capture"]
Map --> Entry["src/entrypoints + src/cli<br/>入口分发"]
Map --> Tools["src/tools<br/>43 个工具实体"]
Map --> Commands["src/commands<br/>97 个命令入口"]
Map --> Services["src/services<br/>服务编排"]
Map --> UI["src/components + src/ink<br/>终端 UI"]
Map --> Memory["src/memdir + SessionMemory<br/>记忆与压缩"]
Map --> Ext["src/skills + src/bridge<br/>扩展织物"]