xiaohei/Agentswarm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
feat/queen-convergence
Agentswarm/docs/integration/frontend-event-api.md
T
Songhaoz666andClaude Opus 4.8 a7d2bb2870 评审/返工时间线对客户端可见：review/rework 4 类脱敏事件纳入冻结集（Refs #34） 
文档：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>
2026-06-11 17:10:57 +08:00

7.0 KiB
Raw Permalink Blame History

前端事件 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、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（FROZEN v1，客户端事件集 + sequence）。即 run/task/event 的数据契约已稳定冻结。
  • 「Agent Registry / 调度入口统一」——蜂群内已统一（单实现）：Agent 经 WS /ws/{agent_id} 注册能力（agent_registry）；调度由 swarm_dispatch 自选（能力 + 信息素 τ + 负载 + 预算，见 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 口径）。

Reference in New Issue View Git Blame Copy Permalink