@skillbuilder/minitool-e2e 0.0.0-beta-20261027053041051

package/lib/session.js

@@ -0,0 +1,592 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MinitoolE2ESession = void 0;
+exports.readDistDir = readDistDir;
+/**
+ * 一次 open→操作→close 的生命周期，持有 Chromium + 宿主页 + 静态服务。
+ * 所有对模拟器的调用都经 `page.evaluate` 打到宿主页的 `window.__MINITOOL_E2E__`，
+ * Node 侧不持有任何浏览器内对象。方法分两组（工具名也按这个分）：通用的任何形态都成立，
+ * 游戏专属的全部经 `window.__GAME_TEST__`，只有 game_2d / game_3d 模板才挂那个桥。
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const browser_1 = require("./browser");
+const host_server_1 = require("./host-server");
+const upload_1 = require("./upload");
+/** 按扩展名判定是否走 base64 中转（文本文件直传，省一次编解码） */
+const BINARY_EXTENSIONS = new Set([
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".webp",
+    ".gif",
+    ".ico",
+    ".bmp",
+    ".woff",
+    ".woff2",
+    ".ttf",
+    ".otf",
+    ".eot",
+    ".mp3",
+    ".wav",
+    ".ogg",
+    ".m4a",
+    ".mp4",
+    ".webm",
+    ".glb",
+    ".gltf",
+    ".bin",
+    ".wasm",
+    ".zip",
+]);
+function notImplemented(capability, message, blockedBy) {
+    // 打一行日志：沙箱里能据此看到模型确实调了这个还没实现的能力，
+    // 从而判断该优先做哪一个（比凭猜测排期靠谱）。
+    console.warn(`[minitool-e2e] 通用 e2e 能力 ${capability} 尚未实现，已如实返回 not_implemented`);
+    return { status: "not_implemented", capability, message, ...(blockedBy ? { blockedBy } : {}) };
+}
+class MinitoolE2ESession {
+    browser;
+    page;
+    host;
+    viewport;
+    constructor(browser, page, host, viewport) {
+        this.browser = browser;
+        this.page = page;
+        this.host = host;
+        this.viewport = viewport;
+    }
+    static async create(opts = {}) {
+        const viewport = opts.viewport ?? { width: 390, height: 844 };
+        const host = await (0, host_server_1.startHostServer)({ viewport });
+        let browser;
+        try {
+            browser = await (0, browser_1.launchChromium)(opts);
+            const context = await browser.newContext({
+                // 画布留出边距，避免模拟器容器贴边导致 devicePixelRatio 换算出现半像素
+                viewport: { width: viewport.width + 40, height: viewport.height + 56 },
+                deviceScaleFactor: 2,
+            });
+            const page = await context.newPage();
+            await page.goto(`${host.baseUrl}/`, { waitUntil: "load" });
+            await page.waitForFunction(() => globalThis.__MINITOOL_E2E_READY__ === true, undefined, { timeout: opts.readyTimeoutMs ?? 30_000 });
+            return new MinitoolE2ESession(browser, page, host, viewport);
+        }
+        catch (err) {
+            await browser?.close().catch(() => undefined);
+            await host.close().catch(() => undefined);
+            throw err;
+        }
+    }
+    /**
+     * 把产物目录读进内存交给模拟器挂载。刻意**不等游戏桥**（那段轮询在 `gameAttach()`）：
+     * 等桥只能轮询到超时，非游戏产物必然白等满 10s，而多数验证只需「加载→截图→读日志」。
+     */
+    async open(input) {
+        const files = readDistDir(input.distDir);
+        if (Object.keys(files).length === 0) {
+            throw new Error(`[minitool-e2e] 产物目录为空：${input.distDir}`);
+        }
+        const entry = input.entry ?? "index.html";
+        if (!(entry in files)) {
+            throw new Error(`[minitool-e2e] 产物目录缺少入口 ${entry}：${input.distDir}（实有 ${Object.keys(files).slice(0, 10).join(", ")}）`);
+        }
+        const { width, height } = input.viewport ?? this.viewport;
+        const viewport = { width, height };
+        await this.page.setViewportSize({ width: width + 40, height: height + 56 });
+        const result = await this.page.evaluate(async ({ files, entry, query, viewport }) => {
+            const bridge = globalThis.__MINITOOL_E2E__;
+            const simulator = bridge.simulator;
+            // 内外视口一起更新，避免截图仍使用旧容器而产生大块留白。
+            const preview = document.getElementById("preview");
+            preview.style.width = `${viewport.width}px`;
+            preview.style.height = `${viewport.height}px`;
+            simulator.setViewport(viewport);
+            bridge.viewport = viewport;
+            // base64 → Uint8Array 必须在页面内还原：结构化克隆过不去 Buffer
+            const decoded = {};
+            for (const [name, content] of Object.entries(files)) {
+                if (typeof content === "string") {
+                    decoded[name] = content;
+                    continue;
+                }
+                const raw = atob(content.base64);
+                const bytes = new Uint8Array(raw.length);
+                for (let i = 0; i < raw.length; i++)
+                    bytes[i] = raw.charCodeAt(i);
+                decoded[name] = bytes;
+            }
+            const loaded = await simulator.loadFiles(decoded, { entry, query });
+            return { entry: loaded?.entry ?? entry, fileCount: Object.keys(decoded).length };
+        }, {
+            files,
+            entry,
+            query: { playtest: "1", ...(input.query ?? {}) },
+            viewport,
+        });
+        this.viewport = viewport;
+        return { ...result, viewport: { ...viewport } };
+    }
+    /**
+     * 等游戏语义桥就绪并判定它到底有没有。
+     *
+     * 必须轮询而非立刻判定：`loadFiles` resolve 只代表虚拟入口已挂载、iframe 已开始导航，
+     * **不代表 guest 的 JS 跑完了**（游戏模板要等 Pixi 初始化 + WebGL 首帧才挂上桥）。
+     * 反过来，**非游戏产物必然等满 timeoutMs 才返回 false** —— 无法预先判断产物形态，
+     * 这正是把它从 `open()` 拆出来的理由。
+     */
+    async gameAttach(timeoutMs = 10_000) {
+        const startedAt = Date.now();
+        const bridgeAvailable = await this.page.evaluate(async (deadlineMs) => {
+            const simulator = globalThis.__MINITOOL_E2E__.simulator;
+            const deadline = Date.now() + deadlineMs;
+            for (;;) {
+                const ok = await simulator.gamePlaytest.isAvailable().catch(() => false);
+                if (ok)
+                    return true;
+                if (Date.now() >= deadline)
+                    return false;
+                await new Promise((resolve) => setTimeout(resolve, 100));
+            }
+        }, timeoutMs);
+        return { bridgeAvailable, waitedMs: Date.now() - startedAt };
+    }
+    // ── 游戏专属：以下全部经 __GAME_TEST__ 桥，非游戏产物会 reject ──────────────────
+    /** 读游戏 manifest（目标、可用动作、里程碑、胜负判据）。非游戏产物会 reject。 */
+    manifest() {
+        return this.invokeBridge("manifest");
+    }
+    /** 读当前语义状态快照。 */
+    snapshot() {
+        return this.invokeBridge("snapshot");
+    }
+    /**
+     * 执行一个 manifest 声明的动作。走**语义桥**（模板注册的动作回调），不是真实指针事件。
+     *
+     * ⚠️ 真实 pointer 路径必须先渲染一帧：试玩模式下模板会 `app.stop()`，而 Pixi v8 的命中测试
+     * 依赖只在 `render()` 内部赋值的 `renderer.lastObjectRendered`。从未渲染过时
+     * `EventBoundary.mapEvent` 会**静默 return** —— 点击看似发生了却什么都不触发。
+     * 所以派发坐标事件前必须先 `step(16)`。该路径未实现，见 performPointerAction()。
+     */
+    act(action) {
+        return this.invokeBridge("act", [action]);
+    }
+    /** 推进确定性时钟。同时也是「先渲染一帧」的手段（见 act 注释）。 */
+    step(ms) {
+        return this.invokeBridge("step", [ms]);
+    }
+    /** 重开，可带确定性随机种子。 */
+    reset(seed) {
+        return this.invokeBridge("reset", seed === undefined ? [] : [seed]);
+    }
+    /** 取页面侧攒下的事件（console / guestError / CSP / 失败请求），取完即清。 */
+    async logs(level) {
+        return this.page.evaluate((lvl) => globalThis.__MINITOOL_E2E__.drainEvents(lvl), level);
+    }
+    /** 截当前帧。截的是模拟器容器，不是整个浏览器窗口。 */
+    async screenshot() {
+        const element = await this.page.$("#preview");
+        // scale:"css" 让截图与 dom rect / interact 坐标同为 1:1 逻辑 CSS px（否则 deviceScaleFactor=2 会放大一倍）
+        const buffer = await (element ?? this.page).screenshot({ type: "png", scale: "css" });
+        const result = {
+            data: Buffer.from(buffer).toString("base64"),
+            mimeType: "image/png",
+            description: "Current miniapp-simulator frame",
+        };
+        // 已配置上传（宿主侧的 e2e 截图上传代理）时先把 PNG 进桶，再带 URL 返回给模型。
+        // 上传失败降级为纯 base64：截图判读不因上传故障中断，符合 e2e 的 fail-open 口径。
+        const uploadBase = process.env.MINITOOL_E2E_UPLOAD_BASE?.trim();
+        const taskId = process.env.MINITOOL_E2E_TASK_ID?.trim();
+        if (uploadBase && taskId) {
+            try {
+                const uploaded = await (0, upload_1.uploadScreenshot)(result.data, {
+                    base: uploadBase,
+                    taskId,
+                    token: process.env.MINITOOL_E2E_UPLOAD_TOKEN?.trim() || undefined,
+                });
+                result.url = uploaded.url;
+                result.fileKey = uploaded.fileKey;
+                result.description = `Current miniapp-simulator frame (saved to ${uploaded.url})`;
+            }
+            catch (err) {
+                console.warn(`[minitool-e2e] 截图上传失败，降级为纯 base64：${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        return result;
+    }
+    // ── e2e 通用能力（实现待补，签名已定） ──────────────────────────────────────────
+    //
+    // 与上面那批 game_* 的区别：**不经 `__GAME_TEST__` 桥**，所以任何产物都成立，
+    // 不只游戏。将来非游戏形态（spa_vue / fullstack_node）的验证主要靠这几个。
+    /**
+     * 读小工具发出的网络请求与响应。数据源已探针实测过，但**不是**模拟器的 `network` 事件 ——
+     * 那个事件声明了、转发了，却**没有任何地方 emit**，且 payload 里没有 body。
+     * 真正能拿到完整请求/响应的是 **bridge 协议日志**：guest 走 `xhs.miniTool.request` 时
+     * bridge 会把 invoke/callback 打进 console，用 `msg.args()` + `jsonValue()` 反序列化
+     * （console 文本里只是 "Object"，拿不到）。
+     */
+    network(_query = {}) {
+        return Promise.resolve(notImplemented("e2e_network", "网络请求观测尚未实现，返回结果不可作为判定依据。", [
+            "需要在宿主页侧常驻收集 bridge 协议日志（page.on('console') + msg.args() 反序列化）",
+            "同源相对路径的 fetch 由 Service Worker 从内存返回，不经网络层，需另走 SW 侧统计",
+        ]));
+    }
+    /**
+     * 读当前渲染出的 DOM 摘要：白屏/是否渲染出内容不靠截图也能判。元素描述与模拟器
+     * `inspector/selector.ts` 的 ElementSelection 同 schema（label/selector/tag/class/text/rect）。
+     */
+    async dom(query = {}) {
+        const frame = await this.guestFrame();
+        const domSummary = await frame.evaluate(({ selector, maxNodes }) => {
+            const doc = document;
+            const max = maxNodes ?? 50;
+            const escapeIdent = (v) => {
+                const css = window.CSS;
+                if (css && typeof css.escape === "function")
+                    return css.escape(v);
+                return v.replace(/[^a-zA-Z0-9_-]/g, (ch) => `\\${ch}`);
+            };
+            const isUniqueId = (el) => {
+                if (!el.id)
+                    return false;
+                try {
+                    return doc.querySelectorAll(`#${escapeIdent(el.id)}`).length === 1;
+                }
+                catch {
+                    return false;
+                }
+            };
+            const computeSelector = (node) => {
+                const parts = [];
+                let el = node;
+                while (el && el.nodeType === 1 && el !== doc.documentElement) {
+                    if (isUniqueId(el)) {
+                        parts.unshift(`#${escapeIdent(el.id)}`);
+                        break;
+                    }
+                    let part = el.tagName.toLowerCase();
+                    const parent = el.parentElement;
+                    if (parent) {
+                        const sameTag = Array.from(parent.children).filter((c) => c.tagName === el.tagName);
+                        if (sameTag.length > 1)
+                            part += `:nth-of-type(${sameTag.indexOf(el) + 1})`;
+                    }
+                    parts.unshift(part);
+                    el = el.parentElement;
+                }
+                return parts.join(" > ");
+            };
+            const makeLabel = (el) => {
+                const tag = el.tagName.toLowerCase();
+                const identity = el.id
+                    ? `#${el.id}`
+                    : el.classList.length > 0
+                        ? `.${el.classList.item(0)}`
+                        : "";
+                const text = (el.textContent ?? "").replace(/\s+/g, " ").trim().slice(0, 18);
+                return text ? `${tag}${identity} · ${text}` : `${tag}${identity}`;
+            };
+            const describe = (el) => {
+                const r = el.getBoundingClientRect();
+                const attributes = {};
+                for (const attr of Array.from(el.attributes))
+                    attributes[attr.name] = attr.value;
+                return {
+                    label: makeLabel(el),
+                    selector: computeSelector(el),
+                    tagName: el.tagName.toLowerCase(),
+                    id: el.id || null,
+                    classList: Array.from(el.classList),
+                    text: (el.textContent ?? "").replace(/\s+/g, " ").trim().slice(0, 200),
+                    attributes,
+                    rect: { x: r.left, y: r.top, width: r.width, height: r.height },
+                };
+            };
+            const matches = selector ? Array.from(doc.querySelectorAll(selector)) : [];
+            const source = selector ? matches : Array.from(doc.body?.querySelectorAll("*") ?? []);
+            const sampled = source.slice(0, max).map(describe);
+            return {
+                viewport: { width: window.innerWidth, height: window.innerHeight },
+                url: location.href,
+                title: doc.title,
+                selector: selector ?? null,
+                matchCount: selector ? matches.length : null,
+                body: {
+                    textLength: doc.body?.innerText.length ?? 0,
+                    elementCount: doc.body?.querySelectorAll("*").length ?? 0,
+                },
+                sampledNodes: sampled,
+                truncated: source.length > max,
+            };
+        }, { selector: query.selector, maxNodes: query.maxNodes });
+        const sceneTree = await this.readSceneTree();
+        return { ...domSummary, sceneTree };
+    }
+    /**
+     * 通用交互适配：手势和 reload 只调用模拟器公开能力，文本输入才直接操作 guest DOM。
+     * 坐标空间 = 应用逻辑 CSS px（由 simulator 的 GestureHostBus 统一换算）。
+     */
+    async interact(input) {
+        if (input.action === "reload") {
+            const result = await this.page.evaluate(async () => {
+                const simulator = globalThis.__MINITOOL_E2E__?.simulator;
+                if (!simulator?.reload)
+                    throw new Error("[minitool-e2e] 模拟器 reload 能力未就绪");
+                await simulator.reload();
+                return { action: "reload" };
+            });
+            return { ...result, via: "simulator" };
+        }
+        const gestureActions = new Set(["tap", "doubleTap", "longPress", "scroll", "swipe"]);
+        if (gestureActions.has(input.action)) {
+            if (input.action === "scroll" &&
+                !((Number.isFinite(input.deltaX) && input.deltaX !== 0) ||
+                    (Number.isFinite(input.deltaY) && input.deltaY !== 0))) {
+                throw new Error("[minitool-e2e] scroll 需要非零的 deltaX 或 deltaY");
+            }
+            if (input.action === "swipe" &&
+                (typeof input.toX !== "number" || typeof input.toY !== "number")) {
+                throw new Error("[minitool-e2e] swipe 需要终点 toX 与 toY");
+            }
+            let point = { x: input.x, y: input.y };
+            if (input.selector) {
+                const frame = await this.guestFrame();
+                point = await frame.evaluate((selector) => {
+                    const target = document.querySelector(selector);
+                    if (!target)
+                        throw new Error(`[minitool-e2e] selector「${selector}」未命中任何元素`);
+                    const rect = target.getBoundingClientRect();
+                    return { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 };
+                }, input.selector);
+            }
+            else if (input.action === "scroll" &&
+                typeof input.x === "undefined" &&
+                typeof input.y === "undefined") {
+                // 保持旧协议兼容：scroll 只带 deltaX/deltaY 时，以 guest viewport 中心作为 wheel 落点。
+                // GestureHostBus 需要坐标，但调用方不应该为了滚动被迫感知模拟器坐标系。
+                const frame = await this.guestFrame();
+                point = await frame.evaluate(() => ({
+                    x: Math.max(0, window.innerWidth / 2),
+                    y: Math.max(0, window.innerHeight / 2),
+                }));
+            }
+            if (!Number.isFinite(point.x) || !Number.isFinite(point.y)) {
+                throw new Error("[minitool-e2e] 手势需要 selector，或同时给 x 与 y（应用逻辑 CSS px）");
+            }
+            const result = await this.page.evaluate(async (gesture) => {
+                const simulator = globalThis.__MINITOOL_E2E__?.simulator;
+                const dispatch = simulator?.gesture?.dispatch;
+                if (typeof dispatch !== "function")
+                    throw new Error("[minitool-e2e] 模拟器 gesture.dispatch 能力未就绪");
+                return dispatch.call(simulator.gesture, gesture);
+            }, {
+                action: input.action,
+                x: point.x,
+                y: point.y,
+                toX: input.toX,
+                toY: input.toY,
+                deltaX: input.deltaX,
+                deltaY: input.deltaY,
+                duration: input.duration,
+            });
+            return { ...result, via: "simulator.gesture" };
+        }
+        // 只有文本输入仍需直接操作 guest DOM（模拟器无对应语义能力）；tap/doubleTap/longPress/scroll/swipe
+        // 全部走上面的 simulator.gesture.dispatch，不在 e2e 侧合成指针事件。
+        if (input.action !== "input") {
+            throw new Error(`[minitool-e2e] interact：未知 action「${input.action}」`);
+        }
+        const frame = await this.guestFrame();
+        if (!input.selector)
+            throw new Error("[minitool-e2e] interact：input 需要 selector 指向可输入元素");
+        if (typeof input.text !== "string")
+            throw new Error("[minitool-e2e] interact：input 需要 text");
+        return frame.evaluate(({ selector, text }) => {
+            const target = document.querySelector(selector);
+            if (!target)
+                throw new Error(`[minitool-e2e] interact：selector「${selector}」未命中任何元素`);
+            target.focus?.();
+            const el = target;
+            const proto = el.tagName === "TEXTAREA"
+                ? window.HTMLTextAreaElement.prototype
+                : window.HTMLInputElement.prototype;
+            const setter = Object.getOwnPropertyDescriptor(proto, "value")?.set;
+            if (setter)
+                setter.call(el, text);
+            else
+                el.value = text;
+            el.dispatchEvent(new Event("input", { bubbles: true }));
+            el.dispatchEvent(new Event("change", { bubbles: true }));
+            return { action: "input", selector, text };
+        }, { selector: input.selector, text: input.text });
+    }
+    /**
+     * 运行时健康汇总：把 logs() 里攒下的事件按口径分类，返回显式计数 + 少量采样，不发空集合。
+     */
+    async health() {
+        const events = (await this.logs());
+        const counts = {
+            guestError: 0,
+            error: 0,
+            consoleError: 0,
+            consoleWarn: 0,
+            navigation: 0,
+            renderDone: 0,
+        };
+        const samples = {
+            guestError: [],
+            error: [],
+            consoleError: [],
+        };
+        const pick = (d) => {
+            if (typeof d === "string")
+                return d;
+            if (d && typeof d === "object") {
+                const o = d;
+                for (const k of ["message", "error", "reason", "detail"]) {
+                    if (typeof o[k] === "string")
+                        return o[k];
+                }
+                return "字段：" + Object.keys(o).slice(0, 6).join(",");
+            }
+            return null;
+        };
+        const push = (bucket, d, cap = 5) => {
+            const m = pick(d);
+            if (m && samples[bucket].length < cap)
+                samples[bucket].push(m);
+        };
+        for (const ev of events) {
+            switch (ev.name) {
+                case "guestError":
+                    counts.guestError++;
+                    push("guestError", ev.detail);
+                    break;
+                case "error":
+                    counts.error++;
+                    push("error", ev.detail);
+                    break;
+                case "console": {
+                    const level = ev.detail?.level;
+                    if (level === "error") {
+                        counts.consoleError++;
+                        push("consoleError", ev.detail);
+                    }
+                    else if (level === "warn") {
+                        counts.consoleWarn++;
+                    }
+                    break;
+                }
+                case "navigation":
+                    counts.navigation++;
+                    break;
+                case "renderDone":
+                    counts.renderDone++;
+                    break;
+            }
+        }
+        const errorTotal = counts.guestError + counts.error + counts.consoleError;
+        return {
+            status: errorTotal > 0 ? "degraded" : "ok",
+            checkedEvents: events.length,
+            counts,
+            topErrors: samples,
+        };
+    }
+    /**
+     * 真实指针动作，未实现（前提见下面 throw 的文案）。探针已验明的坐标换算式：
+     * `canvasBox.origin + appCoord * (canvasBox.size / app.screen.size)`，其中
+     * `selectByRef` 返回的 `viewportRect` 已是宿主屏幕坐标 —— 但它有副作用（会打开选取层并盖
+     * 一层 z-index 极高的拦截元素），所以要等模拟器补一个无副作用的 `describeByRef`。
+     */
+    performPointerAction(_action) {
+        return Promise.reject(new Error("[minitool-e2e] 真实指针动作尚未实现（当前 act 走语义桥）。" +
+            "依赖项：miniapp-simulator 需提供无副作用的 describeByRef；" +
+            "且派发坐标事件前必须先 step(16) 渲染一帧，否则 Pixi 命中测试静默失效。"));
+    }
+    /** 定位 guest 应用 iframe（主 frame 之外的唯一子 frame）。 */
+    async guestFrame() {
+        const frames = this.page.frames();
+        const guest = frames.find((f) => f !== this.page.mainFrame());
+        if (!guest)
+            throw new Error("[minitool-e2e] 应用 iframe 尚未挂载（请先 e2e_open）");
+        return guest;
+    }
+    /**
+     * 读场景树（canvas / Pixi / Three 的 Scene Provider）。无副作用、只读；
+     * 产物没注册 provider 时返回空快照（DOM 形态就是如此）。
+     */
+    async readSceneTree() {
+        return this.page.evaluate(async () => {
+            const sim = globalThis.__MINITOOL_E2E__?.simulator;
+            try {
+                const tree = await sim?.inspector?.getSceneTree?.();
+                return tree ?? { version: 1, providers: [] };
+            }
+            catch {
+                return { version: 1, providers: [] };
+            }
+        });
+    }
+    async close() {
+        await this.browser.close().catch(() => undefined);
+        await this.host.close().catch(() => undefined);
+        return { closed: true };
+    }
+    invokeBridge(method, args = []) {
+        return this.page.evaluate(({ method, args }) => globalThis.__MINITOOL_E2E__.simulator.gamePlaytest[method](...args), { method, args });
+    }
+}
+exports.MinitoolE2ESession = MinitoolE2ESession;
+/** 递归读产物目录，文本直读、二进制转 base64 标记。 */
+function readDistDir(dir, prefix = "") {
+    if (!fs.existsSync(dir)) {
+        throw new Error(`[minitool-e2e] 产物目录不存在：${dir}`);
+    }
+    const out = {};
+    for (const name of fs.readdirSync(dir)) {
+        const file = path.join(dir, name);
+        if (fs.statSync(file).isDirectory()) {
+            Object.assign(out, readDistDir(file, `${prefix}${name}/`));
+            continue;
+        }
+        const ext = path.extname(name).toLowerCase();
+        out[`${prefix}${name}`] = BINARY_EXTENSIONS.has(ext)
+            ? { __binary: true, base64: fs.readFileSync(file).toString("base64") }
+            : fs.readFileSync(file, "utf8");
+    }
+    return out;
+}

