更新日志

每个公开版本的主要迭代。完整 API 见 使用文档。

0.8.0

2026-11-16 截图与录屏、多实例

live 页多了两个按钮

  • 页头 Shot 存一张 JPEG 到 <state-dir>/shots/,走的是 Session.observe({ out }),所以遮罩规则和节点表同一套——文字里藏起来的密码在像素里也是灰块。
  • 页头 Record 录 MP4 到同一目录。它另起一个 record daemon(gRPC 用自己的 socket,WebSocket 用端口 +1),画面不停;同一时间只有一个录屏,页面关掉时正在录的那个会被停掉并写盘。
  • CastOptions.durationMs 现在真的生效:到点自动停止(关 muxer、拉回文件、杀 daemon),不设则由调用方决定何时 dispose()。

同一台设备可以开多个页面

  • 每个 live 进程用自己的 socket 名(uitest_live_<pid>),互不覆盖。
  • daemon 归因改用 ps -ef 的 argv 精确匹配,不再靠「启动前后 pidof 的差集」。原来两个页面同时启动时,各自看到 2 个新进程、各自失败重试、并把对方刚起的 daemon 杀掉,实测陷入活锁并堆出 8 个进程。
  • 租约的同名 task 重入现在要求 pid 相同。原来只要 task 名一样就算重入,于是两个进程都能拿到设备——这正是租约要防的并发驱动。人的 hold 是例外:它没有所属进程(hold 写完就退出,人在另一个 shell 里才 resume),所以按「有没有人持机」判重入。第一版漏了这一条,真机验收时 resume 放不掉租约。

修掉两处静默失败

  • hdc file recv 失败时退出码仍是 0,只在 stdout 打 [Fail]Error opening file。原来把退出码当成功,录屏的 dispose() 解析了而调用方没有文件。现在会读状态行并抛错。
  • 拉文件失败时不再跳过 daemon 与端口的清理:一个失败的传输正是最容易留下孤儿进程的时候。

测试与 CI

  • test/ 与 scripts/ 纳入类型检查(tsconfig.test.json),CI 的 test job 跑它。此前 rootDir 只覆盖 src,测试文件从未被检查过,积了 27 处错误。
  • CI 在部署前先跑单元测试(原来只在 prepublishOnly 里跑,坏提交能直接到 master)。

0.7.1

2026-11-16 投屏解码修复

修掉两种「连着但黑屏」

  • 不再写死 hardwareAcceleration: 'prefer-hardware'。它是硬要求不是偏好:没有 GPU 解码的机器上 isConfigSupported() 返回 false、configure() 抛 OperationError,一帧都出不来(实测 30 帧里 0 帧)。现在交给浏览器挑,只有默认配置被拒时才重试一次软解,并在提示条上写明。
  • 解码中途出错后能自己恢复。原来只把解码器置空并请求关键帧,却没有人再开一个解码器,之后每一帧都被丢掉、那个 IDR 请求也没有接收方——画面永久卡住(实测卡在第 20 帧)。现在会记住最近一次 hello,出错时立刻重开解码器再请求关键帧(实测恢复到第 40 帧)。

官网补上传输与解码的对比

  • 新增「传输与解码,到底谁更快」一节,含三条链路的对比图。
  • 逐行读了 hscrcpy、HOScrcpy、HarmonyMirror 的实现:前两个都是 FFmpeg 软解(hscrcpy 的 README 写「硬解」,源码里没有任何 hwaccel 代码),HarmonyMirror 用 VideoToolbox 但中间夹一层 Python 桥接。
  • 实测我们的每帧成本:转封装 12 µs、解码 1.57 ms(1216×2688 硬解)、绘制 0.07 ms,约占 33 ms 预算的 5%。瓶颈在设备侧编码器,三家一样。

0.7.0

2026-11-16 投屏与实时检查

