docs(kaisa): make UCM HiFi the only supported path

Promote UCM2/HiFi (Jack-driven) as the primary delivery, add HISTORY.md, remove ProAudio/REPRO docs and non-UCM scripts, and fix repo-wide references. Made-with: Cursor
2026-04-08 15:22:45 +08:00
parent 17f0a4521f
commit bda6b60c15
33 changed files with 384 additions and 1780 deletions
--- a/docs/INDEX.md
+++ b/docs/INDEX.md
@@ -4,10 +4,7 @@

 | 文档 | 说明 |
 | ---- | ---- |
-| [linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md](linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md) | **主路线**：**「核心问题」复盘**、pro-audio、`50-kaisa`、**default-profile**、IEC958、一键脚本、**恢复 Ubuntu 后重测**（**deb 见 §4.4**） |
-| [linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md](linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md) | **可选**：UCM2、HiFi、`60-kaisa-ucm.lua`（与 pro-audio 互斥） |
-| [linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md](linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md) | 旧文件名重定向（上表两篇取代） |
-| [linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md](linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md) | deb 手顺**存档**（未来计划） |
+| [linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md](linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md) | **主路线（交付）**：UCM2、HiFi、`60-kaisa-ucm.lua`、Jack-driven 端口、IEC958、安装 / 验收 / 排障 |
 | [README.md](README.md) | 本目录说明 |

-**脚本（仓库根 `scripts/`）**：一键 pro-audio — [`apply-kaisa-pro-audio.sh`](../scripts/apply-kaisa-pro-audio.sh)；登录后再拉 pro-audio — [`kaisa-reapply-pro-audio-session.sh`](../scripts/kaisa-reapply-pro-audio-session.sh)（[ProAudio §4.1b](linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md)）；卸历史 deb — [`remove-kaisa-hdmi-deb.sh`](../scripts/remove-kaisa-hdmi-deb.sh)；门禁 — [`verify-kaisa-pro-audio.sh`](../scripts/verify-kaisa-pro-audio.sh)。
+**脚本（仓库根 `scripts/`）**：禁用 pro-audio 片段 — [`disable-kaisa-pro-audio-wireplumber.sh`](../scripts/disable-kaisa-pro-audio-wireplumber.sh)；安装 UCM overlay — [`install-kaisa-ucm-overlay.sh`](../scripts/install-kaisa-ucm-overlay.sh)。
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,12 +1,10 @@
 # `docs/` 说明

-本目录保留 **已实机验证** 的 PipeWire 主路线；**deb 不作为当前交付**（仅未来计划存档）。
+本目录保留 **已实机验证** 的 Kaisa（`sof-rt5682`）音频交付文档；当前主交付为 **UCM2 + HiFi（Jack-driven）**。

 | 文档 | 内容 |
 | ---- | ---- |
-| [linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md](linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md) | **主路线**：**核心问题复盘**、**default-profile**、pro-audio、`50-kaisa`、一键脚本、**恢复 Ubuntu 重测**、基线 |
-| [linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md](linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md) | **可选**：UCM2、HiFi（与 pro-audio 互斥） |
-| [linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md](linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md) | deb 手顺**存档**（未来若恢复打包时对照） |
+| [linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md](linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md) | **主路线（交付）**：UCM2、HiFi、Jack-driven 端口、IEC958、安装/验收/排障 |

 附属文件：`linux-hdmi/wireplumber/50-kaisa-sof-rt5682-hdmi.conf`、`linux-hdmi/systemd-user/kaisa-hdmi-iec958-pipewire.service`。

