HarmonyOS uitest 扩展 · Node.js SDK

用一条长连接,
控制鸿蒙设备

UI automation, screenshots and H.264 casting for HarmonyOS — from Node.js.

把设备侧的 agent.so 与 libscreen_casting.z.so 封装成类型化 API:点击、滑动、截图、H.264 投流与 MP4 录制,走的是扩展自己的长连接,不是 hdc 的慢路径。

npm install uitest-sdk
真机截图:鸿蒙桌面

快速开始

$ npm install uitest-sdk
$ node quickstart.mjs
✓ connected  BRA-AL00 · 1216×2688
✓ click(608, 1344)                 32 ms
✓ captureScreen() → 608×1344 JPEG  118 ms

也可以不开编辑器

包里带一个命令行:每条命令开一次设备、执行一步、等 UI 稳定、打印屏幕或 diff、释放设备。同一套命令还能以 MCP 暴露给 Agent——写代码不是前提。

$ npx uitest-sdk doctor
settled · doctor
targets: dev-<8 位哈希>
capabilities: waitForIdle=yes findComponent=yes
$ npx uitest-sdk observe --task "check WLAN"
settled
screen 1216x2688 · app: com.huawei.hmos.settings
[65] button "WLAN" @608,432 focused checked
[66] toggle "WLAN" @1067,433 checked

真实输出,2026-11-16 真机 BRA-AL00。序列号只以 8 位哈希出现。

为什么是一条命令一个进程

  • 宿主侧不常驻。没有本地后台进程,也没有「先连上再记住」的会话;设备侧扩展按需拉起、跨命令复用,崩掉的命令不会留下半开的状态。
  • 能看见结果。每条命令都把动作后的屏幕或 diff 打出来,下一步照着最新的 ref 走。
  • 能被审。策略在碰设备前判定:凭据永久拦截,支付、金融、删除、发送默认要人点头。审批 id 绑命令与目标签名,一台设备一个任务。
  • 能复现。每步一条 trace,报告从磁盘读回整轮任务,包括不走屏幕的那些命令。

需要省掉每步的设备启动开销时,用 uitest-sdk mcp:一个进程、一次连接、逐步调用。

21 条命令

observe读屏,每个元素一行,带 ref、角色、标签与中心点
tap按 ref、按标签或按 selector 点击;--long 长按
type输入文本,走设备 IME,中文与 emoji 可用;--paste 一次粘贴,长文本快一倍
swipe方向或两点滑动
double-click双击
drag先按住再移动,用于拖拽排序
fling短促快滑,松手后列表继续滑行
pinch双指缩放,走设备 PointerMatrix
keyback / home / power / enter 等系统键
wait-for等某个标签出现,设备侧一次往返
read-list逐屏读完整个列表,每个标签只出现一次
scroll-until逐屏翻到目标标签为止
launch按别名或 bundle 启动,自动读入口 ability
apps列已装应用;--current 当前应用;--has 是否安装
window焦点窗口或某 bundle 的窗口,可 --focus / --close
doctor探测设备与所需能力
screenshot存一张 JPEG,报告帧尺寸与缩放因子
inspect把每个元素框出并编号(编号即 ref);--html 另存可悬停的面板
report把整轮任务写成自包含 HTML 报告
status当前任务、设备哈希、策略设置
handoff请人接手(登录、验证码、解锁),设备交给人直到 resume

也可以一直开着:uitest-sdk live

浏览器里同时看到画面和布局

  • live 起一个本地页面:左边是投屏,右边是当前屏的节点表。
  • 点节点或点画面上的框,复制它的 ref、角色、标签与中心坐标;编号与 tap --ref 共用。
  • H.264 走浏览器自带 WebCodecs 解码;x86_64 的 MJPEG 走 createImageBitmap。

隐私开关默认打开

  • 密码框与验证码在节点表和画面上都被遮住。
  • 关掉后用 redact: false 重新读布局,原文才出现——遮罩是在读的时候做的。
  • 多个页面同时连着时,只要还有一个开着遮罩,共享模型就保持遮罩。

状态机与背压

  • idle → starting → live → reconnecting → stopping → stopped,失败按 0.5/1/2/4/5 s 退避重启。
  • 页面重载有 5 s 宽限期,不重开投流 daemon。
  • 写队列超过 1 MB 丢增量帧并请求 IDR;页面侧 decodeQueueSize > 4 时同样丢。

实测

  • 真机 1216×2688 / 30 fps:首帧约 3.1 s(含 daemon 启动)。
  • 画面持续变化时页面绘制 18.5 fps,帧间隔中位 33 ms、p90 55 ms。
  • 每帧平均 11.6 KB;MJPEG 路径同一页面 22 fps。

