preflite 1.0.1

package/dist/shared-kernel/enums/index.js

@@ -0,0 +1,70 @@
+export var PlatformType;
+(function (PlatformType) {
+    PlatformType["HARMONY"] = "HARMONY";
+    PlatformType["ANDROID"] = "ANDROID";
+    PlatformType["IOS"] = "IOS";
+    PlatformType["WEB"] = "WEB";
+})(PlatformType || (PlatformType = {}));
+export var ResourceStatus;
+(function (ResourceStatus) {
+    ResourceStatus["OFFLINE"] = "OFFLINE";
+    ResourceStatus["ONLINE"] = "ONLINE";
+    ResourceStatus["LEASED"] = "LEASED";
+    ResourceStatus["RUNNING"] = "RUNNING";
+    ResourceStatus["DEBUGGING"] = "DEBUGGING";
+    ResourceStatus["ERROR"] = "ERROR";
+})(ResourceStatus || (ResourceStatus = {}));
+export var LeaseStatus;
+(function (LeaseStatus) {
+    LeaseStatus["PENDING"] = "PENDING";
+    LeaseStatus["ACTIVE"] = "ACTIVE";
+    LeaseStatus["RELEASED"] = "RELEASED";
+    LeaseStatus["EXPIRED"] = "EXPIRED";
+    LeaseStatus["REJECTED"] = "REJECTED";
+})(LeaseStatus || (LeaseStatus = {}));
+export var SessionStatus;
+(function (SessionStatus) {
+    SessionStatus["CREATED"] = "CREATED";
+    SessionStatus["RUNNING"] = "RUNNING";
+    SessionStatus["CLOSED"] = "CLOSED";
+    SessionStatus["FAILED"] = "FAILED";
+})(SessionStatus || (SessionStatus = {}));
+export var TaskStatus;
+(function (TaskStatus) {
+    TaskStatus["CREATED"] = "CREATED";
+    TaskStatus["DISPATCHED"] = "DISPATCHED";
+    TaskStatus["RUNNING"] = "RUNNING";
+    TaskStatus["SUCCESS"] = "SUCCESS";
+    TaskStatus["FAILED"] = "FAILED";
+    TaskStatus["CANCELLED"] = "CANCELLED";
+})(TaskStatus || (TaskStatus = {}));
+export var ArtifactType;
+(function (ArtifactType) {
+    ArtifactType["LOG"] = "LOG";
+    ArtifactType["TRACE"] = "TRACE";
+    ArtifactType["SCREENSHOT"] = "SCREENSHOT";
+    ArtifactType["VIDEO"] = "VIDEO";
+    ArtifactType["REPORT"] = "REPORT";
+})(ArtifactType || (ArtifactType = {}));
+export var EventType;
+(function (EventType) {
+    EventType["AGENT_REGISTERED"] = "AgentRegisteredEvent";
+    EventType["HEARTBEAT"] = "HeartbeatEvent";
+    EventType["RESOURCE_CHANGED"] = "ResourceChangedEvent";
+    EventType["LEASE_CHANGED"] = "LeaseChangedEvent";
+    EventType["SESSION_CHANGED"] = "SessionChangedEvent";
+    EventType["LIVE_DEBUG_SESSION_CHANGED"] = "LiveDebugSessionChangedEvent";
+    EventType["LIVE_DEBUG_FRAME"] = "LiveDebugFrameEvent";
+    EventType["LIVE_DEBUG_INPUT_ACK"] = "LiveDebugInputAckEvent";
+    EventType["TASK_UPDATED"] = "TaskUpdatedEvent";
+    EventType["ARTIFACT_READY"] = "ArtifactReadyEvent";
+    EventType["HEALTH_WARNING"] = "HealthWarningEvent";
+    /** 本机 http(s) 安装包 URL 缓存列表变化（新增下载、启动时索引加载、幽灵文件清理等） */
+    EventType["APP_PACKAGE_CACHE_CHANGED"] = "AppPackageCacheChangedEvent";
+})(EventType || (EventType = {}));
+export var OwnerType;
+(function (OwnerType) {
+    OwnerType["PLATFORM_TASK"] = "PLATFORM_TASK";
+    OwnerType["DEBUG_CLIENT"] = "DEBUG_CLIENT";
+    OwnerType["SYSTEM_MAINTENANCE"] = "SYSTEM_MAINTENANCE";
+})(OwnerType || (OwnerType = {}));

