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

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

更新时间：2026-05-26
负责人范围：Heicode Manager 端
文档目的：给项目负责人、上级和联调同学快速看到当前项目流程、已完成项、未完成项、原因、依赖和下一步。

资料来源

来源	用途
http://gitee.ath.cx:3000/taijibaga/heicode/src/branch/main/docs/product-package	Heicode 产品资料包，定义客户端、Manager、Agnet 平台、模型、密钥、审批和交付边界
http://gitee.ath.cx:3000/taijibaga/fengqun/src/branch/main/docs	蜂群资料包，定义蜂群最小闭环、生产级差距、任务图、claim、handoff、artifact、审批和验收口径
当前仓库 heicode/ 代码	Manager 实际已实现能力核查
当前仓库 docs/product-package/	本仓库内同步的 Heicode 产品资料包，用于核对远端资料包落地口径
docs/heicode-runtime-auth-newapi-secret-design.md	当前 Manager / Agnet / NewAPI / Azure Key Vault 的运行时边界修正文档
docs/integration/agnet-platform-request-contract.md	Manager 到 Agnet 平台的本地最小控制面与生产联调契约

二次核查结论

本清单已经按 2026-05-26 当前代码和资料包重新核查。下面结论只按代码或文档证据填写，不把规划项写成已完成。

核查项	确认结果	证据
Heicode 产品资料包	远端资料包与本仓库 docs/product-package/ 口径一致，当前用户侧叫“密钥保管器”，技术实现写 Azure Key Vault	docs/product-package/README.md、docs/product-package/01-product-overview.md、远端 Gitea contents API
蜂群资料包	fengqun 已完成的是 swarm-minimal 本地最小闭环，不等于生产级平台联调完成	远端 MINIMAL_CLOSED_LOOP_STATUS.zh-CN.md、01-ten-day-delivery-plan.md
瀑布 / 敏捷与蜂群关系	Heicode 可用瀑布/敏捷表达任务组织或阶段门；蜂群 Runtime 不能依托瀑布、敏捷、Scrum 固定流程	docs/heicode.md、远端 agnet-swarm-design-principles.md
Manager Agnet 控制面	本仓库实现的是 /api/agnet/deployments 本地最小控制面，占位保存 deployment、manifest、audit、logs/metrics 空壳；未真实创建生产 Swarm Run	heicode/controller/agnet_control_plane.go、docs/integration/agnet-platform-request-contract.md
用户任务入口	首页已通过 mcp-server 代理创建 HeicodeTask、追问和任务卡；但任务卡尚未自动转换成本地 Agnet deployment 或真实 Swarm Run	heicode/web/default/src/lib/heicode-mcp.ts、heicode/web/default/src/features/tasks/task-card-view.tsx
普通用户部署权限	当前 /api/agnet/deployments 创建/查询/停止走 AdminAuth，不满足普通用户在 Manager 辅助控制台发起部署的产品闭环	heicode/router/api-router.go
平台回调	当前没有 POST /api/agnet/callbacks/swarm-events、approval-requests、artifacts、usage、status 这类服务端回调入口	heicode/router/api-router.go、远端 agnet-swarm-design-principles.md
审批能力	Manager 有用户态 approval/lease 记录 API，但这不是 Agnet 平台服务端回调审批主线，也没有回传 Runtime 继续/停止	heicode/controller/agnet_approval.go

结论摘要

1. sub 模式下的瀑布 / 敏捷，和蜂群模式不是一回事。
2. sub 模式瀑布 / 敏捷属于 Heicode 的任务组织方式和用户体验层，决定任务怎么拆、怎么推进、怎么确认。
3. 蜂群模式属于 Agnet / Swarm Runtime 执行层，决定多个 Agent / worker 如何动态生成任务图、claim 任务、交接、失败恢复、回传事件和交付物。
4. Manager 侧已经完成资源、密钥、权限、任务草稿入口、任务卡展示、Agnet 部署本地占位、审批记录、短期凭证租约、审计展示等基础控制面。
5. 当前还没有完成生产级蜂群闭环：没有真实 POST /api/swarms 或生产 Agnet 平台创建联调、没有真实 worker runtime claim、没有 artifact / event callback 完整接收、没有客户端高危审批主体验闭环。
6. 蜂群资料包明确说明：fengqun 当前达到本仓库定义的最小化闭环验收，但不是生产级完整交付；生产级差距在 Kubernetes worker runtime、Manager / Agnet API、人类审批主线、生产权限和监控。
7. 当前 Manager 端最大风险不是“没有页面”，而是“页面/接口已有一部分，但仍是本地控制面、管理员权限或 mcp-server 任务草稿，尚未和生产 Swarm Runtime 打通”。

