架构总览
Claude Code 是一个基于 TypeScript + Bun 构建的终端 AI 助手，采用 React + Ink 渲染终端 UI，通过 Commander.js 解析 CLI 命令。其整体架构体现了高度模块化和可扩展性。
架构分层
┌─────────────────────────────────────────────────┐
│ 入口层 (Entrypoints) │
│ main.tsx · Commander.js CLI 解析 │
├─────────────────────────────────────────────────┤
│ UI 层 (Ink + React) │
│ 144 组件 · 104 Hooks · 主题系统 · 快捷键 │
├─────────────────────────────────────────────────┤
│ 命令层 (Commands) │
│ 101+ 斜杠命令 · 命令注册表 │
├─────────────────────────────────────────────────┤
│ 工具层 (Tools) │
│ 43+ Agent 工具 · 权限检查 · Schema 校验 │
├─────────────────────────────────────────────────┤
│ 查询引擎 (Query Engine) │
│ QueryEngine.ts · query.ts · LLM API 管道 │
├─────────────────────────────────────────────────┤
│ 服务层 (Services) │
│ API · MCP · LSP · OAuth · 压缩 · 遥测 · 分析 │
├─────────────────────────────────────────────────┤
│ 状态层 (State & Memory) │
│ 会话历史 · 持久记忆 · 任务管理 · 配置迁移 │
├─────────────────────────────────────────────────┤
│ 集成层 (Integrations) │
│ IDE Bridge · MCP Server · Agent 协调器 │
└─────────────────────────────────────────────────┘
核心入口
main.tsx (4,683 行) 是整个应用的入口文件，负责：
- CLI 参数解析（Commander.js）
- 用户认证与初始化
- 配置加载与迁移
- 启动 Ink 渲染器
- 建立 REPL 循环
查询引擎
查询引擎是 Claude Code 的核心，由两个关键文件组成：
QueryEngine.ts(1,295 行) — 封装与 Anthropic API 的通信，管理消息流、工具调用和流式响应query.ts(1,729 行) — 构建完整的查询管道，包括上下文收集、系统提示词组装、工具注入和响应处理
查询流程
用户输入 → 上下文收集 → 系统提示词组装 → 工具列表注入
↓
Anthropic API 调用 → 流式响应处理 → 工具调用执行
↓
工具结果返回 → 循环直到完成 → 渲染最终输出
性能优化
Claude Code 在启动和运行时做了大量性能优化：
并行预取
在模块加载之前，并行预取 MDM 设置和 Keychain 认证信息，减少启动延迟。
懒加载
重型模块（OpenTelemetry、gRPC、分析服务）采用懒加载策略，只在实际需要时才加载。
编译时特性标记
通过 Bun 的 bun:bundle 特性标记进行编译时死代码消除：
// 在构建时被替换为 true/false，实现条件编译
if (PROACTIVE) { /* 主动模式代码 */ }
if (KAIROS) { /* 计时系统代码 */ }
if (BRIDGE_MODE) { /* IDE 桥接代码 */ }
if (VOICE_MODE) { /* 语音模式代码 */ }
状态管理
Claude Code 采用多层状态管理策略：
| 状态类型 | 存储位置 | 生命周期 |
|---|---|---|
| 会话消息 | 内存 | 单次会话 |
| 用户偏好 | settings.json | 持久化 |
| 项目记忆 | ~/.claude/projects/ | 持久化 |
| 任务进度 | 任务系统 | 单次会话 |
| 认证令牌 | macOS Keychain | 持久化 |
| 遥测数据 | 本地文件 | 持久化 |
设计原则
- 工具即能力 — 每个工具都是一个自包含的能力单元，拥有独立的 Schema、权限和执行逻辑
- 权限先行 — 所有外部操作都经过权限系统审核
- 流式优先 — 从 API 响应到 UI 渲染，全链路流式处理
- 可扩展性 — 通过插件、技能、MCP 三套扩展机制支持第三方集成
- 优雅降级 — 功能不可用时（如无网络、无认证）提供明确的降级路径