Whaleness多级聊天缓存与滚动性能优化:从L1 LRU、Room事务到热会话预加载

原创2026-11-02 18:34:52234 阅读

Whaleness多级聊天缓存与滚动性能优化:从L1 LRU、Room事务到热会话预加载

Whaleness(dsh-mobile)是面向 DeepSeek Harness 的跨平台移动端客户端,通过 dsh-plugin-mobile-gateway 与 Harness 建立 WebSocket 连接,把会话、实时回复和 Agent 执行轨迹带到 iPhone 与 iPad。本文带你完整拆解它的多级聊天缓存体系:内存 L1 窗口 LRU、Room 磁盘 L2 的容量事务、基于热度排序的热会话预加载,以及"滚动优先"的历史分页调度,让长会话离线秒开、翻阅旧记录不卡顿。

Whaleness dsh-mobile 客户端三屏总览:主页会话列表、聊天对话与 Agent 轨迹,由多级聊天缓存加速加载

为什么需要多级聊天缓存

长会话动辄上万条事件,每次进入会话都从网关拉全量历史,等待既长又耗流量。Whaleness 的思路很克制:

  • 网关仍是权威来源,本地只保存"有限窗口",不承担永久归档职责;
  • 缓存先显示正文,网络快照到达后由正常历史状态机接管,旧缓存页不会被拼回;
  • 容量可预算、可淘汰:内存与磁盘都有高水位/回收目标,超了就删最冷的。

这套机制的核心文档见 Docs/多级缓存与磁盘管理.md,全部共享逻辑位于 shared/src/commonMain/kotlin/com/clarklevis/dsh/shared/cache/,iOS 与 Android 两端复用同一套 Room 数据库。

iPad 会话页面:聊天正文先由本地多级缓存显示,再由网络确认最新状态

L1 内存窗口:24 MiB 的全网关共享 LRU

打开会话时第一道关卡是内存命中。L1 由 ChatMemoryCache.kt 实现,设计要点非常简洁:

  • 有界双约束:估算字节数最多 24 MiB,会话数最多 6 个,且是全网关共享——多网关用户不会各占一份内存;
  • 经典 LRU 手法:用有序 map,get 时先移除再重新插入,命中即刷新到"最新"位置;
  • 保守估算:写入时按 编码字节 × 2 + 事件数 × 512B 估算(计入管线中多份副本的保留成本),而不是精确测量堆;
  • 淘汰即同步失效:磁盘 LRU 淘汰会话后,L1 会整体清空并推进 readRevision,杜绝内存继续命中已删除的全文。

注意 L1 存的是"已校验的类型窗口"——命中后直接交给 UI 投影,不重复做 JSON 编解码,这是热路径上最便宜的一跳。内存压力(iOS 内存警告、Android onTrimMemory)会调用 trimMemory() 清空 L1,但不触碰磁盘。

磁盘窗口策略:最多 400 条事件、8 MiB 的尾部快照

写入 L2 之前,ChatCacheWindowPolicy.kt 先把历史裁成"最新尾部快照":

  • 从最新事件往回取,最多 400 条、不超过 8 MiB;
  • 裁掉旧事件时把 hasMore 置真、nextBeforeSequence 指向保留窗口首条,persistentCursor 独立保留——向前翻页的水位不会被裁切破坏;
  • 最新单条事件本身就超预算时整个快照拒绝,不截断正文、不用更旧内容冒充最新水位,已有磁盘窗口继续保留;
  • 临时流式片段 assistant/chunk 一律不入库,只导出稳定历史。

窗口序列化用了个小技巧:事件数组是 envelope 的最后一个字段,逐事件编码后拼接即可,无需二次编码整个窗口,更不会先编码全部历史。

Room 事务:窗口、搜索索引与 LRU 淘汰同进同出

L2 落在 Room(跨平台 SQLite)。真正的"性能与一致性"关键在 ChatCacheDatabase.kt 的 replace()——一个 @Transaction 里完成三件事:

  1. 预算校验:用 logicalBytes(正文 + 冗余搜索索引)预测写入后总量,超过高水位就先按 LRU 逐条淘汰未受保护的会话,直到降到回收目标;
  2. 替换窗口:删除旧行、写入新会话头、事件、可搜索正文与三字符索引;
  3. 失败回滚:预算兜不住时抛 CacheCapacityExceeded,事务整体回滚,旧窗口原样保留。

容量口径(详见容量表文档):聊天逻辑数据高水位 96 MiB、回收目标 72 MiB,跨网关 LRU;离线导航目录独立 8 MiB、最多 64 个主机。SQLite 主文件另有约 128 MiB 的 max_page_count 上限兜底。

一致性靠三级"票据"仲裁,定义在 SharedChatHistoryCache.kt:

票据 职责
epoch 清理缓存前排队的旧写入落不了盘
generation 拒绝同一会话的旧快照(旧代次不覆盖新代次)
revision 隔离读取期间的替换与删除,读完成时校验代次未变

配合 single-flight(同一会话的并发读只放行一个 owner,其余等待同一个 CompletableDeferred),保证了"缓存先显示、网络后接管"不会出现旧数据复活。

Whaleness 客户端主页:最近会话列表与会话内容搜索框,数据来自本地缓存与热会话预加载

热会话预加载:用热度分数决定"先取谁"

断线重连成功后,App 不会下载所有会话的全部历史。iOS 侧由 ChatSessionPrefetcher.swift 调度:收到 hello、会话列表与当前首屏就绪并空闲 750 ms 后,后台按热度依次预加载其他常用会话;用户一旦翻历史、发请求或前台正在生成,调度立即暂停。

热度排序算法在 ChatPrefetchPolicy.kt,记录存于独立的 chat_session_heat 表(只来自真实打开,预加载本身不刷热度):

得分 = 衰减打开次数 × 4 + 衰减最近打开权重 × 8 + 衰减网关活动权重 × 2 + 运行中 3 分 + 未读 2 分

打开次数每 7 天减半、最多累计 64;每轮连接最多尝试 6 个会话、单并发,每次仅请求最新 80 条事件、256 KiB,单响应超过预算直接拒收。预加载只写"冷"的 Room 窗口和搜索索引,不暖入 L1、不切换当前会话、不建后台订阅——用户随后打开它,本地正文直接可见,网络只负责确认最新状态。

滚动性能优化:滚动优先,停稳后再补历史

缓存让"进入会话"变快,翻阅旧历史时的卡顿则需要另一套调度。DeepSeekHarnessMobile/Components/ConversationViewport.swift 实现了"已显示内容滚动优先"策略:

  • 拖动、跟踪、减速期间:只保留现有显示快照,新目标合并为一份,不插入、不测高;
  • 连续停稳约 120 ms 后:每个 display tick 最多准备 1 行,下一 tick 才提交,常规前插每批最多 2 行,从最接近已读内容的一侧逐批补入;
  • 原生位置补偿:仅旧行未变化且锚点有效时才启用,等异步 completion 不再回拉窗口,锚点误差控制在 1 pt 内;
  • 渐显与滚动条治理:新历史在几何稳定后 180 ms 透明度渐显;加载期间隐藏系统滚动条,内容尺寸连续两个 idle tick 稳定后才恢复。

此外还有"批量补页"策略(见 Docs/iOS历史阅读窗口批量补页.md):已结束会话翻旧记录时,若新增内容不足约两屏正文,沿用同一操作继续补取,直到达到正文目标、历史结束或预算上限(8 轮 / 2.5 秒),避免"每次加载只多几个工具调用"的空翻页。

Docs/iOS历史分页滚动性能验证.md 记录了同包三轮真实会话测量:滚动区间 display P95 稳定在 16.667 ms,>33.3 ms 比例从基线约 3% 降到 0.75% 左右,阅读锚点误差 0 pt——优化路径的完整度量合同见 Docs/iOS滚动优先调度测量合同.md。

断线之后:离线阅读与容量全景

网络断开时,主页会话列表、工作区与搜索词全部保留(来自独立的离线导航目录 chat_offline_catalog);已缓存正文可继续离线阅读与向前翻页,未缓存会话明确提示"连接后可加载",不留无限 spinner。

范围 高水位 回收目标/策略
全应用受管磁盘 384 MiB 288 MiB,受租约保护内容可暂超
聊天 Room 逻辑数据 96 MiB 72 MiB,跨网关 LRU
聊天 L1 内存窗口 24 MiB、6 会话 全网关 LRU,内存警告清空
已下载聊天图片 32 MiB 24 MiB,默认 7 天过期
工作区预览 192 MiB 144 MiB

相关验证覆盖在 DeepSeekHarnessMobileTests/ChatHistoryCacheTests.swift、DeepSeekHarnessMobileTests/ChatSessionPrefetcherTests.swift 等测试文件中;iOS 桥接层 ChatHistoryCache.swift 只负责路径与并发适配,数据库与容量策略全部复用 Room 共享层。

小结

Whaleness 的聊天体验优化可以浓缩为三条原则:先命中再联网(L1 LRU → Room 窗口 → 网络接管)、写入必仲裁(epoch/generation/revision + 单事务淘汰)、用户手势永远优先(热会话空闲预加载、停稳 120 ms 才补页)。对想给自家 App 做类似优化的同学,建议先读 Docs/多级缓存与磁盘管理.md 的容量口径,再对照共享层源码落地,最后用冻结的测量合同验证真实滚动体验——性能结论只认数据,不认形容词。

登录后查看全文
dsh-mobile