fengqun/docs/02-person-task-interface-matrix.md

Agnet 受控蜂群三人任务清单与接口联调明细

版本: v0.1
日期: 2026-05-15
计划周期: 2026-05-20 至 2026-05-29，共 10 天
团队人数: 3 人

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

本文是三人平台联调矩阵，用来说明 Heicode / Manager、Agnet Swarm Runtime、Azure 基础设施三条生产级工作线如何对齐。当前 fengqun 仓库已经完成的是独立 swarm-minimal 验收层，不是完整平台联调层。

已完成并有测试证据的最小闭环包括：

• S01-S10 标准矩阵通过，覆盖静态编译、单元回归、连续推理、失败注入、模型 I/O 审计、live 外部代码场景、下一阶段边界最小验收和蜂群六特征验收。
• SW-AQS-16 已在本地确定性代码层验证 3/5/7 Agent 并发自主 claim，无重复领取，任务可稳定完成并收敛。
• 候选融合已从“只选最高分候选”补为“多个有效候选去重合并并保留来源证据”。
• 互相质询已从规则/投票门补为“反驳、修正、再投票”的最小共识过程。
• 蜂群主指标已固定为去中心化、自组织、涌现性、鲁棒性、可扩展性、隐式协作六项。

本文后续仍要完成的是把这些能力接入 Manager / Agnet API、真实 worker runtime、审批、审计、生产资源和人类可见状态面板。阅读本文时应把它理解为生产级联调分工，而不是当前仓库最小闭环是否完成的判定依据。

当前最小原型指标的设计场景和成功阈值见 AGENT_SWARM_INDICATOR_TEST_MATRIX.zh-CN.md。接口联调阶段也必须按同一口径记录：每项指标写清测试场景、成功值和证据入口。

1. 成员 A: Heicode / Manager 对接负责人

1.1 目标

A 负责把 Heicode / Manager 变成蜂群启动、审批、状态和审计的受控入口。

A 不负责 Agnet runtime 调度，也不把底层参数暴露给普通用户。

1.2 详细任务清单

Day 1-2: Manager 侧准备

• 梳理 Manager 已有登录用户、资源绑定、密钥引用、CodeGW 用户侧信息。
• 定义 Manager 内部 Swarm 启动记录字段。
• 定义 Manager 对外展示字段：目标、资源准备状态、启动摘要、运行状态、事件、产物、审批、用量、审计。
• 确认 Manager 不展示长期密钥明文。
• 确认 Manager 不要求普通用户手写 payload。

交付物：

• Manager 创建 Swarm Run 的字段映射。
• Manager 回调接收表或记录结构。
• Manager 审批记录结构。

Day 3-5: Manager 与 Agnet 平台基础联调

• 实现或整理 Manager 调用 POST /api/swarms。
• 保存 swarm_id、状态、请求摘要、correlation_id。
• 接收 Agnet 平台 swarm-events 回调。
• 接收 Agnet 平台 artifacts 回调。
• 提供 Manager 查询 Swarm 状态、事件和产物的 API 或页面。
• 处理重复回调，不重复写事件。

交付物：

• Manager -> Agnet 创建请求成功。
• Manager 可展示 Swarm Run 状态。
• Manager 可展示事件与 artifact 摘要。

Day 6-7: 失败、交接和审批

• 展示任务失败、重试、handoff、blocked、waiting_approval 状态。
• 接收 approval-requests 回调。
• 生成审批记录。
• 提供审批通过/拒绝接口，回传 Agnet 平台。
• 审批记录进入审计。
• 审批页面不展示密钥明文。

交付物：

• Manager 可见审批请求。
• Manager 可回传审批结果。
• Manager 可解释失败和交接。

Day 8-10: 验收与加固

• 支持完整端到端 Swarm Run 展示。
• 支持重复请求和重复回调幂等。
• 支持错误态展示。
• 输出 Manager 侧验收证据。
• 输出剩余风险和未完成项。

交付物：

• Manager 侧验收记录。
• Manager 接口说明。
• 用户可见边界说明。

1.3 A 需要对接的接口

A 调用 B: 创建 Swarm Run

项	内容
方法	POST /api/swarms
调用方	Manager
提供方	Agnet 平台
认证	服务端 token 或签名
幂等	Idempotency-Key
追踪	X-Correlation-Id

请求核心字段：

{
  "request_id": "uuid",
  "heicode_task_id": "task-id",
  "user_context": {
    "user_id": "heicode-user-id",
    "email": "user@example.com",
    "channel_id": "codegw-channel-id"
  },
  "goal": "用户目标",
  "resource_refs": {
    "git": [],
    "sk": [],
    "project_docs": [],
    "cloud": []
  },
  "secret_refs": [],
  "approval_policy": {
    "production_deploy": "client_required",
    "production_secret_access": "client_required"
  },
  "budget": {
    "max_model_cost": 20,
    "max_runtime_minutes": 60,
    "max_iterations": 20
  },
  "runtime_preferences": {
    "mode": "goal_driven_swarm",
    "max_parallel_tasks": 3
  }
}

