灵隙(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

354
docs/v1/02_a2a-protocol.md Normal file
View File

@@ -0,0 +1,354 @@
# A2A 协议(Agent-to-Agent Protocol)
> 版本:1.0.0
> 状态:规范
> 层级:子协议层
> 基于:[灵隙原始协议](01_raw-protocol.md)
> 前缀:`p2p:`
---
## 1. 定位
A2A 协议定义两个 Agent 之间进行点对点任务协作的规范,包括任务提交、进度同步、信息补全、人类介入、能力发现等核心交互。
**适用场景**:
- 单个任务请求与响应
- 任务状态实时同步
- 任务取消
- 信息补全交互
- 人类介入决策
**非适用场景**:
- 多 Agent 群组协作(参见 A2N 协议)
- 非 Agent 调用方接入(参见 P2A 协议)
---
## 2. 功能定义
### 2.1 任务管理
| 功能 | 说明 |
|-----|------|
| 任务提交 | 请求方向执行方提交任务 |
| 任务确认 | 执行方接受任务 |
| 任务拒绝 | 执行方拒绝任务(附带原因) |
| 任务取消 | 请求方中途取消任务 |
| 任务进度 | 执行方实时上报进度 |
| 任务完成 | 执行方上报成功结果 |
| 任务失败 | 执行方上报失败原因 |
### 2.2 信息补全
| 功能 | 说明 |
|-----|------|
| 信息请求 | 执行方发现缺少必要信息时请求补充 |
| 信息提供 | 请求方提供补充信息 |
### 2.3 人类介入(HiL)
| 功能 | 说明 |
|-----|------|
| HiL 请求 | 执行方请求人类决策 |
| HiL 响应 | 请求方返回人类决策结果 |
### 2.4 能力发现
| 功能 | 说明 |
|-----|------|
| 能力查询 | 查询对方支持的任务类型和能力 |
| 能力响应 | 返回能力清单 |
### 2.5 保活与确认
| 功能 | 说明 |
|-----|------|
| 心跳 | 双向心跳保活 |
| ACK | 任务级确认 |
| 消息 ACK | 消息级确认 |
| 消息 NACK | 消息级否定确认(附带错误) |
---
## 3. 消息类型定义
所有消息类型前缀:`p2p:`
### 3.1 任务类消息
| 消息类型 | 方向 | 说明 |
|---------|------|------|
| `p2p:task_request` | 请求方 → 执行方 | 提交任务请求 |
| `p2p:task_confirm` | 执行方 → 请求方 | 确认接受任务 |
| `p2p:task_reject` | 执行方 → 请求方 | 拒绝任务 |
| `p2p:task_status_update` | 执行方 → 请求方 | 任务进度更新 |
| `p2p:task_complete` | 执行方 → 请求方 | 任务完成 |
| `p2p:task_failed` | 执行方 → 请求方 | 任务失败 |
| `p2p:task_cancel` | 请求方 → 执行方 | 取消任务 |
| `p2p:task_ack` | 双向 | 任务级确认 |
### 3.2 信息类消息
| 消息类型 | 方向 | 说明 |
|---------|------|------|
| `p2p:task_need_info` | 执行方 → 请求方 | 请求补充信息 |
| `p2p:task_info_provided` | 请求方 → 执行方 | 提供补充信息 |
### 3.3 HiL 类消息
| 消息类型 | 方向 | 说明 |
|---------|------|------|
| `p2p:task_need_human` | 执行方 → 请求方 | 请求人类介入 |
| `p2p:human_decision` | 请求方 → 执行方 | 人类决策结果 |
### 3.4 能力类消息
| 消息类型 | 方向 | 说明 |
|---------|------|------|
| `p2p:capability_query` | 双向 | 查询对方能力 |
| `p2p:capability_response` | 双向 | 返回能力清单 |
### 3.5 保活与确认类消息
| 消息类型 | 方向 | 说明 |
|---------|------|------|
| `p2p:heartbeat` | 双向 | 心跳保活 |
| `p2p:ack` | 双向 | 通用确认 |
| `p2p:nack` | 双向 | 通用否定确认 |
---
## 4. 任务状态机
### 4.1 状态定义
| 状态 | 说明 |
|------|------|
| `idle` | 空闲(初始状态) |
| `pending` | 待确认(已发送请求) |
| `confirmed` | 已确认(执行方接受) |
| `executing` | 执行中 |
| `info_needed` | 需要信息 |
| `info_provided` | 信息已提供 |
| `need_human` | 需要人类介入 |
| `human_deciding` | 人类决策中 |
| `human_approved` | 人类已批准 |
| `human_rejected` | 人类已拒绝 |
| `completed` | 已完成(终态) |
| `failed` | 已失败(终态) |
| `cancelled` | 已取消(终态) |
| `rejected` | 已拒绝(终态) |
### 4.2 状态流转
请求方视角:
```
idle → pending → confirmed → executing → completed
↓ ↓ → failed
rejected info_needed → cancelled
↑↓
info_provided
↓
need_human
↑↓
human_deciding
↓
human_approved / human_rejected
```
---
## 5. 交互流程
### 5.1 正常任务流程
```
请求方 执行方
| |
|---- p2p:task_request ------------>| 提交任务
| |
|<--- p2p:task_confirm -------------| 确认接受
| |
|<--- p2p:task_status_update (多次) --| 进度更新
| |
|<--- p2p:task_complete ------------| 完成通知
| |
|---- p2p:task_ack ---------------->| 确认收到
```
### 5.2 信息补全流程
```
请求方 执行方
| |
|---- p2p:task_request ------------>|
| |
|<--- p2p:task_need_info -----------| 发现信息缺失
| |
|---- p2p:task_info_provided ------->| 补充信息
| |
|<--- p2p:task_status_update -------| 继续执行
```
### 5.3 人类介入流程
```
请求方 执行方
| |
|---- p2p:task_request ------------>|
| |
|<--- p2p:task_need_human ----------| 需要人类决策
| |
| [人类做出决策] |
| |
|---- p2p:human_decision ---------->| 决策结果
| |
|<--- p2p:task_status_update -------| 继续执行
```
### 5.4 任务取消流程
```
请求方 执行方
| |
|---- p2p:task_request ------------>|
| |
|---- p2p:task_cancel ------------->| 取消任务
| |
|<--- p2p:task_ack -----------------| 确认取消
```
### 5.5 任务拒绝流程
```
请求方 执行方
| |
|---- p2p:task_request ------------>|
| |
|<--- p2p:task_reject --------------| 拒绝(附带原因)
```
---
## 6. 载荷结构定义
### 6.1 task_request 载荷
| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `task_id` | string | ✓ | 任务唯一标识(请求方生成) |
| `task_type` | string | ✓ | 任务类型 |
| `payload` | object | ✓ | 任务参数(结构由 task_type 决定) |
| `priority` | string | - | 优先级:`low`/`normal`/`high`/`urgent` |
| `transport_preferences` | object | - | 传输偏好(回调/轮询等) |
### 6.2 task_confirm 载荷
| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `task_id` | string | ✓ | 任务标识 |
| `estimated_time` | string | - | 预估耗时(如 "30s-2min") |
### 6.3 task_reject 载荷
| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `task_id` | string | ✓ | 任务标识 |
| `reason` | object | ✓ | 拒绝原因(含错误码和描述) |
### 6.4 task_status_update 载荷
| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `task_id` | string | ✓ | 任务标识 |
| `status` | string | ✓ | 当前状态 |
| `progress` | integer | - | 进度百分比(0-100) |
| `message` | string | - | 状态说明 |
| `eta` | string | - | 预估完成时间 |
### 6.5 task_complete 载荷
| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `task_id` | string | ✓ | 任务标识 |
| `result` | object | ✓ | 任务结果(结构由 task_type 决定) |
| `summary` | string | - | 结果摘要 |
| `metadata` | object | - | 结果元数据 |
### 6.6 task_failed 载荷
| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `task_id` | string | ✓ | 任务标识 |
| `error` | object | ✓ | 错误信息(错误码 + 描述 + 详情) |
### 6.7 task_need_info 载荷
| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `task_id` | string | ✓ | 任务标识 |
| `missing_fields` | array | ✓ | 缺失的字段列表 |
| `reason` | string | ✓ | 缺失原因 |
### 6.8 task_info_provided 载荷
| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `task_id` | string | ✓ | 任务标识 |
| `provided_info` | object | ✓ | 补充的信息 |
### 6.9 task_need_human 载荷
| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `task_id` | string | ✓ | 任务标识 |
| `escalation_level` | integer | ✓ | 升级级别(1/2/3) |
| `reason` | object | ✓ | 介入原因 |
| `options` | array | - | 可选方案列表 |
| `suggested_value` | object | - | Agent 建议值 |
### 6.10 human_decision 载荷
| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `task_id` | string | ✓ | 任务标识 |
| `decision` | object | ✓ | 决策内容 |
| `decided_by` | object | ✓ | 决策者信息(用户 ID + 角色) |
---
## 7. 错误处理
参见数字分段错误码系统(1000-9999):
| 分段 | 类别 |
|------|------|
| 1000-1999 | 系统错误 |
| 2000-2999 | 任务错误 |
| 3000-3999 | 信息错误 |
| 4000-4999 | 能力错误 |
| 5000-5999 | 安全错误 |
| 6000-6999 | 通信错误 |
---
## 8. 接口要求
Agent 实现 A2A 协议时必须提供:
| 接口 | 说明 |
|------|------|
| 消息处理器 | 接收并处理 p2p:* 类型消息 |
| 任务处理器 | 执行具体任务逻辑 |
| 回调发送器 | 发送进度、完成、失败等回调 |
| 状态查询 | 支持任务状态查询 |
---
## 9. 与其他协议的关系
- **依赖原始协议**:使用统一消息信封、签名机制
- **被 A2N 协议依赖**:群组内单播通信复用 A2A
- **被 P2A 协议封装**:外部调用最终转换为 A2A 消息