# 指标采集覆盖与缺口根因分析（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 字段，4 个真实可算）

| 字段 | 状态 | 数据来源 / 缺口 |
|---|---|---|
| `s_completion` | ✅ 真实 | 任务状态统计 |
| `s_collaboration` | ✅ 真实 | `handoff.*` 事件 + `depends_on` + `assigned_agent_id` |
| `s_cost` | ✅ 真实 | 每任务 `usage.model_cost_usd` + 请求 `budget.max_cost_usd` |
| `s_robustness` | ✅ 真实 | `retry_count` + 任务状态 |
| `s_governance` | 🟡 部分 | 仅审批可派生；无审批 → NaN |
| `s_gain` | 🔴 NaN | 需基线 |
| `s_communication` | 🔴 NaN | 无消息计数 |
| `tau` / `eta` / `p_decision` | 🔴 NaN | 无 τ/η 决策引擎 |
| `reward` | 🔴 NaN | 权重已给定，**输入**未采集 |
| `s_swarm` / `g_e` / `g_e_cost` / `benchmark` | 🔴 NaN | 依赖上述（任一 NaN → 聚合 NaN） |

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

## 3. 为什么这 4 个能算

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

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

| 指标 | 根因（缺什么） | 类别 | 关闭成本 |
|---|---|---|---|
| `gain`（`G_E = Q_swarm − Q_base`） | **本质是对比指标**，单次 swarm run 无法自算；缺 baseline 运行器（Single/Strong/Chain/Sub-Agent）、对比 harness 与数据集 | 缺**基线** | 高（跨团队/基础设施/设计决策） |
| `communication`（`Successful/Total messages`） | peer/WS 消息只**路由**、从不**计数**；无成功/总数计数器，数据流过但未插桩 | 缺**计数器** | 低（加计数器） |
| `governance`（`Compliant/Total ops`） | 有审批机制，但无「受治理/敏感操作 vs 合规」计数；更广的治理面（tool/MCP 权限、allowed_paths 强制）未实现，**没有受治理操作记录可计数**；无审批的 run → 0 操作 → 空集 → NaN | 缺**计数器 + 策略强制点** | 中（计数器 + 部分强制点） |
| `p_decision`（`τ^α·η^β·100`） | v2.0 已给公式，但派发仍是**确定性贪心能力匹配**（`can_agent_run_task`）；ACO 决策模型**未实现**——无信息素 `τ`（历史有效性追踪）、无启发式 `η` 评分；没有可测的概率决策 | 缺**整套机制** | 高（新建决策引擎 + 历史库） |
| `reward`（`w₁·S_task + … − w₈·P_rework`） | v2.0 **已给定 `w₁..w₈`**；但**输入**未采集（`Q_quality` 需 TestPass/CodeReview/UserAcceptance、`P_risk`、`P_rework`）→ 仍不可算 | 缺**输入**（权重已定） | 中（质量/CI/风险/返工接入） |

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

1. **低成本（本仓可做）**：`s_communication`、`s_governance` — 在 peer/WS 发送处与受治理操作处加计数器，按 `swarm_id` 聚合。可把真实可算项从 4 提到 6。
2. **中成本**：`reward` — 权重 v2.0 已定；接入 `Q_quality`（CI/评审/验收）与 risk/rework 输入即可算。
3. **高成本**：
   - `p_decision` — 设计并实现 `τ/η/P` 决策引擎与历史有效性追踪（改变派发机制）。
   - `gain`（及由其驱动的 `Benchmark_Agent`、`G_E,c`、「Swarm > baselines」验收）— 实现 4 类基线运行器 + 统一数据集 + 对比/显著性，属跨团队与基础设施工作（见 baseline-comparison）。

## 6. 影响

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