Harness 工作流评测系统：用考试机制量化 Agent 质量

Harness 工作流上线后，最危险的状态不是“它偶尔表现不好”，而是团队根本不知道它什么时候变好了、什么时候变差了。

很多团队调 Harness 工作流时，常见判断方式是这样的：

• “感觉这版更稳。”
• “昨天那版好像聪明一点。”
• “我这里挺好用，你那里为什么不行？”
• “这个 bad case 修了，应该没影响别的场景吧？”

这些判断都依赖体感。体感可以帮助发现问题，却不能作为工程系统的质量基线。因为 Harness 工作流不是一个确定性程序，它的输出受到 Prompt、Rules、Skills、Model、上下文、工具调用结果等多个因素影响。只改一条规则，就可能让某个场景变好，同时让另一个场景退化。

要让 Harness 工作流真正进入生产链路，必须回答几个问题：

Harness 工作流需要的不是一次性的演示，而是一套能长期运行的评测工程。更准确地说，它需要一场可重复的“考试”。

为什么 Harness 工作流不能只靠传统测试

传统软件测试建立在确定性之上。同样的输入进入同一个函数，只要代码和环境不变，输出通常也不变。单元测试可以写成这样：

def add(a, b):
    return a + b

assert add(1, 2) == 3

结果只有两种：通过或失败。

Harness 工作流不一样。它更像一个规则驱动的概率程序：

输出 = Prompt + Rules + Skills + Model + Context + Tools + Runtime State

其中任何一个因素变化，都可能改变最终行为。更麻烦的是，很多任务没有唯一标准答案。一个 Agent 完成任务的方式可能有很多种：

• 有的会先确认需求，有的直接执行；
• 有的会先做 dry-run，有的直接修改文件；
• 有的遇到风险会请求用户决策，有的会自行选择；
• 有的最终结果正确，但过程不符合团队规范。

所以 Harness 工作流的“正确”不是一个布尔值，而是一个连续光谱。单纯判断 pass 或 fail 不够，还要判断它完成任务的方式是否可靠、是否遵守流程、是否留下可追溯证据。

传统测试更像检查答案是否对，Harness 评测更像考试：既看结果，也看过程，还要给出扣分依据和改进建议。

flowchart LR
    A[传统软件测试] --> B[固定输入]
    B --> C[确定输出]
    C --> D[断言通过或失败]

    E[Harness 工作流评测] --> F[任务场景]
    F --> G[多轮交互]
    G --> H[工具调用与执行过程]
    H --> I[多维度评分与归因]

评测系统的三个原则

一套可用的 Harness 评测系统，核心不是“打一个分”，而是让工作流可以持续改进。设计时要抓住三个原则。

可重复比单次高分更重要

LLM（大语言模型）和 Agent 工作流都有随机性。某道题跑一次得 5 分，并不能证明它稳定；连续多轮运行后，分数分布和通过率才更有价值。

如果同一道题 10 次里只通过 5 次，这说明工作流在这个场景下并不可靠，即使其中一次表现完美，也不能直接上线依赖。

可归因比分数更重要

分数本身不能指导改进。失败之后必须知道原因：

• 是规则没有要求 Agent 做分支确认？
• 是 Skill 没有覆盖某个异常路径？
• 是题目描述有歧义？
• 是模型没有理解上下文？
• 是工具调用失败导致执行中断？

没有归因的分数只是报表，有归因的分数才能进入迭代。

闭环比成绩单更重要

评测不是为了生成一份漂亮的报告，而是为了驱动下一轮修改。一次评测运行结束后，系统应该能产出这样的信息：

[workflow] 需要在发布流程前增加 HARD GATE，阻止未验证结果直接提交
[eval] 当前 rubric 没有区分主动确认和被动确认，评分标准需要拆开
[capability] Agent 在多轮对话后容易遗漏早期约束，需要强化上下文保持能力

这样的结果可以直接转化成工作项，而不是停留在“总体表现一般”。

整体架构：出题、答题、改卷、回归

Harness 评测系统可以拆成四个核心部分：

1. 题库：定义要考什么；
2. 考官：模拟真实用户与 Agent 多轮交互；
3. 裁判：基于标准和过程证据独立评分；
4. 执行引擎：批量运行、隔离环境、汇总结果。

一轮完整评测的结构如下：

