ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 插件开发的资源预算:四类资源怎么收口,用三个指标提前发现泄漏并做自检

插件开发发布于 2026-11-17作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness插件开发资源泄漏定时器
插件跑几小时后内存上涨、连接不减、日志越刷越快,多半是资源没有收口。本文按定时器、句柄、连接与缓存四类资源,讲清各自的持有者与收口写法,给出三个泄漏观测指标、一份长跑前自检与五步对照验证。

插件开发里最难查的故障,是那种“跑一晚上才出现”的资源泄漏。 定时器、句柄、连接、缓存,这四类东西在短测试里都看不出问题,却在长时间运行中把内存和句柄表慢慢填满。DSH插件 只自动清理通过 ctx 登记的注册,剩下的要你自己收口。

DSH plugin 的四类资源与它们的持有者

先认清谁持有它,才知道卸载时该由谁动手。(来源)

资源典型来源谁负责释放
定时器setInterval、重试轮询插件的处置器
句柄文件描述符、子进程、流插件的处置器
连接socket、数据库、HTTP keep-alive插件的处置器
缓存Map、索引、去重集合插件自己按上限淘汰

这张表只有一个重点:右列写“插件的处置器”的那三行,框架都不会替你完成。它只保证调用你登记的处置器,处置器里做什么由你决定。

第四行更特殊:缓存不报错、不占句柄,只占内存,所以最容易被忽略。它的“释放”不是卸载时清空,而是运行中就该有上限。

定时器与轮询:DSH plugin 里最容易悄悄叠加

一个没登记的定时器,会在每次热重载后变成两个、三个、四个。(来源)

定时器的危险不在于它占多少内存,而在于它会让日志和请求频率成倍增长。开发期每次保存都新建一份,半小时后你会看到同一句日志重复打印十次。

正确写法是把创建与清理放进同一个 ctx.effect:

  1. 在 effect 回调里启动定时器,把句柄存在闭包里。
  2. 返回处置器,在处置器里 clearInterval 并置空句柄。
  3. 定时器回调里先检查取消标记,避免清理后仍执行一轮。
  4. 轮询间隔设下限,别把重试写成忙等。

还要注意异步回调:如果定时器触发的是异步任务,清理时要等在跑的那一轮结束,否则卸载后仍可能写一次缓存。

句柄与连接:DSH plugin 里要成对释放

开与关必须出现在同一段代码里,跨函数传递就一定会漏。(来源)

句柄和连接的共同点是“有明确的开与关”,问题出在把开和关拆到了不同文件:初始化在 A 模块,关闭逻辑忘了写,或者写在了另一个插件的处置器里。

三条稳定做法:

  1. 成对写法 — 打开后立即登记关闭,不要等“需要的时候再加”。
  2. 收进一个 effect — 多个相关资源放进同一个处置器,保证关闭顺序可控。
  3. 失败也要关 — 初始化中途抛错时,把已经打开的部分关掉,别留下半开状态。

第三条最常被漏。一个连接池创建了三个连接、第四个失败,异常向上抛之后前三个就成了孤儿。

缓存也是 DSH plugin 要算的资源

缓存的上限是预算问题,不是性能问题。(来源)

业务缓存通常按 key 增长:每个会话一个、每个文件一个、每个 URL 一个。短期测试里 key 只有几个,跑一天之后可能是几万个,每个还带着不小的值。

处理方式有三种,按复杂度递增:

  1. 固定条数上限 — 超过就淘汰最旧,最简单也最不容易出错。
  2. 按字节估算上限 — 适合值大小差异大的场景,代价是要估算每条的大小。
  3. 按生命周期清理 — 会话结束、任务完成时删除对应 key,需要准确的结束信号。

无论选哪种,都要能在状态查询里看到当前条目数。看不见的缓存,等于没有上限。

DSH plugin 泄漏的三个判断指标

