先做最小的 harness,遇到問題再加零件

深讀 L3 1,223 字 3 分鐘 v2.0.0 更新 2026-11-16

harness 是模型外圍的工作環境。最小版本是迴圈加上讀檔、寫檔、改檔與執行指令的工具,其餘零件遇到問題再加。

組裝時要分清楚:哪些資料在啟動時讀入,哪些處理每輪都做,哪些檢查必須擋在執行之前。

啟動時,先準備規則與工具

context 是一次請求送給模型的全部內容,包含工具定義、系統指示與對話。組成與重送方式見 context 的組成。

實作可照 Thorsten Ball 的文章,先寫出迴圈與三個工具,再依序加入規則檔、權限檢查與壓縮。權限檢查擋在工具之前,壓縮則在 context 太長時執行。每個零件只解決一個問題,出問題時就能判斷該調整哪一個。

harness 啟動時讀入規則檔,把規則放在 context 前段。範例以 read("AGENTS.md") 讀取內容,存入 system。

規則檔的名稱取決於使用的環境。Claude Code 讀取的檔案與放置方式見 CLAUDE.md;這份自製 harness 範例則明確指定 AGENTS.md。

工具以名稱、說明與參數格式描述,格式見 工具呼叫的格式。工具可以由內建函式提供,也可以來自提供工具的 MCP server,連接方式見 MCP。

下圖把五個零件放在同一張圖裡,對照規則的入口、迴圈與模型的往返,以及工具前方的權限檢查。

迴圈是中心。其他零件都接在迴圈上。

每輪請求前檢查長度,收到回覆後判斷是否執行

負責問模型、執行工具並送回結果的主迴圈,見 Agent Loop。接上其他零件時,要把處理放進這個迴圈的正確位置。

範例先用 messages = [user(task)] 放入任務。每輪呼叫模型之前,harness 先執行 maybe_compact(messages),在 context 太長時壓縮內容。

接著,model(system, tools, messages) 接收規則、工具與對話。模型回覆後,harness 用 messages.append(reply) 把回覆加入對話。

工具呼叫是模型提出工具名稱與參數、交由 harness 執行的請求,詳見 工具呼叫。範例檢查 reply.tool_calls;沒有請求時,就回傳 reply.text。

下圖用偽程式碼標出各零件接入的位置。這是教學用的玩具範例,沒有附上各函式的完整實作,不能直接當成可執行的產品。

啟動時讀入規則檔,之後每一輪都不變。

權限檢查必須在工具執行之前

模型提出請求後,harness 逐一執行 gate(call)。回傳 REFUSE 時,harness 將 refused(call) 加入結果;否則才執行 run_tool(call)。

沙箱由作業系統限制程式可讀寫的檔案與可連線的網路,詳見 沙箱。規則檔只是提醒;需要限制可寫入目錄時,應由沙箱約束範圍。

規則太長與過程難查時,資料該放哪裡

規則檔太長時,可以採用 OpenAI 團隊的做法:讓 AGENTS.md 當目錄,把細節放進 docs 資料夾。啟動時載入的檔案因此負責提供入口。

另外,把每次請求、工具呼叫與結果寫成程式執行紀錄,詳見 log。出問題時,沿著紀錄找出偏離任務的那一輪,再判斷該調整哪個零件。

按錯誤發生的位置調整零件

模型選錯工具或填錯參數時,先檢查工具名稱與說明。改寫說明之後,再考慮合併功能重疊的工具。

長對話開始偏離任務,或壓縮後遺失先前決定時,檢查壓縮處理。context 會被壓縮,檔案不會,因此把計畫與決定寫進檔案,長輸出也存成檔案,只回傳路徑。

若 agent 執行不能復原的指令,或修改任務範圍外的檔案,就檢查權限規則。加入拒絕或詢問條件,並限制可寫入的目錄。

下圖可切換這三類錯誤,對照現象與要調整的零件。

遇到的問題

現象

  • 模型呼叫了不適合的工具
  • 或是填錯參數

調整的零件

  • 工具:改寫名稱與說明
  • 合併功能重疊的工具
模型只依名稱與說明選工具。先改說明,再考慮減少工具。

來源

讀完之後

HarnessLLM迴圈工具context快取KV接手協定權限沙箱層注入子 agent實作評測