feat(harmony): add folder transfers and HDC device management
This commit is contained in:
+73
-62
@@ -1,46 +1,89 @@
|
||||
# Harmony Connector
|
||||
|
||||
插件 ID：`dev.trove.harmony-connector`。版本：`0.1.1`。
|
||||
插件 ID：`dev.trove.harmony-connector`。当前版本：`0.2.0`。
|
||||
|
||||
面向 HarmonyOS 6 的 USB 文件传输插件，提供设备选择、存储与目录浏览、分页、名称筛选、新建目录，以及单文件发送/接收、字节进度与取消。使用 libmtp 1.1.23 和 libusb 1.0.30，无需手机开发者模式、HDC、ADB 或 Homebrew 运行依赖。
|
||||
macOS 上的鸿蒙设备连接工具。通过 USB 收发文件与完整文件夹；使用官方 HDC 管理应用、保存截图、导出日志和调试应用数据。功能按连接工具、设备实际能力和授权开放，不按 HarmonyOS 大版本或机型名称限制。
|
||||
|
||||
## 安装与使用
|
||||
## 安装
|
||||
|
||||
在 Trove 添加 Git 软件源：
|
||||
在 Trove 添加 Git 软件源：仓库 `https://git.render.ink/trove/curios.git`，唯一 ID `trove-official`（对应 `source/index.json` 顶层 `id`），显示名称可自行填写。刷新后安装 Harmony Connector。私有仓库使用本机 Git 凭据。
|
||||
|
||||
- 仓库地址：`https://git.render.ink/trove/curios.git`
|
||||
- 唯一 ID：`trove-official`（仓库 `source/index.json` 顶层 `id`）。
|
||||
- 显示名称：可以自定义，例如「Trove 官方软件源」。
|
||||
发布包适用于 Apple Silicon、macOS 13 及以上，内含 libmtp 1.1.23 和 libusb 1.0.30。Intel 需在对应 Mac 构建并单独验证后发布，当前未提供 Intel 包。
|
||||
|
||||
刷新源后安装 **Harmony Connector**。私有仓库使用本机 Git 凭据。当前发布的是 Apple Silicon (`aarch64-apple-darwin`) 包，部署目标为 macOS 13 及以上；Intel 需要在对应 Mac 上构建并追加该架构产物，未发布未经验证的 Intel 包。
|
||||
## 文件与文件夹
|
||||
|
||||
1. 解锁手机，用支持数据传输的 USB 线连接 Mac。
|
||||
2. 在手机 USB 选项中选择「传输文件」，允许访问。
|
||||
3. 等待插件自动发现设备，选择并连接，打开目标文件夹。也可手动点击「扫描设备」。
|
||||
4. 点击「发送文件」从 Mac 选择一个文件；点击文件旁的「接收」选择 Mac 接收文件夹。
|
||||
1. 解锁手机，用支持数据传输的 USB 线连接 Mac，在手机上选择「传输文件」并允许访问。
|
||||
2. 插件启动后自动发现设备，选择手机并连接。也可手动扫描。
|
||||
3. 选择存储位置，进入目标目录。「发送文件」选择文件，「发送文件夹」选择整个目录；文件和文件夹旁的「接收」均可下载到 Mac。
|
||||
|
||||
本插件只访问手机通过 MTP 开放的存储。目录来自设备对象 ID，不映射为 Android 路径。HarmonyOS 6 在文件传输模式下允许导出图库内容，导入图库需要图片传输模式；本版未实现 PTP 图库导入。[华为 HarmonyOS 6 官方说明](https://consumer.huawei.com/cn/support/content/zh-cn16090699/)
|
||||
文件功能不需要 HDC、ADB、Homebrew 或开发者模式。设备每约 2 秒自动检测一次；连接后仅检查 USB 存在性，不重复打开会话。手动断开后不会自行重新连接。
|
||||
|
||||
没有发现设备时，检查数据线和 USB 模式、保持手机解锁，退出占用手机的其他传输应用后重试。取消或 USB 操作失败会释放会话，请重新连接。取消是协作式的，需要等待手机或 USB 超时返回，不保证立即完成。
|
||||
文件夹会保留层级、中文名称、空文件和空目录。整棵目录先检查再传输；总进度汇总全部文件，显示当前文件、已完成文件数、当前/平均速度、耗时和预计剩余时间。速度来自实际字节进度，不是预设数值。
|
||||
|
||||
插件打开时立即扫描，随后在空闲时约每 2 秒检测一次。已连接时只检查 USB 设备是否仍存在，不重复打开 MTP 会话；传输期间也检测拔线并请求结束传输。发现设备后仍由用户选择连接，手动断开不会立即自动重连。
|
||||
- 不覆盖或合并同名条目。上传还会检查设备剩余容量，每次写入前再次检查目标名称。
|
||||
- 下载先写入所选目录下的隐藏临时文件夹，全部文件长度校验成功后，原子保存为最终文件夹。失败或正常取消会清理此次临时内容。
|
||||
- 不跟随符号链接，不传输特殊文件；拒绝路径穿越、循环、重名目录和超过 100,000 条目或 128 层的目录树。
|
||||
- 上传中断时手机可能保留已创建的目录和文件。不会自动删除这些内容，请在手机上检查后再重试。底层 USB 事务取消需等待设备响应。
|
||||
- 长度校验不等于端到端内容哈希校验；实际验收应将上传文件下载回来比较 SHA-256。
|
||||
- 强制结束进程或断电可能留下 `.harmony-*.part` 临时内容。插件不会扫描或删除用户目录中的历史临时文件。
|
||||
|
||||
手动断开会立即清空文件和连接界面，USB 会话在后台释放；清理期间显示提示并暂时禁用连接，完成后继续自动发现。设备不响应 MTP 关闭请求时，底层释放仍可能需要等待 USB 超时。
|
||||
手机只开放 MTP 可见的存储，实际目录、访问权限和图库行为由设备决定；向普通目录发送照片不保证导入图库。本版不提供断点续传、无线 MTP、图库导入或全盘访问。
|
||||
|
||||
名称在扫描阶段来自 USB 描述符；连接后优先使用设备通过 MTP 返回的友好名称，并单独显示设备报告的型号。友好名称由固件提供，不一定等于系统设置中的自定义设备名；缺失时回退到型号或 USB 名称。libmtp 的静态设备匹配表只用于协议兼容，不作为型号展示依据；0.1.0 曾把其中的 `Nova14` 兼容条目误用为设备名称，0.1.1 已修复。
|
||||
扫描名称取自 USB 描述符；连接后使用 MTP 友好名称并单独显示设备报告的型号。它可能不同于手机设置中的自定义名称。0.1.0 将 libmtp 匹配表中的 `Nova14` 误用于展示，0.1.1 已修复，不再把驱动匹配名称当作机型。
|
||||
|
||||
## 文件保护与边界
|
||||
## 设备与应用
|
||||
|
||||
- 一次传输一个普通文件；目录请先压缩。不提供删除手机内容的操作。
|
||||
- 拒绝同名覆盖。接收使用目标目录内的隐藏临时文件，校验长度并同步后通过原子无覆盖操作保存。发送会校验目标名称、存储空间和传输后设备报告的长度。
|
||||
- 长度校验不是内容哈希验证。实际设备验收需回传文件并比较 SHA-256。
|
||||
- 接收失败或正常取消会清理本次临时文件。手机端可能保留未完成的上传对象，需要在手机上检查处理。
|
||||
- 不在传输过程中关闭插件。强制结束进程、USB 长时间阻塞或断电时可能留下 `.harmony-*.part`；正常退出请求最多等待约 3.5 秒，再由底座回收进程。重新启动不会扫描或删除用户目录里的历史临时文件。
|
||||
- 目前不提供无线、批量/递归目录传输、断点续传或图库导入。跨存储、机型文件权限与大文件限制以实际设备为准。
|
||||
在「设备与应用」选择官方 SDK 的 `hdc` 可执行文件。插件会尝试发现 PATH 或 `/Applications`、`~/Applications` 中 DevEco Studio 的内置工具。典型路径：
|
||||
|
||||
## 构建、验证与发布
|
||||
```text
|
||||
/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains/hdc
|
||||
```
|
||||
|
||||
要求 macOS、Xcode Command Line Tools、Rust/Cargo、Node.js、pnpm、make、pkg-config。源码归档及哈希固定在 `vendor/harmony-connector/`。构建不需要另装 libmtp。
|
||||
也可使用华为官方 Command Line Tools。保留 HDC 同目录的依赖库，插件不重打包官方 SDK。选择路径保存在插件自己的数据目录中。手机需启用开发者模式与 USB 调试，并信任这台 Mac。管理页明确选择 HDC 设备，不根据 MTP USB 地址猜测二者对应关系。
|
||||
|
||||
| 操作 | 行为与边界 |
|
||||
| --- | --- |
|
||||
| 设备连接与信息 | 显示 HDC 目标、USB/TCP 类型、授权/连接状态；检查 `bm`、`aa`、`uitest`、`hilog` 等实际工具帮助。未知格式报错，不伪装成无设备。 |
|
||||
| 应用列表与详情 | 按包名筛选，读取版本、签名类型和设备公开的可启动组件。不根据包名猜测 `EntryAbility`。 |
|
||||
| 安装/更新 | 选择已签名 `.hap`；展示包名、版本、大小、SHA-256 并确认。执行前复制到临时快照并重新校验哈希；安装后读取实际版本。签名或权限错误不会触发自动卸载。 |
|
||||
| 卸载 | 用户确认后操作；不移除系统应用，结束后检查应用是否确实消失。 |
|
||||
| 启动/强制停止 | 从实际公开的组件选择启动入口；强制停止需要确认，报告设备返回结果。 |
|
||||
| 截图 | 使用 UITest 捕获，下载并解码验证 PNG 后保存。只清理本次创建的远端临时图片。 |
|
||||
| 日志 | 导出 `hilog -x` 快照到用户选择的目录。日志正文中的错误信息不会被误判为命令失败。 |
|
||||
| 诊断报告 | 使用 HDC `bugreport` 保存报告，拒绝把空结果作为成功。 |
|
||||
| 调试数据导出 | 仅对调试签名且设备允许访问的应用开放；复制 `data/storage/el2/base`，附带路径、大小、SHA-256 清单。应用通常需已启动。 |
|
||||
|
||||
调试数据导出是运行中文件的副本，不保证数据库事务一致性，不包含全部应用状态，不提供一键恢复。HDC 对空目录及空子目录的行为也不同于 MTP 目录传输。普通发布应用私有数据、整机备份/恢复和受保护系统数据没有可供该插件普遍使用的公开权限；不能因为 `backup_tool` 退出码为 0 就宣称备份成功。
|
||||
|
||||
管理操作使用独立串行任务，支持取消与超时；取消不回滚设备端已经完成的更改。操作开始前重新确认所选设备在线。功能有命令支持仍可能被单个应用、对象或系统权限拒绝，失败会显示设备返回的原因。
|
||||
|
||||
## 投屏和控制调研
|
||||
|
||||
**本版本尚未实现实时投屏或键鼠控制。** 官方 scrcpy 的设备端依赖 Android、ADB、`app_process` 和 Android 屏幕/输入 API，不能直接连接原生鸿蒙。仅能运行 APK 并不足以证明 scrcpy 兼容。[scrcpy 官方说明](https://github.com/Genymobile/scrcpy)
|
||||
|
||||
最新 DevEco Studio 与 DevEco Testing 已提供官方 Mac 投屏功能；目前未找到可嵌入本插件的公开投屏协议。可行的插件路线是先以 HDC + UITest 实现截图预览和明确的点击/滑动输入，再单独验证用户授权的鸿蒙采集端、视频编码和传输。连续视频方案需要设备端适配，不能把截图轮询宣传成 scrcpy 视频流。详见[投屏与键鼠控制调研](research/harmony-screen-control.md)。
|
||||
|
||||
## 重连问题与 debug
|
||||
|
||||
0.1.1 真机记录：HUAWEI Pura 70 Ultra，USB `12d1:1101`，USB 名称 `HDC Device`，MTP 友好名称 `HUAWEI Pura 70 Ultra`，型号代码 `HBP-AL00`。设备未通过 MTP 返回自定义名称 `daniel`。连接后可读取存储，断开请求约 0.27 毫秒返回，USB 释放约 61 秒后结束；**这不证明随后能重新打开会话**。用户报告仍需拔线。
|
||||
|
||||
0.2.0 没有将未经真机验证的 USB reset 或超时补丁当作重连修复。调研确认当前 libmtp 标志已经执行 reset，新增同样 reset 不能作为修复依据。须区分 CloseSession、接口释放、USB reset、重新枚举和设备端会话状态。见[会话恢复调研](research/harmony-mtp-session.md)。本轮诊断没有发现 USB 设备，故重连仍待真机复现和修复。
|
||||
|
||||
关闭插件窗口，保留一台解锁且处于「传输文件」模式的手机，然后执行：
|
||||
|
||||
```sh
|
||||
# 仅枚举
|
||||
curios/harmony-connector/backend/harmony-connector --diagnose
|
||||
|
||||
# 只读执行三轮打开、存储/目录读取、关闭与重新打开；不要在插件占用 USB 时运行
|
||||
curios/harmony-connector/backend/harmony-connector --check-reconnect
|
||||
```
|
||||
|
||||
`--check-reconnect` 逐阶段输出 JSON、耗时和实际目录读取结果，不修改手机文件。没有恰好一台设备或任何一轮失败时以非零状态结束；原生 CloseSession 仍可能等待 USB 超时。不能仅凭扫描发现设备、按钮可用或 reset 返回成功判定验收通过。
|
||||
|
||||
## 构建与发布
|
||||
|
||||
要求 macOS、Xcode Command Line Tools、Rust/Cargo、Node.js、pnpm、make、pkg-config。固定源码归档与哈希位于 `vendor/harmony-connector/`。
|
||||
|
||||
```sh
|
||||
pnpm install --frozen-lockfile
|
||||
@@ -50,42 +93,10 @@ pnpm run harmony:pack
|
||||
pnpm run release:prepare --entries dist/harmony-release.json
|
||||
```
|
||||
|
||||
以上命令只构建 Harmony Connector，发布时保留生产索引中其他插件和历史版本。索引和不可变 `.curio` 包必须同一提交推送，不能覆盖已发布的同版本同架构文件。
|
||||
发布创建新的不可变版本产物，保留旧版本、哈希和生产源的已有条目。推送后必须以 Git 仓库为源执行安装验证。生产 README 保持产品介绍；技术约束与验收记录在本文和 `docs/research/`。
|
||||
|
||||
推送后验证真实 Git 软件源：
|
||||
代码职责：`native/src/file_transfer.rs` 管理目录计划与落盘，`progress.rs` 统计进度，`connector.rs` 管理 MTP 会话与任务，`mtp.rs` / `mtp_bridge.c` 封装固定依赖，`hdc.rs` / `hdc_data.rs` / `hdc/files.rs` 管理官方工具与输出校验，`command.rs` 控制进程、输出、取消和时限。UI 的文件与管理工作区分开实现。
|
||||
|
||||
```sh
|
||||
TROVE_APP_DIR=/absolute/path/to/app \
|
||||
pnpm run verify --remote-source https://git.render.ink/trove/curios.git \
|
||||
--source-id trove-official --source-kind git
|
||||
```
|
||||
验证包括文件夹往返与失败清理、会话状态、工具命令和解析、安装确认及后置条件、页面交互、USB 桥接和底座协议。HDC 测试使用明确的工具替身，不代表商业手机已经完成安装、备份或截图验收。实际文件吞吐量和 USB 往返 SHA-256 仍需真机记录。
|
||||
|
||||
界面测试使用独立的显式模拟设备，预览脚本和数据不进入安装包：
|
||||
|
||||
```sh
|
||||
pnpm run harmony:build
|
||||
node tools/preview-harmony.mjs
|
||||
# 打开 http://127.0.0.1:18770
|
||||
```
|
||||
|
||||
## 代码与接口
|
||||
|
||||
| 位置 | 职责 |
|
||||
| --- | --- |
|
||||
| `curios/harmony-connector/ui/` | 独立界面，通过版本化 Trove SDK 调用 Host 文件选择器与 `@self` |
|
||||
| `native/src/connector.rs` | 会话串行化、文件校验、后台传输任务、取消及完成状态 |
|
||||
| `native/src/mtp.rs`、`mtp_bridge.c` | libmtp 所有权、结构转换、文件描述符传输 |
|
||||
| `native/src/wire.rs` | Trove Wire v1 认证握手、请求分发与退出 |
|
||||
| `build.mjs`、`legal/` | 固定依赖构建、动态库路径修正、签名与第三方声明 |
|
||||
|
||||
`@self` 接口：`info`、`devices`、`monitor`、`connect({id})`、`disconnect`、`list({storage,parent,offset?})`、`mkdir({storage,parent,name})`、`transfer(...)`、`transferStatus`、`cancelTransfer({id})`。根目录为 `0xffffffff`；目录响应每页最多 500 个条目，传输异步返回任务 ID，界面轮询实际进度。后端同一时刻仅执行一个 MTP 操作；进度查询、取消及 USB 存在性检查不等待 MTP 锁。重新连接后必须重新获取对象列表。
|
||||
|
||||
## 验证记录与真机验收
|
||||
|
||||
自动测试包含 16 项传输与会话行为测试、10 项完整界面回归测试、2 项界面数据测试、3 项原生 USB 边界检查，以及 Trove 的握手、并发响应、退出协议测试。传输行为测试使用独立内存设备并实际读写临时目录；界面回归测试加载真实页面和 SDK，在模拟硬件边界下验证自动发现、名称、手动断开、慢速 USB 释放、拔线、旧响应与页面关闭。原生边界检查复现静态表 `Nova14` 与设备实际报告信息不同的场景，并验证友好名称和 USB 存在性检测。
|
||||
|
||||
2026-09-10，HUAWEI Pura 70 Ultra 的实机只读连接测试返回 USB ID `12d1:1101`、USB 名称 `HDC Device`、MTP 友好名称 `HUAWEI Pura 70 Ultra`、型号代码 `HBP-AL00`，并成功读取内部存储信息。该设备的 MTP 返回值未包含系统设置中的自定义名称。实机还复现了关闭 MTP 会话时的长时间等待；原生调用栈停在等待 `CloseSession` 响应的位置。0.1.1 实测断开请求约 0.27 毫秒返回并清空连接状态，后台释放约 61 秒后结束，随后恢复可操作状态。
|
||||
|
||||
**这些结果不能代替 HarmonyOS 6 真机兼容性验收。** 当前未记录任何机型的真实 USB 往返或吞吐量。连接实际手机后，按[调研文档验收清单](research/harmony-connector.md#验收与尚未证明的部分)补充完整机型/系统版本、空文件/中文/二进制/大文件往返 SHA-256、图库导出、取消、拔线、重新连接及退出的结果。
|
||||
|
||||
调研依据与备选 HDC 方案见[技术调研](research/harmony-connector.md)。依赖构建与替换说明见[第三方声明](../curios/harmony-connector/legal/THIRD-PARTY.md)。
|
||||
参考：[设备管理能力](research/harmony-device-management.md)、[会话恢复](research/harmony-mtp-session.md)、[投屏与控制](research/harmony-screen-control.md)、[第三方声明](../curios/harmony-connector/legal/THIRD-PARTY.md)。
|
||||
|
||||
Reference in New Issue
Block a user