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

HISTORY.md

@@ -0,0 +1,83 @@
+# HISTORY（Kaisa 桌面音频：硬件结构与技术路线演进）
+
+本文是**历史记录**：解释我们为什么从早期的 pro-audio 路线迁移到当前的 **UCM2 + HiFi（Jack-driven）**，并把关键事实锚点落盘，避免未来“只剩结论、忘了原因”。
+
+---
+
+## 1. 机型与硬件结构（事实锚点）
+
+- **机型**：Google Kaisa（Chromebox 10）
+- **声卡/驱动**：`sof-rt5682`（`snd_soc_sof_rt5682`）
+- **ALSA 设备号（常见）**：`aplay -l` 会列出 `card 0: sofrt5682`
+  - `device 0`：Port1（模拟/3.5mm）
+  - `device 2/3/4`：HDMI1/HDMI2/HDMI3（iDisp/HDMI 音频）
+
+### 1.1 IEC958 与 HDMI device 对照（本机事实）
+
+在本机验证中，HDMI 数字输出开关与 device 号对齐关系为：
+
+- **pcm=2** → `IEC958',0`（numid=14）
+- **pcm=3** → `IEC958',1`（numid=20）
+- **pcm=4** → `IEC958',2`（numid=26）
+
+检查与打开（建议三路全开，避免误判）：
+
+```bash
+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
+```
+
+---
+
+## 2. 早期路线：PipeWire pro-audio（已弃用）
+
+### 2.1 为什么曾经用 pro-audio
+
+- 默认 profile（如 `stereo-fallback`）往往只暴露极少 sink，HDMI 路由在桌面上很难选。
+- 切到 `pro-audio` 后可以强制把多路 PCM 暴露出来，便于用 `pactl`/`wpctl` 明确选到某一路输出。
+
+### 2.2 为什么最终放弃
+
+在 Kaisa 上，`pro-audio` 路线的核心问题不是“能不能出声”，而是**可维护性与一致性**：
+
+- WirePlumber 的 **default-profile 持久化**会把声卡从 `pro-audio` 顶回 `stereo-fallback`，出现“输出出现一下又消失”的体验，需要反复清状态/重拉 profile。
+- 桌面环境对 `pro-audio` 的端口枚举不稳定：常出现“输出列表项少/不直观”，与我们想要的“插线才显示、按端口可用性选路”目标相冲突。
+
+结论：pro-audio 作为调试手段尚可，但不适合作为交付主线。
+
+---
+
+## 3. 现行路线：UCM2 + HiFi（Jack-driven，主交付）
+
+### 3.1 方案目标
+
+- **HDMI 仅在插入时**出现在桌面输出列表（Jack-driven ports）
+- 使用 PipeWire/ACP 的端口可用性模型，减少“鬼端口/常驻多路输出”的误导
+
+### 3.2 仓库实现（关键文件）
+
+- UCM 入口：`reference/ucm2/conf.d/sof-rt5682/sof-rt5682.conf`
+- HiFi UseCase：`reference/ucm2/GoogleKaisa/sof-rt5682/HiFi.conf`
+  - 每路 HDMI 绑定 `JackControl "HDMI/DP,pcm=N Jack"` + 对应 IEC958 numid 开关序列
+  - 必须包含 `SectionVerb { Value { TQ "HiFi" } }`，且 **verb 内不要使用 `disdevall`**（否则可能导致 PipeWire 侧不注册 `HiFi:` profile）
+- WirePlumber 规则：`wireplumber/main.lua.d/60-kaisa-ucm.lua`
+  - 启用 `api.alsa.use-ucm=true`、`api.acp.auto-port=true`
+  - 用 `KAISA_WP_DEVICE_PROFILE` 控制默认 profile（在 `HiFi:` 未注册前可用 `pro-audio` 过渡，避免卡到 `off`）
+
+安装/卸载/验收步骤以主交付文档为准：
+
+- `docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md`
+
+---
+
+## 4. 关于 “HDMI1/HDMI2 展示名”
+
+桌面里看到的 `HDMI1/HDMI2/...` 文案主要来自：
+
+- UCM `HiFi.conf` 中 `SectionDevice."HDMI1"` / `Comment "HDMI1"` 等定义（端口模型）
+- PipeWire/ACP 根据 UCM 设备与 Jack 可用性生成端口/路由
+
+不同桌面版本的展示可能略有差异，但 **“插入才可用/可选”** 是此路线的核心目标。
+