# Claude Code 源码架构总览

> 基于 2026-03-31 公开暴露的源码快照分析

## 项目基本信息

| 属性 | 值 |
|------|-----|
| 语言 | TypeScript (strict) |
| 运行时 | Bun |
| 终端 UI | React + Ink |
| CLI 框架 | Commander.js |
| Schema 验证 | Zod v4 |
| 代码搜索 | ripgrep |
| 通信协议 | MCP SDK, LSP |
| API | Anthropic SDK |
| 遥测 | OpenTelemetry + gRPC |
| 特性开关 | GrowthBook / Bun feature flags |
| 认证 | OAuth 2.0, JWT, macOS Keychain |
| 规模 | ~1,900 文件, 512,000+ 行代码 |

## 整体架构

```mermaid
graph TB
    subgraph 用户层
        CLI[CLI 入口<br/>main.tsx]
        IDE[IDE 扩展<br/>VS Code / JetBrains]
        Desktop[桌面应用]
        Mobile[移动应用]
    end

    subgraph 命令层
        CMD[命令注册器<br/>commands.ts]
        CMD_IMPL[命令实现<br/>commands/ ~82个]
    end

    subgraph 工具层
        TOOL_REG[工具注册器<br/>tools.ts]
        TOOL_IMPL[工具实现<br/>tools/ ~40个]
        TOOL_TYPE[工具类型定义<br/>Tool.ts]
    end

    subgraph 核心引擎
        QE[查询引擎<br/>QueryEngine.ts]
        QS[查询管道<br/>query.ts]
        CTX[上下文管理<br/>context.ts]
    end

    subgraph 服务层
        API_SVC[API 服务<br/>services/api/]
        MCP_SVC[MCP 服务<br/>services/mcp/]
        AUTH_SVC[OAuth 认证<br/>services/oauth/]
        LSP_SVC[LSP 服务<br/>services/lsp/]
        ANALYTICS[分析/特性开关<br/>services/analytics/]
    end

    subgraph 基础设施
        BRIDGE[IDE 桥接<br/>bridge/]
        COORD[多代理协调<br/>coordinator/]
        PLUGINS[插件系统<br/>plugins/]
        SKILLS[技能系统<br/>skills/]
        PERM[权限系统<br/>hooks/toolPermission/]
    end

    subgraph UI 层
        COMP[UI 组件<br/>components/ ~140个]
        SCREENS[全屏界面<br/>screens/]
        VIM[Vim 模式<br/>vim/]
        KB[快捷键<br/>keybindings/]
    end

    CLI --> CMD --> CMD_IMPL
    CLI --> TOOL_REG --> TOOL_IMPL
    IDE --> BRIDGE --> QE
    QE --> QS --> API_SVC
    TOOL_IMPL --> PERM
    QE --> CTX
    CMD_IMPL --> TOOL_IMPL
    TOOL_IMPL --> MCP_SVC
    TOOL_IMPL --> LSP_SVC
    QE --> ANALYTICS
    BRIDGE --> AUTH_SVC
    CLI --> COMP --> SCREENS
    COMP --> VIM
    COMP --> KB
    COORD --> TOOL_IMPL
    PLUGINS --> TOOL_REG
    SKILLS --> CMD
```

## 目录结构

```
src/
├── main.tsx                 # 入口：Commander.js CLI + React/Ink 渲染
├── commands.ts              # 命令注册器
├── tools.ts                 # 工具注册器
├── Tool.ts                  # 工具类型定义
├── QueryEngine.ts           # LLM 查询引擎
├── query.ts                 # 查询管道
├── context.ts               # 系统/用户上下文收集
├── cost-tracker.ts          # Token 成本追踪
│
├── commands/                # 命令实现 (~82 个命令, 189 个文件)
├── tools/                   # 工具实现 (~40 个工具)
├── components/              # Ink UI 组件 (~140 个)
├── hooks/                   # React hooks (~70 个)
├── services/                # 外部服务集成
├── screens/                 # 全屏界面 (Doctor, REPL, Resume)
├── types/                   # TypeScript 类型定义
├── utils/                   # 工具函数
│
├── bridge/                  # IDE 和远程控制桥接 (30+ 文件)
├── coordinator/             # 多代理协调器
├── plugins/                 # 插件系统
├── skills/                  # 技能系统
├── keybindings/             # 快捷键配置
├── vim/                     # Vim 模式
├── voice/                   # 语音输入
├── remote/                  # 远程会话
├── server/                  # 服务模式
├── memdir/                  # 持久化内存目录
├── tasks/                   # 任务管理
├── state/                   # 状态管理 (AppState)
├── migrations/              # 配置迁移
├── schemas/                 # 配置 Schema (Zod)
├── entrypoints/             # 初始化逻辑
├── ink/                     # Ink 渲染器包装
├── buddy/                   # 伙伴精灵
├── native-ts/               # 原生 TypeScript 工具
├── outputStyles/            # 输出样式
├── query/                   # 查询管道子模块
├── assistant/               # 助手相关
├── bootstrap/               # 引导逻辑
├── cli/                     # CLI 相关
├── constants/               # 常量定义
├── context/                 # 上下文子模块
├── moreright/               # 扩展权限
└── upstreamproxy/           # 代理配置
```

## 启动流程

```mermaid
sequenceDiagram
    participant User as 用户
    participant Main as main.tsx
    participant Commander as Commander.js
    participant MDM as MDM 设置
    participant Keychain as macOS Keychain
    participant GB as GrowthBook
    participant Ink as Ink 渲染器
    participant REPL as REPL 主循环

    User->>Main: claude [command]
    Main->>MDM: 并行预取 MDM 设置
    Main->>Keychain: 并行预取 Keychain
    Main->>GB: 并行初始化 GrowthBook
    Main->>Commander: 解析 CLI 参数
    Commander->>Main: 路由到对应命令
    Main->>Ink: 初始化 React/Ink 渲染
    Ink->>REPL: 启动 REPL 主循环
    REPL->>REPL: 进入查询-响应循环
```

## 核心设计模式

### 1. 并行预取 (Parallel Prefetch)
启动时并行预取 MDM 设置、Keychain 读取和 API 预连接，优化启动时间。

### 2. 惰性加载 (Lazy Loading)
重型模块（OpenTelemetry、gRPC、分析等）通过动态 `import()` 延迟加载。

### 3. 特性开关 (Feature Flags)
通过 Bun 的 `bun:bundle` 实现编译时死代码消除：
```typescript
const SleepTool = feature('PROACTIVE') || feature('KAIROS')
  ? require('./tools/SleepTool/SleepTool.js').SleepTool
  : null
```

### 4. 代理集群 (Agent Swarms)
通过 `AgentTool` 生成子代理，`coordinator/` 处理多代理编排，`TeamCreateTool` 支持团队级并行工作。

### 5. 工具搜索延迟发现
`ToolSearchTool` 允许在工具数量超过阈值时延迟加载工具定义，减少 prompt token 开销。