docs: 删除已废弃的蜂群 / 旧计划文档

蜂群(swarm)旧版已弃、新版未出 → 删全部蜂群文档；附带删除旧执行/改造计划与旧项目交接稿（均为已废弃旧产物，由 HM owner 确认）。docs/README 当前索引不引用它们，无死链。删除： - docs/heicode-manager-sub-swarm-progress-checklist.md - docs/heicode-manager-swarm-gap-analysis.md - docs/heicode-manager-standalone-execution-plan.md - docs/integration/agent-manager-swarm-runtime-change-request.md - docs/integration/heicode-manager-swarm-runtime-env-template.md - docs/integration/AgentManager蜂群Runtime接口实现要求.md - docs/integration/AgentManager蜂群Runtime联调待确认与补充要求.md - docs/integration/蜂群模式-AgentManager对接任务清单.md - docs/Heicode-Manager-agent统一改造落地计划.md - Heicode-Manager-项目说明与踩坑交接.md 影响面：仅文档。 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-08 13:29:06 +08:00
parent c9767eb6bb
commit 11f399826c
10 changed files with 0 additions and 3223 deletions
@@ -1,208 +0,0 @@
 # Heicode Manager 项目说明与踩坑交接
 更新时间：2026-06-01  
 用途：给下一位 AI / 工程师快速理解 Heicode Manager 的项目边界、生产拓扑、普通 sub、蜂群、NewAPI 和已踩过的坑。
 ## 1. 一句话说明
 Heicode Manager 是 Heicode 的服务端控制面和网页管理台，负责用户登录、模型网关配置、用户/设备/模型/渠道管理、普通 sub 敏捷任务控制、Runtime callback 落库、artifact/timeline 展示，以及和桌面客户端、Agent Manager Runtime、NewAPI、Azure Key Vault 之间的编排。
 它不是桌面客户端本体，也不是 Agent Runtime 本体，也不是 NewAPI 本体。
 ## 2. 仓库结构
 | 路径 | 作用 | 说明 |
 |------|------|------|
 | `heicode/` | Manager 后端和默认前端 | Go + Gin/GORM，`web/default` 是当前网页端 |
 | `cc-haha/` | Heicode 桌面客户端和本地服务 | Tauri + React + Bun，客户端到 Manager 的请求 body 会走加密/签名流程 |
 | `docs/` | 项目文档、部署、集成、进度清单 | 后续交接优先看这里 |
 | `docs/deployment/` | 生产部署和迁移文档 | VM、Azure、配置交接 |
 | `docs/integration/` | Runtime、桌面客户端、蜂群、普通 sub 对接文档 | 联调时优先看 |
 开发前先看：
 | 范围 | 文档 |
 |------|------|
 | 根仓库规则 | `AGENTS.md` |
 | Manager 规则 | `heicode/AGENTS.md` |
 | 生产配置 | `docs/deployment/Heicode-Manager-生产配置与账号交接清单.md` |
 | 普通 sub 桌面客户端对接 | `docs/integration/heicode-desktop-sub-agile-api.md` |
 | 普通 sub Agent Manager 对接 | `docs/integration/普通sub敏捷模式-AgentManager对接任务清单.md` |
 | 蜂群 Agent Manager 对接 | `docs/integration/蜂群模式-AgentManager对接任务清单.md` |
 ## 3. 生产拓扑
 ```text
 用户/桌面客户端
  -> https://code.xinghanlab.com
  -> Heicode Manager Docker container on Azure VM
  -> Azure PostgreSQL / Azure Redis
  -> NewAPI model gateway
  -> 普通 sub Agent Manager Runtime: http://20.212.121.126
  -> 蜂群 Runtime / Orchestrator: http://52.139.240.116:8000
  -> Azure Key Vault: https://heicode-kv.vault.azure.net
 ```
 当前 Manager 部署在 Azure VM 上，容器名 `heicode`，端口 `3000:3000`。VM 上也能看到 `new-api`、`postgres`、`redis`、`heicode-openbao` 容器，但正式业务数据库和缓存应以 Azure 托管 PostgreSQL / Redis 配置为准，不要误用 VM 本地容器判断生产数据。
 ## 4. 普通 sub 和蜂群必须分开
 这是最容易踩坑的点。
 | 模式 | 含义 | Manager 当前配置 | Runtime |
 |------|------|------------------|---------|
 | 普通 sub 敏捷模式 | 桌面客户端把一个开发任务拆给若干子 Agent，按需求、设计、开发、测试、部署等阶段推进 | `AGENT_RUNTIME_ENABLED=true` | `http://20.212.121.126` |
 | 蜂群模式 | HeiCode-Swarm 的多 Agent swarm run / task graph 模式 | `SWARM_RUNTIME_ENABLED=false` | `http://52.139.240.116:8000`，需单独启用和联调 |
 不要因为两个接口都可能叫 `/api/swarms` 就把它们混成一个概念。普通 sub 是 Heicode 的任务组织方式；蜂群是独立 swarm runtime 形态。
 ## 5. 普通 sub 当前主流程
 ```text
 桌面客户端创建/补充任务
  -> Manager 用户态接口生成 deployment draft
  -> Manager 调 Agent Manager Runtime POST /api/swarms
  -> Runtime 创建 run 并启动子 Agent
  -> Runtime 执行中 callback Manager
  -> Manager 保存 timeline / events / logs / artifacts / usage
  -> 桌面客户端从 Manager 查询展示
 ```
 关键点：
 1. Runtime 执行过程会回调状态、日志、timeline、用量。
 2. 最终业务交付物不是直接塞在聊天文本里，而是通过 `artifact.created` 落库。
 3. 客户端应先查 artifact 列表，再通过 content 接口下载完整产物。
 4. 如果 `usage=0` 或只有失败摘要 artifact，不能算真实业务交付完成。
 ## 6. artifact 展示坑
 桌面客户端曾出现“以下是作为 Frontend 角色...”这种内容，看起来像交付物，其实多半只是 Runtime 的摘要文本。
 正常设计应该是：
 | 层级 | 应展示什么 |
 |------|------------|
 | 聊天时间线 | 阶段进度、Agent 状态、摘要说明 |
 | 交付产物卡片 | `artifact_id`、标题、类型、摘要、大小、hash、下载入口 |
 | 完整代码/文件 | 通过 `GET /api/agent/user/deployments/{deployment_id}/artifacts/{artifact_id}/content` 下载 |
 如果 artifact 里有 `azblob://...` 或 `runtime://...`，客户端不应该直接暴露云凭据或要求用户自己访问 Blob，而应通过 Manager / Runtime content 代理接口拿完整内容。
 ## 7. NewAPI / 模型调用边界
 NewAPI 是模型网关和用量计费入口，不是 Heicode Manager 自己的模型执行器。
 排查模型问题时要区分三条链路：
 | 链路 | 调用方 | 常见问题 |
 |------|--------|----------|
 | 桌面普通聊天 | 桌面客户端 -> Manager/NewAPI | 用户 token、模型列表、渠道权限、body 加密 |
 | 普通 sub Runtime Agent | Runtime 子 Agent -> NewAPI/Manager 模型网关 | Runtime 环境变量、模型名、base_url、请求路径、上游超时 |
 | Manager 后台模型配置 | 管理员网页 -> Manager/NewAPI | 渠道配置、分组、可用模型、价格表达式 |
 曾踩过的坑：
 - 某个模型 503/504 时，不一定是客户端参数错，也可能是 Runtime 子 Agent 使用的模型、base_url 或请求格式不对。
 - Runtime 需要回传 `newapi_request_id` 和非零 token usage，方便定位 NewAPI 日志。
 - 一个模型失败时可以切换模型验证，但不能把失败摘要 artifact 当成业务完成。
 ## 8. Azure Key Vault / OpenBao 边界
 当前正式方向是 Azure Key Vault，不是 OpenBao。
 | 项目 | 结论 |
 |------|------|
 | Azure Key Vault | 正式长期密钥托管方案 |
 | OpenBao | VM 上存在历史/兼容容器，不作为当前正式方案 |
 | Managed Identity | Manager 访问 Key Vault 的推荐方式 |
 | 当前已知问题 | 之前健康检查出现过 `Identity not found`，说明 VM 身份或 `AZURE_CLIENT_ID`/Vault 权限未配好 |
 如果后续迁移到 Container Apps / AKS / App Service，不能只切域名。必须重新配置 Managed Identity、Key Vault 权限、环境变量、持久化、数据库/Redis 网络、Runtime callback 地址。
 ## 9. 登录、设备、模型列表问题排查
 之前遇到过用户登录成功但设备看不到、模型列表拿不到的问题。排查顺序：
 1. Manager 是否有该用户记录。
 2. JWT/session 是否能通过 Manager 校验。
 3. 设备注册/心跳是否入库。
 4. 用户是否绑定 NewAPI channel/group/token。
 5. NewAPI 返回是否 401/403/模型列表为空。
 6. Mac/Windows 客户端请求是否走同一 base_url、同一加密/签名逻辑。
 不要只看“客户端显示已登录”，已登录不代表模型、设备、NewAPI 绑定都完整。
 ## 10. 网页端 Manager 已做过的重点
 已处理过的方向包括：
 - 注册页国内邮箱提示。
 - Manager 登录后菜单跳转问题。
 - 任务总览 / deployments 页面部分英文文案中文化。
 - 普通 sub 控制面、部署草稿、运行状态、timeline、events、logs、artifacts 展示。
 - artifact content 获取链路文档。
 - Azure Key Vault secret_ref 接入方向。
 - PayPal 充值和 NewAPI 模型费用关系说明文档。
 继续改网页端时必须真实点击验证，尤其是：
 - 登录后左侧菜单。
 - 模型、渠道、供应商、支付、部署、任务总览。
 - 创建新运行弹窗/抽屉。
 - 产物卡片和下载入口。
 ## 11. 部署和 git 规则
 生产部署原则：
 ```text
 本地修改
 -> git commit
 -> git push 到 heicode-mananger main
 -> VM 上 git pull
 -> docker compose ... up -d --build
 -> sudo docker image prune -f
 -> 真实接口/页面冒烟
 ```
 注意：
 - 不要用 `scp` 传整份源码到 VM。
 - `HeiCode-issues.git` 已废弃，后续不用再更新。
 - VM 构建后必须清理 Docker 镜像，避免磁盘被旧层占满。
 - 不要提交 `.env`、密钥、token、数据库连接串。
 ## 12. 新 AI 接手建议顺序
 1. 读 `AGENTS.md` 和 `heicode/AGENTS.md`。
 2. 读 `docs/deployment/Heicode-Manager-生产配置与账号交接清单.md`。
 3. 用 `git status` 确认是否有未提交变更，不要动无关文件。
 4. 区分当前任务是普通 sub、蜂群、网页端、NewAPI、Azure 还是桌面客户端。
 5. 先用接口确认真实状态，再下结论。
 6. 涉及生产前先确认是否需要部署，部署后必须真实冒烟。
 7. 涉及密码、token、连接串时只写配置名和获取位置，不写明文。
 ## 13. 已踩过的典型坑
 | 坑 | 正确处理 |
 |----|----------|
 | 把普通 sub 和蜂群混在一起 | 两套模式、两套配置、两套联调清单 |
 | artifact 摘要当完整交付 | 必须通过 content 接口拿完整产物 |
 | Runtime 返回 completed 就算成功 | 还要看 usage、artifact、日志、是否失败摘要 |
 | Key Vault health 报错只改代码 | 先查 Managed Identity 和 Vault 权限 |
 | NewAPI 一个模型失败就判 Manager 错 | 查 Runtime 请求路径、模型名、request id、上游状态 |
 | VM 上有 postgres/redis 容器就当生产库 | 以 `SQL_DSN`、`REDIS_CONN_STRING` 和 Azure 托管服务为准 |
 | 修改网页后不点击验证 | 必须真实打开页面、点菜单、点按钮 |
 | 把密钥写入 md 方便交接 | 只能写配置名、用途、位置，不能写明文 |
 ## 14. 当前后续重点
 | 方向 | 后续任务 |
 |------|----------|
 | 普通 sub | 持续和桌面客户端联调真实开发任务，确认 artifact content 是完整业务产物 |
 | 蜂群 | 如需启用，先配置 `SWARM_RUNTIME_*`，单独跑蜂群 E2E |
 | Key Vault | 修复 Managed Identity / `AZURE_CLIENT_ID` / Key Vault 权限 |
 | NewAPI | 保持 Runtime 回传 `newapi_request_id`、usage、成本信息 |
 | 网页端 | 继续中文化、交互完善、真实点击测试 |
 | 生产部署 | 每次部署后检查 `/api/status`、登录、deployments、Runtime health |
