灵隙(synapse) v1.0.0 版本

This commit is contained in:
lychang
2026-06-29 02:12:44 +08:00
parent 2c59efe0ca
commit 65710a4536
27 changed files with 1819 additions and 760 deletions

View File

@@ -13,6 +13,7 @@
A2N 协议定义多个 Agent 组成群组进行协同工作的规范,包括群组管理、任务拆分与合并、群体决策、角色与权限、升级机制等。
**适用场景**:
- 复杂任务的拆分与并行执行(MapReduce 模式)
- 多 Agent 协同完成单一目标
- 群体投票与共识决策
@@ -20,6 +21,7 @@ A2N 协议定义多个 Agent 组成群组进行协同工作的规范,包括群
- 分级升级机制
**依赖关系**:
- 群组内成员间的单播通信复用 A2A 协议
---
@@ -28,53 +30,53 @@ A2N 协议定义多个 Agent 组成群组进行协同工作的规范,包括群
### 2.1 群组管理
| 功能 | 说明 |
|-----|------|
| 群组创建 | Coordinator 创建群组,定义拓扑结构 |
| 群组解散 | Coordinator 解散群组 |
| 加入群组 | Agent 主动申请加入 |
| 离开群组 | 成员主动离开 |
| 邀请加入 | Coordinator 或成员邀请其他 Agent |
| 接受邀请 | 被邀请者接受邀请 |
| 拒绝邀请 | 被邀请者拒绝邀请 |
| 成员更新通知 | 成员变动时广播通知 |
| 角色变更 | Coordinator 调整成员角色 |
| 群组冻结 | 暂停群组活动 |
| 群组解冻 | 恢复群组活动 |
| 功能 | 说明 |
|--------|---------------------------|
| 群组创建 | Coordinator 创建群组,定义拓扑结构 |
| 群组解散 | Coordinator 解散群组 |
| 加入群组 | Agent 主动申请加入 |
| 离开群组 | 成员主动离开 |
| 邀请加入 | Coordinator 或成员邀请其他 Agent |
| 接受邀请 | 被邀请者接受邀请 |
| 拒绝邀请 | 被邀请者拒绝邀请 |
| 成员更新通知 | 成员变动时广播通知 |
| 角色变更 | Coordinator 调整成员角色 |
| 群组冻结 | 暂停群组活动 |
| 群组解冻 | 恢复群组活动 |
### 2.2 群组通信
| 功能 | 说明 |
|-----|------|
| 广播 | 发送给所有成员 |
| 组播 | 发送给指定成员列表 |
| 单播 | 群内点对点(复用 A2A) |
| 消息中继 | 通过其他成员转发消息 |
| 功能 | 说明 |
|------|---------------|
| 广播 | 发送给所有成员 |
| 组播 | 发送给指定成员列表 |
| 单播 | 群内点对点(复用 A2A) |
| 消息中继 | 通过其他成员转发消息 |
### 2.3 任务协作
| 功能 | 说明 |
|-----|------|
| 任务拆分 | Coordinator 将大任务拆分为子任务 |
| 任务分配 | 子任务分配给指定 Worker |
| 子任务进度 | Worker 上报子任务进度 |
| 结果合并 | Coordinator 合并子任务结果 |
| 功能 | 说明 |
|-------|------------------------|
| 任务拆分 | Coordinator 将大任务拆分为子任务 |
| 任务分配 | 子任务分配给指定 Worker |
| 子任务进度 | Worker 上报子任务进度 |
| 结果合并 | Coordinator 合并子任务结果 |
### 2.4 共识投票
| 功能 | 说明 |
|-----|------|
| 功能 | 说明 |
|------|-----------------------------|
| 发起投票 | Coordinator 或 Reviewer 发起投票 |
| 提交投票 | 成员提交选项及理由 |
| 达成共识 | 公布投票结果 |
| 提交投票 | 成员提交选项及理由 |
| 达成共识 | 公布投票结果 |
### 2.5 升级机制
| 功能 | 说明 |
|-----|------|
| 共识僵局升级 | 投票无法达成共识时升级给人类 |
| 子任务阻塞升级 | 子任务阻塞时升级给人类 |
| 跨群组升级 | 升级到更高层级群组 |
| 功能 | 说明 |
|---------|----------------|
| 共识僵局升级 | 投票无法达成共识时升级给人类 |
| 子任务阻塞升级 | 子任务阻塞时升级给人类 |
| 跨群组升级 | 升级到更高层级群组 |
---
@@ -82,52 +84,52 @@ A2N 协议定义多个 Agent 组成群组进行协同工作的规范,包括群
### 3.1 群组管理消息(前缀 `group:`)
| 消息类型 | 说明 |
|---------|------|
| `group:create` | 创建群组 |
| `group:disband` | 解散群组 |
| `group:join` | 加入群组 |
| `group:leave` | 离开群组 |
| `group:invite` | 邀请加入 |
| `group:accept_invite` | 接受邀请 |
| `group:reject_invite` | 拒绝邀请 |
| 消息类型 | 说明 |
|-----------------------|--------|
| `group:create` | 创建群组 |
| `group:disband` | 解散群组 |
| `group:join` | 加入群组 |
| `group:leave` | 离开群组 |
| `group:invite` | 邀请加入 |
| `group:accept_invite` | 接受邀请 |
| `group:reject_invite` | 拒绝邀请 |
| `group:member_update` | 成员更新通知 |
| `group:role_change` | 角色变更 |
| `group:role_change` | 角色变更 |
### 3.2 群组通信消息(前缀 `group:`)
| 消息类型 | 说明 |
|---------|------|
| 消息类型 | 说明 |
|-------------------|----------|
| `group:broadcast` | 广播(所有成员) |
| `group:multicast` | 组播(指定成员) |
| `group:direct` | 群内单播 |
| `group:relay` | 消息中继 |
| `group:direct` | 群内单播 |
| `group:relay` | 消息中继 |
### 3.3 任务协作消息(前缀 `group:`)
| 消息类型 | 说明 |
|---------|------|
| `group:task_split` | 任务拆分 |
| `group:task_assign` | 任务分配 |
| `group:task_merge` | 结果合并 |
| 消息类型 | 说明 |
|-----------------------|-------|
| `group:task_split` | 任务拆分 |
| `group:task_assign` | 任务分配 |
| `group:task_merge` | 结果合并 |
| `group:task_progress` | 子任务进度 |
### 3.4 共识投票消息(前缀 `group:`)
| 消息类型 | 说明 |
|---------|------|
| `group:vote` | 发起投票 |
| 消息类型 | 说明 |
|---------------------|------|
| `group:vote` | 发起投票 |
| `group:vote_submit` | 提交投票 |
| `group:consensus` | 达成共识 |
| `group:consensus` | 达成共识 |
### 3.5 HiL 升级消息(前缀 `group:` / `inter_group:`)
| 消息类型 | 说明 |
|---------|------|
| `group:consensus_escalate` | 共识僵局升级给人类 |
| `group:subtask_escalate` | 子任务阻塞升级给人类 |
| `group:human_decision` | 人类决策结果 |
| `inter_group:escalate` | 跨群组升级 |
| 消息类型 | 说明 |
|----------------------------|------------|
| `group:consensus_escalate` | 共识僵局升级给人类 |
| `group:subtask_escalate` | 子任务阻塞升级给人类 |
| `group:human_decision` | 人类决策结果 |
| `inter_group:escalate` | 跨群组升级 |
---
@@ -135,49 +137,49 @@ A2N 协议定义多个 Agent 组成群组进行协同工作的规范,包括群
### 4.1 群组拓扑结构
| 拓扑类型 | 说明 | 适用场景 |
|---------|------|---------|
| `star` | 星型,中心 coordinator 协调 | 简单任务分发 |
| `mesh` | 网状,成员间可直接通信 | 对等协作 |
| `chain` | 链式,流水线模式 | 顺序处理 |
| `hierarchical` | 层级型,多层管理 | 大型复杂任务 |
| `fullmesh` | 全连接网状 | 高可靠协作 |
| 拓扑类型 | 说明 | 适用场景 |
|----------------|----------------------|--------|
| `star` | 星型,中心 coordinator 协调 | 简单任务分发 |
| `mesh` | 网状,成员间可直接通信 | 对等协作 |
| `chain` | 链式,流水线模式 | 顺序处理 |
| `hierarchical` | 层级型,多层管理 | 大型复杂任务 |
| `fullmesh` | 全连接网状 | 高可靠协作 |
### 4.2 成员角色
| 角色 | 说明 | 权限 |
|------|------|------|
| 角色 | 说明 | 权限 |
|---------------|-----|------------------------|
| `coordinator` | 协调者 | 创建/解散群组、任务拆分、发起投票、角色变更 |
| `worker` | 工作者 | 执行子任务、提交结果、投票 |
| `reviewer` | 审核者 | 审核结果、发起投票、升级请求 |
| `observer` | 观察者 | 只读,查看进度 |
| `worker` | 工作者 | 执行子任务、提交结果、投票 |
| `reviewer` | 审核者 | 审核结果、发起投票、升级请求 |
| `observer` | 观察者 | 只读,查看进度 |
### 4.3 群组状态
| 状态 | 说明 |
|------|------|
| `creating` | 创建中 |
| `active` | 活跃 |
| `frozen` | 冻结(不可执行新任务) |
| `disbanded` | 已解散(终态) |
| 状态 | 说明 |
|-------------|-------------|
| `creating` | 创建中 |
| `active` | 活跃 |
| `frozen` | 冻结(不可执行新任务) |
| `disbanded` | 已解散(终态) |
### 4.4 合并策略
| 策略 | 说明 |
|------|------|
| 策略 | 说明 |
|-----------------|-----------|
| `first_success` | 首个成功结果即返回 |
| `majority` | 多数结果合并 |
| `weighted` | 按权重加权合并 |
| `custom` | 自定义合并逻辑 |
| `majority` | 多数结果合并 |
| `weighted` | 按权重加权合并 |
| `custom` | 自定义合并逻辑 |
### 4.5 共识类型
| 类型 | 说明 |
|------|------|
| `majority` | 多数投票(>50%) |
| 类型 | 说明 |
|-----------------|------------|
| `majority` | 多数投票(>50%) |
| `supermajority` | 绝对多数(>67%) |
| `unanimity` | 一致同意(100%) |
| `weighted` | 加权投票 |
| `unanimity` | 一致同意(100%) |
| `weighted` | 加权投票 |
---
@@ -245,20 +247,20 @@ Coordinator 所有成员
### 6.2 流程步骤
1. **任务拆分阶段**
- Coordinator 接收原始任务
- 将任务拆分为多个子任务
- 为每个子任务指定执行的 Worker
- 定义合并策略
- Coordinator 接收原始任务
- 将任务拆分为多个子任务
- 为每个子任务指定执行的 Worker
- 定义合并策略
2. **并行执行阶段**
- 各 Worker 并行执行子任务
- 定期上报进度
- 子任务完成后上报结果
- 各 Worker 并行执行子任务
- 定期上报进度
- 子任务完成后上报结果
3. **结果合并阶段**
- Coordinator 收集所有子任务结果
- 按合并策略合并结果
- 返回最终结果
- Coordinator 收集所有子任务结果
- 按合并策略合并结果
- 返回最终结果
---
@@ -280,59 +282,59 @@ Coordinator 所有成员
### 8.1 群组创建载荷
| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `group_id` | string | ✓ | 群组唯一标识 |
| `group_name` | string | - | 群组名称 |
| `topology` | string | ✓ | 拓扑结构 |
| `config` | object | - | 群组配置 |
| 字段 | 类型 | 必填 | 说明 |
|--------------|--------|:--:|--------|
| `group_id` | string | ✓ | 群组唯一标识 |
| `group_name` | string | - | 群组名称 |
| `topology` | string | ✓ | 拓扑结构 |
| `config` | object | - | 群组配置 |
### 8.2 群组配置
| 字段 | 类型 | 说明 |
|------|------|------|
| `max_members` | integer | 最大成员数 |
| `vote_threshold` | float | 投票阈值 |
| `default_consensus_type` | string | 默认共识类型 |
| 字段 | 类型 | 说明 |
|--------------------------|---------|--------|
| `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 | ✓ | 子任务参数 |
| 字段 | 类型 | 必填 | 说明 |
|----------------|--------|:--:|--------------|
| `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 | - | 截止时间 |
| 字段 | 类型 | 必填 | 说明 |
|------------------|--------|:--:|------|
| `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 | - | 投票理由 |
| 字段 | 类型 | 必填 | 说明 |
|-------------|--------|:--:|--------|
| `vote_id` | string | ✓ | 投票标识 |
| `voter_id` | string | ✓ | 投票者 ID |
| `option_id` | string | ✓ | 选择的选项 |
| `reasoning` | string | - | 投票理由 |
### 8.6 共识结果载荷
| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `vote_id` | string | ✓ | 投票标识 |
| `winner` | string | ✓ | 获胜选项 |
| `vote_counts` | object | ✓ | 各选项票数 |
| `passed` | boolean | ✓ | 是否通过阈值 |
| 字段 | 类型 | 必填 | 说明 |
|---------------|---------|:--:|--------|
| `vote_id` | string | ✓ | 投票标识 |
| `winner` | string | ✓ | 获胜选项 |
| `vote_counts` | object | ✓ | 各选项票数 |
| `passed` | boolean | ✓ | 是否通过阈值 |
---
@@ -340,21 +342,21 @@ Coordinator 所有成员
### 9.1 升级场景
| 场景 | 消息类型 | 说明 |
|------|---------|------|
| 共识僵局 | `group:consensus_escalate` | 投票超时未达成共识 |
| 子任务阻塞 | `group:subtask_escalate` | 子任务执行受阻 |
| 跨群组 | `inter_group:escalate` | 升级到上级群组 |
| 场景 | 消息类型 | 说明 |
|-------|----------------------------|-----------|
| 共识僵局 | `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 | - | 可选方案 |
| 字段 | 类型 | 必填 | 说明 |
|--------------------|---------|:--:|-------------|
| `escalation_id` | string | ✓ | 升级标识 |
| `escalation_type` | string | ✓ | 升级类型 |
| `escalation_level` | integer | ✓ | 升级级别(1/2/3) |
| `context` | object | ✓ | 升级上下文 |
| `options` | array | - | 可选方案 |
---
@@ -362,16 +364,16 @@ Coordinator 所有成员
群组错误码分段:7000-7999
| 错误码 | 名称 | 说明 |
|------|------|------|
| 7001 | 群组不存在 | |
| 7002 | 群组未激活 | |
| 7003 | 成员不存在 | |
| 7004 | 不是群组成员 | |
| 7005 | 未达成共识 | |
| 7006 | 角色不存在 | |
| 7007 | 已是成员 | |
| 7008 | 群组已满 | |
| 错误码 | 名称 | 说明 |
|------|--------|----|
| 7001 | 群组不存在 | |
| 7002 | 群组未激活 | |
| 7003 | 成员不存在 | |
| 7004 | 不是群组成员 | |
| 7005 | 未达成共识 | |
| 7006 | 角色不存在 | |
| 7007 | 已是成员 | |
| 7008 | 群组已满 | |
---
@@ -379,12 +381,12 @@ Coordinator 所有成员
Agent 实现 A2N 协议时必须提供:
| 接口 | 说明 |
|------|------|
| 接口 | 说明 |
|---------|---------------|
| 群组管理处理器 | 处理群组创建、加入、离开等 |
| 子任务处理器 | 执行分配的子任务 |
| 投票处理器 | 处理投票相关消息 |
| 升级处理器 | 处理升级请求 |
| 子任务处理器 | 执行分配的子任务 |
| 投票处理器 | 处理投票相关消息 |
| 升级处理器 | 处理升级请求 |
---