第3章：架构设计

本章介绍 Claude Code 的整体架构设计，揭示其分层结构、模块依赖关系、数据流向和多 Agent 协作模式。

3.1 架构分层图

Claude Code 采用分层架构设计，清晰分离入口层、核心层和服务层的职责。

graph TD
    subgraph "入口层 Entry Layer"
        CLI[cli.tsx<br/>CLI 主入口]
        CMD[Commander.js<br/>参数解析]
        INIT[init.ts<br/>初始化入口]
    end
    
    subgraph "核心层 Core Layer"
        MAIN[main.tsx<br/>主逻辑入口]
        QE[QueryEngine<br/>查询引擎]
        TOOL[Tool System<br/>工具系统]
        STATE[AppState<br/>状态管理]
    end
    
    subgraph "服务层 Service Layer"
        API[API Service<br/>Anthropic API]
        MCP[MCP Service<br/>MCP 服务器]
        BRIDGE[Bridge<br/>远程控制]
        LSP[LSP Service<br/>语言服务]
    end
    
    subgraph "UI层 UI Layer"
        INK[Ink<br/>终端渲染]
        REPL[REPL.tsx<br/>交互界面]
        COMP[Components<br/>UI组件]
    end
    
    CLI --> MAIN
    CMD --> CLI
    MAIN --> QE
    QE --> TOOL
    TOOL --> API
    TOOL --> MCP
    MAIN --> INK
    INK --> REPL
    REPL --> COMP
    MAIN --> STATE
    MAIN --> BRIDGE
    TOOL --> LSP

层级职责表

层级	核心模块	主要职责
入口层	cli.tsx, Commander.js	命令行参数解析、启动模式选择
核心层	QueryEngine, Tool System	消息处理、工具调用、状态管理
服务层	API, MCP, Bridge	外部服务通信、协议适配
UI层	Ink, REPL, Components	终端渲染、用户交互

架构特点

Claude Code 的架构设计强调：1) 入口快速路径（fast-path）优化启动速度；2) React/Ink 终端 UI 提供交互体验；3) MCP 协议支持扩展工具生态。

3.2 模块依赖关系

核心模块依赖图

graph LR
    subgraph "入口点"
        CLI[cli.tsx]
        LOCAL[localRecoveryCli.ts]
    end
    
    subgraph "主流程"
        MAIN[main.tsx]
        SETUP[setup.ts]
        REPL_L[replLauncher.tsx]
    end
    
    subgraph "查询处理"
        QE[QueryEngine.ts]
        QUERY[query.ts]
    end
    
    subgraph "工具系统"
        TOOLS[tools.ts]
        BASH[BashTool]
        EDIT[EditTool]
        GLOB[GlobTool]
        AGENT[AgentTool]
    end
    
    subgraph "命令系统"
        CMDS[commands.ts]
        COMMIT[commit.ts]
        REVIEW[review.ts]
    end
    
    CLI --> MAIN
    CLI --> LOCAL
    MAIN --> SETUP
    MAIN --> REPL_L
    REPL_L --> QE
    QE --> QUERY
    QE --> TOOLS
    TOOLS --> BASH
    TOOLS --> EDIT
    TOOLS --> GLOB
    TOOLS --> AGENT
    MAIN --> CMDS
    CMDS --> COMMIT
    CMDS --> REVIEW

源码目录结构