@@ -1,183 +0,0 @@
 # Heicode Manager 统一改造落地计划（Manager 侧）
 > 版本：v0.1（初稿）
 > 日期：2026-06-01
 > 负责范围：仅 `heicode-mananger`（Manager 控制面 + `web/default` 前端）
 > 性质：内部落地计划，随实现推进持续更新。不代表对外承诺。
 > **状态更新（2026-06-01）：`agnet → agent` 已按"强制全量、不留兼容"完成。**
 > 后端 Go（路由 `/api/agent/*`、env `AGENT_*`、结构体/函数/文件名）、前端（`agent-console`/`agent-hub`、`/api/agent` 调用、i18n）、DB（表 `agent_*`、列 `agent_id`，并加幂等迁移 `renameAgnetTablesToAgent` 保住老数据）、文档、compose/.env、脚本均已统一为 `agent`。
 > `go build ./...` 与 `go test ./controller ./model ./router ./middleware` 全绿；前端 `tsc -b` 通过。
 > 本文 §3 原描述的"保留 `agnet` 兼容别名/线缆令牌"策略已**作废**——实际采用一次性硬切。唯一保留 `agnet` 字样的是 `model/main.go` 的迁移源表名（迁移所必需）。
 > **部署待办**：① VM `.env` 的 `AGNET_*` 改名 `AGENT_*`；② 启动时迁移自动 rename 老表（已就绪）；③ 其他三仓库（agent_management / HeiCode-Swarm / 客户端）需同步切到 `/api/agent` 与新 env，否则跨服务对接在它们切换前会中断（按你的要求强制先行）。
 ## 0. 基准文档
 本计划是以下两份的 **Manager 侧拆解执行版**，结论以原文为准：
 | 来源 | 位置 | 作用 |
 |---|---|---|
 | 统一调用方案 v0.1 | gitee `taijibaga/heicodedebug` → `2026-06-01_heicode客户端相关定义.md` | 四仓库总纲：接口归口、模式拆分、状态裁决、产物、回调 |
 | 全链路代码评审报告 | gitee `taijibaga/heicodedebug` → `2026-06-01_Heicode全链路代码评审报告.md` | P1–P7 问题与证据 |
 | 桌面 sub 对接文档 | `docs/integration/heicode-desktop-sub-agile-api.md` | 现行普通 sub 契约 |
 四仓库分工（总纲 §4）：客户端只调 Manager；**Manager 是唯一接口入口 + Runtime 路由器 + 唯一状态裁判**；`agent_management` 执行 Sub Agile；`HeiCode-Swarm` 执行 Swarm。
 ## 1. 贯穿全局的原则（来自总纲）
 1. `agnet` 是历史拼写错误，统一为 `agent`；旧接口兼容期只做转发。
 2. Sub Agile 与 Swarm 是两套运行时，**不再复用 `/api/swarms` 表达两种模式**，按 `mode` 路由。
 3. Runtime 只上报**结构化事实**；Manager 据结构化字段裁决 `display_status`；客户端只消费结论，**不再用正则自判产物**。
 4. 安全红线：只传 `azkv://` 等 `secret_ref`，禁明文密钥；高危操作 Manager 先审批再下发。
 ## 2. 已完成（分支 `fix/manager-deliverable-and-secret-validation`，commit `12602eb`，已推送）
 | 项 | 文件 | 内容 | 对应总纲 |
 |---|---|---|---|
 | P2 交付物判定 | `controller/agnet_runtime_client.go` | `runtimeArtifactsAreSummaryOnly` 改读结构化 `artifact_type`+文件信号，弃脆弱正则 | §10.6 |
 | P6a secret_ref 校验 | `controller/resource.go` | Resource CRUD 强制 `azkv://` | §16/§17.6 |
 | P6b 值级密钥扫描 | `controller/resource.go`、`controller/agnet_control_plane.go` | `containsPlaintextSecret`/`containsSensitiveGrantField` 扫字符串值（sk-/JWT/PEM） | §16 |
 | P5 默认模型收敛 | `controller/agnet_role_template.go`、`controller/agnet_task_bridge.go` | 单一来源 `defaultAgnetModelID()`（env `AGNET_DEFAULT_MODEL_ID`，默认 `gpt-5.4`）；移除 `agnet-model-<role>` 占位回退 | §9 |
 | P3 状态枚举 | `docs/integration/heicode-desktop-sub-agile-api.md` | 补 `completed` 终态 + runtime_state 镜像 + 未知值兜底 | §10.4 |
 | 单测 | `controller/agnet_deliverable_secret_test.go` | 覆盖以上行为 | — |
 > 注：`defaultAgnetModelID` 在后续命名统一中应改名 `defaultAgentModelID`，env 改 `AGENT_DEFAULT_MODEL_ID`（保留 `AGNET_*` 回退）。
 ## 3. 命名统一 `agnet → agent`
 ### 3.1 爆炸半径（仅本仓库，不含另三仓库与跨团队契约）
 **2155 处 / 63 文件**（`rg -i agnet`）。按「客户端/其他服务是否依赖」分类：
 | 类别 | 规模 | 对外可见 | 处理策略 | 风险 |
 |---|---|---|---|---|
 | HTTP 路由 `/api/agnet/*` | 路由表 | ✅ 客户端+Runtime | 新增 `/api/agent/*` 别名，旧保留转发 | 🔴 |
 | JSON 字段 | 仅 `agnet_id`（3 处，含 DB 列） | ✅ resource grant 契约 | 响应 dual-emit `agent_id`，请求 dual-accept | 🟠 |
 | env 变量 `AGNET_*` | compose + 代码读取 | ✅ 部署配置 | 代码先读 `AGENT_*` 回退 `AGNET_*` | 🟠 |
 | DB 表 `agnet_*` / `agnet_id` 列 | ~6 表 | ❌ 内部 | **用 GORM `TableName()` 钉住物理名不动**，物理改名作为最后单独迁移 | 🔴 |
 | Go 内部标识（`AgnetXxx`、函数、文件名 `agnet_*.go`） | ~1800 | ❌ 编译期可查 | 纯重构，分模块小步改 | 🟢 |
 | 前端（`agnet-console/`、组件、i18n key） | ~250 | ❌ 内部（调的是路由） | 重构，随路由切换 | 🟢 |
 | 文档 | 多处 | — | 新文档写 `agent`，`agnet` 标 deprecated | 🟢 |
 ### 3.2 兼容期规则（总纲 §19）
 1. 旧接口只做转发。2. 新文档只写新接口。3. 新客户端只调新接口。4. Manager 内部存储统一 `agent` 命名。5. 日志可记 legacy route，不展示给普通用户。
 ## 4. 路由拆分与归口（总纲 §5）
 ### 4.1 客户端 → Manager（新增）
 ```
 /api/heicode/capabilities
 /api/heicode/sub-agile/tasks/...     （或统一 /api/heicode/tasks + body.mode）
 /api/heicode/swarm/tasks/...
 ```
 ### 4.2 Manager → Runtime（新增，按 mode 分流）
 ```
 /api/agent/sub-agile/deployments  -> agent_management   (AGENT_RUNTIME_* / 现 AGNET_RUNTIME_*)
 /api/agent/swarm/deployments      -> HeiCode-Swarm       (SWARM_RUNTIME_*)
 ```
 Manager 已具备双 env 前缀分流机制（`agnetRuntimeClientConfigForMode`）；蜂群侧配置就绪只差 `SWARM_RUNTIME_SERVICE_TOKEN`。
 ### 4.3 回调（新增 + 旧转发）
 ```
 新：POST /api/agent/callbacks/runtime-events
 旧：POST /api/agnet/callbacks/swarm-events   （兼容转发到同一 handler）
 ```
 ## 5. 状态裁决：Manager 成为唯一裁判（总纲 §10，关联评审 P1）
 ### 5.1 三层状态 + display_status
 - `client_task_status`（客户端本地）/ `cloud_deployment_status`（Manager）/ `runtime_execution_status`（Runtime）
 - Manager 输出唯一 `display_status` 给客户端。
 ### 5.2 Runtime 必须上报的结构化交付物事实（契约）
 ```json
 "deliverable": {
  "has_deliverable": true,
  "summary_only": false,
  "artifact_ids": ["art_xxx"],
  "files_modified": ["src/app.ts"],
  "has_diff": true,
  "commit_sha": ""
 }
 ```
 ### 5.3 Manager 裁决规则
 | Runtime 事实 | display_status |
 |---|---|
 | `completed` + has_deliverable + !summary_only | `completed` |
 | `completed` + summary_only / 无 artifact | `completed_without_deliverable` 或 `needs_codegen` |
 | `failed` | `failed` / `stopped` / `waiting_approval` 同名透传 |
 ### 5.4 Manager 落点
 - `controller/agnet_callback.go`（`applyAgnetCallbackDeploymentState` 消费 `deliverable`，算 verdict）
 - `model/agnet_deployment.go`（加 `DeliveryVerdict` / display_status 列，三库兼容 `varchar`）
 - `controller/agnet_control_plane.go`（detail/timeline 暴露字段）
 - 复用已就绪的 `artifactIsSummaryOnly`（P2）+ usage
 - **阶段化**：先加派生字段不改 `status`（向后兼容）→ 客户端跟进后再引入新终态值。
 ## 6. 模型策略（总纲 §9）
 - Sub Agile：`per_role` / `default`；Swarm：`primary`。
 - 单一来源默认模型（P5 已起步，待改名 `defaultAgentModelID`）。
 - Manager 校验：模型存在 / 套餐允许 / 角色允许 / 预算 / Runtime 支持。
 ## 7. 项目文件夹产物 `project_folder`（总纲 §12）—— 中期大件
 - artifact 升为两级：`Project Artifact` → `File Artifacts / Directory Entries`。
 - 新 artifact_type：`project_folder` / `project_archive`（现有 `code_patch/document/...` 保留）。
 - 新增接口：`.../artifacts/{id}/manifest`、`.../files/{path}`、`.../archive`。
 - **本地修改回传 + revision 协议**（§12.7）：`local-edits` / `batch` / 冲突 `ARTIFACT_REVISION_CONFLICT` / Manager 维护 current accepted revision。
 - 影响：新 model（artifact revision / project entries）、新 controller、content 代理扩展。**工程量大，单独立项。**
 ## 8. 云部署生命周期（总纲 §18）—— 远期
 `project_folder` → 选 target(Azure/阿里云/AWS) → Manager 校验/审批/凭证/预算 → Deploy Worker/Runtime 执行 → `deployment_manifest` artifact 回传。**远期，本轮不展开。**
 ## 9. 安全与审计（总纲 §16/§17）
 | 项 | 现状 | 待办 |
 |---|---|---|
 | `secret_ref` 强制 `azkv://` | ✅ agnet 路径 + Resource CRUD（P6a） | 覆盖其余写入路径 |
 | 值级密钥扫描 | ✅ P6b | — |
 | 高危操作 Manager gate | ❌ 现为立即 `accepted`，阻断依赖 Runtime | Manager 侧加 risk_level/pending 审批 gate（关联 P1/§17.1） |
 | 短期凭证 lease 真派生 | ❌ 占位（只发 `lease://`，不 mint） | 接 Key Vault 派生短期凭证 |
 | revoke 同步 Runtime | ⚠️ approve 有 sync，revoke 无 | 补 revoke→Runtime 通知 |
 | 审计 fail-closed | ⚠️ best-effort | 关键审计改 fail-closed 或告警 |
 | 客户端禁 inline secret_ref | — | Manager 改为接受 `resource_binding_id`，内部映射 secret_ref（§17.6） |
 ## 10. 落地阶段（总纲 §20，Manager 承担）
 | 阶段 | Manager 任务 | 自主性 | 依赖 | 状态 |
 |---|---|---|---|---|
 | **1 接口/命名** | `/api/agent/*` 别名、`/api/heicode/{sub-agile,swarm}/*`、callback 新路由、`AGENT_*` env 回退、`agnet_id`→`agent_id` 双字段 | ✅ 加法自主 | — | 待开始 |
 | **2 模式路由** | 按 `mode` 路由两套 `*_RUNTIME_*` | ✅ | 蜂群 token | 机制已就绪 |
 | **3 模型策略** | per_role/primary 校验 | ✅ | — | P5 起步 |
 | **4 状态/产物裁决** | display_status + deliverable 字段 + project_folder + revision | 🟡 | Runtime 发结构化事实 | P1/P2 起步 |
 | **5 日志/回调/调试** | user_logs/debug_logs 分层 + diagnostics + 统一 callback | ✅ | Runtime callback 切换 | diagnostics 已有雏形 |
 ## 11. 跨团队依赖（Manager 做不了，需协调）
 1. **agent_management / HeiCode-Swarm**：上报结构化 `deliverable` 事实；接入 `/api/agent/{sub-agile,swarm}/*` 路由；callback 切 `/api/agent/callbacks/runtime-events`；产出真实 `project_folder`。
 2. **蜂群 Runtime**：`SWARM_RUNTIME_SERVICE_TOKEN` 安全配置 + 修复 single-agent fallback（评审 P7）。
 3. **客户端（macOS/Windows）**：切新接口、消费 display_status、project 文件树展示、本地 edit 上传、禁 mock/直连（§17）。
 ## 12. 风险与红线
 - **`agnet` 是 load-bearing**（路由/env/DB/跨服务契约）——**严禁全局 sed**，必须加法别名 + 兼容期。
 - DB 物理表/列名暂不改，用 `TableName()` 钉住，避免迁移风险。
 - 跨服务契约字段改动一律 **dual-emit + dual-accept**，且需与调用方协调切换节奏。
 - 状态裁决先加字段不覆盖 `status`，避免误伤「真完成但 Runtime 未回 artifact」的任务。
 ## 13. 待确认事项
 1. 统一方案仍是 **v0.1**，落地前需与作者对齐版本/范围。
 2. approval decision 回传路径：`/api/agent/{mode}/deployments/{id}/approvals/{approval_id}` 的最终形态。
 3. 客户端→Manager 路由用「分模式」还是「统一 `/api/heicode/tasks` + body.mode」。
 4. `needs_codegen` 与 `completed_without_deliverable` 的判定边界（何时用哪个）。
 5. project_folder / 云部署的优先级与排期（是否本阶段做）。
 ---
 *维护：本文件随实现进度更新；每完成一项在「已完成/状态」列标注 commit。*
