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

package/lib/ant-adapter.js

@@ -0,0 +1,716 @@
+/**
+ * Ant Design 组件适配层
+ *
+ * 设计目标：把"触发器定位 → 浮层等待 → 选项交互 → VERIFY → 全局清理"四步固化，
+ *           解决 6/22 反馈中用户绕开 act 自己手写 pickSelect 的根因。
+ *
+ * 关键约束（来自反馈）：
+ *   - Ant Design Select 必须用 mousedown 触发（click 不工作）
+ *   - 浮层渲染在 document.body 末尾，不在 form-item 子树
+ *   - 选项异步渲染需 15×200ms 轮询
+ *   - 每次操作前后必须 closeAllDropdowns 防串选
+ *   - 通过 .ant-select-selection-item[title] 验证回写
+ *
+ * 与 szcd 私有组件库集成：
+ *   构造函数接收 componentMeta（来自 MCP get_architecture_overview("full")），
+ *   szcd 私有组件可注入自定义 selector 规则。例：szcd 的 Query 组件包了一层 .szc-query
+ *   外壳，通过 meta 自定义匹配规则。
+ */
+
+const POLL_TIMEOUT = 3000;
+const POLL_INTERVAL = 200;
+
+/**
+ * 在 frame 上执行带超时的轮询 evaluate
+ */
+async function pollEval(frame, fn, args, options = {}) {
+    const timeout = options.timeout || POLL_TIMEOUT;
+    const interval = options.interval || POLL_INTERVAL;
+    const start = Date.now();
+    let last;
+    while (Date.now() - start < timeout) {
+        try {
+            last = await frame.evaluate(fn, args);
+            if (last) return { ok: true, value: last, duration: Date.now() - start };
+        } catch (err) {
+            last = { error: err.message };
+        }
+        await new Promise((r) => setTimeout(r, interval));
+    }
+    return { ok: false, value: last, duration: Date.now() - start, timedOut: true };
+}
+
+export class AntAdapter {
+    /**
+     * @param {object} options - { componentMeta }
+     *   componentMeta - 可选，来自 szcd MCP 的组件元信息，用于私有组件 selector 覆盖
+     */
+    constructor(options = {}) {
+        this.componentMeta = options.componentMeta || {};
+    }
+
+    /**
+     * 关闭所有打开的下拉浮层 / 抽屉 / 弹窗
+     * 反馈第 2 条：每次 Select 操作后必须调用，否则下次操作会命中残留选项
+     */
+    async closeAllDropdowns(frame) {
+        return frame.evaluate(() => {
+            // 1) 移除 ant-select-open 状态 + 触发 ESC
+            document.querySelectorAll(".ant-select-open").forEach((el) => {
+                el.classList.remove("ant-select-open");
+            });
+            // 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)"
+            );
+            const count = dropdowns.length;
+            dropdowns.forEach((el) => {
+                el.classList.add("ant-select-dropdown-hidden");
+                el.classList.add("ant-cascader-dropdown-hidden");
+                el.classList.add("ant-picker-dropdown-hidden");
+            });
+            // 3) 派发 ESC keydown 让 antd 自己处理
+            document.body.dispatchEvent(new KeyboardEvent("keydown", {
+                key: "Escape", code: "Escape", keyCode: 27, which: 27, bubbles: true,
+            }));
+            return { closed: count };
+        }).catch(() => ({ closed: 0 }));
+    }
+
+    /**
+     * 定位包含指定 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);
+            });
+            if (!item) return { found: false };
+
+            // 找控件：根据 hint 决定优先匹配何种节点
+            let control;
+            if (hint === "select") {
+                control = item.querySelector(".ant-select:not(.ant-select-disabled)");
+            } else if (hint === "treeSelect") {
+                control = item.querySelector(".ant-select.ant-tree-select, .ant-tree-select");
+            } else if (hint === "cascader") {
+                control = item.querySelector(".ant-cascader, .ant-cascader-picker");
+            } else if (hint === "datePicker") {
+                control = item.querySelector(".ant-picker");
+            } else if (hint === "input") {
+                control = item.querySelector("input.ant-input, textarea.ant-input, .ant-input-affix-wrapper input");
+            } else if (hint === "radio") {
+                control = item.querySelector(".ant-radio-group");
+            } else if (hint === "checkbox") {
+                control = item.querySelector(".ant-checkbox-group, .ant-checkbox-wrapper");
+            } else if (hint === "switch") {
+                control = item.querySelector(".ant-switch");
+            } else if (hint === "upload") {
+                control = item.querySelector(".ant-upload input[type='file'], input[type='file']");
+            } else {
+                control = item.querySelector("input, .ant-select, .ant-picker, .ant-cascader");
+            }
+
+            if (!control) return { found: true, hasControl: false };
+
+            // 用临时 data 属性标记，避免重复 traversal
+            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();
+            return {
+                found: true,
+                hasControl: true,
+                marker,
+                tagName: control.tagName,
+                visible: rect.width > 0 && rect.height > 0,
+            };
+        }, { label: labelText, hint: controlHint });
+    }
+
+    async _clearMarkers(frame) {
+        return frame.evaluate(() => {
+            document.querySelectorAll("[data-sz-marker]").forEach((el) => el.removeAttribute("data-sz-marker"));
+            document.querySelectorAll("[data-sz-form-item-marker]").forEach((el) => el.removeAttribute("data-sz-form-item-marker"));
+        }).catch(() => {});
+    }
+
+    /**
+     * Ant Select 操作
+     * @param {Frame} frame
+     * @param {string} fieldLabel - 表单字段 label 文本
+     * @param {string|string[]} option - 要选择的选项文本（多选模式可传数组）
+     * @param {object} opts - { mode, timeout, allowCreate, popupFrame }
+     *   popupFrame - 可选，浮层渲染所在的 frame（用于微前端 getPopupContainer 跨 frame 场景）
+     */
+    async select(frame, fieldLabel, option, opts = {}) {
+        const options = Array.isArray(option) ? option : [option];
+        const mode = opts.mode || "single";
+        const timeout = opts.timeout || POLL_TIMEOUT;
+        // 微前端：浮层可能渲染到父文档（通过 getPopupContainer({ getContainer: () => parent.document.body })）
+        const popupFrame = opts.popupFrame || frame;
+
+        // 0) 预清理：同时清理触发器 frame 和浮层 frame
+        await this.closeAllDropdowns(frame);
+        if (popupFrame !== frame) await this.closeAllDropdowns(popupFrame);
+
+        // 1) 定位 form-item 的 .ant-select 控件（在 trigger frame）
+        const mark = await this._markFormItemControl(frame, fieldLabel, "select");
+        if (!mark.found) {
+            await this._clearMarkers(frame);
+            return { acted: false, reason: `form item with label "${fieldLabel}" not found` };
+        }
+        if (!mark.hasControl) {
+            await this._clearMarkers(frame);
+            return { acted: false, reason: `no .ant-select control inside form item "${fieldLabel}"` };
+        }
+
+        // 2) 触发器 mousedown 打开下拉
+        const triggerOk = await frame.evaluate(({ marker }) => {
+            const el = document.querySelector(`[data-sz-marker="${marker}"]`);
+            if (!el) return false;
+            el.scrollIntoView({ block: "center" });
+            const selector = el.querySelector(".ant-select-selector") || el;
+            // Ant Select 必须 mousedown，click 不工作（反馈第 1 条）
+            selector.dispatchEvent(new MouseEvent("mousedown", { bubbles: true, cancelable: true, button: 0 }));
+            selector.dispatchEvent(new MouseEvent("mouseup", { bubbles: true, cancelable: true, button: 0 }));
+            return true;
+        }, { marker: mark.marker });
+
+        if (!triggerOk) {
+            await this._clearMarkers(frame);
+            return { acted: false, reason: "trigger element disappeared after marking" };
+        }
+
+        const selectedSummary = [];
+        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"
+                ));
+                const visibleItems = items.filter((el) => {
+                    const rect = el.getBoundingClientRect();
+                    return rect.width > 0 && rect.height > 0;
+                });
+                if (visibleItems.length === 0) return null;
+                const matched = visibleItems.find((el) =>
+                    (el.innerText || el.textContent || "").trim() === text
+                ) || visibleItems.find((el) =>
+                    (el.innerText || el.textContent || "").trim().includes(text)
+                );
+                if (!matched) return { renderedButNoMatch: true, options: visibleItems.slice(0, 10).map((el) => (el.innerText || "").trim()) };
+                const tag = `__sz_opt_${Date.now()}`;
+                matched.setAttribute("data-sz-option-marker", tag);
+                return { tag, text: (matched.innerText || "").trim() };
+            }, opt, { timeout: opts.popupFrame ? timeout : Math.min(1500, timeout) });
+
+            // 微前端跨 frame 兜底：触发器 frame 没找到浮层 → 尝试父 frame
+            if ((!optionFound.ok || !optionFound.value?.tag) && popupResolved === frame) {
+                // frame.parentFrame() 是 puppeteer 标准 API
+                let parentFrame = null;
+                try { parentFrame = frame.parentFrame(); } catch {}
+                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"
+                        ));
+                        const visibleItems = items.filter((el) => {
+                            const rect = el.getBoundingClientRect();
+                            return rect.width > 0 && rect.height > 0;
+                        });
+                        if (visibleItems.length === 0) return null;
+                        const matched = visibleItems.find((el) =>
+                            (el.innerText || el.textContent || "").trim() === text
+                        ) || visibleItems.find((el) =>
+                            (el.innerText || el.textContent || "").trim().includes(text)
+                        );
+                        if (!matched) return null;
+                        const tag = `__sz_opt_${Date.now()}`;
+                        matched.setAttribute("data-sz-option-marker", tag);
+                        return { tag, text: (matched.innerText || "").trim() };
+                    }, opt, { timeout: 1500 });
+                    if (retryFound.ok && retryFound.value?.tag) {
+                        optionFound = retryFound;
+                        popupResolved = parentFrame;
+                    }
+                }
+            }
+
+            if (!optionFound.ok || !optionFound.value?.tag) {
+                await this.closeAllDropdowns(frame);
+                if (popupResolved !== frame) await this.closeAllDropdowns(popupResolved);
+                await this._clearMarkers(frame);
+                return {
+                    acted: false,
+                    reason: `option "${opt}" not found in dropdown`,
+                    availableOptions: optionFound.value?.options || [],
+                    triggerFrameUrl: frame.url(),
+                    searchedFrames: [frame.url(), popupResolved.url()].filter((u, i, a) => a.indexOf(u) === i),
+                };
+            }
+
+            // 4) mousedown 选项（在 popupResolved frame 内）
+            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.removeAttribute("data-sz-option-marker");
+                return true;
+            }, optionFound.value.tag);
+
+            selectedSummary.push(opt);
+
+            if (mode === "single") break;
+        }
+
+        // 5) 关闭浮层（双 frame 清理）
+        await this.closeAllDropdowns(frame);
+        if (popupResolved !== frame) await this.closeAllDropdowns(popupResolved);
+
+        // 6) VERIFY：在 trigger frame 检查 selection-item
+        const verify = await pollEval(frame, ({ marker, expected, mode }) => {
+            const el = document.querySelector(`[data-sz-marker="${marker}"]`);
+            if (!el) return null;
+            const items = Array.from(el.querySelectorAll(".ant-select-selection-item"));
+            if (items.length === 0) return null;
+            const texts = items.map((i) => (i.getAttribute("title") || i.innerText || "").trim()).filter(Boolean);
+            if (mode === "single") {
+                return texts[0] && expected.some((e) => texts[0].includes(e)) ? texts : null;
+            }
+            const allFound = expected.every((e) => texts.some((t) => t.includes(e)));
+            return allFound ? texts : null;
+        }, { marker: mark.marker, expected: options, mode }, { timeout: 1500 });
+
+        await this._clearMarkers(frame);
+
+        return {
+            acted: true,
+            field: fieldLabel,
+            selected: selectedSummary,
+            verified: verify.ok,
+            currentValue: verify.value,
+            triggerFrameUrl: frame.url(),
+            popupFrameUrl: typeof popupResolved.url === "function" ? popupResolved.url() : null,
+            reason: verify.ok ? null : "selection-item did not reflect chosen option",
+        };
+    }
+
+    /**
+     * Ant TreeSelect 操作
+     * @param {Frame} frame
+     * @param {string} fieldLabel
+     * @param {string|string[]} path - 树节点路径（按顺序展开），传字符串则只选叶子
+     */
+    async treeSelect(frame, fieldLabel, path, opts = {}) {
+        const segments = Array.isArray(path) ? path : [path];
+        const timeout = opts.timeout || POLL_TIMEOUT;
+
+        await this.closeAllDropdowns(frame);
+        const mark = await this._markFormItemControl(frame, fieldLabel, "treeSelect");
+        if (!mark.found || !mark.hasControl) {
+            await this._clearMarkers(frame);
+            return { acted: false, reason: !mark.found ? `field "${fieldLabel}" not found` : "no tree-select control" };
+        }
+
+        // 触发下拉
+        await frame.evaluate(({ marker }) => {
+            const el = document.querySelector(`[data-sz-marker="${marker}"]`);
+            if (!el) return;
+            el.scrollIntoView({ block: "center" });
+            const selector = el.querySelector(".ant-select-selector") || el;
+            selector.dispatchEvent(new MouseEvent("mousedown", { bubbles: true, cancelable: true, button: 0 }));
+            selector.dispatchEvent(new MouseEvent("mouseup", { bubbles: true, cancelable: true, button: 0 }));
+        }, { marker: mark.marker });
+
+        // 逐级展开 + 最后一级点击
+        for (let i = 0; i < segments.length; i++) {
+            const seg = segments[i];
+            const isLeaf = i === segments.length - 1;
+
+            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"
+                ));
+                const visible = titles.filter((el) => {
+                    const rect = el.getBoundingClientRect();
+                    return rect.width > 0 && rect.height > 0;
+                });
+                if (visible.length === 0) return null;
+                const matched = visible.find((el) => (el.innerText || "").trim() === text)
+                    || visible.find((el) => (el.innerText || "").trim().includes(text));
+                if (!matched) return { rendered: true, options: visible.slice(0, 10).map((el) => (el.innerText || "").trim()) };
+
+                // 找到节点 → 找其 switcher 来展开（非叶子），或直接点击（叶子）
+                const treeNode = matched.closest(".ant-select-tree-treenode");
+                if (!treeNode) return null;
+
+                if (isLeaf) {
+                    matched.dispatchEvent(new MouseEvent("mousedown", { bubbles: true, cancelable: true, button: 0 }));
+                    matched.dispatchEvent(new MouseEvent("mouseup", { bubbles: true, cancelable: true, button: 0 }));
+                    matched.click();
+                    return { acted: "click", text: (matched.innerText || "").trim() };
+                }
+                const switcher = treeNode.querySelector(".ant-select-tree-switcher");
+                if (switcher && !switcher.classList.contains("ant-select-tree-switcher_open")) {
+                    switcher.click();
+                }
+                return { acted: "expand", text };
+            }, { text: seg, isLeaf }, { timeout });
+
+            if (!found.ok) {
+                await this.closeAllDropdowns(frame);
+                await this._clearMarkers(frame);
+                return {
+                    acted: false,
+                    reason: `tree node "${seg}" not found at level ${i + 1}/${segments.length}`,
+                    availableNodes: found.value?.options || [],
+                };
+            }
+        }
+
+        await this.closeAllDropdowns(frame);
+
+        const verify = await pollEval(frame, ({ marker, leaf }) => {
+            const el = document.querySelector(`[data-sz-marker="${marker}"]`);
+            if (!el) return null;
+            const items = Array.from(el.querySelectorAll(".ant-select-selection-item"));
+            if (items.length === 0) return null;
+            const text = items.map((i) => (i.getAttribute("title") || i.innerText || "").trim()).join(" ");
+            return text.includes(leaf) ? text : null;
+        }, { marker: mark.marker, leaf: segments[segments.length - 1] }, { timeout: 1500 });
+
+        await this._clearMarkers(frame);
+        return {
+            acted: true,
+            field: fieldLabel,
+            path: segments,
+            verified: verify.ok,
+            currentValue: verify.value,
+        };
+    }
+
+    /**
+     * Ant Input / TextArea 文本输入
+     * @param {Frame} frame
+     * @param {object} target - { label }（按字段 label）或 { placeholder } 或 { selector }
+     * @param {string} value
+     * @param {object} opts - { clear: true, delay: 0 }
+     */
+    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; }
+            }
+
+            if (!el) return { found: false };
+            el.scrollIntoView({ block: "center" });
+            const proto = Object.getPrototypeOf(el);
+            const valueSetter = Object.getOwnPropertyDescriptor(proto, "value")?.set;
+
+            el.focus();
+            const newValue = clear ? value : (el.value || "") + value;
+            if (valueSetter) {
+                valueSetter.call(el, newValue);
+            } else {
+                el.value = newValue;
+            }
+            el.dispatchEvent(new Event("input", { bubbles: true }));
+            el.dispatchEvent(new Event("change", { bubbles: true }));
+            return {
+                found: true,
+                actualValue: el.value,
+                placeholder: el.getAttribute("placeholder"),
+                tagName: el.tagName,
+            };
+        }, { target, value, clear });
+
+        return {
+            acted: result.found,
+            target,
+            value,
+            actualValue: result.actualValue,
+            verified: result.actualValue === value,
+            reason: result.found ? null : `input not found by ${JSON.stringify(target)}`,
+        };
+    }
+
+    /**
+     * 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);
+            });
+            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()) };
+
+            target.scrollIntoView({ block: "center" });
+            target.click();
+            const input = target.querySelector("input[type='radio']");
+            return {
+                found: true,
+                checked: input?.checked || false,
+                value: input?.value || "",
+            };
+        }, { field: fieldLabel, opt: optionLabel });
+        return {
+            acted: result.found,
+            field: fieldLabel,
+            option: optionLabel,
+            verified: result.checked,
+            availableOptions: result.available,
+            reason: result.reason,
+        };
+    }
+
+    /**
+     * 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);
+            });
+            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];
+            if (!wrapper) return { found: false, reason: "checkbox not found" };
+            const input = wrapper.querySelector("input[type='checkbox']");
+            if (!input) return { found: false };
+            if (input.checked !== target) 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 };
+    }
+
+    /**
+     * 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);
+            });
+            if (!item) return { found: false };
+            const 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 });
+        return { acted: result.found, field: fieldLabel, state: result.state, verified: result.state === on };
+    }
+
+    /**
+     * Ant DatePicker 设值（通过 input + 回车确认）
+     */
+    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);
+            });
+            if (!item) return { found: false };
+            const picker = item.querySelector(".ant-picker");
+            const input = 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;
+            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 };
+    }
+
+    /**
+     * Cascader 选择
+     */
+    async cascader(frame, fieldLabel, path, opts = {}) {
+        const segments = Array.isArray(path) ? path : [path];
+        const timeout = opts.timeout || POLL_TIMEOUT;
+        await this.closeAllDropdowns(frame);
+
+        const mark = await this._markFormItemControl(frame, fieldLabel, "cascader");
+        if (!mark.found || !mark.hasControl) {
+            await this._clearMarkers(frame);
+            return { acted: false, reason: "cascader not found" };
+        }
+
+        await frame.evaluate(({ marker }) => {
+            const el = document.querySelector(`[data-sz-marker="${marker}"]`);
+            const trigger = el?.querySelector(".ant-cascader-picker, .ant-select-selector, input") || el;
+            if (trigger) {
+                trigger.dispatchEvent(new MouseEvent("mousedown", { bubbles: true, button: 0 }));
+                trigger.dispatchEvent(new MouseEvent("mouseup", { bubbles: true, button: 0 }));
+                trigger.click?.();
+            }
+        }, { marker: mark.marker });
+
+        for (let i = 0; i < segments.length; i++) {
+            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"
+                ));
+                const visible = all.filter((el) => {
+                    const r = el.getBoundingClientRect();
+                    return r.width > 0 && r.height > 0;
+                });
+                if (visible.length === 0) return null;
+                const matched = visible.find((el) => (el.innerText || "").trim() === text)
+                    || visible.find((el) => (el.innerText || "").trim().includes(text));
+                if (!matched) return { options: visible.map((el) => (el.innerText || "").trim()) };
+                matched.click();
+                return { clicked: text };
+            }, seg, { timeout });
+            if (!result.ok || !result.value?.clicked) {
+                await this.closeAllDropdowns(frame);
+                await this._clearMarkers(frame);
+                return { acted: false, reason: `cascader level "${seg}" not found`, available: result.value?.options };
+            }
+        }
+
+        await this.closeAllDropdowns(frame);
+        await this._clearMarkers(frame);
+        return { acted: true, field: fieldLabel, path: segments };
+    }
+
+    /**
+     * 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);
+            });
+            if (!item) return { found: false };
+            const input = item.querySelector("input[type='file']");
+            if (!input) return { found: false };
+            const marker = `__sz_upload_${Date.now()}`;
+            input.setAttribute("data-sz-marker", marker);
+            return { found: true, marker };
+        }, fieldLabel);
+
+        if (!result.found) return { acted: false, reason: "upload input not found" };
+
+        try {
+            const handles = await frame.$$(`input[data-sz-marker="${result.marker}"]`);
+            if (handles.length === 0) return { acted: false, reason: "upload input handle lost" };
+            await handles[0].uploadFile(filePath);
+            await this._clearMarkers(frame);
+            return { acted: true, field: fieldLabel, filePath };
+        } catch (err) {
+            await this._clearMarkers(frame);
+            return { acted: false, reason: `upload failed: ${err.message}` };
+        }
+    }
+
+    /**
+     * 高层 API：按字段定义批量填充表单
+     * fields: [{ label, type: "input"|"select"|"treeSelect"|"radio"|"checkbox"|"switch"|"datePicker"|"cascader"|"upload",
+     *            value, path, matchBy: "label"|"placeholder" }]
+     */
+    async formFill(frame, fields, opts = {}) {
+        const stepDelay = opts.stepDelay ?? 200;
+        const results = [];
+        for (const f of fields) {
+            let r;
+            switch (f.type) {
+                case "input":
+                    r = await this.input(frame,
+                        f.matchBy === "placeholder" ? { placeholder: f.label } : { label: f.label },
+                        f.value, { clear: f.clear !== false });
+                    break;
+                case "select":
+                    r = await this.select(frame, f.label, f.value, { mode: f.mode });
+                    break;
+                case "treeSelect":
+                    r = await this.treeSelect(frame, f.label, f.path || f.value);
+                    break;
+                case "radio":
+                    r = await this.radio(frame, f.label, f.value);
+                    break;
+                case "checkbox":
+                    r = await this.checkbox(frame, f.label, f.value, f.checked !== false);
+                    break;
+                case "switch":
+                    r = await this.switch(frame, f.label, f.on !== false);
+                    break;
+                case "datePicker":
+                    r = await this.datePicker(frame, f.label, f.value);
+                    break;
+                case "cascader":
+                    r = await this.cascader(frame, f.label, f.path || f.value);
+                    break;
+                case "upload":
+                    r = await this.upload(frame, f.label, f.value);
+                    break;
+                default:
+                    r = { acted: false, reason: `unknown field type: ${f.type}` };
+            }
+            results.push({ field: f.label, type: f.type, ...r });
+            if (stepDelay > 0) await new Promise((res) => setTimeout(res, stepDelay));
+        }
+        return {
+            fields: results,
+            summary: {
+                total: results.length,
+                acted: results.filter((r) => r.acted).length,
+                verified: results.filter((r) => r.verified).length,
+                failed: results.filter((r) => !r.acted).length,
+            },
+        };
+    }
+}
+
+export default AntAdapter;