Claude Code 源码深度解析白皮书

English | 中文

基于 @anthropic-ai/claude-code npm 包 source map 还原的 1,987 个 TypeScript 源文件的系统性技术分析

版本: v1.0 | 日期: 2026-04-04 | 声明: 本文档仅供技术研究与学习使用，源码版权归 Anthropic 所有

总览与架构
工具系统：Claude Code 的双手
Agent 编排与多任务系统
Bash 工具与沙箱安全机制
文件操作与编辑工具链
BUDDY — AI 电子宠物系统
KAIROS — 永不关机的 Claude
ULTRAPLAN — 云端深度规划
Coordinator — 多 Agent 编排模式
Bridge — 远程遥控终端
26+ 隐藏命令与秘密开关
50 个编译开关与三层门控体系
MCP 协议集成
记忆与上下文管理
权限系统与安全模型
编译与构建体系
附录

1. 总览与架构

1.1 项目概览

Claude Code 是 Anthropic 官方推出的 AI 编程助手 CLI 工具，以 npm 包形式分发。通过对其 source map 的逆向还原，我们获得了完整的 TypeScript 源码树，包含 1,987 个 TS/TSX 文件，涵盖了一个现代 AI 编程助手的全部实现细节。

1.2 技术栈

层面	技术
语言	TypeScript（ESM）
运行时	Bun ≥ 1.3.5、Node.js ≥ 24
UI 框架	React + Ink（终端 UI）
AI API	Anthropic Messages API
网络协议	WebSocket、SSE、HTTP REST
构建工具	Bun bundler（含 DCE 死代码消除）
远程配置	GrowthBook A/B 测试平台

1.3 顶层目录结构

src/                        # 核心源码
├── tools/                  # 53 个工具（Bash/FileEdit/Agent/MCP...）
├── commands/               # 87 个斜杠命令
├── services/               # API / MCP / analytics / autoDream
├── components/             # 148 个终端 UI 组件（React + Ink）
├── hooks/                  # 87 个自定义 React Hooks
├── buddy/                  # 宠物伴侣系统（BUDDY）
├── assistant/              # 持久助手模式（KAIROS）
├── coordinator/            # 多 Agent 协调器
├── bridge/                 # 远程控制桥接（33 文件）
├── proactive/              # 主动自主模式
├── vim/                    # Vim 模式引擎
├── voice/                  # 语音交互系统
├── skills/                 # 技能系统（含 Claude API 文档）
└── ...
shims/                      # 原生模块兼容替代
vendor/                     # 原生绑定源码

1.4 核心设计理念

Claude Code 的架构围绕以下核心原则设计：

工具驱动：Claude 模型本身不执行操作，通过 53 个工具与外部世界交互
安全优先：三层权限模型、沙箱隔离、用户确认机制
渐进式复杂度：外部版是精简版，内部版解锁全部功能
可扩展性：MCP 协议、技能系统、插件架构

2. 工具系统：Claude Code 的双手

2.1 工具概览

Claude Code 定义了 53 个工具（src/tools/），每个工具是一个标准化的 TypeScript 模块，遵循统一的接口协议：

interface Tool {
  name: string;           // 工具名称
  description: string;    // 自然语言描述（模型可见）
  input_schema: object;   // JSON Schema 输入定义
  run(params): Promise;   // 执行逻辑
  render?(params): React; // UI 渲染
}

2.2 核心工具分类

文件操作工具

工具	功能	关键特性
`Read`	读取文件	支持行范围、PDF、图片、Jupyter Notebook
`Edit`	精确字符串替换	要求 `old_string` 唯一匹配，支持 `replace_all`
`Write`	创建/覆写文件	要求先 `Read` 已有文件
`Glob`	文件模式匹配	基于 glob 模式搜索文件
`Grep`	内容搜索	基于 ripgrep，支持正则表达式

执行工具

