[!info] related notes

• 所属 MOC: AI Agent Application MOC
• 数据格式: Schema Versioning, Event Envelope
• 行为契约: 事件契约
• HTTP 入口: API 版本管理

Protocol Versioning

协议版本化管理通信双方对消息格式和交互行为的约定，不限于 SSE。本文以 AI 应用事件流为例；SSE 自身的线格式与应用事件协议版本是不同层次。

版本标识不等于兼容

版本可以在连接协商、URL、请求头或事件 envelope 中表达。放在哪里不决定是“大版本”还是“小版本”；关键是消费者能否正确理解行为。

除字段外，还要考虑事件顺序、重复投递、恢复游标、完成条件、错误处理和审批语义。即使 JSON 结构不变，行为变化也可能破坏旧客户端。

接收规则

读取并校验版本标识
  → 已支持版本：按对应格式和行为处理
  → 缺版本：只有契约明确约定 legacy 默认值时才采用该值
  → 未知版本：拒绝、协商或请求升级，不默认按 v1 处理

连接协商还需定义双方支持版本集合、选定结果与无交集时的失败行为。事件中自报版本不是消费者支持该版本的证明。

未知事件类型

• 只有契约规定为可忽略的扩展事件，旧客户端才可跳过。
• 未知的审批、权限、状态变更或终态事件不能随意忽略后继续执行。
• 新增 heartbeat 一类可选事件也需确认旧解析器行为；添加一个类型字段不会自动获得向后兼容性。

发布与恢复

先部署能识别新旧协议的消费者，再按策略启用新生产者；保留兼容窗口和明确的弃用路径。持久化事件回放时，还需能识别事件当时的版本，而不是全部交给当前解析器。

测试覆盖新旧生产者与消费者组合、未知版本、未知关键事件、重复事件和断线恢复。具体字段位置与名称遵循项目既有 事件契约，不在概念笔记中另立一套全局协议。