PyClickerRPA 0.1.0__tar.gz → 0.3.0__tar.gz

pyclickerrpa-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Equinox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyclickerrpa-0.3.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: PyClickerRPA
+Version: 0.3.0
+Summary: Visual UI automation & testing tool: Windows + Android(ADB) automation, robust/self-healing image matching, OCR, node flow editor, recorder, a visual test framework (assertions, visual regression, HTML/JUnit reports) and a web console.
+Author: Equinox
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Equinox/PyClickerRPA
+Keywords: autoclicker,rpa,automation,opencv,template-matching,ocr,gui,windows,android,adb,testing,visual-regression,ui-testing
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Desktop Environment
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Multimedia :: Graphics :: Capture :: Screen Capture
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: opencv-python>=4.8
+Requires-Dist: pywin32>=305; sys_platform == "win32"
+Requires-Dist: pynput>=1.7
+Requires-Dist: PySide6>=6.5
+Provides-Extra: ocr
+Requires-Dist: paddleocr>=2.7; extra == "ocr"
+Requires-Dist: paddlepaddle>=2.5; extra == "ocr"
+Provides-Extra: web
+Requires-Dist: fastapi>=0.110; extra == "web"
+Requires-Dist: uvicorn[standard]>=0.27; extra == "web"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: httpx>=0.24; extra == "dev"
+Dynamic: license-file
+
+# PyClickerRPA
+
+A visual UI **automation & testing** tool. Automate Windows apps *and* Android
+devices/emulators by what's on screen — image/text matching + mouse/keyboard (or
+ADB) input — then turn those flows into a **visual test framework** with
+assertions, visual-regression baselines, HTML/JUnit reports, and a **web console**
+for remote runs.
+
+Python/PySide6, started as a port of a Qt/C++ AutoClicker (still reads/writes the
+same `.json` task format).
+
+## Install
+
+```
+pip install PyClickerRPA
+```
+
+Optional extras:
+
+```
+pip install "PyClickerRPA[ocr]"   # PaddleOCR — find-text / read-text steps
+pip install "PyClickerRPA[web]"   # FastAPI + uvicorn — web console
+```
+
+## Entry points
+
+```
+autoclicker                          # desktop GUI (flow editor / list editor / test tab)
+autoclicker-run task.json --window "Notepad"   # headless run against a window
+autoclicker-run task.json --adb                # run against an Android device (adb)
+autoclicker-testkit suite.json --report out.html --junit out.xml   # run a test suite
+autoclicker-web --suites-dir examples          # web console at http://127.0.0.1:8000
+```
+
+## Automation engine
+
+- **Targets**: any visible window, the whole screen (multi-monitor + high-DPI
+  aware), or an **Android device/emulator via ADB** (`--adb [serial]`).
+- **Image matching**: OpenCV template match with **self-healing** by default —
+  template → multi-scale → **ORB feature match** fallback (survives scaling /
+  minor UI changes); **transparent-mask** templates (PNG alpha) ignore
+  don't-care regions. Per-step `matchMode` = `robust` / `template` / `feature`.
+- **Also**: pixel-color checks, optional PaddleOCR text find / read-to-variable.
+- **Smart wait**: `wait_stable` waits until the screen (or an ROI) stops
+  changing — replaces guessed `sleep`s (fast when ready, patient when slow).
+- **~30+ step types**: click image/text/position, click-all, relative/offset
+  clicks, wait / random / wait-stable, drag / long-press / pinch / scroll,
+  key / type / hotkey, loop / goto / while / do-until, if image/text/color/
+  count/var with **true/false branching** (if-else), set-var, read-text→variable,
+  activate-window, HTTP request, run-Python-script, call sub-task, groups, and a
+  **stop** step to end a run — with retry / repeat / until policies.
+
+## Authoring (desktop GUI)
+
+Drag-and-drop **node flow graph** (condition nodes have **true/false branch
+ports** for visual if-else; a terminal **stop** node ends the flow) and an
+interoperable **step list** with a full
+per-step dialog; an action **recorder** (global hooks), snippet library, task
+packages (`.zip` with templates), on-preview coordinate/color picking, template
+crop, single-step test run; global hotkeys (F6 run/stop, ESC stop), scheduler,
+and an image/color **monitor/trigger** with tray icon; a **Test** tab to load and
+run visual test suites.
+
+## Visual test framework (`autoclicker.testkit`)
+
+Turn automation into tests:
+
+- **Assertions**: image / text / color present-or-absent, variable comparison.
+- **Visual regression**: baseline diff (first run captures the baseline; later
+  runs flag changed-pixel ratio and emit a baseline|actual|heatmap image).
+- **Cases & suites**: declarative JSON suites *or* pytest fixtures (`screen`,
+  `visual`); **data-driven** cases (a data table / CSV runs the case per row).
+- **Reports**: self-contained **HTML** (embedded screenshots + per-step
+  timeline, optional GIF) and **JUnit XML** for CI; retries mark **flaky**.
+
+```python
+# pytest style
+def test_login(screen, visual):
+    screen.assert_image("assets/login_btn.png")
+    screen.assert_text("Username")
+    visual.check("login.png", tolerance=0.02)
+```
+
+## Web console (`autoclicker-web`)
+
+Browser UI to trigger suites (single or batched), watch **live per-line logs**
+and per-case results, schedule recurring runs, list ADB devices and grab
+**screenshots**, browse **persisted run history**, and open the HTML report — all
+served by FastAPI with a zero-build vanilla-JS front end.
+
+## Notes
+
+- Host is **Windows** (Win32 capture + `SendInput`); ADB targets are
+  cross-platform via the `adb` CLI (must be on `PATH`).
+- OCR's first run downloads PaddleOCR models (~100 MB).
+- Some target windows may require running as administrator.
+
+## License
+
+MIT

