Menu
使用 agent-browser-cli 进行浏览器感知与控制、页面交互、截图/PDF、Cookie/CDP 和排障。
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | agent-browser-cli |
| description | 使用 agent-browser-cli 进行浏览器感知与控制、页面交互、截图/PDF、Cookie/CDP 和排障。 |
使用 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 按需常驻而未启动，不代表故障。只有目标命令已经失败，或者日志/输出明确提示端口、扩展、标签页异常时，才进入排障。
先区分三个入口：
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 必须让 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 粘到对话里。
执行复杂 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。
跨标签页、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。tabs/open/exec/scan。agent-browser-cli install-skill --dry-run 展示计划，用户确认后再 agent-browser-cli install-skill。status、doctor、logs --tail、restart、stop、tabs。