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

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

@@ -1,6 +1,6 @@
 ---
 name: local-browser-test
-description: 本地浏览器测试工具，在用户本地 Chrome 中执行自动化测试。支持设计稿还原度对比（像素级评分）、功能验证（点击/输入/导航）、DOM 结构检查、JS 错误检测。通过 puppeteer-core 连接用户真实浏览器，天然继承登录态和微前端环境。
+description: 在用户真实 Chrome 中执行自动化测试，覆盖 P0 用例批量执行、深度表单填写、微前端测试、长任务生命周期、设计稿对比、JS 错误诊断。通过 puppeteer-core 连接 CDP，天然继承登录态/微前端环境。
 compatibility:
   tools:
     - run_command
@@ -11,29 +11,122 @@ compatibility:
 
 ## 触发条件
 
-当用户说出以下关键词时启动浏览器测试：
-- "测试一下"、"帮我验证"、"浏览器测试"、"接管浏览器"
-- "对比设计稿"、"还原度"、"看看效果"
-- "功能测试"、"能不能正常用"
-- "检查页面"、"页面渲染"
+当用户出现以下意图时启动：
 
-## 主链路定位
+**用例自动化（用 testCase DSL）：**
+- "执行 P0 用例" / "批量测试" / "测试用例自动化"
+- "创建→审核→上线 全链路" / "生命周期测试"
+- "表单填写验证" / "深度表单测试"
+
+**轻量诊断（用 --action diagnose）：**
+- "测试一下" / "检查页面" / "看看效果" / "能不能正常用"
+- "JS 错误" / "页面渲染" / "API 检查"
+
+**视觉对比（用 --action compare）：**
+- "对比设计稿" / "还原度" / "像素对比"
+
+## ⚡ 路径解析（必读，避免 ad-hoc 脚本）
+
+**所有命令使用 `$CLIENT_PATH` 变量，会话开始时先解析一次：**
+
+```bash
+# 解析客户端安装路径（成功后所有命令复用此变量）
+export CLIENT_PATH=$(node -p "require.resolve('@szc-ft/mcp-szcd-client/local-browser-executor.js')" 2>/dev/null \
+  || node -p "require('path').dirname(require.resolve('@szc-ft/mcp-szcd-client/package.json')) + '/local-browser-executor.js'")
+echo "CLIENT_PATH=$CLIENT_PATH"
+```
+
+后续所有命令直接 `node "$CLIENT_PATH" --action ...`，**不要自己 require puppeteer 写脚本**——执行器已封装好 antSelect/formFill/expect/testCase 等步骤，自己写脚本会丢失微前端 frame 探活、closeAllDropdowns、verify 回写等保护。
 
