@hmos-library-adapter/fast 0.0.17-beta.1 → 0.0.17-beta.2

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/capability-domains/usb-host.md

@@ -0,0 +1,82 @@
+# 能力域：usb-host（USB 主机通信）
+
+## 能力描述
+
+作为 USB 主机枚举/读写 USB 设备：JTAG/SWD 调试探针（ST-Link / J-Link / DAPLink）、HID 设备、
+大容量存储等。PC 上由 libusb / hidapi（Linux 走 usbfs `/dev/bus/usb`，Windows 走 WinUSB，macOS 走 IOKit）提供。
+
+**典型触发**：依赖里出现 `libusb-1.0` / `hidapi`，或源码里有 `libusb_init` / `hid_init` /
+`libusb_open` 调用。
+
+## 鸿蒙状态：partial（编译链路 available，app 域不可达，DDK 桥接待实施）
+
+| 子能力 | 状态 | 说明 |
+|---|---|---|
+| 原生 USB DDK | available | NDK 提供 `usb_ddk_api.h`（`OH_Usb_*` 17 个 API）+ `libusb_ndk.z.so`（Init/Release/GetDevices/ClaimInterface/SendControlReadWriteRequest/SendPipeRequest 等）；`hid_ddk_api.h` + `libhid.z.so`（`OH_Hid_Init/Open/Read/Write/EmitEvent` 等）；`libusb_serial_ndk.z.so`（`OH_UsbSerial_*` 串口 DDK） |
+| libusb/hidapi 中心仓适配版 | **⚠️ 仅 compile-time** | 中心仓 `libusb/1.0.27` 经符号级核实（`llvm-nm` + `.rodata` 字符串）确认为 **Linux usbfs 后端**：打开 `/dev/bus/usb/%h` 等设备节点 + `ioctl(USBDEVFS_*)`，**非** USB DDK 后端。`.rodata` 含 `usbfs_scan`/`usbfs_get_fd`/`found usbfs at` 等字符串，undef 含 `open`/`ioctl`/`statfs`/`readlink`，无任何 `OH_Usb_*` 符号。交叉编译可产出签名的 `.so` 但 app 域无法访问 `/dev/bus/usb` → **功能不可用**。hidapi/0.14.0 同理为 usbfs 后端。需要物理 USB 探针的用例需 DDK 后端。 |
+| hdc shell 域访问 | unavailable | 实测 hdc shell 域无法访问 `/dev/bus/usb` |
+| usbfs 后端 app 域 | **unavailable** | app 域沙箱 SELinux + mount namespace 禁止访问 `/dev/bus/usb` 设备节点。实测（usbredir 0.15.0，HAD-W32 / OpenHarmony-6.1.1.135）：`libusb_init(NULL)` 返回 **-99**（非标准 LIBUSB_ERROR 枚举值），`libusb_get_device_list` 可调用但返回空。依赖 libusb 的 glib g_test 二进制应在 init 失败时 `g_test_skip` 提前 return 而非 `g_test_fail`——子测试全 SKIP 且二进制 rc=0 是预期行为 |
+| 社区开源层 | **空仓（无实质代码）** | 仅含 README，无 libusb API 兼容的 DDK 后端包装代码 |
+
+## 替换方案
+
+**交叉编译链路复用中心仓适配版 `libusb`/`hidapi`（Conan 拉取，免自编）**——这只适用于 cross-compile 连通性验证（编得出 .so）、hdc shell 域跑 libusb 测试（如 `libusb_init` 返回 0），以及 CLI 工具在无 USB 时的降级模式验证。**app 域端到端 USB 通信必须走 DDK 后端**（见下文）。
+
+**DDK 后端（唯一正路）**：无现成 libusb API 兼容层（社区仓库空仓），需自研桥接层——写一个导出 `libusb-1.0` 公共 API 子集的 `.so`，内部实现走 `OH_Usb_*` DDK API。已有适配评估：
+
+| 维度 | 评估结论 |
+|------|---------|
+| 同步 API 映射面 | ~80%（init/get_device_list/get_device_descriptor/open/close/claim_interface/control_transfer/bulk_transfer。评估文档 `build/usb-ddk-evaluation/api-mapping.md`） |
+| 异步退化 | libusb `handle_events`/`submit_transfer` 的异步路径需基于 DDK `SendPipeRequest` 的同步语义加线程池模拟 |
+| API 缺口 | `set_configuration`、`detach_kernel_driver` 无 DDK 等价物 |
+| 前置权限 | `ohos.permission.ACCESS_DDK_USB`（system_basic 级）+ 运行期 `usbManager.requestRight` 用户授权 |
+| 编译方式 | NDK clang `--target=aarch64-linux-ohos --sysroot=<ndk>/sysroot -shared -fPIC`，与中心仓 `libusb-1.0.so` 同名覆盖，应用程序无代码改动 |
+
+## 可行性影响
+
+*注意：这里的分档条件适用于「库里用到了 libusb/hidapi/usb_ddk_api.h 做 USB 通信」的场景。如果只是依赖声明但实际可选（`find_package` 非 REQUIRED、运行时 `libusb_init` 失败有降级路径），则影响降低。*
+
+### 场景 A：CLI 工具，libusb 非核心路径（推荐优先走降级模式）
+CLI 工具若只需参数解析/TCP 服务/格式校验等非 USB 功能可用，**优先走降级模式**：
+- 将 `parse_opts()` 提前到 `libusb_init()` 之前
+- libusb_init 失败非致命（降级为 `have_usb=FALSE`）
+- 用守卫保护 USB 依赖段
+- 详见 `pc-knowledge-base/platform/鸿蒙PC-CLI工具main函数平台能力检查降级模式.md`
+- **实证**：USB 重定向工具与调试探针类 CLI（均 2026-09 实证）均采用此模式，TCP 服务/解析等在无 USB 时完整可用
+- **库侧的降级构造路径同样存在**：`usbredirhost_open(NULL, NULL)`（空 libusb 上下文 + 空设备句柄）直接成功，不需要 `libusb_init`——实例生命周期、hello 报文、客机数据读写、`set_device(NULL)` 断开全由 parser 持有，均可在 app 域验证（usbredir 0.15.0 第二轮实证，2026-09-17）。别把 host 库的用例整个挂在 `libusb_init` 成功上
+
+### 场景 B：核心功能依赖 libusb（调试探针、烧录器等）
+必须走 DDK 后端，且需要：
+1. 自行完成 `libusb→OH_Usb_*` 桥接层
+2. 物理 USB 调试探针 + 目标板
+3. app 域的 `ACCESS_DDK_USB` 权限 + `requestRight` 授权
+4. 签名 HAP 在零售机上验证
+
+## 判定要点（scan 阶段）
+
+1. 命中本域 ⇒ `harmony_status: partial`、`replacement: 中心仓 libusb/hidapi 适配版编译复用 + DDK 桥接层自研（app 域运行时唯一正路）`、
+   `solution_source: builtin-asset`、`asset_ref: pc-capability-domains/usb-host.md`。
+2. 依赖 libusb-1.0/hidapi 的库：deps 闭包节点走 `reuse`（中心仓 Conan 命中），不重编。但 scan 须在 `notes` 注明中心仓适配版为 usbfs 后端，app 域运行时需 DDK 桥接子层。
+3. 若库为主干依赖 libusb（非可选）：feasibility 应考虑降级（`needs_adaptation_partial` / `feasible_with_effort`），在 `capability_dependencies` 中明确标记。
+4. **硬件路径必须显式进 `prd.scope_out`**（写清哪条路径、待 DDK 桥接）：不收编又不肯判 partial，验收规则 `scope-out-coverage-consistent` 会拦「target_path_covered=covered」——同一限制曾因 scope_out 留空被判 partial、收编后判 success（usbredir 0.15.0 两轮对照，2026-09）。物理 I/O 出范围后，host 库用例按场景 A 的降级路径设计（见上），不再 blocked。
+
+## 典型库
+
+调试探针类 CLI（libusb/hidapi 复用中心仓，DDK 桥接已完成评估）、dfu-util、pyusb/hidapi Python 绑定、
+USB 重定向工具（已采用降级模式）。
+
+## 适配实证
+
+### 模式 A：降级模式（`main()` 结构可重构类）
+
+工具的 `main()` 在 `parse_opts()` **之前**调用 `libusb_init(NULL)`，导致在 HAP 应用域（USB 设备访问不可达）下所有 CLI 功能（参数解析、TCP 连接、设备标识校验）被阻塞。
+
+**解法**：将 `parse_opts()` 提前到 `libusb_init()` 之前，使 `libusb_init` 失败非致命（降级为 `have_usb=FALSE`），用守卫保护 USB 依赖段。详见 `pc-knowledge-base/platform/鸿蒙PC-CLI工具main函数平台能力检查降级模式.md` 的通用模式。
+
+**验证**：交叉编译通过（`-Werror` 零告警），降级模式下 TCP 连接/监听、设备标识解析等不依赖 USB 的功能可正常测试。
+
+### 模式 B：DDK 桥接层（libusb 调用分散不可降聚类）
+
+中心仓 `libusb/1.0.27` 为 usbfs 后端（符号级核实），在 hdc shell 域和 app 域均不可访问 `/dev/bus/usb`。但此类工具的 dummy 适配器、TCP 远程服务、非 USB 核心功能可离线编译并完整验证。
+
+**DDK 评估**：`build/usb-ddk-evaluation/` 三文档系统评估了 libusb→OH_Usb_* 桥接的 API 映射（~80% 同步面可映射）+ 权限需求（system_basic + requestRight）+ 前置条件。结论：DDK 桥接是 app 域 USB 通信的唯一正路，但无现成 libusb 兼容层，需自研 + 物理探针验证。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/requirements/R001.kv

