Claude Code 源码架构深度分析
16 min read
最近花时间深入分析了 Claude Code 的源码架构，这是一个基于终端的 AI 编程助手，通过自然语言交互帮助用户完成代码编写、文件操作、命令执行等任务。
作为一个技术含量很高的开源项目，它的设计思路和实现细节非常值得学习。本文将从整体架构、核心模块、数据流、权限系统等维度进行深入分析。
项目概述
核心能力
| 能力 | 描述 |
|---|---|
| 代码理解 | 读取、分析、搜索代码库 |
| 文件操作 | 读取、编辑、创建文件 |
| 命令执行 | 执行 Shell/PowerShell 命令 |
| 多 Agent 协作 | 支持多个 Agent 并行工作 |
| MCP 集成 | 通过 Model Context Protocol 连接外部服务 |
| 插件系统 | 可扩展的插件架构 |
| 技能系统 | 预定义和自定义技能 |
运行模式
Claude Code 支持三种运行模式：
- REPL 模式：交互式终端 UI，实时反馈，权限对话框
- SDK/Headless 模式：JSON 输入输出，脚本集成，无 UI 交互
- 远程模式：WebSocket 连接，云端会话，多端同步
技术栈
核心技术
| 类别 | 技术 | 用途 |
|---|---|---|
| 运行时 | Bun / Node.js | JavaScript 运行时 |
| 语言 | TypeScript | 类型安全的 JavaScript 超集 |
| UI 框架 | React + Ink | 终端 UI 渲染 |
| AI SDK | @anthropic-ai/sdk | Claude API 客户端 |
| 协议 | MCP (Model Context Protocol) | 外部服务集成 |
关键依赖
// 核心库
@anthropic-ai/sdk // Claude API
@modelcontextprotocol/sdk // MCP 协议
@commander-js/extra-typings // CLI 命令解析
react // UI 框架
ink // 终端 UI 组件库
// 工具库
lodash-es // 工具函数
zod/v4 // Schema 验证
strip-ansi // ANSI 转义处理
chalk // 终端颜色
整体架构
分层架构图
┌─────────────────────────────────────────────────────────────────────┐
│ 用户交互层 │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │
│ │ CLI 命令系统 │ │ REPL 交互界面 │ │ SDK/Headless API │ │
│ │ (commands/) │ │ (screens/) │ │ (entrypoints/sdk) │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │
├─────────────────────────────────────────────────────────────────────┤
│ UI 组件层 │
│ ┌─────────────────────────────────────────────────────────────────┐│
│ │ Ink 渲染引擎 + React 组件 (components/, ink/) ││
│ │ • Messages: 消息渲染 • Permissions: 权限对话框 ││
│ │ • PromptInput: 输入框 • Spinner: 加载动画 ││
│ │ • Tasks: 任务面板 • Agents: Agent 状态 ││
│ └─────────────────────────────────────────────────────────────────┘│
├─────────────────────────────────────────────────────────────────────┤
│ 核心引擎层 │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │
│ │ QueryEngine │ │ Tool System │ │ Task System │ │
│ │ (query.ts) │ │ (tools/) │ │ (tasks/) │ │
│ │ • 对话管理 │ │ • 工具定义 │ │ • 任务生命周期 │ │
│ │ • API 调用 │ │ • 权限检查 │ │ • 输出管理 │ │
│ │ • 工具编排 │ │ • 结果渲染 │ │ • 状态跟踪 │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │
├─────────────────────────────────────────────────────────────────────┤
│ 服务层 │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │
│ │ MCP Client │ │ API Client │ │ Plugin System │ │
│ │ (services/mcp)│ │ (services/api)│ │ (plugins/) │ │
│ │ • 连接管理 │ │ • Claude API │ │ • 加载机制 │ │
│ │ • 资源发现 │ │ • 日志记录 │ │ • 版本管理 │ │
│ │ • 权限控制 │ │ • 错误处理 │ │ • 依赖解析 │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │
├─────────────────────────────────────────────────────────────────────┤
│ 基础设施层 │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │
│ │ State Mgmt │ │ Permissions │ │ Utilities │ │
│ │ (state/) │ │ (permissions) │ │ (utils/) │ │
│ │ • AppState │ │ • 规则引擎 │ │ • 文件操作 │ │
│ │ • Store │ │ • 分类器 │ │ • Git 集成 │ │
│ │ • Selectors │ │ • 钩子系统 │ │ • Shell 封装 │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
核心模块详解
1. 启动流程模块
启动序列经过精心设计，包含四个阶段：
1. 侧效应预处理 (模块加载前)
• profileCheckpoint: 性能分析标记
• startMdmRawRead: MDM 配置读取 (macOS)
• startKeychainPrefetch: 钥匙串预取 (OAuth/API Key)
2. 初始化阶段 (init())
• enableConfigs(): 加载配置文件
• applySafeConfigEnvironmentVariables(): 应用安全环境变量
• setupGracefulShutdown(): 注册优雅退出处理
• configureGlobalMTLS(): mTLS 配置
• preconnectAnthropicApi(): API 连接预热
3. 信任检查后初始化
• initializeTelemetryAfterTrust(): 遥测初始化
• waitForRemoteManagedSettingsToLoad(): 远程设置加载
4. REPL 启动 (launchRepl)
• 渲染 App → REPL 组件
• 启动 Ink 渲染引擎
• 注册键盘输入处理
性能优化策略
| 优化项 | 实现方式 | 效果 |
|---|---|---|
| 并行预取 | MDM、钥匙串、OAuth 并行启动 | 减少 ~100ms 启动时间 |
| 懒加载 | 动态 import() + feature() 门控 | 减少初始 bundle 大小 |
| API 预连接 | preconnectAnthropicApi() | 重叠 TCP+TLS 握手 (~100-200ms) |
| 缓存预热 | 插件、技能、Git 状态异步加载 | 不阻塞首屏渲染 |
2. 查询引擎模块
QueryEngine 是整个系统的核心引擎，负责管理对话生命周期和会话状态。
查询循环流程
┌─────────────────────────────────────────────────────────────────┐
│ query() 循环流程 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ │
│ │ 准备请求 │ │
│ │ • 构建消息 │ │
│ │ • 应用预算 │ │
│ └──────┬──────┘ │
│ │ │
│ ▼ │
│ ┌─────────────┐ │
│ │ callClaude │ ◄────────────────────────────────────┐ │
│ │ • 流式请求 │ │ │
│ │ • Token 计数 │ │ │
│ └──────┬──────┘ │ │
│ │ │ │
│ ▼ │ │
│ ┌─────────────┐ 是 ┌─────────────┐ │ │
│ │ 有 tool_use?│───────────►│ runTools() │ │ │
│ └──────┬──────┘ └──────┬──────┘ │ │
│ │否 │ │ │
│ │ ▼ │ │
│ │ ┌─────────────┐ │ │
│ │ │ 执行工具 │ │ │
│ │ │ • 权限检查 │ │ │
│ │ │ • 调用工具 │ │ │
│ │ │ • 收集结果 │ │ │
│ │ └──────┬──────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌─────────────┐ │ │
│ └────────────────►│ 构建结果消息 │ │ │
│ └──────┬──────┘ │ │
│ │ │ │
│ ▼ │ │
│ ┌─────────────┐ │ │
│ │ 检查继续？ │───────────┘ │
│ │ • max_turns │ │
│ │ • 预算 │ │
│ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
3. 工具系统模块
工具系统是 Claude Code 的「手脚」，让 AI 能够执行实际操作。
Tool 接口定义
export type Tool<Input extends AnyObject = AnyObject, Output = unknown> = {
// 元数据
readonly name: string
readonly description: string
readonly inputSchema: Input
readonly outputSchema?: z.ZodType<unknown>
// 核心方法
call(
args: z.infer<Input>,
context: ToolUseContext,
canUseTool: CanUseToolFn,
parentMessage: AssistantMessage,
onProgress?: ToolCallProgress
): Promise<ToolResult<Output>>
// 权限相关
checkPermissions(
input: z.infer<Input>,
context: ToolUseContext
): Promise<PermissionResult>
validateInput?(
input: z.infer<Input>,
context: ToolUseContext
): Promise<ValidationResult>
// UI 渲染
renderToolUseMessage(
input: Partial<z.infer<Input>>,
options: { theme: ThemeName; verbose: boolean }
): React.ReactNode
renderToolResultMessage(
content: Output,
progressMessagesForMessage: ProgressMessage[],
options: { /* ... */ }
): React.ReactNode
// 其他特性
isConcurrencySafe(input: z.infer<Input>): boolean
isReadOnly(input: z.infer<Input>): boolean
isDestructive?(input: z.infer<Input>): boolean
interruptBehavior?(): 'cancel' | 'block'
}
工具分类
| 类别 | 工具 |
|---|---|
| 文件操作 | FileReadTool, FileEditTool, FileWriteTool, NotebookEditTool |
| 搜索工具 | GrepTool, GlobTool, WebSearchTool, ToolSearchTool |
| 执行工具 | BashTool, PowerShellTool, REPLTool, SleepTool |
| Agent 工具 | AgentTool, TaskCreateTool, TaskOutputTool, TeamCreateTool |
| MCP 工具 | MCPTool, ListMcpResourceTool, ReadMcpResourceTool |
| 辅助工具 | TodoWriteTool, AskUserQuestionTool, EnterPlanModeTool |
4. Agent 系统模块
Agent 系统支持多 Agent 协作，是 Claude Code 的高级特性。
Agent 架构
┌─────────────────────────────────────────────────────────────────┐
│ Agent 系统架构 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ AgentTool (tools/AgentTool/) │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ 内置 Agents (built-in/) │ │
│ │ ├── general: 通用助手 │ │
│ │ ├── test: 测试专家 │ │
│ │ ├── review: 代码审查 │ │
│ │ └── refactor: 重构专家 │ │
│ ├───────────────────────────────────────────────────────────┤ │
│ │ 自定义 Agents (agents.json) │ │
│ │ • 用户定义的 Agent 配置 │ │
│ │ • 工具白名单/黑名单 │ │
│ │ • 系统提示词定制 │ │
│ ├───────────────────────────────────────────────────────────┤ │
│ │ 运行模式 │ │
│ │ • local_agent: 本地子进程 │ │
│ │ • remote_agent: 远程 daemon │ │
│ │ • in_process_teammate: 进程内队友 │ │
│ └───────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
Agent 通信模式
- 本地模式：进程间管道通信
- 远程模式：WebSocket + 会话 ingress
- 进程内模式：共享状态 + 事件总线
5. MCP 集成模块
MCP (Model Context Protocol) 是 Anthropic 推出的模型上下文协议，用于连接外部服务。
MCP 配置示例
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
}
},
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allow"],
"disabled": false
}
}
}
安全机制
- channelPermissions.ts: 通道权限控制
- channelAllowlist.ts: 服务器白名单
- elicitationHandler.ts: URL 确认处理
- auth.ts: OAuth 认证
6. 权限系统模块
权限系统是 Claude Code 的安全核心，确保 AI 操作在可控范围内。
权限决策流程
canUseTool(tool, input, context)
Step 1: 检查 Deny 规则
• 遍历 alwaysDenyRules[source]
• 匹配工具名或 MCP 服务器前缀
• 匹配 → 直接拒绝
Step 2: 检查 Allow 规则
• 遍历 alwaysAllowRules[source]
• 匹配工具名或模式 (如 "bash(git *)")
• 匹配 → 直接允许
Step 3: 检查 Classifier (如果启用)
• TRANSCRIPT_CLASSIFIER / BASH_CLASSIFIER
• 自动分类工具调用
• 安全 → 允许，危险 → 拒绝/确认
Step 4: 检查 Hooks
• PreToolUse hooks
• 钩子可以批准/拒绝/修改
Step 5: 显示权限对话框
• PermissionDialog 组件
• 用户选择：允许/拒绝/总是允许/总是拒绝
权限模式
| 模式 | 描述 | 使用场景 |
|---|---|---|
| default | 默认模式，需要确认危险操作 | 日常使用 |
| auto | 自动模式，使用 classifier 自动决策 | 批量任务 |
| bypass | 绕过模式，危险操作仍需确认 | 信任环境 |
| yolo | 完全自动，无确认 | CI/CD |
数据流设计
完整数据流
用户输入
│
▼
processUserInput (解析 slash 命令、处理附件)
│
▼
QueryEngine.submitMessage()
│
▼
query() 循环
│
├──────┬────────────┬──────────┐
│ │ │ │
▼ ▼ ▼ ▼
Claude runTools auto- yield
API compact message
│
▼
canUseTool
│
▼
permission
dialog
│
▼
tool.call
│
└─────────────────┘
│
▼
SDKMessage (流式输出)
│
┌─────────┼──────────┐
│ │ │
▼ ▼ ▼
REPL SDK Remote
UI Output Session
目录结构
src/
├── entrypoints/ # 入口点
│ ├── sdk/ # SDK 入口
│ ├── init.ts # 初始化
│ ├── cli.tsx # CLI 入口
│ └── agentSdkTypes.ts # SDK 类型
│
├── screens/ # 主界面
│ ├── REPL.tsx # REPL 主界面
│ └── ...
│
├── components/ # React 组件 (144+)
│ ├── messages/ # 消息组件
│ ├── permissions/ # 权限对话框
│ ├── agents/ # Agent 组件
│ ├── tasks/ # 任务组件
│ └── ...
│
├── tools/ # 工具实现 (43 目录)
│ ├── AgentTool/ # Agent 工具
│ ├── BashTool/ # Bash 工具
│ ├── FileEditTool/ # 文件编辑
│ ├── MCPTool/ # MCP 工具
│ └── ...
│
├── services/ # 服务层 (36 目录)
│ ├── mcp/ # MCP 服务
│ ├── api/ # API 客户端
│ ├── analytics/ # 分析服务
│ ├── lsp/ # LSP 服务
│ └── ...
│
├── commands/ # CLI 命令 (50+)
├── state/ # 状态管理
├── query/ # 查询相关
├── tasks/ # 任务系统
├── utils/ # 工具函数 (50+ 目录)
├── ink/ # Ink 渲染引擎
├── types/ # TypeScript 类型
├── plugins/ # 内置插件
├── skills/ # 技能系统
│
├── main.tsx # 主入口 (4684 行)
├── QueryEngine.ts # 查询引擎 (1296 行)
├── query.ts # 查询实现 (1730 行)
├── Tool.ts # 工具定义 (793 行)
└── commands.ts # 命令注册 (755 行)
设计模式与最佳实践
使用的设计模式
| 模式 | 应用场景 | 实现位置 |
|---|---|---|
| 工厂模式 | Tool 创建 | tools.ts |
| 策略模式 | 权限决策 | permissions.ts |
| 观察者模式 | 状态变更 | store.ts |
| 责任链模式 | 工具执行 | runTools() |
| 生成器模式 | 流式输出 | AsyncGenerator |
| 依赖注入 | 查询依赖 | query/deps.ts |
| 单例模式 | Store | createStore() |
| 适配器模式 | MCP 传输 | InProcessTransport |
代码规范
// 1. 类型安全 - 使用 Zod schema 验证运行时数据
const inputSchema = z.object({
command: z.string(),
path: z.string().optional(),
})
// 2. 错误处理 - 使用类型化的错误处理
try {
await tool.call(args, context)
} catch (error) {
if (error instanceof APIError) {
// 处理 API 错误
}
}
// 3. 性能优化 - 使用 memoization 避免重复计算
const getSystemPrompt = memoize(async () => {
// ...
})
// 4. 特性门控 - 使用 feature() 进行编译时优化
if (feature('COORDINATOR_MODE')) {
// 仅在该特性启用时包含代码
}
安全架构
安全层次
┌─────────────────────────────────────────────────────────────────┐
│ 安全架构层次 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Layer 1: 权限控制 │
│ • 工具级权限：每个工具都有权限检查 │
│ • 规则引擎：allow/deny/ask 规则 │
│ • 分类器：自动识别危险操作 │
│ │
│ Layer 2: 沙箱隔离 │
│ • 命令沙箱：限制命令执行范围 │
│ • 文件系统沙箱：限制文件访问路径 │
│ • 网络沙箱：限制网络访问 │
│ │
│ Layer 3: 审计日志 │
│ • 工具调用日志 │
│ • 权限决策日志 │
│ • 会话转录 │
│ │
│ Layer 4: 数据保护 │
│ • 密钥加密存储 (钥匙串) │
│ • 敏感信息脱敏 │
│ • 会话数据加密 │
│ │
└─────────────────────────────────────────────────────────────────┘
关键指标
项目规模
| 指标 | 数值 |
|---|---|
| 代码文件数 | ~1900 |
| 核心代码行数 | ~100,000+ |
| 组件数量 | 144+ |
| CLI 命令数 | 50+ |
| 工具数量 | 40+ |
| 服务模块数 | 36+ |
性能基准
| 操作 | 目标时间 |
|---|---|
| 启动时间 | < 300ms |
| 模块加载 | < 135ms |
| 首屏渲染 | < 300ms |
| API 响应 | < 2s |
| 工具执行 | < 5s |
总结
通过对 Claude Code 源码的深入分析，我学到了以下几点：
-
分层架构清晰：从用户交互层到基础设施层，每层职责明确，便于维护和扩展。
-
类型安全优先：全面使用 TypeScript 和 Zod schema，确保编译时和运行时的类型安全。
-
性能优化到位：从启动预加载、懒加载、API 预连接到缓存预热，每个细节都经过精心设计。
-
权限系统严谨：多层权限检查、规则引擎、分类器、沙箱隔离，构建了完整的安全体系。
-
可扩展性强：插件系统、技能系统、自定义 Agent、MCP 集成，提供了丰富的扩展能力。
-
设计模式运用：工厂、策略、观察者、责任链、生成器等模式的灵活运用，代码质量很高。
这个项目不仅是一个实用的 AI 编程助手，更是一个学习现代 TypeScript 应用架构的绝佳案例。
参考链接：