scenario-maya-pipeline-scripting

Maya 流水线脚本（流水线 TD）

专业的流水线工作讲究契约与验证：每个离开 Maya 的文件都必须经过自动生成名称、明确的导出设置和重新导入检查；任何批处理都不能让一个 Maya 进程处理两百个文件。流水线 TD 绝不手动输入可自动生成的内容，绝不信任默认值，并通过回读输出进行验证。如果这里提到的某个同级技能不在你的可用技能中，请让用户安装（npx skills add scenario-labs/skills --skill <name>）；若在无人值守的情况下继续，请依据工具架构进行操作并标记这一缺口。

必备背景： scenario-maya-expert（执行通道、审核循环、2027 版本陷阱）。

状态（2026-09-24）： 这里的每次 Maya 调用都尚未在 Maya 中运行（尚未安装）。 scripts/mx_pipeline.py 已离线运行，其 Maya 层使用了伪对象。安装 Maya 后的第一步：tests/code/maya-pipeline-scripting/run_all.sh

工作准则（专业要点）

• 绝不手动输入可自动生成的内容（Guignolle、Borderlands、lfWkJrkhd2U [00:04:58]）：名称、命名空间、路径和片段范围都来自清单；在执行操作的位置进行验证（已批准镜头警告、场景拆解、发布差异绿、蓝、红 [00:22:11] 至 [00:24:57]）。
• 回读输出，证明结果正确（dcc-mcp 的“用数字而非说法”标准；Maya Help 的测试：FBX 重新导入后，法线、缩放、轴向和长度均保持一致）：在干净场景中重新导入并比较网格、三角形、关节、每个网格的边界、法线方向、单位和向上轴；使用 FBXRead 读取动画；使用 pxr 重新打开 USD；对源文件进行哈希处理。每个文件使用一个 mayapy 进程：FBX 设置和 optionVars 会在 file(new=True) 后保留。
• 绝不盲目运行（chadrik、maya-mcp-server：没有 stdout 和 stderr，“Agent 就是盲目的”；FBX 文档：在批处理模式中，日志是问题文件唯一的反馈）：保持 FBXExportGenerateLog 启用，并读取每个子进程的日志；子进程使用 MAYA_DISABLE_ADP=1 运行，且将 Maya 的 stderr 设为 warning（调试时使用 maya_log="all"）；每次桥接调用后读取 stdout、stderr 和 maya_messages。
• FBX 是全局状态（Maya 2027 Help，FBX MEL 命令）：推送设置、重置、设置所有选项、清除动画累积器、查询并回读设置，并在文件旁记录日志，最后弹出设置。Bake Start 和 End 绝不存储在预设中。只有全三角形网格才能导出切线；非正交矩阵会被丢弃。使用受控边在 Maya 中进行三角化（Epic）。
• 导出默认值暗藏陷阱（maya-usd readme）：frameRange [1, 1]、defaultMeshScheme catmullClark（不含法线）、关闭骨架、保留命名空间。传入每个标志，然后使用 pxr 重新打开。
• 规模扩大时，结构胜过硬件（Markowski 和 Hübschmann、RISE、8UIW-g1_heg）：使用值片段而非全范围缓存 [00:37:03]；静音自己的图层以及所有优先级更高的图层 [00:26:19]；固定版本，并在 assetInfo 中记录 [00:23:01]。
• 引用编辑按名称和 DAG 路径重放（Maya 2027 Help）：绝不重命名或重构已发布的子文件；在修复前以及每次版本替换后，检查引用状态（未加载、缺失、编辑失败）。镜头引用资产；引擎使用烘焙后的导出文件。
• 优化前先分析，提速前先保证正确（Roselle，rhtERzmAoUM [00:04:14]；Using Parallel Maya 2027）：DG、Serial 和 Parallel 必须先得出一致结果；无头模式下的数值衡量的是求值，而非绘制。使用 Python 构建和导出；使用原生节点进行求值（Fragapane，_0mb4wIZi80 [00:55:10]）。

首先确定

