202 lines
14 KiB
Markdown
202 lines
14 KiB
Markdown
# 灵隙协议实现规范：消息扩展字段
|
||
|
||
> 版本：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)
|