為什麼是 DeepSeek Harness ?

8 月 13 日 DeepSeek 在釋出 V4 Pro 的同一天，順手把自家的 agent harness 開源了，MIT 授權，沒幾天已經上看 21萬顆星星，現在已經是 GitHub 史上成長最快的專案之一。它叫 DeepSeek Harness，國際社群簡稱它為 dsh。

AI 代理人三部曲選它當執行層的實戰主角，理由不是星數，是三個跟本系列直接相關的特質。
模型無關
官方支援約四十家模型供應商，而且任何 OpenAI 相容端點都能接，也就是說 Day 18 我在地端 AI 伺服器部署的閘道可以直接連上去。

外掛式架構
官方口號是 everything is a plugin，工具、記憶、模型供應商、UI 全部都可以是外掛，這給了許多用戶很高的自由度，你可以像拼拼圖一樣，採用不同元件，把真正屬於自己想要用的 AI 代理人拼湊起來，這種設計對「想換掉某個環節」的地端玩家特別友善。

它有一個本地 Web UI
不輸Open WebUI的樣式，要用cli也可以，非常方便。對不想只用終端機的使用者來說是門檻上的差異。

順便，我的機器上正好常駐著一款 DeepSeek V4 Flash（ds4-server），一個 DeepSeek 出的 harness 配一款 DeepSeek 出的模型，是不是天作之合呢? 還是該用 vllm 來跑比較好? 今天順手比較看看

第一節：安裝與接上閘道

安裝是一行 npm，它是一個一般的 Node 套件：

npm i @deepseek-ai/dsh

版本走得很快，而且 npm 上的標籤曾經與直覺相反。本機這一款是 8 月 20 日裝的 0.1.0-rc.8，當時 latest 還停在 rc.7、rc.8 掛在 next，@latest 會裝到舊的。今天更新看看，latest 與 next 都已經是 0.1.1-rc.2，另外有一條 alpha 在 0.1.2-alpha.4。要重現本篇的數字會需要指定版號。

啟動的入口是 profile，不是指令：dsh --profile headless "工作內容" 跑一次無人值守的任務，dsh web 是 --profile web 的別名。設定檔在 $DSH_HOME/settings.yaml，我們不填任何雲端金鑰，直接填 Day 18 閘道的地端 IP 位址。這裡有一個文件不會告訴你、但一裝上去就會碰到的現實，內建的 llm-deepseek catalog 只能瞄準 DeepSeek 端點，要接一個 Qwen 等其他模型，必須走泛用的 llm-pi-ai adapter 自訂供應商：

llm-pi-ai:
  providers:
    gateway:
      displayName: Day 18 gateway (LiteLLM :8100)
      api: openai-completions
      baseURL: http://127.0.0.1:8100/v1
      apiKeyEnv: GB10_PROXY_KEY
      defaultContextWindow: 65536
      defaultMaxTokens: 16384
      compat:
        thinkingFormat: qwen
        supportsReasoningEffort: false
      models:
        - id: qwen3.8-27b
          name: Qwen3.8-27B-FP8 (single node vLLM :8004, via LiteLLM :8100)
          contextWindow: 65536
          maxTokens: 16384

agent-default-model:
  provider: gateway
  model: qwen3.8-27b

compat 這一節也要照著安裝的版本寫，不要照文件站寫的，官網描述的 supportsDeveloperRole 與 maxTokensField 在 rc.8 的 schema 裡根本不存在，只有 thinkingFormat 與 supportsReasoningEffort 兩個鍵。另外 $DSH_HOME/settings.yaml 疊在入口設定之上，DEEPSEEK_BASE_URL 這個環境變數會被它靜默蓋掉，要改端點只能改這個檔。

接通本身是一次就成，第一句話就回來了。但是「一次接通」跟「零問題」是兩件事，量測期間浮出三個不對稱，全部有證據：

