• 简体中文

      • HarmonyOS 环境配置

      Midscene 通过 HarmonyOS Device Connector（HDC）连接并控制 HarmonyOS NEXT 设备，支持对原生应用、元服务及系统界面进行自动化操作。

      本文介绍运行 Midscene Test、JavaScript SDK 和 Playground 所需的 HarmonyOS 环境配置。你可以先通过 HDC 连接设备，再使用 Playground 验证屏幕截图、触控输入与模型调用。

      通过 HDC 连接设备

      运行 Midscene 的电脑需要通过 hdc 连接目标 HarmonyOS NEXT 设备。如果已安装 hdc 并连接好设备，可直接跳至确认设备连接。

      1. 安装 HDC

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

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

      hdc version

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

      配置 HDC 路径

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

      export HDC_HOME=/path/to/hdc/directory

      2. 开启调试并连接设备

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

      3. 确认设备连接

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

      hdc list targets

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

      0123456789ABCDEF

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

      在 Playground 中验证

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

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

      启动 Playground

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

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

      执行操作并验证结果

      在目标设备上打开系统浏览器，跳过首次启动引导，访问 TodoMVC，并保持设备处于解锁亮屏状态且浏览器位于前台。

      1. 在 Playground 中选择 aiAct，输入以下指令并运行：
      添加一个名为“体验 Midscene”的待办事项，然后将它标记为已完成。
      1. 待页面中出现已勾选完成的待办事项后，切换到 aiAssert，输入以下断言并运行：
      列表中存在名为“体验 Midscene”的待办事项，且它已被标记为完成。
      1. 确认断言执行通过，并在结果面板中查看各步骤的截图与执行过程。至此，设备连接、屏幕截图、触控输入和模型调用均已验证完毕。

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

      清理体验数据

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

      效果展示

      提示词： 打开设置，找到“关于手机”，查看设备信息。（完整报告）

      在测试或脚本中使用

      完成设备连接与 Playground 验证后，即可将设备接入你的测试或脚本项目：

      已准备项在项目中如何使用
      HDC 连接与调试授权保持设备连接、解锁亮屏，并保留 USB 调试授权。
      目标设备 ID在 Midscene Test 的 HarmonyOS 模板中通过 HARMONY_DEVICE_ID 指定，或在代码中通过 HarmonyOS SDK 参数传入。
      模型配置写入项目的 .env 文件并按集成文档加载。Playground 中的设置仅保存在本地浏览器内，不会自动同步到项目中。

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

      常见问题

      输入文本后键盘未收起，或页面意外返回

      请参阅 HarmonyOS JavaScript SDK。

      模型调用失败

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

      高级连接与调试

      如何指定自定义的 HDC 路径？

      可以通过 HDC_HOME 环境变量指定 hdc 所在的目录：

      export HDC_HOME=/path/to/hdc/directory

      通过代码参数传入的方式请参阅 HarmonyOS JavaScript SDK。