Claude Code实现原理分析-架构设计

一、项目概述

Claude Code 是 Anthropic 官方出品的 AI 编程 CLI 工具，代号 Tengu 。它不是一个简单的 LLM 包装器，而是一个完整的 AI Agent 运行时框架，具备以下核心能力：

基于终端的交互式 REPL 界面（React/Ink 渲染）
40+ 个可组合的 Agent 工具
多 Agent 并行编排（Swarm 模式，支持 tmux 多进程协作）
持久化记忆与自动整合（Dream 系统）
IDE 双向集成（Bridge 层）
MCP 协议支持（Model Context Protocol）
插件与技能扩展系统
语音输入支持（流式 STT）
上下文窗口自动管理（Compact / MicroCompact）
推测执行（Speculation）--- 预测用户意图并提前执行
费用追踪与 Token 预算管理
多种权限模式（交互确认 / Auto / Plan / Bypass）

技术栈：TypeScript + Bun 运行时 + React/Ink（终端 UI）+ Commander.js（CLI 框架）+ Zod（输入校验）+ OpenTelemetry（遥测）

二、整体架构分层

复制代码

┌──────────────────────────────────────────────────────────────────┐
│                        接入层 (Access Layer)                      │
│   CLI 终端 (React/Ink)  |  Bridge IDE 集成  |  MCP Server 模式    │
│   Agent SDK (编程接入)  |  Remote 远程会话  |  Channel (IM 接入)    │
├──────────────────────────────────────────────────────────────────┤
│                     交互控制层 (Interaction Layer)                 │
│   REPL 主循环  |  命令路由 (80+ 斜杠命令)  |  快捷键系统           │
│   权限管理 (多模式)  |  状态管理 (React Store)  |  通知系统         │
├──────────────────────────────────────────────────────────────────┤
│                     核心引擎层 (Core Engine Layer)                 │
│   QueryEngine (LLM 调用核心)  |  Task 调度 (7 种任务类型)          │
│   上下文管理 (Compact/MicroCompact)  |  推测执行 (Speculation)     │
│   费用追踪 (Cost Tracker)  |  Token 预算控制                      │
├──────────────────────────────────────────────────────────────────┤
│                     工具执行层 (Tool Layer)                        │
│   Bash | File | Web | LSP | Agent | MCP | REPL | ...40+ tools    │
│   工具权限分类器 (Classifier)  |  并发安全控制  |  中断行为管理      │
├──────────────────────────────────────────────────────────────────┤
│                     Agent 编排层 (Orchestration Layer)             │
│   AgentTool (子 Agent 启动)  |  Swarm 团队协作 (tmux 多进程)       │
│   Task 生命周期管理  |  Agent 间消息路由 (Inbox/SendMessage)       │
├──────────────────────────────────────────────────────────────────┤
│                     服务支撑层 (Service Layer)                     │
│   记忆/Dream  |  MCP  |  OAuth  |  Analytics  |  LSP  |  插件    │
│   语音 STT  |  MagicDocs  |  Compact  |  PromptSuggestion        │
├──────────────────────────────────────────────────────────────────┤
│                     基础设施层 (Infrastructure Layer)              │
│   Bridge 协议  |  传输层 (WS/SSE/Hybrid)  |  配置 (多层级)        │
│   遥测 (OpenTelemetry)  |  迁移  |  Bootstrap  |  安全沙箱        │
└──────────────────────────────────────────────────────────────────┘

各层之间的依赖关系是严格自上而下 的：上层依赖下层，下层不感知上层。唯一的例外是 Tool 接口中的 UI 渲染方法（renderToolUseMessage 等），这是一种控制反转设计------工具层定义渲染逻辑，但由 UI 层调用。

三、核心模块详解

3.1 入口层 (`src/entrypoints/` + `src/main.tsx`)

系统有多个入口点，对应不同的运行模式：

入口文件	用途	运行模式
`entrypoints/cli.tsx`	标准 CLI 交互模式	终端 REPL
`entrypoints/mcp.ts`	作为 MCP Server 运行	被其他 Agent 调用
`entrypoints/init.ts`	初始化与遥测启动	所有模式共用
`entrypoints/agentSdkTypes.ts`	对外暴露的 Agent SDK	编程接入
`src/main.tsx`	主入口，约 4600+ 行，Commander.js 命令注册	所有 CLI 模式

main.tsx 的启动流程：

复制代码

main()
  │
  ├── 1. initializeEntrypoint()     → 环境检测、日志初始化
  ├── 2. eagerLoadSettings()        → 加载配置（CLI flag → 环境变量 → 配置文件）
  ├── 3. runMigrations()            → 执行数据迁移（版本升级兼容）
  ├── 4. logStartupTelemetry()      → 上报启动遥测
  ├── 5. prefetchSystemContextIfSafe() → 预加载系统上下文（Git 信息等）
  ├── 6. run()                      → Commander.js 命令路由
  │       ├── 注册 80+ 斜杠命令
  │       ├── 解析 CLI 参数
  │       └── 启动对应模式（REPL / Bridge / SDK / ...）
  └── 7. maybeActivateProactive()   → 激活 KAIROS 主动模式（如果配置开启）

