DeepSeek Harness：修好 npx 失敗與埠 3080

這不是另一篇快速開始

npx 快速開始 假定 npx @deepseek-ai/dsh web 最後會打出 URL。本文寫給另一半首次流量：終端機掛住、3080 永不回應，或 UI 起來了但每則聊天都死在 API 錯誤。請與可檢索清單 疑難排解 並用——這裡講的是 檢查順序，免得三個變數同時亂轉。

精確 flag 仍歸上游。README 與本頁衝突時，以 README 為準。

階梯 1 — 碰 DSH 之前先證明 Node

上游預覽文件要求 Node.js ^22.19.0 或 >=24.0.0。在即將跑 npx 的 同一個 shell 執行 node -v 與 npm -v。nvm/fnm 在另一視窗選的版本不算數。

引擎不對的症狀：套件開始拉，隨後 engines 檢查失敗；或者根本沒有 node。先修 PATH、重開終端機，再重試。不要「在掛住的 npx 行程裡升級 Node」。

階梯 2 — 讓 @deepseek-ai/dsh 拉得下來

首次執行會下載很大的相依樹。失敗看起來像逾時、404，或快取到極舊的 rc。

1. 確認 scope：@deepseek-ai/dsh——拼錯會浪費半天。
2. 公司鏡像落後時，用 --registry=https://registry.npmjs.org 再試。
3. 只有排除網路與 scope 拼寫之後，再清有毒的 npx 快取。

終端機請留著。下載中途殺行程，等於去除錯半寫完的快取。

階梯 3 — 埠 3080 是本機 socket 問題

Web UI 常見綁定 http://127.0.0.1:3080/。若別的行程占著 3080，服務可能起來了，瀏覽器卻永遠看不到 DSH。

• 找出占用者（依系統用 netstat / lsof / 資源監視器）。
• 停掉它，或依上游文件的埠 flag 啟動（社群常見在 dsh web 上用 --port）。
• 首測留在 localhost。綁定 0.0.0.0 是安全決策，不是便利技巧。

終端機健康但頁面空白：換乾淨瀏覽器設定檔——擴充套件有時會擋本機腳本。

階梯 4 — UI 在、聊天死（金鑰與憑證）

本機 UI 通常是 控制面，不是離線權重。走 DeepSeek 路由的呼叫需要平台 API 金鑰。核對模型 id、配額，以及貼上時多出來的空白。

無頭／CLI 路徑可能讀 $DSH_HOME/.credentials.yaml（常見 ~/.dsh/.credentials.yaml）。Unix 上權限過開時，執行環境會拒絕該檔——chmod 600 是常見修法。本獨立站從不發放金鑰。

階梯 5 — 外掛登場時缺 pnpm

即便你用 npx 啟動，dsh plugin add 也常會叫出 pnpm。全域缺 pnpm，表現成「UI 都好了，安裝卻失敗」。裝好 pnpm、確保 bin 在 PATH，再重試 add——見 外掛指南。

不要做的事

• 排埠時，不要把第一個工作區指到整個使用者家目錄。
• 3080 還抖著，不要疊三個新社群外掛。
• 不要把上週部落格當 CLI 法律——評估時請釘住預覽版版本號。

接下來去哪

1. 健康安裝敘事：npx 快速開始。
2. 分系統一句話：安裝。
3. 分症狀清單：疑難排解。
4. 跑起來之後，先選 執行模式，再去淹在套件海裡。