ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 会话引用错误码:七个 SESSION_REFERENCE_* 的宿主映射与重试矩阵

插件开发发布于 2026-11-10作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness会话引用错误码重试
接入后所有失败都显示「引用失败」,用户不知道能做什么,开发也不知道从哪查。本文把七个错误码按责任分组,给出可重试边界、提示文案方向与一条条构造失败的验证方法。

所有失败都提示「引用失败」,等于没有提示。 DSH plugin(DSH插件) 的七个错误码本来就是让你的宿主分流用的:哪些是用户选错了、哪些是配置错了、哪些值得重试,看 code 就能分开。

DSH plugin 为什么错误码比文案可靠

code 是契约,message 是描述,两者的稳定性完全不同。(来源) 现场:

text
catch (err) {
  toast('引用失败'); // 七种原因,一种文案
}

这样写的问题不只是文案粗糙,而是把「用户能改」和「只能等」混成了同一种体验。

DSH plugin 给出七个 code,宿主协议再把它们映射到自己的错误封装。这一层映射是一次性工作,换来的是后续所有分支都可测。

不要用 message.includes('budget') 这类判断:文案会改,code 不会。

DSH plugin 七个错误码按责任分组

七种失败落在三组里,每组对应不同的修复人。(来源) 分组:

组错误码谁该动手
输入类INVALID_CONFIG、INVALID_REFERENCE、SELF_REFERENCE、TOO_MANY宿主或用户
读取类READ_FAILED、BUDGET_EXCEEDED环境或预算设置
生命周期CANCELLED无需修复

输入类占了一半,说明大多数问题在调用前就能拦住:配置写错、引用串拼错、引用了自己、一次引太多。

读取类才是真正的运行时问题,其中只有 READ_FAILED 值得自动重试。

生命周期类不是错误,只是这次不做了。

DSH plugin 四个输入类错误怎么处理

共同点:重试同样的输入不会变好。(来源) 逐条:

  1. INVALID_CONFIG — 集成配置不合法。检查依赖注入与必填项,不要向用户弹错误,这是开发者问题。
  2. INVALID_REFERENCE — 引用格式或内容无效。让用户重新选择,不要原样重发。
  3. SELF_REFERENCE — 引用了当前会话。这是产品层应该提前禁掉的选项,不应该等报错。
  4. TOO_MANY — 超过数量限制。提示用户减少引用数量,或在 UI 上直接限制选择上限。

第二条最常见:宿主自己拼 dsh-session: 字符串,label 里带括号就解析失败。改用候选返回的 mention 可以避免大部分。

第三条属于「能提前防就别靠报错」:候选列表里直接过滤掉当前会话,比报错体验好。

DSH plugin 读取类错误与生命周期错误

一个可重试,一个要看预算,一个不该重试。(来源) 三条:

  • READ_FAILED — 源会话日志读不出来。带退避重试一到两次;仍失败则提示「该会话暂时无法读取」,并保留用户已选的引用。
  • BUDGET_EXCEEDED — 预算不足导致准备失败。重试无意义,除非缩小引用范围或换更大容量的模型。
  • CANCELLED — 用户切走或停止。不提示、不重试、不补空上下文。

BUDGET_EXCEEDED 与截断的区别在这里必须说清:截断是成功但内容变少,带 truncated 与省略事实;预算超限是失败,没有可发布内容。

把两者混成一种处理,会出现「界面说成功了,模型什么也没收到」。

DSH plugin 的重试矩阵

一张表决定按钮长什么样。(来源) 对照:

错误码重试前必须改变界面动作
INVALID_CONFIG修配置并重启不展示给终端用户
INVALID_REFERENCE重新选择引用回到选择态
SELF_REFERENCE换一个会话禁用当前会话选项
TOO_MANY减少数量提示上限
READ_FAILED无需改变提供重试按钮
BUDGET_EXCEEDED缩小范围或换模型提供调整入口
CANCELLED不需要静默

「重试前必须改变」这一列是防呆:没有改变就重试,只会得到同一个 code。

日志里也应该记录这一列,而不是只记 code。排查时能一眼看出调用方有没有按约定处理。

DSH plugin 宿主映射的写法

枚举对枚举,别对字符串。 用一个穷尽的 switch 把七个 code 分成三类处理:可重试、静默、用户可修复;默认分支给「用户可修复」是刻意的保守选择,未知 code 至少不会静默。

还有一条:日志与遥测里保留原始 code 与关键计数,不要脱敏成 unknown。排查时那是唯一的线索。

DSH plugin 逐条构造失败的验证

七条用例,确认文案、日志与按钮一致。 步骤:

  1. 传一份非法配置,确认 INVALID_CONFIG 且不弹用户提示;
  2. 传一个手工拼错的引用,确认 INVALID_REFERENCE 且回到选择态;
  3. 引用当前会话,确认 SELF_REFERENCE(或 UI 已提前禁用);
  4. 一次传入超过上限的引用,确认 TOO_MANY;
  5. 关闭源会话存储或注入读失败,确认 READ_FAILED 且重试按钮生效;
  6. 构造超预算引用,确认 BUDGET_EXCEEDED 而不是截断;
  7. 在 prepare 进行中触发 signal,确认 CANCELLED 且无上下文发布。

每条用例都同时断言三件事:code、界面文案、日志字段。三者不一致,说明映射层有遗漏。

第 5 与第 6 条最容易混淆,务必分别验证,别用一个用例覆盖两种失败。

错误分流做完,取消的时序还值得单独看。读 DSH plugin 会话引用取消后为什么不能补写上下文;想理解预算与 64 KiB 回退,读 DSH plugin 会话引用的预算从哪里来;想先看全貌,读 DSH plugin 怎么完整实现会话引用。

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

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 的 SESSION_REFERENCE_READ_FAILED 可以自动重试吗?

可以有限重试,DSH plugin 建议带退避重试一到两次。它表示源会话读取失败,可能是瞬时问题;DSH plugin 建议带退避重试一到两次,仍失败则转为用户可见提示。

DSH plugin 的 SESSION_REFERENCE_BUDGET_EXCEEDED 和截断是一回事吗?

不是,DSH plugin 的截断成功返回,预算超限则是失败。截断仍然返回可用结果,并带省略事实;预算超限是失败,没有可发布的内容。DSH plugin 把两者分开,处理方式也不同。

DSH plugin 返回 SESSION_REFERENCE_CANCELLED 时应该补一条空上下文吗?

不应该,DSH plugin 在取消后不会发布上下文。取消表示这次调用被放弃,DSH plugin 不会发布上下文;宿主用空上下文补齐,等于伪造了一次成功。

DSH plugin 的错误码能从 message 文本里解析吗?

不要这样做,DSH plugin 的错误码才是稳定契约。DSH plugin 的错误码是稳定契约,message 是给人看的描述;宿主应映射 code,而不是匹配文案字节。

相关术语

SESSION_REFERENCE_INVALID_CONFIG
表示宿主集成配置无效,例如缺少必要依赖或配置项不合法。— DeepSeek Harness 官方参考 - 会话引用
SESSION_REFERENCE_INVALID_REFERENCE
表示引用格式或内容无效,prepare 无法把这条引用解析成可读取的源。— session-reference/src/types.ts
SESSION_REFERENCE_READ_FAILED
表示读取源会话日志失败,可能是瞬时故障,也是七个错误码里少数适合重试的一个。— DeepSeek Harness 官方参考 - 会话引用
SESSION_REFERENCE_CANCELLED
表示本次调用被取消,取消后不发布上下文,即使底层存储随后完成。— DeepSeek Harness 官方参考 - 会话引用

来源