curios/docs/research/harmony-connector.md

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 文件传输、华为 Mac MTP 指引入口、libmtp 1.1.23 发布

HarmonyOS 6 的用户流程与边界

1. 使用支持数据传输的 USB 线连接 Mac 和手机，解锁手机。
2. 在手机 USB 弹窗或通知卡片选择“传输文件”，在 Harmony Connector 刷新设备并连接。
3. 浏览设备公开的存储，选择文件上传或下载。手机端仍决定哪些内容可见、可写。

华为的 6.0/6.1 说明区分两种模式：“传输文件”可访问文件管理中的内容，图库在此模式下可导出，但不能向图库导入照片或视频；图库双向操作应切换手机的“传输图片”模式。首版不能把图库导入失败当作普通文档上传失败，也不能承诺 PTP 模式已被本插件验收。华为 HarmonyOS 6 USB 文件传输

MTP 公开的是存储和对象层次，不能据此访问所有应用沙箱或系统目录。实现应直接显示设备返回的对象与存储，而不是硬编码 /sdcard、/data 等路径。libmtp 对象、存储与文件接口

Mac 上如有其他 MTP 应用占用设备，应关闭占用者后重试。libusb 官方说明：未被内核驱动独占的设备通常可直接访问，无需 root；驱动独占是另一种限制，不能通过插件静默提权、卸载驱动来掩盖。libusb macOS 访问说明、libmtp 已知设备占用问题

系统与协议比较

设备/路线	第一方证据	对本插件的意义
HarmonyOS 3/4.x 的 USB 文件传输	华为文档明确 MTP，并介绍 Mac 侧文件传输工具。来源	后续可按 MTP 实测扩展；不以“鸿蒙”名称判断底层协议。
HarmonyOS 5.0/5.1	华为 USB 文档指定手机至少 5.0.0.123；“传输文件”模式不访问图库，图库使用另一模式。来源	不能泛称所有早期 NEXT 系统均可用，也不能把 6.x 的图库行为回推至 5.x。
HarmonyOS 6.0/6.1	官方描述 USB 文件/图片传输流程。来源	本次主要目标，按公开对象浏览与传输设计。
ADB 与 HDC	华为开发工具的平台说明分别将 ADB 对应 4.0 及以下、HDC 对应 5.0 及以上。来源	ADB 不是 NEXT/5/6 的通用连接方案；消费者文件传输不应强制引入调试工具。
HiSuite	当前官网明确 HarmonyOS 5 及以上暂不支持在 macOS 上连接使用。来源	不作为插件底层，也不建议用户安装它以解决本插件连接。
华为分享	华为支持页列出手机/平板 6.0.0.112+ 与 Mac 10.15+，Mac 需运行“鸿蒙星河互联”，开启 WLAN/蓝牙。来源	已有官方无线方案，但本文未找到可嵌入的公开 macOS SDK/协议授权；不冒充官方分享客户端。

华为支持页中称为“MTP Tool”的工具，不应未经确认就指向 App Store 某个同名产品。该支持页下游链接在调研时跳转到支持搜索；可确认的是华为推荐 Mac 使用 MTP 工具，无法从此确认某个二进制实现、签名或私有握手。华为原始指引

标准 MTP 与库选择的源码证据

OpenHarmony 第一方 multimedia_media_library 的 media_mtp 使用 OpenSession、GetObjectHandles、GetObject、SendObjectInfo、SendObject 等标准操作与对应操作码，存在会话建立、目录对象查询和双向传输的直接实现。所查实现未显示普通文件传输必须先进行 HiSuite 专有认证。这是对所查开源代码的观察，不是商业 HarmonyOS 固件完全等同该源码的断言。操作定义、设备端操作处理

libmtp 1.1.23 发布说明包含 Huawei Nova14，设备表为 VID 0x12d1 / PID 0x1101，使用已有兼容标志。1.1.22 的设备表尚无该条目；因此首版选择 1.1.23。设备表条目证明上游已收录设备 ID，不能证明本插件在这台设备完成过读写。1.1.23 发布说明、1.1.23 设备表、1.1.22 设备表

libmtp 是基于 libusb 的 MTP 主机库，有现成 C 接口；libusb 明确支持 macOS 及 Apple Silicon，官方提供双架构构建说明。由项目固定版本编译 arm64/x86_64 产物，避免依赖用户电脑中的 Homebrew 路径。libmtp 架构、libusb 平台支持、libusb Apple Silicon

OpenMTP 可用作 macOS MTP 产品与集成的参考，但它当前 Kalam 内核使用 go-mtpx/go-mtpfs，不是直接复用 libmtp。仓库提供 Intel 和 ARM64 版本说明；其项目支持范围不能直接继承为 Harmony Connector 的支持范围。首版用 libmtp 以复用现有原生后端和 C ABI，避免另外加入 Go、Electron 及完整应用依赖。OpenMTP 源码说明、go-mtpx 模块依赖

