Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

GetBrowser Agent Bridge

面向 Agent 的 Firefox 扩展:提取当前浏览界面的所有人眼可见元素(文本 / 图片 / 交互控件),既给出结构化 JSON,也渲染成紧凑的文本描述,供 Agent 感知页面。完整性优先——宁多记、不漏记。操作形态(点击、输入、滚动)在此感知层之上提供,并通过本地 WebSocket 控制通道暴露给外部 Agent。

目录结构

getbrowser/
├── manifest.json          # 扩展清单(Firefox MV2,all_frames 注入每个框架)
├── background.js          # 后台脚本:快捷键、Agent 控制通道(WebSocket 客户端)
├── common/
│   ├── labels.js          # 稳定标号登记表(标号只增不复用,防点错;可插拔依赖)
│   ├── route.js           # 标号 → 框架路由(纯函数,后台 / popup / 测试共用)
│   ├── merge.js           # 多框架快照聚合(纯函数,popup / 后台 / 测试共用)
│   ├── text.js            # 快照文本化渲染器(可插拔 text/json,供 Agent 阅读)
│   ├── layout.js          # 空间化文本渲染器(空格=水平位置、空行=垂直位置,不重叠布局机)
│   └── protocol.mjs       # 控制通道协议文档 + 常量(ESM,供 Agent / 外部进程参考)
├── content/
│   ├── shadow-probe.js    # document_start:记录 closed shadow root 供提取器补采
│   ├── font-decode.js     # 字体混淆反演(自定义字体把假码位渲染成真字时恢复真文本)
│   ├── extract.js         # 核心:单框架内人眼可见元素提取 + 分块 + 动作 + 标注层
│   └── overlay.css        # 标注层样式
├── popup/
│   ├── popup.html/.css/.js  # 工具栏弹窗:聚合 / 分块浏览 / 复制 JSON·文本 / 操作 / 高亮
├── bridge/
│   ├── ws-server.mjs      # 最小 WebSocket server(扩展拨号连接的控制通道)
│   └── mcp-server.mjs     # MCP 桥接:stdio MCP server + 控制通道,暴露 browser_* 工具
└── test/
    ├── unit.mjs           # Node 单测(merge / text / protocol,无浏览器依赖)
    ├── labels.mjs         # 稳定标号自攻防(身份/子标号/复核,无浏览器依赖)
    ├── background.mjs     # 后台接线(伪造扩展 API:路由/校验/scroll,无浏览器依赖)
    ├── labels-firefox.mjs # 真实 Gecko 的标号不变量(BiDi 驱动,headless 可用)
    ├── hover-trusted.mjs  # 真实 Gecko:合成 hover 不触发 :hover,可信 hover 才行
    ├── extension-firefox.mjs # 真实 Firefox 里装真实扩展跑端到端(含「签名包=源码」校验)
    ├── ws-server.mjs      # 最小 WebSocket server 单测(握手/掩码/分片/大帧/ping-close)
    ├── browser.mjs        # 无头 Chromium 端到端测试(提取 → 聚合 → 文本 → 动作)
    ├── mcp.mjs            # MCP 桥接测试(真实 MCP client + 假扩展,无需浏览器)
    ├── control-server.mjs # 交互式 Agent 侧 server(stdin 逐条发 JSON 指令)
    ├── agent-client.mjs   # 真实 Firefox 驱动脚本(open → extract → click/fill)
    ├── agent-ops.mjs      # 真实 Firefox 操作场景(点击导航 / 搜索流 / 选中 / 手势 + 校验)
    ├── screenshot.mjs     # 真实 Firefox 截图 + 多框架捕获验证(诊断用)
    ├── sample.html        # 测试页面(模拟 all_frames + popup 聚合流程)
    ├── frames.html        # 同源 + 跨域 iframe 捕获测试页
    ├── iframe-child.html  # 子框架用例
    └── assets/logo.svg

安装

正式安装(签名 XPI,推荐)

本目录的 getbrowser-0.1.0-signed.xpi 是已通过 AMO 签名的正式包:

  1. 打开 Firefox,访问 about:addons
  2. 右上角齿轮 → 「从文件安装附加组件…」,选择该 .xpi
  3. 工具栏出现扩展图标即安装成功(重启浏览器后依然有效)

也可先卸载再重装以更新版本;升级时无需重新授权权限。

开发调试(临时加载,重启失效)

  1. 打开 about:debugging#/runtime/this-firefox
  2. 「临时载入附加组件」→ 选择本目录的 manifest.json
  3. 或用 npm run firefox(web-ext 自动拉起)

加载本地 file:// 页面做测试时,需在 about:config 开启对应文件访问权限,或用本地 HTTP 服务(见下)。

重新打包 / 签名

npm install
npm run build     # = web-ext build:按 web-ext-config.mjs 忽略 test/ bridge/ 等,得到干净 XPI
npm run sign      # = web-ext sign --channel unlisted:读取 .env 的 AMO_API_KEY / AMO_API_SECRET 提交 AMO 并下载签名 XPI

web-ext-config.mjs 把开发用文件(测试、MCP 桥接、node_modules 等)排除出 XPI,只保留扩展本体。manifest.json 声明了 data_collection_permissions: required: ["websiteContent","browsingActivity"](扩展会把页面内容 / 标签页信息传到用户自行配置的本地控制通道),因此 strict_min_version 为 142.0。

使用

点击工具栏图标打开弹窗,自动提取当前标签页所有框架(主页面 + 各层 iframe,含跨域)的可显示元素:

  • 块大小:每块元素数量(默认 20),修改后自动重新提取
  • 仅视口内:只保留当前视口内的元素
  • 复制 JSON:把聚合后的完整快照复制到剪贴板
  • 复制文本:把同一快照渲染成紧凑文本(见下节),通常比 JSON 小数倍,更适合直接喂给 LLM
  • 标注:在页面上给所有已提取元素画框并显示编号(快捷键 Alt+Shift+E,逐帧下发)
  • 点击弹窗中任意元素行:页面对应元素闪烁高亮;同时选中该元素,可在操作栏执行 点击 / 输入 / 清空 / 选中 / 滚到

能力分类(展示性 vs 可操作)

每个元素都带一个 caps 能力数组 + presentational 标志,回答"这个元素能做什么":

