ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 插件开发把状态放哪:闭包、Fiber、service 与持久化怎么选

插件开发发布于 2026-11-17作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness插件开发插件状态热重载
热重载后计数器归零、服务重启后配置丢了,都是状态放错层。本文用四种寿命不同的位置做对照,讲清 apply 闭包、ctx.effect、service 实例与持久化各自的丢失时机、共享边界,并给出四问决策清单与同一计数器的四种放法验证。

插件开发做到一半,状态放哪往往比逻辑本身更决定成败。 同一个计数器,写在闭包里热重载就归零,放进 service 能活到提供方卸载,写进日志才能跨重启。DSH插件 的状态没有“默认正确的位置”,只有“和寿命匹配的位置”。

DSH plugin 状态四种位置的寿命对照

先问这份状态要活多久,再决定放哪;寿命不匹配就是 bug。(来源)

位置活到什么时候适合放什么
apply 闭包当前插件实例,卸载即丢一次性配置、注册时捕获的引用
ctx.effect 内的变量同上,但清理有归属与资源绑定的运行时句柄
service 实例字段提供方插件 ACTIVE 期间多个调用方共享的内存状态
持久化跨进程、跨会话计数、游标、授权、用户偏好

这张表最有用的一列是“活到什么时候”。很多“状态丢失”的问题,本质是把第一行的位置用在了第四行的需求上。

还要注意第二行和第一行没有寿命差别:ctx.effect 不会让状态活得更久,它只保证清理时有人负责。把状态放进 effect 的闭包,换来的是可控的收尾,不是更长的寿命。

闭包状态:DSH plugin 里最便宜,也最容易丢

闭包状态随实例走,HMR 每保存一次就重置一次。(来源)

官方对 HMR 的描述是卸载旧插件、清理注册、重新加载代码、执行新的 apply。闭包属于旧实例,所以里面的计数器、缓存、去重集合在每次保存后都会回到初始值。

开发期这会表现成“代码没问题,但行为像刚启动”。一个典型症状是限流器在热重载后立刻放行,因为计数清零了。线上则表现为“重启后要重新预热”,例如索引缓存要重新构建。

判断某个闭包变量该不该外移,问一句就够:它归零时,用户会看到行为变化吗?会,就不该只放闭包。

子 Fiber 与父子状态边界:DSH plugin 怎么划

子插件有自己的 Fiber,父插件看不到它的闭包。(来源)

ctx.plugin() 创建一个子 Fiber,子插件继承父上下文,但生命周期独立:父插件卸载时子插件被递归卸载,子插件自己也可以被单独 dispose。

因此“父插件持有一份全局表”这种写法不成立——子插件读不到父插件的闭包变量。要共享,只有两条路:父插件注册一个 service 供子插件 inject,或者在挂载子插件时显式把对象传进去。

前者更符合框架习惯,也让依赖关系显式;后者更轻,适合父子强耦合的内部模块。两条路都不该用模块顶层变量来“偷偷共享”,那会同时破坏卸载语义和热重载。

DSH plugin 的 service 持有状态:共享的代价是跟着提供方走

service 把状态从“一个插件”提升到“一组调用方”,但它仍然不是持久化。(来源)

用类形态提供服务时,状态放在实例字段上,注入该服务的插件拿到的是同一个引用,于是多个调用方看到同一份数据。

代价有两个。其一,必需服务消失时,依赖它的插件会被自动卸载,服务恢复后重新加载,字段自然重置。其二,service 的生命周期由提供方决定,提供方热重载一次,所有调用方都要重新拿引用。

所以 service 适合“运行期共享”,不适合“跨重启记账”。把它当缓存可以,当账本不行。

DSH plugin 状态什么时候必须持久化

跨进程还要用的状态,只有一条路:写下去,再读回来。(来源)

判断标准是三个“跨”:跨进程、跨会话、跨设备。命中任意一个,就必须落到持久化层,例如写入会话日志、存储后端的某个域,或插件自己的配置文件。

持久化会带来三个新问题,必须在设计时一起想清楚:

  1. 写入时机 — 每次变化都写,还是攒批写;崩溃时允许丢多少。
  2. 读回校验 — 读回的版本与当前代码是否兼容,旧格式怎么迁移。
  3. 并发 — 多个实例同时写同一份状态时,谁赢,怎么避免互相覆盖。

