# 指标采集覆盖与缺口根因分析（Metric Coverage Gaps）

> 状态：**现状分析**。说明 `SwarmRunMetricsCollector`（`benchmark/collectors/run_collector.py`）当前能真实计算哪些指标、哪些返回 `NaN + coverage=False`，以及**为什么**。
>
> 配套：[`swarm-metrics-schema.md`](./swarm-metrics-schema.md)、[`telemetry-architecture.md`](./telemetry-architecture.md)、[`emergence-evaluation.md`](./emergence-evaluation.md)、[`baseline-comparison.md`](./baseline-comparison.md)、[`governance-score.md`](./governance-score.md)。

## 1. 一句话根因

本仓最初是**多 Agent 工作流执行器**，不是**被插桩的基准测量目标**。能算出来的指标是「执行过程本就会产生」的副产物；其余指标各自缺少执行器从不需要产生的东西（基线 / 计数器 / 决策机制 / 输入）。**v2.0 已给定全部权重（τ/η/reward/λ）**，但这不改变「输入/机制缺失」的根因。

## 2. 覆盖现状（v2.0 `SwarmMetrics` 共 15 字段）

无条件真实可算 3 项（completion/collaboration/robustness）；有条件真实可算 7 项（cost/governance/communication/reward/tau/eta/p_decision，仅在该 run 走过对应路径时）。即单次 run 最多 10 项真实可算，其余仍 NaN。

| 字段 | 状态 | 数据来源 / 缺口 |
|---|---|---|
| `s_completion` | ✅ 真实 | 任务状态统计 |
| `s_collaboration` | ✅ 真实 | `handoff.*` 事件 + `depends_on` + `assigned_agent_id` |
| `s_cost` | 🟡 部分 | 每任务 `usage.model_cost_usd` + 请求 `budget.max_cost_usd`；缺预算/用量 → NaN |
| `s_robustness` | ✅ 真实 | `retry_count` + 任务状态 |
| `s_governance` | 🟡 部分 | 仅审批可派生；无审批 → NaN |
| `s_communication` | 🟡 部分 | peer 消息内部计数（请求→应答率，按 `correlation_id`）；无 peer 通信 → NaN |
| `reward` | 🟡 部分 | 绑定 fixture 时：`Q_quality`=沙箱评测留出测试的 TestPassRate（掩码归一）、`V_speed`=fixture target_time vs 实际时长、`E_cost`/`R_robust`/`G_gov`/`P_rework` 取自 run、`P_risk` 由审批风险派生（无受治理操作→0，见下注）；未绑定 fixture → NaN |
| `tau` / `eta` / `p_decision` | 🟡 部分 | ACO 决策引擎（`ENABLE_ACO_DISPATCH` 开启时按采样决策记录均值；学习常开但选择门控）；无决策记录 → NaN |
| `s_gain` | 🔴 NaN | 需基线 |
| `s_swarm` / `g_e` / `g_e_cost` / `benchmark` | 🔴 NaN | 依赖上述（`gain` 仍 NaN → 聚合 NaN） |

> ⚠️ `reward` 的 `P_risk` 由审批 `risk_level` 派生，**无受治理操作时记 0**——这是与治理覆盖缺口绑定的**已知低估**（未经审批门的风险面未被计入）。`P_rework` 目前仅由 `retry_count>0` 派生，未含评审重开计数。两者均在 collector 与本表中显式标注，不作隐藏假设。

> 不可算的指标返回 `NaN` 并在 `coverage` 标记 `False`，**不伪造 0/100 分值**（组织规则 #9）。

## 3. 为什么基础几项能算

它们都是执行器正常运行的副产物，已存在于 orchestrator 状态：
- `completion` ← 队列本就跟踪任务状态。
- `collaboration` ← 移交事件、依赖、被分配 Agent 都是派发所需。
- `cost` ← 计费归因本就记录每任务 `model_cost_usd`；预算在请求里。
- `robustness` ← 重试逻辑本就维护 `retry_count` 与状态。

`communication`/`reward` 不是天然副产物，而是本仓新增插桩（通信计数器 / fixture 沙箱评测）后才可算——见 §4 顶部「已关闭」。

## 4. 为什么这几个算不出（逐项根因）

