---
stepsCompleted:
  - 1
  - 2
  - 3
  - 4
  - 5
  - 6
  - 7
  - 8
inputDocuments:
  - _bmad-output/planning-artifacts/prd.md
  - _bmad-output/project-context.md
  - _bmad-output/problem-solution-2026-04-04-linux-hdmi-kaisa.md
  - docs/INDEX.md
  - docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md
workflowType: architecture
lastStep: 8
status: complete
completedAt: '2026-04-05T12:00:00+08:00'
project_name: chromebox_10th_audio_driver
user_name: Jack
date: '2026-04-05T12:26:51+08:00'
---

# Architecture Decision Document

_This document builds collaboratively through step-by-step discovery. Sections are appended as we work through each architectural decision together._

## Project Context Analysis

### Requirements Overview

**Functional Requirements:**  
PRD 定义 **FR1–FR21**，覆盖：单一文档入口与路线图 / `WORK_PROGRESS` 分工（FR1–FR3）；Ubuntu HWE 源码树上补丁预检与应用、禁止强制 `patch`（FR4–FR6）；自编内核安装/回退与构建失败可复现记录（FR7–FR8）；文档化验证路径与 HDMI 相关日志工件（FR9–FR10）；`reference/` 与双树对照流程（FR11–FR13）；进度与预检透明（FR14–FR17）；索引维护与脚本可发现（FR18–FR19）；Linux 与 Windows 文档分界（FR20）；**验证结论具备后**再准备上游材料（FR21）。  
**架构含义**：系统边界是「仓库内可执行的文档 + 脚本 + 补丁」，不是单一运行时服务；一致性依赖 **版本钉扎** 与 **artifact 路径约定**。

**Non-Functional Requirements:**  
**NFR1–NFR2** 约束对外分享前的脱敏与密钥；**NFR3–NFR4** 约束体例与索引变更；**NFR5–NFR6** 约束验证基线与构建/资源事实记录；**NFR7** 约束版本库内摘录的来源与许可。  
**架构含义**：安全与合规主要体现在 **日志与摘录治理**，而非网络边界。

**Scale & Complexity:**  
- **主领域**：棕地 **Linux 内核 / SOF / 文档与工具链**（非典型 Web 全栈）。  
- **复杂度**：部署规模 **低**；**领域与可复现性**为主要风险面。  
- **逻辑组件（约 5 类）**：文档与索引；补丁与 `kernel-src` 构建；验证与采集；对照与 diff 导出；协作元数据（`WORK_PROGRESS` / PRD）。

### Technical Constraints & Dependencies

- **基线环境**：文档以 **Ubuntu 24.04 + linux-hwe-6.17** 为验证叙述主线；其它环境不自动满足 FR9（见 PRD / NFR5）。  
- **大目录**：`kernel-src/`、`chromiumos_kernel/v5.15/` 常不提交，架构上依赖 **路径约定 + README/笔记**，而非「仓库内必有完整树」。  
- **上游顺序**：路线图阶段 4 / FR21：**验证之后再考虑**上游协同，架构上**不得**把上游 issue 当作并行前置依赖。

### Cross-Cutting Concerns Identified

- **内核与源码树版本一致**（`uname -r` ↔ `kernel-src` ↔ 补丁对象）。  
- **可复现性**（脚本退出语义、`VERIFY_OK`、构建日志位置）。  
- **隐私与摘录**（dmesg、上游清单、许可证）。  
- **文档导航不碎裂**（INDEX / REPO_INDEX / 路线图 / `WORK_PROGRESS` 交叉引用）。

### Failure Modes（约束被违反时）

| 情形 | 后果 | 架构上应坚持的约束 |
|------|------|---------------------|
| **`kernel-src` 与运行内核不一致**仍打补丁/宣称验证 | FR4–FR6、NFR5 失效；结论不可引用 | 任何「已验证」叙述必须带 **`uname -r` + 树来源** |
| **未更新 INDEX** 即移动主题文档 | FR18、NFR4 失效；协作者迷路 | 结构变更与索引**同一变更集** |
| **未脱敏即贴全量 dmesg 到公开 issue** | NFR1 失效 | 对外主体以 **`UPSTREAM_*` / COLLECT** 为准 |

