chrome-automation

技能：Chrome 自動化 (agent-browser)

透過 agent-browser CLI 在使用者真實的 Chrome 工作階段中自動化瀏覽器任務。

先決條件：必須安裝 agent-browser 且 Chrome 必須啟用遠端除錯。如果不確定，請參閱 references/agent-browser-setup.md。

---

核心原則：重複使用使用者現有的 Chrome

此技能在單一 Chrome 程序上運作——也就是使用者真實的瀏覽器。沒有工作階段管理、沒有獨立的設定檔、也不會啟動全新的 Playwright 瀏覽器。

例外：瀏覽器視窗錄製是獨立模式。對於帳號、憑證、雲端主控台或示範錄製，請使用 Agent Browser 的 record 指令搭配專用的有頭設定檔，而不是使用者的日常 Chrome。

始終先列出分頁

在開啟任何新頁面之前，務必先列出現有分頁：

agent-browser --auto-connect tab list

這會回傳所有開啟的分頁及其索引編號、標題和 URL。檢查您需要的頁面是否已經開啟：

• 如果目標頁面已經開啟 → 直接切換到該分頁，而不是開啟新分頁。使用者可能已經開啟它，因為他們已經登入且頁面處於正確狀態。

  agent-browser --auto-connect tab <index>
  

• 如果目標頁面未開啟 → 在目前分頁或新分頁中開啟它。

  agent-browser --auto-connect open <url>
  

為什麼這很重要

• 使用者的 Chrome 擁有他們的 Cookie、登入工作階段和瀏覽器狀態
• 當頁面已經可用時開啟新分頁會浪費時間，並可能遺失登入狀態
• 許多行銷平台（社群媒體儀表板、廣告管理員、CMS 工具）需要登入——重複使用已登入的分頁可避免重新驗證

---

連線

始終使用 --auto-connect 連線到使用者正在執行的 Chrome 實例：

agent-browser --auto-connect <command>

這會自動發現已啟用遠端除錯的 Chrome。如果連線失敗，請引導使用者啟用遠端除錯（請參閱 references/agent-browser-setup.md）。

Chrome 144+ 僅 WebSocket 回退

Chrome 144+ 可以從 chrome://inspect/#remote-debugging 以僅 WebSocket 端點暴露遠端除錯。在該狀態下，頁面顯示 Server running at: 127.0.0.1:9222，但傳統的發現 URL 回傳 404：

curl http://127.0.0.1:9222/json/version
curl http://127.0.0.1:9222/json/list

較舊的 agent-browser 版本（例如 0.27.x）可能會失敗，顯示 No running Chrome instance found，即使 Chrome 已準備就緒。首先嘗試最新的 CLI，而不變更全域安裝：

npx -y agent-browser@latest connect "ws://127.0.0.1:9222/devtools/browser"
npx -y agent-browser@latest tab list

如果這有效，請在後續的瀏覽器任務中使用 npx -y agent-browser@latest <command>。如果出現引擎警告或安裝錯誤，請將 Node 升級到 24+ 或全域安裝最新的 agent-browser。

---

常見工作流程

1. 瀏覽與互動

# 列出分頁以尋找現有頁面
agent-browser --auto-connect tab list

# 切換到現有分頁（如果找到）
agent-browser --auto-connect tab <index>

# 或開啟新頁面
agent-browser --auto-connect open https://example.com
agent-browser --auto-connect wait --load networkidle

# 拍攝快照以查看互動元素
agent-browser --auto-connect snapshot -i

# 點擊、填寫等
agent-browser --auto-connect click @e3
agent-browser --auto-connect fill @e5 "some text"

2. 從頁面擷取資料

# 取得所有文字內容
agent-browser --auto-connect get text body

# 截圖以進行視覺檢查
agent-browser --auto-connect screenshot

# 執行 JavaScript 以取得結構化資料
agent-browser --auto-connect eval "JSON.stringify(document.querySelectorAll('table tr').length)"

3. 重播 Chrome DevTools 錄製

使用者可能會提供從 Chrome DevTools Recorder 匯出的錄製（JSON、Puppeteer JS 或 @puppeteer/replay JS 格式）。請參閱下方的重播錄製。

4. 錄製瀏覽器視窗示範

對於僅瀏覽器的示範，最終影片應包含頁面內容但不包含 Chrome 網址列、分頁列、自動化資訊列或桌面，請使用 Agent Browser 視窗錄製：

• 在正式錄製前執行版本檢查：

  python3 <skill-root>/scripts/check_browser_recording_versions.py
  

• 使用 --headed --profile <dedicated-profile> 搭配明確的 --namespace 和 --session。
• 請勿將使用者的日常 Chrome 設定檔用於正式的帳號、憑證或雲端主控台錄製。
• 請勿對帳號、憑證或雲端主控台錄製使用無頭模式；僅將無頭模式保留給公開/本機驗證。
• 將特定網站的腳本、示範腳本、後處理包裝器和時間軸慣例保留在專案特定或私人技能中。

請勿將此模式用於 Finder、系統下載對話框、桌面應用程式或瀏覽器 chrome 本身；請使用 Mac 螢幕錄製技能處理這些情況。

