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 确实不存在还是卡在 Safe Mode 中，以及查明 Editor 的命令目录。请先按该技能操作；不要在此重复推导这些内容。

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

• 你特别需要 eval，而不只是能连接到 Editor。请确认它出现在命令目录中。它是否存在取决于 Pipeline 包版本，而非 CLI，因此即使安装正常，也可能缺少它——如果找不到，请说明这一点并停止。
• 不要退而手动编辑 .mixer 文件。 混音器路由无法在不了解情况时安全地编辑，因此无法连接到 Editor 就应停止，而不是临时想办法。

eval 可用后，以下每个 C# 步骤都通过它运行。

通过已连接的 Editor 使用 eval 命令运行 C#。请通过 unity command --format json 查明它的参数格式，不要自行假设——内联形式为 unity command eval --code '<snippet>'，部分 Pipeline 版本也会注册 eval_file，用于从文件运行代码片段。尝试使用 eval_file 前请先检查命令目录；它经常不存在。 unity command 的默认超时时间为 30 秒。

向 eval 传递 C#

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

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

下面若有代码片段以文件形式编写——包含 using、为了便于阅读，或原本就要保存到项目中——请先将类型改为完全限定名称，再传递给 eval。

步骤 1：预检

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

然后通过步骤 0 所述方式在 Editor 中运行 references/api.md 中的混音器盘点代码片段，检查现有内容。它会列出项目中的所有混音器及各自的组名。

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

**如果项目中完全没有混音器，**请说明情况并停止，不要自行创建：创建混音器没有公开 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 的子集，并非 SFX 的另一种说法，因此不能仅仅因为存在 Foley 分组，就把枪声归入该分组。若现有分组只能部分覆盖你的类别，请说明哪些类别适用、哪些需要新分组，并让用户决定。

对于没有匹配分组的类别，你无法创建分组——目前没有公开 API。请按照 references/api.md 末尾的说明，准确交由用户处理，并明确指出混音器名称和确切的分组名称。然后重新运行清单代码片段，以确认分组存在并核对拼写。不要假设用户已经创建，也不要假设他们采用了你要求的拼写。

步骤 4：路由 Audio Source

分组列表确定并确认存在后，使用 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