> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# 桌面端环境配置

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

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

## 配置桌面环境与系统权限 {#connect-device}

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

### 本机桌面权限与依赖

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

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

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

### 远程 Windows 桌面（RDP，可选）

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

Playground 只能控制本机显示器。若需在代码中连接远程 Windows 会话，请参阅[桌面端 JavaScript SDK 的 RDP 选项](/zh/sdk/desktop.md#rdp-选项)。

## 验证 {#verify}

完成上述权限授予和依赖安装后，在 Playground 中验证环境。打开[开始使用](/zh/get-started.md?platform=desktop\&scene=playground)，页面已为你选好桌面端和 Playground，选择模型接入方式后，按步骤执行一次 `aiAct` 操作和一次 `aiAssert` 断言。断言通过即表示屏幕截图、键鼠输入和模型调用都正常。

## 常见问题

### macOS：脚本无法移动鼠标或输入按键

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

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

### Windows：点击对某些程序不生效

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

解决方法：

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

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

### Linux：在无头服务器上截图或交互失败

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

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

在代码中开启：

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

或通过环境变量开启：

```bash
MIDSCENE_COMPUTER_HEADLESS_LINUX=true npx tsx example.ts
```