ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 卸载清理:ctx 注册自动撤销、effect 逆序与必须串行清理的场景

插件开发发布于 2026-11-05作者: DeepSeek Plugin 插件市场
DSH plugin资源清理ctx.effectdispose热重载
热重载后监听翻倍、端口占用、定时器越跑越多,通常不是插件没卸载,而是清理顺序或归属错了。本文按一次故障复盘讲清注销语义与手动清理的边界。

插件第一次跑通时,什么都对。改代码、保存、热重载,日志里开始出现两条心跳;再改一次,三条。重启进程后又恢复正常——这类「只有热重载才会出现」的问题,几乎都出在清理。

下面按一次真实的排查过程走:症状、归属、顺序、最后给一份能照着做的自检。

DSH plugin 只在热重载后出现的症状

DSH plugin 只在热重载后翻倍的资源,几乎都是没托管给 ctx 的那部分。 现场大致是这样:插件里起了一个后台轮询,负责定时拉取远端状态;同时注册了一个工具,让模型能手动触发一次刷新。

第一次启动正常。修改轮询间隔后保存,HMR 生效,日志里的刷新记录变成两倍频率。再改一次,三倍。dsh --version 没变,代码也没变,唯一变化的是「这个进程被重载过几次」。

初步判断有两个方向:旧实例没被卸载,或者旧实例卸载了但资源没释放。

先确认插件有没有进入卸载流程,不要一上来就改代码。两个观察点:

  1. 热重载后,旧实例注册的工具是否从列表里消失。消失了,说明 ctx.tools.register 那部分被正确撤销;
  2. 日志里是否出现两次 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。 修完归属问题,还有第二个坑:顺序。

官方语义是处置器按注册的逆序调用,但多个异步处置器会并发执行,不保证逐个完成。这句话的含义是:

  1. 你注册了 A 再注册 B,卸载时先 B 后 A;
  2. 如果 B 的处置器是 async 且还没跑完,A 的处置器可能已经开始;
  3. 依赖「B 先关掉、A 才能停」的清理,靠两个独立 effect 保证不了。

判断你的清理有没有顺序依赖,问一句:如果两个清理同时开始,会不会互相打断。 会,就不能拆成两个 effect。

正确做法是在一个 ctx.effect 里完成整条清理链,由返回的处置器自己 await:

ts
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 清理是否干净,看连续重载五次后的资源特征,而不是看有没有报错。 改完不要只看「没报错」,按下面五步验证,每步都有可观察结果:

  1. 启动一次,记住日志里的资源特征,例如轮询频率或监听数量;
  2. 连续触发热重载五次,确认特征值不变;
  3. 卸载插件(删除 patch 行后重启),确认资源特征消失;
  4. 检查端口与文件句柄:lsof -i :3080 与 lsof -p <pid> 没有多余条目;
  5. 再装回来,确认功能恢复且没有「已被占用」类报错。

第 2 步是核心。 它验证的是幂等:加载多少次,资源都只有一份。

把清理当成 DSH plugin 接口的一部分

加载出来的 DSH plugin 必须能被干净卸载,否则每次重载都在累积残留。 最后回到设计层面。清理不是收尾工作,它和 inject、Config 一样属于插件的对外契约:别人依赖你的插件时,默认它能干净卸载。

写任何资源前先问三句话:它归谁所有、卸载时谁负责关、关闭失败会不会阻塞其他清理。三个答案都清楚,再写 apply。

想理解 ctx 注册与 effect 的关系,读 Cordis 入门;想定位「插件到底卡在哪一步」,读 DSH plugin 本地调试;想看这类问题在错误清单里的位置,读 DSH plugin 开发常见错误。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 热重载后定时器执行次数翻倍,是不是卸载没生效?

多数情况是 DSH plugin 的定时器没有经过 ctx 管理。卸载确实发生了,但 setInterval 不在 tracked 范围内,旧实例的定时器仍在跑。把创建与清理放进 ctx.effect,并在返回的处置器里 clearInterval 即可。

DSH plugin 里 ctx.effect 的清理函数一定会按注册的相反顺序逐个执行完吗?

DSH plugin 的处置器顺序上是反向的,但异步处置器会并发执行,不保证前一个完成再跑下一个。清理步骤之间有先后依赖时,要放进同一个 ctx.effect 返回的处置器里,由它自己 await 串行完成。

DSH plugin 卸载后,第三方库自己注册的事件监听会自动移除吗?

不会:DSH plugin 的自动撤销只覆盖通过 ctx 建立的注册,例如 ctx.on、ctx.tools.register、ctx.llm.registerAdapter 和 ctx.effect。第三方库内部保存的回调、全局单例需要你在处置器里显式注销。

DSH plugin 子插件里的资源,父插件卸载时会一起清理吗?

会:只要子插件是通过父 ctx 的 ctx.plugin 挂载的,DSH plugin 父插件 dispose 就会递归卸载它,其注册随之撤销。如果是另建的上下文,就不在这条链上。

相关术语

卸载
卸载是插件实例结束运行的过程,插件进入 UNLOADING 并释放它拥有的注册与资源,完成后变为 DISPOSED。— DeepSeek Harness 开发文档
tracked 注册
tracked 注册是通过 ctx 建立、由框架自动记入作用域并在卸载时撤销的注册,例如事件监听与工具注册。— DeepSeek Harness 开发文档
处置器
处置器是清理资源时执行的函数,由 ctx.effect 的回调返回,在插件卸载时被调用。— DeepSeek Harness 开发文档
逆序清理
逆序清理是指卸载时按注册的相反顺序调用处置器,用于先撤销后建立者的依赖关系。— DeepSeek Harness 开发文档

来源