Coding Agent 的實作課：從 100 行迴路到 Harness 工程

Coding Agent 的實作課：從 100 行迴路到 Harness 工程

今日主題：Coding Agent 的技術棧與實作
2026-10-17 | 資料來源：Princeton SWE-agent 研究團隊、OpenHands（原 OpenDevin）、Anthropic 工程部落格、Mini-SWE-agent 開源專案、Terminal-Bench 評測

前言：Agent 最好的練功房是終端機

過去一年，Coding Agent 從「會補全程式碼的外掛」變成「住在終端機裡的工程師」。Claude Code、OpenHands、Mini-SWE-agent、Pi——它們看起來差很多，但原始碼攤開來看，核心迴路小得驚人：把對話送給模型、執行模型要求的工具、把結果貼回去、重複。一位開發者在 2026 年 10 月讀完 12 個開源 Coding Agent 的原始碼後寫道：12 個裡有 10 個，「模型沒有呼叫任何工具」就等於「工作完成」。Mini-SWE-agent 的核心甚至只有約 100 行 Python，只有一種工具：bash。

迴路很小，真正的工程在迴路周圍。這篇文章拆開 Coding Agent 的技術棧：核心迴路、Agent-Computer Interface（ACI）、Harness（支架工程）、評測方法，以及你要自己動手時的起手清單。

一、核心迴路：小到可以背下來

如圖一，一個最精簡的 Coding Agent 只需要四個零件：

1. 模型呼叫：把完整對話歷史送給 LLM。 2. 工具執行：解析模型要求的工具呼叫，在沙箱裡執行。 3. 歷史追加：把工具結果貼回對話，進入下一輪。 4. 停止條件：模型不再呼叫工具 → 視為完成。

Mini-SWE-agent 把這個想法推到極致：不用模型的 tool-calling 介面，直接讓模型輸出 bash 指令，用 subprocess.run 執行。好處是極簡——任何模型都能跑（連不支援 function calling 的模型都可以）、歷史完全線性（除錯時看到的就是模型看到的）、換沙箱只要把 subprocess.run 換成 docker exec。壞處也明顯：模型得自己拼出所有操作，聰明的模型才玩得轉。

用 Python 寫出來，骨架大概長這樣：


import subprocess

SYSTEM = "你是軟體工程師。每次回覆只輸出一個 bash 指令，或輸出 DONE 結束。"

def run(cmd, timeout=120):
    p = subprocess.run(cmd, shell=True, capture_output=True,
                       text=True, timeout=timeout, cwd="/workspace")
    out = (p.stdout + p.stderr)[-4000:]  # 只保留尾端，避免塞爆上下文
    return f"exit={p.returncode}\n{out}"

messages = [{"role": "system", "content": SYSTEM},
            {"role": "user", "content": "修掉 issue #42 描述的 bug，跑測試確認"}]
for _ in range(30):                       # 迭代上限：Harness 的一部分
    reply = llm(messages)
    if reply.strip() == "DONE":
        break
    messages.append({"role": "assistant", "content": reply})
    messages.append({"role": "user", "content": run(reply)})

這就是全部。剩下的，都是讓這個迴路「跑得穩、跑得快、跑得安全」的工程——也就是 Harness。

二、ACI：把工具做成模型拿得順手的樣子

Princeton 團隊在 SWE-agent 論文（NeurIPS 2024）裡提出一個關鍵詞：ACI（Agent-Computer Interface），類比人類的 HCI。重點不是給模型更多工具，而是給「模型用起來順手」的工具：

  • 專用終端機：一次只顯示 100 行程式碼，附帶「跳到第幾行」指令。模型一次看太多會暈頭——有趣的是，人類一次也只看 50–100 行。
  • 過去踩坑的提示：例如「先重現 bug 再修」「同一個指令失敗就不要原樣重跑」。這些提示來自開發者觀察模型失敗模式後的補救，是經驗的沉澱。
  • CodeAct 典範：OpenHands 不給幾十個窄工具，而是讓 Agent 直接寫程式（Python / Bash）來解決問題。Agent 不是在呼叫固定 API，而是在寫程式——跟人類工程師一樣。

ACI 的設計哲學呼應我們 10/15 寫過的 Agent-Friendly API：描述寫「何時用」、參數防呆、回傳省著用。差別在於，ACI 是「給 Agent 用的電腦介面」整體設計。

三、Harness：真正的工程在這裡

2026 年 2 月，LangChain 公開了一個漂亮的實驗：同一個模型（GPT-5.2-Codex），只改 Harness 不換模型，Terminal-Bench 2.0 成績從 52.8% 拉到 66.5%，名次從 30 名外衝進前 5。13.7 個百分點，零模型進步。改了什麼？四個中介層（middleware），如圖二：

