preflite 1.0.1

package/dist/infrastructure/airtest/AirtestRuntime.js

@@ -0,0 +1,168 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { mkdtemp, mkdir, readFile, writeFile, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { ArtifactType, PlatformType } from "../../shared-kernel/enums/index.js";
+import { getMidsceneReportRootDir, resolveTaskReportFilePaths } from "../transport/midscenePaths.js";
+import { zipDirectoryToFile } from "../midscene/zipReportDir.js";
+const execFileAsync = promisify(execFile);
+function extractDeviceToken(resourceId) {
+    const idx = resourceId.indexOf(":");
+    return idx >= 0 ? resourceId.slice(idx + 1) : resourceId;
+}
+function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function requirePositivePort(value, name) {
+    const n = Number(value);
+    if (!Number.isFinite(n) || n <= 0)
+        throw new Error(`${name} is required`);
+    return Math.floor(n);
+}
+export function buildAirtestDeviceUri(platform, resourceId, options) {
+    const token = extractDeviceToken(String(resourceId));
+    if (platform === PlatformType.ANDROID) {
+        return `Android://${options.androidAdbHost ?? "127.0.0.1"}:${options.androidAdbPort ?? 5037}/${token}`;
+    }
+    if (platform === PlatformType.IOS) {
+        const port = requirePositivePort(options.iosWdaPort, "iosWdaPort");
+        const mjpeg = requirePositivePort(options.iosMjpegPort ?? port + 1000, "iosMjpegPort");
+        const host = options.iosWdaHost ?? "127.0.0.1";
+        return `iOS:///http://${host}:${port}/?mjpeg_port=${mjpeg}&udid=${encodeURIComponent(token)}`;
+    }
+    if (platform === PlatformType.HARMONY) {
+        const params = new URLSearchParams();
+        if (options.harmonyHdcPath)
+            params.set("hdc_path", options.harmonyHdcPath);
+        const q = params.toString();
+        return `Harmony:///${encodeURIComponent(token)}${q ? `?${q}` : ""}`;
+    }
+    throw new Error(`unsupported Airtest platform: ${platform}`);
+}
+function assertSafeZipEntries(entries) {
+    for (const entry of entries) {
+        const clean = entry.replaceAll("\\", "/");
+        if (!clean || clean.startsWith("/") || clean.includes("\0") || clean.split("/").includes("..")) {
+            throw new Error(`unsafe airtest zip entry: ${entry}`);
+        }
+    }
+}
+async function unzipSafe(zipPath, targetDir) {
+    const listing = await execFileAsync("unzip", ["-Z1", zipPath], { maxBuffer: 2 * 1024 * 1024 });
+    assertSafeZipEntries(String(listing.stdout).split(/\r?\n/).filter(Boolean));
+    await execFileAsync("unzip", ["-qq", "-o", zipPath, "-d", targetDir], { maxBuffer: 2 * 1024 * 1024 });
+}
+export class AirtestRuntime {
+    commandRunner;
+    options;
+    constructor(commandRunner, options) {
+        this.commandRunner = commandRunner;
+        this.options = options;
+    }
+    async execute(task, resourceId, signal, context) {
+        if (!task.airtest?.bundleBase64?.trim() || !task.airtest.entryDir?.trim()) {
+            throw new Error("airtest bundle and entryDir are required");
+        }
+        const baseDir = await mkdtemp(path.join(tmpdir(), "airtest-run-"));
+        const zipPath = path.join(baseDir, task.airtest.archiveName || "airtest.zip");
+        const scriptRoot = path.join(baseDir, "script");
+        await mkdir(scriptRoot, { recursive: true });
+        await writeFile(zipPath, Buffer.from(task.airtest.bundleBase64, "base64"));
+        await unzipSafe(zipPath, scriptRoot);
+        const entryDir = path.resolve(scriptRoot, task.airtest.entryDir);
+        if (!entryDir.startsWith(path.resolve(scriptRoot) + path.sep))
+            throw new Error("invalid airtest entryDir");
+        const entryBase = path.basename(entryDir, ".air");
+        await stat(path.join(entryDir, `${entryBase}.py`));
+        const env = { ...process.env, ...(context?.runtimeEnv ?? {}) };
+        const reportStem = String(env.MIDSCENE_FLOW_REPORT_STEM ?? `airtest-${Date.now()}`).trim();
+        const outputFormat = env.MIDSCENE_OUTPUT_FORMAT === "html-and-external-assets" ? "html-and-external-assets" : "single-html";
+        const reportRoot = getMidsceneReportRootDir(process.cwd(), { ...process.env, ...env });
+        const reportPaths = resolveTaskReportFilePaths(reportRoot, reportStem, outputFormat);
+        const reportDir = reportPaths.bundleDir ?? path.dirname(reportPaths.reportHtmlPath);
+        const logDir = path.join(baseDir, "log");
+        await mkdir(logDir, { recursive: true });
+        await mkdir(reportDir, { recursive: true });
+        const python = env.AIRTEST_PYTHON?.trim() || "python3";
+        const pythonPath = env.AIRTEST_REPO_PATH?.trim();
+        const childEnv = pythonPath
+            ? { ...env, PYTHONPATH: [pythonPath, env.PYTHONPATH].filter(Boolean).join(path.delimiter) }
+            : env;
+        const deviceUri = buildAirtestDeviceUri(task.requiredPlatform, resourceId, {
+            androidAdbHost: env.MIDSCENE_ANDROID_ADB_HOST ?? this.options.androidAdbHost,
+            androidAdbPort: Number(env.MIDSCENE_ANDROID_ADB_PORT ?? this.options.androidAdbPort ?? 5037),
+            iosWdaHost: env.MIDSCENE_IOS_WDA_HOST ?? this.options.iosWdaHost,
+            iosWdaPort: Number(env.MIDSCENE_IOS_WDA_PORT ?? env.IOS_WDA_PORT),
+            iosMjpegPort: Number(env.MIDSCENE_IOS_WDA_MJPEG_PORT ?? env.IOS_WDA_MJPEG_PORT),
+            harmonyHdcPath: env.MIDSCENE_HARMONY_HDC_PATH ?? this.options.harmonyHdcPath,
+        });
+        const runCommand = [
+            shellQuote(python),
+            "-m airtest run",
+            shellQuote(entryDir),
+            "--device",
+            shellQuote(deviceUri),
+            "--log",
+            shellQuote(logDir),
+        ].join(" ");
+        const startedAt = Date.now();
+        const run = await this.commandRunner.run(runCommand, this.options.runCommandTimeoutMs, signal, {
+            env: childEnv,
+            onStdoutChunk: context?.onLogChunk ? (t) => context.onLogChunk(t, "stdout") : undefined,
+            onStderrChunk: context?.onLogChunk ? (t) => context.onLogChunk(t, "stderr") : undefined,
+        });
+        const reportCommand = [
+            shellQuote(python),
+            "-m airtest report",
+            shellQuote(entryDir),
+            "--log_root",
+            shellQuote(logDir),
+            "--outfile",
+            shellQuote(reportPaths.reportHtmlPath),
+            ...(reportPaths.bundleDir ? ["--export", shellQuote(reportPaths.bundleDir)] : []),
+        ].join(" ");
+        const report = await this.commandRunner.run(reportCommand, this.options.runCommandTimeoutMs, signal, {
+            env: childEnv,
+            onStdoutChunk: context?.onLogChunk ? (t) => context.onLogChunk(t, "stdout") : undefined,
+            onStderrChunk: context?.onLogChunk ? (t) => context.onLogChunk(t, "stderr") : undefined,
+        });
+        const endedAt = Date.now();
+        const runtimeLog = path.join(baseDir, "runtime.log");
+        const traceFile = path.join(baseDir, "runtime-trace.json");
+        await writeFile(runtimeLog, [`command: ${runCommand}`, run.stdout, run.stderr, `report: ${reportCommand}`, report.stdout, report.stderr].join("\n"));
+        await writeFile(traceFile, JSON.stringify({ startedAt, endedAt, durationMs: endedAt - startedAt, exitCode: run.exitCode, ok: run.ok && report.ok }, null, 2));
+        const artifacts = [
+            { type: ArtifactType.LOG, uri: `file://${runtimeLog}` },
+            { type: ArtifactType.TRACE, uri: `file://${traceFile}` },
+            { type: ArtifactType.REPORT, uri: `file://${reportPaths.reportHtmlPath}` },
+        ];
+        let reportInfo;
+        if (run.ok && report.ok) {
+            const html = await readFile(reportPaths.reportHtmlPath, "utf8");
+            const reportBundleZipPath = reportPaths.bundleDir ? await zipDirectoryToFile(reportPaths.bundleDir, reportStem) : undefined;
+            reportInfo = {
+                reportHtmlPath: reportPaths.reportHtmlPath,
+                reportName: reportPaths.reportName,
+                reportFormat: outputFormat,
+                reportBundleDir: reportPaths.bundleDir,
+                reportBundleZipPath,
+            };
+            context?.onReportProgress?.({
+                reportHtml: html,
+                reportFormat: outputFormat,
+                partial: false,
+                reportName: reportPaths.reportName,
+                reportBundleZipUri: reportBundleZipPath ? `file://${reportBundleZipPath}` : undefined,
+            });
+            if (reportBundleZipPath)
+                artifacts.push({ type: ArtifactType.REPORT, uri: `file://${reportBundleZipPath}` });
+        }
+        return {
+            ok: run.ok && report.ok,
+            message: run.ok && report.ok ? "airtest execution success" : run.stderr || report.stderr || "airtest execution failed",
+            artifacts,
+            reportInfo,
+        };
+    }
+}

package/dist/infrastructure/app-package/AppPackageUrlCache.js

@@ -0,0 +1,191 @@
+import { createHash } from "node:crypto";
+import { access, mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { constants as FsConstants } from "node:fs";
+import { PlatformType } from "../../shared-kernel/enums/index.js";
+const INDEX_NAME = "url-cache-index.json";
+const CACHE_SUBDIR = "url-cache";
+function isProbablyHttpUrl(ref) {
+    return /^https?:\/\//i.test(ref.trim());
+}
+function normalizePackageUrl(raw) {
+    const u = new URL(raw.trim());
+    u.hash = "";
+    return u.toString();
+}
+function urlCacheKey(normalizedUrl, platform) {
+    return createHash("sha256").update(`${normalizedUrl}\n${platform}`, "utf8").digest("hex");
+}
+function extensionForPlatform(platform) {
+    switch (platform) {
+        case PlatformType.ANDROID:
+            return ".apk";
+        case PlatformType.IOS:
+            return ".ipa";
+        case PlatformType.HARMONY:
+            return ".hap";
+        default:
+            return ".pkg";
+    }
+}
+function guessExtensionFromUrl(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 m[0].toLowerCase();
+    }
+    catch {
+        /* ignore */
+    }
+    return extensionForPlatform(platform);
+}
+/**
+ * 按 **规范化后的 http(s) 安装链接 + 目标平台** 主键复用本地包：命中则不再下载，直接用于安装；索引持久化在缓存目录。
+ */
+export class AppPackageUrlCache {
+    cacheDir;
+    indexPath;
+    agentId;
+    onChanged;
+    fetchImpl;
+    index = { version: 1, entries: {} };
+    tails = new Map();
+    constructor(opts) {
+        this.agentId = opts.agentId;
+        this.onChanged = opts.onChanged;
+        this.fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+        const base = (opts.downloadDir?.trim() || path.join(tmpdir(), "agent-app-packages")).replace(/\/+$/, "");
+        this.cacheDir = path.join(base, CACHE_SUBDIR);
+        this.indexPath = path.join(this.cacheDir, INDEX_NAME);
+    }
+    getCacheDir() {
+        return this.cacheDir;
+    }
+    listItems() {
+        return Object.values(this.index.entries).map((e) => ({
+            url: e.url,
+            platform: e.platform,
+            localPath: path.join(this.cacheDir, e.fileName),
+            byteSize: e.byteSize,
+            downloadedAt: e.downloadedAt,
+        }));
+    }
+    async bootstrap() {
+        await mkdir(this.cacheDir, { recursive: true });
+        await this.loadIndex();
+        const prunedEmitted = await this.pruneMissingFiles();
+        if (this.listItems().length > 0 && !prunedEmitted) {
+            await this.fireChanged();
+        }
+    }
+    async resolveHttpToLocalPackage(rawUrl, platform) {
+        const normalized = normalizePackageUrl(rawUrl.trim());
+        const key = urlCacheKey(normalized, platform);
+        const prev = this.tails.get(key) ?? Promise.resolve();
+        const mine = prev.then(() => this.downloadOrUseCached(normalized, platform, key));
+        this.tails.set(key, mine);
+        try {
+            return await mine;
+        }
+        finally {
+            if (this.tails.get(key) === mine) {
+                this.tails.delete(key);
+            }
+        }
+    }
+    async downloadOrUseCached(normalizedUrl, platform, indexKey) {
+        await mkdir(this.cacheDir, { recursive: true });
+        await this.loadIndex();
+        const existing = this.index.entries[indexKey];
+        if (existing) {
+            const abs = path.join(this.cacheDir, existing.fileName);
+            try {
+                await access(abs, FsConstants.R_OK);
+                const noop = async () => { };
+                return { localPath: abs, cleanupTemp: noop };
+            }
+            catch {
+                delete this.index.entries[indexKey];
+                await this.saveIndex();
+            }
+        }
+        const ext = guessExtensionFromUrl(normalizedUrl, platform);
+        const fileName = `${indexKey}${ext}`;
+        const destPart = path.join(this.cacheDir, `${fileName}.part`);
+        const destFinal = path.join(this.cacheDir, fileName);
+        const res = await this.fetchImpl(normalizedUrl, { redirect: "follow" });
+        if (!res.ok) {
+            throw new Error(`download failed: HTTP ${res.status} ${res.statusText}`);
+        }
+        const buf = Buffer.from(await res.arrayBuffer());
+        await writeFile(destPart, buf);
+        await rename(destPart, destFinal);
+        const st = await stat(destFinal);
+        const downloadedAt = new Date().toISOString();
+        this.index.entries[indexKey] = {
+            url: normalizedUrl,
+            platform,
+            fileName,
+            byteSize: st.size,
+            downloadedAt,
+        };
+        await this.saveIndex();
+        await this.fireChanged();
+        const noop = async () => { };
+        return { localPath: destFinal, cleanupTemp: noop };
+    }
+    async loadIndex() {
+        try {
+            const raw = await readFile(this.indexPath, "utf8");
+            const parsed = JSON.parse(raw);
+            if (parsed?.version === 1 && parsed.entries && typeof parsed.entries === "object") {
+                this.index = parsed;
+            }
+        }
+        catch {
+            this.index = { version: 1, entries: {} };
+        }
+    }
+    async saveIndex() {
+        const tmp = `${this.indexPath}.${process.pid}.tmp`;
+        await writeFile(tmp, JSON.stringify(this.index, null, 2), "utf8");
+        await rename(tmp, this.indexPath);
+    }
+    async pruneMissingFiles() {
+        let changed = false;
+        for (const [k, e] of Object.entries(this.index.entries)) {
+            const abs = path.join(this.cacheDir, e.fileName);
+            try {
+                await access(abs, FsConstants.R_OK);
+            }
+            catch {
+                delete this.index.entries[k];
+                changed = true;
+            }
+        }
+        if (changed) {
+            await this.saveIndex();
+            await this.fireChanged();
+            return true;
+        }
+        return false;
+    }
+    /** 供 HTTP 查询：从磁盘刷新索引并清理幽灵项 */
+    async snapshotForHttp() {
+        await this.loadIndex();
+        await this.pruneMissingFiles();
+        return { agentId: this.agentId, items: this.listItems() };
+    }
+    async fireChanged() {
+        if (!this.onChanged)
+            return;
+        await this.onChanged({ agentId: this.agentId, items: this.listItems() });
+    }
+    /** 安装入口：http(s) 走缓存，其它仍由调用方用原有 resolve 逻辑 */
+    static isHttpRef(appRef) {
+        return isProbablyHttpUrl(appRef);
+    }
+}

package/dist/infrastructure/app-package/appPackageDownloadDir.js

@@ -0,0 +1,13 @@
+import path from "node:path";
+export function resolveAppPackageDownloadDir(rawDownloadDir, env = process.env, cwd = process.cwd()) {
+    const trimmed = rawDownloadDir?.trim();
+    if (!trimmed)
+        return undefined;
+    if (path.isAbsolute(trimmed))
+        return trimmed;
+    const agentHome = env.AGENT_HOME?.trim();
+    if (agentHome) {
+        return path.resolve(agentHome, trimmed);
+    }
+    return path.resolve(cwd, trimmed);
+}

package/dist/infrastructure/bootstrap/BuildRuntimeContext.js

@@ -0,0 +1,88 @@
+import { AdapterRegistry } from "../adapters/AdapterRegistry.js";
+import { AndroidResourceAdapter } from "../adapters/android/AndroidResourceAdapter.js";
+import { buildAndroidAdbCliPrefix, buildHarmonyHdcShellPrefix } from "../adapters/deviceDetailsProbe.js";
+import { HarmonyResourceAdapter } from "../adapters/harmony/HarmonyResourceAdapter.js";
+import { IOSResourceAdapter } from "../adapters/ios/IOSResourceAdapter.js";
+import { ShellCommandExecutor, ShellSnapshotProvider } from "../adapters/real/ShellCommandAndSnapshot.js";
+import { MidsceneRuntimeReal } from "../midscene/MidsceneRuntimeReal.js";
+import { NodeCommandRunner } from "../system/CommandRunner.js";
+import path from "node:path";
+export function buildRuntimeContext(env) {
+    const repoRoot = process.cwd();
+    const commandRunner = new NodeCommandRunner();
+    const harmonyDiscoveryCommand = env.HARMONY_DISCOVERY_COMMAND ?? "hdc list targets";
+    const iosDiscoveryCommand = env.IOS_DISCOVERY_COMMAND ?? "xcrun xctrace list devices";
+    const debugCommandTemplate = env.DEBUG_COMMAND_TEMPLATE ?? "echo '{command}'";
+    const snapshotCommandTemplate = env.SNAPSHOT_COMMAND_TEMPLATE ?? "echo 'file:///tmp/automation-agent-snapshot-{resourceId}.png'";
+    const defaultMidsceneRunner = path.join(repoRoot, "scripts", "run-midscene-task.sh");
+    const midsceneRunCommand = env.MIDSCENE_RUN_COMMAND ?? `bash "${defaultMidsceneRunner}" "{scriptFile}"`;
+    const midsceneRunTimeoutMs = Number(env.MIDSCENE_RUN_TIMEOUT_MS ?? "300000");
+    const iosWdaPortRangeStart = Number(env.IOS_WDA_PORT_RANGE_START ?? "8200");
+    const iosWdaPortRangeEnd = Number(env.IOS_WDA_PORT_RANGE_END ?? "8399");
+    const iosWdaHealthUrlTemplate = env.IOS_WDA_HEALTH_URL_TEMPLATE ?? "http://127.0.0.1:{wdaPort}/status";
+    const iosWdaHost = env.MIDSCENE_IOS_WDA_HOST?.trim() || env.IOS_WDA_HOST?.trim() || "127.0.0.1";
+    const defaultWdaStartScript = path.join(repoRoot, "scripts", "start-ios-wda.sh");
+    const iosWdaStartCommandTemplate = env.IOS_WDA_START_COMMAND_TEMPLATE?.trim() || `bash "${defaultWdaStartScript}" "{deviceId}" "{wdaPort}"`;
+    const iosWdaPortMapFilePath = env.IOS_WDA_PORT_MAP_FILE_PATH?.trim() || path.join(repoRoot, ".wda-agent-state", "wda-port-map.json");
+    const iosWdaStartupTimeoutMs = Number(env.IOS_WDA_STARTUP_TIMEOUT_MS ?? "120000");
+    const iosWdaStartupRetry = Number(env.IOS_WDA_STARTUP_RETRY ?? "2");
+    const androidAdbHost = env.MIDSCENE_ANDROID_ADB_HOST?.trim() || env.AGENT_ANDROID_ADB_HOST?.trim() || "127.0.0.1";
+    const androidAdbPort = Number(env.MIDSCENE_ANDROID_ADB_PORT ?? env.AGENT_ANDROID_ADB_PORT ?? "5037");
+    const androidDiscoveryCommand = env.ANDROID_DISCOVERY_COMMAND?.trim() ||
+        `${buildAndroidAdbCliPrefix(androidAdbHost, androidAdbPort)} devices`;
+    const harmonyHdcPath = env.MIDSCENE_HARMONY_HDC_PATH?.trim() || env.AGENT_HARMONY_HDC_PATH?.trim() || undefined;
+    const harmonyHdcHost = env.MIDSCENE_HARMONY_HDC_HOST?.trim() || env.AGENT_HARMONY_HDC_HOST?.trim() || undefined;
+    const harmonyHdcPortRaw = Number(env.MIDSCENE_HARMONY_HDC_PORT ?? env.AGENT_HARMONY_HDC_PORT ?? "");
+    const harmonyHdcPortResolved = Number.isFinite(harmonyHdcPortRaw) && harmonyHdcPortRaw > 0 ? Math.floor(harmonyHdcPortRaw) : undefined;
+    const iosWdaExplicitRaw = Number(env.MIDSCENE_IOS_WDA_PORT ?? env.IOS_WDA_PORT ?? "");
+    const iosWdaExplicitResolved = Number.isFinite(iosWdaExplicitRaw) && iosWdaExplicitRaw > 0 ? Math.floor(iosWdaExplicitRaw) : undefined;
+    const iosWdaMjpegPortRaw = env.MIDSCENE_IOS_WDA_MJPEG_PORT?.trim() || env.IOS_WDA_MJPEG_PORT?.trim() || "";
+    const iosWdaMjpegPortParsed = Number(iosWdaMjpegPortRaw);
+    const iosWdaMjpegPortResolved = iosWdaMjpegPortRaw !== "" && Number.isFinite(iosWdaMjpegPortParsed) && iosWdaMjpegPortParsed > 0
+        ? Math.floor(iosWdaMjpegPortParsed)
+        : undefined;
+    const harmonyHdcShellPrefix = buildHarmonyHdcShellPrefix(harmonyHdcPath, harmonyHdcHost, harmonyHdcPortResolved);
+    const resourceAdapters = [
+        new HarmonyResourceAdapter(commandRunner, harmonyDiscoveryCommand, harmonyHdcShellPrefix),
+        new AndroidResourceAdapter(commandRunner, androidDiscoveryCommand, androidAdbHost, androidAdbPort),
+        new IOSResourceAdapter(commandRunner, iosDiscoveryCommand),
+    ];
+    const adapterRegistry = new AdapterRegistry(resourceAdapters, new ShellCommandExecutor(commandRunner, debugCommandTemplate), new ShellSnapshotProvider(commandRunner, snapshotCommandTemplate));
+    const midsceneRuntime = new MidsceneRuntimeReal(commandRunner, midsceneRunCommand, {
+        runCommandTimeoutMs: Number.isFinite(midsceneRunTimeoutMs) && midsceneRunTimeoutMs > 0 ? Math.floor(midsceneRunTimeoutMs) : 120_000,
+        iosWdaPortRangeStart: Number.isFinite(iosWdaPortRangeStart) && iosWdaPortRangeStart > 0 ? Math.floor(iosWdaPortRangeStart) : 8200,
+        iosWdaPortRangeEnd: Number.isFinite(iosWdaPortRangeEnd) && iosWdaPortRangeEnd > 0 ? Math.floor(iosWdaPortRangeEnd) : 8399,
+        iosWdaHealthUrlTemplate,
+        iosWdaHost,
+        iosWdaStartCommandTemplate,
+        iosWdaPortMapFilePath,
+        iosWdaStartupTimeoutMs: Number.isFinite(iosWdaStartupTimeoutMs) && iosWdaStartupTimeoutMs > 0
+            ? Math.floor(iosWdaStartupTimeoutMs)
+            : 120_000,
+        iosWdaStartupRetry: Number.isFinite(iosWdaStartupRetry) && iosWdaStartupRetry > 0 ? Math.floor(iosWdaStartupRetry) : 2,
+        androidAdbHost,
+        androidAdbPort: Number.isFinite(androidAdbPort) && androidAdbPort > 0 ? Math.floor(androidAdbPort) : 5037,
+        harmonyHdcPath,
+        harmonyHdcHost,
+        harmonyHdcPort: harmonyHdcPortResolved,
+    });
+    return {
+        adapterRegistry,
+        midsceneRuntime,
+        commandRunner,
+        selectedMode: "REAL",
+        harmonyDebugHdc: {
+            path: harmonyHdcPath,
+            host: harmonyHdcHost,
+            port: harmonyHdcPortResolved,
+        },
+        iosDebugWda: {
+            host: iosWdaHost,
+            portMapFilePath: iosWdaPortMapFilePath,
+            portRangeStart: Number.isFinite(iosWdaPortRangeStart) && iosWdaPortRangeStart > 0 ? Math.floor(iosWdaPortRangeStart) : 8200,
+            portRangeEnd: Number.isFinite(iosWdaPortRangeEnd) && iosWdaPortRangeEnd > 0 ? Math.floor(iosWdaPortRangeEnd) : 8399,
+            explicitWdaPort: iosWdaExplicitResolved,
+            ...(iosWdaMjpegPortResolved != null ? { mjpegPort: iosWdaMjpegPortResolved } : {}),
+        },
+    };
+}

package/dist/infrastructure/cache/DirCapacityWatchdog.js

@@ -0,0 +1,150 @@
+import { readdir, rm, stat } from "node:fs/promises";
+import path from "node:path";
+async function entryRecursiveBytes(absPath) {
+    const st = await stat(absPath);
+    if (st.isFile() || st.isSymbolicLink()) {
+        return st.isFile() ? st.size : 0;
+    }
+    if (!st.isDirectory()) {
+        return 0;
+    }
+    let sum = 0;
+    const dirents = await readdir(absPath, { withFileTypes: true });
+    for (const d of dirents) {
+        const child = path.join(absPath, d.name);
+        if (d.isDirectory()) {
+            sum += await entryRecursiveBytes(child);
+        }
+        else if (d.isFile()) {
+            try {
+                sum += (await stat(child)).size;
+            }
+            catch {
+                /* 并发删除等 */
+            }
+        }
+    }
+    return sum;
+}
+async function listChildStats(rootResolved) {
+    let names;
+    try {
+        names = await readdir(rootResolved);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of names) {
+        const absPath = path.join(rootResolved, name);
+        let st;
+        try {
+            st = await stat(absPath);
+        }
+        catch {
+            continue;
+        }
+        const bytes = st.isDirectory() || st.isFile() ? await entryRecursiveBytes(absPath) : 0;
+        const birth = st.birthtimeMs > 0 ? st.birthtimeMs : st.mtimeMs;
+        const sortKey = Math.min(st.mtimeMs, birth);
+        out.push({ absPath, bytes, sortKey });
+    }
+    return out;
+}
+function totalBytes(children) {
+    return children.reduce((a, c) => a + c.bytes, 0);
+}
+/**
+ * 在单个根目录下，将其**直接子项**视为可删除单元；总占用超过 `maxBytes` 时按 `sortKey`（更偏创建/修改时间中较早者）从小到大删除，直到不超限或无可删项。
+ * 不递归挑选「子树内部的单个文件」，避免拆坏 Midscene 报告目录结构。
+ */
+export async function trimDirectoryToMaxBytes(rootDir, maxBytes) {
+    const deletedPaths = [];
+    let freedBytes = 0;
+    const rootResolved = path.resolve(rootDir);
+    if (!Number.isFinite(maxBytes) || maxBytes <= 0) {
+        const children = await listChildStats(rootResolved);
+        return { deletedPaths, freedBytes, finalTotalBytes: totalBytes(children) };
+    }
+    let guard = 0;
+    while (guard < 50_000) {
+        guard += 1;
+        const children = await listChildStats(rootResolved);
+        const sum = totalBytes(children);
+        if (sum <= maxBytes) {
+            return { deletedPaths, freedBytes, finalTotalBytes: sum };
+        }
+        if (children.length === 0) {
+            return { deletedPaths, freedBytes, finalTotalBytes: sum };
+        }
+        children.sort((a, b) => a.sortKey - b.sortKey || a.absPath.localeCompare(b.absPath));
+        const victim = children[0];
+        if (!victim) {
+            return { deletedPaths, freedBytes, finalTotalBytes: sum };
+        }
+        try {
+            await rm(victim.absPath, { recursive: true, force: true });
+            deletedPaths.push(victim.absPath);
+            freedBytes += victim.bytes;
+        }
+        catch {
+            /* 可能正在被写入；下一轮再试 */
+        }
+    }
+    const children = await listChildStats(rootResolved);
+    return { deletedPaths, freedBytes, finalTotalBytes: totalBytes(children) };
+}
+/**
+ * 定时按容量裁剪多个根目录（各自独立上限均为 `maxBytes`）。
+ * @returns `stop` 清除定时器；不会等待进行中的 tick。
+ */
+export function startDirCapacityWatchdog(options) {
+    const roots = [...new Set(options.roots.map((r) => path.resolve(r.trim())).filter(Boolean))];
+    const maxBytes = Math.floor(options.maxBytes);
+    const intervalMs = Math.floor(options.intervalMs);
+    const log = options.log;
+    const tick = async () => {
+        for (const root of roots) {
+            try {
+                const r = await trimDirectoryToMaxBytes(root, maxBytes);
+                if (r.deletedPaths.length > 0) {
+                    log?.(`[CacheWatchdog] root=${root} 删除 ${r.deletedPaths.length} 项，释放约 ${r.freedBytes} 字节，剩余约 ${r.finalTotalBytes} / ${maxBytes}`);
+                }
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                log?.(`[CacheWatchdog] root=${root} 清理失败: ${msg}`);
+            }
+        }
+    };
+    const id = setInterval(() => {
+        void tick();
+    }, intervalMs);
+    if (typeof id.unref === "function") {
+        id.unref();
+    }
+    return {
+        stop: () => {
+            clearInterval(id);
+        },
+    };
+}
+/** 解析如 `1073741824`、`512m`、`2G`（二进制前缀）为正整数字节；无法解析时返回 0 */
+export function parsePositiveByteCount(raw) {
+    if (raw == null)
+        return 0;
+    const compact = raw.trim().replace(/\s+/g, "");
+    if (!compact)
+        return 0;
+    const m = /^(\d+(?:\.\d+)?)([kmgt])?b?$/i.exec(compact);
+    if (!m) {
+        const n = Number(compact);
+        return Number.isFinite(n) && n > 0 ? Math.floor(n) : 0;
+    }
+    const base = Number(m[1]);
+    if (!Number.isFinite(base) || base <= 0)
+        return 0;
+    const u = (m[2] ?? "").toLowerCase();
+    const mul = u === "k" ? 1024 : u === "m" ? 1024 ** 2 : u === "g" ? 1024 ** 3 : u === "t" ? 1024 ** 4 : 1;
+    return Math.floor(base * mul);
+}