From 699fa5ef441dd803d30c951460c89d2e1beaf6c9 Mon Sep 17 00:00:00 2001 From: chenchen Date: Wed, 10 Jun 2026 12:15:57 +0800 Subject: [PATCH] docs(swarm): refresh HM-side swarm docs to current agent_swarm state MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit HM 端文档里的蜂群描述还是旧的(错仓名 + 旧模型),据实更新为当前 agent_swarm: - 仓名:`HeiCode-Swarm` → `agent_swarm`(GitHub xmindlab-heicode/agent_swarm;产品名 HeiCode Swarm)。 - 模型:旧「HM 主导编排 / 仅 /tasks」→ 当前 Master-Agent 编排(分解→派发专家并行→协作/移交→评审/重做→汇总;Orchestrator FastAPI + Redis + WebSocket + Prometheus)。 - 契约:agent_swarm 已起草正式契约 docs/integration/runtime-contract.md(对齐 heicode-am-contract),待 Manager Runtime Team 评审冻结;已实现 create/status/tasks/logs/events/metrics/workflow/diagnostics/stop/approvals(带 deployment_id)。 - issue 引用:`agent_swarm#1`(执行面缺口,已关闭)→ 活动 EPIC `agent_swarm#2`(主链路接入契约冻结);HM 侧前置 #45/#46。 文件: - docs/integration/heicode-swarm-deferred.md:勘误抬头 + §1 模型/接入状态 + §2 归属表(仓名/契约/接口) + §4 收尾据实更新。 - heicode/docker-compose.azure-vm.yml:SWARM_RUNTIME_* 注释更正(agent_swarm,deferred,当前关闭)。 - Heicode-Manager-生产配置与账号交接清单.md §7 + Orchestrator 地址标签:加勘误 banner,保留 env 历史记录但标注为旧模型/当前关闭。 - docs/deployment/Heicode-Manager-更换部署服务配置清单.md §2.2:加勘误 banner。 HM 不实现 swarm runtime 的裁定不变;仅把"蜂群现状"事实对齐。未改 env 变量名/行为(SWARM_RUNTIME_* 仍 disabled),未动 legacy-teardown 历史记录。Docs/注释 only。 Affects: 文档/注释 only。无代码、无计费/审计/部署行为改动。 Co-Authored-By: Claude Opus 4.8 --- Heicode-Manager-生产配置与账号交接清单.md | 4 +++- .../Heicode-Manager-更换部署服务配置清单.md | 2 ++ docs/integration/heicode-swarm-deferred.md | 15 +++++++++------ heicode/docker-compose.azure-vm.yml | 5 ++++- 4 files changed, 18 insertions(+), 8 deletions(-) diff --git a/Heicode-Manager-生产配置与账号交接清单.md b/Heicode-Manager-生产配置与账号交接清单.md index 214605fa..1a5a0fe2 100644 --- a/Heicode-Manager-生产配置与账号交接清单.md +++ b/Heicode-Manager-生产配置与账号交接清单.md @@ -180,6 +180,8 @@ Key Vault 最低权限： ## 7. 蜂群 Runtime 配置 +> ⚠️ **2026-06-10 勘误（模型已更新）**：本节描述的「普通 sub + 蜂群两套模式 + `SWARM_RUNTIME_*` + `/api/swarms`」是**旧的「HM 主导编排」模型，已作废**。当前权威模型：HM **不实现 swarm runtime**；单 Agent 走「模板 Agent + AM」（见 `docs/integration/heicode-am-contract.md`），多 Agent 蜂群归 **`agent_swarm`**（产品名 HeiCode Swarm）仓，其编排为 Master-Agent（分解→派发→评审→汇总），契约见 `agent_swarm/docs/integration/runtime-contract.md`（待冻结，`agent_swarm#2`）。详见 `docs/integration/heicode-swarm-deferred.md`。下表 `SWARM_RUNTIME_*` 仅为**仍存在于 env 但当前关闭（`SWARM_RUNTIME_ENABLED=false`）**的历史开关，保留作记录，不代表当前接入形态。 + 蜂群模式和普通 sub 模式是两套部署、两套语义。Manager 当前环境里蜂群 Runtime 开关是关闭状态。 | 环境变量 | 当前状态 | 当前值 / 位置 | 说明 | @@ -196,7 +198,7 @@ Key Vault 最低权限： | 项目 | 地址 | 说明 | |------|------|------| -| HeiCode-Swarm Orchestrator | `http://52.139.240.116:8000` | 蜂群项目独立 Runtime / Orchestrator | +| `agent_swarm`（HeiCode Swarm）Orchestrator | `http://52.139.240.116:8000` | 蜂群项目独立 Runtime / Orchestrator（HM 侧 deferred，未在 Manager 生产 env 启用） | ## 8. NewAPI / 模型网关配置 diff --git a/docs/deployment/Heicode-Manager-更换部署服务配置清单.md b/docs/deployment/Heicode-Manager-更换部署服务配置清单.md index 5299c81d..6bbc087c 100644 --- a/docs/deployment/Heicode-Manager-更换部署服务配置清单.md +++ b/docs/deployment/Heicode-Manager-更换部署服务配置清单.md @@ -42,6 +42,8 @@ HEICODE_PUBLIC_BASE_URL=https://code.xinghanlab.com ### 2.2 Agent Manager / 普通 sub / 蜂群联调配置 +> ⚠️ **2026-06-10 勘误**：下列「普通 sub / 蜂群 + `/api/swarms` + `SWARM_RUNTIME_*`」属**旧「HM 主导编排」模型，已作废**。当前权威模型：单 Agent 走「模板 Agent + AM」（`heicode-am-contract.md`）；多 Agent 蜂群归 **`agent_swarm`**（HeiCode Swarm）仓（Master-Agent 编排），HM 侧 deferred，契约待 `agent_swarm#2` 冻结。见 `docs/integration/heicode-swarm-deferred.md`。本节 env 仅为历史记录（蜂群开关当前 `SWARM_RUNTIME_ENABLED=false`）。 + ```env AGENT_RUNTIME_ENABLED=true AGENT_RUNTIME_BASE_URL=http://20.212.121.126 diff --git a/docs/integration/heicode-swarm-deferred.md b/docs/integration/heicode-swarm-deferred.md index 40ff24ad..299a71ed 100644 --- a/docs/integration/heicode-swarm-deferred.md +++ b/docs/integration/heicode-swarm-deferred.md @@ -1,8 +1,10 @@ # Heicode 蜂群（Swarm）—— 现状裁定与后续跟踪入口（HM 侧） -> 起草：2026-06-05 · 状态：跟踪占位（HM 侧不实现，归口 AM / Swarm） +> 起草：2026-06-05 · 更新：2026-06-10（同步 `agent_swarm` 当前状态）· 状态：跟踪占位（HM 侧不实现，归口 AM / Swarm） > > 本文是 PR #15「文档大同步」删除全部旧 sub/蜂群文档后留下的**追踪入口**，回答三件事：① 旧文档为什么作废、② 蜂群能力现在归谁、③ 未来对接/待定项在哪里跟踪。删除旧文档≠放弃蜂群能力，**上下文迁移到本文**。 +> +> **2026-06-10 勘误**：蜂群仓库名是 **`agent_swarm`**（GitHub `xmindlab-heicode/agent_swarm`；产品名 **HeiCode Swarm**），不是 `HeiCode-Swarm`。该仓已从「仅 `/tasks`」演进为完整的 Master-Agent 编排运行时并起草了正式契约 `runtime-contract.md`——本文下文已据实更新。 --- @@ -10,7 +12,8 @@ - **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-legacy-teardown.md)，当前模型见 [`heicode-hm-template-agent-model.md`](./heicode-hm-template-agent-model.md)。 -- **新版蜂群能力仍在开发中，但在 AM / Swarm 侧，不在本仓。** 旧文档描述的是「HM 主导编排蜂群」的废弃设计；新蜂群若落地，HM 侧最多提供资源/计费/鉴权支撑面，runtime 与编排由 Swarm 承载。 +- **新版蜂群能力在 `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 承载。 +- **该仓尚未作为 Heicode 主链路正式 Runtime Backend 接入。** 按 `agent_swarm` README 与 `agent_swarm#2`：编排器已可运行（仓内），但 Manager↔Runtime 生命周期契约、HMAC 签名回调 envelope、稳定 `deployment_id`/`workflow_id`/`trace_id`、统一 usage/审计接入等仍为 🟡 待接入，需各 Team 评审冻结后联调。 --- @@ -18,11 +21,11 @@ | 项 | 归属仓 / 负责人 | 说明 | |---|---|---| -| Swarm runtime / 多 agent 编排 | **`agent_swarm` / `HeiCode-Swarm`**（@Songhaoz666） | 执行面、回调、Swarm Runtime | -| Manager ↔ Swarm 契约（若未来需要） | 待 Swarm 侧给出正式 `/api/agent/swarm/*` 接口后，在本目录 `docs/integration/` 另立契约文档跟踪 | 当前 Swarm 仅暴露 `/tasks`、缺 `deployment_id ↔ swarm_id` 映射（见 `agent_swarm#1`） | +| Swarm runtime / 多 agent 编排 | **`agent_swarm`**（产品名 HeiCode Swarm，@Songhaoz666） | 执行面、Master-Agent 编排、回调、Swarm Runtime | +| Manager ↔ Swarm 契约 | Swarm 侧**已起草正式契约** `agent_swarm/docs/integration/runtime-contract.md`（沿用 `heicode-am-contract` 的鉴权/回调/env/路径覆盖约定），**待 Manager Runtime Team 评审冻结**；冻结后在本目录 `docs/integration/` 另立 HM 侧对接契约 | Swarm 已实现生命周期接口 create/status/tasks/logs/events/metrics/workflow/diagnostics/stop/approvals（均带 `deployment_id`，三组路径别名 `/api/swarms`、`/api/agent/swarm/deployments`、`/api/agnet/deployments`）；契约冻结与主链路接入跟踪在 **`agent_swarm#2`**（`#1` 执行面缺口已关闭） | | Agent 运行时（单 agent，已落地） | **`agent_management`（AM）**（@azgy） | 模板 Agent 启动/状态/停止/删除，契约见 [`heicode-am-contract.md`](./heicode-am-contract.md) | -> **HM 侧后续若要支撑蜂群**：不恢复旧文档，按当时 Swarm 的正式契约在 `docs/integration/` 新立文档；本文作为「蜂群在 HM 侧当前为 deferred」的唯一锚点。 +> **HM 侧后续若要支撑蜂群**：不恢复旧文档，按 Swarm 的 `runtime-contract.md` 冻结版在 `docs/integration/` 新立 HM 对接契约；本文作为「蜂群在 HM 侧当前为 deferred」的唯一锚点。HM 侧对接前置依赖见 issue #45（Phase1 只读查询，阻塞于 `agent_swarm#2` 契约冻结）/ #46（Phase2 SSE）。 --- @@ -53,4 +56,4 @@ ## 4. 给后续开发者的一句话 -要找「蜂群在 HM 侧怎么对接」——**当前答案是「HM 不实现，等 Swarm 侧正式契约」**；旧设计已废，别从 git 历史里捞旧文档当依据，按本文与 Swarm 仓的最新结论走。 +要找「蜂群在 HM 侧怎么对接」——**当前答案是「HM 不实现 swarm runtime；Swarm 侧已起草 `agent_swarm/docs/integration/runtime-contract.md`，待 Manager Runtime Team 评审冻结（`agent_swarm#2`）后，HM 再据冻结版做只读查询接入（#45/#46）」**；旧设计（HM 主导编排 / 仅 `/tasks` / `HeiCode-Swarm` 仓名）已废，别从 git 历史里捞旧文档当依据，按本文与 `agent_swarm` 仓的最新结论走。 diff --git a/heicode/docker-compose.azure-vm.yml b/heicode/docker-compose.azure-vm.yml index b87bc57c..ddf8c3dc 100644 --- a/heicode/docker-compose.azure-vm.yml +++ b/heicode/docker-compose.azure-vm.yml @@ -61,7 +61,10 @@ services: - AGENT_RUNTIME_STOP_PATH=${AGENT_RUNTIME_STOP_PATH:-/api/agent/deployments/{deployment_id}/stop} - AGENT_RUNTIME_SERVICE_TOKEN=${AGENT_RUNTIME_SERVICE_TOKEN:-} - AGENT_RUNTIME_CALLBACK_SIGNING_SECRET_REF=${AGENT_RUNTIME_CALLBACK_SIGNING_SECRET_REF:-} - # HeiCode-Swarm Runtime is separate from ordinary sub Agent Runtime. + # agent_swarm (product: HeiCode Swarm) Runtime — separate from the single + # template-agent Runtime (AM). Currently DEFERRED/disabled (SWARM_RUNTIME_ENABLED=false): + # HM does not orchestrate swarm; pending agent_swarm runtime-contract.md freeze (agent_swarm#2). + # See docs/integration/heicode-swarm-deferred.md. - SWARM_RUNTIME_ENABLED=${SWARM_RUNTIME_ENABLED:-false} - SWARM_RUNTIME_BASE_URL=${SWARM_RUNTIME_BASE_URL:-} - SWARM_RUNTIME_CREATE_PATH=${SWARM_RUNTIME_CREATE_PATH:-/api/swarms}