electron

Overview

What the electron skill does

electron 技能讓 agent 可以透過 agent-browser 和 Chrome DevTools Protocol (CDP) 自動化現有的 Electron 桌面應用程式。許多常用工具如 VS Code、Slack、Discord、Figma、Notion 和 Spotify 都是以 Electron 開發，並在內部執行 Chromium。只要開啟 DevTools port，就能像在瀏覽器中操作網站一樣控制它們。

使用這個技能，agent 可以：

• 啟動啟用了 remote debugging 的 Electron 應用程式
• 透過 agent-browser 連線到該應用程式的 CDP port
• 取得目前 UI 狀態的 快照（snapshot）
• 以穩定的元素參照來互動（點擊、輸入、導覽）
• 在狀態改變後重新擷取快照，以延續多步驟的工作流程

Who this skill is for

在以下情境下適合使用 electron 技能：

• 需要自動化 Electron 桌面 app 內部的流程（例如傳送 Slack 訊息、在 Notion 空間中導覽、觸發 VS Code 指令）
• 想把 Electron app 納入端到端測試或回歸檢查中
• 需要跨應用程式的工作流程自動化，把 Electron app 和 Web 自動化一起使用
• 偏好基於 CDP 的 CLI 自動化，而不是 GUI 錄製工具或專有 API

它特別適合以下類型的團隊與個人：

• 已習慣在 macOS、Linux 使用 Bash 執行 shell 指令
• 曾使用過 agent-browser 或類似的 CDP 工具
• 願意把 Electron app 視為「瀏覽器目標」，而不是直接 script 原生 OS 的元件

When electron is not a good fit

以下情況就不太適合使用 electron 技能：

• 想控制的應用程式不是 Electron app，且不會對外提供 DevTools port
• 需要在應用程式視窗之外做深層的 OS 層級操作（系統對話框、不由 Electron 繪製的檔案選擇器等）
• 想要的是開發 Electron app（這個技能是用來自動化既有 app，而不是開發新 app）
• 需要完全免終端機、純 GUI 的自動化工具

在這些情況下，你可能需要其他桌面自動化工具或 OS 原生 script 解決方案。

How the automation model works

在底層，electron 技能沿用 agent-browser Web 自動化中的 snapshot/interact 模型：

1. 使用 --remote-debugging-port 啟動 Electron app，讓它對外提供 CDP
2. 從 agent-browser 連線到該 port
3. 使用 Snapshot 擷取當前 DOM / 可存取性樹狀結構
4. 透過 agent-browser 指令與元素參照來互動 UI 元素
5. 每次重大狀態或頁面變化後再次 Re-snapshot

因為是基於 CDP，agent 看到的應用程式就像一個瀏覽器頁面，可以在多個 session 之間建立可重現、可 script 的流程。

How to Use

1. Install the electron skill

要讓 electron 技能在你的 agent 執行環境中可用，請從 vercel-labs/agent-browser repository 安裝：

npx skills add https://github.com/vercel-labs/agent-browser --skill electron

這會拉下 electron 技能定義，讓 agent 可以使用：

• Bash(agent-browser:*)
• Bash(npx agent-browser:*)

你也應該已安裝好 agent-browser，或能透過 npx 使用，這樣此技能所需的指令才能成功執行。

2. Confirm prerequisites

在執行依賴 electron 技能的流程之前，請確認：

• 你有 macOS 或 Linux，且可以在 shell 中執行 open、bash 或同類指令
• 目標應用程式確實是 Electron-based（例如 Slack、VS Code、Discord、Figma、Notion、Spotify 等）
• 你可以在啟動該應用程式時加入 --remote-debugging-port flag（這是 Chromium/Electron 內建的功能）

如果無法用該 flag 啟動應用程式，agent 就無法透過 CDP 連線。

3. Launch an Electron app with CDP enabled

核心需求是用遠端除錯 port 啟動應用程式：

# Example: Slack on macOS
open -a "Slack" --args --remote-debugging-port=9222

同樣的方式也適用於其他 Electron app；只要依需求調整應用程式名稱即可。

啟動後，應用程式會在指定的 port（此例為 9222）上對外提供 CDP endpoint。

4. Connect agent-browser to the running app

在應用程式以 remote debugging 模式執行後，使用 agent-browser 連線：

agent-browser connect 9222

成功連線後，你就可以對該 Electron 視窗執行標準的 snapshot 與互動指令。

