TL;DR

• Claude Code 用四级渐进式管线应对上下文膨胀：Snip → Microcompact → Context Collapse → Autocompact，从轻到重、从便宜到昂贵。
• 每级的目标都是在不丢失关键信息的前提下释放 token 空间，只有前面的级别不够用时才触发更重的级别。
• 管线之外，还有一个前置阶段（工具结果预算处理），在工具输出进入上下文之前就控制大小。
• Snip 和 Context Collapse 目前对外部用户不可用（ant-only / feature flag），外部用户实际运行的是：Microcompact → Autocompact。

重要概念澄清

本文分析的是 Claude Code 的上下文压缩机制——对话历史过长时，如何缩减已存在于上下文中的消息。

需要区分两个完全不同的阶段：

一、整体架构概览

1.1 为什么需要压缩？

长时间对话中，messages 数组会被逐渐填满：用户和模型的多轮对话、工具执行结果、附件注入（技能、记忆、文件状态）。当接近 LLM 的上下文上限（如 200K tokens）时，必须有机制在保留关键信息的前提下释放空间。

1.2 四级渐进式压缩架构

注意：第一级 Snip 是 Anthropic 内部特性，外部不可用。Context Collapse 受 feature flag 控制，目前对外部用户禁用。 外部用户实际运行的是两级管线：Microcompact → Autocompact。

执行顺序（每次向 API 发请求之前，按固定顺序执行）：

工具结果预算 → Snip → Microcompact → Context Collapse → Autocompact → 发 API 请求

二、第一级：Snip（模型主动删历史）

核心纠偏：Snip 不是系统按阈值自动截断头部、保留尾部 N 条的机制。 它是让模型自己用工具决定删哪些消息——系统只负责给消息打 ID 标签、在合适时机提醒模型、以及执行模型下达的删除指令。

可用性：这是 Anthropic 内部特性，外部公开版本的 Claude Code 不包含。

2.1 整体思路

Snip 要解决一个问题：对话历史里有些消息彻底没用了（已完成的中间步骤、读过的文件内容），但系统不知道哪些是"没用的"，只有模型自己知道。

解决方案：让模型主动"扔掉"它认为没用的消息。具体分三步：

1. 每条用户消息末尾打上一个短 ID 标签，让模型能引用它
2. 上下文增长时，系统提醒模型"你可以用 snip 工具删消息了"
3. 模型调用 snip 工具，传入要删除的 ID 列表，系统执行删除

2.2 Step 1：给消息打 ID 标签

每次给 API 发消息之前，系统会在特定用户消息的末尾追加一个短 ID 标签：

\n[id:k8f3z1]

打标签的前提条件：消息顶层 content 里存在 type: 'text' 的 block。满足这个条件的才打，不满足的跳过。

这个条件决定了实际上只有用户的真实输入（用户打的字）才会被打上 ID。原因是：

• 用户输入的 content 是字符串或带顶层 text block 的数组 → 会打
• toolresult 消息：发 API 前经过合并处理，顶层 sibling text block 会被塞进 toolresult 内部的 content 里，顶层不再有 text block → 不打
• 元消息（nudge、附件等 isMeta 消息）：直接跳过，不走打标签逻辑 → 不打
• assistant 消息：不在遍历范围内 → 不打

哪些消息有 ID：

追加位置：

• content 是字符串 → 直接拼在字符串末尾
• content 是 block 数组 → 拼在最后一个 text block 的 text 字段末尾（不新增 block）

发给 API 的消息示例：

ID 的生成：由消息内部 UUID 确定性派生（UUID 前 10 位十六进制 → 转 base36 → 取前 6 位）。同一条消息每次生成的 ID 始终相同，不单独存储，系统收到短码后反向计算找对应消息。

ID 打在用户真实输入上，不是偶然，而是设计意图：ID 代表的是一个"用户输入轮次"——从这条用户输入开始、到下一条用户输入之前的整段对话（包括这期间所有的 assistant 回复、tooluse、toolresult）。模型传入一个 ID，系统删除的是这整个段落，不是单条消息。这样 tooluse/toolresult 始终成对，不会产生孤儿。

