agent-browser

初始化脚本与扩展#

初始化脚本会在页面 JavaScript 执行前运行。它们可用于在首次导航前安装 hook、polyfill、埋点或测试辅助工具。

启动时脚本#

bash
agent-browser --init-script ./instrumentation.js open https://example.com
agent-browser --init-script ./a.js --init-script ./b.js open https://example.com

你也可以使用环境变量配置脚本：

bash
export AGENT_BROWSER_INIT_SCRIPTS="./a.js,./b.js"
agent-browser open https://example.com

启动时脚本会在浏览器启动时应用。如果守护进程已经在运行，在更改启动脚本选项前先关闭它。

内置脚本#

bash
agent-browser --enable react-devtools open http://localhost:3000

当前可用的内置功能是 react-devtools。它会在应用代码运行前安装 React DevTools hook，并且是 react tree、react inspect、react renders 和 react suspense 的必需项。

运行时脚本#

bash
agent-browser addinitscript "window.__testMode = true"
# Returns an identifier

agent-browser removeinitscript <identifier>

运行时初始化脚本适用于会话已经启动之后。它们仍然属于初始化脚本，因此只会影响后续文档和导航，而不会重写已经执行过的页面代码。

导航前准备#

对于需要在首次真实导航前先设置路由、cookie 或脚本的流程，请在启动浏览器时不带 URL：

bash
agent-browser batch \
  '["open"]' \
  '["network","route","*","--abort","--resource-type","script"]' \
  '["cookies","set","--curl","cookies.curl","--domain","localhost"]' \
  '["navigate","http://localhost:3000/target"]'

不带 URL 的 open 会让浏览器打开 about:blank，这样就能在目标页面加载前先准备状态。

扩展#

bash
agent-browser --extension ./extension open https://example.com
agent-browser --extension ./a --extension ./b open https://example.com

扩展属于启动时选项。它们需要本地 Chromium 系浏览器，不支持 CDP 连接、云提供商或 Lightpanda。

安全性#

初始化脚本和扩展会在页面上下文中以高权限运行。仅从可信的本地路径加载脚本和扩展目录。