harmonyos-device-automation

HarmonyOS 设备自动化

关键规则 — 违反规则会导致工作流中断：

1. 绝不要在后台运行 midscene 命令。 每条命令都必须同步运行，以便你在决定下一步操作之前读取其输出（尤其是截图）。后台执行会破坏截图分析操作循环。
2. 一次只能运行一条 midscene 命令。 等待上一条命令完成，读取截图，然后决定下一步操作。绝不要将多条命令串联执行。
3. 为每条命令留出足够的完成时间。 Midscene 命令涉及 AI 推理和屏幕交互，耗时可能比常规 shell 命令更长。常规命令大约需要 1 分钟；复杂的 act 命令可能需要更久。

使用 npx -y @midscene/harmony@1 自动化 HarmonyOS NEXT 设备。每条 CLI 命令都直接对应一个 MCP 工具——你（AI Agent）充当决策核心，根据截图决定要执行哪些操作。

act 可以做什么

在 HarmonyOS 上，单次 act 调用中，Midscene 可以点击、双击、长按、输入、清除文本、滚动、拖动项目、按键，以及使用返回、主页或最近任务等系统导航，同时根据当前可见屏幕进行操作。由于底层 HarmonyOS 自动化层不支持多点触控输入，因此无法进行双指缩放。

前提条件

Midscene 需要具备强视觉定位能力的模型。必须配置以下环境变量——可以将其设为系统环境变量，也可以放在当前工作目录中的 .env 文件里（Midscene 会自动加载 .env）：

MIDSCENE_MODEL_API_KEY="your-api-key"
MIDSCENE_MODEL_NAME="model-name"
MIDSCENE_MODEL_BASE_URL="https://..."
MIDSCENE_MODEL_FAMILY="family-identifier"

示例：Gemini（Gemini-3-Flash）

MIDSCENE_MODEL_API_KEY="your-google-api-key"
MIDSCENE_MODEL_NAME="gemini-3-flash"
MIDSCENE_MODEL_BASE_URL="https://generativelanguage.googleapis.com/v1beta/openai/"
MIDSCENE_MODEL_FAMILY="gemini"

示例：Qwen 3.5

MIDSCENE_MODEL_API_KEY="your-aliyun-api-key"
MIDSCENE_MODEL_NAME="qwen3.5-plus"
MIDSCENE_MODEL_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
MIDSCENE_MODEL_FAMILY="qwen3.5"
MIDSCENE_MODEL_REASONING_ENABLED="false"
# If using OpenRouter, set:
# MIDSCENE_MODEL_API_KEY="your-openrouter-api-key"
# MIDSCENE_MODEL_NAME="qwen/qwen3.5-plus"
# MIDSCENE_MODEL_BASE_URL="https://openrouter.ai/api/v1"

示例：Doubao Seed 2.0 Lite

MIDSCENE_MODEL_API_KEY="your-doubao-api-key"
MIDSCENE_MODEL_NAME="doubao-seed-2-0-lite"
MIDSCENE_MODEL_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"
MIDSCENE_MODEL_FAMILY="doubao-seed"

常用模型：Doubao Seed 2.0 Lite、Qwen 3.5、Zhipu GLM-4.6V、Gemini-3-Pro、Gemini-3-Flash。

如果尚未配置模型，请让用户进行设置。支持的提供商请参阅模型配置。

HDC 设置

必须安装并确保能够访问 HDC（HarmonyOS Device Connector）。常见设置方式：

• 通过 DevEco Studio 安装
• 或将 HDC_HOME 环境变量设为 HDC 目录的路径

验证 HDC 是否正常运行：

hdc version
hdc list targets

命令

连接设备

npx -y @midscene/harmony@1 connect
npx -y @midscene/harmony@1 connect --deviceId 0123456789ABCDEF

启动应用或 URL

如果希望在执行任务的其余步骤之前确定起始状态，请使用专用的启动步骤：

npx -y @midscene/harmony@1 launch --uri com.huawei.hmos.settings
npx -y @midscene/harmony@1 launch --uri com.huawei.hmos.camera
npx -y @midscene/harmony@1 launch --uri https://www.example.com

