# Baseline Run Record Schema（基线运行记录 · 共享契约）

> 状态：**Schema + 评估器 + 记录生产（runner）均已落地；Quality 仅 TestPassRate 真实，CodeReview/UserAcceptance 仍缺；真实数值需模型 key**。
>
> 依据：**Agent 蜂群指标量化与标准 v2.0 §6, §9**。实现：`benchmark/baselines/comparison.py`（`BenchmarkRunRecord` / `compare` / `evaluate`）+ `benchmark/runners/`（5 系统产出记录，见 [`baseline-runners.md`](./baseline-runners.md)）。配套：[`baseline-comparison.md`](./baseline-comparison.md)、[`emergence-evaluation.md`](./emergence-evaluation.md)、[`cost-normalized-gain.md`](./cost-normalized-gain.md)、[`IMPORTANT-metric-coverage-gaps.md`](./IMPORTANT-metric-coverage-gaps.md)。
>
> 更新：`code_review_score`/`user_acceptance` 现为 **Optional**（runner 仅采 TestPassRate 时传 None，`quality()` 掩码归一；None ≠ 0）。

## 1. 目的

蜂群验收的核心是 **swarm vs baseline 对比**（尤其 sub-agent，Baseline C ×0.90）。要算 `G_E`/`G_E,c`，**swarm 与每个基线必须在同一任务集、同等约束下，产出同一份记录**。本文定义这份共享记录 `BenchmarkRunRecord`：**两侧程序各自产出**，由本仓评估器统一比较。

## 2. 共享记录 `BenchmarkRunRecord`

| 字段 | 类型 | 含义 |
|---|---|---|
| `system` | str | `swarm` / `single` / `chain` / `sub` / `strong` |
| `scenario` | str | `coding` / `refactoring` / `architecture` / `devops` / `bugfix` |
| `task_set_id` | str | 共享任务集 ID（**同一 id 才可比**） |
| `n_agent` | int | 该系统使用的 Agent 数 |
| `completed_tasks` / `total_tasks` | int | 完成度（Completion） |
| `test_pass_rate` / `code_review_score` / `user_acceptance` | float(0–100) | 质量三输入（Quality） |
| `budget_usd` / `actual_cost_usd` | float | 计划/实测成本（Cost、CostEfficiency） |
| `model_tokens` | int | token 用量 |
| `target_time_s` / `actual_time_s` | float | 计划/实测耗时（Time、Speed） |
| `recovered_failures` / `total_failures` | int | 恢复/总失败（Robustness） |

JSON 示例：
```json
{
  "system": "sub", "scenario": "coding", "task_set_id": "coding-set-1", "n_agent": 3,
  "completed_tasks": 9, "total_tasks": 10,
  "test_pass_rate": 70, "code_review_score": 60, "user_acceptance": 65,
  "budget_usd": 10, "actual_cost_usd": 6, "model_tokens": 42000,
  "target_time_s": 600, "actual_time_s": 720, "recovered_failures": 1, "total_failures": 2
}
```

## 3. 派生量（评估器，已实现）

- `Q = quality(rec)` = `0.4·TestPass + 0.3·CodeReview + 0.3·UserAcceptance`
- `CostEfficiency = 100·Budget/ActualCost`
- 统一采集 `unified_metrics(rec)`：Completion / Quality / CostEfficiency / Speed / Robustness（v2.0 §9）
- `compare(swarm_rec, base_rec)`（默认 `symmetric_cost=True`，Owner 修正 2026-06-09）：
  - `G_E = Q_swarm − Q_base`
  - `C_swarm = N_agent_swarm·(CostEfficiency_swarm/100 + 0.5)`；`C_base = N_agent_base·(CostEfficiency_base/100 + 0.5)`（对称）
  - `G_E,c = (Q_swarm/C_swarm) − (Q_base/C_base)`
  - 字面 v2.0（`C_base=1.0`）仅 `symmetric_cost=False` 保留参考；背景见 [`OWNER-NOTE-cost-normalized-gain.md`](./OWNER-NOTE-cost-normalized-gain.md)。
- `evaluate(swarm_rec, [baselines])`：对全部基线比较；`swarm_valid` 要求对每个基线 `G_E>0` 且 `G_E,c>0`。

## 4. 谁产出什么

| 字段族 | swarm 侧现状 | sub-agent 侧需产出 |
|---|---|---|
| Completion (`completed/total`) | ✅ 任务状态 | ✅ 需提供 |
| Cost (`actual_cost_usd`/`model_tokens`)、`n_agent` | ✅ usage 已采集 | ✅ 需提供 |
| Time (`actual_time_s`) | ✅ 时间戳 | ✅ 需提供 |
| Robustness (`recovered/total_failures`) | 🟡 需计数 | ✅ 需提供 |
| **Quality (`test_pass_rate`/`code_review_score`/`user_acceptance`)** | 🔴 **未插桩** | 🔴 **需插桩** |

> **关键阻塞**：Quality 在 **swarm 与 sub-agent 两侧都未插桩**（无 CI/测试通过率、评审分、验收）。没有 Quality 就无 `Q` → 无 `G_E`。这是「记录已可比较、但记录尚不可生产」的根本原因。

## 5. 接入路径

1. 双方各实现一个「跑统一任务集 → 产出 `BenchmarkRunRecord`」的 runner（sub-agent 侧在其程序内；swarm 侧可由 `SwarmRunMetricsCollector` 扩展 + Quality 插桩）。
2. 统一任务集与 `task_set_id`、同等约束（同模型网关、同预算口径）。
3. 把两侧记录交给 `benchmark/baselines/evaluate(...)` → 得 `G_E`/`G_E,c` 与 `swarm_valid`。

## 6. 待对齐

- Quality 三输入的采集口径与 CI/评审/验收来源。
- `CostEfficiency` 口径（`S_cost` vs `E_cost`）与基线参考系数（×0.75/0.85/0.90/0.95）在公式中的确切作用。
- 统一任务集与数据集（各场景）。