科普 Harness 工程——AI Agent 时代的测试基础设施

从 SWE-bench 到企业级实践：AI Agent 评测一站通关

---

一、什么是 Harness

1.1 一句话定义

Harness（测试脚手架）= 一套评估 / 测试 AI Agent 的基础设施：给 Agent 一个任务、给它一个运行环境、让它执行、记录结果、给出评分。

1.2 词源

领域	Harness 含义
马具	套在马身上的"装备"（缰绳 + 鞍具）—— 让马能被控制
软件测试	测试脚手架 —— 让测试能被自动化
AI Agent	Agent 评测脚手架 —— 让 Agent 行为可被量化评估

1.3 传统 Test Harness vs AI Agent Harness

维度	传统 Test Harness	AI Agent Harness
被测对象	单元 / 集成代码	AI Agent
输入	函数参数	自然语言任务
断言	精确值匹配	多模态评估 / LLM 评委
执行	同步 / 毫秒级	异步 / 秒~分钟
结果	pass / fail	通过率 / 步骤轨迹 / 评分

1.4 AI Agent Harness 整体架构

1.5 6 大核心地图

---

二、核心 1：Harness 定义与起源

2.1 一句话定义

Harness = 测试脚手架，把"测试什么 / 怎么测试 / 如何评分"全部封装起来的工具集。

2.2 为什么 AI 时代需要 Harness？

痛点	传统方式	Harness 方式
Agent 效果不稳定	“感觉不错”	量化评分
改动无法回归	人工测试	自动评测
多模型对比难	“A 比 B 好”	标准化基准
上线前评估	等用户反馈	提前量化

2.3 Harness 的 4 个核心角色

2.4 关键点

• ✅ Harness = “AI Agent 的 QA 工具”
• ✅ 从"凭感觉"到"量化"的关键基础设施
• ✅ 传统测试 + AI 评测的桥梁
• ❌ 不是简单的单元测试（需要处理多模态 / 长链路 / 不确定性）

---

三、核心 2：Harness 5 大核心能力

3.1 一句话定义

Harness 的 5 大核心能力 = 任务 / 环境 / 执行 / 评估 / 反馈，缺一不可。

3.2 5 大能力详解

能力 1：任务定义（Task Spec）

问题：要测什么？

{
  "task_id": "fix_bug_123",
  "description": "修复 UserService.java 中的 NPE",
  "repo": "https://github.com/example/repo",
  "base_commit": "abc123",
  "expected_files": ["UserService.java"],
  "test_files": ["UserServiceTest.java"]
}

能力 2：运行环境（Environment）

问题：在什么环境跑？

能力 3：执行控制（Execution）

问题：怎么让 Agent 跑起来？

控制点	实现
超时控制	任务 5 分钟超时
Token 限制	单任务 < 10K tokens
步骤限制	最多 50 步
工具调用	提供 Bash / Edit / Read 等

能力 4：评估打分（Evaluator）

方法	适用场景	优点	缺点
测试通过率	SWE-bench / 代码任务	客观	只看结果
代码 diff	Bug 修复任务	精确	容易误判
LLM 评委	开放式任务	灵活	主观
行为轨迹	调试 Agent	可解释	难量化

能力 5：反馈改进（Feedback）

问题：评测结果怎么用？

3.3 关键点

• ✅ 5 大能力缺一不可
• ✅ 任务 + 环境是"题面"，执行 + 评估是"打分"，反馈是"改进"
• ✅ 没有反馈的 Harness = 一次性评测
• ❌ 不要只看"通过率"（看不到 Agent 的真实能力）

---

四、核心 3：评测体系

4.1 一句话定义

评测体系 = 用一套标准化的指标（Pass@k、成功率、效率分），量化 Agent 的能力。

4.2 6 大评测指标

4.3 指标详解

指标	公式	含义
Pass@1	1 次成功的任务数 / 总任务数	单次通过率
Pass@5	5 次内至少 1 次通过的任务数 / 总任务数	多次尝试的稳定性
任务成功率	成功任务数 / 总任务数	整体能力
平均步数	总步数 / 任务数	效率
Token 效率	Token 总数 / 任务数	成本
失败类型分布	每类失败占比	改进方向

