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

335
docs/v1/04_p2a-protocol.md Normal file
View File

@@ -0,0 +1,335 @@
# P2A 协议(Person/Program-to-Agent Protocol)
> 版本:1.0.0
> 状态:规范
> 层级:子协议层
> 基于:[灵隙原始协议](01_raw-protocol.md)
> 前缀:`caller:`(内部转换)
---
## 1. 定位
P2A 协议定义**非 Agent 调用方**(如普通后端服务、前端应用、第三方系统、人类用户)如何调用 Agent 能力的规范。
本协议将 A2A 协议的复杂性封装起来,提供简洁的 RESTful API,使调用方无需了解 A2A 协议细节即可使用 Agent 能力。
**适用场景**:
- 前端应用直接调用 Agent 能力
- 后端业务系统集成 Agent 服务
- 第三方开发者通过 API 接入
- 无需实现完整 A2A 协议的调用方
**设计原则**:
- **简单易用**:标准 RESTful API,JSON 格式
- **两种模式**:回调模式 + 轮询模式,调用方按需选择
- **认证简单**:API Key 认证,无需 HMAC 签名
- **文件支持**:支持 multipart/form-data 上传文件
- **错误友好**:清晰的错误码和错误信息
---
## 2. 功能定义
### 2.1 任务提交
| 功能 | 说明 |
|-----|------|
| JSON 提交 | application/json 格式提交任务 |
| Multipart 提交 | 带文件上传的任务提交 |
### 2.2 任务查询
| 功能 | 说明 |
|-----|------|
| 任务详情 | 获取完整任务信息(含结果) |
| 任务状态 | 简化版状态查询 |
| 任务列表 | 分页查询任务列表 |
### 2.3 任务控制
| 功能 | 说明 |
|-----|------|
| 任务取消 | 取消正在执行的任务 |
### 2.4 能力查询
| 功能 | 说明 |
|-----|------|
| 能力清单 | 获取 Agent 支持的任务类型 |
### 2.5 通知机制
| 功能 | 说明 |
|-----|------|
| 回调通知 | 任务完成后主动回调调用方 |
| 轮询查询 | 调用方主动查询状态 |
### 2.6 认证
| 功能 | 说明 |
|-----|------|
| API Key 认证 | X-API-Key 头部认证 |
| 回调验证 | X-Callback-Token 验证回调来源 |
---
## 3. API 端点定义
所有端点默认前缀:`/api/v1/synapse`
### 3.1 端点清单
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/task` | 提交任务(JSON) |
| POST | `/task/multipart` | 提交任务(带文件上传) |
| GET | `/task/{task_id}` | 获取任务详情 |
| GET | `/task/{task_id}/status` | 获取任务状态(简化版) |
| GET | `/tasks` | 获取任务列表 |
| POST | `/task/{task_id}/cancel` | 取消任务 |
| GET | `/capabilities` | 获取能力清单 |
---
## 4. 任务状态定义
P2A 协议使用简化状态(5 种):
| 状态 | 说明 |
|------|------|
| `received` | 已接收 |
| `processing` | 处理中 |
| `completed` | 已完成(终态) |
| `failed` | 已失败(终态) |
| `cancelled` | 已取消(终态) |
状态流转:
```
received → processing → completed
→ failed
→ cancelled
```
---
## 5. 认证方式
### 5.1 API Key 认证
传递方式:
- HTTP Header:`X-API-Key: {api_key}`
- URL Query:`?api_key={api_key}`
如果服务端未配置 API Key,则跳过认证。
### 5.2 回调验证(可选)
如果调用方提供了 `callback_token`,则服务端在回调时会在 Header 中带上 `X-Callback-Token`,用于调用方验证回调来源。
---
## 6. 请求结构定义
### 6.1 任务提交请求(JSON)
| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `task_type` | string | ✓ | 任务类型(如 `text_generation`) |
| `payload` | object | ✓ | 任务参数(结构由 task_type 决定) |
| `external_task_id` | string | - | 调用方的任务 ID,用于关联 |
| `priority` | string | - | 优先级:`low`/`normal`/`high`/`urgent`,默认 `normal` |
| `callback_url` | string | - | 回调 URL,不提供则需轮询 |
| `callback_token` | string | - | 回调验证 token |
### 6.2 任务提交请求(Multipart)
| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `task_type` | string | ✓ | 任务类型 |
| `payload` | string(JSON) | ✓ | 任务参数(JSON 字符串) |
| `external_task_id` | string | - | 外部任务 ID |
| `priority` | string | - | 优先级 |
| `callback_url` | string | - | 回调 URL |
| `callback_token` | string | - | 回调 token |
| `file` | file | - | 上传的文件(可多个) |
---
## 7. 响应结构定义
### 7.1 任务提交响应
| 字段 | 类型 | 说明 |
|------|------|------|
| `success` | boolean | 是否成功 |
| `task_id` | string | 服务端生成的任务 ID |
| `status` | string | 初始状态(通常为 `received`) |
| `message` | string | 提示信息 |
| `error` | object | 错误信息(失败时) |
### 7.2 任务详情响应
| 字段 | 类型 | 说明 |
|------|------|------|
| `success` | boolean | 是否成功 |
| `task` | object | 任务详情 |
| `error` | object | 错误信息 |
### 7.3 任务详情结构
| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 任务 ID |
| `type` | string | 任务类型 |
| `status` | string | 任务状态 |
| `progress` | integer | 进度百分比(0-100) |
| `message` | string | 状态说明 |
| `created_at` | string | 创建时间(RFC3339) |
| `updated_at` | string | 更新时间(RFC3339) |
| `completed_at` | string | 完成时间(RFC3339) |
| `eta` | string | 预估完成时间 |
| `result` | object | 任务结果(结构由 task_type 决定) |
| `error` | object | 错误信息 |
### 7.4 任务列表响应
| 字段 | 类型 | 说明 |
|------|------|------|
| `success` | boolean | 是否成功 |
| `tasks` | array | 任务列表 |
| `total` | integer | 总数 |
| `limit` | integer | 每页数量 |
| `offset` | integer | 偏移量 |
| `has_more` | boolean | 是否有更多 |
### 7.5 能力清单响应
| 字段 | 类型 | 说明 |
|------|------|------|
| `agent_id` | string | Agent 唯一标识 |
| `agent_name` | string | Agent 名称 |
| `protocol_version` | string | 协议版本 |
| `supported_task_types` | array | 支持的任务类型列表 |
| `supported_content_types` | array | 支持的内容类型 |
| `max_file_size` | integer | 最大文件大小(字节) |
| `max_concurrent_tasks` | integer | 最大并发任务数 |
| `max_task_duration` | integer | 最大任务时长(秒) |
| `support_progress_updates` | boolean | 是否支持进度更新 |
| `support_streaming` | boolean | 是否支持流式传输 |
| `support_hil` | boolean | 是否支持人类介入 |
| `support_groups` | boolean | 是否支持群组协作 |
### 7.6 任务类型能力
| 字段 | 类型 | 说明 |
|------|------|------|
| `type` | string | 任务类型标识 |
| `name` | string | 任务类型名称 |
| `description` | string | 描述 |
| `estimated_time` | string | 预估耗时(如 "30s-2min") |
| `input_schema` | string | 输入 Schema |
| `output_schema` | string | 输出 Schema |
| `capabilities` | array | 所需能力列表 |
---
## 8. 回调结构定义
### 8.1 回调请求
当任务完成时,服务端向调用方提供的 `callback_url` 发送回调:
| 字段 | 类型 | 说明 |
|------|------|------|
| `task_id` | string | 任务 ID |
| `external_task_id` | string | 外部任务 ID(如有) |
| `status` | string | 任务状态 |
| `progress` | integer | 进度 |
| `result` | object | 任务结果 |
| `error` | object | 错误信息 |
| `timestamp` | string | 时间戳(RFC3339) |
### 8.2 回调 Header
| Header | 说明 |
|--------|------|
| `X-Callback-Token` | 回调验证 token(如调用方提供了 callback_token) |
| `Content-Type` | `application/json` |
---
## 9. 错误响应结构
| 字段 | 类型 | 说明 |
|------|------|------|
| `success` | boolean | false |
| `error` | object | 错误详情 |
错误详情结构:
| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | integer | 数字错误码 |
| `category` | string | 错误类别 |
| `message` | string | 错误描述 |
| `details` | object | 详细信息 |
| `retry_after` | integer | 重试等待时间(秒) |
---
## 10. 传输模式
### 10.1 回调模式
调用方提供 `callback_url`:
- 任务状态变化时主动回调
- 无需轮询
- 适用于实时性要求高的场景
### 10.2 轮询模式
调用方不提供 `callback_url`:
- 需主动调用 `/task/{task_id}/status` 查询
- 适用于无法接收回调的场景
- 推荐轮询间隔:5-10 秒
### 10.3 混合模式
调用方提供 `callback_url`,同时支持轮询:
- 回调为主,轮询兜底
- 适用于高可靠性场景
---
## 11. 与 A2A 协议的关系
```
外部调用方 ──P2A REST API──▶ External API Layer ──A2A 消息──▶ Agent
```
P2A 协议是 A2A 协议的"简化入口":
| P2A API | A2A 消息映射 |
|---------|-------------|
| POST `/task` | `p2p:task_request` |
| GET `/task/{id}` | 内部状态查询 |
| POST `/task/{id}/cancel` | `p2p:task_cancel` |
| GET `/capabilities` | `p2p:capability_query` + `p2p:capability_response` |
| 回调发送 | `p2p:task_complete` / `p2p:task_failed` 等 |
---
## 12. 接口要求
实现 P2A 协议的服务端必须提供:
| 接口 | 说明 |
|------|------|
| 任务接收端点 | 接收任务提交请求 |
| 任务查询端点 | 提供任务状态和结果查询 |
| 任务取消端点 | 支持任务取消 |
| 能力查询端点 | 提供能力清单 |
| 回调发送器 | 支持向调用方回调 |
| A2A 转换器 | 将 P2A 请求转换为 A2A 消息 |