ws-ckpt

name	ws-ckpt
description	工作区快照管理。用户说"保存一下"、"存个快照"时创建 checkpoint，仅限 Linux; 说"回滚"、"撤销"、"恢复到之前"时 rollback;说"删掉快照"时 delete; 说"对比快照"、"快照改了什么"时 diff; 说"看看快照"、"有哪些快照"时 list;说"查看快照状态"、"查看快照剩余空间"时 status。

ws-ckpt 工作区快照管理

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

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

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

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

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

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

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

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

触发规则

用户说	执行命令	说明
"保存一下"、"存个快照"、"checkpoint"、"备份当前状态"	checkpoint	创建快照
"回滚"、"撤销"、"恢复到之前"、"rollback"、"改坏了"	rollback	回滚到指定快照
"对比快照"、"快照差异"、"diff"、"改了什么"	diff	查看两个快照间的文件变更
"删掉快照"、"清理快照"、"delete snapshot"	delete	删除指定快照
"看看快照"、"有哪些快照"、"list"、"列一下"	list	列出快照
"状态"、"空间"、"status"、"工作区怎么样"	status	查看工作区状态

命令用法

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