yaoyao/docs/bot-transcript-parity.md

Bot 模式会话加载与滚动对齐

已合并 main，随 v0.4.13 发布。参考 OpenMausBot 当前本地版本 9d2a992c，本次只调整 Bot 模式。

行为

• 新增 /api/app/workspace/snapshot：一次读取 Bot、会话及各活跃会话最近 50 条消息，带一致的事件游标和 hasOlder。
• 新增 /api/app/events/stream：账号隔离的 SSE，持久事件重放、断线续接、撤销授权检查、慢连接关闭和游标重置恢复。原消息读取与事件轮询接口保留兼容。
• Web 缓存按会话和任务保留；切换直接显示已加载内容。实时事件直接更新对应实体，按动画帧发布，不再每 1.2 秒重新拉取列表和最近 100 条消息。
• 快照请求和历史分页会重放请求期间的新事件，防止旧响应覆盖新文字或恢复已隐藏、已删除内容；切换账号清除缓存和事件流。
• Bot 使用独立 WorkspaceMessageTimeline.vue，默认挂载尾部 120 条，按需展开，保留稳定消息对象，补偿历史插入位置，并依据用户手势控制跟随底部。
• 普通聊天继续使用原 MessageTimeline.vue 和原实时协议。

跨端

iOS、Android 同名分支接入快照、缓存和 SSE。iOS 使用系统导航推进；首次打开会话有顶部胶囊展开及头像回落，时长采用 OpenMausBot 的 40ms 起始延迟、0.5/0.55 秒弹簧、1 秒停留和 600ms 收尾；减少动态效果时跳过。旧服务器不声明新能力时，移动端继续使用兼容路径。

iOS 保留 UICollectionView 复用并缩小行更新依赖，时间分隔直接读时间戳，避免重复完整消息转换。Android 保留 LazyColumn，缓存每行正文转换，增加真正的底部锚点并区分用户上滑和内容增长。

验证

• Web/服务端：126 项定向测试通过；生产构建及类型检查通过。
• Playwright：11 项通过，覆盖普通聊天回归、Bot 单聊/群聊、未读跨端、权限、附件、流式 Markdown；新增 300 条消息场景验证缓存切换无详情 GET、返回仅挂载 120 条、历史和实时更新不移动阅读位置、375px 深色与减少动态效果。
• iOS：43 项单元测试通过；系统推进与交互返回、自动分页历史两项模拟器 UI 测试通过。
• Android：core/model 50 项、core/network 41 项通过；Debug APK 和 lintDebug 通过。API 36 模拟器两次启动均在 QEMU 引擎挂起后崩溃，故本轮未完成 Android 仪器化 UI 验证。

本轮未发布或部署，也未声称已完成与 OpenMausBot 同设备同数据的帧率、耗时对照基准。验证覆盖实现行为与既有功能回归。