如何安裝 DeepSeek Harness（dsh）外掛：CLI 指令、Profile 切換與除錯速查教學（2026）

〇、升級 harness 本體之前先看這裡（0.2.0-rc.1，2026-09-28）

0.2.0 系列已經開跑：2026-09-28 npm latest 翻轉到 0.1.7-rc.2，同日 0.2.0 首個候選（0.2.0-rc.1）登上 next。發行說明裡有兩件事直接關係外掛使用者：自動化任務改由可選外掛包提供（升級後排程任務可能消失，裝上外掛包才會回來），外掛管理介面也做了重做。當天的升級潮在官方討論區留下成片的相容性回報——外掛成批死亡（#8145）、工作區被清（#8140）、Windows 沙箱 0xC0000142（#8141–#8143）。動 harness 之前：

# 1. 備份你的 Profile
cp ~/.dsh/profiles/<name>/cordis.patch.yml ~/dsh-profile-backup.yml

# 2. 預覽 0.2.0 要寫死精確版本號——候選版永遠別用 @latest
npm install -g @deepseek-ai/dsh@0.2.0-rc.1

# 3. 翻車就鎖回上一個可用的版本
npm install -g @deepseek-ai/dsh@0.1.7-rc.2

0.2.0 升級受波及的逐條「症狀 → 原因 → 修復」在疑難排解指南。

一、CLI 指令速查表（Quick Reference）

如果你熟悉 CLI 流程，可以直接參考以下高頻指令速查表：

# 1. 安裝 DeepSeek Harness 本體（dsh CLI）
npm install -g @deepseek-ai/dsh

# 2. 為當前預設環境安裝外掛（從 npm 套件庫）
dsh plugin add dsh-vision-toolkit

# 3. 為特定 Profile（如 Web 介面 / Headless 模式）安裝外掛
dsh plugin --profile web add dsh-web-ui
dsh plugin --profile headless add tokenledger

# 4. 從 GitHub 倉庫直接安裝（支援鎖定分支或 Tag）
dsh plugin add github:volcengine/openviking#main

# 5. 安裝本地正在開發的外掛（除錯模式）
dsh plugin add ./path/to/my-dsh-plugin

# 6. 解除安裝外掛並移除設定
dsh plugin remove dsh-vision-toolkit

二、理解 DSH 的「一切皆外掛」架構

DeepSeek Harness（dsh）採用 Cordis 微核心架構。在 DSH 中，無論是 UI 主題、模型推論中轉、視覺 OCR、長短期記憶還是 CLI 工具，一切能力均透過外掛實現。

生態也很好逛：僅 GitHub 的 dsh-plugin 主題就收錄了數千個公開儲存庫，官方 deepseek-ai/deepseek-harness 位居榜首。

GitHub 上的 dsh-plugin 主題，數千個社群外掛儲存庫。

為什麼 DSH 具有天生的「完全可逆性」？

傳統的套件管理器在解除安裝模組時容易留下殘留檔案或髒狀態。而在 DSH 中，外掛的註冊本質上是向設定層注入一筆宣告式記錄：

• 啟動時：Cordis 容器讀取設定，由下而上構建外掛依賴樹。
• 解除安裝時：只需移出設定記錄並重啟，外掛掛載的所有 API、工具、上下文鉤子與 UI 面板立刻全部撤銷，真正做到零殘留。

三、三種主流安裝方式

根據使用習慣，你可以選擇最適合的安裝方式：

官方課程講義把日常三條路概括成一張圖：敲一條命令、對話裡說一聲、去外掛市場點一下——下文再展開到設定檔與 Profile。

官方總結的三種外掛安裝方式。

方式 1：CLI 命令列一鍵新增（推薦）

透過 dsh plugin add 指令，CLI 會自動解析套件名稱、拉取依賴並將設定寫入對應的 Profile。

# 安裝指定版本
dsh plugin add dsh-mnemon@^1.2.0

# 為指定 Profile 新增帶有參數的外掛
dsh plugin --profile web add @scope/custom-theme --port 8080

方式 2：設定檔顯式宣告（cordis.patch.yml）

如果你習慣使用 Git 統一管理團隊或個人的開發環境，可以直接編輯設定層檔案：

