引言:长任务靠的不是大窗口,而是分级压缩
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 开关控制,尚未完全上线。
可以类比数据库视图:底层表一行不改,查询时返回转换后的结果。也像编辑器里折叠一个函数:代码还在,只显示成一行。
如何折叠
- 记录提交。每次折叠写一条 commit,记下被折叠区间的起止消息 UUID(
firstArchivedUuid/lastArchivedUuid)和摘要文本。 - 读时投影。每次请求前
projectView()重放提交日志,把对应区间替换成占位符。社区分析给出的占位符形如[Previous conversation: 2 user exchanges, 3 assistant responses. 5 tool calls, 2 files read.]。 - 先暂存再提交。可折叠的区间先进入 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 阻塞线 | 有效窗口 − 3K | 177K |
20K 是给摘要输出留的空间,参考的是摘要输出长度的 p99.99(约 17,387 token)。13K 是安全缓冲,保证生成摘要这一步本身不会溢出。
② 压缩前预处理
- 执行 PreCompact hooks,让扩展有机会检查或修改。
- 把图片替换成
[image]标记。 - 移除压缩后会重新注入的附件(如 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、多图输入。
恢复顺序按代价从小到大:
- 先扣住错误。主循环把可恢复的错误从输出流里扣下(withhold),不立刻展示给用户。
- 排空折叠。如果启用了 context collapse,先调用
recoverFromOverflow()把暂存的折叠一次性提交。只要提交数大于 0,就用折叠后的上下文直接重试。 - 反应式压缩。还不够,就调用
tryReactiveCompact()激进地压缩后重试。有分析认为它是从尾部剥离消息,而不是做完整摘要,具体做法未公开。 - 仍失败就放弃。把错误展示给用户。
传给 tryReactiveCompact 的参数也很说明问题:
hasAttempted:记录本轮是否已经尝试过,保证只救一次,避免“压缩 → 还超长 → 再压缩”的死循环。aborted:用户已中断时不再恢复。cacheSafeParams:携带与正常请求相同的 system prompt 和上下文,推测是为了让压缩请求尽量命中现有 prompt cache。
它的价值在于:一次意外的超大工具输出不会把整个会话弄死,用户通常察觉不到这次失败。
compact_boundary 与会话恢复
压缩不只发生在内存里,还会写进会话记录,影响 /resume 恢复。关键是一条 subtype 为 compact_boundary 的系统消息。
它不是界面提示,而是会话链上的锚点,负责三件事:
- 标出哪一段历史已经被总结掉。
- 通过
compactMetadata.preservedSegment.tailUuid记住哪些片段要原样保留。 - 给恢复逻辑一个重新拼接的位置。
压缩后的会话大致是这样的结构:
压缩前:[旧] [旧] [旧] [旧] [旧] [留] [留] [留]
压缩后:[摘要] | 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 reactive | API 报 413 或媒体过大 | 整段内容 | 未公开 | 大,最后手段 |
如果你在做自己的 Agent,可以直接借鉴这几点:
- 先处理工具输出。大部分膨胀来自工具结果,存磁盘留路径、用占位符替换旧结果,成本几乎为零。
- 压缩分级。从便宜、可逆的手段开始,把全局摘要留到最后。
- 摘要要有结构。用固定段落保住意图、文件、错误和待办,并在压缩后补回最近的文件。
- 给失败留后路。报错后先扣住错误、尝试恢复一次;连续失败就熔断。
- 让压缩可恢复。用边界标记和提交日志记录压缩,会话重启后能重建。
- 顾及缓存。压缩时尽量不动已缓存的前缀。
把 Claude Code 看成“模型 + 工具”会低估它。真正让它能持续完成复杂工程任务的,是这套运行时级别的上下文内存管理。
本文首发于 CSDN:Claude Code架构——上下文压缩(03):六层分级管线全解析