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

package/opencode-extension/skills/local-browser-test/lib/browser-engine.js

@@ -24,6 +24,7 @@ export class BrowserEngine {
         this._activeFrame = null;  // 当前活跃 iframe 上下文（微前端场景）
         this._adapter = null;      // 懒加载 AntAdapter
         this._lastActWasDropdown = false; // 用于 act 入口自动 closeAllDropdowns
+        this._wujieContext = null;  // wujie 微前端模式 { type, frameCount, wujieApp? }
     }
 
     /**
@@ -72,6 +73,133 @@ export class BrowserEngine {
         }
     }
 
+    /**
+     * 检测 wujie 微前端模式（WebComponent / iframe）
+     * @returns {{ type: 'webcomponent'|'iframe'|'none', frameCount: number, wujieApp?: object }}
+     */
+    async _detectWujieMode() {
+        const frames = this.page.frames();
+        const frameCount = frames.length;
+        const mainFrame = this.page.mainFrame();
+
+        // 检查主文档中是否有 <wujie-app> 自定义元素（WebComponent 模式标志）
+        const wujieInfo = await mainFrame.evaluate(() => {
+            const app = document.querySelector('wujie-app');
+            if (!app) return null;
+            const sr = app.shadowRoot;
+            return {
+                tagName: app.tagName,
+                className: app.className,
+                hasShadowRoot: !!sr,
+                shadowChildren: sr?.children?.length || 0,
+                shadowBodyText: sr?.querySelector('body')?.innerText?.substring(0, 80) || ''
+            };
+        }).catch(() => null);
+
+        if (wujieInfo) {
+            const ctx = { type: 'webcomponent', frameCount, wujieApp: wujieInfo };
+            process.stderr.write(`[wujie] WebComponent 模式: <${wujieInfo.tagName} class="${wujieInfo.className}"> shadowRoot=${wujieInfo.hasShadowRoot} children=${wujieInfo.shadowChildren} frames=${frameCount}\n`);
+            if (wujieInfo.shadowBodyText) {
+                process.stderr.write(`[wujie]   shadow body preview: "${wujieInfo.shadowBodyText}"\n`);
+            }
+            // 列出所有 frame 供排障
+            for (let i = 0; i < frames.length; i++) {
+                process.stderr.write(`[wujie]   frame[${i}]: ${frames[i].url().substring(0, 100)}\n`);
+            }
+            return ctx;
+        }
+
+        if (frameCount > 1) {
+            process.stderr.write(`[wujie] iframe 模式: ${frameCount} frames\n`);
+            for (let i = 0; i < frames.length; i++) {
+                process.stderr.write(`[wujie]   frame[${i}]: ${frames[i].url().substring(0, 100)}\n`);
+            }
+            return { type: 'iframe', frameCount };
+        }
+
+        process.stderr.write(`[wujie] 未检测到微前端 (frames=${frameCount})\n`);
+        return { type: 'none', frameCount };
+    }
+
+    /**
+     * 安全获取页面列表（优先同步 targets() 避免 pages() 挂死 + 泄露 WebSocket）
+     */
+    async _safeGetPages() {
+        // 1. 优先使用同步 targets()，不会挂死也不会泄露未完成的 promise
+        try {
+            const targets = this.browser.targets();
+            const pageTargets = targets.filter((t) => t.type() === "page");
+            if (pageTargets.length > 0) {
+                const pages = [];
+                for (const t of pageTargets) {
+                    try {
+                        const p = await Promise.race([
+                            t.page(),
+                            new Promise((_, reject) => setTimeout(() => reject(new Error("page() timeout")), 3000)),
+                        ]);
+                        if (p) pages.push(p);
+                    } catch {
+                        // 跳过无法获取的 target
+                    }
+                }
+                if (pages.length > 0) return pages;
+            }
+        } catch {
+            // targets() 失败
+        }
+
+        // 2. 回退：CDP Target.getTargets
+        try {
+            const client = await this.browser.target().createCDPSession();
+            const { targetInfos } = await client.send("Target.getTargets");
+            const pageInfos = targetInfos.filter((t) => t.type === "page");
+            const pages = [];
+            for (const info of pageInfos) {
+                try {
+                    const target = await Promise.race([
+                        this.browser.waitForTarget((t) => t.url() === info.url, { timeout: 2000 }),
+                        new Promise((_, reject) => setTimeout(() => reject(new Error("waitForTarget timeout")), 3000)),
+                    ]);
+                    if (target) {
+                        const p = await Promise.race([
+                            target.page(),
+                            new Promise((_, reject) => setTimeout(() => reject(new Error("page() timeout")), 3000)),
+                        ]);
+                        if (p) pages.push(p);
+                    }
+                } catch {
+                    // skip
+                }
+            }
+            if (pages.length > 0) return pages;
+        } catch {
+            // CDP 回退也失败
+        }
+
+        // 3. 最后手段：只能尝试 pages()（带严格超时，用完立即 disconnect/reconnect 清理）
+        try {
+            const pages = await Promise.race([
+                this.browser.pages(),
+                new Promise((_, reject) => setTimeout(() => reject(new Error("pages() timeout")), 5000)),
+            ]);
+            if (pages && pages.length > 0) return pages;
+        } catch {
+            // pages() 超时；注意此时 browser.pages() 的 WebSocket 可能泄露
+            // 清理：断开后重新连接
+            try {
+                const wsUrl = this.browser.wsEndpoint();
+                const puppeteer = await loadPuppeteer();
+                await this.browser.disconnect();
+                this.browser = await puppeteer.connect({ browserWSEndpoint: wsUrl, defaultViewport: null });
+            } catch {
+                // reconnect 失败，继续用当前 browser
+            }
+        }
+
+        // 4. 最后手段：newPage()
+        return [await this.browser.newPage()];
+    }
+
     /**
      * 模式 A：连接到用户已有的 Chrome
      */
