ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 文件补全的取消:AbortSignal、过期结果与三类竞态的处理方式

插件开发发布于 2026-11-10作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness文件引用AbortSignal竞态
快速输入时列表闪回旧结果,通常是取消没做对。本文讲 file-reference 的 signal 在哪一层、取消为什么不等于失败、三类竞态的时序,以及宿主侧的最小实现与验证方法。

补全列表闪回旧结果,几乎都是「新请求已经发出,旧请求还在路上」:DSH plugin(DSH插件) 的 list(agent, query, signal) 给了取消入口,但取消之后还必须丢弃过期响应,两步缺一不可。 只做防抖不做取消,问题只会变少,不会消失。

DSH plugin 快速输入时列表为什么会闪回

因为发现的触发频率是按键级,而响应顺序不保证。(来源) 一个可复现的时序:

text
t1  输入 "s"      -> 请求 A
t2  输入 "sr"     -> 请求 B
t3  请求 B 返回    -> 渲染 ["src/"]
t4  请求 A 返回    -> 渲染 ["scripts/"]   <- 闪回

用户看到的是「明明输入了 sr,列表却跳回 scripts」。代码上没有任何异常,只是 A 比 B 晚到。

这类问题的特征是:只在网络或磁盘慢时出现,本地快的时候几乎复现不了。所以不能靠手测确认,必须构造延迟。

DSH plugin 的 signal 在哪一层

在接口参数里,从你的宿主一路传到 provider。(来源) 两个入口都带 signal:

  1. ctx.fileReferences.list(agent, query, signal) — 抽象缝;
  2. ctx.sessionFileReferences.list(agent, query, signal) — Remote 适配器。

适配器不应吞掉 signal,provider 也不应忽略它。官方把 signal 描述为「调用方取消」,含义是:调用方不再需要这次结果,提供方可以停止。

注意它只覆盖单次调用,不是全局开关。每次输入都应该有自己的一次调用与一个 signal。

DSH plugin 里取消与失败不是一回事

取消是预期行为,失败是异常,两者不能共用一套 UI。(来源) 对照:

情况语义宿主反应
signal 触发调用方不再需要静默丢弃,不提示
provider 抛错发现失败可提示,保留上一次结果
返回空数组没有候选展示空态

把取消当失败,用户每快速输入一次就看到一次错误提示;把失败当取消,真正的权限或路径问题会被静默吃掉。

一个简单规则:错误提示只应该由「非取消的异常」触发。

DSH plugin 补全的三类竞态

按发生位置分,处理方式不同。(来源) 对照:

竞态场景处理
请求级旧请求晚于新请求返回取消旧请求,并按请求序号丢弃
渲染级状态更新晚于下一次输入渲染前比对当前 query
生命周期级组件卸载后响应到达卸载时取消,响应直接丢弃

第三类最容易被忽略:用户切走了页面,回调仍然执行,轻则无用渲染,重则访问已销毁的状态。

三类竞态的共同解法是「让结果带上它属于哪次输入」,而不是只依赖「最后返回者胜出」。

DSH plugin 宿主侧的最小实现

四个动作,足够覆盖绝大多数场景。(来源) 步骤:

  1. 每次输入生成一个递增序号,并创建新的 AbortController;
  2. 发起请求前,取消上一次 controller;
  3. 响应返回时,比较序号与当前序号,不一致直接丢弃;
  4. 组件卸载时取消当前 controller,并清空序号。

伪代码大致是这样:

ts
let seq = 0
let controller: AbortController | undefined

async function onInput(query: string) {
  controller?.abort()
  controller = new AbortController()
  const current = ++seq
  const items = await list(agent, query, controller.signal)
  if (current !== seq) return
  render(items)
}

这段代码里没有防抖,也没有重试。它只保证一件事:屏幕上永远是最新一次输入的结果。

DSH plugin 取消行为的验证

用人为延迟构造竞态,而不是靠手速。 步骤:

  1. 在测试 provider 里对 s 加 300ms 延迟,对 sr 立即返回;
  2. 连续输入 s、sr,确认最终只显示 sr 的结果;
  3. 输入后立刻卸载组件,确认没有渲染警告;
  4. 让 provider 抛错,确认错误提示出现且旧结果仍在。

第 2 步是核心断言:最终状态必须由最后一次输入决定,而不是最后返回的请求决定。

第 3 步验证生命周期取消,第 4 步验证取消与失败没有被混淆。

补全链路到这里就完整了。想看候选为什么只有路径,读 DSH plugin 文件引用候选为什么只有路径;想看 query 怎么解析,读 DSH plugin 文件引用的 query 怎么传;想先看全貌,读 DSH plugin 怎么完整实现会话引用。

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

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 文件补全快速输入时列表闪回旧结果,是 provider 返回错了吗?

多数不是 provider 返回错了,而是 DSH plugin 的请求时序问题。DSH plugin 的发现按 keystroke rate 触发,前一次请求晚于后一次返回时就会覆盖新结果;宿主需要在每次输入时取消旧请求,并丢弃过期响应。

DSH plugin 的 signal 取消后,provider 应该抛错还是返回空列表?

取消不是业务失败,DSH plugin 把它定义为调用方的取消边界。DSH plugin 把 signal 定义为调用方的取消边界,provider 应停止工作;宿主不应把取消渲染成错误提示,也不该把它当成「没有候选」。

DSH plugin 里文件引用的取消和会话引用的取消是一回事吗?

两者不是一回事,DSH plugin 在发现阶段与 prepare 阶段分别处理取消。DSH plugin 的文件引用取消发生在发现阶段,停止的是候选请求;会话引用的取消发生在 prepare 阶段,阻止的是上下文发布。两者共用 signal 形态,但语义不同。

DSH plugin 补全请求需不需要防抖,防抖能替代取消吗?

不能替代,DSH plugin 的防抖与取消解决的是不同问题。防抖只能减少请求数量,DSH plugin 仍可能出现在延迟边界上返回的旧结果;取消负责让过期请求失效,两者解决的是不同问题。

相关术语

AbortSignal
AbortSignal 是调用方传入的取消信号,provider 收到后应停止发现并放弃返回结果。— DeepSeek Harness 官方参考 - 会话引用
keystroke rate
keystroke rate 是按用户按键频率触发发现的运行方式,意味着请求密集且生命周期很短。— DeepSeek Harness 官方参考 - 会话引用
过期结果(stale result)
过期结果是对应旧 query 的响应,在用户已经继续输入后返回,若被渲染就会覆盖新候选。— DeepSeek Harness 官方参考 - 会话引用
竞态(race)
竞态是多个异步请求的完成顺序与发起顺序不一致,导致最终展示取决于谁最后返回。— DeepSeek Harness 官方参考 - 会话引用

来源