Firefox：用同一套 RPC 操作 Firefox

什么时候读本文件：用户要求在 Firefox 里操作；/status 返回 "browser":"firefox"； 或在 Firefox 上遇到 BIDI_UNAVAILABLE / CDP_UNSUPPORTED。

选浏览器：只改一个环境变量

Chrome 与 Firefox 各有一个本地 host，RPC 方法、参数、返回结构、错误码相同，区别只有端口：

scripts/lib/bridge.mjs 与 scripts/ 下全部脚本都按 BRIDGE_BROWSER / BRIDGE_PORT 选端口（BRIDGE_PORT 优先）：

BRIDGE_BROWSER=firefox node <skill 目录>/scripts/preflight.mjs
BRIDGE_BROWSER=firefox node <skill 目录>/scripts/cdp-eval.mjs <tabId> "document.title"

import { Rpc } from "./scripts/lib/bridge.mjs";
const rpc = new Rpc({ port: 8779, agentName: "MyTask" });   // 或进程环境里设 BRIDGE_BROWSER=firefox
await rpc.withPage("https://example.com/", async (tabId) => {
  await rpc.clickReal(tabId, "a");
  console.log(await rpc.ev(tabId, "document.title"));
});

裸 HTTP：

TOKEN=$(cat ~/.chrome-agent-bridge/token)
curl -s http://127.0.0.1:8779/status
curl -s -X POST http://127.0.0.1:8779/rpc -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"method":"tabs.list","params":{},"timeoutMs":10000}'

两个浏览器的 token 是同一个文件；tabId 各自独立编号，不能把 Chrome 的 tabId 拿到 Firefox 端口用。

前置条件：Firefox 必须以 Remote Agent 模式启动

Firefox 扩展没有 chrome.debugger。真实点击、受控输入、文件上传、CDP 求值、静默截图在 Firefox 上由 host 经 WebDriver BiDi（Firefox 内置的 Remote Agent）执行，而 Remote Agent 只在 Firefox 带 --remote-debugging-port 启动时开启。

/status 判断当前状态：

{ "browser": "firefox", "extConnected": true, "bidi": { "port": 9222, "connected": true, "attachedTabs": [] } }

• extConnected:false：Firefox 没开，或扩展没装（临时扩展在 Firefox 重启后会消失）。
• bidi.connected:false 只表示还没有调用过需要 BiDi 的方法，不代表不可用；第一次调用失败才报 BIDI_UNAVAILABLE。

不需要 BiDi 的方法（tabs.*、page.navigate、page.snapshot、page.click、page.type、page.scroll、 page.evaluate（非严格 CSP 页）、page.inspect、page.read 等）在 Firefox 普通启动时也能用。

启动方式（本机仓库的便利命令，由用户或安装流程执行，见 INSTALL.md「Firefox」一节）：

node <chrome-agent-bridge 仓库根>/relay/firefox-launch.js --no-install   # 已永久安装签名版扩展时；Firefox 须已完全退出
node <chrome-agent-bridge 仓库根>/relay/firefox-launch.js                # 未签名：每次启动都装临时扩展

与 Chrome 的行为差异

navigator.webdriver=true 是 Firefox 方案的固有代价。对 BOSS 直聘、小红书等风控严格的站点，优先用 Chrome。

使用痕迹：用户和网页能看到什么

Firefox 上的痕迹比 Chrome 明显，且大部分在桥没有操作时也存在。开工前向用户说明，风控严格的站点改用 Chrome。

Firefox 独有（v0.3.15 实测）：

两个浏览器共有（桥自己的提示，页面脚本同样能读到）：

• 标题被改为 ● [<agentName>] 接管中 | 原标题，document.title 可读到。
• <html> 下插入指示器节点：#agent-bridge-control-status（接管标记）、#agent-bridge-stop（「停止 Agent」按钮）、#agent-bridge-cursor（虚拟光标）与点击波纹。

session.send 在 Firefox 上支持的 CDP 方法

不支持任何 *.enable 与 CDP 事件订阅（如 Network.enable）：需要网络拦截、性能追踪等能力时改用 Chrome。

Firefox 专有错误码

Firefox 同一时间只允许一个 BiDi 会话，且连接断开不会释放会话。host 正常退出（Firefox 关闭、扩展重载、SIGTERM） 时会先结束会话；被 kill -9 时会话会残留，只能重启 Firefox 释放。