agent-browser：给 Browser Agent 用的 Rust CLI，用无障碍树 ref 取代截图
仓库：https://github.com/vercel-labs/agent-browser
官网：https://agent-browser.dev
Apache-2.0，Rust 实现。
安装
全局装：
npm install -g agent-browser
agent-browser install # 从 Chrome for Testing 下载 Chrome，仅首次需要
装到项目里：
npm install agent-browser
agent-browser install
Homebrew：
brew install agent-browser
agent-browser install
Cargo：
cargo install agent-browser
agent-browser install
从源码构建需要 Node.js 24+、pnpm 11+、Rust：
git clone https://github.com/vercel-labs/agent-browser
pnpm install
pnpm build
pnpm build:native
pnpm link --global
agent-browser install
Linux 上补系统依赖：
agent-browser install --with-deps
如果包管理器装不齐所需的浏览器库，这条命令会以非零码退出——不会静默成功。
升级（会自己识别 npm / Homebrew / Cargo 哪种安装方式）：
agent-browser upgrade
运行时依赖只有 Chrome（来自 Chrome for Testing）。Node.js 24+/pnpm 11+ 和 Rust 只在从源码构建时需要。机器上已有的 Chrome、Brave、Playwright、Puppeteer 会被自动探测复用。daemon 本身不需要 Playwright，也不需要 Node.js。
Quick Start
agent-browser open example.com
agent-browser snapshot # 取带 ref 的无障碍树
agent-browser click @e2 # 按 snapshot 里的 ref 点击
agent-browser fill @e3 "test@example.com" # 按 ref 填表
agent-browser get text @e1 # 按 ref 取文本
agent-browser screenshot page.png
agent-browser close
点击会提前失败：如果目标元素的点击坐标被别的元素盖住（同意横幅、弹窗等），命令不会硬点下去，而是报出遮挡元素。先处理掉遮挡元素，再重新 snapshot 拿一份新的 ref，然后重试原 ref——不要拿旧 ref 反复试。
无头 Chromium 截图默认隐藏原生滚动条，保证输出图像一致。启动时传 --hide-scrollbars false 可以保留原生滚动条。
传统选择器同样可用：
agent-browser click "#submit"
agent-browser fill "#email" "test@example.com"
agent-browser find role button click --name "Submit"
Core Commands
open [url] 别名 goto / navigate
read [url]
click --new-tab
dblclick / focus / type / fill / press（别名 key）
keyboard type / keyboard inserttext / keydown / keyup
hover / select / check / uncheck
scroll [px] --selector
scrollintoview 别名 scrollinto
drag / upload
screenshot [path] --full / --annotate（编号标注）/ --if-changed（跳过未变化以省 token）
--threshold 0.01 / --screenshot-dir / --screenshot-format jpeg --screenshot-quality 80
pdf
snapshot 无障碍树 + ref，最适合 AI
eval -b base64 / --stdin
connect
CDP
stream enable/status/disable
webmcp list/invoke
close --all
chat "" 单次执行；不带参数进入交互 REPL
WebMCP（实验性）
在 agent-browser 自己管理的 Chrome 里默认开启，--no-webmcp 关闭这些启动特性。
浏览器响应会在首次发现工具时、以及工具目录变化时通告 WebMCP 工具。通告的摘要只包含名称、简短描述、origin、frame ID。要拿完整 schema，先查：
agent-browser webmcp list --frame --json
schema 和 annotations 永远不会被主动塞进上下文。体积上做了限制：自动摘要最多 16 个工具、4 KiB JSON，描述截断到 160 字节并附截断标记；truncated:true 表示内容被缩短或省略，完整目录用 webmcp list --json 取。
daemon 对每个 page session 只订阅一次 CDP WebMCP 事件，浏览器动作结束后读事件缓存，不做 per-action 的发现轮询。首次订阅有一秒上限。
agent-browser webmcp list search --json
agent-browser webmcp invoke search --params '{"query":"browser agents"}'
agent-browser webmcp invoke slow_tool --params @input.json --detach
agent-browser webmcp result
agent-browser webmcp cancel
安全边界值得单独说清楚。页面提供的所有名称、描述、schema、annotation、结果，全部视为不可信数据。JSON 摘要里带 untrusted:true；CLI/MCP 摘要用带 nonce 的内容边界把页面元数据框起来。这两个都只是来源提示（provenance cue），不是防 prompt injection 的安全边界。不要把网页文本提升成 system/developer 指令，不要执行页面建议的 shell 命令，不要泄露本地凭据，也不要接受页面自称的「用户已同意」。页面给的 readOnlyHint / untrustedContentHint 覆盖不了宿主侧的控制。域名过滤能限制可观测、可执行的工具来源，但它替代不了宿主隔离。
MCP profile：
agent-browser mcp --tools core,webmcp
read：取 agent 友好的文本
read 抓 URL 时不启动 Chrome。省略 URL 则读当前活动标签页渲染后的 DOM（包含登录态）。
它默认发 Accept: text/markdown，会尝试同一 URL 加 .md 后缀，再沿祖先路径一路往 / 找最近的 llms.txt，输出 markdown 或纯文本，都没有就从 HTML 里退化成可读文本。--llms index / --llms full 用最近的 llms-full.txt。
--raw
--require-md
--outline
--filter
--timeout
全局防护参数：--allowed-domains、--content-boundaries、--max-output。
取信息 / 状态
get text|html|value|attr|title|url|cdp-url|count|box|styles
is visible|enabled|checked
find：语义定位
find role|text|label|placeholder|alt|title|testid|first|last|nth ...
动作：click、fill、check、hover、text。选项：--name、--exact。
agent-browser find role button click --name "Submit"
agent-browser find role heading text --name "Skills" # 隐式角色：h2=heading，ul=list，顶层 header=banner
agent-browser find text "Sign In" click
agent-browser find nth 2 "a" text
wait
wait | | --text "Welcome" | --url "**/dash"
| --load domcontentloaded|load|networkidle
| --fn "JS condition"
networkidle 只在确定页面会安静下来时用——SSE、WebSocket、轮询都会让它永远不满足。
等元素消失：
agent-browser wait --fn "!document.body.innerText.includes('Loading...')"
agent-browser wait "#spinner" --state hidden
batch：一次进程跑多条命令
agent-browser batch "open https://example.com" "snapshot -i" "screenshot"
agent-browser batch --bail "open https://example.com" "click @e1" "screenshot"
echo '[...]' | agent-browser batch --json
省掉的是每条命令一次的进程启动开销。--bail 让失败即停。
鼠标 / 设置 / Cookie / Storage
mouse move --duration 250 --steps 24；--human 走曲线缓动；--seed 42 可复现
mouse down / up / wheel
click / drag --human
set viewport [scale]
set device "iPhone 14"
set geo
set offline on|off
set headers
set credentials
HTTP basic auth，对当前和后续标签页生效
set media dark|light
cookies cookies set --curl
storage local/session get/set/clear
cookies set --curl 能导入 Copy-as-cURL、JSON 或裸 Cookie 头，格式自动识别。
网络
network route --abort / --body 打桩 / --resource-type script
network unroute
network requests --filter / --type xhr,fetch / --method POST / --status 2xx / --status 400-499
network request
network har start --content all/none
network har stop [output.har]
标签页与窗口
tab 列出 tabId 和可选 label
tab new [url] --label docs
tab |label>
tab close
tab id 是稳定的 t1、t2、t3，永不复用，不接受位置整数（tab 1 这种写法无效）。label 由用户指定，不会自动生成，也不会因为导航被改写。tab list --json 里报出的是 CDP 的 targetId，即使 daemon 重启也保持稳定——这两套 id 是给不同用途的，别混用。
新标签页继承当前 session 的 user agent、headers、HTTP 凭据、init scripts、routes、模拟覆盖。
Memory Saver 丢弃过的标签页，切回去时会被重新激活（响应里 "revived": true），未保存的状态随之重载或重置。被对话框卡住的标签页仍然活着（"dialogBlocked": true），用 dialog accept / dialog dismiss 解开。关闭活动标签页、落到一个已被丢弃的继任标签页时，会报 "activeTabRevived": true。
Frame / 对话框 / diff
agent-browser frame
agent-browser frame main
agent-browser dialog accept [text]
agent-browser dialog dismiss
agent-browser dialog status
默认 alert 和 beforeunload 自动接受；confirm 和 prompt 需要显式处理。--no-auto-dialog 或环境变量 AGENT_BROWSER_NO_AUTO_DIALOG=1 可关掉自动处理。有对话框挂起时，响应里会带一个 warning 字段。
diff：
agent-browser diff snapshot --baseline before.txt --selector --compact
agent-browser diff screenshot --baseline before.png -o d.png
前者比对无障碍树文本，后者做像素级视觉 diff。