DeepSeek Harness dsh 安裝教學：Web 啟動、Headless 與 AI Coding 實測

DeepSeek Harness dsh 是什麼？

DeepSeek Harness 是 DeepSeek 開源的 Agent 執行框架，MIT 授權，命令列叫 dsh。產品頁的說法是：模型、工具、Skill、工作階段、沙箱、儲存、迴圈和 UI 都是可替換外掛，底層用 Cordis，口號是 Everything is a plugin。（deepseek.com/harness）

搜「DeepSeek Harness 是什麼」時，真正要分清的是三件東西，而不是再聽一遍函式呼叫協定。

API 是引擎，dsh 是已經裝好方向盤、工具箱和駕駛邏輯的 Runtime。 自己寫 while 迴圈調 chat/completions，是另一條路；8 月那篇 DeepSeek Harness AI Agent 指南 講自建迴圈。這篇只驗收官方啟動器：怎麼裝、Web 開在哪、第一條編碼任務怎樣算跑通。

官網還列了幾種執行模式。第一次用 Standard 的 Web UI 就夠：完整編碼 Agent，能改檔案、跑 shell、做搜尋。Code 模式是在 Standard 之上讓模型用 TypeScript 編排多輪工具呼叫，等 3080 穩定再開。Minimal 幾乎只留 bash 和編輯器，適合對比模型，不適合當日常 IDE。Creator 用來看執行階段、試外掛，第一小時可以跳過。

安裝 dsh 前要準備什麼？

官方 README 的零安裝路徑只有兩句：先裝 Node.js，再跑 npx @deepseek-ai/dsh web。社群文件提過 Node ^22.19.0 或 >=24.0.0；以你本機 npx 能否拉起 @deepseek-ai/dsh 為準，不必為對齊某篇博客去降級系統 Node。

金鑰按官方 CLI 說明解析：程序環境 → ~/.dsh/.credentials.yaml → 目前目錄 .env → ~/.dsh/.env。第一次選一種即可，不要同時寫四份還對不上：

export DEEPSEEK_API_KEY=sk-你的金鑰
mkdir -p ~/.dsh
printf 'DEEPSEEK_API_KEY=sk-你的金鑰\n' >> ~/.dsh/.env
chmod 600 ~/.dsh/.env

官方適配器名稱是 deepseek-official，預設走官方模型路由。要把請求打到自建閘道，屬於第二步，先看 OmniRoute 實測 有沒有必要，第一小時不必換 Base URL。

CLI 把你執行命令時所在的目錄當作預設 workspace。先建一個空倉庫或副本，例如 ~/work/dsh-first-run。SAFETY.md 建議最小權限，並優先用可丟棄的虛擬機器、容器或專用環境。金鑰和隔離目錄沒準備好，就先別執行 npx：介面能開、任務不能控，比裝不上更糟。

DeepSeek Harness 怎麼安裝並開啟 Web UI？

第一次不必 clone。進入隔離目錄：

cd ~/work/dsh-first-run
npx @deepseek-ai/dsh web

這是官方 README 的安裝入口。dsh web 是 --profile web 的別名，第一次會按範本初始化 ~/.dsh/profiles/web/。預設在 http://127.0.0.1:3080 起工作臺，本機啟動還會開啟預設瀏覽器。透過 SSH 啟動時只列印主機 URL，本機轉送由 SSH 用戶端或編輯器處理。預覽階段命令會改，以 deepseek-ai/deepseek-harness 當天 README、CLI 說明為準。

npx @deepseek-ai/dsh web --no-open
npx @deepseek-ai/dsh web --port 8080

預設只綁迴路位址。需要遠端看介面，用 SSH 本機轉送即可；第一天沒有必要把 UI 暴露到區域網路。官方使用指南寫：workspace 在 Web UI 裡用目錄選擇器指定，不是一條 CLI 旗標。開啟 3080 後，先確認目前目錄就是隔離倉庫，再發任務。

設定落在 ~/.dsh/：家目錄讓它自己建；sessions/ 用來回看工具呼叫；.env 只放金鑰，權限 600；profiles/web/ 第一天不用手改 patch。

三種情況才值得 clone 原始碼：要跟某個 commit、要改外掛，或 npx 拉套件失敗、需要對照建置產物。那時再 git clone 官方倉庫，pnpm install、pnpm run build、pnpm dsh web。pnpm dsh web 直接用建置產物，不會再編一次。原始碼樹裡跟 AGENTS.md，不要把示範命令抄進正式環境指令稿。

dsh Headless 怎麼用？

dsh run 已刪除。一次性任務用 headless：新開工作階段，把最後一段非空助手文字打到 stdout，然後結束。

cd ~/work/dsh-first-run
npx @deepseek-ai/dsh --profile headless "列出目前目錄下的檔案名稱，不要修改任何檔案"

這就是第一條值得寫進筆記的實測：程序結束代碼、stdout 有沒有最終回覆、~/.dsh/sessions/ 有沒有多一條可回看的日誌。任務必須唯讀。官方還有 sdk / sdk-minimal / acp 等 profile，給別的程序用 JSON-RPC 或 ACP 接入，那是第二週的事，第一小時不要並行開。

