2026年3月31日，Anthropic 的 Claude Code 因 npm 包中误留 source map 文件，导致完整 TypeScript 源码意外泄露。本文基于泄露的源码进行深度解析。

一、事件背景与源码规模

1.1 泄露事件回顾

2026年3月31日，安全研究员 Chaofan Shou (@Fried_rice) 发现 @anthropic-ai/claude-code npm 包中包含了未剥离的 .map 文件，通过该文件可完整还原原始 TypeScript 源码。泄露的源码托管在 Anthropic 的 R2 存储桶中，任何人都可直接下载。

关键数据：

1.2 技术栈全景

Claude Code 的技术选型体现了现代 CLI 工具的工程化水准：

• 运行时：Bun（高性能 JavaScript 运行时）

• UI 框架：React + Ink（终端 React 渲染器）

• CLI 解析：Commander.js

• 校验库：Zod v4

• 搜索：ripgrep（代码搜索）

• 追踪：OpenTelemetry + gRPC

• 协议集成：MCP SDK、LSP 协议

二、整体架构设计

2.1 六层分层架构

Claude Code 采用清晰的六层分层架构，松耦合设计便于维护和扩展：

┌─────────────────────────────────────────────────────────┐
│  入口层 │ main.tsx + setup.ts │ 启动与初始化              │
├─────────────────────────────────────────────────────────┤
│  展示层 │ React + Ink │ 终端 UI 渲染                    │
├─────────────────────────────────────────────────────────┤
│  核心引擎 │ QueryEngine (46K行) │ LLM 对话处理           │
├─────────────────────────────────────────────────────────┤
│  执行层 │ Tool System + Command System │ 实际操作执行    │
├─────────────────────────────────────────────────────────┤
│  协作层 │ Multi-Agent + Bridge │ 复杂任务协作           │
├─────────────────────────────────────────────────────────┤
│  管理层 │ 权限 + 配置 + 状态 │ 系统稳定性保障           │
└─────────────────────────────────────────────────────────┘

2.2 源码目录结构

泄露的 src/ 目录结构揭示了完整的模块化设计：

src/
├── entrypoints/          # 入口层：cli.tsx, init.ts, mcp.ts, sdk/
├── commands/             # 87+ 斜杠命令处理器
├── tools/                # 43 个内置工具实现
├── services/             # 运行时服务（api, mcp, tools, compact, analytics）
├── components/           # 148 个 Ink 终端 UI 组件
├── hooks/                # 85 个 React Hooks
├── utils/                # 564 个辅助函数
├── state/                # 集中式状态管理
├── coordinator/          # 多 Agent 协调器
├── agents/               # 内置 Agent 定义
├── memdir/               # 记忆持久化层
├── buddy/                # 电子宠物系统（彩蛋）
├── assistant/            # KAIROS 持久模式
├── bridge/               # 远程控制协议
├── tasks/                # 后台任务系统
├── voice/                # 语音输入管道
└── vim/                  # Vim 模式模拟

三、核心引擎：QueryEngine

3.1 职责与能力

QueryEngine.ts（约 46,000 行）是整个系统的"大脑"，负责处理所有 LLM 交互：

• 上下文管理：收集 Git 状态、CLAUDE.md、环境信息

• LLM 交互：API 调用、流式响应处理

• 工具调度：工具调用解析、结果处理

• 权限验证：工具执行前的权限检查

• 重试逻辑：API 失败时的退避重试

• 费用追踪：Token 计数与成本计算

3.2 Query Loop 核心循环

源码中的核心执行流程：

用户输入 → createUserMessage()
    ↓
追加到对话历史
    ↓
构建系统提示词（CLAUDE.md + 工具 + 上下文 + 记忆）
    ↓
流式调用 Claude API
    ↓
解析响应 token → 增量渲染终端
    ↓
if tool_use 块:
    → findToolByName() → canUseTool()
    → StreamingToolExecutor（支持并发）
    → 收集工具结果 → 循环回 API
    ↓
显示最终响应（Markdown 渲染）
    ↓
后处理钩子（自动压缩 · 记忆提取 · 夜间整合）
    ↓
等待下一轮输入

四、工具系统：43 个内置工具

4.1 工具分类全景

Claude Code 的工具系统是其"执行体"能力的核心：

文件操作类

• FileReadTool - 读取文件

• FileEditTool - 精确字符串替换编辑

• FileWriteTool - 写入新文件

• GlobTool - 文件模式匹配

• GrepTool - 内容搜索（ripgrep 驱动）

• NotebookEditTool - Jupyter Notebook 编辑

命令执行类

• BashTool - Shell 命令执行

• PowerShellTool - Windows PowerShell 执行

Agent 与协作类

• AgentTool - 子 Agent 生成与编排

• SendMessageTool - Agent 间通信

• TaskCreateTool - 后台任务创建

• CoordinatorTool - 协调器模式

MCP 集成类

• MCPTool - 动态 MCP 工具包装器

• ListMcpResourcesTool - 列出 MCP 资源

• ReadMcpResourceTool - 读取 MCP 资源

网络类

• WebFetchTool - HTTP 请求 + HTML→Markdown

• WebSearchTool - 网络搜索

系统与工具类

• AskUserQuestionTool - 询问用户

• TodoWriteTool - TODO 文件管理

• SkillTool - 技能调用

• SleepTool - 动作间暂停（功能门控）

4.2 工具的 Prompt 注入机制

每个工具目录下都有独立的 prompt.ts 文件——这是专门写给 LLM 看的"使用手册"。例如 BashTool 的提示词约 370 行，详细规定了使用规范。这些规则在启动时动态注入系统提示词。

