AHE 深度解析：Coding Agent 的 Harness 如何自動演化

前言

做 coding agent，選擇的基座模型能力是一部分。現在真實落地的業務場景中，同樣重要的還有模型外面那層 harness（prompt、tools、middleware、memory、執行環境、trace 和評測流程）。

AHE 這篇論文解決的正是這個問題：如何讓 coding agent 的 harness 像軟件工程一樣，被持續觀察、持續修改、持續評測、持續回滾，甚至自動迭代。

論文全名是 《Agentic Harness Engineering: Observability-Driven Automatic Evolution of Coding-Agent Harnesses》，作者來自復旦大學、北京大學和上海奇績智峰有限公司。高校研究團隊提供方法設計，產業團隊則有 Agent / LLM Infra / Nex AGI 相關係統背景。

更棒的是，AHE 有開源倉庫：china-qijizhifeng/agentic-harness-engineering。

這讓它不只是一個論文概念，你可以直接看到 seed coding agent、evolve agent、實驗配置、trace、manifest、rollback 這些工程結構。對正在做 coding agent、agent infra 或者更廣義 agent 產品的人來說，這個倉庫非常值得拆解研究。

本文將圍繞三個問題展開：AHE 為什麼有效，它如何演化 harness，以及如何基於這個倉庫開始一個自己的小實驗。

一、先簡單講講 Harness Engineering

Harness 可以理解成讓模型真正工作起來的外部工程殼層。在 coding agent 裡，它通常包括：

• system prompt：規定 agent 的基本工作方式；

• tools：文件讀寫、shell、搜索、測試運行、代碼修改等工具；

• tool descriptions：模型看到的工具說明和參數 schema；

• middleware：工具調用前後的攔截、檢查、修正和日誌處理；

• memory：短期記憶、長期記憶、經驗沉澱；

• context management：上下文壓縮、裁剪和召回；

• execution environment: sandbox、權限和運行隔離；

• evaluation / observability：測試、trace、log、reward、失敗報告和迴歸記錄。

這套結構決定了模型如何接觸任務、如何調用工具、如何處理失敗、如何判斷完成。

比如在實際業務中 shell 卡死，不一定要靠 prompt 反覆提醒“不要交互式命令”。更穩的辦法是 shell tool 加 timeout，middleware 識別高風險命令，輸出層截斷長日誌，任務完成前強制檢查狀態。

這就是 Harness Engineering 的重點：把 agent 的能力放進一套可維護的運行系統裡。

這裡就不詳細介紹 Harness 這個概念了，如果想繼續瞭解這個方向，可以搜索這些關鍵詞：Harness Engineering、Agent Harness、Agent Runtime、Tool-use Agent、Agent Observability、Agent Evaluation、Coding Agent Infrastructure.

讓我們進入本文的重點。

二、AHE 的核心定位：讓 Coding Agent 的 Harness 自迭代

AHE，全稱 Agentic Harness Engineering。

論文標題中的關鍵詞是：Observability-Driven Automatic Evolution of Coding-Agent Harnesses。

這句話可以拆成三層：

第一，AHE 面向的是 coding agent 的 harness。它不訓練新模型，也不修改 base model 參數。

第二，它做的是 automatic evolution。目標不是人工調一次 prompt，而是在多輪運行中持續演化 harness。

第三，它依賴 observability。改動來自 trace、log、reward、失敗分析、change manifest 等證據，不靠一句提示中的“自我反思”。

所以，AHE 的準確定位是：

一個面向 coding agent 的 harness 自動演化框架。它通過可觀測的運行證據，持續改進 agent 外圍的 prompt、tools、middleware、memory、skills 和 sub-agents.

這也是它和普通 prompt optimization 的關鍵差異。AHE 會修改 prompt，但 action space 更大。它把 tools、middleware、memory 這些執行結構也納入演化範圍。

三、AHE 的實驗結果

AHE 的主實驗在 Terminal-Bench 2 上進行。論文報告裡，AHE 經過 10 輪迭代，把 seed harness 的 pass @1 從 69.7% 提升到 77.0%。這個結果說明，在目標 benchmark 上，AHE 找到了有效的 harness 改動。

更值得看的是 ablation。論文把 full AHE 中不同組件單獨替換回 seed harness，結果大致是：

這個結果很有信息量。

如果收益主要來自更好的 system prompt，prompt-only 應該提升。但實驗裡 prompt-only 下降了，提升更明顯的是 memory、tool 和 middleware。

這意味著 AHE 的關鍵收益來自結構性 harness 改動。也意味著從數據來看複雜任務裡的 agent 失敗，很多時候需要更硬（工程化）的機制：工具行為、運行時攔截、狀態記錄、長期經驗、迴歸評測。

