> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myrmagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 评测实验室

> 在 GUI 仪表盘中评估 Agent 质量、跟踪回归、对比不同配置的性能表现。

# 评测实验室 (Eval Lab)

Myrm 内置 **评测实验室**，让你在 WebUI 中运行测试用例、对比不同 Agent 配置的表现、追踪质量趋势。

## 核心能力

* **单配置评测** — 对当前 Agent 配置运行测试套件，实时查看通过/失败结果。
* **跨配置矩阵评测** — 同一用例集在多个 Agent Profile 上运行，自动检测切换模型前的回归风险。
* **环境可复现性** — 每次评测运行生成冻结的 `EvalManifest` 快照（模型、工具、配置、基准模式），确保结果可复现。
* **基准模式** — 一键切换，剥离用户自定义配置（技能、MCP、记忆、搜索），仅使用核心工具生成公平基线分数。
* **历史趋势追踪** — 通过交互式图表查看通过率趋势。历史表格展示 Profile、模型、通过率、平均耗时和 Token 用量。
* **点击查看详情** — 点击任意历史记录加载完整报告，包含逐用例结果、环境快照和 Diff 视图。

## 快速开始

1. 从侧边栏导航到 **评测实验室**（或访问 `/eval-lab`）。
2. 在 **配置** 标签页选择数据集，可选开启 **基准模式**。
3. 点击 **运行** 开始评测，进度实时更新。
4. 在 **报告** 标签页查看结果 — 摘要卡片、逐用例表格和环境快照。
5. 切换到 **历史** 标签页对比不同运行的表现。

## WorkBuddy Bench 基准评测

评测实验室内置 **WorkBuddy Bench**（腾讯多领域编码 Agent 基准）适配器，覆盖官方全部四个赛道，评分口径与论文一致：

| 赛道               | 任务数 | 约体积      | 评分模式            |
| ---------------- | --- | -------- | --------------- |
| WBBench Code     | 80  | \~196 MB | composite（组合评分） |
| WBBench Web      | 70  | \~22 MB  | composite       |
| WBBench Office   | 50  | \~10 MB  | composite       |
| WBBench Security | 60  | \~479 MB | native（任务自带评分器） |

### 下载子集

1. 打开 **评测实验室** 并切换到 **WorkBuddy Bench** 标签页。
2. 每个赛道显示任务数、约体积和本地状态（`未下载` / `已下载`）。
3. 点击 **下载** 在后台从 Hugging Face 拉取归档。进度通过 SSE 实时推送，下载期间按钮禁用。
4. 归档会按官方 SHA-256 校验和验证并原子安装——损坏或不完整的归档绝不会被使用。
5. 随时点击 **刷新** 重新读取本地磁盘状态；刚完成的下载会立即把按钮切换为 `已下载`。

### 运行评测

1. 在已下载的赛道上点击 **运行**，对该子集的每个任务进行评测。
2. 运行期间提供 **停止** 控制——运行中和下载中均可中止。
3. 完成后生成可复现报告（manifest 中记录模型、工具、Profile、评分模式）。

:::tip
Security 任务由任务自带的 `tests/scoring.py` 原生评分（无 LLM 判官）；Code/Web/Office 走组合验证器——与 WBBench 论文的验收分层一致。
:::

## 国际权威基准（BrowseComp）

除 WorkBuddy Bench 外，Eval Lab 还接入了 **BrowseComp**——OpenAI 官方基准，含 1,266 道需要多跳证据检索与网页浏览的真实研究考题。跑出的分数与顶级 AI 实验室引用的任务格式一致，是可以直接对外引用的权威成绩。

* **先抽样试跑** — 大基准自动预填小样本（如 1266 题抽 20 题），先用零头 token 成本验证整条链路，再决定是否全量跑。清空样本即全量运行；报告用 `sampled` 徽标如实标注真实抽样的运行，绝不误报。
* **公平基线** — 基准模式剥离你的技能/MCP/记忆，分数只反映「模型 + 核心工具」。
* **前置检查** — 运行前确认基准所需的搜索/嵌入服务已配置且可达，不浪费任何 token。

