preflite 1.0.1

package/dist/utils/midscene-device-session.js

@@ -0,0 +1,353 @@
+import { execFile, execSync } from 'node:child_process';
+import { promisify } from 'node:util';
+import { hdcListTargetsSimpleLines, hdcListTargetsVerboseStdout, looksLikeHdcTcpConnectKey, pickHarmonyDeviceIdFromList, resolveHarmonyDeviceIdFromVerboseList, resolveHdcCliExecutable, } from "./harmonyHdcDeviceId.js";
+import { getHarmonyHdcBridgeScriptPath } from "./harmonyAgentDebugDevice.js";
+import { AndroidAgent, AndroidDevice } from '@midscene/android';
+import { HarmonyAgent, HarmonyDevice, getConnectedDevices as getHarmonyDevices } from '@midscene/harmony';
+import { IOSAgent, IOSDevice } from '@midscene/ios';
+import { midsceneTaskCacheFromEnv } from "./midscene-task-cache-env.js";
+const execFileAsync = promisify(execFile);
+const REPLAN_CYCLE_LIMIT = 40;
+const WAIT_AFTER_ACTION = 2000;
+const DEFAULT_AI_CONTEXT = '若出现权限、协议或系统弹窗请点击同意或允许；若出现登录页可关闭。';
+const MIDSCENE_EVENT_PREFIX = '__MIDSCENE_EVENT__';
+function flowStepIndexFromEnv() {
+    const raw = typeof process.env.MIDSCENE_FLOW_STEP_INDEX === 'string'
+        ? process.env.MIDSCENE_FLOW_STEP_INDEX.trim()
+        : '';
+    const n = raw ? Number.parseInt(raw, 10) : Number.NaN;
+    return Number.isFinite(n) && n >= 1 ? Math.floor(n) : undefined;
+}
+function flowStepIndexFromDumpTasks(tasks) {
+    for (const t of tasks) {
+        const q = t.flowStepIndex;
+        if (typeof q === 'number' && Number.isFinite(q) && q >= 1)
+            return Math.floor(q);
+        if (typeof q === 'string') {
+            const n = Number.parseInt(q.trim(), 10);
+            if (Number.isFinite(n) && n >= 1)
+                return n;
+        }
+    }
+    return undefined;
+}
+function emitMidsceneEvent(payload) {
+    try {
+        console.log(`${MIDSCENE_EVENT_PREFIX}${JSON.stringify(payload)}`);
+    }
+    catch {
+        /* ignore */
+    }
+}
+function finiteNumber(v) {
+    const n = typeof v === 'number' ? v : Number(v);
+    return Number.isFinite(n) && n >= 0 ? n : undefined;
+}
+/**
+ * Apply MIDSCENE_FLOW_STEP_INDEX from the current environment to each task in
+ * the Midscene execution dump, so _merged.dump.json can align screenshots with
+ * flow steps.
+ */
+function applyFlowStepIndexToDumpTasks(tasks) {
+    const raw = typeof process.env.MIDSCENE_FLOW_STEP_INDEX === 'string' ? process.env.MIDSCENE_FLOW_STEP_INDEX.trim() : '';
+    const stepIndex = raw ? Number.parseInt(raw, 10) : Number.NaN;
+    if (!Number.isFinite(stepIndex) || stepIndex < 1)
+        return;
+    for (const t of tasks) {
+        if (t && typeof t === 'object' && !Object.prototype.hasOwnProperty.call(t, 'flowStepIndex')) {
+            ;
+            t.flowStepIndex = stepIndex;
+        }
+    }
+}
+function summarizeExecutionUsage(tasks) {
+    const summary = {
+        prompt_tokens: 0,
+        completion_tokens: 0,
+        total_tokens: 0,
+        cached_input: 0,
+        callCount: 0,
+    };
+    let durationMs = 0;
+    let hasDuration = false;
+    for (const task of tasks) {
+        const taskInfo = task.log?.taskInfo;
+        const usage = task.usage ?? taskInfo?.usage;
+        if (!usage)
+            continue;
+        summary.callCount += 1;
+        summary.prompt_tokens += finiteNumber(usage.prompt_tokens) ?? 0;
+        summary.completion_tokens += finiteNumber(usage.completion_tokens) ?? 0;
+        summary.total_tokens += finiteNumber(usage.total_tokens) ?? 0;
+        summary.cached_input += finiteNumber(usage.cached_input) ?? 0;
+        const usageDuration = finiteNumber(usage.time_cost);
+        const taskInfoDuration = finiteNumber(taskInfo?.durationMs);
+        const taskDuration = usageDuration ?? taskInfoDuration;
+        if (taskDuration != null) {
+            durationMs += taskDuration;
+            hasDuration = true;
+        }
+        if (typeof usage.model_name === 'string' && usage.model_name.trim()) {
+            summary.model_name = usage.model_name.trim();
+        }
+        if (typeof usage.model_description === 'string' && usage.model_description.trim()) {
+            summary.model_description = usage.model_description.trim();
+        }
+    }
+    if (summary.callCount <= 0)
+        return null;
+    if (summary.total_tokens <= 0) {
+        summary.total_tokens = summary.prompt_tokens + summary.completion_tokens;
+    }
+    if (hasDuration)
+        summary.durationMs = durationMs;
+    return summary;
+}
+function attachMidsceneAgentEventHooks(platform, agent) {
+    agent.onTaskStartTip = (tip) => {
+        const text = typeof tip === 'string' ? tip.trim() : '';
+        if (!text)
+            return;
+        emitMidsceneEvent({
+            type: 'task-start-tip',
+            platform,
+            tip: text,
+            ts: Date.now(),
+        });
+    };
+    if (typeof agent.addDumpUpdateListener === 'function') {
+        let lastName = '';
+        let lastMetricKey = '';
+        agent.addDumpUpdateListener((_dump, executionDump) => {
+            const name = typeof executionDump?.name === 'string' ? executionDump.name.trim() : '';
+            const tasks = Array.isArray(executionDump?.tasks) ? executionDump.tasks : [];
+            applyFlowStepIndexToDumpTasks(tasks);
+            const usageSummary = summarizeExecutionUsage(tasks);
+            const metricKey = JSON.stringify({
+                name,
+                count: tasks.length,
+                callCount: usageSummary?.callCount,
+                durationMs: usageSummary?.durationMs,
+                promptTokens: usageSummary?.prompt_tokens,
+                completionTokens: usageSummary?.completion_tokens,
+                totalTokens: usageSummary?.total_tokens,
+            });
+            if (name && name !== lastName) {
+                lastName = name;
+                emitMidsceneEvent({
+                    type: 'dump-update',
+                    platform,
+                    name,
+                    ts: Date.now(),
+                });
+            }
+            if (usageSummary && metricKey !== lastMetricKey) {
+                lastMetricKey = metricKey;
+                const flowStepIndex = flowStepIndexFromEnv() ??
+                    flowStepIndexFromDumpTasks(tasks);
+                emitMidsceneEvent({
+                    type: 'task-usage',
+                    platform,
+                    name,
+                    taskCount: tasks.length,
+                    aiCallCount: usageSummary.callCount,
+                    durationMs: usageSummary.durationMs,
+                    usage: {
+                        prompt_tokens: usageSummary.prompt_tokens,
+                        completion_tokens: usageSummary.completion_tokens,
+                        total_tokens: usageSummary.total_tokens,
+                        cached_input: usageSummary.cached_input,
+                        model_name: usageSummary.model_name,
+                        model_description: usageSummary.model_description,
+                    },
+                    ts: Date.now(),
+                    ...(flowStepIndex != null ? { flowStepIndex } : {}),
+                });
+            }
+        });
+    }
+}
+function toValidPort(port, name) {
+    const parsed = typeof port === 'number' ? port : Number(port);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new Error(`${name} 非法: ${String(port)}`);
+    }
+    return parsed;
+}
+function parseAdbDevices(output) {
+    return output
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line && !line.startsWith('List of devices attached'))
+        .map((line) => {
+        const [serial, state] = line.split(/\s+/);
+        return { serial, state };
+    })
+        .filter((row) => Boolean(row.serial));
+}
+function getRemoteDevices(adbHost, adbPort) {
+    const raw = execSync(`adb -H ${adbHost} -P ${adbPort} devices`, {
+        encoding: 'utf8',
+    });
+    return parseAdbDevices(raw);
+}
+function chooseAndroidSerial(devices, preferredSerial) {
+    if (preferredSerial) {
+        const target = devices.find((d) => d.serial === preferredSerial);
+        if (!target) {
+            throw new Error(`未找到设备: ${preferredSerial}`);
+        }
+        if (target.state !== 'device') {
+            throw new Error(`设备 ${preferredSerial} 不可用，当前状态: ${target.state}`);
+        }
+        return target.serial;
+    }
+    const firstReady = devices.find((d) => d.state === 'device');
+    if (!firstReady) {
+        throw new Error('没有可用设备（state=device）');
+    }
+    return firstReady.serial;
+}
+async function createAndroidSession(opts) {
+    const adbHost = opts.adbHost ?? '127.0.0.1';
+    const adbPort = toValidPort(opts.adbPort ?? '5037', 'ADB_PORT');
+    const preferredSerial = opts.serial;
+    const devices = getRemoteDevices(adbHost, adbPort);
+    const serial = chooseAndroidSerial(devices, preferredSerial);
+    const device = new AndroidDevice(serial, {
+        remoteAdbHost: adbHost,
+        remoteAdbPort: adbPort,
+        scrcpyConfig: {
+            enabled: true,
+        },
+    });
+    const taskCache = midsceneTaskCacheFromEnv();
+    const agent = new AndroidAgent(device, {
+        aiActContext: opts.aiActContext ?? DEFAULT_AI_CONTEXT,
+        reportFileName: opts.reportFileName,
+        replanningCycleLimit: REPLAN_CYCLE_LIMIT,
+        waitAfterAction: WAIT_AFTER_ACTION,
+        ...(opts.outputFormat ? { outputFormat: opts.outputFormat } : {}),
+        persistExecutionDump: true,
+        ...(taskCache ? { cache: taskCache } : {}),
+    });
+    attachMidsceneAgentEventHooks('android', agent);
+    await device.connect();
+    return {
+        platform: 'android',
+        device,
+        agent,
+        target: {
+            serial,
+            adbHost,
+            adbPort,
+        },
+    };
+}
+async function createIosSession(opts) {
+    const wdaHost = opts.wdaHost ?? 'localhost';
+    const wdaPort = toValidPort(opts.wdaPort ?? '8100', 'WDA_PORT');
+    const deviceId = opts.deviceId;
+    const device = new IOSDevice({
+        wdaHost,
+        wdaPort,
+        ...(deviceId ? { deviceId } : {}),
+    });
+    const taskCache = midsceneTaskCacheFromEnv();
+    const agent = new IOSAgent(device, {
+        aiActionContext: opts.aiActContext ?? DEFAULT_AI_CONTEXT,
+        reportFileName: opts.reportFileName,
+        replanningCycleLimit: REPLAN_CYCLE_LIMIT,
+        waitAfterAction: WAIT_AFTER_ACTION,
+        ...(opts.outputFormat ? { outputFormat: opts.outputFormat } : {}),
+        persistExecutionDump: true,
+        ...(taskCache ? { cache: taskCache } : {}),
+    });
+    attachMidsceneAgentEventHooks('ios', agent);
+    console.log(`[ios-target] connecting ${wdaHost}:${wdaPort}${deviceId ? ` udid=${deviceId}` : ' udid=<auto>'}`);
+    await device.connect();
+    return {
+        platform: 'ios',
+        device,
+        agent,
+        target: {
+            deviceId,
+            wdaHost,
+            wdaPort,
+        },
+    };
+}
+async function createHarmonySession(opts) {
+    const hdcPath = opts.hdcPath;
+    let deviceId = opts.deviceId;
+    const hasRemoteTconn = typeof opts.hdcTconnHost === 'string' &&
+        opts.hdcTconnHost.trim() &&
+        typeof opts.hdcTconnPort === 'number' &&
+        Number.isFinite(opts.hdcTconnPort) &&
+        opts.hdcTconnPort > 0;
+    if (hasRemoteTconn) {
+        const host = opts.hdcTconnHost.trim();
+        const port = opts.hdcTconnPort;
+        const server = { host, port };
+        const hdcBin = resolveHdcCliExecutable(hdcPath);
+        const remoteLines = await hdcListTargetsSimpleLines(hdcBin, 20000, server);
+        let resolved = pickHarmonyDeviceIdFromList(remoteLines, deviceId);
+        if (!resolved) {
+            const verbose = await hdcListTargetsVerboseStdout(hdcBin, 20000, server);
+            resolved = resolveHarmonyDeviceIdFromVerboseList(verbose, host, port, deviceId);
+        }
+        if (!resolved) {
+            throw new Error(`鸿蒙：hdc -s ${host}:${port} list targets 未解析到设备序列号。请核对：1) 本机可执行「hdc -s ${host}:${port} list targets」；2) 设备端 TCP 端口与主机「HDC 端口」一致；3) 在设备管理重新探测并选择设备。`);
+        }
+        deviceId = resolved;
+        process.env.HDC_S = `${host}:${port}`;
+        process.env.HDC_REAL = hdcBin;
+    }
+    else if (!deviceId) {
+        const devices = await getHarmonyDevices(hdcPath);
+        if (!devices.length) {
+            throw new Error('没有可用鸿蒙设备');
+        }
+        deviceId = devices[0].deviceId;
+    }
+    if (deviceId && looksLikeHdcTcpConnectKey(deviceId)) {
+        throw new Error('鸿蒙设备 ID 不能为 ip:port 连接串，请通过设备管理重新探测并选择设备（应保存 hdc 序列号），或配置远程 hdc 连接参数。');
+    }
+    const realHdc = resolveHdcCliExecutable(hdcPath);
+    const hdcPathForMidscene = hasRemoteTconn
+        ? getHarmonyHdcBridgeScriptPath()
+        : hdcPath
+            ? realHdc
+            : undefined;
+    const device = new HarmonyDevice(deviceId, {
+        ...(hdcPathForMidscene ? { hdcPath: hdcPathForMidscene } : {}),
+    });
+    const taskCache = midsceneTaskCacheFromEnv();
+    const agent = new HarmonyAgent(device, {
+        aiActContext: opts.aiActContext ?? DEFAULT_AI_CONTEXT,
+        replanningCycleLimit: REPLAN_CYCLE_LIMIT,
+        waitAfterAction: WAIT_AFTER_ACTION,
+        ...(opts.reportFileName ? { reportFileName: opts.reportFileName } : {}),
+        ...(opts.outputFormat ? { outputFormat: opts.outputFormat } : {}),
+        persistExecutionDump: true,
+        ...(taskCache ? { cache: taskCache } : {}),
+    });
+    attachMidsceneAgentEventHooks('harmony', agent);
+    await device.connect();
+    return {
+        platform: 'harmony',
+        device,
+        agent,
+        target: {
+            deviceId,
+            ...(hdcPathForMidscene ? { hdcPath: hdcPathForMidscene } : {}),
+        },
+    };
+}
+export async function createMidsceneSession(opts) {
+    if (opts.platform === 'android')
+        return createAndroidSession(opts);
+    if (opts.platform === 'ios')
+        return createIosSession(opts);
+    return createHarmonySession(opts);
+}

