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>
9.4 KiB
9.4 KiB
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 和代码看，当前项目结构是：
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 页面有没有数据。必须同时满足：
- 桌面客户端能通过 Manager 发起任务，POST 请求体走 V2 加密。
- Manager 创建或桥接 Swarm Run，并保存
deployment_id、runtime_deployment_id、swarm_id。 - Runtime 真实生成任务图，并回传任务状态、Agent 状态、handoff、artifact、审批请求。
- Manager 对 callback 去重、落库、脱敏，并能按 deployment/timeline/artifact 查询。
- 高危审批由客户端展示并提交，Manager 记录，Runtime 收到决定后继续或停止。
- 交付物能回到 Manager 和客户端，不能只停留在 Runtime Redis 或 Agent 日志里。
- 全链路日志和页面不得出现长期明文密钥、模型 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 | 根据真实联调结果更新本文状态 | 把缺失项从“缺接口/未联调”改为“已验证/阻塞/延期” |