关键设计：main.tsx 同时承担了命令注册和启动编排的职责。虽然文件较大，但通过函数拆分保持了可读性。80+ 个斜杠命令分散在 src/commands/ 目录下，每个命令是独立模块。

3.2 核心引擎层 (`src/QueryEngine.ts`)

QueryEngine 是整个系统的 LLM 调用核心，是最重的单文件。

typescript 复制代码

class QueryEngine {
  constructor(config: QueryEngineConfig)
  
  // 核心：提交消息，返回异步流式响应
  async *submitMessage(...): AsyncGenerator<Message>
  
  // 中断当前执行
  interrupt(): void
  
  // 获取完整会话消息历史
  getMessages(): readonly Message[]
  
  // 获取文件读取状态缓存
  getReadFileState(): FileStateCache
  
  // 动态切换模型
  setModel(model: string): void
}

// 独立的 ask() 生成器函数，处理单次 LLM 调用
async function* ask({...}): AsyncGenerator<StreamEvent>

核心职责：

管理与 Anthropic API 的通信（流式响应）
维护完整的对话历史（Message[]）
协调工具调用循环（tool_use → tool_result → 继续对话）
文件读取状态缓存（避免重复读取）
支持运行时切换模型
消息选择器（messageSelector）--- 控制哪些消息发送给 API

QueryEngine 与 ask() 的关系：QueryEngine 是有状态的会话管理器，ask() 是无状态的单次 API 调用。submitMessage() 内部循环调用 ask()，每次工具调用结果返回后再次调用，直到 LLM 不再请求工具。

3.3 工具系统 (`src/Tool.ts` + `src/tools/`)

工具系统是 Claude Code 的执行能力核心，采用接口驱动的插件化设计 。每个工具通过 buildTool() 工厂函数构建，输入使用 Zod schema 校验。

Tool 基类接口

typescript 复制代码

interface Tool<Input, Output> {
  name: string
  
  // ── 核心执行 ──
  call(input: Input): Promise<Output>
  description(): string
  prompt(options): string              // 生成给 LLM 的工具描述
  
  // ── 权限与安全 ──
  checkPermissions(input: Input): PermissionResult
  isReadOnly(input: Input): boolean    // 只读操作无需确认
  isDestructive?(input: Input): boolean // 破坏性操作需要额外警告
  isOpenWorld?(input: Input): boolean  // 是否访问外部资源
  
  // ── 并发控制 ──
  isConcurrencySafe(input: Input): boolean  // 是否可并行执行
  interruptBehavior?(): 'cancel' | 'block' // 中断时取消还是阻塞
  
  // ── 输入处理 ──
  validateInput?(input): ValidationResult  // 自定义输入校验
  inputsEquivalent?(a, b): boolean         // 判断两次调用是否等价（去重）
  toAutoClassifierInput(input): unknown    // 转换为分类器输入格式
  
  // ── UI 渲染（React/Ink）──
  renderToolUseMessage(input): ReactNode           // 工具调用展示
  renderToolResultMessage?(output): ReactNode      // 结果展示
  renderToolUseProgressMessage?(...): ReactNode    // 执行中进度
  renderToolUseQueuedMessage?(): ReactNode         // 排队等待
  renderToolUseRejectedMessage?(...): ReactNode    // 被拒绝
  renderToolUseErrorMessage?(...): ReactNode       // 错误展示
  renderGroupedToolUse?(...): ReactNode            // 分组展示
  
  // ── 元信息 ──
  userFacingName(input): string        // 用户可见名称
  getPath?(input): string              // 关联的文件路径
  getToolUseSummary?(input): string    // 工具使用摘要
  getActivityDescription?(...): string // 活动描述（用于状态栏）
  extractSearchText?(output): string   // 从结果中提取搜索文本
  isResultTruncated?(output): boolean  // 结果是否被截断
}

这个接口设计的精妙之处在于：每个工具是一个自包含的单元，同时封装了执行逻辑、权限策略、并发语义和 UI 渲染。新增工具只需实现这个接口，不需要修改框架代码。

工具清单（40+）

文件系统类：

FileReadTool --- 读取文件内容
FileWriteTool --- 写入/创建文件
FileEditTool --- 精确编辑文件（字符串替换）
GlobTool --- 文件路径模式匹配
GrepTool --- 文件内容正则搜索
NotebookEditTool --- Jupyter Notebook 编辑

代码执行类：

BashTool --- 执行 Shell 命令
PowerShellTool --- Windows PowerShell 执行
REPLTool --- 交互式 REPL 会话

网络类：

WebFetchTool --- 抓取网页内容
WebSearchTool --- 网络搜索

Agent 编排类：

AgentTool --- 启动子 Agent（核心多 Agent 工具）
TaskCreateTool / TaskGetTool / TaskListTool / TaskUpdateTool / TaskStopTool / TaskOutputTool --- 任务生命周期管理
TeamCreateTool / TeamDeleteTool --- Agent 团队管理
SendMessageTool --- Agent 间消息传递