概念边界

概念	所属层	当前定位	不能误解为
sub 瀑布	Heicode 任务组织层	按需求、设计、开发、测试、部署等阶段推进	蜂群 Runtime
sub 敏捷	Heicode 任务组织层	小步迭代，允许多轮反馈和调整	蜂群 Runtime
蜂群模式	Agnet / Swarm Runtime 层	动态任务图、能力编队、任务池 claim、handoff、失败恢复、事件和产物回传	瀑布 / 敏捷 / Scrum
Manager	控制面 / 辅助控制台	资源绑定、密钥引用、权限、启动摘要、状态、审计、审批记录	编码主体验或 Runtime 执行器
客户端	用户主体验	输入想法、持续推进任务、查看反馈、接收交付、高危审批	资源后台或模型供应商配置页
蜂群平台	执行层	AKS / worker runtime、任务图、claim、事件、artifact、指标	用户控制台

总体流程

用户输入想法
-> Heicode 形成任务目标、约束和上下文
-> Manager 准备资源绑定、secret_ref、Resource Grant、审批策略和启动摘要
-> sub 模式选择任务组织方式（瀑布 / 敏捷）
-> Manager 生成 Agnet / Swarm 请求 payload
-> 蜂群平台创建 Swarm Run / 动态任务图 / 能力编队
-> 子 Agnet claim 任务、执行、handoff、失败恢复
-> 高危动作请求客户端审批
-> 审批通过后派生短期凭证
-> 蜂群平台回传状态、事件、日志、指标、artifact、用量、审计
-> Manager 展示状态和审计，客户端展示执行反馈和交付结果

已完成清单

模块	已完成内容	代码 / 页面证据	当前状态
登录与用户	Manager 支持 Heicode 登录、会话、用户上下文、sub / user id 作为业务身份基础	heicode/controller/heicode_oauth.go、heicode/router/api-router.go	已完成基础能力
模型与余额	客户端模型列表、余额、用量基础链路已接 Manager / NewAPI	/api/heicode/self、模型/渠道页面	已完成基础能力
设备绑定	设备配对、撤销、重新配对、审计、真实 IP、设备列表体验已修复	devices 相关接口与页面	已完成
任务想法入口	首页可通过 mcp-server 代理提交 idea，生成 HeicodeTask 并进入追问/任务卡	heicode/web/default/src/features/dashboard/components/home-hero.tsx、heicode/web/default/src/lib/heicode-mcp.ts	已完成任务草稿入口，未接 Agnet 部署
任务追问与任务卡	支持 configuring 追问、答题、任务卡目标/范围/自动生成/Manager 辅助入口展示	heicode/web/default/src/features/tasks/task-card-view.tsx	已完成基础体验
资源绑定	支持 Git / SK / 项目文档 / 云账号 / 云资源等 Resource Binding 数据结构	heicode/controller/resource.go、heicode/model/resource.go	已完成基础能力
资源授权	支持 Resource Grant，能生成 permission manifest	/api/resource-grants、/api/resource-grants/manifest	已完成基础能力
资源撤销	Resource Binding 和 Grant 删除改为 revoked，保留审计链路	DeleteResource、DeleteResourceGrant	已完成
Azure Key Vault	支持 VM Managed Identity 访问 Key Vault、PutSecret、GetSecret、健康状态检查、azkv://... 引用	heicode/controller/secret_store.go	已完成 Manager 侧
Azure 资源发现	Azure cloud account 绑定后可读取 Key Vault 中 SP 凭证并调用 ARM 发现资源	heicode/controller/azure_resource_discovery.go	已完成 Azure 第一阶段
Agnet 角色	提供六角色模板：Product / Architect / Frontend / Backend / Reviewer / Ops	heicode/controller/agnet_role_template.go	已完成
Agnet 部署占位	支持创建、查询、停止 Agnet deployment，占位状态持久化到 DB；能校验 budget、runtime、resource_grants、secret_ref	heicode/controller/agnet_control_plane.go、heicode/model/agnet_deployment.go	已完成控制面占位，非真实 Runtime
权限清单展示	部署详情优先展示持久化 permission manifest，密钥引用脱敏	heicode/web/default/src/features/agnet-console/pages.tsx	已完成
审计事件	Agnet audit event 持久化，不再仅内存保存；deployment events/logs 可从审计表回放	heicode/model/agnet_audit.go、AgnetListDeploymentEvents、AgnetListDeploymentLogs	已完成本地审计
SK 快照解析	可以根据 deployment 中的 sk_sources 生成 SK snapshot 摘要	AgnetResolveSKSnapshots、AgnetListSKSnapshots	已完成内存级占位，未持久化
审批记录	支持 Agnet approval request 创建、审批、拒绝、过期	heicode/controller/agnet_approval.go	已完成 Manager 记录层
短期凭证租约	审批通过后可生成 lease://agnet/...，支持撤销和过期	heicode/model/agnet_approval.go	已完成 Manager 记录层
审计页面	可查看审批、lease、审计流水，敏感字段脱敏	/audit、AgnetAuditPage	已完成基础展示
密钥状态页面	系统设置中可看 Key Vault 配置、认证方式、可达状态	/api/secret-store/status	已完成
后台菜单	模型、模型部署、供应商、全部使用日志等菜单错绑已修复	后台菜单点击冒烟通过	已完成
版本与上线	Manager 生产版本为 1.4.4，线上 VM 构建部署已完成	https://code.xinghanlab.com/api/status	已上线

