mumdad 0.1.4__py3-none-any.whl

mum/__init__.py

@@ -0,0 +1,8 @@
+"""mum — Multi-platform disguise automation toolkit.
+
+- ADB gesture disguise (``DisguiseAdbClient``, ``DisguiseAdbClientDebug``)
+- WeChat session list scroll navigation (from×L model, device-adaptive)
+- Duration randomization (0~80ms) for anti-detection
+"""
+
+__version__ = "0.1.0"

mum/android/base/adb/__init__.py

@@ -0,0 +1,53 @@
+"""mum ADB 伪装模块 — 统一对外导出。
+
+- ``DisguiseAdbClient``（生产）：自动注入随机延迟 + 坐标偏移 + duration 随机化
+- ``DisguiseAdbClientDebug``（调试）：跳过所有伪装，直接走原生 ADB
+- ``scroll_down_base`` / ``scroll_up_base``：会话列表手势翻页
+- ``scroll_up_reposition``：归位专用下拉
+- ``scroll_down_note``：笔记详情页上滑
+"""
+
+from __future__ import annotations
+
+from mum.android.base.adb.disguise_client import (
+    DisguiseAdbClient,
+    DisguiseAdbClientDebug,
+)
+from mum.android.base.adb._raw_adb import (
+    LOCKED_ADB_VERSION,
+    AdbClient,
+    AdbError,
+    AdbResult,
+    KEYCODE_BACK,
+    KEYCODE_HOME,
+)
+from mum.android.base.adb.scroll import (
+    scroll_down_base,
+    scroll_down_note,
+    scroll_up_base,
+    scroll_up_reposition,
+)
+
+# 向后兼容别名
+session_list_content_scroll_down = scroll_down_base
+session_list_content_scroll_up   = scroll_up_base
+
+RiskAdbClient = DisguiseAdbClient
+
+__all__ = [
+    "LOCKED_ADB_VERSION",
+    "AdbClient",
+    "AdbError",
+    "AdbResult",
+    "KEYCODE_BACK",
+    "KEYCODE_HOME",
+    "DisguiseAdbClient",
+    "DisguiseAdbClientDebug",
+    "RiskAdbClient",
+    "scroll_down_base",
+    "scroll_down_note",
+    "scroll_up_base",
+    "scroll_up_reposition",
+    "session_list_content_scroll_down",
+    "session_list_content_scroll_up",
+]

mum/android/base/adb/_protocol.py

