16 lines
2.3 KiB
Markdown
16 lines
2.3 KiB
Markdown
# 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` 必须读它；推荐保存结果表示“归档已提交”，缓存失败单独记录并在下次修复，避免上层误以为用户消息未保存而重复执行。
|
||
|
||
本文后续部分继续记录源码证据、接入点、成本和必须回归的边界。
|