browser-cdp

Browser CDP 操作工具

透過 CDP 協定控制 Chrome，復用現有登入態，執行瀏覽器自動化操作。

前置條件

• macOS / Linux / Windows（實驗性），已安裝 Google Chrome
• Node.js 12+
• agent-browser 已安裝：npm install -g agent-browser

⚠️ 首次啟動會 kill 使用者的常規 Chrome。 在啟動前必須徵求使用者同意（見下方「啟動流程」），否則使用者可能遺失未儲存的標籤頁/草稿。

---

啟動流程（skill-mode 強制步驟）

第一步：探測目前狀態（無副作用）

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=ready → 直接使用 agent-browser --cdp 9222 ...，不要執行 setup。
• CDP_STATUS=needs-setup 且 CHROME_RUNNING=no → 安全啟動：

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

• CDP_STATUS=needs-setup 且 CHROME_RUNNING=yes → 先用 AskUserQuestion 工具向使用者確認：告知會殺掉 N 個 Chrome 程序、可能遺失未儲存工作；使用者同意後再帶 --yes 啟動；使用者拒絕則放棄這次自動化。

為什麼不能直接 --yes： 腳本在非 TTY（即 skill 模式 / Bash 工具）下，如果偵測到 Chrome 在跑而沒有 --yes，會以退出碼 3 報 NEEDS_CONSENT: ... 並中止，不會靜默殺程序。這是有意的兜底——但 skill 流程仍應先問使用者，而不是看到 3 就盲傳 --yes。

---

啟動腳本選項

選項	說明
--detect-only	只探測，不修改任何狀態（skill 用）
--yes	已徵得同意，跳過互動提示
--reset	啟動前清空 ~/chrome-debug-profile（登入失效時用）
--profile <name>	使用非 Default 的 Chrome profile（如 "Profile 1"）
--dry-run	列印將執行的步驟，不執行

退出碼：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

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

複雜 JS（含引號 / $ / 反引號）

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 視窗即可（或 pkill -9 -x 'Google Chrome' / taskkill /F /IM chrome.exe）。
• 登入態失效：node {SKILL_DIR}/scripts/setup-cdp-chrome.js 9222 --reset --yes（注意 --yes 同樣需要先問使用者）。

---

OpenCode 環境注意事項

opencode 沒有背景執行命令行的工具，長時間的 CDP 操作（如等待頁面載入、大批量資料抓取）會阻塞整個工作階段，導致 CLI 無回應。

超時包裝

Windows 上對 CDP 命令使用 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），請重試或手動打斷"

已知限制

即使加了超時包裝，以下場景仍可能出現問題：

場景	風險	緩解
頁面載入超時	eval 命令等待永不返回	設定 30s 超時，超時後重試
大批量資料抓取	多頁翻頁時累計等待過長	每頁獨立超時，失敗後從斷點繼續
Chrome 程序僵死	CDP 連線中斷但程序未退出	用 pkill / taskkill 清理後重連
網路波動	請求掛起無超時	超時後自動重試一次

如遇到持續卡死的操作，在 opencode 中按 ESC 手動打斷。

---

常見問題

問題	解決方案
NEEDS_CONSENT + 退出碼 3	用 AskUserQuestion 詢問使用者是否允許殺掉 Chrome，同意後加 --yes 重跑
CDP 連接埠未監聽	--detect-only 再確認；連接埠被佔用則換連接埠
頁面跳轉到登入頁	snapshot -i 找登入按鈕並操作
eval 返回 null	檢查 localStorage key 名；含引號的 JS 用 eval -b 或 --stdin
登入態過期	setup-cdp-chrome.js 9222 --reset --yes 重新複製
有多個 Chrome profile	--profile "Profile 1" 指定
Chrome 不會啟動（30s 超時）	試 --reset；檢查連接埠衝突；查看 ~/chrome-debug-profile/ 是否損壞