browser-cdp

Browser CDP 操作工具

通过 CDP（Chrome DevTools Protocol）连接 Chrome，复用登录态并执行浏览器操作。

前置条件

• macOS / Linux / Windows（实验性），已安装并使用过 Google Chrome，来源 profile 已存在
• Node.js 20+
• agent-browser 已安装：npm install -g agent-browser

启动或重建时，若需结束 Chrome 进程，先按下方流程征得同意；未保存的标签页或草稿可能丢失。

启动流程（每次都按这个顺序）

下文 {SKILL_DIR} 指本 skill（browser-cdp）的目录。

第一步：探测当前状态（无副作用）

node {SKILL_DIR}/scripts/setup-cdp-chrome.js 9222 --detect-only

输出形如：

CDP_STATUS=ready                        # 已就绪，可直接复用
CDP_URL=http://127.0.0.1:9222/json/version
BROWSER=Chrome/148.0.7778.168

或：

CDP_STATUS=needs-setup
CHROME_RUNNING=yes                      # 用户有 Chrome 在跑，启动会杀掉
CHROME_PID_COUNT=3

第二步：根据探测结果分支

• CDP_STATUS=needs-setup 且 CHROME_INSTALLED=no → 本机没找到 Chrome，告诉用户先安装并用它登录一次需要的网站，不要运行 setup。
• CDP_STATUS=ready 且本次只需连接 → 直接使用 agent-browser --cdp 9222 ...，不要运行 setup。
• 明确请求 --reset / --profile → 即使 ready 也走重建，按下方「需要结束 Chrome 时」处理。
• CDP_STATUS=needs-setup 且 CHROME_RUNNING=no → 安全启动：

  node {SKILL_DIR}/scripts/setup-cdp-chrome.js 9222 --yes

• CDP_STATUS=needs-setup 且 CHROME_RUNNING=yes → 按下方「需要结束 Chrome 时」处理。

需要结束 Chrome 时（同意流程）：凡是会结束正在运行的 Chrome 的命令（Chrome 在运行时启动、--reset、显式 --profile），都按这三步走：

1. 带上原定选项加 --dry-run 跑一次，看会结束几个 Chrome 进程；
2. 告诉用户会结束 N 个 Chrome 进程、未保存的标签页或草稿可能丢失，问是否继续；
3. 用户同意后，去掉 --dry-run、加 --yes 重跑；用户拒绝就放弃这次自动化。

非 TTY 调用中，Chrome 在运行且未传 --yes 时，脚本以退出码 3 报 NEEDS_CONSENT: ... 并中止。取得同意后再重跑，不自动补 --yes。

换端口：9222 被别的程序占用时可以换一个端口（如 9333），之后所有 agent-browser --cdp 命令用同一个端口，扫榜脚本加 --port 9333，查资料助手传 cdp_port: 9333。

启动脚本选项

退出码：0 成功 / 1 通用错误 / 2 用户拒绝（TTY）/ 3 需同意但缺 --yes。

常用操作

打开页面并等待加载

agent-browser --cdp 9222 open "<URL>"
agent-browser --cdp 9222 wait 3000

提取页面文本

agent-browser --cdp 9222 eval 'document.body.innerText.substring(0, 8000)'

提取 Auth Token

示例读取 localStorage 的 token 项或 JavaScript 可读的 Cookie；实际存放位置按站点确认。

agent-browser --cdp 9222 eval 'localStorage.getItem("token") || document.cookie'

复杂 JS（含引号 / $ / 反引号）

用 base64 或标准输入传入脚本，避免 shell 转义错误：

# 1) base64 包裹
agent-browser --cdp 9222 eval -b "$(echo -n "document.querySelectorAll('a').length" | base64)"

# 2) heredoc + --stdin
cat <<'EOF' | agent-browser --cdp 9222 eval --stdin
const links = document.querySelectorAll('a');
links.length;
EOF

页面交互（snapshot 拿元素引用）

agent-browser --cdp 9222 snapshot -i        # 仅交互元素
agent-browser --cdp 9222 click "<CSS or @e1>"
agent-browser --cdp 9222 type "<sel>" "<text>"

停止 / 清理

• 关掉 debug Chrome 窗口即可。若窗口无响应，先按 --user-data-dir 核验出 debug 实例的 PID 再只结束它：
• macOS / Linux：pgrep -af chrome-debug-profile
• Windows（PowerShell）：Get-CimInstance Win32_Process | Where-Object CommandLine -like '*chrome-debug-profile*' | Select-Object ProcessId,CommandLine；没有 PowerShell 的旧系统才用 wmic process get ProcessId,CommandLine | findstr chrome-debug-profile

核验 PID 后用 kill -9 {PID} / taskkill /F /PID {PID}，无法核验则停止。手工清理不得按 Chrome 可执行文件名批量结束进程；启动脚本仍走上述同意流程。

• 登录态失效：用 node {SKILL_DIR}/scripts/setup-cdp-chrome.js 9222 --reset 重新复制来源 profile，按上方「需要结束 Chrome 时」先 dry-run、征得同意再加 --yes。

长命令加超时

在前台执行耗时的 CDP 命令时，为页面加载和批量采集设置超时，避免单次调用长时间占住会话。

超时包装

Windows 用 PowerShell Job 设置超时：

$job = Start-Job { agent-browser --cdp 9222 eval "window.location.replace('https://www.qidian.com/rank/')" }
Wait-Job $job -Timeout 30 | Out-Null
if ($job.State -eq 'Running') { Stop-Job $job; Write-Output "⏱ CDP 操作超时（30s），请重试或手动打断" }
else { Receive-Job $job }
Remove-Job $job -Force

macOS / Linux 有 timeout 时：

timeout 30 agent-browser --cdp 9222 eval "window.location.replace('https://www.qidian.com/rank/')" || echo "⏱ CDP 操作超时（30s），请重试或手动打断"

已知限制

持续卡死时，请用户在宿主里手动打断（如 OpenCode、Claude Code 按 ESC）。

常见问题