[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6K30MJVPNFF4VA778AZC512":3,"skill-same:01M6K30MJVPNFF4VA778AZC512":54},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":27,"linkOnly":28,"markdownContent":29,"markdownBody":30,"frontMatter":31,"refName":32,"commitSha":33,"skillDirectory":34,"forksCount":35,"repositoryHtmlUrl":36,"repositoryHomepageUrl":37,"ownerHtmlUrl":38,"ownerBlogUrl":37,"ownerDescription":6,"updatedAt":39,"install":40,"resources":53},"01M6K30MJVPNFF4VA778AZC512","ws-ckpt",null,"Linux 工作区快照(ws-ckpt)。用户想保存或备份工作区当前状态(\"保存一下\"、\"留个底\"、\"先备份\"), 想撤销或恢复文件改动(\"回滚\"、\"撤销\"、\"改回去\"、\"恢复到之前\"、\"刚才那版\"), 想查看、对比或删除历史版本,或要开启\u002F关闭每回合自动快照、定时快照、快照保留策略时使用。 用户没提\"快照\"、只表达保存或恢复工作区文件的意图时同样适用;用户点名 git 操作(commit、branch、reset 到某提交)时不适用。","agentic-os-org\u002FANOLISA","agentic-os-org","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F326861446?v=4","01M6K2QGJPXKNJFSPNB3FYW1R3","Agentic OS","01M6K2QGQ6W3S1A9J9DR1G88NZ",665,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fagentic-os-org\u002FANOLISA\u002Fblob\u002Fmain\u002Fsrc\u002Fws-ckpt\u002Fsrc\u002Fskills\u002Fws-ckpt\u002FSKILL.md",[],[19,20,21,22,23,24,25,26],"ws ckpt","linux","commit","git","branch","reset","定时","文件","2026-11-10 10:12:30",false,"---\nname: ws-ckpt\ndescription: >\n  Linux 工作区快照(ws-ckpt)。用户想保存或备份工作区当前状态(\"保存一下\"、\"留个底\"、\"先备份\"),\n  想撤销或恢复文件改动(\"回滚\"、\"撤销\"、\"改回去\"、\"恢复到之前\"、\"刚才那版\"),\n  想查看、对比或删除历史版本,或要开启\u002F关闭每回合自动快照、定时快照、快照保留策略时使用。\n  用户没提\"快照\"、只表达保存或恢复工作区文件的意图时同样适用;用户点名 git 操作(commit、branch、reset 到某提交)时不适用。\n---\n# ws-ckpt 工作区快照管理\n\n基于 btrfs COW 快照，为任意工作区提供 checkpoint\u002Frollback；实际耗时取决于文件系统、工作负载和机器环境。\n\n## 工作区路径（关键 — 必须遵守）\n\n⚠️ **绝对禁止猜测或推断工作区路径。**\n\n工作区级操作（checkpoint、rollback、diff、cleanup，以及按工作区执行的 delete\u002Flist\u002Fstatus）需要\n`-w \u003Cworkspace>`。执行这些操作前，必须按以下顺序确定路径：\n\n1. 用户在**当前消息中明确给出**了路径 → 直接使用\n2. 否则 → **必须向用户询问**：\"请提供工作区路径（传给 `-w` 的目录）\"，拿到回复后再执行\n\n不得从环境变量、默认路径、或任何隐含上下文中猜测。确定后，本次会话内复用同一个路径。\n\n以下全局查询\u002F操作允许省略 `-w`，不要为此追问路径：\n\n- `list`：列出所有已注册工作区的快照；\n- `status`：查看 daemon 全局状态；\n- 快照 ID 全局唯一时的 `delete`。若 ID 有歧义，再要求用户提供 `-w`。\n\ncwd 占用的拦截由 daemon 层统一处理,skill 不再做前置守卫。\n\n## 用户没点名工具时\n\n用户只说\"留个底\"、\"改回去\"这类话、没指定用什么工具时,优先用 ws-ckpt,并在回复里说明用的是 ws-ckpt 快照:\n\n- **保存**:工作区已注册 → 直接 checkpoint。未注册 → 告诉用户 ws-ckpt 可以为该目录建快照,说明 `init` 会把目录迁到 btrfs 子卷(原路径变为指向子卷的软链),征得同意后再 init + checkpoint。\n- **恢复**:先 `ws-ckpt list -w \u003Cworkspace>`,按时间和 message 找到用户说的那一版;目标不明确时询问,不要猜测。用 `rollback --preview` 展示影响范围;回滚作用于整个工作区,预览包含用户没要求撤销的改动时先确认,再执行 rollback。找不到对应快照时如实说明,再考虑 git 等其他手段,并建议开启[自动快照](#自动快照)。\n- 用户点名 git 时用 git。ws-ckpt 快照可保存未跟踪、未提交的文件状态,不要求先 git add\u002Fcommit;git commit 只保存暂存区内容。\n\n## 触发规则\n\n| 用户说 | 执行命令 | 说明 |\n|--------|----------|------|\n| \"保存一下\"、\"存个快照\"、\"checkpoint\"、\"备份当前状态\" | `checkpoint` | 创建快照 |\n| \"回滚\"、\"撤销\"、\"恢复到之前\"、\"rollback\"、\"改坏了\" | `rollback` | 回滚到指定快照 |\n| \"对比快照\"、\"快照差异\"、\"diff\"、\"改了什么\" | `diff` | 查看两个快照间的文件变更 |\n| \"删掉快照\"、\"清理快照\"、\"delete snapshot\" | `delete` | 删除指定快照 |\n| \"看看快照\"、\"有哪些快照\"、\"list\"、\"列一下\" | `list` | 列出快照 |\n| \"状态\"、\"空间\"、\"status\"、\"工作区怎么样\" | `status` | 查看工作区状态 |\n| \"开启自动快照\"、\"关闭自动快照\" | 见[自动快照](#自动快照) | 每个改动回合结束时建快照 |\n| \"定时快照\"、\"每小时存一次\"、\"关掉定时快照\" | 见[定时快照](#定时快照) | 管理 crontab |\n| \"保留最近 N 个\"、\"快照保留 7 天\" | `config -w` | 见[config](#config--查看或修改自动清理策略) |\n\n## 命令用法\n\n### checkpoint — 创建快照\n\n```bash\nws-ckpt checkpoint -w \u003Cworkspace> [-s \u003Csnapshot-id>] [-m \u003Cmessage>] [--metadata \u003Cjson>]\n```\n\n- `-w`:工作区路径(必填)\n- `-s`:快照 ID(可选，省略时自动生成）\n- `-m`:快照描述(可选)\n- `--metadata`:附加 JSON 元数据(可选)\n\n```bash\nws-ckpt checkpoint -w \u003Cpath-to-workspace> -s before-refactor -m \"重构前备份\"\nws-ckpt checkpoint -w \u003Cpath-to-workspace>  # ID 自动生成\n```\n\n### rollback — 回滚到快照\n\n```bash\nws-ckpt rollback -w \u003Cworkspace> [-s \u003Csnapshot> | -n \u003Csteps>] [--preview]\n```\n\n- `-w`:工作区路径(必填)\n- `-s`:目标快照 ID（与 `-n` 互斥）\n- `-n`:沿当前 HEAD 的父链选择第 N 项（1 = HEAD 本身,2 = HEAD 的父节点;与 `-s` 互斥）\n- `--preview`:预览文件变更，不实际执行回滚\n\n```bash\nws-ckpt rollback -w \u003Cpath-to-workspace> -s before-refactor\nws-ckpt rollback -w \u003Cpath-to-workspace> -n 1          # 恢复当前 HEAD 快照,丢弃之后未快照的改动\nws-ckpt rollback -w \u003Cpath-to-workspace> -s snap1 --preview  # 仅预览\n```\n\n### diff — 查看快照间差异\n\n```bash\nws-ckpt diff -w \u003Cworkspace> -f \u003Cfrom-snapshot> [-t \u003Cto-snapshot>]\n```\n\n- `-w`:工作区路径(必填)\n- `-f`:源快照 ID(必填)\n- `-t`:目标快照 ID(可选，省略时与当前工作区状态比较)\n\n```bash\n# 两个快照之间的差异\nws-ckpt diff -w \u003Cpath-to-workspace> -f before-refactor -t after-refactor\n\n# 快照与当前工作区的差异\nws-ckpt diff -w \u003Cpath-to-workspace> -f before-refactor\n```\n\n### delete — 删除快照\n\n```bash\nws-ckpt delete -s \u003Csnapshot> --force [-w \u003Cworkspace>]\n```\n\n- `-s`:要删除的快照 ID(必填)\n- `--force`:跳过确认，agent执行必须要求跳过确认\n- `-w`:快照 ID 跨工作区重复时必须指定\n\n```bash\nws-ckpt delete -s old-snap --force\n```\n\n### list — 列出快照\n\n```bash\nws-ckpt list [-w \u003Cworkspace>] [--format table|json] [--limit N] [--cursor TOKEN]\n```\n\n- 省略 `-w` 列出所有工作区的快照\n\n```bash\nws-ckpt list\nws-ckpt list -w \u003Cpath-to-workspace>\nws-ckpt list --format json\n```\n\n默认命令会自动读取全部游标页，JSON 仍输出单个数组。仅当用户明确要求分页时使用\n`--limit N`；响应中的 `next_cursor` 可通过 `--cursor '\u003Ctoken>'` 继续读取。游标是不透明\n且绑定查询范围的，不要解析或修改。若记录包含 `detail: \"summary\"` \u002F `omitted_fields`，\n必须明确告知用户该记录因超大 `message`\u002F`metadata` 只返回摘要，但快照 ID 仍可用于\nrollback、diff、delete 等操作。摘要保留的 `created_at`、`pinned`、`missing` 仍在\n`meta` 下；被省略字段缺席，不应当作原本为空。\n\n### status — 查看状态\n\n```bash\nws-ckpt status [-w \u003Cworkspace>]\n```\n\n- 省略 `-w` 查看全局状态\n\n```bash\nws-ckpt status\nws-ckpt status -w \u003Cpath-to-workspace>\n```\n\n### config — 查看或修改自动清理策略\n\n`ws-ckpt config` 的作用域由 scope 决定:不带 scope = 只读 overview(全局配置 + workspace 覆盖统计,带任何修改 flag 会报错);`-g` 全局;`-w \u003Cworkspace>` 局部。\n\n```bash\n# 全局(daemon-wide)\nws-ckpt config -g                                 # 查看\nws-ckpt config -g --enable-auto-cleanup\nws-ckpt config -g --auto-cleanup-keep 30d         # 或整数 20\n\n# 局部(只覆盖本 workspace 的 auto_cleanup \u002F auto_cleanup_keep)\nws-ckpt config -w \u003Cpath-to-workspace>             # 三栏视图: effective \u002F local \u002F global\nws-ckpt config -w \u003Cpath-to-workspace> --auto-cleanup-keep 5\nws-ckpt config -w \u003Cpath-to-workspace> --disable-auto-cleanup\nws-ckpt config -w \u003Cpath-to-workspace> --reset     # 删除 policy.toml,沿用全局\n```\n\n`-w` 仅可覆盖 `auto_cleanup` 和 `auto_cleanup_keep`,interval\u002Fimage\u002Fhealth-check 等是 daemon-wide,带 `-w` 设置会被 CLI 拒绝。\n\n用户没说\"全局\"时一律用 `-w`,只改当前工作区:\"保留最近 N 个\" → `--enable-auto-cleanup --auto-cleanup-keep N`;\"保留 7 天\" → `--enable-auto-cleanup --auto-cleanup-keep 7d`;\"恢复默认\" → `--reset`。\n\n## 自动快照\n\n默认关闭。用户说\"开启自动快照\"后在本会话内持续生效,直到用户说\"关闭自动快照\"。已启用 ws-ckpt 插件时,开关改用插件的 `ws-ckpt-config`（`autoCheckpoint`）,不再同时执行下面的 skill 自动快照流程,避免重复建快照或关闭不生效。\n\n开启时先按上文规则确定工作区路径,用只读查询核对注册状态(不会自动 init)。本节命令中的 `\u003Cshell-quoted-workspace>` 与 turn_end 命令相同,按下文的参数数组或引用方法传入:\n\n```bash\nws-ckpt status -w \u003Cshell-quoted-workspace>\n```\n\n- 成功且输出该工作区信息 → 已注册,即使快照数为 0。\n- 明确返回 `Error [WorkspaceNotFound]` → 未注册;不要仅凭退出码 1 或 list 为空判断。\n- 连接失败、注册异常或其他错误 → 停止并报告,不要继续 init 或 checkpoint。\n\n未注册时先说明 `init` 会迁移目录并把原路径变为软链,首次 `checkpoint` 也会自动 init;征得同意后再执行下面的命令,拒绝或 init 失败则不继续开启。\n\n```bash\nws-ckpt init -w \u003Cshell-quoted-workspace>   # 已注册时无副作用\nws-ckpt checkpoint -w \u003Cshell-quoted-workspace> -m \"session start\" --metadata '{\"auto\":true,\"type\":\"initial\"}'\n```\n\n基线成功后才告知已开启;失败时告知尚未开启,不要让用户误以为已有保护快照。\n\n初始快照只在开启时建立一次,用于恢复到改动前。之后持续覆盖本会话,不需要用户每轮提醒。**回复用户之前**,按本回合实际发生的文件修改判断,不要仅凭请求里是否有“修改”字样判断:\n\n| 本回合 | 动作 |\n|--------|------|\n| 实际新建\u002F修改\u002F删除了工作区内文件(含命令产生的文件变更) | 建一个快照,见下方命令 |\n| 只读(查看、搜索、问答、list\u002Fdiff\u002Fstatus),或尝试修改但未产生文件变更 | 不建 |\n| 执行过真实 rollback(非 `--preview`) | 不建,保持回滚后的父链 |\n\nmessage 取本回合请求的前 80 字。执行工具支持参数数组时,把本会话已确定的工作区路径和 message 原文作为独立参数传入,不额外添加 shell 引号。\n\n通过 shell 执行时,下面两个占位符这样生成:\n\n- `\u003Cshell-quoted-workspace>`:对本会话已确定的 `\u003Cworkspace>` 路径做 shell 引用,不是另一个路径,不需要重新查询。\n- `\u003Cshell-quoted-message>`:对截断后的 message 做同样的 shell 引用。\n\n引用方法:先把内容中的每个单引号 `'` 替换为 `'\"'\"'`,再在整体两端加单引号;也可用 `shlex.quote` 生成。例如 `\u002Fmnt\u002Fmy ws` 得到 `'\u002Fmnt\u002Fmy ws'`,`O'Reilly` 得到 `'O'\"'\"'Reilly'`。将引用结果直接替换对应占位符,不要再加一层双引号或用 eval 再次求值。无法安全传入 message 时改用固定值 `'turn_end snapshot'`,并在回复中说明降级。\n\n```bash\nws-ckpt checkpoint -w \u003Cshell-quoted-workspace> -m \u003Cshell-quoted-message> --metadata '{\"auto\":true,\"type\":\"turn_end\"}'\n```\n\nturn_end 快照保存该回合改动后的状态,message 通常是该回合请求(降级时为 `turn_end snapshot`)。撤销某回合应选该快照的 `parent_id`,不是按 message 选该快照本身。`-n 1` 指当前 HEAD;HEAD 正是最近回合的 turn_end 快照时,撤销该回合用 `-n 2`。若先建保护快照,先确定目标 ID 再用 `-s` 回滚,避免新增快照改变 `-n` 的含义。\n\n- 每回合最多建一个,不要每改一个文件建一次;用户要中间点时再按 checkpoint 规则显式建。\n- turn_end 快照失败不中断任务,但必须在回复中明确告知本回合改动未保存为快照及错误原因,不要宣称已保护。\n- 开启状态不跨会话保留。用户要求长期开启时,建议用户把\"对 \u003Cworkspace> 开启 ws-ckpt 自动快照\"写进 agent 的全局或项目指令文件。\n\n## 定时快照\n\n通过当前用户的 crontab 定时执行 checkpoint,与 ws-ckpt 插件写入的行格式一致:\n\n```\n\u003Ccron 表达式> \u003Cws-ckpt 绝对路径> checkpoint -w '\u003Cworkspace>' -s \"cron-$(date +\\%s)\" -m \"scheduled snapshot\" --metadata '{\"auto\":true,\"type\":\"cron\"}' >\u002Fdev\u002Fnull 2>&1\n```\n\n- 只用标准 5 段 cron 表达式。用户意图无法精确表达(如\"每 90 分钟\")时不要写近似值,给出最接近的选项,等用户确认。\n- 工作区路径含单引号或换行时不写 crontab,告知用户原因。\n- 已启用 ws-ckpt 插件时改用插件的 `ws-ckpt-config` 工具,否则插件会在会话开始时按自身配置覆盖这些行。\n\n查看本工作区的定时快照:\n\n```bash\ncrontab -l 2>\u002Fdev\u002Fnull | grep -F -e \"checkpoint -w '\u003Cworkspace>' \" -e \"checkpoint -w \u003Cworkspace> \"\n```\n\n修改时先单独执行 `crontab -l`:失败且报错不是 `no crontab for` 时停止并报告,不要写回。然后用下面的模板把本工作区的**完整**表达式列表整体写回(增加 = 原列表加一项;删除 = 去掉一项),其他 crontab 行原样保留。关闭时移除全部表达式,写成 `for expr in; do`,保留循环体、过滤和写回步骤;空列表使循环执行零次,只移除本工作区的旧行:\n\n```bash\nws='\u003Cworkspace>'; bin=$(command -v ws-ckpt) || exit 1\n{\n  crontab -l 2>\u002Fdev\u002Fnull | grep -vF -e \"checkpoint -w '$ws' \" -e \"checkpoint -w $ws \"\n  for expr in '0 * * * *'; do   # 本工作区最终保留的全部表达式\n    echo \"$expr $bin checkpoint -w '$ws' -s \\\"cron-\\$(date +\\\\%s)\\\" -m \\\"scheduled snapshot\\\" --metadata '{\\\"auto\\\":true,\\\"type\\\":\\\"cron\\\"}' >\u002Fdev\u002Fnull 2>&1\"\n  done\n} | crontab -\ncrontab -l | grep -F -e \"checkpoint -w '$ws' \" -e \"checkpoint -w $ws \"   # 核对写入结果\n```\n\n关闭后先确认 `crontab -l` 成功,再确认无本工作区匹配行(此时 grep 返回 1 是预期结果),才告知已关闭。\n\n定时快照依赖 crond 运行(`systemctl is-active crond`)。\n\n## 注意事项\n\n- checkpoint 用 `-s` 指定快照 ID（可省略，自动生成）；rollback 和 delete 也用 `-s` 指定快照 ID\n- daemon 必须运行中(`systemctl status ws-ckpt` 确认),否则所有命令报连接错误\n- 执行破坏性操作前务必先 checkpoint;已开启自动快照且上次快照后没有新改动时不必重复建\n","# ws-ckpt 工作区快照管理\n\n基于 btrfs COW 快照，为任意工作区提供 checkpoint\u002Frollback；实际耗时取决于文件系统、工作负载和机器环境。\n\n## 工作区路径（关键 — 必须遵守）\n\n⚠️ **绝对禁止猜测或推断工作区路径。**\n\n工作区级操作（checkpoint、rollback、diff、cleanup，以及按工作区执行的 delete\u002Flist\u002Fstatus）需要\n`-w \u003Cworkspace>`。执行这些操作前，必须按以下顺序确定路径：\n\n1. 用户在**当前消息中明确给出**了路径 → 直接使用\n2. 否则 → **必须向用户询问**：\"请提供工作区路径（传给 `-w` 的目录）\"，拿到回复后再执行\n\n不得从环境变量、默认路径、或任何隐含上下文中猜测。确定后，本次会话内复用同一个路径。\n\n以下全局查询\u002F操作允许省略 `-w`，不要为此追问路径：\n\n- `list`：列出所有已注册工作区的快照；\n- `status`：查看 daemon 全局状态；\n- 快照 ID 全局唯一时的 `delete`。若 ID 有歧义，再要求用户提供 `-w`。\n\ncwd 占用的拦截由 daemon 层统一处理,skill 不再做前置守卫。\n\n## 用户没点名工具时\n\n用户只说\"留个底\"、\"改回去\"这类话、没指定用什么工具时,优先用 ws-ckpt,并在回复里说明用的是 ws-ckpt 快照:\n\n- **保存**:工作区已注册 → 直接 checkpoint。未注册 → 告诉用户 ws-ckpt 可以为该目录建快照,说明 `init` 会把目录迁到 btrfs 子卷(原路径变为指向子卷的软链),征得同意后再 init + checkpoint。\n- **恢复**:先 `ws-ckpt list -w \u003Cworkspace>`,按时间和 message 找到用户说的那一版;目标不明确时询问,不要猜测。用 `rollback --preview` 展示影响范围;回滚作用于整个工作区,预览包含用户没要求撤销的改动时先确认,再执行 rollback。找不到对应快照时如实说明,再考虑 git 等其他手段,并建议开启[自动快照](#自动快照)。\n- 用户点名 git 时用 git。ws-ckpt 快照可保存未跟踪、未提交的文件状态,不要求先 git add\u002Fcommit;git commit 只保存暂存区内容。\n\n## 触发规则\n\n| 用户说 | 执行命令 | 说明 |\n|--------|----------|------|\n| \"保存一下\"、\"存个快照\"、\"checkpoint\"、\"备份当前状态\" | `checkpoint` | 创建快照 |\n| \"回滚\"、\"撤销\"、\"恢复到之前\"、\"rollback\"、\"改坏了\" | `rollback` | 回滚到指定快照 |\n| \"对比快照\"、\"快照差异\"、\"diff\"、\"改了什么\" | `diff` | 查看两个快照间的文件变更 |\n| \"删掉快照\"、\"清理快照\"、\"delete snapshot\" | `delete` | 删除指定快照 |\n| \"看看快照\"、\"有哪些快照\"、\"list\"、\"列一下\" | `list` | 列出快照 |\n| \"状态\"、\"空间\"、\"status\"、\"工作区怎么样\" | `status` | 查看工作区状态 |\n| \"开启自动快照\"、\"关闭自动快照\" | 见[自动快照](#自动快照) | 每个改动回合结束时建快照 |\n| \"定时快照\"、\"每小时存一次\"、\"关掉定时快照\" | 见[定时快照](#定时快照) | 管理 crontab |\n| \"保留最近 N 个\"、\"快照保留 7 天\" | `config -w` | 见[config](#config--查看或修改自动清理策略) |\n\n## 命令用法\n\n### checkpoint — 创建快照\n\n```bash\nws-ckpt checkpoint -w \u003Cworkspace> [-s \u003Csnapshot-id>] [-m \u003Cmessage>] [--metadata \u003Cjson>]\n```\n\n- `-w`:工作区路径(必填)\n- `-s`:快照 ID(可选，省略时自动生成）\n- `-m`:快照描述(可选)\n- `--metadata`:附加 JSON 元数据(可选)\n\n```bash\nws-ckpt checkpoint -w \u003Cpath-to-workspace> -s before-refactor -m \"重构前备份\"\nws-ckpt checkpoint -w \u003Cpath-to-workspace>  # ID 自动生成\n```\n\n### rollback — 回滚到快照\n\n```bash\nws-ckpt rollback -w \u003Cworkspace> [-s \u003Csnapshot> | -n \u003Csteps>] [--preview]\n```\n\n- `-w`:工作区路径(必填)\n- `-s`:目标快照 ID（与 `-n` 互斥）\n- `-n`:沿当前 HEAD 的父链选择第 N 项（1 = HEAD 本身,2 = HEAD 的父节点;与 `-s` 互斥）\n- `--preview`:预览文件变更，不实际执行回滚\n\n```bash\nws-ckpt rollback -w \u003Cpath-to-workspace> -s before-refactor\nws-ckpt rollback -w \u003Cpath-to-workspace> -n 1          # 恢复当前 HEAD 快照,丢弃之后未快照的改动\nws-ckpt rollback -w \u003Cpath-to-workspace> -s snap1 --preview  # 仅预览\n```\n\n### diff — 查看快照间差异\n\n```bash\nws-ckpt diff -w \u003Cworkspace> -f \u003Cfrom-snapshot> [-t \u003Cto-snapshot>]\n```\n\n- `-w`:工作区路径(必填)\n- `-f`:源快照 ID(必填)\n- `-t`:目标快照 ID(可选，省略时与当前工作区状态比较)\n\n```bash\n# 两个快照之间的差异\nws-ckpt diff -w \u003Cpath-to-workspace> -f before-refactor -t after-refactor\n\n# 快照与当前工作区的差异\nws-ckpt diff -w \u003Cpath-to-workspace> -f before-refactor\n```\n\n### delete — 删除快照\n\n```bash\nws-ckpt delete -s \u003Csnapshot> --force [-w \u003Cworkspace>]\n```\n\n- `-s`:要删除的快照 ID(必填)\n- `--force`:跳过确认，agent执行必须要求跳过确认\n- `-w`:快照 ID 跨工作区重复时必须指定\n\n```bash\nws-ckpt delete -s old-snap --force\n```\n\n### list — 列出快照\n\n```bash\nws-ckpt list [-w \u003Cworkspace>] [--format table|json] [--limit N] [--cursor TOKEN]\n```\n\n- 省略 `-w` 列出所有工作区的快照\n\n```bash\nws-ckpt list\nws-ckpt list -w \u003Cpath-to-workspace>\nws-ckpt list --format json\n```\n\n默认命令会自动读取全部游标页，JSON 仍输出单个数组。仅当用户明确要求分页时使用\n`--limit N`；响应中的 `next_cursor` 可通过 `--cursor '\u003Ctoken>'` 继续读取。游标是不透明\n且绑定查询范围的，不要解析或修改。若记录包含 `detail: \"summary\"` \u002F `omitted_fields`，\n必须明确告知用户该记录因超大 `message`\u002F`metadata` 只返回摘要，但快照 ID 仍可用于\nrollback、diff、delete 等操作。摘要保留的 `created_at`、`pinned`、`missing` 仍在\n`meta` 下；被省略字段缺席，不应当作原本为空。\n\n### status — 查看状态\n\n```bash\nws-ckpt status [-w \u003Cworkspace>]\n```\n\n- 省略 `-w` 查看全局状态\n\n```bash\nws-ckpt status\nws-ckpt status -w \u003Cpath-to-workspace>\n```\n\n### config — 查看或修改自动清理策略\n\n`ws-ckpt config` 的作用域由 scope 决定:不带 scope = 只读 overview(全局配置 + workspace 覆盖统计,带任何修改 flag 会报错);`-g` 全局;`-w \u003Cworkspace>` 局部。\n\n```bash\n# 全局(daemon-wide)\nws-ckpt config -g                                 # 查看\nws-ckpt config -g --enable-auto-cleanup\nws-ckpt config -g --auto-cleanup-keep 30d         # 或整数 20\n\n# 局部(只覆盖本 workspace 的 auto_cleanup \u002F auto_cleanup_keep)\nws-ckpt config -w \u003Cpath-to-workspace>             # 三栏视图: effective \u002F local \u002F global\nws-ckpt config -w \u003Cpath-to-workspace> --auto-cleanup-keep 5\nws-ckpt config -w \u003Cpath-to-workspace> --disable-auto-cleanup\nws-ckpt config -w \u003Cpath-to-workspace> --reset     # 删除 policy.toml,沿用全局\n```\n\n`-w` 仅可覆盖 `auto_cleanup` 和 `auto_cleanup_keep`,interval\u002Fimage\u002Fhealth-check 等是 daemon-wide,带 `-w` 设置会被 CLI 拒绝。\n\n用户没说\"全局\"时一律用 `-w`,只改当前工作区:\"保留最近 N 个\" → `--enable-auto-cleanup --auto-cleanup-keep N`;\"保留 7 天\" → `--enable-auto-cleanup --auto-cleanup-keep 7d`;\"恢复默认\" → `--reset`。\n\n## 自动快照\n\n默认关闭。用户说\"开启自动快照\"后在本会话内持续生效,直到用户说\"关闭自动快照\"。已启用 ws-ckpt 插件时,开关改用插件的 `ws-ckpt-config`（`autoCheckpoint`）,不再同时执行下面的 skill 自动快照流程,避免重复建快照或关闭不生效。\n\n开启时先按上文规则确定工作区路径,用只读查询核对注册状态(不会自动 init)。本节命令中的 `\u003Cshell-quoted-workspace>` 与 turn_end 命令相同,按下文的参数数组或引用方法传入:\n\n```bash\nws-ckpt status -w \u003Cshell-quoted-workspace>\n```\n\n- 成功且输出该工作区信息 → 已注册,即使快照数为 0。\n- 明确返回 `Error [WorkspaceNotFound]` → 未注册;不要仅凭退出码 1 或 list 为空判断。\n- 连接失败、注册异常或其他错误 → 停止并报告,不要继续 init 或 checkpoint。\n\n未注册时先说明 `init` 会迁移目录并把原路径变为软链,首次 `checkpoint` 也会自动 init;征得同意后再执行下面的命令,拒绝或 init 失败则不继续开启。\n\n```bash\nws-ckpt init -w \u003Cshell-quoted-workspace>   # 已注册时无副作用\nws-ckpt checkpoint -w \u003Cshell-quoted-workspace> -m \"session start\" --metadata '{\"auto\":true,\"type\":\"initial\"}'\n```\n\n基线成功后才告知已开启;失败时告知尚未开启,不要让用户误以为已有保护快照。\n\n初始快照只在开启时建立一次,用于恢复到改动前。之后持续覆盖本会话,不需要用户每轮提醒。**回复用户之前**,按本回合实际发生的文件修改判断,不要仅凭请求里是否有“修改”字样判断:\n\n| 本回合 | 动作 |\n|--------|------|\n| 实际新建\u002F修改\u002F删除了工作区内文件(含命令产生的文件变更) | 建一个快照,见下方命令 |\n| 只读(查看、搜索、问答、list\u002Fdiff\u002Fstatus),或尝试修改但未产生文件变更 | 不建 |\n| 执行过真实 rollback(非 `--preview`) | 不建,保持回滚后的父链 |\n\nmessage 取本回合请求的前 80 字。执行工具支持参数数组时,把本会话已确定的工作区路径和 message 原文作为独立参数传入,不额外添加 shell 引号。\n\n通过 shell 执行时,下面两个占位符这样生成:\n\n- `\u003Cshell-quoted-workspace>`:对本会话已确定的 `\u003Cworkspace>` 路径做 shell 引用,不是另一个路径,不需要重新查询。\n- `\u003Cshell-quoted-message>`:对截断后的 message 做同样的 shell 引用。\n\n引用方法:先把内容中的每个单引号 `'` 替换为 `'\"'\"'`,再在整体两端加单引号;也可用 `shlex.quote` 生成。例如 `\u002Fmnt\u002Fmy ws` 得到 `'\u002Fmnt\u002Fmy ws'`,`O'Reilly` 得到 `'O'\"'\"'Reilly'`。将引用结果直接替换对应占位符,不要再加一层双引号或用 eval 再次求值。无法安全传入 message 时改用固定值 `'turn_end snapshot'`,并在回复中说明降级。\n\n```bash\nws-ckpt checkpoint -w \u003Cshell-quoted-workspace> -m \u003Cshell-quoted-message> --metadata '{\"auto\":true,\"type\":\"turn_end\"}'\n```\n\nturn_end 快照保存该回合改动后的状态,message 通常是该回合请求(降级时为 `turn_end snapshot`)。撤销某回合应选该快照的 `parent_id`,不是按 message 选该快照本身。`-n 1` 指当前 HEAD;HEAD 正是最近回合的 turn_end 快照时,撤销该回合用 `-n 2`。若先建保护快照,先确定目标 ID 再用 `-s` 回滚,避免新增快照改变 `-n` 的含义。\n\n- 每回合最多建一个,不要每改一个文件建一次;用户要中间点时再按 checkpoint 规则显式建。\n- turn_end 快照失败不中断任务,但必须在回复中明确告知本回合改动未保存为快照及错误原因,不要宣称已保护。\n- 开启状态不跨会话保留。用户要求长期开启时,建议用户把\"对 \u003Cworkspace> 开启 ws-ckpt 自动快照\"写进 agent 的全局或项目指令文件。\n\n## 定时快照\n\n通过当前用户的 crontab 定时执行 checkpoint,与 ws-ckpt 插件写入的行格式一致:\n\n```\n\u003Ccron 表达式> \u003Cws-ckpt 绝对路径> checkpoint -w '\u003Cworkspace>' -s \"cron-$(date +\\%s)\" -m \"scheduled snapshot\" --metadata '{\"auto\":true,\"type\":\"cron\"}' >\u002Fdev\u002Fnull 2>&1\n```\n\n- 只用标准 5 段 cron 表达式。用户意图无法精确表达(如\"每 90 分钟\")时不要写近似值,给出最接近的选项,等用户确认。\n- 工作区路径含单引号或换行时不写 crontab,告知用户原因。\n- 已启用 ws-ckpt 插件时改用插件的 `ws-ckpt-config` 工具,否则插件会在会话开始时按自身配置覆盖这些行。\n\n查看本工作区的定时快照:\n\n```bash\ncrontab -l 2>\u002Fdev\u002Fnull | grep -F -e \"checkpoint -w '\u003Cworkspace>' \" -e \"checkpoint -w \u003Cworkspace> \"\n```\n\n修改时先单独执行 `crontab -l`:失败且报错不是 `no crontab for` 时停止并报告,不要写回。然后用下面的模板把本工作区的**完整**表达式列表整体写回(增加 = 原列表加一项;删除 = 去掉一项),其他 crontab 行原样保留。关闭时移除全部表达式,写成 `for expr in; do`,保留循环体、过滤和写回步骤;空列表使循环执行零次,只移除本工作区的旧行:\n\n```bash\nws='\u003Cworkspace>'; bin=$(command -v ws-ckpt) || exit 1\n{\n  crontab -l 2>\u002Fdev\u002Fnull | grep -vF -e \"checkpoint -w '$ws' \" -e \"checkpoint -w $ws \"\n  for expr in '0 * * * *'; do   # 本工作区最终保留的全部表达式\n    echo \"$expr $bin checkpoint -w '$ws' -s \\\"cron-\\$(date +\\\\%s)\\\" -m \\\"scheduled snapshot\\\" --metadata '{\\\"auto\\\":true,\\\"type\\\":\\\"cron\\\"}' >\u002Fdev\u002Fnull 2>&1\"\n  done\n} | crontab -\ncrontab -l | grep -F -e \"checkpoint -w '$ws' \" -e \"checkpoint -w $ws \"   # 核对写入结果\n```\n\n关闭后先确认 `crontab -l` 成功,再确认无本工作区匹配行(此时 grep 返回 1 是预期结果),才告知已关闭。\n\n定时快照依赖 crond 运行(`systemctl is-active crond`)。\n\n## 注意事项\n\n- checkpoint 用 `-s` 指定快照 ID（可省略，自动生成）；rollback 和 delete 也用 `-s` 指定快照 ID\n- daemon 必须运行中(`systemctl status ws-ckpt` 确认),否则所有命令报连接错误\n- 执行破坏性操作前务必先 checkpoint;已开启自动快照且上次快照后没有新改动时不必重复建\n",{"name":5,"description":7},"main","0719b08b193a46759436b0436614daf8af1ce516","src\u002Fws-ckpt\u002Fsrc\u002Fskills\u002Fws-ckpt",195,"https:\u002F\u002Fgithub.com\u002Fagentic-os-org\u002FANOLISA","https:\u002F\u002Fagentic-os.sh\u002F","https:\u002F\u002Fgithub.com\u002Fagentic-os-org","2026-11-14 23:49:17",{"source":8,"skillName":5,"commands":41,"prompt":51,"zipAvailable":52},[42,45,48],{"tool":43,"command":44},"npx","npx skills add agentic-os-org\u002FANOLISA --skill ws-ckpt",{"tool":46,"command":47},"bunx","bunx skills add agentic-os-org\u002FANOLISA --skill ws-ckpt",{"tool":49,"command":50},"pnpm","pnpm dlx skills add agentic-os-org\u002FANOLISA --skill ws-ckpt","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fagentic-os-org\u002FANOLISA\u002Fblob\u002Fmain\u002Fsrc\u002Fws-ckpt\u002Fsrc\u002Fskills\u002Fws-ckpt\u002FSKILL.md",true,[],[55,89,106,124,137,153],{"skillNo":56,"name":57,"nameZh":6,"description":58,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":59,"categories":60,"keywords":66,"publishedAt":27},"01M6K30G7BBZB1VCPE3NE08KZP","skillfs-mount","Help users configure, mount, and unmount a skillfs FUSE virtual filesystem on their local machine (e.g. for openclaw). Covers analyzing existing skill usage to suggest view configuration, generating skillfs-views.toml, mounting, and graceful unmount. Use this skill when the user asks to: set up skillfs, configure skill views, mount or unmount skillfs, check if skillfs is running, or get help organizing their skills directory (especially for openclaw users).","https:\u002F\u002Fgithub.com\u002Fagentic-os-org\u002FANOLISA\u002Fblob\u002Fmain\u002Fsrc\u002Fskillfs\u002Fdocs\u002Fskills\u002Fskillfs-mount\u002FSKILL.md",[61],{"categoryNo":62,"categoryName":63,"taxonomyType":64,"taxonomyTypeDesc":65},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88],"mount","skillfs mount","running","virtual","when","use","toml","machine","filesystem","for","view","skill usage","usage","SET","existing skill","openclaw","analyzing","directory","configure","local","up","get",{"skillNo":90,"name":91,"nameZh":6,"description":92,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":93,"categories":94,"keywords":99,"publishedAt":27},"01M6K30CJW0X3V5PG4GP26TB63","test-skill","A test skill used in integration tests.","https:\u002F\u002Fgithub.com\u002Fagentic-os-org\u002FANOLISA\u002Fblob\u002Fmain\u002Fsrc\u002Fskillfs\u002Fcrates\u002Fskillfs-fuse\u002Ftests\u002Ffixtures\u002Ftest-skill\u002FSKILL.md",[95,98],{"categoryNo":96,"categoryName":97,"taxonomyType":64,"taxonomyTypeDesc":65},"01JBSEEDCAT000000000000008","测试与质量",{"categoryNo":62,"categoryName":63,"taxonomyType":64,"taxonomyTypeDesc":65},[100,101,102,103,104,105],"test","Test Skill","integration tests","integration","tests","true",{"skillNo":107,"name":108,"nameZh":6,"description":109,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":110,"categories":111,"keywords":112,"publishedAt":27},"01M6K304VCM7N6AR4PMYNDP3A7","storage-resize","Linux 磁盘扩容技能（RPM 包管理系统），实现云盘扩容后自动完成分区调整和文件系统扩容。支持系统盘\u002F数据盘在线扩容，适配 XFS\u002FEXT4\u002FBtrfs 文件系统。适用于 RPM 包管理的 Linux 系统（如 Alibaba Cloud Linux）。","https:\u002F\u002Fgithub.com\u002Fagentic-os-org\u002FANOLISA\u002Fblob\u002Fmain\u002Fsrc\u002Fos-skills\u002Fsystem-admin\u002Fstorage-resize\u002FSKILL.md",[],[113,114,115,20,116,117,26,118,119,120,121,122,123],"storage resize","storage","system","btrfs","数据","alibaba","cloud","ecs","operations","rpm","aliyun",{"skillNo":125,"name":126,"nameZh":6,"description":127,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":128,"categories":129,"keywords":130,"publishedAt":27},"01M6K2ZJEGANYH9TGGG25H7WVF","ktuner","内核参数自动调优。分析系统配置，输出调优建议并可一键应用，支持自动回滚。使用场景：系统性能优化、安全加固、内核参数诊断。","https:\u002F\u002Fgithub.com\u002Fagentic-os-org\u002FANOLISA\u002Fblob\u002Fmain\u002Fsrc\u002Fos-skills\u002Fsystem-admin\u002Fktuner\u002FSKILL.md",[],[126,131,132,133,134,135,136],"Production","shell","run","command","安全","core",{"skillNo":138,"name":139,"nameZh":6,"description":140,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":141,"categories":142,"keywords":143,"publishedAt":27},"01M6K2ZD5K40XCX8R1EA85MS7P","backup-restore","处理所有备份与恢复任务，覆盖四个层面：工作区（项目\u002F数据库\u002F代码）、用户数据（家目录\u002Fdotfiles\u002F密钥）、操作系统（全量系统\u002F磁盘镜像\u002FLVM 快照）、阿里云快照（云盘快照\u002F自动策略\u002F跨地域复制\u002F整机镜像）。适用于 RPM 包管理的 Linux 系统（如 Alibaba Cloud Linux）纯命令行环境，使用 yum 包管理器。当用户提到备份、恢复、快照、归档、回滚、克隆、迁移、容灾等任何涉及数据保存或恢复的请求时触发此技能，即使请求看起来很简单也应使用。","https:\u002F\u002Fgithub.com\u002Fagentic-os-org\u002FANOLISA\u002Fblob\u002Fmain\u002Fsrc\u002Fos-skills\u002Fsystem-admin\u002Fbackup-restore\u002FSKILL.md",[],[144,145,146,122,147,118,117,119,148,149,150,151,20,123,152],"backup","restore","backup restore","dotfiles","release","lvm","maintenance","beta","runtime",{"skillNo":154,"name":155,"nameZh":6,"description":156,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":157,"categories":158,"keywords":159,"publishedAt":27},"01M6K2Z7KJ486EKKZ2V64SHA52","linux-admin","此技能专为 Alibaba Cloud Linux 4 (ALinux 4) 设计，用于管理 Linux 服务器、编写 shell 脚本、配置 systemd 服务、管理网络。触发场景包括：bash 脚本编写、systemd 单元、SSH 配置、firewalld 防火墙配置、NetworkManager 网络管理、文件权限、进程管理、磁盘管理、文件系统操作，以及任何需要 ALinux 4 系统管理的任务。","https:\u002F\u002Fgithub.com\u002Fagentic-os-org\u002FANOLISA\u002Fblob\u002Fmain\u002Fsrc\u002Fos-skills\u002Fsystem-admin\u002Falinux-admin\u002FSKILL.md",[],[160,161,20,162,163,26,164,75,115,165,166,118,167,168,169,170,171,172,123,173],"linux admin","admin","openai","codex","alinux","gemini","networking","tuning","cli","code","Bash","design","performance","openai-codex"]