DeepSeek Harness plugins directoryDSH Pluginsdsh 外掛市集
返回教學

DeepSeek Harness 外掛疑難排解：安裝錯誤、Patch 衝突、版本回滾與 Profile 失效（2026）

DeepSeek Harness（dsh）外掛問題逐步排解：pnpm workspace 白名單錯誤、cordis.patch.yml 覆蓋順序、Profile 不生效、外掛裝了不載入、升級後變慢——以及升級把外掛弄壞時怎麼鎖版本與回滾。

最近更新: 2026-10-09

何時使用本指南

在「找到外掛」與「外掛正常運作」之間出問題時使用本頁：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。

修復步驟：

  1. 先用 npm view dsh-some-tool 核對套件的確切名稱。外掛的詳情頁與倉庫 README 會給出可用的安裝指令——社群外掛的安裝方式由外掛自己維護。
  2. 外掛只在 GitHub 發行時，用原始碼位址安裝並鎖定分支：dsh plugin add github:owner/repo#main。
  3. 讓參數與啟動方式一致：用 dsh plugin --profile web add <package> 安裝的，就用 dsh --profile web 啟動，不要直接執行 dsh。
  4. 本機開發時直接連結目錄：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 不會連結它，執行時就無法解析外掛或其依賴。

修復步驟：

  1. 把套件宣告進邊界：在根目錄 package.json 的 dependencies（或 pnpm-workspace.yaml 的允許清單/目錄）中加入該外掛，然後在工作區根目錄執行 pnpm install。
  2. 重新安裝並重新啟動：dsh plugin add <package>，再啟動 dsh 讓重建後的外掛樹生效。
  3. 有 npm 發行版時優先使用發行版：發行套件自帶依賴，天然避開工作區邊界問題。
  4. 確認執行環境：node -v 應輸出 20.0.0 及以上。

還是卡住？2026 年「安裝卡住」的兩個新收據（#9178、#9261）

官方討論區新增的兩種形態，正對應「dsh 安裝卡住」這個搜尋：

  1. Windows 上 dsh plugin add 掛住不結束（#9261）。 指令停著不返回，profile 的 bundles 遲遲不 reconcile。重跑 add 指令——瞬時網路中斷是最常見誘因——並檢查到 registry 的網路路徑，直連慢就換鏡像。
  2. 外掛悄悄裝了舊版本，隨後被判不相容（#9178）。 pnpm 11 起 minimumReleaseAge 預設 24 小時：今天發布的版本對解析器不可見，安裝靜默降級到舊版本——舊版本又可能過不了相容檢查。裝明確 package@version，或確要追新就調整 minimumReleaseAge。

三、cordis.patch.yml 衝突（覆蓋順序問題）

症狀：兩個外掛功能重疊——兩個側邊欄、兩個 OCR 引擎、同一個服務的兩套實作——其中一個的設定被靜默忽略；dsh 可能提示 Profile patch collision / Override order issue。

原因：patch 是覆蓋層，疊加在 bundle 與 profile 之上，後寫的項目勝出。當兩個項目註冊同一服務或同一 UI 面板時，宣告順序決定結果。YAML 裡重複的鍵或縮排錯誤，也可能悄悄改寫項目。

修復步驟：

  1. 開啟你實際使用的檔案：cat ~/.dsh/profiles/<name>/cordis.patch.yml，工作區內則是 <專案根>/.dsh/cordis.patch.yml。
  2. 調整順序：把希望生效的外掛移到 plugins: 列表末尾——後面的項目覆蓋前面的。
  3. 或保留兩者、解除衝突：把其中一個項目的 enabled 設為 false。
  4. 最乾淨的長期方案：把衝突外掛拆進不同 Profile，用 dsh --profile <name> 分別啟動。
  5. 重新啟動前先驗證 YAML——一次縮排錯誤就會改變項目的含義：yq eval . cordis.patch.yml。

四、dsh bundle 格式錯誤

症狀：dsh 能啟動，但外掛組合與文件描述完全不同；或從別處複製來的設定檔不斷報衝突、載入失敗。

原因：三個設定層各有分工：bundle 是隨 dsh 發行的官方外掛集合，profile 是你自訂的「bundle + 外掛」組合，patch 只針對單一外掛項目做外科手術式覆蓋。如果 cordis.patch.yml 把整套 bundle 重新宣告了一遍——幾十條外掛外加本應屬於 profile 層的設定——格式就混了，這些覆蓋項目開始與 bundle 自帶內容互相衝突。

修復步驟：

  1. 讓 patch 保持精簡——每個外掛一個項目，只有 enabled 與 options：
# ~/.dsh/profiles/default/cordis.patch.yml
plugins:
  dsh-vision-toolkit:
    enabled: true
    options:
      ocrEngine: 'default'
  1. 想一次啟用整套外掛？那是 profile 層的職責：在 profile 裡設定組合，而不是把每條外掛都貼進 patch。
  2. 刪掉重複項目、儲存並重新啟動 dsh。此時外掛的工具/面板應正常載入，不再印出衝突訊息。

五、Profile 設定無效

症狀：改了 cordis.patch.yml，重新啟動後沒有任何變化；或為某個 Profile 安裝的外掛無處可尋。

原因：三選一的經典失誤：改錯檔案（設定檔有兩處，且專案級覆蓋全域級）、啟動時用的 Profile 名稱與修改的目錄不一致、或根本沒重新啟動。

