Realtime 资源观察

资源观察用于订阅房间资源。带版本资源可以携带恢复游标，播放信息始终返回当前播放源可直接交给播放器使用的数据。资源变化时，服务端可以推送完整 payload，也可以只通知客户端重新拉取。

支持的资源

资源	`ObserveResource.resource` 字段	版本来源	典型用途
播放状态	`playbackState`	`RoomPlaybackState.version`	播放器 UI、同步当前播放时间和状态
播放信息	`playback`	每次观察返回当前值	获取当前播放源 URL、header、代理策略和过期时间
房间设置	`roomSettings`	房间设置版本	控制聊天、播放权限等 UI
播放列表项	`playlistItems`	列表快照版本	根列表、子播放列表、provider 浏览和搜索结果
房间成员	`roomMembers`	成员列表快照版本	成员列表、分页、搜索、角色和状态过滤

每个观察由 observeId 标识。observeId 只需要在当前连接内唯一，长度 1-128。使用稳定命名，例如 playback-state、playlist-root:p1:50、members:online。

每条连接最多保留 64 个观察。超过限制时服务端返回 ResourceObserveError，不会关闭 WebSocket。

Delivery Mode

值	行为
`0`	等同于 `PUSH_SNAPSHOT`
`2`	变化时推送完整 `ResourceChanged.payload`，适合低延迟 UI
`1`	变化时只推送 `changedOnly`，客户端随后通过 HTTP/gRPC 拉取

订阅流程

客户端连接房间 WebSocket。
客户端发送 ClientMessage.observeResource，包含 observeId、deliveryMode 和目标资源。支持恢复游标的资源还可以带事件序列。
服务端加载当前资源，返回 ServerMessage.resourceObserved。
如果服务端判断资源已变化，随后返回同一 observeId 的 ServerMessage.resourceChanged。
连接期间，房间事件、缓存失效、Provider credential 变更或播放信息过期会触发重新评估。

ResourceObserved 字段：

字段	说明
`observeId`	对应客户端提交的订阅 ID
`changed`	服务端当前资源是否需要发送给客户端
`eventCursor`	支持事件回放资源的恢复游标

ResourceChanged 字段：

字段	说明
`observeId`	哪个订阅发生变化
`payload`	完整快照或 `changedOnly`，取决于 `deliveryMode`
`eventCursor`	已回放资源事件对应的游标

取消订阅

不再需要某个视图、列表或查询时，发送 ClientMessage.unobserveResource：

sendClientMessage({
  unobserveResource: {
    observeId: 'playlist-root',
  },
});

取消订阅没有确认消息。断开连接时，服务端会自动清理该连接上的所有观察。

订阅示例

下面示例是 TypeScript 风格伪代码。实际字段名取决于你使用的 protobuf 代码生成器。

sendClientMessage({
  observeResource: {
    observeId: 'playback-state',
    deliveryMode: 2,
    playbackState: {
      afterEventSequence: cached.playbackStateEventSequence,
    },
  },
});

服务端变化时返回 ResourceChanged.payload.playbackState。

sendClientMessage({
  observeResource: {
    observeId: 'playback',
    deliveryMode: 2,
    playback: {
      playbackClientProfile: currentPlaybackClientProfile,
    },
  },
});

播放信息观察会立即返回当前可播放 URL、header、字幕和过期时间，并在房间事件、过期或 Provider credential 变化后重新评估。

sendClientMessage({
  observeResource: {
    observeId: 'room-members:online',
    deliveryMode: 1,
    roomMembers: {
      afterEventSequence: cached.membersEventSequence,
      request: {
        page: 1,
        pageSize: 50,
        search: '',
        status: 1,
        sortBy: 1,
        sortDirection: 1,
      },
    },
  },
});

notify-only 模式下服务端变化时返回 ResourceChanged.payload.changedOnly，客户端随后调用 HTTP/gRPC 成员列表接口刷新本地缓存。

变化触发

事件类型	刷新资源
播放状态变化	`playbackState`、`playback`
当前播放媒体或播放列表相关媒体更新	`playback`，必要时 `playlistItems`
播放列表创建、更新、删除、重排或媒体增删	`playlistItems`
房间设置变化	`roomSettings`、`roomMembers`
用户加入、离开或权限变化	`roomMembers`
缓存失效命中当前房间或用户	对应的播放、设置、列表或成员资源
Provider credential 变更	可能影响当前用户播放信息和 provider 浏览结果
播放信息过期	到期后自动重新评估 `playback` 观察

服务端会对同一房间内相同查询做短窗口合并，减少多个连接同时订阅同一资源时的重复快照加载。客户端不需要依赖这个优化，但可以为多个视图建立独立 observeId。