2.3 Step 2：系统提醒模型（nudge）

系统不会主动替模型做删除决策，但会在适当时机提醒模型"可以删了"。

触发条件：距上一次 snip 执行、compact 执行、或上一次提醒，上下文增长了约 10K tokens 时触发一次提醒。

机制：以 <system-reminder> 包裹注入到当前轮次尾部，不破坏历史消息的前缀缓存。

NUDGE_TEXT 大意（闭源）：

2.4 Step 3：模型调用 snip 工具，系统执行删除

模型决定删消息时，以工具调用的形式发出请求：

系统收到后执行删除，并向磁盘的会话日志里追加一条内部标记记录（记录本次删了哪些消息的 UUID），用于会话恢复时重放删除操作。这条记录不会出现在发给 API 的 messages 数组里。

2.5 删除后 messages 数组的变化

删除前，发给 API 的 messages（注意：tool_result 消息没有 ID）：

snip 的删除粒度是整个用户输入轮次：模型传入 [id:aa1bb2]，系统删除从这条用户输入开始、到下一条用户输入之前的所有消息——包括其间的 assistant 回复、tooluse、toolresult。

模型调用 snip(["aa1bb2"]) 后：

[assistant] "实现如下：..."
[user] "继续写测试"              ← [id:gg7hh8]

关键特点：

• 删除粒度是用户输入轮次：从该条用户输入到下一条用户输入之前的所有消息整段删除
• 删的是任意位置，不限于头部（这是 snip 与 autocompact 最大的区别）
• 删后没有占位符或摘要，消息直接消失

2.6 哪些消息能删，哪些不能

2.7 Session Resume 时的处理

消息历史以 append-only 的方式存在磁盘上，被 snip 掉的消息记录仍然在磁盘里，不会被真正删除。

当用户重新打开会话时，系统读取磁盘上的 boundary 记录，重放删除操作：将记录的 removed_uuids 对应的消息从内存链表里摘除，并修复链表指针。

为什么需要修复指针：消息之间用 parentUuid 形成链表。被删除消息的后继消息的 parent 指针指向了已删除的节点，如果不修复，链在 gap 处断开。

修复方式：对每个 parent 指向已删除节点的消息，沿着已删除节点的 parent 链往前回溯，直到找到第一个未被删除的祖先，重新指向它。

2.8 与 Autocompact 的本质区别

三、第二级：Microcompact（微压缩）

Microcompact 的核心目标是清除已经没有价值的工具调用结果，释放 token 空间。不同于 Autocompact 用 LLM 生成摘要，Microcompact 不调用 LLM——它直接把旧的工具结果内容替换成占位符，或者通过 API 在服务端缓存里删除。

有三种独立的机制，各自独立触发、互不排斥，同一轮迭代中可能有多种同时生效：

3.1 机制一：基于时间的清理

场景：用户暂时离开，过一段时间回来继续工作。

触发条件：距上一条助手消息超过 60 分钟（可由后台配置调整，功能默认关闭）。

60 分钟这个值对应 Anthropic 提示词缓存的 TTL——普通缓存 5 分钟，开启 extended cache 后是 1 小时。超过缓存有效期后，旧的工具结果内容已经无法命中缓存，继续带着它们只是白白占用 token，不如直接清掉。所以触发阈值与 extended cache TTL 保持一致。

做什么：把历史工具结果的内容替换成占位符，只保留最近 5 个工具结果的真实内容。

被清理的工具只限于这几类：Read 文件、Bash/Shell、Grep、Glob、WebSearch、WebFetch、FileEdit、FileWrite。

变形前后（发给 API 的 messages）：

对缓存的影响：修改消息内容会破坏服务端的提示词缓存前缀——这是预期行为，因为用户已经离开很久，缓存本身已过期，释放 token 空间更重要。

3.2 机制二：缓存编辑（Cached Microcompact）

场景：活跃会话中，工具调用越积越多，但用户还在持续工作，不希望破坏缓存。

