ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 引用被截断后:omittedMessages、omittedBytes 与 spill 定位符

插件开发发布于 2026-11-10作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness会话引用截断spill
模型说没看到前面内容,界面却没有任何提示。本文讲截断时持久 source 记录的五个事实字段、truncated 与 compacted 的区别,以及 spill 定位符和不可用提示该怎么用。

截断不是静默失败:DSH plugin(DSH插件) 会在持久 source 里留下 truncated、omittedMessages、omittedBytes,并尽量给出完整快照的 spill 定位符。 模型说「没看到」,界面却毫无提示,问题在你的宿主没读这些字段。

DSH plugin 模型说没看到前面内容

这是截断的典型症状,不是模型理解力问题。(来源) 现场:

text
用户引用了一个长会话
模型回答:「我只看到了后半段」
界面:没有任何省略提示

如果 source 记录里 truncated 为 true,说明准备阶段确实省略了内容。模型没有说谎,是界面没有把事实转达给用户。

判断顺序应该是:先看 truncated,再看省略量,最后才讨论模型行为。

DSH plugin 持久 source 的五个事实字段

五个字段,分别回答「有没有缺」「缺多少」「缺在哪」。(来源) 对照:

字段含义
originalMessages源会话消息总数
retainedMessages本次保留的消息数
omittedMessages本次省略的消息数
omittedBytes本次省略的字节数
truncated是否发生截断

它们记录在 source 的每个 reference 项里,而不是整条上下文一个汇总值。

这意味着引用多个会话时,可以分别看到每个会话被省略了多少。

DSH plugin 的 omittedMessages 与 omittedBytes 怎么读

两个维度一起看,才不会被平均值误导。(来源) 三种组合:

  1. 条数少、字节多 — 省略的是长消息,影响可能很大;
  2. 条数多、字节少 — 省略的是短交互,影响相对小;
  3. 两者都大 — 预算明显不足,应提示用户缩小引用范围。

只看条数会低估第一种情况,只看字节会低估第二种。产品提示文案最好两个都给。

一个实用阈值:当 omittedBytes 超过保留量的某个比例时,直接在引用卡片上显示「已省略」标记。

DSH plugin 的 truncated 与 compacted 的区别

一个说本次,一个说源端,混用会归因错误。(来源) 对照:

字段来源处理方向
compacted源会话已压缩换源会话或接受缺口
truncated本次预算不足缩小引用范围或换大模型

如果两个都为 true,说明源端先压缩、本次又截断,缺口叠加。

排查时先看 compacted:源端已经压缩的情况下,再怎么调预算也读不回被压缩掉的内容。

DSH plugin 的 spill 定位符与不可用提示

能找回就给位置,找不回就明说。(来源) 规则:

  • 截断预览会包含省略事实与完整快照的 spill 定位符;
  • 定位符不可用时,返回明确的不可用提示;
  • 不要用空字符串或 null 伪装「没有截断」。

第三点最重要:缺失与不可用是两种状态,用同一个值表示会让排查无从下手。

宿主应该把这两种状态分别映射到不同文案,例如「已省略,可查看完整快照」与「已省略,完整快照暂不可用」。

DSH plugin 截断可见性的验证

五个断言,覆盖字段、可见提示与定位。 步骤:

  1. 构造超预算引用,确认 truncated 为 true;
  2. 确认 originalMessages = retainedMessages + omittedMessages;
  3. 确认 omittedBytes 大于零;
  4. 确认界面出现省略提示,而不是静默;
  5. 若返回 spill 定位符,确认能据此找回完整快照。

第 2 步是最容易写错的断言:三个计数的关系不成立,说明记录逻辑有 bug。

第 4 步是产品层断言:字段再全,不展示给用户也等于没有。

截断提示应该出现在引用卡片上,而不是只躺在开发日志里;用户看不到,就等于没有发生。

截断讲清楚后,下一步是源端压缩。读 DSH plugin 引用已压缩的源会话;想看预算从哪里来,读 DSH plugin 会话引用的预算与 64 KiB 回退;想先看全貌,读 DSH plugin 怎么完整实现会话引用。

来源:DeepSeek Harness 官方参考 - 会话引用、session-reference/src/types.ts

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 引用之后模型说没看到前面的内容,从哪里确认被截断了?

看 DSH plugin 持久 source 里的 truncated 字段。DSH plugin 在截断时还会记录 omittedMessages 与 omittedBytes,三个字段一起才能说明省略了多少。

DSH plugin 的 omittedMessages 和 omittedBytes 有什么区别?

DSH plugin 的 omittedMessages 是条数,omittedBytes 是字节量。DSH plugin 用两个维度描述缺口,避免「条数很少但内容很长」的情况被低估。

DSH plugin 的 truncated 和 compacted 都是 true,是同一个意思吗?

不是,DSH plugin 用两个字段分别记录源端压缩与本次截断。compacted 表示源会话在捕获前已经压缩,truncated 表示本次准备因预算省略了内容;DSH plugin 把两者分开记录,便于判断缺口来自源端还是本次。

DSH plugin 截断后提到的 spill 定位符是什么,能直接读吗?

它是 DSH plugin 完整快照的定位信息,用于后续找回被省略的内容。DSH plugin 会同时给出省略事实;如果定位不可用,会返回明确的不可用提示,而不是让调用方猜。

相关术语

truncated
truncated 是持久 source 中的布尔字段,表示本次准备是否因预算省略了部分内容。— DeepSeek Harness 官方参考 - 会话引用
omittedMessages
omittedMessages 是截断时被省略的消息条数,用于衡量缺口的规模。— DeepSeek Harness 官方参考 - 会话引用
omittedBytes
omittedBytes 是截断时被省略的字节量,补足条数无法体现的内容体积。— DeepSeek Harness 官方参考 - 会话引用
spill 定位符
spill 定位符是指向完整快照的定位信息,用于在截断后找回被省略内容。— DeepSeek Harness 官方参考 - 会话引用

来源