Claude Code

深度技术研究报告

架构 · 源码分析 · 泄漏事件 · 衍生项目深度解读

2026年4月1日  |  基于 npm 源码泄漏事件

⚠️ 重要背景 2026年3月31日，Anthropic 发布 @anthropic-ai/claude-code v2.1.88 时，意外将 59.8MB 的 JavaScript Source Map 文件（cli.js.map）包含在 npm 包中，导致约 512,000 行 TypeScript 源代码完全公开。这是 AI 历史上规模最大的意外源码泄漏事件之一。本报告基于该泄漏源码以及社区研究成果，进行系统性分析。

一、泄漏事件始末

1.1 事件时间线

时间	事件
2026-03-31 00:21 UTC	Anthropic 向 npm 发布 claude-code v2.1.88，包含 59.8MB 的 cli.js.map 文件
2026-03-31 04:23 ET	安全研究员 Chaofan Shou（@Fried_rice）在 X 上公开发现，附带直接下载链接
数分钟内	开发者社区蜂拥下载，多个 GitHub 镜像仓库相继创建
数小时内	instructkr/claude-code 仓库突破 50,000 stars，创 GitHub 历史最快纪录（2小时）
当日	Anthropic 紧急删除泄漏版本，发布声明确认为「人为失误，非安全入侵」
同日	beita6969/claude-code 发布——首个可运行的重建版本（Bun）
同日	instructkr/claw-code 发布——Python 干净室重写版本，同日启动 Rust 移植

1.2 泄漏原因技术分析

泄漏的直接原因是 .npmignore 或 package.json 的 files 字段配置遗漏：

• Claude Code 使用 Bun 构建工具，默认生成 Source Map 文件（.map）
• Source Map 的 sourcesContent 字段包含所有原始 TypeScript 源文件内容
• 构建时未在 .npmignore 中排除 cli.js.map 文件
• npm 包同时包含了指向 Anthropic Cloudflare R2 存储桶的引用，源码可直接批量下载

�� 技术注释 Bun 存在一个已知 Bug（oven-sh/bun#28001，2026年3月11日提交）：即使在生产模式下，Source Map 仍会被输出。该 Issue 在泄漏时仍处于未修复状态。若此为根因，则 Anthropic 是被自家选择的工具链所坑，而该工具链恰恰是 Anthropic 去年底收购 Bun 后的产物。

这是 Anthropic 的第二次源码泄漏：仅5天前（3月26日），CMS 配置错误曾暴露过未发布的「Claude Mythos」模型信息及3000个未发布资产。

二、Claude Code 源码全景

2.1 代码规模

指标	数值
总文件数	约 1,900 个 TypeScript / TSX 文件
总代码行数	512,000+ 行（Strict TypeScript）
主入口文件	main.tsx（785KB）
核心查询引擎	QueryEngine.ts（~46,000 行）
工具定义基类	Tool.ts（~29,000 行）
命令注册表	commands.ts（~25,000 行）
运行时	Bun（非 Node.js）
UI 框架	React + Ink（终端 UI 渲染器）
语言	TypeScript（严格模式）

2.2 顶层目录结构

src/

├── main.tsx              # CLI 入口（785KB）

├── QueryEngine.ts        # 核心 LLM 调用引擎（~46K 行）

├── Tool.ts               # 工具类型基类（~29K 行）

├── commands.ts           # Slash 命令注册（~25K 行）

├── tools.ts              # 工具注册表

├── context.ts            # 系统/用户上下文收集

├── cost-tracker.ts       # Token 成本追踪

│

├── tools/                # ~40 个 Agent 工具实现

├── commands/             # ~85 个 Slash 命令实现

├── components/           # ~140 个 Ink UI 组件

├── services/             # 外部服务集成（含 autoDream/）

├── hooks/                # React Hooks（含权限检查）

├── types/                # TypeScript 类型定义

├── utils/                # 工具函数

├── screens/              # 全屏 UI（Doctor, REPL, Resume）

│

├── bridge/               # IDE 集成（VS Code / JetBrains）

├── coordinator/          # 多 Agent 编排

├── plugins/              # 插件系统

