如何修正 DeepSeek Harness 安裝與版本錯誤

DeepSeek Harness 安裝的實際內容

DeepSeek Harness 的安裝只有一個指令：npx @deepseek-ai/dsh web。它沒有安裝程式，也沒有需要設定的服務。多數人遇到的問題其實不是安裝問題，而是版本解析問題：@deepseek-ai/dsh 的 npx 今天決定執行哪個版本，以及你的 Node.js 版本是否能執行它。服務啟動後，輸出的位址會繫結至 localhost；Web UI 只在 127.0.0.1:3080 回應的原因，與本頁討論的問題無關。

以下內容都建立在兩個事實上。第一，截至目前，@deepseek-ai/dsh 發布到 npm 的每個版本都是預發布版本。多數是候選發行版（-rc.N）；自 30 August 2026 起，也有 alpha 版本（-alpha.N）。latest 標籤指向候選發行版。截至 6 October 2026，該版本是 0.2.0-rc.2，發布於 29 September 2026。第二，專案 README 表示此 harness 目前處於 developer preview 階段，開發快速迭代，且將會有造成相容性中斷的變更。上週可用的旗標，本週可能已經移除。在以此為基礎建置任何內容前，請先固定版本。

先說明幾個術語。dsh 是 DeepSeek Harness 的命令列工具。Node.js 是它所需的 JavaScript 執行環境。npx 是隨 npm（node package manager）提供的套件執行工具，會按需擷取套件，而不是永久安裝套件。如果這句中的 harness 一詞不熟悉，請參閱agent harness 是包覆在模型外部的程式。它負責管理迴圈、工具、權限與工作階段狀態。因此，未由你選擇的版本號碼，也可能改變 agent 的行為。

dsh 需要哪個 Node.js 版本？

儲存庫的根目錄 package.json 宣告了 "engines": {"node": "^22.19.0 || >=24.0.0"}。該內容讀取於 6 October 2026，當時儲存庫版本為 0.2.1-alpha.1。因此，需要 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 函式尚未載入。請開啟新的 login shell，再試一次。截至 6 October 2026，Node 24 是現行 LTS（long term support）系列，當日最新版本為 24.21.0。選擇此版本還有第二個理由，將在下文說明。

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

npx @deepseek-ai/dsh web 未指定版本，因此 npx 會向 registry 詢問 latest 標籤目前指向的版本。該標籤經常變更。0.1.0-rc.8 於 19 August 2026 發布，時間比 0.1.0-rc.7 晚兩天；到了 6 October 2026，latest 已經改為指向 0.2.0-rc.2。每次標籤變更後，筆記中的指令就會開始執行不同的程式碼，而且不會提示，也不會在執行前顯示變更記錄。

您可以從命令列檢查每個變動環節。

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

dist-tags 會顯示 latest 目前指向的位置。在 6 October 2026，latest 與 next 都指向 0.2.0-rc.2；第三個標籤 alpha 則指向 0.2.1-alpha.1。這些標籤都不是可切換使用的穩定頻道。versions 清單更值得注意，因為其中存在缺號。在 6 October 2026，該清單包含 30 個版本，範圍從 0.0.1-rc.1 到 0.2.1-alpha.1。0.0.1 系列從 -rc.2 跳到 -rc.5，0.1.0 系列從 -rc.3 跳到 -rc.6；alpha 組建從 0.1.2-alpha.2 與 0.1.3-alpha.2 開始，而且完全沒有 0.1.4。版本號缺少，是因為部分組建從未發布；此外，alpha 組建與 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.3 是截至 6 October 2026 最新的 22 版本，內建 npm 10.9.9。
• Node 24.19.0 內建 npm 11.17.0。
• Node 24.21.0 是截至 6 October 2026 最新的 24 版本，內建 npm 11.19.0。

因此，整個 Node 22 系列雖然受到 harness 官方支援，卻內建早於 11.2.0 的 npm。在 Node 22 上，未指定版本的 npx @deepseek-ai/dsh web 會持續執行數週前快取的候選版本。同一個指令在 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

