scenario-unreal-pipeline-automation

Unreal 流水线自动化（流水线与工具 TD）

Unreal 中的专业流水线工作，是将策略作为数据并提供证明：导入策略是带版本的流水线资源，名称取自计划，每条重要规则都由验证器实现，同时也用于保护人工编辑；构建只有在通过致命错误验证并启动后才算完成。批量工作以无头模式运行；任何视觉相关内容都要生成截图，并由真人实际查看。如果这里提到的同级技能不在你可用的技能中，请让用户安装 （npx skills add scenario-labs/skills --skill <name>）；若无人值守，则根据工具模式继续操作，并标明这一缺口。

必需背景： scenario-unreal-expert（通道、审查流程、5.8 陷阱）。

状态（2026-09-24）： 这里的所有 Unreal 调用尚未在 Unreal 中运行；scripts/ue_pipeline.py 的纯逻辑层以及两个任务已离线运行（单元测试，以及针对模拟 unreal 的控制流测试）。安装 5.8 后的第一步： tests/code/unreal-pipeline-automation/in_engine/run_in_unreal.py

立场（专家增量）

• 导入策略是传入的资源，而不是对话框记忆；它会随资源保留。 脚本化导入使用管线默认值，而非对话框上次记住的设置（Interchange PM，Oq6KbrqkGnw [00:39:28]；Jamie Dale，0guOMTiwmhk [01:26:38]）：将通用资源管线复制到项目中，设置每个选项，并通过 override_pipelines 传入。堆栈顺序就是执行顺序：位于默认管线之上的调整管线看不到工厂节点 [00:20:22]。按照 Factory Dependencies 在工厂节点级别进行筛选，避免创建孤立材质 [00:31:33]；如果堆栈中留有 Graph Inspector，它会在批处理过程中弹出 [00:40:00]。资源会保留其堆栈，重新导入时会复用该堆栈（Interchange 文档），因此策略变更只有在重新导入时传入新预设（plan_imports(..., policy=)），才会应用到现有资源。
• 名称来自计划，而非导入器。 Interchange 会忽略 AssetImportTask.destination_name（5.8 API 参考）。将每个文件暂存到目标名称下，仅在必要时重命名：重命名会留下重定向器（命名文档），而 Zen 加载器会忽略核心重定向。重命名为已有资源的名称会失败，这也是重复运行留下重复资源的原因：应改为重新导入（I03）。不要拖放：其他工具依赖路径（Bardoux，MjjkWH0eT3U [00:09:14]）。
• 根据适用条件启用 Nanite，而非根据三角形数量。 目标平台支持 Nanite 时，不透明或遮罩静态网格体（包括低多边形网格体）都启用 Nanite：非 Nanite 几何体“渲染到 VSM 中的成本高得多”（VSM 文档）。半透明材质（Nanite 会绘制默认材质）、变形目标和不支持 Nanite 的目标平台则关闭 Nanite；“并非所有内容都能使用 Nanite”（Oztalay，S2olUc9zcB8 [00:34:33]）。为每个 Nanite 网格体设置回退选项（DxBKmQ-0kfw [00:37:15]）；仍需使用简单碰撞。
• 验证应在创建时通过代码执行，而且红色必须代表新增问题。 大约 30% 至 40% 的错误都能追溯到资源验证器可捕获的问题（Fray，KuIWCzujtag [00:35:40]）。保持 CanValidateAsset 轻量 [00:31:47]，并关注 5.8 中按验证器统计的 Cook 耗时（DataValidation.ReportCookValidationStats）；将遗留错误加入允许列表 [00:38:07]；先在测试样例上确认每项检查都会失败 [01:46:04]。Python 验证器每次会话都要注册，-run=DataValidation 只运行 C++ 规则，而 Cook 验证若未指定 -ValidationErrorsAreFatal，会将错误转为警告。
• 批量操作用无头模式，操作已加载内容时使用已打开的编辑器；不要相信退出码。 命令行程序不会加载关卡（Python 文档），而资源注册表可能仍在扫描：查询前调用 wait_for_completion()（5.8 批处理示例）。除非指定 -ScriptErrorsAreFatal（5.5），否则 Python 执行失败只会记录错误：应以任务自身的结果行（P.job_verdict）为准。编辑器会对已加载的资源保持写入锁（Jamie Dale [01:17:18]）：通过 MCP 或 Python 远程执行在编辑器内运行。set_editor_property 的行为与 Details 面板相同；直接写入属性不会重建任何内容 [00:21:25]。在 Perforce 下，5.8 的 PythonScript 命令行程序会先启用源代码管理；检出将要保存的内容，若检出失败则停止（Bardoux [00:55:27]）。导入操作无法撤销：先创建快照。
• 先列出，再确认，再执行；每个网格体只处理一遍。 打印解析后的目标，然后运行（Sam Deiter，k0tgmrBuIJc [00:52:23]）。一次处理完 Nanite、LOD 和碰撞，并且每个区块只保存一次。LOD 组本身可能不会生成 LOD [待验证]：设置后检查数量，若不足则显式构建 LOD 链，并确认屏幕尺寸逐级减小（L02）。单个文件出错不能中断整个批处理。
• 构建应是可复现的命令行操作，并通过启动验证。 通过 Project Launcher 配置文件生成一次 BuildCookRun 命令行，并将自己的命令与之比对（UAT 文档；P.buildcookrun_diff）。Cook 不会暂存，-skipcook 并不等于省略 -cook（Josh Adams，uxdEt9XXKb8 [00:19:14]、[00:20:20]）；无论是否有人在 Xcode 中编辑，Xcode 都会组装 .app [00:03:33]（内容仅含资源的项目是否需要完整 Xcode 是一项有待验证的推断）。本地和 CI 使用相同命令（Hamilton，3ftOkc-cA7U [00:25:15]）；然后启动项目（Gauntlet UE.BootTest），并持续观察（Ari，102O0FOEzNY [00:39:07]）。性能数据应看作趋势，而非门槛（Fray [01:29:38]）。

