Ws Ckpt

ws-ckpt 工作区快照管理

基于 btrfs COW 快照,为任意工作区提供微秒级 checkpoint/rollback。

工作区路径（关键 — 必须遵守）

⚠️ 绝对禁止猜测或推断工作区路径。

ws-ckpt 的所有命令都需要 -w <workspace> 指定工作区路径。执行任何命令前，必须按以下顺序确定 -w 参数：

1. 用户在当前消息中明确给出了路径 → 直接使用
2. 否则 → 必须向用户询问："请提供工作区路径（传给 -w 的目录）"，拿到回复后再执行

不得从环境变量、默认路径、或任何隐含上下文中猜测。

确定后，本次会话内复用同一个 workspace 路径，不要重复询问。

cwd 占用的拦截由 daemon 层统一处理,skill 不再做前置守卫。

触发规则

命令用法

checkpoint — 创建快照

ws-ckpt checkpoint -w <workspace> [-s <snapshot-id>] [-m <message>] [--metadata <json>]

• -w:工作区路径(必填)
• -s:快照 ID(可选，省略时自动生成）
• -m:快照描述(可选)
• --metadata:附加 JSON 元数据(可选)

ws-ckpt checkpoint -w <path-to-workspace> -s before-refactor -m "重构前备份"
ws-ckpt checkpoint -w <path-to-workspace>  # ID 自动生成

rollback — 回滚到快照

ws-ckpt rollback -w <workspace> [-s <snapshot> | -n <steps>] [--preview]

• -w:工作区路径(必填)
• -s:目标快照 ID（与 -n 互斥）
• -n:沿父链回滚 N 步（与 -s 互斥）
• --preview:预览文件变更，不实际执行回滚

ws-ckpt rollback -w <path-to-workspace> -s before-refactor
ws-ckpt rollback -w <path-to-workspace> -n 1          # 回滚到上一个快照
ws-ckpt rollback -w <path-to-workspace> -s snap1 --preview  # 仅预览

diff — 查看快照间差异

ws-ckpt diff -w <workspace> -f <from-snapshot> [-t <to-snapshot>]

• -w:工作区路径(必填)
• -f:源快照 ID(必填)
• -t:目标快照 ID(可选，省略时与当前工作区状态比较)

# 两个快照之间的差异
ws-ckpt diff -w <path-to-workspace> -f before-refactor -t after-refactor

# 快照与当前工作区的差异
ws-ckpt diff -w <path-to-workspace> -f before-refactor

delete — 删除快照

ws-ckpt delete -s <snapshot> --force [-w <workspace>]

• -s:要删除的快照 ID(必填)
• --force:跳过确认，agent执行必须要求跳过确认
• -w:快照 ID 跨工作区重复时必须指定

ws-ckpt delete -s old-snap --force

list — 列出快照

ws-ckpt list [-w <workspace>] [--format table|json]

• 省略 -w 列出所有工作区的快照

ws-ckpt list
ws-ckpt list -w <path-to-workspace>
ws-ckpt list --format json

status — 查看状态

ws-ckpt status [-w <workspace>]

• 省略 -w 查看全局状态

ws-ckpt status
ws-ckpt status -w <path-to-workspace>

config — 查看或修改自动清理策略

ws-ckpt config 的作用域由 scope 决定:不带 scope = 只读 overview(全局配置 + workspace 覆盖统计,带任何修改 flag 会报错);-g 全局;-w <workspace> 局部。

# 全局(daemon-wide)
ws-ckpt config -g                                 # 查看
ws-ckpt config -g --enable-auto-cleanup
ws-ckpt config -g --auto-cleanup-keep 30d         # 或整数 20

# 局部(只覆盖本 workspace 的 auto_cleanup / auto_cleanup_keep)
ws-ckpt config -w <path-to-workspace>             # 三栏视图: effective / local / global
ws-ckpt config -w <path-to-workspace> --auto-cleanup-keep 5
ws-ckpt config -w <path-to-workspace> --disable-auto-cleanup
ws-ckpt config -w <path-to-workspace> --reset     # 删除 policy.toml,沿用全局

-w 仅可覆盖 auto_cleanup 和 auto_cleanup_keep,interval/image/health-check 等是 daemon-wide,带 -w 设置会被 CLI 拒绝。

注意事项

• checkpoint 用 -s 指定快照 ID（可省略，自动生成）；rollback 和 delete 也用 -s 指定快照 ID
• daemon 必须运行中(systemctl status ws-ckpt 确认),否则所有命令报连接错误
• 执行破坏性操作前务必先 checkpoint