14 KiB
14 KiB
灵隙协议实现规范：消息扩展字段
版本：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 |
签名算法声明，接收方据此选择验证方式 |
代码定义
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 枚举定义了消息在群组内的三种目标选择策略，用于精确控制消息的投递范围，避免向无关成员发送无关消息。
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 ──────▶ │ • 选择验证 │
└──────────────┘ └──────────────┘
参考来源