@harmonyos-arkts/d2h 0.1.20 → 0.1.22

package/skills/cpp/d2h-native-library-analyse/scripts/analyse-android-so.py

@@ -0,0 +1,630 @@
+#!/usr/bin/env python3
+"""Android 应用功能清单 → JNI 方法 → 涉及的 .so/.a 文件。
+
+自顶向下分析：
+  ① 从 Android 源码提取应用**功能清单**（按 Activity/类/包分组）
+  ② 每个功能 → 用到的 JNI native 方法（含调用链/操作步骤）
+  ③ 每个 JNI 方法 → 涉及的 .so/.a 文件（通过 loadLibrary / JNI 符号 / CMake 依赖）
+
+输出：HTML（给人看，功能维度） + JSON（给 AI 映射，机器可读）。
+"""
+
+import argparse
+import html as _html
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+from concurrent.futures import ThreadPoolExecutor
+
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "../../d2h-native-library-verify/scripts"))
+import native_common as nc
+
+__version__ = "3.0.0"
+
+EXCLUDE_DIRS = {
+    ".git", ".hg", ".svn", "node_modules", "oh_modules", ".hvigor",
+    ".gradle", "build", ".idea", ".cxx", ".externalNativeBuild",
+}
+JAVA_EXT = (".java", ".kt")
+SCRIPT_CAP = 1 << 20
+
+# JNI/native 方法声明
+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\("([^"]+)"\)')
+CLASS_RE = re.compile(r"(?:public\s+)?(?:abstract\s+)?(?:final\s+)?class\s+(\w+)")
+ACTIVITY_RE = re.compile(r"extends\s+(?:AppCompat)?Activity|@Entry")
+FRAGMENT_RE = re.compile(r"extends\s+Fragment")
+
+# Activity/场景 → 用户操作场景名（从 Activity 类名提取具体场景）
+ACTIVITY_SCENARIOS = {
+    "VideoHandle": ("视频剪辑处理", "剪辑/转码/添加水印/调节速度等"),
+    "VideoPreview": ("视频预览播放", "预览视频文件/滤镜效果"),
+    "Player": ("视频播放器", "播放视频文件/网络流"),
+    "AudioHandle": ("音频剪辑处理", "音频裁剪/合成/变速等"),
+    "AudioPlay": ("音频播放器", "播放音频文件"),
+    "AudioEffect": ("音频特效", "均衡器/混响/可视化频谱"),
+    "Equalizer": ("均衡器调节", "调节音频频段"),
+    "Filter": ("视频滤镜", "给视频添加滤镜效果"),
+    "CameraFilter": ("相机实时滤镜", "相机预览实时滤镜"),
+    "Live": ("直播推流", "摄像头采集→编码→RTMP推流"),
+    "ProbeFormat": ("媒体格式探测", "获取媒体文件格式信息"),
+    "Main": ("主页入口", "应用主界面"),
+}
+
+# JNI 符号 → so 匹配
+JAVA_SYMBOL_PREFIX = "Java_"
+NDK_LIBS = {"libc++_shared.so", "liblog.so", "libandroid.so", "libm.so", "libc.so", "libdl.so", "libz.so"}
+
+
+def read_file(path, cap=SCRIPT_CAP):
+    try:
+        with open(path, "r", encoding="utf-8", errors="replace") as f:
+            return f.read(cap)
+    except OSError:
+        return ""
+
+
+def run(cmd):
+    return nc.run(cmd)
+
+
+def sdk_bin_dirs():
+    return nc.sdk_bin_dirs()
+
+
+def resolve_tool(names):
+    return nc.resolve_tool(names)
+
+
+TOOL_INSTALL_HINTS = nc.TOOL_INSTALL_HINTS
+
+
+def _is_elf_nm(nm_path):
+    return nc._is_elf_nm(nm_path)
+
+
+def find_elf_nm():
+    return nc.find_elf_nm()
+
+
+def find_so_exports(so_path, nm_tool):
+    """返回 .so 的动态导出符号集合。"""
+    out = run([nm_tool, "-D", "--defined-only", "--extern-only", "-j", so_path])
+    return set(s.strip() for s in out.splitlines() if s.strip())
+
+
+def find_project_libs(root):
+    """找工程中所有 .so/.a 文件，返回 {basename: full_path}。"""
+    libs = {}
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in EXCLUDE_DIRS]
+        for fn in filenames:
+            if fn.endswith((".so", ".a")):
+                libs[fn] = os.path.join(dirpath, fn)
+    return libs
+
+
+def scan_sources(root):
+    """扫描所有 Java/Kotlin 源文件，返回文件信息列表。"""
+    sources = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in EXCLUDE_DIRS]
+        for fn in filenames:
+            if fn.endswith(JAVA_EXT):
+                sources.append(os.path.join(dirpath, fn))
+    return sources
+
+
+def find_operation_for_method(content_lines, method_name, native_lines):
+    """在全文件中找 native 方法的调用点 → 外层 public 方法 = 用户操作入口。
+
+    排除 native 声明行本身（相邻 native 方法不是操作入口）。
+    """
+    call_re = re.compile(r"\b" + re.escape(method_name) + r"\s*\(")
+    native_decl_re = re.compile(r"\bnative\b|\bexternal\b")
+
+    best = ""
+    for i, line in enumerate(content_lines):
+        # 跳过声明行本身
+        if native_decl_re.search(line):
+            continue
+        # 跳过注释
+        stripped = line.strip()
+        if stripped.startswith("//") or stripped.startswith("*") or stripped.startswith("/*"):
+            continue
+        # 找调用点
+        if call_re.search(line):
+            # 向上找最近的 public 方法
+            for j in range(i, max(i - 20, -1), -1):
+                l = content_lines[j]
+                # 排除 native 声明行
+                if native_decl_re.search(l):
+                    continue
+                # 匹配 public/internal 方法签名
+                m2 = re.search(
+                    r"(?:public|internal)\s+(?:static\s+)?(?:final\s+)?(?:suspend\s+)?"
+                    r"(?:fun\s+)?[\w<>\[\],\s]*?\s+(\w+)\s*\(", l)
+                if m2 and m2.group(1) != method_name:
+                    best = m2.group(1)
+                    break
+            if best:
+                break
+    return best
+
+
+def classify_scenario(activity_name):
+    """从 Activity 类名提取用户场景。"""
+    stem = activity_name.replace("Activity", "").replace("activity", "")
+    if stem in ACTIVITY_SCENARIOS:
+        return ACTIVITY_SCENARIOS[stem]
+    return (stem, stem)  # 未识别的用类名本身
+
+
+def classify_feature(class_name, method_name=""):
+    """根据 Java 类名推断所属场景——先精确匹配功能类（native_common），再模糊匹配 Activity。"""
+    feat = nc.classify_feature(class_name)
+    if feat:
+        return feat
+    # 模糊匹配 Activity 名（作为兜底）
+    cls = (class_name or "").lower()
+    for key, scenario in ACTIVITY_SCENARIOS.items():
+        if key.lower() in cls:
+            return scenario[0]
+    return "其他"
+
+
+def extract_file_info(src_path):
+    """从单个源文件提取：类名、native 声明、loadLibrary、调用上下文。"""
+    content = read_file(src_path)
+    if not content:
+        return None
+    pkg_m = PACKAGE_RE.search(content)
+    pkg = pkg_m.group(1) if pkg_m else ""
+    stem = os.path.splitext(os.path.basename(src_path))[0]
+    full_class = (pkg + "." + stem) if pkg else stem
+    ext = os.path.splitext(src_path)[1].lower()
+
+    info = {
+        "file": os.path.basename(src_path),
+        "path": src_path,
+        "class": full_class,
+        "language": "java" if ext == ".java" else "kotlin",
+        "load_libraries": LOAD_LIB_RE.findall(content),
+        "native_methods": [],
+        "is_activity": bool(ACTIVITY_RE.search(content)),
+        "feature": classify_feature(full_class),
+    }
+
+    lines = content.splitlines()
+    for lineno, line in enumerate(lines, 1):
+        method = None
+        if ext == ".java":
+            m = JAVA_NATIVE_RE.search(line)
+            if m: method = m.group(1)
+        else:
+            m = KOTLIN_EXTERNAL_RE.search(line)
+            if m: method = m.group(1)
+        if method:
+            info["native_methods"].append({
+                "method": method,
+                "line": lineno,
+                "feature": classify_feature(full_class, method) or info["feature"] or "通用",
+                "_file": os.path.basename(src_path),
+            })
+    return info
+
+
+def build_cmake_dep_map(root):
+    """解析 CMakeLists.txt 构建 target → 依赖列表映射（去注释后多行匹配）。"""
+    dep_map = {}
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in EXCLUDE_DIRS]
+        for fn in filenames:
+            if fn not in ("CMakeLists.txt",):
+                continue
+            raw = read_file(os.path.join(dirpath, fn))
+            lines = []
+            for line in raw.splitlines():
+                idx = line.find("#")
+                if idx >= 0:
+                    line = line[:idx]
+                if line.strip():
+                    lines.append(line)
+            content = "\n".join(lines)
+
+            # 找所有 add_library 的 target 名
+            targets = re.findall(r"add_library\s*\(\s*([\w-]+)", content)
+            # 找所有 target_link_libraries
+            for m in re.finditer(r"target_link_libraries\s*\(\s*([\w-]+)\s+([^)]*)\)", content):
+                target = m.group(1)
+                deps = []
+                for dep in m.group(2).split():
+                    dep = dep.strip()
+                    if dep.startswith("-l"):
+                        dep = "lib" + dep[2:]
+                    if not dep or dep.startswith("$") or dep.startswith("-"):
+                        continue
+                    if dep in ("log", "android", "jnigraphics", "OpenSLES", "mediandk",
+                               "EGL", "GLESv2", "GLESv3"):
+                        continue
+                    deps.append(dep)
+                if deps:
+                    dep_map[target] = deps
+    return dep_map
+
+
+def match_jni_to_so(native_methods, class_name, load_libraries, project_libs, so_exports_cache, nm_tool, cmake_deps, all_sources_info=None):
+    """把 JNI 方法关联到 .so 文件——通过 loadLibrary 名 → CMake 依赖 → 实际文件。"""
+    results = []
+    for nm in native_methods:
+        method = nm["method"]
+
+        # 策略1：loadLibrary 名 → CMake 依赖 → 工程内实际 .so/.a 文件
+        matched_libs = []
+        for lib_name in load_libraries:
+            # loadLibrary("media-handle") → CMake target "media-handle" → depends ["ffmpeg"]
+            cmake_target = lib_name
+            deps = cmake_deps.get(cmake_target, [])
+            # 也查是否有 lib{lib_name}.so 直接存在
+            direct = "lib" + lib_name + ".so"
+            if direct in project_libs:
+                matched_libs.append({"name": direct, "match_type": "load_library", "path": project_libs[direct]})
+            # CMake 依赖名 → 匹配工程内文件
+            for dep in deps:
+                for suffix in (".so", ".a"):
+                    candidate = dep + suffix
+                    if candidate in project_libs:
+                        matched_libs.append({"name": candidate, "match_type": "cmake_dep", "path": project_libs[candidate]})
+                    candidate2 = "lib" + dep + suffix
+                    if candidate2 in project_libs and candidate2 not in [m["name"] for m in matched_libs]:
+                        matched_libs.append({"name": candidate2, "match_type": "cmake_dep", "path": project_libs[candidate2]})
+
+        # 策略1b：类自身没 loadLibrary → 扫同包/同模块其他类的 loadLibrary
+        if not matched_libs:
+            for other_info in all_sources_info:
+                if other_info.get("load_libraries") and not other_info.get("native_methods"):
+                    # 这个类有 loadLibrary 但没 native 方法——可能是 LibraryLoader
+                    other_libs = other_info["load_libraries"]
+                    for other_lib in other_libs:
+                        deps = cmake_deps.get(other_lib, [])
+                        for dep in deps:
+                            for suffix in (".so", ".a"):
+                                cand = dep + suffix
+                                if cand in project_libs:
+                                    matched_libs.append({"name": cand, "match_type": "indirect_load", "path": project_libs[cand]})
+                                cand2 = "lib" + dep + suffix
+                                if cand2 in project_libs and cand2 not in [m["name"] for m in matched_libs]:
+                                    matched_libs.append({"name": cand2, "match_type": "indirect_load", "path": project_libs[cand2]})
+
+        # 策略1c：同 app 模块（同包前缀）的其他类有 loadLibrary → 关联
+        if not matched_libs:
+            # 找同包前缀（前 3 段相同）且有 loadLibrary 的类
+            cls_parts = class_name.split(".")
+            pkg_prefix = ".".join(cls_parts[:3]) if len(cls_parts) > 3 else class_name
+            for other_info in all_sources_info:
+                other_cls = other_info.get("class", "")
+                if other_cls.startswith(pkg_prefix) and other_info.get("load_libraries"):
+                    for other_lib in other_info["load_libraries"]:
+                        deps = cmake_deps.get(other_lib, [])
+                        for dep in deps:
+                            for suffix in (".so", ".a"):
+                                cand = "lib" + dep + suffix
+                                if cand in project_libs and cand not in [m["name"] for m in matched_libs]:
+                                    matched_libs.append({"name": cand, "match_type": "same_module", "path": project_libs[cand]})
+
+        # 策略2：JNI 符号直接在 .so 导出表匹配
+        if not matched_libs:
+            parts = class_name.split(".")
+            jni_symbol = "Java_" + "_".join(parts) + "_" + method
+            for lib_name, lib_path in project_libs.items():
+                if lib_name.endswith(".a"):
+                    continue
+                if lib_name not in so_exports_cache and nm_tool:
+                    so_exports_cache[lib_name] = find_so_exports(lib_path, nm_tool)
+                if jni_symbol in so_exports_cache.get(lib_name, set()):
+                    matched_libs.append({"name": lib_name, "match_type": "jni_symbol", "path": lib_path})
+
+        results.append({
+            **nm,
+            "class": class_name,
+            "file": nm.get("_file", ""),
+            "jni_symbol": "Java_" + "_".join(class_name.split(".")) + "_" + method,
+            "matched_libs": matched_libs,
+        })
+    return results
+
+
+
+def build_feature_manifest(sources_info, project_libs, nm_tool, cmake_deps, root):
+    """构建功能清单：feature → JNI 方法 → so/a 文件。"""
+    so_exports_cache = {}
+    features = {}
+
+    for info in sources_info:
+        if not info["native_methods"]:
+            continue
+        # 为每个 native 方法计算 operation（找调用点的 public 方法）
+        content_lines = read_file(info["path"]).splitlines()
+        native_line_set = {nm["line"] for nm in info["native_methods"]}
+        for nm in info["native_methods"]:
+            nm["operation"] = find_operation_for_method(content_lines, nm["method"], native_line_set)
+
+        # 匹配 JNI → so
+        matched = match_jni_to_so(info["native_methods"], info["class"], info["load_libraries"], project_libs, so_exports_cache, nm_tool, cmake_deps, sources_info)
+
+        for m in matched:
+            feature = m["feature"]
+            if feature not in features:
+                features[feature] = {
+                    "feature": feature,
+                    "jni_methods": [],
+                    "involved_libs": set(),
+                    "source_files": set(),
+                }
+            features[feature]["jni_methods"].append({
+                "class": m["class"],
+                "method": m["method"],
+                "jni_symbol": m["jni_symbol"],
+                "file": m["file"],
+                "line": m["line"],
+                                "operation": m.get("operation", "") or m["method"],
+                "libs": [l["name"] for l in m["matched_libs"]],
+            })
+            for l in m["matched_libs"]:
+                features[feature]["involved_libs"].add(l["name"])
+            features[feature]["source_files"].add(info["file"])
+
+    # 排序 + 清理
+    result = []
+    for feat_name in sorted(features):
+        f = features[feat_name]
+        result.append({
+            "feature": feat_name,
+            "description": f"涉及 {len(f['jni_methods'])} 个 JNI 方法，{len(f['involved_libs'])} 个原生库",
+            "jni_methods": sorted(f["jni_methods"], key=lambda x: (x["class"], x["method"])),
+            "involved_libs": sorted(f["involved_libs"]),
+            "source_files": sorted(f["source_files"]),
+        })
+    return result
+
+
+HTML_CSS = """<style>
+body{font-family:-apple-system,"PingFang SC","Microsoft YaHei",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:1100px;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;display:flex;align-items:center;gap:10px}
+summary::-webkit-details-marker{display:none}
+.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{color:#555;font-weight:600;background:#fafafa;font-size:12px}
+.b{display:inline-block;padding:2px 10px;border-radius:12px;font-size:12px;font-weight:600}
+.bg{background:#e6f7e6;color:#1a7a1a}.bl{background:#e8f0fe;color:#1a56c4}.by{background:#fff7e0;color:#9a6d00}
+.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}
+.mu{color:#888;font-size:11px}
+.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:120px}
+.card .n{font-size:26px;font-weight:700}
+.card .l{font-size:11px;color:#666}
+</style>"""
+
+
+def _e(v):
+    return nc.esc(v)
+
+
+def render_html(payload):
+    features = payload.get("features", [])
+    total_jni = sum(len(f["jni_methods"]) for f in features)
+    total_libs = set()
+    for f in features:
+        total_libs.update(f["involved_libs"])
+
+    h = ['<!DOCTYPE html><html lang="zh"><head><meta charset="utf-8">',
+         '<meta name="viewport" content="width=device-width,initial-scale=1">',
+         '<title>Native 分析报告</title>', HTML_CSS,
+         '</head><body><div class="hd">',
+         '<h1>Native 分析报告</h1>',
+         '<div class="m">%s · 功能 %d · JNI %d · 原生库 %d</div></div><div class="ct">' % (
+             _e(payload.get("tool_version")), len(features), total_jni, len(total_libs))]
+
+    # 总览卡片
+    h.append('<div class="cards">')
+    for label, val, color in [("功能", len(features), "#1a56c4"), ("JNI 方法", total_jni, "#1a7a1a"),
+                               ("涉及 .so/.a", len(total_libs), "#c0392b")]:
+        h.append('<div class="card"><div class="n" style="color:%s">%d</div><div class="l">%s</div></div>' % (color, val, label))
+    h.append('</div>')
+
+    # 📦 所有 .so/.a 文件完整清单
+    if payload.get("all_libs"):
+        h.append('<details open><summary>📦 工程内全部 .so/.a 文件（' + str(len(payload.get('all_libs', []))) + ' 个）</summary><div class="bd">')
+        h.append('<table><tr><th>文件名</th><th>类型</th><th>架构</th><th>检测到的能力</th><th>被哪些功能使用</th></tr>')
+        lib_to_features = {}
+        for f in features:
+            for lib in f["involved_libs"]:
+                lib_to_features.setdefault(lib, []).append(f["feature"])
+        for lib in payload["all_libs"]:
+            name = os.path.basename(lib["path"])
+            used_by = lib_to_features.get(name, [])
+            used_html = " ".join('<span class="tag" style="background:#e8f0fe;color:#1a56c4">%s</span>' % _e(f) for f in used_by) if used_by else '<span class="mu">未被直接使用</span>'
+            kind_label = "静态库" if lib.get("kind") == "a" else "动态库"
+            caps = lib.get("detected", {})
+            caps_html = " ".join('<span class="tag" style="background:#e6f7e6;color:#1a7a1a">%s</span>' % _e(c) for c in caps) if caps else '<span class="mu">未检测到</span>'
+            h.append('<tr><td><b>%s</b></td><td>%s</td><td>%s</td><td>%s</td><td>%s</td></tr>' % (
+                _e(name), kind_label, _e(lib.get("arch", "?")), caps_html, used_html))
+        h.append('</table></div></details>')
+
+    # 功能 → so/a 总表
+    h.append('<details open><summary>📋 功能 → 原生库 对照表</summary><div class="bd">')
+    h.append('<table><tr><th>功能</th><th>JNI 方法数</th><th>涉及的 .so/.a</th></tr>')
+    for f in features:
+        libs_html = " ".join('<span class="tag">%s</span>' % _e(l) for l in f["involved_libs"])
+        h.append('<tr><td><b>%s</b></td><td>%d</td><td>%s</td></tr>' % (
+            _e(f["feature"]), len(f["jni_methods"]), libs_html))
+    h.append('</table></div></details>')
+
+    # 每个功能的详细卡片
+    for f in features:
+        h.append('<details%s><summary>%s <span class="b bl">%d JNI</span> %s</summary><div class="bd">' % (
+            "", _e(f["feature"]), len(f["jni_methods"]),
+            " ".join('<span class="tag">%s</span>' % _e(l) for l in f["involved_libs"])))
+        h.append('<table><tr><th>Android 类.方法</th><th>操作入口</th><th>源码位置</th></tr>')
+        for jm in f["jni_methods"]:
+            h.append('<tr><td><b>%s.%s()</b></td><td><code>%s</code></td><td class="mu">%s:%s</td></tr>' % (
+                _e(jm["class"]), _e(jm["method"]), _e(jm.get("operation", "")),
+                _e(jm.get("file", "")), _e(jm.get("line", ""))))
+        h.append('</table>')
+
+        # so/a 文件
+        if f["involved_libs"]:
+            h.append('<div style="margin-top:8px"><b>涉及原生库：</b>%s</div>' % " ".join(
+                '<span class="tag" style="background:#fdeaea;color:#c0392b">%s</span>' % _e(l) for l in f["involved_libs"]))
+
+        h.append('</div></details>')
+
+    h.append('</div></body></html>')
+    return "\n".join(h)
+
+
+def _get_lib_arch(path):
+    """快速读 ELF 头获取架构（不重跑完整分析）。"""
+    try:
+        with open(path, "rb") as f:
+            magic = f.read(20)
+        if len(magic) < 20 or magic[:4] != b"\x7fELF":
+            return "unknown"
+        ei_class = magic[4]
+        e_machine = int.from_bytes(magic[18:20], "little")
+        bits = 64 if ei_class == 2 else 32
+        arch = {183: "arm64-v8a", 40: "armeabi-v7a", 62: "x86_64", 3: "x86"}.get(e_machine, "unknown")
+        return arch
+    except OSError:
+        return "unknown"
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Android 功能清单 → JNI → so/a 文件分析")
+    parser.add_argument("target", help="Android 工程目录")
+    parser.add_argument("--json", action="store_true")
+    parser.add_argument("--html", metavar="PATH", nargs="?", const="auto")
+    parser.add_argument("--output", metavar="DIR", help="输出目录（默认 <工程名>-native-reports/）")
+    args = parser.parse_args()
+
+    root = os.path.abspath(args.target)
+    if not os.path.isdir(root):
+        print("目标不存在: %s" % root)
+        return 2
+
+    # 校验能解析 ELF 的 nm 工具（so 符号提取的核心依赖，缺失直接报错）
+    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("     （装好后脚本自动探测 SDK，或设置 OHOS_SDK_HOME / DEVECO_SDK_HOME / ANDROID_NDK_HOME）")
+        print("  ② macOS：brew install llvm")
+        print("  ③ Linux：sudo apt install binutils")
+        return 2
+
+    # ① 扫描源码 + 原生库
+    sources = scan_sources(root)
+    project_libs = find_project_libs(root)
+    sources_info = []
+    for src in sources:
+        info = extract_file_info(src)
+        if info:
+            sources_info.append(info)
+
+    # ② 构建功能清单
+    cmake_deps = build_cmake_dep_map(root)
+    features = build_feature_manifest(sources_info, project_libs, nm_tool, cmake_deps, root)
+
+    # ③ 输出
+    out_dir = os.path.abspath(args.output) if args.output else os.path.join(
+        os.path.dirname(root), os.path.basename(root) + "-native-reports")
+    os.makedirs(out_dir, exist_ok=True)
+
+    # 收集所有 .so/.a，按文件名分组去重（同名多 ABI → 只保留 arm64-v8a，无 arm64 保留第一个）
+    _lib_files = sorted(set(
+        os.path.join(dp, fn) for dp, dns, fns in os.walk(root)
+        for fn in fns if fn.endswith((".so", ".a"))
+        if not any(d in dp for d in EXCLUDE_DIRS)
+    ))
+    _by_name = {}
+    for _p in _lib_files:
+        _by_name.setdefault(os.path.basename(_p), []).append(_p)
+    _deduped = []
+    for _name in sorted(_by_name):
+        _paths = _by_name[_name]
+        _arm64 = [p for p in _paths if "arm64-v8a" in p]
+        _chosen = _arm64[0] if _arm64 else _paths[0]
+        _deduped.append(_chosen)
+    all_libs = []
+    for p in _deduped:
+        arch = _get_lib_arch(p)
+        if arch == "unknown":
+            # .a 或读不到 ELF → 从目录名推断
+            parent = os.path.basename(os.path.dirname(p))
+            if parent in ("arm64-v8a", "armeabi-v7a", "x86", "x86_64", "armeabi"):
+                arch = parent
+        lib_info = {"path": p, "kind": "a" if p.endswith(".a") else "so", "arch": arch}
+        # 能力检测（从 so/a 导出符号，与 verify 共用同一套规则）
+        exports = nc.get_lib_exports(p, nm_tool)
+        lib_info["detected"] = nc.detect_capabilities(exports)
+        lib_info["export_count"] = len(exports)
+        all_libs.append(lib_info)
+
+    payload = {
+        "tool_version": __version__,
+        "target": root,
+        "features": features,
+        "all_libs": all_libs,
+        "summary": {
+            "total_features": len(features),
+            "total_jni": sum(len(f["jni_methods"]) for f in features),
+            "total_libs": len(set(l for f in features for l in f["involved_libs"])),
+            
+            "libs": sorted(set(l for f in features for l in f["involved_libs"])),
+        },
+    }
+
+    # JSON（给 AI 映射用）
+    json_path = os.path.join(out_dir, "feature-manifest.json")
+    with open(json_path, "w", encoding="utf-8") as f:
+        json.dump(payload, f, ensure_ascii=False, indent=2)
+
+    # HTML（给人看）
+    html_path = os.path.join(out_dir, "feature-manifest.html")
+    if args.html != "no":
+        with open(html_path, "w", encoding="utf-8") as f:
+            f.write(render_html(payload))
+
+    print("=" * 72)
+    print("Android 功能清单  (tool %s)" % __version__)
+    print("目标: %s" % root)
+    print("功能: %d | JNI 方法: %d | 涉及原生库: %d" % (
+        payload["summary"]["total_features"], payload["summary"]["total_jni"],
+        payload["summary"]["total_libs"]))
+    print("JSON: %s" % json_path)
+    print("HTML: %s" % html_path)
+    print("=" * 72)
+    for f in features:
+        libs = ", ".join(f["involved_libs"])
+        print("  %s（%d JNI）→ %s" % (f["feature"], len(f["jni_methods"]), libs))
+
+    if args.json:
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())