# A2N 协议（Agent-to-N Protocol）

> 版本：1.0.0
> 状态：规范
> 层级：子协议层
> 基于：[灵隙原始协议](01_raw-protocol.md)、[A2A 协议](02_a2a-protocol.md)
> 前缀：`group:` / `inter_group:`

---

## 1. 定位

A2N 协议定义多个 Agent 组成群组进行协同工作的规范，包括群组管理、任务拆分与合并、群体决策、角色与权限、升级机制等。

**适用场景**：
- 复杂任务的拆分与并行执行（MapReduce 模式）
- 多 Agent 协同完成单一目标
- 群体投票与共识决策
- 临时或永久的 Agent 工作组
- 分级升级机制

**依赖关系**：
- 群组内成员间的单播通信复用 A2A 协议

---

## 2. 功能定义

### 2.1 群组管理

| 功能 | 说明 |
|-----|------|
| 群组创建 | Coordinator 创建群组，定义拓扑结构 |
| 群组解散 | Coordinator 解散群组 |
| 加入群组 | Agent 主动申请加入 |
| 离开群组 | 成员主动离开 |
| 邀请加入 | Coordinator 或成员邀请其他 Agent |
| 接受邀请 | 被邀请者接受邀请 |
| 拒绝邀请 | 被邀请者拒绝邀请 |
| 成员更新通知 | 成员变动时广播通知 |
| 角色变更 | Coordinator 调整成员角色 |
| 群组冻结 | 暂停群组活动 |
| 群组解冻 | 恢复群组活动 |

### 2.2 群组通信

| 功能 | 说明 |
|-----|------|
| 广播 | 发送给所有成员 |
| 组播 | 发送给指定成员列表 |
| 单播 | 群内点对点（复用 A2A） |
| 消息中继 | 通过其他成员转发消息 |

### 2.3 任务协作

| 功能 | 说明 |
|-----|------|
| 任务拆分 | Coordinator 将大任务拆分为子任务 |
| 任务分配 | 子任务分配给指定 Worker |
| 子任务进度 | Worker 上报子任务进度 |
| 结果合并 | Coordinator 合并子任务结果 |

### 2.4 共识投票

| 功能 | 说明 |
|-----|------|
| 发起投票 | Coordinator 或 Reviewer 发起投票 |
| 提交投票 | 成员提交选项及理由 |
| 达成共识 | 公布投票结果 |

### 2.5 升级机制

| 功能 | 说明 |
|-----|------|
| 共识僵局升级 | 投票无法达成共识时升级给人类 |
| 子任务阻塞升级 | 子任务阻塞时升级给人类 |
| 跨群组升级 | 升级到更高层级群组 |

---

## 3. 消息类型定义

### 3.1 群组管理消息（前缀 `group:`）

| 消息类型 | 说明 |
|---------|------|
| `group:create` | 创建群组 |
| `group:disband` | 解散群组 |
| `group:join` | 加入群组 |
| `group:leave` | 离开群组 |
| `group:invite` | 邀请加入 |
| `group:accept_invite` | 接受邀请 |
| `group:reject_invite` | 拒绝邀请 |
| `group:member_update` | 成员更新通知 |
| `group:role_change` | 角色变更 |

### 3.2 群组通信消息（前缀 `group:`）

| 消息类型 | 说明 |
|---------|------|
| `group:broadcast` | 广播（所有成员） |
| `group:multicast` | 组播（指定成员） |
| `group:direct` | 群内单播 |
| `group:relay` | 消息中继 |

### 3.3 任务协作消息（前缀 `group:`）

| 消息类型 | 说明 |
|---------|------|
| `group:task_split` | 任务拆分 |
| `group:task_assign` | 任务分配 |
| `group:task_merge` | 结果合并 |
| `group:task_progress` | 子任务进度 |

### 3.4 共识投票消息（前缀 `group:`）

