architecture

Claude Code 采用分层架构，将复杂的 AI 编程助手功能分解为清晰的模块。

整体架构

┌─────────────────────────────────────────────────────────┐
│                    CLI Entrypoint                       │
│                   (src/main.tsx)                        │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────┐
│                  React TUI Layer                        │
│              (Ink Components + State)                   │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────┐
│                  Query Engine                           │
│         (异步生成器 + 流式处理)                          │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────┐
│                  Tool System                            │
│         (30+ 工具 + 插件化架构)                          │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────┐
│                  Services Layer                         │
│    (Compact, Permissions, MCP, Coordinator...)          │
└─────────────────────────────────────────────────────────┘

核心模块

1. Entrypoints (入口层)

位置: src/entrypoints/

负责 CLI 启动和命令路由：

• cli.tsx - 主入口，处理命令行参数

• commands.ts - 命令注册和分发

• 启动优化：多级 fast-path，首次交互 < 1 秒

2. Query Engine (查询引擎)

位置: src/query.ts, src/QueryEngine.ts

核心执行引擎，基于异步生成器：

async function* query(
  messages: Message[],
  tools: Tool[],
  options: QueryOptions
): AsyncGenerator<QueryEvent>

特点：

• 流式响应，实时反馈

• 支持工具调用和多轮对话

• 内置错误处理和重试机制

3. Tool System (工具系统)

位置: src/tools/, src/Tool.ts

插件化的工具架构：

interface Tool {
  name: string;
  description: string;
  inputSchema: ZodSchema;
  execute(input: unknown, context: ToolContext): Promise<ToolResult>;
}

内置工具分类：

• 文件操作: FileEdit, FileRead, FileSearch

• Shell: Bash, BashBackground

• 代码理解: ReadCode, GetDiagnostics

• Agent: SubAgent, ContextGatherer

• Web: WebSearch, WebFetch

• 其他: StrReplace, SmartRelocate, SemanticRename

4. State Management (状态管理)

位置: src/state/

极简状态管理方案：

// 30 行的极简 Store
class AppStateStore {
  private state: DeepImmutable<AppState>;
  private listeners: Set<Listener>;
  
  setState(updater: (state: AppState) => AppState): void;
  subscribe(listener: Listener): () => void;
}

特点：

• 不可变状态树

• 订阅/通知模式

• 无外部依赖

5. Services Layer (服务层)

位置: src/services/

提供各种核心服务：

• compact/ - 上下文压缩服务

• tools/ - 工具执行服务

• permissions/ - 权限检查服务

• mcp/ - MCP 客户端实现

• coordinator/ - 多 Agent 协调

• skills/ - Skills 加载和管理

6. Bridge System (桥接系统)

位置: src/bridge/

支持远程控制和 IDE 集成：

• WebSocket/SSE 双向通信

• JWT 认证和设备信任

• 消息序列化和反序列化

• 状态同步

数据流

用户输入 → AI 响应

用户输入
  ↓
CLI 解析
  ↓
Query Engine 启动
  ↓
构建 System Prompt + 用户消息
  ↓
调用 Anthropic API
  ↓
流式接收响应
  ↓
解析工具调用
  ↓
执行工具 (并发)
  ↓
收集结果
  ↓
继续对话 (如需要)
  ↓
显示最终响应

工具执行流程

工具调用请求
  ↓
权限检查 (preToolUse hooks)
  ↓
工具参数验证 (Zod)
  ↓
工具执行 (StreamingToolExecutor)
  ↓
结果处理 (postToolUse hooks)
  ↓
上下文压缩 (如需要)
  ↓
返回结果

模块依赖关系

entrypoints
  ├─→ commands (命令定义)
  ├─→ query (查询引擎)
  └─→ state (状态管理)

query
  ├─→ tools (工具系统)
  ├─→ services/compact (上下文压缩)
  └─→ services/tools (工具执行)

tools
  ├─→ services/permissions (权限检查)
  ├─→ services/mcp (MCP 工具)
  └─→ services/coordinator (Agent 协调)

services
  ├─→ state (状态访问)
  └─→ utils (工具函数)

关键设计决策

为什么选择异步生成器？

传统的请求-响应模式无法提供流式体验。异步生成器允许：

• 逐 token 显示 AI 响应

• 实时显示工具执行进度

• 用户可以随时中断

为什么使用 React + Ink？

终端 UI 开发通常很复杂，React + Ink 提供：

• 声明式 UI 开发

• 组件化和状态管理

• 丰富的生态系统

为什么需要上下文压缩？

Claude API 的 token 限制（200K）在复杂项目中很容易达到。五层压缩策略确保：

• 保留最相关的上下文

• 自动清理冗余信息

• 动态调整压缩强度

下一步

• 了解 设计哲学

• 深入 Query Loop 实现

• 探索 工具系统 设计