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

package/agents/szcd-component-expert.qoder.md

@@ -17,6 +17,7 @@ skills:
   - local-browser-test
   - szcd-component-helper
   - szcd-design-to-code
+  - szcd-upload-zip
 mcpServers:
   - szcd-component-helper
   - sketch-mcp-server

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：
@@ -182,13 +215,18 @@ AI 直接构造测试计划 JSON：
 | click | 点击元素（兼容） | `selector`, `waitForNavigation` | `{ clicked, tagName }` |
 | type | 输入文本（兼容） | `selector`, `text`, `clear` | `{ typed, value }` |
 | waitFor | 等待条件 | `selector` 或 `url`, `timeout` | `{ matched, waited }` |
-| evaluate | 执行 JS | `expression` | `{ result }` |
+| evaluate | 执行 JS（浏览器端） | `expression`, `expectResult?`, `expectResultContains?`, `failOnFalsy?` | `{ result, passed, reason }` |
 | checkElement | 元素断言（兼容） | `selector`, `expect: {visible, minCount, maxCount, hasText}` | `{ passed, checks, elementCount }` |
 | findPage | 查找已打开的标签页 | `urlIncludes` 或 `urlRegex` 或 `titleIncludes` | `{ found, url, title, totalPages }` |
-| findFrame | 查找微前端 iframe | `urlIncludes` 或 `urlRegex` 或 `titleIncludes` 或 `contentIncludes` 或 `frameIndex` | `{ found, frameUrl, matchedBy, totalFrames }` |
+| findFrame | 查找微前端 iframe | `frameSelector`(CSS选择器) 或 `frameUrlContains` 或 `frameContentContains` 或 `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[] }` |
+| **apiCall** | **API 直调（绕过 UI）** | `method`, `url`, `body?`, `headers?` | `{ status, data, passed }` |
+| **switchPage** | **多标签页切换** | `urlContains?`/`titleIncludes?`/`pageIndex?` | `{ passed, url, title }` |
+| **cdpScript** | **调用内置/已注册脚本** | `script`, `params?` | `{ acted, passed, ...result }` |
+| **rawScript** | **Node.js 端执行任意 async** | `code`, `params?` | `{ acted, passed, ...result }` |
+| **registerCdpScript** | **注册可复用脚本** | `name`, `code` | `{ registered, passed }` |
 
 ### 场景选择策略
 
@@ -213,14 +251,33 @@ AI 直接构造测试计划 JSON：
 
 ### 构造步骤的指导原则
 
-1. **selector 必须从用户代码中读取，不要猜测**
-   - 读代码中的 `id`、`className`、`data-testid`
-   - szcd 组件的 class 可通过 `get_component_full_profile` 获取
-2. **API 路径从代码中的接口调用读取**
-3. **checkElement 的 expect 从代码逻辑推断**
-   - columns 定义了 N 列 → `expect: { minCount: N }`（检查 th 数量）
-   - dataSource 有数据 → `expect: { minCount: 1 }`（检查行数）
-4. **compare 的 regions 从设计稿分析结果或组件布局推断**
+**⚠️ 强制流程：构造 test-case JSON 前必须先执行 DOM 预检查**
+
+1. **observe 检查目标页面 DOM 结构**
+   - 确认 frame 结构（主页面 + 子应用 iframe）
+   - 确认表格/表单/按钮的 selector
+   - 确认 setup.findFrame 的匹配方式（frameSelector/frameUrlContains）
+
+2. **evaluate 检查关键元素文字**
+   - 按钮文字（如“提 交”中间有空格，不能用“提交”匹配）
+   - Select 选项文字（如“AI知识主题库”可能与 UI 显示不一致）
+   - 表单字段 label（如“数据资源名称”vs“数据集名称”）
+   - 表格列头（确认列数和列名）
+
+3. **根据 DOM 检查结果构造 test-case JSON**
+   - selector 从 observe 获取（不猜测）
+   - 选项文字从 evaluate 获取（不猜测）
+   - 按钮文字从 evaluate 获取（注意空格）
+   - 无项目代码时，DOM 检查替代代码读取
+
+4. **act 文字匹配**
+   - `text=新建` → 模糊匹配（includes），可能误匹配“新建目录”
+   - `text==新建` → 精确匹配（===），只匹配文字恰好为“新建”的元素
+   - 按钮文字可能有空格（如“提 交”），evaluate 检查后再选择匹配方式
+
+5. **API 路径从代码中的接口调用读取，或从 API 文档获取**
+6. **checkElement 的 expect 从代码逻辑推断**
+7. **compare 的 regions 从设计稿分析结果或组件布局推断**
 
 ## 微前端测试指南（实战经验）
 
