fix(harmony): recover owned screen sessions and release 0.4.0

2026-09-10 16:43:25 +08:00
parent 3ce918564d
commit 0a1cefc9fa
19 changed files with 570 additions and 104 deletions
@@ -1,6 +1,6 @@
 # Harmony Connector

-插件 ID：`dev.trove.harmony-connector`。当前版本：`0.3.2`。
+插件 ID：`dev.trove.harmony-connector`。当前版本：`0.4.0`。

 macOS 上的鸿蒙设备连接工具。通过 USB 收发文件与完整文件夹；使用官方 HDC 管理应用、保存截图、导出日志和调试应用数据。功能按连接工具、设备实际能力和授权开放，不按 HarmonyOS 大版本或机型名称限制。

@@ -73,7 +73,7 @@ macOS 上的鸿蒙设备连接工具。通过 USB 收发文件与完整文件夹
 - 用专用文字框发送文本，支持输入法；不读取系统剪贴板。文字能否进入目标输入框，以手机焦点和输入权限为准。
 - 一个屏幕会话只保留一项待发送操作。停止、切换工作区、页面隐藏、断线时清空队列和旧画面，不在重连后重放输入。横竖屏变化后需重新启用控制。

-当前源代码通过 HDC 部署官方 Hypium 代理，持续接收 JPEG 画面，并通过独立连接发送输入。用户无需开发者账号、编译、签名或安装手机应用。拖动在松开时发送完整手势。停止会删除本会话的代理和转发；其他调试工具占用设备时会提示。已发布 0.3.2 仍为逐帧截图，新路径的动态真机验收状态见[开发验证](harmony-realtime-development.md)。
+0.4.0 通过 HDC 部署官方 Hypium 代理，持续接收 JPEG 画面，并通过独立连接发送输入。用户无需开发者账号、编译、签名或安装手机应用。拖动在松开时发送完整手势。停止会删除本会话的代理和转发，再次启动会恢复插件自身的残留会话；其他调试工具占用设备时会提示。真机已通过三轮连续启动、收图、停止及重连；动态性能验收状态见[开发验证](harmony-realtime-development.md)。

 JPEG 采用半尺寸采集，坐标按手机原始尺寸计算。画面不变化时保留显示，通过独立控制连接检查存活；方向变化、会话过期或输入失败时会阻止控制。受保护画面和锁屏遵循系统限制，不自动解锁。自动化测试和真机结果分别记录，详见[HDC 持续投屏调研](research/harmony-hdc-only-screen.md)。

@@ -113,6 +113,8 @@ curios/harmony-connector/backend/harmony-connector --check-screen /absolute/path

 0.3.2 补上工具安装目录和 Downloads 的自动发现。回归在独立 HOME、空 PATH 工具目录、未保存任何设置的进程中运行真实 `Manager::new → hdc.tool`，验证数字版本选择、未完成解压跳过、手动路径优先和官方解压目录布局。实际 Mac 验证通过 Wire 请求 `hdc.tool`，使用空插件数据目录和系统 PATH，未调用 `configure`；0.3.1 返回 `available: false`，0.3.2 自动找到之前解压的工具并返回 `Ver: 3.2.0f`。USB 目标仍为 Unauthorized。该版 42 项原生测试、30 项 UI/格式/坐标测试及 6 项 USB/协议检查全部通过。

+0.4.0 的 HDC 持续采集与会话恢复通过 54 项原生、33 项 UI/格式/坐标、6 项 USB/协议检查（共 93 项）。真机连续三轮开始、接收并解码 JPEG、停止和重新开始全部成功，每轮均确认代理和转发清理，无需拔线。新增回归覆盖自身孤儿进程恢复、结束失败不误报其他工具、多个窗口的同设备锁、仅恢复自身转发以及 JPEG 对齐填充的显示/输入坐标。浏览器确认填充裁切与放大布局。该轮没有发送真机输入或测量动态性能，详见[开发验证](harmony-realtime-development.md)。
+
 ## 构建与发布

 要求 macOS、Xcode Command Line Tools、Rust/Cargo、Node.js、pnpm、make、pkg-config。固定源码归档与哈希位于 `vendor/harmony-connector/`。
@@ -4,11 +4,17 @@

 ## 当前状态

-2026-09-10：已发布的 0.3.2 仍使用逐张截图，真机原链路为 696、803、802 ms，约 1.3 fps。当前源代码已替换该路径，尚未发布新版本。
+2026-09-10：0.4.0 改为 HDC 持续 JPEG 推送，修复投屏残留会话误报占用及重连失败。0.3.2 的逐张截图链路为 696、803、802 ms，约 1.3 fps；新版本的动态帧率仍须独立测量。

 官方 `xdevice-devicetest` 6.1.0.210 的 `uitest_agent_v1.2.2.so` 已在 HUAWEI Pura 70 Ultra 的商业系统上成功加载。独立探针收到真实 JPEG、屏幕尺寸 1260 × 2844，并成功调用尺寸、旋转和唤醒接口。设备端文件为 600245 字节，未改动签名原件。没有安装 HAP，也没有账号或系统共享确认步骤。

