高级用法：run checkpoint 与续跑

权威来源：run 现场 checkpoint 续跑设计。 状态：已落地并跨进程验证（回合末落盘 → 重启后能续）。

它解决什么

一次 run 可能很长。进程重启、实例切换、或用户主动恢复时，不能从头再来 —— 要从「上次的现场」继续，且不能重复副作用。

代码在哪

python-engine/app/agent/checkpoint.py   407 行 —— 落盘与恢复
python-engine/app/agent/resume.py       461 行 —— 恢复流程
python-engine/app/agent/runtime.py      _save_checkpoint（回合末落盘）
python-engine/app/run_registry.py       运行注册表

恢复不是"取最新"

恢复有多个分支，其中一条值得特别注意：

若标记跨过了一个更晚的已完成回合 ⇒ 保留整段 WAL 并发 warn，而不是直接跳到最新。

也就是说：宁可多留证据、并发警告，也不静默地丢掉一段历史。 这与本仓库"证据优先"的一贯做法一致。

三条不变量

1. 回合末落盘：checkpoint 的写入点是回合边界，不是任意时刻 —— 这样恢复的语义才明确。
2. 副作用要幂等：恢复后重放的部分不能重复产生外部效果（靠幂等键，见 app/queue/idempotency.py）。
3. 恢复要留痕：走了哪条分支、为什么，要能被审计读到，而不是只写在日志里。

与"文件级回退（rewind）"的区别

• checkpoint / 续跑（本页）：已实现，是"往前继续"。
• 文件级回退（rewind）：未实现，是"往回撤销"（事务化 + 覆盖率显式 + 冲突类型化）。 它是差距分析里"值得追"的新能力，需迁移；形态要改成「引擎侧持久化 + 网关端点」， 不照搬会话旁挂目录。

延伸阅读

• 会话 · 队列与幂等
• 生产：多实例 —— 实例切换时的续跑

---

本页由仓库内 docs/wiki/ 同步生成（scripts/sync_github_wiki.py）。请不要直接编辑本 wiki —— 改动会下次同步时被覆盖；请改仓库里的对应文件。