Claude Code — 源码文档与架构分析

Claude Code 是 Anthropic 官方的 Claude CLI 工具。本文档提供了对其源码架构、模块和内部设计模式的全面逆向工程分析。

---

如何阅读本文档

本文档是对 Claude Code 源码树进行深度分析的成果。它面向希望了解 Claude Code 底层工作原理的开发者和工程师——包括其架构、模块边界、数据流和设计决策。

结构： 文档采用自顶向下的组织方式，从项目概览和技术栈开始，然后深入到各个主要子系统（工具、命令、状态、服务、UI）。每个章节都是独立的；你可以通过目录跳转到任意章节。

受众： 熟悉 TypeScript、React 和 CLI 工具的中高级开发者。有 AI/LLM 工具开发经验会有帮助，但不是必需的。

范围： 本文档涵盖源码树结构、模块清单和架构模式。不深入涉及运行时行为，也不包含性能基准测试或安全审计。

---

目录

1. 项目概览
2. 技术栈
3. 目录结构
4. 入口点
5. 核心架构
6. 工具系统
7. 命令系统
8. 状态管理
9. 任务系统
10. 服务与集成
11. UI 层
12. 工具函数
13. 特殊模式
14. 插件与技能
15. 钩子与可扩展性
16. 文件统计
17. 架构模式

---

1. 项目概览

Claude Code 是一个功能丰富的交互式终端应用，允许直接在命令行中进行 AI 辅助软件工程。它提供：

• 交互式 REPL，用于与 Claude 进行代码相关的对话
• 40+ 工具，用于文件操作、Shell 执行、网络搜索等
• 100+ 斜杠命令，用于提交、审查、调试等工作流
• Agent/任务系统，用于通过子 Agent 并行处理复杂工作
• 计划模式，用于在编码前设计实现策略
• MCP（Model Context Protocol） 集成，提供可扩展的服务端工具
• 插件与技能系统，用于用户自定义扩展
• 语音模式、桌面/移动端桥接和远程会话

---

2. 技术栈

---

3. 目录结构

claude-code-analysis/
└── src/                          # 所有源码（单一顶级目录）
    ├── main.tsx                  # 主引导与初始化
    ├── QueryEngine.ts            # 对话循环编排器
    ├── Tool.ts                   # 工具类型定义与接口
    ├── Task.ts                   # 任务类型定义与生命周期
    ├── commands.ts               # 命令注册表
    ├── tools.ts                  # 工具注册表与工厂
    ├── context.ts                # 系统/用户上下文构建器
    ├── query.ts                  # 查询上下文准备
    ├── setup.ts                  # 启动阶段编排
    ├── history.ts                # 聊天会话历史
    ├── cost-tracker.ts           # Token 用量与定价
    ├── ink.ts                    # Ink 渲染封装
    ├── replLauncher.tsx          # REPL React 组件启动器
    ├── tasks.ts                  # 任务执行管理器
    │
    ├── commands/                 # 101 个命令模块（斜杠命令）
    ├── tools/                    # 41 个工具实现
    ├── services/                 # 核心服务（API、MCP、分析等）
    ├── components/               # React/Ink UI 组件（130+ 文件）
    ├── utils/                    # 工具函数（300+ 文件）
    ├── state/                    # 应用状态管理
    ├── types/                    # TypeScript 类型定义
    ├── hooks/                    # React Hooks
    ├── schemas/                  # Zod 验证模式
    ├── tasks/                    # 任务类型实现
    ├── entrypoints/              # 入口点定义（CLI、SDK、MCP）
    ├── bootstrap/                # 应用启动与全局状态
    ├── screens/                  # 全屏 UI 布局
    ├── plugins/                  # 插件系统（内置插件）
    ├── skills/                   # 自定义技能系统（内置技能）
    ├── memdir/                   # 内存目录自动发现
    ├── constants/                # 应用常量
    ├── migrations/               # 数据/模式迁移
    ├── ink/                      # Ink 终端自定义
    ├── keybindings/              # 键盘绑定系统
    ├── context/                  # React Context（信箱、通知）
    ├── query/                    # 查询处理模块
    ├── outputStyles/             # 输出格式化样式
    ├── vim/                      # Vim 模式集成
    ├── voice/                    # 语音输入/输出
    ├── native-ts/                # 原生 TypeScript 绑定
    ├── assistant/                # Kairos（助手）模式
    ├── bridge/                   # Bridge 模式（常驻远程连接）
    ├── buddy/                    # Buddy/队友系统
    ├── coordinator/              # 多 Agent 协调
    ├── remote/                   # 远程会话处理
    ├── server/                   # 服务器实现
    ├── cli/                      # CLI 参数解析
    └── upstreamproxy/            # 上游代理设置

