第 6 章 · M6 上下文管理与压缩
第 6 章 · M6 上下文管理与压缩
- 6.1 M6 功能说明:上下文快满时自动压缩
- 6.2 M6 总体架构:包结构与组件协作
- 6.3 核心模型:产生时落盘、窗口投影、改写内存历史
- 6.4 context Token 估算与 context 命令
- 6.5 五层递进压缩链总览:从便宜到贵、链式短路
- 6.6 第一层:大工具结果落盘(Read永不落盘)
- 6.7 第二层:Snip 压缩(清理低价值工具调用)
- 6.8 第三层:微压缩(删除可再获得的旧工具调用结果)
- 6.9 第四层:上下文折叠(代码抽取式摘要,不调模型)
- 6.10 第五层:自动压缩(调模型摘要,替换内存历史)
- 6.11 紧急压缩兜底
- 6.12 compact 命令 + 配置
6.1 M6 功能说明:上下文快满时自动压缩
本篇涉及到的源码列表:
com.minicc.context.HistoryStage.java
com.minicc.context.CompactionStage.java
com.minicc.compact.CompactionManager.java
com.minicc.compact.ToolResultCompactor.java
com.minicc.compact.SnipCompactor.java
com.minicc.compact.MicroCompactor.java
com.minicc.compact.ContextCollapser.java
com.minicc.compact.AutoCompactor.java
com.minicc.cli.command.ContextCommand.java
com.minicc.cli.command.CompactCommand.java
M5 我们做完了,现在这个 Agent 已经能跨会话记住项目约定,也能记住你纠正过它的事。
但它还有一个问题:上下文窗口会被占满。
从 M1 到 M5,我们的 Agent 从来不对上下文做任何精简。
每一轮请求,它都把完整的会话历史原样发给模型。负责这件事的 HistoryStage 只做一件事,就是把历史全部加进去。
不压缩会出什么事
任务比较短的时候,我们感觉不到这个问题。但只要任务变长,问题就会出现。
Agent 读了几个大文件、跑了几轮测试、来回改了几版代码之后,历史就会迅速把上下文窗口占满。
占用增加得不多时,会额外消耗 Token,响应也会变慢。占用继续增加,就会直接触发模型的 prompt_too_long 报错,任务执行到一半就中断。
从这一章开始,我们进入第六个里程碑 M6,为 Agent 增加应对长上下文的能力。
M6 这一版交付什么
我们这一版做四件事,合起来让 Agent 第一次能稳定地跑长任务。
- 固定的上下文组装顺序。M1 就已经确定了"系统提示词 → 记忆 → 会话历史"的顺序。M6 不修改这个顺序,而只是替换会话历史为压缩版本。
- 五层压缩链。按"从便宜到贵、从少丢信息到多丢信息"排列:工具结果预算、Snip、微压缩、上下文折叠、自动压缩。
- 紧急压缩兜底。万一连自动压缩自己都因为历史太长而报错,就直接丢掉最早的一批消息腾出空间,保证摘要请求至少发得出去。
/context与/compact两个命令。前者展示当前窗口各部分的占用,只查看、不压缩;后者手动触发一次压缩。
这一版完成之后,会话可以一直进行下去。接近窗口上限时,它会按层自动精简上下文,既保留关键信息,也不会因为超出窗口上限而中断。
命令行里是什么样的
我们用四个小场景,把 M6 的几项能力分别演示一遍。
场景一:超大工具结果自动落盘
你让它看一段很长的测试输出。命令跑完输出了几万字符,这种超大结果不会原样写入历史。
> 跑一下全量测试,看看哪些挂了
⏺ Bash(command="mvn -q test")
⎿ <工具结果过大,完整内容已落盘:/Users/me/.mcc/projects/-Users-me-orders/tool-results/call_8f3a.txt
(共 54210 字符,可用 Read 读取)。前 2KB 预览:>
[INFO] Running com.orders.OrderServiceTest …
⏺ 我先看完整的测试输出,定位失败的用例
⏺ Read(file_path=/Users/me/.mcc/projects/-Users-me-orders/tool-results/call_8f3a.txt)
⎿ (完整 54210 字符)…写进历史和日志的内容,只是"前 2KB 预览 + 文件路径 + 总字符数"这么一小段。
完整原文写在了 tool-results/ 目录下的一个文件里。模型需要全文时,直接用 Read 工具读那个路径,不用重新执行这条命令。
场景二:/context 看看占用
你想知道当前上下文占用了多少,就输入 /context。它按上下文组装器拼出的三段,分别给出 Token 占用。
> /context
上下文占用(估算):18.2k / 200.0k Token(9%)
系统指令与工具描述 4.1k (系统提示词 + 工具定义 schema)
项目约定与记忆索引 1.3k (AGENT.md + 记忆说明 + MEMORY.md)
会话历史(含待办/工具结果) 12.8k/context 只负责展示,本身不触发任何压缩。
场景三:/compact 手动压缩一次
一段长会话里,你想主动精简一次上下文,输入 /compact。它会把每一层减少的 Token 都打印出来。
> /compact
⏺ 正在压缩上下文…
⎿ Snip:清理空结果 / 被拒绝的调用(182000 → 170000 Token)
⎿ 微压缩:清理较早可再取的工具结果(170000 → 150000 Token)
⎿ 上下文折叠:把较早对话折叠成结构化摘要(150000 → 120000 Token)
⎿ 自动压缩:对历史做一次模型摘要…
⎿ 自动压缩:对其余历史做一次模型摘要(已替换内存历史,JSONL 不动)(120000 → 96000 Token)
⎿ 压缩后:182.0k → 96.0k Token(估算)真实的编程工具通常不会把这个过程展示出来。mini Claude Code 会把过程打印出来,方便你对照后面每一节,看清每一层在做什么。
场景四:接近上限时自动压缩
你不手动输入任何命令,只是一直和它对话。当窗口接近上限时,压缩会在某一轮请求发出前自动发生。
> 继续把剩下的接口也补上
⏺ 正在压缩上下文…
⎿ 上下文折叠:把较早对话折叠成结构化摘要(191000 → 170000 Token)
⎿ 自动压缩:对历史做一次模型摘要…
⏺ 好的,我接着写剩下的两个接口……你不需要关心它什么时候压缩、压缩了哪些内容。接近上限时,它会按层自动精简上下文,任务继续执行。
一条贯穿全章的主线:压缩幅度再大也不丢原文
M6 会删除或替换一部分发给模型的内容,但有一条底线始终成立:完整原文一直在磁盘上。
普通消息完整地保存在 M4 的会话日志(JSONL)里,超大工具结果完整地保存在 tool-results/ 的文件里。
压缩修改的是每一轮发给模型的那段上下文窗口,以及内存里的历史。它不修改磁盘上那份完整记录。
所以哪怕压缩幅度再大,/resume 回来仍然是全量记录。这也是为什么我们把 M4 的持久化放在 M6 之前先做的原因。
本章的学习路线
接下来的几节,我们把上面这些能力逐节细化成代码。
- 6.2 我们先讲一下总体架构:M6 复用 M1–M5 的哪些结构、新增了哪个包、一次"带压缩的请求"怎么走。
- 6.3 我们来讲一下 M6 最核心的模型:产生时落盘、窗口投影、改写内存历史
- 6.4 我们来讲一下 Token 估算和
/context。 - 6.5 我们来讲一下压缩链总览:便宜到贵、链式短路
- 6.6 到 6.10 我们逐层讲一下五层压缩:大工具结果落盘、Snip、微压缩、上下文折叠、自动压缩。
- 6.11 我们来讲一下紧急压缩兜底。
- 6.12 我们来讲一下
/compact命令、配置。
读完这一章,这个 Agent 就能稳定地跑长任务。接近窗口上限时,它会自动精简上下文,而原文始终还在。
6.2 M6 总体架构:包结构与组件协作
本篇涉及到的源码列表:
com.minicc.compact.CompactionManager.java
com.minicc.compact.TokenEstimator.java
com.minicc.compact.ToolResultCompactor.java
com.minicc.compact.SnipCompactor.java
com.minicc.compact.MicroCompactor.java
com.minicc.compact.ContextCollapser.java
com.minicc.compact.AutoCompactor.java
com.minicc.compact.CompactionPromptText.java
com.minicc.context.CompactionStage.java
com.minicc.context.HistoryStage.java
com.minicc.session.Session.java
com.minicc.persistence.SessionPaths.java
com.minicc.agent.AgentLoop.java
com.minicc.cli.Renderer.java
com.minicc.cli.command.ContextCommand.java
com.minicc.cli.command.CompactCommand.java
com.minicc.config.MccConfig.java
default-mcc.yml
com.minicc.MccApplication.java
上一节我们把 M6 要做什么、在命令行里是什么样讲清楚了。
这一节我们来看它的整体结构:复用 M1–M5 的哪些结构、新增了哪个包、一次"带压缩的请求"怎么在各组件之间流动。
你先掌握这张结构图。后面几节逐个讲每个组件时,你就知道它在整体里处在什么位置。
M6 的绝大部分还是新增
M6 继续延续"后续里程碑只新增、少改动既有代码"的原则。
它的主体是一个新的 compact 包、一个新的 Stage、两个命令的实现,对既有代码只有几处很小的修改。
这又一次是前面几个里程碑提前留好扩展点的回报。我们把 M6 的几条主线分别接到这些扩展点上。
- 压缩的"接入点":M1 的上下文组装器
ContextAssembler内部是一条有序、可插入 Stage 的管线,我们新增一个CompactionStage,接管"会话历史"这一段的组装。它替换掉原来只会把历史全部加进去的HistoryStage。 - 大结果的"落盘目录":放在 M4 引入的
~/.mcc结构下,复用 M4 的SessionPaths,和 M5 的记忆目录用的是同一种做法。 - 自动压缩要改写"内存历史":复用 M1/M4 的
Session,给它新增一个只修改内存、不写日志的方法。
包结构的增量
M6 是建在 M5 之上的,所以我们重点看它相对 M5 新增和修改的部分。
mini-claude-code/
├─ src/main/java/com/minicc/
│ ├─ compact/ // 新:整个包(上下文压缩这一件事)
│ │ ├─ CompactionManager.java // 新:压缩链的编排核心
│ │ ├─ TokenEstimator.java // 新:粗略的字符→Token 估算(静态方法)
│ │ ├─ ToolResultCompactor.java // 新:①工具结果预算(入库前落盘 tool-results/)
│ │ ├─ SnipCompactor.java // 新:②Snip(删空结果 / 被拒调用)
│ │ ├─ MicroCompactor.java // 新:③微压缩(清理较早可再取的旧结果)
│ │ ├─ ContextCollapser.java // 新:④上下文折叠(结构化摘要,不调模型)
│ │ ├─ AutoCompactor.java // 新:⑤自动压缩(调模型)+ 紧急压缩兜底
│ │ └─ CompactionPromptText.java // 新:自动压缩的摘要提示词
│ ├─ context/
│ │ ├─ CompactionStage.java // 新:Stage,替换 HistoryStage
│ │ └─ HistoryStage.java // 留:无压缩时的 HistoryStage(测试/兜底用)
│ ├─ session/Session.java // 改:新增 replaceHistoryInMemory(...)
│ ├─ persistence/SessionPaths.java // 改:新增 toolResultsDir(projectRoot)
│ ├─ agent/AgentLoop.java // 改:工具结果入库前加一处第①层落盘
│ ├─ cli/
│ │ ├─ Renderer.java // 改:渲染压缩过程 / 前后 Token
│ │ └─ command/
│ │ ├─ ContextCommand.java // 改:真正的占用分布
│ │ └─ CompactCommand.java // 改:真正触发一次压缩
│ ├─ config/MccConfig.java // 改:新增 compact 阈值 + toolResultBudget
│ ├─ resources/default-mcc.yml // 改:写上这两组配置模板
│ └─ MccApplication.java // 改:装配压缩模块、用 CompactionStage 替换 HistoryStagecompact 包里的几个角色
这个新包里,CompactionManager 是编排核心,另外五个类对应五层压缩,还有两个辅助类。
CompactionManager:压缩链的编排。它持有第①层落盘器和②–⑤四层压缩器,对外暴露三个入口,后面几节会反复提到它。ToolResultCompactor:第①层,工具结果入库前把超大结果落盘(见 6.6)。SnipCompactor:第②层,删掉空结果和被拒绝的调用(见 6.7)。MicroCompactor:第③层,把较早、可再取的旧工具结果换成占位符(见 6.8)。ContextCollapser:第④层,把较早的整轮折叠成结构化摘要(见 6.9)。AutoCompactor:第⑤层,调模型做摘要,并含紧急压缩兜底(见 6.10、6.11)。TokenEstimator:粗略的 Token 估算,全是静态方法(见 6.4)。CompactionPromptText:自动压缩的摘要提示词(见 6.10)。
CompactionManager 对外有三个入口。我们先记住这三个方法的名字,后面各节会把细节写清楚。
// 源码位置:com.minicc.compact.CompactionManager.java
/** 第①层:工具结果写入历史/日志前调用——超阈值的大结果落盘、入库那条换成"预览+路径"。 */
public ToolResponseMessage offloadToolResult(ToolResponseMessage result) { … }
/** 每轮请求前:把内存历史投影成精简窗口(②–⑤,便宜→贵、链式短路)。 */
public List<Message> compact(List<Message> history, Session session) { … }
/** /compact 手动触发:不看阈值,强制把 Snip→微压缩→折叠→自动压缩都跑一遍。 */
public void compactNow(Session session) { … }既有代码的几处修改
除了新包,M6 在既有代码上只有几处小改动,而且多数位置在前面几个里程碑就已经预告过。我们先列出来,建立整体印象。
ContextAssembler的组装清单:把CompactionStage放在最后一段,替换掉HistoryStage。这正是 M1 第 5.5 节预告过的压缩 Stage。AgentLoop:工具结果写入内存历史和日志之前,会先经过第①层的offloadToolResult。这是 M6 对既有写入路径唯一的结构性改动。Session:新增replaceHistoryInMemory(...),供第⑤层自动压缩用"摘要 + 最近几条原文"整体替换内存历史。它和replay一样只修改内存、不写 JSONL。SessionPaths:新增toolResultsDir(projectRoot),返回大工具结果落盘目录,复用既有逻辑。ContextCommand和CompactCommand:从 M1 的占位实现升级成真正的占用分布和真正的压缩。
可以看到,控制循环的骨架、模型边界、工具接口与执行、记忆都没有结构性改动。
一次"带压缩的请求"的全过程
我们把一条完整链路串一遍,就以"历史已经很长、这次请求会触发折叠"的一轮为例。
这里要注意,第①层不在这一步发生。它在之前每次工具结果产生时,就已经完成落盘。
第一步,组装上下文。 AgentLoop 仍然调用 assembler.assemble(session)。管线依次执行 SystemPromptStage 、MemoryStage (M5),然后轮到 CompactionStage。
第二步,执行压缩链。 CompactionStage 调用 CompactionManager.compact(...),在这里按成本从低到高执行②–⑤:Snip 删除低价值的 turn,微压缩在空闲够久时清理旧结果,折叠在窗口仍然超过 90% 时把较早的整轮折成摘要,自动压缩在仍然超过 95% 时调用模型做一次整体摘要。
第三步,把窗口交给模型。 CompactionStage 把压缩链产出的窗口加进消息列表。AgentLoop 把它交给模型。模型只看到精简后的窗口,不会超出上下文上限。
第四步,新结果回写,并完成落盘。 这一轮新产生的工具结果,在写入历史和日志之前,先过第①层的 offloadToolResult:超阈值的大结果当场落盘,入库的那条换成预览加路径。
6.3 核心模型:产生时落盘、窗口投影、改写内存历史
本篇涉及到的源码列表:
com.minicc.session.Session.java
上一节我们看了 M6 的整体结构。这一节我们把整个里程碑最核心的一件事讲清楚。
这一节比较抽象,但它是后面所有具体实现的前提。
如果这里理解清楚了,后面五层压缩就比较容易看懂;如果这里不清楚,后面很容易混淆到底修改了哪份数据。
会话里的几份数据
要理解 M6,我们先要分清会话里同时存在的几份数据。它们的分工各不相同。
| 名称 | 在哪 | 内容 | M6 会修改它吗 |
|---|---|---|---|
| JSONL 日志(M4) | ~/.mcc/projects/<项目>/<id>.jsonl | 只追加的会话记录;大结果在入库时即存为"预览+路径" | 只在第①层入库时确定内容;②–⑤ 不修改 |
| 内存历史(M1) | Session.history() | 内存里的消息列表,是日志的镜像 | ①入库时确定内容;②③④ 只读;⑤自动压缩会整体替换它 |
| 工具结果落盘(M6 新增) | ~/.mcc/projects/<项目>/tool-results/<call-id>.txt | 超阈值工具结果的完整原文 | 第①层写一次,之后只读 |
| 上下文窗口(M6 新增) | 每轮临时组装、发给模型 | 内存历史经②–⑤投影出的精简版 | ②③④ 只作用在这里;⑤既产出它、也把它写回内存历史 |
三类动作各自作用在哪份数据上
M6 把压缩分成三类时机,我们需要把它们分清。
第一类,第①层在"工具结果产生时"执行一次。 超大结果当场落盘到 tool-results/,写进内存历史和 JSONL 的那条就已经是预览加路径。
第二类,②③④ 三层是纯投影。 它们在每一轮请求前重新压缩一遍,把结果发给模型,用完就丢弃。内存历史与 JSONL 一个字都不修改。
第三类,第⑤层自动压缩会就地改写内存历史。 窗口接近上限、前四步仍然降不下来时,它调用模型,把整段历史摘要成一条消息,连同最近几条原文,整体替换掉内存里的消息列表。替换之后,内存历史的占用下降,下一轮不再重复摘要。但它仍然不修改 JSONL,完整原文还在日志里。
"压缩幅度再大也不丢原文"为什么成立
我们把三类动作合起来看,这个结论就成立了。
完整内容要么在 JSONL(普通消息、未超阈值的结果),要么在 tool-results/(超大结果)。
哪怕第①层把大结果换成了预览加路径,哪怕第⑤层把内存历史替换成了摘要,JSONL 里始终是全量原文。
所以 /resume 读回来,仍是未被②–⑤压缩的完整历史。压缩做的是精简内存,并把超大结果转移到独立文件,不是销毁历史。
第⑤层为什么要改写内存历史
你可能会问:既然都是在减少上下文占用,为什么不统一成一种做法?这里的取舍值得我们单独讲一下。
第⑤层为什么要改写内存历史? 因为它是唯一调用模型、成本也最高的一层。摘要结果本身就应该成为长期替代旧历史的新起点。
与其每一轮都把旧历史重新发给模型再摘要一次,不如摘要一次就把内存历史换成"摘要加最近几条原文"。内存历史变短之后,下一轮就不会再超过阈值,也不必重复调用模型。
第①层为什么要在"产生时"就落盘? 因为超大工具结果一旦产生,之后每一轮都会被反复带进上下文,持续占用窗口。
与其每轮投影都重新扫描历史、重新决定要不要落盘,不如在它刚产生、即将入库的那一刻就按阈值判断。如果超过阈值,就把完整原文写到 tool-results/,入库只留预览加路径。
支撑第⑤层的那个新方法
第⑤层要改写内存历史,靠的是我们给 Session 新增的一个方法。
// 源码位置:com.minicc.session.Session.java
/** M6 第⑤层自动压缩用它把"摘要+最近几条原文"整体替换内存历史。只改内存、不写 JSONL。 */
public void replaceHistoryInMemory(List<Message> messages) {
history.clear();
history.addAll(messages);
}它和 M4 回放用的 replay 很像,都只修改内存、不写日志。区别只是它先清空,再整体替换。
正因为有这个只修改内存的方法,第⑤层才能减少内存历史的占用,同时让磁盘上的日志保持原样。
6.4 context Token 估算与 context 命令
本篇涉及到的源码列表:
com.minicc.compact.TokenEstimator.java
com.minicc.cli.command.ContextCommand.java
com.minicc.context.MemoryStage.java
压缩要判断窗口占用了多少,/context 要展示占用分布。这两件事我们都需要先知道一段内容大约有多少 Token。
我们先解决这个估算,再看 /context 怎么用它。
用粗略估算,不接真实分词器
如果要精确计算 Token,就需要使用模型对应的分词器。
但我们这里不需要那么精确。压缩的阈值判断是 90% 和 95%,本就留了余量,对估算误差不敏感。/context 的展示也只需要数量级正确。
所以我们用一个经验系数,把字符数折算成 Token。
英文和代码大约 4 个字符一个 Token,中文大约 1.5 个字符一个 Token,混合场景取中间值,大约 3.5。
// 源码位置:com.minicc.compact.TokenEstimator.java
/** 经验系数:平均多少字符折算成一个 Token。 */
private static final double CHARS_PER_TOKEN = 3.5;
/** 估算一段文本的 Token 数(向上取整)。 */
public static int ofText(String text) {
if (text == null || text.isEmpty()) {
return 0;
}
return (int) Math.ceil(text.length() / CHARS_PER_TOKEN);
}这个类里的方法都是静态的,调用时不需要先创建对象。
一条消息怎么估算
会话里有几种消息:用户消息(UserMessage)、系统消息(SystemMesssage)、含或不含工具调用的 assistant 消息、工具结果。估算要把这几种都覆盖到。
// 源码位置:com.minicc.compact.TokenEstimator.java
public static int ofMessage(Message message) {
if (message == null) {
return 0;
}
int chars = 0;
if (message instanceof ToolResponseMessage trm) {
// 工具结果:累加每条 responseData(大结果在入库时已是"预览+路径",估的就是瘦身后的量)。
for (ToolResponseMessage.ToolResponse resp : trm.getResponses()) {
if (resp.responseData() != null) {
chars += resp.responseData().length();
}
// ……再加上工具名字……
}
} else if (message instanceof AssistantMessage am) {
// 助手消息:正文 + 每个工具调用的名字与参数 JSON。
// ……累加 am.getText(),以及每个 ToolCall 的 name 与 arguments……
} else {
// 其余(用户消息、系统消息):按正文文本计。
String text = message.getText();
if (text != null) {
chars += text.length();
}
}
return (int) Math.ceil(chars / CHARS_PER_TOKEN);
}这里有一个实现细节:工具结果这一类,估算的是 responseData 的字符数。
因为超大结果在入库时就已经被换成了"预览加路径"(见 6.6),所以这里估算出来的,已经是精简之后的量,而不是原始几万字符的量。
我们再增加一个 ofMessages,把一个消息列表的 Token 累加起来。到这里,估算这部分就完整了。
// 源码位置:com.minicc.compact.TokenEstimator.java
public static int ofMessages(List<Message> messages) {
int sum = 0;
for (Message message : messages) {
sum += ofMessage(message);
}
return sum;
}/context:看占用,不压缩
有了这个估算,/context 就容易实现了。它只负责展示当前窗口各部分的 Token 占用,本身不触发任何压缩。
它按上下文组装器拼出的三段来分:系统指令与工具描述、项目约定与记忆、会话历史。
> /context
上下文占用(估算):18.2k / 200.0k Token(9%)
系统指令与工具描述 4.1k (系统提示词 + 工具定义 schema)
项目约定与记忆索引 1.3k (AGENT.md + 记忆说明 + MEMORY.md)
会话历史(含待办/工具结果) 12.8k实现上,ContextCommand 分别估算这三段。关键是它不执行②–⑤投影链。
// 源码位置:com.minicc.cli.command.ContextCommand.java
@Override
public boolean run(String args) {
int system = estimateSystemAndTools(); // 系统提示词 + 各工具定义
int memory = estimateMemory(); // 让 MemoryStage 贡献一条消息再估
int history = TokenEstimator.ofMessages(session.history()); // 内存历史的原始占用
int total = system + memory + history;
int limit = config.contextLimit();
int percent = limit > 0 ? (int) Math.round(100.0 * total / limit) : 0;
renderer.info("上下文占用(估算):" + Renderer.formatTokens(total) + " / "
+ Renderer.formatTokens(limit) + " Token(" + percent + "%)");
// ……再分三行打印 system / memory / history……
return false;
}这三段的估算方法各不相同。
系统指令与工具描述,是系统提示词全文,加上每个工具的名字、描述、参数 schema 的文本。
项目约定与记忆,是让 MemoryStage 往一个临时列表里贡献一条消息,再估算它。这一步只读取,不修改会话。
// 源码位置:com.minicc.cli.command.ContextCommand.java
private int estimateMemory() {
if (memoryStage == null) {
return 0;
}
List<Message> tmp = new ArrayList<>();
memoryStage.contribute(tmp, session); // 只读:加载 AGENT.md / MEMORY.md,不改会话
return TokenEstimator.ofMessages(tmp);
}为什么会话历史估算的是原始占用
这里有一个容易理解错的地方。
会话历史这一段,/context 估算的是 session.history() 的原始占用,也就是不执行投影链、不折叠、不摘要的那一份。
原因是 /context 要回答的是当前占用到了什么程度。这个占用量才是驱动压缩的依据,不是压缩之后模型会看到的窗口。
如果它估算的是压缩后的窗口,就看不到接近上限的情况,也就不知道为什么下一轮会触发压缩。
Token 怎么估算、/context 怎么查看占用,这一节我们就讲完了。下一节我们来看压缩链的总览:五层是怎么按便宜到贵的顺序串起来。
6.5 五层递进压缩链总览:从便宜到贵、链式短路
本篇涉及到的源码列表:
com.minicc.compact.CompactionManager.java
上一节我们把 Token 估算和 /context 讲完了。这一节我们从整体上看五层压缩是怎么接成一条链的。
后面 6.6 到 6.11 会逐层说明。读那些内容之前,我们需要先看清每一层在链条上的位置、什么时候触发、前后怎么衔接。
核心思想:分层,便宜到贵
五层压缩的顺序是固定的,按成本从低到高、丢失的信息从少到多排列。下文把这个顺序称为"便宜到贵"。
- ① 大工具结果落盘:几乎没有额外成本,只是把超大结果写到旁边的文件。
- ② Snip:删除本来就没有参考价值的 turn,不丢失后续推理需要的信息。
- ③ 微压缩:清理可以再次获取的旧结果,这些信息之后还能取回。
- ④ 上下文折叠:把中间的工具往返替换成结构化摘要,会丢失一些细节。
- ⑤ 自动压缩:调用模型把整段历史摘要成一段文字,丢失的信息最多,成本也最高。
越往后成本越高,丢失的信息也可能越多。所以我们总是先用成本低的层。前面的层释放出足够空间之后,后面成本更高的层就不必执行。
链式短路:前面释放出足够空间,后面就不再执行
这条链在每一轮请求发出前都会过一遍,而且是链式短路的。
前面的层把窗口占用降下来。如果占用已经低于阈值,后面的层就直接什么都不做。
负责把这几层串起来的,是 CompactionManager.compact。我们先看一下它的主要流程。
// 源码位置:com.minicc.compact.CompactionManager.java
public List<Message> compact(List<Message> history, Session session) {
double limit = config.contextLimit();
// ② Snip:删掉空结果 / 被拒绝的调用(便宜,成对删除保证窗口合法)。
List<Message> window = snip.apply(history);
// 第③层是否该跑:距上次请求的空闲时长 ≥ microcompactIdleMinutes。
long idleMinutes = Duration.between(lastRequestAt, Instant.now()).toMinutes();
boolean microDue = idleMinutes >= config.microcompactIdleMinutes();
this.lastRequestAt = Instant.now();
// 腾完 Snip,若已回落到折叠阈值以下、且不需微压缩,③④⑤ 都不用做(链式短路)。
if (TokenEstimator.ofMessages(window) < limit * config.collapseAt() && !microDue) {
return window;
}
// ③ 微压缩:仅"会话空闲够久后再继续"才触发。
if (microDue) {
window = micro.apply(window);
}
// ④ 上下文折叠:仍 ≥ 90% → 把较早整轮折叠成结构化摘要(不调模型)。
if (TokenEstimator.ofMessages(window) >= limit * config.collapseAt()) {
window = collapser.apply(window);
}
// ⑤ 自动压缩:仍 ≥ 95% 时触发——调模型摘要整段历史,并就地改写内存历史。
if (TokenEstimator.ofMessages(window) >= limit * config.autoCompactAt()) {
window = auto.apply(window, session);
}
return window;
}这里要注意一个细节:第①层不在这段链里。
它早在工具结果产生、入库之前就执行过了(见 6.6),所以 compact 一进来,拿到的 history 里大结果已经是预览加路径。
我们再看一下阈值的用法。collapseAt 是 0.90,autoCompactAt 是 0.95,它们都乘在 contextLimit 上,得到一个 Token 数。每过一层就重新估算一次上下文窗口的Token占用数量,只有仍然超过阈值,才进入下一层。
你可能注意到,④折叠和⑤自动压缩都是看"占用比例"触发,唯独③微压缩看的是"空闲时长"。
CompactionManager 用一个字段 lastRequestAt 记上次请求的时刻。每次 compact 开头,用它算出距上次请求过了多少分钟,再更新成现在。
空闲时间超过 microcompactIdleMinutes(默认 60 分钟),才会触发微压缩。为什么这么设计,涉及前缀缓存,我们留到 6.8 专门来讲一下。
每一层到底改了什么
五层里,第①层和第⑤层会改写持久状态,②③④加上紧急兜底都是临时映射。我们把差异整理成下面这张表,请仔细看一下。
| 层 | 针对的对象(输入) | 改内存历史? | 改 JSONL? | 性质 |
|---|---|---|---|---|
| ① 工具结果预算 | 刚产生的那条工具结果(入库前) | ✅ 换成"预览+路径" | ✅ 写进去的就是"预览+路径",原文另存 tool-results/ | 入库时一次性改写 |
| ② Snip | 内存历史的副本(投影链起点) | ❌ | ❌ | 临时映射 |
| ③ 微压缩 | ②的输出 | ❌ | ❌ | 临时映射 |
| ④ 上下文折叠 | ③的输出 | ❌ | ❌ | 临时映射 |
| ⑤ 自动压缩 | ④的输出 | ✅ 用"摘要+最近几条原文"替换 | ❌ JSONL 仍是全量原文 | 就地改写内存历史 |
这张表里有两个点最容易混淆,我们分开说明。
第一,没有任何一层把 JSONL 当作输入。JSONL 是只追加的完整记录,只在 /resume 时被读回内存,压缩从不直接读它。
第二,②–⑤ 是链式的。②的输入是内存历史的副本,③④⑤依次以上一步的输出为输入,不是每一层都回到原始历史从头再来。只有第①层例外,它处理的是刚产生的那一条结果,本来就不依赖这条链。
一条贯穿所有层的约束
无论哪一层,产出的窗口对模型必须合法。
具体来说,每个 assistant 消息上的工具调用,都要有配对的工具结果,不能留下悬空的工具调用。
这和 M4 回放时丢弃悬空工具调用是同一个约束。删除、折叠、替换的时候,调用和结果都要成对处理。后面每一层我们都会看到它是怎么满足这条约束的。
整体结构清楚之后,下一节我们从第一层开始,逐层来说明。
6.6 第一层:大工具结果落盘(Read永不落盘)
本篇涉及到的源码列表:
com.minicc.compact.ToolResultCompactor.java
com.minicc.agent.AgentLoop.java
com.minicc.persistence.SessionPaths.java
上一节我们看了压缩链的总览。从这一节开始,我们逐层来说明。
第一层是大工具结果落盘。它和后面四层都不太一样:它不在每轮投影链里,而是在工具结果刚产生、即将入库的那一刻就执行。
做什么、为什么在"产生时"就做
一次 Bash 跑测试、一次 Grep 大范围检索,可能一次输出几万甚至几十万字符。
这种体积很大的单条结果,是上下文膨胀最常见、也最容易处理的。它往往只有开头一小段有用,模型需要时还能把完整内容再取回来。
所以我们在它刚产生、即将写入历史和日志的那一刻就按阈值判断并落盘。这一步成本最低,也适合在入库之前完成。
- 单条工具结果的字符数超过该工具的阈值,我们就把完整内容落盘到
~/.mcc/projects/<项目>/tool-results/<callId>.txt。写进内存历史和 JSONL 的那条,换成一段"引用消息":文件绝对路径、前 2KB 预览、总字符数。 - 模型若需要完整内容,直接用 Read 工具读那个文件路径。
- 因为是在产生时写一次,这个决策做完就不再改变,也不会重复落盘。之后每轮投影、
/resume读回,看到的都是同一份预览加路径。
Read 为什么永不落盘
各工具的阈值里,有一个很特殊:Read 的阈值是 -1,表示无限,永不落盘。
这不是随意确定的,而是一个必须遵守的约定。
如果 Read 的结果也落盘、只留一个路径,模型拿到路径之后会再去 Read 这个路径。读回来又超过阈值、又落盘、又只留路径,于是再去 Read,形成死循环。
所以 Read 永不落盘。M1 实现 Read 时就保留了这个约定,M6 在这里沿用它。
各工具的阈值如下,都来自配置,默认值如下表。
| 工具 | 阈值(字符) | 说明 |
|---|---|---|
| Read | -1 | 无限,永不落盘 |
| Bash | 30000 | 命令输出可能很大 |
| Grep | 20000 | 检索命中可能很多 |
| Edit / Write / Glob | 100000 | 一般不会太大,阈值放宽 |
核心实现
落盘这件事由 ToolResultCompactor 负责。它对一条工具结果里的每一项分别判断:超过阈值的结果就落盘,并换成引用;否则保持原样。
// 源码位置:com.minicc.compact.ToolResultCompactor.java
/** 预览字节数。 */
static final int PREVIEW_BYTES = 2000;
/**
* 入库前调用:逐条看工具结果,单条超阈值的落盘并替换为"预览+路径",否则原样。
* 返回一条"要入库的" ToolResponseMessage——它和日志里存的是同一份。
*/
public ToolResponseMessage apply(ToolResponseMessage trm) {
List<ToolResponseMessage.ToolResponse> out = new ArrayList<>();
boolean changed = false;
for (ToolResponseMessage.ToolResponse resp : trm.getResponses()) {
int limit = budgetFor(resp.name()); // -1 = 无限、永不落盘
String data = resp.responseData();
if (limit < 0 || data == null || data.length() <= limit) {
out.add(resp); // 不超阈值(或无限):原样入库
} else {
Path file = writeToResultFile(resp.id(), data); // 写 <callId>.txt(已存在即复用)
String reference = (file != null)
? reference(file, data)
: data; // 落盘失败则退回原文(宁可不压也不丢)
out.add(new ToolResponseMessage.ToolResponse(resp.id(), resp.name(), reference));
changed = (file != null) || changed;
}
}
// 没有任何一条被替换时,原样返回入参。
return changed ? ToolResponseMessage.builder().responses(out).build() : trm;
}这里有个值得注意的地方。落盘失败不抛异常,而是退回原文。压缩只是优化,不能因为写盘失败就丢数据或者让程序崩。
只写一次,已存在就复用
落盘用 callId 命名文件,而且只写一次。
同一个 callId 的内容是确定的,所以我们用 CREATE_NEW 打开:文件已经存在,就复用它,不再重写。
// 源码位置:com.minicc.compact.ToolResultCompactor.java
private Path writeToResultFile(String callId, String data) {
try {
Files.createDirectories(toolResultsDir);
Path file = toolResultsDir.resolve(sanitize(callId) + ".txt");
try {
Files.writeString(file, data, StandardCharsets.UTF_8,
StandardOpenOption.CREATE_NEW, StandardOpenOption.WRITE);
} catch (java.nio.file.FileAlreadyExistsException eexist) {
// 已落过盘(同一 callId 内容确定),直接复用这份文件。
}
return file;
} catch (IOException e) {
return null; // 失败不抛,交给调用方退回原文
}
}引用消息长这样:一个固定前缀,加上文件路径、总字符数、前 2KB 预览。
// 源码位置:com.minicc.compact.ToolResultCompactor.java
private String reference(Path file, String data) {
String preview = data.substring(0, Math.min(PREVIEW_BYTES, data.length()));
return "<工具结果过大,完整内容已落盘:" + file.toAbsolutePath()
+ "(共 " + data.length() + " 字符,可用 Read 读取)。前 2KB 预览:>\n" + preview;
}那个固定前缀「<工具结果过大」不只是给人看的。第④层折叠时,就靠它识别"这条已经落过盘、可以从里面解析出落盘路径"。
接进工具结果入库点
落盘要在工具结果写入历史和日志之前发生,所以接入点在 AgentLoop 里。这是 M6 对既有写入路径唯一的改动,就加了一行拦截。
// 源码位置:com.minicc.agent.AgentLoop.java
// 工具执行产生结果后、写入历史与日志之前
ToolResponseMessage toolResponseMessage = Session.toToolResponse(call, result);
if (compactionManager != null) {
toolResponseMessage = compactionManager.offloadToolResult(toolResponseMessage);
}
session.appendToolResult(toolResponseMessage); // 内存历史与 JSONL 存的都是这份落盘目录由 SessionPaths 新增的一个方法提供,复用它既有的目录推导,和 M5 的 memoryDir 用的是同一套做法。
// 源码位置:com.minicc.persistence.SessionPaths.java
/** 本项目的工具结果落盘目录:<projectDir>/tool-results/。M6 的大结果都落这里。 */
public Path toolResultsDir(Path projectRoot) {
return projectDir(projectRoot).resolve("tool-results");
}第一层我们就讲完了。下一节我们来看第二层 Snip。
6.7 第二层:Snip 压缩(清理低价值工具调用)
本篇涉及到的源码列表:
com.minicc.compact.SnipCompactor.java
上一节我们讲了第一层大工具结果落盘,它在结果产生时就落盘。
从这一节开始,我们进入压缩链里的层。第二层 Snip 是链的起点,也是成本最低的一层。
Snip 做什么
Snip 以"一次工具调用加工具调用结果"为单位,直接删掉低价值的 turn。
什么叫低价值?就是这两类对后续推理几乎没有参考价值的 turn。
- 空结果:
Grep或Glob没匹配到任何东西。它们没命中时返回的是固定文案「没有匹配结果。」或「没有匹配的文件。」。 - 被拒绝的调用:你在审批卡片里选了"拒绝"(M3)。被拒的结果由 M3 生成,以「用户拒绝执行工具」开头。
这两类留在历史里没有参考价值。所以 Snip 每一轮都执行,不等到接近上限才做。尽早删除,可以减少占用。
它是纯临时映射:只在当次上下文窗口里删除,不修改内存历史,也不修改 JSONL。
成对删除,不留悬空
删除时有一条必须遵守的规则:成对删除。
既要删除那条工具结果,也要把对应的工具调用从它所在的 assistant 消息里去掉。
如果只删除结果、不删除调用,窗口里就会出现一个调用了工具、却没有结果的悬空调用,模型会报协议错误。这正是上一节总览里讲的那条约束。
这套按 id 配对、去掉一边就去掉另一边的逻辑,和 M4 回放时丢弃悬空工具调用是同一种结构,这里沿用它。
两步走的实现
SnipCompactor.apply 分两步:先找出要删的 id,再按 id 成对清理。
// 源码位置:com.minicc.compact.SnipCompactor.java
private static final String GREP_EMPTY = "没有匹配结果。";
private static final String GLOB_EMPTY = "没有匹配的文件。";
private static final String DENIED_PREFIX = "用户拒绝执行工具";
/** 对窗口做一次 Snip 投影:返回删掉低价值 turn 后的新列表(原列表不动)。 */
public List<Message> apply(List<Message> history) {
// 1) 找出要删的 ToolResponse 的 id:空结果 / 被拒绝。
Set<String> dropIds = collectLowValueResponseIds(history);
if (dropIds.isEmpty()) {
return history;
}
// 2) 删掉这些结果,并从对应 AssistantMessage 上摘掉同 id 的 ToolCall(成对清理)。
return rebuildWithout(history, dropIds);
}没有要删的,就原样返回。
判定低价值靠的是一个启发式:把结果 strip() 之后,看它是不是那两句固定文案,或者是不是以"用户拒绝执行工具"开头。
这个做法粗一些。但这里的消息比较简单,固定文案足够覆盖常见情况。
// 源码位置:com.minicc.compact.SnipCompactor.java
private boolean isLowValue(ToolResponseMessage.ToolResponse resp) {
String data = resp.responseData();
if (data == null) {
return false;
}
String trimmed = data.strip();
return trimmed.equals(GREP_EMPTY)
|| trimmed.equals(GLOB_EMPTY)
|| trimmed.startsWith(DENIED_PREFIX);
}重建时怎么成对清理
rebuildWithout 逐条扫历史,分三种情况处理。
// 源码位置:com.minicc.compact.SnipCompactor.java
private List<Message> rebuildWithout(List<Message> history, Set<String> dropIds) {
List<Message> out = new ArrayList<>();
for (Message message : history) {
if (message instanceof ToolResponseMessage trm) {
// 保留不在 dropIds 里的结果;整条结果都被删则跳过这条消息。
List<ToolResponseMessage.ToolResponse> kept = trm.getResponses().stream()
.filter(r -> !dropIds.contains(r.id()))
.collect(Collectors.toList());
if (kept.isEmpty()) {
continue;
}
out.add(kept.size() == trm.getResponses().size()
? trm
: ToolResponseMessage.builder().responses(kept).build());
} else if (message instanceof AssistantMessage assistant) {
List<AssistantMessage.ToolCall> calls =
assistant.getToolCalls() == null ? List.of() : assistant.getToolCalls();
List<AssistantMessage.ToolCall> kept = calls.stream()
.filter(c -> !dropIds.contains(c.id()))
.toList();
// 工具调用全被摘掉、又没有文本 → 整条助手消息丢弃。
if (kept.isEmpty() && (assistant.getText() == null || assistant.getText().isBlank())) {
continue;
}
// 没摘则原样保留;摘掉一部分时换一条只带剩余调用的助手消息。
if (kept.size() == calls.size()) {
out.add(assistant);
} else {
// 保留 metadata:思考模式的 reasoningContent 还要随这条 assistant消息进入下一次请求。
out.add(AssistantMessage.builder()
.content(assistant.getText() == null ? "" : assistant.getText())
.properties(assistant.getMetadata())
.toolCalls(kept)
.build());
}
} else {
out.add(message);
}
}
return out;
}我们把三种情况理一下。
工具结果消息:把被删的结果过滤掉。如果一条消息里的结果全被删了,整条跳过;只删掉一部分,就换一条只带剩余结果的消息。
assistant 消息:把被删 id 对应的工具调用去掉。如果调用被全部去掉、又没有正文,整条丢弃;只去掉一部分,就换一条只带剩余调用的 assistant 消息,正文和 metadata 原样保留。
reasoningContent 就在 metadata 里。这条消息还要进入下一次请求,重建时如果丢掉它,模型会返回 400。
其他消息:原样保留。
这样一来,被删的调用和它的结果一起消失,窗口里不会留下悬空调用。
第二层 Snip 我们就讲到这里。它删除的是本来就没有参考价值的内容,不丢失后续推理需要的信息,所以放在链的最前面,每一轮都执行。
下一节我们讲一下第三层微压缩。它会清理可以再次获取的旧结果。
6.8 第三层:微压缩(删除可再获得的旧工具调用结果)
本篇涉及到的源码列表:
com.minicc.compact.CompactionManager.java
com.minicc.compact.MicroCompactor.java
上一节我们讲了第二层 Snip,它删除本来就没有参考价值的 turn。
这一节我们讲一下第三层微压缩。它清理的是可以再次获取的旧工具结果。最反直觉、也最需要讲清楚的,是它的触发时机。
微压缩做什么
微压缩只清理可以再次获取的工具结果。
哪些结果可以再次获取?我们列了一个白名单:Read、Bash、Grep、Glob、Edit、Write。
这些工具的内容随时能重新获取。把较早的那些替换成占位符,信息并没有丢失。
它保留最近的 5 个,更早的替换成占位符 [Old tool result content cleared]。
和 Snip 一样,它是纯临时映射:只在当次上下文窗口里把旧结果换成占位符,不修改内存历史,也不修改 JSONL。
为什么按"空闲时长"触发
这是微压缩最反直觉的一点:它不是接近窗口上限才做,而是会话空闲大约 60 分钟后再继续时才做。
要理解这个设计,需要先理解前缀缓存。
平时每一轮请求,靠前的那部分内容(系统提示词、记忆、较早的历史)是稳定不变的。模型侧能命中前缀缓存,响应更快,费用也更低。
可一旦我们在历史中间替换掉某些旧结果,就等于修改了靠前的内容,前缀缓存随之失效,后面的内容全部要重新计算KV。
什么时候清理的代价最小?是会话已经空闲很久的时候。
会话空闲很久,前缀缓存本来就已经过期,下次请求必须重建缓存。这时候先清理、再让缓存重建,几乎不增加额外成本。
所以微压缩只在缓存即将失效、下次请求必须重建的时刻执行。
时机判定在编排层
是否到了该做微压缩的时刻,由 CompactionManager 判定,不是 MicroCompactor 自己判断。
CompactionManager 用一个字段 lastRequestAt 记录上次请求的时刻。每次 compact 开头先算出空闲时长,再把它更新成现在。
// 源码位置:com.minicc.compact.CompactionManager.java
long idleMinutes = Duration.between(lastRequestAt, Instant.now()).toMinutes();
boolean microDue = idleMinutes >= config.microcompactIdleMinutes();
this.lastRequestAt = Instant.now();
// ……
if (microDue) {
window = micro.apply(window);
}/compact 手动触发时不看这个时刻,直接调用 apply。
核心实现:留最近 N 个,更早的清掉
apply 分两步:先从后往前标记"最近要保留的几个",再从前往后重建,把该清的换成占位符。
两个需要注意的细节:
第一,微压缩只替换内容,不删除消息。它把结果的正文换成占位符,但这条工具结果本身还在,id 也还在。
所以它不会制造悬空调用,不需要像 Snip 那样成对删除。
第二,它只处理白名单里的工具。TodoWrite、AskUserQuestion 这类工具的结果不能随时重新获取,一律不修改。
// 源码位置:com.minicc.compact.MicroCompactor.java
static final String CLEARED = "[Old tool result content cleared]";
private static final Set<String> COMPACTABLE_TOOLS = Set.of(
"Read", "Bash", "Grep", "Glob", "WebSearch", "WebFetch", "Edit", "Write");
public List<Message> apply(List<Message> window) {
int keepRecent = config.keepRecentToolResults();
// 1) 先从后往前,标记"最近 keepRecent 个可再取结果"的 id(这些保留原文)。
Set<String> keepIds = new HashSet<>();
int kept = 0;
for (int i = window.size() - 1; i >= 0 && kept < keepRecent; i--) {
if (window.get(i) instanceof ToolResponseMessage trm) {
for (ToolResponseMessage.ToolResponse resp : trm.getResponses()) {
if (isCompactable(resp)) {
keepIds.add(resp.id());
kept++;
}
}
}
}
// 2) 再从前往后重建:可再取、且不在"最近保留集"里的,内容换成占位符;其余原样。
List<Message> out = new ArrayList<>(window.size());
for (Message message : window) {
if (message instanceof ToolResponseMessage trm) {
List<ToolResponseMessage.ToolResponse> responses = new ArrayList<>();
boolean changed = false;
for (ToolResponseMessage.ToolResponse resp : trm.getResponses()) {
if (isCompactable(resp) && !keepIds.contains(resp.id())) {
responses.add(new ToolResponseMessage.ToolResponse(resp.id(), resp.name(), CLEARED));
changed = true;
} else {
responses.add(resp);
}
}
out.add(changed ? ToolResponseMessage.builder().responses(responses).build() : trm);
} else {
out.add(message);
}
}
return out;
}判断一条结果能不能替换,要看两个条件:它在白名单里,而且还没有被替换过。
// 源码位置:com.minicc.compact.MicroCompactor.java
private boolean isCompactable(ToolResponseMessage.ToolResponse resp) {
return COMPACTABLE_TOOLS.contains(resp.name())
&& !CLEARED.equals(resp.responseData());
}第三层我们就讲完了。下一节的第四层上下文折叠,会把中间的工具往返替换成摘要。
6.9 第四层:上下文折叠(代码抽取式摘要,不调模型)
本篇涉及到的源码列表:
com.minicc.compact.ContextCollapser.java
上一节我们讲了第三层微压缩。这一节我们讲一下第四层上下文折叠。
前三层做的是转移超大结果、删除没有参考价值的 turn、替换可以再次获取的旧结果。它们都还没有处理那些有用、但占用很大的历史。上下文折叠负责处理这部分。
上下文折叠做什么
窗口在前三层之后仍然大于等于 90%(配置里的 collapseAt)时,触发上下文折叠。
它把较早那些轮中间的工具往返替换成一条结构化摘要。关键特点是不调用模型,只用代码从消息的元数据里抽取。
不调用模型有两个好处:几乎没有额外成本,而且不会引入模型幻觉。抽出来的都是实际记录下来的工具名、文件路径、命令和状态。
它是纯临时映射:每一轮按当前窗口重新计算一遍,折出来的摘要不写回历史,也不写入 JSONL。
一"轮"是什么
折叠的单位是"轮"。一轮指的是:一条用户消息,加上它之后直到下一条用户消息之前的全部消息。
一轮里通常包含三部分:开头的用户请求,中间来回的工具调用和工具结果,末尾那条 assistant 给出的结论。
折叠从窗口开头逐轮往下处理。每折完一轮,就减去这一轮省下的 Token。一旦低于阈值就停止,后面的轮次原样接上。
最近一轮始终保留原文,因为这一轮可能正在进行中。
折叠时保留什么、折掉什么
折叠遵守一条和第五层一致的原则:用户消息是用户意图的原始依据,不截断、不丢弃。
第五层自动压缩会保留全部用户消息。折叠比它更早触发,成本也更低,没有理由反而对用户消息做更大幅度的删改。
末尾那条不含工具调用的 assistant 结论也保留原文。工具元数据只能复原"调用了什么、成功没有",复原不了这一轮的判断、原因和对你的回答。而且这条结论通常很短,本来就不是膨胀的来源。
所以被折叠的每一轮,变成三条消息:
- 用户请求原文,完整保留。
- 一条结构化 JSON 摘要,只替换中间的工具往返。
- 末尾那条结论原文,接在摘要后面。这一轮没有结论就不补这条。
如果一轮里没有工具往返,就不插入空摘要,整轮保持原文。
摘要里有什么
摘要是一段 JSON,形如 {"tools":[...]},不含任何原始结果正文。
每个工具条目抽取这些字段:
tool:工具名。- Read / Edit / Write:
file,也就是参数里的file_path。 - Bash:
command,超过 200 字符就截断。 - Grep / Glob:
pattern。 status:empty(空结果)、denied(被拒)、offloaded(已落盘)、或ok。offloaded:状态是已落盘时,从引用消息里解析出的落盘路径,模型需要原文时可以据此 Read。
抽取单个工具调用的代码是这样的。
// 源码位置:com.minicc.compact.ContextCollapser.java
private Map<String, Object> summaryToolCall(AssistantMessage.ToolCall call, String result) {
Map<String, Object> entry = new LinkedHashMap<>();
entry.put("tool", call.name());
// 按工具类型抽取"操作对象":文件类取 file_path、Bash 取 command。
switch (call.name()) {
case "Read", "Edit", "Write" -> {
String fp = ToolCallHelper.getString(call, "file_path", "");
if (!fp.isBlank()) entry.put("file", fp);
}
case "Bash" -> {
String cmd = ToolCallHelper.getString(call, "command", "");
if (!cmd.isBlank()) entry.put("command", cmd.length() > 200 ? cmd.substring(0, 200) + "…" : cmd);
}
case "Grep", "Glob" -> {
String pattern = ToolCallHelper.getString(call, "pattern", "");
if (!pattern.isBlank()) entry.put("pattern", pattern);
}
default -> { }
}
// 结果状态:空 / 被拒 / 已落盘 / 一般完成。
entry.put("status", statusOf(result));
if (result != null && result.startsWith("<工具结果过大")) {
String path = extractOffloadPath(result);
if (path != null) entry.put("offloaded", path);
}
return entry;
}状态判定复用了我们前面见过的那些固定文案和前缀:空文案判 empty,「用户拒绝执行工具」判 denied,「<工具结果过大」判 offloaded。
逐轮折叠、够了就停
折叠的主循环,从开头逐轮处理,折到够了就把剩下的原样接上。
// 源码位置:com.minicc.compact.ContextCollapser.java
public List<Message> apply(List<Message> window) {
int total = TokenEstimator.ofMessages(window);
double threshold = config.contextLimit() * config.collapseAt();
if (total < threshold) {
return window; // 未到 90%,不折
}
// ……第一条用户消息之前的内容原样留在最前面……
boolean folded = false;
while (i < n) {
// 一轮 = 这条用户消息 + 其后直到下一条用户消息之前的全部消息。
int nextUser = …;
if (nextUser == n) { // 最近一轮:保留原文,剩余原样接上
if (!folded) return window;
out.addAll(window.subList(i, n));
return out;
}
UserMessage user = (UserMessage) window.get(i);
List<Message> body = window.subList(i + 1, nextUser);
// 末尾那条不含工具调用的 assistant 是结论,原文保留;它前面的才是要折的工具往返。
AssistantMessage conclusion = …;
List<Message> toolCallMessages = …;
if (!containsToolCall(toolCallMessages)) { // 本轮没有工具往返,整轮保持原文
out.add(user); out.addAll(body); i = nextUser; continue;
}
out.add(user); // 用户请求:完整保留(意图锚点)
out.add(summaryMessages(toolCallMessages)); // 工具往返 → 一条 assistant 摘要(无 toolCalls)
if (conclusion != null) out.add(conclusion); // 末尾结论:原文保留
folded = true;
total -= …; // 减掉这一轮省下的 token
if (total < threshold) { // 够了,后面的轮次不再折
out.addAll(window.subList(nextUser, n));
return out;
}
i = nextUser;
}
return folded ? out : window;
}两个实现要点:
第一,按一轮的边界来划分,不从一轮的中间切开。折叠的边界必须放在一轮结束的位置。这样被折叠的那段里,每个工具调用和它的结果都在同一段内一起被替换掉,不会出现调用被折叠、结果还留在窗口里的悬空。
第二,只替换中间的工具往返。用户请求和末尾结论都保留原文,只有中间那段来回的调用和结果被折成一条摘要。用户意图和这一轮的判断都还留在窗口里。
小结
第四层我们就讲完了。它不调用模型,就能减少不少 Token。如果折叠之后窗口仍然超过阈值,就要用到最后一层,也是成本最高的一层。下一节我们讲一下第五层自动压缩。
6.10 第五层:自动压缩(调模型摘要,替换内存历史)
本篇涉及到的源码列表:
com.minicc.compact.AutoCompactor.java
com.minicc.compact.CompactionPromptText.java
com.minicc.session.Session.java
上一节我们讲了第四层上下文折叠。它不调用模型,就把中间的工具往返替换成摘要。
这一节我们讲一下第五层自动压缩。它是整条链里唯一需要调用模型、成本也最高的一层,而且它是②–⑤里唯一会改写内存历史的一层。
自动压缩 做什么
窗口在折叠之后仍然大于等于 95%(配置里的 autoCompactAt)时,自动压缩触发。
它做这几件事:把整段历史交给模型做一次摘要,再用一条摘要消息加上最近两轮原文,整体替换掉内存历史。
替换用的是我们在 6.3 讲过的 Session.replaceHistoryInMemory。替换之后,内存历史变短,下一轮就不会再超过阈值,也就不会重复摘要。
它只修改内存,不修改 JSONL。完整原文仍在会话日志和 tool-results/ 里,/resume 读回的是全量。
先把历史渲染成纯文本再发
调模型做摘要,不能直接把带工具调用的原始消息发过去。
原因是:如果请求里带着工具调用、却没有带工具定义,在 OpenAI 兼容服务上会触发协议校验报错。
所以我们先把每条消息逐条渲染成一行可读文字,再作为普通用户消息发出去。
// 源码位置:com.minicc.compact.AutoCompactor.java
public List<Message> apply(List<Message> window, Session session) {
// 1) 组装"摘要请求":系统提示词 + 把待摘要历史渲染成纯文本的多条用户消息。
List<Message> summaryReq = new ArrayList<>();
summaryReq.add(new SystemMessage(CompactionPromptText.SUMMARY_PROMPT));
for (Message m : window) {
String text = toPlainText(m);
if (!text.isBlank()) {
summaryReq.add(new UserMessage(text));
}
}
// 2) 调模型(不带工具);若请求自身过长,走紧急压缩先丢最早一批再重试。
if (renderer != null) {
renderer.compactionNote("自动压缩:对历史做一次模型摘要…");
}
String summary = callWithEmergencyFallback(summaryReq);
// 3) 用"一条摘要用户消息 + 最近几条原文"组成新窗口。
List<Message> compacted = new ArrayList<>();
compacted.add(new UserMessage("[以下为此前对话的压缩摘要,完整原文在会话日志(JSONL)与 tool-results/ 中]\n" + summary));
compacted.addAll(recentOriginals(window));
// 4) session 非 null 时就地改写内存历史;刻意不动 JSONL。
if (session != null) {
session.replaceHistoryInMemory(compacted);
}
return compacted;
}toPlainText 把用户、assistant、工具结果三种消息各自渲染成一行,比如 assistant 的工具调用会写成「助手调用工具: Read(...)」这样的可读文字。
摘要提示词:只输出文字、固定分段
摘要的质量,靠一段固定的提示词来保证。这段提示词有两个要点。
一是强制模型只输出文字,不调用工具。自动压缩是一次性的受限调用,任何工具调用都会被拒绝。
二是把摘要固定分成九段,每一段都明确要求模型写什么。
// 源码位置:com.minicc.compact.CompactionPromptText.java
public static final String SUMMARY_PROMPT = """
重要:只用纯文本回答,不要调用任何工具……
摘要必须严格按下面九个小节组织,每节都要尽量完整准确:
1. 主要请求与意图:完整捕捉用户所有明确的请求与意图。
2. 关键技术概念:列出讨论到的重要技术概念、技术栈与框架。
3. 涉及的文件与代码:逐一列出查看、修改或新建过的文件与代码片段……
4. 报错与修复:列出遇到的所有报错,以及你是如何修复的……
5. 解题过程:记录已解决的问题,以及仍在进行中的排查。
6. 全部用户消息:逐条列出所有非工具结果的用户消息原话。这一段最重要……
7. 未完成事项:列出用户明确要求、但尚未完成的任务。
8. 当前正在做的工作:精确描述在本次摘要之前,你正在进行的具体工作。
9. 可选的下一步:如果有,列出与"最近工作"直接相关的下一步……
""";九段里第 6 段"全部用户消息"最关键。它要求模型逐条复述用户的原话,保证用户的原始意图不因摘要而丢失。
为什么要保留全部用户消息
模型做摘要时难免丢失细节,而用户的原话是意图最可靠的来源。所以自动压缩用两层来保留它。
第一层,摘要提示词第 6 段要求模型逐条复述全部用户消息。
第二层,recentOriginals 把最近两轮原样保留,接在摘要后面。
// 源码位置:com.minicc.compact.AutoCompactor.java
/** 保留最近几"轮"原文(一轮 = 一条用户消息 + 其后到下一条用户消息前的内容)。 */
private static final int KEEP_RECENT_TURNS = 2;
private List<Message> recentOriginals(List<Message> window) {
// 收集所有用户消息的下标
List<Integer> userIdx = …;
if (userIdx.isEmpty()) {
return List.of();
}
// 从倒数第 2 条用户消息处起,到窗口末尾。起点落在用户消息上,保证工具调用与结果成对。
int pick = Math.max(0, userIdx.size() - KEEP_RECENT_TURNS);
int keepFrom = userIdx.get(pick);
return new ArrayList<>(window.subList(keepFrom, window.size()));
}和折叠对比一下
折叠(第④层)和自动压缩(第⑤层)都保留用户消息,但分工不同。
折叠更早触发(90%),不调用模型,只把中间的工具往返替换成代码抽取的结构化摘要。这份摘要更粗,成本也更低,而且每一轮的结构都还在。
自动压缩更晚触发(95%),调用模型把较早的历史摘要成一段文字,只把最近两轮原文接在摘要后面,省略的内容更多。
所以它们是递进的:先用成本更低的折叠处理。折叠之后仍然超过阈值,才执行需要调用模型的自动压缩。
这次调用不进入会话历史
自动压缩调模型这件事,要特别说明一下。
它复用 ModelClient,和 M5 的轮末提取是同一种做法:一次性的受限调用,产出只是那段摘要文字。
摘要请求本身不写入会话历史,也不落盘。只有摘要产物会被写回内存历史,而且仍然不写入 JSONL。
正因为内存历史被换成了摘要加最近几条原文,占用下降了,下一轮就不会再超过阈值。只有占用再次达到 95% 时,才会再调用一次模型。
自动压缩我们就讲完了。但还有一个极端情况没有处理:万一这段历史长到连摘要请求本身都超限,应该怎么办?下一节我们讲一下紧急压缩兜底。
6.11 紧急压缩兜底
本篇涉及到的源码列表:
com.minicc.compact.AutoCompactor.java
上一节我们讲了第五层自动压缩,它调用模型把整段历史摘要成一段文字。
这一节我们讲一下紧急压缩。它处理的是一种极端情况:这段历史长到连摘要请求本身都超限时,应该怎么办。
什么时候会触发
紧急压缩不在每轮的链上。它只在一种情况下触发。
自动压缩(第五层)自己要把整段历史发给模型做摘要,结果这段历史已经长到连摘要请求都超限,模型返回 prompt_too_long。
到了这一步,前面几层已经来不及再起作用。程序只能直接丢弃最早的一批消息,用来腾出空间。
前四层通常已经把窗口降到阈值以下,为什么这里还会超限?
正常情况下,这种情况不会出现。前四层通常已经把窗口降到 95% 以下,紧急压缩很少触发。它的作用是最后一道保障:如果第五层自己的摘要请求也发不出去,程序不会中断,只是这次摘要更粗一些。
做法:丢最早一批,重试
紧急压缩的做法很直接:丢弃最早的一批消息,腾出空间再重试,直到请求能够发出。
它包在自动压缩调用模型的那一步里。
// 源码位置:com.minicc.compact.AutoCompactor.java
/** 紧急压缩最多丢弃多少批后放弃。 */
private static final int MAX_EMERGENCY_DROPS = 8;
private String callWithEmergencyFallback(List<Message> summaryReq) {
List<Message> req = summaryReq;
for (int attempt = 0; attempt < MAX_EMERGENCY_DROPS; attempt++) {
try {
AssistantMessage result = modelClient.call(req, List.of()); // 不带工具
return result.getText() == null ? "" : result.getText();
} catch (RuntimeException e) {
if (!isPromptTooLong(e)) {
throw e; // 别的错误照常抛
}
if (renderer != null) {
renderer.warn("历史过长,紧急压缩:丢弃最早一批消息后重试摘要…");
}
List<Message> dropped = dropEarliestBatch(req);
if (dropped.size() == req.size()) {
break; // 没得可丢了
}
req = dropped;
}
}
throw new IllegalStateException("紧急压缩后摘要请求仍过长,放弃本次自动压缩。");
}逻辑是一个循环:调模型,成功就返回;失败且是上下文过长,就丢一批再试。
最多丢 8 批。如果丢到没得可丢了,就放弃本次自动压缩。
怎么判断是"上下文过长"
模型报错的文案并不统一,所以我们沿着异常链查看消息文本。命中下面几种常见文案之一,就视为上下文过长。
// 源码位置:com.minicc.compact.AutoCompactor.java
private boolean isPromptTooLong(Throwable e) {
for (Throwable t = e; t != null; t = t.getCause()) {
String msg = t.getMessage();
if (msg != null) {
String lower = msg.toLowerCase();
if (lower.contains("prompt_too_long")
|| lower.contains("prompt is too long")
|| lower.contains("too long")
|| lower.contains("maximum context length")
|| lower.contains("context_length_exceeded")
|| lower.contains("context length")
|| lower.contains("reduce the length")) {
return true;
}
}
}
return false;
}只有命中这些文案才按上下文过长处理。其他错误继续向上抛出,不会被当成可以靠丢弃消息解决的问题。
它同样不修改原文
紧急压缩丢弃的,只是本次摘要请求里的消息副本。
M4 的 JSONL 原文仍然完整,内存历史也没有被修改。紧急压缩和前面所有层一样,不修改原文。
它处理的对象,是第五层临时构造出来的那个摘要请求,而不是会话历史本身。所以哪怕丢弃的内容再多,磁盘上的完整记录仍然还在。
到这里,五层压缩链加上紧急兜底,我们就全部讲完了。下一节我们来收尾,讲一下 /compact 命令及压缩配置。
6.12 compact 命令 + 配置
本篇涉及到的源码列表:
com.minicc.compact.CompactionManager.java
com.minicc.cli.command.CompactCommand.java
default-mcc.yml
前面几节我们把五层压缩链和紧急兜底都讲完了。这一节我们来收尾。
/compact:手动压缩一次
/compact 它和每轮自动压缩的区别是:它不看阈值,也不看空闲时长,强制把 Snip、微压缩、折叠、自动压缩都执行一遍。
而且它把每一层减少的 Token 都打印出来,方便你对照前面几节,看清每一层在做什么。
> /compact
⏺ 正在压缩上下文…
⎿ Snip:清理空结果 / 被拒绝的调用(182000 → 170000 Token)
⎿ 微压缩:清理较早可再取的工具结果(170000 → 150000 Token)
⎿ 上下文折叠:把较早对话折叠成结构化摘要(150000 → 120000 Token)
⎿ 自动压缩:对历史做一次模型摘要…
⎿ 自动压缩:对其余历史做一次模型摘要(已替换内存历史,JSONL 不动)(120000 → 96000 Token)
⎿ 压缩后:182.0k → 96.0k Token(估算)真正的编排在 CompactionManager.compactNow 里。它逐层调用,每调完一层就打印前后 Token。
// 源码位置:com.minicc.compact.CompactionManager.java
public void compactNow(Session session) {
List<Message> history = session.history(); // 大结果早在入库时就落过盘了
int before = TokenEstimator.ofMessages(history);
if (renderer != null) renderer.compactionStart();
List<Message> window = snip.apply(history); // ②Snip 起步(①不在投影链里)
note("Snip:清理空结果 / 被拒绝的调用", before, TokenEstimator.ofMessages(window));
int t = TokenEstimator.ofMessages(window);
window = micro.apply(window); // 手动时无视空闲,顺带清理可再取的旧结果
note("微压缩:清理较早可再取的工具结果", t, TokenEstimator.ofMessages(window));
t = TokenEstimator.ofMessages(window);
window = collapser.apply(window); // 强制折叠(不看阈值)
note("上下文折叠:把较早对话折叠成结构化摘要", t, TokenEstimator.ofMessages(window));
t = TokenEstimator.ofMessages(window);
window = auto.apply(window, session); // 强制自动压缩(调模型;就地改写内存历史)
note("自动压缩:对其余历史做一次模型摘要(已替换内存历史,JSONL 不动)", t, TokenEstimator.ofMessages(window));
int after = TokenEstimator.ofMessages(window);
if (renderer != null) renderer.compactionSummary(before, after); // 打印"X → Y Token"
}这里要注意,它同样从第②层 Snip 起步。第①层不在这里,因为大结果在入库时就已经完成落盘。
这里的第⑤层自动压缩同样通过 replaceHistoryInMemory 改写内存历史,后续轮次直接看到这份"摘要加最近两轮原文"。
命令本身很简单。历史为空时,它会提示一句;否则就调用 compactNow。
// 源码位置:com.minicc.cli.command.CompactCommand.java
@Override
public boolean run(String args) {
if (session.history().isEmpty()) {
renderer.info("当前会话历史为空,无需压缩。");
return false;
}
compactionManager.compactNow(session);
return false;
}配置
M6 新增两组配置,都有比较合理的默认值,不配置也能运行。
# 源码位置:default-mcc.yml
contextLimit: 200000 # 上下文窗口上限(Token);M6 起作为所有百分比阈值的分母
compact: # M6 新增:分层压缩的触发阈值
collapseAt: 0.90 # 上下文折叠触发(窗口占用比例)
autoCompactAt: 0.95 # 自动压缩触发(需要调用模型)
microcompactIdleMinutes: 60 # 会话空闲多久后才做微压缩
keepRecentToolResults: 5 # 微压缩保留最近几次工具结果
toolResultBudget: # M6 新增:各工具结果落盘阈值(字符数)
Read: -1 # -1 表示无限大,永不落盘
Bash: 30000
Grep: 20000
Edit: 100000
Write: 100000
Glob: 100000有两点值得说明。
一是压缩默认一律开启,不设总开关,因为它是 M6 的核心能力。
二是 contextLimit 从 M1 起就在配置里,但一直只作记录。到 M6 才真正用到它:它是所有百分比阈值的分母。
本章小结
到这里,M6 就完整了。
我们为 Agent 增加了应对长上下文的能力。五层压缩链按成本从低到高排列,前面的层释放出足够空间后,后面的层就不再执行。接近上限时,它会按层自动精简,另外还有一层紧急兜底。
最关键的一条是:压缩幅度再大也不丢原文。普通消息在 JSONL,超大结果在 tool-results/,/resume 读回来始终是全量。
这个 Agent 第一次能稳定地跑长任务了。下一章我们进入 M7,来讲一下 Skills:把可复用的专业能力分成按需加载的技能文件。这和 M5 的记忆索引一样,都是渐进式披露。
