Agentswarm/docs/benchmark/swarm-metrics-schema.md

Swarm Metrics Schema（v2.0）

状态：公式已对齐标准 v2.0；采集器部分落地。

依据：Agent 蜂群指标量化与标准 v2.0（§3–§8）。配套：swarm-benchmark-protocol.md、metric-coverage-gaps.md、telemetry-architecture.md。

实现：公式见 benchmark/metrics.py（纯函数，含 v2.0 推荐权重常量 TAU_WEIGHTS/ETA_WEIGHTS/REWARD_WEIGHTS/SWARM_WEIGHTS/LAMBDA_WEIGHTS/THETA_DEFAULTS）；真实采集见 benchmark/collectors/run_collector.py（SwarmRunMetricsCollector）。

0. 采集接口（标准 §8.1）

@dataclass
class SwarmMetrics:
    tau: float            # 信息素得分
    eta: float            # 启发式得分
    p_decision: float     # 决策概率
    reward: float         # 执行奖励
    s_completion: float
    s_gain: float
    s_collaboration: float
    s_communication: float
    s_cost: float
    s_robustness: float
    s_governance: float
    s_swarm: float        # 蜂群总分
    g_e: float            # 涌现增益
    g_e_cost: float       # 成本归一化增益
    benchmark: float      # 综合评分

SwarmRunMetricsCollector 真实计算 s_completion/s_collaboration/s_cost/s_robustness，其余返回 NaN 并在 coverage 标记 False（不伪造分值）。

1. 决策层（标准 §3）

τ(s,a,r) = w₁·Success + w₂·Quality + w₃·Acceptance − w₄·Cost − w₅·Time − w₆·Risk − w₇·Rollback
η(s,a,r) = γ₁·Match + γ₂·Urgency + γ₃·Dependency + γ₄·Resource + γ₅·Confidence − γ₆·Risk − γ₇·BudgetPressure
P(s,a,r) = τ^α·η^β / Σ τ_i^α·η_i^β
P_decision = τ^α · η^β · 100        # v2.0 §3.3（变更）

τ 权重（v2.0）：Success 0.25 · Quality 0.20 · Acceptance 0.20（提升为一级因子） · Cost 0.10 · Time 0.10 · Risk 0.08 · Rollback 0.07。 η 权重（v2.0）：Match 0.25 · Urgency 0.15 · Dependency 0.15 · Resource 0.15 · Confidence 0.10（新增） · Risk 0.10 · BudgetPressure 0.10。

✅ τ/η/P 引擎已落地（orchestrator/decision_engine.py，Group A / Option A 单边）：信息素 trail 持久于 Redis（学习常开），概率选择门控 ENABLE_ACO_DISPATCH（默认关）。下表为沉积/评分时各因子的真实喂入状态——无信号的因子喂 0 或中性常数，不伪造（设计与局限见 decision-engine.md）。

因子	数据来源（标准）	本仓沉积/评分时喂入
τ.Success	Task 完成记录	✅ 1/0
τ.Quality	测试 / CI/CD	🟡 run 级 fixture 评分已有（Group B），但晚于沉积时点 → 暂 = success
τ.Acceptance	人工验收日志	🔴 无每任务验收信号 → 0
τ.Cost	资源监控	✅ 任务成本 / run 预算（未知 → 0）
τ.Time / Risk / Rollback	Runtime / 审计 / 部署	🔴 无每任务目标/信号 → 0
η.Match / Dependency	能力画像 / DAG	✅ Jaccard 匹配 / 下游依赖数
η.Urgency / Resource	任务等待时长 / Agent 空闲槽位	✅
η.Confidence	Agent 自评接口	🔴 未实现 → 中性 0.5（全候选同值，不扭曲排序）
η.Risk / BudgetPressure	风险引擎 / 预算	🔴 无信号 → 0
P_decision	上述综合	✅ ε-greedy 采样 + 每决策遥测（SwarmRun.decisions）；单边匹配，决策质量未证（需 Group C）

2. 执行层（标准 §4）

