# Claude Code v2.1.88 源码分析报告

> 分析日期：2026-03-31
> 源码版本：anthropic-ai-claude-code-2.1.88
> 总文件数：1,884 个源文件（.ts/.tsx）
> 总代码行数：约 512,664 行

---

## 一、项目概览

Claude Code 是 Anthropic 官方的 CLI 交互式编程助手。它基于 **Bun 运行时** 构建，使用 **React + Ink** 渲染终端 UI，通过 Anthropic API 与 Claude 模型交互，为用户提供代码编写、调试、文件操作等软件工程任务支持。

### 技术栈

| 类别 | 技术 |
|------|------|
| 运行时 | Bun |
| 语言 | TypeScript / TSX |
| CLI 框架 | Commander.js (`@commander-js/extra-typings`) |
| 终端 UI | React + Ink（自定义 fork） |
| AI SDK | `@anthropic-ai/sdk` (Beta Messages API) |
| 协议 | MCP (Model Context Protocol) |
| 构建 | Bun bundler（`bun:bundle` feature flags） |

---

## 二、整体架构

```
┌─────────────────────────────────────────────────────┐
│                  entrypoints/cli.tsx                 │  ← 入口
├─────────────────────────────────────────────────────┤
│                     main.tsx                         │  ← CLI 参数解析 + 初始化
├─────────────────────────────────────────────────────┤
│                  screens/REPL.tsx                    │  ← 主交互界面（React 组件）
├──────────┬──────────┬───────────┬───────────────────┤
│ query.ts │ tools.ts │commands.ts│  QueryEngine.ts   │  ← 核心调度层
├──────────┴──────────┴───────────┴───────────────────┤
│  services/api/claude.ts  │  services/mcp/client.ts  │  ← API 通信层
├──────────────────────────┴──────────────────────────┤
│         tools/  │  skills/  │  hooks/  │  tasks/     │  ← 功能实现层
├─────────────────────────────────────────────────────┤
│    utils/  │  state/  │  constants/  │  types/       │  ← 基础设施层
└─────────────────────────────────────────────────────┘
```

---

## 三、核心模块详解

### 3.1 入口与启动流程

**文件**: `src/entrypoints/cli.tsx`

启动经过精心优化的多阶段引导：

1. **快速路径（Fast Path）**: `--version` 直接输出版本号，零模块加载
2. **特殊模式检查**: `--dump-system-prompt`, `--claude-in-chrome-mcp`, `--chrome-native-host` 等
3. **主路径**: 动态导入 `main.tsx`，进入完整 CLI 初始化

**文件**: `src/main.tsx`（4,683 行，最核心文件之一）

主函数负责：
- 并行预取：MDM 配置、Keychain 凭证、OAuth、GrowthBook 特性开关
- Commander.js 命令行参数解析
- 初始化分析（analytics）、策略限制（policy limits）、远程托管设置
- 加载 MCP 服务器、工具列表、技能系统、插件系统
- 启动 React/Ink 渲染 → `REPL` 组件

### 3.2 REPL 主界面

**文件**: `src/screens/REPL.tsx`（5,005 行）

核心交互组件，包含：
- 消息列表渲染（虚拟滚动）
- 用户输入处理（含 Vim 模式）
- 权限请求对话框
- 成本追踪与显示
- Agent/Teammate 管理
- 会话持久化与恢复

### 3.3 查询引擎（Query Loop）

**文件**: `src/query.ts` — 单次对话轮次的核心循环
**文件**: `src/QueryEngine.ts` — 高级查询引擎（SDK/非交互模式）

对话流程：
```
用户输入 → System Prompt 构建 → API 调用(streaming) → 解析响应
    ↓
  tool_use → 权限检查 → 工具执行 → 结果返回 → 继续 API 调用
    ↓
  end_turn → 展示结果给用户
```

关键机制：
- **Auto Compact**: 上下文接近限制时自动压缩对话历史
- **Reactive Compact**: 更智能的上下文折叠（feature flag 控制）
- **Token Budget**: 工具结果的 token 预算管理
- **Fingerprint**: 消息去重与缓存优化

### 3.4 API 通信层

**文件**: `src/services/api/claude.ts`（3,419 行）

- 使用 Anthropic SDK 的 **Beta Messages API**（支持 streaming）
- 支持多 provider：Anthropic 直连、AWS Bedrock、GCP Vertex
- 处理 Betas 特性（extended thinking、tool use 等）
- 请求指纹计算（用于 prompt cache）
- 重试与错误处理策略

---

## 四、工具系统（Tools）

### 4.1 工具接口

**文件**: `src/Tool.ts`

核心类型 `ToolUseContext` 定义了工具执行的完整上下文，包括：
- 可用工具列表、命令、MCP 客户端
- `AbortController` 中断控制
- `AppState` 读写
- 文件状态缓存、权限上下文
- Agent/子代理相关状态

