yaoyao/docs/read-cache.md

15300 热点读取缓存

15300 包含两层读取能力：进程内热点缓存，以及仅面向 source=web 普通聊天的持久化投影。它们不改变模型生成速度，也不替代 iOS 本地缓存。

持久化普通聊天

chat-cache.sqlite3 保存 Web/iOS 创建的普通聊天会话、消息、事件游标和附件索引；chat-cache-assets 保存已读取的媒体文件。完整同步的会话优先从本地返回，缓存缺失、事件变更或同步断档时才访问 9119。Web 只读历史记录不写入这两个位置，保持现有按需读取和短时内存缓存。

HERMES_YAOYAO_CHAT_CACHE_MODE 支持 upstream-only、shadow 和 prefer-local，默认 prefer-local。本地数据库不可用时服务退回上游读取；发送、停止、审批、澄清和分支始终需要 9119 确认。

上游认证租期

UpstreamServiceSession 将成功的状态/身份检查复用 30 秒，并合并同一时间的并发检查。每个客户端请求仍执行 15300 的用户、角色或配对设备授权。

上游返回 401 时仅对该请求重新认证并重试一次；并发 401 共用登录任务。不会因为网络超时或 5xx 自动重放写请求。服务账号配置变化会立即使租期及读取缓存失效；旧验证或登录响应不能覆盖新凭据。鉴权端点本身不进入读取缓存。

读取策略

数据	新鲜期	后台刷新宽限
Profile/身份列表	5 秒	15 秒
模型选项	30 秒	60 秒
非持久化会话列表、团队/话题列表	2 秒	无
非持久化会话详情、最近消息、团队详情	1 秒	无
已加载的较早消息页	10 秒	无

仅缓存白名单 GET 的成功 JSON。容量上限为 64 MiB / 512 项，每项不超过 2 MiB，使用 LRU 淘汰；相同读取会合并。缓存键包含已验证的 15300 用户/授权版本或配对设备、上游 Cookie 的摘要、Profile、分页参数和请求头。缓存键不记录原始凭据。

后台推送确认、命令回执、鉴权、搜索、未读确认、团队游标能力端点、增量 afterSeq、Range/条件读取以及错误响应不缓存。上游显式 no-store 或 Set-Cookie 响应不缓存。

这是服务端应用数据缓存，而不是浏览器 HTTP 缓存。浏览器仍可保持 cache: no-store。客户端需要强制最新数据时可发送 X-Yaoyao-Cache: bypass；内部调用可指定 cache: 'reload'。

一致性边界

• HTTP 写入前后失效相应资源；聊天命令和实时事件在投递给客户端之前失效对应会话缓存。
• 团队事件失效房间与列表缓存；获取新的团队 journal cursor 后清除较早的团队快照，保留 snapshot-after-anchor 顺序。
• 断线重置会清除相关缓存。刷新期间发生失效时，较早响应不会重新填回缓存，后续请求不会加入过时的在途读取。
• 缓存只负责读取；发送、停止、审批必须等待真实上游确认。没有事件通知的外部修改仍受上述短 TTL 约束，不能声称跨所有外部写入的强一致。

UpstreamClient.readCache.stats() 提供进程内命中、未命中、合并、淘汰、内存及在途数量，用于测试和诊断，不公开缓存内容。