electron

用途

该技能用于自动化 Electron 桌面应用。Electron 应用基于 Chromium 构建，会暴露一个 Chrome DevTools Protocol（CDP）端口，agent-browser 可以连接该端口，从而复用与网页相同的快照-交互工作流。

核心工作流

以启用远程调试的方式启动 Electron 应用
将 agent-browser 连接到 CDP 端口
快照以发现可交互元素
使用元素引用进行交互
在导航或状态变化后重新快照

# 以远程调试方式启动 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 应用

由于 --remote-debugging-port 标志内置于 Chromium，每个 Electron 应用都支持它。

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

连接后，后续所有命令都会指向已连接的应用，无需再指定 --cdp。

标签页管理

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

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

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

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

Webview 支持

Electron 的 <webview> 元素会被自动发现，并可像普通页面一样控制。Webview 会作为单独目标出现在标签页列表中，类型为 webview：

# 连接到正在运行的 Electron 应用
agent-browser connect 9222

# 列出目标 —— webview 与页面一同出现
agent-browser tab
# 示例输出：
#   0: [page]    Slack - Main Window     https://app.slack.com/
#   1: [webview] Embedded Content        https://example.com/widget

# 切换到某个 webview
agent-browser tab 1

# 像普通页面一样与 webview 交互
agent-browser snapshot -i
agent-browser click @e3
agent-browser screenshot webview.png

注意：Webview 支持通过原始 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 连接时默认配色方案可能为浅色。要保留深色模式：

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 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 自动化。