@szc-ft/mcp-szcd-client 0.28.1 → 0.29.0

package/qwen-extension/skills/local-browser-test/lib/browser-engine.js

@@ -0,0 +1,2427 @@
+/**
+ * 浏览器控制引擎 - 双模式（connect / launch）
+ *
+ * 模式 A: connect（优先）
+ *   连接用户已启动的调试 Chrome（--remote-debugging-port=9222）
+ *   天然继承登录态/Cookie/SSO/微前端环境
+ *
+ * 模式 B: launch（回退）
+ *   启动新的 headless Chrome，需要用户提供可访问的 URL
+ *
+ * 依赖（optionalDependencies）：puppeteer-core
+ */
+
+import { findChrome, getChromeInstallGuide } from "./chrome-finder.js";
+import { AntAdapter } from "./ant-adapter.js";
+import { createExpect, locator as expectLocator, validation as expectValidation, url as expectUrl, api as expectApi } from "./expect.js";
+
+export class BrowserEngine {
+    constructor() {
+        this.browser = null;
+        this.page = null;
+        this.mode = null;        // 'connect' | 'launch'
+        this.ownedBrowser = false; // launch 模式为 true，决定关闭时是否 kill
+        this._activeFrame = null;  // 当前活跃 iframe 上下文（微前端场景）
+        this._adapter = null;      // 懒加载 AntAdapter
+        this._lastActWasDropdown = false; // 用于 act 入口自动 closeAllDropdowns
+        this._wujieContext = null;  // wujie 微前端模式 { type, frameCount, wujieApp? }
+    }
+
+    /**
+     * 获取 / 懒初始化 AntAdapter，支持 componentMeta 注入（来自 szcd MCP 私有组件元数据）
+     */
+    _getAdapter(componentMeta) {
+        if (!this._adapter) {
+            this._adapter = new AntAdapter({ componentMeta: componentMeta || {} });
+        } else if (componentMeta) {
+            this._adapter.componentMeta = { ...this._adapter.componentMeta, ...componentMeta };
+        }
+        return this._adapter;
+    }
+
+    /**
+     * 初始化：自动选择 connect 或 launch 模式
+     * @param {object} options
+     * @param {string} [options.cdpUrl='http://localhost:9222'] - CDP 调试地址
+     * @param {string} [options.pageUrl] - 目标页面 URL（connect 时用于匹配标签页）
+     * @param {object} [options.viewport] - 视口尺寸 { width, height }
+     * @returns {Promise<object>} 初始化结果
+     */
+    async init(options = {}) {
+        const cdpUrl = options.cdpUrl || "http://localhost:9222";
+
+        // 优先尝试 connect 模式
+        if (await this.isDebuggerAvailable(cdpUrl)) {
+            return this.connect(cdpUrl, options);
+        }
+
+        // 回退到 launch 模式
+        return this.launch(options);
+    }
+
+    /**
+     * 检查调试端口是否可用
+     */
+    async isDebuggerAvailable(cdpUrl) {
+        try {
+            const res = await fetch(`${cdpUrl}/json/version`, {
+                signal: AbortSignal.timeout(2000),
+            });
+            return res.ok;
+        } catch {
+            return false;
+        }
+    }
+
+    /**
+     * 检测 wujie 微前端模式（WebComponent / iframe）
+     * @returns {{ type: 'webcomponent'|'iframe'|'none', frameCount: number, wujieApp?: object }}
+     */
+    async _detectWujieMode() {
+        const frames = this.page.frames();
+        const frameCount = frames.length;
+        const mainFrame = this.page.mainFrame();
+
+        // 检查主文档中是否有 <wujie-app> 自定义元素（WebComponent 模式标志）
+        const wujieInfo = await mainFrame.evaluate(() => {
+            const app = document.querySelector('wujie-app');
+            if (!app) return null;
+            const sr = app.shadowRoot;
+            return {
+                tagName: app.tagName,
+                className: app.className,
+                hasShadowRoot: !!sr,
+                shadowChildren: sr?.children?.length || 0,
+                shadowBodyText: sr?.querySelector('body')?.innerText?.substring(0, 80) || ''
+            };
+        }).catch(() => null);
+
+        if (wujieInfo) {
+            const ctx = { type: 'webcomponent', frameCount, wujieApp: wujieInfo };
+            process.stderr.write(`[wujie] WebComponent 模式: <${wujieInfo.tagName} class="${wujieInfo.className}"> shadowRoot=${wujieInfo.hasShadowRoot} children=${wujieInfo.shadowChildren} frames=${frameCount}\n`);
+            if (wujieInfo.shadowBodyText) {
+                process.stderr.write(`[wujie]   shadow body preview: "${wujieInfo.shadowBodyText}"\n`);
+            }
+            // 列出所有 frame 供排障
+            for (let i = 0; i < frames.length; i++) {
+                process.stderr.write(`[wujie]   frame[${i}]: ${frames[i].url().substring(0, 100)}\n`);
+            }
+            return ctx;
+        }
+
+        if (frameCount > 1) {
+            process.stderr.write(`[wujie] iframe 模式: ${frameCount} frames\n`);
+            for (let i = 0; i < frames.length; i++) {
+                process.stderr.write(`[wujie]   frame[${i}]: ${frames[i].url().substring(0, 100)}\n`);
+            }
+            return { type: 'iframe', frameCount };
+        }
+
+        process.stderr.write(`[wujie] 未检测到微前端 (frames=${frameCount})\n`);
+        return { type: 'none', frameCount };
+    }
+
+    /**
+     * 安全获取页面列表（优先同步 targets() 避免 pages() 挂死 + 泄露 WebSocket）
+     */
+    async _safeGetPages() {
+        // 1. 优先使用同步 targets()，不会挂死也不会泄露未完成的 promise
+        try {
+            const targets = this.browser.targets();
+            const pageTargets = targets.filter((t) => t.type() === "page");
+            if (pageTargets.length > 0) {
+                const pages = [];
+                for (const t of pageTargets) {
+                    try {
+                        const p = await Promise.race([
+                            t.page(),
+                            new Promise((_, reject) => setTimeout(() => reject(new Error("page() timeout")), 3000)),
+                        ]);
+                        if (p) pages.push(p);
+                    } catch {
+                        // 跳过无法获取的 target
+                    }
+                }
+                if (pages.length > 0) return pages;
+            }
+        } catch {
+            // targets() 失败
+        }
+
+        // 2. 回退：CDP Target.getTargets
+        try {
+            const client = await this.browser.target().createCDPSession();
+            const { targetInfos } = await client.send("Target.getTargets");
+            const pageInfos = targetInfos.filter((t) => t.type === "page");
+            const pages = [];
+            for (const info of pageInfos) {
+                try {
+                    const target = await Promise.race([
+                        this.browser.waitForTarget((t) => t.url() === info.url, { timeout: 2000 }),
+                        new Promise((_, reject) => setTimeout(() => reject(new Error("waitForTarget timeout")), 3000)),
+                    ]);
+                    if (target) {
+                        const p = await Promise.race([
+                            target.page(),
+                            new Promise((_, reject) => setTimeout(() => reject(new Error("page() timeout")), 3000)),
+                        ]);
+                        if (p) pages.push(p);
+                    }
+                } catch {
+                    // skip
+                }
+            }
+            if (pages.length > 0) return pages;
+        } catch {
+            // CDP 回退也失败
+        }
+
+        // 3. 最后手段：只能尝试 pages()（带严格超时，用完立即 disconnect/reconnect 清理）
+        try {
+            const pages = await Promise.race([
+                this.browser.pages(),
+                new Promise((_, reject) => setTimeout(() => reject(new Error("pages() timeout")), 5000)),
+            ]);
+            if (pages && pages.length > 0) return pages;
+        } catch {
+            // pages() 超时；注意此时 browser.pages() 的 WebSocket 可能泄露
+            // 清理：断开后重新连接
+            try {
+                const wsUrl = this.browser.wsEndpoint();
+                const puppeteer = await loadPuppeteer();
+                await this.browser.disconnect();
+                this.browser = await puppeteer.connect({ browserWSEndpoint: wsUrl, defaultViewport: null });
+            } catch {
+                // reconnect 失败，继续用当前 browser
+            }
+        }
+
+        // 4. 最后手段：newPage()
+        return [await this.browser.newPage()];
+    }
+
+    /**
+     * 模式 A：连接到用户已有的 Chrome
+     */
+    async connect(cdpUrl, options = {}) {
+        const puppeteer = await loadPuppeteer();
+        this.browser = await puppeteer.connect({ browserURL: cdpUrl, defaultViewport: null });
+        this.mode = "connect";
+        this.ownedBrowser = false;
+
+        // 获取页面：优先使用指定 URL 匹配的标签页
+        const pages = await this._safeGetPages();
+        if (options.pageUrl) {
+            this.page = pages.find((p) => p.url().includes(options.pageUrl))
+                     || await this.browser.newPage();
+        } else {
+            // 选择第一个非 chrome:// 的页面
+            this.page = pages.find((p) => !p.url().startsWith("chrome://"))
+                     || pages[0];
+        }
+
+        if (options.viewport && this.page) {
+            await this.page.setViewport(options.viewport);
+        }
+
+        // 微前端模式检测
+        this._wujieContext = await this._detectWujieMode();
+
+        return {
+            mode: "connect",
+            cdpUrl,
+            currentUrl: this.page?.url() || null,
+            totalPages: pages.length,
+            allPageUrls: pages.map((p) => p.url()),
+        };
+    }
+
+    /**
+     * 模式 B：启动新的 Chrome
+     */
+    async launch(options = {}) {
+        const puppeteer = await loadPuppeteer();
+        const chrome = findChrome();
+
+        if (!chrome.path) {
+            const guide = getChromeInstallGuide();
+            const error = new Error(
+                `${guide.message}\n安装方式：\n${guide.installCommands.join("\n")}\n\n` +
+                `或使用 connect 模式：以 --remote-debugging-port=9222 启动 Chrome`
+            );
+            error.code = "CHROME_NOT_FOUND";
+            throw error;
+        }
+
+        this.browser = await puppeteer.launch({
+            executablePath: chrome.path,
+            headless: true,
+            args: [
+                "--no-sandbox",
+                "--disable-setuid-sandbox",
+                "--disable-dev-shm-usage",
+                "--disable-gpu",
+                "--no-first-run",
+                "--no-default-browser-check",
+            ],
+        });
+        this.page = await this.browser.newPage();
+        this.mode = "launch";
+        this.ownedBrowser = true;
+
+        if (options.viewport) {
+            await this.page.setViewport(options.viewport);
+        } else {
+            await this.page.setViewport({ width: 1440, height: 900 });
+        }
+
+        return {
+            mode: "launch",
+            browser: chrome.name,
+            chromePath: chrome.path,
+        };
+    }
+
+    /**
+     * 执行单个步骤
+     * @param {object} step - 步骤定义
+     * @param {object} context - 执行上下文 { outputDir }
+     * @returns {Promise<object>} 步骤执行结果
+     */
+    async executeStep(step, context = {}) {
+        const startTime = Date.now();
+        try {
+            const result = await this._dispatchStep(step, context);
+            if (step.type === "apiCapture" || step.type === "api-capture") {
+                context.lastApiCapture = result;
+                this._lastApiCapture = result; // 同步到 engine，供 _expect 使用
+            }
+            return {
+                ...result,
+                step: step.type,
+                duration: Date.now() - startTime,
+                status: result?.passed === false ? "FAIL" : "PASS",
+            };
+        } catch (err) {
+            return {
+                step: step.type,
+                duration: Date.now() - startTime,
+                status: "FAIL",
+                error: err.message,
+            };
+        }
+    }
+
+    /**
+     * 安全执行 page/frame evaluate，捕获重定向导致的 context destroyed 错误
+     */
+    async safeEval(fn, ...args) {
+        const target = this._activeFrame || this.page;
+        try {
+            return await target.evaluate(fn, ...args);
+        } catch (err) {
+            if (err.message.includes("Not attached") || err.message.includes("Execution context")) {
+                // 重定向后 page/frame 可能已失效，重新获取
+                this._activeFrame = null;
+                return await this.page.evaluate(fn, ...args);
+            }
+            throw err;
+        }
+    }
+
+    async observe(options = {}) {
+        const targetFrame = await this._resolveObserveFrame(options);
+        const selector = options.selector || "body";
+        const depth = Number.parseInt(options.depth ?? 5, 10);
+        const maxInteractiveElements = Number.parseInt(options.maxInteractiveElements ?? 200, 10);
+        const frames = await this._getFrameSummaries();
+        const tree = await this._buildDomTree(targetFrame.frame, selector, depth);
+        const interactiveElements = await this._collectInteractiveElements(
+            targetFrame.frame,
+            targetFrame.frameId,
+            maxInteractiveElements
+        );
+        const title = await this.page.title().catch(() => "");
+
+        return {
+            type: "observe",
+            url: this.page.url(),
+            title,
+            timestamp: new Date().toISOString(),
+            mode: this.mode,
+            target: {
+                frameId: targetFrame.frameId,
+                frameUrl: targetFrame.frame.url(),
+                matchedBy: targetFrame.matchedBy,
+            },
+            wujieContext: this._wujieContext,
+            frames,
+            tree,
+            interactiveElements,
+            summary: {
+                frames: frames.length,
+                interactiveElements: interactiveElements.length,
+            },
+        };
+    }
+
+    async act(options = {}) {
+        // 上一次操作是 antSelect/antTreeSelect 等下拉控件 → 先关闭残留浮层（反馈第 3 条）
+        // 跨 frame 清理：覆盖主 frame + 子应用 iframe（微前端场景）
+        if (this._lastActWasDropdown && !options.skipCloseDropdowns) {
+            try {
+                await this._closeDropdownsAllFrames(this._activeFrame || this.page.mainFrame());
+                this._lastActWasDropdown = false;
+            } catch {
+                // closeAllDropdowns 失败不影响 act 继续
+            }
+        }
+
+        const targetFrame = await this._resolveObserveFrame(options);
+        if (options.menuPath) {
+            // 菜单在 main frame 外壳中渲染，不随子应用切换
+            const menuFrame = this.page.mainFrame();
+            const menuTarget = { frame: menuFrame, frameId: "main", matchedBy: "main (menu shell)" };
+            return this._actMenuPath(menuTarget, options);
+        }
+
+        const index = options.index !== undefined ? Number.parseInt(options.index, 10) : undefined;
+        const selector = this._resolveSelector(options.selector || options.click || options.hover);
+        const typeText = options.typeText ?? options.text;
+        const action = options.hover ? "hover" : typeText !== undefined ? "type" : "click";
+
+        const result = await targetFrame.frame.evaluate((actOptions) => {
+            function getText(el) {
+                return (el.innerText || el.textContent || "").replace(/\s+/g, " ").trim().slice(0, 120);
+            }
+
+            function roleOf(el) {
+                const explicit = el.getAttribute("role");
+                if (explicit) return explicit;
+                const tag = el.tagName.toLowerCase();
+                if (tag === "button") return "button";
+                if (tag === "a") return "link";
+                if (["input", "textarea"].includes(tag)) return "textbox";
+                if (tag === "select") return "combobox";
+                return "generic";
+            }
+
+            function getName(el, text) {
+                return (
+                    el.getAttribute("aria-label") ||
+                    el.getAttribute("title") ||
+                    el.getAttribute("placeholder") ||
+                    el.getAttribute("alt") ||
+                    text ||
+                    ""
+                ).slice(0, 120);
+            }
+
+            function isCandidate(el) {
+                const tag = el.tagName.toLowerCase();
+                return ["a", "button", "input", "select", "textarea", "summary"].includes(tag) ||
+                    el.getAttribute("role") ||
+                    el.getAttribute("tabindex") !== null ||
+                    el.onclick ||
+                    el.getAttribute("data-testid") ||
+                    (typeof el.className === "string" && /btn|button|menu-item|ant-btn|ant-menu|ant-select|ant-input/.test(el.className));
+            }
+
+            function interactiveElements() {
+                return Array.from(document.querySelectorAll("a,button,input,select,textarea,summary,[role],[tabindex],[data-testid],[class*='btn'],[class*='button'],[class*='menu-item'],[class*='ant-btn'],[class*='ant-menu'],[class*='ant-select'],[class*='ant-input']"))
+                    .filter(isCandidate);
+            }
+
+            function isVisibleEnabled(el) {
+                const rect = el.getBoundingClientRect();
+                const style = window.getComputedStyle(el);
+                if (rect.width <= 0 || rect.height <= 0) return false;
+                if (style.display === "none" || style.visibility === "hidden" || Number(style.opacity) === 0) return false;
+                if (el.disabled || el.getAttribute("aria-disabled") === "true") return false;
+                return true;
+            }
+
+            function findBySelector(selector) {
+                if (!selector) return null;
+                if (selector.startsWith("text=")) {
+                    const expected = selector.slice(5).trim();
+                    // 默认仅匹配 visible+enabled 元素，避免命中 ant-select 的隐藏 input、收起菜单里的 li
+                    // 需要包含隐藏元素时显式 includeHidden=true
+                    const includeHidden = actOptions.includeHidden === true;
+                    const filter = (el) => includeHidden || isVisibleEnabled(el);
+                    const interactive = interactiveElements().filter(filter);
+                    let hit = interactive.find((el) => getText(el).includes(expected) || getName(el, getText(el)).includes(expected));
+                    if (hit) return hit;
+                    const all = Array.from(document.querySelectorAll("*")).filter(filter);
+                    return all.find((el) => getText(el).includes(expected)) || null;
+                }
+                if (selector.startsWith("role=")) {
+                    const match = selector.match(/^role=([^\[]+)(?:\[name="([^"]+)"\])?/);
+                    const expectedRole = match?.[1]?.trim();
+                    const expectedName = match?.[2]?.trim();
+                    return interactiveElements().find((el) => {
+                        const text = getText(el);
+                        const name = getName(el, text);
+                        return roleOf(el) === expectedRole && (!expectedName || name.includes(expectedName) || text.includes(expectedName));
+                    });
+                }
+                try {
+                    return document.querySelector(selector);
+                } catch {
+                    return null;
+                }
+            }
+
+            const el = actOptions.index !== undefined
+                ? interactiveElements()[actOptions.index - 1]
+                : findBySelector(actOptions.selector);
+
+            if (!el) {
+                return { found: false };
+            }
+
+            el.scrollIntoView({ block: "center", inline: "center" });
+            const rect = el.getBoundingClientRect();
+            const style = window.getComputedStyle(el);
+            const visible = rect.width > 0 && rect.height > 0 && style.visibility !== "hidden" && style.display !== "none";
+            const enabled = !el.disabled && el.getAttribute("aria-disabled") !== "true";
+            const text = getText(el);
+            const name = getName(el, text);
+            const baseResult = {
+                found: true,
+                tagName: el.tagName,
+                role: roleOf(el),
+                name,
+                text,
+                visible,
+                enabled,
+                bbox: {
+                    x: Math.round(rect.x),
+                    y: Math.round(rect.y),
+                    width: Math.round(rect.width),
+                    height: Math.round(rect.height),
+                },
+            };
+
+            if (!visible || !enabled) {
+                return { ...baseResult, performed: false };
+            }
+
+            if (actOptions.action === "hover") {
+                el.dispatchEvent(new MouseEvent("mouseover", { bubbles: true }));
+                el.dispatchEvent(new MouseEvent("mouseenter", { bubbles: true }));
+                return { ...baseResult, performed: true, action: "hover" };
+            }
+
+            if (actOptions.action === "type") {
+                el.focus();
+                if ("value" in el) {
+                    el.value = actOptions.clear ? "" : el.value;
+                    el.value += actOptions.typeText;
+                } else if (el.isContentEditable) {
+                    el.textContent = actOptions.clear ? actOptions.typeText : `${el.textContent || ""}${actOptions.typeText}`;
+                } else {
+                    return { ...baseResult, performed: false, error: "Target is not typeable" };
+                }
+                el.dispatchEvent(new InputEvent("input", { bubbles: true, inputType: "insertText", data: actOptions.typeText }));
+                el.dispatchEvent(new Event("change", { bubbles: true }));
+                return { ...baseResult, performed: true, action: "type", value: "value" in el ? el.value : el.textContent };
+            }
+
+            el.click();
+            return { ...baseResult, performed: true, action: "click" };
+        }, {
+            index,
+            selector,
+            action,
+            typeText,
+            clear: Boolean(options.clear),
+            includeHidden: Boolean(options.includeHidden),
+        });
+
+        if (!result.found) {
+            throw new Error(index !== undefined ? `Interactive element index not found: ${index}` : `Element not found: ${selector}`);
+        }
+        if (!result.performed) {
+            throw new Error(result.error || `Element is not actionable: ${index ?? selector}`);
+        }
+
+        return {
+            acted: true,
+            action: result.action,
+            index,
+            selector,
+            target: {
+                frameId: targetFrame.frameId,
+                frameUrl: targetFrame.frame.url(),
+                matchedBy: targetFrame.matchedBy,
+            },
+            element: result,
+        };
+    }
+
+    async _actMenuPath(targetFrame, options = {}) {
+        const menuPath = Array.isArray(options.menuPath)
+            ? options.menuPath
+            : String(options.menuPath).split("/").map((item) => item.trim()).filter(Boolean);
+        const waitAfterEach = Number.parseInt(options.waitAfterEach ?? 300, 10);
+        const drawerTriggerSelector = options.drawerTriggerSelector || null;
+        const drawerOpenSelector = options.drawerOpenSelector || ".ant-drawer-open, .ant-drawer.ant-drawer-open";
+        const scrollContainerSelector = options.menuScrollContainer || null;
+        const useNativeHover = options.useNativeHover !== false; // 默认开
+        const maxRetryPerStep = Number.parseInt(options.maxRetryPerStep ?? 2, 10);
+
+        if (menuPath.length === 0) {
+            throw new Error("menuPath is empty");
+        }
+
+        const frame = targetFrame.frame;
+
+        const ensureDrawerOpen = async () => {
+            if (!drawerTriggerSelector) return { ensured: false, reason: "no drawer" };
+            const isOpen = await frame.evaluate((sel) => !!document.querySelector(sel), drawerOpenSelector).catch(() => false);
+            if (isOpen) return { ensured: true, reason: "already open" };
+            const triggered = await frame.evaluate((sel) => {
+                const el = document.querySelector(sel);
+                if (!el) return false;
+                el.scrollIntoView({ block: "center", inline: "center" });
+                el.click();
+                return true;
+            }, drawerTriggerSelector).catch(() => false);
+            if (!triggered) return { ensured: false, reason: "trigger not found" };
+            await new Promise((r) => setTimeout(r, waitAfterEach));
+            return { ensured: true, reason: "clicked trigger" };
+        };
+
+        const scrollContainerOnce = async () => {
+            if (!scrollContainerSelector) return false;
+            return frame.evaluate((sel) => {
+                const c = document.querySelector(sel);
+                if (!c) return false;
+                c.scrollTop = Math.min(c.scrollTop + Math.max(c.clientHeight - 40, 200), c.scrollHeight);
+                return true;
+            }, scrollContainerSelector).catch(() => false);
+        };
+
+        const findStep = async (text, level) => {
+            return frame.evaluate((expectedText, lvl, totalLevels) => {
+                function textOf(el) {
+                    return (el.innerText || el.textContent || "").replace(/\s+/g, " ").trim();
+                }
+                function classText(el) {
+                    return typeof el.className === "string" ? el.className : "";
+                }
+                function isVisible(el) {
+                    const rect = el.getBoundingClientRect();
+                    const style = window.getComputedStyle(el);
+                    return rect.width > 0 && rect.height > 0 && style.display !== "none" && style.visibility !== "hidden";
+                }
+                function menuCandidates() {
+                    return Array.from(document.querySelectorAll([
+                        "[role='menuitem']",
+                        ".ant-menu-item",
+                        ".ant-menu-submenu-title",
+                        "li[class*='menu']",
+                        "a",
+                        "button",
+                        "[class*='menu-item']",
+                        "[class*='submenu']",
+                    ].join(","))).filter(isVisible);
+                }
+                function score(el) {
+                    const actual = textOf(el);
+                    if (!actual) return -1;
+                    let s = -1;
+                    if (actual === expectedText) s = 100;
+                    else if (actual.includes(expectedText)) s = 70;
+                    else if (expectedText.includes(actual)) s = 50;
+                    if (s < 0) return -1;
+                    const cls = classText(el);
+                    const role = el.getAttribute("role") || "";
+                    if (role === "menuitem") s += 10;
+                    if (cls.includes("ant-menu-submenu-title")) s += lvl < totalLevels - 1 ? 20 : -5;
+                    if (cls.includes("ant-menu-item")) s += lvl === totalLevels - 1 ? 20 : 0;
+                    if (cls.includes("ant-menu-item-selected")) s += 5;
+                    return s;
+                }
+                const ranked = menuCandidates()
+                    .map((el) => ({ el, s: score(el), text: textOf(el) }))
+                    .filter((x) => x.s >= 0)
+                    .sort((a, b) => b.s - a.s);
+                const top = ranked[0];
+                if (!top) {
+                    return {
+                        found: false,
+                        candidates: menuCandidates().slice(0, 8).map((el) => ({
+                            text: textOf(el).slice(0, 80),
+                            className: classText(el).slice(0, 120),
+                        })),
+                    };
+                }
+                // 用稳定 attr 标记，避免后续 click 时 ranking 漂移
+                top.el.setAttribute("data-szcd-menu-target", "1");
+                const rect = top.el.getBoundingClientRect();
+                return {
+                    found: true,
+                    matchedText: top.text,
+                    bbox: {
+                        x: Math.round(rect.x), y: Math.round(rect.y),
+                        width: Math.round(rect.width), height: Math.round(rect.height),
+                    },
+                    snapshot: {
+                        tagName: top.el.tagName,
+                        text: textOf(top.el).slice(0, 120),
+                        role: top.el.getAttribute("role") || null,
+                        className: classText(top.el),
+                        ariaExpanded: top.el.getAttribute("aria-expanded"),
+                    },
+                };
+            }, text, level, menuPath.length).catch(() => ({ found: false, candidates: [] }));
+        };
+
+        const clickStep = async (isLast) => {
+            return frame.evaluate(async (waitMs, last) => {
+                const el = document.querySelector("[data-szcd-menu-target='1']");
+                if (!el) return { performed: false, error: "marker lost" };
+                el.scrollIntoView({ block: "center", inline: "center" });
+                const beforeUrl = location.href;
+                const beforeText = document.body?.innerText || "";
+                el.click();
+                el.removeAttribute("data-szcd-menu-target");
+                await new Promise((r) => setTimeout(r, waitMs));
+                const cls = typeof el.className === "string" ? el.className : "";
+                return {
+                    performed: true,
+                    action: last ? "click" : "expand",
+                    after: {
+                        className: cls,
+                        ariaExpanded: el.getAttribute("aria-expanded"),
+                        urlChanged: location.href !== beforeUrl,
+                        textChanged: (document.body?.innerText || "") !== beforeText,
+                        selected: cls.includes("selected") || cls.includes("active"),
+                    },
+                };
+            }, waitAfterEach, isLast);
+        };
+
+        const steps = [];
+
+        for (let i = 0; i < menuPath.length; i++) {
+            const text = menuPath[i];
+            const isLast = i === menuPath.length - 1;
+
+            // 抽屉式菜单：每级前都先确认抽屉是开的
+            const drawerState = await ensureDrawerOpen();
+
+            let match = await findStep(text, i);
+            let attempts = 0;
+            while (!match.found && attempts < maxRetryPerStep) {
+                attempts += 1;
+                // 滚动一次再找
+                const scrolled = await scrollContainerOnce();
+                if (!scrolled) await new Promise((r) => setTimeout(r, waitAfterEach));
+                match = await findStep(text, i);
+            }
+
+            if (!match.found) {
+                return {
+                    acted: false,
+                    action: "menuPath",
+                    menuPath,
+                    target: {
+                        frameId: targetFrame.frameId,
+                        frameUrl: targetFrame.frame.url(),
+                        matchedBy: targetFrame.matchedBy,
+                    },
+                    failedAt: text,
+                    failedAtIndex: i,
+                    candidates: match.candidates || [],
+                    drawerState,
+                    steps,
+                };
+            }
+
+            // native hover（puppeteer frame.hover），优于 dispatchEvent
+            if (useNativeHover && typeof frame.hover === "function") {
+                try {
+                    await frame.hover("[data-szcd-menu-target='1']");
+                } catch {
+                    // hover 失败不致命，继续 click
+                }
+            }
+
+            const clickRes = await clickStep(isLast);
+            steps.push({
+                text,
+                action: clickRes.action || (isLast ? "click" : "expand"),
+                status: clickRes.performed ? "PASS" : "FAIL",
+                matchedText: match.matchedText,
+                before: match.snapshot,
+                after: clickRes.after || null,
+                drawerEnsured: drawerState.ensured,
+                retries: attempts,
+            });
+        }
+
+        const currentUrl = this.page.url();
+        const title = await this.page.title().catch(() => "");
+
+        return {
+            acted: true,
+            action: "menuPath",
+            menuPath,
+            target: {
+                frameId: targetFrame.frameId,
+                frameUrl: targetFrame.frame.url(),
+                matchedBy: targetFrame.matchedBy,
+            },
+            steps,
+            currentUrl,
+            title,
+        };
+    }
+
+    async assert(options = {}) {
+        const targetFrame = await this._resolveObserveFrame(options);
+        const previousFrame = this._activeFrame;
+        this._activeFrame = targetFrame.frame === this.page.mainFrame() ? null : targetFrame.frame;
+
+        try {
+            const checks = {};
+            let passed = true;
+
+            if (options.selector) {
+                const elementResult = await this._checkElement({ selector: options.selector, expect: options.expect || {} });
+                checks.element = elementResult;
+                if (!elementResult.passed) passed = false;
+            }
+
+            if (options.urlContains) {
+                const currentUrl = this.page.url();
+                checks.urlContains = { expected: options.urlContains, actual: currentUrl, passed: currentUrl.includes(options.urlContains) };
+                if (!checks.urlContains.passed) passed = false;
+            }
+
+            if (options.textContains) {
+                const textResult = await this.safeEval((text) => {
+                    const bodyText = document.body?.innerText || "";
+                    return { expected: text, passed: bodyText.includes(text) };
+                }, options.textContains);
+                checks.textContains = textResult;
+                if (!textResult.passed) passed = false;
+            }
+
+            return {
+                passed,
+                target: {
+                    frameId: targetFrame.frameId,
+                    frameUrl: targetFrame.frame.url(),
+                    matchedBy: targetFrame.matchedBy,
+                },
+                checks,
+            };
+        } finally {
+            this._activeFrame = previousFrame;
+        }
+    }
+
+    async captureApi(options = {}) {
+        const wait = Number.parseInt(options.wait ?? options.timeout ?? 15000, 10);
+        const includeRequestBody = options.includeRequestBody !== false;
+        const includeResponseBody = Boolean(options.includeResponseBody);
+        const methodFilter = options.method ? String(options.method).toUpperCase() : null;
+        const urlPattern = options.urlPattern || options.urlIncludes || "";
+        const targetFrame = await this._resolveObserveFrame(options).catch(() => null);
+        const requests = new Map();
+        const sessions = [];
+        const targets = [];
+        const pendingBodies = [];
+        const startedAt = Date.now();
+
+        const matchesUrl = (url = "") => !urlPattern || url.includes(urlPattern);
+        const matchesMethod = (method = "") => !methodFilter || method.toUpperCase() === methodFilter;
+        const normalizeHeaders = (headers = {}) => Object.fromEntries(Object.entries(headers).map(([key, value]) => [key, String(value)]));
+
+        const addSession = async (session, targetInfo) => {
+            await session.send("Network.enable").catch(() => null);
+            sessions.push(session);
+            targets.push(targetInfo);
+
+            session.on("Network.requestWillBeSent", (event) => {
+                const request = event.request || {};
+                if (!matchesUrl(request.url) || !matchesMethod(request.method)) return;
+                // 为每条请求记录 frameUrl：关键的是框架帧的 URL，不是发起者 iframe 的 document
+                // event.frameId / event.loaderId 可关联到 Page.frameNavigated 事件
+                requests.set(`${targetInfo.id}:${event.requestId}`, {
+                    id: event.requestId,
+                    targetId: targetInfo.id,
+                    targetType: targetInfo.type,
+                    targetUrl: targetInfo.url,
+                    frameId: event.frameId,
+                    frameUrl: targetInfo.url,  // 请求来源的 frame URL
+                    url: request.url,
+                    method: request.method,
+                    requestHeaders: normalizeHeaders(request.headers),
+                    requestBody: includeRequestBody ? request.postData || null : undefined,
+                    status: null,
+                    responseHeaders: null,
+                    responseBody: null,
+                    responseBodyBase64Encoded: null,
+                    errorText: null,
+                    startTime: Date.now(),
+                    endTime: null,
+                    duration: null,
+                });
+            });
+
+            session.on("Network.responseReceived", (event) => {
+                const item = requests.get(`${targetInfo.id}:${event.requestId}`);
+                if (!item) return;
+                const response = event.response || {};
+                item.status = response.status;
+                item.mimeType = response.mimeType;
+                item.responseHeaders = normalizeHeaders(response.headers);
+                item.responseUrl = response.url;
+            });
+
+            session.on("Network.loadingFinished", async (event) => {
+                const item = requests.get(`${targetInfo.id}:${event.requestId}`);
+                if (!item) return;
+                item.endTime = Date.now();
+                item.duration = item.endTime - item.startTime;
+                if (includeResponseBody) {
+                    const bodyTask = session.send("Network.getResponseBody", { requestId: event.requestId })
+                        .then((body) => {
+                            item.responseBody = body.body;
+                            item.responseBodyBase64Encoded = body.base64Encoded;
+                        })
+                        .catch((err) => {
+                            item.responseBodyError = err.message;
+                        });
+                    pendingBodies.push(bodyTask);
+                }
+            });
+
+            session.on("Network.loadingFailed", (event) => {
+                const item = requests.get(`${targetInfo.id}:${event.requestId}`);
+                if (!item) return;
+                item.endTime = Date.now();
+                item.duration = item.endTime - item.startTime;
+                item.errorText = event.errorText || "loadingFailed";
+            });
+        };
+
+        const pageSession = await this.page.target().createCDPSession();
+        await addSession(pageSession, {
+            id: "page",
+            type: "page",
+            url: this.page.url(),
+            matchedBy: "currentPage",
+        });
+
+        const pageTarget = this.page.target();
+        const pickCandidates = () => this.browser.targets().filter((target) => {
+            if (target === pageTarget) return false;
+            if (!["iframe", "page"].includes(target.type())) return false;
+            const targetUrl = target.url() || "";
+            if (options.targetUrlContains && !targetUrl.includes(options.targetUrlContains)) return false;
+            if (targetFrame?.frame && targetUrl && targetFrame.frame.url() && targetUrl !== targetFrame.frame.url() && !targetUrl.includes(targetFrame.frame.url())) {
+                return options.includeAllTargets === true;
+            }
+            return true;
+        });
+
+        const attachOnce = async (candidates) => {
+            for (const target of candidates) {
+                const session = await target.createCDPSession().catch(() => null);
+                if (!session) continue;
+                await addSession(session, {
+                    id: target.url() || `${target.type()}-${targets.length}`,
+                    type: target.type(),
+                    url: target.url() || "",
+                    matchedBy: "browser.targets",
+                });
+            }
+        };
+
+        // 微前端 wujie/qiankun 时序：iframe target 可能在主页面 ready 后才注册
+        // attach=0 时延迟重试，最多 3 次（含首次）
+        const maxAttachTries = Number.parseInt(options.attachRetries ?? 3, 10);
+        const attachRetryDelay = Number.parseInt(options.attachRetryDelay ?? 1500, 10);
+        let attachCandidates = pickCandidates();
+        let tries = 1;
+        await attachOnce(attachCandidates);
+        const attachLog = [{ try: 1, count: attachCandidates.length }];
+        while (attachCandidates.length === 0 && tries < maxAttachTries) {
+            tries += 1;
+            await new Promise((r) => setTimeout(r, attachRetryDelay));
+            attachCandidates = pickCandidates();
+            attachLog.push({ try: tries, count: attachCandidates.length });
+            await attachOnce(attachCandidates);
+        }
+
+        if (options.reload) {
+            await this.page.reload({ waitUntil: options.waitUntil || "domcontentloaded", timeout: options.reloadTimeout || 30000 }).catch(() => null);
+        }
+
+        await new Promise((resolve) => setTimeout(resolve, wait));
+        await Promise.allSettled(pendingBodies);
+
+        await Promise.all(sessions.map((session) => session.send("Network.disable").catch(() => null)));
+
+        const requestList = Array.from(requests.values()).sort((a, b) => a.startTime - b.startTime);
+        const title = await this.page.title().catch(() => "");
+        const failed = requestList.filter((item) => item.errorText || (item.status && item.status >= 400));
+
+        return {
+            type: "apiCapture",
+            page: {
+                url: this.page.url(),
+                title,
+            },
+            target: targetFrame ? {
+                frameId: targetFrame.frameId,
+                frameUrl: targetFrame.frame.url(),
+                matchedBy: targetFrame.matchedBy,
+            } : null,
+            targets,
+            requests: requestList,
+            summary: {
+                total: requestList.length,
+                success: requestList.length - failed.length,
+                failed: failed.length,
+                targets: targets.length,
+                attachLog,
+                duration: Date.now() - startedAt,
+            },
+        };
+    }
+
+    assertApi(captureResult, options = {}) {
+        if (!captureResult || !Array.isArray(captureResult.requests)) {
+            throw new Error("assertApi requires an apiCapture result");
+        }
+
+        const requests = captureResult.requests;
+        const expect = options.expect || options;
+        const checks = {};
+        let passed = true;
+
+        if (expect.maxFailed !== undefined) {
+            const actual = requests.filter((item) => item.errorText || (item.status && item.status >= 400)).length;
+            checks.maxFailed = {
+                expected: Number.parseInt(expect.maxFailed, 10),
+                actual,
+                passed: actual <= Number.parseInt(expect.maxFailed, 10),
+            };
+            if (!checks.maxFailed.passed) passed = false;
+        }
+
+        if (expect.forbidStatusGte !== undefined) {
+            const threshold = Number.parseInt(expect.forbidStatusGte, 10);
+            const violations = requests
+                .filter((item) => item.status && item.status >= threshold)
+                .map((item) => ({ url: item.url, method: item.method, status: item.status }));
+            checks.forbidStatusGte = {
+                expected: threshold,
+                violations,
+                passed: violations.length === 0,
+            };
+            if (!checks.forbidStatusGte.passed) passed = false;
+        }
+
+        if (expect.requiredUrls !== undefined) {
+            const requiredUrls = Array.isArray(expect.requiredUrls) ? expect.requiredUrls : [expect.requiredUrls];
+            checks.requiredUrls = requiredUrls.map((url) => {
+                const matched = requests.filter((item) => item.url?.includes(url));
+                return {
+                    url,
+                    matched: matched.length,
+                    passed: matched.length > 0,
+                };
+            });
+            if (checks.requiredUrls.some((item) => !item.passed)) passed = false;
+        }
+
+        if (expect.requiredMethods !== undefined) {
+            const requiredMethods = Array.isArray(expect.requiredMethods) ? expect.requiredMethods : [expect.requiredMethods];
+            checks.requiredMethods = requiredMethods.map((method) => {
+                const normalized = String(method).toUpperCase();
+                const matched = requests.filter((item) => item.method === normalized);
+                return {
+                    method: normalized,
+                    matched: matched.length,
+                    passed: matched.length > 0,
+                };
+            });
+            if (checks.requiredMethods.some((item) => !item.passed)) passed = false;
+        }
+
+        if (expect.minTotal !== undefined) {
+            const expected = Number.parseInt(expect.minTotal, 10);
+            checks.minTotal = {
+                expected,
+                actual: requests.length,
+                passed: requests.length >= expected,
+            };
+            if (!checks.minTotal.passed) passed = false;
+        }
+
+        return {
+            type: "assertApi",
+            passed,
+            checks,
+            summary: captureResult?.summary || {
+                total: requests.length,
+                failed: requests.filter((item) => item.errorText || (item.status && item.status >= 400)).length,
+            },
+        };
+    }
+
+    async _resolveObserveFrame(options = {}) {
+        // testCase setup 已预定位 iframe，且调用方未显式传 frame 参数 → 直接复用
+        if (this._activeFrame && options.frameIndex === undefined && !options.frameUrlContains && !options.frameContentContains) {
+            const frames = this.page.frames();
+            const idx = frames.indexOf(this._activeFrame);
+            if (idx >= 0) {
+                return { frame: this._activeFrame, frameId: idx === 0 ? "main" : `frame-${idx}`, matchedBy: "activeFrame (from testCase setup)" };
+            }
+        }
+
+        const frames = this.page.frames();
+        const mainFrame = this.page.mainFrame();
+
+        if (options.frameIndex !== undefined) {
+            const index = Number.parseInt(options.frameIndex, 10);
+            if (frames[index]) {
+                return { frame: frames[index], frameId: index === 0 ? "main" : `frame-${index}`, matchedBy: `frameIndex ${index}` };
+            }
+        }
+
+        if (options.frameUrlContains) {
+            const index = frames.findIndex((frame) => frame.url().includes(options.frameUrlContains));
+            if (index >= 0) {
+                return { frame: frames[index], frameId: index === 0 ? "main" : `frame-${index}`, matchedBy: `url contains "${options.frameUrlContains}"` };
+            }
+        }
+
+        if (options.frameContentContains) {
+            for (let i = 0; i < frames.length; i++) {
+                const matched = await frames[i].evaluate((text) =>
+                    document.body?.innerText?.includes(text) || false,
+                    options.frameContentContains
+                ).catch(() => false);
+                if (matched) {
+                    return { frame: frames[i], frameId: i === 0 ? "main" : `frame-${i}`, matchedBy: `body contains "${options.frameContentContains}"` };
+                }
+            }
+        }
+
+        // 无显式 frame 参数时：WebComponent 模式默认用 sandbox iframe（含子应用实际 DOM）
+        if (this._wujieContext?.type === 'webcomponent' && frames.length > 1) {
+            const sandboxIdx = frames.findIndex((f) => f !== mainFrame && !f.url().startsWith('about:'));
+            if (sandboxIdx >= 0) {
+                return { frame: frames[sandboxIdx], frameId: `frame-${sandboxIdx}`, matchedBy: 'webcomponent sandbox iframe' };
+            }
+        }
+
+        const mainIndex = frames.indexOf(mainFrame);
+        return { frame: mainFrame, frameId: mainIndex <= 0 ? "main" : `frame-${mainIndex}`, matchedBy: "main" };
+    }
+
+    async _getFrameSummaries() {
+        const frames = this.page.frames();
+        const mainFrame = this.page.mainFrame();
+        const summaries = [];
+        for (let i = 0; i < frames.length; i++) {
+            const frame = frames[i];
+            const title = await frame.evaluate(() => document.title || "").catch(() => "");
+            summaries.push({
+                frameId: frame === mainFrame ? "main" : `frame-${i}`,
+                url: frame.url(),
+                title,
+                isMain: frame === mainFrame,
+            });
+        }
+        return summaries;
+    }
+
+    async _buildDomTree(frame, selector, depth) {
+        return frame.evaluate((rootSelector, maxDepth) => {
+            function attrsOf(el) {
+                const attrs = {};
+                for (const attr of Array.from(el.attributes || [])) {
+                    if (["id", "class", "role", "aria-label", "title", "placeholder", "href", "src", "data-testid"].includes(attr.name)) {
+                        attrs[attr.name] = attr.value.slice(0, 120);
+                    }
+                }
+                return attrs;
+            }
+
+            function directTextOf(el) {
+                return Array.from(el.childNodes || [])
+                    .filter((node) => node.nodeType === Node.TEXT_NODE)
+                    .map((node) => node.textContent.trim())
+                    .filter(Boolean)
+                    .join(" ")
+                    .slice(0, 120);
+            }
+
+            function build(el, currentDepth) {
+                if (!el || currentDepth > maxDepth) return null;
+                const tag = el.tagName?.toLowerCase();
+                if (!tag || ["script", "style", "path"].includes(tag)) return null;
+                const rect = el.getBoundingClientRect();
+                const node = {
+                    tag,
+                    attrs: attrsOf(el),
+                    text: directTextOf(el),
+                    visible: rect.width > 0 && rect.height > 0,
+                    children: [],
+                };
+                for (const child of Array.from(el.children || [])) {
+                    const childNode = build(child, currentDepth + 1);
+                    if (childNode) node.children.push(childNode);
+                }
+                return node;
+            }
+
+            return build(document.querySelector(rootSelector) || document.body, 0);
+        }, selector, depth).catch((err) => ({ error: err.message, tag: "error", attrs: {}, text: "", visible: false, children: [] }));
+    }
+
+    async _collectInteractiveElements(frame, frameId, maxElements) {
+        return frame.evaluate((currentFrameId, limit) => {
+            function cssEscape(value) {
+                if (window.CSS?.escape) return window.CSS.escape(value);
+                return String(value).replace(/["'\\]/g, "\\$&");
+            }
+
+            function getText(el) {
+                return (el.innerText || el.textContent || "").replace(/\s+/g, " ").trim().slice(0, 120);
+            }
+
+            function getName(el, text) {
+                return (
+                    el.getAttribute("aria-label") ||
+                    el.getAttribute("title") ||
+                    el.getAttribute("placeholder") ||
+                    el.getAttribute("alt") ||
+                    text ||
+                    ""
+                ).slice(0, 120);
+            }
+
+            function roleOf(el) {
+                const explicit = el.getAttribute("role");
+                if (explicit) return explicit;
+                const tag = el.tagName.toLowerCase();
+                if (tag === "button") return "button";
+                if (tag === "a") return "link";
+                if (["input", "textarea"].includes(tag)) return "textbox";
+                if (tag === "select") return "combobox";
+                return "generic";
+            }
+
+            function selectorCandidates(el, role, name, text) {
+                const selectors = [];
+                const testId = el.getAttribute("data-testid");
+                if (testId) selectors.push(`[data-testid="${cssEscape(testId)}"]`);
+                if (el.id) selectors.push(`#${cssEscape(el.id)}`);
+                if (role && role !== "generic" && name) selectors.push(`role=${role}[name="${name.replace(/"/g, "\\\"")}"]`);
+                if (text) selectors.push(`text=${text.replace(/"/g, "\\\"")}`);
+                const tag = el.tagName.toLowerCase();
+                const className = typeof el.className === "string" ? el.className.trim().split(/\s+/).filter(Boolean)[0] : "";
+                if (className) selectors.push(`${tag}.${cssEscape(className)}`);
+                selectors.push(tag);
+                return [...new Set(selectors)].slice(0, 5);
+            }
+
+            function isCandidate(el) {
+                const tag = el.tagName.toLowerCase();
+                return ["a", "button", "input", "select", "textarea", "summary"].includes(tag) ||
+                    el.getAttribute("role") ||
+                    el.getAttribute("tabindex") !== null ||
+                    el.onclick ||
+                    el.getAttribute("data-testid") ||
+                    (typeof el.className === "string" && /btn|button|menu-item|ant-btn|ant-menu|ant-select|ant-input/.test(el.className));
+            }
+
+            const viewportWidth = window.innerWidth || document.documentElement.clientWidth;
+            const viewportHeight = window.innerHeight || document.documentElement.clientHeight;
+            return Array.from(document.querySelectorAll("a,button,input,select,textarea,summary,[role],[tabindex],[data-testid],[class*='btn'],[class*='button'],[class*='menu-item'],[class*='ant-btn'],[class*='ant-menu'],[class*='ant-select'],[class*='ant-input']"))
+                .filter(isCandidate)
+                .slice(0, limit)
+                .map((el, idx) => {
+                    const rect = el.getBoundingClientRect();
+                    const style = window.getComputedStyle(el);
+                    const text = getText(el);
+                    const role = roleOf(el);
+                    const name = getName(el, text);
+                    const visible = rect.width > 0 && rect.height > 0 && style.visibility !== "hidden" && style.display !== "none";
+                    return {
+                        index: idx + 1,
+                        frameId: currentFrameId,
+                        tag: el.tagName.toLowerCase(),
+                        role,
+                        name,
+                        text,
+                        selectorCandidates: selectorCandidates(el, role, name, text),
+                        bbox: {
+                            x: Math.round(rect.x),
+                            y: Math.round(rect.y),
+                            width: Math.round(rect.width),
+                            height: Math.round(rect.height),
+                        },
+                        state: {
+                            visible,
+                            enabled: !el.disabled && el.getAttribute("aria-disabled") !== "true",
+                            inViewport: rect.bottom >= 0 && rect.right >= 0 && rect.top <= viewportHeight && rect.left <= viewportWidth,
+                        },
+                    };
+                });
+        }, frameId, maxElements).catch(() => []);
+    }
+
+    /**
+     * 步骤分发
+     */
+    async _dispatchStep(step, context) {
+        switch (step.type) {
+            case "observe":      return this.observe(step);
+            case "act":          return this.act(step);
+            case "assert":       return this.assert(step);
+            case "apiCapture":   return this.captureApi(step);
+            case "api-capture":  return this.captureApi(step);
+            case "assertApi":    return this.assertApi(step.captureResult || context.lastApiCapture, step);
+            case "assert-api":   return this.assertApi(step.captureResult || context.lastApiCapture, step);
+            case "navigate":     return this._navigate(step);
+            case "screenshot":   return this._screenshot(step, context);
+            case "compare":      return this._compare(step, context);
+            case "click":        return this._click(step);
+            case "type":         return this._type(step);
+            case "waitFor":      return this._waitFor(step);
+            case "evaluate":     return this._evaluate(step);
+            case "checkElement": return this._checkElement(step);
+            case "findPage":     return this._findPage(step);
+            case "findFrame":    return this._findFrame(step);
+            case "loginWait":    return this._loginWait(step);
+            case "aiAssert":     return this._aiAssert(step, context);
+            case "runTask":      return this.runTask(step, context);
+            case "run-task":     return this.runTask(step, context);
+            // ===== Ant Design 适配层（6/22 反馈落地） =====
+            case "antSelect":    return this._antSelect(step);
+            case "antTreeSelect":return this._antTreeSelect(step);
+            case "antInput":     return this._antInput(step);
+            case "antRadio":     return this._antRadio(step);
+            case "antCheckbox":  return this._antCheckbox(step);
+            case "antSwitch":    return this._antSwitch(step);
+            case "antDatePicker":return this._antDatePicker(step);
+            case "antCascader":  return this._antCascader(step);
+            case "antUpload":    return this._antUpload(step);
+            case "formFill":     return this._formFill(step);
+            case "closeAllDropdowns": return this._closeAllDropdowns(step);
+            // ===== 语义断言层 =====
+            case "expect":       return this._expect(step);
+            default:
+                throw new Error(`Unknown step type: ${step.type}`);
+        }
+    }
+
+    /**
+     * 解析目标 frame，优先级（微前端场景兼容）：
+     *   1. step 显式传 frameContentContains / frameUrlContains / frameIndex → 用 _resolveObserveFrame
+     *   2. 已有 _activeFrame（来自 setup.findFrame / 上一步 findFrame）→ 直接复用
+     *   3. 否则回退到 mainFrame
+     *
+     * 同时做"frame 探活 + 自动召回"：如果 _activeFrame 因子应用卸载而失效，
+     * 自动清空并回退到 mainFrame，避免无限挂在已销毁的 frame 上。
+     *
+     * @returns {Promise<{frame, frameId, matchedBy, frameRecovered?}>} 含 frameRecovered 标志
+     */
+    async _getTargetFrame(step) {
+        const hasExplicitFrame = step && (step.frameContentContains || step.frameUrlContains || step.frameIndex !== undefined);
+
+        // 路径 1：显式指定 frame → 总是用 _resolveObserveFrame
+        if (hasExplicitFrame) {
+            const resolved = await this._resolveObserveFrame(step);
+            return { frame: resolved.frame, frameId: resolved.frameId, matchedBy: resolved.matchedBy, frameRecovered: false };
+        }
+
+        // 路径 2：复用 _activeFrame（微前端场景的核心优化）
+        if (this._activeFrame) {
+            // 探活：确认 frame 还能 evaluate（未被子应用卸载）
+            const alive = await this._activeFrame.evaluate(() => true).catch(() => false);
+            if (alive) {
+                return { frame: this._activeFrame, frameId: "active", matchedBy: "_activeFrame", frameRecovered: false };
+            }
+            // 失活：清空 _activeFrame，召回到 mainFrame
+            this._activeFrame = null;
+            return { frame: this.page.mainFrame(), frameId: "main", matchedBy: "_activeFrame failed, fallback to main", frameRecovered: true };
+        }
+
+        // 路径 3：mainFrame
+        const resolved = await this._resolveObserveFrame(step || {});
+        return { frame: resolved.frame, frameId: resolved.frameId, matchedBy: resolved.matchedBy, frameRecovered: false };
+    }
+
+    async _antSelect(step) {
+        const { frame } = await this._getTargetFrame(step);
+        const adapter = this._getAdapter(step.componentMeta);
+        let result = await adapter.select(frame, step.field || step.label, step.option || step.value, {
+            mode: step.mode,
+            timeout: step.timeout,
+        });
+
+        // 微前端跨 frame 浮层兜底：
+        // 如果当前 frame 未找到浮层选项（getPopupContainer 指向主文档），尝试主 frame
+        if (!result.acted && result.reason?.includes?.("not found in dropdown")) {
+            const mainFrame = this.page.mainFrame();
+            if (mainFrame !== frame) {
+                const retry = await adapter.select(mainFrame, step.field || step.label, step.option || step.value, {
+                    mode: step.mode,
+                    timeout: step.timeout,
+                });
+                if (retry.acted) {
+                    result = retry;
+                    result._dropdownFrame = "main";
+                }
+            }
+        }
+
+        this._lastActWasDropdown = true;
+        return { type: "antSelect", passed: result.acted && result.verified !== false, ...result };
+    }
+
+    async _antTreeSelect(step) {
+        const { frame } = await this._getTargetFrame(step);
+        const adapter = this._getAdapter(step.componentMeta);
+        let result = await adapter.treeSelect(frame, step.field || step.label, step.path || step.value, {
+            timeout: step.timeout,
+        });
+
+        // 微前端跨 frame 浮层兜底：同上
+        if (!result.acted && result.reason?.includes?.("node")) {
+            const mainFrame = this.page.mainFrame();
+            if (mainFrame !== frame) {
+                const retry = await adapter.treeSelect(mainFrame, step.field || step.label, step.path || step.value, { timeout: step.timeout });
+                if (retry.acted) {
+                    result = retry;
+                    result._dropdownFrame = "main";
+                }
+            }
+        }
+
+        this._lastActWasDropdown = true;
+        return { type: "antTreeSelect", passed: result.acted && result.verified !== false, ...result };
+    }
+
+    async _antInput(step) {
+        const { frame } = await this._getTargetFrame(step);
+        const adapter = this._getAdapter(step.componentMeta);
+        const target = step.placeholder
+            ? { placeholder: step.placeholder }
+            : step.selector
+                ? { selector: step.selector }
+                : { label: step.field || step.label };
+        const result = await adapter.input(frame, target, step.value, { clear: step.clear });
+        return { type: "antInput", passed: result.acted, ...result };
+    }
+
+    async _antRadio(step) {
+        const { frame } = await this._getTargetFrame(step);
+        const adapter = this._getAdapter(step.componentMeta);
+        const result = await adapter.radio(frame, step.field || step.label, step.option || step.value);
+        return { type: "antRadio", passed: result.acted && result.verified, ...result };
+    }
+
+    async _antCheckbox(step) {
+        const { frame } = await this._getTargetFrame(step);
+        const adapter = this._getAdapter(step.componentMeta);
+        const result = await adapter.checkbox(frame, step.field || step.label, step.option, step.checked !== false);
+        return { type: "antCheckbox", passed: result.acted && result.verified, ...result };
+    }
+
+    async _antSwitch(step) {
+        const { frame } = await this._getTargetFrame(step);
+        const adapter = this._getAdapter(step.componentMeta);
+        const result = await adapter.switch(frame, step.field || step.label, step.on !== false);
+        return { type: "antSwitch", passed: result.acted && result.verified, ...result };
+    }
+
+    async _antDatePicker(step) {
+        const { frame } = await this._getTargetFrame(step);
+        const adapter = this._getAdapter(step.componentMeta);
+        const result = await adapter.datePicker(frame, step.field || step.label, step.value);
+        this._lastActWasDropdown = true;
+        return { type: "antDatePicker", passed: result.acted, ...result };
+    }
+
+    async _antCascader(step) {
+        const { frame } = await this._getTargetFrame(step);
+        const adapter = this._getAdapter(step.componentMeta);
+        const result = await adapter.cascader(frame, step.field || step.label, step.path || step.value, { timeout: step.timeout });
+        this._lastActWasDropdown = true;
+        return { type: "antCascader", passed: result.acted, ...result };
+    }
+
+    async _antUpload(step) {
+        const { frame } = await this._getTargetFrame(step);
+        const adapter = this._getAdapter(step.componentMeta);
+        const result = await adapter.upload(frame, step.field || step.label, step.filePath || step.value);
+        return { type: "antUpload", passed: result.acted, ...result };
+    }
+
+    async _formFill(step) {
+        const { frame } = await this._getTargetFrame(step);
+        const adapter = this._getAdapter(step.componentMeta);
+        const result = await adapter.formFill(frame, step.fields || [], { stepDelay: step.stepDelay });
+        const allOk = result.summary.failed === 0;
+        // 校验：可选地立即跑表单校验
+        if (step.validateAfter) {
+            const exp = createExpect({ frame, page: this.page });
+            const validation = await exp.validation().toPass({ timeout: step.validationTimeout ?? 2000 });
+            return {
+                type: "formFill",
+                passed: allOk && validation.passed,
+                ...result,
+                validation,
+            };
+        }
+        return { type: "formFill", passed: allOk, ...result };
+    }
+
+    async _closeAllDropdowns(step) {
+        const { frame } = await this._getTargetFrame(step || {});
+        const adapter = this._getAdapter();
+        // 微前端场景：同时清理主 frame 和所有子 frame 的浮层（修复 2 配套）
+        const result = await this._closeDropdownsAllFrames(frame);
+        this._lastActWasDropdown = false;
+        return { type: "closeAllDropdowns", passed: true, ...result };
+    }
+
+    /**
+     * 修复 2：跨 frame 浮层检测 — Ant 浮层可能渲染在子应用 iframe 内或父应用 document.body
+     * 同时清理当前 frame + 主 frame + 所有可访问子 frame 的浮层
+     */
+    async _closeDropdownsAllFrames(currentFrame) {
+        const adapter = this._getAdapter();
+        const mainFrame = this.page.mainFrame();
+        const allFrames = this.page.frames();
+        const closed = { perFrame: [], total: 0 };
+
+        // 优先清理当前 frame
+        const framesToClose = new Set([currentFrame, mainFrame, ...allFrames]);
+        for (const frame of framesToClose) {
+            try {
+                // 探活
+                const alive = await frame.evaluate(() => true).catch(() => false);
+                if (!alive) continue;
+                const r = await adapter.closeAllDropdowns(frame);
+                if (r?.closed) {
+                    closed.total += r.closed;
+                    closed.perFrame.push({ frameUrl: frame.url().slice(0, 100), closed: r.closed });
+                }
+            } catch {
+                // 跨域 iframe 无法 evaluate，跳过
+            }
+        }
+        return closed;
+    }
+
+    /**
+     * 通用 expect 断言：根据 step.assertion 路由到 expect.js 的不同断言方法
+     *
+     * 支持的 assertion：
+     *   - "locator.toBeVisible" / "toBeHidden" / "toBeEnabled" / "toHaveText" / "toHaveValue" / "toHaveCount" / "toHaveAttribute"
+     *   - "validation.toPass" / "validation.toHaveError"
+     *   - "url.toContain" / "url.toMatch"
+     *   - "api.toAllPass" / "api.toInclude" / "api.toHaveCount"
+     */
+    async _expect(step) {
+        const assertion = step.assertion;
+        const opts = { timeout: step.timeout, interval: step.interval };
+
+        if (!assertion) throw new Error("expect step requires assertion field");
+
+        // locator.* 系列
+        if (assertion.startsWith("locator.") || assertion.startsWith("toBe") || assertion.startsWith("toHave")) {
+            const { frame } = await this._getTargetFrame(step);
+            const loc = expectLocator(frame, step.selector);
+            const method = assertion.replace(/^locator\./, "");
+            if (typeof loc[method] !== "function") {
+                throw new Error(`Unknown locator assertion: ${method}`);
+            }
+            // toHaveText/toHaveValue/toHaveAttribute/toHaveCount 需要 expected 参数
+            const expected = step.expected ?? step.value ?? step.text ?? step.count;
+            const r = method === "toHaveAttribute"
+                ? await loc.toHaveAttribute(step.name, expected, opts)
+                : (expected !== undefined ? await loc[method](expected, opts) : await loc[method](opts));
+            return { type: "expect", ...r };
+        }
+
+        // validation.*
+        if (assertion.startsWith("validation.")) {
+            const { frame } = await this._getTargetFrame(step);
+            const val = expectValidation(frame);
+            const method = assertion.replace("validation.", "");
+            const r = method === "toHaveError"
+                ? await val.toHaveError(step.field || step.message, opts)
+                : await val.toPass(opts);
+            return { type: "expect", ...r };
+        }
+
+        // url.*
+        if (assertion.startsWith("url.")) {
+            const u = expectUrl(this.page);
+            const method = assertion.replace("url.", "");
+            const r = method === "toMatch"
+                ? await u.toMatch(step.regex || step.pattern, opts)
+                : await u.toContain(step.value || step.contains, opts);
+            return { type: "expect", ...r };
+        }
+
+        // api.*
+        if (assertion.startsWith("api.")) {
+            const capture = step.captureResult || this._lastApiCapture;
+            // 微前端：支持按 frame 范围过滤请求
+            // scope: "all"（默认，全 page）/ "current-frame"（仅 _activeFrame 同源）
+            let frameUrlContains = step.frameUrlContains;
+            if (!frameUrlContains && step.scope === "current-frame" && this._activeFrame) {
+                const url = this._activeFrame.url();
+                // blob: URL（wujie 子应用）取冒号后面的部分；http(s): URL 取 origin
+                if (url.startsWith("blob:")) {
+                    try { frameUrlContains = new URL(url.slice(5)).origin; } catch {}
+                } else {
+                    try { frameUrlContains = new URL(url).origin; } catch {}
+                }
+            }
+            const a = expectApi(capture, { scope: step.scope || "all", frameUrlContains });
+            const method = assertion.replace("api.", "");
+            if (typeof a[method] !== "function") {
+                throw new Error(`Unknown api assertion: ${method}`);
+            }
+            const r = method === "toInclude"
+                ? a.toInclude(step.urlPattern || step.pattern)
+                : method === "toHaveCount"
+                    ? a.toHaveCount(step.expected ?? step.count)
+                    : a[method]();
+            return { type: "expect", ...r };
+        }
+
+        throw new Error(`Unknown expect assertion: ${assertion}`);
+    }
+
+    async _navigate(step) {
+        const start = Date.now();
+        // 微前端/SSO 重定向链场景：用 domcontentloaded 避免 page 对象被销毁
+        const waitUntil = step.waitUntil || (step.allowRedirects ? "domcontentloaded" : "networkidle2");
+        try {
+            await this.page.goto(step.url, {
+                waitUntil,
+                timeout: step.timeout || 30000,
+            });
+        } catch (err) {
+            // 重定向链可能触发超时，但页面可能已加载
+            if (err.name === "TimeoutError" && step.allowRedirects) {
+                // 忽略超时，页面可能正在重定向中
+            } else {
+                throw err;
+            }
+        }
+        // 重定向后等待页面稳定
+        if (step.allowRedirects) {
+            await new Promise((r) => setTimeout(r, step.redirectWait || 5000));
+        }
+        const title = await this.safeEval(() => document.title).catch(() => "");
+        return {
+            url: this.page.url(),
+            title,
+            loadTime: Date.now() - start,
+        };
+    }
+
+    async _screenshot(step, context) {
+        const fs = await import("node:fs");
+        const path = await import("node:path");
+        const outputDir = context.outputDir || "/tmp";
+        if (!fs.existsSync(outputDir)) {
+            fs.mkdirSync(outputDir, { recursive: true });
+        }
+
+        const filename = step.filename || `screenshot-${Date.now()}.png`;
+        const filepath = path.join(outputDir, filename);
+
+        await this.page.screenshot({
+            path: filepath,
+            fullPage: step.fullPage !== false,
+            ...(step.clip ? { clip: step.clip } : {}),
+        });
+
+        const viewport = this.page.viewport();
+        return { filepath, width: viewport.width, height: viewport.height };
+    }
+
+    async _compare(step, context) {
+        const { compareDesign } = await import("./visual-compare.js");
+        const fs = await import("node:fs");
+        const path = await import("node:path");
+        const outputDir = context.outputDir || "/tmp";
+
+        // 先截图
+        if (!fs.existsSync(outputDir)) {
+            fs.mkdirSync(outputDir, { recursive: true });
+        }
+        const screenshotPath = path.join(outputDir, `compare-screenshot-${Date.now()}.png`);
+        await this.page.screenshot({ path: screenshotPath, fullPage: true });
+
+        // 执行对比
+        const result = await compareDesign(screenshotPath, step.designImagePath, {
+            threshold: step.threshold,
+            outputDir,
+            regions: step.regions,
+            page: this.page,
+        });
+
+        return result;
+    }
+
+    async _click(step) {
+        const target = this._activeFrame || this.page;
+        const selector = this._resolveSelector(step.selector);
+
+        // iframe 内使用 evaluate 点击（坐标点击无法到达 iframe 内容）
+        if (this._activeFrame) {
+            const clicked = await this.safeEval((sel) => {
+                const el = document.querySelector(sel);
+                if (!el) return { found: false };
+                el.click();
+                return { found: true, tagName: el.tagName };
+            }, selector);
+            if (!clicked.found) {
+                // 回退：模糊匹配
+                const fuzzyResult = await this.safeEval((sel) => {
+                    const base = sel.replace(/\[class\*="([^"]+)"\]/, "$1").replace(/[.#]/, "");
+                    const el = [...document.querySelectorAll("*")].find(e =>
+                        (e.className || "").includes(base)
+                    );
+                    if (el) { el.click(); return { found: true, tagName: el.tagName, matchedClass: el.className } ; }
+                    return { found: false };
+                }, selector);
+                if (!fuzzyResult.found) throw new Error(`Element not found in frame: ${selector}`);
+                return { clicked: true, selector, ...fuzzyResult, fuzzyMatch: true };
+            }
+            return { clicked: true, selector, ...clicked };
+        }
+
+        // 主页面：标准 puppeteer 点击
+        await target.waitForSelector(selector, { timeout: step.timeout || 5000 }).catch(() => {});
+        if (step.waitForNavigation) {
+            await Promise.all([
+                this.page.waitForNavigation({ timeout: 10000 }),
+                target.click(selector),
+            ]);
+        } else {
+            await target.click(selector);
+        }
+        const tagName = await target.$eval(selector, (el) => el.tagName).catch(() => "unknown");
+        return { clicked: true, selector, tagName };
+    }
+
+    async _type(step) {
+        const target = this._activeFrame || this.page;
+        const selector = this._resolveSelector(step.selector);
+        await target.waitForSelector(selector, { timeout: step.timeout || 5000 });
+
+        if (step.clear) {
+            await target.click(selector, { clickCount: 3 });
+        }
+
+        await target.type(selector, step.text);
+        const value = await target.$eval(selector, (el) => el.value).catch(() => "");
+        return { typed: true, selector, value };
+    }
+
+    async _waitFor(step) {
+        const timeout = step.timeout || 10000;
+
+        if (step.selector) {
+            await this.page.waitForSelector(step.selector, { timeout });
+            return { matched: true, type: "selector", value: step.selector };
+        }
+
+        if (step.url) {
+            await this.page.waitForResponse(
+                (r) => r.url().includes(step.url),
+                { timeout }
+            );
+            return { matched: true, type: "url", value: step.url };
+        }
+
+        throw new Error("waitFor requires either 'selector' or 'url'");
+    }
+
+    async _evaluate(step) {
+        const result = await this.safeEval(step.expression);
+        return { result };
+    }
+
+    /**
+     * 查找微前端 iframe（wujie/qiankun/single-spa 等）
+     */
+    async _findFrame(step) {
+        const frames = this.page.frames();
+        let matched = null;
+        let matchReason = "";
+
+        if (step.urlIncludes) {
+            matched = frames.find((f) => f.url().includes(step.urlIncludes));
+            if (matched) matchReason = `url contains "${step.urlIncludes}"`;
+        } else if (step.urlRegex) {
+            const re = new RegExp(step.urlRegex);
+            matched = frames.find((f) => re.test(f.url()));
+            if (matched) matchReason = `url matches /${step.urlRegex}/`;
+        } else if (step.titleIncludes) {
+            // 按页面标题查找 iframe
+            for (const f of frames) {
+                try {
+                    const title = await f.evaluate(() => document.title).catch(() => "");
+                    if (title && title.includes(step.titleIncludes)) {
+                        matched = f;
+                        matchReason = `title contains "${step.titleIncludes}"`;
+                        break;
+                    }
+                } catch { /* context destroyed, skip */ }
+            }
+        } else if (step.contentIncludes) {
+            // 按页面内容查找 iframe（查找包含指定文本的 iframe）
+            for (const f of frames) {
+                try {
+                    const has = await f.evaluate((text) =>
+                        document.body?.innerText?.includes(text) || false,
+                        step.contentIncludes
+                    ).catch(() => false);
+                    if (has) {
+                        matched = f;
+                        matchReason = `body contains "${step.contentIncludes}"`;
+                        break;
+                    }
+                } catch { /* context destroyed, skip */ }
+            }
+        } else if (step.frameIndex !== undefined) {
+            matched = frames[step.frameIndex];
+            if (matched) matchReason = `frameIndex ${step.frameIndex}`;
+        }
+
+        if (!matched) {
+            // 收集各 frame 的标题以便调试
+            const frameInfos = [];
+            for (const f of frames) {
+                try {
+                    const title = await f.evaluate(() => document.title).catch(() => "");
+                    frameInfos.push({ url: f.url(), title: title || "(empty)" });
+                } catch {
+                    frameInfos.push({ url: f.url(), title: "(error)" });
+                }
+            }
+            return {
+                found: false,
+                totalFrames: frames.length,
+                frames: frameInfos,
+                error: "No matching frame found",
+            };
+        }
+
+        this._activeFrame = matched;
+        return {
+            found: true,
+            frameUrl: matched.url(),
+            matchedBy: matchReason,
+            totalFrames: frames.length,
+        };
+    }
+
+    /**
+     * 查找已打开的标签页（connect 模式，端口可变场景）
+     */
+    async _findPage(step) {
+        const pages = await this._safeGetPages();
+        let matched = null;
+        let matchReason = "";
+
+        if (step.urlIncludes) {
+            matched = pages.find((p) => p.url().includes(step.urlIncludes));
+            if (matched) matchReason = `url contains "${step.urlIncludes}"`;
+        } else if (step.urlRegex) {
+            const re = new RegExp(step.urlRegex);
+            matched = pages.find((p) => re.test(p.url()));
+            if (matched) matchReason = `url matches /${step.urlRegex}/`;
+        } else if (step.titleIncludes) {
+            for (const p of pages) {
+                try {
+                    const title = await p.title();
+                    if (title && title.includes(step.titleIncludes)) {
+                        matched = p;
+                        matchReason = `title contains "${step.titleIncludes}"`;
+                        break;
+                    }
+                } catch { /* page may be closed */ }
+            }
+        }
+
+        if (!matched) {
+            const pageInfos = await Promise.all(
+                pages.map(async (p) => {
+                    try {
+                        return { url: p.url(), title: (await p.title()) || "(empty)" };
+                    } catch {
+                        return { url: p.url(), title: "(error)" };
+                    }
+                })
+            );
+            return {
+                found: false,
+                totalPages: pages.length,
+                pages: pageInfos,
+                error: "No matching page/tab found",
+            };
+        }
+
+        this.page = matched;
+        this._activeFrame = null; // 重置 frame 上下文
+        if (step.viewport) {
+            await this.page.setViewport(step.viewport);
+        }
+        return {
+            found: true,
+            url: matched.url(),
+            title: await matched.title().catch(() => ""),
+            matchedBy: matchReason,
+            totalPages: pages.length,
+        };
+    }
+
+    /**
+     * 等待登录完成（SSO 重定向场景）
+     * 轮询检测登录页是否消失
+     */
+    async _loginWait(step) {
+        const timeout = step.timeout || 120000;
+        const interval = step.interval || 3000;
+        const loginSelector = step.loginSelector || 'input[type="password"]';
+        const startTime = Date.now();
+
+        // 检测当前是否在登录页
+        const isLoginPage = async () => {
+            return this.safeEval((sel) => !!document.querySelector(sel), loginSelector).catch(() => false);
+        };
+
+        let loggedIn = !(await isLoginPage());
+        while (!loggedIn && Date.now() - startTime < timeout) {
+            await new Promise((r) => setTimeout(r, interval));
+            loggedIn = !(await isLoginPage());
+        }
+
+        const elapsed = Date.now() - startTime;
+        if (!loggedIn) {
+            return { loggedIn: false, elapsed, error: "Login timeout" };
+        }
+
+        // 登录后等待页面稳定
+        await new Promise((r) => setTimeout(r, step.postLoginWait || 5000));
+        return {
+            loggedIn: true,
+            elapsed,
+            currentUrl: this.page.url(),
+        };
+    }
+
+    async _checkElement(step) {
+        const selector = this._resolveSelector(step.selector);
+        const expect = step.expect || {};
+
+        // 在 frame 内使用 safeEval，主页面也使用 safeEval 防止 context destroyed
+        const info = await this.safeEval((sel) => {
+            // 支持 CSS Modules 模糊匹配：[class*=xxx]
+            const els = document.querySelectorAll(sel);
+            return {
+                count: els.length,
+                visible: els.length > 0 && els[0].offsetParent !== null,
+                texts: Array.from(els).slice(0, 5).map((el) =>
+                    el.textContent?.substring(0, 100) || ""
+                ),
+            };
+        }, selector);
+
+        let passed = true;
+        const checks = {};
+
+        if (expect.visible !== undefined) {
+            checks.visible = { expected: expect.visible, actual: info.visible };
+            if (info.visible !== expect.visible) passed = false;
+        }
+
+        if (expect.minCount !== undefined) {
+            checks.minCount = { expected: expect.minCount, actual: info.count };
+            if (info.count < expect.minCount) passed = false;
+        }
+
+        if (expect.maxCount !== undefined) {
+            checks.maxCount = { expected: expect.maxCount, actual: info.count };
+            if (info.count > expect.maxCount) passed = false;
+        }
+
+        if (expect.hasText !== undefined) {
+            const allText = info.texts.join(" ");
+            checks.hasText = { expected: expect.hasText, actual: allText };
+            if (!allText.includes(expect.hasText)) passed = false;
+        }
+
+        return {
+            passed,
+            selector,
+            checks,
+            elementCount: info.count,
+            visible: info.visible,
+        };
+    }
+
+    /**
+     * 解析选择器：自动处理 CSS Modules 哈希类名
+     * 如果 selector 以 ~ 开头，转换为 [class*=xxx] 模糊匹配
+     */
+    /**
+     * AI 语义断言：截图并标记需要视觉审查
+     * 执行器只负责截图，判断由 Agent 或 MCP 服务端 VLM 完成
+     */
+    async _aiAssert(step, context) {
+        const fs = await import("node:fs");
+        const path = await import("node:path");
+        const outputDir = context.outputDir || "/tmp";
+        if (!fs.existsSync(outputDir)) {
+            fs.mkdirSync(outputDir, { recursive: true });
+        }
+
+        const filename = step.filename || `ai-assert-${Date.now()}.png`;
+        const filepath = path.join(outputDir, filename);
+
+        await this.page.screenshot({
+            path: filepath,
+            fullPage: step.fullPage !== false,
+        });
+
+        return {
+            screenshotPath: filepath,
+            assertion: step.assertion,
+            needsVisualReview: true,
+            reviewHint: "请通过以下方式验证此截图：\n" +
+                "1. 如果你能读取图片 → 直接查看截图文件判断是否满足断言\n" +
+                "2. 如果 MCP 服务器可用 → 上传截图后调用 assert_page_screenshot 工具\n" +
+                "3. 降级方案 → 使用 checkElement 步骤做 DOM 级替代验证",
+        };
+    }
+
+    /**
+     * 高层 runner：把"批量探索动态菜单 + 抓接口 + 出报告"打包成一个 step。
+     * 当前仅支持 task='menu-api-scan'，对应反馈中"129 路由全覆盖"场景。
+     *
+     * options:
+     *   task: "menu-api-scan"
+     *   menuApiPattern (string|RegExp 默认 /listUserViewMenus/) — 用作 _discoverMenus 的 lastApiCapture 过滤
+     *   menuLimit (number 默认 0=不限) — 仅探索前 N 条
+     *   menuPathPrefix (Array<string>) — 仅探索 path 开头匹配的菜单
+     *   menuFilter (Array<string>) — 仅探索 name/path 包含任一关键字的菜单
+     *   drawerTriggerSelector / drawerOpenSelector / menuScrollContainer / useNativeHover / maxRetryPerStep — 透传 _actMenuPath
+     *   apiCaptureOptions (object) — 透传 captureApi
+     *   continueOnFail (bool 默认 true)
+     *   snapshotEach (bool 默认 false) — 每条菜单后做轻量 observe
+     *   screenshotEach (bool 默认 false) — 失败时截图（依赖 context.outputDir）
+     */
+    async runTask(step, context = {}) {
+        const taskName = step.task || step.name || "menu-api-scan";
+        if (taskName !== "menu-api-scan") {
+            return { task: taskName, supported: false, error: `Unsupported task: ${taskName}` };
+        }
+
+        const menus = await this._discoverMenus(step, context);
+        if (!menus.length) {
+            return {
+                task: taskName,
+                discovered: 0,
+                error: "No menus discovered. Run apiCapture targeting menuApiPattern first, or provide step.menus directly.",
+            };
+        }
+
+        const limit = Number.parseInt(step.menuLimit ?? 0, 10);
+        const candidates = limit > 0 ? menus.slice(0, limit) : menus;
+        const continueOnFail = step.continueOnFail !== false;
+        const startedAt = Date.now();
+        const results = [];
+        const byOutcome = { clickFailed: 0, noApi: 0, apiOk: 0, apiFailed: 0 };
+
+        for (let i = 0; i < candidates.length; i += 1) {
+            const menu = candidates[i];
+            const itemStartedAt = Date.now();
+            const item = {
+                index: i,
+                menu: { path: menu.path, name: menu.name, names: menu.names },
+                outcome: null,
+            };
+
+            // 1. 点菜单链路（走 act 顶层入口，让它先 _resolveObserveFrame 再分发到 _actMenuPath）
+            const menuStep = {
+                menuPath: menu.names,
+                drawerTriggerSelector: step.drawerTriggerSelector,
+                drawerOpenSelector: step.drawerOpenSelector,
+                menuScrollContainer: step.menuScrollContainer,
+                useNativeHover: step.useNativeHover,
+                maxRetryPerStep: step.maxRetryPerStep,
+                stepDelay: step.stepDelay,
+                frameContentContains: step.frameContentContains,
+                frameUrlContains: step.frameUrlContains,
+                frameIndex: step.frameIndex,
+            };
+            let menuResult;
+            try {
+                menuResult = await this.act(menuStep);
+            } catch (err) {
+                menuResult = { acted: false, error: err.message };
+            }
+            item.menuResult = menuResult;
+
+            if (!menuResult || menuResult.acted === false) {
+                item.outcome = "clickFailed";
+                byOutcome.clickFailed += 1;
+                if (step.screenshotEach) {
+                    try {
+                        const shot = await this._screenshot({ filename: `runTask-fail-${i}.png`, fullPage: true }, context);
+                        item.screenshot = shot;
+                    } catch {
+                        // ignore
+                    }
+                }
+                results.push({ ...item, durationMs: Date.now() - itemStartedAt });
+                if (!continueOnFail) break;
+                continue;
+            }
+
+            // 2. 抓接口
+            const apiStep = {
+                type: "apiCapture",
+                ...(step.apiCaptureOptions || {}),
+                wait: step.apiCaptureOptions?.wait ?? 4000,
+            };
+            let apiResult;
+            try {
+                apiResult = await this.captureApi(apiStep);
+            } catch (err) {
+                apiResult = { error: err.message, summary: { total: 0, failed: 0 } };
+            }
+            item.api = apiResult;
+
+            const total = apiResult?.summary?.total ?? 0;
+            const failed = apiResult?.summary?.failed ?? 0;
+            if (total === 0) {
+                item.outcome = "noApi";
+                byOutcome.noApi += 1;
+            } else if (failed > 0) {
+                item.outcome = "apiFailed";
+                byOutcome.apiFailed += 1;
+            } else {
+                item.outcome = "apiOk";
+                byOutcome.apiOk += 1;
+            }
+
+            if (step.snapshotEach) {
+                try {
+                    item.snapshot = await this.observe({ headingsOnly: true });
+                } catch {
+                    // ignore
+                }
+            }
+
+            results.push({ ...item, durationMs: Date.now() - itemStartedAt });
+        }
+
+        return {
+            task: taskName,
+            discovered: menus.length,
+            attempted: results.length,
+            durationMs: Date.now() - startedAt,
+            byOutcome,
+            results,
+        };
+    }
+
+    /**
+     * 从 lastApiCapture 中找菜单接口响应（默认 /listUserViewMenus/），
+     * 用 CDP getResponseBody 拿到 body 后递归拍平。
+     * 兜底：如果 step.menus 已显式传入，直接用之。
+     */
+    async _discoverMenus(step = {}, context = {}) {
+        if (Array.isArray(step.menus) && step.menus.length) {
+            return this._flattenMenuTree(step.menus, step.menuPathPrefix, step.menuFilter);
+        }
+
+        const lastCapture = step.captureResult || context.lastApiCapture;
+        if (!lastCapture?.requests?.length) return [];
+
+        const patternRaw = step.menuApiPattern ?? "listUserViewMenus";
+        const pattern = patternRaw instanceof RegExp ? patternRaw : new RegExp(patternRaw);
+        const candidate = lastCapture.requests.find((r) => pattern.test(r.url || ""));
+        if (!candidate) return [];
+
+        let tree = candidate.responseBody;
+        if (typeof tree === "string") {
+            try { tree = JSON.parse(tree); } catch { return []; }
+        }
+        // 常见包装：{ data: [...] } / { result: { data: [...] } }
+        const list =
+            (Array.isArray(tree) && tree) ||
+            tree?.data ||
+            tree?.result?.data ||
+            tree?.result ||
+            [];
+        return this._flattenMenuTree(list, step.menuPathPrefix, step.menuFilter);
+    }
+
+    /**
+     * 把菜单树拍平成可点击的链路：
+     *   { path, name, names: [一级名, 二级名, ...], depth }
+     * children 字段名兼容 children/subMenus/sub。
+     */
+    _flattenMenuTree(tree, pathPrefix, keywords) {
+        const out = [];
+        const prefixes = Array.isArray(pathPrefix) ? pathPrefix : pathPrefix ? [pathPrefix] : null;
+        const kws = Array.isArray(keywords) ? keywords : keywords ? [keywords] : null;
+
+        const visit = (nodes, parentNames) => {
+            if (!Array.isArray(nodes)) return;
+            for (const node of nodes) {
+                if (!node) continue;
+                const name = node.name || node.title || node.label || node.menuName;
+                const path = node.path || node.url || node.route;
+                const names = name ? [...parentNames, name] : parentNames.slice();
+                const children = node.children || node.subMenus || node.sub || node.childs;
+
+                // 叶子节点（无 children 或 children 空）才有意义点击触发请求
+                const isLeaf = !Array.isArray(children) || children.length === 0;
+                if (isLeaf && name && path) {
+                    let keep = true;
+                    if (prefixes && !prefixes.some((p) => path.startsWith(p))) keep = false;
+                    if (keep && kws && !kws.some((k) => name.includes(k) || path.includes(k))) keep = false;
+                    if (keep) out.push({ path, name, names, depth: names.length });
+                } else if (Array.isArray(children) && children.length) {
+                    visit(children, names);
+                }
+            }
+        };
+        visit(tree, []);
+        return out;
+    }
+
+    _resolveSelector(selector) {
+        if (!selector) return selector;
+        // ~.editKnowledge → [class*="editKnowledge"]
+        if (selector.startsWith("~.")) {
+            const base = selector.slice(2);
+            return `[class*="${base}"]`;
+        }
+        // ~#editKnowledge → [id*="editKnowledge"]
+        if (selector.startsWith("~#")) {
+            const base = selector.slice(2);
+            return `[id*="${base}"]`;
+        }
+        return selector;
+    }
+
+    /**
+     * 关闭浏览器
+     * connect 模式: disconnect（不关闭用户浏览器）
+     * launch 模式: close（关闭我们启动的浏览器）
+     */
+    async close() {
+        if (!this.browser) return;
+        try {
+            if (this.ownedBrowser) {
+                await this.browser.close();
+            } else {
+                this.browser.disconnect();
+            }
+        } catch {
+            // ignore close errors
+        }
+        this.browser = null;
+        this.page = null;
+    }
+
+    /**
+     * 执行测试用例：支持 dataset 参数化、变量替换
+     * @param {object} testCase - 用例配置
+     * @param {object} context - 执行上下文
+     * @returns {Promise<object>} 用例执行结果摘要
+     */
+    async executeTestCase(testCase, context = {}) {
+        const startTime = Date.now();
+        const results = [];
+        const dataset = testCase.dataset || [{ __row: 0 }];
+
+        // setup 阶段：frame 预定位
+        if (testCase.setup?.findFrame && !this._activeFrame) {
+            const resolved = await this._resolveObserveFrame(testCase.setup.findFrame);
+            this._activeFrame = resolved.frame;
+        }
+
+        for (let dataRowIndex = 0; dataRowIndex < dataset.length; dataRowIndex++) {
+            const dataRow = dataset[dataRowIndex];
+            const rowStartTime = Date.now();
+            const rowResults = [];
+            let allPassed = true;
+
+            for (let stepIndex = 0; stepIndex < testCase.steps.length; stepIndex++) {
+                const rawStep = testCase.steps[stepIndex];
+                // 变量替换：{{key}} → dataRow[key]
+                const step = this._substituteVariables(rawStep, dataRow);
+
+                // 微前端 frame 探活召回：每次 step 执行前确认 _activeFrame 仍然有效
+                // 如果失效（子应用卸载/路由切换），尝试用 setup.findFrame 重新定位
+                if (this._activeFrame) {
+                    const alive = await this._activeFrame.evaluate(() => true).catch(() => false);
+                    if (!alive) {
+                        this._activeFrame = null;
+                        if (testCase.setup?.findFrame) {
+                            const recovered = await this._resolveObserveFrame(testCase.setup.findFrame).catch(() => null);
+                            if (recovered?.frame) {
+                                this._activeFrame = recovered.frame;
+                                rowResults.push({
+                                    type: "frameRecover",
+                                    status: "PASS",
+                                    duration: 0,
+                                    stepIndex,
+                                    dataRowIndex,
+                                    matchedBy: recovered.matchedBy,
+                                    reason: "auto-recovered from frame loss",
+                                });
+                                results.push(rowResults[rowResults.length - 1]);
+                            }
+                        }
+                    }
+                }
+
+                const stepResult = await this.executeStep(step, context);
+
+                rowResults.push({
+                    ...stepResult,
+                    stepIndex,
+                    dataRowIndex,
+                    dataRow: Object.fromEntries(Object.entries(dataRow).map(([k]) => [k, String(dataRow[k]).slice(0, 80)])),
+                });
+                results.push(rowResults[rowResults.length - 1]);
+
+                if (stepResult.status === "FAIL") {
+                    allPassed = false;
+                    const recovery = testCase.recovery || {};
+                    const maxRetries = recovery.maxRetriesPerStep ?? 0;
+                    for (let retry = 0; retry < maxRetries; retry++) {
+                        const retryResult = await this.executeStep(step, context);
+                        rowResults.push({
+                            ...retryResult,
+                            stepIndex,
+                            dataRowIndex,
+                            retry: retry + 1,
+                        });
+                        results.push(rowResults[rowResults.length - 1]);
+                        if (retryResult.status === "PASS") {
+                            allPassed = true;
+                            break;
+                        }
+                    }
+                    if (!allPassed && step.continueOnFail === false) break;
+                }
+
+                // frame 切换：如果 step 设置了新 frame，后续步骤默认走新 frame
+                if (step.findFrame || step.frameContentContains || step.frameUrlContains) {
+                    const resolved = await this._resolveObserveFrame(step);
+                    this._activeFrame = resolved.frame;
+                }
+            }
+
+            rowResults.duration = Date.now() - rowStartTime;
+            rowResults.passed = allPassed;
+        }
+
+        const duration = Date.now() - startTime;
+        const passed = results.filter((r) => r.status === "PASS").length;
+        const failed = results.filter((r) => r.status === "FAIL").length;
+
+        return {
+            title: testCase.title,
+            datasetSize: dataset.length,
+            totalSteps: results.length,
+            passedSteps: passed,
+            failedSteps: failed,
+            passed: failed === 0,
+            duration,
+            results,
+            summary: {
+                perDataset: results.reduce((acc, r) => {
+                    const key = r.dataRowIndex;
+                    if (!acc[key]) acc[key] = { passed: 0, failed: 0, duration: 0 };
+                    if (r.status === "PASS") acc[key].passed++;
+                    else acc[key].failed++;
+                    acc[key].duration += r.duration;
+                    return acc;
+                }, {}),
+            },
+        };
+    }
+
+    /**
+     * 递归替换对象中的 {{varName}} 变量
+     */
+    _substituteVariables(obj, dataRow) {
+        if (typeof obj === "string") {
+            return obj.replace(/\{\{([^}]+)\}\}/g, (_, key) => {
+                const keys = key.split(".");
+                let val = dataRow;
+                for (const k of keys) val = val?.[k];
+                return val !== undefined ? (typeof val === "string" ? val : String(val)) : "";
+            });
+        }
+        if (Array.isArray(obj)) {
+            return obj.map((item) => this._substituteVariables(item, dataRow));
+        }
+        if (obj && typeof obj === "object") {
+            return Object.fromEntries(Object.entries(obj).map(([k, v]) => [k, this._substituteVariables(v, dataRow)]));
+        }
+        return obj;
+    }
+}
+
+/**
+ * 动态加载 puppeteer-core，从共享缓存目录加载，缺失时自动安装
+ */
+async function loadPuppeteer() {
+    const { ensureCoreDeps, loadFromShared } = await import("./shared-deps.js");
+
+    // 1. 尝试从项目本地 node_modules 加载（开发环境或已手动安装）
+    try {
+        const mod = await import("puppeteer-core");
+        return mod.default || mod;
+    } catch {
+        // 本地未安装
+    }
+
+    // 2. observe/act/assert 主链路只需要 puppeteer-core
+    await ensureCoreDeps();
+
+    try {
+        return loadFromShared("puppeteer-core");
+    } catch (err) {
+        const error = new Error(`puppeteer-core 加载失败：${err.message}`);
+        error.code = "DEPENDENCY_MISSING";
+        throw error;
+    }
+}
+
+export default BrowserEngine;