electron

Overview

What the electron skill does

Kỹ năng electron cho phép một agent tự động hóa các ứng dụng desktop Electron hiện có bằng agent-browser và Chrome DevTools Protocol (CDP). Nhiều công cụ phổ biến như VS Code, Slack, Discord, Figma, Notion và Spotify được xây dựng bằng Electron và chạy trên Chromium bên trong. Bằng cách mở cổng DevTools, chúng có thể được điều khiển gần giống như một website trong trình duyệt.

Với kỹ năng này, agent có thể:

• Khởi chạy một ứng dụng Electron với chế độ remote debugging bật sẵn
• Kết nối tới cổng CDP của ứng dụng thông qua agent-browser
• Chụp snapshots để nắm được trạng thái UI hiện tại
• Tương tác với các phần tử (click, gõ, điều hướng) bằng các tham chiếu phần tử ổn định
• Chụp lại snapshot sau khi trạng thái thay đổi để tiếp tục các quy trình nhiều bước

Who this skill is for

Hãy dùng kỹ năng electron nếu bạn:

• Cần tự động hóa quy trình bên trong một ứng dụng desktop Electron (ví dụ: gửi tin nhắn Slack, điều hướng trong workspace Notion, kích hoạt lệnh trong VS Code)
• Muốn đưa các ứng dụng Electron vào bài kiểm thử end-to-end hoặc kiểm thử hồi quy
• Cần tự động hóa quy trình cross-app, kết hợp ứng dụng Electron với tự động hóa web
• Ưu tiên tự động hóa qua CLI dựa trên CDP thay vì các công cụ ghi thao tác GUI hoặc API đóng

Kỹ năng này phù hợp với các cá nhân và đội ngũ đã quen với:

• Chạy lệnh shell (macOS, Linux) qua Bash
• Sử dụng agent-browser hoặc các công cụ CDP tương tự
• Xem ứng dụng Electron như các “browser targets” thay vì script trực tiếp các widget native của hệ điều hành

When electron is not a good fit

Kỹ năng electron không phù hợp nếu:

• Ứng dụng bạn muốn điều khiển không phải Electron và không mở cổng DevTools
• Bạn cần tương tác sâu ở mức hệ điều hành ngoài cửa sổ ứng dụng (hộp thoại hệ thống, bộ chọn file không do Electron render, v.v.)
• Bạn muốn phát triển ứng dụng Electron (kỹ năng này dành cho tự động hóa ứng dụng sẵn có, không phải phát triển ứng dụng mới)
• Bạn cần công cụ tự động hóa hoàn toàn GUI, không đụng tới terminal

Trong các trường hợp đó, bạn nên cân nhắc giải pháp tự động hóa desktop hoặc scripting native khác.

How the automation model works

Ở tầng bên dưới, kỹ năng electron sử dụng mô hình snapshot/interact giống như tự động hóa web trong agent-browser:

1. Khởi chạy với --remote-debugging-port để ứng dụng Electron mở CDP
2. Kết nối tới cổng đó từ agent-browser
3. Snapshot để thu lại DOM / cây accessibility hiện tại
4. Interact với các phần tử UI bằng lệnh của agent-browser và các tham chiếu phần tử
5. Re-snapshot sau mỗi thay đổi trạng thái hoặc điều hướng quan trọng

Vì dựa trên CDP, agent sẽ “nhìn” ứng dụng tương tự như một trang trong trình duyệt, cho phép thiết lập các luồng script lặp lại, có thể tái sử dụng qua nhiều phiên.

How to Use

1. Install the electron skill

Để kỹ năng electron khả dụng trong môi trường agent của bạn, hãy cài nó từ repository vercel-labs/agent-browser:

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

Lệnh này sẽ tải định nghĩa kỹ năng electron và cho phép agent sử dụng:

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

Bạn cũng nên cài sẵn agent-browser hoặc có thể chạy nó qua npx để các lệnh mà kỹ năng này dựa vào có thể được thực thi.

2. Confirm prerequisites

Trước khi chạy các flow phụ thuộc vào kỹ năng electron, hãy kiểm tra:

• Bạn đang dùng macOS hoặc Linux với shell nơi có thể chạy open, bash hoặc lệnh tương đương
• Ứng dụng mục tiêu thực sự là Electron-based (Slack, VS Code, Discord, Figma, Notion, Spotify và nhiều ứng dụng khác)
• Bạn có thể khởi chạy ứng dụng với flag --remote-debugging-port (tính năng này có sẵn trong Chromium/Electron)

Nếu không thể khởi chạy ứng dụng với flag đó, agent sẽ không kết nối được qua CDP.

3. Launch an Electron app with CDP enabled

Yêu cầu cốt lõi là khởi chạy ứng dụng với remote debugging port:

# Ví dụ: Slack trên macOS
open -a "Slack" --args --remote-debugging-port=9222

Mẫu này áp dụng cho các ứng dụng Electron khác; chỉ cần thay tên ứng dụng cho phù hợp.

Sau khi khởi chạy, ứng dụng sẽ mở một endpoint CDP tại cổng được chỉ định (ở đây là 9222).

4. Connect agent-browser to the running app

Khi ứng dụng đang chạy với remote debugging, hãy kết nối bằng agent-browser:

agent-browser connect 9222

