网络浏览器自动化 web-browser

名称: 网络浏览器 描述: “当任务需要通过 CDP 在 Chrome/Chromium 中进行真实浏览器网络自动化时使用：打开或导航 URL、点击/输入/选择表单、运行页面 JavaScript、等待选择器、抓取结构化内容、捕获屏幕截图、验证 UI 流程，或运行测量的网络浏览器延迟检查 (bench:eval, bench:all) 用于性能回归。”

网络浏览器

何时使用

• 导航或与实时网站交互。
• 点击按钮、填写表单或提取页面内容。
• 在真实浏览器上下文中评估 JavaScript。
• 捕获屏幕截图用于调试或审查。
• 在真实浏览器中进行 UI 验证和冒烟测试。
• 使用本地基准脚本测量和门控网络浏览器工具的延迟回归。

要求

• 从 codex/skills/web-browser/ 运行命令（以便 ./tools/*.js 解析）。
• Node.js（ESM + 顶层 await）和仓库依赖已安装（特别是 puppeteer-core）。
• Chrome/Chromium 已安装，或设置 CODEX_CHROME_PATH。

快速开始

# 在 :9222 上启动带 CDP 的 Chrome
./tools/start.js

# 更安全（推荐在笔记本电脑上使用）：避免杀死现有的 Chrome 会话
./tools/start.js --no-kill

# 打开一个确定性标签页，然后对其进行操作
./tools/nav.js https://example.com --new
./tools/eval.js 'document.title'
./tools/screenshot.js

循环：采取小步骤 → 检查状态（eval.js / screenshot.js） → 重复。

性能通道 ($lift)

在优化或验证网络浏览器工具延迟时使用此功能。

./tools/start.js --no-kill
./tools/nav.js https://example.com --new

cd tools
npm run -s bench:all -- --warmup 5 --samples 30 --screenshot-samples 20

对于更严格的 CI 风格门控，添加 p95 预算：

cd tools
npm run -s bench:all -- \
  --warmup 5 \
  --samples 30 \
  --screenshot-samples 20 \
  --budget-nav-p95-ms 310 \
  --budget-eval-p95-ms 220 \
  --budget-screenshot-p95-ms 320 \
  --budget-start-p95-ms 140

配置

• 标志
  • start.js: --port, --user-data-dir, --chrome-path, --profile, --no-kill
  • nav.js / eval.js / screenshot.js / pick.js: --port, --browser-url
• 环境变量
  • CODEX_BROWSER_URL: CDP URL（当没有 CLI --port/--browser-url 时使用）
  • CODEX_BROWSER_PORT（别名: CODEX_CDP_PORT): 本地主机的 CDP 端口
  • CODEX_BROWSER_USER_DATA_DIR: Chrome 用户数据目录（由 start.js 使用）
  • CODEX_CHROME_PATH（别名: CHROME_PATH, PUPPETEER_EXECUTABLE_PATH): Chrome/Chromium 可执行文件路径

目标（活动标签页）

所有工具都操作“活动标签页”，定义为 puppeteer.pages() 返回的最后一个页面（大致为：最近打开的标签页）。

• 当您想要确定性目标时，优先使用 ./tools/nav.js <url> --new。
• 如果操作命中了“错误”的标签页，关闭额外标签页或打开一个新标签页。

常用命令

# 查看所有选项（安全；不启动/杀死 Chrome）
./tools/start.js --help

# 使用非默认端口
./tools/start.js --port 9223 --no-kill
./tools/nav.js --port 9223 https://example.com --new

# 或通过环境变量配置一次
export CODEX_BROWSER_URL=http://localhost:9223
./tools/eval.js 'document.title'

# 等待选择器（带超时的轮询；适用于 SPA）
./tools/eval.js '(async () => { for (let i = 0; i < 50; i++) { const el = document.querySelector("button[type=submit]"); if (el) return true; await new Promise(r => setTimeout(r, 100)); } return false; })()'

# 截取当前视口截图
# 打印系统临时目录中的 PNG 文件路径
./tools/screenshot.js

# 交互式选取元素
# 为一个元素打印标签/ID/类/文本/HTML/父元素（或通过 Cmd/Ctrl+点击多个）
./tools/pick.js "Click the submit button"

提示：使用 pick.js 检查属性/文本，然后为 eval.js 制作选择器。

食谱

# 抓取结构化数据（返回对象数组以便可读输出）
./tools/eval.js 'Array.from(document.querySelectorAll("a"), a => ({ href: a.href, text: a.textContent?.trim() }))'

• 登录流程
  • 专用自动化配置文件：运行 ./tools/start.js，登录一次，然后在您的用户数据目录（默认：~/.cache/scraping）中重复使用持久化配置文件。
  • 默认配置文件引导：当您确实需要现有 cookie/登录时，运行 ./tools/start.js --profile。

安全与隐私

• ./tools/start.js --profile 使用 rsync -a --delete 将您的默认 Chrome 配置文件复制到用户数据目录（cookies/会话/PII）。
• 将您的用户数据目录（默认：~/.cache/scraping）视为敏感；避免在共享机器上使用，并在需要时删除。

故障排除

• ✗ 无法通过 CDP 连接到 Chrome: 运行 ./tools/start.js（或设置 CODEX_BROWSER_URL/--port 以匹配您的 Chrome）。
• ✗ 未找到活动标签页: 先打开一个页面（例如，./tools/nav.js https://example.com --new）。
• 端口 9222 忙: 选择新端口（./tools/start.js --port 9223）。
• 选择器不稳定: 使用上述轮询模式；SPA 通常需要在 domcontentloaded 后等待。
• Chrome 路径未找到: 设置 CODEX_CHROME_PATH 或传递 --chrome-path。

陷阱

• ./tools/start.js 默认杀死 Chrome 进程（使用 --no-kill 避免此情况）。
• 使用单引号括起 JS 以避免 shell 转义问题。

证明 $lift 使用 Zig

当您需要客观证明本地 $lift 工具是基于 Zig 的：

bench_stats --help 2>&1 | sed -n '1,6p'
perf_report --help 2>&1 | sed -n '1,6p'
brew cat tkersey/tap/lift | rg -n 'depends_on \"zig\" => :build|build-exe|bench_stats.zig|perf_report.zig'

参考文献

• codex/skills/web-browser/tools/start.js
• codex/skills/web-browser/tools/nav.js
• codex/skills/web-browser/tools/eval.js
• codex/skills/web-browser/tools/screenshot.js
• codex/skills/web-browser/tools/pick.js
• codex/skills/web-browser/tools/bench-eval.js
• codex/skills/web-browser/tools/bench-all.js