deveco_hmigbot 0.21.5

package/skills/migrate-core/references/topics/library-migration/README.md

@@ -0,0 +1,234 @@
+<!-- 原技能 arkts-library-migration，已吸收为 migrate-core 语料专题，不再单独注册 -->
+> 三方库替代方案查找与决策。当用户提到三方库替代、ohpm 搜索、库迁移、Android 库用什么替代、依赖替换、build.gradle 迁移、npm 包替代等场景时，务必触发此 skill。即使用户只是说"这个库在鸿蒙上有吗"或"用什么替代 Glide"，也应触发。完整业务功能形态（下拉刷新列表、列表详情页）见 ../ui-alignment/references/visual-patterns.md。
+
+# ArkTS Library Migration — 三方库迁移决策器
+
+## API 版本
+
+本 skill 基于 **API 12+**（HarmonyOS 5.0.0+）。三方库安装使用 ohpm 包管理器。遇到版本兼容性或其他不确定的 ArkTS 知识点：grep 本机 SDK `.d.ts` 声明为准。
+
+---
+
+## 五层查找策略
+
+遇到任何 Android 三方库需要替代时，按以下层次逐级查找：
+
+```
+┌─────────────────────────────────────────────────┐
+│  Level 1: OpenHarmony 三方库 (ohpm)              │  成本最低，直接 ohpm install
+│  搜索渠道：                                       │
+│   - ohpm.openharmony.cn                          │
+│   - gitee.com/openharmony-tpc                    │
+│   - gitee.com/HarmonyOS-tpc                      │
+├─────────────────────────────────────────────────┤
+│  Level 2: HarmonyOS 原生 API (@kit.*)            │  零依赖，需自写业务代码
+│   - @kit.ImageKit (图片处理)                      │
+│   - @kit.ArkData (数据库/偏好)                   │
+│   - @kit.MediaLibraryKit (媒体库)                │
+│   - @kit.CoreFileKit (文件操作)                  │
+│   - @kit.NetworkKit (网络请求)                   │
+│   - ArkUI 内置组件 (Video/Image/Canvas/Web)      │
+├─────────────────────────────────────────────────┤
+│  Level 3: NAPI 桥接 C/C++ 开源库                 │  功能完整，集成成本高
+│   - FFmpeg (音视频处理)                           │
+│   - OpenCV (图像处理)                             │
+│   - libjpeg-turbo (图片解码)                     │
+├─────────────────────────────────────────────────┤
+│  Level 4: WebView + JS 库                        │  开发快，性能有损
+│   - Three.js (3D/全景/VR)                        │
+│   - Fabric.js (图片编辑画布)                     │
+├─────────────────────────────────────────────────┤
+│  Level 5: 自研实现或功能降级                       │  最后手段
+└─────────────────────────────────────────────────┘
+```
+
+---
+
+## 决策树
+
+```
+Android 三方库 X
+  ├─ ohpm / openharmony-tpc 搜索 → 有直接替代？
+  │   ├─ 是 → Level 1: ohpm install（最优）
+  │   └─ 否 ↓
+  ├─ HarmonyOS 原生 @kit.* API 能覆盖？
+  │   ├─ 是 → Level 2: 用原生 API 实现
+  │   └─ 否 ↓
+  ├─ 该库有 C/C++ 开源核心？
+  │   ├─ 是 → Level 3: NAPI 桥接（交叉编译 .so）
+  │   └─ 否 ↓
+  ├─ JS/Web 生态有等价库？
+  │   ├─ 是 → Level 4: ArkWeb 组件 + JS 库
+  │   └─ 否 ↓
+  └─ Level 5: 自研简化版 / 功能降级 / 标记 Skip
+```
+
+---
+
+## 下载 API 选型
+
+```
+文件下载用哪个 API？
+├─ http.request() + ARRAY_BUFFER
+│   ⚠️ 约 5MB 大小限制（错误码 2300023）
+│   ✓ 适合小文件（JSON 配置、图标）
+├─ http.requestInStream()
+│   ❌ 不推荐 — dataEnd 事件在实际设备上不触发
+│   ❌ Promise 在收到响应头后即 resolve
+└─ request.agent（推荐）
+    ✓ 无文件大小限制
+    ✓ 稳定的 progress/completed/failed 回调
+    ✓ 支持前台/后台模式
+```
+
+> 详细对比和代码模板见 `download-api-decision.md`
+
+---
+
+## RxJava / EventBus 迁移
+
+> **MUST**：RxJava→async/await 评估表、EventBus 自建 vs 三方对照见 `library-mapping-table.md`。
+
+---
+
+## 响应头提取 workaround
+
+`http.request()` 的 `response.header` 类型是 `Object`，ArkTS 禁止用 `[]` 索引访问：
+
+```typescript
+// ❌ 错误 — Object 不能用索引访问
+const contentType = response.header['content-type'];
+
+// ✓ 正确 — JSON 桥接
+const headerStr = JSON.stringify(response.header);
+const headerJson = JSON.parse(headerStr);
+```
+
+---
+
+## 每层代价分析
+
+| Level | 开发代价 | 维护代价 | 运行性能 | 适用场景 |
+|-------|---------|---------|---------|---------|
+| **L1 ohpm** | 低 | 低（社区维护） | 高 | 有成熟鸿蒙包的功能 |
+| **L2 原生 API** | 中 | 低（系统级） | 高 | 系统已提供基础能力 |
+| **L3 NAPI** | 高（需 C/C++ + CMake） | 中（需跟进上游） | 高 | 音视频处理、图像算法等计算密集型 |
+| **L4 WebView** | 中 | 中 | 中（JS 桥接开销） | 全景/VR/复杂编辑 UI |
+| **L5 自研** | 高 | 高 | 视实现而定 | 无任何替代方案 |
+
+---
+
+## 华为官方四类法
+
+华为推荐按以下分类处理三方库迁移：
+
+| 类型 | 描述 | 处理方式 |
+|------|------|---------|
+| **A 类** | ohpm 已有鸿蒙版 | 直接 `ohpm install` |
+| **B 类** | 无鸿蒙版但有开源替代 | 用 L2 原生 API 或 L3 NAPI |
+| **C 类** | 闭源 SDK，厂商已/将适配 | 联系厂商获取鸿蒙版 |
+| **D 类** | 无替代方案 | L5 自研或功能降级/Skip |
+
+---
+
+## 技术栈替换表填写指南
+
+迁移项目时，需为每个 Android 依赖填写替换方案表：
+
+### 步骤
+1. **提取依赖清单** — 从 `build.gradle` / `build.gradle.kts` / `libs.versions.toml` 提取所有 implementation 依赖
+2. **逐个查对照表** — 在 `library-mapping-table.md` 中查找，命中则直接填入
+3. **未命中走决策树** — 按 L1→L5 逐层尝试
+4. **闭源 SDK** — 查看 `closed-source-sdk.md` 的处理路径
+5. **标注风险等级**：🟢 低（L1-L2 有成熟替代）、🟡 中（L2-L3 API 差异大）、🔴 高（L3-L5 需重写）
+
+### 格式
+
+```markdown
+| Android 依赖 | ArkTS 替代 | Level | 风险 | 迁移类型 | 备注 |
+|-------------|-----------|-------|------|---------|------|
+| Glide 4.16.0 | @ohos/imageknife | L1 | 🟢 | Auto | ohpm install |
+| Room 2.6.0 | relationalStore @kit.ArkData | L2 | 🟢 | Semi-Auto | 手写 SQL |
+| ExoPlayer 1.1.0 | Video 组件 / AVPlayer | L2 | 🟡 | Manual | 状态机适配 |
+```
+
+---
+
+## 常见错误 vs 正确做法
+
+### 错误 1：直接搜索 npm 包
+
+```typescript
+// 错误 — npm 包在 ArkTS 中不可用
+import axios from 'axios'
+
+// 正确 — 使用 ohpm 包或原生 API
+import { http } from '@kit.NetworkKit'
+// 或
+// ohpm install @ohos/axios
+```
+
+### 错误 2：假设 Android 库有同名鸿蒙版
+
+```
+// 错误 — 直接假设存在
+ohpm install glide  // 不存在
+
+// 正确 — 先查对照表，再走决策树
+// Glide → @ohos/imageknife（L1）
+ohpm install @ohos/imageknife
+```
+
+### 错误 3：闭源 SDK 直接标记为不可迁移
+
+```
+// 错误 — 直接放弃
+微信 SDK → Skip
+
+// 正确 — 先查厂商适配状态，再考虑 JS-Bridge 过渡
+微信 SDK → 联系厂商获取鸿蒙版（类型 C）
+         → 临时方案：ArkWeb + JS-Bridge
+```
+
+---
+
+## 生成检查清单
+
+- [ ] 每个 Android 依赖都有对应的替代方案或标记 Skip
+- [ ] 每个依赖标注了 Level（L1-L5）
+- [ ] 每个依赖标注了风险等级（🟢/🟡/🔴）
+- [ ] 高风险项（🔴）有缓解策略
+- [ ] 闭源 SDK 有厂商联系记录或替代方案
+- [ ] ohpm 包安装命令正确
+- [ ] 没有使用 npm 包
+
+---
+
+## 跨 Skill 协作
+
+| 需要什么 | 读取哪里 |
+|---------|---------|
+| 网络请求替代方案代码模板 | `../system-capabilities/（按 _SKILL 索引取件）` |
+| 数据库替代方案代码模板 | `../system-capabilities/（按 _SKILL 索引取件）` |
+| 系统 API 使用指南 | `arkts-system-capabilities/SKILL.md` |
+| 验证 API 兼容性 | `本机 SDK .d.ts 声明（grep 为准）` |
+| 完整项目依赖配置 | `devecocli create` 生成的工程（宿主自带脚手架）|
+| 媒体播放 | `../system-capabilities/avplayer-guide.md` |
+| 文件下载 | `../system-capabilities/background-tasks.md` |
+| Android UI 对齐 | `../ui-alignment/README.md` |
+
+> 完整路由矩阵见 `本机 SDK .d.ts 声明（grep 为准）`
+
+---
+
+## References
+
+- `library-mapping-table.md` — 50+ 库完整对照表（7 个分类：图片/视频/网络/UI/工具/编辑/商业SDK）
+- `ohpm-search-guide.md` — ohpm 搜索渠道 + 质量评估清单 + 已验证库列表
+- `napi-compile-guide.md` — C/C++ 库交叉编译方法（CMake + oh-compile-script）
+- `closed-source-sdk.md` — 闭源 SDK 三种处理路径 + JS-Bridge 过渡方案代码模板
+- `download-api-decision.md` — http.request vs requestInStream vs request.agent 对比 + 错误码
+- 遇到版本兼容性或其他不确定的 ArkTS 知识点：grep 本机 SDK `.d.ts` 声明为准
+
+## 标准库原语映射
+`java.*`/`kotlin.*` 标准库原语（BigDecimal/BigInteger/正则/加密/日期/集合/UUID 等，非 gradle 依赖）→ 见 `stdlib-mapping-table.md`：查询优先（SDK 声明/`devecocli docs`），禁重造除非证明缺失。

