feat: complete swarm manager callback loop

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

@@ -0,0 +1,112 @@
+# 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` 默认链路也能写入 callback、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 | 当前没有真实 task graph 表和状态展示 | 不满足 | 需要 Runtime 产出 task graph/claim/heartbeat 事件 | 蜂群 + Manager |
+| 展示 handoff、blocked、retry | callback 可接任意 event，但没有专门展示和字段约束 | 部分满足 | 需要标准事件 schema 和 Runtime 实际事件 | 蜂群 + Manager |
+| 高危审批请求进入 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 和代码看，当前项目结构是：
+
+```text
+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 可接 callback，但没有真实数据 | 蜂群侧定义并回调 `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 展示 | 可接通用 callback，但页面未专门展示 | 先定事件 schema，再补 timeline 展示 |
+| 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：完善项
+
+| 缺失项 | 当前状态 | 处理建议 |
+|---|---|---|
+| 蜂群验收脚本 | Manager 默认模拟和单测已覆盖 callback/artifact/approval/timeline；生产 curl 脚本仍需整理 | 增加一套可给联调方直接执行的 curl 脚本 |
+| 页面术语统一 | 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 | 根据真实联调结果更新本文状态 | 把缺失项从“缺接口/未联调”改为“已验证/阻塞/延期” |