工具	功能	关键特性
`Bash`	Shell 命令执行	沙箱隔离、超时控制、后台运行
`Agent`	子代理调度	支持多种子代理类型、工作树隔离

交互工具

工具	功能
`AskUserQuestion`	向用户提问获取输入
`EnterPlanMode`	进入规划模式
`TaskCreate/Update/List/Get`	任务管理
`CronCreate/Delete/List`	定时任务调度

高级工具

工具	功能
`Skill`	调用技能
`NotebookEdit`	Jupyter Notebook 编辑
`WebSearch`	网页搜索
`mcp__*`	MCP 协议扩展工具

2.3 工具并发模型

Claude Code 支持工具的并行调用。当多个工具调用之间没有依赖关系时，系统会自动并行执行以提高效率。工具并发数可通过 CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY 环境变量控制。

3. Agent 编排与多任务系统

3.1 Agent 工具

Agent 工具（src/tools/Agent/）是 Claude Code 最强大的能力之一，允许主 Claude 进程生成专门的子代理来处理复杂任务。

子代理类型

类型	用途	工具权限
`general-purpose`	通用研究、搜索、多步骤任务	全部工具
`Explore`	快速代码库探索	只读工具（Glob/Grep/Read）
`Plan`	软件架构设计	只读工具
`claude-code-guide`	Claude Code 使用指南	有限工具

隔离模式

Agent 支持工作树（worktree）隔离：

主进程 (main branch)
├── Agent A (worktree: feature-a)
├── Agent B (worktree: feature-b)
└── Agent C (worktree: feature-c)

每个 Agent 获得独立的 git worktree 副本，修改互不影响。完成后 worktree 自动清理。

通信机制

单向通信：主进程通过 prompt 向 Agent 发送指令
结果回传：Agent 完成后返回单条消息给主进程
状态通知：<task-notification> XML 格式回传执行结果

<task-notification>
  <task-id>agent-123</task-id>
  <status>completed</status>
  <summary>研究完成，找到 3 处关键代码位置</summary>
  <result>详细结果文本...</result>
  <usage><total_tokens>15000</total_tokens></usage>
</task-notification>

3.2 任务管理系统

Claude Code 内置了完整的任务管理工具集：

TaskCreate  → 创建任务（subject + description）
TaskUpdate  → 更新状态（pending → in_progress → completed）
TaskList    → 列出所有任务
TaskGet     → 获取单个任务详情

任务支持依赖关系（blocks / blockedBy），系统会自动管理任务解锁逻辑。

3.3 定时任务（Cron）

CronCreate  → 创建定时任务（cron 表达式 + prompt）
CronDelete  → 删除定时任务
CronList    → 列出所有定时任务

调度器（src/utils/cronScheduler.ts）每秒 tick 一次，支持：

循环任务（recurring: true）：默认 7 天过期
一次性任务（recurring: false）：触发后自动删除
永久任务（permanent: true）：KAIROS 专用，不过期
会话级任务（durable: false）：仅内存，进程退出即消失

Jitter 防雷群机制：基于 taskId 的确定性延迟，避免全球用户在同一时刻集中请求 API。

4. Bash 工具与沙箱安全机制

4.1 Bash 工具架构

Bash 工具（src/tools/Bash/）是 Claude Code 与系统交互的核心通道，也是安全风险最高的工具。

4.2 沙箱隔离

Claude Code 实现了多层沙箱机制：

文件系统沙箱

工作目录限制：默认限制在项目目录内
只读路径：敏感系统目录设为只读
排除路径：.env、credentials.json 等敏感文件自动排除

进程沙箱

命令在隔离的子进程中执行
Shell 环境从用户 profile 初始化，但会话间状态不持久
支持超时控制（默认 2 分钟，最大 10 分钟）

权限分级

级别	说明
自动允许	读取文件、搜索内容等安全操作
需确认	写文件、运行命令等修改操作
禁止	破坏性操作（如 `rm -rf`、`git push --force`）

