layernav-android 0.2.0__py3-none-any.whl

layernav_android/__init__.py

@@ -0,0 +1,27 @@
+from layernav_android._protocol import AdbProtocol
+from layernav_android.base import (
+    BaseLayerModel,
+    KEYCODE_BACK,
+    KEYCODE_HOME,
+    LayerDef,
+    LayerListener,
+    POST_TRANSITION_SLEEP,
+)
+from layernav_android.cold_start import (
+    APP_DEFAULTS,
+    cold_start_app_from_launcher,
+    dock_app_icon_coords,
+)
+
+__all__ = [
+    "AdbProtocol",
+    "APP_DEFAULTS",
+    "BaseLayerModel",
+    "cold_start_app_from_launcher",
+    "dock_app_icon_coords",
+    "KEYCODE_BACK",
+    "KEYCODE_HOME",
+    "LayerDef",
+    "LayerListener",
+    "POST_TRANSITION_SLEEP",
+]

layernav_android/_protocol.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class AdbProtocol(Protocol):
+    """Minimal ADB interface for layer navigation.
+
+    Users implement or inject their existing ADB client.
+    ``collector_phone_android``'s ``AdbClient`` already satisfies
+    this protocol — no adapter needed.
+    """
+
+    def screencap(self) -> bytes: ...
+    def key_event(self, code: int) -> None: ...
+    def foreground_package(self) -> str: ...
+    def tap(self, x: int, y: int) -> None: ...
+    def _run(self, args: list[str]) -> str: ...

layernav_android/base.py

