web-browser

Web Browser Skill

用于协作式网站探索的精简 CDP 工具。

启动 Chrome（优先使用无头模式）

./scripts/start.js --headless            # Recommended: isolated reusable profile
./scripts/start.js --headless --profile  # Headless with a copy of your profile
./scripts/start.js                       # Visible browser window when needed
./scripts/start.js --headless --reset-profile  # Clear cached profile before launch

启动带有远程调试功能的 Chrome（默认端口为 :9222）。Agent 默认应使用 --headless，因为这种模式干扰较少，并支持导航、求值、截图、模拟和日志记录。无头模式启动时会禁用用户扩展；复制的配置文件仍会提供 Cookie 和其他浏览器状态，但无法使用基于扩展的功能。有头模式启动时会照常加载扩展。只有在需要让用户查看或操作浏览器时，才使用有头模式，例如运行 pick.js、手动进行身份验证，或调试仅在无头模式下出现的差异。

启动脚本只有在配置文件和启动设置匹配时，才会复用正在运行的浏览器。在无头模式和有头模式之间切换前，请先停止正在运行的 Skill 浏览器。更改调试端口不会隔离配置文件：如果某个端口上的配置文件已在使用中，启动时会拒绝修改该配置文件，并保留 Chrome 的配置文件锁。

配置文件行为：

• 默认模式使用：~/.cache/agent-web/browser/fresh-profile
• --profile 模式使用：~/.cache/agent-web/browser/profile-copy
• 此 Skill 不会直接连接到你正在使用的 Chrome 配置文件
• 如果 :9222 已被未知实例占用，启动会失败，而不会复用该实例

如果 Chrome 安装在非标准位置，请设置：

BROWSER_BIN=/path/to/chrome ./scripts/start.js --headless

可选的调试端点覆盖项：

BROWSER_DEBUG_PORT=9333 ./scripts/start.js --headless

停止 Chrome

./scripts/stop.js                         # Stop skill Chrome on :9222
BROWSER_DEBUG_PORT=9333 ./scripts/stop.js  # Stop skill Chrome on :9333
./scripts/stop.js --all                   # Stop all skill Chrome instances

适用于无头和有头浏览器。只会停止使用 Skill 缓存配置文件的进程，不会停止你常用的 Chrome。关闭时会保留 Cookie 和其他缓存状态；绝不会强制终止 Chrome。使用 --reset-profile 前请先停止浏览器。

切换到可见浏览器：

./scripts/stop.js
./scripts/start.js

导航

./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

为浏览器 Skill 命令设置生效的设备模拟偏好设置（视口、DPR、触控、UA）。使用 --reset 清除设置。

nav.js、eval.js、pick.js、dismiss-cookies.js 和 screenshot.js 等命令会自动应用当前生效的偏好设置。

执行 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/eval.js 'JSON.stringify(Array.from(document.querySelectorAll("a")).map(a => ({ text: a.textContent.trim(), href: a.href })).filter(link => !link.href.startsWith("https://")))'

在活动标签页中执行 JavaScript。输入可以是表达式或语句列表；命令会打印类似控制台的完成值，并等待 Promise 和顶层 await 执行完毕。请注意字符串转义，最好使用单引号。

截图

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

截图并返回临时文件路径。

• 默认：当前视口
• --full-page：截取整个文档高度
• --device <preset>：仅为该次截图临时启用移动设备模拟

选择元素

./scripts/pick.js "Click the submit button"

交互式元素选择器。点击以选择，按住 Cmd/Ctrl 并点击可多选，按 Enter 完成。此功能需要有头 Chrome；启动 start.js 时不要使用 --headless。

关闭 Cookie 对话框

./scripts/dismiss-cookies.js          # Accept cookies
./scripts/dismiss-cookies.js --reject # Reject cookies (where possible)

自动关闭欧盟 Cookie 同意对话框。

导航到页面后运行：

./scripts/nav.js https://example.com && ./scripts/dismiss-cookies.js

移动设备快速调试流程

./scripts/start.js --headless
./scripts/nav.js https://example.com
./scripts/emulate.js iphone-14
./scripts/nav.js https://example.com      # reload with mobile UA
./scripts/dismiss-cookies.js
./scripts/screenshot.js --full-page

后台日志（控制台 + 错误 + 网络）

由 start.js 自动启动，并将 JSONL 日志写入：

~/.cache/agent-web/logs/YYYY-MM-DD/<targetId>.jsonl

手动启动：

./scripts/watch.js

查看最新日志：

./scripts/logs-tail.js           # dump current log and exit
./scripts/logs-tail.js --follow  # keep following

汇总网络响应：

./scripts/net-summary.js