EN 中文

# Checkpoint — Two-Layer Safety Net

# Checkpoint — 双层安全网

Per-turn git snapshots and per-file undo/redo for model-driven changes.

自动整轮回滚和单步撤销，让模型动过代码后随时撤回。

seek's built-in safety net automatically snapshots the working tree before every destructive action. Two complementary layers cover different granularities:

seek 内置的双层 checkpoint 安全网，让你在模型动过代码后随时撤回——不管是整个工作区回滚到上一轮，还是单文件撤销上一步 write/edit。

Layer | 层 | Granularity | 粒度 | Command | 命令 | Dependency | 依赖
--- | --- | --- | --- | --- | --- | --- | ---
Git checkpoint | Per-turn (cross-tool) | 整轮（跨工具） | `/checkpoints` / `/restore` / `seek checkpoint` | git repo + git binary
File checkpoint | Per write/edit | 单次 write/edit | `/undo` / `/redo` / `seek undo` | None (git-independent)

## Git Checkpoint — Per-Turn Rollback

## Git checkpoint — 整轮回滚

Before every first destructive action (write / edit / mutating bash) per turn, seek snapshots the working tree via `git stash create` + `git update-ref` to `refs/seek/checkpoints/<sid>/<turn>`.

每当模型发起第一个破坏性操作，seek 自动快照工作区——通过 git stash create + git update-ref 将当前工作树的状态固定到 refs/seek/checkpoints/<session-id>/<turn>。

### List checkpoints

### 查看检查点

    $ seek checkpoint list
    $ seek checkpoint list --session <id>   # specific session
    $ seek checkpoint list --json           # JSONL output

### Restore

### 回滚

    $ seek checkpoint restore 3
    $ seek checkpoint restore 3 --session <id>

Uses `git read-tree --reset -u <ref>` — an in-place overwrite. No branching.

覆盖式回滚，不衍生分支。

### Prune

### 清理

    $ seek checkpoint prune --before 2025-01-01

Checkpoints also enter git's natural GC cycle (90-day default expiry).

检查点也受 git 自身 GC 管理（默认 90 天过期）。

## File Checkpoint — Per-Step Undo/Redo

## 文件 checkpoint — 单步撤销/重做

Every write/edit snapshots the prior file content to a content-addressed SHA-256 blob with an append-only event log. Supports undo and redo.

每次 write/edit 自动备份旧文件内容到内容寻址 blob，记录事件日志。支持撤销和重做。

### Undo

### 撤销

    $ /undo          # TUI: undo last write/edit (global)
    $ /undo <path>   # TUI: undo last write/edit on specific file
    $ seek undo      # CLI
    $ seek undo -n 3      # CLI: undo last 3 steps
    $ seek undo <path>    # CLI: undo specific file only

### Redo

### 重做

    $ /redo          # TUI: redo last undone change
    $ /redo <path>   # TUI: redo last undo on specific file
    $ seek redo      # CLI
    $ seek redo -n 3      # CLI: redo last 3 steps

Note: 注意： New write/edit operations truncate the redo history (classic editor semantics). 新的 write/edit 操作会截断重做历史（经典编辑器语义）。

## CLI Reference

## CLI 参考

    $ seek checkpoint — inspect / restore / prune the safety-net layer

    Usage:
      seek checkpoint <command> [flags] [args]

    Commands:
      list                   List git checkpoints (default: most recent session)
      restore <turn>         Restore working tree to named checkpoint
      prune --before <date>  Delete checkpoint refs older than a date

    Shared flags:
      --session <id>         Target a specific session (default: most recent)
      --json                 (list) emit JSONL on stdout

    See also:
      seek undo / seek redo  File-level undo/redo

## TUI Slash Commands

## TUI 斜杠命令

Command | 命令 | Action | 作用
--- | --- | --- | ---
`/undo` | Undo last write/edit | 撤销最近一次 write/edit
`/undo <path>` | Undo last write/edit on specific file | 撤销对指定文件的最近一次 write/edit
`/redo` | Redo last undone change | 重做最近一次撤销
`/redo <path>` | Redo last undo on specific file | 重做对指定文件的最近一次撤销
`/restore` | Roll back to latest git checkpoint (or `/restore <turn>` to specify turn) | 回滚到最新 git checkpoint（或 /restore <turn> 指定轮次）
`/checkpoints` | List current session git checkpoints | 列出当前会话的 git 检查点

## Design Notes

## 设计要点

- Zero disturbance — No permission prompts for checkpoint writes. TUI status bar shows "✓ checkpoint #N".
- 零打扰——checkpoint 写入不弹 picker，TUI 状态栏显示 "✓ checkpoint #N"。
- No git pollution — Uses `refs/seek/checkpoints/` namespace, never touches HEAD or stash.
- 不污染 git 历史——使用 refs/seek/checkpoints/ 自定义 ref 命名空间。
- Graceful degradation — No git repo? Git checkpoint silently skips, file checkpoint still works.
- 优雅降级——非 git 目录时 git checkpoint 静默跳过，文件 checkpoint 仍工作。
- Content-addressed dedup — Identical content shares one blob.
- 内容寻址去重——相同内容的文件只存储一次 blob。
- External modification detection — Before restoring, re-hashes current content to detect external edits; refuses unless --force.
- 外部修改检测——恢复前重新计算当前文件哈希，若与预期不符则拒绝（除非 --force）。

See guide-references.md — LSP-based semantic find-references via the `references` tool, protected by checkpoint undo/redo. 另见 guide-references.md——references 工具用 LSP 做语义符号引用查找，checkpoint 的 undo/redo 保护这些查找后的编辑。