package/skills/migrate-core/references/topics/library-migration/closed-source-sdk.md

@@ -0,0 +1,128 @@
+# 闭源 SDK 处理方案
+
+> 当 Android 项目使用了闭源商业 SDK，且该 SDK 没有公开源码时的处理策略。
+
+---
+
+## 三条处理路径
+
+```
+闭源 SDK X
+  ├─ 路径 A: 厂商已出/将出鸿蒙版 → 等待或催促，直接替换
+  ├─ 路径 B: JS-Bridge 过渡 → ArkWeb 加载 JS SDK，postMessage 通信
+  └─ 路径 C: 功能替代或厂商更换 → 换用有鸿蒙版的竞品
+```
+
+---
+
+## 路径 A：厂商适配
+
+**适用条件**：厂商已发布或明确计划发布鸿蒙版
+
+| SDK | 鸿蒙适配状态 | 处理 |
+|-----|------------|------|
+| 支付宝 SDK | 已适配 | 直接使用鸿蒙版 |
+| 极光推送 | 已适配 | 直接使用鸿蒙版 |
+| 友盟+ | 已适配 | 直接使用鸿蒙版 |
+| 个推 | 已适配 | 直接使用鸿蒙版 |
+| 微信 SDK | 适配中 | 联系厂商获取时间表 |
+
+**操作**：联系厂商商务或技术支持，获取鸿蒙版 SDK 和接入文档。
+
+---
+
+## 路径 B：JS-Bridge 过渡
+
+**适用条件**：
+- SDK 有 JS/Web 版本
+- 厂商鸿蒙版即将发布但项目等不及
+- 功能复杂度适中，JS 性能可接受
+
+### 代码模板
+
+```typescript
+// ArkTS 侧 — 创建 Web 组件作为桥接容器（V2，API 12+）
+@ComponentV2
+struct SdkBridge {
+  private webController: WebviewController = new WebviewController()
+  private bridgeObject: BridgeInterface = new BridgeImpl()
+
+  build() {
+    Web({ src: $rawfile('sdk_bridge.html'), controller: this.webController })
+      .javaScriptProxy({
+        object: this.bridgeObject,
+        name: 'nativeBridge',
+        methodList: ['onResult', 'onError'],
+        controller: this.webController
+      })
+      .width(0)  // 隐藏 Web 组件
+      .height(0)
+  }
+}
+
+// Bridge 接口实现
+class BridgeImpl {
+  onResult(data: string): void {
+    const result = JSON.parse(data)
+    // 处理 SDK 返回结果
+  }
+
+  onError(error: string): void {
+    // 处理错误
+  }
+}
+```
+
+```html
+<!-- resources/rawfile/sdk_bridge.html -->
+<script src="vendor-sdk.js"></script>
+<script>
+  // 调用 SDK 功能
+  function callSdkMethod(params) {
+    vendorSdk.doSomething(params, function(result) {
+      nativeBridge.onResult(JSON.stringify(result));
+    }, function(error) {
+      nativeBridge.onError(error.message);
+    });
+  }
+</script>
+```
+
+### 注意事项
+- JS-Bridge 通信是异步的，注意回调时序
+- 传输数据量大时考虑性能影响
+- 这是过渡方案，厂商发布鸿蒙版后应替换
+
+---
+
+## 路径 C：功能替代
+
+**适用条件**：
+- 厂商无鸿蒙版计划
+- 无 JS 版本可用于 Bridge
+- 存在功能等价的竞品已适配鸿蒙
+
+**操作**：
+1. 评估竞品功能覆盖度
+2. 评估迁移成本（API 差异）
+3. 商务沟通（价格、合同）
+4. 实施替换
+
+---
+
+## 决策流程
+
+```
+闭源 SDK X
+  ├─ 厂商有鸿蒙版？
+  │   ├─ 已发布 → 路径 A：直接替换
+  │   └─ 计划中 → 时间可等？
+  │       ├─ 是 → 等待 + 先用 Mock
+  │       └─ 否 → 有 JS 版本？
+  │           ├─ 是 → 路径 B：JS-Bridge 过渡
+  │           └─ 否 → 路径 C：竞品替代或功能降级
+  └─ 无鸿蒙版计划
+      └─ 有竞品已适配？
+          ├─ 是 → 路径 C：更换厂商
+          └─ 否 → 功能降级 / 标记 Skip
+```