## 确定性判分：分层验收引擎（CompositeVerifier）

每个任务的判分由任务自带的测试套件驱动——通过/失败路径中不依赖黑箱 LLM 判分。组合验证器在干净的工作区内执行下载轨道中自带的 `tests/` 代码，把结果转化为真实的逐轮分数：

* **运行任务自带测试** — `test_suite` 断言对 agent 的工作区产物执行任务捆绑的测试。结果从 JUnit XML 或纯 reward 脚本退出码解析。
* **逐轮 `pass_rate`** — 多轮对话逐轮判分，第 1 轮通过但后续退化的任务会被及早发现，不再浪费 token（支持可配置的 `on_turn_fail` 策略）。
* **无隐藏 LLM 判官** — 解析完全确定性：通过/失败来自测试运行器而非模型读输出，分数可复现且不受 judge prompt 漂移影响。
* **部分通过而非非黑即白** — `skipped` 测试不计入分母，单个不可收集的 flaky 测试不会拉低真实通过率；reward 脚本输出映射为渐变分数。
* **测试级可见性** — 每个赛道卡片同时显示运行通过率和**测试通过率**（各轮 `avg_pass_rate` 均值），每份报告携带聚合的测试级均值。

| 验收层                      | 验证内容               |
| ------------------------ | ------------------ |
| Tool 调用断言                | agent 是否调用了所需工具    |
| State 断言                 | 文件系统/状态是否符合预期      |
| Sandbox 断言（`test_suite`） | 任务自带测试是否在真实工作区通过   |
| Semantic 判官（可选）          | 仅任务无原生测试时使用 LLM 校验 |

`test_suite` 超时默认 600s，可按用例配置，因此耗时测试（如编译+运行）能完成而不会被过早终止。

### 判分模型配置

Semantic（LLM 裁判）断言从不硬编码某家判分模型。判分模型从你自己的配置解析——优先每次运行显式指定，其次断言级字段，最后兜底你的默认模型配置——用你已经在用的任何模型供应商都能判分。每份报告都记录实际参与判分的模型（`judge_model`），任务原生基准则如实标注 `none`（无 LLM 判官参与）。

### 判分诊断：失败不再沉默

判分运行可能在测试产生任何输出前就失败——判分命令可能被沙箱安全策略拦截、超时或崩溃。这些失败现在被精准归因并携带真实证据透出：

* **失败归因** — 执行级失败（安全拦截、超时、崩溃）按真实原因报告，不再被误报为「reward 文件不可读」。你能立刻看出判分为何失败：策略拦截、超时还是命令本身报错。
* **stdout 尾部透出** — 每条「命令失败」「reward 文件不可读」「JUnit 文件不可读」消息都携带判分命令最多 800 字符的真实 stdout，看到实际输出而非靠猜。
* **计数型 reward 回退** — 只携带 `tests_passed`/`tests_total` 计数（或 `tests[]` 数组）而非完整 `score.json`/`reward.json` 结构的 reward payload，现在能被正确解析判分而非被拒绝为不可读。这镜像官方 WBBench runner 的计数语义，同时兼容轻量判分脚本。

## 分层评测：每一层能力到底贡献了多少？

「框架真的有用，还是只是模型更聪明了？」**分层评测**用一次运行回答这个问题：同一批任务沿能力递增链依次运行——从公平剥离的裸基线到完整 Agent 配置——报告展示**每一层（Harness 核心、技能、记忆）的增量增益**，用实测数据而非宣传话术说话。

### 层链路