修復步驟：

  1. 先看兩處檔案是否都存在：ls ~/.dsh/profiles/*/cordis.patch.yml 2>/dev/null，以及專案根目錄下 ls .dsh/cordis.patch.yml 2>/dev/null。
  2. 記住優先權：兩者都存在時 <專案根>/.dsh/cordis.patch.yml 覆蓋 ~/.dsh/profiles/<name>/cordis.patch.yml。
  3. 讓參數與目錄一致：改了 ~/.dsh/profiles/web/cordis.patch.yml，就用 dsh --profile web 啟動——不是 dsh，也不是 dsh --profile headless。
  4. 重新啟動驗證：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。

修復步驟：

  1. 檢查執行環境：node -v——升級到 20.0.0 及以上（推薦 Node 22 LTS）。
  2. 原始碼安裝需要建置：進入外掛目錄執行 pnpm install && pnpm build，然後重新啟動。
  3. 乾淨重裝：dsh plugin remove <package>，確認 cordis.patch.yml 中的項目，再 dsh plugin add <package>。
  4. 確認項目處於啟用狀態：dsh plugin add 會寫入 enabled: true；如果手改過 YAML，檢查它還在不在。
  5. 如果報錯與沙箱有關且外掛可信任，啟動時放行：dsh --sandbox workspace-write（詳見安全沙箱指南）。
  6. 透過 dsh-market Web UI 安裝的？去 Settings → Plugin Market 看外掛狀態——後端會套用設定並熱載入，失敗狀態會顯示在那裡。

七、升級後變慢 / 效能回退

症狀：升級 dsh 之後，開啟舊工作階段、恢復工作階段或持續對話時明顯變卡，工作階段越長越明顯；或與舊版相比，整體感覺效能回退。

原因：多半不是你裝壞了外掛。長工作階段卡頓是舊版本的已知問題——早期版本的工作階段資料儲存格式偏重，訊息一多，開啟、恢復與每一輪對話都要付出額外的記憶體與解析成本。

修復步驟：

  1. 先升級到目前的穩定線再下結論：長工作階段卡頓已在 v0.1.5 修復（最佳化儲存格式、降低記憶體佔用），且截至 2026-09-29，npm latest 為 0.2.0-rc.2。執行 npm install -g @deepseek-ai/dsh@latest，重新啟動後用同一段長工作階段對比驗證。多數「升級後變慢」其實是舊版的已知問題，升級即解。實驗通道已與 latest 持平——next 同樣指向 0.2.0-rc.2，alpha 指向 0.1.7-alpha.2——但排查效能問題不該從 alpha 通道起步。
  2. 升級後仍慢？超長上下文情境改用 Minimal profile 啟動（見 GitHub 討論 #5485）：dsh --profile minimal 只載入持久終端機等基礎工具，減少隨工作階段注入的內容——日常用 Standard，超長工作階段用 Minimal。
  3. 仍有問題：收集日誌回報——附上 dsh --version、啟動指令、工作階段規模（訊息數/檔案大小）、主控台錯誤與你的對比結果，到官方儲存庫開 issue。資料越齊全，定位越快。

八、升級後外掛掛了（鎖版本 / 回滾）

症狀：dsh 自動更新，或你執行了 npm install -g @deepseek-ai/dsh@latest，昨天還能用的外掛今天載入失敗、面板消失、跳出註冊錯誤——有時只在哪一個 profile 下重現。

原因：升級會壞在兩件事上。其一是 harness 換了對外掛的契約：v0.1.6-alpha.2 的官方發布說明把「外掛相依解析」改為執行期解析，並新增執行期卸載，同時點名要求外掛開發者檢視載入與卸載邏輯——舊契約下正常的外掛，在作者適配前就可能失敗。其二是你自己的設定錯位：條目留在你不再啟動的 profile 裡，或重排後兩條相互覆寫。版本節奏也是現實變數：0.1.6 線兩天連發兩個 alpha（09-15、09-17），穩定線在 0.1.5-rc.3 停到 09-28 的 0.1.7-rc.2 翻轉——同日的 0.2.0-rc.1 又重做了外掛管理介面，所以 0.2.0 預覽版帶著真實的相容性成本（見下一節）。

修復步驟：

  1. 先定位是 dsh 還是外掛：用精簡設定檔啟動 dsh --profile minimal，它只載入持久終端機等基礎工具。若問題在這裡消失，問題在外掛。動手改任何東西之前，先記下 dsh --version 與完整啟動指令（含 --profile <name>）。
  2. 讀啟動診斷：自 0.1.6-alpha.2（alpha 通道）起，啟動失敗會分類顯示錯誤與等待中的服務，並把完整診斷寫入日誌檔案——先讀它，再決定卸什麼。
  3. 整體不穩就鎖 harness：npm install -g @deepseek-ai/dsh@0.1.5-rc.2——寫死版本號，絕對不要用 @latest。這就是回滾：退回去的目標就是上次可用的穩定線版本。
  4. 只有單一外掛壞就鎖外掛：dsh plugin remove <package>，再用標籤安裝 dsh plugin add github:owner/repo#v1.2.3（#ref 位置可寫 tag 或分支）。若該外掛沒有可用標籤，別刪設定，把它在 cordis.patch.yml 的條目設為 enabled: false 並重新啟動，修好再打開。
  5. 動手前先備份：cp ~/.dsh/profiles/<name>/cordis.patch.yml ~/dsh-profile-backup.yml。一次回滾順帶丟掉整套外掛設定，比原始問題更糟。
  6. 檢查多實例衝突：如果 dsh 提示工作階段被其他 DSH 實例佔用，官方做法是結束那個實例後重試——伺服器常駐實例與本機實例共用同一個 profile 時很常見（見 伺服器部署與多人共用）。
  7. 改完必須重新啟動驗證。外掛樹在啟動時組裝，沒重新啟動之前，上面每一步都還算不上驗證過。

如果你是刻意停在 alpha 線，就要接受這件事：發布說明把適配責任交給了外掛作者，生態是一支一支外掛在追。社群外掛對你構成關鍵路徑時，請留在 latest，等 alpha 線沉澱。

九、Windows 沙箱權限：0xC0000142 與存取被拒

症狀：Windows 上沙箱指令全部回報 0xC0000142 (STATUS_DLL_INIT_FAILED)，或受限模式下子程序輸出無法擷取（Access is denied），或桌面端啟動沙箱 PTY 直接失敗，或供給階段直接出現 SetNamedSecurityInfoW failed (Win32 5)——回報多集中在升級 dsh 之後，而且整個 0.2.0-rc 系列期間，討論區的新帖仍在持續增加。

原因：內建 Windows 沙箱會在啟動時為目錄設定 ACL，官方討論區已記錄的故障形態可以分成三族。0xC0000142 族：非系統管理員啟動時 workspace-write 供給失敗並留下無法自癒的損壞 ACL（#8115）；桌面端連 pwsh/cmd echo 這類無害指令都回報 0xC0000142（#8208、#8295）；0.2.0-rc.1 在 Electron 宿主下沙箱子程序一個都起不來（#8193）；加上更早記錄的桌面端全滅（#8142、#8130）、CLI/Web（npx）形態的 stdio 擷取確定性失敗 + 間歇 0xC0000142（#8143、#8141）、minimal 預設 PTY 結束代碼 127（#8158），以及 10 月初的一波高峰——24 小時內連出四份新報告：Win10 LTSC 啟動（#8877）、無主控台啟動（#8878）、confined pwsh 內 DLL 初始化失敗（#8890）、workspace-write 供給在 pwsh 中失敗（#8897）。WRITE_OWNER 族：工作區放在資料碟（例如 D:\...）時，磁碟代號預設繼承的 ACL 只隱含給 WRITE_DAC，而 grantWrite 要以 WRITE_DAC | WRITE_OWNER 打開工作區根目錄，於是回報 Win32 5 失敗——此後該工作階段內所有經沙箱的指令全部不可用，連唯讀指令也一樣，而檔案讀寫工具不受影響（#8232、#8272、#8275、#8282，以及 10 月新增的 WRITE_OWNER Win32 5 報告 #8886）。回歸族：0.1.5 → 0.1.7-rc.2 讓受限子程序掉進 ConstrainedLanguage、所有授權寫入被拒（#8219）；workspace-write 還順帶弄壞了 git for Windows——MSYS 二進位檔起不來、schannel 碰不到憑證庫（#8209）。而第四波在 10 月 6–7 日兩天內就到齊：打包版桌面端所有 workspace-write 指令一律以 3221225794/0xC0000142 結束（#9031）、confined pwsh 的每一條指令都死於同一錯誤（#8991）、Win11 的 pwsh 工具呼叫同樣失敗（#8990），外加 #8971 給出的有用對照——同一台機器跑 0.1.5-rc.2 的 workspace-write 沙箱一切正常。

修復步驟：

  1. 先定性再動手：記下故障形態（每條指令都失敗還是偶發、桌面端還是 npx、系統碟還是資料碟），蒐集 dsh --version 與啟動診斷日誌。
  2. 升級到 0.2.0-rc.2 或更新版本，跑官方一鍵診斷修復：rc.2 發布說明把 Windows 沙箱權限指令稿改為「經授權後一次完成診斷與修復，保留修改前備份與還原指令」。在工作階段裡讓 agent 診斷沙箱權限，先跑它再考慮手動處理（rc.1 時代的診斷與修復是分開的兩步，#8272 記錄了當時的痛點）。
  3. 針對 WRITE_OWNER 形態：把工作區搬回使用者目錄，或替你的帳戶在資料碟根目錄上顯式補 WRITE_OWNER 授權——升級後的一鍵修復做的正是這件事，且帶備份。退而求其次，先用系統管理員終端機啟動一次讓 provisioning 乾淨跑完，再回一般（非系統管理員）終端機複測。
  4. 若損壞的 ACL 仍在：刪掉上次失敗 provisioning 留下的沙箱 profile 目錄，讓下次啟動從頭重建（動手前先備份 cordis.patch.yml——見第八節）。
  5. 仍然失敗：帶著診斷檔案到上面的討論帖串補充你的回報——正是這些細節在協助區分不同故障形態。

十、網路與認證錯誤：Proxy 設定與「API key is invalid」

症狀：公司 Proxy 環境下請求逾時或卡住，但瀏覽器一切正常；或工作階段直接回 API key is invalid（401）、Insufficient Balance（402）、403 類權限錯誤。

原因：dsh 走的是你所在環境的網路：npm 認的 Proxy 而 dsh 程序不認（或反過來），表現就是卡住和逾時，而不是乾淨的錯誤訊息。至於金鑰無效，多半是低階原因——貼上時帶了空白字元、金鑰綁錯服務商、填進了錯誤 profile 的設定裡，以及著名的「登入密碼被自動填進 API Key 欄位」（0.1.7-rc.2 專門緩解過這個）。

修復步驟：

  1. 先處理 Proxy：給啟動 dsh 的程序設定標準變數 HTTP_PROXY / HTTPS_PROXY / NO_PROXY，重新啟動 dsh 再試。外掛下載慢是另一條路徑，用安裝指南的映像來源一節解決。
  2. 想要圖形介面？kanneiren/dsh-network-settings（★107）能診斷 dsh 程序的真實網路路徑、DNS 與首個失敗點；kriskite/dsh-network-proxy（★8）在設定頁裡管理系統/手動/直連三種 Proxy 模式。
  3. 遇到 API key is invalid：去服務商後台重新產生金鑰，乾淨貼上（不帶空格換行），確認它屬於設定裡實際選中的服務商。
  4. 重試前先讀狀態碼：401 是金鑰本身錯了（換金鑰），402 是帳戶沒餘額了（儲值——見餘額指南），403 是金鑰有效但無權使用這個模型或地區（換模型或帳號）。

十一、dsh: command not found（找不到指令）

症狀：終端機回報 dsh: command not found（指令不存在/找不到）；或者桌面端在 PATH 上找不到 dsh 啟動器（#8268）；或者昨天還能用的啟動指令升級後突然「失效」（#8242）。

原因：CLI 裝在 npm 全域目錄裡，所以問題幾乎總是三種之一：全域目錄不在 PATH 上（用 nvm/fnm/volta 等版本管理器或自訂 prefix 時最常見）、安裝根本沒完成，或者從圖形介面啟動的桌面應用程式繼承不到你 shell 裡的 PATH 追加項目。web 變體——敲 dsh web 只得到 zsh: command not found: dsh——是同一個毛病從 Web UI 門口看過去的樣子：CLI 壓根沒啟動，輪不到 Web 部分出錯。

修復步驟：

  1. 先定位可執行檔：npm prefix -g 會印出全域 prefix，dsh 可執行檔就在它底下的 bin 目錄裡。拿這個目錄和 echo $PATH 對一下。
  2. 重新安裝並開一個新終端機（新 shell 會重新讀 PATH）：npm install -g @deepseek-ai/dsh。
  3. macOS / Windows 桌面端：用 0.2.0-rc.2 選單列新增的 「Manage dsh command」——官方代你安裝和管理 dsh 指令（含外掛），不需要另裝 Node.js 或 pnpm；從 GUI 啟動、看不到 shell 環境的場景也一併解決。
  4. 應急方案：npx @deepseek-ai/dsh web 不做全域安裝也能跑目前版本。

十二、桌面端所有指令零輸出、回報 0xC0000142（已解決案例）

症狀：桌面端裡每條指令都回傳 0xC0000142，而且完全沒有輸出——不印錯誤文字，什麼都沒有。同一台機器上，把同樣的指令放進普通終端機跑就一切正常。把這個形態釘死的回報（#8395）已標記為已解決。

原因：0xC0000142 是 STATUS_DLL_INIT_FAILED——沙箱子程序在建立階段就死了，根本輪不到輸出任何東西。danger-full-access 模式不套受限權杖，同一條指令自然能跑——所以「命令列裡正常」正是這個形態的特徵，而不是矛盾。#8336 的受控實驗把矩陣釘死了：受限權杖（WRITE_RESTRICTED + Low 完整性）只要與任一主控台隔離旗標（CREATE_NO_WINDOW / CREATE_NEW_CONSOLE）同時出現，子程序必死；單獨任何一個都還能活。已解決案例裡的變數是安裝位置——桌面端被裝到了自選目錄，而不是預設位置。

修復步驟：

  1. 先對形態：CLI 正常、桌面端靜默死 → 就是本節。動手前記下 dsh --version。
  2. 已驗證的解法（#8395）：解除安裝桌面端，裝回預設安裝位置——安裝時不要自選目錄。
  3. 被卡住時的官方繞道方案：把 DSH_HOME 指到你的 harness 主目錄，再用 ELECTRON_RUN_AS_NODE=1 啟動同一入口——這是 #8395 裡記錄的官方臨時辦法。
  4. 驗證：在 workspace-write 下跑一條無害指令，輸出應該回得來。還是死？回第九節跑一鍵修復。

十三、workspace-write 授權總不生效：ACL 三缺陷（以及 ERROR_NONE_MAPPED 1332）

症狀：workspace-write 已授權，但往工作區子目錄寫檔照樣被拒；桌面端對同一個工作區反覆失敗，直到重啟才好；標準（非系統管理員）使用者的工作區放在非系統碟上，grantWrite 報 Win32 5；想手動清理 ACL 時，icacls /remove 回你一個 ERROR_NONE_MAPPED (1332)。

原因：討論 #8409 記錄了 Windows ACL 沙箱的三個獨立授權缺陷。其一，受保護 DACL 之下的子目錄永遠拿不到授權，所以根目錄授權成功後，子目錄寫入照樣被拒。其二，桌面端對根目錄授權只評估一次並快取結果、之後不重新檢查——一次失敗的評估會一直失敗下去，重啟桌面端會重新評估、自癒。其三，標準使用者在非系統碟上對碟根缺少 WRITE_OWNER，grantWrite 因此報 Win32 5——即第九節的 WRITE_OWNER 族。1332 則是另一回事：能力 SID（capability SID）沒有映射到任何帳戶，icacls 無法按名字刪除它——這個錯誤的意思是「沒有可映射的物件」，不是「你的 ACL 損壞了」。

修復步驟：

  1. 先跑官方一鍵修復（第九節第 2 步）——這是受支援的路徑，而且自帶備份。
  2. 桌面端對明明該工作的區反覆失敗？重啟一次桌面端，讓快取的根授權重新評估——#8409 記錄的自癒路徑。
  3. 標準使用者 + 資料碟：把工作區搬回使用者目錄下（或者給你的帳戶在碟根補 WRITE_OWNER——一鍵修復自動做的就是這件事）。
  4. 別跟 icacls 的 ERROR_NONE_MAPPED 1332 太過不去：未映射的能力 SID 無法按名字刪除，把 ACL 交給官方修復腳本處理——手動剝離可能把沙箱 profile 弄得比缺陷本身更糟。
  5. 驗證：讓 agent 在工作區的子目錄裡建立一個檔案（缺陷一發生在根目錄之下），然後重啟一次桌面端再複測。

十四、dsh 直接起不來：Smart App Control 與防毒軟體 TLS 攔截

症狀：兩種「看似 dsh 出錯、其實不是」的主機層級攔截。Windows 11 開啟 Smart App Control 的機器上 dsh 無法啟動（#8377）；桌面端（0.2.0-rc.2）裝了某些防毒軟體後，宿主程序所有 HTTPS 請求全部失敗，介面上只有一個通用錯誤——登入永遠完不成（#8448）。

原因：Smart App Control 會攔截未簽名的原生模組，而 dsh 剛好帶了一些——啟動在我們自己的任何日誌之前就失敗了；事件檢視器的 CodeIntegrity 記錄裡會留下 3077/3033 事件作為憑證。防毒軟體這種形態是 TLS 換證：卡巴斯基類的「加密連線掃描」攔截 HTTPS 並用防毒軟體自己的憑證重新簽署，宿主程序不認這條憑證鏈，所有 HTTPS 流量死在一個通用錯誤背後。

修復步驟：

  1. Smart App Control：先去事件檢視器確認 CodeIntegrity 3077/3033——這是該形態的指紋。然後關閉 Smart App Control，啟動即恢復（#8377）。SAC 沒有按應用程式放行的名單，沒辦法單獨給 dsh 開白。
  2. 防毒軟體 TLS：把 dsh 相關網域加入防毒軟體的排除名單，或關閉「加密連線掃描」類功能——任一操作都能恢復宿主的 HTTPS（#8448）。
  3. 驗證：改完後啟動一次（SAC）或登入一次（防毒軟體）。還是通用錯誤？收集宿主日誌和 dsh --version，先和第十節的 Proxy 形態對照一遍再回報。

十五、Web UI 提示 authentication required（或連接埠被佔用）

症狀：dsh web（或 npx @deepseek-ai/dsh web）啟動了，頁面卻報認證錯誤（authentication required）；或者連接埠被佔用；或者敲 dsh web 只得到 zsh: command not found: dsh。搜尋引擎把這三句話當同一個問題——它們有三個不同的答案。

原因：Web UI 的存取網址由指令自己印出，其中帶著本次啟動的上下文——官方文件原話是「指令會印出它的 URL」。所以徒手敲裸位址 127.0.0.1:3080 可能撞上認證關卡，而不是控制台。連接埠被佔表示另一個 dsh 執行個體（或殘留程序）已經佔著 3080——即第八節的多重執行個體衝突。command not found 則是第十一節的 PATH 問題，和 Web UI 無關。而且這道門是內建設計：討論 #5936（標題就是 dsh web authentication required）請求把強制 token 認證做成可選——至今沒有落地，所以內網部署撞上的也是同一道牆。

修復步驟：

  1. 重新開啟 dsh web 印出的那個完整 URL——或者乾脆重跑一次指令讓它自己開——不要手敲裸位址。
  2. 從 SSH 啟動的只印主機 URL 是預期行為；去持有連接埠轉發的機器上的瀏覽器裡開啟它。
  3. 連接埠被佔：結束佔用工作階段的另一個執行個體（第八節的多重執行個體處理），或者換個連接埠啟動：dsh --profile web --port 8080。
  4. command not found：先把安裝修好（第十一節——npm 全域路徑，或桌面端的「Manage dsh command」）。
  5. 真心要把控制台暴露到回環之外（反向代理、共用內網伺服器）？token 關卡照樣在——它不可選。社群路線是 hxy91819/dsh-auth（★6，2026-10-03 經 GitHub API 複核）：用受管的 Caddy forward_auth 邊車加 Argon2id 管理員登入，dsh 本體保持只聽回環（展示帖是 #3231）。能用但早期：要求 Linux x64/ARM64 + systemd + Node 24.7+，star 數這個量級代表使用者基數還小——放到公開 URL 前面之前，先讀它的 README。
  6. 繼續深入：Web UI 圖文詳解逐格講過整個介面；遠端與手機存取合集收了 dsh-pocket、dsh-web 等手機/遠端用戶端；遠端存取指南講怎麼從外部網路穿透回來。
  7. 驗證：印出來的 URL 能開啟控制台，選好工作區後輸入框可用。

十六、API key is invalid（401）——鑰匙不一定真的是問題

症狀：工作階段或任務直接死於 API key is invalid 這個原樣報錯（通常帶 401），或 403 一類的權限錯誤。搜到這裡的人敲的是完整錯誤片語——而在已記錄的案例裡，鑰匙有時是好的：同一把 key 在一個介面能用、換個介面就被拒，或者 key 明明沒問題卻一直報錯。

原因：三種常見低級問題覆蓋大多數命中：key 貼上時帶了首尾空白或換行；key 屬於另一個 provider，與 Settings → Models 裡實際選中的不一致；或者 key 存進了另一個 profile 的設定，與你啟動的 profile 不同。再往外，討論 #5794 記錄了兩例「介面不一致」形態——Web UI 與 headless 執行讀取的並不是同一份憑證，一邊能用、另一邊被拒。還有兩份報告（#3073、#3222）顯示 provider 轉接層把非認證失敗也包裝成 API key is invalid 拋出——所以單憑報錯文字，不能斷定 key 壞了。

修復步驟：

  1. 重試之前先讀狀態碼（第十節的分診口徑）：401 = key 本身被拒，修 key；402 = 帳戶餘額不足，儲值；403 = key 有效但沒有該模型/地區的權限，換模型或換帳號。
  2. 去 provider 重新產生 key，乾淨貼上（不帶空白/換行），並確認它屬於 Settings → Models 裡實際選中的那個 provider。
  3. 介面不一致（#5794）：如果 Web UI 能用而 dsh --profile headless 失敗（或反過來），把 key 放到失敗那一側讀取的位置——headless 執行讀 DEEPSEEK_API_KEY 環境變數或儲存庫根 .env——然後重跑同一條指令。
  4. key 確認無誤、報錯卻跨介面持續？按「疑似誤分類」處理：抓全完整報錯輸出加 dsh --version，先對照 #3073/#3222，再決定要不要再次輪替憑證。
  5. 掛著代理伺服器？第十節的代理形態產生的是卡住和逾時，不是乾淨的 401——先在那裡排除，再怪 key。
  6. 在平台誤刪了 key，dsh 卻設不進新 key？這是在案記錄的缺口（#8988，同先前被關閉的 #7625）：桌面端與 Web UI 目前對已存憑證沒有「更新」或「刪除重設」的入口。過渡方案：headless 執行可以從 DEEPSEEK_API_KEY 環境變數讀新 key（即上面第 3 步的路子）；Web/桌面介面暫時沒有產品內重設——去 #8988 補一份你的案例並關注討論串。品牌形搜尋 deepseek harness api key is invalid 落到的就是這一節。

十七、Output token limit reached——兩道天花板，兩套修法

症狀：回答中途停下，報輸出 token 上限錯誤，或長回合被截斷——大家搜尋的原句是 output token limit reached（未解決討論：#1166、#5970）。帶品牌前綴的搜尋形——deepseek harness token limit、deepseek harness output token limit——落到的也是同一處。一個相關但不同的失敗：壓縮過後立刻報 CONTEXT_WINDOW_EXCEEDED。

原因：兩道天花板經常被混為一談。輸出上限：每個模型列都帶一個 Max output tokens 值（自訂模型列的預留位置是 32K）——單則回覆跑過它就被截斷。上下文上限：整個工作階段耗盡視窗，本應由壓縮在到達之前摺疊歷史——但 #8498 記錄了壓縮空轉、隨後把工作階段誤判為 CONTEXT_WINDOW_EXCEEDED，#8494 記錄了可用餘額在大 headroom 值之後塌縮。所以你看到的「上限已到」，可能是壓縮機制失靈，而不是工作階段真的太大。

修復步驟：

  1. 限的是回覆，不是工作階段：在 Settings → Models 裡設定模型列的 Max output tokens（自訂模型列直接暴露這個欄位；預留 256K/32K；留空則繼承 provider 預設）——愛截斷長回答的模型就把它調大。
  2. 工作階段確實大到失控就拆分：開新工作階段、帶一份摘要過去——上下文壓縮指南講過 dsh 怎麼摺疊歷史、三個壓縮觸發點是什麼。
  3. 壓縮剛跑完（或正在跑）就報 CONTEXT_WINDOW_EXCEEDED？這就是 #8498 形態：記下 dsh --version 和工作階段大小，重啟後重試一次，然後把回報連同診斷資訊貼進討論區。
  4. 小任務也反覆在回答中途被切——指向 provider 而非 dsh：先去 provider 自己的用量頁查你方案的長度/頻率上限，再動 dsh 的任何設定。
  5. 仍然重現：帶上 dsh --version、啟動指令和完整報錯，進討論串（#1166、#5970）——這個形態正在那裡被逐例區分。

十八、記憶體不足 OOM——被殺的是行程，不是工作階段

症狀：Linux 上跑 dsh，行程中途直接消失，終端機只剩一句 Killed（或結束代碼 137）；dsh web 跑一段時間後被系統殺掉，日誌裡能找到 OOM（Out of Memory）字樣。大家搜尋的原句是 dsh oom——先提醒一句：搜尋結果裡鋪天蓋地的 DSH 醫療內容（Disproportionate Share Hospital，美國醫療保險術語）與本工具無關，真正的同類案例在 GitHub 討論區。

原因：OOM 是作業系統層面的記憶體耗盡——dsh 行程（或它所在的容器/cgroup）申請的記憶體超過限額，核心直接殺行程保命。它和第十七節的「上限」是兩回事：上下文視窗耗盡回報的是 CONTEXT_WINDOW_EXCEEDED 這類模型側錯誤，工作階段還在；OOM 則是整個行程沒了。已記錄的兩個真實形態：一是用 npx 臨時執行時更容易觸發（GitHub 報告「Linux: OOM when running dsh via npx — use global install」，官方給的辦法就是改全域安裝）；二是 #8639 記錄的 dsh web 常駐場景——RSS 隨工作階段量成長，最後被 1GiB 的 cgroup 限額 OOM-kill。

修復步驟：

  1. 別拿 npx 長期跑，改全域安裝：npm install -g @deepseek-ai/dsh 之後用 dsh 直接啟動——這是官方對該報告的處置方式，順便也解決第十一節的 command not found。
  2. dsh web 常駐被殺（#8639 形態）：先查它所在的 systemd/cgroup 是不是卡著 1GiB 一類的硬限額——把 MemoryMax 調大或取消，再觀察 RSS 是否隨工作階段數持續成長；工作階段吃記憶體就定期重啟 dsh web。
  3. 先分診再動手：錯誤文字裡有 CONTEXT_WINDOW_EXCEEDED / token limit → 走第十七節和上下文壓縮指南；終端機只有一句 Killed、dmesg 裡出現 Out of memory: Killed process → 才是本節的 OOM。
  4. 容器與小記憶體 VPS：給 dsh 所在容器加 swap 或調高記憶體限額；Web UI 和多個工作階段同時跑時，預留 2GiB 以上的餘量更穩。
  5. 仍然重現：帶上 dsh --version、部署方式（npx / 全域 / Docker / cgroup 限額值）和 dmesg 相關行進討論區——#8639 那條線正在收集這類案例。

十九、桌面端起不來：9 月底那一輪啟動災難

症狀：2026 年 9 月底到 10 月初，官方討論區集中出現四種桌面端啟動失敗：Windows 11 上載入 V8 啟動快照失敗、應用直接死掉（#8776）；以系統管理員身分啟動回報 exitCode 18（#8787）；外掛 id 衝突導致宿主崩潰報 'prepare' is undefined（#8822），或 profile 的 package.json 被 BOM 寫壞後 resume 時報同一個錯（#8837）；以及老熟人 0xC0000142 三連報告（#8771、#8772，#8775 給出了背後 DACL capability SID 機制分析）。

逐形態原因與處置：

  1. V8 快照載入失敗（#8776）：桌面二進位的啟動快照無法載入，多發生在升級中斷或安裝損壞之後。重新下載安裝檔覆蓋安裝，不要沿用舊安裝目錄，並先從 CLI 確認 dsh --version 正常。
  2. 系統管理員啟動 exitCode 18（#8787）：提高權限改變了應用預期的環境（使用者目錄重新導向、PATH 不同）。先用一般使用者跑一次；確實需要提高權限時，從已提權的終端機以乾淨環境啟動，別對舊捷徑右鍵「以系統管理員身分執行」。
  3. 'prepare' is undefined（#8822、#8837）：這是宿主側崩潰，不是外掛沙箱內的錯——#8822 裡兩個外掛註冊了衝突的 id，查找落空；#8837 裡帶 BOM 的 package.json 讓 profile 解析失敗，隨後 resume 時同一個錯再次出現。移除肇事外掛，或把檔案另存為無 BOM 的 UTF-8，然後先冷啟動一次再恢復工作階段。10 月還出現了第三種形態（#8924）：web profile 裡自帶一份 @deepseek-ai/dsh-tools（本地開發外掛時的 dual-package 結構）時，所有工具呼叫都死於同一個 reading 'prepare' 錯誤，而純文字輪次存活——移除 profile 內的重複副本，讓 dsh-tools 只解析到一份。
  4. 0xC0000142 再現（#8771、#8772、#8775）：與第九、十二節同族的 STATUS_DLL_INIT_FAILED，第三輪出現，這次中英文報告都有。#8775 的分析指向子行程 DACL 裡的 capability SID。先跑第九節的一鍵修復——它仍是這一族錯誤的官方支援做法。

二十、升級後舊工作階段打不開：session format 編解碼器

症狀：升級到新版 dsh 之後，以前正常的工作階段打不開，回報 SessionFormatError 一類的錯誤。已記錄兩種形態：v0→v1 編解碼器拒絕 0.1.0-rc.6 / 0.1.1-rc.2 寫下的工作階段，因為其中 subagent/descriptor 事件帶的是 version: 2，而遷移程式碼要求 version: 3（#8868）——歷史裡有子代理工作階段的部署因此卡在升級前；v3→v4 編解碼器則在 system/message 不是整份日誌第一個 surface 節點時，拒絕本來合法的日誌（#8888）。

原因：工作階段日誌是帶版本的，每次遷移都做嚴格驗證：v0→v1 把事件版本釘死在單一取值，v3→v4 的 foldSurface 守衛假設 system/message 必須是第一個 surface 節點——兩個假設都誤傷了舊版本合法寫出的日誌。

修法：

  1. 先記下完整錯誤文字和 dsh --version——靠「哪一步遷移在報錯」區分兩種形態。
  2. 如果這些工作階段升級前一直能打開，最快的可用路徑是第 8 節的版本回滾：把 dsh 釘回寫下這些日誌的版本（npm install -g @deepseek-ai/dsh@<版本號>），打開工作階段把需要的內容匯出。
  3. 絕不要為了通過驗證手改工作階段檔案——改壞一處日誌就永久讀不出來了。先備份檔案，再帶著錯誤文字去 #8868 / #8888 追報告，後續修復都會落在這兩條討論串裡。

二十一、安全公告：經本機控制面的沙箱逃逸披露（#8887）

發生了什麼。官方討論區的公開揭露（#8887，嚴重級別：high）描述了一條從 dsh 本機控制面 127.0.0.1:3080 觸發的鏈路：只要能在任意一個沙箱工作階段裡執行一條指令（哪怕檔案策略是 read-only），受限代理就能逃逸沙箱、繞過審批政策，以你的使用者身分任意寫入檔案、全程無審批彈窗。已在 dsh 0.2.0-rc.2（Linux/WSL2）上驗證，揭露者認為與平台無關。

現在就做：

  1. 讓 Web UI 保持預設的僅回環綁定——攻擊鏈的起點是「任何能碰到 127.0.0.1:3080 的東西」，所以不要把綁定改寬，更不要把 3080 連接埠隧道到不完全信任的網路（安全的暴露方式見遠端存取指南）。
  2. 在修復版發布之前，把「沙箱」理解為「加固手段，不是安全邊界」：別讓沙箱工作階段去碰不可信儲存庫或易被注入的內容，尤其在那台機器上存著重要東西的時候。
  3. 修復落地後盡快升級 dsh，並持續關注 #8887——揭露討論串是官方回應與修復版本的權威出處。

二十二、安全公告：根目錄為 / 的工作區會讓沙箱失效（#9026）

發生了什麼。繼 #8887 控制面逃逸（第二十一節）三週後，第二份沙箱揭露落地：根為 / 的工作階段或工作區可以通過 resolveWorkspaceRoot() 的唯一檢查——isAbsolute()——原樣進入 writableRoots()，可寫集合變成 ['/', '/tmp', tmpdir()]。於是每個強制後端都放行整個檔案系統的讀寫：bwrap 靠 --bind / /，Landlock 因為 RW 規則壓過唯讀規則，sandbox-exec 靠 / 的可寫前綴。兩個入口都不做驗證：session.create({ cwd: '/' }) 與 workspace.create({ path: '/' })。

現在就做：

  1. 修復發布之前，絕不執行根為 / 的工作階段或工作區——也稽核一遍替你建立工作階段的工具鏈。眼下這就是全部防禦。
  2. 第二十一節的每一條繼續有效：Web UI 只綁回環、不隧道 3080 連接埠、把沙箱當加固手段而非安全邊界。
  3. 修復落地後及時更新 dsh，並持續關注 #9026——揭露討論串是官方回應的權威出處。

二十三、桌面端穩定性風暴：崩潰循環、被清空的外掛相依、Electron 44（2026 年 10 月）

症狀。一週之內討論區擠進了四種桌面端形態：應用每次啟動都崩、只有全量停用外掛才能救回（#8995）；桌面端升級後某支外掛靜默失效、任何地方都不報錯（#9030）；宿主程序回報 0xC0000409、renderer 在 Electron 44 / Chromium 152 上反覆崩（#8972），還有 renderer OOM 崩潰的姊妹帖（#8932）；以及一位重度使用者發表的 22 條可重現穩定性清單，橫跨外掛載入、相依樹、工作階段檔案與設定（#8951）。

逐形態的原因與修法。

  1. 啟動崩潰循環（#8995）。某支第三方外掛裡的未處理 rejection 被宿主的 fail-loud 處理器按致命錯誤對待，於是每次啟動都重複同一失敗——有記錄的案例三分鐘連崩六次。目前沒有自動安全模式，恢復靠手動：把 ~/.dsh/cordis.patch.yml 裡可疑外掛的 enabled 改為 false（或把檔案挪開），重新啟動，再逐支恢復以定位元兇。
  2. 升級後外掛靜默死亡（#9030）。有記錄的案例：桌面端升級把一支外掛的執行期相依目錄清空了，而套件管理器的狀態檔仍然在冊——內容沒了、哪裡都不報錯。如果升級後某支外掛的面板憑空消失且看不到任何報錯，重裝它（dsh plugin remove + dsh plugin add，或桌面端外掛管理器），讓相依重新落地。
  3. 0.2.0-rc.2 上反覆的宿主/renderer 崩潰（#8972、#8932）。宿主結束代碼 0xC0000409，renderer 在 Electron 44 / Chromium 152 上反覆崩、間隔還在縮短；姊妹帖記錄了 renderer 的 OOM 崩潰。附上桌面端匯出的診斷包，註明 dsh --version，去討論串補你的案例——這些形態正靠「崩潰頻率 + 死的是哪個程序」來區分。
  4. 22 條穩定性清單（#8951）。一份跑了 30 天、100+ 工作階段的記錄把三條修復排在所有之前：註冊了卻既不載入也不報錯的外掛；掛載失敗就連帶整個客戶端起不來的 fail-closed；以及沒有官方驗證/修復工具的工作階段檔案——最後這條就是第二十節的編解碼器地盤。除錯前值得先讀一遍：你遇到的形態可能已經在 P-01 到 P-22 裡。

還是沒解決？

  • 安全安裝外掛指南——安裝方式、Profile 與 CLI 速查
  • 設定教學——bundle、profile、patch：你改的到底是哪一層？
  • dsh 命令列速查表 — 常用指令、flag 與啟動模式一頁打盡
  • DeepSeek Harness 後悔藥 — 用 dsh-undo-savepoint 的存檔點與崩潰救援，先試著回滾而不是重裝
  • 提交外掛——如果外掛 README 描述的行為與你的實際情況不符，去它的倉庫開 issue，附上你的 dsh --profile 指令和完整報錯，維護者解決得最快；若是你維護的外掛，修正 README 後把它提交進目錄。
廣告

DSH Plugins 是獨立的 DeepSeek Harness 外掛市集，與 DeepSeek 官方無關，也不代表官方背書。第三方外掛未經安全稽核，安裝前請審查原始碼。

每週取得最新的 DeepSeek Harness 外掛，絕不濫發。