TLDR DeepSeek Harness(dsh)是 DeepSeek AI 的開源代理執行時,約於 2026 年 8 月 13 日以 MIT 授權的開發者預覽版發布。它遵循「Model + Harness = Agent」原則,所有能力(模型、工具、工作階段、沙盒、迴圈、UI)皆以可替換的 Cordis 外掛實作。
在本機最快的執行方式是使用 npx @deepseek-ai/dsh web(需 Node.js ^22.19 或 ≥24),這會在 http://127.0.0.1:3080. 啟動一個 Web UI。你需提供 DeepSeek(或與 OpenAI 相容)的 API 金鑰與一個工作區。亦提供原始碼建置、桌面應用程式、Docker、Python SDK 與 Ollama 整合。若在使用 harness 的同時需要生產等級的多模型存取、可靠性與成本控制,建議經由 CometAPI 的統一 OpenAI 相容端點轉送請求。
關鍵要點
- DeepSeek Harness 不是模型——它是本機執行時/協調器,讓模型能操作檔案、Shell、工具與工作階段。
- 官方單行指令:
npx @deepseek-ai/dsh web→ 在 3080 埠開啟本機 Web UI。 - Node.js 版本要求嚴格:^22.19.0 或 ≥24.x。
- 支援 DeepSeek 官方模型(deepseek-v4-flash、deepseek-v4-pro)、自訂 OpenAI 相容閘道,以及透過外掛/Ollama 的本地模型。
- 架構完全外掛化(Cordis 核心);模式包含 Standard、Minimal、Code 與 Creator。
- 快速採用:發佈後數日內 GitHub 星標從數萬到 10 萬以上。
- 高階用戶建議:搭配 CometAPI(https://www.cometapi.com/)作為自訂供應商,以便存取 500+ 模型、節省 20–40% 成本,並僅需一把 API 金鑰。
- 一定使用隔離的工作區;代理可修改檔案並執行命令。
- 開發者預覽階段代表可能有破壞性變更——做近生產品驗時請鎖定版本。
2026 年的 DeepSeek Harness 是什麼,為何重要
DeepSeek Harness(dsh)是由 DeepSeek AI 開發的開源代理執行時。以 MIT 授權於開發者預覽階段發布,強調可組合性:所有能力——模型介面、工具、技能、工作階段、沙盒、儲存、代理迴圈、排程與 UI——皆作為 Cordis 外掛存在,可透過設定掛載、解除、替換或重組。實質上沒有需要打補丁的特權核心。
關鍵設計原則包括:
- Agent = Model + Harness.
- 可追溯的事件流,支援恢復、分支、搜尋與重播。
- 多種執行模式(標準全工具組、程式碼/協作模式、最小模式用於效能評測、創作者/實驗模式)。
- 優先本機的 Web UI 以供互動,另有無頭與 SDK 選項以便自動化。
官方資源:
- GitHub: https://github.com/deepseek-ai/deepseek-harness
- 產品/登陸頁: https://www.deepseek.com/harness/en/(及中文對應頁)
- 安裝指南頁與社群鏡像也重申相同核心指令。
重要術語說明:「本地部署」可能有兩層含義。本文所述的 DeepSeek Harness 在你的電腦上本地執行,但標準的
deepseek-harness專案會經由 API 連接至 DeepSeek V4-Pro 或 V4-Flash。這代表「harness、設定、工作階段、驗證與客戶端邏輯」可在本地,而模型推理通常由 DeepSeek 的 API 執行。若你需要真正離線、在自有 GPU 上載入權重做推理,那是另一種部署架構。
先決條件與系統需求
安裝前請確認:
- 作業系統:Windows 10+、macOS 10.15+、主流 Linux(x64 或 arm64)。Python SDK 另有限制(Linux x64/arm64 或 macOS 14+ arm64)。
- Node.js:主 Web UI 路徑所需。目標版本範圍為 ^22.19.0 || ≥24.0.0。以 node --version 檢查。此範圍外的奇數中繼版本不支援。
- 套件管理器:npm/npx(隨 Node 附帶)。原始碼建置需 pnpm(透過 npm install -g pnpm 安裝)。
- Git:原始碼複製所需。
- Python(選用):官方 Python SDK 需 3.10+。
- API 金鑰/端點:platform.deepseek.com 的 DeepSeek API 金鑰,或任何與 OpenAI 相容的端點 + 金鑰 + 模型名稱。
- 硬體:harness 本身不需 GPU——模型推理在遠端(或由你設定的本地供應商)進行。一般筆電資源足以支撐 Web UI 與協調作業。
- 網路:首次執行需下載套件;之後 UI 只需進行模型 API 呼叫。
- 工作區:準備一個隔離的目錄。代理可在設定的工作區內讀寫檔案並執行命令——請勿指向生產或個人資料,除非有保護措施。
需求來源:官方 README 與發佈後不久出現的多篇獨立安裝指南。
方法一:官方 npx 單行指令(適合多數使用者,建議)
這是最快且官方推薦的路徑。
- 確保 Node.js 版本符合要求。
- 開啟終端機並執行:
Bash
npx @deepseek-ai/dsh web
- 套件會下載(或使用快取)、啟動 Web UI 設定檔,並列印監聽位址——預設為 http://127.0.0.1:3080.
- 在瀏覽器開啟該 URL。若顯示開發者預覽通知,請接受。
- 首次使用,於(Settings → Models)配置模型供應商,貼上你的 API 金鑰,並選擇如 deepseek-v4-flash 或 deepseek-v4-pro。
- 選擇或建立一個工作區目錄。
- 開始發出任務。
若要使用不同埠:
Bash
npx @deepseek-ai/dsh web --port 8080
社群站點提供各平台單行指令,可同時確保已安裝 Node(Windows 上的 PowerShell 搭配 winget、macOS 上的 Homebrew、Debian/Ubuntu 上的 NodeSource 等)。
優點:除了 npm 快取外零永久安裝足跡;總是拉取近期發佈版本;上手最簡。缺點:首次需網路下載;不若原始碼路徑方便深入檢視或自訂建置。
方法二:從原始碼安裝與執行
當你想閱讀 Cordis 外掛、鎖定特定提交、開發自訂預設或貢獻時使用。
Bash
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web
同樣會在預設埠提供 Web UI。開發者預覽版本在提交之間可能不相容,請視為實驗性路徑。
方法三:桌面應用程式(無需安裝 Node)
社群與第三方的桌面封裝會打包執行時,讓使用者無需自行安裝 Node/pnpm:
- 基於 Tauri 的輕量客戶端,於啟動時引導內建 Node 執行環境並同步上游最新 harness。它們在 127.0.0.1:3080 上運作、資料留存本機,且註冊 dsh 指令。
- 基於 Electron 的封裝,包含鎖定的相依套件。
從各自的 GitHub Releases 頁面下載安裝程式(搜尋「deepseek-harness-desktop」)。首次啟動會下載核心元件(數百 MB)。對非技術使用者很方便,但並非 DeepSeek 官方產品——請檢視儲存庫與 SHA 雜湊。
方法四:Docker/容器化部署
社群提供的 Docker 映像與 compose 檔可在容器內執行 Web UI,常見搭配 nginx 進行 HTTPS 終止並支援任意 OpenAI 相容閘道。典型流程:
Bash
git clone <docker-repo>
cd <docker-repo>
cp .env.example .env # set API key / public host
docker compose up -d --build
適合 LAN 存取、伺服器,或不希望在主機安裝 Node 的環境。一些設定支援透過 settings.yaml 配置非 DeepSeek 供應商。
方法五:Python SDK(程式化/無頭使用)
適合無人值守代理或整合入 Python 流水線:
Bash
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
python -m pip install deepseek-harness-sdk
設定環境變數:
Bash
export DEEPSEEK_API_KEY=sk-your-key-here
# optional: export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1
# optional: export DSH_MODEL=deepseek-v4-flash
接著執行倉庫內的範例,或在你自己的程式中使用 DeepSeekHarness 類別,指向隔離的工作區與工作階段目錄。該 SDK 內建自身執行時,不需系統層的 Node.js。
方法六:Ollama 整合
Ollama 提供便利啟動器:
Bash
ollama launch dsh
# or with a specific model
ollama launch dsh --model deepseek-v4-flash:cloud
若使用的模型與 Ollama 雲端存取支援,則可使用網路搜尋與工具功能。
設定模型與供應商(含 CometAPI)
在 Web UI 前往「Settings → Models」。
- 官方 DeepSeek:貼上從 platform.deepseek.com 取得的金鑰。常見模型為 deepseek-v4-flash 與 deepseek-v4-pro。
- 型錄供應商(Anthropic、OpenAI 等):使用「Add provider」流程。
- 自訂/自託管/聚合器端點:選擇「Add a custom provider」。提供固定的 Provider ID、base URL、協定(通常為 openai-completions)、API 金鑰的環境引用或值,並至少一個模型 ID。
CometAPI 推薦(對許多近生產品流程強烈建議)CometAPI 是統一的 AI 基礎設施平台,透過單一 OpenAI 相容端點提供 500+ 模型(包含各種 DeepSeek 變體、GPT、Claude、Gemini、Grok 等):https://api.cometapi.com/v1.
搭配 DeepSeek Harness 的好處:
- 只需一把 API 金鑰,無須管理多家供應商憑證。
- 具競爭力的定價(據報相對多數原廠費率可省 20–40%)。
- 高可用(目標 99.9% SLA)、低中位延遲、隨用隨付。
- 便於 A/B 測試或成本最佳化,僅需更換模型 ID,harness 設定幾乎不變。
- 無痛相容:既有 OpenAI SDK 用法僅需更改 base_url 與金鑰即可。
在 harness 的自訂供應商表單中:
- Base URL:
https://api.cometapi.com/v1 - Protocol: openai-completions(或同等受支援選項)
- API key: 你的 CometAPI 金鑰
- Model ID: 來自 CometAPI 模型型錄的任一支援模型字串
此組合保留強大的本地代理執行時,同時提供彈性、具成本效益的多供應商模型存取。新用戶通常可獲得免費試用額度。文件: https://apidoc.cometapi.com/.
金鑰以僅寫入方式儲存(例如位於 $DSH_HOME/.credentials.yaml);UI 只顯示已遮蔽的描述。
DeepSeek Harness 疑難排解
找不到 DEEPSEEK_API_KEY
檢查:
echo $DEEPSEEK_API_KEY
Windows 上:
echo $env:DEEPSEEK_API_KEY
若為空,請重新配置。
400 reasoning_content 錯誤
通常指向推理生命週期處理不正確。
請確認你的應用在多輪思考/工具呼叫請求期間,能保留相關的助理推理資訊。
這正是 harness 主要設計要處理的核心問題之一。
內容長度錯誤(Context-length error)
檢查:
input tokens + max_tokens
文件記載的硬上限為:
1,048,576 tokens
請減少輸入上下文或要求的補全文字數。
串流期間工具呼叫格式異常
請勿假定串流分塊會依工具順序到達。
請依據 tool_call.index 聚合工具呼叫的增量(delta),符合 harness 合約的建議。
請求成本異常偏高
請檢查:
- thinking 模式
- 輸出長度
- 快取命中率
- 提示前綴穩定性
- 模型選擇
- 當前 API 定價
常見的簡易改善是將例行任務從 Pro 移至 Flash。
安裝與部署方法比較
資料綜合自官方文件與發佈後(2026 年 8 月)流通的安裝指南。
結論與後續步驟
DeepSeek Harness 透過 npx 單行指令幾乎零阻力地將設計乾淨、完全外掛化的代理執行時帶到本機。結合彈性的模型路由——尤其是透過如 CometAPI 這類統一平台——你可同時獲得現代代理式開發工作流程的威力,與成本、模型選擇與資料在地性的實務控制。
立刻開始:
npx @deepseek-ai/dsh web
配置 DeepSeek 或 CometAPI 金鑰,指向安全的工作區,探索 Standard 模式。接著可試試用 Minimal 模式做評測、以自訂供應商最佳化成本,或以 Python SDK 進行自動化。
如需最新官方指引,請優先參考 GitHub 儲存庫與說明文件。在使用 harness 進行多模型可靠性與定價優化時,也可探索 CometAPI 與其文件:https://apidoc.cometapi.com/.