IDE 集成类：

LSPTool --- Language Server Protocol 集成
MCPTool --- MCP 协议工具调用
ListMcpResourcesTool / ReadMcpResourceTool --- MCP 资源管理
McpAuthTool --- MCP 认证

流程控制类：

EnterPlanModeTool / ExitPlanModeTool --- 规划模式切换
EnterWorktreeTool / ExitWorktreeTool --- Git Worktree 模式
SleepTool --- 等待/延迟
ScheduleCronTool --- 定时任务调度
AskUserQuestionTool --- 向用户提问
TodoWriteTool --- 待办事项管理
SkillTool --- 技能调用
BriefTool --- 简报生成
ConfigTool --- 配置管理
ToolSearchTool --- 工具搜索
RemoteTriggerTool --- 远程触发
SyntheticOutputTool --- 合成输出

3.4 任务系统 (`src/Task.ts` + `src/tasks/`)

任务系统是多 Agent 编排的基础设施，定义了 7 种任务类型和完整的生命周期管理。

任务类型

TaskType	ID 前缀	用途
`local_bash`	`b`	本地 Shell 命令执行
`local_agent`	`a`	本地子 Agent 任务
`remote_agent`	`r`	远程 Agent 任务（ULTRAPLAN 等）
`in_process_teammate`	`t`	进程内 Teammate（Swarm 成员）
`local_workflow`	`w`	本地工作流
`monitor_mcp`	`m`	MCP 监控任务
`dream`	`d`	记忆整合（Dream）任务

任务生命周期

复制代码

pending → running → completed
                  → failed
                  → killed

任务 ID 生成使用 crypto.randomBytes(8) + 36 字符字母表（0-9a-z），产生约 2.8 万亿种组合，足以抵抗暴力枚举攻击（防止 symlink 攻击）。每个任务有独立的磁盘输出文件（getTaskOutputPath），支持增量读取（outputOffset）。

3.5 多 Agent 编排 (`src/tools/AgentTool/` + `src/coordinator/`)

这是 Claude Code 最复杂的子系统，实现了 Swarm 模式的多 Agent 并行协作。

架构模式

复制代码

主 Agent (Orchestrator / Team Leader)
    │
    ├── AgentTool.call() → 启动子 Agent（进程内）
    │       │
    │       ├── 子 Agent A (独立 QueryEngine 实例, type=local_agent)
    │       ├── 子 Agent B (独立 QueryEngine 实例, type=local_agent)
    │       └── 子 Agent C (独立 QueryEngine 实例, type=local_agent)
    │
    ├── TaskCreateTool → 创建异步后台任务
    │       └── 后台 Agent 持续运行，主 Agent 通过 TaskGetTool 轮询结果
    │
    ├── TeamCreateTool → 创建 Swarm 团队（tmux 多进程）
    │       │
    │       ├── Teammate 1 (独立进程, tmux pane, type=in_process_teammate)
    │       ├── Teammate 2 (独立进程, tmux pane, type=in_process_teammate)
    │       └── Teammate N ...
    │       │
    │       └── SendMessageTool → Agent 间消息传递（通过 Inbox）
    │
    └── coordinatorMode → 协调器模式（高层任务分配）

Swarm 团队协作细节

Swarm 模式通过 teamContext 管理团队状态：

每个 Teammate 运行在独立的 tmux pane 中（真正的多进程隔离）
支持 Git Worktree 隔离（每个 Teammate 可以在独立的 worktree 中工作）
Agent 间通过 Inbox 消息队列通信（SendMessageTool 发送，inbox.messages 接收）
agentNameRegistry：名称到 AgentId 的映射，支持按名称路由消息
Worker 沙箱权限：Teammate 需要网络访问时，需向 Leader 申请（workerSandboxPermissions）

内置 Agent 类型

Agent	用途
`generalPurposeAgent`	通用任务执行
`planAgent`	复杂任务规划（ULTRAPLAN 底层）
`exploreAgent`	代码库探索与理解
`claudeCodeGuideAgent`	Claude Code 使用指导

关键设计

每个子 Agent 拥有独立的 QueryEngine 实例和消息历史
支持 autoBackground：子 Agent 可自动转为后台运行
agentMemory：每种 Agent 类型有独立的记忆目录，支持快照与同步
agentColorManager：终端中用颜色区分不同 Agent 的输出
TeamCreateTool：可动态创建 Agent 团队，协同完成任务
filterToolsForAgent()：每个子 Agent 可以有不同的工具集（安全隔离）
resolveAgentTools()：根据 Agent 定义动态解析可用工具

3.6 权限系统 (`src/utils/permissions/`)

权限系统是 Claude Code 安全模型的核心，采用多层级、多模式设计。

权限模式

