chenchenandClaude Opus 4.8
c3f51fe479
契约已冻结(agent_swarm#14 runtime-contract v1 / #15 event-schema v1),HM 侧据此 落地两项原本 deferred 的能力,叠在读侧适配(PR #59)之上: - stop(#45):HeicodeStopSwarm 真实调用运行时冻结路径 POST /api/agent/swarm/deployments/{deployment_id}/stop,复用 agent_runtime_client 的配置/URL/信封解析;Bearer SWARM_RUNTIME_SERVICE_TOKEN + X-Idempotency-Key 幂等。 仅 SWARM_RUNTIME_ENABLED=true 且配齐 base_url+token 时发起,否则 POLICY_REJECTED, 绝不伪造 accepted;终态不抢写,由 swarm.stopped 回调写回。 - events SSE(#46 读侧):GET /api/heicode/swarms/:id/events/stream?after=,与 events?after 同源(HM 持久化回调事件,按 user_id 收口 + payload 脱敏),命中终态 (swarm.completed/failed/stopped)/客户端断开/超时(30min)收流。不调运行时。 - docs:刷新 heicode-swarm-deferred.md(登记冻结契约、读侧/stop/SSE 已落地、唯一剩余 计费缺口 #60)与 heicode-desktop-client-api.md §5.2(SSE + stop 端点)。 影响面:Client(新增 SSE 端点 + stop 行为变化)、agent_swarm(按冻结契约调用其 stop)。 不涉及 Manager↔AM、密钥、计费扣费逻辑(计费缺口 #60 仍阻塞于 agent_swarm#16)。 测试:callSwarmRuntimeStop(httptest 校验路径/鉴权/幂等头/信封解析/错误路径/runtime id 回退)+ swarmEventIsTerminal;go build ./... 与 controller 测试全绿。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
8.1 KiB
8.1 KiB
Heicode 蜂群（Swarm）—— 现状裁定与后续跟踪入口（HM 侧）
起草：2026-06-05 · 更新：2026-06-10（同步
agent_swarm当前状态）· 状态：跟踪占位（HM 侧不实现，归口 AM / Swarm）本文是 PR #15「文档大同步」删除全部旧 sub/蜂群文档后留下的追踪入口，回答三件事：① 旧文档为什么作废、② 蜂群能力现在归谁、③ 未来对接/待定项在哪里跟踪。删除旧文档≠放弃蜂群能力，上下文迁移到本文。
2026-06-10 勘误：蜂群仓库名是
agent_swarm（GitHubxmindlab-heicode/agent_swarm；产品名 HeiCode Swarm），不是HeiCode-Swarm。该仓已从「仅/tasks」演进为完整的 Master-Agent 编排运行时并起草了正式契约runtime-contract.md——本文下文已据实更新。
1. 裁定（当前结论）
- HM（Heicode Manager）当前不实现 swarm runtime。 HM 的职责边界是：模型网关（
/v1/*）+ 资源/权限/计费/审计 + 模板 Agent 部署编排（经 AM 启动常驻 agent、客户端直连）。多 agent 蜂群编排不在 HM 端。 - 旧的「HM 内部 sub/蜂群任务编排」模型已作废。 那套（sub 任务、display_status、HM 侧蜂群 runtime 对接草案）随产品转向「模板 Agent + 客户端直连」一并下线，相关代码删除清单见
heicode-hm-legacy-teardown.md，当前模型见heicode-hm-template-agent-model.md。 - 新版蜂群能力在
agent_swarm（HeiCode Swarm）仓，不在本仓。 当前模型：主控 Agent（Master Agent，orchestrator/master_agent.py）把需求分解为子任务 → 派发给不同领域的专家 Agent 并行执行 → 重叠领域协作/移交 → 主控评审/重做循环（受MAX_REVIEW_CYCLES约束）→ 汇总交付；Orchestrator(FastAPI) + Redis 权威状态 + WebSocket Agent 协议 + Prometheus 指标。旧文档描述的「HM 主导编排蜂群 / 仅/tasks」已作废。HM 侧最多提供资源/计费/鉴权支撑面，runtime 与编排由 Swarm 承载。 - 契约已冻结为 v1（2026-06-10）。 Swarm 侧已冻结
runtime-contract v1（agent_swarm#14：stop =POST /api/agent/swarm/deployments/{deployment_id}/stop+Bearer SWARM_RUNTIME_SERVICE_TOKEN+X-Idempotency-Key，受理后异步回推swarm.stopped；deployment_id↔swarm_id↔manager_deployment_id三映射；状态 §4.1blocked→degraded）与event-schema v1（agent_swarm#15：per-swarm 严格递增sequence；新增 6 类事件；secret_ref/credential_ref/signing_secret_ref按设计以azkv://引用透传）。 - HM 侧已据冻结契约落地读侧 + stop + SSE（不再 deferred 的部分）：
- 只读查询（#45 / PR #59）🟢：list/status/
events?after/artifacts 全部基于 HM 已持久化的回调事件（agent_callback.go→AgentCallbackEvent），按user_id收口、payload 递归脱敏（剔除 secret_ref/凭据/大字段 +RedactText兜底），无需调用 Swarm 运行时。controller/agent_swarm_query.go。 - stop（#45）🟢（受开关约束）：真实调用运行时冻结路径，复用
agent_runtime_client的配置/URL/信封解析;SWARM_RUNTIME_ENABLED=true且配齐SWARM_RUNTIME_BASE_URL+SWARM_RUNTIME_SERVICE_TOKEN时才发起，否则POLICY_REJECTED，绝不伪造 accepted。终态不抢写,由swarm.stopped回调写回。 - 事件 SSE 实时流（#46 读侧）🟢：
GET /api/heicode/swarms/:id/events/stream?after=，与events?after同源（HM 持久化事件），命中终态（swarm.completed/failed/stopped）/客户端断开/超时结束，不依赖运行时。
- 只读查询（#45 / PR #59）🟢：list/status/
- 仍 deferred / 阻塞的部分： ① per-user 计费令牌注入（#60）——swarm create 目前未像模板 Agent 那样现签隐藏
sk-注入运行时（OPENAI_API_KEY+OPENAI_API_BASE=HM/v1），是 HM 唯一计费缺口，阻塞于 Swarm 对agent_swarm#16注入口径 A/B 的确认；② 事件 append 写入 / 主动拉取仍走回调被动落库，未做 HM→Swarm 主动拉取（无对应需求）。
2. 能力归属与后续跟踪入口
| 项 | 归属仓 / 负责人 | 说明 |
|---|---|---|
| Swarm runtime / 多 agent 编排 | agent_swarm（产品名 HeiCode Swarm，@Songhaoz666） |
执行面、Master-Agent 编排、回调、Swarm Runtime |
| Manager ↔ Swarm 契约 | Swarm 侧契约已冻结为 v1：runtime-contract v1（agent_swarm#14）+ event-schema v1（agent_swarm#15），见 agent_swarm/docs/integration/；HM 侧据此对接，本文为 HM 侧锚点 |
Swarm 已实现生命周期接口 create/status/tasks/logs/events/metrics/workflow/diagnostics/stop/approvals（均带 deployment_id，三组路径别名 /api/swarms、/api/agent/swarm/deployments、/api/agnet/deployments）；HM 接入跟踪在 #45/#46/#60 与 PR #59 |
| Agent 运行时（单 agent，已落地） | agent_management（AM）（@azgy） |
模板 Agent 启动/状态/停止/删除，契约见 heicode-am-contract.md |
HM 侧对接状态（2026-06-10）：契约已按
runtime-contract v1/event-schema v1冻结（agent_swarm#14/#15）。HM 已落地 #45（只读查询 + stop，PR #59 + 本批）与 #46 读侧（events SSE）；剩余阻塞仅 #60（per-user 计费令牌注入，待agent_swarm#16A/B 确认）。本文仍是「蜂群在 HM 侧」的唯一锚点——不恢复旧文档。
3. 已删除文档的迁移映射（PR #15）
对照 Fasthei 复审要求：每份删除文档标明是「作废 / 迁移 / deferred」，以及上下文去向。
蜂群 / swarm 相关（7 份，上下文迁移至本文 + Swarm 仓）
| 删除的文档 | 处置 | 去向 |
|---|---|---|
docs/heicode-manager-sub-swarm-progress-checklist.md |
deferred | 旧 HM 内部 sub/蜂群编排进度；未完成事项随模型作废，新蜂群进度归 Swarm 仓跟踪 |
docs/heicode-manager-swarm-gap-analysis.md |
作废 | 针对废弃的「HM 主导蜂群」模型的 gap 分析，前提不再成立 |
docs/integration/agent-manager-swarm-runtime-change-request.md |
deferred → AM/Swarm | 旧 HM→AM 蜂群 runtime 变更请求；如需重提，由 Swarm 侧按新契约发起 |
docs/integration/AgentManager蜂群Runtime接口实现要求.md |
deferred → AM/Swarm | 蜂群 runtime 接口要求归 Swarm 侧实现与跟踪 |
docs/integration/AgentManager蜂群Runtime联调待确认与补充要求.md |
deferred → AM/Swarm | 联调待确认项随新契约在 Swarm 侧重列 |
docs/integration/heicode-manager-swarm-runtime-env-template.md |
作废 | 旧蜂群 runtime env 模板，对应废弃的 HM 编排路径 |
docs/integration/蜂群模式-AgentManager对接任务清单.md |
deferred → AM/Swarm | 对接任务清单随新契约在 Swarm 侧重建 |
其它旧文档（4 份，被新主线文档取代）
| 删除的文档 | 处置 | 取代者 |
|---|---|---|
Heicode-Manager-项目说明与踩坑交接.md |
作废 | 被 HM-only 化的 README.md / CLAUDE.md / AGENTS.md 取代 |
docs/Heicode-Manager-agent统一改造落地计划.md |
作废 | 被 integration/heicode-hm-template-agent-model.md 取代 |
docs/heicode-manager-standalone-execution-plan.md |
作废 | 被 plan.md 取代 |
docs/integration/agent-platform-request-contract.md |
作废 | 旧出站契约，被 integration/heicode-am-contract.md 取代 |
4. 给后续开发者的一句话
要找「蜂群在 HM 侧怎么对接」——当前答案是「HM 不实现 swarm runtime;但契约已冻结(runtime-contract v1/event-schema v1),HM 已据冻结版落地只读查询 + stop + 事件 SSE(#45/#46/PR #59),代码在 controller/agent_swarm_query.go;唯一剩余计费缺口是 per-user sk- 注入(#60),阻塞于 agent_swarm#16」;旧设计(HM 主导编排 / 仅 /tasks / HeiCode-Swarm 仓名)已废,别从 git 历史里捞旧文档当依据,按本文与 agent_swarm 仓的最新结论走。