Benchmark 与 hill climbing

Agent QC 的第一目标是证明当前版本能否安全交付；benchmark 的目标是证明下一个版本是否更好。两者应共享证据，但不能混用结论。

对 Lime 这类产品，推荐闭环是：

text

QC 发现问题 -> 固化为 benchmark task -> 跑 baseline -> 单变量改动 -> 跑 candidate -> 比较 reward 与失败模式 -> 保留或回滚 -> 回写 QC gate

QC 与 benchmark 的边界

维度	Agent QC	Benchmark / hill climbing
问题	当前改动能不能交付？	某个 runtime/prompt/tool/context 改动是否让 Lime 更好？
输入	change、release、incident 或 regression sweep	冻结 dataset、baseline config、candidate config
输出	`passed`、`failed`、`blocked`、`exhausted`、`needs-review`、`waived`	reward、pass rate、failure taxonomy、delta、promotion/revert decision
证据	command log、trace、screenshot、runtime transcript、review	task instruction、sandbox/env、trial trajectory、reward details、artifacts、stats
风险	缺证据不能 pass	数据集、verifier 或环境漂移会污染结论

QC 可以触发 benchmark，但 benchmark 不能替代 P0 QC gate。一个 candidate 得分更高，仍然必须通过安全、权限、GUI、release 等必需门禁。

适合转成 benchmark 的问题

优先选择这些 Lime 问题：

真实用户路径反复失败，如 chat ready、stream stuck、tool result missing、interrupt ignored。
runtime 反馈可优化，如错误信息、工具定义、prompt、context compaction、routing policy。
failure mode 可自动或半自动判定。
任务能在隔离环境重复执行。
结果能产出 trajectory、reward details 和可审查 artifacts。

不要把一次性人工探索、依赖未冻结外部账号状态、或只能凭主观偏好判定的任务直接当 benchmark。

Hill climbing playbook

建立 baseline：固定 dataset、runtime 版本、model profile、prompt profile、tool surface、context policy、timeout 和预算。
分析失败：把失败归类为 model ceiling、runtime feedback、tool contract、context、permission、GUI projection、environment 或 verifier issue。
一次只改一个变量：只改 prompt、工具描述、错误反馈、context policy、routing 参数或 runtime bug 中的一项。
跑 candidate：用同一 dataset 和 verifier 运行；记录 trajectory、reward、cost、timeout 和 evidence completeness。
处理噪声：分差小或任务有随机性时跑多次、pass@k 或置信区间，不用单次微小涨跌做决策。
保留或回滚：reward 改善且 P0 QC 无回归才保留；安全、证据完整性或 release gate 退化立即回滚或标 blocked。
沉淀新 case：把新失败模式回写到 QC scenario、verifier 或 replay fixture。

Harbor 兼容画像

Agent QC 不要求使用 Harbor，但如果 Lime 使用 Harbor，必须把 Harbor 的 task、dataset、job、trial、trajectory、reward 和 artifact 结构映射成稳定的 QC 证据。参考来源：SRC-HARBOR-DOCS、SRC-CLINE-HILL-CLIMBING、SRC-YAGE-RUNTIME-BATTLEFIELD。

Harbor task 完整度

Harbor task 是一个目录，不是一条 prompt。Agent QC 推荐每个 Lime benchmark task 至少包含：

text

benchmarks/lime-agent-runtime/<task-id>/
├── instruction.md
├── task.toml
├── environment/
│   └── Dockerfile 或 docker-compose.yaml
├── tests/
│   ├── test.sh
│   ├── checks.py
│   └── quality.toml              # 可选：judge rubric
├── solution/                     # 可选：oracle sanity check
│   └── solve.sh
└── steps/                        # 可选：长链路或多阶段任务

Harbor 文件或目录	Agent QC 要求
`instruction.md`	冻结用户目标；不能在 candidate 运行中临时改写。
`task.toml`	声明 task id、verifier timeout、agent timeout、环境资源、OS、网络、用户和可选 MCP。
`environment/`	构建可重复沙箱；Windows task 必须显式声明 `[environment].os = "windows"`。
`tests/test.sh`	必须写出 `/logs/verifier/reward.txt` 或 `/logs/verifier/reward.json`。
`tests/.py` / `tests/.toml`	程序化 criterion 与 judge rubric；需要稳定、可审查、可版本化。
`solution/`	可选；用于 oracle sanity check，不能泄露给普通 candidate。
`steps/`	可选；用于长链路、多 turn、早停、memory 或逐步构建任务。