### Explicit Non-Goals（本仓库架构不承担）

- **无** 7×24 在线服务、**无** 多租户、**无** 统一 API 网关。  
- **无** 强制「仓库内必含完整 `chromiumos_kernel` / `kernel-src`」——架构上为 **可选外置树 + 文档钉扎路径**。  
- **无** 将 **PipeWire / CRAS** 作为交付内核——用户态栈仅作**现象分流**引用（与 PRD 一致）。

### FR → 逻辑组件（追溯草图）

| 逻辑组件 | 主要 FR |
|----------|---------|
| **文档与入口** | FR1–FR3, FR18–FR20 |
| **补丁与源码树** | FR4–FR6, FR11–FR13 |
| **构建 / 安装 / 恢复** | FR7–FR8 |
| **验证与日志** | FR9–FR10 |
| **协作与进度** | FR14–FR17 |
| **上游（条件）** | FR21 |

（正式可追溯矩阵可在 **Epic/Story** 阶段细化。）

### Human–Machine Boundaries

| 层级 | 责任主体 | 架构含义 |
|------|----------|----------|
| **策略与范围** | PRD / 路线图 | 不写进内核；**冲突以 PRD 为准** |
| **可执行步骤** | Bash 脚本 + `PATCH=` | 代理/人必须按**同一入口**调用，避免「口头路径」 |
| **内核行为** | 上游 + 本仓库补丁 | **不**假装能替代固件拓扑；**对照**用 ChromiumOS 树 |
| **事实记录** | `WORK_PROGRESS` + `collected/` | **单一事实源**与路线图阶段对齐 |

### Artifact Flow（简化）

```text
docs（意图） → PATCH/dry-run → kernel-src 树 → debian/rules 构建 → 安装/回退
                    ↓
              verify-* / 采集 → 日志与 collected → 对照 reference/ 或双树 diff
                    ↓
        （条件）UPSTREAM 材料 ← 仅当 FR21 前提满足
```

架构决策应**不**在这条链外再发明「隐式步骤」。

### ADR 衔接（若后续引入）

若仓库内增加 **ADR（Architecture Decision Record）**，建议 **一条 ADR 对应一类可重复冲突**，并 **引用**本文件与 PRD；**避免** ADR 与 PRD 形成第二套需求源。

### Compatibility Matrix（声明级）

- **主线**：Ubuntu **24.04 (Noble)** + **linux-hwe-6.17** 文档与验证叙述。  
- **其它 Ubuntu / 发行版**：**不**列入默认支持矩阵；个案仅记录在 **`WORK_PROGRESS`**。

### Single-Maintainer & Precedence

- **文档与脚本分叉**风险：依赖 **`WORK_PROGRESS` 日期 + 路线图阶段** 可读（与 PRD Scoping 一致）。  
- **本文档与 PRD**：若冲突，**以 PRD 为准**；本文服务于 **实现一致性** 与代理可重复行为，而非替代需求定义。

## Starter Template Evaluation

### Primary Technology Domain

本仓库为 **棕地 Linux 内核 / SOF 相关文档与补丁工程**，**非**典型 Web 应用；不适用 Next.js/Vite 等应用脚手架。所谓「Starter」指：**工程基底与可重复初始化契约**（目录约定、`kernel-src` 对齐、`PATCH=` 流程、验证与采集路径），而非生成新运行时服务。

### Starter Options Considered

| 方向 | 说明 | 结论 |
|------|------|------|
| Web 全栈脚手架 | 与 PRD 主域不符 | **不采纳** |
| 纯文档 + Bash + 既有补丁/构建入口 | 与当前仓库与 FR4–FR8 一致 | **默认采纳（主基底）** |
| 可选 Python 辅助 | 仅当脚本/预检复杂度显著增加时，从同一 Bash 入口调用 | **条件采纳** |
| Devcontainer | 可选降低环境漂移说明成本；**不**替代 Ubuntu+HWE 基线验证叙述 | **可选旁路** |
| Nix/Flake | 可锁工具链，但与文档主线并行成本高 | **默认不列为架构主线** |
| 最小 CI | 可跑无秘密的校验/文档检查；**不**等同于 FR9 验证 | **可选** |

