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>
2026-06-09 16:21:18 +08:00
commit 54cb327348
125 changed files with 22317 additions and 0 deletions
@@ -0,0 +1,123 @@
+# 客户端接入指南（Client Guide）
+
+本文说明**客户端如何与 Agent Swarm 运行时交互**。系统总览见 [README.md](README.md)；接口契约见 [docs/integration/runtime-contract.md](docs/integration/runtime-contract.md)；事件结构见 [docs/integration/event-schema.md](docs/integration/event-schema.md)。
+
+> 架构说明：生产链路中，终端用户通过 **Heicode Manager / 桌面客户端** 提交需求，由 Manager 调用本 Swarm 运行时（见 `heicode-swarm-deferred` 裁定）。「客户端」在本文指**调用 Swarm 运行时 REST API 的一方**（Manager、联调脚本或开发者）。Swarm 不在对话回路，通过**带签名回调**回报状态。
+
+---
+
+## 1. 两个交互面
+
+1. **REST API（客户端 → Swarm）**：创建部署、查询状态/任务/日志/事件/指标、审批、停止。
+2. **回调事件流（Swarm → 客户端/Manager）**：生命周期事件经带 HMAC 签名的回调推送（见 §6）。
+
+WebSocket `/ws/{agent_id}` 仅供 **Agent 执行单元** 接入，**不是客户端接口**。
+
+---
+
+## 2. 鉴权
+
+- 客户端调用带 `Authorization: Bearer <token>`，Swarm 校验 `AGENT_RUNTIME_SERVICE_TOKEN`（兼容 `AGNET_RUNTIME_SERVICE_TOKEN`）。
+- 未配置令牌时为**非安全开发模式**（不校验，仅本地）。
+- 常用请求头：`X-Correlation-ID`（贯穿追踪）、`X-Idempotency-Key`（创建幂等）。
+- 响应信封：成功 `{ "success": true, "data": {...} }`；失败 `{ "success": false, "error": {code,message,request_id} }`。
+
+---
+
+## 3. 生命周期：创建 → 观察 → （审批）→ 停止
+
+### 3.1 创建部署
+`POST /api/swarms`（别名 `/api/agent/swarm/deployments`、`/api/agnet/deployments`）
+
+```bash
+curl -s -X POST http://<host>:8000/api/swarms \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "X-Correlation-ID: corr-123" \
+  -H "X-Idempotency-Key: idem-123" \
+  -d '{
+        "mode": "swarm",
+        "requirement": { "objective": "实现 add(a,b) 并补充测试与说明" },
+        "callback": { "url": "https://your-manager/api/agent/callbacks/runtime-events", "subscribed_events": [] },
+        "metadata": { "manager_deployment_id": "dep-1" }
+      }'
+```
+必填：`requirement.objective`（或 `orchestration_plan.objective`）、`callback.url`、`metadata.manager_deployment_id`。
+
+响应 `data`：`deployment_id`、`runtime_deployment_id`、`swarm_id`(=workflow_id)、`manager_deployment_id`、`mode`、`status`、`created`。**请保存 `deployment_id`** 用于后续查询。
+
+### 3.2 观察
+| 接口 | 用途 |
+|---|---|
+| `GET /api/swarms/{deployment_id}` | 部署状态概要 |
+| `GET /api/swarms/{deployment_id}/workflow` | 工作流/阶段视图（phases、agents、tokens、tools、artifacts、summary） |
+| `GET /api/swarms/{deployment_id}/tasks` | 任务 DAG（task_id、agent_role、status、depends_on…） |
+| `GET /api/swarms/{deployment_id}/logs`（`/events`） | 事件流，分页 `?limit=&cursor=`（断线后用 cursor 回补） |
+| `GET /api/swarms/{deployment_id}/metrics` | 任务/Agent/预算指标 |
+| `GET /api/swarms/{deployment_id}/diagnostics` | 失败、回调尝试、审批诊断 |
+
+状态机：`waiting_approval → running → (blocked ⇄ running) → completed | failed | stopped`。
+
+### 3.3 审批（高危操作）
+当部署进入 `waiting_approval` 并推送 `approval.requested` 时，客户端经 Manager 审批后回执：
+```bash
+curl -s -X POST http://<host>:8000/api/swarms/<deployment_id>/approvals/<approval_id> \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  -d '{ "decision": "approved" }'   # 或 "rejected"，可带 credential_ref / reason
+```
+
+### 3.4 停止
+```bash
+curl -s -X POST http://<host>:8000/api/swarms/<deployment_id>/stop \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  -d '{ "reason": "client requested stop" }'
+```
+
+---
+
+## 4. 健康检查
+
+- `GET /` → `{status, service}`；`GET /health` → 含 Redis 与连接数；`GET /metrics` → Prometheus。
+
+---
+
+## 5. 启用完整工作流
+
+默认仅执行 Manager 提供的编排；要启用「分解 → 评审/重做 → 汇总」主控工作流，运行 Swarm 时设置（默认关闭）：
+- `ENABLE_PLANNER_FALLBACK=1`：无 Manager 分工时由主控 Agent 自动分解。
+- `ENABLE_REVIEW_LOOP=1` / `MAX_REVIEW_CYCLES=2`：主控评审与重做循环 + 结果汇总。
+- 模型走 OpenAI 兼容网关（`OPENAI_API_KEY`/`OPENAI_API_BASE`/`OPENAI_MODEL`，经 `secret_ref` 注入）。
+
+---
+
+## 6. 回调事件流（Swarm → 客户端/Manager）
+
+Swarm 向 `callback.url` POST 事件，**带 HMAC 签名**（客户端须验签）：
+- 头：`X-Agent-Timestamp`(ms)、`X-Agent-Signature`、`X-Agent-Event-Id`、`X-Correlation-ID`（+ `X-Agnet-` 兼容别名）。
+- 签名：`sha256=hex(HMAC_SHA256(secret, "{timestamp}.{event_id}.{raw_body}"))`，secret = `AGENT_CALLBACK_SIGNING_SECRET`，时间容差 300s。
+- 幂等：按 `X-Agent-Event-Id` → body `event_id` → `idempotency_key` 去重。
+- 事件类型与必填字段：见 [event-schema.md](docs/integration/event-schema.md)（`deployment.status_changed`、`task.*`、`handoff.*`、`approval.requested`、`artifact.created`、`timeline.updated`、`budget.alert`…）。
+
+客户端可只消费 REST（轮询 `/workflow`+`/logs?cursor=`），或同时接收回调。
+
+---
+
+## 7. 本地联调（无需密钥）
+
+```bash
+# 1) 编排器（内存存储 + 工作流开关）
+set "REDIS_FAKE=1" & set "ENABLE_PLANNER_FALLBACK=1" & set "ENABLE_REVIEW_LOOP=1"
+python -m uvicorn orchestrator.main:app --host 0.0.0.0 --port 8000
+# 2) 无密钥桩 Agent（联调用）
+set "ORCHESTRATOR_URL=ws://localhost:8000" & set "AGENT_ID=stub-1" & set "AGENT_CAPABILITIES=python,code_generation,testing,pytest,technical-writing,general"
+python scripts/stub_agent.py
+# 3) 用 §3.1 的 curl 提交需求，再用 §3.2 观察
+```
+
+---
+
+## 8. 说明与边界
+
+- **桌面/前端 UI**：当前桌面客户端为单 Agent A2A 直连模型；**蜂群图 / 协作时间线**的前端事件 API 尚未冻结（见 [frontend-event-api.md](docs/integration/frontend-event-api.md)）。
+- **不得在请求/回调/日志中出现明文密钥**；凭据一律 `secret_ref`（`azkv://`）。见 [security-boundary.md](docs/integration/security-boundary.md)。
+- 计费在 NewAPI（模型网关）侧按请求计量，Swarm 仅上报用量；见 [usage-billing-schema.md](docs/integration/usage-billing-schema.md)。