@szc-ft/mcp-szcd-client 0.27.2 → 0.27.4

package/lib/browser-engine.js

@@ -145,11 +145,14 @@ export class BrowserEngine {
         const startTime = Date.now();
         try {
             const result = await this._dispatchStep(step, context);
+            if (step.type === "apiCapture" || step.type === "api-capture") {
+                context.lastApiCapture = result;
+            }
             return {
                 ...result,
                 step: step.type,
                 duration: Date.now() - startTime,
-                status: "PASS",
+                status: result?.passed === false ? "FAIL" : "PASS",
             };
         } catch (err) {
             return {
@@ -215,6 +218,10 @@ export class BrowserEngine {
 
     async act(options = {}) {
         const targetFrame = await this._resolveObserveFrame(options);
+        if (options.menuPath) {
+            return this._actMenuPath(targetFrame, 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;
@@ -262,12 +269,28 @@ export class BrowserEngine {
                     .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();
-                    return interactiveElements().find((el) => getText(el).includes(expected) || getName(el, getText(el)).includes(expected)) ||
-                        Array.from(document.querySelectorAll("*")).find((el) => getText(el).includes(expected));
+                    // 默认仅匹配 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="([^"]+)"\])?/);
@@ -350,6 +373,7 @@ export class BrowserEngine {
             action,
             typeText,
             clear: Boolean(options.clear),
+            includeHidden: Boolean(options.includeHidden),
         });
 
         if (!result.found) {
@@ -373,6 +397,227 @@ export class BrowserEngine {
         };
     }
 
+    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;
@@ -417,6 +662,256 @@ export class BrowserEngine {
         }
     }
 
+    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;
+                requests.set(`${targetInfo.id}:${event.requestId}`, {
+                    id: event.requestId,
+                    targetId: targetInfo.id,
+                    targetType: targetInfo.type,
+                    targetUrl: targetInfo.url,
+                    frameId: event.frameId,
+                    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 = {}) {
         const frames = this.page.frames();
         const mainFrame = this.page.mainFrame();
@@ -613,6 +1108,10 @@ export class BrowserEngine {
             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);
@@ -625,6 +1124,8 @@ export class BrowserEngine {
             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);
             default:
                 throw new Error(`Unknown step type: ${step.type}`);
         }
@@ -1039,6 +1540,205 @@ export class BrowserEngine {
         };
     }
 
+    /**
+     * 高层 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"]