同步与断线恢复

已接入 SDK 的宿主不需要自行监听 WebSocket 或定时补数。下面说明协议层的恢复边界，便于定位消息、未读和多设备状态问题。

两条独立读取链

• POST /app/sdk/sync 恢复首页最多 50 个会话、聚合未读、能力和媒体限制，更多会话用 conversations 游标续读。
• GET /app/sdk/messages 恢复一个会话的消息窗口。当前正在看的聊天必须独立校准，即使它没有出现在首页前 50 个会话中。

GET /app/sdk/unread 只校准角标，不能替代上述任一条链。WebSocket 用于低延迟增量，不是可靠历史。

何时同步

时机	首页	可见聊天
登录	立即 sync，同时建立实时连接	如已显示聊天则校准消息
后台回前台	立即 sync	立即 messages
网络不可用恢复为可用	立即 sync	立即 messages，不等待连接恢复
每次新的 connection.ready	必须 sync	必须 messages
首页下拉刷新	sync	摘要领先窗口时校准
正常连续实时事件	直接归并	直接归并
会话序号、内容版本或删除修订缺口	必要时恢复首页	校准对应窗口
本地聚合未读曾封顶 100 后发生减少	unread 校准绝对值	按已读动作正常更新

网络恢复后 HTTP 可能早于新的 WebSocket 订阅生效，因此 ready 到来后仍需再校准。SDK 对相邻触发合并为一个在途请求，最多保留一次尾随读取。

消息窗口校准

已加载最新尾部时同时提交：

GET /app/sdk/messages?conversation_id=friend_bGluemhvdQ&known_last_seq=18&known_updated_at=1792301401000&known_deletion_revision=0

三项必须来自同一次消息窗口读取。unchanged 表示保留当前消息；reset 表示使用服务器重新返回的窗口，并补上请求期间收到的实时消息。浏览历史时使用 before_seq / after_seq；从搜索定位用 around_mid，不能混用校准三项。

收到更大的序号但缺少中间消息时，先校准，不越过缺口提交已读。已删除消息虽然不显示气泡，仍保留原 ID 和序号，判断消息是否连续时也要计入。

已读与视口

read_seq 只推进到用户实际看见且连续的最新边界。用户停留在历史时，保持视口并提示新消息，不自动跳到最新，也不清空未读。失败后保留最后可见检查点，在后续可见消息、回前台或连接恢复时重试。

在途请求与切换账号

HTTP 请求期间收到的实时事件仍需处理，不能让较早读取的数据覆盖刚收到的新消息。每个异步请求都要记住所属账号和本次登录。退出或切换账号后，丢弃之前登录发起的响应和连接事件，也不再把它们写入缓存。

同身份续票替换 HTTP 与 WebSocket 的凭证；新的 ready 仍执行恢复。断线本身保留可读列表和缓存，只有登录身份失效或用户退出才清理账号会话。