| 层        | 基准模式 |  技能 |  记忆 | 度量内容                           |
| -------- | :--: | :-: | :-: | ------------------------------ |
| `bare`   |   ✅  |  ❌  |  ❌  | 公平基线——仅模型 + 核心工具               |
| `core`   |   ❌  |  ❌  |  ❌  | Harness 核心（规则/replan/MCP/工具策略） |
| `skills` |   ❌  |  ✅  |  ❌  | `skills` − `core` = 技能层的真实增益   |
| `memory` |   ❌  |  ✅  |  ✅  | `memory` − `skills` = 记忆层的真实增益 |

### 如何运行

1. 打开 **Eval Lab** → **Matrix** 标签页。
2. 选择一个已下载的基准，启动 **分层** 运行。
3. 进度实时流式推送（下载字节 → 逐层 case 进度），报告在熟悉的矩阵视图中渲染，每次运行都会进入历史供后续对比。

### 为什么你可以信任这些数字

* **指纹锁定开关组合** — 每层的 `benchmark_mode` / `skills_enabled` / `memory_enabled` 组合以 SHA-256 指纹固化进报告，层定义跨 harness 升级保持可比。
* **完整模型披露** — 报告记录 `agent_model`、`judge_model` 与 `harness_version`（与 Memory A/B、基准 manifest 同一诚实契约），分数曲线只可能在真实能力变化时漂移——绝不是尺子被挪动。
* **行为证据，不止分数** — 每层报告 Agent 真实调用记忆工具的次数（`memory_tool_calls`），「记忆没帮上忙」与「记忆压根没被用」绝不混淆。
* **隔离度量** — 所有层关闭共享上下文、使用一次性记忆卷（SQLite + 嵌入式 Qdrant，跑完 evict 并删除）；记忆层的增益反映记忆机制本身，而非你的真实共享记忆。

这就是 **Harness 杠杆率（HLR）** 思想的落地实践：Myrm 不空口说「我们的框架很强」，而是实测**每一层能力把任务完成率提升了多少**——一个可以在方案、发布说明和迁移材料中引用的数字。

## 跨配置矩阵评测

对比不同 Agent 配置处理同一任务的表现：

1. 在 **配置** 标签页中，从芯片式多选器中选择 **2 个或更多 Profile**。
2. 选中 2+ 个 Profile 后自动出现 **Matrix 模式** 标识。
3. 点击 **运行 Matrix** 开始评测。仪表盘自动切换到 **Matrix** 标签页并显示实时进度：
   * 当前正在评测的 Profile
   * Profile 进度（如 2/3）
   * 用例完成进度条
4. 完成后 **Matrix** 标签页展示：
   * **摘要卡片** — 总用例数、稳定率、回归数、总耗时
   * **Per-profile 表格** — 每个 Profile 的通过率、Token、成本、耗时
   * **Case × Profile 矩阵网格** — 色彩编码展示每个用例在每个 Profile 上的状态（绿 = 稳定，黄 = 回归，红 = 全失败）
5. 用例分类：
   * **稳定** — 在所有选中的 Profile 上都通过（可安全切换模型）
   * **回归** — 在部分 Profile 上通过但在其他上失败（风险区域）
   * **全失败** — 在所有 Profile 上都失败（无论如何需要排查）

:::tip
评测失败时（如 API Key 过期、模型不可用），会立即弹出 toast 通知显示错误信息，不会静默失败。
:::

## 记忆 A/B：用数字证明记忆的价值

开启记忆真的让 Agent 变强了吗？**记忆 A/B** 用并排对比实验回答这个问题，而不是靠营销话术。

### 工作原理

1. 打开 **Eval Lab** → **WorkBuddy Bench**，选择一个已下载的赛道。
2. 点击赛道卡片上的 **Memory A/B** 按钮——确认对话框会清楚展示将要运行的内容。
3. 对话框**先探测 embedding 模型**：记忆检索依赖 embedding，embedding 缺失或不可达会提前提示，避免浪费一次运行。
4. Myrm 对**同一批任务**分别运行两遍——一遍 `enable_memory=True`，一遍 `enable_memory=False`——其余配置完全一致。
5. 运行进度通过 SSE 实时推送；顶部 **Stop** 按钮可中止运行并清理现场。

