如何安裝 DeepSeek Harness（dsh）：npx 單行指令、原始碼建置、無頭模式與外掛程式

To install Deep​Seek Harness (dsh), the open-source agent runtime Deep​Seek shipped on August 13, 2026, run npx @deepseek-ai/dsh web on a machine with Node.js 22.19 or newer. That one command downloads the 0.1.0-rc.6 preview, starts a local web UI at http://127.0.0.1:3080, and walks you through adding a model API key and a workspace on first launch. Two things to know before you start: dsh is not a model — it's the harness layer that connects a model to tools, files, and a terminal — and it's a developer preview, so expect breaking changes between releases. This guide covers both official install methods, headless mode, plugins, MCP, and the honest rough edges.

DeepSeek Harness 是什麼——以及它不是什麼

Deep​Seek 的內部公式，經資深研究員 Chen Deli 證實，即為 Model + Harness = Agent。模型是大腦；工具層（harness）則是將它轉化為能實際完成工作的所有一切：上下文與記憶管理、工具呼叫、任務規劃、檔案讀寫、終端機執行、錯誤回饋，以及判斷任務何時完成。Deep​Seek Harness 就是這一層，於 2026 年 8 月 13 日以 MIT 授權開源——同日 DeepSeek V4 Pro 0813 版本也上線於 Deep​Seek API。

兩個事實定義了安裝體驗。首先，這個架構是「一切都是外掛」，建立在 Cordis（一個 TypeScript 外掛容器）之上——所以你安裝的是小型核心加上一組提供模型適配器、工具、會話和 UI 的外掛。其次，目前 npm 上的版本是 0.1.0-rc.6，這是專案本身標示為開發者預覽版的候選版本：README 以大寫字母警告，破壞相容性的變更即將來臨。人氣是真的——上線 12 小時內獲得 50,000 顆 GitHub 星，約 42 小時內達到 100,000 顆，據中國科技媒體報導，到 8 月 16 日已超過 120,000 顆——但星數衡量的是關注度，不是穩定性。規劃安裝時要像規劃預覽版一樣：快速嘗試，丟掉也不可惜。

開始之前：實際的系統需求

唯一硬性要求是 Node.js。本專案目標引擎範圍為 ^22.19.0 || >=24.0.0——簡言之，就是 Node 22.19 或更新版本，或任何 Node 24.x。請用以下指令檢查你的版本：node --version。如果你用的是較舊的 Node，npx 安裝就會失敗或出現異常，而不會優雅地降級。

其他一切都比模型優先派所假設的更輕量：

• 模型 API 金鑰。 dsh 會執行真實模型；它需要一個用於 Deep​Seek 的 API 或任何你設定的 Open​AI 相容提供者的金鑰。你可以在首次啟動後於網頁 UI 中新增一個。

• pnpm — 僅供從原始碼建置時使用。請安裝一次，使用 npm install -g pnpm。

• 約 1 GB 的可用磁碟空間，用於 npm 套件、工作區與工作階段記錄，再加上本地模型所需的任何空間（dsh 本身不會執行權重）。

• 作業系統：npm 的方式在 Windows、macOS 和 Linux 上皆可使用。Python SDK 的支援範圍較窄（Linux x64/arm64、macOS 14+ arm64——沒有原生 Windows），詳見下方說明。

你不需要 GPU。該 harness 僅負責編排；模型透過 API 遠端執行。

方法 1 — npx 單行指令（推薦給幾乎所有人）

官方快速入門就是一個指令，而且確實就是一個指令：

npx @deepseek-ai/dsh web

npx fetches the @deepseek-ai/dsh package (current version 0.1.0-rc.6), installs it into npm's cache, and starts the Web UI profile. Watch the output for the line that tells you it's listening — by default that is http://127.0.0.1:3080. Open it in your browser. Note the 127.0.0.1 loopback address: the UI binds to localhost only, which is the right default for a tool that can read and write files in your workspace — it also means you won't casually expose it on your network.

首次啟動正好有兩個設定步驟：

• 新增模型金鑰。設定 → 模型 → 輸入你的 API 金鑰。它會儲存在$DSH_HOME/.credentials.yaml，且之後不會以明文顯示。在預設安裝中 DSH_HOME 預設為 ~/.dsh。

• 選擇工作區。新增 dsh 允許工作的專案目錄。在兩個步驟完成前，輸入會保持鎖定。

接著送出第一個任務——一個好的冒煙測試是「總結這個儲存庫並識別其主要套件。」如果摘要回傳，而且執行追蹤中出現工具呼叫，你的安裝就正常運作。

方法 2 — 從原始碼建置

偏好從儲存庫執行？官方路徑是：

git clone https://github.com/deepseek-ai/deepseek-harness.git

cd deepseek-harness

pnpm install

pnpm run build

pnpm dsh web