首先确定

输入	变更	简报未明确说明时的默认值
任务	阶段	新批次：全部；源文件有变更：2 到 10，使用 previous=（P11）；采用规则的现有项目：6，使用允许列表；仅构建：10；美术师按钮：P12
源文件和附属文件	单位、法线	Maya summary.json 和 <file>.settings.json，否则扫描；法线使用 DirectX，除非附属文件注明 opengl
目标平台	Nanite、LOD	PC 和主机；这台 Mac（M5 Max）达到 Nanite 和 VSM 的 M2 门槛
命名	验证器前缀	Epic 的表格（SM_、T_、MI_）；仅当项目使用 Allar 时才采用 Allar
布局	目标位置	/Game/<Project>/Art/<Kind>/<Category>/<Base>，不设类型文件夹（Allar 2.6）
主材质	实例、顶点颜色	来自 scenario-unreal-materials；无：不创建实例，并报告
资产类	碰撞、LOD	附属文件中的 asset_class，否则使用类别映射，否则按大小（150 cm [已添加]）
编辑器是否打开？	通道	是：在编辑器内；否：无头模式
源代码管理	签出	Perforce：require_checkout；重新保存时使用 -autocheckout
构建	平台、配置	Mac、Development，归档放在项目外

工作流

1. 预检。 ue_env.preflight()（芯片、Xcode 窗口）、P.project_path_problems、插件 （Python Editor Script、Editor Scripting Utilities、Interchange、Data Validation、 PythonAutomationTest）、编辑器是否正打开项目、p4 opened。门槛：没有错误行；已选择通道（P0）。

2. 规划并暂存，离线进行。 P.scan_sources、P.read_dcc_manifest、 P.plan_imports(..., previous=manifest, policy="PL_Props@3")、P.stage_plan。门槛：项目数加上 拒绝数等于源文件数；已读取 D01 至 D07；源文件逐字节一致（P1）。

3. 导入策略。 Job describe，然后通过路由设置 preset：post_import（默认：关闭材质，导入后使用显式参数映射创建实例） 或 interchange_mi（Material Import = Import as Material Instance，Parent Material = 主材质；仅填充 Interchange 按名称识别的参数）。除非主材质读取顶点颜色，否则 Vertex Color Import Option 设为 Ignore；Lumen 下关闭 Generate Lightmap UVs。门槛：failed 为空；P.pipeline_stack_problems(stack) 无问题（P2）。

4. 试运行。 make_fixtures.py 加上 5 到 10 个真实文件。门槛：每个损坏的 fixture 都显示其问题 ID；已知每个文件所需秒数。

