@szc-ft/mcp-szcd-client 0.27.1 → 0.27.3

package/lib/shared-deps.js

@@ -1,9 +1,8 @@
 /**
  * 共享依赖加载器
  *
- * 浏览器自动化依赖（puppeteer-core, pixelmatch, pngjs, sharp）
- * 安装到 ~/.szcd-mcp/deps/node_modules/，所有项目共享复用。
- * 首次使用时自动安装，后续直接加载。
+ * 浏览器自动化依赖安装到 ~/.szcd-mcp/deps/node_modules/，所有项目共享复用。
+ * 主链路 observe/act/assert 只安装 puppeteer-core；视觉对比按需安装 pixelmatch/pngjs/sharp。
  */
 
 import { createRequire } from "node:module";
@@ -14,11 +13,14 @@ import fs from "node:fs";
 /** 共享缓存目录 */
 const SHARED_DEPS_DIR = path.join(homedir(), ".szcd-mcp", "deps");
 
-/** 需要共享安装的包列表 */
-const PACKAGES = ["puppeteer-core", "pixelmatch", "pngjs", "sharp"];
+/** 核心浏览器自动化依赖 */
+const CORE_PACKAGES = ["puppeteer-core"];
 
-/** 标记文件，存在表示依赖已安装 */
-const INSTALLED_MARKER = path.join(SHARED_DEPS_DIR, ".installed");
+/** 视觉对比依赖 */
+const VISUAL_COMPARE_PACKAGES = ["pixelmatch", "pngjs", "sharp"];
+
+/** 兼容旧导出 */
+const PACKAGES = [...CORE_PACKAGES, ...VISUAL_COMPARE_PACKAGES];
 
 /**
  * 从共享缓存目录加载模块
@@ -30,27 +32,9 @@ export function loadFromShared(moduleName) {
     return require_(moduleName);
 }
 
-/**
- * 确保共享依赖已安装，未安装则自动安装
- * @returns {Promise<void>}
- */
-export async function ensureSharedDeps() {
-    // 检查标记文件
-    if (fs.existsSync(INSTALLED_MARKER)) {
-        // 快速验证：puppeteer-core 目录是否存在
-        const pcoreDir = path.join(SHARED_DEPS_DIR, "node_modules", "puppeteer-core");
-        if (fs.existsSync(pcoreDir)) {
-            return; // 已安装
-        }
-    }
-
-    process.stderr.write("[shared-deps] 首次使用浏览器测试功能，正在安装共享依赖...\n");
-    process.stderr.write(`[shared-deps] 安装目录: ${SHARED_DEPS_DIR}\n`);
-
-    // 确保目录存在
+function ensurePackageJson() {
     fs.mkdirSync(SHARED_DEPS_DIR, { recursive: true });
 
-    // 初始化 package.json（如果不存在）
     const pkgPath = path.join(SHARED_DEPS_DIR, "package.json");
     if (!fs.existsSync(pkgPath)) {
         fs.writeFileSync(pkgPath, JSON.stringify({
@@ -59,39 +43,95 @@ export async function ensureSharedDeps() {
             private: true,
         }, null, 2));
     }
+}
+
+function isPackageInstalled(packageName) {
+    try {
+        const require_ = createRequire(path.join(SHARED_DEPS_DIR, "node_modules", "_"));
+        require_.resolve(packageName);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+async function installPackages(packages, label) {
+    const missing = packages.filter((packageName) => !isPackageInstalled(packageName));
+    if (missing.length === 0) return;
+
+    process.stderr.write(`[shared-deps] 正在安装${label}: ${missing.join(" ")}\n`);
+    process.stderr.write(`[shared-deps] 安装目录: ${SHARED_DEPS_DIR}\n`);
+
+    ensurePackageJson();
 
-    // 安装依赖
     const { execSync } = await import("node:child_process");
-    const pkgList = PACKAGES.join(" ");
-    const mirrorFlag = "--sharp_binary_host=https://npmmirror.com/mirrors/sharp";
-    const registryFlag = "--registry=https://npmmirror.com";
+    const pkgList = missing.join(" ");
+    const registryFlags = [
+        "--registry=https://registry.npmmirror.com",
+        "--@img:registry=https://registry.npmmirror.com",
+    ];
+    const speedFlags = [
+        "--prefer-offline",
+        "--no-audit",
+        "--no-fund",
+        "--omit=dev",
+        "--package-lock=false",
+        "--loglevel=warn",
+    ];
+    const sharpFlags = missing.includes("sharp") ? [
+        "--sharp_binary_host=https://npmmirror.com/mirrors/sharp",
+        "--sharp_libvips_binary_host=https://npmmirror.com/mirrors/sharp-libvips",
+    ] : [];
+    const installFlags = [...registryFlags, ...speedFlags, ...sharpFlags].join(" ");
 
     try {
-        execSync(`npm install ${registryFlag} ${mirrorFlag} ${pkgList}`, {
+        execSync(`npm install ${installFlags} ${pkgList}`.trim(), {
             cwd: SHARED_DEPS_DIR,
             stdio: "inherit",
             timeout: 180000,
         });
     } catch (err) {
         throw new Error(
-            `浏览器测试依赖安装失败。请手动执行：\n` +
-            `  cd ${SHARED_DEPS_DIR} && npm install ${pkgList}\n` +
+            `${label}安装失败。请手动执行：\n` +
+            `  cd ${SHARED_DEPS_DIR} && npm install ${installFlags} ${pkgList}\n` +
             `原始错误：${err.message}`
         );
     }
 
-    // 写入标记文件
-    fs.writeFileSync(INSTALLED_MARKER, new Date().toISOString());
-    process.stderr.write("[shared-deps] 共享依赖安装完成！后续所有项目将复用此安装。\n");
+    process.stderr.write(`[shared-deps] ${label}安装完成。\n`);
+}
+
+export async function ensureCoreDeps() {
+    await installPackages(CORE_PACKAGES, "浏览器核心依赖");
+}
+
+export async function ensureVisualCompareDeps() {
+    await ensureCoreDeps();
+    await installPackages(VISUAL_COMPARE_PACKAGES, "视觉对比依赖");
+}
+
+/**
+ * 确保全部共享依赖已安装，保留给旧调用兼容。
+ * @returns {Promise<void>}
+ */
+export async function ensureSharedDeps() {
+    await ensureVisualCompareDeps();
+}
+
+/**
+ * 检查核心依赖是否已安装
+ * @returns {boolean}
+ */
+export function isCoreDepsInstalled() {
+    return CORE_PACKAGES.every(isPackageInstalled);
 }
 
 /**
- * 检查共享依赖是否已安装
+ * 检查全部共享依赖是否已安装
  * @returns {boolean}
  */
 export function isSharedDepsInstalled() {
-    return fs.existsSync(INSTALLED_MARKER) &&
-        fs.existsSync(path.join(SHARED_DEPS_DIR, "node_modules", "puppeteer-core"));
+    return PACKAGES.every(isPackageInstalled);
 }
 
-export { SHARED_DEPS_DIR, PACKAGES };
+export { SHARED_DEPS_DIR, PACKAGES, CORE_PACKAGES, VISUAL_COMPARE_PACKAGES };

package/lib/visual-compare.js

@@ -15,7 +15,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import { ensureSharedDeps, loadFromShared } from "./shared-deps.js";
+import { ensureVisualCompareDeps, loadFromShared } from "./shared-deps.js";
 
 /**
  * 全局视觉对比
@@ -27,8 +27,8 @@ import { ensureSharedDeps, loadFromShared } from "./shared-deps.js";
  * @returns {Promise<object>} 对比结果
  */
 export async function compareDesign(screenshotPath, designImagePath, options = {}) {
-    // 确保共享依赖已安装，然后加载
-    await ensureSharedDeps();
+    // 视觉对比才安装 pixelmatch/pngjs/sharp，避免 observe 主链路被重依赖阻塞
+    await ensureVisualCompareDeps();
     const sharp = loadFromShared("sharp");
     const pixelmatch = loadFromShared("pixelmatch");
     const { PNG } = loadFromShared("pngjs");

package/local-browser-executor.js

@@ -3,10 +3,16 @@
  * 本地浏览器测试执行器 - 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）
@@ -36,6 +42,9 @@ function parseArgs() {
 
     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;
@@ -51,9 +60,117 @@ function parseArgs() {
             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 "--help":
             case "-h":
                 printHelp();
@@ -68,17 +185,60 @@ function printHelp() {
 本地浏览器测试执行器
 
 用法:
+  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 --plan '<JSON>' [options]
   node local-browser-executor.js --plan-file <path> [options]
 
 选项:
-  --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 模式时匹配标签页）
-  --base-url <url>    基础 URL，替换计划中的 {{baseUrl}} 占位符
-  -h, --help          显示帮助
+  --action <name>                    直接执行动作，当前支持 observe/act/assert/api-capture
+  --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}} 占位符
+  -h, --help                         显示帮助
 `);
 }
 
@@ -183,9 +343,163 @@ async function executePlan(plan, options) {
 
 // ==================== 主流程 ====================
 
+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() };
+            }
+            default:
+                return {
+                    error: `未知 action: ${args.action}`,
+                    errorCode: "UNKNOWN_ACTION",
+                    supportedActions: ["observe", "act", "assert", "api-capture"],
+                    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);

package/opencode-extension/commands/szcd-mcp-browser-test.md

@@ -53,5 +53,5 @@ argument-hint: <目标页面URL> [可选：设计稿图片路径]
 
 **注意事项**：
 - 首次使用需确保 Chrome 以调试模式启动：`google-chrome --remote-debugging-port=9222`
-- 如执行器报错依赖缺失，引导用户安装：`npm install puppeteer-core pixelmatch pngjs sharp`
+- 如执行器报错依赖缺失，优先按提示安装核心依赖；仅设计稿像素对比需要额外安装 `pixelmatch pngjs sharp`
 - connect 模式下天然继承用户浏览器的登录态和微前端环境