Claude Code fileHistory 文件编辑快照与回滚机制深度解析

基于 Claude Code 源码（通过 sourceMap 还原）逆向分析其文件版本控制系统。
核心模块：utils/fileHistory.ts，负责追踪 AI 编辑过的文件，创建备份快照，支持一键回滚。

一、为什么 AI 编辑文件需要版本控制？

AI 修改代码和人类改代码有一个本质区别：AI 可能一口气改很多文件，而且改完你未必能立刻发现问题。

等你发现 AI 把代码改坏了，可能已经过了好几轮对话。这时候你需要一个"后悔药"——回到 AI 改之前的某个时间点。

Git 当然可以做这件事，但 Claude Code 的使用者不一定都用 Git，而且 Git 的粒度是手动 commit，AI 中间改了什么你得自己 diff。Claude Code 需要一个更轻量、更自动的方案，让用户能够：

1. 看到每轮对话改了哪些文件、改了多少行
2. 一键回滚到 AI 改之前的某个节点
3. 不需要手动管理版本

这就是fileHistory模块的职责。

二、核心数据模型

2.1 三个关键类型

// 单个文件的备份记录typeFileHistoryBackup={backupFileName:string|null// null 表示该版本文件不存在version:number// 版本号，单调递增backupTime:Date}// 一个快照——对应主对话中的一条消息typeFileHistorySnapshot={messageId:UUID// 关联的主对话消息 IDtrackedFileBackups:Record<string,FileHistoryBackup>// 文件路径 → 备份信息timestamp:Date}// 整体状态typeFileHistoryState={snapshots:FileHistorySnapshot[]// 快照列表，最多 100 个trackedFiles:Set<string>// 当前被追踪的文件集合snapshotSequence:number// 单调递增计数器}

一个快照对应主对话中的一轮消息。快照中记录了当时所有被追踪文件的备份状态。

2.2 备份文件存储

备份文件存储在~/.claude/file-history/{sessionId}/目录下：

~/.claude/file-history/ ├── a1b2c3d4-session-id/ │ ├── a1b2c3d4e5f6g7h8@v1 ← 文件 A 的第一个版本 │ ├── a1b2c3d4e5f6g7h8@v2 ← 文件 A 的第二个版本 │ └── d4e5f6a1b2c3d4e5@v1 ← 文件 B 的第一个版本

文件名格式：{sha256(path)[:16]}@v{version}。使用 SHA256 哈希避免路径中的特殊字符问题。

三、核心流程

3.1 追踪文件编辑（fileHistoryTrackEdit）

当 AI 即将修改一个文件时（通过 Edit、Write 等工具），fileHistoryTrackEdit被调用。它的工作是在文件被修改之前，保存一份原始内容的备份。

时间线： AI 决定编辑 file.ts ↓ fileHistoryTrackEdit 被调用 ↓ 检查 file.ts 是否已在最近快照中被追踪 ├── 已追踪 → 跳过（不覆盖 v1 备份） └── 未追踪 → 创建 file.ts 的 v1 备份 ↓ AI 实际修改 file.ts

关键细节：如果同一个文件在一次对话轮次中被多次编辑，fileHistoryTrackEdit只会创建一次 v1 备份。后续的编辑不会覆盖 v1——因为 v1 代表的是"AI 改之前"的状态。

// 防止重复追踪if(mostRecent.trackedFileBackups[trackingPath]){// Already tracked in the most recent snapshot// Do not touch v1 backup.return}

3.2 创建快照（fileHistoryMakeSnapshot）

每轮对话结束后，fileHistoryMakeSnapshot对所有被追踪的文件进行一次"盘点"：

// 对每个追踪文件检查是否需要新备份awaitPromise.all(Array.from(captured.trackedFiles,asynctrackingPath=>{// 1. stat 文件，判断是否存在// 2. 如果存在且内容没变 → 复用上一次的备份引用// 3. 如果存在且内容变了 → 创建新版本备份// 4. 如果文件不存在 → 记录 null（文件被删除）}))

这里有一个重要的优化：未变化的文件不会创建新备份，只是把上一个快照的引用复制过来。

假设追踪 3 个文件，经历 4 轮对话： Snapshot 1: A=v1, B=v1, C=v1 → 磁盘: 3 个备份文件 Snapshot 2: A=v2, B=v1, C=v1 → 磁盘: +1 个备份文件（仅 A 变了） Snapshot 3: A=v2, B=v1, C=v2 → 磁盘: +1 个备份文件（仅 C 变了） Snapshot 4: A=v2, B=v1, C=v2 → 磁盘: 无新增（全都没变）

3.3 回滚（fileHistoryRewind）

当用户想要回到某个历史节点时：