未完成清单

模块	未完成内容	没做完的原因	缺什么	归属
sub 模式字段	没有完整的 sub_mode = waterfall/agile 任务字段、接口参数、页面选择和后端持久化	产品允许用瀑布/敏捷表达任务组织，但蜂群 Runtime 不应绑定固定方法论；当前代码没有统一字段	任务模型字段、选择入口、payload 映射、验收状态	Manager 可先做
sub 任务编排	HeicodeTask 没有自动生成 Agnet deployment payload 并启动	mcp-server 任务卡和本地 /api/agnet/deployments 是两条线，尚未打通	task -> recommendation -> resource grants -> deployment payload 的桥接层	Manager 可先做，客户端配合验收
用户态部署权限	普通用户无法按产品闭环直接创建 Agnet deployment	后端 deployment 控制面当前使用 AdminAuth，更像联调/管理接口	设计 user-scoped create/query/stop，校验 resource grants 和用户归属	Manager 可先做
API 命名统一	蜂群资料包使用 POST /api/swarms，Manager 本地契约和代码使用 /api/agnet/deployments	两份资料来源处于不同层：蜂群目标平台 vs Manager 当前最小控制面	明确 adapter 或统一接口命名，避免联调时双方对不上	Manager + 蜂群平台
瀑布 / 敏捷流程展示	客户端/Manager 还不能按瀑布或敏捷展示子阶段状态	缺少统一任务阶段模型和状态事件	stage, iteration, checkpoint, approval_gate 等字段	Manager + 客户端
真实蜂群创建	Manager 未真实调用蜂群平台 POST /api/swarms 或等价接口	当前 /api/agnet/deployments 是 Manager 本地控制面占位	蜂群平台稳定 API、认证、请求/响应契约、联调环境	需要蜂群平台
swarm_id 绑定	Manager 未保存真实 swarm_id、task graph、worker 状态	真实 Runtime 尚未联调	Swarm Run 模型、状态表、映射关系	Manager + 蜂群平台
动态任务图	没有展示真实动态任务图、任务 claim、heartbeat、release、timeout	Manager 没有收到 Runtime 任务事件	swarm_tasks / task_graph / claim / heartbeat 事件	需要蜂群平台
handoff / retry	没有真实失败、交接、重试、blocked 状态闭环	目前事件主要来自 Manager 审计，占位性质	Runtime 失败注入、handoff 事件、重试策略	需要蜂群平台
artifact 回传	没有 artifact 接收表、回调接口和交付物页面闭环	当前没有蜂群平台 artifact callback	artifact schema、存储位置、回调签名、展示页面	Manager 可建接口，需蜂群输出
真实日志流	没有生产级实时日志流，当前 logs 主要是脱敏审计占位	蜂群平台日志接口/SSE 未接入	/logs/stream 或事件流、脱敏规则、保留策略	需要蜂群平台
真实指标	Metrics 仍是空/估算，不是 Runtime CPU、内存、耗时、token、成本	缺少 Runtime 指标源	Prometheus/监控接口、指标字段、correlation_id	需要蜂群平台/基础设施
callback 接收	Manager 缺少统一 swarm-events、artifacts、approval-requests、usage、status callback 接收端	目前是 Manager 拉取/本地记录，不是平台服务端回调；approval API 也需要用户认证，不适合 Runtime 直接调用	回调 URL、签名验证、幂等 key、重复回调处理、服务身份认证	Manager 可先做，需蜂群调用
客户端审批主体验	高危审批现在是 Manager API/后台页面能力，不是客户端主审批弹窗	产品文档要求客户端审批，Manager 不替代客户端	客户端审批 UI、push/轮询、approval_id 回传	需要客户端
审批回传蜂群	审批通过/拒绝后未真实通知 Runtime 继续或停止	蜂群平台审批等待状态机未联调	approval result callback/API	Manager + 蜂群平台
短期凭证注入	Manager 只有 lease://agnet/... 记录，不负责真实派生/注入子 Agnet runtime	真实凭证派生与注入应在受控 Runtime/平台完成	Key Vault 读取策略、最小权限临时凭证、runtime 注入通道	需要蜂群平台/基础设施
SK 快照持久化	SK snapshot 当前存内存，容器重启会丢	agnetSnapshots 是内存 map，没有对应 DB 表	snapshot 表、artifact/source 版本、查询分页	Manager 可先做
SK 工具调用展示	没有真实“调用哪个 SK、产出什么、失败原因”的任务视角展示	当前只有 SK source / snapshot 占位	SK invocation event、tool output summary、失败事件	需要蜂群/SK 平台
子 Agnet 用量归属	模型用量没有按 task / deployment / role / sub agent 聚合展示	NewAPI 用量和蜂群任务上下文尚未打通	request metadata、correlation_id、role、task_id	Manager + NewAPI + 蜂群
交付结果回流	客户端/Manager 没有完整交付物、测试结果、部署链接展示	Runtime 未产出正式 artifact/result schema	delivery result schema、artifact 存储、客户端展示	Manager + 客户端 + 蜂群
AWS/GCP	云资源绑定目前主要做 Azure，AWS/GCP 未实现	当前优先级先做 Azure Key Vault / ARM	AWS/GCP 授权、发现、secret_ref、权限映射	Manager 后续
历史文档口径	docs/heicode.md 仍保留 Vault/Secret Provider 历史选项，新产品资料包和运行时设计已锁定 Azure Key Vault	新旧文档有历史分层，容易被误读为还要接 OpenBao/Vault	保留用户侧“密钥保管器”，实现侧统一写 Azure Key Vault；清理旧优先级表述	Manager/产品文档可改

