Skip to content

Windows 上的安卓应用运行器:双击 APK 即装,应用以独立窗口与桌面图标运行,自持 QEMU 运行时

36.4 KB
Raw Blame
'use strict';
/**
 * adb 客户端封装
 * 只做 apkstart 需要的那部分:安装 / 启动 / 停止 / 卸载 / 文件同步 / 截图
 */
const { execFile, spawn } = require('child_process');
const fs = require('fs');
const os = require('os');
const path = require('path');
const crypto = require('crypto');

const COMMON_ADB_PATHS = [
  path.join(process.env.LOCALAPPDATA || '', 'Android', 'Sdk', 'platform-tools', 'adb.exe'),
  'C:\\Android\\platform-tools\\adb.exe',
  'C:\\adb\\adb.exe',
  'C:\\LDPlayer\\LDPlayer9\\adb.exe',
  'C:\\Program Files\\Netease\\MuMuPlayer-12.0\\shell\\adb.exe',
  'C:\\Program Files\\BlueStacks_nxt\\HD-Adb.exe',
];

/**
 * 把 pm install 的原始失败原因翻译成用户能看懂的中文。
 * 保留原始错误码在末尾,便于搜索排查。
 */
function friendlyInstallError(raw) {
  const code = /INSTALL_[A-Z_]+/.exec(raw);
  const tag = code ? code[0] : '';
  const table = {
    INSTALL_FAILED_NO_MATCHING_ABIS:
      '安装失败:这个应用只提供 ARM 原生库(多数国产应用如此),'
      + '当前系统镜像没有 ARM 转译层。ApkStart 会自动切换到内置新版翻译层的兼容镜像并重试。',
    INSTALL_FAILED_OLDER_SDK:
      '安装失败:应用要求的 Android 版本高于当前运行时(需更高系统镜像)。',
    INSTALL_PARSE_FAILED_NO_CERTIFICATES:
      '安装失败:APK 没有有效签名,无法安装。',
    INSTALL_PARSE_FAILED_INCONSISTENT_CERTIFICATES:
      '安装失败:与已安装版本签名不一致,请先卸载旧版再装。',
    INSTALL_FAILED_VERSION_DOWNGRADE:
      '安装失败:设备上已安装更高版本,不能降级覆盖。',
    INSTALL_FAILED_INSUFFICIENT_STORAGE:
      '安装失败:运行时磁盘空间不足,请清理后重试。',
    INSTALL_FAILED_INVALID_APK:
      '安装失败:APK 文件损坏或不完整(可能下载未完成),请重新获取。',
    INSTALL_FAILED_INVALID_URI: '安装失败:APK 路径含特殊字符,请把文件移到纯英文路径后重试。',
    INSTALL_FAILED_ALREADY_EXISTS: '安装失败:已存在同名应用且签名不同,请先卸载。',
    INSTALL_FAILED_UPDATE_INCOMPATIBLE: '安装失败:与已安装版本签名不一致,请先卸载旧版。',
    INSTALL_FAILED_DEPRECATED_SDK_VERSION:
      '安装失败:这是面向很老 Android 版本的应用(targetSdk 过低),Android 14 默认禁止安装。'
      + 'ApkStart 会自动用官方绕过参数重试。',
    INSTALL_FAILED_TEST_ONLY: '安装失败:这是仅供测试的应用包,已自动加上测试包参数重试。',
    INSTALL_FAILED_MISSING_SHARED_LIBRARY: '安装失败:应用依赖的设备特性(如特定厂商库)在当前运行时不存在。',
    INSTALL_FAILED_USER_RESTRICTION: '安装失败:系统限制了安装,请重启运行时后重试。',
    INSTALL_FAILED_CONFLICTING_PROVIDER: '安装失败:与已有应用的 ContentProvider 冲突,请卸载冲突应用。',
    INSTALL_FAILED_INTERNAL_ERROR: '安装失败:系统内部错误(常见于存储空间不足或开机未完成),请重启运行时后重试。',
  };
  const msg = table[tag];
  return msg ? `${msg}(${tag})` : `安装失败:${raw}`;
}

/** 把启动后的崩溃日志翻译成能看懂的原因 */
function friendlyLaunchError(raw, pkg) {
  const t = String(raw || '');
  if (/DoBadTrampoline|libndk_translation|houdini|SIGABRT.*arm/i.test(t)) {
    return `${pkg || '应用'} 启动后崩溃:ARM 翻译层与该应用的信号处理不兼容。`
      + 'ApkStart 会自动切换到 Android 14 兼容镜像后重试。';
  }
  if (/UnsatisfiedLinkError|dlopen failed|couldn't find "lib|\.so.*not found/i.test(t)) {
    return `${pkg || '应用'} 启动后崩溃:缺少设备原生库(应用可能只提供 ARM 版本)。`
      + '会自动切换到带 ARM 翻译层的兼容镜像后重试。';
  }
  if (/ClassNotFoundException|NoClassDefFoundError|AndroidRuntime/i.test(t)) {
    return `${pkg || '应用'} 启动即崩溃(应用内部异常,可能与模拟器环境或缺少 Google 服务有关)。`;
  }
  if (/java\.lang\.SecurityException|Permission Denial/i.test(t)) {
    return `${pkg || '应用'} 启动失败:系统拒绝了启动请求(权限或签名问题)。`;
  }
  return `${pkg || '应用'} 未能启动${t ? `:${t.slice(0, 240)}` : '(进程未存活)'}`;
}

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

