如何建立 DeepSeek Harness 外掛
九步截圖實測：從最小的 hello-world Context 函式到雙端 MCP Apps 外掛——契約、Schema 與安裝指令全部給出。
最近更新: 2026-09-14
DeepSeek Harness 裡的所有能力——從單一 hello 工具到完整的互動介面——都以外掛形式存在，而自己寫一個外掛的門檻比看起來低：一個接收 Context 的函式、幾個匯出、一個 Schema。這篇圖文跟著一次真實的開發過程，從空資料夾走到一個能在對話裡跑起來的 MCP Apps 外掛。
九步涵蓋完整路徑：外掛是什麼、最小契約、Host 與 Client 兩個執行環境、load–run–dispose 生命週期、真實儲存庫的目錄結構、宿主入口與 Config Schema，以及在你自己的 profile 裡安裝、宣告、驗證外掛的確切指令。
九步建立一個 DeepSeek Harness 外掛
- 2
從最小的可用外掛開始
教學裡的 hello 例子只需要三樣東西：可載入的模組入口（export const name = 'hello'）、接收 Context 的 apply(ctx) 函式並在其中註冊能力——這裡用 ctx.tools.add 新增一個回顯名稱的 hello 工具——以及只有外掛需要設定時才匯出的、用 Schema.object 建構的 Config。Harness 會驗證這個 Schema，並在管理介面裡渲染對應的欄位。其餘都是可選的。
整個檔案就是一個能跑的外掛：入口、apply 函式、可選的 Config Schema。在 1:00 觀看 - 3
選 Host、Client 還是兩者都要——生命週期是同一套
有兩個執行環境需要分清。Host 是執行 DeepSeek Harness 的後端程式，掌握網路連線和工具要用的金鑰；瀏覽器裡的 Harness Web UI 是 Client，負責元件和互動介面。hello 外掛只有 Host 入口——註冊一個工具，讓對話展示結果；帶介面的外掛則額外提供 Client 入口，宣告自己的 inject 和 apply。無論哪種，每個入口都在自己的執行環境裡執行 apply，解除安裝時 Context 會統一銷毀它註冊的一切。
Host 入口必備，Client 入口可選——兩者走同一個三階段生命週期。在 1:45 觀看 
RUN 就是你的 apply 函式幹活的時刻——把能力註冊到兩個執行環境都能看到的地方。在 1:20 觀看 - 4
研究一個已上線外掛的目錄結構
寫程式碼之前，先看一個已發布外掛是怎麼組織的。sugarforever/dsh-mcp-apps 儲存庫把原始碼、examples、tests、docs 和套件設定放在根目錄，src/ 下再分成 config、connection、protocol、rpc、tools、client。你不必逐行讀完——認準三個錨點（src/index.ts、src/config.ts、src/client/）就足以看懂任何 DSH 外掛。
已上線外掛把契約放在 index.ts、驗證放在 config.ts、瀏覽器端放在 client/。在 2:05 觀看 - 5
寫宿主入口：name、inject、Config、apply
打開 src/index.ts，宣告公開契約。export const name 標識外掛；export const inject 列出相依的服務——MCP Apps 外掛宣告了 ['tools', 'connection']；export const Config 把驗證交給 Harness。apply(ctx, config) 接收 Context 和驗證後的設定，而長連線、工具註冊這類持續資源都包進 ctx.effect，解除安裝時 Harness 會統一釋放。這幾行就是宿主外掛與框架之間必須遵守的介面。
宿主檔案先 import @deepseek-ai/cordis，再寫三個契約匯出，最後是 apply。在 2:34 觀看 
四個匯出就是全部公開契約——name、inject、Config、apply。在 2:55 觀看 - 6
給使用者一個能填的 Config Schema
在 src/config.ts 裡，教學外掛用一個 Schema union 描述兩種傳輸分支：stdio（command、args、env）和 streamable-http（必填 url、可選 headers），外加共用欄位 serverName（必填）、toolCallTimeoutMs（預設 60000）和 failOnStartupError（預設 false）。開發者實作介面和 Schema，使用者只需要填值——儲存庫裡的 examples/streamable-http.cordis.yml 就是那份填空實例。
一個 Schema union 涵蓋兩種傳輸；必填與預設欄位直接驅動管理介面。在 3:05 觀看 
照這樣附一個 examples 檔案——它就是使用者照抄的填空實例。在 3:35 觀看 - 7
把外掛裝進 web profile
複製外掛儲存庫，把 DSH_HOME 指向要擴充的 Harness 主目錄，再把套件加進 web profile。示範執行的是 npx @deepseek-ai/dsh plugin --profile web add <路徑>，它把本機資料夾連結進 profile，並輸出 added 1 package 確認。裝到別的 profile 了？對同一個 profile 再跑一次 add 即可。
$git clone https://github.com/sugarforever/dsh-mcp-apps.git$cd dsh-mcp-apps$export DSH_HOME=/tmp/dsh-video-home$npx @deepseek-ai/dsh plugin --profile web add /path/to/dsh-mcp-apps
從參考儲存庫起步——先複製，再裝相依套件。在 5:37 觀看 
add 指令把外掛連結進 web profile——此時還不需要別的設定。在 5:40 觀看 - 8
在 cordis.patch.yaml 裡宣告實例
只裝套件還不夠——還需要一條 patch 條目告訴 Harness 去實例化它。在 profile 的 cordis.patch.yaml（本例是 $DSH_HOME/profiles/web/cordis.patch.yaml）裡插入一條：唯一的 id、外掛的套件名稱（'@sugarforever/dsh-mcp-apps'）和它的 config：serverName、transport: streamable-http、MCP 伺服器 url 和 failOnStartupError。Harness 啟動時讀取這份 patch，自動載入外掛。
這條 patch 條目才是讓 Harness 在啟動時實例化外掛的關鍵。在 5:49 觀看
建立 DeepSeek Harness 外掛：常見問題
開發者寫第一個外掛時真正會問的問題。
一句話說明白：DeepSeek Harness 外掛是什麼？
外掛就是一個接收 Cordis Context 的函式：它宣告自己相依哪些服務，向 Context 註冊新能力——模型工具、服務或介面——並依靠框架在外掛解除安裝時統一釋放它註冊的一切。
一個 DSH 外掛最少需要什麼？
三樣：可載入的模組入口、接收 Context 的 apply(ctx) 函式，以及 apply 裡註冊的至少一種能力——教學的 hello 外掛用 ctx.tools.add 新增了一個工具。只有外掛需要設定時才匯出 Config Schema，其餘都是可選的。
建立 DeepSeek Harness 外掛必須用 TypeScript 嗎？
教學的參考外掛是 TypeScript 寫的——export const name = 'mcp-apps'、inject 陣列、Schema.object(...) 都是 TypeScript 慣用法，直接複製那個儲存庫起步最快。契約本身只是一組模組匯出，概念可以遷移，但本頁所有範例都是 TypeScript。
Harness 啟動時是怎麼載入我的外掛的？
三步：把 DSH_HOME 指向你的 Harness 主目錄；用 npx @deepseek-ai/dsh plugin --profile web add <路徑> 把套件裝進某個 profile；在該 profile 的 cordis.patch.yaml 裡寫一條 insert 條目，填外掛名稱和設定。Harness 啟動時讀取 patch 並自動載入外掛——Harness 側不用改任何程式碼。
DSH 外掛可以包裝遠端 MCP 伺服器嗎？
可以——案例就是這麼做的。宿主入口連線 stdio 或 Streamable HTTP 的 MCP 伺服器，然後在 ctx.effect 裡把遠端工具註冊成 Harness 模型工具。Config Schema 暴露兩種傳輸分支，使用者只需在 cordis.patch.yaml 裡填 serverName、transport 和 url。
外掛被移除時，連線由誰清理？
框架來清理——前提是你透過 Context 註冊。把持續連線和工具註冊包進 ctx.effect，DISPOSE 階段會在解除安裝時統一釋放。這也是教學從不用模組層級全域變數存連線的原因。
相關指南
外掛生態的其餘部分，從概念到線上目錄。
DeepSeek Harness 外掛開發
概念參考：能力層、契約，以及外掛如何擴充 harness。
閱讀教學什麼是 DeepSeek Harness 外掛？
心智模型：外掛能擴充什麼，它和 skill 有何不同。
閱讀教學DeepSeek Harness 外掛安裝教學
一步步找到社群外掛，從 npm 或 GitHub 安裝。
閱讀教學DeepSeek Harness Skill 安裝教學
另一種擴充形態：幾分鐘裝好並驗證 skill。
閱讀教學瀏覽 DeepSeek Harness 外掛目錄
動手之前，先看看現有外掛都能做什麼。
閱讀教學零程式碼路線：對話做出一個外掛
一句話想法、一份共創規格、創造模式自動開發——不出對話做出能用的面板。
閱讀教學來源與署名
截圖均來自這段公開錄影，每張圖都連回來源影片的對應時間點；上文分步文字是我們自行整理的內容。