feat: add Harmony Connector for HarmonyOS 6 USB file transfer
This commit is contained in:
@@ -0,0 +1,83 @@
|
||||
# Harmony Connector
|
||||
|
||||
插件 ID：`dev.trove.harmony-connector`。版本：`0.1.0`。
|
||||
|
||||
面向 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 超时返回，不保证立即完成。
|
||||
|
||||
## 文件保护与边界
|
||||
|
||||
- 一次传输一个普通文件；目录请先压缩。不提供删除手机内容的操作。
|
||||
- 拒绝同名覆盖。接收使用目标目录内的隐藏临时文件，校验长度并同步后通过原子无覆盖操作保存。发送会校验目标名称、存储空间和传输后设备报告的长度。
|
||||
- 长度校验不是内容哈希验证。实际设备验收需回传文件并比较 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`、`connect({id})`、`disconnect`、`list({storage,parent,offset?})`、`mkdir({storage,parent,name})`、`transfer(...)`、`transferStatus`、`cancelTransfer({id})`。根目录为 `0xffffffff`；目录响应每页最多 500 个条目，传输异步返回任务 ID，界面轮询实际进度。后端同一时刻仅执行一个 USB 操作；进度查询和取消不等待 USB 锁。重新连接后必须重新获取对象列表。
|
||||
|
||||
## 验证记录与真机验收
|
||||
|
||||
开发机的原生 USB 扫描正常返回空设备列表。完成的自动测试包含 10 项传输行为测试、2 项界面数据测试，以及 Trove 的握手、并发响应、退出协议测试；传输行为测试使用独立内存设备并实际读写临时目录。浏览器中验证模拟设备选择、导航、中文目录、筛选、不可信文件名显示、进度、完成和取消状态。
|
||||
|
||||
**这些结果不能代替 HarmonyOS 6 真机兼容性验收。** 当前未记录任何机型的真实 USB 往返或吞吐量。连接实际手机后，按[调研文档验收清单](research/harmony-connector.md#验收与尚未证明的部分)补充完整机型/系统版本、空文件/中文/二进制/大文件往返 SHA-256、图库导出、取消、拔线、重新连接及退出的结果。
|
||||
|
||||
调研依据与备选 HDC 方案见[技术调研](research/harmony-connector.md)。依赖构建与替换说明见[第三方声明](../curios/harmony-connector/legal/THIRD-PARTY.md)。
|
||||
Reference in New Issue
Block a user