taijibaga/heicode-mananger

Fork 0

Files

T

gongzhiyong edf7aeaf8a feat: add agnet artifact content proxy

2026-05-30 12:55:04 +08:00

22 KiB

Raw Blame History

Heicode Manager 可独立执行任务计划

更新时间：2026-05-30 负责人范围：Heicode Manager 端
用途：后续开发按本文逐项执行、验收和更新状态。

一、核查结论

本文只列 Manager 端能独立完成的任务。判断标准是：不要求 Heicode 客户端新增功能、不要求蜂群 / Agnet 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` 或等价生产接口	蜂群 / Agnet Runtime
子 Agnet claim、heartbeat、release、timeout	需要 worker runtime 和任务池	蜂群 / Agnet Runtime
handoff、retry、blocked 的真实状态机	需要 Runtime 产生任务事件	蜂群 / Agnet Runtime
真实日志流和 CPU/内存/耗时指标	需要日志/指标源	蜂群 / 基础设施
客户端高危审批主弹窗	产品要求审批主体验在客户端	Heicode 客户端
短期凭证真实注入子 Agnet	需要受控 runtime、身份和网络通道	蜂群 / 基础设施
SK 工具真实调用结果	需要 SK 平台或 Runtime 上报 invocation event	蜂群 / SK 平台
交付结果回到客户端	需要客户端展示和 Runtime artifact 输出	客户端 + 蜂群

三、执行顺序总览

顺序	任务	优先级	是否 Manager 独立	完成后价值
1	增加 sub 模式字段	P0	是	已完成：明确任务组织方式，支撑瀑布/敏捷状态展示
2	打通 HeicodeTask 到 Agnet deployment 的 Manager 桥接	P0	是	已完成：任务可生成 deployment draft
3	增加用户态 Agnet deployment API	P0	是	已完成：普通用户可以在自己资源范围内创建/查看/停止 deployment
4	统一 `/api/swarms` 与 `/api/agnet/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/agnet_deployment.go`、`heicode/controller/agnet_control_plane.go`、`heicode/web/default/src/features/agnet-console/api.ts`、`heicode/web/default/src/features/agnet-console/create-agnet-deployment-sheet.tsx`
建议字段	`sub_mode`，枚举：`waterfall`、`agile`，默认 `agile`
验收	创建 deployment 后 DB、API response、前端详情都能看到 `sub_mode`
测试	`go test ./controller -run 'TestAgnet.*SubMode

验收标准：

不允许写成自由文本。
旧数据无字段时默认按 agile 展示。
不能把 sub_mode 当成蜂群 Runtime 流程，只表示 Heicode 任务组织方式。

任务 2：HeicodeTask 到 Agnet deployment 桥接