触发条件：工具调用数量达到某个阈值（后台动态配置，feature flag CACHED_MICROCOMPACT，ant-only）。

做什么：利用 Anthropic API 的 cache_edits 特性，在服务端缓存里原地删除旧的工具结果——本地 messages 数组内容不变，但服务端在处理请求时不再看到那些被删掉的工具结果内容。

关键设计：本地不动，服务端删。这样前缀缓存前面的部分完全不变，缓存继续命中，只是旧工具结果在服务端被"剪掉"了。

API 层面的体现：每次 API 请求的最后一条 user message 里会附带一个 cache_edits block：

服务端处理后，响应里会返回 cache_deleted_input_tokens，告知本次删了多少 token。这个 cache_edits block 在后续每轮请求里都要重新发送，以保持服务端缓存状态一致。

3.3 机制三：API 原生 Context Management

这是 Anthropic API 提供的原生上下文管理能力——在 API 请求参数里直接声明清理策略，服务端按策略自动执行，客户端不需要修改 messages 数组。

与前两种机制的关系：这不是 Claude Code 自己实现的逻辑，而是 Anthropic API 的服务端能力。Claude Code 只是在请求参数里声明策略，由 API 服务端执行。三种机制各自独立，可以同时生效——机制一改本地 messages，机制二操作服务端缓存，机制三由 API 服务端自行执行。

两类策略：

① 清理思维链（thinking blocks）：适用于开启了 extended thinking 的会话，把历史轮次的 thinking block 从服务端上下文里清除。外部用户也可用。

正常情况下保留所有 thinking：

空闲超过 1 小时（缓存已过期）时，改为只保留最后 1 个 thinking turn：

② 清理工具结果（ant-only）：仅 Anthropic 内部用户可用。

触发条件：input_tokens >= 180K，目标保留 40K token，即每次清掉约 140K。

整个 context_management 配置作为请求体的顶层参数发给 API，服务端看到后按策略执行，响应里体现为 token 数减少，本地 messages 不变。

3.4 三种机制对比

四、第三级：Context Collapse（工具调用折叠）

可用性：受 feature flag CONTEXT_COLLAPSE（环境变量 CLAUDE_CONTEXT_COLLAPSE）控制，目前对外部用户禁用。启用后会完全禁用 Autocompact（防止两者竞争）。

4.1 两层含义

Context Collapse 这个名字在 Claude Code 里有两层含义，经常被混淆：

第一层：UI 显示折叠——把连续的 Read/Grep/Glob 工具调用在界面上折叠成一行，纯视觉效果，messages 数组不变。

❯ Searched 8 patterns, read 12 files, listed 3 directories

第二层：上下文投影压缩——本章讨论的核心机制。把已完成的工具调用组生成简洁摘要，在发 API 之前通过投影减少实际发出去的 token。

4.2 核心设计：读时投影（Read-time Projection）

与 Autocompact 的"写时替换"不同，Context Collapse 采用读时投影：

• 原始消息始终保留在内存和磁盘中，不删不改
• 每次向 API 发请求时，通过投影函数计算"当前视图"——把已提交的消息段落替换为摘要
• 好处：可逆、可审计，session resume 时只需重放提交记录就能重建投影

4.3 可折叠序列的识别

系统把连续的"搜索/读取类"工具调用识别为一个可折叠序列。

可折叠的工具：

• 内置：Grep、Glob、Read、Bash（仅搜索/读取类）、WebSearch、WebFetch、REPL、Memory 操作
• MCP 工具中分类为搜索/读取的（约 150+ 种）

序列断开条件——遇到以下任一情况，当前序列结束：

• 助手输出文本内容（不只是 tool_use）
• Edit / Write / SendMessage 等状态变更工具
• 用户新消息
• 任何非搜索/读取类工具

序列一旦被识别，就进入暂存队列，等待后续提交。暂存本身不改变任何东西——消息照常发给 API。

4.4 触发与提交：完整生命周期

Context Collapse 有两个阈值（基于有效窗口 180K）：

90% vs 95% 的区别：