### Selected Starter: 棕地仓库 + Ubuntu HWE / `kernel-src` / 补丁工作流（主叙述）

**Rationale for Selection:**  
在对比矩阵与多角色讨论下，选择 **最少新依赖、与 PRD 对齐、人机边界清晰** 的基底。从第一性原理，本仓库「初始化」应落实为 **版本钉扎与路径契约**，而非新应用模板。

**Initialization（叙述级「命令」语义，非单一上游 CLI）：**

1. 克隆本仓库；按 `README` / 路线图将 **`kernel-src`**（或等价路径）对齐到 **`uname -r`** 与文档钉扎的 HWE 版本。  
2. 使用仓库内 **同一入口脚本** 进行 `PATCH=` 预检与应用（禁止未文档化的「口头路径」）。  
3. 按 PRD 执行构建、安装/回退与 **`verify-*`/采集**；将 **`uname -r`、树来源、日志路径** 写入 `WORK_PROGRESS` 或约定工件位置。  
4. （可选）在复杂度需要时引入 **Python 子脚本** 或 **CI**，但必须 **不改变** 下文的入口与验证契约。

**目标机与验证边界（协作澄清）：**

- **本机即目标机**：PRD 所述验证与采集，**默认在唯一目标主机（当前使用中的机器）上执行**；不要求单独的「实验室金机」叙事。`uname -r`、`kernel-src` 与补丁对象的一致性均针对该主机。  
- **术语区分**：**「本机验证」**（满足 FR9 的路径与工件）与 **「CI / 预检门禁」**（若存在）不得混称为「已验证」；**CI 通过不替代** 在本机执行的验证与日志约定。  
- **入口唯一性**：可选 Python 或 CI 仅能为 **子路径**；**README 与文档声明的 Bash/文档入口** 仍为权威；辅助脚本不得自称唯一入口。

**Architectural Decisions Provided by This「Starter」:**

- **语言与运行时**：默认 **Bash + 文档**；Python/Node **仅作可选辅助**，且不得成为唯一入口。  
- **构建与验证**：以 **Ubuntu 24.04 + linux-hwe** 文档主线为准；其它环境不自动满足 FR9。  
- **大目录策略**：`kernel-src` / 对照树 **外置或可选**；架构依赖 **路径约定与记录**，而非「克隆即完整树」。  
- **测试与质量**：**验证脚本 + artifact**；CI 若存在，定位为 **预检/补充**，**不**替代本机验证。  
- **协作**：**INDEX、`WORK_PROGRESS`、路线图** 为导航与事实主轴；Starter **不**引入第二套需求源。  
- **读者分层**：主线只写 **初始化契约**；Devcontainer、Nix、CI 等写入 **旁注**，并标明 **不替代** Ubuntu+HWE 与本机验证。

**Note:** 实现阶段的首个故事应是：**在文档与脚本中显式固定上述初始化与验证契约**（含 `kernel-src` 对齐检查与日志位置），再迭代可选工具。

## Core Architectural Decisions

### Decision Priority Analysis

**Critical（阻塞实现一致性）：** 工件与目录契约；补丁与 `kernel-src` 流程。  
**Important（显著塑造协作方式）：** 验证与可复现；文档与协作入口。  
**Deferred / 门槛驱动：** 可选 Python 辅助、可选 CI——仅在有明确痛点时引入，且不得破坏入口与验证契约（与 Starter Template Evaluation 一致）。

### 1. 工件与目录契约

| 决策 | 内容 | 依据 |
|------|------|------|
| 补丁落位 | **`patches/ubuntu-hwe-6.17/`** 为当前 HWE 线钉扎目录；若未来换内核线，**新建** `patches/<新线>/`，**不**在旧目录混用不同 `uname -r` 语义。 | PRD FR4–FR6；现有补丁布局 |
| 采集与事实工件 | 采集类 Markdown **优先**落在既有约定路径（如 **`audio_topology/collected/`**），遵循 **`audio_topology/COLLECT.md`**；避免在仓库根再建与现有并行的第二套 collected。 | FR10；COLLECT 体例 |
| 验证输出语义 | **`VERIFY_OK`**、跳过 HDMI 测试（如 **`RUN_HDMI_TEST=0`**）等以 **`patches/ubuntu-hwe-6.17/VERIFY_PATCHES.md`** 与 **`scripts/verify-*.sh`** 为准；架构层**不**新增隐式成功条件。 | project-context；验证脚本 |