4.3 安全防护策略

Claude Code 在系统提示中内置了详细的安全准则：

不可逆操作需确认：删除、强制推送等操作必须获得用户明确授权
注入防护：防止命令注入、XSS、SQL 注入等 OWASP Top 10 漏洞
敏感文件保护：自动检测并警告 .env、密钥文件等
Git 安全协议：禁止跳过 hooks、禁止 force push 到 main 分支

4.4 后台任务支持

Bash 工具支持后台运行模式（run_in_background: true）：

命令在后台执行，不阻塞主对话
完成后自动通知
通过 TaskOutput 工具读取结果
通过 TaskStop 工具终止后台任务

5. 文件操作与编辑工具链

5.1 Read 工具

Read（src/tools/Read/）支持多种文件类型的读取：

类型	支持情况
文本文件	行号标注、范围读取
图片（PNG/JPG）	多模态视觉理解
PDF	分页读取（每请求最多 20 页）
Jupyter Notebook	代码 + 输出 + 可视化

设计原则：要求先 Read 再 Edit，确保 AI 了解现有内容后再做修改。

5.2 Edit 工具

Edit（src/tools/Edit/）采用精确字符串匹配替换策略：

{
  old_string: "要替换的原始文本",   // 必须在文件中唯一
  new_string: "替换后的新文本",
  replace_all: false               // 可选，全局替换
}

失败条件：old_string 不唯一或不存在时编辑失败。这防止了意外修改错误的位置。

5.3 Write 工具

Write（src/tools/Write/）用于创建新文件或完全覆写：

新建文件：直接写入
覆写已有文件：必须先 Read，否则报错
推荐优先 Edit：系统提示中明确建议优先使用 Edit 而非 Write

5.4 Glob 与 Grep

工具	引擎	用途
`Glob`	模式匹配	按文件名/路径模式查找文件
`Grep`	ripgrep	按内容正则搜索文件

两者都支持结果截断（head_limit）和排序（按修改时间）。

6. BUDDY — AI 电子宠物系统

源码位置：src/buddy/ 编译开关：feature('BUDDY')

6.1 系统概述

BUDDY 是一个完整的终端虚拟宠物系统，计划于 2026 年 4 月上线。它将拓麻歌子式的养成体验融入编程工作流。

6.2 物种与稀有度

18 种物种，5 级稀有度：

普通(60%) → 非凡(25%) → 稀有(10%) → 史诗(4%) → 传说(1%)

物种	物种	物种
鸭子	鹅	果冻
猫	龙	章鱼
猫头鹰	企鹅	蘑菇
乌龟	蜗牛	幽灵
六角恐龙	水豚	仙人掌
机器人	兔子	胖猫

闪光系统：独立于稀有度的 1% 闪光概率，任何宠物都可能成为闪光个体。

6.3 确定性生成

每只宠物通过确定性算法生成，不可篡改：

用户 ID + 盐值 'friend-2026-401'
    → FNV-1a 哈希
    → Mulberry32 PRNG
    → 物种/眼睛/稀有度/帽子/闪光/属性

只有"灵魂"数据（名字、性格、孵化时间）持久化。"骨架"数据（物种、稀有度等）每次从 userId 重新计算。

6.4 动画系统

精灵图：5 行高、12 字符宽的 ASCII 精灵
帧率：500ms/帧，15 帧序列循环
窄终端适配：< 100 列时退化为表情文字脸（如 =·ω·=）
气泡对话：10 秒显示，最后 3 秒渐隐

6.5 交互命令

命令	功能
`/buddy hatch`	孵化宠物（AI 生成名字和性格）
`/buddy pet`	抚摸（爱心上浮动画）
`/buddy card`	查看宠物卡片
`/buddy mute/unmute`	静音/取消静音
`/buddy reset`	放生宠物
`/buddy reroll`	重新换宠物

7. KAIROS — 永不关机的 Claude