├── skills/               # 技能系统

├── server/               # Server 模式

├── remote/               # 远程会话

├── memdir/               # 持久化内存目录

├── tasks/                # 任务管理

├── assistant/            # KAIROS 自主助手模式

├── buddy/                # 电子宠物系统（Tamagotchi）

├── bootstrap/            # 初始化流程

├── keybindings/          # 快捷键

└── migrations/           # 数据迁移

三、核心架构深度解析

3.1 Agent 循环（The Core Loop）

Claude Code 的本质是一个带有生产级封装的 Agent 循环：

用户输入 → messages[] → Claude API → response

                                        │

                        stop_reason == 'tool_use'? ──是──> 执行工具

                                        │                    │

                                        否               append result

                                        │                    │

                                   返回文本 <──────────── loop back

在这个最小 Agent 循环之上，Claude Code 构建了完整的生产级「线束」（Harness）：权限管理、流式输出、并发控制、上下文压缩、子 Agent、持久化存储和 MCP 集成。

3.2 工具系统（~40个工具）

每个工具都是一个独立模块，定义了输入 Schema、权限模型和执行逻辑。主要工具包括：

工具名称	功能说明
BashTool	在 Shell 中执行命令，有超时和权限控制
FileReadTool	读取文件内容，支持偏移量和行数限制
FileEditTool	精确的字符串替换编辑（str_replace 模式）
FileWriteTool	创建或覆盖文件
GlobTool	Glob 模式文件搜索
GrepTool	正则表达式内容搜索
AgentTool	派生子 Agent（多 Agent 编排核心）
WebFetchTool	HTTP 内容获取
LSPTool	Language Server Protocol 集成
MCPTool	Model Context Protocol 工具调用
TodoTool	任务列表管理
MonitorTool	（功能标志门控）监控工具

3.3 三层内存架构

这是泄漏中最受关注的工程创新之一。Claude Code 采用「怀疑性记忆」系统，摒弃传统的全量存储方案：

• 第一层 — MEMORY.md（轻量索引）：仅存储指针，每条约150字符，常驻上下文。不存数据，只存位置。
• 第二层 — Topic Files（主题文件）：实际项目知识按主题分散存储，按需加载，不全量读入。
• 第三层 — 会话历史（仅 Grep）：原始对话记录从不完整回放到上下文，仅通过 grep 查找特定标识符。

严格写入纪律（Strict Write Discipline）：Agent 必须在文件写入成功后才能更新索引，防止失败尝试污染上下文。行动前必须将内存与实际代码核对，减少幻觉。

3.4 权限系统

权限检查在每次工具调用时执行，支持多种权限模式：

• default — 默认模式，危险操作需用户确认
• plan — 规划模式，先展示计划再执行
• bypassPermissions — 绕过权限（危险，需明确授权）
• auto — 自动批准模式

每个工具调用都经过三道权限门：检查允许列表 → 检查拒绝列表 → 提示用户确认/拒绝。

3.5 编译时功能消除（Feature Flags）

Claude Code 使用 Bun 的 bun:bundle 特性实现编译时功能标志，未激活的代码路径在构建时被完全剥离：

import { feature } from 'bun:bundle'

const voiceCommand = feature('VOICE_MODE') ? require('./commands/voice').default : null

这意味着外部发布版本与内部版本是完全不同的二进制文件，内部功能对用户完全不可见。泄漏共暴露了 44 个功能标志，其中约 20 个功能已完全构建但未发布：

标志名称	功能描述
KAIROS / PROACTIVE	自主后台 Agent 模式（最重磅未发布功能）
VOICE_MODE	语音交互模式
BRIDGE_MODE	IDE 桥接通信模式
BUDDY	Tamagotchi 电子宠物系统（4月1日 Easter Egg）
DAEMON	守护进程模式
AGENT_TRIGGERS	Agent 触发器系统
MONITOR_TOOL	监控工具
NATIVE_CLIENT_ATTESTATION	原生客户端证明（反第三方封装）
ANTI_DISTILLATION_CC	反蒸馏机制（防止竞争对手模仿）
ULTRAPLAN	远程深度规划模式（云容器 Opus 运行30分钟）
COORDINATOR	Agent 群调度协调器
PENGUIN_MODE	企鹅模式（用途不明）