pyclickerrpa-0.3.0/PyClickerRPA.egg-info/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: PyClickerRPA
+Version: 0.3.0
+Summary: Visual UI automation & testing tool: Windows + Android(ADB) automation, robust/self-healing image matching, OCR, node flow editor, recorder, a visual test framework (assertions, visual regression, HTML/JUnit reports) and a web console.
+Author: Equinox
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Equinox/PyClickerRPA
+Keywords: autoclicker,rpa,automation,opencv,template-matching,ocr,gui,windows,android,adb,testing,visual-regression,ui-testing
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Desktop Environment
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Multimedia :: Graphics :: Capture :: Screen Capture
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: opencv-python>=4.8
+Requires-Dist: pywin32>=305; sys_platform == "win32"
+Requires-Dist: pynput>=1.7
+Requires-Dist: PySide6>=6.5
+Provides-Extra: ocr
+Requires-Dist: paddleocr>=2.7; extra == "ocr"
+Requires-Dist: paddlepaddle>=2.5; extra == "ocr"
+Provides-Extra: web
+Requires-Dist: fastapi>=0.110; extra == "web"
+Requires-Dist: uvicorn[standard]>=0.27; extra == "web"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: httpx>=0.24; extra == "dev"
+Dynamic: license-file
+
+# PyClickerRPA
+
+A visual UI **automation & testing** tool. Automate Windows apps *and* Android
+devices/emulators by what's on screen — image/text matching + mouse/keyboard (or
+ADB) input — then turn those flows into a **visual test framework** with
+assertions, visual-regression baselines, HTML/JUnit reports, and a **web console**
+for remote runs.
+
+Python/PySide6, started as a port of a Qt/C++ AutoClicker (still reads/writes the
+same `.json` task format).
+
+## Install
+
+```
+pip install PyClickerRPA
+```
+
+Optional extras:
+
+```
+pip install "PyClickerRPA[ocr]"   # PaddleOCR — find-text / read-text steps
+pip install "PyClickerRPA[web]"   # FastAPI + uvicorn — web console
+```
+
+## Entry points
+
+```
+autoclicker                          # desktop GUI (flow editor / list editor / test tab)
+autoclicker-run task.json --window "Notepad"   # headless run against a window
+autoclicker-run task.json --adb                # run against an Android device (adb)
+autoclicker-testkit suite.json --report out.html --junit out.xml   # run a test suite
+autoclicker-web --suites-dir examples          # web console at http://127.0.0.1:8000
+```
+
+## Automation engine
+
+- **Targets**: any visible window, the whole screen (multi-monitor + high-DPI
+  aware), or an **Android device/emulator via ADB** (`--adb [serial]`).
+- **Image matching**: OpenCV template match with **self-healing** by default —
+  template → multi-scale → **ORB feature match** fallback (survives scaling /
+  minor UI changes); **transparent-mask** templates (PNG alpha) ignore
+  don't-care regions. Per-step `matchMode` = `robust` / `template` / `feature`.
+- **Also**: pixel-color checks, optional PaddleOCR text find / read-to-variable.
+- **Smart wait**: `wait_stable` waits until the screen (or an ROI) stops
+  changing — replaces guessed `sleep`s (fast when ready, patient when slow).
+- **~30+ step types**: click image/text/position, click-all, relative/offset
+  clicks, wait / random / wait-stable, drag / long-press / pinch / scroll,
+  key / type / hotkey, loop / goto / while / do-until, if image/text/color/
+  count/var with **true/false branching** (if-else), set-var, read-text→variable,
+  activate-window, HTTP request, run-Python-script, call sub-task, groups, and a
+  **stop** step to end a run — with retry / repeat / until policies.
+
+## Authoring (desktop GUI)
+
+Drag-and-drop **node flow graph** (condition nodes have **true/false branch
+ports** for visual if-else; a terminal **stop** node ends the flow) and an
+interoperable **step list** with a full
+per-step dialog; an action **recorder** (global hooks), snippet library, task
+packages (`.zip` with templates), on-preview coordinate/color picking, template
+crop, single-step test run; global hotkeys (F6 run/stop, ESC stop), scheduler,
+and an image/color **monitor/trigger** with tray icon; a **Test** tab to load and
+run visual test suites.
+
+## Visual test framework (`autoclicker.testkit`)
+
+Turn automation into tests:
+
+- **Assertions**: image / text / color present-or-absent, variable comparison.
+- **Visual regression**: baseline diff (first run captures the baseline; later
+  runs flag changed-pixel ratio and emit a baseline|actual|heatmap image).
+- **Cases & suites**: declarative JSON suites *or* pytest fixtures (`screen`,
+  `visual`); **data-driven** cases (a data table / CSV runs the case per row).
+- **Reports**: self-contained **HTML** (embedded screenshots + per-step
+  timeline, optional GIF) and **JUnit XML** for CI; retries mark **flaky**.
+
+```python
+# pytest style
+def test_login(screen, visual):
+    screen.assert_image("assets/login_btn.png")
+    screen.assert_text("Username")
+    visual.check("login.png", tolerance=0.02)
+```
+
+## Web console (`autoclicker-web`)
+
+Browser UI to trigger suites (single or batched), watch **live per-line logs**
+and per-case results, schedule recurring runs, list ADB devices and grab
+**screenshots**, browse **persisted run history**, and open the HTML report — all
+served by FastAPI with a zero-build vanilla-JS front end.
+
+## Notes
+
+- Host is **Windows** (Win32 capture + `SendInput`); ADB targets are
+  cross-platform via the `adb` CLI (must be on `PATH`).
+- OCR's first run downloads PaddleOCR models (~100 MB).
+- Some target windows may require running as administrator.
+
+## License
+
+MIT

