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

ws-ckpt 工作区快照管理

基于 btrfs COW 快照，为任意工作区提供 checkpoint/rollback；实际耗时取决于文件系统、工作负载和机器环境。

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

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

工作区级操作（checkpoint、rollback、diff、cleanup，以及按工作区执行的 delete/list/status）需要 -w <workspace>。执行这些操作前，必须按以下顺序确定路径：

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

不得从环境变量、默认路径、或任何隐含上下文中猜测。确定后，本次会话内复用同一个路径。

以下全局查询/操作允许省略 -w，不要为此追问路径：

• list：列出所有已注册工作区的快照；
• status：查看 daemon 全局状态；
• 快照 ID 全局唯一时的 delete。若 ID 有歧义，再要求用户提供 -w。

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] [--limit N] [--cursor TOKEN]

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

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

默认命令会自动读取全部游标页，JSON 仍输出单个数组。仅当用户明确要求分页时使用 --limit N；响应中的 next_cursor 可通过 --cursor '<token>' 继续读取。游标是不透明 且绑定查询范围的，不要解析或修改。若记录包含 detail: "summary" / omitted_fields， 必须明确告知用户该记录因超大 message/metadata 只返回摘要，但快照 ID 仍可用于 rollback、diff、delete 等操作。摘要保留的 created_at、pinned、missing 仍在 meta 下；被省略字段缺席，不应当作原本为空。

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