Initial commit

2026-04-06 21:59:41 +08:00
commit 760bdf2c9b
28 changed files with 2310 additions and 0 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -0,0 +1,12 @@
+/*.deb
+/*.buildinfo
+/*.changes
+
+# capture-ubuntu-audio-baseline.sh 本地基线（含 topology / tar，体积与隐私不宜入库）
+audio_topology/baseline-stash/
+
+# 本机 sound/soc 等对照 diff（可选放入 reference/chromeos-ubuntu-sound-diffs/）
+reference/chromeos-ubuntu-sound-diffs/diff-u_*.txt
+
+# dh_* 本地缓存（勿提交；可能含旧路径如 kernel-src）
+debian/.debhelper/
--- a/README.md
+++ b/README.md
@@ -0,0 +1,36 @@
+# chromebox_10th_audio_driver
+
+Google **Kaisa**（Chromebox 10）上 **Ubuntu + PipeWire** 的 **HDMI 出声**交付：仓库主线为 **`pro-audio` + IEC958 + WirePlumber 片段**（及可选 **UCM2**），与 **`kaisa-hdmi-pipewire-fix` deb**。**自编内核 / SOF 诊断补丁**与 **`kernel-src/` 大目录**已不随仓库提供；若要做 **ChromiumOS ↔ HWE** 源码对照，在本机 **`apt source linux-hwe-6.17`** 后对两棵树自行 **`diff -u`** / **`diff -rq`**（**`chromiumos_kernel/v5.15`** 与解压的 `linux-hwe-6.17-*`）。
+
+## 文档（仅保留已实机验证路线）
+
+| 你想… | 打开 |
+| ----- | ---- |
+| **操作与排障**（WirePlumber、`50-kaisa-…`、deb、基线脚本） | [docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md](docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md) |
+| **deb 手顺与验收** | [docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md](docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md) |
+| 速查下一步 | [next.md](next.md) |
+| 全仓库路径与脚本表 | [REPO_INDEX.md](REPO_INDEX.md) |
+| UCM2 源码（打入 deb） | [reference/ucm2/README.md](reference/ucm2/README.md) |
+| 拓扑采集脚本 | [audio_topology/COLLECT.md](audio_topology/COLLECT.md) |
+| BMad 菜单码 | [bmad-help.zh-CN.md](bmad-help.zh-CN.md) |
+| 产品需求（若仍用 BMad） | [_bmad-output/planning-artifacts/prd.md](_bmad-output/planning-artifacts/prd.md) |
+
+**仅本文件为根 README**；`docs/` 下不再维护旧版 ChromiumOS/路线图索引。
+
+---
+
+## 现象速览（Kaisa）
+
+| 平台 | HDMI | 3.5mm |
+|------|------|-------|
+| Linux（本仓库目标） | 需 **pro-audio profile** + 正确 **IEC958** / 默认 sink；**`stereo-fallback` 常仅一路** | 一般有（以本机 `aplay -L` 为准） |
+
+细节以 **OPERATION** 为准。
+
+---
+
+## 速链
+
+- **基线**：`scripts/capture-ubuntu-audio-baseline.sh`（装 deb / 大改前）、`scripts/restore-ubuntu-audio-baseline.sh`（回滚）— [OPERATION](docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md) §4.5。
+- **打 deb**：`debian/` + `scripts/build-deb.sh`（**≥0.3.0** 包内为 **UCM2 + WirePlumber 片段**，无随包 shell 工具）。
+- 原始拓扑与 dmesg：`audio_topology/collected/`（`baseline-stash/` 见 `.gitignore`）。
--- a/REPO_INDEX.md
+++ b/REPO_INDEX.md
@@ -0,0 +1,56 @@
+# 全仓库索引（路径速查）
+
+**当前维护文档**以根 [README.md](./README.md) 为准（**OPERATION** / **REPRO** / **next**）。
+
+## 大目录
+
+| 路径 | 说明 |
+| ---- | ---- |
+| [`.cursor/`](./.cursor/) | Cursor 配置，非业务源码 |
+| [`chromiumos_kernel/v5.15/`](./chromiumos_kernel/v5.15/) | 可选对照用 ChromiumOS 5.15 树（浅克隆常见） |
+| [`reference/ucm2/`](./reference/ucm2/) | Kaisa UCM2 overlay；见 [reference/ucm2/README.md](./reference/ucm2/README.md) |
+| [`reference/chromeos-ubuntu-sound-diffs/`](./reference/chromeos-ubuntu-sound-diffs/) | 可选：本机 `diff -u` 生成物目录（见目录内 README） |
+| [`_bmad/`](./_bmad/) | BMad 模块；总表 [`_bmad/_config/bmad-help.csv`](./_bmad/_config/bmad-help.csv) |
+| [`_bmad-output/`](./_bmad-output/) | BMad 生成物（若存在） |
+
+## [`docs/`](./docs/) — 正式文档
+
+| 文件 | 说明 |
+| ---- | ---- |
+| [docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md](./docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md) | PipeWire / deb / 基线 |
+| [docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md](./docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md) | deb 验收手顺 |
+
+## [`audio_topology/`](./audio_topology/)
+
+| 文件 | 说明 |
+| ---- | ---- |
+| [COLLECT.md](./audio_topology/COLLECT.md) | 拓扑采集用法 |
+| [collect_linux_audio_topology.sh](./audio_topology/collect_linux_audio_topology.sh) 等 | 采集脚本 |
+| [`collected/`](./audio_topology/collected/) | 实机 `*.txt` 等原始输出 |
+
+## [`scripts/`](./scripts/) — 脚本
+
+| 脚本 | 说明 |
+| ---- | ---- |
+| [capture-ubuntu-audio-baseline.sh](./scripts/capture-ubuntu-audio-baseline.sh) | 安装 deb / 大改前采集系统音频基线 |
+| [restore-ubuntu-audio-baseline.sh](./scripts/restore-ubuntu-audio-baseline.sh) | 恢复到某次基线 |
+| [build-deb.sh](./scripts/build-deb.sh) | 生成 `kaisa-hdmi-pipewire-fix_*.deb`（**≥0.3.0** 仅 **UCM2 + WirePlumber**，无 `/usr/bin` 辅助脚本） |
+
+BMad 中文帮助表生成：[`_bmad/scripts/render_bmad_help_zh_cn.py`](./_bmad/scripts/render_bmad_help_zh_cn.py) → 根目录 `bmad-help.zh-CN.md`。
+
+## [`debian/`](./debian/)
+
+`kaisa-hdmi-pipewire-fix` 包定义与安装文件。
+
+## 根目录
+
+| 文件 | 说明 |
+| ---- | ---- |
+| [README.md](./README.md) | 仓库说明 |
+| [next.md](./next.md) | 下一步速查 |
+| [help.md](./help.md) | BMad 菜单码 |
+
+## 维护
+
+- 新增说明性文档：放入 **`docs/linux-hdmi/`** 或更新 **OPERATION**。
+- 大目录变更：在本文件补一行。
--- a/_bmad-output/planning-artifacts/epics.md
+++ b/_bmad-output/planning-artifacts/epics.md
@@ -0,0 +1,212 @@
+---
+stepsCompleted:
+  - ce-brownfield-synthesis-2026-04-06
+inputDocuments:
+  - _bmad-output/planning-artifacts/prd.md
+architecturePresent: false
+uxPresent: false
+workflowType: epics
+---
+
+# chromebox_10th_audio_driver — Epic 与 Story 分解
+
+**作者：** Jack  
+**日期：** 2026-04-06  
+**依据：** [prd.md](./prd.md)（含 §3.1 SC↔FR、附录 A）
+
+**说明：** 当前 **`planning-artifacts/`** 下**无** `architecture.md` / UX；本分解**仅追溯 PRD**。若后续补 **[CA]**，可增 Story 或调整验收中的技术约束。
+
+---
+
+## 概览
+
+将 PRD **FR1–FR9** 与 **NFR1–NFR5** 拆为 **4 个 Epic**、**12 个 Story**，便于 **[SP] Sprint Planning** 生成 `sprint-status.yaml`。
+
+---
+
+## 需求清单（摘自 PRD）
+
+### 功能需求（FR）
+
+| ID | 能力 |
+|----|------|
+| FR1 | 文档索引 |
+| FR2 | Linux HDMI 路线图 |
+| FR3 | 内核诊断补丁可追溯 |
+| FR4 | 构建与验证脚本 |
+| FR5 | 桌面 HDMI 操作说明 |
+| FR6 | 登录自动修复（Kaisa） |
+| FR7 | WirePlumber 片段示例 |
+| FR8 | 对照与导出 |
+| FR9 | BMad 规划链 |
+
+### 非功能需求（NFR）
+
+| ID | 类别 |
+|----|------|
+| NFR1 | 文档语言（简体中文） |
+| NFR2 | 可维护性（大目录不提交约定） |
+| NFR3 | 变更粒度（最小 diff） |
+| NFR4 | 安全与权限（user systemd 优先） |
+| NFR5 | 诚实边界（pro-audio 多 Pro N） |
+
+### UX 设计需求
+
+无（CLI/文档为主）。
+
+### FR 覆盖映射
+
+| Epic | 覆盖的 FR | 覆盖的 NFR（横切） |
+|------|-----------|---------------------|
+| E1 文档与入口 | FR1, FR2, FR9 | NFR1, NFR2, NFR3 |
+| E2 内核诊断与构建 | FR3, FR4 | NFR2, NFR3 |
+| E3 桌面 HDMI 用户态 | FR5, FR6, FR7 | NFR1, NFR4, NFR5 |
+| E4 双树与上游材料 | FR8 | NFR2, NFR3 |
+
+---
+
+## Epic 列表
+
+| ID | 标题 | 目标（一句话） |
+|----|------|----------------|
+| **E1** | 文档入口与 HDMI 叙事 | 读者能从 README/INDEX 到达路线图、OPERATION、PRD。 |
+| **E2** | 内核诊断补丁与构建验证 | 单补丁可检、脚本可跑、文档可跟。 |
+| **E3** | Kaisa 桌面 HDMI（PipeWire / IEC958） | 操作说明 + 片段 + 登录自动修复闭环。 |
+| **E4** | ChromeOS ↔ Ubuntu 对照与上游 | diff/export 与文档入口可发现。 |
+
+---
+
+## Epic 1：文档入口与 HDMI 叙事
+
+**目标：** 满足 **SC1** 与 **FR1、FR2、FR9**；新贡献者 10 分钟内找到 Linux HDMI 主线。
+
+### Story 1.1：INDEX 与 OPERATION/REPRO
+
+作为一名**维护者**，  
+我希望 **INDEX.md** 能链到 **OPERATION** 与 **REPRO**，  
+以便 **不必搜全库**（**FR1**）。
+
+**验收标准：**
+
+- **Given** 仓库根已克隆  
+- **When** 打开 `docs/INDEX.md`  
+- **Then** 存在指向 `OPERATION_PipeWire_Kaisa_HDMI.md` 与 `REPRO_Kaisa_Deb_ProAudio_Manual.md` 的条目  
+
+### Story 1.2：（已收敛）路线图
+
+**状态：** **`Linux_HDMI_Audio_Roadmap.md`** 与 **WORK_PROGRESS** 类长文已删除；**FR2** 以 **OPERATION + REPRO** 为事实源。
+
+### Story 1.3：README 与 PRD / BMad 链
+
+作为一名**产品/维护者**，  
+我希望 **根 README** 指向 **PRD** 与（可选）**epics**，  
+以便 **BMad 规划链**可追溯（**FR9**）。
+
+**验收标准：**
+
+- **Given** `README.md` 为唯一根 README  
+- **When** 查看文档入口表  
+- **Then** 存在指向 `_bmad-output/planning-artifacts/prd.md` 的链接  
+- **And** 可增链至本 `epics.md`（建议与 INDEX 中 BMad 表一致）
+
+---
+
+## Epic 2：（已收敛）内核诊断补丁与自编内核
+
+**状态：** 仓库已移除 **`patches/ubuntu-hwe-6.17/`** 与 **`verify-*` / `ubuntu-hwe-617-build.sh`**；原 **SC2 / FR3 / FR4** 故事**作废**。  
+若需本地 HWE 源码与 ChromiumOS 对照，在本机 **`apt source linux-hwe-6.17`** 后设 **`export UB=…`**，见 **`reference/chromeos-ubuntu-sound-diffs/README.md`**。
+
+---
+
+## Epic 3：Kaisa 桌面 HDMI（PipeWire / IEC958）
+
+**目标：** 满足 **SC3** 与 **FR5、FR6、FR7**；与 **NFR4、NFR5** 一致。
+
+### Story 3.1：OPERATION 覆盖 pro-audio / EBUSY / IEC958 / 全自动
+
+作为一名 **Kaisa 用户**，  
+我希望 **OPERATION_PipeWire_Kaisa_HDMI.md** 说明 **pro-audio**、**`speaker-test -D pulse`**、**IEC958',N** 与 **§4.3 安装器**，  
+以便 **排障不靠口口相传**（**FR5**）。
+
+**验收标准：**
+
+- **Given** 用户使用 PipeWire 桌面会话  
+- **When** 按 §3–§4 操作  
+- **Then** 能区分 **plughw EBUSY** 与 **Pulse 路径**；§4.2 含 **IEC958** 根因；§4.3 含 **install** 命令
+
+### Story 3.2：WirePlumber 片段可复制
+
+作为一名 **Kaisa 用户**，  
+我希望 **`50-kaisa-sof-rt5682-hdmi.conf`** 在仓库内完整且与 OPERATION 路径一致，  
+以便 **复制到 `~/.config/wireplumber/...`**（**FR7**）。
+
+**验收标准：**
+
+- **Given** 文件在 `docs/linux-hdmi/wireplumber/`  
+- **When** 按 OPERATION §2 安装  
+- **Then** `device.name` 与优先级说明在文中有「PCI 变化时如何改」提示（**NFR5** 相关）
+
+### Story 3.3：登录自动恢复（user systemd）
+
+作为一名 **Kaisa 用户**，  
+我希望按 **OPERATION §4.3** 配置 **user systemd**（自建 **`pactl`/`amixer`**），且可 **`disable --now`** 停用，  
+以便 **重启后仍能自动恢复 HDMI**（**FR6**，**NFR4**）。
+
+**验收标准：**
+
+- **Given** 用户会话可用 `systemctl --user`  
+- **When** 按 §4.3 自建单元并 **enable**  
+- **Then** 登录后执行恢复；停用时 **disable** 单元且不删 WirePlumber 片段
+
+---
+
+## Epic 4：双树对照与上游材料
+
+**目标：** 满足 **SC4** 与 **FR8**。
+
+### Story 4.1：双树对照说明与可选输出目录
+
+作为一名**上游贡献者**，  
+我希望 **ChromeOS ↔ Ubuntu** 对照方式与 **可选** diff 输出目录在文档中可查，  
+以便 **投递前自证边界**（**FR8**）。
+
+**验收标准：**
+
+- **Given** 根目录 **`REPO_INDEX.md`** 与 **`reference/chromeos-ubuntu-sound-diffs/README.md`**  
+- **When** 查找 sound/soc 对照  
+- **Then** 说明本机两树路径（**`chromiumos_kernel/v5.15`**、`apt source` 解压目录）及 **`diff -u` / `diff -rq`** 用法  
+- **And** 输出目录 **`reference/chromeos-ubuntu-sound-diffs/`** 有 README（生成物可选、默认 gitignore）
+
+### Story 4.2：双树齐全性（可选）
+
+作为一名**维护者**，  
+我在运行 **`diff`** 前自行确认两棵树路径存在，  
+以便 **不误报空 diff**（**FR8** 质量）。
+
+**验收标准：**
+
+- **Given** 未克隆 `chromiumos_kernel` 或未准备 HWE 解压目录  
+- **When** 尝试对照  
+- **Then** 自行补全树后再 `diff`（无仓库级预检脚本）
+
+---
+
+## 横切 NFR 守门（不单独 Epic）
+
+| NFR | 落实方式 |
+|-----|----------|
+| NFR1 | 上述 Story 验收说明与用户文档保持简体中文。 |
+| NFR2 | Story 2.2、4.2 强调大目录不提交与 clone 约定。 |
+| NFR3 | Code review / 自检：无关文件不混入 PR。 |
+| NFR4 | Story 3.3 明确 user 单元，不强制 root alsactl 为唯一方案。 |
+| NFR5 | Story 3.1、3.2 保持 OPERATION 中「多 Pro N」说明。 |
+
+**PRD 附录 A：** 可作为 Epic 1/2 的 **CI 任务** 或发布前 **checklist**。
+
+---
+
+## 后续
+
+- **[SP] Sprint Planning**：由本文件生成 **`implementation-artifacts/sprint-status.yaml`**。  
+- **[CA]**：若补充 **architecture.md**，可在 **E2/E3** 增加「与架构决策 §X 对齐」验收行。  
+- **[GPC]**：重建 **project-context.md** 时可将本 Epic 列表摘要写入。
--- a/_bmad-output/planning-artifacts/prd.md
+++ b/_bmad-output/planning-artifacts/prd.md
@@ -0,0 +1,158 @@
+---
+stepsCompleted:
+  - prd-brownfield-synthesis-2026-04-06
+inputDocuments:
+  - README.md
+  - docs/INDEX.md
+  - docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md
+  - docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md
+workflowType: prd
+brownfield_synthesis: true
+synthesis_note: 棕地仓库；经 [VP] 校验后 [EP] 修订（SC↔FR 映射、可脚本化验收附录）。
+last_edited: '2026-04-06'
+---
+
+# 产品需求文档（PRD）— chromebox_10th_audio_driver
+
+**作者：** Jack  
+**日期：** 2026-04-06  
+**状态：** 基线重建；已按 **`prd-validation-report.md`** 做 [EP] 修订（P2/P4）
+
+**2026-04 文档收敛**：仓库已删除 ChromiumOS 长文、路线图、WORK_PROGRESS 等；**事实与验收**以 **README.md**、**OPERATION_PipeWire_Kaisa_HDMI.md**、**REPRO_Kaisa_Deb_ProAudio_Manual.md** 为准。下文仍出现旧路径处视为历史表述。
+
+---
+
+## 1. 摘要
+
+本「产品」为 **Google Kaisa（Chromebox 10 代 / Coreboot）跨平台音频** 的 **文档、脚本与 deb** 单体仓库，**交付主线**是 **Linux 下 HDMI 可稳定出声**（PipeWire / pro-audio / IEC958）；**自编内核与 SOF 诊断补丁**已不在仓库内维护。保留 **ChromeOS 源码树对照** 与 **拓扑采集**。
+
+**已验证关键用户态根因（Kaisa）**：**`IEC958',0`（pcm=2）关闭**时 PipeWire 可看似正常但 **HDMI 无声**；**打开后即有声**。登录自动恢复见 **OPERATION §4.3**（规划中；当前 **pactl**/**amixer** 手顺）。
+
+---
+
+## 2. 愿景与要解决的问题
+
+| 维度 | 说明 |
+|------|------|
+| **问题** | 同机 **ChromeOS / Windows HDMI 正常**，**Linux** 常 **HDMI 无声或难以选路**；需分层区分 **内核/SOF/IPC** 与 **PipeWire/ALSA 混音器**。 |
+| **愿景** | 维护者可 **可重复** 构建、验证、采集；最终用户（技术门槛较低时）可通过 **安装脚本/未来打包** 获得 **开箱可用** 的 HDMI 音频。 |
+| **非目标** | 不承诺任意 x86 机型通用；**Windows 3.5mm** 等为参考文档，**不**作为 Linux HDMI 的阻塞依赖（与 README 范围一致）。 |
+
+---
+
+## 3. 成功标准（可验收）
+
+1. **文档**：存在 **入口链**（根 README → INDEX → OPERATION/REPRO）；**Linux HDMI** 以用户态路线为主。
+2. **（已移除）内核诊断补丁**：不再作为仓库交付物；需要时自行在本地内核树实验。
+3. **桌面 HDMI（Kaisa）**：文档描述 **WirePlumber `pro-audio`**、**IEC958',N** 根因及 **OPERATION §4.3**（自动化规划中）。
+4. **对照与采集**：**ChromeOS ↔ HWE** 可在本机双树 **`diff`**；**`audio_topology/`** 采集可复现材料。
+
+### 3.1 成功标准与 FR 对应（追溯）
+
+| 成功标准 | 主要支撑的 FR | 说明 |
+|----------|---------------|------|
+| **SC1** 文档入口与分流 | **FR1**、**FR2**、**FR9** | INDEX → OPERATION/REPRO；README 链至本 PRD。 |
+| **SC2**（历史）内核诊断 | — | **已收敛**：仓库不再包含补丁与 verify 脚本。 |
+| **SC3** 桌面 HDMI 可恢复 | **FR5**、**FR6**、**FR7** | OPERATION、WirePlumber 片段、user systemd 说明；与 **NFR4** 一致。 |
+| **SC4** 对照材料可及 | **FR8**、**FR2** | 两棵内核树 + 可选 **`reference/chromeos-ubuntu-sound-diffs/`**；**`audio_topology/`** 采集。 |
+
+---
+
+## 4. 用户旅程（摘要）
+
+| 角色 | 目标 | 主要触点 |
+|------|------|----------|
+| **维护者 / Jack** | 可选内核对照、脚本 | `chromiumos_kernel/`、`scripts/`（HWE 源码树本机自行 `apt source`） |
+| **另一台 Kaisa 用户** | 在 Ubuntu + PipeWire 上让 HDMI 有声 | `OPERATION_PipeWire_Kaisa_HDMI.md`、`50-kaisa-sof-rt5682-hdmi.conf`、deb 内工具 |
+| **上游读者** | IPC/内核对照 | 本地两棵内核树 + 可选 `reference/chromeos-ubuntu-sound-diffs/`（本机 diff 输出） |
+
+---
+
+## 5. 范围
+
+### 5.1 范围内（In）
+
+- Linux：**SOF / iDisp / HDMI** 文档、自编 HWE 内核流程、**诊断补丁**、采集脚本。
+- 桌面：**PipeWire / WirePlumber / IEC958** 操作说明与 **user systemd** 自动恢复（见 OPERATION §4.3）。
+- **INDEX**、代理用 **project-context**（待 **[GPC]** 重建）。
+
+### 5.2 范围外（Out）或低优先级
+
+- 通用 Linux 发行版 **正式包维护**（deb/PPA）列为 **后续**，见 sprint-change-proposal 类叙述；本 PRD **不**要求立即上架商店。
+- **图形化「应用」**（GUI）非当前必须；**CLI/系统服务** 可接受。
+
+---
+
+## 6. 功能需求（FR）— 能力契约
+
+| ID | 能力 | 验收要点 |
+|----|------|----------|
+| **FR1** | **文档索引** | 人读 **INDEX.md** 可到达 **OPERATION**、**REPRO**。 |
+| **FR2** | **Linux HDMI 技术路线** | **OPERATION_PipeWire_Kaisa_HDMI.md** 覆盖 pro-audio / UCM / deb；**REPRO** 为验收手顺。 |
+| **FR5** | **桌面 HDMI 操作说明** | **OPERATION_PipeWire_Kaisa_HDMI.md** 覆盖 **pro-audio**、**plughw EBUSY**、**IEC958 §4.2**、**§4.3 登录自动 restore**。 |
+| **FR6** | **登录自动修复（Kaisa）** | **OPERATION §4.3**：**user systemd** 示例 + 手顺；**deb ≥0.3.0** 不随包提供可执行工具。 |
+| **FR7** | **WirePlumber 片段示例** | **`50-kaisa-sof-rt5682-hdmi.conf`** 可复制到 **`~/.config/wireplumber/...`**。 |
+| **FR8** | **对照与导出** | **ChromeOS ↔ Ubuntu**：本机两树 **`diff`**；可选输出至 **`reference/chromeos-ubuntu-sound-diffs/`**（见该目录 README）。 |
+| **FR9** | **BMad 规划链** | **本 PRD** 与（可选）**architecture / epics** 可链接；**README** 指向 **`_bmad-output/planning-artifacts/prd.md`**。 |
+
+### 附录 A：FR1 可脚本化验收（可选）
+
+在**仓库根**执行；用于 CI 或本地 **`bash -c`** 快速检查**关键文件是否存在**。
+
+**FR1（文档索引链）**
+
+```bash
+test -f docs/INDEX.md
+test -f docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md
+test -f docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md
+grep -q 'OPERATION_PipeWire_Kaisa_HDMI' docs/INDEX.md
+```
+
+---
+
+## 7. 非功能需求（NFR）
+
+| ID | 类别 | 要求 |
+|----|------|------|
+| **NFR1** | **文档语言** | 用户面向说明以 **简体中文** 为主（与 **bmm/config** 一致）。 |
+| **NFR2** | **可维护性** | 大目录（如 `chromiumos_kernel/`、本机 HWE 解压树）**不强制入库**；对照脚本用 **`UB=`** 指向本机路径。 |
+| **NFR3** | **变更粒度** | 代码/脚本以 **最小 diff** 对齐现有风格；避免无关重构。 |
+| **NFR4** | **安全与权限** | 用户态修复以 **`systemctl --user`** 为主；**避免**要求普通用户长期 **root** 改系统 ALSA 全局状态作为唯一路径。 |
+| **NFR5** | **诚实边界** | **`pro-audio`** 下 GNOME 可能 **列出多路 Pro N**；文档说明与 **「仅插线才显示」** 的取舍。 |
+
+---
+
+## 8. 假设与依赖
+
+- **产品简报**：无独立 **Product Brief**；棕地事实源以 **`README.md`** 与 **`docs/linux-hdmi/OPERATION_*.md`** 为准，与本 PRD 并行维护。
+- **硬件**：Google **Kaisa**、**Coreboot**、**sof-rt5682** 类 **PipeWire** 会话。
+- **OS**：文档基准 **Ubuntu 24.04 + linux-hwe-6.17**（具体 **`uname -r`** 以本机为准）。
+- **外部**：**PipeWire/WirePlumber** 大版本升级可能导致片段语法变化（需跟进上游 migration）。
+
+---
+
+## 9. 风险
+
+| 风险 | 缓解 |
+|------|------|
+| 上游 **UCM/默认 IEC958** 未合并，用户仍依赖脚本 | 文档标明 **Phase C**；保留 **install** 路径。 |
+| **PCI 路径变化** | **`restore`** 脚本 **`cml_rt5682` 自动检测**；**WirePlumber** 片段需按机改 **device.name**。 |
+| README 与 OPERATION **编号/补丁集合** 陈旧 | 定期 **[DP]** 扫描或与真机对表。 |
+
+---
+
+## 10. 参考（仓库内）
+
+- [docs/INDEX.md](../../docs/INDEX.md)
+- [docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md](../../docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md)
+- [docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md](../../docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md)
+- [README.md](../../README.md)
+
+---
+
+## 11. 后续 BMad 步骤（可选）
+
+- **[CA]** Create Architecture：若需刷新架构决策文档。  
+- **[CE]** Create Epics and Stories：将 FR 拆为可跟踪 story。  
+- **[GPC]** Generate Project Context：重建 **`_bmad-output/project-context.md`**。  
+- **[VP]**：重大改版后再跑校验；当前 P1–P4 已在 [EP] 中处理。
--- a/_bmad/scripts/render_bmad_help_zh_cn.py
+++ b/_bmad/scripts/render_bmad_help_zh_cn.py
@@ -0,0 +1,306 @@
+#!/usr/bin/env python3
+# 根据 _bmad/_config/bmad-help.csv 与下行中文说明表，生成仓库根目录 bmad-help.zh-CN.md
+from __future__ import annotations
+
+import csv
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parents[2]
+CSV_PATH = REPO / "_bmad" / "_config" / "bmad-help.csv"
+OUT_PATH = REPO / "bmad-help.zh-CN.md"
+
+MODULE_ZH = {
+    "BMad Builder": "BMad 构建器",
+    "BMad Method": "BMad 方法",
+    "Core": "核心",
+    "Creative Intelligence Suite": "创意智能套件（CIS）",
+    "Game Dev Studio": "游戏开发工作室（GDS）",
+    "Test Architecture Enterprise": "测试架构企业版（TEA）",
+    "Web Design Studio": "网页设计工作室（WDS）",
+}
+
+PHASE_ZH = {
+    "anytime": "随时",
+    "1-analysis": "阶段 1 · 分析",
+    "2-planning": "阶段 2 · 规划",
+    "3-solutioning": "阶段 3 · 方案设计",
+    "4-implementation": "阶段 4 · 实现",
+    "0-learning": "阶段 0 · 学习",
+    "1-preproduction": "前期制作",
+    "2-design": "设计",
+    "3-technical": "技术",
+    "4-production": "制作",
+    "gametest": "游戏测试",
+    "0-wds-pitch": "WDS · 宣讲/对齐",
+    "0-wds-agents": "WDS · 唤醒代理",
+    "1-wds-strategy": "WDS · 策略",
+    "2-wds-design": "WDS · 设计",
+    "3-wds-build": "WDS · 构建/验证",
+}
+
+# 与 CSV 行顺序一致（共 114 行），对应「sequence」列的中文说明；空原文由脚本行号对应空序列行
+ZH_BY_ROW = [
+    "通过对话式梳理，创建、编辑或重建 Agent 技能。",
+    "对既有 Agent 做质量分析：结构、内聚、提示词工艺与改进空间。",
+    "安装或更新 BMad Builder 模块配置与帮助条目。",
+    "头脑风暴并规划 BMad 模块：创意、架构与构建计划。",
+    "将模块基础设施脚手架化为可安装的 BMad 模块技能。",
+    "检查模块结构是否完整、准确，且能力均已正确注册。",
+    "创建、编辑或重建工作流或工具型技能。",
+    "对既有工作流/技能做质量分析：结构、效率与改进空间。",
+    "将任意技能转换为符合 BMad 的成果导向形态，并生成前后对比 HTML 报告。",
+    "详细描述需求，由代理按文档最佳实践撰写；可多轮对话并子流程做调研/审阅。",
+    "若发现文档惯例缺失，把你的偏好写入代理记忆中的 documentation-standards.md。",
+    "根据描述生成 Mermaid 图；未指定类型时会建议合适的图类。",
+    "对照文档规范与最佳实践审查指定文档，按优先级给出可执行的改进建议。",
+    "为复杂概念撰写清晰技术说明，附示例与图示。",
+    "专家引导，使用一种或多种技法进行项目头脑风暴。",
+    "确保 PRD、UX、架构与 Epic/Story 彼此对齐。",
+    "故事循环：若有问题退回 DS；通过后进入下一 CS，或 Epic 完成时走 ER。",
+    "在重大变更时纠偏：可能建议重来、更新 PRD、重做架构/冲刺规划或修正 Epic 与 Story。",
+    "引导式产出技术决策文档（架构）。",
+    "在架构文档（CA）之后创建 Epic 与用户故事。",
+    "专家引导完成产品需求文档（PRD）。",
+    "故事循环起点：准备冲刺计划中「下一个」待做 Story，或指定 Epic/Story。",
+    "在开发开始前校验 Story 是否就绪、完整。",
+    "落实 UX 方案；若项目以 UI 为主，强烈建议使用。",
+    "故事循环：执行 Story 实现与测试，经 CR，如需修复回到 DS。",
+    "分析现有项目并产出可用文档。",
+    "行业领域深度研究、专业术语与知识沉淀。",
+    "在通过 PRD 校验流程后，编辑并改进指定路径的 PRD。",
+    "扫描代码库生成精简、面向 LLM 的 project-context.md；棕地项目尤其重要。",
+    "市场、竞品、客户需求与趋势分析。",
+    "引导式厘清产品创意与核心价值。",
+    "为已实现代码生成自动化 API 与 E2E 测试；非代码评审或 Story 校验（请用 CR）。",
+    "统一「意图进、代码出」：澄清、实现、审阅与交付展示。",
+    "可选：在 Epic 结束时回顾成果与经验，规划下一 Epic；重大问题考虑走 CC。",
+    "启动实现阶段：生成实现代理将按序执行的冲刺计划。",
+    "随时总结 Sprint 状态并路由到下一工作流。",
+    "技术可行性、架构选项与实现路径研究。",
+    "在创建 PRD（CP）之后校验 PRD 质量。",
+    "在创意早期或思路卡住时做头脑风暴。",
+    "生成节省 token 的蒸馏文，保留供下游 LLM 使用的关键信息。",
+    "成稿后润色正文表达。",
+    "当文档由多段子流程拼成或结构需加强时，做结构性编辑审阅。",
+    "判断当前所处 BMad 流程位置并回答问题；推荐下一步技能与调用方式。",
+    "在不加载全部文件的前提下为目录生成/更新索引，便于掌握文档地图。",
+    "编排多代理/多视角讨论与协作。",
+    "在定稿前做对抗性质量审查；其他模块的代码审也可自动调用，亦适用于文档。",
+    "与对抗审搭配，从边界场景做正交补充，重方法而非「挑刺态度」。",
+    "当单份文档过大（常为 >500 行）时拆分为可管理片段。",
+    "用一种或多种技法主持头脑风暴会话。",
+    "以同理心驱动的人本设计流程指导。",
+    "识别颠覆机会并设计商业模式创新。",
+    "运用系统化问题解决方法拆解复杂挑战。",
+    "用成熟叙事框架与技巧撰写故事/叙述。",
+    "快速游戏原型，验证机制与创意。",
+    "在游戏语境下主持头脑风暴。",
+    "在投产前确保 GDD、UX、架构与 Epic/Story 对齐。",
+    "对标记为「待评审」的 Story 做干净上下文的 QA 代码审查。",
+    "游戏开发冲刺偏离路线时进行纠偏。",
+    "依据 GDD 需求创建 Epic 与 Story 列表，作为开发规格驱动。",
+    "交互式游戏简报，引导用户明确游戏愿景。",
+    "撰写游戏设计文档 GDD：机制、系统、进度与实现指引。",
+    "为剧情向游戏撰写叙事文档：结构、人物弧与世界观。",
+    "从 GDD 或从零撰写 PRD，供 bmad-assist 等外部工具使用。",
+    "为开发代理准备上下文充分的 Story。",
+    "落实游戏 UX/UI；若 UI 是核心，强烈建议使用。",
+    "执行 Dev Story：按任务与测试实现。",
+    "分析现有游戏项目并产出文档。",
+    "游戏产业领域深度研究与术语沉淀。",
+    "搭建 E2E 测试基础设施脚手架。",
+    "改进并增强既有 PRD。",
+    "产出可伸缩游戏架构：引擎、系统、网络与技术设计。",
+    "生成适配所选智能体工具一致性的 project-context.md。",
+    "游戏市场、竞品与玩家需求分析。",
+    "设计性能测试策略。",
+    "撰写结构化试玩/测试计划。",
+    "兼顾游戏特性的灵活开发流程。",
+    "实验性一体化快捷流：单工作流内完成澄清、计划、实现、审阅与展示。",
+    "小需求、小改动、简单应用/工具，无需冗长规划。",
+    "在游戏开发 Epic 完成后组织团队回顾。",
+    "由 Epic 文件生成或更新 sprint-status.yaml。",
+    "查看冲刺进度、暴露风险并给出下一步行动建议。",
+    "游戏引擎选项与实现路径的技术可行性研究。",
+    "生成自动化游戏测试。",
+    "设计覆盖流程与质量要求的游戏测试场景。",
+    "为 Unity / Unreal / Godot 等项目初始化游戏测试框架架构。",
+    "评审测试质量与覆盖。",
+    "按外部工具兼容标准校验 PRD。",
+    "TEA 学院：通过 7 次课讲授测试基础（含进度与证书相关产出）。",
+    "生成失败用例（TDD 红灯阶段）。",
+    "扩展自动化测试覆盖。",
+    "配置 CI/CD 质量流水线。",
+    "初始化生产级测试框架脚手架。",
+    "非功能需求（NFR）评估。",
+    "基于风险的测试规划。",
+    "质量审计（0–100 分制）。",
+    "覆盖度可追溯与质量门禁决策。",
+    "带设计日志与浏览器验证的迭代「构建—验证」循环。",
+    "干系人共识 pitch 与服务协议；若做自有产品可跳过。",
+    "详细规格前的快速视觉草图探索；直接场景可跳过。",
+    "逐页逐元素记录设计决策，开发可直接据此实现。",
+    "校验规格完整并打包为 DD yaml，供开发交接。",
+    "管理组件库与设计令牌；设计系统模式为「无」时跳过。",
+    "第 3–4 阶段 UX 设计师代理 Freya：检查前置条件并给出下一步。",
+    "从规格抽取可复用模式为组件定义；无设计系统时跳过。",
+    "治理代理 Idun：访谈组织以配置 Agent Space 与权限模型。",
+    "以「人设 + 目标 + 结果」定义用户旅程，并与触发图驱动力关联。",
+    "平台、设备、集成与约束等技术边界；简单落地页可跳过。",
+    "持续改进：反馈 → 触发图 → 规格 → 代码 → 验证。",
+    "定义产品愿景、定位与成功标准，设计决策应可追溯至此。",
+    "第 1–2 阶段战略分析师代理 Saga：扫描仓库并建议下一步。",
+    "跨界面串联用户旅程与入口、过渡、异常路径；简单场景可跳过。",
+    "将业务目标映射到用户心理：人设、功能与驱动力打分。",
+    "在真实用户环境中做可用性测试与回顾式出声思考。",
+    "将规格转为带样式的 HTML 原型，可与 Figma 往返。",
+]
+
+
+def _is_arg_cell(s: str) -> bool:
+    """CSV 部分行在 phase 前插入了 [path] / {-H:...} 等参数列。"""
+    if not s:
+        return False
+    if s == "[path]":
+        return True
+    if s.startswith("{-H") or s.startswith("{--"):
+        return True
+    if s.startswith("{description:"):
+        return True
+    return False
+
+
+def phase_token(r: list[str]) -> str:
+    if r[5]:
+        return r[7] or ""
+    if _is_arg_cell(r[6] or ""):
+        return r[7] or ""
+    return r[6] or ""
+
+
+def phase_display(r: list[str]) -> str:
+    p = phase_token(r)
+    if not p or p in ("true", "false"):
+        return "—"
+    return PHASE_ZH.get(p, p)
+
+
+def prereq_display(r: list[str]) -> str:
+    if r[5]:
+        cand = r[12]
+    elif _is_arg_cell(r[6] or ""):
+        cand = r[8] or ""
+    else:
+        cand = r[7] or ""
+    if not cand or cand in ("true", "false"):
+        return "—"
+    return cand
+
+
+def required_gate(r: list[str]) -> str:
+    if r[5]:
+        return r[13]
+    if _is_arg_cell(r[6] or ""):
+        return r[13]
+    return r[12]
+
+
+def output_display(r: list[str]) -> str:
+    if r[5]:
+        loc, out = r[14], r[15]
+    elif _is_arg_cell(r[6] or ""):
+        loc, out = r[14], r[15]
+    else:
+        loc, out = r[13], r[14]
+    parts = [x.replace("|", " · ") for x in (loc, out) if x]
+    return " / ".join(parts) if parts else "—"
+
+
+def main() -> None:
+    with CSV_PATH.open(newline="", encoding="utf-8") as f:
+        rows = list(csv.reader(f))[1:]
+
+    if len(rows) != len(ZH_BY_ROW):
+        raise SystemExit(f"行数不匹配: CSV {len(rows)} vs ZH {len(ZH_BY_ROW)}")
+
+    by_mod: dict[str, list[list[str]]] = {}
+    for r in rows:
+        by_mod.setdefault(r[0], []).append(r)
+
+    lines: list[str] = [
+        "# BMad 帮助目录（中文版）",
+        "",
+        "本文档由 [`_bmad/_config/bmad-help.csv`](_bmad/_config/bmad-help.csv) 翻译并整理，便于中文读者检索 **菜单码**、**技能** 与用途。",
+        "",
+        "技能调用方式（斜杠命令 / 自然语言等）以本机 `npx bmad-method install` 与 Cursor 集成为准。",
+        "",
+        "## 表列说明",
+        "",
+        "| 列 | 含义 |",
+        "| --- | --- |",
+        "| **码** | 菜单快捷码（不同模块下可能重复，以技能名列区分） |",
+        "| **显示名称** | CSV 英文显示名（与上游一致，便于对照） |",
+        "| **技能** | 技能标识 / 工作流名 |",
+        "| **说明** | 对「sequence」列的中文释义 |",
+        "| **阶段** | 工作流阶段或触发时机（`anytime` 等为随时） |",
+        "| **前置** | 建议先完成的技能或条件（CSV 中错位字段已尽量还原） |",
+        "| **必选** | 是否后期阶段强制项（`true` / `false`） |",
+        "| **产出** | 主要输出位置或产物类型（保留英文路径占位符） |",
+        "",
+        "---",
+        "",
+    ]
+
+    idx = 0
+    for mod in [
+        "BMad Builder",
+        "BMad Method",
+        "Core",
+        "Creative Intelligence Suite",
+        "Game Dev Studio",
+        "Test Architecture Enterprise",
+        "Web Design Studio",
+    ]:
+        mrows = by_mod.get(mod)
+        if not mrows:
+            continue
+        lines.append(f"## {MODULE_ZH.get(mod, mod)}")
+        lines.append("")
+        lines.append(
+            "| 码 | 显示名称 | 技能 | 说明 | 阶段 | 前置 | 必选 | 产出 |"
+        )
+        lines.append("| --- | --- | --- | --- | --- | --- | --- | --- |")
+        for r in mrows:
+            zh = ZH_BY_ROW[idx]
+            idx += 1
+            req = required_gate(r)
+            lines.append(
+                "| {code} | {name} | `{skill}` | {desc} | {phase} | {pre} | {req} | {out} |".format(
+                    code=r[3].replace("|", "\\|"),
+                    name=r[2].replace("|", "\\|"),
+                    skill=r[1].replace("|", "\\|"),
+                    desc=zh.replace("|", "\\|"),
+                    phase=phase_display(r).replace("|", "\\|"),
+                    pre=prereq_display(r).replace("|", "\\|"),
+                    req=req.replace("|", "\\|"),
+                    out=output_display(r).replace("|", "\\|"),
+                )
+            )
+        lines.append("")
+
+    if idx != len(rows):
+        raise SystemExit(f"索引错误: 写了 {idx} 行，预期 {len(rows)}")
+
+    lines.append("---")
+    lines.append("")
+    lines.append(
+        "*生成脚本：[`_bmad/scripts/render_bmad_help_zh_cn.py`](_bmad/scripts/render_bmad_help_zh_cn.py)（修改译文表后重新运行以更新本文档。）*"
+    )
+    lines.append("")
+
+    OUT_PATH.write_text("\n".join(lines), encoding="utf-8")
+    print(f"Wrote {OUT_PATH}")
+
+
+if __name__ == "__main__":
+    main()
--- a/audio_topology/COLLECT.md
+++ b/audio_topology/COLLECT.md
@@ -0,0 +1,34 @@
+# 音频拓扑收集
+
+脚本用于在 **Linux / Windows / ChromeOS** 下导出 `aplay`、`pactl`、`dmesg` 等，输出默认落在 **`audio_topology/collected/`**（可按日期与主机名区分文件）。
+
+## 对外分享与脱敏
+
+采集输出可能含 **hostname、账号** 等；外发或贴 issue 前请自行裁剪。
+
+## 目录结构
+
+- `collect_linux_audio_topology.sh` — Linux
+- `collect_windows_audio_topology.ps1` — Windows
+- `collect_chromeos_audio_topology.sh` — ChromeOS（crosh → shell）
+- `collected/` — 原始输出（`*.txt` 等）
+
+## Linux
+
+```bash
+sudo ./audio_topology/collect_linux_audio_topology.sh
+# 或指定输出文件
+sudo ./audio_topology/collect_linux_audio_topology.sh /path/to/output.txt
+```
+
+## Windows
+
+在 `audio_topology` 下以管理员 PowerShell 运行 `collect_windows_audio_topology.ps1`（可用 `-OutputPath`）。
+
+## ChromeOS
+
+见脚本内注释：crosh → `shell`，将脚本拷至设备执行，默认输出在 `/tmp/`，再拷回本仓库 `collected/`。
+
+## 与当前维护文档的关系
+
+排查 HDMI 用户态路由以 **[docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md](../docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md)** 为准；本目录采集为**辅助证据**，不替代该操作文档。
--- a/audio_topology/collect_linux_audio_topology.sh
+++ b/audio_topology/collect_linux_audio_topology.sh
@@ -0,0 +1,285 @@
+#!/bin/bash
+#
+# Chromebox 10 代 - Linux 音频硬件拓扑收集脚本
+# 用于 C1a 任务：在 Linux 下收集硬件拓扑信息
+#
+# 用法: ./collect_linux_audio_topology.sh [输出文件]
+# 默认输出到: audio_topology/collected/audio_topology_linux_$(hostname)_$(date).txt
+#
+# 建议: 用 sudo 运行以获取 dmesg/journalctl；pactl/wpctl 需图形会话，
+#       若用 sudo 会尝试以 SUDO_USER 身份调用，否则可在桌面终端直接运行
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+OUTPUT_DIR="${SCRIPT_DIR}/collected"
+mkdir -p "$OUTPUT_DIR"
+OUTPUT="${1:-${OUTPUT_DIR}/audio_topology_linux_$(hostname)_$(date +%Y%m%d_%H%M%S).txt}"
+
+TMP_DIR=$(mktemp -d)
+trap "rm -rf $TMP_DIR" EXIT
+
+log() {
+    echo "[$(date +%H:%M:%S)] $*"
+}
+
+section() {
+    echo "" >> "$OUTPUT"
+    echo "========================================" >> "$OUTPUT"
+    echo "### $1" >> "$OUTPUT"
+    echo "========================================" >> "$OUTPUT"
+    echo "" >> "$OUTPUT"
+}
+
+run_cmd() {
+    local desc="$1"
+    shift
+    echo "# $desc" >> "$OUTPUT"
+    echo "\`\`\`" >> "$OUTPUT"
+    if "$@" >> "$OUTPUT" 2>&1; then
+        true
+    else
+        echo "(命令返回非零，可能部分信息缺失)" >> "$OUTPUT"
+    fi
+    echo "\`\`\`" >> "$OUTPUT"
+    echo "" >> "$OUTPUT"
+}
+
+log "开始收集 Linux 音频硬件拓扑..."
+log "输出文件: $OUTPUT"
+
+: > "$OUTPUT"
+echo "# Chromebox 10 代 - Linux 音频硬件拓扑" >> "$OUTPUT"
+echo "# 收集时间: $(date -Iseconds)" >> "$OUTPUT"
+echo "# 主机: $(hostname)" >> "$OUTPUT"
+echo "" >> "$OUTPUT"
+
+# --- 系统信息 ---
+section "系统信息"
+run_cmd "uname -a" uname -a
+run_cmd "内核版本" uname -r
+run_cmd "/proc/version" cat /proc/version
+if command -v alsactl &>/dev/null; then
+    run_cmd "ALSA 版本" alsactl --version 2>/dev/null || echo "alsactl 无版本信息"
+fi
+
+# --- PCI 音频设备 ---
+section "PCI 音频相关设备"
+if command -v lspci &>/dev/null; then
+    run_cmd "lspci -nn | grep -i audio (含设备 ID，便于查驱动/quirks)" bash -c "lspci -nn | grep -i audio || echo '(无匹配)'"
+    run_cmd "lspci | grep -i audio" bash -c "lspci | grep -i audio || echo '(无匹配)'"
+    run_cmd "lspci -v | grep -A 15 -i audio" bash -c "lspci -v 2>/dev/null | grep -A 15 -i audio || echo '(无匹配)'"
+fi
+
+# --- 播放/录音设备列表 ---
+section "ALSA 设备列表"
+if command -v aplay &>/dev/null; then
+    run_cmd "aplay -l (播放设备)" aplay -l
+    run_cmd "aplay -L (ALSA 设备描述)" aplay -L 2>/dev/null || true
+else
+    echo "# aplay 未安装" >> "$OUTPUT"
+fi
+if command -v arecord &>/dev/null; then
+    run_cmd "arecord -l (录音设备)" arecord -l
+fi
+run_cmd "cat /proc/asound/cards" cat /proc/asound/cards
+run_cmd "cat /proc/asound/pcm (PCM 设备明细)" cat /proc/asound/pcm
+
+# --- /proc/asound 目录结构 ---
+section "/proc/asound 目录结构"
+run_cmd "ls -la /proc/asound" ls -la /proc/asound
+for card_dir in /proc/asound/card[0-9]*; do
+    if [ -d "$card_dir" ]; then
+        card=$(basename "$card_dir")
+        echo "# $card 目录内容:" >> "$OUTPUT"
+        echo "\`\`\`" >> "$OUTPUT"
+        ls -la "$card_dir" 2>/dev/null >> "$OUTPUT" || true
+        echo "\`\`\`" >> "$OUTPUT"
+    fi
+done
+
+# --- Codec 信息 (HDA) ---
+section "HDA Codec 信息"
+for codec in /proc/asound/card*/codec*; do
+    if [ -f "$codec" ]; then
+        echo "# $codec" >> "$OUTPUT"
+        echo "\`\`\`" >> "$OUTPUT"
+        cat "$codec" >> "$OUTPUT" 2>/dev/null || echo "(无法读取)" >> "$OUTPUT"
+        echo "\`\`\`" >> "$OUTPUT"
+    fi
+done
+if ! ls /proc/asound/card*/codec* &>/dev/null; then
+    echo "(未找到 codec 文件)" >> "$OUTPUT"
+fi
+
+# --- ELD 内容 (HDMI 显示器音频能力，对 HDMI 无声排查很重要) ---
+section "HDMI ELD 内容"
+for eld in /proc/asound/card*/eld*; do
+    if [ -f "$eld" ]; then
+        echo "# $eld" >> "$OUTPUT"
+        echo "\`\`\`" >> "$OUTPUT"
+        cat "$eld" >> "$OUTPUT" 2>/dev/null || echo "(无法读取，或 ELD 为空/未连接)" >> "$OUTPUT"
+        echo "\`\`\`" >> "$OUTPUT"
+    fi
+done
+
+# --- /sys/class/sound 拓扑 ---
+section "/sys/class/sound 设备"
+if [ -d /sys/class/sound ]; then
+    run_cmd "ls -la /sys/class/sound" ls -la /sys/class/sound
+    for card in /sys/class/sound/card[0-9]*; do
+        if [ -d "$card" ]; then
+            name=$(basename "$card")
+            echo "# $name 设备属性:" >> "$OUTPUT"
+            echo "\`\`\`" >> "$OUTPUT"
+            for f in id number; do
+                if [ -f "$card/$f" ]; then
+                    echo "$f: $(cat "$card/$f" 2>/dev/null)" >> "$OUTPUT"
+                fi
+            done
+            echo "\`\`\`" >> "$OUTPUT"
+        fi
+    done
+fi
+
+# --- 内核日志中的音频相关信息 ---
+section "内核日志 (dmesg) 音频相关"
+echo "# dmesg | grep -iE 'snd|hda|audio|codec|hdmi'" >> "$OUTPUT"
+echo "# 提示: 若此处显示「需要 root」，请用 sudo 重新运行本脚本以获取完整日志" >> "$OUTPUT"
+echo "\`\`\`" >> "$OUTPUT"
+dmesg 2>/dev/null | grep -iE 'snd|hda|audio|codec|hdmi' >> "$OUTPUT" || echo "(需要 root 或 dmesg 不可用)" >> "$OUTPUT"
+echo "\`\`\`" >> "$OUTPUT"
+echo "" >> "$OUTPUT"
+
+# --- Kaisa HDMI / SOF IPC 基线（辅助采集；用户态排障见 docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md）---
+section "SOF / HDMI / IPC 基线 (dmesg)"
+echo "# dmesg | grep -iE 'sof|STREAM_PCM|ipc failed|ipc tx|pcm[0-9]|ASoC|iDisp|hdmi' | tail -120" >> "$OUTPUT"
+echo "# 用于对照 SOF/IPC 与 dmesg；建议 sudo 运行本脚本以读全量 dmesg" >> "$OUTPUT"
+echo "\`\`\`" >> "$OUTPUT"
+dmesg 2>/dev/null | grep -iE 'sof|STREAM_PCM|ipc failed|ipc tx|pcm[0-9]|ASoC|iDisp|hdmi' | tail -120 >> "$OUTPUT" || echo "(需要 root 或 dmesg 不可用)" >> "$OUTPUT"
+echo "\`\`\`" >> "$OUTPUT"
+echo "" >> "$OUTPUT"
+
+section "HDMI 试听命令提示（人工执行）"
+{
+  echo "# 在 aplay -L 中查找 HDMI / DisplayPort 设备后，对每个候选 plughw 试播（Ctrl+C 结束）："
+  echo "#   speaker-test -D plughw:卡号,设备号 -c 2 -l 1"
+  echo "# 若 dmesg 已出现 SOF IPC / PARAMS 类错误，用户态换 sink 通常无法单独修复。"
+} >> "$OUTPUT"
+echo "" >> "$OUTPUT"
+
+# --- 可选: journalctl 内核日志 (补充 dmesg，含启动后日志) ---
+section "journalctl 内核日志 (SOF/音频，可选补充)"
+if command -v journalctl &>/dev/null; then
+    echo "# journalctl -b -k --no-pager | grep -iE 'sof|snd|hda|audio|hdmi' | tail -80" >> "$OUTPUT"
+    echo "\`\`\`" >> "$OUTPUT"
+    journalctl -b -k --no-pager 2>/dev/null | grep -iE 'sof|snd|hda|audio|hdmi' | tail -80 >> "$OUTPUT" || echo "(journalctl 需 root 或不可用)" >> "$OUTPUT"
+    echo "\`\`\`" >> "$OUTPUT"
+else
+    echo "(journalctl 未安装)" >> "$OUTPUT"
+fi
+
+# --- 可选: ACPI NHLT 表 (Coreboot 下常缺失，影响 SOF) ---
+section "ACPI NHLT 表"
+if [ -d /sys/firmware/acpi/tables ]; then
+    echo "# ls /sys/firmware/acpi/tables/ | grep -i nhlt" >> "$OUTPUT"
+    echo "\`\`\`" >> "$OUTPUT"
+    ls /sys/firmware/acpi/tables/ 2>/dev/null | grep -i nhlt >> "$OUTPUT" || echo "(未找到 NHLT 表，Coreboot 下常见)" >> "$OUTPUT"
+    echo "\`\`\`" >> "$OUTPUT"
+else
+    echo "(/sys/firmware/acpi/tables 不可用)" >> "$OUTPUT"
+fi
+
+# --- 可选: sof-logger (若已安装，可查看 SOF 固件 trace) ---
+section "sof-logger (可选)"
+# sudo 下同时检查 SUDO_USER 的 ~/.local/bin（用户可能安装于此）
+if [ -n "${SUDO_USER:-}" ]; then
+    USER_HOME=$(getent passwd "$SUDO_USER" 2>/dev/null | cut -d: -f6)
+    [ -n "$USER_HOME" ] && [ -d "$USER_HOME/.local/bin" ] && export PATH="$USER_HOME/.local/bin:$PATH"
+fi
+if command -v sof-logger &>/dev/null; then
+    echo "# sof-logger -t 2>/dev/null | tail -30 (DMA trace，无需 ldc 文件)" >> "$OUTPUT"
+    echo "\`\`\`" >> "$OUTPUT"
+    SOF_LOG=$(timeout 3 sof-logger -t 2>/dev/null | tail -30) || true
+    if [ -z "$SOF_LOG" ]; then
+        echo "(sof-logger 执行超时或需 root/debugfs)" >> "$OUTPUT"
+    elif echo "$SOF_LOG" | grep -q "Usage sof-logger"; then
+        echo "(sof-logger 输出 Usage：通常表示 debugfs 未挂载或需 root 权限读取 /sys/kernel/debug/sof/)" >> "$OUTPUT"
+    else
+        echo "$SOF_LOG" >> "$OUTPUT"
+    fi
+    echo "\`\`\`" >> "$OUTPUT"
+else
+    echo "(sof-logger 未安装，可从 thesofproject/sof-bin 或发行版 firmware-sof 相关包安装)" >> "$OUTPUT"
+fi
+
+# --- 音频服务/会话 ---
+section "音频服务 (PulseAudio / PipeWire)"
+echo "# 提示: sudo 下会以原用户身份调用 pactl/pw-cli，需设置 XDG_RUNTIME_DIR 以连接用户会话" >> "$OUTPUT"
+RUN_PACTL() {
+    if [ -n "${SUDO_USER:-}" ] && [ -d "/run/user/$(id -u "$SUDO_USER" 2>/dev/null)" ]; then
+        runuser -u "$SUDO_USER" -- env XDG_RUNTIME_DIR="/run/user/$(id -u "$SUDO_USER")" "$@"
+    else
+        "$@"
+    fi
+}
+if command -v pactl &>/dev/null; then
+    run_cmd "pactl info" RUN_PACTL pactl info 2>/dev/null || run_cmd "pactl info (直接调用)" pactl info 2>/dev/null || true
+    run_cmd "pactl list cards (含 HDMI/3.5mm 等 profile)" RUN_PACTL pactl list cards 2>/dev/null || true
+    run_cmd "pactl list sinks short" RUN_PACTL pactl list sinks short 2>/dev/null || true
+fi
+if command -v pw-cli &>/dev/null; then
+    run_cmd "pw-cli list-objects Device" RUN_PACTL pw-cli list-objects Device 2>/dev/null || true
+fi
+if command -v wpctl &>/dev/null; then
+    run_cmd "wpctl status (WirePlumber)" RUN_PACTL wpctl status 2>/dev/null || true
+fi
+
+# --- 已加载的音频相关内核模块 ---
+section "音频相关内核模块"
+run_cmd "lsmod | grep -iE 'snd|hda|sound'" bash -c "lsmod | grep -iE 'snd|hda|sound' || echo '(无匹配)'"
+
+# --- 混音器状态 ---
+section "ALSA 混音器状态"
+if command -v amixer &>/dev/null; then
+    run_cmd "amixer -c 0 contents (或 -c default)" amixer -c 0 contents 2>/dev/null || amixer contents 2>/dev/null || echo "(amixer 执行失败)" >> "$OUTPUT"
+fi
+
+# --- SOF 固件与拓扑 ---
+section "SOF 固件 (Intel Sound Open Firmware)"
+if [ -f /sys/kernel/debug/sof/fw_version ]; then
+    echo "# /sys/kernel/debug/sof/fw_version (需 root)" >> "$OUTPUT"
+    echo "\`\`\`" >> "$OUTPUT"
+    cat /sys/kernel/debug/sof/fw_version 2>/dev/null >> "$OUTPUT" || echo "(无法读取)" >> "$OUTPUT"
+    echo "\`\`\`" >> "$OUTPUT"
+    echo "" >> "$OUTPUT"
+fi
+if [ -d /lib/firmware/intel ]; then
+    echo "# ls -la /lib/firmware/intel/ (sof 相关)" >> "$OUTPUT"
+    echo "\`\`\`" >> "$OUTPUT"
+    ls -la /lib/firmware/intel/ 2>/dev/null | grep -E 'sof|avs' >> "$OUTPUT" || ls -la /lib/firmware/intel/ >> "$OUTPUT"
+    echo "\`\`\`" >> "$OUTPUT"
+    for tplg_dir in /lib/firmware/intel/sof /lib/firmware/intel/sof-tplg; do
+        if [ -d "$tplg_dir" ]; then
+            echo "# SOF 拓扑: $tplg_dir" >> "$OUTPUT"
+            echo "\`\`\`" >> "$OUTPUT"
+            find "$tplg_dir" -type f -name '*tplg*' 2>/dev/null | head -30 >> "$OUTPUT"
+            echo "\`\`\`" >> "$OUTPUT"
+        fi
+    done
+else
+    echo "(未找到 /lib/firmware/intel)" >> "$OUTPUT"
+fi
+
+# --- 机器/主板识别 (ACPI) ---
+section "机器识别 (主板/机型)"
+if [ -f /sys/class/dmi/id/board_name ]; then
+    echo "# DMI 主板信息:" >> "$OUTPUT"
+    echo "\`\`\`" >> "$OUTPUT"
+    for f in /sys/class/dmi/id/board_name /sys/class/dmi/id/product_name /sys/class/dmi/id/sys_vendor; do
+        [ -f "$f" ] && echo "$(basename $f): $(cat "$f" 2>/dev/null)" >> "$OUTPUT"
+    done
+    echo "\`\`\`" >> "$OUTPUT"
+fi
+
+log "收集完成，结果已保存到: $OUTPUT"
--- a/bmad-help.zh-CN.md
+++ b/bmad-help.zh-CN.md
@@ -0,0 +1,173 @@
+# BMad 帮助目录（中文版）
+
+本文档由 [`_bmad/_config/bmad-help.csv`](_bmad/_config/bmad-help.csv) 翻译并整理，便于中文读者检索 **菜单码**、**技能** 与用途。
+
+技能调用方式（斜杠命令 / 自然语言等）以本机 `npx bmad-method install` 与 Cursor 集成为准。
+
+## 表列说明
+
+| 列 | 含义 |
+| --- | --- |
+| **码** | 菜单快捷码（不同模块下可能重复，以技能名列区分） |
+| **显示名称** | CSV 英文显示名（与上游一致，便于对照） |
+| **技能** | 技能标识 / 工作流名 |
+| **说明** | 对「sequence」列的中文释义 |
+| **阶段** | 工作流阶段或触发时机（`anytime` 等为随时） |
+| **前置** | 建议先完成的技能或条件（CSV 中错位字段已尽量还原） |
+| **必选** | 是否后期阶段强制项（`true` / `false`） |
+| **产出** | 主要输出位置或产物类型（保留英文路径占位符） |
+
+---
+
+## BMad 构建器
+
+| 码 | 显示名称 | 技能 | 说明 | 阶段 | 前置 | 必选 | 产出 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| BA | Build an Agent | `bmad-agent-builder` | 通过对话式梳理，创建、编辑或重建 Agent 技能。 | 随时 | bmad-agent-builder:quality-analysis | false | bmad_builder_output_folder / agent skill |
+| AA | Analyze an Agent | `bmad-agent-builder` | 对既有 Agent 做质量分析：结构、内聚、提示词工艺与改进空间。 | 随时 | — | false | bmad_builder_reports / quality report |
+| SB | Setup Builder Module | `bmad-bmb-setup` | 安装或更新 BMad Builder 模块配置与帮助条目。 | 随时 | — | false | {project-root}/_bmad / config.yaml and config.user.yaml |
+| IM | Ideate Module | `bmad-module-builder` | 头脑风暴并规划 BMad 模块：创意、架构与构建计划。 | 随时 | bmad-module-builder:create-module | false | bmad_builder_reports / module plan |
+| CM | Create Module | `bmad-module-builder` | 将模块基础设施脚手架化为可安装的 BMad 模块技能。 | 随时 | — | false | bmad_builder_output_folder / setup skill |
+| VM | Validate Module | `bmad-module-builder` | 检查模块结构是否完整、准确，且能力均已正确注册。 | 随时 | — | false | bmad_builder_reports / validation report |
+| BW | Build a Workflow | `bmad-workflow-builder` | 创建、编辑或重建工作流或工具型技能。 | 随时 | bmad-workflow-builder:quality-analysis | false | bmad_builder_output_folder / workflow skill |
+| AW | Analyze a Workflow | `bmad-workflow-builder` | 对既有工作流/技能做质量分析：结构、效率与改进空间。 | 随时 | — | false | bmad_builder_reports / quality report |
+| CW | Convert a Skill | `bmad-workflow-builder` | 将任意技能转换为符合 BMad 的成果导向形态，并生成前后对比 HTML 报告。 | 随时 | — | false | bmad_builder_reports / converted skill + comparison report |
+
+## BMad 方法
+
+| 码 | 显示名称 | 技能 | 说明 | 阶段 | 前置 | 必选 | 产出 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| WD | Write Document | `bmad-agent-tech-writer` | 详细描述需求，由代理按文档最佳实践撰写；可多轮对话并子流程做调研/审阅。 | 随时 | — | false | project-knowledge / document |
+| US | Update Standards | `bmad-agent-tech-writer` | 若发现文档惯例缺失，把你的偏好写入代理记忆中的 documentation-standards.md。 | 随时 | — | false | _bmad/_memory/tech-writer-sidecar / standards |
+| MG | Mermaid Generate | `bmad-agent-tech-writer` | 根据描述生成 Mermaid 图；未指定类型时会建议合适的图类。 | 随时 | — | false | planning_artifacts / mermaid diagram |
+| VD | Validate Document | `bmad-agent-tech-writer` | 对照文档规范与最佳实践审查指定文档，按优先级给出可执行的改进建议。 | 随时 | — | false | planning_artifacts / validation report |
+| EC | Explain Concept | `bmad-agent-tech-writer` | 为复杂概念撰写清晰技术说明，附示例与图示。 | 随时 | — | false | project_knowledge / explanation |
+| BP | Brainstorm Project | `bmad-brainstorming` | 专家引导，使用一种或多种技法进行项目头脑风暴。 | 阶段 1 · 分析 | — | false | planning_artifacts / brainstorming session |
+| IR | Check Implementation Readiness | `bmad-check-implementation-readiness` | 确保 PRD、UX、架构与 Epic/Story 彼此对齐。 | 阶段 3 · 方案设计 | bmad-create-epics-and-stories | true | planning_artifacts / readiness report |
+| CR | Code Review | `bmad-code-review` | 故事循环：若有问题退回 DS；通过后进入下一 CS，或 Epic 完成时走 ER。 | 阶段 4 · 实现 | bmad-dev-story | false | — |
+| CC | Correct Course | `bmad-correct-course` | 在重大变更时纠偏：可能建议重来、更新 PRD、重做架构/冲刺规划或修正 Epic 与 Story。 | 随时 | — | false | planning_artifacts / change proposal |
+| CA | Create Architecture | `bmad-create-architecture` | 引导式产出技术决策文档（架构）。 | 阶段 3 · 方案设计 | — | true | planning_artifacts / architecture |
+| CE | Create Epics and Stories | `bmad-create-epics-and-stories` | 在架构文档（CA）之后创建 Epic 与用户故事。 | 阶段 3 · 方案设计 | bmad-create-architecture | true | planning_artifacts / epics and stories |
+| CP | Create PRD | `bmad-create-prd` | 专家引导完成产品需求文档（PRD）。 | 阶段 2 · 规划 | — | true | planning_artifacts / prd |
+| CS | Create Story | `bmad-create-story` | 故事循环起点：准备冲刺计划中「下一个」待做 Story，或指定 Epic/Story。 | 阶段 4 · 实现 | bmad-create-story:validate | true | implementation_artifacts / story |
+| VS | Validate Story | `bmad-create-story` | 在开发开始前校验 Story 是否就绪、完整。 | 阶段 4 · 实现 | bmad-dev-story | false | implementation_artifacts / story validation report |
+| CU | Create UX | `bmad-create-ux-design` | 落实 UX 方案；若项目以 UI 为主，强烈建议使用。 | 阶段 2 · 规划 | bmad-create-prd | false | planning_artifacts / ux design |
+| DS | Dev Story | `bmad-dev-story` | 故事循环：执行 Story 实现与测试，经 CR，如需修复回到 DS。 | 阶段 4 · 实现 | bmad-create-story:validate | true | — |
+| DP | Document Project | `bmad-document-project` | 分析现有项目并产出可用文档。 | 随时 | — | false | project-knowledge / * |
+| DR | Domain Research | `bmad-domain-research` | 行业领域深度研究、专业术语与知识沉淀。 | 阶段 1 · 分析 | — | false | planning_artifacts · project_knowledge / research documents |
+| EP | Edit PRD | `bmad-edit-prd` | 在通过 PRD 校验流程后，编辑并改进指定路径的 PRD。 | 阶段 2 · 规划 | bmad-validate-prd | false | planning_artifacts / updated prd |
+| GPC | Generate Project Context | `bmad-generate-project-context` | 扫描代码库生成精简、面向 LLM 的 project-context.md；棕地项目尤其重要。 | 随时 | — | false | output_folder / project context |
+| MR | Market Research | `bmad-market-research` | 市场、竞品、客户需求与趋势分析。 | 阶段 1 · 分析 | — | false | planning_artifacts · project-knowledge / research documents |
+| CB | Create Brief | `bmad-product-brief` | 引导式厘清产品创意与核心价值。 | 阶段 1 · 分析 | — | false | planning_artifacts / product brief |
+| QA | QA Automation Test | `bmad-qa-generate-e2e-tests` | 为已实现代码生成自动化 API 与 E2E 测试；非代码评审或 Story 校验（请用 CR）。 | 阶段 4 · 实现 | bmad-dev-story | false | implementation_artifacts / test suite |
+| QQ | Quick Dev | `bmad-quick-dev` | 统一「意图进、代码出」：澄清、实现、审阅与交付展示。 | 随时 | — | false | implementation_artifacts / spec and project implementation |
+| ER | Retrospective | `bmad-retrospective` | 可选：在 Epic 结束时回顾成果与经验，规划下一 Epic；重大问题考虑走 CC。 | 阶段 4 · 实现 | bmad-code-review | false | implementation_artifacts / retrospective |
+| SP | Sprint Planning | `bmad-sprint-planning` | 启动实现阶段：生成实现代理将按序执行的冲刺计划。 | 阶段 4 · 实现 | — | true | implementation_artifacts / sprint status |
+| SS | Sprint Status | `bmad-sprint-status` | 随时总结 Sprint 状态并路由到下一工作流。 | 阶段 4 · 实现 | bmad-sprint-planning | false | — |
+| TR | Technical Research | `bmad-technical-research` | 技术可行性、架构选项与实现路径研究。 | 阶段 1 · 分析 | — | false | planning_artifacts · project_knowledge / research documents |
+| VP | Validate PRD | `bmad-validate-prd` | 在创建 PRD（CP）之后校验 PRD 质量。 | 阶段 2 · 规划 | bmad-create-prd | false | planning_artifacts / prd validation report |
+
+## 核心
+
+| 码 | 显示名称 | 技能 | 说明 | 阶段 | 前置 | 必选 | 产出 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| BSP | Brainstorming | `bmad-brainstorming` | 在创意早期或思路卡住时做头脑风暴。 | 随时 | — | false | {output_folder}/brainstorming / brainstorming session |
+| DG | Distillator | `bmad-distillator` | 生成节省 token 的蒸馏文，保留供下游 LLM 使用的关键信息。 | — | — | adjacent to source document or specified output_path | distillate markdown file(s) |
+| EP | Editorial Review - Prose | `bmad-editorial-review-prose` | 成稿后润色正文表达。 | — | — | report located with target document | three-column markdown table with suggested fixes |
+| ES | Editorial Review - Structure | `bmad-editorial-review-structure` | 当文档由多段子流程拼成或结构需加强时，做结构性编辑审阅。 | — | — | report located with target document | — |
+| BH | BMad Help | `bmad-help` | 判断当前所处 BMad 流程位置并回答问题；推荐下一步技能与调用方式。 | 随时 | — | false | — |
+| ID | Index Docs | `bmad-index-docs` | 在不加载全部文件的前提下为目录生成/更新索引，便于掌握文档地图。 | 随时 | — | false | — |
+| PM | Party Mode | `bmad-party-mode` | 编排多代理/多视角讨论与协作。 | 随时 | — | false | — |
+| AR | Adversarial Review | `bmad-review-adversarial-general` | 在定稿前做对抗性质量审查；其他模块的代码审也可自动调用，亦适用于文档。 | — | — |  | — |
+| ECH | Edge Case Hunter Review | `bmad-review-edge-case-hunter` | 与对抗审搭配，从边界场景做正交补充，重方法而非「挑刺态度」。 | — | — |  | — |
+| SD | Shard Document | `bmad-shard-doc` | 当单份文档过大（常为 >500 行）时拆分为可管理片段。 | — | — |  | — |
+
+## 创意智能套件（CIS）
+
+| 码 | 显示名称 | 技能 | 说明 | 阶段 | 前置 | 必选 | 产出 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| BS | Brainstorming | `bmad-brainstorming` | 用一种或多种技法主持头脑风暴会话。 | 随时 | — | false | output_folder / brainstorming session results |
+| DT | Design Thinking | `bmad-cis-design-thinking` | 以同理心驱动的人本设计流程指导。 | 随时 | — | false | output_folder / design thinking |
+| IS | Innovation Strategy | `bmad-cis-innovation-strategy` | 识别颠覆机会并设计商业模式创新。 | 随时 | — | false | output_folder / innovation strategy |
+| PS | Problem Solving | `bmad-cis-problem-solving` | 运用系统化问题解决方法拆解复杂挑战。 | 随时 | — | false | output_folder / problem solution |
+| ST | Storytelling | `bmad-cis-storytelling` | 用成熟叙事框架与技巧撰写故事/叙述。 | 随时 | — | false | output_folder / narrative/story |
+
+## 游戏开发工作室（GDS）
+
+| 码 | 显示名称 | 技能 | 说明 | 阶段 | 前置 | 必选 | 产出 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| QP | Quick Prototype | `bmad-gds-quick-prototype` | 快速游戏原型，验证机制与创意。 | 随时 | — | false | — |
+| BG | Brainstorm Game | `gds-brainstorm-game` | 在游戏语境下主持头脑风暴。 | 前期制作 | — | false | output_folder / brainstorming session |
+| IR | Check Implementation Readiness | `gds-check-implementation-readiness` | 在投产前确保 GDD、UX、架构与 Epic/Story 对齐。 | 技术 | gds-create-epics-and-stories | true | planning_artifacts / readiness report |
+| CR | Code Review | `gds-code-review` | 对标记为「待评审」的 Story 做干净上下文的 QA 代码审查。 | 制作 | gds-dev-story | false | — |
+| CC | Correct Course | `gds-correct-course` | 游戏开发冲刺偏离路线时进行纠偏。 | 随时 | — | false | planning_artifacts / change proposal |
+| CE | Create Epics and Stories | `gds-create-epics-and-stories` | 依据 GDD 需求创建 Epic 与 Story 列表，作为开发规格驱动。 | 技术 | gds-game-architecture | true | planning_artifacts / epics and stories |
+| GB | Game Brief | `gds-create-game-brief` | 交互式游戏简报，引导用户明确游戏愿景。 | 前期制作 | — | false | output_folder / game brief |
+| GDD | Game Design Document | `gds-create-gdd` | 撰写游戏设计文档 GDD：机制、系统、进度与实现指引。 | 设计 | — | false | planning_artifacts / gdd |
+| ND | Narrative Design | `gds-create-narrative` | 为剧情向游戏撰写叙事文档：结构、人物弧与世界观。 | 设计 | gds-create-gdd | false | planning_artifacts / narrative design |
+| CP | Create PRD | `gds-create-prd` | 从 GDD 或从零撰写 PRD，供 bmad-assist 等外部工具使用。 | 设计 | gds-create-gdd | false | planning_artifacts / prd |
+| CS | Create Story | `gds-create-story` | 为开发代理准备上下文充分的 Story。 | 制作 | gds-sprint-planning | true | implementation_artifacts / story |
+| CU | Create UX Design | `gds-create-ux-design` | 落实游戏 UX/UI；若 UI 是核心，强烈建议使用。 | 设计 | gds-create-gdd | false | planning_artifacts / ux design |
+| DS | Dev Story | `gds-dev-story` | 执行 Dev Story：按任务与测试实现。 | 制作 | gds-create-story | true | — |
+| DP | Document Project | `gds-document-project` | 分析现有游戏项目并产出文档。 | 随时 | — | false | project_knowledge / project documentation |
+| DR | Domain Research | `gds-domain-research` | 游戏产业领域深度研究与术语沉淀。 | 前期制作 | — | false | planning_artifacts / research documents |
+| ES | E2E Scaffold | `gds-e2e-scaffold` | 搭建 E2E 测试基础设施脚手架。 | 游戏测试 | gds-test-automate | false | — |
+| EP | Edit PRD | `gds-edit-prd` | 改进并增强既有 PRD。 | 设计 | gds-validate-prd | false | planning_artifacts / updated prd |
+| GA | Game Architecture | `gds-game-architecture` | 产出可伸缩游戏架构：引擎、系统、网络与技术设计。 | 技术 | — | true | planning_artifacts / game architecture |
+| PC | Project Context | `gds-generate-project-context` | 生成适配所选智能体工具一致性的 project-context.md。 | 技术 | — | false | — |
+| MR | Market Research | `gds-market-research` | 游戏市场、竞品与玩家需求分析。 | 前期制作 | — | false | planning_artifacts / research documents |
+| PT | Performance Test | `gds-performance-test` | 设计性能测试策略。 | 游戏测试 | gds-playtest-plan | false | planning_artifacts / performance strategy |
+| PP | Playtest Plan | `gds-playtest-plan` | 撰写结构化试玩/测试计划。 | 游戏测试 | gds-e2e-scaffold | false | planning_artifacts / playtest plan |
+| QD | Quick Dev | `gds-quick-dev` | 兼顾游戏特性的灵活开发流程。 | 随时 | — | false | — |
+| QQ | Quick Dev New Preview | `gds-quick-dev-new-preview` | 实验性一体化快捷流：单工作流内完成澄清、计划、实现、审阅与展示。 | 随时 | — | false | — |
+| TS | Quick Spec | `gds-quick-spec` | 小需求、小改动、简单应用/工具，无需冗长规划。 | 随时 | — | false | planning_artifacts / tech spec |
+| ER | Retrospective | `gds-retrospective` | 在游戏开发 Epic 完成后组织团队回顾。 | 制作 | gds-code-review | false | implementation_artifacts / retrospective |
+| SP | Sprint Planning | `gds-sprint-planning` | 由 Epic 文件生成或更新 sprint-status.yaml。 | 制作 | — | true | implementation_artifacts / sprint status |
+| SS | Sprint Status | `gds-sprint-status` | 查看冲刺进度、暴露风险并给出下一步行动建议。 | 制作 | gds-sprint-planning | false | — |
+| TR | Technical Research | `gds-technical-research` | 游戏引擎选项与实现路径的技术可行性研究。 | 前期制作 | — | false | planning_artifacts / research documents |
+| TA | Test Automate | `gds-test-automate` | 生成自动化游戏测试。 | 游戏测试 | — | false | — |
+| TD | Test Design | `gds-test-design` | 设计覆盖流程与质量要求的游戏测试场景。 | 技术 | gds-test-framework | false | planning_artifacts / test design |
+| TF | Test Framework | `gds-test-framework` | 为 Unity / Unreal / Godot 等项目初始化游戏测试框架架构。 | 技术 | — | false | — |
+| TR | Test Review | `gds-test-review` | 评审测试质量与覆盖。 | 游戏测试 | gds-performance-test | false | — |
+| VP | Validate PRD | `gds-validate-prd` | 按外部工具兼容标准校验 PRD。 | 设计 | gds-create-prd | false | planning_artifacts / prd validation report |
+
+## 测试架构企业版（TEA）
+
+| 码 | 显示名称 | 技能 | 说明 | 阶段 | 前置 | 必选 | 产出 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| TMT | Teach Me Testing | `bmad-teach-me-testing` | TEA 学院：通过 7 次课讲授测试基础（含进度与证书相关产出）。 | 阶段 0 · 学习 | — | false | test_artifacts / progress file · session notes · certificate |
+| AT | ATDD | `bmad-testarch-atdd` | 生成失败用例（TDD 红灯阶段）。 | 阶段 4 · 实现 | — | false | test_artifacts / atdd tests |
+| TA | Test Automation | `bmad-testarch-automate` | 扩展自动化测试覆盖。 | 阶段 4 · 实现 | bmad-testarch-atdd | false | test_artifacts / test suite |
+| CI | CI Setup | `bmad-testarch-ci` | 配置 CI/CD 质量流水线。 | 阶段 3 · 方案设计 | bmad-testarch-framework | false | test_artifacts / ci config |
+| TF | Test Framework | `bmad-testarch-framework` | 初始化生产级测试框架脚手架。 | 阶段 3 · 方案设计 | bmad-testarch-test-design | false | test_artifacts / framework scaffold |
+| NR | NFR Assessment | `bmad-testarch-nfr` | 非功能需求（NFR）评估。 | 阶段 4 · 实现 | bmad-testarch-automate | false | test_artifacts / nfr report |
+| TD | Test Design | `bmad-testarch-test-design` | 基于风险的测试规划。 | 阶段 3 · 方案设计 | — | false | test_artifacts / test design document |
+| RV | Test Review | `bmad-testarch-test-review` | 质量审计（0–100 分制）。 | 阶段 4 · 实现 | bmad-testarch-automate | false | test_artifacts / review report |
+| TR | Traceability | `bmad-testarch-trace` | 覆盖度可追溯与质量门禁决策。 | 阶段 4 · 实现 | bmad-testarch-test-review | false | test_artifacts / traceability matrix · gate decision |
+
+## 网页设计工作室（WDS）
+
+| 码 | 显示名称 | 技能 | 说明 | 阶段 | 前置 | 必选 | 产出 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| AD | Agentic Development | `bmad-wds-agentic-development` | 带设计日志与浏览器验证的迭代「构建—验证」循环。 | WDS · 构建/验证 | bmad-wds-design-delivery | false | _progress/agent-experiences / experience-documents |
+| AS | Alignment & Signoff | `bmad-wds-alignment` | 干系人共识 pitch 与服务协议；若做自有产品可跳过。 | WDS · 宣讲/对齐 | — | false | design_artifacts/A-Product-Brief / pitch service-agreement signoff |
+| CS | Conceptual Sketching | `bmad-wds-conceptual-sketching` | 详细规格前的快速视觉草图探索；直接场景可跳过。 | WDS · 设计 | bmad-wds-outline-scenarios | false | design_artifacts/C-UX-Scenarios / sketches |
+| SP | Conceptual Specifications | `bmad-wds-conceptual-specs` | 逐页逐元素记录设计决策，开发可直接据此实现。 | WDS · 设计 | bmad-wds-outline-scenarios | true | design_artifacts/C-UX-Scenarios / page-specs scenario-specs |
+| DD | Design Delivery | `bmad-wds-design-delivery` | 校验规格完整并打包为 DD yaml，供开发交接。 | WDS · 设计 | bmad-wds-conceptual-specs | true | design_artifacts/E-PRD/Design-Deliveries / delivery-package acceptance-criteria |
+| DS | Design System | `bmad-wds-design-system` | 管理组件库与设计令牌；设计系统模式为「无」时跳过。 | WDS · 设计 | bmad-wds-functional-components | false | design_artifacts/D-Design-System / components/ design-tokens.md |
+| FREYA | Wake Freya | `bmad-wds-freya` | 第 3–4 阶段 UX 设计师代理 Freya：检查前置条件并给出下一步。 | WDS · 唤醒代理 | — | false | — |
+| FI | Functional Components | `bmad-wds-functional-components` | 从规格抽取可复用模式为组件定义；无设计系统时跳过。 | WDS · 设计 | bmad-wds-conceptual-specs | false | design_artifacts/C-UX-Scenarios / component-candidates |
+| IDUN | Wake Idun | `bmad-wds-idun` | 治理代理 Idun：访谈组织以配置 Agent Space 与权限模型。 | WDS · 唤醒代理 | — | false | — |
+| OS | Outline Scenarios | `bmad-wds-outline-scenarios` | 以「人设 + 目标 + 结果」定义用户旅程，并与触发图驱动力关联。 | WDS · 设计 | bmad-wds-trigger-mapping | true | design_artifacts/C-UX-Scenarios / scenario-overview.md |
+| PR | Platform Requirements | `bmad-wds-platform-requirements` | 平台、设备、集成与约束等技术边界；简单落地页可跳过。 | WDS · 策略 | bmad-wds-project-brief | false | design_artifacts/A-Product-Brief / platform-requirements.md |
+| PE | Product Evolution | `bmad-wds-product-evolution` | 持续改进：反馈 → 触发图 → 规格 → 代码 → 验证。 | WDS · 构建/验证 | bmad-wds-usability-testing | false | design_artifacts / updated-artifacts |
+| PB | Project Brief | `bmad-wds-project-brief` | 定义产品愿景、定位与成功标准，设计决策应可追溯至此。 | WDS · 策略 | — | true | design_artifacts/A-Product-Brief / project-brief.md |
+| SAGA | Wake Saga | `bmad-wds-saga` | 第 1–2 阶段战略分析师代理 Saga：扫描仓库并建议下一步。 | WDS · 唤醒代理 | — | false | — |
+| SB | Storyboarding | `bmad-wds-storyboarding` | 跨界面串联用户旅程与入口、过渡、异常路径；简单场景可跳过。 | WDS · 设计 | bmad-wds-outline-scenarios | false | design_artifacts/C-UX-Scenarios / storyboards |
+| TM | Trigger Mapping | `bmad-wds-trigger-mapping` | 将业务目标映射到用户心理：人设、功能与驱动力打分。 | WDS · 策略 | bmad-wds-project-brief | true | design_artifacts/B-Trigger-Map / trigger-map.md personas/ feature-impact-analysis.md |
+| AT | Acceptance Testing | `bmad-wds-usability-testing` | 在真实用户环境中做可用性测试与回顾式出声思考。 | WDS · 构建/验证 | bmad-wds-agentic-development | false | design_artifacts/F-Testing / test-results findings |
+| VD | Visual Design | `bmad-wds-visual-design` | 将规格转为带样式的 HTML 原型，可与 Figma 往返。 | WDS · 设计 | bmad-wds-conceptual-specs | false | design_artifacts/C-UX-Scenarios / html-prototypes visual-designs |
+
+---
+
+*生成脚本：[`_bmad/scripts/render_bmad_help_zh_cn.py`](_bmad/scripts/render_bmad_help_zh_cn.py)（修改译文表后重新运行以更新本文档。）*
--- a/debian/changelog
+++ b/debian/changelog
@@ -0,0 +1,64 @@
+kaisa-hdmi-pipewire-fix (0.3.0) unstable; urgency=medium
+
+  * Remove /usr/bin helper scripts and user systemd units from the package;
+    delivery is UCM2 + WirePlumber conf only until automation is validated.
+
+ -- chromebox_10th_audio_driver <maintainers@local>  Sun, 06 Apr 2026 22:00:00 +0800
+
+kaisa-hdmi-pipewire-fix (0.2.7) unstable; urgency=medium
+
+  * postinst: systemctl disable --global for kaisa user units (clears stale global enables on upgrade).
+
+ -- chromebox_10th_audio_driver <maintainers@local>  Sun, 05 Apr 2026 12:00:00 +0800
+
+kaisa-hdmi-pipewire-fix (0.2.6) unstable; urgency=medium
+
+  * user preset: disable kaisa-hdmi-auto-default-sink.service by default (opt-in only).
+
+ -- chromebox_10th_audio_driver <maintainers@local>  Sat, 04 Apr 2026 23:30:00 +0800
+
+kaisa-hdmi-pipewire-fix (0.2.5) unstable; urgency=medium
+
+  * kaisa-hdmi-auto-default-sink-watch: skip pcm when aplay reports 0 playback subdevices (avoids set_hw_params EIO).
+
+ -- chromebox_10th_audio_driver <maintainers@local>  Sat, 04 Apr 2026 22:00:00 +0800
+
+kaisa-hdmi-pipewire-fix (0.2.4) unstable; urgency=medium
+
+  * kaisa-hdmi-auto-default-sink-watch: poll HDMI Jack, set-default-sink + IEC958.
+  * user systemd preset: enable auto-sink, disable kaisa-hdmi-iec958-pipewire (pro-audio oneshot).
+
+ -- chromebox_10th_audio_driver <maintainers@local>  Sat, 04 Apr 2026 20:00:00 +0800
+
+kaisa-hdmi-pipewire-fix (0.2.3) unstable; urgency=medium
+
+  * kaisa-restore-iec958-ucm: match HiFi__hw_sofrt5682_N__ sink names (Kaisa pactl).
+  * next.md OPERATION: troubleshooting when IEC958 on but silent (wpctl, HDMI port).
+
+ -- chromebox_10th_audio_driver <maintainers@local>  Mon, 07 Apr 2026 12:00:00 +0800
+
+kaisa-hdmi-pipewire-fix (0.2.2) unstable; urgency=medium
+
+  * kaisa-restore-iec958-ucm: hdmi/displayport sink heuristics; reject pcm 0/1 with hint.
+  * next.md / OPERATION / postinst: apt upgrade may reinstall 50-kaisa; diagnostic block.
+
+ -- chromebox_10th_audio_driver <maintainers@local>  Sun, 06 Apr 2026 22:00:00 +0800
+
+kaisa-hdmi-pipewire-fix (0.2.1) unstable; urgency=medium
+
+  * Add kaisa-restore-iec958-ucm: open IEC958 without forcing pro-audio (UCM/HiFi).
+
+ -- chromebox_10th_audio_driver <maintainers@local>  Sun, 06 Apr 2026 23:59:00 +0800
+
+kaisa-hdmi-pipewire-fix (0.2.0) unstable; urgency=medium
+
+  * Ship reference UCM2 overlay (conf.d/sof-rt5682, GoogleKaisa/sof-rt5682).
+  * Depends on alsa-ucm-conf; document UCM vs pro-audio mutex in postinst/README.
+
+ -- chromebox_10th_audio_driver <maintainers@local>  Sun, 06 Apr 2026 22:30:00 +0800
+
+kaisa-hdmi-pipewire-fix (0.1.0) unstable; urgency=medium
+
+  * Initial packaging: system WirePlumber drop-in, restore script, user systemd unit.
+
+ -- chromebox_10th_audio_driver <maintainers@local>  Sat, 04 Apr 2026 12:00:00 +0800
--- a/debian/control
+++ b/debian/control
@@ -0,0 +1,25 @@
+Source: kaisa-hdmi-pipewire-fix
+Section: sound
+Priority: optional
+Maintainer: chromebox_10th_audio_driver <maintainers@local>
+Build-Depends: debhelper-compat (= 13)
+Rules-Requires-Root: no
+Standards-Version: 4.6.2
+
+Package: kaisa-hdmi-pipewire-fix
+Architecture: all
+Depends: wireplumber, alsa-utils, alsa-ucm-conf, ${misc:Depends}
+Recommends: pipewire-pulse | pipewire-pulseaudio
+Suggests: pulseaudio-utils
+Description: Google Kaisa HDMI audio fix (PipeWire / sof-rt5682, UCM2)
+ Installs UCM2 overlay under /usr/share/alsa/ucm2/ (conf.d/sof-rt5682,
+ GoogleKaisa/sof-rt5682) for Jack-driven HDMI routes plus IEC958 sequences,
+ and a system-wide WirePlumber drop-in (pro-audio profile, HDMI sink
+ priorities). Does not ship helper binaries or user systemd units yet —
+ use manual pactl/amixer steps in OPERATION until automated restore is ready.
+ UCM-first and pro-audio WirePlumber are mutually exclusive — see
+ /usr/share/doc/kaisa-hdmi-pipewire-fix/README.md and OPERATION.
+ .
+ PCI path in the WirePlumber fragment targets BDF 0000:00:1f.3; edit under
+ /etc/wireplumber/ if needed. See OPERATION_PipeWire_Kaisa_HDMI.md.gz in
+ /usr/share/doc/.
--- a/debian/kaisa-hdmi-pipewire-fix.postinst
+++ b/debian/kaisa-hdmi-pipewire-fix.postinst
@@ -0,0 +1,17 @@
+#!/bin/sh
+set -e
+case "$1" in
+configure)
+    echo "kaisa-hdmi-pipewire-fix: UCM2 已安装至 /usr/share/alsa/ucm2/（sof-rt5682 + GoogleKaisa）"
+    echo "kaisa-hdmi-pipewire-fix: WirePlumber 片段: /etc/wireplumber/wireplumber.conf.d/"
+    echo "  重要：UCM（产品目标：无 Jack 不误导）与强制 pro-audio 片段二选一。"
+    echo "  若优先 UCM：请移走 50-kaisa-sof-rt5682-hdmi.conf 后执行:"
+    echo "    systemctl --user restart wireplumber pipewire pipewire-pulse"
+    echo "  注意: apt upgrade 本包后若该文件曾被删/改名, 可能被再次装入; UCM 用户请再移走。"
+    echo "  否则保留 pro-audio 过渡时，可暂叠 UCM 但行为以 OPERATION 互斥说明为准。"
+    echo "  详见: /usr/share/doc/kaisa-hdmi-pipewire-fix/README.md.gz"
+    echo "  本包当前仅含 UCM2 + WirePlumber 片段；自动 restore / IEC958 / Jack 轮询工具尚未随 deb 提供，见 OPERATION 手顺。"
+    ;;
+esac
+#DEBHELPER#
+exit 0
--- a/debian/kaisa-hdmi-pipewire-fix/DEBIAN/control
+++ b/debian/kaisa-hdmi-pipewire-fix/DEBIAN/control
@@ -0,0 +1,21 @@
+Package: kaisa-hdmi-pipewire-fix
+Version: 0.3.0
+Architecture: all
+Maintainer: chromebox_10th_audio_driver <maintainers@local>
+Installed-Size: 56
+Depends: wireplumber, alsa-utils, alsa-ucm-conf, init-system-helpers (>= 1.52)
+Recommends: pipewire-pulse | pipewire-pulseaudio
+Section: sound
+Priority: optional
+Description: Google Kaisa HDMI audio fix (PipeWire / sof-rt5682, UCM2)
+ Installs UCM2 overlay under /usr/share/alsa/ucm2/ (conf.d/sof-rt5682,
+ GoogleKaisa/sof-rt5682) for Jack-driven HDMI routes plus IEC958 sequences,
+ and a system-wide WirePlumber drop-in (pro-audio profile, HDMI sink
+ priorities). Does not ship helper binaries or user systemd units yet —
+ use manual pactl/amixer steps in OPERATION until automated restore is ready.
+ UCM-first and pro-audio WirePlumber are mutually exclusive — see
+ /usr/share/doc/kaisa-hdmi-pipewire-fix/README.md and OPERATION.
+ .
+ PCI path in the WirePlumber fragment targets BDF 0000:00:1f.3; edit under
+ /etc/wireplumber/ if needed. See OPERATION_PipeWire_Kaisa_HDMI.md.gz in
+ /usr/share/doc/.
--- a/debian/kaisa-hdmi-pipewire-fix/DEBIAN/postinst
+++ b/debian/kaisa-hdmi-pipewire-fix/DEBIAN/postinst
@@ -0,0 +1,17 @@
+#!/bin/sh
+set -e
+case "$1" in
+configure)
+    echo "kaisa-hdmi-pipewire-fix: UCM2 已安装至 /usr/share/alsa/ucm2/（sof-rt5682 + GoogleKaisa）"
+    echo "kaisa-hdmi-pipewire-fix: WirePlumber 片段: /etc/wireplumber/wireplumber.conf.d/"
+    echo "  重要：UCM（产品目标：无 Jack 不误导）与强制 pro-audio 片段二选一。"
+    echo "  若优先 UCM：请移走 50-kaisa-sof-rt5682-hdmi.conf 后执行:"
+    echo "    systemctl --user restart wireplumber pipewire pipewire-pulse"
+    echo "  注意: apt upgrade 本包后若该文件曾被删/改名, 可能被再次装入; UCM 用户请再移走。"
+    echo "  否则保留 pro-audio 过渡时，可暂叠 UCM 但行为以 OPERATION 互斥说明为准。"
+    echo "  详见: /usr/share/doc/kaisa-hdmi-pipewire-fix/README.md.gz"
+    echo "  本包当前仅含 UCM2 + WirePlumber 片段；自动 restore / IEC958 / Jack 轮询工具尚未随 deb 提供，见 OPERATION 手顺。"
+    ;;
+esac
+#DEBHELPER#
+exit 0
--- a/debian/kaisa-hdmi-pipewire-fix/DEBIAN/postrm
+++ b/debian/kaisa-hdmi-pipewire-fix/DEBIAN/postrm
@@ -0,0 +1,4 @@
+#!/bin/sh
+set -e
+#DEBHELPER#
+exit 0
--- a/debian/kaisa-hdmi-pipewire-fix/usr/share/doc/kaisa-hdmi-pipewire-fix/README.md
+++ b/debian/kaisa-hdmi-pipewire-fix/usr/share/doc/kaisa-hdmi-pipewire-fix/README.md
@@ -0,0 +1,49 @@
+# Kaisa UCM2 overlay（`sof-rt5682`）
+
+本目录为 **alsa-ucm-conf** 风格的 **UCM2** 草稿，目标：**Jack off 时 HDMI 路由对 ACP/桌面不表现为可随意可用的输出**（与强制 **`pro-audio`** 的 WirePlumber 策略不同，见 [docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md](../../../../../../docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md)「UCM 模式 vs pro-audio 模式」）。
+
+## 布局
+
+| 路径（相对 `ucm2/` 根） | 说明 |
+|-------------------------|------|
+| `conf.d/sof-rt5682/sof-rt5682.conf` | 卡入口，匹配 ALSA **card name** `sof-rt5682` |
+| `GoogleKaisa/sof-rt5682/HiFi.conf` | HiFi：`Port1` + **HDMI1/2/3**，**JackControl** + **`IEC958',N`** |
+
+上游 **alsa-ucm-conf** 若日后增加同名 `conf.d/sof-rt5682/`，与本仓库 **deb 同时安装会冲突** — 优先 **合并上游** 或 **改名/拆包**（与 [OPERATION](../../../../../../docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md) 中 UCM / pro-audio 互斥说明一致）。
+
+## 手工安装（调试）
+
+```bash
+sudo cp -a reference/ucm2/conf.d/sof-rt5682 /usr/share/alsa/ucm2/conf.d/
+sudo cp -a reference/ucm2/GoogleKaisa /usr/share/alsa/ucm2/
+sudo alsactl init # 或重登 / 重启 pipewire
+systemctl --user restart wireplumber pipewire pipewire-pulse
+```
+
+## 与 WirePlumber **`50-kaisa-sof-rt5682-hdmi.conf` 的互斥**
+
+- **UCM 模式（本 overlay）**：依赖 **ACP** 的 profile/端口；**请勿**再使用强制 **`device.profile = pro-audio`** 的片段，否则仍易出现 **多路 `pro-output-*` 常驻**。
+- **过渡 pro-audio 模式**：保留现有 `wireplumber.conf.d` 片段；**不要**同时叠加本 UCM 覆盖（二选一）。
+
+## 校验（可选）
+
+若已安装 **`alsa-utils`**：
+
+```bash
+alsaucm -c sof-rt5682 list _verbs
+alsaucm -c sof-rt5682 set _verb HiFi list _devices
+```
+
+插拔 HDMI 时对照 **`amixer -c0`** 中 **`HDMI/DP,pcm=N` Jack** 与 **`IEC958',N`**。
+
+## 实机验收表（勾选）
+
+| 步骤 | 预期 |
+|------|------|
+| 仅接模拟 / 不接 HDMI | HDMI 相关输出不对「可用路由」误导（依桌面实现） |
+| 接 HDMI，Jack on | 对应 **IEC958** on 后有声 |
+| 拔线 Jack off | 该路不应再被选为有效 HDMI 输出 |
+
+---
+
+_控件名以本机 `amixer` 为准；若 `Headphone`/`IEC958` 命名不同，需改 `HiFi.conf` 后重测。_
--- a/debian/rules
+++ b/debian/rules
@@ -0,0 +1,3 @@
+#!/usr/bin/make -f
+%:
+	dh $@
--- a/docs/INDEX.md
+++ b/docs/INDEX.md
@@ -0,0 +1,9 @@
+# 文档索引
+
+与根 [README.md](../README.md) 相同：**仅**下列为当前维护文档。
+
+| 文档 | 说明 |
+| ---- | ---- |
+| [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 复现与验收 |
+| [README.md](README.md) | 本目录说明 |
--- a/docs/README.md
+++ b/docs/README.md
@@ -0,0 +1,12 @@
+# `docs/` 说明
+
+本目录仅保留 **已实机验证** 的 PipeWire / deb 技术路线：
+
+| 文档 | 内容 |
+| ---- | ---- |
+| [linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md](linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md) | WirePlumber、`50-kaisa-sof-rt5682-hdmi.conf`、pro-audio / UCM、deb、基线采集 |
+| [linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md](linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md) | deb 安装与手动验收 |
+
+附属文件：`linux-hdmi/wireplumber/50-kaisa-sof-rt5682-hdmi.conf`、`linux-hdmi/systemd-user/kaisa-hdmi-iec958-pipewire.service`。
+
+仓库根 [README.md](../README.md) · 路径表 [REPO_INDEX.md](../REPO_INDEX.md)。
--- a/docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md
+++ b/docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md
@@ -0,0 +1,292 @@
+# 操作：Kaisa（sof-rt5682）Ubuntu 上 HDMI 出声与 WirePlumber 固化
+
+**适用**：Google **Kaisa**（如 `Google-Kaisa-rev4`）、PipeWire + WirePlumber（Ubuntu 24.04 常见）、声卡为 **`alsa_card.pci-0000_00_1f.3-platform-cml_rt5682_def`**（若 PCI 路径不同需改配置）。
+
+---
+
+## 路径选择（pro-audio 与 UCM，先选哪条）
+
+| 目标 | 做法 |
+|------|------|
+| **先确认 HDMI 能否出声（对照实验）** | **pro-audio**：把 **[`50-kaisa-sof-rt5682-hdmi.conf`](wireplumber/50-kaisa-sof-rt5682-hdmi.conf)** 放到 **`~/.config/wireplumber/wireplumber.conf.d/`**（文件名以 **`.conf`** 结尾），**`systemctl --user restart wireplumber pipewire pipewire-pulse`**，再 **`pactl set-card-profile <卡名> pro-audio`**、**`pactl set-default-sink`** 指到 **`pro-output-2`**（或当前 Jack 对应路），按 §4.2 打开对应 **`IEC958',N`**，最后 **`paplay` / `speaker-test -D pulse`**。 |
+| **长期「无 Jack 不误导」、桌面端口模型** | **UCM**：安装 overlay 后 **移走** 上述 WirePlumber 片段，依赖 WirePlumber 按 UCM 启用 **`HDMI1/2/3`**；与 pro-audio **互斥**（见下 §2.3）。 |
+
+**建议顺序**：先走 **pro-audio** 验证硬件与 PipeWire 路由；**有声之后**再决定继续 **修 UCM**（例如消除 **`Failed to enable ucm device HDMI*`**）或 **长期保留 pro-audio**。**「自动屏蔽未插入的 HDMI」** 依赖 UCM 或自写策略，见 §2.3，应在 **HDMI 已能出声** 之后再做。
+
+**若已安装 `kaisa-hdmi-pipewire-fix` 却未卸载**：deb 会把 **UCM2** 装入 **`/usr/share/alsa/ucm2/`**（如 **GoogleKaisa**）。仅恢复 **`50-kaisa-…conf`** 时，WirePlumber **仍会按 UCM 做端口可用性**，未插线的 HDMI 可能继续**不可用 / 像被「隐藏」**，与「全开 pro-audio 对照」不一致。要做**干净 pro-audio 基线**：先 **`sudo apt purge kaisa-hdmi-pipewire-fix`**，再按上文复制 WirePlumber 片段。系统自带的 **`alsa-ucm-conf`** 仍可能提供通用 **`sof-rt5682`** 配置；若仍异常，以本机 **`alsaucm` / `pactl list cards`** 为准。
+
+---
+
+## 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** | 该路 **未检测到显示器**，勿用 **`plughw:0,3`** / **`0,4`** 指望有声；对齐 **Jack=on** 的 pcm 与物理口。 |
+| **`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` 提高 HDMI 相对模拟口的 `priority.session`**：HDMI sink **可用且优先级更高** 时，WirePlumber 倾向将其设为 **默认输出**；拔出后回退到模拟（以本机行为为准）。
+
+仓库内 **示例文件**（可复制到上述目录）：
+
+- [`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
+```
+
+**优先级（示例文件内）**：`pro-output-0`（模拟）**1000**；`pro-output-3` **1090**；`pro-output-4` **1095**；`pro-output-2`（HDMI1）**1100**。多路 HDMI 同时存在时 **HDMI1 优先**；若你常接 **HDMI2/3**，可把对应 `node.name` 的优先级调到 **高于 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`** 查看与切换。若期望 **插拔与可用性严格对应、并在设置里以「端口」形式出现**，长期更依赖 **ALSA UCM（`alsa-ucm-conf` 等）** 与栈的集成，而非仅 WirePlumber 静态规则。
+
+### 与「无 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** 驱动路由，让 **未接线的 HDMI** 不成为可选输出（**更接近** Windows/桌面对「无效口」的处理）；**代价**是与 **强制 pro-audio 一次性拉满多路** 的路线不同，需单独调通 **Kaisa** 的 UCM 与 **IEC958**（详见 **[reference/ucm2/README.md](../../reference/ucm2/README.md)** 与 §2.3 互斥说明）。
+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 路线或自定义策略**，而不是假定 **单靠一个与当前 `50-*.conf` 同类的静态片段** 即可覆盖。
+
+### UCM 模式 vs pro-audio 模式（互斥）
+
+| 模式 | 做法 | 适用 |
+|------|------|------|
+| **pro-audio（§2 过渡）** | **`50-kaisa-sof-rt5682-hdmi.conf`** 强制 **`device.profile = pro-audio`** + **IEC958**（**`pactl`/`amixer`**，§4.2） | 快速多路 **`pro-output-*`**、先保证出声 |
+| **UCM（产品目标）** | 安装 **[reference/ucm2/](../../reference/ucm2/README.md)** 至 **`/usr/share/alsa/ucm2/`**（或 **`apt install kaisa-hdmi-pipewire-fix`**），让 **ACP** 按 **JackControl** 暴露路由 | **无 Jack 不误导**、更接近桌面「端口」模型 |
+
+**不要同时使用**：启用 **UCM overlay** 时，请 **移走或禁用** **`~/.config/wireplumber/.../50-kaisa-sof-rt5682-hdmi.conf`** 以及 **系统级** **`/etc/wireplumber/...`** 中同类片段（若由 deb 安装，见 §4.4 **UCM 优先时**说明），否则 **强制 pro-audio** 仍会盖过 **UCM 的 profile 语义**。改完后 **`systemctl --user restart wireplumber pipewire pipewire-pulse`**。
+
+**验证 UCM 是否生效**：`pactl list cards` 中活动配置宜为 **HiFi** 等 **UCM 定义的 profile**，而非长期锁在 **pro-audio**（以本机 **`pactl`** 为准）。
+
+**UCM 模式下 HDMI 无声（IEC958）**：与 §4.2 相同根因——**`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. 再按 §4.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**。
+
+**自动化（未随 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 时是否弹出输出选择** 由 **桌面/会话** 决定。
+
+---
+
+## 3. 验证
+
+```bash
+pactl list cards
+```
+
+**活动配置** 应为 **`pro-audio`**。
+
+```bash
+pactl get-default-sink
+pactl list short sinks
+```
+
+插入 HDMI（**Jack 对应的那路**，如 **pcm=2**）后，默认 sink 宜为 **`...pro-output-2`**（或你优先级最高的那路）。
+
+**出声测试（推荐）**：桌面默认用 PipeWire 时，声卡常被其占用；此时 **`speaker-test -D plughw:0,2`** 会报 **打开错误: -16（设备或资源忙，EBUSY）**，属正常现象。请先 **`pactl set-default-sink`** 指到目标 HDMI sink，再经 **Pulse 兼容设备** 测试：
+
+```bash
+speaker-test -D pulse -c2 -t sine -f 440 -l 3
+```
+
+或 **`paplay /usr/share/sounds/alsa/Front_Center.wav`**（同样走当前默认 sink）。
+
+**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 片段若仍在，常见原因不是 profile 丢失，而是 **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 名以本机为准）：
+
+```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   # 或按 §4.2 对 pcm=3/4 开 IEC958',1 / ',2
+```
+
+再用 **`speaker-test -D pulse`**（或 **`paplay`**）确认经 PipeWire 的默认 sink 是否有声；**`-D plughw:…`** 在 PipeWire 占用声卡时会出现 **EBUSY (-16)**。
+
+**登录自动执行（可选，自建）**：自行编写 **user systemd** oneshot（**`pactl`/`amixer`**），**`After=pipewire-pulse.service`**，必要时 **`ExecStartPre=/bin/sleep 2`**。仓库 **[`systemd-user/kaisa-hdmi-iec958-pipewire.service`](systemd-user/kaisa-hdmi-iec958-pipewire.service)** 仅为示例，**需自备** **`ExecStart`** 所指可执行文件（deb **不**提供）。
+
+### 4.1a 换了 HDMI 口，系统里「默认输出」没跟着变，但仍有声
+
+**常见原因**
+
+1. **默认 sink 是「粘住」的**：GNOME / 会话会记住 **`pactl get-default-sink`**；WirePlumber 又用 **`priority.session`** 把某一路（示例里是 **`pro-output-2`**）抬成首选。**换线**不等于自动把默认 sink 改到「新插上、Jack 刚亮」的那一路 **`pro-output-3` / `pro-output-4`**。
+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** 的那一路。
+
+**另见**：若 **`journalctl --user -u wireplumber`** 有 **`Failed to enable ucm device HDMI2`**（或 **HDMI1** / **HDMI3**），且 **`pipewire`** 仅对 **`HiFi__hw_sofrt5682_3__sink`**（或 `_2__` / `_4__`）报错，则为 **UCM SectionDevice 启用失败**（与 **[reference/ucm2/GoogleKaisa/sof-rt5682/HiFi.conf](../../reference/ucm2/GoogleKaisa/sof-rt5682/HiFi.conf)** 中 **HDMI1/2/3** 对应 **device 2/3/4** 一致）。宜 **换插到另一 HDMI 物理口** 或 **`alsaucm -c sof-rt5682 set _verb HiFi set _device …`** 单独验证；详见 **[next.md](../../next.md)**（单命令：安装 + 诊断）。
+
+### 4.3 登录自动恢复（规划中）
+
+**根因**：**`IEC958',0`（pcm=2）被关** → HDMI 无声（PipeWire 可看似正常）；完整 **「切 pro-audio + 默认 HDMI sink + 开 IEC958」** 自动化**尚未**作为稳定工具随 **`kaisa-hdmi-pipewire-fix`** 发布。
+
+**当前**：请用 §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 包（系统级交付）
+
+仓库 **`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 说明；可选打包 **OPERATION**）。
+
+**0.2.x 及更早** 曾附带 **`kaisa-restore-*`** 与 user systemd 单元；**0.3.0** 起移除，直至手工验证与自动化策略定型。
+
+**UCM 优先时**：按上文 **「UCM 模式 vs pro-audio 模式」** 移走 **`50-kaisa-…`**，避免与 **强制 pro-audio** 叠用。发布前请改 **`debian/control`**、**`debian/changelog`**、**`debian/copyright`** 中的维护者与许可证说明。
+
+**说明**
+
+- **更广分发**：可将该 deb 放入自建 **APT 仓库 / PPA**；更长远的修复仍是 **ALSA UCM / 上游** 在适用机型上 **默认打开 IEC958**（与发行版/上游沟通，不在本仓库另文维护）。
+
+### 4.5 基线备份与恢复（Ubuntu 默认 / 安装 deb 前状态）
+
+**目的**：在**首次安装** `kaisa-hdmi-pipewire-fix` 或做大改之前，把当前机的音频相关路径与诊断**落盘**，并在后续工作中可**尽量恢复**到该状态。
+
+**为何 `reinstall alsa-ucm-conf`**：本 deb 会向 **`/usr/share/alsa/ucm2/conf.d/sof-rt5682/sof-rt5682.conf`** 安装与 **`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
+```
+
+生成文件通常包括：**`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。
+
+---
+
+## 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/REPRO_Kaisa_Deb_ProAudio_Manual.md
+++ b/docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md
@@ -0,0 +1,155 @@
+# 手顺：与 `kaisa-hdmi-pipewire-fix` deb 等价的 pro-audio 路径（可复现）
+
+**目的**：在真机上**不依赖**写死的 `wpctl set-profile 46 4`，按 deb 交付物复现「WirePlumber 片段 + `pro-audio` + 默认 HDMI sink + IEC958」，用于打包前验收。
+
+**相关**：deb 安装内容见 [OPERATION_PipeWire_Kaisa_HDMI.md](OPERATION_PipeWire_Kaisa_HDMI.md) §4.4；pro-audio 路径见同文档 §2（复制 `50-kaisa`、重启栈，再 **`pactl set-card-profile … pro-audio`**）。
+
+### 常用检查（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` 重复（见 [OPERATION](OPERATION_PipeWire_Kaisa_HDMI.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 消失**：在 **GNOME 设置 → 声音** 里用系统自带「测试」或切换输出时，**有可能**把声卡**又改回 `stereo-fallback`**，`wpctl status` 里 **Sinks** 会只剩「立体声」。属 **Pro-audio 与桌面会话抢 profile** 的常见现象（WirePlumber 0.4 尤甚）。**处理**：再执行一次 **`pactl set-card-profile … pro-audio`** 并按 §4 开 **`IEC958`**；试声优先用终端 **`pw-play` / `paplay`**（见 OPERATION §2「测试扬声器」说明）。
+
+- **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`**），并按 [OPERATION §4.2](OPERATION_PipeWire_Kaisa_HDMI.md) 打开对应 **`IEC958',N`**。
+
+若未安装 **`pulseaudio-utils`**：用 **`wpctl set-profile`** + **`wpctl set-default`**（见 OPERATION §4.1），再 **`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 打包前建议
+
+1. 在 **目标 Ubuntu 版本**（如 24.04）上按本文 **0→5** 跑通一次。  
+2. 再 **`./scripts/build-deb.sh`** 安装 deb，**重复 §5 验收**（此时片段在 `/etc/wireplumber/...`，仍无随包 `/usr/bin` 工具）。  
+3. 若走 **UCM** 路线，**移走** `50-kaisa-…conf` 后验收（与 OPERATION「互斥」一致）。
--- a/docs/linux-hdmi/systemd-user/kaisa-hdmi-iec958-pipewire.service
+++ b/docs/linux-hdmi/systemd-user/kaisa-hdmi-iec958-pipewire.service
@@ -0,0 +1,15 @@
+# 示例：登录后执行「pro-audio + 默认 sink + IEC958」——需自备可执行文件（deb ≥0.3.0 不随包提供脚本）。
+# 将 @@HOME@@ 换为 $HOME；ExecStart 可指向你自己写的 shell，内嵌 §4.1/§4.2 的 pactl/amixer 命令。
+[Unit]
+Description=Kaisa SOF rt5682: PipeWire pro-audio + IEC958 (HDMI)
+After=pipewire-pulse.service
+Wants=pipewire-pulse.service
+
+[Service]
+Type=oneshot
+RemainAfterExit=yes
+ExecStartPre=/bin/sleep 2
+ExecStart=@@HOME@@/.local/bin/kaisa-restore-pipewire-hdmi
+
+[Install]
+WantedBy=default.target
--- a/help.md
+++ b/help.md
@@ -0,0 +1,80 @@
+# BMad Help 速查
+
+## BMad Help 是做什么的
+
+用来：**判断你在 BMad 流程里大致处在哪一步**、**下一步该用哪个技能**、以及**怎么调用**（技能名、菜单码、可选参数）。不要求你背全目录。
+
+---
+
+## 本仓库里已装模块（精简版）
+
+### Core（随时可用）
+
+| 菜单码 | 名称 | 技能名 | 用途（摘自目录） |
+| ------ | ---- | ------ | ---------------- |
+| **BH** | BMad Help | `bmad-help` | 就是当前这条帮助 |
+| **BSP** | Brainstorming | `bmad-brainstorming` | 早期发散、卡住时想点子 |
+| **PM** | Party Mode | `bmad-party-mode` | 多角色 / 多视角讨论 |
+| **ID** | Index Docs | `bmad-index-docs` | 让模型先「索引」文档再深入 |
+| **SD** | Shard Document | `bmad-shard-doc` | 长文档拆分（常指 >500 行） |
+| **EP / ES** | Editorial Review | `bmad-editorial-review-prose` / `structure` | 润色 / 调结构 |
+| **AR / ECH** | Adversarial / Edge Case | `bmad-review-adversarial-general` / `edge-case-hunter` | 交付前挑刺、补边界 |
+| **DG** | Distillator | `bmad-distillator` | 把长文压成保留信息的 distillate |
+
+### BMad Method（典型软件交付链，带阶段）
+
+阶段大致为：**1-analysis → 2-planning → 3-solutioning → 4-implementation**。
+
+常用条目示例（完整列表见 `_bmad/_config/bmad-help.csv`）：
+
+| 阶段 | 示例技能（菜单码） |
+| ---- | ------------------ |
+| **1-analysis** | `bmad-product-brief` **[CB]**、`bmad-domain-research` **[DR]**、`bmad-market-research` **[MR]**、`bmad-technical-research` **[TR]**、`bmad-brainstorming` **[BP]** … |
+| **2-planning** | `bmad-create-prd` **[CP]**、`bmad-create-ux-design` **[CU]**、`bmad-validate-prd` **[VP]** … |
+| **3-solutioning** | `bmad-create-architecture` **[CA]**、`bmad-create-epics-and-stories` **[CE]**、`bmad-check-implementation-readiness` **[IR]** … |
+| **4-implementation** | `bmad-sprint-planning` **[SP]**、`bmad-create-story` **[CS]**、`bmad-dev-story` **[DS]**、`bmad-code-review` **[CR]** … |
+| **随时** | `bmad-document-project` **[DP]**、`bmad-generate-project-context` **[GPC]**、`bmad-quick-dev` **[QQ]**、`bmad-correct-course` **[CC]** … |
+
+在 Cursor 里一般是：**用自然语言说明要做的事**，或按安装器提供的**斜杠命令 / 技能名**调用（与 `npx bmad-method install` 生成的集成一致）。
+
+### Creative Intelligence Suite（创意 / 方法套件）
+
+| 菜单码 | 名称 | 技能名 |
+| ------ | ---- | ------ |
+| **IS** | Innovation Strategy | `bmad-cis-innovation-strategy` |
+| **PS** | Problem Solving | `bmad-cis-problem-solving` |
+| **DT** | Design Thinking | `bmad-cis-design-thinking` |
+| **BS** | Brainstorming | `bmad-brainstorming` |
+| **ST** | Storytelling | `bmad-cis-storytelling` |
+
+### BMad Builder（搭技能 / 工作流 / 模块）
+
+例如 **[BA]** 建 Agent、**[BW]** 建 Workflow、**[CM]** 建模块等（见 `_bmad/_config/bmad-help.csv` 前几行）。
+
+---
+
+## 结合本仓库（Chromebox / HDMI）
+
+### 本仓库当前产品目标（Kaisa 桌面音频）
+
+**权威操作与交付**（PipeWire / pro-audio / deb / UCM）：**[docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md](docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md)**、**[reference/ucm2/README.md](reference/ucm2/README.md)**。
+
+在此目标下，BMad 更偏 **棕地攻关 + 文档/交付对齐**。常用下一步：
+
+1. **`bmad-document-project` [DP]**：扩展/更新 `docs/linux-hdmi/` 与 **deb 范围**一致说明。
+2. **`bmad-generate-project-context` [GPC]**：把目标、路径、仓库布局收成代理可用的 **project-context**（若尚未生成）。
+3. **`bmad-cis-problem-solving` [PS]**：UCM 草稿卡壳、Jack/控件映射不清时做结构化拆解。
+4. **`bmad-technical-research` [TR]**：面向 **`alsa-ucm-conf` 上游 MR** 或发行版沟通时整理选项与引用。
+
+若你**改走**标准 BMad Method **从 0 做产品文档**，再从 **[CB] 产品简报**或 **[CP] PRD** 开始会更顺（与 **OPERATION** 并行时，注意 PRD 与实机路线一致）。
+
+---
+
+## 使用建议（技能里写的）
+
+- 重要长流程尽量在**新的对话窗口**里单独跑一个技能，上下文更干净。
+- 更全的条目与依赖关系以 `_bmad/_config/bmad-help.csv` 为准；各模块输出默认可在 `_bmad-output`（见 `_bmad/core/config.yaml`）。
+
+**完整 BMad 目录（中文全表）**：根目录 [bmad-help.zh-CN.md](bmad-help.zh-CN.md)（由 `_bmad/scripts/render_bmad_help_zh_cn.py` 根据 CSV 生成）。
+
+若你接下来是想「写 PRD / 架构」还是「继续攻 HDMI 内核问题」，可以只选**一条**最优先的技能深入（仍用中文）。
--- a/next.md
+++ b/next.md
@@ -0,0 +1,13 @@
+# next
+
+[docs/README.md](docs/README.md) · [OPERATION_PipeWire_Kaisa_HDMI.md](docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md) · [reference/ucm2/README.md](reference/ucm2/README.md)
+
+- **安装 deb 前基线 / 事后恢复**：[scripts/capture-ubuntu-audio-baseline.sh](scripts/capture-ubuntu-audio-baseline.sh) · [scripts/restore-ubuntu-audio-baseline.sh](scripts/restore-ubuntu-audio-baseline.sh)（详见 [OPERATION_PipeWire_Kaisa_HDMI.md](docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md) §4.5）。
+- **pro-audio / UCM / deb 手顺**：[OPERATION](docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md)（§2 起）；与 deb 等价的可复现验收：[REPRO_Kaisa_Deb_ProAudio_Manual.md](docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md)。
+
+```bash
+cd /path/to/chromebox_10th_audio_driver
+./scripts/capture-ubuntu-audio-baseline.sh
+# … 做改动 / 装 deb …
+./scripts/restore-ubuntu-audio-baseline.sh
+```
--- a/reference/chromeos-ubuntu-sound-diffs/README.md
+++ b/reference/chromeos-ubuntu-sound-diffs/README.md
@@ -0,0 +1,5 @@
+# ChromeOS 5.15 ↔ Ubuntu HWE（可选对照）
+
+本目录用于存放你在本机对两棵内核树 **`diff -u`** / **`diff -rq`** 的输出（例如 **`diff-u_sound_soc_….txt`**）。**仓库不再附带**自动生成脚本；在 **`chromiumos_kernel/v5.15`** 与 **`apt source linux-hwe-6.17`** 解压目录之间自行对照即可。
+
+默认可将生成物放于此处；**`diff-u_*.txt`** 仍由根目录 **`.gitignore`** 忽略，避免大段 diff 误入版本库。
--- a/reference/ucm2/README.md
+++ b/reference/ucm2/README.md
@@ -0,0 +1,49 @@
+# Kaisa UCM2 overlay（`sof-rt5682`）
+
+本目录为 **alsa-ucm-conf** 风格的 **UCM2** 草稿，目标：**Jack off 时 HDMI 路由对 ACP/桌面不表现为可随意可用的输出**（与强制 **`pro-audio`** 的 WirePlumber 策略不同，见 [docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md](../../docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md)「UCM 模式 vs pro-audio 模式」）。
+
+## 布局
+
+| 路径（相对 `ucm2/` 根） | 说明 |
+|-------------------------|------|
+| `conf.d/sof-rt5682/sof-rt5682.conf` | 卡入口，匹配 ALSA **card name** `sof-rt5682` |
+| `GoogleKaisa/sof-rt5682/HiFi.conf` | HiFi：`Port1` + **HDMI1/2/3**，**JackControl** + **`IEC958',N`** |
+
+上游 **alsa-ucm-conf** 若日后增加同名 `conf.d/sof-rt5682/`，与本仓库 **deb 同时安装会冲突** — 优先 **合并上游** 或 **改名/拆包**（与 [OPERATION](../../docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md) 中 UCM / pro-audio 互斥说明一致）。
+
+## 手工安装（调试）
+
+```bash
+sudo cp -a reference/ucm2/conf.d/sof-rt5682 /usr/share/alsa/ucm2/conf.d/
+sudo cp -a reference/ucm2/GoogleKaisa /usr/share/alsa/ucm2/
+sudo alsactl init # 或重登 / 重启 pipewire
+systemctl --user restart wireplumber pipewire pipewire-pulse
+```
+
+## 与 WirePlumber **`50-kaisa-sof-rt5682-hdmi.conf` 的互斥**
+
+- **UCM 模式（本 overlay）**：依赖 **ACP** 的 profile/端口；**请勿**再使用强制 **`device.profile = pro-audio`** 的片段，否则仍易出现 **多路 `pro-output-*` 常驻**。
+- **过渡 pro-audio 模式**：保留现有 `wireplumber.conf.d` 片段；**不要**同时叠加本 UCM 覆盖（二选一）。
+
+## 校验（可选）
+
+若已安装 **`alsa-utils`**：
+
+```bash
+alsaucm -c sof-rt5682 list _verbs
+alsaucm -c sof-rt5682 set _verb HiFi list _devices
+```
+
+插拔 HDMI 时对照 **`amixer -c0`** 中 **`HDMI/DP,pcm=N` Jack** 与 **`IEC958',N`**。
+
+## 实机验收表（勾选）
+
+| 步骤 | 预期 |
+|------|------|
+| 仅接模拟 / 不接 HDMI | HDMI 相关输出不对「可用路由」误导（依桌面实现） |
+| 接 HDMI，Jack on | 对应 **IEC958** on 后有声 |
+| 拔线 Jack off | 该路不应再被选为有效 HDMI 输出 |
+
+---
+
+_控件名以本机 `amixer` 为准；若 `Headphone`/`IEC958` 命名不同，需改 `HiFi.conf` 后重测。_
--- a/scripts/capture-ubuntu-audio-baseline.sh
+++ b/scripts/capture-ubuntu-audio-baseline.sh
@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+# 在安装 kaisa-hdmi-pipewire-fix 或其它大改前，采集「Ubuntu / 当前机」音频基线并落盘。
+# 输出目录默认：audio_topology/baseline-stash/<时间戳>_<hostname>/
+# 用法：./scripts/capture-ubuntu-audio-baseline.sh [输出目录]
+# 详见：docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md「基线备份与恢复」
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+STAMP="$(date +%Y%m%d_%H%M%S)_$(hostname)"
+
+if [[ -n "${1:-}" ]]; then
+	STASH="$(realpath "$1")"
+else
+	STASH="${REPO_ROOT}/audio_topology/baseline-stash/${STAMP}"
+fi
+
+mkdir -p "$STASH/backup/root"
+
+write_manifest() {
+	local mf="$STASH/manifest.txt"
+	{
+		echo "# capture-ubuntu-audio-baseline"
+		echo "created_iso: $(date -Iseconds)"
+		echo "hostname: $(hostname)"
+		echo "stash_dir: $STASH"
+		echo ""
+		echo "## uname"
+		uname -a
+		echo ""
+		echo "## dpkg (相关包)"
+		dpkg -l 2>/dev/null | grep -E '^(ii|rc)\s+(alsa-ucm-conf|wireplumber|pipewire|pipewire-pulse|kaisa-hdmi-pipewire-fix)\s' || true
+		echo ""
+		if dpkg -s kaisa-hdmi-pipewire-fix &>/dev/null; then
+			echo "## kaisa-hdmi-pipewire-fix: installed"
+			dpkg -s kaisa-hdmi-pipewire-fix 2>/dev/null | grep -E '^(Package|Version|Status):' || true
+		else
+			echo "## kaisa-hdmi-pipewire-fix: not installed"
+		fi
+		echo ""
+		echo "## deb 相关路径（存在性与 sha256）"
+	} >"$mf"
+
+	local paths=(
+		/etc/wireplumber/wireplumber.conf.d/50-kaisa-sof-rt5682-hdmi.conf
+		/usr/share/alsa/ucm2/conf.d/sof-rt5682/sof-rt5682.conf
+		/usr/share/alsa/ucm2/GoogleKaisa/sof-rt5682/HiFi.conf
+	)
+	local p
+	for p in "${paths[@]}"; do
+		if [[ -e "$p" ]]; then
+			echo "PATH $p exists=yes" >>"$mf"
+			if [[ -f "$p" ]]; then
+				sha256sum "$p" >>"$mf" 2>/dev/null || echo "(sha256sum failed)" >>"$mf"
+			fi
+		else
+			echo "PATH $p exists=no" >>"$mf"
+		fi
+	done
+	echo "" >>"$mf"
+	echo "## /usr/share/doc/kaisa-hdmi-pipewire-fix/" >>"$mf"
+	if [[ -d /usr/share/doc/kaisa-hdmi-pipewire-fix ]]; then
+		ls -la /usr/share/doc/kaisa-hdmi-pipewire-fix >>"$mf" 2>&1 || true
+	else
+		echo "(目录不存在)" >>"$mf"
+	fi
+}
+
+backup_vendor_ucm() {
+	local src="/usr/share/alsa/ucm2/conf.d/sof-rt5682/sof-rt5682.conf"
+	if [[ -f "$src" ]]; then
+		install -D -m0644 "$src" "$STASH/backup/root/usr/share/alsa/ucm2/conf.d/sof-rt5682/sof-rt5682.conf"
+		echo "已备份 vendor UCM: $src -> backup/root/..."
+	fi
+}
+
+backup_user_wireplumber() {
+	local d="${HOME}/.config/wireplumber/wireplumber.conf.d"
+	local names=()
+	if [[ -d "$d" ]]; then
+		shopt -s nullglob
+		local f
+		for f in "$d"/*; do
+			[[ -e "$f" ]] || continue
+			local b
+			b="$(basename "$f")"
+			if [[ "$b" == *kaisa* ]] || [[ "$b" == 50-kaisa* ]]; then
+				names+=("$b")
+			fi
+		done
+	fi
+	if ((${#names[@]} > 0)); then
+		tar -C "$d" -czf "$STASH/user-wireplumber-conf.tar.gz" "${names[@]}"
+		echo "已打包用户 WirePlumber 片段: ${names[*]} -> user-wireplumber-conf.tar.gz"
+	else
+		echo "(未找到 ~/.config/wireplumber/... 下含 kaisa 的片段，跳过 user-wireplumber-conf.tar.gz)"
+	fi
+}
+
+pack_system_overlay() {
+	if [[ -f "$STASH/backup/root/usr/share/alsa/ucm2/conf.d/sof-rt5682/sof-rt5682.conf" ]]; then
+		tar -C "$STASH/backup/root" -czf "$STASH/system-overlay.tar.gz" \
+			usr/share/alsa/ucm2/conf.d/sof-rt5682/sof-rt5682.conf
+		echo "已生成 system-overlay.tar.gz（可配合 restore 还原安装 deb 前的 vendor sof-rt5682.conf）"
+	else
+		echo "(未备份 vendor sof-rt5682.conf，不生成 system-overlay.tar.gz)"
+	fi
+}
+
+write_manifest
+backup_vendor_ucm
+backup_user_wireplumber
+pack_system_overlay
+
+TOPO="$STASH/topology.txt"
+echo "正在调用 collect_linux_audio_topology.sh -> $TOPO"
+bash "${REPO_ROOT}/audio_topology/collect_linux_audio_topology.sh" "$TOPO"
+
+echo ""
+echo "========== 基线已写入: $STASH =========="
+echo "  manifest.txt          — 包状态与 deb 路径清单"
+echo "  topology.txt        — 完整音频拓扑"
+echo "  system-overlay.tar.gz — 若存在：vendor sof-rt5682.conf 快照"
+echo "  user-wireplumber-conf.tar.gz — 若存在：用户 kaisa WirePlumber 片段"
+echo ""
+echo "恢复至「尽量接近本次采集时」的系统文件状态："
+echo "  ./scripts/restore-ubuntu-audio-baseline.sh $STASH"
+echo ""
+echo "若曾启用 §4.3 user systemd 自动 restore，恢复基线前可先禁用该 user 单元（见 OPERATION）。"
--- a/scripts/restore-ubuntu-audio-baseline.sh
+++ b/scripts/restore-ubuntu-audio-baseline.sh
@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# 将系统尽量恢复到某次 capture-ubuntu-audio-baseline 采集时的「安装 deb 前」文件状态。
+# 典型：purge kaisa-hdmi-pipewire-fix → reinstall alsa-ucm-conf → 可选解压备份 tar。
+# 用法：./scripts/restore-ubuntu-audio-baseline.sh [基线目录]
+#       若不传参数，使用 audio_topology/baseline-stash/ 下最近修改的子目录。
+# 需要：sudo（apt、解压到 /）；建议在桌面会话下执行以便重启 PipeWire。
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+resolve_stash() {
+	if [[ -n "${1:-}" ]]; then
+		realpath "$1"
+		return
+	fi
+	local latest
+	latest="$(ls -td "${REPO_ROOT}/audio_topology/baseline-stash"/*/ 2>/dev/null | head -1 || true)"
+	if [[ -z "$latest" ]]; then
+		echo "未找到基线目录。请先运行: ${REPO_ROOT}/scripts/capture-ubuntu-audio-baseline.sh" >&2
+		exit 1
+	fi
+	realpath "${latest%/}"
+}
+
+STASH="$(resolve_stash "${1:-}")"
+
+if [[ ! -f "$STASH/manifest.txt" ]]; then
+	echo "不是有效基线目录（缺少 manifest.txt）: $STASH" >&2
+	exit 1
+fi
+
+echo "========== 使用基线: $STASH =========="
+echo "manifest 创建于:"
+head -5 "$STASH/manifest.txt"
+echo ""
+
+if ! command -v sudo &>/dev/null; then
+	echo "需要 sudo 以执行 apt。" >&2
+	exit 1
+fi
+
+if dpkg -s kaisa-hdmi-pipewire-fix &>/dev/null; then
+	echo ">>> apt purge kaisa-hdmi-pipewire-fix"
+	sudo apt purge -y kaisa-hdmi-pipewire-fix
+else
+	echo "(未安装 kaisa-hdmi-pipewire-fix，跳过 purge)"
+fi
+
+echo ">>> apt install --reinstall alsa-ucm-conf"
+sudo apt install --reinstall -y alsa-ucm-conf
+
+if [[ -f "$STASH/system-overlay.tar.gz" ]]; then
+	echo ">>> 解压 system-overlay.tar.gz -> /（覆盖 vendor sof-rt5682.conf，与 reinstall 通常等价）"
+	sudo tar -xzf "$STASH/system-overlay.tar.gz" -C /
+else
+	echo "(无 system-overlay.tar.gz，仅依赖 alsa-ucm-conf reinstall)"
+fi
+
+if [[ -f "$STASH/user-wireplumber-conf.tar.gz" ]]; then
+	echo ">>> 解压 user-wireplumber-conf.tar.gz -> ${HOME}/.config/wireplumber/wireplumber.conf.d/"
+	mkdir -p "${HOME}/.config/wireplumber/wireplumber.conf.d"
+	tar -xzf "$STASH/user-wireplumber-conf.tar.gz" -C "${HOME}/.config/wireplumber/wireplumber.conf.d"
+	echo "已恢复用户 WirePlumber 片段。"
+else
+	echo "(无 user-wireplumber-conf.tar.gz，跳过用户配置)"
+fi
+
+if systemctl --user is-system-running &>/dev/null; then
+	echo ">>> systemctl --user restart wireplumber pipewire pipewire-pulse"
+	systemctl --user restart wireplumber pipewire pipewire-pulse 2>/dev/null || {
+		echo "（user 会话重启 pipewire 失败，请手动重登或重启）" >&2
+	}
+else
+	echo "（无可用 user systemd 会话，请登录图形界面后执行: systemctl --user restart wireplumber pipewire pipewire-pulse）"
+fi
+
+echo ""
+echo "========== 恢复步骤已完成 =========="
+echo "若曾启用登录自动 restore（user systemd），恢复前可先禁用 kaisa-hdmi-iec958-pipewire 单元（见 OPERATION §4.3 / §4.5）。"
+echo "建议核对: pactl list cards | head -40 ; aplay -l"