heicode/docs/heicode-manager-sub-swarm-progress-checklist.md

Heicode Manager 蜂群模式进度清单

更新时间：2026-05-27 负责人范围：Heicode Manager 端
用途：给负责人、上级和联调同学快速确认 Manager 端在蜂群模式下已经具备什么、还要做什么、哪些需要客户端或蜂群项目配合。

资料来源

来源	用途
http://gitee.ath.cx:3000/taijibaga/fengqun/src/branch/main/docs	蜂群设计资料包，定义目标驱动蜂群、任务图、claim、heartbeat、handoff、artifact、审批、审计和三方分工
http://gitee.ath.cx:3000/taijibaga/HeiCode-Swarm	蜂群项目实现资料，当前 Orchestrator/Agent/Redis/K8s/桌面演示客户端的实际结构
docs/product-package/07-integration-boundaries.md	Heicode、Manager、Agnet 平台、CodeGW、Azure Key Vault 的边界
docs/integration/heicode-desktop-sub-agile-api.md	Heicode 桌面客户端接 Manager 的普通 sub 敏捷流程
当前仓库 heicode/ 代码	Manager 端实际实现核查

一、核心边界

蜂群模式不是普通 sub 敏捷/瀑布本身。普通 sub 是 Heicode 的任务组织方式；蜂群是 Agnet/Swarm Runtime 的执行方式。

系统	定位	应该做什么	不应该做什么
Heicode 桌面客户端	用户主体验	输入目标、持续补充需求、查看反馈、审批高危操作、接收交付结果	直接配置 AKS、模型供应商、完整蜂群 payload
Heicode Manager	控制面和记录面	资源绑定、secret_ref、权限清单、生成启动请求、记录 deployment/swarm 映射、回调、artifact、timeline、审批、审计	替代客户端做主开发对话，或替代 Runtime 执行任务
HeiCode-Swarm / Agnet Runtime	执行层	创建 Swarm Run、任务图、Agent 编队、claim、heartbeat、handoff、执行、结果回传	保存长期明文密钥，直接暴露给普通用户

二、目标调用链

Heicode 桌面客户端
  -> Heicode Manager
     - V2 加密请求 body
     - task/deployment draft
     - resource_grants / secret_ref / budget / approval_policy
  -> Agnet Runtime 或 HeiCode-Swarm
     - POST /api/swarms 或兼容创建入口
     - 返回 swarm_id / runtime_deployment_id
  <- Runtime callback
     - swarm-events / artifact.created / approval.requested / timeline.updated
  <- Manager 查询接口
     - deployment detail / events / logs / metrics / artifacts / sk-snapshots / timeline
  <- 桌面客户端展示和审批

三、当前 Manager 已完成项

以下只按当前仓库代码确认，不把规划项写成已完成。