一、dsh 送的是 max_completion_tokens，不是 max_tokens，所以 Day 18 閘道的輸出上限對它完全無效。 閘道那支 clamp_max_tokens.py 只讀 max_tokens，dsh 走 llm-pi-ai 時送的是新欄位名，於是我在閘道上寫的天花板一次都沒生效。用一個上限 4096 的別名對打驗證：送 max_tokens: 6000 被改寫成 4096（[clamp] max_tokens 6000 -> 4096，finish_reason 剛好停在 4096），送 max_completion_tokens: 6000 沒有任何 clamp 紀錄，請求一路生成過 4096 才停。這不是 dsh 的錯，它用的是比較新的欄位，錯的是「閘道上的用量護欄」這個假設，一個只讀舊欄位的護欄，客戶端不必刻意繞就繞過去了。

二、同一個 harness 對不同 provider 送不同的欄位名。 第三節把它接回 DeepSeek 自家模型、走內建 llm-deepseek adapter 時，閘道記到的又是 max_tokens: 16384。所以「dsh 會不會被我的 clamp 擋住」沒有單一答案，取決於你用哪一條 adapter。

三、上下文壓縮是被 HTTP 400 打回來才觸發的，不是預先算出來的。 dsh 的 compaction 門檻是宣告視窗的 0.8，我照引擎宣告 65536，門檻是 52,429。實際發生的是第 12 輪的請求直接被 vLLM 擋掉：

This model's maximum context length is 65536 tokens. However, you requested
16384 output tokens and your prompt contains at least 49153 input tokens,
for a total of at least 65537 tokens.

49,153 + 16,384 = 65,537，超出一個 token。輸入 49,153 遠低於 52,429 的門檻，所以主動壓縮不會啟動，真正的牆是視窗減掉輸出保留量。好消息是 harness 接得住，它把這個 400 當成 agent/request-error，回頭做一次 tool result 剪枝加一次摘要，然後從摘要繼續，任務照樣完成。壞消息是這一輪的 prefill 白付了，而且如果換一個不會回這種錯誤的後端，行為就不好說，用戶要除錯或處理也會需要費一點心思。

接通後跑 Day 19 那個同樣的真實任務（閱讀 可阻擋惡意連結與廣告的瀏覽器外掛程式 just-ad-blocker的 README 與 src 下主要原始檔，找出未處理的錯誤路徑，整理成 GitHub issue 草稿），同一份 54 檔工作區副本，同一款 Qwen3.8-27B-FP8，同一支閘道記錄器，同一套差分渲染 chat template 的拆解方法：

兩個交叉驗證跟 Day 19 一樣成立，總輸入 473,207 正好等於 vLLM 自己的 prefix_cache_queries_total，命中率 388,864 ÷ 473,207 = 82.2% 也跟引擎日誌那行 Prefix cache hit rate: 82.2% 是 match 的。

最值得看的一列是最上面兩列。
兩個 harness 每輪原樣重送的固定前綴幾乎一樣大，7,631 對 7,593，只差 38 個 token，但組成正好相反。dsh 的系統提示只有 837 token 卻給模型 25 個工具、schema 吃掉 6,742。opencode 的系統提示 2,255 token 而工具只有 10 個、schema 5,286。一個把話講在系統提示裡，一個把話講在工具描述裡，加起來卻收斂到同一個等級。這不是巧合能解釋的，比較像是「要讓一款通用模型穩定地當 coding agent，開場白就是需要這麼多字」。

其餘的差距則是顯著的，兩者比較起來，dsh 少用 33% 的輸入 token、少用 45% 的輸出 token、少跑四個回合、快了 52 分鐘，而兩邊都真的把任務做完並存了檔。dsh 的產出是 258 行、分 A 網路 / B 金鑰 / C 打包三類共 12 條，外加 3 條順手發現的執行期問題，每條都標了檔名行號與嚴重度。命中率高 8.7 個百分點也有具體原因，dsh 的壓縮摘要呼叫會原樣重放整段對話前綴再附上壓縮指令，刻意去吃 KV 快取，而不是另起一個乾淨的摘要請求。

這張表就是「harness 值 8.6 分」那句話的地端版本。同一款模型、同一句任務、同一個閘道，換一個迴圈就少花三分之一的 token 和一半的時間。

第二節：外掛式架構到底長什麼樣

