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 — 创建快照 ```bash ws-ckpt checkpoint -w <workspace> [-s <snapshot-id>] [-m <message>] [--metadata <json>] ``` - `-w`:工作区路径(必填) - `-s`:快照 ID(可选，省略时自动生成） - `-m`:快照描述(可选) - `--metadata`:附加 JSON 元数据(可选) ```bash ws-ckpt checkpoint -w <path-to-workspace> -s before-refactor -m "重构前备份" ws-ckpt checkpoint -w <path-to-workspace> # ID 自动生成 ``` ### rollback — 回滚到快照 ```bash ws-ckpt rollback -w <workspace> [-s <snapshot> | -n <steps>] [--preview] ``` - `-w`:工作区路径(必填) - `-s`:目标快照 ID（与 `-n` 互斥） - `-n`:沿父链回滚 N 步（与 `-s` 互斥） - `--preview`:预览文件变更，不实际执行回滚 ```bash 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 — 查看快照间差异 ```bash ws-ckpt diff -w <workspace> -f <from-snapshot> [-t <to-snapshot>] ``` - `-w`:工作区路径(必填) - `-f`:源快照 ID(必填) - `-t`:目标快照 ID(可选，省略时与当前工作区状态比较) ```bash # 两个快照之间的差异 ws-ckpt diff -w <path-to-workspace> -f before-refactor -t after-refactor # 快照与当前工作区的差异 ws-ckpt diff -w <path-to-workspace> -f before-refactor ``` ### delete — 删除快照 ```bash ws-ckpt delete -s <snapshot> --force [-w <workspace>] ``` - `-s`:要删除的快照 ID(必填) - `--force`:跳过确认，agent执行必须要求跳过确认 - `-w`:快照 ID 跨工作区重复时必须指定 ```bash ws-ckpt delete -s old-snap --force ``` ### list — 列出快照 ```bash ws-ckpt list [-w <workspace>] [--format table|json] ``` - 省略 `-w` 列出所有工作区的快照 ```bash ws-ckpt list ws-ckpt list -w <path-to-workspace> ws-ckpt list --format json ``` ### status — 查看状态 ```bash ws-ckpt status [-w <workspace>] ``` - 省略 `-w` 查看全局状态 ```bash ws-ckpt status ws-ckpt status -w <path-to-workspace> ``` ### config — 查看或修改自动清理策略 `ws-ckpt config` 的作用域由 scope 决定:不带 scope = 只读 overview(全局配置 + workspace 覆盖统计,带任何修改 flag 会报错);`-g` 全局;`-w <workspace>` 局部。 ```bash # 全局(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