:::note
对话框会诚实提示：WBBench 任务为单轮，记忆收益在长多轮会话中更明显。我们宁愿你正确解读结果，也不愿过度宣传。
:::

### 报告

矩阵报告并排展示双臂数据：

* **通过率** — 开记忆 vs 关记忆的任务完成率
* **Token 与成本** — 记住这些的代价
* **`memory_tool_calls`** — 记忆工具实际被调用了多少次。如果记忆确实有用，你能看到它真的被用上了——杜绝「记忆已开启却从未被调用」的假阳性。

### 历史回看

每次记忆 A/B 运行都会写入 **Run History** 历史表（时间戳、数据集、双臂通过率与 `memory_tool_calls`）。点击 **View** 可重开任意历史报告——持续跟踪记忆价值是否随产品迭代而变化。

### 隔离与安全

记忆 A/B 使用**临时隔离记忆存储**，运行结束后即丢弃——你的真实记忆数据永远不会被触碰或污染。

### 测试覆盖

全链路 Chrome E2E 覆盖（真实浏览器 + 真实后端）：卡片入口 + 确认对话框、预置双臂报告 + 历史表渲染、真实运行启动 + 中止——3 个 E2E 测试 + 12 个前端单测。

## 评测工作区生命周期：隔离沙箱，用后即焚

每个评测用例都在**物理隔离的工作区**（`.myrm/eval_workspaces/{case_id}`）中运行——并发用例永远不会竞争同一批文件，Agent 也只能读写自己的沙箱。生命周期完全自动化：

* **每次运行结束即焚**——成功、失败、中止、崩溃全部落到同一条清理路径（`create_session` 与仅 `execute` 的运行同样覆盖），长跑服务永无磁盘堆积。
* **崩溃自愈**——进程崩溃遗留的工作区会在下次服务启动时自动清扫，无需人工清理。
* **清理链路防故障**——每一步清理（记忆卷释放、目录删除、每个 profile 的工作区）都独立防护，任何一步失败都不会让其余清理泄漏。

同样的隔离延伸到记忆 A/B：双臂使用一次性临时记忆卷，运行结束后释放并删除。

## 评测完整性与去污染：预算控制与轨迹披露

一个基准分数只有当「运行无法作弊」且「报告可以审计」时才值得信任。Eval Lab 把这两点做成结构性保证。

### 去污染运行（HF 泄漏防护）

基准评测期间，Agent 被禁止访问存放标准答案的资源库——最重要的是 **Hugging Face**（WBBench 各赛道与大量答案数据都托管于此）。纵深防御：

* **网页抓取**——命中基准阻断名单的 hostname 会立即抛出 `benchmark_blocked` 工具错误。
* **网页搜索**——来自阻断 host 的结果在排序/格式化前被**静默丢弃**，命中阻断查询词的请求直接快速失败。
* **Shell / 代码执行**——网络策略默认无外网（或严格 allowlist 且不含 Hugging Face），不存在外带答案的旁路通道。
* 报告记录去污染是否开启（`decontam_active`），Report 页以徽章展示——「干净的分数」是可证明的，而非假设的。

### 声明的运行预算

每个第三方基准声明自己的**工具调用预算与迭代预算**（`max_tool_calls` / `max_iterations`）：

* 卡壳的 Agent 无法无限烧 token——tool-call 中间件与引擎递归预算强制截断。
* 触达上限立即停止，per-case 报告精确记录是哪个上限截断了运行（`limit_reached`，如 `max_tool_calls` / `max_iterations`）。被截断的用例永远不会与正常完成混淆。
* manifest 记录声明的预算，Report 页展示为 **预算 · N 次调用 / M 轮迭代**。

### 轨迹披露

每份报告都暴露分数背后的执行证据：

