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

package/lib/expect.js

@@ -0,0 +1,392 @@
+/**
+ * 语义断言层 — Playwright expect.poll 风格
+ *
+ * 设计目标：把"15×200ms 硬循环 + ad-hoc checkElement"统一成 Promise 风格的可组合断言。
+ * 所有断言返回 { passed, reason, actual, expected, duration }，可直接进测试报告。
+ *
+ * 用法：
+ *   const exp = createExpect(engine);
+ *   await exp.poll(() => frame.$$eval(".ant-select-item-option", els => els.length > 0));
+ *   await exp.locator(frame, "text=提交").toBeVisible({ timeout: 3000 });
+ *   await exp.validation(frame).toPass();
+ *   await exp.url(page).toContain("/catalog/list");
+ *   await exp.api(captureResult).toAllPass();
+ */
+
+const DEFAULT_TIMEOUT = 5000;
+const DEFAULT_INTERVAL = 200;
+
+/**
+ * 轮询直到 predicate 返回 truthy，否则超时
+ * @param {Function} predicate - 异步函数，返回值参与判定
+ * @param {object} options - { timeout, interval, message }
+ * @returns {Promise<{ passed, value, attempts, duration }>}
+ */
+export async function poll(predicate, options = {}) {
+    const timeout = Number.parseInt(options.timeout ?? DEFAULT_TIMEOUT, 10);
+    const interval = Number.parseInt(options.interval ?? DEFAULT_INTERVAL, 10);
+    const start = Date.now();
+    let attempts = 0;
+    let lastValue;
+    let lastError;
+
+    while (Date.now() - start < timeout) {
+        attempts += 1;
+        try {
+            lastValue = await predicate();
+            if (lastValue) {
+                return {
+                    passed: true,
+                    value: lastValue,
+                    attempts,
+                    duration: Date.now() - start,
+                };
+            }
+        } catch (err) {
+            lastError = err;
+        }
+        await new Promise((r) => setTimeout(r, interval));
+    }
+
+    return {
+        passed: false,
+        value: lastValue,
+        attempts,
+        duration: Date.now() - start,
+        reason: lastError
+            ? `predicate threw: ${lastError.message}`
+            : options.message || `poll timeout after ${timeout}ms (last value: ${JSON.stringify(lastValue)?.slice(0, 200)})`,
+    };
+}
+
+/**
+ * 元素定位断言器：locator(frame, selector) 返回带 toXxx 的对象
+ * selector 支持 text= / role= / ~xxx / 普通 CSS
+ */
+export function locator(frame, selector) {
+    /**
+     * 在 frame 内查找匹配 selector 的第一个元素，返回该元素的可观测状态。
+     * 一次 evaluate 取齐所有状态，避免多次 round-trip。
+     */
+    async function probe() {
+        return frame.evaluate((sel) => {
+            function resolveSelector(s) {
+                if (!s) return null;
+                if (s.startsWith("~")) {
+                    const cls = s.slice(1).replace(/^\./, "");
+                    return `[class*="${cls}"]`;
+                }
+                return s;
+            }
+            function isVisible(el) {
+                const rect = el.getBoundingClientRect();
+                const style = window.getComputedStyle(el);
+                return rect.width > 0 && rect.height > 0
+                    && style.display !== "none"
+                    && style.visibility !== "hidden"
+                    && Number(style.opacity) !== 0;
+            }
+            function isEnabled(el) {
+                return !el.disabled && el.getAttribute("aria-disabled") !== "true";
+            }
+            function findText(text) {
+                const candidates = Array.from(document.querySelectorAll(
+                    "a,button,input,select,textarea,summary,span,div,label,[role],[data-testid]"
+                ));
+                return candidates.find((el) => {
+                    if (!isVisible(el)) return false;
+                    const t = (el.innerText || el.textContent || "").trim();
+                    return t.includes(text);
+                });
+            }
+            function findRole(roleSpec) {
+                const match = roleSpec.match(/^([^\[]+)(?:\[name="([^"]+)"\])?/);
+                const role = match?.[1]?.trim();
+                const name = match?.[2]?.trim();
+                const all = Array.from(document.querySelectorAll(`[role="${role}"]`));
+                return all.find((el) => {
+                    if (!isVisible(el)) return false;
+                    if (!name) return true;
+                    const t = (el.innerText || el.textContent || "").trim();
+                    return t.includes(name) || (el.getAttribute("aria-label") || "").includes(name);
+                });
+            }
+
+            let el = null;
+            if (sel.startsWith("text=")) {
+                el = findText(sel.slice(5).trim().replace(/^["']|["']$/g, ""));
+            } else if (sel.startsWith("role=")) {
+                el = findRole(sel.slice(5));
+            } else {
+                try { el = document.querySelector(resolveSelector(sel)); } catch { el = null; }
+            }
+
+            if (!el) return { found: false };
+
+            const rect = el.getBoundingClientRect();
+            return {
+                found: true,
+                tagName: el.tagName,
+                text: (el.innerText || el.textContent || "").trim().slice(0, 200),
+                value: "value" in el ? el.value : null,
+                visible: isVisible(el),
+                enabled: isEnabled(el),
+                rect: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
+                attributes: {
+                    id: el.id || null,
+                    class: el.className?.toString?.() || null,
+                    placeholder: el.getAttribute("placeholder"),
+                    "aria-label": el.getAttribute("aria-label"),
+                    "aria-checked": el.getAttribute("aria-checked"),
+                    title: el.getAttribute("title"),
+                },
+            };
+        }, selector);
+    }
+
+    return {
+        async toBeVisible(opts = {}) {
+            const r = await poll(async () => {
+                const s = await probe();
+                return s.found && s.visible ? s : null;
+            }, { ...opts, message: `expect ${selector} to be visible` });
+            return formatAssertResult(r, { assertion: "toBeVisible", selector });
+        },
+
+        async toBeHidden(opts = {}) {
+            const r = await poll(async () => {
+                const s = await probe();
+                return !s.found || !s.visible ? s || { found: false } : null;
+            }, { ...opts, message: `expect ${selector} to be hidden` });
+            return formatAssertResult(r, { assertion: "toBeHidden", selector });
+        },
+
+        async toBeEnabled(opts = {}) {
+            const r = await poll(async () => {
+                const s = await probe();
+                return s.found && s.enabled ? s : null;
+            }, { ...opts, message: `expect ${selector} to be enabled` });
+            return formatAssertResult(r, { assertion: "toBeEnabled", selector });
+        },
+
+        async toHaveText(expected, opts = {}) {
+            const r = await poll(async () => {
+                const s = await probe();
+                if (!s.found) return null;
+                return s.text.includes(expected) ? s : null;
+            }, { ...opts, message: `expect ${selector} to have text "${expected}"` });
+            return formatAssertResult(r, { assertion: "toHaveText", selector, expected });
+        },
+
+        async toHaveValue(expected, opts = {}) {
+            const r = await poll(async () => {
+                const s = await probe();
+                if (!s.found || s.value == null) return null;
+                return s.value === expected || s.value.includes?.(expected) ? s : null;
+            }, { ...opts, message: `expect ${selector} to have value "${expected}"` });
+            return formatAssertResult(r, { assertion: "toHaveValue", selector, expected });
+        },
+
+        async toHaveCount(expected, opts = {}) {
+            const r = await poll(async () => {
+                const count = await frame.evaluate((s) => {
+                    try { return document.querySelectorAll(s.startsWith("~") ? `[class*="${s.slice(1).replace(/^\./, "")}"]` : s).length; }
+                    catch { return -1; }
+                }, selector);
+                return count === expected ? count : null;
+            }, { ...opts, message: `expect ${selector} to have count ${expected}` });
+            return formatAssertResult(r, { assertion: "toHaveCount", selector, expected });
+        },
+
+        async toHaveAttribute(name, value, opts = {}) {
+            const r = await poll(async () => {
+                const s = await probe();
+                if (!s.found) return null;
+                const actual = s.attributes[name];
+                if (value === undefined) return actual != null ? actual : null;
+                return actual === value || actual?.includes?.(value) ? actual : null;
+            }, { ...opts, message: `expect ${selector} attribute ${name} to be "${value}"` });
+            return formatAssertResult(r, { assertion: "toHaveAttribute", selector, name, expected: value });
+        },
+    };
+}
+
+/**
+ * 表单校验断言：检查 frame 内是否还有 form-item-explain-error
+ */
+export function validation(frame) {
+    return {
+        async toPass(opts = {}) {
+            const r = await poll(async () => {
+                const errors = await frame.evaluate(() => {
+                    const items = Array.from(document.querySelectorAll(".ant-form-item-explain-error, .ant-form-item-has-error .ant-form-item-explain"));
+                    return items
+                        .filter((el) => {
+                            const rect = el.getBoundingClientRect();
+                            return rect.width > 0 && rect.height > 0;
+                        })
+                        .map((el) => {
+                            const formItem = el.closest(".ant-form-item");
+                            const label = formItem?.querySelector(".ant-form-item-label label, .ant-form-item-label")?.innerText?.trim() || "";
+                            return {
+                                field: label,
+                                message: (el.innerText || el.textContent || "").trim(),
+                            };
+                        });
+                });
+                return errors.length === 0 ? { errors: [] } : null;
+            }, { ...opts, message: "expect form validation to pass" });
+
+            if (r.passed) {
+                return formatAssertResult(r, { assertion: "validation.toPass", expected: "no errors" });
+            }
+            // 失败时把当前错误列表带回去
+            const currentErrors = await frame.evaluate(() => {
+                const items = Array.from(document.querySelectorAll(".ant-form-item-explain-error, .ant-form-item-has-error .ant-form-item-explain"));
+                return items.map((el) => {
+                    const formItem = el.closest(".ant-form-item");
+                    const label = formItem?.querySelector(".ant-form-item-label label, .ant-form-item-label")?.innerText?.trim() || "";
+                    return { field: label, message: (el.innerText || el.textContent || "").trim() };
+                });
+            }).catch(() => []);
+
+            return formatAssertResult(r, {
+                assertion: "validation.toPass",
+                expected: "no errors",
+                actual: currentErrors,
+            });
+        },
+
+        async toHaveError(fieldOrMessage, opts = {}) {
+            const r = await poll(async () => {
+                const errors = await frame.evaluate(() => {
+                    const items = Array.from(document.querySelectorAll(".ant-form-item-explain-error"));
+                    return items.map((el) => {
+                        const formItem = el.closest(".ant-form-item");
+                        const label = formItem?.querySelector(".ant-form-item-label label, .ant-form-item-label")?.innerText?.trim() || "";
+                        return { field: label, message: (el.innerText || el.textContent || "").trim() };
+                    });
+                });
+                const matched = errors.find((e) =>
+                    e.field.includes(fieldOrMessage) || e.message.includes(fieldOrMessage)
+                );
+                return matched || null;
+            }, { ...opts, message: `expect validation error for "${fieldOrMessage}"` });
+            return formatAssertResult(r, { assertion: "validation.toHaveError", expected: fieldOrMessage });
+        },
+    };
+}
+
+/**
+ * URL 断言（针对 page，不需要 poll，因为 url 通常已稳定，但提供选项化轮询）
+ */
+export function url(page) {
+    return {
+        async toContain(expected, opts = {}) {
+            const r = await poll(async () => {
+                const u = page.url();
+                return u.includes(expected) ? u : null;
+            }, { timeout: opts.timeout ?? 1000, interval: 100, message: `expect url to contain "${expected}"` });
+            return formatAssertResult(r, { assertion: "url.toContain", expected, actual: page.url() });
+        },
+
+        async toMatch(regex, opts = {}) {
+            const re = regex instanceof RegExp ? regex : new RegExp(regex);
+            const r = await poll(async () => {
+                const u = page.url();
+                return re.test(u) ? u : null;
+            }, { timeout: opts.timeout ?? 1000, interval: 100 });
+            return formatAssertResult(r, { assertion: "url.toMatch", expected: re.toString(), actual: page.url() });
+        },
+    };
+}
+
+/**
+ * API 捕获结果断言（基于 captureApi 的返回值）
+ * @param {object} captureResult - captureApi 返回对象
+ * @param {object} [options] - { scope: "current-frame"|"all", frameUrlContains }
+ */
+export function api(captureResult, options = {}) {
+    const allRequests = captureResult?.requests || [];
+    const scope = options.scope || "all";
+
+    // 按 frame 范围过滤请求
+    let requests = allRequests;
+    if (scope === "current-frame" && options.frameUrlContains) {
+        requests = allRequests.filter((r) => r.frameUrl && r.frameUrl.includes(options.frameUrlContains));
+    }
+
+    return {
+        toAllPass() {
+            const failed = requests.filter((r) => (r.status && r.status >= 400) || r.errorText);
+            const passed = failed.length === 0;
+            return {
+                passed,
+                assertion: "api.toAllPass",
+                expected: "all requests status < 400",
+                actual: failed.length === 0 ? "all ok" : failed,
+                totalRequests: allRequests.length,
+                scopedRequests: requests.length,
+                reason: passed ? null : `${failed.length}/${requests.length} requests failed`,
+            };
+        },
+
+        toHaveNoFailed() {
+            return this.toAllPass();
+        },
+
+        toInclude(urlPattern) {
+            const re = typeof urlPattern === "string" ? new RegExp(urlPattern) : urlPattern;
+            const matched = requests.find((r) => re.test(r.url));
+            return {
+                passed: Boolean(matched),
+                assertion: "api.toInclude",
+                expected: urlPattern.toString(),
+                actual: matched || null,
+                totalRequests: allRequests.length,
+                scopedRequests: requests.length,
+                reason: matched ? null : `no request matched ${urlPattern}`,
+            };
+        },
+
+        toHaveCount(expected) {
+            return {
+                passed: requests.length === expected,
+                assertion: "api.toHaveCount",
+                expected,
+                actual: requests.length,
+                totalRequests: allRequests.length,
+                scopedRequests: requests.length,
+                reason: requests.length === expected ? null : `got ${requests.length} requests`,
+            };
+        },
+    };
+}
+
+function formatAssertResult(pollResult, meta) {
+    return {
+        passed: pollResult.passed,
+        assertion: meta.assertion,
+        selector: meta.selector,
+        expected: meta.expected,
+        actual: meta.actual ?? pollResult.value,
+        attempts: pollResult.attempts,
+        duration: pollResult.duration,
+        reason: pollResult.passed ? null : pollResult.reason,
+    };
+}
+
+/**
+ * 工厂：返回绑定 frame/page 的 expect 接口
+ */
+export function createExpect(target) {
+    return {
+        poll,
+        locator: (selector) => locator(target.frame || target, selector),
+        validation: () => validation(target.frame || target),
+        url: () => url(target.page || target),
+        api,
+    };
+}
+
+export default { poll, locator, validation, url, api, createExpect };

package/lib/test-plan.js

@@ -0,0 +1,48 @@
+/**
+ * plan → testCase 兼容编译器
+ *
+ * 把现有线性 plan JSON 自动升级为 testCase 对象，无需用户迁移。
+ * 规则：
+ *   - plan.steps[] → testCase.steps
+ *   - plan.dataset 存在 → 参数化执行
+ *   - 新 step type（antSelect/antInput/expect/formFill 等）原样保留
+ *   - 旧 step type（click/type/checkElement 等）也原样保留
+ */
+
+/**
+ * 编译 plan JSON 为 testCase 对象
+ * @param {object} plan - 现有 plan 格式
+ * @returns {object} testCase 对象
+ */
+export function compilePlan(plan) {
+    return {
+        title: plan.description || plan.planId || `auto-${Date.now()}`,
+        labels: plan.labels || [],
+        setup: {
+            findPage: plan.findPage || undefined,
+            findFrame: plan.findFrame || undefined,
+            apiCapture: plan.apiCapture || undefined,
+        },
+        dataset: plan.dataset || [],
+        steps: plan.steps || [],
+        recovery: plan.recovery || {},
+        teardown: plan.teardown || undefined,
+        // 透传元数据，报告使用
+        _planId: plan.planId,
+        _options: plan.options,
+    };
+}
+
+/**
+ * 编译 plan 文件内容为 testCase 对象数组
+ * @param {object|object[]} fileContent - plan JSON 或 plan 数组
+ * @returns {object[]} testCase 数组
+ */
+export function compilePlanFile(fileContent) {
+    if (Array.isArray(fileContent)) {
+        return fileContent.map(compilePlan);
+    }
+    return [compilePlan(fileContent)];
+}
+
+export default { compilePlan, compilePlanFile };

package/local-browser-executor.js

@@ -216,6 +216,18 @@ function parseArgs() {
             case "--capture-input-file":
                 parsed.captureInputFile = args[++i];
                 break;
+            case "--test-case":
+                parsed.testCaseJson = args[++i];
+                break;
+            case "--test-case-file":
+                parsed.testCaseFile = args[++i];
+                break;
+            case "--dataset-index":
+                parsed.datasetIndex = Number.parseInt(args[++i], 10);
+                break;
+            case "--test-report":
+                parsed.testReport = args[++i];
+                break;
             case "--help":
             case "-h":
                 printHelp();
@@ -555,11 +567,68 @@ async function executeAction(args) {
                 }, context);
                 return { type: "runTask", ...result, browserInfo: initResult, startTime: startedAt, endTime: new Date().toISOString() };
             }
+            case "test-case":
+            case "testCase": {
+                // 加载 testCase 定义
+                let testCase;
+                if (args.testCaseFile) {
+                    try {
+                        testCase = JSON.parse(fs.readFileSync(args.testCaseFile, "utf8"));
+                    } catch (err) {
+                        return {
+                            error: `读取 test-case 文件失败: ${err.message}`,
+                            errorCode: "TEST_CASE_INVALID",
+                            startTime: startedAt,
+                            endTime: new Date().toISOString(),
+                        };
+                    }
+                } else if (args.testCaseJson) {
+                    try {
+                        testCase = JSON.parse(args.testCaseJson);
+                    } catch (err) {
+                        return {
+                            error: `解析 --test-case JSON 失败: ${err.message}`,
+                            errorCode: "TEST_CASE_INVALID",
+                            startTime: startedAt,
+                            endTime: new Date().toISOString(),
+                        };
+                    }
+                } else {
+                    return {
+                        error: "必须提供 --test-case 或 --test-case-file",
+                        errorCode: "TEST_CASE_MISSING",
+                        startTime: startedAt,
+                        endTime: new Date().toISOString(),
+                    };
+                }
+
+                // 支持 --dataset-index 仅执行某一行
+                if (args.datasetIndex !== undefined && Array.isArray(testCase.dataset)) {
+                    if (args.datasetIndex < 0 || args.datasetIndex >= testCase.dataset.length) {
+                        return {
+                            error: `--dataset-index ${args.datasetIndex} 越界（共 ${testCase.dataset.length} 行）`,
+                            errorCode: "DATASET_INDEX_OUT_OF_RANGE",
+                        };
+                    }
+                    testCase.dataset = [testCase.dataset[args.datasetIndex]];
+                }
+
+                const result = await engine.executeTestCase(testCase, {});
+
+                if (args.testReport) {
+                    const dir = path.dirname(args.testReport);
+                    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+                    fs.writeFileSync(args.testReport, JSON.stringify(result, null, 2), "utf8");
+                    process.stderr.write(`测试报告已写入: ${args.testReport}\n`);
+                }
+
+                return { type: "testCase", ...result, browserInfo: initResult, startTime: startedAt, endTime: new Date().toISOString() };
+            }
             default:
                 return {
                     error: `未知 action: ${args.action}`,
                     errorCode: "UNKNOWN_ACTION",
-                    supportedActions: ["observe", "act", "assert", "api-capture", "assert-api", "run-task"],
+                    supportedActions: ["observe", "act", "assert", "api-capture", "assert-api", "run-task", "test-case"],
                     startTime: startedAt,
                     endTime: new Date().toISOString(),
                 };

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

@@ -547,6 +547,119 @@ cd ~/.szcd-mcp/deps && npm install --registry=https://registry.npmmirror.com --@
 | `setTimeout(awaitPage.bringToFront(), 30000)` 之外不做兜底 | 调用前自查"目标页是否还活着"（`findPage` / `_findFrame`），失败立刻退而求其次操作主帧 | bringToFront 在 OS 抢焦点失败时会无限挂起，没超时 |
 | iframe attach 失败就报错退出 | `attachRetries` 默认 3 次、间隔 1.5s 重抓 `browser.targets()` | wujie 的 blob iframe target 在主页面 ready 后才注册，时序敏感 |
 | 大批量探索每条都 throw | `_actMenuPath` 失败时返回 `acted:false + candidates`，配合 `runTask --continue-on-fail` | 探索性扫描遇到一条点不开就全部中断，没法发现整体面 |
+| 手写 puppeteer 脚本绕过 `act` 操作 Ant Select | 用 `antSelect` 步骤（内置 mousedown + 轮询 + closeAllDropdowns + VERIFY） | Ant Design Select 必须 mousedown 触发，浮层在 body 末尾，选项异步渲染，单步 `act.evaluate` 无法覆盖四步组合 |
+| 每个 Select 后忘记 `closeAllDropdowns` | `act` 自动检测上一次 antSelect/antTreeSelect 并预清理 | 下拉浮层残留会污染下一次 Select 操作，选项串选 |
+| 硬编码 `sleep(15*200)` 等选项渲染 | `antSelect` 内置 `pollEval` 15×200ms 轮询，`expect(poll)` 可自定义条件 | 选项渲染时间受网络/数据量影响，固定 sleep 时机不可靠 |
+| 表单校验用 ad-hoc evaluate 检查 | 用 `expect validation.toPass` 或 `formFill` 的 `validateAfter` | 语义断言自带 poll + 结构化错误信息（field + message），可直接进报告 |
+
+## Ant Design 适配层（6/22 反馈落地）
+
+把"触发器定位 → 浮层等待 → 选项交互 → VERIFY → 全局清理"固化为单步骤 JSON。
+
+| type | 功能 | 关键参数 |
+|------|------|---------|
+| `antSelect` | Ant Select 选项选择 | `field`, `option`, `mode` |
+| `antTreeSelect` | 树形选择 | `field`, `path` |
+| `antInput` | 输入框（支持 `placeholder` 定位） | `field`/`placeholder`, `value` |
+| `antRadio` / `antCheckbox` / `antSwitch` | 选择类 | `field`, `option`/`on` |
+| `antDatePicker` / `antCascader` / `antUpload` | 其他控件 | 见各方法文档 |
+| `formFill` | 批量填充 + 可选 `validateAfter` | `fields[]` |
+| `closeAllDropdowns` | 关闭所有下拉浮层 | - |
+
+**关键约束**：
+- Ant Select 必须 `mousedown` 触发（不是 click）
+- 选项异步渲染，内置 15×200ms 轮询
+- 每次操作前后自动 `closeAllDropdowns`，`act` 入口检测残留并预清理
+- 操作后 VERIFY `.ant-select-selection-item[title]` 回写
+
+```json
+{ "type": "antSelect", "field": "数据集名称", "option": "测试集A" }
+{ "type": "antInput", "placeholder": "挂接资源", "value": "abc" }
+{ "type": "formFill", "fields": [
+    { "label": "名称", "type": "input", "value": "{{name}}" },
+    { "label": "类型", "type": "select", "value": "{{type}}" }
+], "validateAfter": true }
+```
+
+## 用例 DSL（Test Case）
+
+把多个用例统一为参数化 testCase JSON：
+
+```bash
+node local-browser-executor.js --action test-case --test-case-file /tmp/case.json [--dataset-index 0] [--test-report /tmp/report.json]
+```
+
+```json
+{
+    "title": "创建数据集 - P0",
+    "dataset": [{ "name": "A", "type": "图像" }, { "name": "B", "type": "文本" }],
+    "steps": [
+        { "type": "formFill", "fields": [
+            { "label": "名称", "type": "input", "value": "{{name}}" },
+            { "label": "类型", "type": "select", "value": "{{type}}" }
+        ], "validateAfter": true },
+        { "type": "expect", "assertion": "validation.toPass" },
+        { "type": "act", "click": "text=提交" },
+        { "type": "expect", "assertion": "url.toContain", "value": "/list" }
+    ],
+    "recovery": { "maxRetriesPerStep": 2 }
+}
+```
+
+## 语义断言（expect）
+
+| assertion | 功能 |
+|-----------|------|
+| `validation.toPass` | 表单校验无错误 |
+| `validation.toHaveError` | 某字段有错误 |
+| `locator.toBeVisible` / `toHaveText` / `toHaveValue` / `toHaveCount` | 元素状态 |
+| `url.toContain` / `url.toMatch` | URL 断言 |
+| `api.toAllPass` / `api.toInclude` | API 断言 |
+
+所有断言内置 `poll` 轮询（默认 timeout 5s, interval 200ms）。
+
+## 微前端（wujie / qiankun）场景适配
+
+**核心问题与解决：**
+
+| 微前端坑 | 自动修复 |
+|---------|---------|
+| 子应用业务在 frame[1]，每步都要重传 frameContentContains | testCase `setup.findFrame` 设一次，所有步骤默认走 `_activeFrame` |
+| 子应用路由切换销毁 iframe，导致后续 step 都 evaluate 失败 | `_getTargetFrame` 每次执行前探活，失活自动召回（标记 `frameRecovered: true`） |
+| Ant Select 的 `getPopupContainer` 把浮层渲染到父文档 | `antSelect` 触发器/浮层双 frame 协作：trigger 在子 frame mousedown，浮层在父 frame 找选项 |
+| 残留浮层污染下一次操作 | `closeAllDropdowns` 跨 frame 清理（主 + 所有可访问子 frame） |
+| `api.toAllPass` 因主应用埋点 404 误判子应用 P0 测试失败 | `step.scope: "current-frame"` 仅断言 `_activeFrame` 同源的请求 |
+
+**testCase 微前端模板：**
+
+```json
+{
+    "title": "数据集创建 P0",
+    "setup": {
+        "findFrame": { "contentContains": "数据集目录" }
+    },
+    "dataset": [{ "name": "A" }, { "name": "B" }],
+    "steps": [
+        { "type": "apiCapture", "urlPattern": "/api/dataset", "wait": 5000, "includeAllTargets": true },
+        { "type": "antInput", "field": "名称", "value": "{{name}}" },
+        { "type": "antSelect", "field": "类型", "option": "图像" },
+        { "type": "act", "click": "text=提交" },
+        { "type": "expect", "assertion": "validation.toPass" },
+        { "type": "expect", "assertion": "api.toAllPass", "scope": "current-frame" }
+    ]
+}
+```
+
+**关键参数：**
+
+- `setup.findFrame.contentContains` — 一次定位子应用 frame
+- `step.frameContentContains` — 单步覆盖（少用，违反 DRY）
+- `step.scope: "current-frame"` — API 断言仅看 `_activeFrame` 同源请求
+- `apiCapture.includeAllTargets: true` — 跨 page/iframe target 监听网络
+
+**调试技巧：**
+
+每个 ant 步骤结果含 `triggerFrameUrl` / `popupFrameUrl`，可看到触发器和浮层实际在哪个 frame。若 `_dropdownFrame: "main"` 出现，说明该控件用了 `getPopupContainer` 跨 frame 渲染浮层。
 
 ## 非目标声明
 

package/package.json

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