{pyclickerrpa-0.1.0 → pyclickerrpa-0.3.0}/PyClickerRPA.egg-info/SOURCES.txt

@@ -1,3 +1,4 @@
+LICENSE
 README.md
 pyproject.toml
 PyClickerRPA.egg-info/PKG-INFO
@@ -7,6 +8,7 @@ PyClickerRPA.egg-info/entry_points.txt
 PyClickerRPA.egg-info/requires.txt
 PyClickerRPA.egg-info/top_level.txt
 autoclicker/__init__.py
+autoclicker/adb.py
 autoclicker/app.py
 autoclicker/capture.py
 autoclicker/clicker.py
@@ -30,6 +32,30 @@ autoclicker/gui/recorder.py
 autoclicker/gui/scheduler_widget.py
 autoclicker/gui/snippet_library.py
 autoclicker/gui/task_widget.py
+autoclicker/gui/testkit_widget.py
+autoclicker/testkit/__init__.py
+autoclicker/testkit/__main__.py
+autoclicker/testkit/assertions.py
+autoclicker/testkit/case.py
+autoclicker/testkit/loader.py
+autoclicker/testkit/pytest_plugin.py
+autoclicker/testkit/report.py
+autoclicker/testkit/runner.py
+autoclicker/testkit/visual.py
+autoclicker/web/__init__.py
+autoclicker/web/__main__.py
+autoclicker/web/run_manager.py
+autoclicker/web/scheduler.py
+autoclicker/web/serialize.py
+autoclicker/web/server.py
+autoclicker/web/static/app.js
+autoclicker/web/static/index.html
+autoclicker/web/static/style.css
+tests/test_adb.py
+tests/test_flow_branch.py
 tests/test_matcher.py
 tests/test_models.py
