Claude Code 源码泄漏：技术架构深度解构

版本：v2.1.88 | 泄漏时间：2026年3月31日 | 来源：npm 包 source map 重建

一、整体架构概述

Claude Code 是一个基于终端的 AI 编程助手，核心采用 TypeScript + React（Ink） 构建，运行在 Node.js/Bun 之上。它并非简单的 prompt wrapper，而是一个完整的状态机驱动的交互式 CLI 应用。

┌─────────────────────────────────────────────────────────────────┐
│                        Claude Code CLI                          │
├─────────────────────────────────────────────────────────────────┤
│  entrypoints/cli.tsx    — Commander.js 参数解析，快路径优化      │
│  entrypoints/init.ts    — 遥测、配置、认证初始化                 │
│  entrypoints/mcp.ts     — MCP 服务器入口                         │
├─────────────────────────────────────────────────────────────────┤
│                     React/Ink 终端 UI 层                         │
│  screens/REPL.tsx       — 主交互界面（2800+ 行）                  │
│  components/            — 140+ React 组件                       │
│  ink/                   — 自定义 Ink 分支（flexbox 布局引擎）      │
├─────────────────────────────────────────────────────────────────┤
│                     核心逻辑层                                   │
│  tools/                 — ~40 个 Agent Tool                      │
│  commands/              — ~50 个斜杠命令                          │
│  services/              — API、LSP、OAuth、Analytics、MCP       │
│  utils/hooks/           — 155 个 Hook 文件（异步注册/执行引擎）   │
│  utils/plugins/         — 插件系统（65+ 文件）                   │
│  utils/permissions/     — 权限 & 自动模式分类器（52KB LLM）       │
├─────────────────────────────────────────────────────────────────┤
│                     底层能力层                                   │
│  native-ts/             — TypeScript 端口（Yoga Layout、nucleo） │
│  stubs/@anthropic-ai/   — SDK 源码（bedrock、vertex、foundry）  │
│  stubs/@ant/            — 私有包（computer-use-mcp、chrome）    │
│  sandbox-runtime/       — 沙箱执行（Linux namespace + seccomp） │
└─────────────────────────────────────────────────────────────────┘

二、入口与启动流程

2.1 命令行入口（cli.tsx）

cli.tsx 使用 Commander.js 解析参数，核心设计是快路径优先：

// --version 零导入直接返回
if (args[0] === '--version') {
  console.log(`${MACRO.VERSION} (Claude Code)`);
  return;
}

// 慢路径才加载完整模块
const { profileCheckpoint } = await import('../utils/startupProfiler.js');

关键快路径：

--version / -v — 零模块加载
--dump-system-prompt — 输出渲染后的系统 prompt（Ant 专用）
--chrome-native-host — Chrome 集成
--computer-use-mcp — 计算机使用 MCP 服务器
--daemon-worker — 守护进程工作线程

2.2 初始化流程（init.ts）

完整初始化执行：

遥测关闭检查 — ANTHROPIC_DISABLE_TELEMETRY 环境变量
DataDog/GrowthBook 集成 — 实验特性平台
OAuth 认证流程 — GitHub / Google 登录
自动更新检查（已 patch 禁用远程检查）
后台任务队列初始化

2.3 特性标志系统

源码大量使用 feature('FLAG_NAME') 进行 Dead Code Elimination（DCE）：

// build.ts 中所有 feature() 返回 false
export function feature(_name: string): boolean {
  return false; // 外部构建全部禁用
}

已知特性标志（全部禁用）：

VOICE_MODE, COORDINATOR_MODE, KAIROS, PROACTIVE, ULTRAPLAN,
BRIDGE_MODE, BG_SESSIONS, WORKFLOW_SCRIPTS, TRANSCRIPT_CLASSIFIER,
TOKEN_BUDGET, HISTORY_SNIP, BUDDY, TEAMMEM, AGENT_TRIGGERS,
WEB_BROWSER_TOOL, MESSAGE_ACTIONS, HOOK_PROMPTS, CACHED_MICROCOMPACT,
CHICAGO_MCP, ABLATION_BASELINE, DUMP_SYSTEM_PROMPT

三、工具系统（Tools）

Claude Code 内置 ~40 个 Tool，全部注册到 Agent SDK 的 tool call 循环中。

3.1 核心工具一览

工具	说明
`BashTool`	Shell 命令执行
`FileEditTool`	文件编辑（diff 应用）
`FileReadTool`	文件读取
`FileWriteTool`	文件写入
`GlobTool`	文件模式搜索
`GrepTool`	内容搜索
`AgentTool`	子 Agent 生成（核心！）
`WebFetchTool`	HTTP 获取（含白名单机制）
`WebSearchTool`	网页搜索
`LSPTool`	Language Server Protocol 集成
`MCPTool`	MCP 协议客户端
`TaskCreateTool` / `TaskListTool` / `TaskOutputTool`	任务系统
`SkillTool`	Skill 执行
`TodoWriteTool`	Todo 列表
`SleepTool`	延迟（控制速率）
`TeamCreateTool` / `TeamDeleteTool`	团队管理

3.2 AgentTool（子 Agent 生成）

最关键的元工具——允许 CLI 自身生成子进程：

// tools/AgentTool/runAgent.ts
export async function runAgent(opts: RunAgentOptions): Promise<AgentResult> {
  // 启动新的 Claude Code 子进程
  // 支持 --worktree 模式（隔离工作目录）
  // 支持 resumeAgent（从快照恢复）
}

Agent 快照机制（agentMemorySnapshot.ts）：

将当前对话状态序列化到临时文件
子 Agent 从快照恢复，继承上下文
支持增量快照（避免重复序列化）