一次调用一条命令,状态留在磁盘上

ref 跨进程稳定

  • ref 表存在 <state-dir>/refs-<hash>.json。
  • observe 打印的 [65] 在下一条 tap --ref 65 里仍指向同一元素。
  • 不在当前屏幕上的 ref 直接 not_found,不会悄悄指向别的控件。

审批跨进程可用

  • approval_pending 给出的 id 存在 approvals-<hash>.json。
  • 下一条命令带 --approval-id 就能兑现;id 一次性、10 分钟过期。
  • 页面在等待期间变了返回 stale,不会执行到别的东西上。

凭据不外泄

  • 密码框的值、凭据语境的 3–8 位验证码在 observe 与 diff 里显示为 ••••••。
  • 截图与报告里的对应区域盖灰;被遮住的元素无法再按原文搜索。
  • 策略与脱敏共用同一套凭据词表;低层 captureLayout() 保持原样。

报告跨进程聚合

  • 每条命令各写一个 trace 文件;report 按 task 从磁盘读回来、跨文件重新编号。
  • 覆盖整轮任务,包括 apps、launch 这类不走屏幕动作的命令。
  • --trace-shots 每步存一张截图,链接相对报告自身。

每条命令的实际耗时

命令实测说明
status1.2 s只读状态文件,不碰设备
apps --current1.5 s一次 hdc 查询
observe1.7 s读屏 + 稳定 + 记录
doctor1.9 s探测 5 项能力
tap --ref2.3 s读屏 + 点击 + 等稳定

每条命令都是一次独立进程:设备打开、执行一步、等 UI 稳定、释放。数字是 2026-11-16 真机上 2–3 次采样的范围,含 Node 启动;设备侧动作本身仍是 SDK 的毫秒级。

同一套命令,接给 Agent

npx uitest-sdk connect            # 把 MCP 注册写进 Agent 自己的配置,并装好 Skill
npx uitest-sdk connect --agent gemini   # 也支持 codex、copilot
npx uitest-sdk mcp                # stdio 上暴露 uitest_<command>,整个进程只开一次设备
npx uitest-sdk install-skill      # 写 ~/.claude/skills 与 ~/.agents/skills 两处

Skill 与二进制同版本发布。Agent 拿到的是「先 observe、再按 ref 动作、读 diff」的固定循环,以及一组它必须遵守的安全规则。

connect、hold、handoff、resume 从 0.3.0 起提供,connect --agent gemini|copilot、设备状态与审批记忆从 0.4.0 起提供,dev.hypium 的 118 个方法从 0.5.0 起提供,7.0 WebSocket 投流(transport: "ws")从 0.6.0 起提供,inspect、dev.files、CastConfig、FpsMeter 与浏览器里的 live 投屏从 0.7.0 起提供;npm 上的 latest 是 0.8.0。

只改自己那一项

  • connect 直接编辑 Agent 的设置文件,不再给人一段 JSON 让他手贴。
  • 注释、键顺序、其它 server 的排版原样保留;已经正确时一个字节都不写。
  • 文件解析失败就拒绝并报出偏移,不替人重写。

两处 Skill 目录

  • ~/.claude/skills 给 Claude Code;~/.agents/skills 是跨 runtime 别名。
  • Codex、Copilot CLI、Gemini CLI 都读后者,一次安装覆盖四个 runtime。
  • 两个目标先全部检查再写,拒绝时不会留下半套。

随时可以接管

  • uitest-phone hold 把设备交给此时拿着手机的人,连正在运行的 MCP 会话也一并让出。
  • Agent 也可以反向发起:handoff --reason "请登录" 把手机交给人,并停下等 resume。
  • Agent 命令 2 秒内以 lease_held(退出码 2)停下,不重试、不抢回。
  • resume 交还后,同一个会话下一条命令自动继续,不用重启。
  • hold 与 handoff 都不按进程存活判断,所以不会自己过期。

状态即结果

状态退出码含义
settled0执行完且 UI 已稳定
uncertain1等不到 UI 停止变化
not_found1ref、标签或列表不在屏幕上
lease_held2另一个任务——或人——占着这台设备
handoff2Agent 主动把手机交给人,等对方 resume
approval_pending3需要人确认这一步
blocked4策略在碰设备前就拒绝了
approval_denied4审批 id 错误、用过或过期
stale4等待审批期间页面变了

实拍:投屏与布局检查

两张都是真实页面截下来的,没有重画。图上的黄色高亮由页面自己按节点坐标播放:选中的那一行和手机画面上对应的框同时亮起,就是你在 live 里点一行时看到的样子。