--- a/docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md
+++ b/docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md
@@ -1,10 +0,0 @@
-# 本文件已拆分（兼容旧链接）
-
-原 **`OPERATION_PipeWire_Kaisa_HDMI.md`** 已拆成两篇，请直接打开：
-
-| 文档 | 内容 |
-|------|------|
-| **[`OPERATION_PipeWire_Kaisa_ProAudio.md`](OPERATION_PipeWire_Kaisa_ProAudio.md)** | **主路线（已验证）**：PipeWire **pro-audio**、`50-kaisa-sof-rt5682-hdmi.conf`、默认 **`pro-output-0` / `pro-output-2`**、IEC958、一键脚本与基线（**deb 仅 §4.4 存档**） |
-| **[`OPERATION_PipeWire_Kaisa_UCM_HiFi.md`](OPERATION_PipeWire_Kaisa_UCM_HiFi.md)** | **可选**：ALSA **UCM2**、**HiFi**、`60-kaisa-ucm.lua`、Jack 驱动端口、安装 / 验收 / 卸载 |
-
-两路线 **互斥**。新读者请从 **ProAudio** 文档读起。
--- a/docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md
+++ b/docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md
@@ -1,448 +0,0 @@
-# 操作：Kaisa（sof-rt5682）ProAudio + HDMI（WirePlumber 固化）
-
-**主路线**：PipeWire **`pro-audio`**；默认 **`pro-output-0`（模拟）** / **`pro-output-2`（外接 HDMI）**。UCM / HiFi 为 **可选互斥路线**，见 **[`OPERATION_PipeWire_Kaisa_UCM_HiFi.md`](OPERATION_PipeWire_Kaisa_UCM_HiFi.md)**。
-
-**适用**：Google **Kaisa**（如 `Google-Kaisa-rev4`）、PipeWire + WirePlumber（Ubuntu 24.04 常见）、声卡为 **`alsa_card.pci-0000_00_1f.3-platform-cml_rt5682_def`**（若 PCI 路径不同需改配置）。
-
-**当前阶段**：以 **本机手工配置 + 文档/脚本复现** 完成技术验证。**本文主路线 = 仅 pro-audio（已验证）**：默认 **模拟用 `pro-output-0`、外接 HDMI（逻辑 HDMI1）用 `pro-output-2`**，下文命令与说明均按此约定撰写，除非另行标注排障分支。**Debian 包**：**当前不做交付与维护**，仅作**未来计划**；仓库内 **`debian/`** 与 **§4.4** 保留为日后若恢复打包时的**存档参考**（**`apply-kaisa-pro-audio.sh` 仍会默认 purge 已装的 `kaisa-hdmi-pipewire-fix`，以免与脚本路线冲突**）。
-
---
-
-## 核心问题（复盘摘要）
-
-**记录说明**（2026-04）：以下摘要用于 **还原/重装 Ubuntu 后的回归测试** 对照；与 **§4.1b**（`default-profile`）、一键脚本及 **`verify-kaisa-pro-audio`** 一致。
-
-**业务目标**：在 Kaisa + Ubuntu + PipeWire 上让 **HDMI 数字声**稳定可用；主路线为 **`pro-audio` + 正确默认 sink + IEC958**，不依赖桌面偶然选到某一路。
-
-**技术本质**
-
- **`stereo-fallback` 等默认 profile** 往往只暴露 **极少 sink**，多路 HDMI **不会**都在 **`pactl list short sinks`** 里；**GNOME「输出」项少**常与 **profile/端口可用性**有关，**不等于**栈里只有一路。
- **HDMI 出声**还依赖 **`IEC958`（及对应 Playback Switch）为 on**；PipeWire 侧「在播」仍可能 **显示器无声**。
- **机箱物理口 ↔ `hw:0,N` / `pro-output-N`** 要以 **`aplay -l`、`wpctl inspect`、Jack** 对照，不能死记「HDMI1」等 UCM 展示名（见 **[UCM 文档](OPERATION_PipeWire_Kaisa_UCM_HiFi.md)**）。
-
-**主路线上的硬冲突（重点）**：WirePlumber **`default-profile` 模块**会把上次选用的 profile 记在 **`~/.local/state/wireplumber/default-profile`**。若其中 **`alsa_card…cml_rt5682_def`** 被存成 **`output:stereo-fallback+input:stereo-fallback`**，**每次启动都会从磁盘恢复**，常 **盖过** **`50-kaisa`** 里 **`monitor.alsa.rules` 设的 `pro-audio`**，表现为 **`pro-output-*` 出现一下又变回 `stereo-fallback`**。对策：**`strip-kaisa-default-profile-state.sh`**（**`apply` 已在重启栈前调用**）+ 再 **`pro-audio`**；细节见 **§4.1b**，**`verify-kaisa-pro-audio.sh`** 会对该脏状态 **FAIL**。
-
-**周边**：**UCM/HiFi** 与 **强制 pro-audio** **互斥**；**deb** 非当前交付；登录后若 **`default-profile` 已干净**仍偶发被改 profile，再用 **`kaisa-reapply-pro-audio-session.sh`**（§4.1b）。
-
-### 恢复 Ubuntu 后重新测试（建议手顺）
-
-1. **大改/重装前**（可选）：在仓库根执行 **`./scripts/capture-ubuntu-audio-baseline.sh`**，便于与 **§4.5** 基线对照。
-2. **恢复系统**：按你的方式 **重装 / 还原镜像 / `restore-ubuntu-audio-baseline.sh`**；若曾装 **deb** 或 **UCM overlay**，见 **`remove-kaisa-hdmi-deb.sh`**、**`remove-kaisa-ucm-overlay.sh`**。
-3. **登录图形会话后**，在仓库根执行 **`./scripts/apply-kaisa-pro-audio.sh`**（干净机用默认即可；已手动清过包的可 **`--keep-deb`**）。
-4. **验收**：**`./scripts/verify-kaisa-pro-audio.sh`**；仍异常时 **`./scripts/verify-kaisa-audio-environment.sh --output /tmp/kaisa-audio-verify.txt`**。
-5. **确认无回归**：检查 **`grep cml_rt5682 ~/.local/state/wireplumber/default-profile`** — 不应再出现 **`stereo-fallback`**（应为 **`pro-audio`** 或 **无该行**）。
-
---
-
-## 主路线：仅 pro-audio（已验证默认）
-
-| 步骤 | 做法 |
-|------|------|
-| 1. 禁用与 pro-audio **抢 profile** 的 UCM Lua | **`/usr/share/wireplumber/main.lua.d/60-kaisa-ucm.lua`** 若存在，应 **`sudo mv` 为 `60-kaisa-ucm.lua.disabled`**（或删除）。**未禁用则**重启后常见仍为 **HiFi**，与本文不一致。 |
-| 2. 安装 WirePlumber 片段 | 将 **[`50-kaisa-sof-rt5682-hdmi.conf`](wireplumber/50-kaisa-sof-rt5682-hdmi.conf)** 复制到 **`~/.config/wireplumber/wireplumber.conf.d/`**（文件名以 **`.conf`** 结尾）。 |
-| 3. 重启栈 | **`systemctl --user restart wireplumber pipewire pipewire-pulse`** |
-| 4. 卡 profile + 默认 HDMI | **`pactl set-card-profile <卡名> pro-audio`**；**`pactl set-default-sink`** 指到 **`…pro-output-2`**（逻辑 **HDMI1** / **`hw:0,2`**）。 |
-| 5. IEC958 | 按 §4.2 打开 **`IEC958',0`**（与 **pcm=2 / pro-output-2** 对齐）。 |
-| 6. 试声 | **`speaker-test -D pulse`** / **`paplay`**（见 §3，含 **指定 sink** 写法）。 |
-
-### 一键脚本（应用 + 门禁 + 可选基线）
-
-仓库提供：
-
-| 脚本 | 作用 |
-|------|------|
-| **[`scripts/apply-kaisa-pro-audio.sh`](../../scripts/apply-kaisa-pro-audio.sh)** | 默认 **purge `kaisa-hdmi-pipewire-fix`** 并 **`apt install --reinstall alsa-ucm-conf`**，禁用 **`60-kaisa-ucm.lua`** 与 **系统级 `50-kaisa*.conf`**，安装用户 **`50-kaisa-sof-rt5682-hdmi.conf`**，重启 PipeWire 栈，**`pactl set-card-profile … pro-audio`**、**默认 `pro-output-2`**，**`IEC958',0/1/2` 全开**，最后运行 **`verify-kaisa-pro-audio.sh`**（不通过则 **exit 1**）。 |
-| **[`scripts/remove-kaisa-hdmi-deb.sh`](../../scripts/remove-kaisa-hdmi-deb.sh)** | **仅**卸载历史 **`kaisa-hdmi-pipewire-fix`**（**`apt purge`**）并 **`reinstall alsa-ucm-conf`**；**不**改 WirePlumber、**不**重启栈。曾与 **`install-kaisa-ucm-overlay.sh`** 叠用时，purge 后若仍有 **`/usr/share/alsa/ucm2/GoogleKaisa`**，另跑 **`remove-kaisa-ucm-overlay.sh`**。 |
-| **[`scripts/strip-kaisa-default-profile-state.sh`](../../scripts/strip-kaisa-default-profile-state.sh)** | 删除 **`~/.local/state/wireplumber/default-profile`** 里 **cml_rt5682** 行，避免 **stereo-fallback** 持久化顶掉 **`50-kaisa`**；**`apply` 已内置调用**，见 **§4.1b**。 |
-| **[`scripts/kaisa-reapply-pro-audio-session.sh`](../../scripts/kaisa-reapply-pro-audio-session.sh)** | 先 **strip 同上**，再 **`pro-audio` + 默认 sink + IEC958**（登录 oneshot）；见 **§4.1b**、**[`kaisa-pro-audio-reapply.service`](systemd-user/kaisa-pro-audio-reapply.service)**。 |
-| **[`scripts/verify-kaisa-pro-audio.sh`](../../scripts/verify-kaisa-pro-audio.sh)** | 仅做 **pro-audio 基线门禁**（退出码 **0/1**），可被上手或 CI 单独调用。 |
-
-**常用参数（apply）**
-
- **`--keep-deb`**：不 purge deb、不 reinstall **`alsa-ucm-conf`**（仅改 WirePlumber / pactl / amixer）。
- **`--verify-only`**：不改动系统，只跑 **`verify-kaisa-pro-audio.sh`**。
- **`--no-verify`**：应用后**不**跑门禁（调试用，不推荐）。
- **`--restore DIR`**：先执行 **`scripts/restore-ubuntu-audio-baseline.sh DIR`**，再继续一键应用。
- **`--restore-only [DIR]`**：只做基线恢复，不应用 pro-audio；**`DIR`** 可省略，若与 **`--restore-stash-substring`** 同用则先解析基线目录。
- **`--restore-stash-substring STR`**：在 **`audio_topology/baseline-stash/*STR*/`** 中选 **最新 mtime** 目录作为 **`DIR`**，用于 **`--restore`** 或 **`--restore-only`**；若同时写了 **`--restore DIR`**，**子串解析在后、会覆盖 `DIR`**。找不到则报错并列出现有目录。
-
-**示例**（在仓库根、**登录用户**图形会话下）：
-
-```bash
-./scripts/apply-kaisa-pro-audio.sh
-./scripts/apply-kaisa-pro-audio.sh --keep-deb
-./scripts/remove-kaisa-hdmi-deb.sh          # 只清历史 deb + reinstall alsa-ucm-conf
-./scripts/apply-kaisa-pro-audio.sh --restore-stash-substring 20260406
-./scripts/verify-kaisa-pro-audio.sh
-```
-
-**门禁未通过**：先看 **`verify-kaisa-pro-audio.sh`** 的 **FAIL** 行；仍不清再跑全量采集：**`./scripts/verify-kaisa-audio-environment.sh --output /tmp/kaisa-audio-verify.txt`**。**PCI 非 `0000:00:1f.3`** 时需先改仓库内 **`50-kaisa-…conf`** 再执行 apply。
-
-**默认 sink 约定（已验证基线）**
-
- **3.5mm 模拟（Port1）**：**`alsa_output.…cml_rt5682_def.pro-output-0`**
- **外接 HDMI（逻辑 HDMI1）**：**`…pro-output-2`**，对应 **`api.alsa.path = "hw:0,2"`**、**`IEC958',0`**
-
-拔 HDMI 或仅听模拟时，把默认 sink 设回 **`…pro-output-0`** 即可。
-
-**若曾安装 `kaisa-hdmi-pipewire-fix`**：deb 会装 **UCM2** 等；要做**干净 pro-audio**，宜先 **`./scripts/remove-kaisa-hdmi-deb.sh`**（或 **`sudo apt purge kaisa-hdmi-pipewire-fix`** 并 **`sudo apt install --reinstall alsa-ucm-conf`**），再只保留用户级 **`50-kaisa-…conf`**。若 deb 与 **`install-kaisa-ucm-overlay.sh`** 都用过，purge 后仍可能有 **`GoogleKaisa`** 目录，需 **`./scripts/remove-kaisa-ucm-overlay.sh`**。系统 **`alsa-ucm-conf`** 以 **`reinstall`** 后为准；若异常以本机 **`pactl list cards`** 为准。
-
-**可选：UCM / HiFi** 与 **pro-audio 互斥**，见 **[`OPERATION_PipeWire_Kaisa_UCM_HiFi.md`](OPERATION_PipeWire_Kaisa_UCM_HiFi.md)**；**不要**与上表同时启用。
-
---
-
-## 1. 现象与原因（摘要）
-
-| 现象 | 说明 |
-|------|------|
-| 设置里只有 **「立体声」**、**`pactl list short sinks` 仅 1 个** | 声卡 profile 为 **`stereo-fallback`**，未暴露多路 HDMI PCM。 |
-| GNOME **「测试扬声器」** 无图标 | HDMI / Pro Audio 常无 Front L/R 声道名，**界面不可用**不代表无声；PipeWire 下用 **`speaker-test -D pulse`** 或 **`paplay`**（走默认 sink）；**`plughw:…`** 常与 PipeWire **EBUSY (-16)** 冲突。 |
-| **`HDMI/DP,pcm=3/4 Jack` = off** | 该路 **未检测到显示器** 时，通常不应指望有声；但 **Jack 与 ELD、`hw:0,N` 的编号不一定一一对应**（见 §3 文末）。排障以 **`wpctl inspect @DEFAULT_AUDIO_SINK@`** 里的 **`api.alsa.path`（如 `hw:0,2`）** 与 **`aplay -l` 子设备**为准。 |
-| **`IEC958',N` 与 `IEC958 Playback Switch`** | 本机简单控件名为 **`IEC958',0`** 等（与 **pcm=2/3/4** 对应）；**`Mono: Playback [off]`** 时 PipeWire 仍可能 **RUNNING**、**`speaker-test -D pulse`** 仍跑计数，但 **HDMI 无声**。核对：**`amixer -c0 cget numid=14,20,26`** 或 **`sget 'IEC958',0`**。 |
-
---
-
-## 2. 固化方案：WirePlumber `wireplumber.conf.d`
-
-在 **`~/.config/wireplumber/wireplumber.conf.d/`** 下放片段（**文件名以 `.conf` 结尾**），实现：
-
-1. **强制 `device.profile = pro-audio`**：始终暴露 **Pro / Pro 2 / Pro 3 / Pro 4**（与 `aplay -l` 中 **Port1 / HDMI1/2/3** 对应）。
-2. **`monitor.alsa.rules` 的 `priority.session`**：**`pro-output-2`（1100）高于 `pro-output-0`（1000）**，故 **有外接 HDMI 时**倾向默认 sink 为 **HDMI（pro-output-2）**；**拔出或只用模拟**时回退 **`pro-output-0`**（以本机行为为准）。
-
-仓库内 **示例文件**（可复制到上述目录）：
-
- [`wireplumber/50-kaisa-sof-rt5682-hdmi.conf`](wireplumber/50-kaisa-sof-rt5682-hdmi.conf)
-
-安装命令示例：
-
-```bash
-mkdir -p ~/.config/wireplumber/wireplumber.conf.d
-cp /path/to/chromebox_10th_audio_driver/docs/linux-hdmi/wireplumber/50-kaisa-sof-rt5682-hdmi.conf \
-   ~/.config/wireplumber/wireplumber.conf.d/
-systemctl --user restart wireplumber pipewire pipewire-pulse
-```
-
-**优先级（示例文件内，与「默认 0 / 2」一致）**：**`pro-output-0`（模拟）1000**；**`pro-output-2`（HDMI1）1100**（默认外接声道）；`pro-output-3` **1090**；`pro-output-4` **1095**。多路 HDMI 同时存在时 **仍优先逻辑 HDMI1（pro-output-2）**；若你**固定**使用机箱 **HDMI2/3 物理口**，再把对应 **`pro-output-3`/`4`** 的 **`priority.session` 调到高于 1100**。
-
-**PCI 路径变化**：若 `lspci` 中音频 BDF 不是 **`0000:00:1f.3`**，用以下命令查看实际 **`device.name` / `node.name`** 并替换 conf 中的字符串：
-
-```bash
-pactl list cards
-pactl list short sinks
-```
-
-**WirePlumber 大版本升级**：语法可能变化，见 [WirePlumber migration](https://pipewire.pages.freedesktop.org/wireplumber/daemon/configuration/migration.html)。
-
-### 与系统「声音设置」里输出列表的预期
-
-本文 **`pro-audio` + `monitor.alsa.rules`** 的首要目标是：**在 PipeWire 侧暴露多路 sink**（**`pactl list short sinks`** 中的 **`pro-output-*`**）、配合 **IEC958** 与 **默认 sink / 优先级** 让 HDMI **能出声**、可经 **`pactl set-default-sink`** 或 **`speaker-test -D pulse`** 验证。各**桌面环境**自带的 **「设置 → 声音」** 面板如何枚举输出，取决于其是否把 **`pro-audio` 下的节点**画成易选项、以及 **`pactl list cards`** 里 **声卡「端口」**是否包含 HDMI；在 **`pro-audio`** 下常出现 **仅列出模拟类端口、HDMI 不单独出现在卡端口列表** 的情况，**不等于** HDMI sink 不存在。因此 **「插上 HDMI 后，这一路自动出现在系统声音设置的选择器里」** 不能仅凭本仓库片段保证；若需在图形界面里切换 **`pro-output-*`**，可改用 **Pulse 兼容混音器**、**Patchbay / 节点路由工具** 等（包名因发行版而异；常见可选组件如 **pavucontrol**、**Helvum**），或在终端用 **`wpctl`** 查看与切换。若期望 **插拔与可用性严格对应、并在设置里以「端口」形式出现**，可评估 **UCM / HiFi** 路线（**[`OPERATION_PipeWire_Kaisa_UCM_HiFi.md`](OPERATION_PipeWire_Kaisa_UCM_HiFi.md)**），而非仅 WirePlumber 静态 pro-audio 规则。
-
-### Ubuntu 默认 GNOME vs 启用 pro-audio 之后（避免误解「抢 profile」）
-
-**未按本文修改 WirePlumber 的 Ubuntu 默认态**：声卡活动配置多为 **`stereo-fallback`**（或等价、仅暴露少量 PCM），**GNOME「设置 → 声音」里通常没有**「声卡配置文件 / profile」切换开关，**输出列表往往只有** 3.5mm 模拟（耳机）等 **一两项**。这是因为 **PipeWire/ACP 未切到 pro-audio、未暴露多路 HDMI**，**不是** GNOME 在「主动抢」一个不存在的 pro-audio——**默认下它一般不会去改你没提供的多 profile。**
-
-**按本文启用 pro-audio 之后**（**`pactl list short sinks`** 已有多条 **`pro-output-*`**）：若再在 **GNOME 设置 → 声音** 里用系统「测试扬声器」或反复切换输出，**有可能** 把该卡 **改回 `stereo-fallback` / HiFi**，界面又缩成「**一个 HDMI + 一个 3.5mm**」之类、**像**「自动隐藏」——**这一阶段**才是 **GUI/会话与 profile 回退** 相关现象；**与出厂只有模拟、无开关** 不是同一种情况。
-
-**自检**：动过设置后立刻 **`pactl list cards | grep 活动配置`**（或 **`Active Profile`**）。若 **已非 `pro-audio`**，再 **`pactl set-card-profile … pro-audio`** 或 **`./scripts/apply-kaisa-pro-audio.sh --keep-deb --no-verify`**。若 **仍是 `pro-audio`** 但界面仍少，以 **`pactl list short sinks`** 为准判断是否仍「全开」，勿仅凭 GNOME 列表条数判断。
-
-### 与「无 Jack 就从选择器里删掉」
-
-**与本文 §2 策略存在根本取舍**：
-
- **`device.profile = pro-audio`** 的作用，正是把 **`aplay -l` 里多路 PCM（含 HDMI1/2/3）都变成独立 sink**（**`pro-output-*`**），**一般不随** 某路 **`HDMI/DP,pcm=N` Jack** 关而自动从 PipeWire 里消失；否则也谈不上「多路一次暴露、再调优先级」。
- WirePlumber 文档里虽有 **`node.disabled`**（设为 true 时 **PipeWire 会从节点列表里去掉该 sink**），但 **要匹配「无 Jack」** 需要 **节点属性里存在可随插拔变化的量**，且 **规则在 Jack 变化时会被重新应用**；**仅靠** 仓库里这一条 **静态 `monitor.alsa.rules`**，**不能保证** 对所有机型、所有 PipeWire 版本都实现 **「无 Jack = 选择器里完全没有该项」**。
-
-**若把「按 Jack 隐藏」放在第一位**，可行方向是 **换策略**，而不是把 **`50-kaisa-sof-rt5682-hdmi.conf` 改两行就完事**：
-
-1. **UCM / ACP 端口模型**：用 **端口 availability** 驱动路由（**[`OPERATION_PipeWire_Kaisa_UCM_HiFi.md`](OPERATION_PipeWire_Kaisa_UCM_HiFi.md)**、**[`reference/ucm2/README.md`](../../reference/ucm2/README.md)**）；与 **强制 pro-audio** 互斥，需单独调通 **IEC958**。
-2. **WirePlumber Lua 或自写守护**：监听 **ALSA jack** / 轮询 **`amixer`**，在 **Jack off** 时对对应节点设 **`node.disabled`**（或 **`pw-cli`** 改属性）；**可定制**，但要 **自己维护** 与升级。
-3. **保持本文 §2**：继续 **pro-audio + IEC958**，接受 **选择器里可能仍列出多路**（即便某路 **Jack off**），以 **换线后 `set-default-sink` / `amixer`** 对齐实际出声口。
-
-**结论**：**「无 Jack 就从选择器里删掉」** 与 **「强制 pro-audio 暴露全部 HDMI」** 不能无代价同时成立；要实现前者，**应优先评估 [UCM / HiFi 文档](OPERATION_PipeWire_Kaisa_UCM_HiFi.md) 或自定义策略**，而不是假定 **单靠 `50-*.conf` 静态片段** 即可覆盖。
-
-### 与 UCM / HiFi（可选，互斥）
-
- **本文（ProAudio）**：**`50-kaisa-sof-rt5682-hdmi.conf`**，**禁用** **`60-kaisa-ucm.lua`**，默认 **`pro-output-0` / `pro-output-2`**。
- **UCM 路线**：安装 **`60-kaisa-ucm.lua`** 与 UCM2 overlay，并 **移走** **`50-kaisa-…conf`**。
-
-安装、**`HiFi` profile** 验收、**`alsaucm` vs `pactl`** 排障、**卸载 overlay** 见 **[`OPERATION_PipeWire_Kaisa_UCM_HiFi.md`](OPERATION_PipeWire_Kaisa_UCM_HiFi.md)**。
-
-**不要同时使用**：走 UCM 时须移走或禁用 **50-kaisa**（**`~/.config/...`** 与 **`/etc/wireplumber/...`**），然后 **`systemctl --user restart wireplumber pipewire pipewire-pulse`**。迁移前可 **`./scripts/disable-kaisa-pro-audio-wireplumber.sh`**（可选 **`--system`**）。
-
---
-
-## 3. 验证（仅 pro-audio）
-
-**活动配置** 应为 **`pro-audio`**。若你走 **UCM / HiFi**，本节不适用，验收见 **[`OPERATION_PipeWire_Kaisa_UCM_HiFi.md`](OPERATION_PipeWire_Kaisa_UCM_HiFi.md)**。
-
-```bash
-pactl list cards
-```
-
-```bash
-pactl get-default-sink
-pactl list short sinks
-```
-
-**默认约定（已验证）**：外接 **HDMI（逻辑 HDMI1）** 时，**`pactl get-default-sink`** 宜为 **`…pro-output-2`**，且 **`wpctl inspect @DEFAULT_AUDIO_SINK@`** 中 **`api.alsa.path = "hw:0,2"`**。**仅听模拟** 时宜为 **`…pro-output-0`** / **`hw:0,0`**。
-
-**排障时再核对**：不要仅凭 **`HDMI/DP,pcm=N Jack`** 或某条 **`eld#2.X`** 断定 sink；若 §4.2 中 **`aplay -l`** 该 device 为 **子设备 0/1**，或线缆实际对应 **HDMI2/3**，再依次试 **`pro-output-3` / `pro-output-4`** 及 **`IEC958',1` / `',2`**。
-
-```bash
-wpctl inspect @DEFAULT_AUDIO_SINK@ | grep -E 'api\.alsa\.path|node\.name|alsa\.device'
-```
-
-**出声测试（推荐）**：PipeWire 占用声卡时 **`speaker-test -D plughw:0,2`** 常 **EBUSY (-16)**，属正常。请经 **Pulse 兼容** 设备测试：
-
-```bash
-speaker-test -D pulse -c2 -t sine -f 440 -l 3
-```
-
-或 **`paplay /usr/share/sounds/alsa/Front_Center.wav`**（走**当前默认 sink**；默认 HDMI 时应已指向 **`pro-output-2`**）。
-
-**指定某一路输出（不改默认 sink）**（`SINK` 取自 **`pactl list short sinks`** 第二列）：
-
-```bash
-paplay -d "$SINK" /usr/share/sounds/alsa/Front_Center.wav
-# 例：默认验证 HDMI1
-paplay -d alsa_output.pci-0000_00_1f.3-platform-cml_rt5682_def.pro-output-2 \
-  /usr/share/sounds/alsa/Front_Center.wav
-```
-
-```bash
-pw-play --target alsa_output.pci-0000_00_1f.3-platform-cml_rt5682_def.pro-output-2 \
-  /usr/share/sounds/alsa/Front_Center.wav
-```
-
-```bash
-PULSE_SINK=alsa_output.pci-0000_00_1f.3-platform-cml_rt5682_def.pro-output-2 \
-  speaker-test -D pulse -c2 -t sine -f 440 -l 3
-```
-
-**若 `paplay` 报「排空流失败：超时」、且 `pactl list short sink-inputs` 为空**：该路 sink 可能未能正常完成播放。请 **`pactl set-default-sink`** 指到 **`pro-output-2`**（或 §4.2 子设备正常时的 **3/4**），打开对应 **IEC958**，并用 **`speaker-test -D pipewire`** 复测；同时 **`journalctl --user -u pipewire`** 查 **`set_hw_params` / 输入输出错误**。
-
-**ALSA 直连**（仅在不与 PipeWire 争用同一路时可用，例如已 **`systemctl --user stop pipewire pipewire-pulse wireplumber`** 的排障会话）：
-
-```bash
-speaker-test -D plughw:0,2 -c2 -t sine -f 440 -l 3
-```
-
---
-
-## 4. 可选与兜底
-
- **`api.acp.auto-port = true`**：可在 **同一条 `device` 匹配规则** 的 `update-props` 中尝试（与 **`pro-audio`** / UCM 可能交互）；**先备份 conf**，再 A/B。
- **优先级仍不理想**：可用 **user systemd oneshot**（登录执行 `pactl set-card-profile … pro-audio` + `pactl set-default-sink …`）作次级方案。
-
-### 4.1 重启后又没声
-
-WirePlumber 片段若仍在，常见原因不是片段被删，而是 **活动配置被改回 `stereo-fallback` / HiFi**（多因 **GNOME 设置里操作** 触发，见上节「Ubuntu 默认 GNOME vs 启用 pro-audio 之后」）、**GNOME/会话记住了旧的默认 sink**、**冷启动时 HDMI Jack 尚未就绪**、或 **应用仍指向已不存在的 sink**。
-
-**先快速自检：**
-
-```bash
-pactl list cards | grep -E "名称：alsa_card|活动配置"
-pactl get-default-sink
-pactl list short sinks
-```
-
-若 **活动配置** 回到 **`stereo-fallback`**，检查 **`~/.config/wireplumber/wireplumber.conf.d/50-kaisa-sof-rt5682-hdmi.conf`** 是否仍存在，然后：
-
-```bash
-systemctl --user restart wireplumber pipewire pipewire-pulse
-```
-
-若已是 **`pro-audio`** 但仍无声，可 **手动** 设默认 sink 并开 IEC958（卡名、sink 名以本机为准）。**已验证默认**：HDMI 用 **`pro-output-2`** + **`IEC958',0`**；仅模拟用 **`pro-output-0`**（无需 IEC958）。
-
-```bash
-pactl set-card-profile "$(pactl list cards short | awk '/cml_rt5682/ {print $2; exit}')" pro-audio
-pactl set-default-sink "$(pactl list short sinks | awk '/\\.pro-output-2/ {print $2; exit}')"
-amixer -c0 sset 'IEC958',0 on   # 默认 HDMI1；若走 HDMI2/3 见 §4.2 开 IEC958',1 / ',2
-```
-
-再用 **`speaker-test -D pulse`**（或 **`paplay`**）确认经 PipeWire 的默认 sink 是否有声；**`-D plughw:…`** 在 PipeWire 占用声卡时会出现 **EBUSY (-16)**。
-
-### 4.1b 启动后出现过 pro-audio / 多路输出，随后又自动消失
-
-**首要根因（WirePlumber 0.4 常见）**：会话管理器会把「上次选用的声卡 profile」记在 **`~/.local/state/wireplumber/default-profile`**。若其中对 **`alsa_card…cml_rt5682_def`** 存的是 **`output:stereo-fallback+input:stereo-fallback`**，则 **每次启动 WirePlumber 时会从磁盘恢复该 profile**，往往在 **`50-kaisa` 的 `monitor.alsa.rules` 生效之后仍把卡改回 `stereo-fallback`**，于是 **`pactl list short sinks`** 只剩 **`…stereo-fallback`**，**`pro-output-*` 像「出现一下又没了」**。
-
-**当场核对**：
-
-```bash
-grep cml_rt5682 ~/.local/state/wireplumber/default-profile 2>/dev/null || echo "(无该行)"
-pactl list cards | grep -E "cml_rt5682|活动配置|Active Profile"
-```
-
-**处理**（任选其一）：
-
-1. **一键清状态 + 重载栈**（推荐）：重新执行 **`./scripts/apply-kaisa-pro-audio.sh`**（其中会在 **重启 PipeWire 栈之前** 调用 **`strip-kaisa-default-profile-state.sh`** 删掉上述持久行）。  
-2. **仅清持久行**：**[`scripts/strip-kaisa-default-profile-state.sh`](../../scripts/strip-kaisa-default-profile-state.sh)**，然后 **`systemctl --user restart wireplumber pipewire pipewire-pulse`**，再按 §4.1 手动 **`pactl set-card-profile … pro-audio`**。  
-3. **手工删行**：编辑 **`~/.local/state/wireplumber/default-profile`**，删掉 **含 `cml_rt5682` 的那一行**，再重启用户栈。
-
-**门禁**：**`verify-kaisa-pro-audio.sh`** 若发现 **`default-profile` 里仍是 `cml_rt5682` + `stereo-fallback`** 会直接 **FAIL**，避免误以为基线已稳。
-
-**次要因素**：**GNOME 设置** 在登录后数秒内也可能再 **`set-card-profile`**。在 **已清掉 `default-profile` 脏数据** 之后，若仍偶发，再用登录 **oneshot** 拉两次 profile：
-
-| 文件 | 作用 |
-|------|------|
-| **[`scripts/kaisa-reapply-pro-audio-session.sh`](../../scripts/kaisa-reapply-pro-audio-session.sh)** | 先 **清 `default-profile` 中 cml_rt5682 行**，再 **`pro-audio` / 默认 sink / IEC958**；约 **6 秒后再执行一遍**。 |
-| **[`systemd-user/kaisa-pro-audio-reapply.service`](systemd-user/kaisa-pro-audio-reapply.service)** | **user** oneshot；**`ExecStart=%h/.local/bin/kaisa-reapply-pro-audio-session.sh`**（安装见文件头注释）。 |
-
-**登录自动执行（旧示例）**：[**`systemd-user/kaisa-hdmi-iec958-pipewire.service`**](systemd-user/kaisa-hdmi-iec958-pipewire.service) 仍为占位示例（**需自备** **`ExecStart`**）。**优先**上表 **`kaisa-pro-audio-reapply.service`**。
-
-### 4.1a 换了 HDMI 口，系统里「默认输出」没跟着变，但仍有声
-
-**常见原因**
-
-1. **默认 sink 是「粘住」的**：在 **已有多路 sink** 的前提下，GNOME / 会话会记住 **`pactl get-default-sink`**；WirePlumber 又用 **`priority.session`** 把某一路（示例里是 **`pro-output-2`**）抬成首选。**换线**不等于自动把默认 sink 改到「新插上、Jack 刚亮」的那一路 **`pro-output-3` / `pro-output-4`**。（**默认 Ubuntu 只有一路模拟输出** 时，不存在这种「多 sink 之间粘住」的问题，那是 **未改栈** 时的单一输出模型。）
-2. **出声不一定等于「已切到你心里的那一路」**：声音仍可能从 **当前默认 sink** 对应的那条 **IEC958 / pcm** 出来；若显示器 **多路 HDMI 共用一套喇叭**、或你其实还在听 **模拟口**，会感觉「换口了怎么还有声」。
-3. **画面跟声音可以来自不同逻辑设备**：例如线接到显示器 **HDMI2**，但默认 sink 仍是 **`…pro-output-2`**（逻辑 HDMI1）；部分显示器会把当前选中输入的声音播出来，容易混淆。
-
-**建议自检**
-
-```bash
-pactl get-default-sink
-pactl list short sinks
-pactl list cards
-# 在 cards 输出里看各 HDMI/DP 的 Jack 与 profile，对照 aplay -l 的 pcm 号
-```
-
-**要对齐「物理口 ↔ 默认输出」**：把默认 sink 设到 **Jack=on** 且与当前线一致的那一路，例如（名称以你机器 **`pactl list short sinks`** 为准）：
-
-```bash
-pactl set-default-sink alsa_output.pci-0000_00_1f.3-platform-cml_rt5682_def.pro-output-3
-```
-
-**换插后**：请在 **设置 / pavucontrol** 里重选输出，或 **`pactl set-default-sink`**；若你**固定**用机箱某一 HDMI 口，可在 **`50-kaisa-sof-rt5682-hdmi.conf`** 里把该口对应 **`pro-output-N`** 的 **`priority.session`** 调到 **高于 1100**（见 §2 文末说明）。
-
-### 4.2 IEC958 关闭导致「Pulse 正常、HDMI 无声」
-
-若 **`HDMI/DP,pcm=2 Jack` = on**、默认 sink 为 **`pro-output-2`**，仍无声，检查 **数字输出开关**（本机 **pcm=2** 对应 **`IEC958',0` / `IEC958 Playback Switch` numid=14）：
-
-```bash
-amixer -c0 sget 'IEC958',0
-```
-
-若为 **`[off]`**，执行：
-
-```bash
-amixer -c0 sset 'IEC958',0 on
-```
-
-**pcm=3 / pcm=4** 分别对应 **`IEC958',1`**、**`IEC958',2`**（与 **`pro-output-3` / `pro-output-4`** 对齐）。
-
-**IEC958 已为 on、仍无声，且 `journalctl --user -u pipewire` 出现 `spa.alsa: set_hw_params` / `输入/输出错误`、对应 sink `suspended -> error`**：对照 **`aplay -l`**，若该 HDMI **device** 下一行 **`子设备: 0/1`**（**Subdevices: 0/1**）——左侧 **0** 表示 **ALSA 当前无法打开该 device**，与 **IEC958** 无关。可 **换插另一 HDMI 口**、**`systemctl --user restart wireplumber pipewire pipewire-pulse`** 或 **重启**；勿把默认 sink 锁在 **Jack=on 但子设备为 0** 的那一路。
-
-**另见（UCM 模式）**：若处于 **HiFi / UCM** 且 **`journalctl --user -u wireplumber`** 出现 **`Failed to enable ucm device HDMI*`**，见 **[UCM 文档 §4.4](OPERATION_PipeWire_Kaisa_UCM_HiFi.md)** 与 **[`next.md`](../../next.md)**。纯 **pro-audio** 排障仍以 **`aplay -l` 子设备** 与上文为主。
-
-### 4.3 登录自动恢复（规划中）
-
-**根因**：**`IEC958',0`（pcm=2）被关** → HDMI 无声（PipeWire 可看似正常）；完整 **「切 pro-audio + 默认 HDMI sink + 开 IEC958」** 的**发行级**自动化**尚未**定型（**deb 不作为当前交付**，见文首与 §4.4）。
-
-**当前**：请用 §4.1 / §4.2 **手动命令**；需要登录自启时，自行编写 **user systemd**（可参考 **[`systemd-user/kaisa-hdmi-iec958-pipewire.service`](systemd-user/kaisa-hdmi-iec958-pipewire.service)** 结构，**`ExecStart`** 指向你本机的 shell 片段或脚本）。
-
-### 4.4 Debian 包（未来计划；当前不维护）
-
-**现状**：主线交付为 **`scripts/apply-kaisa-pro-audio.sh`** + 用户级 **`50-kaisa-…conf`**，**不**以 deb 为发布形态；**本节及以下安装/打包说明不作为当前工作项**，仅保留给**将来**若重新启用 **`kaisa-hdmi-pipewire-fix`** 时对照。**若本机曾装过该 deb、只想先卸掉**：**[`scripts/remove-kaisa-hdmi-deb.sh`](../../scripts/remove-kaisa-hdmi-deb.sh)**（`purge` + **`reinstall alsa-ucm-conf`**）。
-
-仓库 **`debian/`** 中曾有原生包 **`kaisa-hdmi-pipewire-fix`**（`Architecture: all`）草稿。若日后恢复构建，在**源码根目录**可执行：
-
-```bash
-./scripts/build-deb.sh
-```
-
-`dpkg-buildpackage` 默认把 **`.deb` / `.changes` / `.buildinfo`** 写到**上一级目录**；本脚本在构建后把 **`kaisa-hdmi-pipewire-fix_*`** 移回**项目根目录**（与根目录 **`.gitignore`** 中的 `*.deb` 等一致），**`chmod 644`**，并把 **`*_all.deb`** 复制到 **`/tmp/`**（供 **`sudo apt install /tmp/…`**，避免家目录权限导致 **`_apt`** 读包报错）。若需沿用默认行为，仍可直接执行 **`dpkg-buildpackage -us -uc -b`**，再到上级目录取 **`kaisa-hdmi-pipewire-fix_<版本>_all.deb`**。
-
-安装示例（在项目根目录先 **`./scripts/build-deb.sh`**；优先用 **`/tmp`** 副本，避免 **`apt`** / **`_apt`** 无法遍历家目录）：
-
-```bash
-sudo apt install /tmp/kaisa-hdmi-pipewire-fix_0.3.0_all.deb
-```
-
-**包内内容（≥0.3.0：仅配置，无 `/usr/bin` 辅助工具）**：
-
- **UCM2**：**`/usr/share/alsa/ucm2/conf.d/sof-rt5682/sof-rt5682.conf`**、**`/usr/share/alsa/ucm2/GoogleKaisa/sof-rt5682/HiFi.conf`**（源码见 **[reference/ucm2/README.md](../../reference/ucm2/README.md)**）；**依赖** **`alsa-ucm-conf`**。
- **WirePlumber**：**`/etc/wireplumber/wireplumber.conf.d/50-kaisa-sof-rt5682-hdmi.conf`**（**系统级**，与 **`~/.config/...`** 二选一即可，勿重复冲突）。**`apt upgrade`** 安装本包新版本时，若该路径在系统上**不存在**（例如已改名为 **`.disabled`**），dpkg **会再次装入**该文件；走 **UCM** 时，升级后请**再移走**或确认仍为 **`.disabled`**。
- **文档**：**`/usr/share/doc/kaisa-hdmi-pipewire-fix/`**（**`README.md.gz`** = UCM 说明；可选打包 **ProAudio / UCM 操作文档**）。
-
-**0.2.x 及更早** 曾附带 **`kaisa-restore-*`** 与 user systemd 单元；**0.3.0** 起移除，直至手工验证与自动化策略定型。
-
-**UCM 优先时**：按 **[`OPERATION_PipeWire_Kaisa_UCM_HiFi.md`](OPERATION_PipeWire_Kaisa_UCM_HiFi.md)** 移走 **`50-kaisa-…`**，避免与 **强制 pro-audio** 叠用。若**未来**恢复 deb 打包，再维护 **`debian/control`**、**`changelog`**、**`copyright`** 等元数据。
-
-**说明**
-
- **更广分发**：可将该 deb 放入自建 **APT 仓库 / PPA**；更长远的修复仍是 **ALSA UCM / 上游** 在适用机型上 **默认打开 IEC958**（与发行版/上游沟通，不在本仓库另文维护）。
-
-### 4.5 基线备份与恢复（Ubuntu 默认 / 大改前）
-
-**目的**：在**做大改**、安装/卸载 **UCM overlay**、或机器上**曾存在**历史 deb **`kaisa-hdmi-pipewire-fix`** 等情况下，把当前机的音频相关路径与诊断**落盘**，并在后续工作中可**尽量恢复**到该状态。
-
-**为何 `reinstall alsa-ucm-conf`**：若曾通过 deb 或手工 overlay 向 **`/usr/share/alsa/ucm2/conf.d/sof-rt5682/`** 写入与 **`alsa-ucm-conf` 同路径**的文件，相当于**覆盖**发行版 vendor 配置。`apt purge kaisa-hdmi-pipewire-fix`（若装过）会移除该包提供的文件，但**稳妥恢复 vendor 内容**仍可执行 **`sudo apt install --reinstall alsa-ucm-conf`**（与基线脚本中的 **`system-overlay.tar.gz`** 二选一通常等价）。
-
-**历史 deb 曾涉及的绝对路径（与 §4.4 存档一致，便于核对）**
-
-| 路径 | 说明 |
-|------|------|
-| `/etc/wireplumber/wireplumber.conf.d/50-kaisa-sof-rt5682-hdmi.conf` | conffile |
-| `/usr/share/alsa/ucm2/conf.d/sof-rt5682/sof-rt5682.conf` | 与 vendor 同路径，purge 后需 reinstall |
-| `/usr/share/alsa/ucm2/GoogleKaisa/sof-rt5682/HiFi.conf` | 本包新增 |
-| （无 **`/usr/bin` 辅助脚本**，≥0.3.0） | 见 §4.4 |
-| `/usr/share/doc/kaisa-hdmi-pipewire-fix/` | 文档（常为 `.gz`） |
-
-**一键采集基线**（默认目录：`audio_topology/baseline-stash/<时间戳>_<hostname>/`，已加入根目录 **`.gitignore`**，避免大块采集误入版本库）：
-
-```bash
-cd /path/to/chromebox_10th_audio_driver
-./scripts/capture-ubuntu-audio-baseline.sh
-```
-
-**一键环境验证（排障前）**：**`./scripts/verify-kaisa-audio-environment.sh`** 在同一会话里汇总 PCI、**`/proc/asound`**、**`aplay`**、**`alsaucm`**、已安装 UCM/Lua、**`pactl`/`wpctl`**、**`amixer`（IEC958/Jack）**、HDMI **ELD**、**`dmesg`** 与 **pipewire/wireplumber** 用户日志片段，末尾输出自动摘要；可选 **`--output FILE`** 保存完整报告。与上文「基线采集」不同：本脚本**不**写入 **`audio_topology/baseline-stash/`**，侧重一次性核对当前机状态。**若用 `sudo ./scripts/verify-…` 跑**：脚本会经 **`sudo -u $SUDO_USER`** 调用 **`pactl`** 与 **`journalctl --user`**（root 进程不能直接占用普通用户的 **`XDG_RUNTIME_DIR`**）；用户 **`~/.config/wireplumber`** 亦按 **`$SUDO_USER` 的家目录** 扫描，避免误读 **`/root/.config`**。
-
-生成文件通常包括：**`manifest.txt`**（dpkg 状态、上表路径是否存在与 sha256）、**`topology.txt`**（调用 `audio_topology/collect_linux_audio_topology.sh` 的完整输出）、**`system-overlay.tar.gz`**（若存在 vendor **`sof-rt5682.conf`** 则备份）、**`user-wireplumber-conf.tar.gz`**（若 `~/.config/wireplumber/wireplumber.conf.d/` 下已有文件名含 kaisa 的片段）。
-
-**一键恢复**（不传参数时使用 **最近**一次基线目录）：
-
-```bash
-./scripts/restore-ubuntu-audio-baseline.sh
-# 或指定目录：
-./scripts/restore-ubuntu-audio-baseline.sh /path/to/audio_topology/baseline-stash/<某次>/
-```
-
-**若曾自建** §4.3 的 **user systemd** 自动执行 **`pactl`/`amixer`**，恢复基线前请先 **`disable --now`** 相应单元，避免登录后仍改 profile。
-
-### 4.6 已验证出声后如何「落盘记录」（备份与 Git 分工）
-
-**目的**：区分「本机可还原的现场」与「仓库里可复现的配置/说明」，避免把大块拓扑采集误提交进 Git。
-
-| 做法 | 内容 | 是否适合进 Git |
-|------|------|------------------|
-| **本机基线** | 运行 **`./scripts/capture-ubuntu-audio-baseline.sh`**，得到 `audio_topology/baseline-stash/<时间戳>_<hostname>/`（含 **`topology.txt`**、**`manifest.txt`** 等） | **通常否**（目录默认在 **`.gitignore`**，体积与隐私不宜入库） |
-| **仓库提交** | 更新 **`OPERATION_PipeWire_Kaisa_ProAudio.md`** / **`OPERATION_PipeWire_Kaisa_UCM_HiFi.md`** / **`REPRO_*.md`**、WirePlumber 源码；在文档中**写一句**当时验证要点（例如 **`pro-audio` + 默认 **`pro-output-0`/`pro-output-2`**、`hw:0,2`）。**`debian/`**：**未来计划**，当前**不**作为常规维护项 | **是** |
-
-**建议在 ProAudio / UCM 文档或提交说明里记一行「事实锚点」**（便于以后对照）：`pactl get-default-sink` 的 sink 名、**`wpctl inspect @DEFAULT_AUDIO_SINK@`** 中的 **`api.alsa.path`**、以及 **`amixer -c0 cget numid=14,20,26`** 中对应 **IEC958** 是否为 on。
-
-**本机最新一次技术验证快照（勿入库）**（主路线为 **pro-audio**，默认 **pro-output-0 / pro-output-2**；含历史上 **Pro 3** 等对照时以 `topology.txt` 为准）：
-
- **当前冻结快照（推荐用于 `./scripts/restore-ubuntu-audio-baseline.sh <目录>`）**  
-  - 基线目录：`audio_topology/baseline-stash/20260408_000644_jack-Kaisa/`  
-  - 采集时间：`2026-04-08T00:06:44+08:00`（以 `manifest.txt` 内 `created_iso` 为准）  
-  - 采集命令：`./scripts/capture-ubuntu-audio-baseline.sh`  
-  - 内容：`manifest.txt`、`topology.txt`、`user-wireplumber-conf.tar.gz`（若存在）等；**目录默认被 `.gitignore` 忽略**，仅在本机磁盘保留  
- **较早快照（仅供参考）**：`audio_topology/baseline-stash/20260407_235227_jack-Kaisa/`（`2026-04-07T23:52:31+08:00`）
- **仓库纳入 UCM2 / WirePlumber Lua 源码后的追加采集**：`audio_topology/baseline-stash/20260408_001125_jack-Kaisa/`（`2026-04-08T00:11:25+08:00` 左右，以 `manifest.txt` 为准）。**在系统上执行 `./scripts/install-kaisa-ucm-overlay.sh` 且 `pactl list cards` 已显示 `HiFi` 后**，请再运行一次 **`capture-ubuntu-audio-baseline.sh`**，用新目录作为「UCM 已生效」的黄金快照。
- 快速锚点（供对照）：`IEC958 numid=14/20/26 = on`；ELD/Jack/默认 sink 等以该基线的 `topology.txt` 与采集时现场为准（建议同时记录 `pactl get-default-sink` 与 `wpctl inspect @DEFAULT_AUDIO_SINK@`）
-
-**本机一次对照（`pro-audio` 下 PipeWire 节点名 ↔ ALSA，以 `wpctl inspect` 为准）**：
-
- **`…pro-output-0`（Pro）**：对应 **`hw:0,0`** / `aplay` 的 **Port1**，即 **3.5mm 模拟输出**（手动验证可正常出声）。
- **`…pro-output-2`（Pro 2）**：对应 **`hw:0,2`** / `aplay` 的 **HDMI1**，**`IEC958',0`**（numid **14**）。
- **`…pro-output-3`（Pro 3）**：对应 **`hw:0,3`** / `aplay` 的 **HDMI2**，**`IEC958',1`**（numid **20**）。
-
-换线、重启或内核/固件变化后，仍以 **`wpctl inspect @DEFAULT_AUDIO_SINK@`** 与 **`aplay -l` 子设备**为准，勿死记编号。
-
---
-
-## 5. 参考链接
-
- [WirePlumber ALSA configuration](https://pipewire.pages.freedesktop.org/wireplumber/daemon/configuration/alsa.html)
- [设备优先级示例（monitor.alsa.rules）](https://danielpower.ca/blog/wireplumber-device-priority)
--- a/docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md
+++ b/docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md
@@ -1,127 +1,202 @@
-# 操作：Kaisa（sof-rt5682）UCM2 + HiFi（可选路线）
+# 操作：Kaisa（sof-rt5682）UCM2 + HiFi（主交付）

-**适用**：与 **[`OPERATION_PipeWire_Kaisa_ProAudio.md`](OPERATION_PipeWire_Kaisa_ProAudio.md)** 相同机型（Google **Kaisa**、PipeWire + WirePlumber、**`sof-rt5682`**）。
+**目标**：在 Google **Kaisa**（Chromebox 10 / `sof-rt5682`）+ Ubuntu + PipeWire + WirePlumber 上，让 **HDMI 只在插入时才作为可选输出出现**（Jack-driven ports），并能稳定出声。

-**本文定位**：在需要 **Jack 驱动端口可用性**、**桌面「端口」模型**（未插线的 HDMI 尽量不表现为随意可选输出）时，使用 **ALSA UCM2** + PipeWire **HiFi** profile，配合 WirePlumber **`60-kaisa-ucm.lua`**。**与强制 pro-audio 的 `50-kaisa-sof-rt5682-hdmi.conf` 互斥**，勿与 ProAudio 主路线同时启用。
+**适用**：PipeWire + WirePlumber（WirePlumber 0.4/0.5 均可），声卡为 `sof-rt5682`。

-**相关**：UCM 源码与目录说明见 **[`reference/ucm2/README.md`](../../reference/ucm2/README.md)**；**IEC958 / `aplay -l` 子设备 / 直连 ALSA 试声** 等通用排障与 **[`OPERATION_PipeWire_Kaisa_ProAudio.md`](OPERATION_PipeWire_Kaisa_ProAudio.md) §4.2** 一致，下文仅补充 **HiFi sink 名** 与 **UCM 特有** 现象。
+**互斥**：本方案与仓库中「强制 pro-audio」的 WirePlumber 片段互斥（例如 `50-kaisa-sof-rt5682-hdmi.conf`）。启用 UCM/HiFi 时必须先禁用/移走 pro-audio 片段。
+
+**相关源码**：UCM2 overlay 与说明见 **[`reference/ucm2/README.md`](../../reference/ucm2/README.md)**。

 ---

-## 1. pro-audio 与 UCM 二选一
+## 1. 方案组成（都与本仓库相关）

-| 路线 | 做法 | 适用 |
-|------|------|------|
-| **pro-audio（主路线）** | **`50-kaisa-sof-rt5682-hdmi.conf`** + **禁用 `60-kaisa-ucm.lua`**；默认 **`pro-output-0` / `pro-output-2`** | 多路 **`pro-output-*`**、已验证基线，见 **[ProAudio](OPERATION_PipeWire_Kaisa_ProAudio.md)** |
-| **UCM / HiFi（本文）** | **`./scripts/install-kaisa-ucm-overlay.sh`**；**移走** **`50-kaisa-…conf`**（历史 **`kaisa-hdmi-pipewire-fix` deb** 若曾安装，见 [ProAudio §4.4](OPERATION_PipeWire_Kaisa_ProAudio.md) **存档**，**当前不维护 deb**） | **Jack 驱动端口**、更接近桌面对「无效口」的处理 |
+| 角色 | 路径 | 作用 |
+|---|---|---|
+| UCM 卡入口 | [`reference/ucm2/conf.d/sof-rt5682/sof-rt5682.conf`](../../reference/ucm2/conf.d/sof-rt5682/sof-rt5682.conf) | 将 UseCase `HiFi` 指向本仓库的 `GoogleKaisa/…/HiFi.conf` |
+| UCM HiFi（Jack + IEC958） | [`reference/ucm2/GoogleKaisa/sof-rt5682/HiFi.conf`](../../reference/ucm2/GoogleKaisa/sof-rt5682/HiFi.conf) | 定义 Port1 + HDMI1/2/3，包含 `JackControl` 与 `IEC958` 开关序列 |
+| WirePlumber 规则 | [`wireplumber/main.lua.d/60-kaisa-ucm.lua`](../../wireplumber/main.lua.d/60-kaisa-ucm.lua) | 对 `sof-rt5682` 启用 `api.alsa.use-ucm`、ACP auto-port，并用 `KAISA_WP_DEVICE_PROFILE` 控制默认 profile |
+| 安装脚本 | [`scripts/disable-kaisa-pro-audio-wireplumber.sh`](../../scripts/disable-kaisa-pro-audio-wireplumber.sh)、[`scripts/install-kaisa-ucm-overlay.sh`](../../scripts/install-kaisa-ucm-overlay.sh) | 禁用 pro-audio 片段、安装 UCM overlay + `60-kaisa-ucm.lua` 到系统路径 |

-**不要同时使用**：启用 **UCM overlay** 时，请 **移走或禁用** **`~/.config/wireplumber/.../50-kaisa-sof-rt5682-hdmi.conf`** 以及 **系统级** **`/etc/wireplumber/...`** 中同类片段（若机器上仍有历史 deb 装入的片段，见 **[ProAudio §4.4](OPERATION_PipeWire_Kaisa_ProAudio.md)** 路径表）。改完后：
+---
+
+## 2. 可复现安装步骤（推荐顺序）
+
+### 2.1 禁用 pro-audio 片段（必须）

 ```bash
-systemctl --user restart wireplumber pipewire pipewire-pulse
+./scripts/disable-kaisa-pro-audio-wireplumber.sh
+# 若你曾在 /etc/wireplumber/ 下也装过 50-kaisa*：
+./scripts/disable-kaisa-pro-audio-wireplumber.sh --system
 ```

-从 **pro-audio 迁到 UCM** 前，可运行 **`./scripts/disable-kaisa-pro-audio-wireplumber.sh`**（及可选 **`--system`**）统一禁用 pro-audio 片段。
-
---
-
-## 2. 验证 UCM 是否在 PipeWire 侧生效
-
-先看 **`pactl list cards`** 的 **「配置文件」** 是否已列出 **`HiFi:`**；若已列出，**活动配置** 宜为 **`HiFi`**，而非长期锁在 **pro-audio**。
-
-若 **`alsaucm -c sof-rt5682 list _verbs` 有 HiFi** 而 **`pactl list cards` 始终没有 `HiFi:`**，说明 **ALSA UCM 可读** 但 **ACP 未注册该 profile**，见下文 **§4 排障**（以本机 **`pactl`** 为准）。
-
-仅在 **`pactl list cards`** 已出现 **`HiFi:`** 时，才可手动切 profile（卡名以 **`pactl list cards short`** 第二列为准）：
+### 2.2 安装 UCM overlay + WirePlumber Lua（需 sudo）

 ```bash
-pactl set-card-profile "$(pactl list cards short | awk '/cml_rt5682/ {print $2; exit}')" HiFi
+./scripts/install-kaisa-ucm-overlay.sh
 ```

-**等价（按整数 profile 序号）**：**`wpctl status`** → **Audio → Devices** 找到 **`sof-rt5682`** 的 **Device id**，再 **`wpctl set-profile <id> <INDEX>`**（**`0` = off**；若仅 **off + pro-audio**，则 **pro-audio** 一般为 **`1`**）。勿用 **MIDI** 等其它对象的 id。
+脚本会把文件安装到：
+
+- `/usr/share/alsa/ucm2/conf.d/sof-rt5682/sof-rt5682.conf`
+- `/usr/share/alsa/ucm2/GoogleKaisa/sof-rt5682/HiFi.conf`
+- `/usr/share/wireplumber/main.lua.d/60-kaisa-ucm.lua`
+
+并在可用时重启用户 PipeWire 栈。

 ---

-## 3. HiFi 下 HDMI 无声（IEC958）
+## 3. 验收（最短闭环）

-与 **[ProAudio §4.2](OPERATION_PipeWire_Kaisa_ProAudio.md)** 根因相同：**`IEC958',N` 为 off** 时界面可选中 **HDMI/DisplayPort** 仍无声音。
-
-**请勿** **`pactl set-card-profile … pro-audio`** 做「恢复」，与 UCM 互斥。应：
-
-1. **`pactl set-default-sink`** 选中外接 HDMI 对应的 **`HiFi__hw_sofrt5682_N__sink`**（或 **`HiFi__hw__0_N__`**，以 **`pactl list short sinks`** 为准）。
-2. 再打开对应 **`IEC958',N`**（**pcm=2→`IEC958',0`**，**pcm=3/4→`IEC958',1`/`',2`**）。
-
-**Kaisa 实机 sink 名**常为 **`HiFi__hw_sofrt5682_N__sink`**（**`N`** 为 **device** 号，**0**=Port1，**2/3/4**=HDMI），与 **`HiFi__hw__0_N__`** 不同。
-
-若 **`IEC958',N` 已为 on**、默认 sink 已是 HDMI 仍无声：检查 **`wpctl`** 静音/音量（**`wpctl set-mute @DEFAULT_AUDIO_SINK@ 0`**、**`wpctl set-volume @DEFAULT_AUDIO_SINK@ 1.0`**）、**物理线是否插在对应 HDMI1/2/3**（与 **`aplay -l`** 里 **device 2/3/4** 一致），以及 **`amixer`** 里 **`HDMI/DP,pcm=N` Jack** 是否为 **on**。
-
-**自动化**：登录后自动 **`set-card-profile` / `set-default-sink` / 开 IEC958** 等**尚未**作为稳定随包工具；若自写 **user systemd**，**勿在 UCM 模式**下执行会强制 **pro-audio** 的命令。**插入 HDMI 时是否弹出输出选择** 由 **桌面/会话** 决定。
-
---
-
-## 4. UCM Jack：思路、安装与验收
-
-**思路**：UCM2 在 **[`reference/ucm2/GoogleKaisa/sof-rt5682/HiFi.conf`](../../reference/ucm2/GoogleKaisa/sof-rt5682/HiFi.conf)** 为 **HDMI1/2/3** 配置 **`JackControl "HDMI/DP,pcm=N Jack"`** 与 **`IEC958`** 开关序列；WirePlumber 通过 **[`wireplumber/main.lua.d/60-kaisa-ucm.lua`](../../wireplumber/main.lua.d/60-kaisa-ucm.lua)** 对 **`sof-rt5682`** 启用 **`api.alsa.use-ucm`**、**`device.profile = "HiFi"`**（并关闭 **`api.acp.auto-profile`**，避免默认抢 **stereo-fallback**），再开 **`api.acp.auto-port`**，让 ACP 按端口可用性暴露路由（**Jack off 时该 HDMI 不对桌面表现为随意可用**）。
-
-**若安装后只剩模拟/耳机、HDMI 全消失**：先看 **`pactl list cards`** 里 **活动配置** 是否为 **`stereo-fallback`**。若是，说明未切到 UCM 的 **`HiFi`**。请 **`sudo cp` 更新后的 `60-kaisa-ucm.lua`** 并 **`systemctl --user restart wireplumber pipewire pipewire-pulse`**。
-
-### 4.1 `alsaucm` 与 `pactl` 不是同一层验收
-
-**`alsaucm -c sof-rt5682 list _verbs` 能列出 `HiFi`**，只说明 **ALSA UCM 配置可被解析**；**PipeWire 是否把该 verb 注册成声卡「配置文件」**，要看 **`pactl list cards`** 里 **「配置文件：」** 下列出的 **名称**（例如 **`off:`**、**`pro-audio:`**、**`HiFi:`**）。若此处 **只有 `off` 与 `pro-audio`、没有 `HiFi:`**，则 **`pactl set-card-profile … HiFi`** 会失败（**「无效参数」** / **「无此实体」**），因为 **对 PipeWire 而言不存在名为 `HiFi` 的 card profile**。
-
-**若 `alsaucm` 正常而 `pactl list cards` 始终没有 `HiFi` profile`**：属于 **spa-acp 未把 UCM HiFi 暴露为 PipeWire 卡配置**。请：
-
-```bash
-journalctl --user -u pipewire -u wireplumber -b --no-pager | grep -iE 'ucm|acp|alsa'
-```
-
-并确认 **`api.alsa.use-ucm = true`**（**`wpctl inspect <device_id>`** 可见）。在此之前，**不要用 `set-card-profile … HiFi` 做硬验收**。
-
-若 **`alsaucm`** 侧就报错，再查 UCM 文件：
+### 3.1 UCM 可解析

 ```bash
 alsaucm -c sof-rt5682 list _verbs
 ```

-若出现 **`parse_verb_file` / `no use case device defined`** 等，说明 **`HiFi.conf` 结构不符合 UCM2 要求**；请 **`git pull`** 后重新执行 **`./scripts/install-kaisa-ucm-overlay.sh`**，再 **`systemctl --user restart wireplumber pipewire pipewire-pulse`**。
+应能列出 `HiFi`（且不应出现 parse 错误）。

-### 4.2 安装（在仓库根目录，需 sudo）
+### 3.2 PipeWire 已注册 `HiFi:` profile

 ```bash
-./scripts/disable-kaisa-pro-audio-wireplumber.sh          # 禁用强制 pro-audio 片段
-# 若曾在 /etc/wireplumber 装过同类片段：
-# ./scripts/disable-kaisa-pro-audio-wireplumber.sh --system
-
-./scripts/install-kaisa-ucm-overlay.sh                     # UCM -> /usr/share/alsa/ucm2/ ，Lua -> /usr/share/wireplumber/main.lua.d/
+pactl list cards
 ```

-### 4.3 验收清单
+在声卡的 **「配置文件：」** 下应能看到 **`HiFi:`**。

-1. **`pactl list cards`**：**「配置文件」** 中若已列出 **`HiFi:`**，则 **活动配置** 宜为 **`HiFi`**；若 **仅有 `off` / `pro-audio`**，则 **尚未** 将 UCM **`HiFi`** 注册为 PipeWire profile，**勿**强行要求 **`set-card-profile … HiFi`** 成功。
-2. **`pactl list short sinks`**：在 **HiFi profile 已存在** 时，宜出现 **`HiFi__…`** 风格 sink；若卡上只有 **pro-audio**，则常见 **`pro-output-*`**（与 UCM Jack 语义不同）。
-3. **插拔 HDMI**：对应 **`HDMI/DP,pcm=N Jack`** on/off 时，GNOME/ACP 下该路 **显示或不可用**（因桌面版本而异）。
-4. **无声排障**：Jack on 仍无声时，仍按 **[ProAudio 文档 §4.2](OPERATION_PipeWire_Kaisa_ProAudio.md)**（**ELD / 子设备 / `set_hw_params`**）；UCM 只管 **Jack 驱动的可用性**。
+若 `pactl` 里已有 `HiFi:`，但活动配置仍不是 `HiFi`，手动切一次：

-### 4.4 PipeWire 日志中的 UCM 设备失败
+```bash
+pactl set-card-profile "$(pactl list cards short | awk '/cml_rt5682/ {print $2; exit}')" HiFi
+```

-若 **`journalctl --user -u wireplumber`** 有 **`Failed to enable ucm device HDMI2`**（或 **HDMI1** / **HDMI3**），且 **`pipewire`** 仅对某 **`HiFi__hw_sofrt5682_N__sink`** 报错，则为 **UCM SectionDevice 启用失败**（与 **`HiFi.conf`** 中 **HDMI1/2/3** 对应 **device 2/3/4** 一致）。宜 **换插另一 HDMI 物理口** 或 **`alsaucm -c sof-rt5682 set _verb HiFi set _device …`** 单独验证；详见 **[`next.md`](../../next.md)**。
+### 3.3 插线才出现 HDMI 输出
+
+插入 HDMI 后：
+
+- GNOME 输出列表应出现 HDMI（例如 `HDMI1`/`HDMI2`），拔出后该项应消失或变为不可用（桌面实现细节可能不同，但应能反映 Jack 可用性）。
+
+### 3.4 出声测试（走 PipeWire）
+
+```bash
+speaker-test -D pulse -c2 -t sine -f 440 -l 3
+```
+
+若你想强制把测试音打到某一路（避免默认 sink 干扰），先取出 sink 名：
+
+```bash
+pactl list short sinks
+```
+
+再指定 sink：
+
+```bash
+paplay -d "$SINK" /usr/share/sounds/alsa/Front_Center.wav
+```

 ---

-## 5. 卸载 / 回退 UCM overlay
+## 4. IEC958 与 device 对照（HiFi 模式）
+
+UCM 的 `HiFi.conf` 约定：
+
+- Port1（模拟）：`hw:0,0`
+- HDMI1：`hw:0,2` 对应 `IEC958',0`（numid=14）
+- HDMI2：`hw:0,3` 对应 `IEC958',1`（numid=20）
+- HDMI3：`hw:0,4` 对应 `IEC958',2`（numid=26）
+
+开关检查（一般建议三路全开，避免误判）：

 ```bash
-sudo apt install --reinstall alsa-ucm-conf   # 恢复 vendor conf.d/sof-rt5682/
+amixer -c0 sget 'IEC958',0; amixer -c0 sget 'IEC958',1; amixer -c0 sget 'IEC958',2
+amixer -c0 sset 'IEC958',0 on
+amixer -c0 sset 'IEC958',1 on
+amixer -c0 sset 'IEC958',2 on
+```
+
+---
+
+## 5. 排障（只覆盖 UCM 主线）
+
+### 5.1 `alsaucm` 有 HiFi，但 `pactl` 没有 `HiFi:`
+
+这是 **ACP 未把 UCM HiFi 注册成 EnumProfile** 的典型表现。优先核对：
+
+- [`reference/ucm2/GoogleKaisa/sof-rt5682/HiFi.conf`](../../reference/ucm2/GoogleKaisa/sof-rt5682/HiFi.conf) 是否包含：
+  - `SectionVerb { Value { TQ "HiFi" } }`
+  - **且不要**在 verb 内使用 `disdevall`
+
+然后重新安装并重启栈：
+
+```bash
+./scripts/install-kaisa-ucm-overlay.sh
+systemctl --user restart wireplumber pipewire pipewire-pulse
+```
+
+仍无时看日志：
+
+```bash
+journalctl --user -u pipewire -u wireplumber -b --no-pager | grep -iE 'ucm|acp|alsa'
+```
+
+### 5.2 `pactl` 有 `HiFi:`，但活动配置卡在 `off`
+
+WirePlumber 的 profile 策略会按设备属性 `device.profile` 在 `EnumProfile` 里匹配同名 profile；若 `60-kaisa-ucm.lua` 强制 `device.profile = "HiFi"` 但 `EnumProfile` 里还没有 `HiFi`，就可能把活动配置留在 `off`。
+
+仓库版 [`wireplumber/main.lua.d/60-kaisa-ucm.lua`](../../wireplumber/main.lua.d/60-kaisa-ucm.lua) 提供变量：
+
+- `KAISA_WP_DEVICE_PROFILE = "pro-audio"`（过渡，避免卡死）
+- `KAISA_WP_DEVICE_PROFILE = "HiFi"`（当 `pactl` 已有 `HiFi:` 后建议切回）
+
+改动后记得重启用户栈：
+
+```bash
+systemctl --user restart wireplumber pipewire pipewire-pulse
+```
+
+### 5.3 `set_hw_params: 输入/输出错误` / `suspended -> error`
+
+这表示 PipeWire 在打开对应 `hw:0,N` 时失败，常见原因：
+
+- **该 device 当前不可用**（例如 `aplay -l` 中某路为 `子设备: 0/1`）
+- HDMI 热插拔/EDID 状态未就绪
+- 你在 PipeWire 运行时尝试对 `hw:0,N` 直连试声导致资源争用与状态混乱
+
+建议检查：
+
+```bash
+aplay -l
+```
+
+并避免在 PipeWire 运行时执行 `speaker-test -D hw:0,N`。若要直连 ALSA 试声，需先停用户栈：
+
+```bash
+systemctl --user stop wireplumber pipewire pipewire-pulse
+speaker-test -D hw:0,3 -c2 -r48000 -t sine
+systemctl --user start pipewire pipewire-pulse wireplumber
+```
+
+---
+
+## 6. 卸载 / 回退 UCM overlay
+
+```bash
+sudo apt install --reinstall alsa-ucm-conf
 sudo rm -f /usr/share/wireplumber/main.lua.d/60-kaisa-ucm.lua
-sudo rm -f /usr/share/wireplumber/main.lua.d/60-kaisa-ucm.lua.disabled   # 若曾改名保留
+sudo rm -f /usr/share/wireplumber/main.lua.d/60-kaisa-ucm.lua.disabled
+systemctl --user restart wireplumber pipewire pipewire-pulse
 ```

-然后 **`systemctl --user restart wireplumber pipewire pipewire-pulse`**。若需回到 **pro-audio**，按 **[ProAudio 文档](OPERATION_PipeWire_Kaisa_ProAudio.md)** 重新启用 **`50-kaisa-sof-rt5682-hdmi.conf`** 并禁用 **`60-kaisa-ucm.lua`**。
-
-**deb 存档路径、基线采集与恢复** 见 **[ProAudio §4.4–§4.5](OPERATION_PipeWire_Kaisa_ProAudio.md)**（**deb 不作为当前交付**）。
-
 ---

-## 6. 参考链接
+## 7. 附录：与 pro-audio（仓库内遗留）互斥关系
+
+若你仍保留或曾启用 `50-kaisa*`（用户级 `~/.config/wireplumber/wireplumber.conf.d/` 或系统级 `/etc/wireplumber/wireplumber.conf.d/`），它可能会强制 profile/优先级，破坏 UCM 的 Jack-driven 端口模型；启用本方案前必须先运行：
+
+```bash
+./scripts/disable-kaisa-pro-audio-wireplumber.sh
+```
+
+仓库仍保留相关 pro-audio 脚本仅供对照与临时排障；仓库主交付以本文为准。

- [WirePlumber ALSA configuration](https://pipewire.pages.freedesktop.org/wireplumber/daemon/configuration/alsa.html)
- **[`reference/ucm2/README.md`](../../reference/ucm2/README.md)**
--- a/docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md
+++ b/docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md
@@ -1,159 +0,0 @@
-# 手顺：与 `kaisa-hdmi-pipewire-fix` deb 等价的 pro-audio 路径（可复现）
-
-**状态（当前）**：**不作为维护中的交付路径**；仓库**放弃 deb 工作**，仅作**未来计划**。本文与下文「打包前」表述保留为**存档**，便于日后若恢复 **`kaisa-hdmi-pipewire-fix`** 时对照。日常请直接用 **`scripts/apply-kaisa-pro-audio.sh`**（见 [ProAudio](OPERATION_PipeWire_Kaisa_ProAudio.md)）。
-
-**目的（存档）**：在真机上**不依赖**写死的 `wpctl set-profile 46 4`，按曾拟定的 deb 交付物复现「WirePlumber 片段 + `pro-audio` + 默认 HDMI sink + IEC958」。
-
-**相关**：deb 存档见 [OPERATION_PipeWire_Kaisa_ProAudio.md](OPERATION_PipeWire_Kaisa_ProAudio.md) §4.4；pro-audio 路径见同文档 §2（复制 `50-kaisa`、重启栈，再 **`pactl set-card-profile … pro-audio`**）。UCM 见 [OPERATION_PipeWire_Kaisa_UCM_HiFi.md](OPERATION_PipeWire_Kaisa_UCM_HiFi.md)。
-
-### 常用检查（sinks / 设备，不依赖 pulseaudio-utils）
-
-| 用途 | 命令 |
-|------|------|
-| **总览**：声卡、**Sinks**（输出）、**Sources**（输入）、默认 sink 标记 `*` | `wpctl status` |
-| 某条 sink 详情（含 `node.name`、`device.profile.name`） | `wpctl inspect <sink 数字 id>`，如 `wpctl inspect @DEFAULT_AUDIO_SINK@` |
-| 若已安装 **pulseaudio-utils** | `pactl list short sinks`、`pactl get-default-sink`、`pactl list cards` |
-
-说明：**Sinks** 前的数字 id **重启栈后会变**，以当次 `wpctl status` 为准；**`wpctl set-default <id>`** 只填 **Sink** 的 id，**不要**与 **Devices**（声卡）混淆。
-
---
-
-## 0. 可选：回到安装 deb / 改配置前的基线
-
-若曾运行过 `capture-ubuntu-audio-baseline.sh`：
-
-```bash
-cd /path/to/chromebox_10th_audio_driver
-./scripts/restore-ubuntu-audio-baseline.sh /path/to/audio_topology/baseline-stash/<某次>/
-```
-
-或仅在本机清掉用户片段后重启栈（自行备份）：
-
-```bash
-mv -f ~/.config/wireplumber/wireplumber.conf.d/50-kaisa-sof-rt5682-hdmi.conf \
-      ~/.config/wireplumber/wireplumber.conf.d/50-kaisa-sof-rt5682-hdmi.conf.disabled 2>/dev/null || true
-systemctl --user restart pipewire pipewire-pulse
-sleep 1
-systemctl --user restart wireplumber
-```
-
---
-
-## 1. 与 deb 一致：安装 WirePlumber 片段
-
-**deb 安装位置**：`/etc/wireplumber/wireplumber.conf.d/50-kaisa-sof-rt5682-hdmi.conf`（需 root）。
-
-**手动复现（二选一）**：
-
-**A. 系统级（与 deb 完全一致）**
-
-```bash
-sudo mkdir -p /etc/wireplumber/wireplumber.conf.d
-sudo cp docs/linux-hdmi/wireplumber/50-kaisa-sof-rt5682-hdmi.conf \
-  /etc/wireplumber/wireplumber.conf.d/
-```
-
-**B. 用户级（与当前调试习惯一致，不 sudo）**
-
-```bash
-mkdir -p ~/.config/wireplumber/wireplumber.conf.d
-cp docs/linux-hdmi/wireplumber/50-kaisa-sof-rt5682-hdmi.conf \
-  ~/.config/wireplumber/wireplumber.conf.d/
-```
-
-若存在**无扩展名**的 `50-kaisa-sof-rt5682-hdmi` 文件，应改名禁用，避免与 `.conf` 重复（见 [ProAudio](OPERATION_PipeWire_Kaisa_ProAudio.md) §2）。
-
---
-
-## 2. 重启 PipeWire 栈（推荐顺序）
-
-与「空 Audio 列表」排障一致：**先 PipeWire，再 WirePlumber**。
-
-```bash
-systemctl --user restart pipewire pipewire-pulse
-sleep 1
-systemctl --user restart wireplumber
-```
-
-再等 1～2 秒。
-
-### 已复制 `50-kaisa-…conf` 但仍只有一条「立体声」sink？
-
-在 **WirePlumber 0.4.x**（Ubuntu 24.04 常见）上，仓库里的 **`monitor.alsa.rules`** 片段**可能不会**自动把卡切到 **pro-audio**，`pactl list cards` 里**活动配置**仍为 **`output:stereo-fallback+input:…`**。这**不代表**片段装错路径，而是**会话管理器版本**与 **0.5+** 行为不同。
-
-**验收与 deb 交付仍成立**：必须再执行下面 §3 的 **`pactl set-card-profile … pro-audio`**。**deb（≥0.3.0）仍包含该 conf**（未来 **0.5+** 或更易合并 drop-in 的环境上可能单独生效）；**不**再随包提供 `kaisa-restore-pipewire-hdmi`，请用本手顺 **`pactl`**/**`amixer`**。
-
---
-
-## 3. 验证：是否已 `pro-audio`（勿写死 46 / 4）
-
-**稳定标识**是 **声卡名** + **profile 名**，不是数字 id。
-
-```bash
-# 若已安装 pulseaudio-utils：
-pactl list cards | grep -A2 'alsa_card.pci-0000_00_1f.3-platform-cml_rt5682_def' -A30
-```
-
-或：
-
-```bash
-wpctl status
-wpctl inspect <Devices 里该卡的 id> | grep -E 'name|profile'
-```
-
-若 **活动配置**仍是 **`stereo-fallback`**，执行：
-
-```bash
-pactl set-card-profile alsa_card.pci-0000_00_1f.3-platform-cml_rt5682_def pro-audio
-```
-
-**实机结论（WirePlumber 0.4.x）**：仅把 **`50-kaisa-…conf`** 放到 **`/etc/wireplumber/...`** 或 **`~/.config/...`** 并重启栈后，**`wpctl status` → Sinks** 往往仍只有一条「立体声」；**执行上列 `pactl set-card-profile … pro-audio` 之后**，才会出现多条 **Pro / Pro 2 / Pro 3 / Pro 4**（或等价 **`pro-output-*`**）。因此 **0.4 验收以本 `pactl` 命令为「多出 sinks」的分界**，而非单靠 conf。
-
-**说明**：**Settings → Default Configured Node Names** 里有时仍出现带 **`stereo-fallback`** 字样的行，以 **`pactl list cards` 中该卡「活动配置」** 与 **`wpctl status` 里 Sinks 条数**为准。
-
-**GUI 试声后 Pro sinks 消失**：（**先分清阶段**：**出厂/默认 Ubuntu** 往往只有 3.5mm 等模拟、设置里 **无 profile 开关**，那是 **栈未暴露 pro-audio**，**不是**「GNOME 在抢 pro-audio」。）在 **已经** 执行过 **`pactl set-card-profile … pro-audio`** 且 **`pactl list short sinks`** 已有多条 **`pro-output-*`** 之后，若在 **GNOME 设置 → 声音** 里用系统自带「测试」或切换输出，**有可能**把声卡**又改回 `stereo-fallback`**，`wpctl status` 里 **Sinks** 会只剩「立体声」——属 **已启用 pro-audio 后** GUI 触发 **profile 回退** 的现象（WirePlumber 0.4 尤甚）。**处理**：再执行一次 **`pactl set-card-profile … pro-audio`** 并按 §4 开 **`IEC958`**；试声优先用终端 **`pw-play` / `paplay`**（见 [ProAudio §2–§3](OPERATION_PipeWire_Kaisa_ProAudio.md) 与 **「Ubuntu 默认 GNOME vs 启用 pro-audio 之后」**）。
-
- **PCI 路径不同**的机器：用 `pactl list cards short` 第二列**实际卡名**替换上面长名。
- **WirePlumber 0.5+** 且片段被正确加载时，有时**无需**再执行 `pactl`，以本步检查结果为准。
- **WirePlumber 0.4.x**：多数情况下**必须**执行本步 `pactl`；见上文「已复制 conf 但仍只有立体声」。
-
---
-
-## 4. 默认 sink + IEC958
-
-**≥0.3.0** 的 deb **不**包含 **`kaisa-restore-pipewire-hdmi`**。请在本机用 **`pactl`**（需 **`pulseaudio-utils`**）完成与 §3 同源的 profile 切换，再 **`pactl set-default-sink`** 指到 **`pro-output-2`**（或当前 Jack 对应 **`pro-output-N`**），并按 [ProAudio §4.2](OPERATION_PipeWire_Kaisa_ProAudio.md) 打开对应 **`IEC958',N`**。
-
-若未安装 **`pulseaudio-utils`**：用 **`wpctl set-profile`** + **`wpctl set-default`**（见 [ProAudio §4.1](OPERATION_PipeWire_Kaisa_ProAudio.md)），再 **`amixer`** 开 IEC958。
-
---
-
-## 5. 验收标准（打包前勾选）
-
-| 检查项 | 命令 / 预期 |
-|--------|-------------|
-| 卡 profile | `pactl list cards` 中该卡 **活动配置** 含 **pro-audio**（或等价描述） |
-| 多 sink | `pactl list short sinks` 或 `wpctl status` 出现 **pro-output-*** 或 **Pro 2/3/4** |
-| 默认输出 | `pactl get-default-sink` 指向 **pro-output-2**（或当前接线对应路） |
-| IEC958 | `amixer -c0 sget 'IEC958'` 对应路为 **on** |
-| 试声 | `pw-play /usr/share/sounds/alsa/Front_Center.wav` 或 `paplay`（走默认 sink） |
-
---
-
-## 6. 手顺小节索引
-
-| 步骤 | 本文 |
-|------|------|
-| 片段 + 清无扩展名 | §1–2 |
-| 重启栈 | §3 |
-| `pactl` / `amixer`（§4） | §4 |
-| 验收 / 试声 | §5 |
-
---
-
-## 7. deb 打包前建议（存档；当前不执行）
-
-若**未来**恢复 **`kaisa-hdmi-pipewire-fix`** 打包，可参考：
-
-1. 在 **目标 Ubuntu 版本**（如 24.04）上按本文 **0→5** 跑通一次。  
-2. 再 **`./scripts/build-deb.sh`** 安装 deb，**重复 §5 验收**（此时片段在 `/etc/wireplumber/...`，仍无随包 `/usr/bin` 工具）。  
-3. 若走 **UCM** 路线，**移走** `50-kaisa-…conf` 后验收（与 [UCM 文档](OPERATION_PipeWire_Kaisa_UCM_HiFi.md)「互斥」一致）。
--- a/docs/linux-hdmi/systemd-user/kaisa-pro-audio-reapply.service
+++ b/docs/linux-hdmi/systemd-user/kaisa-pro-audio-reapply.service
@@ -1,26 +0,0 @@
-# 登录会话：在 pipewire-pulse 就绪后延迟重施 pro-audio，缓解「启动后出现一下又消失」
-# （多为 GNOME/会话稍晚把卡改回 HiFi 或 stereo-fallback）。
-#
-# 安装（示例：脚本放到 ~/.local/bin，避免 unit 里写死仓库路径）：
-#   mkdir -p ~/.local/bin
-#   ln -sf /path/to/chromebox_10th_audio_driver/scripts/kaisa-reapply-pro-audio-session.sh ~/.local/bin/
-#   mkdir -p ~/.config/systemd/user
-#   cp docs/linux-hdmi/systemd-user/kaisa-pro-audio-reapply.service ~/.config/systemd/user/
-#   systemctl --user daemon-reload
-#   systemctl --user enable --now kaisa-pro-audio-reapply.service
-#
-# 与仓库示例 kaisa-hdmi-iec958-pipewire.service 二选一即可；本 unit 自带可执行路径（~/.local/bin）。
-
-[Unit]
-Description=Kaisa: re-apply PipeWire pro-audio after login (mitigate profile revert)
-After=pipewire-pulse.service
-Wants=pipewire-pulse.service
-
-[Service]
-Type=oneshot
-RemainAfterExit=yes
-ExecStartPre=/bin/sleep 2
-ExecStart=%h/.local/bin/kaisa-reapply-pro-audio-session.sh
-
-[Install]
-WantedBy=default.target