screenshot-vision-algorithm 0.3.0__py3-none-any.whl

screenshot_vision_algorithm/android/wechat/algorithms/template_matching.py

@@ -0,0 +1,2163 @@
+"""Template-matching primitives for the WeChat OCR collector.
+
+Pure cv2 + numpy + stdlib. Shared between:
+    - live collector runtime (``scripts/wx_match/collector/driver.py``)
+    - cross-device regression tool
+      (``scripts/wx_match/tools/verify_templates.py``)
+
+so that live capture behaviour is bit-identical to what regression tests
+validate on the 3-device matrix.
+
+Design aligned with:
+    DD section 2.4.x C / C2 (new_messages_hint + unread_divider_hint)
+    DD section 2.7.1 P=B+ single-baseline + scale_w strategy
+    DD section 2.7.2 applicable bounds
+    chat_profiles/README.md v0.2.2 threshold table
+    OCR ADR section 2.7.1 integrity gates
+
+Threshold choices:
+    CORE_THRESHOLD = 0.80   (favorite_label / new_messages_hint_suffix /
+                             wechat_note_header; hard gate, FAIL below)
+    BONUS_THRESHOLD = 0.80  (unread_divider_hint happy path)
+    BONUS_MIN_WARN = 0.70   (unread_divider_hint WARN-only floor; triggers
+                             the CC1 degrade path — post-tap sleep + one
+                             extra divider recheck — rather than failing
+                             the whole capture, see DD section 2.4.x C2)
+
+These constants pin the N=3 cross-device calibration from
+``docs/adr/evidence/wx_match_thin_slice_v1/baseline_devices.md``; do NOT
+change them without refreshing that evidence.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from functools import lru_cache
+from pathlib import Path
+from typing import Literal, Optional, Sequence
+
+import cv2
+import numpy as np
+
+# ---- Template asset resolution ----------------------------------------------
+
+_PACKAGE_ROOT = Path(__file__).resolve().parent.parent.parent.parent
+_DEFAULT_TEMPLATES_SUBDIR: str = "android/wechat/templates/android/8.0.69"
+_templates_dir_override: Path | None = None
+
+
+def set_templates_dir(dir_path: Path) -> None:
+    """Override the template asset directory (e.g. for iOS / Harmony profiles)."""
+    global _templates_dir_override
+    _templates_dir_override = dir_path
+
+
+def _templates_dir() -> Path:
+    if _templates_dir_override is not None:
+        return _templates_dir_override
+    return _PACKAGE_ROOT / _DEFAULT_TEMPLATES_SUBDIR
+
+
+TEMPLATES_DIR: Path = _templates_dir()
+
+# edb1a89f is the baseline device (1080x2248). scale_w = device_width / 1080.
+BASELINE_WIDTH = 1080
+
+# ---- Template registry ------------------------------------------------------
+
+TEMPLATE_FILE: dict[str, str] = {
+    "favorite_label": "favorite_label.png",
+    "new_messages_hint_suffix": "new_messages_hint_suffix.png",
+    "unread_divider_hint": "unread_divider_hint.png",
+    "wechat_note_header": "wechat_note_header.png",
+    "chat_back_chevron": "chat_back_chevron.png",
+    "chat_title_more_dots": "chat_title_more_dots.png",
+    "chat_input_voice": "chat_input_voice.png",
+    "chat_input_emoji_smile": "chat_input_emoji_smile.png",
+    "chat_input_plus": "chat_input_plus.png",
+}
+
+TEMPLATE_ROLE: dict[str, Literal["P0-core", "bonus"]] = {
+    "favorite_label": "P0-core",
+    "new_messages_hint_suffix": "P0-core",
+    "wechat_note_header": "P0-core",
+    "chat_back_chevron": "P0-core",
+    "chat_title_more_dots": "P0-core",
+    "chat_input_voice": "P0-core",
+    "chat_input_emoji_smile": "P0-core",
+    "chat_input_plus": "P0-core",
+    "unread_divider_hint": "bonus",
+}
+
+CORE_THRESHOLD = 0.70
+BONUS_THRESHOLD = 0.80
+BONUS_MIN_WARN = 0.60  # was 0.70; lowered to keep < CORE_THRESHOLD (now 0.70)
+
+
+DEFAULT_NMS_DIST = 50  # pixel distance for non-max suppression of dense hits
+
+
+# ---- Value types ------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Hit:
+    """One template match location in raw-image pixel space.
+
+    ``(x, y)`` is the TOP-LEFT corner of the matched patch, so the center is
+    ``(x + w // 2, y + h // 2)`` — use :meth:`center` for the tap target.
+    """
+
+    x: int
+    y: int
+    w: int
+    h: int
+    score: float
+
+    @property
+    def center(self) -> tuple[int, int]:
+        return (self.x + self.w // 2, self.y + self.h // 2)
+
+    @property
+    def bbox(self) -> tuple[int, int, int, int]:
+        """Inclusive-exclusive bbox ``(x1, y1, x2, y2)``."""
+        return (self.x, self.y, self.x + self.w, self.y + self.h)
+
+
+# ---- Primitives -------------------------------------------------------------
+
+
+@lru_cache(maxsize=len(TEMPLATE_FILE) + 2)
+def load_template(name: str) -> np.ndarray:
+    """Load a baseline template (8.0.69) in BGR; cached per process.
+
+    Raises KeyError for unknown names — keep the dict the source of truth.
+    """
+    if name not in TEMPLATE_FILE:
+        raise KeyError(
+            f"unknown template {name!r}; known templates: "
+            f"{sorted(TEMPLATE_FILE)}"
+        )
+    path = TEMPLATES_DIR / TEMPLATE_FILE[name]
+    img = cv2.imread(str(path))
+    if img is None:
+        raise FileNotFoundError(
+            f"template file not found or unreadable: {path!s}"
+        )
+    return img
+
+
+def scale_template(template: np.ndarray, scale_w: float) -> np.ndarray:
+    """Resize template proportionally by ``scale_w`` (``device_width / 1080``).
+
+    Returns the original template when ``scale_w`` is within 0.001 of 1.0 so
+    the baseline device incurs zero resize cost. INTER_CUBIC keeps the edge
+    sharpness cv2.matchTemplate relies on.
+    """
+    if abs(scale_w - 1.0) < 1e-3:
+        return template
+    return cv2.resize(
+        template, None, fx=scale_w, fy=scale_w,
+        interpolation=cv2.INTER_CUBIC,
+    )
+
+
+def match_all(
+    screen: np.ndarray,
+    template: np.ndarray,
+    threshold: float,
+    nms_dist: int = DEFAULT_NMS_DIST,
+) -> list[Hit]:
+    """Run ``TM_CCOEFF_NORMED`` + greedy NMS; return all surviving hits.
+
+    Hits are sorted by Y ascending (top-to-bottom reading order) to match
+    the convention the verification tool prints and the driver consumes.
+    """
+    if screen.shape[0] < template.shape[0] or screen.shape[1] < template.shape[1]:
+        # Template larger than screen (pathological scale_w) — no hits.
+        return []
+
+    result = cv2.matchTemplate(screen, template, cv2.TM_CCOEFF_NORMED)
+    ys, xs = np.where(result >= threshold)
+    candidates = sorted(
+        (
+            (int(x), int(y), float(result[y, x]))
+            for x, y in zip(xs, ys)
+        ),
+        key=lambda c: -c[2],  # descending score → greedy NMS keeps the best
+    )
+
+    th, tw = template.shape[:2]
+    kept: list[Hit] = []
+    for x, y, s in candidates:
+        if any(abs(x - k.x) < nms_dist and abs(y - k.y) < nms_dist for k in kept):
+            continue
+        kept.append(Hit(x=x, y=y, w=tw, h=th, score=s))
+
+    kept.sort(key=lambda h: h.y)
+    return kept
+
+
+def match_best(
+    screen: np.ndarray,
+    template: np.ndarray,
+    threshold: float,
+) -> Optional[Hit]:
+    """Return the single highest-score hit at-or-above ``threshold``, or None."""
+    hits = match_all(screen, template, threshold)
+    if not hits:
+        return None
+    return max(hits, key=lambda h: h.score)
+
+
+# ---- Convenience detectors (collector driver entry points) ------------------
+
+
+def detect_new_messages_hint(
+    screen: np.ndarray,
+    scale_w: float,
+    threshold: float = CORE_THRESHOLD,
+) -> Optional[Hit]:
+    """Detect the "... new messages" floating hint button.
+
+    Returns the best-scoring hit (tap target = ``Hit.center``) or None if the
+    template does not hit at all at ``threshold``. The caller decides what to
+    do with None (usually: the user already scrolled past it, skip the step).
+    """
+    template = scale_template(load_template("new_messages_hint_suffix"), scale_w)
+    return match_best(screen, template, threshold)
+
+
+def detect_unread_divider(
+    screen: np.ndarray,
+    scale_w: float,
+    threshold: float = BONUS_MIN_WARN,
+) -> Optional[Hit]:
+    """Detect the "以下为新消息" divider (bonus template).
+
+    Threshold defaults to ``BONUS_MIN_WARN`` (0.70) to accept faint divider
+    lines on devices like Honor where ``unread_divider_hint`` scored ~0.755
+    at baseline calibration. Callers that want a stricter signal should pass
+    ``threshold=BONUS_THRESHOLD`` (0.80).
+    """
+    template = scale_template(load_template("unread_divider_hint"), scale_w)
+    return match_best(screen, template, threshold)
+
+
+def detect_favorite_labels(
+    screen: np.ndarray,
+    scale_w: float,
+    threshold: float = CORE_THRESHOLD,
+) -> list[Hit]:
+    """Find every ``favorite_label.png`` hit on the chat screenshot.
+
+    One hit per resume-thumbnail card that is currently visible (DD
+    section 2.4.x A stage 1). The list is top-to-bottom sorted
+    (:func:`match_all` already sorts by y). Empty list means no cards
+    visible — caller typically keeps scrolling instead of entering the
+    resume sub-flow.
+    """
+    template = scale_template(load_template("favorite_label"), scale_w)
+    return match_all(screen, template, threshold)
+
+
+def _chat_title_bar_vertical_band(
+    screen_h: int, scale_w: float,
+) -> tuple[int, int]:
+    """Y-extent shared by chat/note top chrome (baseline-calibrated strip)."""
+    sw = max(scale_w, 1e-6)
+    y1 = int(round(108 * sw))
+    y2 = int(round(220 * sw))
+    y1 = max(0, min(max(2, screen_h) - 2, y1))
+    y2 = max(y1 + 40, min(screen_h, y2))
+    return y1, y2
+
+
+def _patch_nav_color_gate(patch_bgr: np.ndarray) -> bool:
+    """Light WeChat navigation bar backdrop + observable dark glyphs (BGR).
+
+    Complements TM_CCOEFF_NORMED: rejects bogus hits on uniformly flat
+    patches while allowing mostly-light strips that still bear a faint dark
+    chevron / dot trio (thin strokes keep ``dark_frac`` modest).
+    """
+    if patch_bgr is None or patch_bgr.size < 240:
+        return False
+    gray = cv2.cvtColor(patch_bgr, cv2.COLOR_BGR2GRAY).astype(np.float32)
+    hi = float(np.percentile(gray, 78))
+    v_med = float(np.median(gray))
+    dark_frac = float((gray < 92).mean())
+    mid_dark_frac = float((gray < 125).mean())
+    # Reject very dim overlays / non-chrome slabs.
+    if v_med < 88 or hi < 115:
+        return False
+    # Reject uniformly flat patches (no plausible icon ink at all).
+    if dark_frac < 0.010 and mid_dark_frac < 0.022:
+        return False
+    return True
+
+
+def _expand_hit_gate_patch(screen_bgr: np.ndarray, hit: Hit, scale_w: float) -> bool:
+    pad = max(6, int(round(7 * max(scale_w, 1e-6))))
+    h, w_full = screen_bgr.shape[:2]
+    px1 = max(0, hit.x - pad)
+    py1 = max(0, hit.y - pad)
+    px2 = min(w_full, hit.x + hit.w + pad)
+    py2 = min(h, hit.y + hit.h + pad)
+    return _patch_nav_color_gate(screen_bgr[py1:py2, px1:px2])
+
+
+def _suppress_conversation_nav_templates_for_session_list_chrome(
+    screen_bgr: np.ndarray,
+    scale_w: float,
+) -> bool:
+    """Do not expose 「<」「⋯」「底栏话筒/笑脸/+」as *chat-shell* cues on微信主会话列表壳.
+
+    仅 **会话列表**：与 :func:`is_wechat_main_conversation_list_chrome`（
+    ``require_visible_pinned_row=False``）对齐，避免误判成群聊；
+    「左上 「<」+ 右上 ⋯」成对 TM 的假阳性亦不在这层壳上当聊天锚点上送。
+
+    **笔记页**：不由此函数抑制——``detect_chat_title_more_dots`` 仍单独用
+    ``detect_wechat_note_header`` 门控以避免 Honor／宽屏上对 ``wx_note`` 的假阳性。
+    """
+    if is_wechat_main_conversation_list_chrome(
+            screen_bgr,
+            scale_w,
+            require_visible_pinned_row=False,
+    ):
+        return True
+    return False
+
+
+def match_chat_back_chevron_core(
+    screen_bgr: np.ndarray,
+    scale_w: float,
+    threshold: float = CORE_THRESHOLD,
+) -> Optional[Hit]:
+    """Internal: 「<」 match + light-nav ink gate (**no**主会话列表壳抑制逻辑)."""
+    tpl = scale_template(load_template("chat_back_chevron"), scale_w)
+    tw, th = tpl.shape[1], tpl.shape[0]
+    h, w = screen_bgr.shape[:2]
+    sw = max(scale_w, 1e-6)
+    y1, y2 = _chat_title_bar_vertical_band(h, sw)
+    roi_h = y2 - y1
+    if roi_h < th + 6:
+        return None
+    x2 = min(w, max(int(round(145 * sw)), tw + int(round(20 * sw))))
+    roi_w = x2
+    if roi_w < tw + 4:
+        return None
+    roi = screen_bgr[y1:y2, 0:x2]
+    cand = match_best(roi, tpl, threshold)
+    if cand is None:
+        return None
+    abs_hit = Hit(x=cand.x, y=cand.y + y1, w=cand.w, h=cand.h, score=cand.score)
+    if not _expand_hit_gate_patch(screen_bgr, abs_hit, sw):
+        return None
+    return abs_hit
+
+
+def match_chat_title_more_dots_core(
+    screen_bgr: np.ndarray,
+    scale_w: float,
+    threshold: float = CORE_THRESHOLD,
+) -> Optional[Hit]:
+    """Internal: 「⋯」 match + light-nav ink gate (**no** note_header 抑制逻辑)."""
+    tpl = scale_template(load_template("chat_title_more_dots"), scale_w)
+    tw, th = tpl.shape[1], tpl.shape[0]
+    h, w = screen_bgr.shape[:2]
+    sw = max(scale_w, 1e-6)
+    y1, y2 = _chat_title_bar_vertical_band(h, sw)
+    if y2 - y1 < th + 6:
+        return None
+    band_left = max(0, w - max(int(round(278 * sw)), tw + int(round(24 * sw))))
+    roi = screen_bgr[y1:y2, band_left:w]
+    if roi.shape[1] < tw + 6:
+        return None
+    cand = match_best(roi, tpl, threshold)
+    if cand is None:
+        return None
+    abs_hit = Hit(
+        x=cand.x + band_left,
+        y=cand.y + y1,
+        w=cand.w,
+        h=cand.h,
+        score=cand.score,
+    )
+    if not _expand_hit_gate_patch(screen_bgr, abs_hit, sw):
+        return None
+    return abs_hit
+
+
+def detect_chat_back_chevron(
+    screen_bgr: np.ndarray,
+    scale_w: float,
+    threshold: float = CORE_THRESHOLD,
+) -> Optional[Hit]:
+    """Top-left 「<」return control on group/single-chat title bar."""
+    back = match_chat_back_chevron_core(screen_bgr, scale_w, threshold)
+    if _suppress_conversation_nav_templates_for_session_list_chrome(
+            screen_bgr, scale_w,
+    ):
+        return None
+    return back
+
+
+def detect_chat_title_more_dots(
+    screen_bgr: np.ndarray,
+    scale_w: float,
+    threshold: float = CORE_THRESHOLD,
+) -> Optional[Hit]:
+    """Top-right vertical 「⋯」menu control on chat title bars."""
+    if detect_wechat_note_header(screen_bgr, scale_w) is not None:
+        return None
+    more = match_chat_title_more_dots_core(screen_bgr, scale_w, threshold)
+    if _suppress_conversation_nav_templates_for_session_list_chrome(
+            screen_bgr, scale_w,
+    ):
+        return None
+    return more
+
+
+def _chat_bottom_input_roi(screen_bgr: np.ndarray, scale_w: float) -> np.ndarray:
+    """Bottom / keyboard-adjacent band for 话筒・表情・「+」（含输入框略抬高时的中区）。"""
+    h, w = screen_bgr.shape[:2]
+    sw = max(scale_w, 1e-6)
+    y0 = max(0, h - int(round(320 * sw)))
+    return screen_bgr[y0:h, :]
+
+
+def _detect_chat_input_bar_icon_best(
+    screen_bgr: np.ndarray,
+    scale_w: float,
+    tmpl_key: Literal[
+        "chat_input_voice", "chat_input_emoji_smile", "chat_input_plus",
+    ],
+    threshold: float = CORE_THRESHOLD,
+) -> Optional[Hit]:
+    sw = max(scale_w, 1e-6)
+    tpl = scale_template(load_template(tmpl_key), scale_w)
+    th, tw = tpl.shape[:2]
+    roi = _chat_bottom_input_roi(screen_bgr, sw)
+    if roi.shape[0] < th + 3 or roi.shape[1] < tw + 3:
+        return None
+    h_full = screen_bgr.shape[0]
+    y_off = max(0, h_full - int(round(320 * sw)))
+    cand = match_best(roi, tpl, threshold)
+    if cand is None:
+        return None
+    return Hit(
+        x=int(cand.x),
+        y=int(cand.y + y_off),
+        w=int(cand.w),
+        h=int(cand.h),
+        score=float(cand.score),
+    )
+
+
+def detect_chat_input_voice_button(
+    screen_bgr: np.ndarray,
+    scale_w: float,
+    threshold: float = CORE_THRESHOLD,
+) -> Optional[Hit]:
+    """Left-side 「按住说话」麦克风区抠图锚点。"""
+    if _suppress_conversation_nav_templates_for_session_list_chrome(
+            screen_bgr, scale_w,
+    ):
+        return None
+    return _detect_chat_input_bar_icon_best(
+        screen_bgr, scale_w, "chat_input_voice", threshold,
+    )
+
+
+def detect_chat_input_emoji_smile_button(
+    screen_bgr: np.ndarray,
+    scale_w: float,
+    threshold: float = CORE_THRESHOLD,
+) -> Optional[Hit]:
+    """输入栏表情（笑脸）图标抠图锚点。"""
+    if _suppress_conversation_nav_templates_for_session_list_chrome(
+            screen_bgr, scale_w,
+    ):
+        return None
+    return _detect_chat_input_bar_icon_best(
+        screen_bgr, scale_w, "chat_input_emoji_smile", threshold,
+    )
+
+
+def detect_chat_input_plus_button(
+    screen_bgr: np.ndarray,
+    scale_w: float,
+    threshold: float = CORE_THRESHOLD,
+) -> Optional[Hit]:
+    """输入栏右侧「+」（附件）图标抠图锚点。"""
+    if _suppress_conversation_nav_templates_for_session_list_chrome(
+            screen_bgr, scale_w,
+    ):
+        return None
+    return _detect_chat_input_bar_icon_best(
+        screen_bgr, scale_w, "chat_input_plus", threshold,
+    )
+
+
+def detect_wechat_note_header(
+    screen: np.ndarray,
+    scale_w: float,
+    threshold: float = CORE_THRESHOLD,
+) -> Optional[Hit]:
+    """Verify the ``wechat_note_header.png`` (""笔记"" tab marker) is on screen.
+
+    Two uses in Day 1b:
+        - ``tap_thumbnail`` post-tap: confirms the tap actually landed on a
+          resume card and WeChat loaded the note-detail page (vs. e.g.
+          launching an image viewer).
+        - ``detail_content_scroll_down`` per-screen liveness: guards against having
+          accidentally bounced back to the chat page.
+
+    Returns the best hit (or None at threshold miss). Hit position is
+    ignored by callers; they only care about hit / no-hit.
+    """
+    template = scale_template(load_template("wechat_note_header"), scale_w)
+    return match_best(screen, template, threshold)
+
+
+def classify_top_bottom(hit: Hit, screen_h: int) -> Literal["top", "bottom"]:
+    """Assign ``click_position`` based on hit center vs. mid-screen.
+
+    DD section 2.4.x C: the new-messages hint button floats top-right on the
+    first unread screen and re-appears bottom-right after the user scrolls
+    down; ``click_position`` captures which side we tapped so the processor
+    can reconcile ordering.
+    """
+    cy = hit.y + hit.h // 2
+    return "top" if cy < screen_h / 2 else "bottom"
+
+
+# ---- Day 4 auto-scan detectors (d4-auto-scan) -------------------------------
+#
+# Design decision (2026-04-29): WeChat "pinned group + red unread badge"
+# detection deliberately uses HSV color thresholding instead of a template
+# file. Rationale:
+#   (1) Red badges are tiny (~26x26 @ 1080 baseline) and the color signal is
+#       the actual discriminator; template matching adds no signal above a
+#       well-tuned HSV filter.
+#   (2) Pinned-badge geometric marker differs across WeChat sub-versions in
+#       subtle ways (light-gray cell background vs. tiny icon). That
+#       template would need per-device recalibration; deferred to Day 6
+#       (d6-1 真机多轮跑 + trigger-playbook "pinned_badge_calibration").
+#   (4) Session list unread counts are read only from the **avatar
+#       top-right** ROI per row in ``TopGroupScanDriver.scan_pinned_groups``.
+#
+# HSV red thresholds chosen from empirical review of 3 real-world WeChat
+# unread badges (see docs/adr/evidence/wx_match_thin_slice_v1/): WeChat's
+# badge red sits roughly at H≈0..10 or H≈170..180, S≥120, V≥120. These
+# constants are exposed so calibration tweaks can land without touching
+# callers.
+
+RED_HSV_LOW_LO: tuple[int, int, int] = (0, 120, 120)
+RED_HSV_LOW_HI: tuple[int, int, int] = (10, 255, 255)
+RED_HSV_HIGH_LO: tuple[int, int, int] = (170, 120, 120)
+RED_HSV_HIGH_HI: tuple[int, int, int] = (180, 255, 255)
+
+#: List **avatar** unread badges (incl. mute ``...`` style): red can look
+#: slightly desaturated; keep a second, looser saturation/value floor for
+#: :func:`detect_unread_dots` when called from session-list scan only.
+LIST_AVATAR_BADGE_SAT_MIN = 88
+# Slightly below previous 82: last-visible-row digit badges can read V≈79–81
+# under warm backlight (edb1a89f 20260507 probe 007) while staying above noise.
+LIST_AVATAR_BADGE_VAL_MIN = 78
+# Hue coverage for the wrap-around “low reds” (wider than generic 0–10).
+LIST_AVATAR_BADGE_LOW_H_MAX = 15
+# Supplemental orange-red band (H≈16–35) OR'd when ``orange_aux=True``.
+# Warm-tinted list badges can sit in 16–26; primary 0–low_h misses them unless
+# merged with stricter S/V (last-row supplement in list scan driver).
+LIST_AVATAR_BADGE_ORANGE_AUX_HUE_LO = 16
+LIST_AVATAR_BADGE_ORANGE_AUX_HUE_HI = 35
+LIST_AVATAR_BADGE_ORANGE_AUX_SAT_MIN = 65
+LIST_AVATAR_BADGE_ORANGE_AUX_VAL_MIN = 60
+# Min area tuned for list badges; white glyphs can split the red mask —
+# :func:`detect_unread_dots` may merge via ``morph_dilate_iters`` in-driver.
+LIST_AVATAR_BADGE_MIN_AREA_BASELINE = 88
+
+#: Minimum bounding-box area (in baseline-pixel units, so scale_w invariant)
+#: for a red region to qualify as an unread badge. WeChat badge
+#: pixel-diameter ≈ 26 → area ≈ 530 px² at the baseline 1080x2248; 120 gives
+#: plenty of headroom for sub-pixel anti-alias edges while rejecting most
+#: red emoji / stickers.
+UNREAD_DOT_MIN_AREA_BASELINE = 120
+
+#: Maximum bounding-box area at baseline pixel scale. Anything larger is
+#: almost certainly a red sticker / image preview, not a badge.
+UNREAD_DOT_MAX_AREA_BASELINE = 3000
+
+#: Maximum aspect ratio (max(w,h)/min(w,h)) — badges are near-circular, so
+#: elongated red runs (e.g. a red progress bar) are filtered out.
+UNREAD_DOT_MAX_ASPECT = 1.8
+
+#: Minimum circularity (``4π·area / perimeter²``) — real unread badges are
+#: near-perfect circles / ellipses and measure ``≈ 0.89`` on 49×49 badges
+#: (Day 6 edb1a89f baseline: 0.898 / 0.890 / 0.889 / 0.897 / 0.892). Avatar-
+#: interior red decorations / red text / red stickers are typically
+#: irregular (``< 0.4``). Default ``0.0`` preserves backward compatibility
+#: with callers that don't want the hard geometric gate; session-list
+#: scanners should pass ``UNREAD_DOT_LIST_MIN_CIRCULARITY`` for Day 6
+#: calibration (2026-04-30 real-device regression: row 1 false positive
+#: entered a "no unread" group because avatar-inside red element passed
+#: HSV but not circularity). Probe 00002 edb1a89f: one digit badge measures
+#: ``≈0.54`` after ``morph_open`` — a hard ``0.55`` floor dropped it before
+#: the avatar-anchor gate (still well above avatar-interior clutter ``<0.4``).
+UNREAD_DOT_LIST_MIN_CIRCULARITY = 0.54
+
+
+@dataclass(frozen=True)
+class UnreadDotHit:
+    """One detected red unread badge in raw-image pixel space.
+
+    Attributes mirror :class:`Hit` (x/y/w/h are the bounding-box corner +
+    extent) but we give it its own name because HSV thresholding doesn't
+    emit a correlation score — ``area`` stands in as "how bold the badge
+    looked" for QA logging.
+    """
+
+    x: int
+    y: int
+    w: int
+    h: int
+    area: int
+
+    @property
+    def center(self) -> tuple[int, int]:
+        return (self.x + self.w // 2, self.y + self.h // 2)
+
+
+def detect_unread_dots(
+    screen: np.ndarray,
+    scale_w: float,
+    *,
+    roi_bbox: Optional[tuple[int, int, int, int]] = None,
+    min_area_baseline: int = UNREAD_DOT_MIN_AREA_BASELINE,
+    max_area_baseline: int = UNREAD_DOT_MAX_AREA_BASELINE,
+    max_aspect: float = UNREAD_DOT_MAX_ASPECT,
+    min_circularity: float = 0.0,
+    red_saturation_min: int = 120,
+    red_value_min: int = 120,
+    low_red_hue_max: int = 10,
+    morph_open_iters: int = 0,
+    morph_dilate_iters: int = 0,
+    orange_aux: bool = False,
+) -> list[UnreadDotHit]:
+    """Find red unread badges anywhere in ``screen`` (or within ``roi_bbox``).
+
+    Algorithm:
+        1. Convert ROI to HSV.
+        2. OR two red hue bands (``0..10`` + ``170..180``) into a binary mask.
+        3. Morph close (3x3 kernel) to fill anti-alias gaps.
+        4. ``findContours``; filter by area + aspect ratio to reject
+           stickers / emoji / progress bars.
+
+    Args:
+        screen: BGR screenshot (raw-pixel space).
+        scale_w: ``device_width / 1080``; used to scale min/max area
+            thresholds so detection is resolution-invariant.
+        roi_bbox: Optional ``(x1, y1, x2, y2)`` to restrict the search
+            (e.g., when you already know conversation rows bounds).
+            ``None`` scans the whole frame.
+        min_area_baseline: Minimum badge area in baseline-1080 px²
+            (default ``UNREAD_DOT_MIN_AREA_BASELINE``).
+        max_area_baseline: Maximum badge area in baseline-1080 px²
+            (default ``UNREAD_DOT_MAX_AREA_BASELINE``).
+        max_aspect: Reject elongated shapes (default ``UNREAD_DOT_MAX_ASPECT``).
+        min_circularity: Reject non-circular red blobs (avatar-interior red
+            decorations / red text / red stickers). ``0.0`` (default) keeps
+            old behavior; session-list scanners pass
+            :data:`UNREAD_DOT_LIST_MIN_CIRCULARITY` (``0.54``, Day 6 edb1a89f
+            regression). Circularity = ``4π·area / perimeter²``.
+        red_saturation_min / red_value_min: HSV floors (default 120; list
+            avatar scan uses lower values via :data:`LIST_AVATAR_BADGE_SAT_MIN`).
+        low_red_hue_max: upper end of hue wrap ``0°`` band (default ``10``).
+        morph_open_iters: pre-processing erosion+dilation pass (default
+            ``0``). Use ``1`` to break 1-2 px "bridges" between a
+            genuine badge and surrounding avatar-interior red decoration
+            (Day 6' edb1a89f r10: "A十月天使" avatar's red background
+            touched the top-right badge through a thin neck, fusing both
+            into one h=55 irregular blob at the ``morph_close`` stage;
+            a single open iteration restores them to independent blobs).
+            Applied BEFORE ``morph_close`` so the close pass can still
+            heal anti-alias nicks inside the now-isolated badge.
+        morph_dilate_iters: extra dilation to bridge gaps from white glyphs
+            (e.g. ``...``) splitting the red mask (default ``0``).
+        orange_aux: when ``True``, OR a supplemental HSV window
+            (:data:`LIST_AVATAR_BADGE_ORANGE_AUX_HUE_LO` …
+            :data:`LIST_AVATAR_BADGE_ORANGE_AUX_HUE_HI` at
+            :data:`LIST_AVATAR_BADGE_ORANGE_AUX_SAT_MIN` /
+            :data:`LIST_AVATAR_BADGE_ORANGE_AUX_VAL_MIN`) into the mask before
+            morphology. Used only for narrow follow-up ROIs (e.g. last list row)
+            so bottom-row warm/orange unread pills still threshold without
+            widening the global column scan.
+
+    Returns:
+        Top-to-bottom sorted list of hits. Empty list when no red passes
+        the filters (most common on a calm conversation list).
+    """
+    # Clamp ROI against frame bounds to survive callers that passed
+    # coordinates from a baseline-scaled computation.
+    h_full, w_full = screen.shape[:2]
+    if roi_bbox is None:
+        x1, y1, x2, y2 = 0, 0, w_full, h_full
+    else:
+        x1, y1, x2, y2 = roi_bbox
+        x1 = max(0, min(w_full, x1))
+        y1 = max(0, min(h_full, y1))
+        x2 = max(x1, min(w_full, x2))
+        y2 = max(y1, min(h_full, y2))
+    if x2 <= x1 or y2 <= y1:
+        return []
+
+    roi = screen[y1:y2, x1:x2]
+    hsv = cv2.cvtColor(roi, cv2.COLOR_BGR2HSV)
+    low_lo = np.array((0, red_saturation_min, red_value_min), dtype=np.uint8)
+    low_hi = np.array((low_red_hue_max, 255, 255), dtype=np.uint8)
+    high_lo = np.array((170, red_saturation_min, red_value_min), dtype=np.uint8)
+    high_hi = np.array((180, 255, 255), dtype=np.uint8)
+    mask_low = cv2.inRange(hsv, low_lo, low_hi)
+    mask_high = cv2.inRange(hsv, high_lo, high_hi)
+    mask = cv2.bitwise_or(mask_low, mask_high)
+    if orange_aux:
+        aux_lo = np.array(
+            (
+                LIST_AVATAR_BADGE_ORANGE_AUX_HUE_LO,
+                LIST_AVATAR_BADGE_ORANGE_AUX_SAT_MIN,
+                LIST_AVATAR_BADGE_ORANGE_AUX_VAL_MIN,
+            ),
+            dtype=np.uint8,
+        )
+        aux_hi = np.array(
+            (LIST_AVATAR_BADGE_ORANGE_AUX_HUE_HI, 255, 255), dtype=np.uint8
+        )
+        mask = cv2.bitwise_or(mask, cv2.inRange(hsv, aux_lo, aux_hi))
+
+    kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (3, 3))
+    if morph_open_iters > 0:
+        # ``open`` (erode-then-dilate) severs 1-2 px bridges between
+        # the badge and surrounding red decoration. We skip the usual
+        # ``close`` in this mode because close would re-weld the same
+        # bridges we just cut — verified empirically on edb1a89f r10
+        # "A十月天使": open alone gives bbox 27×28 circ=0.88; adding
+        # close after puts it back to 27×70 circ=0.27.
+        mask = cv2.morphologyEx(
+            mask, cv2.MORPH_OPEN, kernel, iterations=morph_open_iters,
+        )
+    else:
+        mask = cv2.morphologyEx(mask, cv2.MORPH_CLOSE, kernel)
+    if morph_dilate_iters > 0:
+        mask = cv2.dilate(mask, kernel, iterations=morph_dilate_iters)
+
+    contours, _ = cv2.findContours(
+        mask, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE
+    )
+
+    # Scale area thresholds by the actual surface area ratio (scale_w²)
+    # so resolution-invariance survives the device matrix we target
+    # (see DD §2.7.2 applicable-bounds table).
+    area_scale = max(scale_w, 1e-3) ** 2
+    min_area = int(min_area_baseline * area_scale)
+    max_area = int(max_area_baseline * area_scale)
+
+    hits: list[UnreadDotHit] = []
+    for c in contours:
+        rx, ry, rw, rh = cv2.boundingRect(c)
+        area = int(cv2.contourArea(c))
+        if area < min_area or area > max_area:
+            continue
+        # Aspect ratio filter — badges are near-circular.
+        long_side = max(rw, rh)
+        short_side = max(1, min(rw, rh))
+        if long_side / short_side > max_aspect:
+            continue
+        # Circularity filter (Day 6 edb1a89f real-device regression): red
+        # avatar-interior elements pass HSV but have irregular contours.
+        # Guarded by a user-opt-in threshold so pre-Day-6 callers (whose
+        # fixtures don't expect this gate) keep their behavior.
+        if min_circularity > 0.0:
+            perim = cv2.arcLength(c, closed=True)
+            if perim <= 0:
+                continue
+            circularity = 4.0 * np.pi * area / (perim * perim)
+            if circularity < min_circularity:
+                continue
+        hits.append(
+            UnreadDotHit(
+                x=rx + x1,
+                y=ry + y1,
+                w=rw,
+                h=rh,
+                area=area,
+            )
+        )
+
+    hits.sort(key=lambda h: h.y)
+    return hits
+
+
+def dedupe_unread_dot_hits(
+    hits: list[UnreadDotHit],
+    *,
+    min_center_dist: float = 26.0,
+) -> tuple[UnreadDotHit, ...]:
+    """Merge HSV unread hits from overlapping ROIs (avatar vs timestamp strip).
+
+    When ``scan_pinned_groups`` scans two regions per row, the same blob can
+    be picked up twice if ROIs intersect — greedy keep-by-area + center
+    distance suppresses duplicates.
+    """
+    if not hits:
+        return ()
+    ordered = sorted(hits, key=lambda h: (-h.area, h.y, h.x))
+    kept: list[UnreadDotHit] = []
+    for h in ordered:
+        cx, cy = h.center
+        if any(
+            abs(cx - k.center[0]) < min_center_dist
+            and abs(cy - k.center[1]) < min_center_dist
+            for k in kept
+        ):
+            continue
+        kept.append(h)
+    kept.sort(key=lambda h: h.y)
+    return tuple(kept)
+
+
+#: Baseline conversation-list row height @ 1080x2248 (measured from WeChat
+#: 8.0.69 on Mi 8 UD). Each row spans one contact/group with avatar + name +
+#: preview + right-side time/badge stack. Used as a heuristic row-split
+#: primitive when the driver has no independent row-boundary anchor (the
+#: ADR §2.7 "图像模板 + 比例坐标" rule — no poco / Accessibility).
+#: Touch SSOT: adb ``input`` only (OCR ADR §6.1.3.1.1) — no sendevent / /dev/input/event*
+#:   / USB-HID keyboard-mouse emulation.
+CONVERSATION_ROW_HEIGHT_BASELINE = 178
+
+#: Top inset (below the search bar) where the first row begins at baseline.
+#: Status bar + search bar area is ~280 px — anything above that is not a
+#: conversation row and should be skipped.
+#:
+#: NOTE (Day 6 edb1a89f 2026-04-30): this constant is the FALLBACK when
+#: :func:`detect_wechat_main_title_bottom_y` cannot anchor the top nav
+#: bar. In practice the session-list scanner calls the dynamic anchor
+#: first and passes its result as ``first_row_top_baseline`` override,
+#: which makes row split robust to pull-to-refresh bounce states where
+#: the content region is briefly offset from the static chrome.
+CONVERSATION_FIRST_ROW_TOP_BASELINE = 280
+
+#: Avatar column ends ~here @ 1080 baseline; nickname + preview middle band;
+# mirrors :meth:`collector.driver.TopGroupScanDriver.scan_pinned_groups`.
+CONVERSATION_AVATAR_RIGHT_EDGE_BASELINE = 220
+CONVERSATION_RIGHT_SIDE_RESERVED_BASELINE = 220
+
+#: Horizontal ROI (1080 baseline) for list-side avatar centroid detection — left
+#: strip only; narrower than ``CONVERSATION_AVATAR_RIGHT_EDGE`` to avoid昵称列误检。
+CONVERSATION_LIST_AVATAR_ROI_LEFT_BASELINE = 24
+CONVERSATION_LIST_AVATAR_ROI_RIGHT_BASELINE = 200
+
+#: Hough 头像列：**median ± half_width×scale**（与同列蓝框对齐略放宽；Hough 偶发右偏需 ≥~56）。
+CONVERSATION_LIST_AVATAR_MEDIAN_X_HALF_WIDTH_BASELINE = 56
+
+#: 底栏墨色带 **上沿** 距屏幕底偏移（与 :func:`detect_wechat_main_bottom_tab_bar_four_columns` ROI 同源）。
+_WECHAT_MAIN_NAV_TAB_BAND_TOP_OFFSET_FROM_BOTTOM_BASELINE = 152
+
+#: 头像 centroid Hough 的竖直 ROI 下边界须早于底栏再上移，剔除「微信」Tab 矢量圆等非会话头像。
+LIST_AVATAR_HOUGH_CLEAR_ABOVE_NAV_BAND_TOP_BASELINE = 16
+
+#: Legacy 占位：整块底栏占位（略高于上条 ``152``）；与 ``nav-exclusive``cap 取 **min** 以更严者为准。
+CONVERSATION_LIST_AVATAR_HOUGH_ROI_NAV_FALLBACK_GAP_FROM_BOTTOM_BASELINE = 160
+
+#: 头像 Hough 圆心（**裁剪坐标 yi**）须 **≤ roi_h − 本值×scale**；与同列 ±56 median 共存时压住 Dock 误导检。
+LIST_AVATAR_HOUGH_MAX_CROP_Y_FROM_ROI_BOTTOM_BASELINE = 102
+
+#: ``ymin_gap`` 叠行：**仅当 Δy≤本阈值×scale（且 < ymin_gap）** 才把两圆收成同一头像去重，
+#: 否则会话行距略小于 ``ymin_gap``（如 Δy≈117.5 对 118）应拆成两行。
+LIST_AVATAR_STACK_SAME_ICON_MAX_CENTER_DY_BASELINE = 92
+
+#: 会话列表 centroid 行带与屏缘相交后：**中间行**至少保留约此高度×scale，否则该行丢弃。
+#: （原硬编码 ``90×scale_w``。）
+CONVERSATION_LIST_AVATAR_ROW_MIN_VISIBLE_HEIGHT_AFTER_CLIP_BASELINE = 90
+
+#: **第一行／最后一行**可与列表顶/底各截一半可视面积 ⇒ 阈值 = 上行 ×本比例后再乘 ``scale_w``。
+CONVERSATION_LIST_AVATAR_ROW_MIN_VISIBLE_HEIGHT_EDGE_FRAC = 0.5
+
+#: 「圆角方块」近似：灰度上做 **形态学梯度** 的核宽（正方形，baseline px @1080）。
+LIST_AVATAR_ROUNDRECT_MORPH_GRAD_KERNEL_BASELINE = 5
+#: OTSU 二值后对边界带 **闭运算** 闭合圆角外轮廓（过大易把行间糊成整块）。
+LIST_AVATAR_ROUNDRECT_CLOSE_KERNEL_BASELINE = 11
+#: bbox 最短边约在 ``[MIN, MAX]×scale`` 视作头像尺度。
+LIST_AVATAR_ROUNDRECT_BBOX_SIDE_MIN_BASELINE = 44
+LIST_AVATAR_ROUNDRECT_BBOX_SIDE_MAX_BASELINE = 152
+LIST_AVATAR_ROUNDRECT_EXTENT_MIN = 0.10
+LIST_AVATAR_ROUNDRECT_EXTENT_MAX = 0.96
+LIST_AVATAR_ROUNDRECT_SOLIDITY_MIN = 0.48
+LIST_AVATAR_ROUNDRECT_MIN_ASPECT = 0.66
+
+#: PRD ``product_requirement_document.md`` §14：校准段内相邻行距 **极差**
+#: ``max(gap) − min(gap)`` 上限（等价于所有两两行距之差均 ≤该值）。
+#: Baseline px，按 ``screen_height / LIST_ROW_SCREEN_HEIGHT_CALIBRATION_Y12_BASELINE`` 缩放。
+LIST_ROW_GEOMETRY_Y12_GAP_SPREAD_MAX_BASELINE = 30
+LIST_ROW_SCREEN_HEIGHT_CALIBRATION_Y12_BASELINE = 2248
+
+
+def conversation_list_avatar_hough_roi_y2_exclusive_px(
+    screen_h: int,
+    scale_w: float,
+) -> int:
+    """会话列表头像 Hough ROI 的 **不包含**的最小 y。
+
+    ``y`` 区间为 ``[roi_y1, roi_y2)``；返回值取「legacy 占位底」与「底栏上沿再减净空」
+    **更靠上（更小）者**，从而在蓝框同款 X 带内不包含底栏「微信」Dock 图标圆。
+    """
+    sw = max(float(scale_w), 1e-6)
+    sh = int(screen_h)
+    legacy_exclusive = sh - int(
+        round(float(CONVERSATION_LIST_AVATAR_HOUGH_ROI_NAV_FALLBACK_GAP_FROM_BOTTOM_BASELINE) * sw),
+    )
+    nav_top_exclusive = sh - int(
+        round(float(_WECHAT_MAIN_NAV_TAB_BAND_TOP_OFFSET_FROM_BOTTOM_BASELINE) * sw),
+    )
+    clearance = int(round(float(LIST_AVATAR_HOUGH_CLEAR_ABOVE_NAV_BAND_TOP_BASELINE) * sw))
+    cap_from_nav_icons = nav_top_exclusive - clearance
+    return min(legacy_exclusive, cap_from_nav_icons)
+
+
+#: Empirical distance from the bottom of the "微信" title glyph block to
+#: the TOP of the first conversation row's avatar badge area, at
+#: 1080-baseline scale. Calibrated on edb1a89f 8.0.69 across r5~r8
+#: screencaps with varying bounce states:
+#:
+#: - r5/r6/r7/r8 title bottom_y = 176~177 (stable, glyphs anchored to chrome)
+#: - r8 row-0 badge bbox y = 247 (measured by detect_unread_badges tool)
+#: - offset = 247 − 177 = 70 → we take **61** with 9 px headroom so
+#:   bounce-up states (content temporarily shifted ~8 px higher than the
+#:   bounce-down resting position) still anchor row 0 above its badge.
+#:
+#: Choosing the floor of the observed range is safer than the mean
+#: because it only expands row 0 upward by a few px into harmless
+#: whitespace (search-bar divider region, no red elements), while a
+#: larger offset would cause row 0 to MISS the badge entirely as seen
+#: in the pre-Day-6 value 103 (=280 baseline − 177 title).
+WECHAT_TITLE_TO_FIRST_ROW_OFFSET_BASELINE = 61
+
+#: PRD 「list_row_y12_gap_abs_px」：极差 ``max−mingap`` **缩放前的**基线最大值（baseline px）。
+#: 缩放规则：阈值 = 本基数 × ``screen_height / LIST_ROW_SCREEN_HEIGHT_CALIBRATION_Y12_BASELINE``。
+WX_COLLECTOR_LIST_ROW_Y12_GAP_SPREAD_MAX_BASELINE_ENV = (
+    "WX_COLLECTOR_LIST_ROW_Y12_GAP_SPREAD_MAX_BASELINE"
+)
+
+
+def resolve_list_row_y12_gap_spread_max_baseline_px(
+    *,
+    baseline_px: Optional[float] = None,
+) -> float:
+    """解析 PRD §4 极差上限基线数值（缩放前）。
+
+    ``baseline_px`` 显式为非 ``None`` 时直接 ``max(0, float(..))``；否则读环境变量
+    :data:`WX_COLLECTOR_LIST_ROW_Y12_GAP_SPREAD_MAX_BASELINE_ENV`；非法／缺省退回
+    :data:`LIST_ROW_GEOMETRY_Y12_GAP_SPREAD_MAX_BASELINE`。
+    """
+    if baseline_px is not None:
+        return max(0.0, float(baseline_px))
+    raw = os.environ.get(WX_COLLECTOR_LIST_ROW_Y12_GAP_SPREAD_MAX_BASELINE_ENV, "").strip()
+    if raw:
+        try:
+            return max(0.0, float(raw))
+        except ValueError:
+            pass
+    return float(LIST_ROW_GEOMETRY_Y12_GAP_SPREAD_MAX_BASELINE)
+
+
+AvatarCentroidSplitStatus = Literal[
+    "ok",
+    "insufficient_avatar_geometry",
+    "prd_y12_gap_spread_over_limit",
+    "prd_y12_insufficient_centroids",
+    "prd_y12_calibration_subset_too_short",
+    "prd_y12_no_inter_gap_on_subset",
+]
+
+
+def conversation_list_avatar_prd_y12_row_pitch_calibration(
+    cy_full_ordered: Sequence[int],
+    *,
+    scale_w: float,
+    screen_h: int,
+    list_row_y12_gap_spread_abs_baseline_px: Optional[float] = None,
+    screen_height_calibration_baseline_px: Optional[float] = None,
+) -> tuple[Optional[int], AvatarCentroidSplitStatus, Optional[float], dict[str, object]]:
+    """PRD §4：校准段极差门控；``high = mean(gap)``，半行宽 ``high/2``（再夹到 scale 窗）。"""
+    sw = max(float(scale_w), 1e-6)
+    mids = sorted(int(y) for y in cy_full_ordered)
+    n = len(mids)
+    spread_bas = resolve_list_row_y12_gap_spread_max_baseline_px(
+        baseline_px=list_row_y12_gap_spread_abs_baseline_px,
+    )
+    cal_bh = float(
+        LIST_ROW_SCREEN_HEIGHT_CALIBRATION_Y12_BASELINE
+        if screen_height_calibration_baseline_px is None
+        else screen_height_calibration_baseline_px,
+    )
+    thresh_px = spread_bas * float(screen_h) / max(cal_bh, 1e-6)
+
+    diagnostics: dict[str, object] = {
+        "n_detected_avatar_centroids": int(n),
+        "mid_y_ordered": tuple(int(x) for x in mids),
+        "spread_threshold_px": float(thresh_px),
+    }
+
+    if n < 5:
+        diagnostics["prd_fail"] = "insufficient_centroids"
+        return None, "prd_y12_insufficient_centroids", None, diagnostics
+
+    subset = mids[1 : n - 2]
+    diagnostics["prd_calibration_subset_mid_y"] = tuple(int(x) for x in subset)
+    if len(subset) < 2:
+        diagnostics["prd_fail"] = "calibration_subset_too_short"
+        return None, "prd_y12_calibration_subset_too_short", None, diagnostics
+
+    gaps_f = [float(subset[k + 1] - subset[k]) for k in range(len(subset) - 1)]
+    diagnostics["prd_calibration_neighbor_gaps"] = tuple(round(g, 4) for g in gaps_f)
+    if len(gaps_f) < 1:
+        diagnostics["prd_fail"] = "no_inter_gap"
+        return None, "prd_y12_no_inter_gap_on_subset", None, diagnostics
+
+    # 置顶区/折叠群等会在相邻 centroid 间产生「段落级」大间距（真机 edb1a89f
+    # 常见 ~2× 行距）；极差门控应基于 **典型行距** 子集，勿把段落缝当行高漂移。
+    sorted_g = sorted(gaps_f)
+    med_gap = sorted_g[len(sorted_g) // 2]
+    if med_gap > 1e-6:
+        lo_typ = med_gap * 0.55
+        hi_typ = med_gap * 1.65
+        gaps_typical = [g for g in gaps_f if lo_typ <= g <= hi_typ]
+    else:
+        gaps_typical = list(gaps_f)
+    if len(gaps_typical) < 2:
+        gaps_typical = list(gaps_f)
+    diagnostics["prd_calibration_gaps_typical"] = tuple(
+        round(g, 4) for g in gaps_typical
+    )
+
+    gmin = float(min(gaps_typical))
+    gmax = float(max(gaps_typical))
+    spread = gmax - gmin
+    diagnostics["prd_gap_spread_px"] = float(spread)
+
+    avg_high = float(sum(gaps_typical) / float(len(gaps_typical)))
+    diagnostics["prd_avg_row_pitch_px"] = float(avg_high)
+
+    if spread > thresh_px + 1e-5:
+        diagnostics["prd_fail"] = "gap_spread_over_limit"
+        return None, "prd_y12_gap_spread_over_limit", float(spread), diagnostics
+
+    half_raw = avg_high / 2.0
+    half_i = int(round(half_raw))
+    min_h = max(48, int(round(70 * sw)))
+    max_h = int(round(118 * sw))
+    half_px = max(min_h, min(max_h, half_i))
+    diagnostics["prd_row_half_px"] = int(half_px)
+    diagnostics["prd_row_pitch_px_mean"] = float(avg_high)
+    return half_px, "ok", None, diagnostics
+
+
+def estimate_list_row_background_v95(
+    screen_bgr: np.ndarray,
+    group_name_bbox: tuple[int, int, int, int],
+) -> float:
+    """Estimate "list cell background lightness" from the nickname column ROI.
+
+    WeChat main list: pinned rows use a light **grey** cell background; normal
+    rows use **white**. Black text lowers raw means; using the **95th
+    percentile of V** (brightness) in HS**V** approximates background without
+    list-side OCR — dark glyphs stay below the percentile on both themes.
+
+    The ROI already excludes the avatar (see ``CONVERSATION_AVATAR_*`` in the
+    driver). We shrink to the horizontal **left slice** (~55%) and vertical
+    middle 50% to avoid subtitle / timestamp bleed from the preview column.
+
+    Returns:
+        A Value in ``[0, 255]`` — lower values suggest pinned grey; white rows
+        are typically **253–255**.
+    """
+    x1, y1, x2, y2 = group_name_bbox
+    h_full, w_full = screen_bgr.shape[:2]
+    x1 = max(0, min(w_full - 1, x1))
+    x2 = max(x1 + 1, min(w_full, x2))
+    y1 = max(0, min(h_full - 1, y1))
+    y2 = max(y1 + 1, min(h_full, y2))
+    w = x2 - x1
+    h = y2 - y1
+    if w < 12 or h < 12:
+        return 255.0
+
+    # Focus on nickname band (avoid top/bottom text baselines extremes).
+    ix1 = x1 + max(4, int(w * 0.02))
+    ix2 = x1 + int(w * 0.55)
+    iy1 = y1 + int(h * 0.22)
+    iy2 = y1 + int(h * 0.78)
+    ix2 = max(ix1 + 4, ix2)
+    iy2 = max(iy1 + 4, iy2)
+
+    roi = screen_bgr[iy1:iy2, ix1:ix2]
+    if roi.size == 0:
+        return 255.0
+
+    hsv = cv2.cvtColor(roi, cv2.COLOR_BGR2HSV)
+    flat_v = hsv[:, :, 2].reshape(-1).astype(np.float32)
+    return float(np.percentile(flat_v, 95))
+
+
+#: If ``estimate_list_row_background_v95(...)`` falls **below** this
+#: threshold (on the 95th percentile of V), the row is classified as pinned
+#: (grey list cell). Tune with real devices if ROM themes shift; daylight
+#: pinned rows observed ~236–246 vs white rows ~253–255.
+PINNED_BACKGROUND_V95_MAX = 251
+
+
+def list_row_is_pinned_grey_background(
+    screen_bgr: np.ndarray,
+    group_name_bbox: tuple[int, int, int, int],
+    *,
+    pinned_v95_max: float = PINNED_BACKGROUND_V95_MAX,
+) -> bool:
+    """Whether the conversation row **looks like** WeChat pinned (grey cell).
+
+    This is heuristic — dark mode / custom skins may drift; pair with unread
+    HSV badges and post-enter :class:`PrePositionedChatDriver` checks."""
+    v95 = estimate_list_row_background_v95(screen_bgr, group_name_bbox)
+    return bool(v95 < pinned_v95_max)
+
+
+def detect_wechat_main_title_bottom_y(
+    screen_bgr: np.ndarray, scale_w: float,
+) -> Optional[int]:
+    """Locate the bottom y (raw-pixel space) of the "微信" title on the
+    WeChat main conversation list.
+
+    Strategy (no PaddleOCR, per rules.md §12 collector dependency
+    isolation): in the top nav band ``y ∈ [100, 220] × scale_w`` and
+    horizontal mid-band ``x ∈ [center ± 180 × scale_w]``, find the densest
+    horizontal strip of dark (V<80) pixels. The ``微信`` glyph and its
+    ``(N)`` unread-count sibling form a bold, compact dark cluster; tab
+    icons / status-bar icons either fall outside the mid-band (they hug
+    the screen edges) or produce fewer dark pixels per row.
+
+    Returns:
+        Raw y of the title block's bottom edge, suitable for
+        :func:`split_conversation_rows`'s ``first_row_top_baseline``
+        anchor (add :data:`WECHAT_TITLE_TO_FIRST_ROW_OFFSET_BASELINE`).
+        ``None`` when the title signal is too weak — callers fall back
+        to :data:`CONVERSATION_FIRST_ROW_TOP_BASELINE`.
+    """
+    h, w = screen_bgr.shape[:2]
+    y1 = int(round(100 * scale_w))
+    y2 = int(round(220 * scale_w))
+    if y2 > h:
+        return None
+    band_half_w = int(round(180 * scale_w))
+    cx = w // 2
+    x1 = max(0, cx - band_half_w)
+    x2 = min(w, cx + band_half_w)
+    if x2 - x1 < 40:
+        return None
+
+    band = screen_bgr[y1:y2, x1:x2]
+    gray = cv2.cvtColor(band, cv2.COLOR_BGR2GRAY)
+    _, mask = cv2.threshold(gray, 80, 255, cv2.THRESH_BINARY_INV)
+    # Count dark pixels per row; title rows should have ≥ 8 dark pixels
+    # (two fat glyph columns at least).
+    row_dark = (mask.sum(axis=1) // 255).astype(np.int32)
+    has_title_row = row_dark > 8
+    if not has_title_row.any():
+        return None
+    last_title_row = int(np.where(has_title_row)[0].max())
+    return y1 + last_title_row
+
+
+#: 底栏 **选中** Tab 的品牌绿（与 ``driver._manual_labeling_step1_hold_to_talk_green_hint``
+#: 同阈），在 N=4 真机截图（微信/通讯录/发现/我 各选中的一帧）上校准：未选栏占比 ≈0，
+#: 选中栏约 0.06–0.10。
+_WECHAT_BOTTOM_TAB_SELECTED_GREEN_HSV_LOW = (36, 55, 45)
+_WECHAT_BOTTOM_TAB_SELECTED_GREEN_HSV_HIGH = (92, 255, 255)
+
+
+def _wechat_bottom_nav_band_roi(
+    screen_bgr: np.ndarray, scale_w: float,
+) -> Optional[np.ndarray]:
+    """Bottom nav band shared by tab-bar heuristics (152×scale_w strip)."""
+    h, _w = screen_bgr.shape[:2]
+    sw = max(scale_w, 1e-6)
+    y0 = max(0, h - int(round(152 * sw)))
+    y1 = h - int(round(6 * sw))
+    if y1 <= y0 + 8:
+        return None
+    return screen_bgr[y0:y1, :]
+
+
+def _wechat_bottom_tab_quarter_ink_fracs(roi: np.ndarray) -> Optional[list[float]]:
+    """Per-quarter ink share = max(dark glyph, brand-green selected tab).
+
+    Selected tab icons/labels are brand-green and often **miss** the dark-pixel
+    threshold — without the green channel, ``detect_wechat_main_bottom_tab_bar_four_columns``
+    false-negatives on the main session list (BUG-1 reposition).
+    """
+    _h, w = roi.shape[:2]
+    quarter = w // 4
+    if quarter < 40:
+        return None
+    gray = cv2.cvtColor(roi, cv2.COLOR_BGR2GRAY)
+    _, dark_mask = cv2.threshold(gray, 105, 255, cv2.THRESH_BINARY_INV)
+    hsv = cv2.cvtColor(roi, cv2.COLOR_BGR2HSV)
+    green_mask = cv2.inRange(
+        hsv,
+        np.array(_WECHAT_BOTTOM_TAB_SELECTED_GREEN_HSV_LOW, dtype=np.uint8),
+        np.array(_WECHAT_BOTTOM_TAB_SELECTED_GREEN_HSV_HIGH, dtype=np.uint8),
+    )
+    fracs: list[float] = []
+    for qi in range(4):
+        x0c = qi * quarter
+        x1c = (qi + 1) * quarter if qi < 3 else w
+        dark_col = dark_mask[:, x0c:x1c]
+        green_col = green_mask[:, x0c:x1c]
+        dark_frac = float(cv2.countNonZero(dark_col)) / float(dark_col.size)
+        green_frac = float(cv2.countNonZero(green_col)) / float(green_col.size)
+        fracs.append(max(dark_frac, green_frac))
+    return fracs
+
+
+def detect_wechat_main_bottom_tab_bar_four_columns(
+    screen_bgr: np.ndarray, scale_w: float,
+) -> bool:
+    """Heuristic: 主界面底栏「微信 / 通讯录 / 发现 / 我」四等分上均有笔墨。
+
+    manual_labeling / 列表扫描：与 :func:`detect_wechat_main_title_bottom_y`
+    联用可区分「主会话列表」与「仅顶部像标题的群聊」等误判。
+
+    Strategy (no OCR): bottom nav band, per-quarter ink = max(dark glyph,
+    brand-green selected tab); require every quarter to have a minimum ink
+    share and roughly comparable density (tabs are four siblings).
+
+    Dark mode / 极端主题可能漂移 —— 与顶栏启发式同级，需真机矩阵复核。
+    """
+    roi = _wechat_bottom_nav_band_roi(screen_bgr, scale_w)
+    if roi is None:
+        return False
+    fracs = _wechat_bottom_tab_quarter_ink_fracs(roi)
+    if fracs is None:
+        return False
+    fmin, fmax = min(fracs), max(fracs)
+    if fmin < 0.0018 or fmax > 0.42:
+        return False
+    if fmax <= 1e-9:
+        return False
+    # Weaker tab may be 「我」单层笔画；最强一般为「通讯录」—— 拒绝单点极强、其余近空
+    if fmin < fmax * 0.20:
+        return False
+    return True
+
+
+def detect_wechat_bottom_tab_selected_green_index(
+    screen_bgr: np.ndarray,
+    scale_w: float,
+    *,
+    min_winner_frac: float = 0.032,
+    min_lead_ratio: float = 1.5,
+    ambiguous_runner_frac: float = 0.014,
+) -> Optional[int]:
+    """Infer which bottom nav tab is **selected** (brand-green icon+label).
+
+    WeChat paints the active tab in #07C160-class green; unselected tabs stay
+    neutral grey outlines. 底栏几何与
+    :func:`detect_wechat_main_bottom_tab_bar_four_columns` 一致：整宽四等分。
+
+    Returns:
+        ``0`` 微信, ``1`` 通讯录, ``2`` 发现, ``3`` 我；无法明确判定时 ``None``
+        （例如暗色主题、强压缩截图、或无明显绿区）——调用方应降级为其它特征。
+
+    Calibration: four full-screen captures with each tabselected; at
+    ``1080``-wide baseline the winning quadrant green-pixel share was
+    ~0.058–0.10 and all others ~0.0 with the HSV band above.
+    """
+    roi = _wechat_bottom_nav_band_roi(screen_bgr, scale_w)
+    if roi is None:
+        return None
+    _h, w = roi.shape[:2]
+    hsv = cv2.cvtColor(roi, cv2.COLOR_BGR2HSV)
+    mask = cv2.inRange(
+        hsv,
+        np.array(_WECHAT_BOTTOM_TAB_SELECTED_GREEN_HSV_LOW, dtype=np.uint8),
+        np.array(_WECHAT_BOTTOM_TAB_SELECTED_GREEN_HSV_HIGH, dtype=np.uint8),
+    )
+    quarter = w // 4
+    if quarter < 40:
+        return None
+    fracs: list[float] = []
+    for qi in range(4):
+        x0c = qi * quarter
+        x1c = (qi + 1) * quarter if qi < 3 else w
+        col = mask[:, x0c:x1c]
+        fracs.append(float(cv2.countNonZero(col)) / float(col.size))
+    winner_i = int(np.argmax(fracs))
+    winner = fracs[winner_i]
+    if winner < float(min_winner_frac):
+        return None
+    others = sorted((fracs[j] for j in range(4) if j != winner_i), reverse=True)
+    runner = float(others[0]) if others else 0.0
+    if (
+        runner > float(ambiguous_runner_frac)
+        and winner < runner * float(min_lead_ratio)
+    ):
+        return None
+    return winner_i
+
+
+def conversation_list_visible_pinned_row_count(
+    screen_bgr: np.ndarray,
+    scale_w: float,
+    *,
+    title_bottom_y_raw_px: Optional[int],
+    pinned_v95_max: float = PINNED_BACKGROUND_V95_MAX,
+    max_rows_scan: int = 14,
+) -> int:
+    """当前屏会话列表中带 **置顶灰底** 会话行的可见数量估算。
+
+    ROI 与同文件 :func:`list_row_is_pinned_grey_background`、群扫
+    :meth:`collector.driver.TopGroupScanDriver.scan_pinned_groups`
+    —— 仅用昵称列背景的 V95 分位区分灰底置顶 vs 白底普行，
+    **不读 OCR**。行带划分与 Driver 对齐：能用 ``微信`` 标题底边锚时
+    优先，否则退回 :data:`CONVERSATION_FIRST_ROW_TOP_BASELINE`。
+
+    Args:
+        title_bottom_y_raw_px: :func:`detect_wechat_main_title_bottom_y`
+            的像素 ``y``；``None`` 时走兜底基线。
+    """
+    h, w_full = screen_bgr.shape[:2]
+    sw = max(scale_w, 1e-6)
+    avatar_right_edge = int(round(CONVERSATION_AVATAR_RIGHT_EDGE_BASELINE * sw))
+    right_reserved = int(round(CONVERSATION_RIGHT_SIDE_RESERVED_BASELINE * sw))
+
+    if title_bottom_y_raw_px is not None and detect_wechat_main_bottom_tab_bar_four_columns(
+            screen_bgr, scale_w,
+    ):
+        first_row_top_bt = int(round(
+            title_bottom_y_raw_px / sw
+            + WECHAT_TITLE_TO_FIRST_ROW_OFFSET_BASELINE,
+        ))
+        row_rects, _split_mode, _gap = conversation_list_row_rects(
+            screen_bgr,
+            scale_w,
+            screen_h=h,
+            list_first_row_top_baseline=first_row_top_bt,
+            strict_pitch_calibration_reject=False,
+        )
+    else:
+        row_rects, _split_mode, _gap = conversation_list_row_rects(
+            screen_bgr,
+            scale_w,
+            screen_h=h,
+            list_first_row_top_baseline=CONVERSATION_FIRST_ROW_TOP_BASELINE,
+            strict_pitch_calibration_reject=False,
+        )
+
+    n_pinned = 0
+    for y1, y2 in row_rects[: max(1, max_rows_scan)]:
+        name_bbox = (
+            min(w_full, avatar_right_edge),
+            y1,
+            max(0, w_full - right_reserved),
+            y2,
+        )
+        if list_row_is_pinned_grey_background(
+                screen_bgr, name_bbox, pinned_v95_max=pinned_v95_max,
+        ):
+            n_pinned += 1
+    return n_pinned
+
+
+def is_wechat_main_conversation_list_chrome(
+    screen_bgr: np.ndarray,
+    scale_w: float,
+    *,
+    require_visible_pinned_row: bool = True,
+    pinned_v95_max: Optional[float] = None,
+) -> bool:
+    """主界面 **微信 Tab 下的会话列表**（含本条业务约定时能识别出的置顶灰行）。
+
+    顶区标题带 + 底栏四 Tab 墨色均衡；若可读到底栏 **品牌绿选中态**，
+    则必须为第 1 栏（微信）；绿区不可信（``None``）时不凭绿否决。
+
+    ``require_visible_pinned_row=True``（默认）时还要求
+    :func:`conversation_list_visible_pinned_row_count` 返回值 ``>= 1``。
+    采集 Runner 一般由
+    ``collector.driver.session_list_chrome_require_visible_pinned_row()`` 读出
+    **``WX_COLLECTOR_SESSION_LIST_REQUIRE_PINNED_ROW``**（缺省等价开启）传入本参数；
+    设 ``0|false|no|off`` 可跳过灰置顶行约束（无置顶检测设备 / 暗色主题调参）。
+    """
+    tb = detect_wechat_main_title_bottom_y(screen_bgr, scale_w)
+    if tb is None:
+        return False
+    if not detect_wechat_main_bottom_tab_bar_four_columns(screen_bgr, scale_w):
+        return False
+    sel = detect_wechat_bottom_tab_selected_green_index(screen_bgr, scale_w)
+    if sel is not None and sel != 0:
+        return False
+    pv = (
+        PINNED_BACKGROUND_V95_MAX
+        if pinned_v95_max is None
+        else float(pinned_v95_max)
+    )
+    if require_visible_pinned_row:
+        n_pin = conversation_list_visible_pinned_row_count(
+            screen_bgr,
+            scale_w,
+            title_bottom_y_raw_px=tb,
+            pinned_v95_max=pv,
+        )
+        if n_pin < 1:
+            return False
+    return True
+
+
+def reposition_anchor_bottom_wechat_tap_lane_plausible(
+    screen_bgr: np.ndarray,
+    scale_w: float,
+    *,
+    tab_x: int,
+    tab_y: int,
+) -> bool:
+    """与 ``driver._session_list_tab_coords`` 即将点击的 **同一点** 邻域，判断底栏是否像「可点的微信条」。
+
+    归位链 **从不** 对底栏做字形/OCR 识别，仅用几何坐标点 ``(tab_x, tab_y)``；
+    早停与此对齐：在 ``tab_x±~90×scale_w``、``tab_y`` 上方约 ``44×scale_w`` 至下方
+    ``24×scale_w`` 的矩形内看灰度方差 + Canny 边密度（主列表四 Tab 与「最近」单胶囊
+    左沿均在相近横坐标落点）。
+    """
+    h, w = screen_bgr.shape[:2]
+    sw = max(scale_w, 1e-6)
+    half_w = int(round(90 * sw))
+    x1 = max(0, int(tab_x) - half_w)
+    x2 = min(w, int(tab_x) + half_w)
+    y1 = max(0, int(tab_y) - int(round(44 * sw)))
+    y2 = min(h, int(tab_y) + int(round(24 * sw)))
+    if x2 <= x1 + 8 or y2 <= y1 + 4:
+        return False
+    roi = screen_bgr[y1:y2, x1:x2]
+    gray = cv2.cvtColor(roi, cv2.COLOR_BGR2GRAY)
+    if float(np.std(gray)) < 4.5:
+        return False
+    edges = cv2.Canny(gray, 50, 150)
+    ef = float(cv2.countNonZero(edges)) / float(edges.size)
+    if ef < 0.012 or ef > 0.55:
+        return False
+    return True
+
+
+def _longest_true_run(mask: np.ndarray) -> int:
+    """最大连续 True 块的行数。"""
+    if not mask.any():
+        return 0
+    padded = np.concatenate(([False], mask, [False]))
+    edges = np.where(padded[:-1] != padded[1:])[0]
+    if len(edges) == 0:
+        return 0
+    runs = edges[1::2] - edges[::2]
+    return int(runs.max())
+
+
+def _recent_pull_top_heading_likely(
+    screen_bgr: np.ndarray,
+    scale_w: float,
+) -> bool:
+    """顶区「最近」类标题：亮底深字 **或** 暗底浅字，竖向窄中带。"""
+    h, w = screen_bgr.shape[:2]
+    sw = max(scale_w, 1e-6)
+    y1 = int(round(222 * sw))
+    y2 = int(round(540 * sw))
+    y2 = min(y2, int(0.36 * h))
+    if y2 <= y1 + 24 or y1 >= h:
+        return False
+    cx = w // 2
+    band_half_w = int(round(140 * sw))
+    x1 = max(0, cx - band_half_w)
+    x2 = min(w, cx + band_half_w)
+    if x2 - x1 < 36:
+        return False
+
+    band = screen_bgr[y1:y2, x1:x2]
+    gray = cv2.cvtColor(band, cv2.COLOR_BGR2GRAY)
+    area = float(max(band.shape[0] * band.shape[1], 1))
+
+    _, mask_dark = cv2.threshold(gray, 80, 255, cv2.THRESH_BINARY_INV)
+    ink_d = float(cv2.countNonZero(mask_dark)) / area
+    if 0.014 <= ink_d <= 0.48:
+        row_dark = (mask_dark.sum(axis=1) // 255).astype(np.int32)
+        has_row = row_dark > 9
+        if has_row.any():
+            # 最大连续块跨度：低分辨率下散点不会拉长 span（2026-06-13）
+            block_span = _longest_true_run(has_row)
+            if block_span <= int(round(70 * sw)):
+                return True
+
+    light = (gray > 96).astype(np.uint8)
+    ink_l = float(np.sum(light)) / area
+    if 0.006 <= ink_l <= 0.32:
+        row_lit = light.sum(axis=1).astype(np.int32)
+        has_row = row_lit > 5
+        if has_row.any():
+            block_span = _longest_true_run(has_row)
+            if block_span <= int(round(72 * sw)):
+                return True
+    return False
+
+
+def is_wechat_recent_pull_anchor_early_stop_frame(
+    screen_bgr: np.ndarray,
+    scale_w: float,
+    *,
+    tab_x: int,
+    tab_y: int,
+) -> bool:
+    """§步骤1(2) 早停：顶区「最近」类标题 **且** 与点击同标的底栏邻域 ``(tab_x,tab_y)`` 可点条带。
+
+    底栏侧与归位 ``adb.tap(tab_x, tab_y)`` 共用 :func:`reposition_anchor_bottom_wechat_tap_lane_plausible`，
+    **不**再单独用四 Tab / 胶囊中区视检。"""
+    if not reposition_anchor_bottom_wechat_tap_lane_plausible(
+            screen_bgr, scale_w, tab_x=tab_x, tab_y=tab_y,
+    ):
+        return False
+    return _recent_pull_top_heading_likely(screen_bgr, scale_w)
+
+
+def split_conversation_rows(
+    screen_h: int,
+    scale_w: float,
+    *,
+    row_height_baseline: int = CONVERSATION_ROW_HEIGHT_BASELINE,
+    first_row_top_baseline: int = CONVERSATION_FIRST_ROW_TOP_BASELINE,
+    bottom_nav_height_baseline: int = 160,
+) -> list[tuple[int, int]]:
+    """Heuristic row splitter for the WeChat main conversation list.
+
+    Returns a list of ``(y_top, y_bottom)`` tuples covering the expected
+    conversation rows between the search bar and the bottom nav (weixin /
+    通讯录 / 发现 / 我 tab strip). Deliberately coarse — subpixel accuracy
+    is not needed because badges are detected by HSV in the avatar ROI; the
+    row boundary is only used to attribute "which row carries an unread
+    badge" for ordering.
+
+    Args:
+        screen_h: raw screen height in pixels.
+        scale_w: ``device_width / 1080``.
+        row_height_baseline: per-row height at baseline (default 178px).
+        first_row_top_baseline: y-coordinate where row 0 starts at baseline
+            (default 280px).
+        bottom_nav_height_baseline: reserved pixels below the last row for
+            WeChat's bottom tab bar (default 160px).
+    """
+    row_height = int(round(row_height_baseline * scale_w))
+    first_top = int(round(first_row_top_baseline * scale_w))
+    nav_reserve = int(round(bottom_nav_height_baseline * scale_w))
+
+    if row_height <= 0:
+        return []
+
+    rows: list[tuple[int, int]] = []
+    y = first_top
+    visible_bottom = screen_h - nav_reserve
+    while y + row_height <= visible_bottom:
+        rows.append((y, y + row_height))
+        y += row_height
+    return rows
+
+
+def split_conversation_rows_by_avatar_centroids(
+    screen_bgr: np.ndarray,
+    scale_w: float,
+    *,
+    screen_h: int,
+    list_first_row_top_px: int,
+    min_rows: int = 4,
+    half_extend_baseline: Optional[int] = None,
+    list_row_y12_gap_spread_abs_baseline_px: Optional[float] = None,
+    list_row_screen_height_calibration_baseline_px: Optional[float] = None,
+) -> tuple[
+    Optional[list[tuple[int, int]]],
+    AvatarCentroidSplitStatus,
+    Optional[float],
+]:
+    """Derive list row bands from left-column avatar centroids.
+
+    After Hough detection + x-median + y-NMS we obtain a **top-to-bottom** list
+    of avatar centre ``cy`` values. Row **半高**遵循 PRD
+    ``product_requirement_document.md`` §4：取第 **2～(n−2)** 个头像 ``mid_y`` 的
+    相邻间距，极差 ``max(gap)−min(gap)`` 不得超过
+    :func:`resolve_list_row_y12_gap_spread_max_baseline_px` 按屏高校准后的阈值；
+    通过后 ``high = mean(gap)``，行带 ``mid_y ± high/2``（再按比例窗钳制）。
+
+    门控失败返回 ``prd_y12_*``；Hough/sparse/stack 不满足 ``min_rows`` 等仍返回
+    ``insufficient_avatar_geometry``。
+
+    ``half_extend_baseline`` 暂无用途，仅为旧调用兼容保留。
+
+    Other UIs (e.g. in-group member pickers) must only call when the left
+    column matches the same stacked-avatar layout.
+
+    Bottom strip: centroid Hough **never scans** pixels at/under the Dock
+    “微信／通讯录／…” 墨色带上沿（与同文件 ``detect_wechat_main_bottom_tab_bar_four_columns``
+    的 ``152×scale_w`` 底边锚一致），再上移净空，避免左侧第一个 Tab 矢量圆误判为会话头像。
+    Horizontal ROI remains ``CONVERSATION_LIST_AVATAR_ROI_*``.
+
+    First and last row bands may clip at the **top/bottom list edge** with only
+    about **half the visible strip height** (see
+    ``CONVERSATION_LIST_AVATAR_ROW_MIN_VISIBLE_HEIGHT_*``); interior rows stay
+    on the full threshold.
+    """
+
+    sw = max(float(scale_w), 1e-6)
+    h_full, w_full = screen_bgr.shape[:2]
+    slack_top = int(round(22 * sw))
+    roi_y1 = max(0, int(list_first_row_top_px) - slack_top)
+    roi_y2_excl_pt = conversation_list_avatar_hough_roi_y2_exclusive_px(int(screen_h), sw)
+    roi_y2 = max(roi_y1 + 8, roi_y2_excl_pt)
+    x1_roi = max(0, int(round(CONVERSATION_LIST_AVATAR_ROI_LEFT_BASELINE * sw)))
+    x2_roi = min(w_full, int(round(CONVERSATION_LIST_AVATAR_ROI_RIGHT_BASELINE * sw)))
+    ins = "insufficient_avatar_geometry"
+    if roi_y2 <= roi_y1 + 40 or x2_roi <= x1_roi + 24:
+        return None, ins, None
+
+    crop = screen_bgr[roi_y1:roi_y2, x1_roi:x2_roi]
+    gray = cv2.cvtColor(crop, cv2.COLOR_BGR2GRAY)
+    gray_blur = cv2.GaussianBlur(gray, (5, 5), 0)
+    circles = cv2.HoughCircles(
+        gray_blur,
+        cv2.HOUGH_GRADIENT,
+        dp=1.25,
+        minDist=int(round(117 * sw)),
+        param1=100,
+        param2=22,
+        minRadius=max(34, int(round(36 * sw))),
+        maxRadius=int(round(80 * sw)),
+    )
+    if circles is None:
+        return None, ins, None
+
+    cand: list[tuple[float, float, float]] = []
+    for xi, yi, ri in circles[0]:
+        cand.append((float(ri), float(xi), float(yi)))
+    if not cand:
+        return None, ins, None
+
+    xs_crop = [c[1] for c in cand]
+    median_x = float(np.median(np.array(xs_crop, dtype=np.float64)))
+    xt = int(round(float(CONVERSATION_LIST_AVATAR_MEDIAN_X_HALF_WIDTH_BASELINE) * sw))
+    filt = [c for c in cand if abs(c[1] - median_x) <= xt]
+
+    roi_h = max(0, int(roi_y2) - int(roi_y1))
+    foot = int(round(float(LIST_AVATAR_HOUGH_MAX_CROP_Y_FROM_ROI_BOTTOM_BASELINE) * sw))
+    if roi_h > foot + 24:
+        filt = [c for c in filt if float(c[2]) <= float(roi_h - foot)]
+
+    if len(filt) < min_rows:
+        return None, ins, None
+
+    filt.sort(key=lambda t: t[2])
+    ymin_gap = round(118 * sw)
+    same_icon_dy_max = float(LIST_AVATAR_STACK_SAME_ICON_MAX_CENTER_DY_BASELINE) * sw
+    stacked: list[tuple[float, float, float]] = []
+
+    for r, xc, yc in filt:
+        if not stacked:
+            stacked.append((r, xc, yc))
+            continue
+        pr, _px, py_prev = stacked[-1]
+        dy = float(yc) - float(py_prev)
+        if dy < ymin_gap:
+            # 极小 Δy：同一头像多圆；居中区间：(same_icon_dy_max, ymin_gap)：仍算相邻两行会话。
+            if dy <= same_icon_dy_max:
+                if r > pr:
+                    stacked[-1] = (r, xc, yc)
+            else:
+                stacked.append((r, xc, yc))
+        else:
+            stacked.append((r, xc, yc))
+
+    if len(stacked) < min_rows:
+        return None, ins, None
+
+    cy_full_ordered: list[int] = [
+        roi_y1 + int(round(yc)) for _r, _xc, yc in stacked
+    ]
+
+    half_px_cal, prd_st, prd_gap_spread, _prd_diag = (
+        conversation_list_avatar_prd_y12_row_pitch_calibration(
+            cy_full_ordered,
+            scale_w=sw,
+            screen_h=int(screen_h),
+            list_row_y12_gap_spread_abs_baseline_px=list_row_y12_gap_spread_abs_baseline_px,
+            screen_height_calibration_baseline_px=(
+                list_row_screen_height_calibration_baseline_px
+            ),
+        )
+    )
+    if half_px_cal is None:
+        return None, prd_st, prd_gap_spread
+
+    half_px = int(half_px_cal)
+
+    min_mid = int(round(float(CONVERSATION_LIST_AVATAR_ROW_MIN_VISIBLE_HEIGHT_AFTER_CLIP_BASELINE) * sw))
+    edge_frac = float(CONVERSATION_LIST_AVATAR_ROW_MIN_VISIBLE_HEIGHT_EDGE_FRAC)
+    min_edge = max(1, int(round(float(min_mid) * edge_frac)))
+
+    n_cy = len(cy_full_ordered)
+    out: list[tuple[int, int]] = []
+    for idx, cy_full in enumerate(cy_full_ordered):
+        top = cy_full - half_px
+        bot = cy_full + half_px
+        top = max(0, top)
+        bot = min(int(screen_h), bot)
+        need_h = min_edge if (idx == 0 or idx == n_cy - 1) else min_mid
+        if bot - top < need_h:
+            continue
+        out.append((top, bot))
+
+    if len(out) < min_rows:
+        return None, ins, None
+
+    out.sort(key=lambda z: z[0])
+    return out, "ok", None
+
+
+def conversation_list_avatar_roundrect_centroid_mid_y_ordered(
+    screen_bgr: np.ndarray,
+    scale_w: float,
+    *,
+    screen_h: int,
+    list_first_row_top_px: int,
+    min_rows: int = 4,
+) -> Optional[list[int]]:
+    """圆角方块路径：自上而下整屏头像 **质心 y（px）**，不写行带。"""
+    sw = max(float(scale_w), 1e-6)
+    _, w_full = screen_bgr.shape[:2]
+    slack_top = int(round(22 * sw))
+    roi_y1 = max(0, int(list_first_row_top_px) - slack_top)
+    roi_y2_excl_pt = conversation_list_avatar_hough_roi_y2_exclusive_px(int(screen_h), sw)
+    roi_y2 = max(roi_y1 + 8, roi_y2_excl_pt)
+    x1_roi = max(0, int(round(CONVERSATION_LIST_AVATAR_ROI_LEFT_BASELINE * sw)))
+    x2_roi = min(w_full, int(round(CONVERSATION_LIST_AVATAR_ROI_RIGHT_BASELINE * sw)))
+    if roi_y2 <= roi_y1 + 40 or x2_roi <= x1_roi + 24:
+        return None
+
+    crop_gray = cv2.cvtColor(
+        screen_bgr[roi_y1:roi_y2, x1_roi:x2_roi], cv2.COLOR_BGR2GRAY,
+    )
+    blur = cv2.GaussianBlur(crop_gray, (5, 5), 0)
+    mk_base = float(LIST_AVATAR_ROUNDRECT_MORPH_GRAD_KERNEL_BASELINE)
+    mk = max(3, int(round(mk_base * sw)) | 1)
+    kern_gr = cv2.getStructuringElement(cv2.MORPH_RECT, (mk, mk))
+    grad_u8 = cv2.morphologyEx(blur, cv2.MORPH_GRADIENT, kern_gr)
+    _, bw = cv2.threshold(
+        grad_u8, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU,
+    )
+    ck_base = float(LIST_AVATAR_ROUNDRECT_CLOSE_KERNEL_BASELINE)
+    ck = max(7, int(round(ck_base * sw)) | 1)
+    kern_ck = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (ck, ck))
+    bw = cv2.morphologyEx(bw.astype(np.uint8), cv2.MORPH_CLOSE, kern_ck)
+
+    contours, _hier = cv2.findContours(
+        bw,
+        cv2.RETR_EXTERNAL,
+        cv2.CHAIN_APPROX_SIMPLE,
+    )
+
+    cand: list[tuple[float, float, float]] = []
+    s_min = float(LIST_AVATAR_ROUNDRECT_BBOX_SIDE_MIN_BASELINE) * sw
+    s_max = float(LIST_AVATAR_ROUNDRECT_BBOX_SIDE_MAX_BASELINE) * sw
+    asp_min = float(LIST_AVATAR_ROUNDRECT_MIN_ASPECT)
+    ext_lo = float(LIST_AVATAR_ROUNDRECT_EXTENT_MIN)
+    ext_hi = float(LIST_AVATAR_ROUNDRECT_EXTENT_MAX)
+    sol_min = float(LIST_AVATAR_ROUNDRECT_SOLIDITY_MIN)
+
+    for cnt in contours:
+        _x, _y0, bw_i, bh = cv2.boundingRect(cnt)
+        small = float(min(bw_i, bh))
+        big = float(max(bw_i, bh))
+        if big > s_max * 1.2 or small < s_min * 0.92:
+            continue
+        if small / max(big, 1.0) < asp_min:
+            continue
+        area = float(cv2.contourArea(cnt))
+        hull = cv2.convexHull(cnt)
+        hull_a = float(cv2.contourArea(hull))
+        sol = area / hull_a if hull_a > 1e-6 else 0.0
+        if sol < sol_min:
+            continue
+        bb_a = float(bw_i * bh)
+        if bb_a <= 1e-6:
+            continue
+        extent = area / bb_a
+        if extent < ext_lo or extent > ext_hi:
+            continue
+        M = cv2.moments(cnt)
+        if M["m00"] < 1e-6:
+            continue
+        xc = float(M["m10"] / M["m00"])
+        yc = float(M["m01"] / M["m00"])
+        merit = bb_a * extent * sol
+        cand.append((merit, xc, yc))
+
+    if len(cand) < min_rows:
+        return None
+
+    xs_crop = [c[1] for c in cand]
+    median_x = float(np.median(np.array(xs_crop, dtype=np.float64)))
+    xt = int(round(float(CONVERSATION_LIST_AVATAR_MEDIAN_X_HALF_WIDTH_BASELINE) * sw))
+    filt = [
+        trip for trip in cand
+        if abs(trip[1] - median_x) <= float(xt)
+    ]
+
+    roi_h_calc = max(0, int(roi_y2) - int(roi_y1))
+    foot = int(round(float(LIST_AVATAR_HOUGH_MAX_CROP_Y_FROM_ROI_BOTTOM_BASELINE) * sw))
+    if roi_h_calc > foot + 24:
+        filt = [trip for trip in filt if float(trip[2]) <= float(roi_h_calc - foot)]
+
+    if len(filt) < min_rows:
+        return None
+
+    filt.sort(key=lambda t: t[2])
+
+    ymin_gap = round(118 * sw)
+    same_icon_dy_max = float(LIST_AVATAR_STACK_SAME_ICON_MAX_CENTER_DY_BASELINE) * sw
+    stacked_h: list[tuple[float, float, float]] = []
+
+    for mer, xc, yc in filt:
+        if not stacked_h:
+            stacked_h.append((mer, xc, yc))
+            continue
+        pr_mer, _px, py_prev = stacked_h[-1]
+        dy = float(yc) - float(py_prev)
+        if dy < ymin_gap:
+            if dy <= same_icon_dy_max:
+                if mer > pr_mer:
+                    stacked_h[-1] = (mer, xc, yc)
+            else:
+                stacked_h.append((mer, xc, yc))
+        else:
+            stacked_h.append((mer, xc, yc))
+
+    if len(stacked_h) < min_rows:
+        return None
+
+    return [
+        roi_y1 + int(round(yc)) for _me, _xc, yc in stacked_h
+    ]
+
+
+def prd_wechat_main_list_row_count_by_gap_y12(
+    mid_y_ordered: Sequence[int],
+    *,
+    scale_w: float,
+    screen_h: int,
+    list_row_y12_gap_spread_abs_baseline_px: Optional[float] = None,
+    screen_height_calibration_baseline_px: Optional[float] = None,
+) -> tuple[int, str, dict[str, object]]:
+    """PRD §4/§14：与头像行带校准同一套极差门控 ⇒ 通过则总行数=n，否则 0。"""
+    half_px, status, gap_spread, diagnostics = conversation_list_avatar_prd_y12_row_pitch_calibration(
+        mid_y_ordered,
+        scale_w=scale_w,
+        screen_h=int(screen_h),
+        list_row_y12_gap_spread_abs_baseline_px=list_row_y12_gap_spread_abs_baseline_px,
+        screen_height_calibration_baseline_px=screen_height_calibration_baseline_px,
+    )
+    diag_out = dict(diagnostics)
+    if gap_spread is not None:
+        diag_out.setdefault("prd_observed_gap_spread_px", float(gap_spread))
+    if half_px is None:
+        return 0, str(status), diag_out
+    n = int(diagnostics["n_detected_avatar_centroids"])
+    diag_out.setdefault("prd_row_band_half_px_clamped", int(half_px))
+    return n, "ok", diag_out
+
+
+def prd_wechat_main_list_row_count_gap_y12_from_screen_roundrect(
+    screen_bgr: np.ndarray,
+    scale_w: float,
+    *,
+    screen_h: int,
+    list_first_row_top_px: int,
+    list_row_y12_gap_spread_abs_baseline_px: Optional[float] = None,
+    screen_height_calibration_baseline_px: Optional[float] = None,
+) -> tuple[int, str, dict[str, object]]:
+    """端到端 PRD §14：**圆角方块** centroid + §14 gate。"""
+    cy = conversation_list_avatar_roundrect_centroid_mid_y_ordered(
+        screen_bgr,
+        scale_w,
+        screen_h=screen_h,
+        list_first_row_top_px=list_first_row_top_px,
+    )
+    if cy is None:
+        return (
+            0,
+            "roundrect_centroid_extraction_failed",
+            {
+                "n_detected_avatar_centroids": 0,
+                "mid_y_ordered": tuple(),
+                "spread_threshold_px": float(
+                    float(LIST_ROW_GEOMETRY_Y12_GAP_SPREAD_MAX_BASELINE)
+                    * float(screen_h)
+                    / max(float(LIST_ROW_SCREEN_HEIGHT_CALIBRATION_Y12_BASELINE), 1e-6),
+                ),
+            },
+        )
+    rn, rst, diagnostics = prd_wechat_main_list_row_count_by_gap_y12(
+        cy,
+        scale_w=scale_w,
+        screen_h=screen_h,
+        list_row_y12_gap_spread_abs_baseline_px=list_row_y12_gap_spread_abs_baseline_px,
+        screen_height_calibration_baseline_px=screen_height_calibration_baseline_px,
+    )
+    merged = dict(diagnostics)
+    merged["raw_roundrect_mid_y"] = tuple(int(x) for x in cy)
+    return rn, rst, merged
+
+
+def split_conversation_rows_by_avatar_roundrect_centroids(
+    screen_bgr: np.ndarray,
+    scale_w: float,
+    *,
+    screen_h: int,
+    list_first_row_top_px: int,
+    min_rows: int = 4,
+    half_extend_baseline: Optional[int] = None,
+    list_row_y12_gap_spread_abs_baseline_px: Optional[float] = None,
+    list_row_screen_height_calibration_baseline_px: Optional[float] = None,
+) -> tuple[
+    Optional[list[tuple[int, int]]],
+    AvatarCentroidSplitStatus,
+    Optional[float],
+]:
+    """Derive list row bands by **rounded-square proxies** via morphological gradient contours.
+
+    WeChat list avatars are visually **rounded rects** — this path uses grayscale
+    **MORPH_GRADIENT → OTSU threshold → morphology close**, then selects **near-square**
+    external contours (`solidity`, `extent`, aspect). Centroid ``(xc,yc)`` substitutes
+    for Hough ``(r,xc,yc)`` in the **same median-x / dock foot / vertical stack** ladder
+    as :func:`split_conversation_rows_by_avatar_centroids`, then reuse identical
+    PRD §4 calibration (极差门控 → ``mean(gap)/2`` 半带) on the stacked centroid ``cy`` list.
+
+    Experimental / alternating geometry path; callers may compare counts vs Hough.
+
+    Horizontal ROI stays ``CONVERSATION_LIST_AVATAR_ROI_*``; ROI bottom aligns with Hough via
+    :func:`conversation_list_avatar_hough_roi_y2_exclusive_px`.
+    """
+
+    sw = max(float(scale_w), 1e-6)
+    ins = "insufficient_avatar_geometry"
+    cy_full_ordered = conversation_list_avatar_roundrect_centroid_mid_y_ordered(
+        screen_bgr,
+        scale_w,
+        screen_h=screen_h,
+        list_first_row_top_px=list_first_row_top_px,
+        min_rows=min_rows,
+    )
+    if cy_full_ordered is None:
+        return None, ins, None
+
+    half_px_cal, prd_st, prd_gap_spread, _prd_diag = (
+        conversation_list_avatar_prd_y12_row_pitch_calibration(
+            cy_full_ordered,
+            scale_w=sw,
+            screen_h=int(screen_h),
+            list_row_y12_gap_spread_abs_baseline_px=(
+                list_row_y12_gap_spread_abs_baseline_px
+            ),
+            screen_height_calibration_baseline_px=(
+                list_row_screen_height_calibration_baseline_px
+            ),
+        )
+    )
+    if half_px_cal is None:
+        return None, prd_st, prd_gap_spread
+
+    half_px = int(half_px_cal)
+
+    min_mid = int(round(float(CONVERSATION_LIST_AVATAR_ROW_MIN_VISIBLE_HEIGHT_AFTER_CLIP_BASELINE) * sw))
+    edge_frac = float(CONVERSATION_LIST_AVATAR_ROW_MIN_VISIBLE_HEIGHT_EDGE_FRAC)
+    min_edge = max(1, int(round(float(min_mid) * edge_frac)))
+
+    n_cy = len(cy_full_ordered)
+    out: list[tuple[int, int]] = []
+    for idx, cy_full in enumerate(cy_full_ordered):
+        top = cy_full - half_px
+        bot = cy_full + half_px
+        top = max(0, top)
+        bot = min(int(screen_h), bot)
+        need_h = min_edge if (idx == 0 or idx == n_cy - 1) else min_mid
+        if bot - top < need_h:
+            continue
+        out.append((top, bot))
+
+    if len(out) < min_rows:
+        return None, ins, None
+
+    out.sort(key=lambda z: z[0])
+    return out, "ok", None
+
+
+def _avatar_row_fallback_half_px(
+    sw: float,
+    half_extend_baseline: Optional[int],
+) -> int:
+    """Fixed half-row when fewer than four avatars or invalid X1/X2."""
+
+    half_bb = half_extend_baseline
+    if half_bb is None:
+        half_bb = CONVERSATION_ROW_HEIGHT_BASELINE // 2
+    return max(56, int(round(half_bb * sw)))
+
+
+ListRowRectsMode = Literal[
+    "avatar_centroid",
+    "stripe_heuristic",
+    "list_row_pitch_calibration_reject",
+]
+
+
+def conversation_list_row_rects(
+    screen_bgr: np.ndarray,
+    scale_w: float,
+    *,
+    screen_h: int,
+    list_first_row_top_baseline: int,
+    min_avatar_rows: int = 4,
+    half_extend_baseline: Optional[int] = None,
+    strict_pitch_calibration_reject: bool = True,
+    list_row_y12_gap_spread_abs_baseline_px: Optional[float] = None,
+    list_row_screen_height_calibration_baseline_px: Optional[float] = None,
+) -> tuple[list[tuple[int, int]], ListRowRectsMode, Optional[float]]:
+    """Prefer avatar-derived strips（PRD §4 ``high=mean gap``）；否则退回条纹启发式。
+
+    当极差门控失败且 ``strict_pitch_calibration_reject=True``（API 默认）时返回
+    **空**行列表，模式 ``list_row_pitch_calibration_reject``，附带观测极差（px）。
+    外扫描与 :func:`conversation_list_visible_pinned_row_count` 传入
+    ``strict_pitch_calibration_reject=False``，以便在 centroid 不可靠时降级为
+    :func:`split_conversation_rows` 条纹带。
+
+    ``list_row_y12_gap_spread_abs_baseline_px`` / ``screen_height_calibration_baseline_px``
+    显式覆盖 PRD 基线与屏高校准分母；``None`` 时走环境与模块默认。
+    """
+
+    sw = max(float(scale_w), 1e-6)
+
+    rows_out, st, gap_px = split_conversation_rows_by_avatar_centroids(
+        screen_bgr,
+        scale_w,
+        screen_h=screen_h,
+        list_first_row_top_px=int(round(list_first_row_top_baseline * sw)),
+        min_rows=min_avatar_rows,
+        half_extend_baseline=half_extend_baseline,
+        list_row_y12_gap_spread_abs_baseline_px=list_row_y12_gap_spread_abs_baseline_px,
+        list_row_screen_height_calibration_baseline_px=(
+            list_row_screen_height_calibration_baseline_px
+        ),
+    )
+    if st == "prd_y12_gap_spread_over_limit" and strict_pitch_calibration_reject:
+        return [], "list_row_pitch_calibration_reject", gap_px
+    if st == "ok" and rows_out is not None:
+        return rows_out, "avatar_centroid", None
+
+    rows = split_conversation_rows(
+        screen_h,
+        scale_w,
+        first_row_top_baseline=list_first_row_top_baseline,
+    )
+    return rows, "stripe_heuristic", None
+
+
+__all__ = [
+    "TEMPLATE_FILE",
+    "TEMPLATE_ROLE",
+    "BASELINE_WIDTH",
+    # Thresholds
+    "CORE_THRESHOLD",
+    "BONUS_THRESHOLD",
+    "BONUS_MIN_WARN",
+    "DEFAULT_NMS_DIST",
+    # Types
+    "Hit",
+    "UnreadDotHit",
+    # Primitives
+    "load_template",
+    "scale_template",
+    "match_all",
+    "match_best",
+    # Detectors (Day 1b)
+    "detect_new_messages_hint",
+    "detect_unread_divider",
+    "detect_favorite_labels",
+    "detect_wechat_note_header",
+    "detect_chat_back_chevron",
+    "detect_chat_title_more_dots",
+    "match_chat_back_chevron_core",
+    "match_chat_title_more_dots_core",
+    "detect_chat_input_voice_button",
+    "detect_chat_input_emoji_smile_button",
+    "detect_chat_input_plus_button",
+    "classify_top_bottom",
+    # Detectors (Day 4 auto-scan)
+    "detect_unread_dots",
+    "dedupe_unread_dot_hits",
+    "split_conversation_rows",
+    "split_conversation_rows_by_avatar_centroids",
+    "split_conversation_rows_by_avatar_roundrect_centroids",
+    "conversation_list_row_rects",
+    # Day 4 auto-scan constants
+    "RED_HSV_LOW_LO",
+    "RED_HSV_LOW_HI",
+    "RED_HSV_HIGH_LO",
+    "RED_HSV_HIGH_HI",
+    "UNREAD_DOT_MIN_AREA_BASELINE",
+    "UNREAD_DOT_MAX_AREA_BASELINE",
+    "UNREAD_DOT_MAX_ASPECT",
+    "UNREAD_DOT_LIST_MIN_CIRCULARITY",
+    "LIST_AVATAR_BADGE_LOW_H_MAX",
+    "LIST_AVATAR_BADGE_MIN_AREA_BASELINE",
+    "LIST_AVATAR_BADGE_SAT_MIN",
+    "LIST_AVATAR_BADGE_VAL_MIN",
+    "LIST_AVATAR_BADGE_ORANGE_AUX_HUE_LO",
+    "LIST_AVATAR_BADGE_ORANGE_AUX_HUE_HI",
+    "LIST_AVATAR_BADGE_ORANGE_AUX_SAT_MIN",
+    "LIST_AVATAR_BADGE_ORANGE_AUX_VAL_MIN",
+    "CONVERSATION_ROW_HEIGHT_BASELINE",
+    "CONVERSATION_AVATAR_RIGHT_EDGE_BASELINE",
+    "CONVERSATION_LIST_AVATAR_ROI_LEFT_BASELINE",
+    "CONVERSATION_LIST_AVATAR_ROI_RIGHT_BASELINE",
+    "CONVERSATION_LIST_AVATAR_MEDIAN_X_HALF_WIDTH_BASELINE",
+    "CONVERSATION_LIST_AVATAR_ROW_MIN_VISIBLE_HEIGHT_AFTER_CLIP_BASELINE",
+    "CONVERSATION_LIST_AVATAR_ROW_MIN_VISIBLE_HEIGHT_EDGE_FRAC",
+    "conversation_list_avatar_hough_roi_y2_exclusive_px",
+    "LIST_ROW_GEOMETRY_Y12_GAP_SPREAD_MAX_BASELINE",
+    "LIST_ROW_SCREEN_HEIGHT_CALIBRATION_Y12_BASELINE",
+    "conversation_list_avatar_roundrect_centroid_mid_y_ordered",
+    "prd_wechat_main_list_row_count_by_gap_y12",
+    "prd_wechat_main_list_row_count_gap_y12_from_screen_roundrect",
+    "CONVERSATION_RIGHT_SIDE_RESERVED_BASELINE",
+    "CONVERSATION_FIRST_ROW_TOP_BASELINE",
+    "WECHAT_TITLE_TO_FIRST_ROW_OFFSET_BASELINE",
+    "WX_COLLECTOR_LIST_ROW_Y12_GAP_SPREAD_MAX_BASELINE_ENV",
+    "resolve_list_row_y12_gap_spread_max_baseline_px",
+    "conversation_list_avatar_prd_y12_row_pitch_calibration",
+    "detect_wechat_main_title_bottom_y",
+    "detect_wechat_main_bottom_tab_bar_four_columns",
+    "detect_wechat_bottom_tab_selected_green_index",
+    "conversation_list_visible_pinned_row_count",
+    "is_wechat_main_conversation_list_chrome",
+    "reposition_anchor_bottom_wechat_tap_lane_plausible",
+    "is_wechat_recent_pull_anchor_early_stop_frame",
+    "estimate_list_row_background_v95",
+    "PINNED_BACKGROUND_V95_MAX",
+    "list_row_is_pinned_grey_background",
+]