scenario-maya-expert

Maya 专家（路由器和 Agent 协议）

Maya 专家工作是一个循环，而不是一段脚本：从大到小进行搭建，每个阶段都先测量、渲染、观察并修正，再添加细节。此技能是每项 Maya 任务都遵循的协议，是其他 scenario-maya-* 技能调用的共享工具包，也是它们的索引。目标：在 macOS Apple Silicon 上通过 Python 驱动 Maya 2027。如果此处提到的同级技能不在你可用的技能中，请要求用户安装（npx skills add scenario-labs/skills --skill <name>）；若需无人值守地继续，则依据工具架构进行操作，并标明缺失之处。

状态（2026-09-24）： 尚未安装 Maya 2027。scripts/ 和 references/ 中的所有 Maya 调用尚未在 Maya 中运行。纯 Python 部分和 Maya 层逻辑已针对模拟对象离线运行并通过。安装 Maya 后的第一步： 运行 tests/code/maya-expert/run_all.sh，然后读取 archive/tests/maya-expert/<stamp>/results/test_00_probe.json，并修正此处标记为 [verify] 的所有内容。

1. 执行渠道

渠道	适用场景	规则
通过 scripts/mx_run.py 使用无头 mayapy	审计、验证、导出、Arnold 审阅渲染、批处理，以及任何不需要视口的任务	python3 mx_run.py [--scene f.ma] [--plugins mtoa,fbx,abc,usd] job.py -- args。每个场景使用一个子进程：崩溃或挂起只影响一个作业。最后一行标准输出为 MX_RESULT {json}；退出码 0 表示成功，1 表示作业出错，4 表示超时。子进程会设置 MAYA_DISABLE_ADP=1，并将 Maya 的标准错误日志级别设为 warning（调试时使用 --maya-log all）。关闭脚本节点。绝不覆盖源文件：使用 --save-as 保存为新版本。
通过 scripts/mx_bridge.py 使用实时 GUI Maya	播放预览、视口截图、交互式工具、用户已打开的场景	Emmanuel 在脚本编辑器中启动 mx_bridge_server.start() 一次。然后执行 Bridge().run(code)：代码长度不限，可包含多条语句；每条记录都会包含 result、stdout、stderr、maya_messages（Maya 的警告和错误）以及回溯，即使发生超时也不例外。每次调用都要读取这些信息。一次调用对应一个撤销块。替换场景前检查 cmds.file(q=True, modified=True)。绝不打开模态界面。完成后调用 stop()。

不要自行启动 GUI Maya [新增]：这会占用许可证席位，而且没有桥接服务就无法驱动。每台机器一次只执行一个 Arnold 渲染 [新增]。 mayapy：/Applications/Autodesk/maya2027/Maya.app/Contents/bin/mayapy（Maya 2027 帮助文档）。 mx_run.find_mayapy() 会依次检查 $MX_MAYAPY、$MAYA_LOCATION/bin/mayapy（在 macOS 上，MAYA_LOCATION 以 Maya.app/Contents 结尾），然后查找最新的 /Applications/Autodesk/maya20*/。在会话开始时记录 cmds.about(version=True)：Smart Bevel、MtoA 和 USD for Maya 在不同的 2027.x 版本间存在差异。

桥接使用文件的原因： commandPort 默认使用 MEL，缓冲区为 4096 个字符（命令过长会关闭连接，结果过长则会报错），且每次只返回一条语句的结果（Maya 2027 帮助文档，commandPort；Python in Maya）。mx_bridge 发送一行简短内容，并通过文件交换代码和结果（GG_MayaMCP 会预先安装处理程序；Palmer 需要往返两次）。安全性：端口以 127.0.0.1:<port> 的形式开放 [使用 lsof 验证]，且没有身份验证；Maya 的帮助文档警告，INET 端口可执行任意命令，包括以当前用户身份运行 system()。仅限个人机器使用，并在会话结束后关闭。

功能矩阵（根据文档整理；探测测试会确认或修正每一行）：

操作	无界面 mayapy	通过桥接的 GUI	依据
cmds / OpenMaya 编辑、文件 IO、引用、FBX、Alembic、USD 导出	是	是	Maya 2027 Help、Python in Maya
Arnold 静帧（mx_review）	是，CPU；没有 Arnold 批处理许可证时会添加水印	是	Arnold 批处理文档
Render -r hw2 视口风格的帧	有文档说明，尚未在 macOS 上验证	不适用	命令行渲染文档
playblast、modelEditor、视口抓取	否（需要模型面板）[verify]	是，mx_review.playblast	脚本编写概要
工具上下文：Quad Draw、Multi-Cut、雕刻、Paint Skin Weights、Skin Tools、3D 绘制、XGen 笔刷	否	仅限交互操作（无笔划 API）：编写底层命令脚本	Maya 2027 Help
scriptJob	否	是，播放期间除外	Maya 2027 Help、scriptJobs
maya.utils.executeInMainThreadWithResult	否，“在批处理模式下不可用”	是	Maya 2027 Help、线程处理
maya.utils.executeDeferred	仅在空闲事件运行时可用 [verify]	是	同上
MMessage 回调	[verify]	是	脚本编写概要
commandPort	据 Theodore 2014 所述不存在 [verify]	是	MCP 桥接说明
PySide6 窗口、workspaceControl	否	是	Qt6 迁移文档
Flow Retopology（云端）	否：需要登录和网络 [added]	是	版本差异
confirmDialog、input()、pdb、文件对话框	永不	永不：它们会阻塞 Maya 主线程和桥接	Maya 2027 Help、标准输入

2. 专家循环（适用于所有领域）

1. 用数字明确简报。 用途（引擎、电影、静帧、动画）、预算（三角面数、纹理尺寸和纹素密度、帧范围和 fps）、风格、参考资料、截止日期。如果简报没有说明，就采用该领域技能文档中记录的默认值，并写下来。
2. 按该领域技能中的阶段，由大到小推进。切勿从细节开始。
3. 构建一个阶段，使用小型、幂等的脚本（按名称获取或创建、为创建的内容添加标签、不依赖选择状态）。
4. 为阶段设置门槛，通过可测量的检查（mx_audit.verdict、mx_validate、该领域的数字指标）以及你用图像读取器打开的渲染结果来检查（无头模式下的 mx_review.review 联系表，或在 GUI 中制作的预览动画）。专家会不断转动模型；联系表就是 Agent 的环绕视角。依据该领域的 references/critique.md 进行评判。
5. 修正后再推进。 在灰模阶段发现问题，只需改一个脚本；纹理绘制后才发现，则需要返工整个阶段。
6. 交付并提供证据： 保存的版本、审计和验证 JSON、联系表或预览动画，以及未验证事项的清单。

未亲自查看模型、绑定、镜头或渲染结果之前，绝不可声称其已完成。先看数字，再用眼睛检查：Fragapane 对匹配工具的标准，是预期矩阵的逆矩阵乘以计算矩阵后得到单位矩阵，而不是“看起来正确”（Cult of Rig， [01:16:03]）；dcc-mcp 的展示则通过 0.0 的差值和至多 1/255 的颜色偏差来证明其主张。

3. Persona 工作流

简介	技能链	交付内容
硬表面道具或游戏资产	scenario-maya-modeling、scenario-maya-retopology-uv、scenario-maya-lookdev、scenario-maya-pipeline-scripting (FBX)	低模、UV、PBR 套件、重新导入并经过比对的 FBX
完善 AI 生成的网格	scenario-3d、在原始网格上运行 mx_audit、scenario-maya-retopology-uv、scenario-maya-lookdev、scenario-maya-pipeline-scripting	符合指定面数预算、从生成的高模烘焙而来的干净 UV 资产
用于关键帧动画的角色	scenario-maya-modeling、scenario-maya-retopology-uv、scenario-maya-rigging、scenario-maya-deformation、scenario-maya-animation (运动范围测试)	被引用的绑定文件、变形播放预览
游戏角色	使用 scenario-maya-rigging 和 scenario-maya-animation 的游戏选项执行相同技能链，然后使用 scenario-maya-pipeline-scripting	适用于 Unreal 或 Unity 的 FBX 骨骼网格和动画片段
动画镜头	scenario-maya-animation (在 scenario-maya-rigging 中修复问题)，然后使用 scenario-maya-lighting-rendering	已批准的播放预览，然后是渲染结果
外观开发或主视觉静帧	scenario-maya-lookdev、scenario-maya-lighting-rendering	转台展示、布光渲染、AOV
特效镜头	scenario-maya-fx (nCloth、Bifrost、MASH)，然后使用 scenario-maya-lighting-rendering	有版本记录的缓存、渲染结果
制作毛发的角色	scenario-maya-groom、scenario-maya-lookdev (毛发着色器)、scenario-maya-lighting-rendering	毛发、缓存、渲染结果
管线或批处理工具	基于 mx_run 和 mx_validate 构建的 scenario-maya-pipeline-scripting	工具和 JSON 报告

**交接约定：**每次交接都必须附带一个新保存的版本（绝不覆盖源文件）、针对接收方配置文件且没有 fail 的 mx_validate 报告、网格的 mx_audit 数值、发送方查看过的图表或播放预览，以及尚未验证的事项列表。单位保持为 cm，轴向保持 Y-up（Maya 2027 Help；Unreal 的单位为 1 cm）。

从，到	代码中的门槛	检查内容
建模到重拓扑与 UV 或绑定	validate(profile="model") 检查通过；将要变形的网格不得有锁定法线；细分或变形网格上不得有多边面；已冻结、无历史记录（FlippedNormals）；角色在 X 轴上对称，站在原点的网格上，Y 轴朝上、面向 +Z（Quick Rig 需要如此）	轮廓和泥稿表
重拓扑与 UV 到外观开发或绑定	每个面都已映射；UV 位于 0-1 范围内或整齐的 UDIM 瓦片中；注明纹素密度，单位为 px/cm；仅允许有意堆叠的重叠	线框和法线表
绑定或变形到动画	绑定采用引用方式，绝不导入；profile="rig" 检查通过；交接前删除 Skin Tools 图层（Maya 2027 Help：Delete Skin Layers 会保留权重）	运动范围预览
动画到灯光	profile="shot", rules={"fps": ...} 检查通过；已加载引用；缓存已进行版本管理（Alembic 仅使用 Ogawa）	最终预览
外观开发到灯光	file_paths 检查通过；为每个文件节点设置色彩空间	转台展示
特效或毛发到灯光	缓存已进行版本管理并包含帧范围；Nucleus 和 Bifrost 假定 1 个单位 = 1 米（Maya 2027 Help）	缓存预览

4. 共享工具集（scripts/，尚未在 Maya 中运行）

导入：import sys; sys.path.insert(0, "<this skill>/scripts")。桥接服务会将此文件夹添加到 Maya 的 sys.path，因此在 GUI 中也可以运行 Bridge().call("mx_audit", "audit", "crate_geo")。

• mx_run.py：find_mayapy()、run_subprocess(job, args, scene=, plugins=, timeout=, save_as=, maya_log=)（父进程端，返回已解析的字典）、child_environment()、run(job, args)（在 mayapy 内运行）。
• mx_bridge.py / mx_bridge_server.py： Bridge(port=7001).ping() / run(code) / call(module, fn, *a, reload=True) / fetch(id)、 format_record(rec)；服务端提供 start() / stop() / handle(id)。
• mx_audit.py：audit(mesh, texture_size=2048, units="cm") 返回计数、按价数统计的极点、非流形、多重面、零面积、边界和孔洞、绕序、UV 集和边界、UDIM 瓦片、重叠和折叠的壳、每个壳的纹素密度、冻结变换、枢轴、历史、命名、实例、X 轴对称、边长 CV；verdict(report, profile="game"|"film"|"subd") 列出 error: / warn: / info: 行；audit_all(roots)。供所有技能使用的保护函数：mfn_mesh(shape)（空网格时返回 None）、is_empty_mesh、split_history（绑定姿势和权重驱动器不属于历史）。
• mx_review.py：review(targets, out_dir, views, modes, resolution=1024, tile=512, focus=None)： front、side、back、threequarter、top、low；clay、wire、silhouette、normals，以及可选启用的 checker（checker_repeats=）和自定义 shader_modes=；subdiv=；一张带标签的图表和瓦片，以及每个视图的摄像机（r["cameras"]、review.json、pixel_ray），并恢复用户设置。技能使用这些选项，绝不使用 _Session。turntable(targets, out_dir, frames=24)； playblast(path, start, end, display={...})（仅限 GUI）。
• mx_validate.py：validate(profile="model"|"rig"|"shot", roots=None, rules=None, fix=())： 检查命名、命名空间、历史、冻结变换、非流形、多重面、n 边形、UV、锁定法线、平滑、渲染统计、图层、集合、未使用和未知节点、插件、引用、脚本节点、单位和上轴、帧速率、缺失文件；SAFE_FIXES；在修复期间通过 UUID 保留根节点（roots_after）。

