DSH plugin 压缩产物:CompactionResult、图片省略与工具结果剪枝怎么读
压缩之后最该问的不是“少了多少 token”,而是“少的这一段还能不能被重建”。 DSH plugin 的压缩把答案拆在三个日志事件里:锁、摘要与闭合。看懂这三个事件,才知道一次压缩是完成了、失败了,还是崩在中途。 DSH插件 排查压缩后少了什么,先看 shadowedSeqs,别拿区间做算术。
三个事件只写日志,不进 surface
compaction/* 是日志事实,真正改变模型视野的只有那条替换用的 user/message。(来源)
压缩通过声明合并给 SessionEventMap 加三种事件:compaction/start、compaction/summary、compaction/end。三者都仅写入日志——记录锁、摘要、选中范围、被遮蔽事件 seq、token 数与模型调用,绝不进入 surface。它们有意不扩展 SurfaceEventType,因为只有产生消息的事件才会到达模型。
摘要本身因此承载在另一条 user/message 上,带 surfaceOp: { op: 'replace', startSeq, endSeq }。这是摘要压缩执行的唯一 surface 变更;理解这一点,就不会去 compaction/summary 里找“模型看到了什么”。
锁的顺序是刻意设计的:先追加 compaction/start,再执行摘要生成、写入 compaction/summary 与 user/message 替换,最后才追加 compaction/end。最后释放锁意味着操作中途崩溃会表现为可检测的遗留锁——有 start 而没有匹配的 end,而不是一个虚假声称压缩已完成的 end。
锁标记是时间点,不是排他容器。摘要等待期间,不相关的空闲注入可以出现在独立的手动 start 与 end 之间;手动路径只重新验证所选位置 span,因此替换检查点之后仍会保留该注入上下文。活动的未匹配 start 会阻塞所有入口点;而较新 session/end-seed 之前的未匹配 start 属于先前生命周期留下的陈旧证据,会被忽略。
summary 载荷能重建一次调用
它不只记结果,还记“这次摘要到底发了什么请求”。(来源)
compaction/summary 的载荷包含:summary、可选 rawOutput、可选 llmStreamCall、shadowedRange、shadowedSeqs、shadowedTokenCount、provider、model、可选 maxTokens 与可选 usage。
几个字段的关系要看清:
llmStreamCall: true表示生成结果时恰好通过此上下文的ctx.llm.stream()发起过一次调用,此时必须提供完整的rawOutput;- 未带该标记的
rawOutput并不能判定调用路径; provider、model与可选maxTokens构成摘要调用的 envelope,写入日志后,这次一次性请求可由日志加代码重建;shadowedRange是被遮蔽的 surface 边界对,即位置跨度,而非数值区间。
最后一条在排查时最能救命。如果你拿 start 与 end 做数值比较来判断“压缩了多少条”,在发生过替换的会话里会算错。
CompactionResult 里哪个字段才是权威
范围看 shadowedSeqs,不要自己拿 range 做算术。(来源)
成功压缩返回的 CompactionResult 有七个字段:compactionId、可选 sourceCommandId、startSeq、summarySeq、endSeq、summary、shadowedRange、shadowedSeqs 与 shadowedTokenCount。
compactionId 是这次压缩完整持久生命周期的稳定身份;手动压缩还会带 sourceCommandId。三个 seq 指向三条追加事件,适合做日志定位。shadowedRange 的注释写得很明确:它是表层位置跨度;当此前的 replace 把一个高 seq 的摘要节点放到旧区间的位置上时,start 可以大于 end。shadowedSeqs 才是权威的被遮蔽节点集合,按 surface 顺序排列。
三个入口的产物形态也略有差别:compactIfNeeded(agent, trigger, signal) 在没有安全范围可压缩时返回 null;compactNow(agent, signal) 作为轮次之间的 agent maintenance 运行,没有有效范围时同样返回 null 且不写入;compactRegion(start, end, agent, signal?) 强制压缩一个两端包含的表层区间,边界不平衡会直接拒绝。三者在成功时都返回 CompactionResult。
手动压缩的失败有六个预期错误码:busy、cancelled、changed、summary、commit、persistence。其中 changed 与 summary 会闭合失败尝试并持久化到日志,但不写入摘要替换;恢复过程中记录的图片省略仍然有效。commit 可能发生在部分变更之后;persistence 表示内存中的标记对已闭合但 flush 失败。取消独立于这些失败,会在完成必要清理后抛出原始 abort 原因。
图片省略是事件加纯投影
它不改 surface 结构,只解释“这张图为什么不在了”。(来源)
compaction-image-offload 拥有 image/offload 声明及其纯消息投影。每个目标指定当前输入节点与按深度优先计数的确切图片位置:
interface ImageOffloadTarget {
seq: SessionSeq
imageIndexes: number[]
}
关键约束是:事件保留节点与消息身份,不携带 surfaceOp。所以它不会新增一条 surface 事件,也不会改变节点顺序;读取方通过纯投影把指定位置替换为占位表示。
这与 LlmFailure.offloadImages 是配套的:当失败码是 IMAGE_OFFLOAD_REQUIRED 时,路由会告诉压缩还需要卸载多少个最老的保留图片;dsh-compaction-image-offload 记录选中的出现位置并重试该步骤。
工具结果剪枝与压缩是两件事
剪枝只改文本长度,压缩才改表层结构。(来源)
可选的工具结果剪枝服务做的是确定性的头/中/尾裁剪,只作用于当前表层的工具结果节点。三个方法边界清晰:
measureContent(blocks)— 按 Unicode code point 计量文本,非文本块计零;pruneContent(blocks)— 超预算时替换中间文本并保留富块顺序;切片按 code point 而不是 UTF-16 代码单元,因此保留边界不会切开代理对,但字素簇仍可能被切开;pruneSession(session)— 对一份稳定的当前表层快照,剪掉每个超预算工具结果。
落地记录在 PrunedEntry 里:originalSeq、replacementSeq、callId、charsBefore、charsAfter。每次替换保留除 content 外的完整事件数据,引用被遮蔽节点以便回放恢复输入,并且紧邻前面会有一条 compaction/prune 影子价事件,通过注入的 token meter 给被遮蔽节点定价,使纯消费方无需逐节点状态就能扣减。
pruneSession 的错误语义也要记住:如果会话拒绝某次替换就抛错,但本次过程中更早提交的替换仍然持久。所以失败后不要假设“什么都没变”。
验证:含图片与长工具输出的会话
验证压缩产物要逐项断言,而不是只看总 token 降了。(来源) 六步:
- 构造一个含图片与超长工具输出的会话,记录压缩前的
shadowedSeqs候选。 - 执行一次压缩,断言日志里 start、summary、end 三条事件齐全,且顺序正确。
- 断言
shadowedSeqs与实际的表层被遮蔽节点一一对应,而不是按 seq 区间推算。 - 在摘要期间强杀进程,重启后断言遗留锁可被检测(有 start 无 end),且不会被当成已完成。
- 单独跑一次工具结果剪枝,断言
charsRemoved等于各条charsBefore - charsAfter之和。 - 构造一次图片省略,断言节点顺序未变、没有新增 surface 事件,且投影结果与目标
imageIndexes对应。
如果第 3 步对不上,先检查是否拿 shadowedRange 做了数值区间遍历。位置跨度与数值区间在替换过的会话里不是一回事。
压缩的触发与报错恢复,可以对照压缩机制说明;被压缩源在引用侧的读法,见引用已压缩的源会话。
一句话收束: 三个事件只写日志,锁最后释放才可信,摘要靠 user/message 进 surface,范围只认 shadowedSeqs,剪枝与图片省略都不改表层结构。
常见问题
不会,DSH plugin 的三个 compaction 事件都只写日志。DSH plugin 让摘要本身承载在另一条带 replace surfaceOp 的 user/message 上,那才是唯一的 surface 变更。
不能,DSH plugin 明确它是表层位置跨度而非数值区间。DSH plugin 在之前发生过替换时,start 可能大于 end,权威的被遮蔽节点集合要看 shadowedSeqs。
不会,DSH plugin 的 image/offload 事件保留节点与消息身份,但不携带 surfaceOp。DSH plugin 通过纯消息投影解释被省略的图片,而不是新增一条 surface 事件。
不是,DSH plugin 把两者分开实现。DSH plugin 的剪枝只处理当前表层里超预算的工具结果文本,压缩则用摘要节点替换一段表层范围。
相关术语
- compaction/start
- compaction/start 是压缩开始时追加的日志事件,携带 turn 归属,数字表示未结束的自动轮次,null 表示独立手动尝试。— packages/compaction/compaction/src/types.ts
- shadowedSeqs
- shadowedSeqs 是被遮蔽的全部表层节点 seq,按 surface 顺序排列,是判断压缩范围的权威集合。— packages/compaction/compaction/src/types.ts
- CompactionResult
- CompactionResult 是一次成功压缩返回的结果,含事务 id、三个事件 seq、摘要、被遮蔽范围与 token 统计。— packages/compaction/compaction/src/types.ts
- PrunedEntry
- PrunedEntry 是一次工具结果剪枝落地的记录,含原事件 seq、替换事件 seq、callId 与前后 code point 数。— packages/compaction/compaction-tool-result-pruner/src/types.ts
来源
- DeepSeek Harness 官方参考 - 压缩· deepseek-ai
- packages/compaction/compaction/src/types.ts· deepseek-ai