响应核心字段：

{
  "swarm_id": "swarm-uuid",
  "status": "created",
  "status_url": "/api/swarms/swarm-uuid",
  "event_url": "/api/swarms/swarm-uuid/events"
}

B 调用 A: 回传事件

项	内容
方法	POST /api/agnet/callbacks/swarm-events
调用方	Agnet 平台
提供方	Manager
幂等	event_id
必须落库	是

请求核心字段：

{
  "swarm_id": "swarm-uuid",
  "event_id": "event-uuid",
  "type": "task.completed",
  "agent_id": "agent-001",
  "task_id": "task-001",
  "message": "任务完成",
  "sequence": 12,
  "metadata": {},
  "timestamp": "2026-05-26T10:00:00Z"
}

B 调用 A: 请求审批

项	内容
方法	POST /api/agnet/callbacks/approval-requests
调用方	Agnet 平台
提供方	Manager
用途	高危部署、云资源写操作、短期凭证读取

请求核心字段：

{
  "swarm_id": "swarm-uuid",
  "approval_id": "approval-uuid",
  "type": "production_deploy",
  "title": "请求部署到生产环境",
  "risk": "high",
  "resource_refs": ["azure-prod-aks"],
  "expires_at": "2026-05-26T10:15:00Z"
}

A 调用 B: 回传审批结果

项	内容
方法	POST /api/swarms/{swarm_id}/approvals/{approval_id}
调用方	Manager
提供方	Agnet 平台
结果	approved 或 rejected

请求核心字段：

{
  "decision": "approved",
  "approved_by": "heicode-user-id",
  "reason": "用户确认部署",
  "decided_at": "2026-05-26T10:05:00Z"
}

2. 成员 B: Agnet Swarm Runtime 负责人

2.1 目标

B 负责把 Agnet 平台从普通 Agent/Workflow 执行扩展为目标驱动的 Swarm Runtime。

B 不负责 Manager 用户体验，也不负责 Azure 资源本身的供应，但必须提供可部署、可观测、可联调的服务。

2.2 详细任务清单

Day 1-2: Swarm Runtime 模型

• 定义 swarm_runs。
• 定义 swarm_capabilities。
• 定义 swarm_tasks。
• 定义 swarm_events。
• 定义 swarm_artifacts。
• 定义 swarm_approvals。
• 定义状态机：created、preparing、running、waiting_approval、degraded、verifying、completed、failed、stopped。

交付物：

• 数据模型。
• 状态机说明。
• 初始迁移或模型代码。

Day 3-4: 创建与任务领取

• 实现 POST /api/swarms。
• 根据用户目标生成最小动态任务图。
• 生成最小能力编队。
• 实现内部 claim。
• 实现 heartbeat。
• 实现任务释放。

交付物：

• 创建 Swarm Run 成功。
• 任务池生成成功。
• 子 Agnet 能 claim。

Day 5-6: 事件、产物、handoff

• 实现 event append。
• 实现 artifact create。
• 实现 Manager callback sender。
• 实现 handoff。
• 实现失败回流。
• 实现 attempt_count 和 max_attempts。

交付物：

• 事件回调 Manager。
• artifact 回调 Manager。
• 至少一次 handoff 或失败回流。

Day 7-8: 审批与端到端

• 高危任务进入 waiting_approval。
• 调用 Manager 审批请求。
• 接收 Manager 审批结果。
• 审批通过后继续执行。
• 审批拒绝后失败或生成替代任务。
• 完成端到端最小 Swarm Run。

交付物：

• 审批状态机。
• 端到端闭环。

Day 9-10: 加固和验收

• 加入幂等 key。
• 加入重复事件保护。
• 加入超时释放。
• 加入收敛判断。
• 输出 Runtime 验收说明。

交付物：

• Swarm Runtime 验收记录。
• 接口说明。
• 状态机说明。

2.3 B 需要对接的接口

对 A 提供的外部接口

接口	用途	Day
POST /api/swarms	Manager 创建 Swarm Run	Day 3
GET /api/swarms/{swarm_id}	Manager 查询状态	Day 4
GET /api/swarms/{swarm_id}/events	Manager 查询事件流	Day 5
GET /api/swarms/{swarm_id}/artifacts	Manager 查询产物	Day 5
POST /api/swarms/{swarm_id}/stop	Manager 停止 Swarm	Day 9
POST /api/swarms/{swarm_id}/approvals/{approval_id}	Manager 回传审批结果	Day 7

对 C 依赖的运行接口

依赖	用途	B 需要
PostgreSQL	保存最终状态	连接串、迁移权限、备份策略
Redis	claim 锁、幂等、heartbeat	Redis 地址和认证方式
NATS/JetStream	异步事件	subject 命名和持久化策略
AKS	子 Agnet runtime	namespace、service account、image pull
密钥保管器	短期凭证引用	secret_ref 解析和租约策略
监控	指标与告警	Prometheus scrape 或 Azure Monitor

内部 Agent Runtime 接口

