chromebox_10th_audio_driver/_bmad-output/project-context.md

---
project_name: chromebox_10th_audio_driver
user_name: Jack
date: '2026-04-05T11:26:09+08:00'
sections_completed:
  - technology_stack
  - language_and_scripts
  - kernel_patches
  - documentation
  - verification_and_testing
  - workflow_and_git
  - critical_dont_miss
document_note: GPC 一次性生成（棕地：文档/脚本/内核补丁）；非 Web 应用仓库
---

# 面向 AI 代理的项目上下文（Project Context）

本文件列出在本仓库内**实现与修改**时必须遵守的规则与易错点；优先写「代理容易忽略」的约定，避免重复常识。

---

## 技术栈与版本

| 类别 | 内容 |
|------|------|
| **宿主与内核实验** | 文档以 **Ubuntu 24.04 + linux-hwe-6.17** 为基准；真机验证需与 **`uname -r`** 及 **`kernel-src` 树版本**一致。 |
| **语言** | **Bash**（`set -e` 等以现有脚本为准）、**Markdown**（文档主体）。 |
| **内核工件** | **Git 格式的补丁**（`patches/ubuntu-hwe-6.17/0001–0003`）；对照树可选 **`chromiumos_kernel/v5.15`**、**`kernel-src/linux-hwe-*`**（体积大，常不提交）。 |

### 源码与对照树（BMad PRD / 技术分析须覆盖）

以下目录为仓库约定位置；**Create PRD** 或源码级需求分析时，应视为与文档同级的输入范围（整树过大时可只登记路径 + 已检入的索引笔记）。

| 路径 | 角色 |
|------|------|
| **`chromiumos_kernel/v5.15/`** | **ChromiumOS** 第三方 Linux 内核 **5.15** 分支（克隆说明见 [docs/meta/WORK_PROGRESS.md](../docs/meta/WORK_PROGRESS.md)）。用于 HDMI / SOF / machine 层与 Ubuntu HWE 的**对照基准**。关键文件索引：[docs/linux-hdmi/CHROMEOS_KAISA_AUDIO_KERNEL_PATHS.md](../docs/linux-hdmi/CHROMEOS_KAISA_AUDIO_KERNEL_PATHS.md)。 |
| **`kernel-src/`** | **Ubuntu** `linux-hwe-*` 源码树放置与构建说明（**非** ChromiumOS 用户态；与上表配对做双树 diff）。入口：[kernel-src/README.md](../kernel-src/README.md)；对称笔记：[docs/linux-hdmi/KERNEL_SRC_LINUX_HWE617_HDMI_3.5MM_PATHS.md](../docs/linux-hdmi/KERNEL_SRC_LINUX_HWE617_HDMI_3.5MM_PATHS.md)。 |
| **非核心** | 无 `package.json` 类主应用；不要默认引入 Node/Python 项目脚手架。 |

---

## 关键实现规则

### 文档

- **体例与全项目改写约定**：[**docs/meta/DOCUMENTATION_STYLE.md**](../docs/meta/DOCUMENTATION_STYLE.md)（语言、命名、进度类分工）。
- **唯一根 README**：仓库根目录仅 **[README.md](../README.md)**；新增主题文档须在 **[docs/INDEX.md](../docs/INDEX.md)**（及需要时 **[REPO_INDEX.md](../REPO_INDEX.md)**）增加链接，避免孤岛页。
- **路线图与进度**：Linux HDMI 以 **[docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md](../docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md)** 为准；交接与阶段结论同步 **[docs/meta/WORK_PROGRESS.md](../docs/meta/WORK_PROGRESS.md)**。
- **语言**：`document_output_language` 为中文时，用户面向说明以**简体中文**为主，与 **`_bmad/bmm/config.yaml`** 一致。

### Shell 脚本（`scripts/`）

- 新脚本放在 **`scripts/`**，命名与现有 **`ubuntu-hwe-617-build.sh`**、**`verify-ubuntu-hwe617-patches-runtime.sh`** 风格一致（小写、连字符）。
- 依赖 **`kernel-src`** 或 **`PATCH=`** 路径时，在脚本注释或 `--help` 中写明**工作目录**（通常仓库根）。

### 内核补丁（`patches/ubuntu-hwe-6.17/`）

- **应用顺序**：先 **0001**，再 **0002**；**0003** 可选且与 0001/0002 **独立**（仅 `hda-dai.c`）。每次 **`apply`** 用环境变量 **`PATCH=...`** 指向**单文件**，见 **[README.md](../patches/ubuntu-hwe-6.17/README.md)**。
- **0002 日志**：需 **`sof_debug` 含 bit 11（2048）** 与 **`dynamic_debug`**（如 `file ipc3-pcm.c +p`）；属诊断增强，**不改变** IPC 载荷语义。
- **0003**：依赖 **`dynamic_debug`**（`hda-dai.c +p`）；用于观察 **`stream_tag`** 等，**不改变** DMA 行为。
- 设计新补丁前应对照 **ChromeOS 5.15 ↔ 6.17** 流程与 **[DIFF_SUMMARY.txt](../patches/ubuntu-hwe-6.17/DIFF_SUMMARY.txt)**，避免重复已否决路径。

### 验证与「测试」

- 补丁验证流程以 **[VERIFY_PATCHES.md](../patches/ubuntu-hwe-6.17/VERIFY_PATCHES.md)** 与 **`scripts/verify-ubuntu-hwe617-patches-runtime.sh`** 为准；成功时脚本可输出 **`VERIFY_OK`**。
- **`RUN_HDMI_TEST=0`** 可跳过 **`speaker-test`**；HDMI 设备号因机而异，可用环境变量（如脚本中的 HDMI plughw）覆盖默认值。
- **现象区分**：**`plughw:0,2` 不一定是 3.5mm**；耳机/模拟口以 **`aplay -L`** 与采集文档为准，避免在文档中写死错误映射。

### 工作流与 Git

- 变更范围：**最小必要 diff**；不顺带大重构无关文件。
- 大目录（**`kernel-src/`**、完整 **`chromiumos_kernel/`**）遵守 **`.gitignore`**，勿提交二进制或整树 tarball。

---

## 严禁遗漏（易错）

1. **文档入口**：改 `docs/` 结构时同步 **INDEX / REPO_INDEX**，否则代理与用户都会迷路。
2. **内核版本一致性**：补丁说明、**dmesg**、**`verify-*`** 必须与**当前运行的内核构建**一致。
3. **勿把本仓库当成前端项目**：无 ESLint/React 约定；规则以 **Bash、内核补丁、Markdown** 为准。
4. **HDMI 仍无声时**：以 **[FIX_PLAN_HDMI_FROM_SOURCE_ANALYSIS.md](../docs/linux-hdmi/FIX_PLAN_HDMI_FROM_SOURCE_ANALYSIS.md)** 与路线图阶段为准，避免在未读源码对照的情况下硬改路由。

---

## 维护

- 与 **BMad** 并列的索引：**[docs/index.md](../docs/index.md)**（小写，AI 检索）、**[docs/INDEX.md](../docs/INDEX.md)**（人用总目）。
- 更新本文件时机：变更补丁策略、验证方式或文档入口约定时。