trove/curios
Public Access
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(harmony): guide official HDC setup and recheck tool availability

Browse Source
This commit is contained in:
render
2026-09-10 14:33:53 +08:00
parent 170ea4d112
commit 5666bb8f40
13 changed files with 372 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/harmony-connector.md
+12 -4
View File
@@ -1,6 +1,6 @@
# Harmony Connector
插件 ID：`dev.trove.harmony-connector`。当前版本：`0.3.0`。
插件 ID：`dev.trove.harmony-connector`。当前版本：`0.3.1`。
macOS 上的鸿蒙设备连接工具。通过 USB 收发文件与完整文件夹；使用官方 HDC 管理应用、保存截图、导出日志和调试应用数据。功能按连接工具、设备实际能力和授权开放，不按 HarmonyOS 大版本或机型名称限制。
@@ -33,13 +33,19 @@ macOS 上的鸿蒙设备连接工具。通过 USB 收发文件与完整文件夹
## 设备与应用
在「设备与应用」选择官方 SDK 的 `hdc` 可执行文件。插件会尝试发现 PATH 或 `/Applications`、`~/Applications` 中 DevEco Studio 的内置工具。典型路径：
首次进入「设备与应用」，如果没有可用 HDC，页面会显示安装引导：
1. 点击「前往华为官网下载」，在浏览器打开 [Command Line Tools 官方下载页](https://developer.huawei.com/consumer/cn/download/command-line-tools-for-hmos)。Apple Silicon 选择 Mac (ARM64)，Intel 选择 Mac (x86)，按官网提示登录华为账号并下载。
2. 完整解压 ZIP，点击「选择已解压的工具目录」。可选择包含 `command-line-tools` 的解压目录、`command-line-tools` 本身，或其 `toolchains` 目录；插件定位 HDC、运行版本检查，成功后保存路径。错误选择和取消不会覆盖已有配置。
3. 手机连接 USB，启用开发者模式与 USB 调试，解锁并允许这台 Mac 的调试请求。配置成功后自动检查设备；「刷新连接」也会重新检查工具，支持启动后才安装到 PATH 的 HDC。
已有 DevEco Studio 或 SDK 的用户也可点击「选择 HDC 文件」。插件启动时尝试发现 PATH 或 `/Applications`、`~/Applications` 中 DevEco Studio 的内置工具。典型路径：
```text
/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains/hdc
```
也可使用华为官方 Command Line Tools。保留 HDC 同目录的依赖库，插件不重打包官方 SDK。选择路径保存在插件自己的数据目录中。手机需启用开发者模式与 USB 调试，并信任这台 Mac。管理页明确选择 HDC 设备，不根据 MTP USB 地址猜测二者对应关系。
请保留完整的工具目录及同目录依赖库，插件不重打包官方 SDK。选择路径保存在插件自己的数据目录中；工具被移动、删除或无法运行时重新显示安装引导和原因。工具准备完成前隐藏空设备列表及不可用的管理面板，文件传输仍可直接使用。管理页明确选择 HDC 设备，不根据 MTP USB 地址猜测二者对应关系。
| 操作 | 行为与边界 |
| --- | --- |
@@ -101,7 +107,9 @@ curios/harmony-connector/backend/harmony-connector --check-screen /absolute/path
该命令走 UI 相同的后端接口，采集并解码 3 帧，输出耗时，最后关闭会话；不启用控制、不发送输入。首次 HDC 连接显示 Unauthorized 时，在手机上允许 USB 调试。`hdc -v` 能运行但管理失败时，先用 `hdc list targets -v` 检查授权状态。
本次自动化验证通过 39 项原生测试、27 项 UI/格式/坐标测试、3 项 USB C 桥接检查及 3 项底座协议检查。浏览器另外验证了持续显示模拟画面、启用控制、中文输入、放大和停止清空；模拟数据不会包含在发布包内。官方 Command Line Tools 26.0.0.821（Mac ARM）的 HDC 返回 `Ver: 3.2.0f`，已识别真机，但当次状态为 Unauthorized，故投屏和输入的真机效果尚未验收，不能将上述替身测试当作真机通过。
0.3.0 自动化验证通过 39 项原生测试、27 项 UI/格式/坐标测试、3 项 USB C 桥接检查及 3 项底座协议检查。浏览器另外验证了持续显示模拟画面、启用控制、中文输入、放大和停止清空；模拟数据不会包含在发布包内。官方 Command Line Tools 26.0.0.821（Mac ARM）的 HDC 返回 `Ver: 3.2.0f`，已识别真机，但当次状态为 Unauthorized，故投屏和输入的真机效果尚未验收，不能将上述替身测试当作真机通过。
0.3.1 的安装引导验证通过 41 项原生测试、30 项 UI/格式/坐标测试和 6 项 USB/协议检查（共 77 项）。新增回归覆盖官网下载入口、选择已解压目录、取消/错误选择保留配置、启动后安装工具、工具丢失后返回引导。浏览器以明确标记的模拟工具检查了引导和配置后的界面切换。使用已下载的官方工具目录调用实际发布后端，成功定位 HDC 并返回 `Ver: 3.2.0f`；设备当时仍为 Unauthorized，后续投屏验收因无已授权设备而停止。
## 构建与发布