package/dist/shared-kernel/errors/index.js

@@ -0,0 +1,21 @@
+export class DomainError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "DomainError";
+    }
+}
+export class LeaseRequiredError extends DomainError {
+    constructor(resourceId) {
+        super(`resource ${resourceId} requires active lease`);
+        this.name = "LeaseRequiredError";
+    }
+}
+/** 设备已被其他租约占用，无法再 Acquire */
+export class LeaseConflictError extends DomainError {
+    resourceId;
+    constructor(resourceId) {
+        super(`设备 ${resourceId} 已被占用（已有租约）`);
+        this.resourceId = resourceId;
+        this.name = "LeaseConflictError";
+    }
+}

package/dist/shared-kernel/ids/index.js

@@ -0,0 +1,18 @@
+export function asAgentId(value) {
+    return value;
+}
+export function asResourceId(value) {
+    return value;
+}
+export function asLeaseId(value) {
+    return value;
+}
+export function asSessionId(value) {
+    return value;
+}
+export function asTaskId(value) {
+    return value;
+}
+export function asArtifactId(value) {
+    return value;
+}

package/dist/shared-kernel/time/index.js

@@ -0,0 +1,3 @@
+export function nowIso() {
+    return new Date().toISOString();
+}

package/dist/shared-kernel/value-objects/index.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/appPackageLocalPath.js

@@ -0,0 +1,75 @@
+import { access, mkdir, rm, writeFile } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { constants as FsConstants } from "node:fs";
+import { PlatformType } from "../shared-kernel/enums/index.js";
+function isProbablyHttpUrl(ref) {
+    return /^https?:\/\//i.test(ref.trim());
+}
+function extensionForPlatform(platform) {
+    switch (platform) {
+        case PlatformType.ANDROID:
+            return ".apk";
+        case PlatformType.IOS:
+            return ".ipa";
+        case PlatformType.HARMONY:
+            return ".hap";
+        default:
+            return ".pkg";
+    }
+}
+function guessDownloadFilename(sourceUrl, platform) {
+    try {
+        const u = new URL(sourceUrl);
+        const base = u.pathname.split("/").pop() ?? "";
+        const m = /\.(apk|ipa|hap)$/i.exec(base);
+        if (m)
+            return `download${m[0].toLowerCase()}`;
+    }
+    catch {
+        /* ignore */
+    }
+    return `download${extensionForPlatform(platform)}`;
+}
+async function ensureDownloadParent(dir) {
+    await mkdir(dir, { recursive: true });
+}
+/**
+ * - `http(s)://`：下载到临时目录（文件名尽量取自 URL 后缀）
+ * - `file:///path`：转为本地路径
+ * - 其它：视为本地路径（须已存在）
+ */
+export async function resolveAppRefToLocalFile(appRef, platform, downloadDir) {
+    const raw = appRef.trim();
+    if (!raw) {
+        throw new Error("appRef is empty");
+    }
+    if (isProbablyHttpUrl(raw)) {
+        const parent = (downloadDir?.trim() || tmpdir()).replace(/\/+$/, "");
+        await ensureDownloadParent(parent);
+        const name = `${Date.now()}-${randomBytes(8).toString("hex")}-${guessDownloadFilename(raw, platform)}`;
+        const dest = path.join(parent, name);
+        const res = await fetch(raw, { redirect: "follow" });
+        if (!res.ok) {
+            throw new Error(`download failed: HTTP ${res.status} ${res.statusText}`);
+        }
+        const buf = Buffer.from(await res.arrayBuffer());
+        await writeFile(dest, buf);
+        return {
+            localPath: dest,
+            cleanupTemp: async () => {
+                await rm(dest, { force: true });
+            },
+        };
+    }
+    const local = raw.startsWith("file://") ?
+        fileURLToPath(raw)
+        : path.resolve(raw);
+    await access(local, FsConstants.R_OK);
+    return {
+        localPath: local,
+        cleanupTemp: async () => { },
+    };
+}

