20260601

raw/articles/chensizhou-mini-agent-harness-2026.md

@@ -0,0 +1,95 @@
+---
+title: "从零搭建 Mini Agent Harness"
+author: "陈思州 (Datawhale)"
+source: "微信公众号 Datawhale干货"
+date: "2026-05"
+url: "https://mp.weixin.qq.com/s/yVFQej3dFk9KHv6J2u6Lew"
+type: "article"
+---
+
+# 从零搭建 Mini Agent Harness
+
+**作者**：陈思州，Datawhale 成员  
+**来源**：Datawhale干货（微信公众号）
+
+## 全文
+
+前面讲 Agent 评测时，我提到：评测 Agent 不能只看最终答案，还要看它用了什么工具、拿到了什么结果、有没有按任务要求完成。那这些东西要怎么稳定记录下来？这就需要一个 harness。
+
+现在有一个观点是 **Agent = model + harness**；
+
+我会把 harness 理解成：把 Agentic model 放进一个可运行、可记录、可评分的小环境里。它不一定一开始就很复杂，只要能把任务、工具、执行过程和评分结果串起来，就已经很有价值。
+
+这篇按 4 个问题梳理：
+1. 一个最 mini 的 harness 解决什么问题？
+2. 它最少需要哪些模块？
+3. 一个 eval case 可以怎么写？
+4. 公开资料里有哪些参考？
+
+### 一个最 mini 的 harness 解决什么问题
+
+如果只是手动测试 Agent，很容易只看到最后回答。比如用户问"请判断这个项目是否支持插件系统"，Agent 回答"当前 README 没有插件系统相关说明，不能确认支持"。
+
+这句话看起来合理，但我们还需要知道：它有没有真的读取 README？有没有读错文件？有没有调用无关工具？有没有把工具结果里没有的信息写进答案？
+
+mini harness 要解决的就是这个问题。
+
+它把任务放进一个固定环境里，让 Agent 使用指定工具完成任务，同时记录执行过程，最后用评分器判断结果。
+
+这样我们看到的就不只是一句回答，而是一条完整记录：任务是什么，环境里有什么，Agent 调用了什么工具，工具返回了什么，最后为什么被判成功或失败。
+
+### mini harness 最少需要哪些模块
+
+最小结构拆成 5 个模块：
+
+- **Task**（任务输入）：任务本身
+- **Environment**（可操作环境）：代码仓库、文件组等
+- **Tools**（工具接口）：read_file、list_files、run_tests 等
+- **Trace**（执行记录）：每步的工具调用、参数、返回
+- **Grader**（评分器）：规则或测试脚本判断结果
+
+### 一个 eval case 可以怎么写
+
+```json
+{
+  "id": "case_001",
+  "task": "判断项目是否支持插件系统",
+  "environment": {
+    "files": {
+      "README.md": "本项目支持本地启动、基础登录和配置管理。",
+      "config.md": "配置项包括 port、theme、log_level。"
+    }
+  },
+  "tools": ["list_files", "read_file"],
+  "grader": {
+    "must_read": ["README.md"],
+    "answer_should_include": "不能确认支持插件系统",
+    "answer_should_not_include": "支持插件系统"
+  }
+}
+```
+
+跑完后记录 trace：
+
+```json
+{
+  "case_id": "case_001",
+  "trace": [
+    {"tool": "list_files", "arguments": {"path": "."}, "result": ["README.md", "config.md"]},
+    {"tool": "read_file", "arguments": {"path": "README.md"}, "result": "本项目支持本地启动、基础登录和配置管理。"}
+  ],
+  "answer": "当前 README 没有插件系统相关说明，不能确认支持插件系统。",
+  "grade": {"success": true, "reason": "读取了 README，回答没有超出文件内容。"}
+}
+```
+
+### 公开资料参考
+
+- **Anthropic Agent Evals**：区分 eval harness 和 agent harness，强调评估的是模型+harness 的整体效果
+- **SWE-agent**：提出 Agent-Computer Interface（ACI），说明外部接口设计对 Agent 表现的影响
+- **Terminal-Bench**：任务结构包含 instruction、隔离环境、测试脚本
+- **SWE-bench**：典型评测流程——真实 issue → patch → 环境测试
+
+### 核心观点
+
+一个 mini Agent harness 不需要一开始做成完整平台。第一版只要能串起任务、环境、工具、执行记录和评分器，就已经能帮我们观察 Agent 到底哪里出问题。有了这套结构，我们就不只是"试一下 Agent 好不好用"，而是能分析问题出在任务理解、工具选择、参数填写、结果读取、步骤冗余，还是评分规则本身不清楚。