agent-browser-cli

name	agent-browser-cli
description	使用 agent-browser-cli 进行浏览器感知与控制、页面交互、截图/PDF、Cookie/CDP 和排障。

agent-browser-cli

使用 agent-browser-cli 控制用户真实 Chrome。底层是 Rust daemon + Chrome 扩展桥，保留登录态和 Cookie；不是 Selenium/Playwright。

正常流程直接执行命令

每次开始浏览器任务，不要先做健康检查，直接执行最贴近目标的命令。tabs / open / exec / scan 会按需自动启动 daemon；daemon 未常驻是正常状态，不是故障。

agent-browser-cli open https://example.com
agent-browser-cli scan --text-only
agent-browser-cli snapshot --limit 200
agent-browser-cli exec --tab <tabId> 'return document.title'

只有目标命令失败、输出明确提示连接异常、扩展未连接、端口不一致、无可用标签页，或用户明确要求排障时，才进入状态检查：

agent-browser-cli status
agent-browser-cli doctor
agent-browser-cli logs --tail 100

status 中 daemon_not_running / running=false 不能单独作为停止操作的理由；优先继续执行目标命令让 CLI 自动拉起 daemon。doctor 只检查状态，不自动启动 daemon、不改配置、不安装 skill。

补充一个容易误判的点：status / doctor 里看到 daemon_not_running，如果此时还没有执行 tabs / open / exec / scan，通常只是 daemon 按需常驻而未启动，不代表故障。只有目标命令已经失败，或者日志/输出明确提示端口、扩展、标签页异常时，才进入排障。

打开本地文件

open 支持 HTTP(S) URL、绝对 file:// URL 和本机文件路径。相对路径以执行 CLI 时的当前目录为基准；支持 ~、中文、空格和符号链接，符号链接会解析到真实文件。所有普通文件类型均可打开，目录会被拒绝。

agent-browser-cli open ./demo.html
agent-browser-cli open ~/Documents/report.pdf
agent-browser-cli open 'file:///Users/me/My%20Files/demo.html#intro'
agent-browser-cli open ./demo.html --timeout 15

本地文件要求 Chrome 扩展版本至少为 2.1，并在 chrome://extensions → Agent Browser CLI Bridge → 详情中开启“允许访问文件网址”。权限关闭时 open 会在创建标签前失败；status / doctor 会按 Profile 报告 file_scheme_access，但该可选能力不影响普通 HTTP(S) 健康状态。

输入分类规则：

• ./、../、~/、绝对路径和显式 file:// 表示本地文件；文件必须存在且是普通文件。
• 裸输入若对应当前目录中已存在的文件，文件优先；否则按 Web 地址处理。要强制打开网站，显式写 https://。
• 普通路径中的 ? 和 # 是文件名字符；仅显式 file:// URL 使用 query/fragment 语义。
• localhost、回环/私网 IP、单标签主机和 .local 的无协议地址默认使用 HTTP；其他域名默认 HTTPS；端口 80/443 分别强制 HTTP/HTTPS。
• 只支持 http:、https: 和 file:；其他显式 scheme 会返回 unsupported_scheme。
• 异平台路径会明确报错，例如 macOS/Linux 不会把 C:\\Users\\... 错当作网址。

本地文件 open 默认最多等待 10 秒，直到新标签成为可控制会话；可用 --timeout 调整。超时后标签会保留，错误结果包含稳定的 error_code 和 opened_tab_id。活动 open 成功后新标签成为默认会话，--background 不切换默认会话。

常用命令优先级

先区分三个入口：

scan：内容感知，适合看正文、列表、页面文本。
snapshot：操作定位，适合找按钮、链接、输入框并生成 @e 引用。
exec / JSON CDP：逃生口，封装命令失效或特殊页面时回退。

基础感知和按需排障：

agent-browser-cli tabs
agent-browser-cli tabtree
agent-browser-cli tabtree --full
agent-browser-cli tabtree --profile work
agent-browser-cli tabtree --tab <tabId>
agent-browser-cli lookup tab <tabId>
agent-browser-cli lookup browser <browser_id>
agent-browser-cli lookup profile work
agent-browser-cli tabs --profile work
agent-browser-cli profile-label set work --profile <profile_id>
agent-browser-cli scan --tabs-only
agent-browser-cli scan --profile work --tab <tabId> --text-only
agent-browser-cli open --profile work https://example.com
agent-browser-cli open --window https://example.com
agent-browser-cli open --window --focus https://example.com
# open 返回后继续操作新页面时，优先使用 result.opened_tab_id / result.opened_session_key
agent-browser-cli open https://example.com
agent-browser-cli close --tab <tabId>
agent-browser-cli exec --tab <tabId> 'return document.title'
agent-browser-cli status
agent-browser-cli doctor
agent-browser-cli logs --tail 100

