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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@szc-ft/mcp-szcd-client",
-    "version": "0.28.0",
+    "version": "0.28.2",
     "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.28.0",
+    "version": "0.28.2",
     "description": "szcd 组件库 MCP 助手 — 查询组件信息、匹配需求、生成代码",
     "mcpServers": {
         "szcd-component-helper": {

package/qwen-extension/skills/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,155 @@ compatibility:
 
 ## 触发条件
 
-当用户说出以下关键词时启动浏览器测试：
-- "测试一下"、"帮我验证"、"浏览器测试"、"接管浏览器"
-- "对比设计稿"、"还原度"、"看看效果"
-- "功能测试"、"能不能正常用"
-- "检查页面"、"页面渲染"
+当用户出现以下意图时启动：
 
-## 主链路定位
+**用例自动化（用 testCase DSL）：**
+- "执行 P0 用例" / "批量测试" / "测试用例自动化"
+- "创建→审核→上线 全链路" / "生命周期测试"
+- "表单填写验证" / "深度表单测试"
+
+**轻量诊断（用 --action diagnose）：**
+- "测试一下" / "检查页面" / "看看效果" / "能不能正常用"
+- "JS 错误" / "页面渲染" / "API 检查"
+
+**视觉对比（用 --action compare）：**
+- "对比设计稿" / "还原度" / "像素对比"
+
+## ⚡ 路径解析（必读，避免 ad-hoc 脚本）
+
+**执行器内置在 skill 目录中（自包含），会话开始时先解析 skill 路径：**
 
-local-browser-test 的长期主链路是：
+```bash
+# 解析 skill 目录路径（执行器 + lib 都在 skill 目录内）
+export SKILL_DIR=$(node -p "
+  const path = require('path');
+  // 尝试从 npm 包解析
+  try { return path.dirname(require.resolve('@szc-ft/mcp-szcd-client/standard-skill/local-browser-test/SKILL.md')); } catch {}
+  // 尝试从 IDE skill 目录查找
+  const os = require('os');
+  const candidates = [
+    path.join(os.homedir(), '.qwen/extensions/szcd-component-helper/skills/local-browser-test'),
+    path.join(os.homedir(), '.claude/skills/local-browser-test'),
+    path.join(os.homedir(), '.config/opencode/skills/local-browser-test'),
+    path.join(os.homedir(), '.trae-cn/skills/local-browser-test'),
+    path.join(os.homedir(), '.qoder/skills/local-browser-test'),
+  ];
+  for (const c of candidates) {
+    if (require('fs').existsSync(path.join(c, 'local-browser-executor.js'))) return c;
+  }
+  throw new Error('local-browser-test skill not found');
+")
+echo "SKILL_DIR=$SKILL_DIR"
+
+# 执行器路径
+export EXECUTOR="$SKILL_DIR/local-browser-executor.js"
+```
+
+后续所有命令直接 `node "$EXECUTOR" --action ...`。
+
+**执行器 + lib 内置在 skill 目录中，自带 Ant 适配层 + expect 断言 + testCase 引擎。禁止自己 require puppeteer 写脚本**——自写脚本会丢失：
+- 微前端 frame 探活 + 自动召回
+- `closeAllDropdowns` 跨 frame 清理
+- Ant Select mousedown + VERIFY 回写
+- testCase recovery 重试
+- API 按 frame scope 过滤
+
+### 过渡兼容执行器
+
+`local-browser-executor.cjs`（同目录）是 CommonJS 过渡版，仅支持基础诊断（diagnose/screenshot/list-pages/api-check/plan/snapshot/interact/perf/watch）。**Ant 适配层 / testCase DSL / expect 断言仅 `local-browser-executor.js`（ES Module 版）支持。** 优先用 `.js` 版本。
+
+## 🎯 三种典型任务（场景驱动）
+
+### 任务 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 "$EXECUTOR" --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 "$EXECUTOR" --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 "$EXECUTOR" --action diagnose --url-contains "platform.aicityos.com" --wait 10000
+
+# 仅看 API
+node "$EXECUTOR" --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 用例首选入口
+  → $SKILL_DIR/local-browser-executor.js  ($EXECUTOR)
+  → $SKILL_DIR/lib/browser-engine.js  (executeTestCase + Ant 适配 + expect)
+  → $SKILL_DIR/lib/ant-adapter.js     (Select/TreeSelect/Input/Radio/...)
+  → $SKILL_DIR/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`。
+执行器 + lib 内置在 skill 目录中（自包含），`postinstall` 会把整个 skill 目录复制到各 IDE。
+**禁止 AI 在用户机器上写 ad-hoc puppeteer 脚本**——会丢失：
+- 微前端 frame 探活 + 自动召回
+- `closeAllDropdowns` 跨 frame 清理
+- Ant Select VERIFY 回写
+- testCase recovery 重试
+- API 按 frame scope 过滤
 
-`standard-skill/local-browser-test/local-browser-executor.cjs` 是过渡兼容执行器；新增稳定能力优先进入 `szcd-mcp-client/lib/browser-engine.js` 和根目录 `local-browser-executor.js`。
+`local-browser-executor.cjs`（同目录）是 CommonJS 过渡版，仅支持基础诊断。**Ant 适配层 / testCase DSL / expect 断言仅 `local-browser-executor.js`（ES Module 版）支持。**
 
 ## 浏览器模式
 
@@ -218,7 +344,7 @@ wujie 微前端子应用渲染在 blob URL iframe 中，**坐标点击无法到
 
 ### 结构化观察（主链路起点）
 ```bash
-node {client_path}/local-browser-executor.js \
+node "$EXECUTOR" \
   --action observe \
   --url-contains "platform.aicityos.com" \
   --frame-content-contains "数据集目录" \
@@ -230,7 +356,7 @@ node {client_path}/local-browser-executor.js \
 
 ### 观察后按 index 交互（主链路闭环）
 ```bash
-node {client_path}/local-browser-executor.js \
+node "$EXECUTOR" \
   --action act \
   --url-contains "platform.aicityos.com" \
   --frame-content-contains "数据集目录" \
@@ -241,7 +367,7 @@ node {client_path}/local-browser-executor.js \
 
 ### 左侧菜单路径稳定点击
 ```bash
-node {client_path}/local-browser-executor.js \
+node "$EXECUTOR" \
   --action act \
   --url-contains "platform.aicityos.com" \
   --menu-path "目录管理/数据集目录" \
@@ -253,7 +379,7 @@ node {client_path}/local-browser-executor.js \
 
 ### 轻量 DOM 断言
 ```bash
-node {client_path}/local-browser-executor.js \
+node "$EXECUTOR" \
   --action assert \
   --url-contains "platform.aicityos.com" \
   --selector ".ant-table" \
@@ -264,7 +390,7 @@ node {client_path}/local-browser-executor.js \
 
 ### API 请求/响应捕获（真实浏览器 + 微前端）
 ```bash
-node {client_path}/local-browser-executor.js \
+node "$EXECUTOR" \
   --action api-capture \
   --url-contains "platform.aicityos.com" \
   --frame-content-contains "数据集目录" \
@@ -279,7 +405,7 @@ node {client_path}/local-browser-executor.js \
 
 ### API 捕获结果断言
 ```bash
-node {client_path}/local-browser-executor.js \
+node "$EXECUTOR" \
   --action assert-api \
   --capture-file /tmp/browser-api-capture.json \
   --max-failed 0 \
@@ -292,7 +418,7 @@ node {client_path}/local-browser-executor.js \
 
 ### 快速诊断（过渡兼容）
 ```bash
-NODE_PATH=~/.szcd-mcp/deps/node_modules node {skill_path}/local-browser-executor.cjs \
+NODE_PATH=~/.szcd-mcp/deps/node_modules node "$SKILL_DIR/local-browser-executor.cjs" \
   --action diagnose \
   --url-contains "platform.aicityos.com" \
   --wait 15000 \
@@ -301,13 +427,13 @@ NODE_PATH=~/.szcd-mcp/deps/node_modules node {skill_path}/local-browser-executor
 
 ### 列出所有标签页
 ```bash
-NODE_PATH=~/.szcd-mcp/deps/node_modules node {skill_path}/local-browser-executor.cjs \
+NODE_PATH=~/.szcd-mcp/deps/node_modules node "$SKILL_DIR/local-browser-executor.cjs" \
   --action list-pages
 ```
 
 ### 检查 API 请求状态
 ```bash
-NODE_PATH=~/.szcd-mcp/deps/node_modules node {skill_path}/local-browser-executor.cjs \
+NODE_PATH=~/.szcd-mcp/deps/node_modules node "$SKILL_DIR/local-browser-executor.cjs" \
   --action api-check \
   --url-contains "platform.aicityos.com" \
   --wait 15000
@@ -315,7 +441,7 @@ NODE_PATH=~/.szcd-mcp/deps/node_modules node {skill_path}/local-browser-executor
 
 ### 截图
 ```bash
-NODE_PATH=~/.szcd-mcp/deps/node_modules node {skill_path}/local-browser-executor.cjs \
+NODE_PATH=~/.szcd-mcp/deps/node_modules node "$SKILL_DIR/local-browser-executor.cjs" \
   --action screenshot \
   --url-contains "platform.aicityos.com" \
   --filename current-page.png \
@@ -324,7 +450,7 @@ NODE_PATH=~/.szcd-mcp/deps/node_modules node {skill_path}/local-browser-executor
 
 ### 执行测试计划 JSON
 ```bash
-NODE_PATH=~/.szcd-mcp/deps/node_modules node {skill_path}/local-browser-executor.cjs \
+NODE_PATH=~/.szcd-mcp/deps/node_modules node "$SKILL_DIR/local-browser-executor.cjs" \
   --action plan \
   --plan-file /tmp/test-plan.json \
   --output /tmp/browser-test-result.json
@@ -332,7 +458,7 @@ NODE_PATH=~/.szcd-mcp/deps/node_modules node {skill_path}/local-browser-executor
 
 ### DOM 快照（结构化页面树，类似 browser-use take_snapshot）
 ```bash
-NODE_PATH=~/.szcd-mcp/deps/node_modules node {skill_path}/local-browser-executor.cjs \
+NODE_PATH=~/.szcd-mcp/deps/node_modules node "$SKILL_DIR/local-browser-executor.cjs" \
   --action snapshot \
   --url-contains "platform.aicityos.com" \
   --depth 4 \
@@ -353,25 +479,25 @@ NODE_PATH=~/.szcd-mcp/deps/node_modules node {skill_path}/local-browser-executor
 ### 智能交互（支持 text=、role=、~ 选择器，类似 Playwright）
 ```bash
 # 点击包含“构建”文本的按钮
-NODE_PATH=~/.szcd-mcp/deps/node_modules node {skill_path}/local-browser-executor.cjs \
+NODE_PATH=~/.szcd-mcp/deps/node_modules node "$SKILL_DIR/local-browser-executor.cjs" \
   --action interact \
   --url-contains "jenkins" \
   --click "text=Build"
 
 # 在输入框中输入文本
-NODE_PATH=~/.szcd-mcp/deps/node_modules node {skill_path}/local-browser-executor.cjs \
+NODE_PATH=~/.szcd-mcp/deps/node_modules node "$SKILL_DIR/local-browser-executor.cjs" \
   --action interact \
   --click "#search-input" \
   --type "hello world"
 
 # 悬停 + 截图
-NODE_PATH=~/.szcd-mcp/deps/node_modules node {skill_path}/local-browser-executor.cjs \
+NODE_PATH=~/.szcd-mcp/deps/node_modules node "$SKILL_DIR/local-browser-executor.cjs" \
   --action interact \
   --hover "~ant-menu-item" \
   --screenshot-after
 
 # 滚动页面
-NODE_PATH=~/.szcd-mcp/deps/node_modules node {skill_path}/local-browser-executor.cjs \
+NODE_PATH=~/.szcd-mcp/deps/node_modules node "$SKILL_DIR/local-browser-executor.cjs" \
   --action interact \
   --scroll down --scroll-amount 500
 ```
@@ -383,14 +509,14 @@ NODE_PATH=~/.szcd-mcp/deps/node_modules node {skill_path}/local-browser-executor
 
 ### 性能指标采集（FCP/TTFB/资源统计）
 ```bash
-NODE_PATH=~/.szcd-mcp/deps/node_modules node {skill_path}/local-browser-executor.cjs \
+NODE_PATH=~/.szcd-mcp/deps/node_modules node "$SKILL_DIR/local-browser-executor.cjs" \
   --action perf \
   --url-contains "platform.aicityos.com"
 ```
 
 ### 持续监控模式（定时截图 + 错误检测）
 ```bash
-NODE_PATH=~/.szcd-mcp/deps/node_modules node {skill_path}/local-browser-executor.cjs \
+NODE_PATH=~/.szcd-mcp/deps/node_modules node "$SKILL_DIR/local-browser-executor.cjs" \
   --action watch \
   --url-contains "platform.aicityos.com" \
   --interval 5000 \