jack
60b7cd389f
Add a more detailed --verify flow to capture Jack/ELD/subdevices, route per sink, and collect kernel error windows. Improve --fix with readiness gating, retries, and connected-only selection; document single-monitor pcm mapping behavior and ignore local logs/artifacts. Made-with: Cursor
213 lines
7.3 KiB
Markdown
213 lines
7.3 KiB
Markdown
---
|
||
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
|
||
|
||
作为一名**维护者**，
|
||
我希望 **INDEX.md** 能链到 **OPERATION**，
|
||
以便 **不必搜全库**（**FR1**）。
|
||
|
||
**验收标准：**
|
||
|
||
- **Given** 仓库根已克隆
|
||
- **When** 打开 `docs/INDEX.md`
|
||
- **Then** 存在指向 `OPERATION_PipeWire_Kaisa_UCM_HiFi.md` 的条目
|
||
|
||
### Story 1.2：（已收敛）路线图
|
||
|
||
**状态：** **`Linux_HDMI_Audio_Roadmap.md`** 与 **WORK_PROGRESS** 类长文已删除；**FR2** 以 **OPERATION** 为事实源。
|
||
|
||
### 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_UCM_HiFi.md** 说明 **UCM2 / HiFi**、**`speaker-test -D pipewire`**、**IEC958',N**、以及安装器脚本（disable + install），
|
||
以便 **排障不靠口口相传**（**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 列表摘要写入。
|