DSH plugin 开发示例:五种插件形态完整代码整理

本文整理自阿里云开发者社区文章《DSH plugin 开发示例:最小插件、工具插件、事件插件、带配置插件与服务插件的完整代码示例》(2026-09-27),原内容转自 DSH Plugin Hub 插件市场。适合直接备份到个人博客。

一、总览

DeepSeek Harness(DSH)插件开发示例比规范更好上手。五个示例覆盖了插件开发的常见形态,每个都可直接抄进 scratch-plugin/src/,用一个 --patch 覆盖层跑起来。无论叫 DSH 插件还是 DeepSeek 插件,运行步骤完全一样。

示例 用途 关键 API
示例一:最小插件 验证环境与加载链路 apply + name
示例二:模型工具 让模型调用你的能力 inject: ['tools'] + defineTool
示例三:事件监听 在框架时机插入逻辑并自动清理 ctx.effect
示例四:带配置 让用户能改插件行为 Config 类型 + Schema
示例五:提供服务 让其他插件调用你 Service 类形态 + inject

二、通用骨架(三步跑通)

五个示例共用同一套目录与运行方式,差别只在源码里注册了什么。

第 1 步:建目录

在检出根创建 scratch-plugin/src/:

bash 复制代码
deepseek-harness/            # 检出根(已完成 run-from-source)
└── scratch-plugin/
    ├── src/my-plugin.ts     # 下面五个示例都写在这里
    └── cordis.yml           # 覆盖层配置

第 2 步:写覆盖层配置

创建 scratch-plugin/cordis.yml,name 填插件源码的绝对路径:

yaml 复制代码
# scratch-plugin/cordis.yml
- insert:
    - id: demo
      name: '/absolute/path/to/deepseek-harness/scratch-plugin/src/my-plugin.ts'

第 3 步:启动

bash 复制代码
pnpm dsh web --patch ./scratch-plugin/cordis.yml

预期:Web UI 起来,并把 my-plugin.ts 挂进插件树。

⚠️ 注意:路径必须写绝对路径。patch 只贡献配置、不改变 loader 解析模块路径的 profile 目录。环境没搭好的先看"开发环境搭建"。

三、示例一:最小插件

用途 :验证环境与加载链路。只有一个会打日志的 apply。

ts 复制代码
import type { Context } from '@deepseek-ai/cordis'

export const name = 'hello-plugin'

export function apply(ctx: Context) {
  console.log('[hello-plugin] plugin loaded!')
}

预期结果 :启动时终端打印 [hello-plugin] plugin loaded!。看不到这行就别往下走,先排查路径与构建。

四、示例二:模型工具

用途 :让模型能调用你的能力。注意 inject 与 defineTool 三件套。

ts 复制代码
import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'

export const name = 'greet-tool'
export const inject = ['tools']

export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'greet',
    description: 'Greet someone by name.',
    parameters: {
      name: { type: 'string', required: true, description: 'The name to greet' },
    },
    output: {
      schema: { type: 'string' },
      render: (_args, value) => [{ type: 'text', text: value }],
    },
    async execute(args) {
      return `Hello, ${args.name}!`
    },
  }))
}

预期结果 :向模型输入「Use the greet tool to greet Ada.」,模型调用 greet 并拿到 Hello, Ada!。execute 契约与卡片渲染的完整规则见"怎么写工具插件"。

五、示例三:事件监听与自动清理

用途 :在框架时机插入逻辑,并正确释放手动资源。通过 ctx.on 注册监听、通过 ctx.effect 交出处置器。

ts 复制代码
import type { Context } from '@deepseek-ai/cordis'

export const name = 'heartbeat-plugin'

export function apply(ctx: Context) {
  ctx.effect(() => {
    const timer = setInterval(() => console.log('heartbeat'), 5000)
    // 返回的函数在插件卸载时执行。
    return () => clearInterval(timer)
  })
}

预期结果 :插件运行后每 5 秒打印一次 heartbeat;卸载插件后定时器停止。

⚠️ 常见坑:把定时器直接写在 apply 里而不包 ctx.effect,插件卸载后仍会继续跑------这是最常见的资源泄漏来源。

六、示例四:带配置的插件

用途 :让用户能改你的行为。声明 Config 类型与同名 schema,apply 接收第二个参数。

ts 复制代码
import type { Context } from '@deepseek-ai/cordis'
import Schema from '@deepseek-ai/schemastery'

export interface Config {
  greeting: string
  maxRetries: number
}