运行原始 HarmonyOS Shell 命令

如果任务需要通过更底层的设备控制来完成，而不适合用可见 UI 交互表达，请使用此命令：

npx -y @midscene/harmony@1 runhdcshell --command "hidumper -s RenderService -a screen"

此命令会转发到已连接设备上的 hdc shell。实际上，底层命令为 hdc -t <deviceId> shell hidumper -s RenderService -a screen。

截取屏幕截图

npx -y @midscene/harmony@1 take_screenshot

截取屏幕截图后，请读取保存的图像文件，了解当前屏幕状态，再决定下一步操作。

执行操作

使用 act 与设备交互并获取结果。它会在内部自主处理所有 UI 交互——点击、输入、滚动、滑动、等待和导航。因此，应将复杂的高级任务作为一个整体交给它，而不是拆分成多个小步骤。请用自然语言描述你想做什么以及期望达到的效果：

# specific instructions
npx -y @midscene/harmony@1 act --prompt "type hello world in the search field and press Enter"
npx -y @midscene/harmony@1 act --prompt "long press the message bubble and tap Delete in the popup menu"

# or target-driven instructions
npx -y @midscene/harmony@1 act --prompt "open Settings and navigate to Wi-Fi settings, tell me the connected network name"

断言当前屏幕状态

使用 assert 验证当前屏幕是否满足自然语言条件。它不会执行 UI 操作；它只检查可见的屏幕状态，并且仅当断言为真时才会通过。可用于验证、QA 检查，以及在 act 后验证最终状态。

npx -y @midscene/harmony@1 assert --prompt "there is a login button visible"
npx -y @midscene/harmony@1 assert --prompt "the settings screen shows Wi-Fi and Bluetooth options"
npx -y @midscene/harmony@1 assert --deviceId 0123456789ABCDEF --prompt "the app shows a successful login message"

默认情况下，断言失败时会抛出 AI 生成的原因。传入 --message 可改为抛出自定义错误消息，这有助于在 QA 和 CI 日志中展示预期结果。

npx -y @midscene/harmony@1 assert \
  --prompt "the order confirmation screen is visible" \
  --message "the order should be confirmed after tapping Pay"

当断言需要与参考图像（图标、徽标、屏幕截图）进行比较时，传入 --image 指定 URL／路径，并传入 --image-name 指定其显示名称。每个 --image 都可以是 http(s) 链接、data: URI 或本地文件路径。如果需要附加多张图像，请按对应顺序重复传入这两个标志。当模型无法直接访问 URL 时，添加 --convertHttpImage2Base64 true。需要 @midscene/[email protected]+。

npx -y @midscene/harmony@1 assert \
  --prompt "the visible app icon matches the supplied reference image" \
  --image "https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png" \
  --image-name "icon" \
  --convertHttpImage2Base64 true

# or with a local file
npx -y @midscene/harmony@1 assert \
  --prompt "the header on screen matches the local screenshot" \
  --image "./fixtures/header.png" \
  --image-name "header"

# multiple reference images — pair --image and --image-name by order
npx -y @midscene/harmony@1 assert \
  --prompt "the screen shows both the app icon and the header" \
  --image "./fixtures/icon.png"   --image-name "icon" \
  --image "./fixtures/header.png" --image-name "header"

录制并断言瞬时 UI

如果待验证的状态可能在当前屏幕断言运行前消失，例如 Toast、加载横幅、动画或过渡，请使用录制：

# Terminal 1: keep this foreground command running
npx -y @midscene/harmony@1 record start \
  --device-id 0123456789ABCDEF \
  --output ./submission-observation.json

# Terminal 2, while Terminal 1 records
npx -y @midscene/harmony@1 act --device-id 0123456789ABCDEF \
  --prompt "tap the Submit button"

# Send Ctrl+C to Terminal 1 and wait for the saved-path message, then assert
npx -y @midscene/harmony@1 assert --device-id 0123456789ABCDEF \
  --record ./submission-observation.json \
  --prompt "a success toast appeared during submission"

