@kkeve/suite 0.0.13 → 0.0.17

package/dist/page-agent/tools.js

@@ -18,6 +18,134 @@ const zod_1 = require("zod");
 function tool(options) {
     return options;
 }
+/** 常见业务 UI 的弹窗容器（dialog / message-box / modal）。 */
+const DIALOG_ROOT_SELECTOR = [
+    '[role="dialog"]',
+    '[role="alertdialog"]',
+    '.ks-dialog',
+    '.el-dialog',
+    '.el-message-box',
+    '.ant-modal',
+    '.ant-modal-confirm',
+    '[class*="message-box"]',
+    '[class*="confirm-dialog"]',
+].join(', ');
+/**
+ * 取当前最上层可见弹窗的文本与按钮。返回空时说明没有可见弹窗。
+ * 通过 page.evaluate 直接跑在浏览器上下文，Playwright/Cypress 共用同一实现。
+ */
+async function currentDialogInfo(page) {
+    try {
+        const selectors = DIALOG_ROOT_SELECTOR.split(',').map(s => s.trim()).filter(Boolean);
+        const result = await page.evaluate(`(() => {
+            var selectors = ${JSON.stringify(selectors)};
+            var seen = [];
+            for (var i = 0; i < selectors.length; i += 1) {
+                var nodes = Array.prototype.slice.call(document.querySelectorAll(selectors[i]));
+                for (var j = 0; j < nodes.length; j += 1) seen.push(nodes[j]);
+            }
+            var visible = [];
+            for (var k = 0; k < seen.length; k += 1) {
+                var el = seen[k];
+                if (!el || !el.getBoundingClientRect) continue;
+                var rect = el.getBoundingClientRect();
+                if (!rect.width && !rect.height) continue;
+                var style = window.getComputedStyle(el);
+                if (!style) continue;
+                if (style.display === 'none' || style.visibility === 'hidden') continue;
+                if (Number(style.opacity) === 0) continue;
+                if (visible.indexOf(el) < 0) visible.push(el);
+            }
+            var root = visible.length ? visible[visible.length - 1] : null;
+            if (!root) return null;
+            var text = String(root.innerText || root.textContent || '').replace(/\\s+/g, ' ').trim();
+            var buttons = [];
+            var candidates = Array.prototype.slice.call(root.querySelectorAll('button, [role="button"], a'));
+            for (var b = 0; b < candidates.length; b += 1) {
+                var btn = candidates[b];
+                if (btn.disabled) continue;
+                var br = btn.getBoundingClientRect();
+                if (!br.width && !br.height) continue;
+                var label = String(btn.textContent || btn.getAttribute('aria-label') || '').replace(/\\s+/g, ' ').trim();
+                if (label && buttons.indexOf(label) < 0) buttons.push(label);
+            }
+            return { text: text.slice(0, 300), buttons: buttons.slice(0, 20) };
+        })()`);
+        if (result && (result.text || result.buttons?.length)) {
+            return { text: String(result.text || ''), buttons: Array.isArray(result.buttons) ? result.buttons.map(String) : [] };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 自动关闭“是否/确认”类弹窗。
+ *
+ * 只有弹窗文本明确包含确认语义时才点正向按钮，避免把普通提示误当操作框；
+ * 点完再检查弹窗是否真正关闭。返回 null 表示不需要/无法自动处理。
+ */
+async function autoConfirmDialog(page, info) {
+    const text = String(info?.text || '');
+    const hasConfirmationWording = /确认|是否|关闭所有|关闭全部|删除|覆盖|确定/.test(text);
+    if (!hasConfirmationWording || !info?.buttons?.length)
+        return null;
+    const wantedLabels = ['确定', '确认', '是', '关闭全部', '关闭所有'];
+    const label = wantedLabels.find(l => info.buttons.includes(l));
+    if (!label)
+        return null;
+    const clickExpression = `(() => {
+        var selectors = ${JSON.stringify(DIALOG_ROOT_SELECTOR.split(',').map(s => s.trim()).filter(Boolean))};
+        var seen = [];
+        for (var i = 0; i < selectors.length; i += 1) {
+            var nodes = Array.prototype.slice.call(document.querySelectorAll(selectors[i]));
+            for (var j = 0; j < nodes.length; j += 1) seen.push(nodes[j]);
+        }
+        var visible = [];
+        for (var k = 0; k < seen.length; k += 1) {
+            var el = seen[k];
+            if (!el || !el.getBoundingClientRect) continue;
+            var rect = el.getBoundingClientRect();
+            if (!rect.width && !rect.height) continue;
+            var style = window.getComputedStyle(el);
+            if (!style || style.display === 'none' || style.visibility === 'hidden') continue;
+            if (Number(style.opacity) === 0) continue;
+            if (visible.indexOf(el) < 0) visible.push(el);
+        }
+        var root = visible.length ? visible[visible.length - 1] : null;
+        if (!root) return null;
+        var wanted = ${JSON.stringify(wantedLabels)};
+        var buttons = Array.prototype.slice.call(root.querySelectorAll('button, [role="button"], a'));
+        for (var w = 0; w < wanted.length; w += 1) {
+            for (var b = 0; b < buttons.length; b += 1) {
+                var btn = buttons[b];
+                if (btn.disabled) continue;
+                var label = String(btn.textContent || btn.getAttribute('aria-label') || '').replace(/\\s+/g, ' ').trim();
+                if (label === wanted[w]) {
+                    if (typeof btn.click === 'function') btn.click();
+                    else btn.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true }));
+                    return label;
+                }
+            }
+        }
+        return null;
+    })()`;
+    try {
+        const clicked = await page.evaluate(clickExpression);
+        if (!clicked)
+            return null;
+        await page.waitForTimeout(600);
+        const after = await currentDialogInfo(page);
+        if (!after) {
+            return `✅ Auto-confirmed blocking dialog via "${clicked}" — dialog closed`;
+        }
+        return `⚠️ Clicked dialog content then auto-confirmed "${clicked}", but dialog still open: "${after.text.slice(0, 80)}". Read the accessibility tree to handle the remaining dialog.`;
+    }
+    catch {
+        return null;
+    }
+}
 // ─── Tool Registry ────────────────────────────────────────────────────
 exports.tools = new Map();
 // --- done ---
@@ -63,7 +191,7 @@ exports.tools.set('click', tool({
         let inDialog = false;
         try {
             const preClickInfo = await locator.evaluate((el) => {
-                const dialog = el.closest('[role="dialog"], [role="alertdialog"], .ks-dialog, .el-dialog, .ant-modal');
+                const dialog = el.closest(DIALOG_ROOT_SELECTOR);
                 const role = el.getAttribute('role') || el.tagName.toLowerCase();
                 const name = el.textContent?.trim()?.slice(0, 40) || el.getAttribute('aria-label') || el.getAttribute('title') || '';
                 const isButton = el.tagName === 'BUTTON' || el.getAttribute('role') === 'button' || el.tagName === 'A';
@@ -83,6 +211,16 @@ exports.tools.set('click', tool({
             : elementRole || `element`;
         await locator.click({ timeout: 5000, force: true });
         await this.page.waitForTimeout(300);
+        // 点击弹窗内容（非按钮）没有自动关闭弹窗时，常见确认框会一直盖住页面；
+        // 这里在 Agent 继续尝试前先扫描弹窗按钮，避免反复 execute_javascript 碰运气。
+        if (inDialog && !dialogContext) {
+            const dialogInfo = await currentDialogInfo(this.page);
+            if (dialogInfo) {
+                const autoResult = await autoConfirmDialog(this.page, dialogInfo);
+                if (autoResult)
+                    return autoResult;
+            }
+        }
         // Post-click check: if we clicked a dialog button, check if dialog closed
         if (dialogContext) {
             try {
@@ -486,20 +624,20 @@ exports.tools.set('navigate', tool({
         // ── Resolve environment variable references (e.g., "process.env.PAGE_BI") ──
         const envRefMatch = url.match(/^process\.env\.(\w+)$/);
         if (envRefMatch) {
-            const envValue = process.env[envRefMatch[1]] || '';
+            const envValue = this.getEnv(envRefMatch[1]);
             if (!envValue) {
                 return `❌ Cannot navigate: environment variable ${envRefMatch[1]} is empty/undefined. This is a test data configuration issue — call done(verdict="blocked") immediately.`;
             }
             url = envValue;
         }
         if (!url.startsWith('http://') && !url.startsWith('https://')) {
-            const base = process.env.KEVE_TARGET_URL || process.env.BASE_URL || '';
+            const base = this.targetUrl || this.getEnv('BASE_URL');
             if (!base) {
                 return `❌ Cannot navigate: no base URL available (KEVE_TARGET_URL and BASE_URL are both empty). Call done(verdict="blocked") immediately.`;
             }
             url = new URL(url, base).href;
         }
-        await this.page.goto(url, { waitUntil: 'networkidle', timeout: 15000 });
+        await this.page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });
         return `✅ Navigated to ${url}`;
     },
 }));
@@ -589,8 +727,7 @@ exports.tools.set('visual_assert', tool({
         // 1. Capture screenshot
         let screenshotBase64;
         try {
-            const buf = await this.page.screenshot({ type: 'png', timeout: 10000 });
-            screenshotBase64 = buf.toString('base64');
+            screenshotBase64 = (await this.page.screenshot({ type: 'png', timeout: 10000 })).base64;
         }
         catch (e) {
             throw new Error(`visual_assert screenshot failed: ${e.message}`);
@@ -613,8 +750,7 @@ exports.tools.set('visual_locate', tool({
         // 1. Capture screenshot
         let screenshotBase64;
         try {
-            const buf = await this.page.screenshot({ type: 'png', timeout: 10000 });
-            screenshotBase64 = buf.toString('base64');
+            screenshotBase64 = (await this.page.screenshot({ type: 'png', timeout: 10000 })).base64;
         }
         catch (e) {
             throw new Error(`visual_locate screenshot failed: ${e.message}`);
@@ -625,7 +761,7 @@ exports.tools.set('visual_locate', tool({
             return `❌ Visual locate failed: element "${input.description}" not found. ${locateResult.analysis || ''}`;
         }
         // 3. Convert normalized bbox (0-1000) to viewport pixel coordinates
-        const viewport = this.page.viewportSize() || { width: 1280, height: 720 };
+        const viewport = (await this.page.viewportSize()) || { width: 1280, height: 720 };
         const [x1, y1, x2, y2] = locateResult.bbox;
         const centerX = Math.round(((x1 + x2) / 2) * viewport.width / 1000);
         const centerY = Math.round(((y1 + y2) / 2) * viewport.height / 1000);
@@ -747,6 +883,302 @@ exports.tools.set('fill_form', tool({
         return results.join('\n');
     },
 }));
+// --- drag ---
+exports.tools.set('drag', tool({
+    description: `Drag from a starting point to an ending point using real mouse events (mousedown → mousemove steps → mouseup). Use for: resizing elements via drag handles, drag-to-reorder lists, any UI requiring hold+move interaction.
+
+Two targeting modes:
+1. By ref — drags from the element's center (use for drag-to-reorder)
+2. By coordinates (startX/startY) — precise point (use for resize handles found via visual_locate)
+
+Target specification:
+- Relative: use deltaX/deltaY (e.g. deltaX=200 moves 200px right)
+- Absolute: use endX/endY (e.g. endX=800, endY=400)
+
+NOT for: scrolling (use scroll), clicking (use click), HTML5 DnD between elements.`,
+    inputSchema: zod_1.z.object({
+        ref: zod_1.z.string().optional()
+            .describe('Element ref to start dragging from. Drags from element center. Use startX/startY for resize handles.'),
+        startX: zod_1.z.number().optional()
+            .describe('X coordinate to start dragging from (viewport pixels). Use when you have precise coordinates from visual_locate.'),
+        startY: zod_1.z.number().optional()
+            .describe('Y coordinate to start dragging from (viewport pixels).'),
+        deltaX: zod_1.z.number().optional()
+            .describe('Horizontal displacement in pixels. Positive=right, negative=left. Use with ref or startX/startY.'),
+        deltaY: zod_1.z.number().optional()
+            .describe('Vertical displacement in pixels. Positive=down, negative=up.'),
+        endX: zod_1.z.number().optional()
+            .describe('Absolute X coordinate to drag to (viewport pixels). Use deltaX/deltaY for relative, endX/endY for absolute.'),
+        endY: zod_1.z.number().optional()
+            .describe('Absolute Y coordinate to drag to (viewport pixels).'),
+        steps: zod_1.z.number().min(1).max(100).default(10)
+            .describe('Number of intermediate mousemove steps. More=smoother animation. Default 10. Use 20+ for CSS resize.'),
+    }),
+    execute: async function (input) {
+        // 1. Determine start coordinates
+        let sx, sy;
+        if (input.ref) {
+            const locator = this.page.locator(`aria-ref=${input.ref}`);
+            try {
+                const box = await locator.boundingBox({ timeout: 5000 });
+                if (!box)
+                    return `❌ Cannot drag: element [ref=${input.ref}] not visible or detached`;
+                sx = box.x + box.width / 2;
+                sy = box.y + box.height / 2;
+            }
+            catch (err) {
+                return `❌ Cannot drag: element [ref=${input.ref}] error: ${err.message}`;
+            }
+        }
+        else if (input.startX !== undefined && input.startY !== undefined) {
+            sx = input.startX;
+            sy = input.startY;
+        }
+        else {
+            return `❌ Cannot drag: provide either ref or startX/startY`;
+        }
+        // 2. Determine end coordinates
+        let ex, ey;
+        if (input.endX !== undefined && input.endY !== undefined) {
+            ex = input.endX;
+            ey = input.endY;
+        }
+        else if (input.deltaX !== undefined || input.deltaY !== undefined) {
+            ex = sx + (input.deltaX || 0);
+            ey = sy + (input.deltaY || 0);
+        }
+        else {
+            return `❌ Cannot drag: provide either deltaX/deltaY or endX/endY`;
+        }
+        // 3. Execute real mouse drag with intermediate steps
+        const steps = input.steps ?? 10;
+        try {
+            await this.page.mouse.move(sx, sy);
+            await this.page.mouse.down();
+            for (let i = 1; i <= steps; i++) {
+                const progress = i / steps;
+                await this.page.mouse.move(sx + (ex - sx) * progress, sy + (ey - sy) * progress);
+                await this.page.waitForTimeout(16); // ~60fps
+            }
+            await this.page.mouse.up();
+            await this.page.waitForTimeout(300); // wait for resize/layout to settle
+            return `✅ Dragged from (${Math.round(sx)}, ${Math.round(sy)}) to (${Math.round(ex)}, ${Math.round(ey)}) in ${steps} steps (Δx=${Math.round(ex - sx)}, Δy=${Math.round(ey - sy)})`;
+        }
+        catch (err) {
+            try {
+                await this.page.mouse.up();
+            }
+            catch { /* ensure mouse released */ }
+            return `❌ Drag failed: ${err.message}`;
+        }
+    },
+}));
+// --- wait_for ---
+exports.tools.set('wait_for', tool({
+    description: `Wait for text to appear or disappear on the page, or for a specified duration. More efficient than polling with wait(time).
+
+- waitForText: wait until specific text becomes visible on the page (e.g. wait for "保存成功" toast)
+- waitForTextGone: wait until specific text disappears (e.g. wait for "加载中..." spinner to vanish)
+- seconds: simple time-based wait (max 30s)
+
+At least one parameter is required. You can combine them (e.g. wait for text + timeout).`,
+    inputSchema: zod_1.z.object({
+        waitForText: zod_1.z.string().optional()
+            .describe('Wait for this text to appear on the page (visible)'),
+        waitForTextGone: zod_1.z.string().optional()
+            .describe('Wait for this text to disappear from the page (hidden)'),
+        seconds: zod_1.z.number().min(0.1).max(30).optional()
+            .describe('Wait time in seconds (max 30)'),
+    }),
+    execute: async function (input) {
+        if (!input.waitForText && !input.waitForTextGone && !input.seconds) {
+            return `❌ wait_for: provide at least one of waitForText, waitForTextGone, or seconds`;
+        }
+        const results = [];
+        if (input.seconds) {
+            await this.page.waitForTimeout(input.seconds * 1000);
+            results.push(`waited ${input.seconds}s`);
+        }
+        if (input.waitForTextGone) {
+            const locator = this.page.getByText(input.waitForTextGone).first();
+            try {
+                await locator.waitFor({ state: 'hidden', timeout: 15000 });
+                results.push(`"${input.waitForTextGone}" disappeared`);
+            }
+            catch {
+                results.push(`⚠️ "${input.waitForTextGone}" still visible after 15s`);
+            }
+        }
+        if (input.waitForText) {
+            const locator = this.page.getByText(input.waitForText).first();
+            try {
+                await locator.waitFor({ state: 'visible', timeout: 15000 });
+                results.push(`"${input.waitForText}" appeared`);
+            }
+            catch {
+                results.push(`⚠️ "${input.waitForText}" not found after 15s`);
+            }
+        }
+        return `✅ ${results.join(', ')}`;
+    },
+}));
+// --- verify_value ---
+exports.tools.set('verify_value', tool({
+    description: `Deterministically verify a form element's current value — no LLM needed. Faster and more precise than visual_assert for value checks.
+
+- textbox/slider/combobox → checks locator.inputValue()
+- checkbox/radio → checks locator.isChecked()
+
+Returns ✅ if value matches, ❌ if mismatch. Use for precise value assertions instead of visual inspection.`,
+    inputSchema: zod_1.z.object({
+        ref: zod_1.z.string().describe('Element ref from the accessibility tree'),
+        type: zod_1.z.enum(['textbox', 'checkbox', 'radio', 'combobox', 'slider'])
+            .describe('Element type: textbox/slider/combobox → check inputValue; checkbox/radio → check isChecked'),
+        value: zod_1.z.string().describe('Expected value. For checkbox/radio: "true" or "false". For textbox: expected text. For combobox: expected selected value.'),
+    }),
+    execute: async function (input) {
+        const locator = this.page.locator(`aria-ref=${input.ref}`);
+        try {
+            if (input.type === 'checkbox' || input.type === 'radio') {
+                const checked = await locator.isChecked({ timeout: 5000 });
+                const expected = input.value === 'true';
+                if (checked === expected) {
+                    return `✅ Verify [ref=${input.ref}] ${input.type}: checked=${checked} (expected ${input.value})`;
+                }
+                return `❌ Verify [ref=${input.ref}] ${input.type}: checked=${checked} (expected ${input.value})`;
+            }
+            // textbox, slider, combobox — check inputValue
+            const actualValue = await locator.inputValue({ timeout: 5000 });
+            if (actualValue === input.value) {
+                return `✅ Verify [ref=${input.ref}] ${input.type}: value="${actualValue}" (expected "${input.value}")`;
+            }
+            // For combobox, also check textContent (custom components may not expose value via inputValue)
+            if (input.type === 'combobox') {
+                const textContent = await locator.textContent({ timeout: 2000 }).catch(() => '');
+                if (textContent?.includes(input.value)) {
+                    return `✅ Verify [ref=${input.ref}] combobox: text contains "${input.value}" (inputValue="${actualValue}")`;
+                }
+            }
+            return `❌ Verify [ref=${input.ref}] ${input.type}: value="${actualValue}" (expected "${input.value}")`;
+        }
+        catch (err) {
+            return `❌ Verify [ref=${input.ref}] failed: ${err.message}`;
+        }
+    },
+}));
+// --- handle_dialog ---
+exports.tools.set('handle_dialog', tool({
+    description: `Handle native browser dialogs (alert, confirm, prompt). Native dialogs are auto-accepted by default when they appear.
+
+Two usage modes:
+1. BEFORE a dialog-triggering action: call handle_dialog(accept=false) to override the default auto-accept behavior. Then click the button that triggers the dialog.
+2. AFTER a dialog appeared: call handle_dialog to check what dialog was captured and how it was handled.
+
+Native dialogs are auto-accepted unless you pre-set a different action. If a click triggers a dialog, it will be handled automatically based on your pre-set preference.`,
+    inputSchema: zod_1.z.object({
+        accept: zod_1.z.boolean().default(true).describe('Whether to accept (true) or dismiss (false) the next native dialog. Default true.'),
+        promptText: zod_1.z.string().optional().describe('Text to enter in prompt dialog (only when accept=true and dialog is a prompt)'),
+    }),
+    execute: async function (input) {
+        // Set handler for the NEXT dialog
+        this._dialogHandler = { accept: input.accept, promptText: input.promptText };
+        // Also report the last captured dialog (if any)
+        const last = this._lastDialogInfo;
+        if (last) {
+            return `Last dialog: [${last.type}] "${last.message.slice(0, 80)}" — was ${last.accepted ? 'accepted' : 'dismissed'}. Next dialog will be ${input.accept ? 'accepted' : 'dismissed'}.`;
+        }
+        return `Next native dialog will be ${input.accept ? 'accepted' : 'dismissed'}${input.promptText ? ` with text "${input.promptText}"` : ''}.`;
+    },
+}));
+// --- console_messages ---
+exports.tools.set('console_messages', tool({
+    description: `Get browser console log messages captured during page execution. Use to check for JavaScript errors, verify log output, or debug page issues. More reliable than visual checking for error toasts or log messages.`,
+    inputSchema: zod_1.z.object({
+        level: zod_1.z.enum(['error', 'warning', 'info', 'debug']).default('info')
+            .describe('Minimum log level. "error"=only errors, "warning"=errors+warnings, "info"=add info logs, "debug"=all. Default "info".'),
+    }),
+    execute: async function (input) {
+        const messages = this._consoleMessages || [];
+        const levelPriority = { debug: 0, info: 1, warning: 2, error: 3 };
+        const minPriority = levelPriority[input.level] ?? 1;
+        const filtered = messages.filter((m) => (levelPriority[m.level] ?? 0) >= minPriority);
+        if (filtered.length === 0) {
+            return `No console messages at level "${input.level}" or above. Total captured: ${messages.length}.`;
+        }
+        const formatted = filtered.map((m, i) => `[${i + 1}] ${m.level.toUpperCase()}: ${m.text.slice(0, 200)}`).join('\n');
+        return `Console messages (${filtered.length}/${messages.length} at level ≥ "${input.level}"):\n${formatted}`;
+    },
+}));
+// --- file_upload ---
+exports.tools.set('file_upload', tool({
+    description: `Upload one or more files via a file input element. When you click a file input button, a file chooser dialog appears. This tool uploads files to the pending file chooser.
+
+Flow: 1) Click the file input button (e.g. "上传文件", "选择文件"), 2) Call file_upload with the file paths.
+
+Paths must be absolute. The file chooser is single-use — after uploading, a new click is needed for another upload.`,
+    inputSchema: zod_1.z.object({
+        paths: zod_1.z.array(zod_1.z.string()).describe('Absolute file paths to upload'),
+    }),
+    execute: async function (input) {
+        const fileChooser = this._pendingFileChooser;
+        if (!fileChooser) {
+            return `❌ No pending file chooser. Click a file input element first to trigger a file chooser dialog.`;
+        }
+        try {
+            await fileChooser.setFiles(input.paths);
+            this._pendingFileChooser = null;
+            return `✅ Uploaded ${input.paths.length} file(s): ${input.paths.map(p => p.split('/').pop()).join(', ')}`;
+        }
+        catch (err) {
+            this._pendingFileChooser = null;
+            return `❌ File upload failed: ${err.message}`;
+        }
+    },
+}));
+// --- network_requests ---
+exports.tools.set('network_requests', tool({
+    description: `List network requests made by the page. Use to verify API calls were made, check response status codes, or debug network issues. Returns a numbered list with method, URL, and status code.
+
+Filter by URL pattern (regex) and optionally include static resources (images, fonts, scripts). By default, only API/XHR requests are shown.`,
+    inputSchema: zod_1.z.object({
+        filter: zod_1.z.string().optional()
+            .describe('Regex pattern to filter URLs (e.g. "/api/.*user")'),
+        includeStatic: zod_1.z.boolean().default(false)
+            .describe('Include static resources (images, fonts, scripts). Default false.'),
+    }),
+    execute: async function (input) {
+        const requests = this._networkRequests || [];
+        const filter = input.filter ? new RegExp(input.filter) : undefined;
+        const lines = [];
+        for (let i = 0; i < requests.length; i++) {
+            const req = requests[i];
+            if (!input.includeStatic && req.isStatic)
+                continue;
+            if (filter && !filter.test(req.url))
+                continue;
+            const status = req.status ? ` [${req.status}]` : '';
+            const method = req.method || '?';
+            lines.push(`[${i + 1}] ${method} ${req.url.slice(0, 120)}${status}`);
+        }
+        if (lines.length === 0) {
+            return `No matching network requests. Total captured: ${requests.length}.`;
+        }
+        return `Network requests (${lines.length} shown, ${requests.length} total):\n${lines.join('\n')}`;
+    },
+}));
+// --- resize_viewport ---
+exports.tools.set('resize_viewport', tool({
+    description: `Resize the browser viewport (window size). Use for responsive design testing or to trigger layout changes at specific viewport sizes. Common breakpoints: 375×667 (mobile), 768×1024 (tablet), 1280×720 (desktop), 1920×1080 (full HD).`,
+    inputSchema: zod_1.z.object({
+        width: zod_1.z.number().min(320).max(3840).describe('Viewport width in pixels'),
+        height: zod_1.z.number().min(240).max(2160).describe('Viewport height in pixels'),
+    }),
+    execute: async function (input) {
+        await this.page.setViewportSize({ width: input.width, height: input.height });
+        await this.page.waitForTimeout(300);
+        return `✅ Viewport resized to ${input.width}×${input.height}`;
+    },
+}));
 // ── verify_expected fully removed (Phase 6) ──
 // LLM now sees screenshots via multimodal prompt and self-evaluates.
 // No separate verification tool or function needed — each step's screenshot

package/doc/skills/keve-e2e-gen/references/script-generation-guide.md

@@ -51,6 +51,7 @@
 > 2. **绝不硬编码等待时间**：不使用 `waitForTimeout()`，通过 POM waitForReady 或断言等待
 > 3. **绝不硬编码环境数据**（D05）：ID/配置值从 `fixtures/test-data.ts` 导入
 > 4. **每个测试覆盖恰好一个排列**：测试体内无 if/else 分支逻辑
+> 5. **绝不使用 `waitForLoadState('networkidle')`**：BI 仪表盘等页面有 WebSocket/SSE/长轮询等持久连接，`networkidle` 永远不会 resolve 导致无限挂起。使用 `waitForLoadState('domcontentloaded')` 或 `page.goto(url, { waitUntil: 'domcontentloaded' })` 代替
 
 ### 正确模式 vs 禁止模式
 
@@ -64,6 +65,16 @@ await expect(page.locator('[data-e2e-name="智能应用列表-筛选区域"]')).
 await page.locator('.filter-area').click();
 await page.waitForTimeout(5000);
 await agentDetailPage.navigate(636, 'edit');
+
+// ❌ 禁止：waitForLoadState('networkidle') — BI 页面有持久连接会无限挂起
+await page.goto(url);
+await page.waitForLoadState('networkidle');  // ← 永远不会 resolve！
+
+// ✅ 正确：使用 domcontentloaded 替代
+await page.goto(url, { waitUntil: 'domcontentloaded' });
+// 或
+await page.goto(url);
+await page.waitForLoadState('domcontentloaded');
 ```
 
 ### fixtures/test-data.ts 结构

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kkeve/suite",
-  "version": "0.0.13",
+  "version": "0.0.17",
   "description": "AI-powered full-stack test agent CLI - static analysis, unit test, component test, E2E test, execute, evaluate, and report",
   "license": "MIT",
   "bin": {
@@ -13,24 +13,32 @@
       "default": "./dist/index.js"
     },
     "./global-setup": {
-      "types": "./dist/core/global-setup.d.ts",
-      "default": "./dist/core/global-setup.js"
+      "types": "./dist/engine-playwright/global-setup.d.ts",
+      "default": "./dist/engine-playwright/global-setup.js"
     },
     "./keve-report": {
-      "types": "./dist/core/keve-report.d.ts",
-      "default": "./dist/core/keve-report.js"
+      "types": "./dist/engine-playwright/keve-report.d.ts",
+      "default": "./dist/engine-playwright/keve-report.js"
     },
     "./keve-test": {
-      "types": "./dist/core/keve-test.d.ts",
-      "default": "./dist/core/keve-test.js"
+      "types": "./dist/engine-playwright/keve-test.d.ts",
+      "default": "./dist/engine-playwright/keve-test.js"
+    },
+    "./engine-cypress": {
+      "types": "./dist/engine-cypress/index.d.ts",
+      "default": "./dist/engine-cypress/index.js"
+    },
+    "./engine-cypress/setup": {
+      "types": "./dist/engine-cypress/setup.d.ts",
+      "default": "./dist/engine-cypress/setup.js"
     },
     "./page-agent": {
       "types": "./dist/page-agent/agent.d.ts",
       "default": "./dist/page-agent/agent.js"
     },
     "./keve-aspect": {
-      "types": "./dist/core/keve-aspect.d.ts",
-      "default": "./dist/core/keve-aspect.js"
+      "types": "./dist/core/decorator/keve-aspect.d.ts",
+      "default": "./dist/core/decorator/keve-aspect.js"
     },
     "./action-log": {
       "types": "./dist/core/action-log-writer.d.ts",
@@ -40,6 +48,10 @@
       "types": "./dist/core/learned-actions.d.ts",
       "default": "./dist/core/learned-actions.js"
     },
+    "./dsl": {
+      "types": "./dist/dsl/index.d.ts",
+      "default": "./dist/dsl/index.js"
+    },
     "./spec/keve-read-doc": {
       "types": "./dist/spec/keve-read-doc.d.ts",
       "default": "./dist/spec/keve-read-doc.js"
@@ -47,11 +59,12 @@
   },
   "files": [
     "dist",
+    "scripts",
     "doc",
     "README.md"
   ],
   "scripts": {
-    "build": "rm -rf dist && tsc && chmod +x dist/bin/keve.js && cp src/page-agent/system_prompt.md dist/page-agent/",
+    "build": "node scripts/gen-system-prompt.mjs && rm -rf dist && tsc && chmod +x dist/bin/keve.js && cp src/page-agent/system_prompt.md dist/page-agent/",
     "dev": "tsc --watch",
     "typecheck": "tsc --noEmit",
     "keve": "node dist/bin/keve.js",
@@ -62,7 +75,7 @@
     "url": "https://github.com/bubblem1029-tech/EVE.git"
   },
   "dependencies": {
-    "@kkeve/core": "^0.0.4",
+    "@kkeve/core": "^0.0.5",
     "@playwright/test": "*",
     "@vitest/coverage-v8": "^4.1.9",
     "@vue/test-utils": "^2.4.6",

package/scripts/gen-system-prompt.mjs

@@ -0,0 +1,36 @@
+/**
+ * 把 page-agent 的 system_prompt.md 编译成浏览器安全的 TS 模块。
+ *
+ * 为什么需要：Cypress 引擎会把 page-agent 打进浏览器 bundle，运行时用
+ * `node:fs` 读 md 文件会让 esbuild 直接失败。这里在构建期把文本内联为
+ * 一个普通字符串常量，两个引擎共用同一份 prompt，避免出现两套文案漂移。
+ *
+ * 用法：node scripts/gen-system-prompt.mjs
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as url from 'node:url';
+
+const here = path.dirname(url.fileURLToPath(import.meta.url));
+const src = path.join(here, '..', 'src', 'page-agent', 'system_prompt.md');
+const out = path.join(here, '..', 'src', 'page-agent', 'system-prompt.ts');
+
+const text = fs.readFileSync(src, 'utf8');
+
+fs.writeFileSync(
+  out,
+  `/**
+ * system-prompt — 由 scripts/gen-system-prompt.mjs 从 system_prompt.md 生成，请勿手改。
+ *
+ * 生成物是纯字符串常量，不含任何 Node 运行时依赖，因此可以被 Cypress 的浏览器
+ * bundle 安全地打包。修改 prompt 请改 system_prompt.md 后重新生成本文件。
+ */
+
+export const SYSTEM_PROMPT: string = ${JSON.stringify(text)};
+`,
+  'utf8',
+);
+
+console.log(
+  `[gen-system-prompt] ${path.relative(process.cwd(), src)} → ${path.relative(process.cwd(), out)} (${text.length} chars)`,
+);