uitest-phone live 页面:左侧是手机画面与节点框,右侧是节点表

左右滑动看完整页面

uitest-phone live · 浏览器里投屏 + 节点表

[100] button 个人热点 [101] button 流量管理 [104] button VPN

画面和节点是同一次读屏

  • 节点框按读屏时的 bounds 画,和设备分辨率同一个坐标系,不会随窗口缩放错位。
  • 帧走一条 WebSocket,浏览器自己用 VideoDecoder 解码;页面上写着它此刻的 fps 和距上一帧的时间。
  • 画面在动、UI 静止时只出一帧——采集是脏区驱动的,不是卡住。

遮罩在读屏时就生效

  • 打开 mask credentials,账号、验证码这类文本在布局被读出来的那一刻就被替换,不是给视频打码。
  • 所以截图、节点表、复制出来的 JSON 三处看到的是同一个遮罩结果。
  • 同一台设备上所有页面都关掉遮罩,才会真的露出原文。
inspect --html 面板:左侧是带编号框的手机截图,右侧是编号、ref、角色、bounds 表格

左右滑动看完整页面

inspect --html · 单文件布局面板

#4 · ref 96 · button 飞行模式 #9 · ref 101 · button 流量管理 #12 · ref 104 · button VPN

图上的数字就是 ref

  • 每个框角上的编号对应表里的 # 行;那一行的 ref 可以直接交给 tap --ref。
  • 框的颜色按角色固定:button 绿、text 蓝、list 紫、toggle 青,两次读同一屏结果一致。
  • 表格给出 bounds 与状态(focused / scrollable),排版问题不用靠猜。

一个 HTML 文件,不联网

  • 截图以 data URI 内嵌,没有外部图片、字体或脚本请求,丢到任何机器上双击就能看。
  • 悬停表格某一行,图上对应的框会加亮;点一下也能固定住。
  • 同一份数据还以 --json 输出,报告和面板用的是同一个结构。

真机实测

同一台真机、同一个脚本跑出来的对比(scripts/bench-compare.ts)。hdc CLI 的数字包含 hdc 进程启动、shell 往返与 uitest 启动——也就是手敲命令时真正付出的时间。

操作本 SDKhdc CLICLI / SDK
点击8–30 ms(中位 9 ms)497–561 ms(中位 531 ms)59.0×
滑动(300 ms 手势 / 600 速度)389–395 ms(中位 391 ms)2630–2787 ms(中位 2695 ms)6.9×
整屏截图(含回传)109–222 ms(中位 184 ms)741–890 ms(中位 828 ms)4.5×

其他截图方式

  • snapshot_display + 回传:592–694 ms(中位 651 ms),约 194 KB。
  • uitest screenCap + 回传:中位 828 ms,1216×2688 PNG 约 701 KB。
  • 本 SDK:中位 184 ms,608×1344 JPEG 约 124 KB,直接拿到字节。

连续画面

  • screenCap 轮询:约 1.4 fps,每帧都要重新起进程并回传。
  • MJPEG 采集流:10–16 fps,静止画面只出 1 帧。
  • H.264 投流:15–89 fps,一条 gRPC 通道连续出帧。
能力API实测
整屏截图agent.captureScreen()107–193 ms
点击agent.click(x, y)21–50 ms
滑动agent.swipe()386–640 ms
MJPEG 流agent.streamScreen()10–16 fps
H.264 投流dev.createCast()15–89 fps

真机 BRA-AL00,1216×2688,uitest 7.0.0.1。对比表是点击 10 次、其余各 5 次的采样,取代表性一轮;多轮之间 CLI 点击中位 390–561 ms(44.9–59.0×),滑动 6.1–6.9×、截图 3.8–4.5×。第二张表来自验收阶段的 8 次采样。原始样本见 docs/benchmarks.md。

和现有方案比

不是把所有路径都重写一遍:同一个 agent RPC 上我们持平;官方走慢路径的地方我们换路;7.0 上失效的录屏,我们直连 6.8 casting。

能力其他方式uitest-sdk结果
整屏截图snapshot_display + 回传:675 msagent MJPEG:178 ms快 3.8×
UI 树dumpLayout + pull:中位 1125 mscaptureLayout:中位 414 ms快 2 倍以上
单次动作官方工具内部同样走 agent RPC同一个 agent RPC持平
录屏官方 26.x 的 7.0 unix 录屏路径在 7.0.0.1 上失效直连 6.8 casting -m 1我们能跑
连续画面screenCap 轮询约 1.4 fpsH.264 投流 15–89 fps最高约 60×