@@ -0,0 +1,14 @@
+# 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。
+id:                     R001
+title:                  gstreamer 运行时插件缺失（appsrc / playbin / audio sink）导致播放链路不可用
+category:           audio
+severity:               2
+status:                 open
+affected_software:      pianod2
+description:            制品仓 gstreamer/1.28.3 配方只发布核心静态库（libgstreamer/gstbase/gstcontroller/gstnet/gstcheck），不含插件 .so 与 plugin registry；pianod2 运行期报 'gst_element_factory_make: Element factory returned null pointer: appsrc'，因此解码/输出链路无法建立，仅服务与元数据层可用
+needed_capability:      gstreamer-plugins-base（appsrc/appsink/playbin3 依赖）+ good（alpha/volume/…）+ 至少一个 OHOS 音频 sink（如 pipewire/alsa 适配插件）与 gst-plugin-scanner 生成的 registry
+current_workaround:     pianod2 可先以 filesystem 元数据/服务/协议功能交付；播放需等 gstreamer 插件包发布，或改走 ffmpeg 引擎 + libao/libsdl 输出（需先适配 libao）
+created_date:           2026-09-15
+closed_in_version:      
+closed_date:            
+contributors:           unknown

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/requirements/R002.kv

@@ -0,0 +1,14 @@
+# 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。
+id:                     R002
+title:                  OHOS 生态缺少 AT&T ksh93 解释器，ksh 脚本类工具无法运行
+category:               shell
+severity:               3
+status:                 open
+affected_software:      pianod2
+description:            pianod2 的 piano 客户端与 runmix 排程工具是 #!/bin/ksh 脚本，依赖 ksh93 内建 getopts -、print、whence 与 $'...' 语法；OHOS 无 /bin/ksh，cmd-pkgs 仅提供 dash 0.5.12 与 zsh 5.9（两者都不兼容 ksh93 特性）。上游 pianod_unittest 集成测试同样因缺少 ksh93 只能 SKIP（脚本自带 exit 77 守卫）
+needed_capability:      ksh93（或 AT&T ksh v93u+）OHOS aarch64 构建包，安装后提供 /bin/ksh
+current_workaround:     服务与 Web 客户端、4445 行协议、JSON/WebSocket 控制路径不受影响；命令行客户端需改写为 POSIX sh 或改用协议直连
+created_date:           2026-09-15
+closed_in_version:      
+closed_date:            
+contributors:           unknown

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/requirements/_template.kv