接口	用途
POST /internal/swarms/{swarm_id}/tasks/{task_id}/claim	子 Agnet 领取任务
POST /internal/tasks/{task_id}/heartbeat	子 Agnet 心跳
POST /internal/tasks/{task_id}/complete	子 Agnet 完成任务
POST /internal/tasks/{task_id}/fail	子 Agnet 上报失败
POST /internal/tasks/{task_id}/handoff	子 Agnet 发起交接
POST /internal/artifacts	子 Agnet 上报产物
POST /internal/events	子 Agnet 上报事件

3. 成员 C: Azure / 基础设施 / 验收负责人

3.1 目标

C 负责让联调发生在真实或准生产 Azure 环境里，并提供服务健康、网络、日志、监控、密钥和验收证据。

C 不把“Pod Running”当完成，必须证明业务链路可以运行。

3.2 详细任务清单

Day 1-2: 环境基线

• 确认 AKS 集群、命名空间、节点、镜像拉取、服务账号。
• 确认 Azure PostgreSQL 连接和迁移权限。
• 确认 Redis 可用。
• 确认 NATS/JetStream 可用或部署计划。
• 确认密钥保管器可用。
• 确认 Manager 与 Agnet 平台网络互通。
• 确认日志采集和指标入口。

交付物：

• 环境基线清单。
• 网络连通性清单。
• 风险清单。

Day 3-5: 服务部署与联调支撑

• 部署 Agnet 平台服务。
• 配置数据库、Redis、NATS、密钥保管器连接。
• 配置 Manager -> Agnet 平台访问路径。
• 配置 Agnet 平台 -> Manager 回调路径。
• 配置日志脱敏策略。
• 配置服务健康检查。

交付物：

• Agnet 服务可访问。
• Manager 与 Agnet 双向联通。
• 日志和指标可查。

Day 6-7: 失败注入与安全验证

• 注入子 Agnet heartbeat 超时。
• 注入任务失败。
• 注入重复事件。
• 验证 Redis 丢失不影响最终事实恢复。
• 验证 NATS 短暂不可用后可补偿。
• 验证密钥不进入日志。
• 验证 OpenBao / 密钥保管器只通过受控路径访问。

交付物：

• 失败恢复记录。
• 安全检查记录。

Day 8-10: 最终验收

• 跑完整端到端验证。
• 收集数据库记录、事件记录、日志、指标、artifact 证据。
• 输出环境部署说明。
• 输出回滚说明。
• 输出最终验收报告。

交付物：

• Azure / 基础设施验收记录。
• 监控和日志证据。
• 回滚和故障处理说明。

3.3 C 需要对接的接口和资源

对接对象	接口或资源	C 的职责
A / Manager	Manager 回调地址	保证 Agnet 平台可访问，认证和 TLS 正常
B / Agnet 平台	Agnet 服务部署	保证服务可运行、可扩缩、可查看日志
B / Agnet 平台	PostgreSQL	提供连接、迁移、备份和最小权限
B / Agnet 平台	Redis	提供 claim 锁和幂等能力
B / Agnet 平台	NATS/JetStream	提供事件通讯
A + B	密钥保管器	验证只传 secret_ref / lease_ref
A + B	监控指标	提供运行耗时、失败、队列、事件、资源指标
A + B	日志	提供关联 ID 查询，保证脱敏

4. 三人联调节奏

日期	必须联调的接口	必须产出的证据
2026-05-20	字段和环境对齐	接口草案、环境清单
2026-05-21	数据模型和健康检查	DB/Redis/NATS 健康证据
2026-05-22	POST /api/swarms	swarm_id、DB 记录
2026-05-23	claim + heartbeat	任务 owner、heartbeat
2026-05-24	event + artifact	Manager 可见事件和产物
2026-05-25	fail + handoff	失败回流或交接记录
2026-05-26	approval	审批请求和结果
2026-05-27	end-to-end	完整 Swarm Run 记录
2026-05-28	idempotency + recovery	重复请求、掉线、脱敏证据
2026-05-29	final acceptance	最终验收报告

5. 接口联调完成标准

接口联调完成必须满足：

• 每个接口有调用方、提供方、认证方式、幂等方式、错误码。
• 每个接口至少有一次真实环境调用证据。
• 每个回调接口支持重复投递。
• 每个高危动作都能进入审批。
• 每个 artifact 都能追溯到 Swarm Run 和 Task。
• 每条日志都能通过 correlation_id 关联。
• 任何接口响应和日志都不能出现长期明文密钥。

接口联调成功值：

指标	成功值
接口调用证据	每个创建、查询、停止、回调、artifact、审批接口至少 1 次真实环境调用成功
幂等	重复创建和重复回调不产生重复 Swarm、重复事件或重复 artifact
状态一致性	Manager、Agnet Runtime、数据库状态可用同一 correlation_id 对齐
安全	长期明文密钥泄露次数为 0；未授权资源访问必须失败并写审计
蜂群能力复用	接入后仍能复验 A01-A09、S01-S10、F01-F06，不能因平台化丢失现有指标