DeepSeek Harness 安裝錯誤與版本衝突解決指南

DeepSeek Harness 安裝的實質內容

DeepSeek Harness 的安裝僅需一個指令：npx @deepseek-ai/dsh web。此工具沒有安裝程式，也無需設定任何服務。使用者遇到的大多數問題並非源於安裝過程，而是版本解析問題：即 npx 當下決定執行哪一個 @deepseek-ai/dsh 建置版本，以及您的 Node.js 版本是否支援該版本。

以下所有內容皆基於兩項事實。首先，目前發布至 npm 的每一版 @deepseek-ai/dsh 均為候選發布版本（release candidate），且 latest 標籤指向其中之一。截至 2026 年 8 月 18 日，該版本為 0.1.0-rc.7，於 2026 年 8 月 17 日發布。其次，專案 README 指出此 Harness 處於「開發者預覽」（developer preview）階段，正處於快速迭代中，且會包含破壞相容性的變更。上週有效的旗標（flag）本週可能就會移除。在基於此工具進行開發前，請務必鎖定版本。

首先說明幾個術語。dsh 是 DeepSeek Harness 的命令列工具。Node.js 是其所需的 JavaScript 執行環境。npx 是隨 npm (node package manager) 附帶的套件執行器，它會按需擷取套件，而非將其永久安裝。

dsh 需要哪個版本的 Node.js？

儲存庫根目錄的 package.json 宣告了 "engines": {"node": "^22.19.0 || >=24.0.0"}，於 2026 年 8 月 18 日讀取時版本為 0.1.0-rc.7。因此需要 Node 22.19.0 或更新的 22 系列版本，或是 Node 24 以上版本。不支援 Node 20。

在進行任何操作前，請先檢查您目前的版本。

node -v
npm -v

以下是令人意外的部分。已發布的 @deepseek-ai/dsh 套件本身並未包含 engines 欄位。只有 monorepo 的根目錄有宣告，而該根目錄檔案並不會發布到 npm。因此 npm 沒有任何檢查依據，不會顯示 EBADENGINE 警告，也不會拒絕安裝。在 Node 20 上安裝看起來會成功，但錯誤會在稍後發生，當載入的程式碼觸及執行環境不支援的語法或 API 時才會出現。由於第一個失敗的模組取決於載入順序，因此沒有單一且穩定的錯誤字串可供搜尋。請閱讀 node -v，不要只看當機訊息。

如果您的 Node 版本過舊，在 VPS 上使用 nvm (node version manager) 是影響最小的修復方式，因為它會安裝在您的家目錄下，不會更動系統層級的 Node。

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash
exec $SHELL -l
nvm install 24
nvm use 24
node -v

node -v 現在應該會顯示以 v24. 開頭的版本。如果 shell 仍顯示舊版本，代表 nvm 的 shell 函式未載入，請開啟新的登入 shell 後再試一次。截至 2026 年 8 月，Node 24.19.0 是目前的 LTS (長期支援) 版本，且基於下方提到的第二個原因，它是更理想的目標版本。

為什麼 npx 每天執行的版本都不一樣？

npx @deepseek-ai/dsh web 沒有指定版本，因此 npx 會向 registry 查詢 latest 標籤所指向的內容。該標籤會隨時變動。當 DeepSeek 發布 0.1.0-rc.8 時，您筆記中的指令就會開始執行不同的程式碼，過程中不會有任何提示，也不會顯示變更日誌。

您可以從命令列檢查每一個變動的部分。

npm view @deepseek-ai/dsh dist-tags
npm view @deepseek-ai/dsh versions --json
npm view @deepseek-ai/dsh time --json