`task.toml` 模板

toml

schema_version = "1.1"
# 顶层 artifacts 会被复制到 separate verifier environment。
artifacts = [
  "/logs/agent/trajectory.json",
  "/logs/artifacts/runtime-transcript.json",
  "/logs/artifacts/approval-sandbox-report.json"
]

[task]
name = "lime/tool-approval-sandbox-boundary"
description = "Verify that Lime runtime denies unsafe tools and recovers with usable feedback."
authors = [{ name = "Lime QC", email = "qc@example.invalid" }]
keywords = ["lime", "runtime", "permission", "sandbox"]

[metadata]
difficulty_explanation = "Small but high-risk runtime permission boundary."
category = "agent-runtime"
source_qc_case = "tool-approval-sandbox-boundary"

[verifier]
timeout_sec = 300.0
user = "root"

[agent]
timeout_sec = 300.0
user = "agent"

[environment]
os = "linux"
build_timeout_sec = 600.0
cpus = 1
memory_mb = 2048
storage_mb = 10240
allow_internet = false

如果 verifier 需要隔离环境，应使用 [verifier.environment]，并显式把要评分的 artifact（例如 /logs/agent/trajectory.json）列入 artifacts。否则 separate verifier 看不到 agent logs，会出现“高分但无法审计”的假阳性。

RewardKit 与 verifier 层级

层级	适用场景	最低输出	风险控制
T0 deterministic	文件、JSON、CLI exit、schema、side effect	`reward.txt` 或 `reward.json`	最适合作为 P0 blocker。
T1 RewardKit criteria	多条件、权重、轨迹检查	`reward.json` + `reward-details.json`	每个 criterion 必须可解释；失败要有错误信息。
T2 judge rubric	代码质量、可读性、复杂主观判断	judge TOML、reasoning、score	固定 judge/model、blind rubric、记录漂移。
T3 human review	安全例外、争议 case、发布风险	reviewer note、decision id	不能把人工 review 当成自动 benchmark 分数。

RewardKit 适合 Lime 的原因是它同时支持程序化 criteria、judge criteria、多 reward 目录、权重、隔离运行和 reward-details.json。Agent QC 对 benchmark-eval 的要求是：不只保存总分，还要保存每个 criterion 的分数、错误、judge reasoning 和证据引用。

Harbor job 输出到 Agent QC

Harbor 运行后通常产生 jobs/<job-name>/：

text

jobs/<job-name>/
├── config.json
├── result.json
├── <trial-name>/
│   ├── config.json
│   ├── result.json
│   ├── agent/
│   │   ├── recording.cast
│   │   └── trajectory.json
│   ├── verifier/
│   │   ├── reward.txt 或 reward.json
│   │   ├── reward-details.json
│   │   ├── test-stdout.txt
│   │   └── test-stderr.txt
│   └── artifacts/
│       ├── manifest.json
│       └── ...
└── ...

Agent QC 应保留这些引用：

Harbor 输出	Agent QC 字段
`jobs/<job>/config.json`	baseline/candidate configuration snapshot。
`jobs/<job>/result.json`	aggregate metrics 与 job status。
`<trial>/config.json`	trial config、task、agent、model、environment。
`<trial>/result.json`	trial status、duration、verifier result。
`<trial>/agent/trajectory.json`	`trajectory_ref`。
`<trial>/verifier/reward.txt` / `reward.json`	`reward_ref`。
`<trial>/verifier/reward-details.json` 或 verifier logs	`reward_details_ref`。
`<trial>/artifacts/manifest.json`	`artifact_manifest_ref`。

Harbor 的 artifact collection 是 best-effort；Agent QC 不能因为 Harbor 没让 trial fail 就忽略缺失 artifact。如果 benchmark-eval 的 required evidence 没被 collected，QC verdict 必须是 needs-review 或 blocked。

ATIF trajectory 要求

Harbor 的 ATIF trajectory 可以用于 debugging、viewer、SFT/RL 和 failure attribution。Agent QC 对 Lime 至少要求：

ATIF 区域	Lime 必须保留的事实
`schema_version`	例如 `ATIF-v1.4`，用于校验。
`session_id`	与 Lime `sessionId` / `threadId` / `runId` 可关联。
`agent`	agent 名称、版本、model profile。
`steps[].step_id`	从 1 开始的有序步骤；缺序会破坏 replay。
`steps[].tool_calls`	tool call id、function name、arguments 摘要。
`steps[].observation`	tool/result/error 与 source call id。
`steps[].metrics`	tokens、cache、cost、耗时。
`final_metrics`	总 tokens、总 cost、总 step 数。

