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

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,184 @@ 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` | 探索性扫描遇到一条点不开就全部中断，没法发现整体面 |
+| 手写 puppeteer 脚本绕过 `act` 操作 Ant Select | 用 `antSelect` 步骤（内置 mousedown + 轮询 + closeAllDropdowns + VERIFY） | Ant Design Select 必须 mousedown 触发，浮层在 body 末尾，选项异步渲染，单步 `act.evaluate` 无法覆盖四步组合 |
+| 每个 Select 后忘记 `closeAllDropdowns` | `act` 自动检测上一次 antSelect/antTreeSelect 并预清理 | 下拉浮层残留会污染下一次 Select 操作，选项串选 |
+| 硬编码 `sleep(15*200)` 等选项渲染 | `antSelect` 内置 `pollEval` 15×200ms 轮询，`expect(poll)` 可自定义条件 | 选项渲染时间受网络/数据量影响，固定 sleep 时机不可靠 |
+| 表单校验用 ad-hoc evaluate 检查 | 用 `expect validation.toPass` 或 `formFill` 的 `validateAfter` | 语义断言自带 poll + 结构化错误信息（field + message），可直接进报告 |
+
+## Ant Design 适配层（6/22 反馈落地）
+
+把"触发器定位 → 浮层等待 → 选项交互 → VERIFY → 全局清理"固化为单步骤 JSON。
+
+| type | 功能 | 关键参数 |
+|------|------|---------|
+| `antSelect` | Ant Select 选项选择 | `field`, `option`, `mode` |
+| `antTreeSelect` | 树形选择 | `field`, `path` |
+| `antInput` | 输入框（支持 `placeholder` 定位） | `field`/`placeholder`, `value` |
+| `antRadio` / `antCheckbox` / `antSwitch` | 选择类 | `field`, `option`/`on` |
+| `antDatePicker` / `antCascader` / `antUpload` | 其他控件 | 见各方法文档 |
+| `formFill` | 批量填充 + 可选 `validateAfter` | `fields[]` |
+| `closeAllDropdowns` | 关闭所有下拉浮层 | - |
+
+**关键约束**：
+- Ant Select 必须 `mousedown` 触发（不是 click）
+- 选项异步渲染，内置 15×200ms 轮询
+- 每次操作前后自动 `closeAllDropdowns`，`act` 入口检测残留并预清理
+- 操作后 VERIFY `.ant-select-selection-item[title]` 回写
+
+```json
+{ "type": "antSelect", "field": "数据集名称", "option": "测试集A" }
+{ "type": "antInput", "placeholder": "挂接资源", "value": "abc" }
+{ "type": "formFill", "fields": [
+    { "label": "名称", "type": "input", "value": "{{name}}" },
+    { "label": "类型", "type": "select", "value": "{{type}}" }
+], "validateAfter": true }
+```
+
+## 用例 DSL（Test Case）
+
+把多个用例统一为参数化 testCase JSON：
+
+```bash
+node local-browser-executor.js --action test-case --test-case-file /tmp/case.json [--dataset-index 0] [--test-report /tmp/report.json]
+```
+
+```json
+{
+    "title": "创建数据集 - P0",
+    "dataset": [{ "name": "A", "type": "图像" }, { "name": "B", "type": "文本" }],
+    "steps": [
+        { "type": "formFill", "fields": [
+            { "label": "名称", "type": "input", "value": "{{name}}" },
+            { "label": "类型", "type": "select", "value": "{{type}}" }
+        ], "validateAfter": true },
+        { "type": "expect", "assertion": "validation.toPass" },
+        { "type": "act", "click": "text=提交" },
+        { "type": "expect", "assertion": "url.toContain", "value": "/list" }
+    ],
+    "recovery": { "maxRetriesPerStep": 2 }
+}
+```
+
+## 语义断言（expect）
+
+| assertion | 功能 |
+|-----------|------|
+| `validation.toPass` | 表单校验无错误 |
+| `validation.toHaveError` | 某字段有错误 |
+| `locator.toBeVisible` / `toHaveText` / `toHaveValue` / `toHaveCount` | 元素状态 |
+| `url.toContain` / `url.toMatch` | URL 断言 |
+| `api.toAllPass` / `api.toInclude` | API 断言 |
+
+所有断言内置 `poll` 轮询（默认 timeout 5s, interval 200ms）。
+
+## 微前端（wujie / qiankun）场景适配
+
+**核心问题与解决：**
+
+| 微前端坑 | 自动修复 |
+|---------|---------|
+| 子应用业务在 frame[1]，每步都要重传 frameContentContains | testCase `setup.findFrame` 设一次，所有步骤默认走 `_activeFrame` |
+| 子应用路由切换销毁 iframe，导致后续 step 都 evaluate 失败 | `_getTargetFrame` 每次执行前探活，失活自动召回（标记 `frameRecovered: true`） |
+| Ant Select 的 `getPopupContainer` 把浮层渲染到父文档 | `antSelect` 触发器/浮层双 frame 协作：trigger 在子 frame mousedown，浮层在父 frame 找选项 |
+| 残留浮层污染下一次操作 | `closeAllDropdowns` 跨 frame 清理（主 + 所有可访问子 frame） |
+| `api.toAllPass` 因主应用埋点 404 误判子应用 P0 测试失败 | `step.scope: "current-frame"` 仅断言 `_activeFrame` 同源的请求 |
+
+**testCase 微前端模板：**
+
+```json
+{
+    "title": "数据集创建 P0",
+    "setup": {
+        "findFrame": { "contentContains": "数据集目录" }
+    },
+    "dataset": [{ "name": "A" }, { "name": "B" }],
+    "steps": [
+        { "type": "apiCapture", "urlPattern": "/api/dataset", "wait": 5000, "includeAllTargets": true },
+        { "type": "antInput", "field": "名称", "value": "{{name}}" },
+        { "type": "antSelect", "field": "类型", "option": "图像" },
+        { "type": "act", "click": "text=提交" },
+        { "type": "expect", "assertion": "validation.toPass" },
+        { "type": "expect", "assertion": "api.toAllPass", "scope": "current-frame" }
+    ]
+}
+```
+
+**关键参数：**
+
+- `setup.findFrame.contentContains` — 一次定位子应用 frame
+- `step.frameContentContains` — 单步覆盖（少用，违反 DRY）
+- `step.scope: "current-frame"` — API 断言仅看 `_activeFrame` 同源请求
+- `apiCapture.includeAllTargets: true` — 跨 page/iframe target 监听网络
+
+**调试技巧：**
+
+每个 ant 步骤结果含 `triggerFrameUrl` / `popupFrameUrl`，可看到触发器和浮层实际在哪个 frame。若 `_dropdownFrame: "main"` 出现，说明该控件用了 `getPopupContainer` 跨 frame 渲染浮层。
+
+## 非目标声明
+
+`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.28.0",
     "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.28.0",
     "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,184 @@ 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` | 探索性扫描遇到一条点不开就全部中断，没法发现整体面 |
