DSH plugin 会话引用错误码:七个 SESSION_REFERENCE_* 的宿主映射与重试矩阵
所有失败都提示「引用失败」,等于没有提示。 DSH plugin(DSH插件) 的七个错误码本来就是让你的宿主分流用的:哪些是用户选错了、哪些是配置错了、哪些值得重试,看 code 就能分开。
DSH plugin 为什么错误码比文案可靠
code 是契约,message 是描述,两者的稳定性完全不同。(来源) 现场:
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 四个输入类错误怎么处理
共同点:重试同样的输入不会变好。(来源) 逐条:
INVALID_CONFIG— 集成配置不合法。检查依赖注入与必填项,不要向用户弹错误,这是开发者问题。INVALID_REFERENCE— 引用格式或内容无效。让用户重新选择,不要原样重发。SELF_REFERENCE— 引用了当前会话。这是产品层应该提前禁掉的选项,不应该等报错。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 逐条构造失败的验证
七条用例,确认文案、日志与按钮一致。 步骤:
- 传一份非法配置,确认
INVALID_CONFIG且不弹用户提示; - 传一个手工拼错的引用,确认
INVALID_REFERENCE且回到选择态; - 引用当前会话,确认
SELF_REFERENCE(或 UI 已提前禁用); - 一次传入超过上限的引用,确认
TOO_MANY; - 关闭源会话存储或注入读失败,确认
READ_FAILED且重试按钮生效; - 构造超预算引用,确认
BUDGET_EXCEEDED而不是截断; - 在 prepare 进行中触发 signal,确认
CANCELLED且无上下文发布。
每条用例都同时断言三件事:code、界面文案、日志字段。三者不一致,说明映射层有遗漏。
第 5 与第 6 条最容易混淆,务必分别验证,别用一个用例覆盖两种失败。
错误分流做完,取消的时序还值得单独看。读 DSH plugin 会话引用取消后为什么不能补写上下文;想理解预算与 64 KiB 回退,读 DSH plugin 会话引用的预算从哪里来;想先看全貌,读 DSH plugin 怎么完整实现会话引用。
来源:DeepSeek Harness 官方参考 - 会话引用、session-reference/src/types.ts
常见问题
可以有限重试,DSH plugin 建议带退避重试一到两次。它表示源会话读取失败,可能是瞬时问题;DSH plugin 建议带退避重试一到两次,仍失败则转为用户可见提示。
不是,DSH plugin 的截断成功返回,预算超限则是失败。截断仍然返回可用结果,并带省略事实;预算超限是失败,没有可发布的内容。DSH plugin 把两者分开,处理方式也不同。
不应该,DSH plugin 在取消后不会发布上下文。取消表示这次调用被放弃,DSH plugin 不会发布上下文;宿主用空上下文补齐,等于伪造了一次成功。
不要这样做,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 官方参考 - 会话引用
来源
- DeepSeek Harness 官方参考 - 会话引用· deepseek-ai
- session-reference/src/types.ts· deepseek-ai