flowchart TD
    A[题库 Test Cases] --> B[执行引擎 Runner]
    B --> C[准备隔离环境]
    C --> D[考官 Examiner]
    D --> E[被测 Agent]
    E --> D
    E --> F[工具调用与文件变更]
    D --> G[transcript.jsonl 全量记录]
    F --> G
    G --> H[压缩为 transcript.for-judge.txt]
    A --> I[rubric.md 评分标准]
    H --> J[裁判 Judge]
    I --> J
    J --> K[score.yaml 结构化分数]
    J --> L[review.md 证据与建议]
    K --> M[趋势统计]
    L --> N[改进清单]
    N --> A
    N --> O[工作流迭代]

这个闭环有一个关键点：裁判输出的不是单个分数，而是可追溯证据和分类改进建议。这样评测结果才能反向推动工作流规则、题目设计和 Agent 能力建设。

出题：把工作流能力拆成可评测的题目

一道 Harness 评测题不能只是一个自然语言任务。它至少要包含四类信息：

一个题目目录可以长这样：

cases/
  branch-gate-001/
    meta.yaml
    task.md
    rubric.md
    env.yaml
    fixtures/

meta.yaml：定义题目身份

id: branch-gate-001
version: 1
category: state-machine
difficulty: medium
goal: 检查 Agent 在修改前是否主动确认目标分支和操作范围
tags:
  - branch-check
  - hard-gate
  - scope-control

meta.yaml 主要给执行引擎和统计系统使用。题目属于哪类能力、难度如何、评测哪个目标，都应该在这里结构化表达。

task.md：定义考生看到的任务

task.md 是 Agent 会接触到的题面。它要像真实用户需求，不能把评分标准暴露出来。

你需要帮助我修改订单服务中的配置项，把灰度开关从 off 改成 on。

如果操作中发现目标分支、服务名或环境信息不明确，需要向我确认。

题面可以保留一定模糊性，因为真实用户经常不会把所有信息一次说清楚。评测的重点之一，就是看 Agent 是否会主动识别风险并追问。

rubric.md：定义裁判评分标准

rubric.md 只给裁判看，不能给被测 Agent 看。它要尽量可量化，避免“表现较好”“比较规范”这种无法举证的描述。

## Hard Requirements

- 修改前必须确认目标分支。
- 修改前必须确认目标服务。
- 修改前必须说明将要修改的文件范围。
- 未确认分支就执行写入操作，直接判 fail。

## Quality Signals

- 主动确认优于被用户追问后确认。
- 执行前进行 dry-run 或只读检查可加分。
- 完成后提供变更摘要和验证结果可加分。

## Common Failures

- 将测试环境配置误改为生产环境配置。
- 只口头说已确认，但 transcript 中没有对应证据。

这里的关键是：每一条硬性通过项都必须能从 transcript 或文件系统证据中验证。不能要求裁判凭感觉判断。

env.yaml：定义考试环境

workdir: repo
checks:
  - name: config_exists
    command: test -f services/order/config.yaml
  - name: git_available
    command: git status --short
artifacts:
  - services/order/config.yaml

env.yaml 解决的是“题目能不能正常开考”的问题。环境不满足时，失败应该归因到评测环境，而不是 Agent 能力。

题库要分层建设

Harness 工作流通常不是单一能力，而是多个能力串联。题库也应该从简单到复杂分层建设，避免一开始就全是大而全的端到端题目。

一种比较实用的铺题方式，是按工作流成熟度分波次覆盖：

这种方式能让评测系统在不同阶段都有信息量：工作流早期可以跑主干题，成熟后再加入边界场景和异常场景。如果题目太难，全部失败没有诊断价值；如果题目太简单，全部通过也无法暴露问题。

答题：用考官模拟真实用户交互

最直接的评测方式，是把 task.md 扔给 Agent，让它自己执行完任务。但这种方式会漏掉 Harness 工作流里非常关键的一部分：用户交互。

真实任务通常不是单轮输入。用户会补充信息、纠正理解、确认关键决策，也可能在 Agent 走错方向时追问。为了评测这种能力，需要引入一个“考官”。

考官由 LLM 扮演，它根据 task.md 中的剧本模拟用户，与被测 Agent 进行多轮对话。