/** 已解析过的启动入口(adbPath|pkg → activity),10 分钟有效 */
const LAUNCHER_CACHE = new Map();

/**
 * Windows 版 adb 对非 ASCII 路径处理不稳定(中文用户名/中文下载目录很常见)。
 * 安装前把 APK 复制到纯 ASCII 的临时目录,装完即删。
 */
function stageApk(apkPath) {
  const p = String(apkPath || '');
  if (/^[\x20-\x7e]*$/.test(p) && p.length < 200) return { path: p, staged: false };
  const dir = path.join(os.tmpdir(), 'apkstart-install');
  fs.mkdirSync(dir, { recursive: true });
  const name = `${crypto.createHash('sha1').update(p).digest('hex').slice(0, 12)}.apk`;
  const target = path.join(dir, name);
  fs.copyFileSync(p, target);
  return { path: target, staged: true };
}

function unstage(staged) {
  if (!staged) return;
  try { fs.rmSync(staged, { force: true }); } catch (_) { /* ignore */ }
}

/**
 * 把「Activity」拼成 am start -n 需要的完整组件。
 * 两种形式都要支持:
 *   - 纯类名(老版本 apps.json 存的是这种):`MainActivity` / `.MainActivity` → `<pkg>/<activity>`
 *   - 完整组件(`cmd package resolve-activity` 的输出):`com.a.b/.Main` → 原样使用
 * 旧实现无条件拼 `${pkg}/${activity}`,遇到完整组件就变成 `pkg/pkg/class`,
 * am start 直接取消(result code=-92),表现是「点图标只看到安卓桌面」。
 */
function componentArg(pkg, activity) {
  const a = String(activity || '').trim();
  if (!a) return '';
  if (a.includes('/')) return a;
  return `${pkg}/${a}`;
}

/** 从 `cmd package resolve-activity --brief` 的输出里取出属于 pkg 的组件(容忍尾部空行/priority 行) */
function parseResolvedActivity(pkg, out) {
  const lines = String(out || '').split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
  for (let i = lines.length - 1; i >= 0; i -= 1) {
    const m = /^([\w.]+)\/([.\w$]+)$/.exec(lines[i]);
    if (m && m[1] === pkg) return `${m[1]}/${m[2]}`;
  }
  return '';
}

/**
 * adb install 的超时上限本来固定 240s,但 2GB+ 的安装包在慢盘上
 * 「push + 安装 + dexopt」很容易超过 4 分钟:一旦超时就会被当成安装失败,
 * 用户看到的就是「大包装了没反应/失败」。这里按包体放大,上限 20 分钟。
 */
function installTimeoutMs(bytes) {
  const mb = Math.max(1, Number(bytes || 0) / 1048576);
  return Math.min(1200000, Math.max(240000, Math.round(60000 + mb * 120)));
}

class AdbError extends Error {
  constructor(message, stderr, code) {
    super(message);
    this.stderr = stderr;
    this.code = code;
  }
}

/**
 * 解析 `find -exec stat -c '%Y|%s|%n'` 的输出。
 * 返回 null 表示输出不像 stat 结果(设备不支持)。
 */