能力 含义 判定依据
click 可点击 原生/ARIA 交互元素(a[href]、button、input、role 交互子集、tabindex/onclick/contenteditable 等)
dblclick 可双击 交互元素、可编辑文本,或显式 ondblclick(双击在文本上=选中词)
longpress 可长按 交互元素,或显式 ontouchstart/onpointerdown
contextmenu 可右键/上下文菜单 交互元素,或显式 oncontextmenu
fill 可输入文本 文本型 input/textarea/contenteditable
choose 可从中选择 <select> 下拉
selecttext 文本可被选中 有可见文本且未被祖先 user-select:none 禁用
  • presentational:true 表示展示性元素:没有可执行动作,Agent 只读取其文本/图片(普通段落、标题、图片等)。
  • click/dblclick/longpress/contextmenu 对交互元素属于「可尝试」的手势能力(事件可被派发,页面是否响应取决于其自身逻辑);fill/choose/selecttext 由控件类型与 CSS 决定,是确定性分类。
  • 文本快照里用单字母码紧凑展示,并在头部给出图例:c=click d=dblclick l=longpress r=contextmenu f=fill o=choose s=selecttext。可用 caps:false 关闭。

文本快照(给 Agent 读)

common/text.js 把快照渲染为「一元素一行、字段按需出现」的文本。相比 JSON,它去掉了 字段名与转义开销,保留 Agent 决策所需的全部信息(编号、标签、语义角色、文字、坐标、链接目标、表单状态、能力分类):

[GetBrowser] 示例页面
url: https://example.com/
viewport: 1440x900  scroll: 0,0
elements: 135  interactive: 40  media: 8  text: 87  frames: 2  chunkSize: 20
caps: c=click d=dblclick l=longpress r=contextmenu f=fill o=choose s=selecttext