---

逐步互動指南

拍攝快照

使用 snapshot -i 查看所有帶有參考（@e1、@e2、...）的互動元素：

agent-browser --auto-connect snapshot -i

輸出會列出每個互動元素及其角色、文字和參考。後續動作請使用這些參考。

步驟類型對應

動作	指令
瀏覽	agent-browser --auto-connect open <url>（可選 wait --load networkidle，但某些網站如 Reddit 永遠不會達到 networkidle——如果 open 已顯示頁面標題則跳過）
點擊	snapshot -i → 找到參考 → click @eN
填寫標準輸入	click @eN → fill @eN "text"
填寫富文字編輯器	click @eN → keyboard inserttext "text"
按鍵	press <key>（Enter、Tab、Escape 等）
捲動	scroll down <amount> 或 scroll up <amount>
等待元素	wait @eN 或 wait "<css-selector>"
截圖	screenshot 或 screenshot --annotate
取得頁面文字	get text body
取得目前 URL	get url
執行 JavaScript	eval <js>

如何區分輸入類型

• 標準 input/textarea → 使用 fill
• Contenteditable div / 富文字編輯器（LinkedIn 訊息框、Gmail 撰寫、Slack、CMS 編輯器）→ 先點擊/聚焦，然後使用 keyboard inserttext

參考生命週期

參考（@e1、@e2、...）在頁面變更時失效。請務必在以下情況後重新快照：

• 點擊觸發導覽的連結或按鈕
• 提交表單
• 觸發動態內容載入（AJAX、SPA 導覽）

驗證

在每個重要動作後，驗證結果：

agent-browser --auto-connect snapshot -i   # 檢查互動狀態
agent-browser --auto-connect screenshot     # 視覺驗證

---

重播錄製

接受的格式

1. JSON（建議）— 結構化，可以逐步讀取：

   # 計算步驟數
   jq '.steps | length' recording.json
   
   # 讀取前 5 個步驟
   jq '.steps[0:5]' recording.json
   

2. @puppeteer/replay JS（import { createRunner }）

3. Puppeteer JS（require('puppeteer')、page.goto、Locator.race）

如何重播

1. 解析錄製 — 在執行前了解完整意圖。總結錄製的內容。
2. 先列出分頁 — 檢查目標頁面是否已經開啟。
3. 導覽 — 執行 navigate 步驟，盡可能重複使用現有分頁。
4. 對於每個互動步驟：
   • 拍攝快照（snapshot -i）以查看目前的互動元素
   • 將錄製中的 aria/... 選擇器與快照比對
   • 回退到 text/...，然後是 CSS 類別提示，最後是截圖
   • 不要依賴 ember ID、數字 ID 或精確 XPath——這些在每次頁面載入時都會變更
5. 在每個步驟後驗證 — 快照或截圖以確認

---

大量使用 iframe 的網站

snapshot -i 僅在主框架上運作，無法穿透 iframe。像 LinkedIn、Gmail 和嵌入式編輯器這類網站會在 iframe 內渲染內容。

偵測 iframe 問題

• snapshot -i 回傳異常簡短或空白的結果
• 錄製中參考的元素未出現在快照輸出中
• get text body 內容與截圖顯示的不符

解決方法

1. 使用 eval 存取 iframe 內容：

   agent-browser --auto-connect eval --stdin <<'EVALEOF'
   const frame = document.querySelector('iframe[data-testid="interop-iframe"]');
   const doc = frame.contentDocument;
   const btn = doc.querySelector('button[aria-label="Send"]');
   btn.click();
   EVALEOF
   

   注意：僅適用於同源 iframe。

2. 使用 keyboard 進行盲目輸入：如果 iframe 元素已獲得焦點，keyboard inserttext "..." 會傳送文字，不受框架邊界影響。

3. 使用 get text body 讀取包含 iframe 在內的完整頁面內容。

4. 使用 screenshot 在快照不可靠時進行視覺驗證。

何時詢問使用者

如果在同一步驟嘗試 2 次後解決方法仍失敗，請暫停並解釋：

• 頁面使用了無法透過快照存取的 iframe
• 您需要的元素以及您的預期
• 請使用者手動執行該步驟，然後繼續

---

處理意外情況

自動處理（不要停止）：

• 彈出視窗或橫幅 → 關閉它們（find text "Dismiss" click 或 find text "Close" click）
• Cookie 同意對話框 → 接受或關閉
• 工具提示覆蓋層 → 先關閉它們
• 元素不在快照中 → 嘗試 find text "..." click，或使用 scroll down 300 捲動顯示

暫停並詢問使用者：

• 需要登入/驗證
• 出現 CAPTCHA
• 頁面結構與預期完全不同
• 即將執行破壞性動作（刪除資料、發送真實內容）— 先確認
• 同一步驟嘗試超過 2 次仍卡住
• 所有 iframe 解決方法都失敗

暫停時，清楚說明：您在哪個步驟、您的預期以及您看到的內容。

---

主要指令參考