@@ -1,413 +0,0 @@
 # Heicode Manager 可独立执行任务计划
 更新时间：2026-05-30
 负责人范围：Heicode Manager 端  
 用途：后续开发按本文逐项执行、验收和更新状态。
 ## 一、核查结论
 本文只列 Manager 端能独立完成的任务。判断标准是：不要求 Heicode 客户端新增功能、不要求蜂群 / Agent Runtime 提供真实接口、不要求 AKS / NATS / Prometheus 等基础设施先上线。
 | 结论 | 说明 |
 |---|---|
 | 可以独立做 | Manager 自己的 DB 模型、Go API、前端页面、权限校验、回调接收骨架、artifact 数据模型、幂等、模拟事件和文档口径 |
 | 不能独立做 | 真实 `swarm_id`、worker claim / heartbeat、真实 handoff / retry、真实 Runtime 日志指标、客户端审批弹窗、短期凭证注入 runtime、SK 工具真实调用结果 |
 | 当前最大问题 | Manager 本地闭环已基本形成；剩余主要是等待真实 Runtime/客户端产生数据后联调验证 |
 ## 二、排除项
 以下任务不放入 Manager 独立开发计划，避免把外部依赖误报为 Manager 可完成。
 | 事项 | 排除原因 | 需要谁配合 |
 |---|---|---|
 | 真实创建 Swarm Run 并返回 `swarm_id` | 需要蜂群平台提供 `POST /api/swarms` 或等价生产接口 | 蜂群 / Agent Runtime |
 | 子 Agent claim、heartbeat、release、timeout | 需要 worker runtime 和任务池 | 蜂群 / Agent Runtime |
 | handoff、retry、blocked 的真实状态机 | 需要 Runtime 产生任务事件 | 蜂群 / Agent Runtime |
 | 真实日志流和 CPU/内存/耗时指标 | 需要日志/指标源 | 蜂群 / 基础设施 |
 | 客户端高危审批主弹窗 | 产品要求审批主体验在客户端 | Heicode 客户端 |
 | 短期凭证真实注入子 Agent | 需要受控 runtime、身份和网络通道 | 蜂群 / 基础设施 |
 | SK 工具真实调用结果 | 需要 SK 平台或 Runtime 上报 invocation event | 蜂群 / SK 平台 |
 | 交付结果回到客户端 | 需要客户端展示和 Runtime artifact 输出 | 客户端 + 蜂群 |
 ## 三、执行顺序总览
 | 顺序 | 任务 | 优先级 | 是否 Manager 独立 | 完成后价值 |
 |---:|---|---|---|---|
 | 1 | 增加 sub 模式字段 | P0 | 是 | 已完成：明确任务组织方式，支撑瀑布/敏捷状态展示 |
 | 2 | 打通 HeicodeTask 到 Agent deployment 的 Manager 桥接 | P0 | 是 | 已完成：任务可生成 deployment draft |
 | 3 | 增加用户态 Agent deployment API | P0 | 是 | 已完成：普通用户可以在自己资源范围内创建/查看/停止 deployment |
 | 4 | 统一 `/api/swarms` 与 `/api/agent/deployments` 边界 | P0 | 是 | 已完成：为后续蜂群联调留稳定 adapter |
 | 5 | 建 callback 接收端骨架 | P0 | 是 | 已完成：先接住事件、artifact、审批请求、timeline |
 | 6 | 建 artifact 数据模型和 API | P0 | 是 | 已完成：交付物/产物摘要落库并可展示 |
 | 7 | 增加回调幂等和签名/服务身份校验骨架 | P1 | 是 | 已完成：重复回调不重复写入，支持 token/HMAC |
 | 8 | 持久化 SK snapshot | P1 | 是 | 已完成：容器重启后任务上下文和审计不丢 |
 | 9 | 任务视角审计聚合 | P1 | 是 | 已完成：按 deployment 聚合 audit/callback/artifact/SK |
 | 10 | 本地模拟蜂群事件冒烟入口 | P1 | 是 | 已完成：默认模拟 task/blocked/retry/handoff/artifact/approval/timeline |
 | 11 | 前端页面补齐独立闭环展示 | P1 | 是 | 已完成：展示任务流、deployment、事件、artifact、审批和审计关系 |
 | 12 | 文档口径清理 | P2 | 是 | 已完成：当前口径以 Azure Key Vault / secret_ref 为准 |
 | 13 | AWS/GCP 占位提示 | P2 | 是 | 已完成：避免用户误以为 AWS/GCP 已可用 |
 | 14 | 请求 body 加密策略确认 | P2 | 是 | 已完成：桌面端 sub POST 复用模型调用 V2 body 加密 |
 | 15 | Runtime 状态诊断与兜底产物识别 | P1 | 是 | 已完成：Manager 可独立查询 Runtime 状态，页面明确区分普通 sub / 蜂群，并提示兜底摘要不是最终交付物 |
 | 16 | Artifact 完整内容代理下载 | P1 | 是 | 已完成：Manager 校验用户和 artifact 后，通过 Runtime content 接口代理下载完整产物 |
 ## 四、任务明细
 ### 任务 1：增加 sub 模式字段
 | 项 | 内容 |
 |---|---|
 | 目标 | Manager 能记录任务或部署计划采用 `waterfall` / `agile` 哪种组织方式 |
 | 修改文件 | `heicode/model/agent_deployment.go`、`heicode/controller/agent_control_plane.go`、`heicode/web/default/src/features/agent-console/api.ts`、`heicode/web/default/src/features/agent-console/create-agent-deployment-sheet.tsx` |
 | 建议字段 | `sub_mode`，枚举：`waterfall`、`agile`，默认 `agile` |
 | 验收 | 创建 deployment 后 DB、API response、前端详情都能看到 `sub_mode` |
 | 测试 | `go test ./controller -run 'TestAgent.*SubMode|TestAgentDeployment'`；`cd web/default && bun run typecheck` |
 验收标准：
 - 不允许写成自由文本。
 - 旧数据无字段时默认按 `agile` 展示。
 - 不能把 `sub_mode` 当成蜂群 Runtime 流程，只表示 Heicode 任务组织方式。
 ### 任务 2：HeicodeTask 到 Agent deployment 桥接
 | 项 | 内容 |
 |---|---|
 | 目标 | Manager 能从 HeicodeTask 的任务卡生成本地 Agent deployment payload |
 | 修改文件 | `heicode/controller/agent_control_plane.go`、新增 `heicode/controller/agent_task_bridge.go`、`heicode/web/default/src/lib/heicode-mcp.ts`、`heicode/web/default/src/features/tasks/task-card-view.tsx` |
 | 新增 API | `POST /api/agent/tasks/:task_id/deployment-draft` 或等价 user-scoped endpoint |
 | 输入 | task id、sub_mode、预算、资源范围、角色模板 |
 | 输出 | deployment draft 或创建后的 `deployment_id` |
 | 测试 | 新增 controller 单测；前端 typecheck |
 验收标准：
 - 任务能关联 `deployment_id` 或返回可提交的 deployment draft。
 - draft 中不能包含明文密钥，只能出现 `secret_ref`。
 - 找不到 task 或资源授权不足时返回明确错误。
 ### 任务 3：用户态 Agent deployment API
 | 项 | 内容 |
 |---|---|
 | 目标 | 普通用户可以创建、查询、停止自己资源范围内的 deployment |
 | 修改文件 | `heicode/router/api-router.go`、`heicode/controller/agent_control_plane.go`、`heicode/controller/agent_control_plane_test.go` |
 | 当前问题 | `/api/agent/deployments` 走 `AdminAuth` |
 | 新增建议 | 保留 admin route；新增 user route：`/api/agent/user/deployments` 或在同一路由中按 user scope 限制 |
 | 测试 | 普通用户创建成功；越权查询别人 deployment 失败；停止别人 deployment 失败 |
 验收标准：
 - 用户只能看到自己的 deployment。
 - `user_context.user_id` 为空时用登录用户 id 填充。
 - 请求体伪造别人 `user_context.user_id` 必须被覆盖或拒绝。
 - resource grant 必须属于当前用户。
 ### 任务 4：统一 `/api/swarms` 与 `/api/agent/deployments` 边界
 | 项 | 内容 |
 |---|---|
 | 目标 | Manager 内部形成生产蜂群接口 adapter，不再让调用方混淆两个口径 |
 | 修改文件 | 新增 `heicode/controller/agent_swarm_adapter.go` 或 `heicode/service/agent_swarm_adapter.go`，更新 `docs/integration/agent-platform-request-contract.md` |
 | 当前现实 | 本地已有 `/api/agent/deployments`，蜂群资料包目标接口是 `/api/swarms` |
 | 独立做法 | 先实现 Manager 内部 adapter 和统一 DTO，真实外呼先留配置开关，默认走本地 control-plane |
 | 测试 | adapter 单测验证 payload 字段、`secret_ref`、correlation_id、sub_mode |
 验收标准：
 - 文档明确本地 control-plane 与生产 Runtime 的关系。
 - 未来切换真实蜂群平台时，不需要重写前端页面。
 - adapter 默认不外呼，避免误触发不存在的生产 Runtime。
 ### 任务 5：callback 接收端骨架
 | 项 | 内容 |
 |---|---|
 | 目标 | Manager 先具备接收蜂群平台回调的 API 和落库能力 |
 | 修改文件 | `heicode/model/agent_callback.go`、`heicode/controller/agent_callback.go`、`heicode/router/api-router.go` |
 | 新增接口 | `POST /api/agent/callbacks/swarm-events` |
 | 独立能力 | 本地模拟 payload 可保存、去重、查询；已补普通 sub 任务事件 schema 校验 |
 | 测试 | controller 单测覆盖正常保存、重复 event_id 幂等、明文密钥拒绝、handoff 缺字段拒绝 |
 验收标准：
 - 请求体不得出现 token/password/private_key/access_key/connection_string 明文字段。
 - 每个回调都有 `event_id` 或 `idempotency_key`。
 - 重复回调返回成功但不重复写入。
 - `task.*` / `handoff.*` 关键事件缺少必填字段时返回 `CALLBACK_SCHEMA_INVALID`。
 ### 任务 6：artifact 数据模型和 API
 | 项 | 内容 |
 |---|---|
 | 目标 | Manager 保存和展示 artifact 摘要，不等 Runtime 真实输出 |
 | 修改文件 | 新增 `heicode/model/agent_artifact.go`、`heicode/controller/agent_artifact.go`、`heicode/web/default/src/features/agent-console/api.ts`、`heicode/web/default/src/features/agent-console/pages.tsx` |
 | 字段 | `artifact_id`、`deployment_id`、`task_id`、`correlation_id`、`artifact_type`、`title`、`summary`、`uri`、`checksum`、`metadata_json`、`created_at` |
 | 测试 | model/controller 单测；前端 typecheck |
 验收标准：
 - artifact 只保存摘要和引用，不保存大文件正文。
 - `uri` 支持 `artifact://`、`git://`、`azblob://`、`https://`，但页面只展示安全摘要。
 - 能按 `deployment_id` 查询 artifact 列表。
 ### 任务 7：回调幂等和服务身份校验骨架
 | 项 | 内容 |
 |---|---|
 | 目标 | 生产联调前先有幂等和认证形状 |
 | 修改文件 | `heicode/controller/agent_callback.go`、新增 `heicode/middleware/agent_callback_auth.go` |
 | 机制 | `X-Request-Id`、`X-Correlation-Id`、`Idempotency-Key`、可选 `X-Agent-Signature` |
 | 当前阶段 | 可以先用配置开关和本地测试 token，不接真实 Key Vault service token |
 | 测试 | 缺少服务 token 时拒绝；重复 key 不重复写入 |
 验收标准：
 - 开发环境可配置跳过严格签名，但生产默认要求服务身份。
 - 日志不打印 token 或签名原文。
 - 幂等冲突能返回已有记录摘要。
 ### 任务 8：持久化 SK snapshot
 | 项 | 内容 |
 |---|---|
 | 目标 | 替换当前 `agentSnapshots` 内存 map |
 | 修改文件 | 新增 `heicode/model/agent_sk_snapshot.go`，修改 `heicode/controller/agent_control_plane.go` |
 | 当前问题 | 容器重启后 `/sk-snapshots` 丢失 |
 | 测试 | 创建 snapshot 后清空内存，再从 DB 查询仍存在 |
 验收标准：
 - `deployment_id`、`snapshot_id` 有索引。
 - 查询按创建时间倒序或稳定顺序返回。
 - 不保存 SK 内容正文，只保存来源和版本引用。
 ### 任务 9：任务视角审计聚合
 | 项 | 内容 |
 |---|---|
 | 目标 | 按 task/deployment/correlation_id 聚合 Manager 已有记录 |
 | 修改文件 | `heicode/controller/agent_control_plane.go`、`heicode/model/agent_audit.go`、`heicode/web/default/src/features/agent-console/pages.tsx` |
 | 聚合内容 | deployment、audit events、approvals、leases、artifacts、callbacks、resource grants |
 | 新增接口 | `GET /api/agent/tasks/:task_id/timeline` 或 `GET /api/agent/deployments/:id/timeline` |
 | 测试 | 同一 correlation_id 下能聚合多类事件 |
 验收标准：
 - 缺少某类数据时返回空数组，不报错。
 - 时间线按时间排序。
 - 敏感字段统一脱敏。
 ### 任务 10：本地模拟蜂群事件冒烟入口
 | 项 | 内容 |
 |---|---|
 | 目标 | 在蜂群 Runtime 未接入前，Manager 能用模拟事件自测完整链路 |
 | 修改文件 | `heicode/controller/agent_callback.go`、`heicode/router/api-router.go`、可选新增 `heicode/controller/agent_smoke.go` |
 | 接口建议 | admin-only `POST /api/agent/dev/simulate-run` |
 | 生成内容 | deployment accepted、task.created、task.claimed、task.heartbeat、task.blocked、handoff.requested、handoff.completed、task.retried、task.completed、artifact.created、approval.requested、timeline.updated |
 | 测试 | 单测验证模拟后 timeline/artifacts/audit 可查；`scripts/agent_sub_mode_smoke.py` 可跑生产健康和 deployment timeline 冒烟 |
 验收标准：
 - 该接口必须 admin-only 或 dev-only。
 - 响应明确 `simulated: true`。
 - 线上页面不能把模拟事件显示成真实 Runtime 事件。
 - task/blocked/retry/handoff 事件能在 timeline 中看到，来源标记为 `simulated`。
 ### 任务 11：前端页面补齐独立闭环展示
 | 项 | 内容 |
 |---|---|
 | 目标 | 用户能看到 Manager 自己可提供的闭环信息 |
 | 修改文件 | `heicode/web/default/src/features/agent-console/pages.tsx`、`api.ts`、必要时新增组件 |
 | 展示内容 | sub_mode、deployment 来源 task、callbacks、artifacts、timeline、SK snapshots 持久化状态 |
 | 测试 | `cd heicode/web/default && bun run typecheck`；本地页面点击冒烟 |
 验收标准：
 - 页面明确区分 `control-plane placeholder`、`simulated`、`runtime` 来源。
 - 没有 artifact/callback 时有空态。
 - 文案不宣称真实蜂群已完成。
 ### 任务 12：文档口径清理
 | 项 | 内容 |
 |---|---|
 | 目标 | 清理旧 Vault/OpenBao/Secret Provider 误导表述 |
 | 修改文件 | `docs/heicode.md`、`docs/plan.md`、`docs/heicode-manager-sub-swarm-progress-checklist.md` |
 | 规则 | 用户侧叫“密钥保管器”，当前实现侧写 Azure Key Vault |
 | 验收 | `rg -n "OpenBao|HashiCorp Vault|Secret Provider" docs` 后剩余内容必须是历史说明或明确非当前实现 |
 验收标准：
 - 不把 Azure Key Vault 写成普通用户要进入的后台。
 - 不删除历史架构背景时，必须标注“历史/非当前实现”。
 ### 任务 13：AWS/GCP 占位提示
 | 项 | 内容 |
 |---|---|
 | 目标 | 避免用户误以为 AWS/GCP 已完成 |
 | 修改文件 | 资源绑定相关前端页面、`heicode/controller/resource.go` 如需补充状态字段 |
 | 当前现实 | Azure 已有第一阶段发现，AWS/GCP 未实现 |
 | 验收 | UI 明确显示 AWS/GCP “即将支持”或禁用状态 |
 验收标准：
 - 禁用项不能提交到后端创建真实资源发现。
 - 已有 Azure 流程不受影响。
 ### 任务 14：请求 body 加密策略确认
 | 项 | 内容 |
 |---|---|
 | 目标 | 桌面客户端调用 Manager 的 sub 流程接口时，支持与模型调用一致的 V2 应用层 body 加密；浏览器后台页面继续兼容普通 HTTPS JSON |
 | 修改文件 | `docs/integration/heicode-desktop-sub-agile-api.md`、`docs/heicode-runtime-auth-newapi-secret-design.md`、必要时补充 `heicode/middleware` 或客户端 SDK 加解密模块 |
 | 当前现实 | `/api/agent/user/*` 与 `/api/heicode-auth/*` 已支持 `Content-Encoding: heicode-aead-v1`；Manager 会先解密并校验设备签名，再把明文 JSON 交给业务处理或代理给上游 |
 | 安全红线 | 请求体、回调、日志、artifact metadata、timeline 中禁止出现明文密码、Token、私钥、连接串、云 access key、模型 key；长期凭证只传 `secret_ref` |
 | 后续判断 | 桌面客户端需要在 sub 流程调用中复用模型调用的 encryptedFetch/V2 签名能力；服务端保留未加密 JSON 只用于 Manager Web 控制台兼容 |
 | 测试 | 单测覆盖 V2 malformed 请求拒绝、普通代理请求兼容；生产需用真实已配对设备发起加密 sub 请求冒烟 |
 验收标准：
 - 文档明确桌面端优先走 V2 应用层 body 加密，且保留浏览器后台未加密 JSON 兼容。
 - 客户端对接文档明确禁止传明文长期凭据，只允许 `secret_ref` / `lease://...` / 资源元数据。
 - 服务端日志不打印请求 body 中的敏感字段。
 - V2 加密失败时返回 `X-Heicode-Auth-Error` 和 `X-Heicode-Server-Time`，便于客户端排障。
 ### 任务 15：Runtime 状态诊断与兜底产物识别
 | 项 | 内容 |
 |---|---|
 | 目标 | Manager 不依赖客户端或 Runtime 改接口，也能把“callback 已到”和“Runtime/Agent 是否真的产出交付物”分开展示 |
 | 修改文件 | `heicode/controller/agent_runtime_client.go`、`heicode/router/api-router.go`、`heicode/web/default/src/features/agent-console/api.ts`、`heicode/web/default/src/features/agent-console/pages.tsx` |
 | 新增 API | `GET /api/agent/user/deployments/:deployment_id/runtime-diagnostics` |
 | 诊断来源 | 用 deployment 记录里的 `runtime_swarm_id` / `runtime_deployment_id` 查询 Runtime status；默认路径 `/api/swarms/{swarm_id}/status`，可用 `AGENT_RUNTIME_STATUS_PATH` / `SWARM_RUNTIME_STATUS_PATH` 配置 |
 | 普通 sub / 蜂群边界 | 返回 `runtime_mode`，页面分别显示“普通 sub 模式”或“蜂群模式”，不把二者合并成一个流程 |
 | 已识别异常 | Runtime agent failed、completed 但存在 failed agents、只有 `Runtime execution summary` 兜底产物、模型 token 用量为 0、Runtime 状态查询失败 |
 | 测试 | `go test ./controller -run TestAgentRuntimeDiagnosticsWarnsOnCompletedRuntimeWithFailedAgents -count=1`；前端 `bun run build:check` |
 验收标准：
 - 诊断接口只读，不改 deployment 状态，不伪造 artifact。
 - 页面中的兜底摘要必须明确提示“不是最终业务交付物”。
 - 普通 sub 与蜂群模式必须通过 `runtime_mode` 区分展示。
 - Runtime 状态查不到时返回可读 warning，不能影响 Manager 已落库 callback/timeline/artifact 查询。
 ### 任务 16：Artifact 完整内容代理下载
 | 项 | 内容 |
 |---|---|
 | 目标 | 对齐 Agent Manager v2.1.10 的产物获取流程：Manager / 前端先查 artifact 列表，再通过用户态 content 代理接口获取完整文件 |
 | 修改文件 | `heicode/model/agent_artifact.go`、`heicode/controller/agent_callback.go`、`heicode/controller/agent_runtime_client.go`、`heicode/router/api-router.go`、`heicode/web/default/src/features/agent-console/pages.tsx` |
 | 新增 API | `GET /api/agent/user/deployments/:deployment_id/artifacts/:artifact_id/content` |
 | Runtime 目标路径 | 默认 `GET /api/swarms/{swarm_id}/artifacts/{artifact_id}/content`，可用 `AGENT_RUNTIME_ARTIFACT_CONTENT_PATH` / `SWARM_RUNTIME_ARTIFACT_CONTENT_PATH` 配置 |
 | 安全边界 | Manager 先校验当前用户拥有 deployment，再校验 artifact 属于该 deployment；不暴露 Azure Blob 凭据、SAS URL 或 Runtime 内网信息 |
 | 测试 | `go test ./controller -run TestAgentArtifactContentProxiesRuntimeContent -count=1` |
 验收标准：
 - 不能直接用用户传入的 URI 下载，必须以 Manager 已落库 artifact 为准。
 - 响应透传 Runtime 的文件正文、`Content-Type` 和 `Content-Disposition`。
 - Runtime 未配置或 content 拉取失败时返回明确业务错误。
 - 页面 artifact 卡片提供“下载产物”，但兜底摘要仍需标记为非最终业务交付物。
 ## 五、推荐执行批次
 ### 批次 A：最小 Manager 闭环
 | 顺序 | 任务 |
 |---:|---|
 | 1 | sub 模式字段 |
 | 2 | 用户态 Agent deployment API |
 | 3 | HeicodeTask 到 deployment 桥接 |
 | 4 | 本地模拟蜂群事件冒烟入口 |
 完成批次 A 后，Manager 应能做到：普通用户从任务卡发起一个本地 deployment，并通过模拟事件看到任务进展，不依赖真实 Runtime。
 ### 批次 B：生产联调准备
 | 顺序 | 任务 |
 |---:|---|
 | 1 | `/api/swarms` 与 `/api/agent/deployments` adapter |
 | 2 | callback 接收端骨架 |
 | 3 | artifact 数据模型和 API |
 | 4 | 回调幂等和服务身份校验骨架 |
 完成批次 B 后，Manager 应能接收蜂群平台未来回调，并能用模拟 payload 证明幂等、落库、查询和脱敏正确。
 ### 批次 C：可观测与收尾
 | 顺序 | 任务 |
 |---:|---|
 | 1 | SK snapshot 持久化 |
 | 2 | 任务视角审计聚合 |
 | 3 | 前端闭环展示 |
 | 4 | 文档口径清理 |
 | 5 | AWS/GCP 占位提示 |
 | 6 | 请求 body 加密策略确认 |
 | 7 | Runtime 状态诊断与兜底产物识别 |
 | 8 | Artifact 完整内容代理下载 |
 完成批次 C 后，Manager 端应具备清晰的任务视角、持久化上下文、准确页面口径和更少误导。
 ## 六、统一自测命令
 每个批次完成后至少执行：
 ```bash
 cd /Users/gongzhiyong/go/heicode-mananger/heicode
 go test ./controller ./model
 ```
 前端有改动时执行：
 ```bash
 cd /Users/gongzhiyong/go/heicode-mananger/heicode/web/default
 bun run typecheck
 bun run build
 ```
 文档有改动时执行：
 ```bash
 cd /Users/gongzhiyong/go/heicode-mananger
 git diff --check -- docs
 ```
 如果涉及生产部署，必须再按：
 ```bash
 cd /Users/gongzhiyong/go/heicode-mananger
 sed -n '1,220p' docs/deployment/azure-production-deploy-guardrails.md
 ```
 ## 七、完成定义
 Manager 独立任务完成，不等于蜂群生产闭环完成。本文完成的定义是：
 | 条件 | 标准 |
 |---|---|
 | 普通用户路径 | 非管理员用户可以基于自己的任务和资源创建/查看/停止本地 deployment |
 | 任务关联 | HeicodeTask 能关联 deployment 或 deployment draft |
 | sub 模式 | `waterfall` / `agile` 在 DB、API、UI 可追踪 |
 | 回调骨架 | 事件、artifact、approval-request、usage、status 可模拟回调落库 |
 | artifact | artifact 摘要可保存、查询、展示 |
 | 幂等 | 重复回调不重复写入 |
 | 审计 | task/deployment/correlation_id 下能聚合审计、审批、artifact、callback |
 | 安全 | API、日志、页面不出现明文长期密钥 |
 | 请求加密 | 桌面端 sub 请求支持与模型调用一致的 V2 body 加密；浏览器后台普通 JSON 兼容路径不受影响 |
 | Runtime 诊断 | Manager 页面能显示 Runtime 真实状态来源、失败 Agent、兜底产物和普通 sub / 蜂群模式归属 |
 | Artifact 内容 | Manager 用户态接口能代理下载 Runtime 保存的完整 artifact 内容，且不暴露存储凭据 |
 | 口径 | 页面和文档不把本地占位/模拟事件说成真实 Runtime |
 ## 八、执行时不能突破的边界
 1. 不在 Manager 中保存长期明文密钥。
 2. 不让普通用户看到 CodeGW 管理后台能力。
 3. 不把 Manager 做成网页编码主体验。
 4. 不把 `sub_mode` 解释成蜂群 Runtime 固定流程。
 5. 不把本地模拟事件当真实蜂群完成证据。
 6. 不把 Azure Key Vault 暴露成普通用户要直接操作的后台。
 7. 不绕过客户端高危审批的产品边界；Manager 只能先提供记录和 API。
 8. 不破坏 V2 body 加密的版本字段、诊断头、重放保护和未加密 Web 控制台兼容路径，避免客户端和 Manager 联调不可排障。
