115 lines
14 KiB
Markdown
115 lines
14 KiB
Markdown
# Harmony Connector 技术调研
|
||
|
||
调研日期：2026-09-10。目标是 macOS 与 HarmonyOS 6 设备之间浏览、上传和下载用户文件。本文区分官方说明、源码证据与实现推断；尚无本项目的 HarmonyOS 6 真机传输验收结果。
|
||
|
||
## 决定：首版使用 USB MTP
|
||
|
||
采用 **libmtp 1.1.23 + libusb 1.0.30**，由 Curio 原生后端管理 USB 会话，界面提供设备选择、存储与文件夹浏览、双向文件传输及进度。依赖随插件发布，用户无需另装开发 SDK。首版聚焦 USB，不同时实现 HDC、ADB 或华为分享。
|
||
|
||
选择依据：华为为 HarmonyOS 6.0/6.1 提供“解锁设备 → 数据线连接 → 选择传输文件”的官方使用流程；其 Mac 支持说明也引导使用 MTP 工具。该消费者流程没有要求开启开发者选项。OpenHarmony 的设备端源码实现了标准 MTP 操作，libmtp 当前发布版已加入较新的华为设备标识。这些证据足以支持开发路线，**不等于特定商业机型已验证兼容**。[华为 HarmonyOS 6 USB 文件传输](https://consumer.huawei.com/cn/support/content/zh-cn16090699/)、[华为 Mac MTP 指引入口](https://consumer.huawei.com/cn/support/content/zh-cn16083899/)、[libmtp 1.1.23 发布](https://github.com/libmtp/libmtp/releases/tag/v1.1.23)
|
||
|
||
## HarmonyOS 6 的用户流程与边界
|
||
|
||
1. 使用支持数据传输的 USB 线连接 Mac 和手机，解锁手机。
|
||
2. 在手机 USB 弹窗或通知卡片选择“传输文件”，在 Harmony Connector 刷新设备并连接。
|
||
3. 浏览设备公开的存储，选择文件上传或下载。手机端仍决定哪些内容可见、可写。
|
||
|
||
华为的 6.0/6.1 说明区分两种模式：“传输文件”可访问文件管理中的内容，图库在此模式下可导出，但不能向图库导入照片或视频；图库双向操作应切换手机的“传输图片”模式。首版不能把图库导入失败当作普通文档上传失败，也不能承诺 PTP 模式已被本插件验收。[华为 HarmonyOS 6 USB 文件传输](https://consumer.huawei.com/cn/support/content/zh-cn16090699/)
|
||
|
||
MTP 公开的是存储和对象层次，不能据此访问所有应用沙箱或系统目录。实现应直接显示设备返回的对象与存储，而不是硬编码 `/sdcard`、`/data` 等路径。[libmtp 对象、存储与文件接口](https://github.com/libmtp/libmtp/blob/v1.1.23/src/libmtp.h.in)
|
||
|
||
Mac 上如有其他 MTP 应用占用设备，应关闭占用者后重试。libusb 官方说明：未被内核驱动独占的设备通常可直接访问，无需 root；驱动独占是另一种限制，不能通过插件静默提权、卸载驱动来掩盖。[libusb macOS 访问说明](https://github.com/libusb/libusb/wiki/FAQ#how-can-i-run-libusb-applications-under-macos-if-there-is-already-a-kernel-extension-installed-for-the-device-and-claim-exclusive-access)、[libmtp 已知设备占用问题](https://github.com/libmtp/libmtp/blob/v1.1.23/README)
|
||
|
||
## 系统与协议比较
|
||
|
||
| 设备/路线 | 第一方证据 | 对本插件的意义 |
|
||
| --- | --- | --- |
|
||
| HarmonyOS 3/4.x 的 USB 文件传输 | 华为文档明确 MTP，并介绍 Mac 侧文件传输工具。[来源](https://consumer.huawei.com/cn/support/content/zh-cn00407259/) | 后续可按 MTP 实测扩展；不以“鸿蒙”名称判断底层协议。 |
|
||
| HarmonyOS 5.0/5.1 | 华为 USB 文档指定手机至少 5.0.0.123；“传输文件”模式不访问图库，图库使用另一模式。[来源](https://consumer.huawei.com/cn/support/content/zh-cn16059258/) | 不能泛称所有早期 NEXT 系统均可用，也不能把 6.x 的图库行为回推至 5.x。 |
|
||
| HarmonyOS 6.0/6.1 | 官方描述 USB 文件/图片传输流程。[来源](https://consumer.huawei.com/cn/support/content/zh-cn16090699/) | 本次主要目标，按公开对象浏览与传输设计。 |
|
||
| ADB 与 HDC | 华为开发工具的平台说明分别将 ADB 对应 4.0 及以下、HDC 对应 5.0 及以上。[来源](https://developer.huawei.com/consumer/cn/doc/tools-guides/overview-0000001050741459) | ADB 不是 NEXT/5/6 的通用连接方案；消费者文件传输不应强制引入调试工具。 |
|
||
| HiSuite | 当前官网明确 HarmonyOS 5 及以上暂不支持在 macOS 上连接使用。[来源](https://consumer.huawei.com/cn/support/hisuite/) | 不作为插件底层，也不建议用户安装它以解决本插件连接。 |
|
||
| 华为分享 | 华为支持页列出手机/平板 6.0.0.112+ 与 Mac 10.15+，Mac 需运行“鸿蒙星河互联”，开启 WLAN/蓝牙。[来源](https://consumer.huawei.com/cn/support/content/zh-cn16093657/) | 已有官方无线方案，但本文未找到可嵌入的公开 macOS SDK/协议授权；不冒充官方分享客户端。 |
|
||
|
||
华为支持页中称为“MTP Tool”的工具，不应未经确认就指向 App Store 某个同名产品。该支持页下游链接在调研时跳转到支持搜索；可确认的是华为推荐 Mac 使用 MTP 工具，无法从此确认某个二进制实现、签名或私有握手。[华为原始指引](https://consumer.huawei.com/cn/support/content/zh-cn16083899/)
|
||
|
||
## 标准 MTP 与库选择的源码证据
|
||
|
||
OpenHarmony 第一方 `multimedia_media_library` 的 `media_mtp` 使用 `OpenSession`、`GetObjectHandles`、`GetObject`、`SendObjectInfo`、`SendObject` 等标准操作与对应操作码，存在会话建立、目录对象查询和双向传输的直接实现。所查实现未显示普通文件传输必须先进行 HiSuite 专有认证。**这是对所查开源代码的观察，不是商业 HarmonyOS 固件完全等同该源码的断言。**[操作定义](https://github.com/openharmony/multimedia_media_library/blob/4a411de74cfaf694c14820a51a0e900b04241fe6/services/media_mtp/include/mtp_constants.h)、[设备端操作处理](https://github.com/openharmony/multimedia_media_library/blob/4a411de74cfaf694c14820a51a0e900b04241fe6/services/media_mtp/src/mtp_operation.cpp)
|
||
|
||
libmtp 1.1.23 发布说明包含 Huawei Nova14，设备表为 `VID 0x12d1 / PID 0x1101`，使用已有兼容标志。1.1.22 的设备表尚无该条目；因此首版选择 1.1.23。设备表条目证明上游已收录设备 ID，不能证明本插件在这台设备完成过读写。[1.1.23 发布说明](https://github.com/libmtp/libmtp/releases/tag/v1.1.23)、[1.1.23 设备表](https://github.com/libmtp/libmtp/blob/v1.1.23/src/music-players.h)、[1.1.22 设备表](https://github.com/libmtp/libmtp/blob/v1.1.22/src/music-players.h)
|
||
|
||
libmtp 是基于 libusb 的 MTP 主机库，有现成 C 接口；libusb 明确支持 macOS 及 Apple Silicon，官方提供双架构构建说明。由项目固定版本编译 arm64/x86_64 产物，避免依赖用户电脑中的 Homebrew 路径。[libmtp 架构](https://github.com/libmtp/libmtp/blob/v1.1.23/README)、[libusb 平台支持](https://github.com/libusb/libusb/blob/v1.0.30/README)、[libusb Apple Silicon](https://github.com/libusb/libusb/wiki/FAQ#does-libusb-support-apple-silicon-based-mac)
|
||
|
||
OpenMTP 可用作 macOS MTP 产品与集成的参考，但它当前 Kalam 内核使用 `go-mtpx`/`go-mtpfs`，不是直接复用 libmtp。仓库提供 Intel 和 ARM64 版本说明；其项目支持范围不能直接继承为 Harmony Connector 的支持范围。首版用 libmtp 以复用现有原生后端和 C ABI，避免另外加入 Go、Electron 及完整应用依赖。[OpenMTP 源码说明](https://github.com/ganeshrvel/openmtp)、[go-mtpx 模块依赖](https://github.com/ganeshrvel/go-mtpx/blob/18f12db021cc4256396748dbd2996d15853d7033/go.mod)
|
||
|
||
## 原生后端实现契约
|
||
|
||
以下是基于库接口的实现建议，不是设备兼容性承诺：
|
||
|
||
| 能力 | libmtp API / 规则 |
|
||
| --- | --- |
|
||
| 枚举与连接 | `LIBMTP_Detect_Raw_Devices`；用户选定后 `LIBMTP_Open_Raw_Device_Uncached`，避免连接即扫描全部文件。 |
|
||
| 存储与浏览 | `LIBMTP_Get_Storage`；`LIBMTP_Get_Files_And_Folders(device, storageId, parentId)`。根对象参数使用库的 `LIBMTP_FILES_AND_FOLDERS_ROOT`。 |
|
||
| 下载 | `LIBMTP_Get_File_To_File_Descriptor`，按 object ID 获取数据。 |
|
||
| 上传 | `LIBMTP_Send_File_From_File_Descriptor`，明确文件名、字节长度、目标 storage ID 和 parent ID。 |
|
||
| 进度/取消 | 库回调返回累计字节及总字节；返回非零值可请求取消当前传输。 |
|
||
| 失败与释放 | 每次操作读取并清理 error stack，断开时 `LIBMTP_Release_Device`。 |
|
||
|
||
接口依据：[libmtp 1.1.23 公开头文件](https://github.com/libmtp/libmtp/blob/v1.1.23/src/libmtp.h.in)。
|
||
|
||
工程约束：
|
||
|
||
- 设备会话和对象 ID 有生命周期；重连后重新枚举，不复用旧句柄。每个会话串行执行命令，传输时允许取消请求但不另开同设备读写。
|
||
- 界面通过结构化消息接收条目与进度，不解析 `mtp-*` 示例程序的输出。库本身也说明其命令行程序是示例。[libmtp 示例说明](https://github.com/libmtp/libmtp/blob/v1.1.23/README)
|
||
- 用本地文件描述符传输；下载先写独立临时文件，只有成功后才提交到用户选定目标，失败清理本次临时文件。默认拒绝同名覆盖或让用户明确选择。
|
||
- 设备返回的名字仍是不可信输入，拒绝路径分隔符、`..`、NUL 等会越出本地目标目录的名字；Unicode 和空格按原名处理。
|
||
- 取消是协作式的，不承诺设备卡死时立即停止；不要强杀执行 USB 调用的线程。阻塞请求交给有超时和退出边界的原生进程处理。[libusb 同步 I/O 限制](https://github.com/libusb/libusb/wiki/FAQ#what-are-the-differences-between-synchronous-and-asynchronous-device-io)
|
||
- 不自动删除手机现有文件，不清空存储，不更改 USB 系统设置，不绕过手机锁屏或授权。
|
||
|
||
## HDC 备选方案记录
|
||
|
||
HDC 可在 macOS 运行，通过 USB 或 TCP 调试连接，需设备启用调试并在信任提示中授权。官方获取入口是 DevEco Studio / Command Line Tools，独立运行需保留相邻的 `libusb_shared` 依赖。目标列表可显示未授权状态；TCP 在所查文档中被标注为测试用途。它适合开发者诊断，不作为本次消费者首版依赖。[HDC 官方文档](https://github.com/openharmony/docs/blob/master/zh-cn/application-dev/dfx/hdc.md)
|
||
|
||
```text
|
||
hdc list targets -v
|
||
hdc -t <device> shell <command>
|
||
hdc -t <device> file send <local-file> <remote-file>
|
||
hdc -t <device> file recv <remote-file> <local-file>
|
||
hdc tconn <ip>:<port>
|
||
```
|
||
|
||
这些命令来自 [HDC 第一方仓库使用说明](https://github.com/openharmony/developtools_hdc/blob/e93f663afa159d3e601cad1e1869d70326731af6/README_zh.md)。可访问性仍由设备限制；不能把 `/data/local/tmp` 调试目录当成手机文件管理的下载目录。应用沙箱 `-b` 仅适用于可调试应用；媒体目录也有 API 版本与操作限制。[HDC 文件与沙箱访问](https://github.com/openharmony/docs/blob/master/zh-cn/application-dev/dfx/hdc.md#文件传输)
|
||
|
||
若将来加入 HDC 浏览，应先探测设备命令能力，用受控脚本、严格参数转义和明确分隔的字段输出，避免按空格拆 `ls -l`。OpenHarmony 的 Toybox `stat` 提供格式化字段，但不同固件需实测。[Toybox stat 实现](https://github.com/openharmony/third_party_toybox/blob/master/toys/other/stat.c)
|
||
|
||
HDC 开源仓库采用 Apache-2.0；这不自动授权重分发华为下载站的整个 SDK 或任意预编译工具。若采用该路线，优先使用用户已装官方工具，或对确切开源依赖自行构建并保存声明。[HDC LICENSE](https://github.com/openharmony/developtools_hdc/blob/e93f663afa159d3e601cad1e1869d70326731af6/LICENSE)、[华为 Command Line Tools 下载](https://developer.huawei.com/consumer/cn/download/command-line-tools-for-hmos)
|
||
|
||
## 依赖与发布许可
|
||
|
||
libmtp 发布的 `COPYING` 为 LGPL 2.1，部分源文件头部保留 version 2 or later 表述；libusb 明确采用 LGPL 2.1 or later。应保留上游实际文本和版权，不自行统一改写原声明。[libmtp COPYING](https://github.com/libmtp/libmtp/blob/v1.1.23/COPYING)、[libmtp 头文件声明](https://github.com/libmtp/libmtp/blob/v1.1.23/src/libmtp.h.in)、[libusb COPYING](https://github.com/libusb/libusb/blob/v1.0.30/COPYING)
|
||
|
||
对本次发布，选择可审查的具体做法：
|
||
|
||
1. 动态链接插件内的库，在第三方声明中标出名称、版本、原项目和许可证，随包提供完整 `COPYING`。
|
||
2. 与对应二进制一起提供完整上游源码归档、固定校验、实际补丁以及构建脚本。若归档独立发布，接收二进制的用户应能在同一分发位置以等价方式获取；只给上游主页不作为交付方案。
|
||
3. 保留用户用兼容修改版库替换、重新构建和运行插件的路径，并说明 macOS 重新签名/本地安装步骤；插件条款不得禁止为调试此类修改而逆向。
|
||
4. `.curio` 安装包与依赖源码都保持版本固定。上游源码或编译选项有变化时重新记录来源并发布新插件版本。
|
||
|
||
第 1—3 项直接对应 LGPL 2.1 第 4 节、第 6 节与第 6(b) 项；动态链接并不免除“已随包分发的库”自身的对应源码交付要求。[LGPL 2.1 随 libmtp 的完整许可](https://github.com/libmtp/libmtp/blob/v1.1.23/COPYING)、[LGPL 2.1 随 libusb 的完整许可](https://github.com/libusb/libusb/blob/v1.0.30/COPYING)
|
||
|
||
## 验收与尚未证明的部分
|
||
|
||
本调研完成了官方流程、第一方设备端代码、库 API 与许可核查。没有将真实设备复制记录、吞吐量或机型兼容性伪装成已完成结果。当前开发主机尚未检测到华为 USB 设备（由主任务本机检查提供）。
|
||
|
||
正式标记某机型可用前，记录 Mac 型号/架构、macOS 版本、手机型号、HarmonyOS 完整版本及 USB 模式，并执行：
|
||
|
||
- 未连接、锁屏、仅充电、文件传输、拒绝授权、设备被其他工具占用等状态。
|
||
- 枚举多个设备与存储，选择后浏览，不访问未选中的设备。
|
||
- 单文件上传和下载：空文件、中文/空格/emoji 名称、二进制和大文件，回传后比较 SHA-256。
|
||
- 同名目标处理、磁盘空间不足、只读目录、权限拒绝、传输中拔线和取消，确认既有文件未被破坏。
|
||
- 连接关闭、重连、插件退出、底座退出后 USB 会话正常释放。
|
||
- HarmonyOS 6 图库导入限制有可理解反馈，不用文档目录成功代替图库验收。
|
||
|
||
通过库级测试、模拟传输、无设备枚举或包安装测试，只能证明对应层的行为，不能替代上述真实 USB 读写。
|