DeepSeek Harness（指令名 dsh，npm 套件名 @deepseek-ai/dsh）是 DeepSeek 官方開源的 Agent 執行環境，MIT 授權，設計口號是「Everything is a Plugin」。做完這篇你會得到：一個在本機 http://127.0.0.1:3080 跑起來的 Web GUI、一個接好的模型、一個選定的工作區，以及你在終端機路線上跑通的一次性任務。兩條路共用同一套設定與憑證。
動手做完大約 20 分鐘，其中大部分是等第一次下載套件。
適用平台
官方 README 只寫「Install Node.js, then run npx @deepseek-ai/dsh web」，沒有列出作業系統矩陣，也沒有在 npm 套件裡宣告 Node 版本下限。實務上：
| 路線 | 需求 |
|---|---|
| npm 路線（本文主線） | 有 Node.js（含 npm 與 npx）即可；官方未指定版本，裝 nodejs.org 的 LTS 版最穩 |
| 原始碼路線 | Git、pnpm，以及能跑 pnpm run build 的 Node 環境 |
官方 README 同時明講：這個專案處於 developer preview，快速迭代中，會有破壞性變更；執行前要先看過倉庫裡的 SAFETY.md。
來源：github.com/deepseek-ai/deepseek-harness（README、apps/cli/README.md、apps/cli/reference/README.md、docs/user/guide/index.md、docs/user/guide/providers.md、SAFETY.md），文件站 deepseek-harness.github.io/deepseek-harness/。
前置需求
- Node.js。不確定自己有沒有，下一個步驟會驗。
- 一把模型金鑰：DeepSeek 平台（
platform.deepseek.com）的 API Key，或其他供應商的。先讀 環境變數與 .env 與 五分鐘設置你的 LLM 開發環境，本文範例金鑰一律是sk-xxxxxxxx這種佔位符。不要把金鑰貼進任何對話視窗，也不要 commit 進 git。 - 一個要讓 Agent 操作的專案目錄。官方說明：你執行
dsh時所在的目錄就是預設工作區根目錄。 - 你會用 Terminal（終端機）。終端機路線整條都在 CLI（命令列介面） 裡。
- 一份心理準備：官方
SAFETY.md說這是實驗性軟體、沒有做過安全稽核，它會執行模型產生的程式碼與指令、會載入第三方插件、會存取你給它的網路／程序／憑證／檔案。官方建議以最小權限執行、優先用一次性 VM 或容器、對它能碰到的檔案先備份。
步驟
步驟一：確認 Node.js 與 npx 在
node --version
npx --version
預期輸出：兩行版本號，形如 v22.x.x 與 10.x.x。有版號就能走 npm 路線。
失敗長這樣：command not found: node —— 到 nodejs.org 裝 LTS 版，裝完開一個新的終端機視窗再試一次（舊視窗讀不到新加進 PATH 與路徑 的指令）。
步驟二：一行啟動 Web GUI
cd 到你要讓 Agent 操作的專案目錄，然後：
npx @deepseek-ai/dsh web
預期輸出：第一次執行會先下載套件，畫面上會出現 npm／npx 的進度訊息（這一段可能花幾十秒到幾分鐘，看你的網路）。之後 dsh 啟動，官方文件說它預設在 http://127.0.0.1:3080 提供 Web UI；在本機啟動時，它會在整棵插件樹完成載入後才打開預設瀏覽器，並在交遞前印出一行：
dsh web: opening the default browser; pass --no-open to disable
瀏覽器打開後你會看到 DeepSeek Harness 的介面。這個終端機視窗要一直開著 —— 它就是伺服器本身，關掉它就等於關掉 Web GUI。
失敗長這樣：如果作業系統的瀏覽器交遞失敗，官方說明 stderr 會印出原因、伺服器繼續跑，並把網址告訴你讓你手動開。如果你透過 SSH（安全外殼） 啟動（環境裡有 SSH_CONNECTION 或 SSH_TTY），它不會開瀏覽器，只印出主機網址 —— 這是刻意的，因為轉發位址由你的 SSH 客戶端或編輯器持有。
步驟三：設定模型
在瀏覽器裡打開 Settings → Models。DeepSeek 那張卡片只有一個 API key 欄位：貼上你的金鑰、按儲存。
預期輸出：官方說明金鑰是 write-only —— 存好之後頁面拿到的是遮罩過的描述，不會再顯示原文；金鑰本身存進 $DSH_HOME/.credentials.yaml（預設 ~/.dsh），設定檔裡只留一個憑證引用。存好後不需要重啟伺服器，模型路線立即可用。
要接其他供應商：按 Add model provider，官方說內建清單包含 anthropic、openai、moonshotai（Kimi）、zai（GLM）這類 provider id，選一個、填金鑰、儲存。要接中繼站、公司閘道或自架伺服器，把卡片切到 Custom model API，填一個小寫的 Provider ID、base URL、API 協定（三種：OpenAI Chat Completions、OpenAI Responses、Anthropic Messages）、憑證與至少一個模型。官方提醒 Provider ID 不可改（請求、已存 session、模型預設與憑證引用都用它），要改名只能新增一個再刪掉舊的。注意 OAuth 登入型的供應商（例如 Codex）目前不支援。
步驟四：選工作區
回到主畫面，按 Choose workspace，加入你在步驟二啟動 dsh 的那個專案目錄，然後選取它。
預期輸出：官方文件把這條規則寫得很明白 —— 在你選定工作區之前，session 的輸入框是不可用的。所以「輸入框灰掉、打不了字」不是壞掉，是還沒選工作區。選好之後輸入框就能用。
步驟五：跑第一個任務
開一個 session，官方指南給的第一句任務是：
Summarize this repository and identify its main packages.
預期輸出：Agent 開始讀檔、搜尋、可能執行指令；畫面上看得到它的動作與工具呼叫。官方說明：在目前權限策略下需要核准的操作，Web UI 會先問你。完成後你會看到一段針對這個倉庫的總結。
步驟六：走終端機路線（headless）
同一套設定與憑證，也可以完全不用瀏覽器。官方 CLI 文件列的模式是 dsh --profile headless "job"：跑一個全新且會持久化的 session、印出最終答案、然後結束。
cd /path/to/your/project
npx @deepseek-ai/dsh --profile headless "Summarize this repository and identify its main packages."
預期輸出（官方 CLI reference 寫得很具體，可以直接對照）：
- stdout 只印最終答案文字
- 模型的推理過程以
dsh: reasoning:標題串流到 stderr（所以你想把答案導向檔案時，不會混進推理文字） - 結束時：任務完成 exit code 是
0，其他情況是1 - 這個 profile 不會開任何 listening port，也不掛瀏覽器、HTTP 伺服器或 Web runtime
第一次跑 headless 時，官方說明該 profile 會自動從出貨範本初始化，所以你會看到它建立設定檔的過程。
步驟七：確認版本與整棵設定樹
npx @deepseek-ai/dsh --version
npx @deepseek-ai/dsh --profile web --dump-config
預期輸出：--version 印出 launcher 的版本號（官方說明 -V／--version 要在「app 參數邊界」之前才印 launcher 版本，所以照上面這樣寫就對）。--dump-config 印出你這台機器上實際組合出來的整棵插件設定樹，每一行都附註是哪個檔案提供的、以及哪些 overlay 改過它；它只印不啟動（官方說明 dump 不會執行 app 的命令列 provider，而且會順手把缺的 profile 檔初始化出來）。想只看 bundle 層，用 --dump-default-config。
步驟八：知道幾個常用旗標與它的界線
Web profile 的旗標（官方 CLI reference 的表格）：--host、--port、可重複的 --trusted-host、--no-open。
npx @deepseek-ai/dsh web --port 8080 --no-open
預期輸出：伺服器在你指定的 port 上提供服務，且不會自動開瀏覽器 —— 你自己到 http://127.0.0.1:8080 開它。
界線也值得先知道：官方明講 CLI 刻意不支援 --host 0.0.0.0，那樣啟動會以 usage error 結束。另外 dsh --help 印的是 launcher 自己的說明，dsh --profile web --help 印的是 Web app 的旗標而且不啟動任何東西 —— 官方建議用後者查旗標。
想從原始碼跑（例如你要改插件）：
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web
預期輸出：pnpm run build 準備好倉庫的產物，pnpm dsh web 用這些產物啟動（官方說明這條指令不會重新 build）。
怎麼確認你裝對了
兩條指令，一條查版本、一條端到端：
npx @deepseek-ai/dsh --version
npx @deepseek-ai/dsh --profile headless "Reply with exactly: DSH_OK"
echo $?
預期輸出：第一行是版號。第二行的 stdout 應該只有 DSH_OK 這幾個字（推理文字走 stderr）。第三行印出 0，代表官方定義的「任務完成」退出碼。三個都對，就代表安裝、模型設定、憑證解析與 agent 迴圈整條鏈路都是通的。
Web GUI 那半邊的驗證不需要指令：http://127.0.0.1:3080 打得開、Settings → Models 裡看得到你加的供應商、選完工作區後輸入框可以打字。
常見錯誤與修法
前四條是官方 docs/user/guide/providers.md 的 troubleshooting 清單原文對應，後面幾條來自 CLI reference：
| 症狀 | 原因 | 修法 |
|---|---|---|
MISSING_CREDENTIAL | 憑證引用指向的金鑰不存在 | 到 Models 頁面存一次金鑰，或把被引用的那個環境變數供給它。官方特別說明：引用錯時它會明確失敗，而不是拿環境裡不相干的金鑰將錯就錯 |
UNKNOWN_MODEL | 選到一個沒設定的模型 | 改選已設定的模型，或把缺的模型加進那個自訂供應商 |
| 「Fetch available models」回 401 | 金鑰不對 | 檢查金鑰。官方說明模型探索打的是 OpenAI 相容的 GET /models；不支援這個端點的閘道要手動輸入模型 id |
| 金鑰與網址都對，閘道卻拒絕所有請求 | 它的請求格式跟 OpenAI 不一樣 | 官方給的第一個修法是設定 compat.supportsDeveloperRole: false 與 compat.maxTokensField: max_tokens；只有推理模型失敗時，前者就是答案 |
| 輸入框灰掉、打不了字 | 還沒選工作區 | 按 Choose workspace，加入你啟動 dsh 的那個目錄並選取 |
| 輸入框顯示 Select model 且不讓你送 | 先前存的預設模型指向一個已被刪掉的供應商 | 從模型選單重選一個模型 |
| 啟動失敗並直接 exit 1 | 設定解析、schema、plugin 開機失敗 | 官方說明最後會有一行 Full diagnostics:，指名一個 startup-<timestamp>-<uuid>.log，位置在 $DSH_HOME/logs/（預設 ~/.dsh/logs/）。先讀那個檔 |
--host 0.0.0.0 直接被拒 | 官方刻意不支援對外綁定 | 這是有意的安全設計，不是 bug。要在別的機器上用，走 SSH port forwarding |
| SSH 環境下瀏覽器沒自動開 | 有 SSH_CONNECTION／SSH_TTY 時官方會略過瀏覽器交遞 | 正常行為，它仍會印出主機網址；本機要關掉自動開啟用 --no-open |
改了 cordis.patch.yml 但沒生效 | 沒開 HMR 時設定變更要重啟 | 官方說明適配器在下一次請求時會重讀該檔；Web profile 的檔案在 $DSH_HOME/profiles/web/cordis.patch.yml，瀏覽器與伺服器同機時也可以用 Settings 標頭的 Open configuration file 直接開 |
最後重申一次官方 SAFETY.md 的定性：沙箱、核准提示與權限控制可以降低風險，但不保證隔離，也不能保護它本來就被允許存取的資源；不要把 DeepSeek Harness 當成不可信工作負載的唯一安全控制。要跑不確定的東西，就用一次性 VM 或容器。
下一步
- 想理解它的架構為什麼值得看：DeepSeek Harness 深度研究 與 DeepSeek Harness 架構深潛
- 想搞懂名詞：Harness（執行環境／框架）、AI Agent（代理）、Tool Call（工具呼叫）、Sandbox（沙箱）、Context Window（上下文視窗）
- 想比對同類型的終端機 Agent：安裝 Claude Code、安裝 OpenAI Codex CLI
- 想在 IDE 而不是終端機裡工作：安裝 Cursor、安裝 Trae
- 金鑰與成本管理：API Key、團隊 AI 成本估算、三層 LLM API 矩陣
- 安全邊界：Prompt Injection（提示詞注入）、AI 安全與紅隊測試、企業資料安全基礎