103 lines
9.4 KiB
Markdown
103 lines
9.4 KiB
Markdown
# 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 包。
|
||
|
||
## 文件与文件夹
|
||
|
||
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 已修复，不再把驱动匹配名称当作机型。
|
||
|
||
## 设备与应用
|
||
|
||
在「设备与应用」选择官方 SDK 的 `hdc` 可执行文件。插件会尝试发现 PATH 或 `/Applications`、`~/Applications` 中 DevEco Studio 的内置工具。典型路径：
|
||
|
||
```text
|
||
/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 官方说明](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
|
||
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 仍需真机记录。
|
||
|
||
参考：[设备管理能力](research/harmony-device-management.md)、[会话恢复](research/harmony-mtp-session.md)、[投屏与控制](research/harmony-screen-control.md)、[第三方声明](../curios/harmony-connector/legal/THIRD-PARTY.md)。
|