From cc148b15c3e961cf1463e8d3ad2ce3586d892d2d Mon Sep 17 00:00:00 2001 From: gongzhiyong Date: Tue, 26 May 2026 17:46:51 +0800 Subject: [PATCH] docs: add sub swarm progress checklist --- docs/README.md | 1 + ...de-manager-sub-swarm-progress-checklist.md | 203 ++++++++++++++++++ 2 files changed, 204 insertions(+) create mode 100644 docs/heicode-manager-sub-swarm-progress-checklist.md diff --git a/docs/README.md b/docs/README.md index 7fe4f97..ad63cc0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -7,6 +7,7 @@ | [`heicode.md`](./heicode.md) | Heicode 当前产品定位、系统边界和架构共识 | | [`plan.md`](./plan.md) | 按当前共识拆出的实施计划 | | [`heicode-runtime-auth-newapi-secret-design.md`](./heicode-runtime-auth-newapi-secret-design.md) | 用户输入、登录用户复用、NewAPI 扣费映射、Azure Key Vault 凭证托管与短期凭证注入边界 | +| [`heicode-manager-sub-swarm-progress-checklist.md`](./heicode-manager-sub-swarm-progress-checklist.md) | Heicode Manager sub 模式、瀑布/敏捷、蜂群模式的已完成/未完成/依赖/风险/下一步进度清单 | | [`integration/Heicode-登录接口对接文档.md`](./integration/Heicode-登录接口对接文档.md) | 已上线登录接口对接文档 | | [`integration/agnet-platform-request-contract.md`](./integration/agnet-platform-request-contract.md) | Manager 请求 Agnet 平台时携带的部署、日志、监控、事件与审计接口参数 | | [`deployment/azure-production-deploy-guardrails.md`](./deployment/azure-production-deploy-guardrails.md) | Azure VM / PostgreSQL / Redis / Agnet / NewAPI 生产部署前的安全守卫、环境变量注入和验证计划 | diff --git a/docs/heicode-manager-sub-swarm-progress-checklist.md b/docs/heicode-manager-sub-swarm-progress-checklist.md new file mode 100644 index 0000000..3e4ee58 --- /dev/null +++ b/docs/heicode-manager-sub-swarm-progress-checklist.md @@ -0,0 +1,203 @@ +# 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 实际已实现能力核查 | + +## 结论摘要 + +1. sub 模式下的瀑布 / 敏捷，和蜂群模式不是一回事。 +2. sub 模式瀑布 / 敏捷属于 Heicode 的任务组织方式和用户体验层，决定任务怎么拆、怎么推进、怎么确认。 +3. 蜂群模式属于 Agnet / Swarm Runtime 执行层，决定多个 Agent / worker 如何动态生成任务图、claim 任务、交接、失败恢复、回传事件和交付物。 +4. Manager 侧已经完成资源、密钥、权限、Agnet 部署占位、审批记录、短期凭证租约、审计展示等基础控制面。 +5. 当前还没有完成生产级蜂群闭环：没有真实 `POST /api/swarms` 联调、没有真实 worker runtime claim、没有 artifact / event callback 完整接收、没有客户端高危审批主体验闭环。 +6. 蜂群资料包明确说明：`fengqun` 当前达到本仓库定义的最小化闭环验收，但不是生产级完整交付；生产级差距在 Kubernetes worker runtime、Manager / Agnet API、人类审批主线、生产权限和监控。 + +## 概念边界 + +| 概念 | 所属层 | 当前定位 | 不能误解为 | +|---|---|---|---| +| sub 瀑布 | Heicode 任务组织层 | 按需求、设计、开发、测试、部署等阶段推进 | 蜂群 Runtime | +| sub 敏捷 | Heicode 任务组织层 | 小步迭代，允许多轮反馈和调整 | 蜂群 Runtime | +| 蜂群模式 | Agnet / Swarm Runtime 层 | 动态任务图、能力编队、任务池 claim、handoff、失败恢复、事件和产物回传 | 瀑布 / 敏捷 / Scrum | +| Manager | 控制面 / 辅助控制台 | 资源绑定、密钥引用、权限、启动摘要、状态、审计、审批记录 | 编码主体验或 Runtime 执行器 | +| 客户端 | 用户主体验 | 输入想法、持续推进任务、查看反馈、接收交付、高危审批 | 资源后台或模型供应商配置页 | +| 蜂群平台 | 执行层 | AKS / worker runtime、任务图、claim、事件、artifact、指标 | 用户控制台 | + +## 总体流程 + +```text +用户输入想法 +-> 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` 相关接口与页面 | 已完成 | +| 任务想法入口 | 首页可提交 idea 到任务接口，任务列表可展示最近任务 | `heicode/web/default/src/features/dashboard/components/home-hero.tsx`、`heicode/web/default/src/lib/heicode-mcp.ts` | 已有入口，但未完全接到 Agnet 部署 | +| 资源绑定 | 支持 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 | `heicode/controller/agnet_control_plane.go`、`heicode/model/agnet_deployment.go` | 已完成控制面占位 | +| 权限清单展示 | 部署详情优先展示持久化 permission manifest，密钥引用脱敏 | `heicode/web/default/src/features/agnet-console/pages.tsx` | 已完成 | +| 审计事件 | Agnet audit event 持久化，不再仅内存保存 | `heicode/model/agnet_audit.go` | 已完成 | +| 审批记录 | 支持 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` 任务字段、接口参数、页面选择和后端持久化 | 当前页面只有 `Agile Minimal` / `Waterfall Minimal` 模板展示，不是完整模式闭环 | 任务模型字段、选择入口、payload 映射、验收状态 | Manager 可先做 | +| sub 任务编排 | idea / HeicodeTask 没有自动生成 Agnet deployment payload 并启动 | 首页任务接口和部署页是两条线，尚未打通 | task -> recommendation -> resource grants -> deployment payload 的桥接层 | 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` callback 接收端 | 目前是 Manager 拉取/本地记录，不是平台回调 | 回调 URL、签名验证、幂等 key、重复回调处理 | Manager 可先做，需蜂群调用 | +| 客户端审批主体验 | 高危审批现在是 Manager API/后台页面，不是客户端主审批弹窗 | 产品文档要求客户端审批，Manager 不替代客户端 | 客户端审批 UI、push/轮询、approval_id 回传 | 需要客户端 | +| 审批回传蜂群 | 审批通过/拒绝后未真实通知 Runtime 继续或停止 | 蜂群平台审批等待状态机未联调 | approval result callback/API | Manager + 蜂群平台 | +| 短期凭证注入 | Manager 只有 lease 记录，不负责真实派生/注入子 Agnet runtime | 真实凭证派生与注入应在受控 Runtime/平台完成 | Key Vault 读取策略、最小权限临时凭证、runtime 注入通道 | 需要蜂群平台/基础设施 | +| 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 后续 | +| 文档口径 | Heicode 远程资料包仍有 OpenBao 表述，实际决策已经改为 Azure Key Vault | 产品文档未同步最新决策 | 将 OpenBao 更新为 Azure Key Vault，保留“密钥保管器”用户称呼 | Manager/产品文档可改 | + +## 按归属拆分 + +### Manager 可以独立继续做 + +| 事项 | 说明 | 优先级 | +|---|---|---| +| 增加 sub 模式字段 | `waterfall` / `agile` 存到任务或部署计划中 | P0 | +| 打通 idea task 到 Agnet deployment | 从任务生成推荐角色、资源、预算、风险、payload | P0 | +| callback 接收端骨架 | 先实现事件、artifact、approval-request 回调接口和幂等保存 | P0 | +| artifact 数据模型 | 先建 artifact 表、列表 API、详情展示 | P0 | +| 任务视角审计聚合 | 按 task/deployment/correlation_id 聚合日志、审批、资源、用量 | P1 | +| 文档口径同步 Azure Key Vault | 产品包中 OpenBao 更新为 Azure Key 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，最终审批必须走客户端 | +| OpenBao / Azure Key Vault 文档不一致 | 部署和安全沟通混乱 | 统一用户侧叫“密钥保管器”，技术实现写 Azure Key Vault | +| 日志/指标无真实来源 | 无法验收蜂群运行质量 | 等 Runtime 接入后按 correlation_id 验证事件、日志、指标、artifact | + +## 下一步建议 + +### 5/27-5/28：全链路联调与问题收敛 + +| 任务 | 目标 | 验收标准 | +|---|---|---| +| sub 模式字段落地 | 明确任务采用瀑布或敏捷组织方式 | payload / DB / UI 至少有一个可追溯字段 | +| idea -> deployment 桥接 | 从用户想法生成 Agnet deployment 请求 | 不再只手动建部署；任务能关联 deployment_id | +| 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 | 已完成占位 | 生产级需真实调用蜂群平台 | +| Manager 能展示审计事件 | 已完成基础 | 生产级需包含 Runtime 事件 | +| Manager 能记录审批和 lease | 已完成记录层 | 生产级需客户端审批和 Runtime 继续/停止 | +| sub 瀑布/敏捷模式 | 未完成 | 有模式字段、状态流和页面展示 | +| 真实 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` | +