package/dist/utils/deviceResourceRouting.js

@@ -0,0 +1,24 @@
+import { PlatformType } from "../shared-kernel/enums/index.js";
+/** 与 ResourceAdapter 生成的 `android:` / `ios:` / `harmony:` 前缀一致 */
+export function parseDeviceTargetFromResourceId(resourceId) {
+    const id = resourceId.trim();
+    if (id.startsWith("android:")) {
+        const serial = id.slice("android:".length).trim();
+        if (!serial)
+            return null;
+        return { platform: PlatformType.ANDROID, serial };
+    }
+    if (id.startsWith("ios:")) {
+        const udid = id.slice("ios:".length).trim();
+        if (!udid)
+            return null;
+        return { platform: PlatformType.IOS, udid };
+    }
+    if (id.startsWith("harmony:")) {
+        const deviceId = id.slice("harmony:".length).trim();
+        if (!deviceId)
+            return null;
+        return { platform: PlatformType.HARMONY, deviceId };
+    }
+    return null;
+}

package/dist/utils/harmonyAgentDebugDevice.js

@@ -0,0 +1,60 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { HarmonyDevice, getConnectedDevices } from "@midscene/harmony";
+import { hdcListTargetsSimpleLines, hdcListTargetsVerboseStdout, looksLikeHdcTcpConnectKey, pickHarmonyDeviceIdFromList, resolveHarmonyDeviceIdFromVerboseList, resolveHdcCliExecutable, } from "./harmonyHdcDeviceId.js";
+/** 与 midscene-device-session 一致：远程 hdc 时 Midscene 执行该脚本以注入 `hdc -s host:port`。 */
+export function getHarmonyHdcBridgeScriptPath() {
+    return path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "scripts", "hdc-bridge.sh");
+}
+export function extractHarmonyDeviceIdFromResourceId(resourceId) {
+    const raw = String(resourceId).trim();
+    const idx = raw.indexOf(":");
+    return idx >= 0 ? raw.slice(idx + 1).trim() : raw;
+}
+/**
+ * 创建并 connect 与任务执行（createHarmonySession）一致的 HarmonyDevice，供实时看屏 / 点击。
+ */
+export async function connectHarmonyAgentDebugDevice(params) {
+    const hdcPath = params.harmonyHdcPath?.trim();
+    let deviceId = extractHarmonyDeviceIdFromResourceId(params.resourceId);
+    const hasRemoteTconn = typeof params.harmonyHdcHost === "string" &&
+        params.harmonyHdcHost.trim() &&
+        typeof params.harmonyHdcPort === "number" &&
+        Number.isFinite(params.harmonyHdcPort) &&
+        params.harmonyHdcPort > 0;
+    if (hasRemoteTconn) {
+        const host = params.harmonyHdcHost.trim();
+        const port = params.harmonyHdcPort;
+        const server = { host, port };
+        const hdcBin = resolveHdcCliExecutable(hdcPath);
+        const remoteLines = await hdcListTargetsSimpleLines(hdcBin, 20_000, server);
+        let resolved = pickHarmonyDeviceIdFromList(remoteLines, deviceId || undefined);
+        if (!resolved) {
+            const verbose = await hdcListTargetsVerboseStdout(hdcBin, 20_000, server);
+            resolved = resolveHarmonyDeviceIdFromVerboseList(verbose, host, port, deviceId || undefined);
+        }
+        if (!resolved) {
+            throw new Error(`鸿蒙实时看屏：hdc -s ${host}:${port} list targets 未解析到设备序列号。请核对 hdc 与 MIDSCENE_HARMONY_HDC_HOST/PORT，并在设备管理选择 harmony: 序列号。`);
+        }
+        deviceId = resolved;
+        process.env.HDC_S = `${host}:${port}`;
+        process.env.HDC_REAL = hdcBin;
+    }
+    else if (!deviceId) {
+        const devices = await getConnectedDevices(hdcPath);
+        if (!devices.length) {
+            throw new Error("鸿蒙实时看屏：没有可用鸿蒙设备（hdc list targets 为空）");
+        }
+        deviceId = devices[0].deviceId;
+    }
+    if (deviceId && looksLikeHdcTcpConnectKey(deviceId)) {
+        throw new Error("鸿蒙设备 ID 不能为 ip:port 连接串；请在设备管理选择序列号，或配置 MIDSCENE_HARMONY_HDC_HOST 与 MIDSCENE_HARMONY_HDC_PORT。");
+    }
+    const realHdc = resolveHdcCliExecutable(hdcPath);
+    const hdcPathForMidscene = hasRemoteTconn ? getHarmonyHdcBridgeScriptPath() : hdcPath ? realHdc : undefined;
+    const device = new HarmonyDevice(deviceId, {
+        ...(hdcPathForMidscene ? { hdcPath: hdcPathForMidscene } : {}),
+    });
+    await device.connect();
+    return device;
+}

