【2026 最新】DeepSeek Harness 架構拆解：5 個可移植的 Agent 設計模式

如果 AI Agent 做錯事，你能不能只靠紀錄重建它當時真正看見的訊息？如果搜尋結果被截斷、模型反覆呼叫同一個工具，或它把工具包進一段程式執行，權限還守得住嗎？這些問題比「模型夠不夠聰明」更早決定 Agent 能不能上線。

這篇 DeepSeek Harness 架構教學不重做安裝與 Plugin 入門，而是拆解目前官方 dsh-v0.1.1-rc.2 原始碼裡五個可移植的設計模式。讀完你會得到一條可用於評估任何 Agent 框架的主線、一個完整任務追蹤案例，以及可以直接帶回自己系統的驗收清單。若你第一次接觸這個專案，先讀DeepSeek Harness 基礎教學會更順。

先說結論：可靠 Agent 不是多一個 Prompt

核心判斷很簡單：可信 Agent ＝ 可重建紀錄＋軟性迴圈煞車＋可追索截斷＋一致的工具權限入口＋可交接的新鮮 Context。

這五項不是 DeepSeek 專屬功能名稱，而是 Harness 應該提供的五種控制面。模型仍可能犯錯，但系統要能回答：它看見什麼、為何重試、漏掉什麼、誰允許執行，以及下一個 Agent 根據什麼接手。只要其中一項只能靠猜，除錯與稽核就會變成事後考古。

DeepSeek Harness 架構的官方版本邊界

本文固定在 2026 年 8 月 21 日發布的 dsh-v0.1.1-rc.2（commit b150a551）。官方仍把它標成 Developer Preview，明說可能有不相容變更；因此本文教的是可移植模式，不把任何設定值當永久 API。想自己對照，可依官方固定版本原始碼執行：

npx @deepseek-ai/dsh@0.1.1-rc.2 web

若要從原始碼建置，官方 contributor prerequisites 列的是 Node.js 22.19+ 或 24+、pnpm 11.7.0 與 Git 2.26+；已發布 CLI 的 manifest 並沒有同一份 engines／OS 最低版本矩陣，不要把 source floor 誤當成所有 npx 使用者的硬門檻。若你只是想理解框架定位，可先看AI Agent Harness 白話解釋；以下則直接進入原始碼層級。

模式一：一份事件日誌，讓 Agent request 可重建

一般聊天紀錄常只保存「最後顯示的訊息」，但真正送往模型的 request 還包含 system prompt、工具清單、temperature、stop 條件與壓縮後上下文。若這些欄位分散在記憶體裡，事故發生後就無法證明模型當時收到什麼。

DeepSeek Harness 採 append-only session event log，再由事件推導 request。可選的開發期 invariant 會把 session 重新折疊一次，比對 loop request 的 messages 與部分 request header；一旦不同便回報 log-reconstruction desync。它是另行掛載的 companion，目前出廠 Web 組態並沒有證明每次 npx 呼叫都會執行，也不涵蓋所有 GenerateOptions 欄位。可直接查看官方 request-reconstruction invariant。

可移植原則：日誌不是執行完才補寫的旁白，而是 request 的單一來源。你的測試至少要能從持久化事件重建訊息順序、系統指令、工具 schema 與採樣設定，並在任何一項漂移時失敗。

模式二：先提醒模型離開死迴圈，不急著硬封鎖

Agent 常把「工具回傳空結果」誤判成「再叫一次也許會成功」。DeepSeek 的 repeat-tool reminder 以「工具名稱＋深層排序後的完整 JSON 參數」當連續鏈 key，預設在第 3、5、8 次完全相同的呼叫後加入逐步升級的提醒。它不改參數、不取消呼叫，也不覆蓋原始工具結果。

- id: repeat-tool-reminder
  name: '@deepseek-ai/dsh-repeat-tool-reminder'
  config:
    thresholds: [3, 5, 8]
    exclude: [todo_write]

像上例明確排除的 bookkeeping 工具不會洗掉鏈；若沒有放進 exclude，它仍會重設連續計數。遭權限拒絕的呼叫會計數，每個 Agent 則用自己的 counter。這種設計值得學，因為「重複」有時是合法 polling，硬封鎖會製造假陽性。但它只抓完全相同參數，路徑多一個空白或改一個值就能避開；超過最高門檻後也不再提醒。正式環境仍要另設 turn／round、wall time、token 或成本的硬上限，提醒不能取代終止條件。完整語意可對照官方 repeat-tool reminder 文件。

模式三：結果可以截斷，但不能假裝完整