---

4. 入口点

主入口：src/main.tsx

主引导文件（约 1,400 行）。执行以下操作：

1. 通过 startupProfiler.ts 进行启动性能分析
2. MDM（移动设备管理） 原始数据预读取
3. 钥匙串预取（macOS OAuth + API 密钥并行读取）
4. 通过 Bun 的 feature() 进行特性标志初始化，实现死代码消除
5. 通过 Commander.js 进行 CLI 参数解析
6. 身份认证（API 密钥、OAuth、AWS Bedrock、GCP Vertex、Azure）
7. GrowthBook 初始化（A/B 测试与特性标志）
8. 策略限制和远程托管设置加载
9. 工具、命令、技能和 MCP 服务器注册
10. 通过 replLauncher.tsx 启动 REPL

其他入口点（src/entrypoints/）

启动阶段：src/setup.ts

负责编排：

• Node.js 版本验证
• 工作树初始化
• 会话与权限模式设置
• Git 根目录检测
• UDS 消息服务器启动

---

5. 核心架构

5.1 查询引擎（src/QueryEngine.ts）

应用的核心（约 46KB）。管理用户与 Claude 之间的对话循环：

• 消息管理 — 维护包含用户、助手、系统和工具消息的对话历史
• 流式传输 — 实时 Token 流式传输与工具调用执行
• 自动压缩 — 当接近上下文窗口限制时自动压缩上下文
• 提示词缓存 — 通过缓存感知策略优化重复上下文
• 重试逻辑 — 处理 API 错误、速率限制和过载，支持退避策略
• 用量追踪 — 统计 Token 数量（输入/输出/缓存读取/缓存写入）和成本
• 工具编排 — 分发工具调用、收集结果、管理权限

5.2 上下文构建器（src/context.ts、src/query.ts）

准备系统提示词和用户上下文：

• 发现并合并 CLAUDE.md 文件（项目级、用户级、全局级）
• 构建系统上下文（操作系统、Shell、平台、Git 状态）
• 集成用户上下文（权限、工作目录）
• 跨查询缓存上下文以提升性能

5.3 成本追踪（src/cost-tracker.ts）

追踪每次会话的成本：

• 按模型统计 Token 数量（输入、输出、缓存读取/写入）
• 通过定价表计算美元成本
• 会话持续时间追踪
• 网络搜索请求计数
• 文件变更指标

---

6. 工具系统

架构（src/Tool.ts、src/tools.ts）

每个工具都是一个自包含的模块，包含：

• JSON Schema 输入验证
• 权限模型（询问/允许/拒绝模式）
• 进度追踪类型
• 错误处理和用户提示

完整工具清单（41 个工具）

文件操作

代码执行

网络与搜索

Agent 与任务管理

计划与工作流

MCP（Model Context Protocol）

配置与系统

团队与远程

内部工具

---

7. 命令系统

注册表（src/commands.ts）

命令是 src/commands/ 下的模块化目录，每个目录包含一个 index.ts（或类似文件），导出一个 Command 定义，包含名称、描述、处理函数和可选的别名。

完整命令清单（101 个模块）

Git 与版本控制

commit、commit-push-pr、diff、branch、review、autofix-pr、pr_comments、teleport、rewind、tag

会话与历史

session、resume、clear、compact、export、share、summary、context

配置与设置

config、permissions、privacy-settings、theme、color、keybindings、vim、output-style、statusline、env

Agent 与任务管理

agents、tasks、brief

文件与代码操作

files、add-dir、diff、debug-tool-call、copy

开发与调试

doctor、heapdump、perf-issue、stats、bughunter、ctx_viz、ant-trace

身份认证

login、logout、oauth-refresh

扩展与插件

mcp、plugin、reload-plugins、skills

工作区

plan、sandbox-toggle、init

信息与帮助

help、version、cost、usage、extra-usage、release-notes、status、insights

