feat(kaisa): UCM2 Jack-driven HDMI + WirePlumber UCM Lua

Add GoogleKaisa HiFi UCM with JackControl and IEC958 sequences for HDMI1/2/3,
card entry under conf.d/sof-rt5682, and main.lua.d rule to enable UCM/ACP on
sof-rt5682. Add install/disable helper scripts and OPERATION section for
verification; restore pro-audio wireplumber sample under docs.

Made-with: Cursor

docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md

@@ -102,15 +102,40 @@ pactl list short sinks
 
 **自动化（未随 deb 提供）**：登录后自动 **`set-card-profile` / `set-default-sink` / 开 IEC958**、以及 **按 Jack 轮询默认 sink** 等，**尚未**在本仓库验证完毕，**`kaisa-hdmi-pipewire-fix` ≥0.3.0** 仅装 **UCM2 + WirePlumber 片段**。若你自行编写 **user systemd**，勿在 **UCM 模式**下执行会强制 **pro-audio** 的命令。**插入 HDMI 时是否弹出输出选择** 由 **桌面/会话** 决定。
 
+### 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`** / **`api.acp.auto-port`**，让 ACP 按端口可用性暴露路由（**Jack off 时该 HDMI 设备不应对桌面表现为随意可用**）。
+
+**安装（在仓库根目录，需 sudo）**：
+
+```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/
+```
+
+**验收**：
+
+1. **`pactl list cards`**：声卡 **活动配置** 为 **`HiFi`**（或 UCM 定义的 profile），**非**长期锁在 **`pro-audio`**。
+2. **`pactl list short sinks`**：出现 **`HiFi__…`** 风格 sink（名称以本机为准）。
+3. **插拔 HDMI**：对应 **`HDMI/DP,pcm=N Jack`** on/off 时，GNOME/ACP 下该路 **显示或不可用**（具体 UI 表现因桌面版本而异；若仅「灰掉/不可用」亦属常见）。
+4. **无声排障**：若 Jack on 仍无声，仍按本文 **ELD / 子设备 / `set_hw_params`** 段落处理；UCM 只管 **Jack 驱动的可用性**，不保证显示器 OSD/ELD 始终一致。
+
+**卸载/回退 UCM overlay**：**`sudo apt install --reinstall alsa-ucm-conf`** 恢复 vendor **`conf.d/sof-rt5682/`**；并 **`sudo rm -f /usr/share/wireplumber/main.lua.d/60-kaisa-ucm.lua`** 后重启 **`wireplumber`/`pipewire`**。详见 §4.5。
+
 ---
 
 ## 3. 验证
 
+**本节默认针对 §2「pro-audio 对照」路径**；若已按上文 **「UCM Jack：自动显示/隐藏」** 安装 overlay，**活动配置宜为 `HiFi`**，以该节验收表为准。
+
 ```bash
 pactl list cards
 ```
 
-**活动配置** 应为 **`pro-audio`**。
+**活动配置** 应为 **`pro-audio`**（对照实验时）。
 
 ```bash
 pactl get-default-sink
@@ -315,6 +340,7 @@ cd /path/to/chromebox_10th_audio_driver
   - 采集命令：`./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` 为准）**：