package/lib/upload.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_UPLOAD_TIMEOUT_MS = void 0;
+exports.uploadScreenshot = uploadScreenshot;
+/**
+ * 上传请求的硬超时。
+ *
+ * 没有它，宿主上传代理无响应 / 连接半开 / 服务端持续不返回时 `fetch` 会一直 pending，
+ * `session.screenshot()` 就永远不返回 —— 调用方那句「上传失败降级为纯 base64」也就永远不生效，
+ * e2e 判读会被一个卡死的上传拖死。
+ *
+ * 取值远高于实测耗时（SIT 真上传 ~0.5s），只兜「卡死」不兜「慢」。
+ */
+exports.DEFAULT_UPLOAD_TIMEOUT_MS = 20_000;
+async function uploadScreenshot(base64, config) {
+    const endpoint = `${config.base.replace(/\/+$/, "")}/e2e/screenshot`;
+    const res = await fetch(endpoint, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            ...(config.token ? { "x-e2e-upload-token": config.token } : {}),
+        },
+        body: JSON.stringify({ taskId: config.taskId, base64 }),
+        // 必须有限超时：宿主不响应时否则会一直 pending，把 screenshot() 挂死（见 DEFAULT_UPLOAD_TIMEOUT_MS）。
+        // signal 会一直挂在响应上，所以后面 res.json() 卡住同样会被中断。
+        signal: AbortSignal.timeout(config.timeoutMs ?? exports.DEFAULT_UPLOAD_TIMEOUT_MS),
+    });
+    if (!res.ok) {
+        throw new Error(`[minitool-e2e] 截图上传失败：HTTP ${res.status}`);
+    }
+    // 宿主信封 `{ code, data, message/msg }`，成功 code === 0、数据在 data 里。
+    const body = (await res.json());
+    if (typeof body.code === "number" && body.code !== 0) {
+        throw new Error(`[minitool-e2e] 截图上传被拒：${body.message || body.msg || `code=${body.code}`}`);
+    }
+    const url = body.data?.url;
+    if (typeof url !== "string" || !url) {
+        throw new Error(`[minitool-e2e] 截图上传未拿到 URL：${JSON.stringify(body)}`);
+    }
+    return { url, fileKey: typeof body.data?.fileKey === "string" ? body.data.fileKey : "" };
+}