@@ -0,0 +1,21 @@
+# 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。
+#====================================================================
+# _template.kv — 需求图谱条目模板
+#
+# 跟踪鸿蒙PC平台缺失的系统能力。当系统支持后标记为closed。
+# 生命周期: 预分析/编译/测试发现缺失 → add → open → 系统支持 → close → closed
+#====================================================================
+
+id:                     R{NNN}
+title:                  简短描述缺失的能力
+category:               graphics|audio|video|ipc|filesystem|shell|toolchain|syscall|network|security|signing|runtime|other
+severity:               1-3 (1=低 2=中 3=高，影响核心功能)
+status:                 open|closed
+affected_software:      软件名或*（多个用逗号分隔）
+description:            详细描述缺失的能力和影响
+needed_capability:      需要的具体API/接口/命令行工具
+current_workaround:     当前变通方案（无则留空）
+created_date:           YYYY-MM-DD
+closed_in_version:      系统支持该能力的版本号（关闭时填写）
+closed_date:            YYYY-MM-DD（关闭时填写）
+contributors:           贡献者（多个用逗号分隔）

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/solutions/ohaudio-backend/PORTING_NOTES.md

@@ -0,0 +1,123 @@
+# NAPI 壳：其他音频库怎么接
+
+本项目只面向**零售/不可调试机**，所有 OHAudio 交付都是同一条路：**签名 HAP 的 NAPI 模块内
+dlopen（LOAD 不 EXEC）**，不 exec 独立二进制。本文件的接入点针对这个机制。
+
+## 骨架（所有库都一样）
+
+一个签名 HAP 的原生模块（NAPI，ArkTS `import '<mod>.so'` 触发）：
+
+```
+RunTool(filesDir):
+  1. dlopen 解码端库 + dlsym 所需符号；dlopen("libohaudio.so") + dlsym 16 个 OH_Audio* 符号
+  2. OH_AudioStreamBuilder:  TYPE_RENDERER, S16LE, 2ch, 48000, RAW, USAGE_MUSIC,
+                             SetRendererWriteDataCallback(回调, NULL), GenerateRenderer, Start
+  3. 把宿主音频库的"推音频"接进 pthread 环形缓冲（producer=解码线程，consumer=OHAudio 回调）
+  4. 收尾: 排空 ring → Renderer_GetFramesWritten → Stop/Release/Destroy
+  5. 证据打 hilog（tag 固定）→ 誊入 build/audio-verify.json（gate 必查）
+```
+
+判据四证合一：`dlopen 16/16` + `stream_id ≠ 0` + `bytes_pushed==bytes_delivered` + `frames_written>0`。
+
+## 各库接入点（差异只在"解码端长啥样"）
+
+| 库 | 要做什么 | 要点 |
+|---|---|---|
+| **liba52 / libao**（已实证） | dlopen liba52.so.0 + a52 解码；libohaudio dlopen | `liba52/` 实例已记录，直接照抄 |
+| **libout123 / out123 / libao**（已实证） | **写一个输出模块**（`ohaudio.c` → `output_ohaudio.so`），库运行时按 `MPG123_MODDIR`/`AO` 的模块目录 dlopen 加载——**不改 NAPI 壳 wiring** | 见下方「自带 module/backend loader 的库」专节 + `libout123/` 实例 |
+| **OpenAL-Soft** | NAPI 壳里 `dlopen("libopenal.so")` + `dlopen("libohaudio.so")`；把 OHAudio 后端跑在 NAPI 线程 | 后端本体（OHAudio dlopen + renderer）用本资产 README 的 oha_api_t 模式实现，差异只是把 openal 的 backend open/reset/start/stop 接到 NAPI 线程 |
+| **PortAudio** | NAPI 壳里建 `Pa_*` host API 线程 + OHAudio renderer | 回调式 host API 与 OHAudio 天然对齐 |
+| **SDL_audio** | NAPI 壳里 `SDL_OpenAudioDevice` 回调 + OHAudio | SDL 拉模型 → 在 OHAudio 回调里调 SDL mixer |
+| **miniaudio** | NAPI 壳里 `ma_device_init` + OHAudio custom backend | 有 custom 钩子，最省事 |
+| **RtAudio** | NAPI 壳里 `RtApi` 子类 + OHAudio | 参考 RtApiOss/RtApiPulse 结构 |
+
+> **共同的坑**：这些库的二进制必须作为模块 **dlopen**（decoder 侧）或链接进 NAPI 模块
+> （`entry/libs/arm64-v8a/` + CMake target），**不要做成 exec 的独立 ELF**——那有撞零售机 exec
+> 签名墙（liba52 在 HiShell 桌面 + 私有 HNP 两处实证 EPERM/127）。
+
+## 自带 module/backend loader 的库（更省事，已实证：libout123）
+
+有些库**本身就带输出后端/插件加载器**（libout123 的 `mpg123_module_t` · libao · gstreamer
+元素 · SDL audio driver · OpenAL-Soft backend）。这类库**不要**再写"NAPI 壳 dlopen 解码库 →
+喂 OHAudio"那套手动 wiring——**写一个 OHAudio 输出模块，让库自己 dlopen 它**：
+
+- 模块就是一个 `mpg123_module_t` 结构体 + 一组回调（`open/write/flush/drain/close/enumerate/
+  get_formats/deinit`），内部起 OHAudio renderer + ring buffer。完整模板见 `libout123/`。
+- 编译**单独走 clang 直调，不进 CMake 目标**（mpg123 的三库/CLI 走 CMake，但输出模块是另一条
+  编译路径）：
+
+  ```sh
+  "$NDK/llvm/bin/clang" -target aarch64-linux-ohos --sysroot="$NDK/sysroot" \
+    -D__MUSL__ -fPIC -shared -lohaudio -lm -o dist/modules/output_ohaudio.so \
+    patches/src/libout123/modules/ohaudio.c
+  ```
+
+- 运行时库按环境变量（libout123 用 `MPG123_MODDIR`）指向模块目录，`dlopen` 加载 `.so` 并调
+  `init_output` 接线。选默认模块可用 `-DDEFAULT_OUTPUT_MODULE=ohaudio`。
+- **模块源码通常上游已 in-tree**（mpg123 的 `ohaudio.c` 在 madebr fork `libout123/modules/`
+  已存在），`patches/` 与 `source/` 内容一致 ⇒ **零补丁**，只补一条"单独编译"命令。
+- 判定要点：`out123 --list-modules` 能枚举出 `ohaudio`（输出驱动列表含 `dummy/ohaudio/raw/...`），
+  即运行时 dlopen 成功；再配合 `build/audio-verify.json` 四证（README §达标判据）证实出声。
+
+## 自带输出后端注册表的库（源码内后端，2026-09 实证）
+
+库源码内自带**编译期输出后端注册表**（后端是源码文件 + 注册表数组/特性开关，无运行时模块
+loader——media framework 的 audio output driver 表是典型）。这类库**不要** NAPI 壳、也不要外部
+模块——**写一个源码内 OHAudio 后端文件，经构建系统编进库本体**：
+
+1. **后端文件（pull 模型，照库内同类回调式后端抄骨架）**：
+   - init：`OH_AudioStreamBuilder_Create(TYPE_RENDERER)` → Set 采样率 / 通道数 /
+     `AUDIOSTREAM_SAMPLE_S16LE` / `AUDIOSTREAM_ENCODING_TYPE_RAW` /
+     `AUDIOSTREAM_LATENCY_MODE_NORMAL` / `USAGE_MUSIC` →
+     `SetRendererWriteDataCallback(cb, ctx)`（+ `SetRendererErrorCallback`）→
+     `GenerateRenderer`；格式固定 S16LE，通道超 2 收敛到立体声，采样率钳 8000–192000；
+   - 写数据回调（库音频线程被平台回调）：调**库的核心供数口**拉一段 PCM 填进回调给的缓冲，
+     返回 `AUDIO_DATA_CALLBACK_RESULT_VALID`；供数口的结束时间用「本段帧数 / 采样率」估；
+   - pause/resume/reset → `Pause` / `Start` /（`Pause`+`Flush`，Flush 必须在非 RUNNING 态）；
+   - **uninit 必打机器判据行**：`GetFramesWritten` 取 renderer 写帧数，打
+     `ohos: frames written: N` → `Stop`/`Release`/`Destroy`。runner 侧 grep「后端加载行 +
+     N > 0」即机器判定（对应本资产 README 四证的第 4 证；N>0 隐含 renderer 被音频系统接受）。
+2. **构建系统接线**（meson 为例，CMake 同理）：新增 feature 选项 →
+   `find_library('ohaudio', required: get_option(...))`（NDK sysroot 的
+   `usr/include/ohaudio/` + `usr/lib/aarch64-linux-ohos/libohaudio.so` **完整在位**，交叉构建
+   直接 found）→ 源文件登记 → **驱动注册表插行**（排在 dummy/null 类后端**之前**，注册表通常
+   以特殊后端截断）。重建后 `readelf -d` 核对 `libohaudio.so` 进了产物 DT_NEEDED。
+3. **执行通道**：CLI 二进制（直接链接 libohaudio.so）经**执行器 HAP fork+execv**
+   （cli-hnp-runner / 私有 HNP）真跑——renderer 初始化成功、真写帧 > 0
+   （2026-09，6.1 级平台实证）。与上面 NAPI 壳路线的旧结论（exec 三路被拒）不矛盾：那是更老
+   的 6.0 级零售机；换设备先复核设备指纹，别拿旧结论裁新设备。
+4. **测试接线注意**：若该库另有「截图/取帧到内存」类**命令式 API**，其结果经调用同步返回，
+   别等属性事件（pc-test-design §九红线）；命令注册表/属性表以 `file:line` 实证后写用例。
+
+## 通用坑（与库无关）
+
+1. **解码库优先 dlopen 不进 NEEDED**：`dlopen("liba52.so.0")` + `.so` 随 HAP libs/ 分发。链接进
+   NEEDED 也行（App 加载模块可解析），但自建 .so 直连 lld 可能遇 `undefined symbol ... defined
+   in: <自建.so>` 解析怪癖——用 dlopen 绕开最稳。
+2. **测试音频文件不依赖文件 IO**：把 AC-3/WAV 样本内嵌进原生模块（生成 C 字节数组），或经
+   rawfile 读 → ArkTS 写 files dir → 传路径给 runTool。避免依赖 App 沙箱外路径。
+3. **测试样本/夹具要提前备齐，缺失只记 blocked 不是库 bug**（mpg123 实证）：Layer I/II 解码
+   功能点（F-01-14）因没有 mp1/mp2 样片、HTTP 网络流（F-04-02）因没有可访问的流媒体地址而
+   blocked——这两条都是夹具缺口，不是能力缺口。跨库重用的样本集：`sweep.mp3`（Layer III）+
+   `layer1-sample.mp1` + `layer2-audiotest.mp2`；HTTP 流用本地 `http-serve/` 起一个静态文件
+   server（`python -m http.server` 或等价），把 mp3 丢进去即可验证 socket+HTTP 解码链路。
+4. **renderer 用量 `AUDIOSTREAM_USAGE_MUSIC`**：`AUDIOSTREAM_USAGE_MEDIA` 在部分 SDK 头里不存在。
+5. **4KB 页对齐**：NAPI 模块 link options 加 `-Wl,-z,max-page-size=0x1000`。
+6. **回调周期回读实测值**：`OH_AudioRenderer_GetSamplingRate` 回读实际采样率写回解码端，
+   请求值可能不被满足，不回写会变调。
+7. **采集另说**：需 `ohos.permission.MICROPHONE`；没验证过就如实声明不支持，别给成功空壳。
+8. **转交织 S16 的样本布局**：liba52 `a52_samples` 是**通道主序** `[L0..L255,R0..R255]` →
+   `s16[2i]=f[i], s16[2i+1]=f[i+256]`。**aarch64 主机即 LE，无需字节翻转**（WAV 的 `s16_LE`
+   在 LE 主机是 no-op）。
+
+## 验证载体
+
+打包：`ohpt-agent scaffold --kind cli-hnp-runner`（改造成 NAPI 壳）或手工 hvigor 构建 HAP →
+`ohpt-agent sign-demo --install` → `aa start` → `hilog -x | grep <tag>` → 誊 `build/audio-verify.json`。
+注意：**cli-hnp-runner 模板默认是 private-HNP exec 路线**，零售机上那条 HNP 装不上（liba52 实证）；
+用它时删掉 `hnpPackages`，只留 entry 工程，把用例放进原生模块的 dlopen 逻辑。
+**反向提醒（2026-09 实证）**：6.1 级平台上 private-HNP exec 路线整条可用（HNP 正常装机、CLI 正常
+exec、直连 libohaudio.so 真写帧）——设备不同结论相反，装机失败先看错误码分档
+（`pc-knowledge-base` 的「HAP 调试签名与设备安装信任链」），别跨设备照搬结论。
+另外 `sign-demo` 给非默认 demo 目录签名时**必须显式传 `--demo-dir`**，否则读到默认工程的
+bundleName → 9568329 验签失败（E164 根因三，专文见同目录知识库）。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/solutions/ohaudio-backend/README.md

