Claude Code 源码深度分析报告

分析日期: 2026-04-01
源码来源: 2026-03-31 通过 npm registry .map 文件泄露
分支: backup

1. 项目总览

2. 代码规模 Top 25 文件

以下是代码行数最多的 25 个文件，反映了系统的复杂度中心：

[!IMPORTANT]
screens/REPL.tsx 文件大小高达 895KB（5,005 行），是整个项目最庞大的单文件组件，承载了几乎所有交互逻辑。

3. 核心架构

3.1 整体架构图

graph TB
    subgraph Entrypoints["入口层"]
        CLI["main.tsx
Commander.js CLI"]
        SDK["entrypoints/sdk/
Agent SDK"]
        MCP_EP["entrypoints/mcp.ts
MCP Server"]
    end

    subgraph Core["核心引擎"]
        QE["QueryEngine.ts
查询引擎"]
        Q["query.ts
查询循环"]
        API["services/api/claude.ts
Anthropic API Client"]
    end

    subgraph ToolSystem["工具系统"]
        TR["tools.ts
工具注册表"]
        T["Tool.ts
工具类型定义"]
        BT["BashTool"]
        FRT["FileReadTool"]
        FET["FileEditTool"]
        FWT["FileWriteTool"]
        AT["AgentTool"]
        ST["SkillTool"]
        MT["MCPTool"]
        OT["40+ 其他工具..."]
    end

    subgraph Commands["命令系统"]
        CR["commands.ts
命令注册表"]
        SC["86+ 斜杠命令目录"]
    end

    subgraph UI["用户界面"]
        REPL["screens/REPL.tsx"]
        COMP["components/
144 个 UI 组件"]
        HOOKS["hooks/
85 个 React Hooks"]
    end

    subgraph Services["服务层"]
        MCP_S["services/mcp/
MCP 客户端"]
        LSP_S["services/lsp/
LSP 集成"]
        OAUTH["services/oauth/
OAuth 2.0"]
        ANALYTICS["services/analytics/
GrowthBook"]
        COMPACT["services/compact/
上下文压缩"]
    end

    subgraph Infra["基础设施"]
        BRIDGE["bridge/
IDE 桥接"]
        COORD["coordinator/
多 Agent 协调"]
        PLUGINS["plugins/
插件系统"]
        SKILLS["skills/
技能系统"]
        STATE["state/
状态管理"]
        REMOTE["remote/
远程会话"]
    end

    CLI --> QE
    SDK --> QE
    QE --> Q
    Q --> API
    Q --> TR
    TR --> T
    T --> BT & FRT & FET & FWT & AT & ST & MT & OT
    QE --> CR
    CLI --> REPL
    REPL --> COMP
    REPL --> HOOKS
    Q --> MCP_S & LSP_S & COMPACT
    QE --> OAUTH & ANALYTICS
    REPL --> BRIDGE
    AT --> COORD
    QE --> PLUGINS & SKILLS
    QE --> STATE
    SDK --> REMOTE

3.2 请求生命周期

sequenceDiagram
    participant U as 用户
    participant REPL as REPL.tsx
    participant QE as QueryEngine
    participant Q as query()
    participant API as claude.ts
    participant T as Tool
    participant P as Permission

    U->>REPL: 输入提示词
    REPL->>QE: submitMessage(prompt)
    QE->>QE: processUserInput()
    QE->>QE: fetchSystemPromptParts()
    QE->>Q: query({messages, systemPrompt, ...})
    
    loop 查询循环 (tool_use → tool_result)
        Q->>Q: autocompact / snip / microcompact
        Q->>API: callModel(messages, tools)
        API-->>Q: stream assistant response
        
        alt 包含 tool_use
            Q->>P: canUseTool(tool, input)
            P-->>Q: allow / deny
            alt 允许
                Q->>T: tool.call(input, context)
                T-->>Q: ToolResult
                Q->>Q: 追加 tool_result 消息
            else 拒绝
                Q->>Q: 追加拒绝消息
            end
        else 纯文本响应
            Q-->>QE: 结束循环
        end
    end
    
    QE-->>REPL: yield SDKMessage
    REPL-->>U: 渲染响应

4. 核心模块详解

4.1 QueryEngine — 查询引擎 (QueryEngine.ts, 1,296 行)

QueryEngine 是整个系统的心脏，每个会话对应一个实例。

核心职责:

• 管理会话状态 (消息历史、文件缓存、用量统计)
• 组装系统提示词 (System Prompt + User Context + Memory)
• 驱动 query() 循环
• 跟踪权限拒绝 (SDK 报告)
• 管理技能/插件发现

关键数据流:

1
2
3
4
5

submitMessage(prompt)
  → processUserInput()       // 处理斜杠命令
  → fetchSystemPromptParts() // 系统提示词组装
  → query()                  // 核心查询循环
  → yield SDKMessage         // 流式输出

配置参数 (QueryEngineConfig):

4.2 query() — 查询循环 (query.ts, 1,730 行)

这是 Claude 与工具交互的核心循环，实现了完整的 tool_use → tool_result 协议。

循环流程:

1. 上下文压缩 — snip → microcompact → context collapse → autocompact
2. API 调用 — 流式调用 Anthropic API
3. 工具执行 — 支持流式并行执行 (StreamingToolExecutor)
4. 止步钩子 — PostToolUse / stop_reason 处理
5. 故障恢复 — max_output_tokens 恢复, reactive compact, fallback model

关键特性:

• Token 预算追踪 — task_budget 跨压缩保持
• 流式工具执行 — 在 API 流式输出时即开始执行工具
• 自动上下文压缩 — 4 层压缩策略 (snip, microcompact, collapse, autocompact)
• Fallback 模型 — streaming 期间自动降级

4.3 Tool 系统 (Tool.ts, 793 行)

每个工具是一个自包含模块，遵循统一接口：

1
2
3
4
5
6
7
8
9
10
11

type Tool = {
  name: string
  inputSchema: ZodSchema         // 输入验证
  call(): Promise<ToolResult>    // 执行逻辑
  checkPermissions(): Promise<PermissionResult>  // 权限检查
  isReadOnly(input): boolean     // 只读判断
  isDestructive(input): boolean  // 破坏性判断
  isConcurrencySafe(input): boolean  // 并发安全
  prompt(): Promise<string>      // 模型提示词
  // ... 渲染方法
}

buildTool() 工厂函数 — 所有工具通过此函数构建，提供安全默认值 (fail-closed):

• isEnabled → true
• isConcurrencySafe → false
• isReadOnly → false
• isDestructive → false

4.4 完整工具清单 (40+ 工具)

[!NOTE]
BashTool 是最复杂的工具，总代码量超过 560KB，包含完整的 bash 命令 AST 解析器、安全检测引擎和权限矩阵。

4.5 命令系统 (commands.ts, 755 行)

共 86+ 个斜杠命令目录 + 15 个独立命令文件：

5. 特性开关系统 (Feature Flags)

通过 bun:bundle 的 feature() 进行编译时死码消除 (DCE)。共发现 86 个特性开关：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

### 核心功能开关
| Flag | 描述 |
|------|------|
| `COORDINATOR_MODE` | 多 Agent 协调模式 |
| `BRIDGE_MODE` | IDE 桥接 (VS Code/JetBrains) |
| `VOICE_MODE` | 语音输入 |
| `PROACTIVE` | 主动模式 |
| `KAIROS` | Kairos 平台 (移动端/推送/GitHub集成) |
| `DAEMON` | 守护进程模式 |
| `AGENT_TRIGGERS` | Agent 触发器 (Cron) |
| `AGENT_TRIGGERS_REMOTE` | 远程 Agent 触发 |
| `WORKFLOW_SCRIPTS` | 工作流脚本 |
| `MCP_SKILLS` | MCP 技能系统 |
<!-- slide -->
### 上下文管理开关
| Flag | 描述 |
|------|------|
| `HISTORY_SNIP` | 历史剪切压缩 |
| `REACTIVE_COMPACT` | 响应式压缩 |
| `CACHED_MICROCOMPACT` | 缓存微压缩 |
| `CONTEXT_COLLAPSE` | 上下文折叠 |
| `TOKEN_BUDGET` | Token 预算管理 |
| `COMPACTION_REMINDERS` | 压缩提醒 |
<!-- slide -->
### 实验性功能
| Flag | 描述 |
|------|------|
| `ULTRAPLAN` | 超级计划模式 |
| `ULTRATHINK` | 超级思考模式 |
| `FORK_SUBAGENT` | 子 Agent 分叉 |
| `WEB_BROWSER_TOOL` | 网页浏览器工具 |
| `TERMINAL_PANEL` | 终端面板 |
| `BUDDY` | 伴侣精灵 (彩蛋) |
| `TORCH` | Torch 功能 |
| `EXPERIMENTAL_SKILL_SEARCH` | 实验性技能搜索 |
| `TEMPLATES` | 模板系统 |

6. 权限系统

6.1 权限模式

6.2 权限检查流程

flowchart TD
    A["tool_use 请求"] --> B{"全局 Deny 规则?"}
    B -->|匹配| C["拒绝"]
    B -->|不匹配| D{"Always Allow 规则?"}
    D -->|匹配| E["允许"]
    D -->|不匹配| F{"工具自身 checkPermissions()"}
    F --> G{"权限模式?"}
    G -->|default| H["提示用户"]
    G -->|plan| I{"isReadOnly?"}
    I -->|是| E
    I -->|否| H
    G -->|auto| J["安全分类器"]
    J -->|安全| E
    J -->|不安全| H
    G -->|bypass| E

6.3 BashTool 安全子系统

BashTool 的安全检测是最复杂的子系统 (超过 200K 代码)：

工作原理：每个 Bash 命令先被解析为 AST，然后通过多层安全检查：

1. 命令分类 — 识别 read-only / write / destructive
2. 路径验证 — 确保在允许的工作目录内
3. sed 分析 — 检测 sed 的 in-place 修改
4. 破坏性警告 — rm -rf, kill 等命令的特殊处理

7. 多 Agent 协调系统

7.1 Coordinator Mode (coordinator/coordinatorMode.ts)

当启用 COORDINATOR_MODE 时，Claude Code 变为协调者 (Coordinator)，不直接执行工具，而是指挥多个 Worker 并行执行任务。

协调者工具集:

• AgentTool — 生成 worker
• SendMessageTool — 向 worker 发送后续指令
• TaskStopTool — 停止 worker

工作流:

1

Research (并行 workers) → 协调者综合 → Implementation (workers) → Verification (workers)

关键设计原则:

• 协调者必须综合 worker 的研究结果，而非简单转发
• Worker 的消息以 <task-notification> XML 格式送达
• 并行是超级能力 — 独立任务尽量并行执行
• 验证必须独立证明代码可用，不能只确认文件存在

7.2 Agent Swarms

通过 TeamCreateTool / TeamDeleteTool 实现团队级并行工作：

• 子 Agent 通过 AgentTool 生成
• Agent 间通过 SendMessageTool 通信
• 支持 in-process 和分叉两种模式

8. 上下文管理策略

Claude Code 实现了4 层上下文压缩策略，确保长会话不超出 Token 限制：

flowchart LR
    A["原始消息"] --> B["1. Snip
(历史剪切)"]
    B --> C["2. Microcompact
(内联压缩)"]
    C --> D["3. Context Collapse
(上下文折叠)"]
    D --> E["4. Autocompact
(自动压缩)"]
    E --> F["发送到 API"]

还有 Reactive Compact 作为后备 — 当 API 返回 prompt_too_long 错误时触发紧急压缩。

9. IDE 桥接系统 (bridge/, 31 个文件)

9.1 架构

graph LR
    subgraph IDE["IDE 侧"]
        VSC["VS Code Extension"]
        JB["JetBrains Plugin"]
    end
    
    subgraph Bridge["桥接层"]
        BM["bridgeMain.ts (115K)"]
        RB["replBridge.ts (100K)"]
        JWT["jwtUtils.ts JWT 认证"]
    end
    
    subgraph CLI["CLI 侧"]
        REPL2["REPL.tsx"]
        TOOLS["工具系统"]
    end
    
    VSC -- WebSocket/stdio --- BM
    JB -- WebSocket/stdio --- BM
    BM --- RB
    RB --- REPL2
    REPL2 --> TOOLS

9.2 关键文件

10. 插件与技能系统

10.1 插件系统

• 内建插件 (plugins/bundled/) — 预装插件
• 第三方插件 — 通过 plugins/ 子系统加载
• 插件市场 (utils/plugins/marketplaceManager.ts, 2,643 行)

10.2 技能系统

技能是可复用的工作流，通过 SkillTool 执行：

• 内建技能 (skills/bundled/) — 预装技能
• 用户技能 — 从 .claude/skills/ 目录加载
• MCP 技能 — 通过 MCP 协议加载
• 动态技能 — 运行时发现 (文件操作时触发)

11. 状态管理

11.1 AppState (state/AppStateStore.ts, 21K)

使用自定义的 createStore + useSyncExternalStore 模式 (非 Redux/Zustand)：

1
2
3
4
5
6
7
8
9
10

AppState = {
  toolPermissionContext  // 权限状态
  mcp                    // MCP 连接 & 工具
  fastMode               // 快速模式
  effortValue            // 推理强度
  fileHistory            // 文件历史
  attribution            // 代码归属
  speculation            // 推测执行
  // ...
}

特点:

• 单一 Store，Context Provider 稳定引用
• useAppState(selector) — 选择器模式避免不必要的 re-render
• useSetAppState() — 无订阅的 updater

11.2 Bootstrap State (bootstrap/state.ts)

会话级全局状态 (非 React)：

• Session ID
• API 用量计数器
• 成本追踪
• SDK betas
• Feature flags cache

12. 性能优化策略

12.1 启动优化

12.2 运行时优化

12.3 内存管理

13. 安全机制

14. 遥测与分析

15. 值得注意的设计决策

15.1 React for CLI

使用 Ink 将 React 渲染到终端，这是一个非常规但强大的选择：

• 组件模型 — 144 个复杂 UI 组件复用
• Hook 生态 — 85 个 React Hook 管理状态
• React Compiler — 代码中可见 react/compiler-runtime 使用

15.2 Bun 运行时

• bun:bundle 用于编译时特性开关 (DCE)
• 比 Node.js 更快的启动时间
• 原生 TypeScript 支持

15.3 内外部版本分离

通过 USER_TYPE === 'ant' 和 feature flags 实现:

• Internal (ant) — 包含 REPLTool, ConfigTool, TungstenTool, 调试命令等
• External — 公开发布版本，通过 DCE 移除内部代码

15.4 CLAUDE.md 记忆系统

utils/claudemd.ts (46K) 实现了项目级持久记忆：

• 自动发现 .claude/ 目录下的 CLAUDE.md
• 支持嵌套记忆 (nested memory attachments)
• 通过 memdir/ 实现持久化

16. 未公开的前沿功能

从 feature flags 和代码中发现的尚未公开发布的功能：

[!WARNING]
Kairos 相关 flags 约有 6 个变体 (KAIROS, KAIROS_BRIEF, KAIROS_CHANNELS, KAIROS_DREAM, KAIROS_GITHUB_WEBHOOKS, KAIROS_PUSH_NOTIFICATION)，暗示这是一个大型的、尚未公开的始终在线 Agent 平台。

17. 总结

Claude Code 是一个工程复杂度极高的产品级 AI 代理系统，核心亮点：

1. 512K 行 TypeScript — 这是一个成熟的、严肃的工程产品
2. 4 层上下文压缩 — 精心设计的长会话管理
3. 560K+ 的 BashTool — 安全是第一优先级，含完整 AST 分析
4. 86 个 Feature Flags — 精密的渐进式发布管道
5. Multi-Agent 协调 — 不仅是单 Agent，而是 Agent 编排器
6. React for CLI — 非传统但极其有效的技术选择
7. Kairos 平台 — 一个尚未发布的始终在线 Agent 系统
8. Teleport (175K) — 跨设备会话迁移是一个巨大的工程投入

[!CAUTION]
此代码来自泄露的源码，所有原始代码归 Anthropic 所有。本报告仅用于技术学习和分析目的。