package/lib/upload.test.js

@@ -0,0 +1,44 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * 上传请求必须**有限超时**。
+ *
+ * 宿主上传代理无响应 / 连接半开时，没有超时的 `fetch` 会一直 pending，`session.screenshot()`
+ * 就永远不返回 —— 调用方那句「上传失败降级为纯 base64」也就永远不生效，一次卡死的上传能把
+ * e2e 判读整个拖死。这里用一个只收请求、永不响应的本地服务端把这条兜底钉住。
+ */
+const strict_1 = __importDefault(require("node:assert/strict"));
+const node_http_1 = __importDefault(require("node:http"));
+const node_test_1 = __importDefault(require("node:test"));
+const upload_1 = require("./upload");
+/** 只建立连接、永不回包的服务端（模拟半开 / 无响应的宿主上传代理）。 */
+async function startSilentServer() {
+    const server = node_http_1.default.createServer(() => {
+        // 故意不 res.end()：让请求悬在那里
+    });
+    await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const address = server.address();
+    const port = typeof address === "object" && address ? address.port : 0;
+    return {
+        base: `http://127.0.0.1:${port}`,
+        close: () => new Promise((resolve) => {
+            server.closeAllConnections?.();
+            server.close(() => resolve());
+        }),
+    };
+}
+(0, node_test_1.default)("上传：宿主不响应时必须按 timeoutMs 失败，而不是一直挂着", async () => {
+    const { base, close } = await startSilentServer();
+    try {
+        const startedAt = Date.now();
+        await strict_1.default.rejects(() => (0, upload_1.uploadScreenshot)("iVBORw0KGgo=", { base, taskId: "t-upload-timeout", timeoutMs: 200 }), /abort|timeout/i);
+        // 真正的判据：是「到点失败」而不是「恰好很快失败」
+        strict_1.default.ok(Date.now() - startedAt >= 200, "早于 timeoutMs 就失败了，用例没有测到超时路径");
+    }
+    finally {
+        await close();
+    }
+});