# 灵隙原始协议（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 必须在消息中声明自己使用的版本，接收方据此判断兼容性。