package/skills/migrate-core/references/topics/library-migration/download-api-decision.md

@@ -0,0 +1,84 @@
+# 下载 API 选型参考
+
+> http.request vs requestInStream vs request.agent 详细对比。
+
+---
+
+## 对比表
+
+| 特性 | http.request | requestInStream | request.agent |
+|------|-------------|-----------------|---------------|
+| 文件大小限制 | ~5MB | 理论无限 | 无限制 |
+| 进度回调 | ❌ | ⚠️ 不可靠 | ✓ 稳定 |
+| 后台下载 | ❌ | ❌ | ✓ |
+| 断点续传 | ❌ | ❌ | ✓ |
+| 稳定性 | ✓ | ❌ | ✓ |
+| 适用场景 | 小文件/API | 不推荐 | **所有文件下载** |
+
+---
+
+## 错误码
+
+| 错误码 | 含义 | 解决方案 |
+|-------|------|---------|
+| 2300023 | 文件大小超限（http.request ARRAY_BUFFER） | 改用 request.agent |
+| 13900002 | ENOENT 路径不存在 | mkdirSync(dir, true) |
+| 401/403 | 未授权/禁止 | 检查 URL 权限 |
+
+---
+
+## request.agent.Config 速查
+
+```typescript
+import { request } from '@kit.BasicServicesKit';
+
+const config: request.agent.Config = {
+  action: request.agent.Action.DOWNLOAD,
+  url: cleanUrl,
+  overwrite: true,
+  saveas: './' + fileName,  // 相对于 cacheDir
+  mode: request.agent.Mode.FOREGROUND,
+  gauge: true
+};
+const task = await request.agent.create(context, config);
+task.on('progress', (p: request.agent.Progress) => {
+  const percent = Math.floor(p.sizes[0] * 100 / p.sizes[1]);
+});
+task.on('completed', () => { /* 完成 */ });
+task.on('failed', () => { /* 失败 */ });
+await task.start();
+```
+
+---
+
+## 从 http.request 迁移到 request.agent
+
+```typescript
+// 旧方案（有 5MB 限制）
+const httpReq = http.createHttp();
+try {
+  const resp = await httpReq.request(url, {
+    method: http.RequestMethod.GET,
+    expectDataType: http.HttpDataType.ARRAY_BUFFER
+  });
+  // 写入文件...
+} finally {
+  httpReq.destroy();
+}
+
+// 新方案（无限制）
+const config: request.agent.Config = {
+  action: request.agent.Action.DOWNLOAD,
+  url: url,
+  saveas: './' + fileName,
+  mode: request.agent.Mode.FOREGROUND,
+  gauge: true
+};
+const task = await request.agent.create(context, config);
+task.on('completed', () => { /* 文件已在 cacheDir */ });
+await task.start();
+```
+
+---
+
+RSS/XML 来源的 URL 先做 HTML 实体解码（&→&，否则 HTTP 400）；下载完成先 statSync 验 size>0 再入库/移动。