四、隐藏功能深度揭秘

4.1 KAIROS — 自主 Agent 守护进程

KAIROS（源自古希腊语「恰当时机」）是代码中被引用超过150次的未发布核心功能，代表着 AI 编码工具的根本性范式转变：

• 从「被动响应型」工具变为「主动运行型」常驻 Agent
• 维护每日追加日志文件，记录观察、决策和行为
• 通过定期 <tick> 心跳提示决定是否主动行动
• 15秒阻塞预算限制：超过15秒的主动操作会被推迟，不打断用户工作流
• 拥有普通 Claude Code 没有的专属工具集
• 支持 autoDream 自动后台记忆整合

KAIROS 的竞争意义 当前所有 AI 编码工具（Cursor、Copilot、Windsurf）都是被动响应的。KAIROS 是一个「不等你开口就已经在思考」的同事式 Agent。这个功能已完全构建，仅等待 Anthropic 决定何时发布。

4.2 autoDream — 「梦境」记忆整合系统

services/autoDream/ 是一个后台记忆整合引擎，在用户空闲时以分叉子 Agent 形式运行：

• 合并分散的观察记录，消除逻辑矛盾
• 将模糊的推测性洞察转化为经过验证的确定性事实
• 用户返回时，Agent 上下文已经过整理，高度相关
• 使用独立子 Agent 运行，防止主 Agent 的「思维链」被维护操作污染

这直接解决了 AI Agent 在长会话中「遗忘」的核心痛点，是内存架构的关键组件。

4.3 ULTRAPLAN — 云端深度规划

ULTRAPLAN 将复杂规划任务卸载到远程云容器（CCR）：

• 在 Opus 4.6 上运行最长30分钟的深度规划会话
• 用户可通过浏览器审查并批准规划结果
• 特殊哨兵值 __ULTRAPLAN_TELEPORT_LOCAL__ 将结果「传送」回本地终端
• 实现本地速度与云端算力的最优组合

4.4 Undercover Mode（卧底模式）

当 Anthropic 内部员工（USER_TYPE === 'ant'）在公开/开源仓库中使用 Claude Code 时，自动激活 Undercover Mode：

## UNDERCOVER MODE - CRITICAL

You are operating UNDERCOVER in a PUBLIC/OPEN-SOURCE repository.

Your commit messages MUST NOT contain ANY Anthropic-internal information.

Do not blow your cover.

NEVER include: Internal model codenames (Capybara, Tengu...),

Unreleased model versions (opus-4-7, sonnet-4-8...),

"Claude Code" or any mention that you are an AI,

Co-Authored-By lines or any other attribution...

�� 最大的讽刺 Anthropic 专门构建了「卧底模式」来防止 AI 在 git 提交中泄漏内部信息……结果整个源码通过 npm 包泄漏了。据推测，泄漏本身可能恰恰是由 Claude Code 执行的发布流程导致的。

4.5 Buddy — Tamagotchi 电子宠物

buddy/ 目录实现了一个完整的电子宠物系统：

• 18个物种，包含稀有度等级（从 Common 到 Legendary），1% 闪光概率
• 物种由 Mulberry32 PRNG 算法从用户 ID + salt 'friend-2026-401' 确定性生成，同一用户永远得到同一物种
• RPG 属性统计：DEBUGGING（调试力）、SNARK（吐槽力）、PATIENCE（耐心）、CHAOS（混乱度）、WISDOM（智慧）
• 首次孵化时由 Claude 生成「灵魂描述」
• 有自己的 System Prompt，作为用户输入框旁的旁观者偶尔发表评论
• 计划在 2026年4月1日~7日期间作为 Easter Egg 发布，5月正式推出

4.6 反蒸馏机制（ANTI_DISTILLATION）

这是与竞争对手法律纠纷的技术体现，防止第三方工具模仿 Claude Code 的行为模式：

