整体架构：从 CLI 入口到 QueryEngine

Claude Code 采用分层架构设计，通过清晰的职责分离实现快速启动、模块化和可测试性。本文档将深入剖析从命令行入口到核心查询引擎的完整链路，揭示各层次间的协作机制。

架构全景图

Claude Code 的架构可分为七个核心层次，每层承担特定职责并通过明确定义的接口协作：

graph TD
    A[CLI 入口层<br/>entrypoints/cli.tsx] -->|快速路径分发| B[主入口层<br/>main.tsx]
    B -->|配置加载与命令解析| C[初始化层<br/>init.ts + setup.ts]
    C -->|系统初始化| D[应用层<br/>replLauncher.tsx]
    D -->|UI渲染| E[REPL界面<br/>screens/REPL.tsx]
    E -->|用户交互| F[查询引擎<br/>QueryEngine.ts]
    F -->|对话循环| G[底层查询<br/>query.ts]
    
    H[状态管理层<br/>bootstrap/state.ts<br/>state/store.ts] -.->|全局状态| B
    H -.->|会话状态| E
    H -.->|应用状态| F
    
    I[支撑系统] -->|任务调度| J[Task系统<br/>Task.ts]
    I -->|工具执行| K[Tool系统<br/>Tool.ts]
    I -->|命令注册| L[Command系统<br/>commands.ts]
    
    F -->|调用| I
    
    style A fill:#e1f5ff
    style F fill:#ffe1e1
    style H fill:#fff4e1
    style I fill:#f0f0f0

Sources: entrypoints/cli.tsx, main.tsx, QueryEngine.ts

分层架构详解

1. CLI 入口层 - 快速路径分发器

核心职责：最小化模块加载，实现零依赖快速路径

entrypoints/cli.tsx 是整个系统的最外层守门人，其设计哲学是”能不加载就不加载”。通过动态 import() 和条件分支，它将不同场景的启动路径完全隔离：

这种设计确保了版本查询等常见操作在 < 50ms 内完成，无需等待 Bun 加载和初始化数百个模块。

// cli.tsx 的快速路径示例
if (args.length === 1 && args[0] === '--version') {
  console.log(`${MACRO.VERSION} (Claude Code)`); // MACRO 在构建时内联
  return; // 立即返回，零模块加载
}

Sources: entrypoints/cli.tsx

2. 主入口层 - 配置协调中心

核心职责：配置初始化、命令行解析、模式选择

main.tsx（4683行）是系统的中央协调器，负责将原始命令行参数转换为运行时配置并选择适当的执行模式。其核心工作流包括：

1. 性能优化前置：并行启动 MDM 配置读取和 Keychain 预取
2. 配置系统启用：调用 enableConfigs() 激活配置层
3. 命令行解析：使用 Commander.js 解析复杂参数
4. 模式选择：根据参数决定进入交互模式、无头模式或其他特殊模式

// main.tsx 的关键初始化序列
startMdmRawRead();          // 并行启动：MDM配置
startKeychainPrefetch();    // 并行启动：Keychain凭证
await init();               // 初始化核心系统
enableConfigs();            // 激活配置系统

主入口层通过命令模式支持两种主要运行模式：

Sources: main.tsx, replLauncher.tsx

3. 初始化层 - 系统就绪保障

核心职责：依赖验证、安全配置、遥测初始化

初始化层由 entrypoints/init.ts 和 setup.ts 组成，确保系统在启动前满足所有前置条件：

init.ts 核心流程：

• 配置验证：检查 settings.json 完整性
• 环境变量应用：先应用安全变量（applySafeConfigEnvironmentVariables），信任确认后应用完整变量
• 优雅退出设置：注册 SIGINT/SIGTERM 处理器
• 遥测初始化：延迟加载 OpenTelemetry 模块（~400KB）直到实际需要

setup.ts 会话准备：

• Node.js版本检查：强制要求 ≥ v18
• 会话ID管理：支持自定义会话ID或自动生成
• Git仓库检测：确定项目根目录
• Worktree配置：处理 Git worktree 模式
• UDS消息服务：启动 Unix Domain Socket 服务器（跨进程通信）