本頁範例使用 0.1.0-rc.7。請替換為實際測試過的 build。2026 年 10 月 6 日，latest 標籤指向 0.2.0-rc.2。

在腳本中，--yes 很重要，因為 npx 否則會在安裝尚未見過的套件前顯示提示，並等待不會出現的回應。

確切版本也是最快的路徑。npx 會以你輸入的 spec 字串作為快取目錄的索引。對於確切版本，它會將該字串與已安裝在快取中的套件 ID 比對，完全不存取 registry 就直接執行。在 npm 11.2.0 及更新版本中，使用未指定版本的名稱，每次啟動都會進行一次 manifest 擷取。

全域安裝也能以相同方式固定版本，並提供較短的命令。

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 規則：除非版本範圍本身指定 prerelease，否則版本範圍不會符合 prerelease 版本。此套件發布的每個 build 都是 prerelease，格式不是 -rc.N，就是 -alpha.N，因此 ^0.1.0 不會符合任何版本。請寫出確切版本。

這項規則也帶來實用的效果。由於範圍無法漂移到新的 release candidate，因此不會有難以判斷的半固定狀態。你要麼使用確切版本，要麼使用會變動的標籤。

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

先使用 npx，因為除了快取目錄之外不會留下其他內容，而你現在已知道如何清除該目錄。凡是重新開機後仍必須運作的項目，則使用鎖定版本的全域安裝，例如 持續在 VPS 上執行的程式碼代理程式。

如果同一台主機同時使用過這兩種方式，兩者可能會產生不同結果，因此請加以比較。

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

which dsh 在全域安裝成功後立即找不到任何內容，幾乎總是表示 npm 的全域 bin 目錄未包含在你的 PATH 中。執行 npm prefix -g 以輸出根目錄；二進位檔位於其下的 bin 資料夾。

另有一項安全性注意事項。npx 每當解析到新的項目時，都會從 registry 擷取並執行程式碼。對伺服器而言，這是實際的暴露風險，而非理論上的問題。鎖定版本是因應方式之一。其餘內容請參閱 npm 供應鏈攻擊如何入侵伺服器。

可重現性中的開發者預覽代表什麼

0.1.0-rc.6 於 13 August 2026 發布，0.1.0-rc.7 則於 17 August 2026 發布。兩者相隔 4 天。此後發布速度並未放緩：在 19 August 至 3 October 2026 期間又發布了 23 個版本，其中包括 28 September 發布的 0.2.0-rc.1，以及隔天發布的 0.2.0-rc.2。依照這個速度，1 個月前撰寫的說明可能描述已不存在的命令列，這個頁面也不例外。請為你記錄的每項版本資訊加上日期，包括自己的筆記。

有 2 個習慣可以讓你較容易應對預覽版本。請在每個命令與每個 script 中鎖定確切版本，讓伺服器重建時使用相同的 harness。接著，請讀取已鎖定版本的 help 輸出，而不是依賴任何指南。

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

可重現性的另一半是 profile。dsh --profile <name> 會啟動儲存在 $DSH_HOME/profiles/<name> 的 profile，而 web 與 headless profile 會在首次使用時，根據隨附的範本自行建立。該目錄也是 harness 讀取API key、model 與 endpoint 設定的位置，因此，鎖定版本與具備可用設定是必須分別處理的兩件事。內建套件會從目前執行中的 dsh 安裝解析，這表示變更鎖定版本也會同時變更這些套件。樹外插件的行為不同。它們位於 profile 目錄中，而 dsh plugin --profile <name> add <package> 會將其引數轉送給 pnpm 以進行安裝。因此，pnpm 必須位於你的 PATH 中；如果不是，dsh 會明確顯示此問題。你新增的每個插件都會以 agent 擁有的相同權限執行，因此值得在安裝前先確認插件可以存取哪些內容。profile 自身的 package.json 會鎖定這些插件，因此完整的版本鎖定涵蓋 2 個檔案，而不是 1 個。

