• 简体中文

      • 桌面端环境配置

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

      本文介绍运行 Midscene Test、JavaScript SDK 和 Playground 所需的桌面端环境配置。你可以先配置桌面环境与系统权限，再使用 Playground 验证屏幕截图、键鼠输入与模型调用。

      配置桌面环境与系统权限

      运行 Midscene 需要具备目标桌面的屏幕截图与键鼠控制能力。请根据使用场景配置本机桌面或远程 Windows 桌面（RDP）；如果所需系统权限与依赖已配置妥当，可直接跳至在 Playground 中验证。

      1. 本机桌面权限与依赖

      • 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 时，请确保被测应用同样启动在该虚拟显示器环境中（本机带有物理显示器时无需开启此项）。

      2. 远程 Windows 桌面（RDP，可选）

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

      注意：下文的 Playground 验证针对本机显示器；若需在代码中连接远程 Windows 会话，请参阅桌面端 JavaScript SDK 的 RDP 选项。

      在 Playground 中验证

      借助 Playground，无需编写代码即可验证屏幕截图、键鼠输入与模型调用。

      开始前，请参照使用模型 API Key或使用 ChatGPT 订阅准备好模型配置。

      启动 Playground

      请确保已安装 Node.js（版本要求 ^20.19.0 || ^22.12.0 || >=24.0.0），且终端中可正常执行 node -v 和 npx --version。

      1. 在终端运行以下命令启动桌面端 Playground：
      npx --yes @midscene/computer-playground

      无头 Linux 环境请使用以下命令启动虚拟显示器，并确保目标应用也在同一虚拟显示器中运行：

      MIDSCENE_COMPUTER_HEADLESS_LINUX=true npx --yes @midscene/computer-playground
      1. 在打开的 Playground 页面中，点击右上角的齿轮图标，粘贴模型配置并保存。
      2. 若浏览器未自动打开，请手动访问终端打印的本地地址，并保持该终端进程持续运行。
      3. 在左侧连接面板的 Display 下拉框中选择要控制的显示器并创建 Agent，同时将待操作的目标应用窗口移至该显示器上。
      4. 确认预览区域已正常显示所选显示器的实时桌面画面；若画面黑屏或报错，请先排查上方的系统屏幕录制权限或依赖项。

      执行操作并验证结果

      在目标显示器上打开一个浏览器窗口，访问 TodoMVC，并调整窗口位置，避免 Playground 页面遮挡住目标 TodoMVC 页面。

      1. 在 Playground 中选择 aiAct，输入以下指令并运行（运行期间请勿手动移动鼠标或操作键盘）：
      添加一个名为“体验 Midscene”的待办事项，然后将它标记为已完成。
      1. 待页面中出现已勾选完成的待办事项后，切换到 aiAssert，输入以下断言并运行：
      列表中存在名为“体验 Midscene”的待办事项，且它已被标记为完成。
      1. 确认断言执行通过，并在结果面板中查看各步骤的截图与执行过程。至此，桌面截图、键鼠输入和模型调用均已验证完毕。

      如果执行失败，请结合报错信息排查：若无画面或无法操控鼠标键盘，请查看下方的常见问题；若模型请求报错，请参考模型连接检查。

      清理体验数据

      验证结束后，请在 TodoMVC 页面中删除刚才创建的“体验 Midscene”待办事项。如果接下来要运行 Midscene Test 的桌面端示例，请切换到 All 视图并确认列表已完全清空（包括已完成事项），因为示例模板在运行前会校验初始列表为空，且不会主动覆盖已有数据。

      效果展示

      提示词（macOS）： 打开 Safari，发布一条介绍 Midscene 支持 AutoGLM 的推文，并使用“下载”文件夹中的 AutoGLM 视频。（完整报告）

      在测试或脚本中使用

      完成桌面截图与键鼠输入验证后，即可将桌面环境接入你的测试或脚本项目：

      已准备项在项目中如何使用
      桌面权限与依赖确保运行项目的终端或 IDE 具备屏幕录制与辅助功能权限；无头 Linux 环境需保持虚拟显示器配置。
      目标显示器在 Midscene Test 的桌面端模板中通过 COMPUTER_DISPLAY_ID 指定显示器，或在代码中通过桌面端 SDK 参数传入。
      模型配置写入项目的 .env 文件并按集成文档加载。Playground 中的设置仅保存在本地浏览器内，不会自动同步到项目中。

      根据使用场景选择下一步：

      常见问题

      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 模式：

      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

      模型调用失败

      请查看失败步骤的报错信息，并核对 Playground 设置或项目 .env 文件中的模型配置。设备连接正常并不代表模型服务可用，可参照模型连接检查排查 API Key、服务地址或网络问题。注意，命令行与项目运行不会读取浏览器中保存的 Playground 配置，需单独加载项目的环境变量。