@harmonyos-arkts/d2h 0.1.19 → 0.1.21

package/skills/cpp/d2h-native-library-build/SKILL.md

@@ -0,0 +1,403 @@
+---
+name: d2h-native-library-build
+description: Android C/C++ 库三种使用方式的鸿蒙适配解决方案。以「使用方式」为主线（① 源码编译成 .so/.a + JNI 引用 ② 源码集成后自己写脚本/patch 修改再编译 ③ 引入三方预编译 .so + 头文件），对每种情况给出：迁移前检查（scripts/check-android-so.py 判断现有 .so/.a 能否直接用于鸿蒙）→ 识别特征 → 分步处置方案 → 验证。内置编译与桥接共享参考（ndk-build/CMake/Gradle externalNativeBuild vs DevEco CMake/externalNativeOptions/OHOS NDK；JNI + System.loadLibrary vs NAPI + napi_module_register + import libxxx.so；类型映射）以及三方预编译库的替代决策树（查鸿蒙替代/获取上游源码/系统 API 重实现/裁剪+风险标记）。当用户需要把 C/C++ 原生库、.so、JNI 迁移/编译到鸿蒙，或询问「现有 so 能不能直接在鸿蒙用」「源码编译的 so 怎么迁」「带 patch 的源码怎么迁」「三方 so 没源码怎么办」「JNI 怎么转 NAPI」「so 怎么打包进鸿蒙」「VLC/ffmpeg 怎么在鸿蒙上用」「NDK 对应鸿蒙的什么」时触发。区别于 native-library-substitution（只提供替代包查询数据，本 Skill 负责三种情况的完整处置流程）。
+---
+
+# Android C/C++ 库三种使用方式 → HarmonyOS 适配解决方案
+
+本 Skill 以 Android 工程里 **C/C++ 库的三种使用方式**为主线，针对每种情况给出从「迁移前检查 → 识别特征 → 分步处置 → 验证」的完整方案。三种情况：
+
+| 情况 | Android 侧使用方式 | 关键差异 | 处置主线 |
+|------|--------------------|----------|----------|
+| **①** | 源码编译成 .so/.a，用 JNI 引用 | 有完整源码 | 源码重编 + JNI→NAPI |
+| **②** | 源码集成后，自己写脚本/patch 修改再编译成 .so | 有源码 + 修改脚本/patch | patch 适配 + 源码重编 + JNI→NAPI |
+| **③** | 引入三方预编译 .so + 头文件 | **无源码** | 查替代 / 获取源码 / 系统 API 重实现 / 裁剪 |
+
+> 三种情况的共同前提：**Android 编译出的 .so（无论自编还是三方）绝大多数不能直接放进鸿蒙工程**，原因是 Bionic libc 与 musl libc 的 ABI 不同、Android 系统库（`liblog.so`/`libandroid.so` 等）鸿蒙无同 ABI、JNI 依赖 ART 运行时（鸿蒙用 NAPI）、目标三元组不同（`aarch64-linux-android` vs `aarch64-linux-ohos`）。①②的解决方案是「重编+桥接改写」，③的解决方案是「替代/获取源码/重实现/裁剪」。
+
+---
+
+## 一、迁移前检查（先判断，再动手）
+
+迁移第一步不是改代码，而是**先检查工程里已有的 .so/.a 能否直接用于鸿蒙**，并据此确定它属于哪种情况、该走哪条处置路线。
+
+### 1.1 自动检查脚本
+
+```bash
+# D2h 流程内推荐：按 facts/native-libs.json 分片清单对账检查（不重扫，含分片①②③初分类比对）
+python3 scripts/check-android-so.py <Android工程目录> \
+  --from-facts <迁移工作区>/.migration/spec/facts/native-libs.json --json
+
+# 独立使用：全工程扫描
+python3 scripts/check-android-so.py <Android工程目录>      # 文本报告
+python3 scripts/check-android-so.py <Android工程目录> --json   # 机器可读 JSON
+```
+
+脚本扫描工程下所有 `.so`/`.a`（或按 `--from-facts` 只查分片列出的产物），输出每个库的：架构、动态依赖（NEEDED）、SONAME、JNI 符号（`Java_*`/`JNI_OnLoad`）、Bionic 版本符号、Android 专用符号，以及「可直接使用 / 不能直接使用」结论 + 情况分类（①②③）+ 分步方案。`--from-facts` 模式还会回显分片的 `usageCase` 初分类与 `loadCalls` 清单供两边对账。
+
+> 已知盲区：AAR/Maven 依赖内嵌的 `jniLibs/*.so` 不在工程仓库内，静态扫描与 `--from-facts` 都看不到——分片只会有 `loadCalls` 线索（`usageCase: load-only`）。遇到 load-only 线索时，先从 Gradle 缓存定位并解包对应 AAR（`~/.gradle/caches/modules-2/files-2.1/<group>/<artifact>/`，`unzip -l` 找 `jni/`），对解出的 .so 跑本脚本，再按情况③处置。
+
+**跨平台（macOS / Linux / Windows）**，仅需 Python 3，且**不依赖 `file`**：文件类型用魔数判断、架构用 `llvm-readelf`/`readelf`，符号用 `llvm-nm`/`nm`。所需工具 `llvm-readelf`/`llvm-nm`/`llvm-objdump` 由 Android NDK 与 DevEco/OpenHarmony SDK 三平台同名自带；脚本自动发现顺序：① PATH → ② 环境变量 `ANDROID_NDK_HOME`/`ANDROID_HOME`/`OHOS_SDK_HOME`/`DEVECO_SDK_HOME` → ③ DevEco 内置 SDK 常见安装目录。Windows 未设 PATH 时，先设 `ANDROID_NDK_HOME`（指向 `ndk/<版本>`）或 `OHOS_SDK_HOME`（指向 SDK 根目录）即可。
+
+### 1.2 判定规则（技术依据）
+
+| 检查项 | 判定信号 | 含义 |
+|--------|----------|------|
+| JNI 桥接层 | 导出符号含 `Java_*` / `JNI_OnLoad` | 需 JNI→NAPI 改写 |
+| Android 系统库 | `NEEDED` 命中 `liblog.so`/`libandroid.so`/`libnativehelper.so`/`libEGL.so` 等 | 需替换/重编 |
+| Bionic 版本符号 | 未定义符号带 `@LIBC`/`@LIBLOG`/`@LIBDL` 等版本后缀 | 需 OHOS 工具链重编 |
+| Android 专用符号 | 引用 `__android_log_*`/`AAssetManager_*`/`ANativeWindow_*` 等 | 需替换为鸿蒙 Native API |
+| 静态库 | `.a`（ar archive），对象文件为 android 三元组 | 需 OHOS 工具链重编 |
+
+任一「Android 特征」命中即判定**不能直接用**；全部未命中（musl/unversioned）才判定可直接用。
+
+### 1.3 手动检查（无脚本时）
+
+三平台可用 `llvm-readelf`/`llvm-nm`（NDK / DevEco SDK 自带）替代下面的 GNU 工具：
+
+```bash
+readelf -h libfoo.so                           # 架构 + Class（ELF32/64）
+readelf -d libfoo.so | grep -E 'NEEDED|SONAME' # 依赖
+readelf -sW libfoo.so | grep -E 'Java_|JNI_OnLoad'  # JNI 符号
+nm -D -u libfoo.so | grep -E '@LIBC|__android'      # Bionic 版本/专用符号
+# 无 readelf 时：objdump -p libfoo.so | grep -E 'NEEDED|SONAME'
+```
+
+### 1.4 情况识别：一眼定位三种情况
+
+| 特征 | 情况 |
+|------|------|
+| 工程有 `CMakeLists.txt`/`Android.mk` + `.c/.cpp` 源码，`jniLibs` 里的 .so 由它编出 | **①** 源码编译 |
+| 有源码 + `.patch`/`.diff` 文件或 `build.sh`/自定义 `.mk` 修改脚本 | **②** 源码+patch |
+| 只有 `libs/<abi>/libxxx.so` + `include/*.h`，无源码、无构建脚本 | **③** 三方预编译 |
+
+---
+
+## 二、情况①：源码编译成 .so/.a + JNI 引用
+
+**现状**：你有完整 C/C++ 源码，`CMakeLists.txt`/`Android.mk` 把它编成 .so，Java/Kotlin 用 `System.loadLibrary` + `native`/`external` 方法通过 JNI 调用。
+
+### 2.1 检查结论
+
+现有 .so **不能直接用**（Bionic + JNI 依赖），但**有完整源码**，是三种情况里迁移成本最低的。核心工作 = **源码用 OHOS 工具链重编 + JNI 桥接层改写成 NAPI**。
+
+### 2.2 处置流程
+
+1. **盘点**：确认构建方式（CMake / ndk-build）、依赖的系统库、ABI 列表、JNI 接口清单（`Java_*` 方法签名）。
+2. **源码重编**：
+   - `ndk-build`（`Android.mk`）→ 改写为 `CMakeLists.txt`（鸿蒙无 ndk-build）。
+   - 已有 `CMakeLists.txt` → 复用，改三点：目标三元组 `aarch64-linux-android`→`aarch64-linux-ohos`、日志库 `-llog`→`libhilog_ndk.z.so`、头文件 `<android/log.h>`→`<hilog/log.h>`。
+   - 详见「六、共享参考：构建与桥接映射」。
+3. **建工程骨架**：DevEco 新建工程，`src/main/cpp/` 放源码，`build-profile.json5` 配 `externalNativeOptions` + `abiFilters`。
+4. **JNI→NAPI 桥接改写**：按接口逐条把 `Java_com_xxx_xxx` / `JNI_OnLoad` 改成 `napi_value` 函数 + `napi_module_register`（见「6.3 JNI ↔ NAPI 桥接对照」）。
+5. **ArkTS 封装 + .d.ts**：把 NAPI 裸接口包成 ArkTS class/对象。
+6. **构建验证**：`hvigor` 构建，确认 `libs/<abi>/libxxx.so` 进 HAP；真机 `import libxxx.so` 调用验证。
+
+### 2.3 识别到 JNI 桥接层的额外提示
+
+- 若 .so 是「JNI 桥接层 + 核心库」分层（如 `libxxx.so` 桥接 JNI，`libxxx_core.so` 是纯 C 逻辑）：核心库只需重编，桥接层重编 + 改写 NAPI，两层都要处理。
+- 依赖的第三方 C/C++ 库同样按本情况重编，或用 `native-library-substitution` 查鸿蒙替代包。
+
+---
+
+## 三、情况②：源码集成 + 自己写脚本/patch 修改后编译
+
+**现状**：你有上游源码 + 自己的一套修改脚本/patch（`.patch`/`.diff`、`build.sh`、自定义 `.mk`），跑完脚本才产出 .so。这比情况①多一层**平台差异适配**：你的 patch/脚本里通常含有 Android 特有代码。
+
+### 3.1 检查结论
+
+现有 .so **不能直接用**，但**有源码 + patch**。核心工作 = **在 OHOS 工具链下重放 patch/脚本 + 逐条适配 Android 特有代码 + JNI→NAPI 重编**。
+
+### 3.2 处置流程
+
+1. **盘点 patch/脚本内容**：grep 出脚本和 patch 里的 Android 特有引用（`__ANDROID__` 宏、`__android_log_*`、`AAssetManager_*`、`ANativeWindow_*`、`#include <android/...>`、`-llog`/`-landroid` 等）。
+2. **重放 patch/脚本**：把构建目标切到 OHOS 工具链（`--target=aarch64-linux-ohos`），重跑修改脚本；patch 用 `git apply`/`patch` 在源码上重放。
+3. **平台差异适配**：按「3.3 Android 特有 C/C++ API → 鸿蒙 Native API 对照」逐条替换 Android 特有 API。
+4. **源码重编**：同情况①（CMake 改写 + `libhilog_ndk.z.so`）。
+5. **JNI→NAPI 桥接改写**：同情况①。
+6. **验证**：构建 + 真机调用，重点回归 patch 修改过的功能点。
+
+### 3.3 Android 特有 C/C++ API → 鸿蒙 Native API 对照
+
+| Android（patch 里常出现） | 鸿蒙对应 | 说明 |
+|---------------------------|----------|------|
+| `<android/log.h>` `__android_log_print` | `<hilog/log.h>` `OH_LOG_Print` | 日志 |
+| `<android/asset_manager.h>` `AAssetManager_*` | `OH_ResourceManager_*`（rawfile） | 资源/文件 |
+| `ANativeWindow_*` | `OH_NativeWindow_*` / XComponent `OH_NativeXComponent` | 渲染表面 |
+| `ANativeActivity_*` | 无直接对应（NAPI + Ability 生命周期） | Activity 桥 |
+| `AHardwareBuffer_*` | `OH_NativeBuffer_*` | 图形缓冲 |
+| `ACameraManager_*` / `ACameraDevice_*` | `OH_Camera_*`（Camera NDK） | 相机 |
+| `AMediaCodec_*` / `AMediaExtractor_*` | `OH_AVCodec_*` / `OH_AVFormat_*` | 音视频编解码 |
+| `ASensorManager_*` | `OH_Sensor_*` | 传感器 |
+| `AAudio_*` | `OH_Audio_*`（OHAudio） | 音频 |
+| `AChoreographer_*` | 无直接对应 | 帧回调 |
+| `JavaVM*` / `JNIEnv*` | `napi_env` | JNI→NAPI 环境 |
+| `-llog` / `liblog.so` | `libhilog_ndk.z.so` | 日志库 |
+| `-landroid` / `libandroid.so` | 拆分到各 Native 模块 | 系统库 |
+| `<sys/system_properties.h>` `__system_property_get` | 无直接对应 | 系统属性 |
+
+> 适配原则：先看鸿蒙是否有「同名语义」的 Native API（上表）；没有则看能否用系统库/ArkTS 侧能力替代；再没有则重新实现该功能点并记录差异。
+
+---
+
+## 四、情况③：三方预编译 .so + 头文件（无源码）
+
+**现状**：只有 `libs/<abi>/libxxx.so`（或 `jniLibs/`）和 `include/*.h`，**没有源码**。这是三种情况里最麻烦的，不能靠重编解决。
+
+### 4.1 识别特征
+
+- 工程里只有 `.so` + `.h`，无对应 `.c/.cpp`、无 `CMakeLists.txt`/`Android.mk`。
+- 头文件只暴露 C/C++ API（可能是 `Java_*` 的 JNI 封装，也可能是纯 C API）。
+- 用 `nm -D` 看导出符号可判断它是什么：有 `Java_*`/`JNI_OnLoad` → JNI 封装；纯 C 函数名 → 纯 C 库。
+
+### 4.2 检查结论
+
+预编译 Android .so **不能直接用于鸿蒙**：即使无 JNI、纯 C，也因 Bionic libc ABI 不同而无法加载；且无源码无法重编。必须走替代路线。
+
+### 4.3 决策树（按优先级，命中即走）
+
+```
+三方预编译 .so + 头文件（无源码）
+│
+├─ 1. 查鸿蒙替代 / 鸿蒙化版 ──── 命中 → 用替代包（ohpm install / 官方鸿蒙 SDK）
+│       · native-library-substitution（ohpm 2678 映射，含「C++/C鸿蒙化库」133 条）
+│       · ohpm 仓库在线搜索：https://ohpm.harmonyos.com
+│       · 厂商官方鸿蒙 SDK（MMKV、推送、地图、支付、IM 等）
+│
+├─ 2. 查上游是否开源 ────────── 有源码 → 退回情况①/②，OHOS 工具链重编 + JNI→NAPI
+│       · 用 .so 库名 + 头文件里的函数名/版权声明反查 GitHub/Gitee
+│
+├─ 3. 鸿蒙系统 API 重实现 ────── 无包无源码 → 用 @ohos.* / @kit.* 或 Native API 重写该功能
+│       · 按头文件暴露的 API 逐条找系统 API 对应
+│
+└─ 4. 功能裁剪 / 降级 ────────── 以上都不行 → 评估能否移除该功能，标记 risk_items（high）
+```
+
+### 4.4 各分支详解
+
+**分支 1 — 查鸿蒙替代**：调用 `native-library-substitution` 技能（或本地查它的 `references/native-library-substitution.json`），按库名/功能查 `ohpm_package` 与 `source_type`（`安卓鸿蒙化库`/`C++/C鸿蒙化库` 优先）。命中后 `ohpm install`，并用替代包的 ArkTS/NAPI 接口替换原 JNI 调用。
+
+**分支 2 — 获取上游源码**：通过头文件里的函数名、类名、版权/仓库注释反查开源地址；找到源码即退回情况①/②。
+
+**分支 3 — 系统 API 重实现**：按头文件 API 语义逐个找鸿蒙系统能力（`@ohos.*` / `@kit.*` 模块，或 Native API）。例：加密 .so → `@ohos.security.cryptoFramework`；网络 .so → `@ohos.net.http`；音视频 .so → `@ohos.multimedia.media`。
+
+**分支 4 — 裁剪/降级**：功能可去则去除依赖并降级体验；不可去则标记阻塞。输出 `risk_items`。
+
+### 4.5 输出格式（写入迁移规划）
+
+```json
+{
+  "native_dependency_mapping": [
+    {
+      "original_platform": "android",
+      "original_lib": "libvlc.so（三方预编译，无源码）",
+      "original_usage": "视频播放",
+      "ohos_solution_type": "ohpm_package | custom_implementation | not_available",
+      "ohos_package": "命中时的 ohpm 包名 | null",
+      "ohos_module": "系统 API 重实现时的模块名 | null",
+      "install_command": "ohpm install xxx | null",
+      "confidence": "high | medium | low",
+      "notes": "决策分支、能力覆盖度、已知限制、备选方案摘要"
+    }
+  ],
+  "risk_items": [
+    {
+      "description": "预编译库 {库名} 无鸿蒙替代、无源码、无系统 API 对应",
+      "severity": "high",
+      "mitigation": "评估移除该功能或换渠道；阻塞级别：partial | full"
+    }
+  ]
+}
+```
+
+---
+
+## 五、情况对照速查
+
+| 情况 | 有无源码 | 现有 .so 能否直接用 | 主工作 | 难点 | 典型工作量 |
+|------|---------|--------------------|--------|------|-----------|
+| ① 源码编译 + JNI | 有 | ❌ | 源码重编 + JNI→NAPI | 桥接改写 | 低 |
+| ② 源码 + patch | 有 | ❌ | patch 适配 + 重编 + JNI→NAPI | 平台差异适配 | 中 |
+| ③ 三方预编译 | 无 | ❌ | 替代/获取源码/重实现/裁剪 | 无源码，依赖外部 | 高 |
+
+---
+
+## 六、共享参考：构建与桥接映射（情况①②使用）
+
+以下映射是情况①②「源码重编 + 桥接改写」的技术底稿。
+
+### 6.1 Android 构建方式 → 鸿蒙构建方式
+
+| Android | HarmonyOS | 说明 |
+|---------|-----------|------|
+| NDK（LLVM/clang） | HarmonyOS NDK / OpenHarmony SDK Native（LLVM/clang） | 同源工具链，目标三元组不同 |
+| ndk-build（`Android.mk`+`Application.mk`） | 无对应，统一 CMake | `Android.mk` 需改写为 `CMakeLists.txt` |
+| CMake（`CMakeLists.txt`） | CMake（`CMakeLists.txt`） | 基本复用，改链接库/头文件/三元组 |
+| `externalNativeBuild.cmake.path` | `buildOption.externalNativeOptions.path` | 配置位置不同 |
+| `ndk.abiFilters` | `externalNativeOptions.abiFilters` | 语义相同 |
+| 预编译 .so 放 `src/main/jniLibs/<abi>/` | 放 `libs/<abi>/` 或 CMake IMPORTED | 位置不同 |
+
+Android ABI：`arm64-v8a`（主流）、`armeabi-v7a`、`x86_64`、`x86`；鸿蒙以 `arm64-v8a` 为必备，`x86_64` 供模拟器。
+
+**鸿蒙构建配置（`build-profile.json5`）**：
+
+```json5
+{
+  "modules": [{
+    "name": "entry",
+    "targets": [{
+      "name": "default",
+      "buildOption": {
+        "externalNativeOptions": {
+          "path": "./src/main/cpp/CMakeLists.txt",
+          "abiFilters": ["arm64-v8a", "x86_64"]
+        }
+      }
+    }]
+  }]
+}
+```
+
+**鸿蒙 CMakeLists.txt**：
+
+```cmake
+cmake_minimum_required(VERSION 3.5.0)
+project(mylib)
+add_library(mylib SHARED napi_init.cpp)
+target_link_libraries(mylib PUBLIC libhilog_ndk.z.so)
+```
+
+**交叉编译三元组对照**：
+
+```bash
+# Android
+$NDK/.../bin/aarch64-linux-android21-clang -shared -fPIC -o libmylib.so mylib.c
+# HarmonyOS
+$OHOS_SDK/native/llvm/bin/clang --target=aarch64-linux-ohos \
+  --sysroot=$OHOS_SDK/native/sysroot -shared -fPIC -o libmylib.so mylib.c
+```
+
+### 6.2 系统库依赖对照（常用）
+
+| Android 库 | HarmonyOS 库 | 用途 |
+|-----------|--------------|------|
+| `-llog` / `liblog.so` | `libhilog_ndk.z.so` | 日志 |
+| `-lz` / `libz.so` | `libz.so` | 压缩 |
+| `-lcrypto -lssl` | 系统 OpenSSL 或自编 | 加解密 |
+| `-landroid` | 无对应（拆到各 Native API） | Android 特有 |
+| OpenGL ES | `libGLESv3.so` / EGL | 图形（XComponent + OpenGL） |
+| `libdl.so` | `libdl.so` | 动态加载 |
+| `-lm` | `libm.so` | 数学库 |
+
+### 6.3 JNI ↔ NAPI 桥接对照
+
+**Java 侧 → ArkTS 侧**：
+
+| Android JNI | HarmonyOS NAPI |
+|-------------|----------------|
+| `<jni.h>` + `JNIEnv*` | `napi/native_api.h` + `napi_env` |
+| `JNIEXPORT ... JNICALL Java_com_x_y_z()` | `static napi_value fn(napi_env, napi_callback_info)` |
+| `System.loadLibrary("x")` | `import x from 'libx.so'` |
+| `native` / `external` 方法声明 | `napi_define_properties` + `.d.ts` 导出 |
+| `JNI_OnLoad` 动态注册 | `napi_module_register` + `__attribute__((constructor))` |
+| `env->GetStringUTFChars` | `napi_get_value_string_utf8` |
+| `env->NewStringUTF` | `napi_create_string_utf8` |
+| `jobject` 回调 Java | `napi_create_function` / `napi_call_function` 回调 ArkTS |
+| `jbyteArray` | `napi_create_arraybuffer` / `napi_create_typedarray` |
+| `NewGlobalRef` 保持引用 | `napi_create_reference` |
+
+**NAPI 模块模板**：
+
+```cpp
+#include "napi/native_api.h"
+
+static napi_value Hello(napi_env env, napi_callback_info info) {
+    size_t argc = 1;
+    napi_value args[1] = {nullptr};
+    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
+    // ...
+    napi_value result;
+    napi_create_string_utf8(env, "hello", NAPI_AUTO_LENGTH, &result);
+    return result;
+}
+
+EXTERN_C_START
+static napi_value Init(napi_env env, napi_value exports) {
+    napi_property_descriptor desc[] = {
+        { "hello", nullptr, Hello, nullptr, nullptr, nullptr, napi_default, nullptr }
+    };
+    napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
+    return exports;
+}
+EXTERN_C_END
+
+static napi_module mylibModule = {
+    .nm_version = 1, .nm_flags = 0, .nm_filename = nullptr,
+    .nm_register_func = Init, .nm_modname = "mylib",
+    .nm_priv = ((void*)0), .reserved = { 0 },
+};
+extern "C" __attribute__((constructor)) void RegisterMylibModule(void) {
+    napi_module_register(&mylibModule);
+}
+```
+
+ArkTS 调用 + 类型声明：
+
+```typescript
+import mylib from 'libmylib.so';
+let r = mylib.hello('world');
+```
+
+`entry/src/main/cpp/types/libmylib/index.d.ts`：
+
+```typescript
+export const hello: (name: string) => string;
+```
+
+### 6.4 类型映射对照
+
+| Java/Kotlin | JNI 类型 | NAPI 类型 |
+|-------------|----------|-----------|
+| `String` | `jstring` | `napi_value`（string） |
+| `Int` | `jint` | `napi_value`（number） |
+| `Long` | `jlong` | `napi_value`（bigint/number） |
+| `Boolean` | `jboolean` | `napi_value`（boolean） |
+| `ByteArray` | `jbyteArray` | `napi_value`（ArrayBuffer/TypedArray） |
+| `Object` | `jobject` | `napi_value`（object） |
+| `void` | `void` | `napi_get_undefined` |
+
+### 6.5 典型库示例：VLC (libvlc)
+
+Android：`LibVLC(context, args)` → `libvlcjni.so`（JNI）→ `libvlc.so`（核心）。
+鸿蒙：OHOS 工具链交叉编译 libvlc 核心得到 `arm64-v8a/libvlc.so`，再写一层 `libvlc_napi.so` 把 `libvlc_new`/`libvlc_media_new_path`/`libvlc_media_player_play` 等 C API 导出给 ArkTS。
+
+| Android（Java 封装） | libvlc C API | HarmonyOS（NAPI 导出） |
+|----------------------|--------------|------------------------|
+| `LibVLC(context, args)` | `libvlc_new` | `libvlc_new` |
+| `Media(libVLC, uri)` | `libvlc_media_new_path` | `libvlc_media_new_path` |
+| `MediaPlayer(libVLC)` | `libvlc_media_player_new` | `libvlc_media_player_new` |
+| `player.play()` | `libvlc_media_player_play` | `libvlc_media_player_play` |
+
+关键点：视频渲染 Android 用 `SurfaceView`（`libvlc_media_player_set_android_surface`），鸿蒙用 XComponent（`OH_NativeXComponent`）；回调用 `napi_threadsafe_function` 跨线程。
+
+### 6.6 常见坑与规避
+
+| 坑 | 规避 |
+|----|------|
+| `-llog` / `liblog` 找不到 | 换成 `libhilog_ndk.z.so`，头文件 `<hilog/log.h>` |
+| 目标三元组错 | Android `aarch64-linux-android` → 鸿蒙 `aarch64-linux-ohos` |
+| 少了 `napi_module_register` | NAPI 模块必须注册 constructor 才能被 `import` 识别 |
+| 预编译 .so 架构不对 | 只放 `arm64-v8a`，缺失架构在对应设备崩溃 |
+| `.d.ts` 缺失导致 import 报类型错 | 建 `types/libmylib/index.d.ts` |
+| JNI 回调对象被 GC | 用 `napi_create_reference` 保持引用 |
+| 大块二进制拷贝慢 | 用 `napi_create_arraybuffer` + 直接指针读写 |
+| 依赖的系统库差异 | 用 `native-library-substitution` 或 OHOS SDK 文档核对可用 Native API |
+
+---
+
+## 七、参考文件
+
+- [scripts/check-android-so.py](scripts/check-android-so.py)：迁移前 .so/.a 检查脚本（能否直接用于鸿蒙 + 三种情况的处置方案）。
+- [references/jni-to-napi-mapping.md](references/jni-to-napi-mapping.md)：JNI ↔ NAPI 逐函数对照速查表。
+- [references/build-config-mapping.md](references/build-config-mapping.md)：build.gradle / CMakeLists / Android.mk ↔ build-profile.json5 / CMakeLists 对照模板。
+- `native-library-substitution`（独立技能）：情况③ 分支 1 的替代包查询数据源（ohpm 2678 映射）。

