Claude Code 深度架构解析

状态机

type State = {
  messages: Message[]
  toolUseContext: ToolUseContext
  autoCompactTracking: AutoCompactTrackingState
  maxOutputTokensRecoveryCount: number
  hasAttemptedReactiveCompact: boolean
  pendingToolUseSummary: Promise<...>
  stopHookActive: boolean
  turnCount: number
  transition: Continue | undefined
}

错误恢复机制

开发 核心开发命令

计划 规划与推理

配置 配置与管理

扩展 扩展与集成

信息 信息与会话

高级 高级功能

核心组件

输入处理

• 键盘：parse-keypress.ts 解析终端键序列
• 鼠标：hit-test.ts 处理点击事件
• 焦点：focus.ts 管理 Tab/Click 焦点
• 选择：selection.ts 文本选择和复制
• 事件：Event Dispatcher 分发事件到组件

ANSI 协议支持

• CSI (Control Sequence Introducer)
• SGR (Select Graphic Rendition) — 颜色
• OSC (Operating System Command)
• DEC 私有模式序列

核心布局组件

输入组件

消息渲染组件 (40+)

对话框与任务组件

核心状态 Hooks

输入与交互 Hooks

连接与会话 Hooks

任务与通知 Hooks

API API 通信服务

services/api/ — 20 个文件

• claude.ts — Anthropic API 核心通信层
• client.ts — SDK 客户端初始化与配置
• withRetry.ts — API 失败重试逻辑
• errors.ts — 错误处理与转换
• usage.ts — Token 使用追踪
• grove.ts — Grove API 集成（Anthropic 内部服务）

压缩 上下文压缩服务

services/compact/ — 11 个文件

• compact.ts — 主压缩算法
• autoCompact.ts — 自动触发系统
• microCompact.ts — 轻量内联压缩
• sessionMemoryCompact.ts — 持久记忆压缩
• prompt.ts — 压缩 Prompt 生成

MCP MCP 协议服务

services/mcp/ — 23 个文件

• MCPConnectionManager.tsx — MCP 生命周期管理
• client.ts — MCP 客户端实现
• config.ts — 配置解析与验证
• channelPermissions.ts — Telegram/Channel 访问控制
• officialRegistry.ts — 官方 MCP 注册表

其他 其他关键服务

1. AsyncGenerator 流式架构

query.ts 和 QueryEngine.ts 使用 async function* 实现流式输出。每个 Token、每个工具结果都通过 yield 逐步发送给 UI 层，实现实时体验。

async function* query(params) {
  while (shouldContinue) {
    yield* streamAPIResponse()
    yield* executeTools()
  }
}

2. Feature Gate 门控

使用 Bun 的 feature() 系统实现构建时代码消除。不同的构建产物包含不同的功能集。

if (feature('KAIROS')) {
  tools.push(SleepTool, CronCreateTool)
}
if (feature('REPL_TOOL')) {
  tools.push(REPLTool)
}

3. Memoize 缓存模式

context.ts、commands.ts 等使用 memoize 缓存昂贵计算结果，一次计算，全程复用。支持手动失效。

4. Branded Types 品牌类型

SessionId 和 AgentId 使用 TypeScript 品牌类型，编译时防止 ID 混用。

type SessionId = string & { __brand: 'SessionId' }
type AgentId = string & { __brand: 'AgentId' }

5. Provider + Hook 模式

全局状态通过 React Context Provider 注入，组件通过 useXxx Hook 订阅。避免 Prop Drilling。

Provider 层级：AppState → Keybinding → Modal → Notifications → Theme

6. buildTool() 工厂模式

所有工具通过 buildTool() 工厂函数创建，自动补充安全默认值。工具只需实现关心的方法。

7. 懒加载 + 延迟预取

非关键模块使用动态 require() 延迟加载。系统 Prompt、MCP 资源在首次渲染后后台预取。

8. 文件锁并发控制

history.jsonl、config.json 等共享文件使用文件级锁防止竞态条件。

9. Forked Agent 隔离

记忆压缩、摘要生成等操作在子进程中运行，不阻塞主线程。使用 CacheSafeParams 共享 Prompt 缓存。

10. Reactor 错误恢复

query 循环实现多级错误恢复：max_output_tokens 继续 → Reactive Compact → Auto Compact → Stop Hook → 用户通知。

