DSH plugin 插件开发把状态放哪:闭包、Fiber、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 状态什么时候必须持久化
跨进程还要用的状态,只有一条路:写下去,再读回来。(来源)
判断标准是三个“跨”:跨进程、跨会话、跨设备。命中任意一个,就必须落到持久化层,例如写入会话日志、存储后端的某个域,或插件自己的配置文件。
持久化会带来三个新问题,必须在设计时一起想清楚:
- 写入时机 — 每次变化都写,还是攒批写;崩溃时允许丢多少。
- 读回校验 — 读回的版本与当前代码是否兼容,旧格式怎么迁移。
- 并发 — 多个实例同时写同一份状态时,谁赢,怎么避免互相覆盖。
只把状态从内存搬到磁盘、不回答这三个问题,通常会换来更难查的 bug。
DSH plugin 状态存放的四问决策清单
四个问题过一遍,位置基本就定了。(来源)
- 归零时用户会察觉吗? 会,就不能只放闭包。
- 需要被别的插件读到吗? 需要,就做成 service,或者显式传出。
- 重启后还要用吗? 要,就必须持久化,并回答写入、校验、并发三件事。
- 它绑定的是资源还是事实? 绑定资源(连接、句柄)放进 effect 并配处置器;是事实(计数、授权)就按寿命往上升。
四个问题里只要有一个答“是”,位置就该往上抬一层。反过来,全答“否”的状态留在闭包里最省事,也最容易读。
验证:同一个计数器四种放法
同一份逻辑换四个位置,丢状态的时机应该和寿命表完全对应。(来源)
- 把计数器放在 apply 闭包里,累加几次后触发一次热重载,断言计数归零。
- 把计数器放进 service 实例字段,注入方累加,卸载提供方再重新加载,断言计数同样归零,且调用方被重载。
- 用
ctx.plugin()挂一个子插件,各自维护计数,断言父插件读不到子插件的值。 - 把计数写进持久化层,重启进程后再读,断言值仍在,且旧版本数据能被正确读回。
- 在 effect 里持有一个资源句柄,卸载后断言处置器执行、句柄关闭。
如果第 2 步调用方没有重载,说明它没有把该服务声明为必需依赖,属于另一种“看起来能用”的隐患。
状态的寿命问题解决后,接着通常是“状态什么时候被清理”,可以对照卸载清理与逆序处置;把状态做成服务对外提供,写法见自定义服务。
一句话收束: 闭包活到卸载,effect 只管收尾,service 活到提供方注销,持久化才跨重启;先问寿命再选位置,别让计数器和账本住进同一个地方。
常见问题
DSH plugin 的热重载是卸载旧实例再跑新的 apply。HMR 会清理旧插件的全部注册并重新执行 apply,闭包随旧实例一起被丢弃,所以计数器、缓存、去重表这类写在闭包里的状态每次保存都会归零。
DSH plugin 里父插件与子插件的状态各自独立:ctx.plugin 会创建子 Fiber,子插件继承父上下文但有独立生命周期,它闭包里的状态父插件读不到。需要共享时,应由父插件提供一个 service 或显式传递对象,而不是指望上下文自动串起来。
DSH plugin 的 service 提供方卸载后,调用方会被一起卸载。依赖驱动加载规定必需服务消失时依赖它的插件自动 dispose,服务恢复后再重新加载,所以 service 里的状态不能当持久化用,重启后同样从零开始。
DSH plugin 里跨进程或跨会话仍然要用的状态必须持久化。内存状态只覆盖当前实例生命周期,进程重启、插件重载都会清空;需要跨重启保留的计数、游标、授权记录应写入会话日志或存储后端,并在启动时读回。
相关术语
- Fiber
- Fiber 是 Cordis 为每个插件实例创建的生命周期作用域,插件加载、激活、卸载都发生在它内部,闭包状态与它同寿。— DeepSeek Harness 官方文档 - 插件与生命周期
- ctx.plugin
- ctx.plugin 用于在插件内部挂载子插件,它创建子 Fiber,子插件继承父上下文但拥有独立的加载与卸载生命周期。— DeepSeek Harness 官方文档 - 插件与生命周期
- Service
- Service 是挂载在 ctx 上的命名能力,用类形态提供服务时为每个插件实例创建一份,调用方通过注入拿到同一个引用。— DeepSeek Harness 官方文档 - 服务与依赖
- HMR
- HMR 是热模块替换,修改插件源文件后先卸载旧实例并清理注册,再加载新代码并执行一次新的 apply。— DeepSeek Harness 官方文档 - 插件与生命周期
来源
- DeepSeek Harness 官方文档 - 插件与生命周期· deepseek-ai
- DeepSeek Harness 官方文档 - 服务与依赖· deepseek-ai