jack/chromebox_10th_audio_driver
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4f9b23d1446ac9281b8c54fbd9e8c0f67cf9eac2
chromebox_10th_audio_driver/_bmad-output/planning-artifacts/architecture.md
jack 4f9b23d144 bmad base
2026-04-05 13:24:31 +08:00

29 KiB
Raw Blame History

stepsCompleted, inputDocuments, workflowType, lastStep, status, completedAt, project_name, user_name, date
stepsCompleted inputDocuments workflowType lastStep status completedAt project_name user_name date
1
2
3
4
5
6
7
8
_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
architecture 8 complete 2026-04-05T12:00:00+08:00 chromebox_10th_audio_driver Jack 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（简化）

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（逻辑视图）

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

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

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

Decisions & patterns

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

Validation

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

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 为调度主线。

Reference in New Issue View Git Blame Copy Permalink