DSH plugin 会话引用没带上怎么查:四步从持久记录反推 compacted 与 truncated
在 DSH plugin(DSH插件) 里,「引用没带上」最常见的样子是:用户说没看到,日志里躺着一条成功记录。 成功只说明 prepare 跑完了,不说明内容进了上下文。要定位,得按固定顺序读持久记录,而不是先怀疑模型。
DSH plugin 成功记录能说明什么
它能说明三件事,不能说明另外三件事。(来源) 对照:
| 能说明 | 不能说明 |
|---|---|
| prepare 被调用并完成 | 用户的选择真的传进来了 |
| 引用被写入持久记录 | 内容完整,没有源端缺口 |
| 返回了结果对象 | additionalContext 被发布给模型 |
第三行是很多误判的起点:返回成功与「模型看到」之间还有一步发布。
所以第一步不是看模型日志,而是看记录里的字段。
DSH plugin 排查顺序为什么不能换
四步之间有依赖,跳步会得到相反结论。 顺序:
references是否为空;capturedFormatVersion与compacted;- 三类消息计数与
truncated; 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 第三步:计数与截断
三个数加一个布尔值,把「缺多少」说清。(来源) 判断:
originalMessages = retainedMessages + omittedMessages
再配合 truncated:
| 现象 | 结论 | 下一步 |
|---|---|---|
| 计数对不上 | 记录逻辑异常 | 查写入侧,不看模型 |
omittedMessages 大、truncated 为 false | 源端压缩缺口 | 换会话或引用更早内容 |
truncated 为 true | 本次预算省略 | 调整预算或缩小范围 |
| 两者都成立 | 缺口叠加 | 先处理源端,再处理预算 |
第三种情况要结合预算来源看:自动预算取的是最后组装的 route,route 变了,截断点也会变。
DSH plugin 第四步:坐标归属
定位失败先问「这是谁的 seq」,再问「存得对不对」。(来源) 三条检查:
capturedThroughSeq是否与源sessionId成对存储;- 定位时是否用源会话身份打开;
- 坐标缺省时,宿主是否错误地展示了第 0 条。
第二条是最高频的错:用当前会话解释源坐标,必然落在无关位置。
第三条属于展示层问题:缺省应该显示「位置未知」,而不是一个具体数字。
坐标本身没有对错,只有归属;归属错了,数值再准也没用。
DSH plugin 复现一次的最小步骤
四步复现,每步留一个可观察结果。 步骤:
- 用同一份夹具重放那次请求,确认
references条数与用户选择一致; - 打印
capturedFormatVersion与compacted,确认解释路径正确; - 打印三类计数与
truncated,确认减法成立; - 用源会话身份按坐标定位,确认落点与快照末条一致。
四条都过,说明记录侧没有问题,应转向发布与展示环节。
任何一条不过,就先修这一条,别继续往下猜。
需要补字段定义的细节,读 DSH plugin 引用被截断后的五个事实字段、DSH plugin 引用已压缩的源会话;想理解坐标,读 DSH plugin 的 capturedThroughSeq 属于源 generation;想从记录结构入手,读 DSH plugin 的 recall 记录怎么读。
来源:DeepSeek Harness 官方参考 - 会话引用、session-reference/src/types.ts
常见问题
先看 DSH plugin 记录里的 references 是否为空。为空说明选择没有传到 prepare;非空再看 compacted 与 truncated,判断内容是本来就没有,还是在准备阶段被省略。
DSH plugin 里 references 为空常见有三种原因:前端只把 mention 留在文本里、宿主序列化时丢了 references、调用方只传了 content。DSH plugin 不会从正文猜引用。
先处理 compacted,它是 DSH plugin 记录里的源端压缩标记。源端已压缩意味着那段历史本来就读不到,调预算无效;确认没有源端缺口之后,再看 truncated 对应的本次预算是否合理。
不一定,先确认 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 官方参考 - 会话引用
来源
- DeepSeek Harness 官方参考 - 会话引用· deepseek-ai
- session-reference/src/types.ts· deepseek-ai