web-browser

web-browser 是一个基于 Chrome DevTools Protocol（CDP）的轻量浏览器自动化技能，主要用于协作式站点探索。它通过一组脚本控制 Chrome 或 Chromium，实现导航、点击、填表、内容检查、截图等操作。

用途该技能面向需要自动化操作网页的场景，例如代理（Agent）在无头浏览器中探索站点、执行脚本、采集页面信息、模拟移动设备以及记录控制台、错误和网络日志。

主要能力

启动与停止浏览器：start.js 启动 Chrome 并开启远程调试（默认端口 :9222），支持 --headless、--profile、--reset-profile 等参数；stop.js 用于停止技能启动的 Chrome 实例，支持 --all 停止全部实例。
导航：nav.js 可导航当前标签页或通过 --new 打开新标签页。
设备模拟：emulate.js 支持列出预设、设置设备（如 iphone-14、pixel-7）、横屏（--landscape）以及重置（--reset）。nav.js、eval.js、pick.js、dismiss-cookies.js、screenshot.js 会自动应用当前模拟偏好。
执行 JavaScript：eval.js 在活动标签页中执行表达式或语句列表，打印控制台风格的结果，并等待 Promise 或顶层 await。
截图：screenshot.js 返回临时文件路径，支持 --full-page 全页截图和 --device 临时移动模拟。
元素选取：pick.js 提供交互式元素选择器，点击选择、Cmd/Ctrl+Click 多选、Enter 完成，需要以有头模式启动 Chrome。
关闭 Cookie 弹窗：dismiss-cookies.js 自动关闭欧盟 Cookie 同意对话框，默认接受，可用 --reject 拒绝。
后台日志：start.js 自动启动日志记录，将控制台、错误和网络日志以 JSONL 格式写入 ~/.cache/agent-web/logs/YYYY-MM-DD/<targetId>.jsonl；watch.js 可手动启动，logs-tail.js 用于查看最新日志（--follow 持续跟踪），net-summary.js 用于汇总网络响应。

使用方式启动 Chrome（推荐无头）： ./scripts/start.js --headless ./scripts/start.js --headless --profile ./scripts/start.js ./scripts/start.js --headless --reset-profile

停止 Chrome： ./scripts/stop.js BROWSER_DEBUG_PORT=9333 ./scripts/stop.js ./scripts/stop.js --all

导航： ./scripts/nav.js https://example.com ./scripts/nav.js https://example.com --new

设备模拟： ./scripts/emulate.js --list ./scripts/emulate.js iphone-14 ./scripts/emulate.js pixel-7 --landscape ./scripts/emulate.js --reset

执行 JavaScript： ./scripts/eval.js 'document.title' ./scripts/eval.js 'document.querySelectorAll("a").length' ./scripts/eval.js 'document.querySelector("button")?.click(); "clicked"' ./scripts/eval.js 'await Promise.resolve(document.title)'

截图： ./scripts/screenshot.js ./scripts/screenshot.js --full-page ./scripts/screenshot.js --device iphone-14 ./scripts/screenshot.js --device pixel-7 --full-page

元素选取： ./scripts/pick.js "Click the submit button"

关闭 Cookie 弹窗： ./scripts/dismiss-cookies.js ./scripts/dismiss-cookies.js --reject

快速移动调试流程： ./scripts/start.js --headless ./scripts/nav.js https://example.com ./scripts/emulate.js iphone-14 ./scripts/nav.js https://example.com ./scripts/dismiss-cookies.js ./scripts/screenshot.js --full-page

日志： ./scripts/watch.js ./scripts/logs-tail.js ./scripts/logs-tail.js --follow ./scripts/net-summary.js

适用场景

代理在无头浏览器中自动探索网站。
需要执行页面脚本、检查 DOM 或采集链接等内容的场景。
移动端页面调试与截图。
需要记录控制台、错误和网络请求日志的调试任务。
需要人工查看或交互时，可切换为有头模式进行元素选取、手动认证或调试无头模式差异。

限制

无头启动会禁用用户扩展；使用 --profile 复制配置文件仍可提供 Cookie 等浏览器状态，但基于扩展的功能不可用。有头启动则正常加载扩展。
该技能不会直接附加到用户正在使用的 Chrome 配置文件。
如果 :9222 已被未知实例占用，start 会失败而不是复用。
更改调试端口不会隔离配置文件；启动时会拒绝修改已在其他端口使用的配置文件，并保留 Chrome 的配置文件锁。
默认模式使用 ~/.cache/agent-web/browser/fresh-profile，--profile 模式使用 ~/.cache/agent-web/browser/profile-copy。
如果 Chrome 安装在非标准位置，需设置 BROWSER_BIN=/path/to/chrome。
可通过 BROWSER_DEBUG_PORT 覆盖调试端口。
stop.js 只停止使用技能缓存配置文件的进程，不会强制终止 Chrome，关闭时会保留 Cookie 和其他缓存状态。
在无头与有头模式之间切换前，需先停止正在运行的技能浏览器。
使用 --reset-profile 前需先停止浏览器。
pick.js 需要以有头模式启动 Chrome。

技能介绍