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

# 开始使用：桌面端 · Playground · ChatGPT 订阅 {#get-started}

本页是在**桌面端**上使用 **Playground**、通过 **ChatGPT 订阅**接入模型的配置步骤。如需其他组合，请查看[全部配置路径](/zh/get-started.md#all-setup-paths)。

## 授予桌面系统权限
- **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 时，请确保被测应用同样启动在该虚拟显示器环境中（本机带有物理显示器时无需开启此项）。
如需通过 RDP 控制远程 Windows 桌面，请参阅[桌面端环境配置](/zh/platforms/desktop.md#connect-device)。

## 使用 ChatGPT 订阅登录

登录命令需要 Node.js `^20.19.0 || ^22.12.0 || >=24.0.0` 和 pnpm。请确认终端中可以执行 `node -v`；如果尚未安装 pnpm，请运行 `npm install -g pnpm`。

首先，在终端运行：

```bash
pnpm dlx @midscene/cli model siwc login
```

按照终端提示，在浏览器中登录 ChatGPT 并授权使用订阅额度。授权时可以自行设置 Agent 名称；完成后，可在 ChatGPT 的使用情况页面查看已授权的 Agent。

命令会将凭据保存到 `~/.midscene/siwc.json`。首次使用前需要手动完成这一步登录。

Playground 会读取该命令保存的凭据。请先保留以下配置，后面的步骤会把它粘贴到 Playground 设置中：

```bash
MIDSCENE_MODEL_AUTH_MODE="siwc"
MIDSCENE_MODEL_NAME="gpt-6-sol"
MIDSCENE_MODEL_FAMILY="gpt-6"
```
可用模型以你的 ChatGPT 账号为准。凭据与额度说明请参阅[使用 ChatGPT 订阅](/zh/chatgpt-subscription.md#额度与凭据)。

## 启动 Playground

请确保已安装 Node.js（版本要求 `^20.19.0 || ^22.12.0 || >=24.0.0`），且终端中可正常执行 `node -v`。下方命令使用 pnpm，如果尚未安装，请运行 `npm install -g pnpm`。

1. 在终端运行以下命令启动桌面端 Playground：

```bash
pnpm dlx @midscene/computer-playground
```

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

```bash
MIDSCENE_COMPUTER_HEADLESS_LINUX=true pnpm dlx @midscene/computer-playground
```

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

## 执行操作并验证结果

在目标显示器上打开一个浏览器窗口，在地址栏中输入以下 TodoMVC 地址：

```text
https://todomvc.com/examples/react/dist/#/
```

调整窗口位置，避免 Playground 页面遮挡住 TodoMVC 页面。

1. 在 Playground 中选择 `aiAct`，输入以下指令并运行（运行期间请勿手动移动鼠标或操作键盘）：

```text
添加一个名为“体验 Midscene”的待办事项，然后将它标记为已完成。
```

2. 待页面中出现已勾选完成的待办事项后，切换到 `aiAssert`，输入以下断言并运行：

```text
列表中存在名为“体验 Midscene”的待办事项，且它已被标记为完成。
```

3. 确认断言执行通过，并在结果面板中查看各步骤的截图与执行过程。至此，桌面截图、键鼠输入和模型调用均已验证完毕。

4. （可选）切换到 `aiQuery`，输入以下查询并运行：

```text
列表中可见的待办事项，返回 {name: string, completed: boolean}[]。
```

结果会包含待办事项名称及其完成状态。`aiQuery` 用于从当前界面提取数据，不会修改页面。

如果执行失败，请结合报错信息排查：若无画面或无法操控鼠标键盘，请查看[常见问题](/zh/platforms/desktop.md#常见问题)；若模型请求报错，请参考[模型连接检查](/zh/model-config.md#verify-model-connectivity)。

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

## 下一步
- **查看更多案例**：[案例展示](/zh/showcases.md)收录了各平台的演示视频和完整执行报告。

- **编写可重复运行的用例**：使用相同的平台和模型[创建 Midscene Test 项目](/zh/get-started/desktop-test-chatgpt.md)。用例是 YAML 文件，可以在本地或 CI 中运行。

- **接入 Vitest**：使用相同的平台和模型，[在 Vitest 测试中调用 Midscene](/zh/get-started/desktop-sdk-chatgpt.md)。

- **了解 Midscene 的工作方式**：[基本概念](/zh/basics.md)介绍了基于视觉的方案，以及 `aiAct`、即时操作和洞察类 API 的适用场景。