jwilson411/dsh-plugin-kit

dsh-plugin-kit

一个极简、可安装的 DeepSeek Harness 函数插件模板。它是仍然算得上真正插件的最小形态：一个包，既是 profile bundle（它附带一个 patch 层），又是该层所挂载的 plugin，只注册一个面向模型的工具 kit_ping。

复制它，重命名它，替换掉那个工具。

安装

dsh plugin --profile web add github:jwilson411/dsh-plugin-kit

dsh plugin 会在 $DSH_HOME/profiles/web 内转发给 pnpm，然后根据已安装状态对 profile 进行协调：由于此包的 manifest 声明了 dsh.bundle.patch，它会被追加到 profile manifest 有序的 dsh.profile.bundles 列表中，其 patch 也就成为一个层。没有该声明的包会作为普通依赖安装，而不是一个层。

移除方式相同，把 add 换成 remove 即可。

锁定的 DSH 候选版本

此包是针对锁定的候选版本 0.1.1-rc.2 编写并测试的——即当前的 @deepseek-ai/dsh 版本以及与之匹配的 @deepseek-ai/dsh-tools@0.1.1-rc.2，后者被精确锁定在 devDependencies 中，以便测试针对一个已知 API 运行。peer 范围是 ^0.1.1-rc.2，与 harness 自身工具包声明它的方式一致。

请注意，@deepseek-ai/dsh-tools 的 npm latest 标签仍指向较旧的 0.0.1-rc.1；0.1.1-rc.2 系列发布在 next 下。请显式锁定，而不要依赖该标签。

它注册了什么

| | |
|---|---|
| Cordis 插件 id | plugin-kit（cordis.patch.yml 中的行 id） |
| 注入 | tools —— 硬依赖；插件会等待而非降级 |
| 工具 | kit_ping |
| 参数 | who（字符串，必填） |
| 返回 | { message, greeted, plugin } |

kit_ping 是一个存活检查：它不读取任何内容，不写入任何内容，也不访问网络，因此可以安全地安装在任何地方，且不需要 API 密钥。

目录结构

package.json        manifest + dsh.bundle.patch —— 正是它使其成为 bundle
cordis.patch.yml    bundle 的 patch 层：一次 insert，一行 plugin
src/index.js        插件：name、inject、apply(ctx)
test/               离线测试，无网络、无凭据

两个部分

manifest 声明 patch。 这个字段正是 profile 安装器所要查找的；没有它，这个包就只是一个库：

"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }

patch 挂载插件。 patch 文件是一个顶层 YAML 数组，由 patch 条目组成，并叠加在其下方的 bundle 之上：

- insert:
- id: plugin-kit
name: dsh-plugin-kit

各层按顺序组合：先是按 dsh.profile.bundles 顺序排列的每个 bundle 的 patch，然后是 profile 自身的 cordis.patch.yml，接着是 home 级文件，最后是任何 --patch 覆盖层。较后的层通过行的 id 来定位某一行。这样的 patch 会替换该行的整个 config，而不是合并进去，因此覆盖时必须重新声明它要保留的字段。
使用 dsh --dump-config 检查组合后的树，而无需启动它。

插件

具名导出会保留加载器的注入元数据，因此请逐个导出它们，而不是作为一个默认对象导出：

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

export const name = 'plugin-kit'
export const inject = ['tools']

export function apply(ctx) {
ctx.tools.register(createKitPingTool())
}

注册发生在 apply 内部，这样 Cordis fiber 就拥有该副作用：停止、更新或重新加载插件都会注销该工具。register 会返回一个 disposer 以实现有序的所有权管理；如果插件只为自身的生命周期注册，则无需保留它。不要在模块作用域中注册。

inject: ['tools'] 声明了一个硬依赖。对于插件可以缺少的能力，请改用 ctx.get('name') 并处理 undefined——在未声明注入的情况下直接访问 ctx.tools 会被守卫拒绝。

工具

defineTool 会从 parameters 推断参数类型，并在函数体运行前针对该类型验证每次调用，因此 execute 接收到的参数是经过类型化、已验证的，而失败路径由 API 负责，而不是由你负责。

在你编辑 schema 之前，有两个值得了解的契约细节：

- 参数映射是一个隐式的开放对象根。 每个属性都带有自己的 required: true；编译后的 schema 没有 additionalProperties: false，并且 API 没有提供任何关闭它的方式，因此未知键会被容忍并忽略。缺失属性、类型错误以及非对象参数都会以 ToolArgsError 拒绝。
- 嵌套对象和输出对象必须显式声明 additionalProperties，这样它们就永远不会获得意外的默认值。

output.schema 是规范的结果契约，而 output.render 是将已验证的值纯投影为模型所看到的内容块。参数和结果都必须是无损 JSON。

测试

npm install
npm test

从构造上就是离线的：apply 被传入一个记录注册的桩上下文，而该工具通过注册表调用的同一个 execute 来驱动。不会启动任何 profile，不会打开任何套接字，不会读取任何密钥。测试套件覆盖了注册、与其声明的输出 schema 匹配的成功调用、渲染投影、对错误参数的显式失败，以及 manifest/patch 接线。

CI（.github/workflows/ci.yml）在 Node 22 和 24 上运行同样的两条命令，并且不需要任何凭据。

让它成为你自己的

1. 重命名 package.json 中的包，并将 cordis.patch.yml 中的 name: 改为与之匹配——patch 行通过包名解析插件。
2. 为该行选择一个新的 id，并在 src/index.js 中选择一个新的 name。
3. 替换 kit_ping：它的 schema、它的函数体、它的描述。描述是面向模型的——说明该工具做什么以及何时使用它。
4. 保持测试诚实；断言你实际交付的契约。

许可证

MIT——参见 LICENSE。