[!info] related notes

• 所属 MOC: AI Agent Application MOC
• 语义: 事件契约, Event Type
• 演进: Schema Versioning, Protocol Versioning
• 载体: SSE

Event Envelope

Event Envelope 为应用事件提供共同的包装结构，承载事件类型、payload 与相关元数据。它可以经 SSE、消息队列或其他方式传输，不是 SSE 标准规定的 JSON 格式。

结构示例

以下沿用本组笔记的 event / data / meta 表达，只作设计示例，不声明所有项目都使用这些字段：

{
  "event": "text_delta",
  "data": { "delta": "你好" },
  "meta": {
    "run_id": "run_001",
    "sequence": 1,
    "timestamp": 1719700000
  }
}

示例 timestamp 约定为 Unix 秒；真实契约需固定单位。sequence 也需明确是在 run、连接还是其他范围内递增，不能只凭一个数字跨流排序。

SSE 承载同一个 envelope

id: run_001:1
event: text_delta
data: {"event":"text_delta","data":{"delta":"你好"},"meta":{"run_id":"run_001","sequence":1,"timestamp":1719700000}}

空行终止 SSE 事件。这里 data: 中放完整 JSON envelope，不能与“只放 payload”的另一种约定混用。若 SSE 的 event: 和 JSON 内 event 同时出现，协议应定义一致性校验。

SSE id: 是传输恢复标识；本例将其与 run/sequence 对应只是一个选择。服务器是否支持按该 ID 重放、保留多久，必须另行实现。

类型与校验

仅使用 EventEnvelope<T>，同时把 event 定成任意字符串，不能保证事件名与 payload 匹配。TypeScript 可用以字面量事件名区分的联合类型表达关联，网络输入仍需按对应 schema 做运行时校验。

元数据字段需有明确所有者。转发层不应随意重写生产时间、序号或身份；需要接收时间、转发时间时，按既有契约区分。

参考

• WHATWG：Server-sent events