投屏:给人在浏览器里看

  • 新增 uitest-sdk live:一个本地页面同时给出画面和节点表。点节点(或点画面上的框)复制它的 ref、角色、标签与中心坐标,编号与 tap --ref 共用;JSON 按钮复制整条节点。
  • 解码全在浏览器:H.264 走 WebCodecs VideoDecoder,服务端把设备侧的 Annex-B 转成 AVCC 并把 SPS/PPS 拼成 avcC 作为 description;没有 MSE、没有 fMP4 重封装、没有额外缓冲层。
  • 解码器由浏览器挑:不指定硬件加速,有 GPU 走硬解、没有就软解;默认配置被拒时再显式重试一次软解,并在页面上说明。解码中途出错会重开解码器并请求关键帧,画面能自己恢复。
  • x86_64 没有编码器,走 MJPEG:同一页面用 createImageBitmap 画整帧 JPEG,不需要解码器配置或重同步。
  • SDK 侧是 LiveServer:LiveServer.start({ source: { createCast, readScreen } }),readScreen 省略就是只投屏的页面。

隐私开关:默认打开

  • 密码框与验证码在节点表和画面上都被遮住;关掉后服务端用 redact: false 重新读布局,原文才出现 —— 遮罩在读的时候完成,不是事后擦除。
  • 多个页面同时连着时,只要有一个还开着遮罩,共享的屏幕模型就保持遮罩;新开的页面从不继承别人关掉的开关。
  • 开关不会让 ref 重编号:ScreenBuilder.setRedact() 只换渲染,签名与编号不变。

