Astron RPA 浏览器插件开发全指南:深度搜索、Shadow DOM 递归定位与 iframe 嵌套元素定位机制

原创2026-10-09 17:15:101,895 阅读
文章标签:工作流自动化桌面应用AI 应用企业应用后端前端

Astron RPA 浏览器插件开发全指南:深度搜索、Shadow DOM 递归定位与 iframe 嵌套元素定位机制

导读

本文以 frontend/packages/browser-plugin/README.zh.md 为主体,系统讲解 Astron RPA 浏览器插件(@rpa/extension)的打包构建方式、鼠标悬浮深度搜索触发机制、Shadow DOM 递归元素获取,以及跨域/同源 iframe 嵌套元素统一定位方案。读完本文,你将掌握该插件从 npm run build 打包到 crx/xpi 分发的完整链路,并深入理解插件在元素拾取与 iframe 定位上的底层实现原理,可直接用于二次开发或排障。

该插件是 Astron RPA 体系中处理网页自动化的一环,负责在浏览器端与 RPA 执行引擎之间建立桥接:content script 负责网页元素采集与坐标换算,background service worker 负责与引擎侧的 WebSocket 通道通信,二者协同完成"网页元素定位 → 坐标与路径上报 → 指令执行"的自动化闭环。

一、插件定位与整体结构

插件本身是一个浏览器扩展(Manifest V3 为主,Firefox 构建时降级为 Manifest V2),源码目录如下:

  • src/background/:background 侧逻辑,包括 tab 管理(tab.ts)、iframe 层级解析(iframe.ts)、Cookie、网络监控、整页截图等能力;
  • src/content/:content script 侧逻辑,负责元素拾取(element.ts)、iframe 消息桥接(iframe.ts)、元素高亮(highlight.ts)、页面变化监听(watcher.ts);
  • src/common/:两端共享的常量与工具函数;
  • src/3rd/:第三方桥接代码,其中 rpa_websocket.js 实现了与引擎端通信的 WebSocket 客户端协议。

从 manifest.ts 可以看到插件以 manifest_version: 3 为基础,background 使用 service_worker: 'background.js' 并以 type: 'module' 加载;content script 声明了 all_frames: true,匹配 http://*/*、https://*/*、file://*/*、ftp://*/*,在 document_start 阶段注入,并申请了 debugger、tabs、webNavigation、cookies、scripting、nativeMessaging 等权限。其中 all_frames: true 正是后续 iframe 统一定位方案得以成立的基础——所有 frame(包括嵌套 iframe)内都会注入同一份 content script。

Firefox 模式(mode === 'firefox')下则降级为 manifest_version: 2,去掉 Chrome 特有的 debugger 权限,增加 webRequest / webRequestBlocking,并写入 browser_specific_settings.gecko.id 与 strict_min_version: '58.0'。

二、打包构建说明

插件基于 Vite 构建,入口脚本在 package.json 中定义:

npm run build        # 打包 Chrome/Edge 通用插件(background + content 双入口)
npm run build:firefox    # 打包 Firefox(MV2)版本
npm run build:chromium   # 打包 Chromium 变体版本
npm run build:all        # 依次执行以上全部构建
npm test                 # 运行 vitest 单元测试

2.1 双入口构建机制

build 脚本通过 cross-env BUILD_ENTRY=background / BUILD_ENTRY=content 各执行一次 Vite 构建,最终在 dist/ 下产出 background.js 与 content.js 两个独立产物。对应逻辑见 vite.config.ts:rollupOptions.input 根据 BUILD_ENTRY 分别指向 src/background.ts 或 src/content.ts,且开启 inlineDynamicImports 保证单文件输出。构建结束后,插件还会通过 archiver 自动把 dist/ 目录压缩为 rpa-extension-v3-{version}-{mode}.zip 发布包。

2.2 构建自定义浏览器变体

README 指出:npm run build 可以打包任何 Chromium/Firefox 内核的变体浏览器插件,只需要在 src/3rd/rpa_websocket.js 中设置 custom_agent,并在 package.json 中添加对应命令即可,browser 为该浏览器可执行文件的文件名。

结合源码看,src/3rd/rpa_websocket.js 中的 custom_agent() 读取 Vite 注入的 __BUILD_MODE__ 编译常量,已内置三个映射:

const modeAgent = {
  '360se': "$360se$",
  '360ChromeX': "$360ChromeX$",
  'chromium': "$chromium$"
}

即默认构建模式下(如 360se 变体)插件会以 $360se$ 作为 agent 标识连接引擎。agent 最终通过 btoa(agent) 生成 token,拼接到 WebSocket 地址 ws_base_url?token=...&nv=...&cid=... 上,用于服务端识别浏览器类型(Chrome/Edge/Firefox 由 get_navigator_user_agent() 自动识别为 $chrome$/$edge$/$firefox$)。因此,若要适配一个新的内核变体浏览器,只需在 modeAgent 中增加一条映射、在 package.json 中新增一条 build:<browser> 脚本并设置对应 BUILD_MODE 即可。

2.3 Node 版本要求

README 明确要求 Node.js v20+。该要求与 Vite 5、@vitest/browser 3.x、chrome-types 等依赖的运行时需求一致,低于 v20 时建议先升级 Node 环境再执行构建。

三、插件深度搜索功能

3.1 触发机制

深度搜索由鼠标悬浮时长触发:鼠标在元素上持续悬浮 5 秒以上,插件会执行一次深度搜索。触发与防抖逻辑在 src/content/contentInject.ts 的 moveListener 中实现,常量定义见 src/content/constant.ts:

export const DEEP_SEARCH_TRIGGER = 5 * 1000   // 深度搜索触发阈值:5 秒
export const ELEMENT_SEARCH_TRIGGER = 200     // 浅搜索防抖阈值:200ms

流程如下:鼠标移动时先清除旧定时器,200ms 后执行一次浅搜索;浅搜索完成后紧接着挂一个 5 秒的定时器,到点后将 deepSearchEnabled 置为 true 再执行一次 findElement,随后立即复位为 false。两次搜索共用同一入口函数 findElement,只是深度标志不同。

3.2 实现原理与适用边界

README 明确指出:深度搜索旨在解决一部分元素遮挡问题,但有些未被遮挡的元素,深度搜索后反而会命中非用户想要的元素,因此并非所有元素都适合触发深度搜索。

浅搜索与深度搜索的分歧点落在 src/content/element.ts 的 findElementByPoint 与 getClosestElementByPoint:

export function findElementByPoint(target: Point, deep = false, docu: Document | ShadowRoot = document) {
  let ele = elementFromPoint(target.x, target.y, docu) as HTMLElement
  if (deep && docu instanceof Document) {
    ele = getClosestElementByPoint(target)
  }
  ...
}

浅搜索直接使用 document.elementFromPoint(x, y) 返回最顶层命中元素;深度搜索则调用 getClosestElementByPoint:

  1. 先通过 document.elementsFromPoint(x, y) 取出鼠标坐标下所有层叠元素;
  2. 过滤出包围盒真正包含目标点(left <= x && top <= y && right >= x && bottom >= y)的元素;
  3. 用 Math.hypot 分别计算每个元素包围盒四角到目标点 (x, y) 的距离,取距离最近者;若存在多个结果,取第一项。

这套算法本质是"用几何距离重排遮挡关系",当被遮挡元素与顶层元素在坐标上几乎重合时,深度搜索能越过遮罩命中下层目标;但若两个元素本就并排或间距相当,最近距离判定也可能选中非预期元素——这正是 README 提醒"不需要所有元素都触发深度搜索"的原因。

四、插件 shadowRoot 递归获取元素功能

4.1 递归查找与 $shadow$ 路径拼接

对于 Web Component 场景,目标元素可能位于多层 shadowRoot 内部。插件通过 shadowRootElement 函数递归下钻,见 src/content/element.ts:

export function shadowRootElement(point: Point, shadowRoot: ShadowRoot, shadowPath = '', shadowDirs: ElementDirectory[] = []) {
  const { x, y } = point
  const ele = shadowRoot.elementFromPoint(x, y) as HTMLElement
  if (ele && ele.shadowRoot) {
    const shadowNth = `:nth-child(${getNodeNthIndex(ele)})`
    shadowPath = shadowPath ? `${shadowPath}>$shadow$>${getNthCssSelector(ele)}${shadowNth}` : `${getNthCssSelector(ele)}${shadowNth}`
    shadowDirs = shadowDirs.concat(getElementDirectory(ele))
    return shadowRootElement(point, ele.shadowRoot, shadowPath, shadowDirs)
  }
  ...
}