-tests/test_runner.py
+tests/test_runner.py
+tests/test_testkit.py
+tests/test_testkit_gui.py
+tests/test_web.py

{pyclickerrpa-0.1.0 → pyclickerrpa-0.3.0}/PyClickerRPA.egg-info/entry_points.txt

@@ -1,5 +1,7 @@
 [console_scripts]
 autoclicker-run = autoclicker.run:main
+autoclicker-testkit = autoclicker.testkit.__main__:main
+autoclicker-web = autoclicker.web.__main__:main
 
 [gui_scripts]
 autoclicker = autoclicker.app:main

{pyclickerrpa-0.1.0 → pyclickerrpa-0.3.0}/PyClickerRPA.egg-info/requires.txt

@@ -6,6 +6,14 @@ PySide6>=6.5
 [:sys_platform == "win32"]
 pywin32>=305
 
+[dev]
+pytest>=7
+httpx>=0.24
+
 [ocr]
 paddleocr>=2.7
 paddlepaddle>=2.5
+
+[web]
+fastapi>=0.110
+uvicorn[standard]>=0.27

pyclickerrpa-0.3.0/README.md

@@ -0,0 +1,100 @@
+# PyClickerRPA
+
+A visual UI **automation & testing** tool. Automate Windows apps *and* Android
+devices/emulators by what's on screen — image/text matching + mouse/keyboard (or
+ADB) input — then turn those flows into a **visual test framework** with
+assertions, visual-regression baselines, HTML/JUnit reports, and a **web console**
+for remote runs.
+
+Python/PySide6, started as a port of a Qt/C++ AutoClicker (still reads/writes the
+same `.json` task format).
+
+## Install
+
+```
+pip install PyClickerRPA
+```
+
+Optional extras:
+
+```
+pip install "PyClickerRPA[ocr]"   # PaddleOCR — find-text / read-text steps
+pip install "PyClickerRPA[web]"   # FastAPI + uvicorn — web console
+```
+
+## Entry points
+
+```
+autoclicker                          # desktop GUI (flow editor / list editor / test tab)
+autoclicker-run task.json --window "Notepad"   # headless run against a window
+autoclicker-run task.json --adb                # run against an Android device (adb)
+autoclicker-testkit suite.json --report out.html --junit out.xml   # run a test suite
+autoclicker-web --suites-dir examples          # web console at http://127.0.0.1:8000
+```
+
+## Automation engine
+
+- **Targets**: any visible window, the whole screen (multi-monitor + high-DPI
+  aware), or an **Android device/emulator via ADB** (`--adb [serial]`).
+- **Image matching**: OpenCV template match with **self-healing** by default —
+  template → multi-scale → **ORB feature match** fallback (survives scaling /
+  minor UI changes); **transparent-mask** templates (PNG alpha) ignore
+  don't-care regions. Per-step `matchMode` = `robust` / `template` / `feature`.
+- **Also**: pixel-color checks, optional PaddleOCR text find / read-to-variable.
+- **Smart wait**: `wait_stable` waits until the screen (or an ROI) stops
+  changing — replaces guessed `sleep`s (fast when ready, patient when slow).
+- **~30+ step types**: click image/text/position, click-all, relative/offset
+  clicks, wait / random / wait-stable, drag / long-press / pinch / scroll,
+  key / type / hotkey, loop / goto / while / do-until, if image/text/color/
+  count/var with **true/false branching** (if-else), set-var, read-text→variable,
+  activate-window, HTTP request, run-Python-script, call sub-task, groups, and a
+  **stop** step to end a run — with retry / repeat / until policies.
+
+## Authoring (desktop GUI)
+
+Drag-and-drop **node flow graph** (condition nodes have **true/false branch
+ports** for visual if-else; a terminal **stop** node ends the flow) and an
+interoperable **step list** with a full
+per-step dialog; an action **recorder** (global hooks), snippet library, task
+packages (`.zip` with templates), on-preview coordinate/color picking, template
+crop, single-step test run; global hotkeys (F6 run/stop, ESC stop), scheduler,
+and an image/color **monitor/trigger** with tray icon; a **Test** tab to load and
+run visual test suites.
+
+## Visual test framework (`autoclicker.testkit`)
+
+Turn automation into tests:
+
+- **Assertions**: image / text / color present-or-absent, variable comparison.
+- **Visual regression**: baseline diff (first run captures the baseline; later
+  runs flag changed-pixel ratio and emit a baseline|actual|heatmap image).
+- **Cases & suites**: declarative JSON suites *or* pytest fixtures (`screen`,
+  `visual`); **data-driven** cases (a data table / CSV runs the case per row).
+- **Reports**: self-contained **HTML** (embedded screenshots + per-step
+  timeline, optional GIF) and **JUnit XML** for CI; retries mark **flaky**.
+
+```python
+# pytest style
+def test_login(screen, visual):
+    screen.assert_image("assets/login_btn.png")
+    screen.assert_text("Username")
+    visual.check("login.png", tolerance=0.02)
+```
+
+## Web console (`autoclicker-web`)
+
+Browser UI to trigger suites (single or batched), watch **live per-line logs**
+and per-case results, schedule recurring runs, list ADB devices and grab
+**screenshots**, browse **persisted run history**, and open the HTML report — all
+served by FastAPI with a zero-build vanilla-JS front end.
+
+## Notes
+
+- Host is **Windows** (Win32 capture + `SendInput`); ADB targets are
+  cross-platform via the `adb` CLI (must be on `PATH`).
+- OCR's first run downloads PaddleOCR models (~100 MB).
+- Some target windows may require running as administrator.
+
+## License
+
+MIT

