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

Harmony Connector 投屏与键鼠控制调研

调研日期：2026-09-10。范围是 macOS 上的 Harmony Connector，目标包括原生 HarmonyOS 和 OpenHarmony，按最新公开资料评估，不以某个系统大版本作硬上限。承接 设备管理调研。本轮仅阅读官方文档及项目源码，未安装工具、执行手机命令或改变设备状态；以下命令是实现契约/待验证方案，不是真机验收记录。

结论

官方 scrcpy 不能直接作为原生鸿蒙投屏后端。 它的设备端是 Android framework 上的 Java/Dex 程序，经 ADB 启动；把可执行文件名从 adb 换成 hdc，不能替代 Android 运行时、屏幕采集和输入 API。官方 scrcpy 当前 README 为 v4.1，设备要求 Android API 21+，macOS 是支持的电脑平台。只有设备确实提供兼容 Android 的运行时、ADB shell 及相应屏幕/输入能力时，才适合另外启用 scrcpy 通道；手机品牌、能运行某些 APK 或存在兼容容器都不是充分条件。scrcpy 官方项目、服务端架构

本项目可按以下顺序推进，优先级是工程建议：

路线	画面与输入	本项目建议
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 必须版本一致，其内部协议不保证跨版本兼容。官方开发说明

因此 hdc fport 只能替代传输中的一小部分，不能运行 Android server；要复用 scrcpy UI/解码需要替换连接、启动器、设备端采集/编码/输入，并协调协议，属于移植工程。不能声称下载官方 scrcpy 后便支持原生 HarmonyOS。对具有 Android 兼容能力的设备，按实际授权 ADB 目标识别，运行受控的原生 scrcpy 会话验收；不要根据 HarmonyOS 名称硬编码“可用/不可用”。scrcpy 连接方式、服务端约束

若用户已经安装官方 scrcpy 和 adb，候选 Android 通道的只读预检可使用 scrcpy --version、adb devices -l、adb -s <serial> shell getprop ro.build.version.sdk。实际会话由用户点击后执行以下 argv；macOS 上优先启动独立窗口，减少嵌入原生渲染的成本。此处参数组合是本项目建议，不是鸿蒙兼容证明。官方连接参数、视频参数、控制参数

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 文档

macOS 官方文档提供预编译包和包管理方式。集成可优先使用用户已安装工具；本轮没有下载运行任何发布二进制。scrcpy 为 Apache-2.0，重新分发还需审核所选构建中的第三方依赖及其声明；这不授予 Huawei SDK 的重打包许可。macOS 获取方式、scrcpy LICENSE

可立即实现：HDC 屏幕预览和操作

HDC 需设备开启开发者调试并信任电脑。以下固定使用用户选择的 key；宿主用 argv 调用，不执行本机 sh -c。设备端 shell 参数仍需严格转义，坐标和速度仅接受有界数字。华为 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 指引。截图 -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 操作定义、OpenHarmony KeyCode

工程实现建议：

• 查看预览和启用控制分开；进入页面不自动注入按键。开始预览后串行截图、下载、解码，完成一帧再请求下一帧，避免积压。可先设置约 1 秒的刷新目标，实际显示采集时间，不宣传固定 FPS。
• 按当前 PNG 真实尺寸和画面显示区域计算坐标，排除留白；旋转/折叠后刷新尺寸，暂停旧坐标输入。鼠标拖动收集起终点后发送一次 swipe/drag，不能伪装成实时多点触控。
• 每个目标限制一个屏幕会话，输入队列有上限；用户停止、窗口隐藏、设备断开或授权失效时立即停止排队，避免恢复连接后补发旧输入。文本使用单独输入框和发送按钮，不全局捕获电脑键盘。
• 对中文、空格、引号、emoji、新行和输入法组合做真实验证。不要为此同步读取剪贴板或关闭密码键盘。输出可解析/退出码正常只能表示命令执行结果，截图刷新或实际界面变化才是操作效果证据。
• 保存截图使用临时文件并校验 PNG；默认帧只在本机短暂缓存。清理只删除本会话生成的远端/本地文件，不碰用户相册。锁屏和受保护画面保持系统行为，不自动解锁或关闭隐私保护。

uiRecord record 是操作记录，不是视频录屏；其记录可写到 CSV，并不产生 H.264 视频。不要把它接成“录制投屏”。UITest uiRecord

官方工具：确有投屏，但没有可确认的第三方嵌入协议

DevEco Studio 官网当前明确支持连接设备投屏、点击、滑动、字符输入及拖拽包/文件；26.0.0 Release 的官方说明将设备投屏列为新增能力。产品提供 macOS Intel/ARM 版本。它是真实设备投屏能力，不能与“鼠标控制模拟器”的教程混用。DevEco Studio 官网、26.0.0 官方版本概览、仅针对模拟器的操控屏幕文档

DevEco Testing 官方 FAQ 确认 Windows/Mac 客户端、设备投屏等测试工具；要求 HarmonyOS NEXT 设备开启开发者模式和 USB 调试，并能被 HDC 识别。官方工具介绍明确其投屏支持在 PC 上操作设备。最新 26.0.0 兼容表仍将“设备投屏”的模拟器列标为不支持；不要把云手机特定接入指引外推到所有本地模拟器。DevEco Testing FAQ、官方工具介绍、最新兼容表