源码位置：src/assistant/、src/proactive/、src/services/autoDream/ 编译开关：feature('KAIROS')

7.1 核心概念

KAIROS 将 Claude Code 从"一次性对话工具"变为"持久运行的 AI 助手"：

关闭终端后 Claude 仍在后台运行
每天自动写工作日志
晚上自动"做梦"整理记忆
没人说话时自己找活干

7.2 激活流程

feature('KAIROS')           ← 编译时 flag
  → settings.assistant: true  ← .claude/settings.json
  → 目录信任状态检查           ← 防恶意仓库劫持
  → tengu_kairos              ← GrowthBook 远程开关
  → setKairosActive(true)     ← 全局状态激活

7.3 做梦机制（Dream）

KAIROS 最精巧的子系统——后台自动运行的记忆整合子代理。

触发条件（三层门控）

1. 时间门控：距上次整合 > 24 小时
2. 会话门控：至少 5 个新会话
3. 锁门控：没有其他进程正在整合

阈值通过 GrowthBook tengu_onyx_plover 远程配置。

四阶段整合流程

阶段	动作
Orient	列出记忆目录、读取索引、浏览已有主题
Gather	从日志、已有记忆、transcript 中搜集新信号
Consolidate	合并新信号，转换日期，删除过时事实
Prune	更新索引，保持在限制内

锁机制

.consolidate-lock 文件 + PID 存活检查
1 小时超时，防多进程竞争
double-write + re-read 验证

7.4 主动模式（Proactive）

没人说话时 Claude 自己找活干：

系统提示："Take initiative -- explore, act, and make progress without waiting for instructions."
Tick 机制：接收周期性 <tick> 提示来检查是否有事可做
SleepTool：没活干就调用 Sleep 等着
状态管理：active / paused（用户按 Esc 暂停）/ contextBlocked（API 错误阻塞）

7.5 后台任务管理

任务类型	说明
一次性（`recurring: false`）	触发后删除，支持错过检测
循环（`recurring: true`）	重新调度，默认 7 天过期
永久（`permanent: true`）	KAIROS 专用，不过期
会话级（`durable: false`）	仅内存，进程退出即消失

8. ULTRAPLAN — 云端深度规划

源码位置：src/commands/ultraplan.tsx、src/utils/ultraplan/ 编译开关：feature('ULTRAPLAN') 访问限制：外部版完全不可用

8.1 核心概念

将复杂任务发送到云端的 Claude Code on the Web（CCR），由 Opus 模型独立研究最长 30 分钟。

8.2 工作流程

本地 CLI                            云端 CCR
   │                                   │
   │  /ultraplan <prompt>               │
   │ ──────────────────────────────────>│
   │                                   │  Opus 独立研究（30分钟）
   │  后台轮询等待                       │
   │ <─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ │
   │                                   │
   │  浏览器查看/修改方案                │
   │ ──────────────────────────────────>│
   │                                   │
   │  批准执行 / 传送回本地              │
   │ <──────────────────────────────────│

8.3 关键词触发

智能检测 "ultraplan" / "ultrareview" 关键词，自动排除：

引号内的出现
文件路径中的出现
标识符中的出现

8.4 Teleport 传送系统

底层传送机制实现本地 ↔ 远程会话的双向传输：

本地 → 远程：--remote [description] 创建远程 CCR 会话
远程 → 本地：--teleport [session-id] 恢复远程会话
Git Bundle 打包：传送时将代码上下文打包为 Git Bundle

8.5 访问限制

isEnabled: () => "external" === 'ant'  // 永远为 false

只有 Anthropic 内部员工（USER_TYPE === 'ant'）能使用。

9. Coordinator — 多 Agent 编排模式

源码位置：src/coordinator/ 编译开关：feature('COORDINATOR_MODE')

9.1 角色分离

角色	职责	可用工具
Coordinator（指挥官）	理解目标、拆解任务、综合结果	Agent、SendMessage、TaskStop
Worker（执行者）	具体代码操作	完整工具集