# ~/.dsh/profiles/default/cordis.patch.yml 或專案根目錄 .dsh/cordis.patch.yml
plugins:
  # 基礎工具與視覺外掛
  dsh-vision-toolkit:
    enabled: true
    options:
      ocrEngine: 'default'
      maxImageSizeMb: 10

  # 記憶增強外掛
  volcengine/openviking:
    enabled: true
    options:
      persistPath: '~/.dsh/memory/viking.db'

編輯完成後，執行 dsh 重啟工作階段即可載入。

方式 3：視覺化市場一鍵安裝

對於透過 Web 介面使用 DSH 的開發者，可以首先安裝 dsh-market 市場外掛：

最快的方式是對話安裝：直接說一聲要裝什麼——下圖中 DSH 自動拉取、驗證並熱載入了 dshmarket v1.14.1，全程沒離開聊天視窗。

在對話裡請助手裝 dsh-market，裝完自動熱載入。

1. 在 Web 介面進入 Settings → Plugin Market。
2. 搜尋所需外掛（如 dsh-web-ui 或 modlens）。
3. 點擊 Install 按鈕，系統將在背景自動完成設定更新與熱載入。

在社群外掛市場彈出視窗中輸入 dsh-market 搜尋，目錄會立刻收斂到匹配的外掛卡片。

Web UI 內建的社群外掛市場搜尋。

點開卡片就是詳情彈出視窗：功能簡介、精確的 dsh plugin add 手動指令，以及跳轉原始碼儲存庫和 DSH 市場的入口。

dsh-market 詳情彈出視窗，附手動安裝指令。

裝好之後都在同一個彈出視窗管理：「已安裝」頁籤給每個外掛配了啟用開關、更新狀態和解除安裝按鈕。

已安裝外掛集中在同一個彈出視窗管理。

中國大陸網路加速：官方換源與 npmmirror 映射站

中國大陸網路環境下，從 npm 官方源安裝外掛經常卡在下載階段，兩條加速路線：

1. 官方換源入口（已隨 0.1.7 系列進入 latest 通道）：官方發行說明確認，外掛管理中的安裝已支援選擇 官方源 / npmmirror 映射站 / 自訂源，並提供安裝範例與進度顯示；0.1.7 系列還新增了「首次安裝且未設定源時，自動優先選擇可連線的最佳 npm 源」。npm latest 已於 2026-09-28 翻轉到 0.1.7 系列（0.1.7-rc.2），目前穩定版即具備此能力。

2. npmmirror 映射站（立即可用）：社群通用做法是把 npm registry 指向 npmmirror 映射站，讓外掛下載走加速通道：

# 將 registry 指向 npmmirror（去掉 -g 則只對當前專案生效）
npm config set registry https://registry.npmmirror.com

# 之後正常安裝外掛即可
dsh plugin add <owner>/<repo>

dsh plugin add github:owner/repo 直連 GitHub 逾時時，可先把儲存庫 clone 到本機再按方式 1 的除錯模式從本機路徑安裝，或設定代理後重試。npmmirror 是 npm 官方資料的完整映射，套件內容一致；企業內部網路也可在官方換源入口填入自己的私有 registry（自訂源）。

四、Profile 多環境隔離與切換

Profile 是 DSH 管理多情境外掛組合的核心機制。例如，你在本機寫程式碼需要強大的 Web UI 與視覺除錯工具，但在 CI/CD 自動化流程上只需要輕量級的 Headless 模式。

Profile 設定路徑層級

1. 全域 Profile：~/.dsh/profiles/<profile-name>/cordis.patch.yml（適用於所有工作區）
2. 專案級 Profile：<project-root>/.dsh/cordis.patch.yml（僅在當前專案生效，優先權高於全域）

切換與啟動 Profile

# 以 Web UI 模式啟動（載入 web profile 中的面板與外觀）
dsh --profile web

# 以 Headless 自動化模式啟動（僅載入核心推論與程式碼執行外掛）
dsh --profile headless --task "run all tests and fix lint errors"

# 以 TUI 純終端機增強模式啟動
dsh --profile tui

五、常見錯誤與排錯百科（Troubleshooting）

在安裝或載入外掛時遇到問題？請對照以下高頻情境排查：

還有一種配額失敗要留意：市場安裝過程中，軌跡可能閃出紅色 Insufficient Balance 條目——DeepSeek API 餘額用盡，儲值後重試即可。