-local-browser-test 的长期主链路是：
+## 🎯 三种典型任务（场景驱动）
+
+### 任务 A：P0 用例批量执行（首选）
+
+用户说"执行 P0 用例 / 批量测试 / 生命周期测试"时，**不要写 ad-hoc puppeteer 脚本**，构造 testCase JSON：
+
+```bash
+cat > /tmp/case.json <<'EOF'
+{
+    "title": "数据集创建 P0",
+    "setup": { "findFrame": { "contentContains": "数据集目录" } },
+    "dataset": [
+        { "name": "测试集A", "type": "图像" },
+        { "name": "测试集B", "type": "文本" }
+    ],
+    "steps": [
+        { "type": "formFill", "fields": [
+            { "label": "名称", "type": "input", "value": "{{name}}" },
+            { "label": "资源类型", "type": "select", "value": "{{type}}" },
+            { "label": "审核结果", "type": "radio", "value": "通过" }
+        ], "validateAfter": true },
+        { "type": "act", "click": "text=提 交" },
+        { "type": "expect", "assertion": "url.toContain", "value": "/list" },
+        { "type": "expect", "assertion": "api.toAllPass", "scope": "current-frame" }
+    ],
+    "recovery": { "maxRetriesPerStep": 2 }
+}
+EOF
+node "$CLIENT_PATH" --action test-case --test-case-file /tmp/case.json --test-report /tmp/report.json
+```
+
+dataset 数组每行跑一遍同样的 steps，`{{name}}` / `{{type}}` 自动替换。`setup.findFrame` 一次定位后所有步骤自动走子应用 frame（微前端默认行为）。
+
+### 任务 B：深度表单填写（Ant Design + 微前端）
+
+用户描述"填表单 / Select 选项 / TreeSelect / 挂接资源"时，用单步 antXxx 或 formFill：
+
+```bash
+# 单字段
+node "$CLIENT_PATH" --action act --frame-content-contains "数据集" \
+    --selector ant-select=资源类型 --click ... # ❌ 不要这样
+
+# ✅ 用 testCase 的 antSelect 步骤（在 testCase.steps 内）：
+#   { "type": "antSelect", "field": "资源类型", "option": "图像" }
+#   { "type": "antTreeSelect", "field": "分类", "path": ["AI", "视觉"] }
+#   { "type": "antInput", "placeholder": "挂接资源", "value": "abc" }
+#   { "type": "antRadio", "field": "审核结果", "option": "通过" }
+#   { "type": "formFill", "fields": [...], "validateAfter": true }
+```
+
+**关键约束（执行器已内置，无需手写）：**
+- Ant Select 必须 mousedown（不是 click）
+- 浮层异步渲染 15×200ms 轮询
+- 每次操作前后 `closeAllDropdowns` 防串选
+- VERIFY 回写检查 `.ant-select-selection-item`
+
+### 任务 C：轻量诊断（看页面是否正常）
+
+```bash
+# 一次性看 JS 错误 + API 失败 + iframe 状态
+node "$CLIENT_PATH" --action diagnose --url-contains "platform.aicityos.com" --wait 10000
+
+# 仅看 API
+node "$CLIENT_PATH" --action api-capture --url-contains "platform.aicityos.com" \
+    --url-pattern "/api/" --wait 10000 --include-response-body \
+    --output /tmp/api.json
+```
+
+---
+
+## 主链路定位
 
 ```
 Agent / SKILL.md
-  → szcd-mcp-client/local-browser-executor.js
-  → lib/browser-engine.js
+  → testCase JSON  ←  P0 用例首选入口
+  → szcd-mcp-client/local-browser-executor.js  ($CLIENT_PATH)
+  → lib/browser-engine.js  (executeTestCase + Ant 适配 + expect)
+  → lib/ant-adapter.js     (Select/TreeSelect/Input/Radio/...)
+  → lib/expect.js          (validation/locator/url/api + poll)
   → puppeteer-core + CDP
   → 用户真实 Chrome / Edge
 ```
 
-目标是在用户真实登录态/真实微前端环境中形成 browser-use + Playwright 结合体：
-- browser-use 侧：`observe → act → observe`，通过结构化页面观察和交互元素 index 支持自主任务执行。
-- Playwright 侧：locator、actionability、assert、plan 报告逐步收敛到 `BrowserEngine`。
-
-`standard-skill/local-browser-test/local-browser-executor.cjs` 是过渡兼容执行器；新增稳定能力优先进入 `szcd-mcp-client/lib/browser-engine.js` 和根目录 `local-browser-executor.js`。
+新增稳定能力优先进入 `lib/browser-engine.js` 和 `lib/ant-adapter.js`，**禁止 AI 在用户机器上写 ad-hoc puppeteer 脚本**——会丢失：
+- 微前端 frame 探活 + 自动召回
+- `closeAllDropdowns` 跨 frame 清理
+- Ant Select VERIFY 回写
+- testCase recovery 重试
+- API 按 frame scope 过滤
 
 ## 浏览器模式
 
@@ -547,6 +640,119 @@ cd ~/.szcd-mcp/deps && npm install --registry=https://registry.npmmirror.com --@
 | `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 渲染浮层。
 
 ## 非目标声明