---
stepsCompleted:
  - step-01-init
  - step-02-discovery
  - step-02b-vision
  - step-02c-executive-summary
  - step-03-success
  - step-04-journeys
  - step-05-domain
  - step-06-innovation
  - step-07-project-type
  - step-08-scoping
  - step-09-functional
  - step-10-nonfunctional
  - step-11-polish
  - step-12-complete
inputDocuments:
  - README.md
  - docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md
  - docs/meta/WORK_PROGRESS.md
  - docs/linux-hdmi/CHROMEOS_KAISA_AUDIO_KERNEL_PATHS.md
  - docs/linux-hdmi/KERNEL_SRC_LINUX_HWE617_HDMI_3.5MM_PATHS.md
  - kernel-src/README.md
  - _bmad-output/project-context.md
  - _bmad-output/problem-solution-2026-04-04-linux-hdmi-kaisa.md
  - chromiumos_kernel/v5.15/
  - kernel-src/
documentCounts:
  briefCount: 0
  researchCount: 1
  brainstormingCount: 0
  projectDocsCount: 8
workflowType: prd
classification:
  projectType: developer_tool
  domain: general
  complexity: low
  projectContext: brownfield
---

# Product Requirements Document - chromebox_10th_audio_driver

**Author:** Jack  
**Date:** 2026-04-05T11:54:55+08:00

## 文档结构（目录）

