灵隙(synapse) v1.0.0 版本
This commit is contained in:
lychang
201
docs/implement/message-extensions.md
Normal file
201
docs/implement/message-extensions.md
Normal file
@@ -0,0 +1,201 @@
|
||||
# 灵隙协议实现规范：消息扩展字段
|
||||
|
||||
> 版本：1.0.0 | 层级：实现层
|
||||
|
||||
---
|
||||
|
||||
## 1. 消息扩展字段总览
|
||||
|
||||
统一消息信封 `UnifiedSynapseMessage` 在原始协议基础字段之上，扩充了以下扩展字段，用于支持会话关联、传输控制、群组精准投递及安全声明等高级功能。
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `ConversationID` | `string` | 会话 ID，用于多轮对话关联 |
|
||||
| `TTL` | `int` | 消息存活时间，单位秒；超时后由灵泊（Harbor）自动清理 |
|
||||
| `Broadcast` | `bool` | 是否广播；为 `true` 时消息将发送至群组所有成员 |
|
||||
| `Encrypt` | `bool` | 标识 payload 是否已加密；接收方据此决定是否解密 |
|
||||
| `TargetType` | `GroupTargetType` | 群组目标类型，定义消息在群组内的投递范围 |
|
||||
| `TargetIDs` | `[]string` | 目标 ID 列表，与 `TargetType` 配合使用 |
|
||||
| `SignatureAlgorithm` | `string` | 签名算法声明，接收方据此选择验证方式 |
|
||||
|
||||
### 代码定义
|
||||
|
||||
```go
|
||||
type UnifiedSynapseMessage struct {
|
||||
// 基础字段（协议定义）
|
||||
ID string `json:"id"`
|
||||
Version string `json:"version"`
|
||||
Type string `json:"type"`
|
||||
Sender AgentEndpoint `json:"sender"`
|
||||
Receiver *AgentEndpoint `json:"receiver,omitempty"`
|
||||
CorrelationID string `json:"correlation_id,omitempty"`
|
||||
ReplyTo string `json:"reply_to,omitempty"`
|
||||
GroupID string `json:"group_id,omitempty"`
|
||||
Payload json.RawMessage `json:"payload"`
|
||||
Timestamp Timestamp `json:"timestamp"`
|
||||
Signature string `json:"signature,omitempty"`
|
||||
|
||||
// 扩展字段（实现补充）
|
||||
ConversationID string `json:"conversation_id,omitempty"`
|
||||
TTL int `json:"ttl,omitempty"`
|
||||
Broadcast bool `json:"broadcast,omitempty"`
|
||||
Encrypt bool `json:"encrypt,omitempty"`
|
||||
TargetType GroupTargetType `json:"target_type,omitempty"`
|
||||
TargetIDs []string `json:"target_ids,omitempty"`
|
||||
SignatureAlgorithm string `json:"signature_algorithm,omitempty"`
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 群组目标类型
|
||||
|
||||
`GroupTargetType` 枚举定义了消息在群组内的三种目标选择策略，用于精确控制消息的投递范围，避免向无关成员发送无关消息。
|
||||
|
||||
```go
|
||||
type GroupTargetType string
|
||||
|
||||
const (
|
||||
TargetTypeAll GroupTargetType = "all" // 所有成员
|
||||
TargetTypeRole GroupTargetType = "role" // 按角色
|
||||
TargetTypeSpecific GroupTargetType = "specific" // 指定成员
|
||||
)
|
||||
```
|
||||
|
||||
### 字段说明表
|
||||
|
||||
| 值 | 常量名 | 含义 | TargetIDs 用法 |
|
||||
|----|--------|------|----------------|
|
||||
| `"all"` | `TargetTypeAll` | 发送给群组内所有成员 | 忽略 `TargetIDs`，即使有值也不参与路由 |
|
||||
| `"role"` | `TargetTypeRole` | 按角色筛选成员 | `TargetIDs` 填入角色名称列表（如 `["admin","operator"]`），仅匹配这些角色的成员会收到消息 |
|
||||
| `"specific"` | `TargetTypeSpecific` | 发送给指定的若干成员 | `TargetIDs` 填入成员 AgentID 列表，精确投递 |
|
||||
|
||||
### 使用约束
|
||||
|
||||
- 仅在 `GroupID` 非空时生效。若 `GroupID` 为空，`TargetType` 和 `TargetIDs` 将被忽略。
|
||||
- 默认值为空字符串，此时行为等同于 `"all"`（全量投递）。
|
||||
- `TargetType` 与 `Broadcast` 的关系：当 `Broadcast` 为 `true` 时，`TargetType` 仍可进一步缩小广播范围；两者协同工作而非互斥。
|
||||
|
||||
---
|
||||
|
||||
## 3. 各字段用途说明表
|
||||
|
||||
| 字段名 | 类型 | 用途 | 使用场景 | 示例值 |
|
||||
|--------|------|------|----------|--------|
|
||||
| `ConversationID` | `string` | 关联同一会话的多条消息，形成对话上下文 | 多轮问答、连续任务编排、长对话跟踪 | `"conv-a1b2c3d4"` |
|
||||
| `TTL` | `int` | 消息的存活时长，超时后由灵泊组件自动丢弃 | 临时通知、时效性指令、过期任务取消 | `300`（5 分钟） |
|
||||
| `Broadcast` | `bool` | 标记消息是否为广播，指示接收方是否需要扩散 | 群组公告、系统通知、状态广播 | `true` |
|
||||
| `Encrypt` | `bool` | 标记 payload 是否已加密，接收方据此触发解密流程 | 包含敏感数据的消息、跨信任域通信 | `true` |
|
||||
| `TargetType` | `GroupTargetType` | 群组内的目标选择策略 | 按角色下发命令、定向通知指定成员 | `"role"` |
|
||||
| `TargetIDs` | `[]string` | 配合 `TargetType` 提供目标标识列表 | 指定角色名列表或成员 ID 列表 | `["admin","operator"]` |
|
||||
| `SignatureAlgorithm` | `string` | 声明消息签名所使用的算法，接收方选择对应验证逻辑 | 多算法共存场景、算法升级过渡期 | `"HMAC-SHA256"` |
|
||||
|
||||
---
|
||||
|
||||
## 4. 扩展字段与基础字段关系图
|
||||
|
||||
下图展示了包含扩展字段在内的完整 `UnifiedSynapseMessage` 结构层次。
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ UnifiedSynapseMessage │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────┐│
|
||||
│ │ 基础字段 ││
|
||||
│ │ ││
|
||||
│ │ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ ││
|
||||
│ │ │ ID │ │ Version │ │ Type │ ││
|
||||
│ │ └──────────┘ └──────────┘ └──────────────────┘ ││
|
||||
│ │ ││
|
||||
│ │ ┌────────────────────────────────────────────────┐ ││
|
||||
│ │ │ Sender (AgentEndpoint) │ ││
|
||||
│ │ │ ┌─────────┐ ┌──────────┐ ┌────────────────┐ │ ││
|
||||
│ │ │ │AgentID │ │AgentName │ │ Endpoint │ │ ││
|
||||
│ │ │ └─────────┘ └──────────┘ └────────────────┘ │ ││
|
||||
│ │ │ ┌─────────┐ ┌──────────┐ ┌────────────────┐ │ ││
|
||||
│ │ │ │SystemID │ │Version │ │ Capabilities │ │ ││
|
||||
│ │ │ └─────────┘ └──────────┘ └────────────────┘ │ ││
|
||||
│ │ └────────────────────────────────────────────────┘ ││
|
||||
│ │ ││
|
||||
│ │ ┌──────────┐ ┌──────────────┐ ┌──────────────┐ ││
|
||||
│ │ │ Receiver │ │CorrelationID │ │ ReplyTo │ ││
|
||||
│ │ │(optional)│ │ │ │ │ ││
|
||||
│ │ └──────────┘ └──────────────┘ └──────────────┘ ││
|
||||
│ │ ││
|
||||
│ │ ┌──────────┐ ┌──────────────────────────────────┐ ││
|
||||
│ │ │ GroupID │ │ Payload │ ││
|
||||
│ │ │ │ │ (json.RawMessage) │ ││
|
||||
│ │ └──────────┘ └──────────────────────────────────┘ ││
|
||||
│ │ ││
|
||||
│ │ ┌──────────┐ ┌──────────┐ ││
|
||||
│ │ │Timestamp │ │Signature │ ││
|
||||
│ │ └──────────┘ └──────────┘ ││
|
||||
│ └─────────────────────────────────────────────────────┘│
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────┐│
|
||||
│ │ 扩展字段 ││
|
||||
│ │ ││
|
||||
│ │ ┌────────────────┐ ┌──────┐ ┌──────────┐ ││
|
||||
│ │ │ ConversationID │ │ TTL │ │ Broadcast│ ││
|
||||
│ │ └────────────────┘ └──────┘ └──────────┘ ││
|
||||
│ │ ││
|
||||
│ │ ┌──────────┐ ┌──────────────────────────────────┐ ││
|
||||
│ │ │ Encrypt │ │ TargetType + TargetIDs │ ││
|
||||
│ │ │ │ │ (群组目标选择) │ ││
|
||||
│ │ └──────────┘ └──────────────────────────────────┘ ││
|
||||
│ │ ││
|
||||
│ │ ┌────────────────────────────────────────────────┐ ││
|
||||
│ │ │ SignatureAlgorithm │ ││
|
||||
│ │ │ (签名算法声明) │ ││
|
||||
│ │ └────────────────────────────────────────────────┘ ││
|
||||
│ └─────────────────────────────────────────────────────┘│
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 层次说明
|
||||
|
||||
| 层级 | 包含字段 | 职责 |
|
||||
|------|----------|------|
|
||||
| **标识层** | `ID`, `Version`, `Type` | 消息唯一标识与协议版本声明 |
|
||||
| **源端层** | `Sender` (AgentEndpoint) | 发送方端点信息，含身份、能力与路由地址 |
|
||||
| **目标层** | `Receiver`, `GroupID`, `TargetType`, `TargetIDs` | 点对点或群组目标寻址 |
|
||||
| **控制层** | `CorrelationID`, `ReplyTo`, `ConversationID` | 消息关联、回复与会话跟踪 |
|
||||
| **数据层** | `Payload` | 业务负载，JSON 格式 |
|
||||
| **传输层** | `TTL`, `Broadcast`, `Priority`, `ExpiresAt` | 传输行为控制与生命周期管理 |
|
||||
| **安全层** | `Signature`, `SignatureAlgorithm`, `Encrypt` | 完整性保护、算法声明与负载加密 |
|
||||
| **时间层** | `Timestamp` | 消息产生时间，ISO 8601 格式 |
|
||||
|
||||
### 扩展字段与基础字段的协作关系
|
||||
|
||||
```
|
||||
发送流程 接收流程
|
||||
───────── ─────────
|
||||
|
||||
发方构造消息 收方解析消息
|
||||
│ │
|
||||
▼ ▼
|
||||
┌──────────────┐ ┌──────────────┐
|
||||
│ 填写基础字段 │ │ 校验基础字段 │
|
||||
│ ID, Sender, │─────────▶ │ ID, Type, │
|
||||
│ Type, Payload│ │ Signature │
|
||||
└──────────────┘ └──────────────┘
|
||||
│ │
|
||||
▼ ▼
|
||||
┌──────────────┐ ┌──────────────┐
|
||||
│ 设置扩展字段 │ │ 读取扩展字段 │
|
||||
│ │ │ │
|
||||
│ • ConversationID ──────▶ │ • 恢复会话 │
|
||||
│ • TTL ──────▶ │ • 设置超时 │
|
||||
│ • Broadcast ──────▶ │ • 判断扩散 │
|
||||
│ • Encrypt ──────▶ │ • 触发解密 │
|
||||
│ • TargetType ──────▶ │ • 筛选成员 │
|
||||
│ • TargetIDs ──────▶ │ • 精确投递 │
|
||||
│ • SigAlgo ──────▶ │ • 选择验证 │
|
||||
└──────────────┘ └──────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**参考来源**
|
||||
- [v0 实现细节 - 第 7 章：消息扩展字段](file:///e:/code/go/synapse/docs/v0/06-implementation-details.md#1088)
|
||||
- [UnifiedSynapseMessage 类型定义](file:///e:/code/go/synapse/pkg/types/types.go#L197-L236)
|
||||
Reference in New Issue
Block a user