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 包。

解锁手机，用支持数据传输的 USB 线连接 Mac。
在手机 USB 选项中选择「传输文件」，允许访问。
扫描、选择设备并连接，打开目标文件夹。
点击「发送文件」从 Mac 选择一个文件；点击文件旁的「接收」选择 Mac 接收文件夹。

本插件只访问手机通过 MTP 开放的存储。目录来自设备对象 ID，不映射为 Android 路径。HarmonyOS 6 在文件传输模式下允许导出图库内容，导入图库需要图片传输模式；本版未实现 PTP 图库导入。华为 HarmonyOS 6 官方说明

没有发现设备时，检查数据线和 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。

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 软件源：

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

界面测试使用独立的显式模拟设备，预览脚本和数据不进入安装包：

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 往返或吞吐量。连接实际手机后，按调研文档验收清单补充完整机型/系统版本、空文件/中文/二进制/大文件往返 SHA-256、图库导出、取消、拔线、重新连接及退出的结果。

5.8 KiB Raw Blame History Unescape Escape