Checkpoints 和 rewind

Checkpoints 是 Axiomate 的文件快照系统。AI 准备修改文件之前，Axiomate 会自动记录一次工作区文件快照。之后如果需要回退文件，可以使用 /rewind；如果需要查看 checkpoint 存储状态，可以使用 /checkpoints。

这套机制的主要价值在于自动保存 AI 多轮修改过程中的中间状态。实际使用时，AI 可能连续读文件、改文件、跑测试、再继续修改；用户通常没有机会、也不太可能在每个中间点都手动 commit 或 stash。Checkpoint 会自动记录这些关键文件状态，让你之后可以回到某个“AI 已经改过一部分”的中间状态，而不只能选择保留全部修改或全部放弃。

Checkpoint 保存在哪里

Checkpoint 不会写进你的项目 git 仓库。Axiomate 使用独立的 checkpoint git store 保存快照，通常位于：

~/.axiomate/checkpoints/store

它是 Axiomate 自己维护的 shadow git。你的项目 .git、commit 历史、暂存区、stash 和 hooks 都不会被 checkpoint 系统修改。

如果一次快照和上一次 checkpoint 完全相同，Axiomate 不会写入新的 checkpoint；只有真实文件差异才会产生新记录。

用 /rewind 回退文件

当你想撤回 Axiomate 对文件的修改时，进入：

/rewind

在 File tab 中选择要恢复到的 checkpoint。列表里的行表示可以回到的文件状态。选择某一行后，确认页会重新计算当前磁盘和目标 checkpoint 的差异，再让你确认是否恢复。

需要注意：/rewind 是文件回退入口；/checkpoints 主要用于查看和维护 checkpoint store，不是主要的回退界面。

/checkpoints 常用命令

rewind 的安全快照

执行 rewind 时，Axiomate 会先创建一个 rewind 前的安全快照，然后再恢复目标文件树。

如果恢复过程中失败，/rewind 的 File tab 里通常会出现类似 ↶ Before rewind 的恢复行。你可以选择它回到 rewind 之前的状态。

和项目 git 的关系

Checkpoint 系统和项目 git 是隔离的：

• 不会自动提交到你的项目仓库。
• 不会修改项目暂存区。
• 不会运行项目 git hooks。
• 不替代你自己的 git commit、branch 或 stash。

它更像是 Axiomate 的本地安全网。正式保存工作成果时，仍然应该使用项目自己的 git 流程。

Nested git 子仓库

Axiomate 的 checkpoint 会把当前工作区当作文件系统快照来处理，因此可以覆盖包含嵌套 .git 的复杂项目结构。常见例子包括 monorepo 里的子仓库、vendor 目录、示例项目或测试 fixture。

处理方式是：

• 嵌套仓库里的普通文件可以进入 checkpoint snapshot。
• 嵌套仓库自己的 .git metadata 不会被当作普通业务文件保存。
• 子仓库的 staged、dirty、untracked 状态不会直接影响父项目 checkpoint 的工作方式。
• 回退时关注的是文件内容本身，而不是替你操作子仓库的 git 历史。

这让 Axiomate 能在更真实的工程目录里提供安全网：即使项目里混有多个 git 边界，也能对实际文件变化做存档和回退。

常见注意事项

• Checkpoint 是 fail-open 的：如果某次快照失败，通常不会阻止 AI 继续执行工具。
• Rewind 更严格：如果缺少安全快照或无法确认目标 checkpoint，Axiomate 会避免盲目恢复。
• 如果 /rewind 列表看起来不对，退出再重新打开 /rewind 刷新。
• 如果 checkpoint store 太大，可以运行 /checkpoints prune 或调整相关配置。