项	内容
目标	Manager 能从 HeicodeTask 的任务卡生成本地 Agnet deployment payload
修改文件	`heicode/controller/agnet_control_plane.go`、新增 `heicode/controller/agnet_task_bridge.go`、`heicode/web/default/src/lib/heicode-mcp.ts`、`heicode/web/default/src/features/tasks/task-card-view.tsx`
新增 API	`POST /api/agnet/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：用户态 Agnet deployment API

项	内容
目标	普通用户可以创建、查询、停止自己资源范围内的 deployment
修改文件	`heicode/router/api-router.go`、`heicode/controller/agnet_control_plane.go`、`heicode/controller/agnet_control_plane_test.go`
当前问题	`/api/agnet/deployments` 走 `AdminAuth`
新增建议	保留 admin route；新增 user route：`/api/agnet/user/deployments` 或在同一路由中按 user scope 限制
测试	普通用户创建成功；越权查询别人 deployment 失败；停止别人 deployment 失败

验收标准：

用户只能看到自己的 deployment。
user_context.user_id 为空时用登录用户 id 填充。
请求体伪造别人 user_context.user_id 必须被覆盖或拒绝。
resource grant 必须属于当前用户。

任务 4：统一 `/api/swarms` 与 `/api/agnet/deployments` 边界

项	内容
目标	Manager 内部形成生产蜂群接口 adapter，不再让调用方混淆两个口径
修改文件	新增 `heicode/controller/agnet_swarm_adapter.go` 或 `heicode/service/agnet_swarm_adapter.go`，更新 `docs/integration/agnet-platform-request-contract.md`
当前现实	本地已有 `/api/agnet/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/agnet_callback.go`、`heicode/controller/agnet_callback.go`、`heicode/router/api-router.go`
新增接口	`POST /api/agnet/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/agnet_artifact.go`、`heicode/controller/agnet_artifact.go`、`heicode/web/default/src/features/agnet-console/api.ts`、`heicode/web/default/src/features/agnet-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/agnet_callback.go`、新增 `heicode/middleware/agnet_callback_auth.go`
机制	`X-Request-Id`、`X-Correlation-Id`、`Idempotency-Key`、可选 `X-Agnet-Signature`
当前阶段	可以先用配置开关和本地测试 token，不接真实 Key Vault service token
测试	缺少服务 token 时拒绝；重复 key 不重复写入

验收标准：

开发环境可配置跳过严格签名，但生产默认要求服务身份。
日志不打印 token 或签名原文。
幂等冲突能返回已有记录摘要。

任务 8：持久化 SK snapshot

项	内容
目标	替换当前 `agnetSnapshots` 内存 map
修改文件	新增 `heicode/model/agnet_sk_snapshot.go`，修改 `heicode/controller/agnet_control_plane.go`
当前问题	容器重启后 `/sk-snapshots` 丢失
测试	创建 snapshot 后清空内存，再从 DB 查询仍存在

验收标准：

deployment_id、snapshot_id 有索引。
查询按创建时间倒序或稳定顺序返回。
不保存 SK 内容正文，只保存来源和版本引用。

任务 9：任务视角审计聚合

项	内容
目标	按 task/deployment/correlation_id 聚合 Manager 已有记录
修改文件	`heicode/controller/agnet_control_plane.go`、`heicode/model/agnet_audit.go`、`heicode/web/default/src/features/agnet-console/pages.tsx`
聚合内容	deployment、audit events、approvals、leases、artifacts、callbacks、resource grants
新增接口	`GET /api/agnet/tasks/:task_id/timeline` 或 `GET /api/agnet/deployments/:id/timeline`
测试	同一 correlation_id 下能聚合多类事件

验收标准：

缺少某类数据时返回空数组，不报错。
时间线按时间排序。
敏感字段统一脱敏。

任务 10：本地模拟蜂群事件冒烟入口

项	内容
目标	在蜂群 Runtime 未接入前，Manager 能用模拟事件自测完整链路
修改文件	`heicode/controller/agnet_callback.go`、`heicode/router/api-router.go`、可选新增 `heicode/controller/agnet_smoke.go`
接口建议	admin-only `POST /api/agnet/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/agnet_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/agnet-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

验收标准：