package/dist/utils/midscene-task-cache-env.js

@@ -0,0 +1,15 @@
+const VALID_STRATEGY = new Set(['read-only', 'read-write', 'write-only']);
+/**
+ * 从子进程环境组装 Midscene `AgentOpt.cache`。
+ * 仅当 `MIDSCENE_TASK_CACHE_ID` 非空时启用；策略非法时回退 `read-write`。
+ */
+export function midsceneTaskCacheFromEnv() {
+    const rawId = typeof process.env.MIDSCENE_TASK_CACHE_ID === 'string' ? process.env.MIDSCENE_TASK_CACHE_ID.trim() : '';
+    if (!rawId)
+        return undefined;
+    const rawStrat = typeof process.env.MIDSCENE_TASK_CACHE_STRATEGY === 'string'
+        ? process.env.MIDSCENE_TASK_CACHE_STRATEGY.trim()
+        : '';
+    const strategy = (VALID_STRATEGY.has(rawStrat) ? rawStrat : 'read-write');
+    return { id: rawId, strategy };
+}

package/dist/utils/midsceneReportConstants.js

@@ -0,0 +1,49 @@
+import { randomBytes } from "node:crypto";
+/**
+ * 供未注入任务上下文时的回退名（如本地调试、非任务入口调用 runner）。
+ * @midscene/core 会拼 `${reportFileName}.html`；不要传入已含 `.html` 的整文件名。
+ */
+export const MIDSCENE_DEFAULT_REPORT_STEM = `report-${new Date()
+    .toLocaleString("zh-CN", {
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hour12: false,
+})
+    .replace(/[^\d]/g, "-")
+    .replace(/-$/, "")}`;
+const PLATFORM_PREFIX = {
+    ANDROID: "android",
+    IOS: "ios",
+    HARMONY: "harmony",
+    WEB: "web",
+};
+/**
+ * 将 taskId 转为可安全作为 Midscene 报告名一部分的 token（无路径分隔符、控制字符）。
+ */
+export function sanitizeTaskIdForReportName(taskId) {
+    const s = String(taskId).trim() || "unknown";
+    return s
+        .replace(/[^a-zA-Z0-9._-]+/g, "_")
+        .replace(/_{2,}/g, "_")
+        .replace(/^[._-]+|[._-]+$/g, "")
+        .slice(0, 96) || "unknown";
+}
+function randomSuffix() {
+    return randomBytes(4).toString("hex");
+}
+/**
+ * 生成本次任务在 Midscene `reportFileName`（无后缀）的 stem，包含平台与 taskId 便于对账与排查。
+ * 子进程经 `MIDSCENE_FLOW_REPORT_STEM` 读取；由 Task 下发时在 runtimeEnv 中设置。
+ */
+export function buildMidsceneReportStemForTask(requiredPlatform, taskId, startedAtMs = Date.now()) {
+    const p = PLATFORM_PREFIX[requiredPlatform] ?? "app";
+    return `${p}-task-${sanitizeTaskIdForReportName(taskId)}-${startedAtMs}-${randomSuffix()}`;
+}
+/** 兼容旧 import：模块级默认 stem（无 task 上下文）。 */
+export const MIDSCENE_REPORT_FILE_STEM = MIDSCENE_DEFAULT_REPORT_STEM;
+export const MIDSCENE_REPORT_FILE_NAME = `${MIDSCENE_DEFAULT_REPORT_STEM}.html`;
+export const MIDSCENE_REPORT_GZIP_FILE_NAME = `${MIDSCENE_DEFAULT_REPORT_STEM}.html.gz`;

