ws-ckpt

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 跨工作区重复时必须指定