面向 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 签名的正式包:
- 打开 Firefox,访问
about:addons - 右上角齿轮 → 「从文件安装附加组件…」,选择该
.xpi - 工具栏出现扩展图标即安装成功(重启浏览器后依然有效)
也可先卸载再重装以更新版本;升级时无需重新授权权限。
开发调试(临时加载,重启失效)
- 打开
about:debugging#/runtime/this-firefox - 「临时载入附加组件」→ 选择本目录的
manifest.json - 或用
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 并下载签名 XPIweb-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,逐帧下发) - 点击弹窗中任意元素行:页面对应元素闪烁高亮;同时选中该元素,可在操作栏执行 点击 / 输入 / 清空 / 选中 / 滚到
每个元素都带一个 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=clickd=dblclickl=longpressr=contextmenuf=fillo=chooses=selecttext。可用caps:false关闭。
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。
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-* 包装层),因此快照里哪个节点都能用。
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跳变,断言要看 释放之后的回读。
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 / 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 来识别。
进度条、滑块、画布、地图这类「同一个元素、不同位置不同语义」的控件:
fx/fy ∈ [0,1],越界夹到边界。返回值含 at: [x, y] 便于核对。
注意:clickAt 内部不用 element.click()——它派发的 click 坐标恒为 (0,0),
会把算好的位置抹掉(进度条会跳回开头);改为手动派发带坐标的 MouseEvent('click'),
默认行为(导航、checkbox 切换)仍然生效。
复制 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块切块,主框架元素在前,子框架内容紧随其后(标号不因分块/排序改变)。
扩展作为 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 :hoverhoverTrusted是 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 指令。
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。
# 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-servertest/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 备选传输
{ "action": "clickAt", "elementId": "1.42", "options": { "fx": 0.3, "fy": 0.5 } }