---
site: "zyx.tw"
title: "先做最小的 harness，遇到問題再加零件"
description: "從迴圈與工具起步，依錯誤補上規則、權限與壓縮。"
url: "https://www.zyx.tw/map/harness/build-a-small-harness"
---

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

紀錄 050，深讀 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。

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

```text
                 ╭───────────╮
   AGENTS.md ──> │   RULES   │
                 ╰─────┬─────╯
                       v
╭────────╮       ╭───────────╮       ╭───────────╮
│ person │ ────> │   LOOP    │ <───> │   model   │
╰────────╯       ╰──┬─────┬──╯       ╰───────────╯
                    v     v
            ╭────────╮  ╭──────────╮
            │  GATE  │  │ COMPACT  │
            ╰───┬────╯  ╰──────────╯
                v
            ╭────────╮       ╭─────────────╮
            │ TOOLS  │ <───> │ MCP servers │
            ╰────────╯       ╰─────────────╯
```

Figure: A small harness with a loop between a person and a model. Rules come from a file. A permission gate stands in front of the tools. Compaction sits beside the loop. Tools may come from MCP servers.

1. Loop: 迴圈是中心。其他零件都接在迴圈上。
2. Rules: 規則檔寫明工作背景與完成標準。
3. Tools: 工具讓模型讀檔、改檔與執行指令。
4. Gate: 每個工具請求先過權限檢查。
5. Compact: 對話太長時，用摘要取代舊訊息。

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

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

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

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

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

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

```text
def main(task):
    system = read("AGENTS.md")               # rules
    tools = BUILTIN + mcp_list_tools()       # tools
    messages = [user(task)]
    for turn in range(MAX_TURNS):            # loop
        maybe_compact(messages)              # compact
        reply = model(system, tools, messages)
        messages.append(reply)
        if not reply.tool_calls:
            return reply.text
        results = []
        for call in reply.tool_calls:
            if gate(call) is REFUSE:         # gate
                results.append(refused(call))
            else:
                results.append(run_tool(call))
        messages.append(user(results))
```

Figure: Pseudo code of a whole small harness: read the rules, list built-in and MCP tools, then loop: compact, ask the model, stop or run each tool behind a permission gate, and append the results.

1. Rules: 啟動時讀入規則檔，之後每一輪都不變。
2. Tools: 內建工具加上 MCP server 列出的工具。
3. Loop: 迴圈與 Agent Loop 那篇相同。
4. Compact: 每一輪開始前，檢查對話是否太長。
5. Gate: 被拒絕的請求不執行，原因當成結果送回。

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

模型提出請求後，harness 逐一執行 gate(call)。回傳 REFUSE 時，harness 將 refused(call) 加入結果；否則才執行 run\_tool(call)。

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

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

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

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

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

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

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

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

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

**遇到的問題 選錯工具**

現象:
- 模型呼叫了不適合的工具
- 或是填錯參數

調整的零件:
- 工具：改寫名稱與說明
- 合併功能重疊的工具

模型只依名稱與說明選工具。先改說明，再考慮減少工具。

**遇到的問題 忘記目標**

現象:
- 對話很長之後偏離任務
- 壓縮後遺失先前的決定

調整的零件:
- 壓縮：把計畫與決定寫進檔案
- 長輸出存成檔案，只回傳路徑

context 會被壓縮，檔案不會。重要的內容寫進檔案。

**遇到的問題 做了不該做的事**

現象:
- 執行了不能復原的指令
- 修改了任務範圍以外的檔案

調整的零件:
- 權限：加上拒絕或詢問規則
- 沙箱：限制可寫入的目錄

規則檔只是提醒。不能有例外的限制，交給權限規則與沙箱。

**遇到的問題 沒做完就回報完成**

現象:
- 回報完成，但測試沒有通過
- 或是只完成一部分

調整的零件:
- 規則：寫明完成標準
- 工具：讓 agent 能自己跑測試

模型停止不等於完成。提供驗證的工具，並要求回報附上實測結果。

## 來源

- [How to Build an Agent](https://ampcode.com/how-to-build-an-agent), Thorsten Ball
- [learn-harness-engineering](https://github.com/walkinglabs/learn-harness-engineering), walkinglabs
- [Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/), Ryan Lopopolo, OpenAI
- [What I learned building an opinionated and minimal coding agent](https://mariozechner.at/posts/2025-11-30-pi-coding-agent/), Mario Zechner
- [Agent SDK overview](https://code.claude.com/docs/en/agent-sdk/overview), Claude Code docs
- [Continually improving our agent harness](https://cursor.com/blog/continually-improving-agent-harness), Cursor
- [AGENTS.md](https://agents.md/), agents.md

## 地圖

- 先讀：[工具以名稱、說明與參數格式約定請求，再用同一個 id 對回結果](https://www.zyx.tw/map/harness/tool-calls.md)
- 先讀：[每輪重送 context，固定前段與對話長度要分開管理](https://www.zyx.tw/map/harness/context-is-resent.md)
- 先讀：[權限規則先拒絕、再詢問、最後放行，沒有命中才交給模式](https://www.zyx.tw/map/harness/permission-gates.md)
- 相關：[MCP 用 JSON-RPC 傳訊息：先取得工具定義，再轉送模型選定的操作](https://www.zyx.tw/map/harness/mcp-on-the-wire.md)
- 相關：[子 agent 另開迴圈，交接內容決定彼此知道多少](https://www.zyx.tw/map/harness/subagent-fresh-context.md)
- 相關：[修改規則前，先用固定任務與自動評分建立比較基準](https://www.zyx.tw/map/harness/evals.md)
- 回到：[Harness](https://www.zyx.tw/map.md)