package/dist/utils/harmonyHdcDeviceId.js

@@ -0,0 +1,134 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+/**
+ * hdc 简单 `list targets` 可能把 TCP 连接键单独成行（如 192.168.1.1:8710），
+ * 不能作为 @midscene/harmony 里 HdcClient 的 deviceId（需为序列号等真实 target）。
+ */
+export function looksLikeHdcTcpConnectKey(id) {
+    return /^\d{1,3}(?:\.\d{1,3}){3}:\d+$/.test(id.trim());
+}
+/** 与 Midscene 一致：可用完整 hdc 路径或依赖 PATH 上的 `hdc` */
+export function resolveHdcCliExecutable(hdcPath) {
+    const p = typeof hdcPath === 'string' ? hdcPath.trim() : '';
+    return p || 'hdc';
+}
+/**
+ * 远程设备：与命令行 `hdc -s 172.23.x.x:8710 list targets` 一致（OpenHarmony hdc 会话参数 `-s`）。
+ * 不同于仅 `tconn`：部分环境必须用 `-s` 才能列出/操作该 TCP 上的设备。
+ */
+export function hdcRemoteServerPrefixArgs(host, port) {
+    return ['-s', `${host.trim()}:${port}`];
+}
+export function parseHdcListTargetsStdout(stdout) {
+    return stdout
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0 && !line.startsWith('['));
+}
+export async function hdcListTargetsSimpleLines(hdcExecutable = 'hdc', timeoutMs = 20000, server) {
+    const tail = ['list', 'targets'];
+    const argv = server ? [...hdcRemoteServerPrefixArgs(server.host, server.port), ...tail] : [...tail];
+    const { stdout } = await execFileAsync(hdcExecutable, argv, {
+        encoding: 'utf8',
+        timeout: timeoutMs,
+        maxBuffer: 2 * 1024 * 1024,
+    });
+    return parseHdcListTargetsStdout(stdout);
+}
+export async function hdcListTargetsVerboseStdout(hdcExecutable = 'hdc', timeoutMs = 20000, server) {
+    const tail = ['list', 'targets', '-v'];
+    const argv = server ? [...hdcRemoteServerPrefixArgs(server.host, server.port), ...tail] : [...tail];
+    const { stdout } = await execFileAsync(hdcExecutable, argv, {
+        encoding: 'utf8',
+        timeout: timeoutMs,
+        maxBuffer: 2 * 1024 * 1024,
+    });
+    return stdout;
+}
+/** 远程 `hdc -s ip:port list targets` 下列出的序列号（或本地 list）中选取设备 ID */
+export function pickHarmonyDeviceIdFromList(lineIds, preferredSerial) {
+    const cleaned = lineIds.map((l) => l.trim()).filter((l) => l.length > 0 && !looksLikeHdcTcpConnectKey(l));
+    const pref = preferredSerial?.trim();
+    if (pref && !looksLikeHdcTcpConnectKey(pref) && cleaned.includes(pref))
+        return pref;
+    if (cleaned.length === 1)
+        return cleaned[0];
+    if (cleaned.length > 1 && pref && cleaned.includes(pref))
+        return pref;
+    if (cleaned.length > 0)
+        return cleaned[0];
+    return null;
+}
+function splitVerboseLines(verboseStdout) {
+    return verboseStdout
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0 && !l.startsWith('['));
+}
+/** 部分 hdc 版本在 -v 中不重复打印 IP，仅标 TCP —— 用行内 TCP 标记兜底 */
+function collectVerboseFirstColumnFromTcpLines(verboseStdout) {
+    const lines = splitVerboseLines(verboseStdout);
+    const seen = new Set();
+    const out = [];
+    for (const line of lines) {
+        if (!/\bTCP\b/i.test(line))
+            continue;
+        const first = line.split(/\t+/)[0]?.trim();
+        if (first && !looksLikeHdcTcpConnectKey(first) && !seen.has(first)) {
+            seen.add(first);
+            out.push(first);
+        }
+    }
+    return out;
+}
+/**
+ * 从 `hdc list targets -v` 输出中解析与某次 tconn（host:port）相关的设备序列号。
+ */
+export function resolveHarmonyDeviceIdFromVerboseList(verboseStdout, hostIp, hdcPort, preferredDeviceId) {
+    const lines = splitVerboseLines(verboseStdout);
+    const tcpKey = `${hostIp}:${hdcPort}`;
+    if (preferredDeviceId && !looksLikeHdcTcpConnectKey(preferredDeviceId)) {
+        const pref = preferredDeviceId.trim();
+        for (const line of lines) {
+            const first = line.split(/\t+/)[0]?.trim();
+            if (first === pref)
+                return pref;
+        }
+    }
+    for (const line of lines) {
+        if (!line.includes(hostIp) && !line.includes(tcpKey))
+            continue;
+        const first = line.split(/\t+/)[0]?.trim();
+        if (first && !looksLikeHdcTcpConnectKey(first))
+            return first;
+    }
+    const loose = collectVerboseFirstColumnFromTcpLines(verboseStdout);
+    if (loose.length === 1)
+        return loose[0];
+    if (preferredDeviceId && !looksLikeHdcTcpConnectKey(preferredDeviceId)) {
+        const pref = preferredDeviceId.trim();
+        if (loose.includes(pref))
+            return pref;
+    }
+    return null;
+}
+/** 探测列表：同一主机下可能多台 */
+export function listHarmonyDeviceIdsFromVerboseForHost(verboseStdout, hostIp, hdcPort) {
+    const lines = splitVerboseLines(verboseStdout);
+    const tcpKey = `${hostIp}:${hdcPort}`;
+    const seen = new Set();
+    const out = [];
+    for (const line of lines) {
+        if (!line.includes(hostIp) && !line.includes(tcpKey))
+            continue;
+        const first = line.split(/\t+/)[0]?.trim();
+        if (first && !looksLikeHdcTcpConnectKey(first) && !seen.has(first)) {
+            seen.add(first);
+            out.push(first);
+        }
+    }
+    if (out.length > 0)
+        return out;
+    return collectVerboseFirstColumnFromTcpLines(verboseStdout);
+}

