Harness Engineering 实践：用 AI Agent 自动评测并迭代优化系统

传统的软件评测通常依赖人工准备评测集：先定义评测目标，再收集用例，之后回放用例、观察指标、整理报告。流程本身并不复杂，真正麻烦的是用例收集和执行过程都很耗时间，尤其当系统包含 AI 能力、内容生成能力或者复杂 UI（用户界面）交互时，人工评测会很快变成重复劳动。

Harness Engineering 的思路是把系统外面套一层“可被控制的评测夹具”。这层夹具不直接替代业务系统，而是负责定义任务、生成评测集、调度执行、收集结果、产出报告，必要时再把报告交给能写代码的 AI Agent（智能体）继续修改系统。人只负责描述目标和边界，剩下的重复动作交给智能体完成。

一个完整的自动评测平台可以抽象成这样：

flowchart LR
    H[人：描述评测目标和约束] --> A[AI Agent]
    P[评测平台<br/>Workspace / API Key / Skill说明] --> A

    A --> T[创建评测任务]
    A --> C[生成评测集]
    A --> R[执行评测]
    R --> S[被测系统<br/>API / MCP / Web UI / 本地服务]
    S --> R
    R --> G[提交评测报告]

    G --> O{是否需要优化}
    O -- 否 --> E[归档结果]
    O -- 是 --> D[AI Coding 修改代码]
    D --> V[启动服务并验证]
    V --> T

这套流程不只是自动化测试。它更像是把“评测—反馈—修改—再评测”的工程闭环标准化，让 AI Agent 可以沿着明确的协议持续工作。

评测平台要抽象出哪些对象

平台不需要一开始做得很复杂，但至少要有三个核心对象：评测任务、评测集、评测报告。再加上工作空间和权限控制，就能支撑多项目、多 Agent 同时运行。

平台最好把入口设计成 AI Agent 友好的形式，例如提供一份 skill-setup.md，里面写清楚可用接口、数据结构、调用顺序和注意事项。这样 Agent 只要拿到这份说明和 API Key（应用程序编程接口密钥），就能开始创建任务、生成用例、执行评测和提交报告。

一个典型的任务数据可以长这样：

{
  "name": "文档 MCP 工具全功能评测",
  "target": "评测文档 MCP 的创建、读取、更新、删除、搜索和权限相关能力",
  "acceptanceCriteria": [
    "核心工具调用能够成功返回",
    "异常输入有明确错误提示",
    "数据写入后能够被后续读取验证",
    "评测报告需要列出失败用例和扣分原因"
  ],
  "version": "v1",
  "status": "created"
}

评测集则更偏执行层：

{
  "caseId": "TC-Create-Doc-001",
  "type": "standard",
  "title": "创建一个新文档并读取内容",
  "steps": [
    "调用 createDocument 创建标题为 Demo 的文档",
    "向文档写入一段测试内容",
    "调用 readDocument 读取文档内容"
  ],
  "expected": "读取结果包含刚写入的测试内容，且文档 ID 可用于后续操作",
  "weight": 10
}

标准评测集和 Rubrics 评测集

并不是所有结果都能用“成功 / 失败”判断。接口是否返回、按钮是否可点击，这类适合标准评测；生成内容是否准确、页面视觉是否协调、汇报文稿质量是否达标，就需要 Rubrics。

Rubrics 可以理解为分级评分规则。它不是问“有没有成功”，而是问“好到什么程度”。

以 OKR（Objectives and Key Results，目标与关键结果）查询为例，如果只判断“查出来没有”，评测会很粗糙。更合理的 Rubrics 可以这样设计：

对于 AI 系统，Rubrics 非常重要。模型输出经常不是完全错误，而是“能用但不够好”。如果平台只能记录成功失败，就无法指导后续优化。

无 UI 场景：让 Agent 自动评测 MCP 工具

无 UI 评测最容易起步，因为 Agent 可以直接通过终端、接口或 MCP 工具完成操作。MCP（Model Context Protocol，模型上下文协议）常用于让大模型调用外部工具，例如文档、数据库、知识库或业务系统能力。

启动评测时，人只需要给 Agent 一段明确指令：

阅读 https://eval.example.com/skill-setup.md?api_key=***
当前 workspace 的 apiKey=***

目标：评测某文档 MCP 工具的完整能力。
要求：
1. 创建一个评测任务，写清楚评测目标和验收标准；
2. 至少生成 10 个评测用例，覆盖创建、读取、更新、删除、搜索、异常输入等能力；
3. 按评测集逐项执行；
4. 提交结构化评测报告，给出总分、失败用例和扣分原因。

