Architecture Map

Claude Code 遵循分层架构，每一层都有明确的职责。理解这张架构图，是高效导航 512K+ 行代码库的关键。

高层架构

graph TB
    subgraph "CLI Layer"
        CLI["cli.tsx — Bootstrap Entrypoint"]
        MAIN["main.tsx — Commander.js CLI"]
    end

    subgraph "Command Layer"
        CMDS["commands.ts — Command Registry"]
        SLASH["60+ Slash Commands"]
        SKILLS["Skills & Plugins"]
    end

    subgraph "Agentic Loop"
        QE["QueryEngine — Session Manager"]
        QUERY["query.ts — Turn Orchestrator"]
        CLAUDE["claude.ts — API Streaming"]
    end

    subgraph "Tool System"
        TOOLS["tools.ts — Tool Pool Assembly"]
        TOOL_DEF["Tool.ts — Tool Interface"]
        STE["StreamingToolExecutor"]
        BUILTIN["30+ Built-in Tools"]
        MCP["MCP Tools"]
    end

    subgraph "Infrastructure"
        RETRY["withRetry.ts — Retry Logic"]
        SETTINGS["settings.ts — Configuration"]
        PERMS["permissions.ts — Security"]
        COMPACT["compact.ts — Context Management"]
    end

    CLI --> MAIN
    MAIN --> CMDS
    CMDS --> SLASH
    CMDS --> SKILLS
    MAIN --> QE
    QE --> QUERY
    QUERY --> CLAUDE
    CLAUDE --> RETRY
    QUERY --> STE
    STE --> BUILTIN
    STE --> MCP
    TOOLS --> BUILTIN
    TOOLS --> MCP
    QUERY --> COMPACT
    STE --> PERMS
    MAIN --> SETTINGS

逐层解析

第 1 层：CLI 入口（src/entrypoints/）

最外层负责进程引导和快速路由。

关键文件：

• src/entrypoints/cli.tsx — Bootstrap 入口，快速路由
• src/entrypoints/init.ts — 配置、遥测和代理初始化
• src/entrypoints/mcp.ts — MCP 服务器模式入口

CLI 层实现了快速路径模式 — 在加载任何重型模块之前，先处理 --version 等特殊标志：

src/entrypoints/cli.tsx

async function main(): Promise<void> {
  const args = process.argv.slice(2)

  // Fast-path for --version: zero module loading needed
  if (args.length === 1 && (args[0] === '--version' || args[0] === '-v')) {
    console.log(`${MACRO.VERSION} (Claude Code)`)
    return
  }

  // For all other paths, load the startup profiler
  const { profileCheckpoint } = await import('../utils/startupProfiler.js')
  profileCheckpoint('cli_entry')

  // Route to specialized entrypoints...
}

init() 函数（已 memoize，只运行一次）负责：

1. 配置校验与启用
2. 环境变量应用（信任前的安全子集，信任后的完整集合）
3. 优雅关闭注册
4. OAuth 账户信息填充
5. mTLS 和代理配置
6. 遥测初始化

第 2 层：CLI 框架（src/main.tsx）

主模块是代码库中最大的文件（约 785KB）。它将 commander.js 参数解析、配置加载和 REPL 启动器整合在一起。

核心职责：

• commander.js 命令注册，配合类型安全选项
• API 密钥校验和认证流程
• MCP 服务器初始化
• Tool pool 组装
• REPL/打印模式启动

// src/main.tsx — Side effects run at import time
import { profileCheckpoint } from './utils/startupProfiler.js'
profileCheckpoint('main_tsx_entry')

import { startMdmRawRead } from './utils/settings/mdm/rawRead.js'
startMdmRawRead()  // Fire MDM subprocess in parallel with imports

import { startKeychainPrefetch } from './utils/secureStorage/keychainPrefetch.js'
startKeychainPrefetch()  // Fire keychain reads in parallel

第 3 层：命令系统（src/commands.ts）

命令注册表通过复杂的加载系统管理 60+ 个 slash command：

src/commands.ts

export async function getCommands(cwd: string): Promise<Command[]> {
  const allCommands = await loadAllCommands(cwd)
  const dynamicSkills = getDynamicSkills()

  const baseCommands = allCommands.filter(
    _ => meetsAvailabilityRequirement(_) && isCommandEnabled(_),
  )
  // ... dedupe dynamic skills
}

命令来自多个来源：

1. 内置命令 — 硬编码在 COMMANDS() 中（已 memoize）
2. 打包 skill — 随二进制文件发布
3. Skill 目录命令 — 用户在 .claude/skills/ 中自定义
4. Plugin 命令 — 来自已安装的 plugin
5. 工作流命令 — 来自工作流脚本
6. MCP 命令 — 来自已连接的 MCP 服务器

第 4 层：Query Engine（src/QueryEngine.ts）

QueryEngine 类负责对话生命周期：

