自动关联目录：写入回滚：文件快照不能替代跨编辑器事务

核心判断：写前快照只能恢复被识别出的文件内容；AI 同时修改多文件、UE 对象、资产索引和外部服务时，必须提交结构化 ChangeSet，而不是事后猜哪些副作用要撤销。

一、业务冲突

模型一轮可能并行改多个文件，随后运行脚本、触发编辑器导入或刷新资产索引。中途失败时，保留一半修改会让工程不可运行；简单“把文件写回去”又可能覆盖用户在执行期间的新修改，或漏掉新建文件、生成目录和 UE 内存状态。

二、实际实现

实际控制器按只读、文件写入、副作用和独占工具分阶段执行。目标路径不同的文件写可并行，相同路径写串行；每个写阶段前读取旧内容，阶段内任一写失败就按快照恢复。这个机制为普通文本修改提供了成本较低的批次补偿。

新一代会话运行时还在副作用调用前持久化 Dispatch Checkpoint，并以会话、工具、规范目标和参数摘要生成幂等身份。终态缺失时记录 Unknown Outcome，禁止把“没收到结果”直接当成“没有发生”。

三、值得保留

同路径冲突串行化、阶段级快照和副作用前持久化都值得保留。它们分别解决并发覆盖、局部失败和结果未知，明显优于让模型自己记住修改过哪些文件。

四、结构性缺陷

当前快照路径依赖少量参数名推断；多文件 Patch 无法得到完整目标集，可能没有可恢复快照。原本不存在的文件在回滚时被写成空文件，而不是恢复为“不存在”；恢复过程再次经过写入 Hook，还可能得到与原始字节不同的内容。文件回滚也覆盖不了 UE Transaction、资产导入、生成文件、进程启动和远端提交，更没有用基线摘要防止覆盖并发用户修改。

五、目标设计

模型先生成 Schema 化 ChangeSet，执行器再准备和提交：

struct ChangeSet {
    ChangeId id;
    vector<Mutation> mutations;       // FilePatch, EditorCommand, AssetImport
    vector<Precondition> preconditions; // BaseHash, ObjectRevision, Schema
    VerificationPlan verification;
    CompensationPlan compensation;
};

PreparedChange Prepare(ChangeSet c) {
    ValidateSchema(c);
    FreezeAllTargets(c);
    ApplyToStagingWorkspace(c);
    return RunPreCommitChecks(c);
}

Commit(prepared, ExpectedRevisions);  // 文件指针与 UE Transaction 一起受控提交

外部不可回滚动作进入 Effect Ledger，使用幂等键和对账，不假装能由文件快照撤销。

六、取舍与验证

结构化输出可以约束 ChangeSet 的字段形状，但官方文档也明确说明，符合 Schema 的内容仍可能在语义上错误，因此基线、路径、引用和领域约束必须由确定性代码复核。Structured Outputs

测试应覆盖新建文件、删除、重命名、多文件 Patch、写入 Hook、同路径并发编辑、UE 对象事务、导入失败、外部结果未知和回滚自身失败。验收不只比较文本，还要确认文件存在性、权限、资产引用、Dirty Revision、编辑器状态与制品摘要全部回到同一基线。