@harmonyos-arkts/d2h 0.1.20 → 0.1.21

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

@@ -0,0 +1,304 @@
+#!/usr/bin/env python3
+"""真机验证编排：准备 demo 工程 → 编译 → 签名 → 安装 → 运行 → 采集证据。
+
+让 verify 的静态能力判定得到真机运行证据支撑（14 个 Hypium 用例真实跑通）。
+
+流程：
+  ① 准备 demo 工程（复制模板 + 补 media 图标 + 生成测试 wav + 集成测试用例 + 替换待测 so）
+  ② ohpm install（装 @sj/ffmpeg 依赖）
+  ③ hvigorw 编译 app + ohosTest 两个 HAP（模板已带签名材料，自动签名）
+  ④ hdc install 两个 HAP
+  ⑤ aa test 运行 Hypium 用例
+  ⑥ hilog 采集 NATIVE_TEST 证据 → run.log
+
+用法：
+    python3 device-verify.py --demo <demo工程目录> --test-ets <FFmpegVerify.test.ets> \
+        --so <待测so> [--media-source <带media图标的工程>] [--device <序列号>] --output <run.log>
+"""
+import argparse
+import os
+import re
+import shutil
+import subprocess
+import sys
+import wave
+import struct
+import math
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+TEMPLATE = os.path.join(HERE, "..", "references", "demo-project-template")
+
+TOOL_PATHS = {
+    "ohpm": ["/Applications/DevEco-Studio.app/Contents/tools/ohpm/bin/ohpm"],
+    "hvigorw": ["/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw.js"],
+    "hdc": ["/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains/hdc"],
+}
+
+
+def find_tool(name):
+    p = shutil.which(name)
+    if p:
+        return p
+    for c in TOOL_PATHS.get(name, []):
+        if os.path.isfile(c):
+            return c
+    return None
+
+
+def run(cmd, cwd=None, shell=True, env=None):
+    return subprocess.run(cmd, shell=shell, cwd=cwd, stdout=subprocess.PIPE,
+                          stderr=subprocess.STDOUT, text=True, errors="replace", env=env)
+
+
+def gen_test_wav(path, seconds=2, rate=44100):
+    """生成 2 秒 440Hz 正弦波 wav（测试音频，供 FFAudioPlayer / 转码用例）。"""
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with wave.open(path, "w") as w:
+        w.setnchannels(1)
+        w.setsampwidth(2)
+        w.setframerate(rate)
+        frames = bytearray()
+        for i in range(rate * seconds):
+            v = int(12000 * math.sin(2 * math.pi * 440 * i / rate))
+            frames += struct.pack("<h", v)
+        w.writeframes(bytes(frames))
+
+
+def prepare_demo(demo_dir, test_ets, so_path, media_source):
+    """从模板复制 demo 工程，补 media 图标、wav、测试用例、待测 so。"""
+    if not os.path.isdir(TEMPLATE):
+        print("demo 模板不存在:", TEMPLATE)
+        return False
+    print(f"① 准备 demo 工程: {demo_dir}")
+    if os.path.exists(demo_dir):
+        shutil.rmtree(demo_dir)
+    shutil.copytree(TEMPLATE, demo_dir)
+
+    # 补 media 图标（从 media_source 工程复制）
+    if media_source and os.path.isdir(media_source):
+        for rel in [
+            "AppScope/resources/base/media",
+            "entry/src/main/resources/base/media",
+        ]:
+            src = os.path.join(media_source, rel)
+            dst = os.path.join(demo_dir, rel)
+            if os.path.isdir(src):
+                os.makedirs(dst, exist_ok=True)
+                for fn in os.listdir(src):
+                    shutil.copy2(os.path.join(src, fn), os.path.join(dst, fn))
+                print(f"  补 media: {rel}")
+        # 修正 app.json5 的 icon 引用（模板引用 app_icon，但分层图标是 layered_image）
+        app_json = os.path.join(demo_dir, "AppScope", "app.json5")
+        if os.path.isfile(app_json):
+            s = open(app_json).read().replace("$media:app_icon", "$media:layered_image")
+            open(app_json, "w").write(s)
+
+    # 生成测试 wav
+    wav_path = os.path.join(demo_dir, "entry/src/main/resources/rawfile/ffmpeg_test.wav")
+    gen_test_wav(wav_path)
+    print("  生成测试 wav: rawfile/ffmpeg_test.wav")
+
+    # 集成测试用例
+    dst_test = os.path.join(demo_dir, "entry/src/ohosTest/ets/test/FFmpegVerify.test.ets")
+    shutil.copy2(test_ets, dst_test)
+    print("  集成测试用例: FFmpegVerify.test.ets")
+
+    # 自动回填签名材料（模板是占位符；从本机 ~/.ohos/config/ + 已签名工程取真实材料）
+    fill_signing_configs(demo_dir)
+
+    # 记录待测 so（编译后替换 oh_modules 里的 so）
+    demo_dir_meta = os.path.join(demo_dir, ".verify-so.txt")
+    with open(demo_dir_meta, "w") as f:
+        f.write(so_path)
+    return True
+
+
+def fill_signing_configs(demo_dir):
+    """模板签名配置是占位符；从本机 DevEco 自动签名材料（~/.ohos/config/）+ 已签名工程的
+    build-profile.json5 回填真实路径与密文密码（机制同 references/demo-build-sign-run.md）。"""
+    bp = os.path.join(demo_dir, "build-profile.json5")
+    if not os.path.isfile(bp):
+        return
+    s = open(bp, encoding="utf-8").read()
+    if "<SIGNING_DIR>" not in s:
+        return  # 已有真实材料（如 --demo 指向已配置好的工程）
+    cfg_dir = os.path.expanduser("~/.ohos/config")
+    if not os.path.isdir(cfg_dir):
+        print("  ⚠ 未找到 ~/.ohos/config 签名材料，真机验证可能编译失败（参考 references/demo-build-sign-run.md 手动配置）")
+        return
+    # 找与 bundleName 匹配的最新一套 .cer/.p12/.p7b（default_<Bundle>_<hash>.xxx）
+    app_json = os.path.join(demo_dir, "AppScope", "app.json5")
+    bundle = ""
+    if os.path.isfile(app_json):
+        m = re.search(r'"bundleName"\s*:\s*"([^"]+)"', open(app_json, encoding="utf-8").read())
+        if m:
+            bundle = m.group(1)
+    stem = bundle.split(".")[-1] if bundle else ""
+    candidates = []
+    for fn in os.listdir(cfg_dir):
+        if fn.endswith(".p7b") and (not stem or stem in fn):
+            p7b = os.path.join(cfg_dir, fn)
+            base = p7b[:-4]
+            if os.path.isfile(base + ".cer") and os.path.isfile(base + ".p12"):
+                candidates.append((os.path.getmtime(p7b), base))
+    if not candidates:
+        # 兜底：不带 bundle 过滤，取最新一套
+        for fn in os.listdir(cfg_dir):
+            if fn.endswith(".p7b"):
+                p7b = os.path.join(cfg_dir, fn)
+                base = p7b[:-4]
+                if os.path.isfile(base + ".cer") and os.path.isfile(base + ".p12"):
+                    candidates.append((os.path.getmtime(p7b), base))
+    if not candidates:
+        print("  ⚠ ~/.ohos/config 无完整签名三件套（.cer/.p12/.p7b），真机验证可能编译失败")
+        return
+    _, base = max(candidates)
+    # 密文密码无法自造：从本机已签名工程的 build-profile.json5 里取同材料（hash 相同）的密文
+    pw = ""
+    stem_hash = os.path.basename(base).split("_", 2)[-1] if base.count("_") >= 2 else ""
+    for dp, dns, fns in os.walk(os.path.expanduser("~/Desktop")):
+        dns[:] = [d for d in dns if d not in ("oh_modules", "build", "node_modules", ".git")]
+        if os.path.basename(dp) != "":
+            for fn in fns:
+                if fn == "build-profile.json5" and stem_hash and stem_hash in open(os.path.join(dp, fn), encoding="utf-8", errors="replace").read(1 << 16):
+                    mp = re.search(r"keyPassword:\s*'([0-9a-f]+)'", open(os.path.join(dp, fn), encoding="utf-8", errors="replace").read(1 << 16))
+                    if mp:
+                        pw = mp.group(1)
+                        break
+        if pw:
+            break
+    if not pw:
+        print("  ⚠ 未能从本机已签名工程取回密文密码，真机验证可能编译失败（参考 demo-build-sign-run.md）")
+        return
+    s = (s.replace("<SIGNING_DIR>/<project>.cer", base + ".cer")
+          .replace("<SIGNING_DIR>/<project>.p7b", base + ".p7b")
+          .replace("<SIGNING_DIR>/<project>.p12", base + ".p12")
+          .replace("<KEY_PASSWORD>", pw)
+          .replace("<STORE_PASSWORD>", pw))
+    open(bp, "w", encoding="utf-8").write(s)
+    print(f"  回填签名材料: {os.path.basename(base)}")
+
+
+def ohpm_install(demo_dir):
+    ohpm = find_tool("ohpm")
+    if not ohpm:
+        print("警告：未找到 ohpm，跳过依赖安装（假设已存在）")
+        return True
+    print("② ohpm install @sj/ffmpeg ...")
+    r = run(f'"{ohpm}" install', cwd=demo_dir)
+    if r.returncode != 0:
+        print("  ohpm install 输出:", r.stdout[-500:])
+    return r.returncode == 0
+
+
+def replace_so(demo_dir, so_path):
+    """把待测 so 替换到 oh_modules 的 libffmpeg.so。"""
+    if not so_path or not os.path.isfile(so_path):
+        return
+    targets = []
+    for dp, dns, fns in os.walk(os.path.join(demo_dir, "oh_modules")):
+        for fn in fns:
+            if fn == "libffmpeg.so":
+                targets.append(os.path.join(dp, fn))
+    if targets:
+        for t in targets:
+            shutil.copy2(so_path, t)
+        print(f"  替换待测 so: {len(targets)} 处")
+
+
+def build(demo_dir):
+    hvigorw = find_tool("hvigorw")
+    if not hvigorw:
+        print("错误：未找到 hvigorw（需安装 DevEco Studio）")
+        return False
+    node = shutil.which("node")
+    env = dict(os.environ)
+    env["DEVECO_SDK_HOME"] = env.get("DEVECO_SDK_HOME", "/Applications/DevEco-Studio.app/Contents/sdk")
+    # 先停残留 daemon（避免上次编译的 daemon cwd 已被删导致的 ENOENT）
+    run(f'{node} "{hvigorw}" --stop-daemon', cwd=demo_dir, env=env)
+    print("③ 编译 app HAP ...")
+    r1 = run(f'{node} "{hvigorw}" --mode module -p product=default assembleHap',
+             cwd=demo_dir, env=env)
+    if r1.returncode != 0:
+        print("  app 编译失败:", r1.stdout[-800:])
+        return False
+    print("  编译 ohosTest HAP ...")
+    r2 = run(f'{node} "{hvigorw}" --mode module -p module=entry@ohosTest -p product=default assembleHap',
+             cwd=demo_dir, env=env)
+    if r2.returncode != 0:
+        print("  ohosTest 编译失败:", r2.stdout[-800:])
+        return False
+    return True
+
+
+def install_and_run(demo_dir, device, bundle="com.example.protobufdemo", module="entry_test"):
+    hdc = find_tool("hdc")
+    if not hdc:
+        print("错误：未找到 hdc")
+        return False
+    if not device:
+        r = run(f'"{hdc}" list targets')
+        lines = [l.strip() for l in r.stdout.splitlines() if l.strip()]
+        if not lines:
+            print("错误：无连接设备")
+            return False
+        device = lines[0]
+    app_hap = os.path.join(demo_dir, "entry/build/default/outputs/default/entry-default-signed.hap")
+    test_hap = os.path.join(demo_dir, "entry/build/default/outputs/ohosTest/entry-ohosTest-signed.hap")
+    print(f"④ 安装 HAP 到设备 {device} ...")
+    run(f'"{hdc}" -t {device} install -r "{app_hap}"')
+    run(f'"{hdc}" -t {device} install -r "{test_hap}"')
+    print("⑤ 运行 Hypium 测试 ...")
+    r = run(f'"{hdc}" -t {device} shell aa test -b {bundle} -m {module} '
+            f'-s unittest OpenHarmonyTestRunner -s timeout 120000')
+    print("  测试结果:", r.stdout.strip().splitlines()[-1] if r.stdout.strip() else "(空)")
+    return True
+
+
+def collect(device, output):
+    hdc = find_tool("hdc")
+    if not hdc or not device:
+        return False
+    r = run(f'"{hdc}" -t {device} shell "hilog -x"')
+    lines = [l for l in r.stdout.splitlines()
+             if "NATIVE_TEST" in l or "OHOS_REPORT_RESULT" in l]
+    if lines:
+        os.makedirs(os.path.dirname(output), exist_ok=True)
+        with open(output, "w") as f:
+            f.write("\n".join(lines) + "\n")
+        print(f"⑥ 采集证据: {output}（{len(lines)} 行）")
+        return True
+    print("警告：未采集到 NATIVE_TEST 日志")
+    return False
+
+
+def main():
+    ap = argparse.ArgumentParser(description="真机验证编排")
+    ap.add_argument("--demo", required=True, help="demo 工程目录")
+    ap.add_argument("--test-ets", required=True, help="Hypium 测试用例文件")
+    ap.add_argument("--so", required=True, help="待测 so 路径")
+    ap.add_argument("--media-source", help="提供 media 图标的工程目录")
+    ap.add_argument("--device", help="设备序列号")
+    ap.add_argument("--output", required=True, help="证据输出 run.log")
+    args = ap.parse_args()
+
+    if not prepare_demo(args.demo, args.test_ets, args.so, args.media_source):
+        return 1
+    ohpm_install(args.demo)
+    replace_so(args.demo, args.so)
+    if not build(args.demo):
+        return 1
+    # 拿到设备序列号（install_and_run 内部可能解析）
+    hdc = find_tool("hdc")
+    device = args.device
+    if not device and hdc:
+        r = run(f'"{hdc}" list targets')
+        lines = [l.strip() for l in r.stdout.splitlines() if l.strip()]
+        device = lines[0] if lines else None
+    install_and_run(args.demo, device)
+    collect(device, args.output)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,341 @@
+#!/usr/bin/env python3
+"""d2h-native-library 两个 skill 共享的工具/能力检测模块。
+
+供 d2h-native-library-analyse 和 d2h-native-library-verify 复用：
+  - 工具发现（llvm-nm / llvm-readelf / c++filt，自动探测 DevEco SDK / Android NDK 路径）
+  - 场景分类（classify_feature，Java 类名 → 功能场景）
+  - 能力检测（CAPABILITY_RULES：从 so/a 导出符号检测真实能力）
+  - 符号 demangle（C++ mangled 名 → 可读的 FFAV::FFAudioPlayer::Play(...)）
+"""
+import html as _html
+import os
+import re
+import shutil
+import subprocess
+
+# ==================== 工具发现 ====================
+TOOL_INSTALL_HINTS = {
+    "llvm-nm": "① DevEco Studio（推荐）https://developer.huawei.com/consumer/cn/deveco-studio/  "
+               "② macOS: brew install llvm  ③ Linux: sudo apt install binutils",
+    "llvm-readelf": "① DevEco Studio（推荐）https://developer.huawei.com/consumer/cn/deveco-studio/  "
+                    "② macOS: brew install llvm  ③ Linux: sudo apt install binutils",
+    "c++filt": "① DevEco Studio（自带 llvm-cxxfilt）  ② macOS: 系统自带 /usr/bin/c++filt  ③ Linux: sudo apt install binutils",
+}
+
+
+def run(cmd):
+    try:
+        return subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
+                              text=True, errors="replace").stdout
+    except OSError:
+        return ""
+
+
+def sdk_bin_dirs():
+    """返回可能包含 llvm-nm/llvm-readelf/c++filt 的 SDK bin 目录列表。"""
+    dirs = []
+    home = os.path.expanduser("~")
+
+    def add(d):
+        if d and os.path.isdir(d):
+            dirs.append(d)
+
+    # Android NDK
+    for env in ("ANDROID_NDK_HOME", "ANDROID_NDK_ROOT"):
+        v = os.environ.get(env)
+        if v:
+            add(os.path.join(v, "toolchains/llvm/prebuilt"))
+    sdk = os.environ.get("ANDROID_HOME")
+    if sdk:
+        ndk = os.path.join(sdk, "ndk")
+        if os.path.isdir(ndk):
+            for v in os.listdir(ndk):
+                add(os.path.join(ndk, v, "toolchains/llvm/prebuilt"))
+    # DevEco / OpenHarmony SDK
+    for env in ("OHOS_SDK_HOME", "DEVECO_SDK_HOME"):
+        v = os.environ.get(env)
+        if v:
+            for sub in ("default/openharmony/native/llvm/bin",
+                        "openharmony/native/llvm/bin", "native/llvm/bin"):
+                add(os.path.join(v, sub))
+    add("/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/native/llvm/bin")
+    add("/Applications/DevEco-Studio.app/Contents/sdk/default/hms/native/BiSheng/bin")
+    add(os.path.join(home, "Library/OpenHarmony/Sdk"))
+    return dirs
+
+
+def resolve_tool(names):
+    for n in names:
+        p = shutil.which(n)
+        if p:
+            return p
+    for d in sdk_bin_dirs():
+        for n in names:
+            c = os.path.join(d, n)
+            if os.path.isfile(c):
+                return c
+    return None
+
+
+def _is_elf_nm(nm_path):
+    """判断 nm 能否解析 ELF：llvm-nm 可以；GNU nm 可以；macOS 旧版 /usr/bin/nm（Mach-O）不行。"""
+    if not nm_path:
+        return False
+    if "llvm-nm" in os.path.basename(nm_path):
+        return True
+    try:
+        out = subprocess.run([nm_path, "--version"], stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
+                             text=True, errors="replace").stdout
+        return "GNU" in out or "llvm-nm" in out
+    except Exception:
+        return False
+
+
+def find_elf_nm():
+    """找一个能解析 ELF 的 nm 工具（llvm-nm 优先，GNU nm 次之）。找不到返回 None。"""
+    p = shutil.which("llvm-nm")
+    if p:
+        return p
+    for d in sdk_bin_dirs():
+        c = os.path.join(d, "llvm-nm")
+        if os.path.isfile(c):
+            return c
+    p = shutil.which("nm")
+    if p and _is_elf_nm(p):
+        return p
+    return None
+
+
+def find_llvm_readelf():
+    p = shutil.which("llvm-readelf")
+    if p:
+        return p
+    for d in sdk_bin_dirs():
+        c = os.path.join(d, "llvm-readelf")
+        if os.path.isfile(c):
+            return c
+    p = shutil.which("readelf")
+    if p:
+        return p
+    return None
+
+
+def find_cxxfilt():
+    """找一个 demangle 工具（c++filt 优先，llvm-cxxfilt 次之）。找不到返回 None。"""
+    for n in ("c++filt", "llvm-cxxfilt"):
+        p = shutil.which(n)
+        if p:
+            return p
+    for d in sdk_bin_dirs():
+        for n in ("c++filt", "llvm-cxxfilt"):
+            c = os.path.join(d, n)
+            if os.path.isfile(c):
+                return c
+    return None
+
+
+def find_hdc():
+    """找 hdc（鸿蒙设备命令行工具，DevEco SDK 自带）。找不到返回 None。"""
+    p = shutil.which("hdc")
+    if p:
+        return p
+    for d in sdk_bin_dirs():
+        c = os.path.join(d, "hdc")
+        if os.path.isfile(c):
+            return c
+    for c in ["/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains/hdc",
+              "/Applications/DevEco-Studio.app/Contents/sdk/default/hms/toolchains/hdc"]:
+        if os.path.isfile(c):
+            return c
+    return None
+
+
+def list_devices(hdc=None):
+    """返回已连接的设备序列号列表。无设备返回 []。"""
+    hdc = hdc or find_hdc()
+    if not hdc:
+        return []
+    out = run([hdc, "list", "targets"])
+    return [l.strip() for l in out.splitlines() if l.strip()]
+
+
+# ==================== 符号 demangle ====================
+def demangle_symbol(sym, cxxfilt=None):
+    """把 C++ mangled 符号 demangle 成可读名字。失败返回原符号。"""
+    if not cxxfilt or not sym or not sym.startswith("_Z"):
+        return sym
+    try:
+        out = subprocess.run([cxxfilt, sym], stdout=subprocess.PIPE, stderr=subprocess.DEVNULL,
+                             text=True, errors="replace").stdout
+        d = out.strip()
+        return d if d and d != sym else sym
+    except Exception:
+        return sym
+
+
+# ==================== 场景分类 ====================
+def classify_feature(class_name):
+    """按 Java 类名精确匹配功能场景（与 analyse/verify 共用，避免 Player 子串误伤）。"""
+    cls = (class_name or "").lower()
+    if "nextplayer" in cls:
+        return "视频播放(NextPlayer引擎)"
+    if "videoplayer" in cls:
+        return "视频滤镜预览(VideoPlayer)"
+    if "audioplayer" in cls or "musicplayer" in cls:
+        return "音频播放(AudioPlayer)"
+    if "ffmpegcmd" in cls or "transcode" in cls:
+        return "视频剪辑处理(FFmpegCmd)"
+    if "mediaretriever" in cls or "metadata" in cls:
+        return "媒体格式探测(MediaRetriever)"
+    if "livepusher" in cls or "rtmp" in cls:
+        return "直播推流(LivePusher)"
+    if "visualizer" in cls or "fft" in cls or "spectrum" in cls:
+        return "音频可视化(FrankVisualizer)"
+    if "equalizer" in cls:
+        return "均衡器(Equalizer)"
+    return None
+
+
+# ==================== so/a 符号提取 ====================
+def get_lib_exports(so_path, nm_tool):
+    """提取 .so/.a 的对外符号名集合。
+
+    - .so：动态导出符号（llvm-nm -D --defined-only --extern-only）
+    - .a ：全局定义符号（llvm-nm --defined-only；ar 归档无动态符号表，
+           取类型为大写字母 T/D/B/R/C 的全局符号）
+    """
+    if not nm_tool:
+        return set()
+    if so_path.endswith(".a"):
+        out = run([nm_tool, "--defined-only", so_path])
+        exports = set()
+        for line in out.splitlines():
+            s = line.strip()
+            if not s or s.endswith(":"):
+                continue
+            parts = s.split()
+            if len(parts) >= 3 and parts[1] and parts[1][0].isupper():
+                exports.add(parts[2])
+        return exports
+    out = run([nm_tool, "-D", "--defined-only", "--extern-only", so_path])
+    exports = set()
+    for line in out.splitlines():
+        parts = line.split()
+        if len(parts) >= 3:
+            exports.add(parts[2])
+    return exports
+
+
+# ==================== 能力检测（从 so/a 导出符号判断）====================
+# 每项：(能力名, 符号名正则, 说明)。正则匹配导出符号名，命中任一即证明 so/a 真实具备该能力。
+CAPABILITY_RULES = [
+    # FFmpeg 核心库
+    ("音视频编解码", r"^avcodec_", "avcodec 库（编解码核心）"),
+    ("封装/解封装", r"^avformat_", "avformat 库（封装/解封装）"),
+    ("滤镜", r"^avfilter_", "avfilter 库（滤镜）"),
+    ("视频缩放", r"^swscale_", "swscale 库（像素缩放）"),
+    ("音频重采样", r"^swresample_", "swresample 库（音频重采样）"),
+    ("IO", r"^avio_", "avio 库（文件/网络 IO）"),
+    # 编码器
+    ("H.264 编码", r"^ff_libx264_encoder$|^x264_encoder_", "H.264 编码器（so 的 ff_libx264_encoder / .a 的 x264_encoder_*）"),
+    ("AAC 编码", r"^ff_aac_encoder$|^faacEnc", "AAC 编码器（so 的 ff_aac_encoder / .a 的 faacEnc*）"),
+    ("AV1 编解码", r"^ff_libaom_av1_", "libaom AV1 编解码器"),
+    # 协议与封装
+    ("RTMP 协议", r"^ff_rtmp_protocol$", "RTMP 推拉流协议"),
+    ("RTSP 协议", r"^ff_rtsp_protocol$", "RTSP 协议"),
+    ("HTTP(S) 协议", r"^ff_https?_protocol$", "HTTP/HTTPS 协议"),
+    ("FLV 封装", r"^ff_flv_muxer$", "FLV 封装器"),
+    ("MP4 封装", r"^ff_mp4_muxer$", "MP4 封装器"),
+    ("MPEG-TS 封装", r"^ff_mpegts_muxer$", "MPEG-TS 封装器"),
+    ("HLS 封装", r"^ff_hls_muxer$", "HLS 封装器"),
+    # NAPI 层（@sj/ffmpeg 的 ArkTS 接口）
+    ("音频播放 NAPI", r"FFAudioPlayer", "FFAudioPlayer NAPI 类（播放/时长/位置/seek）"),
+    ("音频写入 NAPI", r"FFAudioWriter", "FFAudioWriter NAPI 类（PCM 编码写入）"),
+    ("任务取消 NAPI", r"FFAbortSignal", "FFAbortController/FFAbortSignal NAPI 类"),
+    ("命令执行 NAPI", r"FFmpeg", "FFmpeg NAPI（执行 ffmpeg/ffprobe 命令）"),
+    # 常见非 FFmpeg 原生库（换一个 so 也能识别）
+    ("AES 加密", r"^AES_", "OpenSSL AES 加解密"),
+    ("RSA 非对称", r"^RSA_", "OpenSSL RSA"),
+    ("X509 证书", r"^X509_", "OpenSSL X509 证书"),
+    ("TLS/SSL", r"^SSL_|^TLS_", "OpenSSL TLS/SSL"),
+    ("EVP 加密接口", r"^EVP_", "OpenSSL EVP 高层接口"),
+    ("SHA 摘要", r"^SHA(1|224|256|384|512)_", "OpenSSL SHA 系列"),
+    ("OpenSSL BN", r"^BN_", "OpenSSL BN 大数运算"),
+    ("OpenSSL CRYPTO", r"^CRYPTO_", "OpenSSL CRYPTO"),
+    ("OpenSSL 3.x(ossl)", r"^ossl_", "OpenSSL 3.x 内部符号"),
+    ("AMR 编解码", r"^AMREncode|^AMRDecode", "AMR 音频编解码"),
+    ("MP3 编码(LAME)", r"^lame_", "LAME MP3 编码器"),
+    ("AV1 编码(libaom)", r"^aom_", "libaom AV1 编码器"),
+    ("zlib 压缩", r"^(deflate|inflate|compress|uncompress)$", "zlib 压缩"),
+    ("HTTP 客户端", r"^curl_", "libcurl HTTP 客户端"),
+]
+
+
+def detect_capabilities(exports):
+    """从 so/a 导出符号检测能力。返回 {能力名: 命中符号样例}（确定性：sorted 遍历）。"""
+    detected = {}
+    sorted_exports = sorted(exports)
+    for name, pattern, desc in CAPABILITY_RULES:
+        rx = re.compile(pattern)
+        for s in sorted_exports:
+            if rx.search(s):
+                detected[name] = s
+                break
+    return detected
+
+
+def cluster_unknown_symbols(exports, top=25):
+    """对未匹配任何能力规则的符号，按前缀聚类，返回 [(前缀, 数量)]。
+
+    用于自动发现 so 里未纳入规则的库（如 aom_/ossl_/lame_/BN_ 等），
+    让未知 so 也有能力线索，不依赖硬编码规则。
+    """
+    matched = set()
+    for name, pattern, desc in CAPABILITY_RULES:
+        rx = re.compile(pattern)
+        for s in exports:
+            if rx.search(s):
+                matched.add(s)
+    unmatched = exports - matched
+    from collections import Counter
+    prefixes = Counter()
+    for s in unmatched:
+        m = re.match(r"^([A-Za-z_]+)_", s)
+        if m:
+            prefixes[m.group(1)] += 1
+    return prefixes.most_common(top)
+
+
+# 符号前缀 → 语义（让聚类结果可读；有序匹配，长前缀优先）
+PREFIX_MEANING = [
+    ("ff_vf", "FFmpeg 视频滤镜"),
+    ("ff_af", "FFmpeg 音频滤镜"),
+    ("ff_put", "FFmpeg 像素填充"),
+    ("ff_pcm", "FFmpeg PCM 格式"),
+    ("ff_avg", "FFmpeg 像素平均"),
+    ("ff_tx_tab", "FFmpeg 变换表"),
+    ("ff", "FFmpeg 内部符号"),
+    ("cfl", "libaom 帧内预测"),
+    ("aom", "libaom AV1 编码器"),
+    ("av", "FFmpeg avutil"),
+    ("ossl", "OpenSSL 3.x"),
+    ("OPENSSL", "OpenSSL 3.x"),
+    ("BN", "OpenSSL BN 大数"),
+    ("CRYPTO", "OpenSSL CRYPTO"),
+    ("BIO", "OpenSSL BIO"),
+    ("PEM", "OpenSSL PEM"),
+    ("lame", "LAME MP3"),
+    ("__emutls", "线程本地存储"),
+]
+
+
+def prefix_meaning(prefix):
+    for key, meaning in PREFIX_MEANING:
+        if prefix.startswith(key):
+            return meaning
+    return ""
+
+
+# ==================== HTML 工具 ====================
+def esc(v):
+    return _html.escape(str(v if v is not None else "-"))