前言¶

在 DeepSeek Harness（DSH）裏做帶設置頁的客戶端插件，通常要同時處理宿主側註冊、瀏覽器側 UI、文案與構建產物如何被 dsh plugin add 識別。從零搭目錄、package.json 的 exports 與 dsh 清單、cordis.patch.yml 掛接方式，容易在細節上反覆試錯。下面介紹維護者 longyi-0x0 發佈的 dsh-plugin-template：一個不含業務接口與示例業務邏輯的最小插件，保留 TypeScript 宿主入口、React TSX 空設置頁、中英雙語、esbuild 構建與 vitest 測試，便於用 GitHub「Use this template」複製後改名、加業務再安裝驗證。

這是什麼¶

dsh-plugin-template 是 DSH 插件模板，分類爲客戶端。倉庫：GitHub — longyi-0x0/dsh-plugin-template；社區目錄頁：skillhub.cn/plugins/longyi-0x0/dsh-plugin-template。當前 package 版本爲 0.1.0，許可證 MIT（見倉庫 LICENSE）。

它解決的是「先有一個能裝、能編、能測的標準骨架」：宿主在 src/host/index.ts 提供 name / inject / apply；瀏覽器側是空的設置頁骨架；locale/{zh,en}.json 提供插件頁 meta 與界面字典；target/index.js 與 target/client.js 爲已提交的構建產物，因此通過 link: 或 GitHub 安裝時不必在目標機器上現場構建。

目錄與入口¶

README 中的目錄結構如下（入口由 package.json 的 exports['.'] / exports['./client'] 指向 target/）：

package.json               exports、dsh 清單、腳本與開發依賴
cordis.patch.yml           把插件掛進 DSH 配置樹的一行
src/host/index.ts          宿主入口：name / inject / apply
src/host/context.ts        宿主側最小結構化類型
src/client/index.tsx       React TSX：空設置頁 + inject/apply
src/client/i18n.ts         從 locale JSON 導入的類型化字典
src/client/styles.ts       主題變量樣式
src/client/context.ts      Slots / Locale / SlotProps 類型
scripts/build.mjs          esbuild：host → target/index.js，client → target/client.js
target/index.js            宿主產物（提交，不要手改）
target/client.js           瀏覽器產物（提交，不要手改）
locale/{zh,en}.json        meta（插件頁標題/簡介）+ ui（界面字典）
icon.svg                   插件圖標
test/                      vitest：i18n + client 冒煙

核心能力¶

宿主與 Cordis 掛接¶

宿主側在 apply 中擴展服務、路由或監聽器；需要宿主服務時在 inject 中聲明名稱，並補全 src/host/context.ts。插件通過 cordis.patch.yml 掛入 DSH 配置樹；package.json 中 dsh.bundle.patch 指向該文件。

瀏覽器設置頁與插槽¶

客戶端平臺爲 web。默認 dsh.client.inject 激活：

• @deepseek-ai/dsh-client-locale
• @deepseek-ai/dsh-client-ui-settings

client.inject 只控制平臺包激活順序，不是運行期 import。需要其他插槽時，把對應平臺包加入該數組；插槽清單可安裝 dsh-slot-explorer 查看。瀏覽器半區最終打包爲單個 target/client.js；不 import DSH Client 運行期包，UI 結構、主題與可訪問性需按 DSH 規範自行實現。

雙語與類型化文案¶

locale/{zh,en}.json 是唯一文案來源：

• meta.title / meta.description：插件列表展示，宿主直接讀取；
• ui：界面字典，經 src/client/i18n.ts 在 esbuild 構建時內聯進 target/client.js。

en.ui 的鍵自動成爲 MessageKey，zh.ui 須補齊相同鍵，t('key') 在編譯期檢查。

構建與校驗¶

開發依賴 Node >= 20。常用腳本：

npm install        # 開發與 CI
npm run build      # 生成 target/index.js、target/client.js
npm run dev        # 監聽 src/ 自動重建
npm run build:check# 校驗提交的 target/ 與源碼一致
npm run typecheck  # host + client 兩套 tsc
npm run check      # build:check + typecheck + test

宿主：esbuild 打包 src/host/index.ts → target/index.js（ESM，Node 內置模塊 external）。瀏覽器：esbuild 打包 src/client/index.tsx → CJS，react / react/jsx-runtime external，再套 window.__ModuleLoader__.load({ id: <package name>, factory })。target/client.js 文件頭標註爲生成文件，勿手改。

測試¶

npm test           # vitest run
npm run check      # build:check + typecheck + test

覆蓋中英字典鍵一致性、瀏覽器 bundle 的模塊 id / factory / 插槽註冊；組件不做渲染測試。CI 在 .github/workflows/test.yml 中執行 npm ci 與 npm run check。

從模板到新插件¶

1. 在 GitHub 上對倉庫點 Use this template 創建新倉庫。
2. 按 README 表格改名：package.json 的 name（建議 dsh-plugin-<名字>）、cordis.patch.yml 的 name（須與包名一致）、src/client/i18n.ts 的 NS、locale/*.json 的 meta/ui、icon.svg。
3. 在 src/host/index.ts 的 apply 與 src/client/index.tsx 中加入業務；需要時在 dsh.client.inject 中增加平臺包。
4. 本地執行 npm install、npm run build、npm test，並提交 target/index.js / target/client.js；CI 用 build:check 防止產物過期。

安裝與啓用¶

產物已提交，link: 或 GitHub 安裝均不需要在安裝端構建。安裝後需重啓 DSH；若修改並重新構建 target/client.js，也需重啓應用（瀏覽器 bundle 在啓動時裝配）。

macOS（示例 profile 名爲 desktop）：

"/Applications/DeepSeek Harness.app/Contents/Resources/runtime/cli/bin/dsh" \
  plugin --profile desktop add "link:/path/to/your-plugin"

或從 GitHub 安裝（將 your-name/your-plugin 換成你的倉庫）：

dsh plugin --profile desktop add "github:your-name/your-plugin"

Windows：

& "$env:LOCALAPPDATA\Programs\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd" `
  plugin --profile desktop add "link:C:\path\to\your-plugin"

清單字段（摘錄）¶

"dsh": {
  "manifestVersion": 1,
  "bundle": { "patch": "./cordis.patch.yml" },
  "client": {
    "platform": "web",
    "inject": [
      "@deepseek-ai/dsh-client-locale",
      "@deepseek-ai/dsh-client-ui-settings"
    ]
  }
}

適用場景與注意¶

適合需要客戶端設置頁 + 宿主擴展、並希望沿用 TypeScript、React、esbuild 與 vitest 工作流的 DSH 插件作者。默認無 CSS Modules，樣式使用主題變量與 React style 對象；locale/*.json 的 ui 會內聯進瀏覽器 bundle。組件渲染與安裝後的外觀仍須在運行中的 DSH 裏驗證。

DSH 生態理念是「一切皆插件」；社區目錄 skillhub.cn 爲獨立站點，與 DeepSeek / 幻方無官方從屬關係。插件在當前 dsh 進程權限下運行，安裝前應閱讀源碼並確認 MIT 等許可證是否滿足你的使用條件。本文未使用 git clone 作爲安裝步驟；請以 README 中的 dsh plugin add 與本地 link: 爲準。

結尾¶

dsh-plugin-template 提供的是無業務的最小可安裝骨架：Cordis 掛接、React 空設置頁、雙語、構建產物與冒煙測試一併就緒，便於複製後專注業務邏輯。

• 目錄頁：https://www.skillhub.cn/plugins/longyi-0x0/dsh-plugin-template
• GitHub：https://github.com/longyi-0x0/dsh-plugin-template