前言

Read in English (Preview)

《驾驭工程》，中文别名《马书》。

我认为，Claude Code 源码最佳的“食用”姿势应该是转化为一本书，供自己系统学习。对我来说，看书学习比直接看源码更舒服，也更容易形成完整的认知框架。

为了尽可能保证 AI 写作质量，这本书的提取过程并不是“把源码丢给模型直接生成”那么简单，而是按一条比较严格的工程流程推进的：

1. 先根据源码把 DESIGN.md 聊清楚，也就是先把整本书的大纲和设计定下来。
2. 然后为每一章编写 spec，基于我开源的 agent-spec 来约束章节目标、边界和验收标准。
3. 接着再做 plan，把具体执行步骤拆开。
4. 最后再叠加我自己的技术写作 skill，才让 AI 开始正式写作。

这本书并不是为了出版，而是为了让我能更系统地学习 Claude Code。我对它的基本判断是：AI 肯定写不得十全十美，但只要把初始版本开源出来，大家就可以一边阅读、一边讨论、一边逐步完善它，把它共建成一本真正有价值的公版书。

第1章：AI 编码 Agent 的完整技术栈

为什么这很重要

要理解一个 AI 编码 Agent 如何从“接收用户输入“走到“在你的代码库中执行操作“，首先必须理解它的技术栈（technology stack）。技术栈不仅决定了性能天花板，更决定了架构边界——哪些事情可以在编译时完成，哪些必须推迟到运行时，哪些需要模型自己去决策。

Claude Code 的技术栈选择揭示了一个核心理念：AI 编码 Agent 不是传统的 CLI 工具，它是一个“在分发状态下（on distribution）运行“的系统——模型不仅使用工具，还能编写自己的工具。这意味着整个技术栈必须为“模型作为一等公民“而设计，从入口点的启动优化到 Feature Flag 的构建时消除，每一层都在为这个目标服务。

本章将建立一个贯穿全书的核心概念——三层架构——并通过源码分析展示它如何在 Claude Code v2.1.88 中具体落地。

1.1 技术栈概览：TypeScript + React Ink + Bun

Claude Code 的技术选型可以用一句话概括：用 TypeScript 获得类型安全，用 React Ink 获得终端 UI 的组件化能力，用 Bun 获得启动速度和构建时优化。

TypeScript：应用层的语言

整个代码库由 1,902 个 TypeScript 源文件组成。TypeScript 的类型系统在 AI Agent 开发中有一个独特优势：工具的输入/输出 Schema 可以直接从类型定义生成，而这些 Schema 又直接成为发送给模型的 JSON Schema——类型定义、运行时验证和模型指令三者合一。

React Ink：终端 UI 框架

Claude Code 的交互界面不是传统的 readline REPL，而是一个完整的 React 应用。React Ink 将 React 的组件模型带入终端，使得复杂的 UI 状态管理（流式输出、多工具并行显示、权限对话框）可以用声明式的方式表达。主要的 UI 组件位于 restored-src/src/screens/REPL.tsx，它本身就是一个超过 5,000 行的 React 组件。

Bun：运行时与构建工具

Bun 在这里承担双重角色：

1. 运行时：比 Node.js 更快的启动速度，对 CLI 工具至关重要——用户期望输入 claude 后立即看到响应
2. 构建工具：通过 bun:bundle 提供的 feature() 函数实现编译时死代码消除（Dead Code Elimination, DCE），这是整个 Feature Flag 系统的基石

1.2 入口点分析：main.tsx 的启动编排

main.tsx 是整个应用的入口点，它的前 20 行代码就展示了一种经过深思熟虑的启动优化策略。

并行预取（Parallel Prefetch）

// restored-src/src/main.tsx:1-20
import { profileCheckpoint, profileReport } from './utils/startupProfiler.js';
profileCheckpoint('main_tsx_entry');

import { startMdmRawRead } from './utils/settings/mdm/rawRead.js';
startMdmRawRead();

import { ensureKeychainPrefetchCompleted, startKeychainPrefetch }
  from './utils/secureStorage/keychainPrefetch.js';
startKeychainPrefetch();

注意这里的代码组织方式：每个 import 后面紧跟一个立即执行的副作用调用（side-effect call）。源码注释（restored-src/src/main.tsx:1-8）明确解释了设计意图：

1. profileCheckpoint：在任何重量级模块求值开始前标记入口时间点
2. startMdmRawRead：启动 MDM（Mobile Device Management）子进程（macOS 上的 plutil / Windows 上的 reg query），使其与后续约 135ms 的 import 评估并行执行
3. startKeychainPrefetch：并行启动两个 macOS Keychain 读取操作（OAuth 令牌和旧版 API 密钥）——如果不做预取，isRemoteManagedSettingsEligible() 会通过同步 spawn 顺序读取，每次启动多花约 65ms

这三个操作遵循同一个模式：将 I/O 密集型操作提前到模块加载的“死时间“中并行执行。这不是偶然的优化——ESLint 注释 // eslint-disable-next-line custom-rules/no-top-level-side-effects 表明团队有一条自定义规则禁止顶层副作用，这里是经过审慎考虑后的豁免。

延迟导入（Lazy Import）

在并行预取之后，main.tsx 展示了第二种启动优化策略——条件性延迟导入：

// restored-src/src/main.tsx:69-81
const getTeammateUtils = () =>
  require('./utils/teammate.js') as typeof import('./utils/teammate.js');
const getTeammatePromptAddendum = () =>
  require('./utils/swarm/teammatePromptAddendum.js') as ...;

const coordinatorModeModule = feature('COORDINATOR_MODE')
  ? require('./coordinator/coordinatorMode.js') as ...
  : null;

const assistantModule = feature('KAIROS')
  ? require('./assistant/index.js') as ...
  : null;

这里有两种不同的延迟加载策略：

• 函数包装的 require（如 getTeammateUtils）：用于打破循环依赖（teammate.ts -> AppState.tsx -> ... -> main.tsx），每次调用时才解析模块
• Feature Flag 守卫的 require（如 coordinatorModeModule）：利用 Bun 的 feature() 实现构建时消除——当 COORDINATOR_MODE 为 false 时，整个 require 表达式及其导入的模块树都会在构建产物中被移除

Feature Flag 作为门控

从第 21 行开始，feature('...') 函数的身影贯穿整个入口文件：

// restored-src/src/main.tsx:21
import { feature } from 'bun:bundle';

这个来自 bun:bundle 的 feature() 函数是理解整个 Feature Flag 系统的关键。它不是运行时的条件判断——它是一个编译时常量。当 Bun 打包器处理 feature('X') 时，会根据构建配置将其替换为 true 或 false 字面量，然后 JavaScript 引擎的死代码消除会移除不可达的分支。注意 bun:bundle 的 feature() 并非 Bun 公开文档化的 API，而是 Anthropic 构建流水线中的定制条件编译机制。

1.3 三层架构

Claude Code 的架构可以分为三层，每一层有明确的职责边界。这个架构模型将在后续章节中反复引用——第3章的 Agent Loop 运行在应用层，第4章的工具执行编排跨越应用层和运行时层，第13-15章的缓存优化则涉及所有三层的协作。

graph TB
    subgraph L1["应用层 (Application Layer)"]
        direction TB
        TS["TypeScript 源码<br />1,902 个文件"]
        RI["React Ink<br />终端 UI 框架"]
        AL["Agent Loop<br />query.ts 状态机"]
        TL["工具系统<br />40+ 个工具"]
        SP["系统提示词<br />分段式组合"]

        TS --> RI
        TS --> AL
        TS --> TL
        TS --> SP

    subgraph L2["运行时层 (Runtime Layer)"]
        direction TB
        BUN["Bun 运行时<br />快速启动 + ESM"]
        ZIG["Zig 底层<br />Bun 内核"]
        BB["bun:bundle<br />feature() DCE"]
        JSC["JavaScriptCore<br />JS 引擎"]

        BUN --> ZIG
        BUN --> BB
        BUN --> JSC

    subgraph L3["外部依赖层 (External Dependencies)"]
        direction TB
        NPM["npm 包<br />commander, chalk, lodash-es..."]
        API["Anthropic API<br />模型调用 + 提示词缓存"]
        MCP["MCP Servers<br />外部工具扩展"]
        GB["GrowthBook<br />运行时 Feature Flag"]

        NPM --- API
        NPM --- MCP
        NPM --- GB

    L1 --> L2
    L2 --> L3

    style L1 fill:#e8f4f8,stroke:#2196F3,stroke-width:2px
    style L2 fill:#fff3e0,stroke:#FF9800,stroke-width:2px
    style L3 fill:#f3e5f5,stroke:#9C27B0,stroke-width:2px

应用层（TypeScript）

应用层是所有业务逻辑所在的地方。它包含：

• Agent Loop（query.ts）：核心状态机，编排“模型调用 → 工具执行 → 继续判定“的循环（详见第3章）
• 工具系统（tools.ts + tools/ 目录）：40+ 个工具的注册、权限检查和执行（详见第2章）
• 系统提示词（constants/prompts.ts）：分段式组合的提示词架构（详见第5章）
• React Ink UI（screens/REPL.tsx）：终端界面的声明式渲染

运行时层（Bun/Zig/JSC）

运行时层提供三个关键能力：

1. 快速启动：Bun 的启动速度比 Node.js 快数倍，对 CLI 工具体验至关重要
2. 构建时优化：bun:bundle 的 feature() 函数实现编译时 Feature Flag 消除
3. JavaScript 引擎：Bun 底层使用 JavaScriptCore（JSC，Safari 的 JS 引擎）而非 V8，配合 Zig 编写的底层运行时内核

外部依赖层

外部依赖层包括：

• npm 包：commander（CLI 参数解析）、chalk（终端着色）、lodash-es（实用函数）等
• Anthropic API：模型调用和提示词缓存（Prompt Cache）的服务端
• MCP Servers：Model Context Protocol 服务器，提供外部工具扩展能力
• GrowthBook：运行时 A/B 测试和 Feature Flag 服务

层间边界的意义

三层架构的关键在于层间的信息流方向：

• 应用层 → 运行时层：TypeScript 代码编译为 JavaScript，feature() 调用在此时被解析
• 运行时层 → 外部依赖层：HTTP 请求、npm 包加载、MCP 连接
• 外部依赖层 → 应用层：模型响应、工具结果、Feature Flag 值——这些信息向上穿透两层回到应用层

理解这个穿透路径很重要：当 GrowthBook 返回一个 tengu_* Feature Flag 的新值时，它影响的不是构建时的 feature() 函数（那些在构建时已经固化），而是运行时的条件逻辑。Claude Code 中存在两套并行的 Feature Flag 机制：构建时的 feature() 和运行时的 GrowthBook，它们服务于不同的目的（后面详述）。

1.4 为什么 “On Distribution” 很重要

“On distribution” 是理解 Claude Code 架构决策的一个关键概念。传统的 CLI 工具在开发时定义好所有功能，然后分发给用户。但 AI 编码 Agent 不同——它在被用户使用时，其行为由模型动态决定。

具体来说：

1. 模型选择工具：Agent Loop 的每次迭代中，模型决定调用哪个工具、传入什么参数。工具的 description 和 inputSchema 不仅是文档——它们是发送给模型的指令
2. 模型编写自己的工具：通过 BashTool，模型可以执行任意 shell 命令；通过 FileWriteTool，模型可以创建新文件；通过 SkillTool，模型可以加载和执行用户定义的提示词模板
3. 模型作用于自己的上下文：通过压缩（Compaction）、微压缩（Microcompact）和上下文折叠（Context Collapse），模型参与管理自己的上下文窗口

这意味着技术栈必须考虑一个传统软件不需要考虑的维度：模型作为运行时的一部分，它的行为不完全由代码控制，而是由提示词、工具描述和上下文共同塑造。

这就是为什么 Feature Flag 系统如此重要——它不仅控制代码路径，还控制模型能“看到“哪些工具。当 feature('WEB_BROWSER_TOOL') 为 false 时，WebBrowserTool 不仅不会被加载，它的整个模块树都从构建产物中消失，模型永远无法知道它的存在：

// restored-src/src/tools.ts:117-119
const WebBrowserTool = feature('WEB_BROWSER_TOOL')
  ? require('./tools/WebBrowserTool/WebBrowserTool.js').WebBrowserTool
  : null;

1.5 构建时死代码消除：feature() 的工作原理

feature() 函数来自 Bun 的打包器模块 bun:bundle，它在 Claude Code 中被大量使用来实现构建时的条件编译。

机制

当 Bun 的打包器遇到 feature('X') 调用时：

1. 查找构建配置中 X 的值
2. 将 feature('X') 替换为字面量 true 或 false
3. JavaScript 引擎的优化器识别出不可达分支并将其移除

这意味着以下代码：

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

在 PROACTIVE=false, KAIROS=false 的构建中会变成：

const SleepTool = false || false
  ? require('./tools/SleepTool/SleepTool.js').SleepTool
  : null;

进而被优化为 const SleepTool = null;，而 SleepTool.js 及其整个依赖树都不会出现在最终的 bundle 中。

使用模式

在 tools.ts 中，feature() 的使用呈现四种模式：单 Flag 守卫、多 Flag OR 组合、多 Flag AND 组合、数组展开。这些模式在 commands.ts 中同样出现（restored-src/src/commands.ts:59-100），用于控制 slash 命令的可用性。工具注册管线的完整分析详见第2章。

与运行时 Flag 的区别

Claude Code 中存在两套 Feature Flag 机制，容易混淆：

两者互补：feature() 用于“这个功能是否存在“，GrowthBook 用于“这个功能对哪些用户开放“。一个功能通常先由 feature() 守卫其模块加载，再由 GrowthBook 控制其运行时行为。

1.6 89 个 Feature Flag 全景

通过对源码中所有 feature('...') 调用的提取，我们得到 89 个构建时 Feature Flag。按功能分类如下：

从 Flag 看产品路线图

89 个 Feature Flag 不仅是技术实现细节，它们是产品路线图的投影：

• KAIROS 家族（6 个 Flag）：这是最大的 Flag 集群，指向一个完整的“助手模式“产品——后台自主运行、记忆整理、推送通知、GitHub Webhook 集成。这不是一个 CLI 工具的增强，而是一个完全不同的产品形态
• COORDINATOR_MODE + TEAMMEM + UDS_INBOX：多 Agent 协作的基础设施——Worker 分配、队友记忆、进程间通信
• BRIDGE_MODE + DAEMON + CCR_*：远程控制和分布式执行——将 Claude Code 从本地 CLI 扩展为可远程操控的 Agent 平台
• ULTRAPLAN + ULTRATHINK：模型推理能力的升级——更深层的计划和思考能力

1.7 工具注册管线：Feature Flag 的实战应用

tools.ts 的 getAllBaseTools() 函数（restored-src/src/tools.ts:193-251）是 Feature Flag 系统最集中的展示。它展示了三种不同的工具注册策略：

策略一：无条件注册

// restored-src/src/tools.ts:195-209
AgentTool,
TaskOutputTool,
BashTool,
FileReadTool,
FileEditTool,
FileWriteTool,

这些是核心工具，始终可用，无需任何条件。

策略二：构建时 Feature Flag 守卫

// restored-src/src/tools.ts:217-218
...(WebBrowserTool ? [WebBrowserTool] : []),

WebBrowserTool 在文件顶部通过 feature('WEB_BROWSER_TOOL') 守卫——如果 Flag 为 false，变量为 null，此处展开为空数组。整个工具的代码在构建产物中不存在。

策略三：运行时环境变量守卫

// restored-src/src/tools.ts:214-215
...(process.env.USER_TYPE === 'ant' ? [ConfigTool] : []),
...(process.env.USER_TYPE === 'ant' ? [TungstenTool] : []),

ConfigTool 和 TungstenTool 通过运行时环境变量 USER_TYPE 控制——它们的代码存在于构建产物中，但只对 Anthropic 内部用户（ant）可见。这是 A/B 测试的“暂存区“模式：在内部验证后再向外部用户开放。

策略四：运行时函数守卫

// restored-src/src/tools.ts:200-201
...(hasEmbeddedSearchTools() ? [] : [GlobTool, GrepTool]),

这是一个有趣的反向守卫：当 Bun 的单文件可执行中内嵌了搜索工具（bfs/ugrep）时，独立的 GlobTool 和 GrepTool 反而被移除——因为模型可以直接通过 BashTool 访问这些内嵌的快速工具。

1.8 模式提炼

从 Claude Code 的技术栈选择中，我们可以提炼出几个适用于所有 AI Agent 构建者的模式：

模式一：启动时间是 UX

CLI 工具的启动时间直接影响用户体验。Claude Code 通过三种手段优化启动：并行预取（I/O 与模块加载重叠）、延迟导入（按需加载）、构建时消除（减小 bundle 体积）。对于 AI Agent 来说，启动慢意味着用户在等待期间失去上下文，这比传统工具更糟糕。

模式二：双层 Feature Flag

构建时 Flag（feature()）和运行时 Flag（GrowthBook）服务于不同目的。前者控制代码的物理存在，后者控制行为的逻辑分支。在 AI Agent 中，这个区分尤为重要——构建时 Flag 决定模型能“看到“哪些工具（因为不存在的工具不会出现在 Schema 中），运行时 Flag 决定模型的行为参数（如 effort 级别、thinking 预算）。

模式三：模型感知的架构

传统软件的架构是为人类开发者设计的——API 边界、模块划分、抽象层次。AI Agent 的架构还需要为模型设计——工具描述是否清晰、Schema 是否自解释、提示词是否与代码行为一致。Claude Code 的三层架构中，应用层不仅是代码逻辑的组织，更是模型交互界面的组织。

模式四：失败关闭是默认值

工具系统中，工具默认标记为“不安全“（isReadOnly: false）和“不可并发“（isConcurrencySafe: false）。必须显式声明安全才能获得并发执行的优化。这个“失败关闭（fail closed）“原则贯穿整个架构——在 AI Agent 中，一个未经审查的工具调用可能修改用户的代码库，因此保守是正确的默认值。

本章小结

本章建立了理解 Claude Code 的基础框架：

1. 技术栈：TypeScript + React Ink + Bun 的组合，为类型安全、声明式 UI 和构建时优化服务
2. 入口点：main.tsx 通过并行预取、延迟导入和 Feature Flag 实现快速启动
3. 三层架构：应用层（TS）→ 运行时层（Bun/Zig/JSC）→ 外部依赖层（npm/API/MCP/GrowthBook），这是全书的参考框架
4. Feature Flag 系统：89 个构建时 Flag 通过 bun:bundle 的 feature() 实现死代码消除，与运行时 GrowthBook Flag 互补
5. On distribution：AI Agent 的行为由模型在运行时决定，技术栈必须为此设计

在下一章中，我们将深入工具系统——模型的“双手“——看看 40+ 个工具如何通过统一的接口契约、权限模型和 Feature Flag 守卫组成一个可扩展的能力体系。

第2章：工具系统 — 40+ 个工具作为模型的双手

为什么工具系统是 Claude Code 的核心

大语言模型的“思考“发生在文本空间，而软件工程的操作发生在文件系统、终端和网络中。工具系统是连接这两个世界的桥梁：它将模型的意图翻译为真实的副作用，再将副作用的结果翻译回模型可消费的文本。

Claude Code 的工具系统管理着 40+ 个内置工具和不限数量的 MCP 扩展工具。这些工具不是一个平铺的数组——它们经历了一条精密的管线：定义 → 注册 → 过滤 → 调用 → 渲染。每一步都有明确的契约。本章将从 Tool.ts 的接口定义开始，逐层拆解这条管线的设计决策。

2.1 Tool 接口契约

所有工具——无论是内置的 BashTool 还是通过 MCP 协议加载的第三方工具——都必须满足同一个 TypeScript 接口。这个接口定义在 restored-src/src/Tool.ts:362-695，是整个工具系统的基石。

核心字段一览

标注 * 的字段由 buildTool() 提供默认值，工具定义时可省略。

几个值得深究的设计选择：

description 是函数而非字符串。 同一个工具在不同的权限模式下可能需要不同的描述。例如，当用户配置了 alwaysDeny 规则禁止某些子命令时，工具描述可以主动告知模型“不要尝试这些操作“，从而在提示层面就避免无用的工具调用。

inputSchema 使用 Zod v4。 这让工具参数可以在运行时进行严格校验，同时通过 z.toJSONSchema() 自动生成发送给 Anthropic API 的 JSON Schema。Zod 的 z.strictObject() 确保模型不会传入未定义的参数。

call 接收 canUseTool 回调。 这是一个极其重要的设计——工具执行过程中可能需要递归地检查子操作的权限。例如 AgentTool 在启动子 Agent 时需要检查子 Agent 是否有权使用特定工具。权限检查不是一次性的门禁，而是贯穿执行过程的持续验证。

渲染契约：三组方法

Tool 接口中定义了一组渲染方法，它们构成了工具在终端 UI 中的完整生命周期表现（详见 2.5 节）：

renderToolUseMessage          // 工具被调用时展示
renderToolUseProgressMessage  // 工具执行中展示进度
renderToolResultMessage       // 工具执行完成后展示结果

此外还有 renderToolUseErrorMessage、renderToolUseRejectedMessage（权限被拒）和 renderGroupedToolUse（并行工具的分组展示）等可选方法。

2.2 buildTool() 工厂函数与失败关闭默认值

每一个具体工具都不是直接导出一个满足 Tool 接口的对象，而是通过 buildTool() 工厂函数构建。这个函数定义在 restored-src/src/Tool.ts:783-792：

      // export function buildTool<D extends AnyToolDef>(def: D): BuiltTool<D> {
  return {
    ...TOOL_DEFAULTS,
    userFacingName: () => def.name,
    ...def,
  } as BuiltTool<D>
}

运行时行为极简——就是一个对象展开（spread）。但它的类型层面设计（BuiltTool<D> 类型）精确地模拟了 { ...TOOL_DEFAULTS, ...def } 的语义：如果工具定义提供了某个方法，使用工具定义的版本；否则使用默认值。

默认值与“失败关闭“哲学

TOOL_DEFAULTS（restored-src/src/Tool.ts:757-769）的设计遵循一个安全原则——在不确定时假设最危险的情况：

其中最重要的两个默认值是 isConcurrencySafe: false 和 isReadOnly: false。这意味着：一个新工具如果忘记声明这两个属性，系统会自动将其视为“可能修改文件系统且不能并发执行“——这是最保守、最安全的假设。只有当工具开发者主动声明 isConcurrencySafe() { return true } 和 isReadOnly() { return true } 时，系统才会放宽限制。

实际工具如何使用 buildTool

以 GrepTool 为例（restored-src/src/tools/GrepTool/GrepTool.ts:160-194）：

export const GrepTool = buildTool({
  name: GREP_TOOL_NAME,
  searchHint: 'search file contents with regex (ripgrep)',
  maxResultSizeChars: 20_000,
  strict: true,
  // ...
  isConcurrencySafe() { return true },   // 搜索是安全的并发操作
  isReadOnly() { return true },           // 搜索不修改文件
  // ...
})

GrepTool 明确覆盖了两个默认值，因为搜索操作天然是只读且并发安全的。相比之下，BashTool（restored-src/src/tools/BashTool/BashTool.tsx:434-441）的并发安全性是有条件的：

isConcurrencySafe(input) {
  return this.isReadOnly?.(input) ?? false;
},
isReadOnly(input) {
  const compoundCommandHasCd = commandHasAnyCd(input.command);
  const result = checkReadOnlyConstraints(input, compoundCommandHasCd);
  return result.behavior === 'allow';
},

BashTool 只有在被判定为只读命令时才允许并发——一个 git status 可以并发执行，但 git push 不行。这种输入感知的并发控制是 buildTool 的方法签名接收 input 参数的原因。

2.3 工具注册管线：tools.ts

restored-src/src/tools.ts 是工具池（Tool Pool）的组装中心。它回答一个核心问题：在当前环境下，模型可以使用哪些工具？

三级过滤

工具从定义到最终可用，经历三级过滤：

第一级：编译期/启动期条件加载。 大量工具通过 Feature Flag 进行条件加载（restored-src/src/tools.ts:16-135）：

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

const cronTools = feature('AGENT_TRIGGERS')
  ? [
      require('./tools/ScheduleCronTool/CronCreateTool.js').CronCreateTool,
      require('./tools/ScheduleCronTool/CronDeleteTool.js').CronDeleteTool,
      require('./tools/ScheduleCronTool/CronListTool.js').CronListTool,
    ]
  : []

feature() 函数来自 bun:bundle，在打包时求值。这意味着未启用的工具根本不会出现在最终的 JavaScript bundle 中——这是一种比运行时 if 更彻底的死代码消除。

除了 Feature Flag，还有环境变量驱动的条件加载：

const REPLTool =
  process.env.USER_TYPE === 'ant'
    ? require('./tools/REPLTool/REPLTool.js').REPLTool
    : null

USER_TYPE === 'ant' 标记 Anthropic 内部员工使用的特殊工具（如 REPLTool、ConfigTool、TungstenTool），这些工具在公开版本中不可用。

第二级：getAllBaseTools() 组装基础工具池。 这个函数（restored-src/src/tools.ts:193-251）将所有通过第一级过滤的工具收集到一个数组中。它是系统的“工具注册表“——所有可能存在的工具都在这里登记。当前版本包含约 40+ 个内置工具，根据 Feature Flag 的启用情况动态增减。

      // export function getAllBaseTools(): Tools {
  return [
    AgentTool,
    TaskOutputTool,
    BashTool,
    ...(hasEmbeddedSearchTools() ? [] : [GlobTool, GrepTool]),
    FileReadTool,
    FileEditTool,
    FileWriteTool,
    // ... 省略 30+ 个工具
    ...(isToolSearchEnabledOptimistic() ? [ToolSearchTool] : []),
  ]
}

注意一个有趣的条件：hasEmbeddedSearchTools()。在 Anthropic 内部构建中，bfs（fast find）和 ugrep 被嵌入到 Bun 二进制文件中，此时 shell 里的 find 和 grep 已经被别名到这些快速工具，独立的 GlobTool 和 GrepTool 就变得多余了。

第三级：getTools() 运行时过滤。 这是最终的过滤层（restored-src/src/tools.ts:271-327），它执行三个操作：

1. 权限拒绝过滤：通过 filterToolsByDenyRules() 移除被 alwaysDeny 规则覆盖的工具。如果用户配置了 "Bash": "deny"，BashTool 在发送给模型的工具列表中根本不会出现。
2. REPL 模式隐藏：当 REPL 模式启用时，Bash、Read、Edit 等基础工具被隐藏——它们通过 REPLTool 的 VM 上下文间接暴露。
3. isEnabled() 最终检查：每个工具的 isEnabled() 方法是最后一道开关。

简单模式与完整模式

getTools() 还支持一种“简单模式“（CLAUDE_CODE_SIMPLE），只暴露 Bash、FileRead 和 FileEdit 三个核心工具。这在一些集成场景下很有用——减少工具数量可以降低 token 消耗并减少模型的决策负担。

MCP 工具的融合

最终的工具池由 assembleToolPool()（restored-src/src/tools.ts:345-367）完成组装：

      // export function assembleToolPool(
  permissionContext: ToolPermissionContext,
  mcpTools: Tools,
): Tools {
  const builtInTools = getTools(permissionContext)
  const allowedMcpTools = filterToolsByDenyRules(mcpTools, permissionContext)
  const byName = (a: Tool, b: Tool) => a.name.localeCompare(b.name)
  return uniqBy(
    [...builtInTools].sort(byName).concat(allowedMcpTools.sort(byName)),
    'name',
  )
}

这里有两个关键设计：

1. 内置工具优先：uniqBy 保留第一次出现的名称，内置工具排在前面，因此在名称冲突时内置工具胜出。
2. 按名称排序以稳定提示缓存：内置工具和 MCP 工具各自排序后拼接（而非混合排序），确保内置工具作为“连续前缀“出现。这与 API 服务端的缓存断点设计协作——如果 MCP 工具穿插在内置工具中间，任何 MCP 工具的增减都会导致所有下游缓存键失效。详见第13章。

2.4 工具结果大小预算

当一个工具返回结果时，系统面临一个核心矛盾：模型需要看到完整的信息来做出正确决策，但上下文窗口是有限的。Claude Code 通过两级预算解决这个问题。

第一级：单工具结果上限 maxResultSizeChars

每个工具通过 maxResultSizeChars 字段声明自己的结果大小上限。超出此上限的结果会被持久化到磁盘，模型只看到一个预览（preview）加上磁盘文件路径。

以下是不同工具的 maxResultSizeChars 对比：

FileReadTool 的 maxResultSizeChars: Infinity 是一个特殊设计——避免 Read → 持久化文件 → Read 的循环引用。系统还有一个全局上限 DEFAULT_MAX_RESULT_SIZE_CHARS = 50,000（restored-src/src/constants/toolLimits.ts:13），作为无论工具声明什么值都生效的硬顶。

第二级：单消息聚合上限

当模型在一个回合中并行调用多个工具时，所有工具结果会作为同一个 user message 的多个 tool_result 块发送。MAX_TOOL_RESULTS_PER_MESSAGE_CHARS = 200,000（restored-src/src/constants/toolLimits.ts:49）限制了单条消息的工具结果总大小，防止 N 个并行工具集体挤爆上下文窗口。

FileReadTool Infinity 设计理由、per-message 预算的持久化实现细节（包括 ContentReplacementState 决策持久性和 Infinity 豁免机制）详见第4章。

大小预算参数汇总

2.5 三阶段渲染流程

工具在终端 UI 中的呈现不是一次性的，而是一个三阶段渐进过程。这三个阶段与工具执行的生命周期一一对应。

流程图

flowchart TD
    A["模型发出 tool_use 块<br />（参数可能尚未流式完毕）"] --> B
    B["阶段 1: renderToolUseMessage<br />工具被调用，显示名称和参数<br />参数是 Partial&lt;Input&gt;（流式传输中）"]
    B -->|工具开始执行| C
    C["阶段 2: renderToolUseProgressMessage<br />执行中，展示进度<br />通过 onProgress 回调更新"]
    C -->|工具执行完成| D
    D["阶段 3: renderToolResultMessage<br />完成，展示结果"]

阶段 1：renderToolUseMessage — 意图展示

当模型输出一个 tool_use 块时，这个方法立即被调用。注意其签名中的关键类型：

renderToolUseMessage(
  input: Partial<z.infer<Input>>,  // 注意是 Partial!
  options: { theme: ThemeName; verbose: boolean; commands?: Command[] },
): React.ReactNode

input 是 Partial 的原因是：API 以流式方式返回工具参数的 JSON，在 JSON 解析完成之前只有部分字段可用。UI 必须在参数不完整时就能渲染——用户不应该看到空白屏幕。

以 BashTool 为例，即使 command 字段尚未完全接收，UI 已经可以显示 “Bash” 标签和已接收的部分命令文本。

阶段 2：renderToolUseProgressMessage — 过程可见性

这是一个可选方法。对于执行时间较长的工具（如 BashTool、AgentTool），进度反馈至关重要。BashTool 在 shell 命令执行超过 2 秒后开始显示进度（PROGRESS_THRESHOLD_MS = 2000，restored-src/src/tools/BashTool/BashTool.tsx:55）。

进度通过 onProgress 回调传递。每个工具的进度数据结构不同——BashTool 的 BashProgress 包含 stdout/stderr 片段，AgentTool 的 AgentToolProgress 包含子 Agent 的消息流。这些类型在 restored-src/src/types/tools.ts 中统一定义，通过 ToolProgressData 联合类型约束。

阶段 3：renderToolResultMessage — 结果呈现

这也是一个可选方法——省略时工具结果不在终端渲染（例如 TodoWriteTool 的结果通过专用面板展示，不出现在对话流中）。

renderToolResultMessage 接收 style?: 'condensed' 选项。在非 verbose 模式下，搜索类工具（GrepTool、GlobTool）显示精简摘要（如 “Found 42 files across 3 directories”），而在 verbose 模式下展示完整结果。工具可以通过 isResultTruncated(output) 方法告诉 UI 当前结果是否被截断，从而在全屏模式下启用“点击展开“交互。

分组渲染：renderGroupedToolUse

当模型在一个回合中并行调用多个同类型工具时（例如 5 个 Grep 搜索），逐个渲染会占据大量屏幕空间。renderGroupedToolUse 方法允许工具将多个并行调用合并为一个紧凑的分组视图——例如 “Searched 5 patterns, found 127 results across 34 files”。

这个方法只在非 verbose 模式下生效。verbose 模式下每个工具调用仍然在其原始位置独立渲染，确保调试时信息不丢失。

2.6 从具体工具看设计模式

BashTool：最复杂的工具

BashTool（restored-src/src/tools/BashTool/BashTool.tsx）是整个工具系统中最复杂的单一工具，因为 shell 命令的语义空间是无限的。它需要：

• 解析命令结构来判断是否只读（通过 checkReadOnlyConstraints 和 parseForSecurity）
• 感知管道和复合命令（ls && echo "---" && ls 仍然是只读的）
• 条件性并发：只有只读命令才能并发执行
• 进度追踪：超过 2 秒的命令显示 stdout 流式输出
• 文件变更追踪：通过 fileHistoryTrackEdit 和 trackGitOperations 记录 shell 命令导致的文件修改
• 沙箱执行：在某些条件下通过 SandboxManager 隔离执行

BashTool 的 maxResultSizeChars 设为 30,000——比 GrepTool 的 20,000 宽松，因为 shell 输出通常包含更多结构化信息（编译错误、测试结果等），模型需要看到足够的上下文才能做出正确判断。

GrepTool：并发安全的典范

GrepTool 的设计相对简洁。它无条件声明 isConcurrencySafe: true 和 isReadOnly: true，因为搜索操作永远不会修改文件系统。它的 maxResultSizeChars 设为 20,000——搜索结果超过这个长度说明模型的搜索范围太宽，持久化到磁盘并返回预览反而有助于模型调整策略。

FileReadTool：Infinity 的哲学

FileReadTool 将 maxResultSizeChars 设为 Infinity，选择通过自身的 maxTokens 和 maxSizeBytes 限制来控制输出大小。这避免了前文提到的循环读取问题，也意味着 FileReadTool 的结果永远不会被替换为磁盘引用——模型总是能直接看到文件内容。

2.7 延迟加载与 ToolSearch

当工具数量超过一定阈值时（尤其是 MCP 工具大量接入后），将所有工具的完整 schema 发送给模型会消耗大量 token。Claude Code 通过延迟加载（Deferred Loading）机制解决这个问题。

标记了 shouldDefer: true 的工具在初始提示中只发送工具名称（defer_loading: true），不发送完整的参数 schema。模型需要先调用 ToolSearchTool 按关键词搜索并获取工具的完整定义后，才能调用这些延迟加载的工具。

每个工具的 searchHint 字段就是为此设计的——它提供 3-10 个词的能力描述，帮助 ToolSearchTool 进行关键词匹配。例如 GrepTool 的 searchHint 是 'search file contents with regex (ripgrep)'。

标记了 alwaysLoad: true 的工具则永远不会被延迟——它们的完整 schema 总是出现在初始提示中。这适用于模型在第一轮对话就必须能直接调用的核心工具。

2.8 模式提炼

从 Claude Code 的工具系统设计中，可以提炼出几个对 AI Agent 构建者普遍有价值的模式：

模式 1：失败关闭的默认值。 buildTool() 的默认值假设最危险的情况（不可并发、非只读），工具开发者必须主动声明安全属性。这将安全从“选择加入“翻转为“选择退出“，大幅降低了遗漏导致的风险。

模式 2：分层预算控制。 单工具结果有上限，单消息也有聚合上限。两层控制互相补充——单工具上限防止单点失控，消息上限防止并行调用的集体爆炸。

模式 3：输入感知的属性。 isConcurrencySafe(input) 和 isReadOnly(input) 接收工具输入，而非全局判断。同一个 BashTool，ls 和 rm 有完全不同的安全属性。这种细粒度的输入感知是实现精确权限控制的基础。详见第4章。

模式 4：渐进渲染。 三阶段渲染（意图 → 进度 → 结果）让用户在工具执行的每个阶段都有可见性。Partial<Input> 的设计确保即使在参数流式传输期间，UI 也不会空白。这对用户信任至关重要——用户需要知道 Agent 正在做什么，而不是盯着一个旋转的加载图标。

模式 5：编译期消除 vs 运行时过滤。 Feature Flag 通过 bun:bundle 的 feature() 在编译期消除未启用的工具代码，而权限规则在运行时过滤工具列表。两种机制服务不同目的：前者减小 bundle 体积和攻击面，后者支持用户级配置。

用户能做什么

基于 Claude Code 工具系统的设计经验，以下是构建自己的 AI Agent 工具系统时可以采取的行动：

• 采用“失败关闭“默认值。 在你的工具注册框架中，将 isConcurrencySafe、isReadOnly 等安全属性的默认值设为最保守的选项。让工具开发者主动声明安全属性，而非默认假设安全。
• 为每个工具设置结果大小上限。 不要让工具返回无限大的结果。设置单工具上限（如 maxResultSizeChars）和单消息聚合上限，超出时持久化到磁盘并返回预览。
• 让工具描述成为函数而非静态字符串。 如果你的工具在不同权限模式或上下文下有不同的行为限制，动态生成描述可以在提示层面引导模型避免无效调用。
• 实现三阶段渲染。 为长时间运行的工具提供进度反馈（意图展示 → 执行进度 → 最终结果），让用户始终知道 Agent 在做什么。支持 Partial<Input> 在参数流式传输期间也能渲染。
• 使用条件加载减少工具集。 通过 Feature Flag 或环境变量在编译期/启动期过滤不需要的工具，减少 token 消耗和模型决策负担。对于大量 MCP 工具场景，考虑延迟加载（deferred loading）机制。
• 工具排序要稳定。 如果你使用 API 提示缓存，确保工具列表的顺序在请求之间保持稳定。将内置工具作为连续前缀，MCP 工具按名称排序追加，避免缓存键频繁失效。

小结

Claude Code 的工具系统是一个精心分层的架构：Tool 接口定义契约，buildTool() 提供安全默认值，tools.ts 的注册管线通过编译期和运行时两级过滤组装工具池，大小预算机制在单工具和单消息两个层面控制上下文消耗，三阶段渲染让工具执行过程对用户完全透明。

这套系统的设计哲学可以用一句话总结：让正确的事情容易，让危险的事情困难。 buildTool() 的失败关闭默认值让“忘记声明安全属性“成为一个安全的错误；分层预算让“工具返回过多数据“成为一个可控的降级；条件加载让“添加实验性工具“成为一个零风险的操作。

工具的调用和编排——包括权限检查的完整流程、并发执行的调度策略、流式进度的传播机制——将在第4章详细展开。

第3章：Agent Loop — 从用户输入到模型响应的完整生命周期

“A loop is not a loop when every iteration reshapes the world it runs in.”

本章是全书的锚点。从第5章的 API 调用构建到第9章的自动压缩策略，从第13章的流式响应处理到第16章的权限检查体系——几乎所有后续章节讨论的子系统，最终都在 queryLoop() 这个核心循环中被编排、协调、驱动。理解这个循环，就是理解 Claude Code 作为 AI Agent 的运转心脏。

3.1 为什么 Agent Loop 不是简单的 REPL

传统的 REPL（Read-Eval-Print Loop）是一个无状态的三步循环：读取输入、求值、打印结果。每次迭代之间没有上下文传递，没有自动恢复，没有对自身状态的感知。

Agent Loop 根本不同。看这张对比表：

Agent Loop 的每一次迭代都可能改变自身的运行条件：压缩会缩减消息数组，模型降级会切换推理后端，stop hook 会注入新的约束消息。这不是循环——这是一个自修改状态机（self-modifying state machine）。

3.2 queryLoop 状态机总览

3.2.1 入口：query() 与 queryLoop()

入口函数 query() 是一个薄包装器。它调用 queryLoop() 获得结果，然后通知所有已消费的命令完成生命周期：

restored-src/src/query.ts:219-238

export async function* query(params: QueryParams): AsyncGenerator<...> {
  const consumedCommandUuids: string[] = []
  const terminal = yield* queryLoop(params, consumedCommandUuids)
  for (const uuid of consumedCommandUuids) {
    notifyCommandLifecycle(uuid, 'completed')
  }
  return terminal
}

真正的状态机在 queryLoop() 中（restored-src/src/query.ts:241）。它是一个 while (true) 循环，每次迭代通过 state = next; continue 进入下一轮，或通过 return { reason: '...' } 终止。

3.2.2 State 类型：跨迭代的可变状态

State 类型定义了循环在迭代之间需要携带的所有可变状态（restored-src/src/query.ts:204-217）：

注意设计上的一个关键决策：源码注释明确说明“Continue sites write state = { ... } instead of 9 separate assignments“（restored-src/src/query.ts:267）。这意味着每个继续点都必须显式构造完整的 State 对象。这种写法消除了“忘记重置某个字段“的 bug 类——在一个有 7 个继续点的循环中，这不是理论风险，而是必然会发生的事故。

3.2.3 Continue 转换类型

循环内部有 7 个 continue 站点，每个都记录了转换原因。从源码中提取的完整枚举：

3.2.4 Terminal 终止原因

循环通过 return 终止，返回值包含 reason 字段。从源码提取的完整枚举：

下面的流程图展示了状态机的完整拓扑：

flowchart TD
    Entry["queryLoop() Entry<br />初始化 State, budgetTracker, config"] --> Loop

    subgraph Loop["while (true)"]
        direction TB
        Start["解构 state<br />yield stream_request_start"] --> Phase1
        Phase1["阶段 1: 上下文预处理<br />applyToolResultBudget → snipCompact<br />→ microcompact → contextCollapse<br />→ autocompact"] --> Phase2
        Phase2{"阶段 2: Blocking limit<br />token 数 > 硬限制?"}
        Phase2 -->|YES| T_Blocking["return blocking_limit"]
        Phase2 -->|NO| Phase3
        Phase3["阶段 3: API 调用<br />callModel + attemptWithFallback<br />流式响应 → assistantMessages + toolUseBlocks"] --> Phase4
        Phase4{"阶段 4: 中断检查<br />aborted?"}
        Phase4 -->|YES| T_Aborted["return aborted_*"]
        Phase4 -->|NO| Branch
        Branch{"needsFollowUp?"}
        Branch -->|"false（无 tool_use）"| Phase5
        Branch -->|"true（有 tool_use）"| Phase6

        Phase5["阶段 5: 恢复与终止判定<br />prompt-too-long → collapse drain / reactive compact<br />max_output_tokens → escalate / recovery x3<br />stop hooks → blocking errors 注入<br />token budget → nudge 继续"]
        Phase5 -->|恢复成功| Continue1["state = next; continue"]
        Phase5 -->|全部耗尽| T_Completed["return completed"]

        Phase6["阶段 6: 工具执行<br />StreamingToolExecutor / runTools"] --> Phase7
        Phase7["阶段 7: 附件注入<br />memory prefetch / skill discovery / commands"] --> Phase8
        Phase8{"阶段 8: 继续判定<br />maxTurns?"}
        Phase8 -->|未达上限| Continue2["state = next_turn; continue"]
        Phase8 -->|达到上限| T_MaxTurns["return max_turns"]

    Continue1 --> Start
    Continue2 --> Start

以下是原始 ASCII 版本，供需要纯文本阅读环境的读者参考：

┌──────────────────────────────────────────────────────────────────────┐
│                        queryLoop() Entry                            │
│  初始化 State, budgetTracker, config, pendingMemoryPrefetch         │
└──────────────┬───────────────────────────────────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────────────┐
│              while (true) {                      │
│  解构 state → messages, toolUseContext, ...       │
│  yield { type: 'stream_request_start' }          │
├──────────────────────────────────────────────────┤
│                                                  │
│  ┌─────────────────────────────────────────┐     │
│  │ 阶段 1: 上下文预处理                      │     │
│  │ applyToolResultBudget                    │     │
│  │ → snipCompact (HISTORY_SNIP)             │     │
│  │ → microcompact                           │     │
│  │ → contextCollapse (CONTEXT_COLLAPSE)     │     │
│  │ → autocompact ───── 详见第9章 ──────────  │     │
│  └──────────────┬──────────────────────────┘     │
│                 │                                 │
│                 ▼                                 │
│  ┌─────────────────────────────────────────┐     │
│  │ 阶段 2: Blocking limit 检查              │     │
│  │ token 数 > 硬限制 ?                      │     │
│  │   YES → return {reason:'blocking_limit'} │     │
│  └──────────────┬──────────────────────────┘     │
│                 │ NO                              │
│                 ▼                                 │
│  ┌─────────────────────────────────────────┐     │
│  │ 阶段 3: API 调用 ── 详见第5章和第13章 ──  │     │
│  │ attemptWithFallback 循环                  │     │
│  │ callModel({                              │     │
│  │   messages: prependUserContext(...)       │     │
│  │   systemPrompt: appendSystemContext(...) │     │
│  │ })                                       │     │
│  │                                          │     │
│  │ 流式响应 → assistantMessages[]           │     │
│  │         → toolUseBlocks[]                │     │
│  │ FallbackTriggeredError → 切换模型重试     │     │
│  └──────────────┬──────────────────────────┘     │
│                 │                                 │
│                 ▼                                 │
│  ┌─────────────────────────────────────────┐     │
│  │ 阶段 4: 中断检查                         │     │
│  │ abortController.signal.aborted ?        │     │
│  │   YES → return {reason:'aborted_*'}     │     │
│  └──────────────┬──────────────────────────┘     │
│                 │ NO                              │
│                 ▼                                 │
│  ┌─────────────────────────────────────────┐     │
│  │ 阶段 5: needsFollowUp == false 分支      │     │
│  │ (模型未返回 tool_use)                    │     │
│  │                                          │     │
│  │ ┌─ prompt-too-long 恢复 ──────────────┐ │     │
│  │ │ collapse drain → reactive compact   │ │     │
│  │ │ 成功 → state=next; continue         │ │     │
│  │ └────────────────────────────────────-┘ │     │
│  │ ┌─ max_output_tokens 恢复 ────────────┐ │     │
│  │ │ escalate(8k→64k) → recovery(×3)    │ │     │
│  │ │ 成功 → state=next; continue         │ │     │
│  │ └────────────────────────────────────-┘ │     │
│  │ ┌─ stop hooks ── 详见第16章 ──────────┐ │     │
│  │ │ blockingErrors → state=next;continue│ │     │
│  │ └────────────────────────────────────-┘ │     │
│  │ ┌─ token budget check ────────────────┐ │     │
│  │ │ budget未尽 → state=next; continue   │ │     │
│  │ └────────────────────────────────────-┘ │     │
│  │                                          │     │
│  │ return { reason: 'completed' }           │     │
│  └──────────────────────────────────────-──┘     │
│                 │                                 │
│           needsFollowUp == true                  │
│                 │                                 │
│                 ▼                                 │
│  ┌─────────────────────────────────────────┐     │
│  │ 阶段 6: 工具执行                         │     │
│  │ streamingToolExecutor.getRemainingResults│     │
│  │ 或 runTools() ── 详见第4章(工具执行编排) ─ │     │
│  │ → toolResults[]                         │     │
│  └──────────────┬──────────────────────────┘     │
│                 │                                 │
│                 ▼                                 │
│  ┌─────────────────────────────────────────┐     │
│  │ 阶段 7: 附件注入                         │     │
│  │ getAttachmentMessages()                 │     │
│  │ pendingMemoryPrefetch consume           │     │
│  │ skillDiscoveryPrefetch consume          │     │
│  │ queuedCommands drain                    │     │
│  └──────────────┬──────────────────────────┘     │
│                 │                                 │
│                 ▼                                 │
│  ┌─────────────────────────────────────────┐     │
│  │ 阶段 8: 继续判定                         │     │
│  │ maxTurns check                          │     │
│  │ state = { reason: 'next_turn', ... }    │     │
│  │ continue                                │     │
│  └─────────────────────────────────────────┘     │
│                                                  │
└──────────────────────────────────────────────────┘

3.3 单次迭代的完整流程

让我们跟踪一次迭代的每个阶段，从头到尾。

3.3.1 上下文预处理管线

每次迭代开始时，原始 messages 数组要经过四到五级处理才能送往 API。这些阶段按严格顺序执行，且顺序不可互换。

第一级：工具结果预算裁剪（Tool Result Budget）

restored-src/src/query.ts:379-394

applyToolResultBudget() 对聚合工具结果施加大小限制。它在所有压缩阶段之前运行，因为后续的 cached microcompact 仅通过 tool_use_id 操作，不检查内容——先裁剪内容不会干扰它。

第二级：History Snip

restored-src/src/query.ts:401-410

snipCompactIfNeeded() 是一种轻量级压缩：它截断（snip）历史中的旧消息，释放 token 空间。关键的是，它返回 tokensFreed 值——这个值会被传递给 autocompact，让后者的阈值判断能感知 snip 已经释放的空间。

第三级：Microcompact

restored-src/src/query.ts:414-426

Microcompact 是一种细粒度压缩，在 autocompact 之前运行。它还支持一种“缓存编辑“模式（CACHED_MICROCOMPACT），利用 API 的 cache 删除机制实现零额外 API 调用的压缩。

第四级：Context Collapse

restored-src/src/query.ts:440-447

Context Collapse（上下文折叠）是一种读时投影（read-time projection）机制。源码注释揭示了一个精妙的设计：

“Nothing is yielded — the collapsed view is a read-time projection over the REPL’s full history. Summary messages live in the collapse store, not the REPL array.”（restored-src/src/query.ts:434-436）

这意味着折叠不改变原始消息数组，而是在每次迭代时重新投影。折叠结果通过 state.messages 在继续点传递，下一次 projectView() 因为归档消息已经不在输入中而成为空操作。

第五级：Autocompact（详见第9章）

restored-src/src/query.ts:454-468

自动压缩是最重量级的预处理步骤。它在 context collapse 之后运行——如果折叠已经把 token 数降到阈值以下，autocompact 就成为空操作，保留了更细粒度的上下文而不是生成单一摘要。

这五级管线的设计遵循一个原则：从轻到重、从局部到全局。每一级都试图在不丢失太多信息的前提下释放空间，只有前面的级别不够时，后面的级别才会启动。

3.3.2 上下文注入：prependUserContext 与 appendSystemContext

消息预处理完成后，上下文通过两个函数注入到 API 请求中：

appendSystemContext（restored-src/src/utils/api.ts:437-447）：

      // export function appendSystemContext(
  systemPrompt: SystemPrompt,
  context: { [k: string]: string },
): string[] {
  return [
    ...systemPrompt,
    Object.entries(context)
      .map(([key, value]) => `${key}: ${value}`)
      .join('\n'),
  ].filter(Boolean)
}

系统上下文被追加到系统提示词（system prompt）的末尾。这些内容（如当前日期、工作目录等）享受系统提示词的特殊缓存位置——API 的 prompt caching 对系统提示词最为友好。

prependUserContext（restored-src/src/utils/api.ts:449-474）：

      // export function prependUserContext(
  messages: Message[],
  context: { [k: string]: string },
): Message[] {
  // ...
  return [
    createUserMessage({
      content: `<system-reminder>\n...\n</system-reminder>\n`,
      isMeta: true,
    }),
    ...messages,
  ]
}

用户上下文被包裹在 <system-reminder> 标签中，作为第一条用户消息前置到消息数组。这个位置选择不是随意的——它确保上下文出现在所有对话之前，且标记为 isMeta: true（不显示在用户 UI 中）。附带一句重要的提示文本：“this context may or may not be relevant to your tasks”——这给了模型忽略不相关上下文的自由度。

注意调用时序（restored-src/src/query.ts:660）：

messages: prependUserContext(messagesForQuery, userContext),
systemPrompt: fullSystemPrompt,  // 已经 appendSystemContext 过

prependUserContext 在 API 调用时才执行，不在预处理管线中。这意味着用户上下文不参与 token 计数和压缩决策——它是“透明的“注入。

3.3.3 消息标准化管线

在 API 调用的构建阶段（restored-src/src/services/api/claude.ts:1259-1314），消息经过一条四步标准化管线。这条管线的职责是将 Claude Code 内部的丰富消息类型转换为 Anthropic API 能接受的严格格式。

第一步：normalizeMessagesForAPI()（restored-src/src/utils/messages.ts:1989）

这是最复杂的标准化步骤。它完成以下工作：

1. 附件重排序：通过 reorderAttachmentsForAPI() 将附件消息上移，直到碰到 tool_result 或 assistant 消息
2. 虚拟消息过滤：移除 isVirtual 标记的显示专用消息（如 REPL 内部工具调用）
3. 系统/进度消息剥离：过滤 progress 类型和非 local_command 的 system 消息
4. 合成错误消息处理：检测 PDF/图片/请求过大的错误，向后查找并从源用户消息中剥离对应的媒体块
5. 工具输入标准化：通过 normalizeToolInputForAPI 处理工具输入格式
6. 消息合并：相邻的同角色消息被合并（API 要求严格的 user/assistant 交替）

第二步：ensureToolResultPairing()（restored-src/src/utils/messages.ts:5133）

修复 tool_use / tool_result 的配对不匹配。这种不匹配在恢复远程会话（remote/teleport sessions）时特别常见。它为孤立的 tool_use 插入合成错误 tool_result，并剥离引用不存在 tool_use 的孤立 tool_result。

第三步：stripAdvisorBlocks()（restored-src/src/utils/messages.ts:5466）

剥离 advisor blocks。这些 block 需要特定的 beta header 才能被 API 接受（restored-src/src/services/api/claude.ts:1304）：

if (!betas.includes(ADVISOR_BETA_HEADER)) {
  messagesForAPI = stripAdvisorBlocks(messagesForAPI)
}

第四步：stripExcessMediaItems()（restored-src/src/services/api/claude.ts:956）

API 限制每个请求最多 100 个媒体项（图片 + 文档）。这个函数静默地从最旧的消息开始移除多余的媒体项，而不是报错——这在 Cowork/CCD 等场景中很重要，因为硬报错难以恢复。

整条管线的执行顺序不是随意的。源码注释解释了为什么标准化要在 ensureToolResultPairing 之前（restored-src/src/services/api/claude.ts:1272-1276）：

“normalizeMessagesForAPI uses isToolSearchEnabledNoModelCheck() because it’s called from ~20 places (analytics, feedback, sharing, etc.), many of which don’t have model context.”

这揭示了一个架构事实：normalizeMessagesForAPI 是一个被广泛复用的函数，它的接口不能随意添加参数。模型特定的后处理（如 tool search 字段剥离）必须作为独立步骤在它之后运行。

3.3.4 API 调用阶段（详见第5章和第13章）

API 调用被包裹在一个 attemptWithFallback 循环中（restored-src/src/query.ts:650-953）：

let attemptWithFallback = true
while (attemptWithFallback) {
  attemptWithFallback = false
  try {
    for await (const message of deps.callModel({
      messages: prependUserContext(messagesForQuery, userContext),
      systemPrompt: fullSystemPrompt,
      // ...
    })) {
      // 处理流式响应消息
    }
  } catch (innerError) {
    if (innerError instanceof FallbackTriggeredError && fallbackModel) {
      currentModel = fallbackModel
      attemptWithFallback = true
      // 清理孤立消息, 重置 executor
      continue
    }
    throw innerError
  }
}

这里有几个精妙的设计值得注意：

消息不可变性。流式消息在 yield 前被克隆：原始 message 推入 assistantMessages 数组（回传给 API），而克隆版本（带 backfilled observable input）被 yield 给 SDK 调用者。源码注释（restored-src/src/query.ts:744-746）直接说明了原因：“mutating it would break prompt caching (byte mismatch)”。

错误扣留（Withholding）机制。可恢复的错误（prompt-too-long、max-output-tokens、media-size）在流式阶段被扣留——不立即 yield 给调用者。只有在后续的恢复逻辑确认无法恢复时，才会释放给调用者。这防止了 SDK 消费者（如 Desktop/Cowork）过早终止会话。

Tombstone 处理。当流式降级（streaming fallback）发生时，已经 yield 的部分消息会被作为 tombstone 通知删除（restored-src/src/query.ts:716-718）。这解决了一个微妙的问题：部分消息（尤其是 thinking blocks）携带的签名在降级后会导致 API 报 “thinking blocks cannot be modified” 错误。

3.3.5 工具执行阶段（详见第4章）

模型响应完成后，如果存在 tool_use blocks，循环进入工具执行阶段（restored-src/src/query.ts:1363-1408）。

Claude Code 支持两种工具执行模式：

1. 流式并行执行（StreamingToolExecutor）：工具在模型流式响应过程中就开始执行。在 API 调用阶段，每个 tool_use block 到达时就被 addTool() 推入执行器（restored-src/src/query.ts:841-843）。流式结束后，getRemainingResults() 收集所有已完成和未完成的结果。
2. 批量执行（runTools()）：所有 tool_use blocks 收集完毕后一次性执行。

工具执行的结果会经过 normalizeMessagesForAPI 标准化后追加到 toolResults 数组。

3.3.6 Stop Hooks 与继续判定

当模型响应不包含 tool_use（needsFollowUp == false）时，循环进入终止判定路径。这条路径包含多层恢复逻辑和 hook 检查。

Stop Hooks（restored-src/src/query.ts:1267-1306）：

const stopHookResult = yield* handleStopHooks(
  messagesForQuery, assistantMessages,
  systemPrompt, userContext, systemContext,
  toolUseContext, querySource, stopHookActive,
)

如果 stop hook 返回 blockingErrors，循环注入这些错误消息并继续（transition: { reason: 'stop_hook_blocking' }），让模型有机会修正。这是 Claude Code 权限体系的关键执行点——详见第16章。

Token Budget Check（restored-src/src/query.ts:1308-1355）：

当 TOKEN_BUDGET 特性开启时，循环检查当前轮次的 token 消耗是否在预算内。如果模型“提前完成“但预算还有剩余，循环注入 nudge 消息（transition: { reason: 'token_budget_continuation' }）鼓励模型继续工作。这个机制还支持“递减回报“（diminishing returns）检测——如果模型的增量输出不再有实质贡献，即使预算未耗尽也会提前停止。

3.3.7 附件注入与轮次准备

工具执行完成后，循环在进入下一轮之前注入附件（restored-src/src/query.ts:1580-1628）：

1. 队列命令处理：从全局命令队列中拉取当前 agent 地址的命令（区分主线程和子 agent），转换为附件消息
2. Memory prefetch 消费：如果内存预取（在循环入口启动的 startRelevantMemoryPrefetch）已完成且本轮尚未消费，将结果注入
3. Skill discovery 消费：如果技能发现预取已完成，将结果注入

这些注入利用了模型流式响应和工具执行的延迟——它们在后台并行运行，到这里时通常已经完成。

3.4 中止/重试/降级

3.4.1 FallbackTriggeredError 与模型切换

当 API 调用因高负载等原因失败时，FallbackTriggeredError 被抛出（restored-src/src/query.ts:894-950）。处理流程：

1. 切换 currentModel 为 fallbackModel
2. 清空 assistantMessages、toolResults、toolUseBlocks
3. 丢弃并重建 StreamingToolExecutor（防止孤立 tool_result 泄漏）
4. 更新 toolUseContext.options.mainLoopModel
5. 剥离 thinking signature blocks（因为它们是模型绑定的，在降级模型上会 400）
6. yield 系统消息通知用户

关键的是，这个降级发生在 attemptWithFallback 循环内部。它设置 attemptWithFallback = true 并 continue，在同一轮迭代中立即重试——不需要重新进入外部的 while (true) 循环。

3.4.2 max_output_tokens 恢复：三次机会

当模型输出被截断时，恢复策略分两层：

第一层：Escalation（升级）。如果当前使用的是默认的 8k 上限且尚未覆盖过，直接将 maxOutputTokensOverride 设为 64k（ESCALATED_MAX_TOKENS），原样重试同一请求。这是“免费“的恢复——不需要多轮对话。

第二层：Multi-turn recovery（多轮恢复）。如果升级后仍然截断，注入一条元消息：

"Output token limit hit. Resume directly — no apology, no recap of what you were doing.
Pick up mid-thought if that is where the cut happened.
Break remaining work into smaller pieces."

这条消息精心措辞：禁止道歉（浪费 token）、禁止回顾（重复信息）、要求拆分工作（降低单次输出需求）。最多重试 3 次（MAX_OUTPUT_TOKENS_RECOVERY_LIMIT，restored-src/src/query.ts:164）。

3.4.3 Reactive Compact：prompt-too-long 的最后防线

当 API 返回 prompt-too-long 错误时，恢复策略也分两层：

1. Context Collapse Drain：首先尝试提交所有暂存的 context collapse。这是廉价操作，保留了细粒度上下文
2. Reactive Compact：如果 drain 不够，执行完整的 reactive compact。标记 hasAttemptedReactiveCompact = true 防止重试死循环

如果两者都失败，错误被释放给调用者，循环终止。源码注释特别强调了为什么不能在这里运行 stop hooks（restored-src/src/query.ts:1169-1172）：

“Do NOT fall through to stop hooks: the model never produced a valid response, so hooks have nothing meaningful to evaluate. Running stop hooks on prompt-too-long creates a death spiral: error → hook blocking → retry → error → …”

3.5 单次迭代序列图

User          queryLoop         PreProcess       API          Tools          StopHooks
 │                │                  │              │              │              │
 │   messages     │                  │              │              │              │
 │───────────────>│                  │              │              │              │
 │                │                  │              │              │              │
 │                │ applyToolResult  │              │              │              │
 │                │ Budget           │              │              │              │
 │                │─────────────────>│              │              │              │
 │                │                  │              │              │              │
 │                │  snipCompact     │              │              │              │
 │                │─────────────────>│              │              │              │
 │                │                  │              │              │              │
 │                │  microcompact    │              │              │              │
 │                │─────────────────>│              │              │              │
 │                │                  │              │              │              │
 │                │  contextCollapse │              │              │              │
 │                │─────────────────>│              │              │              │
 │                │                  │              │              │              │
 │                │  autocompact     │              │              │              │
 │                │─────────────────>│              │              │              │
 │                │  messagesForQuery│              │              │              │
 │                │<─────────────────│              │              │              │
 │                │                  │              │              │              │
 │                │ prependUserContext               │              │              │
 │                │ appendSystemContext              │              │              │
 │                │                  │              │              │              │
 │                │  callModel(...)  │              │              │              │
 │                │────────────────────────────────>│              │              │
 │                │                  │              │              │              │
 │                │  stream messages │              │              │              │
 │<───────────────│<────────────────────────────────│              │              │
 │  (yield)       │                  │              │              │              │
 │                │                  │              │  tool_use?   │              │
 │                │                  │              │              │              │
 │                │──────── needsFollowUp ─────────────────────────>│              │
 │                │         runTools / StreamingToolExecutor        │              │
 │<───────────────│<───────────────────────────────────────────────│              │
 │  (yield results)                  │              │              │              │
 │                │                  │              │              │              │
 │                │  attachments (memory, skills, commands)        │              │
 │                │                  │              │              │              │
 │                │   state = { reason: 'next_turn', ... }        │              │
 │                │   continue ──────────────────────────> 下一轮迭代             │
 │                │                  │              │              │              │
 │          ──── OR ── needsFollowUp == false ────────────────────>│              │
 │                │                  │              │              │              │
 │                │  handleStopHooks │              │              │              │
 │                │────────────────────────────────────────────────────────────>│
 │                │  blockingErrors? │              │              │              │
 │                │<───────────────────────────────────────────────────────────│
 │                │                  │              │              │              │
 │                │  return { reason: 'completed' }│              │              │
 │<───────────────│                  │              │              │              │

3.6 模式提炼

读完 queryLoop() 的 1730 行源码，几个深层模式浮现出来：

模式一：显式状态重建而非增量修改

每个 continue 站点都构造完整的新 State 对象。没有 state.maxOutputTokensRecoveryCount++，只有 state = { ..., maxOutputTokensRecoveryCount: maxOutputTokensRecoveryCount + 1, ... }。这带来了三个好处：

1. 遗忘免疫：不可能忘记重置某个字段
2. 可审计性：每个继续点的完整意图在一个对象字面量中可见
3. 可测试性：transition 字段让测试能断言恢复路径是否触发

模式二：扣留-释放（Withhold-Release）

可恢复错误不立即暴露给消费者。它们被扣留（pushed to assistantMessages but not yielded），只有在所有恢复手段耗尽后才被释放。这个模式解决了一个现实问题：SDK 消费者（Desktop、Cowork）会在看到错误时终止会话——如果恢复成功，过早暴露错误就是一次不必要的中断。

模式三：从轻到重的分层恢复

无论是上下文压缩（snip → microcompact → collapse → autocompact）还是错误恢复（escalate → multi-turn → reactive compact），策略总是从最轻量（信息损失最小）的手段开始，逐步升级到更重量级的手段。这不仅是性能优化，更是信息保留策略——每一级都在“用最少的代价换最大的空间“。

模式四：后台并行化的滑动窗口

内存预取在循环入口启动，工具摘要在工具执行后异步启动，技能发现在迭代开始时异步启动——它们都在模型流式响应的 5-30 秒窗口期内完成计算。这种“在等待中完成准备工作“的模式将延迟隐藏得几乎不可见。

模式五：死循环保护的单次尝试守卫

hasAttemptedReactiveCompact、maxOutputTokensRecoveryCount、state.transition?.reason !== 'collapse_drain_retry'——这些守卫确保每种恢复策略最多执行一次（或有限次）。在一个 while (true) 循环中，没有这些守卫就是在邀请无限循环。源码注释中反复出现的 “death spiral” 一词（restored-src/src/query.ts:1171、1295）表明这不是理论担忧——这些守卫是从实际生产事故中学来的。

用户能做什么

如果你正在构建自己的 AI Agent 系统，以下是从 queryLoop() 设计中可以直接借鉴的实践：

• 为每种恢复策略设置单次尝试守卫。 在 while (true) 循环中，每种自动恢复（压缩、重试、降级）都必须有布尔标记或计数器防止无限循环。用 hasAttempted* 命名，让意图一目了然。
• 采用“从轻到重“的分层压缩策略。 不要在上下文超限时直接执行全量摘要。先尝试裁剪旧消息（snip）、再微压缩（microcompact）、再折叠（collapse）、最后才全量压缩（autocompact）。每一层都保留尽可能多的上下文信息。
• 用完整状态重建替代增量修改。 在循环的每个 continue 站点构造完整的新状态对象，而非逐字段修改。这消除了“忘记重置字段“的 bug 类，尤其在有多个继续路径时。
• 扣留可恢复错误。 不要在第一时间将错误暴露给上层消费者。先尝试所有恢复手段，只有全部失败后才释放错误。这避免了上层因看到错误而过早终止会话。
• 利用模型响应的等待窗口做并行预取。 在发起 API 调用的同时启动内存预取、技能发现等异步任务。模型生成响应的 5-30 秒窗口是“免费“的计算时间。
• 记录转换原因（transition reason）。 在状态中记录每次循环继续的原因（如 next_turn、reactive_compact_retry），既方便调试，也让自动化测试能断言特定恢复路径是否被触发。

3.7 本章小结

queryLoop() 是 Claude Code 的心跳。它不是简单地在用户和模型之间传递消息，而是在每次迭代中主动管理上下文容量、编排工具执行、处理错误恢复、执行权限检查。理解了这个循环的拓扑结构和转换语义，后续章节中讨论的每一个子系统——autocompact（第9章）、API 调用构建（第5章）、流式响应处理（第13章）、权限检查（第16章）——都能在心智模型中找到它们被调用的精确位置和时机。

这个循环最深刻的设计特征是：它知道自己可能失败，并为此做好了准备。不是“如果一切顺利“的乐观路径，而是“当事情出错时如何优雅地恢复“的防御性设计。这正是将一个 demo 级别的 AI 聊天界面变成生产级 AI Agent 的关键工程决策。

第4章：工具执行编排 – 权限、并发、流式与中断

第3章剖析了 Agent Loop 的完整生命周期，当模型返回 tool_use 类型的内容块时，循环进入“工具执行阶段“。本章将深入这个阶段的内部实现：工具调用如何被分区调度、单工具执行经历哪些生命周期步骤、权限决策链如何层层过滤、大结果如何被持久化，以及流式执行器如何处理并发与中断。

4.1 为什么工具执行编排至关重要

一次 Agent 循环迭代中，模型可能同时请求多个工具调用。例如，模型可能一次性发出三个 Read 调用来读取不同文件，然后紧跟一个 Bash 调用来运行测试。这些调用不能全部并行执行 – 读取操作是安全的，但一个 git checkout 可能改变工作目录状态，导致并行读取得到不一致的结果。

Claude Code 的工具编排层（tool orchestration）解决三个核心问题：

1. 安全并发：只读工具可以并行执行以提高吞吐量，写入工具必须串行执行以保证一致性
2. 权限门控：每个工具在执行前必须通过权限决策链，确保用户对危险操作保持控制
3. 结果管理：工具输出可能极大（一个 cat 命令可能返回数十万字符），需要智能裁剪以避免上下文窗口溢出

这三个问题的解决方案分布在三个核心文件中：toolOrchestration.ts（批次调度）、toolExecution.ts（单工具生命周期）、StreamingToolExecutor.ts（流式并发执行器）。

4.2 partitionToolCalls：工具调用分区

4.2.1 分区算法

当 Agent Loop 将一批 ToolUseBlock 交给编排层时，第一步是将它们分区为交替的“并发安全批次“和“串行批次“。这是 partitionToolCalls 函数的职责：

flowchart TD
    Input["模型返回的工具调用序列（按顺序）<br />[Read A] [Read B] [Grep C] [Bash D] [Read E] [Edit F]"]
    Input -->|partitionToolCalls| B1
    B1["批次 1（并发安全）<br />Read A, Read B, Grep C<br />三个只读工具合并为一批"]
    B1 --> B2["批次 2（串行）<br />Bash D<br />写入工具独占一批"]
    B2 --> B3["批次 3（并发安全）<br />Read E<br />新的只读批次"]
    B3 --> B4["批次 4（串行）<br />Edit F<br />写入工具独占一批"]

    style B1 fill:#d4edda,stroke:#28a745
    style B3 fill:#d4edda,stroke:#28a745
    style B2 fill:#f8d7da,stroke:#dc3545
    style B4 fill:#f8d7da,stroke:#dc3545

图 4-1：partitionToolCalls 分区逻辑图。 连续的并发安全工具被合并到同一批次（绿色），非并发安全工具各自独占一批（红色）。

分区逻辑的核心是一个 reduce 操作（restored-src/src/services/tools/toolOrchestration.ts:91-116）：

      // 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
  }, [])
}

关键设计决策：

• 先验证再分类：输入必须通过 Zod schema 验证后才会调用 isConcurrencySafe。如果模型生成了无效输入，该工具被保守地标记为非并发安全。
• 异常即不安全：如果 isConcurrencySafe 本身抛出异常（比如 shell-quote 解析 Bash 命令失败），同样回退到串行执行。这是“失败即关闭“（fail-closed）的经典安全模式。
• 贪心合并：连续的并发安全工具被合并到同一批次，直到遇到一个非安全工具为止。这保持了调用的相对顺序，同时最大化并行度。

4.2.2 isConcurrencySafe 的判定逻辑

isConcurrencySafe 是 Tool 接口上的必需方法（restored-src/src/Tool.ts:402），默认实现返回 false（restored-src/src/Tool.ts:759）。各工具根据自身语义提供实现：

以 BashTool 为例（restored-src/src/tools/BashTool/BashTool.tsx:434-436）：

isConcurrencySafe(input) {
  return this.isReadOnly?.(input) ?? false;
},

Bash 工具的并发安全性完全取决于命令内容：ls、cat、git log 是安全的，而 rm、git checkout、npm install 则不是。isReadOnly 会解析命令结构来做出判断。

4.3 runTools：批次调度引擎

runTools（restored-src/src/services/tools/toolOrchestration.ts:19-82）是编排层的入口。它遍历分区后的批次，对并发安全批次调用 runToolsConcurrently，对串行批次调用 runToolsSerially。

4.3.1 并发执行路径

并发路径使用 all() 工具函数（restored-src/src/utils/generators.ts:32）将多个异步生成器合并为一个，带有并发上限（concurrency cap）：

async function* runToolsConcurrently(...) {
  yield* all(
    toolUseMessages.map(async function* (toolUse) {
      yield* runToolUse(toolUse, ...)
      markToolUseAsComplete(toolUseContext, toolUse.id)
    }),
    getMaxToolUseConcurrency(),  // 默认 10，可通过环境变量覆盖
  )
}

并发上限通过环境变量 CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY 配置（restored-src/src/services/tools/toolOrchestration.ts:8-11），默认值为 10。

一个重要的细节是上下文修改器的延迟应用（context modifier deferred application）。并发执行的工具可能各自产生上下文修改（例如更新工具可用列表），但这些修改不能在并发执行期间立即应用 – 否则会引发竞态条件。因此，修改器被收集到队列中，在整个并发批次完成后按工具出现顺序依次应用（restored-src/src/services/tools/toolOrchestration.ts:31-63）。

4.3.2 串行执行路径

串行路径则直接按顺序执行每个工具，每次执行后立即应用上下文修改：

for (const toolUse of toolUseMessages) {
  for await (const update of runToolUse(toolUse, ...)) {
    if (update.contextModifier) {
      currentContext = update.contextModifier.modifyContext(currentContext)
    }
    yield { message: update.message, newContext: currentContext }
  }
}

这保证了写入工具能看到前一个工具修改后的上下文状态。

4.4 单工具执行生命周期

每个工具调用，无论通过并发路径还是串行路径，最终都进入 runToolUse（restored-src/src/services/tools/toolExecution.ts:337）和 checkPermissionsAndCallTool（restored-src/src/services/tools/toolExecution.ts:599）。这两个函数组成了单工具的完整生命周期。

┌─────────────────────────────────────────────────────────────────┐
│                    单工具执行生命周期                              │
│                                                                  │
│  ① 工具查找 ──→ ② Schema 验证 ──→ ③ 输入验证                     │
│       │              │                  │                         │
│   找不到工具？    验证失败？          验证失败？                     │
│   ↓ 返回错误     ↓ 返回错误          ↓ 返回错误                   │
│                                                                  │
│  ④ PreToolUse Hooks ──→ ⑤ 权限决策 ──→ ⑥ tool.call()            │
│       │                      │               │                   │
│   Hook 阻止？          权限拒绝？         执行出错？               │
│   ↓ 返回错误          ↓ 返回错误         ↓ 返回错误               │
│                                                                  │
│  ⑦ 结果映射 ──→ ⑧ 大结果持久化 ──→ ⑨ PostToolUse Hooks          │
│                                          │                       │
│                                   Hook 阻止继续？                 │
│                                   ↓ 停止后续循环                  │
└─────────────────────────────────────────────────────────────────┘

图 4-2：单工具生命周期流程图。 每个阶段都可能产生错误消息终止流程，成功路径从左到右贯穿全部九个阶段。

4.4.1 阶段一：工具查找与输入验证

runToolUse 首先在可用工具集中查找目标工具（restored-src/src/services/tools/toolExecution.ts:345-356）。如果找不到，还会检查已弃用工具的别名（alias）– 这保证了旧版会话记录中的工具调用仍然可以执行。

输入验证分两步：

1. Schema 验证：使用 Zod 的 safeParse 对模型输出的参数进行类型校验（restored-src/src/services/tools/toolExecution.ts:615-616）。模型生成的参数类型并不总是正确的 – 比如它可能把一个应为数组的参数输出为字符串。

2. 语义验证：通过 tool.validateInput() 进行工具特定的业务逻辑校验（restored-src/src/services/tools/toolExecution.ts:683-684）。例如，FileEdit 工具可能检查目标文件是否存在。

一个值得注意的细节：当工具是延迟工具（deferred tool）且其 Schema 未被发送给 API 时，系统会在 Zod 错误消息中附加提示，引导模型先通过 ToolSearch 加载工具 Schema 再重试（restored-src/src/services/tools/toolExecution.ts:578-597）。

4.4.2 阶段二：推测性分类器启动

在进入权限检查之前，如果当前工具是 Bash 工具，系统会推测性地启动允许分类器（speculative classifier check，restored-src/src/services/tools/toolExecution.ts:740-752）。这个分类器与 PreToolUse Hooks 并行运行，在用户需要做出权限决策时结果可能已经就绪。这是一个优化手段 – 避免用户等待分类器的延迟。

4.4.3 阶段三：PreToolUse Hooks

系统执行所有注册的 PreToolUse hooks（restored-src/src/services/tools/toolExecution.ts:800-862）。Hooks 可以产生以下效果：

• 修改输入：返回 updatedInput 替换原始参数
• 做出权限决策：返回 allow、deny 或 ask 来影响后续权限检查
• 阻止执行：设置 preventContinuation 标志
• 添加上下文：注入额外信息供模型参考

如果 hook 执行期间发生中断（abort signal），系统立即终止并返回取消消息。

4.4.4 阶段四：权限决策链

权限系统是工具执行生命周期中最复杂的环节。决策链由 resolveHookPermissionDecision（restored-src/src/services/tools/toolHooks.ts:332-433）协调，遵循以下优先级：

┌──────────────────────────────────────────────────────────────────┐
│                       权限决策链                                  │
│                                                                   │
│  PreToolUse Hook 决策                                             │
│  ├─ allow ──→ 检查规则权限 (settings.json deny/ask 规则)          │
│  │            ├─ 无匹配规则 ──→ 允许（跳过用户提示）               │
│  │            ├─ deny 规则 ──→ 拒绝（规则覆盖 Hook）              │
│  │            └─ ask 规则 ──→ 提示用户（规则覆盖 Hook）           │
│  ├─ deny ──→ 直接拒绝                                            │
│  └─ ask ──→ 进入正常权限流程（带 Hook 的 forceDecision）          │
│                                                                   │
│  无 Hook 决策 ──→ 正常权限流程                                    │
│  ├─ 工具自身 checkPermissions                                     │
│  ├─ 通用规则匹配 (settings.json)                                  │
│  ├─ YOLO/Auto 分类器（详见第17章）                                │
│  └─ 用户交互提示（详见第16章）                                    │
└──────────────────────────────────────────────────────────────────┘

图 4-3：权限决策链图。 Hook 的 allow 不能覆盖 settings.json 中的 deny 规则，这是纵深防御的体现。

决策链的一个关键不变量是：Hook 的 allow 决策不能绕过 settings.json 中的 deny/ask 规则。即使 hook 批准了一个操作，如果 settings.json 中存在明确的 deny 规则，该操作仍会被拒绝。这确保了用户配置的安全边界始终有效（restored-src/src/services/tools/toolHooks.ts:373-405）。

权限系统的完整架构详见第16章，YOLO 分类器的实现详见第17章。

4.4.5 阶段五：工具执行

权限通过后，系统调用 tool.call()（restored-src/src/services/tools/toolExecution.ts:1207-1222）。执行过程被包裹在 startSessionActivity('tool_exec') 和 stopSessionActivity('tool_exec') 之间，用于追踪活跃会话状态。

工具执行期间的进度事件通过 Stream 对象传递（restored-src/src/services/tools/toolExecution.ts:509）。streamedCheckPermissionsAndCallTool 将 checkPermissionsAndCallTool 的 Promise 结果和实时进度事件合并到同一个异步可迭代对象中，使得调用者可以同时接收进度更新和最终结果。

4.4.6 阶段六：PostToolUse Hooks 与结果处理

工具执行成功后，系统依次执行：

1. 结果映射：通过 tool.mapToolResultToToolResultBlockParam() 将工具输出转换为 API 格式（restored-src/src/services/tools/toolExecution.ts:1292-1293）
2. 大结果持久化：如果结果超过阈值，将其写入磁盘并用摘要替换（详见 4.6 节）
3. PostToolUse Hooks：执行后置 hooks，可以修改 MCP 工具输出或阻止后续循环继续（restored-src/src/services/tools/toolExecution.ts:1483-1531）

对于 MCP 工具，hooks 可以通过返回 updatedMCPToolOutput 来修改工具输出。这个修改在 addToolResult 调用之前生效，确保最终存入消息历史的是修改后的版本。非 MCP 工具的结果映射在 hooks 之前完成，因此 hooks 只能附加信息，不能修改结果本身。

如果工具执行失败，系统转而执行 PostToolUseFailure hooks（restored-src/src/services/tools/toolExecution.ts:1700-1713），允许 hooks 检查错误并注入额外上下文。

4.5 StreamingToolExecutor：流式并发执行器

前面描述的 runTools 是批量模式（batch mode）– 等待所有 tool_use 块到齐后才开始分区和执行。但在流式响应场景中，工具调用块一个接一个地从 API 流中解析出来。StreamingToolExecutor（restored-src/src/services/tools/StreamingToolExecutor.ts）实现了一种不同的策略：工具调用到达即开始执行，无需等待全部就绪。

4.5.1 状态机模型

StreamingToolExecutor 为每个工具维护一个四状态的生命周期：

queued ──→ executing ──→ completed ──→ yielded

• queued：工具已注册但尚未开始执行
• executing：工具正在运行中
• completed：工具已完成，结果已缓冲
• yielded：结果已被消费者获取

状态转换由 processQueue() 驱动（restored-src/src/services/tools/StreamingToolExecutor.ts:140-151）。每次有工具完成或新工具入队时，队列处理器被唤醒，尝试启动下一个可执行的工具。

4.5.2 并发控制

canExecuteTool 方法（restored-src/src/services/tools/StreamingToolExecutor.ts:129-135）实现了核心的并发策略：

private canExecuteTool(isConcurrencySafe: boolean): boolean {
  const executingTools = this.tools.filter(t => t.status === 'executing')
  return (
    executingTools.length === 0 ||
    (isConcurrencySafe && executingTools.every(t => t.isConcurrencySafe))
  )
}

规则很简洁：

• 如果没有工具在执行，任何工具都可以启动
• 如果有工具在执行，新工具只有在自身和所有正在执行的工具都是并发安全的情况下才能启动
• 非并发安全工具需要独占执行（exclusive access）

4.5.3 Bash 错误级联中断

StreamingToolExecutor 实现了一个精妙的错误处理机制：当一个 Bash 工具出错时，所有同级并行的 Bash 工具会被取消（restored-src/src/services/tools/StreamingToolExecutor.ts:357-363）。

if (tool.block.name === BASH_TOOL_NAME) {
  this.hasErrored = true
  this.erroredToolDescription = this.getToolDescription(tool)
  this.siblingAbortController.abort('sibling_error')
}

这个设计基于一个实际观察：Bash 命令之间通常存在隐式依赖链。如果 mkdir 失败了，后续的 cp 命令也注定失败 – 与其让它们各自报错，不如提前取消。但这个策略仅限于 Bash 工具 – Read、WebFetch 等工具是独立的，一个的失败不应影响其他工具。

错误级联使用一个 siblingAbortController 实现，它是 toolUseContext.abortController 的子控制器。中止兄弟控制器会取消正在运行的子进程，但不会中止父控制器 – 这意味着 Agent Loop 本身不会因为一个 Bash 错误而终止当前回合。

4.5.4 中断行为

每个工具可以声明自己的中断行为（interrupt behavior）：'cancel' 或 'block'（restored-src/src/Tool.ts:416）。当用户发送中断信号时：

• cancel 工具：立即收到取消消息，结果被合成的 REJECT_MESSAGE 替代
• block 工具：继续运行到完成（不响应中断）

StreamingToolExecutor 通过 updateInterruptibleState() 追踪当前是否所有正在执行的工具都是可中断的（restored-src/src/services/tools/StreamingToolExecutor.ts:254-259）。这个信息被传递给 UI 层，决定是否显示“按 ESC 取消“的提示。

4.5.5 进度消息的即时传递

普通工具结果必须按序传递（保证顺序语义），但进度消息可以立即传递（restored-src/src/services/tools/StreamingToolExecutor.ts:417-420）。StreamingToolExecutor 将进度消息存储在独立的 pendingProgress 队列中，getCompletedResults() 在扫描工具列表时会优先 yield 进度消息，不受工具完成顺序的限制。

当没有已完成结果但有正在执行的工具时，getRemainingResults() 通过 Promise.race 等待任一工具完成或有新的进度消息到达（restored-src/src/services/tools/StreamingToolExecutor.ts:476-481），避免不必要的轮询。

4.6 工具结果管理：预算与持久化

4.6.1 大结果持久化

一个 Bash 工具的 cat 命令可能返回数十万字符。将如此巨大的结果直接塞入上下文窗口，不仅浪费 token 预算，还可能导致模型注意力分散。toolResultStorage.ts 实现了大结果持久化机制。

持久化阈值的确定遵循以下优先级（restored-src/src/utils/toolResultStorage.ts:55-78）：

1. GrowthBook 覆盖：运营团队可以通过 Feature Flag（tengu_satin_quoll）为特定工具设置自定义阈值
2. 工具声明值：每个工具的 maxResultSizeChars 属性
3. 全局上限：DEFAULT_MAX_RESULT_SIZE_CHARS = 50,000 字符（restored-src/src/constants/toolLimits.ts:13）

最终阈值取工具声明值和全局上限的较小者。但如果工具声明 Infinity，则跳过持久化 – 例如 Read 工具自己管理输出边界，将其输出持久化到文件再让模型用 Read 读回是循环引用。

当结果超过阈值时，persistToolResult（restored-src/src/utils/toolResultStorage.ts:137）将完整内容写入会话目录下的 tool-results/ 子目录，然后生成一个包含预览的摘要消息：

<persisted-output>
Output too large (245.0 KB). Full output saved to: /path/to/tool-results/abc123.txt

Preview (first 2.0 KB):
[前 2000 字节的内容...]
...
</persisted-output>

预览生成（restored-src/src/utils/toolResultStorage.ts:339-356）会尽量在换行符处截断，避免在行中间切断。截断点的查找范围是阈值的 50% 到 100% 之间最后一个换行符。

4.6.2 每消息聚合预算

除了单工具的大小限制，系统还维护一个每消息聚合预算（per-message aggregate budget）。当一个回合中多个并行工具各自返回接近阈值的结果时，它们的总和可能远超合理范围（例如 10 个工具各返回 40K = 400K 字符）。

聚合预算默认为 200,000 字符（restored-src/src/constants/toolLimits.ts:49），可通过 GrowthBook Flag（tengu_hawthorn_window）覆盖。超出预算时，系统从最大的工具结果开始持久化，直到总量降回预算以内。

为了保持提示缓存（prompt cache）的稳定性，聚合预算系统维护了一个 ContentReplacementState（restored-src/src/utils/toolResultStorage.ts:390-393），记录哪些工具结果已经被持久化。一旦某个结果在某次评估中被持久化，它在后续所有评估中都会使用相同的持久化版本 – 即使后续回合的总量未超预算。这避免了“缓存抖动“（cache thrashing）：同一条消息在不同 API 调用中内容不同，导致前缀缓存失效。

4.6.3 空结果填充

一个容易被忽视的细节：空的 tool_result 内容会导致某些模型（尤其是 Capybara）误将其解释为回合边界，输出 \n\nHuman: 停止序列并终止响应（restored-src/src/utils/toolResultStorage.ts:280-295）。系统通过检测空结果并注入占位文本（如 (Bash completed with no output)）来防止这种行为。

4.7 Stop Hooks：工具执行后的中断点

PreToolUse hooks 和 PostToolUse hooks 都可以请求停止后续循环继续（prevent continuation）。这是通过 preventContinuation 标志实现的。

当 PreToolUse hook 设置了此标志（restored-src/src/services/tools/toolHooks.ts:500-508），工具仍然会执行（除非同时返回了 deny 决策），但执行完成后，系统会向消息列表追加一条 hook_stopped_continuation 类型的附件消息（restored-src/src/services/tools/toolExecution.ts:1572-1582）。Agent Loop 检测到这类消息后会终止当前迭代，不再将结果发送给模型进行下一轮推理。

PostToolUse hooks 同样可以阻止继续（restored-src/src/services/tools/toolHooks.ts:118-129），并且是更常见的用法 – 例如，一个 hook 可能在检测到危险操作的结果后决定中断 Agent 循环。

4.8 模式提炼

模式一：贪心合并的流水线分区

工具调用分区采用“贪心合并“策略：连续的同类工具被合并到同一批次，不同类型的切换点成为批次边界。这个模式的核心洞见是 – 在顺序保证和并行效率之间，选择一个简单的中间方案。完全并行（忽略顺序）可能导致不一致，完全串行（忽略类型）则浪费性能。贪心合并在保持相对顺序的前提下实现了接近最优的并行度。

模式二：失败即关闭的安全默认值

isConcurrencySafe 在解析失败或异常时默认返回 false，Tool 接口的默认实现也是 false。权限 hook 的 allow 不能覆盖 deny 规则。这些都是“fail-closed“模式的体现 – 当系统无法确定安全性时，选择更保守的行为。在 AI Agent 系统中，这个原则尤为重要：模型的输出是不可预测的，任何假设“正常情况下不会发生“的乐观设计都可能成为安全漏洞。

模式三：分层错误级联

Bash 错误取消同级 Bash 工具，但不影响 Read/Grep 等独立工具；兄弟中止控制器取消子进程，但不中止父级 Agent Loop。这种选择性级联（selective cascading）避免了两个极端：要么完全隔离（错误被忽视），要么全局中止（一个小错误杀死整个会话）。

模式四：缓存稳定的结果管理

大结果持久化系统通过 ContentReplacementState 确保同一结果在不同 API 调用中始终使用相同的替换内容。这是提示缓存优化的关键 – 为了性能，牺牲一点逻辑简洁性来维护确定性。类似的缓存稳定性设计将在第13-15章的缓存架构中反复出现。

用户能做什么

以下是从 Claude Code 工具执行编排中提炼出的可操作建议，适用于任何需要编排多工具调用的 AI Agent 系统：

• 实现基于输入的并发分区。 不要简单地将所有工具调用串行执行。根据每个工具调用的实际输入判断是否只读/并发安全，将连续的安全调用合并为并发批次，最大化吞吐量。
• 为并发安全性设置“失败即关闭“默认值。 如果输入解析失败或 isConcurrencySafe 抛异常，默认回退到串行执行。永远不要在不确定时假设并发是安全的。
• 实现 Bash 错误的选择性级联中断。 当一个 shell 命令失败时，取消同级的其他 shell 命令（它们很可能存在隐式依赖），但不要取消独立的只读工具（如 Read、Grep）。使用子级 AbortController 实现，避免中止整个 Agent Loop。
• 为大结果实现两级预算控制。 单工具结果有字符数上限，单消息的所有工具结果也有聚合上限。超出预算时持久化到磁盘并返回预览，从最大的结果开始裁剪。
• 维护结果替换的确定性。 一旦某个工具结果被持久化替换，在后续所有 API 调用中都使用相同的替换版本，即使聚合预算当前未超限。这对提示缓存的命中率至关重要。
• 为空的工具结果注入占位文本。 空的 tool_result 可能被模型误解为回合边界。注入类似 (Bash completed with no output) 的占位文本，避免模型意外终止响应。
• 将权限检查设计为纵深防御。 Hook 的 allow 决策不应绕过用户配置的 deny 规则。多层权限检查（hook → 工具自身 → 规则匹配 → 用户交互）确保安全边界始终有效。

本章揭示了工具执行编排层如何在并发效率、安全控制和上下文管理之间取得平衡。下一章将进入第二篇，分析系统提示词架构 – 另一个驾驭模型行为的关键控制面。

第5章：系统提示词架构

第4章解剖了工具执行编排的全过程。在模型能够做出任何工具调用之前，它需要先“知道自己是谁“ – 这正是系统提示词（system prompt）的职责。本章将深入系统提示词的组装架构：段落如何注册与记忆化、静态与动态内容如何被边界标记分割、缓存优化契约如何在 API 层兑现、以及多来源提示词如何按优先级合成为最终发送给模型的指令集。

5.1 为什么系统提示词需要“架构“

一个朴素的实现可以将系统提示词硬编码为一个字符串常量。但 Claude Code 的系统提示词面临三重工程挑战：

1. 体积与成本：完整的系统提示词包含身份介绍、行为规范、工具使用指南、环境信息、内存文件、MCP 指令等十余个段落，总量达数万 token。每次 API 调用都重传这些内容，意味着巨额的 prompt 缓存（prompt caching）成本。
2. 变化频率不一：身份介绍和编码规范在所有用户、所有会话中完全相同，而环境信息（工作目录、操作系统版本）因会话而异，MCP 服务器指令甚至可能在对话中途变化。
3. 多来源覆盖：用户可以通过 --system-prompt 自定义提示词，Agent 模式有专属提示词，协调器模式（coordinator mode）有独立提示词，Loop 模式可以完全覆盖 – 这些来源之间的优先级必须明确。

Claude Code 的解决方案是一个分段式组合架构（sectioned composition architecture）：将系统提示词拆分为独立的、可记忆化的段落，通过注册表管理生命周期，用边界标记（boundary marker）划分缓存层级，最终在 API 层转化为带有 cache_control 的请求块。

5.2 段落注册表：systemPromptSection 的记忆化与缓存感知

5.2.1 核心抽象

系统提示词的最小单元是段落（section）。每个段落由一个名称、一个计算函数和一个缓存策略组成。这个抽象定义在 systemPromptSections.ts 中：

type SystemPromptSection = {
  name: string
  compute: ComputeFn        // () => string | null | Promise<string | null>
  cacheBreak: boolean       // false = 可记忆化, true = 每轮重算
}

源码参考： restored-src/src/constants/systemPromptSections.ts:10-14

两个工厂函数用于创建段落：

• systemPromptSection(name, compute) – 创建一个记忆化段落。计算函数只在首次调用时执行，结果被缓存到全局状态中，后续轮次直接返回缓存值。缓存在 /clear 或 /compact 时重置。
• DANGEROUS_uncachedSystemPromptSection(name, compute, reason) – 创建一个易变段落。每次解析（resolve）时都会重新执行计算函数。DANGEROUS_ 前缀和必填的 reason 参数是有意为之的 API 设计摩擦（API friction），提醒开发者这种段落会破坏 prompt 缓存。

┌───────────────────────────────────────────────────────────────────────┐
│                      段落注册表 (Section Registry)                    │
│                                                                       │
│  ┌─────────────────────┐   ┌──────────────────────────────────────┐  │
│  │ systemPromptSection │   │ DANGEROUS_uncachedSystemPromptSection│  │
│  │   cacheBreak=false  │   │         cacheBreak=true              │  │
│  └────────┬────────────┘   └────────────┬─────────────────────────┘  │
│           │                              │                            │
│           ▼                              ▼                            │
│  ┌─────────────────────────────────────────────────────────────────┐  │
│  │            resolveSystemPromptSections(sections)                │  │
│  │                                                                 │  │
│  │  for each section:                                              │  │
│  │    if (!cacheBreak && cache.has(name)):                         │  │
│  │      return cache.get(name)    ← 记忆化命中                     │  │
│  │    else:                                                        │  │
│  │      value = await compute()                                    │  │
│  │      cache.set(name, value)    ← 写入缓存                      │  │
│  │      return value                                               │  │
│  └─────────────────────────────────────────────────────────────────┘  │
│                                                                       │
│  缓存存储: STATE.systemPromptSectionCache (Map<string, string|null>) │
│  重置时机: /clear, /compact → clearSystemPromptSections()            │
└───────────────────────────────────────────────────────────────────────┘

图 5-1：段落注册表的记忆化流程。 记忆化段落（cacheBreak=false）在首次计算后缓存到全局 Map 中；易变段落（cacheBreak=true）每次都重新计算。

5.2.2 解析流程

resolveSystemPromptSections 是将段落定义转化为实际字符串的核心函数（restored-src/src/constants/systemPromptSections.ts:43-58）：

export async function resolveSystemPromptSections(
  sections: SystemPromptSection[],
): Promise<(string | null)[]> {
  const cache = getSystemPromptSectionCache()
  return Promise.all(
    sections.map(async s => {
      if (!s.cacheBreak && cache.has(s.name)) {
        return cache.get(s.name) ?? null
      }
      const value = await s.compute()
      setSystemPromptSectionCacheEntry(s.name, value)
      return value
    }),
  )
}

几个关键设计决策：

• 并行解析：使用 Promise.all 并行执行所有段落的计算函数。这对于需要 I/O 操作的段落（如 loadMemoryPrompt 读取 CLAUDE.md 文件）尤为重要。
• null 有效：计算函数返回 null 表示该段落不需要包含在最终提示词中。null 同样会被缓存，避免在后续轮次重复执行条件判断。
• 缓存存储位置：缓存存储在 STATE.systemPromptSectionCache 中（restored-src/src/bootstrap/state.ts:203），这是一个 Map<string, string | null>。选择全局 state 而非模块级变量，是为了让 /clear 和 /compact 命令能够统一重置所有状态。

5.2.3 缓存生命周期

缓存的清除由 clearSystemPromptSections 函数负责（restored-src/src/constants/systemPromptSections.ts:65-68）：

      // export function clearSystemPromptSections(): void {
  clearSystemPromptSectionState()   // 清空 Map
  clearBetaHeaderLatches()          // 重置 beta 头部锁存器
}

这个函数在两个时机被调用：

1. /clear 命令 – 用户显式清除对话历史时，所有段落缓存失效，下一轮 API 调用会重新计算所有段落。
2. /compact 命令 – 对话被压缩时，段落缓存同样失效。这是因为压缩可能改变上下文状态（如工具可用列表），依赖旧状态计算的段落值可能不再正确。

附带的 clearBetaHeaderLatches() 确保新对话能重新评估 AFK、fast-mode 等 beta 特性头部，而不是延续上一轮的锁存值。

5.3 DANGEROUS_uncachedSystemPromptSection 的使用时机

DANGEROUS_ 前缀不是装饰 – 它标记了一个真实的工程权衡（trade-off）。让我们看看源码中唯一的使用案例：

DANGEROUS_uncachedSystemPromptSection(
  'mcp_instructions',
  () =>
    isMcpInstructionsDeltaEnabled()
      ? null
      : getMcpInstructionsSection(mcpClients),
  'MCP servers connect/disconnect between turns',
),

源码参考： restored-src/src/constants/prompts.ts:513-520

MCP 服务器可以在对话的两个轮次之间连接或断开。如果将 MCP 指令段落设为记忆化，那么在第1轮计算时只有服务器 A 连接，缓存了 A 的指令；到第3轮服务器 B 也连接了，但缓存仍然返回只包含 A 的旧值 – 模型永远不会知道 B 的存在。

这就是 DANGEROUS_uncachedSystemPromptSection 的使用时机：当段落的内容可能在对话生命周期内发生变化，且使用过期值会导致功能性错误时。

代码注释中的 reason 参数（'MCP servers connect/disconnect between turns'）不仅是文档，更是一种代码审查约束 – 任何引入新的 DANGEROUS_ 段落的 PR 都需要解释为什么缓存失效是必要的。

值得注意的是，源码中还记录了一个“从 DANGEROUS 降级为普通缓存“的案例。token_budget 段落曾经是 DANGEROUS_uncachedSystemPromptSection，根据 getCurrentTurnTokenBudget() 的值动态切换，但这会在每次 budget 切换时破坏约 20K token 的缓存。解决方案是重新措辞提示词文本，使其在无预算时自然成为空操作（no-op），从而降级为普通的 systemPromptSection（restored-src/src/constants/prompts.ts:540-550）。

5.4 静态与动态边界：SYSTEM_PROMPT_DYNAMIC_BOUNDARY

5.4.1 边界标记的定义

系统提示词中存在一条显式的分界线，将内容划分为“静态区“和“动态区“：

export const SYSTEM_PROMPT_DYNAMIC_BOUNDARY =
  '__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__'

源码参考： restored-src/src/constants/prompts.ts:114-115

这个字符串常量本身不会出现在最终发送给模型的文本中 – 它是一个带内信号（in-band signal），只存在于系统提示词数组中，供下游的 splitSysPromptPrefix 函数识别和处理。

5.4.2 边界的位置与含义

在 getSystemPrompt 函数的返回数组中，边界标记被精确放置在静态内容与动态内容之间（restored-src/src/constants/prompts.ts:560-576）：

返回数组结构：
[
  getSimpleIntroSection(...)          ─┐
  getSimpleSystemSection()             │ 静态区：所有用户/会话相同
  getSimpleDoingTasksSection()         │ → cacheScope: 'global'
  getActionsSection()                  │
  getUsingYourToolsSection(...)        │
  getSimpleToneAndStyleSection()       │
  getOutputEfficiencySection()        ─┘
  SYSTEM_PROMPT_DYNAMIC_BOUNDARY      ← 边界标记
  session_guidance                    ─┐
  memory (CLAUDE.md)                   │ 动态区：因会话/用户而异
  env_info_simple                      │ → cacheScope: null (不缓存)
  language                             │
  output_style                         │
  mcp_instructions (DANGEROUS)         │
  scratchpad                           │
  ...                                 ─┘
]

图 5-2：静态/动态边界示意图。 边界标记将系统提示词数组分为两个区域，分别对应不同的缓存作用域。

关键规则：边界标记之前的所有内容在所有组织、所有用户、所有会话中完全相同。这意味着它们可以使用 scope: 'global' 进行跨组织缓存 – 一个用户的 API 调用计算出的缓存前缀，可以被任何其他用户的调用直接命中。

边界标记只在第一方（firstParty）API 提供者启用全局缓存时才被插入：

...(shouldUseGlobalCacheScope() ? [SYSTEM_PROMPT_DYNAMIC_BOUNDARY] : []),

shouldUseGlobalCacheScope()（restored-src/src/utils/betas.ts:227-231）的判断条件是：API 提供者为 'firstParty'（即直接使用 Anthropic API），且未通过环境变量禁用实验性 beta 特性。第三方提供者（如通过 Foundry 接入）不使用全局缓存。

5.4.3 将会话变化赶到边界之后

源码中有一段精心撰写的注释，解释了 getSessionSpecificGuidanceSection 存在的原因（restored-src/src/constants/prompts.ts:343-347）：

Session-variant guidance that would fragment the cacheScope:‘global’ prefix if placed before SYSTEM_PROMPT_DYNAMIC_BOUNDARY. Each conditional here is a runtime bit that would otherwise multiply the Blake2b prefix hash variants (2^N).

这揭示了一个微妙但关键的设计约束：静态区中不能包含任何因会话而异的条件分支。如果工具可用列表、Skill 命令、Agent 工具等运行时信息出现在边界之前，那么每种工具组合都会产生一个不同的 Blake2b 前缀哈希，导致全局缓存的变体数量呈指数增长（2^N，N 为条件位数），实际命中率降为零。

因此，所有依赖运行时状态的内容 – 工具引导（session guidance）、内存文件、环境信息、语言偏好 – 都被放置在边界之后的动态区中，作为记忆化段落（systemPromptSection）而非静态字符串。

5.5 splitSysPromptPrefix 的三条代码路径

splitSysPromptPrefix（restored-src/src/utils/api.ts:321-435）是将逻辑上的系统提示词数组转化为 API 请求中带有缓存控制的文本块（SystemPromptBlock[]）的桥梁。它根据运行时条件选择三条不同的代码路径。

flowchart TD
    A["splitSysPromptPrefix(systemPrompt, options)"] --> B{"shouldUseGlobalCacheScope()\n&&\nskipGlobalCacheForSystemPrompt?"}
    B -->|"是 (MCP 工具在场)"| C["路径1: MCP 降级"]
    B -->|"否"| D{"shouldUseGlobalCacheScope()?"}
    D -->|"是"| E{"边界标记存在?"}
    D -->|"否"| G["路径3: 默认 org 缓存"]
    E -->|"是"| F["路径2: 全局缓存 + 边界"]
    E -->|"否"| G

    C --> C1["attribution → null\nprefix → org\nrest → org"]
    C1 --> C2["最多 3 块\n跳过边界标记"]

    F --> F1["attribution → null\nprefix → null\nstatic → global\ndynamic → null"]
    F1 --> F2["最多 4 块"]

    G --> G1["attribution → null\nprefix → org\nrest → org"]
    G1 --> G2["最多 3 块"]

    style C fill:#f9d,stroke:#333
    style F fill:#9df,stroke:#333
    style G fill:#dfd,stroke:#333

图 5-3：splitSysPromptPrefix 三路径流程图。 根据全局缓存特性和 MCP 工具存在情况，函数选择不同的缓存策略。

5.5.1 路径1：MCP 降级路径

触发条件： shouldUseGlobalCacheScope() === true 且 options.skipGlobalCacheForSystemPrompt === true

当会话中存在 MCP 工具时，工具 schema 本身是用户级别的动态内容，无法全局缓存。此时即便系统提示词中的静态区可以全局缓存，工具 schema 的存在也使全局缓存的实际收益大打折扣。因此 splitSysPromptPrefix 选择降级到 org 级别缓存。

// 路径1核心逻辑 (restored-src/src/utils/api.ts:332-359)
for (const prompt of systemPrompt) {
  if (!prompt) continue
  if (prompt === SYSTEM_PROMPT_DYNAMIC_BOUNDARY) continue // 跳过边界
  if (prompt.startsWith('x-anthropic-billing-header')) {
    attributionHeader = prompt
  } else if (CLI_SYSPROMPT_PREFIXES.has(prompt)) {
    systemPromptPrefix = prompt
  } else {
    rest.push(prompt)
  }
}
// 结果: [attribution:null, prefix:org, rest:org]

边界标记被直接跳过（continue），所有非特殊块合并为一个 org 级别的缓存块。skipGlobalCacheForSystemPrompt 的传入方来自 claude.ts 中的判断（restored-src/src/services/api/claude.ts:1210-1214）：只有当 MCP 工具实际渲染到请求中（而非被 defer_loading）时，才触发降级。

5.5.2 路径2：全局缓存 + 边界路径

触发条件： shouldUseGlobalCacheScope() === true，未被 MCP 降级，且系统提示词中存在边界标记

这是第一方用户在无 MCP 工具时的主路径，也是缓存效率最高的路径：

// 路径2核心逻辑 (restored-src/src/utils/api.ts:362-409)
const boundaryIndex = systemPrompt.findIndex(
  s => s === SYSTEM_PROMPT_DYNAMIC_BOUNDARY,
)
if (boundaryIndex !== -1) {
  for (let i = 0; i < systemPrompt.length; i++) {
    const block = systemPrompt[i]
    if (!block || block === SYSTEM_PROMPT_DYNAMIC_BOUNDARY) continue
    if (block.startsWith('x-anthropic-billing-header')) {
      attributionHeader = block
    } else if (CLI_SYSPROMPT_PREFIXES.has(block)) {
      systemPromptPrefix = block
    } else if (i < boundaryIndex) {
      staticBlocks.push(block)        // 边界前 → 静态
    } else {
      dynamicBlocks.push(block)       // 边界后 → 动态
    }
  }
  // 结果: [attribution:null, prefix:null, static:global, dynamic:null]
}

这条路径产生最多 4 个文本块：

静态块使用 scope: 'global' 意味着 Anthropic API 后端可以在所有 Claude Code 用户之间共享这个缓存前缀。考虑到静态区通常包含数万 token 的身份介绍和行为规范，这个缓存在高并发场景下节省的计算量是巨大的。

5.5.3 路径3：默认 org 缓存路径

触发条件： 全局缓存特性未启用（第三方提供者），或边界标记不存在

这是最简单的兜底路径：

// 路径3核心逻辑 (restored-src/src/utils/api.ts:411-434)
for (const block of systemPrompt) {
  if (!block) continue
  if (block.startsWith('x-anthropic-billing-header')) {
    attributionHeader = block
  } else if (CLI_SYSPROMPT_PREFIXES.has(block)) {
    systemPromptPrefix = block
  } else {
    rest.push(block)
  }
}
// 结果: [attribution:null, prefix:org, rest:org]

所有非特殊内容合并为单一块，使用 org 级别缓存。这对第三方提供者已经足够 – 同一组织内的用户共享相同的系统提示词前缀，仍能获得组织级别的缓存命中。

5.5.4 从 splitSysPromptPrefix 到 API 请求

buildSystemPromptBlocks（restored-src/src/services/api/claude.ts:3213-3237）是 splitSysPromptPrefix 的直接消费者。它将 SystemPromptBlock[] 转化为 Anthropic API 期望的 TextBlockParam[] 格式：

      // export function buildSystemPromptBlocks(
  systemPrompt: SystemPrompt,
  enablePromptCaching: boolean,
  options?: { skipGlobalCacheForSystemPrompt?: boolean; querySource?: QuerySource },
): TextBlockParam[] {
  return splitSysPromptPrefix(systemPrompt, {
    skipGlobalCacheForSystemPrompt: options?.skipGlobalCacheForSystemPrompt,
  }).map(block => ({
    type: 'text' as const,
    text: block.text,
    ...(enablePromptCaching && block.cacheScope !== null && {
      cache_control: getCacheControl({
        scope: block.cacheScope,
        querySource: options?.querySource,
      }),
    }),
  }))
}

映射规则很直观：cacheScope 不为 null 的块获得 cache_control 属性，null 的块则没有。API 后端根据 cache_control.scope 的值（'global' 或 'org'）决定缓存的共享范围。

5.6 系统提示词的构建流程

5.6.1 getSystemPrompt 的完整流程

getSystemPrompt（restored-src/src/constants/prompts.ts:444-577）是系统提示词构建的主入口。它接受工具列表、模型名称、额外工作目录和 MCP 客户端列表，返回一个 string[] 数组。

flowchart TD
    A["getSystemPrompt(tools, model, dirs, mcpClients)"] --> B{"CLAUDE_CODE_SIMPLE?"}
    B -->|"是"| C["返回最小提示词\n(仅身份 + CWD + 日期)"]
    B -->|"否"| D["并行计算:\nskillToolCommands\noutputStyleConfig\nenvInfo"]
    D --> E{"Proactive 模式?"}
    E -->|"是"| F["返回自治 Agent 提示词\n(精简版，无段落注册)"]
    E -->|"否"| G["构建动态段落数组\n(systemPromptSection ×N)"]
    G --> H["resolveSystemPromptSections\n(并行解析，记忆化)"]
    H --> I["组装最终数组"]

    I --> J["静态区:\nintro, system, tasks,\nactions, tools, tone,\nefficiency"]
    J --> K["BOUNDARY MARKER\n(条件插入)"]
    K --> L["动态区:\nsession_guidance, memory,\nenv_info, language,\noutput_style, mcp, ..."]
    L --> M["filter(s => s !== null)"]
    M --> N["返回 string[]"]

图 5-4：系统提示词构建流程图。 从入口到最终返回的完整数据流。

构建过程有三个快速路径（fast path）：

1. CLAUDE_CODE_SIMPLE 模式：环境变量 CLAUDE_CODE_SIMPLE 为真时，直接返回一个只含身份、工作目录和日期的最小提示词。这主要用于测试和调试场景。
2. Proactive 模式：当启用了 PROACTIVE 或 KAIROS 特性标志且处于活跃状态时，返回一个精简的自治 Agent 提示词。注意这条路径不经过段落注册表，而是直接拼装字符串数组。
3. 标准路径：经过完整的段落注册、解析、静态/动态分区流程。

5.6.2 段落注册表一览

标准路径中注册的动态段落（restored-src/src/constants/prompts.ts:491-555）构成了动态区的全部内容：

唯一的 DANGEROUS_uncachedSystemPromptSection 是 mcp_instructions – 这与 5.3 节的分析一致。所有其他段落都是记忆化的，在会话生命周期内计算一次后不再变化。

5.7 buildEffectiveSystemPrompt 的优先级

getSystemPrompt 构建的是“默认系统提示词“。但在实际调用中，还有多个来源可能覆盖或补充这个默认值。buildEffectiveSystemPrompt（restored-src/src/utils/systemPrompt.ts:41-123）负责按优先级合成最终的有效提示词。

5.7.1 优先级链

优先级 0 (最高): overrideSystemPrompt
  ↓ 不存在时
优先级 1: coordinator system prompt
  ↓ 不存在时
优先级 2: agent system prompt
  ↓ 不存在时
优先级 3: customSystemPrompt (--system-prompt)
  ↓ 不存在时
优先级 4 (最低): defaultSystemPrompt (getSystemPrompt 的输出)

+ appendSystemPrompt 始终追加在末尾 (除 override 外)

5.7.2 各优先级的行为

Override（覆盖）： 当 overrideSystemPrompt 存在时（例如 Loop 模式设置的循环指令），直接返回只包含该字符串的数组，忽略所有其他来源，包括 appendSystemPrompt（restored-src/src/utils/systemPrompt.ts:56-58）：

if (overrideSystemPrompt) {
  return asSystemPrompt([overrideSystemPrompt])
}

Coordinator（协调器）： 当启用了 COORDINATOR_MODE 特性标志且 CLAUDE_CODE_COORDINATOR_MODE 环境变量为真时，使用协调器专用的系统提示词替代默认值。注意这里通过懒加载（lazy require）引入 coordinatorMode 模块，避免循环依赖（restored-src/src/utils/systemPrompt.ts:62-75）。

Agent（代理）： 当设置了 mainThreadAgentDefinition 时，行为取决于是否处于 Proactive 模式：

• Proactive 模式下：Agent 指令被追加到默认提示词末尾，而非替换。这是因为 Proactive 模式的默认提示词已经是精简的自治 Agent 身份，Agent 定义只是在其上添加领域指令 – 与 teammates 模式下的行为一致。
• 普通模式下：Agent 指令替换默认提示词。

Custom（自定义）： --system-prompt 命令行参数指定的提示词，替换默认提示词。

Default（默认）： getSystemPrompt 的完整输出。

Append（追加）： 如果设置了 appendSystemPrompt，它被追加到最终数组的末尾。这提供了一种在不完全覆盖系统提示词的情况下注入额外指令的机制。

5.7.3 最终合成逻辑

当没有 override 和 coordinator 时，核心的三路选择逻辑如下（restored-src/src/utils/systemPrompt.ts:115-122）：

return asSystemPrompt([
  ...(agentSystemPrompt
    ? [agentSystemPrompt]
    : customSystemPrompt
      ? [customSystemPrompt]
      : defaultSystemPrompt),
  ...(appendSystemPrompt ? [appendSystemPrompt] : []),
])

这是一个清晰的三元链（ternary chain）：Agent > Custom > Default，加上可选的 append。asSystemPrompt 是一个品牌类型（branded type）转换，确保返回值的类型安全（详见第8章关于类型系统的讨论）。

5.8 缓存优化契约：设计约束与陷阱

系统提示词架构建立了一个隐式的缓存优化契约（cache optimization contract），违反这个契约会导致缓存命中率断崖式下降。以下是从源码中提炼的关键约束：

约束1：静态区不可含会话变量

如 5.4.3 节所述，边界前的任何条件分支都会指数级增加哈希变体数量。PR #24490 和 #24171 记录了这类 bug：开发者不慎将一个 if (hasAgentTool) 条件放入静态区，导致全局缓存命中率从 95% 暴跌至不到 10%。

约束2：DANGEROUS 段落必须有充分理由

DANGEROUS_uncachedSystemPromptSection 的每次使用都在代码审查中接受审视。reason 参数虽然在运行时不被使用（注意参数名的 _ 前缀：_reason），但它是 PR 审查的锚点 – 审查者会检查理由是否充分、是否有替代方案可以降级为记忆化段落。

约束3：MCP 工具触发全局缓存降级

当存在 MCP 工具时，splitSysPromptPrefix 自动降级到 org 级别缓存。这个决策基于一个工程判断：MCP 工具的 schema 是用户级别的动态内容，即便系统提示词中的静态区可以全局缓存，工具 schema 块的存在意味着 API 请求中已经有了无法全局缓存的大块内容，系统提示词的全局缓存带来的边际收益不足以证明额外的复杂性。

约束4：边界标记的位置是架构不变量

源码中的注释直言不讳（restored-src/src/constants/prompts.ts:572）：

// === BOUNDARY MARKER - DO NOT MOVE OR REMOVE ===

移动或删除边界标记不是一个代码变更 – 它是一个架构变更，会改变所有第一方用户的缓存行为。

5.8 模式提炼

从系统提示词架构中，可以提炼出以下可复用的工程模式：

模式 1：分段记忆化（Sectioned Memoization）

• 解决的问题： 大型提示词中部分内容是静态的、部分是动态的，全量重算浪费资源。
• 方案： 将提示词拆分为独立段落，每个段落有明确的缓存策略（记忆化 vs. 易变）。通过工厂函数区分两种类型，并为易变类型增加 API 摩擦（DANGEROUS_ 前缀 + 必填 reason）。
• 前置条件： 需要全局状态管理器持有缓存 Map，以及明确的缓存失效时机（如 /clear、/compact）。
• 代码模板：

  memoizedSection(name, computeFn)        → 首次计算后缓存
  volatileSection(name, computeFn, reason) → 每轮重算，需说明理由
  resolveAll(sections)                     → Promise.all 并行解析
  

模式 2：缓存边界分治（Cache Boundary Partitioning）

• 解决的问题： 多用户共享的提示词前缀需要全局缓存，但会话特定的内容破坏缓存命中率。
• 方案： 在提示词数组中插入显式的边界标记，将内容分为“全局可缓存的静态区“和“每会话的动态区“。下游函数根据边界位置分配不同的 cacheScope。
• 前置条件： API 后端支持多级缓存作用域（如 global / org / null）。
• 关键约束： 边界前的静态区中不能包含任何因会话而异的条件分支，否则哈希变体数量指数增长。

模式 3：优先级链合成（Priority Chain Composition）

• 解决的问题： 多个来源（用户自定义、Agent 模式、协调器模式、默认值）都可能提供系统提示词，需要明确的优先级。
• 方案： 定义一条线性优先级链（override > coordinator > agent > custom > default），加上一个始终追加的 append 机制。使用三元链（ternary chain）保持代码的线性可读性。
• 前置条件： 各优先级来源的输入接口统一（均为 string | string[]）。

5.9 用户能做什么

基于本章分析的系统提示词架构，以下是读者可以在自己的 AI Agent 项目中直接应用的建议：

1. 为你的提示词建立分段注册表。 不要将系统提示词硬编码为单一字符串。将其拆分为独立的、有名称的段落，每个段落标注是否可缓存。这样做的收益不仅是缓存效率，更是可维护性 – 当需要修改某个行为指令时，你可以精确定位到对应的段落，而不是在一个巨大的字符串中搜索。

2. 为易变段落增加 API 摩擦。 如果你的系统中有部分提示词内容需要每轮重算（如动态工具列表、实时状态信息），参考 DANGEROUS_uncachedSystemPromptSection 的设计：要求调用者提供“为什么需要每轮重算“的理由。这种摩擦在代码审查中尤其有价值 – 它迫使开发者显式权衡缓存效率与内容新鲜度。

3. 将会话变量赶到缓存边界之后。 如果你使用的 API 支持 prompt caching，确保提示词的前缀部分（缓存键的计算范围）不包含因用户、会话或运行时状态而异的内容。Claude Code 的 SYSTEM_PROMPT_DYNAMIC_BOUNDARY 标记是这种策略的直接实现。

4. 定义清晰的提示词优先级链。 当你的系统支持多种运行模式（自治 Agent、协调器、用户自定义等），为每种模式的提示词来源定义明确的优先级。避免“合并“不同来源的提示词 – 使用“替换“语义更安全、更可预测。

5. 监控缓存命中率。 系统提示词架构的价值完全体现在缓存命中率上。如果你的缓存命中率突然下降，检查是否有新的条件分支被引入到静态区中 – 这是 Claude Code 团队在 PR #24490 中踩过的坑。

5.10 小结

系统提示词架构是 Claude Code 中“看不见但处处生效“的基础设施。它的设计体现了三个核心原则：

1. 分段组合：通过 systemPromptSection 注册表将提示词分解为独立的、可记忆化的段落，每个段落有明确的名称、计算函数和缓存策略。
2. 边界分治：SYSTEM_PROMPT_DYNAMIC_BOUNDARY 标记将内容分为全局可缓存的静态区和每会话的动态区，splitSysPromptPrefix 的三条路径根据运行时条件选择最优的缓存策略。
3. 优先级合成：buildEffectiveSystemPrompt 通过清晰的五级优先级链（override > coordinator > agent > custom > default + append）支持多种运行模式，同时保持代码的线性可读性。

这个架构的“成功标准“不是功能的正确性 – 即使把整个系统提示词硬编码为单一字符串，功能上也完全可用。它的价值在于成本效率：通过精心的缓存层级设计，在每天数百万次 API 调用中节省大量的 prompt 处理开销。下一章将讨论系统提示词架构的一个关键输入 – CLAUDE.md 内存文件系统如何被加载和注入（详见第6章）。

第6章：通过提示词引导行为

第5章剖析了系统提示词的组装架构 – 段落注册、缓存边界、多来源合成。但架构只是骨骼，真正让 Claude Code 表现出“像一个有经验的工程师“的，是骨骼上附着的肌肉：那些精心措辞的行为指令。本章将提炼出 6 种可复用的行为引导模式（behavior steering pattern），每种模式都有源码原文、生效原理、以及你可以直接搬进自己提示词的模板。

6.1 行为引导的本质：在生成概率空间中设定边界

大语言模型的输出是一个概率分布上的采样过程。系统提示词中的行为指令，本质上是在这个概率空间中竖起围栏 – 提高期望行为的概率，压低不期望行为的概率。但围栏的措辞方式，决定了它是一堵坚固的墙还是一条模糊的线。

通读 Claude Code 的系统提示词源码（restored-src/src/constants/prompts.ts 与 restored-src/src/tools/BashTool/prompt.ts），可以发现 Anthropic 的工程师们并非随意堆砌指令，而是形成了一套隐含的模式语言（pattern language）。这些模式之所以有效，不仅因为它们“说了正确的话“，更因为它们在措辞结构上暗合了模型的注意力机制和指令遵循特性。

本章将这些模式显式化，命名为 6 种行为引导模式：

1. 极简主义指令（Minimalism Directive）
2. 渐进式升级（Progressive Escalation）
3. 可逆性意识（Reversibility Awareness）
4. 工具偏好引导（Tool Preference Steering）
5. Agent 委托指引（Agent Delegation Protocol）
6. 数值锚定（Numeric Anchoring）

6.2 模式一：极简主义指令（Minimalism Directive）

6.2.1 模式定义

核心思想： 通过明确禁止过度工程，将模型的“乐于助人“倾向限制在任务实际需要的范围内。

大语言模型天生倾向于“多做一点“ – 添加额外的错误处理、补充文档注释、引入抽象层。这在对话场景中是美德，但在代码生成场景中却是灾难。极简主义指令通过具体的反面案例，让模型知道“不做什么“比“做什么“更重要。

6.2.2 源码实例

实例 1：三行代码优于过早抽象

Don't create helpers, utilities, or abstractions for one-time operations.
Don't design for hypothetical future requirements. The right amount of
complexity is what the task actually requires — no speculative abstractions,
but no half-finished implementations either. Three similar lines of code
is better than a premature abstraction.

源码位置： restored-src/src/constants/prompts.ts:203

这段指令的最后一句 “Three similar lines of code is better than a premature abstraction” 是整个极简主义指令中最精彩的一笔。它给出了一个具体的数量门槛 – 三行 – 让模型在面对“要不要提取一个公共函数“的决策时，有了明确的判断基准。没有这个锚点，模型会默认倾向于 DRY（Don’t Repeat Yourself），而 DRY 在 AI 辅助编程的语境中常常导致过度抽象。

实例 2：不要添加超出要求的功能

Don't add features, refactor code, or make "improvements" beyond what was
asked. A bug fix doesn't need surrounding code cleaned up. A simple feature
doesn't need extra configurability. Don't add docstrings, comments, or type
annotations to code you didn't change. Only add comments where the logic
isn't self-evident.

源码位置： restored-src/src/constants/prompts.ts:201

注意这段指令的结构：先是一个总原则（“不要添加超出要求的功能”），然后是三个具体的反面案例（bug 修复不需要清理周围代码、简单功能不需要额外配置性、不要给未修改的代码加注释）。这种“总则 + 反面案例“的结构非常有效，因为模型在遵循指令时需要将抽象原则映射到具体场景，而反面案例提供了这种映射的锚点。

实例 3：不要为不可能的场景添加防御（ant-only）

Don't add error handling, fallbacks, or validation for scenarios that can't
happen. Trust internal code and framework guarantees. Only validate at system
boundaries (user input, external APIs). Don't use feature flags or
backwards-compatibility shims when you can just change the code.

源码位置： restored-src/src/constants/prompts.ts:202

这条指令直击一个常见的 LLM 行为模式：过度防御性编程。模型在训练数据中见过大量的“最佳实践“文章，这些文章强调处理每一种可能的错误。但在实际的内部代码中，许多错误路径永远不会被触发。这条指令通过“Trust internal code and framework guarantees“这个短语，赋予模型一个新的判断框架：区分系统边界和内部调用。

6.2.3 为什么有效

极简主义指令之所以有效，源于三个机制：

1. 反面案例比正面规则更容易遵循。 “不要做 X“比“只做 Y“更精确，因为 X 的边界比 Y 的边界更清晰。模型可以将生成的每个 token 与“这是不是在做 X“进行对照。
2. 具体数量打破默认启发式。 “三行重复代码“这样的数量锚定，覆盖了模型内置的 DRY 启发式。没有具体数字，模型会回退到训练数据中最常见的模式。
3. 场景分类减少歧义。 “bug 修复不需要清理周围代码“这类指令，将一个模糊的“什么时候该多做一点“问题，转化为一个明确的分类任务：“当前任务是 bug 修复还是重构？”

6.2.4 可复用模板

[极简主义指令模板]

不要在任务范围之外添加 {功能/重构/改进}。
{任务类型 A} 不需要 {常见的过度工程行为 A}。
{任务类型 B} 不需要 {常见的过度工程行为 B}。
{N} 行重复代码优于过早抽象。
只在 {明确的边界条件} 时才 {采取额外行动}。

6.3 模式二：渐进式升级（Progressive Escalation）

6.3.1 模式定义

核心思想： 在“放弃“和“死循环“之间定义一条中间路径，引导模型先诊断、再调整、最后求助。

LLM 在面对失败时有两种极端倾向：要么立即放弃并请求用户帮助，要么不断重试完全相同的操作。渐进式升级模式通过定义一个明确的三阶段协议 – 诊断、调整、求助 – 将模型的失败响应锁定在合理的范围内。

6.3.2 源码实例

实例 1：失败处理三阶段

If an approach fails, diagnose why before switching tactics — read the error,
check your assumptions, try a focused fix. Don't retry the identical action
blindly, but don't abandon a viable approach after a single failure either.
Escalate to the user with ask_user_question only when you're genuinely stuck
after investigation, not as a first response to friction.

源码位置： restored-src/src/constants/prompts.ts:233

这段指令在一个段落中定义了完整的失败处理协议：

• 阶段 1（诊断）： “read the error, check your assumptions” – 先理解发生了什么
• 阶段 2（调整）： “try a focused fix” – 基于诊断结果做有针对性的修改
• 阶段 3（求助）： “Escalate to the user… only when you’re genuinely stuck” – 在真正的死胡同处才请求帮助

关键的设计在于两个“不要“之间的张力：“Don’t retry the identical action blindly”（禁止死循环）和 “don’t abandon a viable approach after a single failure”（禁止过早放弃）。这种双边约束迫使模型在两个极端之间寻找中间路径。

实例 2：Git 操作中的诊断优先

Before running destructive operations (e.g., git reset --hard, git push
--force, git checkout --), consider whether there is a safer alternative
that achieves the same goal. Only use destructive operations when they are
truly the best approach.

源码位置： restored-src/src/tools/BashTool/prompt.ts:306

这条指令要求在执行高风险操作前进行一次“是否有更安全的替代方案“的评估。它不是简单地禁止这些操作，而是要求模型在选择之前完成一个推理步骤。

实例 3：Sleep 命令的诊断替代

Do not retry failing commands in a sleep loop — diagnose the root cause.

源码位置： restored-src/src/tools/BashTool/prompt.ts:318

这是渐进式升级模式的最简形式：一句话同时包含禁止（“不要在 sleep 循环中重试”）和替代方案（“诊断根本原因”）。它特别针对一个常见的 LLM 行为模式 – 当命令失败时，模型可能会在循环中 sleep && retry，这在交互式环境中是灾难性的。

6.3.3 为什么有效

渐进式升级的有效性来自于：

1. 双边约束创造张力。 同时定义“不要太快放弃“和“不要无限重试“，让模型在每次失败后必须进行一次显式的推理：“我是在盲目重试，还是在做有信息量的调整？”
2. 阶段顺序映射到 Chain-of-Thought。 诊断 -> 调整 -> 求助的顺序，与模型的推理链（chain of thought）自然对齐。模型可以将这个协议直接编码为思维链中的步骤。
3. 求助作为最后手段。 将“问用户“设定为最后选项，减少了不必要的交互中断，提高了自主完成率。

6.3.4 可复用模板

[渐进式升级模板]

当 {操作} 失败时，先 {诊断动作}（{具体诊断步骤列表}）。
不要盲目重试相同的操作，但也不要在一次失败后就放弃可行的方案。
只在 {升级条件} 时才 {升级动作}，而非将其作为遇到阻力时的第一反应。

6.4 模式三：可逆性意识（Reversibility Awareness）

6.4.1 模式定义

核心思想： 按照操作的可逆性和影响范围分级，对高风险操作建立确认框架。

这是 Claude Code 提示词工程中最复杂、也最精心设计的模式。它不是简单地列出“危险操作“，而是建立了一个完整的风险评估框架，教会模型“三思而后行“（measure twice, cut once）。

6.4.2 源码实例

实例 1：可逆性分析框架

Carefully consider the reversibility and blast radius of actions. Generally
you can freely take local, reversible actions like editing files or running
tests. But for actions that are hard to reverse, affect shared systems beyond
your local environment, or could otherwise be risky or destructive, check
with the user before proceeding.

源码位置： restored-src/src/constants/prompts.ts:258

这段指令引入了两个关键维度：可逆性（reversibility） 和影响范围（blast radius）。这两个维度构成一个 2x2 决策矩阵：

quadrantChart
    title 可逆性与影响范围的决策矩阵
    x-axis "小影响范围" --> "大影响范围"
    y-axis "不可逆 (hard to reverse)" --> "可逆 (reversible)"
    quadrant-1 "告知后执行"
    quadrant-2 "自由执行"
    quadrant-3 "确认后执行"
    quadrant-4 "强制确认"
    "编辑文件": [0.25, 0.8]
    "运行测试": [0.3, 0.85]
    "创建临时分支": [0.7, 0.75]
    "删除本地文件": [0.25, 0.25]
    "force push": [0.8, 0.15]
    "关闭 PR/issue": [0.75, 0.2]

图 6-1：可逆性与影响范围的决策矩阵。 Claude Code 通过这两个维度将操作分为四类，从“自由执行“到“强制确认“。

实例 2：高风险操作详尽列表

源码提供了四大类需要确认的操作，每一类都附有具体例子（restored-src/src/constants/prompts.ts:261-264）：

实例 3：Git 安全协议

Git Safety Protocol:
- NEVER update the git config
- NEVER run destructive git commands (push --force, reset --hard, checkout .,
  restore ., clean -f, branch -D) unless the user explicitly requests these
  actions.
- NEVER skip hooks (--no-verify, --no-gpg-sign, etc) unless the user
  explicitly requests it
- NEVER run force push to main/master, warn the user if they request it
- CRITICAL: Always create NEW commits rather than amending, unless the user
  explicitly requests a git amend. When a pre-commit hook fails, the commit
  did NOT happen — so --amend would modify the PREVIOUS commit, which may
  result in destroying work or losing previous changes.

源码位置： restored-src/src/tools/BashTool/prompt.ts:87-94

Git 安全协议是可逆性意识模式的最精致实现。注意几个设计要点：

1. NEVER 大写 – 不是“避免“或“尽量不要“，而是绝对禁止。大写字母在提示词中起到类似“提高注意力权重“的作用。
2. “unless the user explicitly requests” – 每条 NEVER 规则都附带一个明确的豁免条件，避免模型在用户明确要求时仍然拒绝。
3. CRITICAL 标记 + 因果解释 – 对于 amend vs. new commit 这个最微妙的规则，不仅标记了 CRITICAL，还解释了为什么这条规则存在（hook 失败时 commit 尚未发生，amend 会修改前一个 commit）。因果解释让模型能在新场景中泛化规则的精神，而不仅仅机械地遵循字面意思。

实例 4：一次授权不等于永久授权

A user approving an action (like a git push) once does NOT mean that they
approve it in all contexts, so unless actions are authorized in advance in
durable instructions like CLAUDE.md files, always confirm first.
Authorization stands for the scope specified, not beyond. Match the scope
of your actions to what was actually requested.

源码位置： restored-src/src/constants/prompts.ts:258

这条指令直击 LLM 的一个危险倾向：从单次许可推广到通用许可。模型在上下文中看到用户之前同意了 git push，可能会在后续的不同场景中不经确认就执行 push。这条规则通过“scope specified, not beyond“这个表述，建立了一个精确的授权作用域概念。

6.4.3 为什么有效

可逆性意识的有效性来自：

1. 维度分析替代枚举。 与其列出所有危险操作（不可能穷举），不如教会模型使用“可逆性“和“影响范围“两个维度自主评估。具体的例子列表起辅助校准作用，而非完整覆盖。
2. NEVER + unless 的精确豁免。 绝对禁止 + 明确例外的组合，避免了模型在模糊地带的“创造性解读“。
3. 因果解释促进泛化。 解释“为什么“这条规则存在（如 amend 的因果链），让模型能在未见过的场景中推导出正确行为。
4. “measure twice, cut once“的助记性。 文末的这个英语成语，作为整个框架的认知锚点，帮助模型在面对边界情况时回忆起整个风险评估协议。

6.4.4 可复用模板

[可逆性意识模板]

在执行操作前，评估其可逆性和影响范围。
你可以自由执行 {可逆的本地操作列表}。
对于 {不可逆/影响共享系统} 的操作，在执行前与用户确认。

绝对不要（NEVER）：
- {危险操作 1}，除非用户明确要求
- {危险操作 2}，除非用户明确要求
- [关键] {最微妙的危险操作}，因为 {因果解释}

用户一次批准 {操作} 不代表在所有上下文中批准。
授权仅限于指定的范围。

6.5 模式四：工具偏好引导（Tool Preference Steering）

6.5.1 模式定义

核心思想： 通过工具描述文本将模型的工具选择从通用 Bash 命令重定向到专用工具。

Claude Code 提供了丰富的专用工具（Read、Edit、Write、Glob、Grep），但模型的训练数据中充斥着 cat、grep、sed、find 等 Unix 命令。如果不加引导，模型会自然倾向于通过 Bash 工具执行这些命令。工具偏好引导模式在工具描述的最早位置插入重定向指令，截获模型的默认工具选择路径。

6.5.2 源码实例

实例 1：Bash 工具描述中的前置拦截

IMPORTANT: Avoid using this tool to run find, grep, cat, head, tail, sed,
awk, or echo commands, unless explicitly instructed or after you have
verified that a dedicated tool cannot accomplish your task. Instead, use the
appropriate dedicated tool as this will provide a much better experience for
the user:

 - File search: Use Glob (NOT find or ls)
 - Content search: Use Grep (NOT grep or rg)
 - Read files: Use Read (NOT cat/head/tail)
 - Edit files: Use Edit (NOT sed/awk)
 - Write files: Use Write (NOT echo >/cat <<EOF)
 - Communication: Output text directly (NOT echo/printf)

源码位置： restored-src/src/tools/BashTool/prompt.ts:280-291（由 getSimplePrompt() 拼装）

这段指令的设计有三层精巧之处：

1. 位置优先。 这段文本出现在 Bash 工具描述的开头区域，紧跟工具的基本功能说明之后。当模型开始考虑调用 Bash 工具时，这段重定向指令是它首先遇到的约束。
2. NOT 括号对照。 每条映射规则都同时列出“应该用什么“和“不应该用什么“。Use Grep (NOT grep or rg) 这种格式创造了一个直接的二选一对照，减少了模型的决策犹豫。
3. 用户体验论证。 “this will provide a much better experience for the user” 给出了遵循此规则的理由，而非仅仅作为一个无条件命令。

实例 2：系统提示词中的冗余强化

Do NOT use the Bash to run commands when a relevant dedicated tool is
provided. Using dedicated tools allows the user to better understand and
review your work. This is CRITICAL to assisting the user:
  - To read files use Read instead of cat, head, tail, or sed
  - To edit files use Edit instead of sed or awk
  - To create files use Write instead of cat with heredoc or echo redirection
  - To search for files use Glob instead of find or ls
  - To search the content of files, use Grep instead of grep or rg
  - Reserve using the Bash exclusively for system commands and terminal
    operations that require shell execution.

源码位置： restored-src/src/constants/prompts.ts:291-302

注意这段内容与 Bash 工具描述中的映射表几乎重复。这不是疏忽，而是有意为之的冗余强化（redundant reinforcement）。在系统提示词和工具描述两个位置都放置相同的指令，确保无论模型的注意力路径从哪里经过，都会遇到这个约束。

实例 3：嵌入式工具的条件适配

const embedded = hasEmbeddedSearchTools()

const toolPreferenceItems = [
  ...(embedded
    ? []
    : [
        `File search: Use ${GLOB_TOOL_NAME} (NOT find or ls)`,
        `Content search: Use ${GREP_TOOL_NAME} (NOT grep or rg)`,
      ]),
  `Read files: Use ${FILE_READ_TOOL_NAME} (NOT cat/head/tail)`,
  // ...
]

源码位置： restored-src/src/tools/BashTool/prompt.ts:280-291

当 Ant 内部构建版本（ant-native builds）将 find 和 grep 通过 shell alias 映射到嵌入式的 bfs 和 ugrep 时，指向 Glob/Grep 专用工具的重定向就变得不必要了。源码通过 hasEmbeddedSearchTools() 条件判断，在这种情况下跳过这两条映射。这种条件适配确保了提示词不会包含自相矛盾的指令。

6.5.3 为什么有效

工具偏好引导的有效性来自：

1. 截获决策路径的最早点。 模型在选择工具时，首先读取工具描述。在 Bash 工具的描述中插入“不要用我做 X，去用 Y“，相当于在模型做出选择之前就进行了干预。
2. 二选一对照消除歧义。 Use Grep (NOT grep or rg) 的格式将一个开放性选择（“用哪个工具搜索”）转化为一个二元判断（“用 Grep 工具还是 grep 命令”），降低了决策复杂度。
3. 冗余强化覆盖注意力盲区。 模型的注意力在长上下文中会衰减。在两个不同位置放置相同约束，提高了约束被“看见“的概率。

6.5.4 可复用模板

[工具偏好引导模板]

当需要 {操作类别} 时，使用 {专用工具名}（而非 {通用替代命令列表}）。
使用专用工具可以 {用户体验收益}。

{通用工具名} 仅用于 {明确的合法用途列表}。
如果不确定，默认使用专用工具，只在 {回退条件} 时使用 {通用工具名}。

6.6 模式五：Agent 委托指引（Agent Delegation Protocol）

6.6.1 模式定义

核心思想： 为多 Agent 协作定义精确的委托规则，防止递归派生、上下文污染和结果捏造。

当一个 AI 系统可以派生子 Agent 时，新的失败模式随之出现：Agent 可能无限递归派生自己、可能窥探子 Agent 的中间输出（污染自己的上下文）、可能在子 Agent 返回结果前就编造结果。Agent 委托指引模式通过一组精确的规则来防止这些失败模式。

6.6.2 源码实例

实例 1：Fork vs. 全新 Agent 的选择框架

Fork yourself (omit subagent_type) when the intermediate tool output isn't
worth keeping in your context. The criterion is qualitative — "will I need
this output again" — not task size.
- Research: fork open-ended questions. If research can be broken into
  independent questions, launch parallel forks in one message. A fork beats
  a fresh subagent for this — it inherits context and shares your cache.
- Implementation: prefer to fork implementation work that requires more than
  a couple of edits.

源码位置： restored-src/src/tools/AgentTool/prompt.ts:83-88

这段指令建立了 fork（继承上下文的分叉）和 fresh agent（全新 Agent）之间的选择标准。关键洞察是判断标准不是任务大小，而是“我以后还需要看这些输出吗“。这个定性标准虽然模糊，但配合下面两个具体场景（研究和实现），为模型提供了足够的锚点。

实例 2：“不要偷看” – 上下文卫生规则

Don't peek. The tool result includes an output_file path — do not Read or
tail it unless the user explicitly asks for a progress check. You get a
completion notification; trust it. Reading the transcript mid-flight pulls
the fork's tool noise into your context, which defeats the point of forking.

源码位置： restored-src/src/tools/AgentTool/prompt.ts:91

“Don’t peek”（不要偷看）可能是整个 Claude Code 提示词中最具创意的短语之一。它用两个日常词汇精确描述了一个复杂的技术约束：不要读取子 Agent 的中间输出文件。随后的解释给出了原因 – 这样做会将子 Agent 的工具噪声拉入主 Agent 的上下文，违背了 fork 的初衷（保持主上下文干净）。

这条规则对应的工程问题是：fork 子 Agent 的结果会写入一个文件，主 Agent 有能力通过 Read 工具读取这个文件。如果主 Agent 在子 Agent 完成前读取了中间结果，那些半成品的工具调用输出就会进入主 Agent 的上下文窗口，浪费宝贵的 token 预算。

实例 3：“不要竞争” – 结果捏造防护

Don't race. After launching, you know nothing about what the fork found.
Never fabricate or predict fork results in any format — not as prose,
summary, or structured output. The notification arrives as a user-role
message in a later turn; it is never something you write yourself. If the
user asks a follow-up before the notification lands, tell them the fork is
still running — give status, not a guess.

源码位置： restored-src/src/tools/AgentTool/prompt.ts:93

“Don’t race”（不要竞争）防止了一种微妙但危险的失败模式：主 Agent 在派出 fork 后，可能会“预测“fork 的结果并提前生成回复。这种行为在用户看来可能像是“聪明的预判“，但实际上是纯粹的幻觉 – 主 Agent 根本不知道 fork 发现了什么。

这段指令的设计格外严格：不仅禁止“编造结果“，还明确禁止了所有可能的变体形式 – “not as prose, summary, or structured output”。这种穷举式的格式禁止，是因为模型可能会尝试以不同的输出形式来规避字面上的禁止。

实例 4：Fork 子 Agent 的身份锚定

STOP. READ THIS FIRST.

You are a forked worker process. You are NOT the main agent.

RULES (non-negotiable):
1. Your system prompt says "default to forking." IGNORE IT — that's for the
   parent. You ARE the fork. Do NOT spawn sub-agents; execute directly.
2. Do NOT converse, ask questions, or suggest next steps
3. Do NOT editorialize or add meta-commentary
...
6. Do NOT emit text between tool calls. Use tools silently, then report
   once at the end.

源码位置： restored-src/src/tools/AgentTool/forkSubagent.ts:172-194

这是委托协议中最戏剧性的片段。fork 子 Agent 继承了父 Agent 的完整系统提示词，而父提示词中包含“default to forking“的指令。如果不加干预，子 Agent 会读到这条指令并尝试再次 fork – 造成无限递归。

解决方案是在 fork 子 Agent 的消息开头插入一个“身份覆盖“指令：先以全大写的 “STOP. READ THIS FIRST.” 抢占注意力，然后明确声明“You ARE the fork“，最后直接指出“Your system prompt says ‘default to forking.’ IGNORE IT“。这种“承认矛盾指令的存在并显式覆盖它“的技巧，比简单地希望模型忽略某段提示词要可靠得多。

6.6.3 为什么有效

Agent 委托指引的有效性来自：

1. 拟人化动词建立直觉。 “Don’t peek“和“Don’t race“比“不要读取子 Agent 的输出文件“和“不要在收到通知前生成结果“更容易记忆和遵循。拟人化让抽象的技术约束变成了社交直觉。
2. 穷举式格式禁止。 “not as prose, summary, or structured output” 封堵了模型可能的规避路径。
3. 显式矛盾解决。 承认子 Agent 会看到父 Agent 的“fork“指令，然后显式覆盖，比假设模型会正确处理矛盾指令更可靠。
4. 身份锚定 + 输出格式约束。 fork 子 Agent 的“STOP. READ THIS FIRST.“配合严格的输出格式（Scope: / Result: / Key files: / Files changed: / Issues:），将子 Agent 的行为限定在一个非常狭窄的通道中。

6.6.4 可复用模板

[Agent 委托指引模板]

## 何时 fork
当 {中间输出不值得保留在上下文中} 时，fork 自己。
判断标准是 {定性标准}，而非 {常见误判标准}。

## fork 后的行为
- 不要偷看：{子 Agent} 的中间输出不要读取，等待完成通知。
  原因：{上下文污染的具体后果}。
- 不要竞争：在 {子 Agent} 返回前，不要以任何形式
  （{格式列表}）预测或编造其结果。
  如果用户追问，回复 {状态信息}，而非猜测。

## fork 子 Agent 的身份
你是一个 fork 工作进程，不是主 Agent。
父提示词中的 {可能导致递归的指令} 不适用于你 -- 直接执行，不要再委托。

6.7 模式六：数值锚定（Numeric Anchoring）

6.7.1 模式定义

核心思想： 用精确的数字替代模糊的定性描述，给模型一个可以直接对照的输出标尺。

“简洁一些”、“保持简短”、“不要太冗长” – 这类定性指令几乎没有约束力，因为模型对“简洁“的理解依赖于训练数据中的分布，而这个分布因领域和风格而异。数值锚定通过给出具体数字，将一个主观判断转化为一个可度量的约束。

6.7.2 源码实例

实例 1：工具调用间文字长度限制

Length limits: keep text between tool calls to ≤25 words. Keep final
responses to ≤100 words unless the task requires more detail.

源码位置： restored-src/src/constants/prompts.ts:534

这段指令目前仅对 Anthropic 内部用户（ant-only）启用，附有以下注释：

// Numeric length anchors — research shows ~1.2% output token reduction vs
// qualitative "be concise". Ant-only to measure quality impact first.

源码位置： restored-src/src/constants/prompts.ts:527-528

1.2% 的 output token 削减可能听起来不多，但考虑到 Claude Code 每天处理的请求量，这个百分比在成本节约上的绝对值相当可观。更重要的是，这 1.2% 是仅通过将“be concise“替换为“≤25 words“就获得的 – 零代码变更，纯提示词优化。

注意两个数值锚定的不同设计：

• ≤25 词（工具调用间）：这是一个硬性约束，因为工具调用之间的文字通常是不必要的 – 模型应该直接调用下一个工具，而不是向用户解释自己在做什么。
• ≤100 词（最终响应）：这带有一个豁免条件（“unless the task requires more detail”），因为最终响应的长度确实取决于任务复杂度。

实例 2：fork 子 Agent 的报告长度限制

8. Keep your report under 500 words unless the directive specifies otherwise.
   Be factual and concise.

源码位置： restored-src/src/tools/AgentTool/forkSubagent.ts:186

fork 子 Agent 的 500 词限制服务于一个明确的工程目标：子 Agent 的报告会被注入到主 Agent 的上下文中，过长的报告会浪费主 Agent 的上下文窗口。500 词大约相当于 600-700 个 token，是一个在“提供足够信息“和“节约上下文空间“之间的平衡点。

实例 3：提交消息长度引导

Draft a concise (1-2 sentences) commit message that focuses on the "why"
rather than the "what"

源码位置： restored-src/src/tools/BashTool/prompt.ts:103

“1-2 sentences“是另一种数值锚定形式 – 不是词数，而是句数。这个锚定配合“focuses on the ‘why’ rather than the ‘what’“这个内容指引，同时约束了长度和质量。

6.7.3 ant-only 实验效果

数值锚定模式是 Claude Code 中少数有明确量化效果数据的提示词优化之一：

表 6-1：数值锚定的 ant-only 实验效果。 目前仅对内部用户启用，以便在扩大部署前测量对输出质量的影响。

ant-only 的灰度部署策略本身也值得关注。源码中的条件判断：

...(process.env.USER_TYPE === 'ant'
  ? [
      systemPromptSection(
        'numeric_length_anchors',
        () => 'Length limits: keep text between tool calls to ≤25 words...',
      ),
    ]
  : []),

这种模式在整个 Claude Code 提示词中反复出现：新的行为指令先对内部用户开放，收集数据后再决定是否推广到外部用户。这是提示词工程中的 A/B 测试方法论。

6.7.4 为什么有效

数值锚定的有效性来自：

1. 消除主观解释空间。 “25 words“没有歧义，“concise“有。模型可以在生成每个 token 后计数，判断是否接近阈值。
2. 锚定效应（Anchoring Effect）。 认知心理学研究表明，人类在进行数量估计时会被先前的数字锚定。LLM 的行为与此类似 – 提示词中出现的数字会成为输出长度的参考点。
3. 硬约束 + 软豁免的组合。 “≤25 words“是硬约束，“unless the task requires more detail“是软豁免。这种组合让模型默认遵守数字限制，但在合理情况下可以突破。

6.7.5 可复用模板

[数值锚定模板]

长度限制：
- {输出类型 A} 保持在 ≤{N} 词/句/行以内。
- {输出类型 B} 保持在 ≤{M} 词/句/行以内，除非 {豁免条件}。
保持事实性和简洁性。

6.8 模式汇总

下表总结了本章提炼的 6 种行为引导模式，每种模式附有代表性的源码原文和可直接复用的提示词模板：

表 6-2：6 种行为引导模式汇总。 每种模式都有明确的适用场景和可复用的模板结构。

6.9 跨模式的设计原则

回顾这 6 种模式，可以归纳出几个跨模式的底层设计原则：

原则一：反面定义优于正面描述。 “不要做 X“比“做 Y“更容易被模型遵循，因为禁止的边界比允许的边界更清晰。6 种模式中有 5 种大量使用了“Don’t”/“NEVER”/“NOT“等否定形式。

原则二：具体例子是抽象规则的校准器。 每个抽象规则（“考虑可逆性”）都配有具体的例子列表（“git reset –hard, push –force…”）。例子不是规则的替代品，而是规则的校准点 – 帮助模型理解规则的适用范围和颗粒度。

原则三：因果解释促进泛化。 当规则附带“因为…“的解释时（如 amend vs. new commit 的因果链），模型能在未见过的场景中推导出规则的精神。纯命令式的规则只能在训练分布内生效；因果解释让规则超越字面意思。

原则四：冗余是刻意的。 工具偏好引导在两个位置放置相同的映射表，可逆性意识在系统提示词和 Bash 工具描述中都定义了 Git 安全规则。这种冗余不是疏忽，而是对抗注意力衰减的工程手段。

原则五：灰度部署是提示词工程的一部分。 数值锚定的 ant-only 实验表明，提示词修改也需要 A/B 测试和灰度发布 – 就像代码变更一样。USER_TYPE === 'ant' 条件判断是这种方法论在代码中的体现。

6.10 用户能做什么

基于本章提炼的 6 种行为引导模式，以下是读者可以直接搬进自己提示词的实操建议：

1. 用“不要做 X“替代“做 Y“。 审视你现有的提示词，将正面描述转化为反面约束。“生成简洁的代码“不如“不要添加超出要求的功能。bug 修复不需要清理周围代码。“具体的反面案例比抽象的正面目标更容易被模型遵循。

2. 为失败场景定义三阶段协议。 如果你的 Agent 需要处理可能失败的操作（API 调用、命令执行、文件操作），在提示词中明确定义“诊断 -> 调整 -> 求助“的升级路径。同时禁止两个极端：盲目重试和一次失败就放弃。

3. 用数字替代形容词。 将“保持简洁“替换为“≤25 词“或“1-2 句“。Claude Code 的数据显示，仅这一项改动就带来了 1.2% 的 output token 削减。在你自己的场景中，为每种输出类型设定具体的数量上限。

4. 在工具描述中插入重定向表。 如果你的工具集中有一个“万能工具“（如 Bash），在其描述的最早位置列出“什么场景该用什么替代工具“的映射表。同时在专用工具的描述中声明排他性。双向闭环比单向约束有效得多。

5. 为高风险操作建立可逆性评估框架。 不要简单地列出“危险操作清单“（不可能穷举），而是教会模型使用“可逆性“和“影响范围“两个维度自主评估。配合 NEVER + unless 的精确豁免结构，给模型一个可执行的决策框架。

6. 先在小范围灰度验证。 新的行为指令先对一小部分用户或场景开放，收集效果数据后再推广。Claude Code 的 USER_TYPE === 'ant' 灰度机制是一个可参考的模式 – 提示词修改也需要 A/B 测试。

6.11 小结

本章从 Claude Code 的源码中提炼了 6 种命名的行为引导模式。这些模式不是随意的措辞选择，而是经过实验验证的工程实践 – 从极简主义指令的“三行代码“锚点，到数值锚定的 1.2% token 削减，每种模式都有其明确的设计意图和可度量的效果。

这些模式的共同特征是精确性：用具体数字替代模糊形容词、用反面案例替代正面描述、用因果解释替代无条件命令。这种精确性不是偶然的 – 它反映了一个基本事实：大语言模型遵循指令的可靠性，与指令的精确度正相关。

下一章将转向运行时行为的观察与调试：当这些精心设计的提示词在实际对话中遇到意外情况时，系统如何检测、记录和应对。

第7章：模型特定调优与 A/B 测试

第6章探讨了系统提示词如何被组装为发送给模型的指令集。但同一份提示词并非适用于所有模型 – 每个模型世代都有独特的行为倾向，而 Anthropic 内部用户需要比外部用户更早地接触和验证新模型。本章将揭示 Claude Code 如何通过 @[MODEL LAUNCH] 注解系统、USER_TYPE === 'ant' 门控、GrowthBook Feature Flag 和 Undercover 模式，实现模型特定的提示词调优、内部 A/B 测试以及安全的公开仓库贡献。

7.1 模型发布检查清单：@[MODEL LAUNCH] 注解

在 Claude Code 的代码库中，散布着一种特殊的注释标记：

// @[MODEL LAUNCH]: Update the latest frontier model.
const FRONTIER_MODEL_NAME = 'Claude Opus 4.6'

源码参考： constants/prompts.ts:117-118

这些 @[MODEL LAUNCH] 注解不是普通注释。它们构成了一个分布式检查清单（distributed checklist） – 当新模型准备发布时，工程师只需在代码库中全局搜索 @[MODEL LAUNCH]，就能找到所有需要更新的位置。这种设计将发布流程的知识嵌入到代码本身中，而非依赖外部文档。

在 prompts.ts 中，@[MODEL LAUNCH] 标注了以下关键更新点：

在 antModels.ts 中：

这种模式的妙处在于自文档化：注解的文本本身就是操作说明。例如第 204 行的注解明确说明了解除条件：“remove or soften once the model stops over-commenting by default”。工程师不需要查阅外部运维手册 – 条件和动作都写在代码旁边。

7.2 Capybara v8 行为缓解

每个模型世代都有其独特的“个性缺陷“。Claude Code 的源码记录了 Capybara v8（Claude 4.5/4.6 系列的内部代号之一）的四个已知问题，以及针对每个问题的提示词级缓解措施。

7.2.1 过度注释（Over-commenting）

问题： Capybara v8 倾向于在代码中添加大量不必要的注释。

缓解（第 204-209 行）：

// @[MODEL LAUNCH]: Update comment writing for Capybara —
// remove or soften once the model stops over-commenting by default
...(process.env.USER_TYPE === 'ant'
  ? [
      `Default to writing no comments. Only add one when the WHY is
       non-obvious...`,
      `Don't explain WHAT the code does, since well-named identifiers
       already do that...`,
      `Don't remove existing comments unless you're removing the code
       they describe...`,
    ]
  : []),

源码参考： constants/prompts.ts:204-209

这组指令构成了一个精细的评论哲学：默认不写注释，只在“为什么“不明显时添加；不解释代码做什么（标识符已经做了）；不删除你不理解的已有注释。注意第三条指令的微妙之处 – 它既防止模型过度注释，又防止矫枉过正地删除有价值的已有注释。

7.2.2 虚假声明（False Claims）

问题： Capybara v8 的虚假声明率（False Claims rate）为 29-30%，显著高于 v4 的 16.7%。

缓解（第 237-241 行）：

// @[MODEL LAUNCH]: False-claims mitigation for Capybara v8
// (29-30% FC rate vs v4's 16.7%)
...(process.env.USER_TYPE === 'ant'
  ? [
      `Report outcomes faithfully: if tests fail, say so with the
       relevant output; if you did not run a verification step, say
       that rather than implying it succeeded. Never claim "all tests
       pass" when output shows failures...`,
    ]
  : []),

源码参考： constants/prompts.ts:237-241

这条缓解指令的设计体现了一种对称性思维：它不仅要求模型不要虚报成功，还明确要求不要过度自我怀疑 – “when a check did pass or a task is complete, state it plainly – do not hedge confirmed results with unnecessary disclaimers”。工程师们发现，简单地告诉模型“不要撒谎“会导致模型走向另一个极端，对所有结果都加上不必要的免责声明。缓解措施的目标是准确报告（accurate report），而非防御性报告（defensive report）。

7.2.3 主动性过强（Over-assertiveness）

问题： Capybara v8 倾向于单纯执行用户指令，不提出自己的判断。

缓解（第 224-228 行）：

// @[MODEL LAUNCH]: capy v8 assertiveness counterweight (PR #24302)
// — un-gate once validated on external via A/B
...(process.env.USER_TYPE === 'ant'
  ? [
      `If you notice the user's request is based on a misconception,
       or spot a bug adjacent to what they asked about, say so.
       You're a collaborator, not just an executor...`,
    ]
  : []),

源码参考： constants/prompts.ts:224-228

注解中的 “PR #24302” 表明这个缓解措施是经过代码审查流程引入的，而 “un-gate once validated on external via A/B” 则揭示了完整的发布策略：先在内部用户（ant）上验证，收集数据后再通过 A/B 测试推广到外部用户。

7.2.4 彻底性不足（Lack of Thoroughness）

问题： Capybara v8 倾向于在未验证结果的情况下声称任务完成。

缓解（第 210-211 行）：

// @[MODEL LAUNCH]: capy v8 thoroughness counterweight (PR #24302)
// — un-gate once validated on external via A/B
`Before reporting a task complete, verify it actually works: run the
 test, execute the script, check the output. Minimum complexity means
 no gold-plating, not skipping the finish line.`,

源码参考： constants/prompts.ts:210-211

这条指令的最后一句尤为精妙：“If you can’t verify (no test exists, can’t run the code), say so explicitly rather than claiming success.” 它承认了现实中存在无法验证的情况，但要求模型明确承认这一点，而非默默假装一切正常。

7.2.5 缓解措施的生命周期

四个缓解措施共享一个统一的生命周期模式：

flowchart LR
    A["发现行为问题\n(FC rate 等)"] --> B["PR 引入缓解\n(PR #24302)"]
    B --> C["ant-only 门控\n内部验证"]
    C --> D["A/B 测试验证\n外部推广"]
    D --> E{"新模型发布时\n@[MODEL LAUNCH]\n重新评估"}
    E -->|"问题已修复"| F["移除缓解"]
    E -->|"问题仍在"| G["保留/调整"]
    E -->|"解除 ant-only"| H["全量推广"]

    style A fill:#f9d,stroke:#333
    style D fill:#9df,stroke:#333
    style F fill:#dfd,stroke:#333
    style H fill:#dfd,stroke:#333

图 7-1：模型缓解措施的完整生命周期。 从发现问题到引入缓解，经过内部验证和 A/B 测试，最终在下一个 @[MODEL LAUNCH] 时重新评估。

7.3 USER_TYPE === 'ant' 门控：内部 A/B 测试暂存区

前面四个缓解措施都被包裹在同一个条件中：

process.env.USER_TYPE === 'ant'

这个环境变量不是运行时读取的 – 它是一个构建时常量。源码中的注释解释了这个关键的编译器契约：

DCE: `process.env.USER_TYPE === 'ant'` is build-time --define.
It MUST be inlined at each callsite (not hoisted to a const) so the
bundler can constant-fold it to `false` in external builds and
eliminate the branch.

源码参考： constants/prompts.ts:617-619

这段注释揭示了一个精巧的死代码消除（DCE）机制：

1. 构建时替换：打包工具（bundler）的 --define 选项在编译时将 process.env.USER_TYPE 替换为字符串字面量。
2. 常量折叠：对于外部构建，'external' === 'ant' 被折叠为 false。
3. 分支消除：条件为 false 的分支被整个移除，包括其中的所有字符串内容。
4. 内联要求：每个调用点必须直接写 process.env.USER_TYPE === 'ant'，不能提取为变量，否则打包工具无法进行常量折叠。

这意味着外部用户的构建产物中物理上不存在任何 ant-only 代码。这不是运行时的权限检查，而是编译时的代码消除。即使反编译外部构建，也找不到 Capybara 这样的内部代号或缓解措施的具体措辞。

7.3.1 ant-only 门控完整清单

下表列出了 prompts.ts 中所有受 USER_TYPE === 'ant' 门控的内容：

表 7-1：prompts.ts 中的 ant-only 门控完整清单。 每个门控都有明确的解除条件，构成了从内部验证到外部推广的渐进式发布管道。

getAntModelOverrideSection（第 136-139 行）值得特别注意：

      // function getAntModelOverrideSection(): string | null {
  if (process.env.USER_TYPE !== 'ant') return null
  if (isUndercover()) return null
  return getAntModelOverrideConfig()?.defaultSystemPromptSuffix || null
}

它有双重门控 – 不仅要求是内部用户，还要求不在 Undercover 模式下。这种设计确保即使是内部用户，在向公开仓库贡献代码时也不会泄露内部模型配置。

7.4 Undercover 模式：公开仓库中的隐身术

Undercover 模式是 Claude Code 最独特的功能之一。它解决的问题很具体：Anthropic 内部工程师使用 Claude Code 向公开/开源仓库贡献代码时，不应泄露任何内部信息。

7.4.1 激活逻辑

      // export function isUndercover(): boolean {
  if (process.env.USER_TYPE === 'ant') {
    if (isEnvTruthy(process.env.CLAUDE_CODE_UNDERCOVER)) return true
    return getRepoClassCached() !== 'internal'
  }
  return false
}

源码参考： utils/undercover.ts:28-37

激活规则有三个层级：

1. 强制开启：设置 CLAUDE_CODE_UNDERCOVER=1 环境变量，即使在内部仓库中也强制激活。
2. 自动检测：如果当前仓库的远程地址不在内部白名单中，自动激活。'external'、'none' 和 null（检查尚未运行）都解析为“开启“。
3. 无法强制关闭：设计上不提供强制关闭选项。源码注释解释了原因：“This guards against model codename leaks – if we’re not confident we’re in an internal repo, we stay undercover.”

这种“安全默认为开启“的设计哲学值得深思 – 宁可在内部仓库中多余地隐藏信息，也不冒在公开仓库中泄露的风险。

7.4.2 压制范围

Undercover 模式激活时，执行以下压制操作：

┌─────────────────────────────────────────────────────────────────────┐
│                     Undercover 模式工作流程                          │
│                                                                     │
│  ┌─────────────────┐                                                │
│  │  isUndercover()  │──── false ────▶ 正常模式（显示模型信息）        │
│  │    returns true  │                                                │
│  └────────┬────────┘                                                │
│           │ true                                                     │
│           ▼                                                          │
│  ┌─────────────────────────────────────────────────────────────────┐ │
│  │                    压制层 1：系统提示词                           │ │
│  │                                                                 │ │
│  │  computeEnvInfo (L621):                                         │ │
│  │    modelDescription = ''  ← 模型名称/ID 完全清空                 │ │
│  │                                                                 │ │
│  │  computeSimpleEnvInfo (L660):                                   │ │
│  │    modelDescription = null  ← 从环境信息中移除                   │ │
│  │                                                                 │ │
│  │  模型家族列表 (L694-696):                                       │ │
│  │    null  ← Opus/Sonnet/Haiku ID 列表不出现                      │ │
│  │                                                                 │ │
│  │  Claude Code 平台信息 (L697-699):                               │ │
│  │    null  ← CLI/桌面/Web/IDE 信息不出现                           │ │
│  │                                                                 │ │
│  │  Fast 模式说明 (L700-702):                                      │ │
│  │    null  ← 使用相同模型的说明不出现                               │ │
│  │                                                                 │ │
│  │  getAntModelOverrideSection (L138):                             │ │
│  │    return null  ← ant 模型覆盖后缀不注入                         │ │
│  └─────────────────────────────────────────────────────────────────┘ │
│           │                                                          │
│           ▼                                                          │
│  ┌─────────────────────────────────────────────────────────────────┐ │
│  │                    压制层 2：归因信息                             │ │
│  │                                                                 │ │
│  │  getAttributionTexts():                                         │ │
│  │    return { commit: '', pr: '' }                                │ │
│  │    ← 不生成 Co-Authored-By 行                                   │ │
│  │    ← PR 描述中无 AI 工具归因                                     │ │
│  └─────────────────────────────────────────────────────────────────┘ │
│           │                                                          │
│           ▼                                                          │
│  ┌─────────────────────────────────────────────────────────────────┐ │
│  │                    压制层 3：行为指令                             │ │
│  │                                                                 │ │
│  │  getUndercoverInstructions():                                   │ │
│  │    注入详细的反泄露指令：                                         │ │
│  │    - 禁止内部模型代号（Capybara, Tengu 等）                      │ │
│  │    - 禁止未发布模型版本号                                        │ │
│  │    - 禁止内部仓库/项目名                                         │ │
│  │    - 禁止内部工具、Slack 频道、短链接                             │ │
│  │    - 禁止 "Claude Code" 字样或 AI 身份暗示                       │ │
│  │    - 禁止 Co-Authored-By 归因                                    │ │
│  │    - 要求像人类开发者一样撰写 commit message                      │ │
│  └─────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘

图 7-2：Undercover 模式的三层压制工作流程。 从系统提示词到归因信息再到行为指令，形成完整的信息泄露防线。

源码中的注释（第 612-615 行）解释了为什么压制范围如此之广：

Undercover: keep ALL model names/IDs out of the system prompt so
nothing internal can leak into public commits/PRs. This includes the
public FRONTIER_MODEL_* constants — if those ever point at an
unannounced model, we don't want them in context. Go fully dark.

“Go fully dark” – 即使是公开的常量（如 FRONTIER_MODEL_NAME）也被压制，因为如果这些常量指向了一个尚未公布的模型，它们本身就成了泄露源。

7.4.3 Undercover 指令的示例

getUndercoverInstructions() 函数（utils/undercover.ts:39-69）注入了一段详细的反泄露指令。它用正面和反面示例教导模型：

好的 commit message：

• “Fix race condition in file watcher initialization”
• “Add support for custom key bindings”

绝不能写的 commit message：

• “Fix bug found while testing with Claude Capybara”
• “1-shotted by claude-opus-4-6”
• “Generated with Claude Code”

这种正反示例并列的教学方式比单纯的禁止清单更有效 – 它不仅告诉模型“不要做什么“，还示范了“应该做什么“。

7.4.4 自动通知机制

首次自动激活 Undercover 模式时，Claude Code 会显示一个一次性解释对话框（shouldShowUndercoverAutoNotice，第 80-88 行）。检查逻辑确保不会反复打扰用户：强制开启（通过环境变量）的用户不会看到通知（他们已经知道），已经看过通知的用户不会再看到。这个标志存储在全局配置的 hasSeenUndercoverAutoNotice 字段中。

7.5 GrowthBook 集成：tengu_* Feature Flag 体系

7.5.1 架构概述

Claude Code 使用 GrowthBook 作为其 Feature Flag 和实验平台。所有的 Feature Flag 遵循 tengu_* 命名约定 – “tengu” 是 Claude Code 的内部代号。

GrowthBook 客户端的初始化和特性值获取遵循一个精心设计的多层回退机制：

优先级（高到低）：
  1. 环境变量覆盖 (CLAUDE_INTERNAL_FC_OVERRIDES) — ant-only
  2. 本地配置覆盖 (/config Gates 面板)        — ant-only
  3. 内存中的远程评估值 (remoteEvalFeatureValues)
  4. 磁盘缓存 (cachedGrowthBookFeatures)
  5. 默认值 (defaultValue 参数)

核心的值读取函数是 getFeatureValue_CACHED_MAY_BE_STALE（growthbook.ts:734-775）。如其名称所述，这个函数返回的值可能是过期的 – 它优先从内存或磁盘缓存读取，不会阻塞等待网络请求。这是一个有意的设计决策：在启动关键路径上，陈旧但可用的值好过等待网络而卡住的 UI。

      // export function getFeatureValue_CACHED_MAY_BE_STALE<T>(
  feature: string,
  defaultValue: T,
): T {
  // 1. 环境变量覆盖
  const overrides = getEnvOverrides()
  if (overrides && feature in overrides) return overrides[feature] as T
  // 2. 本地配置覆盖
  const configOverrides = getConfigOverrides()
  if (configOverrides && feature in configOverrides)
    return configOverrides[feature] as T
  // 3. 内存远程评估值
  if (remoteEvalFeatureValues.has(feature))
    return remoteEvalFeatureValues.get(feature) as T
  // 4. 磁盘缓存
  const cached = getGlobalConfig().cachedGrowthBookFeatures?.[feature]
  return cached !== undefined ? (cached as T) : defaultValue
}

源码参考： services/analytics/growthbook.ts:734-775

7.5.2 远程评估与本地缓存同步

GrowthBook 使用 remoteEval: true 模式 – 特性值在服务器端预评估，客户端只需缓存结果。processRemoteEvalPayload 函数（growthbook.ts:327-394）在每次初始化和定期刷新时运行，将服务器返回的预评估值写入两个存储：

1. 内存 Map（remoteEvalFeatureValues）：用于进程生命周期内的快速读取。
2. 磁盘缓存（syncRemoteEvalToDisk，第 407-417 行）：用于跨进程持久化。

磁盘缓存采用整体替换而非合并策略 – 服务器端删除的特性会从磁盘中清除。这保证了磁盘缓存始终是服务器状态的完整快照，而非不断累积的历史沿积。

源码注释（第 322-325 行）记录了一个曾经的故障：

Without this running on refresh, remoteEvalFeatureValues freezes at
its init-time snapshot and getDynamicConfig_BLOCKS_ON_INIT returns
stale values for the entire process lifetime — which broke the
tengu_max_version_config kill switch for long-running sessions.

这个 kill switch 故障说明了为什么定期刷新至关重要 – 如果只在初始化时读取一次，长时间运行的会话将无法响应紧急的远程配置变更。

7.5.3 实验曝光追踪

GrowthBook 的 A/B 测试功能依赖于实验曝光（exposure）追踪。logExposureForFeature 函数（第 296-314 行）在特性值被访问时记录曝光事件，用于后续的实验分析。关键设计：

• 会话级去重：loggedExposures Set 确保每个特性每次会话最多记录一次曝光，防止在热路径（如渲染循环）中频繁调用导致的重复事件。
• 延迟曝光：如果特性在 GrowthBook 初始化完成前被访问，pendingExposures Set 暂存这些访问，待初始化完成后补录。

7.5.4 已知的 tengu_* Feature Flag

从代码库中可以识别出以下 tengu_* Feature Flag：

注意某些 Flag 使用了混淆命名（如 tengu_frond_boric），这是安全考量 – 即使 Flag 名称被外部观察到，也无法推断其用途。

7.5.5 环境变量覆盖：评估线束的后门

CLAUDE_INTERNAL_FC_OVERRIDES 环境变量（growthbook.ts:161-192）允许在不连接 GrowthBook 服务器的情况下覆盖任意 Feature Flag 值。这个机制专为评估线束（eval harness）设计 – 自动化测试需要在确定性条件下运行，不能依赖远程服务的状态。

// Example: CLAUDE_INTERNAL_FC_OVERRIDES='{"my_feature": true}'

覆盖优先级最高（高于磁盘缓存和远程评估值），且仅在 ant 构建中可用。这确保了评估线束的确定性，同时不会影响外部用户。

7.6 tengu_ant_model_override：模型热切换

tengu_ant_model_override 是所有 tengu_* Flag 中最复杂的一个。它通过 GrowthBook 远程配置 ant-only 模型的完整列表，支持运行时热切换，无需发布新版本。

7.6.1 配置结构

export type AntModelOverrideConfig = {
  defaultModel?: string               // 默认模型 ID
  defaultModelEffortLevel?: EffortLevel // 默认 effort 级别
  defaultSystemPromptSuffix?: string   // 追加到系统提示词的后缀
  antModels?: AntModel[]              // 可用模型列表
  switchCallout?: AntModelSwitchCalloutConfig // 切换提示配置
}

源码参考： utils/model/antModels.ts:24-30

每个 AntModel 包含别名（用于命令行选择）、模型 ID、显示标签、默认 effort 级别、上下文窗口大小等参数。switchCallout 允许在 UI 中向用户展示模型切换建议。

7.6.2 解析流程

resolveAntModel（antModels.ts:51-64）将用户输入的模型名称解析为具体的 AntModel 配置：

      // export function resolveAntModel(
  model: string | undefined,
): AntModel | undefined {
  if (process.env.USER_TYPE !== 'ant') return undefined
  if (model === undefined) return undefined
  const lower = model.toLowerCase()
  return getAntModels().find(
    m => m.alias === model || lower.includes(m.model.toLowerCase()),
  )
}

匹配逻辑同时支持精确的别名匹配和模糊的模型 ID 包含匹配。例如，如果用户指定 --model capybara-fast，别名匹配会找到对应的 AntModel；如果指定 --model claude-opus-4-6-capybara，模型 ID 包含匹配也能正确解析。

7.6.3 冷缓存启动问题

main.tsx 中的注释（第 2001-2014 行）记录了一个棘手的启动顺序问题：ant 模型别名通过 tengu_ant_model_override Feature Flag 解析，而 _CACHED_MAY_BE_STALE 在 GrowthBook 初始化完成前只能读取磁盘缓存。如果磁盘缓存为空（冷缓存），resolveAntModel 会返回 undefined，导致模型别名无法解析。

解决方案是在检测到 ant 用户指定了显式模型且磁盘缓存为空时，同步等待 GrowthBook 初始化完成：

if ('external' === 'ant' && explicitModel && ...) {
  await initializeGrowthBook()
}

这是整个代码库中极少数 GrowthBook 调用需要阻塞等待的场景之一。

7.7 知识截止日期映射

getKnowledgeCutoff 函数（prompts.ts:712-730）维护了一个从模型 ID 到知识截止日期的映射表：

      // function getKnowledgeCutoff(modelId: string): string | null {
  const canonical = getCanonicalName(modelId)
  if (canonical.includes('claude-sonnet-4-6'))      return 'August 2025'
  else if (canonical.includes('claude-opus-4-6'))    return 'May 2025'
  else if (canonical.includes('claude-opus-4-5'))    return 'May 2025'
  else if (canonical.includes('claude-haiku-4'))     return 'February 2025'
  else if (canonical.includes('claude-opus-4') ||
           canonical.includes('claude-sonnet-4'))    return 'January 2025'
  return null
}

源码参考： constants/prompts.ts:712-730

这个函数使用 includes 而非精确匹配，使其对模型 ID 后缀（如日期标签 -20251001）具有鲁棒性。截止日期被注入系统提示词的环境信息段落中（第 635-638 行），让模型知道自己的知识边界：

const knowledgeCutoffMessage = cutoff
  ? `\n\nAssistant knowledge cutoff is ${cutoff}.`
  : ''

当 Undercover 模式激活时，整个环境信息段落（包括知识截止日期）中的模型特定部分都被压制 – 但知识截止日期本身仍然保留，因为它不会泄露内部信息。

7.8 工程启示

渐进式发布的三段管道

Claude Code 的模型调优揭示了一个清晰的三段发布管道：

1. 发现与引入：通过模型评估发现行为问题（如 29-30% FC rate），通过 PR 引入缓解措施。
2. 内部验证：通过 USER_TYPE === 'ant' 门控限制在内部用户中，收集真实使用数据。
3. 渐进推广：通过 GrowthBook A/B 测试验证效果后，解除 ant-only 门控推广到所有用户。

编译时安全优于运行时检查

USER_TYPE 的构建时替换 + 死代码消除机制，确保了内部代码在外部构建中物理不存在，而非仅仅“不可访问“。这种编译时安全比运行时权限检查更强 – 没有代码意味着没有攻击面。

安全默认值的哲学

Undercover 模式的“无法强制关闭“设计、DANGEROUS_ 前缀的 API 摩擦、以及“冷缓存时阻塞等待“的启动逻辑，都体现了同一种哲学：当安全和便利冲突时，选择安全。这不是偏执 – 而是在“泄露内部模型信息“与“多等几百毫秒“之间做出的合理权衡。

Feature Flag 作为控制平面

tengu_* Feature Flag 体系将 Claude Code 从一个单一的软件产品转变为一个可远程控制的平台。通过 GrowthBook，工程师可以在不发布新版本的情况下：切换默认模型、调整事件采样率、启用/禁用实验功能、甚至通过 kill switch 紧急关闭有问题的功能。这种“控制平面与数据平面分离“的架构，是 SaaS 产品成熟度的标志。

7.9 用户能做什么

基于本章对模型特定调优和 A/B 测试体系的分析，以下是读者可以在自己的 AI Agent 项目中应用的建议：

1. 在代码中嵌入分布式检查清单。 如果你的系统需要在模型升级时更新多个位置（模型名称、知识截止日期、行为缓解等），采用 @[MODEL LAUNCH] 式的注解标记。在注解文本中直接写明更新动作和解除条件，让检查清单与代码共存，而非依赖外部文档。

2. 为每个模型世代维护行为缓解档案。 当你发现新模型的某个行为倾向（如过度注释、虚假声明），通过提示词级缓解而非代码逻辑来修正。记录每个缓解措施的引入原因、FC rate 等量化指标、以及解除条件。这份档案在下一次模型升级时是无价的参考。

3. 用构建时常量替代运行时检查来保护内部代码。 如果你的产品有内部版本和外部版本的区分，不要依赖运行时 if 判断来隐藏内部功能。参考 Claude Code 的 USER_TYPE + 打包工具 --define + 死代码消除（DCE）机制，确保内部代码在外部构建中物理不存在。

4. 建立 Feature Flag 体系实现提示词的远程控制。 将提示词中的实验性内容（新的行为指令、数值锚定等）通过 Feature Flag 门控，而非硬编码。这让你可以在不发布新版本的情况下调整模型行为、进行 A/B 测试、以及在紧急情况下通过 kill switch 回滚变更。

5. 默认安全，而非默认便利。 当需要在安全和便利之间做选择时，参考 Undercover 模式的设计：安全模式默认开启、无法强制关闭、宁可误报也不漏报。对于 AI Agent 来说，信息泄露的代价远高于偶尔的多余限制。

第8章：工具提示词作为微型驾驭器

第5章解剖了系统提示词的宏观架构 – 段落注册、缓存分层、动态拼装。但系统提示词只是“顶层战略“。在每次工具调用的微观层面，还有一套平行的驾驭体系在运作：工具提示词（tool description / tool prompt）。它们作为 description 字段注入 API 请求的 tools 数组，直接塑造模型对每个工具的使用方式。本章将逐一拆解 Claude Code 六大核心工具的提示词设计，揭示其中的引导策略与可复用模式。

8.1 工具提示词的驾驭本质

工具的 description 字段在 Anthropic API 中的定位是“告诉模型这个工具做什么“。但 Claude Code 将这个字段从简单的功能描述，扩展为一套完整的行为约束协议。每个工具的提示词实际上是一个微型驾驭器（micro-harness），包含：

• 功能描述：工具做什么
• 正面引导：应该怎么用
• 负面禁令：不能怎么用
• 条件分支：在特定场景下该怎么做
• 格式模板：输出应该长什么样

这种设计的核心洞察是：模型对每个工具的行为质量，直接受该工具提示词质量制约。系统提示词设定全局人格，工具提示词塑造局部行为。二者共同构成 Claude Code 的“双层驾驭架构“。

接下来我们按功能复杂度由高到低，逐一分析六个工具。

8.2 BashTool：最复杂的微型驾驭器

BashTool 是 Claude Code 中提示词最长、约束最密集的工具。它的提示词由 getSimplePrompt() 函数动态生成，最终可达数千字。

源码位置： tools/BashTool/prompt.ts:275-369

8.2.1 工具偏好矩阵：把流量导向专用工具

提示词的第一部分就建立了一个明确的工具偏好矩阵：

IMPORTANT: Avoid using this tool to run find, grep, cat, head, tail,
sed, awk, or echo commands, unless explicitly instructed or after you
have verified that a dedicated tool cannot accomplish your task.

紧接着是一张映射表（第281-291行）：

const toolPreferenceItems = [
  `File search: Use ${GLOB_TOOL_NAME} (NOT find or ls)`,
  `Content search: Use ${GREP_TOOL_NAME} (NOT grep or rg)`,
  `Read files: Use ${FILE_READ_TOOL_NAME} (NOT cat/head/tail)`,
  `Edit files: Use ${FILE_EDIT_TOOL_NAME} (NOT sed/awk)`,
  `Write files: Use ${FILE_WRITE_TOOL_NAME} (NOT echo >/cat <<EOF)`,
  'Communication: Output text directly (NOT echo/printf)',
]

这个设计体现了一个重要的驾驭模式：流量导向（traffic steering）。Bash 是一个“万能工具“ – 理论上可以完成文件读写、搜索、编辑等所有操作。但让模型通过 Bash 完成这些操作会带来两个问题：

1. 用户体验差：专用工具（如 FileEditTool）有结构化输入、可视化 diff、权限检查等能力，Bash 命令则是不透明的字符串。
2. 权限控制失效：专用工具有细粒度权限校验，Bash 命令绕过了这些检查。

注意第276-278行的条件分支：当系统检测到嵌入式搜索工具（hasEmbeddedSearchTools()）时，find 和 grep 从禁用列表中移除。这是为 Anthropic 内部构建版本（ant-native builds）做的适配 – 这些构建将 find/grep 别名为嵌入式 bfs/ugrep，同时移除了独立的 Glob/Grep 工具。

可复用模式 – “万能工具降级”： 当你的工具集中存在一个功能覆盖面极广的工具时，在其提示词中显式列出“什么场景应该用什么替代工具“，避免模型过度依赖单一工具。

8.2.2 命令执行指南：从超时到并发

提示词的第二部分是一套详细的命令执行规范（第331-352行），涵盖：

• 目录验证：“If your command will create new directories or files, first use this tool to run ls to verify the parent directory exists”
• 路径引用：“Always quote file paths that contain spaces with double quotes”
• 工作目录保持：“Try to maintain your current working directory throughout the session by using absolute paths”
• 超时控制：默认 120,000ms（2分钟），最大 600,000ms（10分钟）
• 后台执行：run_in_background 参数，带明确的使用条件

其中最精巧的是多命令并发指南（第297-303行）：

const multipleCommandsSubitems = [
  `If the commands are independent and can run in parallel, make multiple
   ${BASH_TOOL_NAME} tool calls in a single message.`,
  `If the commands depend on each other and must run sequentially, use
   a single ${BASH_TOOL_NAME} call with '&&' to chain them together.`,
  "Use ';' only when you need to run commands sequentially but don't
   care if earlier commands fail.",
  'DO NOT use newlines to separate commands.',
]

这不是简单的“最佳实践建议“，而是一套并发决策树：独立任务用并行工具调用 -> 有依赖用 && -> 允许失败用 ; -> 禁止用换行符。每条规则都对应一个具体的故障模式。

8.2.3 Git 安全协议：深度防御

Git 操作是 BashTool 提示词中最重要的安全领域。完整的 Git 安全协议定义在 getCommitAndPRInstructions() 函数中（第42-161行），其核心禁令列表（第88-95行）构成了一道六层防线：

Git Safety Protocol:
- NEVER update the git config
- NEVER run destructive git commands (push --force, reset --hard,
  checkout ., restore ., clean -f, branch -D) unless the user
  explicitly requests these actions
- NEVER skip hooks (--no-verify, --no-gpg-sign, etc) unless the
  user explicitly requests it
- NEVER run force push to main/master, warn the user if they request it
- CRITICAL: Always create NEW commits rather than amending
- When staging files, prefer adding specific files by name rather
  than using "git add -A" or "git add ."
- NEVER commit changes unless the user explicitly asks you to

每一条禁令都对应一个真实的数据丢失场景：

“CRITICAL” 标记被保留给最微妙的场景：pre-commit hook 失败后的 --amend 陷阱。这条规则需要理解 Git 的内部机制 – hook 失败意味着 commit 没有发生，此时 --amend 会修改的是上一个已存在的提交，而不是“重试当前提交“。

提示词还包含完整的 commit 工作流模板（第96-125行），用编号步骤明确指定哪些操作可以并行、哪些必须串行，甚至提供了 HEREDOC 格式的 commit message 模板。这是一种**工作流脚手架（workflow scaffolding）**模式 – 不是告诉模型“做什么“，而是告诉它“按什么顺序做“。

8.2.4 沙箱配置的 JSON 内联

当沙箱（sandbox）启用时，getSimpleSandboxSection() 函数（第172-273行）会将完整的沙箱配置以 JSON 格式内联到提示词中：

const filesystemConfig = {
  read: {
    denyOnly: dedup(fsReadConfig.denyOnly),
    allowWithinDeny: dedup(fsReadConfig.allowWithinDeny),
  },
  write: {
    allowOnly: normalizeAllowOnly(fsWriteConfig.allowOnly),
    denyWithinAllow: dedup(fsWriteConfig.denyWithinAllow),
  },
}

源码参考： tools/BashTool/prompt.ts:195-203

这是一个值得深思的设计决策：将机器可读的安全策略直接暴露给模型。模型需要“理解“自己可以访问哪些路径、可以连接哪些网络主机，才能在生成命令时主动避免违规。JSON 格式保证了信息的精确性和无歧义性。

注意第167-170行的 dedup 函数和第188-191行的 normalizeAllowOnly：前者去除重复路径（因为 SandboxManager 合并多层配置时不去重），后者将用户特定的临时目录路径替换为 $TMPDIR 占位符。这两个优化分别节省了 ~150-200 token 和保证了跨用户的 prompt 缓存一致性。

可复用模式 – “策略透明化”： 当安全策略需要模型配合执行时，将策略的完整规则集以结构化格式（JSON/YAML）内联到提示词中，让模型在生成阶段就能自检合规性。

8.2.5 sleep 反模式抑制

提示词专门用一个小节（第310-327行）来抑制 sleep 的滥用：

const sleepSubitems = [
  'Do not sleep between commands that can run immediately — just run them.',
  'If your command is long running... use `run_in_background`.',
  'Do not retry failing commands in a sleep loop — diagnose the root cause.',
  'If waiting for a background task... do not poll.',
  'If you must sleep, keep the duration short (1-5 seconds)...',
]

这是一个典型的**反模式抑制（anti-pattern suppression）**策略。LLM 在代码生成场景中倾向于使用 sleep + 轮询来处理异步等待，因为这是训练数据中最常见的模式。提示词通过逐一列举替代方案（后台执行、事件通知、诊断根因）来“覆写“这个默认行为。

8.3 FileEditTool：“编辑前必须先读取“的强制机制

FileEditTool 的提示词相比 BashTool 精简得多，但每一句都承载着关键的工程约束。

源码位置： tools/FileEditTool/prompt.ts:1-28

8.3.1 前置读取强制

提示词的第一条规则（第4-6行）：

      // function getPreReadInstruction(): string {
  return `You must use your \`${FILE_READ_TOOL_NAME}\` tool at least once
  in the conversation before editing. This tool will error if you
  attempt an edit without reading the file.`
}

这不是一个“建议“，而是一个硬性约束 – 工具的运行时实现会检查对话历史中是否存在对该文件的 Read 调用，没有则直接返回错误。提示词中的说明是为了让模型提前知道这个约束，避免浪费一次工具调用。

这个设计解决了一个核心问题：模型幻觉（hallucination）。如果模型不先读取文件就尝试编辑，它对文件内容的假设可能完全错误。强制先读取保证了编辑操作基于真实的文件状态，而不是模型对文件内容的“记忆“或“猜测“。

可复用模式 – “前置条件强制”： 当工具 B 的正确性依赖于工具 A 的先行调用时，在 B 的提示词中声明这个依赖关系，并在 B 的运行时中强制检查。双重保障 – 提示词层防止浪费调用，运行时层兜底防止错误操作。

8.3.2 最小唯一 old_string

提示词对 old_string 参数的要求（第20-27行）体现了精妙的平衡：

- The edit will FAIL if `old_string` is not unique in the file. Either
  provide a larger string with more surrounding context to make it unique
  or use `replace_all` to change every instance of `old_string`.

对于 Anthropic 内部用户（USER_TYPE === 'ant'），还有一条额外的优化指引（第17-19行）：

const minimalUniquenessHint =
  process.env.USER_TYPE === 'ant'
    ? `Use the smallest old_string that's clearly unique — usually 2-4
       adjacent lines is sufficient. Avoid including 10+ lines of context
       when less uniquely identifies the target.`
    : ''

这揭示了一个token 经济学问题：模型在使用 FileEditTool 时，需要在 old_string 参数中提供要替换的原文。如果模型习惯性地包含大段上下文来“确保唯一性“，每次编辑操作的 token 消耗就会急剧膨胀。“2-4 行“的指导让模型在唯一性和简洁性之间找到甜点。

8.3.3 缩进保持与行号前缀

提示词中最容易被忽视但最关键的技术细节（第13-16行，第23行）：

const prefixFormat = isCompactLinePrefixEnabled()
  ? 'line number + tab'
  : 'spaces + line number + arrow'

// 在描述中：
`When editing text from Read tool output, ensure you preserve the exact
indentation (tabs/spaces) as it appears AFTER the line number prefix.
The line number prefix format is: ${prefixFormat}. Everything after that
is the actual file content to match. Never include any part of the line
number prefix in the old_string or new_string.`

Read 工具返回的内容带有行号前缀（如 42 →），模型需要在编辑时剥离这个前缀，只提取实际的文件内容作为 old_string。这是 Read 工具与 Edit 工具之间的接口契约 – 提示词承担了“接口文档“的角色。

可复用模式 – “工具间接口声明”： 当两个工具的输出/输入存在格式转换关系时，在下游工具的提示词中显式描述上游工具的输出格式，避免模型在格式转换中出错。

8.4 FileReadTool：资源感知的读取策略

FileReadTool 的提示词看似简单，实则包含了精心设计的资源管理策略。

源码位置： tools/FileReadTool/prompt.ts:1-49

8.4.1 2000 行默认限制

export const MAX_LINES_TO_READ = 2000

// 在提示词模板中：
`By default, it reads up to ${MAX_LINES_TO_READ} lines starting from
the beginning of the file`

源码参考： tools/FileReadTool/prompt.ts:10,37

2000 行是一个经过权衡的数字。Anthropic 的模型有 200K token 的上下文窗口，但上下文越大，注意力分散越严重、推理成本越高。2000 行大约对应 8000-16000 个 token（取决于代码密度），占上下文窗口的 4-8%。这个预算足够覆盖绝大多数单文件场景，同时为多文件操作留出空间。

8.4.2 offset/limit 的渐进式引导

提示词对 offset/limit 参数提供了两种措辞模式（第17-21行）：

export const OFFSET_INSTRUCTION_DEFAULT =
  "You can optionally specify a line offset and limit (especially handy
   for long files), but it's recommended to read the whole file by not
   providing these parameters"

export const OFFSET_INSTRUCTION_TARGETED =
  'When you already know which part of the file you need, only read
   that part. This can be important for larger files.'

两种模式服务于不同的使用阶段：

• DEFAULT 模式鼓励完整读取 – 适用于模型首次接触文件时，需要全局理解。
• TARGETED 模式鼓励精准读取 – 适用于模型已经知道目标位置时，节省 token 预算。

哪种模式被使用取决于运行时上下文（由 FileReadTool 调用方决定），但提示词预先定义了两种“引导语气“，让模型在不同场景下展现不同的读取行为。

8.4.3 多媒体能力声明

提示词用一系列声明式语句扩展了 Read 工具的能力边界（第40-48行）：

- This tool allows Claude Code to read images (eg PNG, JPG, etc).
  When reading an image file the contents are presented visually
  as Claude Code is a multimodal LLM.
- This tool can read PDF files (.pdf). For large PDFs (more than 10
  pages), you MUST provide the pages parameter to read specific page
  ranges. Maximum 20 pages per request.
- This tool can read Jupyter notebooks (.ipynb files) and returns all
  cells with their outputs.

PDF 的分页限制（“more than 10 pages…MUST provide the pages parameter”）是一个渐进式资源限制：小文件直接读取，大文件强制分页。这比“所有文件都必须分页“或“不限制分页“都更合理 – 前者增加不必要的工具调用轮次，后者可能一次性注入过多内容。

注意 PDF 支持是条件性的（第41行）：isPDFSupported() 检查运行时环境是否支持 PDF 解析。不支持时，整个 PDF 说明段落从提示词中消失。这避免了“提示词承诺了运行时无法兑现的能力“这一常见陷阱。

可复用模式 – “能力声明与运行时对齐”： 工具提示词中的能力描述应该由运行时能力动态决定。如果某个功能在特定环境下不可用，不要在提示词中提及它 – 这会导致模型尝试使用不存在的功能，产生困惑和浪费。

8.5 GrepTool：“始终用 Grep 不用 bash grep”

GrepTool 的提示词精简到极致，但每一行都是硬约束。

源码位置： tools/GrepTool/prompt.ts:1-18

8.5.1 排他性声明

提示词的第一条使用规则（第10行）：

ALWAYS use Grep for search tasks. NEVER invoke `grep` or `rg` as a
Bash command. The Grep tool has been optimized for correct permissions
and access.

这是与 BashTool 的工具偏好矩阵双向配合的设计：BashTool 说“不要用 bash 做搜索“，GrepTool 说“搜索必须用我“。两个方向的约束形成闭环，最大程度降低模型“走错路“的概率。

“has been optimized for correct permissions and access” 给出了理由，而非仅仅发出禁令。理由很重要 – GrepTool 底层调用的是相同的 ripgrep，但包裹了权限检查（checkReadPermissionForTool，GrepTool.ts:233-239）、忽略模式应用（getFileReadIgnorePatterns，GrepTool.ts:413-427）和版本控制目录排除（VCS_DIRECTORIES_TO_EXCLUDE，GrepTool.ts:95-102）。通过 Bash 直接调用 rg 会绕过这些安全层。

8.5.2 ripgrep 语法提示

提示词提供了三条关键的语法差异说明（第11-16行）：

- Supports full regex syntax (e.g., "log.*Error", "function\s+\w+")
- Pattern syntax: Uses ripgrep (not grep) - literal braces need
  escaping (use `interface\{\}` to find `interface{}` in Go code)
- Multiline matching: By default patterns match within single lines only.
  For cross-line patterns like `struct \{[\s\S]*?field`, use
  `multiline: true`

第一条明确了语法家族（ripgrep 的 Rust regex），第二条给出了最常见的陷阱（大括号需要转义 – 这与 GNU grep 不同），第三条解释了 multiline 参数的使用场景。

从代码实现看，multiline: true 对应的 ripgrep 参数是 -U --multiline-dotall（GrepTool.ts:341-343）。提示词选择用“使用场景 + 示例“来解释这个功能，而不是暴露底层参数细节 – 模型不需要知道 -U 是什么，只需要知道什么时候设置 multiline: true。

8.5.3 输出模式与 head_limit

GrepTool 的输入 schema（GrepTool.ts:33-89）定义了丰富的参数，但提示词中只简要提及三种输出模式：

Output modes: "content" shows matching lines, "files_with_matches"
shows only file paths (default), "count" shows match counts

而 head_limit 参数的设计（GrepTool.ts:81,107）尤其值得关注：

const DEFAULT_HEAD_LIMIT = 250

// 在 schema 描述中：
'Defaults to 250 when unspecified. Pass 0 for unlimited
(use sparingly — large result sets waste context).'

默认 250 条结果上限是一个上下文保护机制 – 注释中说明（第104-108行），不受限的 content 模式搜索可能填满 20KB 的工具结果持久化阈值。“use sparingly” 的措辞给模型一个温和的警告，而 0 作为“无限制“的逃生舱口保留了灵活性。

可复用模式 – “安全默认值 + 逃生舱口”： 为可能产生大量输出的工具设置保守的默认限制，同时提供一个显式的方式来解除限制。在提示词中说明两者的存在和适用场景。

8.6 AgentTool：动态 agent 列表与 fork 指引

AgentTool 是六个工具中提示词生成逻辑最复杂的，因为它需要根据运行时状态（可用的 agent 定义、是否启用 fork、是否为 coordinator 模式、订阅类型）动态组合内容。

源码位置： tools/AgentTool/prompt.ts:1-287

8.6.1 内联 vs 附件：agent 列表的两种注入方式

提示词中的 agent 列表可以通过两种方式注入（第58-64行，第196-199行）：

      // export function shouldInjectAgentListInMessages(): boolean {
  if (isEnvTruthy(process.env.CLAUDE_CODE_AGENT_LIST_IN_MESSAGES)) return true
  if (isEnvDefinedFalsy(process.env.CLAUDE_CODE_AGENT_LIST_IN_MESSAGES))
    return false
  return getFeatureValue_CACHED_MAY_BE_STALE('tengu_agent_list_attach', false)
}

方式一（内联）： agent 列表直接嵌入工具描述。

`Available agent types and the tools they have access to:
${effectiveAgents.map(agent => formatAgentLine(agent)).join('\n')}`

方式二（附件）： 工具描述只包含静态文本 “Available agent types are listed in <system-reminder> messages in the conversation”，实际列表通过 agent_listing_delta 附件消息单独注入。

源码注释（第50-57行）解释了动机：动态 agent 列表占了全局 cache_creation token 的约 10.2%。每当 MCP 服务器异步连接、插件重载、或权限模式变化时，agent 列表就会变化，导致包含列表的工具 schema 全部失效，触发昂贵的缓存重建。将列表移到附件消息中，工具描述变为静态文本，从而保护了工具 schema 层的 prompt 缓存。

每个 agent 的描述格式（第43-46行）：

      // export function formatAgentLine(agent: AgentDefinition): string {
  const toolsDescription = getToolsDescription(agent)
  return `- ${agent.agentType}: ${agent.whenToUse} (Tools: ${toolsDescription})`
}

getToolsDescription 函数（第15-37行）处理了工具白名单和黑名单的交叉过滤，最终生成如 “All tools except Bash, Agent” 或 “Read, Grep, Glob” 这样的描述。这让模型知道每个 agent 类型能用什么工具，从而做出合理的委派决策。

可复用模式 – “动态内容外移”： 当工具提示词中的某个部分频繁变化且对缓存影响大时，将其从工具 description 移到消息流中（如附件、system-reminder），保持工具描述的稳定性。

8.6.2 Fork 子代理：继承上下文的轻量委派

当 isForkSubagentEnabled() 为 true 时，提示词增加一个“When to fork“段落（第81-96行），引导模型在两种委派模式间选择：

1. Fork（省略 subagent_type）：继承父代理的完整对话上下文，适合研究型和实现型任务。
2. Fresh agent（指定 subagent_type）：从零开始，需要完整的上下文传递。

Fork 的使用指南包含三条核心纪律：

Don't peek. The tool result includes an output_file path — do not
Read or tail it unless the user explicitly asks for a progress check.

Don't race. After launching, you know nothing about what the fork found.
Never fabricate or predict fork results in any format.

Writing a fork prompt. Since the fork inherits your context, the prompt
is a directive — what to do, not what the situation is.

“Don’t peek” 防止父代理读取 fork 的中间输出，这会把 fork 的工具噪音拉入父代理的上下文，违背了 fork 的初衷。“Don’t race” 防止父代理在结果返回前“猜测“fork 的结论 – 这是 LLM 的一个已知倾向。

8.6.3 Prompt 写作指南：防止浅层委派

提示词中最独特的部分是一段“如何写好 agent prompt“的指南（第99-113行）：

Brief the agent like a smart colleague who just walked into the room —
it hasn't seen this conversation, doesn't know what you've tried,
doesn't understand why this task matters.

...

**Never delegate understanding.** Don't write "based on your findings,
fix the bug" or "based on the research, implement it." Those phrases
push synthesis onto the agent instead of doing it yourself.

“Never delegate understanding” 是一条深刻的元认知约束。它防止模型将需要综合判断的思考工作甩给子代理 – 子代理应该是执行者，不是决策者。这条规则将“理解“锚定在父代理身上，确保工作流中的知识不会丢失。

可复用模式 – “委派质量保障”： 当工具涉及向子系统传递任务时，在提示词中约束任务描述的质量标准，防止模型生成模糊、不完整的委派指令。

8.7 SkillTool：预算约束与三级截断

SkillTool 的独特之处在于它不仅驾驭模型的行为，还管理自身提示词的体积。

源码位置： tools/SkillTool/prompt.ts:1-242

8.7.1 1% 上下文窗口预算

export const SKILL_BUDGET_CONTEXT_PERCENT = 0.01
export const CHARS_PER_TOKEN = 4
export const DEFAULT_CHAR_BUDGET = 8_000 // Fallback: 1% of 200k * 4

源码参考： tools/SkillTool/prompt.ts:21-23

技能列表的总字符预算被硬性限制为上下文窗口的 1%。对于 200K token 的上下文窗口，这是 200K * 4 chars/token * 1% = 8000 字符。这个预算约束确保了技能发现功能不会侵蚀模型的工作上下文 – 技能列表是“目录“，不是“内容“，模型只需要看到足够的信息来决定是否调用某个技能，实际的技能内容在调用时才加载。

8.7.2 三级截断策略

formatCommandsWithinBudget 函数（第70-171行）实现了一套渐进式截断策略：

第一级：完整保留。 如果所有技能的完整描述加起来不超过预算，全部保留。

if (fullTotal <= budget) {
  return fullEntries.map(e => e.full).join('\n')
}

第二级：描述裁剪。 超预算时，将非内置技能（non-bundled）的描述裁剪到平均可用长度。内置技能（bundled）始终保留完整描述。

const maxDescLen = Math.floor(availableForDescs / restCommands.length)
// ...
return `- ${cmd.name}: ${truncate(description, maxDescLen)}`

第三级：仅保留名称。 如果裁剪后的平均描述长度小于 20 字符（MIN_DESC_LENGTH），非内置技能退化为仅显示名称。

if (maxDescLen < MIN_DESC_LENGTH) {
  return commands
    .map((cmd, i) =>
      bundledIndices.has(i) ? fullEntries[i]!.full : `- ${cmd.name}`,
    )
    .join('\n')
}

这套三级策略的优先级是：内置技能 > 非内置技能的描述 > 非内置技能的名称。内置技能作为 Claude Code 的核心功能，永远不会被截断。第三方插件技能则按需降级，确保在任何规模的技能生态中都能控制 token 成本。

8.7.3 单条目硬上限

除了总预算外，每个技能条目还有独立的硬上限（第29行）：

export const MAX_LISTING_DESC_CHARS = 250

getCommandDescription 函数（第43-49行）在总预算截断之前，先对每个条目进行 250 字符的预截断：

      // function getCommandDescription(cmd: Command): string {
  const desc = cmd.whenToUse
    ? `${cmd.description} - ${cmd.whenToUse}`
    : cmd.description
  return desc.length > MAX_LISTING_DESC_CHARS
    ? desc.slice(0, MAX_LISTING_DESC_CHARS - 1) + '\u2026'
    : desc
}

注释解释了原因：技能列表是发现（discovery） 用途，不是使用（usage） 用途。冗长的 whenToUse 字符串浪费的是 turn-1 的 cache_creation token，对技能匹配率没有提升。

8.7.4 调用协议

SkillTool 的核心提示词（第173-196行）相对简短，但包含一条关键的阻塞性要求：

When a skill matches the user's request, this is a BLOCKING REQUIREMENT:
invoke the relevant Skill tool BEFORE generating any other response
about the task

“BLOCKING REQUIREMENT” 是 Claude Code 提示词体系中最强的约束措辞之一。它要求模型在识别到匹配技能时，立即调用 Skill 工具，不得先生成文本回复。这防止了一个常见的反模式：模型先输出一段分析文字，然后才调用技能 – 这段文字往往与技能加载后的实际指令冲突。

另一条防御性规则（第194行）：

`If you see a <${COMMAND_NAME_TAG}> tag in the current conversation turn,
the skill has ALREADY been loaded - follow the instructions directly
instead of calling this tool again`

这防止了重复加载：如果技能已经通过 <command-name> 标签注入到当前轮次，模型不应该再次调用 SkillTool，而应该直接执行技能指令。

可复用模式 – “预算感知的目录生成”： 当工具需要向模型呈现一个动态增长的列表（插件、技能、API 端点等）时，为列表分配固定的 token 预算，并实现多级降级策略。优先保留高价值条目的完整性，低优先级条目渐进退化。

8.8 六工具对比总结

下表从五个维度对比六个工具的提示词设计：

block-beta
    columns 2
    block:behavior["行为约束型"]:1
        BT1["BashTool ← 安全协议"]
        ET1["EditTool ← 前置条件"]
        GT1["GrepTool ← 排他声明"]
    block:resource["资源管理型"]:1
        SK1["SkillTool ← 预算截断"]
        RT1["ReadTool ← 行数/页数限制"]
        GT2["GrepTool ← head_limit"]
    block:collab["协作编排型"]:1
        AT1["AgentTool ← 委派指南"]
        BT2["BashTool ← 并发决策树"]
        ET2["EditTool ← 接口契约"]
    block:cache["缓存优化型"]:1
        AT2["AgentTool ← 列表外移"]
        BT3["BashTool ← $TMPDIR 归一化"]
        SK2["SkillTool ← 描述裁剪"]

图 8-1：工具提示词驾驭模式的四象限分布。 每个工具通常横跨多个象限 – BashTool 同时具备行为约束、协作编排和缓存优化特征；GrepTool 兼具行为约束和资源管理。

8.9 设计工具提示词的七条原则

从六个工具的分析中，我们可以提炼出一套通用的工具提示词设计原则：

1. 双向闭环：当工具 A 不应处理某类任务时，同时在 A 中说“不要做 X，用 B“，在 B 中说“做 X 必须用我“。单向约束留有漏洞。

2. 理由先于禁令：每条 “NEVER” 后面跟一个 “because”。模型在理解原因后更不容易违反约束。GrepTool 的 “has been optimized for correct permissions” 比单纯的 “NEVER use bash grep” 更有效。

3. 能力与运行时对齐：提示词声明的能力必须由运行时保证。FileReadTool 的 PDF 支持根据 isPDFSupported() 条件注入，而不是无条件声明。

4. 安全默认值 + 逃生舱口：为所有可能产生大量输出或副作用的参数设置保守默认值，同时提供显式的解除方式。GrepTool 的 head_limit=250/0 是典型案例。

5. 预算意识：工具提示词本身消耗 token。SkillTool 的 1% 预算约束和三级截断是极端但正确的做法。BashTool 的 $TMPDIR 归一化和 dedup 则是更微妙的优化。

6. 前置条件声明：如果工具的正确使用依赖于特定前提（先读取文件、先检查目录），在提示词中声明，在运行时中强制。双重保障优于单层防御。

7. 委派质量标准：当工具涉及向子系统传递任务时，约束任务描述的完整性和具体性。AgentTool 的 “Never delegate understanding” 防止了知识在委派链中丢失。

8.10 用户能做什么

基于本章对六大工具提示词的分析，以下是读者在设计自己的工具提示词时可以直接应用的建议：

1. 为“万能工具“建立流量导向表。 如果你的工具集中有一个功能覆盖面极广的工具（如 Bash、通用 API 调用器），在其描述的最前面放置一张“场景 -> 专用工具“的映射表。同时在每个专用工具中声明排他性。这种双向闭环是防止模型过度依赖单一工具的最有效手段。

2. 强制工具间的前置条件。 当工具 B 的正确性依赖于工具 A 的先行调用时（如“编辑前必须先读取“），在 B 的提示词中声明这个依赖，并在 B 的运行时中用代码强制检查。提示词层防止浪费调用，运行时层兜底防止错误操作 – 双层防御优于单层。

3. 将安全策略以 JSON 内联到提示词。 如果模型需要“理解“自己的权限边界（可访问的路径、可连接的主机等），将完整的策略规则集以结构化格式注入提示词。这让模型在生成阶段就能自检合规性，而非依赖运行时拒绝后的重试。

4. 为大输出工具设置保守默认值。 对所有可能产生大量输出的工具参数（搜索结果数、文件行数、PDF 页数），设置保守的默认限制。同时提供显式的“解除限制“选项（如 head_limit=0），并在提示词中说明“谨慎使用“。

5. 控制工具描述本身的 token 成本。 参考 SkillTool 的 1% 上下文窗口预算和三级截断策略。当你的工具集不断增长时，工具描述的总 token 开销也在增长。为工具描述分配固定预算，优先保留核心工具的完整性，边缘工具渐进退化。

6. 用动态条件控制能力声明。 不要在提示词中声明运行时不一定能兑现的能力。参考 FileReadTool 的 isPDFSupported() 条件检查 – 如果 PDF 解析不可用，就不要在提示词中提及 PDF 支持。提示词承诺了运行时无法兑现的能力，会导致模型反复尝试失败，浪费上下文窗口。

8.11 小结

工具提示词是 Claude Code 驾驭体系中最“接地“的层级。系统提示词设定人格，工具提示词塑造动作。六个工具的提示词设计展示了一个核心规律：优秀的工具提示词不是功能文档，而是行为契约。它不仅告诉模型“这个工具能做什么“，更告诉它“在什么条件下用这个工具“、“怎样用才安全”、“什么时候该用其他工具”。

下一章我们将从单个工具的微观驾驭上升到工具协作的宏观编排 – 探索工具之间如何通过权限系统、状态传递和并发控制形成一个协调的整体。

第9章：自动压缩 — 上下文何时以及如何被压缩

“The best compression is the one the user never notices.”

每一个 Claude Code 的长会话用户都经历过这个时刻：你正在让模型逐步重构一个复杂模块，突然你注意到模型的回答变得“健忘“——它忘记了五分钟前你明确要求保留的接口签名，或者重复建议你已经否决过的方案。这不是模型变笨了，而是上下文窗口满了，自动压缩刚刚发生。

压缩（compaction）是 Claude Code 上下文管理的核心机制。它决定了你的对话历史在什么时刻、以什么方式被浓缩为一份摘要。理解这个机制，意味着你可以预测它何时触发、控制它保留什么、以及在它“出错“时知道该怎么做。

本章将从源码层面完整拆解自动压缩的三个阶段：阈值判定（何时触发）、摘要生成（如何压缩）、失败恢复（出错怎么办）。

9.1 阈值计算：何时触发自动压缩

9.1.1 核心公式

自动压缩的触发条件可以用一个简单的不等式表达：

当前 token 数 >= autoCompactThreshold

而 autoCompactThreshold 的计算涉及三个常量和两层减法。让我们从源码中逐步推导。

第一层：有效上下文窗口

// services/compact/autoCompact.ts:30
const MAX_OUTPUT_TOKENS_FOR_SUMMARY = 20_000

// services/compact/autoCompact.ts:33-48
      // export function getEffectiveContextWindowSize(model: string): number {
  const reservedTokensForSummary = Math.min(
    getMaxOutputTokensForModel(model),
    MAX_OUTPUT_TOKENS_FOR_SUMMARY,
  )
  let contextWindow = getContextWindowForModel(model, getSdkBetas())

  const autoCompactWindow = process.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW
  if (autoCompactWindow) {
    const parsed = parseInt(autoCompactWindow, 10)
    if (!isNaN(parsed) && parsed > 0) {
      contextWindow = Math.min(contextWindow, parsed)
    }
  }

  return contextWindow - reservedTokensForSummary
}

这里的逻辑是：从模型的原始上下文窗口中扣除一块“压缩输出预留区“。MAX_OUTPUT_TOKENS_FOR_SUMMARY = 20_000 这个值来自 p99.99 的实际压缩输出统计——99.99% 的压缩摘要都在 17,387 tokens 以内，20K 是带安全余量的上界。

注意 Math.min(getMaxOutputTokensForModel(model), MAX_OUTPUT_TOKENS_FOR_SUMMARY) 这个取小值操作：如果某个模型的最大输出上限本身就低于 20K（比如某些 Bedrock 配置），则使用模型自身的上限。

第二层：自动压缩缓冲区

// services/compact/autoCompact.ts:62
export const AUTOCOMPACT_BUFFER_TOKENS = 13_000

// services/compact/autoCompact.ts:72-91
      // export function getAutoCompactThreshold(model: string): number {
  const effectiveContextWindow = getEffectiveContextWindowSize(model)
  const autocompactThreshold =
    effectiveContextWindow - AUTOCOMPACT_BUFFER_TOKENS

  const envPercent = process.env.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE
  if (envPercent) {
    const parsed = parseFloat(envPercent)
    if (!isNaN(parsed) && parsed > 0 && parsed <= 100) {
      const percentageThreshold = Math.floor(
        effectiveContextWindow * (parsed / 100),
      )
      return Math.min(percentageThreshold, autocompactThreshold)
    }
  }

  return autocompactThreshold
}

AUTOCOMPACT_BUFFER_TOKENS = 13_000 是一个额外的安全缓冲——它确保在阈值触发到实际执行压缩之间，还有足够的空间容纳当前轮次可能产生的额外 tokens（工具调用结果、系统消息等）。

9.1.2 阈值计算公式表

以 Claude Sonnet 4 (200K 上下文窗口) 为例：

用更直观的方式表达：

|<------------ 200K 上下文窗口 ------------>|
|<---- 167K 可用 ---->|<- 13K 缓冲 ->|<- 20K 压缩输出预留 ->|
                      ^               ^
                自动压缩触发点     有效窗口边界

这意味着在默认配置下，当你的对话消耗了约 83.5% 的上下文窗口时，自动压缩就会触发。

9.1.3 环境变量覆盖

Claude Code 提供了两个环境变量让用户（或测试环境）覆盖默认阈值：

CLAUDE_CODE_AUTO_COMPACT_WINDOW — 覆盖上下文窗口大小

// services/compact/autoCompact.ts:40-46
const autoCompactWindow = process.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW
if (autoCompactWindow) {
  const parsed = parseInt(autoCompactWindow, 10)
  if (!isNaN(parsed) && parsed > 0) {
    contextWindow = Math.min(contextWindow, parsed)
  }
}

这个变量取的是 Math.min(实际窗口, 设置值)——你只能缩小窗口，不能扩大。典型用例：在 CI 环境中设置一个较小的窗口值，强制更频繁地触发压缩以测试其稳定性。

CLAUDE_AUTOCOMPACT_PCT_OVERRIDE — 按百分比覆盖阈值

// services/compact/autoCompact.ts:79-87
const envPercent = process.env.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE
if (envPercent) {
  const parsed = parseFloat(envPercent)
  if (!isNaN(parsed) && parsed > 0 && parsed <= 100) {
    const percentageThreshold = Math.floor(
      effectiveContextWindow * (parsed / 100),
    )
    return Math.min(percentageThreshold, autocompactThreshold)
  }
}

例如设置 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50，阈值就变成有效窗口的 50%（90,000 tokens），但同样取 Math.min——这个覆盖值不能高于默认阈值，只能让压缩更早触发。

9.1.4 完整判定流程

shouldAutoCompact() 函数（autoCompact.ts:160-239）在比较 token 数之前，还有一系列前置守卫：

shouldAutoCompact(messages, model, querySource)
  │
  ├─ querySource 是 'session_memory' 或 'compact'？ → false（防递归）
  ├─ querySource 是 'marble_origami'（ctx-agent）？ → false（防共享状态污染）
  ├─ isAutoCompactEnabled() 返回 false？ → false
  │   ├─ DISABLE_COMPACT 环境变量为 truthy？ → false
  │   ├─ DISABLE_AUTO_COMPACT 环境变量为 truthy？ → false
  │   └─ 用户配置 autoCompactEnabled = false？ → false
  ├─ REACTIVE_COMPACT 实验模式激活？ → false（让 reactive compact 接管）
  ├─ Context Collapse 激活？ → false（collapse 拥有自己的上下文管理）
  │
  └─ tokenCount >= autoCompactThreshold？ → true/false

注意源码中对 Context Collapse 的详细注释（autoCompact.ts:199-222）：autocompact 在有效窗口的约 93% 处触发，而 Context Collapse 在 90% 开始提交、95% 执行阻塞——如果两者同时运行，autocompact 会“抢跑“并销毁 Collapse 正准备保存的细粒度上下文。因此当 Collapse 开启时，主动式 autocompact 被禁用，只保留 reactive compact 作为 413 错误的兜底。

9.2 熔断器：连续失败保护

9.2.1 问题背景

在理想情况下，压缩完成后上下文会显著缩小，下一轮就不再触发。但现实中存在一类“不可恢复“的场景：上下文中包含大量不可压缩的系统消息、附件或编码数据，压缩后的结果仍然超过阈值，导致下一轮立刻再次触发压缩——形成无限循环。

源码注释记录了一个真实的规模数据（autoCompact.ts:68-69）：

BQ 2026-03-10: 1,279 sessions had 50+ consecutive failures (up to 3,272) in a single session, wasting ~250K API calls/day globally.

1,279 个会话中，有会话连续失败了 3,272 次，全局每天浪费约 25 万次 API 调用。这不是边缘情况——这是一个需要硬性保护的系统性问题。

9.2.2 熔断器实现

// services/compact/autoCompact.ts:70
const MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES = 3

熔断器的逻辑极其简洁——整个机制不到 20 行代码：

// services/compact/autoCompact.ts:257-265
if (
  tracking?.consecutiveFailures !== undefined &&
  tracking.consecutiveFailures >= MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES
) {
  return { wasCompacted: false }
}

状态追踪通过 AutoCompactTrackingState 类型在 queryLoop 的迭代之间传递：

// services/compact/autoCompact.ts:51-60
export type AutoCompactTrackingState = {
  compacted: boolean
  turnCounter: number
  turnId: string
  consecutiveFailures?: number  // 熔断器计数器
}

• 成功时（autoCompact.ts:332）：consecutiveFailures 重置为 0
• 失败时（autoCompact.ts:341-349）：递增计数，达到 3 次后记录警告日志并不再尝试
• 熔断后：该会话后续所有轮次的 autocompact 请求直接返回 { wasCompacted: false }

这个设计体现了一个重要原则：宁可让用户手动执行 /compact，也不要用注定失败的重试浪费 API 预算。熔断器只阻止自动压缩，用户仍然可以通过 /compact 命令手动触发。

9.3 压缩提示词剖析：9 段模板

当阈值触发后，Claude Code 需要向模型发送一条特殊的提示词，要求它将整个对话浓缩为一份结构化摘要。这个提示词的设计是压缩质量的关键——它直接决定了摘要中保留了什么、丢失了什么。

9.3.1 三种提示词变体

源码中定义了三种压缩提示词变体，分别对应不同的压缩场景：

三者的核心区别在于摘要的“视野范围“：

• BASE 告诉模型：“Your task is to create a detailed summary of the conversation so far”——总结全部
• PARTIAL 告诉模型：“Your task is to create a detailed summary of the RECENT portion of the conversation — the messages that follow earlier retained context”——只总结新增部分
• PARTIAL_UP_TO 告诉模型：“This summary will be placed at the start of a continuing session; newer messages that build on this context will follow after your summary”——总结前缀，为后续消息提供上下文

9.3.2 模板结构分析

以 BASE_COMPACT_PROMPT 为例（prompt.ts:61-143），整个提示词由 9 个结构化段落组成。下面逐段分析其设计意图：

9.3.3 <analysis> 草稿块：隐藏的质量保证机制

在 9 段摘要之前，模板要求模型先生成一个 <analysis> 块：

// prompt.ts:31-44
const DETAILED_ANALYSIS_INSTRUCTION_BASE = `Before providing your final summary,
wrap your analysis in <analysis> tags to organize your thoughts and ensure
you've covered all necessary points. In your analysis process:

1. Chronologically analyze each message and section of the conversation.
   For each section thoroughly identify:
   - The user's explicit requests and intents
   - Your approach to addressing the user's requests
   - Key decisions, technical concepts and code patterns
   - Specific details like:
     - file names
     - full code snippets
     - function signatures
     - file edits
   - Errors that you ran into and how you fixed them
   - Pay special attention to specific user feedback...
2. Double-check for technical accuracy and completeness...`

这个 <analysis> 块是一个草稿空间（drafting scratchpad）——模型在生成最终摘要之前，先按时间顺序遍历整个对话。关键词是“Chronologically analyze each message“，这迫使模型按序处理而不是跳着总结，减少遗漏。

但这个草稿块不会出现在最终上下文中。formatCompactSummary() 函数（prompt.ts:311-335）会将其完全剥离：

// prompt.ts:316-319
formattedSummary = formattedSummary.replace(
  /<analysis>[\s\S]*?<\/analysis>/,
  '',
)

这是一个巧妙的“思维链“（chain-of-thought）应用：利用 <analysis> 块提升摘要质量，但不让它消耗压缩后的上下文空间。草稿块的 tokens 只在压缩 API 调用的输出中产生，不会成为后续对话的上下文负担。

9.3.4 NO_TOOLS_PREAMBLE：防止工具调用

所有三种变体在最前面都会注入一段“禁止工具调用“的强硬前言：

// prompt.ts:19-26
const NO_TOOLS_PREAMBLE = `CRITICAL: Respond with TEXT ONLY. Do NOT call any tools.

- Do NOT use Read, Bash, Grep, Glob, Edit, Write, or ANY other tool.
- You already have all the context you need in the conversation above.
- Tool calls will be REJECTED and will waste your only turn — you will fail the task.
- Your entire response must be plain text: an <analysis> block followed by a <summary> block.
`

并且在结尾还有一个呼应的 trailer（prompt.ts:269-272）：

const NO_TOOLS_TRAILER =
  '\n\nREMINDER: Do NOT call any tools. Respond with plain text only — ' +
  'an <analysis> block followed by a <summary> block. ' +
  'Tool calls will be rejected and you will fail the task.'

源码注释解释了为什么需要如此“激进“的禁令（prompt.ts:12-18）：压缩请求使用 maxTurns: 1 执行（只允许一轮响应），如果模型在这一轮中尝试了工具调用，工具调用会被拒绝，导致没有文本输出——整个压缩失败，回退到流式后备路径（streaming fallback），在 Sonnet 4.6 上该问题的发生率达到 2.79%。首尾双重禁令将这个问题压缩到可忽略的水平。

9.3.5 PARTIAL 变体的差异

PARTIAL_COMPACT_PROMPT 和 BASE_COMPACT_PROMPT 的主要差异在于：

1. 视野限定：“Focus your summary on what was discussed, learned, and accomplished in the recent messages only”
2. 分析指令：DETAILED_ANALYSIS_INSTRUCTION_PARTIAL 用 “Analyze the recent messages chronologically” 替换了 BASE 版本的 “Chronologically analyze each message and section of the conversation”

PARTIAL_COMPACT_UP_TO_PROMPT 更为特殊——它的第 8 段从 “Current Work” 变成了 “Work Completed”，第 9 段从 “Optional Next Step” 变成了 “Context for Continuing Work”。这是因为 UP_TO 模式下，模型看到的只是对话的前半段（后半段会作为保留消息原样追加），所以摘要需要为“接续者“提供上下文而不是规划下一步。

9.4 压缩执行流程

9.4.1 compactConversation() 主流程

compactConversation() 函数（compact.ts:387-704）是压缩的核心编排器。其主流程可以概括为：

flowchart TD
    A[开始压缩] --> B[执行 PreCompact Hooks]
    B --> C[构建压缩提示词]
    C --> D[发送压缩请求]
    D --> E{响应是否为<br />prompt_too_long?}
    E -->|是| F[PTL 重试循环]
    E -->|否| G{摘要是否有效?}
    F --> D
    G -->|否| H[抛出错误]
    G -->|是| I[清除文件状态缓存]
    I --> J[并行生成附件:<br />文件/计划/技能/工具/MCP]
    J --> K[执行 SessionStart Hooks]
    K --> L[构建 CompactionResult]
    L --> M[记录遥测事件]
    M --> N[返回结果]

几个值得注意的细节：

预清除与后恢复（compact.ts:518-561）：压缩完成后，代码首先清空 readFileState 缓存和 loadedNestedMemoryPaths，然后通过 createPostCompactFileAttachments() 恢复最重要的文件上下文。这是一个“先忘后想起“的策略——与其在摘要中保留所有文件内容（不可靠），不如压缩后重新读取最关键的几个文件（确定性高）。文件恢复预算：最多 5 个文件，总计 50,000 tokens，单文件上限 5,000 tokens。

附件重新注入（compact.ts:566-585）：压缩吃掉了之前的 delta 附件（延迟工具声明、agent 列表、MCP 指令）。代码在压缩后以“空消息历史“为基线重新生成这些附件，确保模型在压缩后的第一轮就拥有完整的工具和指令上下文。

9.4.2 压缩后的消息结构

压缩产生的 CompactionResult 通过 buildPostCompactMessages() 组装为最终消息数组（compact.ts:330-338）：

[boundaryMarker, ...summaryMessages, ...messagesToKeep, ...attachments, ...hookResults]

其中：

• boundaryMarker：一个 SystemCompactBoundaryMessage，标记压缩发生的位置
• summaryMessages：用户消息格式的摘要，包含 getCompactUserSummaryMessage() 生成的前言（“This session is being continued from a previous conversation that ran out of context”）
• messagesToKeep：部分压缩时保留的最近消息
• attachments：文件、计划、技能、工具等附件
• hookResults：SessionStart hooks 的结果

9.5 PTL 重试：当压缩本身也太长

9.5.1 问题场景

这是一个“递归“难题：你的对话太长需要压缩，但压缩请求本身也超过了 API 的输入限制（prompt_too_long）。在极长会话（比如消耗了 190K+ tokens 的会话）中，将整个对话历史发送给压缩模型时，压缩请求的输入 tokens 可能已经逼近甚至超过上下文窗口。

9.5.2 重试机制

truncateHeadForPTLRetry() 函数（compact.ts:243-291）实现了一个“丢弃最旧内容“的重试策略：

flowchart TD
    A[压缩请求] --> B{响应以<br />PROMPT_TOO_LONG<br />开头?}
    B -->|否| C[压缩成功]
    B -->|是| D{ptlAttempts <= 3?}
    D -->|否| E[抛出错误:<br />Conversation too long]
    D -->|是| F[truncateHeadForPTLRetry]
    F --> G[解析 tokenGap]
    G --> H{tokenGap<br />可解析?}
    H -->|是| I[按 tokenGap<br />丢弃最旧的<br />API 轮次组]
    H -->|否| J[回退: 丢弃<br />20% 的轮次组]
    I --> K{至少保留<br />1 个组?}
    J --> K
    K -->|否| L[返回 null → 失败]
    K -->|是| M[prepend PTL_RETRY_MARKER]
    M --> N[用截断后的消息<br />重新发送压缩请求]
    N --> B

核心逻辑分三步：

步骤 1：按 API 轮次分组

// compact.ts:257
const groups = groupMessagesByApiRound(input)

groupMessagesByApiRound()（grouping.ts:22-60）将消息按 API 轮次边界分组——每当出现一个新的 assistant 消息 ID 时，就开始一个新组。这确保了丢弃操作不会拆散一个 tool_use 和它对应的 tool_result。

步骤 2：计算丢弃数量

// compact.ts:260-272
const tokenGap = getPromptTooLongTokenGap(ptlResponse)
let dropCount: number
if (tokenGap !== undefined) {
  let acc = 0
  dropCount = 0
  for (const g of groups) {
    acc += roughTokenCountEstimationForMessages(g)
    dropCount++
    if (acc >= tokenGap) break
  }
} else {
  dropCount = Math.max(1, Math.floor(groups.length * 0.2))
}

如果 API 的 prompt_too_long 响应中包含了具体的 token 差额（tokenGap），代码会精确地从最旧的组开始累加，直到覆盖这个差额。如果差额不可解析（某些 Vertex/Bedrock 错误格式不同），则回退到丢弃 20% 的组——一个保守但有效的启发式方法。

步骤 3：修复消息序列

// compact.ts:278-291
const sliced = groups.slice(dropCount).flat()
if (sliced[0]?.type === 'assistant') {
  return [
    createUserMessage({ content: PTL_RETRY_MARKER, isMeta: true }),
    ...sliced,
  ]
}
return sliced

丢弃最旧的组后，剩余消息的第一条可能是 assistant 消息（因为原始对话的 user 前言被分在了组 0 中被丢弃了）。API 要求第一条消息必须是 user 角色，所以代码会插入一个合成的 user 标记消息 PTL_RETRY_MARKER。

9.5.3 防止标记累积

注意 truncateHeadForPTLRetry() 开头的一个精妙处理（compact.ts:250-255）：

const input =
  messages[0]?.type === 'user' &&
  messages[0].isMeta &&
  messages[0].message.content === PTL_RETRY_MARKER
    ? messages.slice(1)
    : messages

在进行分组之前，如果消息序列的第一条是上一次重试插入的 PTL_RETRY_MARKER，代码会先将其剥离。否则这个标记会被分到组 0 中，而 20% 回退策略可能“只丢弃这个标记“——零进展，第二次重试陷入死循环。

9.5.4 重试上限与缓存穿透

// compact.ts:227
const MAX_PTL_RETRIES = 3

最多重试 3 次。每次重试不仅截断消息，还更新 cacheSafeParams（compact.ts:487-490）以确保 forked-agent 路径也使用截断后的消息：

retryCacheSafeParams = {
  ...retryCacheSafeParams,
  forkContextMessages: truncated,
}

如果 3 次重试后仍然失败，抛出 ERROR_MESSAGE_PROMPT_TOO_LONG 错误，用户会看到提示：“Conversation too long. Press esc twice to go up a few messages and try again.”

9.6 autoCompactIfNeeded() 的完整编排

将上述所有机制串联起来，autoCompactIfNeeded()（autoCompact.ts:241-351）是 queryLoop 在每轮迭代中调用的入口。它的完整流程如下：

flowchart TD
    A["queryLoop 每轮迭代"] --> B{"DISABLE_COMPACT?"}
    B -->|是| Z["返回 wasCompacted: false"]
    B -->|否| C{"consecutiveFailures >= 3?<br />(熔断器)"}
    C -->|是| Z
    C -->|否| D["shouldAutoCompact()"]
    D -->|不需要| Z
    D -->|需要| E["尝试 Session Memory 压缩"]
    E -->|成功| F["清理 + 返回结果"]
    E -->|失败/不适用| G["compactConversation()"]
    G -->|成功| H["重置 consecutiveFailures = 0<br />返回结果"]
    G -->|失败| I{"是用户中止?"}
    I -->|是| J["记录错误"]
    I -->|否| J
    J --> K["consecutiveFailures++"]
    K --> L{">= 3?"}
    L -->|是| M["记录熔断警告"]
    L -->|否| N["返回 wasCompacted: false"]
    M --> N

注意一个有趣的优先级：代码首先尝试 Session Memory 压缩（autoCompact.ts:287-310），只有当 Session Memory 不可用或无法充分释放空间时，才回退到传统的 compactConversation()。Session Memory 压缩是一种更细粒度的策略（通过修剪消息而不是全量总结），将在后续章节中详细讨论。

9.7 用户能做什么

理解了自动压缩的内部机制后，以下是你作为用户可以采取的具体行动：

9.7.1 观察压缩时机

当你在长会话中看到一个短暂的“compacting…“状态指示器时，自动压缩正在进行。根据阈值公式，在 200K 上下文窗口下，这大约发生在你使用了 167K tokens（约 83.5%）时。

9.7.2 提前手动压缩

不要等到自动压缩触发。在你完成一个子任务、准备开始下一个子任务之前，主动执行 /compact。手动压缩允许你传入自定义指令：

/compact 重点保留文件修改历史和错误修复记录，代码片段要完整

这些自定义指令会被追加到压缩提示词的末尾，直接影响摘要内容。

9.7.3 利用 CLAUDE.md 中的压缩指令

在项目的 CLAUDE.md 中可以添加压缩指令段，它们会在每次压缩时被自动注入：

## Compact Instructions
When summarizing the conversation focus on typescript code changes
and also remember the mistakes you made and how you fixed them.

9.7.4 用环境变量调整阈值

如果你发现自动压缩触发得太早（导致不必要的上下文丢失）或太晚（导致频繁的 prompt_too_long 错误），可以用环境变量微调：

# 让压缩在 70% 时就触发（更保守，更少 PTL 错误）
export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=70

# 或者直接限制"可见窗口"为 100K（适合网络慢/预算紧张的场景）
export CLAUDE_CODE_AUTO_COMPACT_WINDOW=100000

9.7.5 禁用自动压缩（不推荐）

# 只禁用自动压缩，保留手动 /compact
export DISABLE_AUTO_COMPACT=1

# 完全禁用所有压缩（包括手动）
export DISABLE_COMPACT=1

完全禁用意味着你必须手动管理上下文，否则会在上下文窗口耗尽时遇到无法恢复的 prompt_too_long 错误。

9.7.6 理解压缩后的“遗忘“

压缩后模型“遗忘“了什么，完全取决于 9 段摘要模板的覆盖范围。最容易丢失的信息类型：

1. 精确的代码差异：虽然模板要求 “full code snippets”，但极长的差异列表会被截断
2. 被否决的方案的具体原因：模板侧重于“做了什么“，对“为什么不做“的覆盖较弱
3. 早期对话中的细微偏好：如果你在对话开头提过一次“不要用 lodash“，这可能在多次压缩后消失

应对策略：将关键约束写入 CLAUDE.md（不受压缩影响），或者在压缩指令中显式列出需要保留的信息。

9.7.7 熔断后的恢复

如果你注意到模型不再自动压缩（连续 3 次失败后熔断），可以：

1. 手动执行 /compact 尝试压缩
2. 如果仍然失败，开始一个新会话——某些情况下上下文已经不可恢复

9.8 小结

自动压缩是 Claude Code 最关键的上下文管理机制之一，它的设计体现了几个重要的工程原则：

1. 多层缓冲：20K 输出预留 + 13K 缓冲区 + 3K 阻塞硬限制，三层防线确保系统在任何竞态条件下都不会溢出
2. 渐进降级：Session Memory 压缩 → 传统压缩 → PTL 重试 → 熔断，每一层都是上一层的兜底
3. 可观测性：tengu_compact、tengu_compact_failed、tengu_compact_ptl_retry 三个遥测事件覆盖了成功、失败和重试路径
4. 用户可控：环境变量覆盖、自定义压缩指令、手动 /compact 命令，给予高级用户足够的控制权

下一章我们将探讨压缩后的文件状态保留机制——压缩可以“忘记“对话历史，但不应该“忘记“它正在编辑哪些文件。

第10章：压缩后的文件状态保留

“Compression without restoration is just data loss with extra steps.”

第9章讲了压缩何时触发以及如何生成摘要。但压缩的故事并未在摘要生成后结束。当一段长对话被浓缩为一条摘要消息时，模型失去了所有原始上下文——它不再知道自己刚刚读过哪些文件，不记得正在执行的计划，甚至不知道有哪些工具可用。如果压缩后的第一个回合就要求模型继续编辑它“刚刚“读过的文件，而模型却一脸茫然地重新 Read 一遍，这不仅浪费 token，更打断了用户的工作流。

本章的主题是压缩后的状态恢复——Claude Code 如何在压缩完成后，通过一系列精心设计的附件（attachments），将模型“需要但已丢失“的关键上下文注入回对话流。我们将逐一拆解五个恢复维度：文件状态、技能内容、计划状态、Delta 工具声明，以及刻意不恢复的内容。

10.1 压缩前快照：先存再清

压缩恢复的第一步，不是在压缩后做什么，而是在压缩前先保存好现场。

10.1.1 cacheToObject + clear：快照-清空模式

// services/compact/compact.ts:517-522
// Store the current file state before clearing
const preCompactReadFileState = cacheToObject(context.readFileState)

// Clear the cache
context.readFileState.clear()
context.loadedNestedMemoryPaths?.clear()

这三行代码实现了一个经典的快照-清空模式：

1. 快照：cacheToObject(context.readFileState) 将内存中的 FileStateCache（一个 Map 结构）序列化为普通的 Record<string, { content: string; timestamp: number }> 对象。这个对象记录了压缩前模型读过的每一个文件——文件名、内容、以及最后读取的时间戳。

2. 清空：context.readFileState.clear() 清除文件状态缓存，context.loadedNestedMemoryPaths?.clear() 清除已加载的嵌套记忆路径。

为什么要先清空？因为压缩将对话历史替换为一条摘要消息。从模型的视角看，它即将“忘记“之前读过任何文件。如果不清空缓存，系统会误以为模型仍然“知道“这些文件的内容，导致后续的文件去重逻辑出错。清空后，系统进入一个干净的状态，然后有选择地恢复最重要的文件——而不是全部恢复。

10.1.2 为什么不全部恢复？

这个问题触及了压缩恢复的核心设计哲学。一次长会话中，模型可能读过几十甚至上百个文件。如果压缩后将它们全部注入回对话，就会造成一个荒谬的循环：压缩刚省出的 token 空间，立刻被恢复的文件内容填满。

因此，恢复策略的本质是一个预算分配问题——在有限的 token 预算内，选择性地恢复最有价值的状态。

10.2 文件恢复：最近 5 个文件、单文件 5K、总预算 50K

10.2.1 五个常量的预算体系

// services/compact/compact.ts:122-130
export const POST_COMPACT_MAX_FILES_TO_RESTORE = 5
export const POST_COMPACT_TOKEN_BUDGET = 50_000
export const POST_COMPACT_MAX_TOKENS_PER_FILE = 5_000
export const POST_COMPACT_MAX_TOKENS_PER_SKILL = 5_000
export const POST_COMPACT_SKILLS_TOKEN_BUDGET = 25_000

这五个常量构成了压缩后恢复的完整预算框架。下面用一张表来展示它们的分配逻辑：

表 10-1：压缩后 token 预算分配表

以 200K 上下文窗口为例，压缩后摘要大约占用 10K-20K token。文件恢复最多消耗 50K，技能恢复最多消耗 25K，总计约 75K-95K——仍然为后续对话留出了 100K+ 的空间。这是一个深思熟虑的平衡：恢复足够的上下文让模型无缝继续工作，但不至于让压缩变得无意义。

10.2.2 恢复逻辑详解

// services/compact/compact.ts:1415-1464
export async function createPostCompactFileAttachments(
  readFileState: Record<string, { content: string; timestamp: number }>,
  toolUseContext: ToolUseContext,
  maxFiles: number,
  preservedMessages: Message[] = [],
): Promise<AttachmentMessage[]> {
  const preservedReadPaths = collectReadToolFilePaths(preservedMessages)
  const recentFiles = Object.entries(readFileState)
    .map(([filename, state]) => ({ filename, ...state }))
    .filter(
      file =>
        !shouldExcludeFromPostCompactRestore(
          file.filename,
          toolUseContext.agentId,
        ) && !preservedReadPaths.has(expandPath(file.filename)),
    )
    .sort((a, b) => b.timestamp - a.timestamp)
    .slice(0, maxFiles)
  // ...
}

这个函数的逻辑可以分解为四步：

第一步：排除不需要恢复的文件。shouldExcludeFromPostCompactRestore（行 1674-1705）排除两类文件：

• 计划文件（plan files）——它们有独立的恢复通道（见 10.4 节）
• CLAUDE.md 记忆文件——这些文件通过系统提示词注入，不需要通过文件恢复通道重复注入

同时，如果某个文件路径已经出现在保留的消息尾部（preservedReadPaths），也不需要重复恢复——模型已经能在上下文中看到它。

第二步：按时间戳排序。.sort((a, b) => b.timestamp - a.timestamp) 将文件按最后读取时间降序排列。最近读取的文件最有可能是模型下一步需要操作的文件。

第三步：取前 N 个。.slice(0, maxFiles) 截取最近的 5 个文件。注意这个截取发生在排除过滤之后——如果 20 个文件中有 3 个被排除，那么参与排序的只有 17 个文件，最终取前 5 个。

第四步：并行生成附件。对选中的文件，通过 generateFileAttachment 并行重新读取文件内容，每个文件受 POST_COMPACT_MAX_TOKENS_PER_FILE（5K token）限制。这里有一个重要细节：恢复时读取的是磁盘上的当前内容，而非快照中的缓存内容。如果文件在压缩期间被外部修改（比如用户在编辑器中手动修改），恢复的内容是修改后的版本。

第五步：预算控制。生成文件附件后，还有一道预算闸门：

// services/compact/compact.ts:1452-1463
let usedTokens = 0
return results.filter((result): result is AttachmentMessage => {
  if (result === null) {
    return false
  }
  const attachmentTokens = roughTokenCountEstimation(jsonStringify(result))
  if (usedTokens + attachmentTokens <= POST_COMPACT_TOKEN_BUDGET) {
    usedTokens += attachmentTokens
    return true
  }
  return false
})

即使只有 5 个文件，如果它们都很大（每个接近 5K token），总量也可能超过 50K 预算。这个 filter 充当最后的守门人——按顺序累加每个文件的 token 数，一旦总量超过 POST_COMPACT_TOKEN_BUDGET（50K），就丢弃剩余的文件。

10.2.3 “保留 vs 丢弃“决策树

下面这棵决策树描述了每个文件在压缩后是否会被恢复的完整判定逻辑：

flowchart TD
    A["文件在压缩前被读取过？"] -->|否| B["不恢复：文件不在 readFileState 中"]
    A -->|是| C{"是 plan 文件？"}
    C -->|是| D["排除：通过 Plan 附件独立恢复（见 10.4）"]
    C -->|否| E{"是 CLAUDE.md 记忆文件？"}
    E -->|是| F["排除：通过系统提示词注入"]
    E -->|否| G{"已在保留的消息尾部？"}
    G -->|是| H["排除：模型已能看到，无需重复"]
    G -->|否| I{"按时间戳排序后排名前 5？"}
    I -->|否| J["丢弃：超出文件数量上限"]
    I -->|是| K{"单文件超过 5K token？"}
    K -->|是| L["截断到 5K token 后继续"]
    K -->|否| M{"累加后总 token 超过 50K？"}
    L --> M
    M -->|是| N["丢弃：超出总预算"]
    M -->|否| O["恢复 ✓ 作为附件注入"]

这棵决策树揭示了一个重要设计：恢复不是一个简单的“最近 N 个“算法，而是一个多层过滤管线。排除规则、数量限制、单文件截断、总预算上限，四层防护确保恢复的内容既有价值又不会过度膨胀。

10.3 技能重注入：invokedSkills 的选择性恢复

10.3.1 为什么技能需要独立恢复？

技能（Skills）是 Claude Code 的扩展能力系统。当用户在会话中调用了一个技能（比如 code-review 或 commit），技能的指令内容会被注入到对话中。压缩后，这些指令和上下文一起消失。但技能往往包含关键的行为约束——比如“提交前必须运行测试“或“代码审查时关注安全问题“。如果不恢复它们，模型在压缩后可能违反这些约束。

10.3.2 技能恢复机制

// services/compact/compact.ts:1494-1534
      // export function createSkillAttachmentIfNeeded(
  agentId?: string,
): AttachmentMessage | null {
  const invokedSkills = getInvokedSkillsForAgent(agentId)

  if (invokedSkills.size === 0) {
    return null
  }

  // Sorted most-recent-first so budget pressure drops the least-relevant skills.
  let usedTokens = 0
  const skills = Array.from(invokedSkills.values())
    .sort((a, b) => b.invokedAt - a.invokedAt)
    .map(skill => ({
      name: skill.skillName,
      path: skill.skillPath,
      content: truncateToTokens(
        skill.content,
        POST_COMPACT_MAX_TOKENS_PER_SKILL,
      ),
    }))
    .filter(skill => {
      const tokens = roughTokenCountEstimation(skill.content)
      if (usedTokens + tokens > POST_COMPACT_SKILLS_TOKEN_BUDGET) {
        return false
      }
      usedTokens += tokens
      return true
    })

  if (skills.length === 0) {
    return null
  }

  return createAttachmentMessage({
    type: 'invoked_skills',
    skills,
  })
}

技能恢复的策略与文件恢复高度相似，但有两个关键差异：

差异一：截断而非丢弃。源码注释（行 125-128）解释了设计意图：

Skills can be large (verify=18.7KB, claude-api=20.1KB). Previously re-injected unbounded on every compact → 5-10K tok/compact. Per-skill truncation beats dropping — instructions at the top of a skill file are usually the critical part.

技能文件可能很大（verify 技能 18.7KB，claude-api 技能 20.1KB），但技能文件开头的指令通常是最关键的部分。truncateToTokens 函数将每个技能截断到 5K token，保留头部指令，丢弃尾部的详细参考内容。这比“整个保留或整个丢弃“的二选一策略更精细。

差异二：按 agent 隔离。getInvokedSkillsForAgent(agentId) 只返回属于当前 agent 的技能。这防止了主会话的技能泄露到子 agent 的上下文中，反之亦然。

10.3.3 预算算术

25K 的总预算能恢复多少个技能？按每个技能 5K token 计算，理论上最多 5 个技能。源码注释也验证了这一点：“Budget sized to hold ~5 skills at the per-skill cap.”

但实际中，许多技能截断后不到 5K token，所以 25K 预算通常能覆盖会话中所有被调用的技能。只有当用户在一次长会话中调用了大量大型技能时，预算才会成为瓶颈——此时最久远的技能会被优先丢弃。

10.4 刻意不恢复的内容：sentSkillNames

并非所有被清空的状态都需要恢复。源码中最有意思的一个设计决策是：

// services/compact/compact.ts:524-529
// Intentionally NOT resetting sentSkillNames: re-injecting the full
// skill_listing (~4K tokens) post-compact is pure cache_creation with
// marginal benefit. The model still has SkillTool in its schema and
// invoked_skills attachment (below) preserves used-skill content. Ants
// with EXPERIMENTAL_SKILL_SEARCH already skip re-injection via the
// early-return in getSkillListingAttachments.

sentSkillNames 是一个模块级的 Map<string, Set<string>>，记录了哪些技能的名称列表已经发送给模型。如果在压缩后重置它，系统会在下一个请求中重新注入完整的技能列表附件——大约 4K token。

但代码故意不重置它。原因是：

1. 成本不对称：4K token 的技能列表全部是 cache_creation token（需要写入缓存的新内容），但收益微乎其微——模型仍然可以通过 SkillTool 的 schema 知道技能工具的存在。
2. 已调用的技能已被恢复：上一节的 invoked_skills 附件已经恢复了实际使用过的技能内容，模型不需要再看到完整的名称列表。
3. 实验性技能搜索：启用了 EXPERIMENTAL_SKILL_SEARCH 的环境本来就跳过技能列表注入。

这是一个典型的节省 token 的工程决策——在“恢复的完整性“和“token 成本“之间，选择了后者。4K token 看似不多，但在每次压缩后都会累积，对于频繁压缩的长会话来说，这是一笔可观的节省。

10.5 Plan 和 PlanMode 附件的保留

Claude Code 的计划模式（Plan Mode）允许模型在执行任何操作前先制定详细计划。压缩后，计划状态必须被完整保留，否则模型会“忘记“正在执行的计划。

10.5.1 Plan 附件

// services/compact/compact.ts:545-548
const planAttachment = createPlanAttachmentIfNeeded(context.agentId)
if (planAttachment) {
  postCompactFileAttachments.push(planAttachment)
}

createPlanAttachmentIfNeeded（行 1470-1486）检查当前 agent 是否有活跃的计划文件。如果有，将计划内容作为 plan_file_reference 类型的附件注入。注意，plan 文件在文件恢复阶段被 shouldExcludeFromPostCompactRestore 显式排除，正是因为它有这条独立的恢复通道——避免同一个文件被恢复两次，浪费预算。

10.5.2 PlanMode 附件

// services/compact/compact.ts:552-555
const planModeAttachment = await createPlanModeAttachmentIfNeeded(context)
if (planModeAttachment) {
  postCompactFileAttachments.push(planModeAttachment)
}

Plan 附件恢复的是计划内容，PlanMode 附件恢复的是模式状态。createPlanModeAttachmentIfNeeded（行 1542-1560）检查用户是否正处于 plan 模式（mode === 'plan'）。如果是，它注入一个 plan_mode 类型的附件，其中包含 reminderType: 'full' 标记——这确保模型在压缩后继续在 plan 模式下运行，而不是回退到正常的执行模式。

这两个附件协同工作：Plan 附件告诉模型“你正在执行这个计划“，PlanMode 附件告诉模型“你必须继续以计划模式工作“。缺少任何一个都会导致行为偏差。

10.6 Delta 附件：工具和指令的重新宣告

压缩不仅清除了文件状态，还清除了所有之前的 delta 附件。Delta 附件是系统在对话过程中逐步告知模型的“增量信息“——新注册的延迟工具、新发现的 agent、新加载的 MCP 指令。压缩后，这些信息随着旧消息一起消失。

10.6.1 三类 Delta 的完整重播

// services/compact/compact.ts:563-585
// Compaction ate prior delta attachments. Re-announce from the current
// state so the model has tool/instruction context on the first
// post-compact turn. Empty message history → diff against nothing →
// announces the full set.
for (const att of getDeferredToolsDeltaAttachment(
  context.options.tools,
  context.options.mainLoopModel,
  [],
  { callSite: 'compact_full' },
)) {
  postCompactFileAttachments.push(createAttachmentMessage(att))
}
for (const att of getAgentListingDeltaAttachment(context, [])) {
  postCompactFileAttachments.push(createAttachmentMessage(att))
}
for (const att of getMcpInstructionsDeltaAttachment(
  context.options.mcpClients,
  context.options.tools,
  context.options.mainLoopModel,
  [],
)) {
  postCompactFileAttachments.push(createAttachmentMessage(att))
}

源码注释揭示了这段代码的精妙设计：传入空数组 [] 作为消息历史。

在正常的对话轮次中，Delta 附件函数会比较当前状态和已出现在消息历史中的内容，只发送“增量“部分。但压缩后没有消息历史可以比较——传入空数组意味着 diff 的基线为空，因此函数会生成完整的工具和指令声明。

三类 Delta 附件各自的作用：

callSite: 'compact_full' 标记用于遥测分析，区分正常的增量声明和压缩后的完整重播。

10.6.2 异步 Agent 附件

// services/compact/compact.ts:532-539
const [fileAttachments, asyncAgentAttachments] = await Promise.all([
  createPostCompactFileAttachments(
    preCompactReadFileState,
    context,
    POST_COMPACT_MAX_FILES_TO_RESTORE,
  ),
  createAsyncAgentAttachmentsIfNeeded(context),
])

createAsyncAgentAttachmentsIfNeeded（行 1568-1599）检查是否有正在后台运行的异步 agent 或已完成但结果未被检索的 agent。如果有，它为每个 agent 生成一个 task_status 类型的附件，包含 agent 的描述、状态和进度摘要。这防止了压缩后模型“忘记“有后台任务在运行而重复启动相同的任务。

注意文件恢复和异步 agent 附件的生成是并行执行的（Promise.all），这是一个性能优化——两者互不依赖，没有理由串行等待。

10.7 恢复的完整编排

现在让我们将所有恢复步骤放在一起，看看压缩后状态恢复的完整编排（compact.ts 行 517-585）：

flowchart TD
    subgraph Step1["步骤 1：快照并清空"]
        S1A["cacheToObject(readFileState)<br />保存文件状态快照"]
        S1B["readFileState.clear()<br />清空文件缓存"]
        S1C["loadedNestedMemoryPaths.clear()<br />清空记忆路径"]
        S1A --> S1B --> S1C

    subgraph Step2["步骤 2：并行生成附件"]
        S2A["createPostCompactFileAttachments<br />文件恢复附件"]
        S2B["createAsyncAgentAttachmentsIfNeeded<br />异步 agent 附件"]

    subgraph Step3["步骤 3：串行生成附件"]
        S3A["createPlanAttachmentIfNeeded<br />计划内容附件"]
        S3B["createPlanModeAttachmentIfNeeded<br />计划模式附件"]
        S3C["createSkillAttachmentIfNeeded<br />已调用技能附件"]
        S3A --> S3B --> S3C

    subgraph Step4["步骤 4：Delta 完整重播"]
        S4A["getDeferredToolsDeltaAttachment<br />延迟工具"]
        S4B["getAgentListingDeltaAttachment<br />Agent 列表"]
        S4C["getMcpInstructionsDeltaAttachment<br />MCP 指令"]

    Step1 --> Step2
    Step2 --> Step3
    Step3 --> Step4
    Step4 --> Step5["步骤 5：合并为 postCompactFileAttachments<br />随压缩后第一条消息发送给模型"]

这个编排的关键特征是层次化和选择性。不是所有状态都被恢复，恢复的方式也各不相同——文件通过重新读取恢复，技能通过截断重注入恢复，计划通过专用附件恢复，工具声明通过 delta 重播恢复。每种状态都有最适合它的恢复通道。

10.8 用户能做什么

理解了压缩后恢复机制，你可以采取以下策略来优化长会话体验：

10.8.1 保持文件读取的聚焦

压缩后只恢复最近读取的 5 个文件。如果你在一次对话中让模型读取了 20 个文件，压缩后只有最后 5 个会被自动恢复。这意味着你在对话前半段让模型读取的那些“参考文件“——测试用例、类型定义、配置文件——很可能在压缩后全部丢失。

策略：在执行复杂任务时，优先让模型读取它下一步需要编辑的文件，而不是“先把所有相关文件都读一遍“。最后读取的文件最有可能在压缩后被保留。如果某个文件对任务至关重要但已经很久没被读取，考虑在你预感压缩即将到来时（比如对话已经进行了 30+ 轮），让模型重新读取一次，刷新它的时间戳。

10.8.2 大文件的截断预期

每个文件恢复上限为 5K token（约 2000-2500 行代码，取决于语言）。如果你正在编辑一个超大文件，压缩后模型只能看到文件的开头部分。

策略：在压缩可能发生的节点（当你注意到对话已经很长时），显式提醒模型关注大文件中的特定区域。或者更好的做法是，将关键约束写入 CLAUDE.md——它永远不受压缩影响。

10.8.3 压缩后技能的行为变化

技能被截断到 5K token 后，文件尾部的参考内容可能丢失。如果你依赖的技能行为在压缩后发生了变化，这可能是截断导致的。

策略：将最关键的技能指令放在技能文件的开头，而非末尾。Claude Code 的截断策略保留头部——这意味着技能文件的结构应该是“关键指令在前，补充参考在后“。

10.8.4 利用 Plan Mode 跨越压缩

如果你在执行一个多步骤任务，使用 plan 模式可以确保计划在压缩后被完整保留。计划附件不受 50K 文件预算的限制，它有独立的恢复通道。

策略：对于可能跨越压缩边界的复杂任务，先让模型制定计划（/plan），然后逐步执行。即使压缩发生在执行过程中，模型也能恢复计划上下文继续工作。

10.8.5 留意“压缩遗忘“的模式

如果压缩后模型突然：

• 重新读取它“刚刚“读过的文件——这个文件可能排在第 6 名之后，未被恢复
• 忘记了后台 agent 的存在——检查 agent 是否已被标记为 retrieved 或 pending
• 不再遵守某个 MCP 工具的约束——delta 重播通常能覆盖，但极端情况下可能有遗漏
• 对之前否决的方案重新提议——摘要倾向于保留“做了什么“，而非“否决了什么“

这些都是正常的工程权衡。预算是有限的，100% 的恢复既不可能也不必要。理解哪些信息“幸存“于压缩、哪些信息会丢失，是驾驭长会话的关键能力。

10.8.6 多次压缩的累积效应

一次极长的会话可能经历多次压缩。每次压缩都会：

• 将所有文件状态缓存清空并重建（最多 5 个）
• 重新截断技能内容（每次都从原始内容截断，不会“截断的截断“）
• 重新生成 Delta 附件（完整重播）

但摘要是不可逆的。第二次压缩的摘要是基于“第一次的摘要 + 后续对话“生成的，信息密度逐次降低。经过三四次压缩后，对话开头的细节几乎不可能被保留。

策略：对于预计超长的任务，在关键的中间节点主动使用 /compact 并附加自定义指令，明确列出需要保留的关键信息。不要等到系统自动压缩——那时你无法控制摘要的重点。

10.9 小结

压缩后的状态恢复体现了 Claude Code 在“信息完整性“和“token 经济性“之间的精细平衡：

1. 快照-清空模式：先保存现场再清空，确保恢复有据可依、缓存状态一致
2. 分层预算：文件恢复 50K、技能恢复 25K、独立的 plan 通道——不同类型的状态有不同的恢复预算和策略
3. 选择性恢复：时间戳排序 + 排除规则 + 预算控制，三层过滤确保只恢复最有价值的内容
4. 刻意不恢复：sentSkillNames 的保留是一个反直觉但正确的决策——4K token 的技能列表注入成本大于收益
5. Delta 完整重播：传入空消息历史触发完整重播，是一个巧妙的复用现有增量机制的设计

核心启示：压缩不是“遗忘“，而是“有选择地记住“。理解这个选择的逻辑，你就能预测压缩后模型会记住什么、忘记什么，并据此调整自己的工作方式。

第11章：微压缩 — 精准上下文修剪

“The cheapest token is the one you never send.”

上一章（第9章）我们详尽分析了自动压缩——当上下文接近窗口上限时，Claude Code 将整个对话浓缩为一份结构化摘要。这是一种“核选项“：有效但代价高昂，它会丢失对话的原始细节，而且需要一次完整的 LLM 调用来生成摘要。

本章的主角是微压缩（microcompact）——一种轻量级的上下文修剪策略。它不生成摘要，不调用 LLM，而是直接清除或删除旧的工具调用结果。你三分钟前 grep 搜索的 200 行输出、半小时前 cat 读取的配置文件、一小时前 bash 命令的日志——这些信息对模型当前的推理任务来说已经“过时“了。微压缩的核心哲学是：与其让这些过时内容占据宝贵的上下文空间，不如在恰当的时机精准地移除它们。

Claude Code 实现了三种微压缩机制，它们在触发条件、执行方式和缓存影响上截然不同：

这三种机制的优先级关系也很明确：时间触发最先执行并短路，缓存微压缩其次，API Context Management 作为独立的声明式层始终存在。

11.1 基于时间的微压缩：缓存过期后的批量清理

11.1.1 设计直觉

想象这样一个场景：你在上午 10 点用 Claude Code 完成了一次复杂的重构，然后去吃午饭。下午 1 点回来继续工作——中间间隔了 3 个小时。

在这 3 个小时里发生了什么？服务端的 prompt cache 已经过期了。Anthropic 的 prompt cache 有两个 TTL 档位：5 分钟（标准）和 1 小时（扩展）。无论是哪个档位，3 小时后都已失效。这意味着你的下一次 API 调用会将完整的对话历史重新写入缓存——每一个 token 都要重新计费为 cache creation。

基于时间的微压缩的逻辑因此非常自然：既然缓存已经过期，整个前缀都要重写，那不如先把不需要的旧内容清掉，让重写的内容更小更便宜。

11.1.2 配置参数

配置通过 GrowthBook 功能开关 tengu_slate_heron 下发，类型为 TimeBasedMCConfig：

// services/compact/timeBasedMCConfig.ts:18-28
export type TimeBasedMCConfig = {
  /** Master switch. When false, time-based microcompact is a no-op. */
  enabled: boolean
  /** Trigger when (now − last assistant timestamp) exceeds this many minutes. */
  gapThresholdMinutes: number
  /** Keep this many most-recent compactable tool results. */
  keepRecent: number
}

const TIME_BASED_MC_CONFIG_DEFAULTS: TimeBasedMCConfig = {
  enabled: false,
  gapThresholdMinutes: 60,
  keepRecent: 5,
}

三个参数各有其考量：

• enabled 默认关闭——这是一个灰度发布特性，通过 GrowthBook 逐步开启
• gapThresholdMinutes: 60 对齐服务端 1 小时 cache TTL——这是“安全选择“，源码注释（第 23 行）明确说明：“the server’s 1h cache TTL is guaranteed expired for all users, so we never force a miss that wouldn’t have happened”
• keepRecent: 5 保留最近 5 个工具结果，为模型提供最小工作上下文

11.1.3 触发判定

evaluateTimeBasedTrigger() 函数（microCompact.ts:422-444）是一个纯判定函数，不产生副作用：

// microCompact.ts:422-444
      // export function evaluateTimeBasedTrigger(
  messages: Message[],
  querySource: QuerySource | undefined,
): { gapMinutes: number; config: TimeBasedMCConfig } | null {
  const config = getTimeBasedMCConfig()
  if (!config.enabled || !querySource || !isMainThreadSource(querySource)) {
    return null
  }
  const lastAssistant = messages.findLast(m => m.type === 'assistant')
  if (!lastAssistant) {
    return null
  }
  const gapMinutes =
    (Date.now() - new Date(lastAssistant.timestamp).getTime()) / 60_000
  if (!Number.isFinite(gapMinutes) || gapMinutes < config.gapThresholdMinutes) {
    return null
  }
  return { gapMinutes, config }
}

注意第 428 行的守卫条件：!querySource 时直接返回 null。这与缓存微压缩的行为不同——isMainThreadSource()（第 249-251 行）将 undefined 视为主线程（为了缓存 MC 的向后兼容），但时间触发显式要求 querySource 存在。源码注释（第 429-431 行）解释了原因：/context、/compact 等分析性调用会在不带 source 的情况下调用 microcompactMessages()，它们不应该触发时间清理。

11.1.4 执行逻辑

当触发条件满足时，maybeTimeBasedMicrocompact() 执行以下步骤：

flowchart TD
    A["maybeTimeBasedMicrocompact(messages, querySource)"] --> B{"evaluateTimeBasedTrigger()"}
    B -->|null| C["返回 null（不触发）"]
    B -->|触发| D["collectCompactableToolIds(messages)<br />收集所有可压缩工具 ID"]
    D --> E["keepRecent = Math.max(1, config.keepRecent)<br />至少保留 1 个<br />（slice(-0) 返回整个数组）"]
    E --> F["keepSet = compactableIds.slice(-keepRecent)<br />保留最近 N 个"]
    F --> G["clearSet = 其余全部清除"]
    G --> H["遍历 messages，将 clearSet 中的<br />tool_result.content 替换为占位文本"]
    H --> I["suppressCompactWarning()<br />抑制上下文压力警告"]
    I --> J["resetMicrocompactState()<br />重置缓存 MC 状态"]
    J --> K["notifyCacheDeletion()<br />通知缓存中断检测器"]

关键实现细节在 microCompact.ts:470-492——消息修改采用不可变风格：

// microCompact.ts:470-492
let tokensSaved = 0
const result: Message[] = messages.map(message => {
  if (message.type !== 'user' || !Array.isArray(message.message.content)) {
    return message
  }
  let touched = false
  const newContent = message.message.content.map(block => {
    if (
      block.type === 'tool_result' &&
      clearSet.has(block.tool_use_id) &&
      block.content !== TIME_BASED_MC_CLEARED_MESSAGE
    ) {
      tokensSaved += calculateToolResultTokens(block)
      touched = true
      return { ...block, content: TIME_BASED_MC_CLEARED_MESSAGE }
    }
    return block
  })
  if (!touched) return message
  return {
    ...message,
    message: { ...message.message, content: newContent },
  }
})

注意第 479 行的 block.content !== TIME_BASED_MC_CLEARED_MESSAGE 守卫——防止对已清除的内容重复计算 tokensSaved。这是幂等性保证：多次执行不会改变 tokensSaved 的统计值。

11.1.5 副作用链

时间触发执行完毕后，会产生三个重要的副作用：

1. suppressCompactWarning()（第 511 行）：微压缩释放了上下文空间，抑制“上下文即将满“的用户可见警告
2. resetMicrocompactState()（第 517 行）：清空缓存 MC 的工具注册状态——因为我们刚修改了消息内容、破坏了服务端缓存，缓存 MC 的旧状态（哪些工具已注册、哪些已删除）全部失效
3. notifyCacheDeletion(querySource)（第 526 行）：通知 promptCacheBreakDetection 模块，下一次 API 响应的 cache_read_tokens 会下降——这是预期行为，不是缓存中断 bug

第三个副作用特别微妙。源码注释（第 520-522 行）解释了为什么使用 notifyCacheDeletion 而不是 notifyCompaction：“notifyCacheDeletion (not notifyCompaction) because it’s already imported here and achieves the same false-positive suppression — adding the second symbol to the import was flagged by the circular-deps check.” 这是循环依赖约束下的务实选择：两个函数的效果相同（都防止误报），但引入额外的 import symbol 会触发循环依赖检测。

11.2 缓存微压缩：不破坏缓存的精准手术

11.2.1 核心挑战

时间触发的微压缩有一个本质局限：它必须修改消息内容，这意味着缓存前缀被改变，下一次 API 调用会产生完整的 cache creation 费用。当缓存已过期时这无所谓（反正都要重写），但在实时会话中，这是不可接受的——你刚积累的缓存前缀可能价值数万 tokens 的 cache creation 费用。

缓存微压缩（cached microcompact）通过 Anthropic API 的 cache_edits 特性解决了这个问题：它不修改本地消息内容，而是向 API 发送“在服务端缓存中删除指定工具结果“的指令。服务端在缓存前缀中原地移除这些内容，保持前缀的连续性——下一次请求仍然能命中已有缓存。

11.2.2 cache_edits 工作原理

以下序列图展示了缓存微压缩的完整生命周期：

sequenceDiagram
    participant MC as microCompact.ts
    participant API as claude.ts (API layer)
    participant Server as Anthropic API Server

    MC->>MC: ① registerToolResult()<br />注册 tool_results
    MC->>MC: ② getToolResultsToDelete()<br />检查是否达到阈值
    MC->>MC: ③ createCacheEditsBlock()<br />创建 cache_edits block
    MC->>API: ④ 存入 pendingCacheEdits

    API->>API: ⑤ consumePendingCacheEdits()
    API->>API: ⑥ getPinnedCacheEdits()
    API->>API: ⑦ addCacheBreakpoints()<br />在 user message 中插入 cache_edits block<br />为 tool_result 添加 cache_reference

    API->>Server: ⑧ API Request: messages 包含 cache_edits
    Server->>Server: ⑨ 在缓存中删除对应 tool_result<br />缓存前缀保持连续
    Server-->>API: ⑩ Response: cache_deleted_input_tokens (累积值)

    API->>API: ⑪ pinCacheEdits()
    API->>API: ⑫ markToolsSentToAPIState()

让我们逐步拆解这个流程。

11.2.3 工具注册与阈值判定

cachedMicrocompactPath() 函数（microCompact.ts:305-399）首先扫描所有消息，注册可压缩的工具结果：

// microCompact.ts:313-329
const compactableToolIds = new Set(collectCompactableToolIds(messages))
// Second pass: register tool results grouped by user message
for (const message of messages) {
  if (message.type === 'user' && Array.isArray(message.message.content)) {
    const groupIds: string[] = []
    for (const block of message.message.content) {
      if (
        block.type === 'tool_result' &&
        compactableToolIds.has(block.tool_use_id) &&
        !state.registeredTools.has(block.tool_use_id)
      ) {
        mod.registerToolResult(state, block.tool_use_id)
        groupIds.push(block.tool_use_id)
      }
    }
    mod.registerToolMessage(state, groupIds)
  }
}

注册分两步：collectCompactableToolIds() 先从 assistant 消息中收集所有属于可压缩工具集的 tool_use ID，然后在 user 消息中找到对应的 tool_result，按消息分组注册。分组是因为 cache_edits 的删除粒度是单个 tool_result，但触发判定基于工具总数。

注册后调用 mod.getToolResultsToDelete(state) 获取需要删除的工具列表。这个函数的逻辑由 GrowthBook 配置的 triggerThreshold 和 keepRecent 控制——当注册的工具总数超过 triggerThreshold 时，保留最近 keepRecent 个，其余标记为待删除。

11.2.4 cache_edits block 的生命周期

当有工具需要删除时，代码创建一个 CacheEditsBlock 并存入模块级变量 pendingCacheEdits：

// microCompact.ts:334-339
const toolsToDelete = mod.getToolResultsToDelete(state)

if (toolsToDelete.length > 0) {
  const cacheEdits = mod.createCacheEditsBlock(state, toolsToDelete)
  if (cacheEdits) {
    pendingCacheEdits = cacheEdits
  }

这个 pendingCacheEdits 变量的消费者是 API 层的 claude.ts。在构建 API 请求参数前（第 1531 行），代码调用 consumePendingCacheEdits() 一次性取出待发送的编辑指令：

// claude.ts:1531-1532
const consumedCacheEdits = cachedMCEnabled ? consumePendingCacheEdits() : null
const consumedPinnedEdits = cachedMCEnabled ? getPinnedCacheEdits() : []

consumePendingCacheEdits() 的设计是单次消费（microCompact.ts:88-94）：调用后立即清空 pendingCacheEdits。源码注释（第 1528-1530 行）解释了为什么不能在 paramsFromContext 内部消费：“paramsFromContext is called multiple times (logging, retries), so consuming inside it would cause the first call to steal edits from subsequent calls.”

11.2.5 在 API 请求中插入 cache_edits

addCacheBreakpoints() 函数（claude.ts:3063-3162）负责将 cache_edits 指令织入消息数组。核心逻辑分三步：

第一步：重新插入已固定的编辑（第 3128-3139 行）

// claude.ts:3128-3139
for (const pinned of pinnedEdits ?? []) {
  const msg = result[pinned.userMessageIndex]
  if (msg && msg.role === 'user') {
    if (!Array.isArray(msg.content)) {
      msg.content = [{ type: 'text', text: msg.content as string }]
    }
    const dedupedBlock = deduplicateEdits(pinned.block)
    if (dedupedBlock.edits.length > 0) {
      insertBlockAfterToolResults(msg.content, dedupedBlock)
    }
  }
}

每一轮 API 调用，之前已发送过的 cache_edits 必须在相同位置重新发送——服务端需要看到完整一致的编辑历史才能正确重建缓存前缀。这就是 pinnedEdits 的作用。

第二步：插入新的编辑（第 3142-3162 行）

新的 cache_edits block 被插入到最后一个 user 消息中，然后通过 pinCacheEdits(i, newCacheEdits) 固定位置索引，确保后续调用在同一位置重复发送。

第三步：去重

deduplicateEdits() 辅助函数（第 3116-3125 行）使用 seenDeleteRefs Set 确保同一个 cache_reference 不会在多个 block 中重复出现。这防止了一种边缘情况：同一个工具结果在不同轮次被标记为待删除。

11.2.6 cache_edits 数据结构

在 API 层，cache_edits block 的类型定义（claude.ts:3052-3055）非常简洁：

type CachedMCEditsBlock = {
  type: 'cache_edits'
  edits: { type: 'delete'; cache_reference: string }[]
}

每个 edit 是一个 delete 操作，指向一个 cache_reference——这是服务端为每个 tool_result 分配的唯一标识符。客户端在之前的 API 响应中获取这些引用，然后在后续请求中引用它们来指定要删除的内容。

11.2.7 baseline 与 delta 追踪

cachedMicrocompactPath() 在返回结果时，记录了一个 baselineCacheDeletedTokens 值（第 374-383 行）：

// microCompact.ts:374-383
const lastAsst = messages.findLast(m => m.type === 'assistant')
const baseline =
  lastAsst?.type === 'assistant'
    ? ((
        lastAsst.message.usage as unknown as Record<
          string,
          number | undefined
        >
      )?.cache_deleted_input_tokens ?? 0)
    : 0

API 返回的 cache_deleted_input_tokens 是一个累积值——它包含本次会话中所有 cache_edits 操作删除的总 token 数。为了计算当前操作的实际 delta，需要记录操作前的 baseline，然后用 API 响应中的新累积值减去它。这个设计避免了在客户端做不精确的 token 估算。

11.2.8 与时间触发的互斥

microcompactMessages() 的入口函数（第 253-293 行）定义了严格的优先级：

// microCompact.ts:267-270
const timeBasedResult = maybeTimeBasedMicrocompact(messages, querySource)
if (timeBasedResult) {
  return timeBasedResult
}

时间触发优先执行并短路。源码注释（第 261-266 行）解释了为什么：“If the gap since the last assistant message exceeds the threshold, the server cache has expired and the full prefix will be rewritten regardless — so content-clear old tool results now … Cached MC (cache-editing) is skipped when this fires: editing assumes a warm cache, and we just established it’s cold.”

这是一个精妙的互斥设计：

• 缓存热（warm cache）：使用 cache_edits，在不破坏缓存的前提下删除内容
• 缓存冷（cold cache）：使用时间触发，直接修改内容，反正缓存已经失效

两种机制不会同时执行。

11.3 API Context Management：声明式上下文管理

11.3.1 从命令式到声明式

前两种微压缩机制都是命令式的——客户端决定删除哪些工具、何时删除、怎么删除。API Context Management 则是声明式的：客户端只需描述“当上下文超过 X tokens 时，清除 Y 类型的内容，保留最近 Z 个“，API 服务端自动执行。

这段逻辑位于 apiMicrocompact.ts，函数 getAPIContextManagement() 构建一个 ContextManagementConfig 对象，随 API 请求一起发送：

// apiMicrocompact.ts:59-62
export type ContextManagementConfig = {
  edits: ContextEditStrategy[]
}

11.3.2 两种策略类型

ContextEditStrategy 联合类型定义了两种服务端可执行的编辑策略：

策略一：clear_tool_uses_20250919

// apiMicrocompact.ts:36-53
| {
    type: 'clear_tool_uses_20250919'
    trigger?: {
      type: 'input_tokens'
      value: number        // 当 input tokens 超过此值时触发
    }
    keep?: {
      type: 'tool_uses'
      value: number        // 保留最近 N 个工具使用
    }
    clear_tool_inputs?: boolean | string[]  // 清除哪些工具的输入
    exclude_tools?: string[]                // 排除哪些工具
    clear_at_least?: {
      type: 'input_tokens'
      value: number        // 至少清除这么多 tokens
    }
  }

策略二：clear_thinking_20251015

// apiMicrocompact.ts:54-56
| {
    type: 'clear_thinking_20251015'
    keep: { type: 'thinking_turns'; value: number } | 'all'
  }

这种策略专门处理 thinking blocks——extended thinking 模型（如 Claude Sonnet 4 with thinking）会生成大量思考过程，这些内容在后续轮次中的价值迅速衰减。

11.3.3 策略组合逻辑

getAPIContextManagement() 根据运行时条件组合多个策略：

// apiMicrocompact.ts:64-88
      // export function getAPIContextManagement(options?: {
  hasThinking?: boolean
  isRedactThinkingActive?: boolean
  clearAllThinking?: boolean
}): ContextManagementConfig | undefined {
  const {
    hasThinking = false,
    isRedactThinkingActive = false,
    clearAllThinking = false,
  } = options ?? {}

  const strategies: ContextEditStrategy[] = []

  // 策略 1: thinking 管理
  if (hasThinking && !isRedactThinkingActive) {
    strategies.push({
      type: 'clear_thinking_20251015',
      keep: clearAllThinking
        ? { type: 'thinking_turns', value: 1 }
        : 'all',
    })
  }
  // ...
}

thinking 策略的三个分支：

注意 clearAllThinking 时 value 设为 1 而不是 0——源码注释（第 81 行）解释：“the API schema requires value >= 1, and omitting the edit falls back to the model-policy default (often ‘all’), which wouldn’t clear.”

11.3.4 工具清除的两种模式

在 clear_tool_uses_20250919 策略中，工具清除有两种互补模式：

模式一：清除工具结果（clear_tool_inputs）

// apiMicrocompact.ts:104-124
if (useClearToolResults) {
  const strategy: ContextEditStrategy = {
    type: 'clear_tool_uses_20250919',
    trigger: { type: 'input_tokens', value: triggerThreshold },
    clear_at_least: {
      type: 'input_tokens',
      value: triggerThreshold - keepTarget,
    },
    clear_tool_inputs: TOOLS_CLEARABLE_RESULTS,
  }
  strategies.push(strategy)
}

TOOLS_CLEARABLE_RESULTS（第 19-26 行）包含那些输出量大但可丢弃的工具：Shell 命令、Glob、Grep、FileRead、WebFetch、WebSearch。这些工具的结果通常是搜索输出或文件内容——模型已经处理过了，清除它们不影响后续推理。

模式二：清除工具使用（exclude_tools）

// apiMicrocompact.ts:128-149
if (useClearToolUses) {
  const strategy: ContextEditStrategy = {
    type: 'clear_tool_uses_20250919',
    trigger: { type: 'input_tokens', value: triggerThreshold },
    clear_at_least: {
      type: 'input_tokens',
      value: triggerThreshold - keepTarget,
    },
    exclude_tools: TOOLS_CLEARABLE_USES,
  }
  strategies.push(strategy)
}

TOOLS_CLEARABLE_USES（第 28-32 行）包含 FileEdit、FileWrite 和 NotebookEdit——这些工具的输入（即模型发送的编辑指令）通常比输出更大。exclude_tools 的语义是“清除除这些工具外的所有工具使用“，这让 API 侧可以更激进地清理。

两种模式的默认参数相同：triggerThreshold = 180,000（约等于自动压缩的警告阈值），keepTarget = 40,000（保留最后 40K tokens），clear_at_least = triggerThreshold - keepTarget = 140,000（至少释放 140K tokens）。这些值可通过 API_MAX_INPUT_TOKENS 和 API_TARGET_INPUT_TOKENS 环境变量覆盖。

11.4 可压缩工具集清单

三种微压缩机制各自定义了不同的可压缩工具集。理解这些差异对于预测哪些工具结果会被清除至关重要。

11.4.1 COMPACTABLE_TOOLS（时间触发 + 缓存微压缩共用）

// microCompact.ts:41-50
const COMPACTABLE_TOOLS = new Set<string>([
  FILE_READ_TOOL_NAME,      // Read
  ...SHELL_TOOL_NAMES,       // Bash (多个 shell 变体)
  GREP_TOOL_NAME,            // Grep
  GLOB_TOOL_NAME,            // Glob
  WEB_SEARCH_TOOL_NAME,      // WebSearch
  WEB_FETCH_TOOL_NAME,       // WebFetch
  FILE_EDIT_TOOL_NAME,       // Edit
  FILE_WRITE_TOOL_NAME,      // Write
])

11.4.2 TOOLS_CLEARABLE_RESULTS（API clear_tool_inputs）

// apiMicrocompact.ts:19-26
const TOOLS_CLEARABLE_RESULTS = [
  ...SHELL_TOOL_NAMES,
  GLOB_TOOL_NAME,
  GREP_TOOL_NAME,
  FILE_READ_TOOL_NAME,
  WEB_FETCH_TOOL_NAME,
  WEB_SEARCH_TOOL_NAME,
]

11.4.3 TOOLS_CLEARABLE_USES（API exclude_tools）

// apiMicrocompact.ts:28-32
const TOOLS_CLEARABLE_USES = [
  FILE_EDIT_TOOL_NAME,       // Edit
  FILE_WRITE_TOOL_NAME,      // Write
  NOTEBOOK_EDIT_TOOL_NAME,   // NotebookEdit
]

关键差异：

NotebookEdit 只出现在 API 的 TOOLS_CLEARABLE_USES 中——客户端微压缩不处理它。FileEdit 和 FileWrite 在客户端清除的是结果（tool_result），在 API 模式下则从 clear_tool_inputs 中排除、改为在 exclude_tools 中处理。这种分层设计让客户端和服务端各自处理最适合的部分。

11.5 缓存中断检测的协调

11.5.1 问题：微压缩会触发误报

promptCacheBreakDetection.ts 模块持续监控 API 响应中的 cache_read_tokens。当该值相比上次请求下降超过 5% 且绝对值超过 2,000 tokens 时，它会报告一次“缓存中断“（cache break）——这通常意味着某些变更（系统提示词修改、工具列表变化）导致缓存前缀失效。

但微压缩故意减少了缓存内容。如果不做协调，每次微压缩都会触发一次误报。Claude Code 通过两个通知函数解决这个问题：

11.5.2 notifyCacheDeletion()

// promptCacheBreakDetection.ts:673-682
      // export function notifyCacheDeletion(
  querySource: QuerySource,
  agentId?: AgentId,
): void {
  const key = getTrackingKey(querySource, agentId)
  const state = key ? previousStateBySource.get(key) : undefined
  if (state) {
    state.cacheDeletionsPending = true
  }
}

调用时机：缓存微压缩发送 cache_edits 后（microCompact.ts:366），以及时间触发修改消息内容后（microCompact.ts:526）。

效果：设置 cacheDeletionsPending = true。当下一次 API 响应到来时，checkResponseForCacheBreak()（第 472-481 行）看到此标志，直接跳过中断检测：

// promptCacheBreakDetection.ts:472-481
if (state.cacheDeletionsPending) {
  state.cacheDeletionsPending = false
  logForDebugging(
    `[PROMPT CACHE] cache deletion applied, cache read: ${prevCacheRead}
     → ${cacheReadTokens} (expected drop)`,
  )
  state.pendingChanges = null
  return
}

11.5.3 notifyCompaction()

// promptCacheBreakDetection.ts:689-698
      // export function notifyCompaction(
  querySource: QuerySource,
  agentId?: AgentId,
): void {
  const key = getTrackingKey(querySource, agentId)
  const state = key ? previousStateBySource.get(key) : undefined
  if (state) {
    state.prevCacheReadTokens = null
  }
}

调用时机：完整压缩（compact.ts:699）和自动压缩（autoCompact.ts:303）完成后。

效果：将 prevCacheReadTokens 重置为 null，这意味着下一次 API 响应时没有“上一次的值“可以比较——检测器会将其视为“第一次调用“，不报告中断。

两个函数的区别：

11.6 子代理隔离

微压缩系统必须处理的一个重要场景是子代理（sub-agent）。Claude Code 的主线程可以 fork 出多个子代理（session_memory、prompt_suggestion 等），每个子代理有独立的对话历史。

cachedMicrocompactPath 只对主线程执行（microCompact.ts:275-285）：

// microCompact.ts:275-285
if (feature('CACHED_MICROCOMPACT')) {
  const mod = await getCachedMCModule()
  const model = toolUseContext?.options.mainLoopModel ?? getMainLoopModel()
  if (
    mod.isCachedMicrocompactEnabled() &&
    mod.isModelSupportedForCacheEditing(model) &&
    isMainThreadSource(querySource)
  ) {
    return await cachedMicrocompactPath(messages, querySource)
  }
}

源码注释（第 272-276 行）解释了原因：“Only run cached MC for the main thread to prevent forked agents from registering their tool_results in the global cachedMCState, which would cause the main thread to try deleting tools that don’t exist in its own conversation.”

cachedMCState 是一个模块级全局变量。如果子代理注册了自己的工具 ID，主线程在下次执行时会尝试删除这些 ID——但它们不存在于主线程的消息中，导致无效的 cache_edits 指令。通过 isMainThreadSource(querySource) 守卫，子代理被完全排除在缓存微压缩之外。

isMainThreadSource() 的实现（第 249-251 行）使用前缀匹配而非精确匹配：

// microCompact.ts:249-251
      // function isMainThreadSource(querySource: QuerySource | undefined): boolean {
  return !querySource || querySource.startsWith('repl_main_thread')
}

这是因为 promptCategory.ts 会将 querySource 设置为 'repl_main_thread:outputStyle:<style>'——如果使用严格的 === 'repl_main_thread' 检查，使用非默认输出样式的用户会被静默排除在缓存微压缩之外。源码注释（第 246-248 行）将旧的精确匹配标注为“latent bug“。

11.7 用户能做什么

理解微压缩的三种机制后，你可以采取以下策略来优化日常使用体验：

11.7.1 理解“工具结果消失“的原因

当你发现模型在对话中后期“忘记“了之前某次 grep 或 cat 的结果，这很可能不是模型的幻觉，而是微压缩主动清除了旧的工具结果。被清除的工具结果会被替换为 [Old tool result content cleared] 占位文本。如果你需要模型重新参考某个搜索结果，直接要求它重新执行搜索即可——这比试图让模型“回忆“已被清除的内容更可靠。

11.7.2 长时间离开后的预期管理

如果你离开超过 1 小时再回来继续对话，基于时间的微压缩可能已经清除了大部分旧工具结果（只保留最近 5 个）。这是设计如此——因为服务端缓存已经过期，清除旧内容可以显著减少下一次 API 调用的 cache creation 成本。回来后，让模型重新读取关键文件是正常且高效的操作。

11.7.3 利用 CLAUDE.md 保留关键上下文

微压缩只清除工具调用的结果，不影响系统提示词中注入的 CLAUDE.md 内容。如果某些信息（如项目约定、架构决策、关键文件路径）需要在整个会话中持续生效，将它们写入 CLAUDE.md 是最可靠的方式——它们不受任何压缩或微压缩机制的影响。

11.7.4 并行工具调用的成本意识

当模型同时发起多个搜索或读取操作时，这些结果的聚合大小受 200K 字符的消息级预算限制。如果你观察到某些并行工具的结果被持久化到磁盘（模型会提示“Output too large, saved to file“），这是预算机制在防止上下文膨胀。你可以通过更精确的搜索条件来减少单次工具输出的大小。

11.7.5 不可压缩工具的认知

并非所有工具结果都会被微压缩清除。FileEdit、FileWrite 等写入类工具的结果在客户端微压缩中是可清除的，但像 ToolSearch、SendMessage 等工具不在可压缩集合中。了解哪些工具结果会被清除（参见 11.4 节的对比表），有助于你理解模型在长会话中的行为变化。

11.8 设计模式总结

微压缩系统展现了几个值得学习的工程模式：

分层降级：三种机制形成层次——API Context Management 作为声明式基线始终存在；缓存微压缩在支持 cache_edits 的环境中提供精准手术；时间触发作为缓存失效后的兜底。每一层都有明确的前提条件和退化路径。

副作用协调：微压缩不是孤立操作——它必须通知缓存中断检测器（防误报）、重置相关状态（防脏数据）、抑制用户警告（防困惑）。这三个副作用通过显式的函数调用（notifyCacheDeletion、resetMicrocompactState、suppressCompactWarning）而非事件系统协调，保持了因果链的可追踪性。

单次消费语义：consumePendingCacheEdits() 返回数据后立即清空——这防止了在 API 重试场景下的重复消费。这种模式在需要跨模块传递一次性状态时非常实用。

不可变消息修改：时间触发路径使用 map + 展开运算符创建新的消息数组，而不是原地修改。这确保了如果微压缩逻辑有 bug，原始消息不会被污染。缓存微压缩更进一步——它完全不修改本地消息，所有修改都在服务端完成。

循环依赖规避：notifyCacheDeletion 被复用来替代 notifyCompaction，仅仅是因为后者的 import 会触发循环依赖检测。这种务实的妥协在大型代码库中很常见——完美的模块边界让位于构建系统的约束。源码注释坦诚记录了这个取舍，而不是试图隐藏它。

第12章：Token 预算策略

为什么这很重要

在第9-11章中，我们分析了 Claude Code 在上下文窗口“满“了之后如何压缩和修剪。但还有一个更基本的问题：在内容进入上下文窗口之前，如何控制它的大小？

一次 grep 返回 80KB 的搜索结果，一次 cat 读取 200KB 的日志文件，五个并行工具调用每个返回 50KB——这些都是真实场景。如果不加控制，单个工具结果就可能吃掉上下文窗口的四分之一，而一组并行工具调用则可能直接将上下文推到需要压缩的临界点。

Token 预算策略是 Claude Code 上下文管理的“入口闸门“。它在三个层级运作：

1. 单工具结果级别：超过阈值的结果持久化到磁盘，只向模型展示预览
2. 单消息级别：一轮并行工具调用的结果总量不超过 200K 字符
3. Token 计数级别：通过规范 API 或粗略估算追踪上下文窗口使用量

本章将深入这三个层级的实现，揭示其中的工程权衡——特别是并行工具调用场景下的 token 计数陷阱。

12.1 工具结果持久化：50K 字符的入口闸门

核心常量

工具结果的大小控制围绕两个核心常量展开，定义在 constants/toolLimits.ts 中：

// constants/toolLimits.ts:13
export const DEFAULT_MAX_RESULT_SIZE_CHARS = 50_000

// constants/toolLimits.ts:49
export const MAX_TOOL_RESULTS_PER_MESSAGE_CHARS = 200_000

第一个常量是单工具结果的全局上限——当一个工具的输出超过 50,000 个字符时，完整内容被写入磁盘文件，模型只收到一个包含文件路径和前 2,000 字节预览的替代消息。第二个常量是单消息内所有工具结果的聚合上限，用于防范并行工具调用的累积效应。

这两个常量之间的关系值得注意：200K / 50K = 4，意味着即使四个工具都各自达到单工具上限，它们在一条消息内仍然安全。但如果五个或更多并行工具同时返回接近上限的结果，就会触发消息级别的预算执行。

持久化阈值的计算

单工具的持久化阈值并非简单等于 50K——它是一个多层决策：

// utils/toolResultStorage.ts:55-78
      // export function getPersistenceThreshold(
  toolName: string,
  declaredMaxResultSizeChars: number,
): number {
  // Infinity = hard opt-out
  if (!Number.isFinite(declaredMaxResultSizeChars)) {
    return declaredMaxResultSizeChars
  }
  const overrides = getFeatureValue_CACHED_MAY_BE_STALE<Record<
    string, number
  > | null>(PERSIST_THRESHOLD_OVERRIDE_FLAG, {})
  const override = overrides?.[toolName]
  if (
    typeof override === 'number' &&
    Number.isFinite(override) &&
    override > 0
  ) {
    return override
  }
  return Math.min(declaredMaxResultSizeChars, DEFAULT_MAX_RESULT_SIZE_CHARS)
}

这个函数的决策逻辑构成一个优先级链：

表 12-1：单工具持久化阈值优先级链

第一个优先级特别有意思：Read 工具将自己的 maxResultSizeChars 设为 Infinity，意味着它永远不会被持久化。源码注释（第59-61行）解释了原因——Read 工具的输出如果被持久化到文件，模型就需要再次调用 Read 去读取那个文件，形成循环。Read 工具通过自己的 maxTokens 参数控制输出大小，不依赖通用的持久化机制。

持久化流程

当工具结果超过阈值时，maybePersistLargeToolResult 函数执行以下流程：

flowchart TD
    A["工具执行完成，产生结果"] --> B{"结果内容为空？"}
    B -->|是| C["注入占位符文本<br />(toolName completed with no output)"]
    B -->|否| D{"包含图片 block？"}
    D -->|是| E["原样返回<br />（图片必须发送给模型）"]
    D -->|否| F{"size ≤ 阈值？"}
    F -->|是| G["原样返回"]
    F -->|否| H["persistToolResult()<br />写入磁盘文件，生成 2KB 预览"]
    H --> I["buildLargeToolResultMessage()<br />构建替代消息：<br />persisted-output 文件路径 + 预览"]

图 12-1：工具结果持久化决策流程

有两个值得关注的实现细节：

空结果的特殊处理（第280-295行）：空的 tool_result 内容会导致某些模型（注释中提到 “capybara”）误判为对话轮次边界，从而错误地结束输出。这是因为服务端渲染器在 tool_result 之后不插入 \n\nAssistant: 标记，空内容会匹配到 \n\nHuman: 的停止序列模式。解决方案是注入一个简短的占位字符串 (toolName completed with no output)。

文件写入的幂等性（第161-172行）：persistToolResult 使用 flag: 'wx' 写入文件，这意味着如果文件已存在则抛出 EEXIST 错误——函数捕获并忽略这个错误。这个设计是为了应对 microcompact 重放原始消息时的重复持久化问题：tool_use_id 在每次调用中是唯一的，相同 ID 的内容是确定性的，所以跳过已存在的文件是安全的。

持久化后的消息格式

当结果被持久化后，模型实际看到的消息如下：

<persisted-output>
Output too large (82.3 KB). Full output saved to:
  /path/to/session/tool-results/toolu_01XYZ.txt

Preview (first 2.0 KB):
[前 2000 字节的内容，在换行符处截断]
...
</persisted-output>

预览的生成逻辑（第339-356行）会尽量在换行符处截断，避免切断一行的中间位置。如果最后一个换行符的位置在限制值的 50% 之前（意味着要么只有一行，要么行非常长），则回退到精确的字节限制。

12.2 单消息预算：200K 聚合上限

为什么需要消息级别的预算

单工具的 50K 上限不足以应对并行工具调用的场景。考虑这种情况：模型同时发起 10 个 Grep 调用搜索不同的关键词，每个返回 40K 字符——单独看都在 50K 阈值以下，但合计 400K 字符将在一条 user 消息中发送给 API。这会立即消耗大量上下文窗口，可能触发不必要的压缩。

MAX_TOOL_RESULTS_PER_MESSAGE_CHARS = 200_000（第49行）就是为这个场景设计的聚合预算。注释（第40-48行）明确说明了核心设计原则：消息之间独立评估——一轮对话中 150K 的结果和另一轮中 150K 的结果各自都在预算内，不会互相影响。

消息分组的复杂性

并行工具调用在 Claude Code 内部的消息表示并不简单。当模型发起多个并行工具调用时，流式处理代码为每个 content_block_stop 事件产生一个独立的 AssistantMessage 记录，然后每个 tool_result 作为独立的 user 消息紧随其后。所以内部消息数组看起来像：

[..., assistant(id=A), user(result_1), assistant(id=A), user(result_2), ...]

注意多个 assistant 记录共享同一个 message.id。但在发送给 API 之前，normalizeMessagesForAPI 会将连续的 user 消息合并为一条。消息级别的预算必须按照 API 看到的分组方式工作，而不是内部的分散表示。

collectCandidatesByMessage 函数（第600-638行）实现了这个分组逻辑。它将消息按“assistant 消息边界“分组——只有未曾见过的 assistant message.id 才创建新的分组边界：

// utils/toolResultStorage.ts:624-635
const seenAsstIds = new Set<string>()
for (const message of messages) {
  if (message.type === 'user') {
    current.push(...collectCandidatesFromMessage(message))
  } else if (message.type === 'assistant') {
    if (!seenAsstIds.has(message.message.id)) {
      flush()
      seenAsstIds.add(message.message.id)
    }
  }
}

这里有一个微妙的边界情况：当并行工具执行中发生中止（abort），agent_progress 消息可能插入到 tool_result 消息之间。如果在 progress 消息处创建分组边界，那些 tool_result 就会被拆分到不同的低于预算的小组中，绕过了聚合预算检查——但 normalizeMessagesForAPI 会在线路上把它们合并为一条超预算的大消息。代码通过只在 assistant 消息处分组（忽略 progress、attachment 等类型）来避免这个问题。

预算执行与状态冻结

消息级别预算的核心机制是 enforceToolResultBudget 函数（第769-908行）。它的设计围绕一个关键约束：prompt cache 稳定性。一旦模型看到了某个工具结果（无论是完整内容还是替代预览），这个决策在后续所有 API 调用中必须保持一致。否则，前缀变化会导致 prompt cache 失效。

这引出了“三态分区“机制：

flowchart LR
    subgraph CRS["ContentReplacementState"]
        direction TB
        S["seenIds: Set &lt; string &gt;<br />replacements: Map &lt; string, string &gt;"]
        subgraph States["三种状态"]
            direction LR
            MA["mustReapply<br />在 seenIds 且有替换内容<br />→ 重新应用缓存的替换"]
            FR["frozen<br />在 seenIds 但无替换<br />→ 不可变更，原样保留"]
            FH["fresh<br />不在 seenIds 中的新结果<br />→ 可被选中进行替换"]
        S --> States

图 12-2：工具结果三态分区与状态转换

每轮 API 调用前的执行流程：

1. 对每个消息分组，将候选的 tool_result 按上述三态分区
2. mustReapply：从 Map 中取出之前缓存的替代字符串，原样重新应用——零 I/O，字节级一致
3. frozen：之前看过但没有被替换的结果——不可再替换（否则会破坏 prompt cache 前缀）
4. fresh：本轮新增的结果——检查聚合预算，超预算时按大小降序选择最大的结果进行持久化

选择哪些 fresh 结果进行替换的逻辑在 selectFreshToReplace（第675-692行）中：按大小降序排列，逐一选中直到剩余总量（frozen + 未选中的 fresh）降到预算限制以下。如果仅 frozen 结果就超过了预算，则接受超额——microcompact 最终会清理它们。

状态标记的时序

代码中有一个精心设计的时序约束（第833-842行）。未被选中持久化的候选者立即同步标记为 seen（加入 seenIds），而被选中持久化的候选者则在 await persistToolResult() 完成后才标记——这保证了 seenIds.has(id) 和 replacements.has(id) 的一致性。注释解释了原因：如果一个 ID 出现在 seenIds 中但不在 replacements 中，它会被分类为 frozen（不可替换），导致完整内容被发送；而同时主线程可能发送的是预览——两边不一致会导致 prompt cache 失效。

12.3 Token 计数：规范 vs 粗略估算

两种计数机制

Claude Code 维护两套 token 计数机制，适用于不同场景：

表 12-2：Token 计数两种机制对比

规范计数：从 API Usage 到上下文大小

API 响应的 usage 对象包含多个字段，getTokenCountFromUsage 函数（utils/tokens.ts:46-53）将它们组合为完整的上下文窗口大小：

// utils/tokens.ts:46-53
      // export function getTokenCountFromUsage(usage: Usage): number {
  return (
    usage.input_tokens +
    (usage.cache_creation_input_tokens ?? 0) +
    (usage.cache_read_input_tokens ?? 0) +
    usage.output_tokens
  )
}

这个计算包含了四个组成部分：input_tokens（本次请求的非缓存输入）、cache_creation_input_tokens（本次新写入缓存的 token）、cache_read_input_tokens（从缓存读取的 token）和 output_tokens（模型生成的输出）。注意缓存相关的字段是可选的（?? 0），因为不是所有 API 提供方都返回这些字段。

粗略估算：4 字节/token 规则

当 API usage 不可用时——例如在两次 API 调用之间新增了消息——Claude Code 使用字符长度除以经验系数来估算 token 数。核心估算函数在 services/tokenEstimation.ts:203-208：

// services/tokenEstimation.ts:203-208
      // export function roughTokenCountEstimation(
  content: string,
  bytesPerToken: number = 4,
): number {
  return Math.round(content.length / bytesPerToken)
}

默认的 4 字节/token 是一个保守估算。Claude 的 tokenizer 对英文文本的实际比率约在 3.5-4.5 之间，取 4 作为经验中位数。但不同内容类型的实际比率差异很大：

表 12-3：文件类型感知的 Token 估算规则汇总

JSON 文件使用 2 而非 4 的原因在注释（第213-215行）中解释得很清楚：密集的 JSON 包含大量单字符 token（{、}、:、,、"），这使得每个 token 平均只对应约 2 个字节。如果仍然用 4 来估算，一个 100KB 的 JSON 文件会被估算为 25K token，而实际可能接近 50K——这个低估可能导致超大的工具结果未被持久化，悄悄进入上下文。

bytesPerTokenForFileType（第215-224行）根据文件扩展名返回不同的系数：

// services/tokenEstimation.ts:215-224
      // export function bytesPerTokenForFileType(fileExtension: string): number {
  switch (fileExtension) {
    case 'json':
    case 'jsonl':
    case 'jsonc':
      return 2
    default:
      return 4
  }
}

图片和文档的固定估算

图片和 PDF 文档是特殊情况。API 对图片的实际 token 计费是 (width × height) / 750，图片会被缩放到最大 2000×2000 像素（约 5,333 token）。但在粗略估算中，Claude Code 统一使用 2,000 token 的固定值（第400-412行）。

这里有一个重要的工程考量：如果图片或 PDF 的 source.data（base64 编码）被送入通用的 JSON 序列化路径，一个 1MB 的 PDF 会产生约 1.33M 的 base64 字符，按 4 字节/token 估算就是约 325K token——远高于 API 实际收费的 ~2,000 token。因此代码在通用估算之前显式检查 block.type === 'image' || block.type === 'document' 并提前返回固定值，避免灾难性的高估。

12.4 并行工具调用的 Token 计数陷阱

消息交错问题

并行工具调用引入了一个微妙但严重的 token 计数问题。tokenCountWithEstimation——Claude Code 中用于阈值判断的规范函数——的实现（utils/tokens.ts:226-261）包含了对这个问题的详细分析。

问题的根源在于消息数组的交错结构。当模型发起两个并行工具调用时，内部消息数组呈现如下形式：

索引:  ... i-3       i-2         i-1          i
消息:  ... asst(A)   user(tr_1)  asst(A)      user(tr_2)
            ↑ usage              ↑ 相同 usage

两个 assistant 记录共享同一个 message.id 和相同的 usage（因为它们来自同一个 API 响应的不同 content block）。如果简单地从后往前找到第一个有 usage 的 assistant 消息（索引 i-1），然后估算它之后的消息（只有索引 i 处的 user(tr_2)），就会遗漏索引 i-2 处的 user(tr_1)。

但在下一次 API 请求中，user(tr_1) 和 user(tr_2) 都会出现在输入中。这意味着 tokenCountWithEstimation 会系统性地低估上下文大小。

             实际上下文中包含的内容
    ┌──────────────────────────────────────┐
    │ asst(A) user(tr_1) asst(A) user(tr_2)│
    └──────────────────────────────────────┘
              ↑                   ↑
              遗漏!                只估算了这个

             修正后的估算范围
    ┌──────────────────────────────────────┐
    │ asst(A) user(tr_1) asst(A) user(tr_2)│
    └──────────────────────────────────────┘
    ↑ 回溯到首个同 ID 的 assistant          ↑
    从这里开始估算所有后续消息

图 12-3：并行工具调用的 token 计数回溯修正

同 ID 回溯修正

tokenCountWithEstimation 的解决方案是在找到最后一个有 usage 的 assistant 记录后，向前回溯到共享同一 message.id 的第一个 assistant 记录：

// utils/tokens.ts:235-250
const responseId = getAssistantMessageId(message)
if (responseId) {
  let j = i - 1
  while (j >= 0) {
    const prior = messages[j]
    const priorId = prior ? getAssistantMessageId(prior) : undefined
    if (priorId === responseId) {
      i = j  // 锚定到更早的同 ID 记录
    } else if (priorId !== undefined) {
      break  // 遇到不同 API 响应，停止回溯
    }
    j--
  }
}

注意回溯逻辑中的三种情况：

1. priorId === responseId：同一 API 响应的更早分片——将锚点移到这里
2. priorId !== undefined（且不同 ID）：遇到了另一个 API 响应——停止回溯
3. priorId === undefined：这是 user/tool_result/attachment 消息——可能是分片之间交错的工具结果，继续回溯

回溯完成后，从锚点之后的所有消息（包括所有交错的 tool_result）都会被纳入粗略估算：

// utils/tokens.ts:253-256
return (
  getTokenCountFromUsage(usage) +
  roughTokenCountEstimationForMessages(messages.slice(i + 1))
)

最终的上下文大小 = 最后一次 API 响应的精确 usage + 此后所有新增消息的粗略估算。这种“精确基线 + 增量估算“的混合方法平衡了精度和性能。

何时不应使用哪个函数

源码中的注释（第118-121行，第207-212行）反复强调了函数选择的重要性：

• tokenCountWithEstimation：规范函数，用于所有阈值比较（自动压缩触发、会话记忆初始化等）
• tokenCountFromLastAPIResponse：只返回最后一次 API 调用的精确 token 总量，不包含新增消息的估算——不适合阈值判断
• messageTokenCountFromLastAPIResponse：只返回 output_tokens——仅用于衡量模型单次生成了多少 token，不反映上下文窗口的使用量

误用这些函数的后果是实际的：如果用 messageTokenCountFromLastAPIResponse 来判断是否需要压缩，返回值可能只有几千（一次助手回复的输出），而实际上下文已经超过 180K——压缩永远不会触发，最终导致 API 调用因超过窗口限制而失败。

12.5 辅助计数：API token 计数与 Haiku 回退

countTokens API

除了粗略估算，Claude Code 还可以通过 API 获取精确的 token 计数。countMessagesTokensWithAPI（services/tokenEstimation.ts:140-201）调用 anthropic.beta.messages.countTokens 端点，传入完整的消息列表和工具定义，获取精确的 input_tokens 值。

这个 API 用于需要精确计数的场景（如工具定义的 token 开销评估），但有延迟开销——它需要一次额外的 HTTP 往返。因此日常的阈值判断使用 tokenCountWithEstimation 的混合方法，只在特定场景下使用 API 计数。

Haiku 回退方案

当 countTokens API 不可用（例如某些 Bedrock 配置）时，countTokensViaHaikuFallback（第251-325行）使用一种巧妙的替代方案：向 Haiku（小模型）发送一个 max_tokens: 1 的请求，利用返回的 usage 获取精确的输入 token 数。代价是消耗一次小模型调用的 API 费用，但获得了精确度。

函数在选择回退模型时需要考虑多个平台约束：

• Vertex 全局区域：Haiku 不可用，回退到 Sonnet
• Bedrock + thinking blocks：Haiku 3.5 不支持 thinking，回退到 Sonnet
• 其他情况：使用 Haiku（成本最低）

12.6 端到端的 Token 预算体系

将上述所有机制组合起来，Claude Code 的 token 预算形成一个多层防御体系：

flowchart TB
    subgraph L1["第1层：单工具结果持久化"]
        L1D["工具执行 → 结果 > 阈值？ → 持久化到磁盘 + 2KB 预览<br />阈值 = min(工具声明值, 50K) 或 GrowthBook 覆盖<br />特例：Read (Infinity), 图片 (跳过)"]
    subgraph L2["第2层：单消息聚合预算"]
        L2D["API 调用前 → tool_result 总量 > 200K？<br />→ 按大小降序持久化 fresh 结果，直到总量 ≤ 200K<br />→ 状态冻结：seen 结果命运永不改变（prompt cache 稳定性）"]
    subgraph L3["第3层：上下文窗口追踪"]
        L3D["tokenCountWithEstimation() = 精确 usage + 增量粗略估算<br />→ 驱动自动压缩、微压缩等决策<br />→ 并行工具调用：同 ID 回溯修正，避免系统性低估"]
    subgraph L4["第4层：自动压缩 / 微压缩（详见第9-11章）"]
        L4D["上下文接近窗口限制 → 压缩历史消息 / 清理旧工具结果"]
    L1 -->|"未拦截则进入"| L2
    L2 -->|"未拦截则进入"| L3
    L3 -->|"超过阈值触发"| L4

图 12-4：Token 预算的四层防御体系

每一层都有明确的职责边界和失败后的降级路径：

• 第1层失败（持久化磁盘出错）→ 原样返回完整结果，第2层和第4层兜底
• 第2层的 frozen 结果无法替换 → 接受超额，由第4层的 microcompact 最终清理
• 第3层的粗略估算不准确 → 可能导致压缩触发过早或过晚，但不会导致数据丢失

GrowthBook 动态调参

两个核心阈值都可以通过 GrowthBook feature flag 在运行时调整，无需发布新版本：

• tengu_satin_quoll：单工具持久化阈值的 per-tool 覆盖 map
• tengu_hawthorn_window：单消息聚合预算的全局覆盖值

getPerMessageBudgetLimit（第421-434行）展示了覆盖逻辑的防御性编码——对 GrowthBook 返回的值进行 typeof、isFinite、> 0 三重检查，因为缓存层可能泄漏 null、NaN 或字符串类型的值。

12.7 用户能做什么

12.7.1 控制工具输出大小

当你的 grep 或 bash 命令返回大量输出时（超过 50K 字符），结果会被持久化到磁盘，模型只能看到前 2KB 的预览。为了避免这种信息损失，尽量使用更精确的搜索条件——比如用 grep -l（只列文件名）替代全文搜索，或者用 head -n 100 限制命令输出。这样模型能看到完整结果，而不是被截断的预览。

12.7.2 注意并行工具调用的累积效应

当模型同时发起多个搜索时，所有结果的聚合大小受 200K 字符限制。如果你要求模型“同时搜索这 10 个关键词“，部分结果可能因超出预算而被持久化。考虑将大规模搜索拆分为几轮较小的搜索，或者让模型逐步搜索以保持每轮结果在预算内。

12.7.3 JSON 文件的特殊考量

JSON 文件的 token 密度是普通代码的 2 倍（每 token 约 2 字节 vs 4 字节）。这意味着一个 100KB 的 JSON 文件实际消耗约 50K token，而同等大小的 TypeScript 文件只消耗约 25K token。当你让模型读取大型 JSON 配置或数据文件时，要意识到它们对上下文窗口的压力更大。

12.7.4 利用 Read 工具的特殊地位

Read 工具的输出永远不会被持久化到磁盘——它通过自己的 maxTokens 参数控制大小。这意味着通过 Read 读取的文件内容始终直接呈现给模型，不会被截断为 2KB 预览。如果你需要模型完整看到某个文件的内容，使用 Read 比 cat 命令更可靠。

12.7.5 关注 token 计数的粗略估算偏差

Claude Code 在两次 API 调用之间使用粗略估算（字符数 / 4）来追踪上下文大小，偏差可达 ±50%。这意味着自动压缩的触发时机可能早于或晚于预期。如果你观察到压缩在意想不到的时机发生，这通常是估算偏差导致的正常行为，而非 bug。

12.8 设计洞察

保守估算 vs 激进估算

Token 预算体系中反复出现的设计取舍是：宁可高估 token 数量，也不要低估。

• JSON 使用 2 字节/token 而非 4，是因为低估会导致超大结果未被持久化
• 图片使用固定 2,000 token 而非 base64 长度估算，是因为后者会导致灾难性高估（上下文看起来“满“了但其实不满）
• 并行工具调用的回溯修正，是因为遗漏 tool_result 会导致系统性低估

这些选择体现了一个原则：token 预算是一个安全机制而非优化机制。高估的代价是提前触发压缩（轻微的性能损失），低估的代价是上下文窗口溢出（API 调用失败）。

Prompt Cache 对预算设计的深层影响

消息级别预算的大部分复杂性——三态分区、状态冻结、字节级一致的重新应用——都源于一个外部约束：prompt cache 要求前缀稳定。如果没有 prompt cache，每轮 API 调用前可以自由地重新评估所有工具结果是否需要持久化。但 prompt cache 的存在意味着一旦模型“看到了“某个工具结果的完整内容，后续调用必须继续发送完整内容（否则前缀变化导致缓存失效）。

这个约束将一个本可以是无状态的函数（“检查大小，超标则替换”）变成了一个有状态的状态机（ContentReplacementState），而且状态必须跨越会话恢复（resume）存活——这就是 ContentReplacementRecord 被持久化到 transcript 的原因。

这是一个典型的例子：在 AI Agent 系统中，性能优化（prompt cache）会反向约束功能设计（预算执行），形成意想不到的架构耦合。

第13章：缓存架构与断点设计

为什么这很重要

在第12章中，我们讨论了 Token 预算策略如何控制进入上下文窗口的内容大小。但还有一个更隐蔽的成本问题：即使上下文窗口内的内容完全相同，每次 API 调用仍然需要为系统提示词和工具定义付费。

对于一个典型的 Claude Code 会话，系统提示词约 11,000 tokens，40+ 个工具的 Schema 定义又贡献约 20,000 tokens——仅这些“固定开销“每次调用就消耗 30,000+ tokens。在一个 50 轮的会话中，这意味着 1,500,000 tokens 被重复处理。按 Anthropic 的定价，这是一笔不可忽视的成本。

Anthropic 的提示词缓存（Prompt Caching）机制正是为解决这个问题而生：如果 API 请求的前缀与之前的请求匹配，服务端可以直接复用已缓存的 KV 状态，将缓存命中部分的费用降低 90%。但缓存命中有严格的条件——前缀必须逐字节匹配。一个字符的变化就会导致缓存未命中（cache miss），也就是“缓存中断“（cache break）。

Claude Code 围绕这个约束构建了一套精密的缓存架构，包含三级缓存范围、两种 TTL 层级、以及一组防止缓存中断的“锁存“（latching）机制。本章将深入这套架构的设计与实现。

13.1 Anthropic API 提示词缓存基础

前缀匹配模型

Anthropic 的提示词缓存基于前缀匹配原则。服务端将 API 请求视为一个序列化的字节流，从头开始逐字节比较。一旦发现不匹配，缓存就在该位置“断裂“——之前的部分可以复用，之后的部分需要重新计算。

这意味着缓存的有效性完全取决于请求前缀的稳定性。API 请求的序列化顺序大致为：

[系统提示词] → [工具定义] → [消息历史]

系统提示词和工具定义位于序列的前端，它们的任何变化都会使整个缓存失效。消息历史追加在末尾，新消息只需为增量部分付费。

cache_control 标记

要启用缓存，需要在 API 请求的内容块上添加 cache_control 标记：

// cache_control 的基本形式
{
  type: 'ephemeral'
}

// 扩展形式（1P 专属）
{
  type: 'ephemeral',
  scope: 'global' | 'org',   // 缓存范围
  ttl: '5m' | '1h'           // 缓存生存时间
}

type: 'ephemeral' 是唯一支持的缓存类型，表示这是一个临时缓存断点。Claude Code 在 utils/api.ts（第68-78行）中定义了扩展的工具 Schema 类型，包含完整的 cache_control 选项：

// utils/api.ts:68-78
type BetaToolWithExtras = BetaTool & {
  strict?: boolean
  defer_loading?: boolean
  cache_control?: {
    type: 'ephemeral'
    scope?: 'global' | 'org'
    ttl?: '5m' | '1h'
  }
  eager_input_streaming?: boolean
}

缓存断点的放置

Claude Code 在请求中精心放置缓存断点，通过 getCacheControl() 函数（services/api/claude.ts，第358-374行）生成统一的 cache_control 对象：

// services/api/claude.ts:358-374
      // export function getCacheControl({
  scope,
  querySource,
}: {
  scope?: CacheScope
  querySource?: QuerySource
} = {}): {
  type: 'ephemeral'
  ttl?: '1h'
  scope?: CacheScope
} {
  return {
    type: 'ephemeral',
    ...(should1hCacheTTL(querySource) && { ttl: '1h' }),
    ...(scope === 'global' && { scope }),
  }
}

这个函数看似简单，但它的每个条件分支都蕴含着深思熟虑的缓存策略。

13.2 三级缓存范围

Claude Code 使用三种缓存范围（cache scope），每种范围对应不同的复用粒度。这些范围通过 splitSysPromptPrefix() 函数（utils/api.ts，第321-435行）分配给系统提示词的不同部分。

范围定义

表 13-1：三级缓存范围对比

全局缓存范围（global）

全局缓存是最激进的优化——标记为 global 的内容可以在所有 Claude Code 用户之间共享 KV 缓存。这意味着当用户 A 发起一个请求，缓存了系统提示词的静态部分后，用户 B 的下一个请求可以直接命中这个缓存。

全局缓存的适用条件非常严格：内容必须是完全不变的，不能包含任何用户特定、组织特定、甚至时间特定的信息。Claude Code 通过一个“动态边界标记“（SYSTEM_PROMPT_DYNAMIC_BOUNDARY）将系统提示词分为静态和动态两部分：

// utils/api.ts:362-404（简化）
if (useGlobalCacheFeature) {
  const boundaryIndex = systemPrompt.findIndex(
    s => s === SYSTEM_PROMPT_DYNAMIC_BOUNDARY,
  )
  if (boundaryIndex !== -1) {
    // 边界之前的内容 → cacheScope: 'global'
    // 边界之后的内容 → cacheScope: null
    for (let i = 0; i < systemPrompt.length; i++) {
      if (i < boundaryIndex) {
        staticBlocks.push(block)
      } else {
        dynamicBlocks.push(block)
      }
    }
    // ...
    if (staticJoined)
      result.push({ text: staticJoined, cacheScope: 'global' })
    if (dynamicJoined)
      result.push({ text: dynamicJoined, cacheScope: null })
  }
}

注意边界之后的动态内容被标记为 cacheScope: null——它甚至不使用 org 级别的缓存，因为动态内容的变化频率太高，缓存命中率极低，标记缓存断点反而增加了 API 请求的复杂度。

组织缓存范围（org）

当全局缓存不可用时（例如没有启用全局缓存功能，或内容包含组织特定信息），Claude Code 回退到 org 级别：

// utils/api.ts:411-435（默认模式）
let attributionHeader: string | undefined
let systemPromptPrefix: string | undefined
const rest: string[] = []

for (const block of systemPrompt) {
  if (block.startsWith('x-anthropic-billing-header')) {
    attributionHeader = block
  } else if (CLI_SYSPROMPT_PREFIXES.has(block)) {
    systemPromptPrefix = block
  } else {
    rest.push(block)
  }
}

const result: SystemPromptBlock[] = []
if (attributionHeader)
  result.push({ text: attributionHeader, cacheScope: null })
if (systemPromptPrefix)
  result.push({ text: systemPromptPrefix, cacheScope: 'org' })
const restJoined = rest.join('\n\n')
if (restJoined)
  result.push({ text: restJoined, cacheScope: 'org' })

这里的分块策略揭示了一个重要细节：计费归属头（x-anthropic-billing-header）被标记为 null，不参与缓存。这是因为归属头包含用户身份信息，在 org 级别也不可共享。而 CLI 系统提示词前缀（CLI_SYSPROMPT_PREFIXES）和剩余系统提示词内容都标记为 org，在同一组织内共享。

MCP 工具的特殊处理

当用户配置了 MCP 工具时，全局缓存的策略发生变化。因为 MCP 工具的定义由外部服务器提供，其内容不可预测，将它们纳入全局缓存会降低命中率。Claude Code 通过 skipGlobalCacheForSystemPrompt 标志处理这种情况：

// utils/api.ts:326-360
if (useGlobalCacheFeature && options?.skipGlobalCacheForSystemPrompt) {
  logEvent('tengu_sysprompt_using_tool_based_cache', {
    promptBlockCount: systemPrompt.length,
  })
  // 所有内容降级为 org 范围，跳过边界标记
  // ...
}

这种降级是保守但合理的——与其冒全局缓存被频繁击穿的风险，不如退回到命中率更稳定的 org 级别。

13.3 缓存 TTL 层级

默认 5 分钟 vs 1 小时

Anthropic 的提示词缓存默认 TTL 为 5 分钟。这意味着如果用户在 5 分钟内没有发起新的 API 请求，缓存就会过期。对于活跃的编程会话，5 分钟通常足够。但对于需要频繁思考、查阅文档的场景，5 分钟可能不够。

Claude Code 支持将 TTL 提升到 1 小时，通过 should1hCacheTTL() 函数（services/api/claude.ts，第393-434行）决定是否启用：

// services/api/claude.ts:393-434
      // function should1hCacheTTL(querySource?: QuerySource): boolean {
  // 3P Bedrock 用户通过环境变量 opt-in
  if (
    getAPIProvider() === 'bedrock' &&
    isEnvTruthy(process.env.ENABLE_PROMPT_CACHING_1H_BEDROCK)
  ) {
    return true
  }

  // 锁存资格检查——防止会话中途 overage 翻转改变 TTL
  let userEligible = getPromptCache1hEligible()
  if (userEligible === null) {
    userEligible =
      process.env.USER_TYPE === 'ant' ||
      (isClaudeAISubscriber() && !currentLimits.isUsingOverage)
    setPromptCache1hEligible(userEligible)
  }
  if (!userEligible) return false

  // 缓存 allowlist——同样锁存以保持会话稳定
  let allowlist = getPromptCache1hAllowlist()
  if (allowlist === null) {
    const config = getFeatureValue_CACHED_MAY_BE_STALE(
      'tengu_prompt_cache_1h_config', {}
    )
    allowlist = config.allowlist ?? []
    setPromptCache1hAllowlist(allowlist)
  }

  return (
    querySource !== undefined &&
    allowlist.some(pattern =>
      pattern.endsWith('*')
        ? querySource.startsWith(pattern.slice(0, -1))
        : querySource === pattern,
    )
  )
}

资格检查的锁存机制

should1hCacheTTL() 中最关键的设计是锁存（latching）。函数首次调用时计算用户是否有资格使用 1 小时 TTL，然后将结果存入全局 STATE（bootstrap/state.ts）：

// bootstrap/state.ts:1700-1706
      // export function getPromptCache1hEligible(): boolean | null {
  return STATE.promptCache1hEligible
}

      // export function setPromptCache1hEligible(eligible: boolean | null): void {
  STATE.promptCache1hEligible = eligible
}

为什么需要锁存？考虑以下场景：

1. 会话开始时，用户在订阅配额内（isUsingOverage === false），获得 1 小时 TTL
2. 会话进行到第 30 轮时，用户超出配额（isUsingOverage === true）
3. 如果此时 TTL 从 1 小时降回 5 分钟，cache_control 对象的序列化结果发生变化
4. 这个变化会导致 API 请求的前缀不再匹配——缓存中断

一次 overage 状态翻转导致 ~20,000 tokens 的系统提示词和工具定义缓存全部失效，这显然是不可接受的。锁存机制确保一旦会话开始时确定了 TTL 等级，整个会话期间保持不变。

同样的锁存逻辑也应用于 GrowthBook 的 allowlist 配置——防止 GrowthBook 的磁盘缓存在会话中途更新导致 TTL 行为变化。

TTL 层级决策表

表 13-2：缓存 TTL 决策矩阵

13.4 Beta Header 锁存机制

问题：动态 Header 导致缓存击穿

Anthropic API 的请求中包含一组“beta headers“，标识客户端使用的实验性功能。这些 header 是服务端缓存键的一部分——添加或移除一个 header 就会改变缓存键，导致缓存中断。

Claude Code 有多个功能可以在会话中途动态激活或停用：

• AFK 模式（Auto Mode）：用户离开时自动执行任务
• Fast Mode：使用更快但可能更贵的模型
• 缓存编辑（Cached Microcompact）：在缓存中进行增量编辑

每次这些功能的状态变化，对应的 beta header 就会被添加或移除，触发缓存中断。代码注释（services/api/claude.ts，第1405-1410行）明确描述了这个问题：

// services/api/claude.ts:1405-1410
// Sticky-on latches for dynamic beta headers. Each header, once first
// sent, keeps being sent for the rest of the session so mid-session
// toggles don't change the server-side cache key and bust ~50-70K tokens.
// Latches are cleared on /clear and /compact via clearBetaHeaderLatches().
// Per-call gates (isAgenticQuery, querySource===repl_main_thread) stay
// per-call so non-agentic queries keep their own stable header set.

锁存实现

Claude Code 的解决方案是“sticky-on“锁存——一旦某个 beta header 在会话中被发送过，它将在整个会话剩余时间内持续发送，即使触发该 header 的功能已经被停用。

以下是三个 beta header 的锁存代码（services/api/claude.ts，第1412-1442行）：

AFK 模式 Header：

// services/api/claude.ts:1412-1423
let afkHeaderLatched = getAfkModeHeaderLatched() === true
if (feature('TRANSCRIPT_CLASSIFIER')) {
  if (
    !afkHeaderLatched &&
    isAgenticQuery &&
    shouldIncludeFirstPartyOnlyBetas() &&
    (autoModeStateModule?.isAutoModeActive() ?? false)
  ) {
    afkHeaderLatched = true
    setAfkModeHeaderLatched(true)
  }
}

Fast Mode Header：

// services/api/claude.ts:1425-1429
let fastModeHeaderLatched = getFastModeHeaderLatched() === true
if (!fastModeHeaderLatched && isFastMode) {
  fastModeHeaderLatched = true
  setFastModeHeaderLatched(true)
}

缓存编辑 Header：

// services/api/claude.ts:1431-1442
let cacheEditingHeaderLatched = getCacheEditingHeaderLatched() === true
if (feature('CACHED_MICROCOMPACT')) {
  if (
    !cacheEditingHeaderLatched &&
    cachedMCEnabled &&
    getAPIProvider() === 'firstParty' &&
    options.querySource === 'repl_main_thread'
  ) {
    cacheEditingHeaderLatched = true
    setCacheEditingHeaderLatched(true)
  }
}

锁存状态图

三个 beta header 的锁存遵循相同的状态转换模式：

stateDiagram-v2
    [*] --> 未锁存
    未锁存 --> 已锁存 : 条件首次为真\n(功能激活 + 满足前置条件)
    已锁存 --> 已锁存 : 功能停用\n(保持锁存不变)
    已锁存 --> 重置 : /clear 或 /compact\n(clearBetaHeaderLatches)
    重置 --> 未锁存 : 下次条件评估

    state 未锁存 {
        [*] : latched = false/null
    }
    state 已锁存 {
        [*] : latched = true
    }
    state 重置 {
        [*] : latched = false/null
    }

图 13-1：Beta Header 锁存状态图

关键特性：

1. 单向锁存：从 false 到 true 是不可逆的（在当前会话内）
2. 条件触发：每个 header 有独立的前置条件组合
3. 会话绑定：只有 /clear 和 /compact 命令会重置锁存状态
4. 查询隔离：isAgenticQuery 和 querySource 等条件保持逐调用评估，确保非 agentic 查询有自己稳定的 header 集

锁存汇总表

表 13-3：Beta Header 锁存详情

13.5 Thinking Clear 锁存

除了 beta header 锁存外，还有一个特殊的锁存机制——thinkingClearLatched（services/api/claude.ts，第1446-1456行）：

// services/api/claude.ts:1446-1456
let thinkingClearLatched = getThinkingClearLatched() === true
if (!thinkingClearLatched && isAgenticQuery) {
  const lastCompletion = getLastApiCompletionTimestamp()
  if (
    lastCompletion !== null &&
    Date.now() - lastCompletion > CACHE_TTL_1HOUR_MS
  ) {
    thinkingClearLatched = true
    setThinkingClearLatched(true)
  }
}

这个锁存的触发条件是：距离上次 API 完成超过 1 小时（CACHE_TTL_1HOUR_MS = 60 * 60 * 1000）。此时即使使用 1 小时 TTL，缓存也已过期。Thinking Clear 利用这个信号优化 thinking 块的处理——既然缓存已经失效，可以清理累积的 thinking 内容，减少后续请求的 token 消耗。

13.6 缓存架构全景

将上述所有机制组合起来，Claude Code 的缓存架构可以概括为以下层次：

┌──────────────────────────────────────────────────────────┐
│                    API 请求构建                           │
│                                                          │
│  ┌─── 系统提示词 ───┐   ┌── 工具定义 ──┐   ┌── 消息 ──┐ │
│  │                  │   │              │   │          │ │
│  │ [attribution]    │   │ [tool 1]     │   │ [msg 1]  │ │
│  │  scope: null     │   │  scope: org  │   │          │ │
│  │                  │   │              │   │ [msg 2]  │ │
│  │ [prefix]         │   │ [tool 2]     │   │          │ │
│  │  scope: org/null │   │  scope: org  │   │ [msg N]  │ │
│  │                  │   │              │   │          │ │
│  │ [static]         │   │ [tool N]     │   │          │ │
│  │  scope: global   │   │  scope: org  │   │          │ │
│  │                  │   │              │   │          │ │
│  │ [dynamic]        │   │              │   │          │ │
│  │  scope: null     │   │              │   │          │ │
│  └──────────────────┘   └──────────────┘   └──────────┘ │
│                                                          │
│  ────────── 前缀匹配方向 ──────────────────────────→      │
│                                                          │
├──────────────────────────────────────────────────────────┤
│                    TTL 决策层                              │
│                                                          │
│  should1hCacheTTL() → 锁存 → 会话稳定                     │
│                                                          │
├──────────────────────────────────────────────────────────┤
│                  Beta Header 锁存层                       │
│                                                          │
│  afkMode / fastMode / cacheEditing → sticky-on           │
│                                                          │
├──────────────────────────────────────────────────────────┤
│                  缓存中断检测层                             │
│  （详见第14章）                                            │
└──────────────────────────────────────────────────────────┘

图 13-2：Claude Code 缓存架构全景

13.7 设计洞察

锁存是缓存稳定性的核心模式

Claude Code 在缓存相关的代码中反复使用同一个模式：首次评估 → 锁存 → 会话稳定。这个模式出现在：

• TTL 资格检查（should1hCacheTTL）
• TTL allowlist 配置
• Beta header 发送状态
• Thinking clear 触发

每一处锁存都是为了同一个目的：防止会话中途的状态变化改变 API 请求的序列化结果，从而保护缓存前缀的完整性。

缓存范围是成本与命中率的权衡

三级缓存范围体现了一个清晰的工程权衡：

• global 范围命中率最高（所有用户共享），但要求内容绝对静态
• org 范围命中率适中，允许包含组织级别的差异
• null 不做缓存标记，避免无效的缓存尝试增加请求复杂度

Claude Code 的策略是“能 global 就 global，不能就 org，都不行就放弃“——这比一刀切的策略更精细，也更有效。

MCP 工具是缓存的最大敌人

MCP 工具的引入给缓存带来了严峻挑战。MCP 服务器可以在会话中途连接或断开，工具定义可以在任何时候变化。当检测到 MCP 工具存在时，系统提示词的全局缓存被降级为 org 级别（skipGlobalCacheForSystemPrompt），工具缓存策略也从系统提示词嵌入切换到独立的 tool_based 策略。这些降级措施在第15章的缓存优化模式中还将进一步讨论。

用户能做什么

基于本章分析的缓存架构，以下是构建缓存友好系统时的实践要点：

1. 理解前缀匹配的含义：Anthropic 的缓存是严格的前缀匹配。在构建 API 请求时，始终将最稳定、最不可能变化的内容放在最前面（系统提示词静态部分），将动态内容（用户消息、附件）放在最后。

2. 为你的系统提示词设计缓存范围：如果你的应用服务多个用户，识别哪些提示词内容是全局共享的（适合 global 范围）、哪些是组织级别的（适合 org 范围）、哪些是完全动态的（不标记 cache_control）。一刀切的缓存策略会浪费命中率。

3. 使用锁存模式保护缓存键稳定性：任何可能在会话中途变化的配置项（feature flag、用户配额状态、功能开关），如果它们影响 API 请求的序列化结果，都应该在会话开始时锁存。锁存的核心原则是：宁可使用略微过时的值，也不要让缓存键在会话中途发生变化。

4. 警惕 MCP 工具对缓存的影响：如果你的应用集成了外部工具（MCP 或类似机制），它们的动态性会显著降低缓存命中率。考虑将外部工具的定义与核心工具分开处理，或在检测到外部工具时降级缓存策略。

5. 监控 cache_read_input_tokens：这是判断缓存健康状态的唯一可靠指标。建立基线后，任何显著下降都值得调查。详见第14章的缓存中断检测系统。

小结

本章剖析了 Claude Code 的提示词缓存架构：

1. 前缀匹配模型要求 API 请求的前缀逐字节稳定，任何变化都会导致缓存中断
2. 三级缓存范围（global/org/null）在命中率和灵活性之间做出精细权衡
3. TTL 层级（5 分钟/1 小时）通过锁存机制保证会话内稳定
4. Beta Header 锁存使用 sticky-on 模式防止功能开关导致缓存键变化

这些机制共同构成了缓存的“防护层“。但光有防护还不够——当缓存确实发生中断时，系统需要能够检测到并诊断原因。第14章将深入缓存中断检测系统的两阶段架构。

第14章：缓存中断检测系统

为什么这很重要

在第13章中，我们看到 Claude Code 通过锁存机制和精心设计的缓存范围来预防缓存中断。但即使有这些防护措施，缓存中断仍然会发生——工具定义可能因为 MCP 服务器重连而变化，系统提示词可能因为新的附件而增长，模型切换、effort 调整、甚至 GrowthBook 的远程配置更新都可能改变 API 请求的前缀。

更棘手的是，缓存中断是“静默“的。API 响应中的 cache_read_input_tokens 下降了，但没有任何错误信息告诉你为什么。开发者只会注意到成本上升了、延迟增加了，却不知道根因在哪里。

Claude Code 构建了一套两阶段缓存中断检测系统来解决这个问题。整个系统实现在 services/api/promptCacheBreakDetection.ts（728行），是 Claude Code 中为数不多专门服务于可观测性（observability）而非功能的子系统。

14.1 两阶段检测架构

设计思路

缓存中断检测面临一个时序问题：

1. 变化发生在请求发送前：系统提示词变了、工具增删了、beta header 翻转了
2. 中断确认在响应返回后：只有看到 cache_read_input_tokens 的下降才能确认缓存确实被击穿了

仅有阶段 2 是不够的——当检测到 token 下降时，请求已经发送，之前的状态已经丢失，无法回溯原因。仅有阶段 1 也不够——很多客户端变化并不一定导致服务端缓存中断（例如，服务端可能恰好还没有缓存该前缀）。

Claude Code 的解决方案是将检测分为两个阶段：

flowchart LR
    subgraph Phase1["阶段 1（请求前）<br />recordPromptState()"]
        A1[捕获当前状态] --> A2[对比前次状态]
        A2 --> A3[记录变化清单]
        A3 --> A4[存为 pendingChanges]

    Phase1 -- "API 请求/响应" --> Phase2

    subgraph Phase2["阶段 2（响应后）<br />checkResponseForCacheBreak()"]
        B1[检查 cache tokens] --> B2[确认是否真正中断]
        B2 --> B3[用阶段 1 的变化解释原因]
        B3 --> B4[输出诊断信息]
        B4 --> B5[发送 analytics 事件]

图 14-1：两阶段检测时序图

调用位置

两个阶段的调用位置在 services/api/claude.ts 中：

阶段 1 在构建 API 请求时调用（第1460-1486行）：

// services/api/claude.ts:1460-1486
if (feature('PROMPT_CACHE_BREAK_DETECTION')) {
  const toolsForCacheDetection = allTools.filter(
    t => !('defer_loading' in t && t.defer_loading),
  )
  recordPromptState({
    system,
    toolSchemas: toolsForCacheDetection,
    querySource: options.querySource,
    model: options.model,
    agentId: options.agentId,
    fastMode: fastModeHeaderLatched,
    globalCacheStrategy,
    betas,
    autoModeActive: afkHeaderLatched,
    isUsingOverage: currentLimits.isUsingOverage ?? false,
    cachedMCEnabled: cacheEditingHeaderLatched,
    effortValue: effort,
    extraBodyParams: getExtraBodyParams(),
  })
}

注意两个关键设计决策：

1. 排除 defer_loading 工具：API 会自动剥离延迟加载的工具，它们不影响实际的缓存键。包含它们会在工具发现或 MCP 服务器重连时产生误报。
2. 传入锁存后的值：fastModeHeaderLatched、afkHeaderLatched、cacheEditingHeaderLatched 是锁存后的值，而非实时状态。因为缓存键由实际发送的 header 决定，而非用户当前的设置。

阶段 2 在 API 响应处理完成后调用，传入响应中的缓存 token 统计数据。

14.2 PreviousState：全量状态快照

阶段 1 的核心是 PreviousState 类型——它捕获了所有可能影响服务端缓存键的客户端状态。

字段清单

PreviousState 定义在 promptCacheBreakDetection.ts（第28-69行），包含 15+ 个字段：

表 14-1：PreviousState 完整字段清单

哈希策略

PreviousState 中有多个哈希字段，它们服务于不同的检测粒度：

// promptCacheBreakDetection.ts:170-179
      // function computeHash(data: unknown): number {
  const str = jsonStringify(data)
  if (typeof Bun !== 'undefined') {
    const hash = Bun.hash(str)
    return typeof hash === 'bigint' ? Number(hash & 0xffffffffn) : hash
  }
  return djb2Hash(str)
}

systemHash vs cacheControlHash 的分离设计值得特别关注：

// promptCacheBreakDetection.ts:274-281
const systemHash = computeHash(strippedSystem)  // 不含 cache_control
const cacheControlHash = computeHash(           // 只有 cache_control
  system.map(b => ('cache_control' in b ? b.cache_control : null)),
)

systemHash 对系统提示词内容做哈希，先通过 stripCacheControl() 移除 cache_control 标记。cacheControlHash 只对 cache_control 标记做哈希。为什么要分离？因为缓存范围翻转（global → org）或 TTL 翻转（1h → 5m）不会改变提示词的文本内容——如果只看 systemHash，这些翻转会被遗漏。分离后，cacheControlChanged 可以独立捕获这类变化。

perToolHashes 的按需计算也是一个性能优化：

// promptCacheBreakDetection.ts:285-286
const computeToolHashes = () =>
  computePerToolHashes(strippedTools, toolNames)

perToolHashes 是一个逐工具的哈希表，用于在工具 Schema 聚合哈希变化时精确定位是哪个工具发生了变化。但逐工具计算哈希的成本较高（N 次 jsonStringify），因此只在 toolsHash 变化时才触发计算。注释（第37行）引用了 BigQuery 数据：77% 的工具 Schema 变化是单个工具的描述改变，而非工具增删。perToolHashes 正是为了精确诊断这 77% 的场景。

跟踪键与隔离策略

每个查询源（query source）维护独立的 PreviousState，存储在一个 Map 中：

// promptCacheBreakDetection.ts:101-107
const previousStateBySource = new Map<string, PreviousState>()

const MAX_TRACKED_SOURCES = 10

const TRACKED_SOURCE_PREFIXES = [
  'repl_main_thread',
  'sdk',
  'agent:custom',
  'agent:default',
  'agent:builtin',
]

跟踪键通过 getTrackingKey() 函数计算（第149-158行）：

// promptCacheBreakDetection.ts:149-158
      // function getTrackingKey(
  querySource: QuerySource,
  agentId?: AgentId,
): string | null {
  if (querySource === 'compact') return 'repl_main_thread'
  for (const prefix of TRACKED_SOURCE_PREFIXES) {
    if (querySource.startsWith(prefix)) return agentId || querySource
  }
  return null
}

几个重要的设计决策：

1. compact 共享 main thread 的跟踪状态：压缩操作使用相同的 cacheSafeParams，共享缓存键，所以应该共享检测状态
2. 子 Agent 使用 agentId 隔离：防止同类型的多个并发 Agent 实例之间产生误报
3. 不跟踪的查询源返回 null：speculation、session_memory、prompt_suggestion 等短生命周期的 Agent 只运行 1-3 轮，没有前后对比的价值
4. Map 容量上限：MAX_TRACKED_SOURCES = 10，防止大量子 Agent 的 agentId 导致内存无限增长

14.3 阶段 1：recordPromptState() 详解

首次调用：建立基线

首次调用 recordPromptState() 时，没有前一个状态可以对比，函数只做两件事：

1. 检查 Map 容量，如果达到上限则驱逐最旧的条目
2. 创建初始 PreviousState 快照，pendingChanges 设为 null

// promptCacheBreakDetection.ts:298-328
if (!prev) {
  while (previousStateBySource.size >= MAX_TRACKED_SOURCES) {
    const oldest = previousStateBySource.keys().next().value
    if (oldest !== undefined) previousStateBySource.delete(oldest)
  }

  previousStateBySource.set(key, {
    systemHash,
    toolsHash,
    cacheControlHash,
    toolNames,
    // ... 所有初始值
    callCount: 1,
    pendingChanges: null,
    prevCacheReadTokens: null,
    cacheDeletionsPending: false,
    buildDiffableContent: lazyDiffableContent,
    perToolHashes: computeToolHashes(),
  })
  return
}

后续调用：变化检测

后续调用时，函数逐字段对比当前值与前一个状态：

// promptCacheBreakDetection.ts:332-346
const systemPromptChanged = systemHash !== prev.systemHash
const toolSchemasChanged = toolsHash !== prev.toolsHash
const modelChanged = model !== prev.model
const fastModeChanged = isFastMode !== prev.fastMode
const cacheControlChanged = cacheControlHash !== prev.cacheControlHash
const globalCacheStrategyChanged =
  globalCacheStrategy !== prev.globalCacheStrategy
const betasChanged =
  sortedBetas.length !== prev.betas.length ||
  sortedBetas.some((b, i) => b !== prev.betas[i])
const autoModeChanged = autoModeActive !== prev.autoModeActive
const overageChanged = isUsingOverage !== prev.isUsingOverage
const cachedMCChanged = cachedMCEnabled !== prev.cachedMCEnabled
const effortChanged = effortStr !== prev.effortValue
const extraBodyChanged = extraBodyHash !== prev.extraBodyHash

如果任何字段发生变化，函数构建 PendingChanges 对象：

// promptCacheBreakDetection.ts:71-99
type PendingChanges = {
  systemPromptChanged: boolean
  toolSchemasChanged: boolean
  modelChanged: boolean
  fastModeChanged: boolean
  cacheControlChanged: boolean
  globalCacheStrategyChanged: boolean
  betasChanged: boolean
  autoModeChanged: boolean
  overageChanged: boolean
  cachedMCChanged: boolean
  effortChanged: boolean
  extraBodyChanged: boolean
  addedToolCount: number
  removedToolCount: number
  systemCharDelta: number
  addedTools: string[]
  removedTools: string[]
  changedToolSchemas: string[]
  previousModel: string
  newModel: string
  prevGlobalCacheStrategy: string
  newGlobalCacheStrategy: string
  addedBetas: string[]
  removedBetas: string[]
  prevEffortValue: string
  newEffortValue: string
  buildPrevDiffableContent: () => string
}

PendingChanges 不仅记录是否变化（boolean 标志），还记录如何变化（增减了哪些工具、beta header 的增删列表、字符数变化量等）。这些详细信息在阶段 2 的中断解释中至关重要。

工具变化的精确归因

当 toolSchemasChanged 为真时，系统进一步分析是哪些工具发生了变化：

// promptCacheBreakDetection.ts:366-378
if (toolSchemasChanged) {
  const newHashes = computeToolHashes()
  for (const name of toolNames) {
    if (!prevToolSet.has(name)) continue
    if (newHashes[name] !== prev.perToolHashes[name]) {
      changedToolSchemas.push(name)
    }
  }
  prev.perToolHashes = newHashes
}

这段代码将工具变化分为三类：

• 新增工具：在新列表中但不在旧列表中（addedTools）
• 移除工具：在旧列表中但不在新列表中（removedTools）
• Schema 变化：工具仍在，但 Schema 哈希不同（changedToolSchemas）

第三类是最常见的——AgentTool 和 SkillTool 的描述中嵌入了动态的 Agent 列表和命令列表，这些内容随会话状态变化。

14.4 阶段 2：checkResponseForCacheBreak() 详解

中断判定标准

阶段 2 在 API 响应返回后调用，核心逻辑是判断缓存是否真正被击穿：

// promptCacheBreakDetection.ts:485-493
const tokenDrop = prevCacheRead - cacheReadTokens
if (
  cacheReadTokens >= prevCacheRead * 0.95 ||
  tokenDrop < MIN_CACHE_MISS_TOKENS
) {
  state.pendingChanges = null
  return
}

判定使用双重门槛：

1. 相对阈值：缓存读取 token 数下降超过 5%（< prevCacheRead * 0.95）
2. 绝对阈值：下降超过 2,000 tokens（MIN_CACHE_MISS_TOKENS = 2_000）

两个条件必须同时满足才触发中断告警。这避免了两类误报：

• 小幅波动：缓存 token 数的自然变化（几百 tokens）不触发告警
• 比例放大：当基线很小时（例如 1,000 tokens），5% 的波动只有 50 tokens，不值得告警

特殊情况：Cache Deletion

缓存编辑（Cached Microcompact）可以通过 cache_edits 主动删除缓存中的内容块。这会导致 cache_read_input_tokens 合法地下降——这是预期行为，不应触发中断告警：

// promptCacheBreakDetection.ts:473-481
if (state.cacheDeletionsPending) {
  state.cacheDeletionsPending = false
  logForDebugging(
    `[PROMPT CACHE] cache deletion applied, cache read: ` +
    `${prevCacheRead} → ${cacheReadTokens} (expected drop)`,
  )
  state.pendingChanges = null
  return
}

cacheDeletionsPending 标志通过 notifyCacheDeletion() 函数设置（第673-682行），由缓存编辑模块在发送删除操作时调用。

特殊情况：Compaction

压缩操作（/compact）会大幅减少消息数量，导致缓存读取 token 数自然下降。notifyCompaction() 函数（第689-698行）通过将 prevCacheReadTokens 重置为 null 来处理这种情况——下一次调用被视为“首次调用“，不做对比：

// promptCacheBreakDetection.ts:689-698
      // export function notifyCompaction(
  querySource: QuerySource,
  agentId?: AgentId,
): void {
  const key = getTrackingKey(querySource, agentId)
  const state = key ? previousStateBySource.get(key) : undefined
  if (state) {
    state.prevCacheReadTokens = null
  }
}

14.5 中断解释引擎

当确认缓存中断后，系统使用阶段 1 收集的 PendingChanges 构建人类可读的解释。解释引擎位于 checkResponseForCacheBreak() 的第495-588行：

客户端归因

如果 PendingChanges 中有变化标志为真，系统生成对应的解释文本：

// promptCacheBreakDetection.ts:496-563（简化）
const parts: string[] = []
if (changes) {
  if (changes.modelChanged) {
    parts.push(`model changed (${changes.previousModel} → ${changes.newModel})`)
  }
  if (changes.systemPromptChanged) {
    const charInfo = charDelta > 0 ? ` (+${charDelta} chars)` : ` (${charDelta} chars)`
    parts.push(`system prompt changed${charInfo}`)
  }
  if (changes.toolSchemasChanged) {
    const toolDiff = changes.addedToolCount > 0 || changes.removedToolCount > 0
      ? ` (+${changes.addedToolCount}/-${changes.removedToolCount} tools)`
      : ' (tool prompt/schema changed, same tool set)'
    parts.push(`tools changed${toolDiff}`)
  }
  if (changes.betasChanged) {
    const added = changes.addedBetas.length ? `+${changes.addedBetas.join(',')}` : ''
    const removed = changes.removedBetas.length ? `-${changes.removedBetas.join(',')}` : ''
    parts.push(`betas changed (${[added, removed].filter(Boolean).join(' ')})`)
  }
  // ... 其他字段的解释逻辑类似
}

解释引擎的设计原则是具体胜于抽象：不是简单地说“缓存中断了“，而是精确列出哪些字段变化了、变化了多少。

cacheControl 变化的独立报告逻辑

在解释引擎中，cacheControlChanged 有一个特殊的报告条件：

// promptCacheBreakDetection.ts:528-535
if (
  changes.cacheControlChanged &&
  !changes.globalCacheStrategyChanged &&
  !changes.systemPromptChanged
) {
  parts.push('cache_control changed (scope or TTL)')
}

只有在全局缓存策略和系统提示词都没变的情况下，才单独报告 cacheControlChanged。原因是：如果全局缓存策略变了（例如从 tool_based 切换到 system_prompt），cache_control 的变化只是策略变化的后果，不需要重复报告。同理，如果系统提示词变了，cache_control 可能只是因为新的内容块结构调整了缓存标记。

TTL 过期检测

当没有客户端变化被检测到时（parts.length === 0），系统检查是否可能是 TTL 过期导致的缓存失效：

// promptCacheBreakDetection.ts:566-588
const lastAssistantMsgOver5minAgo =
  timeSinceLastAssistantMsg !== null &&
  timeSinceLastAssistantMsg > CACHE_TTL_5MIN_MS
const lastAssistantMsgOver1hAgo =
  timeSinceLastAssistantMsg !== null &&
  timeSinceLastAssistantMsg > CACHE_TTL_1HOUR_MS

let reason: string
if (parts.length > 0) {
  reason = parts.join(', ')
} else if (lastAssistantMsgOver1hAgo) {
  reason = 'possible 1h TTL expiry (prompt unchanged)'
} else if (lastAssistantMsgOver5minAgo) {
  reason = 'possible 5min TTL expiry (prompt unchanged)'
} else if (timeSinceLastAssistantMsg !== null) {
  reason = 'likely server-side (prompt unchanged, <5min gap)'
} else {
  reason = 'unknown cause'
}

TTL 过期检测通过查找消息历史中最近的 assistant 消息时间戳来计算时间间隔。两个 TTL 常量定义在文件顶部（第125-126行）：

// promptCacheBreakDetection.ts:125-126
const CACHE_TTL_5MIN_MS = 5 * 60 * 1000
export const CACHE_TTL_1HOUR_MS = 60 * 60 * 1000

服务端归因：“90% 的中断是服务端原因”

最关键的一段注释位于第573-576行：

// promptCacheBreakDetection.ts:573-576
// Post PR #19823 BQ analysis:
// when all client-side flags are false and the gap is under TTL, ~90% of breaks
// are server-side routing/eviction or billed/inference disagreement. Label
// accordingly instead of implying a CC bug hunt.

这段注释引用了一次 BigQuery 数据分析的结论：当客户端没有检测到任何变化，且时间间隔在 TTL 之内时，约 90% 的缓存中断归因于服务端。具体原因包括：

1. 服务端路由变化：请求被路由到不同的服务器实例，该实例没有缓存
2. 服务端缓存驱逐：在高负载期间，服务端主动驱逐低优先级的缓存条目
3. 计费/推理不一致：实际推理使用了缓存，但计费系统报告了不同的 token 数

这个发现改变了中断解释的措辞——从暗示“Claude Code 有 bug“变为明确标记“可能是服务端原因“（likely server-side），避免开发者浪费时间追查不存在的客户端问题。

14.6 诊断输出

中断检测的最终输出包含两部分：

Analytics 事件

tengu_prompt_cache_break 事件发送到 BigQuery 用于全量分析：

// promptCacheBreakDetection.ts:590-644
logEvent('tengu_prompt_cache_break', {
  systemPromptChanged: changes?.systemPromptChanged ?? false,
  toolSchemasChanged: changes?.toolSchemasChanged ?? false,
  modelChanged: changes?.modelChanged ?? false,
  // ... 所有变化标志
  addedTools: (changes?.addedTools ?? []).map(sanitizeToolName).join(','),
  removedTools: (changes?.removedTools ?? []).map(sanitizeToolName).join(','),
  changedToolSchemas: (changes?.changedToolSchemas ?? []).map(sanitizeToolName).join(','),
  addedBetas: (changes?.addedBetas ?? []).join(','),
  removedBetas: (changes?.removedBetas ?? []).join(','),
  callNumber: state.callCount,
  prevCacheReadTokens: prevCacheRead,
  cacheReadTokens,
  cacheCreationTokens,
  timeSinceLastAssistantMsg: timeSinceLastAssistantMsg ?? -1,
  lastAssistantMsgOver5minAgo,
  lastAssistantMsgOver1hAgo,
  requestId: requestId ?? '',
})

Analytics 事件记录了完整的变化标志集合、token 统计、时间间隔和请求 ID，使得后续的 BigQuery 分析可以切分不同维度（按变化类型、按时间窗口、按查询源等）。

调试 Diff 文件与日志

当检测到客户端变化时，系统生成一个 diff 文件，展示前后状态的逐行差异：

// promptCacheBreakDetection.ts:648-660
let diffPath: string | undefined
if (changes?.buildPrevDiffableContent) {
  diffPath = await writeCacheBreakDiff(
    changes.buildPrevDiffableContent(),
    state.buildDiffableContent(),
  )
}

const summary = `[PROMPT CACHE BREAK] ${reason} ` +
  `[source=${querySource}, call #${state.callCount}, ` +
  `cache read: ${prevCacheRead} → ${cacheReadTokens}, ` +
  `creation: ${cacheCreationTokens}${diffSuffix}]`

logForDebugging(summary, { level: 'warn' })

diff 文件通过 writeCacheBreakDiff() 生成（第708-727行），使用 createPatch 库创建标准的 unified diff 格式，保存在临时目录中。文件名包含随机后缀避免冲突。

工具名称安全化

中断检测系统需要在 analytics 事件中报告发生变化的工具名称。但 MCP 工具的名称由用户配置，可能包含文件路径或其他敏感信息。sanitizeToolName() 函数（第183-185行）解决了这个问题：

// promptCacheBreakDetection.ts:183-185
      // function sanitizeToolName(name: string): string {
  return name.startsWith('mcp__') ? 'mcp' : name
}

所有以 mcp__ 开头的工具名称被统一替换为 'mcp'，而内置工具的名称是一个固定词汇表，可以安全地包含在 analytics 中。

14.7 完整检测流程

将两个阶段串联起来，完整的缓存中断检测流程如下：

用户输入新查询
     │
     ▼
┌──────────────────────────────────┐
│ 构建 API 请求                     │
│ (系统提示词 + 工具 + 消息)         │
└────────────────┬─────────────────┘
                 │
                 ▼
┌──────────────────────────────────┐
│ recordPromptState()  [阶段 1]     │
│                                  │
│ ① 计算所有哈希值                  │
│ ② 查找 previousState             │
│ ③ 无 prev → 创建初始快照          │
│ ④ 有 prev → 逐字段对比            │
│ ⑤ 发现变化 → 生成 PendingChanges  │
│ ⑥ 更新 previousState              │
└────────────────┬─────────────────┘
                 │
                 ▼
         [发送 API 请求]
                 │
                 ▼
         [收到 API 响应]
                 │
                 ▼
┌──────────────────────────────────┐
│ checkResponseForCacheBreak()      │
│ [阶段 2]                          │
│                                  │
│ ① 获取 previousState             │
│ ② 排除 haiku 模型                │
│ ③ 检查 cacheDeletionsPending     │
│ ④ 计算 token 下降量              │
│ ⑤ 应用双重门槛判定                │
│   (> 5% 且 > 2,000 tokens)      │
│ ⑥ 未中断 → 清除 pending, 返回    │
│ ⑦ 中断确认 → 构建解释             │
│   - 有客户端变化 → 列举变化        │
│   - 无变化 + 超 TTL → TTL 过期   │
│   - 无变化 + 未超 TTL → 服务端    │
│ ⑧ 发送 analytics 事件            │
│ ⑨ 写入 diff 文件                  │
│ ⑩ 输出调试日志                    │
└──────────────────────────────────┘

图 14-2：完整缓存中断检测流程图

14.8 排除模型与清理机制

排除模型

并非所有模型都适合缓存中断检测：

// promptCacheBreakDetection.ts:129-131
      // function isExcludedModel(model: string): boolean {
  return model.includes('haiku')
}

Haiku 模型因为有不同的缓存行为，被排除在检测之外。这避免了因模型差异导致的误报。

清理机制

系统提供三个清理函数，分别应对不同场景：

// promptCacheBreakDetection.ts:700-706
// Agent 结束时清理其跟踪状态
      // export function cleanupAgentTracking(agentId: AgentId): void {
  previousStateBySource.delete(agentId)
}

// 完全重置（/clear 命令）
      // export function resetPromptCacheBreakDetection(): void {
  previousStateBySource.clear()
}

cleanupAgentTracking 在子 Agent 结束时调用，释放其 PreviousState 占用的内存。resetPromptCacheBreakDetection 在用户执行 /clear 时调用，清除所有跟踪状态。

14.9 设计洞察

两阶段是唯一正确的架构

缓存中断检测的两阶段架构不是一个设计选择，而是由问题的时序约束决定的唯一正确方案。原因在于：原始状态只存在于请求发送前，中断确认只能在响应返回后。任何试图在单一阶段完成两项工作的方案都会丢失关键信息。

“90% 服务端“改变了工程决策

发现大部分缓存中断是服务端原因后，Claude Code 团队的优化重点从“消除所有客户端变化“转向“确保客户端变化可控“。这解释了为什么第13章的锁存机制如此重要——它们不需要消除 100% 的缓存中断，只需要确保客户端可控的那 10% 不再出问题。

可观测性先于优化

整个缓存中断检测系统不做任何缓存优化——它纯粹是可观测性基础设施。但正是这套可观测性使得第15章的优化模式成为可能：没有精确的中断检测，就无法量化优化的效果，也无法发现新的优化机会。BigQuery 中的 tengu_prompt_cache_break 事件数据直接驱动了多个优化模式的发现和验证。

用户能做什么

基于本章分析的缓存中断检测机制，以下是监控和诊断缓存中断的实践要点：

1. 在你的应用中建立缓存基线：记录正常会话中 cache_read_input_tokens 的典型值。没有基线就无法判断下降是否异常。Claude Code 使用双重门槛（>5% 且 >2,000 tokens）来过滤噪声，你也应该根据自己的场景设定合理的阈值。

2. 区分客户端变化与服务端原因：当观察到缓存命中率下降时，先检查客户端是否有变化（系统提示词、工具定义、beta header 等）。如果客户端没有变化且时间间隔在 TTL 之内，大概率是服务端路由或驱逐导致的——不要浪费时间追查不存在的客户端 bug。

3. 为你的请求建立状态快照机制：如果你需要诊断缓存中断，在每次请求前记录关键状态（系统提示词哈希、工具 Schema 哈希、请求 header 列表）。只有在请求前捕获状态，才能在响应后回溯变化原因。

4. 注意 TTL 过期是常见的合法原因：如果用户在两次请求之间有较长停顿（超过 5 分钟或 1 小时，取决于你的 TTL 等级），缓存自然过期是正常现象，不需要特别处理。

5. 对工具变化做精细归因：如果你的应用使用动态工具集（MCP 等），在检测到工具 Schema 变化时，进一步区分是工具增删还是单个工具的 Schema 变化。后者更常见（Claude Code 数据显示 77% 的工具变化属于此类），也更容易通过会话级缓存解决。

小结

本章深入分析了 Claude Code 的缓存中断检测系统：

1. 两阶段架构：recordPromptState() 在请求前捕获状态并检测变化，checkResponseForCacheBreak() 在响应后确认中断并生成诊断
2. PreviousState 15+ 字段：覆盖了所有可能影响服务端缓存键的客户端状态
3. 中断解释引擎：区分客户端变化、TTL 过期和服务端原因，提供精确的归因
4. 数据驱动的洞察：“90% 的中断是服务端原因“这一发现改变了整个缓存优化策略

下一章将转向主动优化——Claude Code 如何通过 7+ 个命名的缓存优化模式，在源头减少缓存中断的发生。

第15章：缓存优化模式

为什么这很重要

第13章分析了缓存架构的防御层，第14章构建了缓存中断的检测能力。本章将转向进攻——Claude Code 如何通过一系列命名的优化模式，从源头消除或减少缓存中断的发生。

这些优化模式并非一次性设计出来的。每一个模式都源自第14章介绍的缓存中断检测系统在 BigQuery 中捕获的真实数据。当 tengu_prompt_cache_break 事件揭示某个特定的中断原因反复出现时，工程团队就会设计一个针对性的优化模式来消除它。

本章将介绍 7 个以上的命名缓存优化模式，从简单的日期记忆化到复杂的工具 Schema 缓存。每个模式都遵循同一个框架：识别变化源 → 理解变化本质 → 将动态变为静态。

模式汇总

在深入每个模式之前，先看一个全局视图：

表 15-1：7+ 缓存优化模式汇总

15.1 模式一：日期记忆化 getSessionStartDate()

问题

Claude Code 的系统提示词包含当前日期（currentDate），用于帮助模型理解时间上下文。日期通过 getLocalISODate() 函数获取：

// constants/common.ts:4-15
      // export function getLocalISODate(): string {
  if (process.env.CLAUDE_CODE_OVERRIDE_DATE) {
    return process.env.CLAUDE_CODE_OVERRIDE_DATE
  }

  const now = new Date()
  const year = now.getFullYear()
  const month = String(now.getMonth() + 1).padStart(2, '0')
  const day = String(now.getDate()).padStart(2, '0')
  return `${year}-${month}-${day}`
}

问题出在午夜跨天：如果用户在 23:59 发起一个请求，系统提示词包含 2026-04-01；当用户在 00:01 发起下一个请求时，日期变为 2026-04-02。这一个字符的变化就足以击穿整个系统提示词前缀的缓存——约 11,000 tokens 需要重新计算。

解决方案

// constants/common.ts:24
export const getSessionStartDate = memoize(getLocalISODate)

getSessionStartDate 使用 lodash 的 memoize 包装 getLocalISODate——函数在首次调用时捕获日期，此后永远返回相同的值，无论实际日期是否已经变化。

源码注释（第17-23行）详细解释了这个决策的权衡：

// constants/common.ts:17-23
// Memoized for prompt-cache stability — captures the date once at session start.
// The main interactive path gets this behavior via memoize(getUserContext) in
// context.ts; simple mode (--bare) calls getSystemPrompt per-request and needs
// an explicit memoized date to avoid busting the cached prefix at midnight.
// When midnight rolls over, getDateChangeAttachments appends the new date at
// the tail (though simple mode disables attachments, so the trade-off there is:
// stale date after midnight vs. ~entire-conversation cache bust — stale wins).

设计权衡

权衡是清晰的：过时的日期 vs 缓存全量击穿。选择过时日期是因为：

1. 日期信息对大多数编程任务不关键
2. 当午夜确实发生时，getDateChangeAttachments 会在消息尾部追加新日期——这不影响前缀缓存
3. Simple mode（--bare）禁用了附件机制，所以必须在源头做记忆化

影响

这个单行优化消除了每日一次的全前缀缓存击穿。对于跨午夜工作的用户，这节省了约 11,000 tokens 的 cache_creation 费用。

15.2 模式二：月度粒度 getLocalMonthYear()

问题

日期记忆化解决了系统提示词中的跨天问题，但工具提示词中也需要时间信息。如果工具提示词使用完整日期（YYYY-MM-DD），每天凌晨都会导致包含该工具的 Schema 缓存失效。而工具 Schema 位于 API 请求的前端位置，其变化的破坏性比系统提示词更大。

解决方案

// constants/common.ts:28-33
      // export function getLocalMonthYear(): string {
  const date = process.env.CLAUDE_CODE_OVERRIDE_DATE
    ? new Date(process.env.CLAUDE_CODE_OVERRIDE_DATE)
    : new Date()
  return date.toLocaleString('en-US', { month: 'long', year: 'numeric' })
}

getLocalMonthYear() 返回 “Month YYYY” 格式（例如 “April 2026”），而非完整日期。变化频率从每日降低到每月。

注释（第27行）说明了设计意图：

// Returns "Month YYYY" (e.g. "February 2026") in the user's local timezone.
// Changes monthly, not daily — used in tool prompts to minimize cache busting.

两种时间精度的分工

这种分工反映了一个基本原则：越靠近 API 请求前端的内容，越需要更低的变化频率。

15.3 模式三：Agent 列表从工具描述移至消息附件

问题

AgentTool 的工具描述中嵌入了可用 Agent 的列表——每个 Agent 的名称、类型和描述。这个列表是动态的：MCP 服务器异步连接会带来新的 Agent、/reload-plugins 命令会刷新插件列表、权限模式变化会改变可用 Agent 集合。

每次列表变化，AgentTool 的工具 Schema 就会改变，导致整个工具 Schema 数组的缓存失效。工具 Schema 在 API 请求中位于系统提示词之后，它的变化不仅废弃自身的缓存，还会废弃下游所有消息的缓存。

源码注释（tools/AgentTool/prompt.ts，第50-57行）量化了这个问题的严重性：

// tools/AgentTool/prompt.ts:50-57
// The dynamic agent list was ~10.2% of fleet cache_creation tokens: MCP async
// connect, /reload-plugins, or permission-mode changes mutate the list →
// description changes → full tool-schema cache bust.

10.2% 的全量 cache_creation tokens 归因于这个问题。

解决方案

// tools/AgentTool/prompt.ts:59-64
      // export function shouldInjectAgentListInMessages(): boolean {
  if (isEnvTruthy(process.env.CLAUDE_CODE_AGENT_LIST_IN_MESSAGES)) return true
  if (isEnvDefinedFalsy(process.env.CLAUDE_CODE_AGENT_LIST_IN_MESSAGES))
    return false
  return getFeatureValue_CACHED_MAY_BE_STALE('tengu_agent_list_attach', false)
}

解决方案是将动态的 Agent 列表从 AgentTool 的工具描述中移出，改为通过消息附件（attachment）注入。工具描述变为静态文本，只描述 AgentTool 的通用功能；可用 Agent 的列表作为 agent_listing_delta 附件追加在用户消息中。

这个迁移的关键洞察是：附件追加在消息尾部，不影响前缀缓存。Agent 列表的变化只增加新消息的 token 成本，不会废弃已缓存的工具 Schema。

影响

消除了 10.2% 的 cache_creation tokens——这是所有优化模式中影响最大的单一改进。通过 GrowthBook feature flag tengu_agent_list_attach 控制灰度发布，同时保留环境变量 CLAUDE_CODE_AGENT_LIST_IN_MESSAGES 作为手动覆盖。

15.4 模式四：技能列表预算（1% Context Window）

问题

SkillTool 类似于 AgentTool，其工具描述中嵌入了可用技能的列表。随着技能生态的增长（内置技能 + 项目技能 + 插件技能），列表可能变得非常长。更重要的是，技能的加载是动态的——不同项目有不同的 .claude/ 配置，插件可能在会话中途加载或卸载。

解决方案

// tools/SkillTool/prompt.ts:20-23
// Skill listing gets 1% of the context window (in characters)
export const SKILL_BUDGET_CONTEXT_PERCENT = 0.01
export const CHARS_PER_TOKEN = 4
export const DEFAULT_CHAR_BUDGET = 8_000 // Fallback: 1% of 200k × 4

SkillTool 对技能列表施加了严格的预算限制：列表总大小不超过上下文窗口的 1%。对于 200K 的上下文窗口，这约为 8,000 个字符。

预算计算函数（第31-41行）：

// tools/SkillTool/prompt.ts:31-41
      // export function getCharBudget(contextWindowTokens?: number): number {
  if (Number(process.env.SLASH_COMMAND_TOOL_CHAR_BUDGET)) {
    return Number(process.env.SLASH_COMMAND_TOOL_CHAR_BUDGET)
  }
  if (contextWindowTokens) {
    return Math.floor(
      contextWindowTokens * CHARS_PER_TOKEN * SKILL_BUDGET_CONTEXT_PERCENT,
    )
  }
  return DEFAULT_CHAR_BUDGET
}

此外，每个技能条目的描述也被截断：

// tools/SkillTool/prompt.ts:29
export const MAX_LISTING_DESC_CHARS = 250

注释（第25-28行）解释了设计逻辑：

// Per-entry hard cap. The listing is for discovery only — the Skill tool loads
// full content on invoke, so verbose whenToUse strings waste turn-1 cache_creation
// tokens without improving match rate.

缓存优化的本质

1% 预算控制的缓存优化效果体现在两个方面：

1. 限制工具描述大小：更短的描述意味着更少的字节需要精确匹配
2. 预算裁剪减少抖动：当新技能被加载但预算已满时，它不会被包含在列表中——列表不变，缓存不破

这是一个“预算即稳定“的模式：通过限制动态内容的最大尺寸，间接控制了缓存键的变化幅度。

15.5 模式五：$TMPDIR 占位符

问题

BashTool 的提示词中需要告诉模型可以写入的临时目录路径。Claude Code 使用 getClaudeTempDir() 获取这个路径，格式通常为 /private/tmp/claude-{UID}/，其中 {UID} 是用户的系统 UID。

问题在于：不同用户有不同的 UID，因此路径字符串不同。如果这个路径嵌入在工具提示词中，它会阻止跨用户的全局缓存命中。用户 A 的 /private/tmp/claude-1001/ 和用户 B 的 /private/tmp/claude-1002/ 是不同的字节序列，即使在全局缓存范围内也无法共享。

解决方案

// tools/BashTool/prompt.ts:186-190
// Replace the per-UID temp dir literal (e.g. /private/tmp/claude-1001/) with
// "$TMPDIR" so the prompt is identical across users — avoids busting the
// cross-user global prompt cache. The sandbox already sets $TMPDIR at runtime.
const claudeTempDir = getClaudeTempDir()
const normalizeAllowOnly = (paths: string[]): string[] =>
  [...new Set(paths)].map(p => (p === claudeTempDir ? '$TMPDIR' : p))

解决方案优雅而简洁：将用户特定的临时目录路径替换为 $TMPDIR 占位符。由于 Claude Code 的沙箱环境已经将 $TMPDIR 设置为正确的目录，模型使用 $TMPDIR 引用临时目录与使用绝对路径效果相同。

提示词中还明确告知模型使用 $TMPDIR：

// tools/BashTool/prompt.ts:258-260
'For temporary files, always use the `$TMPDIR` environment variable. ' +
'TMPDIR is automatically set to the correct sandbox-writable directory ' +
'in sandbox mode. Do NOT use `/tmp` directly - use `$TMPDIR` instead.',

影响

这个优化使得 BashTool 的提示词在所有用户之间逐字节一致，从而允许全局缓存范围的前缀共享。对于 BashTool 这个最常用的工具，其 Schema 的全局缓存命中意味着显著的成本节约。

15.6 模式六：条件段落省略

问题

系统提示词中有一些段落只在特定条件下出现：某个 feature flag 启用时添加一段说明，某个功能可用时插入一段指导。当这些条件在会话中途翻转（例如 GrowthBook 的远程配置更新），段落的出现/消失会改变系统提示词的内容，导致缓存中断。

解决方案

条件段落省略模式的核心原则是：宁可不说，不要说了又删。具体实施方式包括：

1. 用静态文本替代条件段落：如果一段说明对模型行为影响不大，干脆总是包含它（或总是不包含），避免条件判断
2. 将条件内容移到动态边界之后：如果必须条件性包含，将其放在 SYSTEM_PROMPT_DYNAMIC_BOUNDARY 之后，此区域不参与全局缓存（详见第13章）
3. 用附件机制替代内联条件：类似模式三的 Agent 列表，将条件内容作为附件追加在消息尾部

这个模式没有单一的实现位置——它是一个设计原则，贯穿于系统提示词和工具提示词的构建过程中。其本质是确保 API 请求前缀中的系统提示词块在会话生命周期内保持单调稳定：内容要么始终存在，要么始终不存在，不会因外部条件翻转而出现/消失。

15.7 模式七：工具 Schema 缓存 getToolSchemaCache()

问题

工具 Schema 的序列化（toolToAPISchema()）是一个复杂过程，涉及多个运行时决策：

1. GrowthBook feature flag：tengu_tool_pear（strict mode）、tengu_fgts（fine-grained tool streaming）等 flag 控制 Schema 中的可选字段
2. tool.prompt() 的动态输出：部分工具的描述文本包含运行时信息
3. MCP 工具的 Schema：外部服务器提供的 Schema 可能在会话中途变化

每次 API 请求都重新计算工具 Schema 意味着：如果 GrowthBook 在会话中途刷新了缓存（这可能在任何时候发生），某个 flag 的值从 true 变为 false，工具 Schema 的序列化结果就会改变——缓存中断。

解决方案

// utils/toolSchemaCache.ts:1-27
// Session-scoped cache of rendered tool schemas. Tool schemas render at server
// position 2 (before system prompt), so any byte-level change busts the entire
// ~11K-token tool block AND everything downstream. GrowthBook gate flips
// (tengu_tool_pear, tengu_fgts), MCP reconnects, or dynamic content in
// tool.prompt() drift all cause this churn. Memoizing per-session locks the schema
// bytes at first render — mid-session GB refreshes no longer bust the cache.

type CachedSchema = BetaTool & {
  strict?: boolean
  eager_input_streaming?: boolean
}

const TOOL_SCHEMA_CACHE = new Map<string, CachedSchema>()

      // export function getToolSchemaCache(): Map<string, CachedSchema> {
  return TOOL_SCHEMA_CACHE
}

      // export function clearToolSchemaCache(): void {
  TOOL_SCHEMA_CACHE.clear()
}

TOOL_SCHEMA_CACHE 是一个模块级 Map，以工具名（或包含 inputJSONSchema 的复合键）为键，缓存完整的序列化 Schema。一旦工具的 Schema 在首次请求中被渲染并缓存，后续请求直接复用缓存值，不再调用 tool.prompt() 或重新评估 GrowthBook flag。

缓存键设计

缓存键的设计有一个细微但关键的考量（utils/api.ts，第147-149行）：

// utils/api.ts:147-149
const cacheKey =
  'inputJSONSchema' in tool && tool.inputJSONSchema
    ? `${tool.name}:${jsonStringify(tool.inputJSONSchema)}`
    : tool.name

大多数工具以名称为键——每个工具名称唯一，Schema 在会话内不变。但 StructuredOutput 工具是特例：它的名称固定为 'StructuredOutput'，但不同的工作流调用会传入不同的 inputJSONSchema。如果只用名称作为键，第一次调用缓存的 Schema 会在后续不同工作流中被错误复用。

源码注释提到了这个 bug 的严重性：

// StructuredOutput instances share the name 'StructuredOutput' but carry
// different schemas per workflow call — name-only keying returned a stale
// schema (5.4% → 51% err rate, see PR#25424).

错误率从 5.4% 飙升到 51%——这不是一个微妙的缓存一致性问题，而是一个严重的功能 bug。通过将 inputJSONSchema 包含在缓存键中解决了这个问题。

生命周期

TOOL_SCHEMA_CACHE 的生命周期与会话绑定：

• 创建：第一次调用 toolToAPISchema() 时逐工具填充
• 读取：后续每次 API 请求复用缓存的 Schema
• 清除：clearToolSchemaCache() 在用户登出时调用（通过 auth.ts），确保新会话不会复用旧会话的陈旧 Schema

注意 clearToolSchemaCache 被放在 utils/toolSchemaCache.ts 这个独立的叶子模块中，而非 utils/api.ts。注释解释了原因：

// Lives in a leaf module so auth.ts can clear it without importing api.ts
// (which would create a cycle via plans→settings→file→growthbook→config→
// bridgeEnabled→auth).

一个看似简单的缓存 Map，需要仔细的模块拆分来避免循环依赖——这是大型 TypeScript 项目中的常见挑战。

15.8 模式的共同本质

回顾这七个模式，下图展示了所有模式共同遵循的优化决策流程：

flowchart TD
    Start[识别动态内容] --> Q1{内容是否必须\n出现在前缀中?}
    Q1 -- 否 --> Move[移至消息尾部/附件]
    Move --> Done[缓存安全]

    Q1 -- 是 --> Q2{能否消除\n用户维度差异?}
    Q2 -- 是 --> Placeholder[使用占位符/标准化]
    Placeholder --> Done

    Q2 -- 否 --> Q3{能否降低\n变化频率?}
    Q3 -- 是 --> Reduce[记忆化/降低精度/会话级缓存]
    Reduce --> Done

    Q3 -- 否 --> Q4{能否限制\n变化幅度?}
    Q4 -- 是 --> Budget[预算控制/条件段落省略]
    Budget --> Done

    Q4 -- 否 --> Accept[标记为动态区域\nscope: null]
    Accept --> Done

    style Start fill:#f9f,stroke:#333
    style Done fill:#9f9,stroke:#333

图 15-1：缓存优化模式决策流程

可以提取出几个共性原则：

原则一：将动态内容推向请求尾部

API 请求的前缀匹配模型意味着：越靠前的内容，其变化的破坏性越大。因此：

• 日期记忆化（模式一）锁定系统提示词中的日期
• Agent 列表附件化（模式三）将动态列表从工具 Schema（前端）移到消息附件（尾部）
• 条件段落省略（模式六）确保前缀中的内容不抖动

原则二：降低变化频率

当内容必须出现在前缀中时，降低其变化频率是次优选择：

• 月度粒度（模式二）将日期变化从每日降到每月
• 技能列表预算（模式四）通过预算裁剪减少列表变化
• 工具 Schema 缓存（模式七）将变化频率从每请求降到每会话

原则三：消除用户维度的差异

全局缓存的前提是所有用户看到相同的前缀：

• $TMPDIR 占位符（模式五）消除了用户 UID 带来的路径差异
• 日期记忆化也间接服务于此——不同时区用户在同一时刻可能有不同日期

原则四：先测量，再优化

每一个模式的发现都依赖第14章的缓存中断检测系统：

• 10.2% cache_creation tokens 归因于 Agent 列表——这个数字来自 BigQuery 分析
• 77% 的工具变化是单个工具 Schema 变化——这驱动了工具 Schema 缓存的设计
• GrowthBook flag 翻转是中断原因——这驱动了会话级缓存的引入

没有可观测性基础设施，这些模式不会被发现。

用户能做什么

这些模式不仅适用于 Claude Code——任何使用 Anthropic API（或类似前缀缓存机制的 API）的应用都可以借鉴。

对 API 调用者的建议

1. 审计你的系统提示词：识别其中的动态内容（日期、用户名、配置值），将它们推到系统提示词的末尾或移至消息中
2. 锁定工具 Schema：工具定义在会话内应该保持不变。如果必须动态改变工具列表，考虑使用消息附件替代
3. 监控 cache_read_input_tokens：这是判断缓存是否正常工作的唯一指标。如果它在会话中意外下降，你就有了一个缓存中断
4. 理解前缀顺序：cache_control 断点之前的内容变化会废弃该断点的缓存。在请求构建时，将最稳定的内容放在最前面

常见陷阱

小结

本章介绍了 Claude Code 的 7 个缓存优化模式：

1. 日期记忆化：memoize(getLocalISODate) 消除跨天缓存击穿
2. 月度粒度：getLocalMonthYear() 将工具提示词的日期变化频率从每日降至每月
3. Agent 列表附件化：消除了 10.2% 的 cache_creation tokens
4. 技能列表预算：1% context window 的硬预算控制列表大小和变化
5. $TMPDIR 占位符：消除用户维度差异，启用全局缓存
6. 条件段落省略：确保前缀内容不因功能开关抖动
7. 工具 Schema 缓存：会话级 Map 隔离 GrowthBook 翻转和动态内容

这些模式共同体现了一个核心洞察：缓存优化不是一个独立的关注点，而是渗透到系统每一个产生动态内容的位置。从日期格式到路径字符串，从工具描述到 feature flag——任何“看起来不重要“的变化都可能导致成千上万 tokens 的缓存失效。Claude Code 的做法是将缓存稳定性视为一等公民，在每个产生动态内容的位置都显式地做出缓存友好的设计决策。

至此，第四篇“提示词缓存“完结。第13章建立了缓存架构的防御层（范围、TTL、锁存），第14章构建了检测能力（两阶段检测、解释引擎），第15章展示了进攻手段（7+ 优化模式）。三章共同构成了一个完整的缓存工程体系：防御 → 检测 → 优化。

下一篇将转向安全与权限系统——另一个需要系统性工程思维的领域。详见第16章。

第16章：权限系统

为什么这很重要

一个能在用户代码库中执行任意 Shell 命令、读写任意文件的 AI Agent，其权限系统的设计质量直接决定了用户信任的上限。过于宽松，用户面临安全风险——恶意 prompt 注入可能触发 rm -rf / 或窃取 SSH 密钥；过于严格，每一步操作都弹出确认对话框，AI 编码助手沦为一个“需要人类不断点确认“的自动化工具。

Claude Code 的权限系统试图在这两极之间找到平衡点：通过六种权限模式、三层规则匹配机制、以及一条完整的验证-权限-分类管线，实现“安全操作自动通过、危险操作必须人工确认、模糊地带由 AI 分类器裁决“的分级管控。

本章将完整剖析这一权限系统的设计与实现。

16.1 六种权限模式

权限模式（Permission Mode）是整个系统的最高层控制开关。用户通过 Shift+Tab 循环切换模式，或通过 --permission-mode CLI 参数指定。所有模式定义在 types/permissions.ts 中：

// types/permissions.ts:16-22
export const EXTERNAL_PERMISSION_MODES = [
  'acceptEdits',
  'bypassPermissions',
  'default',
  'dontAsk',
  'plan',
] as const

内部还有两个非公开模式——auto 和 bubble，组成完整的类型联合：

// types/permissions.ts:28-29
export type InternalPermissionMode = ExternalPermissionMode | 'auto' | 'bubble'
export type PermissionMode = InternalPermissionMode

以下是各模式的行为说明：

每个模式都有对应的配置对象（PermissionMode.ts:42-91），包含标题、缩写、符号和颜色键。值得注意的是 auto 模式通过 feature('TRANSCRIPT_CLASSIFIER') 编译时特性门控条件注册——外部构建中这段代码会被 Bun 的死代码消除完全移除。

模式切换的循环逻辑

getNextPermissionMode（getNextPermissionMode.ts:34-79）定义了 Shift+Tab 的循环顺序：

外部用户: default → acceptEdits → plan → [bypassPermissions] → default
内部用户: default → [bypassPermissions] → [auto] → default

内部用户跳过 acceptEdits 和 plan，因为 auto 模式替代了二者的功能。bypassPermissions 需要 isBypassPermissionsModeAvailable 标志为 true 才出现在循环中。auto 模式则需要同时满足功能门控和运行时可用性检查：

// getNextPermissionMode.ts:17-29
      // function canCycleToAuto(ctx: ToolPermissionContext): boolean {
  if (feature('TRANSCRIPT_CLASSIFIER')) {
    const gateEnabled = isAutoModeGateEnabled()
    const can = !!ctx.isAutoModeAvailable && gateEnabled
    // ...
    return can
  }
  return false
}

模式转换的副作用

模式切换不只是改变一个枚举值——transitionPermissionMode（permissionSetup.ts:597-646）处理了转换时的副作用：

1. 进入 plan 模式：调用 prepareContextForPlanMode，保存当前模式到 prePlanMode
2. 进入 auto 模式：调用 stripDangerousPermissionsForAutoMode，移除危险的 allow 规则（下文详述）
3. 离开 auto 模式：调用 restoreDangerousPermissions，恢复被剥离的规则
4. 离开 plan 模式：设置 hasExitedPlanMode 状态标志

16.2 权限规则体系

权限模式是粗粒度开关，权限规则（Permission Rule）则提供细粒度控制。一条规则由三个部分组成：

// types/permissions.ts:75-79
export type PermissionRule = {
  source: PermissionRuleSource
  ruleBehavior: PermissionBehavior    // 'allow' | 'deny' | 'ask'
  ruleValue: PermissionRuleValue
}

其中 PermissionRuleValue 指定目标工具和可选的内容限定：

// types/permissions.ts:67-70
export type PermissionRuleValue = {
  toolName: string
  ruleContent?: string    // 如 "npm install"、"git:*"
}

规则来源层级

规则有八种来源（types/permissions.ts:54-62），按优先级从高到低排列：

规则字符串格式与解析

规则在配置文件中以字符串形式存储，格式为 ToolName 或 ToolName(content)。解析由 permissionRuleParser.ts 的 permissionRuleValueFromString 函数（第 93-133 行）完成，它处理了转义括号的问题——因为规则内容本身可能包含括号（如 python -c "print(1)"）。

特殊情况：Bash() 和 Bash(*) 都被视为工具级规则（无内容限定），等价于 Bash。

16.3 三种规则匹配模式

Shell 命令的权限规则支持三种匹配模式，由 shellRuleMatching.ts 的 parsePermissionRule 函数（第 159-184 行）解析为判别联合类型：

// shellRuleMatching.ts:25-38
export type ShellPermissionRule =
  | { type: 'exact'; command: string }
  | { type: 'prefix'; prefix: string }
  | { type: 'wildcard'; pattern: string }

精确匹配

规则字符串不包含通配符，命令必须完全一致：

前缀匹配（Legacy :* 语法）

以 :* 结尾的规则使用前缀匹配——这是向后兼容的遗留语法：