@@ -311,7 +368,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 +380,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 +391,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 +403,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 +414,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 +429,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 +442,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 +451,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 +465,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 +474,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 +482,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 +503,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 +533,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 \
@@ -659,11 +716,15 @@ cd ~/.szcd-mcp/deps && npm install --registry=https://registry.npmmirror.com --@
 | `formFill` | 批量填充 + 可选 `validateAfter` | `fields[]` |
 | `closeAllDropdowns` | 关闭所有下拉浮层 | - |
 
-**关键约束**：
-- Ant Select 必须 `mousedown` 触发（不是 click）
-- 选项异步渲染，内置 15×200ms 轮询
-- 每次操作前后自动 `closeAllDropdowns`，`act` 入口检测残留并预清理
-- 操作后 VERIFY `.ant-select-selection-item[title]` 回写
+**关键约束（6/22 反馈后更新）**：
+- Ant Select 必须 `mousedown` + `click` 触发（click 触发 React onChange）
+- 选项异步渲染，内置 poll 轮询（timeout 默认 3s，不限制 1.5s）
+- `closeAllDropdowns` 去掉 `body >` 限制（适配微前端浮层）+ 增加 300ms sleep
+- 选项点击后 mousedown + mouseup + **click**（三步组合）
+- VERIFY 全局兜底：marker 丢失时全局搜索 `.ant-select-selection-item`
+- VERIFY 检查 `title` + `innerText` + `textContent`（三重兜底）
+- `popupResolved` 变量提升到 for 循环外（避免作用域 bug）
+- 浮层选择器去掉 `body >` 限制（`.ant-select-dropdown` 而非 `body > .ant-select-dropdown`）
 
 ```json
 { "type": "antSelect", "field": "数据集名称", "option": "测试集A" }
@@ -699,6 +760,75 @@ node local-browser-executor.js --action test-case --test-case-file /tmp/case.jso
 }
 ```
 