@@ -0,0 +1,20 @@
+"""Minimal ADB interface for duck-typing compatibility.
+
+``DisguiseAdbClient`` satisfies this protocol, as does any object with
+``swipe()`` and ``_run()`` methods.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class AdbProtocol(Protocol):
+    """Minimal ADB interface for scroll gesture functions.
+
+    Compatible with ``layernav_android._protocol.AdbProtocol``.
+    """
+    def swipe(
+        self, x1: int, y1: int, x2: int, y2: int, duration_ms: int = 300,
+    ) -> None: ...
+    def _run(self, args: list[str]) -> str: ...

mum/android/base/adb/_raw_adb.py

@@ -0,0 +1,414 @@
+"""ADB command-line wrapper — stdlib ``subprocess`` only.
+
+No third-party ADB libraries (adbutils / ppadb). No Airtest runtime.
+
+Design constraints:
+    - Every invocation has a hard timeout (``default_timeout``, 10s).
+    - ``screencap()`` returns raw PNG bytes via ``exec-out screencap -p``.
+    - ``wm_size`` is cached per-instance.
+    - No retries here; higher layers own degradation logic.
+    - **ADB version is locked** via ``LOCKED_ADB_VERSION`` (r35.0.2).
+      ``_locked_adb_path()`` resolves the locked binary relative to the
+      consumer project root; callers should prefer ``_resolve_adb_bin()``
+      (which auto-locks) over raw ``adb_bin="adb"``.
+"""
+
+from __future__ import annotations
+
+import logging
+import os as _os
+import re
+import shutil
+import subprocess
+import sys as _sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+LOG = logging.getLogger("mum.adb")
+
+KEYCODE_BACK = 4
+KEYCODE_HOME = 3
+
+_DEFAULT_TIMEOUT = 10.0
+_WM_OVERRIDE_PATTERN = re.compile(r"Override size:\s*(\d+)x(\d+)")
+_WM_PHYSICAL_PATTERN = re.compile(r"Physical size:\s*(\d+)x(\d+)")
+_WINDOW_FOCUS_PATTERN = re.compile(
+    r"(?:mCurrentFocus|mFocusedApp|mResumedActivity)[^\n]*?([a-zA-Z0-9_.]+)/([a-zA-Z0-9_.$]+)"
+)
+
+# ---------------------------------------------------------------------------
+# ADB version locking
+# ---------------------------------------------------------------------------
+
+LOCKED_ADB_VERSION = "35.0.2"
+"""Locked platform-tools version. ADB binary must match this exact version."""
+
+_LOCKED_ADB_BINARY: Optional[str] = None
+"""Cached locked ADB binary path, resolved once at module level."""
+
+
+def _project_root() -> Optional[Path]:
+    """Walk upward from cwd for a project-root marker."""
+    cwd = Path.cwd()
+    markers = [".git", "pyproject.toml"]
+    for parent in [cwd, *cwd.parents]:
+        if any((parent / m).exists() for m in markers):
+            return parent
+    return None
+
+
+def _locked_adb_path() -> Optional[Path]:
+    """Resolve the locked ADB binary for the locked platform-tools version.
+
+    Resolution order:
+    1. ``MUM_ADB_TOOLS_DIR`` env var — use ``adb`` / ``adb.exe`` inside it.
+    2. Project root ``tools/platform-tools_r{version}/adb.exe``.
+    3. Fallback: ``shutil.which("adb")`` (logged at WARNING).
+    """
+    # 1. Explicit env override
+    tools_dir = _os.getenv("MUM_ADB_TOOLS_DIR")
+    if tools_dir:
+        adb_exe = "adb.exe" if _sys.platform == "win32" else "adb"
+        p = Path(tools_dir) / adb_exe
+        if p.is_file():
+            return p
+        LOG.warning("MUM_ADB_TOOLS_DIR=%s but %s not found inside", tools_dir, adb_exe)
+
+    # 2. Project-root-relative locked directory
+    root = _project_root()
+    if root:
+        plat = "windows" if _sys.platform == "win32" else "linux"
+        subdir = f"tools/platform-tools_r{LOCKED_ADB_VERSION}_{plat}"
+        adb_exe = "adb.exe" if _sys.platform == "win32" else "adb"
+        p = root / subdir / adb_exe
+        if p.is_file():
+            return p
+
+    # 3. Fallback: system ADB (not locked)
+    system_adb = shutil.which("adb")
+    if system_adb:
+        LOG.warning(
+            "locked ADB (r%s) not found; falling back to system adb: %s",
+            LOCKED_ADB_VERSION, system_adb,
+        )
+        return Path(system_adb)
+
+    LOG.warning("no ADB binary found (locked r%s or system)", LOCKED_ADB_VERSION)
+    return None
+
+
+def _verify_version_or_die(adb_path: Path) -> None:
+    """Verify the ADB binary reports version == ``LOCKED_ADB_VERSION``.
+
+    Raises :class:`AdbError` on mismatch or failure to parse.
+    """
+    result = subprocess.run(
+        [str(adb_path), "version"],
+        capture_output=True,
+        text=True,
+        timeout=10.0,
+        check=False,
+    )
+    if result.returncode != 0:
+        raise AdbError(
+            [str(adb_path), "version"],
+            result.returncode,
+            result.stderr,
+        )
+
+    match = re.search(r"Version\s+(\d+\.\d+\.\d+)", result.stdout)
+    if not match:
+        LOG.warning(
+            "cannot parse ADB version from: %s",
+            result.stdout.splitlines()[0] if result.stdout else "(empty)",
+        )
+        return
+
+    actual = match.group(1)
+    if actual != LOCKED_ADB_VERSION:
+        raise AdbError(
+            [str(adb_path)],
+            1,
+            f"ADB version mismatch: expected r{LOCKED_ADB_VERSION}, got r{actual}. "
+            f"Place the correct version under tools/platform-tools_r{LOCKED_ADB_VERSION}_*/ "
+            f"or set MUM_ADB_TOOLS_DIR.",
+        )
+
+
+def _resolve_adb_bin(adb_bin: Optional[str] = None) -> str:
+    """Resolve the ADB binary to use, preferring the locked version.
+
+    * If *adb_bin* is explicitly provided (non-default), use it as-is.
+    * Otherwise resolve via ``_locked_adb_path()`` with fallback to ``"adb"``.
+
+    Callers should pass their ``adb_bin`` kwarg through this function
+    to automatically enforce version locking.
+    """
+    if adb_bin is not None and adb_bin != "adb":
+        return adb_bin
+    locked = _locked_adb_path()
+    return str(locked) if locked else "adb"
+
+
+# Eagerly resolve locked ADB at import time (non-fatal if missing).
+try:
+    _locked = _locked_adb_path()
+    if _locked:
+        _LOCKED_ADB_BINARY = str(_locked)
+        LOG.debug("locked ADB: %s", _LOCKED_ADB_BINARY)
+except Exception:
+    LOG.debug("could not resolve locked ADB at import time", exc_info=True)
+
+
+# ---------------------------------------------------------------------------
+# AdbClient
+# ---------------------------------------------------------------------------
+
+
+class AdbError(RuntimeError):
+    """Raised when an ADB command returns non-zero or times out."""
+
+    def __init__(self, cmd: list[str], returncode: int, stderr: str) -> None:
+        super().__init__(
+            f"adb command failed (rc={returncode}): {' '.join(cmd)!r}\n"
+            f"  stderr: {stderr.strip()!r}"
+        )
+        self.cmd = cmd
+        self.returncode = returncode
+        self.stderr = stderr
+
+
+@dataclass(frozen=True)
+class AdbResult:
+    stdout: str
+    stderr: str
+    returncode: int
+
+    @property
+    def ok(self) -> bool:
+        return self.returncode == 0
+
+
+class AdbClient:
+    """Thin wrapper around the ``adb`` CLI bound to a specific ``device_id``."""
+
+    def __init__(
+        self,
+        device_id: str,
+        adb_bin: str = "adb",
+        default_timeout: float = _DEFAULT_TIMEOUT,
+    ) -> None:
+        self.device_id = device_id
+        self.adb_bin = adb_bin
+        self.default_timeout = default_timeout
+        self._wm_size_cache: Optional[tuple[int, int]] = None
+
+    # ---- low-level invocation ------------------------------------------
+
+    def _run(
+        self,
+        args: list[str],
+        *,
+        timeout: Optional[float] = None,
+    ) -> AdbResult:
+        cmd = [self.adb_bin, "-s", self.device_id, *args]
+        LOG.debug("adb: %s", " ".join(cmd))
+        try:
+            completed = subprocess.run(
+                cmd,
+                capture_output=True,
+                timeout=timeout or self.default_timeout,
+                check=False,
+            )
+        except FileNotFoundError as e:
+            raise AdbError(cmd, 127, f"adb binary not found: {e}") from e
+        except subprocess.TimeoutExpired as e:
+            raise AdbError(cmd, -1, f"timed out after {e.timeout}s") from e
+
+        stdout = completed.stdout.decode("utf-8", errors="replace") if completed.stdout else ""
+        stderr = completed.stderr.decode("utf-8", errors="replace") if completed.stderr else ""
+        return AdbResult(stdout=stdout, stderr=stderr, returncode=completed.returncode)
+
+    def _run_binary(
+        self, args: list[str], *, timeout: Optional[float] = None
+    ) -> bytes:
+        cmd = [self.adb_bin, "-s", self.device_id, *args]
+        LOG.debug("adb: %s  (binary)", " ".join(cmd))
+        try:
+            completed = subprocess.run(
+                cmd,
+                capture_output=True,
+                timeout=timeout or self.default_timeout,
+                check=False,
+            )
+        except FileNotFoundError as e:
+            raise AdbError(cmd, 127, f"adb binary not found: {e}") from e
+        except subprocess.TimeoutExpired as e:
+            raise AdbError(cmd, -1, f"timed out after {e.timeout}s") from e
+
+        if completed.returncode != 0:
+            stderr = completed.stderr.decode("utf-8", errors="replace") if completed.stderr else ""
+            raise AdbError(cmd, completed.returncode, stderr)
+        return completed.stdout or b""
+
+    def _require(self, result: AdbResult, cmd_hint: str) -> AdbResult:
+        if not result.ok:
+            raise AdbError([cmd_hint], result.returncode, result.stderr)
+        return result
+
+    # ---- preflight ------------------------------------------------------
+
+    def is_device_connected(self) -> bool:
+        result = subprocess.run(
+            [self.adb_bin, "devices"],
+            capture_output=True,
+            timeout=self.default_timeout,
+            check=False,
+        )
+        if result.returncode != 0:
+            return False
+        out = result.stdout.decode("utf-8", errors="replace")
+        for line in out.splitlines():
+            parts = line.strip().split("\t")
+            if len(parts) == 2 and parts[0] == self.device_id and parts[1] == "device":
+                return True
+        return False
+
+    # ---- display --------------------------------------------------------
+
+    def wm_size(self) -> tuple[int, int]:
+        if self._wm_size_cache is not None:
+            return self._wm_size_cache
+        result = self._require(
+            self._run(["shell", "wm", "size"]),
+            cmd_hint="adb shell wm size",
+        )
+        match = _WM_OVERRIDE_PATTERN.search(result.stdout) or _WM_PHYSICAL_PATTERN.search(result.stdout)
+        if not match:
+            raise AdbError(
+                ["adb", "shell", "wm", "size"],
+                result.returncode,
+                f"could not parse wm size: {result.stdout!r}",
+            )
+        w, h = int(match.group(1)), int(match.group(2))
+        self._wm_size_cache = (w, h)
+        return (w, h)
+
+    def wm_density(self) -> int:
+        result = self._require(
+            self._run(["shell", "wm", "density"]),
+            cmd_hint="adb shell wm density",
+        )
+        match = (
+            re.search(r"Override density:\s*(\d+)", result.stdout)
+            or re.search(r"Physical density:\s*(\d+)", result.stdout)
+        )
+        if not match:
+            raise AdbError(
+                ["adb", "shell", "wm", "density"],
+                result.returncode,
+                f"could not parse wm density: {result.stdout!r}",
+            )
+        return int(match.group(1))
+
+    # ---- capture --------------------------------------------------------
+
+    def screencap(self, save_to: Optional[Path] = None, timeout: float = 15.0) -> bytes:
+        data = self._run_binary(["exec-out", "screencap", "-p"], timeout=timeout)
+        if not data.startswith(b"\x89PNG\r\n\x1a\n"):
+            raise AdbError(
+                ["adb", "exec-out", "screencap", "-p"],
+                0,
+                f"unexpected non-PNG prefix (len={len(data)})",
+            )
+        if save_to is not None:
+            save_to.write_bytes(data)
+            LOG.debug("screencap saved to %s (%d bytes)", save_to, len(data))
+        return data
+
+    # ---- input ----------------------------------------------------------
+
+    def tap(self, x: int, y: int) -> None:
+        self._require(
+            self._run(["shell", "input", "tap", str(int(x)), str(int(y))]),
+            cmd_hint="adb shell input tap",
+        )
+
+    def swipe(
+        self, x1: int, y1: int, x2: int, y2: int, duration_ms: int = 300,
+    ) -> None:
+        self._require(
+            self._run([
+                "shell", "input", "swipe",
+                str(int(x1)), str(int(y1)),
+                str(int(x2)), str(int(y2)),
+                str(int(duration_ms)),
+            ]),
+            cmd_hint="adb shell input swipe",
+        )
+
+    def key_event(self, code: int) -> None:
+        self._require(
+            self._run(["shell", "input", "keyevent", str(int(code))]),
+            cmd_hint="adb shell input keyevent",
+        )
+
+    # ---- app control ----------------------------------------------------
+
+    def force_stop(self, package: str, *, timeout: Optional[float] = None) -> None:
+        self._require(
+            self._run(["shell", "am", "force-stop", package], timeout=timeout),
+            cmd_hint=f"adb shell am force-stop {package}",
+        )
+
+    def monkey_launch_launcher_category(
+        self, package: str, *, timeout: Optional[float] = None,
+    ) -> None:
+        self._require(
+            self._run(
+                ["shell", "monkey", "-p", package, "-c",
+                 "android.intent.category.LAUNCHER", "1"],
+                timeout=timeout or self.default_timeout,
+            ),
+            cmd_hint=f"adb shell monkey -p {package} … LAUNCHER 1",
+        )
+
+    # ---- window inspection ---------------------------------------------
+
+    def dumpsys_window_focus(self) -> str:
+        result = self._require(
+            self._run(["shell", "dumpsys", "window"], timeout=15.0),
+            cmd_hint="adb shell dumpsys window",
+        )
+        matches = []
+        for line in result.stdout.splitlines():
+            stripped = line.strip()
+            if stripped.startswith(("mCurrentFocus", "mFocusedApp", "mResumedActivity")):
+                matches.append(stripped)
+        return "\n".join(matches)
+
+    def foreground_package(self) -> Optional[str]:
+        focus = self.dumpsys_window_focus()
+        match = _WINDOW_FOCUS_PATTERN.search(focus)
+        if not match:
+            return None
+        return match.group(1)
+
+    def is_foreground_app(self, package: str) -> bool:
+        fg = self.foreground_package()
+        return fg == package
+
+
+__all__ = [
+    "AdbClient",
+    "AdbError",
+    "AdbResult",
+    "KEYCODE_BACK",
+    "KEYCODE_HOME",
+    "LOCKED_ADB_VERSION",
+    "_LOCKED_ADB_BINARY",
+    "_locked_adb_path",
+    "_verify_version_or_die",
+    "_resolve_adb_bin",
+]

mum/android/base/adb/coordinate.py

@@ -0,0 +1,18 @@
+"""坐标微偏移 — 供 ``DisguiseAdbClient`` 内部调用。"""
+
+from __future__ import annotations
+
+import random
+
+_DEFAULT_OFFSET = 5
+
+
+def jitter(x: int, y: int, offset: int = _DEFAULT_OFFSET) -> tuple[int, int]:
+    """在坐标 (x, y) 上添加 ±offset 范围内的随机偏移。
+
+    Returns:
+        (x2, y2): 偏移后的新坐标。
+    """
+    dx = random.randint(-offset, offset)
+    dy = random.randint(-offset, offset)
+    return x + dx, y + dy

mum/android/base/adb/disguise_client.py

@@ -0,0 +1,177 @@
+"""防伪装客户端 — 自动注入人类操作模拟。
+
+- ``DisguiseAdbClient``（生产）：每次操作前注入随机延迟 + 坐标偏移。
+- ``DisguiseAdbClientDebug``（子类）：跳过伪装注入，直接走原生 ADB。
+
+贝塞尔曲线：sendevent / input motionevent 在 MI 8 UD (Android 10)、Xiaomi HyperOS (Android 16)、
+Huawei (Android 13) 上均不产生触摸效果，故保持 ``input swipe`` 直线。
+防检测通过随机起止坐标 + jitter + 随机延迟 + duration 随机化实现。
+"""
+
+from __future__ import annotations
+
+import random
+from pathlib import Path
+from typing import Optional
+
+from mum.android.base.adb._raw_adb import (
+    KEYCODE_BACK,
+    KEYCODE_HOME,
+    _resolve_adb_bin,
+    AdbClient,
+    AdbError,
+    AdbResult,
+)
+from mum.android.base.adb.random_delay import random_sleep
+from mum.android.base.adb.coordinate import jitter
+
+
+class DisguiseAdbClient:
+    """生产环境 ADB 客户端，自动注入人类操作模拟。
+
+    每次操作前自动执行：随机延迟 → 坐标微偏移。
+    """
+
+    def __init__(
+        self,
+        device_id: str,
+        adb_bin: str = "adb",
+        default_timeout: float = 10.0,
+    ) -> None:
+        # Enforce locked ADB unless caller explicitly overrides
+        resolved = _resolve_adb_bin(adb_bin)
+        self._raw = AdbClient(
+            device_id=device_id,
+            adb_bin=resolved,
+            default_timeout=default_timeout,
+        )
+
+    @property
+    def device_id(self) -> str:
+        return self._raw.device_id
+
+    # ---- 伪装操作入口 ----
+
+    def click(self, x: int, y: int) -> None:
+        """带随机延迟和坐标偏移的 tap。
+
+        内部调用顺序：随机延迟 → 坐标微偏移 → adb tap。
+        """
+        random_sleep()
+        x2, y2 = jitter(x, y)
+        self._raw.tap(x2, y2)
+
+    def swipe(
+        self,
+        x1: int,
+        y1: int,
+        x2: int,
+        y2: int,
+        duration_ms: int = 400,
+    ) -> None:
+        """单次连续 swipe（含随机延迟 + duration 随机化）。
+
+        调用一次 ``adb shell input swipe`` 产生 **1 次** 完整的 DOWN→MOVE→UP
+        触摸序列。sendevent / input motionevent 贝塞尔路径在三设备上均
+        不产生触摸效果（D1/D2 Xiaomi 定制内核 + D3 Huawei），故保持直线。
+
+        防风控：duration 0~80ms 随机 + 随机延迟 + tap 坐标 jitter。
+        """
+        random_sleep()
+        d = max(50, duration_ms + int(random.uniform(0, 80)))
+        self._raw.swipe(x1, y1, x2, y2, duration_ms=d)
+
+    def screencap(self, save_to: Optional[Path] = None, timeout: float = 15.0) -> bytes:
+        return self._raw.screencap(save_to=save_to, timeout=timeout)
+
+    def keyevent(self, code: str | int) -> None:
+        """发送按键事件（兼容字符串和整数 code）。
+
+        内部调用顺序：随机延迟 → adb key_event。
+        延迟范围 80~200ms，避免与 screencap 等操作形成固定时序模式。
+
+        Args:
+            code: 按键名 (str) 或键码 (int)，如 ``"BACK"``、``"HOME"``、``4``、``3``。
+        """
+        random_sleep(0.08, 0.20)
+        key_map = {"BACK": KEYCODE_BACK, "HOME": KEYCODE_HOME}
+        if isinstance(code, str) and code.upper() in key_map:
+            code = key_map[code.upper()]
+        self._raw.key_event(int(code))
+
+    # ---- 别名（兼容旧调用） ----
+
+    tap = click
+    key_event = keyevent
+
+    # ---- 委托给 _raw 的只读方法 ----
+
+    def wm_size(self) -> tuple[int, int]:
+        return self._raw.wm_size()
+
+    def wm_density(self) -> int:
+        return self._raw.wm_density()
+
+    def is_device_connected(self) -> bool:
+        return self._raw.is_device_connected()
+
+    def foreground_package(self) -> Optional[str]:
+        return self._raw.foreground_package()
+
+    def dumpsys_window_focus(self) -> str:
+        return self._raw.dumpsys_window_focus()
+
+    def is_foreground_app(self, package: str) -> bool:
+        return self._raw.is_foreground_app(package)
+
+    def _run(self, args: list[str]) -> str:
+        """Raw ADB command (required by AdbProtocol)."""
+        result = self._raw._run(args)
+        return result.stdout
+
+    # ---- app control（不经伪装，直接委托） ----
+
+    def force_stop(self, package: str, *, timeout: Optional[float] = None) -> None:
+        self._raw.force_stop(package, timeout=timeout)
+
+    def monkey_launch_launcher_category(
+        self, package: str, *, timeout: Optional[float] = None,
+    ) -> None:
+        self._raw.monkey_launch_launcher_category(package, timeout=timeout)
+
+
+class DisguiseAdbClientDebug(DisguiseAdbClient):
+    """开发调试 ADB 客户端，跳过所有伪装注入。
+
+    所有操作直接走原生 ADB，不注入随机延迟、坐标偏移。
+    任务脚本通过 import 此类替代魔法环境变量。
+    """
+
+    def click(self, x: int, y: int) -> None:
+        self._raw.tap(x, y)
+
+    def swipe(
+        self,
+        x1: int,
+        y1: int,
+        x2: int,
+        y2: int,
+        duration_ms: int = 400,
+    ) -> None:
+        self._raw.swipe(x1, y1, x2, y2, duration_ms=duration_ms)
+
+    def keyevent(self, code: str | int) -> None:
+        key_map = {"BACK": KEYCODE_BACK, "HOME": KEYCODE_HOME}
+        if isinstance(code, str) and code.upper() in key_map:
+            code = key_map[code.upper()]
+        self._raw.key_event(int(code))
+
+    tap = click
+
+
+__all__ = [
+    "DisguiseAdbClient",
+    "DisguiseAdbClientDebug",
+    "AdbError",
+    "AdbResult",
+]