截图与 UI 树的「其他方式」是官方工具链在同一台真机上的路径;单次动作两边都走 agent RPC,所以不宣称优势。多轮采样范围:截图 3.2–3.8×、UI 树 2.6–2.7×,表中取代表性一轮;完整样本见 docs/benchmarks.md。

完整功能矩阵

能力hdc CLI官方快照 / 布局官方 26.x 套件uitest-sdk
点击 / 滑动 / 输入每步起进程—内部同样走 agent RPC同一 RPC,类型化
整屏截图中位 828 ms675 mssnapshot_display178 ms
窗口级 UI 树dumpLayoutdumpLayout支持captureLayout + dumpLayout
窗口截图不支持不支持未见公开能力整屏 + 按 bounds 裁剪
连续 H.264 投流不支持不支持内置投屏,未公开 API15–89 fps
MP4 录制不支持不支持7.0 上失效6.8 casting
多实例并发命令无状态,受设备锁限制命令无状态,受设备锁限制单设备会话为主复用 daemon + 退避
编程接口shell 字符串shell 字符串图形化 + 脚本TypeScript,125 个导出
命令行 / Agent手敲命令手敲命令图形化界面21 条命令 + MCP + Skill
结构化错误文本输出文本输出文本 / 异常为主UitestError + code

对比基于我们复现过的公开工具路径,不是对厂商产品的完整评测;官方 26.x 指我们测试的 26.0.1.100 套件。

传输与解码,到底谁更快

投屏好不好用,看两段:设备到客户端怎么传,客户端怎么解。我们把三条公开实现逐行读过,也在同一台机器上量了自己的数字。结论是传输不是瓶颈,解码也不是——瓶颈在设备侧编码器,三家都一样。

三条投屏链路的传输与解码路径对比 上:hscrcpy 与 HOScrcpy 走 gRPC 加软件 FFmpeg 解码;中:HarmonyMirror 多一层 Python 桥接后交给 VideoToolbox;下:uitest-sdk 一条 WebSocket,浏览器 WebCodecs 解码(默认硬解,无 GPU 时退软解)。 其他方案 其他方案 uitest-sdk 设备编码器 H.264 硬件编码 gRPC / HTTP2 unix socket + hdc protobuf 分帧 FFmpeg 软解 libavcodec + swscale YUV→RGB 走 CPU CPU 上传 D2D / Swing 每帧整帧拷贝 hscrcpy HOScrcpy 设备编码器 H.264 硬件编码 gRPC unix socket Python 桥接 本地 TCP 转发 VideoToolbox 硬解,系统直出 HarmonyMirror macOS 设备编码器 H.264 硬件编码 WebSocket 一条 TCP,4 字节长度前缀 WebCodecs 浏览器解码,默认硬解 uitest-sdk 无需安装解码器

左右滑动看完整链路

传输:一条连接,没有中间层

  • 别人走 gRPC over unix abstract socket,要 HTTP/2 栈 + protobuf 分帧;HarmonyMirror 还多一个 Python 进程做转发,每帧跨两次进程边界、两次 H.264 解析。
  • 我们一条 WebSocket,二进制帧就是 4 字节长度 + Annex-B,转 AVCC 每帧 12 µs(增量帧)/ 43 µs(关键帧),占 33 ms 预算的 0.04%。
  • 同一台真机上 6.8 gRPC 与 7.0 WebSocket 帧率持平——瓶颈在编码器,不在传输,这条我们自己也测过。

解码:交给浏览器,不用装 FFmpeg

  • hscrcpy 与 HOScrcpy 都是 FFmpeg 软解 + swscale 转 RGB;hscrcpy 的 README 写「硬解」,但源码里没有任何 hwaccel/D3D11VA 代码。
  • 我们用浏览器自带的 WebCodecs,默认走硬件解码。1216×2688 实测 1.57 ms/帧(硬解)对 2.46 ms/帧(强制软解),画布绘制 0.07 ms。
  • 没有 GPU 解码的机器上,浏览器自动退回软解并继续出画——不写死「必须硬解」,因为那样在这些机器上会直接配置失败、黑屏。
  • 客户端不需要 FFmpeg、gRPC、protobuf 任何一个运行时;浏览器有就能用。