大型專案搜尋必須設上限，真正危險的是模型看見 100 筆後，以為整個 repo 只有 100 筆。DeepSeek 的 glob 預設最多顯示 100 個路徑，grep 最多顯示 250 筆；超量時會明說結果遭截斷，並在 spill store 可用時保存完整格式化清單，讓後續工具能追索。

這裡要修正一個流傳說法：目前出廠的 base／standard／code 組態把 sampleOverCapGlobResults 設成 false，因此超量時保留的是依修改時間排序的前 100 筆，不是必然平均灑到整個專案。框架本身支援設成 true 後跨頂層項目取樣，但那是部署選擇。官方檔案搜尋契約也明列兩種模式。

可移植原則：每個有上限的工具都要同時回傳 shown_count、is_truncated、排序／取樣規則，以及完整結果的 locator；如果完整結果保存失敗、過期或無法取回，也必須把失敗寫給模型看。這與Prompt Injection 回歸測試背後的思路相同：邊界要成為可驗證輸出，而不是藏在實作細節。

模式四：Code Mode 的 SDK 呼叫要重返權限管線

Code Mode 讓模型只直接看見 run_code，再於 TypeScript 程式內呼叫產生的工具 SDK。好處是它能迴圈、分支與彙整中間資料，而不必把每個中間結果塞回對話。真正關鍵不在「能寫程式」，而在內層每個 SDK 呼叫仍重新進入原生的 pre-execute → guards → execute → post-execute → result 管線。

因此一次 tools.* 內層呼叫若被政策拒絕，程式收到可捕捉的 ToolCallError；每個已開始的 sub-call 也各自寫入 dispatch event。這證明的是生成 SDK 的工具呼叫不會因多包一層程式而漏掉 approval 與 guard。這個契約可在官方 tools／Code Mode 文件核對。

但這不等於整個 run_code 都被工具政策包住。官方worker-thread runtime 文件明確說它是 containment，不是 security boundary；模型程式可接觸 Node API，信任姿態近似 shell。普通工具已造成的副作用也不會因外層程式失敗而自動回滾。做高風險動作時，除了把 allowlist、路徑限制、核准與可取消性放在工具管線，還要改用能提供硬隔離的 container-class runtime。若要進一步練習這一層，可接著讀DeepSeek Harness 安全 Plugin 實戰。

模式五：用新鮮 Context 換掉累積偏誤

長任務不只會塞滿 token，前一輪的錯誤假設也會一路污染後續判斷。可選的 ralph 工具把一個不可變 objective 交給一連串全新的 child agent；新 child 不繼承 parent 對話或前一位 child 的 session，只讀共享 workspace、目前輪次，以及上一輪的結構化 handoff。

{
  "status": "continue",
  "summary": "已定位搜尋結果截斷，尚未驗證權限拒絕",
  "evidence": ["session-export/round-1.jsonl"],
  "nextSteps": ["重播 denied call", "核對 dispatch event"],
  "blocker": ""
}

這種 handoff 迫使上一輪把結論、證據與下一步外顯化，workspace 則保存長期狀態。代價是每輪都重新付 Context 成本，而且完成與阻塞只是 worker 自我回報，沒有獨立 evaluator。

另一個必要修正是：目前官方實作沒有「前三輪不得回報 blocked」的硬規則；第一輪若無法取得有意義進展，就可以回報阻塞。「只有直接人類要求才使用 Ralph」也是 system prompt 的路由指引，不是獨立的身分授權機制。不要把 prompt policy 誤寫成 security boundary。詳見官方 Ralph 契約。

完整追蹤案例：讓 Agent 稽核一個大型程式庫

假設任務是「找出所有可能把密鑰寫進 log 的路徑，提出修補並附證據」。這個案例可以把五個模式串成同一條可驗收軌跡。

1. 建立可重建 request：objective、system、可用工具與第一個 glob 都先進事件日誌，再由日誌產生模型請求。
2. 揭露搜尋邊界：glob 命中 1,840 個檔案，只顯示 100 個時必須標記截斷與保存位置；Agent 不能據此宣稱「已掃完整個 repo」。
3. 抑制無效重試：若模型連續三次用相同參數搜尋，提醒它閱讀上一個結果、縮小範圍或改採其他證據。
4. 保留政策入口：模型在 run_code 裡透過生成 SDK 並行讀取候選檔；每個 read、grep 與 edit 仍獨立經過權限管線與事件紀錄，任意程式碼則另交給硬隔離 runtime。
5. 用 handoff 重新開局：第一輪把已檢查路徑、未讀 locator、測試結果與下一步寫進 workspace；第二個 fresh agent 先驗證證據，再決定繼續或完成。

