synapse/docs/v1/01_raw-protocol.md

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