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

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

@@ -27,16 +27,46 @@ compatibility:
 
 ## ⚡ 路径解析（必读，避免 ad-hoc 脚本）
 
-**所有命令使用 `$CLIENT_PATH` 变量，会话开始时先解析一次：**
+**执行器内置在 skill 目录中（自包含），会话开始时先解析 skill 路径：**
 
 ```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"
-```
+# 解析 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 过滤
+
+### 过渡兼容执行器
 
-后续所有命令直接 `node "$CLIENT_PATH" --action ...`，**不要自己 require puppeteer 写脚本**——执行器已封装好 antSelect/formFill/expect/testCase 等步骤，自己写脚本会丢失微前端 frame 探活、closeAllDropdowns、verify 回写等保护。
+`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` 版本。
 
 ## 🎯 三种典型任务（场景驱动）
 
@@ -66,7 +96,7 @@ cat > /tmp/case.json <<'EOF'
     "recovery": { "maxRetriesPerStep": 2 }
 }
 EOF
-node "$CLIENT_PATH" --action test-case --test-case-file /tmp/case.json --test-report /tmp/report.json
+node "$EXECUTOR" --action test-case --test-case-file /tmp/case.json --test-report /tmp/report.json
 ```
 
 dataset 数组每行跑一遍同样的 steps，`{{name}}` / `{{type}}` 自动替换。`setup.findFrame` 一次定位后所有步骤自动走子应用 frame（微前端默认行为）。
@@ -77,7 +107,7 @@ dataset 数组每行跑一遍同样的 steps，`{{name}}` / `{{type}}` 自动替
 
 ```bash
 # 单字段
-node "$CLIENT_PATH" --action act --frame-content-contains "数据集" \
+node "$EXECUTOR" --action act --frame-content-contains "数据集" \
     --selector ant-select=资源类型 --click ... # ❌ 不要这样
 
 # ✅ 用 testCase 的 antSelect 步骤（在 testCase.steps 内）：
@@ -98,10 +128,10 @@ node "$CLIENT_PATH" --action act --frame-content-contains "数据集" \
 
 ```bash
 # 一次性看 JS 错误 + API 失败 + iframe 状态
-node "$CLIENT_PATH" --action diagnose --url-contains "platform.aicityos.com" --wait 10000
+node "$EXECUTOR" --action diagnose --url-contains "platform.aicityos.com" --wait 10000
 
 # 仅看 API
-node "$CLIENT_PATH" --action api-capture --url-contains "platform.aicityos.com" \
+node "$EXECUTOR" --action api-capture --url-contains "platform.aicityos.com" \
     --url-pattern "/api/" --wait 10000 --include-response-body \
     --output /tmp/api.json
 ```
@@ -113,21 +143,24 @@ node "$CLIENT_PATH" --action api-capture --url-contains "platform.aicityos.com"
 ```
 Agent / SKILL.md
   → 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)
+  → $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
 ```
 
-新增稳定能力优先进入 `lib/browser-engine.js` 和 `lib/ant-adapter.js`，**禁止 AI 在用户机器上写 ad-hoc puppeteer 脚本**——会丢失：
+执行器 + lib 内置在 skill 目录中（自包含），`postinstall` 会把整个 skill 目录复制到各 IDE。
+**禁止 AI 在用户机器上写 ad-hoc puppeteer 脚本**——会丢失：
 - 微前端 frame 探活 + 自动召回
 - `closeAllDropdowns` 跨 frame 清理
 - Ant Select VERIFY 回写
 - testCase recovery 重试
 - API 按 frame scope 过滤
 
+`local-browser-executor.cjs`（同目录）是 CommonJS 过渡版，仅支持基础诊断。**Ant 适配层 / testCase DSL / expect 断言仅 `local-browser-executor.js`（ES Module 版）支持。**
+
 ## 浏览器模式
 
 支持两种模式，执行器自动检测优先使用 connect：
@@ -311,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 "数据集目录" \
@@ -323,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 "数据集目录" \
@@ -334,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 "目录管理/数据集目录" \
@@ -346,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" \
@@ -357,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 "数据集目录" \
@@ -372,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 \
@@ -385,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 \
@@ -394,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
@@ -408,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 \
@@ -417,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
@@ -425,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 \
@@ -446,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
 ```
@@ -476,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 \