### 2. 补丁与源码树流程

| 决策 | 内容 | 依据 |
|------|------|------|
| 应用方式 | 每次 **`apply`** 使用 **`PATCH=`** 指向**单文件**；顺序 **0001 → 0002**；**0003** 与 0001/2 **独立**（与 `patches/ubuntu-hwe-6.17/README.md` 一致）。 | FR4–FR6 |
| 树与内核 | **`kernel-src/`** 与运行内核 **`uname -r`** 一致后方可宣称补丁相关结论；**`chromiumos_kernel/v5.15/`** 为**对照基准**，大体积 **不**强制入库。 | Step 2；`kernel-src/README.md` |
| 新补丁前 | 设计新补丁前应对照 **ChromeOS 5.15 ↔ 当前 HWE** 与 **`patches/ubuntu-hwe-6.17/DIFF_SUMMARY.txt`**，避免重复已否决路径。 | project-context |

### 3. 验证与可复现

| 决策 | 内容 | 依据 |
|------|------|------|
| 验证权威 | **本机即目标机**：FR9 所指「已按文档验证」= 在 **当前目标机** 上按 **`VERIFY_PATCHES` + `verify-*`** 执行并保留约定工件；**不**与 CI 绿标混称「已验证」。 | Starter 澄清；PRD FR9 |
| CI（若存在） | 仅作 **预检/门禁**（无秘密的脚本或文档检查）；**不**替代本机验证。 | NFR5–NFR6；Starter |
| 可复现记录 | 构建失败、回退等事实记在 **`docs/meta/WORK_PROGRESS.md`** 与各 **OPERATION** 约定位置，不另造影子日志体系。 | FR7–FR8 |

### 4. 文档与协作

| 决策 | 内容 | 依据 |
|------|------|------|
| 入口 | **根目录仅 `README.md`**；主题入口 **`docs/INDEX.md`**，全路径 **`REPO_INDEX.md`**；`docs/` 结构变更须 **同变更集** 更新索引。 | FR1、FR18–FR19 |
| 进度与阶段 | Linux HDMI 以 **`docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md`** 为准；阶段结论与换机信息同步 **`docs/meta/WORK_PROGRESS.md`**。 | FR2–FR3 |
| 体例 | 改写与语言约定以 **`docs/meta/DOCUMENTATION_STYLE.md`** 为准。 | NFR3–NFR4 |

### 5. 可选辅助工具（门槛）

| 决策 | 内容 | 依据 |
|------|------|------|
| 新语言/脚手架 | **不**在仓库根引入 Node/Python **应用式**脚手架。 | Starter；project-context |
| Python | 仅当 Bash 难以维护时，增加 **由 Bash 调用的** Python 辅助；**不**把 Python 当作唯一入口。 | Starter |
| CI | **可选**；引入时须在文档中标明 **「预检 ≠ FR9 本机验证」**，且不依赖密钥。 | Starter |

### Decision Impact Analysis

**实现顺序建议：**  
1）保持 **`PATCH=` / `kernel-src` / `verify-*`** 单一叙事与脚本退出语义；2）任何新目录或新脚本先补 **INDEX / REPO_INDEX** 与 **`WORK_PROGRESS`**；3）再评估 Python/CI。

**跨组件依赖：**  
文档入口 → 脚本可发现性（FR18–FR19）；补丁流程 → 验证工件与 `WORK_PROGRESS`；三者缺一则 FR9 与协作透明度链条断裂。

## Implementation Patterns & Consistency Rules

### Pattern Categories Defined

**Critical conflict points（多代理易分歧处）：**  
脚本命名与放置、`PATCH=`/`kernel-src` 路径叙事、`VERIFY_OK` 语义、文档与索引同事务、采集文件命名、失败时日志形态。

**不适用（本仓库非 Web/API 服务）：** 数据库表名、REST 路由、JSON 字段风格等——**不在此重复约束**；若未来出现，另开 ADR。

### Naming Patterns

