文档版本快照 (doc-snapshot)

文档版本快照 (doc-snapshot) 是什么

在没有 Git 的文档目录中建立 .snapshots 版本库，对每轮 AI 修改做自动留痕，并支持里程碑、历史、比较和恢复。

适用场景

适合 Word、Markdown、策划文档、原型和混合素材项目的修改前备份与错误回退。

核心能力与工作机制

清单定义不可变数据、独立元数据、追加日志、全量/增量阈值、跨 macOS/Windows 命令、三步增量恢复和依赖保护。

执行流程

识别工作目录和排除项，修改前比较最近基础版；小变化保存增量，大变化保存全量，写 meta 与操作日志；回退前保存现场并按版本类型恢复。

输入与输出

需要项目目录、版本说明、是否里程碑、排除目录和可选目标版本。输出 .snapshots/data、meta、操作日志、版本列表、差异报告或恢复后的工作目录。

依赖、账号与权限

跨 macOS/Windows 零额外依赖，使用系统文件命令和哈希工具；需要项目读写权限。

副作用、限制与风险

镜像恢复会删除目标端多余文件，错误基础版会导致增量不完整；快照可能复制敏感和大文件。会复制、创建和在用户明确清理时删除快照；回退会重写当前工作目录。

不适用边界

未确认目标和路径时不得执行回退或清理，不能删除仍被增量版本依赖的基础全量版。

失败处理与验收

恢复异常先停止并以哈希为准检查缓存差异；增量必须从基础全量重建，绝不直接镜像增量目录。对关键文件做哈希和清单对比，检查日志、meta、deleted 清单和恢复后目录完整性。

适合谁使用

适合频繁让 AI 修改文档、但不使用 Git 的个人和团队。

来源、版本与许可

本条目依据 SkillHub 热门榜、发布者详情和版本 1.0.0 的完整 SKILL.md 整理，核验日期为 2026 年 9 月 21 日。完整 SKILL.md 未声明许可证，公开可下载不代表可以任意复制、修改或再分发。 SkillHub 当前两套安全扫描状态为 benign、benign；该状态只是平台信号，不能替代对脚本、凭据、网络请求、数据外送与后续版本的人工审查。

常见问题

1. 文档版本快照 (doc-snapshot) 主要解决什么问题？

在没有 Git 的文档目录中建立 .snapshots 版本库，对每轮 AI 修改做自动留痕，并支持里程碑、历史、比较和恢复。适合 Word、Markdown、策划文档、原型和混合素材项目的修改前备份与错误回退。是否采用它，应以实际任务边界和可核验材料为准，不要因为榜单热度而跳过来源审查。

2. 开始前需要准备什么？

需要项目目录、版本说明、是否里程碑、排除目录和可选目标版本。准备阶段不要代替用户猜测关键事实；缺少会改变路线、费用或权限的输入时，应先补齐再执行。

3. 它怎样完成任务并交付结果？

识别工作目录和排除项，修改前比较最近基础版；小变化保存增量，大变化保存全量，写 meta 与操作日志；回退前保存现场并按版本类型恢复。每个阶段都要保留输入、决策、输出和检查点，不能把计划、预览或排队状态描述成最终交付。

4. 需要哪些工具、账号或权限？

跨 macOS/Windows 零额外依赖，使用系统文件命令和哈希工具；需要项目读写权限。凭据应放在安全环境中，并按最小权限授权；账号、网络或本地依赖不满足时应明确停止条件。

5. 它会产生哪些外部操作或副作用？

会复制、创建和在用户明确清理时删除快照；回退会重写当前工作目录。涉及外部写入、上传、发送、付费或持久配置时，应在实际动作前说明影响范围并取得相应确认。

6. 哪些情况不适合使用？

未确认目标和路径时不得执行回退或清理，不能删除仍被增量版本依赖的基础全量版。超出来源明确能力、专业资质或授权范围时，应切换到更合适的工具或交给专业人员处理。

7. 失败或结果异常时怎样恢复？

恢复异常先停止并以哈希为准检查缓存差异；增量必须从基础全量重建，绝不直接镜像增量目录。恢复时优先查询已有任务、日志或备份，避免无上限重试、重复扣费、重复发送或覆盖唯一原件。

8. 如何验收结果并控制风险？

对关键文件做哈希和清单对比，检查日志、meta、deleted 清单和恢复后目录完整性。验收应基于真实文件、页面、任务终态或权威来源，并把未能实际检查的部分明确标记出来。