@yule-h2o/web_auto_flow 0.0.5

package/dist/index.js

@@ -0,0 +1,2491 @@
+import { writeFileSync, existsSync, readFileSync, mkdirSync } from 'fs';
+import { resolve } from 'path';
+import { Stagehand } from '@browserbasehq/stagehand';
+import { chromium } from 'playwright-core';
+import { pathToFileURL } from 'url';
+
+// ============================================================
+// Rule Engine — 选择器工具
+// ============================================================
+/**
+ * 标准化选择器：对常见简写做展开，确保跨浏览器兼容。
+ * - `#id` 保持不变
+ * - `.class` 保持不变
+ * - `tag` 保持不变
+ * - 含空格的复合选择器保持不变
+ */
+function normalizeSelector(selector) {
+    return selector.trim();
+}
+/**
+ * 生成描述性的选择器标签（用于报告）
+ */
+function selectorLabel(selector) {
+    const s = normalizeSelector(selector);
+    if (s.startsWith("#"))
+        return `#${s.slice(1)}`;
+    if (s.startsWith("."))
+        return `.${s.slice(1)}`;
+    if (s.startsWith("[") && s.includes("=")) {
+        const match = s.match(/\[(\w+)=["']?(.+?)["']?\]/);
+        if (match)
+            return `[${match[1]}="${match[2]}"]`;
+    }
+    if (s.includes(" ")) {
+        const parts = s.split(" ");
+        return parts.map((p) => selectorLabel(p)).join(" > ");
+    }
+    return s.length > 36 ? s.slice(0, 33) + "..." : s;
+}
+/**
+ * 安全获取 locator，捕获 Playwright 语法错误
+ */
+function safeLocator(page, selector) {
+    try {
+        return page.locator(normalizeSelector(selector));
+    }
+    catch {
+        throw new Error(`无效选择器: "${selector}"`);
+    }
+}
+
+// ============================================================
+// Rule Engine — 元素断言器
+// ============================================================
+async function assertElement(page, selector, options = {}) {
+    const label = selectorLabel(selector);
+    const start = Date.now();
+    const checks = [];
+    const failures = [];
+    try {
+        const locator = safeLocator(page, selector);
+        const timeout = options.timeout ?? 5000;
+        if (options.visible === true) {
+            const visible = await locator.isVisible({ timeout });
+            if (!visible)
+                failures.push(`元素 "${label}" 应可见但不可见`);
+            checks.push(`可见: ${visible ? "✓" : "✗"}`);
+        }
+        if (options.hidden === true) {
+            const hidden = await locator.isHidden({ timeout });
+            if (!hidden)
+                failures.push(`元素 "${label}" 应隐藏但可见`);
+            checks.push(`隐藏: ${hidden ? "✓" : "✗"}`);
+        }
+        if (options.editable === true) {
+            let editable;
+            try {
+                editable = await locator.isEditable({ timeout });
+            }
+            catch {
+                try {
+                    editable = await page.$eval(selector, (el) => {
+                        if (el.disabled || el.readOnly)
+                            return false;
+                        const tag = el.tagName.toLowerCase();
+                        if (tag === "input") {
+                            const type = (el.getAttribute("type") || "text").toLowerCase();
+                            const nonEditable = ["checkbox", "radio", "button", "submit", "reset", "image", "file", "hidden"];
+                            return !nonEditable.includes(type);
+                        }
+                        return tag === "textarea" || tag === "select" || el.isContentEditable;
+                    });
+                }
+                catch {
+                    editable = false;
+                }
+            }
+            if (!editable)
+                failures.push(`元素 "${label}" 应可编辑但不可编辑`);
+            checks.push(`可编辑: ${editable ? "✓" : "✗"}`);
+        }
+        if (options.enabled === true) {
+            const enabled = await locator.isEnabled({ timeout });
+            if (!enabled)
+                failures.push(`元素 "${label}" 应启用但已禁用`);
+            checks.push(`启用: ${enabled ? "✓" : "✗"}`);
+        }
+        if (options.disabled === true) {
+            const disabled = await locator.isDisabled({ timeout });
+            if (!disabled)
+                failures.push(`元素 "${label}" 应禁用但已启用`);
+            checks.push(`禁用: ${disabled ? "✓" : "✗"}`);
+        }
+        if (options.count !== undefined || options.minCount !== undefined || options.maxCount !== undefined) {
+            const count = await locator.count();
+            if (options.count !== undefined && count !== options.count)
+                failures.push(`元素 "${label}" 数量应为 ${options.count}，实际 ${count}`);
+            if (options.minCount !== undefined && count < options.minCount)
+                failures.push(`元素 "${label}" 数量应 >= ${options.minCount}，实际 ${count}`);
+            if (options.maxCount !== undefined && count > options.maxCount)
+                failures.push(`元素 "${label}" 数量应 <= ${options.maxCount}，实际 ${count}`);
+            checks.push(`数量: ${count}`);
+        }
+        const hasImplicitCheck = options.visible !== undefined || options.hidden !== undefined ||
+            options.enabled !== undefined || options.disabled !== undefined ||
+            options.editable !== undefined;
+        const hasCountCheck = options.count !== undefined || options.minCount !== undefined || options.maxCount !== undefined;
+        if (hasImplicitCheck && !hasCountCheck) {
+            const count = await locator.count();
+            if (count === 0)
+                failures.push(`找不到匹配元素: "${label}"`);
+            checks.push(`存在: ${count > 0 ? "✓" : "✗"}`);
+        }
+        const passed = failures.length === 0;
+        const duration = Date.now() - start;
+        return {
+            passed, type: "element", name: `元素断言: ${label}`,
+            message: passed ? `元素 "${label}" 全部检查通过 [${checks.join(", ")}]` : failures.join("; "),
+            duration, details: passed ? checks.join(", ") : undefined,
+        };
+    }
+    catch (err) {
+        return {
+            passed: false, type: "element", name: `元素断言: ${label}`,
+            message: `元素 "${label}" 检查异常: ${err.message}`,
+            duration: Date.now() - start, details: err.stack,
+        };
+    }
+}
+
+// ============================================================
+// Rule Engine — 内容断言器（文本 & 属性）
+// ============================================================
+/**
+ * 断言元素的文本内容
+ */
+async function assertText(page, selector, expected, options = {}) {
+    const label = selectorLabel(selector);
+    const start = Date.now();
+    const timeout = options.timeout ?? 5000;
+    try {
+        const locator = safeLocator(page, selector);
+        // 先确保可见（用 page.waitForSelector 兼容 Stagehand）
+        try {
+            await page.waitForSelector(selector, { state: "visible", timeout });
+        }
+        catch {
+            // waitForSelector 也可能不可用，静默回退
+        }
+        // 获取文本
+        const rawText = options.useInnerText
+            ? await locator.innerText({ timeout })
+            : await locator.textContent({ timeout });
+        const text = (rawText ?? "").trim();
+        let passed = false;
+        let expectedStr = "";
+        if (expected instanceof RegExp) {
+            const flags = options.ignoreCase && !expected.flags.includes("i")
+                ? new RegExp(expected.source, expected.flags + "i")
+                : expected;
+            passed = flags.test(text);
+            expectedStr = `/${expected.source}/${expected.flags}`;
+        }
+        else if (options.regex) {
+            const flags = options.ignoreCase ? "i" : "";
+            const re = new RegExp(expected, flags);
+            passed = re.test(text);
+            expectedStr = `/${expected}/${flags}`;
+        }
+        else if (options.exact !== false) {
+            // 默认精确匹配
+            if (options.ignoreCase) {
+                passed = text.toLowerCase() === expected.toLowerCase();
+            }
+            else {
+                passed = text === expected;
+            }
+            expectedStr = `"${expected}"${options.ignoreCase ? " (忽略大小写)" : ""}`;
+        }
+        else {
+            // 包含匹配
+            if (options.ignoreCase) {
+                passed = text.toLowerCase().includes(expected.toLowerCase());
+            }
+            else {
+                passed = text.includes(expected);
+            }
+            expectedStr = `包含 "${expected}"${options.ignoreCase ? " (忽略大小写)" : ""}`;
+        }
+        const actualDisplay = text.length > 80 ? text.slice(0, 77) + "..." : text;
+        const duration = Date.now() - start;
+        return {
+            passed,
+            type: "text",
+            name: `文本断言: ${label}`,
+            message: passed
+                ? `"${label}" 文本匹配: ${expectedStr}`
+                : `"${label}" 文本不匹配: 期望 ${expectedStr}，实际 "${actualDisplay}"`,
+            duration,
+            details: `期望: ${expectedStr}\n实际: "${text}"`,
+        };
+    }
+    catch (err) {
+        return {
+            passed: false,
+            type: "text",
+            name: `文本断言: ${label}`,
+            message: `"${label}" 文本检查异常: ${err.message}`,
+            duration: Date.now() - start,
+            details: err.stack,
+        };
+    }
+}
+/**
+ * 断言元素的 HTML 属性值
+ */
+async function assertAttribute(page, selector, attribute, expected, _options = {}) {
+    const label = selectorLabel(selector);
+    const start = Date.now();
+    try {
+        // 用 page.evaluate 兼容 Stagehand（locator.getAttribute 不被代理）
+        const escapedAttr = attribute.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+        const value = await page.evaluate(`
+      (() => {
+        const el = document.querySelector(${JSON.stringify(selector)});
+        return el ? el.getAttribute(${JSON.stringify(escapedAttr)}) : null;
+      })()
+    `);
+        let passed;
+        let expectedStr;
+        if (expected instanceof RegExp) {
+            passed = expected.test(value ?? "");
+            expectedStr = `/${expected.source}/${expected.flags}`;
+        }
+        else {
+            passed = value === expected;
+            expectedStr = `"${expected}"`;
+        }
+        const duration = Date.now() - start;
+        return {
+            passed,
+            type: "attribute",
+            name: `属性断言: ${label}[${attribute}]`,
+            message: passed
+                ? `"${label}" [${attribute}] 匹配: ${expectedStr}`
+                : `"${label}" [${attribute}] 不匹配: 期望 ${expectedStr}，实际 "${value ?? "null"}"`,
+            duration,
+            details: `属性: ${attribute}\n期望: ${expectedStr}\n实际: "${value ?? "null"}"`,
+        };
+    }
+    catch (err) {
+        return {
+            passed: false,
+            type: "attribute",
+            name: `属性断言: ${label}[${attribute}]`,
+            message: `"${label}" [${attribute}] 检查异常: ${err.message}`,
+            duration: Date.now() - start,
+            details: err.stack,
+        };
+    }
+}
+
+// ============================================================
+// Rule Engine — 导航断言器（URL / Title / Meta）
+// ============================================================
+/**
+ * 断⾔当前页面 URL
+ */
+async function assertUrl(page, expected, options = {}) {
+    const start = Date.now();
+    const timeout = options.timeout ?? 10000;
+    let expectedStr = "";
+    try {
+        // 如果指定了 after 动作（点击选择器），先执行
+        if (options.after) {
+            const trimmed = options.after.trim();
+            if (trimmed.startsWith("click ")) {
+                const clickSelector = trimmed.slice(6).trim();
+                await page.locator(clickSelector).click({ timeout });
+                await page.waitForURL(expected instanceof RegExp ? expected : new RegExp(expected), { timeout });
+            }
+        }
+        const currentUrl = page.url();
+        let passed;
+        if (expected instanceof RegExp) {
+            passed = expected.test(currentUrl);
+            expectedStr = `/${expected.source}/${expected.flags}`;
+        }
+        else {
+            // 支持部分匹配：如果 expected 不以 / 开头，做包含匹配
+            if (expected.startsWith("/") || expected.startsWith("http")) {
+                passed = currentUrl === expected || currentUrl.endsWith(expected);
+            }
+            else {
+                passed = currentUrl.includes(expected);
+            }
+            expectedStr = `"${expected}"`;
+        }
+        const duration = Date.now() - start;
+        return {
+            passed,
+            type: "navigation",
+            name: "URL 断言",
+            message: passed
+                ? `URL 匹配: ${expectedStr}`
+                : `URL 不匹配: 期望 ${expectedStr}，实际 "${currentUrl}"`,
+            duration,
+            details: `期望: ${expectedStr}\n实际: "${currentUrl}"`,
+        };
+    }
+    catch (err) {
+        return {
+            passed: false,
+            type: "navigation",
+            name: "URL 断言",
+            message: `URL 检查异常: ${err.message}`,
+            duration: Date.now() - start,
+            details: err.stack,
+        };
+    }
+}
+/**
+ * 断言页面标题
+ */
+async function assertTitle(page, expected, _options = {}) {
+    const start = Date.now();
+    try {
+        const title = await page.title();
+        let passed;
+        let expectedStr;
+        if (expected instanceof RegExp) {
+            passed = expected.test(title);
+            expectedStr = `/${expected.source}/${expected.flags}`;
+        }
+        else {
+            passed = title.trim() === expected.trim();
+            expectedStr = `"${expected}"`;
+        }
+        const duration = Date.now() - start;
+        return {
+            passed,
+            type: "navigation",
+            name: "Title 断言",
+            message: passed
+                ? `页面标题匹配: ${expectedStr}`
+                : `页面标题不匹配: 期望 ${expectedStr}，实际 "${title}"`,
+            duration,
+            details: `期望标题: ${expectedStr}\n实际标题: "${title}"`,
+        };
+    }
+    catch (err) {
+        return {
+            passed: false,
+            type: "navigation",
+            name: "Title 断言",
+            message: `Title 检查异常: ${err.message}`,
+            duration: Date.now() - start,
+            details: err.stack,
+        };
+    }
+}
+/**
+ * 断言页面 <meta> 标签内容
+ */
+async function assertMeta(page, metaName, expected, _options = {}) {
+    const start = Date.now();
+    try {
+        // 用 page.evaluate 兼容 Stagehand（locator.getAttribute 不被代理）
+        let content = null;
+        try {
+            content = await page.evaluate(`
+        (() => {
+          const el = document.querySelector('meta[name="${metaName}"]');
+          return el ? el.getAttribute("content") : null;
+        })()
+      `);
+        }
+        catch {
+            // 静默回退
+        }
+        // 再尝试 property 属性 (OpenGraph)
+        if (content === null || content === undefined) {
+            try {
+                content = await page.evaluate(`
+          (() => {
+            const el = document.querySelector('meta[property="${metaName}"]');
+            return el ? el.getAttribute("content") : null;
+          })()
+        `);
+            }
+            catch {
+                // 静默回退
+            }
+        }
+        let passed;
+        let expectedStr;
+        if (expected instanceof RegExp) {
+            passed = expected.test(content ?? "");
+            expectedStr = `/${expected.source}/${expected.flags}`;
+        }
+        else {
+            passed = content === expected;
+            expectedStr = `"${expected}"`;
+        }
+        const duration = Date.now() - start;
+        return {
+            passed,
+            type: "navigation",
+            name: `Meta 断言: ${metaName}`,
+            message: passed
+                ? `Meta "${metaName}" 匹配: ${expectedStr}`
+                : `Meta "${metaName}" 不匹配: 期望 ${expectedStr}，实际 "${content ?? "null"}"`,
+            duration,
+            details: `Meta: ${metaName}\n期望: ${expectedStr}\n实际: "${content ?? "null"}"`,
+        };
+    }
+    catch (err) {
+        return {
+            passed: false,
+            type: "navigation",
+            name: `Meta 断言: ${metaName}`,
+            message: `Meta "${metaName}" 检查异常: ${err.message}`,
+            duration: Date.now() - start,
+            details: err.stack,
+        };
+    }
+}
+
+// ============================================================
+// Rule Engine — 网络断言器（状态码 / 响应体 / 响应头）
+// ============================================================
+/**
+ * 断言某个请求的 HTTP 状态码
+ *
+ * 支持两种模式：
+ * 1. 等待模式：传入 url 字符串，拦截匹配的请求并验证
+ * 2. 被动模式：若已通过其他方式捕获 response，可直接传入验证
+ */
+async function assertStatusCode(page, urlOrPattern, expectedStatus, options = {}) {
+    const start = Date.now();
+    const timeout = options.timeout ?? 15000;
+    try {
+        // 等待匹配的响应
+        const response = await page.waitForResponse((res) => {
+            if (urlOrPattern instanceof RegExp) {
+                return urlOrPattern.test(res.url());
+            }
+            return res.url().includes(urlOrPattern);
+        }, { timeout });
+        const actualStatus = response.status();
+        const passed = actualStatus === expectedStatus;
+        const duration = Date.now() - start;
+        const shortUrl = response.url().length > 80
+            ? response.url().slice(0, 77) + "..."
+            : response.url();
+        const result = {
+            passed,
+            type: "network",
+            name: `状态码断言: ${typeof urlOrPattern === "string" ? urlOrPattern : urlOrPattern.source}`,
+            message: passed
+                ? `HTTP ${actualStatus} — ${shortUrl}`
+                : `HTTP 状态码不匹配: 期望 ${expectedStatus}，实际 ${actualStatus} — ${shortUrl}`,
+            duration,
+            details: `URL: ${response.url()}\n期望状态码: ${expectedStatus}\n实际状态码: ${actualStatus}`,
+        };
+        // 可选的响应体验证
+        if (passed && options.schema) {
+            try {
+                const body = await response.json();
+                const schemaErrors = validateSchema(body, options.schema);
+                if (schemaErrors.length > 0) {
+                    result.passed = false;
+                    result.message += ` | JSON Schema 校验失败: ${schemaErrors.join(", ")}`;
+                    result.details += `\nSchema 错误: ${schemaErrors.join("; ")}`;
+                }
+            }
+            catch {
+                result.passed = false;
+                result.message += " | 响应体非有效 JSON";
+            }
+        }
+        // 可选的响应头验证
+        if (passed && options.headers) {
+            const respHeaders = response.headers();
+            const lowerHeaders = {};
+            for (const [k, v] of Object.entries(respHeaders)) {
+                lowerHeaders[k.toLowerCase()] = v;
+            }
+            const headerErrors = [];
+            for (const [key, expectedVal] of Object.entries(options.headers)) {
+                const actual = lowerHeaders[key.toLowerCase()];
+                if (actual !== expectedVal) {
+                    headerErrors.push(`header "${key}": 期望 "${expectedVal}"，实际 "${actual ?? "缺失"}"`);
+                }
+            }
+            if (headerErrors.length > 0) {
+                result.passed = false;
+                result.message += ` | 响应头校验失败`;
+            }
+        }
+        // 可选的响应体文本包含
+        if (passed && options.contains) {
+            const body = await response.text();
+            if (!body.includes(options.contains)) {
+                result.passed = false;
+                result.message += ` | 响应体不包含 "${options.contains}"`;
+            }
+        }
+        return result;
+    }
+    catch (err) {
+        return {
+            passed: false,
+            type: "network",
+            name: `状态码断言: ${typeof urlOrPattern === "string" ? urlOrPattern : urlOrPattern.source}`,
+            message: `网络请求异常: ${err.message}`,
+            duration: Date.now() - start,
+            details: err.stack,
+        };
+    }
+}
+// -----------------------------------------------------------
+// 简易 JSON Schema 校验
+// -----------------------------------------------------------
+function validateSchema(data, schema, path = "$") {
+    const errors = [];
+    for (const [key, expectedType] of Object.entries(schema)) {
+        const value = data?.[key];
+        const fullPath = `${path}.${key}`;
+        if (value === undefined) {
+            if (expectedType !== "optional") {
+                errors.push(`${fullPath}: 缺失`);
+            }
+            continue;
+        }
+        if (typeof expectedType === "string") {
+            if (expectedType === "array" && !Array.isArray(value)) {
+                errors.push(`${fullPath}: 期望 array，实际 ${typeof value}`);
+            }
+            else if (expectedType !== "array" && typeof value !== expectedType && expectedType !== "any") {
+                errors.push(`${fullPath}: 期望 ${expectedType}，实际 ${typeof value}`);
+            }
+        }
+        else if (typeof expectedType === "object" && !Array.isArray(expectedType)) {
+            // 嵌套 schema
+            if (typeof value === "object" && value !== null) {
+                errors.push(...validateSchema(value, expectedType, fullPath));
+            }
+            else {
+                errors.push(`${fullPath}: 期望 object，实际 ${typeof value}`);
+            }
+        }
+    }
+    return errors;
+}
+
+// ============================================================
+// Rule Engine — 性能断言器（FCP / LCP / TTI / CLS 等 Web Vitals）
+// ============================================================
+const METRIC_LABELS = {
+    FCP: "First Contentful Paint",
+    LCP: "Largest Contentful Paint",
+    TTI: "Time to Interactive",
+    CLS: "Cumulative Layout Shift",
+    TBT: "Total Blocking Time",
+    FID: "First Input Delay",
+    load: "页面加载时间",
+    dns: "DNS 解析",
+    tls: "TLS 握手",
+    ttfb: "Time to First Byte",
+    dom: "DOM 解析完成",
+    custom: "自定义指标",
+};
+/**
+ * 从页面提取 Web Vitals 指标（基于 Performance API）
+ */
+async function assertPerformance(page, metric, options = {}, 
+/** 自定义指标时传入具体数值 */
+customValue) {
+    const start = Date.now();
+    const metricLabel = METRIC_LABELS[metric];
+    try {
+        let value;
+        if (metric === "custom" && customValue !== undefined) {
+            value = customValue;
+        }
+        else {
+            // 自包含的 evaluate 字符串（不能引用外部 TS 函数，Stagehand 要求）
+            value = await page.evaluate(`
+        (() => {
+          const m = ${JSON.stringify(metric)};
+          const navEntries = performance.getEntriesByType("navigation");
+          const nav = navEntries.length > 0 ? navEntries[0] : null;
+          const paintEntries = performance.getEntriesByType("paint");
+          const getFcp = () => {
+            const e = paintEntries.find(p => p.name === "first-contentful-paint");
+            return e ? e.startTime : -1;
+          };
+          switch (m) {
+            case "FCP": return Math.round(getFcp());
+            case "LCP": {
+              const lcpEntries = performance.getEntriesByType("largest-contentful-paint");
+              if (lcpEntries.length > 0) return Math.round(lcpEntries[lcpEntries.length - 1].startTime);
+              return nav ? Math.round(nav.loadEventEnd) : -1;
+            }
+            case "TTI": return nav ? Math.round(nav.domInteractive) : -1;
+            case "CLS": return -1;
+            case "TBT": {
+              if (nav) {
+                const fcp = getFcp();
+                return Math.round(Math.max(0, nav.domInteractive - (fcp > 0 ? fcp : 0)));
+              }
+              return -1;
+            }
+            case "FID": return -1;
+            case "load": return nav ? Math.round(nav.loadEventEnd) : -1;
+            case "dns": return nav ? Math.round(nav.domainLookupEnd - nav.domainLookupStart) : -1;
+            case "tls": return nav ? Math.round(nav.secureConnectionStart > 0 ? nav.connectEnd - nav.secureConnectionStart : 0) : -1;
+            case "ttfb": return nav ? Math.round(nav.responseStart - nav.requestStart) : -1;
+            case "dom": return nav ? Math.round(nav.domContentLoadedEventEnd) : -1;
+            default: return -1;
+          }
+        })()
+      `);
+        }
+        // 四舍五入到整数
+        value = Math.round(value);
+        // 阈值比较
+        let passed = true;
+        const thresholdMsgs = [];
+        if (options.lt !== undefined) {
+            if (!(value < options.lt)) {
+                passed = false;
+                thresholdMsgs.push(`${value}ms >= ${options.lt}ms`);
+            }
+        }
+        if (options.lte !== undefined) {
+            if (!(value <= options.lte)) {
+                passed = false;
+                thresholdMsgs.push(`${value}ms > ${options.lte}ms`);
+            }
+        }
+        if (options.gt !== undefined) {
+            if (!(value > options.gt)) {
+                passed = false;
+                thresholdMsgs.push(`${value}ms <= ${options.gt}ms`);
+            }
+        }
+        if (options.gte !== undefined) {
+            if (!(value >= options.gte)) {
+                passed = false;
+                thresholdMsgs.push(`${value}ms < ${options.gte}ms`);
+            }
+        }
+        if (options.between) {
+            const [lo, hi] = options.between;
+            if (!(value >= lo && value <= hi)) {
+                passed = false;
+                thresholdMsgs.push(`${value}ms 不在 [${lo}, ${hi}] 范围内`);
+            }
+        }
+        const duration = Date.now() - start;
+        // 如果没有设置阈值，则仅做报告，总是通过
+        const hasThreshold = options.lt !== undefined ||
+            options.lte !== undefined ||
+            options.gt !== undefined ||
+            options.gte !== undefined ||
+            options.between !== undefined;
+        return {
+            passed: hasThreshold ? passed : true,
+            type: "performance",
+            name: `性能断言: ${metric}`,
+            message: passed
+                ? `${metricLabel}: ${value}ms ✓`
+                : `${metricLabel}: ${value}ms — ${thresholdMsgs.join(", ")}`,
+            duration,
+            details: hasThreshold
+                ? `指标: ${metric} (${metricLabel})\n值: ${value}ms\n阈值: ${JSON.stringify(options)}`
+                : `指标: ${metric} (${metricLabel})\n值: ${value}ms (无阈值，仅报告)`,
+        };
+    }
+    catch (err) {
+        return {
+            passed: false,
+            type: "performance",
+            name: `性能断言: ${metric}`,
+            message: `${metricLabel} 提取异常: ${err.message}`,
+            duration: Date.now() - start,
+            details: err.stack,
+        };
+    }
+}
+
+// ============================================================
+// Rule Engine — 可访问性断言器（a11y）
+// ============================================================
+/**
+ * 断言元素的可访问性：
+ * - 图片是否有 alt 文本
+ * - 表单控件是否有关联 label
+ * - ARIA role 是否正确
+ * - 颜色对比度（基础检查）
+ */
+async function assertAccessibility(page, selector, options = {}) {
+    const label = selectorLabel(selector);
+    const start = Date.now();
+    const timeout = options.timeout ?? 5000;
+    const failures = [];
+    const checks = [];
+    try {
+        const locator = safeLocator(page, selector);
+        // --- alt 文本检查 ---
+        if (options.altText !== undefined) {
+            const actualAlt = await locator.getAttribute("alt", { timeout });
+            let passed = false;
+            if (options.altText instanceof RegExp) {
+                passed = options.altText.test(actualAlt ?? "");
+            }
+            else {
+                passed = actualAlt === options.altText;
+            }
+            if (!passed) {
+                failures.push(`"${label}" alt 文本不匹配: 期望 "${options.altText}"，实际 "${actualAlt ?? "缺失"}"`);
+            }
+            checks.push(`alt: ${actualAlt ?? "缺失"}`);
+        }
+        // --- label 关联检查 ---
+        if (options.hasLabel) {
+            // 检查是否通过 id-label 关联或包裹在 label 中
+            const hasLabel = await locator.evaluate((el) => {
+                const id = el.getAttribute("id");
+                if (id) {
+                    const labelFor = document.querySelector(`label[for="${id}"]`);
+                    if (labelFor)
+                        return true;
+                }
+                // 检查是否被 label 包裹
+                const parentLabel = el.closest("label");
+                if (parentLabel)
+                    return true;
+                // 检查 aria-label / aria-labelledby
+                if (el.getAttribute("aria-label") || el.getAttribute("aria-labelledby"))
+                    return true;
+                return false;
+            }).catch(() => false);
+            if (!hasLabel) {
+                failures.push(`"${label}" 缺少关联的 label`);
+            }
+            checks.push(`label: ${hasLabel ? "✓" : "✗"}`);
+        }
+        // --- ARIA role 检查 ---
+        if (options.role) {
+            const actualRole = await locator.getAttribute("role", { timeout }).catch(() => null);
+            if (actualRole !== options.role) {
+                failures.push(`"${label}" role 不匹配: 期望 "${options.role}"，实际 "${actualRole ?? "缺失"}"`);
+            }
+            checks.push(`role: ${actualRole ?? "缺失"}`);
+        }
+        // --- 颜色对比度基础检查 ---（用 page.$eval 兼容 Stagehand）
+        if (options.minContrast !== undefined) {
+            const minRatio = options.minContrast;
+            let contrastOk = false;
+            try {
+                contrastOk = await page.$eval(selector, (el, ratio) => {
+                    const style = window.getComputedStyle(el);
+                    const color = style.color;
+                    const bg = style.backgroundColor;
+                    const parseRgb = (rgb) => {
+                        const m = rgb.match(/[\d.]+/g);
+                        if (!m || m.length < 3)
+                            return null;
+                        return [Number(m[0]), Number(m[1]), Number(m[2])];
+                    };
+                    const fg = parseRgb(color);
+                    const bgParsed = parseRgb(bg);
+                    if (!fg || !bgParsed)
+                        return false;
+                    const luminance = (r, g, b) => {
+                        const toLinear = (c) => {
+                            c /= 255;
+                            return c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+                        };
+                        return 0.2126 * toLinear(r) + 0.7152 * toLinear(g) + 0.0722 * toLinear(b);
+                    };
+                    const l1 = luminance(fg[0], fg[1], fg[2]);
+                    const l2 = luminance(bgParsed[0], bgParsed[1], bgParsed[2]);
+                    const contrastRatio = (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05);
+                    return contrastRatio >= ratio;
+                }, minRatio);
+            }
+            catch {
+                contrastOk = false;
+            }
+            if (!contrastOk) {
+                failures.push(`"${label}" 颜色对比度不满足 ${options.minContrast}:1 要求`);
+            }
+            checks.push(`对比度 >= ${options.minContrast}:1: ${contrastOk ? "✓" : "✗"}`);
+        }
+        const passed = failures.length === 0;
+        const duration = Date.now() - start;
+        return {
+            passed,
+            type: "accessibility",
+            name: `可访问性断言: ${label}`,
+            message: passed
+                ? `"${label}" 可访问性通过 [${checks.join(", ")}]`
+                : failures.join("; "),
+            duration,
+            details: `元素: "${label}"\n检查项:\n${checks.map((c) => `  ${c}`).join("\n")}`,
+        };
+    }
+    catch (err) {
+        return {
+            passed: false,
+            type: "accessibility",
+            name: `可访问性断言: ${label}`,
+            message: `"${label}" 可访问性检查异常: ${err.message}`,
+            duration: Date.now() - start,
+            details: err.stack,
+        };
+    }
+}
+
+// ============================================================
+// Rule Engine — RuleTest 主类（Fluent API）
+// ============================================================
+class RuleTest {
+    constructor(name, options = {}) {
+        this.tasks = [];
+        this.name = name;
+        this.options = {
+            timeout: options.timeout ?? 10000,
+            screenshotOnFailure: options.screenshotOnFailure ?? true,
+            bailOnFailure: options.bailOnFailure ?? false,
+            retryCount: options.retryCount ?? 0,
+        };
+    }
+    // ==========================================================
+    // Builder API — 链式断言
+    // ==========================================================
+    /** 断言元素存在性/可见性/可编辑性/数量 */
+    assertElement(selector, opts = {}) {
+        this.tasks.push({
+            type: "element",
+            name: `元素断言: ${selector}`,
+            execute: (page) => assertElement(page, selector, opts),
+        });
+        return this;
+    }
+    /** 断言元素文本内容 */
+    assertText(selector, expected, opts = {}) {
+        this.tasks.push({
+            type: "text",
+            name: `文本断言: ${selector}`,
+            execute: (page) => assertText(page, selector, expected, opts),
+        });
+        return this;
+    }
+    /** 断言元素 HTML 属性值 */
+    assertAttribute(selector, attribute, expected, opts = {}) {
+        this.tasks.push({
+            type: "attribute",
+            name: `属性断言: ${selector}[${attribute}]`,
+            execute: (page) => assertAttribute(page, selector, attribute, expected, opts),
+        });
+        return this;
+    }
+    /** 断言当前页面 URL */
+    assertUrl(expected, opts = {}) {
+        this.tasks.push({
+            type: "navigation",
+            name: "URL 断言",
+            execute: (page) => assertUrl(page, expected, opts),
+        });
+        return this;
+    }
+    /** 断言页面 <title> */
+    assertTitle(expected, opts = {}) {
+        this.tasks.push({
+            type: "navigation",
+            name: "Title 断言",
+            execute: (page) => assertTitle(page, expected, opts),
+        });
+        return this;
+    }
+    /** 断言页面 <meta> 标签 */
+    assertMeta(metaName, expected, opts = {}) {
+        this.tasks.push({
+            type: "navigation",
+            name: `Meta 断言: ${metaName}`,
+            execute: (page) => assertMeta(page, metaName, expected, opts),
+        });
+        return this;
+    }
+    /** 断言 HTTP 状态码（可附加响应体/响应头校验） */
+    assertStatusCode(urlOrPattern, expectedStatus, opts = {}) {
+        this.tasks.push({
+            type: "network",
+            name: `状态码断言: ${urlOrPattern}`,
+            execute: (page) => assertStatusCode(page, urlOrPattern, expectedStatus, opts),
+        });
+        return this;
+    }
+    /** 断言 Web 性能指标 */
+    assertPerformance(metric, opts = {}, customValue) {
+        this.tasks.push({
+            type: "performance",
+            name: `性能断言: ${metric}`,
+            execute: (page) => assertPerformance(page, metric, opts, customValue),
+        });
+        return this;
+    }
+    /** 断言可访问性（alt / label / role / 对比度） */
+    assertAccessibility(selector, opts = {}) {
+        this.tasks.push({
+            type: "accessibility",
+            name: `可访问性断言: ${selector}`,
+            execute: (page) => assertAccessibility(page, selector, opts),
+        });
+        return this;
+    }
+    /** 自定义断言：传入任意异步校验函数 */
+    assertCustom(label, fn) {
+        this.tasks.push({
+            type: "custom",
+            name: label,
+            execute: async (page) => {
+                const result = await fn(page);
+                return { ...result, type: "custom" };
+            },
+        });
+        return this;
+    }
+    // ==========================================================
+    // 执行
+    // ==========================================================
+    /**
+     * 运行全部断言，返回结果
+     */
+    async run(page) {
+        const startTime = Date.now();
+        const results = [];
+        for (const task of this.tasks) {
+            let lastResult = null;
+            // 支持重试
+            const attempts = 1 + this.options.retryCount;
+            for (let attempt = 1; attempt <= attempts; attempt++) {
+                const result = await task.execute(page);
+                lastResult = result;
+                if (result.passed)
+                    break;
+                // 如果不是最后一次尝试，打印重试日志
+                if (attempt < attempts) {
+                    console.warn(`[RuleTest] "${task.name}" 第 ${attempt}/${attempts} 次尝试失败，即将重试...`);
+                }
+            }
+            // 确保一定有结果
+            const finalResult = lastResult;
+            // 失败时截图
+            if (!finalResult.passed && this.options.screenshotOnFailure) {
+                try {
+                    const buf = await page.screenshot();
+                    finalResult.screenshot = buf.toString("base64");
+                }
+                catch {
+                    // 截图失败不阻断流程
+                }
+            }
+            results.push(finalResult);
+            // bailOnFailure：遇错即停
+            if (!finalResult.passed && this.options.bailOnFailure) {
+                console.warn(`[RuleTest] bailOnFailure 触发，跳过剩余 ${this.tasks.length - results.length} 个断言`);
+                break;
+            }
+        }
+        const passedCount = results.filter((r) => r.passed).length;
+        const totalDuration = Date.now() - startTime;
+        return {
+            name: this.name,
+            assertions: results,
+            hasFailure: passedCount < results.length,
+            passRate: results.length > 0 ? passedCount / results.length : 1,
+            totalDuration,
+        };
+    }
+}
+
+// ============================================================
+// AI Engine — LLM Client（OpenAI 兼容 API）
+// ============================================================
+/**
+ * 根据模型名推断 Base URL
+ */
+function inferBaseURL(model) {
+    const lower = model.toLowerCase();
+    if (lower.includes("deepseek"))
+        return "https://api.deepseek.com/v1";
+    if (lower.includes("openai") || lower.includes("gpt"))
+        return "https://api.openai.com/v1";
+    if (lower.includes("anthropic") || lower.includes("claude"))
+        return "https://api.anthropic.com/v1";
+    // 默认走 DeepSeek（项目已在使用）
+    return "https://api.deepseek.com/v1";
+}
+/**
+ * 根据模型名推断 API Key 环境变量
+ */
+function inferApiKey(model) {
+    const lower = model.toLowerCase();
+    if (lower.includes("deepseek"))
+        return process.env.DEEPSEEK_API_KEY || "";
+    if (lower.includes("openai") || lower.includes("gpt"))
+        return process.env.OPENAI_API_KEY || "";
+    if (lower.includes("anthropic") || lower.includes("claude"))
+        return process.env.ANTHROPIC_API_KEY || "";
+    return process.env.DEEPSEEK_API_KEY || process.env.OPENAI_API_KEY || "";
+}
+/**
+ * 简易 OpenAI 兼容 LLM 客户端
+ *
+ * 支持 DeepSeek、OpenAI、及任何 OpenAI 兼容 API。
+ * 自动从模型名推断 endpoint 和 API Key。
+ */
+class LLMClient {
+    constructor(config) {
+        this.totalTokens = 0;
+        this.config = {
+            model: config.model,
+            baseURL: config.baseURL || inferBaseURL(config.model),
+            apiKey: config.apiKey || inferApiKey(config.model),
+            temperature: config.temperature ?? 0.1,
+            maxTokens: config.maxTokens ?? 1024,
+            timeout: config.timeout ?? 30000,
+        };
+    }
+    /** 获取累计 token 消耗 */
+    getTotalTokens() {
+        return this.totalTokens;
+    }
+    /** 发送 Chat Completion 请求 */
+    async chat(messages) {
+        const url = `${this.config.baseURL}/chat/completions`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.config.timeout);
+        try {
+            const res = await fetch(url, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "Authorization": `Bearer ${this.config.apiKey}`,
+                },
+                body: JSON.stringify({
+                    model: this.config.model,
+                    messages,
+                    temperature: this.config.temperature,
+                    max_tokens: this.config.maxTokens,
+                }),
+                signal: controller.signal,
+            });
+            if (!res.ok) {
+                const body = await res.text().catch(() => "");
+                throw new Error(`LLM API ${res.status}: ${body.slice(0, 200)}`);
+            }
+            const data = await res.json();
+            const content = data.choices?.[0]?.message?.content ?? "";
+            const usage = data.usage;
+            if (usage?.totalTokens) {
+                this.totalTokens += usage.totalTokens;
+            }
+            return {
+                content: content.trim(),
+                usage: usage ? {
+                    promptTokens: usage.prompt_tokens || usage.promptTokens || 0,
+                    completionTokens: usage.completion_tokens || usage.completionTokens || 0,
+                    totalTokens: usage.total_tokens || usage.totalTokens || 0,
+                } : undefined,
+            };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /** 单轮对话快捷方法 */
+    async complete(systemPrompt, userMessage) {
+        return this.chat([
+            { role: "system", content: systemPrompt },
+            { role: "user", content: userMessage },
+        ]);
+    }
+    /** 判断类快捷方法 — 返回布尔值 */
+    async judge(systemPrompt, userMessage, expectedAnswer = "YES") {
+        const fullPrompt = `${systemPrompt}\n\nReply with ONLY "YES" or "NO" followed by a brief reason.`;
+        const res = await this.complete(fullPrompt, userMessage);
+        const raw = res.content;
+        const upper = raw.toUpperCase().trim();
+        const passed = upper.startsWith(expectedAnswer.toUpperCase());
+        const reason = raw.replace(/^(YES|NO)\s*-?\s*/i, "").trim();
+        return { passed, reason, raw };
+    }
+}
+
+// ============================================================
+// AI Engine — Prompt 模板（内联，打包安全）
+// ============================================================
+const SENTIMENT_PROMPT = `You are a sentiment analyzer for UI testing. Given a piece of UI text, classify its emotional tone.
+
+Categories:
+- positive: encouraging, friendly, warm, optimistic, praising, welcoming
+- negative: angry, frustrated, blaming, cold, dismissive, alarming
+- neutral: factual, informational, neutral instructions
+
+Reply with ONLY one word: "positive", "negative", or "neutral". Then a brief reason.`;
+const EXTRACTION_PROMPT = `You are a data extraction tool for UI testing. Extract structured information from the given HTML or text content.
+
+Rules:
+- Return ONLY valid JSON, no markdown, no explanation
+- Use the exact field names provided in the schema
+- If a field cannot be found, use null
+- For numbers, return the numeric value (not strings)`;
+const ANOMALY_PROMPT = `You are an anomaly detector for UI testing. Analyze the given page content and determine if the page is in an error or unexpected state.
+
+Anomalies to detect:
+- Blank/white page with no meaningful content
+- Error messages (e.g., "500 Internal Server Error", "Something went wrong", "Page not found")
+- Loading failures (e.g., infinite spinner, "Loading..." stuck forever)
+- Broken elements (e.g., missing images, unstyled content)
+- Unexpected redirects to error pages
+
+Reply with ONLY "YES" if an anomaly is detected, or "NO" if the page looks normal.
+Then a brief reason.`;
+
+// ============================================================
+// AI Engine — 情感断言器
+// ============================================================
+/**
+ * 断言页面元素的文本情感倾向
+ */
+async function assertSentiment(page, llm, selector, options) {
+    const start = Date.now();
+    try {
+        // 从页面提取文本
+        const text = await page.locator(selector).first().textContent().catch(() => null);
+        if (!text || !text.trim()) {
+            return {
+                passed: false,
+                type: "sentiment",
+                name: `情感断言: ${selector}`,
+                message: `无法提取 "${selector}" 的文本内容`,
+                duration: Date.now() - start,
+            };
+        }
+        const trimmed = text.trim().slice(0, 2000); // 限制长度
+        // 调用 LLM 判断情感
+        const userMsg = `Analyze the sentiment of this UI text:\n\n"${trimmed}"\n\nExpected sentiment: ${options.expected}${options.criteria ? `\nCustom criteria: ${options.criteria}` : ""}`;
+        const res = await llm.complete(SENTIMENT_PROMPT, userMsg);
+        const label = res.content.toLowerCase().trim();
+        const passed = label.startsWith(options.expected.toLowerCase());
+        const duration = Date.now() - start;
+        return {
+            passed,
+            type: "sentiment",
+            name: `情感断言: ${selector}`,
+            message: passed
+                ? `"${selector}" 情感为 ${options.expected} ✓`
+                : `"${selector}" 情感不匹配: 期望 ${options.expected}，实际 ${label}`,
+            duration,
+            details: `文本: "${trimmed.slice(0, 200)}"\nLLM 判断: ${res.content}`,
+            rawResponse: res.content,
+        };
+    }
+    catch (err) {
+        return {
+            passed: false,
+            type: "sentiment",
+            name: `情感断言: ${selector}`,
+            message: `情感分析异常: ${err.message}`,
+            duration: Date.now() - start,
+            details: err.stack,
+        };
+    }
+}
+
+// ============================================================
+// AI Engine — 结构化提取断言器
+// ============================================================
+/**
+ * 从页面元素中提取结构化数据，并校验是否符合 Schema
+ */
+async function assertExtraction(page, llm, selector, options) {
+    const start = Date.now();
+    try {
+        // 从页面提取 HTML/文本
+        const text = await page.locator(selector).first().textContent().catch(() => null);
+        if (!text || !text.trim()) {
+            return {
+                passed: false,
+                type: "extract",
+                name: `提取断言: ${selector}`,
+                message: `无法提取 "${selector}" 的内容`,
+                duration: Date.now() - start,
+            };
+        }
+        const schemaStr = JSON.stringify(options.schema, null, 2);
+        const instruction = options.instruction || "Extract the requested fields from the content.";
+        const userMsg = [
+            instruction,
+            `\nExpected schema:\n${schemaStr}`,
+            `\nContent:\n${text.slice(0, 3000)}`,
+        ].join("\n");
+        const res = await llm.complete(EXTRACTION_PROMPT, userMsg);
+        // 尝试解析 JSON
+        let parsed = null;
+        let parseError = "";
+        try {
+            // 去掉可能的 markdown 包裹
+            const jsonStr = res.content
+                .replace(/^```json?\s*/i, "")
+                .replace(/\s*```$/i, "")
+                .trim();
+            parsed = JSON.parse(jsonStr);
+        }
+        catch {
+            parseError = `JSON 解析失败，原始响应: ${res.content.slice(0, 200)}`;
+        }
+        const duration = Date.now() - start;
+        if (!parsed) {
+            return {
+                passed: false,
+                type: "extract",
+                name: `提取断言: ${selector}`,
+                message: parseError,
+                duration,
+                rawResponse: res.content,
+                details: parseError,
+            };
+        }
+        // 校验 Schema 字段
+        const missingFields = [];
+        const typeErrors = [];
+        for (const [key, expectedType] of Object.entries(options.schema)) {
+            if (!(key in parsed)) {
+                missingFields.push(key);
+                continue;
+            }
+            const val = parsed[key];
+            if (expectedType === "number" && typeof val !== "number") {
+                typeErrors.push(`${key}: 期望 number，实际 ${typeof val}`);
+            }
+            else if (expectedType === "string" && typeof val !== "string") {
+                typeErrors.push(`${key}: 期望 string，实际 ${typeof val}`);
+            }
+            else if (expectedType === "boolean" && typeof val !== "boolean") {
+                typeErrors.push(`${key}: 期望 boolean，实际 ${typeof val}`);
+            }
+            else if (expectedType === "array" && !Array.isArray(val)) {
+                typeErrors.push(`${key}: 期望 array，实际 ${typeof val}`);
+            }
+        }
+        const passed = missingFields.length === 0 && typeErrors.length === 0;
+        const errors = [...missingFields.map((f) => `缺少字段: ${f}`), ...typeErrors];
+        return {
+            passed,
+            type: "extract",
+            name: `提取断言: ${selector}`,
+            message: passed
+                ? `"${selector}" 结构化提取成功`
+                : `"${selector}" 提取校验失败: ${errors.join("; ")}`,
+            duration,
+            details: `提取结果:\n${JSON.stringify(parsed, null, 2)}`,
+            rawResponse: res.content,
+        };
+    }
+    catch (err) {
+        return {
+            passed: false,
+            type: "extract",
+            name: `提取断言: ${selector}`,
+            message: `提取异常: ${err.message}`,
+            duration: Date.now() - start,
+            details: err.stack,
+        };
+    }
+}
+
+// ============================================================
+// AI Engine — 内容质量断言器
+// ============================================================
+const QUALITY_PROMPT = `You are a content quality evaluator for UI testing. Analyze the given text against the specified quality criteria. Reply with ONLY "YES" if all criteria are met, or "NO" if any criterion fails. Then list which criteria failed.`;
+/**
+ * 断言页面内容质量（长度、关键词、语气、禁用词）
+ */
+async function assertQuality(page, llm, selector, options) {
+    const start = Date.now();
+    try {
+        const text = await page.locator(selector).first().textContent().catch(() => null);
+        if (!text || !text.trim()) {
+            return {
+                passed: false,
+                type: "quality",
+                name: `质量断言: ${selector}`,
+                message: `无法提取 "${selector}" 的文本内容`,
+                duration: Date.now() - start,
+            };
+        }
+        const trimmed = text.trim();
+        const checks = [];
+        const failures = [];
+        // --- 规则层检查（不需要 LLM） ---
+        // 长度
+        if (options.minLength !== undefined) {
+            const ok = trimmed.length >= options.minLength;
+            checks.push(`长度 >= ${options.minLength}: ${ok ? "✓" : "✗"} (${trimmed.length})`);
+            if (!ok)
+                failures.push(`文本长度 ${trimmed.length} < ${options.minLength}`);
+        }
+        // 关键词
+        if (options.containsKeywords) {
+            for (const kw of options.containsKeywords) {
+                const ok = trimmed.toLowerCase().includes(kw.toLowerCase());
+                checks.push(`关键词 "${kw}": ${ok ? "✓" : "✗"}`);
+                if (!ok)
+                    failures.push(`缺少关键词: "${kw}"`);
+            }
+        }
+        // 禁用词
+        if (options.forbiddenWords) {
+            for (const fw of options.forbiddenWords) {
+                const found = trimmed.toLowerCase().includes(fw.toLowerCase());
+                checks.push(`禁用词 "${fw}": ${found ? "✗" : "✓"}`);
+                if (found)
+                    failures.push(`包含禁用词: "${fw}"`);
+            }
+        }
+        // --- LLM 层检查（语气+语法） ---
+        if (options.tone || options.checkGrammar) {
+            const criteriaParts = [];
+            if (options.tone)
+                criteriaParts.push(`Tone must be: ${options.tone}`);
+            if (options.checkGrammar)
+                criteriaParts.push("No spelling or grammar errors");
+            const criteria = criteriaParts.join(". ");
+            const userMsg = `Evaluate this text:\n\n"${trimmed.slice(0, 2000)}"\n\nCriteria: ${criteria}`;
+            const { passed: llmOk, reason } = await llm.judge(QUALITY_PROMPT, userMsg);
+            if (options.tone) {
+                checks.push(`语气 "${options.tone}": ${llmOk ? "✓" : "✗"}`);
+                if (!llmOk)
+                    failures.push(`语气不符合 "${options.tone}": ${reason}`);
+            }
+            if (options.checkGrammar && !llmOk) {
+                failures.push(`语法/拼写问题: ${reason}`);
+            }
+        }
+        const passed = failures.length === 0;
+        const duration = Date.now() - start;
+        return {
+            passed,
+            type: "quality",
+            name: `质量断言: ${selector}`,
+            message: passed
+                ? `"${selector}" 内容质量通过 [${checks.join(", ")}]`
+                : failures.join("; "),
+            duration,
+            details: `文本: "${trimmed.slice(0, 300)}"\n检查项:\n${checks.map((c) => `  ${c}`).join("\n")}`,
+        };
+    }
+    catch (err) {
+        return {
+            passed: false,
+            type: "quality",
+            name: `质量断言: ${selector}`,
+            message: `质量检查异常: ${err.message}`,
+            duration: Date.now() - start,
+            details: err.stack,
+        };
+    }
+}
+
+// ============================================================
+// AI Engine — 异常检测断言器
+// ============================================================
+/**
+ * 全局异常检测 — 检查页面是否处于错误/空白/加载失败等非预期状态
+ */
+async function assertAnomaly(page, llm, options = {}) {
+    const start = Date.now();
+    const { checkBlank = true, checkError = true, checkLoading = true, } = options;
+    try {
+        // 收集页面信息
+        const url = page.url();
+        const title = await page.title().catch(() => "");
+        const bodyText = await page.locator("body").textContent().catch(() => "") ?? "";
+        // 规则层快速检查
+        const quickFailures = [];
+        if (checkBlank && bodyText.trim().length < 10) {
+            quickFailures.push("页面几乎为空（可能白屏）");
+        }
+        if (checkError) {
+            const lowerText = bodyText.toLowerCase();
+            const errorPatterns = [
+                "500", "internal server error", "something went wrong",
+                "page not found", "404", "access denied", "403",
+            ];
+            for (const pattern of errorPatterns) {
+                if (lowerText.includes(pattern)) {
+                    quickFailures.push(`检测到错误提示: "${pattern}"`);
+                    break;
+                }
+            }
+        }
+        if (checkLoading) {
+            const lowerText = bodyText.toLowerCase();
+            if (bodyText.trim().length > 0 && bodyText.trim().length < 50) {
+                const loadingWords = ["loading", "加载", "please wait", "spinner"];
+                for (const w of loadingWords) {
+                    if (lowerText.includes(w)) {
+                        quickFailures.push(`页面可能卡在加载状态: "${w}"`);
+                        break;
+                    }
+                }
+            }
+        }
+        // 如果规则层已发现异常，直接返回
+        if (quickFailures.length > 0) {
+            const duration = Date.now() - start;
+            return {
+                passed: false,
+                type: "anomaly",
+                name: "异常检测",
+                message: quickFailures.join("; "),
+                duration,
+                details: `URL: ${url}\nTitle: "${title}"\nBody 长度: ${bodyText.length}`,
+            };
+        }
+        // LLM 层深度检查
+        const userMsg = [
+            `URL: ${url}`,
+            `Title: "${title}"`,
+            `Body text (first 2000 chars):`,
+            bodyText.slice(0, 2000),
+        ].join("\n");
+        const { passed, reason, raw } = await llm.judge(ANOMALY_PROMPT, userMsg, "NO");
+        const duration = Date.now() - start;
+        return {
+            passed,
+            type: "anomaly",
+            name: "异常检测",
+            message: passed
+                ? "页面状态正常 ✓"
+                : `检测到异常: ${reason}`,
+            duration,
+            details: `URL: ${url}\nTitle: "${title}"\nBody 长度: ${bodyText.length}\nLLM: ${raw}`,
+            rawResponse: raw,
+        };
+    }
+    catch (err) {
+        return {
+            passed: false,
+            type: "anomaly",
+            name: "异常检测",
+            message: `异常检测失败: ${err.message}`,
+            duration: Date.now() - start,
+            details: err.stack,
+        };
+    }
+}
+
+// ============================================================
+// AI Engine — AITest 主类（Fluent API）
+// ============================================================
+class AITest {
+    constructor(name, options) {
+        this.tasks = [];
+        this.name = name;
+        this.stagehand = options.stagehand;
+        const llmConfig = options.llm ?? {
+            model: process.env.AI_MODEL || "deepseek/deepseek-v4-flash",
+        };
+        this.llm = new LLMClient(llmConfig);
+        this.options = {
+            screenshotOnFailure: options.screenshotOnFailure ?? true,
+            bailOnFailure: options.bailOnFailure ?? false,
+        };
+    }
+    // ==========================================================
+    // Builder API — 链式方法
+    // ==========================================================
+    /** 自然语言交互：AI 自动找元素并操作（填充/点击/选择等） */
+    act(instruction) {
+        this.tasks.push({
+            type: "act",
+            name: `Act: ${instruction}`,
+            execute: async (_page) => {
+                const start = Date.now();
+                try {
+                    await this.stagehand.act(instruction);
+                    return {
+                        passed: true,
+                        type: "act",
+                        name: `Act: ${instruction}`,
+                        message: `✓ ${instruction}`,
+                        duration: Date.now() - start,
+                    };
+                }
+                catch (err) {
+                    return {
+                        passed: false,
+                        type: "act",
+                        name: `Act: ${instruction}`,
+                        message: `✗ ${instruction}: ${err.message}`,
+                        duration: Date.now() - start,
+                        details: err.stack,
+                    };
+                }
+            },
+        });
+        return this;
+    }
+    /** 结构化提取：从页面元素提取数据并校验 Schema */
+    extract(selector, schema, instruction) {
+        this.tasks.push({
+            type: "extract",
+            name: `提取: ${selector}`,
+            execute: (page) => assertExtraction(page, this.llm, selector, {
+                schema,
+                instruction,
+            }),
+        });
+        return this;
+    }
+    /** 情感断言：判断文本情感是否符合预期 */
+    assertSentiment(selector, expected, criteria) {
+        this.tasks.push({
+            type: "sentiment",
+            name: `情感: ${selector}`,
+            execute: (page) => assertSentiment(page, this.llm, selector, {
+                expected,
+                criteria,
+            }),
+        });
+        return this;
+    }
+    /** 内容质量断言：检查长度、关键词、语气、禁用词等 */
+    assertQuality(selector, opts) {
+        this.tasks.push({
+            type: "quality",
+            name: `质量: ${selector}`,
+            execute: (page) => assertQuality(page, this.llm, selector, opts),
+        });
+        return this;
+    }
+    /** 异常检测：检查页面是否处于错误/空白/加载失败等非预期状态 */
+    detectAnomaly(opts = {}) {
+        this.tasks.push({
+            type: "anomaly",
+            name: "异常检测",
+            execute: (page) => assertAnomaly(page, this.llm, opts),
+        });
+        return this;
+    }
+    /** 自定义断言 */
+    assertCustom(label, fn) {
+        this.tasks.push({
+            type: "custom",
+            name: label,
+            execute: async (page) => {
+                const result = await fn(page, this.llm, this.stagehand);
+                return { ...result, type: "custom" };
+            },
+        });
+        return this;
+    }
+    // ==========================================================
+    // 执行
+    // ==========================================================
+    async run(page) {
+        const startTime = Date.now();
+        const results = [];
+        let totalTokens = 0;
+        for (const task of this.tasks) {
+            const result = await task.execute(page, this.stagehand);
+            // 失败时截图
+            if (!result.passed && this.options.screenshotOnFailure) {
+                try {
+                    const buf = await page.screenshot();
+                    result.screenshot = buf.toString("base64");
+                }
+                catch {
+                    // 截图失败不阻断
+                }
+            }
+            results.push(result);
+            // bailOnFailure
+            if (!result.passed && this.options.bailOnFailure) {
+                console.warn(`[AITest] bailOnFailure 触发，跳过剩余 ${this.tasks.length - results.length} 个任务`);
+                break;
+            }
+        }
+        totalTokens = this.llm.getTotalTokens();
+        const passedCount = results.filter((r) => r.passed).length;
+        const totalDuration = Date.now() - startTime;
+        return {
+            name: this.name,
+            assertions: results,
+            hasFailure: passedCount < results.length,
+            passRate: results.length > 0 ? passedCount / results.length : 1,
+            totalDuration,
+            estimatedTokens: totalTokens,
+        };
+    }
+}
+
+// ============================================================
+// Share — 报告聚合器
+// ============================================================
+class Reporter {
+    constructor(planName) {
+        this.screenshots = [];
+        this.planName = planName;
+        this.startedAt = new Date().toISOString();
+    }
+    /** 构建报告 */
+    build(ruleResults, aiResults, actionTotal, actionFailed) {
+        const ruleLayer = this.buildRuleLayer(ruleResults);
+        const aiLayer = aiResults.length === 0 && actionTotal === 0
+            ? null
+            : this.buildAILayer(aiResults);
+        // 汇集失败项
+        const failures = [];
+        for (const r of ruleResults) {
+            for (const a of r.assertions.filter((a) => !a.passed)) {
+                failures.push({
+                    layer: "rule",
+                    testName: r.name,
+                    assertionName: a.name,
+                    message: a.message,
+                    details: a.details,
+                });
+            }
+        }
+        for (const r of aiResults) {
+            for (const a of r.assertions.filter((a) => !a.passed)) {
+                failures.push({
+                    layer: "ai",
+                    testName: r.name,
+                    assertionName: a.name,
+                    message: a.message,
+                    details: a.details,
+                });
+            }
+        }
+        // 收集截图
+        const allResults = [
+            ...ruleResults.flatMap((r) => r.assertions),
+            ...aiResults.flatMap((r) => r.assertions),
+        ];
+        for (const a of allResults) {
+            if ("screenshot" in a && a.screenshot) {
+                this.screenshots.push(a.screenshot);
+            }
+        }
+        const totalPassed = ruleLayer.passed + (aiLayer?.passed ?? 0);
+        const totalFailed = ruleLayer.failed + (aiLayer?.failed ?? 0);
+        const totalSkipped = ruleLayer.skipped + (aiLayer?.skipped ?? 0);
+        const totalDuration = ruleLayer.duration + (aiLayer?.duration ?? 0);
+        // 估算成本：每 1M token ≈ DeepSeek $0.28 (输入) + $1.10 (输出)
+        const totalTokens = aiResults.reduce((sum, r) => sum + r.estimatedTokens, 0);
+        const costEstimate = totalTokens > 0
+            ? Math.round(totalTokens / 1000 * 0.001 * 10000) / 10000 // 粗略估算
+            : 0;
+        return {
+            planName: this.planName,
+            startedAt: this.startedAt,
+            summary: {
+                total: totalPassed + totalFailed + totalSkipped,
+                passed: totalPassed,
+                failed: totalFailed,
+                skipped: totalSkipped,
+                duration: totalDuration,
+                costEstimate,
+            },
+            layers: {
+                rule: ruleLayer,
+                ai: aiLayer,
+                actions: { total: actionTotal, failed: actionFailed },
+            },
+            failures,
+            artifacts: {
+                screenshots: this.screenshots.map((_, i) => `screenshot-${i + 1}.png`),
+            },
+        };
+    }
+    buildRuleLayer(results) {
+        const allAssertions = results.flatMap((r) => r.assertions);
+        const passed = allAssertions.filter((a) => a.passed).length;
+        const failed = allAssertions.filter((a) => !a.passed).length;
+        const totalDuration = results.reduce((sum, r) => sum + r.totalDuration, 0);
+        return {
+            passed,
+            failed,
+            skipped: 0,
+            total: allAssertions.length,
+            passRate: allAssertions.length > 0 ? passed / allAssertions.length : 1,
+            duration: totalDuration,
+        };
+    }
+    buildAILayer(results) {
+        const allAssertions = results.flatMap((r) => r.assertions);
+        const passed = allAssertions.filter((a) => a.passed).length;
+        const failed = allAssertions.filter((a) => !a.passed).length;
+        const totalDuration = results.reduce((sum, r) => sum + r.totalDuration, 0);
+        return {
+            passed,
+            failed,
+            skipped: 0,
+            total: allAssertions.length,
+            passRate: allAssertions.length > 0 ? passed / allAssertions.length : 1,
+            duration: totalDuration,
+        };
+    }
+}
+
+// ============================================================
+// Share — HTML 报告生成器
+// ============================================================
+function writeHtmlReport(report, outputDir) {
+    const path = resolve(outputDir, "report.html");
+    writeFileSync(path, buildHtml(report));
+    return path;
+}
+function buildHtml(report) {
+    const { planName, startedAt, layers, failures } = report;
+    const wallDuration = report.wallDuration ?? report.summary.duration;
+    const rule = layers.rule;
+    const ai = layers.ai;
+    const act = layers.actions;
+    // 格式化时间
+    const formattedTime = formatTime(startedAt);
+    const durationStr = formatDuration(wallDuration);
+    return `<!DOCTYPE html>
+<html lang="zh">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>${esc(planName)} — 测试报告</title>
+<style>
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  body { font: 14px/1.6 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; color: #1a1a2e; background: #f0f2f5; }
+  .wrap { max-width: 1024px; margin: 0 auto; padding: 24px 16px; }
+
+  h1 { font-size: 22px; margin-bottom: 2px; }
+  .time { color: #999; font-size: 12px; margin-bottom: 20px; }
+
+  /* stat row */
+  .stat-row { display: flex; gap: 10px; margin-bottom: 20px; flex-wrap: wrap; }
+  .stat-card { flex: 1; min-width: 140px; background: #fff; border-radius: 10px; padding: 14px 16px; box-shadow: 0 1px 4px rgba(0,0,0,.05); }
+  .stat-card .title { font-size: 12px; color: #999; margin-bottom: 6px; }
+  .stat-card .body { display: flex; align-items: baseline; gap: 8px; }
+  .stat-card .val { font-size: 30px; font-weight: 700; }
+  .stat-card .meta { font-size: 12px; color: #bbb; }
+  .v-pass { color: #10b981; }
+  .v-fail { color: #ef4444; }
+  .v-info { color: #6366f1; }
+
+  /* section */
+  .section { background: #fff; border-radius: 10px; padding: 20px; margin-bottom: 14px; box-shadow: 0 1px 4px rgba(0,0,0,.05); }
+  .section h2 { font-size: 15px; margin-bottom: 10px; display: flex; align-items: center; gap: 6px; }
+  .bar-wrap { height: 6px; background: #e5e7eb; border-radius: 3px; margin-bottom: 10px; overflow: hidden; }
+  .bar-inner { height: 100%; border-radius: 3px; transition: width .3s; }
+  .bar-pass { background: #10b981; }
+  .bar-fail { background: #ef4444; }
+
+  /* failures */
+  .fail-item { background: #fef2f2; border-radius: 6px; padding: 10px 14px; margin-bottom: 8px; }
+  .fail-item .layer { font-size: 11px; color: #991b1b; font-weight: 600; margin-bottom: 3px; }
+  .fail-item .msg { font-size: 13px; }
+  .fail-item .detail { font-size: 12px; color: #999; margin-top: 4px; white-space: pre-wrap; word-break: break-all; }
+
+  /* screenshots */
+  .shots { display: grid; grid-template-columns: repeat(auto-fill, minmax(180px, 1fr)); gap: 10px; }
+  .shots figure { cursor: pointer; transition: transform .15s; }
+  .shots figure:hover { transform: scale(1.02); }
+  .shots img { width: 100%; border-radius: 6px; border: 1px solid #e5e7eb; display: block; }
+  .shots figcaption { font-size: 11px; color: #999; text-align: center; margin-top: 4px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+
+  /* lightbox */
+  .lightbox { display: none; position: fixed; inset: 0; background: rgba(0,0,0,.88); z-index: 999; align-items: center; justify-content: center; }
+  .lightbox.show { display: flex; }
+  .lightbox img { max-width: 92vw; max-height: 92vh; border-radius: 6px; cursor: zoom-out; }
+  .lightbox .close { position: absolute; top: 16px; right: 24px; color: #fff; font-size: 32px; cursor: pointer; line-height: 1; }
+  .lightbox .caption { position: absolute; bottom: 16px; left: 50%; transform: translateX(-50%); color: #ccc; font-size: 13px; }
+  .lightbox .nav { position: absolute; top: 50%; transform: translateY(-50%); color: #fff; font-size: 40px; cursor: pointer; padding: 16px; user-select: none; }
+  .lightbox .prev { left: 8px; }
+  .lightbox .next { right: 8px; }
+</style>
+</head>
+<body>
+
+<div class="wrap">
+  <h1>📊 ${esc(planName)}</h1>
+  <div class="time">${formattedTime}</div>
+
+  <div class="stat-row">
+    <div class="stat-card">
+      <div class="title">📏 Rule 断言</div>
+      <div class="body">
+        <span class="val v-pass">${rule.passed}</span><span class="meta">通过</span>
+        <span class="val v-fail">${rule.failed}</span><span class="meta">失败</span>
+      </div>
+    </div>
+    ${ai ? `
+    <div class="stat-card">
+      <div class="title">🤖 AI 断言</div>
+      <div class="body">
+        <span class="val v-pass">${ai.passed}</span><span class="meta">通过</span>
+        <span class="val v-fail">${ai.failed}</span><span class="meta">失败</span>
+      </div>
+    </div>` : ""}
+    <div class="stat-card">
+      <div class="title">🖱️ 操作</div>
+      <div class="body">
+        <span class="val v-pass">${act.total - act.failed}</span><span class="meta">成功</span>
+        <span class="val v-fail">${act.failed}</span><span class="meta">失败</span>
+      </div>
+    </div>
+    <div class="stat-card">
+      <div class="title">⏱️ 总耗时</div>
+      <div class="body"><span class="val v-info">${durationStr}</span></div>
+    </div>
+  </div>
+
+  ${buildLayerSection("📏 Rule Engine", rule)}
+  ${buildActionSection("🖱️ 操作详情", act)}
+  ${ai ? buildLayerSection("🤖 AI Engine", ai) : ""}
+  ${buildFailuresSection(failures)}
+  ${buildScreenshotsSection(report)}
+</div>
+
+<div class="lightbox" id="lightbox" onclick="closeLightbox()">
+  <span class="close">&times;</span>
+  <span class="nav prev" onclick="event.stopPropagation();navLightbox(-1)">‹</span>
+  <img id="lb-img" src="" alt="" onclick="event.stopPropagation()">
+  <span class="nav next" onclick="event.stopPropagation();navLightbox(1)">›</span>
+  <div class="caption" id="lb-caption"></div>
+</div>
+
+<script>
+var lbImages = [];
+var lbIndex = 0;
+
+document.querySelectorAll('.shots img').forEach(function(img, idx) {
+  lbImages.push({ src: img.src, alt: (img.nextElementSibling || {}).textContent || img.alt });
+  img.addEventListener('click', function(e) { e.stopPropagation(); openLightbox(idx); });
+  img.title = '点击放大 · 键盘 ← → 切换 · Esc 关闭';
+});
+
+function openLightbox(idx) {
+  lbIndex = idx;
+  document.getElementById('lb-img').src = lbImages[idx].src;
+  document.getElementById('lb-caption').textContent = lbImages[idx].alt;
+  document.getElementById('lightbox').classList.add('show');
+  document.body.style.overflow = 'hidden';
+}
+function closeLightbox() {
+  document.getElementById('lightbox').classList.remove('show');
+  document.body.style.overflow = '';
+}
+function navLightbox(dir) {
+  lbIndex = (lbIndex + dir + lbImages.length) % lbImages.length;
+  document.getElementById('lb-img').src = lbImages[lbIndex].src;
+  document.getElementById('lb-caption').textContent = lbImages[lbIndex].alt;
+}
+document.addEventListener('keydown', function(e) {
+  if (!document.getElementById('lightbox').classList.contains('show')) return;
+  if (e.key === 'Escape') closeLightbox();
+  if (e.key === 'ArrowLeft') navLightbox(-1);
+  if (e.key === 'ArrowRight') navLightbox(1);
+});
+</script>
+</body>
+</html>`;
+}
+function buildLayerSection(title, layer) {
+    const passPct = (layer.passRate * 100).toFixed(0);
+    const isAllPass = layer.failed === 0;
+    return `
+  <div class="section">
+    <h2><span>${isAllPass ? "✅" : "❌"}</span> ${title}</h2>
+    <div class="bar-wrap">
+      <div class="bar-inner bar-${isAllPass ? "pass" : "fail"}" style="width:${passPct}%"></div>
+    </div>
+    <p style="font-size:13px;color:#999">
+      通过率 ${passPct}% &nbsp;|&nbsp; ${layer.passed}/${layer.total} 通过 &nbsp;|&nbsp; ${layer.duration}ms
+    </p>
+  </div>`;
+}
+function buildActionSection(title, actions) {
+    if (actions.total === 0)
+        return "";
+    const ok = actions.total - actions.failed;
+    const passPct = actions.total > 0 ? (ok / actions.total * 100).toFixed(0) : "0";
+    const isAllPass = actions.failed === 0;
+    return `
+  <div class="section">
+    <h2><span>${isAllPass ? "✅" : "⚠️"}</span> ${title}</h2>
+    <div class="bar-wrap">
+      <div class="bar-inner bar-${isAllPass ? "pass" : "fail"}" style="width:${passPct}%"></div>
+    </div>
+    <p style="font-size:13px;color:#999">
+      共 ${actions.total} 次 &nbsp;|&nbsp; 成功 ${ok} &nbsp;|&nbsp; 失败 ${actions.failed}
+    </p>
+  </div>`;
+}
+function buildFailuresSection(failures) {
+    if (failures.length === 0)
+        return "";
+    const items = failures.map((f) => `
+    <div class="fail-item">
+      <div class="layer">${f.layer === "rule" ? "📏 Rule" : f.layer === "ai" ? "🤖 AI" : "🖱️ Action"} | ${esc(f.testName)}</div>
+      <div class="msg">${esc(f.message)}</div>
+      ${f.details ? `<div class="detail">${esc(f.details)}</div>` : ""}
+    </div>`).join("");
+    return `
+  <div class="section">
+    <h2><span>❌</span> 失败详情 (${failures.length})</h2>
+    ${items}
+  </div>`;
+}
+function buildScreenshotsSection(report) {
+    const paths = report.artifacts.screenshots ?? [];
+    if (paths.length === 0)
+        return "";
+    const images = paths.map((p) => {
+        const name = p.replace(/^.*[\\/]/, "");
+        try {
+            if (existsSync(p)) {
+                const buf = readFileSync(p);
+                const b64 = buf.toString("base64");
+                const ext = p.split(".").pop()?.toLowerCase() ?? "png";
+                const mime = ext === "jpg" ? "jpeg" : ext;
+                return `<figure><img src="data:image/${mime};base64,${b64}" alt="${esc(name)}"><figcaption>${esc(name)}</figcaption></figure>`;
+            }
+        }
+        catch { /* skip */ }
+        return `<figure><figcaption>${esc(name)} (无法加载)</figcaption></figure>`;
+    }).join("");
+    return `
+  <div class="section">
+    <h2><span>📸</span> 截图</h2>
+    <div class="shots">${images}</div>
+  </div>`;
+}
+function esc(s) {
+    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function formatTime(iso) {
+    try {
+        const d = new Date(iso);
+        const pad = (n) => String(n).padStart(2, "0");
+        return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
+    }
+    catch {
+        return iso;
+    }
+}
+function formatDuration(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    const sec = Math.floor(ms / 1000);
+    if (sec < 60)
+        return `${sec}s`;
+    const min = Math.floor(sec / 60);
+    const remain = sec % 60;
+    return remain > 0 ? `${min}m ${remain}s` : `${min}m`;
+}
+
+// ============================================================
+// Share — Composition API（Vue3 风格组合式测试）
+// ============================================================
+// -----------------------------------------------------------
+// Thenable 包装 — await 时自动执行
+// -----------------------------------------------------------
+/**
+ * 可自动执行的 RuleTest
+ *
+ * 用法：
+ *   await check("名称").element("input").performance("FCP")
+ *   //                      ↑ 链式构建       ↑
+ *   //        ↑ await 触发 .run(page)
+ */
+class AutoRuleTest extends RuleTest {
+    constructor(name, page, onResult) {
+        super(name);
+        // 简写别名 — 直接委托给父类方法
+        this.element = this.assertElement;
+        this.text = this.assertText;
+        this.attribute = this.assertAttribute;
+        this.url = this.assertUrl;
+        this.title = this.assertTitle;
+        this.meta = this.assertMeta;
+        this.status = this.assertStatusCode;
+        this.performance = this.assertPerformance;
+        this.accessibility = this.assertAccessibility;
+        this.custom = this.assertCustom;
+        this._page = page;
+        this._onResult = onResult;
+    }
+    then(onfulfilled, onrejected) {
+        return this.run(this._page)
+            .then((r) => {
+            this._onResult(r);
+            return r;
+        })
+            .then(onfulfilled, onrejected);
+    }
+}
+/**
+ * 可自动执行的 AITest
+ *
+ * 用法：
+ *   await inspect("名称").anomaly().sentiment(".msg", "positive")
+ */
+class AutoAITest extends AITest {
+    constructor(name, page, onResult, stagehand) {
+        super(name, { stagehand });
+        // 简写别名
+        this.anomaly = this.detectAnomaly;
+        this.sentiment = this.assertSentiment;
+        this.quality = this.assertQuality;
+        this._page = page;
+        this._onResult = onResult;
+    }
+    then(onfulfilled, onrejected) {
+        return this.run(this._page)
+            .then((r) => {
+            this._onResult(r);
+            return r;
+        })
+            .then(onfulfilled, onrejected);
+    }
+}
+// -----------------------------------------------------------
+// createTestContext — 创建组合式上下文
+// -----------------------------------------------------------
+function createTestContext(page, options) {
+    const name = options?.planName ?? "Test Plan";
+    const ruleResults = [];
+    const aiResults = [];
+    let actionTotal = 0;
+    let actionFailed = 0;
+    let screenshotCount = 0;
+    const screenshotPaths = [];
+    const outputDir = options?.outputDir ?? resolve(process.cwd(), "logs");
+    const ctx = {
+        name,
+        page,
+        stagehand: options?.stagehand,
+        // ======== 核心 API ========
+        has: async (selector) => {
+            try {
+                return (await page.locator(selector).count()) > 0;
+            }
+            catch {
+                return false;
+            }
+        },
+        which: async (selectors) => {
+            const counts = await Promise.all(selectors.map((s) => page
+                .locator(s)
+                .count()
+                .catch(() => 0)));
+            return counts.findIndex((c) => c > 0);
+        },
+        click: async (selector, nth) => {
+            try {
+                const items = page.locator(selector);
+                const count = await items.count();
+                if (count === 0)
+                    return; // 元素不存在，静默跳过
+                const visible = [];
+                for (let i = 0; i < count; i++) {
+                    if (await items
+                        .nth(i)
+                        .isVisible()
+                        .catch(() => false)) {
+                        visible.push(i);
+                    }
+                }
+                const target = nth ?? 0;
+                if (visible.length === 0)
+                    throw new Error(`所有 ${count} 个匹配元素都不可见`);
+                if (target >= visible.length)
+                    throw new Error(`只有 ${visible.length} 个可见元素，无法取第 ${target} 个`);
+                actionTotal++;
+                await items.nth(visible[target]).click();
+                console.log(`  ✓  click ${selector}${nth !== undefined ? `[${nth}]` : ""}\n`);
+            }
+            catch (err) {
+                actionFailed++;
+                console.error(`  ✗  click ${selector}: ${err.message}  [${page.url()}]\n`);
+            }
+        },
+        fill: async (selector, value) => {
+            actionTotal++;
+            try {
+                await page.locator(selector).first().fill(value);
+                console.log(`  ✓  fill ${selector}\n`);
+            }
+            catch (err) {
+                actionFailed++;
+                console.error(`  ✗  fill ${selector}: ${err.message}  [${page.url()}]\n`);
+            }
+        },
+        screenshot: async (label) => {
+            const dir = resolve(outputDir, "screenshots");
+            mkdirSync(dir, { recursive: true });
+            const step = String(screenshotCount++).padStart(2, "0");
+            const name = `${step}-${label.replace(/[^a-zA-Z0-9\u4e00-\u9fa5_-]/g, "_")}.png`;
+            const filepath = resolve(dir, name);
+            await page.screenshot({ path: filepath, fullPage: true });
+            screenshotPaths.push(filepath);
+            console.log(`📸 ${name}`);
+        },
+        sleep: async (ms) => {
+            await page.waitForTimeout(ms);
+        },
+        ai: async (instruction) => {
+            const aiTest = new AutoAITest("AI", page, (r) => {
+                aiResults.push(r);
+                console.log(`🤖 ${r.assertions.map((a) => a.message).join("; ")}\n`);
+            }, options?.stagehand);
+            aiTest.act(instruction);
+            aiTest.anomaly();
+            await aiTest;
+        },
+        wait: async (selector, timeout = 10000) => {
+            await page.locator(selector).first().waitFor({ state: "visible", timeout }).catch(() => { });
+        },
+        // ======== 进阶 API ========
+        check: (testName) => {
+            return new AutoRuleTest(testName, page, (r) => {
+                ruleResults.push(r);
+                printCheckResult(testName, r);
+            });
+        },
+        task: async (label, fn, aiFallback) => {
+            actionTotal++;
+            let via = "";
+            try {
+                await fn(page);
+                via = aiFallback ? "原生 (免费)" : "";
+                console.log(`  ✓  ${via}\n`);
+                return true;
+            }
+            catch (nativeErr) {
+                if (!aiFallback) {
+                    actionFailed++;
+                    console.error(`  ✗  失败: ${nativeErr.message}\n`);
+                    return false;
+                }
+                console.log(`  → 原生失败，降级 AI...`);
+                try {
+                    const aiTest = new AutoAITest(label, page, (r) => {
+                        aiResults.push(r);
+                        printInspectResult(label, r);
+                    }, options?.stagehand);
+                    aiTest.act(aiFallback);
+                    await aiTest;
+                    console.log(`  ✓  AI 兜底成功\n`);
+                    return false;
+                }
+                catch (aiErr) {
+                    actionFailed++;
+                    console.error(`  ✗  AI 也失败: ${aiErr.message}\n`);
+                    return false;
+                }
+            }
+        },
+        inspect: (testName) => {
+            return new AutoAITest(testName, page, (r) => {
+                aiResults.push(r);
+                printInspectResult(testName, r);
+            }, options?.stagehand);
+        },
+        network: () => {
+            const netCalls = [];
+            // 用原生 Playwright page.on("response") 实时收集
+            page.on("response", async (response) => {
+                try {
+                    const body = await response.text();
+                    netCalls.push({
+                        url: response.url(),
+                        status: response.status(),
+                        headers: response.headers(),
+                        body,
+                        timestamp: Date.now(),
+                    });
+                }
+                catch {
+                    netCalls.push({
+                        url: response.url(),
+                        status: response.status(),
+                        headers: response.headers(),
+                        body: "",
+                        timestamp: Date.now(),
+                    });
+                }
+            });
+            return {
+                getCalls: () => [...netCalls],
+                filter(urlPattern) {
+                    return netCalls.filter((c) => typeof urlPattern === "string"
+                        ? c.url.includes(urlPattern)
+                        : urlPattern.test(c.url));
+                },
+                assertCall(urlPattern, opts = {}) {
+                    const matched = netCalls.filter((c) => typeof urlPattern === "string"
+                        ? c.url.includes(urlPattern)
+                        : urlPattern.test(c.url));
+                    if (matched.length === 0) {
+                        return { passed: false, message: `未捕获到: ${urlPattern}` };
+                    }
+                    const call = matched[matched.length - 1];
+                    if (opts.status !== undefined && call.status !== opts.status) {
+                        return {
+                            passed: false,
+                            message: `状态码期望 ${opts.status}，实际 ${call.status}`,
+                        };
+                    }
+                    if (opts.bodyContains && !call.body.includes(opts.bodyContains)) {
+                        return {
+                            passed: false,
+                            message: `响应体不包含 "${opts.bodyContains}"`,
+                        };
+                    }
+                    if (opts.bodySchema) {
+                        try {
+                            const json = JSON.parse(call.body);
+                            for (const [key, type] of Object.entries(opts.bodySchema)) {
+                                if (!(key in json))
+                                    return { passed: false, message: `缺少字段: ${key}` };
+                                if (type !== "any" && typeof json[key] !== type)
+                                    return {
+                                        passed: false,
+                                        message: `${key}: 期望 ${type}，实际 ${typeof json[key]}`,
+                                    };
+                            }
+                        }
+                        catch {
+                            return { passed: false, message: "响应体非有效 JSON" };
+                        }
+                    }
+                    const shortUrl = call.url.length > 60 ? call.url.slice(0, 57) + "..." : call.url;
+                    return { passed: true, message: `HTTP ${call.status} — ${shortUrl}` };
+                },
+            };
+        },
+    };
+    // 挂载 finalize 方法
+    ctx._finalize = () => {
+        const reporter = new Reporter(name);
+        const report = reporter.build(ruleResults, aiResults, actionTotal, actionFailed);
+        report.artifacts.screenshots = screenshotPaths;
+        return report;
+    };
+    return ctx;
+}
+/**
+ * 定义测试计划
+ *
+ * @example
+ * ```ts
+ * export default definePlan("PWA 登录", async ({ page, has, click, fill, screenshot, check, ai }) => {
+ *   await page.goto("https://example.com/login");
+ *
+ *   await check("登录页元素")
+ *     .element("input", { minCount: 2 })
+ *     .performance("FCP", { lt: 3000 });
+ *
+ *   await fill('input[type="email"]', "test@test.com");
+ *   await click('[type="submit"]');
+ *   await screenshot("登录后");
+ *
+ *   await check("登录结果")
+ *     .url("/dashboard");
+ * });
+ * ```
+ */
+function definePlan(name, setup) {
+    return {
+        name,
+        run: async (page, runOptions) => {
+            console.log(`\n🚀 开始执行计划: ${name}\n`);
+            const ctx = createTestContext(page, {
+                planName: name,
+                stagehand: runOptions?.stagehand,
+                outputDir: runOptions?.outputDir,
+            });
+            const startTime = Date.now();
+            await setup(ctx);
+            const report = ctx._finalize();
+            report.startedAt = new Date(startTime).toISOString();
+            report.wallDuration = Date.now() - startTime;
+            printReport(report);
+            // 写 JSON 报告
+            const out = runOptions?.outputDir ?? resolve(process.cwd(), "logs");
+            const jsonPath = resolve(out, "report.json");
+            writeFileSync(jsonPath, JSON.stringify(report, null, 2));
+            // 写 HTML 报告
+            const htmlPath = writeHtmlReport(report, out);
+            console.log(`📄 报告已保存: ${jsonPath}`);
+            console.log(`📄 报告已保存: ${htmlPath}\n`);
+            return report;
+        },
+    };
+}
+// -----------------------------------------------------------
+// 打印工具
+// -----------------------------------------------------------
+function printCheckResult(name, r) {
+    const icon = r.hasFailure ? "❌" : "✅";
+    console.log(`🔧 ${name}`);
+    console.log(`  ${icon} ${(r.passRate * 100).toFixed(0)}%  |  ${r.totalDuration}ms`);
+    for (const a of r.assertions) {
+        console.log(`     ${a.passed ? "✓" : "✗"}  ${a.message} (${a.duration}ms)`);
+    }
+    console.log("");
+}
+function printInspectResult(name, r) {
+    const icon = r.hasFailure ? "❌" : "✅";
+    console.log(`🤖 ${name}`);
+    console.log(`  ${icon} ${(r.passRate * 100).toFixed(0)}%  |  ${r.totalDuration}ms  |  Token: ${r.estimatedTokens}`);
+    for (const a of r.assertions) {
+        console.log(`     ${a.passed ? "✓" : "✗"}  ${a.message} (${a.duration}ms)`);
+    }
+    console.log("");
+}
+function printReport(report) {
+    const { summary, layers } = report;
+    console.log(`\n${"=".repeat(50)}`);
+    console.log(`  📊 ${report.planName}`);
+    console.log(`  总断言: ${summary.total}  |  通过: ${summary.passed}  |  失败: ${summary.failed}`);
+    console.log(`  耗时: ${summary.duration}ms  |  AI 成本: $${summary.costEstimate.toFixed(4)}`);
+    if (layers.actions.total > 0) {
+        console.log(`  操作: ${layers.actions.total} 次 (失败 ${layers.actions.failed})`);
+    }
+    console.log(`${"=".repeat(50)}\n`);
+}
+/** 判断当前文件是否作为入口直接运行 */
+function isMain(metaUrl) {
+    const entry = process.argv[1]?.replace(/\\/g, "/") ?? "";
+    const self = metaUrl.replace("file:///", "").replace(/\\/g, "/");
+    return entry === self || entry.endsWith("/" + self.split("/").pop());
+}
+
+// ============================================================
+// 用户配置 — h2o.config.ts
+// ============================================================
+/** 定义配置（纯类型助手，不做运行时处理） */
+function defineConfig(config) {
+    return config;
+}
+// -----------------------------------------------------------
+// 配置解析 — 优先级：用户配置 > 环境变量 > 默认值
+// -----------------------------------------------------------
+// 从用户项目根目录加载（process.cwd()）
+const CONFIG_FILES = [
+    "h2o.config.ts",
+    "h2o.config.js",
+    "h2o.config.mjs",
+];
+let _cached = null;
+async function loadUserConfig() {
+    if (_cached)
+        return _cached;
+    let userConfig = {};
+    // 尝试加载用户配置文件（从 process.cwd() 解析绝对路径）
+    for (const file of CONFIG_FILES) {
+        try {
+            const absPath = resolve(process.cwd(), file);
+            const mod = await import(pathToFileURL(absPath).href);
+            userConfig = mod.default ?? mod;
+            break;
+        }
+        catch { /* file not found, try next */ }
+    }
+    // 合并默认值
+    _cached = {
+        ai: {
+            apiKey: userConfig.ai?.apiKey ?? process.env.DEEPSEEK_API_KEY ?? process.env.OPENAI_API_KEY,
+            model: userConfig.ai?.model ?? process.env.AI_MODEL ?? "deepseek/deepseek-v4-flash",
+            timeout: userConfig.ai?.timeout ?? (Number(process.env.AI_TIMEOUT) || 30000),
+            temperature: userConfig.ai?.temperature ?? 0.1,
+            maxTokens: userConfig.ai?.maxTokens ?? 1024,
+        },
+        output: {
+            dir: userConfig.output?.dir ?? process.env.OUTPUT_DIR ?? "./logs",
+        },
+        browser: {
+            headless: userConfig.browser?.headless ?? process.env.HEADLESS === "true",
+            viewport: userConfig.browser?.viewport ?? {
+                width: Number(process.env.VIEWPORT_WIDTH) || 1280,
+                height: Number(process.env.VIEWPORT_HEIGHT) || 720,
+            },
+        },
+    };
+    return _cached;
+}
+
+// ============================================================
+// Share — 浏览器启动器（Stagehand + Playwright 集成）
+// ============================================================
+const CHROME_PREFS = {
+    credentials_enable_service: false,
+    profile: { password_manager_enabled: false, password_manager_leak_detection: false },
+    safebrowsing: { enabled: false },
+};
+function createChromeProfile(baseDir) {
+    const dir = resolve(baseDir, "chrome-profile");
+    const prefsDir = resolve(dir, "Default");
+    mkdirSync(prefsDir, { recursive: true });
+    writeFileSync(resolve(prefsDir, "Preferences"), JSON.stringify(CHROME_PREFS));
+    return dir;
+}
+async function createBrowser(baseDir, options = {}) {
+    const config = await loadUserConfig();
+    const userDataDir = createChromeProfile(baseDir);
+    // 从 config 注入 API Key 到环境变量（Stagehand 从 env 读取）
+    if (config.ai?.apiKey) {
+        const model = (options.stagehand?.model ?? config.ai?.model ?? "").toLowerCase();
+        if (model.includes("deepseek"))
+            process.env.DEEPSEEK_API_KEY = config.ai.apiKey;
+        else if (model.includes("openai") || model.includes("gpt"))
+            process.env.OPENAI_API_KEY = config.ai.apiKey;
+        else if (model.includes("anthropic") || model.includes("claude"))
+            process.env.ANTHROPIC_API_KEY = config.ai.apiKey;
+    }
+    const stagehand = new Stagehand({
+        env: "LOCAL",
+        model: options.stagehand?.model ?? config.ai?.model ?? "deepseek/deepseek-v4-flash",
+        localBrowserLaunchOptions: {
+            headless: options.stagehand?.headless ?? config.browser?.headless ?? false,
+            userDataDir,
+        },
+    });
+    await stagehand.init();
+    const browser = await chromium.connectOverCDP({
+        wsEndpoint: stagehand.connectURL(),
+    });
+    const pwContext = browser.contexts()[0];
+    const pwPage = pwContext.pages()[0];
+    if (config.browser?.viewport) {
+        await pwPage.setViewportSize(config.browser.viewport);
+    }
+    return { stagehand, page: pwPage };
+}
+async function runPlan(plan, options) {
+    const config = await loadUserConfig();
+    const outDir = config.output?.dir ?? "./logs";
+    const ts = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+    const runDir = resolve(process.cwd(), outDir, `run-${ts}`);
+    mkdirSync(runDir, { recursive: true });
+    console.log(`📁 ${runDir}\n`);
+    console.log(`🚀 启动浏览器...\n`);
+    const { stagehand, page } = await createBrowser(runDir, options);
+    const report = await plan.run(page, { stagehand, outputDir: runDir });
+    await stagehand.close();
+    console.log("✅ 全部测试完成");
+    return report;
+}
+
+export { createBrowser, createChromeProfile, createTestContext, defineConfig, definePlan, isMain, runPlan, writeHtmlReport };