只把状态从内存搬到磁盘、不回答这三个问题,通常会换来更难查的 bug。

DSH plugin 状态存放的四问决策清单

四个问题过一遍,位置基本就定了。(来源)

  1. 归零时用户会察觉吗? 会,就不能只放闭包。
  2. 需要被别的插件读到吗? 需要,就做成 service,或者显式传出。
  3. 重启后还要用吗? 要,就必须持久化,并回答写入、校验、并发三件事。
  4. 它绑定的是资源还是事实? 绑定资源(连接、句柄)放进 effect 并配处置器;是事实(计数、授权)就按寿命往上升。

四个问题里只要有一个答“是”,位置就该往上抬一层。反过来,全答“否”的状态留在闭包里最省事,也最容易读。

验证:同一个计数器四种放法

同一份逻辑换四个位置,丢状态的时机应该和寿命表完全对应。(来源)

  1. 把计数器放在 apply 闭包里,累加几次后触发一次热重载,断言计数归零。
  2. 把计数器放进 service 实例字段,注入方累加,卸载提供方再重新加载,断言计数同样归零,且调用方被重载。
  3. 用 ctx.plugin() 挂一个子插件,各自维护计数,断言父插件读不到子插件的值。
  4. 把计数写进持久化层,重启进程后再读,断言值仍在,且旧版本数据能被正确读回。
  5. 在 effect 里持有一个资源句柄,卸载后断言处置器执行、句柄关闭。

如果第 2 步调用方没有重载,说明它没有把该服务声明为必需依赖,属于另一种“看起来能用”的隐患。

状态的寿命问题解决后,接着通常是“状态什么时候被清理”,可以对照卸载清理与逆序处置;把状态做成服务对外提供,写法见自定义服务。

一句话收束: 闭包活到卸载,effect 只管收尾,service 活到提供方注销,持久化才跨重启;先问寿命再选位置,别让计数器和账本住进同一个地方。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 插件开发时把状态写在 apply 的闭包里,热重载之后为什么全没了?

DSH plugin 的热重载是卸载旧实例再跑新的 apply。HMR 会清理旧插件的全部注册并重新执行 apply,闭包随旧实例一起被丢弃,所以计数器、缓存、去重表这类写在闭包里的状态每次保存都会归零。

DSH plugin 里父插件和 ctx.plugin 挂的子插件,状态是共享的还是各自独立的?

DSH plugin 里父插件与子插件的状态各自独立:ctx.plugin 会创建子 Fiber,子插件继承父上下文但有独立生命周期,它闭包里的状态父插件读不到。需要共享时,应由父插件提供一个 service 或显式传递对象,而不是指望上下文自动串起来。

DSH plugin 的 service 持有状态,提供方被卸载后调用方会怎样?

DSH plugin 的 service 提供方卸载后,调用方会被一起卸载。依赖驱动加载规定必需服务消失时依赖它的插件自动 dispose,服务恢复后再重新加载,所以 service 里的状态不能当持久化用,重启后同样从零开始。

DSH plugin 插件开发的哪些状态必须落到持久化层,不能只放内存?

DSH plugin 里跨进程或跨会话仍然要用的状态必须持久化。内存状态只覆盖当前实例生命周期,进程重启、插件重载都会清空;需要跨重启保留的计数、游标、授权记录应写入会话日志或存储后端,并在启动时读回。

相关术语

Fiber
Fiber 是 Cordis 为每个插件实例创建的生命周期作用域,插件加载、激活、卸载都发生在它内部,闭包状态与它同寿。— DeepSeek Harness 官方文档 - 插件与生命周期
ctx.plugin
ctx.plugin 用于在插件内部挂载子插件,它创建子 Fiber,子插件继承父上下文但拥有独立的加载与卸载生命周期。— DeepSeek Harness 官方文档 - 插件与生命周期
Service
Service 是挂载在 ctx 上的命名能力,用类形态提供服务时为每个插件实例创建一份,调用方通过注入拿到同一个引用。— DeepSeek Harness 官方文档 - 服务与依赖
HMR
HMR 是热模块替换,修改插件源文件后先卸载旧实例并清理注册,再加载新代码并执行一次新的 apply。— DeepSeek Harness 官方文档 - 插件与生命周期

来源