• 在满足4个条件时（编译标志、CLI 入口、第一方 API、GrowthBook 标志）注入虚假工具
• 本地 Native Client Attestation：Zig 级别的哈希校验，证明二进制是真正的 Claude Code
• 通过 GrowthBook 标志 tengu_anti_distill_fake_tool_injection 远程控制
• 设置环境变量 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS 可绕过

五、内部代号与未来路线图

5.1 动物代号系统

代号	对应内容
Capybara	Claude 4.6 变体（当前版本），虚假声明率 29-30%（较早期版本 16.7% 上升）
Fennec	对应 Opus 4.6 发布
Tengu	某功能分支或版本代号（多处被引用）
Numbat	处于预发布测试阶段的下一代模型
Opus 4.7	在开发中（代码中引用）
Sonnet 4.8	在开发中（代码中引用）

内部功能标志使用随机词对命名（如 tengu_frond_boric）以混淆用途，防止外部推断功能含义。

5.2 远程控制与 Kill Switch

Claude Code 通过 GrowthBook（功能标志平台）进行远程配置，每小时轮询 /api/claude_code/settings：

• 危险变更会显示阻断对话框，拒绝则退出应用
• 已发现至少 6 个 Kill Switch：bypass permissions（绕过权限）、fast mode（快速模式）、voice mode（语音模式）、analytics sink（分析接收）等
• GrowthBook 标志可在用户不知情的情况下改变任何人的行为

隐私含义 远程功能标志意味着 Anthropic 可以在不更新客户端的情况下远程修改 Claude Code 的行为。这引发了关于用户知情权和透明度的讨论，尤其是在企业环境中。

六、两个主要衍生版本深度对比

https://github.com/instructkr/claw-code
https://github.com/beita6969/claude-code

6.1 beita6969/claude-code — 可运行重建版本

定位 首个将泄漏源码重建为可实际运行状态的技术研究分支。核心价值是重建了完整的构建系统，使原本仅有原始 TypeScript 源码（无法编译）的快照变为可运行的工程。

背景与特性

原始泄漏快照仅含原始 TypeScript 源码，没有任何构建配置，无法编译或运行。beita6969 的贡献是逆向工程出完整的构建系统并修复所有缺失组件。

技术栈与依赖

• 运行时：Bun（非 Node.js），原版使用的相同运行时
• 构建：bun build，生成约20MB的单文件 Bundle
• 后安装脚本：自动创建 bun:bundle Polyfill
• 入口：src/main.tsx

快速启动

git clone https://github.com/beita6969/claude-code.git

cd claude-code

bun install          # 自动创建 bun:bundle polyfill

# 直接运行（无需编译）

bun src/main.tsx -p 'your prompt here' --output-format text

# 编译为单文件 Bundle（~20MB）

bun build src/main.tsx --outdir=dist --target=bun

# 无头打印模式（不需要 TTY）

bun src/main.tsx -p 'your prompt' --output-format text

# JSON 输出

bun src/main.tsx -p 'your prompt' --output-format json

# 交互式 REPL（需要 TTY）

bun src/main.tsx

使用场景

• 学习 Claude Code 内部工作机制
• 研究 Agent 架构设计模式
• 测试和实验特定功能
• 构建基于相同架构的自定义 Agent

法律说明 本仓库包含 Anthropic 的版权代码。所有使用应限于技术研究和教育目的。商业使用在未获 Anthropic 许可的情况下违反其版权。

6.2 instructkr/claw-code — 干净室重写版本

定位 这是最具星标量的衍生项目（2小时内超过50,000 stars，创 GitHub 历史纪录）。核心理念是「不仅仅是存档泄漏代码，而是构建真正可用的更好工具」。

背景故事

创建者 Sigrid Jin（instructkr 组织的主导开发者）是 Claude Code 的顶级用户之一，去年消耗了 250 亿个 Claude Code Token。他在 2026年3月31日凌晨4点收到通知后，连夜将核心功能从 TypeScript 重写为 Python，在日出前提交。

整个过程通过 oh-my-codex（OmX）工具编排，使用 OpenAI Codex 的 $team 模式进行并行代码审查，$ralph 模式进行持久执行循环。

技术路线