不把 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/agnet/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/agnet_runtime_client.go`、`heicode/router/api-router.go`、`heicode/web/default/src/features/agnet-console/api.ts`、`heicode/web/default/src/features/agnet-console/pages.tsx`
新增 API	`GET /api/agnet/user/deployments/:deployment_id/runtime-diagnostics`
诊断来源	用 deployment 记录里的 `runtime_swarm_id` / `runtime_deployment_id` 查询 Runtime status；默认路径 `/api/swarms/{swarm_id}/status`，可用 `AGNET_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 TestAgnetRuntimeDiagnosticsWarnsOnCompletedRuntimeWithFailedAgents -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/agnet_artifact.go`、`heicode/controller/agnet_callback.go`、`heicode/controller/agnet_runtime_client.go`、`heicode/router/api-router.go`、`heicode/web/default/src/features/agnet-console/pages.tsx`
新增 API	`GET /api/agnet/user/deployments/:deployment_id/artifacts/:artifact_id/content`
Runtime 目标路径	默认 `GET /api/swarms/{swarm_id}/artifacts/{artifact_id}/content`，可用 `AGNET_RUNTIME_ARTIFACT_CONTENT_PATH` / `SWARM_RUNTIME_ARTIFACT_CONTENT_PATH` 配置
安全边界	Manager 先校验当前用户拥有 deployment，再校验 artifact 属于该 deployment；不暴露 Azure Blob 凭据、SAS URL 或 Runtime 内网信息
测试	`go test ./controller -run TestAgnetArtifactContentProxiesRuntimeContent -count=1`

验收标准：

不能直接用用户传入的 URI 下载，必须以 Manager 已落库 artifact 为准。
响应透传 Runtime 的文件正文、Content-Type 和 Content-Disposition。
Runtime 未配置或 content 拉取失败时返回明确业务错误。
页面 artifact 卡片提供“下载产物”，但兜底摘要仍需标记为非最终业务交付物。

五、推荐执行批次

批次 A：最小 Manager 闭环

顺序	任务
1	sub 模式字段
2	用户态 Agnet deployment API
3	HeicodeTask 到 deployment 桥接
4	本地模拟蜂群事件冒烟入口

完成批次 A 后，Manager 应能做到：普通用户从任务卡发起一个本地 deployment，并通过模拟事件看到任务进展，不依赖真实 Runtime。

批次 B：生产联调准备

顺序	任务
1	`/api/swarms` 与 `/api/agnet/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 端应具备清晰的任务视角、持久化上下文、准确页面口径和更少误导。

六、统一自测命令

每个批次完成后至少执行：

cd /Users/gongzhiyong/go/heicode-mananger/heicode
go test ./controller ./model

前端有改动时执行：

cd /Users/gongzhiyong/go/heicode-mananger/heicode/web/default
bun run typecheck
bun run build

文档有改动时执行：

cd /Users/gongzhiyong/go/heicode-mananger
git diff --check -- docs

如果涉及生产部署，必须再按：

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

八、执行时不能突破的边界

不在 Manager 中保存长期明文密钥。
不让普通用户看到 CodeGW 管理后台能力。
不把 Manager 做成网页编码主体验。
不把 sub_mode 解释成蜂群 Runtime 固定流程。
不把本地模拟事件当真实蜂群完成证据。
不把 Azure Key Vault 暴露成普通用户要直接操作的后台。
不绕过客户端高危审批的产品边界；Manager 只能先提供记录和 API。
不破坏 V2 body 加密的版本字段、诊断头、重放保护和未加密 Web 控制台兼容路径，避免客户端和 Manager 联调不可排障。

22 KiB Raw Blame History Unescape Escape

Heicode Manager 可独立执行任务计划

一、核查结论

二、排除项

三、执行顺序总览

四、任务明细

任务 1：增加 sub 模式字段

任务 2：HeicodeTask 到 Agnet deployment 桥接

任务 3：用户态 Agnet deployment API

任务 4：统一 /api/swarms 与 /api/agnet/deployments 边界

任务 5：callback 接收端骨架

任务 6：artifact 数据模型和 API

任务 7：回调幂等和服务身份校验骨架

任务 8：持久化 SK snapshot

任务 9：任务视角审计聚合

任务 10：本地模拟蜂群事件冒烟入口

任务 11：前端页面补齐独立闭环展示

任务 12：文档口径清理

任务 13：AWS/GCP 占位提示

任务 14：请求 body 加密策略确认

任务 15：Runtime 状态诊断与兜底产物识别

任务 16：Artifact 完整内容代理下载

五、推荐执行批次

批次 A：最小 Manager 闭环

批次 B：生产联调准备

批次 C：可观测与收尾

六、统一自测命令

七、完成定义

八、执行时不能突破的边界

22 KiB

Raw Blame History

任务 4：统一 `/api/swarms` 与 `/api/agnet/deployments` 边界