如果你曾在伺服器上將 Python 工具放在隔離環境中，應該會熟悉這種拆分方式：工具本身與你加入其中的內容，會分別在不同位置鎖定。harness 啟動後，下一個通常需要處理的是網路，而不是版本；這時可參考從遠端 VPS 連線到 dsh Web UI，以及在 VPS 上安裝 DeepSeek Harness的完整說明。

實際會看到的引數錯誤

這些錯誤來自 CLI 自身的剖析器，每則訊息都會指出確切問題。不同 build 之間的文字大致維持一致，但並非完全相同，因此以下訊息已與 0.2.0-rc.2 在 6 October 2026 的版本進行比對。

error: --profile <name> is required

你執行 npx @deepseek-ai/dsh 時沒有指定子命令或 profile。這個裸命令會啟動 profile，因此需要名稱。dsh web 不需要 --profile，因為剖析器會將第一個裸字串視為 profile 名稱，因此會替你啟動隨附的 web profile。

error: --patch needs a path

你使用 --patch 時，後面沒有提供內容。這個旗標可重複使用，每次出現都必須接一個檔案路徑。

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

請擇一使用。在 0.2.0-rc.2 中，build latest 於 6 October 2026 指向的版本會列出第三個旗標，訊息為 error: --dump-config, --dump-default-config, and --dump-config-schema are mutually exclusive，因為 --dump-config-schema 已加入前兩者。它會輸出 profile 項目與 patch 的 JSON Schema。--dump-default-config 會輸出隨附的 bundle layer，且不接受 --patch。--dump-config 會輸出某個 profile 的組合設定。這些選項都會輸出結果後結束，不會啟動 harness，因此是查看新 release candidate 在執行環境中變更內容的安全方式。

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

你未提供任何內容給 dsh plugin --profile <name> 轉送。缺少 profile 時，這個子命令會先初始化 profile，再將命令列的其餘部分交給 pnpm，因此需要提供類似 add @scope/dsh-plugin-example 的引數。

FAQ

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

儲存庫在根目錄的 package.json 中宣告 ^22.19.0 || >=24.0.0。截至 6 October 2026，儲存庫版本為 0.2.1-alpha.1。因此，需要 22 系列的 Node 22.19.0 或更新版本，或 Node 24 以上版本。Node 20 無法運作。已發布的 npm 套件本身沒有 engines 欄位，因此 npm 不會發出警告，也不會阻止安裝，錯誤會延後到執行階段才出現。先檢查 node -v。Node 24 仍是較佳選擇，因為它內建 npm 11，可修正 npx 重複使用版本的問題。

如何強制 npx 使用最新的 dsh，而不是快取中的版本？

在 npm 11.2.0 及更新版本中，npx @deepseek-ai/dsh 每次執行時都會重新向 registry 查詢未指定版本的套件名稱。在每個 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.。每個已發布的 build 都是預發布版本，例如 0.2.0-rc.2 或 0.2.1-alpha.1；除非 semver 範圍本身指定預發布版本，否則範圍不會符合預發布版本。請安裝包含後綴的完整版本字串。執行 npm view @deepseek-ai/dsh versions --json 查看現有版本，因為版本序列中有些 build 從未發布，會出現間隔。

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

npx 適合初步嘗試，因為除了快取目錄之外不會保留其他內容。需要持續運作的環境則適合使用固定版本的全域安裝，例如 npm install -g @deepseek-ai/dsh@0.1.0-rc.7，因為只有在你變更版本時，版本才會改變。如果全域安裝後找不到 dsh 命令，表示 npm 的全域 bin 目錄不在你的 PATH 中；npm prefix -g 會顯示其所在的 root。

DeepSeek Harness 是否已穩定到可以作為基礎使用？

依其自身說明，目前尚未達到。README 表示此專案仍處於 developer preview 階段，正在快速迭代，且會出現破壞相容性的變更。Release candidate 0.1.0-rc.6 與 0.1.0-rc.7 在 August 2026 相隔 4 天發布；0.2.0-rc.1 與 0.2.0-rc.2 則在 September 2026 相隔 1 天發布。請固定使用完整版本，並從該固定版本的 build 閱讀 --help，不要依賴任何指南中的內容。為自己的筆記標註日期，以便判斷內容已經過時多久。