第二阶段后的推荐流程：

看页面内容：scan / scan --text-only
selector 明确时：直接 click/fill selector
selector 不明确或页面复杂时：snapshot 生成 @e，再 click/fill @e
页面结构或内容变化后：重新 snapshot
封装命令失效或覆盖不到特殊页面时：回退 exec / JSON CDP / 自定义 JS

示例：

agent-browser-cli scan --text-only
agent-browser-cli click 'button[type=submit]'
agent-browser-cli snapshot --limit 200
agent-browser-cli snapshot --offset 200 --limit 200
agent-browser-cli snapshot --details
agent-browser-cli click '@e1'
agent-browser-cli fill '@e2' 'hello'
agent-browser-cli fill '@e2' --clear
agent-browser-cli fill '@e2' ' world' --append
agent-browser-cli send-keys --target '@e2' 'Enter'
agent-browser-cli mouse-click '@e3'

所有高层操作都支持 --tab <tabId>，多 Chrome Profile / 多浏览器实例时还支持 --profile <profile_id-or-label> 和 --browser <browser_id>。tabs 输出会包含 browser_id、profile_id、profile_label、tab_id、session_key。tabtree 用树形结构列出 browser → profile → tabs，支持 --tab <tabId>、--profile <profile_id-or-label>、--browser <browser_id> 过滤，过滤结果仍保留父子节点；默认 compact 输出会截断 URL 并省略 session_key，需要完整字段时用 tabtree --full；lookup tab <tabId> 可由 tab 反查 browser_id / profile_id / profile_label，lookup browser <browser_id> 可反查所属 profile。profile-label set <label> --profile <profile_id> 可设置当前 Chrome Profile 的 label 并校验当前 daemon 内唯一性，profile-label clear --profile <profile_id> 可清空；popup 设置是本地便捷入口，不保证跨 Profile 唯一；label 只允许英文、数字、-、_、.，当前 daemon 内匹配到多个 profile 时会报歧义，不能猜。只传 --tab 且存在歧义时，必须补 --profile 或 --browser。@e 只在当前 daemon、当前 session_key、最近一次 snapshot 内有效。@e 只接受 @e1 这种带 @ 的格式。

慢页面要把等待和监控分开：

agent-browser-cli click '@e1' --wait-js 'return document.body.innerText.includes("完成")' --wait-timeout 10 --monitor

--wait-js 负责等慢加载；--monitor 只负责操作前后页面 diff，默认关闭。

Chrome 右上角“正在控制你的浏览器”是 chrome.debugger.attach 的正常提示，不是 daemon 常驻状态。普通 CDP 命令空闲后会延迟约 30 秒自动 detach；30 秒内同一 tab 继续执行 CDP 会复用连接并重新计时。network/console 持续监听期间不会自动 detach，停止监听或清理时才释放。

弹窗处理：扩展默认不改写业务页面的 alert / confirm / prompt。只有 CLI 页面执行命令期间临时抑制弹窗，结束后恢复；如果怀疑页面原生弹窗行为异常，先让用户重载扩展和页面。

端口和扩展

固定 API 端口：

127.0.0.1:18767

默认扩展 WebSocket 端口：

127.0.0.1:18765

配置文件：

~/.agent-browser-cli/config.json

修改扩展端口会影响 Chrome 扩展和 daemon 连接，执行前必须说明影响并取得用户确认：

agent-browser-cli set-extension-port <port>

网络和控制台调试

network / console 需要扩展侧持续监听 CDP 事件。修改或升级扩展后，必须先让用户重载 Chrome 插件。

agent-browser-cli network start --tab <tabId>
agent-browser-cli network list --tab <tabId> --filter api
agent-browser-cli network detail <requestId> --tab <tabId>
agent-browser-cli network clear --tab <tabId>
agent-browser-cli network stop --tab <tabId>

agent-browser-cli console start --tab <tabId>
agent-browser-cli console list --tab <tabId>
agent-browser-cli console list --tab <tabId> --level error
agent-browser-cli console clear --tab <tabId>
agent-browser-cli console stop --tab <tabId>

