Claude Code 源码深度解析:Anthropic 官方 AI 编程助手的架构设计与工程实践

• 知道Claude Code的原理之后，能更好的使用它，比如上下文是如何管理的，就会明白多轮对话之后，效果衰减，不如新开一个对话。
• 找工作的时候是个加持项。

引言

2026年3月31日，Anthropic 官方 AI 编程助手 Claude Code 的完整源码意外泄露。由于 npm 发布时附带了包含完整源码的 source map 文件（cli.js.map，体积达57MB），开发者得以从 Anthropic 的 R2 存储桶下载到未混淆的 TypeScript 源码。还原后的代码库包含约1900个文件、超过70万行代码，为我们深入理解顶级 AI Agent 的架构设计提供了绝佳机会。

本文将从技术架构、核心子系统、设计模式等多个维度，对 Claude Code 进行全面剖析。

一、项目概览

1.1 Claude Code 是什么

Claude Code 是 Anthropic 推出的命令行 AI 编程助手，支持：

• 文件编辑与代码重构
• Shell 命令执行
• Git 工作流管理
• 代码审查与调试
• 多 Agent 协作
• IDE 集成（VS Code、JetBrains）
• Model Context Protocol (MCP) 协议支持

1.2 技术栈一览

1.3 代码规模

• 文件数量：约 1,900 个
• 代码行数：512,000+ 行（核心源码）
• 主要目录结构：

src/├── main.tsx                 # 入口点（Commander.js CLI 解析器）├── QueryEngine.ts           # 核心 LLM API 引擎（~46K 行）├── Tool.ts                  # 工具类型定义（~29K 行）├── commands.ts              # 命令注册表（~25K 行）├── tools.ts                 # 工具注册表├── context.ts               # 系统/用户上下文收集├── cost-tracker.ts          # Token 成本追踪│├── tools/                   # Agent 工具实现（~40个）├── commands/                # 斜杠命令实现（~50个）├── components/              # Ink UI 组件（~140个）├── services/                # 外部服务集成├── hooks/                   # React Hooks├── types/                   # TypeScript 类型定义├── utils/                   # 工具函数├── screens/                 # 全屏 UI（Doctor、REPL、Resume）│├── bridge/                  # IDE 集成层├── coordinator/             # 多 Agent 协调器├── plugins/                 # 插件系统├── skills/                  # 技能系统├── server/                  # 服务器模式├── remote/                  # 远程会话├── memdir/                  # 持久化记忆目录├── tasks/                   # 任务管理├── state/                   # 状态管理├── voice/                   # 语音输入├── vim/                     # Vim 模式└── schemas/                 # 配置 Schema（Zod）

二、核心架构设计

2.1 整体架构

Claude Code 采用管道式架构，整个 UI 层基于 React + Ink 构建，使其成为完全响应式的 CLI 应用：

用户输入 → CLI 解析器 → 查询引擎 → LLM API → 工具执行循环 → 终端 UI

2.2 启动流程

入口点（src/main.tsx）：

• 使用 Commander.js 解析 CLI 参数和标志
• 启动并行预取副作用（MDM 设置、Keychain、API 预连接）
• 初始化 React/Ink 渲染器
• 交由 REPL 启动器（src/replLauncher.tsx）

初始化序列（src/entrypoints/）：

启动时执行并行初始化：MDM 策略读取、Keychain 预取、特性标志检查，然后核心初始化。

2.3 查询引擎（QueryEngine.ts）

查询引擎是 Claude Code 的心脏，约46,000行代码，负责：

• 流式响应
  ：从 Anthropic API 接收流式数据
• 工具调用循环
  ：当 LLM 请求工具时，执行工具并将结果反馈
• 思考模式
  ：扩展思考与预算管理
• 重试逻辑
  ：针对瞬态故障的自动重试与退避
• Token 计数
  ：跟踪输入/输出 token 和每轮成本
• 上下文管理
  ：管理对话历史和上下文窗口

2.4 状态管理

采用 React context + 自定义 store 模式：

AppState 对象传递给工具上下文，使工具能访问对话历史、设置和运行时状态。

三、工具系统（Tool System）

