DSH plugin 卸载清理:ctx 注册自动撤销、effect 逆序与必须串行清理的场景
插件第一次跑通时,什么都对。改代码、保存、热重载,日志里开始出现两条心跳;再改一次,三条。重启进程后又恢复正常——这类「只有热重载才会出现」的问题,几乎都出在清理。
下面按一次真实的排查过程走:症状、归属、顺序、最后给一份能照着做的自检。
DSH plugin 只在热重载后出现的症状
DSH plugin 只在热重载后翻倍的资源,几乎都是没托管给 ctx 的那部分。 现场大致是这样:插件里起了一个后台轮询,负责定时拉取远端状态;同时注册了一个工具,让模型能手动触发一次刷新。
第一次启动正常。修改轮询间隔后保存,HMR 生效,日志里的刷新记录变成两倍频率。再改一次,三倍。dsh --version 没变,代码也没变,唯一变化的是「这个进程被重载过几次」。
初步判断有两个方向:旧实例没被卸载,或者旧实例卸载了但资源没释放。
先确认插件有没有进入卸载流程,不要一上来就改代码。两个观察点:
- 热重载后,旧实例注册的工具是否从列表里消失。消失了,说明
ctx.tools.register那部分被正确撤销; - 日志里是否出现两次
plugin loaded,且没有对应的清理输出。有加载无清理,指向资源没托管给 ctx。
如果工具还在、新工具又出现,那才是「旧实例根本没卸载」,方向不同:查的是 profile 与 HMR 是否真的重新组合了配置。
本例是第一种:工具只剩一份,但轮询翻倍。结论很明确——卸载发生了,setInterval 没被回收。
DSH plugin 自动清理的边界:四类注册
框架自动追踪的是「通过 ctx 建立的注册」,不是「插件里创建的所有东西」。 官方列出的范围可以归成四类:
| 注册方式 | 典型用途 | 卸载时 |
|---|---|---|
ctx.on(event, handler) | 监听框架或插件事件 | 自动移除 |
ctx.tools.register(tool) | 向模型暴露工具 | 自动撤销 |
ctx.llm.registerAdapter(names, adapter) | 接入模型提供方 | 自动撤销 |
ctx.effect(() => cleanup) | 自定义资源 | 调用返回的处置器 |
把这四类当成白名单,不要当成兜底。 只要资源不是通过它们建立的,就不在自动清理范围内。
DSH plugin 不会被清掉的三类东西
DSH plugin 卸载后仍残留的资源只有三类:裸定时器、第三方库内部引用与模块级状态。 排查时按这三类对照,基本能覆盖所有「重载后残留」:
第一,原生定时器与轮询。setInterval、setTimeout、requestAnimationFrame 都是裸资源,没有 ctx 参与。
第二,第三方库内部保存的引用。例如某个客户端 SDK 在你的回调里注册了内部监听,卸载时它并不知道要反注册;你在 ctx.effect 里调用它的 close() 才算闭环。
第三,模块级或全局状态。模块顶层 new 出来的连接池、挂在 globalThis 上的缓存、闭包外层的单例数组,都跨实例存活。
一条实用判断:这段资源的所有权在谁手里。 所有权在 ctx,交给框架;所有权在你,写进 ctx.effect;所有权在第三方库,调用它的关闭方法。
DSH plugin 逆序不等于串行:怎么把清理收进同一个 effect
DSH plugin 的处置器逆序调用但并发执行,有先后依赖的清理必须收进同一个 ctx.effect。 修完归属问题,还有第二个坑:顺序。
官方语义是处置器按注册的逆序调用,但多个异步处置器会并发执行,不保证逐个完成。这句话的含义是:
- 你注册了 A 再注册 B,卸载时先 B 后 A;
- 如果 B 的处置器是 async 且还没跑完,A 的处置器可能已经开始;
- 依赖「B 先关掉、A 才能停」的清理,靠两个独立 effect 保证不了。
判断你的清理有没有顺序依赖,问一句:如果两个清理同时开始,会不会互相打断。 会,就不能拆成两个 effect。
正确做法是在一个 ctx.effect 里完成整条清理链,由返回的处置器自己 await:
export function apply(ctx: Context) {
ctx.effect(() => {
const timer = setInterval(poll, 5000)
const socket = connect()
return async () => {
clearInterval(timer) // 先停止生产者
await socket.drain() // 等队列排空
await socket.close() // 最后关连接
}
})
}
这个处置器内部是串行的,因为它就是一个 async 函数。 框架只负责在卸载时调用它,并等它兑现;它内部怎么排顺序,由你决定。
反过来,如果把 clearInterval、drain、close 拆成三个 effect,框架会并发调用三个处置器,close 可能在 drain 完成前执行。
一份可执行的 DSH plugin 清理自检
验证 DSH plugin 清理是否干净,看连续重载五次后的资源特征,而不是看有没有报错。 改完不要只看「没报错」,按下面五步验证,每步都有可观察结果:
- 启动一次,记住日志里的资源特征,例如轮询频率或监听数量;
- 连续触发热重载五次,确认特征值不变;
- 卸载插件(删除 patch 行后重启),确认资源特征消失;
- 检查端口与文件句柄:
lsof -i :3080与lsof -p <pid>没有多余条目; - 再装回来,确认功能恢复且没有「已被占用」类报错。
第 2 步是核心。 它验证的是幂等:加载多少次,资源都只有一份。
把清理当成 DSH plugin 接口的一部分
加载出来的 DSH plugin 必须能被干净卸载,否则每次重载都在累积残留。 最后回到设计层面。清理不是收尾工作,它和 inject、Config 一样属于插件的对外契约:别人依赖你的插件时,默认它能干净卸载。
写任何资源前先问三句话:它归谁所有、卸载时谁负责关、关闭失败会不会阻塞其他清理。三个答案都清楚,再写 apply。
想理解 ctx 注册与 effect 的关系,读 Cordis 入门;想定位「插件到底卡在哪一步」,读 DSH plugin 本地调试;想看这类问题在错误清单里的位置,读 DSH plugin 开发常见错误。
常见问题
多数情况是 DSH plugin 的定时器没有经过 ctx 管理。卸载确实发生了,但 setInterval 不在 tracked 范围内,旧实例的定时器仍在跑。把创建与清理放进 ctx.effect,并在返回的处置器里 clearInterval 即可。
DSH plugin 的处置器顺序上是反向的,但异步处置器会并发执行,不保证前一个完成再跑下一个。清理步骤之间有先后依赖时,要放进同一个 ctx.effect 返回的处置器里,由它自己 await 串行完成。
不会:DSH plugin 的自动撤销只覆盖通过 ctx 建立的注册,例如 ctx.on、ctx.tools.register、ctx.llm.registerAdapter 和 ctx.effect。第三方库内部保存的回调、全局单例需要你在处置器里显式注销。
会:只要子插件是通过父 ctx 的 ctx.plugin 挂载的,DSH plugin 父插件 dispose 就会递归卸载它,其注册随之撤销。如果是另建的上下文,就不在这条链上。
相关术语
- 卸载
- 卸载是插件实例结束运行的过程,插件进入 UNLOADING 并释放它拥有的注册与资源,完成后变为 DISPOSED。— DeepSeek Harness 开发文档
- tracked 注册
- tracked 注册是通过 ctx 建立、由框架自动记入作用域并在卸载时撤销的注册,例如事件监听与工具注册。— DeepSeek Harness 开发文档
- 处置器
- 处置器是清理资源时执行的函数,由 ctx.effect 的回调返回,在插件卸载时被调用。— DeepSeek Harness 开发文档
- 逆序清理
- 逆序清理是指卸载时按注册的相反顺序调用处置器,用于先撤销后建立者的依赖关系。— DeepSeek Harness 开发文档
来源
- DeepSeek Harness 开发文档:插件与生命周期· deepseek-harness
- DeepSeek Harness 开发文档:第一个插件· deepseek-harness
- deepseek-harness 仓库· deepseek-ai