一个脚本可以在几秒内改完一批资产，但速度并不能说明它已经是可靠的生产工具。目标选错、执行中断、资产在预览后发生变化，或者用户重复点击，都可能把节省的时间变成排错和返工。
生产工具需要设计的是完整操作过程：如何确认输入，如何展示计划，如何处理执行中的变化，以及失败后如何恢复。本文以“批量调整资产导入设置”为例，讨论如何把一次性脚本组织成可解释、可恢复的工作流程。
本文为工具设计方法。文中的计划单是自定义格式示例，并非已接入某个 DCC 或引擎的工具；不声称已经产生项目效率收益。
01 / 从使用场景定义工具边界
先明确用户要解决什么：是把已经确认错误的粗糙度纹理改成线性数据，还是自动判断整个工程的纹理语义？前者是有约束的批处理，后者包含分类判断，两者的风险和验收完全不同。
第一版工具适合选择一个输入可识别、输出可检查的窄任务。例如读取选中资产的元数据，根据明确的角色标记检查导入选项，生成修改计划。仅凭文件名包含 “mask” 就直接修改整个目录，容易把命名不一致变成批量错误。
| 边界 | 需要定义 | 不明确时的行为 |
|---|---|---|
| 输入范围 | 用户选择集、目录还是依赖集合 | 不隐式扩大操作范围 |
| 资产语义 | 哪些数据证明它是线性遮罩或颜色纹理 | 标为需人工确认，不自动猜测 |
| 允许修改 | 具体字段及其合法值 | 不顺便修复其他设置 |
| 冲突条件 | 只读、被修改、正在导入或不支持的版本 | 报告原因并跳过或终止 |
02 / 将计划与执行分开
计划单至少应包含资产稳定标识、待修改字段、预期旧值、目标值、规则版本与输入修订标识。工具界面展示这些内容，用户才能判断“是否改对了对象”。
{
"plan_version": 1,
"rule_id": "linear-mask-import-v1",
"asset_id": "example/roughness_texture",
"expected_revision": "revision-from-scan",
"changes": [
{"field": "srgb", "before": true, "after": false}
],
"reason": "Asset role explicitly declares linear scalar data"
}这里的资产和修订值均为示意，执行器应读取实际值。计划单不应依赖任意可执行表达式描述操作；使用明确的字段和有限的动作类型，方便校验与审计。JSON 能承载这种结构，但格式解析成功不代表字段语义正确，还需要应用层验证。[1]
03 / 预览通过，不代表执行时仍然成立
扫描与执行之间，其他人或其他工具可能修改资产。因此执行前需要重新检查：目标是否仍存在，当前值是否与计划中的旧值一致，输入修订是否变化。发现冲突时，重新生成计划或由用户处理，而不是覆盖新状态。
文件工具可以在适用场景中使用内容摘要识别变化；Python 的 hashlib 提供相关算法。[2]但摘要只能表明所读取字节的关系，不证明资产语义正确，也不会自动锁住文件。检查完成后到写入前仍可能发生变化，严格并发控制需要锁、事务或宿主提供的原子条件更新。
DCC 和引擎资产还可能包含内存状态、依赖文件和导入结果。只对磁盘上的一个源文件算摘要，并不足以代表完整资产修订。应优先使用宿主的资产标识与版本机制，并明确哪些依赖参与冲突判断。
04 / 重复执行应该产生可预期的结果
对于“把 sRGB 设为 false”这样的状态设置，重复执行可以保持目标状态；对于“把数值乘以 0.5”，重复执行则会持续改变结果。工具需要区分这两类操作。
可以把目标表达成 目标值 = 规则(原始输入, 规则版本)，并记录迁移版本，避免把已经迁移的结果再次当作原始输入。结果已符合目标时记录为“无需修改”，而不是再触发一遍昂贵的导入。
| 操作 | 重复执行风险 | 建议设计 |
|---|---|---|
| 设置导入字段 | 额外导入、产生无效变更记录 | 比较当前与目标，未变化则跳过 |
| 批量重命名 | 再次添加前缀、名称冲突 | 基于稳定身份生成目标名，预检整个映射 |
| 数据迁移 | 重复变换破坏数据 | 明确源版本、目标版本和迁移记录 |
| 生成派生资产 | 覆盖手工修改或重复生成 | 区分生成结果与可编辑源，记录输入和生成器版本 |
05 / 把失败当作正常路径设计
批处理结果不能只有“成功”与“失败”两个状态。至少需要区分：待执行、已跳过、执行中、已验证、发生冲突、执行失败与恢复失败。真正成功应当是写入后检查满足目标，而不是 API 调用没有抛异常。
对于文件输出，先写临时文件，再通过原子替换提交单个目标，能降低读到半写文件的风险。Python 的 os.replace 文档说明了替换行为以及跨文件系统可能失败的限制。[3]但这不等于整个批次有事务能力，也不等于断电后数据一定持久化。多文件资产需要另外设计提交与恢复策略。
引擎资源应通过宿主支持的 API 修改和保存，而不是绕过资产系统直接替换文件。宿主的撤销系统也有范围限制：它未必涵盖外部文件、导入任务和已经发送到其他服务的操作。
取消与回滚不是同一件事
取消通常意味着停止安排后续操作，当前不可中断步骤可能仍需完成。回滚则意味着恢复已经执行的变更，需要前值、备份或可逆操作。界面应准确显示“已停止，已修改 12 项，剩余 8 项未执行”，不能在只停下队列时提示“全部恢复”。
回滚本身也要检查冲突。如果工具执行之后又有人修改了资产，盲目写回旧值可能覆盖新工作。恢复时应验证当前状态确实仍是本次操作产生的结果，否则转人工处理。
06 / 界面优先解释范围与结果
用户最需要的不是更多开关，而是知道工具准备做什么、为什么这么做、哪些对象需要处理，以及失败后下一步是什么。推荐将界面组织为目标范围、检查结果、修改预览和执行报告四部分。
- 预览：显示路径或稳定标识、修改前后值、触发规则与风险提示；支持按问题筛选。
- 执行：防止重复提交，显示已完成数量与当前阶段；无法估计剩余时间时不编造倒计时。
- 报告：区分已验证、无需修改、冲突与失败，提供可操作的原因和重试入口。
- 恢复：只对仍满足恢复条件的对象提供操作，保留其他对象的失败信息。
建议将规则判断与宿主 API 分开。规则层输入标准化元数据、输出问题与计划；适配层负责读取和提交资产；界面只呈现结果。这样规则可以用固定数据测试，也更容易扩展到另一个 DCC，而不用把所有逻辑重写进窗口回调。
07 / 用失败场景验收工具
第一轮验收就应覆盖不理想的输入，尤其是会造成部分完成的情况。下面是可用于实施的验收矩阵，不是已经通过的生产测试报告。
| 场景 | 预期行为 |
|---|---|
| 空选择或全部合规 | 清楚说明无需修改，零写入 |
| 目标名称冲突 | 执行前报告，不覆盖其他资产 |
| 预览后资产变更 | 重新检查，标记冲突 |
| 批处理中途写入失败 | 准确保留已完成和未完成列表，不报整批成功 |
| 执行中取消 | 说明取消边界，保留可继续或可恢复的记录 |
| 再次运行相同任务 | 已达到目标的资产不重复迁移 |
| 执行后手工修改，再尝试恢复 | 识别冲突，避免覆盖后续工作 |
效率评估也要包含预览、人工确认、导入等待、失败处理和维护成本。只计算脚本执行时间，容易忽略工具真正占用人的环节。先记录人工流程与工具流程的完整耗时，再讨论节省程度。
08 / 从一个窄问题开始交付
一个有效的第一版，可以只支持一种资产、一条规则和一个宿主。但它应具备清晰范围、修改预览、冲突检查、结果验证与失败报告。复杂的规则库、任务调度和跨软件统一界面，可以在重复需求真正出现后再扩展。
生产工具的专业性，体现在它是否让用户放心地理解并控制修改。自动化只有在输入明确、结果可验证、失败可处理时，才会形成可持续的生产能力。
参考资料
- Python — json：序列化与解析行为。
- Python — hashlib：内容摘要接口。
- Python — os.replace：文件替换及适用限制。
资料核对：2026-10-18。本文为工具架构方法，未声明实现事务系统或通过宿主集成测试。