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

Heicode Manager 普通 sub 与蜂群模式进度清单

更新时间：2026-05-30 负责人范围：Heicode Manager 端
用途：给负责人、上级和联调同学快速确认 Manager 端在普通 sub 与蜂群模式下已经具备什么、还要做什么、哪些需要客户端或 Agent 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、Agent 平台、CodeGW、Azure Key Vault 的边界
docs/integration/heicode-desktop-sub-agile-api.md	Heicode 桌面客户端接 Manager 的普通 sub 敏捷流程
docs/integration/Heicode-Manager-PayPal支付接入与计费关系说明.md	PayPal 收款、Heicode 余额/订阅、NewAPI 模型扣费和 Agent 运行费用边界
当前仓库 heicode/ 代码	Manager 端实际实现核查

一、核心边界

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

模式	Manager 当前职责	Runtime / Agent Manager 当前职责	不能混淆的点
普通 sub 敏捷/瀑布	从任务卡生成 deployment、保存 sub_mode、权限清单、预算、callback、timeline、artifact、审批记录和运行时诊断	执行普通 sub 任务，回传阶段、日志、工具调用、artifact、usage、失败原因	普通 sub 不等于蜂群 task graph；/api/swarms 可作为 Runtime 兼容入口，但页面和文档必须按普通 sub 展示
蜂群模式	生成 swarm adapter 请求、保存 deployment_id <-> swarm_id 映射、接回调、审批、审计、artifact 展示和运行时诊断	创建 Swarm Run、任务图、claim、heartbeat、handoff、Agent 编队、真实执行与结果回传	蜂群是执行形态；不能把普通 sub 的阶段状态误写成蜂群已完成

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

二、目标调用链

Heicode 桌面客户端
  -> Heicode Manager
     - V2 加密请求 body
     - task/deployment draft
     - resource_grants / secret_ref / budget / approval_policy
  -> Agent 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/agent_control_plane.go、heicode/model/agent_deployment.go
