鸿蒙设备自动化

关键规则 — 违反以下规则将导致工作流中断：

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

使用 npx @midscene/harmony@1 自动化鸿蒙 NEXT 设备。每个 CLI 命令直接映射到一个 MCP 工具——您（AI 智能体）充当大脑，根据截图决定要执行的操作。

前提条件

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"
# 如果使用 OpenRouter，设置：
# MIDSCENE_MODEL_API_KEY="your-openrouter-api-key"
# MIDSCENE_MODEL_NAME="qwen/qwen3.5-plus"
# MIDSCENE_MODEL_BASE_URL="https://openrouter.ai/api/v1"

示例：豆包 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"

常用模型：豆包 Seed 2.0 Lite、Qwen 3.5、智谱 GLM-4.6V、Gemini-3-Pro、Gemini-3-Flash。

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

HDC 设置

必须安装 HDC（鸿蒙设备连接器）并可访问。常见设置：

• 通过 DevEco Studio 安装
• 或者设置 HDC_HOME 环境变量指向 HDC 目录

验证 HDC 是否正常工作：

hdc version
hdc list targets

命令

连接设备

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

截取屏幕截图

npx @midscene/harmony@1 take_screenshot

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

执行操作

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

# 具体指令
npx @midscene/harmony@1 act --prompt "在搜索字段中输入 hello world 并按回车键"
npx @midscene/harmony@1 act --prompt "长按消息气泡，然后在弹出菜单中点击删除"

# 或目标驱动指令
npx @midscene/harmony@1 act --prompt "打开设置，导航到 Wi-Fi 设置，告诉我已连接的网络名称"

断开连接

npx @midscene/harmony@1 disconnect

工作流程模式

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

1. 连接 建立会话
2. 启动目标应用并截取屏幕截图 查看当前状态，确保应用已启动并显示在屏幕上。
3. 执行操作 使用 act 执行所需操作或目标驱动指令。
4. 断开连接 完成后

最佳实践

1. 在使用此技能前，将目标应用置于前台：为获得最佳效率，在调用任何 midscene 命令之前，请使用 HDC 启动应用（例如，hdc shell aa start -a EntryAbility -b <bundleName>）。然后截取屏幕截图以确认应用确实在前台。只有在视觉确认后，才应继续使用此技能进行 UI 自动化。HDC 命令比使用 midscene 导航和打开应用要快得多。
2. 具体描述 UI 元素：不要使用模糊的描述，应提供清晰、具体的细节。说 "右侧的 Wi-Fi 开关" 而不是 "那个开关"。
3. 尽可能描述位置：通过描述元素的位置来帮助定位（例如，"右上角的搜索图标"，"列表中的第三项"）。
4. 绝不在后台运行：每个 midscene 命令必须同步运行——后台执行会破坏截图-分析-操作的循环。
5. 将相关操作合并到单个 act 命令中：在同一个应用内执行连续操作时，将它们合并到一个 act 提示中，而不是拆分成单独的命令。例如，“打开设置，点击 Wi-Fi，然后打开开关”应该是一次 act 调用，而不是三次。这减少了往返次数，避免了不必要的截图-分析周期，并且速度显著加快。
6. 完成后总结报告文件：完成自动化任务后，收集并总结所有报告文件（截图、日志、输出文件等）给用户。清晰地总结完成了什么、生成了哪些文件以及它们的位置，方便用户审查结果。

示例 — 应用启动和交互：

hdc shell aa start -a EntryAbility -b com.huawei.hmos.settings
npx @midscene/harmony@1 connect
npx @midscene/harmony@1 take_screenshot
npx @midscene/harmony@1 act --prompt "向下滚动设置列表并点击关于设备"
npx @midscene/harmony@1 take_screenshot
npx @midscene/harmony@1 disconnect

示例 — 表单交互：

npx @midscene/harmony@1 act --prompt "在用户名字段填写 'testuser'，在密码字段填写 'pass123'，然后点击登录按钮"
npx @midscene/harmony@1 take_screenshot

常见鸿蒙应用 Bundle 名称

故障排除