不用等 OOM,三个数字就能看出趋势。(来源)

  1. 登记数 — 插件持有的定时器、监听器、资源登记数量,热重载后应当回到同一水平。
  2. 句柄数 — 进程的文件描述符或子进程数量,长时间运行应保持平稳而不是阶梯上涨。
  3. 缓存条目 — 到上限后应稳定在阈值附近,持续单调上升说明淘汰没生效。

三个数字都要能在插件自己的只读状态里读到,否则每次排查都得重启进程去数。把它们做成状态字段,比打印日志更可靠。

顺带一提,这三个指标也解释了为什么“重启一下就好了”是危险信号:重启会把所有指标清零,问题被掩盖,下一次长跑又从零开始爬升。

验证:长跑对照

短测看不出来的问题,用“重复卸载 + 长跑”两步就能放大。(来源)

  1. 启动插件,记录登记数、句柄数与缓存条目数,作为基线。
  2. 连续触发五次热重载,断言三个数字在每次重载后回到基线附近。
  3. 让插件空跑十分钟,断言句柄数不随轮询次数增长。
  4. 灌入超过上限的缓存 key,断言条目数稳定在阈值附近而非继续上升。
  5. 在定时器回调执行到一半时卸载插件,断言处置器被调用、后续不再写缓存。

如果第 2 步数字阶梯上涨,基本可以确定有资源建在了 effect 之外;第 5 步仍在写入,说明取消标记没有在回调里检查。

资源的收口顺序与卸载语义,可以接着读卸载清理与逆序处置;资源泄漏也会拖慢启动,对照插件开发的启动成本一起看更清楚。

一句话收束: 定时器、句柄、连接都要登记进 effect 并成对释放,缓存必须有上限、有入口可查,三个指标一起看趋势,热重载是放大泄漏最快的手段。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 插件开发时用 setInterval 起的轮询,卸载后为什么还在跑?

因为 DSH plugin 只自动清理通过 ctx 做的注册,裸 setInterval 没有被登记为可清理资源。要让它随插件卸载而停止,必须放进 ctx.effect 并在返回的处置器里 clearInterval。

DSH plugin 的 ctx.effect 处置器是并发执行的,那关闭连接和停止写入该怎么保证顺序?

把有顺序要求的步骤写进 DSH plugin 的同一个处置器。卸载时按注册逆序调用处置器,但多个异步处置器并发执行、不保证逐个完成,所以“先停写入再关连接”必须串行写在同一个处置器的 async 函数里。

DSH plugin 插件开发时缓存要不要设上限,设在哪一层比较合适?

要设,DSH plugin 的缓存上限应该由插件自己按条目数或字节数控制。框架不替你回收业务缓存,缓存条目随不同 key 增长,长期运行会变成事实上的内存泄漏;到上限后淘汰最旧条目,比等 OOM 更容易排查。

DSH plugin 热重载后资源占用翻倍,通常是什么原因造成的?

DSH plugin 热重载后资源翻倍,是因为旧实例的资源没有被释放。HMR 会卸载旧插件,但只清理登记过的资源;如果定时器、连接或监听器直接建在模块顶层或 apply 外,新旧实例会各持一份,表现为句柄数与连接数随保存次数递增。

相关术语

ctx.effect
ctx.effect 是登记可清理资源的入口,回调返回的处置器在插件卸载时执行,适合定时器、连接与监听器这类需要手工收口的资源。— DeepSeek Harness 官方文档 - 插件与生命周期
Fiber
Fiber 是每个插件实例的生命周期作用域,插件卸载时该作用域内的登记会被清理,作用域外的资源不受影响。— DeepSeek Harness 官方文档 - 插件与生命周期
dispose
dispose 是终止插件实例的操作,移除其注册、递归卸载子插件,并在所有异步清理完成后兑现 Promise。— DeepSeek Harness 官方文档 - 插件与生命周期
HMR
HMR 是热模块替换,修改源文件后卸载旧实例、清理注册并执行新的 apply,未登记的资源不会被这次卸载带走。— DeepSeek Harness 官方文档 - 插件与生命周期

来源