跳到主要内容

快照与增量

1.0:演进值如何传输——整体替换,JSON Patch 修订。

生产者报告的某些内容不是文本流,而是会演进的值:智能体状态、活动内容、会话本身。它们以快照(替换)与增量(修订)传输。

三个族使用该模式:状态(STATE_SNAPSHOT、STATE_DELTA,以及用于会话的 MESSAGES_SNAPSHOT)与活动(ACTIVITY_SNAPSHOT、ACTIVITY_DELTA)。本页陈述它们共有的内容;各族页面陈述各自替换与修订什么。

快照

快照携带完整值。消费者 MUST 用快照内容替换自己的副本——快照不是合并——除非快照本身通过其族定义的字段选择不替换(活动的 replace: false 是唯一情形)。

在它之前的增量都已作废:快照——无论被应用还是被拒绝——都是新的基线时刻。

生产者 MAY 在任何时候发送快照,并 SHOULD 在无法保证消费者基线与自身一致时发送:出错之后、增量无法表达的内容之后,或继续旧线程的运行开始时。

增量

增量修订当前值,表达为 RFC 6902 JSON Patch:按序应用的操作数组,原子地——若任一操作失败,文档保持原样。

  • 增量针对消费者当前值应用:最后一次快照经此后每个增量修订后的结果。对状态而言,运行起始值是输入的 state,当输入未携带时为 {}。
  • 生产者 MUST NOT 为它未给消费者基线的值发送增量。什么算基线由族决定——状态从输入就有,活动只有在其首个快照之后才有。
  • Patch 操作是刻意开放的对象:schema 如此标记,RFC 6902 未定义的成员是协议合法内容,处理模型 MUST NOT 剥离。

当 patch 无法应用

结构有效并不意味着 patch 可应用:格式良好的操作可能指向不存在的路径,RFC 6902 把这一点留给应用者。格式错误的操作——patch 不是数组、操作缺少必填成员或成员类型错误——是已知值的格式错误,与其他一样致命。op 命名 RFC 6902 未定义内容的操作不是格式错误,而是未识别——在本消费者发布之后加入的判别联合成员——处理模型的列表规则适用:该元素从 patch 中丢弃并警告,运行存活。

格式良好但应用失败的 patch 又是另一回事:

  • 消费者 MUST NOT 保留部分应用的结果——RFC 6902 应用是原子的。
  • 消费者 MUST 暴露失败——给出足以诊断的警告,说明什么失败及原因——并 MAY 继续使用先前的值而非让运行失败。
  • 失败的 test 操作属于同一情形:patch 不应用,消费者保留先前的值。

从那一刻起,消费者的值可能已与生产者分歧。得知或无法排除这一点的生产者 SHOULD 用快照重新同步;消费者 MUST 采用下一个快照,无论此前跳过了什么——这正是恢复得以可能的原因。

消息流

Producer → Consumer: STATE_SNAPSHOT {"items": []}
Producer → Consumer: STATE_DELTA add /items/0
Producer → Consumer: STATE_DELTA replace /items/0/status
Consumer: 某个 delta 应用失败 → 警告,保留先前的值
Producer → Consumer: STATE_SNAPSHOT(重新同步)

数据类型

patch 形状——JsonPatch、其操作、JsonPointer——由 schema 参考按 RFC 6902 引用定义。

Type to search…

↑↓ navigate↵ selectEsc close