5. Maya 代码规则（通用代码常见错误）

• 不依赖选择，明确指定对象： 每条命令都传入节点名称；绝不先 select 再操作。捕获创建命令的返回值（polyCube 返回 [transform, history]，# 名称会展开）并使用返回值，而不是使用你请求的名称（Autodesk 入门系列）。
• 对可能存在短名称冲突的对象使用长名称或 UUID；ls、 listRelatives、listConnections 后添加 or []［新增，已探测］。
• 撤销由你负责： 用 try/finally 将 GUI 编辑包在撤销块中。OpenMaya 2.0 的写入永远不会进入撤销队列；用 OM2 删除由 cmds 创建的节点会破坏撤销功能（Fragapane，[01:17:49]）。重度读取和矩阵运算使用 OM2；用户可能需要撤销的编辑使用 cmds。
• 单位： OpenMaya 使用厘米和弧度；cmds 返回 UI 单位和角度［新增，已在 test_00_probe 中探测］。
• 绝不触碰你未创建的节点；使用命名空间、属性或集合标记自己创建的节点，并按标记清理。保存阶段版本，绝不覆盖源文件。
• 仅限主线程： 在主线程之外调用 cmds 会引发错误（Maya 2027 Help）。

6. Maya 2027 中会让记忆代码失效的陷阱

• 仅支持 PySide6；不要提供 PySide2 回退方案（安装了 PySide2 时，它会导致 2027.0 崩溃）。 dockControl 已移除：改用 workspaceControl。
• 新场景使用 OpenPBR Surface；其参数无法从 Standard Surface 移植（发射单位为尼特，薄膜单位为微米，SSS 半径的作用互换）。
• addDoubleLinear、multiplyDoubleLinear、pointMatrixMult 已更名为 addDL、multiplyDL、pointMatrixMultDL（2026）；像 power 这样的普通名称现在会创建无单位节点。
• 已移除的标志：getAttr(noEvaluation=)、attributeQuery(computeModifies=)；获取所有关键帧应使用 cutKey(time=(None, None))。
• macOS 上的 Arnold：仅支持 CPU，不支持 OptiX；新场景使用 OIDN 成像器；Maya IPR 无法与 MtoA 5+ 配合使用（使用 Arnold RenderView）；如果许可证验证失败，批量渲染会中止，除非设置 ARNOLD_FORCE_ABORT_ON_LICENSE_FAIL=0。
• 颜色：使用 OCIO v2 和 ACEScg；自 2026.2 起，默认输入色彩空间为 sRGB Encoded Rec.709 (sRGB)；应查询名称，切勿硬编码。
• Skin Tools 图层会阻止使用经典权重工具（Mirror、Copy、Hammer、Paste、Normalize、Set Max Influences），直至删除这些图层。
• maya -render 已过时：使用 Render -r <renderer>；Render Setup 和旧版渲染层在每个会话中只能二选一。
• mayaUSDExport 的默认值：frameRange [1,1]、catmullClark 细分方案，map1 更名为 st。
• MFnMesh 遇到空网格时会引发错误（请使用 mx_audit.mfn_mesh）；MItGeometry 需要将组设为 -1 才能遍历所有顶点。未捆绑 PyMEL；Python 版本未公开，应先探测版本。

参考资料

• references/maya-2027-traps.md：会让 Agent 代码失效的完整清单，包含旧名称到 2027 替代名称的对应关系及来源。在凭记忆编写代码或参照 2025 年之前的教程操作前，请先加载此文件。
• references/cmds-reliability.md：可靠使用 maya.cmds 和 OpenMaya 2.0 的惯用模式及待测试流程（返回类型、已求值数据与原始数据、OM2 模式、撤销、幂等的获取或创建、批处理规范）。编写任何复杂脚本前，请先加载此文件。
• references/sources.md：此技能和工具包的所有来源，以及每个来源最适合的用途。
• 此系列之外的相关技能：scenario-3d（生成网格并在 Maya 中完成处理）、scenario-zbrush-expert 和 scenario-blender-expert（采用相同协议的姐妹团队）。