4.4 关键点

• ✅ Pass@k 是核心指标（k 越大越能反映 Agent 真实能力）
• ✅ 多指标组合（不要只看通过率）
• ✅ 失败类型分类很关键（API 错 / 逻辑错 / 超时）
• ❌ 不要用单一指标定 Agent 优劣

---

五、核心 4：主流框架对比

5.1 一句话定义

主流 Agent Harness 框架 = SWE-bench / AgentBench / LangSmith / Phoenix 等，各有侧重。

5.2 4 大主流框架

5.3 框架对比

框架	侧重点	适用场景	优点	缺点
SWE-bench ⭐	代码 Bug 修复	Agent 编程能力	业界标准	任务固定
AgentBench	通用任务	Agent 综合能力	任务多样	难度不一
LangSmith	LangChain 调试	LangChain 应用	链路追踪	绑定框架
Phoenix	可观测性	LLM 应用监控	开源 / 通用	学习成本

5.4 关键点

• ✅ SWE-bench 是"业界标准"（评估 Agent 编程能力必看）
• ✅ 不同框架各有侧重，按需选
• ✅ 企业级通常自研 + 集成开源框架
• ❌ 不要迷信单一框架

---

六、核心 5：SWE-bench 深度拆解 ⭐ 重头

6.1 一句话定义

SWE-bench = 真实 GitHub Issue + 真实代码仓库，让 Agent 修 Bug，自动用 PR 测试集评测。

6.2 SWE-bench 5 大要素

6.3 SWE-bench 评测流程

6.4 SWE-bench 版本演进

版本	任务数	特点
SWE-bench Lite	300	子集，快
SWE-bench Verified	500	人工验证质量
SWE-bench Multimodal	617	多模态 Issue
SWE-bench Full	2294	全部任务

6.5 主流 Agent 的 SWE-bench 分数（2024-2025）

Agent	SWE-bench Verified	备注
Claude 4 Sonnet	~65% ⭐	当前最强
GPT-5	~60%	接近 Claude
Claude 3.5 Sonnet	~49%	上一代
DeepSeek-V3	~42%	开源 SOTA
GPT-4o	~33%	上一代 OpenAI

6.6 关键点

• ✅ SWE-bench Verified 是当前最权威的评测
• ✅ Claude 4 已经 65% 通过（接近人类水平）
• ✅ Pass@1 ≈ 49-65% 是 Agent 编程能力的"分数线"
• ❌ 不要只看分数（要看任务类型 + 实际使用场景）

---

七、核心 6：企业级实践：自己搭 Harness

7.1 一句话定义

自己搭 Harness = 5 步搭一个最小可用的 Agent 评测系统：任务定义 → 环境 → 执行 → 评估 → 报告。

7.2 5 步搭最小 Harness

7.3 完整示例（Python）

# 最小 Harness 实现（伪代码）
import docker
from agent_sdk import Agent

class AgentHarness:
    def __init__(self):
        self.client = docker.from_env()

    def run_task(self, task):
        # Step 1: 启动 Docker 容器
        container = self.client.containers.run(
            "python:3.11",
            command="bash",
            detach=True,
            volumes={task.workspace: {"bind": "/repo", "mode": "rw"}}
        )

        try:
            # Step 2: 启动 Agent
            agent = Agent(model="claude-4-sonnet")

            # Step 3: 执行任务
            result = agent.run(
                task_description=task.description,
                working_dir="/repo",
                timeout=300,
                max_steps=50
            )

            # Step 4: 评估
            score = self.evaluate(result, task)

            # Step 5: 返回报告
            return {
                "task_id": task.id,
                "score": score,
                "trajectory": result.trajectory,
                "tokens": result.token_usage,
                "steps": len(result.trajectory)
            }
        finally:
            container.remove(force=True)

    def evaluate(self, result, task):
        # 跑 PR 测试集
        test_result = run_tests(
            container=result.container,
            test_files=task.test_files
        )
        return {
            "passed": test_result.passed,
            "failed": test_result.failed,
            "pass_rate": test_result.passed / test_result.total
        }

7.4 关键点