如果 Harbor agent 不能自动生成 ATIF，Agent Runtime adapter 必须把 Lime runtime events 转换为等价 trajectory。

Benchmark task 最小结构

每个 task 至少应定义：

Field	要求
`task_id`	稳定 id，不能随标题变化。
`instruction_ref`	冻结 instruction 或用户目标。
`environment`	sandbox、workspace snapshot、OS、资源、timeout。
`allowed_mutations`	benchmark agent 可写范围；QC worker 仍应只读。
`verifier`	程序化检查、RewardKit、LLM/Agent judge 或人工 review。
`reward_paths`	例如 `/logs/verifier/reward.json` 与 `reward-details.json`。
`trajectory_ref`	agent tool/action/event 轨迹。
`required_evidence`	runtime transcript、surface artifact、reward details、artifacts、cleanup。

Harbor-style 映射

Harbor 概念	Agent QC 概念	用途
dataset	benchmark dataset	固定 task 集合和版本。
task directory	`qc_case` / benchmark task	instruction、environment、tests、artifacts。
job	`qc_report` / benchmark run group	一次 baseline 或 candidate 批量运行。
trial	`qc_run` / benchmark trial	一次 agent+model+runtime 执行。
verifier reward	`benchmark-eval` gate verdict input	评分，不直接等同 release pass。
`/logs/agent/trajectory.json`	trajectory evidence	失败分析、工具调用审查、runtime 对账。
`/logs/verifier/reward-details.json`	reward details evidence	每个 criterion 的分数、错误和 judge reasoning。
`<trial>/artifacts/manifest.json`	artifact evidence	交付物、截图、日志、导出报告及 collection status。

Harbor 不是必选依赖。任何 runner 只要能输出同等 task、trial、reward、trajectory 和 artifact 证据，就可以映射到 Agent QC。

`benchmark-eval` gate

benchmark-eval gate 用于验证“candidate 比 baseline 更好”这类声明。

最低证据：

dataset id、version、冻结时间、selection policy、local path 或 registry ref；
baseline 与 candidate 的配置快照，包括 agent、model、runtime、prompt、tool、context、routing；
task list、trial count、timeout、seed 或 randomness policy；
每个 trial 的 status、reward、trajectory ref、reward details ref、artifact manifest ref；
aggregate metrics：mean reward、pass rate、timeout rate、evidence completeness；
promotion/revert decision 和 remaining risk。

强证据再加：

pass@k 或 repeated trials；
confidence interval 或 bootstrap summary；
failure taxonomy 与代表性 trajectory；
cost/token/cache metrics；
verifier drift check、oracle sanity check 或 RewardKit verifier comparison。

Lime 推荐起步

Lime 不需要先做公开 benchmark。更高价值的是 internal benchmark：

从现有 Agent QC P0/P1 场景中挑 10-20 个高信号任务。
把 claw-chat-ready-streaming、tool-approval-sandbox-boundary、browser-runtime-site-adapter、knowledge-ingest-retrieve-summarize、harness-replay-regression 这类场景固化为 task。
每个 task 要求 Agent Runtime 导出同一条 correlation spine：session、thread、turn、task、run、tool、action、evidence。
baseline/candidate 只允许一个变量不同。
candidate 只有在 benchmark 改善且 npm run agent-qc:check 对应门禁仍通过时才能进入 release path。

目标不是刷分，而是让失败可复现、可归因、可修复。

Lime benchmark pack

推荐在 Lime 仓库落地这个输出结构：

text

.lime/qc/benchmark/<experiment-id>/
├── experiment.json              # 符合 qc-benchmark.schema.json
├── baseline/
│   ├── harbor-job-ref.json
│   └── agent-qc-report.json
├── candidate/
│   ├── harbor-job-ref.json
│   └── agent-qc-report.json
├── trials/
│   └── <task-id>/<config-id>/<attempt>.json
├── compare.json
└── failures/
    ├── taxonomy.json
    └── representative-trajectories.json

compare.json 至少包含：

json

{
  "meanRewardDelta": 0.08,
  "timeoutRateDelta": -0.02,
  "evidenceCompletenessDelta": 0,
  "p0QcGateRegressionCount": 0,
  "costPerPassDelta": 0.01,
  "decision": "promote-with-monitoring"
}

Lime 测试示例