• 90%：即时完成，不调 LLM。摘要是规则生成的——数一下工具调用次数，产出 "Searched 2 patterns, read 1 file" 这样的计数摘要。
• 95%：阻塞主对话，派生子 agent 用 LLM 对同样的工具序列生成语义摘要（如 "用户在调试认证模块，搜索了 handleAuth 和 middleware 相关代码，读取了 auth.go 全文"）。压缩比更高，但需要 LLM 调用。

两者的压缩范围相同——都只替换可折叠的工具调用序列，不动对话文本本身。这是和 Autocompact（全量压缩整个对话历史）的本质区别。

167K（autocompact 阈值）在 Collapse 开启时被跳过：因为 Collapse 在 90%（162K）就开始管理上下文，如果 autocompact 在 93%（167K）又介入，两者会打架——collapse 刚提交完降下来，autocompact 又全量压缩掉，collapse 保留的原始消息全白费。所以启用 collapse 时直接禁用 autocompact 的主动触发。

完整生命周期示例：

4.5 降级路径总结

90% commit（规则摘要）→ 95% ctx-agent（LLM 摘要）→ 413 drain → reactive compact（兜底）

每一级比上一级更重、更贵，但也能处理更极端的情况。前两级只折叠工具序列不动对话文本；reactive compact 作为最终兜底，等同于全量 autocompact，会把整个历史替换为结构化摘要。

4.6 变形前后：投影效果

变形前（原始 messages，6 条）：

投影后（发给 API 的 messages，1 条摘要替换了中间 6 条）：

原始消息保留在磁盘上不动，投影是每次发请求时实时计算的。

4.7 持久化与 Session Resume

归档信息以 append-only 的方式持久化到磁盘：

• Commit 记录：每次提交时写入，包含被折叠的消息范围和摘要内容
• Snapshot 记录：记录当前暂存队列的状态

Session resume 时，系统重放 commit 记录，重建投影——因为投影是确定性的，同样的 commit 记录总能产生同样的视图。

与 compact boundary 的交互：如果 reactive compact 最终触发并写入 boundary marker，之前所有的 collapse commit 和 snapshot 记录被逻辑废弃（因为它们引用的消息已经在 boundary 之前）。

4.8 与 Autocompact 的关系

禁用的是"主动 autocompact"，不是"被动 reactive compact"。

具体来说：

• 被禁用：每轮迭代开始时的"token 数超 167K → 触发 autocompact"这条主动检查路径
• 不被禁用：API 返回 413 后的 reactive compact 兜底路径

原因：Context Collapse 在 90% 就开始工作，主动 autocompact 在 92.8%（167K/180K）触发，两者阈值太近会竞争——collapse 刚提交完降下来，autocompact 又检测到超阈值想全量压缩，造成混乱。所以主动路径二选一。但 413 兜底必须保留，否则 collapse 无法处理的场景（全是不可折叠的对话文本）会导致会话卡死。

Context Collapse 的优劣势：

• 优势：增量、可逆、绝大多数情况不需要 LLM 调用、不会丢失信息（原始消息留存）
• 劣势：只能折叠搜索/读取类工具调用，对话文本本身的膨胀无法处理（最终需要 reactive compact 兜底）

五、第四级：Autocompact（自动压缩）

当 messages 数组的 token 数接近模型上限时，系统自动把前面的历史压缩成一条结构化摘要，释放空间让对话继续。

5.1 触发时机

Autocompact 的检查点在每轮迭代开始、向 API 发请求之前，不是实时监控 token 数。

具体场景举例（200K 窗口，触发点 167K）：

每次向 API 发请求之前都会检查，包括模型在任务进行中发出的每一次工具调用请求。所以压缩可以在任务还在跑时触发，不需要等用户发新消息：

各阈值的含义（200K 窗口示例）：

20K 摘要输出预留：压缩时要调用子模型生成摘要，子模型需要输出 token 空间。实测摘要 p99.99 输出是 17,387 token，预留 20K。如果不留这个空间，压缩时子模型会因为输出空间不足而失败。

