From 760bdf2c9bce82126722bbd0fd918d1b67cc7e38 Mon Sep 17 00:00:00 2001 From: jack Date: Mon, 6 Apr 2026 21:59:41 +0800 Subject: [PATCH] Initial commit --- .gitignore | 12 + README.md | 36 +++ REPO_INDEX.md | 56 ++++ _bmad-output/planning-artifacts/epics.md | 212 ++++++++++++ _bmad-output/planning-artifacts/prd.md | 158 +++++++++ _bmad/scripts/render_bmad_help_zh_cn.py | 306 ++++++++++++++++++ audio_topology/COLLECT.md | 34 ++ .../collect_linux_audio_topology.sh | 285 ++++++++++++++++ bmad-help.zh-CN.md | 173 ++++++++++ debian/changelog | 64 ++++ debian/control | 25 ++ debian/kaisa-hdmi-pipewire-fix.postinst | 17 + debian/kaisa-hdmi-pipewire-fix/DEBIAN/control | 21 ++ .../kaisa-hdmi-pipewire-fix/DEBIAN/postinst | 17 + debian/kaisa-hdmi-pipewire-fix/DEBIAN/postrm | 4 + .../doc/kaisa-hdmi-pipewire-fix/README.md | 49 +++ debian/rules | 3 + docs/INDEX.md | 9 + docs/README.md | 12 + .../OPERATION_PipeWire_Kaisa_HDMI.md | 292 +++++++++++++++++ .../REPRO_Kaisa_Deb_ProAudio_Manual.md | 155 +++++++++ .../kaisa-hdmi-iec958-pipewire.service | 15 + help.md | 80 +++++ next.md | 13 + .../chromeos-ubuntu-sound-diffs/README.md | 5 + reference/ucm2/README.md | 49 +++ scripts/capture-ubuntu-audio-baseline.sh | 128 ++++++++ scripts/restore-ubuntu-audio-baseline.sh | 80 +++++ 28 files changed, 2310 insertions(+) create mode 100644 .gitignore create mode 100644 README.md create mode 100644 REPO_INDEX.md create mode 100644 _bmad-output/planning-artifacts/epics.md create mode 100644 _bmad-output/planning-artifacts/prd.md create mode 100755 _bmad/scripts/render_bmad_help_zh_cn.py create mode 100644 audio_topology/COLLECT.md create mode 100755 audio_topology/collect_linux_audio_topology.sh create mode 100644 bmad-help.zh-CN.md create mode 100644 debian/changelog create mode 100644 debian/control create mode 100755 debian/kaisa-hdmi-pipewire-fix.postinst create mode 100644 debian/kaisa-hdmi-pipewire-fix/DEBIAN/control create mode 100755 debian/kaisa-hdmi-pipewire-fix/DEBIAN/postinst create mode 100755 debian/kaisa-hdmi-pipewire-fix/DEBIAN/postrm create mode 100644 debian/kaisa-hdmi-pipewire-fix/usr/share/doc/kaisa-hdmi-pipewire-fix/README.md create mode 100755 debian/rules create mode 100644 docs/INDEX.md create mode 100644 docs/README.md create mode 100644 docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md create mode 100644 docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md create mode 100644 docs/linux-hdmi/systemd-user/kaisa-hdmi-iec958-pipewire.service create mode 100644 help.md create mode 100644 next.md create mode 100644 reference/chromeos-ubuntu-sound-diffs/README.md create mode 100644 reference/ucm2/README.md create mode 100755 scripts/capture-ubuntu-audio-baseline.sh create mode 100755 scripts/restore-ubuntu-audio-baseline.sh diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000000..af646c46f6 --- /dev/null +++ b/.gitignore @@ -0,0 +1,12 @@ +/*.deb +/*.buildinfo +/*.changes + +# capture-ubuntu-audio-baseline.sh 本地基线（含 topology / tar，体积与隐私不宜入库） +audio_topology/baseline-stash/ + +# 本机 sound/soc 等对照 diff（可选放入 reference/chromeos-ubuntu-sound-diffs/） +reference/chromeos-ubuntu-sound-diffs/diff-u_*.txt + +# dh_* 本地缓存（勿提交；可能含旧路径如 kernel-src） +debian/.debhelper/ diff --git a/README.md b/README.md new file mode 100644 index 0000000000..a3038e9d9a --- /dev/null +++ b/README.md @@ -0,0 +1,36 @@ +# chromebox_10th_audio_driver + +Google **Kaisa**（Chromebox 10）上 **Ubuntu + PipeWire** 的 **HDMI 出声**交付：仓库主线为 **`pro-audio` + IEC958 + WirePlumber 片段**（及可选 **UCM2**），与 **`kaisa-hdmi-pipewire-fix` deb**。**自编内核 / SOF 诊断补丁**与 **`kernel-src/` 大目录**已不随仓库提供；若要做 **ChromiumOS ↔ HWE** 源码对照，在本机 **`apt source linux-hwe-6.17`** 后对两棵树自行 **`diff -u`** / **`diff -rq`**（**`chromiumos_kernel/v5.15`** 与解压的 `linux-hwe-6.17-*`）。 + +## 文档（仅保留已实机验证路线） + +| 你想… | 打开 | +| ----- | ---- | +| **操作与排障**（WirePlumber、`50-kaisa-…`、deb、基线脚本） | [docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md](docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md) | +| **deb 手顺与验收** | [docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md](docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md) | +| 速查下一步 | [next.md](next.md) | +| 全仓库路径与脚本表 | [REPO_INDEX.md](REPO_INDEX.md) | +| UCM2 源码（打入 deb） | [reference/ucm2/README.md](reference/ucm2/README.md) | +| 拓扑采集脚本 | [audio_topology/COLLECT.md](audio_topology/COLLECT.md) | +| BMad 菜单码 | [bmad-help.zh-CN.md](bmad-help.zh-CN.md) | +| 产品需求（若仍用 BMad） | [_bmad-output/planning-artifacts/prd.md](_bmad-output/planning-artifacts/prd.md) | + +**仅本文件为根 README**；`docs/` 下不再维护旧版 ChromiumOS/路线图索引。 + +--- + +## 现象速览（Kaisa） + +| 平台 | HDMI | 3.5mm | +|------|------|-------| +| Linux（本仓库目标） | 需 **pro-audio profile** + 正确 **IEC958** / 默认 sink；**`stereo-fallback` 常仅一路** | 一般有（以本机 `aplay -L` 为准） | + +细节以 **OPERATION** 为准。 + +--- + +## 速链 + +- **基线**：`scripts/capture-ubuntu-audio-baseline.sh`（装 deb / 大改前）、`scripts/restore-ubuntu-audio-baseline.sh`（回滚）— [OPERATION](docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md) §4.5。 +- **打 deb**：`debian/` + `scripts/build-deb.sh`（**≥0.3.0** 包内为 **UCM2 + WirePlumber 片段**，无随包 shell 工具）。 +- 原始拓扑与 dmesg：`audio_topology/collected/`（`baseline-stash/` 见 `.gitignore`）。 diff --git a/REPO_INDEX.md b/REPO_INDEX.md new file mode 100644 index 0000000000..e55210adee --- /dev/null +++ b/REPO_INDEX.md @@ -0,0 +1,56 @@ +# 全仓库索引（路径速查） + +**当前维护文档**以根 [README.md](./README.md) 为准（**OPERATION** / **REPRO** / **next**）。 + +## 大目录 + +| 路径 | 说明 | +| ---- | ---- | +| [`.cursor/`](./.cursor/) | Cursor 配置，非业务源码 | +| [`chromiumos_kernel/v5.15/`](./chromiumos_kernel/v5.15/) | 可选对照用 ChromiumOS 5.15 树（浅克隆常见） | +| [`reference/ucm2/`](./reference/ucm2/) | Kaisa UCM2 overlay；见 [reference/ucm2/README.md](./reference/ucm2/README.md) | +| [`reference/chromeos-ubuntu-sound-diffs/`](./reference/chromeos-ubuntu-sound-diffs/) | 可选：本机 `diff -u` 生成物目录（见目录内 README） | +| [`_bmad/`](./_bmad/) | BMad 模块；总表 [`_bmad/_config/bmad-help.csv`](./_bmad/_config/bmad-help.csv) | +| [`_bmad-output/`](./_bmad-output/) | BMad 生成物（若存在） | + +## [`docs/`](./docs/) — 正式文档 + +| 文件 | 说明 | +| ---- | ---- | +| [docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md](./docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md) | PipeWire / deb / 基线 | +| [docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md](./docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md) | deb 验收手顺 | + +## [`audio_topology/`](./audio_topology/) + +| 文件 | 说明 | +| ---- | ---- | +| [COLLECT.md](./audio_topology/COLLECT.md) | 拓扑采集用法 | +| [collect_linux_audio_topology.sh](./audio_topology/collect_linux_audio_topology.sh) 等 | 采集脚本 | +| [`collected/`](./audio_topology/collected/) | 实机 `*.txt` 等原始输出 | + +## [`scripts/`](./scripts/) — 脚本 + +| 脚本 | 说明 | +| ---- | ---- | +| [capture-ubuntu-audio-baseline.sh](./scripts/capture-ubuntu-audio-baseline.sh) | 安装 deb / 大改前采集系统音频基线 | +| [restore-ubuntu-audio-baseline.sh](./scripts/restore-ubuntu-audio-baseline.sh) | 恢复到某次基线 | +| [build-deb.sh](./scripts/build-deb.sh) | 生成 `kaisa-hdmi-pipewire-fix_*.deb`（**≥0.3.0** 仅 **UCM2 + WirePlumber**，无 `/usr/bin` 辅助脚本） | + +BMad 中文帮助表生成：[`_bmad/scripts/render_bmad_help_zh_cn.py`](./_bmad/scripts/render_bmad_help_zh_cn.py) → 根目录 `bmad-help.zh-CN.md`。 + +## [`debian/`](./debian/) + +`kaisa-hdmi-pipewire-fix` 包定义与安装文件。 + +## 根目录 + +| 文件 | 说明 | +| ---- | ---- | +| [README.md](./README.md) | 仓库说明 | +| [next.md](./next.md) | 下一步速查 | +| [help.md](./help.md) | BMad 菜单码 | + +## 维护 + +- 新增说明性文档：放入 **`docs/linux-hdmi/`** 或更新 **OPERATION**。 +- 大目录变更：在本文件补一行。 diff --git a/_bmad-output/planning-artifacts/epics.md b/_bmad-output/planning-artifacts/epics.md new file mode 100644 index 0000000000..a9ea266bb5 --- /dev/null +++ b/_bmad-output/planning-artifacts/epics.md @@ -0,0 +1,212 @@ +--- +stepsCompleted: + - ce-brownfield-synthesis-2026-04-06 +inputDocuments: + - _bmad-output/planning-artifacts/prd.md +architecturePresent: false +uxPresent: false +workflowType: epics +--- + +# chromebox_10th_audio_driver — Epic 与 Story 分解 + +**作者：** Jack +**日期：** 2026-04-06 +**依据：** [prd.md](./prd.md)（含 §3.1 SC↔FR、附录 A） + +**说明：** 当前 **`planning-artifacts/`** 下**无** `architecture.md` / UX；本分解**仅追溯 PRD**。若后续补 **[CA]**，可增 Story 或调整验收中的技术约束。 + +--- + +## 概览 + +将 PRD **FR1–FR9** 与 **NFR1–NFR5** 拆为 **4 个 Epic**、**12 个 Story**，便于 **[SP] Sprint Planning** 生成 `sprint-status.yaml`。 + +--- + +## 需求清单（摘自 PRD） + +### 功能需求（FR） + +| ID | 能力 | +|----|------| +| FR1 | 文档索引 | +| FR2 | Linux HDMI 路线图 | +| FR3 | 内核诊断补丁可追溯 | +| FR4 | 构建与验证脚本 | +| FR5 | 桌面 HDMI 操作说明 | +| FR6 | 登录自动修复（Kaisa） | +| FR7 | WirePlumber 片段示例 | +| FR8 | 对照与导出 | +| FR9 | BMad 规划链 | + +### 非功能需求（NFR） + +| ID | 类别 | +|----|------| +| NFR1 | 文档语言（简体中文） | +| NFR2 | 可维护性（大目录不提交约定） | +| NFR3 | 变更粒度（最小 diff） | +| NFR4 | 安全与权限（user systemd 优先） | +| NFR5 | 诚实边界（pro-audio 多 Pro N） | + +### UX 设计需求 + +无（CLI/文档为主）。 + +### FR 覆盖映射 + +| Epic | 覆盖的 FR | 覆盖的 NFR（横切） | +|------|-----------|---------------------| +| E1 文档与入口 | FR1, FR2, FR9 | NFR1, NFR2, NFR3 | +| E2 内核诊断与构建 | FR3, FR4 | NFR2, NFR3 | +| E3 桌面 HDMI 用户态 | FR5, FR6, FR7 | NFR1, NFR4, NFR5 | +| E4 双树与上游材料 | FR8 | NFR2, NFR3 | + +--- + +## Epic 列表 + +| ID | 标题 | 目标（一句话） | +|----|------|----------------| +| **E1** | 文档入口与 HDMI 叙事 | 读者能从 README/INDEX 到达路线图、OPERATION、PRD。 | +| **E2** | 内核诊断补丁与构建验证 | 单补丁可检、脚本可跑、文档可跟。 | +| **E3** | Kaisa 桌面 HDMI（PipeWire / IEC958） | 操作说明 + 片段 + 登录自动修复闭环。 | +| **E4** | ChromeOS ↔ Ubuntu 对照与上游 | diff/export 与文档入口可发现。 | + +--- + +## Epic 1：文档入口与 HDMI 叙事 + +**目标：** 满足 **SC1** 与 **FR1、FR2、FR9**；新贡献者 10 分钟内找到 Linux HDMI 主线。 + +### Story 1.1：INDEX 与 OPERATION/REPRO + +作为一名**维护者**， +我希望 **INDEX.md** 能链到 **OPERATION** 与 **REPRO**， +以便 **不必搜全库**（**FR1**）。 + +**验收标准：** + +- **Given** 仓库根已克隆 +- **When** 打开 `docs/INDEX.md` +- **Then** 存在指向 `OPERATION_PipeWire_Kaisa_HDMI.md` 与 `REPRO_Kaisa_Deb_ProAudio_Manual.md` 的条目 + +### Story 1.2：（已收敛）路线图 + +**状态：** **`Linux_HDMI_Audio_Roadmap.md`** 与 **WORK_PROGRESS** 类长文已删除；**FR2** 以 **OPERATION + REPRO** 为事实源。 + +### Story 1.3：README 与 PRD / BMad 链 + +作为一名**产品/维护者**， +我希望 **根 README** 指向 **PRD** 与（可选）**epics**， +以便 **BMad 规划链**可追溯（**FR9**）。 + +**验收标准：** + +- **Given** `README.md` 为唯一根 README +- **When** 查看文档入口表 +- **Then** 存在指向 `_bmad-output/planning-artifacts/prd.md` 的链接 +- **And** 可增链至本 `epics.md`（建议与 INDEX 中 BMad 表一致） + +--- + +## Epic 2：（已收敛）内核诊断补丁与自编内核 + +**状态：** 仓库已移除 **`patches/ubuntu-hwe-6.17/`** 与 **`verify-*` / `ubuntu-hwe-617-build.sh`**；原 **SC2 / FR3 / FR4** 故事**作废**。 +若需本地 HWE 源码与 ChromiumOS 对照，在本机 **`apt source linux-hwe-6.17`** 后设 **`export UB=…`**，见 **`reference/chromeos-ubuntu-sound-diffs/README.md`**。 + +--- + +## Epic 3：Kaisa 桌面 HDMI（PipeWire / IEC958） + +**目标：** 满足 **SC3** 与 **FR5、FR6、FR7**；与 **NFR4、NFR5** 一致。 + +### Story 3.1：OPERATION 覆盖 pro-audio / EBUSY / IEC958 / 全自动 + +作为一名 **Kaisa 用户**， +我希望 **OPERATION_PipeWire_Kaisa_HDMI.md** 说明 **pro-audio**、**`speaker-test -D pulse`**、**IEC958',N** 与 **§4.3 安装器**， +以便 **排障不靠口口相传**（**FR5**）。 + +**验收标准：** + +- **Given** 用户使用 PipeWire 桌面会话 +- **When** 按 §3–§4 操作 +- **Then** 能区分 **plughw EBUSY** 与 **Pulse 路径**；§4.2 含 **IEC958** 根因；§4.3 含 **install** 命令 + +### Story 3.2：WirePlumber 片段可复制 + +作为一名 **Kaisa 用户**， +我希望 **`50-kaisa-sof-rt5682-hdmi.conf`** 在仓库内完整且与 OPERATION 路径一致， +以便 **复制到 `~/.config/wireplumber/...`**（**FR7**）。 + +**验收标准：** + +- **Given** 文件在 `docs/linux-hdmi/wireplumber/` +- **When** 按 OPERATION §2 安装 +- **Then** `device.name` 与优先级说明在文中有「PCI 变化时如何改」提示（**NFR5** 相关） + +### Story 3.3：登录自动恢复（user systemd） + +作为一名 **Kaisa 用户**， +我希望按 **OPERATION §4.3** 配置 **user systemd**（自建 **`pactl`/`amixer`**），且可 **`disable --now`** 停用， +以便 **重启后仍能自动恢复 HDMI**（**FR6**，**NFR4**）。 + +**验收标准：** + +- **Given** 用户会话可用 `systemctl --user` +- **When** 按 §4.3 自建单元并 **enable** +- **Then** 登录后执行恢复；停用时 **disable** 单元且不删 WirePlumber 片段 + +--- + +## Epic 4：双树对照与上游材料 + +**目标：** 满足 **SC4** 与 **FR8**。 + +### Story 4.1：双树对照说明与可选输出目录 + +作为一名**上游贡献者**， +我希望 **ChromeOS ↔ Ubuntu** 对照方式与 **可选** diff 输出目录在文档中可查， +以便 **投递前自证边界**（**FR8**）。 + +**验收标准：** + +- **Given** 根目录 **`REPO_INDEX.md`** 与 **`reference/chromeos-ubuntu-sound-diffs/README.md`** +- **When** 查找 sound/soc 对照 +- **Then** 说明本机两树路径（**`chromiumos_kernel/v5.15`**、`apt source` 解压目录）及 **`diff -u` / `diff -rq`** 用法 +- **And** 输出目录 **`reference/chromeos-ubuntu-sound-diffs/`** 有 README（生成物可选、默认 gitignore） + +### Story 4.2：双树齐全性（可选） + +作为一名**维护者**， +我在运行 **`diff`** 前自行确认两棵树路径存在， +以便 **不误报空 diff**（**FR8** 质量）。 + +**验收标准：** + +- **Given** 未克隆 `chromiumos_kernel` 或未准备 HWE 解压目录 +- **When** 尝试对照 +- **Then** 自行补全树后再 `diff`（无仓库级预检脚本） + +--- + +## 横切 NFR 守门（不单独 Epic） + +| NFR | 落实方式 | +|-----|----------| +| NFR1 | 上述 Story 验收说明与用户文档保持简体中文。 | +| NFR2 | Story 2.2、4.2 强调大目录不提交与 clone 约定。 | +| NFR3 | Code review / 自检：无关文件不混入 PR。 | +| NFR4 | Story 3.3 明确 user 单元，不强制 root alsactl 为唯一方案。 | +| NFR5 | Story 3.1、3.2 保持 OPERATION 中「多 Pro N」说明。 | + +**PRD 附录 A：** 可作为 Epic 1/2 的 **CI 任务** 或发布前 **checklist**。 + +--- + +## 后续 + +- **[SP] Sprint Planning**：由本文件生成 **`implementation-artifacts/sprint-status.yaml`**。 +- **[CA]**：若补充 **architecture.md**，可在 **E2/E3** 增加「与架构决策 §X 对齐」验收行。 +- **[GPC]**：重建 **project-context.md** 时可将本 Epic 列表摘要写入。 diff --git a/_bmad-output/planning-artifacts/prd.md b/_bmad-output/planning-artifacts/prd.md new file mode 100644 index 0000000000..f771ed2afb --- /dev/null +++ b/_bmad-output/planning-artifacts/prd.md @@ -0,0 +1,158 @@ +--- +stepsCompleted: + - prd-brownfield-synthesis-2026-04-06 +inputDocuments: + - README.md + - docs/INDEX.md + - docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md + - docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md +workflowType: prd +brownfield_synthesis: true +synthesis_note: 棕地仓库；经 [VP] 校验后 [EP] 修订（SC↔FR 映射、可脚本化验收附录）。 +last_edited: '2026-04-06' +--- + +# 产品需求文档（PRD）— chromebox_10th_audio_driver + +**作者：** Jack +**日期：** 2026-04-06 +**状态：** 基线重建；已按 **`prd-validation-report.md`** 做 [EP] 修订（P2/P4） + +**2026-04 文档收敛**：仓库已删除 ChromiumOS 长文、路线图、WORK_PROGRESS 等；**事实与验收**以 **README.md**、**OPERATION_PipeWire_Kaisa_HDMI.md**、**REPRO_Kaisa_Deb_ProAudio_Manual.md** 为准。下文仍出现旧路径处视为历史表述。 + +--- + +## 1. 摘要 + +本「产品」为 **Google Kaisa（Chromebox 10 代 / Coreboot）跨平台音频** 的 **文档、脚本与 deb** 单体仓库，**交付主线**是 **Linux 下 HDMI 可稳定出声**（PipeWire / pro-audio / IEC958）；**自编内核与 SOF 诊断补丁**已不在仓库内维护。保留 **ChromeOS 源码树对照** 与 **拓扑采集**。 + +**已验证关键用户态根因（Kaisa）**：**`IEC958',0`（pcm=2）关闭**时 PipeWire 可看似正常但 **HDMI 无声**；**打开后即有声**。登录自动恢复见 **OPERATION §4.3**（规划中；当前 **pactl**/**amixer** 手顺）。 + +--- + +## 2. 愿景与要解决的问题 + +| 维度 | 说明 | +|------|------| +| **问题** | 同机 **ChromeOS / Windows HDMI 正常**，**Linux** 常 **HDMI 无声或难以选路**；需分层区分 **内核/SOF/IPC** 与 **PipeWire/ALSA 混音器**。 | +| **愿景** | 维护者可 **可重复** 构建、验证、采集；最终用户（技术门槛较低时）可通过 **安装脚本/未来打包** 获得 **开箱可用** 的 HDMI 音频。 | +| **非目标** | 不承诺任意 x86 机型通用；**Windows 3.5mm** 等为参考文档，**不**作为 Linux HDMI 的阻塞依赖（与 README 范围一致）。 | + +--- + +## 3. 成功标准（可验收） + +1. **文档**：存在 **入口链**（根 README → INDEX → OPERATION/REPRO）；**Linux HDMI** 以用户态路线为主。 +2. **（已移除）内核诊断补丁**：不再作为仓库交付物；需要时自行在本地内核树实验。 +3. **桌面 HDMI（Kaisa）**：文档描述 **WirePlumber `pro-audio`**、**IEC958',N** 根因及 **OPERATION §4.3**（自动化规划中）。 +4. **对照与采集**：**ChromeOS ↔ HWE** 可在本机双树 **`diff`**；**`audio_topology/`** 采集可复现材料。 + +### 3.1 成功标准与 FR 对应（追溯） + +| 成功标准 | 主要支撑的 FR | 说明 | +|----------|---------------|------| +| **SC1** 文档入口与分流 | **FR1**、**FR2**、**FR9** | INDEX → OPERATION/REPRO；README 链至本 PRD。 | +| **SC2**（历史）内核诊断 | — | **已收敛**：仓库不再包含补丁与 verify 脚本。 | +| **SC3** 桌面 HDMI 可恢复 | **FR5**、**FR6**、**FR7** | OPERATION、WirePlumber 片段、user systemd 说明；与 **NFR4** 一致。 | +| **SC4** 对照材料可及 | **FR8**、**FR2** | 两棵内核树 + 可选 **`reference/chromeos-ubuntu-sound-diffs/`**；**`audio_topology/`** 采集。 | + +--- + +## 4. 用户旅程（摘要） + +| 角色 | 目标 | 主要触点 | +|------|------|----------| +| **维护者 / Jack** | 可选内核对照、脚本 | `chromiumos_kernel/`、`scripts/`（HWE 源码树本机自行 `apt source`） | +| **另一台 Kaisa 用户** | 在 Ubuntu + PipeWire 上让 HDMI 有声 | `OPERATION_PipeWire_Kaisa_HDMI.md`、`50-kaisa-sof-rt5682-hdmi.conf`、deb 内工具 | +| **上游读者** | IPC/内核对照 | 本地两棵内核树 + 可选 `reference/chromeos-ubuntu-sound-diffs/`（本机 diff 输出） | + +--- + +## 5. 范围 + +### 5.1 范围内（In） + +- Linux：**SOF / iDisp / HDMI** 文档、自编 HWE 内核流程、**诊断补丁**、采集脚本。 +- 桌面：**PipeWire / WirePlumber / IEC958** 操作说明与 **user systemd** 自动恢复（见 OPERATION §4.3）。 +- **INDEX**、代理用 **project-context**（待 **[GPC]** 重建）。 + +### 5.2 范围外（Out）或低优先级 + +- 通用 Linux 发行版 **正式包维护**（deb/PPA）列为 **后续**，见 sprint-change-proposal 类叙述；本 PRD **不**要求立即上架商店。 +- **图形化「应用」**（GUI）非当前必须；**CLI/系统服务** 可接受。 + +--- + +## 6. 功能需求（FR）— 能力契约 + +| ID | 能力 | 验收要点 | +|----|------|----------| +| **FR1** | **文档索引** | 人读 **INDEX.md** 可到达 **OPERATION**、**REPRO**。 | +| **FR2** | **Linux HDMI 技术路线** | **OPERATION_PipeWire_Kaisa_HDMI.md** 覆盖 pro-audio / UCM / deb；**REPRO** 为验收手顺。 | +| **FR5** | **桌面 HDMI 操作说明** | **OPERATION_PipeWire_Kaisa_HDMI.md** 覆盖 **pro-audio**、**plughw EBUSY**、**IEC958 §4.2**、**§4.3 登录自动 restore**。 | +| **FR6** | **登录自动修复（Kaisa）** | **OPERATION §4.3**：**user systemd** 示例 + 手顺；**deb ≥0.3.0** 不随包提供可执行工具。 | +| **FR7** | **WirePlumber 片段示例** | **`50-kaisa-sof-rt5682-hdmi.conf`** 可复制到 **`~/.config/wireplumber/...`**。 | +| **FR8** | **对照与导出** | **ChromeOS ↔ Ubuntu**：本机两树 **`diff`**；可选输出至 **`reference/chromeos-ubuntu-sound-diffs/`**（见该目录 README）。 | +| **FR9** | **BMad 规划链** | **本 PRD** 与（可选）**architecture / epics** 可链接；**README** 指向 **`_bmad-output/planning-artifacts/prd.md`**。 | + +### 附录 A：FR1 可脚本化验收（可选） + +在**仓库根**执行；用于 CI 或本地 **`bash -c`** 快速检查**关键文件是否存在**。 + +**FR1（文档索引链）** + +```bash +test -f docs/INDEX.md +test -f docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md +test -f docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md +grep -q 'OPERATION_PipeWire_Kaisa_HDMI' docs/INDEX.md +``` + +--- + +## 7. 非功能需求（NFR） + +| ID | 类别 | 要求 | +|----|------|------| +| **NFR1** | **文档语言** | 用户面向说明以 **简体中文** 为主（与 **bmm/config** 一致）。 | +| **NFR2** | **可维护性** | 大目录（如 `chromiumos_kernel/`、本机 HWE 解压树）**不强制入库**；对照脚本用 **`UB=`** 指向本机路径。 | +| **NFR3** | **变更粒度** | 代码/脚本以 **最小 diff** 对齐现有风格；避免无关重构。 | +| **NFR4** | **安全与权限** | 用户态修复以 **`systemctl --user`** 为主；**避免**要求普通用户长期 **root** 改系统 ALSA 全局状态作为唯一路径。 | +| **NFR5** | **诚实边界** | **`pro-audio`** 下 GNOME 可能 **列出多路 Pro N**；文档说明与 **「仅插线才显示」** 的取舍。 | + +--- + +## 8. 假设与依赖 + +- **产品简报**：无独立 **Product Brief**；棕地事实源以 **`README.md`** 与 **`docs/linux-hdmi/OPERATION_*.md`** 为准，与本 PRD 并行维护。 +- **硬件**：Google **Kaisa**、**Coreboot**、**sof-rt5682** 类 **PipeWire** 会话。 +- **OS**：文档基准 **Ubuntu 24.04 + linux-hwe-6.17**（具体 **`uname -r`** 以本机为准）。 +- **外部**：**PipeWire/WirePlumber** 大版本升级可能导致片段语法变化（需跟进上游 migration）。 + +--- + +## 9. 风险 + +| 风险 | 缓解 | +|------|------| +| 上游 **UCM/默认 IEC958** 未合并，用户仍依赖脚本 | 文档标明 **Phase C**；保留 **install** 路径。 | +| **PCI 路径变化** | **`restore`** 脚本 **`cml_rt5682` 自动检测**；**WirePlumber** 片段需按机改 **device.name**。 | +| README 与 OPERATION **编号/补丁集合** 陈旧 | 定期 **[DP]** 扫描或与真机对表。 | + +--- + +## 10. 参考（仓库内） + +- [docs/INDEX.md](../../docs/INDEX.md) +- [docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md](../../docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md) +- [docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md](../../docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md) +- [README.md](../../README.md) + +--- + +## 11. 后续 BMad 步骤（可选） + +- **[CA]** Create Architecture：若需刷新架构决策文档。 +- **[CE]** Create Epics and Stories：将 FR 拆为可跟踪 story。 +- **[GPC]** Generate Project Context：重建 **`_bmad-output/project-context.md`**。 +- **[VP]**：重大改版后再跑校验；当前 P1–P4 已在 [EP] 中处理。 diff --git a/_bmad/scripts/render_bmad_help_zh_cn.py b/_bmad/scripts/render_bmad_help_zh_cn.py new file mode 100755 index 0000000000..d4d144ce88 --- /dev/null +++ b/_bmad/scripts/render_bmad_help_zh_cn.py @@ -0,0 +1,306 @@ +#!/usr/bin/env python3 +# 根据 _bmad/_config/bmad-help.csv 与下行中文说明表，生成仓库根目录 bmad-help.zh-CN.md +from __future__ import annotations + +import csv +from pathlib import Path + +REPO = Path(__file__).resolve().parents[2] +CSV_PATH = REPO / "_bmad" / "_config" / "bmad-help.csv" +OUT_PATH = REPO / "bmad-help.zh-CN.md" + +MODULE_ZH = { + "BMad Builder": "BMad 构建器", + "BMad Method": "BMad 方法", + "Core": "核心", + "Creative Intelligence Suite": "创意智能套件（CIS）", + "Game Dev Studio": "游戏开发工作室（GDS）", + "Test Architecture Enterprise": "测试架构企业版（TEA）", + "Web Design Studio": "网页设计工作室（WDS）", +} + +PHASE_ZH = { + "anytime": "随时", + "1-analysis": "阶段 1 · 分析", + "2-planning": "阶段 2 · 规划", + "3-solutioning": "阶段 3 · 方案设计", + "4-implementation": "阶段 4 · 实现", + "0-learning": "阶段 0 · 学习", + "1-preproduction": "前期制作", + "2-design": "设计", + "3-technical": "技术", + "4-production": "制作", + "gametest": "游戏测试", + "0-wds-pitch": "WDS · 宣讲/对齐", + "0-wds-agents": "WDS · 唤醒代理", + "1-wds-strategy": "WDS · 策略", + "2-wds-design": "WDS · 设计", + "3-wds-build": "WDS · 构建/验证", +} + +# 与 CSV 行顺序一致（共 114 行），对应「sequence」列的中文说明；空原文由脚本行号对应空序列行 +ZH_BY_ROW = [ + "通过对话式梳理，创建、编辑或重建 Agent 技能。", + "对既有 Agent 做质量分析：结构、内聚、提示词工艺与改进空间。", + "安装或更新 BMad Builder 模块配置与帮助条目。", + "头脑风暴并规划 BMad 模块：创意、架构与构建计划。", + "将模块基础设施脚手架化为可安装的 BMad 模块技能。", + "检查模块结构是否完整、准确，且能力均已正确注册。", + "创建、编辑或重建工作流或工具型技能。", + "对既有工作流/技能做质量分析：结构、效率与改进空间。", + "将任意技能转换为符合 BMad 的成果导向形态，并生成前后对比 HTML 报告。", + "详细描述需求，由代理按文档最佳实践撰写；可多轮对话并子流程做调研/审阅。", + "若发现文档惯例缺失，把你的偏好写入代理记忆中的 documentation-standards.md。", + "根据描述生成 Mermaid 图；未指定类型时会建议合适的图类。", + "对照文档规范与最佳实践审查指定文档，按优先级给出可执行的改进建议。", + "为复杂概念撰写清晰技术说明，附示例与图示。", + "专家引导，使用一种或多种技法进行项目头脑风暴。", + "确保 PRD、UX、架构与 Epic/Story 彼此对齐。", + "故事循环：若有问题退回 DS；通过后进入下一 CS，或 Epic 完成时走 ER。", + "在重大变更时纠偏：可能建议重来、更新 PRD、重做架构/冲刺规划或修正 Epic 与 Story。", + "引导式产出技术决策文档（架构）。", + "在架构文档（CA）之后创建 Epic 与用户故事。", + "专家引导完成产品需求文档（PRD）。", + "故事循环起点：准备冲刺计划中「下一个」待做 Story，或指定 Epic/Story。", + "在开发开始前校验 Story 是否就绪、完整。", + "落实 UX 方案；若项目以 UI 为主，强烈建议使用。", + "故事循环：执行 Story 实现与测试，经 CR，如需修复回到 DS。", + "分析现有项目并产出可用文档。", + "行业领域深度研究、专业术语与知识沉淀。", + "在通过 PRD 校验流程后，编辑并改进指定路径的 PRD。", + "扫描代码库生成精简、面向 LLM 的 project-context.md；棕地项目尤其重要。", + "市场、竞品、客户需求与趋势分析。", + "引导式厘清产品创意与核心价值。", + "为已实现代码生成自动化 API 与 E2E 测试；非代码评审或 Story 校验（请用 CR）。", + "统一「意图进、代码出」：澄清、实现、审阅与交付展示。", + "可选：在 Epic 结束时回顾成果与经验，规划下一 Epic；重大问题考虑走 CC。", + "启动实现阶段：生成实现代理将按序执行的冲刺计划。", + "随时总结 Sprint 状态并路由到下一工作流。", + "技术可行性、架构选项与实现路径研究。", + "在创建 PRD（CP）之后校验 PRD 质量。", + "在创意早期或思路卡住时做头脑风暴。", + "生成节省 token 的蒸馏文，保留供下游 LLM 使用的关键信息。", + "成稿后润色正文表达。", + "当文档由多段子流程拼成或结构需加强时，做结构性编辑审阅。", + "判断当前所处 BMad 流程位置并回答问题；推荐下一步技能与调用方式。", + "在不加载全部文件的前提下为目录生成/更新索引，便于掌握文档地图。", + "编排多代理/多视角讨论与协作。", + "在定稿前做对抗性质量审查；其他模块的代码审也可自动调用，亦适用于文档。", + "与对抗审搭配，从边界场景做正交补充，重方法而非「挑刺态度」。", + "当单份文档过大（常为 >500 行）时拆分为可管理片段。", + "用一种或多种技法主持头脑风暴会话。", + "以同理心驱动的人本设计流程指导。", + "识别颠覆机会并设计商业模式创新。", + "运用系统化问题解决方法拆解复杂挑战。", + "用成熟叙事框架与技巧撰写故事/叙述。", + "快速游戏原型，验证机制与创意。", + "在游戏语境下主持头脑风暴。", + "在投产前确保 GDD、UX、架构与 Epic/Story 对齐。", + "对标记为「待评审」的 Story 做干净上下文的 QA 代码审查。", + "游戏开发冲刺偏离路线时进行纠偏。", + "依据 GDD 需求创建 Epic 与 Story 列表，作为开发规格驱动。", + "交互式游戏简报，引导用户明确游戏愿景。", + "撰写游戏设计文档 GDD：机制、系统、进度与实现指引。", + "为剧情向游戏撰写叙事文档：结构、人物弧与世界观。", + "从 GDD 或从零撰写 PRD，供 bmad-assist 等外部工具使用。", + "为开发代理准备上下文充分的 Story。", + "落实游戏 UX/UI；若 UI 是核心，强烈建议使用。", + "执行 Dev Story：按任务与测试实现。", + "分析现有游戏项目并产出文档。", + "游戏产业领域深度研究与术语沉淀。", + "搭建 E2E 测试基础设施脚手架。", + "改进并增强既有 PRD。", + "产出可伸缩游戏架构：引擎、系统、网络与技术设计。", + "生成适配所选智能体工具一致性的 project-context.md。", + "游戏市场、竞品与玩家需求分析。", + "设计性能测试策略。", + "撰写结构化试玩/测试计划。", + "兼顾游戏特性的灵活开发流程。", + "实验性一体化快捷流：单工作流内完成澄清、计划、实现、审阅与展示。", + "小需求、小改动、简单应用/工具，无需冗长规划。", + "在游戏开发 Epic 完成后组织团队回顾。", + "由 Epic 文件生成或更新 sprint-status.yaml。", + "查看冲刺进度、暴露风险并给出下一步行动建议。", + "游戏引擎选项与实现路径的技术可行性研究。", + "生成自动化游戏测试。", + "设计覆盖流程与质量要求的游戏测试场景。", + "为 Unity / Unreal / Godot 等项目初始化游戏测试框架架构。", + "评审测试质量与覆盖。", + "按外部工具兼容标准校验 PRD。", + "TEA 学院：通过 7 次课讲授测试基础（含进度与证书相关产出）。", + "生成失败用例（TDD 红灯阶段）。", + "扩展自动化测试覆盖。", + "配置 CI/CD 质量流水线。", + "初始化生产级测试框架脚手架。", + "非功能需求（NFR）评估。", + "基于风险的测试规划。", + "质量审计（0–100 分制）。", + "覆盖度可追溯与质量门禁决策。", + "带设计日志与浏览器验证的迭代「构建—验证」循环。", + "干系人共识 pitch 与服务协议；若做自有产品可跳过。", + "详细规格前的快速视觉草图探索；直接场景可跳过。", + "逐页逐元素记录设计决策，开发可直接据此实现。", + "校验规格完整并打包为 DD yaml，供开发交接。", + "管理组件库与设计令牌；设计系统模式为「无」时跳过。", + "第 3–4 阶段 UX 设计师代理 Freya：检查前置条件并给出下一步。", + "从规格抽取可复用模式为组件定义；无设计系统时跳过。", + "治理代理 Idun：访谈组织以配置 Agent Space 与权限模型。", + "以「人设 + 目标 + 结果」定义用户旅程，并与触发图驱动力关联。", + "平台、设备、集成与约束等技术边界；简单落地页可跳过。", + "持续改进：反馈 → 触发图 → 规格 → 代码 → 验证。", + "定义产品愿景、定位与成功标准，设计决策应可追溯至此。", + "第 1–2 阶段战略分析师代理 Saga：扫描仓库并建议下一步。", + "跨界面串联用户旅程与入口、过渡、异常路径；简单场景可跳过。", + "将业务目标映射到用户心理：人设、功能与驱动力打分。", + "在真实用户环境中做可用性测试与回顾式出声思考。", + "将规格转为带样式的 HTML 原型，可与 Figma 往返。", +] + + +def _is_arg_cell(s: str) -> bool: + """CSV 部分行在 phase 前插入了 [path] / {-H:...} 等参数列。""" + if not s: + return False + if s == "[path]": + return True + if s.startswith("{-H") or s.startswith("{--"): + return True + if s.startswith("{description:"): + return True + return False + + +def phase_token(r: list[str]) -> str: + if r[5]: + return r[7] or "" + if _is_arg_cell(r[6] or ""): + return r[7] or "" + return r[6] or "" + + +def phase_display(r: list[str]) -> str: + p = phase_token(r) + if not p or p in ("true", "false"): + return "—" + return PHASE_ZH.get(p, p) + + +def prereq_display(r: list[str]) -> str: + if r[5]: + cand = r[12] + elif _is_arg_cell(r[6] or ""): + cand = r[8] or "" + else: + cand = r[7] or "" + if not cand or cand in ("true", "false"): + return "—" + return cand + + +def required_gate(r: list[str]) -> str: + if r[5]: + return r[13] + if _is_arg_cell(r[6] or ""): + return r[13] + return r[12] + + +def output_display(r: list[str]) -> str: + if r[5]: + loc, out = r[14], r[15] + elif _is_arg_cell(r[6] or ""): + loc, out = r[14], r[15] + else: + loc, out = r[13], r[14] + parts = [x.replace("|", " · ") for x in (loc, out) if x] + return " / ".join(parts) if parts else "—" + + +def main() -> None: + with CSV_PATH.open(newline="", encoding="utf-8") as f: + rows = list(csv.reader(f))[1:] + + if len(rows) != len(ZH_BY_ROW): + raise SystemExit(f"行数不匹配: CSV {len(rows)} vs ZH {len(ZH_BY_ROW)}") + + by_mod: dict[str, list[list[str]]] = {} + for r in rows: + by_mod.setdefault(r[0], []).append(r) + + lines: list[str] = [ + "# BMad 帮助目录（中文版）", + "", + "本文档由 [`_bmad/_config/bmad-help.csv`](_bmad/_config/bmad-help.csv) 翻译并整理，便于中文读者检索 **菜单码**、**技能** 与用途。", + "", + "技能调用方式（斜杠命令 / 自然语言等）以本机 `npx bmad-method install` 与 Cursor 集成为准。", + "", + "## 表列说明", + "", + "| 列 | 含义 |", + "| --- | --- |", + "| **码** | 菜单快捷码（不同模块下可能重复，以技能名列区分） |", + "| **显示名称** | CSV 英文显示名（与上游一致，便于对照） |", + "| **技能** | 技能标识 / 工作流名 |", + "| **说明** | 对「sequence」列的中文释义 |", + "| **阶段** | 工作流阶段或触发时机（`anytime` 等为随时） |", + "| **前置** | 建议先完成的技能或条件（CSV 中错位字段已尽量还原） |", + "| **必选** | 是否后期阶段强制项（`true` / `false`） |", + "| **产出** | 主要输出位置或产物类型（保留英文路径占位符） |", + "", + "---", + "", + ] + + idx = 0 + for mod in [ + "BMad Builder", + "BMad Method", + "Core", + "Creative Intelligence Suite", + "Game Dev Studio", + "Test Architecture Enterprise", + "Web Design Studio", + ]: + mrows = by_mod.get(mod) + if not mrows: + continue + lines.append(f"## {MODULE_ZH.get(mod, mod)}") + lines.append("") + lines.append( + "| 码 | 显示名称 | 技能 | 说明 | 阶段 | 前置 | 必选 | 产出 |" + ) + lines.append("| --- | --- | --- | --- | --- | --- | --- | --- |") + for r in mrows: + zh = ZH_BY_ROW[idx] + idx += 1 + req = required_gate(r) + lines.append( + "| {code} | {name} | `{skill}` | {desc} | {phase} | {pre} | {req} | {out} |".format( + code=r[3].replace("|", "\\|"), + name=r[2].replace("|", "\\|"), + skill=r[1].replace("|", "\\|"), + desc=zh.replace("|", "\\|"), + phase=phase_display(r).replace("|", "\\|"), + pre=prereq_display(r).replace("|", "\\|"), + req=req.replace("|", "\\|"), + out=output_display(r).replace("|", "\\|"), + ) + ) + lines.append("") + + if idx != len(rows): + raise SystemExit(f"索引错误: 写了 {idx} 行，预期 {len(rows)}") + + lines.append("---") + lines.append("") + lines.append( + "*生成脚本：[`_bmad/scripts/render_bmad_help_zh_cn.py`](_bmad/scripts/render_bmad_help_zh_cn.py)（修改译文表后重新运行以更新本文档。）*" + ) + lines.append("") + + OUT_PATH.write_text("\n".join(lines), encoding="utf-8") + print(f"Wrote {OUT_PATH}") + + +if __name__ == "__main__": + main() diff --git a/audio_topology/COLLECT.md b/audio_topology/COLLECT.md new file mode 100644 index 0000000000..298212f5b7 --- /dev/null +++ b/audio_topology/COLLECT.md @@ -0,0 +1,34 @@ +# 音频拓扑收集 + +脚本用于在 **Linux / Windows / ChromeOS** 下导出 `aplay`、`pactl`、`dmesg` 等，输出默认落在 **`audio_topology/collected/`**（可按日期与主机名区分文件）。 + +## 对外分享与脱敏 + +采集输出可能含 **hostname、账号** 等；外发或贴 issue 前请自行裁剪。 + +## 目录结构 + +- `collect_linux_audio_topology.sh` — Linux +- `collect_windows_audio_topology.ps1` — Windows +- `collect_chromeos_audio_topology.sh` — ChromeOS（crosh → shell） +- `collected/` — 原始输出（`*.txt` 等） + +## Linux + +```bash +sudo ./audio_topology/collect_linux_audio_topology.sh +# 或指定输出文件 +sudo ./audio_topology/collect_linux_audio_topology.sh /path/to/output.txt +``` + +## Windows + +在 `audio_topology` 下以管理员 PowerShell 运行 `collect_windows_audio_topology.ps1`（可用 `-OutputPath`）。 + +## ChromeOS + +见脚本内注释：crosh → `shell`，将脚本拷至设备执行，默认输出在 `/tmp/`，再拷回本仓库 `collected/`。 + +## 与当前维护文档的关系 + +排查 HDMI 用户态路由以 **[docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md](../docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md)** 为准；本目录采集为**辅助证据**，不替代该操作文档。 diff --git a/audio_topology/collect_linux_audio_topology.sh b/audio_topology/collect_linux_audio_topology.sh new file mode 100755 index 0000000000..7f8b4ee2fd --- /dev/null +++ b/audio_topology/collect_linux_audio_topology.sh @@ -0,0 +1,285 @@ +#!/bin/bash +# +# Chromebox 10 代 - Linux 音频硬件拓扑收集脚本 +# 用于 C1a 任务：在 Linux 下收集硬件拓扑信息 +# +# 用法: ./collect_linux_audio_topology.sh [输出文件] +# 默认输出到: audio_topology/collected/audio_topology_linux_$(hostname)_$(date).txt +# +# 建议: 用 sudo 运行以获取 dmesg/journalctl；pactl/wpctl 需图形会话， +# 若用 sudo 会尝试以 SUDO_USER 身份调用，否则可在桌面终端直接运行 + +set -e + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +OUTPUT_DIR="${SCRIPT_DIR}/collected" +mkdir -p "$OUTPUT_DIR" +OUTPUT="${1:-${OUTPUT_DIR}/audio_topology_linux_$(hostname)_$(date +%Y%m%d_%H%M%S).txt}" + +TMP_DIR=$(mktemp -d) +trap "rm -rf $TMP_DIR" EXIT + +log() { + echo "[$(date +%H:%M:%S)] $*" +} + +section() { + echo "" >> "$OUTPUT" + echo "========================================" >> "$OUTPUT" + echo "### $1" >> "$OUTPUT" + echo "========================================" >> "$OUTPUT" + echo "" >> "$OUTPUT" +} + +run_cmd() { + local desc="$1" + shift + echo "# $desc" >> "$OUTPUT" + echo "\`\`\`" >> "$OUTPUT" + if "$@" >> "$OUTPUT" 2>&1; then + true + else + echo "(命令返回非零，可能部分信息缺失)" >> "$OUTPUT" + fi + echo "\`\`\`" >> "$OUTPUT" + echo "" >> "$OUTPUT" +} + +log "开始收集 Linux 音频硬件拓扑..." +log "输出文件: $OUTPUT" + +: > "$OUTPUT" +echo "# Chromebox 10 代 - Linux 音频硬件拓扑" >> "$OUTPUT" +echo "# 收集时间: $(date -Iseconds)" >> "$OUTPUT" +echo "# 主机: $(hostname)" >> "$OUTPUT" +echo "" >> "$OUTPUT" + +# --- 系统信息 --- +section "系统信息" +run_cmd "uname -a" uname -a +run_cmd "内核版本" uname -r +run_cmd "/proc/version" cat /proc/version +if command -v alsactl &>/dev/null; then + run_cmd "ALSA 版本" alsactl --version 2>/dev/null || echo "alsactl 无版本信息" +fi + +# --- PCI 音频设备 --- +section "PCI 音频相关设备" +if command -v lspci &>/dev/null; then + run_cmd "lspci -nn | grep -i audio (含设备 ID，便于查驱动/quirks)" bash -c "lspci -nn | grep -i audio || echo '(无匹配)'" + run_cmd "lspci | grep -i audio" bash -c "lspci | grep -i audio || echo '(无匹配)'" + run_cmd "lspci -v | grep -A 15 -i audio" bash -c "lspci -v 2>/dev/null | grep -A 15 -i audio || echo '(无匹配)'" +fi + +# --- 播放/录音设备列表 --- +section "ALSA 设备列表" +if command -v aplay &>/dev/null; then + run_cmd "aplay -l (播放设备)" aplay -l + run_cmd "aplay -L (ALSA 设备描述)" aplay -L 2>/dev/null || true +else + echo "# aplay 未安装" >> "$OUTPUT" +fi +if command -v arecord &>/dev/null; then + run_cmd "arecord -l (录音设备)" arecord -l +fi +run_cmd "cat /proc/asound/cards" cat /proc/asound/cards +run_cmd "cat /proc/asound/pcm (PCM 设备明细)" cat /proc/asound/pcm + +# --- /proc/asound 目录结构 --- +section "/proc/asound 目录结构" +run_cmd "ls -la /proc/asound" ls -la /proc/asound +for card_dir in /proc/asound/card[0-9]*; do + if [ -d "$card_dir" ]; then + card=$(basename "$card_dir") + echo "# $card 目录内容:" >> "$OUTPUT" + echo "\`\`\`" >> "$OUTPUT" + ls -la "$card_dir" 2>/dev/null >> "$OUTPUT" || true + echo "\`\`\`" >> "$OUTPUT" + fi +done + +# --- Codec 信息 (HDA) --- +section "HDA Codec 信息" +for codec in /proc/asound/card*/codec*; do + if [ -f "$codec" ]; then + echo "# $codec" >> "$OUTPUT" + echo "\`\`\`" >> "$OUTPUT" + cat "$codec" >> "$OUTPUT" 2>/dev/null || echo "(无法读取)" >> "$OUTPUT" + echo "\`\`\`" >> "$OUTPUT" + fi +done +if ! ls /proc/asound/card*/codec* &>/dev/null; then + echo "(未找到 codec 文件)" >> "$OUTPUT" +fi + +# --- ELD 内容 (HDMI 显示器音频能力，对 HDMI 无声排查很重要) --- +section "HDMI ELD 内容" +for eld in /proc/asound/card*/eld*; do + if [ -f "$eld" ]; then + echo "# $eld" >> "$OUTPUT" + echo "\`\`\`" >> "$OUTPUT" + cat "$eld" >> "$OUTPUT" 2>/dev/null || echo "(无法读取，或 ELD 为空/未连接)" >> "$OUTPUT" + echo "\`\`\`" >> "$OUTPUT" + fi +done + +# --- /sys/class/sound 拓扑 --- +section "/sys/class/sound 设备" +if [ -d /sys/class/sound ]; then + run_cmd "ls -la /sys/class/sound" ls -la /sys/class/sound + for card in /sys/class/sound/card[0-9]*; do + if [ -d "$card" ]; then + name=$(basename "$card") + echo "# $name 设备属性:" >> "$OUTPUT" + echo "\`\`\`" >> "$OUTPUT" + for f in id number; do + if [ -f "$card/$f" ]; then + echo "$f: $(cat "$card/$f" 2>/dev/null)" >> "$OUTPUT" + fi + done + echo "\`\`\`" >> "$OUTPUT" + fi + done +fi + +# --- 内核日志中的音频相关信息 --- +section "内核日志 (dmesg) 音频相关" +echo "# dmesg | grep -iE 'snd|hda|audio|codec|hdmi'" >> "$OUTPUT" +echo "# 提示: 若此处显示「需要 root」，请用 sudo 重新运行本脚本以获取完整日志" >> "$OUTPUT" +echo "\`\`\`" >> "$OUTPUT" +dmesg 2>/dev/null | grep -iE 'snd|hda|audio|codec|hdmi' >> "$OUTPUT" || echo "(需要 root 或 dmesg 不可用)" >> "$OUTPUT" +echo "\`\`\`" >> "$OUTPUT" +echo "" >> "$OUTPUT" + +# --- Kaisa HDMI / SOF IPC 基线（辅助采集；用户态排障见 docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md）--- +section "SOF / HDMI / IPC 基线 (dmesg)" +echo "# dmesg | grep -iE 'sof|STREAM_PCM|ipc failed|ipc tx|pcm[0-9]|ASoC|iDisp|hdmi' | tail -120" >> "$OUTPUT" +echo "# 用于对照 SOF/IPC 与 dmesg；建议 sudo 运行本脚本以读全量 dmesg" >> "$OUTPUT" +echo "\`\`\`" >> "$OUTPUT" +dmesg 2>/dev/null | grep -iE 'sof|STREAM_PCM|ipc failed|ipc tx|pcm[0-9]|ASoC|iDisp|hdmi' | tail -120 >> "$OUTPUT" || echo "(需要 root 或 dmesg 不可用)" >> "$OUTPUT" +echo "\`\`\`" >> "$OUTPUT" +echo "" >> "$OUTPUT" + +section "HDMI 试听命令提示（人工执行）" +{ + echo "# 在 aplay -L 中查找 HDMI / DisplayPort 设备后，对每个候选 plughw 试播（Ctrl+C 结束）：" + echo "# speaker-test -D plughw:卡号,设备号 -c 2 -l 1" + echo "# 若 dmesg 已出现 SOF IPC / PARAMS 类错误，用户态换 sink 通常无法单独修复。" +} >> "$OUTPUT" +echo "" >> "$OUTPUT" + +# --- 可选: journalctl 内核日志 (补充 dmesg，含启动后日志) --- +section "journalctl 内核日志 (SOF/音频，可选补充)" +if command -v journalctl &>/dev/null; then + echo "# journalctl -b -k --no-pager | grep -iE 'sof|snd|hda|audio|hdmi' | tail -80" >> "$OUTPUT" + echo "\`\`\`" >> "$OUTPUT" + journalctl -b -k --no-pager 2>/dev/null | grep -iE 'sof|snd|hda|audio|hdmi' | tail -80 >> "$OUTPUT" || echo "(journalctl 需 root 或不可用)" >> "$OUTPUT" + echo "\`\`\`" >> "$OUTPUT" +else + echo "(journalctl 未安装)" >> "$OUTPUT" +fi + +# --- 可选: ACPI NHLT 表 (Coreboot 下常缺失，影响 SOF) --- +section "ACPI NHLT 表" +if [ -d /sys/firmware/acpi/tables ]; then + echo "# ls /sys/firmware/acpi/tables/ | grep -i nhlt" >> "$OUTPUT" + echo "\`\`\`" >> "$OUTPUT" + ls /sys/firmware/acpi/tables/ 2>/dev/null | grep -i nhlt >> "$OUTPUT" || echo "(未找到 NHLT 表，Coreboot 下常见)" >> "$OUTPUT" + echo "\`\`\`" >> "$OUTPUT" +else + echo "(/sys/firmware/acpi/tables 不可用)" >> "$OUTPUT" +fi + +# --- 可选: sof-logger (若已安装，可查看 SOF 固件 trace) --- +section "sof-logger (可选)" +# sudo 下同时检查 SUDO_USER 的 ~/.local/bin（用户可能安装于此） +if [ -n "${SUDO_USER:-}" ]; then + USER_HOME=$(getent passwd "$SUDO_USER" 2>/dev/null | cut -d: -f6) + [ -n "$USER_HOME" ] && [ -d "$USER_HOME/.local/bin" ] && export PATH="$USER_HOME/.local/bin:$PATH" +fi +if command -v sof-logger &>/dev/null; then + echo "# sof-logger -t 2>/dev/null | tail -30 (DMA trace，无需 ldc 文件)" >> "$OUTPUT" + echo "\`\`\`" >> "$OUTPUT" + SOF_LOG=$(timeout 3 sof-logger -t 2>/dev/null | tail -30) || true + if [ -z "$SOF_LOG" ]; then + echo "(sof-logger 执行超时或需 root/debugfs)" >> "$OUTPUT" + elif echo "$SOF_LOG" | grep -q "Usage sof-logger"; then + echo "(sof-logger 输出 Usage：通常表示 debugfs 未挂载或需 root 权限读取 /sys/kernel/debug/sof/)" >> "$OUTPUT" + else + echo "$SOF_LOG" >> "$OUTPUT" + fi + echo "\`\`\`" >> "$OUTPUT" +else + echo "(sof-logger 未安装，可从 thesofproject/sof-bin 或发行版 firmware-sof 相关包安装)" >> "$OUTPUT" +fi + +# --- 音频服务/会话 --- +section "音频服务 (PulseAudio / PipeWire)" +echo "# 提示: sudo 下会以原用户身份调用 pactl/pw-cli，需设置 XDG_RUNTIME_DIR 以连接用户会话" >> "$OUTPUT" +RUN_PACTL() { + if [ -n "${SUDO_USER:-}" ] && [ -d "/run/user/$(id -u "$SUDO_USER" 2>/dev/null)" ]; then + runuser -u "$SUDO_USER" -- env XDG_RUNTIME_DIR="/run/user/$(id -u "$SUDO_USER")" "$@" + else + "$@" + fi +} +if command -v pactl &>/dev/null; then + run_cmd "pactl info" RUN_PACTL pactl info 2>/dev/null || run_cmd "pactl info (直接调用)" pactl info 2>/dev/null || true + run_cmd "pactl list cards (含 HDMI/3.5mm 等 profile)" RUN_PACTL pactl list cards 2>/dev/null || true + run_cmd "pactl list sinks short" RUN_PACTL pactl list sinks short 2>/dev/null || true +fi +if command -v pw-cli &>/dev/null; then + run_cmd "pw-cli list-objects Device" RUN_PACTL pw-cli list-objects Device 2>/dev/null || true +fi +if command -v wpctl &>/dev/null; then + run_cmd "wpctl status (WirePlumber)" RUN_PACTL wpctl status 2>/dev/null || true +fi + +# --- 已加载的音频相关内核模块 --- +section "音频相关内核模块" +run_cmd "lsmod | grep -iE 'snd|hda|sound'" bash -c "lsmod | grep -iE 'snd|hda|sound' || echo '(无匹配)'" + +# --- 混音器状态 --- +section "ALSA 混音器状态" +if command -v amixer &>/dev/null; then + run_cmd "amixer -c 0 contents (或 -c default)" amixer -c 0 contents 2>/dev/null || amixer contents 2>/dev/null || echo "(amixer 执行失败)" >> "$OUTPUT" +fi + +# --- SOF 固件与拓扑 --- +section "SOF 固件 (Intel Sound Open Firmware)" +if [ -f /sys/kernel/debug/sof/fw_version ]; then + echo "# /sys/kernel/debug/sof/fw_version (需 root)" >> "$OUTPUT" + echo "\`\`\`" >> "$OUTPUT" + cat /sys/kernel/debug/sof/fw_version 2>/dev/null >> "$OUTPUT" || echo "(无法读取)" >> "$OUTPUT" + echo "\`\`\`" >> "$OUTPUT" + echo "" >> "$OUTPUT" +fi +if [ -d /lib/firmware/intel ]; then + echo "# ls -la /lib/firmware/intel/ (sof 相关)" >> "$OUTPUT" + echo "\`\`\`" >> "$OUTPUT" + ls -la /lib/firmware/intel/ 2>/dev/null | grep -E 'sof|avs' >> "$OUTPUT" || ls -la /lib/firmware/intel/ >> "$OUTPUT" + echo "\`\`\`" >> "$OUTPUT" + for tplg_dir in /lib/firmware/intel/sof /lib/firmware/intel/sof-tplg; do + if [ -d "$tplg_dir" ]; then + echo "# SOF 拓扑: $tplg_dir" >> "$OUTPUT" + echo "\`\`\`" >> "$OUTPUT" + find "$tplg_dir" -type f -name '*tplg*' 2>/dev/null | head -30 >> "$OUTPUT" + echo "\`\`\`" >> "$OUTPUT" + fi + done +else + echo "(未找到 /lib/firmware/intel)" >> "$OUTPUT" +fi + +# --- 机器/主板识别 (ACPI) --- +section "机器识别 (主板/机型)" +if [ -f /sys/class/dmi/id/board_name ]; then + echo "# DMI 主板信息:" >> "$OUTPUT" + echo "\`\`\`" >> "$OUTPUT" + for f in /sys/class/dmi/id/board_name /sys/class/dmi/id/product_name /sys/class/dmi/id/sys_vendor; do + [ -f "$f" ] && echo "$(basename $f): $(cat "$f" 2>/dev/null)" >> "$OUTPUT" + done + echo "\`\`\`" >> "$OUTPUT" +fi + +log "收集完成，结果已保存到: $OUTPUT" diff --git a/bmad-help.zh-CN.md b/bmad-help.zh-CN.md new file mode 100644 index 0000000000..a523feee97 --- /dev/null +++ b/bmad-help.zh-CN.md @@ -0,0 +1,173 @@ +# BMad 帮助目录（中文版） + +本文档由 [`_bmad/_config/bmad-help.csv`](_bmad/_config/bmad-help.csv) 翻译并整理，便于中文读者检索 **菜单码**、**技能** 与用途。 + +技能调用方式（斜杠命令 / 自然语言等）以本机 `npx bmad-method install` 与 Cursor 集成为准。 + +## 表列说明 + +| 列 | 含义 | +| --- | --- | +| **码** | 菜单快捷码（不同模块下可能重复，以技能名列区分） | +| **显示名称** | CSV 英文显示名（与上游一致，便于对照） | +| **技能** | 技能标识 / 工作流名 | +| **说明** | 对「sequence」列的中文释义 | +| **阶段** | 工作流阶段或触发时机（`anytime` 等为随时） | +| **前置** | 建议先完成的技能或条件（CSV 中错位字段已尽量还原） | +| **必选** | 是否后期阶段强制项（`true` / `false`） | +| **产出** | 主要输出位置或产物类型（保留英文路径占位符） | + +--- + +## BMad 构建器 + +| 码 | 显示名称 | 技能 | 说明 | 阶段 | 前置 | 必选 | 产出 | +| --- | --- | --- | --- | --- | --- | --- | --- | +| BA | Build an Agent | `bmad-agent-builder` | 通过对话式梳理，创建、编辑或重建 Agent 技能。 | 随时 | bmad-agent-builder:quality-analysis | false | bmad_builder_output_folder / agent skill | +| AA | Analyze an Agent | `bmad-agent-builder` | 对既有 Agent 做质量分析：结构、内聚、提示词工艺与改进空间。 | 随时 | — | false | bmad_builder_reports / quality report | +| SB | Setup Builder Module | `bmad-bmb-setup` | 安装或更新 BMad Builder 模块配置与帮助条目。 | 随时 | — | false | {project-root}/_bmad / config.yaml and config.user.yaml | +| IM | Ideate Module | `bmad-module-builder` | 头脑风暴并规划 BMad 模块：创意、架构与构建计划。 | 随时 | bmad-module-builder:create-module | false | bmad_builder_reports / module plan | +| CM | Create Module | `bmad-module-builder` | 将模块基础设施脚手架化为可安装的 BMad 模块技能。 | 随时 | — | false | bmad_builder_output_folder / setup skill | +| VM | Validate Module | `bmad-module-builder` | 检查模块结构是否完整、准确，且能力均已正确注册。 | 随时 | — | false | bmad_builder_reports / validation report | +| BW | Build a Workflow | `bmad-workflow-builder` | 创建、编辑或重建工作流或工具型技能。 | 随时 | bmad-workflow-builder:quality-analysis | false | bmad_builder_output_folder / workflow skill | +| AW | Analyze a Workflow | `bmad-workflow-builder` | 对既有工作流/技能做质量分析：结构、效率与改进空间。 | 随时 | — | false | bmad_builder_reports / quality report | +| CW | Convert a Skill | `bmad-workflow-builder` | 将任意技能转换为符合 BMad 的成果导向形态，并生成前后对比 HTML 报告。 | 随时 | — | false | bmad_builder_reports / converted skill + comparison report | + +## BMad 方法 + +| 码 | 显示名称 | 技能 | 说明 | 阶段 | 前置 | 必选 | 产出 | +| --- | --- | --- | --- | --- | --- | --- | --- | +| WD | Write Document | `bmad-agent-tech-writer` | 详细描述需求，由代理按文档最佳实践撰写；可多轮对话并子流程做调研/审阅。 | 随时 | — | false | project-knowledge / document | +| US | Update Standards | `bmad-agent-tech-writer` | 若发现文档惯例缺失，把你的偏好写入代理记忆中的 documentation-standards.md。 | 随时 | — | false | _bmad/_memory/tech-writer-sidecar / standards | +| MG | Mermaid Generate | `bmad-agent-tech-writer` | 根据描述生成 Mermaid 图；未指定类型时会建议合适的图类。 | 随时 | — | false | planning_artifacts / mermaid diagram | +| VD | Validate Document | `bmad-agent-tech-writer` | 对照文档规范与最佳实践审查指定文档，按优先级给出可执行的改进建议。 | 随时 | — | false | planning_artifacts / validation report | +| EC | Explain Concept | `bmad-agent-tech-writer` | 为复杂概念撰写清晰技术说明，附示例与图示。 | 随时 | — | false | project_knowledge / explanation | +| BP | Brainstorm Project | `bmad-brainstorming` | 专家引导，使用一种或多种技法进行项目头脑风暴。 | 阶段 1 · 分析 | — | false | planning_artifacts / brainstorming session | +| IR | Check Implementation Readiness | `bmad-check-implementation-readiness` | 确保 PRD、UX、架构与 Epic/Story 彼此对齐。 | 阶段 3 · 方案设计 | bmad-create-epics-and-stories | true | planning_artifacts / readiness report | +| CR | Code Review | `bmad-code-review` | 故事循环：若有问题退回 DS；通过后进入下一 CS，或 Epic 完成时走 ER。 | 阶段 4 · 实现 | bmad-dev-story | false | — | +| CC | Correct Course | `bmad-correct-course` | 在重大变更时纠偏：可能建议重来、更新 PRD、重做架构/冲刺规划或修正 Epic 与 Story。 | 随时 | — | false | planning_artifacts / change proposal | +| CA | Create Architecture | `bmad-create-architecture` | 引导式产出技术决策文档（架构）。 | 阶段 3 · 方案设计 | — | true | planning_artifacts / architecture | +| CE | Create Epics and Stories | `bmad-create-epics-and-stories` | 在架构文档（CA）之后创建 Epic 与用户故事。 | 阶段 3 · 方案设计 | bmad-create-architecture | true | planning_artifacts / epics and stories | +| CP | Create PRD | `bmad-create-prd` | 专家引导完成产品需求文档（PRD）。 | 阶段 2 · 规划 | — | true | planning_artifacts / prd | +| CS | Create Story | `bmad-create-story` | 故事循环起点：准备冲刺计划中「下一个」待做 Story，或指定 Epic/Story。 | 阶段 4 · 实现 | bmad-create-story:validate | true | implementation_artifacts / story | +| VS | Validate Story | `bmad-create-story` | 在开发开始前校验 Story 是否就绪、完整。 | 阶段 4 · 实现 | bmad-dev-story | false | implementation_artifacts / story validation report | +| CU | Create UX | `bmad-create-ux-design` | 落实 UX 方案；若项目以 UI 为主，强烈建议使用。 | 阶段 2 · 规划 | bmad-create-prd | false | planning_artifacts / ux design | +| DS | Dev Story | `bmad-dev-story` | 故事循环：执行 Story 实现与测试，经 CR，如需修复回到 DS。 | 阶段 4 · 实现 | bmad-create-story:validate | true | — | +| DP | Document Project | `bmad-document-project` | 分析现有项目并产出可用文档。 | 随时 | — | false | project-knowledge / * | +| DR | Domain Research | `bmad-domain-research` | 行业领域深度研究、专业术语与知识沉淀。 | 阶段 1 · 分析 | — | false | planning_artifacts · project_knowledge / research documents | +| EP | Edit PRD | `bmad-edit-prd` | 在通过 PRD 校验流程后，编辑并改进指定路径的 PRD。 | 阶段 2 · 规划 | bmad-validate-prd | false | planning_artifacts / updated prd | +| GPC | Generate Project Context | `bmad-generate-project-context` | 扫描代码库生成精简、面向 LLM 的 project-context.md；棕地项目尤其重要。 | 随时 | — | false | output_folder / project context | +| MR | Market Research | `bmad-market-research` | 市场、竞品、客户需求与趋势分析。 | 阶段 1 · 分析 | — | false | planning_artifacts · project-knowledge / research documents | +| CB | Create Brief | `bmad-product-brief` | 引导式厘清产品创意与核心价值。 | 阶段 1 · 分析 | — | false | planning_artifacts / product brief | +| QA | QA Automation Test | `bmad-qa-generate-e2e-tests` | 为已实现代码生成自动化 API 与 E2E 测试；非代码评审或 Story 校验（请用 CR）。 | 阶段 4 · 实现 | bmad-dev-story | false | implementation_artifacts / test suite | +| QQ | Quick Dev | `bmad-quick-dev` | 统一「意图进、代码出」：澄清、实现、审阅与交付展示。 | 随时 | — | false | implementation_artifacts / spec and project implementation | +| ER | Retrospective | `bmad-retrospective` | 可选：在 Epic 结束时回顾成果与经验，规划下一 Epic；重大问题考虑走 CC。 | 阶段 4 · 实现 | bmad-code-review | false | implementation_artifacts / retrospective | +| SP | Sprint Planning | `bmad-sprint-planning` | 启动实现阶段：生成实现代理将按序执行的冲刺计划。 | 阶段 4 · 实现 | — | true | implementation_artifacts / sprint status | +| SS | Sprint Status | `bmad-sprint-status` | 随时总结 Sprint 状态并路由到下一工作流。 | 阶段 4 · 实现 | bmad-sprint-planning | false | — | +| TR | Technical Research | `bmad-technical-research` | 技术可行性、架构选项与实现路径研究。 | 阶段 1 · 分析 | — | false | planning_artifacts · project_knowledge / research documents | +| VP | Validate PRD | `bmad-validate-prd` | 在创建 PRD（CP）之后校验 PRD 质量。 | 阶段 2 · 规划 | bmad-create-prd | false | planning_artifacts / prd validation report | + +## 核心 + +| 码 | 显示名称 | 技能 | 说明 | 阶段 | 前置 | 必选 | 产出 | +| --- | --- | --- | --- | --- | --- | --- | --- | +| BSP | Brainstorming | `bmad-brainstorming` | 在创意早期或思路卡住时做头脑风暴。 | 随时 | — | false | {output_folder}/brainstorming / brainstorming session | +| DG | Distillator | `bmad-distillator` | 生成节省 token 的蒸馏文，保留供下游 LLM 使用的关键信息。 | — | — | adjacent to source document or specified output_path | distillate markdown file(s) | +| EP | Editorial Review - Prose | `bmad-editorial-review-prose` | 成稿后润色正文表达。 | — | — | report located with target document | three-column markdown table with suggested fixes | +| ES | Editorial Review - Structure | `bmad-editorial-review-structure` | 当文档由多段子流程拼成或结构需加强时，做结构性编辑审阅。 | — | — | report located with target document | — | +| BH | BMad Help | `bmad-help` | 判断当前所处 BMad 流程位置并回答问题；推荐下一步技能与调用方式。 | 随时 | — | false | — | +| ID | Index Docs | `bmad-index-docs` | 在不加载全部文件的前提下为目录生成/更新索引，便于掌握文档地图。 | 随时 | — | false | — | +| PM | Party Mode | `bmad-party-mode` | 编排多代理/多视角讨论与协作。 | 随时 | — | false | — | +| AR | Adversarial Review | `bmad-review-adversarial-general` | 在定稿前做对抗性质量审查；其他模块的代码审也可自动调用，亦适用于文档。 | — | — | | — | +| ECH | Edge Case Hunter Review | `bmad-review-edge-case-hunter` | 与对抗审搭配，从边界场景做正交补充，重方法而非「挑刺态度」。 | — | — | | — | +| SD | Shard Document | `bmad-shard-doc` | 当单份文档过大（常为 >500 行）时拆分为可管理片段。 | — | — | | — | + +## 创意智能套件（CIS） + +| 码 | 显示名称 | 技能 | 说明 | 阶段 | 前置 | 必选 | 产出 | +| --- | --- | --- | --- | --- | --- | --- | --- | +| BS | Brainstorming | `bmad-brainstorming` | 用一种或多种技法主持头脑风暴会话。 | 随时 | — | false | output_folder / brainstorming session results | +| DT | Design Thinking | `bmad-cis-design-thinking` | 以同理心驱动的人本设计流程指导。 | 随时 | — | false | output_folder / design thinking | +| IS | Innovation Strategy | `bmad-cis-innovation-strategy` | 识别颠覆机会并设计商业模式创新。 | 随时 | — | false | output_folder / innovation strategy | +| PS | Problem Solving | `bmad-cis-problem-solving` | 运用系统化问题解决方法拆解复杂挑战。 | 随时 | — | false | output_folder / problem solution | +| ST | Storytelling | `bmad-cis-storytelling` | 用成熟叙事框架与技巧撰写故事/叙述。 | 随时 | — | false | output_folder / narrative/story | + +## 游戏开发工作室（GDS） + +| 码 | 显示名称 | 技能 | 说明 | 阶段 | 前置 | 必选 | 产出 | +| --- | --- | --- | --- | --- | --- | --- | --- | +| QP | Quick Prototype | `bmad-gds-quick-prototype` | 快速游戏原型，验证机制与创意。 | 随时 | — | false | — | +| BG | Brainstorm Game | `gds-brainstorm-game` | 在游戏语境下主持头脑风暴。 | 前期制作 | — | false | output_folder / brainstorming session | +| IR | Check Implementation Readiness | `gds-check-implementation-readiness` | 在投产前确保 GDD、UX、架构与 Epic/Story 对齐。 | 技术 | gds-create-epics-and-stories | true | planning_artifacts / readiness report | +| CR | Code Review | `gds-code-review` | 对标记为「待评审」的 Story 做干净上下文的 QA 代码审查。 | 制作 | gds-dev-story | false | — | +| CC | Correct Course | `gds-correct-course` | 游戏开发冲刺偏离路线时进行纠偏。 | 随时 | — | false | planning_artifacts / change proposal | +| CE | Create Epics and Stories | `gds-create-epics-and-stories` | 依据 GDD 需求创建 Epic 与 Story 列表，作为开发规格驱动。 | 技术 | gds-game-architecture | true | planning_artifacts / epics and stories | +| GB | Game Brief | `gds-create-game-brief` | 交互式游戏简报，引导用户明确游戏愿景。 | 前期制作 | — | false | output_folder / game brief | +| GDD | Game Design Document | `gds-create-gdd` | 撰写游戏设计文档 GDD：机制、系统、进度与实现指引。 | 设计 | — | false | planning_artifacts / gdd | +| ND | Narrative Design | `gds-create-narrative` | 为剧情向游戏撰写叙事文档：结构、人物弧与世界观。 | 设计 | gds-create-gdd | false | planning_artifacts / narrative design | +| CP | Create PRD | `gds-create-prd` | 从 GDD 或从零撰写 PRD，供 bmad-assist 等外部工具使用。 | 设计 | gds-create-gdd | false | planning_artifacts / prd | +| CS | Create Story | `gds-create-story` | 为开发代理准备上下文充分的 Story。 | 制作 | gds-sprint-planning | true | implementation_artifacts / story | +| CU | Create UX Design | `gds-create-ux-design` | 落实游戏 UX/UI；若 UI 是核心，强烈建议使用。 | 设计 | gds-create-gdd | false | planning_artifacts / ux design | +| DS | Dev Story | `gds-dev-story` | 执行 Dev Story：按任务与测试实现。 | 制作 | gds-create-story | true | — | +| DP | Document Project | `gds-document-project` | 分析现有游戏项目并产出文档。 | 随时 | — | false | project_knowledge / project documentation | +| DR | Domain Research | `gds-domain-research` | 游戏产业领域深度研究与术语沉淀。 | 前期制作 | — | false | planning_artifacts / research documents | +| ES | E2E Scaffold | `gds-e2e-scaffold` | 搭建 E2E 测试基础设施脚手架。 | 游戏测试 | gds-test-automate | false | — | +| EP | Edit PRD | `gds-edit-prd` | 改进并增强既有 PRD。 | 设计 | gds-validate-prd | false | planning_artifacts / updated prd | +| GA | Game Architecture | `gds-game-architecture` | 产出可伸缩游戏架构：引擎、系统、网络与技术设计。 | 技术 | — | true | planning_artifacts / game architecture | +| PC | Project Context | `gds-generate-project-context` | 生成适配所选智能体工具一致性的 project-context.md。 | 技术 | — | false | — | +| MR | Market Research | `gds-market-research` | 游戏市场、竞品与玩家需求分析。 | 前期制作 | — | false | planning_artifacts / research documents | +| PT | Performance Test | `gds-performance-test` | 设计性能测试策略。 | 游戏测试 | gds-playtest-plan | false | planning_artifacts / performance strategy | +| PP | Playtest Plan | `gds-playtest-plan` | 撰写结构化试玩/测试计划。 | 游戏测试 | gds-e2e-scaffold | false | planning_artifacts / playtest plan | +| QD | Quick Dev | `gds-quick-dev` | 兼顾游戏特性的灵活开发流程。 | 随时 | — | false | — | +| QQ | Quick Dev New Preview | `gds-quick-dev-new-preview` | 实验性一体化快捷流：单工作流内完成澄清、计划、实现、审阅与展示。 | 随时 | — | false | — | +| TS | Quick Spec | `gds-quick-spec` | 小需求、小改动、简单应用/工具，无需冗长规划。 | 随时 | — | false | planning_artifacts / tech spec | +| ER | Retrospective | `gds-retrospective` | 在游戏开发 Epic 完成后组织团队回顾。 | 制作 | gds-code-review | false | implementation_artifacts / retrospective | +| SP | Sprint Planning | `gds-sprint-planning` | 由 Epic 文件生成或更新 sprint-status.yaml。 | 制作 | — | true | implementation_artifacts / sprint status | +| SS | Sprint Status | `gds-sprint-status` | 查看冲刺进度、暴露风险并给出下一步行动建议。 | 制作 | gds-sprint-planning | false | — | +| TR | Technical Research | `gds-technical-research` | 游戏引擎选项与实现路径的技术可行性研究。 | 前期制作 | — | false | planning_artifacts / research documents | +| TA | Test Automate | `gds-test-automate` | 生成自动化游戏测试。 | 游戏测试 | — | false | — | +| TD | Test Design | `gds-test-design` | 设计覆盖流程与质量要求的游戏测试场景。 | 技术 | gds-test-framework | false | planning_artifacts / test design | +| TF | Test Framework | `gds-test-framework` | 为 Unity / Unreal / Godot 等项目初始化游戏测试框架架构。 | 技术 | — | false | — | +| TR | Test Review | `gds-test-review` | 评审测试质量与覆盖。 | 游戏测试 | gds-performance-test | false | — | +| VP | Validate PRD | `gds-validate-prd` | 按外部工具兼容标准校验 PRD。 | 设计 | gds-create-prd | false | planning_artifacts / prd validation report | + +## 测试架构企业版（TEA） + +| 码 | 显示名称 | 技能 | 说明 | 阶段 | 前置 | 必选 | 产出 | +| --- | --- | --- | --- | --- | --- | --- | --- | +| TMT | Teach Me Testing | `bmad-teach-me-testing` | TEA 学院：通过 7 次课讲授测试基础（含进度与证书相关产出）。 | 阶段 0 · 学习 | — | false | test_artifacts / progress file · session notes · certificate | +| AT | ATDD | `bmad-testarch-atdd` | 生成失败用例（TDD 红灯阶段）。 | 阶段 4 · 实现 | — | false | test_artifacts / atdd tests | +| TA | Test Automation | `bmad-testarch-automate` | 扩展自动化测试覆盖。 | 阶段 4 · 实现 | bmad-testarch-atdd | false | test_artifacts / test suite | +| CI | CI Setup | `bmad-testarch-ci` | 配置 CI/CD 质量流水线。 | 阶段 3 · 方案设计 | bmad-testarch-framework | false | test_artifacts / ci config | +| TF | Test Framework | `bmad-testarch-framework` | 初始化生产级测试框架脚手架。 | 阶段 3 · 方案设计 | bmad-testarch-test-design | false | test_artifacts / framework scaffold | +| NR | NFR Assessment | `bmad-testarch-nfr` | 非功能需求（NFR）评估。 | 阶段 4 · 实现 | bmad-testarch-automate | false | test_artifacts / nfr report | +| TD | Test Design | `bmad-testarch-test-design` | 基于风险的测试规划。 | 阶段 3 · 方案设计 | — | false | test_artifacts / test design document | +| RV | Test Review | `bmad-testarch-test-review` | 质量审计（0–100 分制）。 | 阶段 4 · 实现 | bmad-testarch-automate | false | test_artifacts / review report | +| TR | Traceability | `bmad-testarch-trace` | 覆盖度可追溯与质量门禁决策。 | 阶段 4 · 实现 | bmad-testarch-test-review | false | test_artifacts / traceability matrix · gate decision | + +## 网页设计工作室（WDS） + +| 码 | 显示名称 | 技能 | 说明 | 阶段 | 前置 | 必选 | 产出 | +| --- | --- | --- | --- | --- | --- | --- | --- | +| AD | Agentic Development | `bmad-wds-agentic-development` | 带设计日志与浏览器验证的迭代「构建—验证」循环。 | WDS · 构建/验证 | bmad-wds-design-delivery | false | _progress/agent-experiences / experience-documents | +| AS | Alignment & Signoff | `bmad-wds-alignment` | 干系人共识 pitch 与服务协议；若做自有产品可跳过。 | WDS · 宣讲/对齐 | — | false | design_artifacts/A-Product-Brief / pitch service-agreement signoff | +| CS | Conceptual Sketching | `bmad-wds-conceptual-sketching` | 详细规格前的快速视觉草图探索；直接场景可跳过。 | WDS · 设计 | bmad-wds-outline-scenarios | false | design_artifacts/C-UX-Scenarios / sketches | +| SP | Conceptual Specifications | `bmad-wds-conceptual-specs` | 逐页逐元素记录设计决策，开发可直接据此实现。 | WDS · 设计 | bmad-wds-outline-scenarios | true | design_artifacts/C-UX-Scenarios / page-specs scenario-specs | +| DD | Design Delivery | `bmad-wds-design-delivery` | 校验规格完整并打包为 DD yaml，供开发交接。 | WDS · 设计 | bmad-wds-conceptual-specs | true | design_artifacts/E-PRD/Design-Deliveries / delivery-package acceptance-criteria | +| DS | Design System | `bmad-wds-design-system` | 管理组件库与设计令牌；设计系统模式为「无」时跳过。 | WDS · 设计 | bmad-wds-functional-components | false | design_artifacts/D-Design-System / components/ design-tokens.md | +| FREYA | Wake Freya | `bmad-wds-freya` | 第 3–4 阶段 UX 设计师代理 Freya：检查前置条件并给出下一步。 | WDS · 唤醒代理 | — | false | — | +| FI | Functional Components | `bmad-wds-functional-components` | 从规格抽取可复用模式为组件定义；无设计系统时跳过。 | WDS · 设计 | bmad-wds-conceptual-specs | false | design_artifacts/C-UX-Scenarios / component-candidates | +| IDUN | Wake Idun | `bmad-wds-idun` | 治理代理 Idun：访谈组织以配置 Agent Space 与权限模型。 | WDS · 唤醒代理 | — | false | — | +| OS | Outline Scenarios | `bmad-wds-outline-scenarios` | 以「人设 + 目标 + 结果」定义用户旅程，并与触发图驱动力关联。 | WDS · 设计 | bmad-wds-trigger-mapping | true | design_artifacts/C-UX-Scenarios / scenario-overview.md | +| PR | Platform Requirements | `bmad-wds-platform-requirements` | 平台、设备、集成与约束等技术边界；简单落地页可跳过。 | WDS · 策略 | bmad-wds-project-brief | false | design_artifacts/A-Product-Brief / platform-requirements.md | +| PE | Product Evolution | `bmad-wds-product-evolution` | 持续改进：反馈 → 触发图 → 规格 → 代码 → 验证。 | WDS · 构建/验证 | bmad-wds-usability-testing | false | design_artifacts / updated-artifacts | +| PB | Project Brief | `bmad-wds-project-brief` | 定义产品愿景、定位与成功标准，设计决策应可追溯至此。 | WDS · 策略 | — | true | design_artifacts/A-Product-Brief / project-brief.md | +| SAGA | Wake Saga | `bmad-wds-saga` | 第 1–2 阶段战略分析师代理 Saga：扫描仓库并建议下一步。 | WDS · 唤醒代理 | — | false | — | +| SB | Storyboarding | `bmad-wds-storyboarding` | 跨界面串联用户旅程与入口、过渡、异常路径；简单场景可跳过。 | WDS · 设计 | bmad-wds-outline-scenarios | false | design_artifacts/C-UX-Scenarios / storyboards | +| TM | Trigger Mapping | `bmad-wds-trigger-mapping` | 将业务目标映射到用户心理：人设、功能与驱动力打分。 | WDS · 策略 | bmad-wds-project-brief | true | design_artifacts/B-Trigger-Map / trigger-map.md personas/ feature-impact-analysis.md | +| AT | Acceptance Testing | `bmad-wds-usability-testing` | 在真实用户环境中做可用性测试与回顾式出声思考。 | WDS · 构建/验证 | bmad-wds-agentic-development | false | design_artifacts/F-Testing / test-results findings | +| VD | Visual Design | `bmad-wds-visual-design` | 将规格转为带样式的 HTML 原型，可与 Figma 往返。 | WDS · 设计 | bmad-wds-conceptual-specs | false | design_artifacts/C-UX-Scenarios / html-prototypes visual-designs | + +--- + +*生成脚本：[`_bmad/scripts/render_bmad_help_zh_cn.py`](_bmad/scripts/render_bmad_help_zh_cn.py)（修改译文表后重新运行以更新本文档。）* diff --git a/debian/changelog b/debian/changelog new file mode 100644 index 0000000000..e2018a5028 --- /dev/null +++ b/debian/changelog @@ -0,0 +1,64 @@ +kaisa-hdmi-pipewire-fix (0.3.0) unstable; urgency=medium + + * Remove /usr/bin helper scripts and user systemd units from the package; + delivery is UCM2 + WirePlumber conf only until automation is validated. + + -- chromebox_10th_audio_driver Sun, 06 Apr 2026 22:00:00 +0800 + +kaisa-hdmi-pipewire-fix (0.2.7) unstable; urgency=medium + + * postinst: systemctl disable --global for kaisa user units (clears stale global enables on upgrade). + + -- chromebox_10th_audio_driver Sun, 05 Apr 2026 12:00:00 +0800 + +kaisa-hdmi-pipewire-fix (0.2.6) unstable; urgency=medium + + * user preset: disable kaisa-hdmi-auto-default-sink.service by default (opt-in only). + + -- chromebox_10th_audio_driver Sat, 04 Apr 2026 23:30:00 +0800 + +kaisa-hdmi-pipewire-fix (0.2.5) unstable; urgency=medium + + * kaisa-hdmi-auto-default-sink-watch: skip pcm when aplay reports 0 playback subdevices (avoids set_hw_params EIO). + + -- chromebox_10th_audio_driver Sat, 04 Apr 2026 22:00:00 +0800 + +kaisa-hdmi-pipewire-fix (0.2.4) unstable; urgency=medium + + * kaisa-hdmi-auto-default-sink-watch: poll HDMI Jack, set-default-sink + IEC958. + * user systemd preset: enable auto-sink, disable kaisa-hdmi-iec958-pipewire (pro-audio oneshot). + + -- chromebox_10th_audio_driver Sat, 04 Apr 2026 20:00:00 +0800 + +kaisa-hdmi-pipewire-fix (0.2.3) unstable; urgency=medium + + * kaisa-restore-iec958-ucm: match HiFi__hw_sofrt5682_N__ sink names (Kaisa pactl). + * next.md OPERATION: troubleshooting when IEC958 on but silent (wpctl, HDMI port). + + -- chromebox_10th_audio_driver Mon, 07 Apr 2026 12:00:00 +0800 + +kaisa-hdmi-pipewire-fix (0.2.2) unstable; urgency=medium + + * kaisa-restore-iec958-ucm: hdmi/displayport sink heuristics; reject pcm 0/1 with hint. + * next.md / OPERATION / postinst: apt upgrade may reinstall 50-kaisa; diagnostic block. + + -- chromebox_10th_audio_driver Sun, 06 Apr 2026 22:00:00 +0800 + +kaisa-hdmi-pipewire-fix (0.2.1) unstable; urgency=medium + + * Add kaisa-restore-iec958-ucm: open IEC958 without forcing pro-audio (UCM/HiFi). + + -- chromebox_10th_audio_driver Sun, 06 Apr 2026 23:59:00 +0800 + +kaisa-hdmi-pipewire-fix (0.2.0) unstable; urgency=medium + + * Ship reference UCM2 overlay (conf.d/sof-rt5682, GoogleKaisa/sof-rt5682). + * Depends on alsa-ucm-conf; document UCM vs pro-audio mutex in postinst/README. + + -- chromebox_10th_audio_driver Sun, 06 Apr 2026 22:30:00 +0800 + +kaisa-hdmi-pipewire-fix (0.1.0) unstable; urgency=medium + + * Initial packaging: system WirePlumber drop-in, restore script, user systemd unit. + + -- chromebox_10th_audio_driver Sat, 04 Apr 2026 12:00:00 +0800 diff --git a/debian/control b/debian/control new file mode 100644 index 0000000000..3a595d3d3d --- /dev/null +++ b/debian/control @@ -0,0 +1,25 @@ +Source: kaisa-hdmi-pipewire-fix +Section: sound +Priority: optional +Maintainer: chromebox_10th_audio_driver +Build-Depends: debhelper-compat (= 13) +Rules-Requires-Root: no +Standards-Version: 4.6.2 + +Package: kaisa-hdmi-pipewire-fix +Architecture: all +Depends: wireplumber, alsa-utils, alsa-ucm-conf, ${misc:Depends} +Recommends: pipewire-pulse | pipewire-pulseaudio +Suggests: pulseaudio-utils +Description: Google Kaisa HDMI audio fix (PipeWire / sof-rt5682, UCM2) + Installs UCM2 overlay under /usr/share/alsa/ucm2/ (conf.d/sof-rt5682, + GoogleKaisa/sof-rt5682) for Jack-driven HDMI routes plus IEC958 sequences, + and a system-wide WirePlumber drop-in (pro-audio profile, HDMI sink + priorities). Does not ship helper binaries or user systemd units yet — + use manual pactl/amixer steps in OPERATION until automated restore is ready. + UCM-first and pro-audio WirePlumber are mutually exclusive — see + /usr/share/doc/kaisa-hdmi-pipewire-fix/README.md and OPERATION. + . + PCI path in the WirePlumber fragment targets BDF 0000:00:1f.3; edit under + /etc/wireplumber/ if needed. See OPERATION_PipeWire_Kaisa_HDMI.md.gz in + /usr/share/doc/. diff --git a/debian/kaisa-hdmi-pipewire-fix.postinst b/debian/kaisa-hdmi-pipewire-fix.postinst new file mode 100755 index 0000000000..a00a843771 --- /dev/null +++ b/debian/kaisa-hdmi-pipewire-fix.postinst @@ -0,0 +1,17 @@ +#!/bin/sh +set -e +case "$1" in +configure) + echo "kaisa-hdmi-pipewire-fix: UCM2 已安装至 /usr/share/alsa/ucm2/（sof-rt5682 + GoogleKaisa）" + echo "kaisa-hdmi-pipewire-fix: WirePlumber 片段: /etc/wireplumber/wireplumber.conf.d/" + echo " 重要：UCM（产品目标：无 Jack 不误导）与强制 pro-audio 片段二选一。" + echo " 若优先 UCM：请移走 50-kaisa-sof-rt5682-hdmi.conf 后执行:" + echo " systemctl --user restart wireplumber pipewire pipewire-pulse" + echo " 注意: apt upgrade 本包后若该文件曾被删/改名, 可能被再次装入; UCM 用户请再移走。" + echo " 否则保留 pro-audio 过渡时，可暂叠 UCM 但行为以 OPERATION 互斥说明为准。" + echo " 详见: /usr/share/doc/kaisa-hdmi-pipewire-fix/README.md.gz" + echo " 本包当前仅含 UCM2 + WirePlumber 片段；自动 restore / IEC958 / Jack 轮询工具尚未随 deb 提供，见 OPERATION 手顺。" + ;; +esac +#DEBHELPER# +exit 0 diff --git a/debian/kaisa-hdmi-pipewire-fix/DEBIAN/control b/debian/kaisa-hdmi-pipewire-fix/DEBIAN/control new file mode 100644 index 0000000000..ec3afd6e57 --- /dev/null +++ b/debian/kaisa-hdmi-pipewire-fix/DEBIAN/control @@ -0,0 +1,21 @@ +Package: kaisa-hdmi-pipewire-fix +Version: 0.3.0 +Architecture: all +Maintainer: chromebox_10th_audio_driver +Installed-Size: 56 +Depends: wireplumber, alsa-utils, alsa-ucm-conf, init-system-helpers (>= 1.52) +Recommends: pipewire-pulse | pipewire-pulseaudio +Section: sound +Priority: optional +Description: Google Kaisa HDMI audio fix (PipeWire / sof-rt5682, UCM2) + Installs UCM2 overlay under /usr/share/alsa/ucm2/ (conf.d/sof-rt5682, + GoogleKaisa/sof-rt5682) for Jack-driven HDMI routes plus IEC958 sequences, + and a system-wide WirePlumber drop-in (pro-audio profile, HDMI sink + priorities). Does not ship helper binaries or user systemd units yet — + use manual pactl/amixer steps in OPERATION until automated restore is ready. + UCM-first and pro-audio WirePlumber are mutually exclusive — see + /usr/share/doc/kaisa-hdmi-pipewire-fix/README.md and OPERATION. + . + PCI path in the WirePlumber fragment targets BDF 0000:00:1f.3; edit under + /etc/wireplumber/ if needed. See OPERATION_PipeWire_Kaisa_HDMI.md.gz in + /usr/share/doc/. diff --git a/debian/kaisa-hdmi-pipewire-fix/DEBIAN/postinst b/debian/kaisa-hdmi-pipewire-fix/DEBIAN/postinst new file mode 100755 index 0000000000..a00a843771 --- /dev/null +++ b/debian/kaisa-hdmi-pipewire-fix/DEBIAN/postinst @@ -0,0 +1,17 @@ +#!/bin/sh +set -e +case "$1" in +configure) + echo "kaisa-hdmi-pipewire-fix: UCM2 已安装至 /usr/share/alsa/ucm2/（sof-rt5682 + GoogleKaisa）" + echo "kaisa-hdmi-pipewire-fix: WirePlumber 片段: /etc/wireplumber/wireplumber.conf.d/" + echo " 重要：UCM（产品目标：无 Jack 不误导）与强制 pro-audio 片段二选一。" + echo " 若优先 UCM：请移走 50-kaisa-sof-rt5682-hdmi.conf 后执行:" + echo " systemctl --user restart wireplumber pipewire pipewire-pulse" + echo " 注意: apt upgrade 本包后若该文件曾被删/改名, 可能被再次装入; UCM 用户请再移走。" + echo " 否则保留 pro-audio 过渡时，可暂叠 UCM 但行为以 OPERATION 互斥说明为准。" + echo " 详见: /usr/share/doc/kaisa-hdmi-pipewire-fix/README.md.gz" + echo " 本包当前仅含 UCM2 + WirePlumber 片段；自动 restore / IEC958 / Jack 轮询工具尚未随 deb 提供，见 OPERATION 手顺。" + ;; +esac +#DEBHELPER# +exit 0 diff --git a/debian/kaisa-hdmi-pipewire-fix/DEBIAN/postrm b/debian/kaisa-hdmi-pipewire-fix/DEBIAN/postrm new file mode 100755 index 0000000000..55ea131a4c --- /dev/null +++ b/debian/kaisa-hdmi-pipewire-fix/DEBIAN/postrm @@ -0,0 +1,4 @@ +#!/bin/sh +set -e +#DEBHELPER# +exit 0 diff --git a/debian/kaisa-hdmi-pipewire-fix/usr/share/doc/kaisa-hdmi-pipewire-fix/README.md b/debian/kaisa-hdmi-pipewire-fix/usr/share/doc/kaisa-hdmi-pipewire-fix/README.md new file mode 100644 index 0000000000..a9713b56e2 --- /dev/null +++ b/debian/kaisa-hdmi-pipewire-fix/usr/share/doc/kaisa-hdmi-pipewire-fix/README.md @@ -0,0 +1,49 @@ +# Kaisa UCM2 overlay（`sof-rt5682`） + +本目录为 **alsa-ucm-conf** 风格的 **UCM2** 草稿，目标：**Jack off 时 HDMI 路由对 ACP/桌面不表现为可随意可用的输出**（与强制 **`pro-audio`** 的 WirePlumber 策略不同，见 [docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md](../../../../../../docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md)「UCM 模式 vs pro-audio 模式」）。 + +## 布局 + +| 路径（相对 `ucm2/` 根） | 说明 | +|-------------------------|------| +| `conf.d/sof-rt5682/sof-rt5682.conf` | 卡入口，匹配 ALSA **card name** `sof-rt5682` | +| `GoogleKaisa/sof-rt5682/HiFi.conf` | HiFi：`Port1` + **HDMI1/2/3**，**JackControl** + **`IEC958',N`** | + +上游 **alsa-ucm-conf** 若日后增加同名 `conf.d/sof-rt5682/`，与本仓库 **deb 同时安装会冲突** — 优先 **合并上游** 或 **改名/拆包**（与 [OPERATION](../../../../../../docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md) 中 UCM / pro-audio 互斥说明一致）。 + +## 手工安装（调试） + +```bash +sudo cp -a reference/ucm2/conf.d/sof-rt5682 /usr/share/alsa/ucm2/conf.d/ +sudo cp -a reference/ucm2/GoogleKaisa /usr/share/alsa/ucm2/ +sudo alsactl init # 或重登 / 重启 pipewire +systemctl --user restart wireplumber pipewire pipewire-pulse +``` + +## 与 WirePlumber **`50-kaisa-sof-rt5682-hdmi.conf` 的互斥** + +- **UCM 模式（本 overlay）**：依赖 **ACP** 的 profile/端口；**请勿**再使用强制 **`device.profile = pro-audio`** 的片段，否则仍易出现 **多路 `pro-output-*` 常驻**。 +- **过渡 pro-audio 模式**：保留现有 `wireplumber.conf.d` 片段；**不要**同时叠加本 UCM 覆盖（二选一）。 + +## 校验（可选） + +若已安装 **`alsa-utils`**： + +```bash +alsaucm -c sof-rt5682 list _verbs +alsaucm -c sof-rt5682 set _verb HiFi list _devices +``` + +插拔 HDMI 时对照 **`amixer -c0`** 中 **`HDMI/DP,pcm=N` Jack** 与 **`IEC958',N`**。 + +## 实机验收表（勾选） + +| 步骤 | 预期 | +|------|------| +| 仅接模拟 / 不接 HDMI | HDMI 相关输出不对「可用路由」误导（依桌面实现） | +| 接 HDMI，Jack on | 对应 **IEC958** on 后有声 | +| 拔线 Jack off | 该路不应再被选为有效 HDMI 输出 | + +--- + +_控件名以本机 `amixer` 为准；若 `Headphone`/`IEC958` 命名不同，需改 `HiFi.conf` 后重测。_ diff --git a/debian/rules b/debian/rules new file mode 100755 index 0000000000..cbe925d758 --- /dev/null +++ b/debian/rules @@ -0,0 +1,3 @@ +#!/usr/bin/make -f +%: + dh $@ diff --git a/docs/INDEX.md b/docs/INDEX.md new file mode 100644 index 0000000000..41ba4e3247 --- /dev/null +++ b/docs/INDEX.md @@ -0,0 +1,9 @@ +# 文档索引 + +与根 [README.md](../README.md) 相同：**仅**下列为当前维护文档。 + +| 文档 | 说明 | +| ---- | ---- | +| [linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md](linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md) | 主操作文档 | +| [linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md](linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md) | deb 复现与验收 | +| [README.md](README.md) | 本目录说明 | diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000000..bfd1fc2cff --- /dev/null +++ b/docs/README.md @@ -0,0 +1,12 @@ +# `docs/` 说明 + +本目录仅保留 **已实机验证** 的 PipeWire / deb 技术路线： + +| 文档 | 内容 | +| ---- | ---- | +| [linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md](linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md) | WirePlumber、`50-kaisa-sof-rt5682-hdmi.conf`、pro-audio / UCM、deb、基线采集 | +| [linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md](linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md) | deb 安装与手动验收 | + +附属文件：`linux-hdmi/wireplumber/50-kaisa-sof-rt5682-hdmi.conf`、`linux-hdmi/systemd-user/kaisa-hdmi-iec958-pipewire.service`。 + +仓库根 [README.md](../README.md) · 路径表 [REPO_INDEX.md](../REPO_INDEX.md)。 diff --git a/docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md b/docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md new file mode 100644 index 0000000000..593e655416 --- /dev/null +++ b/docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md @@ -0,0 +1,292 @@ +# 操作：Kaisa（sof-rt5682）Ubuntu 上 HDMI 出声与 WirePlumber 固化 + +**适用**：Google **Kaisa**（如 `Google-Kaisa-rev4`）、PipeWire + WirePlumber（Ubuntu 24.04 常见）、声卡为 **`alsa_card.pci-0000_00_1f.3-platform-cml_rt5682_def`**（若 PCI 路径不同需改配置）。 + +--- + +## 路径选择（pro-audio 与 UCM，先选哪条） + +| 目标 | 做法 | +|------|------| +| **先确认 HDMI 能否出声（对照实验）** | **pro-audio**：把 **[`50-kaisa-sof-rt5682-hdmi.conf`](wireplumber/50-kaisa-sof-rt5682-hdmi.conf)** 放到 **`~/.config/wireplumber/wireplumber.conf.d/`**（文件名以 **`.conf`** 结尾），**`systemctl --user restart wireplumber pipewire pipewire-pulse`**，再 **`pactl set-card-profile <卡名> pro-audio`**、**`pactl set-default-sink`** 指到 **`pro-output-2`**（或当前 Jack 对应路），按 §4.2 打开对应 **`IEC958',N`**，最后 **`paplay` / `speaker-test -D pulse`**。 | +| **长期「无 Jack 不误导」、桌面端口模型** | **UCM**：安装 overlay 后 **移走** 上述 WirePlumber 片段，依赖 WirePlumber 按 UCM 启用 **`HDMI1/2/3`**；与 pro-audio **互斥**（见下 §2.3）。 | + +**建议顺序**：先走 **pro-audio** 验证硬件与 PipeWire 路由；**有声之后**再决定继续 **修 UCM**（例如消除 **`Failed to enable ucm device HDMI*`**）或 **长期保留 pro-audio**。**「自动屏蔽未插入的 HDMI」** 依赖 UCM 或自写策略，见 §2.3，应在 **HDMI 已能出声** 之后再做。 + +**若已安装 `kaisa-hdmi-pipewire-fix` 却未卸载**：deb 会把 **UCM2** 装入 **`/usr/share/alsa/ucm2/`**（如 **GoogleKaisa**）。仅恢复 **`50-kaisa-…conf`** 时，WirePlumber **仍会按 UCM 做端口可用性**，未插线的 HDMI 可能继续**不可用 / 像被「隐藏」**，与「全开 pro-audio 对照」不一致。要做**干净 pro-audio 基线**：先 **`sudo apt purge kaisa-hdmi-pipewire-fix`**，再按上文复制 WirePlumber 片段。系统自带的 **`alsa-ucm-conf`** 仍可能提供通用 **`sof-rt5682`** 配置；若仍异常，以本机 **`alsaucm` / `pactl list cards`** 为准。 + +--- + +## 1. 现象与原因（摘要） + +| 现象 | 说明 | +|------|------| +| 设置里只有 **「立体声」**、**`pactl list short sinks` 仅 1 个** | 声卡 profile 为 **`stereo-fallback`**，未暴露多路 HDMI PCM。 | +| GNOME **「测试扬声器」** 无图标 | HDMI / Pro Audio 常无 Front L/R 声道名，**界面不可用**不代表无声；PipeWire 下用 **`speaker-test -D pulse`** 或 **`paplay`**（走默认 sink）；**`plughw:…`** 常与 PipeWire **EBUSY (-16)** 冲突。 | +| **`HDMI/DP,pcm=3/4 Jack` = off** | 该路 **未检测到显示器**，勿用 **`plughw:0,3`** / **`0,4`** 指望有声；对齐 **Jack=on** 的 pcm 与物理口。 | +| **`IEC958',N` 与 `IEC958 Playback Switch`** | 本机简单控件名为 **`IEC958',0`** 等（与 **pcm=2/3/4** 对应）；**`Mono: Playback [off]`** 时 PipeWire 仍可能 **RUNNING**、**`speaker-test -D pulse`** 仍跑计数，但 **HDMI 无声**。核对：**`amixer -c0 cget numid=14,20,26`** 或 **`sget 'IEC958',0`**。 | + +--- + +## 2. 固化方案：WirePlumber `wireplumber.conf.d` + +在 **`~/.config/wireplumber/wireplumber.conf.d/`** 下放片段（**文件名以 `.conf` 结尾**），实现： + +1. **强制 `device.profile = pro-audio`**：始终暴露 **Pro / Pro 2 / Pro 3 / Pro 4**（与 `aplay -l` 中 **Port1 / HDMI1/2/3** 对应）。 +2. **`monitor.alsa.rules` 提高 HDMI 相对模拟口的 `priority.session`**：HDMI sink **可用且优先级更高** 时，WirePlumber 倾向将其设为 **默认输出**；拔出后回退到模拟（以本机行为为准）。 + +仓库内 **示例文件**（可复制到上述目录）： + +- [`wireplumber/50-kaisa-sof-rt5682-hdmi.conf`](wireplumber/50-kaisa-sof-rt5682-hdmi.conf) + +安装命令示例： + +```bash +mkdir -p ~/.config/wireplumber/wireplumber.conf.d +cp /path/to/chromebox_10th_audio_driver/docs/linux-hdmi/wireplumber/50-kaisa-sof-rt5682-hdmi.conf \ + ~/.config/wireplumber/wireplumber.conf.d/ +systemctl --user restart wireplumber pipewire pipewire-pulse +``` + +**优先级（示例文件内）**：`pro-output-0`（模拟）**1000**；`pro-output-3` **1090**；`pro-output-4` **1095**；`pro-output-2`（HDMI1）**1100**。多路 HDMI 同时存在时 **HDMI1 优先**；若你常接 **HDMI2/3**，可把对应 `node.name` 的优先级调到 **高于 1100**。 + +**PCI 路径变化**：若 `lspci` 中音频 BDF 不是 **`0000:00:1f.3`**，用以下命令查看实际 **`device.name` / `node.name`** 并替换 conf 中的字符串： + +```bash +pactl list cards +pactl list short sinks +``` + +**WirePlumber 大版本升级**：语法可能变化，见 [WirePlumber migration](https://pipewire.pages.freedesktop.org/wireplumber/daemon/configuration/migration.html)。 + +### 与系统「声音设置」里输出列表的预期 + +本文 **`pro-audio` + `monitor.alsa.rules`** 的首要目标是：**在 PipeWire 侧暴露多路 sink**（**`pactl list short sinks`** 中的 **`pro-output-*`**）、配合 **IEC958** 与 **默认 sink / 优先级** 让 HDMI **能出声**、可经 **`pactl set-default-sink`** 或 **`speaker-test -D pulse`** 验证。各**桌面环境**自带的 **「设置 → 声音」** 面板如何枚举输出，取决于其是否把 **`pro-audio` 下的节点**画成易选项、以及 **`pactl list cards`** 里 **声卡「端口」**是否包含 HDMI；在 **`pro-audio`** 下常出现 **仅列出模拟类端口、HDMI 不单独出现在卡端口列表** 的情况，**不等于** HDMI sink 不存在。因此 **「插上 HDMI 后，这一路自动出现在系统声音设置的选择器里」** 不能仅凭本仓库片段保证；若需在图形界面里切换 **`pro-output-*`**，可改用 **Pulse 兼容混音器**、**Patchbay / 节点路由工具** 等（包名因发行版而异；常见可选组件如 **pavucontrol**、**Helvum**），或在终端用 **`wpctl`** 查看与切换。若期望 **插拔与可用性严格对应、并在设置里以「端口」形式出现**，长期更依赖 **ALSA UCM（`alsa-ucm-conf` 等）** 与栈的集成，而非仅 WirePlumber 静态规则。 + +### 与「无 Jack 就从选择器里删掉」 + +**与本文 §2 策略存在根本取舍**： + +- **`device.profile = pro-audio`** 的作用，正是把 **`aplay -l` 里多路 PCM（含 HDMI1/2/3）都变成独立 sink**（**`pro-output-*`**），**一般不随** 某路 **`HDMI/DP,pcm=N` Jack** 关而自动从 PipeWire 里消失；否则也谈不上「多路一次暴露、再调优先级」。 +- WirePlumber 文档里虽有 **`node.disabled`**（设为 true 时 **PipeWire 会从节点列表里去掉该 sink**），但 **要匹配「无 Jack」** 需要 **节点属性里存在可随插拔变化的量**，且 **规则在 Jack 变化时会被重新应用**；**仅靠** 仓库里这一条 **静态 `monitor.alsa.rules`**，**不能保证** 对所有机型、所有 PipeWire 版本都实现 **「无 Jack = 选择器里完全没有该项」**。 + +**若把「按 Jack 隐藏」放在第一位**，可行方向是 **换策略**，而不是把 **`50-kaisa-sof-rt5682-hdmi.conf` 改两行就完事**： + +1. **UCM / ACP 端口模型**：用 **端口 availability** 驱动路由，让 **未接线的 HDMI** 不成为可选输出（**更接近** Windows/桌面对「无效口」的处理）；**代价**是与 **强制 pro-audio 一次性拉满多路** 的路线不同，需单独调通 **Kaisa** 的 UCM 与 **IEC958**（详见 **[reference/ucm2/README.md](../../reference/ucm2/README.md)** 与 §2.3 互斥说明）。 +2. **WirePlumber Lua 或自写守护**：监听 **ALSA jack** / 轮询 **`amixer`**，在 **Jack off** 时对对应节点设 **`node.disabled`**（或 **`pw-cli`** 改属性）；**可定制**，但要 **自己维护** 与升级。 +3. **保持本文 §2**：继续 **pro-audio + IEC958**，接受 **选择器里可能仍列出多路**（即便某路 **Jack off**），以 **换线后 `set-default-sink` / `amixer`** 对齐实际出声口。 + +**结论**：**「无 Jack 就从选择器里删掉」** 与 **「强制 pro-audio 暴露全部 HDMI」** 不能无代价同时成立；要实现前者，**应优先评估 UCM 路线或自定义策略**，而不是假定 **单靠一个与当前 `50-*.conf` 同类的静态片段** 即可覆盖。 + +### UCM 模式 vs pro-audio 模式（互斥） + +| 模式 | 做法 | 适用 | +|------|------|------| +| **pro-audio（§2 过渡）** | **`50-kaisa-sof-rt5682-hdmi.conf`** 强制 **`device.profile = pro-audio`** + **IEC958**（**`pactl`/`amixer`**，§4.2） | 快速多路 **`pro-output-*`**、先保证出声 | +| **UCM（产品目标）** | 安装 **[reference/ucm2/](../../reference/ucm2/README.md)** 至 **`/usr/share/alsa/ucm2/`**（或 **`apt install kaisa-hdmi-pipewire-fix`**），让 **ACP** 按 **JackControl** 暴露路由 | **无 Jack 不误导**、更接近桌面「端口」模型 | + +**不要同时使用**：启用 **UCM overlay** 时，请 **移走或禁用** **`~/.config/wireplumber/.../50-kaisa-sof-rt5682-hdmi.conf`** 以及 **系统级** **`/etc/wireplumber/...`** 中同类片段（若由 deb 安装，见 §4.4 **UCM 优先时**说明），否则 **强制 pro-audio** 仍会盖过 **UCM 的 profile 语义**。改完后 **`systemctl --user restart wireplumber pipewire pipewire-pulse`**。 + +**验证 UCM 是否生效**：`pactl list cards` 中活动配置宜为 **HiFi** 等 **UCM 定义的 profile**，而非长期锁在 **pro-audio**（以本机 **`pactl`** 为准）。 + +**UCM 模式下 HDMI 无声（IEC958）**：与 §4.2 相同根因——**`IEC958',N` 仍为 off** 时，界面可选中 **HDMI/DisplayPort** 仍无声音。**请勿** **`pactl set-card-profile … pro-audio`** 做「恢复」，与 UCM 互斥。应： + +1. 先用 **`pactl set-default-sink`** 选中外接 HDMI 对应的 **`HiFi__hw_sofrt5682_N__sink`**（或 **`HiFi__hw__0_N__`**，以 **`pactl list short sinks`** 为准）。 +2. 再按 §4.2 打开对应 **`IEC958',N`**（**pcm=2→`IEC958',0`**，**pcm=3/4→`IEC958',1`/`',2`**）。 + +**Kaisa 实机 sink 名**常为 **`HiFi__hw_sofrt5682_N__sink`**（**`N`** 为 **device** 号，**0**=Port1，**2/3/4**=HDMI），与 **`HiFi__hw__0_N__`** 不同。 + +若 **`IEC958',N` 已为 on**、默认 sink 已是 HDMI 仍无声：检查 **`wpctl`** 静音/音量（**`wpctl set-mute @DEFAULT_AUDIO_SINK@ 0`**、**`wpctl set-volume @DEFAULT_AUDIO_SINK@ 1.0`**）、**物理线是否插在对应 HDMI1/2/3**（与 **`aplay -l`** 里 **device 2/3/4** 一致），以及 **`amixer`** 里 **`HDMI/DP,pcm=N` Jack** 是否为 **on**。 + +**自动化（未随 deb 提供）**：登录后自动 **`set-card-profile` / `set-default-sink` / 开 IEC958**、以及 **按 Jack 轮询默认 sink** 等，**尚未**在本仓库验证完毕，**`kaisa-hdmi-pipewire-fix` ≥0.3.0** 仅装 **UCM2 + WirePlumber 片段**。若你自行编写 **user systemd**，勿在 **UCM 模式**下执行会强制 **pro-audio** 的命令。**插入 HDMI 时是否弹出输出选择** 由 **桌面/会话** 决定。 + +--- + +## 3. 验证 + +```bash +pactl list cards +``` + +**活动配置** 应为 **`pro-audio`**。 + +```bash +pactl get-default-sink +pactl list short sinks +``` + +插入 HDMI（**Jack 对应的那路**，如 **pcm=2**）后，默认 sink 宜为 **`...pro-output-2`**（或你优先级最高的那路）。 + +**出声测试（推荐）**：桌面默认用 PipeWire 时，声卡常被其占用；此时 **`speaker-test -D plughw:0,2`** 会报 **打开错误: -16（设备或资源忙，EBUSY）**，属正常现象。请先 **`pactl set-default-sink`** 指到目标 HDMI sink，再经 **Pulse 兼容设备** 测试： + +```bash +speaker-test -D pulse -c2 -t sine -f 440 -l 3 +``` + +或 **`paplay /usr/share/sounds/alsa/Front_Center.wav`**（同样走当前默认 sink）。 + +**ALSA 直连**（仅在不与 PipeWire 争用同一路时可用，例如已 **`systemctl --user stop pipewire pipewire-pulse wireplumber`** 的排障会话）： + +```bash +speaker-test -D plughw:0,2 -c2 -t sine -f 440 -l 3 +``` + +--- + +## 4. 可选与兜底 + +- **`api.acp.auto-port = true`**：可在 **同一条 `device` 匹配规则** 的 `update-props` 中尝试（与 **`pro-audio`** / UCM 可能交互）；**先备份 conf**，再 A/B。 +- **优先级仍不理想**：可用 **user systemd oneshot**（登录执行 `pactl set-card-profile … pro-audio` + `pactl set-default-sink …`）作次级方案。 + +### 4.1 重启后又没声 + +WirePlumber 片段若仍在，常见原因不是 profile 丢失，而是 **GNOME/会话记住了旧的默认 sink**、**冷启动时 HDMI Jack 尚未就绪**、或 **应用仍指向已不存在的 sink**。 + +**先快速自检：** + +```bash +pactl list cards | grep -E "名称：alsa_card|活动配置" +pactl get-default-sink +pactl list short sinks +``` + +若 **活动配置** 回到 **`stereo-fallback`**，检查 **`~/.config/wireplumber/wireplumber.conf.d/50-kaisa-sof-rt5682-hdmi.conf`** 是否仍存在，然后： + +```bash +systemctl --user restart wireplumber pipewire pipewire-pulse +``` + +若已是 **`pro-audio`** 但仍无声，可 **手动** 设默认 sink 并开 IEC958（卡名、sink 名以本机为准）： + +```bash +pactl set-card-profile "$(pactl list cards short | awk '/cml_rt5682/ {print $2; exit}')" pro-audio +pactl set-default-sink "$(pactl list short sinks | awk '/\\.pro-output-2/ {print $2; exit}')" +amixer -c0 sset 'IEC958',0 on # 或按 §4.2 对 pcm=3/4 开 IEC958',1 / ',2 +``` + +再用 **`speaker-test -D pulse`**（或 **`paplay`**）确认经 PipeWire 的默认 sink 是否有声；**`-D plughw:…`** 在 PipeWire 占用声卡时会出现 **EBUSY (-16)**。 + +**登录自动执行（可选，自建）**：自行编写 **user systemd** oneshot（**`pactl`/`amixer`**），**`After=pipewire-pulse.service`**，必要时 **`ExecStartPre=/bin/sleep 2`**。仓库 **[`systemd-user/kaisa-hdmi-iec958-pipewire.service`](systemd-user/kaisa-hdmi-iec958-pipewire.service)** 仅为示例，**需自备** **`ExecStart`** 所指可执行文件（deb **不**提供）。 + +### 4.1a 换了 HDMI 口，系统里「默认输出」没跟着变，但仍有声 + +**常见原因** + +1. **默认 sink 是「粘住」的**：GNOME / 会话会记住 **`pactl get-default-sink`**；WirePlumber 又用 **`priority.session`** 把某一路（示例里是 **`pro-output-2`**）抬成首选。**换线**不等于自动把默认 sink 改到「新插上、Jack 刚亮」的那一路 **`pro-output-3` / `pro-output-4`**。 +2. **出声不一定等于「已切到你心里的那一路」**：声音仍可能从 **当前默认 sink** 对应的那条 **IEC958 / pcm** 出来；若显示器 **多路 HDMI 共用一套喇叭**、或你其实还在听 **模拟口**，会感觉「换口了怎么还有声」。 +3. **画面跟声音可以来自不同逻辑设备**：例如线接到显示器 **HDMI2**，但默认 sink 仍是 **`…pro-output-2`**（逻辑 HDMI1）；部分显示器会把当前选中输入的声音播出来，容易混淆。 + +**建议自检** + +```bash +pactl get-default-sink +pactl list short sinks +pactl list cards +# 在 cards 输出里看各 HDMI/DP 的 Jack 与 profile，对照 aplay -l 的 pcm 号 +``` + +**要对齐「物理口 ↔ 默认输出」**：把默认 sink 设到 **Jack=on** 且与当前线一致的那一路，例如（名称以你机器 **`pactl list short sinks`** 为准）： + +```bash +pactl set-default-sink alsa_output.pci-0000_00_1f.3-platform-cml_rt5682_def.pro-output-3 +``` + +**换插后**：请在 **设置 / pavucontrol** 里重选输出，或 **`pactl set-default-sink`**；若你**固定**用机箱某一 HDMI 口，可在 **`50-kaisa-sof-rt5682-hdmi.conf`** 里把该口对应 **`pro-output-N`** 的 **`priority.session`** 调到 **高于 1100**（见 §2 文末说明）。 + +### 4.2 IEC958 关闭导致「Pulse 正常、HDMI 无声」 + +若 **`HDMI/DP,pcm=2 Jack` = on**、默认 sink 为 **`pro-output-2`**，仍无声，检查 **数字输出开关**（本机 **pcm=2** 对应 **`IEC958',0` / `IEC958 Playback Switch` numid=14）： + +```bash +amixer -c0 sget 'IEC958',0 +``` + +若为 **`[off]`**，执行： + +```bash +amixer -c0 sset 'IEC958',0 on +``` + +**pcm=3 / pcm=4** 分别对应 **`IEC958',1`**、**`IEC958',2`**（与 **`pro-output-3` / `pro-output-4`** 对齐）。 + +**IEC958 已为 on、仍无声，且 `journalctl --user -u pipewire` 出现 `spa.alsa: set_hw_params` / `输入/输出错误`、对应 sink `suspended -> error`**：对照 **`aplay -l`**，若该 HDMI **device** 下一行 **`子设备: 0/1`**（**Subdevices: 0/1**）——左侧 **0** 表示 **ALSA 当前无法打开该 device**，与 **IEC958** 无关。可 **换插另一 HDMI 口**、**`systemctl --user restart wireplumber pipewire pipewire-pulse`** 或 **重启**；勿把默认 sink 锁在 **Jack=on 但子设备为 0** 的那一路。 + +**另见**：若 **`journalctl --user -u wireplumber`** 有 **`Failed to enable ucm device HDMI2`**（或 **HDMI1** / **HDMI3**），且 **`pipewire`** 仅对 **`HiFi__hw_sofrt5682_3__sink`**（或 `_2__` / `_4__`）报错，则为 **UCM SectionDevice 启用失败**（与 **[reference/ucm2/GoogleKaisa/sof-rt5682/HiFi.conf](../../reference/ucm2/GoogleKaisa/sof-rt5682/HiFi.conf)** 中 **HDMI1/2/3** 对应 **device 2/3/4** 一致）。宜 **换插到另一 HDMI 物理口** 或 **`alsaucm -c sof-rt5682 set _verb HiFi set _device …`** 单独验证；详见 **[next.md](../../next.md)**（单命令：安装 + 诊断）。 + +### 4.3 登录自动恢复（规划中） + +**根因**：**`IEC958',0`（pcm=2）被关** → HDMI 无声（PipeWire 可看似正常）；完整 **「切 pro-audio + 默认 HDMI sink + 开 IEC958」** 自动化**尚未**作为稳定工具随 **`kaisa-hdmi-pipewire-fix`** 发布。 + +**当前**：请用 §4.1 / §4.2 **手动命令**；需要登录自启时，自行编写 **user systemd**（可参考 **[`systemd-user/kaisa-hdmi-iec958-pipewire.service`](systemd-user/kaisa-hdmi-iec958-pipewire.service)** 结构，**`ExecStart`** 指向你本机的 shell 片段或脚本）。 + +### 4.4 Debian 包（系统级交付） + +仓库 **`debian/`** 提供原生包 **`kaisa-hdmi-pipewire-fix`**（`Architecture: all`）。在**源码根目录**构建： + +```bash +./scripts/build-deb.sh +``` + +`dpkg-buildpackage` 默认把 **`.deb` / `.changes` / `.buildinfo`** 写到**上一级目录**；本脚本在构建后把 **`kaisa-hdmi-pipewire-fix_*`** 移回**项目根目录**（与根目录 **`.gitignore`** 中的 `*.deb` 等一致），**`chmod 644`**，并把 **`*_all.deb`** 复制到 **`/tmp/`**（供 **`sudo apt install /tmp/…`**，避免家目录权限导致 **`_apt`** 读包报错）。若需沿用默认行为，仍可直接执行 **`dpkg-buildpackage -us -uc -b`**，再到上级目录取 **`kaisa-hdmi-pipewire-fix_<版本>_all.deb`**。 + +安装示例（在项目根目录先 **`./scripts/build-deb.sh`**；优先用 **`/tmp`** 副本，避免 **`apt`** / **`_apt`** 无法遍历家目录）： + +```bash +sudo apt install /tmp/kaisa-hdmi-pipewire-fix_0.3.0_all.deb +``` + +**包内内容（≥0.3.0：仅配置，无 `/usr/bin` 辅助工具）**： + +- **UCM2**：**`/usr/share/alsa/ucm2/conf.d/sof-rt5682/sof-rt5682.conf`**、**`/usr/share/alsa/ucm2/GoogleKaisa/sof-rt5682/HiFi.conf`**（源码见 **[reference/ucm2/README.md](../../reference/ucm2/README.md)**）；**依赖** **`alsa-ucm-conf`**。 +- **WirePlumber**：**`/etc/wireplumber/wireplumber.conf.d/50-kaisa-sof-rt5682-hdmi.conf`**（**系统级**，与 **`~/.config/...`** 二选一即可，勿重复冲突）。**`apt upgrade`** 安装本包新版本时，若该路径在系统上**不存在**（例如已改名为 **`.disabled`**），dpkg **会再次装入**该文件；走 **UCM** 时，升级后请**再移走**或确认仍为 **`.disabled`**。 +- **文档**：**`/usr/share/doc/kaisa-hdmi-pipewire-fix/`**（**`README.md.gz`** = UCM 说明；可选打包 **OPERATION**）。 + +**0.2.x 及更早** 曾附带 **`kaisa-restore-*`** 与 user systemd 单元；**0.3.0** 起移除，直至手工验证与自动化策略定型。 + +**UCM 优先时**：按上文 **「UCM 模式 vs pro-audio 模式」** 移走 **`50-kaisa-…`**，避免与 **强制 pro-audio** 叠用。发布前请改 **`debian/control`**、**`debian/changelog`**、**`debian/copyright`** 中的维护者与许可证说明。 + +**说明** + +- **更广分发**：可将该 deb 放入自建 **APT 仓库 / PPA**；更长远的修复仍是 **ALSA UCM / 上游** 在适用机型上 **默认打开 IEC958**（与发行版/上游沟通，不在本仓库另文维护）。 + +### 4.5 基线备份与恢复（Ubuntu 默认 / 安装 deb 前状态） + +**目的**：在**首次安装** `kaisa-hdmi-pipewire-fix` 或做大改之前，把当前机的音频相关路径与诊断**落盘**，并在后续工作中可**尽量恢复**到该状态。 + +**为何 `reinstall alsa-ucm-conf`**：本 deb 会向 **`/usr/share/alsa/ucm2/conf.d/sof-rt5682/sof-rt5682.conf`** 安装与 **`alsa-ucm-conf` 同路径**的文件，相当于**覆盖**发行版 vendor 配置。`apt purge kaisa-hdmi-pipewire-fix` 会移除本包提供的文件，但**稳妥恢复 vendor 内容**应执行 **`sudo apt install --reinstall alsa-ucm-conf`**（与基线脚本中的 **`system-overlay.tar.gz`** 二选一通常等价）。 + +**deb 涉及的绝对路径（与 §4.4 一致，便于核对）** + +| 路径 | 说明 | +|------|------| +| `/etc/wireplumber/wireplumber.conf.d/50-kaisa-sof-rt5682-hdmi.conf` | conffile | +| `/usr/share/alsa/ucm2/conf.d/sof-rt5682/sof-rt5682.conf` | 与 vendor 同路径，purge 后需 reinstall | +| `/usr/share/alsa/ucm2/GoogleKaisa/sof-rt5682/HiFi.conf` | 本包新增 | +| （无 **`/usr/bin` 辅助脚本**，≥0.3.0） | 见 §4.4 | +| `/usr/share/doc/kaisa-hdmi-pipewire-fix/` | 文档（常为 `.gz`） | + +**一键采集基线**（默认目录：`audio_topology/baseline-stash/<时间戳>_/`，已加入根目录 **`.gitignore`**，避免大块采集误入版本库）： + +```bash +cd /path/to/chromebox_10th_audio_driver +./scripts/capture-ubuntu-audio-baseline.sh +``` + +生成文件通常包括：**`manifest.txt`**（dpkg 状态、上表路径是否存在与 sha256）、**`topology.txt`**（调用 `audio_topology/collect_linux_audio_topology.sh` 的完整输出）、**`system-overlay.tar.gz`**（若存在 vendor **`sof-rt5682.conf`** 则备份）、**`user-wireplumber-conf.tar.gz`**（若 `~/.config/wireplumber/wireplumber.conf.d/` 下已有文件名含 kaisa 的片段）。 + +**一键恢复**（不传参数时使用 **最近**一次基线目录）： + +```bash +./scripts/restore-ubuntu-audio-baseline.sh +# 或指定目录： +./scripts/restore-ubuntu-audio-baseline.sh /path/to/audio_topology/baseline-stash/<某次>/ +``` + +**若曾自建** §4.3 的 **user systemd** 自动执行 **`pactl`/`amixer`**，恢复基线前请先 **`disable --now`** 相应单元，避免登录后仍改 profile。 + +--- + +## 5. 参考链接 + +- [WirePlumber ALSA configuration](https://pipewire.pages.freedesktop.org/wireplumber/daemon/configuration/alsa.html) +- [设备优先级示例（monitor.alsa.rules）](https://danielpower.ca/blog/wireplumber-device-priority) diff --git a/docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md b/docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md new file mode 100644 index 0000000000..afb569d948 --- /dev/null +++ b/docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md @@ -0,0 +1,155 @@ +# 手顺：与 `kaisa-hdmi-pipewire-fix` deb 等价的 pro-audio 路径（可复现） + +**目的**：在真机上**不依赖**写死的 `wpctl set-profile 46 4`，按 deb 交付物复现「WirePlumber 片段 + `pro-audio` + 默认 HDMI sink + IEC958」，用于打包前验收。 + +**相关**：deb 安装内容见 [OPERATION_PipeWire_Kaisa_HDMI.md](OPERATION_PipeWire_Kaisa_HDMI.md) §4.4；pro-audio 路径见同文档 §2（复制 `50-kaisa`、重启栈，再 **`pactl set-card-profile … pro-audio`**）。 + +### 常用检查（sinks / 设备，不依赖 pulseaudio-utils） + +| 用途 | 命令 | +|------|------| +| **总览**：声卡、**Sinks**（输出）、**Sources**（输入）、默认 sink 标记 `*` | `wpctl status` | +| 某条 sink 详情（含 `node.name`、`device.profile.name`） | `wpctl inspect `，如 `wpctl inspect @DEFAULT_AUDIO_SINK@` | +| 若已安装 **pulseaudio-utils** | `pactl list short sinks`、`pactl get-default-sink`、`pactl list cards` | + +说明：**Sinks** 前的数字 id **重启栈后会变**，以当次 `wpctl status` 为准；**`wpctl set-default `** 只填 **Sink** 的 id，**不要**与 **Devices**（声卡）混淆。 + +--- + +## 0. 可选：回到安装 deb / 改配置前的基线 + +若曾运行过 `capture-ubuntu-audio-baseline.sh`： + +```bash +cd /path/to/chromebox_10th_audio_driver +./scripts/restore-ubuntu-audio-baseline.sh /path/to/audio_topology/baseline-stash/<某次>/ +``` + +或仅在本机清掉用户片段后重启栈（自行备份）： + +```bash +mv -f ~/.config/wireplumber/wireplumber.conf.d/50-kaisa-sof-rt5682-hdmi.conf \ + ~/.config/wireplumber/wireplumber.conf.d/50-kaisa-sof-rt5682-hdmi.conf.disabled 2>/dev/null || true +systemctl --user restart pipewire pipewire-pulse +sleep 1 +systemctl --user restart wireplumber +``` + +--- + +## 1. 与 deb 一致：安装 WirePlumber 片段 + +**deb 安装位置**：`/etc/wireplumber/wireplumber.conf.d/50-kaisa-sof-rt5682-hdmi.conf`（需 root）。 + +**手动复现（二选一）**： + +**A. 系统级（与 deb 完全一致）** + +```bash +sudo mkdir -p /etc/wireplumber/wireplumber.conf.d +sudo cp docs/linux-hdmi/wireplumber/50-kaisa-sof-rt5682-hdmi.conf \ + /etc/wireplumber/wireplumber.conf.d/ +``` + +**B. 用户级（与当前调试习惯一致，不 sudo）** + +```bash +mkdir -p ~/.config/wireplumber/wireplumber.conf.d +cp docs/linux-hdmi/wireplumber/50-kaisa-sof-rt5682-hdmi.conf \ + ~/.config/wireplumber/wireplumber.conf.d/ +``` + +若存在**无扩展名**的 `50-kaisa-sof-rt5682-hdmi` 文件，应改名禁用，避免与 `.conf` 重复（见 [OPERATION](OPERATION_PipeWire_Kaisa_HDMI.md) §2）。 + +--- + +## 2. 重启 PipeWire 栈（推荐顺序） + +与「空 Audio 列表」排障一致：**先 PipeWire，再 WirePlumber**。 + +```bash +systemctl --user restart pipewire pipewire-pulse +sleep 1 +systemctl --user restart wireplumber +``` + +再等 1～2 秒。 + +### 已复制 `50-kaisa-…conf` 但仍只有一条「立体声」sink？ + +在 **WirePlumber 0.4.x**（Ubuntu 24.04 常见）上，仓库里的 **`monitor.alsa.rules`** 片段**可能不会**自动把卡切到 **pro-audio**，`pactl list cards` 里**活动配置**仍为 **`output:stereo-fallback+input:…`**。这**不代表**片段装错路径，而是**会话管理器版本**与 **0.5+** 行为不同。 + +**验收与 deb 交付仍成立**：必须再执行下面 §3 的 **`pactl set-card-profile … pro-audio`**。**deb（≥0.3.0）仍包含该 conf**（未来 **0.5+** 或更易合并 drop-in 的环境上可能单独生效）；**不**再随包提供 `kaisa-restore-pipewire-hdmi`，请用本手顺 **`pactl`**/**`amixer`**。 + +--- + +## 3. 验证：是否已 `pro-audio`（勿写死 46 / 4） + +**稳定标识**是 **声卡名** + **profile 名**，不是数字 id。 + +```bash +# 若已安装 pulseaudio-utils： +pactl list cards | grep -A2 'alsa_card.pci-0000_00_1f.3-platform-cml_rt5682_def' -A30 +``` + +或： + +```bash +wpctl status +wpctl inspect | grep -E 'name|profile' +``` + +若 **活动配置**仍是 **`stereo-fallback`**，执行： + +```bash +pactl set-card-profile alsa_card.pci-0000_00_1f.3-platform-cml_rt5682_def pro-audio +``` + +**实机结论（WirePlumber 0.4.x）**：仅把 **`50-kaisa-…conf`** 放到 **`/etc/wireplumber/...`** 或 **`~/.config/...`** 并重启栈后，**`wpctl status` → Sinks** 往往仍只有一条「立体声」；**执行上列 `pactl set-card-profile … pro-audio` 之后**，才会出现多条 **Pro / Pro 2 / Pro 3 / Pro 4**（或等价 **`pro-output-*`**）。因此 **0.4 验收以本 `pactl` 命令为「多出 sinks」的分界**，而非单靠 conf。 + +**说明**：**Settings → Default Configured Node Names** 里有时仍出现带 **`stereo-fallback`** 字样的行，以 **`pactl list cards` 中该卡「活动配置」** 与 **`wpctl status` 里 Sinks 条数**为准。 + +**GUI 试声后 Pro sinks 消失**：在 **GNOME 设置 → 声音** 里用系统自带「测试」或切换输出时，**有可能**把声卡**又改回 `stereo-fallback`**，`wpctl status` 里 **Sinks** 会只剩「立体声」。属 **Pro-audio 与桌面会话抢 profile** 的常见现象（WirePlumber 0.4 尤甚）。**处理**：再执行一次 **`pactl set-card-profile … pro-audio`** 并按 §4 开 **`IEC958`**；试声优先用终端 **`pw-play` / `paplay`**（见 OPERATION §2「测试扬声器」说明）。 + +- **PCI 路径不同**的机器：用 `pactl list cards short` 第二列**实际卡名**替换上面长名。 +- **WirePlumber 0.5+** 且片段被正确加载时，有时**无需**再执行 `pactl`，以本步检查结果为准。 +- **WirePlumber 0.4.x**：多数情况下**必须**执行本步 `pactl`；见上文「已复制 conf 但仍只有立体声」。 + +--- + +## 4. 默认 sink + IEC958 + +**≥0.3.0** 的 deb **不**包含 **`kaisa-restore-pipewire-hdmi`**。请在本机用 **`pactl`**（需 **`pulseaudio-utils`**）完成与 §3 同源的 profile 切换，再 **`pactl set-default-sink`** 指到 **`pro-output-2`**（或当前 Jack 对应 **`pro-output-N`**），并按 [OPERATION §4.2](OPERATION_PipeWire_Kaisa_HDMI.md) 打开对应 **`IEC958',N`**。 + +若未安装 **`pulseaudio-utils`**：用 **`wpctl set-profile`** + **`wpctl set-default`**（见 OPERATION §4.1），再 **`amixer`** 开 IEC958。 + +--- + +## 5. 验收标准（打包前勾选） + +| 检查项 | 命令 / 预期 | +|--------|-------------| +| 卡 profile | `pactl list cards` 中该卡 **活动配置** 含 **pro-audio**（或等价描述） | +| 多 sink | `pactl list short sinks` 或 `wpctl status` 出现 **pro-output-*** 或 **Pro 2/3/4** | +| 默认输出 | `pactl get-default-sink` 指向 **pro-output-2**（或当前接线对应路） | +| IEC958 | `amixer -c0 sget 'IEC958'` 对应路为 **on** | +| 试声 | `pw-play /usr/share/sounds/alsa/Front_Center.wav` 或 `paplay`（走默认 sink） | + +--- + +## 6. 手顺小节索引 + +| 步骤 | 本文 | +|------|------| +| 片段 + 清无扩展名 | §1–2 | +| 重启栈 | §3 | +| `pactl` / `amixer`（§4） | §4 | +| 验收 / 试声 | §5 | + +--- + +## 7. deb 打包前建议 + +1. 在 **目标 Ubuntu 版本**（如 24.04）上按本文 **0→5** 跑通一次。 +2. 再 **`./scripts/build-deb.sh`** 安装 deb，**重复 §5 验收**（此时片段在 `/etc/wireplumber/...`，仍无随包 `/usr/bin` 工具）。 +3. 若走 **UCM** 路线，**移走** `50-kaisa-…conf` 后验收（与 OPERATION「互斥」一致）。 diff --git a/docs/linux-hdmi/systemd-user/kaisa-hdmi-iec958-pipewire.service b/docs/linux-hdmi/systemd-user/kaisa-hdmi-iec958-pipewire.service new file mode 100644 index 0000000000..8e67723f1f --- /dev/null +++ b/docs/linux-hdmi/systemd-user/kaisa-hdmi-iec958-pipewire.service @@ -0,0 +1,15 @@ +# 示例：登录后执行「pro-audio + 默认 sink + IEC958」——需自备可执行文件（deb ≥0.3.0 不随包提供脚本）。 +# 将 @@HOME@@ 换为 $HOME；ExecStart 可指向你自己写的 shell，内嵌 §4.1/§4.2 的 pactl/amixer 命令。 +[Unit] +Description=Kaisa SOF rt5682: PipeWire pro-audio + IEC958 (HDMI) +After=pipewire-pulse.service +Wants=pipewire-pulse.service + +[Service] +Type=oneshot +RemainAfterExit=yes +ExecStartPre=/bin/sleep 2 +ExecStart=@@HOME@@/.local/bin/kaisa-restore-pipewire-hdmi + +[Install] +WantedBy=default.target diff --git a/help.md b/help.md new file mode 100644 index 0000000000..85029c4ce7 --- /dev/null +++ b/help.md @@ -0,0 +1,80 @@ +# BMad Help 速查 + +## BMad Help 是做什么的 + +用来：**判断你在 BMad 流程里大致处在哪一步**、**下一步该用哪个技能**、以及**怎么调用**（技能名、菜单码、可选参数）。不要求你背全目录。 + +--- + +## 本仓库里已装模块（精简版） + +### Core（随时可用） + +| 菜单码 | 名称 | 技能名 | 用途（摘自目录） | +| ------ | ---- | ------ | ---------------- | +| **BH** | BMad Help | `bmad-help` | 就是当前这条帮助 | +| **BSP** | Brainstorming | `bmad-brainstorming` | 早期发散、卡住时想点子 | +| **PM** | Party Mode | `bmad-party-mode` | 多角色 / 多视角讨论 | +| **ID** | Index Docs | `bmad-index-docs` | 让模型先「索引」文档再深入 | +| **SD** | Shard Document | `bmad-shard-doc` | 长文档拆分（常指 >500 行） | +| **EP / ES** | Editorial Review | `bmad-editorial-review-prose` / `structure` | 润色 / 调结构 | +| **AR / ECH** | Adversarial / Edge Case | `bmad-review-adversarial-general` / `edge-case-hunter` | 交付前挑刺、补边界 | +| **DG** | Distillator | `bmad-distillator` | 把长文压成保留信息的 distillate | + +### BMad Method（典型软件交付链，带阶段） + +阶段大致为：**1-analysis → 2-planning → 3-solutioning → 4-implementation**。 + +常用条目示例（完整列表见 `_bmad/_config/bmad-help.csv`）： + +| 阶段 | 示例技能（菜单码） | +| ---- | ------------------ | +| **1-analysis** | `bmad-product-brief` **[CB]**、`bmad-domain-research` **[DR]**、`bmad-market-research` **[MR]**、`bmad-technical-research` **[TR]**、`bmad-brainstorming` **[BP]** … | +| **2-planning** | `bmad-create-prd` **[CP]**、`bmad-create-ux-design` **[CU]**、`bmad-validate-prd` **[VP]** … | +| **3-solutioning** | `bmad-create-architecture` **[CA]**、`bmad-create-epics-and-stories` **[CE]**、`bmad-check-implementation-readiness` **[IR]** … | +| **4-implementation** | `bmad-sprint-planning` **[SP]**、`bmad-create-story` **[CS]**、`bmad-dev-story` **[DS]**、`bmad-code-review` **[CR]** … | +| **随时** | `bmad-document-project` **[DP]**、`bmad-generate-project-context` **[GPC]**、`bmad-quick-dev` **[QQ]**、`bmad-correct-course` **[CC]** … | + +在 Cursor 里一般是：**用自然语言说明要做的事**，或按安装器提供的**斜杠命令 / 技能名**调用（与 `npx bmad-method install` 生成的集成一致）。 + +### Creative Intelligence Suite（创意 / 方法套件） + +| 菜单码 | 名称 | 技能名 | +| ------ | ---- | ------ | +| **IS** | Innovation Strategy | `bmad-cis-innovation-strategy` | +| **PS** | Problem Solving | `bmad-cis-problem-solving` | +| **DT** | Design Thinking | `bmad-cis-design-thinking` | +| **BS** | Brainstorming | `bmad-brainstorming` | +| **ST** | Storytelling | `bmad-cis-storytelling` | + +### BMad Builder（搭技能 / 工作流 / 模块） + +例如 **[BA]** 建 Agent、**[BW]** 建 Workflow、**[CM]** 建模块等（见 `_bmad/_config/bmad-help.csv` 前几行）。 + +--- + +## 结合本仓库（Chromebox / HDMI） + +### 本仓库当前产品目标（Kaisa 桌面音频） + +**权威操作与交付**（PipeWire / pro-audio / deb / UCM）：**[docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md](docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md)**、**[reference/ucm2/README.md](reference/ucm2/README.md)**。 + +在此目标下，BMad 更偏 **棕地攻关 + 文档/交付对齐**。常用下一步： + +1. **`bmad-document-project` [DP]**：扩展/更新 `docs/linux-hdmi/` 与 **deb 范围**一致说明。 +2. **`bmad-generate-project-context` [GPC]**：把目标、路径、仓库布局收成代理可用的 **project-context**（若尚未生成）。 +3. **`bmad-cis-problem-solving` [PS]**：UCM 草稿卡壳、Jack/控件映射不清时做结构化拆解。 +4. **`bmad-technical-research` [TR]**：面向 **`alsa-ucm-conf` 上游 MR** 或发行版沟通时整理选项与引用。 + +若你**改走**标准 BMad Method **从 0 做产品文档**，再从 **[CB] 产品简报**或 **[CP] PRD** 开始会更顺（与 **OPERATION** 并行时，注意 PRD 与实机路线一致）。 + +--- + +## 使用建议（技能里写的） + +- 重要长流程尽量在**新的对话窗口**里单独跑一个技能，上下文更干净。 +- 更全的条目与依赖关系以 `_bmad/_config/bmad-help.csv` 为准；各模块输出默认可在 `_bmad-output`（见 `_bmad/core/config.yaml`）。 + +**完整 BMad 目录（中文全表）**：根目录 [bmad-help.zh-CN.md](bmad-help.zh-CN.md)（由 `_bmad/scripts/render_bmad_help_zh_cn.py` 根据 CSV 生成）。 + +若你接下来是想「写 PRD / 架构」还是「继续攻 HDMI 内核问题」，可以只选**一条**最优先的技能深入（仍用中文）。 diff --git a/next.md b/next.md new file mode 100644 index 0000000000..5ae1ed98e8 --- /dev/null +++ b/next.md @@ -0,0 +1,13 @@ +# next + +[docs/README.md](docs/README.md) · [OPERATION_PipeWire_Kaisa_HDMI.md](docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md) · [reference/ucm2/README.md](reference/ucm2/README.md) + +- **安装 deb 前基线 / 事后恢复**：[scripts/capture-ubuntu-audio-baseline.sh](scripts/capture-ubuntu-audio-baseline.sh) · [scripts/restore-ubuntu-audio-baseline.sh](scripts/restore-ubuntu-audio-baseline.sh)（详见 [OPERATION_PipeWire_Kaisa_HDMI.md](docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md) §4.5）。 +- **pro-audio / UCM / deb 手顺**：[OPERATION](docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md)（§2 起）；与 deb 等价的可复现验收：[REPRO_Kaisa_Deb_ProAudio_Manual.md](docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md)。 + +```bash +cd /path/to/chromebox_10th_audio_driver +./scripts/capture-ubuntu-audio-baseline.sh +# … 做改动 / 装 deb … +./scripts/restore-ubuntu-audio-baseline.sh +``` diff --git a/reference/chromeos-ubuntu-sound-diffs/README.md b/reference/chromeos-ubuntu-sound-diffs/README.md new file mode 100644 index 0000000000..2e8d8f76be --- /dev/null +++ b/reference/chromeos-ubuntu-sound-diffs/README.md @@ -0,0 +1,5 @@ +# ChromeOS 5.15 ↔ Ubuntu HWE（可选对照） + +本目录用于存放你在本机对两棵内核树 **`diff -u`** / **`diff -rq`** 的输出（例如 **`diff-u_sound_soc_….txt`**）。**仓库不再附带**自动生成脚本；在 **`chromiumos_kernel/v5.15`** 与 **`apt source linux-hwe-6.17`** 解压目录之间自行对照即可。 + +默认可将生成物放于此处；**`diff-u_*.txt`** 仍由根目录 **`.gitignore`** 忽略，避免大段 diff 误入版本库。 diff --git a/reference/ucm2/README.md b/reference/ucm2/README.md new file mode 100644 index 0000000000..a0729c7e42 --- /dev/null +++ b/reference/ucm2/README.md @@ -0,0 +1,49 @@ +# Kaisa UCM2 overlay（`sof-rt5682`） + +本目录为 **alsa-ucm-conf** 风格的 **UCM2** 草稿，目标：**Jack off 时 HDMI 路由对 ACP/桌面不表现为可随意可用的输出**（与强制 **`pro-audio`** 的 WirePlumber 策略不同，见 [docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md](../../docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md)「UCM 模式 vs pro-audio 模式」）。 + +## 布局 + +| 路径（相对 `ucm2/` 根） | 说明 | +|-------------------------|------| +| `conf.d/sof-rt5682/sof-rt5682.conf` | 卡入口，匹配 ALSA **card name** `sof-rt5682` | +| `GoogleKaisa/sof-rt5682/HiFi.conf` | HiFi：`Port1` + **HDMI1/2/3**，**JackControl** + **`IEC958',N`** | + +上游 **alsa-ucm-conf** 若日后增加同名 `conf.d/sof-rt5682/`，与本仓库 **deb 同时安装会冲突** — 优先 **合并上游** 或 **改名/拆包**（与 [OPERATION](../../docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md) 中 UCM / pro-audio 互斥说明一致）。 + +## 手工安装（调试） + +```bash +sudo cp -a reference/ucm2/conf.d/sof-rt5682 /usr/share/alsa/ucm2/conf.d/ +sudo cp -a reference/ucm2/GoogleKaisa /usr/share/alsa/ucm2/ +sudo alsactl init # 或重登 / 重启 pipewire +systemctl --user restart wireplumber pipewire pipewire-pulse +``` + +## 与 WirePlumber **`50-kaisa-sof-rt5682-hdmi.conf` 的互斥** + +- **UCM 模式（本 overlay）**：依赖 **ACP** 的 profile/端口；**请勿**再使用强制 **`device.profile = pro-audio`** 的片段，否则仍易出现 **多路 `pro-output-*` 常驻**。 +- **过渡 pro-audio 模式**：保留现有 `wireplumber.conf.d` 片段；**不要**同时叠加本 UCM 覆盖（二选一）。 + +## 校验（可选） + +若已安装 **`alsa-utils`**： + +```bash +alsaucm -c sof-rt5682 list _verbs +alsaucm -c sof-rt5682 set _verb HiFi list _devices +``` + +插拔 HDMI 时对照 **`amixer -c0`** 中 **`HDMI/DP,pcm=N` Jack** 与 **`IEC958',N`**。 + +## 实机验收表（勾选） + +| 步骤 | 预期 | +|------|------| +| 仅接模拟 / 不接 HDMI | HDMI 相关输出不对「可用路由」误导（依桌面实现） | +| 接 HDMI，Jack on | 对应 **IEC958** on 后有声 | +| 拔线 Jack off | 该路不应再被选为有效 HDMI 输出 | + +--- + +_控件名以本机 `amixer` 为准；若 `Headphone`/`IEC958` 命名不同，需改 `HiFi.conf` 后重测。_ diff --git a/scripts/capture-ubuntu-audio-baseline.sh b/scripts/capture-ubuntu-audio-baseline.sh new file mode 100755 index 0000000000..9d9c7a7520 --- /dev/null +++ b/scripts/capture-ubuntu-audio-baseline.sh @@ -0,0 +1,128 @@ +#!/usr/bin/env bash +# 在安装 kaisa-hdmi-pipewire-fix 或其它大改前，采集「Ubuntu / 当前机」音频基线并落盘。 +# 输出目录默认：audio_topology/baseline-stash/<时间戳>_/ +# 用法：./scripts/capture-ubuntu-audio-baseline.sh [输出目录] +# 详见：docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md「基线备份与恢复」 +set -euo pipefail + +REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +STAMP="$(date +%Y%m%d_%H%M%S)_$(hostname)" + +if [[ -n "${1:-}" ]]; then + STASH="$(realpath "$1")" +else + STASH="${REPO_ROOT}/audio_topology/baseline-stash/${STAMP}" +fi + +mkdir -p "$STASH/backup/root" + +write_manifest() { + local mf="$STASH/manifest.txt" + { + echo "# capture-ubuntu-audio-baseline" + echo "created_iso: $(date -Iseconds)" + echo "hostname: $(hostname)" + echo "stash_dir: $STASH" + echo "" + echo "## uname" + uname -a + echo "" + echo "## dpkg (相关包)" + dpkg -l 2>/dev/null | grep -E '^(ii|rc)\s+(alsa-ucm-conf|wireplumber|pipewire|pipewire-pulse|kaisa-hdmi-pipewire-fix)\s' || true + echo "" + if dpkg -s kaisa-hdmi-pipewire-fix &>/dev/null; then + echo "## kaisa-hdmi-pipewire-fix: installed" + dpkg -s kaisa-hdmi-pipewire-fix 2>/dev/null | grep -E '^(Package|Version|Status):' || true + else + echo "## kaisa-hdmi-pipewire-fix: not installed" + fi + echo "" + echo "## deb 相关路径（存在性与 sha256）" + } >"$mf" + + local paths=( + /etc/wireplumber/wireplumber.conf.d/50-kaisa-sof-rt5682-hdmi.conf + /usr/share/alsa/ucm2/conf.d/sof-rt5682/sof-rt5682.conf + /usr/share/alsa/ucm2/GoogleKaisa/sof-rt5682/HiFi.conf + ) + local p + for p in "${paths[@]}"; do + if [[ -e "$p" ]]; then + echo "PATH $p exists=yes" >>"$mf" + if [[ -f "$p" ]]; then + sha256sum "$p" >>"$mf" 2>/dev/null || echo "(sha256sum failed)" >>"$mf" + fi + else + echo "PATH $p exists=no" >>"$mf" + fi + done + echo "" >>"$mf" + echo "## /usr/share/doc/kaisa-hdmi-pipewire-fix/" >>"$mf" + if [[ -d /usr/share/doc/kaisa-hdmi-pipewire-fix ]]; then + ls -la /usr/share/doc/kaisa-hdmi-pipewire-fix >>"$mf" 2>&1 || true + else + echo "(目录不存在)" >>"$mf" + fi +} + +backup_vendor_ucm() { + local src="/usr/share/alsa/ucm2/conf.d/sof-rt5682/sof-rt5682.conf" + if [[ -f "$src" ]]; then + install -D -m0644 "$src" "$STASH/backup/root/usr/share/alsa/ucm2/conf.d/sof-rt5682/sof-rt5682.conf" + echo "已备份 vendor UCM: $src -> backup/root/..." + fi +} + +backup_user_wireplumber() { + local d="${HOME}/.config/wireplumber/wireplumber.conf.d" + local names=() + if [[ -d "$d" ]]; then + shopt -s nullglob + local f + for f in "$d"/*; do + [[ -e "$f" ]] || continue + local b + b="$(basename "$f")" + if [[ "$b" == *kaisa* ]] || [[ "$b" == 50-kaisa* ]]; then + names+=("$b") + fi + done + fi + if ((${#names[@]} > 0)); then + tar -C "$d" -czf "$STASH/user-wireplumber-conf.tar.gz" "${names[@]}" + echo "已打包用户 WirePlumber 片段: ${names[*]} -> user-wireplumber-conf.tar.gz" + else + echo "(未找到 ~/.config/wireplumber/... 下含 kaisa 的片段，跳过 user-wireplumber-conf.tar.gz)" + fi +} + +pack_system_overlay() { + if [[ -f "$STASH/backup/root/usr/share/alsa/ucm2/conf.d/sof-rt5682/sof-rt5682.conf" ]]; then + tar -C "$STASH/backup/root" -czf "$STASH/system-overlay.tar.gz" \ + usr/share/alsa/ucm2/conf.d/sof-rt5682/sof-rt5682.conf + echo "已生成 system-overlay.tar.gz（可配合 restore 还原安装 deb 前的 vendor sof-rt5682.conf）" + else + echo "(未备份 vendor sof-rt5682.conf，不生成 system-overlay.tar.gz)" + fi +} + +write_manifest +backup_vendor_ucm +backup_user_wireplumber +pack_system_overlay + +TOPO="$STASH/topology.txt" +echo "正在调用 collect_linux_audio_topology.sh -> $TOPO" +bash "${REPO_ROOT}/audio_topology/collect_linux_audio_topology.sh" "$TOPO" + +echo "" +echo "========== 基线已写入: $STASH ==========" +echo " manifest.txt — 包状态与 deb 路径清单" +echo " topology.txt — 完整音频拓扑" +echo " system-overlay.tar.gz — 若存在：vendor sof-rt5682.conf 快照" +echo " user-wireplumber-conf.tar.gz — 若存在：用户 kaisa WirePlumber 片段" +echo "" +echo "恢复至「尽量接近本次采集时」的系统文件状态：" +echo " ./scripts/restore-ubuntu-audio-baseline.sh $STASH" +echo "" +echo "若曾启用 §4.3 user systemd 自动 restore，恢复基线前可先禁用该 user 单元（见 OPERATION）。" diff --git a/scripts/restore-ubuntu-audio-baseline.sh b/scripts/restore-ubuntu-audio-baseline.sh new file mode 100755 index 0000000000..87c9791bd8 --- /dev/null +++ b/scripts/restore-ubuntu-audio-baseline.sh @@ -0,0 +1,80 @@ +#!/usr/bin/env bash +# 将系统尽量恢复到某次 capture-ubuntu-audio-baseline 采集时的「安装 deb 前」文件状态。 +# 典型：purge kaisa-hdmi-pipewire-fix → reinstall alsa-ucm-conf → 可选解压备份 tar。 +# 用法：./scripts/restore-ubuntu-audio-baseline.sh [基线目录] +# 若不传参数，使用 audio_topology/baseline-stash/ 下最近修改的子目录。 +# 需要：sudo（apt、解压到 /）；建议在桌面会话下执行以便重启 PipeWire。 +set -euo pipefail + +REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" + +resolve_stash() { + if [[ -n "${1:-}" ]]; then + realpath "$1" + return + fi + local latest + latest="$(ls -td "${REPO_ROOT}/audio_topology/baseline-stash"/*/ 2>/dev/null | head -1 || true)" + if [[ -z "$latest" ]]; then + echo "未找到基线目录。请先运行: ${REPO_ROOT}/scripts/capture-ubuntu-audio-baseline.sh" >&2 + exit 1 + fi + realpath "${latest%/}" +} + +STASH="$(resolve_stash "${1:-}")" + +if [[ ! -f "$STASH/manifest.txt" ]]; then + echo "不是有效基线目录（缺少 manifest.txt）: $STASH" >&2 + exit 1 +fi + +echo "========== 使用基线: $STASH ==========" +echo "manifest 创建于:" +head -5 "$STASH/manifest.txt" +echo "" + +if ! command -v sudo &>/dev/null; then + echo "需要 sudo 以执行 apt。" >&2 + exit 1 +fi + +if dpkg -s kaisa-hdmi-pipewire-fix &>/dev/null; then + echo ">>> apt purge kaisa-hdmi-pipewire-fix" + sudo apt purge -y kaisa-hdmi-pipewire-fix +else + echo "(未安装 kaisa-hdmi-pipewire-fix，跳过 purge)" +fi + +echo ">>> apt install --reinstall alsa-ucm-conf" +sudo apt install --reinstall -y alsa-ucm-conf + +if [[ -f "$STASH/system-overlay.tar.gz" ]]; then + echo ">>> 解压 system-overlay.tar.gz -> /（覆盖 vendor sof-rt5682.conf，与 reinstall 通常等价）" + sudo tar -xzf "$STASH/system-overlay.tar.gz" -C / +else + echo "(无 system-overlay.tar.gz，仅依赖 alsa-ucm-conf reinstall)" +fi + +if [[ -f "$STASH/user-wireplumber-conf.tar.gz" ]]; then + echo ">>> 解压 user-wireplumber-conf.tar.gz -> ${HOME}/.config/wireplumber/wireplumber.conf.d/" + mkdir -p "${HOME}/.config/wireplumber/wireplumber.conf.d" + tar -xzf "$STASH/user-wireplumber-conf.tar.gz" -C "${HOME}/.config/wireplumber/wireplumber.conf.d" + echo "已恢复用户 WirePlumber 片段。" +else + echo "(无 user-wireplumber-conf.tar.gz，跳过用户配置)" +fi + +if systemctl --user is-system-running &>/dev/null; then + echo ">>> systemctl --user restart wireplumber pipewire pipewire-pulse" + systemctl --user restart wireplumber pipewire pipewire-pulse 2>/dev/null || { + echo "（user 会话重启 pipewire 失败，请手动重登或重启）" >&2 + } +else + echo "（无可用 user systemd 会话，请登录图形界面后执行: systemctl --user restart wireplumber pipewire pipewire-pulse）" +fi + +echo "" +echo "========== 恢复步骤已完成 ==========" +echo "若曾启用登录自动 restore（user systemd），恢复前可先禁用 kaisa-hdmi-iec958-pipewire 单元（见 OPERATION §4.3 / §4.5）。" +echo "建议核对: pactl list cards | head -40 ; aplay -l"