asyncfunctionfileHistoryRewind(updateFileHistoryState,messageId,// 目标快照的 messageId){// 1. 找到目标快照consttargetSnapshot=captured.snapshots.findLast(snapshot=>snapshot.messageId===messageId)// 2. 将所有追踪文件恢复到快照中的版本constfilesChanged=awaitapplySnapshot(captured,targetSnapshot)}

applySnapshot对每个追踪文件：

1. 获取目标版本对应的备份文件名
2. 用copyFile将备份覆盖回原路径
3. 恢复文件权限

四、变更检测的三层优化

checkOriginFileChanged是判断"文件是否被修改过"的核心函数。它用三层递进的策略，尽量避免全量读取文件内容：

第一层：快速判断 ├── 文件大小不同 → 已变化 ├── 文件权限不同 → 已变化 └── 继续下一层 第二层：时间戳判断 ├── mtime < 备份时间 → 未变化（文件比备份更旧，不可能被改过） └── 继续下一层 第三层：全量内容比较 └── readFile 两个文件，逐字节比较

大部分情况下，第一层或第二层就能得出结论，避免了昂贵的磁盘 I/O。

五、备份策略：全量拷贝 + 引用复用

不是增量 Diff

每个版本的备份都是完整的文件拷贝（通过copyFile系统调用），而不是增量 diff：

asyncfunctioncreateBackup(filePath,version){constbackupFileName=getBackupFileName(filePath,version)// 如 "a1b2c3@v1"constbackupPath=resolveBackupPath(backupFileName)awaitcopyFile(filePath,backupPath)// 全量拷贝，不走 JS 堆awaitchmod(backupPath,srcStats.mode)// 保留文件权限return{backupFileName,version,backupTime:newDate()}}

选择全量拷贝的原因：

• copyFile是内核层面的零拷贝操作，不走 JavaScript 堆，大文件不会 OOM
• 实现简单可靠，不需要处理 diff/patch 的边界情况
• 恢复时只需一次copyFile，不需要按顺序回放所有 diff

引用复用节省空间

快照中引用复用的设计让存储开销大幅降低。一个被追踪但长期不变的文件，无论经历多少轮对话，在磁盘上只有一份备份。

六、谁会被追踪，谁不会？

只有被 AI 工具编辑过的文件才会进入追踪集合。

• AI 用 Edit 工具改了file.ts→file.ts被加入trackedFiles
• AI 用 Write 工具创建了new.ts→new.ts被追踪
• AI 只读取了readonly.ts（Read 工具） → 不会被追踪
• 用户手动编辑了任何文件 → 不会新加入追踪，但如果文件已被追踪，变更会被下一个快照捕获

用户手动修改已追踪文件时的行为：

AI 编辑 file.ts → file.ts 被追踪，创建 v1 备份 用户手动编辑 file.ts 下一轮 AI 对话 → fileHistoryMakeSnapshot 检测到 file.ts 内容变了 → 创建 v2 备份（包含用户的修改）

系统不区分"谁改的文件"——只关心"文件内容是否与最新备份不同"。

七、回滚的注意事项

7.1 回滚会覆盖用户修改

applySnapshot不区分改动来源。如果用户在 AI 编辑之后手动改了文件，回滚到 AI 编辑之前的快照会把用户的手动修改也一并覆盖：

AI 改了 file.ts → 快照记录 v1（原始）→ v2（AI 改后） 用户手动改 file.ts → 下一快照 v3（用户改后） 用户回滚到 v1 → v3 被覆盖，用户的修改丢失

这类似git reset --hard的语义——用户主动触发回滚时，通常预期这个行为。

7.2 最多 100 个快照

constMAX_SNAPSHOTS=100

超出后淘汰最早的快照。对于长会话，早期的快照可能已经不可回滚。

八、多 Agent 协作的文件安全

8.1 子 Agent 不产生快照

这是源码中一个容易被忽视的设计。在forkedAgent.ts中：

// forkedAgent.ts:432updateFileHistoryState:()=>{},// 空操作！

子 agent（通过 AgentTool 启动的 agent）拿到的updateFileHistoryState是一个空函数。当子 agent 调用FileEditTool编辑文件时，虽然工具内部会调用fileHistoryTrackEdit，但因为回调是空函数，captured变量为undefined，函数在第 107 行直接返回：

updateFileHistoryState(state=>{captured=state// 子 agent 中 captured = undefinedreturnstate})if(!captured)return// 直接退出，不创建备份

8.2 为什么这样设计？

快照绑定的是主对话的 messageId，而不是子 agent 的内部消息 ID：

typeFileHistorySnapshot={messageId:UUID// 主对话消息 IDtrackedFileBackups:Record<string,FileHistoryBackup>}

子 agent 有自己独立的消息链，它们的 messageId 在主对话中不存在。如果让子 agent 也写入快照，会破坏"一个主轮次 = 一个快照"的模型。

8.3 实际影响：快照粒度是"主对话轮次"

主轮次 N：用户提问 ├→ 主 agent 编辑 fileA → Snapshot N 包含 fileA 的变更 ├→ 子 agent B 编辑 fileB → 无快照 └→ 子 agent C 编辑 fileC → 无快照 主轮次 N+1：用户继续提问 ├→ fileHistoryMakeSnapshot → Snapshot N+1 创建 │ （包含 fileB、fileC 的累积变更） └→ 主 agent 继续编辑

回滚能力：

风险：无法选择性回滚——子 agent A 和 B 各改了不同文件，你无法只撤销 A 的改动而保留 B 的。

8.4 Worktree 隔离

Claude Code 提供了isolation: 'worktree'作为更强的隔离手段：

// forkSubagent.ts:209`You are operating in an isolated git worktree at${worktreeCwd}— same repository, separate working copy. Your changes stay in this worktree and will not affect the parent's files.`

在 worktree 中运行的子 agent 拥有独立的文件副本，天然不冲突。完成后由主 agent 决定是否合并。这是处理高风险多 agent 文件编辑的推荐方式。

九、文件冲突的乐观并发控制

多 agent 编辑同一文件时，Claude Code 没有全局文件锁，而是采用"乐观并发 + 失败重试"的策略，防线在FileEditTool中：

第一层：时间戳校验

if(lastWriteTime>readTimestamp.timestamp){return{behavior:'ask',message:'File has been modified since read... Read it again before attempting to write it.',errorCode:7,}}

每个 agent 各自维护readFileState，记录上次读取文件的时间戳。编辑前比对磁盘 mtime，发现文件被改过就拒绝写入。

第二层：old_string 匹配

constactualOldString=findActualString(file,old_string)if(!actualOldString){return{behavior:'ask',message:'String to replace not found in file.'}}

即使通过了时间戳检查，还要验证old_string确实存在于文件中。如果另一个 agent 已经改了这段内容，匹配失败。

冲突处理流程

Agent A: 读取 file.ts → 看到 function foo() {...} Agent B: 读取 file.ts → 看到同一个 function foo() {...} Agent B: 编辑 foo() → 成功，mtime 更新 Agent A: 尝试编辑 foo() → mtime 检查失败 → 报错 "Read it again" Agent A: 重新读取 file.ts → 看到 B 修改后的版本 → 基于新内容编辑 → 成功

先到先得，后到的被拒绝，必须重新读取后再编辑。没有自动 merge，没有操作队列串行化。

十、Session Resume 的备份迁移

当用户恢复一个历史会话时，需要把旧 session 的备份文件迁移到新 session 目录。copyFileHistoryForResume处理这个过程：

asyncfunctioncopyFileHistoryForResume(log){// 1. 获取旧 session 的备份目录constpreviousSessionId=lastMessage?.sessionId// 2. 创建新 session 的备份目录constnewBackupDir=join(getClaudeConfigHomeDir(),'file-history',sessionId)awaitmkdir(newBackupDir,{recursive:true})// 3. 并行迁移所有备份文件（优先硬链接，失败时降级为拷贝）awaitlink(oldBackupPath,newBackupPath)// 硬链接优先，零拷贝// fallback:awaitcopyFile(oldBackupPath,newBackupPath)// 跨文件系统时降级}

优先使用硬链接（link）而非拷贝——硬链接不占用额外磁盘空间，两个路径指向同一份数据。只有在硬链接失败时（比如跨文件系统）才降级为copyFile。

十一、VSCode 扩展通知

每次创建新快照时，系统会通知 VSCode 扩展哪些文件发生了变化：

asyncfunctionnotifyVscodeSnapshotFilesUpdated(oldState,newState){for(consttrackingPathofnewState.trackedFiles){constoldBackup=oldSnapshot?.trackedFileBackups[trackingPath]constnewBackup=newSnapshot.trackedFileBackups[trackingPath]// 只通知内容实际变化的文件if(oldContent!==newContent){notifyVscodeFileUpdated(filePath,oldContent,newContent)}}}

这让 VSCode 中的 Claude Code 扩展能够实时显示文件变更，增强用户对 AI 编辑行为的感知。

十二、设计总结

整体来看，fileHistory 是一个面向"AI 改坏了要能回滚"这个具体场景设计的轻量级版本控制系统。它不追求 Git 级别的功能完整性，而是在简单性和安全性之间找到了一个适合 AI 编程助手场景的平衡点。