ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 会话引用的取消机制:为什么存储晚到也不能发布上下文,宿主该做什么处理

插件开发发布于 2026-11-10作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness会话引用取消竞态
用户点了停止,引用上下文还是出现在下一条消息里。本文讲 prepare 的取消边界、存储完成与取消的时序、CANCELLED 错误码,以及宿主在取消后该做什么。

取消的语义不是「尽量快停下」,而是「即使结果已经算出来,也不发布」:DSH plugin(DSH插件) 明确保证,存储在取消之后完成,也不会把上下文写进消息。 你的宿主没传 signal,这条保证就不存在。

DSH plugin 用户停止后上下文还是出现了

先查 signal 有没有传进 prepare。(来源) 现场:

text
用户点击停止
宿主取消 UI 状态,但没有 abort 请求
prepare 继续执行,存储完成,上下文发布
下一条消息带上了引用内容

从用户视角看,是「停了还在跑」;从链路看,是取消只停在了界面层。

判断方法:在 prepare 的错误分支里打日志,看有没有出现 SESSION_REFERENCE_CANCELLED。没有出现,说明取消根本没到。

DSH plugin 的取消边界在哪

在一次 prepare 调用上,不在全局。(来源) 规则:

  1. prepare(agent, content, references, signal) 的 signal 可选;
  2. 传入后,它是本次 turn 的取消边界;
  3. 取消只影响这次准备,不影响其他消息;
  4. 没有 signal 时,prepare 不会自己猜「用户可能想停」。

第四点意味着:取消是宿主的责任,不是服务的默认行为。

DSH plugin 存储完成与取消的时序

两种顺序,结果都必须是「不发布」。(来源) 对照:

时序存储取消结果
1先完成后到不发布
2后完成先到不发布

第二种是真正难处理的:取消时数据还没写完,但写完也不能用。

官方对这条写得很直接:取消阻止上下文发布,包括存储在取消之后完成的情况。

实现上,这要求发布前再检查一次取消状态,而不是只在入口检查。

DSH plugin 取消返回哪个错误码

返回 SESSION_REFERENCE_CANCELLED,不要返回空上下文。(来源) 原因有三:

  • 空上下文表示「没有引用内容」,与取消语义不同;
  • 错误码可以让上层区分「用户主动停」与「引用为空」;
  • 日志里能统计取消频率,便于优化体验。

如果实现选择吞掉取消、返回成功,用户会在下一条消息里看到不该出现的上下文。

反过来,如果所有失败都返回 CANCELLED,真正的问题又会被掩盖。错误码要按实际原因给。

DSH plugin 取消后宿主该做什么

四件事,按顺序。(来源) 步骤:

  1. 停止把本次准备结果写入消息;
  2. 保留用户已选的引用,但标记为「未生效」;
  3. 不自动重试,除非用户重新发送;
  4. 记录取消原因,便于区分手动停止与超时。

第二点容易被忽略:用户取消后重新发送,不应该重新选一遍。

第四点对产品有用:如果取消频率高,可能是准备太慢,而不是用户反复无常。

还有一个时序细节:发布前要再检查一次 signal。只在入口检查的话,存储在取消后完成,上下文仍可能被写进消息。

DSH plugin 取消的竞态验证

两个用例,覆盖两种时序。 步骤:

  1. 准备完成后立即取消,确认上下文不发布;
  2. 准备进行中取消,让存储在取消后完成,确认上下文仍不发布;
  3. 不传 signal,确认正常发布(对照组)。

第 2 个用例需要人为延迟存储,否则很难触发。

第 3 个用例用来确认测试环境本身没有误取消。

三个都过,说明取消逻辑在入口与发布前各检查了一次。

取消之后是安全边界。读 DSH plugin 会话引用为什么把上下文标为不可信;想看错误码怎么映射,读 DSH plugin 会话引用的七个错误码;想先看全貌,读 DSH plugin 怎么完整实现会话引用。

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

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 里用户停止生成后,为什么下一条消息还带着上次的引用上下文?

取消没有传到位,DSH plugin 没有收到 signal。DSH plugin 的 prepare 在收到取消后会阻止上下文发布;如果宿主没有把 signal 传下去,存储完成后仍会产出上下文。

DSH plugin 的会话引用取消后,应该返回空上下文还是报错?

DSH plugin 在取消时应返回稳定错误码 SESSION_REFERENCE_CANCELLED。DSH plugin 不把取消当成功;当成空上下文会让调用方误以为引用本来就没有内容。

DSH plugin 的取消能阻止已经开始的存储完成吗,为什么?

DSH plugin 的取消不保证中断底层存储,但保证不发布结果。DSH plugin 的约束是:即使存储在取消之后完成,也不再发布上下文。

DSH plugin 里面包取消和上下文取消应该用同一个 signal 吗?

不应该,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

来源