sequenceDiagram
    participant User
    participant QE as QueryEngine
    participant PUI as processUserInput
    participant Q as query()
    participant C as claude.ts

    User->>QE: submitMessage(prompt)
    QE->>PUI: Process slash commands, attachments
    PUI-->>QE: messages, shouldQuery, allowedTools
    QE->>Q: query({ messages, systemPrompt, ... })
    Q->>C: createStreamedResponse()
    C-->>Q: Stream events (text, tool_use, ...)
    Q->>Q: Execute tools via StreamingToolExecutor
    Q-->>QE: Yield messages (assistant, user, system)
    QE-->>User: SDKMessage stream

关键设计：submitMessage() 返回 AsyncGenerator<SDKMessage>，让调用方能够增量消费消息：

src/QueryEngine.ts

export class QueryEngine {
  async *submitMessage(
    prompt: string | ContentBlockParam[],
    options?: { uuid?: string; isMeta?: boolean },
  ): AsyncGenerator<SDKMessage, void, unknown> {
    // 1. Process user input (slash commands, attachments)
    // 2. Build system prompt
    // 3. Enter query loop
    for await (const message of query({ messages, systemPrompt, ... })) {
      // 4. Process each message (record, track usage, yield)
    }
    // 5. Yield final result
  }
}

第 5 层：Agentic Loop（src/query.ts）

query() 函数实现了核心 agentic loop — 循环包括：

1. 向 API 发送消息
2. 接收 streaming 响应
3. 执行 tool 调用
4. 将结果反馈回去

// src/query.ts — Imports reveal the orchestration scope
import { StreamingToolExecutor } from './services/tools/StreamingToolExecutor.js'
import { runTools } from './services/tools/toolOrchestration.js'
import { isAutoCompactEnabled } from './services/compact/autoCompact.js'
import { FallbackTriggeredError } from './services/api/withRetry.js'

该循环负责处理：

• 自动 compaction：接近 context 上限时自动压缩
• 响应式 compaction：遇到 prompt 过长错误时，使用压缩后的 context 重试
• 模型降级：在连续 529 错误时从 Opus 降级到 Sonnet
• Tool 执行：通过 StreamingToolExecutor 并行执行并发安全的 tool

第 6 层：API Streaming（src/services/api/claude.ts）

最底层负责原始 API 通信：

// src/services/api/claude.ts — Types reveal the protocol
import type {
  BetaRawMessageStreamEvent,
  BetaMessageStreamParams,
} from '@anthropic-ai/sdk/resources/beta/messages/messages.mjs'
import type { Stream } from '@anthropic-ai/sdk/streaming.mjs'

该层负责：

• 带 cache 断点的 system prompt 构建
• 消息规范化为 API 格式
• Streaming 事件处理（message_start、content_block_start、content_block_delta 等）
• Beta 功能头部（thinking、effort、fast mode、tool search）
• 多提供商支持（Anthropic 直连、Bedrock、Vertex）

第 7 层：Tool 系统（src/Tool.ts、src/tools.ts）

Tool 系统是 Claude 与外界交互的主要机制：

// src/Tool.ts — Core tool interface (simplified)
export type Tool<Input, Output, P> = {
  name: string
  inputSchema: Input           // Zod schema
  call(args, context, canUseTool, parentMessage, onProgress?): Promise<ToolResult<Output>>
  checkPermissions(input, context): Promise<PermissionResult>
  isReadOnly(input): boolean
  isDestructive?(input): boolean
  isConcurrencySafe(input): boolean
  prompt(options): Promise<string>
  // ... rendering, validation, progress tracking
}

Tool 通过 getTools() 配合权限感知过滤来组装：

src/tools.ts

export const getTools = (permissionContext: ToolPermissionContext): Tools => {
  if (isEnvTruthy(process.env.CLAUDE_CODE_SIMPLE)) {
    return filterToolsByDenyRules([BashTool, FileReadTool, FileEditTool], permissionContext)
  }
  // Full tool pool with deny-rule filtering and REPL mode handling
}

模块依赖流

graph LR
    CLI["cli.tsx"] --> INIT["init.ts"]
    CLI --> MAIN["main.tsx"]
    MAIN --> SETUP["setup.ts"]
    MAIN --> QE["QueryEngine.ts"]
    MAIN --> CMDS["commands.ts"]
    MAIN --> TOOLS_TS["tools.ts"]

    QE --> QUERY["query.ts"]
    QE --> PUI["processUserInput.ts"]

    QUERY --> CLAUDE["claude.ts"]
    QUERY --> STE["StreamingToolExecutor.ts"]
    QUERY --> COMPACT["compact.ts"]

    CLAUDE --> RETRY["withRetry.ts"]
    CLAUDE --> ERRORS["errors.ts"]

    STE --> EXEC["toolExecution.ts"]
    EXEC --> PERMS["permissions.ts"]
    EXEC --> HOOKS["hooks.ts"]

    TOOLS_TS --> TOOL["Tool.ts"]
    TOOL --> BUILTIN["30+ Tool implementations"]