論文還做了遷移實驗。演化後的 harness 遷移到 SWE-bench-verified 時，成功率提升很小，但 token 使用下降更明顯。這說明 AHE 演化出的結構可能更擅長減少無效探索和上下文浪費。

跨模型遷移也值得注意。AHE 生成的 harness 放到多個 base model 上，論文報告都有正收益。這個結果說明，它學到的東西包含了一部分可遷移的工程結構。

我的判斷是：AHE 對“哪些改動會修復問題”的預測明顯好於隨機，但對“哪些改動會導致退化”的預測還比較弱。它確實能證明 harness 可以被文件化、證據化、版本化地持續演化。

四、AHE 的關鍵流程：評測、診斷、修改、驗證、回滾

AHE 的主流程：

graph TD
    A[當前 Harness] --> B[在 benchmark 上運行 Code Agent]
    B --> C[收集 trace、log、reward]
    C --> D[分析失敗模式]
    D --> E[讓 Evolve Agent 修改 Harness 文件]
    E --> F[寫入 change_manifest]
    F --> G[下一輪重新評測]
    G --> H[驗證修改是否有效,必要時回滾]
    H -.-> A

這個閉環裡有三個主要角色。

第一個是 Code Agent。

它是真正完成 coding task 的 agent，也是被優化的對象。在 AHE 倉庫裡，seed agent 很簡單，基本是一個 bash-only coding agent。

第二個是 Agent Debugger。

它負責讀取 Code Agent 的運行軌跡，把大量 trace 壓縮成可讀的失敗報告。一個 benchmark 跑下來，原始 trace 可能非常長，直接交給模型讀取成本太高。Agent Debugger 會把這些軌跡變成 overview 和 per-task analysis，讓後續修改有證據可依。

第三個是 Evolve Agent。

它讀取上一輪的運行結果、失敗分析、歷史修改記錄，然後在 workspace 裡修改 harness 文件。它能修改的對象包括 prompt、tools、middleware、memory、skills、sub-agent config 等。

AHE 給這個過程加了很強的工程約束：

每次修改必須落到文件。每次修改要寫 manifest。下一輪要驗證 manifest 裡的預測。效果不好要能回滾。整個過程儘量留下可檢查的證據鏈。

self-reflection agent 要求回答更具體的問題：改了哪個文件，為什麼改，預計修哪些任務，可能傷害哪些任務，下一輪結果是否驗證了這個判斷。

五、AHE 把 Harness 拆成了哪些可演化組件

AHE 的第一步，是把 harness 拆成明確的組件。

論文中強調了幾類可演化對象：

System Prompt：規定 Code Agent 的基本行為，比如非交互執行 shell、完成任務前檢查狀態、不要提前退出。

Tool Descriptions：模型看到的工具說明。工具本身可能沒變，但工具說明變了，模型調用方式也會變。

Tool Implementations：工具的真實實現。比如 shell 工具如何執行命令，如何處理 timeout，如何截斷輸出，如何返回錯誤信息。

Middleware：運行時攔截層。它可以在工具調用前後做檢查，比如識別危險命令、提醒任務未驗證、阻止過早結束、記錄風險狀態。

Skills：可複用經驗。可以理解為某些任務模式下的操作手冊。

Sub-agents：子 agent 配置。複雜任務可以拆給不同角色處理。

Long-term Memory：長期記憶。用於跨任務、跨輪次沉澱經驗。

這套拆分讓 Evolve Agent 的 action space 更豐富。它可以根據失敗證據選擇合適的位置動手。

舉個例子：Code Agent 總是在 shell 中卡死。最低效的處理方式是繼續加 prompt 提醒。AHE 的路徑更工程化：shell tool 加 timeout；middleware 檢查明顯交互式命令；返回信息裡明確提示失敗原因；system prompt 再補充行為約束。

這類結構性改動更穩定，也更容易被複用和回滾。

關鍵是搞清楚定位：prompt 是行為建議，tool、middleware、memory 是執行機制。

AHE 的價值就在於把這些執行機制也納入演化範圍。

六、三層可觀測性：AHE 如何避免盲目搜索

只讓一個 agent 隨機改文件，再跑 benchmark，價值很有限。AHE 的核心設計是三層 observability。

1. Component Observability：組件可觀測

組件可觀測，指系統知道 harness 有哪些組成部分，也知道每一部分在哪裡、怎麼改、怎麼註冊。

在 AHE 倉庫裡，prompt、tool description、tool implementation、middleware、memory 等都以文件形式出現。新增工具要有 YAML 描述和 Python 實現，還要在配置裡註冊；新增 middleware 也要明確接入；新增 skill 或 sub-agent 同樣要通過配置暴露。

2. Experience Observability：經驗可觀測

經驗可觀測，指 agent 運行之後，系統記錄它是怎麼成功、怎麼失敗的。