输入	变更	简述未说明时的默认值
目标	预设、检查、文件布局	Unreal 5、FBX 2020.2、每个资产一个文件、每个文件一个片段
资产类型	静态、骨骼、动画、缓存、USD 图层	绑定场景使用骨骼类型，其他情况使用静态类型
场景约定	单位、向上轴、命名正则表达式	cm、Y-up、mx_validate 默认值；如果工作室没有约定，则使用 _geo 后缀（FlippedNormals）
帧速率	E27、片段长度	使用简述中指定的引擎或项目帧速率；否则报告实际帧速率，绝不重新采样
允许的修复	未经询问可更改的内容	history, smooth_preview, unknown_dead, namespaces；不得更改权重、拓扑或法线
影响数上限	限制值或报告	Unity：4（Unity 手册）；Unreal：报告直方图
事实来源	名称、版本、范围	在输出旁放置一份 JSON 清单
运行规模	工作进程、隔离	先进行 5 个文件的试运行，然后使用 workers=1 或 2，并进行进程隔离

工作流

1. 预检、清点、测试样例。 P.preflight(out, scenes)：检查 mayapy、本地主机及主机名解析（macOS 批量渲染可能会因此卡住）、磁盘和可读取的场景。P.find_scenes(root)。每条规则准备一个只破坏一项内容的小型场景（test_engine_checks.py）；在 5 个真实文件上运行完整链路。GATE：预检通过；每个测试样例都能被捕获；已知每个文件所需时间。
2. 批处理。 P.batch(scenes, job, out, plugins=("fbx",), timeout=900)：每个场景启动一个 mx_run 子进程，关闭脚本节点，并在环境变量中设置 MX_PIPELINE_OUT/STEM/SOURCE 和每个子进程的 FBX 日志名称。任务返回 status、issues、fixes、exports（procedures.md P1）。仅对大量小型可信文件使用 isolation="session"；崩溃的文件需重新隔离运行。GATE：每个场景都有一份报告；summary["sources_untouched"] 为 True；每条非通过记录都有说明。
3. 只读验证。 首先检查引用健康状况：P.reference_issues(P.references_report())（R01 未加载、R02 缺失、R03 编辑失败、R04 孤儿父级）。然后运行 mx_validate.validate(profile, roots) 和 P.check_engine_export(roots, engine, kind, rules={"fps": 30})（E01 至 E27：单位、单个根节点、名称、命名空间、矩阵、三角化、UV 和颜色集、锁定法线、影响对象、碰撞、枢轴、关节、空网格、时间单位）。GATE：每个文件都有问题列表；此时尚未更改任何内容。
4. 安全修复，然后保存版本。 仅执行允许的修复；N 边形、非流形、朝向、对称、单位和关节朝向只报告，不修复（FlippedNormals、ToWRH4IXF7A [00:11:50]）。unlock_normals 和影响对象上限需显式启用；若权重移动超过 0.1，上限设置会拒绝执行 [added]。P.save_version() 会写入 <out>/fixed/<stem>_fixed.ma。GATE：每个节点都有修复日志；重新验证时没有新增失败项。
5. 导出。 P.fbx_export(path, roots, "unreal_skeletal")（预设 unreal_/unity_ 加上 static、skeletal、anim；P.fbx_commands(preset) 可显示 MEL）。动画：明确烘焙范围；Unreal 每个文件一个片段；仅导出关节。缓存：P.abc_export（-uvWrite -writeFaceSets，取自合成镜头）。USD：P.usd_export(path, roots, frame_range=...)。GATE：<file>.settings.json 显示回读的所有选项；已找到并读取 FBX 日志（rep["fbx_log"]、X05）。
6. 在干净场景中验证。 P.fbx_takes(path)（不导入）、P.reimport_stats(path)、P.compare_stats(before, after)；P.abc_verify；P.usd_verify。GATE：网格、三角形、UV 集、关节名称、每个网格的包围盒、法线方向（移动不超过 2%）、单位和向上轴均匹配；片段数 = 动画片段数 + Take001；USD 的默认 prim、时间范围、带法线的 scheme none、SkelRoot、metersPerUnit 0.01。
7. 报告和差异对比。 summary.json/summary.csv、P.export_manifest(summary)、P.publish_diff(previous, current)。检查一个样本（修复后文件的图集、引擎导入结果）。GATE：报告列出未验证的内容。

内置任务会为每个文件执行第 3 至第 6 阶段： P.batch(scenes, P.BUILTIN_EXPORT, out, plugins=("fbx",), job_args=["--preset", "unreal_skeletal", "--profile", "rig", "--fps", "30"]) （procedures.md P2）。