@@ -1,144 +0,0 @@
 # 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 回传 | 保存长期明文密钥，直接暴露给普通用户，或自行决定用户账本扣费 |
 ## 二、目标调用链
 ```text
 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 |
@@ -1,112 +0,0 @@
 # 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` 默认链路也能写入 task、blocked、retry、handoff、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/agent/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 | Manager 已可接收并展示普通 task flow callback；没有独立 task graph 状态表 | 部分满足 | 真实任务图仍需要 Runtime 产出 task/agent 事件 | 蜂群 |
 | 展示 handoff、blocked、retry | 已补 `task.*` / `handoff.*` schema 校验和页面任务流展示 | 基本满足接收和展示 | 真实数据仍需要 Runtime 持续回调 | 蜂群 |
 | 高危审批请求进入 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 可接收/展示 task flow callback；缺真实 Runtime 数据 | 蜂群侧定义并回调 `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 展示 | Manager 已有 schema 校验、模拟事件和页面任务流展示 | 用真实 Runtime callback 做生产联调验证 |
 | 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：完善项
 | 缺失项 | 当前状态 | 处理建议 |
 |---|---|---|
 | 蜂群验收脚本 | 已新增 `scripts/agent_sub_mode_smoke.py`，可检查生产 Manager、Agent health 和指定 deployment timeline | 后续按真实 Runtime deployment 固化执行参数 |
 | 页面术语统一 | 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 | 根据真实联调结果更新本文状态 | 把缺失项从“缺接口/未联调”改为“已验证/阻塞/延期” |
@@ -1,677 +0,0 @@
 # Agent Manager 蜂群 Runtime 接口实现要求
 更新时间：2026-05-28
 面向对象：Agent Manager / HeiCode-Swarm Runtime 开发负责人
 用途：Agent Manager 按本文实现接口、字段和回调后，Heicode Manager 可直接联调蜂群模式。
 ## 1. 结论
 Heicode Manager 已负责控制面和记录面：
 - 生成 deployment / swarm 创建请求。
 - 传递 `resource_grants`、`secret_ref`、预算、模型网关上下文和 callback 地址。
 - 保存 `deployment_id <-> runtime_deployment_id <-> swarm_id` 映射。
 - 接收 Runtime callback，落库 artifact / approval / timeline / audit。
 - 用户 approve/reject 后，把审批决定回传 Runtime。
 Agent Manager / Swarm Runtime 需要负责执行层：
 - 创建真实 Swarm Run。
 - 生成真实 task graph。
 - 管理 Agent claim / heartbeat / handoff / retry / blocked / failed 状态机。
 - 真实执行任务并产出 artifact。
 - 在高危动作前暂停并回调审批请求。
 - 接收审批结果后继续或停止。
 - 回传日志、指标、用量和最终结果。
 ### 1.1 2026-05-28 生产联调实测结论
 使用测试用户 `zsbgnw@gmail.com`（Manager 用户 `chenchen`，`user_id=22`）在生产 Manager 上实测蜂群入口。
 当前生产 Manager Runtime 配置实际为：
 ```text
 AGENT_RUNTIME_BASE_URL=http://20.212.121.126
 AGENT_RUNTIME_CREATE_PATH=/api/agent/deployments
 AGENT_RUNTIME_STOP_PATH=/api/agent/deployments/{deployment_id}/stop
 ```
 实测结果：
 | 项 | 结果 |
 |---|---|
 | `GET /api/agent/runtime/health` | 通过，远端 Agent Manager IP healthy |
 | `POST /api/swarms` 使用 `agent_runtime.platform=agent-swarm` | 失败，Manager 返回 `agent_runtime.platform must be agent when runtime context is present` |
 | `POST /api/swarms` 使用 `agent_runtime.platform=agent` | 通过 |
 | Manager deployment | `dep_72cdc138b9c8` |
 | Manager 返回 swarm_id | `dep_72cdc138b9c8`，当前是 Manager 本地 deployment id |
 | Runtime deployment | `dep_77370f27186f` |
 | Manager events | `deployment.accepted`、`runtime.sync.started`、`runtime.sync.accepted` |
 | Manager stop | 通过 |
 | Runtime stop | 通过，Agent Manager 侧 `dep_77370f27186f` 状态为 `stopped` |
 | Runtime callback | 未观察到，生产 Manager callback 表 0 条对应记录 |
 | artifact / timeline callback | 未产出 |
 | SK / usage callback | 未产出 |
 | Runtime logs | 仅 `Pod ... has no logs yet` |
 | Runtime metrics | 返回固定 CPU/内存/网络汇总，看起来仍是占位值 |
 结论：
 1. Heicode Manager 的 `/api/swarms` adapter 能接收用户态蜂群请求，并能通过当前 Runtime bridge 调 Agent Manager IP。
 2. 当前生产链路实际走的是 Agent Manager `/api/agent/deployments`，不是 Agent Manager `/api/swarms`。
 3. Manager stop 可以传递到 Agent Manager deployment stop。
 4. 当前还没有真实蜂群 Runtime callback、task graph、artifact、SK、usage。
 5. Agent Manager 如果要满足正式蜂群模式，仍需实现本文后续定义的 `/api/swarms`、`/api/swarms/{swarm_id}`、`/api/swarms/{swarm_id}/stop`、callback 和 usage 约束。
 ## 2. 总体调用链
 ```text
 Heicode Desktop Client
  -> Heicode Manager
     POST /api/swarms 或 /api/agent/user/deployments
  -> Agent Manager / Swarm Runtime
     POST /api/swarms
  <- Runtime response
     runtime_deployment_id / swarm_id / status
  <- Runtime callback
     POST /api/agent/callbacks/swarm-events
  -> Runtime approval decision
     POST /api/swarms/{swarm_id}/approvals/{approval_id}
 ```
 客户端到 Heicode Manager 的 `POST /api/swarms` 与普通 sub 用户态接口一样，必须支持 V2 body 加密：
 ```http
 Content-Encoding: heicode-aead-v1
 X-Heicode-Device-Id: <device_id>
 X-Heicode-Timestamp: <unix_ms>
 X-Heicode-Nonce: <nonce_hex>
 X-Heicode-Fingerprint: <device_fingerprint>
 X-Heicode-Eph-Pubkey: <base64_x25519_ephemeral_pubkey>
 X-Heicode-Signature: <base64_ed25519_signature>
 Content-Type: application/json
 ```
 未加密 Web 控制台请求仍按 Manager session cookie + `New-Api-User` 兼容处理。Manager 调 Agent Manager / Swarm Runtime 的服务间请求不使用该客户端 body 加密协议，而使用 `Authorization: Bearer <service_token>` 和公共追踪 Header。
 ## 3. Agent Manager 必须提供的接口
 | 优先级 | 方法 | 路径 | 必须 | 用途 |
 |---|---|---|---:|---|
 | P0 | `GET` | `/api/agent/health` | 是 | 健康检查 |
 | P0 | `POST` | `/api/swarms` | 是 | 创建真实 Swarm Run |
 | P0 | `POST` | `/api/swarms/{swarm_id}/stop` | 是 | 停止 Swarm Run |
 | P0 | `POST` | `/api/swarms/{swarm_id}/approvals/{approval_id}` | 是 | 接收 Manager 审批决定 |
 | P0 | callback | Manager `/api/agent/callbacks/swarm-events` | 是 | 回写状态、task、handoff、artifact、approval |
 | P1 | `GET` | `/api/swarms/{swarm_id}` | 建议 | 查询 Runtime 详情 |
 | P1 | `GET` | `/api/swarms/{swarm_id}/tasks` | 建议 | 查询 task graph |
 | P1 | `GET` | `/api/swarms/{swarm_id}/logs` | 建议 | 查询日志 |
 | P1 | `GET` | `/api/swarms/{swarm_id}/metrics` | 建议 | 查询指标 |
 如果短期无法提供 `/api/swarms`，可以临时确认兼容路径，例如 `/tasks`。但这只能作为联调过渡，不作为最终生产契约。
 ## 4. 认证与公共 Header
 Manager 调 Agent Manager 时携带：
 ```http
 Authorization: Bearer <service_token>
 X-User-ID: <manager_user_id>
 X-Binding-Scope: <binding_scope>
 X-Correlation-ID: <correlation_id>
 X-Idempotency-Key: manager-<manager_deployment_id>
 Content-Type: application/json
 ```
 要求：
 1. `Authorization` 用于服务间鉴权。
 2. `X-Correlation-ID` 必须贯穿 create、callback、approval decision、logs、metrics。
 3. `X-Idempotency-Key` 必须支持幂等；重复创建请求不能生成多个真实 Swarm Run。
 4. Agent Manager 不得要求 Manager 传长期明文密钥。
 ## 5. `GET /api/agent/health`
 ### 响应
 ```json
 {
  "success": true,
  "data": {
    "status": "healthy",
    "service": "agent-manager-swarm-runtime",
    "version": "1.0.0",
    "runtime": "aks",
    "time": "2026-05-28T10:00:00Z"
  }
 }
 ```
 验收：
 - HTTP 200。
 - `status` 为 `healthy` / `ok` / `up` 之一。
 - 不返回密钥、Token、连接串。
 ## 6. `POST /api/swarms`
 ### 请求体
 ```json
 {
  "orchestration_plan": {
    "intent_id": "task_123",
    "template_hint": "heicode-task",
    "objective": "完成本轮用户目标",
    "sub_mode": "agile",
    "risk_level": "medium",
    "budget": {
      "max_tokens": 120000,
      "max_cost_usd": 8,
      "max_duration_sec": 3600
    },
    "user_context": {
      "user_id": "22",
      "channel_id": "heicode",
      "binding_scope": "task-task-123"
    },
    "billing_context": {
      "provider": "newapi",
      "default_model_id": "model_xxx",
      "allowed_model_ids": ["model_xxx"],
      "secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/model-gateway-key"
    },
    "agile_context": {
      "iteration": "2026-05-28",
      "stage": "development",
      "checkpoint": "draft_created",
      "acceptance_criteria": [
        "接口返回成功",
        "artifact 可回写到 timeline",
        "不出现明文密钥"
      ],
      "next_action": "continue",
      "requires_user_approval": false
    },
    "agents": [
      {
        "role_template": "backend",
        "goal": "完成后端实现和测试",
        "default_model_id": "model_xxx",
        "resource_grants": []
      }
    ],
    "resource_grants": []
  },
  "agents": [
    {
      "role": "backend",
      "resource_grants": []
    }
  ],
  "resource_grants": [
    {
      "grant_id": "grant-task-123-git",
      "resource_id": "repo-main",
      "resource_type": "git",
      "permission_scope": ["repo:read", "repo:write:feature-branches"],
      "secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/repo-main",
      "ref": "azkv://heicode-kv.vault.azure.net/secrets/repo-main",
      "target_role": "backend",
      "constraints": {
        "allowed_paths": "heicode/**"
      },
      "metadata": {
        "repo": "heicode-manager"
      }
    }
  ],
  "callback": {
    "url": "https://code.xinghanlab.com/api/agent/callbacks/swarm-events",
    "signing_secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/agent-callback-signing-key",
    "subscribed_events": [
      "deployment.status_changed",
      "task.created",
      "task.claimed",
      "task.heartbeat",
      "task.blocked",
      "task.retried",
      "task.failed",
      "task.completed",
      "handoff.requested",
      "handoff.completed",
      "approval.requested",
      "artifact.created",
      "timeline.updated",
      "budget.alert"
    ]
  },
  "metadata": {
    "manager_deployment_id": "dep_xxx",
    "heicode_deployment_id": "dep_xxx",
    "heicode_runtime_bridge": true,
    "correlation_id": "corr_xxx"
  }
 }
 ```
 ### Agent Manager 必须消费的字段
 | 字段 | 必须 | 说明 |
 |---|---:|---|
 | `orchestration_plan.objective` | 是 | 用户目标 |
 | `orchestration_plan.sub_mode` | 是 | `agile` / `waterfall`；蜂群执行时也要保留此组织方式 |
 | `orchestration_plan.risk_level` | 是 | 高危动作必须走审批 |
 | `orchestration_plan.budget` | 是 | token / cost / duration 上限 |
 | `billing_context.provider` | 是 | 当前为 `newapi` |
 | `billing_context.secret_ref` | 是 | 模型网关密钥引用，只能是 `azkv://...` |
 | `agents[].role` 或 `role_template` | 是 | 子 Agent 角色 |
 | `resource_grants[]` | 是 | 资源授权清单 |
 | `resource_grants[].secret_ref` | 凭据资源必填 | 只允许 Key Vault 引用，不允许明文 |
 | `callback.url` | 是 | Runtime 回调 Manager 的地址 |
 | `callback.signing_secret_ref` | 建议 | HMAC 签名密钥引用 |
 | `metadata.manager_deployment_id` | 是 | Manager 侧 deployment id |
 | `metadata.correlation_id` | 是 | 全链路追踪 |
 ### 响应
 ```json
 {
  "success": true,
  "data": {
    "deployment_id": "runtime-dep-123",
    "swarm_id": "swarm-123",
    "status": "running",
    "created_at": "2026-05-28T10:00:00Z",
    "estimated_ready_at": "2026-05-28T10:02:00Z"
  }
 }
 ```
 兼容响应：
 ```json
 {
  "deployment_id": "runtime-dep-123",
  "swarm_id": "swarm-123",
  "status": "running"
 }
 ```
 Manager 映射规则：
 | Agent Manager 返回字段 | Manager 保存字段 |
 |---|---|
 | `data.deployment_id` / `deployment_id` / `id` | `runtime_deployment_id` |
 | `data.swarm_id` / `swarm_id` / `runtime_swarm_id` | `runtime_swarm_id` |
 | `data.status` / `status` / `runtime_status` | `runtime_state` |
 ## 7. Runtime 必须生成的 task graph
 Agent Manager 创建 Swarm Run 后，必须在 Runtime 内部生成任务图，并通过 callback 回写。
 每个 task 至少包含：
 ```json
 {
  "task_id": "task-backend-1",
  "title": "实现后端接口",
  "description": "完成 API、校验和测试",
  "agent_role": "backend",
  "status": "pending",
  "depends_on": ["task-design-1"],
  "attempt": 1
 }
 ```
 状态建议：
 | status | 说明 |
 |---|---|
 | `pending` | 等待执行 |
 | `claimed` | 已被 Agent 领取 |
 | `running` | 执行中 |
 | `blocked` | 阻塞 |
 | `handoff_requested` | 等待交接 |
 | `retrying` | 重试中 |
 | `completed` | 完成 |
 | `failed` | 失败 |
 ## 8. Runtime 回调 Manager
 Manager 回调地址：
 ```http
 POST https://code.xinghanlab.com/api/agent/callbacks/swarm-events
 X-Agent-Service-Token: <callback_token>
 X-Agent-Event-Id: <event_id>
 X-Correlation-ID: <correlation_id>
 Content-Type: application/json
 ```
 也支持 HMAC：
 ```http
 X-Agent-Timestamp: <unix_ms>
 X-Agent-Signature: sha256=<hex>
 ```
 HMAC 签名内容：
 ```text
 timestamp + "." + event_id + "." + raw_body
 ```
 联调前可拉取 Manager 当前接受的事件 schema：
 ```http
 GET https://code.xinghanlab.com/api/agent/callbacks/swarm-events/schema
 ```
 ### 通用 callback envelope
 ```json
 {
  "event_id": "evt_123",
  "idempotency_key": "evt_123",
  "event_type": "task.claimed",
  "deployment_id": "dep_xxx",
  "swarm_id": "swarm-123",
  "agent_instance_id": "agent-backend-1",
  "task_id": "task-backend-1",
  "occurred_at": "2026-05-28T10:10:00Z",
  "correlation_id": "corr_xxx",
  "source": "agent-manager-runtime",
  "payload": {}
 }
 ```
 要求：
 1. `event_id` 全局唯一。
 2. 重试同一事件必须复用相同 `event_id` 或 `idempotency_key`。
 3. `deployment_id` 优先使用 Manager deployment id。
 4. 如果只知道 `swarm_id`，Manager 也会按 `runtime_swarm_id` 查找 deployment。
 5. `source` 要能区分真实 Runtime，例如 `agent-manager-runtime`，不要写 `simulated`。
 ## 9. 必须回调的事件和字段
 | event_type | 必填字段 | 说明 |
 |---|---|---|
 | `deployment.status_changed` | `payload.status` | Runtime 整体状态变化 |
 | `task.created` | `task_id`, `payload.title` | 任务图新增任务 |
 | `task.claimed` | `task_id`, `payload.agent_role` | Agent 领取任务 |
 | `task.running` | `task_id`, `payload.agent_role` | Agent 开始执行 |
 | `task.heartbeat` | `task_id`, `payload.agent_role` | Agent 心跳 |
 | `task.blocked` | `task_id`, `payload.reason` | 任务阻塞 |
 | `task.retried` | `task_id`, `payload.attempt` | 任务重试 |
 | `task.failed` | `task_id`, `payload.reason` | 任务失败 |
 | `task.completed` | `task_id` | 任务完成 |
 | `handoff.requested` | `task_id`, `payload.from_role`, `payload.to_role` | 请求交接 |
 | `handoff.completed` | `task_id`, `payload.from_role`, `payload.to_role` | 完成交接 |
 | `artifact.created` | `artifact.artifact_id` 或 `payload.artifact_id` | 产物生成 |
 | `approval.requested` | `payload.approval_id`, `payload.operation`, `payload.risk_level` | 高危审批 |
 | `timeline.updated` | `payload.title` | 用户可见时间线 |
 | `budget.alert` | `payload.threshold_pct` | 预算告警 |
 ## 10. artifact.created
 Runtime 产生中间产物或最终交付物时回调：
 ```json
 {
  "event_id": "evt_artifact_1",
  "event_type": "artifact.created",
  "deployment_id": "dep_xxx",
  "swarm_id": "swarm-123",
  "task_id": "task-backend-1",
  "source": "agent-manager-runtime",
  "artifact": {
    "artifact_id": "art_backend_patch_1",
    "artifact_type": "code_patch",
    "title": "Backend API patch",
    "summary": "新增任务创建和状态查询接口",
    "uri": "git://heicode-manager/branches/feature/task-api",
    "checksum": "sha256:abc123",
    "metadata": {
      "agent_role": "backend",
      "redacted": true
    }
  }
 }
 ```
 支持的 `artifact_type`：
 | 类型 | 说明 |
 |---|---|
 | `code_patch` | 代码补丁或分支 |
 | `document` | 文档 |
 | `test_report` | 测试报告 |
 | `deployment_manifest` | 部署清单 |
 | `log_bundle` | 日志包 |
 | `other` | 其他 |
 要求：
 1. 大文件不要内联到 callback body。
 2. `summary` 可展示给用户，不得包含密钥。
 3. `uri` 可以是 `git://`、`artifact://`、`azblob://`、`https://`。
 4. metadata 必须脱敏。
 ## 11. approval.requested 与审批结果
 高危动作前 Runtime 必须暂停，并回调：
 ```json
 {
  "event_id": "evt_approval_1",
  "event_type": "approval.requested",
  "deployment_id": "dep_xxx",
  "swarm_id": "swarm-123",
  "task_id": "task-deploy-1",
  "source": "agent-manager-runtime",
  "payload": {
    "approval_id": "runtime-approval-1",
    "operation": "deploy.production",
    "resource_id": "prod-env",
    "resource_type": "azure",
    "resource_scope": "resource-group/heicode-prod",
    "target_role": "ops",
    "risk_level": "high",
    "requires_credential": true,
    "secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/prod-deploy",
    "ttl_seconds": 600,
    "reason": "需要部署到生产环境"
  }
 }
 ```
 Manager / 客户端审批后，Manager 调 Runtime：
 ```http
 POST /api/swarms/{swarm_id}/approvals/{approval_id}
 Authorization: Bearer <service_token>
 X-Correlation-ID: <correlation_id>
 X-Idempotency-Key: approval-decision-<approval_id>-<decision>
 Content-Type: application/json
 ```
 请求：
 ```json
 {
  "approval_id": "runtime-approval-1",
  "decision": "approved",
  "reason": "用户已确认",
  "manager_deployment_id": "dep_xxx",
  "swarm_id": "swarm-123",
  "decided_by": "user:22",
  "decided_at": "2026-05-28T10:20:00Z",
  "credential_lease": {
    "lease_id": "lease_xxx",
    "credential_ref": "lease://runtime/runtime-approval-1",
    "expires_at": "2026-05-28T10:30:00Z"
  }
 }
 ```
 `decision` 枚举：
 | decision | Runtime 行为 |
 |---|---|
 | `approved` | 继续原高危动作 |
 | `rejected` | 停止该动作，回调 `timeline.updated` 或 `task.failed` |
 要求：
 1. Runtime 收到 `approved` 后才可以继续高危动作。
 2. Runtime 收到 `rejected` 后不能继续执行该动作。
 3. Runtime 不得把 `credential_ref` 展开写入日志或 artifact metadata。
 4. Runtime 必须把审批结果后的状态继续通过 callback 回写。
 ## 12. 日志、指标和用量
 ### 日志
 建议提供：
 ```http
 GET /api/swarms/{swarm_id}/logs?limit=100&cursor=<cursor>
 ```
 响应：
 ```json
 {
  "success": true,
  "data": {
    "items": [
      {
        "timestamp": "2026-05-28T10:21:00Z",
        "level": "info",
        "agent_role": "backend",
        "task_id": "task-backend-1",
        "message": "test completed",
        "redacted": true
      }
    ],
    "next_cursor": ""
  }
 }
 ```
 ### 指标
 建议提供：
 ```http
 GET /api/swarms/{swarm_id}/metrics?window=15m&step=60s
 ```
 响应：
 ```json
 {
  "success": true,
  "data": {
    "swarm_id": "swarm-123",
    "agent_metrics": [
      {
        "agent_instance_id": "agent-backend-1",
        "agent_role": "backend",
        "task_id": "task-backend-1",
        "status": "running",
        "cpu_percent": 12.5,
        "memory_bytes": 268435456,
        "uptime_seconds": 300
      }
    ]
  }
 }
 ```
 ### 用量
 Runtime 调模型时必须带关联字段：
 | 字段 | 说明 |
 |---|---|
 | `manager_deployment_id` | Manager deployment id |
 | `swarm_id` | Runtime swarm id |
 | `task_id` | 当前任务 |
 | `agent_role` | Agent 角色 |
 | `model_id` | 使用模型 |
 | `correlation_id` | 全链路追踪 |
 Runtime 可通过 `budget.alert` 或 `timeline.updated` 回传用量摘要。
 ## 13. 安全约束
 必须遵守：
 1. 禁止在请求、callback、日志、artifact metadata 中出现明文密码、Token、私钥、连接串、云 access key、模型 key。
 2. 长期凭据只能通过 `azkv://<vault>/secrets/<name>` 传引用。
 3. Runtime 可以把短期租约写成 `lease://...`，但不能写真实密钥。
 4. `secret_ref`、`credential_ref` 只能作为引用使用，不能在用户可见内容中展开。
 5. 所有 callback payload 必须脱敏。
 6. 高危动作必须先 `approval.requested`，不能先执行后补审批。
 ## 14. 错误码建议
 | HTTP | code | 场景 |
 |---:|---|---|
 | 401 | `UNAUTHORIZED` | service token 无效 |
 | 403 | `FORBIDDEN` | 权限不足 |
 | 404 | `SWARM_NOT_FOUND` | swarm 不存在 |
 | 409 | `IDEMPOTENCY_CONFLICT` | 幂等键冲突 |
 | 422 | `VALIDATION_ERROR` | 请求字段缺失 |
 | 422 | `SECRET_REF_INVALID` | `secret_ref` 非 `azkv://...` |
 | 422 | `POLICY_REJECTED` | 高危策略拒绝 |
 | 500 | `INTERNAL_ERROR` | Runtime 内部错误 |
 错误响应：
 ```json
 {
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "resource_grants[0].secret_ref is required",
    "request_id": "corr_xxx"
  }
 }
 ```
 ## 15. 联调验收清单
 | 步骤 | 操作 | 通过标准 |
 |---:|---|---|
 | 1 | Manager 调 `GET /api/agent/health` | 返回 healthy |
 | 2 | Manager 调 `POST /api/swarms` | 返回真实 `deployment_id` 和 `swarm_id` |
 | 3 | Runtime 回调 `deployment.status_changed` | Manager timeline 可见 |
 | 4 | Runtime 回调 `task.created` | Manager task flow / Agent task map 可见 |
 | 5 | Runtime 回调 `task.claimed` / `task.heartbeat` | Manager 可看到 Agent 领取和心跳 |
 | 6 | Runtime 回调 `handoff.requested` / `handoff.completed` | Manager 可看到交接 |
 | 7 | Runtime 回调 `artifact.created` | Manager artifact 列表可见 |
 | 8 | Runtime 回调 `approval.requested` | Manager approval 列表出现 pending |
 | 9 | 客户端 / Manager approve | Runtime 收到 decision 并继续 |
 | 10 | 客户端 / Manager reject | Runtime 收到 decision 并停止对应动作 |
 | 11 | Runtime 回传 logs / metrics / usage | Manager 可查询或 timeline 可见 |
 | 12 | Runtime 回调最终 `deployment.status_changed=completed` | Manager 和客户端看到完成 |
 ## 16. 当前不能误报完成的项
 以下项只有在 Agent Manager 真实实现并联调后才能算完成：
 1. 真实 Swarm Run 创建成功。
 2. 真实 task graph 生成。
 3. 真实 Agent claim / heartbeat。
 4. 真实 handoff / retry / blocked。
 5. 真实 artifact 产出。
 6. 审批后 Runtime 继续或停止。
 7. Runtime 真实日志和指标。
 8. 子 Agent 模型用量归属。
 9. 最终交付物回到客户端。
 Manager 本地模拟事件、测试桩、空态页面和 schema 校验只能证明 Manager 接收和展示能力，不能证明蜂群生产闭环完成。
