Browser Harness 跨源 iframe 操控指南iframe_target 目标附着与合成器层坐标点击【免费下载链接】browser-harnessBrowser Harness | Self-healing harness that enables LLMs to complete any task.项目地址: https://gitcode.com/gh_mirrors/br/browser-harness导读本文聚焦 Browser Harnessbrowser-harness处理跨源 iframe 的核心方法论通过iframe_target(...)解析出 iframe 的 CDP Target借助js(..., target_id...)完成目标附着target attachment并在 DOM 层面无法直接操作时改用合成器层compositor-level坐标点击。读完本文你将掌握跨源 iframe 场景下何时走 DOM、何时走坐标的取舍原则以及从 helpers.py 到真实领域技能CentileBrain、Shopify Admin的完整调用链。关联文档 interaction-skills/cross-origin-iframes.md 定义了三条铁律聚焦iframe_target(...)、理解目标附着、认识到合成器层坐标点击在跨目标 DOM 工作受阻时更低摩擦。本文沿此骨架结合源码纵深展开。为什么跨源 iframe 是独立的关卡同源与跨源的本质差异浏览器安全模型决定了对 iframe 的两种截然不同的处理方式同源 iframe父页面可以通过contentDocument/contentWindow直接穿透访问内部 DOM这也是 interaction-skills/iframes.md 讲述的路径——直接遍历 frame 内部文档。跨源 iframe父页面的 JavaScript 无法触碰其 DOMcontentDocument返回nullcontentWindow上的属性访问被SecurityError拦截。此时任何从父页面 JS 注入查询的方案都会失败。Browser Harness 的答案不是绕过安全模型而是绕过父页面把 iframe 当作一个独立的 CDP Target 来附着直接在目标上下文中执行 JavaScript。这正是iframe_target(...)存在的意义。设计约束不要发明跨 frame 的 JS 遍历器项目主文档 src/browser_harness/SKILL.md 的 Gotchas 一节明确要求 Agent Do not invent aRuntime.evaluatescroll replacement or a cross-frame JS walker。换句话说遇到跨源 iframe 时正确姿势是使用框架内置的iframe_target() target 附着机制而不是尝试在父页面写一个递归遍历所有 frame 的 JS 脚本这在跨源下本就行不通。iframe_target()从 CDP Target 列表中定位 iframe源码实现iframe_target()定义在 src/browser_harness/helpers.pydef iframe_target(url_substr): First iframe target whose URL contains url_substr. Use with js(..., target_id...). for t in cdp(Target.getTargets)[targetInfos]: if t[type] iframe and url_substr in t.get(url, ): return t[targetId] return None其工作原理调用 CDP 命令Target.getTargets通过 cdp() 封装返回result中的targetInfos。遍历所有 target 信息筛选type iframe且 URL 中包含url_substr的目标。返回第一个匹配的targetId无匹配时返回None。入参设计为什么用 URL 子串匹配跨源 iframe 没有可用的 CSS 选择器父页面 DOM 访问不到因此定位依据必须是浏览器层可见的属性而 URL 是最稳定、最具辨识度的特征。典型用法是传 iframe 加载的应用路径片段例如CentileBrain 的 Shiny 应用iframe_target(shinyapps.io/SV-MALE)—— 定位子皮层体积Subcortical Volume男性模态的 iframeShopify Admin 的嵌入应用iframe_target(qa-pairs-app)—— 定位 Knowledge Base 应用 iframe。返回值的两种形态命中返回字符串形式的targetId可原样传给js(..., target_id...)未命中返回None。调用方应据此判断 iframe 尚未渲染完成或 URL 匹配错误再决定重试或放弃。目标附着js(..., target_id...) 的完整生命周期调用链剖析js()定义在 src/browser_harness/helpers.py是目标附着的核心入口def js(expression, target_idNone): Run JS in the attached tab (default) or inside an iframe target (via iframe_target()). sid cdp(Target.attachToTarget, targetIdtarget_id, flattenTrue)[sessionId] if target_id else None try: result _js_evaluate(expression, sid) except BaseException: if sid: try: _detach_iframe_session(sid) except BaseException: pass raise if sid: _detach_iframe_session(sid) return result一次完整的跨源 iframe JS 执行包含四个阶段附着attach调用Target.attachToTarget(targetIdtarget_id, flattenTrue)获得一个专属的sessionId。flattenTrue使该 session 的消息走扁平化协议与 daemon 的 IPC 模型兼容。这是目标附着的字面含义——在浏览器内部把执行上下文切换到目标 iframe。求值evaluate_js_evaluate(expression, sid)内部走 Runtime.evaluate带session_idsid把脚本投递到 iframe 的 JS 上下文。表达式先原样求值若 Chrome 报 Illegal return statement则用(function(){...})()包裹后重试见 helpers.py因此document.title和const x 1; return x两种写法都可用。异常清理求值抛错时仍会尝试 detach避免 session 泄漏且 detach 失败不会覆盖原始求值错误。分离detach正常路径也会调用_detach_iframe_session(sid)释放 session。为什么每次调用都要 detach_detach_iframe_session()的文档字符串helpers.py解释了原因防止轮询循环每次调用累积一个存活 session及其事件流。Agent 在 iframe 内等待元素出现时常写 15 次轮询若不及时分离session 会越积越多。实现上调用Target.detachFromTarget(sessionIdsid)并宽容处理 Chrome 已因 iframe 导航或关闭而丢弃 session 的情况no session with given id 视为正常不抛错保证iframe 已不在时不是泄漏。落到真实调用形态在 agent-workspace/domain-skills/shopify-admin/polaris-inputs.md 的 add-FAQ 模式中附着后的典型用法是from helpers import iframe_target, js, type_text, page_info, screenshot tid iframe_target(qa-pairs-app) # 1. 解析 iframe target for _ in range(15): # 2. 轮询等表单渲染完成 ready js((() { const i Array.from(document.querySelectorAll(input[typetext], input:not([type]))) .find(x { const r x.getBoundingClientRect(); return r.width 100; }); const t Array.from(document.querySelectorAll(textarea)) .find(x { const r x.getBoundingClientRect(); return r.width 100; }); if (i t) { i.focus(); return true; } return false; })(), target_idtid) # 3. 附着到 iframe 执行 if ready: break time.sleep(0.3) type_text(question) # 4. 焦点已在 iframe 内直接输入注意第 3 步选择器input、textarea是在iframe 自己的文档里查询的而不是父页面——这正是目标附着的价值。合成器层坐标点击跨目标 DOM 工作的低摩擦替代核心原理项目设计约束src/browser_harness/SKILL.md原话是Coordinate clicks default. CDP mouse events pass through iframes/shadow/cross-origin at the compositor level.即 CDP 的鼠标事件是在合成器层派发的天然穿透 iframe、Shadow DOM、跨源边界。当目标元素在跨源 iframe 内、且无法或不便用 JS 操作时直接用页面坐标系计算坐标并派发鼠标事件就能物理点击到 iframe 里的元素。实现click_at_xy()坐标点击的底层实现在 src/browser_harness/helpers.pydef click_at_xy(x, y, buttonleft, clicks1): cdp(Input.dispatchMouseEvent, typemousePressed, xx, yy, buttonbutton, clickCountclicks) cdp(Input.dispatchMouseEvent, typemouseReleased, xx, yy, buttonbutton, clickCountclicks)它连续派发mousePressed与mouseReleased两个事件完成一次点击可指定buttonleft/right/middle与clicks连击次数。坐标(x, y)为页面视口坐标CSS 像素。这里必须强调 frame-local 与 page 坐标的换算陷阱iframe 内部元素调用getBoundingClientRect()得到的是相对于 iframe 视口的坐标而click_at_xy()需要的是相对于顶层页面的坐标。跨源 iframe 在父页面中的偏移可通过父页面 JS 读取 iframe 元素自身的位置父页面能读到 iframe 标签的布局信息获得然后做加法换算。这也是 interaction-skills/iframes.md 要求keep the frame-local versus page-coordinate warning explicit的原因。何时坐标点击优于跨目标 DOM 工作场景首选方案理由需要读 iframe 内部状态值、文本、属性js(..., target_idiframe_target(...))DOM 读取必须附着到目标上下文需要触发框架事件React/Vue 受控组件js(target_id...)fill_input系辅助坐标点击不产生框架可见的合成事件只差点一下按钮/链接无需读取结果click_at_xy(x, y)合成器层穿透跨源边界零 DOM 依赖、零 session 开销元素在 Shadow DOM 深层且跨源坐标点击合成器层同样穿透 shadow 边界核心取舍需要读就附着 target 走 DOM只需要点就坐标点击。前者每次调用都有 attach/detach 与 JS 求值成本后者只是两次鼠标事件派发因此更低摩擦lower-friction。真实场景复盘两个跨源 iframe 实战案例CentileBrain多模态 Shiny iframe 切换agent-workspace/domain-skills/centilebrain/generate-estimates.md 记录了一个教科书级场景https://centilebrain.org/#/model主页面只是薄壳真正的工作界面是centilebrain-app.shinyapps.io/{SV|CT|SA}-{MALE|FEMALE}/三个模态 × 两种性别的Shiny iframe。上传表单、Compute 按钮、下载链接全部在 iframe 内部且切换模态 换 iframe src。因此t iframe_target(shinyapps.io/SV-MALE) # 定位对应模态的 iframe再配合upload_file(..., target_id...)这类 iframe 感知辅助函数完成任务。该文档还警告了一个关键坑详见下节。Shopify Admin嵌入应用Embedded App面板Shopify 的嵌入式应用同样通过跨源 iframe 承载embedded-apps.md 与 knowledge-base.md 展示了标准套路tid iframe_target(qa-pairs-app)或online-store-web后一切针对面板内部元素的操作都带target_idtid执行。实战注意事项target_id 会随导航失效CentileBrain 技能文档明确指出模态切换后旧 target_id 立即失效。原因在于 iframe 导航会使其对应的 CDP Target 被浏览器销毁重建旧targetId指向已不存在的目标。即便Target.getTargets短暂仍列出旧条目附着也会失败。正确做法是点击切换按钮如CORTICAL THICKNESStime.sleep(2-3)等待新 iframe 加载重新调用iframe_target(shinyapps.io/CT-MALE)获取新 target_id。未命中返回 None 的处理iframe_target()找不到匹配时返回None。此时若直接传入js(..., target_idNone)会退化为在当前已附着标签页执行 JS——这可能静默执行到错误上下文。因此在真实技能中应显式轮询如 15 次 × 0.3s确认tid非空再继续。注意聚焦限制合成器层点击依赖视口坐标因此目标元素必须先滚动进视口参考 interaction-skills/scrolling.md。若页面因隐藏而暂停background tab 的节流可临时用cdp(Emulation.setFocusEmulationEnabled, enabledTrue)操作完成后在finally中关闭而不是把 Chrome 带到前台SKILL.md。小结跨源 iframe 的三个决策点定位一律用iframe_target(url_substr)按 URL 子串从Target.getTargets解析 targetId禁止尝试跨 frame JS 遍历SKILL.md 明确禁止。执行需要读写 iframe 内部 DOM 时用js(expression, target_idtid)附着执行js()内部自动完成 attach → evaluate → detach 的生命周期且 detach 是防泄漏的必要环节helpers.py。点击只需触发交互时优先click_at_xy(x, y)走合成器层鼠标事件它天然穿透跨源边界务必把 frame 内getBoundingClientRect()得到的局部坐标换算为顶层页面坐标。掌握这三步Browser Harness 就能稳定驾驭支付回调页、嵌入式管理后台、Shiny 数据分析面板等典型跨源 iframe 应用——这是纯 DOM 自动化工具难以企及的边界。【免费下载链接】browser-harnessBrowser Harness | Self-healing harness that enables LLMs to complete any task.项目地址: https://gitcode.com/gh_mirrors/br/browser-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考