其他任务，遵循相同规范（procedures.md）：USD 镜头图层，使用单个编辑目标，将自身及更强的图层静音（P9）；根据清单处理引用，命名空间冲突时抛出异常（P10）；OM2 通过 mx_audit.mfn_mesh 读取、插件和 PySide6 面板（P12、P13）；先运行 P.perf_census，再运行 P.eval_timing（P14）；检查 modified 后，通过 mx_bridge 处理 GUI 部分（P15）。

数值

数值	相关对象	来源
FBX 2020.2（FBX202000 [verify token]）	Unreal 导入	Epic
cm，缩放系数 1.0；1 Unreal 单位 = 1 cm	Maya 工作单位	Maya 2027 Help，缩放
每个顶点 4 个影响	Unity 默认	Unity manual
至少 15 根骨骼，T 姿势	Unity 人形	Unity manual
UCX_/UBX_/USP_/UCP_ + 网格名称 + _00	Unreal 自定义碰撞	Epic
SOCKET_<mesh>_##，每个文件一个网格	Unreal 插槽	Epic
Take001 始终存在	FBX Take 数量	Maya 2027 Help
frameRange 默认为 [1, 1]	mayaUSDExport	maya-usd readme
每个图层丢失 2 GB	USD 保存到 Maya 文件中	USD for Maya 2027
stdout 为 none，stderr 为 all（默认值）；mx_run：stderr 为 warning	MAYA_BATCH_*_LOGGING_LEVEL	devkit 2022；[added]
最大权重变化 0.1；包围盒对角线的 1e-3；法线的 2%（每轴 8 个区间）	自动影响上限；往返包围范围；往返法线	[added]

质量门槛

代码检查： 预检通过；批处理统计涵盖每个文件，源文件未被修改，且没有崩溃导致批处理停止；修复前参考状态干净；修复前进行验证，修复后记录修复日志；引擎检查错误数为零（E27 按目标速率）；每次导出均有设置旁文件和 FBX 日志；每次导出均通过往返检查，包含法线和轴向；fbx_takes 数量符合预期；usd_verify 通过；细分结果为空；在提出任何速度声明前，eval_timing(...)["consistent"] 为真；生成代码通过 test_offline_snippets_compile.py 中的 lint 检查。评分标准： references/critique.md。

目视检查： 抽样检查已修复文件的 mx_review 表格（任何 unlock_normals 之后采用法线模式）；逐个检查缓存相对于绑定骨架的 playblast；抽样检查引擎中的导入结果（枢轴、碰撞、LOD 切换、材质槽）；材质随 USD 传递时，对比原始 USD 与重新导入后的渲染；截取任何工具 UI 的屏幕截图。

常见错误

错误	表现	修复
在单个 mayapy 循环中处理所有文件	处理到文件 57 时发生段错误，文件 143 从未运行	使用 P.batch（每个文件对应一个子进程）
仅设置一次 FBX 选项，从不重置	第二次导出带上了第一次导出的动画片段或设置	fbx_export：推入、重置、设置、清除动画片段，然后弹出
关闭 FBX 日志或从不读取	批处理“成功”，却不知道哪些文件有问题（Maya Help）	开启日志，为每个子进程设置 MAYA_FBX_LOG_FILENAME，并在报告中记录 X05
在四边形上计算切线，由导出器进行三角化	切线错误；出现“完全随机的平滑效果”（Epic）	绑定前在 Maya 中使用 polyTriangulate 并控制边
存在剪切或父级非均匀缩放	导入后部件跳动或扭曲	E05；冻结变换或重建层级
往返检查仅比较数量	数量相同，但平滑、轴向或缩放信息丢失	使用 compare_stats：逐网格比较边界、法线、单位和向上轴
FBX 或 OBJ 导入后法线被锁定	绑定变形时，着色效果保持不变	E11 / locked_normals；绑定前解锁（FBXImportUnlockNormals）
动画未指定烘焙范围	受约束骨骼保持静止，时长错误	每次都设置 bake=(s, e)；对于 Unreal，每个文件只包含一个动画片段
场景为 30 fps，序列为 24 fps	动画与引擎序列不同步	使用 --fps 指定 E27；修正源帧率
使用默认设置的 mayaUSDExport	仅导出一帧、网格被平滑处理，且没有骨架	使用 P.usd_export，或显式设置每个标志
参考文件未加载或编辑失败	部件缺失、关键帧丢失	R01 到 R03 会停止任务；使用 swap_reference，绝不要重命名子对象
对每个形状都调用 MFnMesh	一个多余的空网格就会导致文件崩溃	使用 mx_audit.mfn_mesh；E24
自动修复 n 边形或权重	轮廓或变形发生变化	报告问题；设置启用选项，并限定最大偏差
盲目调用桥接；在 macOS 上批量渲染卡住	警告信息一闪而过；渲染从未开始	读取 stdout、stderr、maya_messages；预检，并在 /etc/hosts 中配置 localhost

