Claude-Code-SourceCode-ZH

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. 技术栈

层级	技术
语言	TypeScript (.ts / .tsx)
运行时	Bun（打包工具，通过 bun:bundle 实现特性标志）
UI 框架	React + Ink（终端 React 渲染器）
API 客户端	@anthropic-ai/sdk（Anthropic SDK）
MCP	@modelcontextprotocol/sdk
CLI 框架	@commander-js/extra-typings
数据验证	Zod v4
样式	Chalk（终端颜色）
状态管理	Zustand 风格 Store + React Context

---

3. 目录结构

claude-code
└── 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/）

文件	用途
cli.tsx	CLI 入口点，带 React/Ink UI 渲染
init.ts	引导初始化、版本检查
mcp.ts	Model Context Protocol 集成
agentSdkTypes.ts	Agent SDK 的类型定义
sandboxTypes.ts	沙箱执行环境类型
sdk/	SDK 相关实现

启动阶段：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 个工具）

文件操作

工具	用途
FileReadTool	读取文件内容，支持行范围
FileWriteTool	创建或覆盖文件
FileEditTool	精确字符串替换编辑
GlobTool	基于模式的文件匹配
GrepTool	基于正则的内容搜索（基于 ripgrep）

代码执行

工具	用途
BashTool	执行 Shell 命令，支持超时
PowerShellTool	执行 PowerShell 命令（Windows）
REPLTool	执行 Python 代码（仅内部使用）
NotebookEditTool	Jupyter Notebook 单元格操作

网络与搜索

工具	用途
WebFetchTool	获取并解析网页内容
WebSearchTool	互联网搜索
ToolSearchTool	搜索可用的延迟加载工具

Agent 与任务管理

工具	用途
AgentTool	生成子 Agent 进行并行工作
TaskCreateTool	创建新的后台任务
TaskGetTool	获取任务状态和结果
TaskUpdateTool	更新任务状态或描述
TaskListTool	列出所有任务及其状态
TaskStopTool	终止正在运行的任务
TaskOutputTool	流式读取任务输出
SendMessageTool	向运行中的 Agent 发送消息

计划与工作流

工具	用途
EnterPlanModeTool	进入只读计划模式
ExitPlanModeTool	退出计划模式并获得批准
EnterWorktreeTool	创建隔离的 Git 工作树
ExitWorktreeTool	从工作树返回并携带变更

MCP（Model Context Protocol）

工具	用途
MCPTool	调用 MCP 服务器上的工具
McpAuthTool	MCP 服务器认证
ListMcpResourcesTool	列出 MCP 服务器资源
ReadMcpResourceTool	读取特定 MCP 资源

配置与系统

工具	用途
ConfigTool	读取/修改设置
SkillTool	执行用户自定义技能
AskUserQuestionTool	提示用户输入/确认
BriefTool	生成会话摘要
TodoWriteTool	管理待办事项列表
SleepTool	暂停执行指定时长

团队与远程

工具	用途
TeamCreateTool	创建 Agent 团队
TeamDeleteTool	删除 Agent 团队
RemoteTriggerTool	触发远程任务执行
ScheduleCronTool	调度定时任务
LSPTool	Language Server Protocol 集成

内部工具

工具	用途
SyntheticOutputTool	用于结构化响应的合成输出

---

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/）

文件	用途
AppState.tsx	React Context 提供者，带 useAppState(selector) Hook
AppStateStore.ts	中心状态结构定义
store.ts	Zustand 风格 Store 实现

关键状态字段