最後的驗收不是「Agent 說完成」，而是你能從 session log 重建最後一次 request、看見每次截斷提示與 locator、驗證 locator 仍可讀、看到每個 SDK 內層工具的政策決策，並把 handoff 中的 evidence 逐一打開。Session ZIP 不保證連 spill 檔一起打包，不能把 export 當成天然自包含的完整軌跡。這也是自行打造 AI Agent Harness時最值得先做的最小垂直切片。

如何把五個模式移植到自己的 Harness

1. 先定義事件 vocabulary：至少涵蓋 request header、user／assistant message、tool call、policy decision、tool result、handoff 與 terminal status。
2. 寫重建 invariant：在測試環境把事件重新折疊，與真正送出的 request 做深度相等比對；不要只比對最後一則訊息。
3. 把每個 cap 變成資料：回傳上限、已顯示數、截斷旗標、選取規則與完整結果 locator，並測 spill 失敗路徑。
4. 集中權限管線：無論工具從聊天、子 Agent 或 Code Mode 的生成 SDK 進來，都走同一個 policy function；測試包裝後仍會被拒絕，並把任意程式執行放到真正的隔離後端。
5. 把交接做成 schema：限制 handoff 大小，要求 evidence 與 next steps，將 complete 視為待驗證主張，而非自動通關。

第一版不必一次做完所有 UI。先選一個跨越「搜尋 → 權限 → 修改 → 驗證」的真實任務，保存完整事件，再故意觸發重複呼叫、截斷與 denied call。若這三種失敗都能在重播中被解釋，你的 Harness 才開始具備可營運性。

DeepSeek Harness 架構的限制與採用判斷

• 適合：你在建置可觀測、可插拔的 coding agent，願意閱讀 TypeScript 原始碼，並能承受 prerelease 的相容性變動。
• 不適合直接照搬：你需要已穩定的長期 API、獨立完成判定、跨輪 token／成本／時間預算，或把 worker thread 當資安沙箱。
• 最值得先抄的部分：request reconstruction invariant 與 truncation disclosure；它們小、可測，且能立刻改善事故調查品質。

若你的需求更偏向 Plugin 的路徑權限、HMR 與 crash recovery，直接讀安全 Plugin 實戰會比在本文繼續擴充題外細節有效；本文刻意只處理跨框架可移植的五種控制面。

常見問題 FAQ

1. DeepSeek Harness 是模型嗎？

不是。它是承接模型、工具、session、權限與工作流程的 Agent Harness；模型只是其中一個可替換元件。

2. Append-only log 等於完整可重播嗎？

不一定。它能重建模型請求，但外部 API、時間與檔案狀態可能已改變；要重現副作用，還需要 fixture、版本固定或模擬環境。

3. 第八次重複後會自動封鎖工具嗎？

不會。預設門檻只在第 3、5、8 次注入提醒，屬於 advisory；最高門檻之後不會持續追加提醒。

4. Glob 超過 100 筆一定會跨目錄取樣嗎？

不一定。是否跨頂層項目取樣由 sampleOverCapGlobResults 決定；目前出廠組態為 false，保留修改時間排序的前段。

5. Code Mode 會減少所有任務的 token 嗎？

不保證。它用 SDK 文字與一個 run_code schema 取代一般工具 schema，並把中間值留在程式內；實際節省取決於工具數與任務形狀。

6. Worker thread 能隔離惡意程式嗎？

不能把它當資安保證。權限控制仍要由工具 allowlist、政策管線、檔案邊界與外部 sandbox 承擔。

7. Ralph 會自動證明任務完成嗎？

不會。complete 是 child agent 的自我回報，官方目前沒有獨立 evaluator；重要任務仍需驗證 evidence。

8. 我應該先實作哪一個模式？

先做可重建 request。沒有可信事件來源，其餘提醒、權限與交接就很難被測試，也無法在事故後證明。

給初學者的 5 個重點

• Harness 的工作不是讓模型變聰明，而是讓行為可重建、可限制、可驗證。
• 事件日誌應該生成 request，而不是執行後再補一份看起來相似的紀錄。
• 結果截斷沒有錯；沒有告訴模型截斷與追索方法才危險。
• Code Mode 的 SDK 呼叫要走同一權限管線，但 worker thread 本身不是安全沙箱。
• 先用一條真實失敗軌跡驗收，再擴充更多工具與工作流程。