5. Run the standard snapshot–interact workflow

現在你可以把這個 Electron app 當成瀏覽器頁面來操作：

# Discover interactive elements
agent-browser snapshot -i

# Click a specific element reference (example: @e5)
agent-browser click @e5

# Capture a screenshot of the current window
agent-browser screenshot slack-desktop.png

在典型的 agent 執行流程中，agent 會：

• 呼叫 snapshot 了解目前 UI 狀態
• 依元素參照（例如 @e5、@e12）選擇要點擊或輸入的元素
• 在任何重大變化（導覽、開啟/關閉 modal 等）後再次使用 snapshot

6. Integrate into larger desktop and workflow automation

electron 技能在需要串聯多個應用程式時特別有用。例如，agent 可以：

• 先從 Chrome 中的 Web app 取得資料
• 再開啟 Slack（Electron）並貼上一則格式化好的狀態訊息
• 接著切換到 VS Code（Electron）觸發 build 或執行 task

由於一切都透過 CDP 和 agent-browser 進行，你可以在 CLI 中 script 這些流程，或交由基於 LLM 的 agent 自動協調。

7. Adapting to your environment

雖然 repository 中的範例著重在通用的 Electron 模式，你可以依自己的環境做調整，包括：

• 應用程式（Slack、Discord、Notion、自家開發的 Electron 工具等）
• 連接埠（選擇可用的 port；9222 很常見，但不是唯一選項）
• OS 指令（在 macOS 使用 open，在 Linux 則使用相對應的啟動指令）

每當你調整啟動指令時，都要保留 --remote-debugging-port flag，這樣 electron 技能才能透過 agent-browser 順利連線。

FAQ

Is the electron skill only for Slack and VS Code?

不是。只要是能用 --remote-debugging-port 啟動的 任何 Electron app，都可以搭配 electron 技能使用。Slack 和 VS Code 只是常見範例，同樣的模式也適用於 Discord、Figma、Notion、Spotify 以及其他眾多基於 Electron 的工具。

How does electron know it is talking to an Electron app and not a website?

從自動化的角度來看，Electron app 會提供一個與 Chromium 瀏覽器類似的 Chrome DevTools Protocol 介面。一旦連上指定的 port，agent-browser 就會把目標當成瀏覽器頁面來操作。electron 技能只是假設該 port 對應到一個基於 Electron 的 Chromium 實例。

Do I need to modify the Electron app’s source code?

不需要。你不必修改應用程式原始碼。只要在啟動既有 app 時加上 --remote-debugging-port flag，讓 CDP 能對外使用即可。只要 OS 的啟動指令允許額外參數，這對於已封裝、現成安裝的 Electron 應用程式同樣適用。

Can the electron skill automate system dialogs or non-Electron windows?

electron 技能專注在可透過 CDP 存取、由 Chromium 支援的 Electron 視窗。OS 原生對話框或非 Electron 的視窗通常不會透過這個介面呈現。若要自動化這類操作，你會需要另一套 OS 層級的自動化工具。

What commands does the skill rely on?

依據技能的 metadata，electron 可以使用：

• Bash(agent-browser:*)
• Bash(npx agent-browser:*)

這代表 agent 可以直接或透過 npx 執行 agent-browser 指令，包括 connect、snapshot、click、screenshot 以及其他支援的子指令。

How do I troubleshoot connection issues on the CDP port?

如果 agent 無法連線，請檢查：

• 應用程式是否以 --remote-debugging-port=<port> 啟動
• agent-browser connect 使用的 port 是否與啟動指令一致
• 是否只啟動了一個應用程式實例；關閉多餘實例後再以 debugging flag 重新啟動

如果該 port 被阻擋或已被占用，請改用其他可用的 port，並同時更新啟動指令與 connect 指令中的 port 編號。

When should I choose another skill instead of electron?

你應該在以下情況選擇其他技能，而不是 electron：

• 目標是一般的 瀏覽器網站（此時應該使用專注於瀏覽器自動化的技能）
• 需要 OS 層級的操作，例如檔案管理、系統偏好設定或非 Electron app
• 主要是在開發（build）而非自動化 Electron 應用程式

electron 技能最適合在你明確需要把既有的 Electron 桌面 app 納入 CDP 型自動化，並作為更大範圍桌面或工作流程自動化的一部分時使用。