DeepSeek Harness（dsh）外掛疑難排解：安裝錯誤、cordis.patch.yml 衝突與 Profile 設定無效修復指南（2026）
DeepSeek Harness（dsh）外掛安裝與設定常見問題排錯手冊：pnpm workspace allowlist 錯誤、dsh bundle 格式問題、cordis.patch.yml 衝突、Profile 設定無效、外掛裝了卻沒載入，逐項說明原因與修復指令。
最近更新: 2026-08-26
何時使用本指南
在「找到外掛」與「外掛正常運作」之間出問題時使用本頁：dsh plugin add 失敗、monorepo 裡奇怪的 pnpm-workspace allowlist 報錯、cordis.patch.yml 改了沒反應、Profile 載入了錯誤的外掛組合。每個小節都依同一結構展開——症狀、原因、修復指令。
還沒走到安裝步驟？先讀安全安裝外掛指南；不確定自己在改哪一層設定？先看設定教學。
動手之前先記住一條鐵律：每次修改設定後都要重新啟動 dsh。外掛樹在啟動時由 Cordis 容器組裝，「什麼都沒發生」的案例裡有一半只是改了設定忘了重新啟動。
一、安裝時提示找不到外掛（Plugin not found）
症狀：dsh plugin add dsh-some-tool 報解析錯誤，或安裝成功但外掛始終沒有出現。
原因：CLI 依精確套件名稱從 npm registry 解析。常見原因：套件名稱拼寫錯誤、少了 @scope/ 前綴、外掛只透過 GitHub 發行（npm 上沒有項目）、或 --profile <name> 與之後啟動的 Profile 不一致——項目加進了你從未啟用的 Profile。
修復步驟：
- 先用
npm view dsh-some-tool核對套件的確切名稱。外掛的詳情頁與倉庫 README 會給出可用的安裝指令——社群外掛的安裝方式由外掛自己維護。 - 外掛只在 GitHub 發行時，用原始碼位址安裝並鎖定分支：
dsh plugin add github:owner/repo#main。 - 讓參數與啟動方式一致：用
dsh plugin --profile web add <package>安裝的，就用dsh --profile web啟動，不要直接執行dsh。 - 本機開發時直接連結目錄：
dsh plugin add ./path/to/my-dsh-plugin。
二、安裝卡住或失敗：pnpm workspace allowlist
症狀：在 pnpm monorepo 中安裝外掛時卡住，或報 pnpm-workspace allowlist、module not found、ESM & CJS 解析錯誤——尤其是從 git 或本機建置安裝時。
原因：pnpm 嚴格限制依賴邊界。從 GitHub 安裝的外掛實際上進入了工作區，如果套件沒有在邊界內宣告，pnpm 不會連結它，執行時就無法解析外掛或其依賴。
修復步驟：
- 把套件宣告進邊界：在根目錄
package.json的 dependencies（或pnpm-workspace.yaml的允許清單/目錄）中加入該外掛，然後在工作區根目錄執行pnpm install。 - 重新安裝並重新啟動：
dsh plugin add <package>，再啟動dsh讓重建後的外掛樹生效。 - 有 npm 發行版時優先使用發行版：發行套件自帶依賴，天然避開工作區邊界問題。
- 確認執行環境：
node -v應輸出 20.0.0 及以上。
三、cordis.patch.yml 衝突（覆蓋順序問題）
症狀：兩個外掛功能重疊——兩個側邊欄、兩個 OCR 引擎、同一個服務的兩套實作——其中一個的設定被靜默忽略；dsh 可能提示 Profile patch collision / Override order issue。
原因：patch 是覆蓋層，疊加在 bundle 與 profile 之上，後寫的項目勝出。當兩個項目註冊同一服務或同一 UI 面板時，宣告順序決定結果。YAML 裡重複的鍵或縮排錯誤，也可能悄悄改寫項目。
修復步驟：
- 開啟你實際使用的檔案：
cat ~/.dsh/profiles/<name>/cordis.patch.yml，工作區內則是<專案根>/.dsh/cordis.patch.yml。 - 調整順序：把希望生效的外掛移到
plugins:列表末尾——後面的項目覆蓋前面的。 - 或保留兩者、解除衝突：把其中一個項目的
enabled設為false。 - 最乾淨的長期方案：把衝突外掛拆進不同 Profile，用
dsh --profile <name>分別啟動。 - 重新啟動前先驗證 YAML——一次縮排錯誤就會改變項目的含義：
yq eval . cordis.patch.yml。
四、dsh bundle 格式錯誤
症狀：dsh 能啟動，但外掛組合與文件描述完全不同；或從別處複製來的設定檔不斷報衝突、載入失敗。
原因：三個設定層各有分工：bundle 是隨 dsh 發行的官方外掛集合，profile 是你自訂的「bundle + 外掛」組合，patch 只針對單一外掛項目做外科手術式覆蓋。如果 cordis.patch.yml 把整套 bundle 重新宣告了一遍——幾十條外掛外加本應屬於 profile 層的設定——格式就混了，這些覆蓋項目開始與 bundle 自帶內容互相衝突。
修復步驟：
- 讓 patch 保持精簡——每個外掛一個項目，只有
enabled與options：
# ~/.dsh/profiles/default/cordis.patch.yml
plugins:
dsh-vision-toolkit:
enabled: true
options:
ocrEngine: 'default'
- 想一次啟用整套外掛？那是 profile 層的職責：在 profile 裡設定組合，而不是把每條外掛都貼進 patch。
- 刪掉重複項目、儲存並重新啟動
dsh。此時外掛的工具/面板應正常載入，不再印出衝突訊息。
五、Profile 設定無效
症狀：改了 cordis.patch.yml，重新啟動後沒有任何變化；或為某個 Profile 安裝的外掛無處可尋。
原因：三選一的經典失誤：改錯檔案（設定檔有兩處，且專案級覆蓋全域級）、啟動時用的 Profile 名稱與修改的目錄不一致、或根本沒重新啟動。
修復步驟：
- 先看兩處檔案是否都存在：
ls ~/.dsh/profiles/*/cordis.patch.yml 2>/dev/null，以及專案根目錄下ls .dsh/cordis.patch.yml 2>/dev/null。 - 記住優先權：兩者都存在時
<專案根>/.dsh/cordis.patch.yml覆蓋~/.dsh/profiles/<name>/cordis.patch.yml。 - 讓參數與目錄一致：改了
~/.dsh/profiles/web/cordis.patch.yml，就用dsh --profile web啟動——不是dsh，也不是dsh --profile headless。 - 重新啟動驗證：
dsh --profile web，檢查外掛的工具或面板是否出現。還是沒有？看下一節。
六、外掛裝上了卻載入不了（failed to register）
症狀：安裝成功、設定看起來沒問題，但啟動時 dsh 報 Plugin failed to register / Lifecycle timeout——或外掛無聲無息地沒載入。
原因：通常是執行環境太舊（Node.js 低於 20）、依賴缺失（git 安裝需要自己建置）、宣告順序與別的外掛衝突，或項目被留成了 enabled: false。還有一個相關的失敗模式是沙箱：dsh 預設 read-only 執行，需要讀寫磁碟或存取網路的外掛可能在載入時就被攔下，報 Permission denied / Sandbox security policy violation。
修復步驟：
- 檢查執行環境：
node -v——升級到 20.0.0 及以上（推薦 Node 22 LTS）。 - 原始碼安裝需要建置：進入外掛目錄執行
pnpm install && pnpm build，然後重新啟動。 - 乾淨重裝：
dsh plugin remove <package>，確認cordis.patch.yml中的項目，再dsh plugin add <package>。 - 確認項目處於啟用狀態：
dsh plugin add會寫入enabled: true；如果手改過 YAML，檢查它還在不在。 - 如果報錯與沙箱有關且外掛可信任，啟動時放行：
dsh --sandbox workspace-write（詳見安全沙箱指南）。 - 透過 dsh-market Web UI 安裝的？去 Settings → Plugin Market 看外掛狀態——後端會套用設定並熱載入，失敗狀態會顯示在那裡。