用户态 deployment	已有 /api/agent/user/deployments 创建、查询、停止、日志、事件、指标、artifact、SK snapshot、timeline	heicode/router/api-router.go
任务到 deployment draft	已有 /api/agent/user/tasks/:task_id/deployment-draft	heicode/controller/agent_task_bridge.go
/api/swarms 兼容入口	已有用户态 POST /api/swarms，内部走 Manager deployment 创建，并作为 adapter source 记录	heicode/router/api-router.go、AgentCreateUserSwarm
Runtime 创建桥接	已能按配置调用 Runtime 创建接口，默认路径 /api/agent/deployments，可用环境变量改为蜂群创建路径	heicode/controller/agent_runtime_client.go
Runtime stop 桥接	已能在停止 Manager deployment 时调用 Runtime stop	heicode/controller/agent_runtime_client.go
Runtime 状态诊断	已新增用户态只读诊断接口，按 runtime_mode 区分普通 sub / 蜂群，查询 Runtime status 并识别 failed agent、兜底摘要 artifact、零 token 用量等异常	heicode/controller/agent_runtime_client.go、AgentGetUserDeploymentRuntimeDiagnostics
callback 接收	已有 POST /api/agent/callbacks/swarm-events	heicode/controller/agent_callback.go
callback 鉴权	支持 X-Agent-Service-Token 和 HMAC 签名校验，并可从 Key Vault ref 读取签名密钥	heicode/controller/agent_callback.go
callback 幂等	event_id / idempotency_key 去重，重复回调返回成功但不重复写	heicode/model/agent_callback.go
artifact 落库	artifact.created 可生成 artifact 记录，支持用户态列表查询	heicode/model/agent_artifact.go、AgentListUserDeploymentArtifacts
artifact 完整内容代理	已新增用户态 content 下载接口，Manager 校验 deployment/artifact 权限后代理 Runtime content 接口读取完整产物	AgentGetUserDeploymentArtifactContent、callAgentRuntimeArtifactContent
approval 回调	approval.requested 可转成 Manager 审批记录	heicode/controller/agent_callback.go
审批结果回传 Runtime	用户 approve/reject 后，Manager 可按配置 POST 回 Runtime approval decision，且不发送 secret_ref	heicode/controller/agent_approval.go、heicode/controller/agent_runtime_client.go
timeline 聚合	用户态 timeline 聚合 audit、callbacks、artifacts、sk_snapshots	AgentGetUserDeploymentTimeline
SK snapshot 持久化	已有 agent_sk_snapshots 模型和列表查询	heicode/model/agent_sk_snapshot.go
本地模拟事件	已有用户态 simulate-events；默认模拟会写入 callback、artifact、approval、timeline 记录，用于 Manager 自测展示链路和脱敏检查	AgentSimulateUserDeploymentEvents
V2 body 加密	/api/agent/user/*、/api/heicode-auth/*、/api/swarms 已按同一套 V2 设备签名和 body 加密路径设计；未加密 Web 控制台仍兼容 session + New-Api-User	heicode/middleware/auth.go、heicode/router/api-router.go
生产普通 sub 烟测记录	2026-05-31 已用生产 Manager 入口完成真实普通 sub 复核：dep_1d6d66896cc6 -> swm_03995f7c7a27，gpt-5.4，tokens_used=2682，newapi_request_id=chatcmpl-DlbZce3VZnsv5DptBILFoiRYy5ZHN，业务 code_patch artifact 可通过 Manager content 接口下载	docs/integration/heicode-desktop-sub-agile-api.md
PayPal/计费边界文档	已明确 PayPal 只是收款渠道；模型调用仍走 Heicode/NewAPI 的钱包或订阅额度；Agent 运行费用目前只有预算字段，真实收费需 Runtime usage 回传	docs/integration/Heicode-Manager-PayPal支付接入与计费关系说明.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/agent/callbacks/swarm-events/schema 输出事件类型、分类和必填字段；callback 接收端按 schema 校验关键 task/handoff/artifact/approval 字段	是	task.created/claimed/running/completed/failed/handoff/approval/artifact 都有 schema
P0	Runtime 联调配置模板	已完成：两份 Agent Manager 对接任务清单已写清 AGENT_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	Artifact 完整内容下载	已完成：用户态 /artifacts/{artifact_id}/content 代理 Runtime content，页面提供下载入口	是	artifact 属于当前用户 deployment 才能下载，响应透传 Runtime 文件内容
P1	任务图/Agent 状态展示占位	已完成：页面从 task.* / handoff.* callback 聚合 Agent task map；无真实数据时显示 Runtime callback 空态	Manager 可先做展示结构，真实数据需 Runtime	有空态和字段，不宣称真实已运行
P1	Runtime 状态诊断展示	已完成：任务总览详情页显示运行模式、运行状态、数据来源和异常 warning；兜底摘要产物会提示“不是最终业务交付物”	是	页面能识别 callback 已到但 Runtime agent 失败、只返回兜底摘要的情况
P1	日志/指标真实来源标识	已完成：logs/metrics API 返回 data_source、runtime_source，当前明确是 Manager control-plane / estimated，不伪装 Runtime 真实指标	需要 Runtime 数据	页面和 API 响应能区分来源
P1	Agent 运行费用口径收敛	已完成文档口径：budget.max_tokens/max_cost_usd/max_duration_sec 是预算约束，不等于真实扣费账本；真实收费必须依赖 Runtime 回传 usage	Manager 已完成文档，真实数据需 Runtime	页面/文档不把 estimated budget 说成真实扣费
P1	高危审批客户端联动文档	已完成：docs/integration/heicode-desktop-sub-agile-api.md 已包含 approval 查询、approve/reject、awaiting_approval 流程	是	客户端文档补齐 approval flow
P2	蜂群模式验收脚本	已完成：scripts/agent_sub_mode_smoke.py 支持 schema 检查、生产健康检查、可选 simulate-events、可选真实 callback smoke	是	本地/生产能跑出 callback、artifact、approval、timeline 可见
P2	生产 schema / 认证链路复测	本地代码和测试已覆盖；生产公开 GET /api/agent/callbacks/swarm-events/schema 当前返回 404，认证接口需有效登录态或后台 token 才能测	是，部署后复测	生产 schema 返回 200，用户态/后台态 smoke 能拿到真实数据

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

事项	为什么 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 只能保存预算和回传结果，不能凭本地估算扣真实 Agent 运行费用	model_tokens、model_cost_usd、runtime_seconds、cpu_core_seconds、memory_mb_seconds 等 usage callback
审批等待状态机	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 回调
Runtime execution summary 就等于最终交付物	不是。Manager 页面会标记这是兜底摘要；真实最终交付物必须是 Runtime/Agent 返回的 code_patch、document、test_report、Git branch/commit、部署地址等可核对 artifact
高危审批在 Manager 里点完就闭环	不是。产品要求桌面客户端主审批，并且 Runtime 要收到 decision
本地测试通过就等于生产接口全通	不是。本地 router/controller/middleware 测试能证明代码能力；生产仍必须确认对应镜像、路由和认证配置已生效
Agent budget 就等于真实收费	不是。当前 budget 是执行上限和审计字段；真实收费需要 Runtime/Agent Manager 回传可核对 usage
PayPal 接入会改变模型扣费方式	不是。PayPal 只是充值/购买订阅的收款渠道，模型调用仍从钱包余额或内部订阅额度扣

八、后续执行顺序

顺序	任务	负责人范围	备注
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	核对 Runtime usage 回传字段	Manager + 蜂群	至少覆盖模型 token/cost、运行时长、Agent role、deployment/task/correlation
7	补页面来源标识和任务图空态	Manager	防止把 simulated/control-plane 误认为 runtime