TLDR DeepSeek Harness（dsh）是 DeepSeek AI 的開源代理執行時（agent runtime），於 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 kernel）；模式包含 Standard、Minimal、Code 與 Creator。
- 快速採用：在發佈後數天內，GitHub star 從數萬到超過 10 萬不等。
- 強烈建議進階使用者：搭配 CometAPI（https://www.cometapi.com/）作為自訂供應商，以存取 500+ 模型、節省 20–40% 成本，並使用單一 API 金鑰。
- 一定要使用隔離的工作區；代理可修改檔案並執行指令。
- 開發者預覽狀態代表可能有破壞性變更——在類生產實驗中請釘選版本。
什麼是 DeepSeek Harness，以及它在 2026 年的重要性
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.
- 在瀏覽器開啟該網址。如顯示開發者預覽提示，請接受。
- 首次使用時，在「Settings → Models」貼上你的 API 金鑰並選擇模型，如 deepseek-v4-flash 或 deepseek-v4-pro。
- 選擇或建立一個工作區目錄。
- 開始下達任務。
若要使用不同埠：
Bash
npx @deepseek-ai/dsh web --port 8080
平台特定的一行安裝指令 可從社群網站取得（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 的環境。有些設定支援對非 DeepSeek 供應商使用自訂 settings.yaml。
方法五：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 主要設計來處理的核心問題之一。
內容長度錯誤
檢查：
input tokens + max_tokens
文件記載的硬上限為：
1,048,576 tokens
請縮減輸入脈絡或請求的輸出長度。
串流時工具呼叫格式異常
不要假設串流區塊會依工具順序到達。
請依照 tool_call.index 聚合工具呼叫增量，這也是 harness 合約所建議的方式。
請求成本意外偏高
檢查：
- thinking 模式
- 輸出長度
- 快取命中率
- 提示字首穩定性
- 模型選擇
- 目前 API 價格
一個簡單的改進通常是將例行任務從 Pro 移至 Flash。
安裝與部署方式比較
| Method | Ease of Use | Node Required | Best For | Persistence / Control | Typical Port / Access | Notes |
|---|---|---|---|---|---|---|
| npx one-liner | Highest | Yes | Quick trials, most users | Ephemeral (cache only) | 3080 (configurable) | Official recommended |
| Source (pnpm) | Medium | Yes | Development, plugins, pinning | Full source control | 3080 | Needs pnpm + build |
| Desktop (Tauri/Electron) | High | No (bundled) | Non-technical users | Local profiles & auto-update | 3080 (internal) | Community packages |
| Docker | Medium | No (container) | Servers, LAN, HTTPS | Container volumes | Custom / 443 | Community images |
| Python SDK | Medium | No (bundled) | Headless, automation, pipelines | Programmatic sessions | N/A (no UI by default) | Official SDK |
| Ollama launch | High | Optional | Local-model experiments | Ollama settings | 3080 | Integrates with Ollama |
資料綜整自官方文件與發佈後的指南（2026 年 8 月）。
結論與後續步驟
DeepSeek Harness 透過 npx 單行指令幾乎零摩擦地將一個設計清晰、完全外掛化的代理執行時帶到本地機器。結合彈性的模型路由——尤其是像 CometAPI 這類的統一平台——你能同時獲得現代代理式編碼工作流程的威力，以及對成本、模型選擇與資料在地性的實用控制。
立刻開始：
npx @deepseek-ai/dsh web
設定 DeepSeek 或 CometAPI 金鑰，指向安全的工作區，探索 Standard 模式。接著試試用於基準的 Minimal 模式、用於成本最佳化的自訂供應商，或用於自動化的 Python SDK。
如需最新官方說明請優先參考 GitHub 倉庫與說明文件。若要在使用 harness 的同時獲得多模型的可靠性與價格優勢，請探索 CometAPI 及其文件 https://apidoc.cometapi.com/.