3.1 设计理念

每个工具都是自包含模块，定义了：

• 输入 Schema
  ：Zod 验证的参数
• 权限模型
  ：哪些操作需要用户批准
• 执行逻辑
  ：工具的实际实现
• UI 组件
  ：调用和结果在终端中的渲染方式
• 并发安全
  ：是否可并行运行

3.2 工具定义模式

typescript
exportconstMyTool = buildTool({name: 'MyTool',aliases: ['my_tool'],description: '工具描述',inputSchema: z.object({param: z.string(),  }),asynccall(args, context, canUseTool, parentMessage, onProgress) {// 执行并返回 { data: result, newMessages?: [...] }  },asynccheckPermissions(input, context) { /* 权限检查 */ },isConcurrencySafe(input) { /* 可并行运行？ */ },isReadOnly(input) { /* 非破坏性？ */ },prompt(options) { /* 系统提示注入 */ },renderToolUseMessage(input, options) { /* 调用的 UI */ },renderToolResultMessage(content, progressMessages, options) { /* 结果的 UI */ },})

每个工具的目录结构：

src/tools/MyTool/├── MyTool.ts        # 主实现├── UI.tsx           # 终端渲染├── prompt.ts        # 系统提示贡献└── utils.ts         # 工具特定辅助函数

3.3 工具分类

文件系统工具

Shell 与执行工具

Agent 与编排工具

任务管理工具

Web 工具

MCP 工具

集成工具

调度与触发工具

四、命令系统（Command System）

4.1 命令类型

用户可通过 /command-name 在 REPL 中调用斜杠命令。三种类型：

4.2 主要命令

五、核心子系统

5.1 Bridge（IDE 集成）

位置：src/bridge/

Bridge 是连接 Claude Code CLI 与 IDE 扩展（VS Code、JetBrains）的双向通信层。

架构：

┌──────────────────┐         ┌──────────────────────┐│   IDE Extension  │◄───────►│   Bridge Layer       ││  (VS Code, JB)   │  JWT    │  (src/bridge/)       ││                  │  Auth   │                      ││  - UI 渲染       │         │  - 会话管理          ││  - 文件监视      │         │  - 消息路由          ││  - Diff 显示     │         │  - 权限代理          │└──────────────────┘         └──────────┬───────────┘                                        │                                        ▼                              ┌──────────────────────┐                              │   Claude Code Core   │                              │  (QueryEngine, Tools)│                              └──────────────────────┘

关键文件：

5.2 MCP（Model Context Protocol）

位置：src/services/mcp/

Claude Code 既可作为 MCP 客户端（消费 MCP 服务器的工具/资源），也可作为 MCP 服务器（通过 src/entrypoints/mcp.ts 暴露自己的工具）。

客户端功能：

• 工具发现：枚举已连接 MCP 服务器的工具
• 资源浏览：列出和读取 MCP 暴露的资源
• 动态工具加载：ToolSearchTool 在运行时发现工具
• 认证：McpAuthTool 处理 MCP 服务器认证流程

5.3 权限系统

位置：src/hooks/toolPermission/

每个工具调用在执行前都经过集中权限检查。

权限模式：

权限规则使用通配符模式：

Bash(git *)           # 允许所有 git 命令无需提示Bash(npm test)        # 特定允许 'npm test'FileEdit(/src/*)      # 允许编辑 src/ 下的任何内容FileRead(*)           # 允许读取任何文件

5.4 插件系统

位置：src/plugins/、src/services/plugins/

支持可安装插件扩展能力。

插件生命周期：

1. 发现——扫描插件目录和市场
2. 安装——下载并注册（/plugin 命令）
3. 加载——启动时或按需初始化
4. 执行——插件可贡献工具、命令和提示
5. 自动更新——usePluginAutoupdateNotification 处理更新

5.5 技能系统（Skill System）

位置：src/skills/

技能是可复用的命名工作流，捆绑提示和工具配置用于特定任务。

内置技能（16个）：

5.6 任务系统

位置：src/tasks/

管理后台和并行工作项。

任务类型：

5.7 记忆系统（Memory System）

位置：src/memdir/

基于 CLAUDE.md 文件的持久化记忆系统。

记忆层次：

5.8 协调器（Coordinator）

位置：src/coordinator/

编排多个 Agent 并行处理任务的不同方面。

• coordinatorMode.ts
   管理协调器生命周期
• TeamCreateTool
   和 TeamDeleteTool 管理 Agent 团队
• SendMessageTool
   启用 Agent 间通信
• AgentTool
   生成子 Agent

5.9 语音系统

位置：src/voice/

免提交互的语音输入/输出支持。

组件：

• 语音服务（src/services/voice.ts）
• STT 流式传输（src/services/voiceStreamSTT.ts）
• 关键词（src/services/voiceKeyterms.ts）
• 语音命令（src/commands/voice/）

六、设计模式与工程亮点

6.1 并行预取（Parallel Prefetch）

启动优化——MDM 设置、Keychain 读取和 API 预连接作为副作用在重模块评估前并行触发：

typescript
// main.tsxstartMdmRawRead()startKeychainPrefetch()

6.2 懒加载（Lazy Loading）

重度模块通过动态 import() 延迟加载：

• OpenTelemetry（~400KB）
• gRPC（~700KB）

6.3 特性标志与死代码消除

Bun 的 bun:bundle 特性标志在构建时启用死代码消除：

typescript
import { feature } from'bun:bundle'if (feature('PROACTIVE')) {// 主动 Agent 工具}

主要特性标志：

6.4 Agent 群（Agent Swarms）

通过 AgentTool 生成子 Agent，coordinator/ 处理编排。TeamCreateTool 启用团队级并行工作。

6.5 React for CLI

整个 UI 层使用 React + Ink 构建，享受：

• 组件化开发
• Hooks 模式
• 响应式更新
• React Compiler 优化

6.6 Schema 驱动验证

所有输入验证使用 Zod v4，在系统边界进行强类型检查。

七、服务层

位置：src/services/

八、配置与迁移

配置位置：

• 全局：~/.claude/config.json、~/.claude/settings.json
• 项目：.claude/config.json、.claude/settings.json
• 系统：macOS Keychain + MDM、Windows Registry + MDM
• 托管：企业用户的远程同步

迁移（src/migrations/）：处理版本间配置格式变更——读取旧配置并转换为当前 schema。

九、关键文件解析

十、总结与启示

10.1 架构亮点

1. 终端原生 React 应用
   ：将现代前端框架思想引入 CLI，实现组件化、响应式的终端 UI
2. 工具化架构
   ：每个能力都是自包含工具，具有清晰的接口、权限模型和 UI 渲染
3. 多 Agent 协作
   ：内置协调器支持 Agent 群、团队并行工作
4. 协议优先
   ：MCP 和 LSP 协议支持，实现生态互联
5. 企业级安全
   ：完善的权限系统、MDM 集成、OAuth 认证

10.2 工程实践

1. 性能优化
   ：并行预取、懒加载、死代码消除
2. 类型安全
   ：TypeScript 严格模式 + Zod schema 验证
3. 可扩展性
   ：插件系统、技能系统、MCP 协议
4. 可观测性
   ：OpenTelemetry 遥测、成本追踪、诊断工具

10.3 对 AI Agent 开发的启示

1. 工具抽象是核心
   ：将每个能力抽象为标准化工具，便于组合和扩展
2. 权限模型不可少
   ：AI Agent 执行操作必须有清晰的权限边界
3. 多 Agent 协作是趋势
   ：复杂任务需要多个专业 Agent 协同完成
4. 记忆系统是关键
   ：持久化记忆让 Agent 具备长期上下文
5. 协议标准化
   ：MCP 等协议让 Agent 能够接入外部工具生态

参考资料

• Claude Code 源码快照：https://github.com/777genius/claude-code-source-code-full
• 架构文档：docs/architecture.md
• 工具参考：docs/tools.md
• 子系统指南：docs/subsystems.md
• 命令参考：docs/commands.md

声明：本文基于公开泄露的源码快照进行技术分析，仅用于学习和研究目的。Claude Code 的原始源码为 Anthropic 所有，本文不授予任何权利。