• ✅ 从最小可用 Harness 开始（不要一开始就做完整）
• ✅ Docker 隔离环境是必须的（防止污染）
• ✅ 超时 + Token + 步数限制 3 重防护
• ❌ 不要把 Agent 和 Harness 耦合太紧

---

八、6 大核心的关系图

金句：Harness 是"AI Agent 的 QA 工具集"——从定义到能力、从评测到框架、从标准到实践，6 大核心组成完整的 Agent 测试基础设施。

---

九、5 个常见误区

#	误区	真相
1	“Agent 答得对就行”	需要量化指标（Pass@k / 成功率）
2	“SWE-bench 分数高 = Agent 好”	分数高但场景不对，仍然不能用
3	“一次评测够了”	Agent 评估要多次 + 多次任务 + 不同场景
4	“LLM 评委准”	LLM 评委需要校准（用人类评分对齐）
5	“不用 Harness 也能上线”	不上 Harness = 等用户当评委

---

十、工具栈推荐

层	推荐工具
任务定义	SWE-bench / 自建 YAML / JSON
运行环境	Docker / Kubernetes
Agent 框架	Claude Agent SDK / LangGraph / AutoGen
评测框架	SWE-bench Verified / AgentBench / 自研
可观测性	LangSmith / Phoenix / Helicone
报告	Pandas / Streamlit / 自建 Web

推荐学习路径

---

十一、6 步学习路径

1. 第 1 步：理解 Harness 是什么（AI Agent 的 QA 工具）
2. 第 2 步：掌握 5 大能力（任务 / 环境 / 执行 / 评估 / 反馈）
3. 第 3 步：理解评测体系（Pass@k / 成功率 / 效率）
4. 第 4 步：对比主流框架（SWE-bench / AgentBench）
5. 第 5 步：深度学习 SWE-bench（业界标准）
6. 第 6 步：自己搭 Harness（5 步实战）

---

十二、推荐阅读

如果你想深入学 Harness 工程，这些资料值得读：

• 📚 《Software Testing》（Sommerville）—— 软件测试基础
• 📚 《LLM Evaluation》—— LLM 评测综述
• 📖 SWE-bench 官方论文（arXiv:2310.06770）—— Agent 评测基准
• 📖 AgentBench 官方论文（arXiv:2308.03688）—— 通用 Agent 评测
• 📖 LangSmith 文档—— LangChain 可观测性
• 🔗 SWE-bench GitHub—— 跑一遍 Lite / Verified
• 🔗 OpenAI Evals—— OpenAI 官方评测框架

---

十三、附录

一句话总结 6 大核心

核心	一句话
定义与起源	Harness = AI Agent 的 QA 工具集
5 大核心能力	任务 / 环境 / 执行 / 评估 / 反馈
评测体系	Pass@k + 成功率 + 效率多维评估
主流框架	SWE-bench / AgentBench / LangSmith / Phoenix
SWE-bench	真实 GitHub Issue + 真实仓库 + 自动评分
企业级实践	5 步搭最小可用 Harness

5 个面试常问问题

Q1：什么是 AI Agent Harness？

评估 / 测试 AI Agent 的基础设施：给 Agent 一个任务、给它一个运行环境、让它执行、记录结果、给出评分。

Q2：SWE-bench 是什么？

真实 GitHub Issue + 真实代码仓库，让 Agent 修 Bug，自动用 PR 测试集评测的 Agent 编程能力基准。

Q3：SWE-bench Verified 和 Lite 的区别？

• Lite：300 个任务（子集，2-4 小时跑完）
• Verified：500 个任务（人工验证质量，更权威）
• Multimodal：617 个任务（带截图）
• Full：2294 个任务（全部）

Q4：怎么评估 Agent 的代码能力？

用 SWE-bench Verified 的 Pass@1 分数。当前 SOTA：

• Claude 4 Sonnet：~65%
• GPT-5：~60%
• Claude 3.5 Sonnet：~49%

Q5：企业级怎么自己搭 Harness？

5 步：任务定义 → 搭环境（Docker）→ 执行 Agent → 评估打分 → 生成报告。关键是要"量化"+“反馈”，不是一次性评测。