本轮没有从这些第一方资料确认可供第三方插件使用的投屏 SDK、稳定 socket 协议、可重新分发的 device agent 或指定设备投屏 deep link。因此可以引导用户打开已安装的官方应用并选择设备；不能提取其私有 agent 并当作插件依赖。Device Manager 只是工具内管理入口的名称，不能据二手教程编造其稳定 CLI。本轮未检视商业工具安装包，不判断其内部实现。

官方录屏 CLI：结束后导出视频

华为官方录屏文档要求设备解锁；录制中锁屏会退出，文档不支持模拟器录屏。其命令流程是启动系统录屏组件、停止、定位媒体、必要时复制到可下载目录、下载文件，未给出实时 stdout 视频流协议。华为录屏文档

开始：
["-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、返回路径和唯一文件名。开始/停止是设备写操作，不能作为能力探测；录屏组件的停止写法也不能无限重试。用会话状态管理、手机通知和最终可解码文件验收，未知状态引导在手机停止。本功能会生成设备媒体文件，默认不能顺手删除相册原件。华为录屏文件导出流程

真正视频流：自建伴随应用路线

AVScreenCapture 支持将采集结果作为码流交给其他模块，以实现桌面共享。最新 OpenHarmony 指引区分文件输出和码流输出，并说明码流录制开始会出现隐私选择弹窗；受保护内容可被屏蔽。华为最新窗口级录屏文档亦明确 Phone/Tablet 的 Picker 能力和权限条件。因此“普通应用一概不能录屏”不正确；需要区别用户授权录屏与系统免授权采集/输入注入。OpenHarmony 录屏基础流程、华为窗口级录屏与授权

建议独立原型链路为：用户启动已签名 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 示例

传输示例为 ["-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 端口转发

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、调用实现、JPEG 采集实现

源码可导出的启动契约是 uitest start-daemon singleness --extension-name curios-screen-<nonce>.so，加载 /data/local/tmp/ 下相应文件，默认名 agent.so。扩展须自行实现有界传输、停止以及主机认证。这是源码入口，不是本次确认的商业公共 CLI。 官方仓库 README 将 start-daemon 标为测试端注入用途；商业固件可能改变加载策略、系统库、ABI 或采集实现。先在自己可控制的 OpenHarmony 测试镜像验证，再专门评估真实商业设备，不应默认为任何手机加载 native 代码。加载器、命令分派、官方 README

不能从论坛提到的 xdevice_scrcpy 或 DevEcoScrcpy 日志推断商业工具私有协议已公开，也不能把上面的开源 JPEG 路径描述成与商业 H.264 路径完全相同。

已核查的开源成品

项目与锁定提交	真实机制、macOS、授权边界	结论
鸿镜 ohos-scrcpy-app	Flutter macOS/Windows；H.264、VideoToolbox、鼠标/触摸/按键、录制，编码失败可降级 JPEG。设备端为系统 HAP，作者明确要求 Full SDK、目标系统信任签名和权限白名单。	可参考本机解码与协议设计；不能普通签名安装到商业手机便承诺工作。
OpenHarmony_Scrcpy	项目声明跨桌面平台，设备端明确要求 OpenHarmony 5+ root 版本；原生 AVScreenCapture + H.264/H.265。安装脚本 remount 并写 /system/bin 和 /system/etc/init，服务具媒体采集权限。	只适合受控开发镜像；不用于本项目普通手机自动安装。
scrcpy-ohos	JavaFX/JDK11；源码 snapshot_display 截图下载，操作后刷新，uinput 模拟事件；README 明确非实时。未找到根 LICENSE。	不是官方 scrcpy 的鸿蒙兼容层，也不提供连续视频流；可看思路，不能据公开代码便假定可复制分发。

鸿镜设备权限包括 CAPTURE_SCREEN、EXEMPT_CAPTURE_SCREEN_AUTHORIZE、INJECT_INPUT_EVENT，其文档明确需 ACL、系统签名和指纹白名单。仅将 HAP 换成自己的普通调试证书不解决这些限制。鸿镜签名要求、设备权限声明

鸿镜可复核的传输为 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。鸿镜协议、loopback 监听

许可分别是鸿镜 MIT、OpenHarmony_Scrcpy Apache-2.0；仍需保留声明、审查依赖和自行构建的分发物。root 项目的安装脚本会遍历目标设备并更改系统分区，本项目不能直接调用它。鸿镜 LICENSE、OpenHarmony_Scrcpy LICENSE、root 服务要求、系统分区安装脚本

验收与后续决策

先交付可探测的屏幕预览和明确输入，再进行视频流原型。每条能力分别保存 available/unavailable/unknown 及原因；不把 HDC 已连接等同全部投屏/输入可用。最小真机验收需要覆盖截图解码、旋转坐标、点击/滑动效果、中文输入、断线取消、锁屏、拒绝授权、受保护画面、停止采集后不再传帧和本会话文件/转发清理。视频流另外测首帧时延、实际 FPS、CPU/温度、背压、编码器重建与应用后台状态；完成这些前不使用“低延迟 60 FPS”等宣传。

本轮明确未验证：Pura 70 Ultra 当前固件的 UITest 输入效果、HDC 版本、官方工具真机投屏、伴随应用采集权限、UITest addon 加载、任何社区 HAP/二进制。已确认的是公开能力与实现边界；没有执行设备动作，也没有修改插件代码。