chenchenandClaude Opus 4.8
0fe1d20d67
按桌面客户端统一方案 v0.1 + agent_management Sub Mode Runtime 对接,强制全量统一,不留兼容。
命名统一(强制,无兼容):
- 全仓 agnet/Agnet/AGNET → agent/Agent/AGENT:后端 Go(路由 /api/agent/*、env AGENT_*、
结构体/函数、19 个文件改名)、前端(agent-console/agent-hub、/api/agent 调用、i18n)、
DB(表 agent_*、列 agent_id)、compose/.env、文档、脚本。
- DB 加幂等迁移 renameAgnetTablesToAgent():启动时 rename 老 agnet_* 表/列,保住生产数据。
统一方案核心(10 项):
- callback 统一 /api/agent/callbacks/runtime-events(路由/广播URL/函数名)。
- artifact 兜底判定改用 Runtime 权威信号 metadata.synthesized(§7.2)+ 结构化 artifact_type。
- Manager→Runtime 路径对齐 /api/agent/sub-agile/deployments(§2.2),{deployment_id} 回退 swarm_id。
- 状态裁决 display_status:Manager 唯一裁判,completed 无有效产物→needs_codegen/
completed_without_deliverable(§10.6),接入 detail/timeline/workflow。
- GET /api/heicode/capabilities 能力发现(§6)。
- 模型策略 per_role(role_models)+ 收集 allowed_model_ids(§9)。
- resource_binding_id→secret_ref 服务端解析,客户端不再 inline secret_ref(§17.6)。
- 客户端统一路由层 /api/heicode/sub-agile|swarm/*(task≡deployment,复用控制面)+ workflow 投影。
- 日志分层 user_logs/debug_logs(§13)。
验证:go build ./... + go test(controller/router/model/middleware)全绿;前端 tsc -b + rsbuild build 通过。
待部署:VM .env 的 AGNET_*→AGENT_*;启动迁移自动 rename 表;其他三仓库需同步切到 /api/agent。
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
145 lines
16 KiB
Markdown
145 lines
16 KiB
Markdown
# 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 |
|