桌面端环境配置

Midscene 通过系统原生键鼠事件或远程桌面协议（RDP），支持在 Windows、macOS 和 Linux 上自动化操控各类桌面应用（如 Electron、Qt、原生客户端及跨应用工作流），并支持多显示器切换。

本文介绍如何准备桌面端环境：授予屏幕截图与键鼠控制权限，并在 Linux 上安装所需依赖。Playground、Midscene Test 和 JavaScript SDK 都依赖这些配置。

配置桌面环境与系统权限

运行 Midscene 需要具备目标桌面的屏幕截图与键鼠控制能力。请根据使用场景配置本机桌面或远程 Windows 桌面（RDP）。

macOS：需要为启动 Playground 或运行脚本的终端 / IDE（如 Terminal、iTerm2、VS Code、Cursor、WebStorm 等）授予两项独立的系统权限：
1. 辅助功能权限（用于控制鼠标与键盘）：前往「系统设置 > 隐私与安全性 > 辅助功能」开启对应应用的开关（详见 nut.js macOS 配置说明）。
2. 屏幕录制权限（用于截取桌面画面）：前往「系统设置 > 隐私与安全性 > 屏幕录制」开启对应应用的开关。授权后请完全退出并重启该终端或 IDE，再启动 Playground。
Windows：操作常规权限的桌面程序无需额外配置。但受 Windows 用户界面特权隔离（UIPI）机制限制，未提权的普通进程无法向「以管理员身份运行」的高权限窗口注入鼠标点击或按键事件（光标仍能移动到目标位置，但点击和按键会被系统静默丢弃）。建议优先以普通权限启动被测程序；若被测程序必须以管理员身份运行，请同样以管理员身份启动运行 Midscene 的终端或 Node.js 进程（详见下方常见问题）。
Linux（图形桌面）：需安装 ImageMagick 以提供截图能力。
Linux（无头服务器 / CI 环境）：在没有物理显示器的 Linux 服务器（如 GitHub Actions）上运行时，需安装 Xvfb 与 ImageMagick，并开启无头（Headless）模式自动创建虚拟显示器：

# 安装依赖
sudo apt-get install -y xvfb x11-xserver-utils imagemagick

使用 Xvfb 时，请确保被测应用同样启动在该虚拟显示器环境中（本机带有物理显示器时无需开启此项）。

如果需要通过 RDP 控制远程 Windows 桌面，请在运行 Midscene 的宿主机上安装 FreeRDP，并在目标 Windows 机器上开启远程桌面服务。

Playground 只能控制本机显示器。若需在代码中连接远程 Windows 会话，请参阅桌面端 JavaScript SDK 的 RDP 选项。

完成上述权限授予和依赖安装后，在 Playground 中验证环境。打开开始使用，页面已为你选好桌面端和 Playground，选择模型接入方式后，按步骤执行一次 aiAct 操作和一次 aiAssert 断言。断言通过即表示屏幕截图、键鼠输入和模型调用都正常。

在 macOS 上控制鼠标和键盘需要授予辅助功能权限。请前往「系统设置 > 隐私与安全性 > 辅助功能」，确认运行脚本的终端或 IDE（如 Terminal、iTerm2、VS Code、Cursor 或 WebStorm）已开启权限。

如果开关已开启但仍然无法控制，请先将该应用从辅助功能列表中移除（点击减号 -），重新添加后再重启该应用——macOS 在应用更新后有时会缓存失效的旧权限签名。

如果鼠标光标能够准确移动到目标位置，但在某个特定程序窗口上点击或按键毫无反应（而在浏览器或记事本等其他程序中正常），请检查该目标程序是否正以管理员身份运行。Windows 的用户界面特权隔离（UIPI）机制会静默拦截由普通权限进程向管理员权限窗口发送的输入事件，且不会抛出任何系统报错。

解决方法：

推荐做法：以普通用户权限启动被测程序（取消勾选快捷方式属性中的「以管理员身份运行此程序」）。
备选做法：如果被测程序必须以管理员权限运行，请同样以管理员身份启动运行 Midscene 的终端（如 PowerShell、Windows Terminal 或 IDE），使两者处于同一权限级别。

注：像 Win+Tab 这类系统级快捷键由 Windows Shell 直接处理，不受目标窗口权限限制，因此可能会出现「系统快捷键有效、但窗口内点击无效」的现象。只要确认鼠标光标已移动到正确坐标但点击无响应，即可优先排查此权限问题。

无头 Linux 服务器（如 CI 容器）没有物理显示器，需先安装 Xvfb 与 ImageMagick，并在创建 Agent 时开启 headless 模式：

sudo apt-get install -y xvfb x11-xserver-utils imagemagick

在代码中开启：

const agent = await agentForComputer({ headless: true });

或通过环境变量开启：

MIDSCENE_COMPUTER_HEADLESS_LINUX=true npx tsx example.ts