heicode/docs/heicode-manager-swarm-gap-analysis.md

Heicode Manager 蜂群模式缺失对照文档

更新时间：2026-05-27 对照范围：fengqun 设计资料、HeiCode-Swarm 项目现状、Heicode 产品资料包、当前 Heicode Manager 代码。

一、对照结论

Manager 端已经具备蜂群联调需要的控制面基础：用户态 deployment、task draft、/api/swarms adapter、Runtime 创建/停止桥接、callback 接收、artifact、approval、approval decision 回传 adapter、timeline、SK snapshot、V2 加密请求。本地 simulate-events 默认链路也能写入 task、blocked、retry、handoff、artifact、approval、timeline 记录，便于 Manager 自测页面展示和脱敏。

仍然缺的是“真实蜂群 Runtime 产生的数据和状态机”。也就是说，Manager 不是完全没写；缺口主要集中在 Runtime 真正创建 Swarm Run、任务图、Agent 执行、handoff、产物和审批继续/停止闭环。

二、按文档要求逐项对照

文档要求	当前 Manager 状态	是否满足	缺失原因	需要谁
Heicode 客户端是主体验	Manager 文档和接口已按客户端调用设计，V2 加密 POST 已支持	部分满足	桌面客户端还需按文档接任务、展示进度和审批	客户端
Manager 是受控入口，不暴露完整 payload 给普通用户	用户态 draft/create 已有，可由任务卡生成 plan	部分满足	页面还需要更弱化底层 payload，突出启动摘要和状态	Manager
Manager 调用 POST /api/swarms 创建 Swarm Run	Manager 已有 /api/swarms adapter，Runtime create path 可配置	部分满足	是否真实创建 Swarm Run 取决于蜂群 Runtime 是否提供生产接口	蜂群 + Manager
保存 swarm_id、状态、请求摘要、correlation_id	模型已有 runtime_swarm_id、runtime_state、payload JSON、correlation metadata	基本满足	真实 swarm_id 需要 Runtime 返回	蜂群
接收 swarm-events 回调	已有 POST /api/agnet/callbacks/swarm-events	满足接收能力	还缺真实 Runtime 持续回调	蜂群
重复回调幂等	已按 event_id / idempotency_key 去重	满足	需要蜂群侧稳定传唯一事件 ID	蜂群
接收 artifact 回调	artifact.created 可落库并查询	满足接收能力	真实 artifact schema 和文件/分支引用需 Runtime 输出	蜂群
展示 Swarm 状态、事件、产物	deployment detail/events/artifacts/timeline 已有，页面已强化 runtime/simulated 来源和 artifact 类型/URI	基本满足	真实展示内容仍依赖 Runtime 回调真实数据	蜂群
展示 task graph、claim、heartbeat	Manager 已可接收并展示普通 task flow callback；没有独立 task graph 状态表	部分满足	真实任务图仍需要 Runtime 产出 task/agent 事件	蜂群
展示 handoff、blocked、retry	已补 task.* / handoff.* schema 校验和页面任务流展示	基本满足接收和展示	真实数据仍需要 Runtime 持续回调	蜂群
高危审批请求进入 Manager	approval.requested callback 可转审批记录；用户 approve/reject 后可按配置 POST 回 Runtime	部分满足	还需要蜂群 Runtime 提供并验证 approval decision 接收接口	Manager + 蜂群
高危审批在客户端主体验完成	Manager 有审批 API	部分满足	桌面客户端要弹窗、轮询/订阅、提交决定	客户端
短期凭证和长期密钥隔离	Manager 使用 secret_ref / lease:// 记录，不传明文	基本满足	Runtime 侧短期凭证派生/注入未验证	蜂群 + 基础设施
CodeGW 用量归属	Manager 有模型/余额基础，Runtime payload 带 billing_context	部分满足	子 Agent 调用用量按 task/deployment/role 回流未验证	蜂群 + CodeGW + Manager
日志和指标	Manager 有 logs/metrics 接口占位和 runtime state	部分满足	CPU/内存/Agent 存活/任务耗时等真实指标来自 Runtime/AKS	蜂群 + 基础设施
最终交付回流	artifact/timeline 接收能力已有	部分满足	最终交付结果、Git branch/commit、部署 URL 需要 Runtime 输出，客户端展示	蜂群 + 客户端

三、HeiCode-Swarm 项目现状对 Manager 的影响

从 HeiCode-Swarm 项目 README 和代码看，当前项目结构是：

desktop-client -> Orchestrator(FastAPI) -> Redis -> Agent Pods

当前 Orchestrator 主要入口：

