Agent Skill

简易版本控制工具

文档版本快照管理,为非技术用户提供目录级版本控制。AI 每完成一轮文档修改(PRD、需求文档、方案等)后自动保存带版本号,可立即切换版本不用等待

办公效率·小鱼干·来自 skill_hub·skillhub.cn ↗
skillhub install @user_cbeb91bb/doc-snapshot
1 Stars·2.5万 综合热度·8,524 字文档·源站更新 2026-10-26

README 文档

8,524 字

文档版本快照 (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"产生歧义)
  1. 确定版本类型(type):
  • macOS:所有版本均为全量版(克隆复制零空间,无需增量)
  • Windows:手动存(里程碑)为全量版;自动存为增量版(基于最近一个全量版),但变化文件总量超过其基础全量版大小的 50% 时,自动升级为全量版
  1. 按平台与类型执行复制命令(见下)
  2. 用 Write 工具写入 .snapshots/meta/0012.json(含 type;增量版含 base)
  3. 更新操作日志(格式见下方"操作日志"小节),在表格顶部插入一行:手动存操作列写"保存(里程碑)",自动存写"保存"
  4. 向用户汇报:已保存 v2.1:{改动摘要}

macOS(APFS 克隆复制,系统自带 cp):未变化的文件与工作目录共享存储块,几乎不占额外空间,只有真正变化的文件才占新空间;克隆是写时复制,修改任一方互不影响,历史绝不因原地编辑被污染。

mkdir -p ".snapshots/data/0012"
find . -mindepth 1 -maxdepth 1 ! -name '.snapshots' ! -name '.DS_Store' ! -name 'Thumbs.db' ! -name '~$*' -exec cp -Rc {} ".snapshots/data/0012/" \;
find ".snapshots/data/0012" \( -name '.DS_Store' -o -name 'Thumbs.db' -o -name '~$*' \) -delete

若 cp -c 报错(旧式 HFS+ 等卷不支持克隆),退回 rsync 全量复制:

rsync -a --exclude='.snapshots' --exclude='.DS_Store' --exclude='~$*' --exclude='Thumbs.db' ./ ".snapshots/data/0012/"

Windows(robocopy + PowerShell,系统自带,在 PowerShell 执行):

全量版(里程碑、以及变化量超基础版 50% 的自动存):

robocopy "." ".snapshots\data\0012" /E /XD .snapshots /XF "~$*" .DS_Store Thumbs.db /NJH /NJS /NDL /NFL

⚠️ robocopy 退出码 0–7 均为成功(1 = 有文件被复制),≥ 8 才是失败,勿误判。

增量版(自动存的常规情况,三步):设最近全量版序号对应的目录为 B(如 0001)。

⚠️ 增量清单 = 工作目录相对基础全量版的全部当前差异——包含之前轮次改过但尚未还原的文件(如 v1.1 改过 001、本轮又改 002,则 v1.2 的清单同时含 001 与 002 的最新内容),严禁只存本轮改动。这样每个增量版都能配合基础版一步独立恢复,clean 也可安全删除任何一版。

① 找出工作目录相对基础版的变化(按相对路径 + 大小 + 修改时间对比,输出 ADDED / DELETED / CHANGED 三组清单):

$base = ".snapshots\data\0001"
$baseFiles = Get-ChildItem $base -Recurse -File | ForEach-Object { @{ Path = $_.FullName.Substring((Resolve-Path $base).Path.Length + 1); Size = $_.Length; Time = $_.LastWriteTimeUtc } }
$workFiles = Get-ChildItem "." -Recurse -File | Where-Object { $_.FullName -notmatch '\\\.snapshots\\' -and $_.Name -notlike '~$*' -and $_.Name -ne '.DS_Store' -and $_.Name -ne 'Thumbs.db' } | ForEach-Object { @{ Path = $_.FullName.Substring((Resolve-Path ".").Path.Length + 1); Size = $_.Length; Time = $_.LastWriteTimeUtc } }
$baseMap = @{}; $baseFiles | ForEach-Object { $baseMap[$_.Path] = $_ }
$workMap = @{}; $workFiles | ForEach-Object { $workMap[$_.Path] = $_ }
"=== ADDED ===";   ($workFiles | Where-Object { -not $baseMap.ContainsKey($_.Path) } | ForEach-Object { $_.Path })
"=== DELETED ==="; ($baseFiles | Where-Object { -not $workMap.ContainsKey($_.Path) } | ForEach-Object { $_.Path })
"=== CHANGED ==="; ($workFiles | Where-Object { $baseMap.ContainsKey($_.Path) -and ($baseMap[$_.Path].Size -ne $_.Size -or $baseMap[$_.Path].Time -ne $_.Time) } | ForEach-Object { $_.Path })

② 判断:若 CHANGED + ADDED 文件大小总和超过基础版大小((Get-ChildItem $base -Recurse -File | Measure-Object Length -Sum).Sum)的 50% → 改存全量版(上方全量命令)。否则:新建 .snapshots\data\0012 目录,用 Write 工具写入 manifest.json(内容见③),再把 CHANGED + ADDED 的文件按相对路径逐个复制进去(目标子目录不存在时先 New-Item -ItemType Directory 创建):

New-Item -ItemType Directory -Path ".snapshots\data\0012" -Force | Out-Null
Copy-Item "会员积分系统PRD.md" -Destination ".snapshots\data\0012\会员积分系统PRD.md" -Force

③ manifest.json(增量版专用,放 data/0012/manifest.json):

{
  "base": 1,
  "changed": ["会员积分系统PRD.md"],
  "added": ["积分商城原型说明.md"],
  "deleted": []
}

空清单为合法边界情况:若三组清单全为空(典型场景:里程碑 v2 存完后未做任何修改就要求回退——回退前现场与其 base 零差异),照常建目录并写入三组均为空数组的 manifest.json(目录内仅有 manifest.json),meta 照常记录;恢复时等价于直接镜像基础版。严禁因清单为空而跳过建版或误判对比出错。

若目标目录含明显的构建/依赖产物(如 node_modules、dist),一并追加到排除列表。

空间说明:macOS 克隆副本未变化的文件不占新空间;Windows 无克隆机制,采用"里程碑全量 + 过程版增量"——磁盘只随里程碑数线性增长,AI 的中间修改只存变化量,几十轮对话也吃不满磁盘。含大量视频、安装包、构建产物的目录不建议使用。

.snapshots/meta/0012.json 内容(时间用 Shell 取:mac date '+%Y-%m-%d %H:%M',win Get-Date -Format 'yyyy-MM-dd HH:mm'):

{
  "seq": 12,
  "name": "v2.1",
  "type": "delta",
  "base": 11,
  "time": "2026-09-08 14:30",
  "desc": "把登录方式从手机号验证码改为扫码,删除了短信模块"
}

(全量版则 "type": "full" 且无 base 字段)

操作日志(.snapshots/操作日志.md)

人类可读的操作台账,供用户不问 AI、直接用肉眼翻阅全部历史。首行固定表头,每次操作在表格顶部(表头下方)插入一行,只增不减:

时间版本操作说明
2026-09-08 14:30v2.1保存把登录方式从手机号验证码改为扫码
2026-09-08 14:00v2保存(里程碑)登录方案定稿
2026-09-08 13:58v1.1回退从 v2.1 回退到 v1.1,回退前现场已存为 v2.2

操作类型共四种:保存(AI 自动留痕)、保存(里程碑)(用户主动要求)、回退(说明里注明从哪版回到哪版、现场存为了哪版)、清理(删除旧版本,记录仍保留)。

list(版本历史)

一条命令批量读取全部元数据(mac:cat .snapshots/meta/.json;win:Get-Content .snapshots\meta\.json),按 seq 从大到小排列,表格输出(大版本是用户标记的里程碑,小版本是 AI 自动留痕):

版本时间改动说明
v2.109-08 14:30调整退货审批流,增加财务节点
v209-08 14:00里程碑:登录方案定稿
v1.109-08 10:12新增会员积分需求
v109-07 18:00初始版本

用户只是想看上一版内容而不回退时,直接读取对应快照目录里的文件展示,不改动工作目录。

restore(回退)

触发:用户说"回到 v1.2 / 回到第 X 版 / 回退到 / 撤销刚才的修改"。

流程(顺序不可乱):

  1. list 展示版本历史,与用户确认目标版本(用户已明确指定版本号时跳过),由目标版本的 name 定位其序号目录(如 v1.2 → data/0003/)
  2. 先 save 当前状态(按自动存规则计版本号),desc 固定写:回退到 {目标name} 前的现场
  3. 按目标版本类型执行恢复(见下):全量版直接镜像;增量版三步重建
  4. 汇报:已回退到 {目标name}(时间 + 改动说明),当前目录内容与该版本完全一致
  5. 上下文对齐(必做):回退只还原文件,对话记忆仍停留在回退前的最新状态——必须明确告知用户这一点,并主动询问:“接下来是基于 {目标name} 开新方向,还是重做刚才回退掉的内容?”用户本轮的回答是后续所有修改的基准;回退后的第一轮修改前必须重新读取文件当前内容,严禁凭回退前的对话记忆直接写入(防止按旧认知覆盖刚恢复的文件)
  6. 更新操作日志:顶部插入 | {时间} | {目标name} | 回退 | 从 {回退前name} 回退到 {目标name},回退前现场已存为 {现场name} |

全量版恢复(目标目录内无 manifest.json,直接镜像):

# macOS
rsync -a --delete --exclude='.snapshots' ".snapshots/data/0003/" ./
# Windows
robocopy ".snapshots\data\0003" "." /MIR /XD .snapshots /NJH /NJS /NDL /NFL

增量版恢复(目标目录内有 manifest.json,三步顺序不可乱):设目标增量版序号目录为 D(如 0007)、manifest 中 base 指向的基础全量版为 B(如 0003)。

# macOS
rsync -a --delete --exclude='.snapshots' ".snapshots/data/0003/" ./        # ① 先镜像恢复基础全量版
rsync -a --exclude='manifest.json' ".snapshots/data/0007/" ./                # ② 覆盖增量文件(不删除多余文件)
# ③ 按 manifest.json 的 deleted 清单逐个删除(rm -f "文件路径")
# Windows
robocopy ".snapshots\data\0003" "." /MIR /XD .snapshots /NJH /NJS /NDL /NFL   # ① 先镜像恢复基础全量版
robocopy ".snapshots\data\0007" "." /E /XF manifest.json /NJH /NJS /NDL /NFL  # ② 覆盖增量文件(不删除多余文件)
# ③ 按 manifest.json 的 deleted 清单逐个删除(Remove-Item "文件路径" -Force)

"撤销刚才 AI 的修改" = 回退到最新一版的前一版。

⚠️ 镜像命令会删除目标端多余文件使目录与快照完全一致。排除规则(保护 .snapshots 自身)严禁去掉,否则快照库会被删除。

内容校验守则(确认改动生效、验证恢复结果等任何需要校验文件内容的场合,双平台适用):

  • 优先用文件 hash 对比(mac shasum "文件",win (Get-FileHash "文件").Hash)或 ASCII 特征串(如 Select-String '\+100')验证内容,严禁依赖中文正则/关键词 pattern——经终端转发的 PowerShell 命令里,中文 pattern 可能因控制台编码(GBK)乱码而假阴性(实际匹配却返回 False);中文文件内容本身与中文路径传参不受影响
  • 外部命令(rsync/robocopy/cp)改完文件后,Read 工具可能短暂显示缓存的旧内容,与 hash 结果矛盾时一律以 hash 为准,勿误判为恢复失败(IDE 缓存现象,非 skill 问题)

diff(对比两版)

macOS:

diff -rq ".snapshots/data/0002" ".snapshots/data/0003"

Windows:

robocopy ".snapshots\data\0002" ".snapshots\data\0003" /L /E /NJH /NJS /NDL

输出为文件级差异列表,需汇总为业务语言汇报,例如:"这一版主要改了《PRD-登录模块》,另新增 2 张原型图"。

若参与对比的版本是增量版(目录内有 manifest.json):先把该版重建到临时目录再对比——镜像其基础全量版到 .snapshots/tmp/、覆盖增量文件(排除 manifest.json)、应用删除清单,对比完成后删除 .snapshots/tmp/。

clean(清理旧版本,仅用户明确要求时执行)

磁盘空间不足且用户明确要求删除某些旧版本时,成对删除对应的 .snapshots/data/NNNN/ 目录与 .snapshots/meta/NNNN.json(各版本相互独立,无全局索引)。执行前列出版本让用户确认,并提示:删除后该版本无法恢复。建议始终保留初始版(v1)与最近 3 个版本。⚠️ 删除全量版前必须检查:若仍有增量版的 base 指向它,该全量版与其全部增量版须一起删除(或都不删),否则增量版会失去基础无法恢复。删除后,在操作日志顶部插入:| {时间} | — | 清理 | 删除了版本 {name 列表} |(日志记录保留,不随版本删除)。

交互规范

  • 所有汇报使用业务语言,不出现 rsync、robocopy、镜像等技术词汇
  • 每轮修改完成的汇报末尾附当前显示版本号(如 v2.1),不向用户提及内部序号
  • 用户要回退但说不清版本时,先展示最近 5 版供其选择
  • 回退后的第一轮修改:动手前必须重新读取目标文件当前内容,以文件实际内容为准,严禁凭回退前的对话记忆直接写入;用户未说明方向时先确认“基于回退后的版本继续,还是重做回退掉的内容”
  • 用户想自己翻历史时,告知可直接打开 .snapshots/操作日志.md(无需问 AI)

同分类其他技能

查看全部 ›