web-browser

Web Browser

使用场景

• 浏览或与实时网站交互。
• 点击按钮、填写表单或提取页面内容。
• 在真实浏览器环境中执行 JavaScript。
• 截取屏幕截图以便调试或审查。
• 在真实浏览器中进行 UI 验证和冒烟测试。
• 使用本地基准测试脚本测量 Web Browser 工具的延迟回归并设置门槛。

要求

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

快速开始

# Start Chrome with CDP on :9222
./tools/start.js

# Safer (recommended on your laptop): avoid killing an existing Chrome session
./tools/start.js --no-kill

# Open a deterministic tab, then operate on it
./tools/nav.js https://example.com --new
./tools/eval.js 'document.title'
./tools/screenshot.js

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

性能检查（$lift）

在优化或验证 Web Browser 工具延迟时使用。

./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。
• 如果操作落在“错误的”标签页上，请关闭多余标签页或打开新标签页。

常用命令

# See all options (safe; does not start/kill Chrome)
./tools/start.js --help

# Use a non-default port
./tools/start.js --port 9223 --no-kill
./tools/nav.js --port 9223 https://example.com --new

# Or configure once via env
export CODEX_BROWSER_URL=http://localhost:9223
./tools/eval.js 'document.title'

# Wait for a selector (polling with timeout; good for SPAs)
./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; })()'

# Screenshot current viewport
# Prints a PNG filepath in your system temp dir
./tools/screenshot.js

# Pick elements interactively
# Prints tag/id/class/text/html/parents for one element (or many via Cmd/Ctrl+click)
./tools/pick.js "Click the submit button"

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

示例

# Scrape structured data (return an array of objects for readable output)
./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 配置文件复制到你的用户数据目录（包含 Cookie/会话/PII）。
• 请将你的用户数据目录（默认：~/.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

需要客观证明本地 $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