devhelmkit 0.1.0__py3-none-any.whl

devhelmkit/harmony/driver.py

@@ -0,0 +1,1416 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""HarmonyDriver：鸿蒙平台驱动门面。
+
+编排 HdcDevice（设备通道）、RpcClient（RPC 通信）、ComponentFinder
+（控件查找）三层能力，对用户暴露 U2 风格 API。
+
+仅支持 HarmonyOS 5.0.0+（API 12+），设备端 uitest 服务统一使用
+api9+ 命名（Driver/Component/On）。
+"""
+from __future__ import annotations
+
+import json
+import re
+import shlex
+import time
+from typing import Any, Dict, List, Optional, Tuple, Union, TYPE_CHECKING
+
+from devhelmkit.core.base_driver import BaseDriver
+from devhelmkit.core.selector_spec import SelectorSpec, build_selector
+from devhelmkit.exceptions import DevhelmError, DevhelmTimeoutError
+from devhelmkit.harmony.config import HarmonyDriverConfig
+from devhelmkit.harmony.device.hdc import HdcDevice
+from devhelmkit.harmony.finder.component_finder import ComponentFinder, DRIVER_REF
+from devhelmkit.harmony.rpc.client import RpcClient
+from devhelmkit.harmony.uiobject import UiObject
+from devhelmkit.harmony.uiwindow import UiWindow
+from devhelmkit.model.input import GestureAction, InputDevice
+from devhelmkit.model.keys import KeyCode
+from devhelmkit.utils import logger
+
+if TYPE_CHECKING:
+    from PIL.Image import Image
+    from devhelmkit.core.base_component import BaseComponent
+    from devhelmkit.core.base_window import BaseWindow
+
+# 语义按键 → KeyCode 映射
+_KEY_MAP = {
+    'back': KeyCode.BACK,
+    'home': KeyCode.HOME,
+    'power': KeyCode.POWER,
+    'volume_up': KeyCode.VOLUME_UP,
+    'volume_down': KeyCode.VOLUME_DOWN,
+    'menu': KeyCode.MENU,
+    'enter': KeyCode.ENTER,
+    'escape': KeyCode.ESCAPE,
+    'delete': KeyCode.DEL,
+    'tab': KeyCode.TAB,
+    'space': KeyCode.SPACE,
+}
+
+# 不支持的 uitest 版本
+_UNSUPPORTED_UITEST_VERSIONS = {"4.1.3.2"}
+
+# 控件属性名 → 设备端 RPC 方法名映射
+_PROPERTY_METHOD_MAP = {
+    "id": "getId",
+    "text": "getText",
+    "key": "getKey",
+    "type": "getType",
+    "enabled": "isEnabled",
+    "focused": "isFocused",
+    "clickable": "isClickable",
+    "scrollable": "isScrollable",
+    "checked": "isChecked",
+    "checkable": "isCheckable",
+    "description": "getDescription",
+    "selected": "isSelected",
+    "bounds": "getBounds",
+}
+
+
+class HarmonyDriver(BaseDriver):
+    """鸿蒙平台驱动门面。"""
+
+    def __init__(self, serial: str,
+                 config: Optional[HarmonyDriverConfig] = None,
+                 **config_kwargs):
+        self._config = HarmonyDriverConfig.from_input(config, config_kwargs)
+        # 应用 hdc 路径配置（全局生效，影响所有后续 HdcDevice 实例）
+        if self._config.hdc_path and self._config.hdc_path != "hdc":
+            HdcDevice.set_hdc_path(self._config.hdc_path)
+        self._device = HdcDevice(serial)
+        self._setup_device()
+        self._rpc = RpcClient(self._device)
+        self._finder = ComponentFinder(self._rpc, self._config)
+        self._implicit_wait: float = 10.0
+        self._closed = False
+        self._toast_observer: Optional[str] = None
+        self._toast_listening: bool = False
+        self._ui_event_observer: Optional[str] = None
+        self._ui_event_listening: bool = False
+
+    # ============================================================
+    # 生命周期
+    # ============================================================
+
+    def close(self, stop_daemon: Optional[bool] = None) -> None:
+        """关闭驱动，释放 RPC 对象、socket 与端口转发。
+
+        Args:
+            stop_daemon: 是否停止设备端 uitest 守护进程。
+                None 时取 config.stop_daemon_on_close（默认 False）。
+                True 强制停止；False 强制保留。
+        """
+        if self._closed:
+            return
+        self._closed = True
+        try:
+            self._rpc.remote_objects.release_all()
+        except Exception:
+            pass
+        if stop_daemon is None:
+            stop_daemon = self._config.stop_daemon_on_close
+        self._device.close(stop_daemon=stop_daemon)
+
+    @property
+    def device_sn(self) -> str:
+        return self._device.serial
+
+    @property
+    def platform(self) -> str:
+        return "harmony"
+
+    # ============================================================
+    # 设备信息
+    # ============================================================
+
+    @property
+    def info(self) -> Dict[str, Any]:
+        """设备基本信息（品牌、型号、系统版本等）。"""
+        return {
+            "serial": self.device_sn,
+            "platform": self.platform,
+            "device_type": self.get_device_type(),
+            "os_type": self.get_os_type(),
+            "display_size": self.get_display_size(),
+            "display_rotation": self.get_display_rotation(),
+        }
+
+    def get_display_size(self) -> Tuple[int, int]:
+        result = self._rpc.call("Driver.getDisplaySize", DRIVER_REF, [])
+        if isinstance(result, dict):
+            return (int(result.get('x', 0)), int(result.get('y', 0)))
+        if isinstance(result, (list, tuple)) and len(result) >= 2:
+            return (int(result[0]), int(result[1]))
+        return (0, 0)
+
+    def get_display_rotation(self) -> int:
+        result = self._rpc.call("Driver.getDisplayRotation", DRIVER_REF, [])
+        return int(result) if result is not None else 0
+
+    def set_display_rotation(self, rotation: int) -> None:
+        self._rpc.call("Driver.setDisplayRotation", DRIVER_REF, [rotation])
+
+    def set_display_rotation_enabled(self, enabled: bool) -> None:
+        self._rpc.call(
+            "Driver.setDisplayRotationEnabled", DRIVER_REF, [enabled]
+        )
+
+    def get_device_type(self) -> str:
+        return self.shell("param get const.product.devicetype").strip()
+
+    def get_os_type(self) -> str:
+        return "harmony"
+
+    # ============================================================
+    # 屏幕操作
+    # ============================================================
+
+    def screen_on(self) -> None:
+        logger.debug("亮屏 (serial=%s)", self.device_sn)
+        self.shell("power-shell wakeup")
+
+    def screen_off(self) -> None:
+        logger.debug("熄屏 (serial=%s)", self.device_sn)
+        self.shell("power-shell suspend")
+
+    def is_screen_on(self) -> bool:
+        output = self.shell("hidumper -s PowerManagerService -a '-a'")
+        return "Current State: AWAKE" in output
+
+    def is_screen_locked(self) -> bool:
+        output = self.shell("hidumper -s ScreenlockService -a -all")
+        for line in output.splitlines():
+            if "screenLocked" in line:
+                return "false" not in line
+        return not self.is_screen_on()
+
+    def unlock(self) -> None:
+        logger.debug("解锁设备 (serial=%s)", self.device_sn)
+        w, h = self.get_display_size()
+        self.screen_on()
+        self.wait(1)
+        if not self.is_screen_locked():
+            return
+        if self.get_device_type() == "2in1":
+            self.press("enter")
+        else:
+            self.swipe(
+                int(0.5 * w), int(0.99 * h),
+                int(0.5 * w), int(0.7 * h),
+                duration=0.1,
+            )
+
+    def set_sleep_time(self, seconds: float) -> None:
+        if not self.is_screen_on():
+            self.screen_on()
+        self.shell("power-shell timeout -o %d" % int(seconds * 1000))
+
+    def restore_sleep_time(self) -> None:
+        self.shell("power-shell timeout -r")
+
+    def wake_up_display(self) -> None:
+        """唤醒屏幕（语义化别名，等价于 screen_on）。"""
+        self.screen_on()
+
+    def close_display(self) -> None:
+        """关闭屏幕（语义化别名，等价于 screen_off）。"""
+        self.screen_off()
+
+    # ============================================================
+    # 选择器入口（U2 风格）
+    # ============================================================
+
+    def __call__(self, **kwargs) -> 'UiObject':
+        selector = build_selector(**kwargs)
+        return UiObject(self, selector)
+
+    def xpath(self, xpath: str) -> 'UiObject':
+        selector = build_selector(xpath=xpath)
+        return UiObject(self, selector)
+
+    # ============================================================
+    # 应用管理
+    # ============================================================
+
+    def app_start(self, package: str, activity: Optional[str] = None,
+                  params: str = "", wait_time: float = 1) -> None:
+        # ability 名需全路径（包名.Ability名），短名自动拼接
+        if activity is None:
+            ability = package + ".MainAbility"
+        elif "." not in activity:
+            ability = package + "." + activity
+        else:
+            ability = activity
+        cmd = "aa start -a %s -b %s" % (ability, package)
+        if params:
+            cmd += " " + params
+        logger.debug("启动应用 %s/%s (serial=%s)", package, ability, self.device_sn)
+        self.shell(cmd)
+        if wait_time:
+            self.wait(wait_time)
+
+    def app_stop(self, package: str, wait_time: float = 0.5) -> None:
+        logger.debug("停止应用 %s (serial=%s)", package, self.device_sn)
+        self.shell("aa force-stop %s" % package)
+        if wait_time:
+            self.wait(wait_time)
+
+    def app_current(self) -> Tuple[str, str]:
+        """获取当前前台应用包名与 Ability 名。
+
+        通过 hidumper 解析焦点窗口 ID 与 mission 列表匹配。
+        位于桌面或读取失败时返回 (None, None)。
+
+        Returns:
+            (package_name, ability_name)
+        """
+        # 焦点窗口 ID
+        win_echo = self.shell("hidumper -s WindowManagerService -a '-a'")
+        focus_match = re.search(r"Focus window: (\d+)", win_echo)
+        if not focus_match:
+            return (None, None)
+        focus_window = focus_match.group(1)
+
+        # mission 列表
+        mission_echo = self.shell("hidumper -s AbilityManagerService -a -l")
+        missions = re.findall(
+            r"Mission ID #(\d+)\s+mission name #\[(.*?)\]", mission_echo
+        )
+        for mission_id, mission_name in missions:
+            if mission_id == focus_window:
+                pkg = mission_name.split(":")[0].replace("#", "")
+                ability = mission_name.split(":")[-1]
+                return (pkg, ability)
+
+        # 焦点窗口未命中 mission，回退在窗口回显中查找
+        missions = re.findall(
+            r"Mission ID #(\d+)\s+mission name #\[(.*?)\]", win_echo
+        )
+        for mission_id, mission_name in missions:
+            if mission_id == focus_window:
+                pkg = mission_name.split(":")[0].replace("#", "")
+                ability = mission_name.split(":")[-1]
+                return (pkg, ability)
+
+        return (None, None)
+
+    def app_list(self) -> List[str]:
+        output = self.shell("bm dump -a")
+        packages = []
+        for line in output.splitlines():
+            line = line.strip()
+            if line and not line.startswith("ID") and "." in line:
+                packages.append(line)
+        return packages
+
+    def has_app(self, package: str) -> bool:
+        output = self.shell("bm dump -n %s" % shlex.quote(package))
+        return package in output
+
+    def clear_app_data(self, package: str) -> None:
+        self.shell("bm clean -n %s -d" % shlex.quote(package))
+
+    def app_install(self, path: str, options: str = "") -> None:
+        """安装应用。
+
+        Args:
+            path: 安装包在设备端的路径（hap/hsp 包）
+            options: bm install 额外参数（如 "-r" 覆盖安装）
+        """
+        cmd = "bm install -p %s" % shlex.quote(path)
+        if options:
+            cmd += " " + options
+        logger.debug("安装应用 %s (serial=%s)", path, self.device_sn)
+        self.shell(cmd)
+
+    def app_uninstall(self, package: str) -> None:
+        """卸载应用。"""
+        logger.debug("卸载应用 %s (serial=%s)", package, self.device_sn)
+        self.shell("bm uninstall -n %s" % shlex.quote(package))
+
+    # ============================================================
+    # 坐标操作
+    # ============================================================
+
+    def click(self, x: int, y: int) -> None:
+        self._rpc.call("Driver.click", DRIVER_REF, [x, y])
+
+    def long_click(self, x: int, y: int, duration: float = 0.5) -> None:
+        # 设备端 longClickAt 要求 duration >= 1500ms，低于阈值用 longClick（设备默认约1秒）
+        duration_ms = int(duration * 1000)
+        if duration_ms >= 1500:
+            self._rpc.call(
+                "Driver.longClickAt", DRIVER_REF, [{"x": x, "y": y}, duration_ms]
+            )
+        else:
+            self._rpc.call("Driver.longClick", DRIVER_REF, [x, y])
+
+    def double_click(self, x: int, y: int) -> None:
+        self._rpc.call("Driver.doubleClick", DRIVER_REF, [x, y])
+
+    def swipe(self, x1: int, y1: int, x2: int, y2: int,
+              duration: float = 0.5) -> None:
+        distance = max(abs(x2 - x1), abs(y2 - y1), 1)
+        speed = int(distance / duration) if duration > 0 else 600
+        self._rpc.call(
+            "Driver.swipe", DRIVER_REF, [x1, y1, x2, y2, speed]
+        )
+
+    def swipe_dir(self, direction: str, distance: int = 60,
+                  area=None, speed=None) -> None:
+        w, h = self.get_display_size()
+        cx, cy = w // 2, h // 2
+        direction = direction.upper()
+        if direction == 'UP':
+            x1, y1, x2, y2 = cx, cy + distance, cx, cy - distance
+        elif direction == 'DOWN':
+            x1, y1, x2, y2 = cx, cy - distance, cx, cy + distance
+        elif direction == 'LEFT':
+            x1, y1, x2, y2 = cx + distance, cy, cx - distance, cy
+        elif direction == 'RIGHT':
+            x1, y1, x2, y2 = cx - distance, cy, cx + distance, cy
+        else:
+            raise DevhelmError("未知滑动方向: %s" % direction)
+        self.swipe(x1, y1, x2, y2)
+
+    def drag(self, x1: int, y1: int, x2: int, y2: int,
+             duration: float = 0.5) -> None:
+        distance = max(abs(x2 - x1), abs(y2 - y1), 1)
+        speed = int(distance / duration) if duration > 0 else 600
+        self._rpc.call(
+            "Driver.drag", DRIVER_REF, [x1, y1, x2, y2, speed]
+        )
+
+    def fling(self, direction: str, distance: int = 50,
+              area=None, speed: str = "fast") -> None:
+        speed_map = {"fast": 1000, "normal": 600, "slow": 300}
+        swipe_speed = speed_map.get(speed, 600)
+        w, h = self.get_display_size()
+        cx, cy = w // 2, h // 2
+        direction = direction.upper()
+        if direction == 'UP':
+            x1, y1, x2, y2 = cx, cy + distance, cx, cy - distance
+        elif direction == 'DOWN':
+            x1, y1, x2, y2 = cx, cy - distance, cx, cy + distance
+        elif direction == 'LEFT':
+            x1, y1, x2, y2 = cx + distance, cy, cx - distance, cy
+        elif direction == 'RIGHT':
+            x1, y1, x2, y2 = cx - distance, cy, cx + distance, cy
+        else:
+            raise DevhelmError("未知滑动方向: %s" % direction)
+        self._rpc.call(
+            "Driver.swipe", DRIVER_REF, [x1, y1, x2, y2, swipe_speed]
+        )
+
+    # ============================================================
+    # 实时触控（Gestures 模块，支持 down/move/up 序列）
+    # ============================================================
+
+    def touch_down(self, x: int, y: int) -> None:
+        """按下触控点。"""
+        from devhelmkit.harmony.rpc.proxy_v2 import rpc_gestures
+        logger.debug("Gestures -> touchDown (%d, %d)", x, y)
+        rpc_gestures(self._device, "touchDown", {"x": x, "y": y})
+
+    def touch_move(self, x: int, y: int) -> None:
+        """移动触控点（需先 touch_down）。"""
+        from devhelmkit.harmony.rpc.proxy_v2 import rpc_gestures
+        logger.debug("Gestures -> touchMove (%d, %d)", x, y)
+        rpc_gestures(self._device, "touchMove", {"x": x, "y": y})
+
+    def touch_up(self, x: int, y: int) -> None:
+        """抬起触控点（结束触控序列）。"""
+        from devhelmkit.harmony.rpc.proxy_v2 import rpc_gestures
+        logger.debug("Gestures -> touchUp (%d, %d)", x, y)
+        rpc_gestures(self._device, "touchUp", {"x": x, "y": y})
+
+    # ============================================================
+    # 按键
+    # ============================================================
+
+    def press(self, key: str) -> None:
+        keycode = _KEY_MAP.get(key.lower())
+        if keycode is None:
+            raise DevhelmError("未知按键: %s" % key)
+        self.press_keycode(int(keycode))
+
+    def press_keycode(self, keycode: int) -> None:
+        if isinstance(keycode, KeyCode):
+            keycode = int(keycode)
+        # Driver.pressKey 设备端不存在，改用 Driver.triggerKey
+        self._rpc.call("Driver.triggerKey", DRIVER_REF, [keycode])
+
+    def go_home(self) -> None:
+        # 专用 API，比 pressKey 更稳定
+        self._rpc.call("Driver.pressHome", DRIVER_REF, [])
+
+    def go_back(self) -> None:
+        # 专用 API，比 pressKey 更稳定
+        self._rpc.call("Driver.pressBack", DRIVER_REF, [])
+
+    def press_power(self) -> None:
+        self.press_keycode(int(KeyCode.POWER))
+
+    def press_combination_key(self, key1: int, key2: int,
+                              key3: Optional[int] = None) -> None:
+        keys = []
+        for item in (key1, key2, key3):
+            if item is None:
+                continue
+            if isinstance(item, KeyCode):
+                item = int(item)
+            keys.append(item)
+        self._rpc.call("Driver.triggerCombineKeys", DRIVER_REF, keys)
+
+    # ============================================================
+    # Shell
+    # ============================================================
+
+    def shell(self, cmd: str, timeout: float = 60) -> str:
+        return self._device.shell(cmd, timeout=timeout)
+
+    # ============================================================
+    # 截图
+    # ============================================================
+
+    def screenshot(self, filename: Optional[str] = None,
+                   area=None) -> Union['Image', str, None]:
+        # area 暂未支持，预留接口
+        import os
+        import tempfile
+        from PIL import Image
+        # 设备端 snapshot_display 强制要求后缀为 .jpeg
+        remote_path = "/data/local/tmp/devhelm_screenshot.jpeg"
+        self.shell("snapshot_display -f %s" % remote_path)
+        # 先 pull 到本地临时 jpeg 文件
+        tmp = tempfile.NamedTemporaryFile(suffix=".jpeg", delete=False)
+        tmp_path = tmp.name
+        tmp.close()
+        try:
+            self._device.pull(remote_path, tmp_path)
+            img = Image.open(tmp_path)
+            img.load()
+            if filename:
+                # 按用户指定路径扩展名保存（png/jpg/...）
+                img.save(filename)
+                return filename
+            return img
+        finally:
+            if os.path.exists(tmp_path):
+                os.remove(tmp_path)
+
+    def dump_hierarchy(self, source: str = "rpc",
+                       filename: Optional[str] = None) -> Union[dict, str, None]:
+        """导出控件树。
+
+        - source="rpc": 走 uitest RPC（Captures.captureLayout），直接返回控件树 JSON，无需文件中转
+        - source="hdc": 走 hdc shell（uitest dumpLayout -p），独立于 RPC 守护进程状态
+        - filename 为 None：返回解析后的 dict
+        - filename 指定：保存 JSON 到文件，返回文件路径 str
+        """
+        import json
+        import os
+
+        if source not in ("rpc", "hdc"):
+            raise ValueError("source 仅支持 'rpc' 或 'hdc'，当前: %s" % source)
+
+        if source == "rpc":
+            # 走 RPC 通道：Captures.captureLayout 直接返回控件树 JSON
+            from devhelmkit.harmony.rpc.proxy_v2 import rpc_captures
+            logger.debug("RPC(Captures) -> captureLayout")
+            reply = rpc_captures(self._device, "captureLayout", {})
+            try:
+                data = json.loads(reply)
+            except json.JSONDecodeError as e:
+                logger.error("控件树响应解析失败: %s", e)
+                return None
+            # 检测错误
+            if isinstance(data, dict):
+                if data.get('error'):
+                    logger.warn("captureLayout 调用失败: %s", data['error'])
+                    return None
+                if data.get('exception'):
+                    msg = data['exception'].get('message', str(data['exception']))
+                    logger.warn("captureLayout 调用异常: %s", msg)
+                    return None
+                # 响应可能是 {"result": {...}} 或直接是控件树
+                if 'result' in data:
+                    data = data['result']
+            logger.debug("RPC(Captures) <- captureLayout ok")
+        else:
+            # 走 hdc shell：uitest dumpLayout -p 命令独立于 RPC 守护进程
+            import tempfile
+            remote_path = "/data/local/tmp/devhelm_layout.json"
+            self.shell("uitest dumpLayout -p %s" % remote_path)
+            tmp = tempfile.NamedTemporaryFile(suffix=".json", delete=False)
+            tmp_path = tmp.name
+            tmp.close()
+            try:
+                self._device.pull(remote_path, tmp_path)
+                with open(tmp_path, "r", encoding="utf-8") as f:
+                    data = json.load(f)
+            except Exception as e:
+                logger.error("控件树解析失败 (source=hdc): %s", e)
+                return None
+            finally:
+                if os.path.exists(tmp_path):
+                    os.remove(tmp_path)
+
+        if not isinstance(data, dict):
+            logger.error("控件树数据格式异常: %s", type(data))
+            return None
+
+        if filename:
+            with open(filename, "w", encoding="utf-8") as f:
+                json.dump(data, f, ensure_ascii=False, indent=2)
+            return filename
+        return data
+
+    # ============================================================
+    # 等待
+    # ============================================================
+
+    def wait(self, seconds: float) -> None:
+        time.sleep(seconds)
+
+    def wait_for_idle(self, idle_time: float = 0.7,
+                      timeout: float = 10) -> None:
+        # TODO: 通过 RPC 轮询 UI 空闲状态
+        self.wait(idle_time)
+
+    def implicitly_wait(self, seconds: float) -> None:
+        self._implicit_wait = seconds
+
+    # ============================================================
+    # 窗口
+    # ============================================================
+
+    @property
+    def window(self) -> 'UiWindow':
+        return UiWindow(self, self._rpc)
+
+    def get_windows(self) -> List['UiWindow']:
+        """获取所有窗口（当前不支持，返回空列表）。"""
+        return []
+
+    # ============================================================
+    # webview 自动化
+    # ============================================================
+
+    def webview(self, bundle_name: str,
+                chromedriver_search_path: str = "",
+                chromedriver_exe_path: str = "",
+                remote_devtools_port: Optional[int] = None,
+                connection_timeout: int = 60,
+                options=None) -> "WebViewDriver":
+        """连接指定应用的 webview，返回 selenium webdriver 封装。
+
+        Args:
+            bundle_name: 目标应用包名
+            chromedriver_search_path: chromedriver 存放目录（多版本结构）
+            chromedriver_exe_path: 直接指定 chromedriver 路径（优先）
+            remote_devtools_port: 自定义 webview 内核的 devtools 端口；
+                                  系统 web 内核无需指定
+            connection_timeout: 连接超时（秒）
+            options: 传递给 selenium webdriver 的 options
+
+        Returns:
+            WebViewDriver 实例，可通过 .driver 访问 selenium webdriver
+
+        Example:
+            wv = d.webview("com.huawei.hmos.browser")
+            wv.driver.get("https://www.baidu.com")
+            wv.close()
+        """
+        from devhelmkit.harmony.webview import WebViewDriver
+        wv = WebViewDriver(
+            self._device,
+            chromedriver_search_path=chromedriver_search_path,
+            chromedriver_exe_path=chromedriver_exe_path,
+        )
+        wv.connect(
+            bundle_name,
+            remote_devtools_port=remote_devtools_port,
+            connection_timeout=connection_timeout,
+            options=options,
+        )
+        return wv
+
+    # ============================================================
+    # 文件操作
+    # ============================================================
+
+    def push_file(self, local_path: str, remote_path: str,
+                  timeout: int = 60) -> None:
+        self._device.push(local_path, remote_path, timeout=timeout)
+
+    def pull_file(self, remote_path: str,
+                  local_path: Optional[str] = None,
+                  timeout: int = 60) -> None:
+        if local_path is None:
+            import tempfile
+            tmp = tempfile.NamedTemporaryFile(delete=False)
+            local_path = tmp.name
+            tmp.close()
+        self._device.pull(remote_path, local_path, timeout=timeout)
+
+    def has_file(self, path: str) -> bool:
+        output = self.shell("test -f %s && echo yes || echo no" % shlex.quote(path))
+        return "yes" in output
+
+    # ============================================================
+    # 控件查找（UiObject 门面方法）
+    # ============================================================
+
+    def call_component(self, selector: SelectorSpec, method: str,
+                       args: Optional[list] = None,
+                       timeout: Optional[float] = None) -> Any:
+        return self._finder.call_component(
+            selector, method, args or [],
+            timeout if timeout is not None else self._implicit_wait
+        )
+
+    def component_exists(self, selector: SelectorSpec) -> bool:
+        selector = _to_selector(selector)
+        if selector is None:
+            return False
+        return self._finder.component_exists(selector)
+
+    def wait_component(self, selector: SelectorSpec,
+                       timeout: float) -> bool:
+        selector = _to_selector(selector)
+        if selector is None:
+            return False
+        return self._finder.wait_component(selector, timeout)
+
+    def wait_component_gone(self, selector: SelectorSpec,
+                            timeout: float) -> bool:
+        selector = _to_selector(selector)
+        if selector is None:
+            return True
+        return self._finder.wait_component_gone(selector, timeout)
+
+    def scroll_search(self, selector: SelectorSpec, target,
+                      vertical: bool = True,
+                      offset: Optional[int] = None) -> Optional['UiObject']:
+        # TODO: 滚动查找实现
+        raise NotImplementedError("scroll_search 待实现")
+
+    # ============================================================
+    # 控件查找（BaseDriver 契约）
+    # ============================================================
+
+    def find_component(self, target,
+                       scroll_target=None) -> Optional['BaseComponent']:
+        selector = _to_selector(target)
+        if selector is None:
+            return None
+        return UiObject(self, selector)
+
+    def find_all_components(self, target) -> List['BaseComponent']:
+        selector = _to_selector(target)
+        if selector is None:
+            return []
+        refs = self._finder.find_components(selector)
+        # 每个 ref 包装为 UiObject，持有相同 selector
+        # TODO: 后续支持按 index 区分多个匹配控件
+        if not refs:
+            return []
+        return [UiObject(self, selector)]
+
+    def get_component_bound(self, target) -> Optional[Any]:
+        selector = _to_selector(target)
+        if selector is None:
+            return None
+        try:
+            return UiObject(self, selector).bounds
+        except DevhelmError:
+            return None
+
+    def get_component_property(self, target, name: str) -> Any:
+        selector = _to_selector(target)
+        if selector is None:
+            raise DevhelmError("无效的控件目标: %r" % (target,))
+        method = _PROPERTY_METHOD_MAP.get(name)
+        if method is None:
+            raise DevhelmError(
+                "不支持的属性: %s，支持: %s" % (name, list(_PROPERTY_METHOD_MAP.keys()))
+            )
+        return self.call_component(selector, method)
+
+    def switch_component_status(self, target, checked: bool) -> None:
+        """切换控件状态（如 Checkbox/RadioButton）。
+
+        读取控件当前 isChecked，仅当与目标状态不一致时点击切换，
+        避免重复点击导致状态回退。
+
+        Args:
+            target: 控件目标（SelectorSpec / UiObject / 选择器 kwargs）
+            checked: 目标状态 True=选中 / False=取消选中
+        """
+        selector = _to_selector(target)
+        if selector is None:
+            raise DevhelmError("无效的控件目标: %r" % (target,))
+        current = self.call_component(selector, "isChecked")
+        if bool(current) != bool(checked):
+            self.call_component(selector, "click")
+
+    # ============================================================
+    # 图片识别
+    # ============================================================
+
+    def find_image(self, image_path: str,
+                   mode: str = "sift") -> Optional[Any]:
+        # TODO: 图像识别能力后续阶段实现
+        raise NotImplementedError("find_image 待实现")
+
+    def touch_image(self, image_path: str, mode: str = "normal",
+                    similarity: float = 0.95) -> None:
+        # TODO: 图像识别能力后续阶段实现
+        raise NotImplementedError("touch_image 待实现")
+
+    # ============================================================
+    # 文本输入辅助
+    # ============================================================
+
+    def hide_keyboard(self) -> None:
+        self.press("back")
+
+    def input_text_on_cursor(self, text: str) -> None:
+        import shlex
+        self.shell("uitest uiInput text %s" % shlex.quote(text))
+
+    def clear_text_on_cursor(self) -> None:
+        """清空当前获焦输入框文本。
+
+        通过 uitest uiInput clear 命令清空当前光标所在输入框，
+        不依赖控件定位。
+        """
+        self.shell("uitest uiInput clear")
+
+    def move_cursor(self, direction: str, times: int = 1) -> None:
+        key_map = {
+            "LEFT": KeyCode.DPAD_LEFT,
+            "RIGHT": KeyCode.DPAD_RIGHT,
+            "UP": KeyCode.DPAD_UP,
+            "DOWN": KeyCode.DPAD_DOWN,
+            "BEGIN": KeyCode.MOVE_HOME,
+            "END": KeyCode.MOVE_END,
+        }
+        keycode = key_map.get(direction.upper())
+        if keycode is None:
+            raise DevhelmError("未知光标方向: %s" % direction)
+        for _ in range(times):
+            self.press_keycode(int(keycode))
+
+    # ============================================================
+    # 手势扩展
+    # ============================================================
+
+    def _build_pointer_matrix(self,
+                              gestures: List[GestureAction]) -> str:
+        """将 GestureAction 列表转为设备端 PointerMatrix 远程对象。
+
+        每个 GestureAction 代表一指的轨迹，步骤数取最大值，
+        不足的用末尾坐标填充以保持位置静止。
+
+        Returns:
+            PointerMatrix 对象引用（如 "PointerMatrix#0"）
+        """
+        fingers = len(gestures)
+        if fingers == 0:
+            raise DevhelmError("gestures 不能为空")
+        max_steps = max(len(g.steps) for g in gestures)
+        if max_steps == 0:
+            raise DevhelmError("GestureAction 无步骤")
+        ref = self._rpc.call(
+            "PointerMatrix.create", "PointerMatrix#seed", [fingers, max_steps]
+        )
+        if not isinstance(ref, str):
+            raise DevhelmError("PointerMatrix 创建失败: %r" % (ref,))
+        for finger_idx, gesture in enumerate(gestures):
+            steps = gesture.steps
+            if not steps:
+                continue
+            last = steps[-1]
+            for step_idx in range(max_steps):
+                step = steps[step_idx] if step_idx < len(steps) else last
+                self._rpc.call(
+                    "PointerMatrix.setPoint", ref,
+                    [finger_idx, step_idx, {"x": step.x, "y": step.y}]
+                )
+        return ref
+
+    def inject_gesture(self, gesture: GestureAction,
+                       speed: int = 2000) -> None:
+        """单指自定义手势。"""
+        ref = self._build_pointer_matrix([gesture])
+        self._rpc.call("Driver.injectMultiPointerAction", DRIVER_REF, [ref, speed])
+
+    def inject_multi_finger_gesture(self, gestures: List[GestureAction],
+                                    speed: int = 2000) -> None:
+        """多指手势，每个 GestureAction 代表一指轨迹。"""
+        ref = self._build_pointer_matrix(gestures)
+        self._rpc.call("Driver.injectMultiPointerAction", DRIVER_REF, [ref, speed])
+
+    def two_finger_swipe(self, s1: tuple, e1: tuple,
+                         s2: tuple, e2: tuple,
+                         duration: float = 0.5) -> None:
+        """双指滑动。
+
+        Args:
+            s1/e1: 第一指起止坐标
+            s2/e2: 第二指起止坐标
+            duration: 滑动时长（秒），用于计算速度
+        """
+        g1 = GestureAction()
+        g1.add_step("move", s1[0], s1[1])
+        g1.add_step("move", e1[0], e1[1])
+        g2 = GestureAction()
+        g2.add_step("move", s2[0], s2[1])
+        g2.add_step("move", e2[0], e2[1])
+        dist = max(abs(e1[0] - s1[0]), abs(e1[1] - s1[1]), 1)
+        speed = int(dist / duration) if duration > 0 else 600
+        self.inject_multi_finger_gesture([g1, g2], speed)
+
+    def multi_finger_touch(self, points: List[tuple],
+                           duration: float = 0.1) -> None:
+        """多指同时点击。
+
+        Args:
+            points: 各指按下坐标 [(x, y), ...]
+            duration: 按住时长（秒），用于计算速度
+        """
+        gestures = []
+        for pt in points:
+            g = GestureAction()
+            g.add_step("down", pt[0], pt[1])
+            g.add_step("up", pt[0], pt[1])
+            gestures.append(g)
+        speed = int(100 / duration) if duration > 0 else 1000
+        self.inject_multi_finger_gesture(gestures, speed)
+
+    # ============================================================
+    # 鼠标操作
+    # ============================================================
+
+    def mouse_click(self, pos, button_id: int = 0,
+                    key1: Optional[int] = None,
+                    key2: Optional[int] = None) -> None:
+        """鼠标点击。
+
+        Args:
+            pos: 点击位置 (x, y) 或 {x, y}
+            button_id: 0=左键 1=右键 2=中键
+            key1: 组合键1（如 Ctrl=2072）
+            key2: 组合键2
+        """
+        args = [_to_point(pos), button_id]
+        if key1 is not None:
+            args.append(key1)
+            if key2 is not None:
+                args.append(key2)
+        self._rpc.call("Driver.mouseClick", DRIVER_REF, args)
+
+    def mouse_double_click(self, pos, button_id: int = 0) -> None:
+        """鼠标双击。"""
+        self._rpc.call(
+            "Driver.mouseDoubleClick", DRIVER_REF,
+            [_to_point(pos), button_id]
+        )
+
+    def mouse_long_click(self, pos, button_id: int = 0,
+                         press_time: float = 1.5) -> None:
+        """鼠标长按。
+
+        Args:
+            press_time: 按住时长（秒），转为毫秒传入设备端
+        """
+        duration_ms = int(press_time * 1000)
+        self._rpc.call(
+            "Driver.mouseLongClick", DRIVER_REF,
+            [_to_point(pos), button_id, 0, 0, duration_ms]
+        )
+
+    def mouse_scroll(self, pos, direction: str, steps: int,
+                     key1: Optional[int] = None,
+                     key2: Optional[int] = None) -> None:
+        """鼠标滚轮滚动。
+
+        Args:
+            direction: 'up' 向上 / 'down' 向下
+            steps: 滚动步数
+        """
+        down = direction.lower() == "down"
+        args = [_to_point(pos), down, steps]
+        if key1 is not None:
+            args.append(key1)
+            if key2 is not None:
+                args.append(key2)
+        self._rpc.call("Driver.mouseScroll", DRIVER_REF, args)
+
+    def mouse_move_to(self, pos) -> None:
+        """鼠标光标瞬移到指定位置。"""
+        self._rpc.call("Driver.mouseMoveTo", DRIVER_REF, [_to_point(pos)])
+
+    def mouse_move(self, start, end, speed: int = 3000) -> None:
+        """鼠标沿轨迹从起点移动到终点。"""
+        self._rpc.call(
+            "Driver.mouseMoveWithTrack", DRIVER_REF,
+            [_to_point(start), _to_point(end), speed]
+        )
+
+    def mouse_drag(self, start, end, speed: int = 3000) -> None:
+        """鼠标拖拽。"""
+        self._rpc.call(
+            "Driver.mouseDrag", DRIVER_REF,
+            [_to_point(start), _to_point(end), speed]
+        )
+
+    # ============================================================
+    # 触控笔操作
+    # ============================================================
+
+    def pen_click(self, target, offset=None) -> None:
+        """触控笔点击。
+
+        Args:
+            target: 坐标 (x, y) 或 UiObject（取 center）
+            offset: 相对偏移 (dx, dy)
+        """
+        point = self._resolve_target_point(target, offset)
+        self._rpc.call("Driver.penClick", DRIVER_REF, [point])
+
+    def pen_double_click(self, target, offset=None) -> None:
+        """触控笔双击。"""
+        point = self._resolve_target_point(target, offset)
+        self._rpc.call("Driver.penDoubleClick", DRIVER_REF, [point])
+
+    def pen_long_click(self, target, offset=None,
+                       pressure: Optional[float] = None) -> None:
+        """触控笔长按。
+
+        Args:
+            pressure: 笔压力值 0.0-1.0
+        """
+        point = self._resolve_target_point(target, offset)
+        args = [point]
+        if pressure is not None:
+            args.append(pressure)
+        self._rpc.call("Driver.penLongClick", DRIVER_REF, args)
+
+    def pen_swipe(self, direction: str, distance: int = 60,
+                  area=None, pressure: Optional[float] = None,
+                  duration: float = 0.3) -> None:
+        """触控笔方向滑动。
+
+        Args:
+            direction: 'UP'/'DOWN'/'LEFT'/'RIGHT'
+            distance: 滑动距离（像素）
+            duration: 滑动时长（秒），用于计算速度
+        """
+        w, h = self.get_display_size()
+        cx, cy = w // 2, h // 2
+        direction = direction.upper()
+        if direction == 'UP':
+            start, end = (cx, cy + distance), (cx, cy - distance)
+        elif direction == 'DOWN':
+            start, end = (cx, cy - distance), (cx, cy + distance)
+        elif direction == 'LEFT':
+            start, end = (cx + distance, cy), (cx - distance, cy)
+        elif direction == 'RIGHT':
+            start, end = (cx - distance, cy), (cx + distance, cy)
+        else:
+            raise DevhelmError("未知滑动方向: %s" % direction)
+        self.pen_slide(start, end, area, pressure, duration)
+
+    def pen_slide(self, start, end, area=None,
+                  pressure: Optional[float] = None,
+                  duration: float = 0.3) -> None:
+        """触控笔精确滑动。
+
+        Args:
+            start: 起点 (x, y)
+            end: 终点 (x, y)
+            pressure: 笔压力值
+            duration: 滑动时长（秒），用于计算速度
+        """
+        start_pt = _to_point(start)
+        end_pt = _to_point(end)
+        dist = max(abs(end_pt['x'] - start_pt['x']),
+                   abs(end_pt['y'] - start_pt['y']), 1)
+        speed = int(dist / duration) if duration > 0 else 600
+        args = [start_pt, end_pt, speed]
+        if pressure is not None:
+            args.append(pressure)
+        self._rpc.call("Driver.penSwipe", DRIVER_REF, args)
+
+    def pen_drag(self, start, end, area=None,
+                 pressure: Optional[float] = None,
+                 press_time: float = 1.5,
+                 duration: float = 0.5) -> None:
+        """触控笔拖拽（按住后移动）。
+
+        Args:
+            start: 起点 (x, y)
+            end: 终点 (x, y)
+            press_time: 起点按住时长（秒）
+            duration: 移动到终点的时长（秒）
+            pressure: 笔压力值
+        """
+        g = GestureAction(input_device=InputDevice.PEN)
+        g.add_step("down", start[0], start[1], press_time)
+        g.add_step("move", end[0], end[1], duration)
+        ref = self._build_pointer_matrix([g])
+        dist = max(abs(end[0] - start[0]), abs(end[1] - start[1]), 1)
+        speed = int(dist / duration) if duration > 0 else 600
+        args = [ref, speed]
+        if pressure is not None:
+            args.append(pressure)
+        self._rpc.call("Driver.injectPenPointerAction", DRIVER_REF, args)
+
+    def pen_inject_gesture(self, gesture: GestureAction,
+                          pressure: Optional[float] = None,
+                          speed: int = 2000) -> None:
+        """触控笔自定义手势。"""
+        ref = self._build_pointer_matrix([gesture])
+        args = [ref, speed]
+        if pressure is not None:
+            args.append(pressure)
+        self._rpc.call("Driver.injectPenPointerAction", DRIVER_REF, args)
+
+    # ============================================================
+    # 指关节操作
+    # ============================================================
+
+    def knuckle_knock(self, targets: list, times: int = 2) -> None:
+        """指关节敲击（常用于截屏等快捷操作）。
+
+        Args:
+            targets: 敲击位置列表，1-2 个点 [(x, y), ...]
+            times: 敲击次数
+        """
+        points = [_to_point(t) for t in targets]
+        # 设备端底层参数非数组：单点 [point, times]，双点 [p0, p1, times]
+        args = points + [times]
+        self._rpc.call("Driver.knuckleKnock", DRIVER_REF, args)
+
+    def inject_knuckle_gesture(self, gesture: GestureAction,
+                               speed: int = 2000) -> None:
+        """指关节自定义手势。"""
+        ref = self._build_pointer_matrix([gesture])
+        self._rpc.call(
+            "Driver.injectKnucklePointerAction", DRIVER_REF, [ref, speed]
+        )
+
+    # ============================================================
+    # 手势导航
+    # ============================================================
+
+    def swipe_to_home(self, times: int = 1) -> None:
+        logger.debug("上滑回桌面 times=%d (serial=%s)", times, self.device_sn)
+        w, h = self.get_display_size()
+        start_x = w // 2
+        start_y = h - 10
+        end_y = h - h // 3
+        end_x = int(start_x * 1.2)
+        for i in range(times):
+            self.swipe(start_x, start_y, end_x, end_y, duration=0.3)
+            if i < times - 1:
+                self.wait(0.5)
+        self.wait(1)
+
+    def swipe_to_back(self, side: str = "right", times: int = 1,
+                      height: float = 0.5) -> None:
+        logger.debug("侧滑返回 side=%s times=%d (serial=%s)",
+                     side, times, self.device_sn)
+        side = side.upper()
+        if side == "RIGHT":
+            start = self.to_abs_pos(0.99, height)
+            end = self.to_abs_pos(0.6, height * 1.2)
+        elif side == "LEFT":
+            start = self.to_abs_pos(0.01, height)
+            end = self.to_abs_pos(0.4, height * 1.2)
+        else:
+            raise DevhelmError("未知侧滑方向: %s" % side)
+        cmd = "uinput -T -m %d %d %d %d %d" % (
+            start[0], start[1], end[0], end[1], 200
+        )
+        for i in range(times):
+            self.shell(cmd)
+            if i < times - 1:
+                self.wait(0.5)
+
+    def swipe_to_recent_task(self) -> None:
+        logger.debug("上滑进入多任务 (serial=%s)", self.device_sn)
+        w, h = self.get_display_size()
+        start_x = w // 2
+        start_y = h - 10
+        end_y = h - h // 4
+        end_x = int(start_x * 1.2)
+        self.swipe(start_x, start_y, end_x, end_y, duration=0.3)
+        self.wait(1)
+
+    # ============================================================
+    # 坐标转换
+    # ============================================================
+
+    def to_abs_pos(self, x: float, y: float) -> Tuple[int, int]:
+        # 每轴独立判断：[-1,1] 按比例转换，否则按绝对值
+        w, h = self.get_display_size()
+        abs_x = int(x * w) if -1.0 <= x <= 1.0 else int(x)
+        abs_y = int(y * h) if -1.0 <= y <= 1.0 else int(y)
+        return (abs_x, abs_y)
+
+    # ============================================================
+    # 设备初始化
+    # ============================================================
+
+    def _setup_device(self) -> None:
+        """设备初始化：检查 uitest 版本。"""
+        uitest_version = self._get_uitest_version()
+        if uitest_version in _UNSUPPORTED_UITEST_VERSIONS:
+            raise DevhelmError(
+                "不支持的 uitest 版本: %s" % uitest_version
+            )
+
+    def _get_uitest_version(self) -> str:
+        """获取 uitest 版本。"""
+        output = self._device.shell("uitest --version")
+        return output.strip()
+
+    # ============================================================
+    # 穿戴设备扩展
+    # ============================================================
+
+    def rotate_crown(self, steps: int,
+                     speed: Optional[int] = None) -> None:
+        """旋转表冠（穿戴设备专用）。
+
+        Args:
+            steps: 旋转角度（正数顺时针，负数逆时针）
+            speed: 旋转速度（可选）
+        """
+        args = [steps]
+        if speed is not None:
+            args.append(speed)
+        self._rpc.call("Driver.crownRotate", DRIVER_REF, args)
+
+    # ============================================================
+    # 触控板操作
+    # ============================================================
+
+    def touchpad_swipe(self, direction: str, fingers: int = 3,
+                       speed: Optional[int] = None) -> None:
+        """触控板多指滑动。
+
+        Args:
+            direction: 'UP'/'DOWN'/'LEFT'/'RIGHT'
+            fingers: 手指数（2-4）
+            speed: 滑动速度（可选）
+        """
+        direction_code = _UIDIRECTION_MAP.get(direction.upper())
+        if direction_code is None:
+            raise DevhelmError("未知滑动方向: %s" % direction)
+        args = [fingers, direction_code]
+        if speed is not None:
+            args.append({"speed": speed})
+        self._rpc.call("Driver.touchPadMultiFingerSwipe", DRIVER_REF, args)
+
+    def touchpad_swipe_and_hold(self, direction: str, fingers: int = 3,
+                                speed: Optional[int] = None) -> None:
+        """触控板多指滑动后停顿（stay=true）。
+
+        Args:
+            direction: 'UP'/'DOWN'/'LEFT'/'RIGHT'
+            fingers: 手指数（2-4）
+            speed: 滑动速度（可选）
+        """
+        direction_code = _UIDIRECTION_MAP.get(direction.upper())
+        if direction_code is None:
+            raise DevhelmError("未知滑动方向: %s" % direction)
+        options: Dict[str, Any] = {"stay": True}
+        if speed is not None:
+            options["speed"] = speed
+        self._rpc.call(
+            "Driver.touchPadMultiFingerSwipe", DRIVER_REF,
+            [fingers, direction_code, options]
+        )
+
+    # ============================================================
+    # 事件监听
+    # ============================================================
+
+    def start_listen_toast(self) -> None:
+        """开始 Toast 监听（once 模式，触发一次后自动移除）。"""
+        if self._toast_observer is None:
+            self._toast_observer = self._rpc.call(
+                "Driver.createUIEventObserver", DRIVER_REF, []
+            )
+        self._rpc.call(
+            "UIEventObserver.once", self._toast_observer,
+            ["toastShow", "callback#0"]
+        )
+        self._toast_listening = True
+
+    def get_latest_toast(self, timeout: float = 3.0) -> str:
+        """获取最新 Toast 文本。
+
+        阻塞等待设备端 Toast 事件回调推送，超时抛 DevhelmTimeoutError。
+        需先调用 start_listen_toast。
+        """
+        if not self._toast_listening:
+            raise DevhelmError("未启动 toast 监听，请先 start_listen_toast")
+        push = self._device.wait_push(timeout)
+        self._toast_listening = False
+        if push is None:
+            raise DevhelmTimeoutError("等待 toast 超时（%ss）" % timeout)
+        return self._parse_event_text(push)
+
+    def check_toast(self, text: str, fuzzy: str = "equal",
+                    timeout: float = 3.0) -> bool:
+        """检查 Toast 是否包含指定文本。
+
+        Args:
+            text: 期望文本
+            fuzzy: 匹配方式 'equal'/'contains'/'startswith'
+            timeout: 等待超时（秒）
+        """
+        try:
+            actual = self.get_latest_toast(timeout)
+        except DevhelmTimeoutError:
+            return False
+        if fuzzy == "contains":
+            return text in actual
+        if fuzzy == "startswith":
+            return actual.startswith(text)
+        return actual == text
+
+    def start_listen_ui_event(self, event_type: str) -> None:
+        """开始 UI 事件监听（once 模式）。
+
+        Args:
+            event_type: 'dialogShow' / 'windowChange' / 'componentEventOccur'
+        """
+        if self._ui_event_observer is None:
+            self._ui_event_observer = self._rpc.call(
+                "Driver.createUIEventObserver", DRIVER_REF, []
+            )
+        if event_type in ("windowChange", "componentEventOccur"):
+            args = [event_type, 1, {"timeout": 5000}, "callback#0"]
+        else:
+            args = [event_type, "callback#0"]
+        self._rpc.call(
+            "UIEventObserver.once", self._ui_event_observer, args
+        )
+        self._ui_event_listening = True
+
+    def get_latest_ui_event(self, timeout: float = 3.0) -> Optional[dict]:
+        """获取最新 UI 事件数据。
+
+        阻塞等待设备端事件回调推送，超时返回 None。
+        需先调用 start_listen_ui_event。
+        """
+        if not self._ui_event_listening:
+            raise DevhelmError("未启动 ui_event 监听，请先 start_listen_ui_event")
+        push = self._device.wait_push(timeout)
+        self._ui_event_listening = False
+        if push is None:
+            return None
+        return self._parse_event_dict(push)
+
+    @staticmethod
+    def _parse_event_text(push: str) -> str:
+        """从回调推送帧中提取文本字段（容错解析）。"""
+        try:
+            data = json.loads(push)
+        except (json.JSONDecodeError, TypeError):
+            return push
+        if not isinstance(data, dict):
+            return str(data)
+        for key in ('args', 'params'):
+            val = data.get(key)
+            if isinstance(val, list) and val:
+                info = val[0]
+                if isinstance(info, dict):
+                    return info.get('text') or info.get('message') or ''
+        info = data.get('result') or data.get('info') or data
+        if isinstance(info, dict):
+            return info.get('text') or info.get('message') or ''
+        return str(info)
+
+    @staticmethod
+    def _parse_event_dict(push: str) -> Optional[dict]:
+        """从回调推送帧中提取事件数据字典（容错解析）。"""
+        try:
+            data = json.loads(push)
+        except (json.JSONDecodeError, TypeError):
+            return None
+        if not isinstance(data, dict):
+            return None
+        for key in ('args', 'params'):
+            val = data.get(key)
+            if isinstance(val, list) and val and isinstance(val[0], dict):
+                return val[0]
+        info = data.get('result') or data.get('info')
+        if isinstance(info, dict):
+            return info
+        return data
+
+    # ============================================================
+    # 配置访问
+    # ============================================================
+
+    @property
+    def config(self) -> HarmonyDriverConfig:
+        return self._config
+
+    def update_config(self, **kwargs) -> None:
+        self._config.update_from_dict(kwargs)
+
+    def _resolve_target_point(self, target, offset=None) -> dict:
+        """将 target 解析为 {x, y} 坐标点。
+
+        Args:
+            target: 坐标 (x, y) / {x, y} / UiObject（取 center）
+            offset: 相对偏移 (dx, dy)
+        """
+        if hasattr(target, 'center'):
+            x, y = target.center()
+        else:
+            pt = _to_point(target)
+            x, y = pt['x'], pt['y']
+        if offset:
+            x += int(offset[0])
+            y += int(offset[1])
+        return {"x": x, "y": y}
+
+
+def _to_point(pos) -> dict:
+    """将坐标转为 {x, y} 字典。
+
+    支持 (x, y) tuple/list 和 {x, y} dict。
+    """
+    if isinstance(pos, dict):
+        return {"x": int(pos['x']), "y": int(pos['y'])}
+    if isinstance(pos, (list, tuple)) and len(pos) >= 2:
+        return {"x": int(pos[0]), "y": int(pos[1])}
+    raise DevhelmError("无效的坐标: %r" % (pos,))
+
+
+# UiDirection 枚举值（设备端数字编码）
+_UIDIRECTION_MAP = {"LEFT": 0, "RIGHT": 1, "UP": 2, "DOWN": 3}
+
+
+def _to_selector(target) -> Optional[SelectorSpec]:
+    """将 target 转为 SelectorSpec。"""
+    if isinstance(target, SelectorSpec):
+        return target
+    if isinstance(target, dict):
+        return build_selector(**target)
+    if isinstance(target, str):
+        return build_selector(text=target)
+    return None