简易版本控制工具

SKILL.md 节选

# 文档版本快照 (doc-snapshot)

为非技术用户（产品经理等）提供目录级版本管理：每次修改自动留快照，可秒级精确回退，不使用 Git。

## 核心机制

快照库位于目标目录下的 `.snapshots/`：

```
目标目录/
├── .snapshots/
│   ├── data/
│   │   ├── 0001/        # 全量版：完整文件副本（严禁混入任何其他文件）
│   │   └── 0002/        # 增量版（仅 Windows 产生）：manifest.json + 变化文件副本
│   ├── meta/
│   │   ├── 0001.json    # 序号 1 的元数据（显示版本号 + 时间 + 改动说明 + 类型）
│   │   └── 0002.json
│   └── 操作日志.md       # 人类可读的操作台账（只增不减，供用户直接翻阅）
└── （用户的工作文件）
```

六条铁律：

1. **快照不可变**：`.snapshots/data/` 下的内容一旦写入，只新增版本，永不修改或删除已有版本（用户明确要求清理时除外）
2. **回退必留后路**：执行 restore 前，必须先把当前状态保存为快照（描述标明"回退前现场"），保证任何回退都可撤销
3. **描述必写清**：每版元数据（`meta/NNNN.json`）的 name 与 desc 必须写清——name 是用户引用的版本号，desc 是一句人类可读的改动摘要，这是用户回看历史的唯一线索
4. **元数据与数据分离**：版本元数据只放 `meta/NNNN.json`，严禁放进 `data/NNNN/` 内部——全量版 restore 会把 `data/NNNN/` 整个镜像回工作目录，混入的文件会污染用户目录；增量版目录内只允许 manifest.json 与变化文件副本
5. **操作日志只增不减**：`.snapshots/操作日志.md` 每次保存、回退、清理都必须在表格顶部追加一行记录；即使删除了旧版本，日志记录也永不删除——它是用户不问 AI 就能翻阅全部操作的唯一凭证
6. **增量版严禁直接镜像恢复**：增量版（目录内有 manifest.json）必须按"镜像其基础全量版 → 覆盖增量文件 → 应用删除清单"三步重建；直接镜像增量版目录会让工作目录丢掉所有未变化文件

## 第一步：确定平台与目标目录

- 目标目录 = 当前正在编辑的文档目录（当前 workspace，或用户明确指定的目录）
- 平台检测：优先从环境信息判断；不确定时执行 `uname -s`（`Darwin` → macOS；报错或返回 `MINGW*`/`CYGWIN*` → Windows）
- 复制策略随平台：macOS 全部全量克隆（零空间）；Windows 里程碑全量 + 过程版增量（详见 save）

## save（保存快照）

触发时机：
- **首次使用**：目录尚无 `.snapshots/` 时，在动手修改任何文件**之前**先保存（name 固定 `v1`，desc 写"初始版本"），保住改前原始状态
- **自动存（过程版本）**：每完成一轮文档修改（一个需求点落地）后主动执行，无需用户提醒
- **手动存（里程碑版本）**：用户说"存个版本 / 保存快照 / 存档"时

步骤：

1. 若 `.snapshots/data/` 不存在 → 本次为首个版本，name 固定 `v1`，desc 写"初始版本"
2. 序号 = 现有最大序号 + 1，目录名四位零填充（如 `0012`）；序号只用于存储定位、永远递增，用户无需感知
3. 计算显示版本号 name（用户看到并引用的就是它）：
   - **手动存**（用户开口要求保存）→ 主版本 +1：上一版是 `v1.3` → 新版 `v2`；上一版是 `v2` → 新版 `v3`
   - **自动存**（AI 改完自动留痕、回退前现场）→ 主版本不变、次版本 +1：上一版是 `v1` → 新版 `v1.1`；上一版是 `v1.2` → 新版 `v1.3`；上一版是 `v2` → 新版 `v2.1`
   - 铁则：**上一版 = 序号最大的版本，版本号永远向前、永不复用**——即使刚发生过回退。如最新是 v11、回退到 v9.2 后继续工作：回退现场存为 v11.1，后续依次 v11.2、v11.3……绝不产生新的 v9.3（同号不同内容会让"回到 v9.3"产生歧义）
4. 确定版本类型（type）：

SKILL.md 不止这些内容，安装后可阅读全文。

技能包内容

共 4 个文件，合计 28.2 KiB