dist-tags 會顯示 latest 目前指向的位置。在 2026 年 8 月 18 日，latest 與 next 皆指向 0.1.0-rc.7，因此沒有獨立的穩定頻道可供切換。versions 列表更值得關注，因為其中存在斷層：0.0.1-rc.1、0.0.1-rc.2、0.0.1-rc.5、0.1.0-rc.2、0.1.0-rc.3、0.1.0-rc.6、0.1.0-rc.7。該序列中缺少某些數字，是因為部分發布候選版本（release candidate）從未正式發布。在部署腳本中猜測下一個 -rc.N 將會失敗，因此請直接讀取列表，而非嘗試遞增推算。

為什麼 npx 總是執行舊版本？

這與常見的抱怨相反，但根據您所使用的 npm 版本，這兩種情況都可能發生。

npx 會維護一個獨立於 tarball 快取的套件目錄，該目錄位於 npm 快取內的 _npx 資料夾中。請列印該路徑並進行檢查。

npm config get cache
ls "$(npm config get cache)/_npx"

多年來，當指定純套件名稱時，npx 會重複使用該目錄中已有的任何內容，而不會再次向 registry 查詢。npm 11.2.0 改變了此行為。當規格為純名稱或版本範圍時，npx 現在會先取得 manifest，只有在解析出的 tarball 與 registry 最新回傳的內容相符時，才會重複使用快取副本。

您會遇到哪種行為取決於您的 Node 版本，因為 Node 內建了特定版本的 npm：

• Node 20.20.2 內建 npm 10.8.2。
• Node 22.19.0 內建 npm 10.9.3。
• Node 22.23.2（最新的 22 版本）內建 npm 10.9.8。
• Node 24.19.0 內建 npm 11.17.0。

因此，官方支援的整個 Node 22 系列所搭載的 npm 版本皆低於 11.2.0。在 Node 22 上，執行純 npx @deepseek-ai/dsh web 指令會持續執行數週前快取的 release candidate。相同的指令在 Node 24 上則會在每次執行時重新解析。同一個指令有兩種行為，且兩者皆不會發出警告。請查詢工具版本以確認：

npx @deepseek-ai/dsh --version

清除 npx 快取

在 npm 11.2.0 及更新版本中，提供了專用的子指令。

npm cache npx ls
npm cache npx rm --force

若未使用 --force，npm 會拒絕清除所有內容並顯示 Please use --force to remove entire npx cache。若您只想移除特定鍵值的項目而非全部清除，請先使用 npm cache npx ls。

在 npm 10 中，這些子指令不存在，因此您必須手動刪除該目錄。

rm -rf "$(npm config get cache)/_npx"

npm cache clean --force 在此無效。它只會清除 _cacache（即 tarball 儲存區），而不會更動 _npx。這種分離正是 npm 後來加入 npm cache npx 子指令的原因。清除 _npx 不會有任何永久性的損失：它僅存放已下載的套件，而您的 harness 狀態位於 $DSH_HOME/profiles/<name> 下，不會受到影響。

如何鎖定特定的發行候選版本 (release candidate)？

請指定完整的版本字串，包含 -rc.N 的部分。

npx --yes @deepseek-ai/dsh@0.1.0-rc.7 web

在腳本中使用 --yes 非常重要，否則 npx 在安裝未曾見過的套件前會顯示提示訊息，並等待永遠不會收到的回應。

指定確切版本也是執行速度最快的方式。npx 會根據您輸入的規格字串來標記快取目錄；若為確切版本，npx 會直接與已安裝的套件 ID 進行比對並執行，完全不需要向 registry 發送請求。在 npm 11.2.0 及更新版本中，若僅使用套件名稱，每次啟動時都會觸發一次 manifest 擷取。

全域安裝 (global install) 的鎖定方式相同，且能提供簡短的執行指令。

npm install -g @deepseek-ai/dsh@0.1.0-rc.7
dsh --version

找不到符合 @deepseek-ai/dsh@^0.1.0 的版本