Coordinator 不直接操作代码，只负责指挥。

9.2 标准四阶段流程

阶段	执行者	目的
Research	Worker（并行）	调查代码库
Synthesis	Coordinator	综合发现，编写规格
Implementation	Worker	精准改动
Verification	Worker	测试验证

9.3 核心铁律：禁止甩锅式委派

Coordinator 必须自己做综合分析

禁止写 "based on your findings"
Prompt 必须包含具体文件路径、行号、改动内容
Worker 看不到 Coordinator 的对话，每个 prompt 必须完全自包含

9.4 并发管理

任务类型	策略
只读（研究）	自由并行
写操作（实施）	同组文件同时只能一个 Worker
验证	可在不同文件区域并行

10. Bridge — 远程遥控终端

源码位置：src/bridge/（33 个文件）编译开关：feature('BRIDGE_MODE')

10.1 核心概念

从 claude.ai 网页端或手机远程操控本地终端中的 Claude Code。

10.2 两种运行模式

独立模式（`claude remote-control`）

长运行服务器，支持 3 种 session 分发：

模式	说明
`single-session`	一个 session，结束后关闭
`worktree`	每个 session 获得隔离 git worktree
`same-dir`	所有 session 共享工作目录

REPL 内嵌模式（`/remote-control`）

在交互式 REPL 中启动
将当前对话镜像到 claude.ai
双向：本地和网页都能驱动同一个会话

10.3 两代传输协议

版本	传输层	特点
v1	WebSocket 读 + HTTP POST 写	完整环境生命周期管理
v2	SSE 读 + CCRClient 写	跳过环境层，直连 session-ingress

10.4 安全机制

OAuth 令牌：主身份凭证，自动刷新
Worker JWT：每 session 短期令牌
回声去重：环形缓冲区（2000 条）过滤自己发出的消息
401 恢复：自动 OAuth 刷新 + 重建传输层
JWT 主动刷新：到期前 5 分钟调度刷新

10.5 崩溃恢复

bridge-pointer.json 文件记录 session 状态：

session 创建后写入
运行中定期刷新 mtime
干净退出时清除
TTL 4 小时
下次启动检测到指针文件提供恢复选项

11. 26+ 隐藏命令与秘密开关

11.1 Feature-gated 命令

通过编译开关控制，外部版本中不可见：

命令	开关	功能
`/buddy`	`BUDDY`	电子宠物
`/proactive`	`PROACTIVE`/`KAIROS`	主动自主模式
`/assistant`	`KAIROS`	持久助手模式
`/brief`	`KAIROS`/`KAIROS_BRIEF`	简报模式
`/bridge`	`BRIDGE_MODE`	远程控制桥接
`/voice`	`VOICE_MODE`	语音交互
`/ultraplan`	`ULTRAPLAN`	云端深度规划
`/fork`	`FORK_SUBAGENT`	子代理分叉
`/peers`	`UDS_INBOX`	对等通信
`/workflows`	`WORKFLOW_SCRIPTS`	工作流脚本
`/torch`	`TORCH`	Torch 功能
`/force-snip`	`HISTORY_SNIP`	强制历史截断

11.2 仅内部命令（USER_TYPE === 'ant'）

命令	功能
`/teleport`	传送会话
`/bughunter`	Bug 猎人
`/ctx_viz`	上下文可视化
`/break-cache`	缓存清除
`/ant-trace`	内部追踪
`/autofix-pr`	自动修复 PR
`/agents-platform`	智能体平台
`/debug-tool-call`	调试工具调用

以及 /share、/summary、/subscribe-pr、/tags、/files、/env 等 24+ 个内部命令。

11.3 隐藏 CLI 参数

