前言¶
DSH 的理念是「一切皆插件」。对插件开发者来说，单写一个 tool 或一个 hook 并不难，难的是把 Config、Tool、Events、Service、Hook 和 browser client half 放进同一个可安装 bundle，并让它能在 profile 里正确激活。
下面介绍 dsh-plugin-template。它不是某个具体业务插件，而是一个 starter template：用最小可读的代码展示 DeepSeek Harness 插件的常见形态，适合作为本地开发模板，也适合用来阅读 DSH 插件的结构边界。
这是什么¶
dsh-plugin-template 是一个面向 DSH 插件开发的入门模板，仓库路径为 kun2-5code/dsh-plugin-template，包名为 dsh-plugin-template，package.json 中版本为 0.1.0，许可证为 MIT。
它在一个 installable bundle 中演示了六类常见插件形态：
- Config
- Tool
- Events
- Service
- Hook
- Browser half（client）
它遵循 DSH 的 bundle distribution model：包内声明 dsh.bundle 与 cordis.patch.yml，通过 dsh plugin add 作为 config layer 激活。
package.json 中还声明了浏览器端入口：
{
"dsh": {
"bundle": {
"patch": "./cordis.patch.yml"
},
"client": {
"platform": "web",
"inject": [
"slots"
]
}
}
}
这里的 client.platform 为 web，inject 包含 slots。也就是说，它同时覆盖了 host 端插件逻辑和 browser 端 UI 注册。
核心能力¶
Config¶
模板包含 Config interface 和 Schemastery schema。加载时应用 validation 和 defaults。
这类配置适合用来学习 DSH 插件如何把插件内部状态接到 settings namespace，而不是自己维护一套独立配置。
Tool¶
Tool 通过以下 API 注册：
ctx.tools.register(defineTool(...))
模板中的 greet 工具具有 presentResult render intent。
Events¶
Events 使用 ctx.on / ctx.emit，并通过 declaration merging 提供 typed events。
适合用来观察 DSH 插件事件如何在类型层面扩展，而不是依赖字符串事件名。
Service¶
Service 是一个 class-form plugin，可向其他插件提供服务。
service.ts 是可选示例，默认禁用。
Hook¶
Hook 提供 tools/pre-execute 权限门，可按配置拒绝工具调用。
hook.ts 也是可选示例，默认禁用。
Browser half¶
Browser half 会在 14 个 surfaces 注册 browser UI。资料中列出的位置包括：
- clickable config card
- sidebar footer action
- input dock
- shell overlay
- header utility
- input tool-row buttons
/dsh-democommand row- General settings row
- Plugins tab
- settings header action
- session header action
- composer dock
- per-message actions
其中 clickable config card 可写入 greeting、maxRetries、verbose。在 stock harness 上，这张卡片会渲染 read-only 的 “not exposed” explainer，而不是直接消失。
这里有一个边界需要分清：只有 config card 的数据路径受 harness allowlist 限制；其他十三个是 pure slot registrations，可以在任意 harness 上工作。
演示命令¶
模板还包含两个演示斜杠命令：
/hello：replies world/dsh-demo：custom row
这些命令用于验证 host half 的命令注册和 client 端 command row 的展示位置。
安装与启用¶
本地目录安装¶
先做本地安装，适合确认模板能跑通：
dsh plugin --profile demo add /path/to/dsh-plugin-template
这里的 /path/to/dsh-plugin-template 需要替换成你机器上的实际目录。
安装后可以先看 config layer：
dsh --profile demo --dump-config
正常应能看到 # == dsh-plugin-template 这一层。
然后启动 DSH：
dsh --profile demo
注意：自定义命名的 profile，例如 demo，只包含 dsh-base，是 headless 的，没有 GUI。若要查看 Web GUI 和 config card，需要使用 web profile。
GitHub 安装¶
README 给出的 GitHub 安装示例是：
dsh plugin --profile demo add github:you/dsh-plugin-template
这里的 you 是占位命令，fork 后应替换为你自己的仓库路径。
GitHub 安装会拉取源码；pnpm 会执行 prepare，也就是用 tsdown 构建 lib/。
在 pnpm ≥10 时，首次 git-dependency prepare 可能被拒绝。需要把 pnpm 输出的包名加入 profile 的 pnpm-workspace.yaml，然后重试：
allowBuilds:
dsh-plugin-template: true
allowBuilds 会授权在安装时执行该包代码。只允许信任源码，并优先固定 commit：
github:you/dsh-plugin-template#<sha>
本地开发 overlay¶
如果你在 deepseek-harness 源码 checkout 内开发，可以直接加载模板源码：
pnpm dsh web --patch /absolute/path/to/dsh-plugin-template/dev/cordis.yml
/absolute/path/to/dsh-plugin-template 需要替换为本机绝对路径。
--patch overlay 只加载插件的 host half。若要测试 browser-half config card，必须把插件安装到 profile，并按 name: dsh-plugin-template 解析。
开发期间可以运行这些检查：
pnpm install
pnpm typecheck
pnpm build
node test/smoke.mjs
如果这个模板位于 deepseek-harness checkout 内，pnpm install 可能被父 workspace 捕获。此时应使用：
pnpm install --ignore-workspace
或者把模板单独克隆出来再安装。
适用场景与注意¶
适合用它做以下事情：
- 学习 DSH 插件的 Config、Tool、Events、Service、Hook 结构。
- 查看 browser client half 如何在多个 UI surfaces 注册。
- 理解
dsh.bundle、cordis.patch.yml和dsh plugin add的 bundle 安装关系。 - 作为自己的 DSH 插件 fork 起点。
使用前注意：
- 插件以当前
dsh进程权限运行，安装前应检查源码与许可证。 service.ts与hook.ts是可选示例，默认禁用。demo这类自定义 profile 是 headless；要看 config card 和 Web GUI，需要webprofile。allowBuilds会授权安装时执行包内代码，只应加入信任源码。- 不要把该仓库或社区目录理解为 DeepSeek 官方应用商店；社区目录是独立站点，不应写成与 DeepSeek 或幻方有官方从属关系。
小结¶
dsh-plugin-template 的价值在于把 DSH 插件最常见的六类形态放进同一个可安装 bundle，并明确区分 host half、browser half、config card、slot registration 和 bundle 激活边界。它适合先读懂结构，再改造成自己的插件。
- GitHub：https://github.com/kun2-5code/dsh-plugin-template
- 许可证：
MIT
现有资料未给出已核实的社区目录页 URL，因此本文不提供具体目录链接。
