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>
414 lines
22 KiB
Markdown
414 lines
22 KiB
Markdown
# 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 联调不可排障。
|