@harmonyos-arkts/d2h 0.1.20 → 0.1.21

package/skills/cpp/d2h-native-library-verify/scripts/verify-ohos-native.py

@@ -0,0 +1,1099 @@
+#!/usr/bin/env python3
+"""Android 功能场景 → 鸿蒙 so/a 能力验证（按功能，从 so/a 导出符号检测能力）。
+
+理念：
+  不按 Android 每个 JNI API 做 1:1 映射，也不依赖 .d.ts 声明（声明可能与实际 so 不符）。
+  能力判定的唯一依据是 so/a 的导出符号表（llvm-nm）——这是「事实」，不是声明、不是编造：
+    · 用 llvm-nm 提取 so/a 导出符号（.so 动态符号 / .a 全局符号）
+    · 从符号检测真实能力（avcodec_/avformat_/ff_libx264_encoder/ff_rtmp_protocol/FFAudioPlayer…）
+    · 能力 ⊆ 功能所需（requires）→ 可实现/部分实现/无法实现
+    · 能实现 → NAPI 可基于真实符号自己写桥接，生成 Hypium demo 真机验证
+    · 不能实现 → 真正无法实现（so 未导出对应符号）
+
+流程：
+  ① 加载 analyse 产出的功能清单（feature-manifest.json）或直接扫描 Android 源码
+  ② llvm-nm 提取 so/a 导出符号 → detect_capabilities 检测能力（非 .d.ts）
+  ③ 每个功能场景：judge_feature(requires, detected) 判定可实现/部分实现/无法实现
+  ④ 生成 Hypium 测试用例（用 so 真实能力实现功能，文件产物断言）
+  ⑤ 输出：能力验证报告（HTML+JSON）+ 每场景 NAPI 方案（.md）+ demo 测试用例
+
+用法：
+    python3 verify-ohos-native.py --android <工程> --ohos <so或.a文件或目录> \
+        [--manifest <feature-manifest.json>] [--dts <Index.d.ts>] [--output <目录>]
+"""
+import argparse, json, os, re, sys, subprocess, html as _html
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import native_common as nc
+from native_common import (run, resolve_tool, find_elf_nm, find_llvm_readelf,
+                           find_cxxfilt, demangle_symbol, classify_feature,
+                           detect_capabilities, CAPABILITY_RULES, TOOL_INSTALL_HINTS,
+                           prefix_meaning, esc)
+
+_e = esc
+
+__version__ = "4.0.0"
+
+# ==================== Android 源码扫描 ====================
+JAVA_NATIVE_RE = re.compile(r"\bnative\s+[\w<>\[\],\s]*?(\w+)\s*\(")
+KOTLIN_EXTERNAL_RE = re.compile(r"\bexternal\s+fun\s+(\w+)\s*\(")
+PACKAGE_RE = re.compile(r"^\s*package\s+([\w.]+)", re.MULTILINE)
+LOAD_LIB_RE = re.compile(r'System\.loadLibrary\("([^"]+)"\)')
+
+def scan_android_jni(root):
+    results = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in (".git", ".gradle", "build", ".idea", "node_modules")]
+        for fn in filenames:
+            if not fn.endswith((".java", ".kt")):
+                continue
+            path = os.path.join(dirpath, fn)
+            try:
+                content = open(path, encoding="utf-8", errors="replace").read(1 << 20)
+            except OSError:
+                continue
+            pkg_m = PACKAGE_RE.search(content)
+            pkg = pkg_m.group(1) + "." if pkg_m else ""
+            stem = os.path.splitext(fn)[0]
+            full_class = pkg + stem
+            ext = os.path.splitext(fn)[1]
+            native_methods = []
+            for lineno, line in enumerate(content.splitlines(), 1):
+                m = JAVA_NATIVE_RE.search(line) if ext == ".java" else KOTLIN_EXTERNAL_RE.search(line)
+                if m:
+                    native_methods.append({"method": m.group(1), "line": lineno})
+            if native_methods:
+                results.append({
+                    "class": full_class, "file": fn, "path": path,
+                    "load_libraries": LOAD_LIB_RE.findall(content),
+                    "native_methods": native_methods,
+                    "feature": classify_feature(full_class) or "通用",
+                })
+    return results
+
+# ==================== 鸿蒙 so/a 分析 ====================
+def get_so_exports(so_path, nm_tool):
+    return nc.get_lib_exports(so_path, nm_tool)
+
+def get_so_napi_apis(so_path, nm_tool):
+    exports = get_so_exports(so_path, nm_tool)
+    is_napi = any("napi_" in s or s.startswith("napi") for s in exports)
+    return {"is_napi": is_napi, "export_count": len(exports)}
+
+def check_android_residue(so_path, nm_tool, readelf=None):
+    if readelf is None:
+        readelf = resolve_tool(["llvm-readelf", "readelf"])
+    dyn = run([readelf, "-d", "-W", so_path]) if readelf else ""
+    needed = re.findall(r"\(NEEDED\)\s+Shared library:\s*\[([^\]]+)\]", dyn)
+    android_libs = [l for l in needed if l in ("liblog.so", "libandroid.so", "libnativehelper.so", "libmediandk.so")]
+    exports = get_so_exports(so_path, nm_tool) if nm_tool else set()
+    jni_exports = [s for s in exports if s.startswith("Java_")]
+    ndk1_count = sum(1 for s in exports if "__ndk1" in s)
+    issues = []
+    if android_libs:
+        issues.append({"level": "fail", "msg": f"依赖 Android 专有库: {', '.join(android_libs)}"})
+    if jni_exports:
+        issues.append({"level": "fail", "msg": f"JNI 导出残留 {len(jni_exports)} 个（鸿蒙无 ART）"})
+    if ndk1_count > 0:
+        issues.append({"level": "warn", "msg": f"__ndk1 符号 {ndk1_count} 个（C++ ABI）"})
+    return issues, needed
+
+# ==================== 鸿蒙 .d.ts NAPI 提取 ====================
+def extract_napi_from_dts(dts_path):
+    if not dts_path or not os.path.isfile(dts_path):
+        return {}
+    try:
+        content = open(dts_path, encoding="utf-8", errors="replace").read(1 << 20)
+    except OSError:
+        return {}
+    content = re.sub(r"/\*.*?\*/", "", content, flags=re.DOTALL)
+    content = re.sub(r"//[^\n]*", "", content)
+
+    apis = {}
+    pat = re.compile(r"export\s+(namespace|class|interface|enum)\s+(\w+)")
+    i = 0
+    while True:
+        m = pat.search(content, i)
+        if not m:
+            break
+        kind, name = m.group(1), m.group(2)
+        open_brace = content.find("{", m.end())
+        if open_brace == -1:
+            i = m.end()
+            continue
+        depth = 0
+        j = open_brace
+        while j < len(content):
+            if content[j] == "{":
+                depth += 1
+            elif content[j] == "}":
+                depth -= 1
+                if depth == 0:
+                    break
+            j += 1
+        body = content[open_brace + 1:j]
+        i = j + 1
+        if kind == "namespace":
+            for fm in re.finditer(r"export\s+function\s+(\w+)\s*\(([^)]*)\)\s*(?::\s*([^;{]+))?;", body):
+                fname, params, ret = fm.group(1), fm.group(2).strip(), (fm.group(3) or "void").strip()
+                apis[f"{name}.{fname}"] = f"{fname}({params}): {ret}"
+        elif kind == "class":
+            for mm in re.finditer(r"(?:public\s+)?(\w+)\s*\(([^)]*)\)\s*(?::\s*([^;{]+))?;", body):
+                mname, params = mm.group(1), mm.group(2).strip()
+                if mname in ("get", "set", "constructor"):
+                    continue
+                apis[f"{name}.{mname}"] = f"{mname}({params})" + (f": {mm.group(3).strip()}" if mm.group(3) else "")
+            for pm in re.finditer(r"(?:public\s+)?(?:get|set)\s+(\w+)\s*\(\)\s*:\s*([^;]+);", body):
+                apis[f"{name}.{pm.group(1)}"] = f"{pm.group(1)}: {pm.group(2).strip()}"
+    return apis
+
+def find_dts_for_so(so_path):
+    dirs = [os.path.dirname(so_path)]
+    p = os.path.dirname(so_path)
+    for _ in range(5):
+        parent = os.path.dirname(p)
+        if parent == p:
+            break
+        dirs.append(parent)
+        p = parent
+    for d in dirs:
+        try:
+            entries = os.listdir(d)
+        except OSError:
+            continue
+        for e in entries:
+            if e.endswith(".d.ts") or e.endswith(".d.ets"):
+                return os.path.join(d, e)
+        for sub in ("types", "libffmpeg", "cpp"):
+            subdir = os.path.join(d, sub)
+            if os.path.isdir(subdir):
+                for dp2, _, fns in os.walk(subdir):
+                    if "node_modules" in dp2 or "oh_modules" in dp2:
+                        continue
+                    for fn in fns:
+                        if fn.endswith((".d.ts", ".d.ets")):
+                            return os.path.join(dp2, fn)
+    return None
+
+# ==================== 功能场景能力方案 ====================
+# 每个功能场景：Android 用 so 实现的功能 → 所需底层能力（requires）。
+# requires 里的能力名对应 CAPABILITY_RULES；判定完全由 so 导出符号检测结果决定：
+#   requires 全命中 → 可实现；部分命中 → 部分实现；全不命中 → 无法实现。
+# 「视频播放/渲染」「音频采样回调」等能力不在 CAPABILITY_RULES（so 未导出），故检测不到 → 判为无法实现。
+FEATURE_PLANS = {
+    "媒体格式探测(MediaRetriever)": {
+        "usage": "提取媒体元数据、生成音频波形图、提取视频帧缩略图",
+        "requires": ["封装/解封装", "音视频编解码"],
+        "plan": [
+            ("提取元数据", "FFmpeg.execute", "ffprobe -v info -of json -show_format -show_streams -i <file>"),
+            ("音频波形图", "FFmpeg.execute", "ffmpeg -i <file> -filter_complex showwavespic=s=800x400 <out.png>"),
+            ("视频帧提取", "FFmpeg.execute", "ffmpeg -ss <t> -i <file> -frames:v 1 <out.jpg>"),
+            ("缩放帧提取", "FFmpeg.execute", "ffmpeg -ss <t> -i <file> -frames:v 1 -vf scale=<w>:<h> <out.jpg>"),
+        ],
+        "note": "setSurface（视频渲染表面）非本场景核心，且需 XComponent，不纳入本功能验证",
+    },
+    "视频剪辑处理(FFmpegCmd)": {
+        "usage": "执行 ffmpeg/ffprobe 命令（剪辑、转码、探测）",
+        "requires": ["命令执行 NAPI", "音视频编解码", "封装/解封装"],
+        "plan": [
+            ("执行命令", "FFmpeg.execute", "FFmpeg.execute(['ffmpeg', '-i', in, out, '-y'])"),
+            ("探测命令", "FFmpeg.execute", "FFmpeg.execute(['ffprobe', '-i', in])"),
+            ("取消任务", "FFAbortController.abort", "FFmpeg.execute(cmds, { signal: ctrl.signal }); ctrl.abort()"),
+        ],
+    },
+    "音频播放(AudioPlayer)": {
+        "usage": "播放音频（播放/时长/位置/重播）",
+        "requires": ["音频播放 NAPI"],
+        "plan": [
+            ("播放", "FFAudioPlayer.play", "player.url = ...; player.prepare(); player.play()"),
+            ("时长", "FFAudioPlayer.duration", "player.duration"),
+            ("位置", "FFAudioPlayer.currentTime", "player.currentTime"),
+            ("重播", "FFAudioPlayer.seek", "player.seek(0); player.play()"),
+        ],
+    },
+    "直播推流(LivePusher)": {
+        "usage": "音视频实时推流到 RTMP 服务器（H.264/AAC 编码）",
+        "requires": ["H.264 编码", "AAC 编码", "RTMP 协议", "FLV 封装"],
+        "plan": [
+            ("RTMP 推流", "FFmpeg.execute",
+             "ffmpeg -re -i <input> -c:v libx264 -preset fast -c:a aac -f flv <rtmp://...>"),
+            ("H.264 编码", "FFmpeg.execute", "ffmpeg -i <in> -c:v libx264 <out.mp4>"),
+            ("AAC 编码", "FFmpeg.execute", "ffmpeg -i <in> -c:a aac <out.m4a>"),
+            ("FLV 封装", "FFmpeg.execute", "ffmpeg -i <in> -c:v libx264 -f flv <out.flv>"),
+        ],
+        "note": "libfaac.a/libx264.a 为 Android 侧编码器静态库；鸿蒙 so 内置 libx264/aac 编码器与 flv 封装，真机验证可用",
+    },
+    "视频滤镜预览(VideoPlayer)": {
+        "usage": "视频转码、滤镜处理、音频播放",
+        "requires": ["滤镜", "视频渲染"],  # 滤镜命中；视频渲染 so 未导出 → 部分实现
+        "plan": [
+            ("转码", "FFmpeg.execute", "ffmpeg -i <in> -c:v libx264 <out.mp4>"),
+            ("滤镜处理", "FFmpeg.execute", "ffmpeg -i <in> -vf <filter> <out.mp4>"),
+            ("音频播放", "FFAudioPlayer", "FFAudioPlayer 播放音轨"),
+        ],
+        "note": "filter 离线处理可用（avfilter 库存在）；实时预览需解码帧 + 渲染表面，so 未导出渲染 NAPI，需 XComponent 自建渲染管线",
+    },
+    "视频播放(NextPlayer引擎)": {
+        "usage": "视频解码 + 播放 + 渲染（25 个播放器引擎 JNI）",
+        "requires": ["视频播放/渲染"],  # so 未导出视频播放/渲染 NAPI → 无法实现
+        "plan": [],
+        "note": "so 仅导出音频播放（FFAudioPlayer），无视频解码帧 + 渲染 NAPI；需系统 @ohos.multimedia.media.AVPlayer 替代，或用 avcodec 软解 + XComponent 自建渲染管线",
+    },
+    "音频可视化(FrankVisualizer)": {
+        "usage": "捕获实时音频 PCM 数据做波形/频谱可视化",
+        "requires": ["音频采样回调"],  # so 未导出 PCM 采样回调 → 无法实现
+        "plan": [],
+        "note": "so 的 FFAudioPlayer 不暴露 PCM、FFAudioWriter 只写不读；需 @ohos.multimedia.audio.AudioRenderer on('audioData') 回调自实现 FFT",
+    },
+}
+
+VERDICT_LABEL = {
+    "可实现": "✓ 可实现",
+    "部分实现": "◐ 部分实现",
+    "需验证": "⚠ 需验证",
+    "无法实现": "✗ 无法实现",
+}
+
+def judge_feature(requires, detected):
+    """根据 so 导出符号检测到的能力，判定功能场景能否实现。"""
+    met = [r for r in requires if r in detected]
+    missing = [r for r in requires if r not in detected]
+    if not missing:
+        return "可实现", f"所需能力全部由 so 导出符号证实：{', '.join(requires)}"
+    if met:
+        return "部分实现", f"已证实能力：{', '.join(met)}；缺失（so 未导出）：{', '.join(missing)}"
+    return "无法实现", f"所需能力均未在 so 导出符号中检测到：{', '.join(missing)}"
+
+# ==================== 功能场景匹配 ====================
+def match_feature_plan(feature):
+    """按功能场景名精确匹配能力方案；未命中用通用推断。"""
+    if feature in FEATURE_PLANS:
+        return FEATURE_PLANS[feature]
+    f = feature.lower()
+    if any(k in f for k in ["推流", "live", "rtmp"]):
+        return {"usage": feature, "requires": ["RTMP 协议", "FLV 封装", "H.264 编码", "AAC 编码"], "plan": []}
+    if any(k in f for k in ["播放", "player", "video"]):
+        return {"usage": feature, "requires": ["视频播放/渲染"], "plan": []}
+    if any(k in f for k in ["可视化", "visual", "fft"]):
+        return {"usage": feature, "requires": ["音频采样回调"], "plan": []}
+    return {"usage": feature, "requires": ["命令执行 NAPI"], "plan": []}
+
+# ==================== NAPI 名验证（对照 so 导出符号，非 .d.ts）====================
+# plan 里的 NAPI 接口名 → 对应的能力（能力从 so 导出符号检测）
+NAPI_CLASS_TO_CAPABILITY = {
+    "FFmpeg": "命令执行 NAPI",
+    "FFAudioPlayer": "音频播放 NAPI",
+    "FFAudioWriter": "音频写入 NAPI",
+    "FFAbortController": "任务取消 NAPI",
+    "FFAbortSignal": "任务取消 NAPI",
+}
+
+def verify_plan_napi(plan, detected):
+    """验证 plan 每个步骤的 NAPI 名对应的能力是否被 so 导出符号证实。
+
+    返回 {napi_name: status}，status:
+      declared —— 对应能力已被 so 导出符号检测到（真实存在）
+      missing  —— so 导出符号中无对应类/接口（不能写 NAPI 桥接，不能编造）
+    """
+    verified = {}
+    for step, napi, code in (plan or []):
+        cls = napi.split(".")[0]
+        cap = NAPI_CLASS_TO_CAPABILITY.get(cls, cls)
+        verified[napi] = "declared" if cap in detected else "missing"
+    return verified
+
+
+# ==================== Hypium 测试用例生成 ====================
+def generate_hypium_case(feature, verdict, reason=""):
+    """为功能场景生成 Hypium 断言用例（用鸿蒙 so NAPI 实现功能）。"""
+    name = re.sub(r"[^\w]", "_", feature)
+    if verdict == "无法实现":
+        return {
+            "test_name": f"{name}_no_ohos_api",
+            "code": None,
+            "assert": "unverifiable",
+            "comment": reason,
+        }
+    # 可实现/部分实现/需验证 → 生成可运行的测试代码（占位，由 demo 生成器填入）
+    return {
+        "test_name": f"{name}_capability",
+        "code": None,
+        "assert": "runtime",
+    }
+
+HYPIUM_HEADER = '''import { describe, it, expect, beforeAll } from '@ohos/hypium';
+import { FFmpeg, FFAbortController, FFAudioPlayer } from '@sj/ffmpeg';
+import { abilityDelegatorRegistry } from '@kit.TestKit';
+import { common } from '@kit.AbilityKit';
+import { fileIo as fs } from '@kit.CoreFileKit';
+
+let filesDir = '';
+let wav = '';
+
+function run(cmd: string[]): Promise<string> {
+  return new Promise<string>((resolve) => {
+    let out = '';
+    FFmpeg.execute(cmd, {
+      logCallback: (msg: string) => { out += msg; },
+      outputCallback: (msg: string) => { out += msg; },
+    }).then(() => resolve(out)).catch((e: Error) => resolve('ERR:' + e.message));
+  });
+}
+
+function fileExists(p: string): boolean {
+  try { fs.accessSync(p); return true; } catch (e) { return false; }
+}
+'''
+
+# 每个功能场景 → Hypium 测试用例代码（用鸿蒙 so NAPI 实现功能并断言）
+HYPIUM_SCENARIO_TESTS = {
+    "视频剪辑处理(FFmpegCmd)": '''
+    // ==== 视频剪辑处理(FFmpegCmd) — 可实现：FFmpeg.execute 命令执行 + 文件产物 ====
+    it('FFmpegCmd_handle_executes', 0, async () => {
+      await run(['ffmpeg', '-f', 'lavfi', '-i', 'color=c=red:s=64x64:d=1', `${filesDir}/handle_test.mp4`, '-y']);
+      const ok = fileExists(`${filesDir}/handle_test.mp4`);
+      console.info(`[NATIVE_TEST] FFmpegCmd_handle ok=${ok}`);
+      expect(ok).assertTrue();
+    });
+    it('FFmpegCmd_handleProbe_executes', 0, async () => {
+      const out = await run(['ffprobe', '-i', wav]);
+      console.info(`[NATIVE_TEST] FFmpegCmd_handleProbe out=${out.slice(0, 60)}`);
+      expect(out.length).assertLarger(0);
+    });
+    it('FFmpegCmd_cancelTask_abort', 0, async () => {
+      const c = new FFAbortController();
+      const p = FFmpeg.execute(['ffmpeg', '-f', 'lavfi', '-i', 'testsrc=duration=10:size=320x240:rate=30', '-c:v', 'libx264', `${filesDir}/abort.mp4`, '-y'],
+        { signal: c.signal, logCallback: (msg: string) => {} });
+      setTimeout(() => { c.abort(); }, 500);
+      let aborted = false;
+      try { await p; } catch (err) { aborted = true; }
+      console.info(`[NATIVE_TEST] FFmpegCmd_cancelTask aborted=${aborted}`);
+      expect(aborted).assertTrue();
+    });
+''',
+    "音频播放(AudioPlayer)": '''
+    // ==== 音频播放(AudioPlayer) — 可实现：FFAudioPlayer ====
+    it('AudioPlayer_play', 0, async () => {
+      const p = new FFAudioPlayer();
+      p.url = `file://${wav}`;
+      p.prepare();
+      await new Promise<void>((r) => setTimeout(r, 1500));
+      p.play();
+      await new Promise<void>((r) => setTimeout(r, 800));
+      const playing = p.playWhenReady;
+      p.pause();
+      console.info(`[NATIVE_TEST] AudioPlayer_play playing=${playing}`);
+      expect(playing).assertTrue();
+    });
+    it('AudioPlayer_duration', 0, async () => {
+      const p = new FFAudioPlayer();
+      p.url = `file://${wav}`;
+      p.prepare();
+      await new Promise<void>((r) => setTimeout(r, 1500));
+      console.info(`[NATIVE_TEST] AudioPlayer_duration duration=${p.duration}`);
+      expect(p.duration).assertLarger(0);
+    });
+    it('AudioPlayer_position', 0, async () => {
+      const p = new FFAudioPlayer();
+      p.url = `file://${wav}`;
+      p.prepare();
+      await new Promise<void>((r) => setTimeout(r, 1500));
+      p.play();
+      await new Promise<void>((r) => setTimeout(r, 500));
+      const pos = p.currentTime;
+      p.pause();
+      console.info(`[NATIVE_TEST] AudioPlayer_position pos=${pos}`);
+      expect(pos).assertLargerOrEqual(0);
+    });
+    it('AudioPlayer_again_replay', 0, async () => {
+      const p = new FFAudioPlayer();
+      p.url = `file://${wav}`;
+      p.prepare();
+      await new Promise<void>((r) => setTimeout(r, 1500));
+      p.play();
+      await new Promise<void>((r) => setTimeout(r, 500));
+      p.seek(0);
+      p.play();
+      const playing = p.playWhenReady;
+      p.pause();
+      console.info(`[NATIVE_TEST] AudioPlayer_again_replay playing=${playing}`);
+      expect(playing).assertTrue();
+    });
+''',
+    "媒体格式探测(MediaRetriever)": '''
+    // ==== 媒体格式探测(MediaRetriever) — 可实现：FFmpeg.execute 跑 ffprobe/ffmpeg ====
+    it('MediaRetriever_extractMetadata', 0, async () => {
+      const out = await run(['ffprobe', '-v', 'info', '-of', 'json', '-show_format', '-i', wav]);
+      console.info(`[NATIVE_TEST] MediaRetriever_metadata len=${out.length}`);
+      expect(out).assertContain('format');
+    });
+    it('MediaRetriever_getFrameAtTime', 0, async () => {
+      await run(['ffmpeg', '-f', 'lavfi', '-i', 'color=c=red:s=64x64:d=1', `${filesDir}/gen.mp4`, '-y']);
+      await run(['ffmpeg', '-ss', '0', '-i', `${filesDir}/gen.mp4`, '-frames:v', '1', `${filesDir}/frame.jpg`, '-y']);
+      let ok = false;
+      try { fs.accessSync(`${filesDir}/frame.jpg`); ok = true; } catch (e) { ok = false; }
+      console.info(`[NATIVE_TEST] MediaRetriever_frame ok=${ok}`);
+      expect(ok).assertTrue();
+    });
+    it('MediaRetriever_getScaleFrameAtTime', 0, async () => {
+      await run(['ffmpeg', '-ss', '0', '-i', `${filesDir}/gen.mp4`, '-frames:v', '1',
+        '-vf', 'scale=32:32', `${filesDir}/frame_small.jpg`, '-y']);
+      let ok = false;
+      try { fs.accessSync(`${filesDir}/frame_small.jpg`); ok = true; } catch (e) { ok = false; }
+      console.info(`[NATIVE_TEST] MediaRetriever_scaleFrame ok=${ok}`);
+      expect(ok).assertTrue();
+    });
+''',
+    "视频滤镜预览(VideoPlayer)": '''
+    // ==== 视频滤镜预览(VideoPlayer) — 部分实现：转码可用，filter 实时预览需渲染管线 ====
+    it('VideoPlayer_executeTranscode', 0, async () => {
+      const out = `${filesDir}/t.m4a`;
+      await run(['ffmpeg', '-i', wav, out, '-y']);
+      let ok = false;
+      try { fs.accessSync(out); ok = true; } catch (e) { ok = false; }
+      console.info(`[NATIVE_TEST] VideoPlayer_transcode ok=${ok}`);
+      expect(ok).assertTrue();
+    });
+''',
+    "直播推流(LivePusher)": '''
+    // ==== 直播推流(LivePusher) — 需验证：用文件产物验证 H.264/AAC 编码 + FLV 封装 ====
+    it('LivePusher_check_h264_encoder', 0, async () => {
+      await run(['ffmpeg', '-f', 'lavfi', '-i', 'color=c=red:s=64x64:d=1', '-c:v', 'libx264', `${filesDir}/h264.mp4`, '-y']);
+      const ok = fileExists(`${filesDir}/h264.mp4`);
+      console.info(`[NATIVE_TEST] LivePusher_h264 ok=${ok}`);
+      expect(ok).assertTrue();
+    });
+    it('LivePusher_check_aac_encoder', 0, async () => {
+      await run(['ffmpeg', '-i', wav, '-c:a', 'aac', `${filesDir}/aac.m4a`, '-y']);
+      const ok = fileExists(`${filesDir}/aac.m4a`);
+      console.info(`[NATIVE_TEST] LivePusher_aac ok=${ok}`);
+      expect(ok).assertTrue();
+    });
+    it('LivePusher_check_flv_muxer', 0, async () => {
+      await run(['ffmpeg', '-f', 'lavfi', '-i', 'color=c=red:s=64x64:d=1', '-c:v', 'libx264', `${filesDir}/test.flv`, '-y']);
+      const ok = fileExists(`${filesDir}/test.flv`);
+      console.info(`[NATIVE_TEST] LivePusher_flv ok=${ok}`);
+      expect(ok).assertTrue();
+    });
+''',
+}
+
+HYPIUM_BEFOREALL = '''
+export default function ffmpegVerifyTest() {
+  describe('FFmpegVerify', () => {
+    beforeAll(async () => {
+      const delegator = abilityDelegatorRegistry.getAbilityDelegator();
+      const ability = await delegator.getCurrentTopAbility();
+      const ctx = ability.context as common.UIAbilityContext;
+      filesDir = ctx.filesDir;
+      wav = `${filesDir}/ffmpeg_test.wav`;
+      const raw = await ctx.resourceManager.getRawFileContent('ffmpeg_test.wav');
+      const f = fs.openSync(wav, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE);
+      fs.writeSync(f.fd, raw.buffer);
+      fs.closeSync(f);
+    });
+'''
+
+# 每个功能场景 → Hypium 测试用例的期望结果（key 与 console.info 的 [NATIVE_TEST] 短名一致）
+TEST_EXPECTATIONS = {
+    "MediaRetriever_metadata": "ffprobe 输出含 format 元数据",
+    "MediaRetriever_frame": "生成帧图片 frame.jpg",
+    "MediaRetriever_scaleFrame": "生成缩放帧图片",
+    "LivePusher_h264": "libx264 编码生成 H.264 文件",
+    "LivePusher_aac": "aac 编码生成音频文件",
+    "LivePusher_flv": "FLV 封装生成文件",
+    "FFmpegCmd_handle": "ffmpeg 命令执行生成文件",
+    "FFmpegCmd_handleProbe": "ffprobe 输出探测信息",
+    "FFmpegCmd_cancelTask": "abort 中断任务 aborted=true",
+    "VideoPlayer_transcode": "转码生成 m4a 文件",
+    "AudioPlayer_play": "播放状态 playing=true",
+    "AudioPlayer_duration": "时长 duration > 0",
+    "AudioPlayer_position": "位置 currentTime >= 0",
+    "AudioPlayer_again_replay": "重播后 playing=true",
+}
+
+def generate_hypium_test_file(scenarios):
+    """生成按功能场景组织的 Hypium 测试文件（FFmpegVerify.test.ets）。"""
+    lines = [HYPIUM_HEADER]
+    lines.append(HYPIUM_BEFOREALL)
+    for s in scenarios:
+        code = HYPIUM_SCENARIO_TESTS.get(s["feature"])
+        if code:
+            lines.append(code)
+        else:
+            v = s["verdict"]
+            if v == "无法实现":
+                lines.append(f"    // ==== {s['feature']} — 无法实现：{s['reason']} ====")
+                lines.append(f"    // unverifiable 登记：鸿蒙 so 未导出对应 NAPI 能力；{s.get('note','')}")
+                lines.append("")
+            else:
+                lines.append(f"    // ==== {s['feature']} — {v}：无预置测试代码 ====")
+                lines.append("")
+    lines.append("  });")
+    lines.append("}")
+    return "\n".join(lines)
+
+# ==================== 真实运行证据 ====================
+def parse_evidence(log_path):
+    """解析运行日志 run.log，返回每个测试的结果 + 汇总。"""
+    if not log_path or not os.path.isfile(log_path):
+        return None
+    try:
+        content = open(log_path, encoding="utf-8", errors="replace").read()
+    except OSError:
+        return None
+    results = {}
+    for m in re.finditer(r"\[NATIVE_TEST\]\s+(\w+)\s+(.+)", content):
+        results[m.group(1)] = m.group(2).strip()
+    m = re.search(r"Tests run:\s*(\d+),\s*Failure:\s*(\d+),\s*Error:\s*(\d+),\s*Pass:\s*(\d+)", content)
+    summary = None
+    if m:
+        summary = {"run": int(m.group(1)), "failure": int(m.group(2)),
+                   "error": int(m.group(3)), "pass": int(m.group(4))}
+    return {"tests": results, "summary": summary}
+
+# ==================== NAPI 方案（Markdown）====================
+def render_napi_plan_md(feature, plan, libs, jni_methods):
+    lines = [f"# {feature} — NAPI 实现方案", ""]
+    lines.append(f"> 判定：**{VERDICT_LABEL[plan['verdict']]}**")
+    lines.append("")
+    lines.append(f"- **Android 功能用途**：{plan['usage']}")
+    lines.append(f"- **涉及的 so/a**：{', '.join(libs) if libs else '—'}")
+    lines.append(f"- **判定依据**：{plan['reason']}")
+    lines.append("")
+    if plan["capabilities"]:
+        lines.append("## 依赖的能力（so 导出符号已证实）")
+        for c in plan["capabilities"]:
+            lines.append(f"- {c}")
+        lines.append("")
+    if plan["plan"]:
+        lines.append("## 实现步骤（NAPI 名经 so 符号验证）")
+        lines.append("")
+        lines.append("| 步骤 | 鸿蒙 NAPI | so 符号验证 | 用法 |")
+        lines.append("|------|-----------|-----------|------|")
+        napi_verified = plan.get("napi_verified", {})
+        for step, napi, code in plan["plan"]:
+            v = napi_verified.get(napi, "")
+            mark = {"declared": "✓ 符号证实", "missing": "✗ 未证实"}.get(v, "—")
+            lines.append(f"| {step} | `{napi}` | {mark} | `{code}` |")
+        lines.append("")
+    if plan.get("note"):
+        lines.append(f"## 说明")
+        lines.append(plan["note"])
+        lines.append("")
+    if jni_methods:
+        lines.append("## 对应的 Android JNI 面")
+        for jm in jni_methods:
+            lines.append(f"- `{jm['class'].split('.')[-1]}.{jm['method']}`")
+    return "\n".join(lines)
+
+# ==================== HTML ====================
+HTML_CSS = """<style>
+body{font-family:-apple-system,"PingFang SC",sans-serif;margin:0;background:#f6f7f9;color:#1a1a2e}
+.hd{background:linear-gradient(135deg,#1a2a4a,#2d4a7a);color:#fff;padding:22px 30px}
+.hd h1{margin:0 0 6px;font-size:21px}
+.hd .m{font-size:12px;opacity:.85}
+.ct{max-width:1200px;margin:18px auto;padding:0 14px}
+details{background:#fff;border-radius:10px;margin-bottom:10px;box-shadow:0 1px 3px rgba(0,0,0,.08);overflow:hidden}
+summary{padding:14px 16px;cursor:pointer;font-weight:600;font-size:15px}
+.bd{padding:0 16px 14px}
+table{width:100%;border-collapse:collapse;font-size:13px;margin:6px 0}
+th,td{text-align:left;padding:6px 10px;border-bottom:1px solid #eee;vertical-align:top}
+th{background:#fafafa;font-size:12px;color:#555}
+.b{display:inline-block;padding:2px 10px;border-radius:12px;font-size:12px;font-weight:600}
+.bg{background:#e6f7e6;color:#1a7a1a}.br{background:#fdeaea;color:#c0392b}.by{background:#fff7e0;color:#9a6d00}.bl{background:#e8f0fe;color:#1a56c4}
+.tag{display:inline-block;margin:2px 3px 2px 0;padding:2px 8px;border-radius:4px;font-size:11px;background:#f0f2f5}
+code{background:#f0f2f5;padding:1px 5px;border-radius:4px;font-size:12px;word-break:break-all;overflow-wrap:anywhere}
+pre{background:#f6f8fa;padding:10px;border-radius:6px;font-size:12px;overflow-x:auto}
+.mu{color:#888;font-size:12px}
+.cards{display:flex;gap:10px;flex-wrap:wrap;margin-bottom:16px}
+.card{background:#fff;border-radius:10px;padding:12px 18px;box-shadow:0 1px 3px rgba(0,0,0,.08);min-width:110px}
+.card .n{font-size:26px;font-weight:700}
+.card .l{font-size:11px;color:#666}
+.tabbar{display:flex;gap:6px;overflow-x:auto;margin:0 auto 14px;max-width:1200px;padding:0 14px;-webkit-overflow-scrolling:touch;scrollbar-width:none}
+.tabbar::-webkit-scrollbar{display:none}
+.tabbtn{flex:0 0 auto;padding:8px 18px;border-radius:18px;border:1px solid #d0d5dd;background:#fff;font-size:13px;cursor:pointer;white-space:nowrap;color:#333;font-weight:500}
+.tabbtn:hover{background:#f0f4ff}
+.tabbtn.active{background:#1a56c4;color:#fff;border-color:#1a56c4}
+.tab-content{display:none}
+.tab-content.active{display:block}
+.filterbar{display:flex;gap:8px;align-items:center;flex-wrap:wrap;margin:0 auto 14px;max-width:1200px;padding:0 14px}
+.searchbox{flex:1;min-width:200px;padding:8px 14px;border-radius:18px;border:1px solid #d0d5dd;font-size:13px;outline:none}
+.searchbox:focus{border-color:#1a56c4}
+.filterbtn{padding:6px 14px;border-radius:16px;border:1px solid #d0d5dd;background:#fff;font-size:12px;cursor:pointer;color:#555;white-space:nowrap}
+.filterbtn.active{background:#1a56c4;color:#fff;border-color:#1a56c4}
+details.scene-detail.hidden{display:none}
+</style>"""
+
+HTML_JS = """<script>
+function switchTab(idx) {
+  var btns = document.querySelectorAll('.tabbtn');
+  var contents = document.querySelectorAll('.tab-content');
+  for (var i = 0; i < btns.length; i++) {
+    btns[i].classList.toggle('active', i === idx);
+  }
+  for (var j = 0; j < contents.length; j++) {
+    contents[j].classList.toggle('active', j === idx);
+  }
+  applyFilter();
+}
+
+var currentFilter = '全部';
+
+function setFilter(btn) {
+  currentFilter = btn.getAttribute('data-verdict');
+  var btns = document.querySelectorAll('.filterbtn');
+  for (var i = 0; i < btns.length; i++) {
+    btns[i].classList.toggle('active', btns[i].getAttribute('data-verdict') === currentFilter);
+  }
+  applyFilter();
+}
+
+function applyFilter() {
+  var kw = (document.getElementById('searchbox').value || '').toLowerCase();
+  var items = document.querySelectorAll('details.scene-detail');
+  for (var i = 0; i < items.length; i++) {
+    var it = items[i];
+    var verdict = it.getAttribute('data-verdict');
+    var text = it.textContent.toLowerCase();
+    var matchV = currentFilter === '全部' || verdict === currentFilter;
+    var matchK = !kw || text.indexOf(kw) >= 0;
+    it.classList.toggle('hidden', !(matchV && matchK));
+  }
+}
+</script>"""
+
+def _verdict_badge(verdict):
+    return {
+        "可实现": '<span class="b bg">✓ 可实现</span>',
+        "部分实现": '<span class="b by">◐ 部分实现</span>',
+        "需验证": '<span class="b bl">⚠ 需验证</span>',
+        "无法实现": '<span class="b br">✗ 无法实现</span>',
+    }.get(verdict, f'<span class="b">{_e(verdict)}</span>')
+
+def render_html(payload):
+    ohos_libs = payload.get("ohos_libs", {})
+    rules_desc = {r["name"]: r["desc"] for r in payload.get("capability_rules", [])}
+    lib_names = list(ohos_libs.keys())
+
+    def scenario_table(scs):
+        out = ['<details open><summary>📋 功能能力判定</summary><div class="bd">',
+               '<table><tr><th>功能场景</th><th>Android 用途</th><th>判定</th><th>已证实能力</th><th>无法实现的能力</th><th>JNI 数</th></tr>']
+        for s in scs:
+            ok_caps = " ".join(f'<span class="tag" style="background:#e6f7e6;color:#1a7a1a">{_e(c)}</span>' for c in s.get("capabilities", [])) or '<span class="mu">—</span>'
+            miss_caps = " ".join(f'<span class="tag" style="background:#fdeaea;color:#c0392b">{_e(c)}</span>' for c in s.get("missing_capabilities", [])) or '<span class="mu">—</span>'
+            out.append(f'<tr><td><b>{_e(s["feature"])}</b></td>'
+                       f'<td>{_e(s["usage"])}</td>'
+                       f'<td>{_verdict_badge(s["verdict"])}</td>'
+                       f'<td>{ok_caps}</td><td>{miss_caps}</td><td>{s["total_jni"]}</td></tr>')
+        out.append('</table></div></details>')
+        return "\n".join(out)
+
+    def scenario_details(scs):
+        out = []
+        for s in scs:
+            out.append(f'<details class="scene-detail" data-verdict="{_e(s["verdict"])}">'
+                       f'<summary>{_e(s["feature"])} {_verdict_badge(s["verdict"])} '
+                       f'<span class="mu">({s["total_jni"]} JNI · {"、".join(s["libs"]) if s["libs"] else "无 so"})</span></summary><div class="bd">')
+            out.append(f'<p><b>判定依据</b>：{_e(s["reason"])}</p>')
+            if s.get("capabilities"):
+                out.append('<p><b>已证实能力</b>：' + " ".join(f'<span class="b bg">{_e(c)}</span>' for c in s["capabilities"]) + '</p>')
+            if s.get("missing_capabilities"):
+                out.append('<p><b>无法实现的能力</b>：' + " ".join(f'<span class="b br">{_e(c)}</span>' for c in s["missing_capabilities"]) + '</p>')
+            if s["plan"]:
+                out.append('<table><tr><th>功能步骤</th><th>鸿蒙 NAPI（so 符号验证）</th><th>实现用法</th></tr>')
+                napi_verified = s.get("napi_verified", {})
+                for step, napi, code in s["plan"]:
+                    v = napi_verified.get(napi, "")
+                    badge = {"declared": '<span class="b bg">✓ 符号证实</span>',
+                             "missing": '<span class="b br">✗ 未证实</span>'}.get(v, '<span class="mu">—</span>')
+                    out.append(f'<tr><td><b>{_e(step)}</b></td>'
+                               f'<td><code>{_e(napi)}</code><br>{badge}</td>'
+                               f'<td><code>{_e(code)}</code></td></tr>')
+                out.append('</table>')
+            if s.get("note"):
+                out.append(f'<p class="mu">说明：{_e(s["note"])}</p>')
+            if s["jni_methods"]:
+                out.append('<details><summary>对应的 Android JNI 面</summary><div class="bd"><ul>')
+                for jm in s["jni_methods"]:
+                    out.append(f'<li><code>{_e(jm["class"].split(".")[-1])}.{_e(jm["method"])}</code> <span class="mu">({",".join(jm.get("libs", []))})</span></li>')
+                out.append('</ul></div></details>')
+            out.append('</div></details>')
+        return "\n".join(out)
+
+    def capabilities(lib_info):
+        lib_detected = lib_info.get("detected", {})
+        cxxfilt = find_cxxfilt()
+        out = ['<details open><summary>🧩 能力清单</summary><div class="bd">']
+        for r in lib_info.get("android_residue", []):
+            color = "#c0392b" if r.get("level") == "fail" else "#9a6d00"
+            out.append(f'<p class="mu" style="color:{color}">⚠ {_e(r.get("msg", ""))}</p>')
+        if lib_detected:
+            out.append('<table><tr><th>能力</th><th>命中符号（证据）</th><th>说明</th></tr>')
+            for cap_name, symbol in lib_detected.items():
+                demangled = demangle_symbol(symbol, cxxfilt)
+                short = demangled if len(demangled) <= 60 else demangled[:60] + "…"
+                out.append(f'<tr><td><b>{_e(cap_name)}</b></td>'
+                           f'<td><code title="{_e(symbol)}">{_e(short)}</code></td>'
+                           f'<td>{_e(rules_desc.get(cap_name, ""))}</td></tr>')
+            out.append('</table>')
+        else:
+            out.append('<p class="mu">未检测到已知能力</p>')
+        # 未识别符号前缀聚类（自动发现未纳入规则的库）
+        clusters = lib_info.get("unknown_clusters", [])
+        if clusters:
+            out.append('<details><summary>🔍 未纳入规则的符号前缀（可能的能力线索）</summary><div class="bd">')
+            tags = " ".join(
+                f'<span class="tag">{_e(p)}{"（" + _e(prefix_meaning(p)) + "）" if prefix_meaning(p) else ""} ×{c}</span>'
+                for p, c in clusters)
+            out.append(f'<p class="mu">{tags}</p>')
+            out.append('</div></details>')
+        out.append('</div></details>')
+        return "\n".join(out)
+
+    h = ['<!DOCTYPE html><html lang="zh"><head><meta charset="utf-8">',
+         '<title>Android 功能 → 鸿蒙 so 能力验证报告</title>', HTML_CSS, HTML_JS,
+         '</head><body><div class="hd">',
+         '<h1>Android 功能场景 → 鸿蒙 so 能力验证报告</h1>',
+         '<div class="m">tool %s · 按 so/a 划分能力验证（非逐 API 映射）</div></div>' % _e(payload.get("tool_version"))]
+
+    # 全局卡片
+    h.append('<div class="ct"><div class="cards">')
+    for label, val, color in [("so/a 文件", len(lib_names), "#1a56c4")]:
+        h.append(f'<div class="card"><div class="n" style="color:{color}">{val}</div><div class="l">{label}</div></div>')
+    # 真机验证门禁卡片（通过/失败/未进行 三态）
+    ev = payload.get("evidence")
+    gate = payload.get("summary", {}).get("真机验证门禁", "未进行")
+    if ev and ev.get("summary"):
+        es = ev["summary"]
+        if es["pass"] == es["run"] and es["run"] > 0:
+            g_color, g_label = "#1a7a1a", "✅ 真机验证通过"
+        else:
+            g_color, g_label = "#c0392b", "❌ 真机验证失败"
+        h.append(f'<div class="card"><div class="n" style="color:{g_color}">{es["pass"]}/{es["run"]}</div>'
+                 f'<div class="l">{g_label}</div></div>')
+    else:
+        h.append(f'<div class="card"><div class="n" style="color:#9a6d00">—</div>'
+                 f'<div class="l">⚠ 未真机验证</div></div>')
+    h.append('</div>')
+
+    # Tab 栏：每个 so/a
+    h.append('<div class="tabbar">')
+    for i, name in enumerate(lib_names):
+        active = ' active' if i == 0 else ''
+        h.append(f'<button class="tabbtn{active}" onclick="switchTab({i})">📦 {_e(name)}</button>')
+    h.append('</div>')
+
+    # 搜索 + 筛选（作用于当前 tab 的场景详情）
+    h.append('<div class="filterbar">')
+    h.append('<input id="searchbox" class="searchbox" type="text" placeholder="搜索功能场景 / JNI 方法..." oninput="applyFilter()">')
+    h.append('<button class="filterbtn active" data-verdict="全部" onclick="setFilter(this)">全部</button>')
+    for v in ("可实现", "部分实现", "无法实现"):
+        h.append(f'<button class="filterbtn" data-verdict="{v}" onclick="setFilter(this)">{v}</button>')
+    h.append('</div>')
+
+    # 每个 so/a tab：功能判定 + 场景详情 + 能力清单
+    for i, name in enumerate(lib_names):
+        lib_info = ohos_libs[name]
+        lib_scenarios = lib_info.get("scenarios", [])
+        active = ' active' if i == 0 else ''
+        h.append(f'<div class="tab-content{active}">')
+        h.append(f'<h3 style="margin:4px 0 10px">📦 {_e(name)}</h3>')
+        h.append(scenario_table(lib_scenarios))
+        h.append(scenario_details(lib_scenarios))
+        h.append(capabilities(lib_info))
+        h.append('</div>')
+
+    # 真实运行验证证据（始终显示，合并验证）
+    ev = payload.get("evidence")
+    if ev and ev.get("tests"):
+        h.append('<details><summary>🔬 真实运行验证证据（Hypium 测试）</summary><div class="bd">')
+        h.append('<table><tr><th>测试用例</th><th>期望结果</th><th>真实结果</th></tr>')
+        for name, result in sorted(ev["tests"].items()):
+            expected = TEST_EXPECTATIONS.get(name, "—")
+            actual = result if len(result) <= 64 else result[:64] + "…"
+            h.append(f'<tr><td><code>{_e(name)}</code></td>'
+                     f'<td>{_e(expected)}</td>'
+                     f'<td><code>{_e(actual)}</code></td></tr>')
+        h.append('</table></div></details>')
+
+    h.append('</div></body></html>')
+    return "\n".join(h)
+
+
+# ==================== 主流程 ====================
+def main():
+    parser = argparse.ArgumentParser(description="Android 功能场景 → 鸿蒙 so/a 能力验证（按功能，非按 API）")
+    parser.add_argument("--android", required=True, help="Android 工程目录")
+    parser.add_argument("--ohos", required=True, help="鸿蒙 so/a 文件或目录")
+    parser.add_argument("--manifest", help="analyse 产出的 feature-manifest.json（可选，有则直接用）")
+    parser.add_argument("--dts", help="鸿蒙 so 的 .d.ts 声明文件（可选，自动查找）")
+    parser.add_argument("--output", help="输出目录（默认 <工程名>-native-reports/）")
+    parser.add_argument("--device", help="真机验证：设备序列号（触发编译+安装+运行+采集证据）")
+    parser.add_argument("--demo", help="真机验证：demo 工程目录（默认 <输出目录>/../<工程名>-verify-demo）")
+    parser.add_argument("--media-source", help="真机验证：提供 media 图标的工程目录（如 cppdemoHarmony）")
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args()
+
+    android_root = os.path.abspath(args.android)
+    ohos_path = os.path.abspath(args.ohos)
+    if not os.path.isdir(android_root):
+        print("Android 工程不存在:", android_root)
+        return 2
+
+    # 收集鸿蒙 so/a
+    ohos_libs = {}
+    if os.path.isfile(ohos_path):
+        ohos_libs[os.path.basename(ohos_path)] = {"path": ohos_path}
+    else:
+        for dp, dns, fns in os.walk(ohos_path):
+            for fn in fns:
+                if fn.endswith((".so", ".a")) and (dp == ohos_path or "arm64" in dp or "ohos" in dp or fn in os.listdir(ohos_path)):
+                    if fn not in ohos_libs:
+                        ohos_libs[fn] = {"path": os.path.join(dp, fn)}
+
+    if not ohos_libs:
+        print("未找到鸿蒙 .so/.a 文件")
+        return 2
+
+    # 校验能解析 ELF 的 nm 工具（能力检测的核心依赖，缺失直接报错）
+    nm_tool = find_elf_nm()
+    if not nm_tool:
+        print("错误：未找到能解析 ELF 的 llvm-nm / GNU nm 工具")
+        print("安装方法：")
+        print("  ① DevEco Studio（推荐）：https://developer.huawei.com/consumer/cn/deveco-studio/")
+        print("     （装好后脚本自动探测 /Applications/DevEco-Studio.app/Contents/sdk，或设置 OHOS_SDK_HOME / DEVECO_SDK_HOME）")
+        print("  ② macOS：brew install llvm")
+        print("  ③ Linux：sudo apt install binutils")
+        return 2
+
+    # readelf 用于 Android 残留检查（辅助，缺失仅告警不中断）
+    readelf = find_llvm_readelf()
+    if not readelf:
+        print("警告：未找到 llvm-readelf/readelf，跳过 Android 残留检查")
+        print(f"      安装方法：{TOOL_INSTALL_HINTS['llvm-readelf']}")
+
+    all_exports = set()
+    for name, info in ohos_libs.items():
+        exports = get_so_exports(info["path"], nm_tool)
+        info["exports"] = exports
+        info["export_count"] = len(exports)
+        info["is_napi"] = any("napi_" in s or s.startswith("napi") for s in exports)
+        info["detected"] = detect_capabilities(exports)
+        info["capability_count"] = len(info["detected"])
+        info["unknown_clusters"] = nc.cluster_unknown_symbols(exports, 15)
+        all_exports |= exports
+        issues, needed = check_android_residue(info["path"], nm_tool, readelf)
+        info["android_residue"] = issues
+        info["needed"] = needed
+
+    # 合并所有 so/a 的能力（用于功能场景判定）
+    detected = detect_capabilities(all_exports)
+    print(f"共 {len(ohos_libs)} 个 so/a，导出符号 {len(all_exports)} 个 → 合并能力 {len(detected)} 项")
+    for name, info in ohos_libs.items():
+        print(f"  {name}: {info['export_count']} 符号 → {info['capability_count']} 项能力")
+
+    # .d.ts 仅作参考（可选），不作为能力判定依据
+    dts_path = args.dts
+    if not dts_path:
+        first_so = next(iter(ohos_libs.values()))["path"]
+        dts_path = find_dts_for_so(first_so)
+    napi_interfaces = extract_napi_from_dts(dts_path) if dts_path else {}
+    if dts_path:
+        print(f"参考 .d.ts: {dts_path}（{len(napi_interfaces)} 接口，仅参考）")
+
+    # 加载功能场景
+    jni_to_libs = {}
+    if args.manifest and os.path.isfile(args.manifest):
+        manifest = json.load(open(args.manifest))
+        features = manifest.get("features", [])
+        for f in features:
+            for jm in f.get("jni_methods", []):
+                jni_to_libs[f'{jm.get("class","")}.{jm.get("method","")}'] = jm.get("libs", []) or f.get("involved_libs", [])
+        print(f"从 analyse 产物加载 {len(features)} 个功能场景")
+    else:
+        features = None
+        print("直接扫描 Android 源码...")
+
+    scenario_jni = {}
+    if features:
+        for f in features:
+            scenario_jni.setdefault(f["feature"], []).extend(f.get("jni_methods", []))
+    else:
+        for cls in scan_android_jni(android_root):
+            feat = cls["feature"] or "通用"
+            for nm in cls["native_methods"]:
+                scenario_jni.setdefault(feat, []).append(
+                    {"class": cls["class"], "method": nm["method"]})
+
+    # 功能场景定义（feat_name → jni_methods + libs + plan）
+    scene_defs = []
+    for feat_name in sorted(scenario_jni):
+        jni_methods = scenario_jni[feat_name]
+        libs = sorted({l for jm in jni_methods for l in (jm.get("libs") or jni_to_libs.get(f'{jm["class"]}.{jm["method"]}', []))})
+        plan = match_feature_plan(feat_name)
+        scene_defs.append((feat_name, jni_methods, libs, plan))
+
+    # 合并所有 so/a 的能力（用于 napi-plans / demo 生成）
+    detected = detect_capabilities(all_exports)
+
+    # 合并场景判定（供 JSON + napi-plans + demo）
+    scenarios = []
+    for feat_name, jni_methods, libs, plan in scene_defs:
+        verdict, reason = judge_feature(plan.get("requires", []), detected)
+        scenarios.append({
+            "feature": feat_name, "usage": plan["usage"], "verdict": verdict, "reason": reason,
+            "requires": plan.get("requires", []),
+            "capabilities": [r for r in plan.get("requires", []) if r in detected],
+            "missing_capabilities": [r for r in plan.get("requires", []) if r not in detected],
+            "plan": plan["plan"], "napi_verified": verify_plan_napi(plan["plan"], detected),
+            "note": plan.get("note", ""), "total_jni": len(jni_methods),
+            "jni_methods": jni_methods, "libs": libs,
+            "hypium": generate_hypium_case(feat_name, verdict, reason),
+        })
+
+    # 每个 so/a 单独判定功能场景（按 so 划分，非合并能力）
+    for lib_name, lib_info in ohos_libs.items():
+        lib_detected = lib_info.get("detected", {})
+        lib_scenarios = []
+        for feat_name, jni_methods, libs, plan in scene_defs:
+            v, reason = judge_feature(plan.get("requires", []), lib_detected)
+            lib_scenarios.append({
+                "feature": feat_name, "usage": plan["usage"], "verdict": v, "reason": reason,
+                "requires": plan.get("requires", []),
+                "capabilities": [r for r in plan.get("requires", []) if r in lib_detected],
+                "missing_capabilities": [r for r in plan.get("requires", []) if r not in lib_detected],
+                "plan": plan["plan"], "napi_verified": verify_plan_napi(plan["plan"], lib_detected),
+                "note": plan.get("note", ""), "total_jni": len(jni_methods),
+                "jni_methods": jni_methods, "libs": libs,
+            })
+        lib_info["scenarios"] = lib_scenarios
+
+    ok = sum(1 for s in scenarios if s["verdict"] == "可实现")
+    partial = sum(1 for s in scenarios if s["verdict"] == "部分实现")
+    verify = sum(1 for s in scenarios if s["verdict"] == "需验证")
+    fail = len(scenarios) - ok - partial - verify
+
+    # 输出目录（提前确定，供 evidence 读取）
+    out_dir = os.path.abspath(args.output) if args.output else os.path.join(
+        os.path.dirname(android_root), os.path.basename(android_root) + "-native-reports")
+    os.makedirs(out_dir, exist_ok=True)
+
+    # Hypium 测试用例（提前生成，真机验证需要）
+    demo_dir = os.path.join(out_dir, "demo-tests")
+    os.makedirs(demo_dir, exist_ok=True)
+    test_ets = os.path.join(demo_dir, "FFmpegVerify.test.ets")
+    with open(test_ets, "w") as f:
+        f.write(generate_hypium_test_file(scenarios))
+
+    # 真机验证门禁：自动检测设备，连真机则自动触发（也可用 --device 显式指定）
+    device = args.device
+    if device in (None, "auto"):
+        devices = nc.list_devices()
+        if devices:
+            device = devices[0]
+            print(f"检测到设备 {device}，自动加入真机验证门禁")
+    if device:
+        dv_script = os.path.join(os.path.dirname(os.path.abspath(__file__)), "device-verify.py")
+        demo_proj = args.demo or os.path.join(os.path.dirname(out_dir), os.path.basename(android_root) + "-verify-demo")
+        first_so = next(iter(ohos_libs.values()))["path"]
+        run_log = os.path.join(out_dir, "verify-evidence", "run.log")
+        cmd = [sys.executable, dv_script, "--demo", demo_proj, "--test-ets", test_ets,
+               "--so", first_so, "--output", run_log]
+        if device != "auto":
+            cmd += ["--device", device]
+        # media 图标来源：显式指定，或自动在同级目录找带 media 的鸿蒙工程
+        media_source = args.media_source
+        if not media_source:
+            parent = os.path.dirname(android_root)
+            for cand in ("cppdemoHarmony", "ProtobufDemoOhos", "CalculatorExampleOhos"):
+                p = os.path.join(parent, cand)
+                if os.path.isdir(os.path.join(p, "AppScope", "resources", "base", "media")):
+                    media_source = p
+                    break
+        if media_source:
+            cmd += ["--media-source", media_source]
+        print("=" * 72)
+        print("真机验证门禁：编译 demo → 签名 → 安装 → 运行 14 个 Hypium 用例 → 采集证据")
+        print("=" * 72)
+        subprocess.run(cmd)
+    else:
+        print("未检测到设备，跳过真机验证门禁（报告将标注「未真机验证」）")
+
+    # 真实运行证据（run.log）
+    evidence = parse_evidence(os.path.join(out_dir, "verify-evidence", "run.log"))
+
+    # 真机验证门禁状态
+    device_gate = "未进行"
+    if evidence and evidence.get("summary"):
+        es = evidence["summary"]
+        if es["pass"] == es["run"] and es["run"] > 0:
+            device_gate = f"通过（{es['pass']}/{es['run']}）"
+        else:
+            device_gate = f"失败（{es['pass']}/{es['run']}）"
+
+    payload = {
+        "tool_version": __version__,
+        "android_root": android_root,
+        "ohos_libs": {k: {"path": v["path"], "is_napi": v.get("is_napi"),
+                           "export_count": v.get("export_count", 0),
+                           "detected": v.get("detected", {}),
+                           "capability_count": v.get("capability_count", 0),
+                           "scenarios": v.get("scenarios", []),
+                           "unknown_clusters": v.get("unknown_clusters", []),
+                           "android_residue": v.get("android_residue", [])} for k, v in ohos_libs.items()},
+        "dts_path": dts_path,
+        "napi_interface_count": len(napi_interfaces),
+        "so_export_count": len(all_exports),
+        "detected_capabilities": detected,
+        "capability_rules": [{"name": n, "pattern": p, "desc": d} for n, p, d in CAPABILITY_RULES],
+        "scenarios": scenarios,
+        "evidence": evidence,
+        "summary": {
+            "total_scenarios": len(scenarios),
+            "可实现": ok, "部分实现": partial, "需验证": verify, "无法实现": fail,
+            "真机验证门禁": device_gate,
+        },
+    }
+
+    # 输出
+    os.makedirs(out_dir, exist_ok=True)
+
+    json_path = os.path.join(out_dir, "capability-report.json")
+    with open(json_path, "w") as f:
+        json.dump(payload, f, ensure_ascii=False, indent=2)
+
+    html_path = os.path.join(out_dir, "capability-report.html")
+    with open(html_path, "w") as f:
+        f.write(render_html(payload))
+
+    # 每场景 NAPI 方案 .md
+    plans_dir = os.path.join(out_dir, "napi-plans")
+    os.makedirs(plans_dir, exist_ok=True)
+    for s in scenarios:
+        md = render_napi_plan_md(s["feature"], s, s["libs"], s["jni_methods"])
+        fname = re.sub(r"[^\w\u4e00-\u9fff]+", "-", s["feature"]).strip("-") + ".md"
+        with open(os.path.join(plans_dir, fname), "w") as f:
+            f.write(md)
+
+    # 控制台摘要
+    print("=" * 72)
+    print("Android 功能场景 → 鸿蒙 so/a 能力验证  (tool %s)" % __version__)
+    print("功能场景: %d | ✓ 可实现: %d | ◐ 部分: %d | ⚠ 需验证: %d | ✗ 无法实现: %d" % (
+        len(scenarios), ok, partial, verify, fail))
+    print("JSON: %s" % json_path)
+    print("HTML: %s" % html_path)
+    print("NAPI 方案: %s/" % plans_dir)
+    print("Hypium 测试: %s" % test_ets)
+    print("=" * 72)
+    for s in scenarios:
+        print(f"  {VERDICT_LABEL[s['verdict']]:<10} {s['feature']}  ({s['total_jni']} JNI)")
+    print("=" * 72)
+
+    if args.json:
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())