> ✅ **已关闭（本仓）**：
> - `communication` —— peer 消息原先只路由不计数，现已在 orchestrator 路由处按 `correlation_id` 计请求/应答（`SwarmRun.collaboration` 内部计数，不进 Manager 事件流），collector 据此算 `SuccessfulMessages/TotalMessages×100`；无 peer 通信的 run 仍 NaN（不伪造）。
> - `reward`（Group B）—— 已建**留出测试沙箱**（`orchestrator/sandbox.py`，Pod 内执行 + 环境清洗 + 超时/限额）与 **fixture**（`benchmark/fixtures/`）：绑定 fixture 的 run 在完成时用留出测试评分得 `TestPassRate` → 经掩码 `quality_score` 得 `Q_quality`，再由 collector 合成 `reward`。`CodeReview`/`UserAcceptance` 仍未采集（掩码自动忽略）；`P_risk` 为审批派生的已知低估。未绑定 fixture 的 run 仍 NaN。
> - `tau`/`eta`/`p_decision`（Group A）—— 已建 **ACO 决策引擎**（`orchestrator/decision_engine.py`）：信息素 trail（Redis 持久、按 `(role, agent)` 键控、**学习常开**）+ η 启发式评分 + ε-greedy 概率采样（**选择门控** `ENABLE_ACO_DISPATCH`，默认关）。决策遥测落 `SwarmRun.decisions`，collector 取均值。**单边匹配（Option A）**、τ 的 quality 输入暂 = success、**决策质量未证（需 Group C）**——均已在 decision-engine.md 标注。

| 指标 | 根因（缺什么） | 类别 | 关闭成本 |
|---|---|---|---|
| `gain`（`G_E = Q_swarm − Q_base`） | **本质是对比指标**，单次 swarm run 无法自算；缺 baseline 运行器（Single/Strong/Chain/Sub-Agent）、对比 harness 与数据集 | 缺**基线** | 高（跨团队/基础设施/设计决策） |
| `governance`（`Compliant/Total ops`） | 有审批机制，但无「受治理/敏感操作 vs 合规」计数；更广的治理面（tool/MCP 权限、allowed_paths 强制）未实现，**没有受治理操作记录可计数**；无审批的 run → 0 操作 → 空集 → NaN | 缺**计数器 + 策略强制点** | 中（计数器 + 部分强制点） |
| `reward` 的剩余短板 | 主输入 `Q_quality` 已通过 fixture 沙箱采集；但 `CodeReview`/`UserAcceptance` 仍缺（需评审/验收信号源），`P_risk` 仅审批派生（低估），fixture 只有 1 个示例、统一任务集未建 | 缺**评审/验收信号 + 统一任务集** | 中（评审/验收接入 + 任务集扩充） |
| `tau`/`eta`/`p_decision` 的剩余短板 | 机制已建但**单边**（任务对 Agent 的全局路由 = Option B 未实现）；τ 的 quality/acceptance/time 输入无信号暂 0 或 = success；**概率派发是否优于贪心未证**（需 Group C 对比） | 缺**双边匹配 + 决策质量验证** | 中-高（matchmaker + 对比 harness） |

## 5. 关闭路径（按成本排序）

1. **低成本（本仓可做）**：~~`s_communication`~~（✅ 已关闭）、`s_governance` — 通信计数器已落地；治理仍需在受治理操作处加计数器 + 策略强制点，按 `swarm_id` 聚合。无条件真实项 3 项，有条件已增至 4 项（cost/governance/communication/reward）。
2. **中成本**：~~`reward`~~（✅ 已关闭，本仓）— `Q_quality` 主输入已由 fixture 沙箱采集；剩余为**扩充统一任务集** + 接入 `CodeReview`/`UserAcceptance` 评审/验收信号（部分需 Product/Manager）。
3. **高成本**：
   - ~~`p_decision`~~（✅ 已关闭，本仓，Option A）— `τ/η/P` 决策引擎与信息素历史库已落地（`ENABLE_ACO_DISPATCH` 门控）；剩余为 Option B 双边匹配与决策质量验证（依赖 Group C）。
   - `gain`（及由其驱动的 `Benchmark_Agent`、`G_E,c`、「Swarm > baselines」验收）— 🟡 **基线对比管线已落地**（`benchmark/runners/` + `tasksets/` + `reports/` + `replay/`，#21/#22），CI offline smoke 跑通；但 **Offline 仅验证管线（G_E=0、无偏）**，真实 `G_E>0` 仍需 `--backend openai` + 足量冻结任务集 + 多次运行（方差/显著性）+ Quality 评审/验收输入。**这是最后一块，也是唯一动验收的一块**（见 baseline-runners.md）。

## 6. 影响

- 在 `gain` 落地前，**无法输出完整 `Benchmark_Agent`，也无法证明 Swarm 优于任一基线** —— 这正是工单「当前更接近多 Agent Workflow Demo」的判断依据。
- `NaN + coverage=False` 是这一缺口的**诚实证据**；不得以占位分值对外宣称已具备量化自证能力。