web-browser

用途

web-browser 用于在真实浏览器（Chrome/Chromium）中通过 CDP 进行网页自动化。适用场景包括：导航或与实时网站交互；点击按钮、填写表单或提取页面内容；在真实浏览器上下文中执行 JavaScript；截取截图用于调试或审查；在真实浏览器中进行 UI 验证和冒烟测试；以及使用本地基准脚本测量和门控 web-browser 工具的延迟回归。

主要能力

启动带 CDP 的 Chrome（默认端口 :9222），可选择不杀死已有 Chrome 会话。
打开或导航 URL，并支持以确定性方式新建标签页。
在页面中执行 JavaScript（eval.js），可用于读取标题、轮询等待选择器等。
截取当前视口截图，输出系统临时目录中的 PNG 文件路径。
交互式拾取元素（pick.js），打印元素的 tag/id/class/text/html/parents 等信息。
提供基准测试脚本（bench-eval.js、bench-all.js），支持预热、采样和 p95 预算门控。

使用方式

要求从 codex/skills/web-browser/ 目录运行命令（以便 ./tools/*.js 正确解析），需要 Node.js（ESM + 顶层 await）并安装仓库依赖（尤其是 puppeteer-core），需要安装 Chrome/Chromium 或设置 CODEX_CHROME_PATH。

快速开始：

# 启动带 CDP 的 Chrome，端口 :9222
./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，localhost 的 CDP 端口）、CODEX_BROWSER_USER_DATA_DIR（start.js 使用的 Chrome 用户数据目录）、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

# 交互式拾取元素
# 打印一个元素（或通过 Cmd/Ctrl+点击多个）的 tag/id/class/text/html/parents
./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，登录一次，然后在 user-data-dir（默认：~/.cache/scraping）中复用持久化配置文件。
默认配置文件引导：当确实需要现有 cookies/登录时，运行 ./tools/start.js --profile。

适用场景

需要与实时网站交互的自动化任务。
表单填写、按钮点击、页面内容提取。
在真实浏览器上下文中执行 JavaScript。
截图用于调试或审查。
真实浏览器中的 UI 验证和冒烟测试。
测量和门控 web-browser 工具的延迟回归。

限制与注意事项

安全与隐私：./tools/start.js --profile 使用 rsync -a --delete 将默认 Chrome 配置文件复制到 user-data-dir（包含 cookies/会话/PII）。应将 user-data-dir（默认：~/.cache/scraping）视为敏感数据；避免在共享机器上使用，必要时用完后删除。

故障排查：

✗ Failed to connect to Chrome via CDP：运行 ./tools/start.js（或设置 CODEX_BROWSER_URL/--port 以匹配你的 Chrome）。
✗ No active tab found：先打开页面（例如 ./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：

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、nav.js、eval.js、screenshot.js、pick.js、bench-eval.js、bench-all.js。

技能介绍

用途

主要能力

使用方式

适用场景

限制与注意事项