Agent 拿到指令后，会经历这样的调用链：

sequenceDiagram
    participant Human as 人
    participant Agent as AI Agent
    participant Platform as 评测平台
    participant MCP as 文档 MCP
    participant Report as 评测报告

    Human->>Agent: 提供 skill 说明和评测目标
    Agent->>Platform: 创建评测任务
    Agent->>Platform: 生成评测集
    loop 每个用例
        Agent->>MCP: 调用 MCP 工具执行步骤
        MCP-->>Agent: 返回执行结果
        Agent->>Agent: 对比预期结果
    end
    Agent->>Platform: 提交用例结果
    Agent->>Report: 生成总分、问题和建议
    Report-->>Platform: 归档报告

这种模式适合评测：

• MCP 工具包；
• REST API；
• 命令行工具；
• 数据处理脚本；
• Agent skill 包；
• 后端服务的核心能力。

报告不能只写一个总分，必须包含证据。比如某个创建文件夹用例扣分，报告里应该说明：调用成功了，但名称被自动追加了 (1)，说明系统可能做了同名处理；问题在于接口没有返回冲突提示，用户或调用方不容易理解为什么名称发生变化。

这类问题人工也能发现，但 AI Agent 可以一次性覆盖大量组合路径，并把每条路径的操作结果整理成统一结构。

UI 场景：不只测按钮，还要测内容质量

带 UI 的评测更复杂。Agent 需要连接浏览器，复用登录态，打开目标页面，像用户一样点击、输入、等待结果，再根据页面内容判断质量。

如果系统是一个“输入文本或导入文档后生成汇报文稿”的工具，评测目标就不只是“页面有没有报错”。更有价值的评测应该同时覆盖功能和产出质量。

可以给 Agent 这样的任务描述：

阅读 https://eval.example.com/skill-setup.md?api_key=***
打开浏览器并进入汇报生成平台。

目标：自动评测最近生成的 5 个汇报项目。
要求：
1. 为 5 个项目分别创建评测用例；
2. 每个项目都要检查功能是否正常，包括能否打开、预览、导出、切换页面；
3. 对生成内容做 Rubrics 评分，包括内容完整性、结构清晰度、视觉一致性、图文匹配度；
4. 提交一份总报告，列出每个项目的功能问题和质量问题。

UI 评测可以按这些维度拆分：

UI 评测的关键不是让 Agent “随便看看页面”，而是给它稳定的评测规则。对于内容生成类系统，Rubrics 应该尽量细化，否则 Agent 很容易给出泛泛的“质量不错”“整体良好”之类判断，这种报告无法指导改进。

自动优化：让评测报告进入代码修改闭环

评测平台的价值不止于生成报告。对于能由 AI Coding 维护的系统，可以让 Agent 读取报告后直接修改代码，然后再次评测。这个过程会形成多轮优化闭环。

flowchart TD
    A[版本 v1] --> B[生成评测任务和评测集]
    B --> C[执行标准评测和 Rubrics 评测]
    C --> D[生成报告：分数、缺陷、建议]
    D --> E[AI Coding 修改代码]
    E --> F[本地启动服务并验证]
    F --> G{达到轮次或分数目标?}
    G -- 否 --> H[归档当前版本]
    H --> B
    G -- 是 --> I[输出最终对比报告]

启动这种任务时，提示词要把轮次、边界和禁止事项写清楚：

阅读 https://eval.example.com/skill-setup.md?api_key=***
当前 workspace 的 apiKey=***

目标：对功能 A 和功能 B 做自动评测与优化。
流程要求：
1. 创建 v1 评测任务，生成标准评测集和 Rubrics 评测集；
2. 执行所有用例并提交报告；
3. 根据报告修改代码，但不能修改评分规则来规避问题；
4. 启动本地服务完成基本验证；
5. 归档当前版本，继续 v2、v3；
6. 至少完成 3 轮迭代；
7. 最终输出三轮分数对比、主要修改点和仍然存在的问题。

一次三轮迭代可以记录成这样的结果：

这里的重点不是分数本身，而是每一轮都要留下可追溯证据：哪些用例失败了，失败原因是什么，改了哪些代码，重新评测后是否真的改善。如果 Agent 只给出一个更高分，却没有用例级证据，分数很容易失真。

评分最好结构化，而不是一段自然语言

评测报告可以有自然语言说明，但底层最好是结构化数据。结构化报告更容易被下一轮 Agent 消费，也方便做趋势对比。

一个报告对象可以包含这些字段：

