Claude Code架构——上下文压缩(03):六层分级管线全解析

本文深入解析Claude Code的六层上下文压缩管线,涵盖工具结果裁剪、snip局部裁剪、microcompact微压缩、context collapse折叠、autocompact结构化摘要及reactive compact反应式补救。各层按成本与信息损失递增设计,强调推迟信息损失、保留结构、支持恢复与prompt cache协同。核心目标是在长任务中维持有效上下文,而非依赖大窗口。

⏱ 约 9 分钟读完 ✍️ 4348 字

引言:长任务靠的不是大窗口,而是分级压缩

Claude Code 能连续干几小时的工程任务,靠的是一条六层的上下文压缩管线,而不是“快满了就做一次摘要”。

它的工作方式决定了上下文一定会膨胀:读文件、搜代码、跑 Bash、写补丁、调子 Agent,每一步都在往历史里追加消息和工具输出。真正占空间的往往不是对话,而是大段的终端日志和文件内容。

它的系统提示词也直接告诉模型:对话接近上限时,系统会自动压缩早期消息,上下文因此“近似无限”。这说明压缩是基础设施,不是补丁。

整套设计可以概括为一个原则:尽量推迟信息损失。能局部裁剪就不做全局摘要,能折叠视图就不合并历史,主动手段失败了还有报错后的恢复。

全景:六层压缩管线

主入口在 query.ts。每次向模型发请求之前,消息依次经过 5 层处理,每层只在自己的条件满足时动手;第 6 层只在请求被拒之后出场。

前 4 层都不调用模型做全局摘要,尽量保留结构;第 4 层故意排在第 5 层前面,折叠够用就不需要摘要。简化后的调用顺序如下:

messagesForQuery = await applyToolResultBudget(...)          // 1
messagesForQuery = snipCompactIfNeeded(messagesForQuery)      // 2
messagesForQuery = await microcompact(messagesForQuery, ...)  // 3
messagesForQuery = await applyCollapsesIfNeeded(...)          // 4
const { compactionResult } = await autocompact(...)           // 5
// … 请求模型,413 时走 tryReactiveCompact()               // 6

第 1 层:工具结果预算裁剪

这一层先把超大的工具输出移出上下文,只留一个预览和文件路径。

  • 何时触发:每次请求前都执行 applyToolResultBudget,检查单条工具结果是否超出该工具的大小上限。
  • 压缩什么:只处理超大输出,例如长篇 Bash 日志、大文件内容、大量搜索结果。
  • 怎么省:大结果存到磁盘,模型只拿到预览和路径。原文没有丢,模型需要时可以按路径再读。
  • 例外:maxResultSizeChars 不是有限值的工具会被单独挑出,不套用这套预算。

把它放在最前面的理由很简单:低价值的大文本如果不先处理,后面每一层都会被它拖累。可以理解成“大件行李先寄存,手里只留取件单”。

第 2 层:snip

snip 是轻量的局部裁剪,它的实现不公开,但输出和用法在调用方代码里看得很清楚。

  • 何时触发:每次请求前由 snipCompactIfNeeded 判断是否需要,受 HISTORY_SNIP 开关控制,目前仅内部启用。
  • 压缩什么(推测):社区分析认为它清除“僵尸消息”和过时标记,或裁掉历史中段较旧的消息。速度快,但有损。
  • 返回什么:新的消息数组、释放的 token 数 tokensFreed,必要时还有一条边界消息。

最值得注意的是它和第 5 层的联动。tokensFreed 会作为 snipTokensFreed 传给 shouldAutoCompact。autocompact 判断是否超阈值时会把这部分扣掉,避免“已经省过了还去做摘要”。

第 3 层:microcompact:微压缩

microcompact 只清理旧的工具结果,不碰用户和助手的对话,也不调用模型。

可压缩的工具由 COMPACTABLE_TOOLS 限定:Read、Bash(Shell)、Grep、Glob、WebSearch、WebFetch、Edit、Write。其他工具的结果不动。

它按服务端 prompt cache 的冷热分两条路径:

路径触发条件做法代价
基于时间(缓存已冷)主线程会话,距上一条 assistant 消息超过 gapThresholdMinutes保留最近 N 个工具结果,其余内容替换为 [Old tool result content cleared]占位符下次请求重建缓存,反正缓存已过期
cached MC(缓存还热)按 tool_use_id 登记并追踪工具结果用缓存编辑 API 在服务端删除旧工具结果,本地消息不变缓存前缀不失效