向 record start 传入目标标志、捕获标志和 --output，然后等待 Recording. Press Ctrl+C to stop and save.。将录制器作为前台进程运行在专用终端中；切勿添加 shell &。手动或从第二个终端执行交互操作，向录制器发送 Ctrl+C，并等待它打印保存路径后再进行断言。HarmonyOS 录制使用定期截图。可选的捕获标志包括 --interval-ms、--max-frames 和 --watchdog-ms；--max-frames 限制采样帧数，清单中可能额外包含一帧最终代表性画面。默认看门狗会在五分钟后完成并保存录制；--watchdog-ms 0 则会禁用此安全限制。输出是一个 JSON 清单及其旁边的 <name>.frames 图像目录，而不是编码后的视频或归档文件。清单包含相对 JPEG／PNG 路径，不包含 base64 图像数据。JSON 文件和图像目录需放在一起保存或移动，并将 JSON 路径传给 assert --record。如果只关注当前屏幕，请使用普通的 assert，不带 --record。

使用参考图像进行精确定位

当用户提供屏幕截图、图标、徽标或参考图像，并希望实现精确的视觉匹配时，优先使用 tap --locate，而不是通用的 act --prompt。将 --locate 作为 JSON 传入。prompt 用于描述目标，images 用于提供带名称的参考图像；如果模型可能无法直接访问图像 URL，则可以使用 convertHttpImage2Base64: true。

npx -y @midscene/harmony@1 tap --locate '{
  "prompt": "tap the area contains the image",
  "images": [
    {
      "name": "target image",
      "url": "https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png"
    }
  ],
  "convertHttpImage2Base64": true
}'

同样的 locate JSON 结构也适用于接受 locate 参数的其他命令。

断开连接

npx -y @midscene/harmony@1 disconnect

使用报告文件

建议优先使用生成的 HTML 报告供人阅读。报告包含逐步执行详情和每项操作的回放视频，因此更容易了解发生了什么并排查问题。

如果其他技能或工具需要使用报告，请先使用同一平台 CLI 包中的 report-tool 转换报告。基于 LLM 的工作流优先使用 Markdown；如果需要以编程方式处理报告，则使用 JSON。

npx -y @midscene/harmony@1 report-tool --action to-markdown --htmlPath ./midscene_run/report/.../index.html --outputDir ./output-markdown
npx -y @midscene/harmony@1 report-tool --action split --htmlPath ./midscene_run/report/.../index.html --outputDir ./output-data

工作流模式

由于 CLI 命令在各次调用之间是无状态的，请遵循以下模式：

1. 连接以建立会话
2. 启动目标应用并截取屏幕截图以查看当前状态，并确保应用已启动且在屏幕上可见。
3. 执行操作：使用 act 执行所需操作或目标驱动的指令。使用 assert 检查操作后的屏幕状态；对于瞬时状态工作流，也可以在专用终端中持续运行 record start --output ...，通过 Ctrl+C 停止录制，然后使用 assert --record。
4. 断开连接以结束操作

最佳实践

1. 交互前将目标应用置于前台：连接后，使用专用启动器（例如，npx -y @midscene/harmony@1 launch --uri <bundleName>），然后截屏确认应用确实位于前台。不要使用猜测的能力名称调用 aa start，因为 HarmonyOS 应用可能声明了不同的入口能力。只有通过视觉确认后，才能使用此技能进行 UI 自动化。
2. 明确描述 UI 元素：不要使用含糊的描述，而应提供清晰、具体的细节。例如，说“右侧的 Wi-Fi 开关”，而不是“开关”。
3. 尽可能描述位置：描述元素的位置，帮助定位目标（例如，“右上角的搜索图标”、“列表中的第三项”）。
4. 绝不要在后台运行：每条 midscene 命令都必须同步运行——后台执行会打断截图、分析和操作的循环。
5. 将相关操作合并到单个 act 命令中：在同一应用中连续执行操作时，应将它们合并到一条 act 提示词中，而不是拆分成多条命令。例如，“打开设置，轻点 Wi-Fi 并将其开启”应作为一次 act 调用，而不是三次。这能减少往返次数，避免不必要的截图和分析循环，并显著提高速度。
6. 选择合适的验证窗口：验证当前屏幕时使用 assert --prompt "..."。验证 toast、横幅、动画或过渡时，在专用终端中运行 record start --output ...，执行交互操作，然后按 Ctrl+C 停止录制，等待显示保存路径的消息，再将产物传给 assert --record。
7. 完成后汇总报告文件：自动化任务完成后，收集并汇总所有报告文件（截图、日志、输出文件等），并呈现清晰的总结，说明完成了哪些工作、生成了哪些文件以及文件的位置，方便用户查看结果。
8. 提供参考图像时优先使用 tap --locate：如果用户分享了截图、图标或徽标，并希望定位该确切的视觉目标，请使用带有多模态 locate JSON 对象（例如 { "prompt": "...", "images": [...] }）的 tap --locate，而不要只依赖 act --prompt。

