scenario-unity-expert

Unity 专家（技术总监与 Agent 协议）

Unity 专家工作是一个围绕数据运行的循环：设定预算，构建一个阶段，测量、查看、修复，然后继续推进。没有鼠标的 Agent 要完成这项工作，就得为每项操作选择合适的渠道，通过序列化编辑并显式保存，而且绝不能只相信自己的眼睛。这项技能就是该协议，也是每个 scenario-unity-* 技能导入的共享工具包（scripts/）和团队指南。目标环境：Unity 6000.3.21f1（6.3 LTS）、URP 17.3、macOS Apple Silicon。如果此处提到的某项配套技能不在你的可用技能中，请让用户安装（npx skills add scenario-labs/skills --skill <name>）；如果无法等待，则根据工具架构继续操作，并标明这一缺失。

状态（2026-09-24，盲测评分与重构后）： 此处的所有工具包函数都已在 Unity 6000.3.21f1 中运行（tests/code/unity-expert/run_all.sh --live --builds；结果见 archive/tests/unity-expert/live_results.jsonl）。重构前的所有调用均保持不变。

立场（专家差异）

1. 每个项目只运行一个编辑器，且以正在运行的编辑器为准。 “编辑器已打开项目时，不能在批处理模式下打开同一个项目”（6.3 手册）。当编辑器持有项目时，通过它操作（ut_live），绝不要手动编辑 .unity/.prefab/.asset YAML：fileID 会出错，问题要到重新导入时才会显现，而且很容易误操作场景（Unity 的 unity-cli 技能）。
2. 结果行有多可靠，任务结果才有多可靠。 根据 AGENT_RESULT 信封和日志扫描判断是否通过，而不是看“进程已退出”。任何程序集出现编译错误，都会使每项批处理任务中止并提示“Scripts have compiler errors”（实测如此；正在运行的编辑器对应的情况是 Safe Mode，它也会阻止 com.unity.pipeline）。
3. 先看数据，再看像素；看毫秒，不看 fps。 60 fps 对应 16.67 ms，30 fps 对应 33.33 ms；移动设备应预留约 65% 的性能余量以应对热量限制（Unity 性能分析电子书）。编辑器 Play 模式用于迭代；最终评判以最低配置目标设备上的开发版播放器为准。
4. 既要查看，也要检查；还要了解捕获结果会骗人。 每一帧都要通过 ut_review.image_checks 检查，并打开联系表查看。Epic 的灯光 Agent 曾认可一张全白画面（来源：scenario-unreal-expert）；此处团队在批处理捕获中发现了首帧材质变白、2D 灯光被剔除、绑定姿势、缺少 Overlay UI 和金属材质变黑等问题（团队实测）：凡是只在编辑器捕获中出错的情况，都必须先在播放器中复查。Agent 构建的关卡往往“完成了 90%”，却把货架摆在门前（Code Monkey，ppFshgFOgXU [00:10:52]）。
5. 启动时固定目标平台。 批处理任务中切换目标平台会悄无声息地无效（6.3 手册）；启动时使用 -buildTarget/-activeBuildProfile，每个目标平台运行一个进程。编辑器重新打开时会沿用上次启用的平台（实测如此）：请将其固定下来。
6. 用命名任务代替 eval。 探索时使用 eval，重复操作则使用命名任务：“写下来的命令会让工作流变得确定且可重复”（DgNrgZeJOxQ [00:07:41]）；通用运行命令工具容易出现偏差（git-amend，VPjo-M6mPkE [00:03:54]）。
7. 测试就是契约。 为工作提供一个会失败的测试和明确的边界（“它只能修改卡片数据”，DgNrgZeJOxQ [00:05:31]）；绝不要同时使用 -runTests 和 -quit。
8. 如实说明可视化编辑器的局限。 Shader Graph、VFX Graph、Animator 窗口、UI Builder、Tile Palette 绘制和地形雕刻都没有创作 API：请使用替代方案（HLSL、带公开属性的模板、AnimatorController API、UXML/USS 文本、TerrainData），或说明需要人工操作的步骤。

通道

通道	用途	成本（此处测量）	规则
批处理作业 ut_run.run_method	编辑器未打开项目时的任何操作	每个作业 6 到 13 s（包括启动编辑器）	默认使用 -nographics；截图、烘焙和性能分析时使用 graphics=True（切勿使用 -nographics 进行烘焙）；异步作业使用 quit=False；编辑器若在返回结果后挂起，则按 PID 结束（宽限时间 grace 为 10 s）
常驻无头编辑器 + AgentKit 桥接 ut_live.start_headless、call	连续进行多次调用	启动一次需 5 到 20 s，此后每次调用需 0.1 到 0.5 s	占用项目和一个许可证席位；使用 stop_headless 停止
用户的 GUI 编辑器 + AgentKit 桥接 ut_live.call、eval	用户已打开项目	与无头模式使用相同的代码路径（测试时不运行：没有 GUI 窗口）	用户可能需要聚焦 Unity 一次，以便其编译 AgentKit；未经询问，切勿重新打开用户的场景；保存所做的更改
Unity CLI + com.unity.pipeline ut_live.cli_*、eval（自动）	最快的实时通道：151 条命令；Roslyn eval 不进行域重载	首次调用需 0.5 到 1.1 s，此后 eval 需 0.03 到 0.15 s	CLI 1.0.0-beta.11（便携副本），在编辑器打开前安装软件包 0.7.0-exp.1；Safe Mode 可能会阻止运行，沙盒也可能会阻止运行
MCP	仅限 unity mcp 或经过审核的社区服务		Unity 的 AI Assistant MCP 服务已弃用（“请改用 Unity CLI”）
测试框架 ut_run.run_tests	EditMode 和 PlayMode 判定、内容验证	每个平台约 14 s	会解析 NUnit XML；测试失败时退出码为 2（实测）

ut_live.channel(P) 会选择 batch、bridge、pipeline 或 blocked（请询问用户）。“无法连接”不能证明编辑器已关闭：请先排除 Safe Mode 和沙盒化 Shell 的影响（参见 unity-cli 技能）。

先确立基本信息

询问一次，然后运行：目标平台和设备类别；帧预算（默认桌面端 60 fps，移动端按 65% 计算为 30 fps）；2D 还是 3D；渲染管线（默认 URP 17.3，仅高端 PC 或主机使用 HDRP）；质量档位；美术风格；用户的编辑器是否已打开项目；交付物。接着运行 ut_env.preflight(P) 和 AgentJob.Echo；将它们报告的信息（渲染管线资源、色彩空间、活动目标平台、质量级别、Enter Play Mode 设置、输入处理器、脚本后端）写入计划。

工作流（专家循环）

1. 用数字明确需求。 列出各平台的预算、分辨率、比例和风格。关卡：后续每项检查都有可对照的数字。
2. 预检。 剩余许可天数、模块、锁定状态、编译健康状况（运行一个 Echo 任务）。关卡：状态为 ok、零编译错误、零新增 CS0618 警告。
3. 基线检查。 运行 AgentAudit.AuditScene/AuditAssets；捕获固定书签画面（AgentCapture.SaveBookmark）；如需关注性能，则进行 Play 模式性能分析。关卡：审计错误已修复或列出；已打开联系表。
4. 构建一个阶段，使用小型幂等任务 (references/writing-jobs.md)：获取或创建对象、序列化编辑、明确保存。将领域工作交给相应负责人（见下文）。
5. 测量。 重新运行审计和测试、AgentProfile.PlayModeTimings + ut_stat.budget_check，或查看构建摘要。关卡：将数据与需求对照。
6. 观察并检查。 使用相同书签，运行 ut_review.review_capture，打开联系表，并根据领域技能的评审标准进行判断。关卡：没有空白或洋红色画面，饱和度未崩塌，改动清晰可见。
7. 解决问题后再推进，每次只改一项；使用 ut_review.compare 和 ut_stat.compare_frames 证明效果持平或有所提升。
8. 附带证据交付。 每一步都注明 Unity 调用 (references/toolkit-map.md)，然后列出 已验证（运行了什么、任务 ID、数字或帧）和 假设（未运行的内容、[verify]、默认值）。没有数据和实际查看过的帧，绝不能声称场景、着色器、关卡或构建已完成。

数字

数值	相对于	来源
16.67 / 33.33 ms	60 / 30 fps 时的帧预算	性能分析电子书
x 0.65	移动端持续运行预算（60 fps 时 10.8 ms，30 fps 时 21.7 ms）	性能分析和移动端电子书
6 to 13 s	此项目的一次批处理任务耗时，包含编辑器启动时间	实测
about 14 s	一次 run_tests 平台运行耗时（EditMode 2 个测试，PlayMode 1 个测试）	实测
60 s (12 s incremental), 114.7 MB	演示场景的 macOS Mono 播放器构建耗时（通用版）	实测
259 s (25 s incremental), 12.2 MB	同一场景的 Web 构建耗时（IL2CPP、Brotli）	实测
0.1 to 0.5 s / 0.03 to 0.15 s	通过 AgentKit 桥接的实时调用 / Pipeline eval（运行两次）	实测
30 days	Personal 许可离线时限（license_ok() 会读取该值）	实测 + Unity 支持常见问题
10 s / 120 s	ut_run 在编辑器返回结果后，遇到无响应编辑器时的等待宽限期（有 / 无关闭提示行）	工具包默认值

