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

package/local-browser-executor.js

@@ -171,6 +171,51 @@ function parseArgs() {
             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 "--help":
             case "-h":
                 printHelp();
@@ -191,11 +236,12 @@ function printHelp() {
   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
+  --action <name>                    直接执行动作，当前支持 observe/act/assert/api-capture/assert-api/run-task
   --plan <json>                      测试计划 JSON 字符串
   --plan-file <path>                 测试计划 JSON 文件路径
   --output <path>                    结果输出文件路径（默认 stdout）
@@ -238,6 +284,20 @@ function printHelp() {
   --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                         显示帮助
 `);
 }
@@ -454,11 +514,52 @@ async function executeAction(args) {
                 });
                 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() };
+            }
             default:
                 return {
                     error: `未知 action: ${args.action}`,
                     errorCode: "UNKNOWN_ACTION",
-                    supportedActions: ["observe", "act", "assert", "api-capture"],
+                    supportedActions: ["observe", "act", "assert", "api-capture", "assert-api", "run-task"],
                     startTime: startedAt,
                     endTime: new Date().toISOString(),
                 };

package/opencode-extension/skills/local-browser-test/SKILL.md

@@ -95,6 +95,7 @@ AI 直接构造测试计划 JSON：
 | findFrame | 查找微前端 iframe | `urlIncludes` 或 `urlRegex` 或 `titleIncludes` 或 `contentIncludes` 或 `frameIndex` | `{ found, frameUrl, matchedBy, totalFrames }` |
 | loginWait | 等待 SSO 登录完成 | `loginSelector`, `timeout`, `interval` | `{ loggedIn, elapsed, currentUrl }` |
 | aiAssert | 语义断言（截图+审查） | `assertion`, `filename` | `{ screenshotPath, assertion, needsVisualReview }` |
+| runTask | 高层任务 runner（批量动态菜单扫描） | `task: "menu-api-scan"`, `menuApiPattern`, `menuLimit`, `menuPathPrefix[]`, `menuFilter[]`, `drawerTriggerSelector`, `useNativeHover`, `apiCaptureOptions`, `continueOnFail` | `{ task, discovered, attempted, byOutcome, results[] }` |
 
 ### 场景选择策略
 
@@ -488,3 +489,71 @@ cd ~/.szcd-mcp/deps && npm install --registry=https://registry.npmmirror.com --@
     "outputDir": "/tmp/browser-test-xxx"
 }
 ```
+
+## 批量动态菜单扫描（runTask）
+
+适用场景：测试系统有 N 条动态路由（来自后端菜单接口），要逐条点击触发并验证接口是否返回 200。6/18 反馈中，AI 最终用 130 余条 `act --menu-path` + `api-capture` 手工组合走完 129 条菜单——`runTask` 把这套流水固化为单步骤。
+
+工作流：
+
+1. **第一步：先抓菜单接口**（一次即可，作为整张菜单树的来源）
+   ```bash
+   node local-browser-executor.js --action api-capture \
+       --url-pattern "listUserViewMenus" \
+       --include-response-body \
+       --include-all-targets \
+       --reload --wait 8000 \
+       --output /tmp/menu-tree.json
+   ```
+
+2. **第二步：把菜单树喂给 runTask**
+   ```bash
+   node local-browser-executor.js --action run-task \
+       --task menu-api-scan \
+       --capture-input-file /tmp/menu-tree.json \
+       --menu-path-prefix /catalog \
+       --menu-limit 20 \
+       --drawer-trigger-selector "[data-test=menu-toggle]" \
+       --use-native-hover true \
+       --max-retry-per-step 2 \
+       --wait 4000 \
+       --output /tmp/menu-scan-report.json
+   ```
+
+3. **结果解读**：`byOutcome` 给出四档统计：
+   - `apiOk`：菜单点开 + 接口 200 ✅
+   - `apiFailed`：菜单点开 + 接口 ≥400（看 `results[i].api.requests` 找具体 URL）
+   - `noApi`：菜单点开但没产生任何 XHR（可能是纯静态页或路由没触发请求）
+   - `clickFailed`：菜单点不开（看 `results[i].menuResult.failedAt` + `candidates`）
+
+4. **plan JSON 形式**（也可作为 `--plan-file` 一步：先 apiCapture 再 runTask）：
+   ```json
+   {
+     "steps": [
+       { "type": "apiCapture", "urlPattern": "listUserViewMenus", "includeResponseBody": true, "reload": true, "wait": 8000, "includeAllTargets": true },
+       { "type": "runTask", "task": "menu-api-scan", "menuLimit": 30, "drawerTriggerSelector": "[data-test=menu-toggle]" }
+     ]
+   }
+   ```
+   `runTask` 会自动从 `context.lastApiCapture` 拿菜单树，不需要再传文件。
+
+## 反模式备忘（来自 6/17 + 6/18 实战反馈）
+
+| 错误做法 | 正确做法 | 原因 |
+|---------|---------|------|
+| `setRequestInterception(true)` 抓接口 | 仅 CDP `Network.responseReceived` + `getResponseBody` | request interception 会拦下 wujie iframe 的 RPC 帧造成挂起 |
+| `page.click("text=保存")` 不加可见性过滤 | 默认走 `act` 的 `text=`，已自动只匹配 `visible+enabled` 的元素 | 隐藏在收起菜单/未渲染抽屉里的同名文本会被错误命中 |
+| 多级菜单只用一次 `dispatchEvent("mouseover")` | `useNativeHover: true`（默认） + `drawerTriggerSelector` 每级前重开 | Vue 的 v-on:mouseenter 对 dispatchEvent 不触发；抽屉式菜单点完一次会自动收起 |
+| `setTimeout(awaitPage.bringToFront(), 30000)` 之外不做兜底 | 调用前自查"目标页是否还活着"（`findPage` / `_findFrame`），失败立刻退而求其次操作主帧 | bringToFront 在 OS 抢焦点失败时会无限挂起，没超时 |
+| iframe attach 失败就报错退出 | `attachRetries` 默认 3 次、间隔 1.5s 重抓 `browser.targets()` | wujie 的 blob iframe target 在主页面 ready 后才注册，时序敏感 |
+| 大批量探索每条都 throw | `_actMenuPath` 失败时返回 `acted:false + candidates`，配合 `runTask --continue-on-fail` | 探索性扫描遇到一条点不开就全部中断，没法发现整体面 |
+
+## 非目标声明
+
+`local-browser-test` **不**承担以下职责，遇到时显式拒绝并指给正确工具：
+
+- ❌ 接口压力测试 / 并发性能验证 → 用 k6、wrk、jmeter
+- ❌ 跨浏览器兼容性矩阵（Safari/Firefox 多版本）→ BrowserStack / SauceLabs
+- ❌ 单元测试 / 组件级测试 → Vitest / Jest / RTL
+- ❌ 视觉回归全量对比（无 baseline 设计稿）→ Percy / Chromatic
+- ✅ 真实浏览器内的功能验证、API 时序捕获、设计稿单图对比、动态菜单批量扫描

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

@@ -38,6 +38,21 @@
  *   --max-rounds <n>        最大轮数（默认 60）
  */
 
+// 共享缓存自愈：6/17 反馈中 NODE_PATH 未注入会导致 puppeteer-core MODULE_NOT_FOUND。
+// 把 ~/.szcd-mcp/deps/node_modules 注入 module 解析路径，再 require puppeteer-core。
+(function ensureSharedDeps() {
+  try {
+    const os = require('os');
+    const Module = require('module');
+    const sharedDeps = require('path').join(os.homedir(), '.szcd-mcp', 'deps', 'node_modules');
+    if (require('fs').existsSync(sharedDeps) && !Module.globalPaths.includes(sharedDeps)) {
+      Module.globalPaths.push(sharedDeps);
+    }
+  } catch {
+    // ignore — 没有共享缓存时退回项目本地 node_modules
+  }
+})();
+
 const puppeteer = require('puppeteer-core');
 const fs = require('fs');
 const path = require('path');

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@szc-ft/mcp-szcd-client",
-    "version": "0.27.3",
+    "version": "0.27.4",
     "description": "MCP client for szcd component library - auto-configures AI coding tools with MCP server, skills, agents and commands",
     "keywords": [
         "mcp",

package/qwen-extension/qwen-extension.json

@@ -1,6 +1,6 @@
 {
     "name": "szcd-component-helper",
-    "version": "0.27.3",
+    "version": "0.27.4",
     "description": "szcd 组件库 MCP 助手 — 查询组件信息、匹配需求、生成代码",
     "mcpServers": {
         "szcd-component-helper": {

package/qwen-extension/skills/local-browser-test/SKILL.md

@@ -95,6 +95,7 @@ AI 直接构造测试计划 JSON：
 | findFrame | 查找微前端 iframe | `urlIncludes` 或 `urlRegex` 或 `titleIncludes` 或 `contentIncludes` 或 `frameIndex` | `{ found, frameUrl, matchedBy, totalFrames }` |
 | loginWait | 等待 SSO 登录完成 | `loginSelector`, `timeout`, `interval` | `{ loggedIn, elapsed, currentUrl }` |
 | aiAssert | 语义断言（截图+审查） | `assertion`, `filename` | `{ screenshotPath, assertion, needsVisualReview }` |
+| runTask | 高层任务 runner（批量动态菜单扫描） | `task: "menu-api-scan"`, `menuApiPattern`, `menuLimit`, `menuPathPrefix[]`, `menuFilter[]`, `drawerTriggerSelector`, `useNativeHover`, `apiCaptureOptions`, `continueOnFail` | `{ task, discovered, attempted, byOutcome, results[] }` |
 
 ### 场景选择策略
 
@@ -488,3 +489,71 @@ cd ~/.szcd-mcp/deps && npm install --registry=https://registry.npmmirror.com --@
     "outputDir": "/tmp/browser-test-xxx"
 }
 ```
+
+## 批量动态菜单扫描（runTask）
+
+适用场景：测试系统有 N 条动态路由（来自后端菜单接口），要逐条点击触发并验证接口是否返回 200。6/18 反馈中，AI 最终用 130 余条 `act --menu-path` + `api-capture` 手工组合走完 129 条菜单——`runTask` 把这套流水固化为单步骤。
+
+工作流：
+
+1. **第一步：先抓菜单接口**（一次即可，作为整张菜单树的来源）
+   ```bash
+   node local-browser-executor.js --action api-capture \
+       --url-pattern "listUserViewMenus" \
+       --include-response-body \
+       --include-all-targets \
+       --reload --wait 8000 \
+       --output /tmp/menu-tree.json
+   ```
+
+2. **第二步：把菜单树喂给 runTask**
+   ```bash
+   node local-browser-executor.js --action run-task \
+       --task menu-api-scan \
+       --capture-input-file /tmp/menu-tree.json \
+       --menu-path-prefix /catalog \
+       --menu-limit 20 \
+       --drawer-trigger-selector "[data-test=menu-toggle]" \
+       --use-native-hover true \
+       --max-retry-per-step 2 \
+       --wait 4000 \
+       --output /tmp/menu-scan-report.json
+   ```
+
+3. **结果解读**：`byOutcome` 给出四档统计：
+   - `apiOk`：菜单点开 + 接口 200 ✅
+   - `apiFailed`：菜单点开 + 接口 ≥400（看 `results[i].api.requests` 找具体 URL）
+   - `noApi`：菜单点开但没产生任何 XHR（可能是纯静态页或路由没触发请求）
+   - `clickFailed`：菜单点不开（看 `results[i].menuResult.failedAt` + `candidates`）
+
+4. **plan JSON 形式**（也可作为 `--plan-file` 一步：先 apiCapture 再 runTask）：
+   ```json
+   {
+     "steps": [
+       { "type": "apiCapture", "urlPattern": "listUserViewMenus", "includeResponseBody": true, "reload": true, "wait": 8000, "includeAllTargets": true },
+       { "type": "runTask", "task": "menu-api-scan", "menuLimit": 30, "drawerTriggerSelector": "[data-test=menu-toggle]" }
+     ]
+   }
+   ```
+   `runTask` 会自动从 `context.lastApiCapture` 拿菜单树，不需要再传文件。
+
+## 反模式备忘（来自 6/17 + 6/18 实战反馈）
+
+| 错误做法 | 正确做法 | 原因 |
+|---------|---------|------|
+| `setRequestInterception(true)` 抓接口 | 仅 CDP `Network.responseReceived` + `getResponseBody` | request interception 会拦下 wujie iframe 的 RPC 帧造成挂起 |
+| `page.click("text=保存")` 不加可见性过滤 | 默认走 `act` 的 `text=`，已自动只匹配 `visible+enabled` 的元素 | 隐藏在收起菜单/未渲染抽屉里的同名文本会被错误命中 |
+| 多级菜单只用一次 `dispatchEvent("mouseover")` | `useNativeHover: true`（默认） + `drawerTriggerSelector` 每级前重开 | Vue 的 v-on:mouseenter 对 dispatchEvent 不触发；抽屉式菜单点完一次会自动收起 |
+| `setTimeout(awaitPage.bringToFront(), 30000)` 之外不做兜底 | 调用前自查"目标页是否还活着"（`findPage` / `_findFrame`），失败立刻退而求其次操作主帧 | bringToFront 在 OS 抢焦点失败时会无限挂起，没超时 |
+| iframe attach 失败就报错退出 | `attachRetries` 默认 3 次、间隔 1.5s 重抓 `browser.targets()` | wujie 的 blob iframe target 在主页面 ready 后才注册，时序敏感 |
+| 大批量探索每条都 throw | `_actMenuPath` 失败时返回 `acted:false + candidates`，配合 `runTask --continue-on-fail` | 探索性扫描遇到一条点不开就全部中断，没法发现整体面 |
+
+## 非目标声明
+
+`local-browser-test` **不**承担以下职责，遇到时显式拒绝并指给正确工具：
+
+- ❌ 接口压力测试 / 并发性能验证 → 用 k6、wrk、jmeter
+- ❌ 跨浏览器兼容性矩阵（Safari/Firefox 多版本）→ BrowserStack / SauceLabs
+- ❌ 单元测试 / 组件级测试 → Vitest / Jest / RTL
+- ❌ 视觉回归全量对比（无 baseline 设计稿）→ Percy / Chromatic
+- ✅ 真实浏览器内的功能验证、API 时序捕获、设计稿单图对比、动态菜单批量扫描

package/qwen-extension/skills/local-browser-test/local-browser-executor.cjs

@@ -38,6 +38,21 @@
  *   --max-rounds <n>        最大轮数（默认 60）
  */
 
+// 共享缓存自愈：6/17 反馈中 NODE_PATH 未注入会导致 puppeteer-core MODULE_NOT_FOUND。
+// 把 ~/.szcd-mcp/deps/node_modules 注入 module 解析路径，再 require puppeteer-core。
+(function ensureSharedDeps() {
+  try {
+    const os = require('os');
+    const Module = require('module');
+    const sharedDeps = require('path').join(os.homedir(), '.szcd-mcp', 'deps', 'node_modules');
+    if (require('fs').existsSync(sharedDeps) && !Module.globalPaths.includes(sharedDeps)) {
+      Module.globalPaths.push(sharedDeps);
+    }
+  } catch {
+    // ignore — 没有共享缓存时退回项目本地 node_modules
+  }
+})();
+
 const puppeteer = require('puppeteer-core');
 const fs = require('fs');
 const path = require('path');

package/standard-skill/local-browser-test/SKILL.md

@@ -95,6 +95,7 @@ AI 直接构造测试计划 JSON：
 | findFrame | 查找微前端 iframe | `urlIncludes` 或 `urlRegex` 或 `titleIncludes` 或 `contentIncludes` 或 `frameIndex` | `{ found, frameUrl, matchedBy, totalFrames }` |
 | loginWait | 等待 SSO 登录完成 | `loginSelector`, `timeout`, `interval` | `{ loggedIn, elapsed, currentUrl }` |
 | aiAssert | 语义断言（截图+审查） | `assertion`, `filename` | `{ screenshotPath, assertion, needsVisualReview }` |
+| runTask | 高层任务 runner（批量动态菜单扫描） | `task: "menu-api-scan"`, `menuApiPattern`, `menuLimit`, `menuPathPrefix[]`, `menuFilter[]`, `drawerTriggerSelector`, `useNativeHover`, `apiCaptureOptions`, `continueOnFail` | `{ task, discovered, attempted, byOutcome, results[] }` |
 
 ### 场景选择策略
 
@@ -488,3 +489,71 @@ cd ~/.szcd-mcp/deps && npm install --registry=https://registry.npmmirror.com --@
     "outputDir": "/tmp/browser-test-xxx"
 }
 ```
+
+## 批量动态菜单扫描（runTask）
+
+适用场景：测试系统有 N 条动态路由（来自后端菜单接口），要逐条点击触发并验证接口是否返回 200。6/18 反馈中，AI 最终用 130 余条 `act --menu-path` + `api-capture` 手工组合走完 129 条菜单——`runTask` 把这套流水固化为单步骤。
+
+工作流：
+
+1. **第一步：先抓菜单接口**（一次即可，作为整张菜单树的来源）
+   ```bash
+   node local-browser-executor.js --action api-capture \
+       --url-pattern "listUserViewMenus" \
+       --include-response-body \
+       --include-all-targets \
+       --reload --wait 8000 \
+       --output /tmp/menu-tree.json
+   ```
+
+2. **第二步：把菜单树喂给 runTask**
+   ```bash
+   node local-browser-executor.js --action run-task \
+       --task menu-api-scan \
+       --capture-input-file /tmp/menu-tree.json \
+       --menu-path-prefix /catalog \
+       --menu-limit 20 \
+       --drawer-trigger-selector "[data-test=menu-toggle]" \
+       --use-native-hover true \
+       --max-retry-per-step 2 \
+       --wait 4000 \
+       --output /tmp/menu-scan-report.json
+   ```
+
+3. **结果解读**：`byOutcome` 给出四档统计：
+   - `apiOk`：菜单点开 + 接口 200 ✅
+   - `apiFailed`：菜单点开 + 接口 ≥400（看 `results[i].api.requests` 找具体 URL）
+   - `noApi`：菜单点开但没产生任何 XHR（可能是纯静态页或路由没触发请求）
+   - `clickFailed`：菜单点不开（看 `results[i].menuResult.failedAt` + `candidates`）
+
+4. **plan JSON 形式**（也可作为 `--plan-file` 一步：先 apiCapture 再 runTask）：
+   ```json
+   {
+     "steps": [
+       { "type": "apiCapture", "urlPattern": "listUserViewMenus", "includeResponseBody": true, "reload": true, "wait": 8000, "includeAllTargets": true },
+       { "type": "runTask", "task": "menu-api-scan", "menuLimit": 30, "drawerTriggerSelector": "[data-test=menu-toggle]" }
+     ]
+   }
+   ```
+   `runTask` 会自动从 `context.lastApiCapture` 拿菜单树，不需要再传文件。
+
+## 反模式备忘（来自 6/17 + 6/18 实战反馈）
+
+| 错误做法 | 正确做法 | 原因 |
+|---------|---------|------|
+| `setRequestInterception(true)` 抓接口 | 仅 CDP `Network.responseReceived` + `getResponseBody` | request interception 会拦下 wujie iframe 的 RPC 帧造成挂起 |
+| `page.click("text=保存")` 不加可见性过滤 | 默认走 `act` 的 `text=`，已自动只匹配 `visible+enabled` 的元素 | 隐藏在收起菜单/未渲染抽屉里的同名文本会被错误命中 |
+| 多级菜单只用一次 `dispatchEvent("mouseover")` | `useNativeHover: true`（默认） + `drawerTriggerSelector` 每级前重开 | Vue 的 v-on:mouseenter 对 dispatchEvent 不触发；抽屉式菜单点完一次会自动收起 |
+| `setTimeout(awaitPage.bringToFront(), 30000)` 之外不做兜底 | 调用前自查"目标页是否还活着"（`findPage` / `_findFrame`），失败立刻退而求其次操作主帧 | bringToFront 在 OS 抢焦点失败时会无限挂起，没超时 |
+| iframe attach 失败就报错退出 | `attachRetries` 默认 3 次、间隔 1.5s 重抓 `browser.targets()` | wujie 的 blob iframe target 在主页面 ready 后才注册，时序敏感 |
+| 大批量探索每条都 throw | `_actMenuPath` 失败时返回 `acted:false + candidates`，配合 `runTask --continue-on-fail` | 探索性扫描遇到一条点不开就全部中断，没法发现整体面 |
+
+## 非目标声明
+
+`local-browser-test` **不**承担以下职责，遇到时显式拒绝并指给正确工具：
+
+- ❌ 接口压力测试 / 并发性能验证 → 用 k6、wrk、jmeter
+- ❌ 跨浏览器兼容性矩阵（Safari/Firefox 多版本）→ BrowserStack / SauceLabs
+- ❌ 单元测试 / 组件级测试 → Vitest / Jest / RTL
+- ❌ 视觉回归全量对比（无 baseline 设计稿）→ Percy / Chromatic
+- ✅ 真实浏览器内的功能验证、API 时序捕获、设计稿单图对比、动态菜单批量扫描

package/standard-skill/local-browser-test/local-browser-executor.cjs

@@ -38,6 +38,21 @@
  *   --max-rounds <n>        最大轮数（默认 60）
  */
 
+// 共享缓存自愈：6/17 反馈中 NODE_PATH 未注入会导致 puppeteer-core MODULE_NOT_FOUND。
+// 把 ~/.szcd-mcp/deps/node_modules 注入 module 解析路径，再 require puppeteer-core。
+(function ensureSharedDeps() {
+  try {
+    const os = require('os');
+    const Module = require('module');
+    const sharedDeps = require('path').join(os.homedir(), '.szcd-mcp', 'deps', 'node_modules');
+    if (require('fs').existsSync(sharedDeps) && !Module.globalPaths.includes(sharedDeps)) {
+      Module.globalPaths.push(sharedDeps);
+    }
+  } catch {
+    // ignore — 没有共享缓存时退回项目本地 node_modules
+  }
+})();
+
 const puppeteer = require('puppeteer-core');
 const fs = require('fs');
 const path = require('path');