package/skills/migrate-core/references/topics/library-migration/library-mapping-table.md

@@ -0,0 +1,100 @@
+# 三方库完整对照表
+
+> 50+ Android 库到 ArkTS 的替代方案映射。按功能分类，每个条目标注 Level、安装方式和注意事项。
+
+---
+
+## 图片加载与显示
+
+| Android 库 | ArkTS 替代 | Level | 安装方式 | 备注 |
+|-----------|-----------|-------|---------|------|
+| Glide | `@ohos/imageknife` | L1 | `ohpm install @ohos/imageknife` | 内存+磁盘二级缓存 |
+| Picasso | `@ohos/imageknife` | L1 | 同上 | 功能覆盖 |
+| Coil | `Image` 组件 + `photoAccessHelper` | L2 | 原生 | 简单场景直接用原生 Image |
+| SubsamplingScaleImageView | `@ohos/largeimage` | L1 | `ohpm install @ohos/largeimage` | 支持缩放/拖拽/旋转 |
+| PhotoView | `Image` + `PinchGesture` | L2 | 原生 | 手动实现手势缩放 |
+| CircleImageView | `Image` + `.borderRadius('50%')` | L2 | 原生 | 原生属性即可 |
+| Android Image Cropper | `Canvas` + 手势 API | L5 | 自研 | 需自绘可拖拽裁剪框 |
+| AndroidSVG | ohos-svg | L1 | 需确认最新地址 | SVG 解析渲染 |
+| GIF Drawable | ohos_gif-drawable | L1 | 需确认最新地址 | 基于 Canvas 渲染 GIF |
+| APNG 动画库 | `ImageAnimator` 组件 | L2 | 原生 | 基础动画格式支持 |
+| WebP 解码 | `Image` 组件 | L2 | 原生 | HarmonyOS 原生支持 WebP |
+
+## 图片编辑与滤镜
+
+| Android 库 | ArkTS 替代 | Level | 安装方式 | 备注 |
+|-----------|-----------|-------|---------|------|
+| ImgLy PESDK | `Canvas` + `@kit.ImageKit` PixelMap | L5 | 自研 | 商业库无鸿蒙版 |
+| GPUImage | `@kit.ImageKit` + `effectKit` | L2 | 原生 | 基础滤镜可用 |
+| zomato/androidphotofilters | PixelMap 像素操作 | L2 | 原生 | 灰度/复古/反转可自研 |
+| Lottie | `@ohos/lottie` | L1 | `ohpm install @ohos/lottie` | Lottie 动画支持 |
+
+## 视频播放与编辑
+
+| Android 库 | ArkTS 替代 | Level | 安装方式 | 备注 |
+|-----------|-----------|-------|---------|------|
+| ExoPlayer / Media3 | `Video` 组件 / `AVPlayer` | L2 | 原生 | 状态机有差异（见踩坑 P13） |
+| IJKPlayer | `Video` 组件 / `AVPlayer` | L2 | 原生 | 同上 |
+| ImgLy VESDK | FFmpeg + 自研 UI | L3+L5 | NAPI | 商业库无鸿蒙版 |
+| FFmpeg | `HarmonyOS-tpc/FFmpeg` | L3 | HAR/NAPI | 完整 7 大核心库 |
+| GSYVideoPlayer | GSYVideoPlayer (鸿蒙版) | L1 | 需确认最新地址 | 支持多内核和滤镜 |
+| Google VR SDK | Three.js + Pannellum | L4 | ArkWeb + JS | 全景/360度视频 |
+
+## 网络与数据
+
+| Android 库 | ArkTS 替代 | Level | 安装方式 | 备注 |
+|-----------|-----------|-------|---------|------|
+| OkHttp | `@kit.NetworkKit` http | L2 | 原生 | 实例需 `destroy()` |
+| Retrofit | `@ohos/axios` 或原生 http | L1/L2 | `ohpm install @ohos/axios` | axios 提供更友好的 API |
+| Gson / Moshi | `JSON.parse` / `JSON.stringify` | L2 | 原生 | ArkTS 原生支持 |
+| Room / GreenDAO / Realm | `@kit.ArkData` relationalStore | L2 | 原生 | 手写 SQL |
+| SharedPreferences / DataStore | `@kit.ArkData` preferences | L2 | 原生 | 异步 API |
+
+## UI 框架与组件
+
+| Android 库 | ArkTS 替代 | Level | 安装方式 | 备注 |
+|-----------|-----------|-------|---------|------|
+| ConstraintLayout | `Flex`/`Stack`/`Row`/`Column` | L2 | 原生 | 声明式布局 |
+| RecyclerView | `List`/`Grid`/`WaterFlow` | L2 | 原生 | 配合 `ForEach`/`LazyForEach` |
+| ViewPager2 | `Swiper` | L2 | 原生 | 支持水平/垂直翻页 |
+| SwipeRefreshLayout | `Refresh` 组件 / `@ohos/pulltorefresh` | L1/L2 | 原生或 ohpm | 下拉刷新 |
+| Material Components | ArkUI 原生组件 | L2 | 原生 | Tabs/Dialog/Toast 等 |
+| Navigation Component | `Navigation` + `NavPathStack` | L2 | 原生 | 路由栈管理 |
+
+## 工具与基础设施
+
+| Android 库 | ArkTS 替代 | Level | 安装方式 | 备注 |
+|-----------|-----------|-------|---------|------|
+| RxJava / Coroutine | `async/await` + `Promise` | L2 | 原生 | 原生异步 |
+| EventBus | 自建 `Map<string, Function[]>` | L5 | 自研 | 简单发布订阅 |
+| WorkManager | `@kit.BackgroundTasksKit` | L2 | 原生 | 间隔约束不同 |
+| Timber / Logger | `hilog` (`@kit.PerformanceAnalysisKit`) | L2 | 原生 | 系统级日志 |
+| LeakCanary | DevEco Profiler | — | IDE 工具 | 内存分析 |
+| Sanselan / ExifInterface | `@kit.ImageKit` image.ImageSource | L2 | 原生 | EXIF 读取 |
+| JSOUP (HTML 解析) | `@ohos/htmlparser2` 或自研 | L1 | ohpm | HTML 解析 |
+| SAX Parser | `XmlPullParser` (`@ohos.xml`) | L2 | 原生 | push→pull 需重写（见踩坑 P11） |
+
+## 商业 SDK（推送/支付/地图等）
+
+| Android 库 | ArkTS 替代 | Level | 处理方式 |
+|-----------|-----------|-------|---------|
+| Firebase | AppGallery Connect | L2 | 华为对标服务 |
+| Google Maps | 华为 Map Kit | L2 | 华为对标服务 |
+| 极光推送 | 极光推送鸿蒙版 | L1 | 厂商已适配 |
+| 友盟+ | 友盟+鸿蒙版 | L1 | 厂商已适配 |
+| 个推 | 个推鸿蒙版 | L1 | 厂商已适配 |
+| 微信 SDK | 联系厂商获取鸿蒙版 | — | 类型 C：联系厂商 |
+| 支付宝 SDK | 支付宝鸿蒙版 | L1 | 已适配 |
+| BiometricPrompt | `@ohos.userIAM.userAuth` | L2 | 原生 API |
+
+---
+
+## 按 Level 汇总
+
+| Level | 数量 | 代表库 |
+|-------|------|-------|
+| **L1 ohpm** | ~12 | imageknife, largeimage, lottie, axios, pulltorefresh, 极光, 友盟, 个推, 支付宝 |
+| **L2 原生 API** | ~25 | Image, Video/AVPlayer, relationalStore, preferences, http, Canvas, Navigation, hilog... |
+| **L3 NAPI** | ~3 | FFmpeg, OpenCV, OpenSSL |
+| **L4 WebView+JS** | ~2 | Three.js(全景), Fabric.js(编辑) |
+| **L5 自研** | ~5 | EventBus, 图片裁剪框, PESDK 简化版 |