按归属拆分

Manager 可以独立继续做

事项	说明	优先级
增加 sub 模式字段	waterfall / agile 存到任务或部署计划中	P0
打通 idea task 到 Agnet deployment	从任务生成推荐角色、资源、预算、风险、payload	P0
增加用户态 Agnet deployment API	在 UserAuth 下允许用户创建/查询/停止自己资源范围内的 deployment	P0
callback 接收端骨架	先实现事件、artifact、approval-request 回调接口和幂等保存	P0
artifact 数据模型	先建 artifact 表、列表 API、详情展示	P0
统一 /api/swarms 与 /api/agnet/deployments 边界	明确 Manager 对外给 Runtime 的生产接口，保留本地 control-plane 兼容层	P0
持久化 SK snapshot	去掉仅内存保存，保证重启后审计和任务上下文不丢	P1
任务视角审计聚合	按 task/deployment/correlation_id 聚合日志、审批、资源、用量	P1
文档口径同步 Azure Key Vault	清理旧 Vault / Secret Provider 优先级表述，避免被误读为还要接 OpenBao/Vault	P1
AWS/GCP 占位与提示	保持 UI 明确“即将支持”，避免误导	P2

需要客户端配合

事项	Manager 需要提供	客户端需要提供
高危审批主体验	approval list/detail/approve/reject API、风险摘要、TTL、resource scope	审批弹窗、用户确认、拒绝、结果回传
任务驾驶舱	task status、stage、event、artifact、delivery API	持续任务对话、状态展示、交付接收
sub 瀑布/敏捷展示	stage/iteration/checkpoint 状态数据	按模式展示进度和下一步

需要蜂群 / Agnet Runtime 配合

事项	Manager 需要	蜂群平台需要
真实创建 Swarm Run	创建请求、secret_ref、Resource Grant、预算、审批策略	swarm_id、初始任务图、能力编队、状态返回
任务 claim / heartbeat	状态展示、事件保存	worker claim、heartbeat、release、timeout
handoff / retry / blocked	展示失败和后续动作	失败恢复、任务交接、重试上限
event / artifact callback	回调接收端和幂等处理	事件、产物、日志摘要回调
真实日志 / 指标	查询和展示	日志流、指标源、脱敏和保留
短期凭证注入	审批记录、lease 引用、secret_ref	读取/派生短期凭证并注入子 Agnet

需要基础设施配合