用 DeepSeek Harness 做 AI Coding

Web 或 headless 能說話，還不等於「可以讓它改倉庫」。按官方 Standard 能力，它確實能改檔案、跑 shell、做搜尋和子 Agent；預覽軟體加上模型會寫命令，所以第一條編碼任務必須能對照 git diff。下面不是跑分，而是確認 dsh 會不會在你指定的目錄裡改對一個函式。

先做一個能看清對錯的小倉庫：greet.ts 故意回傳 hi Ada，測試預期 Hello, Ada。對錯你自己能看出來，不依賴模型「說得像那麼回事」。

mkdir -p ~/work/dsh-first-run && cd ~/work/dsh-first-run
git init
printf '%s\n' 'export function greet(name: string): string {' '  return "hi " + name' '}' > greet.ts
printf '%s\n' 'import { greet } from "./greet.ts"' 'if (greet("Ada") !== "Hello, Ada") {' '  throw new Error("unexpected greeting")' '}' > greet.test.ts
git add . && git commit -m "chore: isolated dsh first-run repo"

1. 唯讀：閱讀 greet.ts 和 greet.test.ts，說明測試為什麼會失敗。不要修改任何檔案。 通過：它指出回傳值和測試預期不一致，工作區 git status 仍是乾淨的。
2. 單一檔案：只修改 greet.ts，讓 greet("Ada") 回傳 Hello, Ada。不要改測試，不要提交。 改完後自己跑測試，沒有現成 runner 就直接看函式回傳值，再執行 git diff。通過：diff 只動 greet.ts，回傳值對上測試。
3. 測試仍失敗，就把失敗輸出貼回去，讓它再改同一檔案。最後提交前必須你自己看 diff。編碼任務失敗時，開啟 ~/.dsh/sessions/ 或官網 Trajectory，區分「選錯工具」「參數不合法」「你拒絕了核准」「工作區根本不是這個目錄」。

第一次用預設 Standard / native 工具。單一檔案任務已經穩定，再考慮 DSH_TOOLS_MODE=code 或 both，讓模型用 TypeScript 編排多輪呼叫。官方參考裡，DSH_PERMISSION_MODE 的程序級回退接近 workspace-write；danger-full-access 幾乎不再問核准，第一次執行清單已經排除它。卡在 JSON 工具參數時，先讀 JSON Schema 與 AI Agent，再考慮換模型。任務拆太大、來回改，見 AI Coding 工作流——dsh 只解決「官方執行階段在不在」。

DeepSeek Harness 安裝成功了嗎？

標題裡的「實測」在這裡不是跑分榜，而是一份半小時清單。五項都過，才算「dsh 在這台機器上能用」。缺一項就回到對應步驟，先別擴大改檔案範圍。

五項裡缺任何一項，都先別進入「自動改幾十個檔案」。預覽版迭代快，把命令、Node 版本、dsh 套件版本和日期記在筆記裡，下週再跑時才分得清是你的環境變了，還是上游 breaking change。

dsh 常見報錯與解決方法

npx 失敗或很慢。 第一次要拉 @deepseek-ai/dsh。網路不穩就換原始碼建置，或先確認 npm registry。半套快取目錄不能當成「已經安裝成功」。

3080 打不開。 加 --no-open 後手動造訪；檢查連接埠是否被占用，或你用了 --port 卻仍開啟 3080。

介面開了但模型不運作。 多半是金鑰層沒對上。程序環境優先順序最高，~/.dsh/.env 只是備援。改完重新啟動 web 程序，不要指望熱更新金鑰。

改錯了目錄。 看啟動時的目前目錄，以及 Web 裡選取的倉庫。最常見的誤操作是把家目錄當成 workspace。

還在用 dsh run，或 headless 不結束。 官方使用指南寫明該子命令已移除，一次性任務改 --profile headless。把任務收成一句唯讀指令，確認程序沒有在等核准，再看 session 日誌卡在哪一步。

dsh 不是 Claude Code、Codex 的換皮。出品方分別是 DeepSeek、Anthropic 和 OpenAI；形態上 dsh 是獨立執行階段加 Web / headless，另外兩套是各自的 CLI。設定目錄也不互通：dsh 在 ~/.dsh。第一次驗收，dsh 看 3080 或一條 headless，另外兩套走各自官方冒煙測試。可以同時安裝，但不能假設 Key、權限和工作階段互通。真的要把三套請求併到一個入口，再評估閘道；第一天先把 dsh 自己跑通。

現在不適合當成正式環境執行階段。官方 README 寫明處於 developer preview，會有破壞相容性的變更。SAFETY.md 寫得更硬：未經安全稽核；它能執行模型產生的命令、載入第三方外掛、存取網路和你交給它的檔案。沙箱和核准能降低風險，不能當唯一的安全控管。現在適合隔離目錄裡的安裝驗收、單一函式級 AI Coding、對照 session 日誌做實驗。現在不適合對著正式環境倉庫開高權限、無人值守改整個 monorepo、把 preview 寫進對外 SLA。

常見問題