network detail 会截断大响应体并标记 base64Encoded，不要把巨大 body 粘到对话里。network clear 清请求缓存；network stop 会停止监听并清请求缓存。console clear 清日志缓存；console stop 会停止监听并清日志缓存。

agent-browser-cli stop / daemon idle 退出时会额外清理 daemon 内的 snapshot/@e 缓存，并通知扩展清理 network/console 调试缓存。

标签分组

多任务开新标签时可以用 session 或 group-title 把标签放入 Chrome 原生标签组。需要独立窗口时用 open --window；默认不聚焦，需要抢焦点时显式加 --focus；--window --group-title / --window --session 会把新窗口里的首个 tab 加入对应 tab group。分组只是整理浏览器标签，失败不影响开 tab 主流程。

agent-browser-cli open https://example.com --session research
agent-browser-cli open https://example.com --group-title "任务A"
agent-browser-cli open --window https://example.com
agent-browser-cli open --window --focus https://example.com
agent-browser-cli open --profile work https://example.com

--session 和 --group-title 都会作为标签组标题；两者同时传时优先使用 --group-title。

截图和 PDF

截图/PDF 必须让 CLI 写文件，不要把 base64 大段塞进上下文。命令只返回路径、字节数和少量元信息。

agent-browser-cli screenshot --out /tmp/page.png
agent-browser-cli screenshot --full-page --out /tmp/full.png
agent-browser-cli screenshot --target '@e1' --out /tmp/button.png
agent-browser-cli screenshot --selector 'button[type=submit]' --format jpeg --quality 70 --out /tmp/button.jpg
agent-browser-cli save-pdf --out /tmp/page.pdf
agent-browser-cli save-pdf --paper a4 --landscape --scale 0.9 --out /tmp/page.pdf

screenshot 默认截当前视口；--full-page 截全页；--target 和兼容别名 --selector 二选一，目标既可以是 @e 也可以是 CSS selector。没有 --out 时，截图写到 /tmp/agent-browser-cli-screenshots/。

save-pdf 默认 paper=a4、scale=1.0、print-background=true；需要关闭背景时用 --no-print-background。没有 --out 时，PDF 写到 /tmp/agent-browser-cli-pdfs/，默认文件名来自清理后的页面标题。

如果封装命令失效，用 exec 调 CDP 后由脚本落盘，仍然避免把 base64 粘到对话里。

exec 使用规则

执行复杂 JS 时写入临时文件：

agent-browser-cli exec --tab <tabId> --file /tmp/script.js

需要等待页面变化时使用 --wait-js，不要在脚本里固定 setTimeout：

agent-browser-cli exec --tab <tabId> 'document.querySelector("button").click()' --wait-js 'return document.body.innerText.includes("完成")' --wait-timeout 3

exec 中使用 await 必须显式 return，否则结果可能是 null。

JSON/CDP 逃生口

跨标签页、Cookie、CDP、扩展管理、浏览器内容权限时，用 JSON 指令：

agent-browser-cli exec '{"cmd":"tabs"}'
agent-browser-cli exec '{"cmd":"cookies"}'
agent-browser-cli exec '{"cmd":"cdp","tabId":303987837,"method":"Page.captureScreenshot","params":{"format":"png"}}'

CDP 点击优先三事件序列：mouseMoved -> mousePressed -> mouseReleased。首次 attach 可能出现 Chrome infobar，先发无害 mouseMoved(0,0) 预热。

文件上传

文件上传优先用 DataTransfer API，不优先使用 CDP DOM.setFileInputFiles：

const input = document.querySelector('input[type=file]');
const file = new File(['content'], 'demo.txt', { type: 'text/plain' });
const dt = new DataTransfer();
dt.items.add(file);
input.files = dt.files;
input.dispatchEvent(new Event('input', { bubbles: true }));
input.dispatchEvent(new Event('change', { bubbles: true }));
return input.files.length;

运维入口

• 目标命令失败、扩展未连接、端口不一致、无可用标签页：看 references/operations.md。
• daemon 未运行但尚未执行目标命令：不要排障，直接继续执行 tabs/open/exec/scan。
• skill 安装：先 agent-browser-cli install-skill --dry-run 展示计划，用户确认后再 agent-browser-cli install-skill。
• 可自动执行的排障命令：status、doctor、logs --tail、restart、stop、tabs。