逻辑要点:

  • 在当前 ShadowRoot 上调用 shadowRoot.elementFromPoint(x, y) 获取该层命中元素;
  • 若该元素自身又挂有 shadowRoot,则把当前元素的 CSS 选择器拼入路径,并以 $shadow$ 作为跨层分隔符,同时把该层元素的 getElementDirectory 结果并入目录数组,继续向下一层递归;
  • 直到命中普通元素为止,返回 { element, path, dirs }。

最终生成的路径形如 custom-element:nth-child(2)>$shadow$>.inner-element>button:nth-child(1),$shadow$ 分隔符方便用户直接识别 shadow DOM 层级边界。

4.2 通过 path 反查元素

拿到 $shadow$ 路径后,插件在 getElementBySelector 中识别该分隔符并转入 shadow DOM 专用查询:

export function getElementBySelector(selector: string, onlyPosition = false): HTMLElement[] | null {
  ...
  if (selector.includes('$shadow$')) {
    const sahdowElements = getShadowElementsBySelector(selector)
    return sahdowElements.length > 0 ? sahdowElements : null
  }
  ...
}

getShadowElementsBySelector 先把选择器按 >$shadow$> 切分为"每层一个 CSS 选择器"的数组,再交给 queryDeepShadow 逐层递归:

function queryDeepShadow(selectorLevels: string[], currentHosts: [Document | ShadowRoot] = [document]) {
  const currentSelector = selectorLevels[0]
  const remainingSelectors = selectorLevels.slice(1)
  ...
  for (const host of currentHosts) {
    const elements = host.querySelectorAll(currentSelector)
    ...
    for (const el of elements) {
      if (el.shadowRoot) {
        const nestedMatches = queryDeepShadow(remainingSelectors, [el.shadowRoot])
        ...
      }
    }
  }
}

即:在 document 上执行第一层选择器,对每个命中元素检查其 shadowRoot,若存在则带着剩余选择器继续在该 shadowRoot 内递归,直至最后一层。

重要限制(README 明确):shadowRoot 元素暂时只支持 CSS 选择器获取,不支持 XPath 选择器获取。原因在于标准 XPath API(document.evaluate)无法直接穿透 ShadowRoot 边界,普通 XPath 查询对 shadow DOM 内部节点是无效的,因此插件统一走 getElementBySelector 的 CSS 路径。

五、frame 定位功能:跨域/同源 iframe 统一处理

iframe 定位是网页自动化中最棘手的场景之一。插件将其拆分为"iframe 嵌套位置换算"与"iframe 目标元素绑定"两个子问题,分别由 background 与 content 两侧协作完成。

5.1 跨域 iframe 元素位置统一处理办法

问题背景(README 原文要点):在跨域 iframe 中,由于同源策略限制,且 iframe 的 src 固定而 url 可能变动,同一个 tab 下还可能存在 src 完全相同的多个 iframe,因此通过 src 查找目标 iframe 是不准确的。

解决方案:通过插件主进程(background)拿到 iframe 的嵌套关系——即 parentFrameId,得到一组嵌套关系顺序;然后按该顺序逐层查找:传入的 (x, y) 坐标在每层都会减去对应 iframe 的位置,并扣除 iframe 盒模型的 borderLeft、paddingLeft,最终得到 iframe 内部 content 的准确位置。README 明确说"详细见 getIframeElement 这个函数在 backgroundInject 和 contentInject 的处理"。

getIframeElement 的 background 实现位于 src/background/iframe.ts,核心流程:

export async function getIframeElement(p: Point, activeElement: ElementInfo) {
  const tab = await Tabs.getActiveTab()
  const frames = await Tabs.getAllFrames(tab.id)
  ...
  let targetFrame = frames.find(frame => frame.frameId === activeElement.frameId)
  const framePath: number[] = []
  // 沿 parentFrameId 回溯,构建从顶层到目标 frame 的路径
  while (targetFrame) {
    framePath.unshift(targetFrame.frameId)
    targetFrame = frames.find(frame => frame.frameId === targetFrame.parentFrameId)
  }
  const iframeDepthInfo = await processFrames(tab, framePath, p, activeElement)
  ...
}

