firefox-browser

用途

Firefox Browser Agent Bridge 用于让智能体控制用户真实的 Firefox 浏览器会话。它通过 WebSocket 连接，使用用户现有的登录状态和 Cookie，而不是无头浏览器，因此可以以用户身份浏览网站并与需要认证的页面交互。

主要能力

会话与标签页管理

listTabs：列出所有窗口中的打开标签页
newSession：创建新标签页进行工作，可选 url 和 sandbox（隐私窗口）
newWindow：创建新的普通窗口，可选 url、focus（默认 true）、sandbox
setActiveTab：切换智能体操作的标签页，参数 tabId、focus
getActiveTab：获取当前标签页信息

导航与页面信息

navigate：在当前标签页跳转到 URL，参数 url、wait、newTab
getContent：获取页面内容，格式支持 annotated、text、html
getInteractables：列出可点击元素和输入框，可选 selector 限定范围
screenshot：截取可见区域为 PNG，可选 filename
reload：重新加载当前标签页

交互

click：点击元素，支持 selector、text 或 x/y 坐标
type：向聚焦或选中的输入框输入文本，参数 selector、text、submit、clear
fillForm：填写表单字段（inputs、textareas、selects），使用 fields[] 数组，每项含 selector/value
scroll：滚动页面或元素，支持 y/x、selector、position
waitFor：等待元素或文本出现，参数 selector、text、timeout

富文本编辑器与文件操作

uploadFile：上传文件到 <input type="file">，参数 selector、path（本地文件路径）
dropFile：拖放文件到元素上，参数 selector、path（本地文件路径）
evaluate：在页面上下文中运行 JavaScript，参数 script、pageWorld（布尔值）

控制流

fork：将标签页复制为多个路径，paths[] 含 name 和 commands
killFork：关闭某个 fork，参数 fork（名称）
listForks：列出活跃的 fork
tryUntil：尝试多个备选方案直到一个成功，参数 alternatives[]、timeout
parallel：在多个 URL 上运行命令，branches[] 含 url 和 commands
batch：按顺序运行多个命令，参数 commands[]

认证与保险库

autoLogin：从 Bitwarden 保险库自动填充凭据并可选择提交，参数 domain、submit（默认 false）
vaultStatus：检查保险库锁定状态和凭据数量
vaultSync：通过 API 密钥从 Bitwarden 服务器重新同步保险库
getAuthContext：检测登录页面和可用账户
requestAuth：请求用户批准认证，参数 reason

使用方式

快速开始

# 0. 如果 Firefox 未运行，先启动它
nohup firefox &>/dev/null &

# 1. 检查连接
browser ping

# 2. 查看打开的标签页
browser listTabs '{}'

# 3. 启动新会话（推荐）
browser newSession '{"url": "https://example.com"}'

# 4. 读取页面，交互元素已标记
browser getContent '{"format": "annotated"}'

客户端用法

browser <action> '<json_params>'

# 带计时信息
browser --timing <action> '<json_params>'

# 带屏幕录制
browser --record /path/to/dir <action> '<json_params>'

表单填写

没有单独的 fill 命令，应使用 fillForm 配合 fields 数组：

browser fillForm '{"fields": [{"selector": "#email", "value": "test@example.com"}]}'

支持 <input>、<textarea>、<select>、复选框、单选按钮、contenteditable 元素以及富文本编辑器（Draft.js、Lexical、TinyMCE、ProseMirror）。

文件上传与拖拽

browser uploadFile '{"selector": "#fileInput", "path": "/home/user/doc.pdf"}'
browser dropFile '{"selector": "#dropZone", "path": "/home/user/image.png"}'

JavaScript 执行

browser evaluate '{"script": "return document.title"}'
browser evaluate '{"script": "return window.someAppState", "pageWorld": true}'

认证设置

需要安装 bronzewarden（本地 Bitwarden 保险库客户端），登录 Bitwarden，同步保险库，并设置无密码解锁。autoLogin 默认需要指纹验证，可通过环境变量 FAB_AUTOLOGIN_REQUIRE_FINGERPRINT 控制。

并行执行

使用 tabId 进行隔离会话，避免冲突：

browser newSession '{"url": "https://example.com"}'
browser navigate '{"url": "https://example.com/page", "tabId": 15}'

适用场景

需要以用户身份浏览需要登录的网站
自动化填写表单、上传文件
在多个网站间并行比较信息
处理不确定的 UI（如 Cookie 横幅、A/B 测试）
需要访问页面 JavaScript 上下文（如 React 状态、应用全局变量）

限制

需要 Firefox 浏览器正在运行
自动登录功能依赖 Bitwarden 保险库和 bronzewarden 客户端
指纹验证需要安装 fprintd 并录入指纹
部分功能（如保险库同步）需要 Bitwarden API 密钥
文档中未提供具体的收费、价格或平台兼容性信息

技能介绍

用途