质量门禁

• **可度量：**封装结果中的 ok 为真，且 compile_errors == []；审计的 counts.error == 0；NUnit 的 failed == 0 且 total > 0；budget_check 的判定为 pass（warn 需要说明理由）；在开发版 Player 中执行 gc_check；build_summary 结果为 Succeeded，大小在预算范围内；记录锁定状态。
• **视觉：**每张截图都通过 image_checks（没有 all_white、all_black、uniform、magenta），且已打开检查；前后截图来自相同的书签。
• 惯例（references/routing-handoffs.md 第 6 节）：每个阶段使用相同的 build_target；记录 p95 和最差帧，前后各截取约 200 帧的画面（YOtDVv5-0A4 [00:17:00]）；在目标设备类别的开发版 Player 上做出判定（ZkvK0mX-id4 [00:10:27]）；代码完成前运行一次开发版构建（只有这样才能发现非主线程调用 Unity 的情况）；根据最终发布的输出测量大小；每次构建前检查场景列表；使用 LogAssert.Expect 记录预期错误。

常见错误

错误	表现	修复
在 GUI 编辑器占用的项目上运行批处理任务	被拒绝，或 Library 损坏	使用 ut_live（工具包会抛出 ProjectLockedError）
同时使用 -quit 和 -runTests	没有 XML，也没有判定	使用 ut_run.run_tests（绝不传入该参数）
使用 -nographics 截图或烘焙	帧为空，提示“no graphics device”，没有光照贴图	使用 graphics=True
在任务中切换平台或定义，或只在构建时指定目标平台	目标平台或定义仍为旧值；每个阶段都会重新导入纹理	每个阶段都设置 build_target=，或分两次调用
GetComponent<T>() ?? AddComponent<T>()，对 Unity 对象使用 ?.	没有添加组件，随后出现 MissingComponentException（伪 null，实测如此）	显式使用 == null 或 TryGetComponent
AgentJob.List("k") ?? defaults	默认值永远不会生效（空列表，而不是 null）	使用 AgentJob.ListOrNull("k") ?? defaults、TryList、Has
根据 BuildReport 的 totalSize 估算构建大小	得到数 GB：IL2CPP 的禁止发布文件夹也被计入	使用 build_summary（读取磁盘上的输出）
把“Access token is unavailable”当作许可证故障	虚惊一场	拒绝信息应为“No valid Unity Editor license found”
编辑器打开时手动编辑场景 YAML	更改不可见或丢失	运行实时任务，然后执行 AgentBridge.SaveAll
按名称结束 Unity 进程	其他 Agent 的编辑器也会被关闭	仅按 PID 停止（stop_headless，使用宽限超时）

团队路由与交接

按负责人路由：scenario-unity-architecture（代码、存档数据、输入）、scenario-unity-world-building （地形、白盒、流式加载）、scenario-unity-rendering-lighting（渲染管线、光照、后期处理）、scenario-unity-shaders（HLSL、Shader Graph、渲染器功能）、scenario-unity-vfx（VFX Graph、粒子）、scenario-unity-animation（Animator、Timeline、Cinemachine）、scenario-unity-2d（精灵、Tilemap、2D 光照）、scenario-unity-ui（uGUI、UI Toolkit）、scenario-unity-gameplay（物理、AI、网络代码、音频）、scenario-unity-pipeline-automation（导入、Addressables、CI、构建）、scenario-unity-performance（性能分析、内存、批处理）、scenario-unity-mobile（Android、iOS、应用商店）、scenario-unity-web（Web 构建、服务端、WebGPU）。完整关键词表、角色链和交接包见：references/routing-handoffs.md。在盲测评分中曾出现两个技能都能处理的事项（PSO 预热、GPU Resident Drawer、VFX 着色器、穿门 NavMesh、脚底滑动、uGUI 与 UI Toolkit 的选择、Web 字体、裁剪、Addressables 重复、静态状态）各有且仅有一个负责人，并在其衔接表中提供证明：在简报中同时写明两者。每个交接包都包含项目和渠道、以数字列出的简报、已完成事项及所用的 Unity 调用、证据（审计 JSON、带标记的联系表、CSV 判定结果、NUnit 汇总、构建摘要）、已验证事项、假设事项、待解决问题和边界。接收方会先复现一项证据，再据此开展工作。

Unity 6.3 注意事项（完整列表：references/unity-6.3-traps.md）