{
  "taskId": "task-001",
  "version": "v2",
  "score": 97.4,
  "cases": [
    {
      "caseId": "TC-001",
      "status": "passed",
      "score": 10,
      "evidence": "成功创建文档并读取到一致内容"
    },
    {
      "caseId": "TC-010",
      "status": "partial",
      "score": 7,
      "evidence": "同名文件夹被自动追加序号，但接口未返回冲突提示",
      "suggestion": "返回明确的 duplicateName 提示，并提供自动重命名说明"
    }
  ],
  "issues": [
    {
      "severity": "medium",
      "module": "folder-create",
      "description": "同名处理缺少显式提示",
      "recommendedFix": "补充冲突检测返回字段"
    }
  ]
}

总分可以按权重计算：

总分 = Σ(用例得分 × 用例权重) / Σ(用例权重)

Rubrics 也可以拆成多个维度：

内容质量分 = 准确性 × 0.4 + 完整性 × 0.25 + 结构清晰度 × 0.2 + 表达质量 × 0.15

这样做的好处是，优化 Agent 不必猜测“哪里不好”，它可以直接看到低分维度，再定位要改提示词、改交互、改数据处理逻辑，还是改 UI 状态反馈。

适合和不适合的场景

自动评测不是把所有权限都交出去。更合理的做法是给 Agent 一个受限工作空间，让它能创建任务、执行沙箱评测、读取必要数据，但不能随意操作生产环境。

落地时最容易踩的坑

UI 不规范会让 Agent 迷路

如果页面缺少稳定选择器、按钮文案频繁变化、加载状态不明确，Agent 很容易点错位置或误判结果。这个问题表面上是“AI 不会测”，实际也说明真实用户可能同样会迷路。

更适合自动化评测的 UI 应该具备：

• 关键元素有稳定的 data-testid 或语义化标签；
• 加载中、成功、失败状态明确；
• 弹窗、遮罩、浮层不会随机打断主流程；
• 错误提示能说明原因，而不是只有“操作失败”；
• 页面结构符合常见浏览器自动化工具的访问方式。

本地环境必须能被 Agent 启动

自动优化要求 Agent 修改代码后自己验证。如果项目启动方式依赖大量口口相传的约定，或者本地服务长期不可用，Agent 会耗费大量时间处理环境问题。

建议把启动和验证命令显式写进仓库：

# 安装依赖
pnpm install

# 启动开发服务
pnpm dev

# 执行单元测试
pnpm test

# 执行端到端测试
pnpm e2e

再配一份机器可读的说明：

dev:
  install: pnpm install
  start: pnpm dev
  test: pnpm test
  healthcheck: http://localhost:3000/health

不能让 Agent 修改评分规则来“刷分”

自动优化有一个典型风险：Agent 发现改系统很难，转而修改测试、评分规则或绕过失败用例。平台需要把评测集、评分标准和系统代码分开管理，并记录每轮评测使用的用例版本。

更稳妥的策略是：

• 基线评测集冻结；
• 新增用例可以进入下一轮，但不能删除失败用例；
• 评分规则变更需要单独审批；
• 报告必须包含执行证据；
• 代码 diff 和评测结果一起归档。

AI 输出有随机性，单次得分不一定可靠

涉及大模型输出时，同一个输入可能产生不同结果。对于关键用例，可以重复执行多次后取平均分，或者记录最低分作为稳定性指标。

稳定性分 = 1 - 多次执行结果的方差惩罚

如果某个功能平均分很高，但波动很大，用户体验仍然可能不稳定。评测报告应该把均值和波动都记录下来。

一个可执行的最小版本

不需要一开始就做完整平台。最小可用版本只要满足四件事：

flowchart LR
    A[一份 skill-setup.md] --> B[Agent 知道怎么调用平台]
    B --> C[创建任务和用例]
    C --> D[执行并提交报告]
    D --> E[人或 Agent 根据报告修复问题]

可以按这个顺序建设：

1. 定义任务、用例、报告的数据结构；
2. 提供创建任务、创建用例、提交报告三个接口；
3. 写一份面向 AI Agent 的 skill 说明；
4. 让 Agent 在无 UI 场景跑通一次完整评测；
5. 增加 Rubrics 支持；
6. 接入浏览器自动化，覆盖 UI 场景；
7. 把报告交给 AI Coding，形成多轮优化闭环。

Harness Engineering 的核心不是“让 AI 随便帮忙测试”，而是把评测工作拆成 Agent 能理解、能执行、能复盘的工程协议。只要任务目标清楚、用例结构明确、报告可追溯，AI Agent 就能承担大量重复评测工作；当系统本身具备可启动、可验证、可回滚的工程基础时，多轮自动优化也能真正跑起来。