## f0 https://example.com/  offset 0,0  n=100  #1.1-1.100
[chunk 0 #1.1-1.20]
#1.1 h1 "欢迎" @20,20 400x40 [s]
#1.2 a "登录" @1200,20 80x30 -> /login [cdlrs]
#1.5 input:text[textbox] "用户名" @20,180 200x28 ph="请输入用户名" editable [cdlrf]
#1.6 input:checkbox @230,180 16x16 checked [cdlr]
#1.8 img alt="示例图片" @20,220 120x60 src=/assets/logo.png offscreen
#1.9 div[button] "更多" @20,300 60x28 [cdlrs]
## f1 https://ads.example/x  offset null  n=35  #f3j5k1p.1…f3j5k1p.35
...

约定:#id 为稳定标号(点分,如 #1.4.2,见下文「稳定标号」);tag 后跟 :inputType 与 [role](默认 role 省略);同源 URL 只保留 path;末尾 [cdlrs] 为能力码。可插拔:GBText.register(name, fn) 注册自定义格式,GBText.render(snap, { format }) 分派。常用选项:format、header、frames、chunks、offscreen、caps、maxText、maxUrl。

空间化文本(format:"spatial")

common/layout.js 是另一种渲染器:把元素按真实坐标铺到字符网格上——前导空格=水平位置(x),空行=垂直位置(y),让纯文本也保留二维版面关系(标题在上、侧栏在右、按钮并排)。

[GetBrowser spatial] 章节测验
url: https://…/doHomeWorkNew…
layout: 8px/col × 16px/row  前导空格=水平位置(x),空行=垂直位置(y);同格冲突时向右/向下让位保证不重叠
frames:
  f0 @0,0 n=… …
  f19327353074 @100,218 n=250 …
  0         1         2         3         4         5
  #1.23 h3 一. 单选题(共4题) [s]
  #1.29 label A [cdlrs] #1.35 a 系统抽样 [cdlrs]
  #1.47 li[radio] A 李克特量表 [cdlrs] #1.51 li[radio] B 语义差异量表 [cdlrs]

布局机保证不重叠、不错位:元素坐标 = 包围盒 + 所在框架在顶层页面的偏移(跨帧对齐);量化为网格后按阅读序放置,同行水平冲突时向右让位(保持行=垂直位置),放不下则下移;过大的垂直空隙折叠为 ⋮ (+N rows)。选项:colW(8)、rowH(16)、maxCols(200)、maxText(40)、maxBlankRows(3)、rulers、header、offscreen。经 MCP 时用 browser_extract { format:"spatial" }。

稳定标号(防止点错元素)

页面是活的:悬浮会弹出菜单、列表会重排、组件会重渲染、iframe 里有独立的小世界。 如果标号按「本次提取的行号」生成,上一刻的 #12 在下一刻可能已经是另一个元素, Agent 拿着旧标号去点就会点错。GetBrowser 因此把标号设计成元素身份,而不是行号:

  • 只增不复用:标号与 DOM 节点身份绑定(WeakMap)。同一个节点永远得到同一标号, 与它的位置、文本、是否在视口内无关;节点消失后,它的标号也永远不会发给别的元素。
  • 新元素拿新子标号:新节点分配 父标号.序号,父标号取「最近的已标号祖先」 (跨开放/闭合 Shadow DOM、同源子帧都能向上找到);没有这样的祖先时挂在根下 (1.序号)。序号单调递增,悬浮菜单展开→收起→再展开,每次都是新号。
  • 前缀即位置:同一容器下的兄弟元素共享前缀(1.4.7 / 1.4.8),层级越近前缀 重合越多。看前缀就能判断「挨着谁、在哪个容器里」,而不是靠坐标记忆。
  • 跨框架唯一:子框架的标号加帧前缀 f<frameId 的 36 进制>.(如 f3j5k1p.3.2), 主框架保持 1.x;因此「是不是嵌套网页」不影响标号的一一对应。前缀只取决于该框架 文档的身份,文档存活期间恒定(Firefox 的子框架 id 是 17179869185 这类大数, 直接用会更长且易被误读,故用 36 进制)。
  • 失败优于错点:执行动作前逐项复核——文档身份 docId(导航/重载后失效)、 身份键 expect(见下)、标号仍指向同一节点、元素仍可见。任一不符就返回 ok:false(unknown or stale elementId / element left the document / refusing to act: ...),不会退回猜测。
  • 校验基准是「你看到的那份快照」,不是「最近一次提取」:快照每条记录带身份键 fk(tag / role / 关键属性 / 归一化文本);动作时代理把该记录的 fk 作为 expect 下发,内容脚本用「此刻」重算并逐项比较。这样别的客户端(例如打开 popup 触发的自动提取)不会替已经变质的元素背书——这是实测抓到的一次真实错点路径。
  • 状态变化要靠「确认」而不是「猜测」:文案随状态变化(复制 → 已复制)时, 重新提取会拿到新的 fk,随后的动作即正常;而「提取之后、动作之前」的变化一律 拒绝。关键属性按「记录时 ∪ 现在」的键比较,<a> 后加 href(纯文本变成可导航 链接)同样会被拒绝。

典型时序(悬浮菜单):

提取 → #1.4 a "菜单"          # 悬浮前
悬浮 → #1.4.1 a "子项 A"      # 新节点 → 新子标号(与旧标号集合不相交)
       #1.4.2 a "子项 B"
移开 → 菜单节点离开文档;#1.4.1/#1.4.2 动作失败(不存在),#1.4 仍是 #1.4
再悬浮 → #1.4.3 a "子项 A"    # 新 DOM 节点 → 新标号,绝不复用 #1.4.1

可测试的契约见 test/labels.mjs(Node,14 项自攻防)、test/unit.mjs 的 route 用例(标号解析 + 身份键透传)、test/background.mjs(伪造扩展 API 验证接线与 expect 下发)与 test/browser.mjs 的「稳定标号」用例(真实 DOM:悬浮菜单两种 实现、列表重排、文案变化、属性变化、隐藏/显示、改造成别的东西、第三方提取背书)。

两类「同一位置」要区分开:同一节点重新显示(display:none 悬浮菜单)→ 复用 原标号;节点被销毁后重建(React 重渲染、菜单每次重建)→ 新标号。判据是 DOM 节点身份,不是坐标或文案。

设计取舍:标号跟随节点身份而非「看起来相同的槽位」。框架整体重渲染(React 重建 DOM)后,即使界面一模一样,元素也会拿到新标号——这是有意的:新节点可能有 新的监听器/状态,宁可让 Agent 重新提取,也不把旧标号映射到它上面。

视频 / 音频控制(含倍速、拖动进度)

不要靠坐标点播放器的控制条。 实测(智慧树播放器):

  • 原生 <video controls> 的控制条在 UA 层,DOM 里根本没有那些按钮;
  • video.js 一类的控制条是 opacity:0 的覆盖层,且常被包在 <a> 里—— 合成 click 冒泡会触发导航(测试中页面被跳走两次)。

正确做法是直接操作媒体元素的确定性属性,动作后回读状态:

动作 参数 回读
state — paused / currentTime / duration / playbackRate / muted / volume / ended
play / pause — 同上(play() 被自动播放策略拒绝时 ok:false 并说明原因)
seek {to:30} 秒 | {fraction:0.5} 按比例 | {by:-10} 相对 currentTime
rate {rate:2}(0 < rate ≤ 16) playbackRate(浏览器夹过值会返回 ok:false)

元素可以是 <video>/<audio> 本身,也可以是包含它们的任意容器(video.js 的 .vjs-* 包装层),因此快照里哪个节点都能用。

拖动进度条 / 滑块(drag)

seek 是操作媒体属性的确定性路径;如果非要走站点自己的控制条(例如它维护额外 状态),才用 drag:

browser_act { action:"drag", elementId:"1.107",
              options:{ fx:0.26, toFx:0.60, steps:12 } }
  • 起点 fx/fy、终点 toFx/toFy 都是元素内相对位置(默认 0.5/0.5,终点默认等于 起点);中间按 steps 分段(默认 6)。
  • 默认 DOM 后端派发合成 pointerdown → pointermove(buttons=1) → pointerup; input:"bidi" 时是可信指针(真实命中测试,站点校验 isTrusted 也能过)。
  • 必须从滑块(handle/圆点)上按下才进入拖动:实测播放器只有按在圆点上才跟随 pointermove,按在轨道其它位置只在按下瞬间定位一次(等于单击 seek)。所以起点 要取「圆点中心的横向比例」,而不是轨道上随便一点;圆点的位置可由快照里该节点的 几何(bb)或当前进度换算。
  • 拖动期间站点可能只更新预览、到 pointerup 才真正 currentTime 跳变,断言要看 释放之后的回读。

可信悬浮:唯一能触发 CSS :hover 的悬浮

hover 动作只是 dispatchEvent(new MouseEvent('mouseover'))——不会更新浏览器的 命中测试状态,所以 CSS :hover 永远是 false。实测对照(test/hover-trusted.mjs, 真实 Gecko):

方式 el.matches(':hover') #wrap:hover #bar 显形 JS mouseover 监听
合成 hover false 仍是 opacity:0 触发
hoverTrusted(BiDi pointerMove) true opacity:1 触发

hoverTrusted 走 WebDriver BiDi 注入 isTrusted=true 的真实指针移动(不移动系统鼠标), 参数 {fx, fy} 指定元素内相对位置(默认中心)、{steps} 分段移动(默认 4,连续 mousemove 才能重置「控制条自动收起」定时器)、{settle} 到达后保持毫秒数。 需要调试模式(browser_debug {on:true})。

结论:要「悬浮唤醒」就必须可信指针;只是想拿到悬浮后才出现的元素,用下面的 includeHidden 更省事、也不会有时序问题。

合成 vs 可信:怎么选

控件形态 合成(默认 DOM) 可信(hoverTrusted + BiDi)
始终可见的按钮/进度条/滑块 ✅ 可用(clickAt 按比例点) ✅ 可用
仅 :hover 显形的控制条 ❌ 看不到(opacity 0 被排除);includeHidden 能拿到标号但动作被拒(is no longer visible) ✅ 唯一可行
页面校验 isTrusted ❌ 被丢弃 ✅ 通过
需要真实指针轨迹/命中测试 ❌ ✅

代价:可信路径要开调试模式(browser_debug {on:true},需 --remote-debugging-port 启动 Firefox),且会真实的操作页面(真实站点上会留下使用痕迹)。

红蓝对抗:人机区分信号的边界

test/fixtures/risk-gate.html(蓝队)把「点击 / 拖动 / 输入 / 悬浮后点菜单」串成四步任务, 客户端按加权信号打分,服务端再验一次性令牌、蜜罐、节奏签名。test/hostile-risk.mjs 用三种打法跑同一任务,测出来的边界(数字随运行略有波动,判定不变):

信号 正常模式(DOM 合成) 可信·默认 可信·加固
输入事件可信 isTrusted ✗ ✓ ✓
点击时 :hover / 按下时 :active ✗ ✗ ✓ ✓ ✓ ✓
指针 movementX/Y ✗ ✓ ✓
拖动轨迹非完美直线 ✗ ✗ ✓
点击前停留、按键节奏 ✗ ✗ ✓
navigator.webdriver ✗ ✗ ✗
  • 浏览器强制(合成事件永远拿不到):isTrusted、:hover、:active、movementX/Y。 DOM 后端还因此做不到「悬浮才出现的菜单」——CSS :hover 不成立,菜单根本不渲染。
  • 只是行为习惯:拖动轨迹是否笔直、按下到移动的停顿、按键间隔与抖动、是否逐字符输入。 这些客户端完全可控,drag 的 curve/jitter/ease、click 的 approach/dwell、 fill 的 cadence 就是为此准备的;但默认参数仍然会被识别,必须显式开启。
  • 客户端解决不了:navigator.webdriver、服务端的历史/频率/一票否决(蜜罐、令牌重放、 重复行为签名)。测试脚本明确不做指纹伪装——那是伪装环境,不是提升可靠性。

用途是能力边界而不是「绕过术」:知道哪些差异是强制的,才能判断一次失败该修插件、 该改参数,还是本来就该交给人工/服务端规则。

直接识别隐藏元素(includeHidden)

悬浮才出现的控制条、折叠菜单、未激活的 Tab 面板——它们的 DOM 通常一开始就在, 只是 CSS 隐藏。browser_extract {includeHidden:true} 会把隐藏但有语义的元素也列出来:

  • 收录条件:交互元素 / 媒体 / 有文本 / 可编辑 / 有 role / 背景图 / 伪元素; 纯布局容器不列(避免把整棵隐藏 DOM 吐出来),默认上限 300 条 (hiddenLimit),超出计入 snapshot.hidden.truncated。
  • 记录带 hidden:true、inViewport:false;文本渲染为 hidden offscreen。
  • 标号现在就分配好了:等它显示时,同一节点仍是同一标号——彻底消除 「hover 唤醒前后编号变了」的问题(如果站点是 hover 时 innerHTML 新建节点, 那必然是新标号,任何方案都改不了)。
  • 隐藏期间动作一律拒绝(element ... is no longer visible),显示后即可操作。

自定义控件(无 role 的 div):靠 cursor:pointer 发现

进度条、滑块、自制开关、事件委托型「按钮」常常是没有 role / tabindex / onclick 的普通 <div>,人眼判断它能点的唯一线索是 cursor:pointer。不识别这类, Agent 就会「看得到却点不到」——实测播放器进度条就完全不在快照里。

判定规则(isInteractive 末尾):

  • 自身 cursor:pointer,且直接父级不是 pointer → 视为「指针区域的根」,标为可交互;
  • 父级也是 pointer → 说明是继承来的,不算(cursor 是继承属性,不这样剪枝, 一个 cursor:pointer 容器会把整棵子树都变成「可交互」);
  • 开销实测 +3%(6000 元素 491ms → 505ms)。

因此 #progress 这类元素现在会以 div @x,y WxH [cdlrs] 出现,配合 clickAt 按比例点击即可拖动进度。注意它仍是一个无文本的 div,语义上要靠「宽而扁」的 形状 + clickAt 来识别。

按相对位置点击(clickAt)

进度条、滑块、画布、地图这类「同一个元素、不同位置不同语义」的控件:

{ "action": "clickAt", "elementId": "1.42", "options": { "fx": 0.3, "fy": 0.5 } }

fx/fy ∈ [0,1],越界夹到边界。返回值含 at: [x, y] 便于核对。 注意:clickAt 内部不用 element.click()——它派发的 click 坐标恒为 (0,0), 会把算好的位置抹掉(进度条会跳回开头);改为手动派发带坐标的 MouseEvent('click'), 默认行为(导航、checkbox 切换)仍然生效。

快照 JSON 结构

复制 JSON 与协议 extract(默认格式)返回同一结构:

{
  "url": "https://example.com/",
  "title": "Example",
  "capturedAt": 1760000000000,
  "viewport": { "width": 1440, "height": 900 },
  "scroll": { "x": 0, "y": 0 },
  "chunkSize": 20,
  "total": 135,
  "counts": { "interactive": 40, "media": 8, "text": 87 },
  "frames": [                       // 参与聚合的框架元信息
    { "frameId": 0, "parentFrameId": -1, "url": "...", "offset": [0, 0], "total": 100 },
    { "frameId": 1, "parentFrameId": 0,  "url": "(跨域 iframe)", "offset": null, "total": 35 }
  ],
  "chunks": [
    {
      "chunkId": 0,
      "range": ["1.1", "1.20"],   // 首元素…末元素标号(不是数字区间)
      "count": 20,
      "elements": [
        {
          "id": "1.4.2",            // 稳定标号(跨提取不变、永不复用;见「稳定标号」)
          "fk": "[\"button\",\"\",\"提交\",[[\"id\",\"submit\"]]]",
                                    // 身份键:动作时由扩展回传做「与本快照一致」复核
          "frameId": 0,             // 所在框架
          "tag": "button",
          "role": "button",
          "text": "登录",
          "interactive": true,
          "presentational": false,  // 纯展示元素为 true
          "caps": ["click", "dblclick", "longpress", "contextmenu", "selecttext"],
          "bb": [120, 32, 48, 20],  // 所在框架视口坐标 [x, y, w, h]
          "inViewport": true
          // 帧内标号:"lid": "1.4.2"(动作路由用;非主框架的 id 会加帧前缀 f<frameId 36进制>.)
          // 链接:"href";输入框:"inputType/value/placeholder/checked/disabled";可编辑:"editable"
          // 背景图:"bg": ["url", ...];伪元素:"pseudo": "★"
          // 图片:"src/alt/naturalSize";iframe:"src";媒体:"poster/controls";下拉:"optionCount"
        }
      ]
    }
  ]
}

帧偏移 offset 是该框架原点在顶层页面坐标系中的位置(同源链逐级累加;祖先跨域时为 null)。需要顶层页面绝对坐标时,用 offset + bb 换算。

提取规则要点

  • 可见性:display:none、visibility:hidden/collapse、opacity:0(含祖先叠加)、零尺寸、content-visibility:hidden、aria-hidden、装饰图(alt="")排除;视口外元素保留并标记 inViewport:false。判定按祖先链缓存,跨开放 Shadow DOM。
  • 文本按块归属:内联元素(display: inline/contents/ruby)中的文本向上合并到最近的块级祖先或交互元素,<p>文本 <a>链接</a></p> 产出 2 条记录;SVG/MathML 内的文本以元素自身为归属,不向外层 HTML 攀爬。
  • 无障碍名称(近似 accname):交互元素的名称优先取 aria-labelledby / aria-label / 关联 <label> / input 的 value·alt / 内部 <img alt>,再退回可见文本,最后 title;由此纯图标按钮(✕、<img alt>)也能被正确描述。
  • 交互识别与能力分类:a[href]、表单控件、role 交互子集、tabindex/onclick/contenteditable 等识别为可点击;再据此标注 caps(click/dblclick/longpress/contextmenu/fill/choose/selecttext)与 presentational,见上文「能力分类」。
  • 媒体去重:按钮/链接内部的图标,若宿主已有可见文本或可访问名称则不单独记录。
  • 分块:聚合后按快照顺序每 chunkSize 块切块,主框架元素在前,子框架内容紧随其后(标号不因分块/排序改变)。

控制通道(外部 Agent)

扩展作为 WebSocket 客户端 连接 Agent 提供的 server(默认 ws://127.0.0.1:8765),断线指数退避重连;在 popup 控制面板开启/配置。协议详见 common/protocol.mjs,要点:

  • ping / tabs / open / overlay / extract / act / screenshot

  • extract 支持 options.format = "json"(默认)| "text";text 时返回 { format:"text", text }

  • act 的 elementId 用快照里的稳定标号(如 1.4.2)。扩展依据最近一次 extract 的快照解析成「frameId + 帧内标号 + 文档身份 docId」并路由;找不到即失败,绝不退回按数字猜帧内编号。scroll 动作不需要元素

  • act 动作集合以 common/protocol.mjs 的 ACTION_SPECS 为单一事实来源: 下面的表、MCP 的 action 枚举、browser_act 工具描述里的动作表、各输入后端的 能力判断(backends: dom|bidi)全部由它派生。新增/修改动作只改一处, 单测会断言枚举与表格不漂移。

    action | needs an element? | backends | options | returns | meaning
    
    动作 需要元素 后端 要点
    click / dblclick 是 dom,bidi 完整 pointer/mouse 手势(含坐标),click 适配在 mousedown 上提交的控件
    contextmenu 是 dom 右键菜单事件
    longpress 是 dom 触摸式长按(约 600ms 后释放)
    clickAt 是 dom 元素内相对位置点击(fx/fy),进度条/画布用
    drag 是 dom,bidi 按下—移动—释放(fx/fy→toFx/toFy,steps);拖动滑块必须从 handle 起手
    fill / clear 是 dom,bidi 填写/清空;bidi 可进富文本编辑器,支持 cadence 逐字符节奏
    select 是 dom 按 value 或可见文本 text 选 <option>
    submit 是 dom 提交所属 <form>("回车"路径)
    selectText 是 dom 选中元素文本并回传
    focus 是 dom,bidi 聚焦
    hover 是 dom 合成悬浮,不触发 CSS :hover
    hoverTrusted 是 bidi 唯一能触发 :hover 的悬浮(需调试模式)
    scrollIntoView 是 dom 滚入视口
    locate 是 dom 只读:滚入顶层视口并返回 rect/center(可信输入用)
    scroll 否 dom 页面滚动(direction/amount)
    play/pause/seek/rate/state 是 dom 媒体动作,作用于 <video>/<audio> 或包含它的容器,均回读 media

    失败时返回的不只是错误文本,还有机器可读的 code(如 STALE_LABEL、 IDENTITY_CHANGED、NOT_VISIBLE)以及对应的「下一步」建议(ERROR_HINTS)。 MCP 层把建议渲染成错误文本的第二行:

    unknown or stale elementId 9.9: no such element in this document (re-extract)
    next: call browser_extract again, then use the NEW elementId (ids are never reused for another element)
    

    这样 Agent 的重试路径是确定的(重新提取 / 换元素 / 用 includeHidden), 而不是原样重试同一个调用。

  • click 会做有效目标路由:按 HTML 规范,点击 <label> 内的「交互内容后代」(如选项文字里的 <a href="javascript:void(0)">)不会激活关联控件,直接点行容器(li)也不会。为符合 Agent 的「选中该选项」意图,click 会把点击路由到能真正激活控件的元素——label 后代/行容器 → 关联的 input/select/textarea(或 label);真实链接(可导航 href)保持链接语义,不被劫持。返回值含 routedTo 便于观测

  • 主动推送 gb:tab 事件(标签页 activated / updated / removed)

演示 server:node test/control-server.mjs,在 popup 开启控制通道后从 stdin 逐行发 JSON 指令。

MCP 接入(让 LLM Agent 直接操作浏览器)

Firefox 本身不是 MCP 服务器(它无法监听 stdio、也不该由 Host 启动)。正确做法是加一层 MCP 桥接进程 bridge/mcp-server.mjs,它同时扮演两个角色:

MCP Host (opencode / Claude Desktop / Cursor)
   │  stdio / MCP 工具调用
   ▼
bridge/mcp-server.mjs ──ws://127.0.0.1:8765──▶ 扩展 ──▶ 页面
  • 对 Host:stdio 上的 MCP server,暴露 browser_* 工具
  • 对扩展:本地 WebSocket server,等扩展拨号连上(复用控制通道协议)

使用前提(已在 MCP instructions 与每个工具的 description 中标注):这些工具会驱动用户真实的、已登录的 Firefox 会话,因此 仅在用户明确要求操作浏览器时才可使用(例如"打开这个页面""点一下…""看看页面上有什么")。Agent 不得主动、试探性或"顺手"调用;用户没有明确要求时,应改用其它信息源或先询问。

工具一览(面向 Agent 的 title/description/instructions 均为英文,便于 LLM 直接消费)

工具 作用
browser_connect 启动控制通道并等待扩展连接(桥接进程启动时不自动监听;waitMs 控制等待时长,缺省 GB_GRACE_MS)
browser_disconnect 停止监听、断开扩展并释放端口(桥接进程存活;可再次 browser_connect)
browser_status 检查监听与连接状态(connected + listening + 当前 endpoint + 当前输入模式 input + bidiEndpoint),无副作用
browser_listen 启动监听或重绑控制通道端口(缺省 8765):跟随浏览器 popup 改的端口,或端口被占时换端口
browser_debug 需用户显式要求:以调试模式打开/连接浏览器(必要时启动 Firefox)并改用可信输入;on:false 退回 DOM。其余动作无法用 BiDi 完成的仍回落 DOM
browser_eval 受控逃生口,仅调试模式可用(browser_debug on 后):在页面自身 JS realm 执行任意代码(return 返回值、可 await、可覆盖页面函数/对象——脚本能做的一切),结果 JSON 化返回;页面异常可读且不重建会话。用于标准动作表达不了的站点怪癖(如提交前调用编辑器自己的 sync())
browser_view 记录用户查看偏好(text/image/text+image/image+text);纯提示,不改变任一通道返回
browser_extract 提取页面可见元素(纯文本通道:format:"text" 紧凑文本 / "spatial" 二维排布 / "json" 完整快照)
browser_act 操作元素。动作、参数与返回值见上文 ACTION_SPECS 表(工具描述里也内嵌了同一张表);input:"dom" 合成事件 / input:"bidi" 走 WebDriver BiDi 可信输入(富文本编辑器场景);省略 input 时用当前默认模式
browser_tabs 列出标签页(返回的 id 可作其它工具的 tabId)
browser_open 打开/导航网址
browser_overlay 开关页面标注层
browser_screenshot 纯图片通道:截当前视口并直接以内联图像返回(模型即时可见,无需再读文件);传 savePath 才额外落盘。与文本通道相互独立

opencode:把示例 opencode.json.example 拷到你的配置里(项目级 ./opencode.json 或全局 ~/.config/opencode/opencode.json),在 mcp 段加入:

{
  "mcp": {
    "getbrowser": {
      "type": "local",
      "command": ["node", "/home/life/Work/getbrowser/bridge/mcp-server.mjs"],
      "enabled": true,
      "environment": { "GB_PORT": "8765" }
    }
  }
}

保存后需退出并重启 opencode 才会加载新的 MCP 配置。

Claude Desktop(claude_desktop_config.json):

{
  "mcpServers": {
    "getbrowser": {
      "command": "node",
      "args": ["/home/life/Work/getbrowser/bridge/mcp-server.mjs"],
      "env": { "GB_PORT": "8765" }
    }
  }
}

其余 Host 同理:都是「用 node bridge/mcp-server.mjs 启动一个 stdio MCP server」。

使用流程:① 加载扩展并开启控制通道;② Host 启动桥接进程(此进程只建立 stdio,不自动监听); ③ Agent 调 browser_connect 启动监听并等待扩展接入(GB_GRACE_MS,默认 30s);④ Agent 用 browser_extract 感知页面拿到元素编号,再 browser_act 操作,随后重新 browser_extract 获取新状态; ⑤ 结束时调 browser_disconnect 释放端口。 需要目视核对时可先 browser_overlay 开标注层,再用 browser_screenshot(图像直接内联返回)。 感知分为两个相互独立的纯通道:browser_extract(纯文本)与 browser_screenshot(纯图像)。 用户可用 browser_view 声明偏好(text/image/text+image/image+text,仅作提示、不改变返回); 需要补充通道时由模型再调另一个工具。 等待只发生在 browser_connect:其余工具在未连接时立即返回可读错误,不会静默阻塞。

npm run mcp                              # 手动启动桥接(默认即 stdio,供 Host 拉起)
GB_PORT=9000 npm run mcp                 # 换端口(需与扩展控制面板一致)

MCP 部署副本与版本同步(重要)

Host 的 MCP 配置可以指向仓库,也可以指向一份部署副本(例如 ~/.config/opencode/getbrowser/)。副本没有版本管理,升级仓库后容易落后,而落后的 后果不是「少个新功能」而是协议不兼容:0.4.0 起 elementId 是点分标号字符串 ("1.4.2"),旧副本的 schema 是 z.number().int(),会在 MCP 层直接拒绝 (expected number, received string,看起来像扩展坏了)。

npm run check:mcp     # 检查副本是否落后(落后则退出码 1)
npm run sync:mcp      # 同步 bridge/*.mjs + common/protocol.mjs 到副本
npm run sync:mcp -- /path/to/copy     # 自定义目标(或用 GB_MCP_DIR)
  • 同步只覆盖 MCP 进程真正加载的文件,不动 node_modules,也不碰扩展本体 (扩展走 XPI 安装)。
  • 同步后必须重启 Host:MCP 进程在 Host 启动时创建,运行中的会话仍持有旧的 schema 与工具描述。
  • 想验证「副本的行为与仓库一致」:GB_MCP_SERVER=~/.config/opencode/getbrowser/bridge/mcp-server.mjs npm run test:mcp。
  • 彻底避免漂移:把 Host 配置直接指向仓库路径(bridge/mcp-server.mjs),只有一个源。

端口规则与多实例:连接方向是「扩展 → 桥接」,浏览器侧 popup 配置是锚点。

  • GB_PORT(默认 8765)只在桥接启动时读取;直到 Agent 调 browser_connect / browser_listen 才开始监听。运行中由 browser_listen { port } 重绑(缺省仍是 8765),扩展按 1–30s 退避自动重连到新端口。
  • 端口被占(两个 opencode 抢 8765):桥接不崩溃——stdio 照常就绪, browser_connect / browser_listen 返回可读的「端口已被占用」提示,可换端口后重试。
  • 多组「opencode × Firefox」用端口分片:A 组 8765 / B 组 8766(Firefox 需各自 profile, firefox -P profB --no-remote;扩展的控制通道设置按 profile 隔离)。

安全:控制通道目前无鉴权,本机任意进程都能连上并驱动浏览器。对外发布前应加 token。

可信输入后端(调试模式)— 富文本编辑器填写

普通表单用默认的 DOM 合成事件即可。但富文本编辑器(超星的 UEditor 等)只跟随 可信输入更新其内部模型:合成事件虽然能把文字塞进 DOM(看着填进去了),编辑器 模型却仍为空,失焦/提交时按模型重渲染,内容就被清零。

调试模式是显式开关:只有用户明确要求「以调试模式打开浏览器」时才调用 browser_debug,否则一律走普通 DOM:

browser_debug { on:true }                       # 必要时启动 Firefox 并开调试端口,之后默认用可信输入
browser_act   { action:"fill", elementId:N, value:"…" }   # 无需再传 input,默认即 bidi
browser_debug { on:false }                      # 退回普通 DOM

也可以不切默认、只对单次调用使用:browser_act { …, input:"bidi" }。

调试模式通过 WebDriver BiDi 在浏览器进程内注入 isTrusted=true 的真实指针/键盘 事件(不移动系统鼠标),走编辑器自身的输入管线,模型得以更新。

  • browser_debug { on:true } 的行为:若调试端点已就绪则直接连接;否则在 Firefox 未运行 时以 --remote-debugging-port=<port> 启动它(默认端口 9222,可用 GB_BIDI_PORT 覆盖, GB_FIREFOX 指定二进制,端点 ws://127.0.0.1:<port>/session)。若 Firefox 正在运行且未 指定 profile,会明确报错(同一 profile 再次启动只会转发给现有实例)——请先完全退出 Firefox,或传 profile 用一个独立 profile 与之并存。
  • 后端选择:dom / bidi。bidi 仅覆盖输入类动作(click/dblclick/focus/fill/clear), 其余动作(select/submit/scroll/…)自动回落到 dom,并在结果中以 backend:"dom" 标明。
  • 工作方式:扩展的 locate 动作把元素滚入顶层视口并返回其顶层视口坐标(含跨 iframe 的内层 编辑器坐标),桥接进程据此用 BiDi 先点入、再逐字符可信输入,并回读实际写入内容。 也可用 npm run firefox:debug 手动拉起(会临时加载当前源码)。
  • 限制:Firefox 每个浏览器只允许一个 BiDi 会话——同一时间只能有一个自动化客户端连接该调试 端口;会话会在断开时显式 session.end 释放。跨源祖先的框架无法计算顶层坐标,会明确报错。 可信键盘在 headless 下无法输入 contenteditable,请用可见窗口。
  • 架构:bridge/input-backend.mjs(接口与后端注册)、bridge/input-dom.mjs、 bridge/input-bidi.mjs、bridge/input-mock.mjs(测试替身);BiDi 协议封装见 bridge/bidi-client.mjs,调试模式启动/探测见 bridge/browser-debug.mjs。
  • 逃生口:标准动作覆盖不了的站点自身缺陷(例如提交时序列化隐藏 textarea、页面却从不把 富文本编辑器内容同步进去),在调试模式下用 browser_eval 执行一小段页面 JS 补救 (如 UE.getEditor(id).sync());也可走站点自带的「保存草稿 → 提交」路径。 该工具按设计不加能力约束——页面脚本能做的一切(含覆盖站点函数)都允许, 仅以「调试模式需显式开启」作为闸门。

本地验证

npm install          # 安装依赖(扩展本身零运行时依赖;playwright/web-ext 仅开发用)

npm test             # = test:unit + test:labels + test:background + test:input + test:launch + test:ws + test:layout + test:browser + test:hostile + test:mcp
npm run test:unit    # Node:merge / route / text / spatial,38 项断言
npm run test:labels  # 稳定标号自攻防:身份/子标号/复核,14 项(无需浏览器)
npm run test:background # 后台接线:路由/校验/scroll/导航失效,8 项(伪造扩展 API)
npm run test:input   # 输入后端:BiDi 客户端 / 后端编排 / 会话生命周期 / 错误透传 / 分片,29 项(无需浏览器)
npm run test:launch  # 调试模式启动器:就绪/运行中报错/启动/profile/spawn 错误,10 项(无需浏览器)
npm run test:ws      # 最小 WebSocket server:握手/掩码/分片/大帧/ping-close,13 项(无需浏览器)
npm run test:layout  # 自攻防:空间化布局机的不变量与健壮性,18 项
npm run test:browser # 无头 Chromium:加载 test/sample.html 做 45 项端到端断言(稳定标号 + includeHidden + clickAt + 媒体动作)
npm run test:labels-bidi  # 真实 Gecko(BiDi):标号不变量 10 项;端点不可达则跳过
npm run test:extension    # 真实 Firefox + 真实扩展(web-ext 临时安装):打包/沙箱/控制通道/iframe 13 项
npm run test:hover-bidi   # 真实 Gecko:合成 hover vs 可信 hover 对 CSS :hover 的差异,8 项
npm run test:player-bidi  # 真实 Gecko:可信指针驱动播放器控制条(含进度条按住拖动),12 项
npm run test:hostile # 自建红队:test/hostile.html 对抗已知反爬手法,56 项判定
npm run test:hostile-risk  # 红蓝对抗:行为闸门页 vs 正常模式/默认可信/加固可信,8 项判定(需空白 Firefox 实例)
npm run test:mcp     # MCP 桥接:真实 MCP client + 假扩展,61 项断言(生命周期/转发/校验/标号 schema/bidi 分支,无需浏览器)
npm run test:bidi    # 可信输入 E2E(需 Firefox --remote-debugging-port,非 headless);端点不可达时跳过
npm run test:hostile-input  # 输入攻防:DOM 合成 vs BiDi 可信输入,判定哪些防御被突破(需调试 Firefox)

test/browser.mjs 自动探测 ~/.cache/ms-playwright 下的 Chromium(可用 GB_CHROMIUM=/path/to/chrome 覆盖),验证:多框架聚合、内联合并、无障碍名称、表单状态、图片/装饰图去重、SVG/MathML、背景图、伪元素、隐藏元素(含祖先 opacity:0 与 content-visibility:hidden)、视口过滤、GB.act 动作、文本渲染器。设 GB_DUMP=1 可打印文本快照。若只想快速核对,也可用 python3 -m http.server 打开 test/sample.html,控制台查看 window.__GB_TEST / __GB_TEST_TEXT / __GB_ACT_RESULTS。

在真实 Firefox 上试跑(真实网页)

# 1) 用 web-ext 把你的 Firefox 以「临时加载」方式拉起本扩展
npm run firefox                       # = web-ext run --source-dir . --firefox /usr/bin/firefox
# 2) 点工具栏图标 → popup 勾选「控制通道」(host 127.0.0.1:8765)
# 3) 另开终端,运行脚本化 Agent:open 真实站点 → 提取文本 → 可选 click/fill
npm run agent -- --urls "https://en.wikipedia.org/wiki/Firefox,https://news.ycombinator.com"
npm run agent -- --urls "https://duckduckgo.com/" --fill-text "hello" --click-text "Search"
npm run agent -- --urls "https://example.com/" --click-text "Learn more"   # 验证点击导航
# 跑一组真实操作场景(点击导航 / 搜索流 / 文本选中 / 手势),逐项校验:
npm run agent:ops                       # 全部场景
npm run agent:ops -- --scenario ddg-search --list
# 截图 + 多框架捕获验证(同源/跨域 iframe 是否都进来、截图与标注层比对):
npm run shot                            # 对当前活动标签页
npm run shot -- --url http://127.0.0.1:8123/test/frames.html --out /tmp/opencode
# 交互式逐条发指令(stdin JSON):
npm run control-server

test/agent-client.mjs 参数:--urls a,b(--url 别名)、--click-text S、--fill-text S、--print N、--out FILE、--wait MS、--json、--events、--keep。它会在提取后打印文本快照,并校验 fill 值进入新快照、click 后 URL 是否导航。--print 控制终端行数,完整内容写入 --out。

npm run firefox 默认使用系统 /usr/bin/firefox;换发行版/路径可改脚本或直接调用 web-ext run -f <可执行文件>。临时加载的扩展在 Firefox 退出后失效,重跑即可。扩展本身仍是零运行时依赖,web-ext / playwright 仅为开发工具。

剩余盲区(平台限制 / 后续路线)

  • closed Shadow DOM:经 content/shadow-probe.js(document_start 注入)包装 attachShadow 旁路记录 root,closed 子树可提取、可操作;探针不改 mode、不影响页面行为。站点若在探针之前自行创建 shadow root(极少见)才会漏采
  • 动态 about:blank / srcdoc 同源子帧:这类帧(如超星填空题的按需编辑器)可能拿不到独立内容脚本;父帧在遍历时检测其同源子帧未打就绪标记(data-gb-frame)时,直接进入该子文档补采,并把坐标加上 iframe 偏移、归属父帧,因此补采到的元素同样可被 fill/click 操作
  • 填空/编辑器宿主:可见空框内含「隐藏编辑器」(display:none 的 textarea/contenteditable,或同源 iframe 里的富文本 body,如超星 UEditor 填空)时,其最近的「可见且自身无文本」祖先会被标记为 editorHost(editable:true、caps 含 fill,文本快照显示 editor);对宿主执行 fill 会路由到内部真正的编辑器(iframe 富文本 > light DOM contenteditable > textarea),contenteditable 优先走 execCommand('insertText') 以让富文本编辑器同步内部模型
  • 字体混淆:content/font-decode.js 做字形反演——站点用自定义 @font-face 把假码位渲染成真字时(DOM 文本=密文),把罕见汉字用元素字体画到 canvas,与 GB2312 常用字表(运行时 GBK 枚举,6763 字)在 sans/serif 参考字体下的 12x12 灰度向量做单位化 L2 比对,最优且显著优于次优者胜出;按字体缓存映射。快照头部输出 font-decoded: N chars。无自定义字体的页面走零开销快速路径;比对在无 @font-face 页面永不触发
  • canvas / 视频的像素内容:只记录元素本身,像素需要截图/OCR 路线
  • 白底白字 / 同色高对比伪装:需解析背景绘制(背景图/渐变/层叠)才能判定,当前会捕获——已知边界
  • 遮挡命中测试:不做——按需求「人眼可见即提取,不判脏」
  • srcdoc / 特殊 about:blank 帧:match_about_blank + match_origin_as_fallback 尽力匹配,个别帧可能取不到
  • 多帧标注层:页面标注框显示帧内标号,弹窗显示完整标号(子框架带 f<frameId 36进制>. 前缀,通过 lid + frameId 对应)
  • 截图范围:browser_screenshot 只截当前视口(纯图像通道,图像直接内联返回),整页拼接未做(固定/粘性元素会重复)。若某帧加载较慢,截图时可能尚未绘制(提取会在该帧就绪后正常收录)
  • 标号的作用域:标号在一个文档实例内唯一且不复用;导航/框架重载后文档身份(docId)改变,旧标号一律被拒绝(不会再指向新文档里的同名标号)。因此跨导航必须重新 extract
  • 语义级伪装:同一节点被页面原地改造成另一个操作,但 tag / role / 关键属性 / 文本都没变(只换了事件监听器)时,指纹无从分辨——这是 DOM 层可观测性的边界;标号仍指向那个节点,不会指向别的节点
  • 虚拟列表复用节点:同一 DOM 节点被滚动复用显示不同条目时,标号跟着节点走(这是「同一元素」,只是内容换了)。若列表在两次提取之间滚动,指纹会拒绝动作;若滚动发生在提取之前,Agent 看到的就是新内容——它需要对最新快照负责

攻防对抗(自建红队)

test/hostile.html + npm run test:hostile 把已知反爬手法收敛成可回归的对抗用例(56 项判定),双向判定「应捕获 / 应排除」:

手法 处置
裸 <option> 渲染成块(超星选项伪装) ✓ 捕获(仅 <select>/<datalist> 内的 option 跳过)
父 visibility:hidden + 子再开启 ✓ 捕获(visibility 只看自身计算值)
::before/::after 承载文字(含 attr() 取属性值)/ content:url() 图片 ✓ 捕获(pseudo / bg 字段)
开放 / 闭合 / 嵌套闭合 Shadow DOM ✓ 捕获(shadow-probe)
内联拆字、视觉乱序(flex order)、竖排(writing-mode)、ruby ✓ 捕获(合并 / 坐标)
transform、SVG <text> / foreignObject、MathML(含 mrow 容器) ✓ 捕获(命名空间容器 SKIP 下钻)
渐变文字(background-clip:text)、描边文字 ✓ 捕获(不误杀透明填充的可见绘制)
可见的 aria-hidden 内容、展开的 <details>、零尺寸父下的可见子 ✓ 捕获(不误杀 / 不连坐)
display:none / visibility:hidden / opacity<0.05 / filter:opacity(0)(含祖先)/ content-visibility:hidden ✓ 排除
font-size:0 / 亚像素字号 <0.5px / text-indent:-9999px / 零尺寸 / scale(0)(含祖先) ✓ 排除
sr-only clip:rect(0,0,0,0) / clip-path:inset(≥50% 或某方向裁满) / circle(0) / 退化多边形 ✓ 排除
color/-webkit-text-fill-color 透明 / 近透明 / 同色伪装(白底白字,实色背景) ✓ 排除(渐变/背景图时保守捕获)
祖先 overflow:hidden 裁空、收起 <details>、未打开 <dialog> ✓ 排除
透明填充色的表单控件值 / type=hidden / <template> / <script> / <noscript> ✓ 排除
压力:1200 元素批量提取 ✓ 通过(尾部元素完整收录)
CSS 计数器序号、canvas 像素文字 ⚠ 已知边界(无 DOM 文本 / 需 OCR)

输入侧攻防(可信输入的能力边界)

test/hostile-input.html + npm run test:hostile-input 部署抵制自动化输入的防御,分别用 S(DOM 合成事件,等价于扩展后端)与 T(BiDi 可信输入)驱动,判定谁被突破。结论是 「BiDi 能突破以事件可信性区分人机的防御,但不是突破一切防御」:

组 防御 S 合成 T 可信 判定
A1 contenteditable 仅可信 input 更新模型 被挡 突破 isTrusted 门禁失效
A2 beforeinput 非可信即 preventDefault 被挡 突破 同上(UEditor 式)
A3 仅可信 mousedown 提交 被挡 突破 同上
A4 仅可信 keydown 计数 被挡 突破 同上
A5 仅可信 pointerdown 触发 被挡 突破 同上
B1 disabled 输入框 直接写值(绕过) 不可写 浏览器强制,T 也必须遵守
B2 readonly 输入框 直接写值 不可写 同上
B3 pointer-events:none + 覆盖层 直接 focus 绕过 命中覆盖层 T 遵守命中测试
B4 被绝对定位元素遮挡 直接 focus 绕过 命中遮挡层 T 遵守命中测试
B5 display:none 输入框 直接写值 无法定位 T 不作用于不可见元素
C1 isTrusted 预言机 false true isTrusted 不能作为防线
C2 蜜罐字段 定向不触发 定向不触发 盲目“填所有输入框”会被抓
C3 IME compositionstart 0 0 逐字注入无输入法特征,可检测
C4 按键时序 / C5 鼠标轨迹 快、直线 快、直线/跳转 行为特征(时序、轨迹熵)可检测
D1/D2 验证码 / 服务端校验 — — 输入层无解(需 OCR/人工、服务端复核)

要点:信任输入解决的是「合成事件被富文本编辑器丢弃」这一类事件可信性防御; 它不会绕过浏览器强制的交互限制、蜜罐与行为风控,也不解决验证码与服务端校验。

路线

  • 感知:接入截图/OCR 覆盖 canvas 与视频像素内容;可选的区域/语义分组渲染
  • 操作:动作后自动回传新快照(已具备基础);等待导航/网络空闲的同步语义;批量动作
  • 通道:控制通道鉴权与来源校验;native messaging 备选传输

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages