前言¶

DeepSeek Harness（DSH）採用「一切皆插件」的架構。開發一個新工具插件通常需要處理配置、Schema 定義、打包發佈等繁瑣流程。dsh-plugin-template 提供了一個最小可用骨架，包含純 ESM 架構、零依賴配置以及腳手架腳本，幫助開發者快速起步。

插件簡介¶

本倉庫是 DSH 插件的模板代碼，用於創建新的 npm bundle 插件。
- 名稱：dsh-plugin-template
- 維護者：ZhijiangTang
- 分類：客戶端
- 許可證：MIT
- 核心價值：腳手架一個新工具插件的最小可用骨架。

核心特性¶

• 純 ESM 架構，無需 Babel/TypeScript 編譯步驟。
• 零依賴，直接使用 peerDependencies 中的核心庫。
• 包含 hello_world 佔位工具，展示參數定義、輸出 schema、渲染和執行邏輯。
• mount 自檢機制走真實的 ctx.tools.execute 管道。
• 提供內置 scaffold.sh 腳手架腳本。

使用步驟¶

先做 X，再做 Y。以下以創建新包名 dsh-mytool 爲例。

1. 初始化項目¶

使用模板倉庫自帶的腳手架腳本生成骨架。

bash scripts/scaffold.sh dsh-mytool

2. 修改配置文件¶

生成後需手動調整核心配置：

• package.json：
• 刪除 private: true 字段（否則無法發佈 npm）。
• 修改 name 爲你的 npm 包名。
• 修改 keywords，例如 ["dsh-plugin", "dsh-mytool"]。
• cordis.patch.yml：
• 修改 id：插件的穩定身份，每次啓動重新掛載。
• 修改 name：按 npm 包名引用代碼。
• index.js：
• 修改插件名 export const name。
• 修改工具名 name: 'hello_world'。
• 根據需求重寫參數定義、輸出 schema 和執行邏輯。

3. 本地驗證¶

本模板本身不是可安裝插件（private: true），需先發布或通過 file: 協議本地加載。

# 安裝本地插件（必須使用 file: 協議）
dsh plugin --profile px-tdemo add file:./plugins/dsh-mytool

# 啓動並觀察自檢日誌
dsh --profile px-tdemo --port 0 2>&1 | grep -m1 'self-test ok'

4. 發佈¶

配置無誤後，發佈到 npm。

cd plugins/dsh-mytool
pnpm publish

常見注意點¶

• 本地安裝協議：本地測試必須使用 file:./目錄 協議，./目錄 會被解析爲符號鏈接導致找不到模塊。
• Schema DSL 限制：output.schema 不接受頂層 required 數組，必須使用屬性級 required: true。
• pnpm 24h 門控：新版本發佈不滿 24h，pnpm add 可能解析到舊版，建議顯式指定版本號。
• 原生依賴處理：若插件包含原生依賴（如 node-pty），需在 profile 的 pnpm-workspace.yaml 中配置 allowBuilds。插件儘量保持零原生依賴。
• 非發佈倉庫：本倉庫本身設置了 private: true，不發佈 npm，僅作爲模板使用。

總結¶

dsh-plugin-template 是一個輕量級的開發腳手架，適合需要快速搭建 DSH 插件的開發者。它通過零依賴、無構建步驟的純 ESM 設計，降低了開發門檻。
- GitHub：https://github.com/ZhijiangTang/dsh-plugin-template
- 目錄頁：https://www.skillhub.cn/plugins/ZhijiangTang/dsh-plugin-template