ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 里再挂插件:ctx.plugin() 的子 Fiber、独立状态与父子卸载顺序

插件开发发布于 2026-11-05作者: DeepSeek Plugin 插件市场
DSH pluginctx.pluginFiber插件生命周期DeepSeek Harness
插件写大了要不要拆内部插件?本文用一段会重复注册的代码讲清 ctx.plugin() 创建的子 Fiber 继承什么、卸载怎么传导,以及三种拆法的取舍。

一个插件从一百行涨到八百行,最先出现的不是性能问题,而是「这段逻辑该不该拆出去」的犹豫。拆可以,但拆错方式,热重载后你会看到工具被注册两遍、定时器越跑越多。

DSH plugin 里一段会重复注册的写法

DSH plugin 里会重复注册的写法,问题不在代码太长,而在资源没经过 ctx。 先看一个真实会出问题的结构。父插件在 apply 里自己注册工具,同时又在里面手写了一个 setInterval:

ts
export const name = 'report-plugin'
export const inject = ['tools']

export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'report',
    description: 'Generate a report.',
    parameters: {},
    async execute() { return 'ok' },
  }))
  setInterval(() => ctx.logger?.info?.('tick'), 5000)
}

工具注册走的是 ctx,会被自动清理;setInterval 没有走 ctx,重载一次就多一个。多数人这时才想起「应该把这段拆成子插件」,但如果拆的时候仍然手工管理资源,问题只是换了个位置。

ctx.plugin() 创建了什么

它创建的不是一个函数调用,而是一个子 Fiber。 子 Fiber 继承父上下文,但拥有独立的状态与独立的注册表。

  • 继承:子插件拿到的 ctx 能看到父层提供的服务;
  • 独立:子插件有自己的状态机,可以单独失败、单独卸载;
  • 连坐:父插件卸载时,子插件随之卸载。

状态机与顶层插件一致:PENDING、LOADING、ACTIVE、FAILED、UNLOADING、DISPOSED。区别只在于它的父级不是根上下文,而是挂载它的那个插件。

判断你是否真的用对了,看一点:子插件是用父插件收到的 ctx 挂的,还是你另建了一个上下文。 前者才享受父子连带卸载,后者等于又开了一棵独立的树。

DSH plugin 拆分:三种方式,先选一种

DSH plugin 的拆分要按生命周期边界选,不要按代码行数选。 拆分不是只有「挂子插件」一条路。三种做法解决的问题不同:

做法适合什么代价
同文件拆函数只是代码太长生命周期仍绑在一起,无法独立卸载
ctx.plugin() 挂内部插件这段能力有自己的依赖与配置多一层上下文,调试要看子 Fiber
拆成独立包会被别的插件复用要处理版本、依赖与发布

如果这段逻辑只是长,拆成普通函数就够了,不必上 Fiber。只有当它满足下面两条之一,才值得挂成子插件:

  1. 它需要自己的 inject,比如父插件不依赖 llm,子插件依赖;
  2. 它需要能单独卸载,比如后台任务要按功能开关停掉。

子插件卸载为什么会连坐

父子关系不是继承关系,是作用域关系。 卸载规则可以拆成四步理解:

  1. 父插件进入 UNLOADING,先撤销自己通过 ctx 做的注册;
  2. 接着递归卸载子插件,子插件再撤销它自己的注册;
  3. 子插件的子插件继续往下递归;
  4. 全部清理完成后,dispose() 返回的 Promise 才兑现。

有两个细节常被忽略。第一,处置器按注册的逆序调用,但多个异步处置器会并发执行,不保证逐个完成;有先后依赖的清理要放进同一个 ctx.effect 返回的处置器里串行等待。第二,递归卸载只覆盖通过 ctx 建立的关系,你在模块顶层 new 出来的连接、挂在 globalThis 上的监听,都不在清理范围内。

所以拆子插件之前先问一句:这段代码里有哪些资源是「没经过 ctx」的。 有,就先补 ctx.effect,再谈拆。

动手验证:一个最小的 DSH plugin 例子

验证 DSH plugin 子插件是否拆对,看重复加载五次后的资源数量,而不是看它能不能跑。 下面这个例子把「后台任务」拆成子插件,父插件只负责组装。放进 scratch-plugin/src/ 后用 --patch 加载:

ts
// parent.ts
export const name = 'report-parent'
export function apply(ctx: Context) { ctx.plugin(heartbeat) }

// heartbeat.ts
export const name = 'heartbeat'
export function apply(ctx: Context) {
  ctx.effect(() => {
    const timer = setInterval(() => console.log('[heartbeat] tick'), 5000)
    return () => clearInterval(timer)
  })
}

验证按四步走,每步都有可观察结果:

  1. 启动:pnpm dsh web --patch ./scratch-plugin/cordis.yml,日志出现心跳输出;
  2. 热重载:改一下 heartbeat.ts 的间隔,保存,确认旧定时器停止、新间隔生效;
  3. 卸载:把 parent 的 patch 行删掉重启,心跳消失且没有残留输出;
  4. 复查:连续触发热重载五次,确认日志里每秒只有一条心跳,而不是五条。

第 4 步是关键。 它验证的不是「有没有跑」,而是「有没有重复跑」,这正是子插件拆错时最常见的症状。

拆 DSH plugin 时的四个常见错位

DSH plugin 子插件的错误多数集中在归属上:注册、实例、依赖、解耦四件事。 第一,在父插件里把子插件的工具也注册一遍。子插件已经注册过,父层再注册就是两份,模型会看到同名工具。

第二,用同一个模块挂两次。ctx.plugin(heartbeat) 调两次就是两个实例、两个定时器;需要单例就让一个插件提供服务,其他插件 inject。

第三,子插件依赖父插件提供的服务,却没有声明 inject。父插件的服务注册可能晚于子插件加载,结果子插件在 apply 里拿到 undefined。

第四,把「拆出去」当成「解耦」。父插件如果直接 import 子插件的内部函数,两个插件仍然是一个整体;真正的解耦是只通过服务与事件通信。

拆子插件的收益是生命周期边界,不是代码行数。边界没画对,拆完只是多了一层更难查的调用栈。想看 Context 与 inject 的基础,读 Cordis 入门;想核对插件形态与自检清单,读 DSH plugin 开发规范。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 里用 ctx.plugin() 挂子插件,为什么热重载后会出现两份同名工具?

因为子插件被挂到了不归当前插件管的上下文上,重载只清了父插件的注册。ctx.plugin() 创建的子 Fiber 会随父插件一起卸载,但前提是用父 ctx 调用,而不是另起一个根上下文。

DSH plugin 父插件卸载时,子插件里注册的工具和定时器会自动清掉吗?

会:父插件 dispose 会递归卸载子插件,子插件通过 ctx 做的注册全部撤销。但第三方库里自己注册的监听、全局单例不在这套机制内,需要你在 ctx.effect 的处置器里手动清。

同一个插件模块被 ctx.plugin() 调用两次,会得到两个实例还是复用?

会:同一个插件模块被 ctx.plugin() 调用两次会得到两个独立实例,各自一个 Fiber、各自一份注册。需要单例时应只挂一次,让其他插件通过 inject 依赖它提供的服务,而不是重复挂载同一个模块。

DSH plugin 子插件的 apply 抛异常,父插件会跟着失败吗?

子 Fiber 进入 FAILED,父插件本身不会自动失败,但你会发现子插件的能力缺失。排查时先看启动日志里失败的是哪个模块,再确认它是不是被父插件挂载的子插件。

相关术语

Fiber
Fiber 是 Cordis 为每个已加载插件分配的运行作用域,记录该插件的状态与它拥有的全部注册,卸载时按作用域统一撤销。— DeepSeek Harness 开发文档
ctx.plugin()
ctx.plugin() 是在当前上下文里挂载另一个插件的 API,它创建子 Fiber、继承父上下文,并让子插件随父插件一起卸载。— DeepSeek Harness 开发文档
dispose
dispose 是终止一个插件实例的操作,会移除它的全部注册、递归卸载子插件,并在所有异步清理完成后兑现 Promise。— DeepSeek Harness 开发文档
inject
inject 是插件声明所需服务的字段,框架会等这些服务就绪后再执行 apply,服务消失时依赖它的插件会被自动卸载。— DeepSeek Harness 开发文档

来源