3.3 WebFetchTool 安全机制

白名单域名列表（硬编码）：

github.com, gitlab.com, bitbucket.org
stackoverflow.com, npmjs.com 等

带 PREAPPROVED_ 前缀的域名可直接 fetch，非白名单需要用户确认。

四、权限系统（Permissions）

4.1 三种权限模式

accept-all — 完全信任（自动化场景）
refuse-all — 全部拒绝（安全优先）
ask — 交互确认（默认）

4.2 自动模式分类器（YOLO Classifier）

yoloClassifier.ts（52KB）是自动模式的核心，使用 LLM 对每个 Bash 命令做安全评估：

允许 / 软拒绝 / 环境规则三元分类
环境规则示例：只允许 npm install，禁止 rm -rf /

注意：分类器依赖的 prompt 文件因 TRANSCRIPT_CLASSIFIER 特性标志被 DCE 删除，逻辑代码保留但不可用。

4.3 BashClassifier

硬编码的安全命令白名单：

1 2	`const ALLOWED_COMMANDS = ['git', 'npm', 'ls', 'cat', ...]; const DANGEROUS_PATTERNS = [/rm\s+(-rf\|-fr)/, /dd\s+/, ...];`

五、插件系统（Plugins）

完整的插件架构，支持从 ~/.claude/plugins/ 目录加载：

插件结构

plugin/
├── plugin.json          # 插件元数据
├── commands/             # 斜杠命令
├── agents/               # Agent 定义
├── hooks/                # Hook 脚本
├── skills/               # Skill 目录
└── resources/            # 静态资源

插件加载链路

pluginLoader.ts
  → loadPluginCommands.ts    // 注册 /mycommand
  → loadPluginAgents.ts       // 注册 @myagent
  → loadPluginHooks.ts        // 注册 preTool / postTool 等钩子
  → loadSkillsDir.ts          // 加载 skills/

内置 Skills（16个）

skills/bundled/
├── batch/        — 批量处理
├── claudeApi/    — Claude API 工具
├── debug/        — 调试助手
├── loop/        — 循环执行
├── skill-creator/ — Skill 创建工具
└── ...

Hook 系统

export type HookEvent =
  | 'preTool'       // 工具执行前
  | 'postTool'      // 工具执行后
  | 'preTask'       // 任务执行前
  | 'postAgent'     // Agent 完成后
  | 'prePrompty'    // Prompt 渲染前
  | 'onExit'        // 退出时
  | 'onError'       // 错误时
  | 'http';         // HTTP 请求拦截

六、UI 层：React + Ink

6.1 Ink 定制分支

Claude Code fork 了 Ink（React 分支，专门用于终端渲染）：

ink/
├── layout/          — Flexbox 布局引擎
├── components/      — <Box>, <Text>, <ScrollBox>, <Button>
├── hooks/           — useInput, useStdin, useSelection
├── events/          — Click、Keyboard、Focus 事件
├── termio/         — 终端 I/O、ANSI 解析
└── reconciler.ts   — React Reconciler 实现

关键修改：支持键盘快捷键、鼠标点击（ANSI 鼠标协议）、Vim 模式。

6.2 Vim 模式

完整的 Vim 实现：

vim/
├── motions/     — hjkl、w、b、e、f、t...
├── operators/   — d、c、y、p、<、>...
└── textObjects/ — iw、aw、ib、ab...

七、后端与 SDK

多后端支持

stubs/@anthropic-ai/
├── sdk/              — 主 SDK（40+ 文件，232KB）
├── bedrock-sdk/       — AWS Bedrock（12 文件，36KB）
├── vertex-sdk/        — GCP Vertex AI（7 文件，13KB）
├── foundry-sdk/       — Foundry（8 文件，16KB）
└── sandbox-runtime/   — 沙箱运行时（17 文件，180KB）

沙箱运行时的 Linux 实现：

Namespace 隔离 — pid、net、mount、ipc、uts、user
Seccomp-BPF — 生成字节码阻止危险系统调用
Parent Proxy — 父子进程通信代理

八、运行状态

✅ 完全可用

所有标准工具（Bash、Edit、Read、Write、Grep、Glob、WebFetch、WebSearch、Agent）
完整 React/Ink REPL 界面
OAuth 认证流程
MCP 服务器支持
斜杠命令（/help、/clear、/compact、/resume 等）
会话持久化和恢复
完整插件系统
完整 Hook 系统
完整 Skill 系统
Vim 模式
AWS Bedrock / GCP Vertex / Foundry 后端

❌ 不可用

Computer Use — 缺 native Swift/Rust 二进制
自动模式分类器 — prompt 文件被 DCE 删除
特性标志功能 — voice、coordinator 等全被禁用

总结

Claude Code 绝非简单的”AI + CLI”包装，而是一个工程化程度极高的复杂系统：

状态机驱动的 REPL — 基于 React/Ink 的交互式状态机
完善的权限模型 — 三级权限 + LLM 自动分类器
插件 + Hook + Skill 三位一体 — 可扩展性设计完整
多后端抽象 — Bedrock/Vertex/Foundry/Sandbox 支持
MCP 协议实现 — 完整的 Model Context Protocol 客户端/服务器
沙箱安全 — Linux namespace + seccomp-BPF

这次源码泄漏让我们得以一窥 Anthropic 内部工程实践的深度——代码组织清晰、模块边界明确、安全考虑周全。

技术

#Claude Code #源码分析 #Anthropic #AI编程

Claude Code 源码泄漏：技术架构深度解构

https://dongpeixian.art/2026/03/31/claude-code-技术解构/

作者

董沛贤

发布于

2026年3月31日

许可协议

Hello World 上一篇