6 · 上下文治理阶梯 ★ 全文核心

6.1 Claude Code 的做法：五级流水线

每一次调用模型之前，消息历史要穿过一条固定顺序的流水线。顺序不是随意排的 —— 越便宜的越靠前。

下面这段是同一条流水线在源代码里的实际形态，附上每一级对应的函数名：

顺序为什么是这个顺序：源码里的一句注释

关于第 ④ 级为什么必须排在第 ⑤ 级之前，源代码里有一句精确的说明：

6.2 第 ① 级：工具结果预算与落盘

每个工具都在自己的定义里声明了一个 maxResultSizeChars（结果最大字符数）。超过这个上限的执行结果不会进上下文，而是：

1. 完整内容被写到磁盘上 tool-results/ 目录下的一个文件里
2. 模型收到的是一个 <persisted-output> 标签包裹的前 2000 字节预览 + 那个文件的路径
3. 如果模型确实需要看全文，它自己调 Read 工具去读那个文件

export const PREVIEW_SIZE_BYTES = 2000           // 预览多少字节
export const PERSISTED_OUTPUT_TAG = '<persisted-output>'   // 包裹用的标签
export const TOOL_RESULT_CLEARED_MESSAGE = '[Old tool result content cleared]'
                                                  // 内容被清空后的占位文字

claude-code/src/utils/toolResultStorage.ts

有意思的是，这个上限允许被设成 Infinity（无穷大，即永不落盘）。源码注释解释了为什么需要这个例外：

除了单条结果的上限，还有一个「每条消息的聚合预算」机制（源码里叫 ContentReplacementState）—— 防止模型一次并行发出 20 个搜索调用，每个的结果都在单条上限之内，但加起来爆掉。

6.3 第 ③ 级：缓存编辑 —— 全文最精彩的一处

这一节需要先理解第 1.8 节的提示词缓存。如果还不清楚，请回去读一遍再回来。

先看清楚这里的困境

目标很朴素：把上下文里那些没用了的旧工具结果删掉。比如 30 轮前读过的一个文件，模型早就用完那个信息了，那几千个 token 白占着。

但直接删有一个致命副作用：

Claude Code 的解法：让服务端在缓存里删

Anthropic 的接口提供了一个叫 cache_edits（缓存编辑）的能力。它的作用是：

回到失忆专家的类比：

代码上的实现流程是：

/**
 * Cached microcompact path - uses cache editing API to remove tool results
 * without invalidating the cached prefix.
 *
 * - Does NOT modify local message content
 *   (cache_reference and cache_edits are added at API layer)
 * - Uses count-based trigger/keep thresholds from GrowthBook config
 */
async function cachedMicrocompactPath(messages, querySource) {
  // 1. 扫出所有"可压缩工具"的调用 id
  //    只有这 8 种工具的结果允许被删：
  //    Read / Bash / Grep / Glob / WebSearch / WebFetch / Edit / Write
  const compactableToolIds = new Set(collectCompactableToolIds(messages))

  // 2. 按"用户消息"分组，把这些工具结果注册进状态机
  mod.registerToolResult(state, block.tool_use_id)
  mod.registerToolMessage(state, groupIds)

  // 3. 问状态机：该删哪些？（策略是保留最近 N 个，删掉更早的）
  const toolsToDelete = mod.getToolResultsToDelete(state)

  // 4. 生成 cache_edits 指令块，排队交给 API 层去拼进请求
  pendingCacheEdits = mod.createCacheEditsBlock(state, toolsToDelete)

  // 5. 消息原样返回 —— 本地什么都没变
  return { messages, compactionInfo: { pendingCacheEdits: {...} } }
}

claude-code/src/services/compact/microCompact.ts

注意第 1 步：只有 8 种特定工具的结果允许被删。这 8 种的共同特征是「结果是一次性的观察数据」—— 读了个文件、搜了个关键词、跑了个命令。模型消化完就不需要原文了。而其他工具（比如 TodoWrite 维护待办列表）的结果代表持续有效的状态，删掉会造成失忆。

删了多少 token？得等服务端告诉你

因为本地什么都没改，客户端不知道实际省了多少。所以「已压缩」的通知消息被推迟到 API 响应回来之后才发，用服务端返回的真实数字：