src/
├── entrypoints/          # 入口点
│   ├── cli.tsx           # CLI 主入口
│   ├── init.ts           # 初始化入口
│   └── agentSdkTypes.ts  # SDK 类型定义
│
├── main.tsx              # 主逻辑（Commander.js + Ink）
├── setup.ts              # 启动初始化
├── replLauncher.tsx      # REPL 启动器
│
├── QueryEngine.ts        # 查询引擎（核心）
├── query.ts              # 查询处理
├── tools.ts              # 工具注册
├── commands.ts           # 命令注册
│
├── ink/                  # Ink 终端渲染引擎
│   ├── components/       # 核心组件
│   │   ├── App.tsx       # 根组件
│   │   └── AppContext.ts # 全局上下文
│   ├── events/           # 事件系统
│   ├── reconciler.ts     # React reconciler
│   └── termio/           # 终端 I/O
│
├── components/           # UI 组件
│   ├── PromptInput/      # 输入组件
│   ├── Messages.tsx      # 消息渲染
│   └── Spinner/          # 加载指示器
│
├── tools/                # Agent 工具
│   ├── BashTool/         # Shell 命令
│   ├── FileEditTool/     # 文件编辑
│   ├── FileReadTool/     # 文件读取
│   ├── GlobTool/         # 文件匹配
│   ├── GrepTool/         # 内容搜索
│   ├── AgentTool/        # 子 Agent
│   ├── WebFetchTool/     # 网页获取
│   └── ...               # 其他工具
│
├── commands/             # 斜杠命令
│   ├── commit.ts         # /commit
│   ├── review.ts         # /review
│   ├── init.ts           # /init
│   └── ...               # 其他命令
│
├── services/             # 服务层
│   ├── api/              # API 服务
│   ├── mcp/              # MCP 服务
│   ├── lsp/              # LSP 服务
│   └── analytics/        # 分析服务
│
├── state/                # 状态管理
│   ├── AppStateStore.ts  # 应用状态
│   └── store.ts          # 状态存储
│
├── utils/                # 工具函数
│   ├── config.ts         # 配置管理
│   ├── auth.ts           # 认证
│   ├── permissions/      # 权限系统
│   └── hooks/            # Hook 系统
│
├── skills/               # Skill 系统
│   ├── bundled/          # 内置 Skills
│   └── ...               # 其他 Skills
│
├── bridge/               # 远程控制
│   ├── bridgeMain.ts     # Bridge 主逻辑
│   ├── bridgeApi.ts      # Bridge API
│   └── ...               # 其他 Bridge 模块
│
├── bootstrap/            # 启动状态
│   └── state.ts          # 全局状态
│
├── buddy/                # Companion 伴侣
│   ├── companion.ts      # 伴侣逻辑
│   └── sprites.ts        # 动画精灵
│
├── context.ts            # 上下文管理
├── Tool.ts               # 工具基类
├── Task.ts               # 任务定义
└── tasks.ts              # 任务管理

关键模块依赖关系

graph TD
    subgraph "入口依赖链"
        CLI --> MAIN
        MAIN --> SETUP
        MAIN --> CMDS_GET[getCommands]
        MAIN --> REPL_L
    end
    
    subgraph "QueryEngine 依赖"
        QE --> QUERY
        QE --> TOOLS_GET[getTools]
        QE --> STATE_GET[getAppState]
        QE --> PERMISSIONS[permissionCheck]
    end
    
    subgraph "工具依赖链"
        TOOLS --> TOOL_IMPL[Tool Implementations]
        TOOL_IMPL --> SERVICES[Services]
        SERVICES --> API
        SERVICES --> MCP
        SERVICES --> LSP
    end
    
    subgraph "UI 依赖链"
        INK --> TERMINAL[Terminal I/O]
        REPL --> COMP_IMPL[Component Implementations]
        REPL --> STATE
    end

模块组织原则

模块按职责划分：入口模块负责启动；核心模块负责业务逻辑；服务模块负责外部通信；UI 模块负责渲染。依赖关系单向流动，避免循环依赖。

3.3 数据流向图

用户输入到响应输出的完整数据流

sequenceDiagram
    participant U as 用户
    participant REPL as REPL.tsx
    participant QE as QueryEngine
    participant TOOL as Tool System
    participant API as API Service
    participant MCP as MCP Service
    participant OUT as 终端输出
    
    U->>REPL: 输入 Prompt
    REPL->>QE: 提交用户消息
    QE->>QE: processUserInput()
    QE->>API: 发送 API 请求
    API->>QE: 返回 Assistant 响应
    
    loop 工具调用循环
        QE->>TOOL: 解析 tool_use
        TOOL->>TOOL: 执行工具
        TOOL->>MCP: MCP 工具调用（可选）
        MCP->>TOOL: 返回 MCP 结果
        TOOL->>QE: 返回工具结果
        QE->>API: 继续对话
        API->>QE: 下一步响应
    end
    
    QE->>REPL: 更新消息列表
    REPL->>OUT: 渲染输出
    OUT->>U: 显示结果

数据流关键节点

节点	输入	输出	处理逻辑
REPL.tsx	用户键盘输入	UserMessage	输入处理、历史记录
QueryEngine	Message[]	AssistantMessage	消息组装、API 调用
Tool System	tool_use block	tool_result	工具匹配、权限检查、执行
API Service	messages + tools	stream response	Anthropic API 通信
MCP Service	MCP request	MCP response	MCP 协议适配

消息处理流程

