本文档旨在帮助您完成鸿蒙 (HarmonyOS) 真机设备的自动化测试环境配置。完成配置后，您将能够通过 UI-TARS 对鸿蒙设备进行控制和测试。
📋 前置条件
* 硬件：
    * 一台运行 HarmonyOS (3.0/4.0/NEXT) 的真机。
    * 一根支持数据传输的 USB 数据线。
    * Mac 电脑 (推荐 macOS 13+)。

* 软件：
    * DevEco Studio (用于获取 SDK 和 HDC 工具)。
    * Node.js (>= 16)。

🛠️ 1. 安装与配置 HDC 工具
HDC (HarmonyOS Device Connector) 是连接鸿蒙设备的命令行工具，类似于 Android 的 ADB。
1.1 安装 DevEco Studio
1. 下载并安装最新版的 DevEco Studio。
2. 首次启动时，按照向导安装 HarmonyOS SDK。记下 SDK 的安装路径 (通常在 /Users/<用户名>/Library/Huawei/Sdk)。

1.2 配置环境变量
为了在终端直接使用 hdc 命令，需要将其加入 PATH。
1. 打开终端，编辑您的 Shell 配置文件 (如 ~/.zshrc 或 ~/.bash_profile)：

nano ~/.zshrc
2. 添加以下内容 (请将路径替换为您的实际 SDK 路径，通常在 toolchains 目录下)：

# HarmonyOS SDK
export HDC_HOME=/Users/hrx/Library/OpenHarmony/Sdk/20/toolchains # 请根据实际版本调整，如 /10/toolchains
export PATH=$PATH:$HDC_HOME
3. 保存并生效：

source ~/.zshrc
4. 验证：
在终端输入 hdc help。如果显示帮助信息，说明配置成功。

📱 2. 手机端配置
2.1 开启开发者模式
1. 进入 设置 -> 关于手机。
2. 连续点击 版本号 7次，直到提示“您已处于开发者模式”。
3. 回到 设置 -> 系统和更新 -> 开发人员选项。

2.2 开启 USB 调试
1. 在“开发人员选项”中，开启 USB 调试。
2. 关键步骤：连接电脑后，下拉通知栏，点击“正在通过 USB 充电”，将连接模式切换为 “传输文件” 或 “MTP”。
3. 如果此时手机连接了电脑，手机上会弹出“允许 USB 调试吗？”的弹窗。
4. 勾选“始终允许使用这台计算机进行调试”，然后点击 允许。

2.3 验证连接
连接 USB 线后，在电脑终端执行：
hdc list targets
如果输出了设备的序列号 (UDID)，说明连接成功。

⚠️ 常见连接问题排查
如果执行命令返回 [Empty] 或找不到设备：
1. 通知栏无反应/电脑未识别：

    * 更换数据线：这是最常见原因。市面上很多线是“仅充电线”，无法传输数据。请务必使用手机原装线或品牌数据线。

判定标准：如果手机插上电脑后，通知栏没有任何 USB 相关提示（甚至连“正在充电”的横幅都没有，或者只有电池图标在充电），那么这根线 100% 是仅充电线，必须更换。
    * 直连电脑（排除扩展坞问题）：
        * 注意：很多扩展坞上的 Type-C 接口 往往设计为 “仅供电 (PD Charging)”，不支持数据传输。如果你插在这个口上，就只能充电。
        * 排查方法：请务必将手机数据线直接插在 Mac 机身上的雷电/USB-C 接口，或者使用扩展坞上明确支持数据的 USB-A (大口)。

    * 检查 Mac 系统报告：点击 Mac 左上角苹果图标 -> 关于本机 -> 系统报告 -> USB。如果这里都没看到手机，说明物理连接不通。

2. 检查手机弹窗：重新插拔 USB，留意手机屏幕是否弹出“允许 USB 调试”的授权框，务必点击“允许”。
3. 切换 USB 模式：下拉手机通知栏，点击“正在通过 USB 充电”，尝试切换为 “传输文件” 或 “MIDI” 模式。
4. 检查数据线：确保使用的是支持数据传输的数据线，而非仅充电线。
5. 重启 HDC 服务：在终端执行 hdc kill 然后再次执行 hdc list targets。

🚀 3. 配置与启动自动化服务 (Hypium)
本项目通过 HypiumOperator 与鸿蒙设备交互，默认通信端口为 8001。
3.1 确认 Hypium Server
您需要确保有一个能够接收 WebDriver 协议指令并控制鸿蒙设备的 Server 正在运行，且监听在 http://127.0.0.1:8001。
* 如果您使用的是 Appium：
确保 Appium Server 已启动，并且安装了对应的鸿蒙驱动 (HarmonyOS Driver)。

# 示例：启动 Appium 并指定端口 (如果驱动默认端口不是 8001，请使用 -p 8001)
appium -p 8001
* 如果您使用的是其他 Hypium 封装工具：
请参考相关工具文档，确保其服务端口配置为 8001。

3.2 验证服务状态
在服务启动后，可以通过 curl 验证是否通畅：
curl http://127.0.0.1:8001/status
如果返回了 JSON 格式的状态信息，说明服务已就绪。

🔌 4. 接入 UI-TARS
4.1 代码配置
目前 HypiumOperator 已预置了对 8001 端口的调用。
文件路径：packages/ui-tars/operators/hypium/src/index.ts
private baseUrl: string = 'http://127.0.0.1:8001'; // Default Hypium port
4.2 启动原子化服务
在项目根目录下运行：
node packages/ui-tars/cli/bin/index.js
服务启动后，当您在前端选择“鸿蒙”设备 (ClientType 4) 时，系统将自动调用 Hypium Operator 进行控制。

❓ 常见问题 (FAQ)
Q: hdc list targets 找不到设备？
A:
1. 检查数据线是否支持数据传输。
2. 确保手机已解锁且处于开发者模式。
3. 尝试撤销 USB 调试授权 (设置 -> 开发人员选项 -> 撤销 USB 调试授权) 并重新插拔。
4. 重启 HDC 服务：hdc kill 然后 hdc start。

Q: 端口 8001 被占用？
A:
检查是否有其他服务占用了该端口：
lsof -i :8001
如果有，请关闭相关进程或修改 HypiumOperator 中的 baseUrl 配置。