5. 导入。 无头模式：通过 ue_run.run_python 执行 Job import；编辑器已打开：通过 MCP 或 ue_remote.PythonRemote 执行 P.run_import_plan；P3b 中的引擎调用。每批 25 个， 执行 unreal.collect_garbage()。门槛：每个文件都有记录，P.job_verdict 退出码为 0（P3、P4）。

   步骤	无头模式	需要可渲染的编辑器
   导入、实例、Nanite、碰撞、LOD、验证器、报告	是（写入锁：使用已打开的编辑器）	否
   截图、碰撞和 Nanite 视图	否	是（mode="latent"）
   主材质图表、Blueprint 工作流、Graph Inspector	否	scenario-unreal-materials 或人工

6. 验证。 报告包含我们的问题、engine_validate 和 ue_audit；C++ 规则使用 -run=DataValidation；P.new_issues(records, allow) 决定 CI 是否通过。门槛：新增错误数为零；已知验证器耗时 （P5）。

7. 检查外观。 ue_contact_sheet_job.py（P7 中展示了原始的 latent 截图循环），然后执行 ue_review.review_images；打开联系表；检查一个样本的碰撞视图。门槛：没有空白画面；每个标记的资产都有 备注。

8. 重定向器和签入。 若 redirectors_found（来自注册表）大于 0： 执行 P.resave_command(uproject, autocheckout=...)，关闭编辑器。门槛：零（P8）。

9. 测试。 通过 P.automation_command 运行 Python 测试（test_*.py），使用 P.parse_automation_report 读取；层级为 push、build、weekend（Fray [01:31:46]）。门槛：全部通过；每个 新测试都至少见过一次失败（P6）。

10. Cook、打包、启动。 使用 P.cook_command（仅 cook）或 package_command(..., incremental=True)（-cookincremental、Beta、Zen）迭代内容；发布： P.zen_ci_patch、P.package_command、P.buildcookrun_problems、与启动器版本对比的 P.buildcookrun_diff、 ue_run.run_uat、P.parse_uat_log、P.gauntlet_command。门槛：退出码为 0， 已归档 .app，BootTest 通过（P9）。

数值

数值	对应项	来源
1 uu = 1 cm，FBX 2020.2	DCC 导出	Epic；scenario-maya-pipeline-scripting
UCX_ UBX_ UCP_ USP_ + 网格名称	DCC 碰撞	Interchange 文档
最大 8192，UI 除外均为 2 的幂	纹理	Allar 7.1，7.3
每项低于 1 s	Epic 的 Smoke 标志	自动化文档
等待 0.5 到 1 s	Smoke 检查	KuIWCzujtag [01:03:07]
预期 3 s，限制 4 s	功能测试时限	3ftOkc-cA7U [00:26:46]
20 到 30 min；约 60 min	推送后留守时间	Ari [00:39:07]；Fray [01:56:41]
26.0 min，推荐 26.1.1，26.4 不兼容	适用于 5.8 的 Xcode	macOS 文档（此处为 26.6：未列出）
每块 25 个文件；小型道具 150 cm	保存和 GC；类别拆分	[added]
每类 3 或 4 个 LOD；逐级减半链	最低 LOD 数；显式回退	[added] 项目默认值

质量门槛

可衡量： 项目数加上拒绝数等于来源数；summary["ok"]；没有新增错误；已注册验证器且 engine_validation.ok；ue_audit 为 pass；redirectors_found 为空；DataValidation 无问题；自动化 failed 为 0；使用 -ValidationErrorsAreFatal 执行 cook；每个作业的 P.job_verdict 退出码为 0；已审查启动器差异；UAT 退出码为 0；.app 存在；BootTest 通过。评分标准： references/critique.md。

视觉： 联系表（与人形模型对比比例、枢轴、法线绿色通道、纹理槽、使用 r.ForceLOD 查看 LOD 跳变）、样例的碰撞视图、Nanite 可视化，以及在 scenario-unreal-lighting-rendering 的灯光装置下进行外观开发。

常见错误

