灵隙(synapse) v1.0.0 版本
This commit is contained in:
160
docs/v1/01-raw-protocol.md
Normal file
160
docs/v1/01-raw-protocol.md
Normal file
@@ -0,0 +1,160 @@
|
||||
# 灵隙原始协议(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 必须在消息中声明自己使用的版本,接收方据此判断兼容性。
|
||||
Reference in New Issue
Block a user