Initial commit

2026-04-06 21:59:41 +08:00
commit 760bdf2c9b
28 changed files with 2310 additions and 0 deletions
--- 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] 中处理。