audio-setup-mixers

音频混音器设置

将音频源路由到混音器组是一项场景编辑操作，只能由正在运行的 Editor 执行，因此此技能需要一个可以运行 C# 的实时 Editor。第 0 步会先确认这一点。

此技能会自动执行的操作，以及需要交由你完成的操作。 检查混音器并将音频源路由到各个组，完全可以使用 Unity 公共 API 完成；这也是繁琐之处——逐一检查几十个音频源，并根据它们播放的内容进行分类。创建混音器或组没有公共 API；它们只存在于 Unity 不承诺保持稳定的类型中。因此，此技能不会擅自创建组。它会盘点现有内容、提出路由方案、请你在 Audio Mixer 窗口中添加缺少的组，然后自行完成所有路由。

这是有意设置的限制，并非需要设法绕过的缺陷。不要使用反射来创建组，也不要手动编辑 .mixer 文件——在不了解结构的情况下，无法安全地编写混音器。

第 0 步：确认你可以在 Editor 中运行 C#

下面的每个 C# 步骤都会通过 Unity CLI 在实时 Editor 中运行。unity-cli 技能负责带你完成这一步——安装 CLI、确认 Editor 已连接、添加项目的 com.unity.pipeline 包、区分确实没有 Editor 和 Editor 卡在 Safe Mode 的情况，以及查找 Editor 的命令目录。请先遵循该技能的说明；不要在此重复推断这些内容。

有两件事需要你自行确认：

• 你需要的是 script eval，而不仅仅是能连接到 Editor。 请确认它出现在命令目录中。它是否存在取决于 Pipeline 包的版本，而非 CLI，因此即使安装正常，也可能没有此命令——如果缺少，请说明情况并停止。
• 不要退而求其次，手动编辑 .mixer 文件。 在不了解结构的情况下，无法安全地编写混音器，因此无法连接到 Editor 时应停止，而不是临时想办法绕过。

script eval 可用后，下面的每个 C# 步骤都会通过它运行。

通过已连接的 Editor 使用 script eval 命令运行 C#。请通过 unity command --format json 查明其参数格式，不要自行假设——内联形式为 unity command script eval --caller plugin --skill audio-setup-mixers --code '<snippet>'，某些 Pipeline 版本还会注册 script eval_file，用于运行文件中的代码片段。使用 script eval_file 前，请先检查命令目录；此命令经常不存在。 unity command 默认超时时间为 30 秒。

向 script eval 传递 C#

script eval 编译的是语句块，而不是文件。这会带来两个后果，都会导致编译错误，而非警告：

• 不能使用 using 指令。 编译器会将 using UnityEngine; 视为资源释放语句并拒绝它（CS0210）。
• 类型必须使用完整限定名。 无法解析未限定的 AssetDatabase 或 Volume（CS0246 / CS0103），未限定的 Object 则会与 object 冲突（CS0104）。

下面的代码片段如果以文件形式编写——包含 using 指令、为了便于阅读，或用于保存到项目中——在传递给 script eval 之前，请先为类型添加完整限定名。

步骤 1：准备工作

如果用户没有明确要求设置 Audio Mixers，请先确认他们是否要继续设置。

然后使用 references/api.md 中的 mixer-inventory 代码片段盘点现有内容，并按照步骤 0 中的说明通过 Editor 运行。这样可以获取项目中的所有 mixer 及其各自的组名。

它返回的是扁平的组列表，而非父子树。这足以用于路由，也是公共 API 所能提供的全部信息。如果对话中需要了解层级结构，请让用户查看 Audio Mixer 窗口并描述结构——不要调用非公开的树 API 来查询。

如果项目中完全没有 mixer， 请说明这一点并停止，不要自行创建：创建 mixer 没有公共 API。请用户创建一个（Window → Audio → Audio Mixer，然后点击 Mixers 旁边的 +），等它创建完成后再从这里继续。

步骤 2：查找场景引用

查找所有 Audio Source 组件，查看分配给它们的 Generator 资源名称，并归纳出合适的声音类别或类型，最好是已有的类别。 Audio Clip 资源名称示例：

• "FootStep4_Sound" -> Foley
• "Dialogue_Female_Scene4" -> Vox/Voice/Dialogue
• "GunShot" -> SFX
• "Menu_Theme_Variation" -> Music

如果分配的资源名称描述性不足或资源不存在，请尝试查看 GameObject 名称或可能相关的 MonoBehaviour 名称。 如果难以判断 Audio Source 的用途，或分类把握不大，请询问是否创建 Uncategorized 组。

步骤 3：确认组列表，并创建缺少的组

将步骤 2 中的分类作为路由方案提供给用户——列出每个 Audio Source 及你打算将其发送到的组——并与用户一起修改。

等待用户回复后再继续。

如果现有组确实适用于某个类别，即使你会采用不同的名称，也优先使用该组。但不要合并混音工程师会分别处理的类别——Foley 是 SFX 的子集，并非它的另一种说法，因此不能仅仅因为存在 Foley 组，就把枪声归入其中。如果现有组只能覆盖部分类别，请说明哪些类别适用、哪些需要新建组，并让用户决定。

对于没有匹配组的类别，你无法创建该组——没有用于此操作的公共 API。请准确告知用户需要创建哪些组，并指出 mixer 名称和确切的组名，具体格式见 references/api.md 末尾。然后重新运行 inventory 代码片段，确认这些组已存在并检查拼写，再进行路由。不要假设用户已经创建，也不要假设他们按你要求的名称拼写。

第 4 步：路由音频源

确认分组列表已敲定且存在后，使用 references/api.md 中的路由代码段，为每个 Audio Source 指定输出组。整个过程都使用公共 API，并封装在单个撤销步骤中，因此用户可以一次性撤销所有操作。

映射的键应使用你分类时依据的标识符。 第 2 步会先读取片段资源名称，只有在没有该名称时才使用 GameObject 名称，因此映射接受其中任意一种——二者是不同的标识符，使用错误的标识符作为键会导致源被遗漏。

以下三项应如实报告，不要自行假定：

• 代码段返回的任何 NO SUCH GROUP 条目。 这表示你预期存在的组不在混音器中——通常是拼写差异。请与用户确认并解决，不要默默跳过该源。
• 任何 NOT IN THE MAPPING 条目。 这些是分类时遗漏的 Audio Source。悄悄留下未路由的源，却报告路由成功，是最糟糕的结果，因为这会让人以为操作已成功。
• 场景已修改，而非混音器资源。 路由设置保存在 Audio Source 上，因此只有保存场景后才会持久保留。请告知用户，并仅在获得用户同意后保存。

音量、效果和重新设置父级不在本次范围内。 这些功能使用非公共 API。如果用户提出相关要求，请说明路由已完成，并引导他们在 Audio Mixer 窗口中调整混音本身。

参考

请参阅 references/api.md