From 09331752f217e4f09cac7752a9f1b5c884dc6e81 Mon Sep 17 00:00:00 2001 From: chenchen Date: Mon, 8 Jun 2026 15:19:17 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20address=20review=20=E2=80=94=20add=20sw?= =?UTF-8?q?arm-deferred=20tracking=20entry=20+=20migration=20mapping?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per Fasthei's CHANGES_REQUESTED on #15: deleting all sub/swarm docs left no tracking entry for the still-in-development swarm capability. Adds docs/integration/heicode-swarm-deferred.md stating HM does not implement swarm runtime, the old HM-orchestrated sub/swarm model is deprecated, new swarm work lives on AM/Swarm side, and a per-file migration mapping (deprecated / deferred / superseded) for all 11 deleted docs. Links it from docs/README.md so deletion no longer drops context. Co-Authored-By: Claude Opus 4.8 --- docs/README.md | 3 +- docs/integration/heicode-swarm-deferred.md | 56 ++++++++++++++++++++++ 2 files changed, 58 insertions(+), 1 deletion(-) create mode 100644 docs/integration/heicode-swarm-deferred.md diff --git a/docs/README.md b/docs/README.md index 13bd16a..bb2a31f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -11,8 +11,9 @@ | [`integration/heicode-hm-legacy-teardown.md`](./integration/heicode-hm-legacy-teardown.md) | 旧 sub 任务编排模型的代码/表/前端删除清单 | | [`integration/heicode-desktop-client-api.md`](./integration/heicode-desktop-client-api.md) | 桌面客户端对接 HM（模板 Agent 模型），已生产验证 | | [`integration/heicode-am-contract.md`](./integration/heicode-am-contract.md) | HM ↔ AM（agent_management）接口契约 | +| [`integration/heicode-swarm-deferred.md`](./integration/heicode-swarm-deferred.md) | **蜂群（Swarm）现状裁定与后续跟踪入口**：HM 当前不实现 swarm runtime，旧 sub/蜂群文档作废后的上下文迁移映射与归属（AM/Swarm 侧） | | [`deployment/azure-production-deploy-guardrails.md`](./deployment/azure-production-deploy-guardrails.md) | Azure VM / PostgreSQL / Redis / Agent / NewAPI 生产部署前的安全守卫、环境变量注入和验证计划 | -旧 Agent API 草案、旧 sub / 蜂群任务编排、旧里程碑、旧架构说明和旧上手材料不再作为实施依据（相关文档已删除）。当前实施模型以 `heicode.md`、`plan.md` 与 `integration/heicode-hm-template-agent-model.md` 为准；生产部署操作以安全守卫文档约束，且不得覆盖产品/架构主线。 +旧 Agent API 草案、旧 sub / 蜂群任务编排、旧里程碑、旧架构说明和旧上手材料不再作为实施依据（相关文档已删除）。**蜂群相关文档的作废/迁移映射与「HM 不实现 swarm runtime、新能力归 AM/Swarm 侧跟踪」的结论见 [`integration/heicode-swarm-deferred.md`](./integration/heicode-swarm-deferred.md)（删除≠丢上下文，迁移到此追踪入口）。** 当前实施模型以 `heicode.md`、`plan.md` 与 `integration/heicode-hm-template-agent-model.md` 为准；生产部署操作以安全守卫文档约束，且不得覆盖产品/架构主线。 代码中的过渡期命名、旧接口注释或旧 UI 文案只作为现状参考；若与 `heicode.md` / `plan.md` 冲突，应先更新实现或另行补充当前主线文档，不得恢复旧 Agent/M1-M5 草案作为依据。 diff --git a/docs/integration/heicode-swarm-deferred.md b/docs/integration/heicode-swarm-deferred.md new file mode 100644 index 0000000..40ff24a --- /dev/null +++ b/docs/integration/heicode-swarm-deferred.md @@ -0,0 +1,56 @@ +# Heicode 蜂群（Swarm）—— 现状裁定与后续跟踪入口（HM 侧） + +> 起草：2026-06-05 · 状态：跟踪占位（HM 侧不实现，归口 AM / Swarm） +> +> 本文是 PR #15「文档大同步」删除全部旧 sub/蜂群文档后留下的**追踪入口**，回答三件事：① 旧文档为什么作废、② 蜂群能力现在归谁、③ 未来对接/待定项在哪里跟踪。删除旧文档≠放弃蜂群能力，**上下文迁移到本文**。 + +--- + +## 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-legacy-teardown.md)，当前模型见 [`heicode-hm-template-agent-model.md`](./heicode-hm-template-agent-model.md)。 +- **新版蜂群能力仍在开发中，但在 AM / Swarm 侧，不在本仓。** 旧文档描述的是「HM 主导编排蜂群」的废弃设计；新蜂群若落地，HM 侧最多提供资源/计费/鉴权支撑面，runtime 与编排由 Swarm 承载。 + +--- + +## 2. 能力归属与后续跟踪入口 + +| 项 | 归属仓 / 负责人 | 说明 | +|---|---|---| +| 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`） | +| Agent 运行时（单 agent，已落地） | **`agent_management`（AM）**（@azgy） | 模板 Agent 启动/状态/停止/删除，契约见 [`heicode-am-contract.md`](./heicode-am-contract.md) | + +> **HM 侧后续若要支撑蜂群**：不恢复旧文档，按当时 Swarm 的正式契约在 `docs/integration/` 新立文档；本文作为「蜂群在 HM 侧当前为 deferred」的唯一锚点。 + +--- + +## 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 侧正式契约」**；旧设计已废，别从 git 历史里捞旧文档当依据，按本文与 Swarm 仓的最新结论走。