【Vercel实用Skill】electron 技能

使用agent-browser通过Chrome DevTools Protocol自动化Electron桌面应用（VS Code、Slack、Discord、Figma、Notion、Spotify等）。用于与Electron应用交互、自动化桌面应用、连接到运行中的应用、控制原生应用或测试Electron应用程序。

技能概述

electron 技能允许自动化任何基于Electron构建的桌面应用程序。由于Electron应用基于Chromium构建，它们暴露了一个Chrome DevTools Protocol（CDP）端口，agent-browser可以连接到该端口，从而实现与网页相同的快照-交互工作流程。这使得AI代理能够控制和自动化各种流行的桌面应用程序，如VS Code、Slack、Discord、Figma、Notion、Spotify等。

下载地址：https://github.com/vercel-labs/agent-browser

主要功能

• 应用启动：使用远程调试标志启动Electron应用
• CDP连接：连接到Electron应用的Chrome DevTools Protocol端口
• 元素快照：发现应用中的交互元素
• 元素交互：使用元素引用进行点击、填充等操作
• 标签管理：在多个窗口或webview之间切换
• 截图捕获：截取桌面应用的屏幕截图
• 数据提取：从桌面应用中提取文本和数据
• 表单填写：在桌面应用中填写表单
• 多应用控制：使用命名会话同时控制多个Electron应用
• 颜色方案：保持应用的深色模式设置
• 跨平台支持：支持macOS、Linux和Windows

触发条件

在以下情况下应该调用此技能：

• 用户需要与Electron应用交互
• 用户需要"自动化Slack应用"
• 用户需要"控制VS Code"
• 用户需要"与Discord应用交互"
• 用户需要"测试这个Electron应用"
• 用户需要"连接到桌面应用"
• 任何需要自动化原生Electron应用程序的任务

核心工作流程

标准自动化流程

每个Electron应用自动化都遵循以下模式：

1. 启动：使用远程调试启用标志启动Electron应用
2. 连接：将agent-browser连接到CDP端口
3. 快照：发现交互元素
4. 交互：使用元素引用进行操作
5. 重新快照：在导航或状态更改后获取新引用

处理过程

1. 启动Electron应用

每个Electron应用都支持--remote-debugging-port标志，因为它是Chromium内置的。

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标志必须在启动时存在。

2. 连接到应用

# 连接到特定端口 agent-browser connect 9222 # 或在每个命令上使用 --cdp agent-browser --cdp 9222 snapshot -i # 自动发现运行中的基于Chromium的应用 agent-browser --auto-connect snapshot -i

在connect之后，所有后续命令都针对已连接的应用，无需--cdp。

3. 标签管理

Electron应用通常有多个窗口或webview。使用标签命令在它们之间列出和切换：

# 列出所有可用目标（窗口、webview等）
agent-browser tab

# 按索引切换到特定标签
agent-browser tab 2

# 按URL模式切换
agent-browser tab --url "*settings*"

4. 检查和导航应用

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 # 导航后重新快照

输入要求

使用此技能时，用户需要提供：

• 应用名称：要自动化的Electron应用名称（如Slack、VS Code、Discord等）
• CDP端口（可选）：远程调试端口号，默认为9222
• 操作指令：具体的自动化操作（点击、填充、截图等）
• 会话名称（可选）：用于同时控制多个应用

输出说明

技能将提供：

• 应用快照：包含交互元素及其引用标识符的可访问性树
• 截图文件：PNG格式的应用截图
• 提取的文本：应用或元素的文本内容
• 应用状态：JSON格式的应用状态数据

使用示例

示例1：检查和导航应用

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 # 导航后重新快照

示例2：截取桌面应用截图

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

示例3：从桌面应用提取数据

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

示例4：在桌面应用中填写表单

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

示例5：同时运行多个应用

使用命名会话同时控制多个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

颜色方案

Playwright在通过CDP连接时默认将颜色方案覆盖为light。要保留深色模式：

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

或全局设置：

AGENT_BROWSER_COLOR_SCHEME=dark agent-browser connect 9222

故障排除

"Connection refused" 或 "Cannot connect"

• 确保应用使用--remote-debugging-port=NNNN标志启动
• 如果应用已经在运行，退出并使用标志重新启动
• 检查端口是否未被其他进程使用：lsof -i :9222

应用启动但连接失败

• 启动后等待几秒钟再连接（sleep 3）
• 某些应用需要时间初始化其webview

元素未出现在快照中

• 应用可能使用多个webview。使用agent-browser tab列出目标并切换到正确的目标
• 使用agent-browser snapshot -i -C包含光标交互元素（带有onclick处理程序的div）

无法在输入字段中输入

• 尝试agent-browser keyboard type "text"在当前焦点处输入，无需选择器
• 某些Electron应用使用自定义输入组件；使用agent-browser keyboard inserttext "text"绕过按键事件

支持的应用

任何基于Electron构建的应用都可以工作，包括：

如果一个应用是用Electron构建的，它支持--remote-debugging-port并且可以用agent-browser自动化。

最佳实践

1. 先退出再启动：如果应用已经在运行，必须先退出，然后使用--remote-debugging-port标志重新启动
2. 等待启动：启动应用后等待几秒钟（sleep 3）再连接，让应用有时间初始化
3. 使用命名会话：同时控制多个应用时，使用命名会话以避免冲突
4. 检查标签：Electron应用通常有多个窗口或webview，使用tab命令列出和切换
5. 重新快照：导航或状态更改后，重新获取快照以获得新的元素引用
6. 使用 -C 标志：如果元素未出现在快照中，使用snapshot -i -C包含光标交互元素
7. 键盘输入：对于自定义输入组件，使用keyboard type或keyboard inserttext而非fill
8. 保持深色模式：如果应用使用深色模式，设置AGENT_BROWSER_COLOR_SCHEME=dark

平台特定说明

macOS

使用open -a命令启动应用：

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

Linux

直接调用应用可执行文件：

slack --remote-debugging-port=9222

Windows

使用完整路径调用应用可执行文件：

"C:\Users\%USERNAME%\AppData\Local\slack\slack.exe" --remote-debugging-port=9222