Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Browser & automation

agent-browser-cli

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

sleepinginsummer · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add sleepinginsummer/agent-browser-cli --skill agent-browser-cli

About this skill


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 consol
Read the complete source ↗