package/dist/utils/seedMidsceneTaskCache.js

@@ -0,0 +1,61 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { resolveMidsceneRunDir } from "../infrastructure/transport/midscenePaths.js";
+/** 与 `@midscene/shared` 的 `midscene_run/cache` 路径约定一致，避免 Agent 包未显式依赖 `@midscene/shared`。 */
+const DEFAULT_RUN_DIR = "midscene_run";
+function getMidsceneRunBaseDir(env) {
+    let basePath = resolveMidsceneRunDir(process.cwd(), env);
+    if (!existsSync(basePath)) {
+        try {
+            mkdirSync(basePath, { recursive: true });
+        }
+        catch {
+            basePath = path.join(tmpdir(), DEFAULT_RUN_DIR);
+            mkdirSync(basePath, { recursive: true });
+        }
+    }
+    return basePath;
+}
+function getMidsceneCacheDir(env) {
+    const p = path.join(getMidsceneRunBaseDir(env), "cache");
+    if (!existsSync(p))
+        mkdirSync(p, { recursive: true });
+    return p;
+}
+/**
+ * 在启动 Midscene 子进程前，将平台下发的缓存 YAML 写入 `midscene_run/cache/<id>.cache.yaml`。
+ * 环境变量：`MIDSCENE_TASK_CACHE_ID`、`MIDSCENE_TASK_CACHE_SEED_YAML_B64`（UTF-8 文本的 base64）。
+ */
+export function seedMidsceneTaskCacheFromRuntimeEnv(runtimeEnv) {
+    const id = String(runtimeEnv.MIDSCENE_TASK_CACHE_ID ?? "").trim();
+    const b64 = String(runtimeEnv.MIDSCENE_TASK_CACHE_SEED_YAML_B64 ?? "").trim();
+    if (!id || !b64)
+        return;
+    let text;
+    try {
+        text = Buffer.from(b64, "base64").toString("utf8");
+    }
+    catch {
+        return;
+    }
+    if (!text.trim())
+        return;
+    const dir = getMidsceneCacheDir(runtimeEnv);
+    const fp = path.join(dir, `${id}.cache.yaml`);
+    writeFileSync(fp, text, "utf8");
+}
+export async function readMidsceneTaskCacheFileIfExists(runtimeEnv) {
+    const id = String(runtimeEnv.MIDSCENE_TASK_CACHE_ID ?? "").trim();
+    if (!id)
+        return null;
+    const fp = path.join(getMidsceneCacheDir(runtimeEnv), `${id}.cache.yaml`);
+    if (!existsSync(fp))
+        return null;
+    const { readFile } = await import("node:fs/promises");
+    const buf = await readFile(fp);
+    return {
+        relativePath: `midscene-cache/${id}.cache.yaml`,
+        base64: buf.toString("base64"),
+    };
+}

