android2harmony 0.1.6 → 0.1.8

package/skills/a2h-spec-implement/scripts/device_ui_core.mjs

@@ -0,0 +1,895 @@
+// device_ui_core.mjs — HarmonyOS device UI driver core (hypium-driver backend, single shared implementation).
+//
+// All entry points share this module; logic is written once:
+//   device_ui.mjs   CLI (one-shot + serve daemon): args + single-line JSON stdout contract
+//   test/l2_run.mjs L2 e2e runner: in-process calls (no per-step subprocess round-trip)
+// All intelligence is host-side (dump JSON → active layer → selector match → coordinate action);
+// hypium-driver is a dumb "fetch tree + inject" channel; the device-side agent is the official uitest channel.
+//
+// No-console-window rule: every spawn/spawnSync uses windowsHide:true; the daemon stays resident with a
+// hidden console (CREATE_NO_WINDOW semantics), inherited by its children (hdc etc.) — no cmd popups, ever.
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { getKey } from "./_lib/config.mjs";
+import { HMOS_SKIP_TYPES as SKIP_TYPES, HMOS_SKIP_BUNDLES as SKIP_BUNDLES } from "./_lib/common.mjs";
+
+// --------------------------------------------------------------------------
+// stdout discipline: hypium-driver may log to stdout, polluting the single-line JSON contract.
+// Entry processes call captureStdout() before importing the driver: real stdout is reserved for emit; everything else is rerouted to stderr.
+// --------------------------------------------------------------------------
+let _realWrite = null;
+export function captureStdout() {
+  if (_realWrite) return;
+  _realWrite = process.stdout.write.bind(process.stdout);
+  process.stdout.write = (chunk, enc, cb) => process.stderr.write(chunk, enc, cb);
+  console.log = (...a) => console.error(...a);
+}
+export function writeStdoutLine(s) {
+  (_realWrite || process.stdout.write.bind(process.stdout))(s + "\n");
+}
+export function warn(msg) {
+  try { process.stderr.write(`[device_ui] ${msg}\n`); } catch { /* ignore */ }
+}
+
+export class DeviceUIError extends Error {
+  // Expected selector/argument errors: one-shot maps to fail(), daemon/l3 to an error dict (process keeps running)
+  constructor(reason, extra = {}) { super(reason); this.reason = reason; this.extra = extra; }
+}
+
+// --------------------------------------------------------------------------
+// hdc lookup and invocation: prefer PATH, else derive from conf.yaml DEVECO_PATH/DEVECO_SDK_HOME.
+// The driver talks to the hdc server (TCP 8710) instead of spawning hdc; one `hdc list targets`
+// run both locates the binary and starts the hdc server — called before connect.
+// --------------------------------------------------------------------------
+const HDC_NAMES = os.platform() === "win32" ? ["hdc.exe", "hdc"] : ["hdc"];
+function dirHasHdc(d) {
+  try { return HDC_NAMES.some((n) => fs.statSync(path.join(d, n)).isFile()); } catch { return false; }
+}
+export function ensureHdcOnPath() {
+  const sep = path.delimiter;
+  for (const d of (process.env.PATH || "").split(sep)) if (d && dirHasHdc(d)) return true;
+  const deveco = getKey("DEVECO_PATH", "");
+  const sdk = getKey("DEVECO_SDK_HOME", "") || (deveco ? path.join(deveco, "sdk") : "");
+  const cands = [];
+  if (sdk) {
+    try {
+      for (const sub of fs.readdirSync(sdk)) cands.push(path.join(sdk, sub, "openharmony", "toolchains"));
+    } catch { /* sdk missing */ }
+    cands.push(path.join(sdk, "openharmony", "toolchains"));
+  }
+  if (deveco) cands.push(path.join(deveco, "tools", "hdc"));
+  for (const d of cands.sort()) {
+    if (dirHasHdc(d)) { process.env.PATH = d + sep + (process.env.PATH || ""); return true; }
+  }
+  return false;
+}
+export function hdcRun(device, args, timeoutMs = 15000) {
+  // Every hdc subprocess goes through here: windowsHide pinned (no-console-window rule)
+  const full = [...(device ? ["-t", device] : []), ...args];
+  return spawnSync("hdc", full, {
+    encoding: "utf8", timeout: timeoutMs, windowsHide: true,
+  });
+}
+
+// --------------------------------------------------------------------------
+// view tree parsing (dumpLayout emits JSON)
+// --------------------------------------------------------------------------
+// SKIP_TYPES / SKIP_BUNDLES (HarmonyOS system-UI denylist) are single-sourced in _lib/common.mjs,
+// imported above — edit the denylist there, not here.
+
+export function parseXyBounds(s) {
+  const nums = (s || "").match(/-?\d+/g);
+  if (!nums || nums.length !== 4) return null;
+  const [x1, y1, x2, y2] = nums.map(Number);
+  return [[x1, y1, x2, y2], [Math.floor((x1 + x2) / 2), Math.floor((y1 + y2) / 2)]];
+}
+
+export function collectElements(tree, includeAll, includeBound = false) {
+  const out = [];
+  const walk = (node) => {
+    const a = node.attributes || {};
+    const t = a.type || "", bundle = a.bundleName || "";
+    if (SKIP_TYPES.has(t) || SKIP_BUNDLES.has(bundle)) {
+      for (const c of node.children || []) walk(c);
+      return;
+    }
+    const bc = parseXyBounds(a.bounds || "");
+    const text = a.text || "", desc = a.description || "", key = a.key || "";
+    const clickable = a.clickable === "true";
+    const scrollable = a.scrollable === "true";
+    if (includeAll || text || desc || clickable || scrollable) {
+      const e = { type: t, text, center: bc ? bc[1] : null, clickable };
+      if (includeBound && bc) e.bound = bc[0]; // [x1,y1,x2,y2] exact pixel box (for geometry comparators)
+      if (desc) e.desc = desc;
+      if (key) e.key = key;
+      if (scrollable) e.scrollable = true;
+      // State attributes, sparsely exposed: only non-default values appear (saves tokens) — fills assertion blind spots
+      if (a.checked === "true") e.checked = true;
+      if (a.selected === "true") e.selected = true;
+      if (a.focused === "true") e.focused = true;
+      if (a.enabled === "false") e.enabled = false;
+      out.push(e);
+    }
+    for (const c of node.children || []) walk(c);
+  };
+  walk(tree);
+  return out;
+}
+
+// Interactive overlays (Dialog/Sheet/Popup/Menu). ArkUI overlay stack: push appends as the last sibling under root; last-in shows on top
+const OVERLAY_TYPES = ["Dialog", "Sheet", "Popup", "Menu"];
+
+export function resolveActiveLayer(tree) {
+  // Active surface = topmost overlay subtree (last in document order, no overlay ancestor); else the whole page
+  const tops = [];
+  const walk = (node, hasAnc) => {
+    const t = (node.attributes || {}).type || "";
+    const isOverlay = OVERLAY_TYPES.some((k) => t.includes(k));
+    if (isOverlay && !hasAnc) tops.push(node);
+    for (const c of node.children || []) walk(c, hasAnc || isOverlay);
+  };
+  walk(tree, false);
+  return tops.length ? [tops[tops.length - 1], tops.length] : [tree, 0];
+}
+
+// --------------------------------------------------------------------------
+// Selectors (host-side matching; single source of truth shared with observe)
+// Precedence: exact text > contains substring > regex > starts > ends > key > desc > type
+// --------------------------------------------------------------------------
+const SELECTOR_KEYS = ["text", "contains", "regex", "starts", "ends", "key", "desc", "type"];
+
+export function hasSelector(opts) {
+  return SELECTOR_KEYS.some((k) => opts[k] != null);
+}
+export function selectorDesc(opts) {
+  for (const k of SELECTOR_KEYS) if (opts[k] != null) return `${k}=${JSON.stringify(opts[k])}`;
+  return null;
+}
+export function matches(e, opts) {
+  const txt = e.text || "";
+  if (opts.text != null) return txt === opts.text;
+  if (opts.contains != null) return txt.includes(opts.contains);
+  if (opts.regex != null) { try { return new RegExp(opts.regex).test(txt); } catch { throw new DeviceUIError(`非法正则: ${opts.regex}`); } }
+  if (opts.starts != null) return txt.startsWith(opts.starts);
+  if (opts.ends != null) return txt.endsWith(opts.ends);
+  if (opts.key != null) return (e.key || "") === opts.key;
+  if (opts.desc != null) return (e.desc || "") === opts.desc;
+  if (opts.type != null) return (e.type || "") === opts.type;
+  return true;
+}
+
+async function dumpTree(d) {
+  // Dump the current ui-tree to a temp file, parse and return (for tap/input resolution, not persisted; observe writes its own ui_tree.json)
+  const p = path.join(fs.mkdtempSync(path.join(os.tmpdir(), "uitree_")), "tree.json");
+  try {
+    await d.dumpLayout(p);
+    return JSON.parse(fs.readFileSync(p, "utf8"));
+  } finally {
+    try { fs.rmSync(path.dirname(p), { recursive: true, force: true }); } catch { /* ignore */ }
+  }
+}
+
+export async function resolveOne(d, opts, action, includeBound = false) {
+  // Selector → single target element (with center).
+  // Native fast path (~43ms vs ~900ms full host tree dump, 30x; closes on-device, no host tree walk):
+  //   a unique findComponents hit yields the center directly. 0/≥2 hits/desc/--nth/bound needed →
+  //   fall back to the authoritative host path (miss confirmation, active-layer disambiguation +
+  //   ghost filtering, bound extraction) — most of the win without losing correctness.
+  //   The narrow edge case (unique hit on a background ghost under an overlay) is caught by the pipeline's per-step expect gate.
+  const desc = selectorDesc(opts);
+  if (desc == null) throw new DeviceUIError(`${action} 需要选择器(--text/--contains/--regex/--starts/--ends/--key/--desc/--type)或 --xy`);
+  if (!includeBound && opts.desc == null && opts.nth == null) {
+    try {
+      const comps = (await d.findComponents(byFromSelector(d.__pkg, opts))) || [];
+      if (comps.length === 1) {
+        const c = await comps[0].getBoundsCenter();
+        return [{ center: [c.x ?? c.width, c.y ?? c.height] }, desc];
+      }
+      // 0 or ≥2 → fall back to host (authoritative: confirm miss / active-layer disambiguation / ghost filtering / list candidates)
+    } catch (e) { if (e instanceof DeviceUIError) { /* byFromSelector rejects desc; fall back to host */ } /* native RPC errors also fall back to host */ }
+  }
+  const [scope] = resolveActiveLayer(await dumpTree(d));
+  const cands = collectElements(scope, true, includeBound).filter((e) => matches(e, opts) && e.center);
+  if (!cands.length) {
+    throw new DeviceUIError(`选择器未命中(活跃层): ${desc}`, {
+      hint: "先 observe 看屏幕,或换选择器/用 --xy(--raw observe 看全树)" });
+  }
+  if (cands.length > 1 && opts.nth == null) {
+    const info = cands.slice(0, 10).map((c) => ({ text: c.text, center: c.center, clickable: c.clickable }));
+    throw new DeviceUIError(`命中 ${cands.length} 个: ${desc}`, { candidates: info, hint: "加 --nth N(0 起)" });
+  }
+  const idx = opts.nth || 0;
+  if (idx >= cands.length) throw new DeviceUIError(`--nth ${idx} 越界,仅 ${cands.length} 个命中`);
+  return [cands[idx], desc];
+}
+
+// --------------------------------------------------------------------------
+// hypium-driver loading (lazy: pure-hdc commands like devices/density don't need it)
+//
+// Resolution order mirrors a2h-integration-test's batch_runner lookup:
+//   1. bare specifier — repo dev copy, after `npm install` under scripts/
+//   2. global npm root — `<root>/hypium-driver`, imported by absolute file URL
+//      (a bare specifier only walks up node_modules from this file, so it can
+//      never see a global install)
+//   3. `npm install -g hypium-driver@<range from scripts/package.json>`, then retry 2
+//
+// Step 3 is what makes the plugin edition work at all: shipped inside DevEco Code the
+// scripts live under node_modules/@deveco-test/deveco-code/vendor/android2harmony/skills/…,
+// where there is no node_modules ancestor to resolve from and no sane place to
+// `npm install` in situ (a reinstall of the host wipes it). The plugin therefore keeps
+// `dependencies` empty and the driver self-heals into the global root at first use.
+// --------------------------------------------------------------------------
+const DRIVER_PKG = "hypium-driver";
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+// Global npm root(s) where `npm install -g` places packages.
+let _globalRootsCache = null;
+function globalNodeModulesRoots() {
+  if (_globalRootsCache) return _globalRootsCache;
+  const roots = new Set();
+  try {
+    const r = spawnSync("npm", ["root", "-g"], { encoding: "utf-8", timeout: 15000, windowsHide: true, shell: true });
+    const p = (r.stdout || "").trim();
+    if (r.status === 0 && p) roots.add(p);
+  } catch { /* npm not on PATH or timed out — fall through to the heuristics */ }
+  // Heuristic fallbacks in case `npm root -g` is unavailable.
+  const home = os.homedir();
+  if (process.platform === "win32") {
+    if (process.env.APPDATA) roots.add(path.join(process.env.APPDATA, "npm", "node_modules"));
+  } else {
+    roots.add("/usr/local/lib/node_modules");
+    roots.add("/usr/lib/node_modules");
+    roots.add(path.join(home, ".npm-global", "lib", "node_modules"));
+  }
+  _globalRootsCache = [...roots].filter(Boolean);
+  return _globalRootsCache;
+}
+
+// The pinned range lives in scripts/package.json — sole source of truth, so the
+// auto-install can never drift to a `latest` that lacks a fix we depend on.
+//
+// The version reaches the command line through `shell: true` (unavoidable: since
+// CVE-2024-27980 Node refuses to spawn a `.cmd` — which is what npm is on Windows —
+// without a shell), so cmd.exe gets a crack at it: `^` is cmd's escape character and
+// `|` / `&` in a range like `^6 || ^7` would be read as operators. Only a bare semver
+// is therefore allowed through; anything else degrades to the unversioned package name
+// (npm resolves `latest`) rather than handing metacharacters to the shell.
+const SEMVER_EXACT = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+function driverInstallSpec() {
+  let range = "";
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(HERE, "package.json"), "utf-8"));
+    range = ((pkg.dependencies && pkg.dependencies[DRIVER_PKG]) || "").trim();
+  } catch { /* unreadable package.json — install unversioned */ }
+  // `^6.1.210` / `~6.1.210` / `=6.1.210` → `6.1.210`; a real multi-comparator range → dropped.
+  const pinned = range.replace(/^[\^~=v\s]+/, "");
+  return SEMVER_EXACT.test(pinned) ? `${DRIVER_PKG}@${pinned}` : DRIVER_PKG;
+}
+
+// Absolute entry file of a package dir, per its package.json (exports["."] → main → index.js).
+function packageEntry(dir) {
+  let pkg;
+  try { pkg = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf-8")); } catch { return ""; }
+  const pick = (v) => {
+    if (typeof v === "string") return v;
+    if (v && typeof v === "object") return pick(v.import || v.module || v.require || v.default || v.node);
+    return "";
+  };
+  const rel = pick(pkg.exports && pkg.exports["."] !== undefined ? pkg.exports["."] : pkg.exports) || pkg.main || "index.js";
+  const abs = path.join(dir, rel);
+  return fs.existsSync(abs) ? abs : "";
+}
+
+function resolveDriverEntry() {
+  for (const root of globalNodeModulesRoots()) {
+    const entry = packageEntry(path.join(root, DRIVER_PKG));
+    if (entry) return entry;
+  }
+  return "";
+}
+
+function installDriverGlobally() {
+  const spec = driverInstallSpec();
+  warn(`hypium-driver 未找到,自动安装(npm install -g ${spec})...`);
+  try {
+    const r = spawnSync("npm", ["install", "-g", spec], {
+      encoding: "utf-8", timeout: 180000, windowsHide: true, shell: true, stdio: ["ignore", "pipe", "pipe"],
+    });
+    if (r.status === 0) { warn(`hypium-driver 安装完成: ${spec}`); return { ok: true, detail: "" }; }
+    const tail = ((r.stderr || "") + (r.stdout || "")).trim().slice(-400);
+    warn(`npm install 退出码=${r.status}: ${tail}`);
+    return { ok: false, detail: tail };
+  } catch (e) {
+    const detail = String(e.message || e).slice(0, 300);
+    warn(`npm install 异常: ${detail}`);
+    return { ok: false, detail };
+  }
+}
+
+let _pkg = null;
+async function loadDriverPkg() {
+  if (_pkg) return _pkg;
+  // 1. bare specifier (repo dev copy with scripts/node_modules)
+  try { _pkg = await import(DRIVER_PKG); return _pkg; } catch { /* not resolvable from here — try the global root */ }
+  // 2. global npm root
+  let entry = resolveDriverEntry();
+  let install = null;
+  // 3. auto-install, then re-resolve (drop the cache: the install may have created the root)
+  if (!entry) {
+    install = installDriverGlobally();
+    _globalRootsCache = null;
+    entry = resolveDriverEntry();
+  }
+  if (!entry) {
+    throw new DeviceUIError(
+      install && !install.ok
+        ? `hypium-driver 自动安装失败(可能是网络或全局目录权限);请手动执行 \`npm install -g ${driverInstallSpec()}\`(Node ≥20.11.1)`
+        : `npm install 报告成功但 hypium-driver 仍未定位到;请检查 npm 全局目录(\`npm root -g\`)权限或路径`,
+      { detail: (install && install.detail) || "" });
+  }
+  try {
+    _pkg = await import(pathToFileURL(entry).href);
+  } catch (e) {
+    throw new DeviceUIError(`hypium-driver 加载失败: ${entry}`, { detail: String(e.message || e).slice(0, 200) });
+  }
+  return _pkg;
+}
+
+export async function connect(device, workDir) {
+  ensureHdcOnPath();
+  hdcRun(device, ["list", "targets"], 10000); // also starts the hdc server (driver uses TCP 8710)
+  const pkg = await loadDriverPkg();
+  // Runtime artifacts (daemon.json/calls.jsonl/ui_tree etc.) are confined to <work-dir>/.hypium/
+  let wd = workDir;
+  if (!wd) {
+    wd = fs.mkdtempSync(path.join(os.tmpdir(), "device_ui_"));
+    warn(`未传 --work-dir:运行杂物落到 ${wd}(传 --work-dir 可让它们随本次运行落盘)`);
+  }
+  const base = path.join(wd, ".hypium");
+  fs.mkdirSync(base, { recursive: true });
+  try { process.chdir(base); } catch { /* a bad dir must not block connect */ }
+  const caps = device ? { deviceSn: device } : {};
+  const driver = await pkg.UiDriver.connect(caps);
+  driver.__pkg = pkg; // carry KeyCode etc. constants with the driver so the action layer avoids re-imports
+  return driver;
+}
+
+export async function disconnect(d) {
+  try { await d.disconnect(); } catch { /* best-effort release */ }
+}
+
+// --------------------------------------------------------------------------
+// Device self-heal: clear accumulated forwards → wake + keep-awake + start uitest singleton.
+// (Known daemon leftovers are handled by device_ui.mjs killDaemonByPid via pid; no separate engine seizes the device.)
+// --------------------------------------------------------------------------
+export function cleanStaleFport(device) {
+  // hypium opens a new local tcp→device uitest port forward per connection and never reclaims it; stale = remote contains "uitest" or ≥3 forwards to the same remote
+  try {
+    const out = hdcRun(device, ["fport", "ls"]);
+    const rows = [], remoteCount = {};
+    for (const line of (out.stdout || "").split(/\r?\n/)) {
+      const eps = line.split(/\s+/).filter((t) => t.startsWith("tcp:") || t.startsWith("localabstract:"));
+      if (eps.length >= 2) {
+        rows.push([eps[0], eps[1]]);
+        remoteCount[eps[1]] = (remoteCount[eps[1]] || 0) + 1;
+      }
+    }
+    for (const [local, remote] of rows) {
+      if (remote.includes("uitest") || remoteCount[remote] >= 3) {
+        hdcRun(device, ["fport", "rm", local, remote], 10000);
+      }
+    }
+  } catch { /* best-effort */ }
+}
+
+export function warmDevice(device) {
+  // Wake + keep screen on (an override, undone by restoreScreenTimeout at session end) + start
+  // uitest singleton daemon: OSBase init hoisted to once per session
+  for (const tail of [["shell", "power-shell", "wakeup"],
+                      ["shell", "power-shell", "timeout", "-o", "86400000"],
+                      ["shell", "uitest", "start-daemon", "singleness"]]) {
+    try { hdcRun(device, tail); } catch { /* best-effort */ }
+  }
+}
+
+export function restoreScreenTimeout(device) {
+  // Undo warmDevice's screen-off override (power-shell keeps the pre-override value itself; -r
+  // restores it). Crash paths may leave the override; the next warm/restore cycle clears it.
+  try { hdcRun(device, ["shell", "power-shell", "timeout", "-r"]); } catch { /* best-effort */ }
+}
+
+export function selfHealDevice(device) {
+  cleanStaleFport(device);
+  warmDevice(device);
+}
+
+export async function connectWithReclaim(device, workDir) {
+  try {
+    return await connect(device, workDir);
+  } catch (first) {
+    if (first instanceof DeviceUIError) throw first; // missing-dependency class; self-heal won't help
+    selfHealDevice(device);
+    await new Promise((r) => setTimeout(r, 2000));
+    try {
+      return await connect(device, workDir);
+    } catch (again) {
+      throw new DeviceUIError("连接设备失败:已清残留持有者 + 预热 uitest 仍无法连接(息屏/无设备/agent 异常)。"
+        + `重试错误: ${String(again.message || again).slice(0, 160)};首错: ${String(first.message || first).slice(0, 160)}`);
+    }
+  }
+}
+
+// --------------------------------------------------------------------------
+// Pure hdc commands (no driver connection)
+// --------------------------------------------------------------------------
+export function doDevices() {
+  ensureHdcOnPath();
+  const p = hdcRun(null, ["list", "targets"], 15000);
+  if (p.error) return { ok: false, error: "hdc 不在 PATH(且无法由 conf.yaml 的 DEVECO_PATH 定位);无法枚举设备" };
+  if (p.status !== 0) return { ok: false, error: `hdc list targets 失败(rc=${p.status}): ${(p.stderr || "").trim().slice(0, 300)}` };
+  const devs = (p.stdout || "").split(/\r?\n/).map((l) => l.trim()).filter((l) => l && !l.includes("Empty"));
+  return { ok: true, devices: devs, count: devs.length };
+}
+
+export function probeDensity(device) {
+  // px↔vp scale factor (= densityDPI/160): from the "Density:" line of hidumper DisplayManagerService
+  ensureHdcOnPath();
+  try {
+    const out = hdcRun(device, ["shell", "hidumper", "-s", "DisplayManagerService", "-a", "-a"], 15000);
+    const m = /Density:\s*([\d.]+)/.exec(out.stdout || "");
+    if (m) return parseFloat(m[1]);
+  } catch { /* best-effort */ }
+  return null;
+}
+
+// --------------------------------------------------------------------------
+// Action layer (pure functions: driver d + opts → result dict; shared by one-shot/daemon/l3)
+// --------------------------------------------------------------------------
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+export async function displaySize(d) {
+  const v = await d.getDisplaySize();
+  return [v.x ?? v.width, v.y ?? v.height];
+}
+async function currentAppArr(d) {
+  const s = await d.currentApp(); // "bundle/ability"
+  const i = String(s).indexOf("/");
+  return i >= 0 ? [s.slice(0, i), s.slice(i + 1)] : [String(s), ""];
+}
+
+export function resolveOut(opts) {
+  // observe/screenshot output dir: never cwd. Absolute -o as-is; relative joins --work-dir; default <work-dir>/.hypium/; neither → temp dir + warning
+  const out = opts.out, wd = opts.workDir;
+  if (out) {
+    if (path.isAbsolute(out)) return path.normalize(out);
+    if (wd) return path.normalize(path.join(wd, out));
+    const td = fs.mkdtempSync(path.join(os.tmpdir(), "device_ui_obs_"));
+    warn(`observe/screenshot 收到相对 -o ${JSON.stringify(out)} 且无 --work-dir,落到临时目录 ${td}`);
+    return td;
+  }
+  if (wd) return path.normalize(path.join(wd, ".hypium"));
+  const td = fs.mkdtempSync(path.join(os.tmpdir(), "device_ui_obs_"));
+  warn(`observe/screenshot 未传 -o 且无 --work-dir,ui_tree/screenshot 落到临时目录 ${td}`);
+  return td;
+}
+
+function probeMainAbility(device, bundle) {
+  // Probe the main ability via bm dump (the driver's startApp auto-match fails for some apps; observed with com.xuncorp.sp)
+  try {
+    const out = hdcRun(device, ["shell", `bm dump -n ${bundle}`], 15000);
+    const m = /"mainElement"\s*:\s*"([^"]+)"/.exec(out.stdout || "")
+      || /"mainAbility"\s*:\s*"([^"]+)"/.exec(out.stdout || "");
+    return m ? m[1] : null;
+  } catch { return null; }
+}
+
+export async function doLaunch(d, opts) {
+  if (opts.restart) {
+    try { await d.stopApp(opts.bundle); } catch (e) { warn(`restart 时 stopApp 失败(继续启动): ${String(e.message || e).slice(0, 160)}`); }
+    await sleep(500);
+  }
+  try {
+    await d.startApp(opts.bundle, opts.ability || undefined);
+  } catch (e) {
+    const ability = !opts.ability && probeMainAbility(opts.device, opts.bundle);
+    if (!ability) throw e;
+    warn(`startApp 自动匹配失败,按 bm dump mainElement 重试: ${ability}`);
+    await d.startApp(opts.bundle, ability);
+  }
+  await sleep(1200);
+  return { ok: true, action: "launch", bundle: opts.bundle, current_app: await currentAppArr(d) };
+}
+
+export async function doObserve(d, opts) {
+  const outDir = resolveOut(opts);
+  fs.mkdirSync(outDir, { recursive: true });
+  const treePath = path.normalize(path.join(outDir, "ui_tree.json"));
+  await d.dumpLayout(treePath);
+  const tree = JSON.parse(fs.readFileSync(treePath, "utf8"));
+  const [active, overlays] = resolveActiveLayer(tree);
+  const scope = opts.raw ? tree : active;
+  const includeBound = !!opts.bound;
+  const actionable = collectElements(scope, !!opts.all, includeBound);
+  const density = includeBound ? probeDensity(opts.device) : null;
+  const result = {
+    ok: true, current_app: await currentAppArr(d), display_size: await displaySize(d),
+    count: actionable.length, dialog: overlays > 0, tree_file: treePath,
+  };
+  if (density != null) result.density = density;
+  if (overlays >= 2) result.overlays = overlays; // multi-overlay "transitioning" frame; keep evidence for tiebreak review
+  let elements;
+  if (hasSelector(opts)) {
+    elements = collectElements(scope, true, includeBound).filter((e) => matches(e, opts));
+    result.find = selectorDesc(opts);
+    result.matched = elements.length;
+  } else {
+    elements = actionable;
+  }
+  if (opts.limit != null && elements.length > opts.limit) {
+    result.truncated = elements.length;
+    elements = elements.slice(0, opts.limit);
+  }
+  result.elements = elements;
+  if (opts.screenshot) {
+    const shot = path.normalize(path.join(outDir, "screenshot.jpeg"));
+    result.screenshot = await d.screenCap(shot);
+  }
+  return result;
+}
+
+export async function doTap(d, opts) {
+  if (opts.xy) {
+    await d.click(opts.xy[0], opts.xy[1]);
+    return { ok: true, action: "tap", center: opts.xy };
+  }
+  const [el, desc] = await resolveOne(d, opts, "tap");
+  await d.click(el.center[0], el.center[1]);
+  return { ok: true, action: "tap", matched: desc, center: el.center };
+}
+
+export async function doDoubleTap(d, opts) {
+  if (opts.xy) {
+    await d.doubleClick(opts.xy[0], opts.xy[1]);
+    return { ok: true, action: "double-tap", center: opts.xy };
+  }
+  const [el, desc] = await resolveOne(d, opts, "double-tap");
+  await d.doubleClick(el.center[0], el.center[1]);
+  return { ok: true, action: "double-tap", matched: desc, center: el.center };
+}
+
+export async function doLongPress(d, opts) {
+  let center = opts.xy, desc;
+  if (!center) { const [e, dd] = await resolveOne(d, opts, "long-press"); center = e.center; desc = dd; }
+  const [x, y] = center;
+  if (opts.pressMs) {
+    // longClickAt's duration param fails over RPC on agent v1.1.9 (observed); same-point swipeHold gives a controllable duration
+    await d.swipeHold(x, y, x, y, 600, opts.pressMs);
+  } else {
+    await d.longClickAt({ x, y });
+  }
+  return { ok: true, action: "long-press", ...(desc ? { matched: desc } : {}), center,
+           ...(opts.pressMs ? { press_ms: opts.pressMs } : {}) };
+}
+
+export async function doInput(d, opts) {
+  let center = opts.xy, desc;
+  if (!center) { const [e, dd] = await resolveOne(d, opts, "input"); center = e.center; desc = dd; }
+  await d.inputText({ x: center[0], y: center[1] }, opts.value);
+  return { ok: true, action: "input", ...(desc ? { matched: desc } : {}), center, value: opts.value };
+}
+
+export async function doSwipe(d, opts) {
+  if (opts.from && opts.to) { // exact two-point swipe
+    await d.swipe(opts.from[0], opts.from[1], opts.to[0], opts.to[1], opts.speed || undefined);
+    return { ok: true, action: "swipe", from: opts.from, to: opts.to };
+  }
+  const [w, h] = await displaySize(d);
+  // Directional: full-screen area + percent (distance is a 0-100 percentage, default 60)
+  const percent = Math.min(1, Math.max(0.05, (opts.distance ?? 60) / 100));
+  await d.Screen.swipe(0, 0, w, h, opts.dir, percent, opts.speed || 5000);
+  return { ok: true, action: "swipe", dir: opts.dir };
+}
+
+export async function doDrag(d, opts) {
+  if (!opts.from || !opts.to) throw new DeviceUIError("drag 需要 --from X Y 与 --to X Y(选择器由调用方先 observe 解析为坐标)");
+  await d.drag(opts.from[0], opts.from[1], opts.to[0], opts.to[1], opts.speed || undefined);
+  return { ok: true, action: "drag", from: opts.from, to: opts.to };
+}
+
+export async function doFling(d, opts) {
+  const [w, h] = await displaySize(d);
+  await d.Screen.fling(0, 0, w, h, opts.dir, opts.speed || 7500);
+  return { ok: true, action: "fling", dir: opts.dir };
+}
+
+export async function doPinch(d, opts) {
+  let area = opts.area; // [x1,y1,x2,y2]
+  if (!area && hasSelector(opts)) {
+    const [el] = await resolveOne(d, opts, "pinch", true);
+    if (!el.bound) throw new DeviceUIError("pinch 目标元素无 bound(不可作捏合区域)");
+    area = el.bound;
+  }
+  if (!area) { // default: center half of the screen
+    const [w, h] = await displaySize(d);
+    area = [Math.floor(w / 4), Math.floor(h / 4), Math.floor((3 * w) / 4), Math.floor((3 * h) / 4)];
+  }
+  const [x1, y1, x2, y2] = area;
+  const percent = opts.scale ?? 0.5, speed = opts.speed || 2500;
+  const fn = opts.mode === "out" ? "pinchOpen" : "pinchClose";
+  await d.Screen[fn](x1, y1, x2 - x1, y2 - y1, percent, speed);
+  return { ok: true, action: "pinch", mode: opts.mode, area, scale: percent };
+}
+
+export async function doKey(d, opts) {
+  const pkg = d.__pkg || {};
+  let name;
+  if (opts.back) { await d.pressBack(); name = "Back"; }
+  else if (opts.home) { await d.pressHome(); name = "Home"; }
+  else if (opts.power) { await d.pressKey(pkg.KeyCode?.POWER ?? 18); name = "Power"; }
+  else if (opts.combo) { await d.triggerCombineKeys(...opts.combo); name = `combo:${opts.combo.join("+")}`; }
+  else if (opts.code != null) { await d.pressKey(opts.code); name = `code:${opts.code}`; }
+  else throw new DeviceUIError("key 需要 --back/--home/--power/--code/--combo");
+  return { ok: true, action: "key", name };
+}
+
+export async function doRotate(d, opts) {
+  const map = { 0: 0, 90: 1, 180: 2, 270: 3 };
+  const rot = map[opts.deg];
+  if (rot == null) throw new DeviceUIError("rotate 需要 --deg 0|90|180|270");
+  await d.Screen.setDisplayRotation(rot);
+  return { ok: true, action: "rotate", deg: opts.deg };
+}
+
+// --------------------------------------------------------------------------
+// By-path actions (clear-text/scroll-until need a device-side component handle, so they use the
+// official By — the sole exemption from the dump main path; uniqueness guard via findComponents count)
+// --------------------------------------------------------------------------
+function byFromSelector(pkg, opts) {
+  const { BY, MatchPattern } = pkg;
+  if (opts.text != null) return BY.text(opts.text);
+  if (opts.contains != null) return BY.text(opts.contains, MatchPattern.CONTAINS);
+  if (opts.regex != null) return BY.text(opts.regex, MatchPattern.REGEXP);
+  if (opts.starts != null) return BY.text(opts.starts, MatchPattern.STARTS_WITH);
+  if (opts.ends != null) return BY.text(opts.ends, MatchPattern.ENDS_WITH);
+  if (opts.key != null) return BY.key(opts.key);
+  if (opts.type != null) return BY.type(opts.type);
+  if (opts.desc != null) throw new DeviceUIError("该动作走设备侧 By 寻址,node 版 By 无 description 匹配器——换 --text/--key/--type");
+  throw new DeviceUIError("需要选择器(--text/--contains/--regex/--starts/--ends/--key/--type)");
+}
+
+async function findUniqueComponent(d, opts, action) {
+  const by = byFromSelector(d.__pkg, opts);
+  const comps = (await d.findComponents(by)) || [];
+  if (!comps.length) throw new DeviceUIError(`选择器未命中(By): ${selectorDesc(opts)}`,
+    { hint: "先 observe 看屏幕,或换选择器" });
+  if (comps.length > 1 && opts.nth == null) {
+    throw new DeviceUIError(`命中 ${comps.length} 个: ${selectorDesc(opts)}`, { hint: "加 --nth N(0 起)" });
+  }
+  const idx = opts.nth || 0;
+  if (idx >= comps.length) throw new DeviceUIError(`--nth ${idx} 越界,仅 ${comps.length} 个命中`);
+  return comps[idx];
+}
+
+export async function doClearText(d, opts) {
+  const comp = await findUniqueComponent(d, opts, "clear-text");
+  await comp.clearText();
+  return { ok: true, action: "clear-text", matched: selectorDesc(opts) };
+}
+
+export async function doScrollUntil(d, opts) {
+  // Scroll until target visible: container (default = first scrollable container).scrollSearch(target)
+  const pkg = d.__pkg;
+  const targetBy = byFromSelector(pkg, opts);
+  let container;
+  if (opts.containerKey != null || opts.containerType != null) {
+    container = await findUniqueComponent(d,
+      { key: opts.containerKey, type: opts.containerType, nth: opts.containerNth }, "scroll-until.container");
+  } else {
+    const cands = (await d.findComponents(pkg.BY.scrollable(true))) || [];
+    if (!cands.length) throw new DeviceUIError("scroll-until: 屏上无可滚动容器");
+    container = cands[opts.containerNth || 0];
+    if (!container) throw new DeviceUIError(`scroll-until: --container-nth 越界,仅 ${cands.length} 个容器`);
+  }
+  let found;
+  try {
+    found = await container.scrollSearch(targetBy);
+  } catch (e) { // driver throws "Fail to resolve object [ScrollSearchComp…]" on not-found (observed); translate to a stable error
+    if (String(e.message || e).includes("ScrollSearchComp")) found = null;
+    else throw e;
+  }
+  if (!found) throw new DeviceUIError(`scroll-until 滚完未命中: ${selectorDesc(opts)}`,
+    { hint: "确认目标文字存在于该滚动容器内" });
+  const c = await found.getBoundsCenter();
+  return { ok: true, action: "scroll-until", matched: selectorDesc(opts), center: [c.x ?? c.width, c.y ?? c.height] };
+}
+
+export async function doGesture(d, opts) {
+  // Custom trajectories (single/multi finger): tracks = [[{x,y,ms?}|[x,y,ms?], ...], ...]; first point of each track is down, the rest move_to
+  const pkg = d.__pkg;
+  const tracks = opts.tracks;
+  if (!Array.isArray(tracks) || !tracks.length || !tracks.every((t) => Array.isArray(t) && t.length >= 2)) {
+    throw new DeviceUIError("gesture 需要 tracks:每轨 ≥2 个点,形如 [[[x,y,ms?],…],…]");
+  }
+  const actions = tracks.map((track) => {
+    const pa = new pkg.PointAction(opts.samplingMs || undefined);
+    track.forEach((p, i) => {
+      const pt = Array.isArray(p) ? { x: p[0], y: p[1], ms: p[2] } : p;
+      if (i === 0) pa.down({ x: pt.x, y: pt.y }, pt.ms || undefined);
+      else pa.move_to({ x: pt.x, y: pt.y }, pt.ms || undefined);
+    });
+    return pa;
+  });
+  const payload = actions.length === 1 ? actions[0] : pkg.PointAction.mergeMultiPointAction(actions);
+  await d.injectMultiPointerAction(payload, opts.speed || undefined);
+  return { ok: true, action: "gesture", tracks: tracks.length,
+           points: tracks.reduce((n, t) => n + t.length, 0) };
+}
+
+// --------------------------------------------------------------------------
+// Extended commands (round out the hypium-driver capability surface; the agent can only use what's exposed as a command)
+// A) Driver-backed (need driver d; registered in ACTIONS)
+// --------------------------------------------------------------------------
+export async function doWaitIdle(d, opts) {
+  // Wait for the UI to settle (returns after idle_ms without refresh, or on timeout).
+  // Default idle 1000ms — smaller values RPC-flake (measured; the contract warns against <1000).
+  await d.waitForIdle((opts.idleMs ?? 1000) / 1000, (opts.timeoutMs ?? 10000) / 1000);
+  return { ok: true, action: "wait-idle", idle_ms: opts.idleMs ?? 1000 };
+}
+
+export async function doUnlock(d) {
+  await d.wakeUpDisplay();
+  const locked = await d.isDisplayLocked().catch(() => null);
+  if (locked !== false) await d.unlock();
+  return { ok: true, action: "unlock", was_locked: locked };
+}
+
+export async function doWake(d) {
+  await d.wakeUpDisplay();
+  return { ok: true, action: "wake", display_on: await d.isDisplayOn().catch(() => null) };
+}
+
+export async function doInfo(d, opts) {
+  // Device/screen info in one call. Every probe is timeout-raced: on a flaky channel a driver
+  // RPC can hang (never rejects) — that must degrade the field to null, not hang the whole
+  // command (measured 2min+ per hang). displaySize included: it was the un-guarded first await.
+  const g = (p, fb = null) => Promise.race([p.catch(() => fb), sleep(8000).then(() => fb)]);
+  const [w, h] = await g(displaySize(d), [null, null]);
+  return { ok: true, action: "info",
+    device_type: await g(d.getDeviceType()), model: await g(d.getDeviceModel()),
+    api_level: await g(d.getApiLevel()), system_version: await g(d.getSystemVersion()),
+    display_size: [w, h], density: probeDensity(opts.device),
+    rotation: await g(d.getDisplayRotation()), display_on: await g(d.isDisplayOn()),
+    display_locked: await g(d.isDisplayLocked()) };
+}
+
+const RESIZE_DIR = { left: 0, right: 1, up: 2, down: 3, "left-up": 4, "left-down": 5, "right-up": 6, "right-down": 7 };
+
+export async function doWindow(d, opts) {
+  // Find a window (--bundle/--title/--focused; default = currently focused) and optionally apply a window op (multi-window/PC)
+  const filter = {};
+  if (opts.wbundle != null) filter.bundleName = opts.wbundle;
+  if (opts.title != null) filter.title = opts.title;
+  filter.focused = opts.focused != null ? opts.focused : (opts.wbundle == null && opts.title == null);
+  const win = d.findWindow(filter);
+  if (!(await win.exist?.().catch(() => true)) && win.exist) throw new DeviceUIError("window 未命中(换 --bundle/--title/--focused)");
+  const g = async (p) => p.catch(() => null);
+  if (opts.wop === "resize") await win.resize(opts.w, opts.h, RESIZE_DIR[opts.dir ?? "right-down"] ?? 7);
+  else if (opts.wop === "maximize") await win.maximize();
+  else if (opts.wop === "minimize") await win.minimize();
+  else if (opts.wop === "close") await win.close();
+  else if (opts.wop === "focus") await win.focus();
+  else if (opts.wop === "move") await win.moveTo(opts.x, opts.y);
+  const b = await g(win.getBounds());
+  return { ok: true, action: "window", op: opts.wop || "info",
+    bundle: await g(win.getBundleName()), bounds: b ? [b.left ?? b.x, b.top ?? b.y, b.right ?? (b.x + b.width), b.bottom ?? (b.y + b.height)] : null,
+    focused: await g(win.isFocused()), active: await g(win.isActive()) };
+}
+
+export async function doRecord(d, opts) {
+  // Screen recording start/stop (daemon only: start and stop are two separate calls, the driver session must stay alive)
+  if (opts.rop === "start") { await d.Screen.startRecordingScreen(); return { ok: true, action: "record", op: "start" }; }
+  if (opts.rop === "stop") {
+    const outDir = resolveOut(opts);
+    fs.mkdirSync(outDir, { recursive: true });
+    const mp4 = path.normalize(path.join(outDir, "record.mp4"));
+    await d.Screen.stopRecordingScreen({ mp4 });
+    return { ok: true, action: "record", op: "stop", path: mp4 };
+  }
+  throw new DeviceUIError("record 需要 --op start 或 --op stop");
+}
+
+export async function doLaunchUri(d, opts) {
+  // Implicit launch by action/uri
+  await d.startAppImplicit(opts.uaction || undefined, opts.uri || undefined, opts.extra || undefined);
+  await sleep(1200);
+  return { ok: true, action: "launch-uri", current_app: await currentAppArr(d) };
+}
+
+export async function doApp(d, opts) {
+  // Thin app-management wrapper (install/uninstall/clear/info/running)
+  if (opts.aop === "info") return { ok: true, action: "app", op: "info", info: await d.getAppInfo(opts.bundle) };
+  if (opts.aop === "running") return { ok: true, action: "app", op: "running", running: await d.isAppRunning(opts.bundle) };
+  if (opts.aop === "install") { await d.installApp(opts.path); return { ok: true, action: "app", op: "install", path: opts.path }; }
+  if (opts.aop === "uninstall") { await d.uninstallApp(opts.bundle); return { ok: true, action: "app", op: "uninstall", bundle: opts.bundle }; }
+  if (opts.aop === "clear") { await d.clearAppData(opts.bundle); return { ok: true, action: "app", op: "clear", bundle: opts.bundle }; }
+  throw new DeviceUIError("app 需要 --op info/running/install/uninstall/clear");
+}
+
+// --------------------------------------------------------------------------
+// B) Pure hdc (no driver needed; CLI/daemon run these before connecting, skipping connect overhead)
+// --------------------------------------------------------------------------
+export function doShell(opts) {
+  ensureHdcOnPath();
+  const out = hdcRun(opts.device, ["shell", opts.cmd], (opts.timeoutMs ?? 60000));
+  if (out.error) return { ok: false, error: `hdc 不可用: ${out.error.message}` };
+  return { ok: out.status === 0 || out.status == null, action: "shell",
+    stdout: (out.stdout || "").trim(), stderr: (out.stderr || "").trim() || undefined, rc: out.status };
+}
+
+export function doHdc(opts) {
+  ensureHdcOnPath();
+  const out = hdcRun(opts.device, opts.args || [], (opts.timeoutMs ?? 60000));
+  if (out.error) return { ok: false, error: `hdc 不可用: ${out.error.message}` };
+  return { ok: out.status === 0 || out.status == null, action: "hdc",
+    stdout: (out.stdout || "").trim(), stderr: (out.stderr || "").trim() || undefined, rc: out.status };
+}
+
+export function doHilog(opts) {
+  // Snapshot the current hilog buffer (hilog -x dumps and exits, non-blocking); supports --grep filter + --lines cap.
+  // The pipeline's hilog-marker collection relies on this (snapshot right after an action, grep the marker).
+  ensureHdcOnPath();
+  const out = hdcRun(opts.device, ["shell", "hilog", "-x"], (opts.timeoutMs ?? 30000));
+  if (out.error) return { ok: false, error: `hdc 不可用: ${out.error.message}` };
+  let lines = (out.stdout || "").split(/\r?\n/);
+  if (opts.grep) { try { const re = new RegExp(opts.grep); lines = lines.filter((l) => re.test(l)); } catch { lines = lines.filter((l) => l.includes(opts.grep)); } }
+  const n = opts.lines ?? 200;
+  const matched = lines.length;
+  return { ok: true, action: "hilog", grep: opts.grep, matched, lines: lines.slice(-n) };
+}
+
+export function doToast(opts) {
+  // Toast detection (hypium-driver has no Toast API; grep toast events from a hilog snapshot — best-effort, OS-version dependent).
+  ensureHdcOnPath();
+  const out = hdcRun(opts.device, ["shell", "hilog", "-x"], (opts.timeoutMs ?? 30000));
+  if (out.error) return { ok: false, error: `hdc 不可用: ${out.error.message}` };
+  const re = /toast/i;
+  const hits = (out.stdout || "").split(/\r?\n/).filter((l) => re.test(l));
+  return { ok: true, action: "toast", note: "best-effort via hilog(无原生 Toast API)",
+    matched: hits.length, lines: hits.slice(-30) };
+}
+
+export function doFile(opts) {
+  // Device file transfer (hdc file send/recv; cheaper for one-shots than driver.pushFile)
+  ensureHdcOnPath();
+  if (opts.fop === "push") {
+    const out = hdcRun(opts.device, ["file", "send", opts.local, opts.remote], (opts.timeoutMs ?? 60000));
+    return { ok: out.status === 0, action: "file", op: "push", local: opts.local, remote: opts.remote, out: (out.stdout || out.stderr || "").trim() };
+  }
+  if (opts.fop === "pull") {
+    const out = hdcRun(opts.device, ["file", "recv", opts.remote, opts.local], (opts.timeoutMs ?? 60000));
+    return { ok: out.status === 0, action: "file", op: "pull", remote: opts.remote, local: opts.local, out: (out.stdout || out.stderr || "").trim() };
+  }
+  throw new DeviceUIError("file 需要 --op push 或 --op pull");
+}
+
+// Pure hdc command set (no driver; CLI/daemon run these before connect)
+export const HDC_ACTIONS = { shell: doShell, hdc: doHdc, hilog: doHilog, toast: doToast, file: doFile };
+
+// Action dispatch table (needs driver; shared by daemon and l3; CLI one-shot uses the same table)
+export const ACTIONS = {
+  launch: doLaunch, observe: doObserve, tap: doTap, "double-tap": doDoubleTap,
+  "long-press": doLongPress, input: doInput, "clear-text": doClearText, swipe: doSwipe,
+  drag: doDrag, fling: doFling, pinch: doPinch, "scroll-until": doScrollUntil,
+  gesture: doGesture, key: doKey, rotate: doRotate,
+  "wait-idle": doWaitIdle, unlock: doUnlock, wake: doWake, info: doInfo,
+  window: doWindow, record: doRecord, "launch-uri": doLaunchUri, app: doApp,
+};
+
+export async function runAction(d, cmd, opts) {
+  const fn = ACTIONS[cmd];
+  if (!fn) throw new DeviceUIError(`不支持的命令: ${cmd}`);
+  return fn(d, opts);
+}