15 KiB
15 KiB
Claude Code 架构总览
本文件说明：介绍 Claude Code 的整体架构设计、技术栈、核心设计模式。
1. 项目背景
Claude Code 是 Anthropic 官方开发的 CLI（命令行界面）工具，旨在为开发者提供一个在终端环境中与 Claude 交互的途径，完成各种软件工程任务。
核心定位
- 终端优先：专为命令行环境设计，使用 Ink（React for CLIs）渲染 Terminal UI
- 软件工程助手：专注于代码编写、文件操作、Git 管理、任务执行等开发任务
- 安全可控：提供细粒度的权限控制，用户可精确控制工具访问范围
源码泄露事件
2026 年 3 月 31 日，通过 npm source map 泄露了大量 Claude Code 源码，引起了安全研究社区的关注。这次泄露使外界得以深入了解 Claude Code 的内部实现机制。
2. 技术栈详解
2.1 运行时环境：Bun
Claude Code 使用 Bun 作为 JavaScript/TypeScript 运行时：
// 使用 bun:bundle feature flag 进行条件编译
import { feature } from 'bun:bundle'
// Dead code elimination 示例
const REPLTool = feature('REPL_MODE')
? require('./tools/REPLTool/REPLTool.js').REPLTool
: null
Bun 的优势：
- 启动速度快
- 内置 bundler 功能，支持条件导入（Dead code elimination）
- 原生支持 TypeScript
- 高效的 I/O 操作
2.2 语言：TypeScript
全项目使用 TypeScript 开发，具有：
- 完整的类型系统
- 严格的参数校验（基于 Zod v4）
- 模块化的接口设计
2.3 终端 UI：React + Ink
Claude Code 使用 Ink 库来实现 React 风格的终端界面：
// Ink 组件示例
import { Box, Text } from 'ink'
const MyComponent = () => (
<Box>
<Text>Hello, Terminal!</Text>
</Box>
)
UI 组件特点：
- 支持颜色、布局、边框等终端视觉效果
- 兼容 React 生态系统（hooks、context）
- 用于渲染消息、进度条、选择器等 UI 元素
2.4 CLI 框架：Commander.js
使用 Commander.js 处理命令行参数和子命令：
import { Command } from '@commander-js/extra-typings'
const program = new Command()
program
.name('claude')
.description('Anthropic 的 CLI 工具')
.version('1.0.0')
2.5 参数校验：Zod v4
使用 Zod v4 进行运行时参数校验：
import { z } from 'zod/v4'
const inputSchema = z.object({
file_path: z.string(),
offset: z.number().int().nonnegative().optional(),
limit: z.number().int().positive().optional(),
})
2.6 代码搜索：ripgrep
内置集成了 ripgrep (rg) 用于高效的代码搜索：
// 在 GrepTool 等工具中使用
import { execFile } from 'child_process'
execFile('rg', ['--json', pattern, directory], callback)
3. 核心架构设计
3.1 整体架构图
┌─────────────────────────────────────────────────────────────┐
│ main.tsx │
│ (CLI 入口点) │
└─────────────────────┬───────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ QueryEngine │
│ (查询引擎核心) │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ - submitMessage(): 处理用户输入 │ │
│ │ - query(): 执行 API 调用循环 │ │
│ │ - 流式响应处理 │ │
│ │ - 工具调用编排 │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────┬───────────────────────────────────────────┘
│
┌─────────────┼─────────────┐
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Tools │ │ Commands │ │ Context │
│ (工具系统) │ │ (命令系统) │ │ (上下文系统) │
└─────────────┘ └─────────────┘ └─────────────┘
3.2 工具系统架构
工具系统是 Claude Code 最核心的扩展机制：
┌─────────────────────────────────────────────────────────────┐
│ Tool.ts │
│ (工具基类定义) │
│ - inputSchema: Zod 输入校验 │
│ - call(): 工具执行入口 │
│ - checkPermissions(): 权限检查 │
│ - render*: UI 渲染方法 │
└─────────────────────────────────────────────────────────────┘
│
┌────────────────────┼────────────────────┐
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ BashTool │ │ FileReadTool │ │ AgentTool │
│ (Shell命令) │ │ (文件读取) │ │ (子Agent) │
└─────────────┘ └─────────────┘ └─────────────┘
│ │ │
└────────────────────┼────────────────────┘
▼
┌───────────────────────────────────┐
│ ToolRegistry (tools.ts) │
│ - getAllBaseTools(): 获取所有工具 │
│ - getTools(): 按权限过滤工具 │
│ - assembleToolPool(): 合并 MCP │
└───────────────────────────────────┘
3.3 命令系统架构
命令系统支持三种类型的命令：
type CommandType =
| 'prompt' // 展开为提示发送给模型
| 'local' // 本地执行，返回文本结果
| 'local-jsx' // 本地执行，渲染 Ink UI
命令注册流程：
- 在
commands.ts中定义命令 - 使用条件编译控制命令可见性
- 通过
getCommands()获取可用命令列表
3.4 查询管道架构
用户输入 ──► processUserInput() ──► query() ──► API 调用
│ │
│ ▼
│ 工具执行循环
│ │
│ ┌─────────┼─────────┐
│ ▼ ▼ ▼
│ Tool 1 Tool 2 Tool N
│ │ │ │
│ └─────────┼─────────┘
│ ▼
│ 结果处理 ◄──────┐
│ │ │
│ ▼ │
└──────► 结果返回 ───────────┘
4. 关键设计模式
4.1 工厂模式 (Factory Pattern)
使用 buildTool() 工厂函数创建工具实例：
export function buildTool<D extends AnyToolDef>(def: D): BuiltTool<D> {
return {
...TOOL_DEFAULTS, // 填充默认实现
userFacingName: () => def.name,
...def,
} as BuiltTool<D>
}
4.2 策略模式 (Strategy Pattern)
权限检查使用策略模式：
async checkPermissions(
input: z.infer<Input>,
context: ToolUseContext,
): Promise<PermissionResult> {
// 根据权限模式选择不同的检查策略
switch (context.mode) {
case 'auto': return autoCheck(input, context)
case 'bypass': return allowAll(input)
case 'default': return defaultCheck(input, context)
}
}
4.3 装饰器模式 (Decorator Pattern)
backfillObservableInput() 允许在工具执行前修改输入：
backfillObservableInput?(input: Record<string, unknown>): void {
// 在观察者看到输入之前修改它
// 必须幂等
}
4.4 生成器模式 (Generator Pattern)
查询管道使用 AsyncGenerator 实现流式处理：
async *query(params: QueryParams): AsyncGenerator<
| StreamEvent
| RequestStartEvent
| Message
| TombstoneMessage
| ToolUseSummaryMessage,
Terminal
> {
// 流式 yield 消息
}
5. 状态管理
5.1 全局状态 (AppState)
interface AppState {
toolPermissionContext: ToolPermissionContext
fastMode: boolean
fileHistory: FileHistoryState
mcp: MCPState
// ...其他状态
}
5.2 会话状态
- Session ID：唯一标识每次会话
- Message 列表：维护对话历史
- Token 使用：追踪 API 调用成本
- 文件缓存：readFileState 缓存已读文件内容
6. 安全机制
6.1 权限模式 (Permission Modes)
| 模式 | 描述 |
|---|---|
default |
执行危险操作前询问用户 |
auto |
基于规则自动允许/拒绝 |
bypass |
允许所有操作（仅供可信环境） |
plan |
计划模式，限制更严格 |
6.2 工具沙箱
BashTool 支持使用沙箱执行命令：
const shouldUseSandbox = await shouldUseSandbox(command)
if (shouldUseSandbox) {
// 使用沙箱执行
} else {
// 直接执行
}
7. 扩展机制
7.1 MCP (Model Context Protocol)
支持通过 MCP 协议扩展工具：
interface MCPServerConnection {
name: string
type: 'stdio' | 'http'
command?: string
args?: string[]
env?: Record<string, string>
}
7.2 插件系统
// 插件加载
const plugins = await loadAllPluginsCacheOnly()
// 插件命令注册
export function getPluginCommands(): Promise<Command[]>
7.3 技能系统 (Skills)
技能是保存在本地目录中的可执行脚本：
// 技能目录结构
~/.claude/skills/
├── skill-name/
│ ├── skill.md # 技能定义
│ └── script.sh # 执行脚本
8. 性能优化
8.1 记忆化 (Memoization)
使用 lodash 的 memoize 缓存昂贵计算：
export const getGitStatus = memoize(async (): Promise<string | null> => {
// Git 状态获取（只计算一次）
})
8.2 条件编译 (Dead Code Elimination)
通过 Bun 的 feature() 实现条件编译：
const SleepTool = feature('PROACTIVE') || feature('KAIROS')
? require('./tools/SleepTool/SleepTool.js').SleepTool
: null
8.3 自动压缩 (Auto-compact)
当上下文接近 Token 限制时自动压缩历史：
const { compactionResult } = await deps.autocompact(
messagesForQuery,
toolUseContext,
{ systemPrompt, userContext, systemContext, toolUseContext },
querySource,
tracking,
snipTokensFreed,
)
9. 源码目录结构
claude-code/
├── src/
│ ├── main.tsx # CLI 入口
│ ├── QueryEngine.ts # 查询引擎
│ ├── Tool.ts # 工具基类
│ ├── tools.ts # 工具注册表
│ ├── commands.ts # 命令注册
│ ├── context.ts # 上下文收集
│ ├── cost-tracker.ts # 成本追踪
│ ├── query.ts # 查询管道
│ │
│ ├── tools/ # 工具实现
│ │ ├── BashTool/ # Shell 命令执行
│ │ ├── FileReadTool/ # 文件读取
│ │ ├── FileEditTool/ # 文件编辑
│ │ ├── FileWriteTool/ # 文件写入
│ │ ├── GlobTool/ # 文件模式匹配
│ │ ├── GrepTool/ # 代码搜索
│ │ ├── AgentTool/ # 子 Agent
│ │ ├── WebFetchTool/ # 网页获取
│ │ ├── WebSearchTool/ # 网络搜索
│ │ ├── Task*/ # 任务管理系列
│ │ └── ...
│ │
│ ├── services/ # 服务层
│ │ ├── api/ # API 调用
│ │ ├── mcp/ # MCP 协议
│ │ ├── compact/ # 上下文压缩
│ │ └── analytics/ # 分析服务
│ │
│ ├── state/ # 状态管理
│ │ ├── AppState.ts
│ │ └── store.ts
│ │
│ └── utils/ # 工具函数
│ ├── permissions/ # 权限系统
│ ├── model/ # 模型配置
│ └── ...
│
├── package.json
└── tsconfig.json
10. 总结
Claude Code 的架构设计体现了以下原则：
- 模块化：清晰的分层和模块划分
- 可扩展性：工具系统、命令系统、插件系统三位一体
- 类型安全：TypeScript + Zod 双重保障
- 性能优先：记忆化、条件编译、流式处理
- 安全可控：细粒度的权限控制系统
这套架构使得 Claude Code 能够有效地在终端环境中执行复杂的软件工程任务，同时保持高度的可配置性和安全性。