package/dist/utils/task-runners/context/androidTaskRunnerContext.js

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

package/dist/utils/task-runners/context/harmonyTaskRunnerContext.js

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

package/dist/utils/task-runners/context/iosTaskRunnerContext.js

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

package/dist/utils/task-runners/runAndroidNativeAppTask.js

@@ -0,0 +1,29 @@
+import { createMidsceneSession } from "../midscene-device-session.js";
+import { MIDSCENE_DEFAULT_REPORT_STEM } from "../midsceneReportConstants.js";
+import { createTaskAppPackageFromEnv } from "./taskAppPackage.js";
+/**
+ * 青桔 Android 原生 App 任务：建连、启动乘客端，再执行用例业务回调。
+ */
+export async function runAndroidNativeAppTask(target, runBusiness) {
+    const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+    const stem = process.env.MIDSCENE_FLOW_REPORT_STEM?.trim() || `android-${MIDSCENE_DEFAULT_REPORT_STEM}`;
+    const outputFormat = process.env.MIDSCENE_OUTPUT_FORMAT === 'html-and-external-assets' ? 'html-and-external-assets' : 'single-html';
+    const session = await createMidsceneSession({
+        platform: 'android',
+        adbHost: target.adbHost,
+        adbPort: target.adbPort,
+        serial: target.serial,
+        reportFileName: stem,
+        outputFormat,
+    });
+    if (session.platform !== 'android') {
+        throw new Error('当前任务平台不是 Android');
+    }
+    const page = session.device;
+    const agent = session.agent;
+    console.log('[android-target]', session.target.adbHost + ':' + session.target.adbPort, session.target.serial ? 'serial=' + session.target.serial : 'serial=<auto>');
+    const { installApp, uninstallApp } = createTaskAppPackageFromEnv();
+    await runBusiness({ agent, page, sleep, installApp, uninstallApp }).finally(async () => {
+        await page.destroy();
+    });
+}