### 4.2 工具注册

**文件**: `src/tools.ts`

所有工具在此文件中集中注册。支持条件加载（通过 `bun:bundle` feature flags）：

| 工具 | 功能 |
|------|------|
| **BashTool** | 执行 shell 命令 |
| **FileReadTool** | 读取文件 |
| **FileEditTool** | 编辑文件（精确替换） |
| **FileWriteTool** | 写入文件 |
| **GlobTool** | 文件模式匹配搜索 |
| **GrepTool** | 内容正则搜索（基于 ripgrep） |
| **WebFetchTool** | 抓取网页内容 |
| **WebSearchTool** | 网页搜索 |
| **AgentTool** | 启动子代理 |
| **SendMessageTool** | 向子代理发送消息 |
| **NotebookEditTool** | 编辑 Jupyter Notebook |
| **AskUserQuestionTool** | 向用户提问 |
| **EnterPlanModeTool** | 进入计划模式 |
| **ExitPlanModeTool** | 退出计划模式 |
| **EnterWorktreeTool** | 创建 Git Worktree |
| **ExitWorktreeTool** | 退出 Git Worktree |
| **TaskCreateTool** | 创建任务 |
| **TaskUpdateTool** | 更新任务 |
| **TaskGetTool** | 获取任务详情 |
| **TaskListTool** | 列出任务 |
| **TaskOutputTool** | 获取任务输出 |
| **TaskStopTool** | 停止任务 |
| **SkillTool** | 执行技能 |
| **TodoWriteTool** | 写入待办事项 |
| **LSPTool** | Language Server Protocol 交互 |
| **MCPTool** | 调用 MCP 工具 |
| **ToolSearchTool** | 搜索可用工具 |
| **ConfigTool** | 配置管理 |
| **BriefTool** | 简洁模式 |
| **ScheduleCronTool** | 定时任务（CronCreate/Delete/List） |
| **ListMcpResourcesTool** | 列出 MCP 资源 |
| **ReadMcpResourceTool** | 读取 MCP 资源 |

**内部/实验性工具**（feature flag 控制）：
- `REPLTool` — 仅内部用户
- `SleepTool` — 主动等待
- `RemoteTriggerTool` — 远程触发
- `MonitorTool` — 监控工具
- `SendUserFileTool` — 发送文件给用户（KAIROS）
- `PushNotificationTool` — 推送通知
- `SubscribePRTool` — PR 订阅
- `TeamCreateTool` / `TeamDeleteTool` — 团队/多代理管理
- `TungstenTool` — 内部工具

### 4.3 Bash 工具安全系统

**文件**: `src/tools/BashTool/bashSecurity.ts`（2,592 行）
**文件**: `src/tools/BashTool/bashPermissions.ts`（2,621 行）

Bash 工具有最复杂的安全系统：
- 命令白名单/黑名单
- 破坏性命令检测（rm -rf, git push --force 等）
- 沙箱模式
- Bash AST 解析器（`bashParser.ts` 4,436 行）用于静态分析命令安全性

---

## 五、权限系统

### 5.1 权限模式

**文件**: `src/types/permissions.ts`

三种权限模式：
- **`default`**: 默认模式，危险操作需要用户确认
- **`plan`**: 计划模式，只读操作
- **`bypass`**: 跳过权限检查（需用户明确启用）

### 5.2 权限规则

```typescript
type ToolPermissionContext = {
  mode: PermissionMode
  alwaysAllowRules: ToolPermissionRulesBySource  // 始终允许
  alwaysDenyRules: ToolPermissionRulesBySource   // 始终拒绝
  alwaysAskRules: ToolPermissionRulesBySource    // 始终询问
  isBypassPermissionsModeAvailable: boolean
}
```

权限规则可在多个层级配置：
- 全局设置 (`~/.claude/settings.json`)
- 项目设置 (`.claude/settings.json`)
- 命令行参数
- 运行时用户选择

---

## 六、任务系统（Tasks）

**文件**: `src/Task.ts`

支持的任务类型：

| 类型 | 说明 |
|------|------|
| `local_bash` | 本地 Shell 后台命令 |
| `local_agent` | 本地子代理 |
| `remote_agent` | 远程代理 |
| `in_process_teammate` | 进程内协作者（多代理） |
| `local_workflow` | 本地工作流 |
| `monitor_mcp` | MCP 监控 |
| `dream` | Dream 任务（后台推理） |

任务状态机：`pending → running → completed/failed/killed`

---

## 七、MCP 集成

**文件**: `src/services/mcp/client.ts`（3,348 行）
**文件**: `src/services/mcp/auth.ts`（2,465 行）

