DSH plugin 插件开发代码怎么组织:一个 apply 太长该拆到哪、怎么拆才可测、能复用
插件开发写到后期,apply 会变成一锅乱炖:注册、解析、格式化、重试全塞在一起。 这时候再加功能,每改一行都要重新读一遍全文。DSH插件 的代码组织没有唯一答案,但有一条硬边界:装配归装配,计算归计算。
DSH plugin 的 apply 只做装配的三条判据
apply 里出现业务分支,就是该拆的信号。(来源)
三条判据,任意一条不满足就该动手:
- 只做注册 — 注册工具、登记资源、订阅事件;不解析输入,不计算结果。
- 不出现领域 if/for — 一旦按业务条件分支,说明逻辑漏进来了。
- 失败只发生在注册 — apply 抛错应该意味着“注册不了”,而不是“某个数据处理失败”。
满足这三条,apply 通常只有几十行:几个 ctx.tools.register、几个 ctx.effect、几次 ctx.on。读的人一眼能看出插件提供了什么。
拆文件的第一刀:DSH plugin 按依赖方向切
先切“谁依赖谁”,再切“文件多大”。(来源)
一个插件通常有三层:装配层(碰 ctx)、业务层(纯逻辑)、适配层(与外部世界打交道:文件、网络、存储)。
依赖方向是单向的:装配层依赖业务层与适配层,业务层不回头依赖装配层。按这个方向切,文件自然分成三类,而不是按“工具一个文件、事件一个文件”切得七零八落。
这样切的好处是测试:业务层不碰 ctx,可以直接单测;适配层可以注入假实现;装配层只有在真正验证注册时才需要加载。
ctx 传递边界:DSH plugin 的装配层持有
ctx 是注册入口,不是全局容器。(来源)
最常见的坏味道是把 ctx 一路传进业务函数。这样做的直接后果是业务模块离不开框架,单测必须先造一个假 ctx,最后测试变成“测框架”而不是“测逻辑”。
正确做法是把需要的东西在装配层取出来再传下去:
- 需要注册能力 — 在装配层调用,业务层只提供描述。
- 需要读配置 — 装配层读取后作为参数传入。
- 需要回调 — 业务层暴露纯函数,装配层把它包成 handler。
边界清楚之后,业务模块的签名里不会出现 ctx,也不会出现框架类型。
可测逻辑抽成纯函数:DSH plugin 的抽法
能脱离 Harness 跑的代码,才叫可测。(来源)
判断标准很简单:这个函数能不能在 node -e 里直接调用?能,就是纯函数;不能,说明它依赖了运行时。
值得抽出来的通常是三类:参数归一化、结果整形、错误分类。它们在插件里被反复调用,也最容易写错,抽出来之后可以用表驱动的方式覆盖边界。
抽的时候注意两点:不要把 IO 混进纯函数(读文件、发请求都不算纯);不要为了“纯”而把上下文拆成十几个参数,必要时用一个普通对象承载。
DSH plugin 什么时候该拆成第二个插件
拆包是发布决策,不是代码整洁决策。(来源)
用三个问题判断:
- 需要独立启用或卸载吗? 需要,用
ctx.plugin挂子插件,各自有 Fiber。 - 需要被第三方依赖吗? 需要,拆成独立包并提供 service,让调用方注入。
- 只是想让文件短一点吗? 是,就拆模块,别动生命周期与包边界。
第 2 条和第 3 条最容易被混淆。拆包会带来版本号、发布流程与依赖声明三份成本,只在本插件内部复用的代码不值得付这份成本。
DSH plugin 的目录结构示例
四文件结构能覆盖大部分中小插件。(来源)
一个可用的起点:
src/index.ts— 导出名称、inject 与 apply,只做装配。src/domain.ts— 纯函数:归一化、校验、整形、错误分类。src/adapter.ts— 与外部打交道:读写文件、调用 seam,接口用普通函数暴露。src/types.ts— 对外类型与声明合并,不放实现。
再大一点就把 adapter.ts 拆成多个,但装配层始终只有一个入口。这样读代码的人先看 index.ts 就知道插件提供了什么,再按需往下追。
验证:不启动 Harness 也能测
装配层之外的部分,应该能在一个空进程里跑通。(来源)
- 直接 import
domain.ts,用几组输入断言输出,不引入任何框架依赖。 - 给
adapter.ts注入假实现,断言它在失败与超时下返回预期结构。 - 用一个最小假 ctx 调用
apply,断言注册了预期数量的能力,且没有副作用。 - 调用
ctx.plugin挂子插件,断言父子卸载顺序符合预期。 - 把
domain.ts里的一处逻辑改错,断言测试能定位到具体函数,而不是一片红。
如果第 1 步就必须先造 ctx,说明业务逻辑还粘在框架上;第 5 步定位不到函数,说明测试粒度太粗。
拆包与依赖放置的进一步判断,可以看能力拆三包;不启动真实模型时的测试组织见插件怎么测。
一句话收束: apply 只装配,文件按依赖方向切,ctx 不出装配层,纯函数单独成文件,拆子插件看生命周期、拆包看是否被第三方依赖。
常见问题
DSH plugin 的 apply 该不该拆,看行数不如看职责。它只该做装配:注册工具、登记资源、连接事件;一旦出现解析、计算、格式化这类纯逻辑,就该挪出去。常见信号是 apply 里出现 if/for 的业务分支,而不是某个具体行数。
DSH plugin 的 ctx 只在需要注册能力的地方传。它是注册入口,不是全局容器;把 ctx 传给纯计算模块会让它依赖框架、难以测试。做法是装配层持有 ctx,业务层只接收数据和回调。
DSH plugin 的子插件有独立 Fiber 与生命周期,拆文件只是一份代码。ctx.plugin 适合“这部分可以单独启用、单独卸载”的能力;只是想把文件写短,用模块拆分即可,不必引入新的生命周期。
当这部分能力需要被别的 DSH plugin 独立依赖时,就该拆包。插件以包为单位安装,如果某部分能力要被第三方注入使用,就该拆成独立的 service 包;只在本插件内部复用,拆包只会增加发布与版本负担。
相关术语
- apply
- apply 是 DSH plugin 的同步入口,负责把插件的能力装配到上下文上,理想状态下只做注册与连接,不承载业务计算。— DeepSeek Harness 官方文档 - 第一个插件
- ctx.plugin
- ctx.plugin 用于挂载子插件,它创建带独立生命周期的子 Fiber,父插件卸载时子插件被递归卸载。— DeepSeek Harness 官方文档 - 插件与生命周期
- Fiber
- Fiber 是每个插件实例的生命周期作用域,装配层与子插件各自拥有一个,卸载时其登记被清理。— DeepSeek Harness 官方文档 - 插件与生命周期
- 装配层
- 装配层是插件里唯一接触 ctx 的部分,负责注册能力、登记资源并把数据与回调交给业务模块。— DeepSeek Harness 官方文档 - 插件与生命周期
来源
- DeepSeek Harness 官方文档 - 插件与生命周期· deepseek-ai
- DeepSeek Harness 官方文档 - 第一个插件· deepseek-ai