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

一、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 工具，一切能力均透過外掛實現。

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

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

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

三、三種主流安裝方式

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

方式 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 市場外掛：

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

四、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）

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

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

八、相關資源與延伸閱讀

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