Files

T

Songhaoz666andClaude Opus 4.8 54cb327348 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

4.3 KiB

Raw Blame History

前端事件 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、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 通道如何衔接。

4.3 KiB Raw Blame History Unescape Escape