PyClickerRPA 0.6.0__tar.gz → 0.9.0__tar.gz

{pyclickerrpa-0.6.0 → pyclickerrpa-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyClickerRPA
-Version: 0.6.0
+Version: 0.9.0
 Summary: Visual UI automation & testing tool: Windows + Android(ADB) automation, robust/self-healing image matching, OCR, structured conditions and loops with array iteration, node flow editor, smart recorder, task health checks and failure attribution, a visual test framework (assertions, visual regression, HTML/JUnit reports) and a web console.
 Author: Equinox
 License-Expression: MIT

{pyclickerrpa-0.6.0 → pyclickerrpa-0.9.0}/PyClickerRPA.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyClickerRPA
-Version: 0.6.0
+Version: 0.9.0
 Summary: Visual UI automation & testing tool: Windows + Android(ADB) automation, robust/self-healing image matching, OCR, structured conditions and loops with array iteration, node flow editor, smart recorder, task health checks and failure attribution, a visual test framework (assertions, visual regression, HTML/JUnit reports) and a web console.
 Author: Equinox
 License-Expression: MIT

{pyclickerrpa-0.6.0 → pyclickerrpa-0.9.0}/PyClickerRPA.egg-info/SOURCES.txt

@@ -8,19 +8,27 @@ PyClickerRPA.egg-info/entry_points.txt
 PyClickerRPA.egg-info/requires.txt
 PyClickerRPA.egg-info/top_level.txt
 autoclicker/__init__.py
+autoclicker/actions.py
 autoclicker/adb.py
 autoclicker/app.py
 autoclicker/capture.py
 autoclicker/clicker.py
+autoclicker/controllers.py
 autoclicker/diagnose.py
 autoclicker/dpi.py
 autoclicker/expr.py
 autoclicker/lint.py
 autoclicker/matcher.py
+autoclicker/migrations.py
 autoclicker/models.py
 autoclicker/ocr.py
+autoclicker/recognizers.py
+autoclicker/reports.py
+autoclicker/resources.py
 autoclicker/run.py
 autoclicker/runner.py
+autoclicker/sandbox.py
+autoclicker/task_queue.py
 autoclicker/templatize.py
 autoclicker/windows.py
 autoclicker/gui/__init__.py
@@ -29,15 +37,20 @@ autoclicker/gui/flow_editor.py
 autoclicker/gui/flow_node.py
 autoclicker/gui/hotkeys.py
 autoclicker/gui/lint_dialog.py
+autoclicker/gui/log_panel.py
 autoclicker/gui/main_window.py
 autoclicker/gui/monitor.py
 autoclicker/gui/preview_label.py
+autoclicker/gui/property_panel.py
 autoclicker/gui/qt_runner.py
+autoclicker/gui/queue_panel.py
 autoclicker/gui/recorder.py
 autoclicker/gui/scheduler_widget.py
 autoclicker/gui/snippet_library.py
+autoclicker/gui/step_list_widget.py
 autoclicker/gui/task_widget.py
 autoclicker/gui/testkit_widget.py
+autoclicker/gui/var_panel.py
 autoclicker/testkit/__init__.py
 autoclicker/testkit/__main__.py
 autoclicker/testkit/assertions.py
@@ -56,18 +69,28 @@ autoclicker/web/server.py
 autoclicker/web/static/app.js
 autoclicker/web/static/index.html
 autoclicker/web/static/style.css
+tests/test_actions.py
 tests/test_adb.py
 tests/test_diagnose.py
 tests/test_diagnose_gui.py
+tests/test_engine_integration.py
+tests/test_engine_services.py
 tests/test_flow_branch.py
 tests/test_lint.py
+tests/test_listener_lifecycle.py
 tests/test_matcher.py
+tests/test_migrations.py
 tests/test_models.py
+tests/test_phase4_integration.py
+tests/test_platform_recognition.py
+tests/test_queue_entrypoints.py
 tests/test_recorder_gui.py
 tests/test_runner.py
+tests/test_sandbox.py
 tests/test_structured_flow.py
 tests/test_structured_gui.py
 tests/test_templatize.py
 tests/test_testkit.py
+tests/test_testkit_contracts.py
 tests/test_testkit_gui.py
 tests/test_web.py

pyclickerrpa-0.9.0/autoclicker/actions.py

@@ -0,0 +1,450 @@
+"""Action registry for the task engine.
+
+Every built-in step has its own handler. Structured flow and recognition helpers
+remain on the runner; handlers lazily import its result enum to avoid a cycle.
+Third-party handlers can use enum values or custom strings, and replacing an
+existing handler requires ``replace=True``.
+"""
+from __future__ import annotations
+
+import random
+import threading
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Callable, Optional
+
+from autoclicker.models import Step, StepType
+
+if TYPE_CHECKING:
+    from autoclicker.runner import StepResult
+
+
+@dataclass
+class ExecutionContext:
+    """Shared backends and runner helpers available to an action."""
+    runner: Any
+    screenshot: Optional[Callable] = None
+    clicker: Any = None
+    matcher: Any = None
+    vars: dict[str, str] = field(default_factory=dict)
+    log: Callable[[str], None] = lambda msg: None
+    stop_event: Any = None
+    allow_unsafe_scripts: bool = False
+    load_template: Optional[Callable] = None
+
+    def sleep_ms(self, ms: int) -> None:
+        self.runner._sleep_ms(ms)
+
+    def interp(self, template: str) -> str:
+        return self.runner._interp_required(template)
+
+
+ActionHandler = Callable[[ExecutionContext, Step], "StepResult"]
+_ACTION_REGISTRY: dict[StepType | str, ActionHandler] = {}
+_registry_lock = threading.RLock()
+_installed = False
+
+
+def _action_key(step_type: StepType | str) -> StepType | str:
+    if isinstance(step_type, StepType):
+        return step_type
+    if not isinstance(step_type, str):
+        raise TypeError("step_type must be a StepType or str")
+    # Do not call StepType(value): its legacy _missing_ maps unknowns to Wait.
+    return StepType._value2member_map_.get(step_type, step_type)
+
+
+def register_action(step_type: StepType | str, *, replace: bool = False):
+    """Register a handler; reject duplicates unless explicitly replacing them."""
+    key = _action_key(step_type)
+
+    def decorator(fn: ActionHandler) -> ActionHandler:
+        if not callable(fn):
+            raise TypeError("action handler must be callable")
+        _install()
+        with _registry_lock:
+            if key in _ACTION_REGISTRY and not replace:
+                raise ValueError(f"Action already registered: {key}")
+            _ACTION_REGISTRY[key] = fn
+        return fn
+
+    return decorator
+
+
+def registered_actions() -> list[StepType | str]:
+    """Return installed built-in and custom types in deterministic value order."""
+    _install()
+    with _registry_lock:
+        return sorted(_ACTION_REGISTRY,
+                      key=lambda t: t.value if isinstance(t, StepType) else t)
+
+
+def get_action(step_type: StepType | str) -> Optional[ActionHandler]:
+    """Return a handler, or None for an unknown type (never a Wait fallback)."""
+    key = _action_key(step_type)
+    _install()
+    with _registry_lock:
+        return _ACTION_REGISTRY.get(key)
+
+
+def exec_click_image(ctx: ExecutionContext, step: Step) -> StepResult:
+    return ctx.runner._exec_image_poll(step, StepType.ClickImage)
+
+
+def exec_click_text(ctx: ExecutionContext, step: Step) -> StepResult:
+    return ctx.runner._exec_click_text(step)
+
+
+def exec_click_position(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    cx, cy = step.x, step.y
+    if step.varName == "use_var":
+        cx = int(ctx.vars.get("last_x", "0"))
+        cy = int(ctx.vars.get("last_y", "0"))
+    cx = ctx.runner._rand_offset(cx, step.randomOffset)
+    cy = ctx.runner._rand_offset(cy, step.randomOffset)
+    ctx.log(f"  点击 ({cx}, {cy})")
+    ctx.clicker.click(ctx.runner.target_hwnd, cx, cy)
+    return StepResult.Success
+
+
+def exec_wait(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    ctx.log(f"  等待 {step.waitMs}ms")
+    ctx.sleep_ms(step.waitMs)
+    return StepResult.Success
+
+
+def exec_loop(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    return StepResult.Success
+
+
+def exec_if_image_found(ctx: ExecutionContext, step: Step) -> StepResult:
+    return ctx.runner._exec_if_image(step)
+
+
+def exec_if_text_found(ctx: ExecutionContext, step: Step) -> StepResult:
+    result, ctx.runner._last_condition = ctx.runner._evaluate_condition(step, StepType.IfTextFound)
+    return result
+
+
+def exec_if_else(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    ctx.log(f"  If/Else 分支 (上次条件: {'true' if ctx.runner._last_condition else 'false'})")
+    return StepResult.Success
+
+
+def exec_call_sub(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    if not step.subTaskPath:
+        ctx.log("  错误: 未指定子任务路径")
+        return StepResult.Fail
+    # T1-4: the outputs mapping belongs to THIS CallSub step; the runner must
+    # not scan the task for "the first CallSub" (wrong for multiple/nested subs).
+    return ctx.runner._run_subtask(step.subTaskPath, step.params.get("outputs"))
+
+
+def exec_set_var(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    value = step.varValue
+    typed = getattr(ctx.runner.task, "variable_mode", "legacy") == "typed"
+    if typed and isinstance(value, (bool, int, float, list)):
+        pass  # native value assigned as-is
+    elif value.startswith("++"):
+        value = int(ctx.vars.get(step.varName, 0)) + 1
+        if not typed:
+            value = str(value)
+    elif value.startswith("--"):
+        value = int(ctx.vars.get(step.varName, 0)) - 1
+        if not typed:
+            value = str(value)
+    elif value.startswith("="):
+        from autoclicker import expr
+        try:
+            value = expr.safe_eval(value[1:], ctx.vars, typed=typed)
+        except Exception as e:  # noqa: BLE001 - recoverable step failure
+            ctx.log(f"  表达式错误: {e}")
+            return StepResult.Fail
+    else:
+        value = ctx.interp(value)
+    ctx.vars[step.varName] = value
+    ctx.runner.cb.var_changed(step.varName, value)
+    ctx.log(f"  变量 {step.varName} = {value}")
+    return StepResult.Success
+
+
+def exec_random_wait(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    lo, hi = step.waitMs, step.waitMsMax
+    if hi <= lo:
+        hi = lo + 1
+    actual = random.randint(lo, hi - 1)
+    ctx.log(f"  随机等待 {actual}ms (范围 {lo}~{hi})")
+    ctx.sleep_ms(actual)
+    return StepResult.Success
+
+
+def exec_key_press(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    from autoclicker.clicker import parse_vk
+    vk = parse_vk(step.keyName)
+    if vk == 0:
+        ctx.log(f'  错误: 无效按键 "{step.keyName}"')
+        return StepResult.Fail
+    ctx.log(f"  按键: {step.keyName}")
+    ctx.clicker.key_press(vk)
+    return StepResult.Success
+
+
+def exec_type_text(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    text = ctx.interp(step.text)
+    ctx.log(f'  输入文字: "{text}"')
+    ctx.clicker.type_text(text)
+    return StepResult.Success
+
+
+def exec_hotkey(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    from autoclicker.clicker import parse_vk
+    mod, vk = parse_vk(step.modifierKey), parse_vk(step.keyName)
+    if vk == 0:
+        ctx.log("  错误: 无效按键")
+        return StepResult.Fail
+    ctx.log(f"  快捷键: {step.modifierKey}+{step.keyName}")
+    ctx.clicker.hotkey(mod, vk)
+    return StepResult.Success
+
+
+def exec_long_press(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    ctx.log(f"  长按 ({step.x}, {step.y}) {step.holdMs}ms")
+    ctx.clicker.long_press(ctx.runner.target_hwnd, step.x, step.y, step.holdMs)
+    return StepResult.Success
+
+
+def exec_drag(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    ctx.log(f"  拖拽 ({step.x},{step.y}) → ({step.x2},{step.y2}) {step.durationMs}ms")
+    ctx.clicker.drag(ctx.runner.target_hwnd, step.x, step.y, step.x2, step.y2, step.durationMs)
+    return StepResult.Success
+
+
+def exec_pinch(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    ctx.log(f"  捏合 中心({step.x},{step.y}) {step.pinchStartDist}→{step.pinchEndDist}")
+    ctx.clicker.pinch(ctx.runner.target_hwnd, step.x, step.y,
+                      step.pinchStartDist, step.pinchEndDist, step.durationMs)
+    return StepResult.Success
+
+
+def exec_wait_image(ctx: ExecutionContext, step: Step) -> StepResult:
+    return ctx.runner._exec_image_poll(step, StepType.WaitImage)
+
+
+def exec_wait_image_gone(ctx: ExecutionContext, step: Step) -> StepResult:
+    return ctx.runner._exec_image_poll(step, StepType.WaitImageGone)
+
+
+def exec_scroll(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    ctx.log(f"  滚轮 ({step.x},{step.y}) {step.scrollAmount}格")
+    ctx.clicker.scroll(ctx.runner.target_hwnd, step.x, step.y, step.scrollAmount)
+    return StepResult.Success
+
+
+def exec_if_color_match(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    screen = ctx.screenshot()
+    if screen.size == 0 or step.x >= screen.shape[1] or step.y >= screen.shape[0]:
+        ctx.runner._last_condition = False
+        return StepResult.Success
+    ctx.runner._last_condition = ctx.runner._color_at_matches(
+        screen, step.x, step.y, step.targetColor, step.colorTolerance)
+    ctx.log(f"  条件(颜色): ({step.x},{step.y}) vs {step.targetColor} → "
+            f"{'true' if ctx.runner._last_condition else 'false'}")
+    return StepResult.Success
+
+
+def exec_do_until(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    return StepResult.Success
+
+
+def exec_merge_image(ctx: ExecutionContext, step: Step) -> StepResult:
+    return ctx.runner._exec_image_poll(step, StepType.MergeImage)
+
+
+def exec_multi_drag(ctx: ExecutionContext, step: Step) -> StepResult:
+    return ctx.runner._exec_multidrag(step)
+
+
+def exec_goto(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    return StepResult.Success
+
+
+def exec_if_image_count(ctx: ExecutionContext, step: Step) -> StepResult:
+    return ctx.runner._exec_if_image_count(step)
+
+
+def exec_if_var(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    val = ctx.vars.get(step.varName, "0")
+    ctx.runner._last_condition = ctx.runner._compare(val, step.compareOp, ctx.interp(step.compareValue))
+    ctx.log(f"  条件(变量): {step.varName}={val} {step.compareOp} {step.compareValue} → "
+            f"{'true' if ctx.runner._last_condition else 'false'}")
+    return StepResult.Success
+
+
+def exec_click_all(ctx: ExecutionContext, step: Step) -> StepResult:
+    return ctx.runner._exec_click_all(step)
+
+
+def exec_group_begin(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    return StepResult.Success
+
+
+def exec_group_end(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    return StepResult.Success
+
+
+def exec_while_condition(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    return StepResult.Success
+
+
+def exec_read_text(ctx: ExecutionContext, step: Step) -> StepResult:
+    return ctx.runner._exec_read_text(step)
+
+
+def exec_click_relative(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    bx = int(ctx.vars.get("last_x", "0")) + step.x
+    by = int(ctx.vars.get("last_y", "0")) + step.y
+    cx = ctx.runner._rand_offset(bx, step.randomOffset)
+    cy = ctx.runner._rand_offset(by, step.randomOffset)
+    ctx.log(f"  相对点击 last+({step.x},{step.y}) = ({cx}, {cy})")
+    ctx.clicker.click(ctx.runner.target_hwnd, cx, cy)
+    return StepResult.Success
+
+
+def exec_http_request(ctx: ExecutionContext, step: Step) -> StepResult:
+    return ctx.runner._exec_http(step)
+
+
+def exec_run_script(ctx: ExecutionContext, step: Step) -> StepResult:
+    return ctx.runner._exec_script(step)
+
+
+def exec_drag_image(ctx: ExecutionContext, step: Step) -> StepResult:
+    return ctx.runner._exec_drag_image(step)
+
+
+def exec_wait_stable(ctx: ExecutionContext, step: Step) -> StepResult:
+    return ctx.runner._exec_wait_stable(step)
+
+
+def exec_activate_window(ctx: ExecutionContext, step: Step) -> StepResult:
+    return ctx.runner._exec_activate_window(step)
+
+
+def exec_stop(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    ctx.log("  结束任务")
+    ctx.runner._running = False
+    return StepResult.Success
+
+
+def exec_if_block(ctx: ExecutionContext, step: Step) -> StepResult:
+    return ctx.runner._exec_block(step)
+
+
+def exec_repeat_block(ctx: ExecutionContext, step: Step) -> StepResult:
+    return ctx.runner._exec_block(step)
+
+
+def exec_while_block(ctx: ExecutionContext, step: Step) -> StepResult:
+    return ctx.runner._exec_block(step)
+
+
+def exec_for_each(ctx: ExecutionContext, step: Step) -> StepResult:
+    return ctx.runner._exec_block(step)
+
+
+def exec_break(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    if ctx.runner._loop_depth == 0:
+        ctx.log("  退出循环 / 下一轮只能放在循环体内")
+        return StepResult.Abort
+    return StepResult.Break
+
+
+def exec_continue(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    if ctx.runner._loop_depth == 0:
+        ctx.log("  退出循环 / 下一轮只能放在循环体内")
+        return StepResult.Abort
+    return StepResult.Continue
+
+
+_BUILTIN_ACTIONS: dict[StepType, ActionHandler] = {
+    StepType.ClickImage: exec_click_image,
+    StepType.ClickText: exec_click_text,
+    StepType.ClickPosition: exec_click_position,
+    StepType.Wait: exec_wait,
+    StepType.Loop: exec_loop,
+    StepType.IfImageFound: exec_if_image_found,
+    StepType.IfTextFound: exec_if_text_found,
+    StepType.IfElse: exec_if_else,
+    StepType.CallSub: exec_call_sub,
+    StepType.SetVar: exec_set_var,
+    StepType.RandomWait: exec_random_wait,
+    StepType.KeyPress: exec_key_press,
+    StepType.TypeText: exec_type_text,
+    StepType.Hotkey: exec_hotkey,
+    StepType.LongPress: exec_long_press,
+    StepType.Drag: exec_drag,
+    StepType.Pinch: exec_pinch,
+    StepType.WaitImage: exec_wait_image,
+    StepType.WaitImageGone: exec_wait_image_gone,
+    StepType.Scroll: exec_scroll,
+    StepType.IfColorMatch: exec_if_color_match,
+    StepType.DoUntil: exec_do_until,
+    StepType.MergeImage: exec_merge_image,
+    StepType.MultiDrag: exec_multi_drag,
+    StepType.Goto: exec_goto,
+    StepType.IfImageCount: exec_if_image_count,
+    StepType.IfVar: exec_if_var,
+    StepType.ClickAll: exec_click_all,
+    StepType.GroupBegin: exec_group_begin,
+    StepType.GroupEnd: exec_group_end,
+    StepType.WhileCondition: exec_while_condition,
+    StepType.ReadText: exec_read_text,
+    StepType.ClickRelative: exec_click_relative,
+    StepType.HttpRequest: exec_http_request,
+    StepType.RunScript: exec_run_script,
+    StepType.DragImage: exec_drag_image,
+    StepType.WaitStable: exec_wait_stable,
+    StepType.ActivateWindow: exec_activate_window,
+    StepType.Stop: exec_stop,
+    StepType.IfBlock: exec_if_block,
+    StepType.RepeatBlock: exec_repeat_block,
+    StepType.WhileBlock: exec_while_block,
+    StepType.ForEach: exec_for_each,
+    StepType.Break: exec_break,
+    StepType.Continue: exec_continue,
+}
+
+
+def _install() -> None:
+    """Install built-ins once, atomically, without overwriting user handlers."""
+    global _installed
+    with _registry_lock:
+        if _installed:
+            return
+        for step_type, handler in _BUILTIN_ACTIONS.items():
+            _ACTION_REGISTRY.setdefault(step_type, handler)
+        _installed = True

{pyclickerrpa-0.6.0 → pyclickerrpa-0.9.0}/autoclicker/adb.py

@@ -6,6 +6,7 @@
 from __future__ import annotations
 
 import subprocess
+from math import isfinite
 
 import numpy as np
 
@@ -33,9 +34,12 @@ def _vk_to_android(vk: int) -> int | None:
 
 
 class AdbDevice:
-    def __init__(self, serial: str | None = None, adb: str = "adb"):
+    def __init__(self, serial: str | None = None, adb: str = "adb", *, timeout_s: float = 10):
+        if isinstance(timeout_s, bool) or not isfinite(timeout_s) or timeout_s <= 0:
+            raise ValueError("timeout_s must be finite and positive")
         self.serial = serial
         self.adb = adb
+        self.timeout_s = timeout_s
 
     def _cmd(self, args: list[str]) -> list[str]:
         base = [self.adb]
@@ -46,13 +50,29 @@ class AdbDevice:
     def _run(self, args: list[str]) -> bytes:
         try:
             proc = subprocess.run(self._cmd(args), stdout=subprocess.PIPE,
-                                  stderr=subprocess.PIPE)
+                                  stderr=subprocess.PIPE, timeout=self.timeout_s)
+        except subprocess.TimeoutExpired as e:
+            raise RuntimeError(f"adb {' '.join(args)} 超时 ({self.timeout_s}s)") from e
         except FileNotFoundError as e:
             raise RuntimeError(f"找不到 adb 可执行文件 '{self.adb}'，请安装 Android Platform Tools 并加入 PATH") from e
         if proc.returncode != 0:
             raise RuntimeError(f"adb {' '.join(args)} 失败: {proc.stderr.decode('utf-8', 'replace').strip()}")
         return proc.stdout
 
+    def connect(self):
+        state = self._run(["get-state"]).decode("utf-8", "replace").strip()
+        if state != "device":
+            raise RuntimeError(f"ADB device is not connected: {state!r}")
+        return True
+
+    def disconnect(self):
+        # Release this local CLI handle, never 'adb disconnect' a shared device.
+        return None
+
+    def reconnect(self):
+        self.disconnect()
+        return self.connect()
+
     # ---- capture ----
     def screencap(self) -> np.ndarray:
         """截图 -> BGR ndarray（exec-out 避免 stdout CRLF 转换的坑）。"""
@@ -82,10 +102,14 @@ class AdbDevice:
         self._run(["shell", "input", "keyevent", str(int(code))])
 
     @staticmethod
-    def list_devices(adb: str = "adb") -> list[str]:
+    def list_devices(adb: str = "adb", *, timeout_s: float = 10) -> list[str]:
+        if isinstance(timeout_s, bool) or not isfinite(timeout_s) or timeout_s <= 0:
+            raise ValueError("timeout_s must be finite and positive")
         try:
             out = subprocess.run([adb, "devices"], stdout=subprocess.PIPE,
-                                 stderr=subprocess.PIPE).stdout.decode("utf-8", "replace")
+                                 stderr=subprocess.PIPE, timeout=timeout_s).stdout.decode("utf-8", "replace")
+        except subprocess.TimeoutExpired as e:
+            raise RuntimeError(f"adb devices 超时 ({timeout_s}s)") from e
         except FileNotFoundError:
             return []
         serials = []
@@ -121,7 +145,7 @@ class AdbClicker:
         self.device.tap(x, y)
 
     def right_click(self, hwnd, x: int, y: int) -> None:
-        self.device.tap(x, y)          # Android 无右键，退化为点击
+        raise NotImplementedError("ADB input does not support right click; use click for a tap")
 
     def long_press(self, hwnd, x: int, y: int, hold_ms: int) -> None:
         self.device.long_press(x, y, hold_ms)
@@ -141,20 +165,21 @@ class AdbClicker:
 
     def key_press(self, vk: int) -> None:
         code = _vk_to_android(vk)
-        if code is not None:
-            self.device.keyevent(code)
+        if code is None:
+            raise NotImplementedError(f"ADB has no mapping for virtual key {vk!r}")
+        self.device.keyevent(code)
 
     def key_down(self, vk: int) -> None:
-        self.key_press(vk)
+        raise NotImplementedError("ADB input does not support held keys")
 
     def key_up(self, vk: int) -> None:
-        pass
+        raise NotImplementedError("ADB input does not support held keys")
 
     def hotkey(self, modifier: int, vk: int) -> None:
-        self.key_press(vk)             # Android input 无组合键，尽力而为
+        raise NotImplementedError("ADB input does not support hotkeys")
 
     def pinch(self, hwnd, cx, cy, start_dist, end_dist, duration_ms: int = 400) -> None:
-        pass                           # adb input 不支持多点触控，跳过
+        raise NotImplementedError("ADB input does not support multi-touch pinch")
 
 
 def make_adb_backends(serial: str | None = None, adb: str = "adb"):