pyclickerrpa-0.3.0/autoclicker/adb.py

@@ -0,0 +1,163 @@
+"""ADB 设备后端：自动化 Android 手机/模拟器（通用 adb CLI）。
+
+契约与 Windows 后端一致（capture 返回 BGR ndarray、clicker 首参 hwnd 但忽略），
+所以能直接注入 TaskRunner(target_hwnd=None, capture=AdbCapture, clicker=AdbClicker)。
+"""
+from __future__ import annotations
+
+import subprocess
+
+import numpy as np
+
+# Windows VK -> Android keycode（覆盖常用键；其余忽略）
+_VK_TO_ANDROID = {
+    0x0D: 66,   # ENTER
+    0x1B: 4,    # ESC -> BACK
+    0x09: 61,   # TAB
+    0x20: 62,   # SPACE
+    0x08: 67,   # BACKSPACE -> DEL
+    0x2E: 112,  # DELETE -> FORWARD_DEL
+    0x26: 19, 0x28: 20, 0x25: 21, 0x27: 22,  # UP DOWN LEFT RIGHT
+    0x24: 3,    # HOME
+}
+
+
+def _vk_to_android(vk: int) -> int | None:
+    if vk in _VK_TO_ANDROID:
+        return _VK_TO_ANDROID[vk]
+    if 0x41 <= vk <= 0x5A:            # A-Z -> KEYCODE_A(29)..
+        return 29 + (vk - 0x41)
+    if 0x30 <= vk <= 0x39:            # 0-9 -> KEYCODE_0(7)..
+        return 7 + (vk - 0x30)
+    return None
+
+
+class AdbDevice:
+    def __init__(self, serial: str | None = None, adb: str = "adb"):
+        self.serial = serial
+        self.adb = adb
+
+    def _cmd(self, args: list[str]) -> list[str]:
+        base = [self.adb]
+        if self.serial:
+            base += ["-s", self.serial]
+        return base + args
+
+    def _run(self, args: list[str]) -> bytes:
+        try:
+            proc = subprocess.run(self._cmd(args), stdout=subprocess.PIPE,
+                                  stderr=subprocess.PIPE)
+        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
+
+    # ---- capture ----
+    def screencap(self) -> np.ndarray:
+        """截图 -> BGR ndarray（exec-out 避免 stdout CRLF 转换的坑）。"""
+        import cv2
+        raw = self._run(["exec-out", "screencap", "-p"])
+        img = cv2.imdecode(np.frombuffer(raw, dtype=np.uint8), cv2.IMREAD_COLOR)
+        if img is None or img.size == 0:
+            raise RuntimeError("screencap 解码失败（设备可能不支持 exec-out）")
+        return img
+
+    # ---- input ----
+    def tap(self, x: int, y: int) -> None:
+        self._run(["shell", "input", "tap", str(int(x)), str(int(y))])
+
+    def swipe(self, x1: int, y1: int, x2: int, y2: int, ms: int = 300) -> None:
+        self._run(["shell", "input", "swipe", str(int(x1)), str(int(y1)),
+                   str(int(x2)), str(int(y2)), str(int(ms))])
+
+    def long_press(self, x: int, y: int, hold_ms: int = 800) -> None:
+        self.swipe(x, y, x, y, hold_ms)   # same point + duration = long press
+
+    def text(self, s: str) -> None:
+        # Android `input text` 用 %s 表示空格
+        self._run(["shell", "input", "text", s.replace(" ", "%s")])
+
+    def keyevent(self, code: int) -> None:
+        self._run(["shell", "input", "keyevent", str(int(code))])
+
+    @staticmethod
+    def list_devices(adb: str = "adb") -> list[str]:
+        try:
+            out = subprocess.run([adb, "devices"], stdout=subprocess.PIPE,
+                                 stderr=subprocess.PIPE).stdout.decode("utf-8", "replace")
+        except FileNotFoundError:
+            return []
+        serials = []
+        for line in out.splitlines()[1:]:
+            parts = line.split()
+            if len(parts) >= 2 and parts[1] == "device":
+                serials.append(parts[0])
+        return serials
+
+
+class AdbCapture:
+    """capture 后端：忽略 hwnd，一律截设备屏。"""
+    def __init__(self, device: AdbDevice):
+        self.device = device
+
+    def capture_screen(self) -> np.ndarray:
+        return self.device.screencap()
+
+    def capture_window(self, hwnd) -> np.ndarray:
+        return self.device.screencap()
+
+
+class AdbClicker:
+    """clicker 后端：把 Windows 语义的调用映射到 adb input（首参 hwnd 忽略）。"""
+    def __init__(self, device: AdbDevice):
+        self.device = device
+
+    def click(self, hwnd, x: int, y: int) -> None:
+        self.device.tap(x, y)
+
+    def double_click(self, hwnd, x: int, y: int) -> None:
+        self.device.tap(x, y)
+        self.device.tap(x, y)
+
+    def right_click(self, hwnd, x: int, y: int) -> None:
+        self.device.tap(x, y)          # Android 无右键，退化为点击
+
+    def long_press(self, hwnd, x: int, y: int, hold_ms: int) -> None:
+        self.device.long_press(x, y, hold_ms)
+
+    def swipe(self, hwnd, x1, y1, x2, y2, duration_ms: int = 300) -> None:
+        self.device.swipe(x1, y1, x2, y2, duration_ms)
+
+    def drag(self, hwnd, x1, y1, x2, y2, duration_ms: int = 300) -> None:
+        self.device.swipe(x1, y1, x2, y2, duration_ms)
+
+    def scroll(self, hwnd, x, y, amount: int) -> None:
+        # 正数向上滚：从 (x,y) 向上滑
+        self.device.swipe(x, y, x, y - amount * 100, 300)
+
+    def type_text(self, text: str) -> None:
+        self.device.text(text)
+
+    def key_press(self, vk: int) -> None:
+        code = _vk_to_android(vk)
+        if code is not None:
+            self.device.keyevent(code)
+
+    def key_down(self, vk: int) -> None:
+        self.key_press(vk)
+
+    def key_up(self, vk: int) -> None:
+        pass
+
+    def hotkey(self, modifier: int, vk: int) -> None:
+        self.key_press(vk)             # Android input 无组合键，尽力而为
+
+    def pinch(self, hwnd, cx, cy, start_dist, end_dist, duration_ms: int = 400) -> None:
+        pass                           # adb input 不支持多点触控，跳过
+
+
+def make_adb_backends(serial: str | None = None, adb: str = "adb"):
+    """便捷构造：返回 (capture, clicker) 供注入 TaskRunner。"""
+    dev = AdbDevice(serial, adb)
+    return AdbCapture(dev), AdbClicker(dev)