先講一件對「everything is a plugin」的實測校正，dsh 的外掛沒有官方定義的「類別」，它是一個組合出來的扁平樹。--dump-default-config 把 headless profile 的組合結果吐出來，是 81 個 loader entry，每一個都是 id + 套件名 + 選填 config，由 bundle（dsh-base、dsh-headless）依序疊，再疊 profile 自己的 cordis.patch.yml。所謂類別其實是套件命名的家族：dsh-tool-* 是工具、dsh-llm-* 是模型供應商、dsh-sandbox-* 與 dsh-*-sandbox 是沙箱、dsh-session-* 是會話與稽核、dsh-client-ui-* 是 Web UI、dsh-storage-* 是非會話儲存、dsh-mcp-client 是 MCP 接口。安裝目錄底下總共 197 個 @deepseek-ai/* 套件，headless 用掉其中 81 個。

掛載一個自己的外掛只要兩件事，把套件放進 profile 的 node_modules（我用 symlink），然後在 cordis.patch.yml 裡 insert 三行。我實際裝了三個來看它的邊界。

一個工具外掛
這讓 AI agent 能讀我 NAS 上的模型庫資料，整支外掛就是一次 ctx.tools.register(defineTool({...}))，registry 會自己把 schema 餵進系統提示的組裝，所以工具外掛完全不必碰提示詞。掛上去之後 agent 手上從 25 個工具變成 26 個，它自己就會用：

我用 nas_models 看了 NAS 模型庫（/mnt/nas/AIModels）最上層的 12 個目錄
（datasets、ds4、FastVideo、gguf、hf-cache、huggingface、lightx2v、logs、
MiniMax、ollama、rag-docs、vllm），再進 gguf 目錄看到 gpt-oss-120b-mxfp4。

寫這種外掛有一個必須自己守的紀律，根目錄要寫在 config 裡，不能當成參數讓模型傳。模型只給相對子路徑，外掛負責解析並拒絕任何逃出根目錄的路徑，一個接受絕對路徑的工具，等於用「nas_models」這個名字把整個檔案系統交出去。

一個記憶外掛
先說 dsh 本身的記憶機制，因為它跟大家以為的不一樣，headless bundle 裡沒有任何跨 session 的記憶。它持久化的是 session 本身，dsh-session-persistence-jsonl 把每一個事件寫成 $DSH_HOME/sessions/<工作區>/<session-id>/session.jsonl.zstd，這有點像是逐字稿，並不是記憶。唯一會自己跨越 session 邊界的是 AGENTS.md，而那是我們人類寫 的AI 代理人定義檔案。真正的接縫是 storage hub（ctx.storage 加 dsh-storage-domain 加 json 或 sqlite backend），但 base bundle 一個都沒掛上去。

所以我把接縫補起來，一支外掛，一個 JSON 檔，兩個工具（remember / forget），加一段 runtime context 注入。實測跨 session 生效，第二個 session 沒有呼叫任何工具就先答出來：

根據先前 session 存下的記憶：本機的 GGUF 權重放在 NAS 的 AIModels/gguf 底下，
目前包含 gpt-oss-120b-mxfp4。

寫的時候有一個選擇值得記錄，注入要走 systemPrompt.context() 而不是 section()。section 會併進穩定的系統提示，也就是上面那塊每輪重送 7,631 token 的固定前綴，改一條記憶就會讓之後每一輪、每一個 session 的快取前綴失效。context 是接在保留歷史之後的動態脈絡，寫一條記憶只付新增的位元組。

跟 ds4 的磁碟 KV 是完全不同的兩件事。
dsh 的記憶檔這一刻是 229 bytes 的 JSON，內容是一句中文事實，ds4-server 的 /var/lib/ds4-kv 是 37 GB 的 .kv blob，由 AI 推論引擎把算過的 KV cache 落到磁碟，重開機後同樣的前綴不用再算一次。一個是 agent 記得什麼，一個是引擎算過什麼，層次不同、生命週期不同，也不會互相取代。

一個模型供應商外掛
這是今天最有趣的一個實驗，同一份 settings.yaml 同時宣告兩個供應商，內建 catalog 的 deepseek-official（指向 ds4-server）與泛用 adapter 的 gateway（指向閘道上的 Qwen）。Web UI 的模型選單直接把它們分組列出來，切換是每一輪級的、按一下就換：

但地端的真相是：GPU 只有一個租戶，兩款模型不可能同時活著。切到當下沒在跑的那一個，當然就掛掉了，沒辦法用：

dsh: INVALID_REQUEST: 400: {"message":"/chat/completions: Invalid model name
passed in model=qwen3.8-27b. ..."}

harness 不重試、不繞路，直接 exit 1。這個行為是對的，但它也說明「同時接上兩個後端」在地端是設定層面的事實、不是執行層面的事實，除非你有第二張卡或第二台機器。

外掛式架構的代價，測起來只有一個，但它很大：外掛不受沙箱管。 我在 NAS 那支工具外掛裡加上一個探針，每次呼叫就用 node:fs 往工作區外面寫一個檔案，然後把整個 session 切到 read-only 沙箱模式再跑一次。同一個 session 裡出現這樣：

• agent 用內建 write 工具寫工作區外的檔案，被沙箱擋下（[sandbox: file access denied under read-only mode]），依提示升級到 danger-full-access，升級也被擋（requires approval, but no approval channel is available），檔案沒有出現。
• 同一個 session、同一時間，外掛自己那行 writeFileSync 寫到同一個目錄，成功。

模型自己把這件事講出來了：「有趣的是同一個動作從 tool plugin 內部卻寫成功了，顯示 plugin 與我這個 agent 的沙箱權限並不相等。」

原因不難理解：沙箱管的是它自己那幾個 first-party 工具與 bash 子行程，而外掛是跑在 harness 行程裡的同一份 Node 程式碼，它想做什麼就做什麼。所以「裝一個外掛」在信任模型上等同「在這台機器上多跑一支有完整權限的程式」，跟裝一個瀏覽器擴充套件是不同等級的決定。

第三節：天作之合嗎 ?

把 harness 指向 ds4-server 上的 DeepSeek V4 Flash（IQ2XXS 量化、--ctx 100000、--batched-session 2），同一句任務、另一份全新的 54 檔工作區副本，再跑一次。路徑仍然走 Day 18 閘道，因為要比的是模型，不是路徑：

天作之合的答案是：沒有看到任何「自家人」待遇，但這一趟確實快得多。 兩處觀察分別回答如下。

第一，dsh 對自家模型有沒有特殊照顧? 我觀察到有一個結構上的差別，但不是照顧，是省事，ds4-server 的 served model name 剛好就是內建 catalog 的 deepseek-v4-flash，所以這一欄零設定、不必寫自訂 provider，思考區塊與工具呼叫格式也都原生對上。除此之外沒有看到任何提示詞模板的特調，系統提示與 25 個工具的 schema 兩欄一模一樣。而 12.9 分鐘對 64.6 分鐘這個差距，主要不是模型比較聰明，是它比較不囉嗦：11 輪就收工、總輸出只有 9,473 token（Qwen 那欄 27,691），輸入輸出比因此拉到 35.4×。代價寫在交付物上，101 行對 258 行，兩份都做完了任務，詳盡程度差一截。

第二，單 session 引擎遇到平行工具呼叫會不會撞牆。這個問題問錯了層。 agent 迴圈確實會平行呼叫工具，這一趟 10 個批次裡有 9 個一次送出 2 到 3 個呼叫，但那是在 harness 這一端執行的，引擎從頭到尾只看到一個請求。真正會把併發丟給引擎的是 subagent。所以我另外跑了一次，叫 dsh 派三個 subagent 平行讀三個檔案。

閘道上同時出現 4 個請求（三個分身加母 agent），對上 --batched-session 2 的兩個常駐 session。結果是：運作正常，進入排隊狀態。零失敗、零格式錯誤，但擠在同一瞬間的那幾個請求，首 token 從沒排隊時的 0.7 到 1.1 秒變成 51.2 / 69.6 / 81.8 秒。Day 11 說「只要 agent 會開分身就直上 vLLM」，量到的就是這張圖，而且它同時修正了那句話的適用範圍，平行工具呼叫不算，開分身才算。

第四節：治理邊界是近來熱門話題

一個能讀寫檔案、能執行指令、能接外掛的 harness 跑在你的機器上，等於機器上多了一個有手有腳的使用者，它的權限邊界必須被明確定義，也是目前資安的重點，這邊我列出四個檢查點：

工具白名單。
dsh 有 ctx.tools.restrict()，但它自己的文件就寫明那是「live visibility composition, not an authority boundary」，只是遮蔽視野。真正的邊界是組合樹：一個沒被載入的工具外掛不會註冊任何東西，模型看不到 schema，也沒有執行器可以到達。做法是在 profile 的 patch 層用 id 把它們關掉：

- id: tool-bash
  disabled: true
- id: tool-subagent
  disabled: true
- id: tool-web
  disabled: true

實測從 28 個工具降到 15 個，bash、subagent、workflow、web_search 全部消失，讀取面（read / glob / grep / read_image）與我自己那兩個外掛留著。而且它同時是一筆省下來的資源，固定前綴從 7,947 token 掉到 3,280，少了 59%，那是每一輪都要重送的量。收緊權限跟降低成本在這裡是同一個動作。這邊設計的原則是預設只給讀取，寫入與執行逐一開放。

執行沙箱。
指令與檔案工具跑在平台沙箱裡，Linux 上依序探測 bwrap 與 Landlock（本機兩者都在），macOS 用 Seatbelt，Windows 用 ACL 受限 token，探測不到就 fail closed 丟 SANDBOX_UNAVAILABLE，不會無聲地不設限跑下去。三個模式的檔案效果是：read-only 任何地方都不能寫（/dev/null 除外）、workspace-write 只能寫工作區與 /tmp、danger-full-access 不設限。
它透過位置控制而不是行為控制，工作區內的 rm -rf 不需要提權，所以也永遠不會經過核可。Perplexity 的 Portable Computer（Day 13的文章有提到）把沙箱做成預設，dsh 這邊的做法是把預設放在 sandbox-policy 的 config（出廠 read-only，dsh 自己的 headless bundle 則讀 DSH_PERMISSION_MODE，預設 workspace-write），並且每個 session 可以用一個 log-only 的 sandbox/mode 事件覆寫，重播就能還原。上一節那個外掛探針是這一項唯一的破口，沙箱管工具，但不會管外掛。

審核閘門。
dsh 有這個，而且預設 fail closed。read-only 底下模型要寫檔會被拒，它可以帶 sandbox_permissions: danger-full-access 重試一次，這一次會走到 ctx.approval.request()；沒有 answerer 的部署會直接拒絕，這也是為什麼排程一律用 headless（web profile 的 apiproxy 會為每個 agent 註冊 answerer 等人按，無人值守就是無限期卡住）。掛上部署自己的策略外掛之後，同一個 session 兩次寫入得到兩個相反的裁決：

approval write -> allowed-once | allow-path:/home/spark/aiops-runbook/
approval write -> rejected     | default-deny

閃光和我做的 AI 代理人中介框架那套是分層權限加策略引擎，dsh 內建的機制覆蓋到的是接縫與生命週期：一次一個授權、只對發問的那一次呼叫有效、問與答成對寫進稽核之後才回傳。
所以呢，策略本身不在裡面，那三十行判斷是你要自己寫的一個 approval/request 監聽器。另外一個實測過的教訓寫在這裡也剛剛好，核可請求只帶 toolName、callId 與模型自己寫的 reason，用那段 prose 比對路徑白名單是不可靠的，如果你在同一個寫入時而放行時而 default-deny，只因為模型那次沒把完整路徑寫進說明，這時必須在 tools/pre-execute 把真實 arguments 記下來，讓核可層去讀到事實。

稽核日誌。
這一項是 dsh 最強的一環。每個 session 一個 session.jsonl.zstd，事件流不是摘要而是逐事件，上面那個只寫了兩次檔的 session 有 1,607 個事件，第一節那個跑了 64 分鐘的任務有 22,363 個。顆粒度長這樣：

{"type":"tool/call","seq":614,"data":{"turn":1,"step":1,
 "callId":"chatcmpl-tool-be6bc0fd814bf1c2","name":"write",
 "arguments":"{\"file_path\":\"/home/spark/aiops-runbook/day20-test.md\", ...}"}}
{"type":"approval/asked","seq":1017,"data":{"toolName":"write","reason":"escalate ..."}}
{"type":"approval/decided","seq":1018,"data":{"outcome":"allowed-once"}}

每一次工具呼叫、完整參數、每一次核可的問與答、sandbox/mode 與 permission/preset 的每一次變更都在裡面，而且是 append-only 的事件流，可以重播重建。以 ISO 27001 稽核的習慣，這一項是及格有餘，剩下的工作是輪替與保存期限，這反而是部署的事情了，和 harness 比較無關。

四項總評
接縫齊全，策略要自己帶，而且外圍還要補三件事。
沙箱、核可、稽核三個機制本身都做對了（fail closed、一次一授、事件流可重播），但 dsh 出廠不含任何政策，也不會限制外掛。所以要進客戶環境，我會去加上，讓它跑在專用容器裡（因為外掛與 harness 同權限，容器是唯一能框住外掛的那一層）、模型庫與資料目錄唯讀掛載、閘道層做用量與速率限制，記得同時看 max_tokens 與 max_completion_tokens 兩個欄位，否則你的設定的限制只擋得住舊客戶端的請求。

今天的結論

dsh 作為地端 harness 是可以用的，而且在這台機器上跑同一個任務比 opencode 少花三分之一的輸入 token、少一半的時間。它與 opencode 的分工，我會這樣切，opencode 是終端機裡順手的那一個，dsh 是要留下紀錄、要被治理的那一個，差別不在能力而在它把 session、核可與稽核當成重要的事情來看待，而這會是 2026 下半年的熱門要務之一， AI 代理人越來越好用，但是要稽核、保留證據和紀錄是困難且有實際需求的。
天作之合的答案是「沒有特殊照顧，但確實省事」，DeepSeek V4 Flash 零設定就接上，12.9 分鐘做完同一件事，只是交付的產出會比較精簡。
最後一句警語則是關於外掛的部分，外掛不受沙箱管，裝一個外掛等於在這台機器上多跑一支有完整權限的程式，這件事沒有寫在任何一頁 README 上，是本文測試中實際跑測試出來看到的。

明天預告

一個 harness 跑一件事很清楚，如果三個 harness 同時跑三件事就開始混亂囉，會變成這樣，誰在等我確認? 誰卡在錯誤? 誰跑完任務了? 很難一目了然，所以明天是救援投手 herdr 登板，一個知道你的 agent 們在幹嘛的終端機多工器，把 opencode、dsh 與其他 agent 收進同一個看板。

我們 Day 21 見。

Day 1｜為什麼 2026 年是地端 AI 部署元年：系列規劃與硬體總覽
Day 2｜DGX Spark GB10 深度解析：128GB 統一記憶體到底解決了什麼問題
Day 3｜網路與儲存規劃：10GbE 骨幹、雙 Spark 直連與 NFS 集中模型庫
Day 4｜開箱之後：DGX OS 初始環境建置與 CUDA、Docker 生態確認
Day 5｜NFS 模型庫實戰：下載工具、權限設計與版本管理
Day 6｜llama.cpp、vLLM、TensorRT-LLM 、Ollama、DS4 與 Unsloth 的定位與取捨
Day 7｜第一個模型上線：gpt-oss-120b 從模型庫到 API 的完整流程
Day 8｜llama.cpp 實測：先定量尺與 SOP
Day 9｜vLLM 實測：官方容器、同時處理吞吐曲線，與剛出爐的新模型 Ornith 1.5
Day 10｜TensorRT-LLM 實測：我花了一個下午，跟它的預設值搏感情
Day 11｜地端 AI 三大推論引擎綜合評測，同場加映神秘嘉賓
Day 12｜量化格式解析：「4-bit」兩個字，古今多少事 ? 都付笑談中
Day 13｜Perplexity 把整套 Agent 搬上 DGX Spark：地端元年的官方背書
Day 14｜Qwen3.8-27B 與 Flash-Next 加碼實測：地端模型世代對決與落地評估
Day 15｜Ornith 1.5 實測：為 AI agent 而生的 35B-A3B
Day 16｜模型選型方法論：五個問題幫你跳脫排行榜迷失，找到適合自己任務用的 AI 模型
Day 17｜ds4 深度解析：Redis 之父只為一種模型造了一個引擎
Day 18｜OpenAI 相容 API 層：地端 AI 多模型常駐好助手
Day 19｜地端 agent 框架總覽：它們到底對你的端點做了什麼呢?
Day 20｜DeepSeek Harness 實戰：21 萬顆星的外掛式 harness 接上地端
Day 21｜herdr 是地端 AI 同時跑多個 AI agent 的最佳解