160 lines
4.0 KiB
Markdown
160 lines
4.0 KiB
Markdown
# 灵隙原始协议（Synapse Raw Protocol）
|
||
|
||
> 版本：1.0.0
|
||
> 状态：规范
|
||
> 层级：基础层
|
||
|
||
---
|
||
|
||
## 1. 定位
|
||
|
||
原始协议定义灵隙协议栈的公共基础，为所有子协议（A2A、A2N、P2A）提供统一的消息信封、身份标识、时间格式和签名机制。
|
||
|
||
---
|
||
|
||
## 2. 功能定义
|
||
|
||
### 2.1 核心功能
|
||
|
||
| 功能 | 说明 |
|
||
|-----|------|
|
||
| 统一消息信封 | 所有协议共用的消息格式 |
|
||
| 身份标识 | Agent 端点定义 |
|
||
| 时间戳 | 统一时间格式（RFC3339） |
|
||
| 消息签名 | HMAC 签名验证机制 |
|
||
| 关联机制 | correlation_id / reply_to 消息关联 |
|
||
| 协议版本 | 版本标识与兼容性 |
|
||
|
||
### 2.2 扩展功能
|
||
|
||
| 功能 | 说明 |
|
||
|-----|------|
|
||
| 会话关联 | conversation_id 多轮对话关联 |
|
||
| 消息存活 | TTL 消息过期机制 |
|
||
| 广播标识 | broadcast 广播消息标记 |
|
||
| 加密标识 | encrypt 消息加密标记 |
|
||
| 签名算法 | signature_algorithm 签名算法声明 |
|
||
|
||
---
|
||
|
||
## 3. 数据格式定义
|
||
|
||
### 3.1 统一消息信封
|
||
|
||
所有协议消息必须使用统一信封格式：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|:----:|------|
|
||
| `id` | string | ✓ | 消息唯一标识（UUID） |
|
||
| `version` | string | ✓ | 协议版本（如 "1.0.0"） |
|
||
| `type` | string | ✓ | 消息类型（格式：`协议:类型`，如 `p2p:task_request`） |
|
||
| `sender` | AgentEndpoint | ✓ | 发送方端点 |
|
||
| `receiver` | AgentEndpoint | - | 接收方端点（广播时可为空） |
|
||
| `payload` | object | ✓ | 消息载荷（具体结构由消息类型定义） |
|
||
| `timestamp` | string | ✓ | 时间戳（RFC3339 格式） |
|
||
|
||
### 3.2 关联字段
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|:----:|------|
|
||
| `correlation_id` | string | - | 关联 ID（用于请求-响应关联） |
|
||
| `reply_to` | string | - | 回复的消息 ID |
|
||
| `group_id` | string | - | 群组 ID（群组消息必填） |
|
||
|
||
### 3.3 安全字段
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|:----:|------|
|
||
| `signature` | string | - | HMAC 签名（签名算法由 signature_algorithm 指定） |
|
||
| `signature_algorithm` | string | - | 签名算法（默认 "HMAC-SHA256"） |
|
||
|
||
### 3.4 扩展字段
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `conversation_id` | string | 会话 ID（多轮对话关联） |
|
||
| `ttl` | integer | 消息存活时间（秒） |
|
||
| `broadcast` | boolean | 是否广播消息 |
|
||
| `encrypt` | boolean | payload 是否加密 |
|
||
|
||
### 3.5 Agent 端点
|
||
|
||
Agent 身份标识结构：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|:----:|------|
|
||
| `agent_id` | string | ✓ | Agent 唯一标识 |
|
||
| `agent_name` | string | - | Agent 名称 |
|
||
| `system_id` | string | ✓ | 所属系统标识 |
|
||
| `endpoint` | string | ✓ | 回调端点 URL |
|
||
| `version` | string | - | Agent 版本 |
|
||
|
||
---
|
||
|
||
## 4. 签名机制
|
||
|
||
### 4.1 签名算法
|
||
|
||
支持算法：
|
||
- `HMAC-SHA256`（默认）
|
||
- `HMAC-SHA512`
|
||
|
||
### 4.2 签名内容
|
||
|
||
签名内容为以下字段的拼接（UTF-8 编码）：
|
||
|
||
```
|
||
signature_content = sender_id | receiver_id | timestamp | payload_json
|
||
```
|
||
|
||
分隔符：`|`（竖线）
|
||
|
||
### 4.3 签名验证
|
||
|
||
接收方必须：
|
||
1. 提取 sender 的认证密钥
|
||
2. 使用相同算法重新计算签名
|
||
3. 比对签名是否一致
|
||
|
||
---
|
||
|
||
## 5. 协议类型前缀
|
||
|
||
| 前缀 | 协议 | 说明 |
|
||
|------|------|------|
|
||
| `p2p:` | A2A 协议 | 点对点消息 |
|
||
| `group:` | A2N 协议 | 群组内消息 |
|
||
| `inter_group:` | A2N 协议 | 跨群组消息 |
|
||
| `caller:` | P2A 协议 | 外部调用消息 |
|
||
|
||
---
|
||
|
||
## 6. 消息类型命名规范
|
||
|
||
格式：`协议前缀:消息类型`
|
||
|
||
示例：
|
||
- `p2p:task_request` - A2A 协议的任务请求
|
||
- `group:vote` - A2N 协议的投票消息
|
||
- `inter_group:escalate` - A2N 协议的跨群组升级
|
||
|
||
---
|
||
|
||
## 7. 时间格式
|
||
|
||
所有时间字段使用 RFC3339 格式：
|
||
|
||
```
|
||
2026-06-27T15:30:00Z
|
||
2026-06-27T15:30:00+08:00
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 版本兼容性
|
||
|
||
- 主版本号变更：不兼容
|
||
- 次版本号变更：新增功能，向后兼容
|
||
- 修订号变更：修复问题，完全兼容
|
||
|
||
Agent 必须在消息中声明自己使用的版本，接收方据此判断兼容性。 |