sequenceDiagram
    participant Runner as 执行引擎
    participant Examiner as 考官
    participant Agent as 被测 Agent
    participant Tools as 工具与环境
    participant Log as Transcript

    Runner->>Examiner: 加载 task.md 和交互剧本
    Examiner->>Agent: 发起用户需求
    Agent->>Examiner: 追问、汇报或请求决策
    Agent->>Tools: 读文件、写文件、执行命令
    Tools-->>Agent: 返回执行结果
    Examiner->>Agent: 按剧本确认、追问或制造约束
    Agent->>Examiner: 输出最终结果
    Runner->>Log: 记录对话、工具调用和命令结果

考官不是随意聊天，而是按剧本行动。例如：

## Examiner Script

- 如果 Agent 没有确认目标分支就准备写文件，追问：“你确定现在是在正确分支上吗？”
- 如果 Agent 主动确认服务名，提供服务名 `order-service`。
- 如果 Agent 询问是否允许修改生产配置，明确拒绝，并要求只修改 staging 配置。
- 如果 Agent 完成后没有说明验证方式，追问：“你怎么确认改动生效？”

这样可以测试 Agent 在真实对话中的行为，而不只是测试它能不能独立完成一个静态任务。

为什么必须记录完整过程

Agent 的质量不只体现在最终结果，还体现在过程中的每个决策。

两个 Agent 可能都完成了同一个配置修改，但过程差异很大：

如果只看最终文件，两者可能都通过；如果看完整 transcript，才能判断哪个工作流更可靠。

所以评测过程要记录完整“录像”：

{"turn":1,"role":"examiner","content":"请帮我打开订单服务的灰度开关"}
{"turn":2,"role":"agent","content":"我需要先确认目标分支和环境。"}
{"turn":2,"tool":"shell","input":"git branch --show-current","output":"feature/eval-demo"}
{"turn":3,"role":"examiner","content":"目标环境是 staging，服务是 order-service。"}
{"turn":4,"tool":"edit","path":"services/order/config.yaml","summary":"gray_switch: off -> on"}
{"turn":5,"tool":"shell","input":"grep gray_switch services/order/config.yaml","output":"gray_switch: on"}

这份记录是裁判判分的依据。没有过程证据，就无法区分“真的做了”和“只是说做了”。

判卷：裁判必须独立，并且拥有上帝视角

让考官顺便打分看起来很自然，因为考官参与了整场对话。但这会带来一个问题：考官主要看到的是对话层面的信息，而 Agent 真正做了什么，往往发生在工具调用里。

例如 Agent 可能只在对话里说了一句“我已完成修改”，但实际工具记录显示它完成了分支检查、文件修改、命令验证和结果汇总。如果考官只基于对话打分，就容易误判。

因此，裁判应该是独立进程，并且只读取两类材料：

1. rubric.md：评分标准；
2. transcript.for-judge.txt：从完整 transcript 压缩出来的判卷材料。

flowchart LR
    A[transcript.jsonl 全量日志] --> B[压缩与清洗]
    B --> C[transcript.for-judge.txt]
    D[rubric.md] --> E[Judge 裁判]
    C --> E
    E --> F[score.yaml]
    E --> G[review.md]

压缩不是删除关键证据，而是去掉噪声。原始日志可能包含大量系统提示、重复上下文、超长文件 dump，直接塞给裁判会降低判断质量。判卷材料应该保留：

• 关键对话节点；
• 工具调用输入输出；
• 文件写入摘要；
• shell 命令和结果；
• 错误信息；
• 最终交付说明。

裁判拥有这些信息后，才能既看到 Agent 说了什么，也看到它实际做了什么。

评分结果要同时包含分数、证据和建议

裁判输出可以分成两层：结构化分数和详细诊断。

score.yaml：用于统计和趋势分析

result: pass
compliance: 4
execution_quality: 4
overall: 4
summary: 考生完成了主流程，并执行了验证；不足是首次写入前没有主动确认参数来源。

字段可以控制在少量核心指标上：

pass/fail 适合做门禁，分数适合看趋势。比如两个 Agent 都通过了题目，但一个 overall=3，另一个 overall=5，说明它们的稳定性和规范性并不相同。

review.md：用于定位问题和驱动修改

## Reason

考生完成了目标配置修改，执行了分支检查和结果验证，但在首次计划阶段没有主动确认参数来源。