模式	行为	适用场景
交互模式 (default)	每次写操作/Shell 命令需用户确认	日常使用
Auto 模式	分类器自动判断是否安全，不安全时回退到提示	信任度较高的场景
Plan 模式	只规划不执行，退出时可带 `allowedPrompts` 执行	复杂任务预审
Bypass 模式	跳过所有权限检查	受控环境（有 killswitch）

权限检查链

复制代码

LLM 请求 tool_use
    │
    ├── isReadOnly(input)?  ──── 是 → 直接执行（无需确认）
    │
    ├── isAutoModeActive()?
    │       ├── isAutoModeAllowlistedTool()? → 直接执行
    │       └── bashClassifier / classifierDecision → 分类器判断
    │               ├── 安全 → 执行
    │               └── 不安全 → 回退到交互确认
    │
    ├── checkPermissions(input) → 路径校验 + 沙箱检查
    │       ├── isPathAllowed() → 路径白名单
    │       ├── isPathInSandboxWriteAllowlist() → 沙箱写入白名单
    │       └── getClaudeSkillScope() → Skill 作用域限制
    │
    └── denialTracking → 连续拒绝追踪
            └── shouldFallbackToPrompting() → 超过阈值回退到提示模式

安全机制

bypassPermissionsKillswitch：远程 killswitch，可紧急禁用 Bypass 模式
denialTracking：追踪连续拒绝次数，防止 Agent 反复尝试被拒绝的操作
pathValidation：严格的路径校验，防止目录遍历攻击
expandTilde()：安全的 ~ 展开，避免路径注入

3.7 记忆系统 (`src/services/autoDream/` + `src/services/SessionMemory/` + `src/memdir/`)

Claude Code 实现了一套分层记忆架构，是其区别于普通 LLM 包装器的关键特性。

记忆层次

复制代码

┌─────────────────────────────────────────────┐
│  工作记忆 (Working Memory)                    │
│  当前对话的消息历史，存在 QueryEngine 中        │
├─────────────────────────────────────────────┤
│  会话记忆 (SessionMemory)                     │
│  当前会话的结构化记忆，可选择性持久化            │
├─────────────────────────────────────────────┤
│  持久记忆 (memdir/)                           │
│  MEMORY.md 索引 + 主题文件，跨会话持久化        │
│  由 autoDream 自动整合，或 /remember 手动写入   │
├─────────────────────────────────────────────┤
│  Agent 记忆 (agentMemory)                     │
│  每种 Agent 类型独立的记忆目录                  │
│  支持快照 (snapshot) 和跨作用域同步             │
└─────────────────────────────────────────────┘

自动整合记忆 (autoDream)

后台运行的记忆整合子 Agent（TaskType = dream），流程如下：

复制代码

1. Orient      → ls 记忆目录，读取 MEMORY.md 索引，了解当前记忆状态
2. Gather      → 扫描自上次整合以来的会话日志（增量，grep JSONL）
3. Consolidate → 提炼新知识，合并到已有主题文件（避免重复）
                 将相对日期转为绝对日期，删除已被推翻的旧事实
4. Prune       → 更新 MEMORY.md 索引（保持 <25KB），
                 每条索引 <150 字符，只做指针不做内容

关键机制：

consolidationLock：文件锁防止并发整合冲突（tryAcquireConsolidationLock / rollbackConsolidationLock）
isGateOpen()：基于时间间隔控制整合频率，避免过于频繁
isForced()：支持强制触发整合
listSessionsTouchedSince()：增量扫描，只处理上次整合后的新会话
Dream 与 KAIROS 解耦：consolidationPrompt.ts 独立于 KAIROS feature flag

记忆提取 (extractMemories)

从对话中自动识别并提取值得记住的信息片段，写入持久记忆。

3.8 Bridge 层 (`src/bridge/`)

Bridge 是 Claude Code 与 IDE（如 VS Code）之间的双向通信层，是实现"IDE 内嵌 AI"的核心。

架构

复制代码

IDE (VS Code Extension)
        │
        │  HTTP/WebSocket
        ▼
  Bridge Server (bridgeMain.ts)
        │
        ├── 轮询工作队列 (pollForWork)
        ├── 会话管理 (createSession / reconnectSession)
        ├── 权限回调 (bridgePermissionCallbacks)
        ├── 消息路由 (bridgeMessaging)
        └── 状态同步 (bridgeStatusUtil)
        │
        ▼
  Claude Code REPL 实例

关键组件

文件	职责
`bridgeMain.ts`	Bridge 主循环，管理连接生命周期
`bridgeApi.ts`	Bridge REST API 封装
`bridgeConfig.ts`	Bridge 配置（端点、认证等）
`bridgeMessaging.ts`	消息序列化与路由
`bridgePermissionCallbacks.ts`	工具权限的 IDE 侧确认
`jwtUtils.ts`	JWT 令牌生成与验证
`replBridge.ts`	REPL 实例与 Bridge 的绑定
`sessionRunner.ts`	会话生命周期管理
`trustedDevice.ts`	设备信任管理
`workSecret.ts`	工作密钥管理
`flushGate.ts`	输出刷新控制
`capacityWake.ts`	容量唤醒机制