export const Config: Schema<Config> = Schema.object({
  greeting: Schema.string().default('Hello'),
  maxRetries: Schema.number().default(3),
})

export const name = 'configured-plugin'

export function apply(ctx: Context, config: Config) {
  console.log(`${config.greeting} (retries: ${config.maxRetries})`)
}

预期结果 :不提供配置时打印默认值 Hello (retries: 3);提供部分配置时,未提供的字段被补上默认值。配置在界面上的展示见"插件配置怎么用"。

七、示例五:提供服务

用途 :让其他插件调用你。这时才需要类形态------构造函数里注册服务名,消费方用 inject 声明。

ts 复制代码
import { Service, type Context } from '@deepseek-ai/cordis'

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

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

  count(name: string) {
    console.log(`[metrics] ${name}`)
  }
}

预期结果 :插件加载后,其他插件用 export const inject = ['metrics'] 即可在 apply 里拿到 ctx.metrics。

💡 只有对外提供服务时才用类形态,普通插件用函数形态更简单。

八、从示例到可安装的包

示例只在检出里跑通,还不能分发。要变成可安装的包,需要补三样:

  1. package.json 里声明:
    • main(指向入口)
    • type: module
    • files(包含入口与 cordis.patch.yml)
    • dsh.bundle.patch(指向该 patch 文件)
  2. 把它放进一个带 cordis.patch.yml 的工程目录。

发布路径:先照"打包成 bundle"生成可安装产物,再用"发布到插件中心"提交收录;装好后可在 DSH Plugin Hub 的已安装列表核对插件与配置项。写代码时的硬性自检项见"开发规范"。

九、常见问题(FAQ)

Q1:哪个示例最适合先照着跑一遍? 先跑最小插件:只有 name 与一个会打日志的 apply,用 --patch 覆盖层挂进 Web UI,看到日志就说明环境与加载链路都通了。官方也把最小插件放在教程第一步,因为后面所有示例都只是往这个骨架里加注册代码。

Q2:目录结构应该怎么摆? 分两阶段:本地调试阶段官方从仓库根创建 scratch-plugin/src/,用绝对路径挂载;准备分发时再把工程独立出来,带上 package.json(main、type: module、files、dsh.bundle.patch)与 cordis.patch.yml。两者不是二选一:先在检出里调通,再把它抽成可安装的包。

Q3:有没有一段示例能同时展示工具与配置? 把工具示例与配置示例叠起来就是:先声明 inject = ['tools'] 与 Config schema,再在 apply(ctx, config) 里用 config 的值构造 defineTool 的 description 或行为。注意 apply 的第二个参数来自框架按 schema 补齐后的配置对象,可直接使用。

Q4:服务示例里的类写法和普通插件有什么区别? 服务示例用类形态:export default class ... extends Service,在构造函数里 super(ctx, 'myService') 把服务名注册进上下文,其他插件通过 inject: ['myService'] 消费。普通插件注册能力就结束,服务插件还对外提供实例------所以只有"别的插件要调用你"时才用类形态。


版权说明:本文转自 DSH Plugin Hub 插件市场,版权归属 DSH Plugin Hub 插件市场。原文发布于阿里云开发者社区。

相关推荐
Yk酱2284035 分钟前
A2UI随笔-demo-01
前端
云起SAAS37 分钟前
本地生活同城多商户商城系统源码源码 合伙人分红加区域代理加排队返现
前端·javascript·后端
奶油话梅糖1 小时前
3 天 1,705 Star:DeepSeek 开源官方聊天前端——零后端纯静态,浏览器直连 API
前端·开源
Linye1 小时前
HTML 流程图连线交叉看不清?聊聊画布避障折线与跳弧实现
前端·人工智能
接着奏乐接着舞_1 小时前
Electron 白屏问题排查及解决记录
前端
htzyl2061 小时前
前端监控最容易写错的 18 个地方:从平均值到 beforeunload
前端·浏览器
鹿鹿鹿鹿isNotDefined2 小时前
布局更新后,canvas 重新绘制,出现了只持续一帧的闪烁?!
前端·javascript·vue.js
zhanlang02172 小时前
HTML 零基础入门到企业实战【第六章 表格标签】6.3 单元格合并:跨行 rowspan、跨列 colspan 实战技巧
前端·html
技术分享官2 小时前
Geejing WebBuilder 新手指导:用 Wb.Button 按钮组件跑通企业级快速开发平台的前后端闭环
前端·javascript·低代码