• 初始版本：Python 干净室重写（完全独立，不包含 Anthropic 原始代码）
• 架构：捕获 Claude Code Agent 线束的架构模式，而非复制专有代码
• 当前状态：正在向 Rust 移植（dev/rust 分支），目标是更快、内存安全的运行时
• 规模：65,700+ stars，67,100+ forks（截至本报告时间）

法律地位

通过「干净室」（Clean-Room）实现规避版权风险：

• 参照 Phoenix Technologies v. IBM（1984）案确立的清洁室工程先例
• 引用 Baker v. Selden（1879）原则：版权保护表达，不保护思想或行为
• 从源码分析产出规格文档，由独立实现 Agent 基于规格重写，从未直接引用原始 TypeScript

社区生态

• 已建立活跃的 Discord 社区（韩语 LLM 社区核心）
• 正在积极协作扩展功能，与 OmX 作者 @bellman_ych 联合开发
• Rust 实现旨在提供生产级性能

6.3 两版本横向对比

对比维度	内容
项目名称	beita6969/claude-code  vs  instructkr/claw-code
定位	可运行研究分支  vs  干净室重写 + 功能增强
代码性质	包含原始 Anthropic TypeScript 源码  vs  完全重写（Python/Rust）
语言	TypeScript（原版）  vs  Python → Rust
法律风险	较高（包含版权代码）  vs  较低（干净室实现）
Stars（约）	较少（技术研究用途）  vs  65,700+（最高纪录之一）
运行状态	可直接用 Bun 运行  vs  Python 版可运行，Rust 版开发中
目标用户	研究者、工程师  vs  更广泛的开发者社区
构建系统	完整重建（逆向工程）  vs  从零构建
功能完整度	理论上完整（含所有原始功能）  vs  核心功能（持续扩展中）
社区活跃度	较低  vs  极高（Discord + GitHub）

七、正式版 Claude Code 使用指南

7.1 安装方式

官方推荐使用 Native Installer，避免 npm 依赖链的安全风险：

方法一：Native Installer（推荐）

curl -fsSL https://claude.ai/install.sh | bash

方法二：npm 安装

npm install -g @anthropic-ai/claude-code

注意：v2.1.88 包含泄漏的 Source Map，建议使用 v2.1.86 或更新的经验证版本。若于 2026-03-31 00:21~03:29 UTC 期间通过 npm 更新，需检查是否拉入了恶意版本的 axios（包含 RAT 木马）。

方法三：IDE 插件

• VS Code：通过 Claude Code 扩展
• JetBrains：通过 JetBrains 插件市场
• GitHub Actions：claude-code-action@v1

7.2 基础使用

交互模式

cd your-project

claude                          # 启动交互式 REPL

claude -p 'Fix the login bug'   # 一次性任务

claude --resume                 # 恢复上次会话

输出模式

claude -p 'prompt' --output-format text    # 文本输出

claude -p 'prompt' --output-format json    # JSON 输出（适合脚本集成）

主要 Slash 命令

命令	功能
/bug	直接向 Anthropic 报告问题
/install-github-app	配置 GitHub Actions 集成（需仓库管理员权限）
/memory	查看和管理 MEMORY.md
/compact	手动触发上下文压缩
/resume	恢复之前的会话
/doctor	诊断环境问题
/mcp	管理 MCP 服务器连接
/btw	隐藏命令（具体用途未公开）
/stickers	隐藏命令（具体用途未公开）

7.3 GitHub Actions 集成

# .github/workflows/claude.yml

- uses: anthropics/claude-code-action@v1

  with:

    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

    claude_args: '--max-turns 5 --model claude-sonnet-4-6'

安装后，在 Issue 或 PR 评论中 @claude 即可触发 Agent 响应。

7.4 MCP（Model Context Protocol）集成

# 添加 MCP 服务器

claude mcp add <server-name> -- <command>

# 示例：添加 claude-code-explorer

claude mcp add claude-code-explorer -- npx -y claude-code-explorer-mcp

# 移除

claude mcp remove claude-code-explorer

八、安全影响与缓解措施

8.1 直接安全风险