状态机、重连与背压

  • idle → starting → live → reconnecting → stopping → stopped;失败从任意状态进入 failed,之后按 0.5/1/2/4/5 s 退避重启。重复断言当前状态是 no-op,未声明的转移直接抛错。
  • 页面重载有 5 s 宽限期:宽限期内重新连上就继续出流,不重开投流 daemon(实测重载后没有 starting)。
  • 背压按 socket 写队列:超过 1 MB 丢增量帧并请求 IDR(250 ms 内至多一次),队列回落到一半时只在关键帧上恢复;页面侧 decodeQueueSize > 4 时同样丢增量帧。
  • 只把带 IDR 切片的帧标成关键帧。6.8 扩展开场那一帧只有 SPS/PPS 却被标成 keyframe,WebCodecs 会直接拒绝(marked as type key but wasn't a key frame)—— 这是实测中发现并修掉的。

实测

  • 真机 BRA-AL00,1216×2688,--fps 30:连接后首帧约 3.1 s(含 daemon 启动),画面持续变化时页面绘制 18.5 fps,帧间隔中位 33 ms、p90 55 ms,每帧平均 11.6 KB。
  • MJPEG 路径(400×800 合成源)同一页面 22 fps,像素与源一致。
  • 页面无外部依赖:单文件 HTML,没有 CDN、没有构建步骤,离线可用。

0.6.0

2026-11-16 7.0 WebSocket 投流

可选的 WebSocket 传输

  • 新增 createCast({ transport: "ws" }):走 7.0 扩展的 RFC6455 通道,客户端不再需要 gRPC 运行时。帧率与 6.8 持平(真机实测 20.8–23.2 fps),首帧 82–137 ms,requestIDR 7–9 ms。
  • wsExtension 指向本地的 7.0 .so;SDK 按文件名推到 /data/local/tmp,与内置的 6.8 扩展同时存在、互不覆盖。port 选设备侧端口(默认 5000)。
  • 传输是显式选择的:要 ws 却没给 wsExtension,或设备是 x86_64(没有 7.0 构建),直接抛 ExtensionMissingError,不会静默退回 gRPC。
  • SDK 不打包 7.0 二进制(来源与再分发条款见 能力差异文档 §1.6)。

实测推翻的三条旧结论

  • 多实例有边界:同一 daemon 上两个客户端能同时出流,但 stop 是进程级的 —— 任一客户端 stop,另一路立刻停;stop 后监听 socket 关闭,新客户端连不上。并发只能靠多个端口、各自一个 daemon。
  • 7.0 的 cpd 收不到:格式串在二进制里,但 10 s、195 帧、三种命令顺序都没触发过。不要靠它初始化解码器。
  • 静止画面两个版本都录不到帧:8 s 不动屏,6.8 和 7.0 都是 259 B 空文件。「7.0 muxer 持续写帧」是错的。另外 7.0 在 start 时就建好 259 B 的头,样本到 stop 才落盘,所以拉取前必须等文件大小稳定。

0.5.0

2026-11-16 完整 hypium API

完整 hypium API:118 个方法

  • 新增 dev.hypium(HypiumDriver):把 hypium 6.1.0.210 的 OHOSDriver 106 个方法与兼容层 12 个方法逐个铺平成 TypeScript 驼峰方法,参数与返回值都有类型。
  • 位置参数统一为 Target:绝对坐标、屏幕比例 [0.5, 0.5]、矩形、On 选择器或已解析的 ComponentHandle 可以互换。
  • 按动作选注入通道:单指手势、PointerMatrix 多指、鼠标/笔 Driver RPC、组件侧动作(Component.click 等)。
  • HYPIIUM_CATALOG 导出 118 条映射(hypium 原名 → TS 名 → 分类 → 状态);单元测试核对它与门面一一对应。
  • 真机逐条实测(BRA-AL00 / uitest 7.0.0.1):106 verified、4 device、3 hardware、5 unsupported。不可用的路径抛 UnsupportedError,不会挂起到超时。
  • 新增官网独立页面 完整 API:118 条方法表、参数说明、分类示例与四张调用路径图,由 catalog 生成。

实测中发现并修掉的三个缺陷

  • isDisplayLocked() 在解锁状态下报 true:hidumper 表格按空白切分会把字段名与值拆开,改为逐行读第二个字段。
  • pushFile() 用相对路径时在设备上建出一个同名目录:hdc file send 需要绝对路径,改为先 resolve()。
  • setDisplayRotation() 传字符串被设备拒绝:类型收窄为 0 | 1 | 2 | 3,错误信息说明设备只收整数。

0.4.0

2026-11-16 脱敏、设备状态与审批

凭据在屏幕上也会被遮住

  • 密码框的值显示为 ••••••;凭据语境中的 3–8 位数字(验证码、PIN、CVV)显示为等长圆点,前后的词保留,策略仍能分类。
  • observe、动作后的 diff、read-list、screenshot、--trace-shots 与 report 共用同一份脱敏后的屏幕;截图的对应区域盖成灰色。
  • 被遮住的元素无法再按原文找到:tap --text 482913 返回 not_found,Agent 只能请人接手。
  • 策略与脱敏使用同一套凭据词表;低层 agent.captureLayout() / captureScreen() 仍返回设备原样数据。

设备状态也有名字

  • 新增 device_locked、device_needs_setup、device_offline 三个状态,退出码统一为 2:Agent 一看就知道该请人解锁、点「允许 USB 调试」,还是插线,而不是重试同一条命令。
  • 锁屏识别放在屏幕模型里(锁屏 bundle / ScreenLockWidget):observe 不再把锁屏当成一个可点的页面,动作命令在碰设备之前就以 device_locked 停下。
  • 连接阶段改读 hdc list targets -v:Unauthorized 报 device_needs_setup,Offline 或没有目标报 device_offline;多目标时优先选 Connected 的那台。

同一条审批可以记住

  • --approval-id 兑现时加 --approval-scope task(本任务内这个应用的这条规则不再问)或 always(这个 state dir 的所有任务都不再问);默认 once,只兑现这一步。
  • 记住的授权按 rule + bundle 匹配,存在 grants-<hash>.json;它只跳过审批这一项检查,凭据、--read-only 与 --apps 白名单仍然生效。
  • resume 清掉 task 范围的授权:人接管后批准它的上下文已经不在,Agent 要继续就得重新问;always 是人的长期决定,保留。
  • 审批状态的提示语直接教 Agent 用这两个 flag;status 列出当前记住的授权。

升级后 Skill 自己跟上

  • 安装 Skill 时在目录里写 .uitest-skill.json:包名、版本与两个文件的摘要。
  • mcp 启动前检查:包已升级、且副本仍是本包写的那份,就地把 SKILL.md / REFERENCE.md 更新到当前版本,不用重跑 install-skill --force。
  • 人改过的副本(摘要不符)与手写的 Skill(没有记录)不动;0.3.0 装的副本按发布时的精确摘要识别后接管,老用户也能自动升级。
  • 刷新失败不会阻止 MCP server 启动;已经是最新版本时启动没有任何额外输出。

更多 Agent 一步接好

  • connect --agent gemini 写 ~/.gemini/settings.json 的 mcpServers;--agent copilot 写 ~/.copilot/mcp-config.json,条目按 Copilot CLI 自己的 schema 带 type: "local" 与 tools: ["*"]。
  • 四家 Agent 共用同一条「只改自己那一项」的写入路径:注释、键顺序、邻居排版不动,已经正确时零写入;Agent 目录不存在时创建,不再因缺少父目录而失败。
  • Gemini 不写 trust:逐次工具确认保持默认,审批仍由本包自己的策略层负责。

0.3.0

2026-11-16 默认值、接管与交接

四处功能修改,都来自「默认值不该替人放行」这一条:Agent 能做的动作更安全,人也能随时把手机拿回来。

删除与发送默认要审批

  • 默认审批集从「支付、金融」扩到「支付、金融、删除、发送」——这四类是 Agent 做了、人收不回来的事。
  • commits(确认 / 保存)仍不默认:手机上半数普通表单按钮都叫这个,每次都问会把人训练成不看就点同意。
  • 与之前的 --read-only 失效同类:默认值放行了人不会希望 Agent 自主执行的动作。

人可以随时接管

  • uitest-phone hold 把设备租约写成 "held by a person" 后退出;Agent 命令随后以 lease_held(退出码 2)停下。
  • 可以抢走正在运行的任务,包括整个进程只持一次租约的 mcp 会话:任务在下一条命令前发现租约没了,不会在动作中途被打断。
  • resume 交还;只释放 hold,别的任务的租约不碰;同一个 Agent 会话下一条命令自动重新取得设备,不用重启。
  • hold 不按进程存活判断,所以不会自己过期,也没有命令能把它抢回去。
  • 实测:hold 之后一条 Agent 命令 2.3 s 退出 2,提示「A person is using the phone. Stop and wait; they will run uitest-phone resume.」;MCP 会话在 hold 期间的工具调用返回 lease_held,resume 后下一条恢复 settled。
  • 设备侧的 UI 事件流不可用于判断「人在动手机」:会关掉会话、能把 daemon 卡死,且合成点击也被当成手指。所以接管是人的明确声明。

Agent 可以请人接手

  • uitest-phone handoff --reason "请登录后继续"(MCP 工具 uitest_handoff)把手机交给人并立即返回 handoff(退出码 2):Agent 遇到登录、验证码、解锁这类只有人能做的一步时,不再猜或试图绕开。
  • 原因写进租约,之后每个拿到 lease_held 的命令都会重复它;人做完后 resume,同一个 Agent 会话下一条命令自动继续。
  • 与 hold 是同一条租约、同一个 resume:不做两套状态机。真机实测 MCP 会话 handoff → 同一会话 lease_held → resume → settled。

一步接好 Agent

  • uitest-phone connect 把 MCP 注册直接写进 Agent 自己的设置文件,只改自己那一项;注释、键顺序、其它 server 的排版原样保留,已经正确时零写入。
  • 支持 claude(~/.claude.json)与 codex(~/.codex/config.toml)。文件解析失败就拒绝并报出偏移,不替人重写。
  • 入口写成本包绝对路径 + 当前 node:从 Dock / 开始菜单启动的 Agent 看不到终端 PATH。
  • install-skill 同时写 ~/.claude/skills 与 ~/.agents/skills(agentskills.io 跨 runtime 别名),一次覆盖 Claude Code、Codex、Copilot CLI、Gemini CLI。

修复

  • lease_held 的退出码一直是 1:Session.open 在命令执行前抛错,而错误分支统一返回 1。现在按错误类型映射为 2。
  • 被 hold 的设备上,命令要挂 60 s 才被杀死:Session.open 失败时设备连接没关,进程不退出。现在立即释放并退出 2。
  • hold 不生效:租约按 pid 判断存活,而写租约的命令早已退出,下一条 Agent 命令立刻把设备抢回去。新增 hold 标记跳过存活判断。

0.2.0

2026-11-16 命令行与 Agent

SDK 之上多了一层给人和 Agent 用的命令行:每条命令开一次设备、执行一步、等 UI 稳定、打印屏幕或 diff、释放设备。同一套命令既走 CLI,也走 MCP。SDK 的公开接口只增不改,0.1.0 的代码不用改。

命令行

  • 19 条命令:observe、tap、type、swipe、double-click、drag、fling、pinch、key、wait-for、read-list、scroll-until、launch、apps、window、doctor、screenshot、report、status。
  • 实测端到端:status 1.2 s、apps --current 1.5 s、observe 1.7 s、doctor 1.9 s、tap --ref 2.3 s(含 Node 启动与设备打开)。
  • 屏幕模型:每行一个元素,带 ref、角色、标签、中心点与状态;动作后打印 diff。
  • 设备侧稳定:动作后先 Driver.waitForIdle,再由 host 轮询两次相同哈希,超时记为 uncertain 而不是抛错。
  • 退出码即结果:0 settled、1 uncertain/not_found、2 lease held、3 待审批、4 被拒。

跨进程状态

  • ref 表存在 <state-dir>/refs-<hash>.json:observe 打印的 ref 在下一条 tap 里仍指向同一元素;不在当前屏幕就 not_found,绝不悄悄指向别的控件。
  • 审批 id 存在 <state-dir>/approvals-<hash>.json:一次性、10 分钟 TTL、绑定命令与目标签名;页面变了返回 stale。
  • 报告按 task 把各进程写的 trace 读回来,跨文件重新编号,覆盖整轮任务——包括 apps、launch 这类不走屏幕动作的命令。
  • 设备序列号在任何文件与输出里都只以 8 位哈希出现。

安全

  • 策略层按标签分类:凭据类永久拦截,支付与金融默认需要人工审批,--confirm 可把删除/发送/确认也纳入。
  • 审批由 CLI 自己校验,不是靠提示词约束 Agent。
  • 一台设备一个任务:第二个任务在碰设备之前拿到 lease_held。
  • 被强杀的客户端会在 daemon 上留下 CLOSE_WAIT 死连接并永久锁住设备;connect() 只在没有任何活连接时才重启 agent daemon。

Agent 接入

  • npx uitest-sdk mcp:stdio 上以 JSON-RPC 2.0 暴露 uitest_<command>,整个进程只开一次设备。
  • npx uitest-sdk install-skill:把随包发布的 Skill 写进 Agent 的 skills 目录,命令与二进制永远同版本。
  • --trace-shots 每步存截图,报告里的链接相对报告自身,截图与 HTML 可整体搬走。

SDK 新增(兼容)

  • Session、ScreenReader、Components、Gestures、AppManager、Policy、Approvals、Lease、TraceRecorder、DevicePool 全部导出。
  • Device 新增 readonly hdc 与 readonly deviceId;原有成员与方法签名不变。
  • isBusyException 参数放宽为 unknown(设备 1.2.x 会把异常发成对象),新增 exceptionText()。

修复

  • --read-only 之前从未生效:布尔 flag 以 kebab-case 存、以 camelCase 读,被静默丢弃。
  • 报告里的截图链接指向文件系统路径,浏览器打不开;改为相对报告目录的正斜杠路径。
  • 同一毫秒创建的两个 trace 记录器文件名相同,后者会截断前者的文件。
  • apps、launch、doctor 之前完全不进 trace,报告漏掉改变应用的那一步。

工程

  • npm 包 919.4 kB / 84 个文件,新增 dist/bin.js 与随包 Skill;SDK 运行时导出 81 个。
  • 335 个单元测试;--version 与 MCP 握手都从 package.json 读版本,不再有第二处字面量。

0.1.0

2026-11-15 首个公开版本

把鸿蒙 uitest 扩展封装成 Node.js SDK:一条长连接做 UI 自动化,一条 gRPC 通道做投流与录制。发布到 npm,官网与文档同步上线。

传输与生命周期

  • 一条 TCP 长连接(agent.so,8012)承载全部 UI 请求,串行队列 + 指数退避。
  • 自动按 ABI 推送 agent.so 与 libscreen_casting.z.so;缺失时才推送。
  • 多实例安全:复用已监听的 daemon,只杀自己拉起的那个;ownDaemon 显式控制。
  • 断线后下一次调用自动重连,失败中的请求不重放;超时即断连。

UI 自动化

  • 点击、原子触摸、三段式滑动、文本输入、按键、UI 事件流。
  • 实测:点击 8–30 ms(中位 9 ms),滑动 389–395 ms,整屏截图 109–222 ms。
  • 对比 hdc CLI:点击 59.0×、滑动 6.9×、截图 4.5×。

截图与 UI 树

  • captureScreen():起停采集流取首帧,608×1344 JPEG 直接是字节。
  • cropToWindow():整屏采集 + 按节点 bounds 裁剪,弥补设备没有窗口级截图。
  • captureLayout() 整屏树快于 dumpLayout + pull;后者保留用于窗口过滤。
  • 对比 snapshot_display:agent MJPEG 178–212 ms vs 675–684 ms,快 3.2–3.8×。

投流与录制

  • H.264 over gRPC(6.8 casting),实测 15–89 fps,支持 15/30/60/120 目标帧率。
  • x86_64 模拟器显式走 MJPEG(10–16 fps),不假装支持 H.264。
  • MP4 录制:设备侧编码器直接写文件,dispose() 关闭 muxer 并拉回;使用 casting -m 1 路径。

工程

  • npm 包 840.8 kB / 38 个文件,含三个签名扩展、docs/api.md 与可运行示例。
  • prepublishOnly 强制 build + 85 个单元测试;npm test 不碰设备。
  • 真机验收 16/16 PASS;官网零外部请求,视频 1920×1080 / 30 s。
  • Node.js ≥ 20,ESM,TypeScript 类型随包发布。

0.0.0-stage

2026-11-15 npm 占位

npm 分阶段发布(staged publishing)为新包名预留的占位版本,描述为 “Temporary package placeholder for staged publishing”。它不包含代码,也不是可安装的功能版本;安装 uitest-sdk 时 latest 指向 0.1.0。

计划中

未发布 · 不是承诺
  • live 页的点击交互:画布上点一下等于在设备上点一下。要先定清楚它与租约、接管的规则——页面开着期间 live 进程持有设备租约,点击天然是「持租约的人」在操作,但页面必须把这件事说出来。
  • perfmonitor.so(HTTP 9999)性能指标接入。
  • 录制参数在设备侧可配置(目前文件路径写死在扩展里)。
  • 音频转发:需要自建 HAP 采集,得用使用者自己的华为账号签名。
  • 接管期间的线性「人的操作」时间线(captureLayout 轮询写 JSONL;uiRecord 与 daemon 互斥,不可用)。

版本节奏以实测为准:每个版本都会更新本页、README 与 npm 包内文档。