AHE 會收集每個任務的 trace、runtime log、reward 等信息。隨後，Agent Debugger 會把這些原始軌跡壓縮成分析報告。

一個 coding agent 失敗時，單純知道“失敗了”沒有太大用。真正需要定位的是失敗層級：命令執行失敗、依賴安裝失敗、測試沒跑、文件路徑錯誤、輸出太長導致上下文汙染、agent 提前判斷任務完成、長任務中丟失前文狀態。

AHE 通過 trace 和 analysis，把失敗變成可以閱讀、可以歸納、可以行動的證據。

3. Decision Observability：決策可觀測

Evolve Agent 每次修改後，必須寫一個 change_manifest.json。這個 manifest 會記錄改了哪些文件、對應的失敗模式是什麼、為什麼選擇改這個組件、預計能修復哪些任務、可能會讓哪些任務退化、修改的約束強度如何。

下一輪評測後，系統會對照這個 manifest，看預測是否兌現。

這一步讓每次修改都變成一個可驗證假設。哪怕不使用 AHE 的完整自動演化流程，只把 change manifest 這個習慣引入自己的 agent 團隊，也會立刻提升工程透明度。

很多 agent 項目長期難以維護，根源就在這裡：改了很多 prompt，調了很多工具，但沒人知道每次改動到底解決了什麼，也沒人知道它有沒有引入新問題。AHE 的 manifest 機制，至少讓這個過程變得可審計。

七、從倉庫看 AHE 的工程組織

AHE 倉庫的主要入口是 evolve.py。它負責編排整個演化流程，包括初始化 workspace、運行評測、處理迭代目錄、做歸因、恢復和回滾。

被演化的 seed agent agents/code_agent_simple/，

裡面包括：

code_agent.yaml 描述這個 agent 如何加載 prompt、使用哪些工具、用什麼 tracer。

systemprompt.md 是初始系統提示詞。

LongTermMEMORY.md 和 ShortTermMEMORY.md 分別對應長期和短期記憶界面。tool_descriptions/ 放工具說明，tools/ 放工具實現。

Evolve Agent agents/evolve_agent/，這裡重點值得看的文件是：

evolve_agent.yaml 定義 Evolve Agent 自己可以使用哪些工具、middleware、skills.

evolve_prompt.md 一份演化契約：它規定 Evolve Agent 只能改 workspace，要基於證據修改，要寫 summary 和 manifest，要遵守註冊規則。

配置文件 configs/、configs/experiments/，其中 configs/base.yaml 是基礎配置，configs/experiments/exp-simple-code-gpt54.yaml 是一個接近論文實驗的配置 overlay。

啟動腳本 scripts/，比如 scripts/evolve.sh 用來啟動長時間實驗，scripts/build_templates.py 用來為 E2B 構建任務模板。

如果只是想理解這個項目，不需要一開始就讀所有文件。建議先按這個順序看：

README
  ↓
agents/code_agent_simple/code_agent.yaml
  ↓
agents/code_agent_simple/systemprompt.md
  ↓
agents/evolve_agent/evolve_prompt.md
  ↓
configs/base.yaml
  ↓
configs/experiments/exp-simple-code-gpt54.yaml
  ↓
evolve.py

這個順序能幫你先建立概念，再看執行細節。

八、如何上手這個倉庫：先跑一個小嚐試

AHE 不是輕量級 SDK。你不能期待 pip install 後立刻嵌進業務系統。

它更像一個研究型實驗框架。完整跑論文級實驗需要 LLM API、E2B sandbox、SERPER API、benchmark 數據、併發調度和不少 token 成本。

所以更現實的上手方式，是先跑一個最小閉環。

目標先設成：讓 AHE 的核心鏈路跑起來。

也就是：

graph LR
    A[任務運行] --> B[trace 產生]
    B --> C[analysis 生成]
    C --> D[change_manifest 寫入]
    D --> E[下一輪重新評測]
    E --> F[change_evaluation<br>判斷改動效果]

只要這條鏈路跑通，你就理解了 AHE 的實用價值。

1. 克隆倉庫

官方倉庫是：

git clone https://github.com/china-qijizhifeng/agentic-harness-engineering.git
cd agentic-harness-engineering

2. 安裝依賴

項目使用 uv 管理 Python 依賴。

uv sync

3. 配置環境變量

複製環境變量模板：

cp .env.example .env

至少需要關注這些變量：

LLM_API_KEY
LLM_BASE_URL
E2B_API_KEY
SERPER_API_KEY
GITHUB_TOKEN

Agent Debugger 也可以單獨配置模型 endpoint。實際以 .env.example 為準。

這裡要注意一點：AHE 的任務執行依賴 E2B sandbox。很多代碼運行會在隔離的遠程環境裡完成。這對安全和復現有幫助，但也意味著你需要準備 E2B 賬號和額度。

4. 準備 benchmark task templates

