DSH plugin 会话引用的取消机制:为什么存储晚到也不能发布上下文,宿主该做什么处理
取消的语义不是「尽量快停下」,而是「即使结果已经算出来,也不发布」:DSH plugin(DSH插件) 明确保证,存储在取消之后完成,也不会把上下文写进消息。 你的宿主没传 signal,这条保证就不存在。
DSH plugin 用户停止后上下文还是出现了
先查 signal 有没有传进 prepare。(来源) 现场:
用户点击停止
宿主取消 UI 状态,但没有 abort 请求
prepare 继续执行,存储完成,上下文发布
下一条消息带上了引用内容
从用户视角看,是「停了还在跑」;从链路看,是取消只停在了界面层。
判断方法:在 prepare 的错误分支里打日志,看有没有出现 SESSION_REFERENCE_CANCELLED。没有出现,说明取消根本没到。
DSH plugin 的取消边界在哪
在一次 prepare 调用上,不在全局。(来源) 规则:
prepare(agent, content, references, signal)的signal可选;- 传入后,它是本次 turn 的取消边界;
- 取消只影响这次准备,不影响其他消息;
- 没有 signal 时,prepare 不会自己猜「用户可能想停」。
第四点意味着:取消是宿主的责任,不是服务的默认行为。
DSH plugin 存储完成与取消的时序
两种顺序,结果都必须是「不发布」。(来源) 对照:
| 时序 | 存储 | 取消 | 结果 |
|---|---|---|---|
| 1 | 先完成 | 后到 | 不发布 |
| 2 | 后完成 | 先到 | 不发布 |
第二种是真正难处理的:取消时数据还没写完,但写完也不能用。
官方对这条写得很直接:取消阻止上下文发布,包括存储在取消之后完成的情况。
实现上,这要求发布前再检查一次取消状态,而不是只在入口检查。
DSH plugin 取消返回哪个错误码
返回 SESSION_REFERENCE_CANCELLED,不要返回空上下文。(来源) 原因有三:
- 空上下文表示「没有引用内容」,与取消语义不同;
- 错误码可以让上层区分「用户主动停」与「引用为空」;
- 日志里能统计取消频率,便于优化体验。
如果实现选择吞掉取消、返回成功,用户会在下一条消息里看到不该出现的上下文。
反过来,如果所有失败都返回 CANCELLED,真正的问题又会被掩盖。错误码要按实际原因给。
DSH plugin 取消后宿主该做什么
四件事,按顺序。(来源) 步骤:
- 停止把本次准备结果写入消息;
- 保留用户已选的引用,但标记为「未生效」;
- 不自动重试,除非用户重新发送;
- 记录取消原因,便于区分手动停止与超时。
第二点容易被忽略:用户取消后重新发送,不应该重新选一遍。
第四点对产品有用:如果取消频率高,可能是准备太慢,而不是用户反复无常。
还有一个时序细节:发布前要再检查一次 signal。只在入口检查的话,存储在取消后完成,上下文仍可能被写进消息。
DSH plugin 取消的竞态验证
两个用例,覆盖两种时序。 步骤:
- 准备完成后立即取消,确认上下文不发布;
- 准备进行中取消,让存储在取消后完成,确认上下文仍不发布;
- 不传 signal,确认正常发布(对照组)。
第 2 个用例需要人为延迟存储,否则很难触发。
第 3 个用例用来确认测试环境本身没有误取消。
三个都过,说明取消逻辑在入口与发布前各检查了一次。
取消之后是安全边界。读 DSH plugin 会话引用为什么把上下文标为不可信;想看错误码怎么映射,读 DSH plugin 会话引用的七个错误码;想先看全貌,读 DSH plugin 怎么完整实现会话引用。
来源:DeepSeek Harness 官方参考 - 会话引用、session-reference/src/index.ts
常见问题
取消没有传到位,DSH plugin 没有收到 signal。DSH plugin 的 prepare 在收到取消后会阻止上下文发布;如果宿主没有把 signal 传下去,存储完成后仍会产出上下文。
DSH plugin 在取消时应返回稳定错误码 SESSION_REFERENCE_CANCELLED。DSH plugin 不把取消当成功;当成空上下文会让调用方误以为引用本来就没有内容。
DSH plugin 的取消不保证中断底层存储,但保证不发布结果。DSH plugin 的约束是:即使存储在取消之后完成,也不再发布上下文。
不应该,DSH plugin 的上下文取消与补全取消属于不同范围。DSH plugin 的上下文取消属于一次 turn,文件补全取消属于一次输入;共用一个 signal 会让停止生成时把补全也一并取消。
相关术语
- 取消边界(cancellation boundary)
- 取消边界是 prepare 接收的 signal,表示本次 turn 是否还需要结果。— DeepSeek Harness 官方参考 - 会话引用
- 发布(publication)
- 发布是 prepare 把准备好的上下文交给后续消息装配的动作,取消后不再发生。— session-reference/src/index.ts
- SESSION_REFERENCE_CANCELLED
- SESSION_REFERENCE_CANCELLED 是取消场景的稳定错误码,表示准备被调用方中止。— DeepSeek Harness 官方参考 - 会话引用
- 存储完成(storage completion)
- 存储完成是底层把快照写入完成的时刻,它可能晚于取消,但不改变不发布的结果。— session-reference/src/index.ts
来源
- DeepSeek Harness 官方参考 - 会话引用· deepseek-ai
- session-reference/src/index.ts· deepseek-ai