@@ -1,491 +0,0 @@
 # Agent Manager 蜂群 Runtime 联调待确认与补充要求
 更新时间：2026-05-29  
 发给：Agent Manager / HeiCode-Swarm Runtime 负责人  
 范围：仅针对蜂群模式，不包含普通 sub 敏捷模式。
 ## 1. 先明确边界
 普通 sub 模式和蜂群模式是两套不同的运行时部署，不能混用。
 | 模式 | Runtime | 当前已知地址 | 说明 |
 |---|---|---|---|
 | 普通 sub 敏捷模式 | Agent Manager / Agent Runtime | `http://20.212.121.126` | 用于普通子 Agent 敏捷开发流程 |
 | 蜂群模式 | HeiCode-Swarm Orchestrator | `http://52.139.240.116:8000` | 用于蜂群任务图、Agent 协作、handoff、task graph |
 注意：两套服务可能都提供 `/api/swarms` 这类路径，但业务含义不同。Heicode Manager 后续需要按模式分别配置，不应只用一套 `AGENT_RUNTIME_BASE_URL` 混跑。
 ## 2. 本次读取到的蜂群 Runtime 新能力
 根据 HeiCode-Swarm 最新 `蜂群对接文档.md` 和代码，蜂群 Runtime 已经补充以下接口：
 | 能力 | 路径 | 当前判断 |
 |---|---|---|
 | 健康检查 | `GET /api/agent/health` | 已提供 |
 | 创建蜂群 run | `POST /api/swarms` | 已提供 |
 | 兼容创建入口 | `POST /api/agent/deployments` | 已提供 |
 | 查询 swarm 详情 | `GET /api/swarms/{swarm_id}` | 已提供 |
 | 查询任务图 | `GET /api/swarms/{swarm_id}/tasks` | 已提供 |
 | 查询日志 | `GET /api/swarms/{swarm_id}/logs` | 已提供 |
 | 查询指标 | `GET /api/swarms/{swarm_id}/metrics` | 已提供 |
 | 停止 swarm | `POST /api/swarms/{swarm_id}/stop` | 已提供 |
 | 审批结果回传 | `POST /api/swarms/{swarm_id}/approvals/{approval_id}` | 已提供 |
 | callback token / HMAC | Runtime callback Manager | 代码支持 |
 | `azkv://` 校验 | 请求体 secret 引用 | 代码支持 |
 | 幂等创建 | `X-Idempotency-Key` | 代码支持 |
 本地契约测试也已确认通过：
 ```text
 python3 scripts/test-runtime-contract.py
 runtime contract checks passed
 ```
 ## 3. 实测结果
 ### 3.1 健康检查通过
 请求：
 ```bash
 curl http://52.139.240.116:8000/api/agent/health
 ```
 返回核心内容：
 ```json
 {
  "success": true,
  "data": {
    "status": "healthy",
    "service": "heicode-swarm-runtime",
    "version": "1.0.0",
    "runtime": "aks",
    "capabilities": [
      "swarm.create",
      "task.flow",
      "handoff.events",
      "artifact.events",
      "approval.pause_resume",
      "deployment.stop",
      "runtime.tasks.query",
      "runtime.logs.query",
      "runtime.metrics.query"
    ]
  }
 }
 ```
 ### 3.2 创建接口鉴权已通过
 Agent Manager / 蜂群 Runtime 已提供当前部署认可的 Runtime Bearer token。使用该 token 后，`POST /api/swarms` 不再返回 401。
 ```bash
 curl -X POST http://52.139.240.116:8000/api/swarms \
  -H "Authorization: Bearer <runtime-service-token>" \
  -H "Content-Type: application/json" \
  -H "X-Correlation-Id: corr_token_check_local" \
  -H "X-Idempotency-Key: codex-swarm-token-check" \
  -d '<valid-swarm-create-body>'
 ```
 返回：
 ```json
 {
  "success": true,
  "data": {
    "deployment_id": "runtime-dep-e9ef617146fd",
    "runtime_deployment_id": "runtime-dep-e9ef617146fd",
    "manager_deployment_id": "dep_token_check_local",
    "swarm_id": "swarm-64004a6aaf67",
    "status": "running",
    "created": true
  }
 }
 ```
 结论：Runtime token 阻塞已解决。具体 token 不写入 Markdown 或 Git。
 ### 3.3 查询和停止接口已通过
 对 `swarm-64004a6aaf67` 查询结果：
 | 接口 | 结果 |
 |---|---|
 | `GET /api/swarms/{swarm_id}` | 成功，返回 Runtime run 详情 |
 | `GET /api/swarms/{swarm_id}/tasks` | 成功 |
 | `GET /api/swarms/{swarm_id}/logs` | 成功，返回 Runtime event 列表 |
 | `GET /api/swarms/{swarm_id}/metrics` | 成功，返回任务数、运行时长、Agent 数等轻量指标 |
 | `POST /api/swarms/{swarm_id}/stop` | 成功，状态变为 `stopped` |
 ### 3.4 新发现：线上蜂群 Runtime 仍只生成单任务
 2026-05-29 已按 `HeiCode-Swarm/蜂群对接文档.md` 的结构真实请求线上蜂群 Runtime：
 ```text
 POST http://52.139.240.116:8000/api/swarms
 Authorization: Bearer <runtime-service-token>
 ```
 第一组使用文档中的单 Agent 结构，`agents` 放在 `orchestration_plan.agents`，角色为 `backend`。创建成功：
 ```json
 {
  "success": true,
  "data": {
    "runtime_deployment_id": "runtime-dep-fc99510eb2c5",
    "manager_deployment_id": "dep_doc_single",
    "swarm_id": "swarm-004f1ae3a114",
    "status": "running"
  }
 }
 ```
 但查询任务后，线上 Runtime 没有保留文档请求中的 `backend` 角色，而是生成 `general` 单任务：
 ```json
 {
  "task_id": "swarm-004f1ae3a114-task-1",
  "title": "Swarm objective",
  "agent_role": "general",
  "context": {
    "workflow_mode": "single_agent",
    "allow_handoff": false
  }
 }
 ```
 第二组使用同样文档结构，但传入 3 个 agents：`planner`、`builder`、`reviewer`。创建成功：
 ```json
 {
  "success": true,
  "data": {
    "runtime_deployment_id": "runtime-dep-ba9de6fe1df3",
    "manager_deployment_id": "dep_doc_multi",
    "swarm_id": "swarm-ee319f1d4705",
    "status": "running"
  }
 }
 ```
 但查询任务后仍只生成 1 个 `general` 任务：
 ```json
 {
  "tasks": [
    {
      "title": "Swarm objective",
      "agent_role": "general",
      "status": "pending",
      "task_graph_id": "task-1",
      "context": {
        "workflow_mode": "single_agent",
        "allow_handoff": false
      }
    }
  ]
 }
 ```
 两组测试的日志均只出现 `Created 1 task(s)`，停止接口均返回 `status=stopped`。
 这与蜂群设计要求的“动态任务图、能力编队、handoff、协作任务链”仍有差距。当前线上 Runtime 看起来仍是 single-agent fallback 路径，尚未按请求中的 3 个 planner/builder/reviewer 任务生成真实 task graph。
 ### 3.5 Gitee main 与线上 Runtime 行为不一致
 已检查项目地址：
 ```text
 http://gitee.ath.cx:3000/taijibaga/HeiCode-Swarm
 ```
 当前 main commit：
 ```text
 802bbe97ca278d2da3c70a3e471219db62c01c98 对接文档
 ```
 仓库 main 中 `orchestrator/swarm_runtime.py` 的 `build_task_descriptions()` 逻辑会读取：
 ```python
 agents = plan.get("agents") or body.get("agents") or []
 ```
 如果请求里传入 3 个 agents，本地按同样 payload 测试该函数，结果会生成 3 个任务：
 ```text
 plan-1   planner
 build-1  builder
 verify-1 reviewer
 count=3
 ```
 但线上 `http://52.139.240.116:8000` 对同样结构只生成：
 ```text
 task-1 general
 workflow_mode=single_agent
 allow_handoff=false
 ```
 另外，线上返回中的 `workflow_mode`、`allow_handoff`、`required_capabilities`、`source=runtime_bridge` 等字段，在当前 Gitee main 的 `orchestrator/swarm_runtime.py` 中没有对应代码。
 因此当前判断是：
 1. 线上 `52.139.240.116:8000` 运行的镜像/代码不是 Gitee main 当前代码；或
 2. 线上部署使用了未提交到 Gitee main 的分支/镜像；或
 3. 线上通过环境变量或另一套 runtime bridge 强制走 single-agent fallback。
 请 Agent Manager / HeiCode-Swarm 负责人确认线上部署的镜像 tag、代码 commit、分支，以及是否启用了 single-agent fallback 配置。
 ## 4. Agent Manager / 蜂群 Runtime 需要提供或确认
 ### P0 必须先提供
 | 项 | 需要提供 / 确认 | 原因 |
 |---|---|---|
 | 蜂群 Runtime 调用 token | 已提供并验证可用；后续需要通过安全渠道配置到 Manager，不写入 Git | Manager 调 `POST /api/swarms` 需要 Bearer 鉴权 |
 | callback 凭据配置 | Runtime 配置 Manager 认可的 `AGENT_CALLBACK_SERVICE_TOKEN` 或 `AGENT_CALLBACK_SIGNING_SECRET` | Runtime 回调 Manager 必须通过鉴权 |
 | 两套部署边界 | 明确普通 sub 继续走 `20.212.121.126`，蜂群走 `52.139.240.116:8000` | 防止普通 sub 和蜂群混用 |
 | 创建响应字段 | `deployment_id`、`runtime_deployment_id`、`swarm_id`、`status` 字段保持稳定 | Manager 需要保存映射 |
 | callback deployment id 规则 | callback 中 `deployment_id` 应为 Manager deployment id，`runtime_deployment_id` 为 Runtime id，`swarm_id` 为 Runtime swarm id | Manager 根据这些字段落库和展示 |
 callback 地址：
 ```text
 https://code.xinghanlab.com/api/agent/callbacks/swarm-events
 ```
 callback schema 查询：
 ```text
 GET https://code.xinghanlab.com/api/agent/callbacks/swarm-events/schema
 ```
 说明：具体 token / signing secret 不应写入 Markdown 或 Git，请通过安全渠道提供。
 ### P0 端到端能力
 | 能力 | 当前情况 | 需要补充或证明 |
 |---|---|---|
 | Manager 创建蜂群 run | Runtime 直连创建已跑通；Manager 生产尚未切蜂群专用配置 | 将 Runtime token 安全配置到 Manager 后跑真实 Manager 创建 |
 | 动态任务图 | 当前线上 Runtime 只生成 1 个 `general` 任务，`workflow_mode=single_agent` | 至少根据目标生成 2-3 个可追踪任务，并回调多条 `task.created` |
 | Agent claim / running / heartbeat | 代码里有 dispatch 和事件能力 | 需要真实 Agent 连接、claim、running、heartbeat 证据 |
 | handoff | 事件类型和部分逻辑存在 | 需要真实 `handoff.requested` / `handoff.completed` 场景 |
 | 失败回流 | 有 `task.blocked`、`task.failed`、`task.retried` 事件类型 | 需要一次真实失败、重试或 blocked 证据 |
 | artifact | Agent 返回 `git_branch` 时会发 artifact | 需要真实 `artifact.created` 回 Manager，带 `uri`、`summary`、`artifact_type` |
 | 审批暂停 / 恢复 | high risk 会 `waiting_approval`，支持 decision 接口 | 需要真实 `approval.requested` -> Manager approve/reject -> Runtime 继续/阻塞 |
 | 日志 | `/logs` 当前主要来自 Runtime 事件 | 需要说明是否提供真实 Agent / Pod 日志，或至少返回可排障日志摘要 |
 | 指标 | `/metrics` 返回轻量聚合 | 需要补充真实运行时长、任务耗时、Agent 数、失败数、资源用量 |
 | 用量 / 成本 | 只有 Agent result 带 `usage` 时才回传 | 需要真实 NewAPI token、model_cost_usd、runtime_seconds 或明确暂无 |
 | callback 可靠性 | 当前代码 callback 失败记录 warning | 需要确认是否有重试、死信、人工重放；没有则列为未完成 |
 ## 5. 建议双方统一的蜂群创建请求
 Heicode Manager 调蜂群 Runtime：
 ```http
 POST http://52.139.240.116:8000/api/swarms
 Authorization: Bearer <runtime-service-token>
 X-User-ID: <manager-user-id>
 X-Binding-Scope: <binding-scope>
 X-Correlation-ID: <correlation-id>
 X-Idempotency-Key: manager-<manager-deployment-id>
 Content-Type: application/json
 ```
 请求体建议：
 ```json
 {
  "orchestration_plan": {
    "intent_id": "task_xxx",
    "objective": "完成本轮用户目标",
    "sub_mode": "goal_driven_swarm",
    "risk_level": "medium",
    "budget": {
      "duration_seconds": 3600,
      "token_limit": 20000,
      "max_cost_usd": 8
    },
    "user_context": {
      "user_id": "22",
      "channel_id": "heicode",
      "binding_scope": "task-task-xxx"
    },
    "agents": [
      {
        "task_id": "plan-1",
        "role": "planner",
        "title": "目标理解与任务生成",
        "description": "整理用户目标、资源约束和验收标准",
        "depends_on": []
      },
      {
        "task_id": "build-1",
        "role": "builder",
        "title": "代码或文档变更",
        "description": "根据目标生成可验证交付物",
        "depends_on": ["plan-1"]
      },
      {
        "task_id": "verify-1",
        "role": "reviewer",
        "title": "验证与交付整理",
        "description": "检查交付物并形成验收摘要",
        "depends_on": ["build-1"]
      }
    ]
  },
  "callback": {
    "url": "https://code.xinghanlab.com/api/agent/callbacks/swarm-events",
    "signing_secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/agent-callback-signing-key",
    "subscribed_events": [
      "deployment.status_changed",
      "task.created",
      "task.claimed",
      "task.running",
      "task.heartbeat",
      "task.blocked",
      "task.retried",
      "task.failed",
      "task.completed",
      "handoff.requested",
      "handoff.completed",
      "approval.requested",
      "artifact.created",
      "budget.alert",
      "timeline.updated"
    ]
  },
  "metadata": {
    "manager_deployment_id": "dep_xxx",
    "heicode_deployment_id": "dep_xxx",
    "correlation_id": "corr_xxx",
    "heicode_runtime_bridge": true,
    "runtime_mode": "swarm"
  },
  "billing_context": {
    "provider": "newapi",
    "default_model_id": "model_xxx",
    "allowed_model_ids": ["model_xxx"],
    "secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/model-gateway-key"
  },
  "resource_grants": [
    {
      "grant_id": "grant-task-git",
      "resource_id": "repo-main",
      "resource_type": "git",
      "permission_scope": ["repo:read", "repo:write:feature-branches"],
      "secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/repo-main",
      "ref": "azkv://heicode-kv.vault.azure.net/secrets/repo-main",
      "target_role": "builder"
    }
  ]
 }
 ```
 ## 6. Secret 引用格式需要统一
 Heicode Manager 当前正式约束建议使用：
 ```text
 azkv://<vault>/secrets/<name>
 ```
 例如：
 ```text
 azkv://heicode-kv.vault.azure.net/secrets/repo-main
 azkv://heicode-kv.vault.azure.net/secrets/model-gateway-key
 ```
 HeiCode-Swarm 文档中示例为：
 ```text
 azkv://heicode/git-write-token
 ```
 建议 Agent Manager / 蜂群 Runtime 确认是否可以接受标准 Key Vault 形式，并在示例文档中同步，避免后续联调时因为 `secret_ref` 格式不一致失败。
 ## 7. Manager 侧后续配置建议
 Heicode Manager 需要保留普通 sub 和蜂群两套 Runtime 配置。建议后续拆成：
 ```text
 # 普通 sub 敏捷模式
 AGENT_RUNTIME_BASE_URL=http://20.212.121.126
 AGENT_RUNTIME_CREATE_PATH=/api/swarms
 # 蜂群模式
 SWARM_RUNTIME_BASE_URL=http://52.139.240.116:8000
 SWARM_RUNTIME_CREATE_PATH=/api/swarms
 SWARM_RUNTIME_STOP_PATH=/api/swarms/{swarm_id}/stop
 SWARM_RUNTIME_APPROVAL_DECISION_PATH=/api/swarms/{swarm_id}/approvals/{approval_id}
 SWARM_RUNTIME_SERVICE_TOKEN=<runtime-service-token>
 ```
 如果短期 Manager 还只有一套 `AGENT_RUNTIME_*`，只能临时切换到蜂群 Runtime 做专项联调，不能同时代表普通 sub 和蜂群都在线。
 ## 8. 蜂群 MVP 验收口径
 根据蜂群设计文档和 Heicode 产品资料包，蜂群 MVP 不是“接口能创建一个 run”就完成。最小验收应至少满足：
 | 验收项 | 成功标准 |
 |---|---|
 | 创建 | Manager 调 `POST /api/swarms` 成功，Runtime 返回真实 `swarm_id` |
 | 任务图 | Runtime 至少生成 2 个可追踪任务，并可通过 `/tasks` 查询 |
 | Agent 执行 | 至少一个真实 Agent claim、running、completed |
 | 交接或失败回流 | 至少出现一次 handoff，或一次失败/blocked/retry 并可解释 |
 | artifact | 至少 1 个真实 artifact 回 Manager，可在 Manager 查询 |
 | 审批 | high risk 流程能 `approval.requested`，Manager approve/reject 后 Runtime 状态变化 |
 | 日志 | Manager 或 Runtime 能查到可排障日志，不只是空占位 |
 | 指标 | 能看到任务数、状态、耗时、Agent 数、失败数等真实指标 |
 | 用量 | 能回传 token、模型成本或明确当前未接真实模型成本 |
 | 安全 | 请求、callback、日志、artifact metadata 不出现明文长期密钥 |
 | 幂等 | 同一个 `X-Idempotency-Key` 重试不会创建重复 swarm |
 | 停止 | Manager stop 后 Runtime 状态为 `stopped`，不继续执行 |
 ## 9. 建议下一次联调步骤
 1. Heicode Manager 新增或临时配置蜂群 Runtime base URL 和 Runtime Bearer token。
 2. Agent Manager / 蜂群 Runtime 确认 callback token 或 HMAC secret 已和 Heicode Manager 生产端一致。
 3. 使用测试用户通过 Manager 创建蜂群 run。
 4. 验证 Manager 保存 `runtime_deployment_id` 和 `runtime_swarm_id`。
 5. 验证 Runtime 不再只生成 single-agent fallback，而是生成多任务 task graph。
 6. 验证 Runtime 主动 callback：
   - `deployment.status_changed`
   - `task.created`
   - `task.claimed`
   - `task.running`
   - `task.completed`
   - `artifact.created`
   - `timeline.updated`
 7. 验证查询：
   - `GET /api/swarms/{swarm_id}`
   - `GET /api/swarms/{swarm_id}/tasks`
   - `GET /api/swarms/{swarm_id}/logs`
   - `GET /api/swarms/{swarm_id}/metrics`
 8. 验证 high risk 审批：
   - Runtime 回调 `approval.requested`
   - Manager approve
   - Runtime 收到 decision 并继续
 9. 验证 stop：
   - Manager stop
   - Runtime stopped
   - 不再继续发 running/completed callback
 ## 10. 当前结论
 蜂群 Runtime 当前已经具备可联调的接口骨架和一部分运行时能力，但还没有完成 Heicode 产品设计要求的完整蜂群 MVP 生产验收。
 当前最优先阻塞项是：
 1. 将已验证可用的蜂群 Runtime Bearer token 通过安全渠道配置到 Heicode Manager。
 2. 确认 Runtime 回调 Manager 的 callback token 或 HMAC secret 已生效。
 3. 修正线上 Runtime 只生成 1 个 `general` 任务的问题，使其按目标生成真实多任务 task graph。
 4. 确认线上镜像/代码 commit 与 Gitee main 是否一致；如果不一致，需要先部署包含多任务 task graph 逻辑的版本。
 5. 跑通一次真实 Manager -> 蜂群 Runtime -> Manager callback 的端到端链路。
 6. 补齐真实 Agent 执行、handoff/失败回流、artifact、日志、指标、usage/cost 的生产证据。