package/dist/utils/iosAgentDebugDevice.js

@@ -0,0 +1,72 @@
+import { readFile } from "node:fs/promises";
+export function extractIosUdidFromResourceId(resourceId) {
+    const raw = String(resourceId).trim();
+    const idx = raw.indexOf(":");
+    return idx >= 0 ? raw.slice(idx + 1).trim() : raw;
+}
+export function normalizeIosWdaPortRange(start, end) {
+    const s = Number.isFinite(start) && start > 0 ? Math.floor(start) : 8200;
+    const e = Number.isFinite(end) && end > 0 ? Math.floor(end) : 8399;
+    return s <= e ? { start: s, end: e } : { start: e, end: s };
+}
+export async function readMappedWdaPortForUdid(mapFilePath, udid) {
+    const path = mapFilePath?.trim();
+    if (!path)
+        return undefined;
+    try {
+        const raw = await readFile(path, "utf8");
+        const parsed = JSON.parse(raw);
+        const portRaw = parsed.portsByUdid?.[udid];
+        const port = Number(portRaw);
+        if (!Number.isFinite(port) || port <= 0)
+            return undefined;
+        return Math.floor(port);
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function isWdaHealthy(commandRunner, wdaHost, wdaPort, timeoutMs = 2_000) {
+    const host = wdaHost.trim() || "127.0.0.1";
+    const url = `http://${host}:${wdaPort}/status`;
+    const curlTimeoutSeconds = Math.max(1, Math.ceil(timeoutMs / 1_000));
+    const command = `curl -fsS --max-time ${curlTimeoutSeconds} ${JSON.stringify(url)}`;
+    const result = await commandRunner.run(command, timeoutMs + 500);
+    if (!result.ok)
+        return false;
+    return result.stdout.trim().length > 0;
+}
+async function findFirstHealthyWdaPortInRange(commandRunner, wdaHost, rangeStart, rangeEnd) {
+    const { start, end } = normalizeIosWdaPortRange(rangeStart, rangeEnd);
+    for (let port = start; port <= end; port += 1) {
+        if (await isWdaHealthy(commandRunner, wdaHost, port, 300)) {
+            return port;
+        }
+    }
+    return undefined;
+}
+/**
+ * 解析实时看屏可用的 WDA 端口（与 MidsceneRuntimeReal.prepareIosSession 优先级对齐：显式端口 → 映射文件 → 区间扫描）。
+ * 不在此函数内启动 WDA；需先由 watchdog / 任务 / 手动拉起 WDA。
+ */
+export async function resolveIosWdaPortForLiveDebug(commandRunner, params) {
+    const wdaHost = params.wdaHost.trim() || "127.0.0.1";
+    const udid = extractIosUdidFromResourceId(params.resourceId);
+    const explicit = params.explicitWdaPort;
+    if (Number.isFinite(explicit) && explicit > 0) {
+        const p = Math.floor(explicit);
+        if (await isWdaHealthy(commandRunner, wdaHost, p))
+            return p;
+        throw new Error(`iOS 实时看屏：环境变量指定的 WDA 端口 ${p} 不可用（${wdaHost}）。请检查 WDA 是否已启动或端口是否正确。`);
+    }
+    const mapped = await readMappedWdaPortForUdid(params.portMapFilePath, udid);
+    if (mapped != null) {
+        if (await isWdaHealthy(commandRunner, wdaHost, mapped))
+            return mapped;
+        throw new Error(`iOS 实时看屏：端口映射中 ${udid} 对应端口 ${mapped} 的 WDA 不可访问（${wdaHost}）。请检查 WDA 或 IOS_WDA_WATCHDOG，勿在未映射时使用区间扫描以免连错设备。`);
+    }
+    const scanned = await findFirstHealthyWdaPortInRange(commandRunner, wdaHost, params.portRangeStart, params.portRangeEnd);
+    if (scanned != null)
+        return scanned;
+    throw new Error(`iOS 实时看屏：未在 ${wdaHost} 上找到可用 WDA（端口区间 ${params.portRangeStart}-${params.portRangeEnd}）。请启动 WDA、配置 IOS_WDA_PORT_MAP_FILE_PATH，或设置 MIDSCENE_IOS_WDA_PORT。`);
+}

package/dist/utils/iosMjpegCapture.js

@@ -0,0 +1,90 @@
+import http from "node:http";
+import https from "node:https";
+/** 从已缓冲的字节中截取第一张 JPEG（SOI … EOI） */
+export function extractFirstJpegFromBuffer(buf) {
+    const soi = buf.indexOf(Buffer.from([0xff, 0xd8]));
+    if (soi === -1)
+        return null;
+    const eoi = buf.indexOf(Buffer.from([0xff, 0xd9]), soi + 2);
+    if (eoi === -1)
+        return null;
+    return buf.subarray(soi, eoi + 2);
+}
+function mjpegStreamUrl(wdaHost, mjpegPort) {
+    const h = wdaHost.trim() || "127.0.0.1";
+    const hostForUrl = h.includes(":") && !h.startsWith("[") ? `[${h}]` : h;
+    return `http://${hostForUrl}:${mjpegPort}/`;
+}
+/**
+ * 从 WDA MJPEG 服务（默认 9100，与 WebDriver 会话端口独立）读取流直到拼出第一张 JPEG。
+ * 不创建 WebDriver 会话，可与 Midscene 任务子进程并行，避免顶掉任务 session。
+ */
+export async function captureFirstJpegFromWdaMjpegStream(wdaHost, mjpegPort, options) {
+    const timeoutMs = options?.timeoutMs ?? 8_000;
+    const maxBytes = options?.maxBytes ?? 6 * 1024 * 1024;
+    const urlString = mjpegStreamUrl(wdaHost, mjpegPort);
+    const u = new URL(urlString);
+    const lib = u.protocol === "https:" ? https : http;
+    return new Promise((resolve, reject) => {
+        const req = lib.request({
+            hostname: u.hostname,
+            port: u.port || 80,
+            path: `${u.pathname}${u.search}` || "/",
+            method: "GET",
+            headers: { Connection: "close", Accept: "*/*" },
+            timeout: timeoutMs,
+        }, (res) => {
+            if (res.statusCode != null && res.statusCode >= 400) {
+                res.resume();
+                reject(new Error(`MJPEG HTTP ${res.statusCode}`));
+                return;
+            }
+            const chunks = [];
+            let total = 0;
+            let settled = false;
+            const settle = (fn) => {
+                if (settled)
+                    return;
+                settled = true;
+                try {
+                    res.destroy();
+                }
+                catch {
+                    /* ignore */
+                }
+                fn();
+            };
+            res.on("data", (chunk) => {
+                if (settled)
+                    return;
+                chunks.push(chunk);
+                total += chunk.length;
+                if (total > maxBytes) {
+                    settle(() => reject(new Error("MJPEG: exceeded maxBytes before first JPEG")));
+                    return;
+                }
+                const buf = Buffer.concat(chunks, total);
+                const jpeg = extractFirstJpegFromBuffer(buf);
+                if (jpeg) {
+                    settle(() => resolve(jpeg));
+                }
+            });
+            res.on("end", () => {
+                if (settled)
+                    return;
+                settle(() => reject(new Error("MJPEG: stream ended before first complete JPEG")));
+            });
+            res.on("error", (err) => {
+                settle(() => reject(err instanceof Error ? err : new Error(String(err))));
+            });
+        });
+        req.on("error", (err) => {
+            reject(err instanceof Error ? err : new Error(String(err)));
+        });
+        req.on("timeout", () => {
+            req.destroy();
+            reject(new Error("MJPEG: request timeout"));
+        });
+        req.end();
+    });
+}

package/dist/utils/liveDebugForegroundParse.js

@@ -0,0 +1,71 @@
+/**
+ * 从 `adb shell dumpsys activity …` / `dumpsys window …` 等**小片段** stdout 解析当前前台包名（Android 包名写入 `bundleId` 字段以与 iOS 对齐）。
+ */
+export function parseAndroidForegroundFromDumpsys(text) {
+    const lines = text.split("\n");
+    for (const line of lines) {
+        if (!line.includes("ResumedActivity") && !line.includes("resumed"))
+            continue;
+        const m = line.match(/ActivityRecord\{[^ ]+\s+u\d+\s+([^/\s]+)\//);
+        if (m?.[1])
+            return { bundleId: m[1] };
+    }
+    for (const line of lines) {
+        if (!line.includes("mCurrentFocus"))
+            continue;
+        const m = line.match(/mCurrentFocus=Window\{[^}]+\s(?:u0|u\d+)\s+([^/\s}]+)\//);
+        if (m?.[1])
+            return { bundleId: m[1] };
+    }
+    const act = text.match(/^\s*ACTIVITY\s+([A-Za-z0-9_.]+)\//m);
+    if (act?.[1])
+        return { bundleId: act[1] };
+    return undefined;
+}
+function pickHarmonyBundleFromChunk(chunk) {
+    const bundle = chunk.match(/"bundleName"\s*:\s*"([^"]+)"/)?.[1] ??
+        chunk.match(/\bbundleName\s*=\s*"([^"]+)"/)?.[1] ??
+        chunk.match(/\bbundleName\s*[:=]\s*([A-Za-z0-9_.]+)\b/i)?.[1];
+    if (!bundle)
+        return undefined;
+    const name = chunk.match(/"appName"\s*:\s*"([^"]+)"/)?.[1] ??
+        chunk.match(/\bappName\s*=\s*"([^"]+)"/)?.[1] ??
+        chunk.match(/\bappName\s*[:=]\s*([^\r\n]+)/i)?.[1]?.trim();
+    const pidM = chunk.match(/\b(?:pid|processId)\s*[:=]\s*(\d{2,8})\b/i);
+    const pid = pidM?.[1] ? Number.parseInt(pidM[1], 10) : undefined;
+    const out = { bundleId: bundle };
+    if (name)
+        out.name = name.slice(0, 400);
+    if (pid !== undefined && Number.isFinite(pid))
+        out.pid = pid;
+    return out;
+}
+/**
+ * 从鸿蒙 `aa dump` / `hidumper` 等 stdout 解析前台 bundle（写入 `bundleId`）。
+ */
+export function parseHarmonyForegroundFromShellDump(text) {
+    const t = text.length > 800_000 ? text.slice(0, 800_000) : text;
+    const fgIter = t.matchAll(/\b(?:FOREGROUND|STATE_FOREGROUND)\b/gi);
+    for (const m of fgIter) {
+        const pos = m.index ?? 0;
+        const chunk = t.slice(Math.max(0, pos - 2500), Math.min(t.length, pos + 2500));
+        const hit = pickHarmonyBundleFromChunk(chunk);
+        if (hit)
+            return hit;
+    }
+    const focusIdx = t.search(/(?:Focus|focus)(?:ed)?Window/i);
+    if (focusIdx >= 0) {
+        const w = t.slice(focusIdx, focusIdx + 1400);
+        const bundle = w.match(/"bundleName"\s*:\s*"([^"]+)"/)?.[1] ??
+            w.match(/\bbundleName\s*=\s*"([^"]+)"/)?.[1];
+        if (bundle) {
+            const name = w.match(/"appName"\s*:\s*"([^"]+)"/)?.[1] ?? w.match(/\bappName\s*=\s*"([^"]+)"/)?.[1];
+            return name ? { bundleId: bundle, name: name.slice(0, 400) } : { bundleId: bundle };
+        }
+    }
+    const top = t.match(/\btop(?:Mission|Ability)[^\n\r]{0,240}?(?:bundleName|bundle)\s*[:=]\s*\[?([A-Za-z0-9_.]+)\]?/i)?.[1] ??
+        t.match(/\bmain(?:Ability)?BundleName\s*[:=]\s*\[?([A-Za-z0-9_.]+)\]?/i)?.[1];
+    if (top)
+        return { bundleId: top };
+    return undefined;
+}