vercel-labs/electron

Electron 앱 자동화

agent-browser를 사용하여 모든 Electron 데스크톱 앱을 자동화합니다. Electron 앱은 Chromium 기반으로 구축되어 Chrome DevTools Protocol(CDP) 포트를 노출하며, agent-browser가 이 포트에 연결하여 웹 페이지와 동일한 스냅샷-상호작용 워크플로를 사용할 수 있습니다.

핵심 워크플로

1. 원격 디버깅을 활성화한 상태로 Electron 앱 실행
2. agent-browser를 CDP 포트에 연결
3. 스냅샷으로 대화형 요소 찾기
4. 요소 참조를 사용하여 상호작용
5. 탐색 또는 상태 변경 후 다시 스냅샷

# 원격 디버깅으로 Electron 앱 실행
open -a "Slack" --args --remote-debugging-port=9222

# agent-browser를 앱에 연결
agent-browser connect 9222

# 이후 표준 워크플로
agent-browser snapshot -i
agent-browser click @e5
agent-browser screenshot slack-desktop.png

CDP로 Electron 앱 실행하기

모든 Electron 앱은 Chromium에 내장되어 있으므로 --remote-debugging-port 플래그를 지원합니다.

macOS

# Slack
open -a "Slack" --args --remote-debugging-port=9222

# VS Code
open -a "Visual Studio Code" --args --remote-debugging-port=9223

# Discord
open -a "Discord" --args --remote-debugging-port=9224

# Figma
open -a "Figma" --args --remote-debugging-port=9225

# Notion
open -a "Notion" --args --remote-debugging-port=9226

# Spotify
open -a "Spotify" --args --remote-debugging-port=9227

Linux

slack --remote-debugging-port=9222
code --remote-debugging-port=9223
discord --remote-debugging-port=9224

Windows

"C:\Users\%USERNAME%\AppData\Local\slack\slack.exe" --remote-debugging-port=9222
"C:\Users\%USERNAME%\AppData\Local\Programs\Microsoft VS Code\Code.exe" --remote-debugging-port=9223

중요: 앱이 이미 실행 중이라면 먼저 종료한 후 플래그와 함께 다시 실행하세요. --remote-debugging-port 플래그는 실행 시점에 반드시 포함되어야 합니다.

연결

# 특정 포트에 연결
agent-browser connect 9222

# 또는 각 명령어에 --cdp 사용
agent-browser --cdp 9222 snapshot -i

# 실행 중인 Chromium 기반 앱 자동 발견
agent-browser --auto-connect snapshot -i

connect 이후, 모든 후속 명령어는 --cdp 없이 연결된 앱을 대상으로 합니다.

탭 관리

Electron 앱은 여러 개의 창이나 웹뷰를 가질 수 있습니다. 탭 명령어를 사용하여 목록을 보고 전환하세요:

# 사용 가능한 모든 대상(창, 웹뷰 등) 나열
agent-browser tab

# 인덱스로 특정 탭으로 전환
agent-browser tab 2

# URL 패턴으로 전환
agent-browser tab --url "*settings*"

웹뷰 지원

Electron <webview> 요소는 자동으로 발견되며 일반 페이지처럼 제어할 수 있습니다. 웹뷰는 type: "webview"와 함께 탭 목록에 별도의 대상으로 나타납니다:

# 실행 중인 Electron 앱에 연결
agent-browser connect 9222

# 대상 나열 -- 웹뷰가 페이지와 함께 표시됨
agent-browser tab
# 예시 출력:
#   0: [page]    Slack - Main Window     https://app.slack.com/
#   1: [webview] Embedded Content        https://example.com/widget

# 웹뷰로 전환
agent-browser tab 1

# 웹뷰와 정상적으로 상호작용
agent-browser snapshot -i
agent-browser click @e3
agent-browser screenshot webview.png

참고: 웹뷰 지원은 raw CDP 연결을 통해 작동합니다.

일반적인 패턴

앱 검사 및 탐색

open -a "Slack" --args --remote-debugging-port=9222
sleep 3  # 앱이 시작될 때까지 대기
agent-browser connect 9222
agent-browser snapshot -i
# 스냅샷 출력을 읽어 UI 요소 식별
agent-browser click @e10  # 섹션으로 이동
agent-browser snapshot -i  # 탐색 후 다시 스냅샷

데스크톱 앱 스크린샷

agent-browser connect 9222
agent-browser screenshot app-state.png
agent-browser screenshot --full full-app.png
agent-browser screenshot --annotate annotated-app.png

데스크톱 앱에서 데이터 추출

agent-browser connect 9222
agent-browser snapshot -i
agent-browser get text @e5
agent-browser snapshot --json > app-state.json

데스크톱 앱에서 양식 작성

agent-browser connect 9222
agent-browser snapshot -i
agent-browser fill @e3 "search query"
agent-browser press Enter
agent-browser wait 1000
agent-browser snapshot -i

여러 앱 동시 실행

이름 있는 세션을 사용하여 여러 Electron 앱을 동시에 제어하세요:

# Slack에 연결
agent-browser --session slack connect 9222

# VS Code에 연결
agent-browser --session vscode connect 9223

# 각각 독립적으로 상호작용
agent-browser --session slack snapshot -i
agent-browser --session vscode snapshot -i

색상 구성

CDP로 연결할 때 기본 색상 구성은 light일 수 있습니다. 다크 모드를 유지하려면:

agent-browser connect 9222
agent-browser --color-scheme dark snapshot -i

또는 전역으로 설정:

AGENT_BROWSER_COLOR_SCHEME=dark agent-browser connect 9222

문제 해결

"연결 거부됨" 또는 "연결할 수 없음"

• 앱이 --remote-debugging-port=NNNN과 함께 실행되었는지 확인하세요.
• 앱이 이미 실행 중이었다면 종료하고 플래그와 함께 다시 실행하세요.
• 포트가 다른 프로세스에서 사용 중인지 확인: lsof -i :9222

앱이 실행되지만 연결 실패

• 연결하기 전에 몇 초 기다리세요. (sleep 3)
• 일부 앱은 웹뷰를 초기화하는 데 시간이 걸립니다.

스냅샷에 요소가 나타나지 않음

• 앱이 여러 웹뷰를 사용할 수 있습니다. agent-browser tab을 사용하여 대상을 나열하고 올바른 대상으로 전환하세요.

입력 필드에 입력할 수 없음

• agent-browser keyboard type "text"를 사용하여 선택자 없이 현재 포커스에 입력하세요.
• 일부 Electron 앱은 사용자 정의 입력 구성 요소를 사용합니다. agent-browser keyboard inserttext "text"를 사용하여 키 이벤트를 우회하세요.

지원되는 앱

Electron 기반으로 구축된 모든 앱이 작동하며, 다음을 포함합니다:

• 커뮤니케이션: Slack, Discord, Microsoft Teams, Signal, Telegram Desktop
• 개발: VS Code, GitHub Desktop, Postman, Insomnia
• 디자인: Figma, Notion, Obsidian
• 미디어: Spotify, Tidal
• 생산성: Todoist, Linear, 1Password

앱이 Electron으로 구축되었다면 --remote-debugging-port를 지원하며 agent-browser로 자동화할 수 있습니다.