// query.ts，流式响应结束后
const usage = lastAssistant?.message.usage
const cumulativeDeleted = usage?.cache_deleted_input_tokens ?? 0
// ★ 这个字段是"累积的"（从会话开始到现在总共删了多少），
//   不是"本次删了多少"。所以要减去请求前抓的基线值
const deletedTokens = Math.max(0, cumulativeDeleted
                                  - pendingCacheEdits.baselineCacheDeletedTokens)
if (deletedTokens > 0) {
  yield createMicrocompactBoundaryMessage(..., deletedTokens, ...)
}

这带来一个副作用：存在一个短暂的「认知偏差窗口」。从「决定删除」到「响应回来」这几秒内，客户端对上下文大小的估算是偏高的（它按没删的算）。这也是为什么后面自动压缩的阈值检查里到处是手工补偿项。

反过来的那条路径：时间触发

还有一条逻辑完全相反的路径。如果距离上一条模型回复的时间间隔超过了阈值（比如用户去吃了顿饭，30 分钟后才回来）：

// 服务端缓存已经过期了，整个前缀无论如何都要重新处理 ——
// 那就在发请求之前先把旧工具结果清掉，缩小要重新处理的量。
// 此时跳过缓存编辑：缓存编辑的前提是缓存还热着，而我们刚确认它已经凉了。
const trigger = evaluateTimeBasedTrigger(messages, querySource)
...
const keepRecent = Math.max(1, config.keepRecent)   // ★ 至少留 1 条
const keepSet  = new Set(compactableIds.slice(-keepRecent))    // 保留最后几个
const clearSet = new Set(compactableIds.filter(id => !keepSet.has(id)))
// 直接把这些工具结果的 content 替换成 '[Old tool result content cleared]'

那个 Math.max(1, ...) 有一条很实在的注释：

6.4 第 ⑤ 级：自动摘要压缩的工程细节

阈值怎么定

export const WARNING_THRESHOLD_BUFFER_TOKENS = 20_000   // 警告线的缓冲量
export const ERROR_THRESHOLD_BUFFER_TOKENS   = 20_000   // 错误线的缓冲量

const warningThreshold = threshold - WARNING_THRESHOLD_BUFFER_TOKENS
const errorThreshold   = threshold - ERROR_THRESHOLD_BUFFER_TOKENS

claude-code/src/services/compact/autoCompact.ts

（20_000 是 JavaScript 里写 20000 的一种可读性写法，下划线只是千位分隔符，不影响数值。）

注意一个反直觉的设计：「硬阻断」只在自动压缩被关闭时才生效。

逻辑是这样的：自动压缩开着的时候，撞线了就自动压缩，没必要拦用户。只有当用户手动关掉了自动压缩，系统才需要预留 20,000 token 的空间 —— 因为用户可能想自己敲 /compact 命令手动压缩，而那个命令本身也要消耗上下文空间。如果不预留，用户就陷入「上下文满了 → 想手动压缩 → 但压缩命令自己也放不进去了」的死锁。

压缩本身是一次「分叉子智能体」调用

压缩这件事本身就是让模型做摘要，所以它需要调一次模型。Claude Code 用「分叉子智能体」（forked agent）的方式跑它 —— 也就是复制当前会话的状态开一个临时的子会话。

关键决定是：让这个分叉出来的子会话继承父会话的完整工具集。不是因为摘要需要用工具，而是为了让缓存的键值能匹配上，复用父会话已经建立好的缓存前缀（回顾第 5.3 节：工具清单是上下文前缀的一部分）。

这个决定带来了一个真实的生产问题，源码注释里连数字都留了：

