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

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

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

## 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` |

请求核心字段：

```json
{
  "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
  }
}
```

响应核心字段：

```json
{
  "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` |
| 必须落库 | 是 |

请求核心字段：

```json
{
  "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 |
| 用途 | 高危部署、云资源写操作、短期凭证读取 |

请求核心字段：

```json
{
  "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` |

请求核心字段：

```json
{
  "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` 关联。
- 任何接口响应和日志都不能出现长期明文密钥。