package/skills/migrate-core/references/topics/library-migration/napi-compile-guide.md

@@ -0,0 +1,84 @@
+# C/C++ 库 NAPI 交叉编译指南
+
+> 当 Level 1（ohpm）和 Level 2（原生 API）都无法满足需求时，可通过 NAPI 桥接 C/C++ 开源库。
+
+---
+
+## 适用场景
+
+- 音视频处理（FFmpeg）
+- 图像算法（OpenCV）
+- 加解密（OpenSSL）
+- 其他计算密集型的 C/C++ 库
+
+---
+
+## 方式一：CMake 构建（最常见）
+
+```bash
+cmake \
+  -DCMAKE_TOOLCHAIN_FILE=${OHOS_SDK}/native/build/cmake/ohos.toolchain.cmake \
+  -DCMAKE_BUILD_TYPE=Release \
+  -DOHOS_ARCH=arm64-v8a \
+  ..
+ninja -C build
+```
+
+### 关键环境变量
+
+| 变量 | 说明 |
+|------|------|
+| `OHOS_SDK` | HarmonyOS SDK 路径 |
+| `OHOS_ARCH` | 目标架构：`arm64-v8a`（手机）/ `armeabi-v7a` / `x86_64`（模拟器）|
+| `CMAKE_TOOLCHAIN_FILE` | SDK 自带的工具链文件 |
+
+---
+
+## 方式二：oh-compile-script（推荐）
+
+基于 Conan 2.x 的自动化编译工具，已预置 100+ 常用库的依赖管理：
+
+```bash
+git clone https://gitee.com/aspect1103/oh-compile-script.git
+pip install conan==2.x
+python3 build.py --lib=ffmpeg --arch=arm64-v8a
+```
+
+### 支持的库（部分）
+
+- FFmpeg（完整 7 大核心库）
+- OpenSSL
+- libjpeg-turbo
+- libpng
+- zlib
+- curl
+
+---
+
+## 编译产物验证
+
+```bash
+# 检查是否为 ARM aarch64 架构
+file libxxx.so       # 期望: ELF 64-bit LSB shared object, ARM aarch64
+
+# 检查导出符号
+nm -D libxxx.so | grep <目标函数>
+```
+
+---
+
+## 在 ArkTS 项目中使用
+
+1. 将 `.so` 文件放入 `entry/libs/arm64-v8a/`
+2. 编写 NAPI 绑定层（C/C++）
+3. 在 `CMakeLists.txt` 中配置
+4. ArkTS 侧通过 `import xxx from 'libxxx.so'` 调用
+
+---
+
+## 注意事项
+
+- 交叉编译的 .so 必须匹配目标设备架构
+- 模拟器用 `x86_64`，真机用 `arm64-v8a`
+- Debug 包体积会显著增大，Release 模式编译
+- 某些库可能需要禁用不支持的系统调用