first commit
This commit is contained in:
H
441
claude-code-中文Wiki/01-架构总览.md
Normal file
441
claude-code-中文Wiki/01-架构总览.md
Normal file
@@ -0,0 +1,441 @@
|
||||
# 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](https://bun.sh/) 作为 JavaScript/TypeScript 运行时：
|
||||
|
||||
```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](https://github.com/vadimdemedes/ink) 库来实现 React 风格的终端界面：
|
||||
|
||||
```typescript
|
||||
// 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 处理命令行参数和子命令：
|
||||
|
||||
```typescript
|
||||
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 进行运行时参数校验：
|
||||
|
||||
```typescript
|
||||
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`) 用于高效的代码搜索：
|
||||
|
||||
```typescript
|
||||
// 在 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 命令系统架构
|
||||
|
||||
命令系统支持三种类型的命令：
|
||||
|
||||
```typescript
|
||||
type CommandType =
|
||||
| 'prompt' // 展开为提示发送给模型
|
||||
| 'local' // 本地执行，返回文本结果
|
||||
| 'local-jsx' // 本地执行，渲染 Ink UI
|
||||
```
|
||||
|
||||
**命令注册流程**：
|
||||
1. 在 `commands.ts` 中定义命令
|
||||
2. 使用条件编译控制命令可见性
|
||||
3. 通过 `getCommands()` 获取可用命令列表
|
||||
|
||||
### 3.4 查询管道架构
|
||||
|
||||
```
|
||||
用户输入 ──► processUserInput() ──► query() ──► API 调用
|
||||
│ │
|
||||
│ ▼
|
||||
│ 工具执行循环
|
||||
│ │
|
||||
│ ┌─────────┼─────────┐
|
||||
│ ▼ ▼ ▼
|
||||
│ Tool 1 Tool 2 Tool N
|
||||
│ │ │ │
|
||||
│ └─────────┼─────────┘
|
||||
│ ▼
|
||||
│ 结果处理 ◄──────┐
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
└──────► 结果返回 ───────────┘
|
||||
```
|
||||
|
||||
## 4. 关键设计模式
|
||||
|
||||
### 4.1 工厂模式 (Factory Pattern)
|
||||
|
||||
使用 `buildTool()` 工厂函数创建工具实例：
|
||||
|
||||
```typescript
|
||||
export function buildTool<D extends AnyToolDef>(def: D): BuiltTool<D> {
|
||||
return {
|
||||
...TOOL_DEFAULTS, // 填充默认实现
|
||||
userFacingName: () => def.name,
|
||||
...def,
|
||||
} as BuiltTool<D>
|
||||
}
|
||||
```
|
||||
|
||||
### 4.2 策略模式 (Strategy Pattern)
|
||||
|
||||
权限检查使用策略模式：
|
||||
|
||||
```typescript
|
||||
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()` 允许在工具执行前修改输入：
|
||||
|
||||
```typescript
|
||||
backfillObservableInput?(input: Record<string, unknown>): void {
|
||||
// 在观察者看到输入之前修改它
|
||||
// 必须幂等
|
||||
}
|
||||
```
|
||||
|
||||
### 4.4 生成器模式 (Generator Pattern)
|
||||
|
||||
查询管道使用 AsyncGenerator 实现流式处理：
|
||||
|
||||
```typescript
|
||||
async *query(params: QueryParams): AsyncGenerator<
|
||||
| StreamEvent
|
||||
| RequestStartEvent
|
||||
| Message
|
||||
| TombstoneMessage
|
||||
| ToolUseSummaryMessage,
|
||||
Terminal
|
||||
> {
|
||||
// 流式 yield 消息
|
||||
}
|
||||
```
|
||||
|
||||
## 5. 状态管理
|
||||
|
||||
### 5.1 全局状态 (AppState)
|
||||
|
||||
```typescript
|
||||
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 支持使用沙箱执行命令：
|
||||
|
||||
```typescript
|
||||
const shouldUseSandbox = await shouldUseSandbox(command)
|
||||
if (shouldUseSandbox) {
|
||||
// 使用沙箱执行
|
||||
} else {
|
||||
// 直接执行
|
||||
}
|
||||
```
|
||||
|
||||
## 7. 扩展机制
|
||||
|
||||
### 7.1 MCP (Model Context Protocol)
|
||||
|
||||
支持通过 MCP 协议扩展工具：
|
||||
|
||||
```typescript
|
||||
interface MCPServerConnection {
|
||||
name: string
|
||||
type: 'stdio' | 'http'
|
||||
command?: string
|
||||
args?: string[]
|
||||
env?: Record<string, string>
|
||||
}
|
||||
```
|
||||
|
||||
### 7.2 插件系统
|
||||
|
||||
```typescript
|
||||
// 插件加载
|
||||
const plugins = await loadAllPluginsCacheOnly()
|
||||
|
||||
// 插件命令注册
|
||||
export function getPluginCommands(): Promise<Command[]>
|
||||
```
|
||||
|
||||
### 7.3 技能系统 (Skills)
|
||||
|
||||
技能是保存在本地目录中的可执行脚本：
|
||||
|
||||
```typescript
|
||||
// 技能目录结构
|
||||
~/.claude/skills/
|
||||
├── skill-name/
|
||||
│ ├── skill.md # 技能定义
|
||||
│ └── script.sh # 执行脚本
|
||||
```
|
||||
|
||||
## 8. 性能优化
|
||||
|
||||
### 8.1 记忆化 (Memoization)
|
||||
|
||||
使用 lodash 的 `memoize` 缓存昂贵计算：
|
||||
|
||||
```typescript
|
||||
export const getGitStatus = memoize(async (): Promise<string | null> => {
|
||||
// Git 状态获取（只计算一次）
|
||||
})
|
||||
```
|
||||
|
||||
### 8.2 条件编译 (Dead Code Elimination)
|
||||
|
||||
通过 Bun 的 `feature()` 实现条件编译：
|
||||
|
||||
```typescript
|
||||
const SleepTool = feature('PROACTIVE') || feature('KAIROS')
|
||||
? require('./tools/SleepTool/SleepTool.js').SleepTool
|
||||
: null
|
||||
```
|
||||
|
||||
### 8.3 自动压缩 (Auto-compact)
|
||||
|
||||
当上下文接近 Token 限制时自动压缩历史：
|
||||
|
||||
```typescript
|
||||
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 的架构设计体现了以下原则：
|
||||
|
||||
1. **模块化**：清晰的分层和模块划分
|
||||
2. **可扩展性**：工具系统、命令系统、插件系统三位一体
|
||||
3. **类型安全**：TypeScript + Zod 双重保障
|
||||
4. **性能优先**：记忆化、条件编译、流式处理
|
||||
5. **安全可控**：细粒度的权限控制系统
|
||||
|
||||
这套架构使得 Claude Code 能够有效地在终端环境中执行复杂的软件工程任务，同时保持高度的可配置性和安全性。
|
||||
Reference in New Issue
Block a user