graph TD
    subgraph "输入处理"
        A[用户输入] --> B[PromptInput]
        B --> C[processUserInput]
        C --> D[createUserMessage]
    end
    
    subgraph "查询构建"
        D --> E[fetchSystemPromptParts]
        E --> F[buildQueryContext]
        F --> G[组装 Messages]
    end
    
    subgraph "API 调用"
        G --> H[prepareApiRequest]
        H --> I[streamResponse]
        I --> J[accumulateUsage]
    end
    
    subgraph "响应处理"
        J --> K[parseContentBlocks]
        K --> L{有 tool_use?}
        L --> |"是"| M[执行工具]
        L --> |"否"| N[完成响应]
        M --> O[返回 tool_result]
        O --> H
    end
    
    subgraph "输出渲染"
        N --> P[updateMessages]
        P --> Q[renderMessages]
        Q --> R[终端显示]
    end

状态同步机制

graph LR
    subgraph "状态流向"
        INPUT[用户输入] --> STATE[AppState]
        STATE --> QE[QueryEngine]
        QE --> STATE_UPDATE[状态更新]
        STATE_UPDATE --> UI[UI 渲染]
        UI --> RENDER[渲染输出]
    end
    
    subgraph "持久化"
        STATE --> STORAGE[SessionStorage]
        STORAGE --> FILE[JSONL 文件]
    end

状态一致性

状态变更需要立即持久化到 SessionStorage（JSONL 文件），确保崩溃恢复和 Context 压缩后可恢复。

3.4 多 Agent 架构图

Claude Code 支持多 Agent 协作模式，通过 AgentTool 实现子 Agent 派发和结果整合。

Agent 协作模式

graph TD
    subgraph "主 Agent"
        MAIN_AGENT[Main Agent<br/>QueryEngine]
        ORCHESTRATOR[Orchestrator<br/>任务派发]
    end
    
    subgraph "子 Agent 类型"
        EXPLORE[Explore Agent<br/>代码探索]
        PLAN[Plan Agent<br/>任务规划]
        CODE[Code Agent<br/>代码实现]
        RESEARCH[Research Agent<br/>信息检索]
        CUSTOM[Custom Agent<br/>自定义]
    end
    
    subgraph "协作机制"
        DISPATCH[Task Dispatch<br/>任务派发]
        ISOLATE[Worktree Isolation<br/>工作树隔离]
        AGGREGATE[Result Aggregation<br/>结果聚合]
        SYNC[State Sync<br/>状态同步]
    end
    
    MAIN_AGENT --> ORCHESTRATOR
    ORCHESTRATOR --> DISPATCH
    DISPATCH --> EXPLORE
    DISPATCH --> PLAN
    DISPATCH --> CODE
    DISPATCH --> RESEARCH
    DISPATCH --> CUSTOM
    
    EXPLORE --> ISOLATE
    PLAN --> ISOLATE
    CODE --> ISOLATE
    
    ISOLATE --> AGGREGATE
    AGGREGATE --> SYNC
    SYNC --> MAIN_AGENT

Agent 定义结构

interface AgentDefinition {
  name: string;              // Agent 名称
  color: AgentColorName;     // 颜色标识（用于 UI）
  description: string;       // 功能描述
  model?: string;            // 指定模型
  tools?: string[];          // 可用工具列表
  capabilities?: string[];   // 能力声明
  systemPrompt?: string;     // 自定义系统提示
  isolated?: boolean;        // 是否隔离执行
}

Agent 工具调用流程

sequenceDiagram
    participant MAIN as Main Agent
    participant AT as AgentTool
    participant WT as Worktree
    participant SUB as Sub Agent
    participant API as API Service
    
    MAIN->>AT: 检测 Agent 调用请求
    AT->>AT: 解析 AgentDefinition
    AT->>WT: 创建隔离 Worktree（可选）
    WT->>SUB: 启动 Sub Agent
    SUB->>API: 发送请求
    API->>SUB: 返回响应
    loop 工具执行
        SUB->>SUB: 执行工具
        SUB->>API: 继续对话
    end
    SUB->>AT: 返回最终结果
    AT->>WT: 清理 Worktree（可选）
    AT->>MAIN: 返回聚合结果

Agent 颜色系统

Agent 使用颜色标识区分，便于 UI 渲染：

颜色	名称	用途
`blue`	探索 Agent	代码探索、文件搜索
`yellow`	规划 Agent	任务分解、方案设计
`green`	实现 Agent	代码编写、编辑
`purple`	研究 Agent	信息检索、分析
`orange`	自定义 Agent	用户定义的 Agent

Worktree 隔离

Agent 可以在独立 Git Worktree 中执行，隔离文件修改，避免与主工作区冲突。通过 --worktree 参数或 AgentDefinition.isolated 启用。

