# 中断恢复

[README](../README.md) · [English](recovery.md)

从 0.4.0 开始，新回退及其 redo 会在修改文件前保存命名救援快照和独立恢复记录。DSH 退出、进程被终止、超时或部分文件还原失败后，重启插件即可从设置继续处理。

## 使用入口

打开 **DSH 设置 → FileSnap → 中断恢复**，无需先打开原会话。

1. 选择未完成的回退或 redo，点击 **预览继续还原** 或 **预览回滚到操作前**。
2. 查看将还原和删除的文件。预览只保存安全快照，不修改工作区。
3. 确认后执行。完成时可打开对应对话；原有分支仍保留。

“继续”到达原先选择的目标；“回滚”回到这次操作开始前。回滚一旦开始，中断后只能继续回滚，避免混淆两种方向。文件已经全部到位但进程没来得及记录成功时，也需确认完成记录，不会再消费一次 redo。

有未完成操作时，插件会阻止该工作区的新 Agent 步骤、受监控编辑和回退/redo，并暂停插件的空间清理。先处理恢复，再继续任务。

![中断恢复预览：查看待还原和删除的文件并确认（0.4.0）](../assets/screenshots/v0.4.0/09-interrupted-restore.png)

## 冲突与边界

恢复预览检查现有文件内容和权限。文件既不符合操作前状态，也不符合目标状态时，会列为冲突并禁用确认；确认时再次检查。先用编辑器或其他位置保留新增修改，再处理冲突。预览不会替你丢弃修改。

![中断后文件再次修改时列出冲突并禁用确认（0.4.0）](../assets/screenshots/v0.4.0/10-recovery-conflict.png)

- 如果 `.filesnapignore` 与当时确认的规则不同，恢复会拒绝执行。先将忽略规则恢复到操作开始时的文本，再预览；这也适用于原操作修改了忽略文件的情况。现有引擎的 `prepare` 只读取当前规则，插件不会用不完整清单确认恢复。
- 同一工作区只由一个 DSH 进程操作；恢复期间停止外部编辑器、脚本和其他助手写入。插件会检查本进程的运行中 Agent，但不是跨进程或文件系统事务锁。
- 恢复针对本机工作区，依赖救援快照及源会话的快照引用仍然存在。不要手动删除相关引擎数据。
- 这是进程中断恢复，不承诺整台机器断电时的跨文件原子性。插件记录使用临时文件、刷新和重命名；快照持久性仍受现有引擎和文件系统影响。
- 升级前已经发生的回退继续使用旧引擎 undo 路径，无法补出当时不存在的插件恢复记录。新能力适用于本版创建的回退及其 redo。

## 保存了什么

恢复记录位于配置的 `dataDir`（未设置则为平台数据目录）下的 `dsh-filesnap/recovery-v1/`。它只保存恢复所需的目标、救援点、路径状态、分支对应关系和 redo 栈，不是聊天操作日志。恢复完成时，未完成记录与 redo 栈在同一次替换中提交；临时操作状态随之移除。

这些记录不进入 DSH 的会话文件。卸载插件后，对话仍由 DSH 原生读取；需要恢复插件的文件操作时再安装插件，并保留原数据目录。未知版本或损坏的恢复记录会被拒绝，不会猜测后继续写文件。

引擎保持 FileSnap 0.5.1+，复用 `prepare`、`restore` 及明确传入忽略规则的能力。`doctor` 仍只检测文件锁和清理临时残留，不承担这套宿主恢复流程。