@harmonyos-arkts/d2h 0.1.19 → 0.1.21

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

@@ -0,0 +1,91 @@
+---
+name: d2h-native-library-analyse
+description: Android 应用功能清单分析：从 Android 工程源码提取用户功能场景 → 每个场景的 JNI native 方法 → 每个方法涉及的 .so/.a 文件。自顶向下分析：① 扫描 Java/Kotlin 源码提取 native 声明和调用上下文 ② 通过 loadLibrary → CMake target_link_libraries → 实际文件三级关联（含间接 LibraryLoader 和同包前缀兜底）③ 按用户场景（视频播放/音频播放/直播推流/媒体转码等）分组。输出 feature-manifest.html（给人看，功能维度）+ feature-manifest.json（给 AI 映射，机器可读）。当用户要求「分析 Android 工程用了哪些 so」「功能涉及哪些原生库」「生成功能清单」「JNI 和 so 的对应关系」时触发。
+---
+
+# Android 应用功能清单 → JNI → so/a 文件分析
+
+## 一、分析链条（自顶向下）
+
+```
+用户功能场景（视频播放/音频播放/直播推流/媒体转码…）
+  → JNI native 方法（Java/Kotlin 中的 native/external fun 声明）
+    → 涉及的 .so/.a 文件（通过 loadLibrary → CMake 依赖 → 实际文件）
+```
+
+## 二、快速用法
+
+```bash
+# 完整分析
+python3 scripts/analyse-android-so.py <Android工程目录>
+
+# 指定输出目录
+python3 scripts/analyse-android-so.py <工程> --output <目录>
+
+# JSON 输出（给 AI 映射）
+python3 scripts/analyse-android-so.py <工程> --json
+```
+
+产出（默认 `<工程名>-native-reports/`）：
+- `feature-manifest.html` — 给人看，页面结构自上而下：
+  1. **📦 工程内全部 .so/.a 文件**（去重后同名多 ABI 优先保留 arm64-v8a，含**迁移分级**（🔴阻断/🟡需适配/🟢干净）/架构/路径/被哪些功能使用，悬停显示分级原因）
+  2. **📋 功能 → 原生库对照表**
+  3. 各功能详情卡片（JNI 方法清单 + 涉及库）
+- `feature-manifest.json` — 给 AI 映射（`features[]` + `all_libs[]`，机器可读）
+
+## 三、so/a 关联策略（三级）
+
+| 优先级 | 策略 | 示例 |
+|--------|------|------|
+| ① 直接 | 类自身 `System.loadLibrary("media-handle")` → CMake `target_link_libraries(media-handle ffmpeg)` → `libffmpeg.so` | FFmpegCmd |
+| ② 间接 | LibraryLoader 类加载 → `loadLibrary("nextplayer")` → CMake nextplayer→ffmpeg | NextPlayer |
+| ③ 同模块 | 同包前缀（前 3 段相同）其他类的 loadLibrary | FrankVisualizer → AudioPlayer 的 media-handle |
+| ④ JNI 符号 | .so 导出表中直接匹配 `Java_` 符号 | 备用 |
+
+CMake 解析：去 `#` 注释后多行匹配 `target_link_libraries(target dep1 dep2 ...)`，过滤 NDK 系统库（log/android/jnigraphics 等）。
+
+## 四、场景识别
+
+从 Java 类名推断用户场景（精确匹配优先，Activity 名兜底）：
+
+| 类名关键词 | 场景 | 用户操作 |
+|-----------|------|----------|
+| `NextPlayer` | 视频播放(NextPlayer引擎) | 播放视频/网络流 |
+| `VideoPlayer` | 视频滤镜预览 | 预览滤镜效果 |
+| `AudioPlayer` | 音频播放 | 播放音频文件 |
+| `FFmpegCmd` | 视频剪辑处理 | 转码/压缩/加水印 |
+| `MediaRetriever` | 媒体格式探测 | 获取时长/截图/元数据 |
+| `LivePusher` | 直播推流 | 摄像头→编码→RTMP推流 |
+| `Visualizer` | 音频可视化 | 实时频谱/波形 |
+
+## 五、输出 JSON 结构
+
+```json
+{
+  "features": [
+    {
+      "feature": "视频剪辑处理(FFmpegCmd)",
+      "jni_methods": [
+        {"class": "com.frank.ffmpeg.FFmpegCmd", "method": "handle",
+         "jni_symbol": "Java_com_frank_ffmpeg_FFmpegCmd_handle",
+         "operation": "execute", "file": "FFmpegCmd.java", "line": 139,
+         "libs": ["libffmpeg.so"]}
+      ],
+      "involved_libs": ["libffmpeg.so"],
+      "source_files": ["FFmpegCmd.java"]
+    }
+  ]
+}
+```
+
+## 六、约束
+
+- 只读分析，不修改任何文件
+- so/a 关联是推断性的（基于 loadLibrary + CMake 依赖链），可能有误报/漏报
+- 编译期产物（如 NextPlayer 的 libnextplayer.so）在仓库内无 .so 文件，正确显示为空（通过间接策略仍可关联到 CMake 依赖的 libffmpeg.so）
+- 功能场景识别基于类名关键词，未识别的类归「其他」
+
+## 七、参考文件
+
+- [scripts/analyse-android-so.py](scripts/analyse-android-so.py)：分析脚本
+- 输出目录默认 `<工程名>-native-reports/`