@@ -1,403 +0,0 @@
 # Agent Manager / HeiCode-Swarm 蜂群对接改造请求
 更新时间：2026-05-27
 发起方：Heicode Manager  
 用途：给 Agent Manager / HeiCode-Swarm 侧确认需要补齐或对齐的生产接口，便于 Heicode 桌面客户端 -> Manager -> 蜂群 Runtime 跑完整蜂群流程。
 ## 一、当前 Manager 已准备好的能力
 | 能力 | Manager 状态 |
 |---|---|
 | 用户态创建 | `POST /api/agent/user/deployments`、`POST /api/swarms` 已可创建 Manager deployment |
 | Runtime 创建桥接 | 可通过 `AGENT_RUNTIME_BASE_URL` + `AGENT_RUNTIME_CREATE_PATH` 调用 Runtime |
 | Runtime 停止桥接 | 可通过 `AGENT_RUNTIME_STOP_PATH` 停止 Runtime deployment |
 | 回调接收 | `POST /api/agent/callbacks/swarm-events` 已支持事件、artifact、approval、timeline 回调 |
 | 回调安全 | 支持 `X-Agent-Service-Token` 或 `X-Agent-Signature` HMAC |
 | 幂等 | `event_id` / `idempotency_key` 去重 |
 | 审批结果回传 | 用户 approve/reject 后，Manager 可调用 Runtime approval decision 接口 |
 | 密钥边界 | Manager 只传 `secret_ref` / `credential_ref`，不传长期明文密钥 |
 ## 二、Runtime 需要提供的接口
 ### 1. 健康检查
 ```http
 GET /api/agent/health
 ```
 如果蜂群侧沿用现有 Orchestrator，也可以临时配置为：
 ```http
 GET /health
 ```
 响应建议：
 ```json
 {
  "success": true,
  "data": {
    "status": "healthy",
    "service": "heicode-swarm-runtime",
    "version": "x.y.z"
  }
 }
 ```
 ### 2. 创建 Swarm Run
 生产目标接口：
 ```http
 POST /api/swarms
 Authorization: Bearer <service_token>
 X-Correlation-ID: <correlation_id>
 X-Idempotency-Key: manager-<deployment_id>
 Content-Type: application/json
 ```
 Manager 当前也可兼容配置：
 ```text
 AGENT_RUNTIME_CREATE_PATH=/api/swarms
 ```
 请求核心字段：
 ```json
 {
  "orchestration_plan": {
    "sub_mode": "agile",
    "risk_level": "high",
    "user_context": {
      "user_id": "22",
      "channel_id": "heicode"
    },
    "billing_context": {
      "provider": "newapi",
      "default_model_id": "model_xxx",
      "allowed_model_ids": ["model_xxx"],
      "secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/model-gateway-key"
    },
    "agents": [],
    "resource_grants": []
  },
  "agents": [
    {
      "role": "backend",
      "resource_grants": []
    }
  ],
  "resource_grants": [
    {
      "grant_id": "grant-task-backend",
      "resource_type": "git",
      "permission_scope": ["read", "write"],
      "secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/repo-main"
    }
  ],
  "callback": {
    "url": "https://code.xinghanlab.com/api/agent/callbacks/swarm-events",
    "signing_secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/agent-callback-signing-key",
    "subscribed_events": [
      "deployment.status_changed",
      "task.created",
      "task.claimed",
      "task.heartbeat",
      "task.completed",
      "task.failed",
      "handoff.requested",
      "approval.requested",
      "artifact.created",
      "timeline.updated"
    ]
  },
  "metadata": {
    "manager_deployment_id": "dep_xxx",
    "heicode_runtime_bridge": true,
    "correlation_id": "corr_xxx"
  }
 }
 ```
 响应必须返回至少一个 Runtime 标识：
 ```json
 {
  "success": true,
  "data": {
    "deployment_id": "runtime-dep-123",
    "swarm_id": "swarm-123",
    "status": "created"
  }
 }
 ```
 兼容要求：
 1. `deployment_id` 可作为 Runtime deployment id。
 2. `swarm_id` 用于蜂群任务图、审批和事件关联。
 3. 如果 Runtime 只返回顶层 JSON，不包 `data`，Manager 也能解析。
 4. 不要要求 Manager 发送长期明文密钥。
 ### 3. 停止 Runtime Run
 默认路径：
 ```http
 POST /api/agent/deployments/{deployment_id}/stop
 Authorization: Bearer <service_token>
 Content-Type: application/json
 ```
 请求：
 ```json
 {
  "reason": "Heicode Manager requested stop",
  "manager_deployment_id": "dep_xxx"
 }
 ```
 响应：
 ```json
 {
  "success": true,
  "data": {
    "deployment_id": "runtime-dep-123",
    "swarm_id": "swarm-123",
    "status": "stopped"
  }
 }
 ```
 如果蜂群侧希望使用：
 ```http
 POST /api/swarms/{swarm_id}/stop
 ```
 则 Manager 可通过环境变量配置：
 ```text
 AGENT_RUNTIME_STOP_PATH=/api/swarms/{swarm_id}/stop
 ```
 ## 三、Runtime 回调 Manager
 统一回调入口：
 ```http
 POST https://code.xinghanlab.com/api/agent/callbacks/swarm-events
 X-Agent-Service-Token: <callback_token>
 X-Agent-Event-Id: <event_id>
 X-Correlation-ID: <correlation_id>
 Content-Type: application/json
 ```
 也支持 HMAC：
 ```http
 X-Agent-Timestamp: <unix_ms>
 X-Agent-Signature: sha256=<hex>
 ```
 签名内容：
 ```text
 timestamp + "." + event_id + "." + raw_body
 ```
 ### 通用事件 envelope
 ```json
 {
  "event_id": "evt_123",
  "idempotency_key": "evt_123",
  "event_type": "task.completed",
  "deployment_id": "dep_xxx",
  "swarm_id": "swarm-123",
  "agent_instance_id": "agent-backend-1",
  "task_id": "task-backend-1",
  "occurred_at": "2026-05-27T10:00:00Z",
  "correlation_id": "corr_xxx",
  "source": "heicode-swarm-runtime",
  "payload": {}
 }
 ```
 必须支持的事件类型：
 | event_type | 用途 |
 |---|---|
 | `deployment.status_changed` | Runtime 整体状态变化 |
 | `task.created` | 任务图新增任务 |
 | `task.claimed` | Agent claim 任务 |
 | `task.heartbeat` | Agent 执行心跳 |
 | `task.completed` | 任务完成 |
 | `task.failed` | 任务失败 |
 | `handoff.requested` | 任务交接 |
 | `handoff.completed` | 交接完成 |
 | `approval.requested` | 请求用户审批 |
 | `artifact.created` | 产物生成 |
 | `timeline.updated` | 用户可见时间线 |
 ### artifact 回调
 ```json
 {
  "event_id": "evt_artifact_1",
  "event_type": "artifact.created",
  "deployment_id": "dep_xxx",
  "swarm_id": "swarm-123",
  "task_id": "task-backend-1",
  "artifact": {
    "artifact_id": "art_backend_patch_1",
    "artifact_type": "code_patch",
    "title": "Backend patch",
    "summary": "完成后端接口修改",
    "uri": "git://repo#agent-backend-1-results",
    "checksum": "sha256:xxx",
    "metadata": {
      "commit_sha": "abc123",
      "branch": "agent-backend-1-results",
      "redacted": true
    }
  }
 }
 ```
 ### approval 请求回调
 ```json
 {
  "event_id": "evt_approval_1",
  "event_type": "approval.requested",
  "deployment_id": "dep_xxx",
  "swarm_id": "swarm-123",
  "task_id": "task-deploy-1",
  "payload": {
    "approval_id": "runtime-approval-1",
    "operation": "production_deploy",
    "resource_id": "azure-prod",
    "resource_type": "cloud_resource",
    "resource_scope": "/subscriptions/.../resourceGroups/prod",
    "target_role": "ops",
    "risk_level": "high",
    "requires_credential": true,
    "secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/azure-prod-sp",
    "ttl_seconds": 900,
    "reason": "部署到生产环境需要用户确认"
  }
 }
 ```
 ## 四、Manager 回传审批结果给 Runtime
 Manager 已支持调用该接口。蜂群侧需要实现接收。
 默认路径：
 ```http
 POST /api/swarms/{swarm_id}/approvals/{approval_id}
 Authorization: Bearer <service_token>
 X-Correlation-ID: <correlation_id>
 X-Idempotency-Key: approval-decision-<approval_id>-<decision>
 Content-Type: application/json
 ```
 Manager 可配置：
 ```text
 AGENT_RUNTIME_APPROVAL_DECISION_PATH=/api/swarms/{swarm_id}/approvals/{approval_id}
 ```
 请求：
 ```json
 {
  "approval_id": "runtime-approval-1",
  "decision": "approved",
  "manager_deployment_id": "dep_xxx",
  "runtime_deployment_id": "runtime-dep-123",
  "swarm_id": "swarm-123",
  "operation": "production_deploy",
  "resource_id": "azure-prod",
  "resource_type": "cloud_resource",
  "resource_scope": "/subscriptions/.../resourceGroups/prod",
  "target_role": "ops",
  "risk_level": "high",
  "requires_credential": true,
  "credential_ref": "lease://agent/lease_xxx",
  "lease_id": "lease_xxx",
  "lease_expires_at": 1770000000000,
  "decided_by": "user:22",
  "reason": "用户确认部署",
  "decided_at": 1770000000000
 }
 ```
 拒绝时：
 ```json
 {
  "approval_id": "runtime-approval-1",
  "decision": "rejected",
  "manager_deployment_id": "dep_xxx",
  "runtime_deployment_id": "runtime-dep-123",
  "swarm_id": "swarm-123",
  "reason": "风险过高",
  "decided_by": "user:22",
  "decided_at": 1770000000000
 }
 ```
 安全要求：
 1. Manager 不会在该请求中发送 `secret_ref`。
 2. 如果审批通过且需要凭证，只发送短期 `credential_ref = lease://agent/...`。
 3. Runtime 不得把 `credential_ref`、service token、签名密钥写入日志或 artifact metadata。
 4. Runtime 收到 `approved` 后继续原高危动作；收到 `rejected` 后停止该动作并回调 `timeline.updated` 或 `task.failed/blocked`。
 响应：
 ```json
 {
  "success": true,
  "data": {
    "approval_id": "runtime-approval-1",
    "status": "accepted"
  }
 }
 ```
 ## 五、当前 HeiCode-Swarm 现状与建议
 当前 `HeiCode-Swarm` 可见 Orchestrator 入口是：
 | 当前入口 | 可用性 | 建议 |
 |---|---|---|
 | `GET /health` | 可直接作为健康检查 | Manager `AGENT_RUNTIME_HEALTH_PATH=/health` |
 | `POST /tasks` | 可临时创建任务 | 只能做兼容桥接，不建议作为最终生产契约 |
 | `GET /tasks` | 可查任务 | 后续需要映射到 callback/timeline |
 | `GET /agents` | 可查 Agent | 后续需要回调 agent status |
 | `GET /handoffs` | 可查 handoff | 后续需要回调 handoff events |
 | `GET /metrics` | 可查指标 | 后续需要按 deployment/swarm 关联 |
 | `WS /ws/{agent_id}` | Agent 内部通道 | Manager 不直接接 WS |
 建议蜂群侧优先补正式 `POST /api/swarms` 和 approval decision 接口；如果短期只想先跑通，可由 Manager 临时把 create path 指到 `/tasks`，但这会缺少 `secret_ref`、resource grants、approval policy、artifact callback 等正式字段。
 ## 六、联调验收
 最小验收顺序：
 1. Manager 调 `GET /api/agent/health` 或 `/health` 返回 healthy。
 2. Manager 调 Runtime create，拿到 `runtime_deployment_id` 和 `swarm_id`。
 3. Runtime 回调 `deployment.status_changed`，Manager timeline 可见。
 4. Runtime 回调 `task.claimed`、`task.completed`，Manager timeline 可见。
 5. Runtime 回调 `artifact.created`，Manager artifacts 可见。
 6. Runtime 回调 `approval.requested`，Manager/客户端能看到 pending approval。
 7. 用户 approve/reject 后，Runtime 收到 approval decision。
 8. Runtime 根据 decision 继续或停止，并回调最终结果。
 9. 全链路无明文长期密钥、模型 key、云 access key、私钥、连接串。
