Harmony Connector

插件 ID：dev.trove.harmony-connector。当前版本：0.2.0。

macOS 上的鸿蒙设备连接工具。通过 USB 收发文件与完整文件夹；使用官方 HDC 管理应用、保存截图、导出日志和调试应用数据。功能按连接工具、设备实际能力和授权开放，不按 HarmonyOS 大版本或机型名称限制。

安装

在 Trove 添加 Git 软件源：仓库 https://git.render.ink/trove/curios.git，唯一 ID trove-official（对应 source/index.json 顶层 id），显示名称可自行填写。刷新后安装 Harmony Connector。私有仓库使用本机 Git 凭据。

发布包适用于 Apple Silicon、macOS 13 及以上，内含 libmtp 1.1.23 和 libusb 1.0.30。Intel 需在对应 Mac 构建并单独验证后发布，当前未提供 Intel 包。

文件与文件夹

解锁手机，用支持数据传输的 USB 线连接 Mac，在手机上选择「传输文件」并允许访问。
插件启动后自动发现设备，选择手机并连接。也可手动扫描。
选择存储位置，进入目标目录。「发送文件」选择文件，「发送文件夹」选择整个目录；文件和文件夹旁的「接收」均可下载到 Mac。

文件功能不需要 HDC、ADB、Homebrew 或开发者模式。设备每约 2 秒自动检测一次；连接后仅检查 USB 存在性，不重复打开会话。手动断开后不会自行重新连接。

文件夹会保留层级、中文名称、空文件和空目录。整棵目录先检查再传输；总进度汇总全部文件，显示当前文件、已完成文件数、当前/平均速度、耗时和预计剩余时间。速度来自实际字节进度，不是预设数值。

不覆盖或合并同名条目。上传还会检查设备剩余容量，每次写入前再次检查目标名称。
下载先写入所选目录下的隐藏临时文件夹，全部文件长度校验成功后，原子保存为最终文件夹。失败或正常取消会清理此次临时内容。
不跟随符号链接，不传输特殊文件；拒绝路径穿越、循环、重名目录和超过 100,000 条目或 128 层的目录树。
上传中断时手机可能保留已创建的目录和文件。不会自动删除这些内容，请在手机上检查后再重试。底层 USB 事务取消需等待设备响应。
长度校验不等于端到端内容哈希校验；实际验收应将上传文件下载回来比较 SHA-256。
强制结束进程或断电可能留下 .harmony-*.part 临时内容。插件不会扫描或删除用户目录中的历史临时文件。

手机只开放 MTP 可见的存储，实际目录、访问权限和图库行为由设备决定；向普通目录发送照片不保证导入图库。本版不提供断点续传、无线 MTP、图库导入或全盘访问。

扫描名称取自 USB 描述符；连接后使用 MTP 友好名称并单独显示设备报告的型号。它可能不同于手机设置中的自定义名称。0.1.0 将 libmtp 匹配表中的 Nova14 误用于展示，0.1.1 已修复，不再把驱动匹配名称当作机型。

设备与应用

在「设备与应用」选择官方 SDK 的 hdc 可执行文件。插件会尝试发现 PATH 或 /Applications、~/Applications 中 DevEco Studio 的内置工具。典型路径：

/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains/hdc

也可使用华为官方 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 官方说明

最新 DevEco Studio 与 DevEco Testing 已提供官方 Mac 投屏功能；目前未找到可嵌入本插件的公开投屏协议。可行的插件路线是先以 HDC + UITest 实现截图预览和明确的点击/滑动输入，再单独验证用户授权的鸿蒙采集端、视频编码和传输。连续视频方案需要设备端适配，不能把截图轮询宣传成 scrcpy 视频流。详见投屏与键鼠控制调研。

重连问题与 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、重新枚举和设备端会话状态。见会话恢复调研。本轮诊断没有发现 USB 设备，故重连仍待真机复现和修复。

关闭插件窗口，保留一台解锁且处于「传输文件」模式的手机，然后执行：

# 仅枚举
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/。

pnpm install --frozen-lockfile
export TROVE_BIN=/absolute/path/to/app/target/debug/trove
pnpm run harmony:test
pnpm run harmony:pack
pnpm run release:prepare --entries dist/harmony-release.json

发布创建新的不可变版本产物，保留旧版本、哈希和生产源的已有条目。推送后必须以 Git 仓库为源执行安装验证。生产 README 保持产品介绍；技术约束与验收记录在本文和 docs/research/。

代码职责：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 的文件与管理工作区分开实现。

验证包括文件夹往返与失败清理、会话状态、工具命令和解析、安装确认及后置条件、页面交互、USB 桥接和底座协议。HDC 测试使用明确的工具替身，不代表商业手机已经完成安装、备份或截图验收。实际文件吞吐量和 USB 往返 SHA-256 仍需真机记录。

9.4 KiB Raw Blame History Unescape Escape