package/skills/cpp/d2h-native-library-build/references/build-config-mapping.md

@@ -0,0 +1,180 @@
+# 构建配置对照模板：Android ↔ HarmonyOS
+
+用于把 Android 的 native 构建配置平移为鸿蒙构建配置。
+
+## 一、整体配置位置对照
+
+| 关注点 | Android | HarmonyOS |
+|--------|---------|-----------|
+| 模块构建脚本 | `app/build.gradle`（或 `.kts`） | `entry/build-profile.json5` |
+| 包/模块声明 | `build.gradle` 的 `android { }` | `oh-package.json5` |
+| 原生构建脚本 | `src/main/cpp/CMakeLists.txt` 或 `jni/Android.mk` | `src/main/cpp/CMakeLists.txt` |
+| ABI 过滤 | `android.defaultConfig.ndk.abiFilters` | `buildOption.externalNativeOptions.abiFilters` |
+| 预编译 .so 目录 | `src/main/jniLibs/<abi>/` | `entry/libs/<abi>/`（或 CMake IMPORTED） |
+
+## 二、build.gradle → build-profile.json5
+
+### Android（app/build.gradle）
+
+```gradle
+android {
+    defaultConfig {
+        ndk { abiFilters 'arm64-v8a', 'armeabi-v7a' }
+    }
+    externalNativeBuild {
+        cmake {
+            path "src/main/cpp/CMakeLists.txt"
+            version "3.22.1"
+        }
+    }
+}
+```
+
+### HarmonyOS（entry/build-profile.json5）
+
+```json5
+{
+  "app": { "signingConfigs": [], "products": [{ "name": "default", "signingConfig": "default" }] },
+  "modules": [
+    {
+      "name": "entry",
+      "srcPath": "./entry",
+      "targets": [
+        {
+          "name": "default",
+          "applyToProducts": ["default"],
+          "buildOption": {
+            "externalNativeOptions": {
+              "path": "./src/main/cpp/CMakeLists.txt",
+              "arguments": "",
+              "cppFlags": "",
+              "abiFilters": ["arm64-v8a", "x86_64"]
+            }
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+## 三、CMakeLists.txt 对照
+
+### Android 版
+
+```cmake
+cmake_minimum_required(VERSION 3.18)
+project(mylib)
+
+add_library(mylib SHARED native.cpp)
+
+find_library(log-lib log)
+target_link_libraries(mylib ${log-lib})
+```
+
+### HarmonyOS 版（差异点：日志库、头文件、三元组）
+
+```cmake
+cmake_minimum_required(VERSION 3.5.0)
+project(mylib)
+
+add_library(mylib SHARED napi_init.cpp)
+
+# 鸿蒙日志库替换 Android 的 liblog
+target_link_libraries(mylib PUBLIC libhilog_ndk.z.so)
+```
+
+对应头文件替换：
+
+| Android | HarmonyOS |
+|---------|-----------|
+| `<android/log.h>` + `__android_log_print` | `<hilog/log.h>` + `OH_LOG_Print` |
+
+## 四、Android.mk（ndk-build）→ CMakeLists.txt
+
+### Android.mk（遗留）
+
+```makefile
+LOCAL_PATH := $(call my-dir)
+include $(CLEAR_VARS)
+LOCAL_MODULE := mylib
+LOCAL_SRC_FILES := native.cpp
+LOCAL_LDLIBS := -llog
+include $(BUILD_SHARED_LIBRARY)
+```
+
+### 等价 CMakeLists.txt（鸿蒙）
+
+```cmake
+cmake_minimum_required(VERSION 3.5.0)
+project(mylib)
+add_library(mylib SHARED napi_init.cpp)
+target_link_libraries(mylib PUBLIC libhilog_ndk.z.so)
+```
+
+## 五、预编译 .so 引入对照
+
+### Android（jniLibs 目录，自动打包）
+
+```
+app/src/main/jniLibs/arm64-v8a/libfoo.so
+```
+
+无需额外配置，Gradle 自动打入 APK。
+
+### HarmonyOS（CMake IMPORTED）
+
+```cmake
+add_library(foo SHARED IMPORTED)
+set_target_properties(foo PROPERTIES IMPORTED_LOCATION
+    ${CMAKE_SOURCE_DIR}/../libs/${CMAKE_ANDROID_ABI}/libfoo.so)  # 注意用 OHOS 变量
+target_link_libraries(mylib PUBLIC foo)
+```
+
+或将预编译 .so 放 `entry/libs/arm64-v8a/libfoo.so`，在 CMake 里引入。
+
+## 六、交叉编译工具链对照
+
+| 项 | Android NDK | HarmonyOS NDK |
+|----|-------------|---------------|
+| 编译器 | `$NDK/toolchains/llvm/prebuilt/<host>/bin/aarch64-linux-android<api>-clang` | `$OHOS_SDK/native/llvm/bin/clang` |
+| 目标三元组 | `aarch64-linux-android` | `aarch64-linux-ohos` |
+| sysroot | `$NDK/toolchains/llvm/prebuilt/<host>/sysroot` | `$OHOS_SDK/native/sysroot` |
+| C++ 库 | `libc++`（`-stdlib=libc++` 默认） | `libc++`（默认） |
+
+### 编译命令对照
+
+Android：
+
+```bash
+$NDK/toolchains/llvm/prebuilt/darwin-x86_64/bin/aarch64-linux-android21-clang \
+  -shared -fPIC -o libmylib.so mylib.c
+```
+
+HarmonyOS：
+
+```bash
+$OHOS_SDK/native/llvm/bin/clang \
+  --target=aarch64-linux-ohos --sysroot=$OHOS_SDK/native/sysroot \
+  -shared -fPIC -o libmylib.so mylib.c
+```
+
+## 七、系统库依赖对照（常用）
+
+| Android 库 | HarmonyOS 库 | 用途 |
+|-----------|--------------|------|
+| `-llog` / `liblog.so` | `libhilog_ndk.z.so` | 日志 |
+| `-lz` / `libz.so` | `libz.so` | 压缩 |
+| `-lcrypto -lssl` | 系统 OpenSSL 或自编 | 加解密 |
+| `-landroid` | 无对应（用 Native API） | Android 特有（如 AssetManager） |
+| OpenGL ES | `libGLESv3.so` / EGL | 图形（鸿蒙用 XComponent + OpenGL） |
+| `libdl.so` | `libdl.so` | 动态加载 |
+| `-lm` | `libm.so` | 数学库 |
+
+## 八、验证命令
+
+| 步骤 | Android | HarmonyOS |
+|------|---------|-----------|
+| 构建 | `./gradlew assembleDebug` | DevEco 构建 / `hvigorw assembleHap` |
+| 产物 | `app/build/intermediates/.../cmake/.../libmylib.so` | `entry/build/default/intermediates/libs/default/<abi>/libmylib.so` |
+| 产物检查 | `unzip -l app-debug.apk | grep .so` | 解包 HAP 检查 `libs/<abi>/` |

package/skills/cpp/d2h-native-library-build/references/jni-to-napi-mapping.md

@@ -0,0 +1,74 @@
+# JNI ↔ NAPI 函数对照速查表
+
+本表用于把 Android JNI 桥接代码逐函数改写为 HarmonyOS NAPI 代码。
+
+## 一、环境与模块注册
+
+| 目的 | Android JNI | HarmonyOS NAPI |
+|------|-------------|----------------|
+| 头文件 | `#include <jni.h>` | `#include "napi/native_api.h"` |
+| 环境类型 | `JNIEnv *env` | `napi_env env` |
+| 导出函数签名 | `JNIEXPORT jstring JNICALL Java_pkg_Class_method(JNIEnv *env, jobject thiz, ...)` | `static napi_value method(napi_env env, napi_callback_info info)` |
+| 获取参数 | 直接来自函数形参 | `napi_get_cb_info(env, info, &argc, args, &this_arg, nullptr)` |
+| 模块加载 | `System.loadLibrary("x")` 触发 `JNI_OnLoad` | `import x from 'libx.so'` 触发 `napi_module_register` |
+| 模块注册 | `JNI_OnLoad(JavaVM*, void*)` 返回版本号 | `static napi_module m = { .nm_register_func = Init, .nm_modname = "x" };` + `__attribute__((constructor)) void f(){ napi_module_register(&m); }` |
+| 导出方法 | `RegisterNatives` 或静态命名 | `napi_define_properties(env, exports, n, desc)` |
+
+## 二、基础类型转换
+
+| Java/Kotlin | JNI | NAPI 取值 | NAPI 构造 |
+|-------------|-----|-----------|-----------|
+| `String` | `jstring` | `napi_get_value_string_utf8` | `napi_create_string_utf8` |
+| `int` | `jint` | `napi_get_value_int32` | `napi_create_int32` |
+| `long` | `jlong` | `napi_get_value_int64` / `napi_get_value_bigint_int64` | `napi_create_int64` / `napi_create_bigint_int64` |
+| `double` | `jdouble` | `napi_get_value_double` | `napi_create_double` |
+| `boolean` | `jboolean` | `napi_get_value_bool` | `napi_get_boolean` |
+| `void` | `void` | — | `napi_get_undefined` |
+| `null` | `nullptr` | `napi_get_null` | `napi_get_null` |
+| `byte[]` | `jbyteArray` | `napi_get_typedarray_info` / `napi_get_arraybuffer_info` | `napi_create_arraybuffer` / `napi_create_typedarray` |
+
+## 三、对象与数组
+
+| 目的 | JNI | NAPI |
+|------|-----|------|
+| 创建对象 | `env->NewObject(cls, ctor, ...)` | `napi_new_instance(env, ctor, ...)` |
+| 取字段 | `env->GetObjectField` | `napi_get_named_property` / `napi_get_property` |
+| 设字段 | `env->SetObjectField` | `napi_set_named_property` / `napi_set_property` |
+| 创建数组 | `env->NewObjectArray` | `napi_create_array` / `napi_create_array_with_length` |
+| 取数组元素 | `env->GetObjectArrayElement` | `napi_get_element` |
+| 设数组元素 | `env->SetObjectArrayElement` | `napi_set_element` |
+
+## 四、函数与回调
+
+| 目的 | JNI | NAPI |
+|------|-----|------|
+| 创建回调函数 | `env->NewGlobalRef(obj)` + 回调方法 ID | `napi_create_function` / `napi_create_threadsafe_function` |
+| 调用 Java/ArkTS 方法 | `env->CallVoidMethod` / `CallStaticObjectMethod` | `napi_call_function` |
+| 跨线程回调 | JNI 线程 attach + CallMethod | `napi_threadsafe_function`（`napi_call_threadsafe_function`） |
+| 保持引用 | `env->NewGlobalRef` | `napi_create_reference` |
+| 释放引用 | `env->DeleteGlobalRef` | `napi_delete_reference` |
+
+## 五、异常与字符串
+
+| 目的 | JNI | NAPI |
+|------|-----|------|
+| 抛异常 | `env->ThrowNew(cls, msg)` | `napi_throw_error` / `napi_throw_type_error` / `napi_throw_range_error` |
+| 检查异常 | `env->ExceptionCheck()` | `napi_is_exception_pending` |
+| 取字符串 | `GetStringUTFChars` + `ReleaseStringUTFChars` | `napi_get_value_string_utf8` |
+| 字符串长度 | `GetStringUTFLength` | 先 `napi_get_value_string_utf8` 传 `nullptr` 取长度，再取内容 |
+
+## 六、同步/异步
+
+| 场景 | JNI | NAPI |
+|------|-----|------|
+| 同步返回 | 直接 return | 直接 return `napi_value` |
+| 异步 | 用 Java 线程 + 回调 | `napi_create_async_work` + `napi_queue_async_work`，完成时 `napi_create_promise` / 回调 |
+| Promise | 无内置，需 Java 侧 CompletableFuture | `napi_create_promise` + `napi_resolve_deferred` / `napi_reject_deferred` |
+
+## 七、内存与生命周期
+
+| 目的 | JNI | NAPI |
+|------|-----|------|
+| 分配 | `env->NewByteArray` / malloc | `napi_create_arraybuffer`（GC 托管）或 `malloc` 自行管理 |
+| 外部缓冲 | `NewDirectByteBuffer` / `GetDirectBufferAddress` | `napi_create_external_arraybuffer` / `napi_get_arraybuffer_info` |
+| 释放 | `env->DeleteLocalRef` | `napi_delete_reference`（引用）/ 托管内存自动回收 |