Appearance
Checkpointing 为 Kiro CLI 会话提供类似 Git 的临时快照。本文解释它如何通过 shadow git repo 跟踪文件改动，如何查看、比较和恢复 checkpoint，以及 soft restore 与 hard restore 的区别，帮助你在重构、试验和排障时安全回退。
Kiro CLI Experimental Checkpointing：安全回滚会话中的文件改动
Checkpointing 是 Kiro CLI 的会话级文件快照能力。你可以把它理解成“只服务于当前聊天会话的临时 Git”：Kiro 会在背后创建一个 shadow bare git repository，用来记录当前会话中每一轮文件变更。需要时，你可以查看 checkpoint、比较差异，或者恢复到某个已知状态。
它不替代项目自己的 Git，也不会直接改写你的真实 Git 仓库历史。它的价值在于：当你和 Kiro 试验多个实现方案、做复杂重构或排查错误时，可以更低成本地回到前面的工作点。
启用 checkpointing
使用 settings 启用：
bash
kiro-cli settings chat.enableCheckpoint true也可以在会话中打开实验功能菜单：
bash
/experiment然后从列表里选择 Checkpointing。
它是怎么工作的？
自动初始化
- 在 Git 仓库中：启动聊天会话后会自动启用。
- 在非 Git 目录中：需要手动执行
/checkpoint init。 - 作用范围：checkpoint 只属于当前会话，通常会在会话结束后清理。
Shadow repository
Checkpointing 会创建一个临时的 bare git repo。它负责：
- 跟踪当前会话中发生的文件改动。
- 为每一轮对话或工具操作保存快照。
- 支持比较不同文件状态。
- 支持恢复到某个 checkpoint。
- 会话结束后自动清理，避免长期占用空间。
这个 shadow repo 不等于你的项目 .git，因此不会创建真实 commit，也不会影响远程仓库。
常用命令
/checkpoint init
在非 Git 目录中手动初始化 checkpointing：
bash
/checkpoint init如果你在 Git 仓库里工作，通常不需要手动执行这一步。
/checkpoint list
查看当前会话的 turn-level checkpoints，并显示文件统计信息：
bash
/checkpoint list [--limit N]示例输出：
text
[0] 2025-09-18 14:00:00 - Initial checkpoint
[1] 2025-09-18 14:05:31 - add two_sum.py (+1 file)
[2] 2025-09-18 14:07:10 - add tests (modified 1)
[3] 2025-09-18 14:10:45 - refactor algorithm (modified 1)建议在长任务中定期运行它，确认当前会话已经记录了哪些关键节点。
/checkpoint expand
查看某个 turn 下面更细的 tool-level checkpoints：
bash
/checkpoint expand <tag>示例：
text
> /checkpoint expand 2
[2] 2025-09-18 14:07:10 - add tests
└─ [2.1] write: Add minimal test cases to two_sum.py (modified 1)当一个 turn 内部包含多次文件写入时，expand 可以帮你定位具体是哪一步产生了改动。
/checkpoint diff
比较两个 checkpoint，或把某个 checkpoint 与当前工作区比较：
bash
/checkpoint diff <tag1> [tag2|HEAD]示例：
bash
/checkpoint diff 1 2 # 比较 checkpoint 1 和 checkpoint 2
/checkpoint diff 1 HEAD # 比较 checkpoint 1 和当前状态
/checkpoint diff 1 # 等同于和 HEAD 比较如果你让 Kiro 生成了两个不同实现方案，可以用 diff 直接比较差异，而不是凭记忆判断。
/checkpoint restore
恢复到某个 checkpoint：
bash
/checkpoint restore [<tag>] [--hard]如果不传 tag，Kiro 会显示交互式选择器。
示例：
bash
/checkpoint restore 2 # soft restore 到 checkpoint 2
/checkpoint restore 2 --hard # hard restore 到 checkpoint 2
/checkpoint restore # 交互式选择恢复时，对话历史也会回退到对应 checkpoint，保证 Kiro 的上下文理解与文件状态一致。
/checkpoint clean
删除当前会话的 shadow repository：
bash
/checkpoint clean注意：这会删除当前会话里的所有 checkpoint 数据，执行前请确认不再需要回退。
Soft restore 与 hard restore 的区别
默认恢复：soft restore
bash
/checkpoint restore 2它会：
- 把已跟踪的修改恢复到 checkpoint 状态。
- 恢复在 checkpoint 后被删除的文件。
- 保留 checkpoint 之后新创建的文件。
适合：
- 想撤销某些修改，但保留新写出来的文件。
- 在多个实现方案之间切换。
- 回退具体修改，而不是完全清空后续工作。
强制恢复：hard restore
bash
/checkpoint restore 2 --hard它会让工作区尽量精确匹配 checkpoint：
- 修改过的文件恢复到 checkpoint 状态。
- 删除过的文件被恢复。
- checkpoint 之后新增的已跟踪文件会被删除。
适合：
- 确认要完全放弃近期改动。
- 想从某个干净状态重新开始。
- 当前工作区已经明显跑偏，需要彻底回退。
请谨慎使用 --hard，因为它可能永久删除文件。
典型使用场景
试验不同重构方案
text
> Help me refactor this function
# Kiro 做了一版修改
> /checkpoint list
[0] Initial checkpoint
[1] Refactored function (modified 1)
> Actually, let's try a different approach
> /checkpoint restore 0
# 回到原始状态
> Now try using a different pattern...这种方式适合“先试试看”的工作。你不用提前手动复制文件，也不用担心试验失败后难以回滚。
比较两个实现
text
> Implement feature A
# 第一版实现完成
> /checkpoint list
[1] Implemented feature A (modified 2)
> Now show me an alternative implementation
# 第二版实现完成
> /checkpoint list
[2] Alternative implementation (modified 2)
> /checkpoint diff 1 2
# 查看两种方案的差异在做架构选择或性能优化时，diff 比口头描述更可靠。
追踪任务进度
text
> /checkpoint list
[0] Initial state
[1] Added user model (+1 file)
[2] Added authentication (+2 files)
[3] Added tests (modified 3)
> /checkpoint expand 2
[2] Added authentication
└─ [2.1] write: Create auth.py (+1 file)
└─ [2.2] write: Update routes.py (modified 1)这能帮你复盘 Kiro 在每个阶段改了哪些文件，也方便定位问题从哪一步引入。
从错误尝试中恢复
text
> /checkpoint list
[0] Working code
[1] Attempted optimization (modified 1)
[2] More changes (modified 2)
# 发现优化引入问题
> /checkpoint restore 0
# 回到可工作的状态对“优化后反而坏了”的场景，checkpointing 很实用。
对话历史也会回退
Checkpointing 不只恢复文件，还会把 conversation history 回退到对应 checkpoint。这样做是为了避免文件已经恢复，但 Kiro 的上下文仍然记着后续错误尝试，导致它继续基于错误假设回答。
恢复后会发生：
- checkpoint 之后的消息从上下文中移除。
- Kiro 的理解回到当时状态。
- 文件状态和对话状态保持一致。
最佳实践
什么时候应该用？
- 实验性改动：想安全试多个方案。
- 复杂重构：每一步都希望可回退。
- 学习和对比：想比较不同实现方式。
- Debug：想确认问题是在哪个阶段引入的。
如何管理 checkpoint？
- 经常用
/checkpoint list查看进度。 - 在关键节点后确认 checkpoint 已记录。
- 用
/checkpoint diff做方案比较。 - 只有非常确定时才使用
--hard。 - 任务结束后用
/checkpoint clean清理 shadow repo。
限制与注意事项
会话范围限制
- Checkpoints 只存在于当前会话。
- Shadow repository 通常在会话结束后清理。
- 不能跨会话共享 checkpoint。
文件追踪限制
- 只跟踪会话中修改过的文件。
- 不跟踪工作目录之外的文件。
- 二进制文件可被记录，但 diff 结果通常不够有用。
性能限制
- 大文件可能拖慢 checkpoint 操作。
- checkpoint 太多会占用更多磁盘空间。
- 大范围 diff 可能比较慢。
常见排障
Checkpointing 不工作怎么办？
先确认开关：
bash
kiro-cli settings chat.enableCheckpoint如果当前目录不是 Git 仓库，再手动初始化：
bash
/checkpoint init同时留意聊天输出中是否有权限或路径相关错误。
无法恢复 checkpoint 怎么办？
先确认 checkpoint 存在：
bash
/checkpoint list然后检查文件是否有写入权限。建议优先尝试默认的 soft restore，确认无误后再考虑 --hard。
Shadow repository 似乎损坏了怎么办？
可以清理后重新初始化：
bash
/checkpoint clean
/checkpoint init如果仍然异常，开启新会话通常是最直接的恢复方式。
相关功能
常见问题
Checkpointing 会替代 Git 吗？
不会。它只是在当前 Kiro CLI 会话中提供临时快照，不会替代真实 commit、branch、stash 或代码评审流程。
使用 restore 会不会影响对话上下文？
会。恢复到 checkpoint 时，对话历史也会回退到对应位置，这是为了让文件状态和 Kiro 的上下文保持一致。
什么时候不该用 --hard？
只要你还不确定 checkpoint 之后新增的文件是否有价值，就不要用 --hard。默认 soft restore 更安全，适合作为第一选择。