1. 自我驗證（Self-verification）：宣告完成前強制跑檢查清單，確認自己的工作真的做完了。 2. 迴路偵測（Loop detection）：追蹤每個檔案的編輯次數，砍掉「doom loop」——那種反覆改同一個檔案、燒掉幾千個 token 的重試漩渦。Doom loop 是 Harness 的 bug，不是模型的 bug。 3. 上下文注入（Context injection）：啟動時給目錄結構與工具地圖，外加時間預算警告，讓 Agent 一開始就知道自己在哪，而不是到處亂逛。 4. 停止條件：不體面的斷電開關。沒有它，Agent 會在某個死角裡燒錢燒到天亮。

Anthropic 內部的經驗也指向同一個結論：工程師不再「寫 prompt 給 Claude」，而是「建造會自己 prompt 自己的系統」。Claude Code 團隊的 Boris Cherny 說，關鍵是 Harness 工程——讓 Claude 觀察、計畫、行動、反思的迭代迴路可以跑上幾小時甚至幾天。到 2026 年 5 月，Anthropic 內部超過八成合併的正式程式碼由 Claude 撰寫，工程師的工作變成設計架構、寫測試支架、處理 Agent 真正卡住的時刻。

一句話總結：模型決定上限，Harness 決定下限。

四、怎麼評測：SWE-bench 與 Terminal-Bench

寫 Coding Agent 不能只憑感覺，業界有兩套主流考卷：

  • SWE-bench Verified：500 個經過人工驗證的真實 GitHub issue，來自 django、sympy、scikit-learn 等知名 Python 專案。評分看兩組測試：FAIL_TO_PASS（修之前不過、修之後要過）與 PASS_TO_PASS（原本會過的不能被修壞）。Agent 的產出是一份 git patch，在乾淨的 Docker 環境裡重跑驗證。
  • Terminal-Bench 2.0：更貼近真實終端機任務的評測，考的是在 shell 裡完成任務的能力。LangChain 的 Harness 實驗就是在這張考卷上拿的分數。

自己動手時可以偷師這套方法：準備一個 Docker 沙箱、一組「修前不過、修後要過」的測試，Agent 跑完自動打分。這比人工看 log 可靠得多，也是我們 10/1 寫過的「評測飛輪」在程式碼領域的具體長相。

五、選型光譜：極簡、中庸、全功能

2026 年中的 CLI Coding Agent 版圖，大致是一條光譜：

  • 極簡端 — Mini-SWE-agent：約 100 行 Python、bash only。定位是「研究對照組」：拿掉支架變因，量的是模型本身的能力。想理解 Coding Agent，先讀它的原始碼。
  • 中庸端 — Pi：4 個工具（讀、寫、編輯、bash）、系統提示不到 1000 token。主張現代模型不需要更多，MCP 支援都該放進擴充 SDK。
  • 全功能端 — OpenHands：事件流架構、瀏覽器、Jupyter kernel、雲端編排。適合「把整個開發環境交給 Agent」的場景，但複雜度與維運成本也最高。

選型建議：如果團隊第一次導入，從極簡或中庸開始。支架的每一層複雜度都要有評測分數來背書——連 Mini-SWE-agent 都打不贏的支架，就是純粹的累贅。

六、自己動手的起手清單

如果你想在自己的專案裡接一個 Coding Agent（例如修 bug、跑 migration、整理測試），按這個順序做：

1. 沙箱先行：Agent 的 bash 只能在 Docker 容器裡跑，正式環境的 credential 一律不進容器。這是 10/8 沙箱文章的同一條鐵律。 2. 迭代上限＋超時：迴圈設硬上限（例如 30 輪），每個指令設 timeout。這是最便宜的 doom loop 保險。 3. 驗證閘：完成前強制跑測試或 lint，不通過就把錯誤貼回去繼續修，而不是直接宣告完成。 4. 線性歷史：除錯時能完整重播「模型看到什麼、做了什麼」。Mini-SWE-agent 的線性歷史設計值得抄。 5. 從一條小任務開始量測：挑一個真實的小 issue，記錄修好率、token 花費、人工介入次數，再決定要不要加支架。

結論

Coding Agent 的技術棧可以濃縮成三句話：迴路要小（100 行就夠）、介面要順（ACI 思維）、支架要硬（驗證閘、迴路偵測、停止條件）。模型年年變強，但 2026 年的實證反覆證明同一件事：同一顆模型，Harness 的好壞可以差出 13 個百分點。與其等下一代模型，不如先把你手上的迴路周圍砌好——那才是你真正能控制的工程。

參考來源

Uploaded Image Uploaded Image
at
Labels:

沒有留言:

張貼留言

訂閱： 張貼留言 (Atom)