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