{"id":"browser-cdp","name":"browser-cdp","summary":"このスキルは、CDP(Chrome DevTools Protocol)を使って既存のログインセッションを再利用するためにChromeブラウザを制御する必要がある場合に活用してください。","body":"# Browser CDP 操作工具\n\n通过 CDP 协议控制 Chrome，复用已有登录态，执行浏览器自动化操作。\n\n## 前置条件\n\n- macOS / Linux / Windows（实验性），已安装 Google Chrome\n- Node.js 20+\n- `agent-browser` 已安装：`npm install -g agent-browser`\n\n> ⚠️ **首次启动会 kill 用户的常规 Chrome。** 在启动前必须征求用户同意（见下方\"启动流程\"），否则用户可能丢失未保存的标签页/草稿。\n\n---\n\n## 启动流程（skill-mode 强制步骤）\n\n**第一步：探测当前状态（无副作用）**\n\n```bash\nnode {SKILL_DIR}/scripts/setup-cdp-chrome.js 9222 --detect-only\n```\n\n输出形如：\n\n```\nCDP_STATUS=ready                        # 已就绪，可直接复用\nCDP_URL=http://127.0.0.1:9222/json/version\nBROWSER=Chrome/148.0.7778.168\n```\n\n或：\n\n```\nCDP_STATUS=needs-setup\nCHROME_RUNNING=yes                      # 用户有 Chrome 在跑，启动会杀掉\nCHROME_PID_COUNT=3\n```\n\n**第二步：根据探测结果分支**\n\n- `CDP_STATUS=ready` → 直接使用 `agent-browser --cdp 9222 ...`，**不要运行 setup**。\n- `CDP_STATUS=needs-setup` 且 `CHROME_RUNNING=no` → 安全启动：\n  ```bash\n  node {SKILL_DIR}/scripts/setup-cdp-chrome.js 9222 --yes\n  ```\n- `CDP_STATUS=needs-setup` 且 `CHROME_RUNNING=yes` → **先用 AskUserQuestion 工具向用户确认**：告知会杀掉 N 个 Chrome 进程、可能丢失未保存工作；用户同意后再带 `--yes` 启动；用户拒绝则放弃这次自动化。\n\n**为什么不能直接 `--yes`：** 脚本在非 TTY（即 skill 模式 / Bash 工具）下，如果检测到 Chrome 在跑而没有 `--yes`，会以退出码 3 报 `NEEDS_CONSENT: ...` 并中止，**不会**静默杀进程。这是有意的兜底——但 skill 流程仍应先问用户，而不是看到 3 就盲传 `--yes`。\n\n---\n\n## 启动脚本选项\n\n| 选项 | 说明 |\n|------|------|\n| `--detect-only` | 只探测，不修改任何状态（skill 用） |\n| `--yes` | 已征得同意，跳过交互提示 |\n| `--reset` | 启动前清空 `~/chrome-debug-profile`（登录失效时用） |\n| `--profile <name>` | 使用非 Default 的 Chrome profile（如 `\"Profile 1\"`） |\n| `--dry-run` | 打印将执行的步骤，不执行 |\n\n退出码：`0` 成功 / `1` 通用错误 / `2` 用户拒绝（TTY）/ `3` 需同意但缺 `--yes`。\n\n---\n\n## 常用操作\n\n### 打开页面并等待加载\n\n```bash\nagent-browser --cdp 9222 open \"<URL>\"\nagent-browser --cdp 9222 wait 3000\n```\n\n### 提取页面文本\n\n```bash\nagent-browser --cdp 9222 eval 'document.body.innerText.substring(0, 8000)'\n```\n\n### 提取 Auth Token\n\n```bash\nagent-browser --cdp 9222 eval 'localStorage.getItem(\"token\") || document.cookie'\n```\n\n### 复杂 JS（含引号 / `$` / 反引号）\n\nshell 转义容易出错，用以下两种方式之一：\n\n```bash\n# 1) base64 包裹\nagent-browser --cdp 9222 eval -b \"$(echo -n \"document.querySelectorAll('a').length\" | base64)\"\n\n# 2) heredoc + --stdin\ncat <<'EOF' | agent-browser --cdp 9222 eval --stdin\nconst links = document.querySelectorAll('a');\nlinks.length;\nEOF\n```\n\n### 页面交互（snapshot 拿元素引用）\n\n```bash\nagent-browser --cdp 9222 snapshot -i        # 仅交互元素\nagent-browser --cdp 9222 click \"<CSS or @e1>\"\nagent-browser --cdp 9222 type \"<sel>\" \"<text>\"\n```\n\n---\n\n## 停止 / 清理\n\n- 关掉 debug Chrome 窗口即可。若窗口无响应，先按 `--user-data-dir` 核验出 debug 实例的 PID 再只结束它：\n  - macOS / Linux：`pgrep -af chrome-debug-profile`\n  - Windows：`wmic process where \"name='chrome.exe'\" get ProcessId,CommandLine | findstr chrome-debug-profile`\n  拿到 PID 后 `kill -9 {PID}` / `taskkill /F /PID {PID}`。核验不出归属时停止，**手工清理不得按 Chrome 可执行文件名批量结束进程**——那会连带杀掉用户的日常 Chrome。\n  例外：`setup-cdp-chrome.js --reset` 内部确实会做一次按可执行名的清理，它属于本 skill 自带的、需 `--yes` 显式同意的启动流程；手工排障不要复制该做法。\n- 登录态失效：`node {SKILL_DIR}/scripts/setup-cdp-chrome.js 9222 --reset --yes`（注意 `--yes` 同样需要先问用户）。\n\n---\n\n## OpenCode 环境注意事项\n\nopencode 没有后台执行命令行的工具，长时间的 CDP 操作（如等待页面加载、大批量数据抓取）会阻塞整个会话，导致 CLI 无响应。\n\n### 超时包装\n\nWindows 上对 CDP 命令使用 PowerShell Job 包装超时：\n\n```powershell\n$job = Start-Job { agent-browser --cdp 9222 eval \"window.location.replace('https://www.qidian.com/rank/')\" }\nWait-Job $job -Timeout 30 | Out-Null\nif ($job.State -eq 'Running') { Stop-Job $job; Write-Output \"⏱ CDP 操作超时（30s），请重试或手动打断\" }\nelse { Receive-Job $job }\nRemove-Job $job -Force\n```\n\nmacOS / Linux 上使用 `timeout` 命令：\n\n```bash\ntimeout 30 agent-browser --cdp 9222 eval \"window.location.replace('https://www.qidian.com/rank/')\" || echo \"⏱ CDP 操作超时（30s），请重试或手动打断\"\n```\n\n### 已知限制\n\n即使加了超时包装，以下场景仍可能出现问题：\n\n| 场景 | 风险 | 缓解 |\n|------|------|------|\n| 页面加载超时 | eval 命令等待永不返回 | 设置 30s 超时，超时后重试 |\n| 大批量数据抓取 | 多页翻页时累计等待过长 | 每页独立超时，失败后从断点继续 |\n| Chrome 进程僵死 | CDP 连接断开但进程未退出 | 先核验 debug profile 对应 PID，只结束该 debug 实例后重连；不得连带普通 Chrome |\n| 网络波动 | 请求挂起无超时 | 超时后自动重试一次 |\n\n如遇到持续卡死的操作，在 opencode 中按 `ESC` 手动打断。\n\n---\n\n## 常见问题\n\n| 问题 | 解决方案 |\n|------|----------|\n| `NEEDS_CONSENT` + 退出码 3 | 用 AskUserQuestion 询问用户是否允许杀掉 Chrome，同意后加 `--yes` 重跑 |\n| CDP 端口未监听 | `--detect-only` 再确认；端口被占用则换端口 |\n| 页面跳转到登录页 | `snapshot -i` 找登录按钮并操作 |\n| `eval` 返回 `null` | 检查 localStorage key 名；含引号的 JS 用 `eval -b` 或 `--stdin` |\n| 登录态过期 | `setup-cdp-chrome.js 9222 --reset --yes` 重新拷贝 |\n| 有多个 Chrome profile | `--profile \"Profile 1\"` 指定 |\n| Chrome 不会启动（30s 超时） | 试 `--reset`；检查端口冲突；查看 `~/chrome-debug-profile/` 是否损坏 |","author":"@worldwonderer","ownerProfile":null,"authorContacts":null,"sourceUrl":"https://github.com/worldwonderer/oh-story-claudecode/tree/main/skills/browser-cdp","license":"MIT","category":null,"lang":"en","tokens":1921,"stars":0,"calls30d":0,"claimed":false,"visibility":"public","origin":"crawler","version":"0.1.0","createdAt":"2026-08-22","updatedAt":"2026-08-22","files":[{"path":"scripts/setup-cdp-chrome.js","size":40851,"sha256":"ecd3c2d6811e85d6013b6e02034aa59b9fe992417d1719a7be3b70b8c52b0c3d"}],"requires":{"mcp":[],"tools":[]},"safety":{"flags":[{"code":"net.endpoints","kind":"exfiltration","excerpt":"www.qidian.com","message":"bundled scripts reach 1 external host(s)","severity":"warn"}],"scannedAt":"2026-08-22","hasScripts":true,"networkEndpoints":["www.qidian.com"]}}