本文整理自阿里云开发者社区文章《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。
💡 只有对外提供服务时才用类形态,普通插件用函数形态更简单。
八、从示例到可安装的包
示例只在检出里跑通,还不能分发。要变成可安装的包,需要补三样:
- package.json 里声明:
main(指向入口)type: modulefiles(包含入口与cordis.patch.yml)dsh.bundle.patch(指向该 patch 文件)
- 把它放进一个带
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 插件市场。原文发布于阿里云开发者社区。