指令	說明
tab list	列出所有開啟的分頁及其索引、標題和 URL
tab <index>	按索引切換到現有分頁
tab new	開啟新的空白分頁
tab close	關閉目前分頁
open <url>	導覽到 URL
snapshot -i	列出帶有參考的互動元素
click @eN	按參考點擊元素
fill @eN "text"	清除並填寫標準 input/textarea
type @eN "text"	不經清除直接輸入
keyboard inserttext "text"	插入文字（最適合 contenteditable）
press <key>	按下鍵盤按鍵
scroll down/up <amount>	以像素為單位捲動頁面
wait @eN	等待元素出現
wait --load networkidle	等待網路穩定
wait <ms>	等待一段時間
screenshot [path]	截圖
screenshot --annotate	截圖並加上編號標籤
eval <js>	在頁面中執行 JavaScript
get text body	取得所有文字內容
get url	取得目前 URL
set viewport <w> <h>	設定視窗大小
find text "..." click	語意搜尋並點擊
close	關閉瀏覽器工作階段

---

已知限制

1. iframe 盲區：snapshot -i 無法看到 iframe 內部。請參閱大量使用 iframe 的網站。
2. find text 嚴格模式：當多個元素匹配時會失敗。請改用 snapshot -i 定位特定參考。
3. fill 與 contenteditable：fill 僅適用於 <input> 和 <textarea>。對於富文字編輯器，請使用 keyboard inserttext。
4. eval 僅限主框架：要與 iframe 內容互動，請透過 document.querySelector('iframe').contentDocument... 遍歷。

---

多平台操作

當使用者要求跨多個平台執行動作時（例如「將這篇文章發布到 Dev.to、LinkedIn 和 X」），請勿在單一對話中嘗試所有平台。相反地，啟動依序的子代理/工作者，每個平台一個。選擇此技能即表示明確允許在此多平台工作流程中使用子代理/工作者。

為什麼使用子代理

每個平台操作大約消耗 25-40K tokens（參考檔案 + 快照 + 互動）。在一個上下文中執行 3-5 個平台可能會達到上下文限制並降低後期平台的準確性。每個子代理/工作者都有自己的全新上下文視窗。

如何執行

1. 準備內容 — 與使用者確認貼文文字、標題、標籤以及任何平台特定的調整。
2. 對於每個平台，啟動一個子代理/工作者，提示中包含：
   • 要發布的完整內容
   • 讀取相關參考檔案的指示（例如 Read /path/to/skills/chrome-automation/references/x.md）
   • 讀取 agent-browser 技能檔案以取得指令參考的指示
   • 特定任務（發布、留言、回覆等）
   • 任何平台特定的指示（例如「在 LinkedIn 上使用這些主題標籤」）
3. 依序執行子代理/工作者（一次一個），因為它們都透過 --auto-connect 共用同一個 Chrome 瀏覽器。並行子代理/工作者會導致分頁衝突。
4. 在每個子代理/工作者完成後，向使用者報告結果，然後再啟動下一個。

子代理的提示範本

您正在 [PLATFORM] 上自動化瀏覽器任務。

首先，讀取這些檔案以了解上下文：
- /absolute/path/to/skills/chrome-automation/references/[platform].md
- 已安裝的 agent-browser 技能檔案（如果有的話，agent-browser 指令參考）

然後使用 `agent-browser --auto-connect` 連線到使用者的 Chrome 瀏覽器，並執行以下任務：

[任務說明]

要發布的內容：
[內容]

重要事項：
- 始終先列出分頁（`tab list`）並重複使用已登入的現有分頁
- 在每次導覽或動作後重新快照
- 在提交/發布前與使用者確認（破壞性動作）
- 如果需要登入或出現 CAPTCHA，請停止並解釋

何時不使用子代理

• 單一平台 — 直接在目前對話中執行即可。
• 唯讀任務（瀏覽、搜尋、擷取資料）— 上下文使用較輕；單一對話可以處理 2-3 個平台。

---

平台參考

在特定平台上自動化任務時，請查閱相關參考文件以了解頁面結構細節、常見操作和已知問題：

平台	參考文件	重點說明
Reddit	references/reddit.md	自訂 faceplate-* 元件；永遠不會達到 networkidle；無標籤的留言文字框；find text 因重複元素而失敗
X (Twitter)	references/x.md	open 經常超時（使用 tab list 重複使用現有分頁）；點擊時間戳以查看貼文詳情（不是使用者名稱）；DraftJS contenteditable 輸入（data-testid="tweetTextarea_0"）；避免 networkidle
LinkedIn	references/linkedin.md	Ember.js SPA；Enter 提交留言（使用 Shift+Enter 換行）；留言框和撰寫框共用相同標籤；避免 networkidle；訊息覆蓋層可能阻擋內容
Dev.to	references/devto.md	快速的伺服器渲染 HTML（Forem/Rails）；留言/貼文使用標準 <textarea>（Markdown）；5 種反應類型；Algolia 驅動的搜尋；networkidle 正常運作
Hacker News	references/hackernews.md	極簡純 HTML；所有表單欄位均無標籤；link "reply" 導覽到獨立頁面；networkidle 立即生效；貼文/留言有速率限制

---

有關安裝和 Chrome 設定說明，請參閱 references/agent-browser-setup.md。