@@ -1,151 +0,0 @@
 # Heicode Manager 蜂群 Runtime 联调配置模板
 更新时间：2026-05-27
 适用范围：Heicode Manager 调用 Agent Manager / HeiCode-Swarm Runtime。
 ## 一、标准 Agent Manager Runtime 配置
 当 Runtime 提供正式 `POST /api/swarms` 时，Manager 建议配置：
 ```bash
 AGENT_RUNTIME_ENABLED=true
 AGENT_RUNTIME_ASYNC=false
 AGENT_RUNTIME_BASE_URL=http://<runtime-host>
 AGENT_RUNTIME_SERVICE_TOKEN=<service-token>
 AGENT_RUNTIME_HEALTH_PATH=/api/agent/health
 AGENT_RUNTIME_CREATE_PATH=/api/swarms
 AGENT_RUNTIME_STOP_PATH=/api/swarms/{swarm_id}/stop
 AGENT_RUNTIME_APPROVAL_DECISION_PATH=/api/swarms/{swarm_id}/approvals/{approval_id}
 AGENT_RUNTIME_TIMEOUT_SECONDS=10
 HEICODE_PUBLIC_BASE_URL=https://code.xinghanlab.com
 AGENT_RUNTIME_CALLBACK_URL=https://code.xinghanlab.com/api/agent/callbacks/swarm-events
 AGENT_CALLBACK_TOKEN=<callback-token>
 ```
 说明：
 1. `AGENT_RUNTIME_SERVICE_TOKEN` 是 Manager 调 Runtime 的 Bearer token。
 2. `AGENT_CALLBACK_TOKEN` 是 Runtime 回调 Manager 时放在 `X-Agent-Service-Token` 的 token。
 3. 两个 token 可以不同，不要写进前端或日志。
 4. 如果 Runtime 返回 `swarm_id`，Manager 会保存到 `runtime_swarm_id`。
 5. 如果 Runtime 返回 `deployment_id`，Manager 会保存到 `runtime_deployment_id`。
 ## 二、当前 HeiCode-Swarm Orchestrator 兼容配置
 如果短期只用现有 Orchestrator 的 `/health` 和 `/tasks` 先做连通性测试，可以临时配置：
 ```bash
 AGENT_RUNTIME_ENABLED=true
 AGENT_RUNTIME_ASYNC=false
 AGENT_RUNTIME_BASE_URL=http://52.139.240.116:8000
 AGENT_RUNTIME_SERVICE_TOKEN=<optional-if-supported>
 AGENT_RUNTIME_HEALTH_PATH=/health
 AGENT_RUNTIME_CREATE_PATH=/tasks
 AGENT_RUNTIME_STOP_PATH=/tasks/{runtime_deployment_id}/stop
 AGENT_RUNTIME_APPROVAL_DECISION_PATH=/api/swarms/{swarm_id}/approvals/{approval_id}
 AGENT_RUNTIME_TIMEOUT_SECONDS=10
 HEICODE_PUBLIC_BASE_URL=https://code.xinghanlab.com
 AGENT_RUNTIME_CALLBACK_URL=https://code.xinghanlab.com/api/agent/callbacks/swarm-events
 AGENT_CALLBACK_TOKEN=<callback-token>
 ```
 注意：
 1. `/tasks` 不是最终生产契约，只能做临时兼容测试。
 2. 当前 `/tasks` 字段不足以完整表达 `resource_grants`、`secret_ref`、`approval_policy`、`budget`。
 3. 若 Orchestrator 不支持 stop 和 approval decision，Manager 会记录回传失败审计，但用户审批记录仍会保存。
 ## 三、Runtime 回调 Manager 的请求头
 推荐使用 service token：
 ```http
 POST /api/agent/callbacks/swarm-events
 X-Agent-Service-Token: <callback-token>
 X-Agent-Event-Id: <event-id>
 X-Correlation-ID: <correlation-id>
 Content-Type: application/json
 ```
 也支持 HMAC：
 ```http
 X-Agent-Event-Id: <event-id>
 X-Agent-Timestamp: <unix-ms>
 X-Agent-Signature: sha256=<hex>
 X-Correlation-ID: <correlation-id>
 Content-Type: application/json
 ```
 签名内容：
 ```text
 timestamp + "." + event_id + "." + raw_body
 ```
 ## 四、最小联调命令
 健康检查：
 ```bash
 curl -sS "$AGENT_RUNTIME_BASE_URL$AGENT_RUNTIME_HEALTH_PATH"
 ```
 Manager 本地默认模拟链路：
 ```bash
 curl -sS -X POST "https://code.xinghanlab.com/api/agent/user/deployments/<manager-deployment-id>/simulate-events" \
  -H "Authorization: Bearer <manager-user-token>" \
  -H "Content-Type: application/json" \
  -d '{}'
 ```
 该命令用于 Manager 自测，不代表真实 Runtime 已执行。默认模拟会落 callback、artifact、approval、timeline 记录，并用于检查页面展示和 `secret_ref` 脱敏。
 模拟 Runtime 回调 Manager：
 ```bash
 curl -sS -X POST "https://code.xinghanlab.com/api/agent/callbacks/swarm-events" \
  -H "Content-Type: application/json" \
  -H "X-Agent-Service-Token: $AGENT_CALLBACK_TOKEN" \
  -H "X-Agent-Event-Id: evt-smoke-001" \
  -H "X-Correlation-ID: corr-smoke-001" \
  -d '{
    "event_id": "evt-smoke-001",
    "event_type": "timeline.updated",
    "deployment_id": "<manager-deployment-id>",
    "swarm_id": "<runtime-swarm-id>",
    "occurred_at": "2026-05-27T10:00:00Z",
    "source": "heicode-swarm-runtime",
    "payload": {
      "title": "Runtime callback received",
      "summary": "Manager callback pipeline is reachable",
      "severity": "info"
    }
  }'
 ```
 成功响应：
 ```json
 {
  "success": true,
  "data": {
    "event_id": "evt-smoke-001",
    "inserted": true,
    "deduplicated": false,
    "deployment_id": "<manager-deployment-id>"
  }
 }
 ```
 ## 五、上线前必须确认
 | 项 | 标准 |
 |---|---|
 | create | Manager 能拿到 `runtime_deployment_id` 和 `runtime_swarm_id` |
 | callback | Runtime 至少回调 `deployment.status_changed`、`task.completed`、`artifact.created` |
 | approval | Runtime 发 `approval.requested`，Manager 用户审批后 Runtime 收到 decision |
 | artifact | Manager artifacts 页面能看到 artifact 类型、标题、摘要和 URI |
 | timeline | Manager timeline 能区分 `manager`、`runtime`、`simulated` 来源 |
 | secret | 请求、响应、日志、artifact metadata 中无长期明文密钥 |
