ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 插件开发代码怎么组织:一个 apply 太长该拆到哪、怎么拆才可测、能复用

插件开发发布于 2026-11-17作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness插件开发代码组织可测试
apply 写到四百行,改一处怕碰坏另一处。本文给出 apply 只做装配的三条判据、按依赖方向切文件的方法、ctx 传递边界与纯函数抽取,并用决策树判断什么时候该拆成第二个插件或独立包。

插件开发写到后期,apply 会变成一锅乱炖:注册、解析、格式化、重试全塞在一起。 这时候再加功能,每改一行都要重新读一遍全文。DSH插件 的代码组织没有唯一答案,但有一条硬边界:装配归装配,计算归计算。

DSH plugin 的 apply 只做装配的三条判据

apply 里出现业务分支,就是该拆的信号。(来源)

三条判据,任意一条不满足就该动手:

  1. 只做注册 — 注册工具、登记资源、订阅事件;不解析输入,不计算结果。
  2. 不出现领域 if/for — 一旦按业务条件分支,说明逻辑漏进来了。
  3. 失败只发生在注册 — apply 抛错应该意味着“注册不了”,而不是“某个数据处理失败”。

满足这三条,apply 通常只有几十行:几个 ctx.tools.register、几个 ctx.effect、几次 ctx.on。读的人一眼能看出插件提供了什么。

拆文件的第一刀:DSH plugin 按依赖方向切

先切“谁依赖谁”,再切“文件多大”。(来源)

一个插件通常有三层:装配层(碰 ctx)、业务层(纯逻辑)、适配层(与外部世界打交道:文件、网络、存储)。

依赖方向是单向的:装配层依赖业务层与适配层,业务层不回头依赖装配层。按这个方向切,文件自然分成三类,而不是按“工具一个文件、事件一个文件”切得七零八落。

这样切的好处是测试:业务层不碰 ctx,可以直接单测;适配层可以注入假实现;装配层只有在真正验证注册时才需要加载。

ctx 传递边界:DSH plugin 的装配层持有

ctx 是注册入口,不是全局容器。(来源)

最常见的坏味道是把 ctx 一路传进业务函数。这样做的直接后果是业务模块离不开框架,单测必须先造一个假 ctx,最后测试变成“测框架”而不是“测逻辑”。

正确做法是把需要的东西在装配层取出来再传下去:

  1. 需要注册能力 — 在装配层调用,业务层只提供描述。
  2. 需要读配置 — 装配层读取后作为参数传入。
  3. 需要回调 — 业务层暴露纯函数,装配层把它包成 handler。

边界清楚之后,业务模块的签名里不会出现 ctx,也不会出现框架类型。

可测逻辑抽成纯函数:DSH plugin 的抽法

能脱离 Harness 跑的代码,才叫可测。(来源)

判断标准很简单:这个函数能不能在 node -e 里直接调用?能,就是纯函数;不能,说明它依赖了运行时。

值得抽出来的通常是三类:参数归一化、结果整形、错误分类。它们在插件里被反复调用,也最容易写错,抽出来之后可以用表驱动的方式覆盖边界。

抽的时候注意两点:不要把 IO 混进纯函数(读文件、发请求都不算纯);不要为了“纯”而把上下文拆成十几个参数,必要时用一个普通对象承载。

DSH plugin 什么时候该拆成第二个插件

拆包是发布决策,不是代码整洁决策。(来源)

用三个问题判断:

  1. 需要独立启用或卸载吗? 需要,用 ctx.plugin 挂子插件,各自有 Fiber。
  2. 需要被第三方依赖吗? 需要,拆成独立包并提供 service,让调用方注入。
  3. 只是想让文件短一点吗? 是,就拆模块,别动生命周期与包边界。

第 2 条和第 3 条最容易被混淆。拆包会带来版本号、发布流程与依赖声明三份成本,只在本插件内部复用的代码不值得付这份成本。

DSH plugin 的目录结构示例

四文件结构能覆盖大部分中小插件。(来源)

一个可用的起点:

  1. src/index.ts — 导出名称、inject 与 apply,只做装配。
  2. src/domain.ts — 纯函数:归一化、校验、整形、错误分类。
  3. src/adapter.ts — 与外部打交道:读写文件、调用 seam,接口用普通函数暴露。
  4. src/types.ts — 对外类型与声明合并,不放实现。

再大一点就把 adapter.ts 拆成多个,但装配层始终只有一个入口。这样读代码的人先看 index.ts 就知道插件提供了什么,再按需往下追。

验证:不启动 Harness 也能测

装配层之外的部分,应该能在一个空进程里跑通。(来源)

  1. 直接 import domain.ts,用几组输入断言输出,不引入任何框架依赖。
  2. 给 adapter.ts 注入假实现,断言它在失败与超时下返回预期结构。
  3. 用一个最小假 ctx 调用 apply,断言注册了预期数量的能力,且没有副作用。
  4. 调用 ctx.plugin 挂子插件,断言父子卸载顺序符合预期。
  5. 把 domain.ts 里的一处逻辑改错,断言测试能定位到具体函数,而不是一片红。

如果第 1 步就必须先造 ctx,说明业务逻辑还粘在框架上;第 5 步定位不到函数,说明测试粒度太粗。

拆包与依赖放置的进一步判断,可以看能力拆三包;不启动真实模型时的测试组织见插件怎么测。

一句话收束: apply 只装配,文件按依赖方向切,ctx 不出装配层,纯函数单独成文件,拆子插件看生命周期、拆包看是否被第三方依赖。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 插件开发的 apply 里到底能写多少行,超过多少就该拆?

DSH plugin 的 apply 该不该拆,看行数不如看职责。它只该做装配:注册工具、登记资源、连接事件;一旦出现解析、计算、格式化这类纯逻辑,就该挪出去。常见信号是 apply 里出现 if/for 的业务分支,而不是某个具体行数。

DSH plugin 里拆文件时,ctx 要不要一路往下传?

DSH plugin 的 ctx 只在需要注册能力的地方传。它是注册入口,不是全局容器;把 ctx 传给纯计算模块会让它依赖框架、难以测试。做法是装配层持有 ctx,业务层只接收数据和回调。

DSH plugin 插件开发用 ctx.plugin 拆子插件,和拆成多个文件有什么区别?

DSH plugin 的子插件有独立 Fiber 与生命周期,拆文件只是一份代码。ctx.plugin 适合“这部分可以单独启用、单独卸载”的能力;只是想把文件写短,用模块拆分即可,不必引入新的生命周期。

DSH plugin 插件什么时候该拆成独立包,而不是留在同一个包里?

当这部分能力需要被别的 DSH plugin 独立依赖时,就该拆包。插件以包为单位安装,如果某部分能力要被第三方注入使用,就该拆成独立的 service 包;只在本插件内部复用,拆包只会增加发布与版本负担。

相关术语

apply
apply 是 DSH plugin 的同步入口,负责把插件的能力装配到上下文上,理想状态下只做注册与连接,不承载业务计算。— DeepSeek Harness 官方文档 - 第一个插件
ctx.plugin
ctx.plugin 用于挂载子插件,它创建带独立生命周期的子 Fiber,父插件卸载时子插件被递归卸载。— DeepSeek Harness 官方文档 - 插件与生命周期
Fiber
Fiber 是每个插件实例的生命周期作用域,装配层与子插件各自拥有一个,卸载时其登记被清理。— DeepSeek Harness 官方文档 - 插件与生命周期
装配层
装配层是插件里唯一接触 ctx 的部分,负责注册能力、登记资源并把数据与回调交给业务模块。— DeepSeek Harness 官方文档 - 插件与生命周期

来源