Unity-Skills快照与Undo深度解析：五类快照、内容寻址存储与workflow_undo_task

Unity-Skills 是一款面向 Unity 的 AI 自动化技能插件，它内置的持久化快照与 Undo 系统让 AI 的每一步改动都可以按任务精确回退。本文带你深度解析它的核心机制：五类分级快照、以 SHA1 哈希命名的内容寻址存储，以及如何用workflow_undo_task一键撤销整个任务。

为什么需要"任务级快照"，而不只是 Ctrl+Z？

Unity 原生 Undo 栈只存在于当前会话中：一旦编辑器重载（Domain Reload）、重启工程，撤销栈就基本失效了。而 AI 代理往往会在一次会话里连续修改场景对象、材质、脚本、工程设置，出问题时需要的不是"退回一步"，而是"把刚才这一整批改动全部回滚"。

Unity-Skills 的 Workflow 模块为此设计了一个"时间机器"：

• 任务（Task）：用workflow_task_start/workflow_task_end包裹一段操作，期间所有被触碰的对象都会自动打快照；
• 会话（Session）：用workflow_session_start/workflow_session_undo把整轮对话的改动打包，支持一次性全部撤销；
• 持久化：历史写入Library/UnitySkills/workflow_history.json（当前schemaVersion为 5），重启编辑器后依然可以撤销。

相关的技能文档可参考 workflow/SKILL.md，它完整列出了每个技能的参数与返回值。

一图看懂：五类快照类型

快照不是"无脑全量备份"，而是按改动性质分成五种类型，由枚举 SnapshotType 定义：

这套"按需存最少数据"的设计既省空间又省时：新建一个物体只需存几个 ID，而真正被删除的大文件才会完整搬进备份仓库。

内容寻址存储：把 SHA1 哈希当文件名的备份仓库

Deleted 和 Modified 类快照的原始字节，存放在一个内容寻址文件仓库中，核心实现是 WorkflowFileStore.cs：

• 位置：Library/UnitySkills/workflow_files/<SHA1>，每个文件 blob 以自己的内容 SHA1 哈希为文件名；
• 自动去重：相同内容只存一份，多个任务删除了相同文件不会占用双倍空间；
• .meta独立寻址：Unity 的.meta伴生文件按自己的内容单独哈希存储，历史中用fileHash/metaFileHash两个引用定位；
• 原子写入：先写.tmp再改名，避免存到一半的损坏文件；
• 完整性校验：恢复前先重算哈希比对，一旦内容对不上文件名，blob 会被隔离为<hash>.corrupt并中止恢复——宁可不还，也不写入坏数据（见 VerifyBlobIntegrity）。

自动清理：备份不会无限膨胀

仓库不会一直膨胀。WorkflowAutoCleanConfig 提供了一组可调的自动清理参数（默认值）：

清理逻辑非常克制：仍被保留历史引用的 blob 绝不删除，10 分钟内刚写入的 blob（可能正属于尚未入史的快照）也会被宽限保护（见 PruneByAgeAndSize）。

workflow_undo_task：如何撤销一个任务

核心撤销入口是workflow_undo_task，实现在 WorkflowSkills.cs。典型工作流：

1. workflow_task_start（带 tag，如"创建 NPC"）→ AI 开始执行一系列操作；
2. workflow_task_end→ 任务连同所有快照落盘保存，返回taskId；
3. workflow_list查看历史，找到目标任务的taskId；
4. workflow_undo_task(taskId)→ 该任务的所有改动被逆序还原，任务进入"已撤销栈"；
5. 反悔了？workflow_redo_task可把它重做回来，workflow_undone_list查看可重做列表。

撤销执行有三个值得注意的细节：

• 逆序执行：快照按操作发生的相反顺序恢复，保证依赖关系正确；
• 失败可重试：中途某个快照恢复失败时，失败及未处理的快照会留在栈上，可再次调用重试；
• 逐条明细：返回TaskUndoResult（total/succeeded/failed/details），AI 能精确知道哪个对象恢复失败、失败原因是什么。

安全边界与已知限制 ⚠️

• 面（Surface）门禁：workflow_undo_task会预先检查目标任务的每个快照，若还原会涉及当前配置排除的类别（如场景 GameObject 或.unity/.mat资产），整次调用会被拒绝并返回SURFACE_EXCLUDED，而不是半撤销；
• scene_save撤销：还原的是磁盘上的.unity文件，若场景正处于打开状态，需要手动 Reload 才能生效；
• 未保存场景中的新物体：其GlobalObjectId跨重启失效，撤销时会在结果中标记为 failed；
• 外部副作用不可回滚：如 Package Manager 操作等引擎外部行为，快照无法覆盖；
• 清空历史是高危操作：workflow_clear_history只删除追踪记录，不会还原已应用的改动，且不可逆，仅在 Bypass 模式或白名单命中时可调用。

快速上手清单 🚀

1. 每轮对话开头调workflow_session_start，结尾调workflow_session_end，获得会话级兜底；
2. 对高危改动额外用workflow_task_start/workflow_task_end包一层，拿到细粒度taskId；
3. 出问题先workflow_list定位任务，再workflow_undo_task精确回退；
4. 想彻底重来前，记住顺序：先 undo，再考虑workflow_clear_history。

延伸阅读

• 快照机制与自动清理文档：workflow/SKILL.md（"Snapshot Mechanism" 一节）
• 模式与门禁说明：docs/OPERATING_MODES_CN.md
• 安装与配置指南：docs/SETUP_GUIDE_CN.md
• 数据模型源码：WorkflowModels.cs、WorkflowManager.cs

理解了"五类快照 + 内容寻址 + 任务级 Undo"这套组合，你就掌握了 Unity-Skills 让 AI 改工程时"敢放手、能回头"的核心底气。