DSH plugin 文件补全的取消:AbortSignal、过期结果与三类竞态的处理方式
补全列表闪回旧结果,几乎都是「新请求已经发出,旧请求还在路上」:DSH plugin(DSH插件) 的 list(agent, query, signal) 给了取消入口,但取消之后还必须丢弃过期响应,两步缺一不可。 只做防抖不做取消,问题只会变少,不会消失。
DSH plugin 快速输入时列表为什么会闪回
因为发现的触发频率是按键级,而响应顺序不保证。(来源) 一个可复现的时序:
t1 输入 "s" -> 请求 A
t2 输入 "sr" -> 请求 B
t3 请求 B 返回 -> 渲染 ["src/"]
t4 请求 A 返回 -> 渲染 ["scripts/"] <- 闪回
用户看到的是「明明输入了 sr,列表却跳回 scripts」。代码上没有任何异常,只是 A 比 B 晚到。
这类问题的特征是:只在网络或磁盘慢时出现,本地快的时候几乎复现不了。所以不能靠手测确认,必须构造延迟。
DSH plugin 的 signal 在哪一层
在接口参数里,从你的宿主一路传到 provider。(来源) 两个入口都带 signal:
ctx.fileReferences.list(agent, query, signal)— 抽象缝;ctx.sessionFileReferences.list(agent, query, signal)— Remote 适配器。
适配器不应吞掉 signal,provider 也不应忽略它。官方把 signal 描述为「调用方取消」,含义是:调用方不再需要这次结果,提供方可以停止。
注意它只覆盖单次调用,不是全局开关。每次输入都应该有自己的一次调用与一个 signal。
DSH plugin 里取消与失败不是一回事
取消是预期行为,失败是异常,两者不能共用一套 UI。(来源) 对照:
| 情况 | 语义 | 宿主反应 |
|---|---|---|
| signal 触发 | 调用方不再需要 | 静默丢弃,不提示 |
| provider 抛错 | 发现失败 | 可提示,保留上一次结果 |
| 返回空数组 | 没有候选 | 展示空态 |
把取消当失败,用户每快速输入一次就看到一次错误提示;把失败当取消,真正的权限或路径问题会被静默吃掉。
一个简单规则:错误提示只应该由「非取消的异常」触发。
DSH plugin 补全的三类竞态
按发生位置分,处理方式不同。(来源) 对照:
| 竞态 | 场景 | 处理 |
|---|---|---|
| 请求级 | 旧请求晚于新请求返回 | 取消旧请求,并按请求序号丢弃 |
| 渲染级 | 状态更新晚于下一次输入 | 渲染前比对当前 query |
| 生命周期级 | 组件卸载后响应到达 | 卸载时取消,响应直接丢弃 |
第三类最容易被忽略:用户切走了页面,回调仍然执行,轻则无用渲染,重则访问已销毁的状态。
三类竞态的共同解法是「让结果带上它属于哪次输入」,而不是只依赖「最后返回者胜出」。
DSH plugin 宿主侧的最小实现
四个动作,足够覆盖绝大多数场景。(来源) 步骤:
- 每次输入生成一个递增序号,并创建新的
AbortController; - 发起请求前,取消上一次 controller;
- 响应返回时,比较序号与当前序号,不一致直接丢弃;
- 组件卸载时取消当前 controller,并清空序号。
伪代码大致是这样:
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 取消行为的验证
用人为延迟构造竞态,而不是靠手速。 步骤:
- 在测试 provider 里对
s加 300ms 延迟,对sr立即返回; - 连续输入
s、sr,确认最终只显示sr的结果; - 输入后立刻卸载组件,确认没有渲染警告;
- 让 provider 抛错,确认错误提示出现且旧结果仍在。
第 2 步是核心断言:最终状态必须由最后一次输入决定,而不是最后返回的请求决定。
第 3 步验证生命周期取消,第 4 步验证取消与失败没有被混淆。
补全链路到这里就完整了。想看候选为什么只有路径,读 DSH plugin 文件引用候选为什么只有路径;想看 query 怎么解析,读 DSH plugin 文件引用的 query 怎么传;想先看全貌,读 DSH plugin 怎么完整实现会话引用。
常见问题
多数不是 provider 返回错了,而是 DSH plugin 的请求时序问题。DSH plugin 的发现按 keystroke rate 触发,前一次请求晚于后一次返回时就会覆盖新结果;宿主需要在每次输入时取消旧请求,并丢弃过期响应。
取消不是业务失败,DSH plugin 把它定义为调用方的取消边界。DSH plugin 把 signal 定义为调用方的取消边界,provider 应停止工作;宿主不应把取消渲染成错误提示,也不该把它当成「没有候选」。
两者不是一回事,DSH plugin 在发现阶段与 prepare 阶段分别处理取消。DSH plugin 的文件引用取消发生在发现阶段,停止的是候选请求;会话引用的取消发生在 prepare 阶段,阻止的是上下文发布。两者共用 signal 形态,但语义不同。
不能替代,DSH plugin 的防抖与取消解决的是不同问题。防抖只能减少请求数量,DSH plugin 仍可能出现在延迟边界上返回的旧结果;取消负责让过期请求失效,两者解决的是不同问题。
相关术语
- AbortSignal
- AbortSignal 是调用方传入的取消信号,provider 收到后应停止发现并放弃返回结果。— DeepSeek Harness 官方参考 - 会话引用
- keystroke rate
- keystroke rate 是按用户按键频率触发发现的运行方式,意味着请求密集且生命周期很短。— DeepSeek Harness 官方参考 - 会话引用
- 过期结果(stale result)
- 过期结果是对应旧 query 的响应,在用户已经继续输入后返回,若被渲染就会覆盖新候选。— DeepSeek Harness 官方参考 - 会话引用
- 竞态(race)
- 竞态是多个异步请求的完成顺序与发起顺序不一致,导致最终展示取决于谁最后返回。— DeepSeek Harness 官方参考 - 会话引用
来源
- DeepSeek Harness 官方参考 - 会话引用· deepseek-ai
- file-reference/src/index.ts· deepseek-ai