processFrames 沿 framePath 逐层在对应 frame 内执行 content 侧的 getIframeElement(通过 window.handleSync({ key: 'getIframeElement', ... })),每层返回的 nextPos 会把 (x, y) 换算到该 frame 的 content 坐标系,实现坐标逐层"减掉 iframe 位置"。随后各层的 iframeContentRect 叠加到目标元素 rect 上,得到相对最顶层文档的绝对坐标,并组装出 iframeXpath(以 /$iframe$ 作为 iframe 层级分隔符)与 iframePathDirs。

content 侧对 iframe 位置的精算在 src/content/element.ts 的 getFrameContentRect:

export function getFrameContentRect(element: HTMLElement) {
  const frameRect = getBoundingClientRect(element)
  const padding = getPadding(element)   // 读取 paddingLeft/Top/Right/Bottom 并乘 devicePixelRatio
  const border = getBorder(element)     // 读取 borderLeft/Top/Right/Bottom 并乘 devicePixelRatio
  const frameContentRect = {
    left: frameRect.left + padding.paddingLeft + border.borderLeft,
    ...
  }
  return frameContentRect
}

即 iframe 可视内容区 = iframe 包围盒扣除 padding 与 border 后的内部区域;getPadding/getBorder 都通过 window.getComputedStyle 读取并乘以 devicePixelRatio,保证高 DPI 屏幕下坐标换算不失真。

5.2 同源 iframe 元素位置统一处理办法

README 说明:同源 iframe 虽然限制更小,但插件仍沿用跨域的同一套方法处理,目的是避免冗余、减少变量、减少出错。也就是说,同源与跨域统一走 parentFrameId 嵌套关系 + 坐标逐层减法 + getFrameContentRect 换算的同一管线,而不是为同源场景另写一套分支逻辑。

5.3 iframe 元素定位处理办法:postMessage 绑定 iframeXpath 与 frameId

处理流程(README 原文要点):

  1. 在 content 中标记当前窗口下的所有 frame 元素;
  2. 通过 iframe.contentWindow.postMessage 把该 iframe 的 xpath 路径传给对应的 iframe;
  3. 对应的 iframe 通过 window.addEventListener('message', function(e) { ... }) 接收 xpath 路径并传给主进程;
  4. 由此绑定 iframe 的 xpath 路径与 iframe 的 id;
  5. 再按照 id 的嵌套关系,得到一个总的 iframe path 全路径;
  6. 通过 iframeXpath 字段即可定位到对应的 iframe 以及 iframe 中的目标元素。

该机制的 content 侧实现集中在 src/content/iframe.ts:

  • tagFrames():遍历当前文档所有 frame 元素(getIFramesElements()),对每个 frame 执行 postToIframe(frame)——通过 frame.contentWindow?.postMessage({ key: 'setCurrentWindowIframeInfo', data: { iframeXpath: directoryXpath(frame), iframeTransform, iframePathDirs } }, '*') 下发自身 xpath;对未加载完成的 frame 还注册 onload 再次下发。当前窗口自身若已是 iframe(window.parent !== window),则向父窗口发送 getCurrentWindowIframeInfo 请求与 bindCurrentWindowIframeInfo 回传;
  • listenMessage(ev):接收 setCurrentWindowIframeInfo 时,把父级传来的 iframeXpath、iframeTransform、iframePathDirs 写入当前 frame 的 currentFrameInfo;
  • requestFrameId():通过 requestFrame() 从主进程获取当前 frame 的 frameId,并回传 bindCurrentWindowIframeInfo 完成绑定;
  • tagFrameId(frameInfo):根据父级下发的 iframeXpath 用 getElementByXPath 反查父文档中的 iframe 元素,并写入 data-astron-frame-id 属性,把 xpath 与 id 在 DOM 上显式关联起来。

在 background 侧,src/background/iframe.ts 的 findFrameByXpath 负责按 /$iframe$ 切分总路径、从根 frame(frameId === 0)开始逐段匹配子 frame:

function findFrameByXpath(frames: FrameDetails[], iframeXpath: string) {
  const segments = iframeXpath.split('/$iframe$').map(s => s.trim()).filter(Boolean)
  ...
  let current: FrameDetails | null = rootFrame
  for (const seg of segments) {
    const next = frames.find(f => f.iframeXpath === seg && f.parentFrameId === current!.frameId)
    ...
    current = next
  }
  return current
}

