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

package/opencode-extension/skills/local-browser-test/local-browser-executor.js

@@ -0,0 +1,735 @@
+#!/usr/bin/env node
+/**
+ * 本地浏览器测试执行器 - CLI 入口
+ *
+ * 用法：
+ *   node local-browser-executor.js --action observe --output /tmp/observe.json
+ *   node local-browser-executor.js --action act --index 1 --observe-after
+ *   node local-browser-executor.js --action act --menu-path "目录管理/数据集目录" --observe-after
+ *   node local-browser-executor.js --action api-capture --wait 15000 --include-response-body
+ *   node local-browser-executor.js --action assert-api --capture-file /tmp/browser-api-capture.json --max-failed 0
+ *   node local-browser-executor.js --plan '<JSON>' --output /tmp/result.json
+ *   node local-browser-executor.js --plan-file /path/to/plan.json --output /tmp/result.json
+ *
+ * 参数：
+ *   --action     直接执行动作，当前支持 observe/act/assert/api-capture
+ *   --plan       测试计划 JSON 字符串
+ *   --plan-file  测试计划 JSON 文件路径（与 --plan 二选一）
+ *   --output     结果输出文件路径（默认 stdout）
+ *   --cdp-url    Chrome DevTools Protocol URL（默认自动检测 localhost:9222）
+ *   --page-url   连接已有 Chrome 时的目标页面 URL
+ *   --base-url   基础 URL，替换计划中的 {{baseUrl}} 占位符
+ *
+ * 退出码：
+ *   0 - 全部步骤执行成功
+ *   1 - 部分步骤失败
+ *   2 - 环境错误（Chrome 未安装 / 依赖缺失 / 无法连接）
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { BrowserEngine } from "./lib/browser-engine.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// ==================== 参数解析 ====================
+
+function parseArgs() {
+    const args = process.argv.slice(2);
+    const parsed = {};
+
+    for (let i = 0; i < args.length; i++) {
+        switch (args[i]) {
+            case "--action":
+                parsed.action = args[++i];
+                break;
+            case "--plan":
+                parsed.planJson = args[++i];
+                break;
+            case "--plan-file":
+                parsed.planFile = args[++i];
+                break;
+            case "--output":
+                parsed.output = args[++i];
+                break;
+            case "--cdp-url":
+                parsed.cdpUrl = args[++i];
+                break;
+            case "--page-url":
+                parsed.pageUrl = args[++i];
+                break;
+            case "--url-contains":
+                parsed.urlContains = args[++i];
+                break;
+            case "--frame-url-contains":
+                parsed.frameUrlContains = args[++i];
+                break;
+            case "--frame-content-contains":
+                parsed.frameContentContains = args[++i];
+                break;
+            case "--frame-index":
+                parsed.frameIndex = args[++i];
+                break;
+            case "--selector":
+                parsed.selector = args[++i];
+                break;
+            case "--depth":
+                parsed.depth = args[++i];
+                break;
+            case "--max-interactive-elements":
+                parsed.maxInteractiveElements = args[++i];
+                break;
+            case "--index":
+                parsed.index = args[++i];
+                break;
+            case "--click":
+                parsed.click = args[++i];
+                break;
+            case "--type":
+                parsed.typeText = args[++i];
+                break;
+            case "--clear":
+                parsed.clear = true;
+                break;
+            case "--hover":
+                parsed.hover = args[++i];
+                break;
+            case "--menu-path":
+                parsed.menuPath = args[++i];
+                break;
+            case "--wait-after-each":
+                parsed.waitAfterEach = args[++i];
+                break;
+            case "--observe-after":
+                parsed.observeAfter = true;
+                break;
+            case "--url-contains-assert":
+                parsed.urlContainsAssert = args[++i];
+                break;
+            case "--text-contains":
+                parsed.textContains = args[++i];
+                break;
+            case "--expect-visible":
+                parsed.expectVisible = true;
+                break;
+            case "--min-count":
+                parsed.minCount = args[++i];
+                break;
+            case "--has-text":
+                parsed.hasText = args[++i];
+                break;
+            case "--wait":
+                parsed.wait = args[++i];
+                break;
+            case "--method":
+                parsed.method = args[++i];
+                break;
+            case "--url-pattern":
+                parsed.urlPattern = args[++i];
+                break;
+            case "--target-url-contains":
+                parsed.targetUrlContains = args[++i];
+                break;
+            case "--include-request-body":
+                parsed.includeRequestBody = true;
+                break;
+            case "--no-request-body":
+                parsed.includeRequestBody = false;
+                break;
+            case "--include-response-body":
+                parsed.includeResponseBody = true;
+                break;
+            case "--reload":
+                parsed.reload = true;
+                break;
+            case "--include-all-targets":
+                parsed.includeAllTargets = true;
+                break;
+            case "--capture-file":
+                parsed.captureFile = args[++i];
+                break;
+            case "--max-failed":
+                parsed.maxFailed = args[++i];
+                break;
+            case "--forbid-status-gte":
+                parsed.forbidStatusGte = args[++i];
+                break;
+            case "--required-url":
+                parsed.requiredUrls = [...(parsed.requiredUrls || []), args[++i]];
+                break;
+            case "--required-method":
+                parsed.requiredMethods = [...(parsed.requiredMethods || []), args[++i]];
+                break;
+            case "--min-total":
+                parsed.minTotal = args[++i];
+                break;
+            case "--base-url":
+                parsed.baseUrl = args[++i];
+                break;
+            case "--allow-launch":
+                parsed.allowLaunch = true;
+                break;
+            case "--task":
+                parsed.task = args[++i];
+                break;
+            case "--menu-api-pattern":
+                parsed.menuApiPattern = args[++i];
+                break;
+            case "--menu-limit":
+                parsed.menuLimit = Number.parseInt(args[++i], 10);
+                break;
+            case "--menu-path-prefix":
+                parsed.menuPathPrefix = (parsed.menuPathPrefix || []).concat(args[++i]);
+                break;
+            case "--menu-filter":
+                parsed.menuFilter = (parsed.menuFilter || []).concat(args[++i]);
+                break;
+            case "--drawer-trigger-selector":
+                parsed.drawerTriggerSelector = args[++i];
+                break;
+            case "--drawer-open-selector":
+                parsed.drawerOpenSelector = args[++i];
+                break;
+            case "--menu-scroll-container":
+                parsed.menuScrollContainer = args[++i];
+                break;
+            case "--use-native-hover":
+                parsed.useNativeHover = args[++i] !== "false";
+                break;
+            case "--max-retry-per-step":
+                parsed.maxRetryPerStep = Number.parseInt(args[++i], 10);
+                break;
+            case "--snapshot-each":
+                parsed.snapshotEach = true;
+                break;
+            case "--screenshot-each":
+                parsed.screenshotEach = true;
+                break;
+            case "--continue-on-fail":
+                parsed.continueOnFail = args[++i] !== "false";
+                break;
+            case "--no-continue-on-fail":
+                parsed.continueOnFail = false;
+                break;
+            case "--capture-input-file":
+                parsed.captureInputFile = args[++i];
+                break;
+            case "--test-case":
+                parsed.testCaseJson = args[++i];
+                break;
+            case "--test-case-file":
+                parsed.testCaseFile = args[++i];
+                break;
+            case "--dataset-index":
+                parsed.datasetIndex = Number.parseInt(args[++i], 10);
+                break;
+            case "--test-report":
+                parsed.testReport = args[++i];
+                break;
+            case "--help":
+            case "-h":
+                printHelp();
+                process.exit(0);
+        }
+    }
+    return parsed;
+}
+
+function printHelp() {
+    console.log(`
+本地浏览器测试执行器
+
+用法:
+  node local-browser-executor.js --action observe [options]
+  node local-browser-executor.js --action act --index 1 --observe-after [options]
+  node local-browser-executor.js --action act --menu-path "目录管理/数据集目录" --observe-after [options]
+  node local-browser-executor.js --action assert --selector ".ant-table" --expect-visible [options]
+  node local-browser-executor.js --action api-capture --wait 15000 --include-response-body [options]
+  node local-browser-executor.js --action assert-api --capture-file /tmp/browser-api-capture.json --max-failed 0 [options]
+  node local-browser-executor.js --action run-task --task menu-api-scan --capture-input-file /tmp/menu-tree.json [options]
+  node local-browser-executor.js --plan '<JSON>' [options]
+  node local-browser-executor.js --plan-file <path> [options]
+
+选项:
+  --action <name>                    直接执行动作，当前支持 observe/act/assert/api-capture/assert-api/run-task
+  --plan <json>                      测试计划 JSON 字符串
+  --plan-file <path>                 测试计划 JSON 文件路径
+  --output <path>                    结果输出文件路径（默认 stdout）
+  --cdp-url <url>                    Chrome DevTools Protocol URL（默认 http://localhost:9222）
+  --page-url <url>                   目标页面 URL（connect 模式时匹配标签页）
+  --url-contains <text>              按 URL 片段匹配已打开标签页
+  --frame-url-contains <text>        按 URL 片段匹配 iframe
+  --frame-content-contains <text>    按文本内容匹配 iframe
+  --frame-index <n>                  按 frame 下标选择 iframe
+  --selector <css>                   observe/assert 根节点或目标元素（observe 默认 body）
+  --depth <n>                        observe 的 DOM 树深度（默认 5）
+  --max-interactive-elements <n>     observe 的交互元素上限（默认 200）
+  --index <n>                        act 时按 observe 的 interactiveElements[index] 操作
+  --click <selector>                 act 时点击 selector/text=/role=/~ 目标
+  --type <text>                      act 时输入文本
+  --clear                            act 输入前清空目标
+  --hover <selector>                 act 时悬停 selector/text=/role=/~ 目标
+  --menu-path <a/b>                  act 时按菜单路径展开并点击，如 "目录管理/数据集目录"
+  --wait-after-each <ms>             menu-path 每步点击后的等待时间（默认 300）
+  --observe-after                    act 后再次 observe，返回 before/act/after 闭环结果
+  --url-contains-assert <text>       assert 当前 URL 包含文本
+  --text-contains <text>             assert 页面文本包含内容
+  --expect-visible                   assert selector 可见
+  --min-count <n>                    assert selector 数量下限
+  --has-text <text>                  assert selector 文本包含内容
+  --wait <ms>                        api-capture 监听时长（默认 15000）
+  --method <GET|POST>                api-capture 按请求方法过滤
+  --url-pattern <text>               api-capture 按 URL 片段过滤
+  --target-url-contains <text>       api-capture 按 target URL 过滤 iframe/page target
+  --include-request-body             api-capture 包含请求体（默认包含）
+  --no-request-body                  api-capture 不包含请求体
+  --include-response-body            api-capture 调用 Network.getResponseBody 获取响应体
+  --reload                           api-capture 开始监听后刷新页面触发请求
+  --include-all-targets              api-capture 不限制到匹配 frame，监听所有 page/iframe targets
+  --capture-file <path>              assert-api 读取 api-capture JSON 结果
+  --max-failed <n>                   assert-api 允许失败请求数上限
+  --forbid-status-gte <n>            assert-api 禁止出现大于等于该状态码的响应
+  --required-url <text>              assert-api 要求出现的 URL 片段，可重复传入
+  --required-method <GET|POST>       assert-api 要求出现的请求方法，可重复传入
+  --min-total <n>                    assert-api 要求捕获请求总数下限
+  --allow-launch                     action 模式允许无 CDP 时启动 headless Chrome
+  --base-url <url>                   基础 URL，替换计划中的 {{baseUrl}} 占位符
+  --task <name>                      run-task 任务名（当前仅支持 menu-api-scan）
+  --capture-input-file <path>        run-task 读取已抓到的菜单接口 JSON 作为 lastApiCapture
+  --menu-api-pattern <regex>         run-task 在 lastApiCapture 中筛选菜单接口的正则（默认 listUserViewMenus）
+  --menu-limit <n>                   run-task 仅探索前 N 条菜单
+  --menu-path-prefix <text>          run-task 仅探索 path 以此开头的菜单（可重复）
+  --menu-filter <text>               run-task 仅探索 name/path 包含此关键字的菜单（可重复）
+  --drawer-trigger-selector <css>    run-task / act 抽屉式菜单的触发器选择器
+  --drawer-open-selector <css>       run-task / act 抽屉打开态选择器（默认 .ant-drawer-open）
+  --menu-scroll-container <css>      run-task / act 菜单容器需要滚动时的容器选择器
+  --use-native-hover <true|false>    run-task / act 使用 puppeteer 原生 hover 触发子菜单（默认 true）
+  --max-retry-per-step <n>           run-task / act 每级菜单查找重试次数（默认 2）
+  --snapshot-each                    run-task 每条菜单成功后做一次轻量 observe
+  --screenshot-each                  run-task 失败时截图（依赖 outputDir，默认关闭）
+  --no-continue-on-fail              run-task 第一条失败即终止（默认遇错继续）
+  -h, --help                         显示帮助
+`);
+}
+
+function loadPlan(args) {
+    let raw;
+    if (args.planJson) {
+        raw = args.planJson;
+    } else if (args.planFile) {
+        raw = fs.readFileSync(args.planFile, "utf8");
+    } else {
+        throw new Error("必须提供 --plan 或 --plan-file 参数");
+    }
+
+    // 模板变量替换：{{baseUrl}} → --base-url 参数值
+    if (args.baseUrl) {
+        raw = raw.replace(/\{\{baseUrl\}\}/g, args.baseUrl);
+    }
+
+    return JSON.parse(raw);
+}
+
+// ==================== 执行引擎 ====================
+
+async function executePlan(plan, options) {
+    const engine = new BrowserEngine();
+    const results = {
+        planId: plan.planId || "unknown",
+        description: plan.description || "",
+        mode: null,
+        steps: [],
+        summary: {
+            total: plan.steps.length,
+            passed: 0,
+            failed: 0,
+            fidelity: null,
+        },
+        startTime: new Date().toISOString(),
+    };
+
+    const outputDir = plan.options?.outputDir || path.join("/tmp", `browser-test-${results.planId}`);
+    if (!fs.existsSync(outputDir)) {
+        fs.mkdirSync(outputDir, { recursive: true });
+    }
+
+    try {
+        // 初始化浏览器
+        const initResult = await engine.init({
+            cdpUrl: options.cdpUrl,
+            pageUrl: options.pageUrl || plan.options?.pageUrl,
+            viewport: plan.options?.viewport,
+        });
+        results.mode = initResult.mode;
+        results.browserInfo = initResult;
+
+        // 如果计划中有 navigate 步骤且当前是 connect 模式，导航到目标页面
+        const navigateStep = plan.steps.find((s) => s.type === "navigate");
+
+        // 逐步执行
+        for (let i = 0; i < plan.steps.length; i++) {
+            const step = plan.steps[i];
+            const stepResult = await engine.executeStep(step, { outputDir });
+            stepResult.index = i + 1;
+            results.steps.push(stepResult);
+
+            if (stepResult.status === "PASS") {
+                results.summary.passed++;
+            } else {
+                results.summary.failed++;
+            }
+
+            // 提取 fidelity
+            if (step.type === "compare" && stepResult.status === "PASS" && stepResult.fidelity !== undefined) {
+                results.summary.fidelity = stepResult.fidelity;
+            }
+
+            // 输出进度
+            const status = stepResult.status === "PASS" ? "✓" : "✗";
+            process.stderr.write(
+                `  ${status} Step ${i + 1}/${plan.steps.length} ${step.type}` +
+                (step.selector ? ` (${step.selector})` : "") +
+                (stepResult.duration ? ` [${stepResult.duration}ms]` : "") +
+                "\n"
+            );
+        }
+    } catch (err) {
+        results.error = err.message;
+        results.errorCode = err.code || "UNKNOWN";
+
+        if (err.code === "CHROME_NOT_FOUND" || err.code === "DEPENDENCY_MISSING") {
+            results.installGuide = err.message;
+        }
+    } finally {
+        await engine.close();
+    }
+
+    results.endTime = new Date().toISOString();
+    results.duration = new Date(results.endTime) - new Date(results.startTime);
+    results.outputDir = outputDir;
+
+    return results;
+}
+
+// ==================== 主流程 ====================
+
+function executeAssertApiAction(args) {
+    if (!args.captureFile) {
+        return {
+            error: "必须提供 --capture-file 参数",
+            errorCode: "CAPTURE_FILE_REQUIRED",
+        };
+    }
+
+    const captureResult = JSON.parse(fs.readFileSync(args.captureFile, "utf8"));
+    const engine = new BrowserEngine();
+    return engine.assertApi(captureResult, {
+        maxFailed: args.maxFailed,
+        forbidStatusGte: args.forbidStatusGte,
+        requiredUrls: args.requiredUrls,
+        requiredMethods: args.requiredMethods,
+        minTotal: args.minTotal,
+    });
+}
+
+async function executeAction(args) {
+    const engine = new BrowserEngine();
+    const startedAt = new Date().toISOString();
+    try {
+        const cdpUrl = args.cdpUrl || "http://localhost:9222";
+        const debuggerAvailable = await engine.isDebuggerAvailable(cdpUrl);
+        if (!debuggerAvailable && !args.allowLaunch) {
+            return {
+                error: `无法连接到 Chrome 调试端口: ${cdpUrl}`,
+                errorCode: "CDP_UNAVAILABLE",
+                guide: "请先以 --remote-debugging-port=9222 启动用户真实浏览器；如确需启动 headless 回退，追加 --allow-launch。",
+                startTime: startedAt,
+                endTime: new Date().toISOString(),
+            };
+        }
+
+        const initResult = await engine.init({
+            cdpUrl,
+            pageUrl: args.pageUrl || args.urlContains,
+        });
+
+        switch (args.action) {
+            case "observe": {
+                const result = await engine.observe({
+                    selector: args.selector,
+                    depth: args.depth,
+                    frameUrlContains: args.frameUrlContains,
+                    frameContentContains: args.frameContentContains,
+                    frameIndex: args.frameIndex,
+                    maxInteractiveElements: args.maxInteractiveElements,
+                });
+                return { ...result, browserInfo: initResult, startTime: startedAt, endTime: new Date().toISOString() };
+            }
+            case "act": {
+                const actResult = await engine.act({
+                    index: args.index,
+                    selector: args.selector,
+                    click: args.click,
+                    hover: args.hover,
+                    menuPath: args.menuPath,
+                    waitAfterEach: args.waitAfterEach,
+                    typeText: args.typeText,
+                    clear: args.clear,
+                    frameUrlContains: args.frameUrlContains,
+                    frameContentContains: args.frameContentContains,
+                    frameIndex: args.frameIndex,
+                });
+                if (!args.observeAfter) {
+                    return { type: "act", ...actResult, browserInfo: initResult, startTime: startedAt, endTime: new Date().toISOString() };
+                }
+                const after = await engine.observe({
+                    depth: args.depth,
+                    frameUrlContains: args.frameUrlContains,
+                    frameContentContains: args.frameContentContains,
+                    frameIndex: args.frameIndex,
+                    maxInteractiveElements: args.maxInteractiveElements,
+                });
+                return { type: "actObserve", act: actResult, after, browserInfo: initResult, startTime: startedAt, endTime: new Date().toISOString() };
+            }
+            case "assert": {
+                const expect = {};
+                if (args.expectVisible) expect.visible = true;
+                if (args.minCount !== undefined) expect.minCount = Number.parseInt(args.minCount, 10);
+                if (args.hasText !== undefined) expect.hasText = args.hasText;
+                const result = await engine.assert({
+                    selector: args.selector,
+                    expect,
+                    urlContains: args.urlContainsAssert,
+                    textContains: args.textContains,
+                    frameUrlContains: args.frameUrlContains,
+                    frameContentContains: args.frameContentContains,
+                    frameIndex: args.frameIndex,
+                });
+                return { type: "assert", ...result, browserInfo: initResult, startTime: startedAt, endTime: new Date().toISOString() };
+            }
+            case "api-capture":
+            case "apiCapture": {
+                const result = await engine.captureApi({
+                    wait: args.wait,
+                    method: args.method,
+                    urlPattern: args.urlPattern,
+                    targetUrlContains: args.targetUrlContains,
+                    includeRequestBody: args.includeRequestBody,
+                    includeResponseBody: args.includeResponseBody,
+                    reload: args.reload,
+                    includeAllTargets: args.includeAllTargets,
+                    frameUrlContains: args.frameUrlContains,
+                    frameContentContains: args.frameContentContains,
+                    frameIndex: args.frameIndex,
+                });
+                return { ...result, browserInfo: initResult, startTime: startedAt, endTime: new Date().toISOString() };
+            }
+            case "run-task":
+            case "runTask": {
+                // 把外部 captureFile 当作 lastApiCapture 注入 context
+                const context = {};
+                if (args.captureInputFile) {
+                    const fs = await import("node:fs");
+                    try {
+                        context.lastApiCapture = JSON.parse(fs.readFileSync(args.captureInputFile, "utf8"));
+                    } catch (err) {
+                        return {
+                            error: `读取 capture 输入文件失败: ${err.message}`,
+                            errorCode: "CAPTURE_INPUT_INVALID",
+                            startTime: startedAt,
+                            endTime: new Date().toISOString(),
+                        };
+                    }
+                }
+                const result = await engine.runTask({
+                    task: args.task || "menu-api-scan",
+                    menuApiPattern: args.menuApiPattern,
+                    menuLimit: args.menuLimit,
+                    menuPathPrefix: args.menuPathPrefix,
+                    menuFilter: args.menuFilter,
+                    drawerTriggerSelector: args.drawerTriggerSelector,
+                    drawerOpenSelector: args.drawerOpenSelector,
+                    menuScrollContainer: args.menuScrollContainer,
+                    useNativeHover: args.useNativeHover,
+                    maxRetryPerStep: args.maxRetryPerStep,
+                    snapshotEach: args.snapshotEach,
+                    screenshotEach: args.screenshotEach,
+                    continueOnFail: args.continueOnFail,
+                    apiCaptureOptions: {
+                        wait: args.wait,
+                        targetUrlContains: args.targetUrlContains,
+                        includeAllTargets: args.includeAllTargets,
+                        includeResponseBody: args.includeResponseBody !== false,
+                        urlPattern: args.urlPattern,
+                    },
+                }, context);
+                return { type: "runTask", ...result, browserInfo: initResult, startTime: startedAt, endTime: new Date().toISOString() };
+            }
+            case "test-case":
+            case "testCase": {
+                // 加载 testCase 定义
+                let testCase;
+                if (args.testCaseFile) {
+                    try {
+                        testCase = JSON.parse(fs.readFileSync(args.testCaseFile, "utf8"));
+                    } catch (err) {
+                        return {
+                            error: `读取 test-case 文件失败: ${err.message}`,
+                            errorCode: "TEST_CASE_INVALID",
+                            startTime: startedAt,
+                            endTime: new Date().toISOString(),
+                        };
+                    }
+                } else if (args.testCaseJson) {
+                    try {
+                        testCase = JSON.parse(args.testCaseJson);
+                    } catch (err) {
+                        return {
+                            error: `解析 --test-case JSON 失败: ${err.message}`,
+                            errorCode: "TEST_CASE_INVALID",
+                            startTime: startedAt,
+                            endTime: new Date().toISOString(),
+                        };
+                    }
+                } else {
+                    return {
+                        error: "必须提供 --test-case 或 --test-case-file",
+                        errorCode: "TEST_CASE_MISSING",
+                        startTime: startedAt,
+                        endTime: new Date().toISOString(),
+                    };
+                }
+
+                // 支持 --dataset-index 仅执行某一行
+                if (args.datasetIndex !== undefined && Array.isArray(testCase.dataset)) {
+                    if (args.datasetIndex < 0 || args.datasetIndex >= testCase.dataset.length) {
+                        return {
+                            error: `--dataset-index ${args.datasetIndex} 越界（共 ${testCase.dataset.length} 行）`,
+                            errorCode: "DATASET_INDEX_OUT_OF_RANGE",
+                        };
+                    }
+                    testCase.dataset = [testCase.dataset[args.datasetIndex]];
+                }
+
+                const result = await engine.executeTestCase(testCase, {});
+
+                if (args.testReport) {
+                    const dir = path.dirname(args.testReport);
+                    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+                    fs.writeFileSync(args.testReport, JSON.stringify(result, null, 2), "utf8");
+                    process.stderr.write(`测试报告已写入: ${args.testReport}\n`);
+                }
+
+                return { type: "testCase", ...result, browserInfo: initResult, startTime: startedAt, endTime: new Date().toISOString() };
+            }
+            default:
+                return {
+                    error: `未知 action: ${args.action}`,
+                    errorCode: "UNKNOWN_ACTION",
+                    supportedActions: ["observe", "act", "assert", "api-capture", "assert-api", "run-task", "test-case"],
+                    startTime: startedAt,
+                    endTime: new Date().toISOString(),
+                };
+        }
+    } catch (err) {
+        return {
+            error: err.message,
+            errorCode: err.code || "ACTION_FAILED",
+            installGuide: err.code === "CHROME_NOT_FOUND" || err.code === "DEPENDENCY_MISSING" ? err.message : undefined,
+            startTime: startedAt,
+            endTime: new Date().toISOString(),
+        };
+    } finally {
+        await engine.close();
+    }
+}
+
+async function main() {
+    const args = parseArgs();
+
+    if (args.action === "assert-api" || args.action === "assertApi") {
+        try {
+            const results = executeAssertApiAction(args);
+            outputResult(results, args.output);
+            process.exit(results.error ? 2 : results.passed === false ? 1 : 0);
+        } catch (err) {
+            const errorResult = {
+                error: err.message,
+                errorCode: "ASSERT_API_FAILED",
+            };
+            outputResult(errorResult, args.output);
+            process.exit(2);
+        }
+    }
+
+    if (args.action) {
+        const results = await executeAction(args);
+        outputResult(results, args.output);
+        process.exit(results.error ? 2 : 0);
+    }
+
+    let plan;
+    try {
+        plan = loadPlan(args);
+    } catch (err) {
+        const errorResult = {
+            error: err.message,
+            errorCode: "INVALID_PLAN",
+        };
+        outputResult(errorResult, args.output);
+        process.exit(2);
+    }
+
+    process.stderr.write(`\n浏览器测试执行器\n`);
+    process.stderr.write(`计划: ${plan.description || plan.planId || "unnamed"}\n`);
+    process.stderr.write(`步骤: ${plan.steps?.length || 0}\n\n`);
+
+    const results = await executePlan(plan, {
+        cdpUrl: args.cdpUrl,
+        pageUrl: args.pageUrl,
+    });
+
+    // 输出结果
+    outputResult(results, args.output);
+
+    // 输出摘要
+    process.stderr.write(`\n执行完成:\n`);
+    process.stderr.write(`  模式: ${results.mode || "failed"}\n`);
+    process.stderr.write(`  通过: ${results.summary.passed}/${results.summary.total}\n`);
+    process.stderr.write(`  失败: ${results.summary.failed}/${results.summary.total}\n`);
+    if (results.summary.fidelity !== null) {
+        process.stderr.write(`  还原度: ${results.summary.fidelity}%\n`);
+    }
+    process.stderr.write(`  耗时: ${results.duration}ms\n\n`);
+
+    // 退出码
+    if (results.error) {
+        process.exit(2);
+    } else if (results.summary.failed > 0) {
+        process.exit(1);
+    } else {
+        process.exit(0);
+    }
+}
+
+function outputResult(results, outputPath) {
+    const json = JSON.stringify(results, null, 2);
+
+    if (outputPath) {
+        const dir = path.dirname(outputPath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        fs.writeFileSync(outputPath, json, "utf8");
+        process.stderr.write(`结果已写入: ${outputPath}\n`);
+    } else {
+        process.stdout.write(json + "\n");
+    }
+}
+
+main().catch((err) => {
+    process.stderr.write(`Fatal error: ${err.message}\n`);
+    process.exit(2);
+});