ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 能力拆三包:Service Definition、Provider 与 Consumer 怎么分

插件开发发布于 2026-11-05作者: DeepSeek Plugin 插件市场
DSH plugin能力分层Service DefinitionProviderConsumer
同一个能力该写一个包还是三个包?用 Bash 能力的三包结构讲清 Definition、Provider、Consumer 的依赖方向,以及什么时候不该拆。

工具能跑,但你隐约觉得哪里不对:模型调用的是 run_command,真正执行的是本机 shell;哪天要换成容器执行、远端执行,工具代码是不是得跟着改一遍?

这个问题的答案,决定了你要写一个包还是三个包。

DSH plugin 的三种能力角色各管什么

DSH plugin 的一项能力由 Definition、Provider、Consumer 三个角色构成,产出各不相同。 先不急着建目录,把角色对齐。官方把一项通用能力拆成三种角色,各有各的产出:

角色产出例子
Service Definition服务本身 + 请求/结果类型dsh-shell
Service Provider一个具体实现dsh-bash-local
Consumer把能力暴露给模型或用户dsh-tool-bash

Definition 不是接口文档,是可执行的契约。 它导出一个继承 Service 的抽象类,在构造函数里用 super(ctx, 'shell') 注册服务名,并把 Request / Result 类型一起导出。Provider 继承它写实现,Consumer 通过 inject: ['shell'] 拿到 ctx.shell,所以工具插件里看不到命令拼接逻辑——那属于 Provider。

DSH plugin 依赖方向:三条边,少一条就退化成单体

三包结构的核心不是包的数量,而是依赖只能朝一个方向走。 关系可以写成三句话:

  1. Provider 依赖 Definition;
  2. Consumer 依赖 Definition;
  3. Provider 与 Consumer 互不依赖。

为什么不能有第四条边? 一旦 Consumer 直接 import Provider 的内部函数,换 Provider 就变成了改 Consumer;一旦 Provider 引用 Consumer 的工具定义,Provider 就无法脱离模型单独使用。两种都会把「可替换」变成口号。Definition 里除了抽象方法,还应放 resolve(request): Spec 这类显式处理默认值的步骤;把 ?? default 藏在 run() 里,Provider 的默认值就不可见。

DSH plugin 什么时候才该拆包

拆包的门槛是「角色是否需要独立演进」,不是「代码是否够多」。 用三个问题自测:

  1. 这项能力会不会有第二个实现?会,Definition 与 Provider 必须分开;
  2. Provider 会不会独立于工具迭代?会,两者必须分开;
  3. 有没有别的 Consumer 也要用这项能力?有,Definition 必须独立成包。

三个都答「不会」,就别拆;一个包同时承担三种角色完全合法,官方也建议不要预防性拆分。反过来,拆过头的信号很具体: 每个包只有几十行、版本永远一起发、改一处要改三个 package.json、依赖图里出现环——出现这些,说明拆的是目录,不是边界。

走一遍最小的 DSH plugin 三包

最小的 DSH plugin 三包按 Definition、Provider、Consumer 的顺序写,再在 cordis.yml 里组合。 下面按角色顺序写一遍,命令与结构都来自官方实践页的最小示例,做了删减。

先写 Definition。它只做两件事:注册服务名、声明能力方法:

ts
export abstract class MyCapService extends Service {
  constructor(ctx: Context) { super(ctx, 'myCap') }
  abstract execute(request: MyCapRequest): Promise<MyCapResult>
}
export interface MyCapRequest { input: string }
export interface MyCapResult { output: string }

再写 Provider。它继承抽象类,实现方法,然后把自己挂上去:

ts
class MyCapLocal extends MyCapService {
  async execute(request: MyCapRequest) {
    return { output: request.input.toUpperCase() }
  }
}
export const name = 'my-cap-local'
export function apply(ctx: Context) { ctx.plugin(MyCapLocal) }