| 消息类型 | 说明 |
|---------|------|
| `group:vote` | 发起投票 |
| `group:vote_submit` | 提交投票 |
| `group:consensus` | 达成共识 |

### 3.5 HiL 升级消息（前缀 `group:` / `inter_group:`）

| 消息类型 | 说明 |
|---------|------|
| `group:consensus_escalate` | 共识僵局升级给人类 |
| `group:subtask_escalate` | 子任务阻塞升级给人类 |
| `group:human_decision` | 人类决策结果 |
| `inter_group:escalate` | 跨群组升级 |

---

## 4. 核心概念定义

### 4.1 群组拓扑结构

| 拓扑类型 | 说明 | 适用场景 |
|---------|------|---------|
| `star` | 星型，中心 coordinator 协调 | 简单任务分发 |
| `mesh` | 网状，成员间可直接通信 | 对等协作 |
| `chain` | 链式，流水线模式 | 顺序处理 |
| `hierarchical` | 层级型，多层管理 | 大型复杂任务 |
| `fullmesh` | 全连接网状 | 高可靠协作 |

### 4.2 成员角色

| 角色 | 说明 | 权限 |
|------|------|------|
| `coordinator` | 协调者 | 创建/解散群组、任务拆分、发起投票、角色变更 |
| `worker` | 工作者 | 执行子任务、提交结果、投票 |
| `reviewer` | 审核者 | 审核结果、发起投票、升级请求 |
| `observer` | 观察者 | 只读，查看进度 |

### 4.3 群组状态

| 状态 | 说明 |
|------|------|
| `creating` | 创建中 |
| `active` | 活跃 |
| `frozen` | 冻结（不可执行新任务） |
| `disbanded` | 已解散（终态） |

### 4.4 合并策略

| 策略 | 说明 |
|------|------|
| `first_success` | 首个成功结果即返回 |
| `majority` | 多数结果合并 |
| `weighted` | 按权重加权合并 |
| `custom` | 自定义合并逻辑 |

### 4.5 共识类型

| 类型 | 说明 |
|------|------|
| `majority` | 多数投票（>50%） |
| `supermajority` | 绝对多数（>67%） |
| `unanimity` | 一致同意（100%） |
| `weighted` | 加权投票 |

---

## 5. 群组生命周期

### 5.1 状态流转

```
creating → active → frozen → disbanded
             ↑         ↓
             └─────────┘
               解冻
```

### 5.2 群组创建流程

```
创建者(Coordinator)                被邀请成员
  |                                   |
  |---- group:invite ---------------->|  发送邀请
  |                                   |
  |<--- group:accept_invite ----------|  接受邀请
  |                                   |
  |---- group:member_update --------->|  通知成员更新
  |                                   |
  [群组状态变为 active]                |
```

### 5.3 群组解散流程

```
Coordinator                        所有成员
  |                                   |
  |---- group:disband --------------->|  通知解散
  |                                   |
  [群组状态变为 disbanded]             |
```

---

## 6. 任务协作流程

### 6.1 MapReduce 模式

```
                    Coordinator
                         │
          group:task_split（拆分任务）
                         │
       ┌─────────────────┼─────────────────┐
       ▼                 ▼                 ▼
    Worker1           Worker2           Worker3
       │                 │                 │
       │ 执行子任务       │ 执行子任务       │ 执行子任务
       │                 │                 │
       ▼                 ▼                 ▼
    子任务结果        子任务结果        子任务结果
       └─────────────────┼─────────────────┘
                         │
          group:task_merge（合并结果）
                         ▼
                    最终结果
```

### 6.2 流程步骤

1. **任务拆分阶段**
   - Coordinator 接收原始任务
   - 将任务拆分为多个子任务
   - 为每个子任务指定执行的 Worker
   - 定义合并策略

2. **并行执行阶段**
   - 各 Worker 并行执行子任务
   - 定期上报进度
   - 子任务完成后上报结果

