灵隙(synapse) v1.0.0 版本

This commit is contained in:
lychang
2026-06-28 03:24:26 +08:00
parent 88b606b9ca
commit 812f68d5aa
48 changed files with 5566 additions and 1499 deletions

395
docs/v1/03_a2n-protocol.md Normal file
View File

@@ -0,0 +1,395 @@
# 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 协议封装**:外部调用可触发群组任务