package/dist/utils/task-runners/runHarmonyNativeAppTask.js

@@ -0,0 +1,36 @@
+import { createMidsceneSession } from "../midscene-device-session.js";
+import { MIDSCENE_DEFAULT_REPORT_STEM } from "../midsceneReportConstants.js";
+import { createTaskAppPackageFromEnv } from "./taskAppPackage.js";
+/**
+ * 青桔鸿蒙原生 App 任务：远程时通过 bridge 注入 `hdc -s`，再建连并执行业务回调。
+ */
+export async function runHarmonyNativeAppTask(target, runBusiness) {
+    const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+    const stem = process.env.MIDSCENE_FLOW_REPORT_STEM?.trim() || `harmony-${MIDSCENE_DEFAULT_REPORT_STEM}`;
+    const outputFormat = process.env.MIDSCENE_OUTPUT_FORMAT === 'html-and-external-assets' ? 'html-and-external-assets' : 'single-html';
+    const session = await createMidsceneSession({
+        platform: 'harmony',
+        deviceId: target.deviceId,
+        hdcPath: target.hdcPath,
+        hdcTconnHost: target.hdcTconnHost,
+        hdcTconnPort: target.hdcTconnPort,
+        reportFileName: stem,
+        outputFormat,
+    });
+    if (session.platform !== 'harmony') {
+        throw new Error('当前任务平台不是鸿蒙');
+    }
+    const page = session.device;
+    const agent = session.agent;
+    const remoteTargetLog = typeof target.hdcTconnHost === 'string' &&
+        target.hdcTconnHost.trim() &&
+        Number.isFinite(target.hdcTconnPort) &&
+        (target.hdcTconnPort ?? 0) > 0
+        ? `${target.hdcTconnHost}:${target.hdcTconnPort}`
+        : 'local-hdc';
+    console.log('[harmony-target]', remoteTargetLog, 'deviceId=' + target.deviceId);
+    const { installApp, uninstallApp } = createTaskAppPackageFromEnv();
+    await runBusiness({ agent, page, sleep, installApp, uninstallApp }).finally(async () => {
+        await page.destroy();
+    });
+}

