DSH plugin 开发指南：插件形态怎么选、能力注册到哪里、本地怎么调试，DSH 插件开发完整路线图

DSH plugin 开发指南解决的是「选路线」问题：先用三种插件形态里的哪一种、把能力注册到 tools 还是 service 还是事件、本地用 --patch 覆盖层还是装进 profile 调试；把这三条线定下来，再照教程动手就不会反复返工。 DSH插件 与 DeepSeek插件 都走同一套插件框架，形态与能力落点的判断标准完全一致。

DSH plugin 开发全景：三条线一次说清

一个 DSH plugin 从想法到跑通，只需要依次回答三个问题。 这三个问题对应官方文档里的三块内容（来源）：

1. 形态——这个插件是纯注册能力的函数，还是要带依赖和配置的对象，还是要对外提供服务的类？
2. 能力落点——这个能力是给模型用（tool）、给别的插件用（service），还是只在某个时机插入（事件）？
3. 调试方式——改源码期间用 --patch 覆盖层热加载，还是打包后装进 profile 验证？

下面三节按这个顺序展开，每节给判断标准而不是罗列 API。

DSH plugin 形态怎么选：函数、对象、类

函数形态覆盖绝大多数插件，只有「对外提供服务」才需要类形态。 官方原文是 「Function form is sufficient in most cases」，并明确指向服务场景才用类形态（来源）。

类形态的最小写法如下，构造函数里做同步初始化，服务名（这里是 myService）就是其他插件 inject 时用的名字：

import { Service, type Context } from '@deepseek-ai/cordis'

export default class MyService extends Service {
  static inject = ['tools']

  constructor(ctx: Context) {
    super(ctx, 'myService')
    // 在这里做同步初始化。
  }
}

注意具名导出与默认导出不能混写：函数形态用具名导出，对象形态和类形态用默认导出——这是加载器识别插件形态的依据，具体自检项见 开发规范。

DSH plugin 能力注册到哪里：tools、service、事件

能力落点由「谁来调用」决定，而不是由「你想写什么」决定。 DSH plugin 的能力有三类消费方，对应三种注册方式（来源）：

• 模型调用 → 注册 tool：用 ctx.tools.register 暴露一个模型可调用的工具，先 inject: ['tools']。
• 其他插件调用 → 注册 service：用类形态把自己注册成服务，消费方通过 inject 拿到实例。
• 框架时机 → 注册事件监听：用 ctx.on 在插件加载、卸载等时机插入逻辑。

事件本身还有五种触发模式，选错模式会导致逻辑不执行或顺序错乱：emit 是广播、bail 短路返回第一个结果、serial 有序执行、waterfall 是管道且必须调用 next() 才会继续往下传。写事件监听前先确认该事件属于哪种模式。

对外暴露工具时用 defineTool 声明参数与输出，让模型知道怎么调用、让框架知道怎么渲染结果：

import { defineTool } from '@deepseek-ai/dsh-tools'

export const inject = ['tools']

export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'my_cap',
    description: 'Execute my capability.',
    parameters: {
      input: { type: 'string', required: true },
    },
    output: {
      schema: { type: 'string' },
      render: (_args, value) => [{ type: 'text', text: value }],
    },
    async execute(args) {
      return args.input.toUpperCase()
    },
  }))
}

DSH plugin 需要可替换提供方时：三角色设计

只有当能力需要「换一个实现而不动调用方」时才拆包，否则不要提前拆。 官方把这类能力拆成三个角色，并用 Bash 执行能力举例：dsh-shell（Service Definition）定义契约、dsh-bash-local（Service Provider）实现本地执行、dsh-tool-bash（Consumer）暴露成模型可调用的工具（来源）。

三条依赖关系是设计的核心：

• Service Provider 依赖 Service Definition；
• Consumer 依赖 Service Definition；
• Provider 与 Consumer 互不依赖。

于是换提供方只需改 cordis.yml 里的一行，Definition 和 tool 都不用动：

# 本地执行
- name: '@deepseek-ai/dsh-bash-local'
# 换一行同样提供该服务的包即可替换实现。

官方给的三条设计要点值得抄进评审清单：不要预防性拆包（简单工具插件不拆）；Request/Result 类型归 Service Definition 所有；显式优于隐式——把默认值放在明确的 resolve(request) 步骤里，而不是藏在 run() 内部的 ?? default。

DSH plugin 调试方式：--patch 覆盖层与安装验证

改源码期间用 --patch 覆盖层，验证分发产物才装进 profile——两者验证的目标不同。 官方教程用覆盖层把本地插件挂进 Web UI，三步完成（来源）：

1. 拿绝对路径 — 在插件仓库根执行 pwd。预期：得到仓库根绝对路径，下一步的 name 字段要用它。
2. 写覆盖层配置 — 新建 cordis.yml，用 insert 把本地插件插进配置树：

- insert:
    - id: hello
      name: '/absolute/path/to/deepseek-harness/scratch-plugin/src/my-plugin.ts'

3. 带 patch 启动 — 执行下面这条命令。预期：Web UI 启动后插件已挂载，之后改源码重启即生效：

pnpm dsh web --patch ./scratch-plugin/cordis.yml

两条硬规则：插件路径必须写绝对路径；patch 文件只贡献配置、不改变 loader 解析模块路径的 profile 目录——所以「patch 里写了却没加载」通常不是语法问题，而是路径解析问题。

要验证打包产物，就换成 profile 安装：dsh plugin --profile <name> add <包>，装完先 dsh --profile demo --dump-config 核对配置层再启动。这两种方式的取舍与更多调试手法见 本地调试。

从 DSH plugin 开发指南到发布

指南定完路线，接下来按「教程 → 规范 → 发布」推进。 建议顺序：

1. 照 开发教程 六步跑通第一个可安装插件；
2. 用 开发规范 的自检清单过一遍导出、依赖、清理、配置；
3. 打包与分发看 打包成 bundle 与 发布到插件中心；
4. 插件装好后在 DSH Plugin Hub 里核对是否出现在已安装列表，并确认配置项展示正常。

如果插件加载后行为不对（没生效、服务报重复注册），先查 插件没激活 与 服务重复注册 两篇排查文，多数问题出在形态选错或 inject 写漏。