browser-cdp

1# Browser CDP 操作工具
2 
3通过 CDP（Chrome DevTools Protocol）连接 Chrome，复用登录态并执行浏览器操作。
4 
5## 前置条件
6 
7- macOS / Linux / Windows（实验性），已安装并使用过 Google Chrome，来源 profile 已存在
8- Node.js 20+
9- `agent-browser` 已安装：`npm install -g agent-browser`
10 
11> 启动或重建时，若需结束 Chrome 进程，先按下方流程征得同意；未保存的标签页或草稿可能丢失。
12 
13---
14 
15## 启动流程（每次都按这个顺序）
16 
17下文 `{SKILL_DIR}` 指本 skill（browser-cdp）的目录。
18 
19**第一步：探测当前状态（无副作用）**
20 
21```bash
22node {SKILL_DIR}/scripts/setup-cdp-chrome.js 9222 --detect-only
23```
24 
25输出形如：
26 
27```
28CDP_STATUS=ready                        # 已就绪，可直接复用
29CDP_URL=http://127.0.0.1:9222/json/version
30BROWSER=Chrome/148.0.7778.168
31```
32 
33或：
34 
35```
36CDP_STATUS=needs-setup
37CHROME_RUNNING=yes                      # 用户有 Chrome 在跑，启动会杀掉
38CHROME_PID_COUNT=3
39```
40 
41**第二步：根据探测结果分支**
42 
43- `CDP_STATUS=needs-setup` 且 `CHROME_INSTALLED=no` → 本机没找到 Chrome，告诉用户先安装并用它登录一次需要的网站，不要运行 setup。
44- `CDP_STATUS=ready` 且本次只需连接 → 直接使用 `agent-browser --cdp 9222 ...`，**不要运行 setup**。
45- 明确请求 `--reset` / `--profile` → 即使 ready 也走重建，按下方「需要结束 Chrome 时」处理。
46- `CDP_STATUS=needs-setup` 且 `CHROME_RUNNING=no` → 安全启动：
47  ```bash
48  node {SKILL_DIR}/scripts/setup-cdp-chrome.js 9222 --yes
49  ```
50- `CDP_STATUS=needs-setup` 且 `CHROME_RUNNING=yes` → 按下方「需要结束 Chrome 时」处理。
51 
52**需要结束 Chrome 时（同意流程）**：凡是会结束正在运行的 Chrome 的命令（Chrome 在运行时启动、`--reset`、显式 `--profile`），都按这三步走：
53 
541. 带上原定选项加 `--dry-run` 跑一次，看会结束几个 Chrome 进程；
552. 告诉用户会结束 N 个 Chrome 进程、未保存的标签页或草稿可能丢失，问是否继续；
563. 用户同意后，去掉 `--dry-run`、加 `--yes` 重跑；用户拒绝就放弃这次自动化。
57…