-探测期间手机主要处于锁屏或静止状态。黑色首帧、短暂变化及收包时间不能证明动态帧率或端到端延迟达标。接入生产后端时手机变为 Offline，后端的完整真机连通、持续动态画面、输入及重连仍待验收。自动化替身测试不替代这项验收。完整自动化检查通过 85 项：47 项原生、32 项 UI/格式/坐标、6 项 USB 桥接与底座协议检查。
+生产后端已在同一台真机上连续通过三轮“开始 → 接收并解码 → 停止 → 再次开始”，全程未拔 USB，每轮均确认 `pidof uitest` 为空、`fport ls` 无残留。每轮收到 2–3 张独立画面，也验证了静止画面返回 unchanged 的行为。独立探针另收到可查看的实际手机内容；这项连通/重连检查没有发送输入，不能作为动态帧率、跟手程度或端到端延迟达标的证据。
+
+本次错误来自插件自身的残留 `trove-screen-*.so` 会话。手机的普通 `kill` 返回 `Permission denied`，旧代码忽略失败并把任意 UITest 进程视作其他工具。官方 xdevice 的清理使用 `kill -9`；当前手机实测接受该命令。修复会检查完整命令行身份，只清理本插件代理并确认进程退出；显式停止时清理失败会返回错误。其他工具的代理和未经本机记录的活动转发保持不动。主机按设备加文件锁，并记录自己的转发供异常退出后恢复。
+
+手机正常画面实测为 640 × 1422，逻辑半尺寸为 630 × 1422，右侧含对齐填充。接收器兼容 16 像素边界的尾部填充，保留逻辑视口和 JPEG 存储尺寸；UI 直接裁去填充，不重新编码 JPEG，输入仍映射到 1260 × 2844。旋转或无法匹配的尺寸仍会关闭控制。
+
+完整自动化检查通过 93 项：54 项原生、33 项 UI/格式/坐标、6 项 USB 桥接与底座协议检查。浏览器另外确认模拟画面的尾部彩色填充被裁去，放大时可见区域保持居中；这些界面测试不等同于真机性能测试。

 之前的 HAP 实验源码和签名流程已移除。本机签名材料不属于插件或发行包。原方案的研究过程保留在[历史记录](research/harmony-realtime-stream.md)，当前方案及来源见[HDC 持续投屏调研](research/harmony-hdc-only-screen.md)。

@@ -35,6 +41,6 @@ curios/harmony-connector/backend/harmony-connector --check-screen-stream /absolu
 - 图像与控制使用两个独立 socket，共用本会话的 HDC 转发。按键和手势通过持久 RPC 发送，文字使用已验证的 `uitest uiInput text`。
 - 代理回包包括 JSON 行与 JPEG；解析 JPEG 段长度，避免把 EXIF 数据中的字节误认作图像结尾。单帧上限 2 MiB，JSON 上限 64 KiB。
 - 静止画面不视为断线；独立控制连接查询尺寸检查存活。UI 停止请求超过 15 秒会结束会话。屏幕几何变化会关闭输入控制。
- 每次部署使用唯一文件名，只结束加载该文件的进程，只删除本次转发和文件。发现其他 UITest 会话时提示占用，不接管或结束其他调试工具。
+- 每次部署使用唯一文件名，以完整命令行重新确认进程身份后结束代理，并验证退出。设备锁与转发记录支持异常退出恢复；其他工具的代理和活动转发会阻止启动。停止时删除自己的临时文件和转发。

 运行 HDC 不需要完整 SDK：本机独立验证了 `hdc` 与同目录 `libusb_shared.dylib` 的版本命令，总计约 6.4 MiB。完整工具包用于开发构建，不应成为普通投屏用户的依赖。本次尚未新增精简 HDC 发行包；插件继续使用已配置或自动发现的官方工具。
@@ -147,3 +147,10 @@ ASCII "_uitestkit_rpc_message_tail_"
 - 未确认 `Captures/Gestures` 跨版本稳定性；应固定已验收的 agent，报告能力与错误，避免无提示降为旧截图模式。

 最终用户流程可以保持“连接 USB → 允许调试 → 开始投屏”。官方 agent 的获取、校验、部署、转发和清理应由插件完成，不能再把开发者账号或 HAP 签名作为该流程的要求。
+
+
+## 2026-09-10：主任务重连验证补充
+
+实际商业手机拒绝普通 `kill <pid>`，返回 `Permission denied`；同一身份的 `kill -9 <pid>` 成功，进程随即消失。此前残留代理能响应 Driver RPC，却无法恢复采集，因此不将无条件复用残留代理作为恢复策略。官方 `xdevice-ohos 6.1.0.210` 的 `ohos/proxy/ui_proxy.py::stop_ui_rpc` 与 `proxy_base.py::_kill_uitest` 均使用 `kill -9`；默认销毁代理对象可不杀进程，显式重连则先停止。插件只借鉴结束自己代理的方式，绝不照搬按名称批量结束所有工具进程的逻辑。[官方连接包](https://pypi.org/project/xdevice-ohos/6.1.0.210/)
+
+生产后端现已连续通过三轮真机开始、解码 JPEG、停止和重新开始，每轮都验证代理和转发清理完成。正常画面 JPEG 宽度实测含尾部对齐填充（640 × 1422 对应逻辑半尺寸 630 × 1422），UI 应裁掉该部分，不能按 JPEG 宽度直接映射物理触点。该结果只证明本轮设备的连通与重连，不代表动态帧率、实时手势或其他固件兼容性全部验收。