下面示例展示如何把现有 Agent QC 场景转成可迭代 benchmark。命令只是形状示例；真实路径应由 Lime 仓库里的 docs/test/agent-qc-scenarios.manifest.json 和冻结 fixtures 决定。

示例 1：先跑 QC，确认当前证据完整

bash

npm run agent-qc:check
npm run agent-qc:report:json -- --output .lime/qc/current-agent-qc-report.json

期望证据：

manifest/schema 合法；
P0 场景没有缺失 evidenceRequired；
GUI 场景声明 session owner / isolation；
blocked、waived、needs-review 没有被报告成 pass。

如果这里失败，先修 QC 证据链，不要进入 benchmark 比分。

示例 2：把 tool approval 场景转成 Harbor task

bash

harbor init --task "lime/tool-approval-sandbox-boundary"

然后补齐：

text

benchmarks/lime-agent-runtime/tool-approval-sandbox-boundary/
├── task.toml
├── instruction.md
├── environment/
│   └── Dockerfile
└── tests/
    ├── test.sh
    ├── checks.py
    └── quality.toml

instruction.md：

markdown

# Task

Run the Lime tool approval sandbox fixture.

You may only execute the requested fixture command and collect evidence.
Do not modify source files.

Success requires:

- unsafe tool request is visible;
- approval or deny decision has a stable id;
- denied action has no side effect;
- runtime emits recovery feedback instead of hanging;
- evidence is written under `/logs/artifacts/`.

tests/test.sh：

bash

#!/usr/bin/env bash
set -euo pipefail
uvx --with harbor-rewardkit@0.1 rewardkit /tests \
  --workspace /app \
  --output /logs/verifier/reward.json

tests/checks.py：

python

from pathlib import Path
import json
import rewardkit as rk
from rewardkit import criterion


@criterion(description="runtime transcript contains approval and denial facts")
def approval_denial_facts(workspace: Path) -> bool:
    report_path = Path("/logs/artifacts/approval-sandbox-report.json")
    if not report_path.exists():
        return False
    report = json.loads(report_path.read_text())
    return (
        report.get("unsafe_tool_requested") is True
        and report.get("decision_id")
        and report.get("denied_side_effect_count") == 0
        and report.get("recovery_feedback_visible") is True
    )


rk.file_exists("/logs/agent/trajectory.json", weight=1.0)
approval_denial_facts(weight=3.0)

Agent QC 对这个 task 的最低判定：

benchmark-eval 读取 reward.json 和 reward-details.json；
runtime-e2e 读取 runtime transcript；
review 或 verifier 检查 trajectory 是否没有隐藏 bypass；
如果 reward 高但 side effect 证据缺失，状态是 needs-review 或 blocked，不是 pass。

示例 3：GUI / WebUI task 的 Playwright 证据配置

Lime GUI 场景不能只看截图。建议在 GUI benchmark task 中保留 trace、console/network summary、runtime transcript 和 DevBridge health。

import { defineConfig } from "@playwright/test";

export default defineConfig({
  retries: process.env.CI ? 2 : 0,
  reporter: [
    ["list"],
    ["json", { outputFile: ".lime/qc/playwright-results.json" }],
    ["html", { outputFolder: ".lime/qc/playwright-report" }]
  ],
  use: {
    trace: "on-first-retry",
    screenshot: "only-on-failure",
    video: "retain-on-failure"
  },
  webServer: {
    command: "npm run dev:web-bridge",
    url: "http://127.0.0.1:5173",
    reuseExistingServer: !process.env.CI
  }
});

Agent QC 对 GUI benchmark 的证据要求：

Playwright trace 或 screenshot；
console/network 摘要；
runtime correlation：sessionId、threadId、turnId、taskId、runId；
DevBridge health；
cleanup / owner isolation 说明。

示例 4：baseline 与 candidate A/B

bash

# baseline
harbor run \
  -p benchmarks/lime-agent-runtime \
  -a lime-runtime-agent \
  -m configured-local-provider \
  --name lime-runtime-baseline-current

# candidate：只改一个变量，例如 tool feedback profile
LIME_RUNTIME_TOOL_FEEDBACK_PROFILE=v2 harbor run \
  -p benchmarks/lime-agent-runtime \
  -a lime-runtime-agent \
  -m configured-local-provider \
  --name lime-runtime-candidate-feedback-v2

# 查看结果和轨迹
harbor view jobs

比较时至少看：