1. System Prompt —— Harness 的「宪法」

文件：constants/prompts.ts

System Prompt 不是简单的「你是一个 AI 助手」，而是一份精心编写的行为规范文档，包括：

• 工具使用优先级（Read 优先于 cat，Edit 优先于 sed）
• 安全规则（不要引入 XSS/SQL 注入等漏洞）
• 行为约束（不要过度重构、不要添加多余注释）
• Git 安全协议（永远不要 amend 除非明确要求）
• 动态注入的输出风格、记忆文件、Hooks 配置说明

2. Hooks 系统 —— 确定性行为拦截

文件：utils/hooks.ts, query/stopHooks.ts

Hooks 允许用户在模型行为的关键节点注入确定性 Shell 命令：

3. Permission 系统 —— 模型能力的硬边界

文件：utils/permissions/filesystem.ts

权限系统定义了模型的硬能力边界，独立于模型的判断：

• 路径保护：.gitconfig、.bashrc、.ssh/、.git/ 等敏感路径硬编码保护
• Harness 内部路径：会话记忆、计划文件、工具结果目录标记为 harness-controlled，自动放行读取
• 多级信任：default（逐一审批）→ plan（只读预览）→ acceptEdits（自动批准编辑）→ dontAsk（完全信任）
• UNC/SSH 路径阻止：防止凭据泄露攻击

// filesystem.ts line 1153
// 7. Allow reads from internal harness paths
//    (session-memory, plans, tool-results)

// filesystem.ts line 1763
// this subtree is harness-controlled.

4. Speculation 推测执行 —— 安全沙箱

文件：services/PromptSuggestion/speculation.ts

Harness 可以在模型不知情的情况下，将执行切换到沙箱模式：

• 安全工具：只有 Read、Glob、Grep、TaskGet 可执行
• 写操作隔离：Edit/Write 写入 Overlay 目录（/tmp/speculation/{pid}/）
• 上限控制：最多 20 轮推测、100 条消息
• 用户决策：接受 → Overlay 合并到真实文件系统；拒绝 → 丢弃

5. Claude Code Hints —— 带外侧信道

文件：utils/claudeCodeHints.ts

工具可以通过特殊 XML 标签与 Harness 直接通信，不经过模型：

// 工具 Stderr 输出
<claude-code-hint v="1" type="plugin" value="name@marketplace" />

// Harness 处理：
// 1. 扫描工具输出中的 hint 标签
// 2. 从输出中剥离（模型看不到）
// 3. 以 UI 提示形式展示给用户

源码注释明确指出："hints are a harness-only side channel"（hints 是仅 harness 可见的侧信道）

6. Memory 目录保证 —— Harness 基础设施

文件：memdir/memdir.ts

Harness 保证记忆目录始终存在，模型无需检查：

// memdir.ts line 114
// Harness guarantees the directory exists
// via ensureMemoryDirExists().
// The model can write directly without mkdir.

这意味着 System Prompt 可以告诉模型「直接写入，不要运行 mkdir」，因为 Harness 已经在启动时创建好了目录。这是一个微小但典型的 Harness-Model 协作模式：Harness 处理基础设施，模型专注推理。

7. 消融实验基线 —— 衡量 Harness 的独立价值

文件：entrypoints/cli.tsx line 16

// Harness-science L0 ablation baseline.
if (feature('ABLATION_BASELINE') &&
    process.env.CLAUDE_CODE_ABLATION_BASELINE) {
  // 关闭所有 Harness 增强功能：
  // CLAUDE_CODE_SIMPLE       → 简化 System Prompt
  // DISABLE_THINKING         → 关闭 Extended Thinking
  // DISABLE_COMPACT          → 关闭自动压缩
  // DISABLE_INTERLEAVED_THINKING → 关闭交错思维
  // ...
}

8. 工具编排 —— 模型请求，Harness 决策

文件：services/tools/toolOrchestration.ts

模型通过 API 发出工具调用请求，但Harness 控制实际执行：

• 并发分区：只读工具可并行，写入工具串行
• 权限拦截：canUseTool() 在执行前检查，可阻止
• 超时管理：Bash 命令 15 秒后自动后台化
• 中止信号：AbortController 可以随时终止所有进行中的工具
• 结果大小控制：超过 maxResultSizeChars 自动持久化到磁盘