3.9 上下文窗口管理 (`src/services/compact/`)

长对话场景下，上下文窗口管理是 AI Agent 的核心挑战。Claude Code 实现了多层级的上下文压缩策略。

压缩层次

层级	触发条件	策略
MicroCompact	每轮对话后	缓存友好的增量压缩，保留 prompt cache 命中率
AutoCompact	Token 使用超过阈值	自动触发完整压缩
手动 Compact	用户执行 `/compact`	用户主动触发
PTL Retry	API 返回 prompt_too_long	紧急截断头部消息重试

压缩流程

复制代码

原始消息历史
    │
    ├── stripImagesFromMessages()      → 移除图片（节省大量 token）
    ├── stripReinjectedAttachments()   → 移除重复注入的附件
    │
    ▼
groupMessagesByApiRound()             → 按 API 轮次分组
    │
    ▼
LLM 生成摘要 (getCompactPrompt)       → 用 LLM 压缩历史为摘要
    │
    ▼
buildPostCompactMessages()            → 构建压缩后的消息序列
    │
    ▼
runPostCompactCleanup()               → 清理缓存、重置状态

关键设计：

getEffectiveContextWindowSize(model)：根据模型动态计算有效窗口大小
getAutoCompactThreshold(model)：不同模型有不同的自动压缩阈值
calculateTokenWarningState()：Token 使用量预警（黄色/红色）
sessionMemoryCompact：压缩时保留会话记忆的关键信息
cachedMicrocompact：MicroCompact 结果缓存，避免重复压缩

3.10 状态管理 (`src/state/`)

采用类 Zustand 的不可变状态 + 选择器订阅设计，基于 React Context：

typescript 复制代码

// 核心 Store（自定义实现，非第三方库）
type Store<T> = {
  getState(): T
  setState(f: (prev: T) => T): void
  subscribe(listener: () => void): () => void
}

// React 绑定
AppState → AppStateStore → AppStateProvider (React Context)

// 访问方式
useAppState(selector)   // 订阅特定状态片段（选择器模式，避免不必要的重渲染）
useSetAppState()        // 获取状态更新函数
useAppStore()           // 获取完整 store 实例

AppState 是一个非常庞大的类型（约 400 行定义），使用 DeepImmutable<> 包装确保不可变性。主要包含：

状态域	内容
会话	settings, mainLoopModel, statusLineText
Agent/Swarm	tasks, agentNameRegistry, teamContext, inbox
Bridge	replBridgeEnabled/Connected/SessionActive/...
MCP	mcp.clients, mcp.tools, mcp.commands, mcp.resources
插件	plugins.enabled/disabled/errors/installationStatus
UI	expandedView, footerSelection, activeOverlays, notifications
推测执行	speculation (idle/active), speculationSessionTimeSavedMs
ULTRAPLAN	ultraplanLaunching/SessionUrl/PendingChoice
权限	toolPermissionContext, denialTracking
语音	通过 VoiceProvider 独立管理
Computer Use	computerUseMcpState (Chicago MCP)
Tungsten (tmux)	tungstenActiveSession, tungstenPanelVisible

注意：tasks 字段被排除在 DeepImmutable 之外，因为 TaskState 包含函数类型（kill() 方法）。

3.11 UI 层 (`src/screens/` + `src/components/` + `src/context/` + `src/hooks/`)

基于 React + Ink 实现终端 UI，将 React 的组件化思想带入 CLI。

主要屏幕

屏幕	用途
`REPL.tsx`	主交互界面，消息流展示
`ResumeConversation.tsx`	历史会话恢复
`Doctor.tsx`	系统诊断（`/doctor` 命令）

Context 系统

Context	用途
`mailbox.tsx`	Agent 间消息邮箱
`notifications.tsx`	通知队列管理（当前通知 + 等待队列）
`overlayContext.tsx`	覆盖层（弹窗）管理，支持 Escape 键协调
`promptOverlayContext.tsx`	提示词覆盖层
`modalContext.tsx`	模态框尺寸与滚动
`voice.tsx`	语音状态管理
`fpsMetrics.tsx`	渲染性能监控（FPS 采集）
`stats.tsx`	运行时统计指标（increment/set/observe/add）
`QueuedMessageContext.tsx`	排队消息管理

Hooks 系统 (`src/hooks/`)

hooks/ 目录包含 100+ 个 React hooks，是 UI 层最庞大的部分。主要分类：

notifs/ --- 各种通知 hooks（自动模式不可用、弃用警告、快速模式、LSP 初始化、MCP 连接状态等）
fileSuggestions.ts --- 文件路径自动补全（基于 Git 索引）
各种 IDE 状态指示器、安装消息等

3.12 服务层 (`src/services/`)

