Agent Swarm v6：基准 v2.1、主控 Agent、实质性对等回复、客户端指南

- 基准标准 v2.1：SwarmMetrics（15 字段）、τ/η/P_decision/reward 公式、对称 G_E,c（修正 C_base=1.0 退化）、Σλ=1.0 校验；新增基线对比与运行记录 schema；指标覆盖缺口分析；参考系数暂留为元数据（待量化）。
- 主控 Agent 实体（分解 / 评审决策 / 汇总）；事件契约修正（timeline.title、budget.threshold_pct、handoff 角色、task.released）+ 契约校验脚本。
- 实质性 LLM 对等回复（含降级回退）；集成契约（runtime / event / usage / audit / frontend / capability / security）；CLIENT_GUIDE 客户端指南；CI 工作流；治理与交付文档。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

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

@@ -0,0 +1,57 @@
+# 指标采集覆盖与缺口根因分析（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` 是这一缺口的**诚实证据**；不得以占位分值对外宣称已具备量化自证能力。