* **工具调用明细**——Agent 实际调用了多少次工具（`N×` 徽章 + tooltip）。
* **拦截次数**——去污染守卫拦截了多少次尝试（`Blocked N` 徽章）。
* **触达上限**——哪个预算停止了运行（`Limit` 徽章，tooltip 显示具体类型）。
* **判分透明**——语义判分（LLM-as-a-judge）断言支持可配置的 `judge_prompt` 并写入报告；每次运行都披露 `agent_model` / `judge_model`（任务原生判分诚实标记 `none`）。精确匹配的答案直接短路判官，琐碎命中从不消耗判分 token。

这些机制共同让分数**可审计到每一次工具调用**——你不仅能说清分数是多少，还能说清它是在什么防护、什么预算、什么轨迹下产生的。

## 环境快照

每次评测运行记录 `EvalManifest`：

| 字段                            | 用途                                                                        |
| ----------------------------- | ------------------------------------------------------------------------- |
| `model_provider` / `model_id` | 使用的 LLM                                                                   |
| `agent_model` / `judge_model` | 被评测的 Agent 模型 + 判分模型——任务原生判分时为 `none`（无 LLM 判官）。每份报告与历史行都记录两者，换模型后分数漂移可追溯 |
| `profile_id`                  | 活跃的 Agent Profile                                                         |
| `benchmark_mode`              | 是否剥离了用户自定义配置                                                              |
| `harness_version`             | 框架版本（用于复现）                                                                |
| `tool_policy`                 | 可用的工具列表                                                                   |
| `prompt_fingerprint`          | 系统提示词的 SHA-256                                                            |
| `task_set_hash`               | 测试数据集的哈希                                                                  |

快照显示在报告标签页的 **环境** 区域，以及历史表格的 **Profile** 和 **模型** 列。

## 基准模式

在配置标签页切换 **基准模式** 获取纯净基线：

* 系统提示词 → 空
* 工具 → 仅核心工具（无 MCP、无技能、无子 Agent）
* 记忆、搜索、Replan、上下文压缩 → 禁用

让你衡量模型的原始能力，分数可跨配置对比。

## 编写测试用例

测试用例为 JSONL 文件，每行一个 JSON 对象：

```json theme={null}
{"message": "2+2等于多少？", "expected": "4"}
```

语义断言（LLM-as-Judge）：

```json theme={null}
{
  "message": "写一首关于编程的俳句",
  "assertions": [
    {"type": "semantic", "criteria": "输出是一首有效的俳句，符合5-7-5音节结构"}
  ]
}
```

多轮用例通过可配置失败策略串联各轮：

```json theme={null}
{
  "turns": [
    {"message": "创建一个名为 test.txt 的文件", "assertions": [{"type": "tool", "tool_name": "write_file"}]},
    {"message": "读取该文件", "expected_contains": "test.txt"}
  ],
  "on_turn_fail": "stop"
}
```

## Skill 发布质量防线

当技能通过 Myrm 的 Skill Evolution 管线进化时，会经过 **5 层防线** 才能进入生产：

1. **EvolutionScreener** — 5 阶段筛选（锁定 → 强制重试 → 冷却期 → 拒绝历史 → LLM 确认），在消耗资源前阻止无效进化。
2. **EvalCase 回归门** — 对候选变体运行绑定的 EvalCase。根据失败用例比例施加分数惩罚；100% 失败的变体被直接过滤。
3. **改进门** — 将原始技能作为 baseline 竞争者注入。只有真正优于原版的变体才能存活。
4. **沙箱验证器** — 在隔离沙箱中执行候选变体，验证其实际可用。
5. **ConfidenceApprovalFlow** — 多信号风控（diff 比率、有效率、置信度阈值）。任何红灯降级为人工 Diff Review。

审批通过后，**Shadow AB 灰度测试** 在真实流量上验证新版本。如出现问题，**一键回滚** 立即恢复。

## 历史与降级

* 旧报告（在 manifest 追踪之前创建）在 Profile 和模型列显示 `-`，不会丢失数据。
* 历史表格在窄屏上支持水平滚动。
* 报告加载失败时显示 toast 通知而非静默失败。