Files
curios/docs/research/harmony-screen-control.md
T

135 lines
21 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Harmony Connector 投屏与键鼠控制调研
调研日期:2026-09-10。范围是 macOS 上的 Harmony Connector,目标包括原生 HarmonyOS 和 OpenHarmony,按最新公开资料评估,不以某个系统大版本作硬上限。承接 [设备管理调研](harmony-device-management.md)。本轮仅阅读官方文档及项目源码,未安装工具、执行手机命令或改变设备状态;以下命令是实现契约/待验证方案,不是真机验收记录。
## 结论
**官方 scrcpy 不能直接作为原生鸿蒙投屏后端。** 它的设备端是 Android framework 上的 Java/Dex 程序,经 ADB 启动;把可执行文件名从 adb 换成 hdc,不能替代 Android 运行时、屏幕采集和输入 API。官方 scrcpy 当前 README 为 v4.1,设备要求 Android API 21+,macOS 是支持的电脑平台。只有设备确实提供兼容 Android 的运行时、ADB shell 及相应屏幕/输入能力时,才适合另外启用 scrcpy 通道;手机品牌、能运行某些 APK 或存在兼容容器都不是充分条件。[scrcpy 官方项目](https://github.com/Genymobile/scrcpy)、[服务端架构](https://github.com/Genymobile/scrcpy/blob/master/doc/develop.md)
本项目可按以下顺序推进,优先级是工程建议:
| 路线 | 画面与输入 | 本项目建议 |
| --- | --- | --- |
| HDC + UITest CLI | 单次截图;可轮询预览。点击、长按、滑动、指定文本、常用键。 | P0:复用现有 HDC 后端;显示“屏幕预览与操作”,不承诺视频级流畅度。 |
| 官方 DevEco Studio / DevEco Testing | 官方已提供设备投屏、点击/滑动/字符输入等。 | P0:提供官方工具入口及指引;未查到可嵌入第三方插件的公开投屏协议。 |
| 官方系统录屏 CLI | 录制后导出 MP4。 | P1:作为“录屏导出”独立功能,不把 MP4 文件导出当实时镜像流。 |
| 自建正常签名的鸿蒙伴随应用 + AVScreenCapture + HDC 转发 | 经手机用户同意采集,编码后持续传输;输入可另走 UITest。 | P2:真实视频流的优先独立原型,必须验证商业设备授权、后台持续采集和编码器。 |
| OpenHarmony UITest addon | 自建 native 扩展,JPEG 帧回调及原子输入 API。 | P2:开源实现可研究,商业固件可加载性/ABI 未验证。 |
| 鸿镜 / OpenHarmony_Scrcpy | 已有连续编码视频及控制实现。 | 面向可配置 OpenHarmony 系统的参考,当前系统权限/root 要求不适合作为普通华为手机的默认方案。 |
| 官方 scrcpy | Android 视频流及键鼠控制。 | 仅为已验证 Android/ADB 设备提供独立可选入口。 |
## scrcpy 依赖与直接集成边界
scrcpy 客户端推送 server 到设备并启动,视频、音频、控制使用分离 socket。server 使用 Android `app_process` 加载 Dex,屏幕关联 Surface 经 `MediaCodec` 编码,输入通过 Android `InputManager.injectInputEvent()` 等方法处理;其中包含通过反射调用的隐藏 API。客户端解码使用 FFmpeg、窗口输入使用 SDL。项目明确客户端和 server 必须版本一致,其内部协议不保证跨版本兼容。[官方开发说明](https://github.com/Genymobile/scrcpy/blob/master/doc/develop.md)
因此 `hdc fport` 只能替代传输中的一小部分,不能运行 Android server;要复用 scrcpy UI/解码需要替换连接、启动器、设备端采集/编码/输入,并协调协议,属于移植工程。不能声称下载官方 scrcpy 后便支持原生 HarmonyOS。对具有 Android 兼容能力的设备,按实际授权 ADB 目标识别,运行受控的原生 scrcpy 会话验收;不要根据 HarmonyOS 名称硬编码“可用/不可用”。[scrcpy 连接方式](https://github.com/Genymobile/scrcpy/blob/master/doc/connection.md)、[服务端约束](https://github.com/Genymobile/scrcpy/blob/master/doc/develop.md)
若用户已经安装官方 scrcpy 和 adb,候选 Android 通道的只读预检可使用 `scrcpy --version`、`adb devices -l`、`adb -s <serial> shell getprop ro.build.version.sdk`。实际会话由用户点击后执行以下 argv;macOS 上优先启动独立窗口,减少嵌入原生渲染的成本。此处参数组合是本项目建议,不是鸿蒙兼容证明。[官方连接参数](https://github.com/Genymobile/scrcpy/blob/master/doc/connection.md)、[视频参数](https://github.com/Genymobile/scrcpy/blob/master/doc/video.md)、[控制参数](https://github.com/Genymobile/scrcpy/blob/master/doc/control.md)
```text
scrcpy argv: ["--serial", serial, "--no-audio", "--max-size=1280", "--max-fps=30"]
仅观看时再添加: ["--no-control"]
```
scrcpy 的 `--otg` 通过 Android Open Accessory 模拟 USB HID,不依赖 ADB,但它**没有投屏**。不能将 OTG 模式宣传成绕开鸿蒙设备端视频支持的办法,也不能未验证便承诺手机实现相应 USB accessory 协议。[官方 OTG 文档](https://github.com/Genymobile/scrcpy/blob/master/doc/otg.md)
macOS 官方文档提供预编译包和包管理方式。集成可优先使用用户已安装工具;本轮没有下载运行任何发布二进制。scrcpy 为 Apache-2.0,重新分发还需审核所选构建中的第三方依赖及其声明;这不授予 Huawei SDK 的重打包许可。[macOS 获取方式](https://github.com/Genymobile/scrcpy/blob/master/doc/macos.md)、[scrcpy LICENSE](https://github.com/Genymobile/scrcpy/blob/master/LICENSE)
## 可立即实现:HDC 屏幕预览和操作
HDC 需设备开启开发者调试并信任电脑。以下固定使用用户选择的 `key`;宿主用 argv 调用,不执行本机 `sh -c`。设备端 shell 参数仍需严格转义,坐标和速度仅接受有界数字。[华为 HDC](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/hdc)
| 操作 | HDC argv(省略 hdc 本身) |
| --- | --- |
| 版本 | `["-t", key, "shell", "uitest --version"]` |
| 工具帮助 | `["-t", key, "shell", "uitest help"]` |
| 输入帮助 | `["-t", key, "shell", "uitest uiInput help"]` |
| 截图 | `["-t", key, "shell", "uitest screenCap -p /data/local/tmp/curios-screen-<nonce>.png"]` |
| 下载截图 | `["-t", key, "file", "recv", remoteTemp, localTemp]` |
| 点击 | `["-t", key, "shell", "uitest uiInput click 160 240"]` |
| 长按 | `["-t", key, "shell", "uitest uiInput longClick 160 240"]` |
| 滑动 | `["-t", key, "shell", "uitest uiInput swipe 160 720 160 320 600"]` |
| 拖拽 | `["-t", key, "shell", "uitest uiInput drag 160 240 480 640 600"]` |
| 当前焦点文本 | `["-t", key, "shell", "uitest uiInput text <escaped-text>"]` |
| 指定输入框文本 | `["-t", key, "shell", "uitest uiInput inputText 160 240 <escaped-text>"]` |
| 返回/主页 | `["-t", key, "shell", "uitest uiInput keyEvent Back"]` / `Home` |
精确 CLI 来源是 [OpenHarmony UITest 指引](https://github.com/openharmony/docs/blob/f41b9345badd47c7ab0c263344cd7f4b5a549afb/zh-cn/application-dev/application-test/uitest-guidelines.md)。截图 `-p` 只支持 `/data/local/tmp/`;`-d <displayId>` 从 API 20 起。`swipe`/`drag` 最后参数是速度 px/s,范围 200–40000,**不是毫秒时长**。`text` 从 API 18 起,只有当前焦点支持输入时才有实际效果。键码取 OpenHarmony `KeyCode`,不能照搬 Android keycode 或 macOS keycode;特殊 `Back/Home/Power` 不支持组合键。[UITest 操作定义](https://github.com/openharmony/testfwk_arkxtest/blob/b04e30c40cf266c9abfbd52933e43a0456eb99a2/README_zh.md)、[OpenHarmony KeyCode](https://github.com/openharmony/docs/blob/f41b9345badd47c7ab0c263344cd7f4b5a549afb/zh-cn/application-dev/reference/apis-input-kit/js-apis-keycode.md)
工程实现建议:
- 查看预览和启用控制分开;进入页面不自动注入按键。开始预览后串行截图、下载、解码,完成一帧再请求下一帧,避免积压。可先设置约 1 秒的刷新目标,实际显示采集时间,不宣传固定 FPS。
- 按当前 PNG 真实尺寸和画面显示区域计算坐标,排除留白;旋转/折叠后刷新尺寸,暂停旧坐标输入。鼠标拖动收集起终点后发送一次 swipe/drag,不能伪装成实时多点触控。
- 每个目标限制一个屏幕会话,输入队列有上限;用户停止、窗口隐藏、设备断开或授权失效时立即停止排队,避免恢复连接后补发旧输入。文本使用单独输入框和发送按钮,不全局捕获电脑键盘。
- 对中文、空格、引号、emoji、新行和输入法组合做真实验证。不要为此同步读取剪贴板或关闭密码键盘。输出可解析/退出码正常只能表示命令执行结果,截图刷新或实际界面变化才是操作效果证据。
- 保存截图使用临时文件并校验 PNG;默认帧只在本机短暂缓存。清理只删除本会话生成的远端/本地文件,不碰用户相册。锁屏和受保护画面保持系统行为,不自动解锁或关闭隐私保护。
`uiRecord record` 是操作记录,不是视频录屏;其记录可写到 CSV,并不产生 H.264 视频。不要把它接成“录制投屏”。[UITest uiRecord](https://github.com/openharmony/docs/blob/f41b9345badd47c7ab0c263344cd7f4b5a549afb/zh-cn/application-dev/application-test/uitest-guidelines.md)
## 官方工具:确有投屏,但没有可确认的第三方嵌入协议
DevEco Studio 官网当前明确支持连接设备投屏、点击、滑动、字符输入及拖拽包/文件;26.0.0 Release 的官方说明将设备投屏列为新增能力。产品提供 macOS Intel/ARM 版本。它是真实设备投屏能力,不能与“鼠标控制模拟器”的教程混用。[DevEco Studio 官网](https://developer.huawei.com/consumer/cn/deveco-studio)、[26.0.0 官方版本概览](https://developer.huawei.com/consumer/cn/doc/doccenter-release-notes/overview-2600)、[仅针对模拟器的操控屏幕文档](https://developer.huawei.com/consumer/cn/doc/HarmonyOS-Guides/ide-emulator-control-screen)
DevEco Testing 官方 FAQ 确认 Windows/Mac 客户端、设备投屏等测试工具;要求 HarmonyOS NEXT 设备开启开发者模式和 USB 调试,并能被 HDC 识别。官方工具介绍明确其投屏支持在 PC 上操作设备。最新 26.0.0 兼容表仍将“设备投屏”的模拟器列标为不支持;不要把云手机特定接入指引外推到所有本地模拟器。[DevEco Testing FAQ](https://devecotesting.huawei.com/userPortal/help?jobType=100000102)、[官方工具介绍](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V14/devecotesting-V14)、[最新兼容表](https://developer.huawei.com/consumer/cn/doc/doccenter-release-notes/deveco-testing-releasenotes-2600)
本轮没有从这些第一方资料确认可供第三方插件使用的投屏 SDK、稳定 socket 协议、可重新分发的 device agent 或指定设备投屏 deep link。因此可以引导用户打开已安装的官方应用并选择设备;不能提取其私有 agent 并当作插件依赖。`Device Manager` 只是工具内管理入口的名称,不能据二手教程编造其稳定 CLI。本轮未检视商业工具安装包,不判断其内部实现。
## 官方录屏 CLI:结束后导出视频
华为官方录屏文档要求设备解锁;录制中锁屏会退出,文档不支持模拟器录屏。其命令流程是启动系统录屏组件、停止、定位媒体、必要时复制到可下载目录、下载文件,未给出实时 stdout 视频流协议。[华为录屏文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-screen-recording)
```text
开始:
["-t", key, "shell", "aa start -b com.huawei.hmos.screenrecorder -a com.huawei.hmos.screenrecorder.ServiceExtAbility --ps CustomizedFileName curios-record-<nonce>.mp4"]
停止(官方写法仍为 aa start,同组件但不传文件名):
["-t", key, "shell", "aa start -b com.huawei.hmos.screenrecorder -a com.huawei.hmos.screenrecorder.ServiceExtAbility"]
定位录制结果:
["-t", key, "shell", "mediatool query curios-record-<nonce>.mp4 -u"]
查询含 uri 时,用查询返回且已验证的 URI 导出:
["-t", key, "shell", "mediatool recv <escaped-returned-uri> /data/local/tmp"]
下载工具实际返回的路径:
["-t", key, "file", "recv", returnedRecordFile, localTemp]
```
官方说明有 URI 时不能直接下载查询结果里的原始媒体路径;需 `mediatool recv` 得到可下载路径。实现不要只盲取“第几行”,应验证 URI、返回路径和唯一文件名。开始/停止是设备写操作,不能作为能力探测;录屏组件的停止写法也不能无限重试。用会话状态管理、手机通知和最终可解码文件验收,未知状态引导在手机停止。本功能会生成设备媒体文件,默认不能顺手删除相册原件。[华为录屏文件导出流程](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-screen-recording)
## 真正视频流:自建伴随应用路线
AVScreenCapture 支持将采集结果作为码流交给其他模块,以实现桌面共享。最新 OpenHarmony 指引区分文件输出和码流输出,并说明码流录制开始会出现隐私选择弹窗;受保护内容可被屏蔽。华为最新窗口级录屏文档亦明确 Phone/Tablet 的 Picker 能力和权限条件。因此“普通应用一概不能录屏”不正确;需要区别用户授权录屏与系统免授权采集/输入注入。[OpenHarmony 录屏基础流程](https://github.com/openharmony/docs/blob/f41b9345badd47c7ab0c263344cd7f4b5a549afb/zh-cn/application-dev/media/media/avscreencapture-c-basic-process.md)、[华为窗口级录屏与授权](https://developer.huawei.com/consumer/cn/doc/doccenter-capabilities/using-avscreencapture-for-file-with-window)
建议独立原型链路为:用户启动已签名 HAP并在手机允许共享 → `OH_AVScreenCapture_Create/Init` → 绑定编码器输入 Surface 后 `OH_AVScreenCapture_StartScreenCaptureWithSurface` → `OH_VideoEncoder` 输出 H.264 → 应用内 loopback TCP → HDC fport → macOS VideoToolbox/受控播放器。采集、编码和传输分别处理错误与背压;音频初版关闭。停止使用 `OH_AVScreenCapture_StopScreenCapture/Release`,并关闭编码器和本会话转发。详细 API 配置从配套 SDK 的官方示例实现,不复制系统免授权权限。[官方采集到编码器 Surface 示例](https://github.com/openharmony/docs/blob/f41b9345badd47c7ab0c263344cd7f4b5a549afb/zh-cn/application-dev/media/media/avscreencapture-c-custom-scenarios.md)
传输示例为 `["-t", key, "fport", "tcp:<hostPort>", "tcp:<companionPort>"]`,停止后仅移除本次建立的转发 `["-t", key, "fport", "rm", "tcp:<hostPort>", "tcp:<companionPort>"]`;两个端口是自建协议配置,HDC 本身不会生成视频。使用 loopback、每会话随机 token、长度上限和协议版本;需要网络直连时另行设计用户配对与认证,不默认监听 `0.0.0.0`。手机端普通 HAP 不由录屏授权获得任意输入注入权限;键鼠仍可通过已授权 HDC 的 UITest 命令完成。此路线需新建手机工程、签名与真机验证,当前插件未具备。[华为 HDC 端口转发](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/hdc)
## OpenHarmony UITest addon:可研究的 native 扩展
检查官方 `testfwk_arkxtest` 提交 `b04e30c40cf266c9abfbd52933e43a0456eb99a2`:`uitest/addon/extension_c_api.h` 定义 `UiTestExtension_OnInit`、`UiTestExtension_OnRun`,通过 `UiTestPort.initLowLevelFunctions` 获取 `startCapture/stopCapture`、`atomicTouch`、`atomicMouseAction` 等函数。`startCapture` 名称 `copyScreen` 接收 JSON 选项 `scale`(严格 0 到 1 之间)、`displayId`;回调提供 JPEG 字节,当前开源实现反复 `GetScreenshot` 并编码变化帧,不是 H.264 编码流。[扩展 C ABI](https://github.com/openharmony/testfwk_arkxtest/blob/b04e30c40cf266c9abfbd52933e43a0456eb99a2/uitest/addon/extension_c_api.h)、[调用实现](https://github.com/openharmony/testfwk_arkxtest/blob/b04e30c40cf266c9abfbd52933e43a0456eb99a2/uitest/addon/extension_executor.cpp)、[JPEG 采集实现](https://github.com/openharmony/testfwk_arkxtest/blob/b04e30c40cf266c9abfbd52933e43a0456eb99a2/uitest/addon/screen_copy.cpp)
源码可导出的启动契约是 `uitest start-daemon singleness --extension-name curios-screen-<nonce>.so`,加载 `/data/local/tmp/` 下相应文件,默认名 `agent.so`。扩展须自行实现有界传输、停止以及主机认证。**这是源码入口,不是本次确认的商业公共 CLI。** 官方仓库 README 将 start-daemon 标为测试端注入用途;商业固件可能改变加载策略、系统库、ABI 或采集实现。先在自己可控制的 OpenHarmony 测试镜像验证,再专门评估真实商业设备,不应默认为任何手机加载 native 代码。[加载器](https://github.com/openharmony/testfwk_arkxtest/blob/b04e30c40cf266c9abfbd52933e43a0456eb99a2/uitest/addon/extension_executor.cpp#L354)、[命令分派](https://github.com/openharmony/testfwk_arkxtest/blob/b04e30c40cf266c9abfbd52933e43a0456eb99a2/uitest/server/server_main.cpp#L471)、[官方 README](https://github.com/openharmony/testfwk_arkxtest/blob/b04e30c40cf266c9abfbd52933e43a0456eb99a2/README_zh.md)
不能从论坛提到的 `xdevice_scrcpy` 或 `DevEcoScrcpy` 日志推断商业工具私有协议已公开,也不能把上面的开源 JPEG 路径描述成与商业 H.264 路径完全相同。
## 已核查的开源成品
| 项目与锁定提交 | 真实机制、macOS、授权边界 | 结论 |
| --- | --- | --- |
| [鸿镜 ohos-scrcpy-app](https://github.com/guoxiucai/ohos-scrcpy-app/tree/1d470ea8f571f19fcbb6883cc6118fafed6fe14f) | Flutter macOS/Windows;H.264、VideoToolbox、鼠标/触摸/按键、录制,编码失败可降级 JPEG。设备端为系统 HAP,作者明确要求 Full SDK、目标系统信任签名和权限白名单。 | 可参考本机解码与协议设计;不能普通签名安装到商业手机便承诺工作。 |
| [OpenHarmony_Scrcpy](https://github.com/luodh0157/OpenHarmony_Scrcpy/tree/85890e693fb5b3e4b3ef50a16af688787ca85070) | 项目声明跨桌面平台,设备端明确要求 OpenHarmony 5+ root 版本;原生 AVScreenCapture + H.264/H.265。安装脚本 remount 并写 `/system/bin` 和 `/system/etc/init`,服务具媒体采集权限。 | 只适合受控开发镜像;不用于本项目普通手机自动安装。 |
| [scrcpy-ohos](https://github.com/l376571926/scrcpy-ohos/tree/5d938ac1d125406705c764d7061192d91c33b9d1) | JavaFX/JDK11;源码 `snapshot_display` 截图下载,操作后刷新,uinput 模拟事件;README 明确非实时。未找到根 LICENSE。 | 不是官方 scrcpy 的鸿蒙兼容层,也不提供连续视频流;可看思路,不能据公开代码便假定可复制分发。 |
鸿镜设备权限包括 `CAPTURE_SCREEN`、`EXEMPT_CAPTURE_SCREEN_AUTHORIZE`、`INJECT_INPUT_EVENT`,其文档明确需 ACL、系统签名和指纹白名单。仅将 HAP 换成自己的普通调试证书不解决这些限制。[鸿镜签名要求](https://github.com/guoxiucai/ohos-scrcpy-app/blob/1d470ea8f571f19fcbb6883cc6118fafed6fe14f/README.md#签名与系统权限)、[设备权限声明](https://github.com/guoxiucai/ohos-scrcpy-app/blob/1d470ea8f571f19fcbb6883cc6118fafed6fe14f/scrcpy_server/entry/src/main/module.json5)
鸿镜可复核的传输为 `hdc fport tcp:<localPort> tcp:53535`,设备只监听 `127.0.0.1:53535`。它使用自定义包:大端 u32 类型 + 大端 u32 payload 长度;`0x02` 配置、`0x03` 视频帧、`0x10` 控制。H.264 帧 payload 是 flags u8、PTS u64、NAL 数据;控制下含触摸/键鼠子类型。它与官方 scrcpy wire protocol 不兼容,不能拿其 server 对接官方 scrcpy client。[鸿镜协议](https://github.com/guoxiucai/ohos-scrcpy-app/blob/1d470ea8f571f19fcbb6883cc6118fafed6fe14f/scrcpy_client_flutter/lib/net/protocol.dart)、[loopback 监听](https://github.com/guoxiucai/ohos-scrcpy-app/blob/1d470ea8f571f19fcbb6883cc6118fafed6fe14f/scrcpy_server/entry/src/main/cpp/TcpServer.cpp)
许可分别是鸿镜 MIT、OpenHarmony_Scrcpy Apache-2.0;仍需保留声明、审查依赖和自行构建的分发物。root 项目的安装脚本会遍历目标设备并更改系统分区,本项目不能直接调用它。[鸿镜 LICENSE](https://github.com/guoxiucai/ohos-scrcpy-app/blob/1d470ea8f571f19fcbb6883cc6118fafed6fe14f/LICENSE)、[OpenHarmony_Scrcpy LICENSE](https://github.com/luodh0157/OpenHarmony_Scrcpy/blob/85890e693fb5b3e4b3ef50a16af688787ca85070/LICENSE)、[root 服务要求](https://github.com/luodh0157/OpenHarmony_Scrcpy/blob/85890e693fb5b3e4b3ef50a16af688787ca85070/Server/README.md)、[系统分区安装脚本](https://github.com/luodh0157/OpenHarmony_Scrcpy/blob/85890e693fb5b3e4b3ef50a16af688787ca85070/Server/install_ohscrcpy_server.sh)
## 验收与后续决策
先交付可探测的屏幕预览和明确输入,再进行视频流原型。每条能力分别保存 available/unavailable/unknown 及原因;不把 HDC 已连接等同全部投屏/输入可用。最小真机验收需要覆盖截图解码、旋转坐标、点击/滑动效果、中文输入、断线取消、锁屏、拒绝授权、受保护画面、停止采集后不再传帧和本会话文件/转发清理。视频流另外测首帧时延、实际 FPS、CPU/温度、背压、编码器重建与应用后台状态;完成这些前不使用“低延迟 60 FPS”等宣传。
本轮明确未验证:Pura 70 Ultra 当前固件的 UITest 输入效果、HDC 版本、官方工具真机投屏、伴随应用采集权限、UITest addon 加载、任何社区 HAP/二进制。已确认的是公开能力与实现边界;没有执行设备动作,也没有修改插件代码。