ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 会话引用没带上怎么查:四步从持久记录反推 compacted 与 truncated

插件开发发布于 2026-11-10作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness会话引用排查持久记录
用户说「引用没带上」,日志里却是一条成功记录。本文给一个固定排查顺序:先看 references 是否为空,再看版本与压缩标记,再比对计数与截断,最后确认坐标归属。

在 DSH plugin(DSH插件) 里,「引用没带上」最常见的样子是:用户说没看到,日志里躺着一条成功记录。 成功只说明 prepare 跑完了,不说明内容进了上下文。要定位,得按固定顺序读持久记录,而不是先怀疑模型。

DSH plugin 成功记录能说明什么

它能说明三件事,不能说明另外三件事。(来源) 对照:

能说明不能说明
prepare 被调用并完成用户的选择真的传进来了
引用被写入持久记录内容完整,没有源端缺口
返回了结果对象additionalContext 被发布给模型

第三行是很多误判的起点:返回成功与「模型看到」之间还有一步发布。

所以第一步不是看模型日志,而是看记录里的字段。

DSH plugin 排查顺序为什么不能换

四步之间有依赖,跳步会得到相反结论。 顺序:

  1. references 是否为空;
  2. capturedFormatVersion 与 compacted;
  3. 三类消息计数与 truncated;
  4. capturedThroughSeq 的归属。

如果第 1 步就为空,后面三步全是在分析一个不存在的引用。

如果跳过第 2 步直接看计数,会把源端压缩的缺口误判成本次预算不足。

顺序本身就是方法:每一步只回答一个问题,答完再走下一步。

DSH plugin 第一步:references 是不是空的

空数组意味着内容从来没进来,与预算无关。(来源) 三个常见原因:

  • 前端把 mention 留在输入框文本里,没有解析成 SessionReferenceInput;
  • 你的宿主序列化消息时只带了 content,把 references 丢了;
  • 调用方用自动补全做了 UI,但提交时没有把选中项传下去。

DSH plugin 不会从正文里的 dsh-session: 字符串反推引用;输入必须显式给出。

判断很快:记录里没有 reference 项,就不必再看后面的字段。

修复点在宿主层:提交时校验「正文含 mention 但 references 为空」,直接拦住这种请求。

DSH plugin 第二步:版本与压缩标记

先确认这条记录能被正确解释,再看内容规模。(来源) 两个字段:

  • capturedFormatVersion 缺失 → 按格式 v0 读,不要当成未知或损坏;
  • compacted: true → 源会话在捕获前已压缩,早期内容本来就不在可读范围。

第二项决定了后续判断的方向:源端已压缩时,「内容少」是正常事实,不是 bug。

这一步还能发现另一类问题:记录由更新版本写入,而当前实现按老格式硬解,字段读出来全是空值。

看到空值先别下结论,确认版本分派是否正确。

DSH plugin 第三步:计数与截断

三个数加一个布尔值,把「缺多少」说清。(来源) 判断:

text
originalMessages = retainedMessages + omittedMessages

再配合 truncated:

现象结论下一步
计数对不上记录逻辑异常查写入侧,不看模型
omittedMessages 大、truncated 为 false源端压缩缺口换会话或引用更早内容
truncated 为 true本次预算省略调整预算或缩小范围
两者都成立缺口叠加先处理源端,再处理预算

第三种情况要结合预算来源看:自动预算取的是最后组装的 route,route 变了,截断点也会变。

DSH plugin 第四步:坐标归属

定位失败先问「这是谁的 seq」,再问「存得对不对」。(来源) 三条检查:

  1. capturedThroughSeq 是否与源 sessionId 成对存储;
  2. 定位时是否用源会话身份打开;
  3. 坐标缺省时,宿主是否错误地展示了第 0 条。

第二条是最高频的错:用当前会话解释源坐标,必然落在无关位置。

第三条属于展示层问题:缺省应该显示「位置未知」,而不是一个具体数字。

坐标本身没有对错,只有归属;归属错了,数值再准也没用。

DSH plugin 复现一次的最小步骤

四步复现,每步留一个可观察结果。 步骤:

  1. 用同一份夹具重放那次请求,确认 references 条数与用户选择一致;
  2. 打印 capturedFormatVersion 与 compacted,确认解释路径正确;
  3. 打印三类计数与 truncated,确认减法成立;
  4. 用源会话身份按坐标定位,确认落点与快照末条一致。

四条都过,说明记录侧没有问题,应转向发布与展示环节。

任何一条不过,就先修这一条,别继续往下猜。

需要补字段定义的细节,读 DSH plugin 引用被截断后的五个事实字段、DSH plugin 引用已压缩的源会话;想理解坐标,读 DSH plugin 的 capturedThroughSeq 属于源 generation;想从记录结构入手,读 DSH plugin 的 recall 记录怎么读。

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

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 记录显示引用成功,但模型说没有内容,先查什么?

先看 DSH plugin 记录里的 references 是否为空。为空说明选择没有传到 prepare;非空再看 compacted 与 truncated,判断内容是本来就没有,还是在准备阶段被省略。

DSH plugin 里 references 为空一般是什么原因?

DSH plugin 里 references 为空常见有三种原因:前端只把 mention 留在文本里、宿主序列化时丢了 references、调用方只传了 content。DSH plugin 不会从正文猜引用。

DSH plugin 的 compacted 和 truncated 都为 true,排查应该先处理哪个?

先处理 compacted,它是 DSH plugin 记录里的源端压缩标记。源端已压缩意味着那段历史本来就读不到,调预算无效;确认没有源端缺口之后,再看 truncated 对应的本次预算是否合理。

DSH plugin 里坐标定位失败,一定是 capturedThroughSeq 存错了吗?

不一定,先确认 DSH plugin 的坐标是否用源会话身份打开。先确认定位时用的是源会话身份。DSH plugin 的 capturedThroughSeq 属于源 generation,用当前会话去解释它,必然定位到错误位置。

相关术语

references 空数组
references 空数组表示这次 prepare 没有收到任何会话引用,上下文自然不会有内容。— DeepSeek Harness 官方参考 - 会话引用
成功记录(success record)
成功记录只说明 prepare 完成且引用被写入,不代表内容一定进入了模型可见上下文。— session-reference/src/types.ts
排查顺序(diagnostic order)
排查顺序是从 references 到版本与压缩、再到计数与截断、最后到坐标的固定检查路径。— DeepSeek Harness 官方参考 - 会话引用
坐标归属(coordinate ownership)
坐标归属指 capturedThroughSeq 属于哪个源会话的 generation,决定它能否被正确解释。— DeepSeek Harness 官方参考 - 会话引用

来源