Rewind / Checkpoint 机制

1. 入口与触发#

openMessageSelector 在 REPL.tsx 里就是 setIsMessageSelectorVisible(true)，渲染 <MessageSelector> 组件。

2. MessageSelector：选消息 + 选范围#

components/MessageSelector.tsx：

• 列出所有可选 user message（selectableUserMessagesFilter），外加一条"当前 prompt"的虚拟消息。
• 选中一条后，根据该 messageId 是否有文件快照（fileHistoryCanRestore）给出恢复选项：
  • both（默认）：恢复代码 + 对话
  • conversation：只恢复对话
  • code：只恢复代码
  • summarize / summarize_up_to：从这里 / 到这里做部分压缩（partial compact，不是 rewind）
  • nevermind：取消
• 选消息时会先用 fileHistoryGetDiffStats（dry-run）算出"回退会改几个文件、+/- 多少行"，显示给用户确认。

both 时按顺序调 onRestoreCode（文件）→ onRestoreMessage（对话），各自独立 try/catch，分别报错。

3. 对话恢复：rewindConversationTo#

REPL.tsx 的 rewindConversationTo(message) 核心只有一行截断，但连带重置了一堆易 stale 的状态：

setMessages(prev.slice(0, messageIndex))   // 截断到该消息之前
→ setConversationId(randomUUID())          // 新会话 id
→ resetMicrocompactState()                 // 防 stale pinned cache edits 引用被截断的 tool_use_id
→ resetContextCollapse()                   // staged queue / ID map 引用了 stale uuid，全部重置
→ 恢复该 message 的 permissionMode
→ 清 promptSuggestion

restoreMessageSync 进一步把该消息的文本和图片重新填回输入框（textForResubmit + pasted images），所以 rewind 同时是"编辑后重发"的入口——你回到那条 prompt，改一改再发。

4. 代码恢复：fileHistoryRewind#

utils/fileHistory.ts 的 fileHistoryRewind(updater, messageId)：

1. 用 no-op updater 捕获当前 FileHistoryState（rewind 是纯文件系统副作用，不改 state）。
2. findLast 找到该 messageId 对应的 targetSnapshot。
3. applySnapshot：遍历所有 tracked files：
   • 该版本备份为 null（文件当时不存在）→ unlink 删除现在的文件。
   • 备份有内容 → 若当前文件与备份不同（checkOriginFileChanged）→ restoreBackup（copyFile 覆盖 + chmod 还原权限）。
   • 只动确实变了的文件（基于 stat 的 mode/size/mtime，必要时再比内容）。

5. 文件快照怎么来的（写入侧）#

fileHistoryTrackEdit 是三阶段设计，防 speculative write 和并发 race：

Phase 1: 检查最近快照是否已跟踪该文件（已跟踪则不动 v1，防覆盖）
Phase 2: async createBackup(v1)
Phase 3: commit，再次 re-check（可能有另一个 trackEdit 抢先）

fileHistoryMakeSnapshot 同样分三阶段：capture state（no-op updater）→ async 备份所有 tracked 文件（比对 mtime/size 决定复用旧备份还是建新版本）→ commit 新快照。

6. 备份存储格式#

{configDir}/file-history/{sessionId}/{sha256(filePath)[:16]}@v{version}

• 用 copyFile 而不是 readFileSync + writeFileSync——避免把大文件读进 JS heap 导致 OOM。
• chmod 保留原文件权限。
• 路径在 state 里用相对路径（maybeShortenFilePath）做 key，减少 session storage 占用。
• MAX_SNAPSHOTS = 100，超出后 LRU 丢最老；snapshotSequence 单调递增计数器即使快照被淘汰也不回退，给 useGitDiffStats 当活动信号。
• null 备份是一个显式的"该版本文件不存在"标记，使 rewind 能"删除一个回退点之后才创建的文件"。

7. 预览与无损快速路径#

• fileHistoryGetDiffStats（dry-run）：算回退会改哪些文件、insertions/deletions，用 diffLines，供 UI 显示。
• fileHistoryHasAnyChanges：轻量 bool 版，早退，不算行数，用于"要不要弹确认框"的判断。
• 无损直接 rewind：消息操作栏 edit 时，若 noFileChanges（回退不改任何文件）且 onlySynthetic（该消息后只有合成消息），直接 rewind 不弹确认；否则才打开 MessageSelector 确认。

8. resume / 跨会话迁移#

• 快照记进 transcript（recordFileHistorySnapshot）；resume 时 fileHistoryRestoreStateFromLog 重建 FileHistoryState（含 abs→rel 路径迁移），useFileHistorySnapshotInit 在 mount 时一次性恢复。
• copyFileHistoryForResume：换 session id 后，用 hard link（失败 fallback copyFile）把旧 session 的备份文件迁到新 session 目录，这样 resume 后仍能 rewind。EEXIST 跳过，ENOENT 报错。
• restoreWorktreeForResume / exitRestoredWorktree（sessionRestore.ts）：resume 时还会处理 worktree 工作目录的恢复与退出。

9. 开关#

• settings fileCheckpointingEnabled（默认开）。
• CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING 关闭。
• 非交互 / SDK 默认关，需 CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING 开启。

10. 关键文件与设计要点#

设计要点：

1. 对话与代码 rewind 解耦，可单独执行，用 messageId 锚定同一时间点。
2. 文件快照按 message 存而非按时间，天然对齐"回到那条消息"。
3. 备份用 copyFile + hash 命名 + 版本号 + per-session 目录，resume 用 hard link 迁移，省空间。
4. rewind 顺带把原 prompt 填回输入框，把"回退"变成"编辑重发"。
5. trackEdit/makeSnapshot 的三阶段 + re-check 防 speculative/并发 race 污染 v1。
6. 截断对话时连带重置 microcompact / contextCollapse / conversationId / promptSuggestion，防 stale 引用。
7. 回退前 dry-run diff 预览 + 无损快速路径，既安全又不啰嗦。