# 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)。