入口	当前作用	与 Manager 目标契约差异
GET /health	健康检查	可直接用于 Runtime health
POST /tasks	创建任务	不是文档要求的 POST /api/swarms，字段也不是 Heicode task/resource/secret/budget 结构
GET /tasks / GET /tasks/{id}	查询任务	可作为早期状态查询，但缺 swarm_id 维度
GET /agents	Agent 列表	可映射到 Agent 状态
GET /handoffs	handoff 历史	可映射到 Manager timeline
GET /metrics	Prometheus 指标	可映射到 Manager metrics
WS /ws/{agent_id}	Agent 注册、心跳、任务、结果	Manager 不应直接接 Agent WS，应该由 Runtime 汇总后回调 Manager

因此，Manager 后续联调有两种路线：

路线	说明	风险
蜂群侧补正式 POST /api/swarms	最符合设计文档，Manager adapter 直接对接	需要蜂群项目改接口
Manager 临时适配 POST /tasks	可以先跑通现有 Orchestrator	字段语义不足，无法完整覆盖 resource_grants、secret_ref、approval_policy、budget、artifact callback

建议：生产目标仍以 POST /api/swarms 为准；短期可以做 /tasks 兼容测试，但必须标记为兼容桥接，不作为最终契约。

四、缺失项清单

P0：影响蜂群主流程

缺失项	当前状态	处理建议
真实 POST /api/swarms 联调	Manager 有 adapter，蜂群当前可见接口是 /tasks	蜂群侧确认是否补 /api/swarms；Manager 固定 adapter 文档
deployment_id <-> swarm_id 真实映射	Manager 字段已准备，真实值需 Runtime 返回	Runtime create response 必须返回 swarm_id
task graph / claim / heartbeat 事件	Manager 可接收/展示 task flow callback；缺真实 Runtime 数据	蜂群侧定义并回调 task.created/claimed/heartbeat/released/completed/failed
artifact 真实产出	Manager 能落库，缺 Runtime 产出	蜂群侧回调 artifact.created，带 Git branch/commit 或存储 URI
审批结果回传 Runtime	Manager adapter 已完成，真实闭环未验证	蜂群侧提供接收接口并验证 approved/rejected 后继续或停止

P1：影响可观测和验收

缺失项	当前状态	处理建议
handoff/retry/blocked 展示	Manager 已有 schema 校验、模拟事件和页面任务流展示	用真实 Runtime callback 做生产联调验证
Runtime 日志/指标	Manager 有 logs/metrics 位置，缺真实数据源	蜂群侧提供日志摘要或查询接口；指标对齐 Prometheus
事件来源标识	API 有部分 runtime/simulated 状态，页面还需强化	Manager 页面区分 manager、runtime、simulated
桌面客户端审批主流程	Manager 有 API，客户端未完成主体验	客户端按 Manager approval API 接入
子 Agent 用量归属	billing_context 有，真实用量未回流	Runtime 调模型时带 task/deployment/role correlation

P2：完善项

缺失项	当前状态	处理建议
蜂群验收脚本	已新增 scripts/agnet_sub_mode_smoke.py，可检查生产 Manager、Agent health 和指定 deployment timeline	后续按真实 Runtime deployment 固化执行参数
页面术语统一	sub/蜂群容易混淆	页面和文档统一：sub 是任务组织，swarm 是执行层
兼容 HeiCode-Swarm demo client 的说明	容易误认为正式 Heicode 桌面客户端	文档明确 demo client 不等于 cc-haha 正式客户端

五、验收口径

蜂群模式不能只看 Manager 页面有没有数据。必须同时满足：

1. 桌面客户端能通过 Manager 发起任务，POST 请求体走 V2 加密。
2. Manager 创建或桥接 Swarm Run，并保存 deployment_id、runtime_deployment_id、swarm_id。
3. Runtime 真实生成任务图，并回传任务状态、Agent 状态、handoff、artifact、审批请求。
4. Manager 对 callback 去重、落库、脱敏，并能按 deployment/timeline/artifact 查询。
5. 高危审批由客户端展示并提交，Manager 记录，Runtime 收到决定后继续或停止。
6. 交付物能回到 Manager 和客户端，不能只停留在 Runtime Redis 或 Agent 日志里。
7. 全链路日志和页面不得出现长期明文密钥、模型 key、云 access key、私钥或连接串。

六、下一步建议

顺序	动作	目标
1	把 docs/heicode-manager-sub-swarm-progress-checklist.md 发给蜂群侧确认	让对方知道 Manager 已有什么、需要他们回什么
2	确认蜂群侧最终入口是 /api/swarms 还是先兼容 /tasks	避免双方接口错位
3	用 Manager callback 接口跑一次蜂群侧真实 artifact.created / approval.requested	证明回调、artifact、approval、timeline 有真实数据
4	客户端按 docs/integration/heicode-desktop-sub-agile-api.md 接入审批和 timeline	跑通用户主体验
5	根据真实联调结果更新本文状态	把缺失项从“缺接口/未联调”改为“已验证/阻塞/延期”