Agent 一接 iframe 后台就开始点错层：从 Frame Affinity 到 Cross-Frame Action Guard 的工程实战

浏览器 Agent 接进控制台和运营后台后最先暴露的往往不是模型读不懂文案而是它明明识别到“发布”“保存”“确认”执行器却在多层 iframe 里点错层。⚠️ 页面被主框架和业务子页反复切开后问题会放大。人类会自然把左侧菜单、右侧业务区和弹层反馈理解成同一个操作面。 Agent 若只依赖浅层 DOM 或截图坐标点到的却可能是错误 frame 内的同名按钮。 缺失的是 frame 绑定关系。图 1浏览器 Agent 在多层后台里最常见的失误不是看不懂而是动作落在了错误 frameiframe 为什么会让 Agent 看得见却点错层iframe 的麻烦在于页面对人类展示的是一个连续界面对执行器暴露的却是多层上下文。 许多 Agent 先全局搜文本再把最近的可点击节点当目标一旦“保存”同时出现在主页面和子页里动作就可能落到错误 frame。更隐蔽的是这类错误常常不会立刻报成硬失败。 有些系统会把点击吞掉也有些会在旁路页面触发无关操作日志像“按钮已点击”业务状态却已经偏航。✅ 团队最后缺的往往是 frame 身份和动作结果之间的闭环校验。图 2在嵌套后台里同名按钮可能分布在不同 frame错误上下文会直接放大误点一组 Frame Affinity 对比实验把问题暴露得很直实验回放了58条真实浏览器任务覆盖发布按钮、筛选面板、日期组件和二次确认弹层。 基线方案只用截图理解加普通 CSS 定位改进方案先锁定目标 frame再用Frame Affinity绑定页面身份最后用Cross-Frame Action Guard校验回显。方案动作成功率平均重试次数误点率人工接管率截图理解 浅层 DOM 定位61%4.214%19%Frame Affinity Cross-Frame Action Guard89%1.33%6%拉开差距的不是模型“更会找按钮”而是执行器先证明动作落在哪个 frame、点击后出现什么反馈。 只把成功定义成“元素被点击”系统就会被大量伪成功污染把成功改成“命中正确上下文并拿到回显”误点率才会收敛。asyncfunctionclickWithFrameAffinity(page,intent){constframepage.frameLocator(intent.frameSelector).frameLocator(intent.innerFrameSelector);consttargetframe.locator([aria-label${intent.label}], [data-testid${intent.testId}]).first();awaittarget.scrollIntoViewIfNeeded();awaittarget.click();awaitframe.locator(intent.confirmSelector).waitFor({state:visible});}这段逻辑的关键不在于多写几行 locator而在于把 frame 身份和成功回显放进同一份契约。️ 当契约缺一项时流程宁可回退重试也不要把一次侥幸点击当成稳定能力。图 3浏览器 Agent 的点击稳定性往往取决于是否能先穿透组件边界再验证动作结果工程上真正该补的是 Cross-Frame Action Guard很多团队一看到找不到按钮就先把重试次数从2次拉到5次。 这种做法只会放大偶然命中的假象因为错误目标被点得越多页面状态越乱。更有效的做法是把目标 frame 和动作回显收敛成可验证链路。实践里最值钱的三个锚点很朴素目标 frame 是否匹配任务意图、点击后页面是否出现预期回显、异常时能否立即阻断副作用。 只要这三层能串起来iframe 就不再是“模型看不懂”的问题而是可治理的执行边界问题。图 4真正可上线的浏览器 Agent不只会点按钮还会证明这次点击为什么成立未来 3 到 6 个月 浏览器 Agent 会更依赖组件语义值得投入的方向不是继续堆更大截图理解模型而是给执行层补齐 frame 身份缓存、选择器版本化和动作回显断言。 大量浏览器事故都发生在“模型理解正确、执行绑定错误”的夹层里工程护栏更重要。一句话总结iframe 不是按钮消失了而是动作目标落进了错误上下文。⭐ 把Frame Affinity和Cross-Frame Action Guard补上后Agent 才能从“偶尔点对”走向“稳定命中”。你们现在的浏览器 Agent会先验证目标 frame 和成功回显吗