文件保护与版本管理

本 Skill 使用 MiniVCS 对所有文件操作进行版本追踪。

脚本位置：与本 SKILL.md 同目录下的 scripts/minivcs/minivcs.py
（执行前需先确定本文件所在目录，下文以 $SKILL_DIR 表示）

核心机制：

• - 修改：保存增量 Diff + 修改前完整快照，支持回滚
• 删除：将文件完整移入 ~/.openclaw/minivcs/trash/，支持恢复
• 所有文件均建立索引，根据重要程度设定不同留存期
• 每次操作后自动扫描整体记录表，找出已到期记录并通知用户确认

使用限制：

• - 二进制文件（图片、PDF、音视频等）：无法进行文本 diff，改为直接将文件完整复制一份存为 .bak 备份，支持回滚还原，原文件不受影响。需告知用户：二进制文件每次调用 record 都会保存一份完整副本，占用空间相对较大。
• 首条记录无法回滚：一个文件第一次被 record 时尚无历史基准，该条记录没有快照；此后每次编辑后调用一次 record_modify，均会自动保存快照，支持回滚到任意一次编辑前的状态

前置检查：确认 Python 已安装

在执行任何操作前，必须先检查用户环境是否安装了 Python 3。

检测方式

CODEBLOCK0

• - 输出 Python 3.x.x 即为已安装，可继续
• 提示 command not found 或 不是内部或外部命令 则需要帮用户安装

安装指引（未安装时）

macOS

推荐通过 Homebrew 安装：

CODEBLOCK1

如果用户在中国大陆，访问 GitHub 速度慢，安装前先配置镜像源加速：

CODEBLOCK2

如果用户使用 bash 而非 zsh，把上面的 ~/.zshrc 替换为 ~/.bash_profile。
中国大陆镜像源参考：清华 https://mirrors.tuna.tsinghua.edu.cn/help/homebrew/

也可引导用户前往官网下载安装包：https://www.python.org/downloads/macos/

Linux（Debian / Ubuntu）

CODEBLOCK3

Linux（CentOS / RHEL / Fedora）

CODEBLOCK4

Windows

推荐引导用户从官网下载安装：https://www.python.org/downloads/windows/

安装时勾选 "Add Python to PATH"，否则命令行无法识别 python 命令。

安装完成后在 PowerShell 中验证：
CODEBLOCK5

注意：Windows 上部分系统命令为 python，macOS/Linux 为 python3。
后续所有命令中的 python 请根据实际环境替换为正确的命令名。

留存策略

每条记录创建时自动设置 expireAt（到期时间戳）和 expireAtDatetime（可读时间）字段。

操作流程

第一步：初始化 MiniVCS 工作目录

首次使用时自动创建存储目录，无需额外操作：

CODEBLOCK6

数据统一存储在 ~/.openclaw/minivcs/：

~/.openclaw/minivcs/
  logs.json     # 操作日志（含 expireAt 字段）
  diffs/        # 文本文件修改的增量补丁
  bases/        # 下次比较的基准（按完整相对路径命名，无同名冲突）
  snapshots/    # 文本文件修改前的完整快照（用于回滚）
  trash/        # 已删除文件的完整备份（用于恢复）
  backups/      # 二进制文件的 .bak 完整副本备份（用于回滚）

第二步：操作前询问用户确认

删除或修改文件前，必须向用户说明以下内容，并等待确认：

1. 1. 要操作的文件路径
2. 操作类型（修改 / 删除）
3. 操作目的与意图
4. 可能产生的影响
5. 告知保护范围：只有文本文件会被自动备份和追踪；若涉及二进制文件（图片、PDF 等），不会被记录，需用户自行保管
6. 告知文本文件已纳入版本记录，可随时恢复/回滚

操作前示例：
CODEBLOCK8

操作完成后，必须告知用户记录结果，示例：

# 修改完成后
已完成对 path/to/file.py 的修改，并记录了本次变更（Record ID: 1710000000000）。
- 变更摘要：+5 lines, -2 lines
- 留存期：7 天（到期时间：2026-03-20 10:00:00）
- 可回滚：是（使用 restore 1710000000000 可恢复到修改前状态）
如需查看 Diff 或回滚，请告诉我。

# 删除完成后
已将 path/to/file.py 移入回收站并建立备份（Record ID: 1710000001000）。
- 留存期：14 天（到期时间：2026-03-27 10:00:00）[重要文件]
如需恢复该文件，请告诉我。

第三步：使用 MiniVCS 操作文件

修改文件（支持回滚）

每次编辑后调用一次 record 即可，快照链自动形成，支持回滚到任意历史状态：

CODEBLOCK10

CODEBLOCK11

Python API：
CODEBLOCK12

删除文件（支持恢复）

不要直接删除文件，改用 record_delete，文件自动移入 trash：

CODEBLOCK13

Python API：
CODEBLOCK14

恢复/回滚

同一命令 restore 处理两种场景：

CODEBLOCK15

Python API：

result = vcs.restore_file(record_id="...")
# DELETE 成功后：记录标记为 RESTORED，不再出现在 trash 列表
# MODIFY 成功后：记录标记为 ROLLED_BACK
# 重复恢复：返回 {"success": False, "error": "already been restored/rolled_back"}

第四步：处理到期清理通知（每次操作后必须执行）

每次调用 record_modify 或 record_delete 后，返回值中包含 due_for_cleanup 字段。

若 due_for_cleanup 不为空，Agent 必须：

1. 1. 向用户展示到期记录列表（从早到晚排序）
2. 询问用户哪些可以删除、哪些需要延期

展示格式示例：
CODEBLOCK17

用户响应后的处理：

CODEBLOCK18

命令行：

# 查看所有到期记录
python "$SKILL_DIR/scripts/minivcs/minivcs.py" cleanup --project-root <project_root>

# 确认清理
python "$SKILL_DIR/scripts/minivcs/minivcs.py" cleanup --confirm --project-root <project_root>

# 延期某条记录
python "$SKILL_DIR/scripts/minivcs/minivcs.py" extend <record_id> --project-root <project_root>

其他常用操作

CODEBLOCK20

记录字段说明

完整操作流程图

CODEBLOCK21