browser-opt 1.0.23 → 1.0.25

package/dist/browser-opt/runner/actions/utils/select-option-action.js

@@ -1,8 +1,22 @@
 import { findSelectableFieldRef, findSelectableOption, } from '../../../utils.js';
 import { captureTransientSnapshot } from '../../evidence.js';
+import { selectFieldScopedDomTarget, verifyFieldScopedDomSelection } from './dom-action.js';
 import { executeDateSelectOptionAction, resolveDateSelectOption, verifyDateSelectOptionActionEffect, } from './date-action.js';
-/** 执行选项选择动作，包含 switch、原生单选复选框和长表单滚动搜索兜底。 */
+/** 选择前按需滚动目标，包含 switch、原生单选复选框和长表单滚动搜索兜底。 */
 export function executeSelectOptionAction(agent, action, snapshot, options) {
+    if (action.rowNumber && action.field) {
+        const scoped = selectFieldScopedDomTarget(agent, action.field, action.option, action.rowNumber, action.mode);
+        if (scoped?.output) {
+            return scoped.output;
+        }
+        if (scoped?.dropdownOpened) {
+            const dropdown = clickDropdownDomTarget(agent, action.field, action.option, true);
+            if (dropdown.output) {
+                return dropdown.output;
+            }
+        }
+        throw new Error(`无法找到选项：第 ${action.rowNumber} 行 ${action.field} -> ${action.option}`);
+    }
     const normalizedDate = resolveDateSelectOption(action);
     if (normalizedDate) {
         return executeDateSelectOptionAction(agent, action, snapshot, normalizedDate);
@@ -10,26 +24,34 @@ export function executeSelectOptionAction(agent, action, snapshot, options) {
     let option = findSelectableOption(snapshot, action.field, action.option);
     let searchSnapshot = snapshot;
     const fieldLabel = action.field ?? '选项';
-    if (option.alreadySelected) {
-        if (!isSwitchSelectable(option.role)) {
-            return `selection skipped: ${fieldLabel} 已是 ${action.option}`;
-        }
+    if (option.alreadySelected && isSwitchSelectable(option.role)) {
         const domState = action.field ? verifySwitchDomState(agent, action.field, action.option) : null;
         if (domState === true) {
             return `selection skipped: ${fieldLabel} 已是 ${action.option}`;
         }
         option = { ...option, alreadySelected: false };
     }
-    const switchDomTarget = action.field && (isSwitchSelectable(option.role) || snapshotHasSwitchField(snapshot, action.field))
-        ? clickSwitchDomTarget(agent, action.field, action.option)
+    const switchField = action.field;
+    const switchDomTarget = switchField && shouldUseSwitchDomFallback(snapshot, action, option.role)
+        ? clickSwitchDomTarget(agent, switchField, action.option)
         : null;
     if (switchDomTarget) {
         return switchDomTarget;
     }
-    const nativeSelectableDomTarget = clickNativeSelectableDomTarget(agent, option.role, action.option);
+    const hasExpandableField = Boolean(findSelectableFieldRef(searchSnapshot, action.field));
+    const shouldSearchNativeDom = /radio|checkbox/i.test(option.role ?? '') || !hasExpandableField;
+    const nativeSelectableDomTarget = shouldSearchNativeDom
+        ? clickNativeSelectableDomTarget(agent, action)
+        : null;
     if (nativeSelectableDomTarget) {
         return nativeSelectableDomTarget;
     }
+    if (option.alreadySelected && action.mode !== 'deselect') {
+        return `selection skipped: ${fieldLabel} 已是 ${action.option}`;
+    }
+    if (!option.alreadySelected && action.mode === 'deselect' && option.ref) {
+        return `selection skipped: ${fieldLabel} 已取消 ${action.option}`;
+    }
     const searchOutput = [];
     const dropdownDomTarget = action.field ? clickDropdownDomTarget(agent, action.field, action.option) : { attempted: false, output: null };
     if (dropdownDomTarget.output) {
@@ -38,6 +60,7 @@ export function executeSelectOptionAction(agent, action, snapshot, options) {
     if (!option.ref) {
         const fieldRef = findSelectableFieldRef(searchSnapshot, action.field);
         if (fieldRef) {
+            agent.scrollIntoView(fieldRef);
             searchOutput.push(`open select @${fieldRef}\n${agent.click(fieldRef)}`.trim());
             agent.waitMs(300);
             const openedSnapshot = captureTransientSnapshot(agent);
@@ -52,9 +75,16 @@ export function executeSelectOptionAction(agent, action, snapshot, options) {
             searchOutput.push(...scrolled.logs);
         }
     }
+    if (/radio|checkbox/i.test(option.role ?? '')) {
+        const revealedNativeTarget = clickNativeSelectableDomTarget(agent, action);
+        if (revealedNativeTarget) {
+            return [...searchOutput, revealedNativeTarget].filter(Boolean).join('\n').trim();
+        }
+    }
     if (!option.ref) {
         const fieldRef = findSelectableFieldRef(searchSnapshot, action.field);
         if (fieldRef) {
+            agent.scrollIntoView(fieldRef);
             searchOutput.push(`open select @${fieldRef}\n${agent.click(fieldRef)}`.trim());
             agent.waitMs(300);
             const openedSnapshot = captureTransientSnapshot(agent);
@@ -64,6 +94,10 @@ export function executeSelectOptionAction(agent, action, snapshot, options) {
     if (!option.ref) {
         throw new Error(`无法找到选项：${fieldLabel} -> ${action.option}`);
     }
+    if (action.mode === 'exclusive' && /checkbox/i.test(option.role ?? '')) {
+        throw new Error(`无法可靠执行“仅勾选”：未能在 DOM 中确认 ${fieldLabel} 的复选框分组`);
+    }
+    agent.scrollIntoView(option.ref);
     const output = agent.click(option.ref);
     const dropdownCleanup = isDropdownOption(option.role) ? dismissActiveDropdown(agent) : null;
     return [
@@ -75,20 +109,37 @@ export function executeSelectOptionAction(agent, action, snapshot, options) {
 }
 /** 对选择动作做后置状态确认，防止命令发出但页面没有完成目标状态时误报成功。 */
 export function verifySelectOptionActionEffect(agent, action, afterSnapshot) {
+    if (action.rowNumber && action.field) {
+        const reached = verifyFieldScopedDomSelection(agent, action.field, action.option, action.rowNumber, action.mode);
+        const target = `第 ${action.rowNumber} 行${action.field}=${action.option}`;
+        return reached === true
+            ? { passed: true, message: `已通过 DOM 确认选择状态：${target}` }
+            : { passed: false, message: `DOM 未确认目标行选择状态：${target}` };
+    }
     const normalizedDate = resolveDateSelectOption(action);
     if (normalizedDate) {
         return verifyDateSelectOptionActionEffect(agent, action, afterSnapshot, normalizedDate);
     }
     const selected = findSelectableOption(afterSnapshot, action.field, action.option);
-    if ((isSwitchSelectable(selected.role) || snapshotHasSwitchField(afterSnapshot, action.field)) && action.field) {
-        const domState = verifySwitchDomState(agent, action.field, action.option);
+    const switchField = action.field;
+    if (switchField && shouldUseSwitchDomFallback(afterSnapshot, action, selected.role)) {
+        const domState = verifySwitchDomState(agent, switchField, action.option);
         if (domState === true) {
-            return { passed: true, message: `已确认开关状态：${action.field}=${action.option}` };
+            return { passed: true, message: `已确认开关状态：${switchField}=${action.option}` };
         }
         if (domState === false) {
-            return { passed: false, message: `DOM 确认开关未达到目标状态：${action.field}=${action.option}` };
+            return { passed: false, message: `DOM 确认开关未达到目标状态：${switchField}=${action.option}` };
+        }
+    }
+    if (/radio|checkbox/i.test(selected.role ?? '') || action.mode === 'deselect' || action.mode === 'exclusive') {
+        const domState = verifyNativeSelectableDomState(agent, action);
+        if (domState === true) {
+            const intent = action.mode === 'exclusive' ? '仅勾选' : action.mode === 'deselect' ? '取消勾选' : '勾选';
+            return { passed: true, message: `已通过 DOM 确认${intent}状态：${action.field ?? '选项'}=${action.option}` };
+        }
+        if (domState === false || action.mode === 'deselect' || action.mode === 'exclusive') {
+            return { passed: false, message: `DOM 确认复选状态未达到目标：${action.field ?? '选项'}=${action.option}` };
         }
-        return { passed: false, message: `无法可靠确认开关状态：${action.field}=${action.option}` };
     }
     if (selected.alreadySelected) {
         return { passed: true, message: `已确认选择状态：${action.field ?? '选项'}=${action.option}` };
@@ -99,55 +150,231 @@ export function verifySelectOptionActionEffect(agent, action, afterSnapshot) {
     if (isOrdinalOptionIntent(action.option) && action.field && isFieldSelectedValueVisible(afterSnapshot.text, action.field)) {
         return { passed: true, message: `已确认按位置选择：${action.field}=${action.option}` };
     }
+    if (action.field && verifyDropdownDomState(agent, action.field, action.option) === true) {
+        return { passed: true, message: `已通过 DOM 确认选择状态：${action.field}=${action.option}` };
+    }
     return { passed: false, message: `动作后未确认目标已选中：${action.field ?? '选项'}=${action.option}` };
 }
-/** radio/checkbox 的无障碍 ref 可能指向隐藏 input，文案唯一时改点真实 label 以触发组件事件。 */
-function clickNativeSelectableDomTarget(agent, role, option) {
-    if (!/radio|checkbox/i.test(role ?? '')) {
-        return null;
-    }
+/**
+ * radio/checkbox 可能位于当前交互快照之外，直接从完整 DOM 按字段和选项定位真实 label。
+ * 定位成功后先滚入视口再点击，既覆盖长表单，也避免无障碍 ref 指向隐藏 input。
+ */
+function clickNativeSelectableDomTarget(agent, action) {
+    const field = action.field;
+    const option = action.option;
+    const mode = action.mode ?? 'select';
     const script = `(() => {
   const normalize = (value) => (value || '').replace(/\\s+/g, '').trim();
+  const isVisible = (element) => {
+    const style = window.getComputedStyle(element);
+    const rect = element.getBoundingClientRect();
+    return style.visibility !== 'hidden' && style.display !== 'none' && rect.width > 0 && rect.height > 0;
+  };
   const target = normalize(${JSON.stringify(option)});
-  const labels = [...document.querySelectorAll('label')].filter((label) => normalize(label.textContent) === target);
-  if (labels.length !== 1) {
-    return JSON.stringify({ matchedCount: labels.length, clicked: false });
+  const field = normalize(${JSON.stringify(field)});
+  const mode = ${JSON.stringify(mode)};
+  const candidates = [...document.querySelectorAll('label')]
+    .map((label) => ({
+      label,
+      input: label.querySelector('input[type="radio"], input[type="checkbox"]'),
+    }))
+    .filter(({ label, input }) => input && isVisible(label) && normalize(label.textContent) === target);
+  if (candidates.length === 0) {
+    return JSON.stringify({ matchedCount: 0, clicked: false });
+  }
+
+  const fieldNodes = field
+    ? [...document.querySelectorAll('label, [class*="label"], [class*="form-item"], [class*="formItem"], dt, th')]
+      .filter((element) => isVisible(element) && normalize(element.textContent).includes(field))
+    : [];
+  const distance = (left, right) => {
+    const a = left.getBoundingClientRect();
+    const b = right.getBoundingClientRect();
+    return Math.abs((a.left + a.right - b.left - b.right) / 2)
+      + Math.abs((a.top + a.bottom - b.top - b.bottom) / 2);
+  };
+  const scoped = candidates
+    .map((candidate) => ({
+      ...candidate,
+      fieldDistance: fieldNodes.length > 0
+        ? Math.min(...fieldNodes.map((fieldNode) => distance(fieldNode, candidate.label)))
+        : 0,
+    }))
+    .sort((a, b) => a.fieldDistance - b.fieldDistance);
+  if (scoped.length > 1 && (!field || scoped[0].fieldDistance === scoped[1].fieldDistance)) {
+    return JSON.stringify({ matchedCount: scoped.length, clicked: false, ambiguous: true });
   }
-  const input = labels[0].querySelector('input[type="radio"], input[type="checkbox"]');
+
+  const { label, input } = scoped[0];
   if (!input || input.disabled) {
-    return JSON.stringify({ matchedCount: 1, clicked: false, disabled: Boolean(input?.disabled) });
+    return JSON.stringify({ matchedCount: scoped.length, clicked: false, disabled: Boolean(input?.disabled) });
   }
-  labels[0].click();
-  return JSON.stringify({ matchedCount: 1, clicked: true, checked: input.checked });
+  label.scrollIntoView({ block: 'center', inline: 'nearest' });
+  const group = (() => {
+    let current = label.parentElement;
+    for (let depth = 0; current && depth < 8; depth += 1, current = current.parentElement) {
+      const checkboxes = [...current.querySelectorAll('input[type="checkbox"]')].filter((item) => !item.disabled);
+      if (checkboxes.includes(input) && checkboxes.length > 1 && (!field || normalize(current.textContent).includes(field))) {
+        return checkboxes;
+      }
+    }
+    return [input];
+  })();
+  const clickInputLabel = (targetInput) => {
+    const targetLabel = targetInput.closest('label') || document.querySelector('label[for="' + CSS.escape(targetInput.id) + '"]');
+    (targetLabel || targetInput).click();
+  };
+  let clickCount = 0;
+  if (mode === 'exclusive') {
+    if (input.type !== 'checkbox' || group.length < 2) {
+      return JSON.stringify({ matchedCount: scoped.length, clicked: false, groupFound: false });
+    }
+    for (const sibling of group) {
+      if (sibling !== input && sibling.checked) {
+        clickInputLabel(sibling);
+        clickCount += 1;
+      }
+    }
+  }
+  const desiredChecked = mode !== 'deselect';
+  if (input.checked !== desiredChecked) {
+    clickInputLabel(input);
+    clickCount += 1;
+  }
+  const otherSelectedCount = group.filter((item) => item !== input && item.checked).length;
+  const reached = input.checked === desiredChecked && (mode !== 'exclusive' || otherSelectedCount === 0);
+  return JSON.stringify({
+    matchedCount: scoped.length,
+    clicked: clickCount > 0,
+    checked: input.checked,
+    alreadySelected: clickCount === 0 && reached,
+    groupFound: group.length > 1,
+    otherSelectedCount,
+    reached,
+  });
 })()`;
     try {
         const parsed = parseEvalJson(agent.evaluate(script));
-        return parsed.matchedCount === 1 && parsed.clicked === true
-            ? `selectable dom click ${option}`
-            : null;
+        const reached = parsed.reached ?? (mode === 'select' && parsed.checked === true);
+        if (reached !== true) {
+            return null;
+        }
+        // 页面异步水合期间，复选框可能会先短暂显示为未选中，再恢复到真实已选状态。
+        // 已达到目标时仍等待一次重渲染并复查(parseEvalJson)，避免把水合瞬间的未选中误判为需要继续点击。
+        if (parsed.alreadySelected === true) {
+            agent.waitMs(300);
+            revealNativeSelectableDomTarget(agent, field, option);
+            agent.waitMs(200);
+            const settled = parseEvalJson(agent.evaluate(script));
+            if (settled.clicked === true && settled.reached === true) {
+                agent.waitMs(300);
+                revealNativeSelectableDomTarget(agent, field, option);
+                agent.waitMs(200);
+                return `selectable dom ${mode} ${field ?? '选项'}=${option}`;
+            }
+            if (settled.alreadySelected !== true || settled.reached !== true) {
+                return null;
+            }
+            return `selectable dom revealed: ${field ?? '选项'} 已达到 ${option}`;
+        }
+        if (parsed.clicked === true) {
+            agent.waitMs(300);
+            revealNativeSelectableDomTarget(agent, field, option);
+            agent.waitMs(200);
+            return `selectable dom ${mode} ${field ?? '选项'}=${option}`;
+        }
+        return null;
     }
     catch {
         return null;
     }
 }
-/** 普通下拉优先按 DOM 中字段同组控件和可见弹层选项点击，避开嵌套布局里的 ref 坐标漂移。 */
-function clickDropdownDomTarget(agent, field, option) {
-    const openScript = `(() => {
-  const selectHelper = ${dropdownDomHelperSource()};
-  return JSON.stringify(selectHelper.openDropdownByField(${JSON.stringify(field)}));
+/** 组件状态更新可能触发表单重渲染并复位滚动位置，动作完成后重新把目标控件滚入视口。 */
+function revealNativeSelectableDomTarget(agent, field, option) {
+    const script = `(() => {
+  const normalize = (value) => (value || '').replace(/\\s+/g, '').trim();
+  const isVisible = (element) => {
+    const style = window.getComputedStyle(element);
+    const rect = element.getBoundingClientRect();
+    return style.visibility !== 'hidden' && style.display !== 'none' && rect.width > 0 && rect.height > 0;
+  };
+  const target = normalize(${JSON.stringify(option)});
+  const field = normalize(${JSON.stringify(field)});
+  const candidates = [...document.querySelectorAll('label')]
+    .filter((label) => label.querySelector('input[type="radio"], input[type="checkbox"]'))
+    .filter(isVisible)
+    .filter((label) => normalize(label.textContent) === target);
+  if (candidates.length === 0) return JSON.stringify({ revealed: false });
+  const fieldNodes = field
+    ? [...document.querySelectorAll('label, [class*="label"], [class*="form-item"], [class*="formItem"], dt, th')]
+      .filter((element) => isVisible(element) && normalize(element.textContent).includes(field))
+    : [];
+  const distance = (left, right) => {
+    const a = left.getBoundingClientRect();
+    const b = right.getBoundingClientRect();
+    return Math.abs((a.left + a.right - b.left - b.right) / 2)
+      + Math.abs((a.top + a.bottom - b.top - b.bottom) / 2);
+  };
+  const targetLabel = candidates
+    .map((label) => ({
+      label,
+      fieldDistance: fieldNodes.length > 0 ? Math.min(...fieldNodes.map((fieldNode) => distance(fieldNode, label))) : 0,
+    }))
+    .sort((a, b) => a.fieldDistance - b.fieldDistance)[0]?.label;
+  if (!targetLabel) return JSON.stringify({ revealed: false });
+  targetLabel.scrollIntoView({ block: 'center', inline: 'nearest', behavior: 'instant' });
+  return JSON.stringify({ revealed: true });
 })()`;
     try {
-        const opened = parseEvalJson(agent.evaluate(openScript));
-        if (typeof opened.opened !== 'boolean') {
-            return { attempted: false, output: null };
-        }
-        if (!opened.found) {
-            return { attempted: false, output: null };
-        }
-        if (opened.opened === false) {
-            return { attempted: true, output: null };
-        }
-        agent.waitMs(300);
+        return parseEvalJson(agent.evaluate(script)).revealed === true;
+    }
+    catch {
+        return false;
+    }
+}
+/** 直接读取 DOM 中目标复选框及同组状态，验证“取消”与“仅勾选”的最终语义。 */
+function verifyNativeSelectableDomState(agent, action) {
+    const script = `(() => {
+  const normalize = (value) => (value || '').replace(/\\s+/g, '').trim();
+  const isVisible = (element) => {
+    const style = window.getComputedStyle(element);
+    const rect = element.getBoundingClientRect();
+    return style.visibility !== 'hidden' && style.display !== 'none' && rect.width > 0 && rect.height > 0;
+  };
+  const target = normalize(${JSON.stringify(action.option)});
+  const field = normalize(${JSON.stringify(action.field)});
+  const mode = ${JSON.stringify(action.mode ?? 'select')};
+  const candidates = [...document.querySelectorAll('label')]
+    .map((label) => ({ label, input: label.querySelector('input[type="radio"], input[type="checkbox"]') }))
+    .filter(({ label, input }) => input && isVisible(label) && normalize(label.textContent) === target);
+  if (candidates.length !== 1) return JSON.stringify({ found: false });
+  const { label, input } = candidates[0];
+  let group = [input];
+  for (let current = label.parentElement, depth = 0; current && depth < 8; current = current.parentElement, depth += 1) {
+    const checkboxes = [...current.querySelectorAll('input[type="checkbox"]')].filter((item) => !item.disabled);
+    if (checkboxes.includes(input) && checkboxes.length > 1 && (!field || normalize(current.textContent).includes(field))) {
+      group = checkboxes;
+      break;
+    }
+  }
+  const desiredChecked = mode !== 'deselect';
+  const otherSelectedCount = group.filter((item) => item !== input && item.checked).length;
+  return JSON.stringify({
+    found: true,
+    reached: input.checked === desiredChecked && (mode !== 'exclusive' || group.length > 1 && otherSelectedCount === 0),
+  });
+})()`;
+    try {
+        const parsed = parseEvalJson(agent.evaluate(script));
+        return parsed.found === true && typeof parsed.reached === 'boolean' ? parsed.reached : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** 普通下拉优先按 DOM 中字段同组控件和可见弹层选项点击，避开嵌套布局里的 ref 坐标漂移。 */
+function clickDropdownDomTarget(agent, field, option, alreadyOpened = false) {
+    const consumeOpenedDropdown = () => {
         const clickScript = `(() => {
   const selectHelper = ${dropdownDomHelperSource()};
   return JSON.stringify(selectHelper.clickVisibleOption(${JSON.stringify(option)}));
@@ -161,23 +388,64 @@ function clickDropdownDomTarget(agent, field, option) {
             const searched = parseEvalJson(agent.evaluate(searchScript));
             if (searched.searched === true) {
                 agent.waitMs(500);
-                const retryClickScript = `(() => {
+                Object.assign(clicked, parseEvalJson(agent.evaluate(clickScript)));
+            }
+        }
+        if (clicked.clicked !== true) {
+            for (let attempt = 0; attempt < 20; attempt += 1) {
+                const scrollScript = `(() => {
   const selectHelper = ${dropdownDomHelperSource()};
-  return JSON.stringify(selectHelper.clickVisibleOption(${JSON.stringify(option)}));
+  return JSON.stringify(selectHelper.scrollActiveDropdown(${JSON.stringify(option)}));
 })()`;
-                Object.assign(clicked, parseEvalJson(agent.evaluate(retryClickScript)));
+                const scrolled = parseEvalJson(agent.evaluate(scrollScript));
+                Object.assign(clicked, scrolled);
+                if (scrolled.clicked === true || scrolled.scrolled !== true) {
+                    break;
+                }
+                agent.waitMs(200);
             }
         }
-        if (clicked.clicked === true) {
-            agent.waitMs(300);
-            const selectedText = clicked.selectedText ? ` (${clicked.selectedText})` : '';
-            const dropdownCleanup = dismissActiveDropdown(agent);
-            return {
-                attempted: true,
-                output: [`select dom click ${field}=${option}${selectedText}`, dropdownCleanup].filter(Boolean).join('\n'),
-            };
+        if (clicked.clicked !== true) {
+            return { attempted: true, output: null };
         }
-        return { attempted: true, output: null };
+        agent.waitMs(300);
+        const selectedText = clicked.selectedText ? ` (${clicked.selectedText})` : '';
+        const dropdownCleanup = dismissActiveDropdown(agent);
+        return {
+            attempted: true,
+            output: [`select dom click ${field}=${option}${selectedText}`, dropdownCleanup].filter(Boolean).join('\n'),
+        };
+    };
+    const visibleDropdownScript = `(() => {
+  const selectHelper = ${dropdownDomHelperSource()};
+  return JSON.stringify(selectHelper.hasVisibleDropdown());
+})()`;
+    const openScript = `(() => {
+  const selectHelper = ${dropdownDomHelperSource()};
+  return JSON.stringify(selectHelper.openDropdownByField(${JSON.stringify(field)}));
+})()`;
+    try {
+        const dropdownVisible = parseEvalJson(agent.evaluate(visibleDropdownScript)).dropdownOpen === true;
+        if (dropdownVisible) {
+            const consumed = consumeOpenedDropdown();
+            if (consumed.output || alreadyOpened) {
+                return consumed;
+            }
+        }
+        if (!alreadyOpened) {
+            const opened = parseEvalJson(agent.evaluate(openScript));
+            if (typeof opened.opened !== 'boolean') {
+                return { attempted: false, output: null };
+            }
+            if (!opened.found) {
+                return { attempted: false, output: null };
+            }
+            if (opened.opened === false) {
+                return { attempted: true, output: null };
+            }
+        }
+        agent.waitMs(300);
+        return consumeOpenedDropdown();
     }
     catch (error) {
         if (error instanceof Error && error.message === '选中选项后下拉层仍未收起') {
@@ -214,6 +482,20 @@ function dismissActiveDropdown(agent) {
     }
     return 'dismiss active dropdown';
 }
+/** 快照未暴露组合输入中的下拉值时，读取字段对应下拉的真实 DOM 值做最终确认。 */
+function verifyDropdownDomState(agent, field, option) {
+    const script = `(() => {
+  const selectHelper = ${dropdownDomHelperSource()};
+  return JSON.stringify(selectHelper.verifySelectedValueByField(${JSON.stringify(field)}, ${JSON.stringify(option)}));
+})()`;
+    try {
+        const parsed = parseEvalJson(agent.evaluate(script));
+        return parsed.found === true && typeof parsed.reached === 'boolean' ? parsed.reached : null;
+    }
+    catch {
+        return null;
+    }
+}
 /** 长表单中字段可能不在当前可交互快照里，按视口上下搜索字段和目标选项。 */
 function searchSelectableInLongForm(agent, action) {
     const logs = [];
@@ -241,18 +523,17 @@ function clickSwitchDomTarget(agent, field, option) {
     const script = `(() => {
   const switchHelper = ${switchDomHelperSource()};
   const result = switchHelper.findSwitchByField(${JSON.stringify(field)}, ${JSON.stringify(option)});
-  if (!result.found || !result.switchId || typeof result.desiredChecked !== 'boolean') {
-    return JSON.stringify(result);
+  const element = result.element;
+  const { element: ignoredElement, ...evidence } = result;
+  if (!result.found || !element || typeof result.desiredChecked !== 'boolean') {
+    return JSON.stringify(evidence);
   }
   if (result.checked === result.desiredChecked) {
-    return JSON.stringify({ ...result, clicked: false });
-  }
-  const element = document.querySelector('[data-browser-opt-switch-id="' + result.switchId + '"]');
-  if (!element) {
-    return JSON.stringify({ ...result, clicked: false, missingElement: true });
+    return JSON.stringify({ ...evidence, clicked: false });
   }
+  element.scrollIntoView({ block: 'center', inline: 'nearest' });
   element.click();
-  return JSON.stringify({ ...result, clicked: true });
+  return JSON.stringify({ ...evidence, clicked: true });
 })()
 `;
     try {
@@ -282,7 +563,8 @@ function verifySwitchDomState(agent, field, option) {
     const script = `(() => {
   const switchHelper = ${switchDomHelperSource()};
   const result = switchHelper.findSwitchByField(${JSON.stringify(field)}, ${JSON.stringify(option)});
-  return JSON.stringify(result);
+  const { element: ignoredElement, ...evidence } = result;
+  return JSON.stringify(evidence);
 })()
 `;
     try {
@@ -476,7 +758,12 @@ function clickVisibleOption(option) {
     ? options[ordinalIndex === -1 ? options.length - 1 : ordinalIndex]
     : options
       .filter((item) => item.text.includes(optionText) || optionText.includes(item.text))
-      .sort((a, b) => (a.rect.width * a.rect.height) - (b.rect.width * b.rect.height))[0];
+      .sort((a, b) => {
+        const aExactRank = a.text === optionText ? 0 : 1;
+        const bExactRank = b.text === optionText ? 0 : 1;
+        return aExactRank - bExactRank
+          || (a.rect.width * a.rect.height) - (b.rect.width * b.rect.height);
+      })[0];
   if (!target) {
     return { found: false, clicked: false };
   }
@@ -492,9 +779,44 @@ function searchActiveDropdown(option) {
   if (!(input instanceof HTMLInputElement || input instanceof HTMLTextAreaElement)) {
     return { searched: false };
   }
+  if (input.readOnly || input.disabled) {
+    return { searched: false };
+  }
   browserOptInputValue(input, option);
   return { searched: true };
 }
+function scrollActiveDropdown(option) {
+  const clicked = clickVisibleOption(option);
+  if (clicked.clicked) {
+    return clicked;
+  }
+  const active = document.querySelector('[data-browser-opt-active-select="true"]');
+  const activeRect = active?.getBoundingClientRect();
+  const root = browserOptDropdownContainers()
+    .map((item) => ({ ...item, distance: activeRect ? browserOptCenterDistance(activeRect, item.rect) : 0 }))
+    .sort((a, b) => a.distance - b.distance)[0]?.element;
+  if (!root) {
+    return { found: false, clicked: false, scrolled: false };
+  }
+  const preferred = root.querySelector('.rc-virtual-list-holder, .ant-select-dropdown-menu, .el-scrollbar__wrap');
+  const candidates = [preferred, root, ...root.querySelectorAll('[role="listbox"], [class*="virtual-list"], [class*="scroll"]')]
+    .filter((element, index, items) => element instanceof HTMLElement && items.indexOf(element) === index)
+    .filter((element) => element.scrollHeight > element.clientHeight + 1);
+  const scrollable = candidates[0];
+  if (!scrollable) {
+    return { found: false, clicked: false, scrolled: false };
+  }
+  const previousTop = scrollable.scrollTop;
+  const maxTop = Math.max(scrollable.scrollHeight - scrollable.clientHeight, 0);
+  scrollable.scrollTop = Math.min(previousTop + Math.max(Math.floor(scrollable.clientHeight * 0.8), 120), maxTop);
+  scrollable.dispatchEvent(new Event('scroll', { bubbles: true }));
+  return {
+    found: false,
+    clicked: false,
+    scrolled: scrollable.scrollTop > previousTop,
+    reachedEnd: scrollable.scrollTop >= maxTop,
+  };
+}
 function dismissActiveDropdown() {
   const containers = browserOptDropdownContainers();
   if (containers.length === 0) {
@@ -514,7 +836,46 @@ function dismissActiveDropdown() {
 function hasVisibleDropdown() {
   return { dropdownOpen: browserOptDropdownContainers().length > 0 };
 }
-return { openDropdownByField, clickVisibleOption, searchActiveDropdown, dismissActiveDropdown, hasVisibleDropdown };
+function verifySelectedValueByField(field, option) {
+  const fieldText = normalizeBrowserOptText(field);
+  const optionText = normalizeBrowserOptText(option);
+  const labels = [...document.querySelectorAll('body *')]
+    .filter((element) => browserOptVisible(element) && normalizeBrowserOptText(element.textContent).includes(fieldText))
+    .map((element) => ({ element, rect: element.getBoundingClientRect() }))
+    .sort((a, b) => (a.rect.width * a.rect.height) - (b.rect.width * b.rect.height));
+  for (const label of labels) {
+    for (const container of browserOptClosestFieldContainers(label.element)) {
+      const targets = browserOptSelects()
+        .filter((select) => container.element.contains(select))
+        .map((element) => ({ element, distance: browserOptCenterDistance(label.rect, element.getBoundingClientRect()) }))
+        .sort((a, b) => a.distance - b.distance);
+      for (const target of targets) {
+        const element = target.element;
+        const nativeValue = element.matches('select')
+          ? String(element.selectedOptions?.[0]?.textContent || element.value || '')
+          : '';
+        const inputValue = String(element.querySelector('input:not([type="hidden"])')?.value || '');
+        const selectedText = String(element.querySelector([
+          '.ant-select-selection-item',
+          '.ant-select-selection-selected-value',
+          '.el-input__inner',
+          '[class*="singleValue"]'
+        ].join(','))?.textContent || '');
+        const values = [nativeValue, inputValue, selectedText]
+          .map(normalizeBrowserOptText)
+          .filter(Boolean);
+        if (values.some((value) => value === optionText)) {
+          return { found: true, reached: true, value: optionText };
+        }
+      }
+      if (targets.length > 0) {
+        return { found: true, reached: false };
+      }
+    }
+  }
+  return { found: false };
+}
+return { openDropdownByField, clickVisibleOption, searchActiveDropdown, scrollActiveDropdown, dismissActiveDropdown, hasVisibleDropdown, verifySelectedValueByField };
 })()
 `;
 }
@@ -558,22 +919,32 @@ const browserOptSwitches = () => [...document.querySelectorAll('[role="switch"],
   .filter((element) => browserOptVisible(element) && (element.getAttribute('role') === 'switch' || String(element.className || '').includes('switch')));
 function findSwitchByField(field, option) {
   const fieldText = normalizeBrowserOptText(field);
+  // 字段文案只做标准化后的完整匹配，避免相似字段误触发相邻开关。
   const labels = [...document.querySelectorAll('body *')]
-    .filter((element) => browserOptVisible(element) && normalizeBrowserOptText(element.textContent).includes(fieldText))
-    .map((element) => ({ element, rect: element.getBoundingClientRect() }))
-    .sort((a, b) => (a.rect.width * a.rect.height) - (b.rect.width * b.rect.height));
-  const switches = browserOptSwitches().map((element, index) => {
-    const id = 'browser-opt-switch-' + index;
-    element.setAttribute('data-browser-opt-switch-id', id);
-    return {
-      element,
-      id,
-      rect: element.getBoundingClientRect(),
-      checked: browserOptSwitchState(element),
-      desiredChecked: browserOptSwitchDesiredState(element, option),
-    };
-  });
+    .filter((element) => browserOptVisible(element))
+    .map((element) => {
+      const text = normalizeBrowserOptText(element.textContent);
+      return { element, text, rect: element.getBoundingClientRect() };
+    })
+    .filter((item) => item.text.includes(fieldText))
+    .sort((a, b) => a.text.length - b.text.length || (a.rect.width * a.rect.height) - (b.rect.width * b.rect.height));
+  const switches = browserOptSwitches().map((element) => ({
+    element,
+    rect: element.getBoundingClientRect(),
+    checked: browserOptSwitchState(element),
+    desiredChecked: browserOptSwitchDesiredState(element, option),
+  }));
   for (const label of labels) {
+    // 优先使用字段所在的最小单开关容器，避免相邻卡片或大表单中的无名 switch 串位。
+    let container = label.element.parentElement;
+    for (let depth = 0; container && container !== document.body && depth < 6; depth += 1, container = container.parentElement) {
+      const contained = switches.filter((item) => container.contains(item.element) && item.checked !== null && item.desiredChecked !== null);
+      if (contained.length === 1) {
+        const target = contained[0];
+        return { found: true, checked: target.checked, desiredChecked: target.desiredChecked, element: target.element };
+      }
+    }
+
     const sameRow = switches
       .map((item) => {
         const verticalOverlap = Math.min(label.rect.bottom, item.rect.bottom) - Math.max(label.rect.top, item.rect.top);
@@ -585,7 +956,7 @@ function findSwitchByField(field, option) {
       .sort((a, b) => a.yDistance - b.yDistance || a.xDistance - b.xDistance);
     const target = sameRow[0];
     if (target) {
-      return { found: true, checked: target.checked, desiredChecked: target.desiredChecked, switchId: target.id };
+      return { found: true, checked: target.checked, desiredChecked: target.desiredChecked, element: target.element };
     }
   }
   return { found: false, checked: null, desiredChecked: null };
@@ -601,6 +972,16 @@ function isSwitchSelectable(role) {
 function isDropdownOption(role) {
     return Boolean(role && /option/i.test(role));
 }
+/** 布尔型目标值在真实页面常呈现为无名 switch，先尝试 DOM 同行近邻开关，失败后再回落其他选择策略。 */
+function shouldUseSwitchDomFallback(snapshot, action, role) {
+    if (!action.field) {
+        return false;
+    }
+    if (isSwitchSelectable(role) || snapshotHasSwitchField(snapshot, action.field)) {
+        return true;
+    }
+    return isBooleanLikeSwitchOption(action.option);
+}
 /** 只有 snapshot 明确把字段暴露为 switch 时，才启用开关 DOM 兜底，避免大表单误碰邻近控件。 */
 function snapshotHasSwitchField(snapshot, field) {
     if (!field) {
@@ -640,6 +1021,10 @@ function isFieldLabelSnapshotLine(parsed, normalizedField) {
     const normalizedLabel = normalizeVisibleText(parsed.label);
     return normalizedLabel.includes(normalizedField) && normalizedLabel.length <= normalizedField.length + 8;
 }
+/** 与 utils 中的布尔 switch 词表保持一致，供本文件决定是否值得走 switch DOM 兜底。 */
+function isBooleanLikeSwitchOption(option) {
+    return /^(是|否|开|关|开启|关闭|打开|启用|停用|true|false|yes|no|on|off)$/i.test(option.trim());
+}
 /** 下拉选择通常会收起选项列表，只保留字段和值文案，因此补充基于页面文案的确认。 */
 function isSelectedValueVisible(text, field, option) {
     const normalizedText = normalizeVisibleText(text);