@@ -1,441 +0,0 @@
 # Agent Manager 蜂群模式对接任务清单
 更新时间：2026-05-28
 发给：Agent Manager / HeiCode-Swarm 负责人
 来源：Heicode Manager 当前代码、生产 1.4.9 验证结果、蜂群资料包和 Heicode 产品资料包。
 ## 1. 结论
 Heicode Manager 端已经具备蜂群模式所需的控制面能力：创建 deployment、桥接 Runtime、保存 `runtime_deployment_id` / `swarm_id`、接收 callback、落 artifact、落 approval、聚合 timeline、审批结果回传 Runtime、页面展示 task flow。
 Agent Manager / Swarm Runtime 当前还需要补齐或确认的是：真实创建 Swarm Run、生成任务图、Agent claim/heartbeat/handoff/retry/blocked 状态机、artifact 真实产出、审批暂停和恢复、日志指标、用量回传。
 ## 2. 当前 Manager 已完成
 | 能力 | 状态 | 说明 |
 |---|---|---|
 | Runtime 创建桥接 | 已完成 | Manager 可通过 `AGENT_RUNTIME_BASE_URL` + `AGENT_RUNTIME_CREATE_PATH` 调 Agent Manager |
 | Runtime 停止桥接 | 已完成 | 默认 `POST /api/agent/deployments/{deployment_id}/stop` |
 | `/api/swarms` adapter | 已完成 | Manager 用户态入口已存在，后续可切真实 Runtime |
 | callback 接收 | 已完成 | `POST /api/agent/callbacks/swarm-events` |
 | callback 鉴权 | 已完成 | 支持 service token 或 HMAC |
 | callback 幂等 | 已完成 | 按 `event_id` / `idempotency_key` 去重 |
 | task flow 校验 | 已完成 | `task.*` / `handoff.*` 缺关键字段会返回 `CALLBACK_SCHEMA_INVALID` |
 | artifact 落库 | 已完成 | `artifact.created` 可落库并在 deployment 详情展示 |
 | approval 落库 | 已完成 | `approval.requested` 可转 Manager 审批记录 |
 | approval decision 回传 | 已完成 | 用户 approve/reject 后 Manager 可回传 Runtime |
 | 页面验证 | 已完成 | 生产 1.4.9 已验证 `Sub task flow` 展示 task/blocked/retry/handoff |
 ## 3. Agent Manager 需要实现或确认的 P0
 | 任务 | 必需 | 原因 | 验收 |
 |---|---:|---|---|
 | 提供真实创建 Swarm Run 接口 | 是 | Manager 只能发起，不能替 Runtime 生成真实任务图 | `POST /api/swarms` 或配置等价接口返回真实 `deployment_id` / `swarm_id` |
 | 返回稳定 Runtime 标识 | 是 | Manager 要保存 `deployment_id <-> runtime_deployment_id/swarm_id` 映射 | 创建响应包含 `deployment_id` 或 `id`，建议同时包含 `swarm_id` |
 | 生成任务图 | 是 | 蜂群模式核心是 task graph，不是单个占位 deployment | Runtime 内部能创建任务节点，并回调 `task.created` |
 | Agent claim / heartbeat | 是 | Manager 页面和客户端需要知道哪个 Agent 在做哪个任务 | 回调 `task.claimed`、`task.heartbeat` |
 | blocked / retry / failed 状态机 | 是 | 失败恢复和阻塞是蜂群运行核心 | 回调 `task.blocked`、`task.retried`、`task.failed`，字段符合 schema |
 | handoff 状态机 | 是 | 蜂群 Agent 间交接需要可审计 | 回调 `handoff.requested`、`handoff.completed` |
 | artifact 真实产出 | 是 | Manager 只保存摘要和引用，真实产物来自 Runtime | 回调 `artifact.created`，带 `uri`、`summary`、`artifact_type` |
 | 高危审批暂停/恢复 | 是 | 高危操作需要客户端审批后 Runtime 才能继续 | Runtime 回调 `approval.requested`，并接收 Manager decision |
 | 日志/指标 | 是 | 线上排障和验收需要真实运行数据 | 提供 logs/metrics 查询或通过 callback 摘要回传 |
 | 不记录明文长期密钥 | 是 | 安全红线 | Runtime 只消费 `secret_ref` / `credential_ref`，日志和 artifact metadata 不出现明文密钥 |
 ## 4. Runtime 创建接口
 生产目标：
 ```http
 POST /api/swarms
 Authorization: Bearer <service_token>
 X-User-ID: <manager_user_id>
 X-Binding-Scope: <binding_scope>
 X-Correlation-ID: <correlation_id>
 X-Idempotency-Key: manager-<manager_deployment_id>
 Content-Type: application/json
 ```
 Manager 当前可通过环境变量切换：
 ```text
 AGENT_RUNTIME_BASE_URL=http://20.212.121.126
 AGENT_RUNTIME_CREATE_PATH=/api/swarms
 AGENT_RUNTIME_HEALTH_PATH=/api/agent/health
 AGENT_RUNTIME_STOP_PATH=/api/agent/deployments/{deployment_id}/stop
 AGENT_RUNTIME_APPROVAL_DECISION_PATH=/api/swarms/{swarm_id}/approvals/{approval_id}
 ```
 请求体核心形状：
 ```json
 {
  "orchestration_plan": {
    "intent_id": "task_xxx",
    "objective": "完成本轮用户目标",
    "sub_mode": "agile",
    "risk_level": "medium",
    "budget": {
      "max_tokens": 120000,
      "max_cost_usd": 8,
      "max_duration_sec": 3600
    },
    "user_context": {
      "user_id": "22",
      "channel_id": "heicode"
    },
    "billing_context": {
      "provider": "newapi",
      "default_model_id": "model_xxx",
      "allowed_model_ids": ["model_xxx"],
      "secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/model-gateway-key"
    },
    "agile_context": {
      "iteration": "2026-05-28",
      "stage": "development",
      "checkpoint": "draft_created",
      "next_action": "continue",
      "requires_user_approval": false
    },
    "agents": []
  },
  "agents": [
    {
      "role": "backend",
      "resource_grants": []
    }
  ],
  "resource_grants": [
    {
      "grant_id": "grant-task-backend",
      "resource_id": "repo-main",
      "resource_type": "git",
      "permission_scope": ["repo:read", "repo:write:feature-branches"],
      "secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/repo-main",
      "ref": "azkv://heicode-kv.vault.azure.net/secrets/repo-main",
      "target_role": "backend"
    }
  ],
  "callback": {
    "url": "https://code.xinghanlab.com/api/agent/callbacks/swarm-events",
    "signing_secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/agent-callback-signing-key",
    "subscribed_events": [
      "deployment.status_changed",
      "task.created",
      "task.claimed",
      "task.heartbeat",
      "task.blocked",
      "task.retried",
      "task.failed",
      "task.completed",
      "handoff.requested",
      "handoff.completed",
      "approval.requested",
      "artifact.created",
      "timeline.updated"
    ]
  },
  "sub_mode": "agile",
  "metadata": {
    "manager_deployment_id": "dep_xxx",
    "heicode_deployment_id": "dep_xxx",
    "heicode_runtime_bridge": true,
    "correlation_id": "corr_xxx"
  }
 }
 ```
 响应必须至少满足一种：
 ```json
 {
  "success": true,
  "data": {
    "deployment_id": "runtime-dep-123",
    "swarm_id": "swarm-123",
    "status": "running"
  }
 }
 ```
 或：
 ```json
 {
  "deployment_id": "runtime-dep-123",
  "swarm_id": "swarm-123",
  "status": "running"
 }
 ```
 Manager 解析规则：
 | Runtime 字段 | Manager 保存到 |
 |---|---|
 | `data.deployment_id` / `deployment_id` / `id` | `runtime_deployment_id` |
 | `data.swarm_id` / `swarm_id` / `runtime_swarm_id` | `runtime_swarm_id` |
 | `data.status` / `status` | `runtime_state` |
 ## 5. Runtime 回调 Manager
 统一入口：
 ```http
 POST https://code.xinghanlab.com/api/agent/callbacks/swarm-events
 X-Agent-Service-Token: <callback_token>
 X-Agent-Event-Id: <event_id>
 X-Correlation-ID: <correlation_id>
 Content-Type: application/json
 ```
 也支持 HMAC：
 ```http
 X-Agent-Timestamp: <unix_ms>
 X-Agent-Signature: sha256=<hex>
 ```
 签名内容：
 ```text
 timestamp + "." + event_id + "." + raw_body
 ```
 Agent Manager / 蜂群侧可以先拉取 Manager 当前接受的事件 schema：
 ```http
 GET https://code.xinghanlab.com/api/agent/callbacks/swarm-events/schema
 ```
 该接口不返回任何 token 或密钥，只返回事件类型、分类和必填字段，用于联调前核对 `task.*`、`handoff.*`、`artifact.created`、`approval.requested` 等 callback payload 是否符合 Manager 接收规则。
 统一 envelope：
 ```json
 {
  "event_id": "evt_xxx",
  "idempotency_key": "evt_xxx",
  "event_type": "task.blocked",
  "deployment_id": "dep_xxx",
  "swarm_id": "swarm-123",
  "agent_instance_id": "agent-backend-1",
  "task_id": "task-backend-1",
  "occurred_at": "2026-05-28T10:00:00Z",
  "correlation_id": "corr_xxx",
  "source": "heicode-swarm-runtime",
  "payload": {}
 }
 ```
 ## 6. task / handoff 事件 schema
 Manager 已上线校验。以下字段缺失会拒绝，返回 `CALLBACK_SCHEMA_INVALID`。
 | event_type | 必填字段 |
 |---|---|
 | `task.created` | `task_id`, `payload.title` |
 | `task.claimed` | `task_id`, `payload.agent_role` |
 | `task.running` | `task_id`, `payload.agent_role` |
 | `task.heartbeat` | `task_id`, `payload.agent_role` |
 | `task.blocked` | `task_id`, `payload.reason` |
 | `task.retried` | `task_id`, `payload.attempt` |
 | `task.released` | `task_id`, `payload.agent_role` |
 | `task.failed` | `task_id`, `payload.reason` |
 | `task.completed` | `task_id` |
 | `handoff.requested` | `task_id`, `payload.from_role`, `payload.to_role` |
 | `handoff.completed` | `task_id`, `payload.from_role`, `payload.to_role` |
 | `artifact.created` | `artifact.artifact_id` 或 `payload.artifact_id` |
 示例：
 ```json
 {
  "event_id": "evt_task_blocked_1",
  "event_type": "task.blocked",
  "deployment_id": "dep_xxx",
  "swarm_id": "swarm-123",
  "agent_instance_id": "agent-backend-1",
  "task_id": "task-backend-1",
  "source": "heicode-swarm-runtime",
  "payload": {
    "task_id": "task-backend-1",
    "agent_role": "backend",
    "reason": "等待前端接口字段确认",
    "severity": "warning",
    "next_action": "handoff_to_frontend"
  }
 }
 ```
 ```json
 {
  "event_id": "evt_handoff_1",
  "event_type": "handoff.requested",
  "deployment_id": "dep_xxx",
  "swarm_id": "swarm-123",
  "task_id": "task-backend-1",
  "source": "heicode-swarm-runtime",
  "payload": {
    "task_id": "task-backend-1",
    "from_role": "backend",
    "to_role": "frontend",
    "summary": "后端接口已完成，交给前端接页面"
  }
 }
 ```
 ## 7. artifact 回调
 Runtime 不要把大文件正文塞进 callback。只回写摘要和可访问引用。
 ```json
 {
  "event_id": "evt_artifact_1",
  "event_type": "artifact.created",
  "deployment_id": "dep_xxx",
  "swarm_id": "swarm-123",
  "task_id": "task-backend-1",
  "source": "heicode-swarm-runtime",
  "artifact": {
    "artifact_id": "art_backend_patch_1",
    "artifact_type": "code_patch",
    "title": "Backend patch",
    "summary": "完成工单列表和状态流转接口",
    "uri": "git://repo#feature/task-backend-1",
    "checksum": "sha256:abc123",
    "metadata": {
      "redacted": true,
      "agent_role": "backend"
    }
  }
 }
 ```
 ## 8. approval 回调和 decision 接口
 Runtime 在高危动作前必须暂停，并回调 Manager：
 ```json
 {
  "event_id": "evt_approval_1",
  "event_type": "approval.requested",
  "deployment_id": "dep_xxx",
  "swarm_id": "swarm-123",
  "agent_instance_id": "agent-backend-1",
  "task_id": "task-backend-1",
  "source": "heicode-swarm-runtime",
  "payload": {
    "approval_id": "appr_runtime_1",
    "operation": "git.write",
    "resource_id": "repo-main",
    "resource_type": "git",
    "resource_scope": "feature/*",
    "target_role": "backend",
    "risk_level": "high",
    "requires_credential": true,
    "secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/repo-main",
    "ttl_seconds": 900,
    "reason": "需要写入功能分支"
  }
 }
 ```
 Manager 用户同意或拒绝后会调用 Runtime：
 ```http
 POST /api/swarms/{swarm_id}/approvals/{approval_id}
 Authorization: Bearer <service_token>
 X-Correlation-ID: <correlation_id>
 X-Idempotency-Key: approval-decision-<approval_id>-<approved|rejected>
 Content-Type: application/json
 ```
 请求：
 ```json
 {
  "approval_id": "appr_runtime_1",
  "decision": "approved",
  "manager_deployment_id": "dep_xxx",
  "runtime_deployment_id": "runtime-dep-123",
  "swarm_id": "swarm-123",
  "operation": "git.write",
  "resource_id": "repo-main",
  "resource_type": "git",
  "resource_scope": "feature/*",
  "target_role": "backend",
  "risk_level": "high",
  "requires_credential": true,
  "user_id": "22",
  "credential_ref": "lease://agent/lease_xxx",
  "lease_id": "lease_xxx",
  "lease_expires_at": 1779850900000
 }
 ```
 注意：Manager 不会把长期 `secret_ref` 发回 decision，只会在同意时发短期 `credential_ref`。
 ## 9. 停止接口
 默认：
 ```http
 POST /api/agent/deployments/{runtime_deployment_id}/stop
 Authorization: Bearer <service_token>
 Content-Type: application/json
 ```
 请求：
 ```json
 {
  "reason": "Heicode Manager requested stop",
  "manager_deployment_id": "dep_xxx"
 }
 ```
 响应：
 ```json
 {
  "success": true,
  "data": {
    "deployment_id": "runtime-dep-123",
    "swarm_id": "swarm-123",
    "status": "stopped"
  }
 }
 ```
 ## 10. 验收用例
 | 用例 | 操作 | 期望 |
 |---|---|---|
 | health | `GET /api/agent/health` | 200，`status=healthy` |
 | create | Manager 创建 deployment | Runtime 返回 `deployment_id` 和 `swarm_id` |
 | task flow | Runtime 回调 `task.created/claimed/heartbeat/blocked/retried/completed` | Manager timeline 和页面 Sub task flow 可见 |
 | handoff | Runtime 回调 `handoff.requested/completed` | Manager 页面可见 from/to role |
 | schema 拒绝 | 发送缺 `to_role` 的 `handoff.requested` | Manager 返回 `CALLBACK_SCHEMA_INVALID` |
 | artifact | Runtime 回调 `artifact.created` | Manager artifacts 列表出现产物 |
 | approval | Runtime 回调 `approval.requested` | Manager pending approval 出现 |
 | decision | 用户 approve/reject | Runtime decision 接口收到 `approved/rejected` |
 | stop | Manager stop deployment | Runtime 状态变为 stopped |
 | 安全 | 搜索日志和回调 payload | 不出现 password/token/private_key/access_key/connection_string 明文 |
 ## 11. Agent Manager 不需要做的事
 | 不需要做 | 原因 |
 |---|---|
 | 实现桌面客户端 V2 body 加密 | 这是客户端到 Manager 的协议，Manager 已支持 |
 | 直接让普通用户访问 Azure Key Vault | 密钥入口由 Manager 控制，Runtime 只消费 `secret_ref` 或短期 `credential_ref` |
 | 在 callback 中发送明文模型 key / Git token / 云密钥 | 安全红线，Manager 会拒绝疑似明文敏感字段 |
 | 替 Manager 保存用户、资源绑定、审批主记录 | Manager 是控制面和记录面 |
 ## 12. 联调顺序建议
 1. Agent Manager 确认 health、create、stop、approval decision 路径。
 2. Manager 配置 `AGENT_RUNTIME_CREATE_PATH=/api/swarms` 后创建一个真实 deployment。
 3. Agent Manager 回调 `task.created`、`task.claimed`、`task.heartbeat`。
 4. 回调 `task.blocked`、`handoff.requested`、`handoff.completed`、`task.retried`。
 5. 回调 `artifact.created`。
 6. 回调 `approval.requested`，客户端/Manager approve 后 Runtime 接收 decision 并继续。
 7. Manager stop，Runtime 停止任务并回调最终状态。