android-decompile-mcp 0.0.0-stage → 1.0.0

package/dist/smali.js

@@ -0,0 +1,128 @@
+import { join, basename, resolve, dirname } from "node:path";
+import { stat, readFile, readdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { exec, hasCommand, ensureDir } from "./util.js";
+/** 项目根目录（dist/ 的上一级），不依赖启动时的 cwd。 */
+const PROJECT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+/**
+ * baksmali 调用方式解析：
+ *  - 若设置 BAKSMALI_JAR 环境变量，则作为可执行 fat jar 调用（java -jar）。
+ *  - 否则使用项目内 tools/ 目录下的 baksmali 及其依赖，走 classpath 调用。
+ */
+function baksmaliInvocation() {
+    if (process.env.BAKSMALI_JAR) {
+        return { args: ["-jar", process.env.BAKSMALI_JAR], desc: process.env.BAKSMALI_JAR };
+    }
+    const toolsDir = join(PROJECT_ROOT, "tools");
+    const cp = join(toolsDir, "*");
+    return { args: ["-cp", cp, "org.jf.baksmali.Main"], desc: `${toolsDir}/*` };
+}
+async function ensureJava() {
+    if (!(await hasCommand("java"))) {
+        throw new Error("未找到 java。baksmali 依赖 JRE，请先安装 Java。");
+    }
+}
+/**
+ * 把一个或多个 dex 反编译为 smali。
+ * dexInput 可以是单个 .dex 文件、也可以是包含多个 dex 的目录。
+ */
+export async function dexToSmali(dexInput, outDir) {
+    await ensureJava();
+    const bak = baksmaliInvocation();
+    const st = await stat(dexInput).catch(() => null);
+    if (!st)
+        throw new Error(`输入路径不存在：${dexInput}`);
+    // 收集待处理 dex
+    let dexFiles = [];
+    if (st.isDirectory()) {
+        const names = await readdir(dexInput);
+        dexFiles = names.filter((n) => n.toLowerCase().endsWith(".dex")).map((n) => join(dexInput, n));
+    }
+    else {
+        dexFiles = [dexInput];
+    }
+    if (dexFiles.length === 0)
+        throw new Error(`在 ${dexInput} 中未找到 .dex 文件。`);
+    await ensureDir(outDir);
+    const classDirs = [];
+    let log = "";
+    for (const dex of dexFiles) {
+        // 每个 dex 输出到独立子目录，避免互相覆盖
+        const sub = join(outDir, basename(dex).replace(/\.dex$/i, ""));
+        await ensureDir(sub);
+        const r = await exec("java", [...bak.args, "d", dex, "-o", sub], { timeoutMs: 300000 });
+        log += `# ${basename(dex)} (exit ${r.code})\n${r.stdout}${r.stderr}\n`;
+        if (r.code !== 0)
+            throw new Error(`baksmali 反编译失败：${dex}\n${r.stderr}`);
+        classDirs.push(sub);
+    }
+    return { dexFiles, outDir, classDirs, log };
+}
+/** 递归收集目录下所有 .smali 文件。 */
+async function walkSmali(dir, acc = []) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const e of entries) {
+        const full = join(dir, e.name);
+        if (e.isDirectory())
+            await walkSmali(full, acc);
+        else if (e.name.toLowerCase().endsWith(".smali"))
+            acc.push(full);
+    }
+    return acc;
+}
+/** smali 类名（com.foo.Bar）转相对文件路径。 */
+function classToPath(className) {
+    const norm = className.replace(/^L/, "").replace(/;$/, "").replace(/\./g, "/");
+    return norm.endsWith(".smali") ? norm : `${norm}.smali`;
+}
+/** 列出 smali 目录下所有类（以类名形式）。 */
+export async function smaliListClasses(smaliDir, keyword) {
+    const files = await walkSmali(smaliDir);
+    const base = resolve(smaliDir);
+    let classes = files.map((f) => resolve(f).slice(base.length + 1).replace(/\\/g, "/").replace(/\.smali$/i, "").replace(/\//g, "."));
+    if (keyword)
+        classes = classes.filter((c) => c.includes(keyword));
+    return classes.sort();
+}
+/** 读取指定类的 smali 源码。支持 com.foo.Bar 或 com/foo/Bar 形式。 */
+export async function smaliReadClass(smaliDir, className) {
+    const rel = classToPath(className);
+    const candidate = join(smaliDir, rel);
+    if (existsSync(candidate))
+        return readFile(candidate, "utf8");
+    // 回退：在整个目录中搜索同名文件
+    const files = await walkSmali(smaliDir);
+    const target = rel.split("/").pop();
+    const hit = files.find((f) => basename(f) === target);
+    if (!hit)
+        throw new Error(`未找到类：${className}`);
+    return readFile(hit, "utf8");
+}
+/**
+ * 在 smali 目录中按正则搜索（内容分析）。返回命中行及上下文位置。
+ * 适合查找 API 调用、字符串、权限、加解密逻辑等。
+ */
+export async function smaliSearch(smaliDir, pattern, opts = {}) {
+    const files = await walkSmali(smaliDir);
+    const re = new RegExp(pattern, opts.flags ?? "i");
+    const max = opts.maxResults ?? 500;
+    const base = resolve(smaliDir);
+    const matches = [];
+    for (const f of files) {
+        const content = await readFile(f, "utf8");
+        const lines = content.split(/\r?\n/);
+        for (let i = 0; i < lines.length; i++) {
+            if (re.test(lines[i])) {
+                matches.push({
+                    file: resolve(f).slice(base.length + 1).replace(/\\/g, "/"),
+                    line: i + 1,
+                    text: lines[i].trim(),
+                });
+                if (matches.length >= max)
+                    return matches;
+            }
+        }
+    }
+    return matches;
+}

package/dist/smali_patch.js

@@ -0,0 +1,237 @@
+import { readFile, writeFile, copyFile, readdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { findAppEntry } from "./entry.js";
+const VERIFY_LOG_SNIPPET = `    # --- DexAndroid verify marker (learning rebuild check) ---
+    const-string v0, "DexAndroid"
+    const-string v1, "entry_ok"
+    invoke-static {v0, v1}, Landroid/util/Log;->d(Ljava/lang/String;Ljava/lang/String;)I
+    # --- end marker ---
+`;
+function splitLines(text) {
+    return text.split(/\r?\n/);
+}
+function joinLines(lines) {
+    return lines.join("\n");
+}
+function findOnCreateSuperIndex(lines) {
+    let inOnCreate = false;
+    for (let i = 0; i < lines.length; i++) {
+        if (/^\s*\.method\s+.*\bonCreate\s*\(/.test(lines[i])) {
+            inOnCreate = true;
+            continue;
+        }
+        if (inOnCreate && /^\s*\.end method\b/.test(lines[i]))
+            break;
+        if (inOnCreate &&
+            /invoke-super\s+\{[^}]*\},\s*L[^;]+;->onCreate\s*\(\s*Landroid\/os\/Bundle;\s*\)V/.test(lines[i])) {
+            return i;
+        }
+    }
+    // fallback: first .locals inside onCreate
+    inOnCreate = false;
+    for (let i = 0; i < lines.length; i++) {
+        if (/^\s*\.method\s+.*\bonCreate\s*\(/.test(lines[i])) {
+            inOnCreate = true;
+            continue;
+        }
+        if (inOnCreate && /^\s*\.locals\b/.test(lines[i]))
+            return i;
+        if (inOnCreate && /^\s*\.end method\b/.test(lines[i]))
+            break;
+    }
+    return -1;
+}
+function ensureLocalsForVerify(lines) {
+    // insert_verify_log uses v0/v1; bump .locals if needed inside onCreate
+    let inOnCreate = false;
+    for (let i = 0; i < lines.length; i++) {
+        if (/^\s*\.method\s+.*\bonCreate\s*\(/.test(lines[i])) {
+            inOnCreate = true;
+            continue;
+        }
+        if (!inOnCreate)
+            continue;
+        if (/^\s*\.end method\b/.test(lines[i]))
+            break;
+        const m = lines[i].match(/^\s*\.locals\s+(\d+)/);
+        if (m) {
+            const n = parseInt(m[1], 10);
+            if (n < 2)
+                lines[i] = lines[i].replace(/\.locals\s+\d+/, ".locals 2");
+            break;
+        }
+    }
+    return lines;
+}
+async function findClassSmali(roots, className) {
+    const rel = className.replace(/\./g, "/") + ".smali";
+    for (const root of roots) {
+        const candidates = [join(root, rel), join(root, "smali", rel)];
+        for (const p of candidates)
+            if (existsSync(p))
+                return p;
+        try {
+            for (const n of await readdir(root)) {
+                if (!n.startsWith("smali"))
+                    continue;
+                const p = join(root, n, rel);
+                if (existsSync(p))
+                    return p;
+            }
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    return undefined;
+}
+async function resolveTargetSmali(opts) {
+    if (opts.smaliPath) {
+        const p = resolve(opts.smaliPath);
+        if (!existsSync(p))
+            throw new Error(`smali 文件不存在：${p}`);
+        return p;
+    }
+    const roots = [];
+    if (opts.projectDir)
+        roots.push(resolve(opts.projectDir));
+    if (opts.smaliDir)
+        roots.push(resolve(opts.smaliDir));
+    if (opts.className && roots.length) {
+        const p = await findClassSmali(roots, opts.className);
+        if (p)
+            return p;
+        throw new Error(`未找到类 ${opts.className} 的 smali，请检查 className / projectDir。`);
+    }
+    if (opts.projectDir) {
+        const info = await findAppEntry({
+            projectDir: opts.projectDir,
+            smaliDir: opts.smaliDir,
+        });
+        const first = info.launchers.find((L) => L.smaliPath);
+        if (first?.smaliPath)
+            return first.smaliPath;
+        throw new Error("未能定位入口 Activity 的 smali，请显式传 smaliPath 或 className。");
+    }
+    throw new Error("请提供 smaliPath，或 projectDir（自动定位入口 Activity）。");
+}
+/**
+ * 通用 smali 补丁：内容由调用方提供（或使用内置 verify Log 标记）。
+ * 用于学习/验证自有工程重打包是否生效；不生成广告、外链跳转等业务模板。
+ */
+export async function smaliPatch(opts) {
+    const smaliPath = await resolveTargetSmali(opts);
+    const dryRun = !!opts.dryRun;
+    const backup = opts.backup !== false;
+    const original = await readFile(smaliPath, "utf8");
+    let lines = splitLines(original);
+    let detail = "";
+    let changed = false;
+    let nextText = original;
+    switch (opts.mode) {
+        case "insert_verify_log": {
+            if (original.includes("DexAndroid") && original.includes("entry_ok")) {
+                return {
+                    smaliPath,
+                    mode: opts.mode,
+                    dryRun,
+                    changed: false,
+                    detail: "已存在 verify 标记，跳过。",
+                };
+            }
+            lines = ensureLocalsForVerify(lines);
+            const idx = findOnCreateSuperIndex(lines);
+            if (idx < 0)
+                throw new Error("未找到 onCreate 内的 invoke-super/.locals，无法插入 verify Log。");
+            const snippet = splitLines(VERIFY_LOG_SNIPPET.replace(/\n$/, ""));
+            lines.splice(idx + 1, 0, ...snippet);
+            nextText = joinLines(lines);
+            changed = nextText !== original;
+            detail = `在 onCreate 第 ${idx + 1} 行后插入 Log.d("DexAndroid","entry_ok") 验证标记。`;
+            break;
+        }
+        case "insert_after_onCreate_super": {
+            if (!opts.content?.trim()) {
+                throw new Error("mode=insert_after_onCreate_super 需要提供 content（你自己的 smali 片段）。");
+            }
+            const idx = findOnCreateSuperIndex(lines);
+            if (idx < 0)
+                throw new Error("未找到 onCreate 内的 invoke-super/.locals。");
+            const snippet = splitLines(opts.content.replace(/\s+$/, ""));
+            lines.splice(idx + 1, 0, ...snippet);
+            nextText = joinLines(lines);
+            changed = nextText !== original;
+            detail = `在 onCreate 锚点第 ${idx + 1} 行后插入 ${snippet.length} 行（调用方 content）。`;
+            break;
+        }
+        case "insert_at_line": {
+            if (!opts.content?.trim())
+                throw new Error("mode=insert_at_line 需要 content。");
+            if (!opts.line || opts.line < 1)
+                throw new Error("mode=insert_at_line 需要 line（1-based）。");
+            const at = Math.min(opts.line, lines.length);
+            const snippet = splitLines(opts.content.replace(/\s+$/, ""));
+            lines.splice(at, 0, ...snippet);
+            nextText = joinLines(lines);
+            changed = nextText !== original;
+            detail = `在第 ${at} 行后插入 ${snippet.length} 行。`;
+            break;
+        }
+        case "replace": {
+            if (!opts.find)
+                throw new Error("mode=replace 需要 find。");
+            if (opts.content === undefined)
+                throw new Error("mode=replace 需要 content（替换后文本，可为空）。");
+            if (!original.includes(opts.find)) {
+                return {
+                    smaliPath,
+                    mode: opts.mode,
+                    dryRun,
+                    changed: false,
+                    detail: "未找到 find 文本，未修改。",
+                };
+            }
+            nextText = original.replace(opts.find, opts.content);
+            changed = nextText !== original;
+            detail = `replace 完成（find 长度 ${opts.find.length} → content 长度 ${opts.content.length}）。`;
+            break;
+        }
+        default:
+            throw new Error(`未知 mode: ${opts.mode}`);
+    }
+    const previewLines = splitLines(nextText);
+    const previewStart = Math.max(0, (opts.line ?? findOnCreateSuperIndex(splitLines(original))) - 3);
+    const preview = previewLines.slice(previewStart, previewStart + 40).join("\n");
+    let backupPath;
+    if (changed && !dryRun) {
+        if (backup) {
+            backupPath = smaliPath + ".bak";
+            await copyFile(smaliPath, backupPath);
+        }
+        await writeFile(smaliPath, nextText, "utf8");
+    }
+    return {
+        smaliPath,
+        mode: opts.mode,
+        dryRun,
+        backupPath,
+        changed,
+        detail,
+        preview,
+    };
+}
+export function formatSmaliPatch(r) {
+    return [
+        `file: ${r.smaliPath}`,
+        `mode: ${r.mode}`,
+        `dryRun: ${r.dryRun}`,
+        `changed: ${r.changed}`,
+        r.backupPath ? `backup: ${r.backupPath}` : "",
+        `detail: ${r.detail}`,
+        r.preview ? `--- preview ---\n${r.preview}` : "",
+        "说明: 内容由调用方提供；内置仅有 Log 验证标记。仅用于有权修改的自有/授权工程学习验证。",
+    ]
+        .filter(Boolean)
+        .join("\n");
+}

package/dist/unpack/blackdex.js

@@ -0,0 +1,119 @@
+import { join } from "node:path";
+import { stat } from "node:fs/promises";
+import { ensureDir } from "../util.js";
+import { resolveSerial, isInstalled, install, launchApp, shell, pull, adb, } from "../adb.js";
+/** 常见 BlackDex 包名（不同架构/版本不一致）。 */
+export const BLACKDEX_PKGS = [
+    "top.niunaijun.blackdexa64",
+    "top.niunaijun.blackdexa32",
+    "com.wrlus.blackdex",
+];
+/** 在设备上查找已安装的 BlackDex 包名。 */
+export async function findBlackDexPkg(serial) {
+    for (const pkg of BLACKDEX_PKGS) {
+        if (await isInstalled(serial, pkg))
+            return pkg;
+    }
+    return null;
+}
+/** BlackDex dump 可能落在这些目录（v3.2 实际写在 dump/ 下）。 */
+function candidateOutputDirs(pkg) {
+    return [
+        `/sdcard/Android/data/${pkg}/dump`,
+        `/storage/emulated/0/Android/data/${pkg}/dump`,
+        `/sdcard/Android/data/${pkg}/files`,
+        `/storage/emulated/0/Android/data/${pkg}/files`,
+        `/sdcard/BlackDex`,
+        `/storage/emulated/0/BlackDex`,
+        `/sdcard/Download/BlackDex`,
+    ];
+}
+/**
+ * 免 root 方案（BlackDex）：安装并启动 BlackDex，用户在界面中选择目标 app 脱壳。
+ */
+export async function blackdexPrepare(blackdexApkPath, serial) {
+    const s = await resolveSerial(serial);
+    let pkg = await findBlackDexPkg(s);
+    if (!pkg) {
+        if (!blackdexApkPath) {
+            return {
+                serial: s,
+                pkg: null,
+                installed: false,
+                launched: false,
+                message: `设备上未安装 BlackDex。请提供 BlackDex 的 APK 路径（参数 blackdexApkPath）以自动安装，\n` +
+                    `或手动安装后重试。开源下载：https://github.com/CodingGay/BlackDex/releases`,
+            };
+        }
+        const st = await stat(blackdexApkPath).catch(() => null);
+        if (!st)
+            throw new Error(`BlackDex APK 不存在：${blackdexApkPath}`);
+        const r = await install(s, blackdexApkPath);
+        if (r.code !== 0)
+            throw new Error(`安装 BlackDex 失败：\n${r.stderr}`);
+        pkg = await findBlackDexPkg(s);
+        if (!pkg) {
+            throw new Error("BlackDex APK 已安装，但未识别到包名。请确认安装的是官方 BlackDex 发行版。");
+        }
+    }
+    // monkey 启动；失败时尝试显式 Activity
+    let launch = await launchApp(s, pkg);
+    let launched = launch.code === 0 && !/No activities found/i.test(launch.stdout + launch.stderr);
+    if (!launched) {
+        const act = await adb([
+            "shell",
+            "am",
+            "start",
+            "-n",
+            `${pkg}/top.niunaijun.blackdex.view.base.WelcomeActivity`,
+        ], { serial: s });
+        launched = act.code === 0 && !/Error/i.test(act.stdout + act.stderr);
+        launch = act;
+    }
+    const dirs = candidateOutputDirs(pkg).join("\n  ");
+    return {
+        serial: s,
+        pkg,
+        installed: true,
+        launched,
+        message: `BlackDex 已就绪（包名: ${pkg}）。\n` +
+            `请在设备 BlackDex 界面中选择目标应用并点击脱壳，\n` +
+            `完成后调用 blackdex_pull。dump 目录可能位于：\n  ${dirs}`,
+    };
+}
+/** 在候选目录中找到含 dump 结果的远端路径。 */
+async function resolveRemoteDump(serial, pkg, targetPkg) {
+    for (const base of candidateOutputDirs(pkg)) {
+        const remote = targetPkg ? `${base}/${targetPkg}` : base;
+        const ls = await shell(serial, `ls -R "${remote}" 2>/dev/null`);
+        if (ls.stdout.trim() && /\.dex/i.test(ls.stdout)) {
+            return { remote, listing: ls.stdout };
+        }
+        // 有内容但还没看到 dex 也先返回，便于排查
+        if (ls.stdout.trim() && targetPkg) {
+            return { remote, listing: ls.stdout };
+        }
+    }
+    // 再全局搜一遍 BlackDex / 目标包名目录
+    const find = await shell(serial, `ls -R /sdcard/BlackDex /sdcard/Android/data/${pkg}/files 2>/dev/null | head -n 200`);
+    throw new Error(`未找到 BlackDex dump 结果。请确认已在 BlackDex 中完成脱壳。\n` +
+        `当前可见内容：\n${find.stdout || "(空)"}`);
+}
+/** 把 BlackDex dump 出的 dex 从设备拉回本机。 */
+export async function blackdexPull(localOutDir, serial, targetPkg) {
+    const s = await resolveSerial(serial);
+    await ensureDir(localOutDir);
+    const pkg = await findBlackDexPkg(s);
+    if (!pkg)
+        throw new Error("设备上未安装 BlackDex，无法拉取结果。");
+    const { remote, listing } = await resolveRemoteDump(s, pkg, targetPkg);
+    const r = await pull(s, remote, localOutDir);
+    if (r.code !== 0)
+        throw new Error(`拉取 BlackDex 结果失败：\n${r.stderr}`);
+    return {
+        serial: s,
+        remote,
+        pulledTo: join(localOutDir, targetPkg ?? "dump"),
+        listing,
+    };
+}

package/dist/unpack/frida.js

@@ -0,0 +1,66 @@
+import { join } from "node:path";
+import { existsSync } from "node:fs";
+import { exec, hasCommand, ensureDir } from "../util.js";
+import { resolveSerial, shell, push } from "../adb.js";
+/** 推送并启动 frida-server（需 root）。默认使用项目 tools/frida-server。 */
+export async function fridaPrepare(serial, serverLocalPath) {
+    const s = await resolveSerial(serial);
+    const local = serverLocalPath || join(process.cwd(), "tools", "frida-server");
+    if (!existsSync(local)) {
+        throw new Error(`未找到 frida-server：${local}\n请下载与本机 frida 版本匹配的 android-arm64 文件到该路径。`);
+    }
+    await push(s, local, "/data/local/tmp/frida-server");
+    await shell(s, "su -c 'chmod 755 /data/local/tmp/frida-server'");
+    await shell(s, "su -c 'killall frida-server 2>/dev/null; true'");
+    await shell(s, "su -c 'setenforce 0'");
+    await shell(s, "su -c 'nohup /data/local/tmp/frida-server >/data/local/tmp/frida.log 2>&1 &'");
+    const ps = await shell(s, "su -c 'ps -A | grep frida-server'");
+    const running = /frida-server/.test(ps.stdout);
+    return {
+        serial: s,
+        running,
+        message: running
+            ? "frida-server 已在设备上运行（Magisk/root）。可调用 frida_unpack。"
+            : `frida-server 启动失败，请查看 /data/local/tmp/frida.log\n${ps.stdout}${ps.stderr}`,
+    };
+}
+/**
+ * root 方案：基于 frida-dexdump，从内存中搜索并 dump 已解密的 dex。
+ */
+export async function fridaUnpack(pkg, outDir, opts = {}) {
+    const s = await resolveSerial(opts.serial);
+    await ensureDir(outDir);
+    if (!(await hasCommand("frida-dexdump"))) {
+        throw new Error("未找到 frida-dexdump。请先安装：pip install frida-tools frida-dexdump\n" +
+            "并确保设备已 root 且 frida-server 正在运行。");
+    }
+    const ps = await shell(s, "su -c 'ps -A | grep frida-server' || true");
+    const fridaRunning = /frida-server/.test(ps.stdout);
+    const args = ["-D", s];
+    if (opts.spawn !== false) {
+        args.push("-f", pkg);
+    }
+    else {
+        args.push("-n", pkg);
+    }
+    args.push("-o", outDir);
+    if (opts.deepSearch !== false)
+        args.push("-d");
+    if (opts.sleepSec != null)
+        args.push("--sleep", String(opts.sleepSec));
+    else if (opts.spawn !== false)
+        args.push("--sleep", "10");
+    const r = await exec("frida-dexdump", args, {
+        timeoutMs: opts.timeoutMs ?? 300000,
+    });
+    return {
+        pkg,
+        outDir,
+        code: r.code,
+        log: (fridaRunning ? "" : "[警告] 设备上未检测到 frida-server 进程。\n") +
+            r.stdout +
+            "\n" +
+            r.stderr,
+        dexHint: `dump 出的 dex 位于 ${outDir}，可用 dex_to_smali 反编译。`,
+    };
+}

package/dist/unpack/static.js

@@ -0,0 +1,50 @@
+import AdmZip from "adm-zip";
+import { join, basename, isAbsolute } from "node:path";
+import { stat } from "node:fs/promises";
+import { ensureDir } from "../util.js";
+import { resolveSerial, getApkPaths, pull } from "../adb.js";
+/**
+ * 静态解包：解压 APK，提取所有 classes*.dex。
+ * 对加固 APK，这里拿到的只是壳 dex，需要配合 Frida/BlackDex 做运行时脱壳。
+ */
+export async function staticUnpack(apkPath, outDir) {
+    const st = await stat(apkPath).catch(() => null);
+    if (!st || !st.isFile())
+        throw new Error(`APK 文件不存在：${apkPath}`);
+    await ensureDir(outDir);
+    const zip = new AdmZip(apkPath);
+    const entries = zip.getEntries();
+    const dexFiles = [];
+    for (const e of entries) {
+        if (/^classes\d*\.dex$/i.test(e.entryName)) {
+            zip.extractEntryTo(e, outDir, false, true);
+            dexFiles.push(join(outDir, basename(e.entryName)));
+        }
+    }
+    return {
+        apk: apkPath,
+        outDir,
+        dexFiles,
+        note: dexFiles.length > 0
+            ? `已提取 ${dexFiles.length} 个 dex。若该 APK 被加固，这些可能只是壳 dex。`
+            : "未发现 classes*.dex，可能是加固后 dex 被加密隐藏，需运行时脱壳。",
+    };
+}
+/** 从设备上拉取已安装应用的 APK，返回本地主 APK 路径。 */
+export async function pullApkFromDevice(pkg, outDir, serial) {
+    const s = await resolveSerial(serial);
+    const remotePaths = await getApkPaths(s, pkg);
+    await ensureDir(outDir);
+    const localApks = [];
+    for (const remote of remotePaths) {
+        const name = basename(remote);
+        const local = join(outDir, name === "base.apk" ? `${pkg}.apk` : `${pkg}-${name}`);
+        const r = await pull(s, remote, local);
+        if (r.code !== 0)
+            throw new Error(`拉取 APK 失败：${remote}\n${r.stderr}`);
+        localApks.push(isAbsolute(local) ? local : join(process.cwd(), local));
+    }
+    // base.apk 作为主 APK
+    const baseApk = localApks.find((p) => p.endsWith(`${pkg}.apk`)) || localApks[0];
+    return { localApks, baseApk };
+}

package/dist/util.js

@@ -0,0 +1,61 @@
+import { spawn } from "node:child_process";
+import { mkdir } from "node:fs/promises";
+/**
+ * 执行一个外部命令并收集输出。不经过 shell，避免 Windows 下的转义问题。
+ */
+export function exec(cmd, args, opts = {}) {
+    return new Promise((resolve) => {
+        const child = spawn(cmd, args, {
+            cwd: opts.cwd,
+            windowsHide: true,
+            shell: false,
+        });
+        let stdout = "";
+        let stderr = "";
+        let finished = false;
+        const timer = opts.timeoutMs
+            ? setTimeout(() => {
+                if (!finished) {
+                    child.kill();
+                    finished = true;
+                    resolve({ code: -1, stdout, stderr: stderr + "\n[超时被终止]" });
+                }
+            }, opts.timeoutMs)
+            : null;
+        child.stdout.on("data", (d) => (stdout += d.toString()));
+        child.stderr.on("data", (d) => (stderr += d.toString()));
+        child.on("error", (err) => {
+            if (finished)
+                return;
+            finished = true;
+            if (timer)
+                clearTimeout(timer);
+            resolve({ code: -1, stdout, stderr: stderr + "\n" + err.message });
+        });
+        child.on("close", (code) => {
+            if (finished)
+                return;
+            finished = true;
+            if (timer)
+                clearTimeout(timer);
+            resolve({ code: code ?? -1, stdout, stderr });
+        });
+        if (opts.input) {
+            child.stdin.write(opts.input);
+            child.stdin.end();
+        }
+    });
+}
+/** 判断某个命令是否在 PATH 中可用。 */
+export async function hasCommand(cmd) {
+    const probe = process.platform === "win32" ? "where" : "which";
+    const r = await exec(probe, [cmd], { timeoutMs: 5000 });
+    return r.code === 0;
+}
+export async function ensureDir(dir) {
+    await mkdir(dir, { recursive: true });
+}
+/** 组合文本工具结果，方便 MCP 返回。 */
+export function textResult(text) {
+    return { content: [{ type: "text", text }] };
+}