示例 — 启动并操作应用：

npx -y @midscene/harmony@1 connect
npx -y @midscene/harmony@1 launch --uri com.huawei.hmos.settings
npx -y @midscene/harmony@1 take_screenshot
npx -y @midscene/harmony@1 act --prompt "scroll down the settings list and tap About device"
npx -y @midscene/harmony@1 take_screenshot
npx -y @midscene/harmony@1 disconnect

示例 — 表单操作：

npx -y @midscene/harmony@1 act --prompt "fill in the username field with 'testuser' and the password field with 'pass123', then tap the Login button"
npx -y @midscene/harmony@1 take_screenshot

常见 HarmonyOS Bundle 名称

应用	Bundle 名称
设置	com.huawei.hmos.settings
相机	com.huawei.hmos.camera
图库	com.huawei.hmos.photos
日历	com.huawei.hmos.calendar
时钟	com.huawei.hmos.clock
计算器	com.huawei.hmos.calculator
浏览器	com.huawei.hmos.browser
天气	com.huawei.hmos.weather

提高精度（Deep Locate / Deep Think）

当 Midscene 难以完成任务时，可以使用两个可选的全局标志。将它们放在命令中的任意位置（子命令之前或之后）即可；设置后，相关操作会默认使用它们，因此无需为每次调用传入参数。

• --deep-locate — 额外进行一轮视觉推理，以精确定位目标元素。当操作落在错误位置（位置偏移）时使用。它适用于所有需要定位元素的操作，包括 tap --locate 和 act 内部执行的定位。
• --deep-think — 使用更深入的推理来规划 act（提供更丰富的上下文并拆分子目标）。复杂的多步 act 指令可使用此标志；它只影响规划。

这两个标志会稍微降低速度以换取更好的结果，并且可以组合使用。

# more accurate element location (helps act's internal locating too)
npx -y @midscene/harmony@1 act --deep-locate --prompt "tap the small back arrow in the top-left corner"

# deeper planning for a complex, multi-step act
npx -y @midscene/harmony@1 act --deep-think --prompt "scroll the settings list, open About device, and find the system version"

# combine both
npx -y @midscene/harmony@1 act --deep-locate --deep-think --prompt "open Settings, go to Wi-Fi, and toggle it on"

故障排查

问题	解决方案
未找到 HDC	通过 DevEco Studio 安装，或设置 HDC_HOME 环境变量。
设备未列出	检查 USB 连接，确保已在开发者选项中启用 USB 调试，然后运行 hdc list targets。
命令超时	设备屏幕可能已关闭或锁定。唤醒设备并解锁。
API 密钥错误	检查 .env 文件中是否包含 MIDSCENE_MODEL_API_KEY=<your-key>。请参阅模型配置。
@midscene/* 依赖版本过旧	使用 npm ls @midscene/harmony @midscene/core @midscene/shared（或 pnpm why @midscene/harmony）检查本地版本。使用 npm view @midscene/harmony version、npm view @midscene/core version 和 npm view @midscene/shared version 与最新版本进行比较。如有需要，请升级：npm i @midscene/harmony@latest @midscene/core@latest @midscene/shared@latest。
目标设备错误	如果连接了多台设备，请在 connect 命令中使用 --deviceId <id> 标志。