写第一个插件:从加载到注册工具
核验于 2026-10-31dsh 0.2.1-rc.5版本说明
插件最小结构
一个 dsh 插件就是一个导出 apply 函数的模块。dsh 加载插件时调用 apply,并把 ctx 作为参数传进来;你在 ctx 上注册工具、事件或其他能力。
export const name = 'hello-plugin';
export function apply() {
console.log('[hello-plugin] plugin loaded!');
}
上面这段代码就是插件的全部结构:不需要构建步骤,没有必须继承的类,也不需要事先登记插件清单。仓库里可运行的版本在 examples/01-hello-plugin/index.js。
用 patch 加载(实测)
开发阶段用 --patch 覆盖层加载最方便。新建一个 hello.patch.yml,其中 name 必须写成绝对路径:
- insert:
- id: hello
name: '/absolute/path/to/dsh-handbook/examples/01-hello-plugin/index.js'
在存放 hello.patch.yml 的目录里启动:
dsh web --patch ./hello.patch.yml
启动日志里出现下面这一行,就说明插件已经被加载:
[hello-plugin] plugin loaded!
2026-10-31 在 Windows 上实测:执行 npx @deepseek-ai/dsh@0.2.1-rc.5 web --patch ... --no-open,约 20 秒后打印加载日志。
patch 文件里的
name不会按“相对于 patch 文件所在目录”来解析;写成相对路径会找不到模块。先执行pwd打印当前目录,再拼出绝对路径。
打包成 bundle 并安装(实测)
要让别人也能安装,就要把插件目录打包成组合包。组合包的目录结构:
01-hello-plugin/
├─ package.json
├─ cordis.patch.yml
└─ index.js
组合包的 package.json 里起作用的两个字段是 dsh.bundle 与 engines.dsh:
{
"name": "dsh-plugin-hello",
"version": "0.1.0",
"type": "module",
"main": "index.js",
"files": ["index.js", "cordis.patch.yml"],
"license": "MIT",
"dsh": { "bundle": { "patch": "./cordis.patch.yml" } },
"engines": { "dsh": ">=0.2.0 <0.3.0" }
}
组合包里的 cordis.patch.yml 用包名 dsh-plugin-hello 引用插件,不再写源码路径:
- insert:
- id: hello
name: dsh-plugin-hello
把插件装进一个测试 profile。命令里的 ./examples/01-hello-plugin 是相对路径,要在本手册仓库 dsh-handbook 的根目录执行:
dsh plugin --profile hello add ./examples/01-hello-plugin
dsh --profile hello --dump-config
实测输出:profile 初始化成功,dsh-plugin-hello 以链接方式加入,--dump-config 里能看到 dsh-plugin-hello 这条 bundle 记录;再用 dsh --profile hello web --no-open 启动,6 秒后打印加载日志。
注意:dsh plugin 依赖 pnpm。本机没有 pnpm 时,这条命令会直接报“不是内部或外部命令”,具体处置见 插件安装与排错。
注册一个工具
工具插件在 apply 里调用 ctx.tools.register 登记工具,并用 defineTool 描述参数的结构与输出的格式。下面这段代码取自官方文档《开发一个工具》(docs/user/develop/basic/tool.zh.md):
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}!`;
},
}));
}
三个要点:
inject = ['tools']:声明插件依赖工具注册表,Cordis 要等工具注册表就绪之后再挂载该插件。parameters用来校验模型生成的参数;execute里拿到的args已按parameters声明的类型校验过。output.render决定工具结果以什么形式呈现给模型;execute的返回值必须符合output.schema声明的规范。
核验状态: 最小加载与 bundle 安装已实测;工具注册代码按官方《开发一个工具》教程编写,本页没有完成“带模型 Key 调用 greet 工具”的端到端验证。工具版插件还需要把 @deepseek-ai/dsh-tools 写进包依赖,具体包结构以官方文档为准。
发布到 npm 与 GitHub
- 包名要用
dsh-plugin-前缀或带作用域,package.json保留dsh.bundle与engines.dsh两个字段。 files只放运行需要的文件,不要把测试和本地配置发上去。- 发布前在一个干净的 profile 里重新安装一次,确认插件能被加载。
- 在 GitHub 仓库加上
dsh-plugintopic,方便别人搜索到插件。 - 不把 API Key、cookie、个人路径写进仓库。
延伸阅读
- 官方开发教程:第一个插件
- 工具编写参考:adding-a-tool
- 插件安装与报错:插件安装与排错