| 章节 | 内容摘要 |
|------|----------|
| [Executive Summary](#executive-summary) | 问题范围、差异点、不交付项 |
| [Project Classification](#project-classification) | developer_tool / brownfield 等 |
| [Success Criteria](#success-criteria) | 用户/业务/技术成功、可量化结果 |
| [Product Scope](#product-scope) | MVP / Growth / Vision、上游后置 |
| [User Journeys](#user-journeys) | 五类旅程与能力汇总 |
| [developer_tool Specific Requirements](#developer_tool-specific-requirements) | 语言、安装、接口、迁移 |
| [Project Scoping & Phased Development](#project-scoping--phased-development) | 与路线图阶段对齐、MVP 顺序 |
| [Functional Requirements](#functional-requirements) | 能力契约 FR1–FR21 |
| [Non-Functional Requirements](#non-functional-requirements) | 隐私、文档、可复现、许可 |

**追溯链**：愿景 → 成功标准 → 用户旅程 → **FR/NFR**；实现与 Epic 应能回溯至对应条目。

## Executive Summary

本仓库将 **Google Kaisa（Chromebox 10 / Coreboot）** 在 **Linux（Ubuntu 24.04 + linux-hwe-6.17）** 下的 **HDMI 无输出 / SOF IPC 失败（典型如 `STREAM_PCM_PARAMS`、约 -5）** 问题，收敛为一条**可复现、可交接**的 **developer_tool** 路径：以 **路线图阶段**划分行动，每阶段有**可核对的完成判据**；以 **补丁、`verify-*`、自编内核构建、ChromiumOS 5.15（`chromiumos_kernel/v5.15/`）与 Ubuntu HWE（`kernel-src/`）双树 diff 与导出脚本** 支撑**同一结论在不同机器上可被重复验证**。**首要成功标准（可观察）**：他人能在**明确文档入口**下复现**构建与验证步骤**，并产出**可对齐的日志/证据**（dmesg、脚本输出等）；**周期（如换机后 ≤N 天）** 可后续在成功标准中量化。**不承诺**「限时必出声」；**承诺**路径、证据与索引分层可读。**主要受众**为**维护者本人与少数协作者**。文档治理：**路线图**管阶段与顺序；**WORK_PROGRESS** 管事实与换机/clone——卡死时以二者及预检脚本为权威入口。**明确不包含**：**ChromeOS 用户态 CRAS** 深度适配；**亦不将** **Windows 音频驱动/成套闭源驱动方案** 纳入本 PRD 交付范围（相关说明保留在仓库其他文档）。**约束**：自编内核涉及**磁盘空间、模块包完整性、Secure Boot/unsigned 安装**，以既有 `kernel-src` 与安装 OPERATION 为准，本 PRD 不展开逐步操作。

### What Makes This Special

与零散帖子或一次性操作相比，差异集中在：**（1）证据链**——从现象到 **IPC 载荷**与 **ChromiumOS ↔ Ubuntu HWE** 对照，避免仅靠换 tplg/固件试错；**（2）工具链可复现**——`PATCH=`、构建、验证与 diff 导出使重复实验成为约定；**（3）治理与期望**——防迷路、成功标准优先「可复现与可验证」，**不将「上游短期合入或发行版默认修复」** 假定为必然结果。核心洞察：失败多表现为 **hw_params / IPC 契约与固件预期不一致**；对照基准应是 **ChromiumOS 内核树与同机 trace**，而非与 Chrome 行为不对等的替代内核包。

## Project Classification

| 维度 | 取值 |
|------|------|
| **项目类型** | developer_tool |
| **领域** | general |
| **领域复杂度（CSV 维度）** | low |
| **项目语境** | brownfield |

## Success Criteria

### User Success

- **协作者 / 换机**：在**未口头交接**的前提下，仅凭 **`README` → `INDEX` → 路线图 / `WORK_PROGRESS`** 能定位当前阶段，并执行**至少一条**已文档化的验证路径（如 `verify-*`、采集脚本或 `speaker-test` 流程），得到**可对比的产出物**（日志、`collected/`、脚本退出码）。
- **「值得」时刻**：当 **`VERIFY_OK`** 或等价结论出现，或 **HDMI 播放尝试** 能产生**与路线图一致、可解释**的 dmesg（含或不含 IPC 载荷），而非「黑盒无声」。
- **情感**：从「不知道该信哪篇帖」转为「**下一步在路线图 / 修复计划里有编号**」。

### Business Success

本仓库语境下，**「业务」**指项目可持续性与可信度，而非收入指标。

- **维护诚实度**：`WORK_PROGRESS` 与路线图**阶段声明**与真机状态一致；**不宣称**尚未验证的项为已解决。
- **协作成本**：新协作者**首次**跑通文档化验证路径时的**阻塞**（缺树、缺 deb 包、浅克隆等）在 `WORK_PROGRESS` 或预检中有**明确记录与缓解链接**。
- **上游相关（顺序约束）**：**仅在**验证路径已给出**明确结论**（已修复 / 已定位责任组件 / 已文档化不可行边界）**之后**，再评估是否启动 **`UPSTREAM_SOF_*` 类对外沟通**。**不**采用「先发 issue 再慢慢试」为默认顺序；**上游协同不作为**验证完成**之前的并行里程碑**。

### Technical Success

- **Linux 主线**：在目标 **`linux-hwe-6.17`** 与仓库补丁策略下，**构建与安装**可重复；**验证脚本**与 **`uname -r`**、已装模块包一致。
- **根因方向**：对 **HDMI IPC 失败** 具备**可引用**的对照材料（双树 diff、trace 或**验证后**再补充的上游链接），而非仅「换过固件」。
- **回归**：自编内核场景下，**3.5mm / WiFi** 等**非目标子系统**不因验证流程被**未记录地**破坏。

### Measurable Outcomes

| 类型 | 指标（与 `Linux_HDMI_Audio_Roadmap.md` 对齐） |
|------|-----------------------------------------------|
| **客观** | 对目标 HDMI 口试播时，与本次播放**相关**的 **`STREAM_PCM_PARAMS` / `ipc tx error`** 在 dmesg 中**消失**，或已被**文档解释**为无害 / 已规避。 |
| **主观** | 目标口有**稳定可听**输出。 |
| **复现** | 在**另一台按文档准备的机器**上，同一验证命令可重复执行并产出**同类**证据结构。 |
| **可选量化** | 换机后 **≤N 天**内完成首次成功验证（**N** 后续填入）。 |

## Product Scope

### MVP - Minimum Viable Product

- **文档入口**：根 `README`、`docs/INDEX`、`Linux_HDMI_Audio_Roadmap`、`WORK_PROGRESS` **互相可导航**。
- **工具链最小**：**0001**（及按需 **0002 / 0003**）的 **apply → 构建 → 安装** 路径**可重复**；**`verify-*`** 在约定环境下有**明确通过 / 失败语义**。
- **证据最小**：一次 **HDMI 试播** 的 **dmesg 基线** + **可选** trace 配置说明（指向现有 OPERATION）。

### Growth Features (Post-MVP)

- **双树深度**：`chromiumos_kernel/v5.15/` 与 `kernel-src/` **齐全**时，**自动化 / 半自动化** diff 与 `reference/` 导出**例行化**。
- **Trace / 深度对照**：按路线图阶段 3，完善 **IPC / 载荷** 与板级对照（与现有脚本一致）。
- **上游协同（显式后置）**：**仅当**验证已解决或**清晰界定**问题责任后，再启用 **`UPSTREAM_SOF_Kaisa_HDMI_REPRO.md` 类投递**；本 PRD **不**将「发上游」列为与验证并行的必达项。

### Vision (Future)

- **Linux HDMI** 在 Kaisa + 约定栈上具备**明确结论**（修复路径、固件 / 拓扑变更、或**文档化边界**）。
- **本仓库**成为同款硬件在 **Linux SOF** 路径上的**可引用协作基线**；与社区的**持续协同**以**验证结论**为前提展开。

## User Journeys

### 旅程 A — 维护者（主路径 · 阶段推进）

**开场**：真机 HDMI 仍无声，3.5mm 正常；dmesg 已有 IPC 线索。  
**发展**：打开**路线图**，确认处于阶段 2 或 3；按 **`WORK_PROGRESS`** 核对内核与补丁版本；运行 **`verify-*`** 或构建脚本，得到 **`VERIFY_OK`** 或**可行动的失败原因**。  
**高潮**：自编内核与补丁与文档一致，**证据链**（dmesg + 可选 trace）能对照 **Chrome 树笔记**。  
**结局**：在 **`WORK_PROGRESS`** 中**诚实更新阶段与日期**（与路线图交叉引用）；下一步在路线图中有**编号**。  
**恢复**：若自编内核导致启动异常，**不**在 PRD 内展开逐步排错；**回退 / unsigned / Secure Boot** 以现有 **`OPERATION_Install_CustomKernel_Ubuntu_HWE617.md`** 与 GRUB 说明为准；详见**旅程 E**。维护者在验证记录中注明是否已回退可用内核。

**决策点**：若同一阶段内 **第三次** 仍只有「现象变化、结论不变」，**先**更新 `WORK_PROGRESS` 与采集文件时间戳，**再**改补丁或参数。  
**可观测检查点**：`verify` 输出或 dmesg 片段与 **`uname -r`**、**`dpkg -l | grep linux-image`** 可同屏对应。  
**完成定义（DoD）**：`WORK_PROGRESS` 中含**可引用**的日期/内核/补丁标识，且与路线图阶段**一致**。

### 旅程 B — 新协作者（换机 · 易错恢复）

**开场**：新克隆仓库，尚无完整 **`kernel-src`** 或 **ChromiumOS** 仅为浅克隆。  
**发展**：**第一动作**：打开 **`WORK_PROGRESS`** 与（若存在）**预检脚本**，对照「缺树 / 缺包」**是否被写明**；再执行文档中的 **`apt source` / 补 clone**。  
**高潮**：阻塞从「心里慌」变为**清单上可勾选**；第一次验证命令产出**可对比日志**。  
**结局**：建立「卡死时信 **`WORK_PROGRESS` + 预检**」；**上游 issue 不替代**本地验证。

**决策点**：若预检失败项 **>2 项**，**优先**补齐与运行内核一致的 **`kernel-src` 完整树**（或记明「本机仅文档化、未构建」），再跑 verify。  
**可观测检查点**：预检退出码与 `WORK_PROGRESS` 中 **「已满足 / 未满足」** 一行对齐。  
**完成定义（DoD）**：未通过项有**负责人或推迟原因**（磁盘、时间等），避免「静默卡住」。

### 旅程 C — 边缘：验证「全绿」但 HDMI 仍无声

**开场**：脚本通过、构建成功，主观仍无声。  
**发展**：回到路线图**成功标准**：区分「IPC 相关日志已干净」与「仍无声」；查 **FIX_PLAN / REANALYSIS**，核对 **设备号与物理口**、路由。  
**高潮**：现象归入**已文档化分支**（如阶段 C/D），不叠加未记录补丁。  
**结局**：结论写回 **`WORK_PROGRESS`**；**上游协同**仅当验证已界定责任后再评估。

**决策点**：若 **IPC 已干净** 仍无声，**先**完成 **设备号 ↔ 物理口** 对照（可链到 `collected/`），再进入 FIX_PLAN 下一分支。  
**可观测检查点**：同一次试播前后 **dmesg 过滤** 与路线图**成功标准**可对照。  
**完成定义（DoD）**：**设备映射或 FIX_PLAN 分支** 至少更新**一处**可追溯文档。

### 旅程 D — 只读使用者（查结论、不构建）

**开场**：同款硬件用户，**不愿**自建内核。  
**发展**：从路线图**已排除项**、**已否决路径**获益；若需对外描述问题，使用 **`UPSTREAM_SOF_Kaisa_HDMI_REPRO.md`** 等**采集清单**作**最小信息打包**（**不等于**启动上游协同）。  
**高潮**：预期对齐：本仓库**不承诺**一键出声，**承诺**防弯路与可核对叙事。  
**结局**：若决定深入构建，转入旅程 B。

**决策点**：若仍尝试**纯用户态**改路由，**标注**为实验性质，**不与**内核 IPC 根因结论混写。  
**可观测检查点**：至少**引用一条**路线图「已排除项」说明**未重复**已知弯路。  
**完成定义（DoD）**：对外或自用说明中**可见**对已记录弯路的**显式回避**。

### 旅程 E — 恢复与可启动性（短旅程）

**开场**：自编或模块实验后**无法启动**或**无网络**等严重回归。  
**发展**：优先 **GRUB 选旧内核**、按 **安装 OPERATION** 处理 **unsigned / Secure Boot**。  
**高潮**：机器回到**可重复验证**状态。  
**结局**：在 **`WORK_PROGRESS`** 记**回退事实**（版本、是否恢复）；恢复细节**不**与 HDMI 调试混写，但**必须**可追溯。

**决策点**：若 GRUB 旧内核仍无法启动，**停止** HDMI 主线，**以恢复为 P0**；`WORK_PROGRESS` 记 **P0 阻塞**。  
**可观测检查点**：回退后 **`uname -r`** 与 `WORK_PROGRESS` **「当前可用内核」** 一致。  
**完成定义（DoD）**：**可启动内核**与记录一致，HDMI 主线才可继续。

### Journey Requirements Summary

| 能力域 | 需求 |
|--------|------|
| **入门与导航** | **README → INDEX → 路线图 / `WORK_PROGRESS`** 单一链条。 |
| **最短命令路径** | 预检 / `verify-*` / 构建入口在文档中有**单点引用**（指向 `WORK_PROGRESS` 或脚本 `--help`）。 |
| **可执行验证** | `verify-*`、构建脚本、**明确退出语义**。 |
| **阻塞透明** | 预检、`WORK_PROGRESS`**列出**缺树/缺包。 |
| **期望管理** | 路线图「已排除项」、成功标准主客观分离。 |
| **顺序约束** | 验证先行，**上游协同后置**。 |
| **恢复与可信** | **GRUB / unsigned / Secure Boot** 以 **OPERATION** 为准；旅程 E 专责**可启动性**。 |
| **只读信息包** | 引用 **UPSTREAM/采集清单** 做**最小信息打包**，**不**自动触发上游流程。 |
| **状态更新责任** | 阶段或结论变更时**同步** `WORK_PROGRESS` 与路线图**交叉引用**。 |
| **决策纪律** | 重复尝试无新结论时，**先**更新 `WORK_PROGRESS` 与采集物，**再**变配置。 |
| **可观测检查点** | 每阶段至少保留 **可与 `uname -r`/包表对齐** 的证据；恢复类以 **P0** 记入 `WORK_PROGRESS`。 |
| **文档结构维护** | 大改 `docs/` 时**同步** **INDEX / REPO_INDEX**（与仓库约定一致）。 |

## developer_tool Specific Requirements

### Project-Type Overview

本仓库在 BMad 分类中为 **developer_tool**：交付物以 **可执行脚本、Git 格式补丁、Markdown 文档与索引** 为主，服务于 **可复现构建、验证与双树对照**，而非独立 GUI 或上架应用。受众为 **维护者本人与少数协作者**（与 Executive Summary 一致）。**索引用途分工**：**`docs/index.md`**（小写）便于 AI 检索；**`docs/INDEX.md`** 为人读总目——二者须与 **`project-context`** 及换机约定保持一致。**验证基线**以 **Ubuntu 24.04 + linux-hwe-6.17** 为主；其他发行版仅作**类比**，不纳入本 PRD 的验证义务。

### Technical Architecture Considerations

- **宿主**：以 **Ubuntu 24.04 + linux-hwe-6.17** 为文档与验证基线；真机以 **`uname -r`** 与 **`kernel-src`** 树版本一致为准。  
- **源码布局**：**`kernel-src/`**（Ubuntu HWE 解压树 + 构建产物约定）、**`chromiumos_kernel/v5.15/`**（ChromiumOS 对照树）；二者体积大，遵守 **`.gitignore`**，以 **README / 索引笔记** 为入口。  
- **补丁管线**：**`patches/ubuntu-hwe-6.17/`** 内 **0001–0003** 按仓库 README 顺序；**`PATCH=`** 指向**单文件** 再 **`apply`**。  
- **自动化**：**`scripts/`** 下构建、验证、diff 导出脚本；依赖路径在注释或 `--help` 中写明。

### language_matrix

| 语言 / 形态 | 用途 |
|-------------|------|
| **Bash** | 构建、验证、采集、预检脚本（`set -e` 等以现有脚本为准）。 |
| **Markdown** | 文档主体；入口 **README**、**`docs/INDEX.md`**、路线图与 `WORK_PROGRESS`。 |
| **C（内核）** | 仅通过 **补丁** 修改；不在 PRD 中要求独立应用工程。 |
| **Git** | 克隆 **ChromiumOS** 树、**unshallow**、按路径 diff（见 `OPERATION_ChromeOS_Kernel_Deep_Diff.md` 等）。 |

### installation_methods

- **Ubuntu 内核源码**：`apt source linux-hwe-6.17=<与运行内核一致的 Version>`，解压至 **`kernel-src/`**（见 **`kernel-src/README.md`**）。  
- **构建依赖**：`scripts/ubuntu-hwe-617-build.sh` 的 **`deps`** / **`apt build-dep linux-hwe-6.17`**；Noble 上包名以文档为准。  
- **Debian 式完整 generic 构建**：在解压树内使用 **`fakeroot debian/rules clean`**、**`fakeroot debian/rules binary-generic`**；若曾 **`make defconfig` / `prepare`** 导致 tree 不洁，须在源码根 **`make mrproper`**（或等价清理）后再打包——**详见 `kernel-src/README.md`**（含磁盘与失败模式）。**高并行**下 **`binary-generic`** 可能因 **`make` 并行/信号量** 等失败（见历史日志如 `semop`）；可**降低并行**（如 **`CONCURRENCY_LEVEL`**）重试，具体以 **`WORK_PROGRESS`** 与构建日志为准，本 PRD 不规定固定线程数。  
- **ChromiumOS 内核**：浅克隆 + 可选 sparse-checkout（见 **`docs/meta/WORK_PROGRESS.md`**），本仓库路径 **`chromiumos_kernel/v5.15/`**。  
- **安装自编 deb**：**`docs/kernel-build/OPERATION_Install_CustomKernel_Ubuntu_HWE617.md`**（unsigned、模块包、Secure Boot）。  
- **IDE**：无强制 IDE；编辑器与 `patch`/`git` 即可。

### api_surface（工具与接口面）

| 接口类型 | 说明 |
|----------|------|
| **环境变量** | 如 **`PATCH=`** 指向单补丁文件；**必须**与当前正在操作的 **`kernel-src/linux-hwe-*`** 树根及版本一致；**先** **`patch -p1 --dry-run`** 再正式应用；**禁止**在 **`dry-run` 失败** 时使用 **`patch --force`** 强行覆盖——应改为手工合并或核对树版本。 |
| **脚本子命令** | **`ubuntu-hwe-617-build.sh`**：`apply` / `deps` / `build` 等（以脚本 `--help` 为准）。 |
| **验证** | **`verify-ubuntu-hwe617-patches-runtime.sh`** 等；成功时可 **`VERIFY_OK`**。 |
| **预检 / diff** | **`preflight-chromeos-ubuntu-diff.sh`**、**`export-chromeos-ubuntu-sound-file-diffs.sh`** 等；双树齐全时启用。 |

### code_examples

- **补丁应用与构建**：**`patches/ubuntu-hwe-6.17/README.md`**、**`kernel-src/README.md`**（含 **`mrproper`** 与 **`binary-generic`** 注意）。  
- **验证**：**`patches/ubuntu-hwe-6.17/VERIFY_PATCHES.md`**。  
- **对照与导出**：**`scripts/export-chromeos-ubuntu-sound-file-diffs.sh`**、**`docs/kernel-build/OPERATION_ChromeOS_Kernel_Deep_Diff.md`**。  
- **只读 / 文本级对照（无需本机构建）**：**`patches/ubuntu-hwe-6.17/reference/`** 下已有 **unified diff**；可配合上述 **export** / **diff** 脚本做文件级对比。  
- **索引**：**`docs/INDEX.md`**、**`REPO_INDEX.md`**（全路径）。

### migration_guide（迁移与版本演进）

- **内核小版本升级**（如 6.17.0-19 → -20）：在 **`kernel-src/`** 重新 **`apt source`** 对齐 **`uname -r`**；**`make mrproper`** 后再 **`fakeroot debian/rules binary-generic`**（见 **`kernel-src/README.md`**）。  
- **补丁重贴**：在新树 **`patch -p1 --dry-run`**；**`DIFF_SUMMARY.txt`** 与 **reference/** 对照变更范围。  
- **ChromiumOS 树**：浅克隆若 **`git log` 单条**，需 **`git fetch --unshallow`** 后再做历史向分析（见 **`CHROMEOS_KAISA_AUDIO_KERNEL_PATHS.md`** 附录）。  
- **文档搬迁**：换机时同步 **`WORK_PROGRESS`** 与路线图阶段；大目录不提交，**只迁移或重拉**说明留在 **`WORK_PROGRESS`**。

### Implementation Considerations

- **最小 diff**：变更以仓库既有体例为准（**`project-context`**）。  
- **`PATCH=` 安全使用**：**禁止**对错误版本树强贴；**dry-run** 失败时先核对 **`uname -r`**、`dpkg -s` 与 **`kernel-src`** 树是否同源。  
- **许可证**：**ChromiumOS 内核树**、**Ubuntu 源码包** 各自遵循**上游许可证**；本仓库**自产**文档、脚本与补丁的许可以**仓库根目录及既有约定**为准（若有 `LICENSE` / 贡献说明则从其规定）。  
- **可观测性**：验证与构建日志建议保留在 **`kernel-src/`** 或约定文件名，并在 **`WORK_PROGRESS`** 引用。  
- **跳过项**：不写 **visual_design**、**store_compliance**；不写 CRAS/Windows 驱动交付（见 Executive Summary）。

## Project Scoping & Phased Development

### MVP Strategy & Philosophy

- **MVP 取向**：**问题解决型 + 可验证学习**——最小可用 = **他人能按文档复现验证并留下可对齐证据**（与 Executive Summary 一致）。  
- **资源假设**：**1 名核心维护者 + 0～少数协作者**；技能：**Linux 命令行、Git、`patch`**；无专职测试/设计。

### Alignment: PRD Phases vs Linux HDMI Roadmap

| 本 PRD | 路线图（`docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md`） | 摘要 |
|--------|--------------------------------------------------------|------|
| **MVP** | **阶段 1–2** 中与「可复现验证」相关的子集 | 用户态基线 + HWE/补丁/自编内核与 **`verify-*`**；**不**强制完整 ChromiumOS 树。 |
| **Post-MVP · 增长** | **阶段 3** | 双树、diff 导出、可选 trace、深度对照。 |
| **Post-MVP · 扩展** | **阶段 4** | **上游协同**；**仅**在成功标准中「验证之后再考虑」的前提下启用。 |

### MVP Dependency Order

1. 文档入口链可用（`README` → `INDEX` / `index` → 路线图 / `WORK_PROGRESS`）。  
2. **运行内核**与 **`kernel-src`**（或书面声明未建源树）一致。  
3. **`PATCH=`**：`dry-run` → `apply`（至少 **0001**）。  
4. 至少一条 **`verify-*`** 有记录（日志或退出码）。  
5. **`WORK_PROGRESS`** 与路线图阶段对齐更新。

### Mapping: README L1–L4

- **L1** → MVP（阶段 1 用户态基线）。  
- **L2** → MVP 以文档与采集为主；深度 SOF 对照属 Post-MVP（阶段 3）。  
- **L3** → MVP 核心（阶段 2：HWE、补丁、自编内核）。  
- **L4** → MVP 含脚本+补丁可用；**双树例行 diff** 属 Post-MVP Phase 2。

### MVP Feature Set（Phase 1）

**核心旅程（最小）**：**旅程 A**、**旅程 B** 主路径；**旅程 E** 以引用 **OPERATION** 为满足。

**Must-have 能力**

| 能力 | 说明 |
|------|------|
| **文档入口链** | `README` → `INDEX` / `index` → 路线图 / `WORK_PROGRESS`。 |
| **补丁与验证** | **`PATCH=` + dry-run**；**`verify-*`** 有明确通过/失败语义。 |
| **与运行内核一致** | **`kernel-src`**（或等价说明）与 **`uname -r`** 对齐后方可宣称验证完成。 |
| **阶段诚实** | `WORK_PROGRESS` 与路线图阶段一致。 |

**MVP 明确不强制**：本机已检出完整 **`chromiumos_kernel/v5.15/`**（无树时仍可依赖 **`patches/.../reference/`** 只读对照，见 **developer_tool** 节）。

### MVP Completion Checklist (lightweight)

- [ ] 协作者 **≤30 分钟**内可定位「下一步三个入口文件」（自测）。  
- [ ] `WORK_PROGRESS` 含最近一次验证或指向 `audio_topology/collected/` 等采集物。  
- [ ] 路线图 **阶段 1–2** 与 `WORK_PROGRESS` **无矛盾**。

### Anti-scope（MVP 不纳入）

- 路线图 **阶段 3** 的**完整**双树自动化（**只读 reference/** 除外）。  
- 路线图 **阶段 4** 上游协同（见 **Success Criteria**）。  
- **完整** `chromiumos_kernel` 检出（MVP 不强制）。

### Post-MVP Features

**Phase 2（增长）— 对齐路线图阶段 3**

- 双树齐备时 **diff 导出例行化**、**trace / 深度对照**（与现有脚本一致）。  
- **`reference/`** 与预检的文档化（降低「必须本机构建」门槛）。

**Phase 3（扩展）— 对齐路线图阶段 4**

- **验证界定责任之后**的 **上游协同**（`UPSTREAM_*`）。  
- **Linux HDMI** 明确结论或文档化边界（与 **Vision** 一致）。

### Risk Mitigation Strategy

| 风险 | 缓解 |
|------|------|
| **技术** | 高并行 **`binary-generic` 失败** → 降并行、日志见 `WORK_PROGRESS`；**`PATCH=`** 先 **dry-run**、**禁止 `patch --force`**。 |
| **期望** | 「限时出声」类预期 → 由 Executive Summary 与旅程 **D** 约束。 |
| **资源** | 磁盘/时间不足 → 阻塞写入 `WORK_PROGRESS`；**单点维护者**停顿 → 依赖 **`WORK_PROGRESS` 日期 + 路线图阶段** 仍可读，否则 Phase 2 推进条件不足。 |

## Functional Requirements

### 文档与导航

- **FR1**：**维护者或协作者**能够仅通过 **`README` → 索引 → 路线图 / `WORK_PROGRESS`** 定位当前工作阶段与下一步阅读顺序。  
- **FR2**：**读者**能够区分 **路线图**（阶段顺序）与 **`WORK_PROGRESS`**（事实与换机状态）的职责边界。  
- **FR3**：**读者**能够查阅 **Linux HDMI 已排除或低期望方向**，并在**现象分流**时区分「已知不成立路径」与「需继续对照内核/用户态」的路径（引用既有分析文档）。

### 补丁与内核源码对齐

- **FR4**：**维护者**能够将仓库内 **指定补丁** 应用于**与运行内核版本一致**的 **Ubuntu HWE 源码树**，并在应用前获得 **`patch` 预检结果**（成功/失败）。  
- **FR5**：**维护者**能够记录当前验证所对应的 **`uname -r`**、内核包来源与 **`kernel-src`** 树状态（含「未建源树」声明）。  
- **FR6**：**维护者**在 **`patch` 预检失败**时**不**以强制覆盖方式掩盖失败，而转入核对或手工合并。

### 构建、安装与恢复

- **FR7**：**维护者**能够按照 **`OPERATION_Install_CustomKernel_Ubuntu_HWE617.md`** 等权威说明完成 **自编内核的安装与回退**；**安装范围**（含 **unsigned、模块包完整性、相关固件/无线等**）以该 OPERATION 为准，**不**在 PRD 内逐包枚举。  
- **FR8**：**维护者**在 **完整内核构建**失败时，能够记录 **并行度/日志位置** 等可复现信息，以便重试或协作排查。

### 验证与诊断

- **FR9**：**维护者**能够运行 **`VERIFY_PATCHES.md` 或文档当前版本**所钉扎的验证路径（与补丁版本、内核线一致），并得到 **通过/失败** 的可判读结果。  
- **FR10**：**维护者**能够保存 **HDMI 相关试播** 的 **内核日志工件**，并使其可与 **路线图成功标准** 对照；**对外分享前**可按 **`audio_topology/COLLECT.md`** 等采集说明做**脱敏**（细则见 **Non-Functional Requirements**）。

### 对照与参考

- **FR11**：**维护者或协作者**能够在 **不构建内核** 的前提下，使用 **文本级对照材料**（如 **`patches/ubuntu-hwe-6.17/reference/`**）支撑讨论；**无完整源码树**时仍可就 **`reference/`**、补丁与 **PR** 进行文本级协作。  
- **FR12**：**维护者**在 **双源码树可用**时，能够执行或引用 **ChromiumOS 与 Ubuntu 树之间的对照流程**（脚本或操作说明）。  
- **FR13**：**读者**能够找到 **ChromiumOS 5.15** 与 **`kernel-src`** 的**约定路径与入口说明**。

### 协作与进度

- **FR14**：**维护者**能够在 **`WORK_PROGRESS`** 中更新 **阶段结论、日期与阻塞项**。  
- **FR15**：**协作者**能够根据 **`WORK_PROGRESS`** 判断 **预检是否通过**或 **缺哪类树/包**。  
- **FR16**：**只读使用者**能够使用 **信息采集清单** 组织 **最小信息包**，**而不自动触发**上游协同义务。  
- **FR17**：**维护者**在阶段或结论变更时，能够完成 **`WORK_PROGRESS` 与路线图**的**交叉引用更新**。

### 索引与可发现性

- **FR18**：**维护者**在新增或重组主题文档时，能够按约定**更新** **`docs/INDEX.md` / `REPO_INDEX.md`**（或等效索引），避免孤岛页；**大段摘录上游文档或代码**时须**标明来源与许可证**（与 **developer_tool** 许可证约定一致）。  
- **FR19**：**协作者**能够从索引或脚本表**定位**与 **HWE / HDMI** 相关的 **脚本及用途**。

### 范围分界与上游（条件触发）

- **FR20**：**读者**能够从索引或总览中识别 **Linux HDMI 主线文档**与 **Windows / 其他平台** 文档的**入口分界**（本 PRD **不**交付 Windows 方案）。  
- **FR21**：**维护者**在 **Success Criteria 所定义的验证结论已具备**之后，能够准备 **上游复现/对外沟通** 所需材料（此前**无**必须完成的对外义务）。

## Non-Functional Requirements

### Privacy & Data Handling

- **NFR1**：**对外分享** dmesg / 采集前，**维护者**须按 **`audio_topology/COLLECT.md`**（或等效采集说明）对 **序列号、MAC、账号** 等可识别信息做**脱敏或裁剪**；**默认**不将未脱敏日志提交至公共 issue。**例外**：若 **上游 / issue** 在 **`UPSTREAM_SOF_Kaisa_HDMI_REPRO.md`** 等清单中**明确要求**某工具的全量输出，按该清单执行，并遵循**最小必要**与清单内说明。  
- **NFR2**：**维护者**不得在仓库中提交 **密钥、Cookie、个人账号口令** 等机密；脚本与文档示例使用占位符。

### Documentation & Consistency

- **NFR3**：面向用户/协作者的说明须与 **`docs/meta/DOCUMENTATION_STYLE.md`** 及 **`project-context`** 中的语言与入口约定一致（**简体中文**为主，与 BMM 配置一致）。  
- **NFR4**：**新增主题文档**或**改变 `docs/` 导航结构**时，须在**同一变更或紧随提交**中**同步** **`docs/INDEX.md` / `REPO_INDEX.md`**（或等效索引）；**仅修改根 README 短链**且**不改变主题归属**时，**不**强制全文重链（与 **FR18** 配套）。

### Reproducibility & Environment

- **NFR5**：**验证脚本**在文档声明的**环境基线**（**Ubuntu 24.04 + 与文档一致的 `linux-hwe-6.17` 线**）且**前置条件满足**时，须具备**可重复**的通过/失败语义；**其它发行版或内核线**仅作类比，**不声称**满足 **FR9** 的验证义务，除非在 **`WORK_PROGRESS`** 或文档中**单独记录**环境与结论。  
- **NFR6**：**完整内核构建**的耗时与磁盘占用**不作为**用户响应时间类指标；在文档与 **`WORK_PROGRESS`** 中**如实记录**典型量级与失败模式（如并行、空间不足）。

### Licensing & Attribution

- **NFR7**：进入本仓库**版本库**的上游**摘录**（含大段文档或代码）须**可追溯来源与许可证**；**优先**以 **链接 + 短引** 替代长粘贴；**合理使用**边界按 **`developer_tool`** 与上游许可执行。