curios/docs/harmony-connector.md

Harmony Connector

插件 ID：dev.trove.harmony-connector。当前版本：0.5.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 包。

文件与文件夹

1. 解锁手机，用支持数据传输的 USB 线连接 Mac，在手机上选择「传输文件」并允许访问。
2. 插件启动后自动发现设备，选择手机并连接。也可手动扫描。
3. 选择存储位置，进入目标目录。「发送文件」选择文件，「发送文件夹」选择整个目录；文件和文件夹旁的「接收」均可下载到 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 已修复，不再把驱动匹配名称当作机型。

设备与应用

首次进入「设备与应用」，如果没有可用 HDC，页面会显示安装引导：

1. 点击「前往华为官网下载」，在浏览器打开 Command Line Tools 官方下载页。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、~/Library/HarmonyConnector/tools 中的工具安装、~/Downloads 中已解压的 Command Line Tools、/Applications 和 ~/Applications 中的 DevEco Studio 依次查找。工具安装目录按数字版本从新到旧检查，跳过未包含可执行 HDC 的目录；Downloads 只检查名称以 command-line-tools 或 commandline-tools 开头的直接子目录及 SDK 的标准位置，不递归扫描用户文件、不将 ZIP 视为已安装工具。典型路径：

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

请保留完整的工具目录及同目录依赖库，插件不重打包官方 SDK。选择路径保存在插件自己的数据目录中；工具被移动、删除或无法运行时重新显示安装引导和原因。工具准备完成前隐藏空设备列表及不可用的管理面板，文件传输仍可直接使用。管理页明确选择 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 就宣称备份成功。

管理操作使用独立串行任务，支持取消与超时；取消不回滚设备端已经完成的更改。操作开始前重新确认所选设备在线。功能有命令支持仍可能被单个应用、对象或系统权限拒绝，失败会显示设备返回的原因。

投屏与控制

在「设备与应用」选择已授权的 HDC 目标，点击「打开投屏窗口」。投屏使用独立的 macOS 窗口，默认可以直接通过画面控制手机。

• 鼠标按下、拖动、松开即时发送触摸动作；按住即可长按，滚轮滑动，右键返回，中键回到主页。
• ⌘F 切换全屏，⌘V 向手机粘贴剪贴板文字，⌘R 切换仅观看，⌘W 关闭投屏。方向键、回车、退格直接作用于手机。
• 窗口标题显示显示帧率和接收码率。只保留最新解码画面，避免积累播放延迟。
• 切换管理页和文件页、隐藏管理窗口不停止投屏。关闭投屏窗口或点击「停止投屏」会释放设备会话；退出插件也会停止。
• 失焦、关闭窗口和画面方向变化时释放当前触摸；移动事件合并，按下和松开保持顺序，不在重连后重放输入。

0.5.0 使用官方 Hypium 26 的 Unix H.264 recorder 和独立控制代理，经 HDC 转发视频及触摸通道。手机端编码，Mac 端 VideoToolbox 解码并立即显示。无需开发者账号、签名、手机应用或完整 SDK；用户只需官方 HDC 和已授权的设备 USB 调试。编码配置目标为 60 fps、8 Mbps、半尺寸，实际流畅度取决于设备，当前版本尚未进行真机性能验收。

组件与传输依据见官方视频与触控调研。旧 JPEG 后端接口仅保留用于诊断；管理页已使用独立视频窗口。

重连问题与 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.3.0 真机复现了 CloseSession 等待 60 秒的问题。固定 libmtp 依赖增加一个小补丁，仅把 CloseSession 的超时设为 2 秒，文件传输超时、接口释放、现有 USB reset 与关闭顺序保持不变。macOS 重枚举有短暂离线窗口，诊断程序最多等 10 秒重新发现设备，再实际打开并读取存储和目录。

2026-09-10，在同一 USB 插接周期，开发构建与发布构建各完成 3 轮只读重连，每轮返回 1 个存储和 9 个根目录条目。开发构建关闭约 2.28–2.33 秒；发布构建约 2.13–7.28 秒，包含 USB 重枚举耗时。设备仍不正常响应 CloseSession，恢复由随后的 USB 清理/reset 完成；不能将 2 秒超时宣传为所有设备都固定 2 秒完成断开。该结果覆盖这台手机，不代表全部固件。见会话恢复调研。

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

# 仅枚举
curios/harmony-connector/backend/harmony-connector --diagnose

# 只读执行三轮打开、存储/目录读取、关闭与重新打开；不要在插件占用 USB 时运行
curios/harmony-connector/backend/harmony-connector --check-reconnect

--check-reconnect 逐阶段输出 JSON、耗时和实际目录读取结果，不修改手机文件。没有恰好一台设备或任何一轮失败时以非零状态结束；CloseSession 时限为 2 秒，USB 清理和重枚举仍可能增加耗时。不能仅凭扫描发现设备、按钮可用或 reset 返回成功判定验收通过。

只读验证投屏（先完成手机 USB 调试授权）：

curios/harmony-connector/backend/harmony-connector --check-screen /absolute/path/to/hdc
# 多台设备时可指定目标；最后的可选目录用于保存最终画面
curios/harmony-connector/backend/harmony-connector --check-screen /absolute/path/to/hdc DEVICE_ID /absolute/save/directory

该命令走 UI 相同的后端接口，采集并解码 3 帧，输出耗时，最后关闭会话；不启用控制、不发送输入。首次 HDC 连接显示 Unauthorized 时，在手机上允许 USB 调试。hdc -v 能运行但管理失败时，先用 hdc list targets -v 检查授权状态。

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，后续投屏验收因无已授权设备而停止。

0.3.2 补上工具安装目录和 Downloads 的自动发现。回归在独立 HOME、空 PATH 工具目录、未保存任何设置的进程中运行真实 Manager::new → hdc.tool，验证数字版本选择、未完成解压跳过、手动路径优先和官方解压目录布局。实际 Mac 验证通过 Wire 请求 hdc.tool，使用空插件数据目录和系统 PATH，未调用 configure；0.3.1 返回 available: false，0.3.2 自动找到之前解压的工具并返回 Ver: 3.2.0f。USB 目标仍为 Unauthorized。该版 42 项原生测试、30 项 UI/格式/坐标测试及 6 项 USB/协议检查全部通过。

0.4.0 的 HDC 持续采集与会话恢复通过 54 项原生、33 项 UI/格式/坐标、6 项 USB/协议检查（共 93 项）。真机连续三轮开始、接收并解码 JPEG、停止和重新开始全部成功，每轮均确认代理和转发清理，无需拔线。新增回归覆盖自身孤儿进程恢复、结束失败不误报其他工具、多个窗口的同设备锁、仅恢复自身转发以及 JPEG 对齐填充的显示/输入坐标。浏览器确认填充裁切与放大布局。该轮没有发送真机输入或测量动态性能，详见开发验证。

构建与发布

要求 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 管理官方工具与输出校验，hdc/screen.rs / screen_input.rs 管理屏幕会话与输入，command.rs 控制进程、输出、取消和时限。UI 的文件与管理工作区分开实现。

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

参考：设备管理能力、会话恢复、投屏与控制、第三方声明。