+## 脚本执行能力分层
+
+| 层级 | 步骤类型 | 执行环境 | 能力 | 适用场景 |
+|------|---------|---------|------|---------|
+| 1 | evaluate | 浏览器端 | DOM 查询/操作 | 简单检查、点击元素 |
+| 2 | rawScript | Node.js 端 | 完整 puppeteer API | 跨 frame、等待、多标签页 |
+| 3 | cdpScript | Node.js 端 | 调用已注册脚本 | 复用通用交互模式 |
+| 4 | 内置 cdpScript | Node.js 端 | 预定义通用 UI 交互 | Drawer/Modal/表格等 |
+
+**evaluate**：浏览器端执行 JS，只能操作 DOM，不能等待/跨 frame/调用 puppeteer
+**rawScript**：Node.js 端执行 async 函数，接收 `(page, frame, params, browser)`，可调用所有 puppeteer API
+**registerCdpScript**：注册可复用脚本，后续通过 cdpScript 步骤按 name 调用
+**cdpScript**：调用 registerCdpScript 注册的脚本或内置脚本
+
+### 内置 cdpScript（通用 UI 交互模式）
+
+| script | 功能 | params |
+|--------|------|--------|
+| `drawer-action` | Drawer 操作 | `action: 'search'\|'select'\|'confirm'\|'cancel'`, `radioIndex?`, `searchText?`, `searchPlaceholder?` |
+| `modal-action` | Modal/Popconfirm 操作 | `action: 'confirm'\|'cancel'`, `buttonText?` |
+| `switch-tab` | 多标签页切换 | `urlContains?`, `titleIncludes?`, `pageIndex?` |
+| `wait-api` | 等待 API 响应 | `urlPattern`, `timeout?`, `method?` |
+| `get-table-data` | 提取表格数据 | `selector?`, `maxRows?` |
+
+**设计原则**：cdpScript 内置通用 UI 交互模式（跨项目复用），业务流程由 LLM 用 rawScript 动态生成
+
+```json
+// 内置 cdpScript 示例
+{ "type": "cdpScript", "script": "get-table-data", "params": { "maxRows": 5 } }
+{ "type": "cdpScript", "script": "drawer-action", "params": { "action": "select", "radioIndex": 0 } }
+{ "type": "cdpScript", "script": "drawer-action", "params": { "action": "confirm" } }
+{ "type": "cdpScript", "script": "modal-action", "params": { "action": "confirm" } }
+{ "type": "cdpScript", "script": "switch-tab", "params": { "urlContains": "localhost:8088" } }
+
+// rawScript 示例（LLM 动态生成业务逻辑）
+{ "type": "rawScript", "code": "async (page, frame, params, browser) => { var count = await frame.evaluate(() => document.querySelectorAll('tr').length); return { acted: true, passed: count > 0, rowCount: count, status: 'PASS' } }" }
+
+// registerCdpScript + cdpScript（先注册再调用）
+{ "type": "registerCdpScript", "name": "my-check", "code": "async (page, frame, params) => { ... }" }
+{ "type": "cdpScript", "script": "my-check", "params": { "id": "123" } }
+```
+
+### evaluate 增强
+
+```json
+// expectResult：精确匹配返回值
+{ "type": "evaluate", "expression": "...", "expectResult": "found" }
+
+// expectResultContains：包含匹配返回值
+{ "type": "evaluate", "expression": "...", "expectResultContains": "数据资源" }
+
+// failOnFalsy：返回 falsy 时标记 FAIL
+{ "type": "evaluate", "expression": "...", "failOnFalsy": true }
+```
+
+### apiCall（API 直调）
+
+```json
+{ "type": "apiCall", "method": "POST", "url": "http://localhost:8088/api/submit", "body": { "id": "123" } }
+// → { status: 200, data: { code: "200" }, passed: true }
+```
+
+### switchPage（多标签页切换）
+
+```json
+{ "type": "switchPage", "urlContains": "localhost:8088" }
+// → { passed: true, url: "http://localhost:8088/...", title: "..." }
+```
+
 ## 语义断言（expect）
 
 | assertion | 功能 |
@@ -729,20 +859,26 @@ node local-browser-executor.js --action test-case --test-case-file /tmp/case.jso
 {
     "title": "数据集创建 P0",
     "setup": {
-        "findFrame": { "contentContains": "数据集目录" }
+        "findFrame": { "frameUrlContains": "#/catalog/" }
     },
     "dataset": [{ "name": "A" }, { "name": "B" }],
     "steps": [
-        { "type": "apiCapture", "urlPattern": "/api/dataset", "wait": 5000, "includeAllTargets": true },
+        { "type": "navigate", "url": "http://localhost:8088/#/szc-ai-data/catalog/catalog-manage", "waitUntil": "domcontentloaded" },
+        { "type": "expect", "assertion": "locator.toBeVisible", "selector": ".ant-table", "timeout": 20000 },
         { "type": "antInput", "field": "名称", "value": "{{name}}" },
         { "type": "antSelect", "field": "类型", "option": "图像" },
-        { "type": "act", "click": "text=提交" },
+        { "type": "act", "click": "text==提 交" },
         { "type": "expect", "assertion": "validation.toPass" },
-        { "type": "expect", "assertion": "api.toAllPass", "scope": "current-frame" }
+        { "type": "expect", "assertion": "locator.toBeVisible", "selector": ".ant-table", "timeout": 15000 }
     ]
 }
 ```
 
+**findFrame 三种方案（按稳定性排序）**：
+- `frameSelector: "iframe"` — 基于 DOM 选择器（最稳定，推荐）
+- `frameUrlContains: "#/catalog/"` — 基于 URL 子串（navigate 后可能失效）
+- `frameContentContains: "数据集目录"` — 基于内容文字（页面未加载时不可用）
+
 **关键参数：**
 
 - `setup.findFrame.contentContains` — 一次定位子应用 frame