針對此套件使用 caret (^) 或 tilde (~) 範圍會失敗。npm install -g @deepseek-ai/dsh@^0.1.0 會回傳錯誤代碼 ETARGET 以及訊息 No matching version found for @deepseek-ai/dsh@^0.1.0.。Registry 本身運作正常。這是 semver 的規則：除非版本範圍本身明確指定了預發行版本，否則該範圍不會匹配任何預發行版本。此套件發布的每個組建皆為 -rc.N，屬於預發行版本，因此 ^0.1.0 無法匹配任何內容。請務必寫入確切的版本號。

此規則有一個實用的副作用。由於版本範圍不會自動更新至新的發行候選版本，因此不會出現難以判斷的「半鎖定」狀態。您不是鎖定在確切版本，就是使用變動的標籤 (tag)。

我應該使用 npx 還是全域安裝 dsh？

若只是初步嘗試，請使用 npx，因為除了您已知如何清除的快取目錄外，系統不會留下任何殘留檔案。若該工具在重開機後仍需運作，例如 您在 VPS 上持續執行的程式設計代理，請使用鎖定版本的全域安裝。

若您在同一台機器上同時使用這兩種方式，兩者可能會產生衝突，請務必進行比對。

which dsh
dsh --version
npx @deepseek-ai/dsh --version

which dsh 在全域安裝成功後卻找不到指令，通常是因為 npm 的全域二進位目錄未加入您的 PATH。請執行 npm prefix -g 來列印根目錄，二進位檔案位於該目錄下的 bin 資料夾中。

安全性注意事項：npx 在解析新項目時會從 registry 抓取並執行程式碼，這在伺服器上是實際存在的風險，而非理論上的威脅。鎖定版本是解決方案的一部分，其餘細節請參考 npm 供應鏈攻擊如何入侵伺服器。

開發者預覽版對可重現性的意義

0.1.0-rc.6 發布於 2026 年 8 月 13 日，而 0.1.0-rc.7 發布於 2026 年 8 月 17 日。兩者僅相隔四天。以此速度，一個月前撰寫的指令可能已不存在，本頁面亦然。請為您記錄的每個版本聲明標註日期，包含您自己的筆記。

兩種習慣能讓您在預覽版中存活。請在每個指令與腳本中鎖定確切版本，確保重建伺服器時能產生相同的環境。接著，請閱讀已鎖定版本的說明輸出，而非參考任何指南。

npx @deepseek-ai/dsh@0.1.0-rc.7 --help
npx @deepseek-ai/dsh@0.1.0-rc.7 web --dump-config

可重現性的後半部分在於設定檔。dsh --profile <name> 會啟動儲存於 $DSH_HOME/profiles/<name> 的設定檔，而 web 與 headless 設定檔會在首次使用時從內建範本自動建立。該目錄也是 harness 讀取 其 API 金鑰、模型與端點設定 的位置，因此鎖定版本與運作中的設定是兩件必須正確處理的獨立事項。內建套件會從當前執行的 dsh 安裝解析，這意味著變更鎖定版本也會一併變更這些套件。外部插件的行為則不同。它們位於設定檔目錄中，且 dsh plugin --profile <name> add <package> 會將其參數轉發給 pnpm 進行安裝。因此 pnpm 必須存在於您的 PATH 中，若未安裝，dsh 會明確提示。設定檔本身的 package.json 用於鎖定這些插件，因此完整的鎖定涵蓋兩個檔案，而非一個。

如果您曾 在伺服器上將 Python 工具保持在隔離環境中，這種拆分方式會讓您感到熟悉：工具本身與您額外加入的項目會分別鎖定在不同位置。一旦 harness 啟動，下一個問題通常是網路而非版本，此時請參考 存取遠端 VPS 上的 dsh Web UI 以及 在 VPS 上安裝 DeepSeek Harness 中的詳細操作說明。

您實際會遇到的參數錯誤

這些錯誤來自 CLI 自身的解析器，因此在各個候選發布版本（release candidate）間保持穩定，且每個錯誤都會明確指出問題所在。

error: --profile <name> is required