Sau khi kết nối thành công, bạn có thể chạy các lệnh snapshot và tương tác như thường lệ với cửa sổ ứng dụng Electron.

5. Run the standard snapshot–interact workflow

Giờ bạn có thể coi ứng dụng Electron gần như một trang web trong trình duyệt:

# Khám phá các phần tử có thể tương tác
agent-browser snapshot -i

# Click một phần tử cụ thể (ví dụ: @e5)
agent-browser click @e5

# Chụp screenshot cửa sổ hiện tại
agent-browser screenshot slack-desktop.png

Trong một workflow agent-run điển hình, agent sẽ:

• Gọi snapshot để hiểu trạng thái UI hiện tại
• Chọn phần tử bằng tham chiếu (ví dụ: @e5, @e12) để click hoặc nhập liệu
• Dùng lại snapshot sau mỗi thay đổi lớn (điều hướng, mở/đóng modal, v.v.)

6. Integrate into larger desktop and workflow automation

Kỹ năng electron đặc biệt hữu ích khi bạn cần xâu chuỗi nhiều ứng dụng với nhau. Ví dụ, một agent có thể:

• Lấy dữ liệu từ một web app trong Chrome
• Mở Slack (Electron) và đăng một status đã định dạng
• Chuyển sang VS Code (Electron) để kích hoạt build hoặc chạy một tác vụ

Vì mọi thứ đều chạy qua CDP và agent-browser, bạn có thể script toàn bộ từ CLI hoặc để một agent dùng LLM tự động điều phối.

7. Adapting to your environment

Các ví dụ trong repository tập trung vào pattern Electron chung, nhưng bạn nên điều chỉnh cách triển khai cho những đặc điểm cụ thể của mình:

• Ứng dụng (Slack, Discord, Notion, các công cụ Electron nội bộ của công ty, v.v.)
• Cổng (chọn một cổng trống; 9222 là lựa chọn phổ biến nhưng không bắt buộc)
• Lệnh hệ điều hành (dùng open trên macOS, và lệnh khởi chạy phù hợp trên Linux)

Bất cứ khi nào chỉnh sửa lệnh khởi chạy, hãy giữ nguyên flag --remote-debugging-port để kỹ năng electron vẫn có thể kết nối qua agent-browser.

FAQ

Is the electron skill only for Slack and VS Code?

Không. Kỹ năng electron hoạt động với bất kỳ ứng dụng Electron nào có thể được khởi chạy với --remote-debugging-port. Slack và VS Code chỉ là những ví dụ phổ biến; cùng một pattern này áp dụng cho Discord, Figma, Notion, Spotify và nhiều công cụ Electron khác.

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

Từ góc độ tự động hóa, ứng dụng Electron mở ra một giao diện Chrome DevTools Protocol tương tự như trình duyệt Chromium. Một khi đã kết nối tới cổng được chỉ định, agent-browser tương tác với target như thể đó là một trang trong trình duyệt. Kỹ năng electron đơn giản giả định rằng cổng đó tương ứng với một instance Chromium dựa trên Electron.

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

Không. Bạn không cần sửa mã nguồn của ứng dụng. Bạn chỉ cần khởi chạy ứng dụng hiện có với flag --remote-debugging-port để mở CDP. Điều này vẫn hoạt động với các ứng dụng Electron đóng gói, cài đặt sẵn, miễn là lệnh khởi chạy trên hệ điều hành cho phép truyền thêm đối số.

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

Kỹ năng electron tập trung vào các cửa sổ Electron được hỗ trợ bởi Chromium và truy cập được qua CDP. Các hộp thoại native của hệ điều hành hoặc cửa sổ ngoài Electron thường sẽ không hiển thị qua giao diện này. Để tự động hóa những phần đó, bạn sẽ cần một công cụ tự động hóa ở mức hệ điều hành riêng.

What commands does the skill rely on?

Theo metadata của kỹ năng, electron được phép sử dụng:

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

Điều này có nghĩa agent có thể chạy các lệnh agent-browser trực tiếp hoặc qua npx, bao gồm connect, snapshot, click, screenshot và các subcommand được hỗ trợ khác.

How do I troubleshoot connection issues on the CDP port?

Nếu agent không kết nối được:

• Kiểm tra xem ứng dụng đã được khởi chạy với --remote-debugging-port=<port> chưa
• Xác nhận số cổng dùng trong agent-browser connect trùng với cổng trong lệnh khởi chạy
• Đảm bảo chỉ có một instance của ứng dụng đang chạy; đóng các bản dư và khởi động lại với flag debugging

Nếu cổng bị chặn hoặc đã được sử dụng, hãy chọn một cổng trống khác và cập nhật cả lệnh khởi chạy lẫn lệnh connect.

When should I choose another skill instead of electron?

Hãy chọn kỹ năng khác khi:

• Mục tiêu là một website trong trình duyệt thông thường (hãy dùng kỹ năng chuyên cho tự động hóa browser)
• Bạn cần thao tác ở mức hệ điều hành như quản lý file, cài đặt hệ thống, hoặc ứng dụng không phải Electron
• Bạn chủ yếu đang xây dựng (develop) chứ không phải tự động hóa ứng dụng Electron

Kỹ năng electron phát huy hiệu quả nhất khi bạn muốn tự động hóa ứng dụng desktop Electron hiện có dựa trên CDP như một phần trong tự động hóa desktop hoặc workflow rộng hơn.