入选理由:官方文档覆盖本地安装、元素引用和会话隔离,练习无需登录即可核对跳转结果,补充现有浏览器引擎指南中未展开的命令行交互流程。
入选:2026-11-10 · 资料核对:2026-11-10。根据官方资料整理,未进行安装与功能实测。
agent-browser:用页面快照定位链接并验证跳转
它解决什么问题
浏览器自动化需要先知道页面有哪些控件,再对正确的目标操作,并检查结果。agent-browser 将页面的无障碍树整理成终端可读的文本,为控件提供 @e1 之类的引用。浏览器在命令之间保持运行,适合把“观察、操作、再检查”拆成几步。
本篇用两个由本机提供的静态页面,验证能否找到一个链接、点击并确认打开了结果页。练习流程依据官方文档编写,未进行浏览器安装或运行实测。
适合谁,哪些情况不适合
适合会使用终端、想调试网页交互或为智能体准备浏览器工具的开发者。可以先手工运行命令,看懂每一步,再考虑写成测试或交给智能体执行。
如果任务只需下载一个接口的 JSON,不一定需要启动浏览器。也不要把一个点击示例当作完整的业务测试;登录、提交表单或改动真实账户需要另行设计环境、权限和验收条件。这里不接入个人浏览器或模型服务。
环境与准备
本例使用 macOS 或 Linux 终端、Node.js 24 及 npm,固定安装本次核对的 agent-browser@0.41.2。先运行 node --version 和 npm --version;该版本 npm 包声明 Node.js 至少为 24。CLI 及浏览器首次下载需要联网,练习页在本机运行。
官方提供 macOS、Linux 的 ARM64 和 x64 构建,以及 Windows x64 构建。本文用 Unix 风格的终端命令。macOS 自动下载 Chrome for Testing 的路径要求系统至少为 13;Linux 需要能运行 Chrome 的系统库,缺失时按官方安装页补齐。install --with-deps 会调用系统包管理器,可能需要管理员权限,先确认机器允许安装这些依赖。
准备两个终端窗口:一个启动练习页,另一个操作浏览器。不要复用配置了个人浏览器连接、远程提供方或会话恢复的环境。端口 8765 需要空闲。
安装与第一次使用
1. 在终端 A 安装到独立练习目录。 这条路线把 CLI 版本写进练习项目,不替换已有全局 CLI。浏览器下载仍使用工具的本机缓存。
ab_demo_dir=$(mktemp -d) &&
mkdir "$ab_demo_dir/browser-lab" &&
cd "$ab_demo_dir/browser-lab" &&
npm init -y &&
npm install --save-dev --save-exact agent-browser@0.41.2 &&
./node_modules/.bin/agent-browser --version &&
./node_modules/.bin/agent-browser install
先确认版本为 0.41.2,再确认浏览器安装没有报错。执行 pwd,记下当前练习目录,稍后终端 B 也要进入这里。
2. 在终端 A 创建并启动练习页。 服务器只在本机回环地址监听,返回首页和结果页两段静态 HTML,不读取目录文件或接受表单。
cat > fixture.cjs <<'JS'
const { createServer } = require('node:http');
const host = '127.0.0.1';
const port = 8765;
const pages = {
'/': '<title>Browser Lab</title><h1>Browser Lab</h1><a href="/done">Open result</a>',
'/done': '<title>Browser Lab Result</title><h1>Navigation complete</h1>',
};
createServer((req, res) => {
const page = req.method === 'GET' && Object.hasOwn(pages, req.url) ? pages[req.url] : null;
res.writeHead(page ? 200 : 404, { 'Content-Type': 'text/html; charset=utf-8' });
res.end(page ? '<!doctype html><meta charset="utf-8">' + page : 'Not found');
}).listen(port, host, () => console.log('http://' + host + ':' + port + '/'));
JS
node fixture.cjs
终端显示 http://127.0.0.1:8765/ 后保持服务运行。这个示例不需要从公开网站获取测试内容,链接和目标页由上面的代码定义。
3. 在终端 B 进入同一目录,打开独立会话。 下方 ab 是当前终端的简短函数:每次调用都使用练习目录中的 CLI、显式配置文件和同一个会话名。如果会话名已被使用,请换一个未使用的名称。
cat > browser-lab.json <<'JSON'
{"headed": false}
JSON
ab() {
./node_modules/.bin/agent-browser --config ./browser-lab.json --session repowatch-browser-lab "$@"
}
ab open http://127.0.0.1:8765/
ab snapshot -i
找出输出中名称为 Open result 的链接,记下它的引用。-i 用于聚焦可交互元素。若当前引用显示为 @e1,可执行下例;若是其他编号,替换为实际编号。
ab click @e1
ab get url
ab snapshot
预期 get url 返回 http://127.0.0.1:8765/done,新快照包含标题 Navigation complete。这两项分别检查目标地址与页面内容。导航后应以新快照为准,首页的引用不能直接用在结果页。这里只描述预期结果,不把文档核对当作实测。
4. 结束练习。 在终端 B 运行 ab close,关闭这一个浏览器会话。然后回到终端 A 按 Ctrl+C 停止静态服务。练习目录中的包和样例仍保留,可在下次继续用。
主要能力与典型场景
- 检查页面导航。 在有权测试的页面上先读取链接的可见名称,点击后核对 URL 和新页面的关键内容。
- 定位交互故障。 在点击前后分别取快照,确认控件是否存在、是否被遮挡、动作后是否出现预期结果。可按文档选择可见浏览器窗口观察问题。
- 把网页状态交给脚本。 CLI 支持 JSON 输出和按选择器获取内容。动态页面可以等待目标文本、元素或 URL,再进行下一步。
- 区分多个任务。 为每项任务使用独立会话,避免共享 cookie、存储和导航历史;保留登录状态或连接已有浏览器是单独的配置选择。
与提供网页运行能力的浏览器引擎相比,本例练的是操作命令以及对结果的检查。换用其他引擎或提供方时,需要重新核对功能支持。
常见问题与排错
- 终端找不到本地 CLI。 确认终端 B 位于终端 A 的练习目录,安装命令已成功,并用本地二进制查看版本。
- Chrome 未找到或启动失败。 核对下载是否完成、系统版本与浏览器依赖。官方
doctor可诊断版本、缓存、守护进程和启动情况;先阅读诊断结果,不要直接运行会清理或修复其他状态的选项。 - 服务报端口已占用。 先确认原进程用途。可以给练习换一个空闲端口,同时修改
fixture.cjs中的端口、打开地址与结果检查地址。 - 找不到
Open result。 检查服务是否仍在终端 A 运行,打开地址是否为首页。已经在/done时,应回到首页再取snapshot -i;结果页没有这个链接。 - 点击失败或引用不对。 重新读取快照,确认当前页面与会话;在业务页面中还要检查控件是否禁用、不可见或被覆盖。不要沿用上一次页面的引用。
费用、隐私与限制
CLI 源码采用 Apache 2.0。本例在本机运行,无需付费浏览器服务或模型账号;下载 CLI 和 Chrome 仍需要网络与磁盘。云浏览器、在线模型和代理服务的费用及数据处理方式需要另行确认。
独立会话隔离浏览器状态,但不会自动限制可访问域名或可执行动作。官方的域名、动作与输出边界需要显式配置,域名列表也不能代替系统网络隔离。若以后接入智能体,应把网页文字当作输入数据,不能把网页里的文字直接当成有权限的操作指令。登录态、页面快照和截图可能包含私人信息,本例没有使用真实账号或会话文件。
本例只检查一个静态链接,不能说明复杂页面、登录或跨站交互的兼容性。扩展到自己的应用时,按具体页面状态设计等待条件,并确认预期结果后再自动执行下一步。