@@ -0,0 +1,304 @@
+"""Multi-layer Android task-stack navigation framework.
+
+Framework—Task contract:
+    Task subclass overrides:
+        - ``layers`` — list of :class:`LayerDef`
+        - ``detect`` — screenshot-based layer detection
+        - ``_on_Lx`` — per-layer handler (business logic + tap)
+
+Framework provides:
+    Atomic:   ``detect``  ``enter_next``  ``back_one``  ``back_recover``
+    Combined: ``back``    ``advance``     ``restore``
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from dataclasses import dataclass
+from typing import Protocol
+
+from layernav_android._protocol import AdbProtocol
+
+LOG = logging.getLogger("layernav")
+
+POST_TRANSITION_SLEEP = 1.5
+
+KEYCODE_BACK = 4
+KEYCODE_HOME = 3
+
+# ── Layer definition ──────────────────────────────────────────────────────────
+
+
+@dataclass
+class LayerDef:
+    """Description of one layer in the Android task stack."""
+
+    key: str
+    """Layer key: ``"L0"`` | ``"L1"`` | ``"L2"`` | ``"L3"``."""
+
+    name: str
+    """Machine-readable name."""
+
+    label_cn: str
+    """Human-readable Chinese label."""
+
+    detection: str
+    """How this layer is detected (human-readable)."""
+
+
+# ── Observer / Listener (inspired by python-statemachine's Listener pattern) ───
+
+
+class LayerListener(Protocol):
+    """Observer interface for layer model lifecycle events.
+
+    All methods are optional — implement only what you need.
+    Inspired by `python-statemachine
+    <https://github.com/fgmacedo/python-statemachine>`_'s Listener pattern.
+    """
+
+    def on_transition(
+        self, from_layer: str, to_layer: str, method: str,
+    ) -> None:
+        """Called after an atomic layer transition completes.
+
+        *method* is one of ``"enter_next"`` or ``"back_one"``.
+        """
+        ...
+
+    def on_timeout(
+        self, from_layer: str, target_layer: str, elapsed_s: float,
+    ) -> None:
+        """Called when :meth:`BaseLayerModel.enter_next` polling times out."""
+        ...
+
+    def on_recovery(self, target_layer: str, ok: bool) -> None:
+        """Called after :meth:`BaseLayerModel.back_recover` completes.
+
+        *ok* indicates whether the recovery succeeded.
+        """
+        ...
+
+
+# ── Abstract base ─────────────────────────────────────────────────────────────
+
+
+class BaseLayerModel:
+    """Abstract Android task-stack layer model.
+
+    Subclass contract:
+        - Override :attr:`layers`.
+        - Override :meth:`detect`.
+        - Override ``_on_L0`` / ``_on_L1`` / ``_on_L2`` / ``_on_L3``.
+        - Optionally override :meth:`_cold_start`.
+    """
+
+    layers: list[LayerDef] = []
+    _ON_METHODS: tuple[str, ...] = ("_on_L0", "_on_L1", "_on_L2", "_on_L3")
+
+    def __init__(self) -> None:
+        self._listeners: list[LayerListener] = []
+
+    def add_listener(self, listener: LayerListener) -> None:
+        """Register a :class:`LayerListener` to observe lifecycle events."""
+        self._listeners.append(listener)
+
+    def _notify_transition(
+        self, from_layer: str, to_layer: str, method: str,
+    ) -> None:
+        for lst in self._listeners:
+            lst.on_transition(from_layer, to_layer, method)
+
+    def _notify_timeout(
+        self, from_layer: str, target_layer: str, elapsed_s: float,
+    ) -> None:
+        for lst in self._listeners:
+            lst.on_timeout(from_layer, target_layer, elapsed_s)
+
+    def _notify_recovery(self, target_layer: str, ok: bool) -> None:
+        for lst in self._listeners:
+            lst.on_recovery(target_layer, ok)
+
+    # ── Subclass overrides ────────────────────────────────────────────────────
+
+    def detect(self, adb: AdbProtocol, scale_w: float) -> str:
+        """Return current layer key.  Task MUST override."""
+        raise NotImplementedError("subclass must override detect()")
+
+    def _on_L0(self, adb: AdbProtocol, scale_w: float, *, quick: bool = False) -> str | None:
+        """L0 handler: home screen → cold-start App."""
+        raise NotImplementedError("subclass must override _on_L0")
+
+    def _on_L1(self, adb: AdbProtocol, scale_w: float, *, quick: bool = False) -> str | None:
+        """L1 handler: App main screen → pick content, tap."""
+        raise NotImplementedError("subclass must override _on_L1")
+
+    def _on_L2(self, adb: AdbProtocol, scale_w: float, *, quick: bool = False) -> str | None:
+        """L2 handler: content page → pick sub-content, tap."""
+        raise NotImplementedError("subclass must override _on_L2")
+
+    def _on_L3(self, adb: AdbProtocol, scale_w: float, *, quick: bool = False) -> str | None:
+        """L3 handler: deepest layer — typically no further advance."""
+        raise NotImplementedError("subclass must override _on_L3")
+
+    def _call_on_layer(
+        self, layer_key: str, adb: AdbProtocol, scale_w: float, *, quick: bool
+    ) -> str | None:
+        i = self._layer_index(layer_key)
+        if i < 0:
+            LOG.error("_call_on_layer: unknown layer %s", layer_key)
+            return None
+        method = getattr(self, self._ON_METHODS[i])
+        return method(adb, scale_w, quick=quick)
+
+    # ── Helpers ───────────────────────────────────────────────────────────────
+
+    def _layer_index(self, layer_key: str) -> int:
+        for i, ld in enumerate(self.layers):
+            if ld.key == layer_key:
+                return i
+        return -1
+
+    def init(self, adb: AdbProtocol) -> None:
+        """One-time initialisation (optional)."""
+        pass
+
+    def _cold_start(
+        self, adb: AdbProtocol, target_layer: str, scale_w: float
+    ) -> None:
+        """Cold-start the target app (override in subclass)."""
+        pass
+
+    # ── Atomic API ────────────────────────────────────────────────────────────
+
+    def enter_next(
+        self,
+        adb: AdbProtocol,
+        scale_w: float,
+        *,
+        quick: bool = False,
+        max_wait_s: float = 8.0,
+    ) -> bool:
+        """Advance ONE layer from current position.
+
+        1. detect current layer  ← **guard** (pre-check)
+        2. call _on_L[cur](quick) — handler does business + tap
+        3. if handler returns None or same layer → stop (success)
+        4. wait POST_TRANSITION_SLEEP, then detect  ← **validator** (post-check)
+        5. if not yet on target, poll with increasing intervals up to max_wait_s
+
+        This handles variable transition times (network loading, animations).
+        """
+        cur = self.detect(adb, scale_w)
+        target = self._call_on_layer(cur, adb, scale_w, quick=quick)
+        if target is None or target == cur:
+            return True
+
+        time.sleep(POST_TRANSITION_SLEEP)
+        next_cur = self.detect(adb, scale_w)
+        if next_cur == target:
+            self._notify_transition(cur, next_cur, "enter_next")
+            return True
+
+        poll_start = time.monotonic()
+        deadline = poll_start + max_wait_s
+        interval = 0.5
+        while time.monotonic() < deadline:
+            time.sleep(interval)
+            next_cur = self.detect(adb, scale_w)
+            if next_cur == target:
+                self._notify_transition(cur, next_cur, "enter_next")
+                return True
+            interval = min(interval + 0.5, 2.0)
+
+        elapsed = time.monotonic() - poll_start
+        LOG.warning(
+            "enter_next: %s→%s timeout after %.1fs — still on %s",
+            cur, target, max_wait_s, next_cur,
+        )
+        self._notify_timeout(cur, target, elapsed)
+        return False
+
+    def back_one(self, adb: AdbProtocol, scale_w: float) -> str:
+        """Send KEYCODE_BACK once, return new layer.
+
+        1. detect current layer  ← **guard** (pre-check)
+        2. KEYCODE_BACK
+        3. sleep, detect new layer  ← **validator** (post-check)
+        """
+        cur = self.detect(adb, scale_w)
+        LOG.debug("back_one: from %s", cur)
+        adb.key_event(KEYCODE_BACK)
+        time.sleep(1.0)
+        next_cur = self.detect(adb, scale_w)
+        LOG.debug("back_one: %s → %s", cur, next_cur)
+        self._notify_transition(cur, next_cur, "back_one")
+        return next_cur
+
+    def back_recover(
+        self, adb: AdbProtocol, target_layer: str, scale_w: float
+    ) -> bool:
+        """Recover after BACK exhaustion: cold-start → fast-forward → normal
+        resume."""
+        LOG.warning("back_recover: cold-start → fast-forward → %s", target_layer)
+        adb.key_event(KEYCODE_HOME)
+        time.sleep(0.8)
+        self._cold_start(adb, "L1", scale_w)
+
+        ok = self.advance(adb, target_layer, scale_w, quick=True)
+        if not ok:
+            self._notify_recovery(target_layer, False)
+            return False
+
+        result = self.detect(adb, scale_w) == target_layer
+        self._notify_recovery(target_layer, result)
+        return result
+
+    # ── Combined API ──────────────────────────────────────────────────────────
+
+    def back(self, adb: AdbProtocol, to_layer: str, scale_w: float) -> bool:
+        """Retreat to *to_layer* via repeated BACK."""
+        for _ in range(3):
+            cur = self.detect(adb, scale_w)
+            if cur == to_layer:
+                self._call_on_layer(to_layer, adb, scale_w, quick=False)
+                return True
+            if cur == "L0":
+                break
+            self.back_one(adb, scale_w)
+        return self.back_recover(adb, to_layer, scale_w)
+
+    def advance(
+        self, adb: AdbProtocol, target_layer: str, scale_w: float, *,
+        quick: bool = False,
+        max_wait_s: float = 8.0,
+    ) -> bool:
+        """Advance layer-by-layer to *target_layer*.
+
+        Uses :meth:`enter_next` for each step.  *quick* is forwarded to
+        intermediate layers' handlers.  At the target layer, handler is
+        always called with ``quick=False``.
+        """
+        while True:
+            cur = self.detect(adb, scale_w)
+            if cur == target_layer:
+                self._call_on_layer(target_layer, adb, scale_w, quick=False)
+                return True
+            ok = self.enter_next(adb, scale_w, quick=quick, max_wait_s=max_wait_s)
+            if not ok:
+                return False
+
+    def restore(
+        self, adb: AdbProtocol, target_layer: str, scale_w: float
+    ) -> bool:
+        """Restore to *target_layer* from any position."""
+        cur = self.detect(adb, scale_w)
+        if cur == target_layer:
+            return True
+        ci = self._layer_index(cur)
+        ti = self._layer_index(target_layer)
+        if ci > ti:
+            return self.back(adb, target_layer, scale_w)
+        else:
+            return self.advance(adb, target_layer, scale_w, quick=True)

layernav_android/cold_start.py

@@ -0,0 +1,162 @@
+"""Generic cold-start: launch an Android app from the launcher home screen.
+
+Supports two paths in priority order:
+
+1. **monkey** — ``monkey -p <package> -c LAUNCHER 1`` (primary)
+2. **Dock icon tap** — calculated via ``dock_app_icon_coords`` (fallback)
+
+After the app enters foreground, optionally taps a session tab to reach the
+app's main content list (e.g. WeChat's bottom "微信" tab).
+
+.. code-block:: python
+
+    from layernav_android.cold_start import cold_start_app_from_launcher
+
+    ok = cold_start_app_from_launcher(
+        adb, "com.tencent.mm", 1080, 2248, 1.0,
+        app_name="wechat", M=4, N=3,
+        session_tab_x=108, session_tab_y=2192,
+    )
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+
+from layernav_android._protocol import AdbProtocol
+
+LOG = logging.getLogger("layernav.cold_start")
+
+APP_DEFAULTS: dict[str, dict[str, int]] = {
+    "wechat": {"M": 4, "N": 3},
+    "xhs":    {"M": 4, "N": 1},
+}
+
+
+def dock_app_icon_coords(
+    screen_w: int,
+    screen_h: int,
+    scale_w: float,
+    *,
+    app_name: str = "wechat",
+    M: int = 4,
+    N: int | None = None,
+) -> tuple[int, int]:
+    """Calculate the centre of the *N*-th Dock slot (1‑indexed) in a Dock with *M* equal-width slots.
+
+    - *M*: total number of Dock slots (default 4).
+    - *N*: 1‑based slot index; defaults from ``APP_DEFAULTS`` (wechat→3, xhs→1).
+    - Formula: ``x = round(W * (N - 0.5) / M)``.
+    """
+    if N is None:
+        defaults = APP_DEFAULTS.get(app_name, {})
+        N = defaults.get("N", 1)
+        M = defaults.get("M", M)
+    N = max(1, min(M, N))
+    pad_x = max(12, screen_w // 8)
+    dx = int(round(screen_w * (N - 0.5) / M))
+    dx = max(pad_x, min(screen_w - pad_x, dx))
+    dy = screen_h - max(48, int(round(52 * max(scale_w, 1e-6))))
+    return dx, dy
+
+
+def cold_start_app_from_launcher(
+    adb: AdbProtocol,
+    package: str,
+    screen_w: int,
+    screen_h: int,
+    scale_w: float,
+    *,
+    app_name: str = "wechat",
+    M: int = 4,
+    N: int | None = None,
+    session_tab_x: int | None = None,
+    session_tab_y: int | None = None,
+    force_stop_before: bool = True,
+    deadline_s: float = 25.0,
+) -> bool:
+    """Cold-start *package* from the Android launcher and optionally tap a session tab.
+
+    Args:
+        adb: :class:`AdbProtocol` client.
+        package: Android package name (e.g. ``"com.tencent.mm"``).
+        screen_w, screen_h: device resolution in pixels.
+        scale_w: ``screen_w / 1080.0``.
+        app_name: key in :data:`APP_DEFAULTS` — drives default *M* / *N*.
+        M: number of Dock slots.
+        N: 1‑based slot index where the app icon lives.
+        session_tab_x, session_tab_y: if both are non-``None``, tap this
+            coordinate after the app enters foreground (e.g. WeChat's
+            「微信」 bottom tab).
+        force_stop_before: issue ``am force-stop`` before cold-start.
+        deadline_s: maximum time budget for the whole cold-start.
+
+    Returns:
+        ``True`` if *package* is the foreground app after cold-start.
+    """
+    deadline = time.monotonic() + deadline_s
+
+    if force_stop_before:
+        LOG.info("cold_start: force-stop %s", package)
+        try:
+            adb._run(["shell", "am", "force-stop", package])
+        except Exception:
+            LOG.warning("cold_start: force-stop %s failed (non-fatal)", package)
+        time.sleep(0.65)
+
+    # -- primary: monkey LAUNCHER --
+    LOG.info("cold_start: monkey LAUNCHER for %s", package)
+    try:
+        adb._run(
+            ["shell", "monkey", "-p", package, "-c",
+             "android.intent.category.LAUNCHER", "1"],
+        )
+    except Exception as exc:
+        LOG.warning("cold_start: monkey primary failed (%s) — fallback to Dock tap", exc)
+    else:
+        time.sleep(1.5)
+        if session_tab_x is not None and session_tab_y is not None:
+            adb.tap(session_tab_x, session_tab_y)
+            time.sleep(0.55)
+
+    if _check_foreground(adb, package):
+        return True
+
+    # -- fallback: Dock icon tap --
+    dx, dy = dock_app_icon_coords(
+        screen_w, screen_h, scale_w, app_name=app_name, M=M, N=N,
+    )
+    LOG.info("cold_start: Dock tap fallback at (%d, %d) for %s", dx, dy, package)
+    adb.tap(dx, dy)
+    time.sleep(1.2)
+    if session_tab_x is not None and session_tab_y is not None:
+        adb.tap(session_tab_x, session_tab_y)
+        time.sleep(0.55)
+
+    if _check_foreground(adb, package):
+        return True
+
+    # -- retry monkey --
+    LOG.info("cold_start: monkey retry for %s", package)
+    try:
+        adb._run(
+            ["shell", "monkey", "-p", package, "-c",
+             "android.intent.category.LAUNCHER", "1"],
+        )
+    except Exception as exc:
+        LOG.warning("cold_start: monkey retry failed: %s", exc)
+    else:
+        time.sleep(1.5)
+        if session_tab_x is not None and session_tab_y is not None:
+            adb.tap(session_tab_x, session_tab_y)
+            time.sleep(0.55)
+
+    return _check_foreground(adb, package)
+
+
+def _check_foreground(adb: AdbProtocol, package: str) -> bool:
+    try:
+        return adb.foreground_package() == package
+    except Exception:
+        return False

layernav_android/contrib/wechat.py

@@ -0,0 +1,223 @@
+"""WeChat 4-layer model for group screenshot collection.
+
+Requires ``pip install layernav_android[wechat]`` and an existing vision backend
+(typically ``collector_phone_android.vision.template_matcher``).
+
+.. code-block:: python
+
+    from layernav_android.contrib.wechat import WeChatGroupLayerModel
+
+    model = WeChatGroupLayerModel()
+    model.restore(adb, "L1", scale_w)
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any
+
+import numpy as np
+
+from layernav_android._protocol import AdbProtocol
+from layernav_android.base import KEYCODE_BACK, KEYCODE_HOME, BaseLayerModel, LayerDef
+from layernav_android.cold_start import cold_start_app_from_launcher
+
+LOG = logging.getLogger("layernav.wechat")
+
+WECHAT_PACKAGE = "com.tencent.mm"
+
+
+def _decode_png(data: bytes) -> np.ndarray:
+    buf = np.frombuffer(data, dtype=np.uint8)
+    return __import__("cv2").imdecode(buf, __import__("cv2").IMREAD_COLOR)
+
+
+def _calc_wechat_session_tab(screen_w: int, screen_h: int, scale_w: float) -> tuple[int, int]:
+    tab_x = max(24, min(screen_w - 24, int(round(screen_w * 0.10))))
+    tab_y = max(screen_h // 2, screen_h - int(round(56 * max(scale_w, 1e-6))))
+    return tab_x, tab_y
+
+
+class WeChatGroupLayerModel(BaseLayerModel):
+    """4-layer model for WeChat group screenshot collection.
+
+    Layer stack::
+
+        L3  微信笔记       detect_wechat_note_header() → score > 0
+        L2  群聊天界面      WeChat FG + bottom-4-tab absent + no note-header
+        L1  微信主界面      is_wechat_main_conversation_list_chrome()
+        L0  手机主屏幕      foreground_package() ≠ com.tencent.mm
+    """
+
+    layers = [
+        LayerDef("L0", "home", "手机主屏幕", "foreground ≠ com.tencent.mm"),
+        LayerDef("L1", "main_list", "微信主会话列表", "is_main_list_chrome()"),
+        LayerDef("L2", "chat", "群聊天界面", "WeChat FG + no tabs4 + no notes"),
+        LayerDef("L3", "notes", "微信笔记", "detect_note_header()"),
+    ]
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._device_id: str = "unknown"
+
+    def init(self, adb: AdbProtocol) -> None:
+        self._device_id: str = getattr(adb, "_serial", "unknown")
+
+    def _ensure_vision(self):
+        try:
+            from collector_phone_android.vision.template_matcher import (
+                detect_wechat_main_bottom_tab_bar_four_columns,
+                detect_wechat_note_header,
+                is_wechat_main_conversation_list_chrome,
+            )
+            return (
+                detect_wechat_note_header,
+                is_wechat_main_conversation_list_chrome,
+                detect_wechat_main_bottom_tab_bar_four_columns,
+            )
+        except ImportError:
+            raise ImportError(
+                "WeChatGroupLayerModel.detect() requires "
+                "collector_phone_android.vision.template_matcher. "
+                "Install with: pip install collector_phone_android"
+            )
+
+    # ── detect ────────────────────────────────────────────────────────────────
+
+    def detect(self, adb: AdbProtocol, scale_w: float) -> str:
+        fg = adb.foreground_package()
+        if fg != WECHAT_PACKAGE:
+            return "L0"
+        (
+            detect_wechat_note_header,
+            is_wechat_main_conversation_list_chrome,
+            detect_wechat_main_bottom_tab_bar_four_columns,
+        ) = self._ensure_vision()
+        png = adb.screencap()
+        arr = _decode_png(png)
+        if detect_wechat_note_header(arr, scale_w) is not None:
+            return "L3"
+        if is_wechat_main_conversation_list_chrome(
+            arr, scale_w, require_visible_pinned_row=False,
+        ):
+            return "L1"
+        if detect_wechat_main_bottom_tab_bar_four_columns(arr, scale_w):
+            return "L1"
+        return "L2"
+
+    def detect_from_png(self, png: bytes, scale_w: float, fg: str) -> str:
+        """Detect from already-captured PNG (no extra screencap)."""
+        if fg != WECHAT_PACKAGE:
+            return "L0"
+        (
+            detect_wechat_note_header,
+            is_wechat_main_conversation_list_chrome,
+            detect_wechat_main_bottom_tab_bar_four_columns,
+        ) = self._ensure_vision()
+        arr = _decode_png(png)
+        if detect_wechat_note_header(arr, scale_w) is not None:
+            return "L3"
+        if is_wechat_main_conversation_list_chrome(
+            arr, scale_w, require_visible_pinned_row=False,
+        ):
+            return "L1"
+        if detect_wechat_main_bottom_tab_bar_four_columns(arr, scale_w):
+            return "L1"
+        return "L2"
+
+    # ── Layer handlers ────────────────────────────────────────────────────────
+
+    def _on_L0(self, adb: AdbProtocol, scale_w: float, *, quick: bool = False) -> str | None:
+        self._cold_start(adb, "L1", scale_w)
+        return "L1"
+
+    def _on_L1(self, adb: AdbProtocol, scale_w: float, *, quick: bool = False) -> str | None:
+        if quick:
+            row = self._pick_first_unread(adb, scale_w)
+        else:
+            row = self._scan_and_select(adb, scale_w)
+        if row is None:
+            return None
+        self._tap_row(row, adb)
+        return "L2"
+
+    def _on_L2(self, adb: AdbProtocol, scale_w: float, *, quick: bool = False) -> str | None:
+        if quick:
+            card = self._pick_first_card(adb, scale_w)
+        else:
+            card = self._scan_and_select_card(adb, scale_w)
+        if card is None:
+            return None
+        adb.tap(card.click_x, card.click_y)
+        return "L3"
+
+    def _on_L3(self, adb: AdbProtocol, scale_w: float, *, quick: bool = False) -> str | None:
+        return None
+
+    # ── Internal helpers ──────────────────────────────────────────────────────
+
+    def _tap_row(self, row: Any, adb: AdbProtocol) -> None:
+        x1, y1, x2, y2 = row.bbox
+        if getattr(row, "unread_dots", None):
+            badge = row.unread_dots[0]
+            row_h = max(1, y2 - y1)
+            badge_cx = badge.x + badge.w // 2
+            badge_cy = badge.y + badge.h // 2
+            cy = badge_cy + int(row_h * 0.35)
+            cy = max(y1 + 10, min(y2 - 10, cy))
+            cx = badge_cx
+        else:
+            cx = (x1 + x2) // 2
+            cy = (y1 + y2) // 2
+        adb.tap(cx, cy)
+
+    def _pick_first_unread(self, adb: AdbProtocol, scale_w: float) -> Any:
+        return None  # TODO: wire real scan from driver
+
+    def _scan_and_select(self, adb: AdbProtocol, scale_w: float) -> Any:
+        return None  # TODO: wire real scan — caller holds the logic
+
+    def _pick_first_card(self, adb: AdbProtocol, scale_w: float) -> Any:
+        return None
+
+    def _scan_and_select_card(self, adb: AdbProtocol, scale_w: float) -> Any:
+        return None
+
+    # ── Cold-start ────────────────────────────────────────────────────────────
+
+    def _cold_start(
+        self,
+        adb: AdbProtocol,
+        target_layer: str,
+        scale_w: float,
+        deadline_s: float = 20.0,
+    ) -> None:
+        LOG.info("_cold_start: HOME → WeChat → poll %s", target_layer)
+
+        png = adb.screencap()
+        arr = _decode_png(png)
+        h, w = arr.shape[:2]
+
+        tab_x, tab_y = _calc_wechat_session_tab(w, h, scale_w)
+
+        adb.key_event(KEYCODE_HOME)
+        time.sleep(0.8)
+
+        cold_start_app_from_launcher(
+            adb, WECHAT_PACKAGE, w, h, scale_w,
+            app_name="wechat", M=4, N=3,
+            session_tab_x=tab_x, session_tab_y=tab_y,
+            force_stop_before=True,
+            deadline_s=deadline_s,
+        )
+
+        deadline = time.monotonic() + deadline_s
+        while time.monotonic() < deadline:
+            if self.detect(adb, scale_w) == target_layer:
+                LOG.info("_cold_start: reached %s", target_layer)
+                return
+            time.sleep(1.0)
+        raise TimeoutError(
+            f"cold-start WeChat: did not reach {target_layer} within {deadline_s}s"
+        )

layernav_android/contrib/xhs.py

@@ -0,0 +1,69 @@
+"""Xiaohongshu placeholder layer model.
+
+.. code-block:: python
+
+    from layernav_android.contrib.xhs import XhsLayerModel
+
+    model = XhsLayerModel()
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+
+from layernav_android._protocol import AdbProtocol
+from layernav_android.base import KEYCODE_BACK, KEYCODE_HOME, BaseLayerModel, LayerDef
+from layernav_android.cold_start import cold_start_app_from_launcher
+
+LOG = logging.getLogger("layernav.xhs")
+
+
+class XhsLayerModel(BaseLayerModel):
+    """Placeholder layer model for Xiaohongshu feed collection."""
+
+    layers = [
+        LayerDef("L0", "home", "手机主屏幕", "foreground ≠ com.xingin.xhs"),
+        LayerDef("L1", "feed", "小红书首页推荐流", "TODO"),
+        LayerDef("L2", "note_detail", "笔记详情页", "TODO"),
+        LayerDef("L3", "comments", "评论浮层", "TODO"),
+    ]
+
+    def detect(self, adb: AdbProtocol, scale_w: float) -> str:
+        return "L0"
+
+    def _on_L0(self, adb: AdbProtocol, scale_w: float, *, quick: bool = False) -> str | None:
+        self._cold_start(adb, "L1", scale_w)
+        return "L1"
+
+    def _on_L1(self, adb: AdbProtocol, scale_w: float, *, quick: bool = False) -> str | None:
+        return None
+
+    def _on_L2(self, adb: AdbProtocol, scale_w: float, *, quick: bool = False) -> str | None:
+        return None
+
+    def _on_L3(self, adb: AdbProtocol, scale_w: float, *, quick: bool = False) -> str | None:
+        return None
+
+    def _cold_start(self, adb: AdbProtocol, target_layer: str, scale_w: float) -> None:
+        adb.key_event(KEYCODE_HOME)
+        time.sleep(0.8)
+
+        png = adb.screencap()
+        import numpy as np
+        arr = np.frombuffer(png, dtype=np.uint8)
+        arr = __import__("cv2").imdecode(arr, __import__("cv2").IMREAD_COLOR)
+        h, w = arr.shape[:2]
+
+        cold_start_app_from_launcher(
+            adb, "com.xingin.xhs", w, h, scale_w,
+            app_name="xhs", M=4, N=1,
+            force_stop_before=True,
+            deadline_s=20.0,
+        )
+
+        deadline = time.monotonic() + 20.0
+        while time.monotonic() < deadline:
+            if self.detect(adb, scale_w) == target_layer:
+                return
+            time.sleep(1.0)

layernav_android-0.2.0.dist-info/METADATA

@@ -0,0 +1,334 @@
+Metadata-Version: 2.4
+Name: layernav_android
+Version: 0.2.0
+Summary: Multi-layer task-stack navigation framework for Android ADB automation. Define N layers, register per-layer handlers, and let the framework handle BACK recovery, cold-start, and cross-layer verification.
+Project-URL: Homepage, https://github.com/yuyidream/layernav_android
+License: MIT
+License-File: LICENSE
+Keywords: adb,android,app-crawler,automation,crawler,data-collection,fault-tolerance,layer-model,mobile-rpa,navigation,python,task-automation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.12
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: wechat
+Requires-Dist: numpy>=1.24; extra == 'wechat'
+Requires-Dist: opencv-python>=4.8; extra == 'wechat'
+Description-Content-Type: text/markdown
+
+# LayerNav_Android
+
+> A stable page layer navigation framework for Android ADB automation.
+> 基于 ADB 的安卓页面层级导航框架，主打**强校验、自动容错、故障恢复**，适用于 APP 数据采集、移动端 RPA、UI 自动化测试场景。
+>
+> **Python 3.12+** · 零外部依赖 · MIT License
+
+[![PyPI](https://badge.fury.io/py/layernav_android.svg)](https://badge.fury.io/py/layernav_android)
+[![Python](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![CI](https://github.com/yuyidream/layernav_android/actions/workflows/ci.yml/badge.svg)](https://github.com/yuyidream/layernav_android/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/yuyidream/layernav_android/branch/main/graph/badge.svg)](https://codecov.io/gh/yuyidream/layernav_android)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+---
+
+## 一、项目介绍
+
+市面上主流 ADB / UI 自动化库仅提供点击、滑动、返回等基础原子能力，**缺少页面状态校验、层级管理、异常恢复**，脚本极易因页面跳转失败、APP 卡死、返回失灵而中断。
+
+本框架基于 **L0~Ln 页面层级模型** 设计，将手机桌面、APP 主页、内容页、详情页抽象为标准化层级，内置「动作执行 → 截屏校验 → 自动重试 → 冷启动恢复」全链路能力，大幅提升自动化脚本稳定性与开发效率。
+
+### 核心定位
+
+- 不是通用 UI 自动化库，而是 **导航调度 + 容错引擎**
+- 框架负责：层级检测、跳转校验、后退/前进/恢复逻辑、异常兜底
+- 业务脚本负责：控件点击、数据采集、业务逻辑（职责彻底分离）
+
+---
+
+## 二、核心特性
+
+✅ **标准化层级模型**
+统一抽象 `L0(手机桌面) / L1(APP主页) / L2(内容页) / L3(详情页) ... Ln`，一套模型适配绝大多数 APP。
+
+✅ **闭环跳转校验**
+执行操作后自动截屏检测页面，**拒绝盲操作**，跳转失败即时感知。guard（前置校验）+ validator（后置轮询）语义分离。
+
+✅ **完整导航原子 API**
+内置 `detect / enter_next / back_one / back_recover` 四原子操作 + `advance / back / restore` 三组合操作，一行代码完成跨层级跳转。
+
+✅ **故障自动恢复**
+返回键失效、页面卡死、意外退回桌面时，自动执行 `back_recover`：HOME → 冷启动 APP → 快速前进至目标层级 → 正常恢复业务。
+
+✅ **Quick 快速模式**
+专为恢复场景设计，handlers 收到 `quick=True` 时可精简业务逻辑（如选第一个未读），提升导航速度。
+
+✅ **可观测监听器**
+内置 `LayerListener` 观察者接口，零侵入监控层切换、超时、恢复事件，方便接入指标采集与告警。
+
+✅ **解耦设计**
+- 页面检测 `detect` 接口可自由接入：OCR / 图像匹配 / UI 控件解析
+- ADB 客户端通过 `AdbProtocol` 完全抽象，原生 ADB / 风控加固 ADB 均可无缝接入
+- 分层 Handler 机制（`_on_Lx`），业务代码与框架逻辑完全隔离
+
+---
+
+## 三、架构设计
+
+### 1. 层级模型
+
+```
+L0     手机主屏幕（非 APP 前台）
+L1     APP 主界面
+L2     二级内容页
+L3     三级详情页
+...
+Ln     最深业务层级
+```
+
+### 2. 职责划分
+
+| 模块 | 框架能力 | Task 能力 |
+|------|---------|----------|
+| 状态检测 | 调用 `detect()`、校验结果 | 实现截图/识别逻辑 |
+| 页面动作 | 流程调度、等待、重试 | 实现 `_on_Lx` 点击/滑动等业务动作 |
+| 导航逻辑 | `advance` / `back` / `restore` / 恢复 | 无 |
+| 点击 | **不负责** — 框架不 `tap` | handler 内 `adb.tap()` |
+
+### 3. 核心流程
+
+```
+1. detect() 实时识别当前页面层级
+2. 调用对应层级 _on_Lx handler 执行业务操作
+3. 二次校验页面是否到达目标层级（截屏 + 轮询）
+4. 跳转失败 → 自动重试 → 重试失败 → 冷启动恢复
+```
+
+---
+
+## 四、快速上手
+
+### 1. 安装
+
+**方式一：pip 安装（推荐）**
+
+```bash
+pip install layernav_android
+```
+
+如需使用 WeChat contrib 模块，需额外安装 `opencv-python` 和 `numpy`：
+
+```bash
+pip install layernav_android[wechat]
+```
+
+**方式二：从源码安装**
+
+```bash
+git clone https://github.com/yuyidream/layernav_android.git
+cd layernav_android
+pip install -e .
+```
+
+如需运行测试：
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v --tb=short
+```
+
+### 2. 基础使用
+
+继承 `BaseLayerModel`，实现层级检测与页面处理器，即可使用全套导航能力：
+
+```python
+from layernav_android import BaseLayerModel, LayerDef
+
+class DemoAppModel(BaseLayerModel):
+    layers = [
+        LayerDef(key="L0", name="desktop",   label_cn="手机桌面", detection="截屏识别桌面图标"),
+        LayerDef(key="L1", name="app_home",  label_cn="APP 主页", detection="OCR 识别主页文字"),
+        LayerDef(key="L2", name="content",   label_cn="内容列表页", detection="图像特征匹配"),
+        LayerDef(key="L3", name="detail",    label_cn="详情页",   detection="模板匹配"),
+    ]
+
+    def detect(self, adb, scale_w: float) -> str:
+        screenshot = adb.screencap()
+        if is_desktop(screenshot):
+            return "L0"
+        elif is_app_home(screenshot):
+            return "L1"
+        elif is_content_list(screenshot):
+            return "L2"
+        return "L3"
+
+    def _on_L0(self, adb, scale_w, *, quick=False):
+        self._cold_start(adb, "L1", scale_w)
+        return "L1"
+
+    def _on_L1(self, adb, scale_w, *, quick=False) -> str | None:
+        if quick:
+            row = self._pick_first_row(adb, scale_w)
+        else:
+            row = self._scan_and_select(adb, scale_w)
+        if row is None:
+            return None
+        adb.tap(row.x, row.y)
+        return "L2"
+
+    def _on_L2(self, adb, scale_w, *, quick=False) -> str | None:
+        item = self._pick_item(adb, scale_w, quick=quick)
+        if item is None:
+            return None
+        adb.tap(item.x, item.y)
+        return "L3"
+
+    def _on_L3(self, adb, scale_w, *, quick=False) -> str | None:
+        return None  # 最深层，不再前进
+
+
+# 执行导航流程
+model = DemoAppModel()
+adb = get_adb_client()
+
+# 智能恢复到 L1
+model.restore(adb, target_layer="L1", scale_w=1.0)
+# 逐层前进到 L3
+model.advance(adb, target_layer="L3", scale_w=1.0)
+# 后退回 L1
+model.back(adb, to_layer="L1", scale_w=1.0)
+```
+
+### 3. 核心 API
+
+**原子操作**
+
+| 方法 | 说明 |
+|------|------|
+| `detect(adb, scale_w) → str` | 检测当前所在层级（Task 覆盖实现） |
+| `enter_next(adb, scale_w, *, quick, max_wait_s) → bool` | 单步进入下一层 ← guard + validator + 轮询 |
+| `back_one(adb, scale_w) → str` | 单步 `KEYCODE_BACK`，返回新层级 |
+| `back_recover(adb, target, scale_w) → bool` | 故障恢复：HOME → 冷启动 → 快速前进 → 正常恢复 |
+
+**组合操作**
+
+| 方法 | 说明 |
+|------|------|
+| `back(adb, to_layer, scale_w) → bool` | 逐层后退至目标（3 次重试 → 恢复） |
+| `advance(adb, target, scale_w, *, quick, max_wait_s) → bool` | 逐层前进至目标（目标层 always `quick=False`） |
+| `restore(adb, target, scale_w) → bool` | 智能判断方向，从任意位置恢复至目标 |
+
+**可观测**
+
+```python
+from layernav_android import LayerListener
+
+class MetricsListener:
+    def on_transition(self, from_layer, to_layer, method):
+        print(f"{from_layer} → {to_layer} via {method}")
+
+    def on_timeout(self, from_layer, target_layer, elapsed_s):
+        print(f"Timeout {from_layer}→{target_layer} after {elapsed_s:.1f}s")
+
+    def on_recovery(self, target_layer, ok):
+        print(f"Recovery to {target_layer}: {'OK' if ok else 'FAILED'}")
+
+model.add_listener(MetricsListener())
+```
+
+---
+
+## 五、通用冷启动工具
+
+`cold_start_app_from_launcher` 提供统一的 APP 冷启动能力，支持 monkey 主路径 + Dock 图标兜底 + session tab 点击：
+
+```python
+from layernav_android.cold_start import cold_start_app_from_launcher
+
+# 微信冷启动
+ok = cold_start_app_from_launcher(
+    adb, "com.tencent.mm", 1080, 2248, 1.0,
+    app_name="wechat", M=4, N=3,
+    session_tab_x=108, session_tab_y=2192,
+)
+
+# 小红书冷启动
+ok = cold_start_app_from_launcher(
+    adb, "com.xingin.xhs", 1080, 2248, 1.0,
+    app_name="xhs", M=4, N=1,
+)
+```
+
+**关键设计**：使用普通 ADB tap（非防风控触控），因为是系统级操作（桌面 Dock 图标点击），不涉及 APP 内反爬检测，方便所有系统集成。
+
+---
+
+## 六、适用场景
+
+- **APP 合规数据采集** — 内容抓取、列表遍历、批量浏览
+- **移动端 RPA 自动化** — 账号矩阵、批量操作、运营工具
+- **Android UI 自动化测试** — 提升脚本稳定性，减少维护成本
+- **APP 流程逆向 / 行为模拟** — 稳定进入深层页面
+
+---
+
+## 七、优势对比
+
+| 能力 | 本框架 | Appium / uiautomator2 / Airtest |
+|------|--------|---------------------------------|
+| 标准化页面层级 | ✅ 内置模型 | ❌ 无统一抽象 |
+| 操作后页面校验 | ✅ 闭环 guard + validator | ❌ 仅执行动作，不校验结果 |
+| 自动后退恢复 | ✅ 3 次重试 + 冷启动兜底 | ❌ 需手动编写重试逻辑 |
+| 层级穿越 API | ✅ `advance` / `back` / `restore` | ❌ 仅基础点击/返回 |
+| 可观测监听器 | ✅ `LayerListener` 事件回调 | ❌ 需自行埋点 |
+| ADB 解耦 | ✅ `AdbProtocol` 接口抽象 | ⚠️ 部分耦合 |
+
+---
+
+## 八、拓展建议
+
+- **页面检测能力**：可接入 PaddleOCR / EasyOCR / OpenCV 图像匹配
+- **ADB 加固**：对接自定义风控 ADB 客户端，模拟真人操作轨迹
+- **状态机拓展**：可结合 `python-statemachine` 优化状态管理（本框架的 `LayerListener` 即借鉴其设计）
+- **多设备并行**：每设备独立 `BaseLayerModel` 实例即可天然支持多设备
+
+---
+
+## 九、目录结构
+
+```
+layernav_android/
+├── src/layernav_android/
+│   ├── __init__.py          # 公开导出
+│   ├── _protocol.py         # AdbProtocol 接口
+│   ├── base.py              # LayerDef, LayerListener, BaseLayerModel
+│   ├── cold_start.py        # 通用冷启动工具
+│   └── contrib/
+│       ├── __init__.py
+│       ├── wechat.py        # WeChatGroupLayerModel（微信示例）
+│       └── xhs.py           # XhsLayerModel（小红书占位）
+├── tests/
+│   └── test_base.py         # 23 个单元测试
+├── pyproject.toml
+├── README.md
+└── LICENSE
+```
+
+---
+
+## 十、参与贡献
+
+欢迎提交 Issue、PR，共建安卓自动化导航生态：
+
+- **Bug 反馈、功能建议** → [Issues](https://github.com/yuyidream/layernav_android/issues)
+- **代码优化、新增示例** → Pull Request
+
+---
+
+## 十一、开源协议
+
+本项目基于 [MIT License](LICENSE) 开源，可自由用于个人、商业项目。

layernav_android-0.2.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+layernav_android/__init__.py,sha256=WVWd4xwoaewDOerZyrzQa_SN6aR2R-pa7EamsQmyDPQ,573
+layernav_android/_protocol.py,sha256=NLQuU3RLD-n1l5LAEc7ZAM-CNegTO5bnxHO80gDw0yk,546
+layernav_android/base.py,sha256=T9UHXyBriEAJQvqjryGJoeja8V4f2mfxMIX-wATlIFE,11283
+layernav_android/cold_start.py,sha256=9Tx21k7axRRG6dsydbeYrhPeWZ9jb8CUChFgvv8tmhE,5170
+layernav_android/contrib/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+layernav_android/contrib/wechat.py,sha256=YIUG91Zyx3fCdmKDOvkKLgRdBRcX_gWoxAddTcq5yHw,8410
+layernav_android/contrib/xhs.py,sha256=9Oi-TSvh6yfMQNPa4u3HKz4brstMx7VhWPcilFOatH4,2226
+layernav_android-0.2.0.dist-info/METADATA,sha256=-nVHKju44Tk0_YqSPBuOQR6GEoLAv40r-t3VjlgvlwA,12094
+layernav_android-0.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+layernav_android-0.2.0.dist-info/licenses/LICENSE,sha256=jqDbAPajfDAMxAm4FAolM8I7CwnMdVNT6TfQNx2Th8U,1066
+layernav_android-0.2.0.dist-info/RECORD,,

layernav_android-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

layernav_android-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 yuyidream
+
+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.