平台集成

desktop、mobile、chrome、ide、install、install-github-app、install-slack-app

记忆与知识

memory、good-claude

模型与性能

model、effort、fast、thinkback、thinkback-play、advisor

特殊操作

bridge、voice、remote-setup、remote-env、stickers、feedback、onboarding、passes、ultraplan、rename、exit

---

8. 状态管理

Store 架构（src/state/）

关键状态字段

{
  settings: UserSettings           // 来自 settings.json 的用户配置
  mainLoopModel: string            // 当前活跃的 Claude 模型
  messages: Message[]              // 对话历史
  tasks: TaskState[]               // 运行中/已完成的任务
  toolPermissionContext: {         // 每个工具的权限规则
    rules: PermissionRule[]
    bypassMode: 'auto' | 'block' | 'ask'
    denialTracking: DenialTrackingState
  }
  kairosEnabled: boolean           // 助手模式标志
  remoteConnectionStatus: Status   // 远程会话连接状态
  replBridgeEnabled: boolean       // 常驻桥接（CCR）状态
  speculationState: Cache          // 内联推测缓存/预览
}

---

9. 任务系统

任务类型（src/Task.ts）

任务生命周期

pending -> running -> completed
                   -> failed
                   -> killed

任务状态结构

{
  id: string           // 带类型前缀的唯一 ID（例如 "b-xxx" 表示 bash）
  type: TaskType
  status: TaskStatus
  description: string
  startTime: number
  endTime?: number
  outputFile: string   // 磁盘持久化输出
  outputOffset: number // 当前读取位置
  notified: boolean    // 是否已报告完成
}

---

10. 服务与集成

10.1 API 客户端（src/services/api/）

支持的提供商：

• Anthropic 直连 API
• AWS Bedrock
• Google Cloud Vertex AI
• Azure Foundry

10.2 MCP 集成（src/services/mcp/）

10.3 分析与遥测（src/services/analytics/）

10.4 上下文压缩（src/services/compact/）

10.5 其他服务

---

11. UI 层

框架

UI 使用 React 构建，通过 Ink 渲染到终端。组件使用标准 React 模式（Hooks、Context、Props），但渲染为终端 ANSI 输出而非 DOM。

核心应用组件

组件分类

消息展示

Message.tsx、MessageRow.tsx、MessageResponse.tsx、MessageModel.tsx、MessageTimestamp.tsx、MessageSelector.tsx、messages/（专用消息类型子目录）

对话框与模态组件

TrustDialog/、AutoModeOptInDialog.tsx、BypassPermissionsModeDialog.tsx、CostThresholdDialog.tsx、BridgeDialog.tsx、ExportDialog.tsx、InvalidConfigDialog.tsx、InvalidSettingsDialog.tsx、ManagedSettingsSecurityDialog/、IdeAutoConnectDialog.tsx、IdleReturnDialog.tsx、WorktreeExitDialog.tsx、RemoteEnvironmentDialog.tsx

代码展示

HighlightedCode/、StructuredDiff/、FileEditToolDiff.tsx

设置与配置

Settings/、ThemePicker.tsx、OutputStylePicker.tsx、ModelPicker.tsx、LanguagePicker.tsx

任务与 Agent UI

tasks/、teams/、agents/、CoordinatorAgentStatus.tsx、TaskListV2.tsx、TeammateViewHeader.tsx

导航与搜索

GlobalSearchDialog.tsx、HistorySearchDialog.tsx、QuickOpenDialog.tsx、SearchBox.tsx

设计系统

design-system/、Spinner/、CustomSelect/、LogoV2/、HelpV2/

权限

permissions/（基于角色的访问对话框和提示）

---

12. 工具函数

src/utils/ 目录包含 300+ 文件，提供底层功能。主要分类：

Git 与版本控制

Shell 与进程

认证与安全

配置

文件系统

AI 与模型

Agent 与集群

性能与诊断

UI 辅助工具

---

13. 特殊模式

13.1 Bridge 模式（src/bridge/）

通过基于 WebSocket 的会话入口与 Claude.ai 保持常驻连接。支持持久化后台会话和远程访问。

13.2 Kairos / 助手模式（src/assistant/）

企业助手功能：

• 后台任务处理
• 推送通知
• GitHub Webhook 订阅
• 远程任务监控
• 通过 KAIROS 标志进行功能门控

