使用文档
把鸿蒙 uitest 的设备侧扩展封装成 TypeScript API:一条 TCP 长连接(agent.so)负责点击、滑动、截图与 UI 树;另一条 gRPC 通道(libscreen_casting.z.so)负责 H.264 投流与 MP4 录制。0.2.0 起,同一套能力还有一层命令行,可作为 uitest-phone 使用,也能以 MCP 暴露给 Agent。
1. 安装与前提
npm install uitest-sdk
npx uitest-sdk doctor # 确认设备与所需能力都在
- Node.js ≥ 20,ESM(
import)。 - hdc:DevEco Studio 自带的
hdc在PATH上,或设置HDC_PATH,或传Device.connect({ hdcPath })。 - 一台设备:真机或模拟器,
hdc list targets能看到。 - 扩展文件:已随 npm 包发布在
assets/下(arm64/agent.so、arm64/libscreen_casting.z.so、x86_64/agent.so),Device.connect()会自动推送缺失的那份。 - H.264 与录制需要 arm64:x86_64 模拟器只有 MJPEG。
扩展必须由华为签名才能在真机加载(XPM 校验拒绝未签名 .so)。本包内置的是实测可用的签名版本。
2. 快速开始
import { Device } from "uitest-sdk";
const dev = await Device.connect(); // 只有一台设备时可省略参数
try {
const { width, height } = await dev.agent.getDisplaySize();
await dev.agent.click(width / 2, height / 2);
await dev.agent.swipe(width / 2, height * 0.7, width / 2, height * 0.3);
const jpeg = await dev.agent.captureScreen(); // 608×1344 JPEG
console.log(`captured ${jpeg.length} bytes`);
} finally {
await dev.dispose();
}
可运行的版本在包里:node_modules/uitest-sdk/examples/quickstart.mjs。
3. 核心概念
坐标
所有触摸坐标都是逻辑显示坐标,即 getDisplaySize() 返回的那套(例如 1216×2688)。captureScreen() 默认按 scale: 0.5 出图(608×1344);把截图上的点换回显示坐标,乘以 display.width / 608。
扩展与 daemon
Device.connect() 依次完成:读 ABI → 推送对应 agent.so(必要时也推 casting 扩展)→ 如果没有 daemon 在监听 8012 就拉起一个 → 建 hdc fport 隧道 → 连上 TCP → 用一次 getDisplaySize() 做健康检查。任何一步失败都会清掉自己建立的隧道与 daemon,然后抛错。
失败即报错
每个失败都是 UitestError 的子类,带稳定的 code。SDK 不做静默降级:能走 H.264 就走 H.264,走不了会通过 cast.castKind 明确告诉你走的是 MJPEG。
4. Device
import { Device } from "uitest-sdk";
const dev = await Device.connect(options?);
DeviceOptions
| 字段 | 类型 | 默认 | 说明 |
|---|---|---|---|
hdcPath | string | 自动查找 | 查找顺序:HDC_PATH → PATH → 常见 DevEco 安装位置 |
deviceId | string | 唯一设备 | 多设备时必须指定(或设 HDC_TARGET) |
agentPort | number | 8012 | 本地隧道起始端口,被占用时向后找空位 |
autoRestart | boolean | true | 断开后下一次调用自动重连;进行中的请求不会重放 |
extensionDir | string | 包内 assets/ | 按 <dir>/<abi>/agent.so 查找 |
requestTimeoutMs | number | 30000 | 单次请求超时;超时后连接被丢弃 |
ownDaemon | boolean | false | 为 true 时 dispose() 杀掉本实例拉起的那个 daemon |
retryOnBusy | boolean | true | 设备全局锁冲突时按抖动退避重试 |
属性与方法
| 成员 | 类型 | 说明 |
|---|---|---|
dev.agent | AgentClient | 长连接客户端 |
dev.cli | CliRunner | 走 uitest dumpLayout 的窗口级工具 |
dev.files | Files | 设备文件:list / stat / mkdir / remove / move / push / pull / readText |
dev.state | connected / disconnected | dispose() 后变为 disconnected,再调用抛 EDISPOSED |
dev.ownsDaemon | boolean | 本次连接是否由自己拉起 daemon |
dev.resolveCastExtension() | string / null | 该 ABI 的 casting 扩展路径 |
dev.createCast(opts) | Promise<CastClient> | 创建投流或录制 |
dev.dispose() | Promise<void> | 关连接、撤销自己的 fport;ownDaemon: true 时再杀掉自己的 daemon |
5. AgentClient:UI 自动化
所有方法都返回 Promise,失败抛 UitestError。
显示
await dev.agent.getDisplaySize(); // { width: 1216, height: 2688 }
await dev.agent.getDisplayRotation(); // 0 / 1 / 2 / 3
触摸
await dev.agent.click(x, y);
await dev.agent.touchDown(x, y);
await dev.agent.touchMove(x, y);
await dev.agent.touchUp(x, y);
await dev.agent.swipe(x1, y1, x2, y2, { steps?: number; durationMs?: number });
click=touchDown+touchUp,实测 8–30 ms。swipe默认steps: 8、durationMs: 300,是 touchDown + N 次 touchMove + touchUp 的三段式;中途失败会先touchUp再抛错。- 坐标四舍五入为整数。
文本与按键
await dev.agent.inputText(x, y, "hello"); // hypium Driver.inputText
await dev.agent.triggerKey(keyCode);
截图
const jpeg = await dev.agent.captureScreen(); // 608×1344 JPEG Buffer
const jpeg2 = await dev.agent.captureScreen({ scale: 1 }); // 1.1.10 上 scale 无效
实现是「起一次采集流 → 取第一帧 → 停止」,这是设备上最快的整屏路径。
连续取帧(MJPEG)
for await (const jpeg of dev.agent.streamScreen({ scale: 0.5 })) {
// jpeg 是完整的 JPEG Buffer
if (done) break;
}
采集是脏区驱动的:静止画面只出 1 帧然后不再出帧,这不是卡死。断开循环会自动 stopStream()。
UI 事件流
for await (const ev of dev.agent.streamUiActions()) {
console.log(ev.type, ev);
}
只上报真实用户输入;通过 agent 注入的合成触摸不会回传。stopCaptureUiAction 会关闭会话。
事件与低层接口
const off = dev.agent.onFrame((jpeg) => void 0);
const offClose = dev.agent.onClose((err) => void 0);
dev.agent.connected; // boolean
dev.agent.close(); // 主动关闭,之后不再重连
await dev.agent.call("CtrlCmd", { api: "getDisplaySize", args: [] });
await dev.agent.hypium("Driver.screenCapture", "Driver#0", []);
call 的 method 只能是 "Captures" / "CtrlCmd" / "Gestures" / "callHypiumApi"。
6. Session 与命令行
Session 是 SDK 里「一个任务看一台设备」的那一层:它持有租约(两个任务不能交错)、策略(危险步骤在碰设备前停下)、ref 表(ref 只指向它被观察时的那个元素)和 trace。CLI 的每条命令都只是开一个 Session、跑一步、关掉。
直接使用 Session
import { Device, Session } from "uitest-sdk";
const dev = await Device.connect();
const session = await Session.open(dev, { task: "check WLAN" });
try {
await session.observe(); // 读屏并记录
const r = await session.tap({ ref: 12 }); // 按 ref 点击
console.log(r.status, r.text); // settled · 一行 diff
} finally {
await session.release(); // 释放租约、关 trace、dispose 设备
}
| 成员 | 说明 |
|---|---|
Session.open(device, opts) | 取设备租约;被别的任务占用时抛 LeaseHeldError,此时设备还没被读写 |
observe() / screen() | 读屏并记录;screen() 返回上一次读到的屏幕,没有则新读 |
tap(target, opts) | {ref} 走坐标点击,{text} 或 On 走设备自己的 Component.click |
type(text, opts) | 默认输入到焦点框;密码框在任何按键前被策略拒绝。{paste: true} 一次粘贴而不是逐字符输入,实测 36 字符 1.3 s 对 2.8 s |
swipe / longPress / doubleClick / drag / fling / pinch | 手势;pinch 走 PointerMatrix,单指通道表达不了两条同时的轨迹 |
waitFor / readList / scrollUntilVisible | 设备侧等待、逐屏读列表、逐屏翻到目标 |
window(filter, opts) | 报告焦点窗口或某 bundle 的窗口,可 focus / close |
pressKey(key) | 命名按键或数字 key code |
steps | 本会话已记录的步数 |
release() | 结束任务 |
SessionOptions
| 字段 | 类型 | 默认 | 说明 |
|---|---|---|---|
task | string | — | 任务名,出现在租约、trace 与报告里 |
stateDir | string | .uitest-phone | trace、截图、租约所在目录 |
lease | object | false | 开 | false 表示放弃独占 |
policy | PolicyOptions | — | read-only、confirm 规则、应用白名单 |
traceShots | boolean | false | 每步存一张截图 |
settleMs | number | 3000 | 动作后等待 UI 稳定的上限 |
noTrace | boolean | false | 不读写 trace 文件 |
命令行
安装后命令名是 uitest-phone;npx uitest-sdk <command> 等价,无需全局安装。
uitest-phone doctor
uitest-phone observe --task "check WLAN"
uitest-phone inspect --html layout.html
uitest-phone tap --ref 12 --task "check WLAN"
uitest-phone read-list --ref 20
uitest-phone report --title "WLAN check"
uitest-phone live # 浏览器里投屏 + 节点表(0.7.0)
全局 flag 对所有命令生效:--task、--state-dir、--device、--read-only、--apps、--confirm、--settle-ms、--trace-shots、--approval-id、--approval-scope、--json。完整命令与参数见 --help 与随包 Skill 的 REFERENCE.md。
状态与退出码:settled 0、uncertain/not_found 1、lease_held/handoff/device_locked/device_needs_setup/device_offline 2、approval_pending 3、blocked/approval_denied/stale 4。--json 时输出 {status, code, text, data}。
设备本身不可用时也有名字:锁屏是 device_locked(不把锁屏当成页面去点),连上但没授权调试是 device_needs_setup,没插/关机/Offline 是 device_offline。三者都以退出码 2 停下,Agent 应请人解锁、点「允许」或插线,而不是重试。
凭据脱敏
observe、动作后的 diff、read-list、screenshot、--trace-shots 与 report 共用一份屏幕模型:密码框的值显示为 ••••••;凭据语境里的 3–8 位验证码显示为等长圆点,前后的词保留,策略仍能分类。被遮住的元素不能再按原文找到(tap --text 482913 返回 not_found),截图里的对应区域盖成灰色。低层 agent.captureLayout() / captureScreen() 返回设备原样数据,不脱敏。
MCP 与 Skill
uitest-phone mcp # stdio 上以 JSON-RPC 2.0 暴露 uitest_<command>
uitest-phone install-skill # 写进 ~/.claude/skills 与 ~/.agents/skills
MCP 进程只开一次设备,工具调用不再付每步的设备启动开销。返回非 settled 的工具调用是 isError: true 的工具错误,文本里带状态与原因,而不是传输失败。install-skill 同时写两个目录:~/.claude/skills 给 Claude Code,~/.agents/skills 是 agentskills.io 的跨 runtime 别名,Codex、Copilot CLI、Gemini CLI 都读它。两个目标先全部检查再写,拒绝时不会留下半套;已有的 SKILL.md 默认保留,除非给 --force。升级不需要重跑:安装目录里记着版本与文件摘要,mcp 启动时会把本包写的那份就地更新到当前版本;人改过的与手写的副本不动。
一步接好 Agent0.4.0
uitest-phone connect # 默认 claude
uitest-phone connect --agent codex
uitest-phone connect --agent gemini
uitest-phone connect --agent copilot
把「改配置文件 + 装 Skill」合成一步:只改自己那一项,注释、顺序与其它 server 的格式原样保留;已经正确时什么都不写;文件解析失败就拒绝并报出文件名与偏移,不替人重写。
| Agent | 设置文件 | Skill 目录 |
|---|---|---|
claude(默认) | ~/.claude.json($CLAUDE_CONFIG_DIR) | ~/.claude/skills、~/.agents/skills |
codex | ~/.codex/config.toml($CODEX_HOME) | ~/.agents/skills |
gemini | ~/.gemini/settings.json | ~/.agents/skills |
copilot | ~/.copilot/mcp-config.json($COPILOT_HOME) | ~/.agents/skills |
写入的入口是当前 node 加本包的绝对路径:从 Dock 或开始菜单启动的 Agent 看不到终端的 PATH,裸命令可能解析不到、或被别的程序顶替。只有当本包只存在于 npx 缓存(npm 会清掉它)时,才改写成 npx -y uitest-sdk@<version> mcp。MCP server 在会话开始时读取,接好之后要开新会话。
接管:人要用手机
uitest-phone hold # 设备归人;Agent 命令 2 秒内以 lease_held(退出码 2)停下
uitest-phone handoff --reason "请登录后继续" # Agent 主动请人接手,停在 handoff
uitest-phone resume # 交还给 Agent
hold 把租约写成 "held by a person" 后立即退出。它不按进程存活判断,所以不会自己过期,也没有 Agent 命令能把它抢回去;resume 只释放 hold,别的任务自己的租约不碰——只有取走设备的那个任务能干净地结束。
它可以抢走正在运行的任务,包括整个进程只持一次租约的 uitest-phone mcp 会话。任务不会在动作中途被打断,而是在下一条命令前发现租约没了,返回 lease_held;hold 会打印它从哪个任务手里接过了设备。resume 之后同一个 Agent 会话在下一条命令自动重新取得设备,不需要重启。
Agent 也能反向发起:handoff --reason "请登录后继续" 把手机交给人,立即返回 handoff(退出码 2)。原因写在租约里,之后每个拿到 lease_held 的命令都会重复它;人做完后 resume,同一个 Agent 会话下一条命令继续。MCP 里对应工具是 uitest_handoff,参数 reason 必填——没有原因,人打开手机时只能猜 Agent 要什么。
设备侧没有「人在用手机」的可靠信号:UI 事件流会关掉会话、能把 agent daemon 卡死,而且合成点击也会被当成手指,分不出真假。所以接管是人的明确声明,这也正好是 Agent 唯一能遵守的形式。
7. 投流与录制
const cast = await dev.createCast({
mode: "stream", // "stream" | "record"
frameRate: 60, // 15 | 30 | 60 | 120,默认 30
scale: 2, // 1..5 整数缩小因子,默认 1
});
for await (const chunk of cast.stream()) {
// H.264: { data, pts, flags, isKeyFrame };MJPEG: { data, pts }
if (chunk.isKeyFrame) { /* 从这里开始解码 */ }
}
await cast.requestIDRFrame(); // H.264 专用;MJPEG 上是 no-op
await cast.dispose();
CastOptions
| 字段 | 类型 | 默认 | 说明 |
|---|---|---|---|
mode | stream / record | 必填 | record 只支持 arm64(需要 casting 扩展) |
frameRate | 15|30|60|120 | 30 | 扩展只认这四个值,其它值会被设备侧静默重置 |
scale | 1..5 | 1 | 整数缩小因子;越界抛 EBADARG |
outputPath | string | — | record 必填,dispose() 时把 MP4 拉到这里 |
bitRate | number | 8_000_000 | 编码码率 |
iFrameInterval | number | 2000 | 关键帧间隔 |
screenId | number | 0 | 屏幕编号 |
transport | grpc / ws | grpc | grpc 用内置 6.8 扩展;ws 用 7.0 WebSocket 扩展(需 wsExtension) |
wsExtension | string | — | ws 必填:本地 7.0 .so 路径,按文件名推到设备 |
port | number | 5000 | ws 专用:设备侧监听端口,每个 daemon 一个 |
socketName | string | 内部常量 | grpc 专用:覆盖抽象 socket 名,同机跑多个投流的方式 |
durationMs | number | — | record:到点自动停止(等价于调 dispose():关 muxer、拉回文件、杀 daemon) |
CastClient
| 成员 | 说明 |
|---|---|
castKind | "h264" 或 "mjpeg",显式选择的结果 |
stream() | AsyncIterable,逐块给出 H.264 / JPEG |
requestIDRFrame() | 请求一个关键帧(H.264);MJPEG 无操作 |
dispose() | 结束投流;录制模式下关闭 muxer 并拉回文件 |
选择规则
transport: "ws"→ 7.0 WebSocket 扩展。没有wsExtension、文件不存在、或设备是 x86_64(没有 7.0 构建)都抛ExtensionMissingError。不会退回 gRPC。- 否则
resolveCastExtension()非空 → H.264(gRPC over abstract socket,实测 15–89 fps)。 - 为空(x86_64 模拟器)→ MJPEG(
castKind === "mjpeg",10–16 fps)。 - x86_64 上请求
mode: "record"直接抛ExtensionMissingError,不会返回一个「录不到东西」的客户端。
7.0 WebSocket 传输0.6.0
const cast = await dev.createCast({
mode: "stream",
transport: "ws",
wsExtension: "./libscrcpy_server_unix_7.0-20260930.z.so",
port: 5000,
});
SDK 不打包 7.0 扩展,需要自己提供 .so。它按文件名推到 /data/local/tmp/<name> 并用 --extension-name <name> 加载,所以能和内置的 6.8 扩展同时存在、互不覆盖。
真机实测:启动 0.9–1.3 s,首帧 82–137 ms,requestIDR 7–9 ms,-frameRate 30 下 20.8–23.2 fps。与 6.8 持平,优势是客户端零 gRPC 依赖。
一个客户端独占一个 daemon。实测 stop 是进程级的:任一客户端 stop,同一 daemon 上另一路立刻停止出流;stop 后监听 socket 关闭,新客户端连不上。并发投流靠多个 port,不是一个 daemon 多客户端。
投屏与实时检查:uitest-sdk live0.7.0
npx uitest-sdk live # http://127.0.0.1:7000/
npx uitest-sdk live --privacy off # 初始不遮凭据
npx uitest-sdk live --no-layout # 只投屏
一个页面里同时有画面和布局:右边是当前屏的节点表,点节点(或点画面上的框)就复制它的 ref、角色、标签与中心坐标,编号和 tap --ref 共用。解码在浏览器里完成:H.264 走 WebCodecs VideoDecoder(服务端把 Annex-B 转 AVCC 并生成 avcC),MJPEG 走 createImageBitmap,没有 MSE、没有 fMP4 重封装。
隐私开关默认打开:密码框与验证码在节点表和画面上都被遮住。关掉后服务端用 redact: false 重新读布局,原文才出现 —— 遮罩在读的时候完成,不是事后擦除。多个页面同时连着时,只要有一个还开着遮罩,共享的屏幕模型就保持遮罩。
状态机是 idle → starting → live → reconnecting → stopping → stopped,失败从任意状态进入 failed 并按 0.5/1/2/4/5 s 退避重启;页面重载有 5 s 宽限期,不重开投流。背压在 socket 写队列超过 1 MB 时丢增量帧并请求 IDR,页面侧 decodeQueueSize > 4 时同样丢。
页头两个按钮:Shot 存截图,Record 录 MP4。截图走 Session.observe({ out }),所以遮罩规则和节点表是同一套——文字里藏起来的密码在像素里也是灰块。录屏另起一个 record daemon(gRPC 用自己的 socket,WebSocket 用端口 +1),画面不会停;同一时间只有一个录屏,页面关掉时正在录的那个会被停掉并写盘。实测录制期间画面保持 29–30 fps。
真机 1216×2688 / 30 fps 实测:首帧约 3.1 s(含 daemon 启动),画面持续变化时页面绘制 18.5 fps,帧间隔中位 33 ms、p90 55 ms,每帧平均 11.6 KB。
这条链路每一步的耗时都量过:服务端把 Annex-B 转 AVCC 并封装成帧是 12 µs/帧(关键帧 43 µs),浏览器解码 1216×2688 是 1.57 ms/帧(硬解)到 2.46 ms/帧(强制软解),画布绘制 0.07 ms。30 fps 的 33 ms 预算里只用掉约 5%,瓶颈在设备侧编码器。和 hscrcpy / HOScrcpy / HarmonyMirror 的逐行对比见首页,真实页面截图见首页「实拍」。
import { LiveServer } from "uitest-sdk";
const server = await LiveServer.start({
port: 0,
privacy: true,
graceMs: 5000,
layoutMs: 250,
source: {
createCast: () => dev.createCast({ mode: "stream", frameRate: 30 }),
readScreen: (redact) => {
session.reader.builder.setRedact(redact);
return session.reader.read();
},
},
});
console.log(server.port); // 页面地址
await server.close();
录制
const cast = await dev.createCast({ mode: "record", frameRate: 30, outputPath: "out.mp4" });
// 让画面动起来:静止画面不会产生新帧
await cast.dispose(); // 关闭 muxer → 等待设备写完 → 拉回 out.mp4
设备侧文件路径写死在扩展里(/data/local/tmp/mytest.mp4),不可改。编码器是起停驱动的:createCast 返回时已经在录,dispose() 后才完成。
8. UI 树与窗口
整屏 UI 树
const tree = await dev.agent.captureLayout(); // { attributes, children }
console.log(tree.attributes.bundleName, tree.children.length);
窗口截图
设备不提供窗口级截图,SDK 的做法是「整屏采集 + 按节点 bounds 裁剪」:
const jpeg = await dev.agent.cropToWindow({ bundleName: "com.huawei.hmos.settings" });
const jpeg2 = await dev.agent.cropToWindow({ windowId: 12, scale: 1 });
找不到窗口抛 ENOWINDOW,节点没有可解析的 bounds 抛 ENOBOUNDS。
窗口级 UI 树
agent.captureLayout() 永远返回整屏;要按窗口过滤,用 cli.dumpLayout(一次 shell + pull):
const tree = await dev.cli.dumpLayout({ windowId: 12 });
const tree2 = await dev.cli.dumpLayout({ bundleName: "com.huawei.hmos.settings", withFontAttrs: true });
找节点并点击
import { parseBounds } from "uitest-sdk";
const tree = await dev.agent.captureLayout();
const target = find(tree, (n) => n.attributes.text === "设置");
const bounds = target && parseBounds(target.attributes.bounds ?? "");
if (bounds) {
await dev.agent.click(bounds.x + bounds.width / 2, bounds.y + bounds.height / 2);
}
布局检查与节点高亮
Session.inspect 读一次屏幕、截一帧,把每个元素的 bounds 画成方框并编号 —— 编号就是 ref,可以直接 tap --ref 3。框线按角色着色,被脱敏的元素先涂灰再画框;html 另存一个单文件面板(图片 base64 内嵌,悬停节点表高亮对应的框)。面板长什么样:首页「实拍」。
const r = await session.inspect({ out: "layout.jpg", html: "layout.html" });
// r.nodes: [{ index, ref, role, label, rect, state, masked }, ...]
不走 Session 时可以直接组合组件:Screenshot.mark(boxes) 是绘制原语,inspectScreen(screen, shot) 返回 { nodes, annotated, plain },renderPanel(screen, inspection) 生成 HTML。纯客户端,建立在已有的 captureLayout 与 JPEG 截图上。
9. 完整 hypium API0.5.0
设备侧的 hypium 驱动公开 118 个方法(OHOSDriver 106 + 兼容层 12)。dev.hypium 把它们逐个映射成 TypeScript 方法,参数按设备实际行为定,并逐条标注真机状态:
import { On } from "uitest-sdk";
await dev.hypium.click(On.text("设置"));
await dev.hypium.waitForComponent(On.text("WLAN"), { timeoutMs: 3000 });
await dev.hypium.swipe("up", { distance: 40 });
console.log(await dev.hypium.getComponentProperty(On.type("Button"), "bounds"));
- 位置参数统一为
Target:绝对坐标{x,y}、屏幕比例[0.5,0.5]、矩形,或选择器On/ComponentHandle。 - 选择器目标走设备侧控件(
Component.click等),坐标目标走单指通道(实测 8–30 ms)。 - 多指手势(
pinchIn/twoFingerSwipe/injectGesture)走PointerMatrix,单指通道表达不了两条同时轨迹。 - 不可用的路径立即报错:Toast / UI 事件五个方法抛
UnsupportedError,手写笔与表冠在没有对应硬件时也抛它,不会挂起到超时。 sn()返回序列号的 8 位哈希;findImage只支持模板匹配(SIFT 需要主机侧 OpenCV)。
全部 118 个方法、参数说明、示例与调用路径图在 完整 API 页。
从 0.5.0 起提供;0.4.0 及更早的版本没有 dev.hypium。
10. 工具类与导出
文件、配置与帧率
const entries = await dev.files.list("/data/local/tmp"); // [{ name, path, size, isDir, mode, mtime }]
await dev.files.mkdir("/data/local/tmp/demo dir", { parents: true });
await dev.files.push("./clip.mp4", "/data/local/tmp/demo dir/clip.mp4");
await dev.files.remove("/data/local/tmp/demo dir", { recursive: true });
const cfg = await CastConfig.load(castConfigPath(stateDir));
await cfg.set({ scale: 2, frameRate: 30, transport: "ws" });
const cast = await dev.createCast({ ...cfg.toCastOptions("stream"), wsExtension: "./lib.so" });
const meter = new FpsMeter({ windowMs: 2000 });
for await (const chunk of cast.stream()) meter.add();
Files.remove 拒绝空路径与 /;readText 默认上限 1 MiB。CastConfig 不接管 createCast,合并是显式的;load 忽略手改坏的键,set 对非法值抛 EBADARG。FpsMeter 按帧间隔计算,MJPEG 与 H.264 都能用。
| 导出 | 说明 |
|---|---|
parseBounds("[x1,y1][x2,y2]") | 解析成 { x, y, width, height },格式不对返回 null |
cropRect(inner, outer) | 求交集矩形;无交集返回零矩形 |
FrameDemux | 把「一行 JSON + 裸 JPEG」的混合流拆开 |
SerialQueue | 串行队列,run(fn) 保证同一时刻只有一个请求在途 |
HdcRunner | hdc 封装:shell、push、pull、fportAdd/Remove、listTargets |
CliRunner | 窗口级 dumpLayout |
isBusyException(msg) | 判断是不是「全局锁被占用」 |
MODULE_ID | com.ohos.devicetest.hypiumApiHelper |
CASTING_EXTENSION | libscreen_casting.z.so |
resolveCastingExtension(abi, dir) | 该 ABI 的 casting 扩展路径,没有返回 null |
loadScrcpyService() | 加载 scrcpy.proto 的 gRPC service 构造器 |
H264CastClient / MjpegCastClient | 低层客户端;正常用 dev.createCast() |
Files | 设备文件封装(dev.files):list / stat / mkdir / remove / move / push / pull / readText |
CastConfig / castConfigPath() | 投流默认值的 JSON 持久化(<state-dir>/cast.json) |
FpsMeter | 客户端帧率统计:add() / stats() / reset() |
inspectScreen() / renderPanel() | 布局检查:叠框、编号、生成 HTML 面板 |
Session | 一个任务看一台设备:租约、策略、ref 表、trace |
ScreenReader / ScreenBuilder | 读屏与渲染;renderDiff / renderFull 生成 CLI 打印的那份文本 |
Components / Gestures / AppManager | 设备侧控件操作、手势、应用与窗口管理 |
HypiumDriver / HYPIIUM_CATALOG | hypium 全部 118 个方法的封装,以及它们的状态清单 |
Gesture | 宿主侧手势构造器:start / moveTo / pause |
Policy / Approvals / Lease | 标签策略、一次性或记住的审批、每设备租约 |
TraceRecorder | 逐步 JSONL trace 与 HTML 报告 |
CommandRunner / COMMANDS | 命令层;CLI 与 MCP 共用同一张表 |
McpServer / toolDefinitions | stdio JSON-RPC 服务与工具定义 |
DevicePool | 多设备连接池 |
installSkill() / skillFiles() | 随包 Skill 的安装 |
doctor() / deviceTagOf(id) | 能力探测;设备序列号的 8 位哈希 |
VERSION | 从 package.json 读出的版本号 |
11. 错误码
所有错误继承 UitestError,带 code 与可选 cause。
| 类 | 典型 code | 触发条件 |
|---|---|---|
DeviceNotConnectedError | ENODEVICE / ENOHDC / EHDC / EDISPOSED | 没有设备、找不到 hdc、hdc 命令失败、Device 已 dispose |
ExtensionMissingError | ENOEXT / ENOCAST | 本地没有对应 ABI 的 agent.so;x86_64 上请求录制 |
DaemonStartError | ENODAEMON / EPORT / ENOSOCKET / ENORECORD | daemon 拉不起来、端口耗尽、投流 socket 没出现、录制文件没出现 |
AgentProtocolError | EPROTO / ETIMEDOUT / EBADJSON / ENOWINDOW / ENOBOUNDS / EBADARG | 设备返回异常、请求超时、输出不是 JSON、找不到窗口/边界、参数非法 |
AgentBusyError | EBUSY | 全局锁被其它进程占着且重试耗尽;或该设备已有采集流(立即失败) |
AgentConnectionError | ECONN | 连接不可用、请求超时后连接被丢弃、关闭后继续调用 |
12. 并发与生命周期
- 一条连接一个在途请求:
SerialQueue串行化;断开后autoRestart用新 socket 重连,不重放失败中的请求。 - 全局锁冲突:只有
Disallow concurrent use会退避重试(0.5 s 起,抖动后翻倍,最多 40 次,20 s 封顶)。 - 采集冲突:设备同一时刻只允许一条采集流。
Capture already running立刻抛AgentBusyError,不会等、不会抢占。 - daemon 归属:只认本次连接前后新增的、且只有一个的 pid;
ownDaemon: true时才会在dispose()杀掉它。 - 超时即断连:请求超时后连接被丢弃,下一次调用走重连。
- 退出前
dispose():撤销 fport,否则本地会留下隧道。
13. 完整示例
点击、滑动与输入
const { width, height } = await dev.agent.getDisplaySize();
await dev.agent.click(width / 2, height / 2);
await dev.agent.swipe(width / 2, height * 0.8, width / 2, height * 0.2, { durationMs: 200 });
await dev.agent.inputText(width / 2, height * 0.5, "hello");
只截一个应用窗口
const jpeg = await dev.agent.cropToWindow({ bundleName: "com.huawei.hmos.settings" });
投流并解码
const cast = await dev.createCast({ mode: "stream", frameRate: 30 });
try {
for await (const chunk of cast.stream()) {
if ("isKeyFrame" in chunk && chunk.isKeyFrame) {
// H.264 Annex-B:从这里开始送解码器
}
}
} finally {
await cast.dispose();
}
录制 10 秒
const cast = await dev.createCast({ mode: "record", frameRate: 30, outputPath: "demo.mp4" });
await new Promise((r) => setTimeout(r, 10_000));
await cast.dispose();
多设备并行
const ids = ["<device-a>", "<device-b>"];
const devices = await Promise.all(ids.map((deviceId) => Device.connect({ deviceId })));
try {
await Promise.all(devices.map((d) => d.agent.click(100, 100)));
} finally {
await Promise.all(devices.map((d) => d.dispose()));
}