ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 压缩产物:CompactionResult、图片省略与工具结果剪枝怎么读

插件开发发布于 2026-11-12作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness压缩CompactionResult工具结果剪枝
压缩后内容少了,却说不清少了什么、能不能恢复。本文讲 compaction/* 三个日志事件与锁语义、summary 载荷如何重建一次调用、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 声明及其纯消息投影。每个目标指定当前输入节点与按深度优先计数的确切图片位置:

ts
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 降了。(来源) 六步:

  1. 构造一个含图片与超长工具输出的会话,记录压缩前的 shadowedSeqs 候选。
  2. 执行一次压缩,断言日志里 start、summary、end 三条事件齐全,且顺序正确。
  3. 断言 shadowedSeqs 与实际的表层被遮蔽节点一一对应,而不是按 seq 区间推算。
  4. 在摘要期间强杀进程,重启后断言遗留锁可被检测(有 start 无 end),且不会被当成已完成。
  5. 单独跑一次工具结果剪枝,断言 charsRemoved 等于各条 charsBefore - charsAfter 之和。
  6. 构造一次图片省略,断言节点顺序未变、没有新增 surface 事件,且投影结果与目标 imageIndexes 对应。

如果第 3 步对不上,先检查是否拿 shadowedRange 做了数值区间遍历。位置跨度与数值区间在替换过的会话里不是一回事。

压缩的触发与报错恢复,可以对照压缩机制说明;被压缩源在引用侧的读法,见引用已压缩的源会话。

一句话收束: 三个事件只写日志,锁最后释放才可信,摘要靠 user/message 进 surface,范围只认 shadowedSeqs,剪枝与图片省略都不改表层结构。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 的 compaction/summary 会直接进模型历史吗?

不会,DSH plugin 的三个 compaction 事件都只写日志。DSH plugin 让摘要本身承载在另一条带 replace surfaceOp 的 user/message 上,那才是唯一的 surface 变更。

DSH plugin 的 shadowedRange 能直接当数值区间用吗?

不能,DSH plugin 明确它是表层位置跨度而非数值区间。DSH plugin 在之前发生过替换时,start 可能大于 end,权威的被遮蔽节点集合要看 shadowedSeqs。

DSH plugin 的图片省略会带 surfaceOp 吗?

不会,DSH plugin 的 image/offload 事件保留节点与消息身份,但不携带 surfaceOp。DSH plugin 通过纯消息投影解释被省略的图片,而不是新增一条 surface 事件。

DSH plugin 的工具结果剪枝和压缩是同一件事吗,区别在哪?

不是,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

来源