Songhaoz666andClaude Opus 4.8
a7d2bb2870
文档：event-schema §4 增 4 类(标 ⭐ + 脱敏说明)、header 13→17；frontend-event-api 评审/返工时间线行推进为已定义 + header 注明部分推进 + 剩余跨仓项(HM 注册、cockpit 渲染、仅脱敏摘要)；review-loop-protocol §3.2 由"事件不进 Manager 流"更正为"已脱敏外发"。 测试：新增 scripts/test-review-timeline-events.py(单元投影脱敏 + run_cross_review 真实站点发出 + 断言无 evidence/summary 泄漏 + 4 类在冻结集)；test-contract-freeze 的 13-精确断言改为"13 核心为子集"(因 #34 扩到 17)。接入 CI。本地全绿(含 e2e/cross-review 回归)。 影响范围：仅 agent_swarm(orchestrator + docs + 测试 + CI)。Manager：回调新增 4 类(向后兼容；HM agent_callback.go 需登记方可对客户端暴露)。密钥/内容：脱敏投影不含 evidence/summary/原文/密钥。不改契约鉴权/计费/审批链。 Refs #34 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
74 lines
7.0 KiB
Markdown
74 lines
7.0 KiB
Markdown
# 前端事件 API（Frontend Event API）
|
||
|
||
> 状态：**DRAFT / 待对齐 Frontend & Product Team**；**评审/返工时间线部分已推进（#34）**——`review.started`/`review.decision_made`/`rework.requested`/`rework.completed` 已定义为客户端可见事件（脱敏投影）并纳入冻结集（见 §4 / event-schema §4）。其余视图（graph/cost/SSE 传输）仍待 Frontend & Product 冻结。
|
||
>
|
||
> **剩余跨仓项（#34 DoD）**：HM `agent_callback.go` 登记这 4 类；macOS/winos cockpit 渲染评审结论/证据摘要/返工目标/循环次数时间线（客户端仓子工单）；渲染只用脱敏摘要，不展示原文（对齐 security-boundary）。
|
||
>
|
||
> 依据：`heicode-mananger/docs/integration/heicode-desktop-client-api.md`、`docs/integration/manager-side-contract-patches.md §6`。配套：[`event-schema.md`](./event-schema.md)、[`runtime-contract.md`](./runtime-contract.md)。
|
||
|
||
## 1. 现状（重要）
|
||
|
||
- 当前**桌面端是单 Agent 模型**：用户部署「模板 Agent」，客户端从 HM 拿 `subdomain`+`access_token` 后**直连 Agent**走 A2A：`POST {subdomain}/message/stream`（SSE）/ `message/send`、`GET /.well-known/agent.json`、`/health`。HM 不在回路。
|
||
- **HM 尚未定义「蜂群图 / agent 拓扑 / review loop / retry 时间线」的前端事件 API**。蜂群前端契约**归 Swarm + Frontend/Product Team 共同定义**，目前不存在。
|
||
- 因此本文档区分：①HM 既有的任务卡片事件通道；②Swarm 现已提供、前端可消费的 REST；③待定义的蜂群前端事件 API。
|
||
|
||
## 2. HM 既有前端事件通道（任务卡片，非蜂群图）
|
||
|
||
来自 `manager-side-contract-patches.md §6`：
|
||
- `GET /api/user/tasks/{id}/events`（SSE）；HM 当前以**轮询兜底**（active 3s、其它状态 15s）。
|
||
- 建议 SSE 事件名与载荷：
|
||
- `status_changed` → 新状态
|
||
- `followup_added` → followup 载荷
|
||
- `card_updated` → 完整 `HeicodeTaskCard`（`{goal, scope, generated_artifacts, manager_actions:[{label, deeplink}]}`）
|
||
- 这是**任务卡片**视角，不是蜂群 DAG/拓扑视角。
|
||
|
||
## 3. Swarm 现已提供的可消费 REST（已实现）
|
||
|
||
前端（经 HM 或直连受控读接口）可消费：
|
||
|
||
| 接口 | 用途 | 关键字段 |
|
||
|---|---|---|
|
||
| `GET …/{deployment_id}/workflow` | 工作流/阶段视图 | `status`、`summary`、`agent_count`、`tokens`、`tools`、`elapsed_seconds`、`phases[]`、`artifacts[]` |
|
||
| `GET …/{deployment_id}/tasks` | 任务 DAG | 每任务 `task_id`、`agent_role`、`status`、`depends_on`、`parent_task_id`、`root_task_id`、`attempt`、`blocked_reason` |
|
||
| `GET …/{deployment_id}/logs`（`/events`） | 事件流 | 事件 envelope（见 event-schema），分页 `cursor`/`limit` |
|
||
| `GET …/{deployment_id}/metrics` | 指标 | `tasks_by_status`、`agents_connected`、`average_task_duration_seconds`、`budget` |
|
||
| `GET …/{deployment_id}/diagnostics` | 诊断 | 失败任务、回调尝试、审批 |
|
||
|
||
`phases[]` 形如：`{phase_id, name, status, agents[]}`，`name ∈ {Plan, Dispatch, Execute, Handoff, Review, Deliver}`；`agents[]` 形如 `{agent_id, name, role, status, tokens, tools, elapsed_seconds, artifact_ids}`。
|
||
|
||
> 注意：当前**仅 REST 拉取**，Swarm 未向前端推送 SSE/WS。前端可轮询 `/workflow` + `/logs`（用 `cursor` 增量）。
|
||
|
||
## 4. 目标：蜂群前端事件 API（待定义）
|
||
|
||
为支撑工单要求的 swarm graph / agent topology / task DAG / review loop / retry timeline / token-cost monitor / collaboration timeline，建议（待 Frontend/Product Team 冻结）：
|
||
|
||
| UI 视图 | 数据来源（现有） | 缺口 |
|
||
|---|---|---|
|
||
| Task DAG / topology | `/tasks`（`depends_on`）+ `/workflow.phases` | 稳定 graph schema、增量更新事件 |
|
||
| Review loop / retry timeline | **`review.started` / `review.decision_made` / `rework.requested` / `rework.completed`**（#34，脱敏客户端投影，见 event-schema §4）+ `task.retried` | ✅ 事件类型已定义并纳入冻结集（17 类）；HM 注册 + cockpit 渲染（评审结论/证据摘要/返工目标/循环次数）落客户端仓子工单 |
|
||
| Collaboration timeline | `handoff.requested/completed` + peer 路由 | peer 消息事件未对前端暴露 |
|
||
| Token / cost monitor | `/metrics` + `budget.alert`（usage） | 统一 usage 推送（见 usage-billing §7） |
|
||
| 实时推送 | `/logs` 轮询 | 统一 SSE/WS event stream（事件名、断线重连、刷新可恢复） |
|
||
|
||
建议事件流形态（草案）：SSE `GET …/{deployment_id}/stream`，事件名复用 `event-schema` 的 `event_type`，载荷为对应 envelope；前端按 `swarm_id` 渲染、按 `event_id` 去重、断线后用 `/logs?cursor=` 回补。
|
||
|
||
## 5. 缺口与待对齐
|
||
|
||
- 🔴 Swarm 未提供前端 SSE/WS 推送（仅 REST 轮询）。
|
||
- 🔴 蜂群 graph/timeline/cost 的统一前端 schema 未定义。
|
||
- 🟢 review/rework 已有独立客户端事件（#34：`review.started`/`review.decision_made`/`rework.requested`/`rework.completed`，脱敏投影，已纳入冻结集）；collaboration 仍借 `handoff.*`/peer 路由（未单列）。
|
||
- 待对齐：Frontend / Product Team 确认蜂群三视图（graph / timeline / cost）入口与事件流形态；与 HM 的 `/api/user/tasks/{id}/events` 通道如何衔接。
|
||
|
||
## 6. Swarm 侧冻结口径（#18：run/task/event API + Agent Registry/调度）
|
||
|
||
回应 #18 两项 DoD，明确本仓**已满足**的范围与**外部/后续**项（按规则 #9 据实标注，不夸大）：
|
||
|
||
- **「前端可渲染 run/task/event 稳定 API」——本仓已冻结**：前端（经 HM 或受控读接口）用 §3 的 REST 即可稳定渲染：`GET …/{id}`（run 状态）、`/tasks`（task DAG）、`/events?after=<sequence>`（事件流，**per-swarm 严格递增 `sequence` 去重/续传**）、`/workflow`、`/metrics`、`/diagnostics`、`/audit`。事件类型与 envelope 见 [`event-schema.md`](./event-schema.md)（**FROZEN v1**，客户端事件集 + `sequence`）。即 run/task/event 的**数据契约已稳定冻结**。
|
||
- **「Agent Registry / 调度入口统一」——蜂群内已统一（单实现）**：Agent 经 WS `/ws/{agent_id}` 注册能力（`agent_registry`）；调度由 `swarm_dispatch` **自选**（能力 + 信息素 τ + 负载 + 预算，见 [`agent-capability-schema.md`](./agent-capability-schema.md)、`orchestrator/dispatch_score.py`、`orchestrator/decision_engine.py`）。蜂群内**单一调度入口，无双实现**。
|
||
- **外部 / 后续（非本仓范围）**：
|
||
- ① 统一 **SSE/WS 推送传输**：HM Phase2（见 #46 / runtime-contract §8）；当前为 REST 轮询 + `events?after=` 续传，前端不丢步。
|
||
- ② **跨平台统一 agent registry / capability center / quota / region·GPU / provider routing**：Infra/Scheduling Team（#2 对齐对象），非本仓编排器。
|
||
- ③ cockpit 三视图（graph / timeline / cost）**渲染**：客户端仓子工单。
|
||
|
||
> 结论：#18 在**本仓范围内已满足**（run/task/event 稳定 API + 蜂群调度入口统一）；SSE 传输与跨平台 registry 为外部/Phase2。建议 owner 据此关闭本仓部分，或保留 #18 跟踪上述外部项（同 #19 口径）。
|