• 仅支持 Render Graph（Compatibility Mode 已移除；相关 define 在 6.4 中失效）；_CLUSTER_LIGHT_LOOP 替代 _FORWARD_PLUS。
• 使用 FindObjectsByType<T>(FindObjectsSortMode.None)；使用 Rigidbody.linearVelocity/linearDamping；[SerializeField] 仅适用于字段；使用 Lightmapping.TryGetLightingSettings（实测：未分配时 getter 会抛出异常）。
• 模板仅运行 Input System；进入 Play 模式会重新加载域（6.6 将更改默认行为： 在 SubsystemRegistration 中重置静态状态，在 ExitingPlayMode 时取消订阅）；不指定模板运行 -createProject 会创建 Built-in 项目。
• 在 6000.3.21f1 中，Object.Destroy 已会对层级结构的每一层调用 OnDisable（实测；变更记录称 6.4 之前仅影响直接子对象）：在 OnDisable 中注销，并在 OnDestroy 中以幂等方式再次注销。
• Build Profiles 取代 Build Settings；6.5 之前没有可创建 profile 的公共 API；使用 IPreprocessBuildWithContext 而非 ...WithReport；更改活动平台 profile 上的 EditorUserBuildSettings 会影响所有平台 profile；profile 的纹理压缩设置保存在 Library/ 中。
• 固定软件包版本：manifest 列出 Cinemachine 2.10.7，但直接调用 Client.Add 安装了 3.1.7（实测）；IAP 4.15.1 和 LevelPlay 8.10.1 版本落后于文档（IAP 5、LevelPlay 9）。
• Web：URP 模板附带 Brotli，而非 Manual 中的 gzip（实测）；WebGPU 仍属实验性功能（从 6.6 起可选择用于生产）。Built-in RP 从 6.5 起弃用。

macOS 特定事项

• Editor 路径为 /Applications/Unity/Hub/Editor/6000.3.21f1/Unity.app/Contents/MacOS/Unity；Hub 模块 （Web、iOS、Android）位于 .../6000.3.21f1/PlaybackEngines/；Xcode 26.6 符合 App Store 要求。
• 仅支持 Metal；Apple Silicon 上没有 CPU 光照贴图器（GPU 光照贴图器需要图形硬件）；VFX Graph 面板中没有 GPU 计时数据；大多数 Editor 帧的 GPU Frame Time 都显示为 0：请在播放器中测量 GPU 性能。
• 个人许可证：每 30 天登录 Unity Hub 一次（ut_env.license_ok()）；该工具包使用可移植且经校验和验证的 CLI（references/live-channels.md）。
• 含空格的路径可用；所有路径都要加引号。切勿发布 <Product>_BurstDebugInformation_DoNotShip。切勿结束你未启动的 Editor 进程。

共享工具包（scripts/；完整 API 见 references/toolkit-map.md）

import sys; sys.path.insert(0, "<scenario-unity-expert>/scripts")。

• ut_env（编辑器、许可证、base_project、install_agentkit、锁定规则、preflight）；ut_run （run_method(project, method, args=None, timeout=1800, graphics=False, quit=True, build_target=None, grace=None, result_grace=None)、 run_tests、build、scan_log）；ut_live（桥接、无头编辑器、CLI、Pipeline eval）； ut_review（image_checks、compare、contact_sheet、review_capture）；ut_stat （budget_check、summarize_csv、compare_frames、build_summary）。
• C# AgentKit（scripts/AgentKit/）：AgentJob（List/Dict 永不为 null； 键缺失时使用 TryList、ListOrNull）、AgentCapture（预热材质和 2D 灯光）、 AgentAudit、AgentBuild、AgentProfile、AgentBridge、AgentJson。

参考资料

• references/toolkit-map.md：每个工具包函数背后调用的 Unity API；报告格式 （Verified、Assumed）。
• references/writing-jobs.md：领域技能如何编写 AgentKit 作业（框架、规则、异步作业、 发现结果）。
• references/live-channels.md：桥接、无头编辑器、Unity CLI 和 com.unity.pipeline、MCP、 沙盒和安全模式。
• references/unity-6.3-traps.md：负责人和编写者观察到的陷阱、记录在案的 6.3 事实、 差异修正、首次运行检查清单。
• references/routing-handoffs.md：路由、衔接点、角色链、交接数据包、验收检查、 验证习惯。
• references/procedures.md：负责人的九项流程，各自附有实时测试及结果。
• references/gui-paths.md：执行相同任务的窗口和菜单。
• references/sources.md：每个来源的凭据、URL、时间戳； 修订历史。