# 基线运行器与基准套件（Benchmark Group C · #21/#22）

把「swarm vs 基线」从纸面公式变成**可运行的管线**：统一任务集 → 5 个系统各跑一遍 → 统一
`BenchmarkRunRecord` → 评估器算 `G_E`/`G_E,c` → 报告 + 回放归档。本文是 Group C 的唯一入口。

## 1. 管线

```
benchmark/tasksets/<id>  ──┐
                           ├─ runners.run_all(taskset, backend) ──► {system: BenchmarkRunRecord}
共享 ExecutionBackend ──────┘            │（5 系统同后端同任务集，仅拓扑不同）
                                         ▼
            reports.build_report ──► G_E / G_E,c / coverage / confidence / swarm_valid
                                         ▼
            replay.save_archive ──► records.json / report.json / report.md / meta.json
```

入口：`scripts/run-benchmark-suite.py --taskset coding-set-1 [--backend offline|openai]`。

## 2. 五个系统（标准 §9.1，仅拓扑不同）

| system | 文件 | 拓扑（公平：同后端同任务集） | n_agent |
|---|---|---|---|
| single | `runners/single.py` | 1 次生成，无评审 | 1 |
| strong | `runners/strong.py` | 1 次生成，**更强/更贵后端**（×0.95 最难超） | 1 |
| chain | `runners/chain.py` | 串行 impl→test→doc，无协作/评审 | 3 |
| sub | `runners/sub_agent.py` | 主管分解 + 3 子агент，无对等/评审（×0.90 最近邻） | 4 |
| swarm | `runners/swarm.py` | **去中心化**：种子 → 自选 + 自主分解 → 专家执行 → **同伴交叉评审** → 收敛 → 综合（calls=6, review=1） | 3 |

> swarm 拓扑已对齐**去中心化重构**（播种/自选/自主分解/竞争/交叉评审/收敛，见 `docs/swarm/decentralized-rework-plan.md`），非旧 Master「分解→派发→单评审」。仍用**同一离线后端**建模以保证公平对比；驱动活体编排器会换后端→记录不可比，故另计（见 `runners/swarm.py` 说明），活体全流程由 `scripts/test-workflow-e2e.py` 验证。

每个系统的产出物用 **fixture 留出测试**在 Group B 沙箱里评分得 `TestPassRate`（权威，非自评）。

## 3. 执行后端（公平网关，`runners/backend.py`）

- **OfflineBackend**（默认）：确定性、无 key、无网络。回显 fixture 的 `reference_solution/`，按调用数计名义成本。**对所有系统完全相同** → 管线可验证，但**不可能也不应显示蜂群质量优势**（防造假）。
- **OpenAIBackend**：真实 OpenAI 兼容生成（需 `OPENAI_API_KEY`），产出真实文件 + token/成本。**真实 `G_E` 由它产生。**

## 4. 当前能得到什么 / 不能得到什么

**能**（Offline，CI 每次跑）：完整管线、5 份非 NaN 记录、`G_E`/`G_E,c`/coverage/confidence、回放归档、Markdown 报告。

**不能**（诚实）：
- Offline `G_E=0`、`swarm_valid=False`——同一参考解，无差异。**这是正确的反造假结果，不是 bug。**
- 真实 `G_E>0` 需 `--backend openai` + **足量冻结任务集**（当前仅 1 个示例任务）+ **多次运行求方差**（当前 confidence=none/low）。
- `CodeReview`/`UserAcceptance` 未采集（掩码忽略）。
- 完整 `Benchmark_Agent` 需**活体 swarm run 的 SwarmMetrics**（S_swarm/Reward/Observability，来自 Group A/B 的 collector）与本套件 `G_E` 的合成——报告里标为 NOT AVAILABLE，**不猜数**。

## 5. 与验收（#13/Issue #2）的关系

本套件是 #13 验收的**必要管线**，但**本身不构成验收**。验收要求：真实后端、冻结任务集、多次运行、
对**全部** A–D 满足 `G_E>0` 且 `G_E,c>0`、并能排除「靠堆 Agent/Token 变强」。在拿到这些真实结果前，
**不得关闭 Issue #2/#13，不得宣称 Agent Swarm 正式验收通过。**

## 6. 测试

- `scripts/test-benchmark-runners.py`：5 runner 产出有效记录、offline 质量一致（G_E=0 反造假）、
  报告/coverage/confidence、回放归档（hermetic）。
- `scripts/run-benchmark-suite.py`：CI offline smoke gate（防回归）。