服务	职责
`autoDream/`	后台记忆整合（Dream 系统）
`SessionMemory/`	会话记忆管理
`extractMemories/`	对话记忆提取
`lsp/`	Language Server Protocol 客户端
`mcp/`	MCP Server 管理与通信
`oauth/`	OAuth 2.0 认证流程
`analytics/`	使用数据分析上报
`plugins/`	插件加载与管理
`MagicDocs/`	文档智能处理
`AgentSummary/`	Agent 执行摘要生成
`compact/`	上下文压缩（长对话裁剪）
`PromptSuggestion/`	提示词建议
`settingsSync/`	设置云端同步
`teamMemorySync/`	团队记忆同步
`remoteManagedSettings/`	远程托管配置
`policyLimits/`	策略限制执行
`toolUseSummary/`	工具使用摘要
`tips/`	使用技巧提示
`voice.ts`	语音输入（STT）服务
`vcr.ts`	请求录制回放（测试用）

MCP 服务详解 (`src/services/mcp/`)

MCP 是 Claude Code 最复杂的服务之一，包含 23 个文件：

模块	职责
`client.ts`	MCP 客户端核心，管理连接和工具调用
`config.ts`	MCP 配置管理（企业级 + 项目级 + 用户级）
`auth.ts`	OAuth 认证流程（含 PKCE）
`channelAllowlist.ts`	Channel（IM 渠道）白名单管理
`channelNotification.ts`	Channel 消息包装与路由
`channelPermissions.ts`	Channel 权限中继
`claudeai.ts`	claude.ai 平台 MCP 配置
`elicitationHandler.ts`	MCP Elicitation（表单/URL 交互）
`envExpansion.ts`	环境变量展开
`headersHelper.ts`	MCP 请求头管理（含 helper 程序集成）

3.13 API 通信层 (`src/services/api/`)

这是与 Anthropic API 通信的底层模块，QueryEngine 的下游依赖。

模块	职责
`client.ts`	Anthropic SDK 客户端创建（含自定义 headers、fetch 拦截）
`claude.ts`	API 请求参数构建（prompt caching、effort 参数、beta headers）
`errors.ts`	API 错误解析（prompt_too_long、media_size 等）
`errorUtils.ts`	连接错误诊断（SSL 错误提示等）
`bootstrap.ts`	启动时的 Bootstrap API 调用（获取初始配置）
`filesApi.ts`	文件上传/下载 API
`adminRequests.ts`	管理员请求 API
`dumpPrompts.ts`	API 请求缓存与调试导出

关键设计：

getPromptCachingEnabled(model)：按模型控制 prompt caching 开关
getCacheControl()：精细的缓存控制策略（支持 1 小时 TTL）
configureEffortParams()：动态调整 effort 参数（影响推理深度）
buildFetch()：自定义 fetch 实现，支持代理、重试、日志

3.14 插件与技能系统 (`src/plugins/` + `src/skills/`)

插件系统

builtinPlugins.ts：内置插件注册表
插件可以注册新的 Skill 命令
通过 pluginId 唯一标识

内置技能 (Skills)

技能	功能
`batch`	批量执行指令
`claudeApi`	Claude API 文档参考
`claudeInChrome`	Chrome 扩展集成
`debug`	调试辅助
`keybindings`	快捷键参考
`loop`	循环执行任务
`loremIpsum`	测试文本生成
`remember`	手动记忆存储

3.15 CLI 传输层 (`src/cli/transports/`)

支持多种传输协议，适配不同的运行环境：

传输	用途
`WebSocketTransport.ts`	WebSocket 实时双向通信
`SSETransport.ts`	Server-Sent Events 单向流
`HybridTransport.ts`	自动选择最优传输方式
`SerialBatchEventUploader.ts`	批量事件串行上传
`WorkerStateUploader.ts`	Worker 状态上传
`ccrClient.ts`	CCR（Claude Code Remote）客户端

3.16 快捷键系统 (`src/keybindings/`)

完整的终端快捷键框架，支持用户自定义：

parser.ts：快捷键字符串解析（支持 chord 组合键，如 Ctrl+K Ctrl+S）
match.ts：按键匹配引擎（处理修饰键、Ink 键盘事件）
resolver.ts：快捷键解析器（从绑定到动作的映射）
loadUserBindings.ts：加载用户自定义快捷键（JSON 配置文件）
reservedShortcuts.ts：系统保留快捷键（不可覆盖）
KeybindingContext.tsx：React Context，提供快捷键注册和查询
shortcutFormat.ts：快捷键显示格式化

3.17 Buddy 系统 (`src/buddy/`)

一个隐藏的终端电子宠物系统，纯属彩蛋。

复制代码

userId → hashString() → mulberry32(seed) → 确定性 PRNG
                                                │
                                    ┌───────────┴───────────┐
                                    │                       │
                               rollRarity()           rollStats()
                                    │                       │
                              5种稀有度              6种属性值
                         (common→legendary)    (DEBUGGING, CHAOS,
                                    │           SNARK, ...)
                                    │
                              pick(species)  → 18种物种
                              pick(eye)      → 眼睛样式
                              pick(hat)      → 帽子（稀有度≥uncommon）
                              shiny          → 1% 概率闪光

设计亮点：

