claude-browser-cap

高速浏览器自动化工具集，作为 pm-skills 中 feature-acceptance / ui-walkthrough 两个验收 skill 的可选高速底座。

场景	不装本工具	装了本工具
验收一个 5 页面模块	chrome-devtools MCP，单 Chrome 串行	并行多 Chrome，一次配方跑完多步
Token 用量	基准	约 1/2 ~ 1/5
回合数	基准	约 1/3 ~ 1/5

适用范围

• macOS only（脚本依赖 Chrome .app 路径，未来可扩展但目前未做）。
• Node 22+（用 WebSocket / fetch global，无第三方依赖）。
• 当前主要场景：竞品调研、产品验收、UI 走查、知识抓取。

安装

git clone https://github.com/mayuemarsha-del/claude-browser-cap.git ~/.claude/tools/browser-cap

然后在 ~/.zshrc / ~/.bashrc 里添加环境变量：

# 工具安装目录（pm-skills 通过这个变量找到脚本）
export BROWSER_CAP_DIR="$HOME/.claude/tools/browser-cap"

# stash-shots.sh 的允许目标根（冒号分隔，按你自己的工作区填）
export BROWSER_CAP_DEST_ROOTS="$HOME/work/acceptance:$HOME/work/research"

# 可选：Chrome 路径（默认 /Applications/Google Chrome.app/...）
# export BROWSER_CAP_CHROME="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

配合 Claude Code 的 settings.json 把脚本加进 permissions.allow，免确认提示：

{
  "permissions": {
    "allow": [
      "Bash($BROWSER_CAP_DIR/bin/cap-launch-chrome.sh:*)",
      "Bash($BROWSER_CAP_DIR/bin/stash-shots.sh:*)",
      "Bash(node $BROWSER_CAP_DIR/bin/capture.js:*)",
      "Bash(node $BROWSER_CAP_DIR/bin/cdp_fetch.js:*)"
    ]
  }
}

三个脚本

脚本	作用
cap-launch-chrome.sh <端口>	起一个隔离 Chrome（无头 + 临时 user-data-dir）。端口限 9222–9299，已占自动拒绝。每个并行任务起自己的 Chrome。
capture.js <端口> <配方.json>	一次性按配方跑：导航 / 点击 / hover / 读 DOM 断言 / 抓接口响应 / 截图。Node 22 内置 WebSocket / fetch，无依赖。
cdp_fetch.js <端口> <命令>	单步 CDP 操作（list / new / nav / eval / shot），适合临时探测。
stash-shots.sh <源> <目标>	把临时截图拷进笔记目录。目标根由 BROWSER_CAP_DEST_ROOTS 配置，安全边界写在脚本里。

capture.js 配方 schema

{
  "outDir": "/private/tmp/cap-shots",
  "viewport": [1440, 2400],
  "recordNetwork": true,
  "steps": [
    {
      "url": "https://example.com",
      "waitMs": 1500,
      "clicks": ["text=辅助数据", "css=.tab li:nth-child(2)"],
      "clickWaitMs": 800,
      "hover": "css=.tooltip-trigger",
      "eval": "document.title",
      "shot": "01-home.png",
      "fullPage": true,
      "grabBody": ["/api/data/list"]
    }
  ]
}

每个 step 可包含的字段：

1. url：要导航的 URL；省略 = 在当前页继续操作。支持 file:// 路径（设计 HTML 走查用）。
2. waitMs：导航后等待毫秒。SPA 通常需要 2000+。
3. clicks：按序点击；元素选择支持 text=...（按可见文本匹配）和 css=...。
4. clickWaitMs：每次点击之间等待。
5. hover：hover 触发悬停态 / tooltip。
6. eval：执行 JS 表达式，结果回传 stdout（用于读 DOM / computed style）。
7. shot：截图文件名（落到 outDir）。
8. fullPage：true = 全页截图；false = 视口截图（推荐用于 UI 走查）。
9. grabBody：URL 子串列表，匹配的接口响应体写到 outDir/network/。

何时用本工具，何时用 MCP

场景	推荐
单页面 / 单状态快速点击	chrome-devtools MCP（无需安装）
需要 PM 手过登录 / 验证码	chrome-devtools MCP（人在浏览器前更直接）
多页面 / 多状态验收（10+ 操作）	browser-cap（一次配方搞定，省 token）
多 tab / 多弹窗 UI 走查	browser-cap（并行多端口）
大批量帮助中心抓取	browser-cap（脚本化批处理）

许可

MIT