参数	功能
`--teleport [session]`	恢复传送会话
`--remote [description]`	创建远程会话
`--sdk-url <url>`	WebSocket 端点
`--advisor <model>`	服务端顾问
`--agent-id <id>`	队友代理 ID
`--plan-mode-required`	强制计划模式
`--parent-session-id <id>`	父会话 ID
`--proactive`	主动模式
`--remote-control`	远程控制
`--hard-fail`	硬失败模式

11.4 隐藏环境变量

变量	功能
`ANTHROPIC_MODEL`	覆盖默认模型
`CLAUDE_CODE_MAX_OUTPUT_TOKENS`	最大输出 token
`CLAUDE_CODE_DISABLE_THINKING`	禁用思考
`CLAUDE_CODE_PROACTIVE`	主动模式
`CLAUDE_CODE_COORDINATOR_MODE`	协调器模式
`CLAUDE_CODE_USE_BEDROCK`	使用 AWS Bedrock
`CLAUDE_CODE_USE_VERTEX`	使用 Google Vertex
`CLAUDE_CODE_EXTRA_BODY`	API 附加 JSON
`CLAUDE_CODE_IDLE_THRESHOLD_MINUTES`	空闲阈值（默认 75 分钟）
`CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`	最大工具并发数

12. 50 个编译开关与三层门控体系

12.1 三层门控架构

┌─────────────────────────────────────────────┐
│  第一层：编译时开关 feature()                  │
│  ~50 个，构建时决定代码包含/排除（DCE）         │
├─────────────────────────────────────────────┤
│  第二层：运行时 USER_TYPE                      │
│  'ant'（内部）vs 'external'（外部）             │
├─────────────────────────────────────────────┤
│  第三层：GrowthBook 远程 A/B 测试               │
│  tengu_ 前缀远程开关，动态灰度控制               │
└─────────────────────────────────────────────┘

12.2 第一层：编译时开关（完整列表）

核心功能开关

开关	说明
`BUDDY`	宠物伴侣系统
`KAIROS`	持久助手模式
`KAIROS_BRIEF`	简报模式
`KAIROS_CHANNELS`	通道通知
`KAIROS_GITHUB_WEBHOOKS`	GitHub Webhook
`ULTRAPLAN`	云端深度规划
`COORDINATOR_MODE`	多 Agent 编排
`BRIDGE_MODE`	远程控制桥接
`VOICE_MODE`	语音交互
`PROACTIVE`	主动自主模式
`FORK_SUBAGENT`	子代理分叉
`DAEMON`	守护进程模式

基础设施开关

开关	说明
`UDS_INBOX`	Unix Socket 收件箱
`WORKFLOW_SCRIPTS`	工作流脚本
`TORCH`	Torch 功能
`MONITOR_TOOL`	监控工具
`HISTORY_SNIP`	历史截断
`BG_SESSIONS`	后台会话
`HARD_FAIL`	硬失败模式
`CCR_REMOTE_SETUP`	Web 远程设置
`CHICAGO_MCP`	MCP 扩展（Computer Use）

优化与实验开关

开关	说明
`CACHED_MICROCOMPACT`	缓存微压缩
`CONTEXT_COLLAPSE`	上下文折叠
`REACTIVE_COMPACT`	响应式压缩
`QUICK_SEARCH`	快速搜索
`TOKEN_BUDGET`	Token 预算
`STREAMLINED_OUTPUT`	精简输出
`CONNECTOR_TEXT`	连接器文本
`TERMINAL_PANEL`	终端面板
`MESSAGE_ACTIONS`	消息操作

安全与合规开关

开关	说明
`ANTI_DISTILLATION_CC`	反蒸馏保护
`BASH_CLASSIFIER`	Bash 命令分类器
`NATIVE_CLIENT_ATTESTATION`	客户端证明
`TRANSCRIPT_CLASSIFIER`	转录分类器
`UNATTENDED_RETRY`	无人值守重试

数据与遥测开关