R = w₁·S_task + w₂·Q_quality + w₃·V_speed + w₄·E_cost + w₅·R_robust + w₆·G_gov − w₇·P_risk − w₈·P_rework
S_task   = CompletedTasks/TotalTasks×100      Q_quality = 0.4·TestPass + 0.3·CodeReview + 0.3·UserAcceptance
V_speed  = 100·TargetTime/ActualTime          E_cost    = 100·ExpectedCost/ActualCost
R_robust = RecoveredFailures/TotalFailures×100 G_gov    = CompliantActions/SensitiveActions×100
P_rework = ReworkCount/TotalTasks×100

R 权重（v2.0，已给定）：S_task 0.20 · Q_quality 0.20（与完成度对齐） · V_speed 0.12 · E_cost 0.13 · R_robust 0.13 · G_gov 0.10 · P_risk 0.07 · P_rework 0.05。

指标	本仓可采集
S_task	✅
Q_quality	🟡 TestPass 已接入（fixture 留出测试 + 沙箱，Group B）；CodeReview/UserAcceptance 缺 → 掩码归一
V_speed	🟡 绑定 fixture 时（target_time_seconds）可算
E_cost	🟡 预算 + 用量齐备时可算
R_robust	✅ retry_count + 任务状态（collector 已算）
G_gov / P_risk / P_rework	🟡 审批合规 / 审批高危占比 / retry 派生——均为已知低估口径（见 metric-coverage-gaps 注）

v2.0 已给定全部 w*/γ* 权重；输入现为有条件采集：绑定 fixture 的 run 可算 reward，开启 ENABLE_ACO_DISPATCH 的 run 可算 τ/η/p_decision；条件不满足 → NaN。

3. 蜂群层（标准 §5，权重未变）

S_swarm = 0.25·S_completion + 0.20·S_gain + 0.15·S_collaboration
        + 0.10·S_communication + 0.10·S_cost + 0.10·S_robustness + 0.10·S_governance
S_completion   = CompletedTasks/TotalTasks×100
S_collaboration= 0.5·HandoffSuccessRate + 0.3·DependencyResolutionRate + 0.2·WorkloadBalanceScore
S_communication= SuccessfulMessages/TotalMessages×100
S_cost         = 100·Budget/ActualUsage
S_robustness   = RecoveredFailures/TotalFailures×100
S_governance   = CompliantOperations/TotalOperations×100

指标	状态
s_completion / s_collaboration / s_robustness	✅ 真实可算（采集器，无条件）
s_cost	🟡 有条件（需预算 + 用量）
s_communication	🟡 有条件（peer 消息请求→应答率，按 correlation_id 内部计数；无 peer 通信 → NaN）
s_governance	🟡 有条件（仅审批可派生）
s_gain	🔴 需基线（见 emergence-evaluation）
s_swarm	🔴 含 gain NaN → 暂为 NaN

4. 说明与待对齐

• 成本口径统一（v2.1）：S_cost（§3）、E_cost（§2）、CostEfficiency（见 cost-normalized-gain）为同一量 100×Budget/ActualCost。

• Q_quality 掩码归一（v2.1 裁定）：Q_quality 是对 {TestPassRate, CodeReviewScore, UserAcceptance} 的加权均值，但只对“该任务适用”的项计权并归一化——不适用项（如非编码任务无 TestPassRate）同时退出分子与分母，权重按比例重分配给其余项，使分值恒在 [0,100] 且跨任务类型可比：

  Q_quality = Σ_{i∈present} wᵢ·xᵢ / Σ_{i∈present} wᵢ      （默认 w = 0.4/0.3/0.3）
  

  • 「是否编码任务」由任务 required_capabilities 是否含 {python, code_generation, testing, pytest} 派生，无需额外输入。
  • 三项全不适用 → NaN（规则 #9，不伪造 0）。三项全适用时退化为 v2.0 的 0.4/0.3/0.3 混合。
  • 实现：benchmark/metrics.py:quality_score（纯函数，缺项传 None）；单测见 scripts/test-benchmark-metrics.py。
  • ⚠️ 该函数为纯公式；其输入（TestPassRate 等）仍未采集（见 metric-coverage-gaps reward 行），故 reward 仍 NaN。

• α/β/ρ/N_agent/ε 取值：标准 §7.2 给推荐初值（1.0 / 2.0 / 0.10 / 5 / 0.10），调优口径待定。

• Q_quality 三项来源、SuccessfulMessages/TotalMessages、Recovered/Total、Compliant/Total、Rework/Total 的精确计数定义。