DSH plugin 插件开发的异步边界:apply 为什么必须同步、异步初始化该放哪才最稳
插件开发里最隐蔽的 bug,是 apply 写成了 async 却没人等你。 框架在 LOADING 阶段同步调用 apply,返回就认为插件可以激活;你在里面 await 的那一段,跑在插件已经对外可用之后。DSH插件 的异步问题几乎都能在这条时间线上找到位置。
DSH plugin 的 apply 是同步入口,框架不替你 await
apply 返回即视为加载完成,异步部分没有人和你排队。(来源)
官方的状态机把 apply 放在 LOADING 这一格:依赖就绪后框架调用它,正常返回进入 ACTIVE,抛错进入 FAILED。这里没有“等待 Promise”的格子,所以 async apply 不会让加载变慢,只会让异步部分游离在加载窗口之外。
后果有三层。第一,插件已经被标记为可用,别的插件可以通过服务拿到它,但它的内部状态可能还是空的。第二,异步段抛出的错误不会进 FAILED,插件看起来一切正常。第三,热重载时旧实例被卸载,而上一轮的异步任务还挂在内存里,新一轮又起一份。
判断方法很直接:看 apply 的返回类型。只要它返回 Promise,就说明你把同步入口当成了异步流程的容器。
异步初始化该放哪:DSH plugin 的 ctx.effect 写法
初始化与清理必须成对登记,ctx.effect 就是这对关系的载体。(来源)
正确做法是把异步初始化放进 ctx.effect 的回调,并让处置器负责取消:
- 在 apply 里同步登记 effect — apply 本身不 await,只负责把这件事挂到 Fiber 上。
- 在 effect 回调里启动异步初始化 — 例如读配置、建连接、拉索引。
- 返回处置器 — 处置器里取消未完成的初始化、关闭已建立的连接、清掉定时器。
- 把就绪状态存进闭包 — 一个 Promise 或一个
ready标记,供后续使用点等待。
这样写的好处不是“代码更整齐”,而是卸载路径有归属:卸载时框架一定会调用处置器,你能在里面把异步收掉。反之,直接写在 apply 里的 await,卸载时没有任何钩子会碰它。
export function apply(ctx: Context) {
let cancelled = false
const ready = (async () => {
const config = await loadConfig()
if (cancelled) throw new Error('cancelled')
return config
})()
ctx.effect(() => {
// 卸载时先置位,再等初始化退出。
return async () => {
cancelled = true
await ready.catch(() => {})
}
})
}
注意 ready 只创建一次,所有使用点共享同一个 Promise;cancelled 让初始化在卸载后主动退出,而不是继续跑完再写缓存。
DSH plugin 里未捕获的 rejection 去了哪
它不会变成 FAILED,也不会让插件停下,只会安静地消失在控制台。(来源)
FAILED 的定义是“apply 抛出异常”。异步段在另一个微任务里失败,对框架来说加载早已成功,所以既不会转状态,也不会触发重载。
这带来一个典型现场:插件日志里有一句“初始化失败”,但 UI 一切正常,直到某个请求拿到空数据才暴露。排查时不要只看 Fiber 状态,要看异步段自己有没有 catch 并把失败落到可观测的地方。
可行的做法是把异步初始化包一层:失败时记录原因、把 ready 置为 rejected,让使用点显式拿到错误。比起静默重试,明确失败更容易定位。
首请求与初始化的竞争:DSH plugin 怎么排
框架不会因为你的初始化没跑完而推迟请求。(来源)
插件进入 ACTIVE 之后就可以被调用,而异步初始化可能还在路上。于是同一个插件会出现两种时序:初始化先完成,一切正常;请求先到,读到空缓存。
处理方式有三种,按代价从低到高:
- 共享同一个 ready Promise — 使用点
await它,首次请求慢一点,之后无感; - 未就绪时返回明确错误 — 不返回空数组或 undefined,让调用方知道是“还没好”而不是“没有”;
- 同步占位 + 异步补全 — 先返回一个可用的空结构,初始化完成后通过事件或状态刷新。
第一种最稳,第三种体验最好但要处理“补全后谁负责刷新”。无论选哪种,都不要在每次请求里重新触发一次初始化——那是把竞争变成雪崩。
DSH plugin 卸载时还没完成的异步怎么收口
卸载只保证调用处置器,不保证你的异步任务自己会停。(来源)
官方对 dispose 的承诺是三条:移除该插件的全部注册、递归卸载子插件、等所有异步清理完成后兑现 Promise。注意第三条说的是“异步清理”,也就是处置器返回的 Promise,不包括你没登记的那些任务。
所以处置器里要做两件事:把进行中的异步标记为取消,并等待它退出。一个常见的错误是处置器只关连接、不取消正在跑的读取,结果卸载后日志还继续打印。
另外,处置器之间是逆序调用但并发执行,多个异步处置器不保证逐个完成。如果“先停轮询、再关连接”有严格顺序,就必须写进同一个处置器里串行等待,而不是拆成两个 effect。
验证:三步对照
只改一处,才能把问题归因到同步入口还是异步段。(来源)
- 写一个 async apply,在里面延迟两秒再注册能力,启动后立刻调用该能力,断言调用失败或拿到空结果——这一步证明框架没有等你。
- 改成同步 apply +
ctx.effect内延迟两秒初始化,使用点await同一个 ready Promise,断言首次调用变慢但结果正确。 - 在初始化进行到一半时触发卸载,断言处置器被调用、异步任务收到取消、日志停止输出。
- 再打开 HMR 保存一次,断言旧实例的异步任务没有和新实例并行跑。
如果第 3 步日志还在打印,说明你只关了资源,没取消任务。第 4 步出现两套日志,通常是把异步任务存在模块顶层,而不是存在 Fiber 的 effect 里。
异步与启动成本是一体两面:外移重活会让启动变快,但也会把竞争带到运行时,可以接着读插件开发的启动成本;卸载侧的处置顺序见卸载清理与逆序处置。
一句话收束: apply 只做同步登记,异步初始化交给 ctx.effect 并配好取消,首请求共享同一个 ready,卸载时先停任务再关资源,HMR 下更要确认旧实例真的停了。
常见问题
不会,DSH plugin 的 apply 是同步入口,框架不会等你 await。它在 LOADING 阶段被调用,返回后插件就被视为可以进入 ACTIVE。写成 async 只会得到一个没人 await 的 Promise,异步部分跑在插件已激活之后,出错也没人接。
差别在清理:DSH plugin 的 ctx.effect 会把回调返回的处置器登记到 Fiber 上,卸载时执行;直接写在 apply 里的异步逻辑没有任何登记,卸载后仍在跑。异步初始化必须和它的清理成对出现,才能避免重载后残留。
DSH plugin 不会替你在请求前暂停,做法是让使用点等待同一个就绪 Promise。插件自己要暴露一个可等待的 ready 状态,或在未就绪时返回明确错误而不是空结果。把初始化 Promise 存在闭包里复用,比每个请求都重跑一次更稳。
清理顺序由 DSH plugin 的同一个 ctx.effect 处置器保证。它卸载时按注册逆序调用处置器,但多个异步处置器是并发执行的,不保证逐个完成;有先后依赖的收尾要串行写在一个处置器里。dispose 返回的 Promise 会在异步清理全部结束后才兑现。
相关术语
- apply
- apply 是 DSH plugin 的同步入口函数,框架在 LOADING 阶段调用它,此时 inject 声明的服务已就绪,你在这里注册能力或登记资源。— DeepSeek Harness 官方文档 - 第一个插件
- ctx.effect
- ctx.effect 是注册自定义资源的标准方式,回调可以返回一个处置器,插件卸载时由框架调用,用于关闭连接、清理定时器或取消异步任务。— DeepSeek Harness 官方文档 - 插件与生命周期
- LOADING
- LOADING 是 Fiber 的加载状态,表示依赖已就绪、框架正在执行 apply,apply 抛错则转入 FAILED,正常返回则进入 ACTIVE。— DeepSeek Harness 官方文档 - 插件与生命周期
- dispose
- dispose 是提前终止插件实例的操作,它移除该插件的全部注册、递归卸载子插件,并在所有异步清理完成后兑现 Promise。— DeepSeek Harness 官方文档 - 插件与生命周期
来源
- DeepSeek Harness 官方文档 - 插件与生命周期· deepseek-ai
- DeepSeek Harness 官方文档 - 第一个插件· deepseek-ai