DSH plugin 自定义服务:抽象类、Request/Result 类型与默认值该放哪层
给能力定接口这件事,难点从来不是语法。真正容易出错的是三件事:哪些东西属于契约、默认值归谁管、以后能不能改。
这篇按一次接口评审的顺序走:先看反例,再决定 Definition 里放什么,最后给出可以照着写的结构。
先看一个能跑但会返工的 DSH plugin 接口
DSH plugin 里只写 interface 的接口能跑,但注册、默认值与错误语义一定返工。 假设团队要统一「代码执行」:本机执行、容器执行、远端执行,以后可能还有别的。第一版通常长这样:
export interface Runner {
run(command: string, cwd?: string, timeout?: number): Promise<string>
}
看起来干净,问题在三个地方。第一,它不是服务,运行时的 ctx 上没有 runner,Consumer 只能自己 new 一个实现。第二,timeout 的默认值写在各实现里,本机是 30 秒、容器是 60 秒,调用方永远不知道实际值。第三,返回值是 string,错误与输出混在一起,换实现时错误语义必然变。
判断一个定义是否合格,可以问三个问题:它能不能被注册?默认值是否可见?错误与结果是否分开? 三个都能回答「是」,才值得放进 Definition 包。
DSH plugin Definition 里的四样东西
DSH plugin 的一个可用 Definition 只有四部分:服务类、请求类型、结果类型与类型声明合并。 一个可用的 Service Definition,通常只有四部分,其他都不该放:
- 继承
Service的抽象类,构造函数里super(ctx, '服务名')完成注册; - 请求类型,描述调用方必须提供什么;
- 结果类型,描述成功时返回什么,以及与错误的分界;
- 类型声明合并,让
ctx.服务名在编译期有类型。
用代码写出来是这样:
export abstract class RunnerService extends Service {
constructor(ctx: Context) { super(ctx, 'runner') }
abstract resolve(request: RunRequest): RunSpec
abstract run(spec: RunSpec): Promise<RunResult>
}
export interface RunRequest { command: string; cwd?: string; timeoutMs?: number }
export interface RunSpec { command: string; cwd: string; timeoutMs: number }
export interface RunResult { stdout: string; stderr: string; exitCode: number }
注意这里出现了两个对象:RunRequest 是调用方给的,允许缺字段;RunSpec 是补齐默认值后的,字段齐全。这一步拆分就是默认值的归属声明。
抽象类同时解决了两个层面的问题。 在运行时,Service 基类负责把实例挂到 ctx 上;在编译期,抽象方法约束每个 Provider 必须实现同样的签名。只写 interface 拿不到前者,只写抽象类不导出请求类型拿不到后者。
DSH plugin 默认值为什么不能藏在实现里
DSH plugin 的默认值一旦写进 Provider,就会随实现漂移,必须收进 Definition 的 resolve()。 回到反例:timeout 的默认值写在每个 Provider 里,调用方看到的行为就随实现变化。今天本机执行 30 秒超时,明天换成容器变成 60 秒,业务代码的超时重试逻辑全部要跟着调。
推荐做法是把默认值收进 resolve(),让它成为契约的一部分:
export abstract class RunnerService extends Service {
constructor(ctx: Context) { super(ctx, 'runner') }
resolve(request: RunRequest): RunSpec {
return {
command: request.command,
cwd: request.cwd ?? process.cwd(),
timeoutMs: request.timeoutMs ?? 30000,
}
}
abstract run(spec: RunSpec): Promise<RunResult>
}
这样有三个直接好处:
- Provider 只关心
RunSpec,不需要重复写?? 30000; - Consumer 想知道默认值,读 Definition 就够,不用翻实现;
- 以后调整默认值只改一处,所有 Provider 同步生效。
resolve 必须显式存在于类型上。 如果它只是抽象类里的一个私有辅助方法,Provider 依然可以绕开它自己补默认值,契约就失效了。
DSH plugin 服务名是最容易被低估的公开接口
DSH plugin 的服务名是最硬的公开接口,改名等于破坏性变更。 代码里最不起眼的一行是 super(ctx, 'runner'),但 runner 这个字符串是整个体系里最硬的约定。
Consumer 会写 inject: ['runner'],cordis.yml 的 isolate 会按服务名分组,日志里的 PENDING 也会告诉你「缺 runner 服务」——三处都只认这个名字。改名等于破坏性变更,而且失败形态很不友好:所有依赖它的插件停在 PENDING,启动日志里只写「等待服务」,不会告诉你「名字改了」。
要改名的安全顺序是:
- Definition 同时注册新旧两个服务名,两个名字指向同一个实例;
- 所有 Consumer 的
inject逐步切到新名字; - 确认没有插件再引用旧名后,移除旧注册;
- 在 CHANGELOG 里写明旧名移除的版本。服务名用名词,不要用动词:
runner、metrics、storage都是好名字;doRun、handleCommand会让人误以为它是可以直接调用的函数。
DSH plugin 三个常被问到的设计决定
接口粒度:一个方法还是多个。 能力强相关就放一个服务里,例如 run 与 cancel;两个能力只是碰巧同一领域,就拆开。判断标准是「Consumer 会不会只想要其中一个」。同步还是异步。 一律返回 Promise:即使当前实现是同步的,以后换成远端调用时,同步签名会把所有 Consumer 锁死。错误抛异常还是放进结果。 结果里只放业务数据,失败用异常表达;把错误塞进 RunResult 会让每个调用点都写一次 if (result.error),换实现时错误字段的形态也必然漂移。
DSH plugin 写完之后怎么验
DSH plugin 的 Definition 写完要逐项验证,换实现与服务缺失两步最能暴露设计问题。 按下面五步验证,每步都有明确结论:
- 只 import Definition 包写一个 Consumer,确认编译通过、
ctx.runner有类型; - 写两个 Provider,只实现
run,确认都不需要碰默认值; - 在
cordis.yml里换 Provider 那一行,重启后工具行为按新实现变化,Consumer 未改; - 移除 Provider,确认依赖它的 Consumer 停在 PENDING,日志能读出缺
runner; - 把服务名临时改掉,确认失败信息能让你定位到名字问题,而不是怀疑加载器。
第 3 步和第 4 步最能暴露设计问题。 换实现要改 Consumer,说明 Definition 漏了东西;服务缺失时看不出缺什么,说明服务名或日志约定没设计好。
Definition 是给别人用的,不是给自己用的。写完先让一个不了解实现的人照着它写 Consumer,能写出来,接口就算立住了。想看服务在运行期消失后会发生什么,读 DSH plugin 服务隔离;想看能力拆成三个包的判断标准,读 能力拆三包。
常见问题
因为 DSH plugin 的服务需要在运行时注册到 ctx 上,抽象类继承 Service 后可以用 super(ctx, 'name') 完成注册;interface 只存在于类型层,不会被运行时识别。接口约束由抽象类承担,类型声明合并负责补全 ctx 的类型。
DSH plugin 的默认值应写在 Definition 暴露的显式步骤里,例如 resolve(request): Spec,让默认值成为契约的一部分。Provider 只实现执行,调用方不需要知道兜底规则,这样换实现时默认行为不会跟着漂移。
DSH plugin 的服务名不需要和包名一致,但一旦被 Consumer 通过 inject 引用就是公开契约。改名等于破坏性变更,所有依赖它的插件都会停在 PENDING。要改就先加新服务名、两套并存一轮,再移除旧名。
取决于需求:DSH plugin 的必需能力在 inject 里声明,服务缺失时插件不会加载。可选能力则不写 inject,改用 ctx.get('name') 判断,返回空就跳过相关功能,避免把可选能力写成硬依赖。
相关术语
- 服务名
- 服务名是插件通过 super(ctx, 'name') 注册到上下文上的键,Consumer 用 inject 或 ctx.get 按这个名字查找服务。— DeepSeek Harness 开发文档
- 抽象类
- 抽象类是 TypeScript 中不能直接实例化、只声明方法签名的类,DSH plugin 用它同时承担运行时注册与编译期约束。— DeepSeek Harness 开发文档
- 类型声明合并
- 类型声明合并是通过 declare module 扩展 Cordis 的 Context 接口,让 ctx.myService 在编译期获得正确类型的方式。— DeepSeek Harness 开发文档
- 可选依赖
- 可选依赖是不写进 inject、而在使用时用 ctx.get 查询的服务依赖,服务不存在时插件照常运行但跳过相关功能。— DeepSeek Harness 开发文档
来源
- DeepSeek Harness 开发文档:能力的三种角色· deepseek-harness
- DeepSeek Harness 开发文档:服务与依赖· deepseek-harness
- deepseek-harness 仓库· deepseek-ai