ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 自定义服务:抽象类、Request/Result 类型与默认值该放哪层

插件开发发布于 2026-11-05作者: DeepSeek Plugin 插件市场
DSH pluginService Definition自定义服务TypeScriptDeepSeek Harness
给团队能力定接口时,抽象类、请求结果类型、默认值分别该放在哪一层?本文用一次接口评审的视角,把 Service Definition 的四个组成部分讲清楚。

给能力定接口这件事,难点从来不是语法。真正容易出错的是三件事:哪些东西属于契约、默认值归谁管、以后能不能改。

这篇按一次接口评审的顺序走:先看反例,再决定 Definition 里放什么,最后给出可以照着写的结构。

先看一个能跑但会返工的 DSH plugin 接口

DSH plugin 里只写 interface 的接口能跑,但注册、默认值与错误语义一定返工。 假设团队要统一「代码执行」:本机执行、容器执行、远端执行,以后可能还有别的。第一版通常长这样:

ts
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,通常只有四部分,其他都不该放:

  1. 继承 Service 的抽象类,构造函数里 super(ctx, '服务名') 完成注册;
  2. 请求类型,描述调用方必须提供什么;
  3. 结果类型,描述成功时返回什么,以及与错误的分界;
  4. 类型声明合并,让 ctx.服务名 在编译期有类型。

用代码写出来是这样:

ts
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(),让它成为契约的一部分:

ts
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>
}

这样有三个直接好处:

  1. Provider 只关心 RunSpec,不需要重复写 ?? 30000;
  2. Consumer 想知道默认值,读 Definition 就够,不用翻实现;
  3. 以后调整默认值只改一处,所有 Provider 同步生效。

resolve 必须显式存在于类型上。 如果它只是抽象类里的一个私有辅助方法,Provider 依然可以绕开它自己补默认值,契约就失效了。

DSH plugin 服务名是最容易被低估的公开接口

DSH plugin 的服务名是最硬的公开接口,改名等于破坏性变更。 代码里最不起眼的一行是 super(ctx, 'runner'),但 runner 这个字符串是整个体系里最硬的约定。

Consumer 会写 inject: ['runner'],cordis.yml 的 isolate 会按服务名分组,日志里的 PENDING 也会告诉你「缺 runner 服务」——三处都只认这个名字。改名等于破坏性变更,而且失败形态很不友好:所有依赖它的插件停在 PENDING,启动日志里只写「等待服务」,不会告诉你「名字改了」。

要改名的安全顺序是:

  1. Definition 同时注册新旧两个服务名,两个名字指向同一个实例;
  2. 所有 Consumer 的 inject 逐步切到新名字;
  3. 确认没有插件再引用旧名后,移除旧注册;
  4. 在 CHANGELOG 里写明旧名移除的版本。服务名用名词,不要用动词: runner、metrics、storage 都是好名字;doRun、handleCommand 会让人误以为它是可以直接调用的函数。

DSH plugin 三个常被问到的设计决定

接口粒度:一个方法还是多个。 能力强相关就放一个服务里,例如 run 与 cancel;两个能力只是碰巧同一领域,就拆开。判断标准是「Consumer 会不会只想要其中一个」。同步还是异步。 一律返回 Promise:即使当前实现是同步的,以后换成远端调用时,同步签名会把所有 Consumer 锁死。错误抛异常还是放进结果。 结果里只放业务数据,失败用异常表达;把错误塞进 RunResult 会让每个调用点都写一次 if (result.error),换实现时错误字段的形态也必然漂移。

DSH plugin 写完之后怎么验

DSH plugin 的 Definition 写完要逐项验证,换实现与服务缺失两步最能暴露设计问题。 按下面五步验证,每步都有明确结论:

  1. 只 import Definition 包写一个 Consumer,确认编译通过、ctx.runner 有类型;
  2. 写两个 Provider,只实现 run,确认都不需要碰默认值;
  3. 在 cordis.yml 里换 Provider 那一行,重启后工具行为按新实现变化,Consumer 未改;
  4. 移除 Provider,确认依赖它的 Consumer 停在 PENDING,日志能读出缺 runner;
  5. 把服务名临时改掉,确认失败信息能让你定位到名字问题,而不是怀疑加载器。

第 3 步和第 4 步最能暴露设计问题。 换实现要改 Consumer,说明 Definition 漏了东西;服务缺失时看不出缺什么,说明服务名或日志约定没设计好。

Definition 是给别人用的,不是给自己用的。写完先让一个不了解实现的人照着它写 Consumer,能写出来,接口就算立住了。想看服务在运行期消失后会发生什么,读 DSH plugin 服务隔离;想看能力拆成三个包的判断标准,读 能力拆三包。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 自定义服务,为什么用抽象类而不是只写一个 TypeScript interface?

因为 DSH plugin 的服务需要在运行时注册到 ctx 上,抽象类继承 Service 后可以用 super(ctx, 'name') 完成注册;interface 只存在于类型层,不会被运行时识别。接口约束由抽象类承担,类型声明合并负责补全 ctx 的类型。

DSH plugin 自定义服务的默认值应该写在抽象类、Provider 还是调用方?

DSH plugin 的默认值应写在 Definition 暴露的显式步骤里,例如 resolve(request): Spec,让默认值成为契约的一部分。Provider 只实现执行,调用方不需要知道兜底规则,这样换实现时默认行为不会跟着漂移。

DSH plugin 的服务名和包名需要保持一致吗,改名会不会影响已有 Consumer?

DSH plugin 的服务名不需要和包名一致,但一旦被 Consumer 通过 inject 引用就是公开契约。改名等于破坏性变更,所有依赖它的插件都会停在 PENDING。要改就先加新服务名、两套并存一轮,再移除旧名。

DSH plugin 的 Consumer 拿不到自定义服务时,应该报错还是降级?

取决于需求: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 开发文档

来源