@szc-ft/mcp-szcd-client 0.28.2 → 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

@@ -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

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

@@ -49,6 +49,28 @@ export class AntAdapter {
         this.componentMeta = options.componentMeta || {};
     }
 
+    /**
+     * 统一的表单项查找 helper（浏览器端执行）
+     * 弹窗/抽屉打开时优先在其中搜索，避免页面搜索栏的同名 label 被错误命中
+     * 用法：在 frame.evaluate 内调用 _findFormItem(label)
+     */
+    static get FORM_ITEM_HELPER() {
+        return `
+function _findFormItem(label) {
+    var modalOrDrawer = document.querySelector('.ant-modal:not(.ant-modal-hidden), .ant-drawer:not(.ant-drawer-hidden), .ant-drawer-open .ant-drawer-content-wrapper');
+    var scope = modalOrDrawer || document;
+    var items = Array.from(scope.querySelectorAll('.ant-form-item'));
+    if (items.length === 0 && scope !== document) {
+        items = items.concat(Array.from(document.querySelectorAll('.ant-form-item')));
+    }
+    return items.find(function(el) {
+        var lbl = el.querySelector('.ant-form-item-label label, .ant-form-item-label');
+        return lbl && (lbl.innerText || lbl.textContent || '').trim().includes(label);
+    }) || null;
+}
+`;
+    }
+
     /**
      * 关闭所有打开的下拉浮层 / 抽屉 / 弹窗
      * 反馈第 2 条：每次 Select 操作后必须调用，否则下次操作会命中残留选项
@@ -61,9 +83,9 @@ export class AntAdapter {
             });
             // 2) 隐藏所有未隐藏的下拉浮层
             const dropdowns = document.querySelectorAll(
-                "body > .ant-select-dropdown:not(.ant-select-dropdown-hidden), " +
-                "body > .ant-cascader-dropdown:not(.ant-cascader-dropdown-hidden), " +
-                "body > .ant-picker-dropdown:not(.ant-picker-dropdown-hidden)"
+                ".ant-select-dropdown:not(.ant-select-dropdown-hidden), " +
+                ".ant-cascader-dropdown:not(.ant-cascader-dropdown-hidden), " +
+                ".ant-picker-dropdown:not(.ant-picker-dropdown-hidden)"
             );
             const count = dropdowns.length;
             dropdowns.forEach((el) => {
@@ -79,39 +101,45 @@ export class AntAdapter {
         }).catch(() => ({ closed: 0 }));
     }
 
+    /**
+     * 在 frame 上执行 evaluate，自动注入 _findFormItem helper
+     * 后续所有新方法只需调用本方法，无需手动处理弹窗/抽屉优先逻辑
+     */
+    async _evalWithFormHelper(frame, fnBody) {
+        const wrapped = "(function() {" + AntAdapter.FORM_ITEM_HELPER + "return (" + fnBody + ")();\n})()";
+        return frame.evaluate(wrapped);
+    }
+
     /**
      * 定位包含指定 label 的 .ant-form-item，返回其内 control 元素的 selector 信息
      * 不直接返回 ElementHandle（跨 evaluate 边界丢失），而是返回一个临时标记 id
      */
     async _markFormItemControl(frame, labelText, controlHint) {
-        return frame.evaluate(({ label, hint }) => {
-            const items = Array.from(document.querySelectorAll(".ant-form-item"));
-            const item = items.find((el) => {
-                const lbl = el.querySelector(".ant-form-item-label label, .ant-form-item-label");
-                if (!lbl) return false;
-                return (lbl.innerText || lbl.textContent || "").trim().includes(label);
-            });
+        const label = labelText.replace(/'/g, "\\'");
+        const hint = controlHint;
+        return this._evalWithFormHelper(frame, `() => {
+            const item = _findFormItem('${label}');
             if (!item) return { found: false };
 
             // 找控件：根据 hint 决定优先匹配何种节点
             let control;
-            if (hint === "select") {
+            if (${JSON.stringify(hint)} === "select") {
                 control = item.querySelector(".ant-select:not(.ant-select-disabled)");
-            } else if (hint === "treeSelect") {
+            } else if (${JSON.stringify(hint)} === "treeSelect") {
                 control = item.querySelector(".ant-select.ant-tree-select, .ant-tree-select");
-            } else if (hint === "cascader") {
+            } else if (${JSON.stringify(hint)} === "cascader") {
                 control = item.querySelector(".ant-cascader, .ant-cascader-picker");
-            } else if (hint === "datePicker") {
+            } else if (${JSON.stringify(hint)} === "datePicker") {
                 control = item.querySelector(".ant-picker");
-            } else if (hint === "input") {
+            } else if (${JSON.stringify(hint)} === "input") {
                 control = item.querySelector("input.ant-input, textarea.ant-input, .ant-input-affix-wrapper input");
-            } else if (hint === "radio") {
+            } else if (${JSON.stringify(hint)} === "radio") {
                 control = item.querySelector(".ant-radio-group");
-            } else if (hint === "checkbox") {
+            } else if (${JSON.stringify(hint)} === "checkbox") {
                 control = item.querySelector(".ant-checkbox-group, .ant-checkbox-wrapper");
-            } else if (hint === "switch") {
+            } else if (${JSON.stringify(hint)} === "switch") {
                 control = item.querySelector(".ant-switch");
-            } else if (hint === "upload") {
+            } else if (${JSON.stringify(hint)} === "upload") {
                 control = item.querySelector(".ant-upload input[type='file'], input[type='file']");
             } else {
                 control = item.querySelector("input, .ant-select, .ant-picker, .ant-cascader");
@@ -120,7 +148,7 @@ export class AntAdapter {
             if (!control) return { found: true, hasControl: false };
 
             // 用临时 data 属性标记，避免重复 traversal
-            const marker = `__sz_marker_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`;
+            const marker = '__sz_marker_' + Date.now() + '_' + Math.random().toString(36).slice(2, 6);
             control.setAttribute("data-sz-marker", marker);
             item.setAttribute("data-sz-form-item-marker", marker);
             const rect = control.getBoundingClientRect();
@@ -131,7 +159,7 @@ export class AntAdapter {
                 tagName: control.tagName,
                 visible: rect.width > 0 && rect.height > 0,
             };
-        }, { label: labelText, hint: controlHint });
+        }`);
     }
 
     async _clearMarkers(frame) {
@@ -189,12 +217,12 @@ export class AntAdapter {
         }
 
         const selectedSummary = [];
+        let popupResolved = popupFrame;
         for (const opt of options) {
             // 3) 浮层探测：先在触发器 frame 找，没找到再在 popupFrame 找（兜底）
-            let popupResolved = popupFrame;
             let optionFound = await pollEval(popupResolved, (text) => {
                 const items = Array.from(document.querySelectorAll(
-                    "body > .ant-select-dropdown:not(.ant-select-dropdown-hidden) .ant-select-item-option"
+                    ".ant-select-dropdown:not(.ant-select-dropdown-hidden) .ant-select-item-option"
                 ));
                 const visibleItems = items.filter((el) => {
                     const rect = el.getBoundingClientRect();
@@ -220,7 +248,7 @@ export class AntAdapter {
                 if (parentFrame && parentFrame !== frame) {
                     const retryFound = await pollEval(parentFrame, (text) => {
                         const items = Array.from(document.querySelectorAll(
-                            "body > .ant-select-dropdown:not(.ant-select-dropdown-hidden) .ant-select-item-option"
+                            ".ant-select-dropdown:not(.ant-select-dropdown-hidden) .ant-select-item-option"
                         ));
                         const visibleItems = items.filter((el) => {
                             const rect = el.getBoundingClientRect();
@@ -257,12 +285,13 @@ export class AntAdapter {
                 };
             }
 
-            // 4) mousedown 选项（在 popupResolved frame 内）
+            // 4) 点击选项（在 popupResolved frame 内），需同时触发 mousedown+click 才可驱动 React onChange
             await popupResolved.evaluate((tag) => {
                 const el = document.querySelector(`[data-sz-option-marker="${tag}"]`);
                 if (!el) return false;
                 el.dispatchEvent(new MouseEvent("mousedown", { bubbles: true, cancelable: true, button: 0 }));
                 el.dispatchEvent(new MouseEvent("mouseup", { bubbles: true, cancelable: true, button: 0 }));
+                el.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true, button: 0 }));
                 el.removeAttribute("data-sz-option-marker");
                 return true;
             }, optionFound.value.tag);
@@ -338,8 +367,8 @@ export class AntAdapter {
 
             const found = await pollEval(frame, ({ text, isLeaf }) => {
                 const titles = Array.from(document.querySelectorAll(
-                    "body > .ant-select-dropdown:not(.ant-select-dropdown-hidden) .ant-select-tree-title, " +
-                    "body > .ant-tree-select-dropdown:not(.ant-select-dropdown-hidden) .ant-select-tree-title"
+                    ".ant-select-dropdown:not(.ant-select-dropdown-hidden) .ant-select-tree-title, " +
+                    ".ant-tree-select-dropdown:not(.ant-select-dropdown-hidden) .ant-select-tree-title"
                 ));
                 const visible = titles.filter((el) => {
                     const rect = el.getBoundingClientRect();
@@ -408,29 +437,33 @@ export class AntAdapter {
      */
     async input(frame, target, value, opts = {}) {
         const clear = opts.clear !== false;
-        const result = await frame.evaluate(({ target, value, clear }) => {
-            let el = null;
-
-            if (target.label) {
-                const items = Array.from(document.querySelectorAll(".ant-form-item"));
-                const item = items.find((x) => {
-                    const lbl = x.querySelector(".ant-form-item-label");
-                    return lbl && (lbl.innerText || lbl.textContent || "").trim().includes(target.label);
-                });
-                el = item?.querySelector("input.ant-input, textarea.ant-input, .ant-input-affix-wrapper input, input[type='text'], input[type='number'], input[type='password'], input:not([type])");
-            } else if (target.placeholder) {
-                el = document.querySelector(`input[placeholder*="${target.placeholder}"], textarea[placeholder*="${target.placeholder}"]`);
-            } else if (target.selector) {
-                try { el = document.querySelector(target.selector); } catch { el = null; }
+        const label = (target.label || '').replace(/'/g, "\\'");
+        const placeholder = (target.placeholder || '').replace(/'/g, "\\'");
+        const selector = (target.selector || '').replace(/'/g, "\\'");
+
+        const result = await this._evalWithFormHelper(frame, `() => {
+            var el = null;
+            var val = ${JSON.stringify(value)};
+            var shouldClear = ${clear};
+
+            var item = _findFormItem('${label}');
+            if (item) {
+                el = item.querySelector("input.ant-input, textarea.ant-input, .ant-input-affix-wrapper input, input[type='text'], input[type='number'], input[type='password'], input:not([type])");
+            }
+            if (!el && '${placeholder}') {
+                el = document.querySelector('input[placeholder*="${placeholder}"], textarea[placeholder*="${placeholder}"]');
+            }
+            if (!el && '${selector}') {
+                try { el = document.querySelector('${selector}'); } catch(e) { el = null; }
             }
 
             if (!el) return { found: false };
             el.scrollIntoView({ block: "center" });
-            const proto = Object.getPrototypeOf(el);
-            const valueSetter = Object.getOwnPropertyDescriptor(proto, "value")?.set;
+            var proto = Object.getPrototypeOf(el);
+            var valueSetter = Object.getOwnPropertyDescriptor(proto, "value") && Object.getOwnPropertyDescriptor(proto, "value").set;
 
             el.focus();
-            const newValue = clear ? value : (el.value || "") + value;
+            var newValue = shouldClear ? val : (el.value || "") + val;
             if (valueSetter) {
                 valueSetter.call(el, newValue);
             } else {
@@ -444,7 +477,7 @@ export class AntAdapter {
                 placeholder: el.getAttribute("placeholder"),
                 tagName: el.tagName,
             };
-        }, { target, value, clear });
+        }`);
 
         return {
             acted: result.found,
@@ -460,27 +493,26 @@ export class AntAdapter {
      * Ant Radio 选择
      */
     async radio(frame, fieldLabel, optionLabel) {
-        const result = await frame.evaluate(({ field, opt }) => {
-            const items = Array.from(document.querySelectorAll(".ant-form-item"));
-            const item = items.find((x) => {
-                const lbl = x.querySelector(".ant-form-item-label");
-                return lbl && (lbl.innerText || lbl.textContent || "").trim().includes(field);
-            });
+        const field = fieldLabel.replace(/'/g, "\\'");
+        const opt = optionLabel.replace(/'/g, "\\'");
+
+        const result = await this._evalWithFormHelper(frame, `() => {
+            var item = _findFormItem('${field}');
             if (!item) return { found: false, reason: "form item not found" };
 
-            const wrappers = Array.from(item.querySelectorAll(".ant-radio-wrapper"));
-            const target = wrappers.find((w) => (w.innerText || "").trim().includes(opt));
-            if (!target) return { found: false, reason: `radio option "${opt}" not found`, available: wrappers.map((w) => (w.innerText || "").trim()) };
+            var wrappers = Array.from(item.querySelectorAll(".ant-radio-wrapper"));
+            var target = wrappers.find(function(w) { return (w.innerText || "").trim().includes('${opt}'); });
+            if (!target) return { found: false, reason: 'radio option not found', available: wrappers.map(function(w) { return (w.innerText || "").trim(); }) };
 
             target.scrollIntoView({ block: "center" });
             target.click();
-            const input = target.querySelector("input[type='radio']");
+            var input = target.querySelector("input[type='radio']");
             return {
                 found: true,
-                checked: input?.checked || false,
-                value: input?.value || "",
+                checked: input && input.checked || false,
+                value: input && input.value || "",
             };
-        }, { field: fieldLabel, opt: optionLabel });
+        }`);
         return {
             acted: result.found,
             field: fieldLabel,
@@ -495,24 +527,20 @@ export class AntAdapter {
      * Ant Checkbox 切换（按 label 文本）
      */
     async checkbox(frame, fieldLabel, optionLabel, checked = true) {
-        const result = await frame.evaluate(({ field, opt, target }) => {
-            const items = Array.from(document.querySelectorAll(".ant-form-item"));
-            const item = items.find((x) => {
-                const lbl = x.querySelector(".ant-form-item-label");
-                return lbl && (lbl.innerText || lbl.textContent || "").trim().includes(field);
-            });
+        const field = fieldLabel.replace(/'/g, "\\'");
+        const opt = (optionLabel || '').replace(/'/g, "\\'");
+
+        const result = await this._evalWithFormHelper(frame, `() => {
+            var item = _findFormItem('${field}');
             if (!item) return { found: false };
-            // 支持 group 和单独 checkbox
-            const wrappers = Array.from(item.querySelectorAll(".ant-checkbox-wrapper"));
-            const wrapper = opt
-                ? wrappers.find((w) => (w.innerText || "").includes(opt))
-                : wrappers[0];
+            var wrappers = Array.from(item.querySelectorAll(".ant-checkbox-wrapper"));
+            var wrapper = '${opt}' ? wrappers.find(function(w) { return (w.innerText || "").includes('${opt}'); }) : wrappers[0];
             if (!wrapper) return { found: false, reason: "checkbox not found" };
-            const input = wrapper.querySelector("input[type='checkbox']");
+            var input = wrapper.querySelector("input[type='checkbox']");
             if (!input) return { found: false };
-            if (input.checked !== target) wrapper.click();
+            if (input.checked !== ${checked}) wrapper.click();
             return { found: true, checked: input.checked };
-        }, { field: fieldLabel, opt: optionLabel, target: checked });
+        }`);
         return { acted: result.found, field: fieldLabel, option: optionLabel, verified: result.checked === checked };
     }
 
@@ -520,19 +548,17 @@ export class AntAdapter {
      * Ant Switch 切换
      */
     async switch(frame, fieldLabel, on = true) {
-        const result = await frame.evaluate(({ field, target }) => {
-            const items = Array.from(document.querySelectorAll(".ant-form-item"));
-            const item = items.find((x) => {
-                const lbl = x.querySelector(".ant-form-item-label");
-                return lbl && (lbl.innerText || lbl.textContent || "").trim().includes(field);
-            });
+        const field = fieldLabel.replace(/'/g, "\\'");
+
+        const result = await this._evalWithFormHelper(frame, `() => {
+            var item = _findFormItem('${field}');
             if (!item) return { found: false };
-            const sw = item.querySelector(".ant-switch");
+            var sw = item.querySelector(".ant-switch");
             if (!sw) return { found: false };
-            const isOn = sw.getAttribute("aria-checked") === "true" || sw.classList.contains("ant-switch-checked");
-            if (isOn !== target) sw.click();
-            return { found: true, state: target };
-        }, { field: fieldLabel, target: on });
+            var isOn = sw.getAttribute("aria-checked") === "true" || sw.classList.contains("ant-switch-checked");
+            if (isOn !== ${on}) sw.click();
+            return { found: true, state: ${on} };
+        }`);
         return { acted: result.found, field: fieldLabel, state: result.state, verified: result.state === on };
     }
 
@@ -541,29 +567,27 @@ export class AntAdapter {
      */
     async datePicker(frame, fieldLabel, dateString) {
         await this.closeAllDropdowns(frame);
-        const result = await frame.evaluate(({ field, value }) => {
-            const items = Array.from(document.querySelectorAll(".ant-form-item"));
-            const item = items.find((x) => {
-                const lbl = x.querySelector(".ant-form-item-label");
-                return lbl && (lbl.innerText || lbl.textContent || "").trim().includes(field);
-            });
+        const field = fieldLabel.replace(/'/g, "\\'");
+        const val = (dateString || '').replace(/'/g, "\\'");
+
+        const result = await this._evalWithFormHelper(frame, `() => {
+            var item = _findFormItem('${field}');
             if (!item) return { found: false };
-            const picker = item.querySelector(".ant-picker");
-            const input = picker?.querySelector("input");
+            var picker = item.querySelector(".ant-picker");
+            var input = picker && picker.querySelector("input");
             if (!input) return { found: false };
 
             input.scrollIntoView({ block: "center" });
             input.focus();
-            const setter = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(input), "value")?.set;
-            if (setter) setter.call(input, value);
-            else input.value = value;
+            var setter = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(input), "value") && Object.getOwnPropertyDescriptor(Object.getPrototypeOf(input), "value").set;
+            if (setter) setter.call(input, '${val}');
+            else input.value = '${val}';
             input.dispatchEvent(new Event("input", { bubbles: true }));
             input.dispatchEvent(new Event("change", { bubbles: true }));
-            // 回车确认
             input.dispatchEvent(new KeyboardEvent("keydown", { key: "Enter", code: "Enter", keyCode: 13, which: 13, bubbles: true }));
             input.blur();
             return { found: true, value: input.value };
-        }, { field: fieldLabel, value: dateString });
+        }`);
         await this.closeAllDropdowns(frame);
         return { acted: result.found, field: fieldLabel, value: result.value, verified: result.value === dateString };
     }
@@ -596,7 +620,7 @@ export class AntAdapter {
             const seg = segments[i];
             const result = await pollEval(frame, (text) => {
                 const all = Array.from(document.querySelectorAll(
-                    "body > .ant-cascader-dropdown:not(.ant-cascader-dropdown-hidden) .ant-cascader-menu-item"
+                    ".ant-cascader-dropdown:not(.ant-cascader-dropdown-hidden) .ant-cascader-menu-item"
                 ));
                 const visible = all.filter((el) => {
                     const r = el.getBoundingClientRect();
@@ -625,21 +649,16 @@ export class AntAdapter {
      * Upload 文件上传
      */
     async upload(frame, fieldLabel, filePath) {
-        // 注意：puppeteer 上传文件需要通过 ElementHandle.uploadFile，evaluate 内做不到
-        // 这里只能返回需要上层处理的标志
-        const result = await frame.evaluate((field) => {
-            const items = Array.from(document.querySelectorAll(".ant-form-item"));
-            const item = items.find((x) => {
-                const lbl = x.querySelector(".ant-form-item-label");
-                return lbl && (lbl.innerText || lbl.textContent || "").trim().includes(field);
-            });
+        const field = fieldLabel.replace(/'/g, "\\'");
+        const result = await this._evalWithFormHelper(frame, `() => {
+            var item = _findFormItem('${field}');
             if (!item) return { found: false };
-            const input = item.querySelector("input[type='file']");
+            var input = item.querySelector("input[type='file']");
             if (!input) return { found: false };
-            const marker = `__sz_upload_${Date.now()}`;
+            var marker = '__sz_upload_' + Date.now();
             input.setAttribute("data-sz-marker", marker);
-            return { found: true, marker };
-        }, fieldLabel);
+            return { found: true, marker: marker };
+        }`);
 
         if (!result.found) return { acted: false, reason: "upload input not found" };