13.3 协调器模式（src/coordinator/）

多 Agent 编排：

• 任务面板管理
• Agent 交互协调
• 通过 COORDINATOR_MODE 标志进行功能门控

13.4 语音模式（src/voice/）

语音输入/输出支持：

• 语音转文字（STT）集成
• 文字转语音
• 语音转录
• 语音关键词检测

13.5 计划模式

用于在编码前设计实现策略的只读模式：

• 在 .claude/plans/ 中创建计划文件
• 限制工具为只读操作
• 执行前需要用户明确批准
• 由 EnterPlanModeTool / ExitPlanModeTool 管理

13.6 工作树模式

用于安全实验的 Git 工作树隔离：

• 创建临时 Git 工作树
• 支持 tmux 会话管理
• 临时分支创建
• 变更可以合并或丢弃

13.7 Vim 模式（src/vim/）

终端输入的 Vim 键绑定集成。

---

14. 插件与技能

插件系统（src/plugins/）

• plugins/bundled/ 中的内置插件（键盘快捷键、主题等）
• 通过 PluginInstallationManager 管理插件生命周期
• 用于插件管理的 CLI 命令
• 通过 reload-plugins 命令支持热重载

技能系统（src/skills/）

• skills/bundled/ 中的内置技能（提交、审查、简化等）
• 技能是可通过 /skill-name 调用的命名提示词
• 技能发现与执行引擎
• 变更检测支持实时更新

---

15. 钩子与可扩展性

钩子模式（src/schemas/hooks.ts）

通过 Zod 验证定义：

• HookEvent — 执行前/执行后生命周期钩子
• PromptRequest / PromptResponse — 用户提示协议
• 同步和异步钩子响应模式
• 权限决策钩子

React Hooks（src/hooks/）

工具 Hooks（src/utils/hooks/）

用于 Shell 配置、权限状态和工具行为的额外 Hooks。

---

16. 文件统计

---

17. 架构模式

延迟加载与死代码消除

通过 require() 条件导入，由 Bun 的 feature() 标志门控。这使得在打包时可以对整个子系统（例如 KAIROS、COORDINATOR_MODE）进行 Tree-Shaking。

const assistantModule = feature('KAIROS')
  ? require('./assistant/index.js')
  : null;

基于工具的执行模型

与外部世界的每次交互都通过已注册的 Tool 进行。工具具有：

• 声明式 JSON Schema 输入
• 执行前的权限检查
• 执行期间的进度报告
• 结构化结果输出

命令模式

斜杠命令是模块化目录，每个目录导出一个 Command 对象。commands.ts 中的注册表将它们聚合在一起，支持可选的特性门控条件。

消息驱动架构

对话是一系列类型化消息（UserMessage、AssistantMessage、SystemMessage、ProgressMessage 等），由 QueryEngine 管理。工具结果作为 ToolResultBlockParam 消息注入。

上下文压缩

当对话上下文接近模型窗口限制时，系统自动压缩旧消息，同时保留关键上下文。提供多种策略：完整压缩、微压缩（选择性修剪）和会话记忆持久化。

权限优先安全模型

每次工具执行都经过权限检查。模式包括：

• 询问 — 每次操作都提示用户
• 自动允许 — 基于信任规则允许
• 拒绝 — 阻止特定操作
• 文件系统沙箱 — 将文件访问限制在项目目录内

React 终端 UI

整个 UI 是通过 Ink 渲染的 React 组件树。这使得以下特性成为可能：

• 声明式 UI 更新
• 组件组合与复用
• 状态驱动渲染
• 针对终端特定行为的 Hooks（光标、窗口调整、键盘）

---

---

贡献

欢迎贡献！如果你发现了额外的架构细节、发现了不准确之处，或想扩展特定子系统的覆盖范围：

1. Fork 本仓库
2. 为你的更改创建分支（git checkout -b fix/tool-system-details）
3. 提交 Pull Request，并附上清晰的描述说明你添加或修正了什么

请保持贡献的事实性和技术准确性。这是一份参考文档——推测内容应明确标注。

---

免责声明： 这是一份非官方的独立分析。Claude Code 是 Anthropic 的产品。所有商标归其各自所有者所有。

生成于 2025-03-31。基于对 Claude Code 源码树的分析。