13K 提前量：messages 的 token 估算不是精确值，可能比实际偏低；提前 13K 触发确保压缩后有足够空间继续工作，不会压完立刻又超。

3K blocking 缓冲：autocompact 关闭或失败时，还有 3K 空间让用户手动执行 /compact。

有两条触发路径：

路径一：主动检查（每轮迭代开始，如上所述）

路径二：被动触发（API 返回 413 之后） 主动检查没触发，但发出去的请求被 API 拒绝（prompt too long）。这时走 Reactive Compact：

• 先尝试 Context Collapse drain（如果该功能启用）
• 不够的话，调用完整压缩
• 压缩完重新发请求

5.2 压缩做了什么

触发后，当前对话立即暂停，系统 fork 出一个子模型来生成摘要，主对话等待子模型完成后才继续。整个过程是同步的。

子模型收到什么：当前完整的 messages 数组（图片被剥离），加上一条 user message 形式的摘要 prompt（见 5.3）。

子模型只跑 1 轮，不允许调用任何工具，产出摘要文本后退出。

压缩后 messages 变成（全量替换，没有任何原始消息保留）：

然后用这个新的 messages 数组继续当前轮次，向 API 发请求。用户还没发新消息，模型继续完成手头的任务。

注意：autocompact 是全量压缩，触发时的 tool_result 内容被压进摘要里，不会单独保留在外面。

5.3 摘要生成的 prompt

子模型收到的最后一条 user message 内容（不是 system prompt）：

子模型产出摘要后，系统剥离 <analysis> 部分（只是生成时的草稿），把 <summary> 里的内容格式化成上面 5.2 里的那条 user message。

5.4 压缩后的状态恢复

压缩把所有历史消息替换成了摘要，模型因此"忘记"了之前读过的文件内容。系统需要把关键状态重新注入。

恢复策略是按预算重新注入：

• 文件：最多恢复 5 个最近读过的文件，单文件限 5K token，总预算 50K token
• Skill：单个 skill 限 5K token，总预算 25K token
• Plan 文件、PlanMode 状态、Delta 附件：无单独预算限制，直接注入

文件选择优先级：按最近读取时间排序，超出预算的直接丢弃（不截断）。

5.5 失败处理与安全机制

层级一：PTL Retry（compact 内部自救）

compact 把当前所有消息发给子模型生成摘要，但如果消息本身太大，连这个请求也超限（prompt too long），compact 会截掉最旧的消息重试。

消息分组方式：按 API round 分组——以 assistant 消息的 response ID 为边界，每次 API 调用对应一个 group。tooluse 和对应的 toolresult 在同一个 group 里，配对完整。

裁切逻辑：

1. 从最旧的 group 开始丢，累积直到覆盖超限的 token 数（拿不到精确数字时丢掉 20% 的 group）
2. 剩余消息展平为一个数组
3. 如果第一条是 assistant（role 不合法），在头部补一条合成 user message：[earlier conversation truncated for compaction retry]
4. 用截断后的消息重试，最多重试 3 次

截断是有损的——被丢掉的 group 里的历史不会出现在摘要里，但至少能解除卡死。3 次都失败则抛出错误，走外层熔断器。

层级二：熔断器（circuit breaker）

compact 抛出错误时，外层记录失败次数，成功则重置为 0。连续失败 3 次后，后续轮次直接跳过 compact，不再尝试。

失败后当前轮次不中断，用原来未压缩的 messages 继续发请求。

这个机制因真实事故而加入：曾有 1279 个会话连续失败 50 次以上（最高 3272 次），每天全球浪费约 25 万次 API 调用。

层级三：blocking limit 兜底

熔断后 compact 不再触发，但 token 继续累积。到 177K（有效窗口 - 3K）时，系统拒绝发 API 请求，对话停止，需要用户手动 /compact 或放弃会话。

这 3K 缓冲就是留给用户手动操作的空间。

六、完整执行流程汇总

每次向 API 发请求之前，系统按固定顺序依次执行各压缩机制。以下用一个具体场景走一遍完整流程。