function parseStatList(text) {
  const lines = String(text || '').split('\n').map((l) => l.trim()).filter(Boolean);
  if (!lines.length) return [];
  const rows = [];
  for (const l of lines) {
    const m = /^(\d{9,})\|(\d+)\|(.+)$/.exec(l);
    if (!m) continue;
    const rel = m[3].replace(/^\.\//, '');
    if (!rel || rel.endsWith('/')) continue;
    rows.push({ rel, size: Number(m[2]), mtime: Number(m[1]) * 1000 });
  }
  // 有输出但一行都解析不出来 → 说明不是 stat 格式
  if (!rows.length) return null;
  return rows;
}

class AdbClient {
  constructor({ adbPath, serial }) {
    this.adbPath = adbPath || 'adb';
    this.serial = serial || '';
    this._input = null;        // 常驻 `adb shell` 进程
    this._inputSeq = 0;
    this._waiters = new Map(); // id -> { resolve, reject, timer, token }
  }

  static resolveAdb(explicit, appRoot) {
    const candidates = [
      explicit,
      appRoot && path.join(appRoot, 'tools', 'platform-tools', 'adb.exe'),
      ...COMMON_ADB_PATHS,
    ].filter(Boolean);
    for (const c of candidates) {
      try { if (fs.existsSync(c)) return c; } catch (_) { /* ignore */ }
    }
    return 'adb'; // 交给 PATH
  }

  _args(args, withSerial = true) {
    const a = [];
    if (withSerial && this.serial) a.push('-s', this.serial);
    return a.concat(args);
  }

  _adbEnv() {
    return { ...process.env, ANDROID_ADB_SERVER_PORT: process.env.ANDROID_ADB_SERVER_PORT || '5044' };
  }

  exec(args, { timeout = 30000, withSerial = true, binary = false } = {}) {
    return new Promise((resolve, reject) => {
      const finalArgs = this._args(args, withSerial);
      execFile(this.adbPath, finalArgs, {
        timeout,
        maxBuffer: 64 * 1024 * 1024,
        encoding: binary ? 'buffer' : 'utf8',
        windowsHide: true,
        // 与运行时模拟器共用专用 adb server 端口(默认 5044),与 5037 上的
        // WSA / 第三方模拟器 adb 隔离,避免注册被反复踢掉导致设备 offline
        env: this._adbEnv(),
      }, (err, stdout, stderr) => {
        if (err) {
          // adb install 的失败原因写在 stdout 且退出码非 0;
          // 旧版只看 stderr,导致用户永远只看到一句空泛的「失败」。
          const text = [stdout, stderr, err.message].filter(Boolean).join('\n').trim();
          const e = new AdbError(`adb ${finalArgs.join(' ')} 失败: ${text}`, stderr, err.code);
          e.stdout = stdout;
          e.raw = text;
          return reject(e);
        }
        resolve({ stdout, stderr });
      });
    });
  }

  async shell(cmd, opts = {}) {
    const { stdout } = await this.exec(['shell', cmd], opts);
    return typeof stdout === 'string' ? stdout.trim() : stdout;
  }

  /**
   * 常驻输入通道。
   * 滚轮/返回是高频输入:每格滚轮都 execFile 一个 adb 会起一堆进程,
   * 桌面会明显发顿。这里复用一条 `adb shell`,每行一条命令,并在末尾
   * echo 一个结束标记 —— 既知道命令何时真正跑完,也天然形成背压,
   * 不会让滑动命令在 shell 里排成一长队。
   */
  _inputSession() {
    const old = this._input;
    if (old && old.exitCode === null && !old.killed && old.stdin && old.stdin.writable) return old;
    if (old) this.disposeInput();

    const p = spawn(this.adbPath, this._args(['shell'], true), {
      stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true, env: this._adbEnv(),
    });
    this._input = p;
    let buf = '';
    p.stdout.setEncoding('utf8');
    p.stdout.on('data', (chunk) => {
      buf += chunk;
      let i;
      while ((i = buf.indexOf('\n')) >= 0) {
        const line = buf.slice(0, i).trim();
        buf = buf.slice(i + 1);
        for (const [id, w] of this._waiters) {
          // 必须整行等于标记:某些 shell 会把整条命令行回显出来,
          // 用 contains 会把「刚写进去」误判成「已执行完」,滑动就会堆积。
          if (line === w.token) {
            this._waiters.delete(id);
            clearTimeout(w.timer);
            w.resolve(true);
            break;
          }
        }
      }
    });
    p.stderr.on('data', () => { /* 忽略:设备离线等信息由调用方兜底 */ });
    p.stdin.on('error', () => { /* 断开时由 exit 统一清理 */ });
    p.on('error', () => { this._failWaiters(new Error('adb shell 启动失败')); });
    p.on('exit', () => {
      if (this._input === p) this._input = null;
      this._failWaiters(new Error('adb shell 已退出'));
    });
    return p;
  }

  _failWaiters(err) {
    for (const [, w] of this._waiters) {
      clearTimeout(w.timer);
      w.reject(err);
    }
    this._waiters.clear();
  }

  /** 执行一条白名单内的 input 命令;失败会回收会话,调用方可回退到一次性 adb */
  async input(cmd, { timeout = 4000 } = {}) {
    const { isInputCommand } = require('./pointer');
    if (!isInputCommand(cmd)) throw new Error('非法的输入命令');
    const p = this._inputSession();
    const id = ++this._inputSeq;
    const token = `__APKSTART_${id}__`;
    return new Promise((resolve, reject) => {
      const timer = setTimeout(() => {
        this._waiters.delete(id);
        this.disposeInput();
        reject(new Error('input 命令超时'));
      }, timeout);
      this._waiters.set(id, { resolve, reject, timer, token });
      try {
        p.stdin.write(`${cmd}; echo ${token}\n`);
      } catch (e) {
        this._waiters.delete(id);
        clearTimeout(timer);
        reject(e);
      }
    });
  }

  disposeInput() {
    const p = this._input;
    this._input = null;
    for (const [, w] of this._waiters) {
      clearTimeout(w.timer);
      w.reject(new Error('输入通道已关闭'));
    }
    this._waiters.clear();
    if (p) {
      try { p.stdin.end(); } catch (_) { /* ignore */ }
      try { p.kill(); } catch (_) { /* ignore */ }
    }
  }

  async version() {
    const { stdout } = await this.exec(['version'], { withSerial: false });
    const m = /version\s+([\d.]+)/i.exec(stdout);
    return m ? m[1] : stdout.trim();
  }

  async connect() {
    if (!this.serial.includes(':')) return true;
    try {
      await this.exec(['connect', this.serial], { withSerial: false, timeout: 15000 });
    } catch (_) { /* 可能已连接 */ }
    return this.isOnline();
  }

  async isOnline() {
    try {
      const { stdout } = await this.exec(['get-state'], { timeout: 8000 });
      return stdout.trim() === 'device';
    } catch (_) {
      // get-state 在未指定 serial 时不可用,退化用 devices 列表
      try {
        const { stdout } = await this.exec(['devices'], { withSerial: false, timeout: 8000 });
        return stdout.split('\n').some((l) => l.startsWith(this.serial) && l.includes('device'));
      } catch (_) {
        return false;
      }
    }
  }

  async devices() {
    const { stdout } = await this.exec(['devices', '-l'], { withSerial: false });
    return stdout.split('\n').slice(1)
      .map((l) => l.trim())
      .filter((l) => l && l.includes('device') && !l.startsWith('*'))
      .map((l) => {
        const parts = l.split(/\s+/);
        return { serial: parts[0], state: parts[1], model: (l.match(/model:(\S+)/) || [])[1] || '' };
      })
      .filter((d) => d.state === 'device');
  }

  /**
   * 安装单个 APK,带自动降级:
   *  - 默认去掉 -g(自动授予全部权限在部分镜像上会让 PermissionController 崩掉);
   *  - 带 --bypass-low-target-sdk-block,解决 Android 14 拒绝安装老 targetSdk 应用;
   *  - adb 版本不认该参数 / 中文路径 / 传输错误时自动换写法重试;
   *  - NO_MATCHING_ABIS 抛带 code 的错误,交给上层自动切换兼容镜像。
   */
  async install(apkPath) {
    if (!fs.existsSync(apkPath)) throw new Error(`APK 不存在: ${apkPath}`);
    const staged = stageApk(apkPath);
    const file = staged.path;
    const variants = [
      // -g 自动授予运行时权限,省掉应用里的授权弹窗;部分镜像不支持则自动降级去掉
      ['install', '-r', '-t', '-g', '--bypass-low-target-sdk-block', file],
      ['install', '-r', '-t', '--bypass-low-target-sdk-block', file],
      ['install', '-r', '-t', file],
      ['install', '-r', file],
    ];
    let last = '';
    let timeout = 240000;
    try { timeout = installTimeoutMs(fs.statSync(file).size); } catch (_) { /* 取不到大小就用默认值 */ }
    try {
      for (const args of variants) {
        try {
          // eslint-disable-next-line no-await-in-loop
          const { stdout } = await this.exec(args, { timeout });
          if (/Failure|Error/i.test(stdout) && !/Success/i.test(stdout)) {
            throw new Error(String(stdout).trim());
          }
          return stdout.trim();
        } catch (e) {
          const raw = String(e.raw || e.stdout || e.message || '');
          last = raw;
          const tag = (/INSTALL_[A-Z_]+/.exec(raw) || [])[0] || '';

          if (tag === 'INSTALL_FAILED_NO_MATCHING_ABIS') {
            const err = new Error(friendlyInstallError(raw));
            err.code = 'NO_MATCHING_ABIS';
            err.raw = raw;
            throw err;
          }
          // 老 adb 不认新参数 / 测试包标记 → 换一种写法
          if (/Unknown option|unrecognized option|Unknown command/i.test(raw)) continue;
          if (tag === 'INSTALL_FAILED_TEST_ONLY' || tag === 'INSTALL_FAILED_DEPRECATED_SDK_VERSION') continue;
          // 传输类错误(设备掉线、adb server 重启)重试一次
          if (/device (not found|offline)|closed|protocol fault|no devices/i.test(raw)) {
            // eslint-disable-next-line no-await-in-loop
            await sleep(1500);
            continue;
          }
          if (tag) {
            const err = new Error(friendlyInstallError(raw));
            err.code = tag;
            err.raw = raw;
            throw err;
          }
          // 没拿到明确错误码:最后一种写法再试
        }
      }
      const err = new Error(friendlyInstallError(last || '安装失败,未获得明确原因'));
      err.code = (/INSTALL_[A-Z_]+/.exec(last) || [])[0] || 'INSTALL_UNKNOWN';
      err.raw = last;
      throw err;
    } finally {
      unstage(staged.staged ? file : null);
    }
  }

  /** 拆分 APK(.apks / .xapk 解出来的多个分片)走 install-multiple */
  async installMultiple(apkPaths) {
    if (!apkPaths || !apkPaths.length) throw new Error('没有可安装的分片 APK');
    const staged = apkPaths.map((p) => stageApk(p));
    const files = staged.map((s) => s.path);
    const totalBytes = staged.reduce((n, s) => n + (fs.existsSync(s.path) ? fs.statSync(s.path).size : 0), 0);
    const timeout = installTimeoutMs(totalBytes);
    try {
      for (const extra of [['-r', '-t', '--bypass-low-target-sdk-block'], ['-r', '-t']]) {
        try {
          // eslint-disable-next-line no-await-in-loop
          const { stdout } = await this.exec(['install-multiple', ...extra, ...files], { timeout });
          if (/Failure|Error/i.test(stdout) && !/Success/i.test(stdout)) throw new Error(stdout);
          return stdout.trim();
        } catch (e) {
          const raw = String(e.raw || e.stdout || e.message || '');
          if (/Unknown option|unrecognized option/i.test(raw)) continue;
          if (/INSTALL_FAILED_NO_MATCHING_ABIS/.test(raw)) {
            const err = new Error(friendlyInstallError(raw));
            err.code = 'NO_MATCHING_ABIS';
            throw err;
          }
          throw new Error(friendlyInstallError(raw));
        }
      }
      throw new Error('拆分 APK 安装失败');
    } finally {
      staged.forEach((s) => unstage(s.staged ? s.path : null));
    }
  }

  async uninstall(pkg) {
    try {
      await this.exec(['uninstall', pkg], { timeout: 60000 });
    } catch (e) {
      // 部分设备需要指定 user
      await this.exec(['shell', 'pm', 'uninstall', '--user', '0', pkg], { timeout: 60000 });
    }
  }

  async isInstalled(pkg) {
    const out = await this.shell(`pm path ${pkg}`);
    return /package:/.test(out);
  }

  async listPackages() {
    const out = await this.shell('pm list packages -3');
    return out.split('\n').map((l) => l.replace('package:', '').trim()).filter(Boolean);
  }

  /** 从系统解析真正的启动 Activity(清单里解析不出来时的兜底) */
  /** 应用升级后入口可能变,解析前先把这个包从缓存里摘掉 */
  clearLauncherCache(pkg) {
    if (!pkg) { LAUNCHER_CACHE.clear(); return; }
    LAUNCHER_CACHE.delete(`${this.adbPath}|${pkg}`);
  }

  async resolveLauncher(pkg) {
    // 解析入口 Activity 要一次 adb 往返(~200-400ms),而它在一个启动会话里不会变。
    // 缓存起来,第二次点同一个应用直接跳过;10 分钟后自然失效,重装应用也不会用错入口。
    const key = `${this.adbPath}|${pkg}`;
    const hit = LAUNCHER_CACHE.get(key);
    if (hit && Date.now() - hit.at < 10 * 60 * 1000) return hit.value;
    try {
      const out = await this.shell(
        `cmd package resolve-activity --brief ${pkg}`, { timeout: 10000 },
      );
      const comp = parseResolvedActivity(pkg, out);
      if (comp) {
        LAUNCHER_CACHE.set(key, { value: comp, at: Date.now() });
        return comp;
      }
    } catch (_) { /* 落到 monkey */ }
    return null;
  }

  /** 应用是否真的活着:am start 返回成功 ≠ 进程没崩 */
  async waitAppAlive(pkg, timeoutMs = 12000) {
    const start = Date.now();
    while (Date.now() - start < timeoutMs) {
      // eslint-disable-next-line no-await-in-loop
      const pid = await this.shell(`pidof ${pkg}`, { timeout: 6000 }).catch(() => '');
      if (String(pid).trim()) return { ok: true };
      // eslint-disable-next-line no-await-in-loop
      await sleep(1000);
    }
    let crash = '';
    try {
      crash = await this.shell(
        `logcat -d -t 250 -v brief AndroidRuntime:E DEBUG:E libc:E 2>/dev/null | `
        + `grep -i -E '${pkg}|FATAL|ndk_translation|SIGABRT|SIGSEGV|UnsatisfiedLink' | tail -n 30`,
        { timeout: 12000 },
      );
    } catch (_) { /* ignore */ }
    const text = String(crash || '').trim();
    // 没有崩溃日志时不能断言失败:部分大型应用首次启动要 20-40 秒
    return { ok: false, crash: text, uncertain: !text };
  }

  /**
   * 启动应用,带三级降级:
   *   freeform 独立窗口 → 普通全屏 → monkey 兜底;
   * 每次都验证进程是否存活,崩溃时抓 logcat 并抛带 code 的错误供上层自动切镜像。
   */
  async startApp(pkg, activity, { freeform = true, bounds = null, forceStop = false } = {}) {
    if (forceStop) await this.forceStop(pkg);
    // 必须用系统解析出来的 LAUNCHER 入口,不能只用 APK 里解析到的主 Activity:
    // 很多应用(红果短剧等)的启动页才做真正的初始化,直接进主 Activity 会
    // 抛 "had you called RpcService.init",表现为点开闪一下就没了。
    const resolved = (await this.resolveLauncher(pkg).catch(() => '')) || activity;
    // resolved 可能是完整组件(pkg/class),也可能只是类名(老 apps.json);
    // 这里统一成 am start -n 要的完整组件,避免 pkg/pkg/class 被系统取消。
    const comp = componentArg(pkg, resolved);
    const intent = comp
      ? ['-n', comp]
      : ['-a', 'android.intent.action.MAIN', '-c', 'android.intent.category.LAUNCHER', '-p', pkg];
    const modes = freeform
      ? [['--windowingMode', '5'], []]
      : [[]];
    let lastError = '';

    for (const mode of modes) {
      const parts = ['am', 'start', ...mode, '--activity-clear-top', ...intent];
      let out = '';
      try {
        // eslint-disable-next-line no-await-in-loop
        out = await this.shell(parts.join(' '), { timeout: 20000 });
      } catch (e) {
        lastError = String(e.message || e);
        continue;
      }
      if (/Error|Exception/i.test(out)) { lastError = out; continue; }

      if (bounds) this.resizeTaskOfPackage(pkg, bounds).catch(() => {});
      // eslint-disable-next-line no-await-in-loop
      const alive = await this.waitAppAlive(pkg, 6000);
      if (alive.ok) return out;
      if (alive.uncertain) return `${out}\n(应用仍在加载中)`;
      lastError = alive.crash || lastError;
      // 崩溃日志明确指向 ARM 翻译层时不再重试,直接交给上层切换兼容镜像
      if (/DoBadTrampoline|libndk_translation|UnsatisfiedLinkError|dlopen failed/i.test(alive.crash || '')) {
        const err = new Error(friendlyLaunchError(alive.crash, pkg));
        err.code = 'APP_CRASHED';
        err.crash = alive.crash;
        throw err;
      }
    }

    // monkey 兜底:部分镜像的 am start -a/-c/-p 解析不到 launcher
    try {
      const out = await this.shell(
        `monkey -p ${pkg} -c android.intent.category.LAUNCHER 1`, { timeout: 20000 },
      );
      const alive = await this.waitAppAlive(pkg, 12000);
      if (alive.ok || alive.uncertain) return out;
      lastError = alive.crash || lastError;
    } catch (e) {
      // 有明确崩溃信息时优先用它,否则保留原始启动错误
      if (!lastError) lastError = String(e.message || e);
    }

    if (!lastError) return 'started';
    const err = new Error(friendlyLaunchError(lastError, pkg));
    err.code = 'APP_CRASHED';
    err.crash = lastError;
    throw err;
  }

  async forceStop(pkg) {
    try { await this.shell(`am force-stop ${pkg}`); } catch (_) { /* ignore */ }
  }

  async runningPackages() {
    try {
      const out = await this.shell('dumpsys activity activities | grep -E "mResumedActivity|ResumedActivity"');
      const pkgs = [...out.matchAll(/([a-zA-Z][\w.]+\/[.\w$]+)/g)].map((m) => m[1].split('/')[0]);
      return [...new Set(pkgs)];
    } catch (_) {
      return [];
    }
  }

  async taskIdOfPackage(pkg) {
    try {
      const out = await this.shell('dumpsys activity recents');
      const blocks = out.split('Recent #');
      for (const b of blocks) {
        if (!b.includes(pkg)) continue;
        const m = /taskId=(\d+)/.exec(b) || /^\d+/.exec(b);
        if (m) return Number(m[1] || m[0]);
      }
    } catch (_) { /* ignore */ }
    return null;
  }

  async resizeTaskOfPackage(pkg, bounds) {
    const id = await this.taskIdOfPackage(pkg);
    if (!id) return false;
    await this.shell(`am task resize ${id} ${bounds.left} ${bounds.top} ${bounds.right} ${bounds.bottom}`);
    return true;
  }

  /** 开启 freeform(独立窗口)支持,失败不影响主流程 */
  async ensureFreeform() {
    // 合成为一次 adb shell:4 次独立 execFile 在 Windows 上要 600ms+,
    // 而这段正好在「点开应用」的等待里。
    const out = await this.shell(
      'settings put global enable_freeform_support 1 ; '
      + 'settings put global force_resizable_activities 1 ; '
      + 'settings put global development_settings_enabled 1 ; '
      + 'settings get global enable_freeform_support',
      { timeout: 12000 },
    ).catch(() => '0');
    return String(out).trim().split(/\r?\n/).pop().trim() === '1';
  }

  async wmSize() {
    const out = await this.shell('wm size');
    const m = /(\d+)x(\d+)/.exec(out.split('\n').pop() || out);
    return m ? { width: Number(m[1]), height: Number(m[2]) } : null;
  }

  async androidVersion() {
    return (await this.shell('getprop ro.build.version.release').catch(() => '')).trim();
  }

  async sdkInt() {
    const v = await this.shell('getprop ro.build.version.sdk').catch(() => '0');
    return Number(v.trim()) || 0;
  }

  async screenshot() {
    const { stdout } = await this.exec(['exec-out', 'screencap', '-p'], { binary: true, timeout: 20000 });
    return Buffer.isBuffer(stdout) ? stdout : Buffer.from(stdout);
  }

  async push(local, remote) {
    await this.exec(['push', local, remote], { timeout: 180000 });
  }

  async pull(remote, local) {
    await this.exec(['pull', remote, local], { timeout: 180000 });
  }

  async shellMkdir(remote) {
    await this.shell(`mkdir -p "${remote}"`);
  }

  async listRemote(remote) {
    const out = await this.shell(`ls -l "${remote}" 2>/dev/null`);
    return String(out).split('\n').map((line) => {
      const l = line.trim();
      if (!l || l.startsWith('total ')) return null;
      // Android 的 ls -l 有「含 group」和「不含 group」两种格式,日期可能是
      // "2026-11-12 18:52" 或 "Nov 12 18:52",用固定正则会全解析不出来。
      // 权限位之后的第 2 个数字即文件大小,最后一段即文件名。
      const parts = l.split(/\s+/);
      if (parts.length < 6 || !/^[\-dl]/.test(parts[0])) return null;
      const sizeIdx = parts.findIndex((p, i) => i >= 2 && /^\d+$/.test(p)
        && /(\d{4}-\d{2}-\d{2}|^[A-Za-z]{3}$)/.test(parts[i + 1] || ''));
      if (sizeIdx < 0) return null;
      const size = Number(parts[sizeIdx]);
      // 文件名在「时:分」token 之后(日期段 2-3 个 token,不固定)
      const timeIdx = parts.findIndex((p, i) => i > sizeIdx && /^\d{1,2}:\d{2}(:\d{2})?$/.test(p));
      const name = parts.slice((timeIdx >= 0 ? timeIdx : sizeIdx + 2) + 1).join(' ');
      return name ? { isDir: parts[0][0] === 'd', size, name } : null;
    }).filter(Boolean);
  }

  /**
   * 带真实 mtime 的远端列表(toybox stat)。
   * ls -l 的日期是「月 日 时:分」,无法可靠换算,会导致同步误判为「每次都变了」。
   * 返回 null 表示设备不支持 stat,调用方应退回 listRemote。
   */
  async listRemoteStat(remote) {
    let out = '';
    try {
      out = await this.shell(`cd "${remote}" 2>/dev/null && find . -type f -exec stat -c '%Y|%s|%n' {} + 2>/dev/null`);
    } catch (_) {
      return null;
    }
    const rows = parseStatList(out);
    if (!rows) return null;
    return rows;
  }

  /** 清除应用数据 */
  async clearData(pkg) {
    await this.shell(`pm clear ${pkg}`);
  }

  /** 导出应用数据(Windows/调试版可用 run-as;否则走 adb backup 兜底) */
  async exportAppData(pkg, localTarPath) {
    const remote = `/sdcard/apkstart-tmp-${pkg}.tar`;
    const cmd = `run-as ${pkg} tar -cf ${remote} . 2>/dev/null || (cd /data/data/${pkg} && tar -cf ${remote} .)`;
    await this.shell(cmd);
    await this.pull(remote, localTarPath);
    await this.shell(`rm -f ${remote}`).catch(() => {});
    return localTarPath;
  }

  async batteryOptimizeOff(pkg) {
    try { await this.shell(`dumpsys deviceidle whitelist +${pkg}`); } catch (_) { /* ignore */ }
  }

  /**
   * 把应用申请的运行时权限一次性授掉。
   * 不授会有两个后果:① 首次启动弹系统授权框,用户看到的是「应用没打开」;
   * ② 清过数据(pm clear)之后权限会掉,应用起来就卡在授权页。
   */
  async grantRuntimePermissions(pkg) {
    let dump = '';
    try {
      dump = await this.shell(`dumpsys package ${pkg}`, { timeout: 20000 });
    } catch (_) {
      return [];
    }
    const lines = String(dump).split(/\r?\n/);
    let inRuntime = false;
    const denied = [];
    for (const line of lines) {
      if (/^\s*runtime permissions:/.test(line)) { inRuntime = true; continue; }
      if (!inRuntime) continue;
      if (/^\s{0,6}\S/.test(line)) break; // 离开 runtime permissions 段
      const m = /^\s+([A-Za-z0-9_.]+):\s*granted=(\w+)/.exec(line);
      if (m && m[2] === 'false') denied.push(m[1]);
    }
    const granted = [];
    // 授权一次发完:pm grant 每条一次进程在 Windows 上要 150ms+,
    // 四五个权限就是 1 秒,而这些命令本身没有任何依赖关系。
    const cmds = [];
    for (const p of denied) cmds.push(`pm grant ${pkg} ${p}`);
    // 特殊权限走 appops,否则仍然会弹窗
    const ops = ['MANAGE_EXTERNAL_STORAGE', 'SYSTEM_ALERT_WINDOW', 'REQUEST_INSTALL_PACKAGES', 'WRITE_SETTINGS'];
    for (const op of ops) cmds.push(`cmd appops set ${pkg} ${op} allow`);
    if (cmds.length) {
      await this.shell(cmds.join(' ; '), { timeout: 20000 }).catch(() => '');
      granted.push(...denied);
    }
    return granted;
  }

  /**
   * 进入「就是这个应用」的状态:
   *  - 收起锁屏,避免开机后停在锁屏挡住应用;
   *  - 隐藏状态栏(保留底部导航键,鼠标不在手边时还能点返回/主页);
   *  - 关掉系统动画,低配机器上体感差别非常大。
   * 全部是 settings 级命令,一次几百毫秒,重复调用无害。
   */
  async prepareForeground() {
    // 以前是 7 条命令串行发,每条都要新起一个 adb 进程(Windows 上 150~250ms),
    // 合计 1~1.7 秒,全压在「点开应用」的等待里。合成一条 shell 后只剩一次往返。
    const cmds = [
      'wm dismiss-keyguard',
      'settings put global policy_control immersive.status=*',
      'settings put secure immersive_mode_confirmations confirmed',
      'settings put global window_animation_scale 0',
      'settings put global transition_animation_scale 0',
      'settings put global animator_duration_scale 0',
      'settings put system screen_off_timeout 2147483647',
      // 注意:这里不要再写 wm user-rotation / accelerometer_rotation。
      // 方向由 setOrientation / resetDisplayOverrides 按当前横竖屏状态统一定,
      // 在这里写死 lock 0 会把横屏方向覆盖回竖屏(画面躺倒)。
    ];
    await this.shell(cmds.join(' ; '), { timeout: 15000 }).catch(() => {});
    return true;
  }

  /** 鼠标右键 / 侧键 / 快捷键映射:走常驻输入通道,右键返回不再有 100ms 级延迟 */
  async _key(code) {
    try {
      await this.input(`input keyevent ${code}`);
    } catch (_) {
      // 运行时刚重启、常驻 shell 还没连上时,退回一次性 adb,不能把这次点击丢掉
      await this.shell(`input keyevent ${code}`, { timeout: 6000 }).catch(() => {});
    }
  }

  async keyBack() { return this._key(4); }
  async keyForward() { return this._key(125); }

  /**
   * 切换「手机排版 / 平板排版」。
   *
   * 关键:**绝不改 wm size**。改 wm size 会改变 guest framebuffer 的物理尺寸
   * (720x1280 -> 1280x720),而嵌入的 Qt 窗口仍是原来的尺寸/方向,于是画面被
   * 压扁或整体躺倒 90°,鼠标坐标映射也跟着错乱。更糟的是 wm size 覆盖会持久化
   * 在 /data 里,重启后仍然生效 —— 这就是用户反复看到「黑边 / 未填满 / 点不动」
   * 的根源。
   *
   * 现在只改逻辑密度(wm density),framebuffer 始终是 720x1280 正立:
   *   - 320dpi -> smallestWidth 360dp -> 手机排版
   *   - 190dpi -> smallestWidth 606dp(>=600dp)-> 平板 / 分栏排版
   * 尺寸、方向、点击映射全部不变,因此不会躺倒、不会有黑边、点击永远对应。
   */
  async setOrientation(landscape) {
    try {
      // 自动旋转必须关掉(否则传感器会乱转),但 user_rotation 要按目标方向锁:
      // 物理面板换成 1280x720 之后,只有把 user-rotation 锁成 1(90°),
      // Android 才会按横屏方向排版 —— 否则它仍按 rotation 0 渲染竖内容,
      // Qt 贴进横窗口就变成「躺倒 90°」。
      await this.shell('settings put system accelerometer_rotation 0; wm size reset', { timeout: 15000 });
      await this.shell(`wm user-rotation lock ${landscape ? 1 : 0}`, { timeout: 15000 });
      await this.shell(landscape ? 'wm density 190' : 'wm density reset', { timeout: 15000 });
      return true;
    } catch (_) {
      return false;
    }
  }

  /** 启动时清掉旧版本残留的 wm size / density 覆盖(持久化在 /data,会一直躺倒) */
  async resetDisplayOverrides(landscape = false) {
    try {
      await this.shell('wm size reset; wm density reset', { timeout: 15000 });
      await this.shell('settings put system accelerometer_rotation 0', { timeout: 15000 });
      await this.shell(`wm user-rotation lock ${landscape ? 1 : 0}`, { timeout: 15000 });
      return true;
    } catch (_) {
      return false;
    }
  }

  /** 当前逻辑分辨率(横屏切换后窗口要按它算宽高比) */
  async displaySize() {
    try {
      const out = await this.shell('wm size', { timeout: 8000 });
      const o = /Override size:\s*(\d+)x(\d+)/.exec(out);
      if (o) return { w: Number(o[1]), h: Number(o[2]) };
      const p = /Physical size:\s*(\d+)x(\d+)/.exec(out);
      if (p) return { w: Number(p[1]), h: Number(p[2]) };
    } catch (_) { /* ignore */ }
    return null;
  }

  /** 授权框还挂在最前面时(用户不在电脑前也能自愈),按返回键收掉 */
  async dismissPermissionDialog() {    try {
      const top = await this.shell('dumpsys activity activities', { timeout: 12000 });
      if (/GrantPermissionsActivity|permissioncontroller/i.test(String(top))) {
        await this.shell('input keyevent 4', { timeout: 6000 }).catch(() => {});
        return true;
      }
    } catch (_) { /* ignore */ }
    return false;
  }

  /**
   * 显示适配:全屏时把 Android 分辨率改成显示器尺寸(内容自动铺满),
   * 窗口模式时恢复竖屏预设。wm 命令是运行时生效的,不需要重启 Android。
   */
  async setDisplaySize(width, height, density) {
    const w = Math.max(320, Math.round(Number(width) || 0));
    const h = Math.max(480, Math.round(Number(height) || 0));
    await this.shell(`wm size ${w}x${h}`);
    if (density) await this.shell(`wm density ${Math.max(120, Math.min(640, Math.round(density)))}`);
    return { w, h };
  }

  async resetDisplaySize() {
    await this.shell('wm size reset').catch(() => {});
    await this.shell('wm density reset').catch(() => {});
  }
}

module.exports = {
  AdbClient, AdbError, parseStatList, friendlyInstallError, friendlyLaunchError,
  componentArg, parseResolvedActivity,
};