几个细节:

  • 时间路径优先。它先执行,一旦触发就跳过 cached MC,因为缓存编辑以缓存是热的为前提。
  • 至少保留 1 条。keepRecent 有下限 1:一是 slice(-0) 会返回整个数组;二是全清空会让模型完全失去工作上下文。
  • 结构保留。工具调用本身还在,模型知道自己“读过哪个文件、跑过哪条命令”,只是看不到旧输出。需要时可以重新读。

第 4 层:context collapse:上下文折叠

context collapse 不删除任何原始消息,只在发请求前临时把一段旧消息换成摘要占位符。模型看到的是“折叠视图”,完整记录仍在 REPL 数组和磁盘 JSONL 里。它受 CONTEXT_COLLAPSE 开关控制,尚未完全上线。

可以类比数据库视图:底层表一行不改,查询时返回转换后的结果。也像编辑器里折叠一个函数:代码还在,只显示成一行。

如何折叠

  1. 记录提交。每次折叠写一条 commit,记下被折叠区间的起止消息 UUID(firstArchivedUuid / lastArchivedUuid)和摘要文本。
  2. 读时投影。每次请求前 projectView() 重放提交日志,把对应区间替换成占位符。社区分析给出的占位符形如 [Previous conversation: 2 user exchanges, 3 assistant responses. 5 tool calls, 2 files read.]。
  3. 先暂存再提交。可折叠的区间先进入 staged 队列,上下文压力到阈值时才正式 commit,提交时按风险分数从高到低挑选。

持久化

  • commit 是 append-only 的,恢复时全部回放;snapshot 保存 staged 队列,以最后一次写入为准。
  • 被折叠的原文不重复存储,它们本来就在 transcript 里;只存边界 UUID 和摘要占位符。

第 5 层:autocompact

autocompact 是唯一主动调用模型的一层:用量超过约 83.5% 窗口时,把旧历史写成一份 9 段结构化摘要。代码位于 services/compact/ 下的 autoCompact.ts、compact.ts、prompt.ts。

① 阈值怎么算

以 200K 窗口为例:

量算法结果
有效窗口窗口 − min(最大输出, 20K)180K
自动压缩阈值有效窗口 − 13K(AUTOCOMPACT_BUFFER_TOKENS)167K,约 83.5%
手动 /compact 阻塞线有效窗口 − 3K177K

20K 是给摘要输出留的空间,参考的是摘要输出长度的 p99.99(约 17,387 token)。13K 是安全缓冲,保证生成摘要这一步本身不会溢出。

② 压缩前预处理

  1. 执行 PreCompact hooks,让扩展有机会检查或修改。
  2. 把图片替换成 [image] 标记。
  3. 移除压缩后会重新注入的附件(如 skill 列表)。

③ 生成 9 段摘要

fork 出一个 agent,把完整历史加上摘要提示词发给同一个模型,流式返回后取出 <summary> 块。提示词要求摘要包含固定段落,其中最关键的是:

  • 用户的主要意图和具体要求
  • 关键技术概念
  • 涉及的文件和代码段(带完整代码片段,并说明为什么重要)
  • 遇到的错误和修复方式
  • 解题进展与待办工作

提示词还提供一个 <analysis> 草稿区让模型先理清思路,最终摘要里会把它剥掉,提升质量又不占压缩后的 token。

④ 失败处理

  • 压缩请求本身超长:截掉最老的几轮 API 往返再重试,次数有限。
  • 熔断:连续失败 3 次后停止自动压缩,避免死循环。

⑤ 重建消息链并恢复工作上下文

buildPostCompactMessages 生成新的消息链:boundary 标记 + 摘要 + 后续消息,并替换主循环里的 messagesForQuery。

光有摘要,模型压缩完马上又要重读文件,所以会主动补回一部分:

补回内容预算
最近读过的文件最多 5 个,每个 5K,共 50K token
调用过的 skill每个 5K,共 25K token
计划文件存在就补回
Plan mode 指令处于 plan mode 时补回

经验上,压缩后的上下文大约在 30–60K token,从 167K 降下来后又有了大量余量。

第 6 层:reactive compact

reactive compact 不在请求前运行,而是在 API 已经拒绝请求之后补救,受 REACTIVE_COMPACT 开关控制。

触发条件有两类:

  • prompt too long,即 413 请求过大;
  • 媒体内容过大,如图片、PDF、多图输入。

恢复顺序按代价从小到大:

  1. 先扣住错误。主循环把可恢复的错误从输出流里扣下(withhold),不立刻展示给用户。
  2. 排空折叠。如果启用了 context collapse,先调用 recoverFromOverflow() 把暂存的折叠一次性提交。只要提交数大于 0,就用折叠后的上下文直接重试。
  3. 反应式压缩。还不够,就调用 tryReactiveCompact() 激进地压缩后重试。有分析认为它是从尾部剥离消息,而不是做完整摘要,具体做法未公开。
  4. 仍失败就放弃。把错误展示给用户。

