跳至内容

源码分析

当你在 Claude Code 终端输入一条消息时,内部到底发生了什么?

基于 @anthropic-ai/claude-code 2.1.88 发布包(npm 发布包,该版本后已从 npm 历史中移除),通过 source map 逆向还原 → 路径统计 → 语义分层 → 交叉验证,解剖一个包含 1,902 个源文件、43 个工具、97 个命令的工业级 agent harness 系统。

非官方单快照逆向分析。 数字来自 source map 路径的归一化统计口径,不等于物理目录数。阅读时请区分"直接证据"“语义聚类"和"解释性判断”。
文档 + 可视化双窗口。 文档解释"为什么这样设计",可视化地图 回答"在哪里、怎么连"。两者共用同一套五主题骨架和数据口径,建议对照阅读。

从这里开始

专题深化

阅读路径

不同背景的读者,关注点不同。选择适合自己的起点:

路径一:用户视角

想理解"Claude Code 为什么这样运行"——为什么工具会被拒绝、为什么长会话突然压缩、为什么某些命令不可见。

  1. 运行时流程 — 理解一次请求穿过七个阶段的过程
  2. 权限治理 — 理解工具被允许或拒绝的判定链路
  3. 命令表面 — 找到你常用命令的内部映射
  4. 成本追踪 — 理解 token 计量和压缩触发

路径二:Agent 构建者

想从工业级 agent 系统中提炼可复用的设计模式——query loop、tool governance、context compact、memory 闭环。

  1. 架构地图 — 从六层结构建立全局认知
  2. 运行时流程 — 理解 query loop 心跳与状态机
  3. 工具平面 — 理解工具注册、治理和执行模型
  4. 记忆系统 — 理解 compact 五层策略和长会话连续性
  5. Coordinator 编排 — 理解多 Worker 编排模式

路径三:逆向研究者

想完整理解这个系统的能力边界和演进方向——从主干到实验外沿。

  1. 架构地图 — 把 1,902 个文件还原成六层结构
  2. 工具平面 + 命令表面 — 全量能力面扫描
  3. 扩展与信号 — 识别成熟能力与实验方向
  4. 所有 专题深化 页面 — 逐一验证源码路径证据

通用建议

无论哪条路径,都建议配合 可视化地图 一起使用——文档解释"为什么这样设计",可视化回答"在哪里、怎么连"。

和官方资料怎么配合读

官方资料更适合确认功能定义、支持边界和最小示例;这里的源码分析更适合回答系统如何组织、为什么这样约束,以及哪些模式值得迁移到自己的 Agent 工程。

建议按这个顺序读:

  1. 先用官方文档确认能力原语和当前边界
  2. 再读 研究方法 建立阅读框架
  3. 然后进入 运行时流程 与 工具平面
  4. 再用 工程落地清单 把这些能力重组为执行路线
  5. 最后把 记忆系统、Coordinator 编排 和 MCP 与 Bridge 当作可迁移的工程样本

这样可以避免两种常见误读:一是把官方最小示例当成完整系统设计,二是把单个源码快照里的局部信号误读成长期产品承诺。

关键发现

Claude Code 不是一个简单的 LLM 套壳命令行工具。从 source map 逆向还原出来的 1,902 个源文件揭示了一个精心设计的 agent harness 系统——模型只是系统中的一个不稳定部件,围绕它的是一套完整的外循环编排:

  1. query loop 是心跳:一个 while(true) 循环(query.ts 第 241-1728 行),驱动"采样 → 工具 → 权限 → 恢复/继续/停止"的持续循环
  2. 工具是受管接口而非裸函数:43 个工具通过 Tool.ts 统一注册,每个工具声明 readonly、concurrencySafe、sandboxed 等接口特征,运行前经过四层治理
  3. 上下文不是无限的:五层压缩策略(Micro → TimeBased → APISide → SessionMemory → Full)在 ~93% token 阈值时自动触发
  4. 记忆不只在 transcript 中:CLAUDE.md、memdir、SessionMemory、daily logs 等外化工件共同维护跨会话连续性
  5. 安全不是附加层:权限模式、规则匹配、Hook 拦截、OS 级沙箱从架构上嵌入执行路径
  6. 子代理不是"另开一个 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 变得过度谨慎
  • 渐进式信任:新用户从受限权限开始逐步建立信任——模仿人类社交中的信任机制

可视化入口

可视化地图在 code.claudecn.com,提供交互式结构图、工具特征标签、Agent Loop 动画和全局搜索。每个工具卡片都带有 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/>扩展织物"]
  

进一步阅读