@@ -82,7 +210,7 @@ export class BrowserEngine {
         this.ownedBrowser = false;
 
         // 获取页面：优先使用指定 URL 匹配的标签页
-        const pages = await this.browser.pages();
+        const pages = await this._safeGetPages();
         if (options.pageUrl) {
             this.page = pages.find((p) => p.url().includes(options.pageUrl))
                      || await this.browser.newPage();
@@ -96,6 +224,9 @@ export class BrowserEngine {
             await this.page.setViewport(options.viewport);
         }
 
+        // 微前端模式检测
+        this._wujieContext = await this._detectWujieMode();
+
         return {
             mode: "connect",
             cdpUrl,
@@ -223,6 +354,7 @@ export class BrowserEngine {
                 frameUrl: targetFrame.frame.url(),
                 matchedBy: targetFrame.matchedBy,
             },
+            wujieContext: this._wujieContext,
             frames,
             tree,
             interactiveElements,
@@ -247,7 +379,10 @@ export class BrowserEngine {
 
         const targetFrame = await this._resolveObserveFrame(options);
         if (options.menuPath) {
-            return this._actMenuPath(targetFrame, options);
+            // 菜单在 main frame 外壳中渲染，不随子应用切换
+            const menuFrame = this.page.mainFrame();
+            const menuTarget = { frame: menuFrame, frameId: "main", matchedBy: "main (menu shell)" };
+            return this._actMenuPath(menuTarget, options);
         }
 
         const index = options.index !== undefined ? Number.parseInt(options.index, 10) : undefined;
@@ -944,6 +1079,15 @@ export class BrowserEngine {
     }
 
     async _resolveObserveFrame(options = {}) {
+        // testCase setup 已预定位 iframe，且调用方未显式传 frame 参数 → 直接复用
+        if (this._activeFrame && options.frameIndex === undefined && !options.frameUrlContains && !options.frameContentContains) {
+            const frames = this.page.frames();
+            const idx = frames.indexOf(this._activeFrame);
+            if (idx >= 0) {
+                return { frame: this._activeFrame, frameId: idx === 0 ? "main" : `frame-${idx}`, matchedBy: "activeFrame (from testCase setup)" };
+            }
+        }
+
         const frames = this.page.frames();
         const mainFrame = this.page.mainFrame();
 
@@ -973,6 +1117,14 @@ export class BrowserEngine {
             }
         }
 
+        // 无显式 frame 参数时：WebComponent 模式默认用 sandbox iframe（含子应用实际 DOM）
+        if (this._wujieContext?.type === 'webcomponent' && frames.length > 1) {
+            const sandboxIdx = frames.findIndex((f) => f !== mainFrame && !f.url().startsWith('about:'));
+            if (sandboxIdx >= 0) {
+                return { frame: frames[sandboxIdx], frameId: `frame-${sandboxIdx}`, matchedBy: 'webcomponent sandbox iframe' };
+            }
+        }
+
         const mainIndex = frames.indexOf(mainFrame);
         return { frame: mainFrame, frameId: mainIndex <= 0 ? "main" : `frame-${mainIndex}`, matchedBy: "main" };
     }
@@ -1693,7 +1845,7 @@ export class BrowserEngine {
      * 查找已打开的标签页（connect 模式，端口可变场景）
      */
     async _findPage(step) {
-        const pages = await this.browser.pages();
+        const pages = await this._safeGetPages();
         let matched = null;
         let matchReason = "";
 

package/opencode-extension/skills/local-browser-test/package.json

@@ -0,0 +1 @@
+{"type": "module"}

package/opencode-extension/skills/szcd-upload-zip/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: szcd-upload-zip
+description: |
+    本地 ZIP 文件上传与解压工具。将用户本地的 zip 压缩包通过 `upload-zip` REST 端点上传到 szcd-mcp-server，
+    自动解压到服务器的 `uploads/<zip包名>/` 目录，并返回解压后的文件列表。
+    上传后解压的文件可通过文件下载接口按路径获取或供其他流程使用。
+compatibility:
+  tools:
+    - run_command
+  runtime:
+    - node >= 18（读取配置用，仅 `cat ~/.szcd-mcp-config.json` 场景）
+    - curl（文件上传所需）
+---
+
+# ZIP 上传与解压工具（szcd-upload-zip）
+
+## 概述
+
+当 AI 需要将用户本地的 ZIP 压缩包上传到 szcd-mcp-server 时，使用此技能。
+上传后服务器自动解压，开发者或 AI 可通过下载 API 访问解压后的文件。
+
+## 适用场景
+
+- 用户有一个本地 zip 包需要上传到服务器存储
+- zipped 源码/资源包需要上传到服务器供后续流程使用
+- 需要在服务器端解压 zip 并取用其中的文件
+
+## 工作流
+
+### 第 0 步：探测运行时
+
+```bash
+node --version 2>/dev/null && echo "NODE_OK"; \
+curl --version 2>/dev/null | head -1 && echo "CURL_OK"
+```
+
+### 第 1 步：读取配置获取服务器地址和 API Key
+
+```bash
+cat ~/.szcd-mcp-config.json
+```
+
+配置示例：
+```json
+{
+  "MCP_SERVER_URL": "http://localhost:3456",
+  "MCP_TIMEOUT": 30000,
+  "MCP_API_KEY": "your-api-key"
+}
+```
+
+- 若 `MCP_API_KEY` 为空字符串，则上传时不带 `X-API-Key` header
+- 若 `MCP_SERVER_URL` 未配置，默认使用 `http://localhost:3456`
+
+### 第 2 步：上传 ZIP 文件
+
+```bash
+# 从 ~/.szcd-mcp-config.json 取 URL 和 API Key
+MCP_URL=$(node -e "const c=require('fs').readFileSync(require('os').homedir()+'/.szcd-mcp-config.json','utf8');const j=JSON.parse(c);console.log(j.MCP_SERVER_URL||'http://localhost:3456')")
+MCP_KEY=$(node -e "const c=require('fs').readFileSync(require('os').homedir()+'/.szcd-mcp-config.json','utf8');const j=JSON.parse(c);console.log(j.MCP_API_KEY||'')")
+
+# 上传 zip 文件
+if [ -n "$MCP_KEY" ]; then
+  curl -s -X POST "$MCP_URL/upload-zip" -H "X-API-Key: $MCP_KEY" -F "file=@<zip文件路径>"
+else
+  curl -s -X POST "$MCP_URL/upload-zip" -F "file=@<zip文件路径>"
+fi
+```
+
+其中 `<zip文件路径>` 替换为实际 zip 文件的绝对路径。
+
+**响应示例：**
+```json
+{
+  "ok": true,
+  "dir_name": "my-package",
+  "extract_dir": "/scity/zengzhijie/mcp/uploads/my-package",
+  "file_count": 5,
+  "files": [
+    { "path": "index.html", "size": 2048 },
+    { "path": "js/app.js", "size": 15360 },
+    { "path": "css/style.css", "size": 4096 },
+    { "path": "images/logo.png", "size": 819200 },
+    { "path": "data/config.json", "size": 512 }
+  ]
+}
+```
+
+### 第 3 步：查看解压后的文件
+
+上传成功后，可通过下载 API 查看解压后的文件或取单个文件内容：
+
+```bash
+# 列出解压目录
+curl -s "$MCP_URL/api/download/list?dir=/scity/zengzhijie/mcp/uploads/my-package" \
+  ${MCP_KEY:+-H "X-API-Key: $MCP_KEY"}
+
+# 下载单个文件
+curl -s "$MCP_URL/api/download?path=/scity/zengzhijie/mcp/uploads/my-package/data/config.json" \
+  ${MCP_KEY:+-H "X-API-Key: $MCP_KEY"}
+```
+
+## 限制说明
+
+- 仅支持真正的 ZIP 格式（magic number `PK\x03\x04` 校验），改扩展名无用
+- 单文件大小上限 100MB
+- 同名 zip 包名会覆盖服务器上已有的目录
+- 解压后文件持久存储，无自动过期
+- 上传路径始终为 `/upload-zip`（不含 `/api/` 前缀）
+
+## 完整命令示例（一步完成）
+
+```bash
+# 读取配置
+MCP_URL=$(node -e "try{const c=require('fs').readFileSync(require('os').homedir()+'/.szcd-mcp-config.json','utf8');const j=JSON.parse(c);console.log(j.MCP_SERVER_URL||'http://localhost:3456')}catch{console.log('http://localhost:3456')}")
+MCP_KEY=$(node -e "try{const c=require('fs').readFileSync(require('os').homedir()+'/.szcd-mcp-config.json','utf8');const j=JSON.parse(c);console.log(j.MCP_API_KEY||'')}catch{console.log('')}")
+
+# 上传
+curl -s -X POST "$MCP_URL/upload-zip" \
+  ${MCP_KEY:+-H "X-API-Key: $MCP_KEY"} \
+  -F "file=@/path/to/archive.zip" | python3 -m json.tool
+```

package/package.json

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

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

@@ -215,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 }` |
 
 ### 场景选择策略
 
@@ -246,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 从设计稿分析结果或组件布局推断**
 
 ## 微前端测试指南（实战经验）
 
@@ -692,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" }
@@ -732,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 | 功能 |
@@ -762,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