核心抽象

QueryEngine

会话级编排器。每个对话对应一个实例。管理消息历史、文件状态 cache、用量追踪和 permission 拒绝追踪。

src/QueryEngine.ts (1296 行)
├── submitMessage()      — 主入口，yield SDKMessage stream
├── interrupt()          — 中止当前操作
├── getMessages()        — 读取对话历史
└── setModel()           — 会话中途切换模型

Tool

所有能力的通用接口 — 从读取文件到派生 sub-agent。每个 tool 都实现相同的接口，buildTool() 提供默认值：

src/Tool.ts (793 行)
├── Tool<Input, Output, P>    — 完整 tool 接口
├── ToolDef<Input, Output, P> — 部分定义（用于 buildTool）
├── buildTool()               — 填充默认值，返回完整 Tool
├── ToolUseContext             — 传递给每次 tool 调用的运行时 context
└── ToolPermissionContext      — 用于 tool 过滤的 permission 状态

Command

slash command 接口，支持三种类型：

src/types/command.ts

type Command =
  | { type: 'local'; ... }      // Synchronous, local execution
  | { type: 'local-jsx'; ... }  // Renders Ink UI
  | { type: 'prompt'; ... }     // Expands to text for the model

Permission

多来源 permission 规则，支持模式匹配：

src/types/permissions.ts
├── PermissionMode        — 'default' | 'plan' | 'auto' | 'bypassPermissions'
├── PermissionResult      — 'allow' | 'deny' | 'ask' with updatedInput
├── ToolPermissionRulesBySource — Rules keyed by setting source
└── AdditionalWorkingDirectory  — Extra allowed directories

数据流：从用户输入到响应

sequenceDiagram
    participant U as User
    participant M as main.tsx
    participant QE as QueryEngine
    participant Q as query.ts
    participant C as claude.ts
    participant R as withRetry
    participant API as Anthropic API
    participant STE as StreamingToolExecutor
    participant T as Tool.call()

    U->>M: Type message + Enter
    M->>QE: submitMessage(prompt)
    QE->>QE: processUserInput() → messages
    QE->>Q: query({ messages, systemPrompt })
    Q->>C: createStreamedResponse()
    C->>R: withRetry(operation)
    R->>API: POST /v1/messages (streaming)
    API-->>R: SSE stream events
    R-->>C: Stream events
    C-->>Q: Parsed messages

    alt Tool use requested
        Q->>STE: addTool(block, assistantMessage)
        STE->>T: call(args, context, canUseTool)
        T-->>STE: ToolResult
        STE-->>Q: User message with tool_result
        Q->>C: Next turn with tool results
    end

    Q-->>QE: yield messages
    QE-->>M: SDKMessage stream
    M-->>U: Rendered output

目录结构图

src/
├── entrypoints/          # 进程入口（cli.tsx, init.ts, mcp.ts）
├── bootstrap/            # 早期状态初始化
├── commands/             # 60+ slash command（/help, /config, /model, ...）
├── components/           # Ink React 组件（UI）
├── constants/            # system prompt、beta 功能、限制
├── context/              # React context provider
├── hooks/                # React hook（permission、tool、state）
├── services/
│   ├── api/              # claude.ts, withRetry.ts, errors.ts
│   ├── analytics/        # GrowthBook, 遥测
│   ├── compact/          # 自动 compaction, 响应式 compaction
│   ├── mcp/              # MCP 客户端, 配置, 服务器管理
│   ├── tools/            # StreamingToolExecutor, toolOrchestration
│   └── ...
├── tools/                # 30+ tool 实现
│   ├── AgentTool/
│   ├── BashTool/
│   ├── FileEditTool/
│   ├── FileReadTool/
│   ├── GlobTool/
│   ├── GrepTool/
│   └── ...
├── types/                # TypeScript 类型定义
├── utils/                # 工具模块
│   ├── settings/         # 配置系统
│   ├── permissions/      # Permission 引擎
│   ├── model/            # 模型选择与路由
│   ├── plugins/          # Plugin 加载
│   └── ...
├── main.tsx              # Commander.js CLI 框架
├── commands.ts           # 命令注册表
├── query.ts              # Agentic loop
├── QueryEngine.ts        # 会话生命周期
├── Tool.ts               # Tool 接口
└── tools.ts              # Tool pool 组装

核心要点

架构原则

1. 分层隔离：每一层都有单一职责，从进程引导到 API 通信
2. 基于 generator 的 streaming：AsyncGenerator 贯穿全局，用于具备背压感知的消息传递
3. 默认失败关闭：buildTool() 默认 isConcurrencySafe: false、isReadOnly: false
4. Feature flag：Bun 的 feature() 支持内部功能的构建时死代码消除
5. Memoize：耗时操作（命令加载、tool 组装）使用 lodash/memoize