并行 Agent 执行

graph TD
    subgraph "并行派发"
        A[主 Agent] --> B[分析任务]
        B --> C{可并行?}
        C --> |"是"| D[派发多个 Agent]
        C --> |"否"| E[串行执行]
        
        D --> F[Agent 1]
        D --> G[Agent 2]
        D --> H[Agent 3]
        
        F --> I[结果聚合]
        G --> I
        H --> I
        
        I --> J[整合响应]
        E --> J
        J --> K[返回主对话]
    end

Teammate 模式（多人协作）

graph TD
    subgraph "Teammate 架构"
        SWARM[Swarm Orchestrator]
        TM1[Teammate 1]
        TM2[Teammate 2]
        TM3[Teammate 3]
        
        SHARED[Shared Context<br/>Team Memory]
        MSG[Message Bus<br/>UDS Messaging]
    end
    
    SWARM --> TM1
    SWARM --> TM2
    SWARM --> TM3
    
    TM1 --> SHARED
    TM2 --> SHARED
    TM3 --> SHARED
    
    TM1 --> MSG
    TM2 --> MSG
    TM3 --> MSG
    
    MSG --> SWARM

Agent Swarms

Agent Swarms 是高级协作模式，支持多个 Agent 同时工作，通过 Team Memory 同步状态，通过 UDS Messaging 传递消息。需要 isAgentSwarmsEnabled() 开启。

3.5 服务层架构

API 服务架构

graph TD
    subgraph "API 请求流程"
        REQ[API Request] --> PREPARE[prepareApiRequest]
        PREPARE --> AUTH[Authentication]
        AUTH --> HEADERS[Request Headers]
        HEADERS --> STREAM[Stream Response]
        
        STREAM --> PARSE[Parse Events]
        PARSE --> ACCUMULATE[accumulateUsage]
        ACCUMULATE --> HANDLE[Handle Response]
    end
    
    subgraph "认证方式"
        KEY[API Key<br/>x-api-key header]
        TOKEN[Auth Token<br/>Bearer header]
        OAUTH[OAuth Token<br/>Claude AI]
    end
    
    AUTH --> KEY
    AUTH --> TOKEN
    AUTH --> OAUTH

MCP 服务架构

graph TD
    subgraph "MCP 协议"
        CLIENT[MCP Client]
        TRANSPORT[Transport Layer]
        
        STDIO[Stdio Transport]
        SSE[SSE Transport]
        HTTP[HTTP Transport]
        
        SERVER[MCP Server]
        RESOURCES[Resources]
        TOOLS[Tools]
        PROMPTS[Prompts]
    end
    
    CLIENT --> TRANSPORT
    TRANSPORT --> STDIO
    TRANSPORT --> SSE
    TRANSPORT --> HTTP
    
    STDIO --> SERVER
    SSE --> SERVER
    HTTP --> SERVER
    
    SERVER --> RESOURCES
    SERVER --> TOOLS
    SERVER --> PROMPTS

MCP 工具集成

// MCP 工具转换为 Claude Code 工具
interface McpTool {
  name: string;           // 工具名称（带 server 前缀）
  description: string;    // 工具描述
  inputSchema: JSONSchema; // 输入 schema
  serverName: string;     // 来源服务器
}

// 工具调用流程
McpClient.callTool(toolName, args) -> McpServer -> ToolResult

MCP 协议

Model Context Protocol (MCP) 是 Anthropic 定义的模型上下文协议，支持工具、资源、提示的标准化接入。Claude Code 支持多种传输方式（Stdio、SSE、HTTP）。

3.6 设计原则

快速启动原则

Fast-Path 设计

入口 cli.tsx 实现快速路径优化：

--version 零模块加载直接输出
--dump-system-prompt 动态加载最小模块
特殊子命令（daemon、bridge、ps）独立处理路径
正常启动延迟加载 main.tsx

状态持久化原则

所有状态变更立即持久化：

持久化原则

消息历史保存到 JSONL 文件
工具调用结果记录到日志
配置变更写入 settings.json
状态崩溃可恢复

单一职责原则

模块	单一职责
cli.tsx	快速路径判断、参数解析
main.tsx	Commander.js 配置、启动选择
setup.ts	环境初始化、预加载
QueryEngine	消息处理、API 调用循环
Tool System	工具注册、匹配、执行
Ink/App	终端渲染、事件处理
REPL	用户交互、输入处理

下一章将深入探讨 入口与启动流程 的实现细节。

Keyboard shortcuts

Claude Code 源码解析