Claude Code 源码解析学习笔记：从 v2.1.88 反编译看 AI 编程助手的真实架构

最近发现了一个很有意思的仓库：sanbuphy/claude-code-source-code。

作者从 @anthropic-ai/claude-code npm 包（v2.1.88）中反编译出了约 1,884 个 TypeScript 源文件，并附上了五份详细的中英双语分析报告。这是目前公开资料里对 Claude Code 内部架构描述最详细的一次。

本文不是逐行解读代码，而是以学习笔记的方式，把这份分析里最值得关注的部分系统整理出来。

仓库规模

先给一个整体的数字感：

维度	数值
源文件数	~1,884 个 `.ts` / `.tsx`
代码行数	~512,664 行
最大单文件	`query.ts`（~785KB，包含主 Agent 循环）
内置工具数	40+
斜杠命令数	80+
npm 依赖包	192 个

这个规模远超大多数人对”命令行工具”的印象。Claude Code 实际上是一个具备完整 Agent 运行时的中型系统。

核心架构：Agent 循环

整个系统的核心在 query.ts 里，实现了一个流式 Agent 循环：

用户输入
  → 组装系统提示词（System Prompt）
  → 调用 Claude API（流式响应）
  → 解析工具调用（Tool Use）
  → 权限检查
  → 执行工具
  → 结果写回上下文
  → 重新调用 API
  → 循环，直到 stop_reason ≠ "tool_use"

这个循环看起来简单，但它叠加了 12 层 Harness 机制：

Streaming — 流式输出，边生成边处理
Concurrency — 工具并行执行
Planning — 任务分解与计划生成
Sub-agents — 子 Agent 派生（Fork 模式）
Knowledge injection — 上下文知识注入（CLAUDE.md 等）
Context compaction — 三层上下文压缩策略
Persistent tasks — 任务持久化（JSONL append-only 日志）
Background execution — 后台执行模式
Team protocols — 多 Agent 消息传递协议
Worktree isolation — Git worktree 隔离环境
Permissions — 多阶段权限验证
Telemetry — 遥测与实验系统

这 12 层叠加在一起，才构成了用户看到的那个”能写代码、能改代码、能跑命令”的体验。

工具系统（40+ 内置工具）

工具是 Agent 的手。Claude Code 的工具分为以下几类：

文件操作

Read — 读文件（支持 PDF、Notebook、图片）
Write — 写文件
Edit — 精确字符串替换
Glob — 文件模式匹配
Grep — 基于 ripgrep 的代码搜索

执行环境

Bash — 执行 Shell 命令（最核心的工具）
NotebookEdit — 编辑 Jupyter Notebook

网络 & 知识

WebFetch — 获取 URL 内容，转换为 Markdown
WebSearch — 网络搜索

Agent 编排

Agent — 派生子 Agent（隔离上下文）
TodoWrite — 任务追踪

任务管理

TaskOutput — 读取后台任务输出
TaskStop — 停止任务

MCP 集成

通过 stdio、SSE、HTTP、WebSocket 四种传输协议连接 MCP 服务器
支持 OAuth 鉴权

工具的调用流程不是直接执行，而是先走权限检查。这是 Claude Code 安全设计的核心。

权限系统

每个工具调用都经过多阶段验证：

工具调用请求
  → 输入验证（Input Validation）
  → Pre-execution Hooks（用户自定义的 shell 钩子）
  → 权限规则匹配（Allow / Deny / Ask）
  → 交互式提示（需要用户确认时）
  → 工具执行
  → Post-execution Hooks

权限规则支持通配符匹配，例如：