你需要 pnpm 才能執行此操作（貢獻者鎖定 pnpm 11.7.0）。請選擇源碼建置：當你想執行最新的main 而不是已發佈的候選版本、當你計劃閱讀或修改測試框架，或當你想從 repo 的apps/cli/config/agent-presets/ 目錄建立自訂預設時。對其他人而言，npx 路線是相同的軟體，但更簡單——源碼建置並不會解鎖 npm 套件所缺少的功能。

三個設定檔：web、headless 和 tui

dsh 提供三種執行設定檔，使用哪一種取決於工作在哪裡執行：

• web（預設）— 連接埠 3080 上的完整瀏覽器 UI。這就是 npx @deepseek-ai/dsh web 所啟動的內容，也是大多數人會首先安裝的設定檔。

• headless — 單一任務，然後結束。 dsh --profile headless "run the test suite and report failures" 會啟動一個工作階段，執行任務，寫入結果，然後終止。headless 執行環境明確是單一任務流程：你無法在執行中途插入後續任務，修正則是對同一個工作區重新執行。這就是要整合到腳本和 CI 的設定檔。

• tui — 用於鍵盤驅動工作階段的終端機介面：dsh --profile tui.

三者共用相同的配置（~/.dsh/profiles/<name>/）與相同的插件系統，因此將任務從 Web UI 移到無頭模式只是換個指令，而非重新安裝。

新增外掛程式

外掛程式管理是第一等的 CLI 指令，而非就地編輯的操作：

npx @deepseek-ai/dsh plugin --profile web add <來源>

來源可以是 npm 套件名稱、GitHub 儲存庫（github:user/repo）、tarball，或本機資料夾。最值得優先安裝的是官方外掛市集，它能將外掛探索變成一個 UI：

npx @deepseek-ai/dsh plugin --profile web add dshmarket

然後重新啟動 Web 服務，並開啟 設定 → 外掛程式市集，即可從目錄中瀏覽並一鍵安裝。有兩個容易讓人搞混的規則：外掛程式套件會在設定檔啟動時掛載，因此新加入的外掛程式需要重新啟動 dsh web；而單純的 npm install並不會將外掛程式註冊到設定檔中——你必須使用 dsh plugin。這個生態系雖然年輕，但並非空無一物：由社群維護的 awesome-dsh-plugin 清單已經收錄了數百個外掛程式，涵蓋 UI、技能、工具、提供者及通知等類別。

MCP、四個預設與軌跡重播

過了基本安裝階段之後，有三個功能很重要：

MCP。dsh 通過內建的 @deepseek-ai/dsh-mcp-client 外掛程式來使用模型上下文協議。目前這是通過檔案配置的，而非在 UI 中：你編輯 ~/.dsh/profiles/web/cordis.patch.yml（或專案本地的 patch）並宣告每個伺服器的傳輸方式——stdio用於本機命令，例如 npx @playwright/mcp@latest、streamable-http 用於遠端 URL。它能運作，但這是預覽版中最不完善的部分；預期會有不穩定情況，且沒有 GUI 可以切換伺服器。

預設。dsh 每個工作階段會載入四個代理預設之一，而每個都是不同的取捨：

• Standard — 完整的工具集：檔案編輯、shell、檔案與網路檢索、技能、規劃、子代理、工作流程。日常使用的預設。

• PTC（程式化工具呼叫）— 標準版加上 Code Mode SDK，讓模型可以撰寫 TypeScript 程式來編排多輪工具呼叫。更強大，副作用也更多。

• 極簡 — 僅需 bash 和一個檔案編輯器，除此之外什麼都不用。專為模型基準測試和最小重現而建；DeepSeek V4 Flash API 文件在揭露自家 agent 分數時所引用的模式，就是運行在「Deep​Seek Harness minimal mode」上。

• Creation — 一個執行時期遊樂場：在記憶體中檢查並載入 Cordis 外掛程式，進行實驗，並將可行的組合鞏固成新的預設。

軌跡重播。每次執行都會寫入一份僅可追加的會話日誌——系統提示、推理過程、工具呼叫及其結果、子代理排程。軌跡檢視可讓您依來源檢查、繼續、分叉、搜尋及重播執行。這就是代理工作的除錯器：當任務失敗時，您不會重新執行並寄望於運氣；您會重播失敗的軌跡，在出錯的步驟將其分叉，並在不丟棄原始軌跡的情況下測試修正。

Python SDK 選項

如果你比較想用 Python 而不是瀏覽器來驅動 harness，這裡有官方 SDK：pip install deepseek-harness-sdk。它整合了 dsh runtime（pip wheel 內含 Node runtime，所以無需另外安裝 Node），用法是一個 context manager：建立 Deep​SeekHarness 實例，然後呼叫 run("task")。它會繼承標準環境變數，例如 DEEPSEEK_API_KEY 和 DEEPSEEK_BASE_URL，因此更換 provider 只是設定變更。缺點是：它僅支援 Python 3.10+ 及 Linux x64/arm64 與 macOS 14+ arm64——沒有原生 Windows wheel，如果你的主機是 Windows，這確實是個缺口。在 Windows 上，請沿用 npm 方案。