// setup.ts 的关键检查
const nodeVersion = process.version.match(/^v(\d+)\./)?.[1];
if (!nodeVersion || parseInt(nodeVersion) < 18) {
  console.error('Error: Claude Code requires Node.js version 18 or higher.');
  process.exit(1);
}

Sources: entrypoints/init.ts, setup.ts

4. 应用层 - React 终端渲染

核心职责：Ink框架集成、组件树挂载、事件循环管理

应用层通过 replLauncher.tsx 将 React 组件树挂载到终端环境，其核心是 Ink 框架（React for CLI）：

graph LR
    A[launchRepl] --> B[动态导入App/REPL]
    B --> C[renderAndRun]
    C --> D[Ink Root]
    D --> E[React并发渲染]
    E --> F[终端输出]

关键机制：

• 动态导入：延迟加载 React/Ink 模块（~2MB）直到交互模式
• 并发模式：利用 React 18 并发特性优化渲染性能
• Fiber架构：Ink 的自定义 reconciler 将 React 组件映射到终端输出

Sources: replLauncher.tsx

5. REPL 界面 - 交互式对话管理

核心职责：用户输入处理、消息流展示、状态同步

screens/REPL.tsx（5006行）是最复杂的组件，整合了所有交互功能：

REPL 组件通过 AppState 管理全局状态，使用 useLogMessages hook 监听消息队列变化并触发重新渲染。

Sources: screens/REPL.tsx

6. 查询引擎 - 对话循环核心

核心职责：消息流转、工具调用、API交互、上下文管理

QueryEngine.ts（1295行）是整个系统的心脏，封装了完整的对话生命周期：

sequenceDiagram
    participant User
    participant REPL
    participant QueryEngine
    participant Query
    participant API
    participant Tools
    
    User->>REPL: 输入提示
    REPL->>QueryEngine: runQuery(userMessage)
    QueryEngine->>QueryEngine: 构建上下文<br/>(系统提示+记忆+历史)
    QueryEngine->>Query: query(messages, tools)
    loop 流式响应
        API-->>Query: content_block_delta
        Query-->>QueryEngine: StreamEvent
        QueryEngine->>REPL: 状态更新
    end
    alt 工具调用
        Query-->>QueryEngine: tool_use块
        QueryEngine->>Tools: 执行工具
        Tools-->>QueryEngine: 结果
        QueryEngine->>Query: 继续对话
    end
    QueryEngine-->>REPL: 完成

QueryEngine 的核心职责：

1. 消息归一化：将用户输入、工具结果、系统提示转换为 API 兼容格式
2. 上下文窗口管理：token 预算计算、自动压缩、优先级排序
3. 流式处理：实时处理 API 流并更新 UI
4. 工具编排：并行/串行执行工具，处理依赖关系
5. 错误恢复：重试逻辑、降级策略、会话持久化

Sources: QueryEngine.ts

7. 底层查询 - API 通信协议

核心职责：Anthropic API 封装、流式解析、错误分类

query.ts（1729行）是 QueryEngine 的底层实现，直接与 Anthropic API 交互：

关键特性：

• 流式解析：处理 SSE (Server-Sent Events) 流
• 重试逻辑：指数退避、错误分类（临时/永久）
• Token追踪：实时统计输入/输出 token
• 压缩集成：触发自动压缩的阈值检测

// query.ts 的核心流处理
export async function* query(
  messages: Message[],
  tools: Tools,
  context: QueryContext
): AsyncGenerator<StreamEvent> {
  // 流式请求 Anthropic API
  const stream = await anthropic.messages.stream({...});
  
  for await (const event of stream) {
    yield normalizeStreamEvent(event); // 归一化事件
  }
}

Sources: query.ts

状态管理架构

Claude Code 采用双层状态管理策略，分离全局单例状态和响应式应用状态：

Bootstrap State（全局单例）

bootstrap/state.ts 管理进程级别的全局状态，通过 Signal 模式实现响应式：

// bootstrap/state.ts 的 Signal 实现
const stateSignal = createSignal<SessionId>(generateSessionId());