基于 userId 的确定性生成，同一用户永远得到同一只宠物
bones（外观）不持久化存储，每次从 userId 重新生成，防止配置篡改
soul（性格描述）由 Claude 生成，存储在配置中
结果缓存（rollCache），避免高频调用重复计算

四、特殊系统

4.1 KAIROS --- 主动式助手

通过 maybeActivateProactive() 激活，是一个"始终在线"的后台 Agent：

持续监控项目日志和变更
无需用户输入，主动发现问题并采取行动
可通过配置开关控制（kairosEnabled 在 AppState 中）
与 setKairosActive() / getKairosActive() 全局状态联动

4.2 ULTRAPLAN --- 深度规划

通过 planAgent 实现，将复杂任务卸载到远程 Opus 4.6 会话：

最长运行 30 分钟
专门用于需要深度思考的复杂规划任务
结果返回给主 Agent 继续执行
完整的状态机：ultraplanLaunching → ultraplanSessionUrl → ultraplanPendingChoice
用户可选择在当前会话实施计划或开启新会话

4.3 推测执行 (Speculation)

预测用户下一步意图并提前执行，减少等待时间：

typescript 复制代码

type SpeculationState =
  | { status: 'idle' }
  | { status: 'active',
      id: string,
      abort: () => void,
      messagesRef: { current: Message[] },
      writtenPathsRef: { current: Set<string> },  // overlay 文件系统
      boundary: CompletionBoundary | null,
      isPipelined: boolean,
      pipelinedSuggestion?: { text, promptId, generationRequestId }
    }

CompletionBoundary：推测执行的边界条件（完成/bash 命令/文件编辑/工具拒绝）
speculationSessionTimeSavedMs：累计节省的时间（用于统计展示）
推测结果写入 overlay 文件系统，确认后才真正应用

4.4 Undercover 模式

供 Anthropic 内部员工在公开仓库工作时使用：

屏蔽内部模型代号（Capybara、Tengu 等）
隐藏 AI 身份信息
防止内部信息通过 AI 输出泄露

4.5 语音模式

voiceStreamSTT.ts：流式语音转文字
voiceKeyterms.ts：语音关键词识别
通过 isVoiceModeEnabled() 控制开关（GrowthBook 特性标志 + OAuth 认证检查）
VoiceProvider React Context 管理语音状态

4.6 MagicDocs --- 智能文档

自动检测和管理项目中的"魔法文档"（如 CLAUDE.md）：

detectMagicDocHeader()：识别文档头部标记
registerMagicDoc()：注册文档到追踪系统
getMagicDocsAgent()：获取专门处理文档更新的 Agent
buildMagicDocsUpdatePrompt()：构建文档更新提示词

4.7 费用追踪 (`src/cost-tracker.ts` + `src/bootstrap/state.ts`)

精细的费用和 Token 使用追踪：

按模型分别统计（输入/输出/缓存读取/缓存创建 token）
会话费用持久化（saveCurrentSessionCosts / restoreCostStateForSession）
支持 Token 预算控制（getCurrentTurnTokenBudget）
预算续期计数（getBudgetContinuationCount）
未知模型费用标记（hasUnknownModelCost）
工具执行时间、分类器时间、Hook 时间分别追踪

五、数据流

5.1 用户输入到 LLM 响应的完整流程

复制代码

用户输入 (键盘/语音/Bridge/Channel)
    │
    ▼
REPL.tsx (React/Ink UI)
    │
    ├── 推测执行检查：是否有匹配的 Speculation 结果？
    │       ├── 匹配 → 直接应用推测结果，跳过 API 调用
    │       └── 不匹配 → 继续正常流程
    │
    ▼
QueryEngine.submitMessage()
    │
    ├── 1. 构建消息（系统提示 + 工具定义 + 历史记录 + CLAUDE.md）
    ├── 2. 检查上下文窗口：是否需要 AutoCompact？
    │       └── 超过阈值 → 触发压缩，重建消息
    ├── 3. 费用预算检查：是否超出 Token 预算？
    │
    ▼
ask() → Anthropic API (流式响应)
    │
    ├── text_delta → 实时渲染到终端
    │
    └── tool_use → 工具调用
            │
            ├── 权限检查链（见 3.6 节）
            │       ├── 通过 → 继续
            │       ├── 拒绝 → tool_result(error) → 返回给 LLM
            │       └── 需确认 → Bridge 回调 IDE / 终端提示 / Channel 提示
            │
            ├── tool.call(input) → 执行工具
            │       ├── 并发安全？→ 可能并行执行多个工具
            │       └── 中断行为？→ cancel 或 block
            │
            └── tool_result → 返回给 LLM
                    │
                    └── LLM 继续生成（可能再次请求工具）
                            │
                            └── 循环直到 LLM 不再请求工具（end_turn）
    │
    ▼
MicroCompact 检查 → 是否需要增量压缩？
    │
    ▼
推测执行 → 预测下一步，提前开始执行

5.2 Bridge 通信流程

复制代码