package/dist/utils/task-runners/runIosNativeAppTask.js

@@ -0,0 +1,30 @@
+import { createMidsceneSession } from "../midscene-device-session.js";
+import { MIDSCENE_DEFAULT_REPORT_STEM } from "../midsceneReportConstants.js";
+import { createTaskAppPackageFromEnv } from "./taskAppPackage.js";
+/**
+ * 青桔 iOS 原生 App 任务：建连、按关联应用解析的 Bundle 启动 App，再执行用例业务回调。
+ * 模版逻辑集中在此文件，便于维护；wrapIosTaskScript 只负责拼接入参与生成的用例片段。
+ */
+export async function runIosNativeAppTask(target, runBusiness) {
+    const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+    const stem = process.env.MIDSCENE_FLOW_REPORT_STEM?.trim() || `ios-${MIDSCENE_DEFAULT_REPORT_STEM}`;
+    const outputFormat = process.env.MIDSCENE_OUTPUT_FORMAT === 'html-and-external-assets' ? 'html-and-external-assets' : 'single-html';
+    const session = await createMidsceneSession({
+        platform: 'ios',
+        wdaHost: target.wdaHost,
+        wdaPort: target.wdaPort,
+        deviceId: target.deviceId,
+        reportFileName: stem,
+        outputFormat,
+    });
+    if (session.platform !== 'ios') {
+        throw new Error('当前任务平台不是 iOS');
+    }
+    const page = session.device;
+    const agent = session.agent;
+    console.log('[ios-target]', session.target.wdaHost + ':' + session.target.wdaPort, session.target.deviceId ? 'udid=' + session.target.deviceId : 'udid=<auto>');
+    const { installApp, uninstallApp } = createTaskAppPackageFromEnv();
+    await runBusiness({ agent, page, sleep, installApp, uninstallApp }).finally(async () => {
+        await page.destroy();
+    });
+}