3. **结果合并阶段**
   - Coordinator 收集所有子任务结果
   - 按合并策略合并结果
   - 返回最终结果

---

## 7. 共识投票流程

```
发起者(vote发起)                   所有成员
  |                                   |
  |---- group:vote ------------------>|  发起投票
  |                                   |
  |<--- group:vote_submit (各成员) ---|  提交投票
  |                                   |
  |---- group:consensus ------------->|  公布结果
```

---

## 8. 载荷结构定义

### 8.1 群组创建载荷

| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `group_id` | string | ✓ | 群组唯一标识 |
| `group_name` | string | - | 群组名称 |
| `topology` | string | ✓ | 拓扑结构 |
| `config` | object | - | 群组配置 |

### 8.2 群组配置

| 字段 | 类型 | 说明 |
|------|------|------|
| `max_members` | integer | 最大成员数 |
| `vote_threshold` | float | 投票阈值 |
| `default_consensus_type` | string | 默认共识类型 |

### 8.3 子任务结构

| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `subtask_id` | string | ✓ | 子任务标识 |
| `description` | string | ✓ | 子任务描述 |
| `assigned_to` | string | ✓ | 执行者 Agent ID |
| `dependencies` | array | - | 依赖的子任务 ID 列表 |
| `status` | string | ✓ | 子任务状态 |
| `payload` | object | ✓ | 子任务参数 |

### 8.4 投票载荷

| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `vote_id` | string | ✓ | 投票标识 |
| `question` | string | ✓ | 投票问题 |
| `options` | array | ✓ | 选项列表 |
| `consensus_type` | string | ✓ | 共识类型 |
| `deadline` | string | - | 截止时间 |

### 8.5 投票提交载荷

| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `vote_id` | string | ✓ | 投票标识 |
| `voter_id` | string | ✓ | 投票者 ID |
| `option_id` | string | ✓ | 选择的选项 |
| `reasoning` | string | - | 投票理由 |

### 8.6 共识结果载荷

| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `vote_id` | string | ✓ | 投票标识 |
| `winner` | string | ✓ | 获胜选项 |
| `vote_counts` | object | ✓ | 各选项票数 |
| `passed` | boolean | ✓ | 是否通过阈值 |

---

## 9. 升级机制

### 9.1 升级场景

| 场景 | 消息类型 | 说明 |
|------|---------|------|
| 共识僵局 | `group:consensus_escalate` | 投票超时未达成共识 |
| 子任务阻塞 | `group:subtask_escalate` | 子任务执行受阻 |
| 跨群组 | `inter_group:escalate` | 升级到上级群组 |

### 9.2 升级载荷

| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `escalation_id` | string | ✓ | 升级标识 |
| `escalation_type` | string | ✓ | 升级类型 |
| `escalation_level` | integer | ✓ | 升级级别（1/2/3） |
| `context` | object | ✓ | 升级上下文 |
| `options` | array | - | 可选方案 |

---

## 10. 错误处理

群组错误码分段：7000-7999

| 错误码 | 名称 | 说明 |
|------|------|------|
| 7001 | 群组不存在 | |
| 7002 | 群组未激活 | |
| 7003 | 成员不存在 | |
| 7004 | 不是群组成员 | |
| 7005 | 未达成共识 | |
| 7006 | 角色不存在 | |
| 7007 | 已是成员 | |
| 7008 | 群组已满 | |

---

## 11. 接口要求

Agent 实现 A2N 协议时必须提供：

| 接口 | 说明 |
|------|------|
| 群组管理处理器 | 处理群组创建、加入、离开等 |
| 子任务处理器 | 执行分配的子任务 |
| 投票处理器 | 处理投票相关消息 |
| 升级处理器 | 处理升级请求 |

---

## 12. 与其他协议的关系

- **依赖原始协议**：使用统一消息信封
- **依赖 A2A 协议**：群内单播通信复用 A2A
- **被 P2A 协议封装**：外部调用可触发群组任务