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/integration/event-schema.md

@@ -0,0 +1,98 @@
+# Swarm 运行时事件 Schema（回调 / 事件流）
+
+> 状态：**已对齐 HM 实现**（依据 `heicode-mananger/heicode/controller/agent_callback.go`，handler `POST /api/agent/callbacks/runtime-events`）。本文是 Swarm → HM 回调与 `GET …/{id}/events` 事件流的统一 schema。
+>
+> 配套：生命周期与签名见 [`runtime-contract.md`](./runtime-contract.md)。
+
+## 1. 传输与鉴权
+
+- Swarm → HM：`POST {callback.url}`（create 时下发）。
+- 鉴权二选一：服务令牌 `X-Agent-Service-Token`（或 `Authorization: Bearer`），或 HMAC 签名。
+- **HMAC 签名（已实现，与 HM 一致）**：
+  - 头：`X-Agent-Timestamp`（Unix 毫秒）、`X-Agent-Signature`、`X-Agent-Event-Id`、`X-Correlation-ID`（均含 `X-Agnet-` 兼容别名）。
+  - 规范串：`canonical = f"{timestamp}.{event_id}.{raw_body}"`。
+  - 签名：`X-Agent-Signature = "sha256=" + hex(HMAC_SHA256(secret, canonical))`。
+  - secret：`AGENT_CALLBACK_SIGNING_SECRET`（兼容 `AGNET_…`，支持 `…_REF` 的 `azkv://` 解析）。
+  - 时间容差：HM 默认 300s（`AGENT_CALLBACK_SIGNATURE_TOLERANCE_SECONDS`）。
+- **幂等去重**：HM 依次按 `X-Agent-Event-Id` 头 → body `event_id` → `idempotency_key`。重复返回 `{inserted:false, idempotent:true, deduplicated:true}`。
+
+## 2. 事件 Envelope
+
+```jsonc
+{
+  "event_id": "evt-...",            // 必填；去重主键
+  "idempotency_key": "...",          // 可选；缺省回退 event_id
+  "event_type": "task.completed",    // 必填；取值见 §4
+  "deployment_id": "runtime-dep-...",// 运行时部署 ID
+  "swarm_id": "swarm-...",           // 工作流 ID（事件按此持久化）
+  "agent_instance_id": "...",        // Agent 实例/角色实例 ID（可选）
+  "task_id": "...",                  // 任务相关事件填
+  "occurred_at": "2026-06-08T...Z",  // 事件时间
+  "correlation_id": "corr-...",      // 追踪 ID（X-Correlation-ID）
+  "source": "heicode-swarm-runtime", // 事件来源标识
+  "metadata": { },                   // 自定义元数据（不得含明文密钥）
+  "payload": { },                    // 事件专属字段（见 §4）
+  "artifact": { }                    // 可选；见 §3
+}
+```
+
+## 3. Artifact 子对象（`artifact.created` 及完成事件可带）
+
+```jsonc
+{
+  "artifact_id": "art_...",
+  "artifact_type": "code_patch | document | deployment_manifest",
+  "title": "...",
+  "summary": "...",
+  "uri": "git://repo#branch | runtime://...",
+  "checksum": "<commit_sha>",
+  "metadata": { "redacted": true, "agent_role": "...", "files_modified": [] }
+}
+```
+
+## 4. 事件类型注册表（与 HM 一致）
+
+| event_type | payload 必填字段（HM 校验） | 分类 | Swarm 是否发出 |
+|---|---|---|---|
+| `deployment.status_changed` | `status` | deployment | ✅ |
+| `phase.changed` | `stage` 或 `checkpoint` | ordinary_sub | ❌（暂未用） |
+| `agent.started` | `agent_role` | ordinary_sub | ❌ |
+| `agent.completed` | `agent_role` | ordinary_sub | ❌ |
+| `agent.crashed` | `agent_role`, `reason` | ordinary_sub | ❌ |
+| `task.created` | `task_id`, `title` | swarm_task_flow | ✅ |
+| `task.claimed` | `task_id`, `agent_role` | swarm_task_flow | ✅ |
+| `task.running` | `task_id`, `agent_role` | swarm_task_flow | ✅ |
+| `task.heartbeat` | `task_id`, `agent_role` | swarm_task_flow | ✅ |
+| `task.blocked` | `task_id`, `reason` | swarm_task_flow | ✅ |
+| `task.retried` | `task_id`, `attempt` | swarm_task_flow | ✅ |
+| `task.released` | `task_id`, `agent_role` | swarm_task_flow | ⚠️ 未发出（见 §6） |
+| `task.failed` | `task_id`, `reason` | swarm_task_flow | ✅ |
+| `task.completed` | `task_id` | swarm_task_flow | ✅ |
+| `handoff.requested` | `task_id`, `from_role`, `to_role` | swarm_task_flow | ✅ |
+| `handoff.completed` | `task_id`, `from_role`, `to_role` | swarm_task_flow | ⚠️ 缺 `from_role`/`to_role`（见 §6） |
+| `approval.requested` | `approval_id`, `operation`, `risk_level` | approval | ✅ |
+| `artifact.created` | `artifact_id` | artifact | ✅ |
+| `timeline.updated` | `title` | timeline | ⚠️ 发出 `summary`，缺 `title`（见 §6） |
+| `sk_tool.called` | `tool_name`, `tool_invocation_id` | sk | ❌（无 SK 工具） |
+| `sk_tool.completed` | `tool_name`, `tool_invocation_id` | sk | ❌ |
+| `sk_tool.failed` | `tool_name`, `tool_invocation_id`, `reason` | sk | ❌ |
+| `budget.alert` | `threshold_pct` | budget | ⚠️ 发出 `threshold`，缺 `threshold_pct`（见 §6） |
+
+> 说明：评审/重做循环复用 `task.retried` + `timeline.updated`（`Review cycle N`）表达，无单独 review 事件类型；如 HM 前端需要独立 review 事件，列为待对齐项。
+
+## 5. HM 响应
+
+```json
+{ "success": true, "event_id": "evt-...", "inserted": true, "idempotent": false, "deduplicated": false, "deployment_id": "dep_..." }
+```
+
+## 6. 已知对齐缺口（需在 Swarm 代码修正）
+
+下列为本仓 `orchestrator/` 当前发出字段与 HM 校验的差异，应在对应 emit 处修正后再宣称完全对齐：
+
+1. **`timeline.updated`**：HM 要求 `title`；当前发 `summary`。修正：payload 增加 `title`（可复用 `summary`）。
+2. **`budget.alert`**：HM 要求 `threshold_pct`；当前发 `threshold`（如 `0.8`）。修正：增加 `threshold_pct`（百分比，如 `80`）。
+3. **`handoff.completed`**：HM 要求 `from_role`/`to_role`；当前缺。修正：在 `finalize_parent_after_child` / handoff 完成处补 `from_role`/`to_role`。
+4. **`task.released`**：HM 注册表含此事件；`task_queue.release_task` 当前静默。修正：释放任务时发 `task.released`（`task_id`, `agent_role`）。
+
+> 这些是确定性的小修，建议配 contract test（按 HM 必填字段断言每类事件 payload）。