+| 手写 puppeteer 脚本绕过 `act` 操作 Ant Select | 用 `antSelect` 步骤（内置 mousedown + 轮询 + closeAllDropdowns + VERIFY） | Ant Design Select 必须 mousedown 触发，浮层在 body 末尾，选项异步渲染，单步 `act.evaluate` 无法覆盖四步组合 |
+| 每个 Select 后忘记 `closeAllDropdowns` | `act` 自动检测上一次 antSelect/antTreeSelect 并预清理 | 下拉浮层残留会污染下一次 Select 操作，选项串选 |
+| 硬编码 `sleep(15*200)` 等选项渲染 | `antSelect` 内置 `pollEval` 15×200ms 轮询，`expect(poll)` 可自定义条件 | 选项渲染时间受网络/数据量影响，固定 sleep 时机不可靠 |
+| 表单校验用 ad-hoc evaluate 检查 | 用 `expect validation.toPass` 或 `formFill` 的 `validateAfter` | 语义断言自带 poll + 结构化错误信息（field + message），可直接进报告 |
+
+## Ant Design 适配层（6/22 反馈落地）
+
+把"触发器定位 → 浮层等待 → 选项交互 → VERIFY → 全局清理"固化为单步骤 JSON。
+
+| type | 功能 | 关键参数 |
+|------|------|---------|
+| `antSelect` | Ant Select 选项选择 | `field`, `option`, `mode` |
+| `antTreeSelect` | 树形选择 | `field`, `path` |
+| `antInput` | 输入框（支持 `placeholder` 定位） | `field`/`placeholder`, `value` |
+| `antRadio` / `antCheckbox` / `antSwitch` | 选择类 | `field`, `option`/`on` |
+| `antDatePicker` / `antCascader` / `antUpload` | 其他控件 | 见各方法文档 |
+| `formFill` | 批量填充 + 可选 `validateAfter` | `fields[]` |
+| `closeAllDropdowns` | 关闭所有下拉浮层 | - |
+
+**关键约束**：
+- Ant Select 必须 `mousedown` 触发（不是 click）
+- 选项异步渲染，内置 15×200ms 轮询
+- 每次操作前后自动 `closeAllDropdowns`，`act` 入口检测残留并预清理
+- 操作后 VERIFY `.ant-select-selection-item[title]` 回写
+
+```json
+{ "type": "antSelect", "field": "数据集名称", "option": "测试集A" }
+{ "type": "antInput", "placeholder": "挂接资源", "value": "abc" }
+{ "type": "formFill", "fields": [
+    { "label": "名称", "type": "input", "value": "{{name}}" },
+    { "label": "类型", "type": "select", "value": "{{type}}" }
+], "validateAfter": true }
+```
+
+## 用例 DSL（Test Case）
+
+把多个用例统一为参数化 testCase JSON：
+
+```bash
+node local-browser-executor.js --action test-case --test-case-file /tmp/case.json [--dataset-index 0] [--test-report /tmp/report.json]
+```
+
+```json
+{
+    "title": "创建数据集 - P0",
+    "dataset": [{ "name": "A", "type": "图像" }, { "name": "B", "type": "文本" }],
+    "steps": [
+        { "type": "formFill", "fields": [
+            { "label": "名称", "type": "input", "value": "{{name}}" },
+            { "label": "类型", "type": "select", "value": "{{type}}" }
+        ], "validateAfter": true },
+        { "type": "expect", "assertion": "validation.toPass" },
+        { "type": "act", "click": "text=提交" },
+        { "type": "expect", "assertion": "url.toContain", "value": "/list" }
+    ],
+    "recovery": { "maxRetriesPerStep": 2 }
+}
+```
+
+## 语义断言（expect）
+
+| assertion | 功能 |
+|-----------|------|
+| `validation.toPass` | 表单校验无错误 |
+| `validation.toHaveError` | 某字段有错误 |
+| `locator.toBeVisible` / `toHaveText` / `toHaveValue` / `toHaveCount` | 元素状态 |
+| `url.toContain` / `url.toMatch` | URL 断言 |
+| `api.toAllPass` / `api.toInclude` | API 断言 |
+
+所有断言内置 `poll` 轮询（默认 timeout 5s, interval 200ms）。
+
+## 微前端（wujie / qiankun）场景适配
+
+**核心问题与解决：**
+
+| 微前端坑 | 自动修复 |
+|---------|---------|
+| 子应用业务在 frame[1]，每步都要重传 frameContentContains | testCase `setup.findFrame` 设一次，所有步骤默认走 `_activeFrame` |
+| 子应用路由切换销毁 iframe，导致后续 step 都 evaluate 失败 | `_getTargetFrame` 每次执行前探活，失活自动召回（标记 `frameRecovered: true`） |
+| Ant Select 的 `getPopupContainer` 把浮层渲染到父文档 | `antSelect` 触发器/浮层双 frame 协作：trigger 在子 frame mousedown，浮层在父 frame 找选项 |
+| 残留浮层污染下一次操作 | `closeAllDropdowns` 跨 frame 清理（主 + 所有可访问子 frame） |
+| `api.toAllPass` 因主应用埋点 404 误判子应用 P0 测试失败 | `step.scope: "current-frame"` 仅断言 `_activeFrame` 同源的请求 |
+
+**testCase 微前端模板：**
+
+```json
+{
+    "title": "数据集创建 P0",
+    "setup": {
+        "findFrame": { "contentContains": "数据集目录" }
+    },
+    "dataset": [{ "name": "A" }, { "name": "B" }],
+    "steps": [
+        { "type": "apiCapture", "urlPattern": "/api/dataset", "wait": 5000, "includeAllTargets": true },
+        { "type": "antInput", "field": "名称", "value": "{{name}}" },
+        { "type": "antSelect", "field": "类型", "option": "图像" },
+        { "type": "act", "click": "text=提交" },
+        { "type": "expect", "assertion": "validation.toPass" },
+        { "type": "expect", "assertion": "api.toAllPass", "scope": "current-frame" }
+    ]
+}
+```
+
+**关键参数：**
+
+- `setup.findFrame.contentContains` — 一次定位子应用 frame
+- `step.frameContentContains` — 单步覆盖（少用，违反 DRY）
+- `step.scope: "current-frame"` — API 断言仅看 `_activeFrame` 同源请求
+- `apiCapture.includeAllTargets: true` — 跨 page/iframe target 监听网络
+
+**调试技巧：**
+
+每个 ant 步骤结果含 `triggerFrameUrl` / `popupFrameUrl`，可看到触发器和浮层实际在哪个 frame。若 `_dropdownFrame: "main"` 出现，说明该控件用了 `getPopupContainer` 跨 frame 渲染浮层。
+
+## 非目标声明
+
+`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,184 @@ 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` | 探索性扫描遇到一条点不开就全部中断，没法发现整体面 |
+| 手写 puppeteer 脚本绕过 `act` 操作 Ant Select | 用 `antSelect` 步骤（内置 mousedown + 轮询 + closeAllDropdowns + VERIFY） | Ant Design Select 必须 mousedown 触发，浮层在 body 末尾，选项异步渲染，单步 `act.evaluate` 无法覆盖四步组合 |
+| 每个 Select 后忘记 `closeAllDropdowns` | `act` 自动检测上一次 antSelect/antTreeSelect 并预清理 | 下拉浮层残留会污染下一次 Select 操作，选项串选 |
+| 硬编码 `sleep(15*200)` 等选项渲染 | `antSelect` 内置 `pollEval` 15×200ms 轮询，`expect(poll)` 可自定义条件 | 选项渲染时间受网络/数据量影响，固定 sleep 时机不可靠 |
+| 表单校验用 ad-hoc evaluate 检查 | 用 `expect validation.toPass` 或 `formFill` 的 `validateAfter` | 语义断言自带 poll + 结构化错误信息（field + message），可直接进报告 |
+
+## Ant Design 适配层（6/22 反馈落地）
+
+把"触发器定位 → 浮层等待 → 选项交互 → VERIFY → 全局清理"固化为单步骤 JSON。
+
+| type | 功能 | 关键参数 |
+|------|------|---------|
+| `antSelect` | Ant Select 选项选择 | `field`, `option`, `mode` |
+| `antTreeSelect` | 树形选择 | `field`, `path` |
+| `antInput` | 输入框（支持 `placeholder` 定位） | `field`/`placeholder`, `value` |
+| `antRadio` / `antCheckbox` / `antSwitch` | 选择类 | `field`, `option`/`on` |
+| `antDatePicker` / `antCascader` / `antUpload` | 其他控件 | 见各方法文档 |
+| `formFill` | 批量填充 + 可选 `validateAfter` | `fields[]` |
+| `closeAllDropdowns` | 关闭所有下拉浮层 | - |
+
+**关键约束**：
+- Ant Select 必须 `mousedown` 触发（不是 click）
+- 选项异步渲染，内置 15×200ms 轮询
+- 每次操作前后自动 `closeAllDropdowns`，`act` 入口检测残留并预清理
+- 操作后 VERIFY `.ant-select-selection-item[title]` 回写
+
+```json
+{ "type": "antSelect", "field": "数据集名称", "option": "测试集A" }
+{ "type": "antInput", "placeholder": "挂接资源", "value": "abc" }
+{ "type": "formFill", "fields": [
+    { "label": "名称", "type": "input", "value": "{{name}}" },
+    { "label": "类型", "type": "select", "value": "{{type}}" }
+], "validateAfter": true }
+```
+
+## 用例 DSL（Test Case）
+
+把多个用例统一为参数化 testCase JSON：
+
+```bash
+node local-browser-executor.js --action test-case --test-case-file /tmp/case.json [--dataset-index 0] [--test-report /tmp/report.json]
+```
+
+```json
+{
+    "title": "创建数据集 - P0",
+    "dataset": [{ "name": "A", "type": "图像" }, { "name": "B", "type": "文本" }],
+    "steps": [
+        { "type": "formFill", "fields": [
+            { "label": "名称", "type": "input", "value": "{{name}}" },
+            { "label": "类型", "type": "select", "value": "{{type}}" }
+        ], "validateAfter": true },
+        { "type": "expect", "assertion": "validation.toPass" },
+        { "type": "act", "click": "text=提交" },
+        { "type": "expect", "assertion": "url.toContain", "value": "/list" }
+    ],
+    "recovery": { "maxRetriesPerStep": 2 }
+}
+```
+
+## 语义断言（expect）
+
+| assertion | 功能 |
+|-----------|------|
+| `validation.toPass` | 表单校验无错误 |
+| `validation.toHaveError` | 某字段有错误 |
+| `locator.toBeVisible` / `toHaveText` / `toHaveValue` / `toHaveCount` | 元素状态 |
+| `url.toContain` / `url.toMatch` | URL 断言 |
+| `api.toAllPass` / `api.toInclude` | API 断言 |
+
+所有断言内置 `poll` 轮询（默认 timeout 5s, interval 200ms）。
+
+## 微前端（wujie / qiankun）场景适配
+
+**核心问题与解决：**
+
+| 微前端坑 | 自动修复 |
+|---------|---------|
+| 子应用业务在 frame[1]，每步都要重传 frameContentContains | testCase `setup.findFrame` 设一次，所有步骤默认走 `_activeFrame` |
+| 子应用路由切换销毁 iframe，导致后续 step 都 evaluate 失败 | `_getTargetFrame` 每次执行前探活，失活自动召回（标记 `frameRecovered: true`） |
+| Ant Select 的 `getPopupContainer` 把浮层渲染到父文档 | `antSelect` 触发器/浮层双 frame 协作：trigger 在子 frame mousedown，浮层在父 frame 找选项 |
+| 残留浮层污染下一次操作 | `closeAllDropdowns` 跨 frame 清理（主 + 所有可访问子 frame） |
+| `api.toAllPass` 因主应用埋点 404 误判子应用 P0 测试失败 | `step.scope: "current-frame"` 仅断言 `_activeFrame` 同源的请求 |
+
+**testCase 微前端模板：**
+
+```json
+{
+    "title": "数据集创建 P0",
+    "setup": {
+        "findFrame": { "contentContains": "数据集目录" }
+    },
+    "dataset": [{ "name": "A" }, { "name": "B" }],
+    "steps": [
+        { "type": "apiCapture", "urlPattern": "/api/dataset", "wait": 5000, "includeAllTargets": true },
+        { "type": "antInput", "field": "名称", "value": "{{name}}" },
+        { "type": "antSelect", "field": "类型", "option": "图像" },
+        { "type": "act", "click": "text=提交" },
+        { "type": "expect", "assertion": "validation.toPass" },
+        { "type": "expect", "assertion": "api.toAllPass", "scope": "current-frame" }
+    ]
+}
+```
+
+**关键参数：**
+
+- `setup.findFrame.contentContains` — 一次定位子应用 frame
+- `step.frameContentContains` — 单步覆盖（少用，违反 DRY）
+- `step.scope: "current-frame"` — API 断言仅看 `_activeFrame` 同源请求
+- `apiCapture.includeAllTargets: true` — 跨 page/iframe target 监听网络
+
+**调试技巧：**
+
+每个 ant 步骤结果含 `triggerFrameUrl` / `popupFrameUrl`，可看到触发器和浮层实际在哪个 frame。若 `_dropdownFrame: "main"` 出现，说明该控件用了 `getPopupContainer` 跨 frame 渲染浮层。
+
+## 非目标声明
+
+`local-browser-test` **不**承担以下职责，遇到时显式拒绝并指给正确工具：
+
+- ❌ 接口压力测试 / 并发性能验证 → 用 k6、wrk、jmeter
+- ❌ 跨浏览器兼容性矩阵（Safari/Firefox 多版本）→ BrowserStack / SauceLabs
+- ❌ 单元测试 / 组件级测试 → Vitest / Jest / RTL
+- ❌ 视觉回归全量对比（无 baseline 设计稿）→ Percy / Chromatic
+- ✅ 真实浏览器内的功能验证、API 时序捕获、设计稿单图对比、动态菜单批量扫描