下载地址
https://www.zhengdianxue.com/wp-content/uploads/skills/user_cbeb91bb--doc-snapshot.zip将提示词发送给你的 AI 安装该 skills
请根据 https://skillhub.cn/install/skillhub.md,安装 @user_cbeb91bb/doc-snapshot。文档版本快照管理,为非技术用户提供目录级版本控制。AI 每完成一轮文档修改(PRD、需求文档、方案等)后自动保存带版本号,可立即切换版本不用等待
阅读全文 (展开查看完整说明)
概述
文档版本快照 (doc-snapshot)
为非技术用户(产品经理等)提供目录级版本管理:每次修改自动留快照,可秒级精确回退,不使用 Git。
核心机制
快照库位于目标目录下的 .snapshots/:
目标目录/
├── .snapshots/
│ ├── data/
│ │ ├── 0001/ # 全量版:完整文件副本(严禁混入任何其他文件)
│ │ └── 0002/ # 增量版(仅 Windows 产生):manifest.json + 变化文件副本
│ ├── meta/
│ │ ├── 0001.json # 序号 1 的元数据(显示版本号 + 时间 + 改动说明 + 类型)
│ │ └── 0002.json
│ └── 操作日志.md # 人类可读的操作台账(只增不减,供用户直接翻阅)
└── (用户的工作文件)六条铁律:
- 快照不可变:
.snapshots/data/下的内容一旦写入,只新增版本,永不修改或删除已有版本(用户明确要求清理时除外) - 回退必留后路:执行 restore 前,必须先把当前状态保存为快照(描述标明"回退前现场"),保证任何回退都可撤销
- 描述必写清:每版元数据(
meta/NNNN.json)的 name 与 desc 必须写清——name 是用户引用的版本号,desc 是一句人类可读的改动摘要,这是用户回看历史的唯一线索 - 元数据与数据分离:版本元数据只放
meta/NNNN.json,严禁放进data/NNNN/内部——全量版 restore 会把data/NNNN/整个镜像回工作目录,混入的文件会污染用户目录;增量版目录内只允许 manifest.json 与变化文件副本 - 操作日志只增不减:
.snapshots/操作日志.md每次保存、回退、清理都必须在表格顶部追加一行记录;即使删除了旧版本,日志记录也永不删除——它是用户不问 AI 就能翻阅全部操作的唯一凭证 - 增量版严禁直接镜像恢复:增量版(目录内有 manifest.json)必须按"镜像其基础全量版 → 覆盖增量文件 → 应用删除清单"三步重建;直接镜像增量版目录会让工作目录丢掉所有未变化文件
第一步:确定平台与目标目录
- 目标目录 = 当前正在编辑的文档目录(当前 workspace,或用户明确指定的目录)
- 平台检测:优先从环境信息判断;不确定时执行
uname -s(Darwin→ macOS;报错或返回MINGW*/CYGWIN*→ Windows) - 复制策略随平台:macOS 全部全量克隆(零空间);Windows 里程碑全量 + 过程版增量(详见 save)
save(保存快照)
触发时机:
- 首次使用:目录尚无
.snapshots/时,在动手修改任何文件之前先保存(name 固定v1,desc 写"初始版本"),保住改前原始状态 - 自动存(过程版本):每完成一轮文档修改(一个需求点落地)后主动执行,无需用户提醒
- 手动存(里程碑版本):用户说"存个版本 / 保存快照 / 存档"时
步骤:
- 若
.snapshots/data/不存在 → 本次为首个版本,name 固定v1,desc 写"初始版本" - 序号 = 现有最大序号 + 1,目录名四位零填充(如
0012);序号只用于存储定位、永远递增,用户无需感知 - 计算显示版本号 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% 时,自动升级为全量版
- 按平台与类型执行复制命令(见下)
- 用 Write 工具写入
.snapshots/meta/0012.json(含 type;增量版含 base) - 更新操作日志(格式见下方"操作日志"小节),在表格顶部插入一行:手动存操作列写"保存(里程碑)",自动存写"保存"
- 向用户汇报:
已保存 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 "." ".snapshotsdata 012" /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 = ".snapshotsdata 001"
$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% → 改存全量版(上方全量命令)。否则:新建 .snapshotsdata 012 目录,用 Write 工具写入 manifest.json(内容见③),再把 CHANGED + ADDED 的文件按相对路径逐个复制进去(目标子目录不存在时先 New-Item -ItemType Directory 创建):
New-Item -ItemType Directory -Path ".snapshotsdata 012" -Force | Out-Null
Copy-Item "会员积分系统PRD.md" -Destination ".snapshotsdata 012会员积分系统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:30 | v2.1 | 保存 | 把登录方式从手机号验证码改为扫码 |
| 2026-09-08 14:00 | v2 | 保存(里程碑) | 登录方案定稿 |
| 2026-09-08 13:58 | v1.1 | 回退 | 从 v2.1 回退到 v1.1,回退前现场已存为 v2.2 |
操作类型共四种:保存(AI 自动留痕)、保存(里程碑)(用户主动要求)、回退(说明里注明从哪版回到哪版、现场存为了哪版)、清理(删除旧版本,记录仍保留)。
list(版本历史)
一条命令批量读取全部元数据(mac:cat .snapshots/meta/*.json;win:Get-Content .snapshotsmeta*.json),按 seq 从大到小排列,表格输出(大版本是用户标记的里程碑,小版本是 AI 自动留痕):
| 版本 | 时间 | 改动说明 |
|---|---|---|
| v2.1 | 09-08 14:30 | 调整退货审批流,增加财务节点 |
| v2 | 09-08 14:00 | 里程碑:登录方案定稿 |
| v1.1 | 09-08 10:12 | 新增会员积分需求 |
| v1 | 09-07 18:00 | 初始版本 |
用户只是想看上一版内容而不回退时,直接读取对应快照目录里的文件展示,不改动工作目录。
restore(回退)
触发:用户说"回到 v1.2 / 回到第 X 版 / 回退到 / 撤销刚才的修改"。
流程(顺序不可乱):
- list 展示版本历史,与用户确认目标版本(用户已明确指定版本号时跳过),由目标版本的 name 定位其序号目录(如
v1.2→data/0003/) - 先 save 当前状态(按自动存规则计版本号),desc 固定写:
回退到 {目标name} 前的现场 - 按目标版本类型执行恢复(见下):全量版直接镜像;增量版三步重建
- 汇报:已回退到 {目标name}(时间 + 改动说明),当前目录内容与该版本完全一致
- 上下文对齐(必做):回退只还原文件,对话记忆仍停留在回退前的最新状态——必须明确告知用户这一点,并主动询问:“接下来是基于 {目标name} 开新方向,还是重做刚才回退掉的内容?”用户本轮的回答是后续所有修改的基准;回退后的第一轮修改前必须重新读取文件当前内容,严禁凭回退前的对话记忆直接写入(防止按旧认知覆盖刚恢复的文件)
- 更新操作日志:顶部插入
| {时间} | {目标name} | 回退 | 从 {回退前name} 回退到 {目标name},回退前现场已存为 {现场name} |
全量版恢复(目标目录内无 manifest.json,直接镜像):
# macOS
rsync -a --delete --exclude='.snapshots' ".snapshots/data/0003/" ./# Windows
robocopy ".snapshotsdata 003" "." /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 ".snapshotsdata 003" "." /MIR /XD .snapshots /NJH /NJS /NDL /NFL # ① 先镜像恢复基础全量版
robocopy ".snapshotsdata 007" "." /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 ".snapshotsdata 002" ".snapshotsdata 003" /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)