解决方案是一段措辞极其强硬的前置指令：

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.
`

claude-code/src/services/compact/prompt.ts

译：「至关重要：只用文字回复。不要调用任何工具。
· 不要使用 Read、Bash、Grep、Glob、Edit、Write，或任何其他工具。
· 你已经在上面的对话里拥有了所需的全部上下文。
· 工具调用会被拒绝，并且会浪费掉你唯一的一次机会 —— 你会任务失败。
· 你的整个回复必须是纯文字：一个 <analysis> 块，后面跟一个 <summary> 块。」

三个提示词工程手法叠在一起用：

两段式输出：一块用完就扔的草稿纸

摘要指令要求模型先写 <analysis>（分析）块，再写 <summary>（摘要）块。而处理函数 formatCompactSummary() 会把 analysis 块整个剥掉，只把 summary 块放进上下文。

分析块具体要求模型按时间顺序逐段过一遍对话，并逐条识别：

• 用户明确提出的请求和意图
• 你（模型）是怎么应对这些请求的
• 关键决策、技术概念、代码模式
• 具体细节：文件名、完整的代码片段、函数签名

6.5 上下文真的超了之后：三级恢复瀑布

如果所有预防措施都失效，API 真的返回了 413（上下文过长），还有三级恢复：

第 ③ 步「明确不走结束钩子」，有一条专门的注释解释

请体会一下这个循环的形状。「结束前质量检查」这个功能本身完全合理 —— 它的作用是「如果模型的回答不合格，就把问题指出来让它重做」。但当失败原因是「上下文已经装不下了」时，这个功能会：

1. 看到一个失败的回复
2. 判定不合格，生成一段「你的回答有以下问题……」的反馈
3. 把这段反馈注入上下文 —— 上下文变得更长了
4. 重试 → 更超了 → 又失败 → 回到第 1 步

6.6 Hermes 的做法：把整条阶梯抽象成一个插座

Hermes 走了完全相反的路。它不定义流水线，而是定义一个可以被整体替换的抽象基类（回顾第 1.9 节：抽象基类是一份「插座标准」，规定接进来的东西必须提供哪些功能）。

class ContextEngine(ABC):                    # ABC = Abstract Base Class 抽象基类
    threshold_percent: float = 0.75          # 用到上下文窗口的 75% 就开始压缩
    protect_first_n:   int   = 3             # 开头保护 3 条消息（系统提示词之外）
    protect_last_n:    int   = 6             # 结尾保护 6 条消息

    # ↓ 下面三个标了 @abstractmethod，意思是"任何实现都必须提供这三个"
    @abstractmethod
    def update_from_response(self, usage) -> None: ...
        # 每次拿到模型响应后，用其中的用量数据更新自己的记账

    @abstractmethod
    def should_compress(self, prompt_tokens=None) -> bool: ...
        # 这一轮该压缩了吗？

    @abstractmethod
    def compress(self, messages, current_tokens=None, focus_topic=None,
                 force=False, memory_context="") -> List[Dict]: ...
        # 执行压缩，返回压缩后的新消息列表

    # ↓ 下面这些是可选钩子，默认实现都是安全的"什么都不做"
    def prune_tool_results_only(self, messages, current_tokens=None):
        return messages, 0                   # 不调模型的确定性裁剪
    def select_context(self, request_messages, ...): return None
    def on_turn_complete(self, messages, usage=None, **kw): return None
    def should_compress_preflight(self, messages): return False
    def get_tool_schemas(self): return []    # 引擎可以自带工具！
    def handle_tool_call(self, name, args, **kw): ...

hermes-agent/agent/context_engine.py

最精辟的一处设计：select 和 compress 是两个正交的动词

这是一个被真实误用逼出来的接口。故事是这样的：

1. 有第三方做了一个基于检索的上下文引擎 —— 它想每一轮都根据当前问题去检索最相关的历史片段
2. 但接口只提供了 should_compress() 和 compress()
3. 于是它只能骗系统：should_compress() 永远返回 True，把 compress() 当成「每轮回调」来用
4. 后果：一旦这个引擎的检索后端挂了，compress() 就会失败 —— 而系统以为「压缩失败了，上下文还是太长」，进入错误的恢复流程
5. Hermes 于是加了一个正经的每轮钩子 select_context()

select_context() 返回的列表只作用于本次请求，不写回持久化的对话记录。所以即使引擎选错了，也不会污染后续轮次。

还有一个对称的后置钩子 on_turn_complete()：轮次结束后观察实际发生了什么，更新自己的索引、路由状态、话题状态，让下一次 select_context() 能用上这些信息。选择（前）+ 观察（后）构成一个闭环。

Hermes 的缓存契约写得比 Claude Code 更明确

翻译成设计原则：插件钩子必须跑在所有校验器之前。这样插件返回的垃圾数据也过不了校验，不会污染到模型供应商。这是「不完全信任插件」的正确姿势 —— 你给了第三方替换整个上下文的权力，但你保留了最终的把关权。

6.7 两家横向对照