原生后端实现契约

以下是基于库接口的实现建议，不是设备兼容性承诺：

能力	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 公开头文件。

工程约束：

• 设备会话和对象 ID 有生命周期；重连后重新枚举，不复用旧句柄。每个会话串行执行命令，传输时允许取消请求但不另开同设备读写。
• 界面通过结构化消息接收条目与进度，不解析 mtp-* 示例程序的输出。库本身也说明其命令行程序是示例。libmtp 示例说明
• 用本地文件描述符传输；下载先写独立临时文件，只有成功后才提交到用户选定目标，失败清理本次临时文件。默认拒绝同名覆盖或让用户明确选择。
• 设备返回的名字仍是不可信输入，拒绝路径分隔符、..、NUL 等会越出本地目标目录的名字；Unicode 和空格按原名处理。
• 取消是协作式的，不承诺设备卡死时立即停止；不要强杀执行 USB 调用的线程。阻塞请求交给有超时和退出边界的原生进程处理。libusb 同步 I/O 限制
• 不自动删除手机现有文件，不清空存储，不更改 USB 系统设置，不绕过手机锁屏或授权。

HDC 备选方案记录

HDC 可在 macOS 运行，通过 USB 或 TCP 调试连接，需设备启用调试并在信任提示中授权。官方获取入口是 DevEco Studio / Command Line Tools，独立运行需保留相邻的 libusb_shared 依赖。目标列表可显示未授权状态；TCP 在所查文档中被标注为测试用途。它适合开发者诊断，不作为本次消费者首版依赖。HDC 官方文档

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 第一方仓库使用说明。可访问性仍由设备限制；不能把 /data/local/tmp 调试目录当成手机文件管理的下载目录。应用沙箱 -b 仅适用于可调试应用；媒体目录也有 API 版本与操作限制。HDC 文件与沙箱访问

若将来加入 HDC 浏览，应先探测设备命令能力，用受控脚本、严格参数转义和明确分隔的字段输出，避免按空格拆 ls -l。OpenHarmony 的 Toybox stat 提供格式化字段，但不同固件需实测。Toybox stat 实现

HDC 开源仓库采用 Apache-2.0；这不自动授权重分发华为下载站的整个 SDK 或任意预编译工具。若采用该路线，优先使用用户已装官方工具，或对确切开源依赖自行构建并保存声明。HDC LICENSE、华为 Command Line Tools 下载

依赖与发布许可

libmtp 发布的 COPYING 为 LGPL 2.1，部分源文件头部保留 version 2 or later 表述；libusb 明确采用 LGPL 2.1 or later。应保留上游实际文本和版权，不自行统一改写原声明。libmtp COPYING、libmtp 头文件声明、libusb COPYING

对本次发布，选择可审查的具体做法：

1. 动态链接插件内的库，在第三方声明中标出名称、版本、原项目和许可证，随包提供完整 COPYING。
2. 与对应二进制一起提供完整上游源码归档、固定校验、实际补丁以及构建脚本。若归档独立发布，接收二进制的用户应能在同一分发位置以等价方式获取；只给上游主页不作为交付方案。
3. 保留用户用兼容修改版库替换、重新构建和运行插件的路径，并说明 macOS 重新签名/本地安装步骤；插件条款不得禁止为调试此类修改而逆向。
4. .curio 安装包与依赖源码都保持版本固定。上游源码或编译选项有变化时重新记录来源并发布新插件版本。

第 1—3 项直接对应 LGPL 2.1 第 4 节、第 6 节与第 6(b) 项；动态链接并不免除“已随包分发的库”自身的对应源码交付要求。LGPL 2.1 随 libmtp 的完整许可、LGPL 2.1 随 libusb 的完整许可

验收与尚未证明的部分

本调研完成了官方流程、第一方设备端代码、库 API 与许可核查。没有将真实设备复制记录、吞吐量或机型兼容性伪装成已完成结果。当前开发主机尚未检测到华为 USB 设备（由主任务本机检查提供）。

正式标记某机型可用前，记录 Mac 型号/架构、macOS 版本、手机型号、HarmonyOS 完整版本及 USB 模式，并执行：

• 未连接、锁屏、仅充电、文件传输、拒绝授权、设备被其他工具占用等状态。
• 枚举多个设备与存储，选择后浏览，不访问未选中的设备。
• 单文件上传和下载：空文件、中文/空格/emoji 名称、二进制和大文件，回传后比较 SHA-256。
• 同名目标处理、磁盘空间不足、只读目录、权限拒绝、传输中拔线和取消，确认既有文件未被破坏。
• 连接关闭、重连、插件退出、底座退出后 USB 会话正常释放。
• HarmonyOS 6 图库导入限制有可理解反馈，不用文档目录成功代替图库验收。

通过库级测试、模拟传输、无设备枚举或包安装测试，只能证明对应层的行为，不能替代上述真实 USB 读写。