能力	当前状态	代码证据
sub 模式字段	已支持 sub_mode，默认 agile，校验 agile/waterfall	heicode/controller/agnet_control_plane.go、heicode/model/agnet_deployment.go
用户态 deployment	已有 /api/agnet/user/deployments 创建、查询、停止、日志、事件、指标、artifact、SK snapshot、timeline	heicode/router/api-router.go
任务到 deployment draft	已有 /api/agnet/user/tasks/:task_id/deployment-draft	heicode/controller/agnet_task_bridge.go
/api/swarms 兼容入口	已有用户态 POST /api/swarms，内部走 Manager deployment 创建，并作为 adapter source 记录	heicode/router/api-router.go、AgnetCreateUserSwarm
Runtime 创建桥接	已能按配置调用 Runtime 创建接口，默认路径 /api/agnet/deployments，可用环境变量改为蜂群创建路径	heicode/controller/agnet_runtime_client.go
Runtime stop 桥接	已能在停止 Manager deployment 时调用 Runtime stop	heicode/controller/agnet_runtime_client.go
callback 接收	已有 POST /api/agnet/callbacks/swarm-events	heicode/controller/agnet_callback.go
callback 鉴权	支持 X-Agnet-Service-Token 和 HMAC 签名校验，并可从 Key Vault ref 读取签名密钥	heicode/controller/agnet_callback.go
callback 幂等	event_id / idempotency_key 去重，重复回调返回成功但不重复写	heicode/model/agnet_callback.go
artifact 落库	artifact.created 可生成 artifact 记录，支持用户态列表查询	heicode/model/agnet_artifact.go、AgnetListUserDeploymentArtifacts
approval 回调	approval.requested 可转成 Manager 审批记录	heicode/controller/agnet_callback.go
审批结果回传 Runtime	用户 approve/reject 后，Manager 可按配置 POST 回 Runtime approval decision，且不发送 secret_ref	heicode/controller/agnet_approval.go、heicode/controller/agnet_runtime_client.go
timeline 聚合	用户态 timeline 聚合 audit、callbacks、artifacts、sk_snapshots	AgnetGetUserDeploymentTimeline
SK snapshot 持久化	已有 agnet_sk_snapshots 模型和列表查询	heicode/model/agnet_sk_snapshot.go
本地模拟事件	已有用户态 simulate-events；默认模拟会写入 callback、artifact、approval、timeline 记录，用于 Manager 自测展示链路和脱敏检查	AgnetSimulateUserDeploymentEvents
V2 body 加密	/api/agnet/user/* 和 /api/heicode-auth/* 已支持桌面端 V2 加密 body	heicode/middleware/auth.go
生产普通 sub 烟测	已验证 production create/detail/metrics/events/logs/artifacts/sk-snapshots/timeline/stop 链路	docs/integration/heicode-desktop-sub-agile-api.md

四、Manager 端还需要继续做的蜂群任务

优先级	任务	当前缺口	是否 Manager 可独立做	验收标准
P0	把 /api/swarms adapter 文档化并固定字段	已完成：docs/integration/蜂群模式-AgentManager对接任务清单.md 和 docs/integration/普通sub敏捷模式-AgentManager对接任务清单.md 已写清 Runtime create、callback、source、deployment_id <-> swarm_id 映射	是	文档可直接发给 Agent Manager / 蜂群侧核对
P0	增加 Swarm Run 显示字段	已完成：用户态 deployment 详情展示 runtime_deployment_id、runtime_swarm_id、runtime_state，并在相关记录里展示 source	是	用户态 deployment 详情和后台页面能看到 Runtime 映射
P0	回调事件类型收敛	已完成：GET /api/agnet/callbacks/swarm-events/schema 输出事件类型、分类和必填字段；callback 接收端按 schema 校验关键 task/handoff/artifact/approval 字段	是	task.created/claimed/running/completed/failed/handoff/approval/artifact 都有 schema
P0	Runtime 联调配置模板	已完成：两份 Agent Manager 对接任务清单已写清 AGNET_RUNTIME_*、callback URL、service token/HMAC 方式和验收步骤	是	蜂群项目按模板能调用 Manager callback
P1	审批结果回传 Runtime 联调	Manager adapter 已有；仍需要 Runtime 提供接收接口并验证状态继续/停止	需要 Runtime 接口	审批通过/拒绝后 Runtime 状态能继续或停止
P1	Artifact 展示优化	Manager 端已完成：页面展示 artifact 类型、摘要和 URI；真实 code_patch/document/test_report/deployment_manifest 仍需 Runtime 输出	需要 Runtime 数据	artifact 页面/详情能按类型展示摘要和链接
P1	任务图/Agent 状态展示占位	已完成：页面从 task.* / handoff.* callback 聚合 Agent task map；无真实数据时显示 Runtime callback 空态	Manager 可先做展示结构，真实数据需 Runtime	有空态和字段，不宣称真实已运行
P1	日志/指标真实来源标识	已完成：logs/metrics API 返回 data_source、runtime_source，当前明确是 Manager control-plane / estimated，不伪装 Runtime 真实指标	需要 Runtime 数据	页面和 API 响应能区分来源
P1	高危审批客户端联动文档	已完成：docs/integration/heicode-desktop-sub-agile-api.md 已包含 approval 查询、approve/reject、awaiting_approval 流程	是	客户端文档补齐 approval flow
P2	蜂群模式验收脚本	已完成：scripts/agnet_sub_mode_smoke.py 支持 schema 检查、生产健康检查、可选 simulate-events、可选真实 callback smoke	是	本地/生产能跑出 callback、artifact、approval、timeline 可见

五、需要蜂群项目配合的事项

事项	为什么 Manager 不能单独完成	蜂群侧需要提供
真实 Swarm Run	Manager 只能发起请求和记录，不能替 Runtime 创建任务图	生产 POST /api/swarms 或确认使用现有 /tasks 兼容方式
真实 task graph	任务拆解、依赖、状态机在 Runtime 内部产生	swarm_tasks、依赖关系、状态枚举
claim / heartbeat / release	这是 worker runtime 行为	事件回调或查询接口
handoff / retry / blocked	任务交接和失败恢复属于 Runtime	标准事件、重试次数、失败原因、下一步动作
Agent 执行结果	Manager 不能生成真实代码产物	artifact schema、Git branch/commit、测试报告、部署结果
Runtime 指标	CPU、内存、耗时、Agent 存活、任务耗时来自集群	metrics 查询或 Prometheus 指标映射
审批等待状态机	Runtime 要能暂停高危动作并等待 Manager/客户端审批	approval request 和 approval decision API

六、需要桌面客户端配合的事项

事项	Manager 已有基础	客户端需要做
V2 加密请求	Manager 已支持	sub/蜂群相关 POST 请求复用模型调用加密
任务创建和追问	Manager 有 /api/heicode-auth/* 代理	带 Heicode access token 调用任务接口
deployment draft	Manager 有用户态接口	从任务卡调用 draft，再创建 deployment/swarm
进度展示	Manager 有 detail/events/timeline/artifacts 接口	做用户主体验展示，不暴露底层 payload
高危审批	Manager 有 approval API 和回调转审批记录	弹窗展示风险、资源、TTL，并提交 approve/reject

七、当前不应误报为完成的项

项	当前真实状态
蜂群生产闭环	未完成。Manager 有控制面和回调骨架，但真实 Runtime 任务图/Agent 执行仍需蜂群项目联调
HeiCode-Swarm 项目等于正式 Heicode 桌面客户端	不是。它有自己的 desktop-client 演示端，正式链路应走 Heicode 桌面客户端 -> Manager -> Runtime
/api/swarms 已等于真实 Runtime Swarm Run	不是。Manager 侧已有 adapter 入口，但是否真实创建 Swarm Run 取决于 Runtime 配置和蜂群接口
artifact/timeline 有接口就等于有真实产物	不是。Manager 能接和展示，真实产物必须由 Runtime 回调
高危审批在 Manager 里点完就闭环	不是。产品要求桌面客户端主审批，并且 Runtime 要收到 decision

八、后续执行顺序

顺序	任务	负责人范围	备注
1	固定 Manager -> Swarm adapter 契约	Manager	先把 /api/swarms、Runtime create path、callback 字段写死成可联调文档
2	跑一次本地模拟 Runtime callback	Manager	已有默认模拟链路；继续用于验证 callback/artifact/timeline/approval 去重和脱敏
3	给蜂群项目配置 callback URL 和 service token	Manager + 蜂群	不传明文长期密钥
4	用 HeiCode-Swarm 当前 Orchestrator 做兼容测试	Manager + 蜂群	先判断是否走 /tasks 适配，还是蜂群侧补 /api/swarms
5	桌面客户端按文档跑任务 -> draft -> create -> timeline -> approval	客户端 + Manager	使用 V2 加密 POST
6	补页面来源标识和任务图空态	Manager	防止把 simulated/control-plane 误认为 runtime