官方流程裡，需要先構建任務模板。示例命令是：

uv run python scripts/build_templates.py --dataset-dir /path/to/dataset -j 16

這裡的 /path/to/dataset 要換成自己的任務數據路徑。

如果只是做小嚐試，不建議一開始就準備完整 Terminal-Bench 2。先選幾個任務，把流程跑通更重要。

5. 從小配置開始

論文實驗配置可以參考：

configs/experiments/exp-simple-code-gpt54.yaml

直接跑完整配置成本比較高。可以複製一份小配置，例如：

cp configs/experiments/exp-simple-code-gpt54.yaml configs/experiments/exp-mini.yaml

然後把裡面的參數調小：

max_iterations: 2
harbor:
  k: 2
  n_concurrent: 4

如果配置支持指定任務子集，可以只放 3 到 5 個任務。小實驗的重點是驗證流程，不是追求分數。

6. 啟動演化實驗

可以用腳本啟動：

./scripts/evolve.sh configs/experiments/exp-mini.yaml

也可以直接看腳本內部如何調用 evolve.py，再按需手動啟動。

完整實驗可能會跑很久。小實驗也要關注 API 成本、E2B 併發限制、網絡穩定性。

7. 看實驗產物，而不只看分數

跑完後，不要只看 pass rate。

更值得看的是這些產物：

runs/iteration_*/
analysis/overview.md
analysis/detail/*.md
change_manifest.json
change_evaluation.json
agent/nexau_in_memory_tracer.cleaned.json
verifier/reward.txt

跑起來後重點觀察並回答幾個問題：

• 這輪失敗被歸因成了什麼模式？

• Evolve Agent 改了哪些文件？

• 它為什麼選擇改這些文件？

• manifest 裡預測會修哪些任務？

• 下一輪有沒有驗證這個預測？

• 有沒有出現修好一個任務、弄壞另一個任務的情況？

如果這些問題都能在產物裡找到答案，說明 AHE 的核心閉環已經跑起來了。

九、AHE 還沒有解決什麼

AHE 很有價值，但邊界也要說清楚。

第一，它仍然是研究型框架。完整運行成本不低，需要 benchmark、sandbox、LLM API 和較複雜的實驗配置。

第二，論文中的有效性證據還需要更多重複實驗。Terminal-Bench 2 上的提升很明確，但如果要作為強統計結論，還需要更多 seed、更多 campaign、更多置信區間報告。

第三，它對退化風險的預測還不夠強。系統比較擅長解釋這個修改可能修什麼，但還不夠擅長判斷這個修改會傷害什麼，這也是自動演化系統難的地方吧。

十、AHE 對 Agent 產品團隊的啟發

AHE 給產品型 agent 團隊最大的啟發，是把 agent 改進流程從“玄學調 prompt”拉回工程世界。

一個真實 agent 產品，遲早要面對這些問題：

• 用戶報錯後，如何復現？

• 失敗原因如何聚合？

• 某次 prompt 修改到底有沒有收益？

• 某個工具改動有沒有讓別的場景退化？

• 上線前有沒有迴歸評測？

• 線上表現變差能不能回滾？

• 有效經驗如何沉澱到 memory 或 skill？

這些問題都不是單個模型能替你解決的。

它們屬於 harness engineering 的工作範圍。

如果你也在做自己的 agent，這個倉庫值得認真拆一遍。即使不完整運行它，也能學到很多關於 harness 組織、trace 設計、修改歸因和迴歸驗證的工程方法。

常見問題

AHE 和普通 Prompt 優化有什麼區別？

普通 prompt 優化主要修改模型看到的提示詞。AHE 的範圍更大，它把 system prompt、tool descriptions、tool implementations、middleware、memory、skills、sub-agents 和評測回滾流程都視為可以演化的 harness 組件。

Coding Agent Harness 為什麼會影響 Agent 效果？

Coding agent harness 決定模型如何讀取代碼、調用工具、執行 shell、管理上下文、記錄 trace、運行測試以及判斷任務是否完成。模型能力相同的情況下，harness 設計會直接影響穩定性、成本和可復現性。

Agent 基礎設施團隊應該如何借鑑 AHE？

最實用的切入點不是立刻自動演化全部 harness，而是先建立可觀測閉環：記錄 trace、沉澱失敗歸因、寫 change manifest、做迴歸評測，並確保每次 harness 改動都能解釋、驗證和回滾。

參考

• Agentic Harness Engineering: Observability-Driven Automatic Evolution of Coding-Agent Harnesses
  arXiv: https://arxiv.org/abs/2604.25850

• AHE 官方代碼倉庫
  GitHub: https://github.com/china-qijizhifeng/agentic-harness-engineering

• Harness engineering: leveraging Codex in an agent-first world
  OpenAI Engineering Blog: https://openai.com/index/harness-engineering/