package/dist/utils/task-runners/taskAppPackage.js

@@ -0,0 +1,20 @@
+import { installAppOnAgent, uninstallAppOnAgent } from "../../client/agentAppPackageClient.js";
+function requireTaskResourceId() {
+    const id = process.env.AGENT_RESOURCE_ID?.trim();
+    if (!id) {
+        throw new Error("installApp / uninstallApp requires AGENT_RESOURCE_ID (injected by Agent when dispatching a task — do not call from bare scripts)");
+    }
+    return id;
+}
+export function createTaskAppPackageFromEnv() {
+    return {
+        installApp: async (appRef) => {
+            const resourceId = requireTaskResourceId();
+            await installAppOnAgent({ resourceId, appRef });
+        },
+        uninstallApp: async (bundleId) => {
+            const resourceId = requireTaskResourceId();
+            await uninstallAppOnAgent({ resourceId, bundleId });
+        },
+    };
+}

package/dist/utils/wrapper/resolveTaskRunnerImport.js

@@ -0,0 +1,11 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+export function resolveTaskRunnerImportUrl(runnerName) {
+    const runtimeRoot = process.env.AGENT_RUNTIME_ROOT?.trim() || process.cwd();
+    const distRunner = path.join(runtimeRoot, 'dist/utils/task-runners', `${runnerName}.js`);
+    if (existsSync(distRunner)) {
+        return pathToFileURL(distRunner).href;
+    }
+    return pathToFileURL(path.join(process.cwd(), 'src/utils/task-runners', `${runnerName}.ts`)).href;
+}

