Files

T

2026-05-14 17:50:32 +00:00

9.8 KiB

Raw Blame History

Agnet 受控蜂群最小验证与验收流程

版本: v0.1
日期: 2026-05-15
计划周期: 2026-05-20 至 2026-05-29，共 10 天
目标: 用最小流程证明 Heicode、Manager、Agnet 平台、Azure、密钥保管器和 CodeGW 的蜂群闭环方向正确

1. 最小验证结论先行

最小验证不是证明“有 3 个 Agent”，也不是证明“有一个 workflow 跑完”。

最小验证必须证明：

用户目标能进入 Swarm Run。
Swarm Run 能生成动态任务图。
子 Agnet 能从共享任务池领取任务。
子 Agnet 能产生产物。
任务之间能发生交接或失败回流。
高危动作能进入审批。
Manager 能看到状态、事件、产物、用量和审计。
长期密钥不进入请求体、日志、事件、artifact 或 Git。

2. 验证前提

2.1 环境前提

项	最小要求
Manager	能登录，能发起 Swarm Run，能接收回调
Agnet 平台	能提供 `POST /api/swarms` 和状态查询
AKS	能运行 Agnet 平台和至少一个子 Agnet runtime
PostgreSQL	能保存 Swarm Run、Task、Event、Artifact、Approval
Redis	能提供 claim 锁、heartbeat、幂等缓存
NATS/JetStream	能传递或广播任务事件
密钥保管器	能保存长期密钥，输出 `secret_ref` 或 `lease_ref`
CodeGW	能提供用户模型和用量归因所需的引用

2.2 测试数据前提

测试数据必须满足：

使用测试仓库或测试分支。
使用测试云资源或无害资源。
使用临时密钥或测试 secret_ref。
不在文档、日志、事件中写入真实密钥。
生产部署类动作可以用审批模拟，但流程必须真实。

建议测试目标：

请在测试仓库中完成一个小型代码或文档变更，生成验证结果，并在需要部署前请求审批。

3. Happy Path 最小流程

Step 1: 用户目标进入 Manager

用户在 Heicode 客户端或 Manager 启动入口输入目标。

必须记录：

heicode_task_id
user_id
goal
correlation_id

验收：

Manager 有一条待启动任务记录。
记录中没有明文密钥。

Step 2: Manager 检查资源准备

Manager 检查：

Git 资源。
SK 资源。
项目文档资源。
云资源。
secret_ref。
审批策略。
预算策略。

验收：

Manager 能生成用户可读启动摘要。
用户不需要填写完整 payload。

Step 3: Manager 创建 Swarm Run

Manager 调用：

POST /api/swarms

必须带：

Idempotency-Key
X-Correlation-Id
服务认证。
用户目标。
资源引用。
密钥引用。
审批策略。
预算。

验收：

Agnet 平台返回 swarm_id。
Manager 保存 swarm_id。
重复请求不会创建重复 Swarm Run。

Step 4: Agnet 平台生成动态任务图

Agnet 平台根据目标生成至少两个任务：

任务	能力
目标理解与任务生成	goal_plan
代码或文档变更	build
验证和交付整理	verify_release

验收：

swarm_tasks 至少有 2 条记录。
每条任务有 required_capability、status、acceptance。

Step 5: Agnet 平台生成能力编队

Agnet 平台生成最小能力编队：

Goal/Plan Capability。
Build Capability。
Verify/Release Capability。

验收：

swarm_capabilities 有记录。
每个能力有权限范围、工具范围、停止条件。

Step 6: 子 Agnet claim 任务

子 Agnet 调用内部接口领取任务：

POST /internal/swarms/{swarm_id}/tasks/{task_id}/claim

验收：

任务状态从 created 变成 claimed 或 running。
owner_agent_id 有值。
heartbeat 正常更新。

Step 7: 子 Agnet 产生产物

子 Agnet 完成一个无害变更或文档产物，并上报 artifact：

POST /internal/artifacts

验收：

swarm_artifacts 有记录。
artifact 有 uri、checksum、task_id。
Manager 能看到 artifact 摘要。

Step 8: 任务交接

Build Capability 完成后，任务交接给 Verify/Release Capability。

验收：

有 handoff.created 事件。
下一个任务可 claim。
Manager 能看到交接摘要。

Step 9: 验证任务执行

Verify/Release Capability 执行验证。

验收：

有测试或检查结果。
有 task.completed 或 task.failed 事件。
如果无法测试，必须记录未测试原因。

Step 10: 高危审批请求

如果任务触发部署、云资源写操作或短期高危凭证读取，Agnet 平台必须请求审批：

POST /api/agnet/callbacks/approval-requests

验收：

Manager 生成审批记录。
状态变为 waiting_approval。
用户可审批。
日志中无明文长期密钥。

Step 11: 审批结果回传

Manager 调用：

POST /api/swarms/{swarm_id}/approvals/{approval_id}

验收：

审批通过后任务继续。
审批拒绝后任务失败或生成安全替代方案。
审批记录进入审计。

Step 12: Swarm 收敛

Agnet 平台判断任务完成。

完成条件：

必要任务完成。
必要 artifact 生成。
必要验证通过或记录未通过原因。
没有 pending 审批。
没有 blocking 失败任务。

验收：

Swarm Run 状态为 completed，或 failed 且原因清楚。
Manager 与 Agnet 平台状态一致。

Step 13: Manager 展示最终结果

Manager 展示：

总体状态。
任务列表。
事件流。
artifact。
审批记录。
用量。
审计。

验收：

用户可以理解发生了什么。
不需要查看底层完整参数。
不显示任何长期密钥明文。

4. 失败回流验证

必须至少验证一次失败回流。

推荐失败注入：

子 Agnet heartbeat 超时。
测试命令故意失败。
artifact 上报失败。
重复事件回调。
Redis 短暂不可用。

验证流程：

创建 Swarm Run。
子 Agnet claim 任务。
注入失败。
Agnet 平台写入失败事件。
任务 attempt_count 增加。
任务释放、重试、拆分或 handoff。
Manager 展示失败原因和后续动作。

验收：

失败不是静默失败。
失败能在事件流中看到。
失败后任务状态可解释。
重试不超过上限。
如果最终失败，失败原因可读。

5. 审批验证

必须至少验证一次审批。

审批类型：

production_deploy
cloud_write
production_secret_access