最后写 Consumer。它只认识 myCap 这个服务名,把能力包成工具:

ts
export const name = 'tool-my-cap'
export const inject = ['tools', 'myCap']
export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'my_cap',
    parameters: { input: { type: 'string', required: true } },
    output: {
      schema: { type: 'string' },
      render: (_args, value) => [{ type: 'text', text: value }],
    },
    async execute(args) {
      const result = await ctx.myCap.execute({ input: args.input })
      return result.output
    },
  }))
}

组合在 cordis.yml 里完成,两行,顺序是 Provider 在前、Consumer 在后:

yaml
- name: '@deepseek-ai/dsh-my-cap-local'
- name: '@deepseek-ai/dsh-tool-my-cap'

验证替换是否真的成立,不要看代码,看配置: 把第一行换成另一个实现同一 MyCapService 的包,重启,工具照常可用,Consumer 一行没改,就算拆对了。

DSH plugin 拆错的三种样子

第一种,Definition 里带实现。 抽象类里顺手写了一个默认的 execute,Provider 不实现也能跑。结果是「可替换」失效,因为默认实现成了事实标准。

第二种,Consumer 直接 new Provider。 工具插件里 import { MyCapLocal } 并自己实例化。配置层再也管不到用哪个实现,cordis.yml 换行也没用。

第三种,把工具当能力。 只写一个 dsh-tool-my-cap,没有 Definition 也没有 Provider:功能能跑,但换执行方式必须改工具,第二个人想复用只能复制代码。

判断自己有没有踩中,有个简单办法:问「换掉执行方式,需要改几个包」。 答案应该是零个包,只改一行配置。拆包的收益是可替换与独立演进,代价是维护成本;两边都算清楚,再决定要不要动目录结构。想看服务与 inject 的运行期行为,读 DSH plugin 服务隔离;想知道一个能力最终该挂在哪个扩展点,读 能力挂到哪个扩展点。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 的能力一定要拆成 Definition、Provider、Consumer 三个包吗?

不一定:只有 DSH plugin 的某个角色需要独立演进或被替换时才拆;角色始终一起改,一个包承担多个角色更省事。官方明确说不要预防性拆分,拆包的成本在版本与依赖维护上。

DSH plugin 里为什么 Service Provider 和 Consumer 之间不应该互相依赖?

因为 DSH plugin 的 Provider 与 Consumer 只应该认识 Service Definition 的约定。Provider 依赖 Definition 提供实现,Consumer 依赖 Definition 调用能力,彼此互不认识,换 Provider 时 Consumer 才能一行不改。

DSH plugin 换了 Bash 的执行后端,工具插件需要跟着改吗?

不需要:DSH plugin 只要在 cordis.yml 里把 Provider 那一行换成另一个实现同一 Service 的包即可,Definition 与 Consumer 都保持原样。这就是三包结构最直接的好处:替换发生在配置层。

DSH plugin 能力只有一个实现、也不会换,拆三包会有什么问题?

DSH plugin 拆三包会多出两个包的版本、发布与依赖维护,收益接近零。这种情况把接口与实现放一个包,甚至把工具也放进去,等真出现第二个实现或独立演进需求时再拆。

相关术语

Service Definition
Service Definition 是定义能力的包,包含 Cordis 服务、请求与结果类型,供 Provider 与 Consumer 共同依赖。— DeepSeek Harness 开发文档
Service Provider
Service Provider 是实现能力的包,继承或实现 Definition 定义的服务,并通过 ctx.plugin 挂载自身。— DeepSeek Harness 开发文档
Consumer
Consumer 是使用能力的包,通常把能力包装成模型可调用的工具,只依赖 Service Definition。— DeepSeek Harness 开发文档
seam
seam 是一项完整能力在架构上的接缝,由 Definition、Provider、Consumer 三种角色共同构成,单个角色不等于 seam。— DeepSeek Harness 开发文档

来源