frameFinder 会优先按 iframeXpath(可视化拾取模式则用 iframePathDirs 拼装)查找 frame,查不到时回退按 URL 匹配;仍失败时,还会向所有 frame 广播 elementLocatorFrameId,由每个 frame 内的 content 判断元素是否属于自己的文档,从而兜底定位目标 frame。

5.4 注意:iframeXpath 与其他元素定位逻辑统一

README 特别提醒:iframeXpath 与其他元素定位逻辑相同,统一查找逻辑,也存在动态性问题。即 iframe 路径本质上也是 XPath,页面上 iframe 的新增、删除、重排,或 iframe 内部 DOM 结构变化,都可能导致 iframeXpath 失效。这与普通元素的 XPath/CSS 选择器动态性问题一致,自动化流程设计时应把 iframe 路径也视为"动态定位策略"的一部分来对待。

六、构建 crx / xpi 包说明

6.1 Chrome:发布到商店 vs 企业策略安装

方案 A:发布 Chrome 插件商店

  • 推荐使用 Chrome Developer Dashboard 发布到 Chrome 插件商店;
  • 注意:Chrome 开发者账户需要收费;
  • 若不上架商店,插件会被 Chrome 浏览器的限制拦截启用,必须通过 chrome://policy 策略写入白名单:
    • Windows:以注册表方式写入 Software\Policies\Google\Chrome\ExtensionInstallAllowlist;
    • Linux:写入 /etc/opt/chrome/policies/managed/policy.json;
  • 策略项为 ExtensionInstallAllowlist,详细说明可查阅 Chrome 企业策略文档中对应策略条目。

方案 B:不发布、本地打包

  1. 打开 Chrome,进入 chrome://extensions/ 页面;
  2. 启用"开发者模式";
  3. 点击"打包扩展程序",浏览扩展程序根目录;
  4. 第一次打包时私钥文件可以不填;
  5. 打包完成后,扩展程序根目录会生成对应的 .crx 文件和 .pem 密钥文件;
  6. .pem 文件在后续更新插件包时必须保留:同一个密钥文件会生成一样的插件 id,用于插件更新时保持 id 不变,避免已安装用户的插件被当作"新扩展"重新安装。

6.2 Firefox:免费开发者账户 + xpi

  • Firefox 可免费自行申请一个开发者账户;
  • 上传打包好的插件 xpi 文件,可以不发布,直接下载 xpi 文件即可安装;
  • Firefox 插件请自行打包,使用自己的开发者账户上传,构建自己的 xpi 文件。

需要说明的是,源码仓库内不包含现成的 crx/xpi 产物,构建脚本(npm run build 及 build:firefox)会产出 dist/ 与 zip 包,crx/xpi 的最终封装需要按上述流程在浏览器侧或开发者账户中完成。

七、从源码到测试:如何进一步深入

若希望深入验证或二次开发上述机制,仓库提供了可继续探索的入口:

  • 单元测试:src/test/ 下有针对 background 与 content 侧的工具测试,如 background.tab.test.js、content.element.test.js、content.inject.test.js;浏览器端集成测试配置见 tests/chrome.vitest.js 与 vitest.browser.config.js;
  • 接口文档:frontend/packages/browser-plugin/API.md 提供了插件对外消息接口的进一步说明;
  • 环境变量:插件通过 Vite loadEnv 读取 VITE_APP_WS_URL(引擎 WebSocket 地址)、VITE_APP_NAME、VITE_FIREFOXID 等,构建前需确保 .env 环境文件配置正确。

结语

本文从 README 出发,结合源码把 Astron RPA 浏览器插件的四块核心能力拆解清楚:一是基于 Vite 双入口与 custom_agent 的多浏览器打包体系;二是以"5 秒悬浮触发 + elementsFromPoint 几何最近距离"为核心的深度搜索;三是用 $shadow$ 分隔符实现多层 Shadow DOM 递归定位;四是借助 parentFrameId 嵌套关系、postMessage 绑定与 iframeXpath 字段完成的跨域/同源 iframe 统一定位。这四块能力共同支撑了插件在复杂网页(遮挡层、Web Component、嵌套 iframe)场景下的稳定元素拾取,也是后续在此基础上扩展更多自动化能力的地基。

登录后查看全文
astron-rpa