在与 AI 的多轮对话中,常出现模型遗忘早期关键指令(如“本项目禁用 TypeScript”)的情况。这通常源于上下文压缩机制未能妥善保留关键约束。当上下文窗口满载时,系统需腾出空间,若将核心约束误判为闲聊丢弃,便会导致此类问题。
这一难点在于:系统需在未知后续提问内容的情况下,预判并决定当前可丢弃的信息。通过对 DeepSeek Harness 源码的深入分析,其解决方案分为三层策略:优先避免压缩;若必须压缩,仅处理最旧片段;并在压缩过程中通过固定的八段式结构强制模型保留关键信息。
前提:压缩是可选策略
ctx.compaction 被定义为一种能力接口(capability seam),官方明确指出其不属于 Agent 循环的主干流程。
若不加载此插件,运行时仍可正常工作,仅会在上下文满溢时停止响应。默认配置(dsh base)启用 compaction-basic 后端,但用户可根据需求替换为基于分词器、基于模板的实现,或直接禁用。
这一设计定位至关重要:压缩是一种可替换的策略,而非固定机制。 不同场景对压缩内容与程度的需求差异巨大,模块化设计提供了灵活性。
触发机制与阈值设定
默认触发阈值的计算逻辑如下:
W 为上下文窗口大小
O 为当前请求的实际输出上限
B 为预留缓冲空间(Headroom),默认 65,536 tokens
在保留策略上,默认保留最新 16% 的内容(即 W − O 的 16%)作为逐字保留区。
取 min 值是关键步骤。仅参考 80% 窗口利用率并不足够,若输出上限较大,80% 位置可能无法容纳输出内容。因此,需同时减去输出量和缓冲空间,采取更保守的算法。
配置校验十分严格:若 headroom 为零,必须显式指定正的 maxTokens;保留比例不得大于或等于阈值比例;retainRatio 和 retainTokens 两种保留形式不可同时配置。任何违反规则的操作将导致插件加载失败。
此外,modelPolicies 支持按 Provider/Model 单独配置阈值。当后端服务多个不同上下文大小的模型时,无需被迫使用统一参数。
需注意,官方在开发文档中指出:
Default ratios, undecided ——thresholdRatio: 0.8和retainRatio: 0.16仅为固定默认值,缺乏语料支撑的调参指导。
因此,这些数值应视为经验值,而非金科玉律。
核心机制:遮蔽而非删除
这是该方案与简陋实现的核心区别。压缩过程不删除任何数据。
鉴于 Session Log 采用追加写入(append-only)模式,压缩完全遵循此规则:它追加一条新的 user/message,并携带 surfaceOp: { op: 'replace', startSeq, endSeq } 操作指令。
原始事件仍保留在日志中,只是不再出现在“模型可见的表面视图”上。官方术语称为 shadowed(被遮蔽),shadowedSeqs 字段完整记录了被遮蔽的序列号。
这一设计的实际优势在于:事后复盘时可完整追溯“模型当时所见内容”。压缩本质上是一种投影操作,而非破坏性操作。
配套的三个事件 compaction/start、compaction/summary、compaction/end 均为 log-only,不进入模型转录记录。官方特意说明 SurfaceEventType未进行扩展——仅有产生消息的事件才能到达模型。
锁释放顺序的设计考量
三个事件的执行顺序严格固定:
首先追加 compaction/start(加锁),随后生成摘要,记录 compaction/summary,落地 user/message 替换操作,最后才追加 compaction/end(释放锁)。
官方解释如下:
最后释放锁可将中途崩溃转化为可检测的孤儿锁(有 start 无配对 end),而非留下一个谎称压缩已完成的 end。
若中途崩溃,下次启动时发现未闭合的 start 即可判定异常。若先释放锁,崩溃现场将留下“一切正常”的假象。
反直觉的细节:Start 大于 End
shadowedRange 的 start 可能大于end。
这并非 Bug,而是因为其为表面位置的跨度,而非数字区间。若之前已进行过压缩,一个较大序列号的摘要节点可能位于较老的位置。再次压缩时,该位置区间的首尾序列号可能反转。
因此,官方明确指示:shadowedSeqs 是被遮蔽节点的权威集合,按表面顺序排列。切勿通过 start/end 进行数值比较。
结构化摘要:八段式强制规范
确保关键事实不被遗漏的核心,在于发送给摘要模型的指令。该指令要求输出严格固定的八个小节,顺序不可变,空缺需填写 (none),严禁整段删除:
|
|
|
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
单个
(none)
|
|
|
|
指令中包含若干硬性要求:
Preserve exact file paths, commands, error strings, identifiers, numeric values, function signatures, and syntax fragments.
精确保留路径、命令、报错字符串、标识符、数值、函数签名及语法片段。
Capture user feedback and explicit instructions faithfully, especially corrections.
忠实记录用户反馈和明确指令,尤其是纠正性指令。
前文提到的“禁用 TypeScript”例子,正是依靠 Critical Context 及“尤其是纠正”这一规则得以保留。
为防止摘要退化,若对话中已存在 <compacted-summary> 块(即上一次检查点),禁止原样复制——需保留仍成立的事实,丢弃过时信息,并将新信息合并至同一结构中。
否则,多次压缩后摘要将变为层层嵌套的旧摘要堆砌。
前置优化:工具结果剪枝
compaction-tool-result-pruner 是一个可选的前置环节,具有极高的性价比。
其功能是对超预算的工具结果进行确定性的“头/中/尾”裁剪——保留开头和结尾,移除中间部分。
该模块具备三个显著特点:
第一,零模型调用。 纯本地字符串操作,无成本且零延迟。
第二,可能免除摘要。 官方指出:裁剪后若对话落回阈值以内,可直接跳过摘要步骤,完全消除摘要必要性。
第三,按需触发。 仅在触发阈值后运行,“低于压力的对话永远不会被触碰”,避免无故修改工具输出。
细节方面:切分基于 Unicode 码点而非 UTF-16 码元,避免切断代理对。但官方也承认边界情况:字形簇(grapheme cluster)仍可能被切开,即某些 Emoji 组合可能会破碎。
裁剪同样遵守遮蔽规则:每条替换均引用被遮蔽的原节点,并紧随一条 compaction/prune 影子定价事件。
缓存优化技巧
摘要需单独发起一次模型请求。组装方式如下:
答案是将对话原样重放——使用相同的 System Prompt、工具 Schema 及消息,与上一次真实请求逐字节一致,仅在末尾追加压缩指令。
此举带来的直接好处是:
the provider's warm prefix cache is reused up to the trailing instruction; only that instruction, and the summary output, is uncached.
提供方的热前缀缓存可复用至末尾指令处。仅指令本身和摘要输出未命中缓存。
这意味着,压缩产生的额外模型调用中,绝大部分 Token 享受缓存读取价格。
代价也很明确:若将摘要路由至其他 Provider/Model,或压缩非头部区间,则无法享受此复用优势。
方案优劣势分析
优势:压缩不破坏历史。
Append-only 结合遮蔽机制,使本质上有损的“压缩”在存储层面变为无损。审计、复盘及重放功能均可正常使用。
优势:分层止损策略。
先剪枝(免费)→ 不足再摘要(一次模型调用)→ 仍不足则报错。溢出恢复走独立路径:收到 Provider 确认的 CONTEXT_WINDOW_EXCEEDED 后,绕过正常阈值和保留策略,进行最大化头部削减并重试。
区分正常压力与真正溢出,采用两套策略,极具实用价值。
优势:结构化摘要可靠性高。
八个固定小节配合“空缺写 (none)”的强制要求,远优于模糊的“请总结对话”。它将“勿漏待办事项”等要求转化为模型必须填充的结构化字段。
劣势:部分对象不可压缩。
官方明确指出:压缩无法缩小 System Prompt、工具 Schema、会话前缀,无法切割不可分割的非工具节点,也无法修复“非可裁剪剩余部分仍然超窗”的工具单元。
换言之,若 System Prompt 占据窗口大半,或某次工具返回巨大的不可切分对象,压缩机制将失效。
劣势:计量估算偏差,对中文不友好。
Token 计量的固定启发式算法为每 Token 四个字符,官方承认该算法严重低估中文和 JSON Schema。
阈值判断基于此估算。因此,在中文对话中,实际 Token 数可能远超估算值,导致压缩触发滞后。中文用户需特别留意此风险。
劣势:摘要失败时选择“带病继续”。
在替换落地前,若摘要失败,自动路径仅记录警告,并带着超预算的完整历史继续运行。
此选择虽可理解(优于破坏历史),但意味着下一次请求极大概率直接遭遇上下文溢出。
此外,compactRegion要求存在一个开放的 Turn,在完全关闭的会话上手动调用将抛出 "no open turn" 错误。
本文依据 0.1.7-alpha.1 快照的 docs/subsystems/compaction.md、spill.md 和 compaction-basic 包 README 编写。
总结与洞察
这套压缩设计最值得借鉴之处,并非触发公式,而是其对“压缩”的定位:压缩是投影,而非删除。
接受此前提后,诸多难题迎刃而解。无需备份,原件本就存在;压错可回滚,只需撤销 replace 操作;审计模型视野,重放日志至相应版本即可。
反之,若实现方式为“从数组中 splice 掉旧消息”,上述每个问题都需单独解决。
其次值得借鉴的是八段式表格。
许多“让模型总结”的实现产出质量不稳定。将其转化为必填表格,加上“空缺写 (none),严禁删除小节”的规则,相当于为自由发挥套上了 Schema 约束。
此思路适用于所有“让模型产出结构化内容”的场景:与其祈祷模型不遗漏,不如提供一张必须填满的表。
最后的 KV Cache 技巧同样巧妙。摘要请求逐字节复用上一次前缀,将昂贵的额外调用成本压低至仅支付输出费用。这种优化唯有在请求装配确定性的前提下才可实现——再次印证了“模型所见一切必须能从日志重建”的价值。
延伸阅读
compaction-basic 包参考:https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/compaction/compaction-basic/README.md