export function getSessionId(): SessionId {
  return stateSignal.get();
}

export function switchSession(newId: SessionId): void {
  stateSignal.set(newId);
}

Store（响应式应用状态）

state/store.ts 提供类似 Redux 的不可变状态容器，用于 React 组件：

export type Store<T> = {
  getState: () => T;
  setState: (updater: (prev: T) => T) => void;
  subscribe: (listener: Listener) => () => void;
};

AppState 通过 onChangeAppState 回调实现细粒度更新通知，避免全量重渲染。

Sources: bootstrap/state.ts, state/store.ts

支撑系统概览

Task 系统 - 异步任务抽象

Task.ts 定义了统一的任务接口，支持多种执行后端：

所有任务共享 kill() 接口用于优雅终止。

Sources: Task.ts

Tool 系统 - 工具调用协议

Tool.ts 定义了统一的工具接口，支持输入验证、权限检查、进度报告：

export type Tool = {
  name: string;
  inputSchema: ToolInputJSONSchema;
  validate: (input: unknown) => ValidationResult;
  canUse: (context: ToolUseContext) => Promise<PermissionResult>;
  execute: (input: T, context: ToolUseContext) => AsyncGenerator<ToolProgress>;
};

工具系统通过 权限模式（PermissionMode）控制危险操作。

Sources: Tool.ts

Command 系统 - 斜杠命令注册

commands.ts 汇总所有内置命令（commit、review、compact 等），提供统一的注册和发现机制：

export function getCommands(): Command[] {
  return [
    commit,      // Git提交
    review,      // 代码审查
    compact,     // 上下文压缩
    doctor,      // 环境诊断
    // ... 60+ 命令
  ];
}

命令通过 动态导入 延迟加载，减少启动时间。

Sources: commands.ts

关键设计模式

1. 快速路径优先

CLI 入口通过条件分支树实现零依赖快速响应：

// 优先级：零加载 > 单模块 > 完整初始化
if (args[0] === '--version') return;         // 零加载
if (args[0] === 'remote-control') {...}      // 单模块
await import('./main.js');                   // 完整初始化

2. 延迟初始化

重模块通过动态 import() 延迟到实际使用时加载：

• OpenTelemetry (~400KB)：首次遥测事件时
• React/Ink (~2MB)：交互模式启动时
• LSP服务 (~1MB)：首次代码补全请求时

3. 并行预取

启动时并行执行独立的 I/O 操作：

• MDM 配置读取（子进程）
• Keychain 凭证读取（两次独立查询）
• MCP 服务器发现（文件系统扫描）

4. 分层错误处理

错误根据严重性在不同层次处理：

• CLI层：立即退出（版本不兼容）
• Init层：显示对话框（配置错误）
• QueryEngine层：重试/降级（API错误）
• Tool层：返回错误消息（工具执行失败）

Sources: entrypoints/cli.tsx

架构演进启示

Claude Code 的架构设计体现了以下工程原则：

1. 性能优先：通过快速路径和延迟加载优化启动时间
2. 模块化：清晰的层次边界便于独立测试和维护
3. 可扩展性：Task/Tool/Command 系统支持插件化扩展
4. 容错性：多层错误处理和优雅降级
5. 可观测性：内置遥测和性能追踪

这种架构使得 Claude Code 能够在保持功能丰富性的同时，维持优秀的用户体验（< 200ms 冷启动）。

下一步探索

根据本架构概览，建议按以下顺序深入各子系统：

1. 启动流程：main.tsx 与 init.ts 初始化链 - 深入理解配置加载和系统就绪检查
2. 状态管理：AppState 与 React Context 体系 - 掌握响应式状态更新机制
3. 查询引擎：QueryEngine 对话生命周期管理 - 剖析对话循环和上下文管理
4. 工具架构：Tool 接口与权限模型 - 理解工具执行和安全机制
5. Ink 框架：React 终端渲染原理 - 探索终端UI的实现细节

通过这种渐进式学习路径，您将全面掌握 Claude Code 的设计哲学和实现细节。