前言¶
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，因此本文不提供具體目錄鏈接。
