dsh 命令列速查表
DeepSeek Harness 值得記住的每一條指令——安裝、啟動、模式、外掛、設定與版本管理——整理成可列印的速查表。
最近更新: 2026-10-01
dsh 是 DeepSeek Harness 的命令列入口：一個二進位，啟動所有形態——Web UI、終端機工作階段、一次性 headless 任務，以及自動化 profile。它也是安裝、更新、修復整套 harness 最快的路徑。
本頁是速查參考：只收錄已核實的指令，全部取自官方 apps/cli README、根 README 與 npm 套件，並與站內逐步教學交叉核對。列印一份放在終端機旁，需要完整步驟時再順著連結進入教學。
速覽
- ▸一條指令安裝：npm install -g @deepseek-ai/dsh（需要 Node.js 20+）；不想裝全域？npx @deepseek-ai/dsh web 直接跑。
- ▸dsh web 啟動 Web UI（127.0.0.1:3080）；dsh --profile <名稱> 啟動任意 profile；dsh --profile headless 跑一次任務就結束。
- ▸外掛按 profile 隔離：用哪個 --profile 安裝（dsh plugin --profile web add），就必須用同一個 profile 啟動。
- ▸@latest 更新，精確版本號回滾（如 @0.2.0-rc.2）；任何除錯前先跑 dsh --version。
安裝與首次啟動
從零到跑起來共四步。npm 路線是官方文件路線；原始碼路線服務於開發。
- 1
檢查執行環境
dsh 需要 Node.js 20 或更高版本（建議 Node 22 LTS）。終端機裡 node -v 應顯示 v20.0.0 以上——這一條檢查能擋住最常見的「外掛註冊失敗」工單。
$node -v - 2
全域安裝 CLI
一次全域安裝，dsh 指令進入 PATH；繼續之前用 dsh --version 確認。macOS/Windows 桌面版（0.2.0-rc.2 起）還提供 Manage dsh command 選單項目，可以幫你裝好指令，無需另外的 Node.js 或 pnpm。
$npm install -g @deepseek-ai/dsh$dsh --version - 3
啟動：裝了用 dsh，沒裝用 npx
npx @deepseek-ai/dsh web 不做全域安裝直接執行目前版本，是第一次體驗最快的路。dsh web 效果相同：啟動 Web profile、開啟瀏覽器，並由指令本身印出存取網址（預設 127.0.0.1:3080；--no-open 不開瀏覽器，--port 換連接埠；SSH 下只印主機位址）。首次連接模型在 Settings → Models 完成。
$npx @deepseek-ai/dsh web$dsh web - 4
替代路線：從原始碼執行
面向開發：複製儲存庫，安裝並建置一次，之後 pnpm dsh web 直接用建置產物，不再重複建置。同一個啟動器轉發所有參數——pnpm dsh --profile headless 接引號裡的任務，且需要在環境變數或儲存庫根 .env 設定 DEEPSEEK_API_KEY。
$git clone https://github.com/deepseek-ai/deepseek-harness$pnpm install$pnpm run build$pnpm dsh web
profile、鏡像源與第三方外掛審查清單，見安裝教學： 安全地安裝外掛
模式對照：每個入口啟動什麼
dsh 沒有另外的桌面、伺服器或用戶端二進位——一個啟動器，不同 profile。下表內建 profile 首次使用時會自動從範本初始化。
| 模式 | 指令 | 給你什麼 |
|---|---|---|
| Web UI | dsh web | 瀏覽器裡的儀表板（127.0.0.1:3080）：工作區、外掛市場、設定。日常的圖形化主介面。 |
| Headless | dsh --profile headless "task" | 每次呼叫一個全新持久化工作階段：執行任務、印出最終答案、結束。為腳本和 CI 而生。 |
| ACP | dsh --profile acp | 官方 automation-only 的 Agent Client Protocol 服務（JSON-RPC stdio）——給編輯器與自動化用戶端；有意省略計畫、標題、終端機檢視等呈現面。 |
| SDK | dsh --profile sdk | 透過 JSON-RPC stdio 服務 SDK 用戶端，直到關閉或斷線——程式化整合。 |
| SDK Minimal | dsh --profile sdk-minimal | 以獨立最小代理樹服務 SDK 用戶端——最輕量的嵌入方式。 |
| TUI | dsh --profile tui | 終端機原生工作階段；--resume <id> 這個 flag 屬於該終端機應用。 |
| Desktop | — | 保留給 Electron 桌面版——CLI 拒絕啟動它、匯出它的設定或管理它的外掛。 |
模式是「表面」，工作階段能做什麼由 agent 預設集決定——Standard、PTC、Minimal、Creator 四個內建預設集，差別在工具箱： 四種模式：Standard、PTC、Minimal、Creator
常用指令速查表
按用途分組，方便列印：外掛、工作階段與 profile、設定檢查、診斷，版本管理在下一節。指令逐字照錄；安裝時用的 flag 必須與啟動時一致。
外掛——按 profile 安裝與管理
| 指令 | 作用 |
|---|---|
| dsh plugin --profile web list | 印出該 profile 的外掛條目與磁碟目錄——動手前先核對。 |
| dsh plugin --profile web add <package> | 從 npm registry 安裝外掛到 web profile（把 profile 名稱換成你自己的）。 |
| dsh plugin --profile web add github:owner/repo#tag | 安裝僅發布在 GitHub 的外掛，#ref 可釘住分支或標籤。 |
| dsh plugin --profile web add ./path/to/plugin | 從本機資料夾安裝外掛——本機開發路線。 |
| dsh plugin --profile web update | 更新一個 profile 的全部外掛。 |
| dsh plugin --profile web remove <package> | 從一個 profile 移除外掛。 |
工作階段與 profile
| 指令 | 作用 |
|---|---|
| dsh web | 啟動 Web profile——等同 dsh --profile web，指令會印出存取網址。 |
| dsh --profile <name> | 啟動 $DSH_HOME/profiles/<名稱> 下的指定 profile（web、headless、acp、sdk、sdk-minimal、tui 首次使用自動從範本初始化）。 |
| dsh --profile headless "one-off task" | Headless 一次性：全新持久化工作階段，印出最終答案後結束。 |
| dsh --profile tui --resume <id> | 在終端機應用裡恢復一個持久化工作階段。 |
| dsh --profile <name> --from-default-profile web | 從內建範本新建自訂 profile 並啟動。 |
設定——先檢查再修改
| 指令 | 作用 |
|---|---|
| dsh --dump-default-config | 不啟動、直接印出預設組合樹——看原生 dsh 會組出什麼。 |
| dsh --dump-config | 套用你的 profile 與 patch 覆蓋後印出組合樹——同樣不啟動。 |
| dsh --dump-config-schema | 印出外掛條目與 patch 的 JSON Schema（而非設定值）。 |
| dsh --patch <file> | 本次啟動在組合樹之上再疊加一個 patch 檔案。 |
| cat ~/.dsh/profiles/<name>/cordis.patch.yml | 手動讀取某個 profile 的 patch 檔案——若存在工作區層級 .dsh/cordis.patch.yml，它會覆蓋前者。 |
層級順序：bundle patch → profile cordis.patch.yml → $DSH_HOME/cordis.patch.yml → --patch 覆蓋。每次改設定先問自己「我在改哪一層」—— Profile、Patch 與 Preset
診斷
| 指令 | 作用 |
|---|---|
| dsh --version | 顯示執行環境版本（用於 peer 範圍檢查）。任何除錯前先跑它。 |
| dsh --help | 啟動器自帶說明；應用層 flag 因 profile 而異（試試 dsh --profile web --help）。 |
| node -v | 確認 Node.js 20+——外掛註冊失敗最常見的原因。 |
| npm prefix -g | 印出 npm 全域前綴——dsh 執行檔在其 bin 目錄裡；shell 回報 command not found 時與 PATH 對照。 |
這裡的指令跑不動時，按「症狀 → 原因 → 修復」排錯百科逐條處理： 疑難排解與錯誤百科
版本管理
更新與回滾是同一條指令，差別只在標籤。改用預發布通道前，先看 npm dist-tags 或 release notes。
| 指令 | 作用 |
|---|---|
| npm install -g @deepseek-ai/dsh@latest | 把 CLI 更新到 npm latest 最新——截至 2026-10-01 是 0.2.0-rc.2。 |
| npm install -g @deepseek-ai/dsh@<exact-version> | 釘住（或回滾到）精確版本——重現問題或還原時永遠不要用 @latest。 |
| dsh plugin --profile web update | 更新一個 profile 的外掛。 |
| dsh plugin --profile web add github:owner/repo#v1.2.3 | 把外掛釘在標籤上，而不是跟著移動的分支。 |
升級前先備份 ~/.dsh/profiles/<名稱>/cordis.patch.yml——0.2.0-rc 升級潮在討論區留下大量工作區被清空、外掛批量失效的回報。
完整的更新與回滾教學（含 Web UI 市場路線）： 升級 DSH 與外掛
平台一行卡
每個平台一段可複製的指令。四條路的終點相同：127.0.0.1:3080 的 Web UI。
macOS
終端機裡免安裝直接跑，npm 只詢問一次，輸 y：
Windows
PowerShell（無需 WSL）：先裝一次，再啟動——
Linux
先查執行環境，再免全域安裝執行：
WSL2
WSL2 內直接用 Linux 指令；dsh 也能原生跑在 Windows 上，二選一並固定使用——混用會把 ~/.dsh 分成兩份。
dsh CLI 常見問題
打開速查表之後最先冒出來的問題。
dsh 和 DeepSeek Harness 是同一個東西嗎？
dsh 是 harness 的命令列入口，也就是 npm 上發布的 @deepseek-ai/dsh 套件。桌面版與 Web UI 是同一棵樹上的不同表面：dsh web 從同一份安裝啟動 Web profile。0.2.0-rc.2 起，macOS/Windows 桌面版還內建 Manage dsh command 選單項目，能幫你安裝並管理這條 CLI（含外掛），無需另外的 Node.js 或 pnpm。
用 npx @deepseek-ai/dsh web 還是先全域安裝？
npx 是零安裝路線——抓套件跑一次 Web UI，最快看到介面，也是全域安裝壞掉時的臨時替代。日常使用建議全域安裝（npm install -g @deepseek-ai/dsh）：dsh web 秒啟，dsh --version 告訴你實際在跑什麼，dsh plugin 管理外掛。兩條路線都可以用 dsh --version 驗證。
裝了外掛，dsh 啟動後卻沒有——去哪了？
幾乎都是 profile 不匹配。dsh plugin --profile web add <套件名> 把條目寫進 web profile；之後如果直接執行 dsh（預設 profile），那棵樹裡沒有這個外掛。先用 dsh plugin --profile web list 確認條目和目錄，再用 dsh --profile web 啟動。所有 flag 同理：裝的時候用什麼，啟動時就用什麼。
profile 存在哪裡，怎麼新建？
profile 位於 $DSH_HOME/profiles/<名稱>，也就是 harness home（預設 ~/.dsh，DSH_HOME 可改）下面。內建 profile（web、headless、acp、sdk、sdk-minimal、tui）首次使用自動從範本初始化。自訂 profile：dsh --profile <名稱> --from-default-profile web 複製一份內建範本並啟動。不啟動、只看組合結果用 dsh --dump-config。
desktop profile 是做什麼的——為什麼 dsh 拒絕它？
desktop 這個名稱保留給 Electron 桌面版。CLI 會拒絕啟動它、匯出它的設定、管理它的外掛，所以 dsh --profile desktop 按設計直接報錯。想要那個表面就用桌面版；瀏覽器路線用 dsh web。
dsh 怎麼更新？升級壞掉怎麼回滾？
更新：npm install -g @deepseek-ai/dsh@latest（npm latest 截至 2026-10-01 是 0.2.0-rc.2），然後 dsh --version 確認。回滾：改裝精確版本 npm install -g @deepseek-ai/dsh@0.1.5-rc.2——永遠不要用 @latest 回滾。升級前先備份 ~/.dsh/profiles/<名稱>/cordis.patch.yml；個別外掛可用 dsh plugin add github:owner/repo#v1.2.3 釘住。
相關教學
每張速查表背後的完整逐步教學。
DeepSeek Harness：10 步全流程導覽
從 git clone 到 headless 模式——安裝、接供應商、配預設、Creator 模式做外掛、沙箱與軌跡收據，一篇導覽走完。
閱讀教學安全地安裝外掛
dsh 裡「安裝外掛」到底發生什麼，附一套第三方程式碼審查清單。
閱讀教學四種模式：Standard、PTC、Minimal、Creator
每種 agent preset 包含什麼、什麼情境用哪一種，以及怎麼在 Creator 模式裡做自己的 preset。
閱讀教學Profile、Patch 與 Preset
一個 dsh 行程如何由層層設定組裝而成 —— 以及怎麼把它調成你的形狀。
閱讀教學升級 DSH 與外掛
經過核實的升級命令：查版本、升級 dsh CLI、在終端或 Web UI 外掛市場更新外掛，以及安全回滾。
閱讀教學疑難排解與錯誤百科
症狀 → 原因 → 修復：安裝失敗、pnpm workspace allowlist 錯誤、cordis.patch.yml 衝突、bundle 格式錯誤與 Profile 設定無效。
閱讀教學