docs/scripts(kaisa): add doctor verify mode and HDMI readiness checks

Add a more detailed --verify flow to capture Jack/ELD/subdevices, route per sink, and collect kernel error windows. Improve --fix with readiness gating, retries, and connected-only selection; document single-monitor pcm mapping behavior and ignore local logs/artifacts. Made-with: Cursor
2026-04-09 22:26:35 +08:00
parent bda6b60c15
commit 60b7cd389f
14 changed files with 1406 additions and 76 deletions
--- a/docs/INDEX.md
+++ b/docs/INDEX.md
@@ -5,6 +5,9 @@
 | 文档 | 说明 |
 | ---- | ---- |
 | [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、安装 / 验收 / 排障 |
+| [linux-hdmi/DEBUG_Reboot_No_Sound_and_Fix.md](linux-hdmi/DEBUG_Reboot_No_Sound_and_Fix.md) | 排障记录：重启后无声的根因链路（WirePlumber 状态恢复 / `set_hw_params`）与 `--fix` 一键恢复 |
+| [linux-hdmi/LOCAL_Root_Cause_and_Fix.md](linux-hdmi/LOCAL_Root_Cause_and_Fix.md) | **本机判因（替代 Live）**：`kaisa-audio-doctor.sh` 流程、证据表、安装顺序、与 DEBUG 文档衔接 |
+| [linux-hdmi/ROOTCAUSE_Reboot_Silent_Analysis.md](linux-hdmi/ROOTCAUSE_Reboot_Silent_Analysis.md) | **根因深读**：`default-routes` 极低 HDMI 音量（机制 A 实测）与 `set_hw_params`（机制 B）分工 |
 | [README.md](README.md) | 本目录说明 |

 **脚本（仓库根 `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
@@ -5,7 +5,9 @@
 | 文档 | 内容 |
 | ---- | ---- |
 | [linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md](linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md) | **主路线（交付）**：UCM2、HiFi、Jack-driven 端口、IEC958、安装/验收/排障 |
+| [linux-hdmi/DEBUG_Reboot_No_Sound_and_Fix.md](linux-hdmi/DEBUG_Reboot_No_Sound_and_Fix.md) | 排障记录：重启后无声与 `--fix` 恢复的证据与判因路径 |
+| [linux-hdmi/ROOTCAUSE_Reboot_Silent_Analysis.md](linux-hdmi/ROOTCAUSE_Reboot_Silent_Analysis.md) | 根因深读：`default-routes` 极低 HDMI 音量 vs `set_hw_params` |

-附属文件：`linux-hdmi/wireplumber/50-kaisa-sof-rt5682-hdmi.conf`、`linux-hdmi/systemd-user/kaisa-hdmi-iec958-pipewire.service`。
+附属文件：`linux-hdmi/wireplumber/50-kaisa-sof-rt5682-hdmi.conf`、`linux-hdmi/systemd-user/kaisa-hdmi-iec958-pipewire.service`（旧 pro-audio 示例）、**`linux-hdmi/systemd-user/kaisa-ucm-hifi-boot-fix.service`（重启必现无声时登录自动 `--fix`）**。

 仓库根 [README.md](../README.md) · 路径表 [REPO_INDEX.md](../REPO_INDEX.md)。
--- a/docs/linux-hdmi/DEBUG_Reboot_No_Sound_and_Fix.md
+++ b/docs/linux-hdmi/DEBUG_Reboot_No_Sound_and_Fix.md
@@ -0,0 +1,97 @@
+# 排障记录：重启后无声（sof-rt5682 / UCM HiFi）与 `--fix` 恢复
+
+本文把一次已复现的问题“落盘”：**系统重启后没有声音**，但运行仓库脚本的 **`--fix` 模式后恢复有声**。目标是让后续排障有统一的证据与判因路径。
+
+适用：Ubuntu + PipeWire + WirePlumber，声卡为 `sof-rt5682`，并已按主交付文档启用 **UCM2 + HiFi**。
+
+---
+
+## 1. 现象
+
+- **重启后无声**：桌面看起来仍是 HiFi/HDMI，但测试音无声。
+- **运行修复工具后恢复**：执行 `./scripts/kaisa-audio-doctor.sh --fix` 后恢复有声。
+
+---
+
+## 2. 关键结论（根因链路）
+
+该问题至少包含两类机制：
+
+- **机制 A（确定）**：WirePlumber 会在重启后按持久化状态恢复默认路由/默认音量（`~/.local/state/wireplumber/default-nodes`、`default-routes`）。如果恢复到“错误的默认输出”或“极小音量”，就会表现为“无声”。
+  - **本机已量化的一例**：`default-routes` 里 HDMI1 端口的 `channelVolumes` 曾被持久化为约 **0.063**（6% 线性增益），冷启动后等价于「几乎无声」；Port1 仍为 1.0。详见 [ROOTCAUSE_Reboot_Silent_Analysis.md](ROOTCAUSE_Reboot_Silent_Analysis.md)。
+- **机制 B（不稳定点）**：HDMI1（常见为 `pcm=2`）在某些时刻会出现驱动层打开失败（PipeWire 日志出现 `set_hw_params: 输入/输出错误`），即使 **Jack=on / ELD 有效** 也可能无声。
+
+`--fix` 模式之所以能“立刻恢复”，本质是把上述两类状态做了一次“强制收敛”：
+
+- 重启用户音频栈（清理 error 节点与链路）
+- 强制 `HiFi` profile
+- 按 **Jack/ELD** 选择输出（只尝试 Jack=on 的 HDMI）
+- 取消静音、把音量拉到 1.0
+- 打开对应 `IEC958',N`
+- `pw-play` 做最短试播闭环
+
+---
+
+## 3. 如何采集证据（重启后第一时间）
+
+重启后，先不要手工乱改设置，直接跑一次诊断：
+
+```bash
+cd "/home/jack/文档/chromebox_10th_audio_driver"
+./scripts/kaisa-audio-doctor.sh
+```
+
+重点关注这几段输出：
+
+- **WirePlumber state**：
+  - `~/.local/state/wireplumber/default-nodes`
+  - `~/.local/state/wireplumber/default-routes`
+- **HDMI Jack states + ELD controls**：
+  - `HDMI/DP,pcm=2/3/4 Jack` 是否为 on/off
+  - `ELD device=2/3/4` 是否有 bytes（为空通常代表该路未就绪）
+- **PipeWire 日志**：
+  - 是否出现 `set_hw_params: 输入/输出错误`
+
+---
+
+## 4. 一键恢复（可重复执行）
+
+```bash
+cd "/home/jack/文档/chromebox_10th_audio_driver"
+./scripts/kaisa-audio-doctor.sh --fix
+```
+
+说明：
+
+- `--fix` 会尽量只对“确实插线”的 HDMI（Jack=on）尝试输出；若所有 HDMI Jack 都是 off，会回退到 Port1（模拟）。
+- `--fix` 会把音量拉到 1.0 并取消静音，避免“看似路由正确但音量太小”的假无声。
+
+---
+
+## 5. 重启后**必现**无声：自动收敛（可选）
+
+若每次冷启动进桌面后都要手跑 `--fix` 才有声，多半是 **机制 A**（WirePlumber 把默认 sink / 路由恢复到不合适的状态）或 **机制 B**（错误节点需重启栈清空）。可以用登录后 **user systemd oneshot** 自动执行与 `--fix` 相同的逻辑，无需改内核。
+
+1. 仓库已提供：
+   - `scripts/kaisa-audio-boot-fix.sh`（等待 `pactl` 就绪后调用 doctor）
+   - `scripts/kaisa-audio-doctor.sh --fix-only`（只做修复、不写完整诊断报告，适合开机跑）
+2. 单元模板：[systemd-user/kaisa-ucm-hifi-boot-fix.service](systemd-user/kaisa-ucm-hifi-boot-fix.service)（内附 `sed` 安装说明）。
+
+**副作用**：每次登录会 **重启用户 PipeWire 栈一次** 并 **把默认 sink 音量拉到 1.0**（与手动 `--fix` 相同）。若你希望保留「仅诊断、不重启」，不要启用该单元，继续手跑 `./scripts/kaisa-audio-doctor.sh --fix`。
+
+---
+
+## 6. LiveCD 验证如何使用本工具
+
+在 Ubuntu Live 环境中（临时安装 UCM overlay 后），同样可以运行：
+
+```bash
+./scripts/kaisa-audio-doctor.sh
+./scripts/kaisa-audio-doctor.sh --fix
+```
+
+用于判断问题属于：
+
+- **Live 原生就存在**（偏内核/硬件/显示链路/线材），还是
+- **仅安装后出现**（偏 WirePlumber 状态恢复、策略或配置）。
+
--- a/docs/linux-hdmi/LOCAL_Root_Cause_and_Fix.md
+++ b/docs/linux-hdmi/LOCAL_Root_Cause_and_Fix.md
@@ -0,0 +1,135 @@
+# 本机定位根因与修复方案（替代 LiveCD）
+
+LiveCD 未通过或不便使用时，在**已安装的 Ubuntu + PipeWire** 本机上用仓库脚本与下表即可判因；本机可长期保留安装与 WirePlumber 持久化状态，证据比 Live 更完整。
+
+**必读**：主交付步骤见 [OPERATION_PipeWire_Kaisa_UCM_HiFi.md](OPERATION_PipeWire_Kaisa_UCM_HiFi.md)；历史与 IEC958 对照见 [HISTORY.md](../../HISTORY.md)。
+
+---
+
+## 1. 前置条件
+
+- 在**桌面会话**、**普通用户**下操作（**不要** `sudo ./scripts/kaisa-audio-doctor.sh`）。若以 root 运行，`systemctl --user` 会离线，`pactl` 可能无法连接，日志会误报「无声音」。
+- 仓库根目录执行：`./scripts/kaisa-audio-doctor.sh`（可加 `-o ./_logs/my.log` 指定报告路径）。
+
+---
+
+## 2. 判因流程（与计划一致）
+
+```mermaid
+flowchart TD
+  start[本机桌面用户运行 doctor]
+  checkFiles{系统路径 UCM+Lua 存在?}
+  checkUcm{alsaucm 列出 HiFi?}
+  checkPactl{pactl 有 HiFi profile?}
+  branchInstall[安装: disable pro-audio + install overlay]
+  branchUcm[修 UCM: sof-rt5682.conf / HiFi.conf]
+  branchWp[修 WirePlumber: 60-kaisa-ucm.lua 与互斥片段]
+  branchRuntime[运行时: doctor --fix / 查 state / journal]
+  start --> checkFiles
+  checkFiles -->|否| branchInstall
+  checkFiles -->|是| checkUcm
+  checkUcm -->|否| branchUcm
+  checkUcm -->|是| checkPactl
+  checkPactl -->|否| branchWp
+  checkPactl -->|是| branchRuntime
+```
+
+---
+
+## 3. 证据与修复对照表
+
+| 本机证据 | 根因归纳 | 修复方向 |
+|----------|----------|----------|
+| `/usr/share/alsa/ucm2/conf.d/sof-rt5682/sof-rt5682.conf`、`GoogleKaisa/.../HiFi.conf`、`/usr/share/wireplumber/main.lua.d/60-kaisa-ucm.lua` **缺失** | 未安装 overlay（与 Live 仅跑一键未 `--install` 同类） | 见下文 **§4 安装顺序** |
+| `alsaucm -c sof-rt5682` **import/parse 失败** | UCM 语法或入口未指向 `GoogleKaisa/.../HiFi.conf` | 对照仓库 [`reference/ucm2/`](../../reference/ucm2/README.md)；[HISTORY.md](../../HISTORY.md) §3.2：`SectionVerb` + `TQ "HiFi"`、避免 `disdevall` 等导致 PipeWire 不注册 profile |
+| `alsaucm` **有 HiFi**，`pactl list cards` **无 `HiFi:`** | ACP 未走 UCM，或与强制 pro-audio 片段互斥 | [`scripts/disable-kaisa-pro-audio-wireplumber.sh`](../../scripts/disable-kaisa-pro-audio-wireplumber.sh)（必要时 `--system`）；重装 [`scripts/install-kaisa-ucm-overlay.sh`](../../scripts/install-kaisa-ucm-overlay.sh)；`systemctl --user restart wireplumber pipewire pipewire-pulse` |
+| **`HiFi:` 已存在**，但无声 / 切换异常 / journal 有 `set_hw_params: 输入/输出错误` | WirePlumber 恢复的默认路由错误，或某路 HDMI PCM 打开失败 | [DEBUG_Reboot_No_Sound_and_Fix.md](DEBUG_Reboot_No_Sound_and_Fix.md)；**`./scripts/kaisa-audio-doctor.sh --fix`**；仅插一根 HDMI 试 pcm=3/4 再切默认 sink |
+
+---
+
+## 4. 未安装时的推荐安装顺序（本机）
+
+仅在 §3 第一行命中时执行：
+
+```bash
+cd "/path/to/chromebox_10th_audio_driver"
+./scripts/disable-kaisa-pro-audio-wireplumber.sh
+# 若曾在 /etc/wireplumber 装过 kaisa 片段：
+# ./scripts/disable-kaisa-pro-audio-wireplumber.sh --system
+
+./scripts/install-kaisa-ucm-overlay.sh
+# 脚本会在可用时重启用户 PipeWire 栈；否则登录会话后手动：
+# systemctl --user restart wireplumber pipewire pipewire-pulse
+
+./scripts/kaisa-audio-doctor.sh
+```
+
+然后按 [OPERATION](OPERATION_PipeWire_Kaisa_UCM_HiFi.md) §3 验收 `alsaucm` / `pactl list cards`。
+
+---
+
+## 5. HiFi 已生效时的「重启后无声 / HDMI 打开失败」
+
+1. 先读 [DEBUG_Reboot_No_Sound_and_Fix.md](DEBUG_Reboot_No_Sound_and_Fix.md)（机制 A：持久化路由；机制 B：`set_hw_params`），以及 [ROOTCAUSE_Reboot_Silent_Analysis.md](ROOTCAUSE_Reboot_Silent_Analysis.md)（**机制 A 实测**：`default-routes` 里 HDMI 端口 `channelVolumes≈0.06` 导致假无声）。
+2. 查看 `~/.local/state/wireplumber/default-nodes`、`default-routes`（重点 **`grep channelVolumes`**）与 `journalctl --user -u pipewire -b`。
+3. **首选一键恢复**：`./scripts/kaisa-audio-doctor.sh --fix` 在本机实测中**执行后即可恢复正常出声与路由**（重启栈 + 强制 HiFi + 按 Jack 选路 + IEC958 + 试播）；若问题复现，可**重复执行**，不必先改 UCM。
+
+```bash
+./scripts/kaisa-audio-doctor.sh --fix
+```
+
+**重启必现、不想每次手跑**：见 [DEBUG_Reboot_No_Sound_and_Fix.md §5](DEBUG_Reboot_No_Sound_and_Fix.md) — 使用 `scripts/kaisa-audio-boot-fix.sh` + [systemd-user/kaisa-ucm-hifi-boot-fix.service](systemd-user/kaisa-ucm-hifi-boot-fix.service) 在登录后自动执行与 `--fix` 等价的收敛（有音量拉满、重启音频栈等副作用，与手动 `--fix` 相同）。
+
+### 5.1 重要澄清：物理 HDMI 口 ≠ 固定的 ALSA pcm 编号
+
+在 **jack-Kaisa** 上观察到一个容易误判的现象：
+
+- 仅连接 **一个** 显示器时，即使把同一根 HDMI 线插到不同物理口，系统也可能始终表现为 **`pcm=2 Jack=on`**，并在 `pactl list cards` 中显示 **`HDMI/DP,pcm=2` available**。
+- 只有在连接 **两个** 显示器时，才更容易同时出现 `pcm=2` 与 `pcm=3` 两路都 `Jack=on/available`（从而可对比两路的稳定性差异）。
+
+因此，做 A/B 验证时不要用「插 HDMI1 / 插 HDMI2」直接类比为「测试 `pcm=2` / `pcm=3`」；请以 **Jack/ELD 实测**为准：
+
+```bash
+amixer -c0 cget "iface=CARD,name='HDMI/DP,pcm=2 Jack'"
+amixer -c0 cget "iface=CARD,name='HDMI/DP,pcm=3 Jack'"
+amixer -c0 cget "iface=CARD,name='HDMI/DP,pcm=4 Jack'"
+```
+
+（可选）再看 ELD 是否非空：
+
+```bash
+amixer -c0 cget "iface=PCM,name='ELD',device=2"
+amixer -c0 cget "iface=PCM,name='ELD',device=3"
+amixer -c0 cget "iface=PCM,name='ELD',device=4"
+```
+
+`values=on` + `ELD values>0` 的 pcm，才是当前实际连着显示器的输出链路。
+
+---
+
+## 6. 交付物（便于他人复核）
+
+1. `./_logs/kaisa-audio-doctor_*.log`（修复前后各一份更佳）。
+2. 注明命中 §3 中哪一行，以及是否已执行 §4 / §5。
+
+---
+
+## 7. 本仓库所在机器一次实测摘要（2026-04-09）
+
+在 **jack-Kaisa** 上以用户 `jack` 运行 `kaisa-audio-doctor.sh` 的报告见：
+
+- `_logs/kaisa-audio-doctor_local-plan-jack_20260409_130048.log`
+
+**归类**：§3 **第四行**（运行时 / 驱动打开失败），**不是**「未安装」分支。
+
+**依据**：
+
+- 三处系统文件均存在；`alsaucm` 列出 `HiFi`；`pactl` **活动配置为 HiFi**，多路 `HiFi__hw_sofrt5682_*__sink` 已注册。
+- `journalctl` 中 **`HiFi__hw_sofrt5682_2__sink`**（HDMI1 / pcm=2）反复出现 **`set_hw_params: 输入/输出错误`**；默认 sink 曾指向该节点时易表现为无声或节点 `error`。
+- `~/.config/wireplumber/.../50-kaisa-sof-rt5682-hdmi.conf.disabled` 已存在，pro-audio 强制片段已禁用。
+
+**修复结果**：随后执行 **`kaisa-audio-doctor.sh --fix`** 后，**本机实际使用已恢复正常**（与 DEBUG 文档中「`--fix` 可立刻恢复有声」的结论一致）。说明当时问题主要是 **栈内错误节点 / 默认 sink 与 Jack 路由未收敛**，而不是「必须改 UCM 才能好」。
+
+**若日后再次无声**：可再跑 `--fix`；若 journal 仍反复出现某一路 `set_hw_params: 输入/输出错误`，再按 DEBUG 文档做单 HDMI、换口、对照 [HISTORY.md](../../HISTORY.md) IEC958。
+
+`--fix` 运行记录：`_logs/kaisa-audio-doctor_local-plan-jack-fix_20260409_130131.log`。
--- a/docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md
+++ b/docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md
@@ -80,7 +80,7 @@ pactl set-card-profile "$(pactl list cards short | awk '/cml_rt5682/ {print $2;
 ### 3.4 出声测试（走 PipeWire）

 ```bash
-speaker-test -D pulse -c2 -t sine -f 440 -l 3
+speaker-test -D pipewire -c2 -t sine -f 440 -l 3
 ```

 若你想强制把测试音打到某一路（避免默认 sink 干扰），先取出 sink 名：
@@ -177,6 +177,13 @@ speaker-test -D hw:0,3 -c2 -r48000 -t sine
 systemctl --user start pipewire pipewire-pulse wireplumber
 ```

+### 5.4 每次重启进桌面后都要手跑 `--fix` 才有声
+
+多为 WirePlumber 持久化默认路由不当或 PipeWire 残留 error 节点；证据与判因见 [DEBUG_Reboot_No_Sound_and_Fix.md](DEBUG_Reboot_No_Sound_and_Fix.md)。
+
+- **临时**：`./scripts/kaisa-audio-doctor.sh --fix`
+- **自动（接受与 `--fix` 相同副作用：重启用户音频栈、默认 sink 音量拉满）**：按 [DEBUG §5](DEBUG_Reboot_No_Sound_and_Fix.md) 安装 `kaisa-ucm-hifi-boot-fix.service`，使用 [`scripts/kaisa-audio-boot-fix.sh`](../../scripts/kaisa-audio-boot-fix.sh)。
+
 ---

 ## 6. 卸载 / 回退 UCM overlay
@@ -198,5 +205,5 @@ systemctl --user restart wireplumber pipewire pipewire-pulse
 ./scripts/disable-kaisa-pro-audio-wireplumber.sh
 ```

-仓库仍保留相关 pro-audio 脚本仅供对照与临时排障；仓库主交付以本文为准。
+本仓库已收敛为 UCM/HiFi 主线；pro-audio 仅作为概念与历史背景出现在 `HISTORY.md`。

--- a/docs/linux-hdmi/ROOTCAUSE_Reboot_Silent_Analysis.md
+++ b/docs/linux-hdmi/ROOTCAUSE_Reboot_Silent_Analysis.md
@@ -0,0 +1,67 @@
+# 根因分析：重启后「无声」与本机状态对照
+
+本文在已启用 **UCM HiFi** 的前提下，把「重启必现无声 / 手跑 `--fix` 又好」拆成**可验证**的两条链路，并给出比「整栈重启」更轻的验证手段。
+
+---
+
+## 1. 机制 A（本机已证实）：WirePlumber 持久化了**极低的路由音量**
+
+WirePlumber 把每张声卡、每个**输出端口**的 `channelVolumes` 写在：
+
+`~/.local/state/wireplumber/default-routes`
+
+在本机（jack-Kaisa）与历史日志 `kaisa-audio-doctor_local-plan-jack_20260409_130048.log` 中，同一文件里出现：
+
+- **HDMI1**（UCM 端口名在文件里常编码为 `\oOut\c\sHDMI1`）：`channelVolumes=0.062991671264172;0.062991671264172`（约 **6.3%** 线性增益，主观上接近无声）
+- **Port1**：`channelVolumes=1.0;1.0`（正常）
+
+冷启动后 WirePlumber **按该文件恢复**各端口的音量；若当前默认输出或某条路由落在 HDMI1 上，就会表现为 **「路由看起来对、就是没声」**。这与 [DEBUG_Reboot_No_Sound_and_Fix.md](DEBUG_Reboot_No_Sound_and_Fix.md) 中的**机制 A**一致，并把「极小音量」落实为**可 grep 的数字**。
+
+**`--fix` 为何能立刻好**：`kaisa-audio-doctor.sh` 的 `apply_fix` 会对当前默认 sink 执行 `wpctl set-volume @DEFAULT_AUDIO_SINK@ 1.0`，相当于把**当前输出**从持久化的低音量里拉出来；若再配合切到 Jack=on 的 HDMI / 重启栈，就会把「错路由 + 低音量 + error 节点」一并收敛。
+
+**更轻的验证（不必先重启栈）**：
+
+```bash
+grep -n channelVolumes ~/.local/state/wireplumber/default-routes
+wpctl get-volume @DEFAULT_AUDIO_SINK@
+```
+
+若 `default-routes` 里某 HDMI 行 `< 0.2` 而你觉得应该能听见，可先：
+
+```bash
+wpctl set-volume @DEFAULT_AUDIO_SINK@ 1.0
+# 或在声音设置里把对应输出滑条拉高，观察 default-routes 是否被写回合理值
+```
+
+**根因追问（仍开放）**：为何 HDMI1 会被写成 ~0.06？可能是 GNOME/滑条与 WirePlumber 路由音量的交互、某次误触、或显示刻度与存储线性值不一致。**产品侧**可在 deb 文档中建议用户检查该文件；**工程侧**可评估是否在登录后只做「路由音量下限裁剪」而非整栈重启（需单独实现与测试）。
+
+---
+
+## 2. 机制 B（日志已见）：某路 HDMI PCM `set_hw_params` 打开失败
+
+`journalctl --user -u pipewire` 中出现：
+
+- `spa.alsa: set_hw_params: 输入/输出错误`
+- `alsa_output....HiFi__hw_sofrt5682_2__sink`（pcm=2 / HDMI1）`suspended -> error`
+
+即 **驱动/时序层** 在打开 `hw:0,2` 时失败。脚本里已优先尝试 pcm=3/4 再 2（见 `detect_available_pcm` 注释）。这与 DEBUG 中的**机制 B**一致。
+
+**根因追问**：需内核/SOF/HDMI 音频路径上进一步对照（单线插拔、EDID、HWE 小版本），超出用户态 deb 能「根治」的范围。
+
+---
+
+## 3. `default-nodes` 在说什么（辅助理解）
+
+`~/.local/state/wireplumber/default-nodes` 里常见多行 `default.configured.audio.sink.N=...`，表示曾配置过的默认 sink 候选；**当前真正生效的默认 sink** 仍以 `pactl info` / `wpctl status` 为准。机制 A 的「假无声」可以发生在 **default-nodes 指向 Port1，但某应用或路由仍走 HDMI1 且音量为 0.06** 的组合下，因此排查时 **务必看 `default-routes` 里各端口的 channelVolumes**。
+
+---
+
+## 4. 与交付策略的关系
+
+| 手段 | 针对 |
+|------|------|
+| 查 / 清 / 修正 `default-routes` 中的低 `channelVolumes` | **机制 A**（用户态、可文档化） |
+| `--fix` / 登录 oneshot | **A + B** 一并收敛（重、但稳） |
+| 内核/驱动跟进 | **机制 B** 的根本缩小 |
+
+继续「找根本原因」时，建议优先在本机复现一次重启后、无声当下执行 **§1 的 grep**，确认是否仍为 HDMI 某行 `channelVolumes≈0.06`；若是，则**首要根因已落在 WirePlumber 持久化音量**，再决定是否做轻量修复脚本或上游 issue（WirePlumber/GNOME 音量模型）。
--- a/docs/linux-hdmi/systemd-user/kaisa-ucm-hifi-boot-fix.service
+++ b/docs/linux-hdmi/systemd-user/kaisa-ucm-hifi-boot-fix.service
@@ -0,0 +1,24 @@
+# 重启后若「必现无声」，可启用本 user 单元：登录后自动执行与
+# kaisa-audio-doctor.sh --fix 相同的收敛（实际调用 scripts/kaisa-audio-boot-fix.sh）。
+#
+# 安装（把下面 @REPO@ 换成仓库绝对路径，或复制后手工改 ExecStart 一行）：
+#   mkdir -p ~/.config/systemd/user
+#   sed "s|@REPO@|$HOME/文档/chromebox_10th_audio_driver|g" kaisa-ucm-hifi-boot-fix.service > ~/.config/systemd/user/kaisa-ucm-hifi-boot-fix.service
+#   chmod +x .../scripts/kaisa-audio-boot-fix.sh .../scripts/kaisa-audio-doctor.sh
+#   systemctl --user daemon-reload
+#   systemctl --user enable --now kaisa-ucm-hifi-boot-fix.service
+#
+# 日志：~/.local/state/kaisa-audio/last-boot-fix.log（或环境变量 KAISA_BOOT_FIX_LOG）
+#
+[Unit]
+Description=Kaisa sof-rt5682: post-login audio convergence (UCM HiFi, same as doctor --fix)
+After=wireplumber.service pipewire-pulse.service pipewire.service
+Wants=wireplumber.service
+
+[Service]
+Type=oneshot
+RemainAfterExit=yes
+ExecStart=@REPO@/scripts/kaisa-audio-boot-fix.sh
+
+[Install]
+WantedBy=default.target