@@ -0,0 +1,76 @@
+# OHAudio 后端方案资产（NAPI 壳 · LOAD 不 EXEC · 零售机）
+
+把 C/C++ 音频库在鸿蒙 PC（**零售/不可调试机**，uid2000、无 root、无 DevBox/公共 HNP）上接到
+系统音频的**方案本体**。本项目只面向零售机，**不存在可调试机路线**——所有音频域交付都走本资产
+的 NAPI 壳机制。
+
+实测设备：鸿蒙 PC **零售不可调试机**（HAD-W24 **6.0.0.130**，`hdc shell id` = `uid=2000(shell)`，
+API 22），2026-09-02 liba52 案例全链路实证 **6/6 通过**（stream_id=100028，frames_written=53496）。
+
+## 为什么必须 NAPI 壳（LOAD 不 EXEC）
+
+零售机上 exec 任何含 OHAudio 后端的**独立可执行文件**都会被 exec 签名墙拒绝：
+
+| 路径 | 结果 |
+|---|---|
+| HiShell 桌面工作区 exec 自签独立二进制 | **EPERM/127**（`hmdfs`/`data_local_tmp` 标签全拒） |
+| 私有 HNP（`hnpPackages type=private` + 签名 HAP）exec | **EPERM/127**（私有 HNP 装不上，`/data/app/bin` 符号链接农场不存在） |
+| **签名 HAP 的 App 域 `dlopen`（LOAD 不 EXEC）** | ✅ **全链路真跑通** |
+
+同样二进制 exec 被拒、dlopen 就通——**根因是交付机制不是 OHAudio API**：零售机 XPM/签名层拒绝
+"exec 自签名 ELF"，但允许签名 HAP 应用的进程在 App 域加载库。所以把解码端从"独立可执行文件"
+换成"HAP 内 NAPI 模块 + dlopen"，即绕开 exec 签名墙。
+
+## 方案本体（liba52 实证，直接照抄）
+
+一个**签名 HAP** 的原生模块（ArkTS `import 'xxx_demo.so'` 即拉起）做四件事：
+
+1. **dlopen 解码库**：`dlopen("liba52.so.0")` 等，`.so` 随 HAP `entry/libs/arm64-v8a/` 分发，
+   App 加载时与 `libc++_shared.so` 同路解析；`dlsym` 解析所需符号（`a52_syncinfo/init/frame/block/...`）。
+   **不链接进 NEEDED**——绕开 lld 对自建 .so 的 `undefined symbol ... defined in:` 解析怪癖，
+   且让 NAPI 模块 NEEDED 保持最小。
+2. **dlopen OHAudio**：`dlopen("libohaudio.so")`（在 `/system/lib64/ndk/`，默认加载路径无需
+   `LD_LIBRARY_PATH`），`dlsym` 解析 16 个 `OH_Audio*` 符号。**dlopen 模式是硬要求**：接受
+   `OH_AudioStreamBuilder_*` / `OH_AudioRenderer_*` 函数指针接口，不直接用头文件声明的符号。
+3. **起 renderer**：`OH_AudioStreamBuilder_*` 建 `AUDIOSTREAM_TYPE_RENDERER`（S16LE / 2ch /
+   48000，`AUDIOSTREAM_ENCODING_TYPE_RAW`，`AUDIOSTREAM_USAGE_MUSIC`），
+   `SetRendererWriteDataCallback` 挂**回调拉取**，`GenerateRenderer` → `Renderer_Start`。
+4. **喂音频**：解码线程把交织 S16LE 推进 pthread 环形缓冲（producer），回调从 ring 拉消费
+   （consumer，ring 空补零）；收尾置 eof → 等排空 → `Renderer_GetFramesWritten` → `Stop/Release/Destroy`。
+
+完整的可运行实例见 `liba52/`（napi 壳源码要点 + 证据原文），以及 liba52 适配工作区的
+`audio-hnp-runner/entry/src/main/cpp/napi_stub.cpp`。
+
+## 达标判据（四证合一，写进 build/audio-verify.json）
+
+命中 audio 域的交付，`gate`/`acceptance-checks` 要求**必须捕获 `build/audio-verify.json`**
+（`audio-output` 档，`DOMAIN_EVIDENCE` 表）。零售机 NAPI 壳版本四证缺一不可，全部取自设备
+hilog（`hilog -x | grep <tag>`）后誊入该文件：
+
+| 判据 | 证据串 | 含义 |
+|---|---|---|
+| 后端接通 | `OHAUDIO_LOAD: OK (resolved 16/16 OH_Audio* symbols)` | dlopen libohaudio.so + 全符号解析 |
+| renderer 真拿到 | `OHAUDIO_SETUP: GenerateRenderer=0 renderer=non-null stream_id=<非0> Start=0` | 音频系统真分配流、renderer 启动成功 |
+| **全量 PCM 命中渲染** | `bytes_pushed == bytes_delivered`（liba52: 196608 == 196608） | 解码的每个字节都被回调消费，非半截入局 |
+| **真写帧** | `OHAUDIO_CLOSE: frames_written > 0`（liba52: 53496） | renderer 实际从设备音频管线写出帧 |
+
+> ⚠️ **别只看"播放没报错"**：判据必须含 `frames_written > 0` 且 `stream_id ≠ 0`（0 = renderer
+> 没被音频系统接受）。`frames_written` 通常 ≥ 解码总帧（启停期回调补零），只要
+> `bytes_delivered == bytes_pushed` 即真音频全量送达，多余帧是静音补齐，属正常。
+> 另需一证：解码端 `frames_ok == 素材帧数` 且 `crc_fail == 0`（liba52: 32/32，0 CRC 失败）。
+
+## 已验证场景与局限
+
+- ✅ **播放（渲染）**：liba52 真实 AC-3（57344B，32 帧）→ dlopen liba52.so.0 解码 → 196608B
+  全量交付 → `frames_written=53496`，6/6 通过。App 域无需任何音频权限（`ohos.permission` 无）。
+- **采集（录制）**：本资产未覆盖。采集需 `ohos.permission.MICROPHONE`（SDK 声明），权限模型与播放不同。
+- **多声道**：实证范围为立体声（2ch / S16LE / 48000）。
+- **低延迟**：`AUDIOSTREAM_LATENCY_MODE_NORMAL` 实测通过；SDK 另有 `_FAST` 档。
+
+## 目录
+
+| 文件 | 内容 |
+|---|---|
+| `PORTING_NOTES.md` | 其他音频库（OpenAL/PortAudio/SDL_audio/miniaudio/RtAudio）怎么接同一个 NAPI 壳 |
+| `liba52/` | liba52 零售机实例：验证记录、证据、napi 壳要点（照抄模板） |
+| `libout123/` | libout123 实例：**自带 module loader 的库**怎么写 OHAudio 输出模块（照抄模板） |

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/solutions/ohaudio-backend/liba52/evidence.md