MCP (Model Context Protocol) 深度集成：
- 支持 stdio 和 SSE 传输
- OAuth 2.0 认证流程
- 工具、资源、提示的完整支持
- 官方 MCP 服务器注册表（`officialRegistry.ts`）
- 连接生命周期管理（`MCPConnectionManager.tsx`）
- 通道权限控制（`channelPermissions.ts`）

---

## 八、技能系统（Skills）

**文件**: `src/skills/`

技能是更高级的命令抽象：
- `bundled/` — 内置技能
- `loadSkillsDir.ts` — 从目录加载自定义技能
- `mcpSkillBuilders.ts` — 从 MCP 构建技能
- 支持用户通过 `/skill-name` 快捷调用

---

## 九、UI 系统

### 9.1 Ink 终端渲染

**文件**: `src/ink/`（96 个文件）

自定义的 Ink (React for CLI) 框架：
- `layout/` — 布局引擎（基于 Yoga layout）
- `components/` — 基础 UI 组件
- `hooks/` — React hooks（终端尺寸、焦点、搜索等）
- `termio/` — 终端 I/O 和 DEC 控制序列
- `events/` — 事件系统

### 9.2 主要组件

**文件**: `src/components/`（389 个文件）

关键组件包括：
- `PromptInput/` — 用户输入框（支持多行、Vim 模式）
- `VirtualMessageList` — 虚拟滚动消息列表
- `Spinner` — 加载动画
- `permissions/` — 权限请求 UI
- `mcp/` — MCP 相关 UI
- `MessageSelector` — 消息选择器
- `CostThresholdDialog` — 成本阈值对话框

---

## 十、命令系统

**文件**: `src/commands/`（207 个文件）

Slash 命令系统（用户通过 `/command` 触发）：

| 分类 | 命令示例 |
|------|---------|
| **Git** | `/commit`, `/branch`, `/diff`, `/pr_comments`, `/review` |
| **会话** | `/resume`, `/session`, `/compact`, `/clear`, `/exit` |
| **配置** | `/config`, `/model`, `/theme`, `/permissions`, `/vim` |
| **工具** | `/mcp`, `/plugin`, `/skills`, `/hooks` |
| **调试** | `/doctor`, `/debug-tool-call`, `/cost`, `/stats`, `/perf-issue` |
| **AI 模式** | `/plan`, `/fast`, `/effort`, `/brief`, `/thinkback` |
| **协作** | `/agents`, `/tasks`, `/teleport`, `/remote-setup` |
| **其他** | `/memory`, `/export`, `/help`, `/feedback`, `/version` |

---

## 十一、服务层

**文件**: `src/services/`（130 个文件）

| 服务 | 说明 |
|------|------|
| `api/` | Anthropic API 通信（claude.ts, bootstrap.ts, filesApi.ts） |
| `mcp/` | MCP 协议客户端和服务器管理 |
| `oauth/` | OAuth 2.0 认证 |
| `analytics/` | 分析追踪（GrowthBook 特性开关） |
| `compact/` | 对话压缩（autoCompact, reactiveCompact） |
| `policyLimits/` | 策略限制管理 |
| `remoteManagedSettings/` | 远程托管设置 |
| `plugins/` | 插件加载与管理 |
| `SessionMemory/` | 会话记忆 |
| `tips/` | 使用提示 |
| `lsp/` | LSP 服务 |
| `tools/` | 工具相关服务 |
| `extractMemories/` | 自动记忆提取 |
| `voice/` | 语音交互 |

---

## 十二、状态管理

**文件**: `src/state/`

- `AppState.tsx` — 全局应用状态类型定义
- `AppStateStore.ts` — 状态存储实现
- `store.ts` — 状态存储工厂
- `selectors.ts` — 状态选择器
- `onChangeAppState.ts` — 状态变更监听

状态包含：消息列表、任务状态、权限上下文、MCP 连接、成本追踪等。

---

## 十三、辅助系统

### 13.1 记忆系统
**文件**: `src/memdir/`（8 个文件）
管理 `MEMORY.md` 和持久化记忆目录，跨会话保持上下文。

### 13.2 Vim 模式
**文件**: `src/vim/`（5 个文件）
终端输入框支持 Vim 键绑定。

### 13.3 语音交互
**文件**: `src/services/voice.ts`, `voiceStreamSTT.ts`
语音输入支持（STT）。

### 13.4 代理群集（Agent Swarms）
**文件**: `src/utils/swarm/`
支持多代理协作：leader/worker 权限同步、team 管理、沙箱权限请求。

### 13.5 插件系统
**文件**: `src/services/plugins/`, `src/utils/plugins/`
- `pluginLoader.ts`（3,302 行）— 插件加载器
- `marketplaceManager.ts`（2,643 行）— 插件市场管理
- 支持内置插件和第三方插件

