Agentswarm/docs/benchmark/IMPORTANT-metric-coverage-gaps.md

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

状态：现状分析。说明 SwarmRunMetricsCollector（benchmark/collectors/run_collector.py）当前能真实计算哪些指标、哪些返回 NaN + coverage=False，以及为什么。

配套：swarm-metrics-schema.md、telemetry-architecture.md、emergence-evaluation.md、baseline-comparison.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 是这一缺口的诚实证据；不得以占位分值对外宣称已具备量化自证能力。