@@ -0,0 +1,61 @@
+# liba52 零售机 OHAudio NAPI 壳实例（2026-09-02 实证）
+
+## 设备与产物
+
+- 设备：鸿蒙 PC **零售不可调试机** HAD-W24 6.0.0.130（`hdc shell id` = uid2000, API22, aarch64）
+- 被测库：liba52（AC-3 解码）+ libao（含 OHAudio 后端），交叉编译 `aarch64-linux-ohos`
+- 载体：签名 HAP `com.ohospc.a52audio`，原生模块 `liba52audio_demo.so`（NAPI runTool）
+- 解码素材：`test_real.ac3`（ffmpeg 生成，57344B，32 帧，BSID8 立体声，内嵌为 C 字节数组）
+
+## 死路（同设备上被拒，勿再走）
+
+| 路径 | 结果 |
+|---|---|
+| exec 含 OHAudio 后端的独立 a52dec（55680B，`--code-sign`，HiShell 桌面工作区）| EPERM/127 |
+| 同上经私有 HNP（`hnpPackages type=private`，签名 HAP 安装 → `/data/app/bin` 符号链接落地）| rc=127（**HNP 根本装不上**：`/data/app/bin` 农场不存在）|
+| 对照：同路径 exec plain a52dec（47488B 无 OHAudio）| **同样 rc=127**（坐实是 exec 通道问题，非 OHAudio 内容）|
+
+## 正路（本次通过）
+
+```
+签名 HAP 原生模块内：
+  dlopen("libohaudio.so")        → 16/16 OH_Audio* 符号
+  dlopen("liba52.so.0")          → 7 个 a52_* 符号
+  GenerateRenderer               → 0 (success), stream_id=100028, actual_rate=48000, Start=0
+  解码 32 帧 AC-3                → frames_ok=32 blocks=192 crc_fail=0
+  推 ring → 回调消费             → bytes_pushed==bytes_delivered==196608（全量命中）
+  Renderer_GetFramesWritten      → frames_written=53496
+  TAP: PASS=6 FAIL=0
+```
+
+## 关键实现要点（照抄）
+
+1. `oha_api_t` 结构体 = 16 个 `OH_Audio*` 函数指针 + `oha_load()`（`dlopen("libohaudio.so",RTLD_NOW)`
+   + dlsym 16 个符号并计数），是 NAPI 壳的标准打开方式，照抄即可。
+2. 解码库同样 dlopen：`a52_api_t`（syncinfo/crc/init/frame/block/samples/free 7 指针）+
+   `dlopen("liba52.so.0")`；**liba52.so.0 拷进 HAP `entry/libs/arm64-v8a/`**，App 加载时与
+   libc++_shared.so 同路解析。
+3. 采样率/声道：`AUDIOSTREAM_SAMPLE_S16LE`、2ch、48000。liba52 的 `a52_samples` 是
+   通道主序 `[L0..L255,R0..R255]` → 用 `s16[2i]=f[i], s16[2i+1]=f[i+256]` 转交织 S16。
+   **aarch64 主机即 LE，无需字节翻转**（`s16_LE` 在 LE 主机是 no-op）。
+4. renderer 是**回调拉取**：解码线程（producer）把交织 S16 推 pthread 环形缓冲（256KB），
+   `SetRendererWriteDataCallback`（consumer）从 ring 拉，ring 空时回调补零。
+5. 收尾：置 eof → 等 ring 排空 → `GetFramesWritten` → Stop/Release/Destroy。
+6. 转化证据打 hilog（tag=`liba52run`），宿主 `hdc shell "hilog -x | grep liba52run"` 取回，
+   誊入 `build/audio-verify.json`（gate 必查，判据见 `README.md`）。
+
+## 证据原文（设备 hilog 摘录）
+
+```
+OHAUDIO_LOAD: OK (resolved 16/16 OH_Audio* symbols via dlopen)
+OHAUDIO_SETUP: GenerateRenderer=0 renderer=non-null stream_id=100028 actual_rate=48000 Start=0
+A52_LOAD: OK (7 a52_* symbols via dlopen liba52.so.0)
+DECODE: frames_ok=32 blocks_ok=192 samples_ok=49152 crc_fail=0 ac3_bytes=57344
+OHAUDIO_CLOSE: renderer=non-null callback_count=12 bytes_pushed=196608 bytes_delivered=196608
+               frames_written=53496 remaining_in_ring=0 stream_id=100028
+TAP: PASS=6 FAIL=0 SKIP=0
+```
+
+> 工作区产物（完整源码/脚本/构建链）在 liba52 适配工作区：`audio-hnp-runner/`（NAPI 壳 HAP 工程：
+> `napi_stub.cpp` 主体、`ac3_embedded.c` 内嵌样本）与 `build/ohaudio-backend/audio_out_ohaudio.c`
+> （OHAudio 后端原型：dlopen+ring+回调即 NAPI 壳的实现母本）。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/solutions/ohaudio-backend/libout123/ohaudio-module.md