---

## 十四、Feature Flags 系统

通过 `bun:bundle` 的 `feature()` 函数实现编译时特性开关：

| Flag | 功能 |
|------|------|
| `ABLATION_BASELINE` | A/B 测试基线 |
| `DUMP_SYSTEM_PROMPT` | 导出系统提示 |
| `PROACTIVE` | 主动模式 |
| `KAIROS` | Assistant 模式 |
| `AGENT_TRIGGERS` | 定时任务 |
| `AGENT_TRIGGERS_REMOTE` | 远程触发 |
| `MONITOR_TOOL` | 监控工具 |
| `COORDINATOR_MODE` | 协调器模式 |
| `REACTIVE_COMPACT` | 响应式压缩 |
| `CONTEXT_COLLAPSE` | 上下文折叠 |
| `KAIROS_GITHUB_WEBHOOKS` | GitHub Webhook |
| `KAIROS_PUSH_NOTIFICATION` | 推送通知 |

外部构建通过 DCE（Dead Code Elimination）移除内部功能。

---

## 十五、关键文件索引

| 文件 | 行数 | 功能 |
|------|------|------|
| `cli/print.ts` | 5,594 | 非交互式输出/打印模式 |
| `utils/messages.ts` | 5,512 | 消息创建与处理 |
| `utils/sessionStorage.ts` | 5,105 | 会话持久化存储 |
| `utils/hooks.ts` | 5,022 | Hooks 系统实现 |
| `screens/REPL.tsx` | 5,005 | 主 REPL 界面 |
| `main.tsx` | 4,683 | 主入口/初始化 |
| `utils/bash/bashParser.ts` | 4,436 | Bash 命令解析器 |
| `utils/attachments.ts` | 3,997 | 附件处理 |
| `services/api/claude.ts` | 3,419 | API 通信 |
| `services/mcp/client.ts` | 3,348 | MCP 客户端 |
| `utils/plugins/pluginLoader.ts` | 3,302 | 插件加载器 |
| `commands/insights.ts` | 3,200 | 洞察命令 |
| `bridge/bridgeMain.ts` | 2,999 | Bridge 主进程 |
| `utils/bash/ast.ts` | 2,679 | Bash AST |
| `tools/BashTool/bashPermissions.ts` | 2,621 | Bash 权限 |
| `tools/BashTool/bashSecurity.ts` | 2,592 | Bash 安全 |

---

## 十六、架构亮点

### 1. 启动性能优化
- 多阶段懒加载：快速路径零导入，主路径并行预取
- `startupProfiler.ts` 追踪每个启动阶段耗时
- MDM、Keychain、OAuth 凭证并行预取

### 2. 安全设计
- Bash 命令 AST 级静态分析
- 多层权限控制（白名单、黑名单、始终询问）
- 沙箱模式隔离
- 破坏性操作自动检测与拦截

### 3. 多代理架构
- 子代理（AgentTool）支持并发执行
- 团队协作（TeamCreate/TeamDelete）
- 进程内协作者（InProcessTeammate）
- 远程代理（RemoteAgent）
- Leader/Worker 权限同步

### 4. 上下文管理
- Auto Compact 自动压缩历史
- Reactive Compact 智能压缩
- Context Collapse 上下文折叠
- Token Budget 精细控制
- 文件状态缓存 LRU

### 5. 可扩展性
- 插件系统 + 插件市场
- MCP 协议集成
- 自定义技能
- Hooks 系统
- Feature Flags 编译时裁剪

---

## 十七、数据流图

```
User Input
    │
    ▼
┌─────────────┐     ┌──────────────┐
│ PromptInput │────▶│  REPL.tsx    │
└─────────────┘     └──────┬───────┘
                           │
                    ┌──────▼───────┐
                    │  query.ts    │ ◄── System Prompt (constants/prompts.ts)
                    │  (主循环)     │ ◄── Memory (memdir/)
                    └──────┬───────┘ ◄── CLAUDE.md
                           │
                    ┌──────▼───────┐
                    │ claude.ts    │ ── Anthropic Beta Messages API (streaming)
                    │ (API 调用)    │
                    └──────┬───────┘
                           │
              ┌────────────┼────────────┐
              ▼            ▼            ▼
         text_delta   tool_use    end_turn
              │            │            │
              ▼            ▼            ▼
         渲染文本     ┌─────────┐   返回结果
                     │权限检查  │
                     └────┬────┘
                          │
                     ┌────▼────┐
                     │工具执行  │ → BashTool / FileReadTool / AgentTool / ...
                     └────┬────┘
                          │
                     tool_result → 继续 API 调用（循环）
```

---

*报告生成完毕。源代码已还原至 `package/source/src/` 目录。*