场景：用户让模型分析一个项目，模型连续执行了多轮工具调用，累计消耗了 170K token。

本轮迭代开始（准备向 API 发下一次请求）：

Step 1：工具结果预算控制

检查刚产生的工具结果大小。单条超 50K 字符的，把内容存到磁盘，消息里换成"已保存到 /path/to/file"；所有工具结果合计超 200K 字符的，选最大的几条替换，直到总量达标。

这步不是压缩，是防止单次工具调用输出把窗口撑爆。

Step 2：Snip（ant-only，外部用户跳过）

如果 Snip 功能启用，模型可能在上一轮调用了 snip 工具指定删除某些历史 user input 轮次。这里执行那些删除，更新 messages 数组。

Step 3：Microcompact

检查是否满足微压缩条件：

• 距上次工具调用已超过 60 分钟？→ 把旧工具结果内容替换成 [Old tool result content cleared]，只保留最近 5 个
• 工具调用数量达到阈值？→ 通过 cache_edits 在服务端缓存里删除旧工具结果，本地 messages 不变

Step 4：Context Collapse（feature flag 控制，外部用户跳过）

如果 Context Collapse 启用：

• 检查上下文利用率是否达到 90%（162K）→ 提交所有已暂存的可折叠序列
• 对发出去的 messages 做投影（把已提交的序列替换成摘要消息）
• 如果达到 95%（171K）→ 派生子 agent 生成更优质摘要

Step 5：Autocompact 检查（Context Collapse 启用时跳过此步）

检查当前 messages token 数是否超过触发阈值（167K）。

本场景是 170K > 167K，触发 Autocompact：

1. 暂停当前轮次
2. Fork 子模型，把当前所有 messages + 9 段摘要 prompt 发过去
3. 子模型生成摘要（最多 20K token 输出），剥离 <analysis> 草稿块
4. 用摘要 + 重新注入的文件/attachments 替换全部历史消息（约 60K token）
5. 用新的 messages 数组继续当前轮次，向 API 发请求

如果 Autocompact 不触发（token 未超阈值）：直接向 API 发请求。

整体顺序总结：

工具结果预算 → Snip → Microcompact → Context Collapse → Autocompact → 发 API 请求

注意：Context Collapse 和主动 Autocompact 是互斥的（启用 collapse 则跳过 autocompact 的主动检查），但 API 返回 413 时的 reactive compact 仍然可用作最终兜底。

前几步越来越重，目的是尽量在轻量级机制就把 token 降下来，只有前几步都不够用时才走全量 Autocompact。Autocompact 成功后，后续轮次从约 60K 重新开始积累，直到再次触发。

七、关键设计原则总结

7.1 渐进式降级

7.2 缓存一致性优先

关键原则：

"Once a tool result is seen by the model (whether full content or replacement preview), this decision must remain consistent across all subsequent API calls."

实现为三态分区：

• mustReapply：之前已替换过的，必须在后续请求中重新应用同样的替换
• frozen：之前模型看过完整内容的，现在不可再替换（否则模型会困惑）
• fresh：本轮新增的，可被选中进行替换

7.3 熔断保护

连续失败 3 次后跳过 compact，不再尝试。

原则：宁可让用户手动执行 /compact，也不要用注定失败的重试浪费 API 预算。

7.4 预算分配思维

压缩后的恢复不是"越多越好"，而是严格的预算分配：

总计约 75K，为后续对话留出 100K+ 空间。

附录：工具结果预算处理（前置阶段）

注意：这不是上下文压缩的一部分，而是工具执行后的结果处理阶段。放在这里是为了与压缩管线做明确区分。

A.1 执行时机

A.2 两级闸门机制

A.3 消息分组（用于 200K 限制计算）

200K 字符限制是按消息组计算的。分组方式：同一轮次的所有并行 tool_result 被视为一个组。

分组边界由 assistant 消息的 ID 决定——同一轮 API 调用（同一个 assistant message ID）产生的所有 tooluse 对应的 toolresult，属于同一个组。

A.4 与上下文压缩的关系