4.3 安全设计："先读后改"铁律

FileEditTool 会强制检查是否已用 FileReadTool 读取过目标文件。未读取直接报错，确保 AI 先理解再修改。

五、Agent 协作系统

5.1 多 Agent 架构

Claude Code 不是单一 Agent，而是一套多 Agent 协作系统：

Coordinator 模式：协调器本身只有三个工具——派活（Agent）、通信（SendMessage）、停工（Shutdown）。Worker 作为独立子进程，拥有完整工具集。

角色分离：

• 系统提示明确规定"禁止甩锅式委派"，不能把不清楚的需求直接丢给 Worker

• 子 Agent 有严格的"自我意识"注入："You are a worker, not a manager. Don't try to hire more people, do the work yourself."

5.2 子 Agent 的缓存优化

为了最大化 prompt cache 命中率，所有 fork 子代理的工具结果使用相同占位符文本："Fork started—processing in background"。如果 10 个子 Agent 的前缀字节完全一致，只有第一个需要冷启动，后续 9 个直接命中缓存。

六、安全与权限系统

6.1 三级门控机制

Claude Code 采用三层门控确保安全：

6.2 四层安全流水线

当 AI 执行操作时，后台的安全分类器独立评估：

1. 规则匹配层：命中已有规则直接放行

2. 低风险过滤层：识别低风险操作，跳过后续

3. 白名单层：只读工具自动放行

4. AI 审查层：调用独立 Claude Sonnet 做安全分类（温度设为 0，保证确定性）

6.3 熔断机制

连续 3 次被拒或累计 20 次被拒后，系统自动降级为手动确认模式。

七、性能优化策略

7.1 启动优化：并行预取

源码 main.tsx 前 19 行采用并行预取，减少启动时间约 135ms：

const tasks = Promise.all([
  profileCheckpoint(),      // 性能分析
  startMdmRawRead(),        // MDM 配置读取
  startKeychainPrefetch()   // OAuth/API 钥匙串预取
])

7.2 延迟加载

重模块按需动态导入：OpenTelemetry、gRPC、分析模块等在实际需要时才执行 import()。

7.3 Prompt Cache 边界设计

源码中定义 SYSTEM_PROMPT_DYNAMIC_BOUNDARY 常量：

• 边界前：静态内容，所有用户共享，可缓存

• 边界后：动态内容（Git 状态、CLAUDE.md、记忆），每用户独立

这体现了"Prompt assembly with cache economics"的工程思维。

八、上下文压缩机制

8.1 三层压缩策略

为防止上下文超限，Claude Code 设计了渐进式压缩：

8.2 结构化压缩模板

完全压缩采用 9 段式提取方案，确保关键信息不丢失：

1. 核心请求

2. 关键概念

3. 文件和代码

4. 错误和修复

5. 解决过程

6. 所有用户消息（必须完整保留）

7. 待办任务

8. 当前工作

9. 下一步行动

九、记忆系统

9.1 记忆提取机制

Claude Code 不是简单的向量检索，而是用独立的 Claude Sonnet 模型决定"哪些记忆与当前对话相关"：

• 扫描所有记忆文件的标题和描述

• 最多选出 5 个最相关的

• 完整内容注入上下文

• 策略：精确度优先于召回率

9.2 记忆分类

源码将记忆分为四类：

• user - 用户偏好

• feedback - 行为反馈

• project - 项目信息

• reference - 外部资源

9.3 "不记代码"原则

记忆不存储代码事实，只存储人的偏好和判断。代码永远从源码中实时读取，避免因代码重构导致记忆过期。

十、隐藏功能大揭秘

10.1 KAIROS 模式

KAIROS 是一个尚未发布的守护进程系统，源码中出现 154 次：

• 跨会话持久运行：通过 .claude/settings.json 的 assistant: true 激活

• 每日日志：自动记录工作日志

• 自动 Dream：满足条件（>24 小时 + 5+ 新会话）时自动整合记忆

• 主动模式：无人说话时自己找活干

10.2 BUDDY 系统（电子宠物）

src/buddy/ 目录下藏着一套完整虚拟宠物系统：

• 物种：18 种（鸭、鹅、猫、龙、章鱼、水豚、仙人掌、蘑菇等）

• 稀有度：common (60%) → uncommon (25%) → rare (10%) → epic (4%) → legendary (1%)

• 属性：DEBUGGING、PATIENCE、CHAOS、WISDOM、SNARK

• 闪光概率：1%

• 交互命令：/buddy hatch、/buddy pet、/buddy card

10.3 其他隐藏特性

十一、启示与总结

11.1 Claude Code 的本质

Claude Code 不是简单的"套壳 CLI"，而是一套完整的 Agent Operating System：

Prompt 不是静态文本，而是模块化 runtime assembly
Tool 不是直接裸调，而是走 permission/hook/analytics 的执行管道
Agent 不是万能 worker，而是多角色分工系统
Skill 是 prompt-native workflow package
Plugin 是 prompt + metadata + runtime constraint 的扩展机制

11.2 核心设计哲学

1. Harness Engineering：围绕模型搭建工程系统，把 AI 从"能力强但不可预测"变成"稳定可靠能交付"

2. Cache Economics：把 Token 成本纳入架构设计，系统级优化缓存命中率

3. 渐进式功能发布：通过 feature flags 控制功能上线，支持 A/B 测试

4. 安全优先：fail-closed 设计，宁可过度保守也不遗漏风险