將 dsh 指向您付費使用的模型

dsh 需要一個模型 API 金鑰，而且它刻意與供應商無關：設定 → 模型 接受具有 Open​AI 相容基礎 URL 的自訂供應商（在 settings.yaml中，即 api: openai-completions、baseURL，以及一個 models清單）。預設是 Deep​Seek 自己的 API；自訂供應商正是路由閘道派上用場的地方。

OrcaRouter is an Open​AI-compatible endpoint that passes Deep​Seek's list price through with zero markup — https://api.orcarouter.ai/v1. That gives you DeepSeek V4 Flash (deepseek/deepseek-v4-flash-0731, about $0.15 per million input tokens and $0.29 per million output) and DeepSeek V4 Pro (about $0.44/$0.88), both at provider list price with no token markup, plus automatic failover if a provider wobbles. For dsh, the practical win is that you can run the cheap V4 Flash for the bulk of everyday agent tasks and switch the same harness to V4 Pro for the hard passes — one key, one base URL, and the swap is a model name in the settings, not a reinstall.

先釐清界線：OrcaRouter 託管模型的 dsh 呼叫；它本身並不託管 dsh。dsh 是本機代理執行環境，你在自己的機器上執行它。

這份指南在哪些地方對你不適用——預覽版的誠實問題

只告訴你該輸入什麼的安裝教學，只算做了一半的工作。以下是預覽版目前會出錯的地方，免得你在凌晨兩點才發現：

• 破壞性變更是一項承諾，而非警告。 你目前使用的是 0.1.0-rc.6。設定鍵、外掛程式 API 與預設格式都可能隨時變動，恕不另行通知。請將 ~/.dsh 視為可丟棄的狀態——更新失敗的代價就是重新安裝，而在這個階段之所以可以接受，是因為安裝只需一條指令。

• 你並不需要 dsh 就能將 Deep​Seek 模型用作 agent。如果你現在的唯一目標是在 agent 中使用 DeepSeek V4 Flash 或 DeepSeek V4 Pro，Deep​Seek 的 Anthro​pic 相容端點已經能在 Claude Code 和其他 agent 工具中運作，無需任何新軟體。dsh 是第一方選項，並非必要條件。先略過此安裝，直到你確實需要原生 harness。

• MCP 採用檔案設定，且偶爾會不穩定。沒有圖形介面，也沒有個別伺服器的啟動/停止開關，實測報告指出會間歇性故障。如果你的工作流程依賴 MCP 伺服器，請預留時間進行 YAML 除錯。

• 外掛程式信任是一項安全決策。第三方外掛程式會在工具框架的核心程序中執行，安裝時沒有簽章或來源驗證。只安裝你讀過或來自可信來源的外掛程式，並在將它們用於實際工作之前，先在一次性工作區中測試。danger-full-access沙盒設定檔可以修改任何可見檔案——請僅用於一次性簽出的工作副本。

• 預覽版本中存在已知錯誤。 bash 迴圈卡住是已記錄的失敗模式（中斷後重試），而長時間執行工作階段的相關行為仍在調整中。

• 非官方桌面版本是個陷阱。一些社群包裝程式將 dsh 打包成一鍵安裝的桌面應用程式，並附帶 Node 執行環境。它們可以運作，但未經簽章，且並非由 Deep​Seek 維護；如果你使用這類工具，就等於將一個握有你檔案系統權限的工具託付給第三方。

• 若您需要生產穩定性，請等待非 rc 版本釋出。 這個 harness 功能強大但尚未成熟。就生產級 agent 技術棧而言，在 dsh 達到穩定版本之前，成熟的、經過實戰考驗的 harness — 或 Anthro​pic 相容的 endpoint 路線 — 才是站得住腳的選擇。

底線

在任何配備 Node 22.19+ 的機器上，安裝 Deep​Seek Harness 確實是只需一行指令的事：npx @deepseek-ai/dsh web，新增模型金鑰和工作區，送出測試任務。選擇原始碼建置，只在您想修改或追蹤main；若用於腳本，請使用 headless；請及早新增外掛市場；並將 MCP 視為開發中的功能。誠實的警告與專案在其 README 中印出的內容相同：這是 0.1.0-rc 預覽版，在邁向穩定版的路上會破壞一些東西。如果您想看看 Deep​Seek 正在將代理層帶往何方，這是個正確的取捨——而它所執行的模型 DeepSeek V4 Flash 和 DeepSeek V4 Pro，目前可透過 OrcaRouter 以定價取得，已準備好在安裝完成後驅動 harness。