DSH plugin 能力拆三包:Service 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 依赖方向:三条边,少一条就退化成单体
三包结构的核心不是包的数量,而是依赖只能朝一个方向走。 关系可以写成三句话:
- Provider 依赖 Definition;
- Consumer 依赖 Definition;
- Provider 与 Consumer 互不依赖。
为什么不能有第四条边? 一旦 Consumer 直接 import Provider 的内部函数,换 Provider 就变成了改 Consumer;一旦 Provider 引用 Consumer 的工具定义,Provider 就无法脱离模型单独使用。两种都会把「可替换」变成口号。Definition 里除了抽象方法,还应放 resolve(request): Spec 这类显式处理默认值的步骤;把 ?? default 藏在 run() 里,Provider 的默认值就不可见。
DSH plugin 什么时候才该拆包
拆包的门槛是「角色是否需要独立演进」,不是「代码是否够多」。 用三个问题自测:
- 这项能力会不会有第二个实现?会,Definition 与 Provider 必须分开;
- Provider 会不会独立于工具迭代?会,两者必须分开;
- 有没有别的 Consumer 也要用这项能力?有,Definition 必须独立成包。
三个都答「不会」,就别拆;一个包同时承担三种角色完全合法,官方也建议不要预防性拆分。反过来,拆过头的信号很具体: 每个包只有几十行、版本永远一起发、改一处要改三个 package.json、依赖图里出现环——出现这些,说明拆的是目录,不是边界。
走一遍最小的 DSH plugin 三包
最小的 DSH plugin 三包按 Definition、Provider、Consumer 的顺序写,再在 cordis.yml 里组合。 下面按角色顺序写一遍,命令与结构都来自官方实践页的最小示例,做了删减。
先写 Definition。它只做两件事:注册服务名、声明能力方法:
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。它继承抽象类,实现方法,然后把自己挂上去:
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 这个服务名,把能力包成工具:
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 在后:
- 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 服务隔离;想知道一个能力最终该挂在哪个扩展点,读 能力挂到哪个扩展点。
常见问题
不一定:只有 DSH plugin 的某个角色需要独立演进或被替换时才拆;角色始终一起改,一个包承担多个角色更省事。官方明确说不要预防性拆分,拆包的成本在版本与依赖维护上。
因为 DSH plugin 的 Provider 与 Consumer 只应该认识 Service Definition 的约定。Provider 依赖 Definition 提供实现,Consumer 依赖 Definition 调用能力,彼此互不认识,换 Provider 时 Consumer 才能一行不改。
不需要:DSH plugin 只要在 cordis.yml 里把 Provider 那一行换成另一个实现同一 Service 的包即可,Definition 与 Consumer 都保持原样。这就是三包结构最直接的好处:替换发生在配置层。
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 开发文档
来源
- DeepSeek Harness 开发文档:能力的三种角色· deepseek-harness
- DeepSeek Harness 开发文档:服务与依赖· deepseek-harness
- deepseek-harness 仓库· deepseek-ai