chromebox_10th_audio_driver/_bmad-output/planning-artifacts/prd.md

stepsCompleted, inputDocuments, workflowType, brownfield_synthesis, synthesis_note, last_edited

stepsCompleted	inputDocuments	workflowType	brownfield_synthesis	synthesis_note	last_edited
prd-brownfield-synthesis-2026-04-06	README.md docs/INDEX.md docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md	prd	true	棕地仓库；经 [VP] 校验后 [EP] 修订（SC↔FR 映射、可脚本化验收附录）。	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_ProAudio.md、OPERATION_PipeWire_Kaisa_UCM_HiFi.md、REPRO_Kaisa_Deb_ProAudio_Manual.md 为准。旧名 OPERATION_PipeWire_Kaisa_HDMI.md 仅为重定向 stub。

---

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_ProAudio.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 技术路线	ProAudio / UCM 文档 覆盖 pro-audio、UCM、deb；REPRO 为验收手顺。
FR5	桌面 HDMI 操作说明	ProAudio 文档 覆盖 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（文档索引链）

test -f docs/INDEX.md
test -f docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md
test -f docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md
test -f docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md
grep -q 'OPERATION_PipeWire_Kaisa_ProAudio' 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/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md
• docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md
• docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.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] 中处理。