feat(harmony): add screen viewing and control with USB reconnection recovery
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
# Harmony Connector
|
||||
|
||||
插件 ID：`dev.trove.harmony-connector`。当前版本：`0.2.0`。
|
||||
插件 ID：`dev.trove.harmony-connector`。当前版本：`0.3.0`。
|
||||
|
||||
macOS 上的鸿蒙设备连接工具。通过 USB 收发文件与完整文件夹；使用官方 HDC 管理应用、保存截图、导出日志和调试应用数据。功能按连接工具、设备实际能力和授权开放，不按 HarmonyOS 大版本或机型名称限制。
|
||||
|
||||
@@ -57,17 +57,27 @@ macOS 上的鸿蒙设备连接工具。通过 USB 收发文件与完整文件夹
|
||||
|
||||
管理操作使用独立串行任务，支持取消与超时；取消不回滚设备端已经完成的更改。操作开始前重新确认所选设备在线。功能有命令支持仍可能被单个应用、对象或系统权限拒绝，失败会显示设备返回的原因。
|
||||
|
||||
## 投屏和控制调研
|
||||
## 投屏与控制
|
||||
|
||||
**本版本尚未实现实时投屏或键鼠控制。** 官方 scrcpy 的设备端依赖 Android、ADB、`app_process` 和 Android 屏幕/输入 API，不能直接连接原生鸿蒙。仅能运行 APK 并不足以证明 scrcpy 兼容。[scrcpy 官方说明](https://github.com/Genymobile/scrcpy)
|
||||
在「设备与应用」选择已授权的 HDC 目标，点击「开始投屏」。默认仅观看；画面出现后勾选「启用鼠标与键盘控制」。功能依设备的 `uitest` 帮助和实际操作结果开放。
|
||||
|
||||
最新 DevEco Studio 与 DevEco Testing 已提供官方 Mac 投屏功能；目前未找到可嵌入本插件的公开投屏协议。可行的插件路线是先以 HDC + UITest 实现截图预览和明确的点击/滑动输入，再单独验证用户授权的鸿蒙采集端、视频编码和传输。连续视频方案需要设备端适配，不能把截图轮询宣传成 scrcpy 视频流。详见[投屏与键鼠控制调研](research/harmony-screen-control.md)。
|
||||
- 连续显示手机画面，显示真实分辨率、实测刷新帧率和采集耗时。可放大面板，将当前画面保存为 JPEG。
|
||||
- 点击、双击、长按、滑动、拖拽与滚轮滚动；坐标按实际手机尺寸映射，忽略画面周围留白。
|
||||
- 返回、主页、音量、方向键、回车、退格等按键。快捷键只在手机画面获得焦点时生效。
|
||||
- 用专用文字框发送文本，支持输入法；不读取系统剪贴板。文字能否进入目标输入框，以手机焦点和输入权限为准。
|
||||
- 一个屏幕会话只保留一项待发送操作。停止、切换工作区、页面隐藏、断线时清空队列和旧画面，不在重连后重放输入。横竖屏变化后需重新启用控制。
|
||||
|
||||
当前实现通过 HDC + UITest 连续采集截图，完成一帧再开始下一帧；不是 H.264/H.265 视频流，不承诺 scrcpy 的 30/60 FPS、音频或低延迟多点触控。拖动在松开时发送完整手势。采集临时文件使用每次唯一名称并清理；远端清理被断线阻断时，不扫描删除其他文件。
|
||||
|
||||
图像解码限制内存与尺寸，传给 UI 的 JPEG 最长边不超过 1600 像素；坐标仍按手机原始尺寸计算。画面过旧、方向变化、会话过期或输入失败时会阻止控制。受保护画面和锁屏遵循系统限制，不自动解锁。自动化测试和真机结果分别记录，详见[投屏能力调研](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 设备，故重连仍待真机复现和修复。
|
||||
0.3.0 真机复现了 CloseSession 等待 60 秒的问题。固定 libmtp 依赖增加一个小补丁，仅把 CloseSession 的超时设为 2 秒，文件传输超时、接口释放、现有 USB reset 与关闭顺序保持不变。macOS 重枚举有短暂离线窗口，诊断程序最多等 10 秒重新发现设备，再实际打开并读取存储和目录。
|
||||
|
||||
2026-09-10，在同一 USB 插接周期，开发构建与发布构建各完成 3 轮只读重连，每轮返回 1 个存储和 9 个根目录条目。开发构建关闭约 2.28–2.33 秒；发布构建约 2.13–7.28 秒，包含 USB 重枚举耗时。设备仍不正常响应 CloseSession，恢复由随后的 USB 清理/reset 完成；不能将 2 秒超时宣传为所有设备都固定 2 秒完成断开。该结果覆盖这台手机，不代表全部固件。见[会话恢复调研](research/harmony-mtp-session.md)。
|
||||
|
||||
关闭插件窗口，保留一台解锁且处于「传输文件」模式的手机，然后执行：
|
||||
|
||||
@@ -79,7 +89,19 @@ curios/harmony-connector/backend/harmony-connector --diagnose
|
||||
curios/harmony-connector/backend/harmony-connector --check-reconnect
|
||||
```
|
||||
|
||||
`--check-reconnect` 逐阶段输出 JSON、耗时和实际目录读取结果，不修改手机文件。没有恰好一台设备或任何一轮失败时以非零状态结束；原生 CloseSession 仍可能等待 USB 超时。不能仅凭扫描发现设备、按钮可用或 reset 返回成功判定验收通过。
|
||||
`--check-reconnect` 逐阶段输出 JSON、耗时和实际目录读取结果，不修改手机文件。没有恰好一台设备或任何一轮失败时以非零状态结束；CloseSession 时限为 2 秒，USB 清理和重枚举仍可能增加耗时。不能仅凭扫描发现设备、按钮可用或 reset 返回成功判定验收通过。
|
||||
|
||||
只读验证投屏（先完成手机 USB 调试授权）：
|
||||
|
||||
```sh
|
||||
curios/harmony-connector/backend/harmony-connector --check-screen /absolute/path/to/hdc
|
||||
# 多台设备时可指定目标；最后的可选目录用于保存最终画面
|
||||
curios/harmony-connector/backend/harmony-connector --check-screen /absolute/path/to/hdc DEVICE_ID /absolute/save/directory
|
||||
```
|
||||
|
||||
该命令走 UI 相同的后端接口，采集并解码 3 帧，输出耗时，最后关闭会话；不启用控制、不发送输入。首次 HDC 连接显示 Unauthorized 时，在手机上允许 USB 调试。`hdc -v` 能运行但管理失败时，先用 `hdc list targets -v` 检查授权状态。
|
||||
|
||||
本次自动化验证通过 39 项原生测试、27 项 UI/格式/坐标测试、3 项 USB C 桥接检查及 3 项底座协议检查。浏览器另外验证了持续显示模拟画面、启用控制、中文输入、放大和停止清空；模拟数据不会包含在发布包内。官方 Command Line Tools 26.0.0.821（Mac ARM）的 HDC 返回 `Ver: 3.2.0f`，已识别真机，但当次状态为 Unauthorized，故投屏和输入的真机效果尚未验收，不能将上述替身测试当作真机通过。
|
||||
|
||||
## 构建与发布
|
||||
|
||||
@@ -95,7 +117,7 @@ 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 的文件与管理工作区分开实现。
|
||||
代码职责：`native/src/file_transfer.rs` 管理目录计划与落盘，`progress.rs` 统计进度，`connector.rs` 管理 MTP 会话与任务，`mtp.rs` / `mtp_bridge.c` 封装固定依赖，`hdc.rs` / `hdc_data.rs` / `hdc/files.rs` 管理官方工具与输出校验，`hdc/screen.rs` / `screen_input.rs` 管理屏幕会话与输入，`command.rs` 控制进程、输出、取消和时限。UI 的文件与管理工作区分开实现。
|
||||
|
||||
验证包括文件夹往返与失败清理、会话状态、工具命令和解析、安装确认及后置条件、页面交互、USB 桥接和底座协议。HDC 测试使用明确的工具替身，不代表商业手机已经完成安装、备份或截图验收。实际文件吞吐量和 USB 往返 SHA-256 仍需真机记录。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user