Bash(git *) — 允许所有 git 命令
Bash(rm *) — 拒绝所有 rm 命令
Read(**/secrets/*) — 要求用户确认才能读取 secrets 目录

settings.json 里的 permissions 字段就是这套规则的配置入口。

上下文管理：三层压缩策略

长对话的上下文管理一直是 Agent 系统的难点。Claude Code 实现了三种压缩机制，按情况选用：

策略	触发条件	行为
Auto-compact	接近上下文窗口上限	自动调用内部 API 压缩历史
Snip-compact	特定工具返回过大	截断工具结果，保留首尾
Context-collapse	极端情况（内部功能，已 DCE）	完全折叠上下文，重建摘要

其中第三种 context-collapse 属于功能门控模块（feature-gated），在公开的 npm 包里通过 Dead Code Elimination 被移除，只存在于 Anthropic 内部版本。

多 Agent 支持

Agent 工具支持四种运行模式：

Fork 模式（隔离子进程） 子 Agent 在独立上下文中运行，任务完成后结果写回主 Agent。适合需要隔离的复杂子任务。

Remote Agents（通过 Bridge） 通过 bridge/ 层与 Claude Desktop 集成，或连接到远程执行环境。

In-process Teammates（共享上下文） 多个 Agent 实例在同一进程内协作，通过消息传递协议通信。

Swarm 模式（功能门控，未发布） 源码中有引用，但在公开包里被功能门控屏蔽。

Worktree 隔离是多 Agent 协作的重要支撑：每个 Agent 可以在独立的 Git worktree 分支上工作，避免并发写入冲突。

重要发现：隐藏功能与安全隐患

这是这份反编译分析里最受关注的部分，也是这个仓库获得 3.6k Star 的主要原因。

1. 双重遥测系统

Claude Code 同时向两个端点发送遥测数据：

Anthropic 自有服务器 — 使用行为、工具调用频率、会话指纹
Datadog — 性能指标、错误追踪

关键点：当前 UI 中没有公开暴露的第一方日志关闭选项。官方文档提到的 DISABLE_TELEMETRY=1 只影响部分数据收集，不是全量关闭。

2. 内部用户特权（Codename: Capybara、Tengu、Numbat）

源码中有三个动物代号对应不同的内部/未来版本：

Capybara — v8 版本相关功能
Tengu — 特定内部功能标识
Numbat — 下一代版本（next-gen，已有接口定义）

内部员工（通过身份标识检测）会获得：

更完整的系统提示词
验证 Agent（Verification Agent） — 额外的质量检查层
部分已开发但未对外开放的工具

3. Undercover Mode（隐身模式）

最受争议的发现之一。

当 Claude Code 检测到用户在公开 GitHub 仓库中工作时，会自动进入一种模式，在生成的代码、提交信息等内容里不声明 AI 参与。

现状：

触发是自动的，用户无法感知
不存在强制关闭（force-OFF）机制
文档中未有明确说明

从工程角度理解，这可能是为了避免某些公司”代码不得包含 AI 生成内容”的合规要求。但没有告知用户本身就是问题所在。

4. 远程控制与 Killswitch

Claude Code 每小时轮询一次 /api/claude_code/settings 端点，获取远程配置更新。

这套机制包含：

6 个以上的 Killswitch，可以从服务端关闭主要功能
触发”危险变更”时会弹出阻断对话框，用户点击拒绝则 App 直接退出
用户无法绕过

这意味着 Anthropic 可以在不发布新版本的情况下，远程修改用户的 Claude Code 行为。

缺失的 108 个模块

公开 npm 包里缺失了 108 个模块，它们在源码中被引用但已通过 Dead Code Elimination 移除。

主要类别：

内部基础设施（~70 个）

Daemon worker（后台守护进程）
Proactive notifications（主动通知系统）
Context collapse（极端上下文折叠）
Skill search system（技能搜索）
Workflow execution engine（工作流引擎）

有类型签名但无实现的工具（~20 个）

工具名	推测功能
`REPL`	交互式代码执行
`Snip`	代码片段管理
`Sleep`	Agent 延时等待
`Monitor`	系统监控
`VoiceInput`	语音输入
`CanvasRender`	可视化渲染

内部提示词模板（~6 个）

包括 Verification Agent 的系统提示词
内部用户专属的增强提示词

路线图线索

从未发布的模块和功能门控代码里，可以推测出一些未来方向：

KAIROS 模式 一种”完全自主（fully autonomous）“的 Agent 模式，代号 KAIROS。目前所有接口都已定义，但所有实现路径都被功能门控屏蔽。预计是 Numbat 版本的重点功能。

Voice Mode 语音输入/输出接口已在源码中声明，对应工具 VoiceInput 和相关组件。

17 个未发布工具 除上述 REPL、Snip 等外，还有若干代码生成、数据分析和多模态相关的工具类型。

架构总结

用一张简化图来理解 Claude Code 的整体分层：

┌─────────────────────────────────────────────┐
│              用户界面（Terminal UI）          │
│         React/Ink 组件 + 斜杠命令             │
├─────────────────────────────────────────────┤
│              Harness 层（12 机制）            │
│  规划 / 子 Agent / 上下文压缩 / 持久化任务    │
├─────────────────────────────────────────────┤
│              Agent 循环（query.ts）           │
│         系统提示词 → API 调用 → 工具执行      │
├──────────────┬──────────────────────────────┤
│   工具系统   │         权限系统              │
│  40+ 工具    │  Allow/Deny/Ask + Hooks       │
├──────────────┴──────────────────────────────┤
│              Bridge 层                      │
│    Claude Desktop 集成 / 远程执行环境        │
├─────────────────────────────────────────────┤
│              遥测 & 远程配置                 │
│   Anthropic + Datadog / 小时级轮询          │
└─────────────────────────────────────────────┘

几点思考

1. 这套架构有多少可以复用？

Agent 循环、工具系统、权限模型这三块是通用的。如果你在构建自己的 Agent 系统，这份分析相当于一份来自生产环境的参考实现。12 层 Harness 机制也可以按需选取，不一定要全部实现。

2. 遥测和隐身模式的启示

对于企业级 Agent 工具来说，数据流向透明性和用户知情权会越来越重要。Claude Code 的这些发现可能会推动 Anthropic 在后续版本中提供更明确的控制选项。

3. 功能门控 vs 版本发布

108 个缺失模块揭示了一种产品策略：核心代码统一维护，通过 feature flags 控制对外暴露的功能集。这让 Anthropic 可以在内部完整测试功能，同时对外保持稳定的 API 表面。

参考资料

sanbuphy/claude-code-source-code — 本文分析的源仓库
Claude Code 官方文档 — 官方参考
MCP 协议规范 — Model Context Protocol

本文基于截至 2026-04-01 的仓库内容整理，仅供学习研究使用。Claude Code 的版本迭代较快，部分细节可能已随新版本变化。