事项	依赖
Kubernetes worker runtime	AKS/集群、worker 镜像、服务账号、网络策略
监控指标	Prometheus 或等价指标源、日志采集、告警规则
Key Vault 网络安全	Private Endpoint / 防火墙 / Managed Identity / Workload Identity
生产级回调安全	内网访问、签名验证、重放保护、request id / correlation id

当前风险

风险	影响	应对
把蜂群最小闭环误报为生产级完成	上级预期错误，联调时暴露落差	文档明确“最小闭环已验收，不等于生产级完整交付”
把瀑布/敏捷和蜂群模式混为一谈	产品和技术边界混乱	sub 模式只表达任务组织，蜂群只表达执行层
Manager 继续堆本地占位接口	看起来页面有了，但真实 Runtime 没跑	所有占位接口在文档和页面中标清“control-plane placeholder”
客户端审批未接入	高危操作不符合产品边界	Manager 只保留记录/API，最终审批必须走客户端
历史 Vault / Azure Key Vault 口径混用	部署和安全沟通混乱	统一用户侧叫“密钥保管器”，当前实现侧写 Azure Key Vault
日志/指标无真实来源	无法验收蜂群运行质量	等 Runtime 接入后按 correlation_id 验证事件、日志、指标、artifact

下一步建议

5/27-5/28：全链路联调与问题收敛

任务	目标	验收标准
sub 模式字段落地	明确任务采用瀑布或敏捷组织方式	payload / DB / UI 至少有一个可追溯字段
idea -> deployment 桥接	从用户想法生成 Agnet deployment 请求	不再只手动建部署；任务能关联 deployment_id
用户态部署权限	普通用户可在自己资源范围内创建/查看 deployment	非管理员用户不 403，且不能越权看别人 deployment
callback 骨架	Manager 能接事件和 artifact 回调	本地模拟回调可保存、去重、展示
客户端审批接口联调	客户端能读 pending approval 并回传决定	approval approve/reject 后状态正确

5/29-5/30：全面测试、验收与上线风险确认

任务	目标	验收标准
真实蜂群接口联调	Manager 调用蜂群平台创建 Swarm Run	获得真实 swarm_id，状态可查
任务 claim 可见	Runtime 任务领取状态回到 Manager	能看到 created -> claimed -> running
artifact / event 可见	执行结果和事件回到 Manager	至少一个 task.completed 和 artifact 摘要
安全验收	密钥不明文，审批有记录，lease 可撤销	日志、页面、API 响应均无明文密钥
最终风险报告	明确上线可放行与阻塞项	剩余问题按 Manager / 客户端 / 蜂群 / 基础设施分类

验收清单

验收项	当前状态	通过标准
Manager 能保存资源和 secret_ref	已完成	资源响应不含明文密钥
Manager 能生成 Resource Grant manifest	已完成	manifest 只含授权范围和 secret_ref
Manager 能创建 Agnet deployment	已完成占位	生产级需真实调用蜂群平台
普通用户创建 deployment	未完成	UserAuth 用户能基于自己的 Resource Grant 创建，不要求管理员权限
Manager 能展示审计事件	已完成基础	生产级需包含 Runtime 事件
Manager 能记录审批和 lease	已完成记录层	生产级需客户端审批和 Runtime 继续/停止
sub 瀑布/敏捷模式	未完成	有模式字段、状态流和页面展示
/api/swarms / /api/agnet/deployments 口径	未完成	Manager 与蜂群平台统一创建接口或有明确 adapter
真实 Swarm Run	未完成	Manager 获得真实 swarm_id
任务 claim	未完成	至少一个任务从 created 到 claimed/running
handoff / retry	未完成	失败任务可回流或转交，并可观察
artifact 回传	未完成	Manager/客户端可看到交付物摘要
日志/指标	未完成	可按 correlation_id 查询日志、指标、用量
客户端高危审批	未完成	客户端审批后 Manager 和 Runtime 状态一致

代码索引

能力	主要文件
Agnet 控制面占位	heicode/controller/agnet_control_plane.go
Agnet 审批和 lease	heicode/controller/agnet_approval.go、heicode/model/agnet_approval.go
Agnet 审计	heicode/model/agnet_audit.go
资源绑定和授权	heicode/controller/resource.go、heicode/model/resource.go
Azure Key Vault	heicode/controller/secret_store.go
Azure 资源发现	heicode/controller/azure_resource_discovery.go
前端 Agnet 控制台	heicode/web/default/src/features/agnet-console/
任务想法入口	heicode/web/default/src/features/dashboard/components/home-hero.tsx
Heicode task / mcp client	heicode/web/default/src/lib/heicode-mcp.ts