传给 tryReactiveCompact 的参数也很说明问题:

  • hasAttempted:记录本轮是否已经尝试过,保证只救一次,避免“压缩 → 还超长 → 再压缩”的死循环。
  • aborted:用户已中断时不再恢复。
  • cacheSafeParams:携带与正常请求相同的 system prompt 和上下文,推测是为了让压缩请求尽量命中现有 prompt cache。

它的价值在于:一次意外的超大工具输出不会把整个会话弄死,用户通常察觉不到这次失败。

compact_boundary 与会话恢复

压缩不只发生在内存里,还会写进会话记录,影响 /resume 恢复。关键是一条 subtype 为 compact_boundary 的系统消息。

它不是界面提示,而是会话链上的锚点,负责三件事:

  1. 标出哪一段历史已经被总结掉。
  2. 通过 compactMetadata.preservedSegment.tailUuid 记住哪些片段要原样保留。
  3. 给恢复逻辑一个重新拼接的位置。

压缩后的会话大致是这样的结构:

压缩前:[旧] [旧] [旧] [旧] [旧] [留] [留] [留]
压缩后:[摘要] | compact_boundary | [保留段原文] [后续新消息]

/resume 时,sessionStorage.ts 的 applyPreservedSegmentRelinks() 把保留段重新接回消息链。多次压缩时只重新链接最后一个边界,因为更早的边界内容已经被总结进了后一次摘要。

context collapse 的提交记录(contextCollapseCommits)和快照(contextCollapseSnapshot)也在这里一起恢复,必须在第一次查询之前完成,否则折叠视图无法重建。

这就是 Claude Code 的会话存储比普通聊天产品复杂得多的原因:它不是“用一段摘要替换前文”,而是摘要、保留段、折叠记录三者并存。

与 Prompt Cache 的协同

压缩的目标不只是“变短”,还要尽量不破坏 prompt cache,因为缓存命中直接决定成本和延迟。

静态与动态的分界。constants/prompts.ts 里有一个常量 SYSTEM_PROMPT_DYNAMIC_BOUNDARY:

  • 标记之前的 system prompt 是静态内容,可以全局缓存;
  • 标记之后是用户或会话相关内容,不缓存。

压缩层对缓存的照顾体现在好几处:

  • microcompact 在缓存还热时用缓存编辑 API 删内容,不让前缀失效;只有缓存已冷时才直接改消息。
  • autocompact 和 reactive compact 的压缩请求都沿用正常请求的 system prompt 和上下文(cacheSafeParams),让摘要调用也能复用缓存。
  • 压缩后会做缓存状态重置和记忆文件重新加载(postCompactCleanup.ts)。

所以整体策略是两条线并行:静态部分靠缓存省钱,动态历史靠分层压缩控制长度。

总结与设计启示

六层压缩的规律是:越往后越贵、丢失的信息越多,所以只有前面不够用时才升级。

层何时触发处理对象调用模型信息损失
1 预算裁剪每轮,单条结果超限超大工具输出否很小,全文在磁盘
2 snip每轮,条件未公开过时或较旧的消息否小
3 microcompact缓存冷时按时间间隔;缓存热时按 tool_use_id旧工具结果否小,结构保留
4 collapse每轮投影,压力到阈值时提交较早的对话段推测用于生成分段摘要中,可恢复
5 autocompact约 83.5% 窗口或手动 /compact边界前整段历史是大,会补回关键文件
6 reactiveAPI 报 413 或媒体过大整段内容未公开大,最后手段

如果你在做自己的 Agent,可以直接借鉴这几点:

  1. 先处理工具输出。大部分膨胀来自工具结果,存磁盘留路径、用占位符替换旧结果,成本几乎为零。
  2. 压缩分级。从便宜、可逆的手段开始,把全局摘要留到最后。
  3. 摘要要有结构。用固定段落保住意图、文件、错误和待办,并在压缩后补回最近的文件。
  4. 给失败留后路。报错后先扣住错误、尝试恢复一次;连续失败就熔断。
  5. 让压缩可恢复。用边界标记和提交日志记录压缩,会话重启后能重建。
  6. 顾及缓存。压缩时尽量不动已缓存的前缀。

把 Claude Code 看成“模型 + 工具”会低估它。真正让它能持续完成复杂工程任务的,是这套运行时级别的上下文内存管理。


本文首发于 CSDN:Claude Code架构——上下文压缩(03):六层分级管线全解析