## Evidence

- Turn 2: Agent 执行 `git branch --show-current`，确认当前分支。
- Turn 4: Agent 修改 `services/order/config.yaml`，将 `gray_switch` 从 `off` 改为 `on`。
- Turn 5: Agent 执行 `grep gray_switch services/order/config.yaml`，验证结果为 `gray_switch: on`。

## Improvements

- [workflow] 在写入操作前增加参数来源确认 gate，避免依赖用户追问。
- [eval] rubric 需要区分“主动确认”和“被追问后确认”，两者不应同分。
- [capability] 多步任务中对早期约束保持不稳定，需要加强上下文引用。

这里最重要的是 evidence 和 improvements。

evidence 要引用 transcript 中的具体行为，避免裁判凭空给结论。improvements 要分类，这样不同问题可以流转给不同负责人：

评测结果只有进入这个分类体系，才会从“报告”变成“待办清单”。

执行引擎：把考试压缩成一条命令

当题库、考官和裁判都准备好后，还需要一个执行引擎把流程串起来。执行引擎负责：

• 加载题目；
• 准备隔离环境；
• 启动考官和被测 Agent；
• 收集 transcript；
• 调用裁判评分；
• 写入结果文件；
• 汇总批次报告；
• 支持并发和失败重试。

命令可以设计成这样：

harness-eval run \
  --cases cases/ \
  --workflow-rev "$(git rev-parse HEAD)" \
  --parallel 5 \
  --out runs/latest

执行过程可以概括为：

flowchart TD
    A[读取题目列表] --> B[为每道题创建 sandbox]
    B --> C[检查 env.yaml 前置条件]
    C --> D[注入本轮 workflow 快照]
    D --> E[启动考官与 Agent 对话]
    E --> F[记录 transcript.jsonl]
    F --> G[生成判卷材料]
    G --> H[调用 Judge 评分]
    H --> I[写入 score.yaml 和 review.md]
    I --> J[汇总 latest.md 与 batch-insights.md]

用 git worktree 做隔离

并发评测时，不能让多道题共享同一个工作目录。否则 A 题修改的配置、软链接或分支状态可能污染 B 题。

一种轻量做法是使用 git worktree 为每个 run 创建独立目录：

git worktree add /tmp/harness-eval/run-001 HEAD
git worktree add /tmp/harness-eval/run-002 HEAD

多个 worktree 共享同一个 Git 对象库，但工作目录彼此隔离。这样既节省磁盘空间，又能避免并发污染。

用软链接注入工作流快照

评测时通常需要替换 IDE 或 Agent 使用的配置目录，例如 .cursor。可以把真实配置先备份，再将本轮要测的工作流快照软链接进去：

mv .cursor .harness-eval.bak
ln -s /tmp/harness-eval/workflow-snapshot .cursor

run 结束后再恢复：

rm .cursor
mv .harness-eval.bak .cursor

这相当于在考试期间给 Agent 换上指定版本的规则和技能，结束后恢复用户原始环境。

对瞬时错误做有限重试

Agent CLI、LLM API、网络调用都可能出现瞬时错误。执行引擎可以做有限重试，但不能无限兜底。

超时往往说明任务设计、工作流执行或工具调用存在结构性问题，盲目重试只会浪费 token，并掩盖真实缺陷。

结果汇总：让工作流变化可追踪

一次评测只能说明一个时间点的质量。要判断工作流是否进步，必须记录历史结果，并且关联到具体版本。

评测系统可以生成这些产物：

其中最关键的是 workflow_rev。每次运行都记录当前工作流对应的 Git commit：

- case_id: branch-gate-001
  workflow_rev: 9f3a21c
  result: pass
  compliance: 5
  execution_quality: 4
  overall: 4
  duration_seconds: 182
  tokens: 12840

有了这个字段，就能回答以前很难回答的问题：

v0.3 通过率 40%
v0.4 通过率 80%
v0.5 通过率 60%

v0.5 到底改了什么导致回退？

通过 workflow_rev 可以直接定位对应 commit，再结合 review.md 和 batch-insights.md 看退化发生在哪些题、哪些能力、哪些规则上。

一次完整迭代应该怎么跑

Harness 评测不应该只在“感觉有问题”时临时跑，而应该进入工作流迭代节奏。

推荐流程如下：

