第16章 快照(Snapshots)
Snapshots 允许你同时撤销最近的对话和文件修改。可以用它们来修订最近的工作,但对于重要数据,请保留 Git 提交或备份。
在完成希望修订的回复后,运行 /undo。OpenCode 会暂存回滚操作,恢复受影响的文件,并将被移除的提示词放回编辑器,方便你继续编辑。
/undo
# 编辑恢复的提示词,然后再次提交。
添加验证逻辑,但不要改变公共 API。
提交编辑后的提示词时,暂存的回滚操作即生效。在提交前,可以运行 /redo 取消回滚,恢复在 /undo 之前的对话和文件状态。
/redo
终端也提供默认快捷键:
- 操作:暂存上一条消息的回滚,命令 /undo,快捷键 <leader>u
- 操作:取消暂存的回滚,命令 /redo,快捷键 <leader>r
你还可以选择更早的消息,并选择 Revert(撤销)来暂存回滚到该节点。
对于每个模型步骤,OpenCode 会尝试在调用模型前和步骤结束(成功或失败)时各创建一次快照。助手消息会记录这两个快照之间发生变化的路径。
模型步骤前 ── 快照 A
模型编辑 src/api.ts
步骤结束 ────── 快照 B ── 变化:src/api.ts
快照捕获是尽力而为的。如果任一侧快照不可用,对话将继续,但该步骤可能没有可供恢复的文件变更。
Snapshots 覆盖 Git worktree 中会话的当前活动目录。例如,在 packages/app 中打开的会话,只会捕获 packages/app 下的目标文件,而不会包含仓库其他位置的变更。
| 内容类型 | 是否捕获 | 示例 |
|---|---|---|
| 活动目录中的受跟踪文件 | 是 | packages/app/src/app.tsx |
| 未被忽略且单文件不超过 2 MiB 的非跟踪文件 | 是 | packages/app/notes.txt |
| 被 Git 忽略的文件 | 否 | packages/app/dist/app.js |
| 单个超过 2 MiB 的非跟踪文件 | 否 | packages/app/debug.log |
| 活动目录外的文件 | 否 | packages/server/src/index.ts |
| Git 元数据及其他副作用 | 否 | 提交、分支、数据库或进程 |
文件系统快照依赖 Git 仓库。在仓库外使用时,/undo 仍可回滚对话历史,但无法恢复文件。
回滚仅恢复归属于选中对话边界之后助手步骤的路径。每个路径都会回到第一个被撤销步骤之前的状态;如果某文件是由这些步骤创建的,且之前不存在,则会被删除。
| 时间轴 | src/api.ts | src/new.ts |
|---|---|---|
| 选定的边界 | 版本 A | 不存在 |
| 后续的助手步骤 | 版本 B | 已创建 |
| 回滚后 | 版本 A | 已删除 |
未归属于这些步骤的路径保持不变。由于当前对受影响路径的编辑可能会被覆盖,建议在继续操作前检查恢复后的摘要和 git diff。
终端命令:
git diff --stat
git diff
OpenCode 在数据目录下的独立内部 Git 对象库中本地存储快照。捕获快照不会创建提交、移动分支或有意修改仓库的索引。
终端命令:
# 捕获后,你的仓库仍是一个普通的未提交工作区。
git status --short
快照对象可能包含受跟踪及合格非跟踪文件的完整内容。请视 OpenCode 数据目录为敏感的本地数据。
Snapshots 默认启用。在配置中将 snapshots 设为 false 可停止未来的文件系统捕获。
opencode.jsonc 配置示例:
{
"$schema": "https://opencode.ai/config.json",
"snapshots": false,
}
禁用 snapshots 不会删除已存储的快照。对话回滚功能依然可用,但在没有捕获文件系统状态的情况下,无法恢复相关的文件变更。
Snapshots 是便捷工具,而非事务或备份机制:
- Shell 命令可能改变服务、进程、网络资源、数据库、Git 状态、被忽略的输出或活动目录外的文件。恢复快照不会逆转这些影响。
- 如果捕获失败或没有可用的快照对,中断或失败的工作可能残留变更。
- 恢复受影响的路径会覆盖其当前内容。取消暂存的回滚也可能覆盖后续的编辑。
- 会话运行期间,OpenCode 会拒绝回滚操作,但在捕获和恢复之间,外部编辑器和命令仍可能修改工作区。
- 提交回滚会从当前对话视图中移除消息,但不会从持久化的会话历史或现有快照存储中移除。这不是安全的擦除操作。
在脏工作区上使用 /undo 前,请务必提交或备份重要工作。