# 前端事件 API（Frontend Event API）

> 状态：**DRAFT / 待对齐 Frontend & Product Team**。
>
> 依据：`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 | `task.retried` + `timeline.updated`（`Review cycle N`） | 独立 review/retry 事件类型与时间线 schema |
| 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/retry/collaboration 缺独立事件类型（当前借 `task.retried`/`timeline.updated`）。
- 待对齐：Frontend / Product Team 确认蜂群三视图（graph / timeline / cost）入口与事件流形态；与 HM 的 `/api/user/tasks/{id}/events` 通道如何衔接。