环节hscrcpyHOScrcpyHarmonyMirroruitest-sdk
传输协议gRPC(nghttp2)/ 7.0 也有 WebSocketgRPC(grpc-java)gRPC + 本地 TCP 转发WebSocket,单跳
客户端运行时nghttp2 + FFmpeg + protobufgrpc-java + javacv/FFmpegPython + gRPC + Swift无(浏览器内置)
解码FFmpeg 软解,2 线程FFmpeg 软解VideoToolbox 硬解WebCodecs(默认硬解,可退软解)
色彩转换swscale 软件转 RGBswscale 软件转 RGB系统完成GPU 完成
每帧解码实测未公开未公开未公开1.57 ms(1216×2688)
渲染Direct2D / GDI 回退Swing drawImageAVSampleBufferDisplayLayerCanvas drawImage
丢帧策略最新帧胜出有队列但渲染路径绕过层未就绪即丢写队列 + 解码队列双水位

「未公开」表示对方仓库里没有可引用的解码耗时数据——不是我们没查。hscrcpy 与 HOScrcpy 的结论来自源码逐行核对(h264_decoder.cpp、MainForm.java),HarmonyMirror 来自其 Swift 与 Python 桥接实现。我们的数字在同一台 Windows 机器上用 Chrome 157 无头模式测得,源码见仓库 .work-bench/ 下的探针脚本。解码器的选择交给浏览器:显式要求 prefer-hardware 在无 GPU 的机器上会配置失败(实测 0/30 帧),所以只在默认配置失败后才重试软解。

为什么传输不是瓶颈

设备侧编码器决定了帧率上限:-frameRate 30 时两条通道都是 28.8–30.1 fps,-frameRate 60 时都是 59.3–65.3 fps。把同一段流交给浏览器解码,1216×2688 能跑到 777 fps 上限。也就是说,客户端这一侧还有 20 倍以上的余量。

环节实测相对 30 fps 预算
服务端 Annex-B → AVCC → 帧封装12 µs/帧0.04%
浏览器解码 1216×2688(硬解)1.57 ms/帧4.7%
浏览器解码 1216×2688(强制软解)2.46 ms/帧7.4%
画布绘制(drawImage)0.07 ms/帧0.2%
合计(硬解路径)约 1.64 ms/帧约 5%

32.5 ms 的预算里我们只用掉约 1.6 ms,剩下的是设备编码、网络和浏览器的合成开销。这也是为什么实测页面在持续画面下画 18.5 fps——限制来自设备端 -frameRate 30 与浏览器的显示节奏,不是解码能力。

能力

一个 SDK,覆盖从自动化点击到实时投流的全部路径。

一条长连接

所有请求走同一条 TCP 长连接,串行队列加指数退避,不会因为并发把自己锁死。

毫秒级点击

touchDown + touchMove + touchUp 三段式驱动,点击 21–50 ms,滑动 386–640 ms。

整屏截图

起停驱动的最快路径,608×1344 JPEG 在 107–193 ms 内返回,直接是字节。

窗口截图

设备不提供窗口级截图,SDK 整屏采集后按 UI 树的 bounds 裁剪,结果一样准。

H.264 投流

libscreen_casting 走 gRPC,随 frameRate 输出 15–89 fps 的 Annex-B 帧。

MP4 录制

设备侧编码器直接写 MP4,dispose() 时关闭 muxer 并把文件拉回本地。

多实例安全

复用已在监听的 daemon,只杀自己拉起的那一个,绝不盲杀别人的进程。

失败即报错

每个失败都是 UitestError 子类,不做静默兜底,问题停在它发生的地方。

布局检查

inspect 把每个元素的 bounds 画成框并编号,编号就是 tap --ref 用的 ref;--html 另存一个单文件面板,悬停节点表会高亮对应的框。

命令行

21 条命令覆盖读屏、动作、列表、窗口与报告,每条开一次设备、执行一步、释放。不写代码也能操作手机。

Agent 接入

同一套命令以 MCP 暴露成 uitest_<command>,并随包发布 Skill;connect 把注册写进 Agent 自己的配置,只改自己那一项。策略与审批由 CLI 自己校验,不靠提示词。

人随时接管

hold 之后所有 Agent 命令以 lease_held 停下,不会重试也不会抢回;resume 交还。Agent 遇到登录或验证码也可以 handoff,把手机交给人并等待。

双通道架构

一条长连接做 UI 自动化,一条 gRPC 通道做投流与录制。

Node 进程经 hdc fport 连接 agent.so:8012 与 libscreen_casting.z.so Node 进程 uitest-sdk hdc fport TCP 隧道 agent.so · :8012 JSON + JPEG · 长连接 libscreen_casting.z.so gRPC · H.264

30 秒了解它

从安装到截图、从点击到 89 fps 投流,画面全部来自真机。

已知限制

这些都是实测撞到的设备侧事实,写在这里比藏起来有用。