package/dist/utils/wrapper/wrapAndroidTaskScript.js

@@ -0,0 +1,38 @@
+import { resolveTaskRunnerImportUrl } from './resolveTaskRunnerImport.js';
+function targetToRunnerArgs(target) {
+    return {
+        adbHost: target.adbHost,
+        adbPort: target.adbPort,
+        serial: target.serial,
+    };
+}
+/**
+ * Android 任务执行：生成薄层脚本，实际模版见 {@link runAndroidNativeAppTask}。
+ */
+export function wrapAndroidTaskScript(userScript, target) {
+    const body = userScript.trim();
+    const indented = body
+        ? body.split(/\r?\n/).map((line) => `      ${line}`).join('\n')
+        : '      // （用例脚本为空）';
+    const t = targetToRunnerArgs(target);
+    const adbHostLiteral = JSON.stringify(t.adbHost);
+    const adbPortLiteral = JSON.stringify(t.adbPort);
+    const serialLiteral = typeof t.serial === 'string' && t.serial.trim()
+        ? JSON.stringify(t.serial.trim())
+        : 'undefined';
+    const runnerImportUrlLiteral = JSON.stringify(resolveTaskRunnerImportUrl('runAndroidNativeAppTask'));
+    return `import { runAndroidNativeAppTask } from ${runnerImportUrlLiteral};
+
+Promise.resolve(
+  runAndroidNativeAppTask(
+    { adbHost: ${adbHostLiteral}, adbPort: ${adbPortLiteral}, serial: ${serialLiteral} },
+    async ({ agent, page, sleep, installApp, uninstallApp }) => {
+${indented}
+    },
+  ),
+).catch((e) => {
+  console.error(e);
+  process.exit(1);
+});
+`;
+}