餘額耗盡時，市場安裝會被攔下。

1. Plugin failed to register / Lifecycle timeout

• 症狀：啟動 dsh 時終端機提示外掛初始化逾時或找不到匯出符號。
• 排查步驟：
  1. 檢查 Node.js 執行環境：DSH 現代外掛體系需要 Node.js ≥ 20.0.0（推薦 Node 22 LTS）。
  2. 檢查依賴套件完整性：若使用 Git 原始碼安裝，確認是否執行過 pnpm install && pnpm build。

2. Profile patch collision / Override order issue

• 症狀：同時安裝了兩個同類型外掛（如兩個側邊欄 UI 外掛），介面出現重疊或樣式錯亂。
• 排查步驟：
  1. 開啟 cordis.patch.yml，檢查外掛列表順序。排在後面的外掛會覆蓋前面的同名服務。
  2. 將衝突外掛之一設為 enabled: false，或者將兩者分配到不同的 Profile 中隔離執行。

3. Permission denied / Sandbox security policy violation

• 症狀：外掛嘗試讀寫檔案或發起網路請求時被攔截報錯。
• 排查步驟：
  1. DSH 預設處於 read-only 安全沙箱模式。
  2. 若該外掛確實需要寫入權限（例如自動化重構外掛），在啟動參數中放寬權限：dsh --sandbox workspace-write。
  3. 詳見 DSH 安全沙箱指南。

4. pnpm-workspace allowlist / ESM CJS 模組載入失敗

• 症狀：在 monorepo 專案下安裝第三方外掛提示模組找不到。
• 排查步驟：
  1. 確保在根目錄 package.json 或 pnpm-workspace.yaml 中將外掛套件列入允許清單。
  2. 優先使用 npm 發布的官方相容版本。

六、五分鐘外掛安全審查清單

在安裝任何未經驗證的第三方外掛前，建議花五分鐘執行自檢：

1. 查閱 README：明確外掛功能邊界、所需環境變數以及是否包含對外網路請求。
2. 檢查開源授權條款（License）：優先選擇 MIT、Apache-2.0 等合規開源協議。
3. 快速掃描進入點原始碼：確認其沒有掃描工作區之外的敏感檔案（如 ~/.ssh/、~/.aws/）。
4. 查看社群健康度與活躍度：本站每個外掛詳情頁均公開展示 GitHub Star 數、近 90 天 Push 活躍度、Open Issues 與封存狀態。
5. 優先選擇收錄/精選外掛：本站目錄標有 Curated 或 Featured 徽章的外掛已經過社群多輪驗證。

七、常見問題 FAQ

Q: 有沒有類似 npm install 那樣的一行指令？
A: 有的。可以使用 dsh plugin add <package>（例如 dsh plugin add dsh-vision-toolkit），它會自動完成套件拉取與設定檔追加。

Q: 裝完外掛需要重新啟動 DSH 嗎？
A: 需要。DSH 在啟動時動態編譯外掛樹，修改設定後重新執行 dsh 指令即可生效。

Q: 怎麼徹底解除安裝一個 DSH 外掛？
A: 執行 dsh plugin remove <package>，或直接在 cordis.patch.yml 中刪掉那一行設定並重啟。得益於 Cordis 的可逆設計，不會殘留任何孤兒檔案。

Q: 本站目錄裡的 20,289+ 個外掛都經過審核嗎？
A: 本站提供全網最完整的即時索引，並對熱門外掛進行多維度體檢和多語言深度解析。安裝第三方程式碼時，仍建議遵循上述五分鐘安全審查清單。

八、相關資源與延伸閱讀

• 2026 必裝外掛排行榜 Top 10 與情境套件 —— 複製一條指令一鍵裝機
• 2026 必裝外掛推薦（12 款首選） —— 剛裝好 DSH 不知道裝什麼？看這篇
• 按情境探索精選合集 —— 聚合高頻開發工作流程
• DSH 設定檔詳細語法與疊加規則 —— 深入掌控 Cordis Patch 機制
• 從零編寫你的第一個 DSH 外掛 —— 外掛開發新手教學
• 瀏覽 22 大分類全部外掛目錄 —— 探索全網最大 DSH 外掛生態