**Shell 脚本（`scripts/`）：**

- **小写字母 + 连字符**；与现有 **`verify-*`**、**`ubuntu-hwe-*`** 前缀体系一致，**不**引入第三套动词/前缀（如随意新建 `tools/run.sh` 作为并列权威入口）。
- 新脚本名称应 **可扫一眼知用途**（验证 / 构建 / 辅助），并在文件头或 `--help` 写明**工作目录**（通常为仓库根）。

**补丁与单文件应用：**

- 叙述 **`PATCH=`** 时，**权威** 为 **`patches/ubuntu-hwe-6.17/README.md`**（及同目录 README 体系）；**单文件、顺序 0001→0002、0003 独立** 的语义不得在不同文档中互相矛盾。

**文档与采集文件：**

- 采集类 Markdown 命名须 **可排序、可检索**，遵循 **`audio_topology/COLLECT.md`**（及同类体例）。
- 新主题文档避免「孤岛文件名」；与 **INDEX / REPO_INDEX** 登记名一致或可追溯。

### Structure Patterns

**目录与权威入口：**

- **`kernel-src/`** 的工作目录与构建叙述 **以 `kernel-src/README.md` 为准**；不在随机笔记中定义第二套「默认路径」。
- 新可执行能力 **优先** 落在 **`scripts/`**；避免在仓库根散落多个未登记的 `.sh` 作为「正式入口」。

**文档变更与索引：**

- 变更 **`docs/`** 结构、新增或移动 **重要 OPERATION / 路线图级** 文档时，**同一变更集** 更新 **`docs/INDEX.md` 和/或 `REPO_INDEX.md`**（与 Core Architectural Decisions 一致，升为模式级）。

### Format Patterns

**验证成功语义：**

- **`VERIFY_OK`** 仅用于 **仓库已约定的验证脚本** 成功路径；其它语言或工具 **不得** 打印同名字符串冒充通过。

**失败与调试输出（Bash）：**

- 失败时建议在 **stderr** 输出 **至少一行可 `grep` 的前缀**（含脚本名或仓库约定前缀），便于写入 **`WORK_PROGRESS`** 与复现记录。
- **对外** 粘贴日志仍遵守 **NFR1 脱敏**；本机调试与内部记录不受「前缀」约束冲突。

### Process Patterns

**错误与退出：**

- 脚本以现有惯例为准（如 **`set -e`**）；**退出码** 与 **`VERIFY_OK`** 的约定以 **`VERIFY_PATCHES.md`** 与对应 **`verify-*.sh`** 为准，**不**在架构层新增隐式成功条件。

**协作流程：**

- **最小必要 diff**；不顺带重构无关文件。大目录遵守 **`.gitignore`**，不提交整树。

### Enforcement Guidelines

**All AI Agents MUST:**

- 新增/改名 **`scripts/`** 下脚本时，**对齐现有命名风格** 并更新 **`docs/INDEX.md`**（若脚本已列入索引表）或相关 OPERATION。
- 任何 **`PATCH=`、`kernel-src`、验证流程** 的改写，**同步** **`patches/.../README`**、**`VERIFY_PATCHES.md`** 或 **`kernel-src/README.md`** 之一，避免「口头路径」。
- 不动 **`docs/`** 导航结构，或 **同事务** 更新 **INDEX / REPO_INDEX**。

**Pattern enforcement：** 代码审查与自检时对照本节 **+ `_bmad-output/project-context.md`**；冲突以 **PRD** 与 **Core Architectural Decisions** 为准。

### Pattern Examples

**Good examples:**

- 新验证脚本：`scripts/verify-<kernel-line>-<concern>.sh`，并在 `VERIFY_PATCHES.md` 或 `docs/INDEX.md` 脚本表中登记。
- 文档：新增 `docs/linux-hdmi/OPERATION_Foo.md` 且 **同一 MR** 修改 `docs/INDEX.md` 链接。

**Anti-patterns:**

- 在聊天或 issue 里写「你本机 `cd` 到某路径再 patch」，但 **仓库内无任何 README/脚本** 对应。
- 非约定脚本在 stdout/stderr 打印 **`VERIFY_OK`**。
- 移动 `docs/` 下文件却 **不** 更新 INDEX，导致代理与用户迷路。

