文档体例与改写约定（全项目）
范围：本仓库自有说明文字——README.md、docs/、audio_topology/、patches/**/README*.md、根目录 next.md、REPO_INDEX.md、help.md 等。
不包含：_bmad/（BMad 安装树）、.cursor/ 技能包、kernel-src//chromiumos_kernel/ 内上游源码（除非本仓库另有 README 说明）。
目的：统一口吻、入口与术语，便于本人、代理与换机交接阅读；与 DOCUMENTATION_ARCHITECTURE.md（结构）互补——本文管「怎么写」，架构文管「往哪放」。
1. 语言与语气
| 项 |
约定 |
| 默认 |
简体中文（与 _bmad/bmm/config.yaml 中 document_output_language 一致）。 |
| 技术专名 |
保留英文：SOF、iDisp、PIPEWIRE、plughw、STREAM_PCM_PARAMS、dynamic_debug、内核符号与路径。 |
| 句式 |
说明体：先可执行结论或指向，再背景；避免口号式空话。 |
| 版本与事实 |
写内核版本、uname、deb 后缀时写全或指到 WORK_PROGRESS/操作记录，避免半句过时数字。 |
2. 入口与互链（硬约定）
| 规则 |
说明 |
| 唯一根 README |
仅 README.md；不在子目录另立「第二 README」抢入口。 |
| 主题索引 |
新增/改名主题文档后，在 docs/INDEX.md 增加或更新一行链入；全路径速查维护 REPO_INDEX.md。 |
| 占位文件 |
docs/WORK_PROGRESS.md、docs/Linux_HDMI_Audio_Roadmap.md 仅作重定向，正文以 meta/、linux-hdmi/ 为准。 |
| BMad |
docs/index.md（小写）与 INDEX.md 并存；代理规则 _bmad-output/project-context.md；勿合并二者。 |
| NFR4 同事务 |
新增或移动主题文档、或改变 docs/ 导航结构时，在同一变更集（或紧随的提交）中更新 docs/INDEX.md 与/或 REPO_INDEX.md；见 §6。 |
3. 文件命名（建议）
| 模式 |
用途 |
OPERATION_*.md |
可重复执行的操作步骤（安装、trace、采集）。 |
FIX_PLAN_*.md / REPAIR_Plan_*.md |
分阶段修复策略或跨平台总方案。 |
*_Roadmap.md |
路线图、成功标准、已排除项。 |
PHASE_* / ANALYSIS_* |
阶段结论或对比分析。 |
4. 术语简表（Kaisa / 音频）
| 用语 |
含义 |
| Kaisa |
Google Chromebox 10 代参考板名称。 |
| Coreboot |
替代原厂固件后的引导环境（本仓库问题前提之一）。 |
| HWE 6.17 |
Ubuntu 24.04 的 linux-hwe-6.17 内核线（文档与补丁默认对齐对象）。 |
| ChromeOS 5.15 / ChromiumOS 5.15 |
对照用内核分支语境；不等于 Ubuntu Mainline 5.15 包。 |
5. 进度类文档分工（勿混写）
| 文件 |
只写 |
docs/meta/WORK_PROGRESS.md |
已验证事实、阶段结论、clone/版本命令。 |
next.md（根） |
临时下一步；含重启时须分 重启前 / 重启后。 |
| 路线图 / FIX_PLAN |
目标、分支、不宜投入项；不写日常命令流水账。 |
6. 改写清单（全项目落地时自检）
7. 与 Index Docs 的关系
[ID] 产出的 LLM_INDEX.md：按文件短描述导航。- 体例变更时：先改本文，再视需要更新 LLM_INDEX 一行摘要。
