Electron 应用自动化

使用 agent-browser 自动化任何 Electron 桌面应用。Electron 应用基于 Chromium 构建，并暴露一个 Chrome DevTools 协议 (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 应用都支持 --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 标志必须在启动时存在。

连接

# 连接到特定端口
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*"

Webview 支持

Electron 的 <webview> 元素会被自动发现，并且可以像普通页面一样进行控制。使用 --native 模式时，网页视图会作为单独的目标出现在标签页列表中，类型为 type: "webview"：

# 以原生模式连接
agent-browser --native connect 9222

# 列出目标 -- 网页视图与页面一起出现
agent-browser tab
# 示例输出：
#   0: [page]    Slack - 主窗口     https://app.slack.com/
#   1: [webview] 嵌入内容        https://example.com/widget

# 切换到网页视图
agent-browser tab 1

# 正常与网页视图交互
agent-browser snapshot -i
agent-browser click @e3
agent-browser screenshot webview.png

注意： Webview 支持需要 --native 模式（原生 CDP）。基于 Playwright 的模式不支持 webview 目标。

常见模式

检查并导航应用

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 "搜索查询"
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 连接时，Playwright 默认会覆盖颜色方案为 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 snapshot -i -C 包含光标交互式元素（带有 onclick 处理程序的 div）

无法在输入字段中键入

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

支持的应用

任何基于 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 进行自动化。