## Project Structure & Boundaries

### Complete Project Directory Structure（逻辑视图）

仓库以 **文档 + 脚本 + 补丁 + 可选大目录** 为主；下列为 **协作常用边界**（非逐文件穷举）。

```text
chromebox_10th_audio_driver/
├── README.md                 # 唯一根 README；总入口
├── REPO_INDEX.md             # 全路径速查
├── docs/
│   ├── INDEX.md              # docs 主题索引（必维护）
│   ├── linux-hdmi/           # HDMI 路线图、对照、trace、上游材料
│   ├── kernel-build/         # 自编内核安装、深度 diff 操作
│   ├── meta/                 # WORK_PROGRESS、双系统、体例引用
│   └── windows/              # Windows 音频（与 Linux 文档分界）
├── audio_topology/           # 拓扑分析、采集脚本、修复计划
│   └── collected/            # 真机采集/trace 工件（命名遵循 COLLECT.md）
├── patches/
│   └── ubuntu-hwe-6.17/      # 钉扎 HWE 线补丁；PATCH= 单文件应用
├── scripts/                  # Bash 入口；verify-* / ubuntu-hwe-* / diff 工具链
├── kernel-src/               # linux-hwe 解压与构建（常 .gitignore；说明见 README）
├── chromiumos_kernel/v5.15/ # 对照树（可选克隆；索引见 docs/linux-hdmi/…）
├── _bmad-output/
│   └── planning-artifacts/   # PRD、architecture.md、project-context 等
└── .cursor/                  # 编辑器技能（非业务交付物）
```

**可选/忽略提交：** `kernel-src/`、`chromiumos_kernel/` 整树；**业务事实** 以 **README + WORK_PROGRESS + 脚本参数** 钉扎。

### Navigation Anchors（导航锚点）

新协作者优先沿下列 **固定锚点** 定位可执行路径（与 `README` / `docs/INDEX.md` 一致）：

| 目的 | 锚点路径 |
|------|----------|
| 补丁与 `PATCH=` 语义 | `patches/ubuntu-hwe-6.17/README.md` |
| 验证流程与 `VERIFY_OK` | `patches/ubuntu-hwe-6.17/VERIFY_PATCHES.md`、`scripts/verify-ubuntu-hwe617-patches-runtime.sh` |
| 源码树与 `uname -r` 对齐 | `kernel-src/README.md` |
| 主题文档总表 | `docs/INDEX.md` |
| 进度与换机事实 | `docs/meta/WORK_PROGRESS.md` |

**目录分工（避免混淆）：** **`audio_topology/`** — 拓扑脚本、采集规范与 `collected/` 原始工件；**`docs/linux-hdmi/`** — HDMI 路线图、重分析与对照结论文档。二者交叉引用，**不**互相当作对方唯一入口。

**构建/安装故事：** **`scripts/ubuntu-hwe-617-build.sh`** 与 **`docs/kernel-build/`** 在叙述上视为 **同一工作流的脚本侧与文档侧**（索引与 OPERATION 互链）。

### Structure Failure Modes & Guards（结构相关失效与防护）

- **索引漂移**：`docs/` 移动或新增 OPERATION → **同一变更集** 更新 `docs/INDEX.md` / `REPO_INDEX.md`（见 Implementation Patterns）。  
- **树不一致**：补丁/验证叙事须同时锚定 **`patches/.../README.md`**、**`kernel-src/README.md`** 与 **`uname -r`**。  
- **双叙事冲突**：`audio_topology/` 与 `docs/linux-hdmi/` **分工**见上表；阶段真相以 **`docs/meta/WORK_PROGRESS.md`** 与路线图为准。  
- **脚本不可发现**：新脚本须进入 **INDEX 或 REPO_INDEX 脚本表**（若适用）。  
- **采集不可检索**：`audio_topology/collected/` 命名遵循 **`audio_topology/COLLECT.md`**。  
- **多内核线（未来）**：新 HWE 线 → **`patches/<新线>/`** 独立 README/验证说明，**不**与旧线混用补丁编号语义。  
- **规划 vs 需求**：**`_bmad-output/`** 为规划契约；需求冲突 **以 PRD 为准**。