您執行 npx @deepseek-ai/dsh 時未指定子指令也未指定 profile。由於直接執行該指令會啟動一個 profile，因此必須提供名稱。dsh web 是不需要 --profile 的子指令，因為它會自動為您啟動內建的 web profile。

error: --patch needs a path

執行 --patch 時後方未接任何參數。此旗標可重複使用，且每次使用時皆須提供一個檔案路徑。

error: --dump-config and --dump-default-config are mutually exclusive

請擇一使用。--dump-default-config 會印出內建的套件層（bundle layers），且不接受任何 --patch。--dump-config 則會印出該 profile 的組合設定。兩者皆會在印出資訊後結束程式，不會啟動 harness，因此這是確認新候選發布版本變更內容最安全的方式。

error: plugin needs pnpm arguments to forward (e.g. add <package>)

dsh plugin --profile <name> 未接收到任何可轉發的參數。該子指令會在 profile 遺失時進行初始化，隨後將指令列的其餘部分交給 pnpm 處理，因此必須提供如 add @scope/dsh-plugin-example 等參數。

FAQ

DeepSeek Harness 需要哪個 Node.js 版本？

該儲存庫在根目錄的 package.json 中宣告了 ^22.19.0 || >=24.0.0，截至 2026 年 8 月 18 日的版本 0.1.0-rc.7，需求為 Node 22.19.0 或更高版本的 22 系列，或是 Node 24 及更新版本。Node 20 無法運作。已發布的 npm 套件本身沒有 engines 欄位，因此 npm 不會發出警告或阻止安裝，導致錯誤在執行階段才出現。請先檢查 node -v。無論如何，Node 24 是更好的選擇，因為它內建了 npm 11，修正了 npx 版本重複使用的問題。

如何強制 npx 使用最新的 dsh 而非快取版本？

在 npm 11.2.0 及更新版本中，npx @deepseek-ai/dsh 每次執行時都會重新檢查登錄檔中的套件名稱。但在所有 Node 22 版本內建的 npm 10 中，則不會執行此檢查。請在 npm 11 上使用 npm cache npx rm --force 清除 npx 快取，或在 npm 10 上使用 rm -rf "$(npm config get cache)/_npx" 刪除該資料夾。接著使用 npx @deepseek-ai/dsh --version 確認。請注意，npm cache clean --force 清除的是不同的目錄，無法解決此問題。

為什麼安裝 @deepseek-ai/dsh@^0.1.0 會失敗？

npm 會回傳錯誤代碼 ETARGET 並顯示 No matching version found for @deepseek-ai/dsh@^0.1.0.。每個已發布的組建皆為預發布版本（例如 0.1.0-rc.7），而 semver 範圍除非明確指定，否則不會匹配預發布版本。請安裝確切的版本字串，並包含 -rc.N 後綴。執行 npm view @deepseek-ai/dsh versions --json 以查看現有版本，因為該序列中存在未發布候選版本的間隙。

應該全域安裝 dsh 還是透過 npx 執行？

npx 適合初步嘗試，因為除了快取目錄外不會留下任何殘留。若需長期穩定運作，建議使用如 npm install -g @deepseek-ai/dsh@0.1.0-rc.7 的固定版本全域安裝，因為版本僅會在您手動變更時才會異動。若全域安裝後找不到 dsh 指令，代表 npm 的全域 bin 目錄未加入您的 PATH，請使用 npm prefix -g 顯示其所在根目錄。

DeepSeek Harness 是否穩定到可以進行開發？

根據其自身描述，目前尚未穩定。README 指出該專案處於開發者預覽階段，正快速迭代，且將會有破壞相容性的變更。候選版本 0.1.0-rc.6 與 0.1.0-rc.7 於 2026 年 8 月相隔四天發布。請鎖定確切版本，並閱讀該鎖定組建中的 --help，而非參考任何指南。請為您的筆記標註日期，以便判斷資訊是否已過時。