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

# 开始使用：HarmonyOS · Playground · 模型 API Key {#get-started}

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

## 连接 HarmonyOS 设备
运行 Midscene 的电脑需要通过 `hdc` 连接目标 HarmonyOS NEXT 设备。如果已安装 `hdc` 并连接好设备，可直接跳至[确认设备连接](#verify-device-connection)。

### 安装 HDC

HDC（HarmonyOS Device Connector）是 HarmonyOS 官方提供的设备连接命令行工具，可通过以下任一方式安装：

- 通过 [DevEco Studio](https://developer.huawei.com/consumer/cn/deveco-studio/) 安装（推荐）
- 下载 [HarmonyOS 命令行工具（Command Line Tools）](https://developer.huawei.com/consumer/cn/download/)独立安装

在终端运行以下命令，验证 `hdc` 是否安装成功：

```bash
hdc version
```

终端输出版本号即表示安装成功。

:::info 配置 HDC 路径

如果 `hdc` 未加入系统 `PATH`，可以通过设置 `HDC_HOME` 环境变量指向 `hdc` 所在的目录：

```bash
export HDC_HOME=/path/to/hdc/directory
```

:::

### 开启调试并连接设备

1. 在 HarmonyOS 设备的系统设置中进入「系统 > 开发者选项」，开启 **USB 调试**。
2. 使用支持数据传输的 USB 数据线将设备连接到电脑。
3. 保持设备解锁亮屏，并在设备弹窗中允许 USB 调试授权。

### 确认设备连接 {#verify-device-connection}

在终端运行以下命令检查连接状态：

```bash
hdc list targets
```

终端输出设备序列号（Device ID）即表示连接就绪：

```log
0123456789ABCDEF
```

如果同时连接了多台设备，请记录目标设备的序列号，以便后续在 Playground 或项目配置中指定该设备。若输出为空或显示 `[Empty]`，请检查 USB 数据线、连接模式、**USB 调试**开关及手机端的调试授权弹窗。

## 配置模型
在下方选择一个模型，它的配置包含四项。点击**获取 API Key**到服务商创建 API Key，再用它替换 `MIDSCENE_MODEL_API_KEY` 中的 `......`。

下方是 Doubao-Seed-2.1 Turbo 的配置。其他推荐模型：

- [Qwen3.7 Plus](/zh/model-api-setup.md#qwen) (阿里巴巴)
- [DeepSeek V4.1 Flash](/zh/model-api-setup.md#deepseek) (深度求索)
- [Gemini 3.5 Flash](/zh/model-api-setup.md#gemini) (Google)
- [GPT-6 Sol](/zh/model-api-setup.md#gpt) (OpenAI)
- [Kimi K3](/zh/model-api-setup.md#kimi) (月之暗面)
- [MiMo V2.6 Pro](/zh/model-api-setup.md#xiaomi-mimo) (小米)
- [GLM-5V-Turbo](/zh/model-api-setup.md#glm-v) (智谱)
- [Ling-3.0-flash-VL](/zh/model-api-setup.md#ant-ling) (蚂蚁集团)

**火山引擎** ([获取 API Key](https://console.volcengine.com/ark))

```bash
MIDSCENE_MODEL_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"
MIDSCENE_MODEL_API_KEY="......"
MIDSCENE_MODEL_NAME="doubao-seed-2-1-turbo-260628"
MIDSCENE_MODEL_FAMILY="doubao-seed"
```

**OpenRouter** ([获取 API Key](https://openrouter.ai/settings/keys))

```bash
MIDSCENE_MODEL_BASE_URL="https://openrouter.ai/api/v1"
MIDSCENE_MODEL_API_KEY="......"
MIDSCENE_MODEL_NAME="bytedance-seed/seed-2-1-turbo"
MIDSCENE_MODEL_FAMILY="doubao-seed"
```

其他版本与使用说明请参阅[豆包 Seed 系列](/zh/model-api-setup.md#doubao-seed-model)。

各模型的差异请参阅[模型选择指南](/zh/model-selection.md)。UI-TARS 等兼容模型请参阅[使用模型 API Key](/zh/model-api-setup.md#支持的模型)。

先保留这份配置，后面的步骤会把它粘贴到 Playground 中。

## 启动 Playground

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

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

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

2. 在打开的 Playground 页面中，点击右上角的齿轮图标，粘贴模型配置并保存。
3. 若浏览器未自动打开，请手动访问终端打印的本地地址，并保持该终端进程持续运行。
4. 在左侧连接面板中选择目标 HDC 设备并创建 Agent（设备 ID 与 `hdc list targets` 的输出一致）。
5. 确认预览区域已正常显示当前手机屏幕画面；若画面未显示，请先排查 HDC 连接与设备调试授权。

## 执行操作并验证结果

在目标设备上打开系统浏览器，跳过首次启动引导，然后在地址栏中输入以下 TodoMVC 地址：

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

保持设备处于解锁亮屏状态且浏览器位于前台。

1. 在 Playground 中选择 `aiAct`，输入以下指令并运行：

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

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

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

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

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

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

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

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

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

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

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

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

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