交接

从每个角色接收： 保存的版本、接收配置文件的 mx_validate 报告、mx_audit 数值、发送方查看的图纸或预览播放，以及未验证列表。scenario-maya-modeling 和 scenario-maya-retopology-uv：位于原点的静态网格，注明三角化方式，包含 UV，接缝处有硬边，除非有意为之，否则法线不锁定；scenario-maya-rigging 和 scenario-maya-deformation：可引用的绑定、一个变形骨架、已删除 Skin Tools 图层，影响数量符合目标；scenario-maya-animation：片段名称、范围和速率；scenario-maya-fx 和 scenario-maya-groom：带版本号和帧范围的缓存；scenario-maya-lookdev：适合传递的材质（UsdPreviewSurface 或 MaterialX）。

交付： 可供引擎使用的文件（<out>/fbx/、缓存、USD 图层），每个文件都附带设置旁车文件和 FBX 日志，<out>/fixed/ 中的修复版本、逐文件报告、summary.json/.csv、清单和发布差异，以及未验证列表。问题按 ID 退回负责人：E07 和 E11 退回 scenario-maya-modeling，E14 和 E26 退回 scenario-maya-deformation（Delete Skin Layers 会保留权重），E02、E13 和 E27 退回 scenario-maya-rigging 或 scenario-maya-animation。

Maya 2027 说明

• FBX 选项页面仍将 FBX 2019.2 称为默认版本：请设置版本；2027 FBX 导入可以读取用户法线（What's New 2027）。MAYA_FBX_LOG_FILENAME 和 MAYA_FBX_LOG_DATETIME_ISO（2025）可将并行的 FBX 日志分开；macOS 日志文件夹为 [verify]。
• 批处理输出：MAYA_DISABLE_ADP=1 和 MAYA_BATCH_STDOUT/STDERR_LOGGING_LEVEL（devkit 2022），由 mx_run 设置。
• 2027.0 至 2027.2 中的 USD for Maya 版本为 0.35 至 0.37：新安装中 MaterialX 是默认材质目标（0.34），而 readme 写的是 UsdPreviewSurface；-parentScope 已弃用，请改用 -rootPrim。
• Alembic 仅支持 Ogawa；2027.2 修复了变形导出中的 UV 集顺序错误。
• MFnMesh 在网格为空时会引发异常（2022.1）；已移除的标志和 PySide 规则：参见 scenario-maya-expert。
• 引用：2027.1 修复了卸载 ikRPsolver 引用后 ls(modified=True) 崩溃的问题；2027.2 中，在打开 Node Editor 时移除引用可能导致崩溃。

参考资料

• references/procedures.md：批处理作业、内置导出作业、预检、FBX（静态、骨骼、片段、日志、包含法线和轴验证的验证）、锁定法线、Alembic、GPU 缓存、USD 导出和图层、引用及其健康状态、发布差异、DG 节点插件、PySide6 面板、性能、GUI 部分的完整代码。编写任何管线代码前请加载。
• references/expert-notes.md：按来源整理的判断，附时间戳，以及包含决策条件的不同意见。选择取决于任务说明时请加载。
• references/critique.md：每种输出的评分标准，以及 H01 至 H34 的每条交接规则的测量位置。报告运行完成前请加载。
• references/gui-paths.md：执行相同任务的菜单和选项。
• references/sources.md：所有来源及其凭据、URL 和最佳时间戳。
• scripts/mx_pipeline.py：经过离线测试的模块（文档字符串列出了所有函数）。