开关	说明
`EXTRACT_MEMORIES`	自动提取记忆
`MEMORY_SHAPE_TELEMETRY`	记忆形状遥测
`COWORKER_TYPE_TELEMETRY`	协作者遥测
`SLOW_OPERATION_LOGGING`	慢操作日志
`PROMPT_CACHE_BREAK_DETECTION`	缓存中断检测
`COMMIT_ATTRIBUTION`	提交归属标注

其他开关

开关	说明
`LODESTONE`	Lodestone 功能
`MCP_SKILLS`	MCP 技能系统
`EXPERIMENTAL_SKILL_SEARCH`	实验性技能搜索
`TEMPLATES`	模板/分类器
`TEAMMEM`	团队记忆同步
`FILE_PERSISTENCE`	文件持久化
`DOWNLOAD_USER_SETTINGS`	下载用户设置
`UPLOAD_USER_SETTINGS`	上传用户设置
`BREAK_CACHE_COMMAND`	缓存清除注入
`AGENT_TRIGGERS`	Cron 触发器系统

12.3 第二层：用户类型

USER_TYPE 在构建时被硬编码为 "external"。

值	身份	GrowthBook 刷新	额外能力
`ant`	Anthropic 内部	20 分钟	200+ 检查点、调试工具、全部命令
`external`	外部用户	6 小时	精简版

ant 专属能力包括：GrowthBook 覆盖（CLAUDE_INTERNAL_FC_OVERRIDES）、API 错误详情、推测性执行日志、24+ 内部命令、5xx 额外重试逻辑等。

12.4 第三层：GrowthBook 远程开关

开关	控制内容
`tengu_kairos`	KAIROS 助手模式总开关
`tengu_onyx_plover`	AutoDream 阈值配置
`tengu_cobalt_frost`	语音识别开关
`tengu_ultraplan_model`	Ultraplan 模型选择
`tengu_ant_model_override`	内部用户模型覆盖
`tengu_session_memory`	会话记忆功能
`tengu_sm_config`	会话记忆配置
`tengu_max_version_config`	自动更新 Kill Switch
`tengu_frond_boric`	数据接收器 Kill Switch
`tengu_herring_clock`	团队记忆路径
`tengu_ccr_bridge`	Bridge 远程控制总开关
`tengu_bridge_repl_v2`	Bridge v2 传输协议
`tengu_ccr_mirror`	CCR Mirror 模式
`tengu_scratch`	Coordinator Scratchpad
`tengu_kairos_cron_config`	Cron Jitter 配置

12.5 功能分层总结

外部用户能看到的
═══════════════════════════════
  基础 CLI 功能、公开命令

被 feature() 裁剪掉的
═══════════════════════════════
  BUDDY、KAIROS、ULTRAPLAN、
  BRIDGE、COORDINATOR、VOICE...

被 USER_TYPE 锁住的
═══════════════════════════════
  24+ 内部命令、调试工具、
  GrowthBook 覆盖能力

被 GrowthBook 远程控制的
═══════════════════════════════
  A/B 测试、灰度发布、
  Kill Switch、动态配置

13. MCP 协议集成

13.1 MCP 概述

Model Context Protocol（MCP）是 Claude Code 的扩展协议层，允许外部服务注册工具供 Claude 调用。

13.2 MCP 工具注册

MCP 工具以 mcp__<server>__<tool> 格式命名，系统会自动发现和注册：

通过 src/services/mcp/ 下的模块管理 MCP 连接
CHICAGO_MCP 编译开关控制 Computer Use 扩展
MCP_SKILLS 编译开关控制 MCP 技能系统

13.3 MCP 技能系统

MCP Skills（src/skills/）是预打包的知识和工具组合：

Claude API 技能：包含多语言的 API 使用文档和示例
Agent SDK 技能：自定义代理构建指南
技能通过 Skill 工具调用
EXPERIMENTAL_SKILL_SEARCH 开关控制实验性技能搜索

14. 记忆与上下文管理

14.1 记忆系统

Claude Code 实现了多层记忆系统：

