render
6bdcfdb44e
Use USB descriptors and MTP identity instead of the static libmtp product label. Monitor attachment, discard stale UI responses, clear disconnected views, and release slow MTP sessions in the background while preserving operation serialization. Publish 0.1.1 with immutable source history. Cover discovery, names, unplugging and slow disconnect with native and UI regressions. Verify real Pura 70 Ultra identity and prompt disconnect; run the newest published backend during Git-source checks.
92 lines
7.6 KiB
Markdown
92 lines
7.6 KiB
Markdown
# Harmony Connector
|
||
|
||
插件 ID：`dev.trove.harmony-connector`。版本：`0.1.1`。
|
||
|
||
面向 HarmonyOS 6 的 USB 文件传输插件，提供设备选择、存储与目录浏览、分页、名称筛选、新建目录，以及单文件发送/接收、字节进度与取消。使用 libmtp 1.1.23 和 libusb 1.0.30，无需手机开发者模式、HDC、ADB 或 Homebrew 运行依赖。
|
||
|
||
## 安装与使用
|
||
|
||
在 Trove 添加 Git 软件源：
|
||
|
||
- 仓库地址：`https://git.render.ink/trove/curios.git`
|
||
- 唯一 ID：`trove-official`（仓库 `source/index.json` 顶层 `id`）。
|
||
- 显示名称：可以自定义，例如「Trove 官方软件源」。
|
||
|
||
刷新源后安装 **Harmony Connector**。私有仓库使用本机 Git 凭据。当前发布的是 Apple Silicon (`aarch64-apple-darwin`) 包，部署目标为 macOS 13 及以上；Intel 需要在对应 Mac 上构建并追加该架构产物，未发布未经验证的 Intel 包。
|
||
|
||
1. 解锁手机，用支持数据传输的 USB 线连接 Mac。
|
||
2. 在手机 USB 选项中选择「传输文件」，允许访问。
|
||
3. 等待插件自动发现设备，选择并连接，打开目标文件夹。也可手动点击「扫描设备」。
|
||
4. 点击「发送文件」从 Mac 选择一个文件；点击文件旁的「接收」选择 Mac 接收文件夹。
|
||
|
||
本插件只访问手机通过 MTP 开放的存储。目录来自设备对象 ID，不映射为 Android 路径。HarmonyOS 6 在文件传输模式下允许导出图库内容，导入图库需要图片传输模式；本版未实现 PTP 图库导入。[华为 HarmonyOS 6 官方说明](https://consumer.huawei.com/cn/support/content/zh-cn16090699/)
|
||
|
||
没有发现设备时，检查数据线和 USB 模式、保持手机解锁，退出占用手机的其他传输应用后重试。取消或 USB 操作失败会释放会话，请重新连接。取消是协作式的，需要等待手机或 USB 超时返回，不保证立即完成。
|
||
|
||
插件打开时立即扫描，随后在空闲时约每 2 秒检测一次。已连接时只检查 USB 设备是否仍存在，不重复打开 MTP 会话；传输期间也检测拔线并请求结束传输。发现设备后仍由用户选择连接，手动断开不会立即自动重连。
|
||
|
||
手动断开会立即清空文件和连接界面，USB 会话在后台释放；清理期间显示提示并暂时禁用连接，完成后继续自动发现。设备不响应 MTP 关闭请求时，底层释放仍可能需要等待 USB 超时。
|
||
|
||
名称在扫描阶段来自 USB 描述符；连接后优先使用设备通过 MTP 返回的友好名称，并单独显示设备报告的型号。友好名称由固件提供，不一定等于系统设置中的自定义设备名；缺失时回退到型号或 USB 名称。libmtp 的静态设备匹配表只用于协议兼容，不作为型号展示依据；0.1.0 曾把其中的 `Nova14` 兼容条目误用为设备名称，0.1.1 已修复。
|
||
|
||
## 文件保护与边界
|
||
|
||
- 一次传输一个普通文件；目录请先压缩。不提供删除手机内容的操作。
|
||
- 拒绝同名覆盖。接收使用目标目录内的隐藏临时文件，校验长度并同步后通过原子无覆盖操作保存。发送会校验目标名称、存储空间和传输后设备报告的长度。
|
||
- 长度校验不是内容哈希验证。实际设备验收需回传文件并比较 SHA-256。
|
||
- 接收失败或正常取消会清理本次临时文件。手机端可能保留未完成的上传对象，需要在手机上检查处理。
|
||
- 不在传输过程中关闭插件。强制结束进程、USB 长时间阻塞或断电时可能留下 `.harmony-*.part`；正常退出请求最多等待约 3.5 秒，再由底座回收进程。重新启动不会扫描或删除用户目录里的历史临时文件。
|
||
- 目前不提供无线、批量/递归目录传输、断点续传或图库导入。跨存储、机型文件权限与大文件限制以实际设备为准。
|
||
|
||
## 构建、验证与发布
|
||
|
||
要求 macOS、Xcode Command Line Tools、Rust/Cargo、Node.js、pnpm、make、pkg-config。源码归档及哈希固定在 `vendor/harmony-connector/`。构建不需要另装 libmtp。
|
||
|
||
```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
|
||
```
|
||
|
||
以上命令只构建 Harmony Connector，发布时保留生产索引中其他插件和历史版本。索引和不可变 `.curio` 包必须同一提交推送，不能覆盖已发布的同版本同架构文件。
|
||
|
||
推送后验证真实 Git 软件源：
|
||
|
||
```sh
|
||
TROVE_APP_DIR=/absolute/path/to/app \
|
||
pnpm run verify --remote-source https://git.render.ink/trove/curios.git \
|
||
--source-id trove-official --source-kind git
|
||
```
|
||
|
||
界面测试使用独立的显式模拟设备，预览脚本和数据不进入安装包：
|
||
|
||
```sh
|
||
pnpm run harmony:build
|
||
node tools/preview-harmony.mjs
|
||
# 打开 http://127.0.0.1:18770
|
||
```
|
||
|
||
## 代码与接口
|
||
|
||
| 位置 | 职责 |
|
||
| --- | --- |
|
||
| `curios/harmony-connector/ui/` | 独立界面，通过版本化 Trove SDK 调用 Host 文件选择器与 `@self` |
|
||
| `native/src/connector.rs` | 会话串行化、文件校验、后台传输任务、取消及完成状态 |
|
||
| `native/src/mtp.rs`、`mtp_bridge.c` | libmtp 所有权、结构转换、文件描述符传输 |
|
||
| `native/src/wire.rs` | Trove Wire v1 认证握手、请求分发与退出 |
|
||
| `build.mjs`、`legal/` | 固定依赖构建、动态库路径修正、签名与第三方声明 |
|
||
|
||
`@self` 接口：`info`、`devices`、`monitor`、`connect({id})`、`disconnect`、`list({storage,parent,offset?})`、`mkdir({storage,parent,name})`、`transfer(...)`、`transferStatus`、`cancelTransfer({id})`。根目录为 `0xffffffff`；目录响应每页最多 500 个条目，传输异步返回任务 ID，界面轮询实际进度。后端同一时刻仅执行一个 MTP 操作；进度查询、取消及 USB 存在性检查不等待 MTP 锁。重新连接后必须重新获取对象列表。
|
||
|
||
## 验证记录与真机验收
|
||
|
||
自动测试包含 16 项传输与会话行为测试、10 项完整界面回归测试、2 项界面数据测试、3 项原生 USB 边界检查，以及 Trove 的握手、并发响应、退出协议测试。传输行为测试使用独立内存设备并实际读写临时目录；界面回归测试加载真实页面和 SDK，在模拟硬件边界下验证自动发现、名称、手动断开、慢速 USB 释放、拔线、旧响应与页面关闭。原生边界检查复现静态表 `Nova14` 与设备实际报告信息不同的场景，并验证友好名称和 USB 存在性检测。
|
||
|
||
2026-09-10，HUAWEI Pura 70 Ultra 的实机只读连接测试返回 USB ID `12d1:1101`、USB 名称 `HDC Device`、MTP 友好名称 `HUAWEI Pura 70 Ultra`、型号代码 `HBP-AL00`，并成功读取内部存储信息。该设备的 MTP 返回值未包含系统设置中的自定义名称。实机还复现了关闭 MTP 会话时的长时间等待；原生调用栈停在等待 `CloseSession` 响应的位置。0.1.1 实测断开请求约 0.27 毫秒返回并清空连接状态，后台释放约 61 秒后结束，随后恢复可操作状态。
|
||
|
||
**这些结果不能代替 HarmonyOS 6 真机兼容性验收。** 当前未记录任何机型的真实 USB 往返或吞吐量。连接实际手机后，按[调研文档验收清单](research/harmony-connector.md#验收与尚未证明的部分)补充完整机型/系统版本、空文件/中文/二进制/大文件往返 SHA-256、图库导出、取消、拔线、重新连接及退出的结果。
|
||
|
||
调研依据与备选 HDC 方案见[技术调研](research/harmony-connector.md)。依赖构建与替换说明见[第三方声明](../curios/harmony-connector/legal/THIRD-PARTY.md)。
|