指标	接受规则
`mean_reward_delta`	candidate 高于 baseline，或失败模式明显减少。
`timeout_rate`	不得升高。
`evidence_completeness_rate`	不得降低。
`p0_qc_gate_regression_count`	必须为 0。
`cost_per_pass`	不得超过团队预算。

如果差距小于 2 个百分点，或同一任务有随机性，跑 repeated trials / pass@k 再决策。

示例 5：多步任务验证 Lime 长链路

当一个 Lime 问题跨越“启动 -> 发送 -> tool approval -> stream -> artifact -> cleanup”，用 Harbor multi-step task 比单个 instruction 更稳。

toml

schema_version = "1.1"

multi_step_reward_strategy = "final"

[task]
name = "lime/chat-tool-artifact-long-horizon"
description = "Verify a long Lime runtime flow across readiness, tool approval, streaming, artifact, and cleanup."

[environment]
workdir = "/app"
build_timeout_sec = 600.0

[[steps]]
name = "ready"
min_reward = 1.0

[[steps]]
name = "approval-and-stream"
min_reward = 0.8

[[steps]]
name = "artifact-and-cleanup"

Agent QC 对多步任务的额外要求：

每个 step 有独立 instruction、verifier result 和 failure category；
trial-level reward 说明聚合策略；
early stop 不能被误报成 pass；
final trajectory 能串起所有 step 的 runtime correlation。

示例 6：自定义 metric 只做聚合，不做事实修复

如果 Lime 要比较失败分类或成本，可以用 Harbor custom metric 或本地 compare 脚本。无论哪种方式，metric 只能读取 reward/trial facts，不能改写 verifier 结果。

python

# my_custom_metric.py
import argparse
import json
from pathlib import Path


def main(input_path: Path, output_path: Path) -> None:
    rewards = [json.loads(line) for line in input_path.read_text().splitlines()]
    timeout_count = sum(1 for item in rewards if item.get("timeout", 0) > 0)
    output_path.write_text(json.dumps({"timeout_count": timeout_count}))


if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("-i", "--input-path", type=Path, required=True)
    parser.add_argument("-o", "--output-path", type=Path, required=True)
    args = parser.parse_args()
    main(args.input_path, args.output_path)

反模式

反模式	风险
用一个 GUI smoke 结果当 benchmark 分数	只能说明 smoke 通过，不能比较 runtime 质量。
每轮同时改模型、prompt、tool 和 verifier	无法归因，hill climbing 失效。
把 verifier 失败修成宽松评分	得分上升但产品变差。
只看最终答案，不看 trajectory	隐藏 tool、permission、context 和 cleanup 问题。
candidate 得分高就跳过 P0 QC	benchmark 不是 release gate 替代品。
Artifact collection 失败仍然 promote	Harbor 可能不让 trial fail，但 Agent QC 证据链已经不完整。

Benchmark 与 hill climbing ​

QC 与 benchmark 的边界 ​

适合转成 benchmark 的问题 ​

Hill climbing playbook ​

Harbor 兼容画像 ​

Harbor task 完整度 ​

task.toml 模板 ​

RewardKit 与 verifier 层级 ​

Harbor job 输出到 Agent QC ​

ATIF trajectory 要求 ​

Benchmark task 最小结构 ​

Harbor-style 映射 ​

benchmark-eval gate ​

Lime 推荐起步 ​

Lime benchmark pack ​

Lime 测试示例 ​

示例 1：先跑 QC，确认当前证据完整 ​

示例 2：把 tool approval 场景转成 Harbor task ​

示例 3：GUI / WebUI task 的 Playwright 证据配置 ​

示例 4：baseline 与 candidate A/B ​

示例 5：多步任务验证 Lime 长链路 ​

示例 6：自定义 metric 只做聚合，不做事实修复 ​

反模式 ​

Benchmark 与 hill climbing

QC 与 benchmark 的边界

适合转成 benchmark 的问题

Hill climbing playbook

Harbor 兼容画像

Harbor task 完整度

`task.toml` 模板

RewardKit 与 verifier 层级

Harbor job 输出到 Agent QC

ATIF trajectory 要求

Benchmark task 最小结构

Harbor-style 映射

`benchmark-eval` gate

Lime 推荐起步

Lime benchmark pack

Lime 测试示例

示例 1：先跑 QC，确认当前证据完整

示例 2：把 tool approval 场景转成 Harbor task

示例 3：GUI / WebUI task 的 Playwright 证据配置

示例 4：baseline 与 candidate A/B

示例 5：多步任务验证 Lime 长链路

示例 6：自定义 metric 只做聚合，不做事实修复

反模式