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

160
docs/v1/01_raw-protocol.md Normal file
View 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 必须在消息中声明自己使用的版本,接收方据此判断兼容性。