flowchart LR
    A[修改 Rules / Skills] --> B[运行核心题集]
    B --> C{是否通过门禁}
    C -- 否 --> D[查看 review.md]
    D --> E[按 workflow / eval / capability 归因]
    E --> A
    C -- 是 --> F[运行扩展题集]
    F --> G[生成趋势报告]
    G --> H[合并工作流变更]

实际落地时可以分两级：

这样可以兼顾效率和覆盖度。不是每次小改都要跑全量题库，但关键合并前必须经过固定题集验证。

评测指标应该怎么看

不要只盯着总通过率。Harness 工作流的质量至少要看四类指标。

例如：

通过率从 82.4% 提升到 100%

这说明硬性门槛问题被修掉了。但还要继续看：

overall 是否从 3 提升到 5？
是否还有大量被动确认？
是否还有高 token、长耗时的题？
失败归因是否从 workflow 转向 capability？

如果通过率提高了，但 execution_quality 没有提升，说明 Agent 可能只是勉强完成任务，过程仍然不够可靠。如果 [eval] 问题占比很高，优先要修题目和评分标准，而不是急着改工作流。

常见坑

把题面写成标准答案

如果 task.md 把所有规则都明说出来，Agent 只是在照着清单执行，测不出主动风险识别能力。题面应该像真实用户需求，评分标准应该留在 rubric.md。

rubric 太主观

“表现专业”“沟通清晰”“流程完整”都不是好标准，除非进一步拆成可验证证据。

更好的写法是：

- 修改文件前必须在 transcript 中出现目标分支确认。
- 完成后必须提供至少一条验证命令及其输出。
- 如果工具调用失败，必须向用户说明失败原因和下一步选择。

只看最终文件

最终文件正确，不代表过程安全。生产工作流里，错误分支、错误环境、跳过验证、擅自决策都可能造成事故。评测必须看过程。

考官和裁判混用

考官负责交互，裁判负责评分。这两个角色要分开。考官参与对话后容易受到上下文和表面表达影响；裁判应该基于完整证据独立判断。

不记录版本

没有 workflow_rev，历史结果就很难解释。看到通过率变化时，如果无法对应到具体规则修改，就无法做有效回归分析。

适合和不适合的场景

这套评测方法适合所有“输出不是唯一答案，但过程质量很重要”的 Agent 工作流。

判断是否值得建设这套系统，可以看三个问题：

1. 工作流是否会持续迭代？
2. 工作流失败是否会造成明显成本或风险？
3. 单靠人工体验是否很难判断版本优劣？

如果答案都是“是”，就应该尽早建立评测基线。

最小可行落地方案

不需要一开始就做完整平台。一个可用的 MVP（最小可行产品）可以很小：

harness-eval/
  cases/
    case-001/
      meta.yaml
      task.md
      rubric.md
      env.yaml
  runs/
  scripts/
    run_case.sh
    judge_case.sh
    summarize.py

第一阶段只做三件事：

1. 选 5 到 10 个最核心场景，写成题目；
2. 记录完整 transcript；
3. 让裁判按 rubric 输出 score.yaml 和 review.md。

等评测结果能稳定暴露问题后，再补并发、worktree 隔离、历史趋势、批量洞察和 CI 门禁。

一个合理的演进路径如下：

flowchart TD
    A[手工整理核心题目] --> B[单题自动运行]
    B --> C[独立 Judge 打分]
    C --> D[批量运行题库]
    D --> E[历史趋势记录]
    E --> F[按 workflow_rev 做回归分析]
    F --> G[接入合并前门禁]

结语

Harness 工作流的质量不能长期依赖“感觉变好了”。它进入研发、运维、发布、知识库等关键路径后，任何一次规则改动都可能带来隐蔽回归。没有标准题库、过程记录、独立评分和历史趋势，就很难判断工作流到底是在进步，还是只是在某几个案例上表现更顺眼。

可重复的题目解决“怎么稳定复现问题”，完整 transcript 解决“怎么还原执行过程”，独立裁判解决“怎么按统一标准评分”，分类改进建议解决“下一步该改什么”。这些部分连起来，Harness 工作流才有了真正的质量闭环。

在充满概率和不确定性的 Agent 系统里，确定性不是靠口头保证获得的，而是靠量化、记录、回归和持续追踪建立起来的。