2.3 KiB
cc-web 完整历史持久化设计调查
调查日期：2026-10-10。范围：只读检查代码、现有任务和规范，只写入本研究文档。当前 PRD 仍在更新，本文描述完整历史存档设计，不将旧 PRD 的快照分页范围视为最终范围。
明确推荐
新增 cc-web 自有的完整会话归档，将其作为 saveSession 的持久化提交点；现有受限 JSON 快照保留为列表、首屏和搜索预览缓存。loadSession 优先从已提交归档恢复完整会话，原生 Codex/Claude 日志只作已确认边界的补充来源。完整归档不得调用现有 sanitizeSessionForPersist、sanitizeMessageForPersist 或其文本、消息、数组裁剪逻辑。
最小版本建议使用独立 lib/session-history-store.js，同目录临时文件 + 原子 rename 保存一份紧凑 JSON。归档包括完整持久化会话字段，而不只包括 messages，以便完整归档写入成功、受限快照失败时，重启仍恢复本次提交的线程绑定、清空状态和消息顺序。没有归档的旧会话先读取现有快照，保留“前缀未知”的事实，不能因为新建归档就宣称旧历史完整。
正常业务读取完整归档后，保存的是当前完整消息数组的精确状态，而不是永久 upsert。这样自然保留 /clear 的空数组、撤回/删除和在 steer 用户消息之前插入旧 turn 输出的语义。对来源为受限快照、旧修订或导入的消息数组，使用来源与修订信息区分：它们不能凭消息数量或长度覆盖完整归档。导入应按可靠标识确认重叠后合并，保留 cc-web 独有气泡；无法确认时拒绝破坏性替换并保留旧归档。
保存顺序：构造完整、可序列化的提交记录 → 写完整归档并原子提交 → 更新内存归档状态 → 尽力写受限快照 → 通知搜索/统计索引。完整归档失败时不覆盖旧快照、不更新成功状态，返回失败。完整归档成功而受限快照失败时，归档已经是本次持久状态，loadSession 必须读它；推荐保存结果表示“归档已提交”，缓存失败单独记录并在下次修复，避免上层误以为用户消息未保存而重复执行。
本文后续部分继续记录源码证据、接入点、成本和必须回归的边界。