IDE Extension (VS Code / claude.ai)
    │  HTTP POST /work (提交任务)
    ▼
Bridge Server (bridgeMain.ts)
    │  pollForWork() --- 长轮询 + 睡眠检测
    │  (pollSleepDetectionThresholdMs 防止笔记本休眠导致的假超时)
    ▼
工作队列
    │  acknowledgeWork() --- 确认接收
    ▼
sessionRunner → 创建/恢复 REPL 实例
    │  支持多会话 (isMultiSessionSpawnEnabled)
    │  支持 Worktree 模式 (每个会话独立 Git Worktree)
    ▼
REPL 实例处理
    │  结果/事件流
    ▼
Bridge Server
    │  SSE/WebSocket 推送
    │  heartbeatWork() --- 心跳保活
    ▼
IDE Extension 更新 UI
    │
    └── 断线重连：isConnectionError() / isServerError()
            └── addJitter(ms) --- 带抖动的指数退避

5.3 配置加载优先级

复制代码

CLI flags (--settings-file, --setting-sources)
    │  最高优先级
    ▼
环境变量 (ANTHROPIC_API_KEY, etc.)
    │
    ▼
项目级配置 (.claude/ 目录)
    │
    ▼
用户级配置 (~/.claude/ 目录)
    │
    ▼
远程托管配置 (remoteManagedSettings)
    │
    ▼
Bootstrap API 返回的默认配置
    │  最低优先级

六、设计模式总结

模式	应用场景	具体实现
插件/策略模式	Tool 系统、Skills、Plugins、传输层	`Tool` 接口 + `buildTool()` 工厂；`WebSocket/SSE/Hybrid` 传输策略
观察者/订阅模式	状态管理、Bridge 事件	`Store.subscribe()`、`useAppState(selector)`
命令模式	CLI 子命令、斜杠命令	Commander.js 注册 + `Command` 类型
异步生成器模式	LLM 流式响应	`async function* ask()`、`async *submitMessage()`
控制反转 (IoC)	工具 UI 渲染	工具定义渲染方法，UI 层调用
不可变状态模式	全局状态管理	`DeepImmutable<AppState>` + 函数式更新
文件锁模式	记忆整合并发控制	`tryAcquireConsolidationLock()`
确定性生成模式	Buddy 系统	`mulberry32(hashString(userId))`
分层缓存模式	上下文管理	MicroCompact（增量）→ AutoCompact（全量）→ PTL Retry（紧急）
断路器模式	权限系统	`denialTracking` + `shouldFallbackToPrompting()`
推测执行模式	响应加速	`SpeculationState` + overlay 文件系统

七、关键设计决策

React/Ink 做终端 UI ：将组件化思想引入 CLI，工具的进度、错误、结果都有独立的 React 组件渲染，UI 与逻辑解耦清晰。代价是引入了 React 运行时开销，但通过 fpsMetrics 监控保证了性能可控。
Tool 接口统一渲染与执行：每个 Tool 既负责执行逻辑，也负责自己的 UI 渲染，高内聚设计，新增工具无需修改其他代码。Zod schema 做输入校验，编译时类型安全。
QueryEngine 作为单一 LLM 网关 ：所有 LLM 调用都经过 QueryEngine，便于统一管理 token 计数、历史记录、模型切换、中断控制。ask() 函数与 QueryEngine 类的分离，让单次调用和会话管理各司其职。
Bridge 解耦 IDE 与 CLI：通过 HTTP/WebSocket 协议将 IDE 集成与核心逻辑完全解耦，Claude Code 可以独立运行，也可以被任何 IDE 通过 Bridge 协议接入。长轮询 + 睡眠检测的设计考虑了笔记本电脑的实际使用场景。
确定性 Buddy 生成：用 PRNG + userId 而非随机数，保证同一用户的宠物永远一致，同时 bones 不持久化防止作弊，是一个优雅的安全设计。
记忆分层：工作记忆（消息历史）→ 会话记忆 → 持久记忆（memdir）→ Agent 记忆，四层架构覆盖了从即时到永久的完整记忆需求。autoDream 的文件锁 + 增量扫描设计，保证了多会话并发场景下的数据一致性。
多层上下文压缩：MicroCompact（缓存友好增量）→ AutoCompact（阈值触发全量）→ PTL Retry（紧急截断），三层策略平衡了上下文利用率和 API 成本。
权限系统的纵深防御 ：从 isReadOnly 快速放行，到分类器自动判断，到交互确认，到 denialTracking 断路器，再到远程 killswitch，形成了完整的安全纵深。
推测执行：通过预测用户意图提前执行，将结果写入 overlay 文件系统（不影响真实文件），确认后才应用。这是一个在 AI Agent 领域比较前沿的优化。
Swarm 的进程隔离：Teammate 通过 tmux pane 实现真正的进程隔离（而非线程/协程），每个 Teammate 可以有独立的 Git Worktree，通过 Inbox 消息队列通信。这种设计牺牲了一些通信效率，但获得了更强的隔离性和容错性。

Claude Code实现原理分析-架构设计