{
  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）

类型	描述
local_bash	本地 Shell 命令执行
local_agent	本地子 Agent（通过 AgentTool 生成）
remote_agent	远程 Agent 执行
in_process_teammate	进程内队友（共享内存空间）
local_workflow	本地多步骤工作流
monitor_mcp	MCP 服务器监控任务
dream	自动梦境后台任务

任务生命周期

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/）

文件	用途
client.ts	Anthropic SDK 客户端，支持多提供商
claude.ts	消息流式传输与工具调用处理
bootstrap.ts	启动时获取引导数据
usage.ts	Token 用量记录
errors.ts / errorUtils.ts	错误分类与处理
logging.ts	API 请求/响应日志
withRetry.ts	指数退避重试逻辑
filesApi.ts	文件上传/下载
sessionIngress.ts	远程会话桥接
grove.ts	Grove 集成
referral.ts	推荐/通行证系统

支持的提供商：

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

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

文件	用途
client.ts	MCP 客户端实现
types.ts	服务器定义与连接类型
config.ts	配置加载与验证
auth.ts	MCP 服务器的 OAuth/认证
officialRegistry.ts	官方 MCP 服务器注册表
InProcessTransport.ts	进程内 MCP 传输
normalization.ts	URL/配置规范化
elicitationHandler.ts	通过 MCP 提示用户

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

文件	用途
index.ts	事件日志 API
growthbook.ts	特性标志与 A/B 测试
sink.ts	分析接收器配置
datadog.ts	Datadog 集成
firstPartyEventLogger.ts	第一方分析
metadata.ts	事件元数据增强

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

文件	用途
compact.ts	完整上下文窗口压缩
autoCompact.ts	自动压缩触发器
microCompact.ts	选择性消息修剪
compactWarning.ts	压缩用户警告
sessionMemoryCompact.ts	跨压缩的记忆持久化

10.5 其他服务

目录/文件	用途
SessionMemory/	会话记忆持久化与转录
MagicDocs/	智能文档生成
AgentSummary/	Agent 执行摘要
PromptSuggestion/	建议的后续提示词
extractMemories/	从对话中提取学习内容
plugins/	插件生命周期管理
oauth/	OAuth 客户端流程
lsp/	Language Server Protocol 客户端
remoteManagedSettings/	远程配置同步
settingsSync/	设置同步
teamMemorySync/	团队记忆同步
policyLimits/	速率限制与配额
autoDream/	自动梦境后台功能
tips/	上下文提示系统
toolUseSummary/	工具使用分析
voice.ts / voiceStreamSTT.ts	语音输入处理

---

11. UI 层

框架

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

核心应用组件

组件	文件	用途
App	components/App.tsx	根应用组件
REPL	screens/REPL.tsx	主 REPL 界面
Messages	components/Messages.tsx	对话消息列表
PromptInput	components/PromptInput/	带自动补全的用户输入
StatusLine	components/StatusLine.tsx	底部状态栏

组件分类

消息展示

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 与版本控制

文件/目录	用途
git.ts	Git 命令封装
git/	扩展 Git 工具
gitDiff.ts	Diff 生成与解析
gitSettings.ts	Git 指令开关
github/	GitHub API 辅助工具
worktree.ts	Git 工作树自动化

Shell 与进程

文件/目录	用途
Shell.ts	Shell 执行封装
shell/	Shell 配置与辅助工具
bash/	Bash 专用工具
powershell/	PowerShell 工具
execFileNoThrow.ts	安全进程启动
process.ts	进程管理

认证与安全

文件/目录	用途
auth.ts	API 密钥、OAuth、AWS/GCP 凭证管理
secureStorage/	钥匙串集成（macOS）
permissions/	权限规则、文件系统沙箱
crypto.ts	加密工具
sandbox/	沙箱环境

配置

文件/目录	用途
config.ts	.claude/config.json 管理
settings/	settings.json 验证与应用
env.ts	静态环境变量
envDynamic.ts	动态环境检测
envUtils.ts	环境变量解析
managedEnv.ts	托管环境配置

文件系统

文件/目录	用途
claudemd.ts	CLAUDE.md 自动发现与解析
fileStateCache.ts	文件变更追踪
fileHistory.ts	文件快照（用于撤销）
filePersistence/	持久化文件存储
glob.ts	Glob 模式匹配
ripgrep.ts	Ripgrep 集成

AI 与模型

文件/目录	用途
model/	模型选择与上下文窗口管理
modelCost.ts	Token 定价表
thinking.ts	扩展思考模式配置
effort.ts	任务工作量级别管理
fastMode.ts	速度优化模式
advisor.ts	AI 顾问集成
tokens.ts	Token 计数与估算

Agent 与集群

文件/目录	用途
swarm/	多 Agent 集群协调
teammate.ts	队友/Agent 模式工具
forkedAgent.ts	分叉 Agent 进程管理
agentContext.ts	Agent 执行上下文

性能与诊断

文件/目录	用途
startupProfiler.ts	启动性能监控
headlessProfiler.ts	运行时性能分析
fpsTracker.ts	帧率指标
diagLogs.ts	诊断日志（无 PII）
debug.ts	调试工具

UI 辅助工具

文件/目录	用途
theme.ts	主题管理
renderOptions.ts	Ink 渲染配置
format.ts	数字/时长格式化
markdown.ts	Markdown 处理
cliHighlight.ts	CLI 语法高亮

---

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/）

Hook	用途
useSettings	设置变更检测
useTerminalSize	终端尺寸追踪
useExitOnCtrlC	信号处理
useBlink	光标闪烁动画
useDoublePress	双按键检测
useCanUseTool	工具权限验证

工具 Hooks（src/utils/hooks/）

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

---

16. 文件统计

分类	数量
TypeScript 文件总数	1,884
命令模块	101
工具实现	41
UI 组件	130+
工具函数文件	300+
服务模块	35+
顶层源文件	18
入口点	6
src/ 中的子目录	37

---

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（光标、窗口调整、键盘）

---

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

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