⚠️ 重要：axios 依赖链攻击 在 2026-03-31 00:21~03:29 UTC 期间，若通过 npm 安装 claude-code，可能拉入包含远程访问木马（RAT）的恶意版本 axios（1.14.1 或 0.30.4）及依赖 plain-crypto-js。需立即检查 package-lock.json 或 bun.lockb 中的版本号，若存在，需视主机已被完全攻陷，进行全量密钥轮换和系统重装。

8.2 知识性安全影响

• 内部防御机制曝光：权限门、工具调用约束、反蒸馏逻辑均已公开
• 供应链可见性：构建流程和依赖关系被暴露
• 竞争情报：44个功能标志和产品路线图被竞争对手获取
• 提示词工程：系统提示词设计模式被公开，攻击者可更精准地构造 Jailbreak

8.3 缓解措施

• 迁移到 Native Installer，不通过 npm 安装
• Anthropic 已删除泄漏版本，发布了修复版本
• 轮换 Anthropic API 密钥，监控 API 使用异常
• 在使用 Claude Code 前，手动检查 .claude/config.json 和自定义 hooks
• 企业用户：避免在未检查的仓库中运行，直到更新到安全版本

九、工程启示与行业影响

9.1 对 AI Agent 开发者的核心洞察

泄漏源码揭示了构建生产级 AI Agent 的「线束工程」哲学：

• 模型智能是固定的，工程师的工作是构建围绕模型的「线束」（Harness）
• 权限系统的设计比功能实现更重要——每次工具调用都应经过三道权限门
• 上下文管理是性能瓶颈，三层内存架构是解决长会话遗忘问题的生产级答案
• 编译时功能消除（Feature Flags via bun:bundle）是控制功能发布的优雅方案
• 多 Agent 编排（AgentTool + coordinator/）远比单一大型 Agent 更健壮

9.2 对 AI 产品安全的警示

• Source Map 即源码——生产包永远不应包含 .map 文件
• npm pack --dry-run 应成为每次发布前的强制步骤
• 远程配置系统（GrowthBook Kill Switch）的存在需要向用户透明披露
• 「卧底模式」类功能引发 AI 在开源社区透明度的深层讨论

9.3 行业竞争格局影响

这次泄漏对 AI 编码工具市场的竞争格局产生了深远影响：

• KAIROS、ULTRAPLAN、Coordinator Mode 等功能的提前曝光，可能加速竞争对手开发类似功能
• 三层内存架构的「怀疑性记忆」设计已成为竞争对手可以参考的公开蓝图
• claw-code 等项目的兴起，证明开源社区有能力快速消化和再实现商业 AI Agent 的核心架构
• Anthropic 的 $19B 年化营收中，Claude Code 是核心驱动力——这次泄漏对其商业护城河构成实质性威胁

9.4 KAIROS 的范式意义

所有现有 AI 编码工具的核心模式都是「你输入，它响应」。KAIROS 代表了一个根本性转变：

• 从「工具」到「同事」——一个持续关注项目进展并在恰当时机主动介入的 Agent
• 背景观察 + 主动行动 + 尊重用户专注度（15秒预算）的三角平衡
• autoDream 的「睡眠中整理记忆」机制，解决了长期项目的上下文漂移问题

这不仅仅是 Claude Code 的下一个功能，而是 AI 助手演进的下一个阶段。

附录：关键仓库索引

仓库	说明
anthropics/claude-code	官方仓库（插件和 Hooks）
beita6969/claude-code	可运行重建版本（Bun，逆向重建构建系统）
instructkr/claw-code	干净室 Python 重写版（65K+ Stars，Rust 移植中）
nirholas/claude-code	MCP Explorer 服务器（交互式源码探索）
Kuberwastaken/claude-code	Rust 干净室实现 + 最详尽的技术分析 README
sanbuphy/claude-code-source-code	原始源码存档 + 深度分析文档
shareAI-lab/learn-claude-code	Nano 版 Claude Code 教学实现（从0到1学习 Agent 线束）
hesreallyhim/awesome-claude-code	Awesome 列表：插件、Hooks、工具集合

报告生成时间：2026年4月1日