@@ -0,0 +1,70 @@
+# libout123 输出模块模板（ohaudio 模块 · module-loader 形状 · 零售机实证）
+
+当宿主库**自带输出后端/模块加载器**时（libout123 的 `mpg123_module_t`、libao、SDL audio driver、
+gstreamer 元素），OHAudio 接入不是"NAPI 壳 dlopen 解码库 → 喂 OHAudio"，而是**写一个输出模块，
+让库自己 dlopen 它**。本文件是这条路的照抄模板，mpg123/out123 在零售机 46 条名册全通实证。
+
+## 机制
+
+libout123 运行时按环境变量 `MPG123_MODDIR` 指向的目录 `dlopen("output_<name>.so")`，读模块的
+`mpg123_module_t` 结构体，取其 `init_output` 回调完成接线。模块内部自己起 OHAudio renderer +
+pthread ring buffer（sfifo），push 模型：解码线程 `write()` 推 PCM 进 ring，OHAudio 回调从 ring
+拉。这与 liba52 的 NAPI 壳是**同一套 OHAudio 后端本体**，只是装载方从"NAPI 壳"换成"库的模块加载器"。
+
+## 编译（单独 clang 直调，不进 CMake 目标）
+
+mpg123 的三库/CLI 走 `ports/cmake` 的 CMake，但输出模块是**另一条编译路径**——不带引号的路径
+直调会在 NDK 路径含空格时崩（见 E143/E144）：
+
+```sh
+"$NDK/llvm/bin/clang" -target aarch64-linux-ohos --sysroot="$NDK/sysroot" \
+  -D__MUSL__ -fPIC -shared -lohaudio -lm -o dist/modules/output_ohaudio.so \
+  patches/src/libout123/modules/ohaudio.c
+```
+
+要点：
+
+- `-D__MUSL__`、`-fPIC`、`-shared`、`-lohaudio -lm` 是硬要求；`-lohaudio` 解析
+  `/system/lib64/ndk/libohaudio.so`（默认加载路径已含，无需 `LD_LIBRARY_PATH`）。
+- 模块源码**上游已 in-tree**（madebr fork `libout123/modules/ohaudio.c`），`patches/` 与 `source/`
+  内容一致 ⇒ 零补丁，只补这一条编译命令。
+- 选默认模块：CMake 配 `-DDEFAULT_OUTPUT_MODULE=ohaudio`；或运行时 `MPG123_MODDIR=dist/modules`。
+
+## 模块骨架（关键点，不是完整源码）
+
+```c
+mpg123_module_t mpg123_output_module_info = {
+    MPG123_MODULE_API_VERSION,     /* api_version */
+    "ohaudio",                     /* name */
+    "Output audio using OHAudio (HarmonyOS native audio API).",
+    "$Rev:$", NULL,
+    init_ohaudio                   /* init_output */
+};
+```
+
+`init_ohaudio()` 只做两件事：把 `ao->open/write/flush/drain/close/enumerate/get_formats/deinit`
+指向各回调，再 `malloc` 一个 `struct handle`（含 `OH_AudioRenderer*`、`OH_AudioStreamBuilder*`、
+`sfifo_t fifo`、`finished` 标志）。OHAudio 配置与 liba52 相同：
+
+- `AUDIOSTREAM_TYPE_RENDERER` + `SetSampleFormat`（map mpg123 enc → `AUDIOSTREAM_SAMPLE_S16LE/...`）
+- `SetEncodingType(RAW)` + `SetLatencyMode(NORMAL)` + `SetRendererInfo(AUDIOSTREAM_USAGE_MUSIC)`
+- `SetRendererWriteDataCallback(audio_callback_ohaudio, ao)`：回调从 sfifo 拉、不够则按 `framesize`
+  `ms_sleep` 等待、尾段 memset 补零
+- `GenerateRenderer` 后 `OH_AudioRenderer_GetSamplingRate` **回读实际采样率写回 `ao->rate`**（不回写会变调）
+- 收尾 `close`：置 `finished=1` → 等 ring 排空 → `Stop/Release` + `Destroy` + `sfifo_close`
+
+## 判定要点
+
+1. `out123 --list-modules`（或等价）枚举出 `ohaudio`，且驱动列表含 `dummy/ohaudio/raw/...` ⇒ 运行时
+   dlopen 成功（模块真被加载器接上，不是编译出来没人用）。
+2. 配合 `build/audio-verify.json` 四证（`dlopen 16/16` + `stream_id≠0` + `bytes_pushed==bytes_delivered`
+   + `frames_written>0`）证实出声——见 `../README.md` §达标判据。
+
+## 关联
+
+- `../README.md` —— OHAudio 后端方案本体 + 四证判据
+- `../PORTING_NOTES.md` —— 「自带 module/backend loader 的库」专节 + 各库接入表
+- `../liba52/evidence.md` —— NAPI 壳形状（无自带 loader 的库用这条）
+- `pc-error-atlas` E143 / E144 —— NDK 路径含空格时编译命令的坑（本模板的带引号直调正是规避它）
+- `pc-error-atlas` E149 —— demo 验证接线坑：`out123_open` 只装载模块不启 renderer（`out123_start` 才启）；
+  库级驱动列表一次即可，别跨用例泄漏句柄 + 重复 `out123_drivers`，否则 NAPI 壳内 CPP_CRASH 阻断后续用例

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/solutions/ohos-libusb-ddk/api-mapping.md