### Architectural Boundaries

| 边界 | 含义 |
|------|------|
| **文档 vs 可执行** | 意图与步骤在 **`docs/`**；**同一操作** 的入口在 **`scripts/`** 与 **`patches/.../README`**，不在聊天里另起一套路径。 |
| **补丁 vs 运行内核** | 补丁只针对与 **`uname -r`** 对齐的 **`kernel-src`**；对照在 **`chromiumos_kernel`**，**不**混为「运行树」。 |
| **Linux vs Windows** | 分目录 **`docs/linux-hdmi`** vs **`docs/windows`**；共享硬件事实时 **交叉引用**，不合并成单一含糊文档。 |
| **BMad 生成物** | **`_bmad-output/`** 为规划/契约；**不**替代 PRD 作为需求源。 |

### Requirements to Structure Mapping（FR 簇 → 位置）

| FR 范围 | 主要落点 |
|---------|----------|
| FR1–FR3 入口与进度 | `README.md`、`docs/INDEX.md`、`docs/meta/WORK_PROGRESS.md`、`docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md` |
| FR4–FR6 补丁 | `patches/ubuntu-hwe-6.17/`、`VERIFY_PATCHES.md`、`scripts/verify-*.sh` |
| FR7–FR8 构建/安装 | `kernel-src/README.md`、`docs/kernel-build/`、`scripts/ubuntu-hwe-617-build.sh` |
| FR9–FR10 验证与采集 | `scripts/verify-*.sh`、`audio_topology/collected/`、`audio_topology/COLLECT.md` |
| FR11–FR13 对照 | `chromiumos_kernel/`、`docs/linux-hdmi/*PATHS*.md`、`scripts/*chromeos*diff*.sh` |
| FR14–FR17 透明协作 | `docs/meta/WORK_PROGRESS.md`、路线图、补丁 README |
| FR18–FR19 索引与脚本可发现 | `docs/INDEX.md`、`REPO_INDEX.md` |
| FR20 平台分界 | `docs/linux-hdmi/` vs `docs/windows/` |
| FR21 上游（条件） | `docs/linux-hdmi/UPSTREAM_*` 等（仅验证后） |

### Integration Points（与 Artifact Flow 一致）

- **内部：** `docs` → `PATCH=` / `kernel-src` → `scripts` 构建与 `verify-*` → `collected` / `WORK_PROGRESS`。  
- **外部：** 上游内核/固件/发行版包 **不**入库；通过 **文档链接与版本号** 钉扎。

### File Organization Patterns（摘要）

- **配置：** 无应用级 `package.json` 主线；宿主依赖在 **OPERATION** 与 **`kernel-src/README.md`** 中叙述。  
- **「源码」：** 内核改动以 **`patches/*.patch`** 与 **`kernel-src/`** 工作副本表达。  
- **测试：** **无** 单元测试树；**验证** = `verify-*` + 文档化手工步骤（FR9）。

### Development Workflow Integration

- **日常：** 读 **`README` → INDEX → 路线图**；改补丁则 **`patches/` + kernel-src 对齐**；验证则 **`verify-*` + WORK_PROGRESS**。  
- **构建：** `scripts/ubuntu-hwe-617-build.sh` 与 `kernel-src/README.md` 对齐。  
- **部署：** **deb 安装/回退** 由 **`docs/kernel-build/`** 与构建脚本叙述；**无**容器/多机部署主线。

## Architecture Validation Results

### Coherence Validation

**Decision Compatibility：** Starter（Bash + 文档入口）、Core Decisions（补丁 / 本机验证 / 索引）、Implementation Patterns（`VERIFY_OK`、INDEX 同事务）、Project Structure（Navigation Anchors 与失效防护）**相互一致**；未混入与 PRD 冲突的第二套 Web/应用栈。

**Pattern Consistency：** 命名、路径权威与「本机验证 vs CI」边界在 **Patterns** 与 **Structure Failure Modes** 中可交叉引用，无矛盾条款。

**Structure Alignment：** 逻辑目录树与 **FR→位置映射**、**Artifact Flow** 对齐；大目录外置与锚点表支持 Step 2 中的失败模式约束。

### Requirements Coverage Validation

