Claude Code 2.1.88 源码分析地图

当你在 Claude Code 终端输入一条消息时，内部到底发生了什么？Agent Loop 如何驱动工具系统、多代理协作、权限闸门和上下文压缩——每个结论直接对应源码路径。

当前快照包含 1902 个用户源码文件、43 个工具实体、97 个命令入口和 10 个能力信号。

分析概括

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 不能在错误边界被切断、错误恢复不能暴露半成品状态
• 缓存前缀不能漂：模型已经看过的内容在后续轮次中命运被冻结，工具顺序、子代理前缀都围绕这条约束收敛
• 能力面不能一次性敞开：工具、MCP、skill 不是全部预加载，而是分层暴露、延迟发现、按时机激活
• 连续性不能只寄托在 transcript 上：真正稳定的连续性分散在 CLAUDE.md、memdir、SessionMemory、daily logs 等外化工件上

对 agent 开发者的启示

Claude Code 的源码不只是一个产品实现，更是一份 Agent Harness 工程模式的参考样本：

• 模型当不稳定部件：所有工具默认 isReadOnly=false、isConcurrencySafe=false，不信任模型判断
• Query Loop 是心跳：while(true) 循环驱动，7 个 continue + 1 个 return 出口
• 工具是受管接口：权限模式 → 规则匹配 → Hook 拦截 → 沙箱约束四层治理
• 上下文是工作内存：五层压缩策略，~93% 阈值触发
• 错误路径就是主路径：prompt too long → 自动 compact → 恢复继续
• 验证必须独立：内建 verificationAgent，不让实现者自己给自己打分

五个认知入口

source-analysis 文档入口

• 研究方法 — 如何把官方资料、最小示例与源码快照一起读
• 工程落地清单 — 如何把源码里的能力装成团队可维护的工作流
• 架构地图 — 系统由哪些边界、层次和子系统组成
• 运行时流程 — 一次请求如何在系统里形成持续闭环
• 工具平面 — 系统到底能做什么，以及为什么要这样分层
• 命令表面 — 用户从哪些产品入口接触系统能力
• 扩展与信号 — 从代码结构看系统还会往哪里长

推荐阅读路径

一手证据从哪里来

• package.json — 版本 2.1.88、bin 入口 cli.js、Node ≥ 18
• cli.js.map — 1,902 个 ../src/ 用户源文件，47 个顶层模块
• sdk-tools.d.ts — 工具 schema、输入输出类型定义
• vendor/ — ripgrep（代码搜索）、audio-capture（语音输入）

配套长文：claudecn.com/docs/source-analysis/