层级	存储	生命周期
对话记忆	上下文窗口	单次对话
会话记忆	`.claude/` 目录	跨会话
项目记忆	`MEMORY.md`	持久化

14.2 自动记忆提取

当 EXTRACT_MEMORIES 编译开关启用时，系统自动从对话中提取关键信息写入记忆文件。

14.3 上下文压缩

当对话接近上下文窗口限制时，系统自动压缩早期消息：

CONTEXT_COLLAPSE：上下文折叠
REACTIVE_COMPACT：响应式压缩
CACHED_MICROCOMPACT：缓存微压缩

14.4 记忆文件结构

记忆系统使用 frontmatter 格式：

---
name: 记忆名称
description: 一行描述
type: user | feedback | project | reference
---

记忆内容...

MEMORY.md 作为索引文件，每条记忆占一行指针。

15. 权限系统与安全模型

15.1 三层权限模型

┌───────────────────────────┐
│ 自动允许（安全操作）         │  读取文件、搜索内容
├───────────────────────────┤
│ 需用户确认（修改操作）       │  写文件、执行命令
├───────────────────────────┤
│ 始终禁止（危险操作）         │  rm -rf、force push
└───────────────────────────┘

15.2 沙箱架构

Bash 工具的沙箱隔离：

文件系统限制：工作目录 + 只读系统路径
进程隔离：独立子进程，环境初始化但不持久
超时控制：默认 120 秒，最大 600 秒
后台模式：长时间命令自动转后台

15.3 安全准则（系统提示内置）

不可逆操作需确认
防注入（命令注入、XSS、SQL 注入）
敏感文件保护（.env、密钥文件）
Git 安全协议（禁止 --no-verify、禁止 force push main）
破坏性操作需确认（删除文件/分支、kill 进程）

15.4 反蒸馏保护

ANTI_DISTILLATION_CC 编译开关实现了反蒸馏保护机制，防止模型输出被用于训练竞争模型。

16. 编译与构建体系

16.1 构建系统

Claude Code 使用 Bun bundler 构建：

DCE（Dead Code Elimination）：未启用的 feature() 代码被完全移除
字符串替换：USER_TYPE 在构建时被替换为 "external" 或 "ant"
Source Map：生产构建包含 source map（这也是本次逆向的基础）

16.2 Feature 函数

// 来自 bun:bundle 的编译时函数
function feature(name: string): boolean {
  // 构建时被替换为 true/false
  // false 的分支被 DCE 移除
}

16.3 多版本构建

构建类型	USER_TYPE	Feature 集合
外部版	`external`	基础子集
内部版	`ant`	全部 50+

16.4 开发命令

bun install                    # 安装依赖
bun run dev                    # 启动开发 CLI
bun run start                  # 别名
bun run version                # 验证版本
bun run dev:buddy              # 带宠物功能启动

附录

A. 源码统计数据

指标	数量
TypeScript/TSX 文件	1,987
工具定义	53
斜杠命令	87+
React 组件	148
自定义 Hooks	87
编译开关	~50
GrowthBook 远程开关	19+
隐藏 CLI 参数	20+
隐藏环境变量	30+
Bridge 模块	33

B. 第三方模型集成

平台	环境变量
AWS Bedrock	`CLAUDE_CODE_USE_BEDROCK`
Google Vertex	`CLAUDE_CODE_USE_VERTEX`
Foundry	`CLAUDE_CODE_USE_FOUNDRY`

C. 数据来源

npm 包：@anthropic-ai/claude-code
还原方式：提取 cli.js.map 中的 sourcesContent
源码版权归 Anthropic 所有

D. 免责声明

本白皮书仅用于技术研究与学习
请勿用于商业用途
源码版权归 Anthropic 所有
如有侵权，请联系删除

白皮书完

Generated on 2026-04-04 · Based on @anthropic-ai/claude-code source map restoration

FilesExpand file tree

Claude-Code-Whitepaper.md

Latest commit

History