错误	表现	修复方法
导入脚本时未显式指定管线	与对话框中的运行结果不同	在 override_pipelines 中预设
更改了预设，却未重新导入资源	旧资源仍使用旧设置	在计划中设置 policy=：使用该预设重新导入
再次导入，而不是重新导入	计划中的资源旁出现重复资源	使用 previous= 清单；I03 会阻止此操作
在 Interchange 下设置 destination_name	资源以文件名命名	使用目标名称进行暂存
将调整管线放在默认管线上方	更改会悄无声息地丢失	将其放在默认管线之后
导入后删除不需要的网格	留下孤立材质	禁用工厂节点及其依赖项
根据三角形数量启用 Nanite，或对半透明内容启用 Nanite	阴影开销高；材质使用默认设置	使用 P.nanite_decision
Python 验证器从未运行	CI 显示通过，编辑器中无提示	在 init_unreal.py 和每个作业中使用 add_validator；名称以 k2_ 开头
验证器路径未标记通过或失败	显示“未检查”	通过检查时设置 asset_passes
信任命令行工具的退出代码	运行显示通过，但作业已崩溃	检查结果行、-ScriptErrorsAreFatal 和 P.job_verdict
无头启动时查询注册表	列表中缺少资源	先调用 wait_for_completion()
使用 EditorAssetLibrary、EditorStaticMeshLibrary、ScriptingCollisionShapeType	出现弃用警告、类型错误	使用子系统和 ScriptCollisionShapeType
设置了 LOD 组，却从未统计 LOD	报告中只有一个 LOD	先统计，再调用 set_lods
编辑器打开时保存	文件被锁定	使用编辑器内通道
用一个循环处理数百个文件	内存不断攀升	分块处理并调用 collect_garbage；数千个文件使用批处理器
使用 Automation RunTests；截图时使用 -nullrhi	未运行任何测试；图像全黑	使用 Automation RunTest；使用带渲染功能的编辑器
手动输入 BuildCookRun；首次构建使用 Shipping	缺少 -stage 或 -package，没有应用；没有日志	使用启动器命令行、P.buildcookrun_problems；先构建 Development

交接

接收： 来自 scenario-maya-pipeline-scripting 的 FBX（每个资产一个，单位为 cm）、UCX_<mesh>_NN、 <file>.settings.json、含 sha1 的 summary.json；来自 scenario-zbrush-retopology-export 的 OBJ（单位为 cm）、 脚部位于 0 的模型、贴图；来自 Blender 的 FBX 或 glTF（使用 DirectX 法线或 opengl 标志） （scenario-blender-uv-baking）；来自 scenario-unreal-materials 的主材质路径、参数映射、主材质是否读取顶点颜色；来自 scenario-unreal-lighting-rendering 的外观开发关卡。

交付： 资产以及 report.json、report.csv、manifest.json（包含每个来源的 sha1 和策略） 和未验证列表。骨骼类项目交给 scenario-unreal-animation，M04 缺失项交给 scenario-unreal-materials，道具交给 scenario-unreal-world-building。问题按 ID 反馈（D01、D02、 S01 反馈给 scenario-maya-pipeline-scripting；T01 反馈给贴图制作人员）。构建产物交给 QA 和 scenario-unreal-performance，附上归档路径、UAT 结论、BootTest 结果和变更列表。

UE 5.8 说明

• Interchange 负责处理 FBX（自 5.5 起用于生产）；5.8 重命名了对话框选项，新增了 uFBX （实验性），并使 USD 资产导入达到生产就绪状态。InterchangeManager.import_asset 和 reimport_asset 会返回对象或 None（5.8 API）。
• AssetImportTask.result 已弃用（改用 get_objects()）；验证器重写函数为 k2_can_validate_asset 和 k2_validate_loaded_asset；create_asset 新增了 overwrite_existing。
• 批处理器：BatchProcessLibrary.run_batch；从 init_unreal.py 导入的脚本应使用 __main__ 保护（避免 fork bomb）。
• 默认启用 Zen 烘焙输出存储：CI 使用 LimitProcessLifetime=false；编辑器内烘焙将在 5.9 中移除。
• Remote Control 默认会阻止远程 UFUNCTION 调用：通过 Python 远程执行或 MCP 触发导入。
• SupportedClasses 为空的操作工具无法通过验证。Interchange 页面仍将 FBX cvars 显示为“Experimental”：安装时读取这些选项（作业 flags）。
• Python 3.11.8。

参考资料

• references/procedures.md：P0 至 P14 及 P3b（原始引擎调用）， 每项均附测试路径和状态。
• references/expert-notes.md：按来源整理的判断、分歧和 决定条件。
• references/critique.md：运行、验证器、测试和构建的评估标准。
• references/gui-paths.md：相同流程的菜单路径。
• references/sources.md：来源、凭据、时间戳、修订 历史。
• scripts/ue_pipeline.py、scripts/ue_pipeline_job.py、 scripts/ue_contact_sheet_job.py。