瀏覽器自動化：companion 擴充套件與 Playwright 外掛

CoS 有兩條瀏覽器自動化路線：companion 擴充套件在你的 Chromium 瀏覽器裡用背景分頁工作；Playwright Browser 外掛則是另一個由 Plugins 連接器帶進來的 headless 路線。這篇先走完第一條，再說明分界。

情境

receipt-cli 的預覽頁 /checkout 有一個「確認」按鈕，同事回報它「數量與單價都填了還是灰的」。你要 ChatGPT 用瀏覽器工具找出原因。

前提：companion 擴充套件已載入（ChatGPT 頁面上的配對是自動的，沒有配對碼要輸入）；開發伺服器可以用長指令與開發伺服器的方式先跑起來。

目標

讓 ChatGPT 在瀏覽器裡重現問題、從 DOM 狀態與 console 找出讓按鈕維持 disabled 的確切條件，先診斷、不急著修。

步驟：給 ChatGPT 的 prompt

The dev server is running at http://localhost:3000.

Use the browser tools to open /checkout, then find out why the confirm
button stays disabled after I set a quantity and a price.

Read the DOM state of the button and the form, check the console for
errors, and tell me the exact condition that keeps the button disabled.
Don't fix anything yet — diagnose first.

預期的工具呼叫序列

1. <browser bridge: 開背景分頁 http://localhost:3000/checkout>
2. <browser bridge: 讀取表單的 DOM／accessibility 狀態>
3. <browser bridge: 設定 quantity 與 price 兩個輸入值>
4. <browser bridge: 讀取 confirm 按鈕元素（disabled、相關屬性）>
5. <browser bridge: 讀取 console 訊息／頁面錯誤>
6. <browser bridge: 截圖>
7. read(paths: ["src/web/checkout.tsx"])   # 回到檔案面比對

瀏覽器工具的實際名稱由 companion bridge 提供，會隨擴充套件版本不同；上表用能力描述代替，避免記錯名稱。分辨方式很簡單：由擴充套件而來的工具，其主體是「你正在登入的瀏覽器分頁」。

這裡發生了什麼

• 螢幕／控制權限同時會在 Chromium 主機上啟用 companion 的背景瀏覽器工具。瀏覽器擴充套件會向 Chrome 取得所需的 debugger／tabs 與 HTTP(S) 主機權限；沒有額外的每分頁核准對話框——所以瀏覽器工具在你的真實瀏覽器裡工作，請不要在它運作時和它搶同一批分頁。
• Read-only 模式會停用瀏覽器輸入、導覽、開關分頁與頁面 JavaScript。 因此像這種「需要執行頁面腳本才能診斷」的任務，不能開 Read-only；反過來說，純閱讀頁面內容的任務可以靠它降風險。
• 第 4、5 步是關鍵：按鈕的 disabled 條件、表單 state 是否同步、console 有沒有丟錯，這三條線索合起來，通常比讀十遍原始碼快。
• 診斷完成後，修復走一般流程：apply_patch 改 checkout.tsx，重新載入頁面，再用瀏覽器工具親眼確認按鈕狀態。

什麼時候改用 Playwright 外掛

如果你的需求是「可重現的腳本化流程」而不是「操作我眼前這個瀏覽器」，把工作交給 Playwright Browser 外掛更合適：

• 它是 Plugins catalog 中的 pinned npm recipe，需要 Node.js／npm 在對應位置安裝。
• 外掛走獨立的 Plugins 連接器與獨立的 tunnel，與 Core／Desktop 的權限邊界分開。
• Read-only 模式會拒絕外部外掛呼叫，因為上游註解無法證明外部程序不會改動狀態。
• 安裝與自訂伺服器的流程見自訂外掛與 MCPB 打包，權限邊界的原理見工具表面與權限。

驗收方式

• ChatGPT 說得出讓按鈕維持 disabled 的確切條件（例如 disabled 條件讀了錯誤的 state 欄位），並附上它讀到的 DOM 值與 console 訊息。
• 修好後重新載入頁面，按鈕狀態在你眼前改變。

注意事項

• 擴充套件更新後有兩個動作：重新載入 unpacked 的 companion，然後重新整理 ChatGPT 頁面。少做一步就會遇到工具版本不符或工具看起來壞掉。
• 瀏覽器 bridge port 預設 Auto（依序試 8765–8769）；固定選埠若被占用不會靜默改用別的埠。
• 瀏覽器自動化仍然受 provider 條款約束：這不是公開的 ChatGPT 自動化 API，MCP 可用也不等於所有自動化流程都被授權。