@@ -0,0 +1,86 @@
+# libusb-1.0 ↔ OHOS USB DDK API 映射表
+
+## 核心初始化/退出
+
+| libusb-1.0 | OHOS USB DDK | 映射方式 | 备注 |
+|---|---|---|---|
+| libusb_init(ctx) | OH_Usb_Init() | 直接调用 | ctx 参数构造全局桩 |
+| libusb_exit(ctx) | OH_Usb_Release() | 直接调用 | |
+
+## 设备枚举
+
+| libusb-1.0 | OHOS USB DDK | 映射方式 | 备注 |
+|---|---|---|---|
+| libusb_get_device_list(ctx, list) | OH_Usb_GetDevices(&devices) | 转写 | 需自建 device 对象池（list->usb_device[].deviceId） |
+| libusb_free_device_list(list, unref) | 自建释放 | 遍历释放 object 池 |
+| libusb_ref_device / libusb_unref_device | 无 | 自建引用计数 |
+| libusb_get_device_descriptor(dev, desc) | OH_Usb_GetDeviceDescriptor(dev->id, desc) | 直接转发 |
+| libusb_get_config_descriptor(dev, idx, config) | OH_Usb_GetConfigDescriptor(dev->id, idx, config) | 直接转发 |
+| libusb_free_config_descriptor(config) | OH_Usb_FreeConfigDescriptor(config) | 直接转发 |
+| libusb_get_bus_number / get_device_address / get_port_number | 无 | 返回桩值（0） |
+| libusb_get_device_speed | 无 | 返回 LIBUSB_SPEED_UNKNOWN |
+| libusb_get_max_packet_size | 无 | 从 config descriptor 自行计算 |
+
+## 设备操作
+
+| libusb-1.0 | OHOS USB DDK | 映射方式 | 备注 |
+|---|---|---|---|
+| libusb_open(dev, handle) | 存 dev->id 到 handle | 直接赋值 | DDK 无 open 概念，deviceId 即身份 |
+| libusb_close(handle) | 释放 handle | 内部无需调 DDK |
+| libusb_set_configuration(dev, config) | 无 | 返回 LIBUSB_ERROR_NOT_SUPPORTED |
+| libusb_claim_interface(dev, iface) | OH_Usb_ClaimInterface(dev->id, iface, &handle) | 直接转发 |
+| libusb_release_interface(dev, iface) | OH_Usb_ReleaseInterface(iface_handle) | 直接转发 |
+| libusb_set_interface_alt_setting(dev, iface, alt) | OH_Usb_SelectInterfaceSetting(iface_handle, alt) | 直接转发 |
+
+## 同步传输
+
+| libusb-1.0 | OHOS USB DDK | 映射方式 | 备注 |
+|---|---|---|---|
+| libusb_control_transfer(handle, bmReqType, bReq, wVal, wIdx, data, len, timeout) | OH_Usb_SendControlReadRequest / OH_Usb_SendControlWriteRequest | 按 bmReqType 定向 bit7 分流 | Setup packet 构造需按 USB spec |
+| libusb_bulk_transfer(handle, ep, data, len, transferred, timeout) | OH_Usb_SendPipeRequest | 需构造 UsbRequestPipe（含 endpoint address + direction） | timeout 映射：DDK 默认无限等待，libusb timeout=0 需用大值 |
+| libusb_interrupt_transfer(handle, ep, data, len, transferred, timeout) | OH_Usb_SendPipeRequest | 同上 | |
+
+## 异步传输（❌ 不可直接映射）
+
+| libusb-1.0 | OHOS USB DDK | 映射方式 | 备注 |
+|---|---|---|---|
+| libusb_submit_transfer | 无 | 返回 LIBUSB_ERROR_NOT_SUPPORTED | 所有异步路径退化 |
+| libusb_handle_events / handle_events_timeout | 无 | 返回 0（no events） | |
+| libusb_cancel_transfer | 无 | 返回 LIBUSB_ERROR_NOT_SUPPORTED | |
+
+## 热插拔（❌ 不可直接映射）
+
+| libusb-1.0 | OHOS USB DDK | 映射方式 | 备注 |
+|---|---|---|---|
+| libusb_hotplug_register_callback | 无 | 返回 LIBUSB_ERROR_NOT_SUPPORTED | 需轮询 OH_Usb_GetDevices 实现 |
+| libusb_hotplug_deregister_callback | 无 | 无操作 | |
+
+## 其他
+
+| libusb-1.0 | OHOS USB DDK | 映射方式 | 备注 |
+|---|---|---|---|
+| libusb_get_string_descriptor_ascii | 无 | 用控制传输 + USB spec 手动实现 | |
+| libusb_get_active_config_descriptor | OH_Usb_GetConfigDescriptor(idx=0) | 假设 idx=0 | |
+| libusb_has_capability | 自判 | 返回 LIBUSB_CAP_HAS_HOTPLUG=0 等 | |
+
+## openocd 实际用到的子集分析
+
+查看 `src/jtag/drivers/libusb1_common.c` 和相关文件，openocd 通过
+`libusb1_common.h`（jimtcl 内嵌）使用 libusb 的 API 子集。核心函数：
+
+- libusb_init / libusb_exit ✅
+- libusb_open / libusb_close ⚠️（无 DDK 直接等价需桥）
+- libusb_get_device_list / free_device_list ✅（需自建池）
+- libusb_get_device_descriptor ✅
+- libusb_claim_interface / release_interface ✅
+- libusb_control_transfer ✅
+- libusb_bulk_transfer ✅
+- libusb_interrupt_transfer ✅
+- libusb_set_interface_alt_setting ✅
+- libusb_set_configuration ⚠️（返回 NOT_SUPPORTED，FTDI/STLink 可能工作不正常）
+
+核心缺口：`libusb_set_configuration` 在 FTDI/ST-Link 驱动初始化时可能为前置条件。
+若返回 NOT_SUPPORTED，适配器工作在默认配置（通常也够用），但需真机验证。
+
+**综合评价**：同步 API 子集可桥接（~80% 匹配），异步路径退化，
+set_configuration 缺口可能影响少数适配器。整体可行但需真机验证。