**Functional Requirements：** FR1–FR21 均在 **Project Context Analysis**、**Core Architectural Decisions** 或 **Requirements to Structure Mapping** 中有落点；FR21 保持为 **验证通过后的条件路径**（与 PRD 一致）。

**Non-Functional Requirements：** NFR1–NFR7 通过 **脱敏、索引、WORK_PROGRESS、可复现记录、摘录与许可** 等叙述覆盖；未过度承诺性能、多租户或在线 SLA。

### Implementation Readiness Validation

**Decision & pattern completeness：** 关键决策与代理可执行规则已写清；**无** 要求钉死具体内核次版本号（由 `uname -r` + 文档钉扎承担）。

**Structure completeness：** 提供 **逻辑树 + Navigation Anchors**，避免与 `REPO_INDEX` 逐文件重复；集成点与 **Development Workflow** 已摘要。

**诚实范围：** 本仓库 **无** 可替代 FR9 的仓库级自动化测试套件；FR9 仍以 **本机 `verify-*` + 约定工件 + `WORK_PROGRESS`** 为准（与 Starter、Core Decisions 一致）。

### Gap Analysis Results

| 优先级 | 说明 |
|--------|------|
| **非阻塞** | Epic/Story 级可追溯矩阵可在后续规划细化。 |
| **非阻塞** | 若引入 **第二条 `patches/<内核线>/`**，须为新线增加 **独立 README 与验证叙述**（Structure 与下表已预警）。 |
| **可选** | 可选 CI 仅作预检；**不**在本文扩写具体 CI 语法（保持与 PRD 一致）。 |

### Party Mode & Review Supplements（Step 7）

- **变更防呆：** 与补丁或本机验证相关的变更，应能 **指回** `patches/.../README` 或 `VERIFY_PATCHES.md`，或本文 **Navigation Anchors** 中的等价路径。  
- **双索引分流：** 默认 **`README` → `docs/INDEX.md`**；已知文件名或全路径速查时 **`REPO_INDEX.md`**。  
- **后续内核线：** 新 HWE/补丁线 → **`patches/<新线>/`** + **独立验证说明**；不与旧线混用补丁编号语义。

### Architecture Completeness Checklist

**Requirements & constraints**

- [x] 项目上下文、规模、技术约束与跨切面关切已分析  
- [x] 失败模式与非目标已声明  

**Decisions & patterns**

- [x] Starter 与核心决策已文档化  
- [x] 实现模式与反模式已给出  
- [x] 项目结构与边界、FR 映射已建立  

**Validation**

- [x] 一致性、需求覆盖与实现就绪已复核  
- [x] 已知缺口已标注为非阻塞或后续增强  

### Architecture Readiness Assessment

**Overall status：** **READY** — 可作为代理与维护者的 **单一技术叙事** 与 PRD 对齐实现；冲突时 **以 PRD 为准**。

**Confidence level：** **高**（棕地文档 + 脚本 + 补丁；约束闭合，未虚构运行时服务）。

**Strengths：** 路径锚点清晰；验证与索引规则可执行；与 `project-context.md` 可并列使用。

**Areas for future enhancement：** 第二条补丁线的独立验证包；可选 CI 的文档化（若引入）。

### Implementation Handoff

**AI agent guidelines：**

- 遵循 **`_bmad-output/project-context.md`** 与本 **`architecture.md`**；变更 **最小必要**，并维护 **INDEX / REPO_INDEX**。  
- 补丁与验证：**`PATCH=`**、**`kernel-src` 对齐**、**`verify-*`** 与 **`VERIFY_OK`** 语义以仓库内 **README / VERIFY_PATCHES** 为准。  

**First implementation priority（与 Starter Note 一致）：** 在文档与脚本中 **显式固定** 初始化与验证契约（含 `kernel-src` 与 `uname -r` 检查、日志与 `WORK_PROGRESS` 路径），再迭代可选工具或 CI。

---

## Architecture Workflow Completion

**BMad Create Architecture** 流程已在本仓库 **`architecture.md`** 中跑通 **Step 1–8**（`stepsCompleted` 与 `status` 见文首 YAML）。后续实现与拆故事请以 **PRD** 与 **`docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md`** 为调度主线。