fengqun/docs/03-minimal-validation-and-acceptance.md

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

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

0. 当前实现状态（2026-05-16）

本文描述的是平台级最小验证与验收流程，覆盖 Heicode、Manager、Agnet 平台、Azure、密钥保管器和 CodeGW 的完整受控闭环。当前 fengqun 仓库已经完成的是其中的 swarm-minimal 行为验收层：

• 本地静态与单元门禁已通过：py_compile 和 45 项 unittest。
• 学术化本地门禁已通过：A01-A09。
• 完整标准矩阵已扩展为：S01-S10。
• S07 live 外部代码场景已通过：固定 fastapi/fastapi commit、7 个任务、14 项检查、2 轮质量共识、无失败检查。
• S09 下一阶段边界已通过：3/5/7 并发 claim、候选融合、互相质询共识。
• S10 蜂群六特征已通过：去中心化、自组织、涌现性、鲁棒性、可扩展性、隐式协作。

因此，当前仓库可以判定为“最小化闭环已完成并可验收”。但本文中涉及的 Manager 启动入口、审批页面、Agnet 平台 API、AKS worker runtime、密钥保管器和 CodeGW 归因仍属于生产级平台验证，不应被当前仓库的本地验收结果自动覆盖。

当前仓库所有指标的设计场景和成功阈值以 AGENT_SWARM_INDICATOR_TEST_MATRIX.zh-CN.md 为准。本文的“可观测”只表示生产平台需要采集这些指标，不自动等于当前最小原型已完成生产级指标。

1. 最小验证结论先行

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

最小验证必须证明：

1. 用户目标能进入 Swarm Run。
2. Swarm Run 能生成动态任务图。
3. 子 Agnet 能从共享任务池领取任务。
4. 子 Agnet 能产生产物。
5. 任务之间能发生交接或失败回流。
6. 高危动作能进入审批。
7. Manager 能看到状态、事件、产物、用量和审计。
8. 长期密钥不进入请求体、日志、事件、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 短暂不可用。

验证流程：

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

验收：

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

5. 审批验证

必须至少验证一次审批。

审批类型：

• production_deploy
• cloud_write
• production_secret_access

验证流程：

1. Agnet 平台遇到高危动作。
2. Swarm Run 状态变成 waiting_approval。
3. Agnet 平台回调 Manager 创建审批请求。
4. Manager 展示审批信息。
5. 用户选择 approve 或 reject。
6. Manager 回传审批结果。
7. Agnet 平台继续或停止。

验收：

• 未审批前不能继续高危动作。
• 拒绝审批后不能继续高危动作。
• 审批记录可审计。
• 审批请求不包含长期明文密钥。

6. 安全验证

必须验证以下安全项：

项	验收标准
明文密钥	Git、Markdown、日志、事件、artifact、错误响应中均无明文长期密钥
secret_ref	Manager 与 Agnet 平台只传引用
短期凭证	只在审批后派生，且有过期时间
越权访问	未授权资源访问失败并写审计
回调认证	Agnet -> Manager 回调必须认证或签名
幂等	重复请求不造成重复任务、重复审批、重复 artifact
日志脱敏	token、password、private_key、connection_string 不输出

7. 观测验证

必须能查询：

• Swarm Run 状态。
• Task 状态。
• Agent heartbeat。
• Event stream。
• Artifact index。
• Approval record。
• Usage record。
• Audit record。
• Pod/runtime 日志。
• 基础指标。

最低指标：

指标	验收标准
Swarm 创建耗时	可观测；生产平台需记录 start/end timestamp；当前最小原型不把耗时作为 PASS 阈值
任务等待时间	可观测；生产平台需记录 task created 到 claimed；当前最小原型以 claim 是否正确为主
任务执行时间	可观测；生产平台需记录 claimed 到 done/failed；当前最小原型不设 SLA
handoff 次数	可观测；当前 S07 成功值为 7 个 STEP、7 条 chain edge
失败次数	可观测；当前故障注入成功值为 failed_tasks >= 1 且 run 仍 converged
重试次数	可观测；当前 fallback 场景成功值为 bad model 失败后至少一次 retry/fallback 并由 good model 接手
审批等待时间	可观测；属于生产级 Manager / Heicode 验收，不属于当前本地原型 PASS 阈值
模型用量	可归因到用户或任务；当前 S07 成功值为 3 个 discovered distinct 模型参与 7 步链路

8. Day 10 最终验收清单

最终验收时，三人必须共同确认：

编号	验收项	负责人	通过标准
1	Manager 发起 Swarm Run	A	返回 swarm_id 并保存
2	Agnet 平台创建 Swarm Run	B	DB 有 swarm_runs
3	动态任务图生成	B	至少 2 个任务
4	能力编队生成	B	至少 2 个能力
5	子 Agnet claim	B/C	owner 和 heartbeat 可见
6	事件回传 Manager	A/B	Manager 可查事件
7	artifact 回传 Manager	A/B	Manager 可查产物
8	handoff 或失败回流	B/C	有事件和状态变化
9	高危审批	A/B	审批请求和结果完整
10	用量回传	A/B	Manager 可查用量摘要
11	审计记录	A/B/C	操作可追踪
12	AKS 运行证据	C	runtime 日志和指标可查
13	密钥安全	A/C	无明文长期密钥
14	幂等	A/B	重复请求不重复创建
15	停止能力	A/B/C	Swarm 可停止且状态可解释

9. 不通过判定

出现以下任一情况，不能算通过：

• 只有文档，没有真实接口调用。
• 只有 Pod Running，没有 Swarm Run 业务状态。
• 只有固定 workflow，没有动态任务图。
• 没有任务 claim。
• 没有 artifact。
• 没有 handoff 或失败回流。
• 审批只是页面展示，没有阻断高危动作。
• Manager 与 Agnet 平台状态不一致。
• 日志或事件出现长期明文密钥。
• 最终结果无法被用户理解。

10. 最终交付包

最终交付必须包含：

• Manager 接口和页面验收记录。
• Agnet 平台接口和状态机说明。
• Azure 环境部署和健康记录。
• 最小验证流程截图或日志摘要。
• 数据库记录摘要。
• 事件流摘要。
• artifact 摘要。
• 审批记录摘要。
• 安全检查结果。
• 未完成项和下一阶段建议。