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

screenshot_vision_algorithm/android/wechat/ocr/nickname_binding.py

@@ -0,0 +1,1888 @@
+"""Session-scoped, simplest-viable speaker nickname extractor (d3-nickname-ocr-minimal, v0.5 P1-3 minimal).
+
+Day 3 scope (this module):
+
+    Take one ``OcrPageResult`` (from ``text_ocr_adapter`` — d2-4) plus the
+    corresponding ``Screenshot`` metadata and return a
+    ``ChatSpeakerAttribution`` describing which OCR text blocks are
+    **nicknames** (group-chat bubble headers) and which bubbles belong
+    to the device owner (right-half-screen) vs. still-unknown speakers.
+
+    Replaces the ``speaker_nickname=stub='UNKNOWN'`` placeholder that
+    Thin Slice v1 left behind. **Session-internal only** — no cross-session
+    nickname-hash aggregation (that's P1-3' ``CrossSessionSpeakerService``,
+    scheduled post-launch).
+
+**PRD 验收口径（防漂移）**：单帧 **昵称行 / 气泡块** 的产品边界、靠左/靠右发言之 **头像守卫** 硬门槛，以及「昵称不属于任何气泡、气泡内不包括昵称」等，以仓库根 **[`docs/requirements/product_requirement_document.md`](../../../docs/requirements/product_requirement_document.md) §九、7.（2）（3）** 为验收 SSOT；本模块启发式或 `nickname_avatar_guard` 行为与之不一致时，**以实现补丁对齐 PRD** 为准（ADR §2.5.2 术语镜像段亦引用该节）。
+
+Explicit non-goals (by design, per ADR v0.3 / v0.5):
+
+  - **Cross-session aggregation**: P1-3' ``CrossSessionSpeakerService``
+    will handle ``sha256(platform|NFC(nickname)|phone_extracted|salt)[:16]``
+    hashing for order attribution; this module stops at
+    ``nickname=<raw-string>`` within one session.
+  - **Head-avatar pHash / geometry**: ADR v0.3 永久边界：**不做**头像 pHash；
+    仅以 OCR 块 + bbox 归因；PRD 术语§5 另允许 **侧栏头像 Hough 纵向筒**
+    （`processor/chat_bubble_geometry_prd.py`，与 pHash **无关**）。
+  - **Bubble detection**: PaddleOCR returns text blocks, NOT speech bubble
+    outlines. We approximate bubble membership via "next text block(s)
+    below the nickname within ``bubble_vertical_gap_max_px`` on the same
+    screen-half". This is the simplest viable heuristic and covers the
+    80% case (group chat with visible nicknames above each bubble).
+  - **Confidence-weighted voting across pages**: a nickname string is
+    returned as-is per page; no de-duping / normalization / merging
+    happens here. Downstream code (Admin ``/wx-ocr-stats`` page) does
+    its own roll-up (non-stub share %).
+  - **Text normalization**: raw OCR string is kept as-is (matches the
+    ``raw_full_text`` contract of ``text_ocr_adapter``). Downstream
+    ``lite_text_normalizer.normalize_business_text`` is the phase-4
+    consumer.
+
+Contract surface (2 dataclasses + 1 function):
+
+    ``extract_nicknames(
+        ocr_result, screenshot, config=None, png_path=None
+    ) -> ChatSpeakerAttribution``
+
+    The function accepts any ``OcrPageResult`` (``screenshot.type ==
+    "chat_message"`` expected by caller; we assert it) and returns a
+    frozen ``ChatSpeakerAttribution``. All geometry heuristics live in
+    ``NicknameOcrConfig`` — overridable for fixture / test isolation.
+
+Heuristic summary (all adjustable via ``NicknameOcrConfig``):
+
+    STEP 0 (PRD §7(3))：仅对相邻且均已标为 ``bubble_text`` 的块尝试合并——
+        **同一半屏**内「水平连续」（同水平带 + 横向间隙小）的 Paddle 碎片合成一条气泡块；
+        （同气泡多行竖叠合并易与相邻消息混淆，留给昵称认领链处理。）
+        再进入昵称认领。
+
+    STEP 1: Pre-filter each text block to one of
+        "nickname_candidate" / "bubble_text" / "drop".
+
+        ``nickname_candidate`` requires:
+          (a) ``confidence >= config.min_confidence``
+          (b) ``len(text_stripped) <= config.nickname_max_chars``
+          (c) text does NOT start with any prefix in
+              ``config.system_prefix_drops`` (``@``, ``撤回``,
+              ``系统消息``, …)
+          (d) text is NOT a pure ``HH:MM`` time stamp
+          (e) text is NOT a pure digit run (phone / day number)
+          (f) bbox x-center is on the LEFT half-screen
+              (``x_center < original_width * config.screen_midline_ratio``)
+          (g) bbox height is ``<= median_text_height *
+              config.nickname_max_char_height_ratio``
+              (nicknames are visually smaller than bubble body text in
+              the WeChat group-chat layout)
+
+        ``bubble_text``: the leftover blocks (may be left-half or
+        right-half bubbles).
+
+        ``drop``: low-confidence blocks (already filtered by
+        ``TextOcrAdapter`` upstream; we keep the gate here for
+        tests that inject raw fake blocks bypassing the adapter).
+
+    STEP 2: For each ``nickname_candidate``, claim ``bubble_text``
+        blocks immediately below it on the LEFT half screen, within
+        ``bubble_vertical_gap_max_px`` vertical pixels, stopping when
+        we hit the next ``nickname_candidate`` or walk past the gap.
+
+    STEP 3: Classify each remaining ``bubble_text``:
+          - right-half bubble → ``owner``（``wo``）
+          - left-half orphan → 归因链结束后 **继承**同侧上方最近昵称；无可继承则
+            ``speaker_display=找不到归属昵称``（参见 PRD 九§7(4)(5））。
+
+    STEP 4（PRD §7(5)+(5')）：``SpeakerBodySegment`` 层按 **整行占位关键词**剔除后，
+        ``len(body.strip()) < min_bubble_body_chars`` 的段落丢弃；
+        ``total_bubbles`` 等计数以_finalize 过滤后为准。
+
+    STEP 5（术语§5）：在提供 ``png_path`` 且启用 ``NicknameOcrConfig.use_prd_chat_vertical_bands``
+        时加载 ``chat_bubble_geometry_prd`` 纵向筒——昵称仅能认领与其 **同属一筒（含 ±12px@1080）**
+        的左侧正文块；检出无头像则将整帧正文归为「找不到归属昵称」单段。
+
+Fields on ``ChatSpeakerAttribution`` designed so Admin roll-up can
+compute "non-stub share %" via ``bubbles_with_nickname / total_bubbles``.
+
+References:
+    OCR ADR v0.5 §2.3 speaker_nickname (phase 2 NicknameBoundaryService)
+    OCR ADR v0.3 §4.3.0 project vision-layer boundary
+    session-handoff-20260429.mdc Day 3 d3-nickname-ocr-minimal row
+    scripts/wx_match/processor/text_ocr_adapter.py
+        ``OcrPageResult`` / ``TextBlock`` / reading order contract
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from dataclasses import replace as dataclass_replace
+from pathlib import Path
+from statistics import median
+from typing import TYPE_CHECKING, Any, Optional, Tuple
+
+from screenshot_vision_algorithm.android.wechat.ocr.text_ocr_adapter import OcrPageResult, TextBlock
+
+if TYPE_CHECKING:
+    from collector.contracts import Screenshot
+
+_OWNER_SPEAKER_LABEL = "wo"
+"""右侧气泡（设备持有方）在 PRD 发言人 JSON 中的统一展示键。"""
+
+SPEAKER_DISPLAY_UNATTRIBUTED = "找不到归属昵称"
+"""PRD 九§7（4）：左侧无法归因到昵称的段级占位展示键。"""
+
+
+# ============================================================================
+# Config
+# ============================================================================
+
+
+@dataclass(frozen=True)
+class NicknameOcrConfig:
+    """All heuristic thresholds in one place.
+
+    Defaults are tuned for the ``edb1a89f`` Thin Slice v1 fixture
+    (1080x2248 real-device captures, WeChat 8.0.69, default-light
+    theme). Tests override freely — no I/O, no logging dependency.
+    """
+
+    min_confidence: float = 0.7
+    """Skip any block below this confidence（defence-in-depth vs.
+    ``TextOcrAdapter.confidence_threshold``；与 PRD §6 / §11 块级 **0.7** 对齐）。"""
+
+    nickname_max_chars: int = 30
+    """WeChat group-chat nickname cap. Longer strings are almost
+    certainly bubble body text."""
+
+    screen_midline_ratio: float = 0.5
+    """x-center < ``original_width * ratio`` ⇒ left-half-screen."""
+
+    nickname_max_char_height_ratio: float = 0.85
+    """Nickname bbox height must be at most ``median_height * ratio``.
+
+    Default ``0.85`` is calibrated for real WeChat captures — nicknames
+    render in a visibly smaller font than bubble body text (typically
+    ~30px vs. ~45px on a 1080-wide device). This cuts false positives
+    cleanly once the frame has ≥1 bubble-body block to anchor the median.
+
+    Failure mode on degenerate same-height synthetic inputs: every block
+    fails the bound (median == self) and no nickname is reported. That's
+    acceptable — a frame with zero height variance has no speaker
+    signal to extract anyway; callers see ``nicknames=()`` and fall
+    through to the owner/unknown classification. Tests override this
+    knob to explore boundary behaviour."""
+
+    bubble_vertical_gap_max_px: int = 120
+    """Max vertical distance (bubble top minus nickname bottom) within
+    which a ``bubble_text`` block is claimed by the nickname above."""
+
+    min_bubble_body_chars: int = 12
+    """PRD §7(5) L：单段气泡正文 strip 后字符数低于此值则丢弃该段（不计入分段与计数）。"""
+
+    bubble_fragment_same_line_y_tol_px: int = 18
+    """PRD §7(3)：同一水平带上相邻 OCR 块竖直中心容差（px）。"""
+
+    bubble_fragment_horizontal_gap_max_px: int = 36
+    """PRD §7(3)：水平相邻碎片最大间隙；实际阈值与 ``median_h`` 成比例取较大。"""
+
+    avatar_gutter_px: int = 10
+    avatar_min_left_roi_width_px: int = 40
+    avatar_laplacian_var_min: float = 48.0
+    avatar_rgb_std_min: float = 4.0
+    avatar_roi_extend_up_px: int = 80
+    avatar_roi_extend_down_px: int = 4
+    avatar_roi_extend_up_row_mul: float = 2.5
+    avatar_roi_narrow_up_px: int = 4
+    avatar_roi_narrow_down_px: int = 4
+    avatar_edge_sig_cols_min: float = 15.0
+    avatar_edge_right_left_ratio_min: float = 1.2
+    """头像栏 ROI 裁剪与纹理/形状阈值（见 ``nickname_avatar_guard.avatar_roi_pass``）。"""
+
+    nickname_max_x1_ratio: float = 0.30
+    """昵称行 bbox 左缘须 ``x1 < original_width * ratio``（排除居中系统行/时间行）。"""
+
+    nickname_phone_height_ratio: float = 1.08
+    """行末含 11 位手机号时，字高上限放宽为 ``median_h * ratio``。"""
+
+    #: True 时在提供 PNG 路径且 cv2 可用时启用 PRD 术语§5头像时间轴纵向筒昵称认领。
+    use_prd_chat_vertical_bands: bool = True
+
+    #: PRD §九 7（2）：无 ``png_path`` 或守卫未通过时 **不得** 记为可绑定昵称行。
+    require_avatar_guard_for_nickname: bool = True
+
+    #: PRD §九 7（2）：``avatar_roi_pass`` 使用 :func:`nickname_avatar_guard.nickname_row_passes_prd_avatar_guard`（须有 Hough 锚点）。
+    use_prd_strict_avatar_guard: bool = True
+
+    #: PRD §九 7（3）：昵称行 bbox 宽度上限（px @ 1080 设计宽，× ``width/1080``）；更宽视为气泡正文。
+    nickname_max_bbox_width_px: int = 220
+
+    system_prefix_drops: tuple[str, ...] = (
+        "@",
+        "撤回了一条消息",
+        "系统消息",
+        "邀请",
+        "加入了群聊",
+        "已加入群聊",
+        "[系统提示]",
+        "以上为历史消息",
+        "仅群主",
+        "以下为新消息",
+    )
+    """Prefix / substring tags that exclude a block from nickname
+    consideration even if all geometric criteria pass."""
+
+
+_ATTRIBUTION_PREFIX_DROPS: tuple[str, ...] = (
+    "撤回了一条消息",
+    "系统消息",
+    "邀请",
+    "加入了群聊",
+    "已加入群聊",
+    "[系统提示]",
+    "以上为历史消息",
+    "仅群主",
+)
+"""归因展示昵称路径专用：不包含 ``@``，避免企业微信「@后缀」整块被误判为 @mention。
+
+
+业务规则：归因用昵称取 OCR 原文（同桌邻块按阅读序拼接）；仅排除明确的系统占位行。"""
+
+
+# ============================================================================
+# Output shape
+# ============================================================================
+
+
+@dataclass(frozen=True)
+class NicknameExtraction:
+    """One identified nickname + which subsequent bubble text blocks it owns.
+
+    ``following_block_indices`` are indices into
+    ``OcrPageResult.text_blocks`` (reading-order). Empty list means the
+    nickname was detected but no bubble body was close enough to claim;
+    still reported so Admin can surface "naked nickname lines" (useful
+    for QA).
+
+    ``nickname_block_index`` is the index of the nickname line itself in
+    ``text_blocks`` (reading order), used to emit ``SpeakerBodySegment`` in
+    top-to-bottom order.
+    """
+
+    nickname: str
+    bbox_xyxy: tuple[int, int, int, int]
+    confidence: float
+    following_block_indices: tuple[int, ...] = field(default_factory=tuple)
+    nickname_block_index: int = -1
+    band_index: Optional[int] = None
+
+
+@dataclass(frozen=True)
+class SpeakerBodySegment:
+    """单页聊天图中一段可归属正文（PRD §8 发言人 JSON 的原材料）。"""
+
+    speaker_display: str
+    """OCR 昵称原文、设备侧 ``wo``、或空串（左侧 orphan 气泡）。"""
+
+    body_text: str
+    orphan: bool
+    #: OCR text block 在 ``blocks`` 列表中的原始索引（-1 表示无）。
+    #: 用于 PRD §5 band 归属推断。
+    block_index: int = -1
+
+
+@dataclass(frozen=True)
+class ResumeThumbBinding:
+    """PRD §6(2)：单帧内一张简历卡 → 所属昵称的绑定。
+
+    绑定依据 **PRD §5 头像 y-top 纵向筒**（``chat_bubble_geometry_prd``）：
+    thumb bbox 与已被昵称认领的左侧气泡块几何相交 → 认领该气泡的昵称即为
+    thumb 所属发言人。参见 ``_resume_thumb_bindings_and_orphans``。
+    """
+
+    thumb_bbox: tuple[int, int, int, int]
+    """[x1, y1, x2, y2] — 与 metadata ``source_thumb_bbox`` 完全对齐。"""
+    nickname: str
+    """OCR 昵称原文（与 ``NicknameExtraction.nickname`` 同源）。"""
+
+
+@dataclass(frozen=True)
+class ChatSpeakerAttribution:
+    """Session-internal speaker attribution result for ONE chat screenshot.
+
+    Top-level status counters expose enough for Admin
+    ``/wx-ocr-stats`` to compute per-session non-stub share:
+
+        non_stub_share = bubbles_with_nickname / max(total_bubbles, 1)
+
+    Zero-text frames (OCR soft error / all low-confidence) return
+    ``total_bubbles=0`` and empty ``nicknames``; callers must handle
+    the divide-by-zero explicitly.
+
+    ``resume_thumb_orphans``: PRD 九 · §7(1)+§9(4) — metadata 中给出的简历卡
+    bbox 是否与**已被昵称认领**的左侧气泡相交；若不相交则计为孤儿（无法归属昵称）。
+
+    ``resume_thumb_bindings``: PRD §6(2) — 简历卡 bbox → 所属昵称的绑定映射
+    （经 PRD §5 头像 y-top 纵向筒归属的左侧气泡）。bridge 层直接用于
+    ``resolve_resume_card_speaker_binding``，不再使用侧栏启发式 fallback。
+    """
+
+    screenshot_id: str
+    nicknames: tuple[NicknameExtraction, ...] = field(default_factory=tuple)
+    total_bubbles: int = 0
+    bubbles_with_nickname: int = 0
+    bubbles_owner: int = 0
+    bubbles_unknown: int = 0
+    resume_thumb_orphans: int = 0
+    #: PRD §6(2)：简历卡 bbox → 昵称的绑定映射（本帧内，经纵向筒归属验证）。
+    resume_thumb_bindings: tuple[ResumeThumbBinding, ...] = field(default_factory=tuple)
+    #: PRD §8：本页按昵称 / 设备侧 / orphan 切分的正文段（供合并后按发言人形成 JSON 工作项）。
+    speaker_body_segments: tuple[SpeakerBodySegment, ...] = field(default_factory=tuple)
+    #: 调试用：本帧 OCR 归因全量中间数据（blocks / bands / ytops / bboxes）。
+    #: 非 None 时写入 ``debug_session_derived.json``；线上可通过环境变量关闭。
+    ocr_debug: Optional[dict[str, Any]] = None
+
+
+# ============================================================================
+# Internal helpers
+# ============================================================================
+
+
+_PURE_DIGITS_RE = re.compile(r"^\d+$")
+_PURE_TIME_RE = re.compile(r"^\d{1,2}:\d{2}(:\d{2})?$")
+_WEEKDAY_TIME_RE = re.compile(
+    r"^周[一二三四五六日天].*?(?:上午|下午|晚上|凌晨)?\s*\d{0,2}[:：]?\d{0,2}"
+)
+_MOBILE_PHONE_SUFFIX_RE = re.compile(r"1\d{10}\s*$")
+
+
+def _block_height(block: "TextBlock") -> int:
+    x1, y1, x2, y2 = block.bbox_xyxy
+    return max(0, y2 - y1)
+
+
+def _block_x_center(block: "TextBlock") -> float:
+    x1, _, x2, _ = block.bbox_xyxy
+    return (x1 + x2) / 2.0
+
+
+def _block_top(block: "TextBlock") -> int:
+    return block.bbox_xyxy[1]
+
+
+def _block_bottom(block: "TextBlock") -> int:
+    return block.bbox_xyxy[3]
+
+
+def _is_pure_time(text: str) -> bool:
+    return bool(_PURE_TIME_RE.match(text))
+
+
+def _is_pure_digits(text: str) -> bool:
+    return bool(_PURE_DIGITS_RE.match(text))
+
+
+def _is_chat_timestamp_or_divider(text: str) -> bool:
+    t = (text or "").strip()
+    if not t:
+        return False
+    if "以下为新消息" in t:
+        return True
+    if _WEEKDAY_TIME_RE.match(t):
+        return True
+    return False
+
+
+def _is_favorite_card_label(text: str) -> bool:
+    """微信卡片底栏「收藏」：禁止作为发言人昵称（产品约定昵称不可用「收藏」）。"""
+    t = (text or "").strip()
+    if t == "收藏":
+        return True
+    inner = t.strip("「」[]()（） \t")
+    return inner == "收藏"
+
+
+def _has_mobile_phone_suffix(text: str) -> bool:
+    return bool(_MOBILE_PHONE_SUFFIX_RE.search((text or "").replace(" ", "")))
+
+
+def _is_avatar_column_nickname_row(
+    block: "TextBlock",
+    original_width: int,
+    config: NicknameOcrConfig,
+    avatar_layout: Any = None,
+) -> bool:
+    try:
+        from processor.left_avatar_column import nickname_bbox_in_avatar_column
+    except ImportError:
+        nickname_bbox_in_avatar_column = None  # type: ignore[assignment,misc]
+    if avatar_layout is not None and nickname_bbox_in_avatar_column is not None:
+        if not getattr(avatar_layout, "empty", True):
+            return nickname_bbox_in_avatar_column(
+                avatar_layout,
+                block.bbox_xyxy,
+                original_width=original_width,
+                max_x1_ratio=config.nickname_max_x1_ratio,
+            )
+    x1, _, _, _ = block.bbox_xyxy
+    return float(x1) < float(original_width) * float(config.nickname_max_x1_ratio)
+
+
+def _avatar_guard_kwargs(config: NicknameOcrConfig) -> dict:
+    return {
+        "gutter_px": config.avatar_gutter_px,
+        "min_roi_width_px": config.avatar_min_left_roi_width_px,
+        "laplacian_min": float(config.avatar_laplacian_var_min),
+        "rgb_std_min": float(config.avatar_rgb_std_min),
+        "edge_sig_cols_min": float(config.avatar_edge_sig_cols_min),
+        "edge_right_left_ratio_min": float(config.avatar_edge_right_left_ratio_min),
+    }
+
+
+def _avatar_anchor_for_block(
+    block: "TextBlock",
+    avatar_layout: Any,
+    *,
+    scale_w: float,
+) -> Any:
+    if avatar_layout is None or getattr(avatar_layout, "empty", True):
+        return None
+    try:
+        from processor.left_avatar_column import find_avatar_anchor_for_nickname_bbox
+    except ImportError:
+        return None
+    return find_avatar_anchor_for_nickname_bbox(
+        avatar_layout,
+        block.bbox_xyxy,
+        scale_w=scale_w,
+    )
+
+
+def _load_left_avatar_layout(
+    png_path: Optional[Path],
+    screenshot: "Screenshot",
+) -> Any:
+    if png_path is None:
+        return None
+    try:
+        from processor.chat_bubble_geometry_prd import compute_chat_content_vertical_bounds
+        from processor.left_avatar_column import detect_left_avatar_column_layout
+        from processor.nickname_avatar_guard import load_png_bgr
+    except ImportError:
+        return None
+    arr = load_png_bgr(str(png_path))
+    if arr is None or getattr(arr, "size", 0) == 0:
+        return None
+    ow = screenshot.original_resolution.width
+    oh = screenshot.original_resolution.height
+    sw = float(ow) / 1080.0
+    bounds = compute_chat_content_vertical_bounds(arr, sw, screen_h=oh)
+    return detect_left_avatar_column_layout(
+        arr,
+        sw,
+        y_top=bounds.y_top,
+        y_bottom_excl=bounds.y_bottom_excl,
+    )
+
+
+def _starts_with_system_prefix(text: str, drops: tuple[str, ...]) -> bool:
+    for p in drops:
+        if text.startswith(p):
+            return True
+    return False
+
+
+def _is_on_left_half(
+    block: "TextBlock",
+    original_width: int,
+    ratio: float,
+) -> bool:
+    return _block_x_center(block) < original_width * ratio
+
+
+def _vertical_center(block: "TextBlock") -> float:
+    return (_block_top(block) + _block_bottom(block)) / 2.0
+
+
+def _xyxy_intersects(
+    a: tuple[int, int, int, int],
+    b: tuple[int, int, int, int],
+) -> bool:
+    ax1, ay1, ax2, ay2 = a
+    bx1, by1, bx2, by2 = b
+    return not (ax2 < bx1 or bx2 < ax1 or ay2 < by1 or by2 < ay1)
+
+
+def _xyxy_union(
+    a: tuple[int, int, int, int],
+    b: tuple[int, int, int, int],
+) -> tuple[int, int, int, int]:
+    return (
+        min(a[0], b[0]),
+        min(a[1], b[1]),
+        max(a[2], b[2]),
+        max(a[3], b[3]),
+    )
+
+
+
+def _bubble_envelopes_from_blocks(
+    blocks: list["TextBlock"],
+    classes: list[str],
+    *,
+    original_width: int,
+    config: NicknameOcrConfig,
+    median_height: float,
+) -> list[tuple[int, int, int, int]]:
+    """由 ``bubble_text`` 聚块得到包络 bbox（昵称行不得与之相交）。"""
+    envelopes: list[tuple[int, int, int, int]] = []
+    n = len(blocks)
+    i = 0
+    while i < n:
+        if classes[i] != "bubble_text":
+            i += 1
+            continue
+        cur = blocks[i].bbox_xyxy
+        j = i + 1
+        while j < n and classes[j] == "bubble_text":
+            prev_b, next_b = blocks[j - 1], blocks[j]
+            merged = _mergeable_bubble_fragments(
+                prev_b,
+                next_b,
+                original_width=original_width,
+                median_h=median_height,
+                config=config,
+            )
+            same_half = _is_on_left_half(
+                prev_b, original_width, config.screen_midline_ratio
+            ) == _is_on_left_half(
+                next_b, original_width, config.screen_midline_ratio
+            )
+            gap = _block_top(next_b) - _block_bottom(prev_b)
+            if merged is not None or (
+                same_half
+                and 0 <= gap <= int(config.bubble_vertical_gap_max_px)
+            ):
+                cur = _xyxy_union(cur, next_b.bbox_xyxy)
+                j += 1
+            else:
+                break
+        envelopes.append(cur)
+        i = j
+    return envelopes
+
+
+def _apply_prd_nickname_bubble_separation(
+    blocks: list["TextBlock"],
+    classes: list[str],
+    *,
+    original_width: int,
+    config: NicknameOcrConfig,
+    median_height: float,
+) -> None:
+    """PRD §九 7（3）：（已禁用 — 改为 bridge 层 bbox 过滤）。"""
+    pass
+
+
+def _nickname_passes_avatar_guard(
+    *,
+    bgr_guard: Any,
+    nick_block: "TextBlock",
+    avatar_layout: Any,
+    scale_w: float,
+    original_width: int,
+    config: NicknameOcrConfig,
+) -> bool:
+    """PRD §九 7（2）：靠左/靠右发言均须影像守门（无 PNG 时由调用方在 ``require_*`` 下拒绝）。"""
+    if bgr_guard is None:
+        return not config.require_avatar_guard_for_nickname
+    try:
+        from processor.nickname_avatar_guard import avatar_roi_pass
+    except ImportError:
+        return not config.require_avatar_guard_for_nickname
+
+    x1, y1, x2, y2 = nick_block.bbox_xyxy
+    left = _is_on_left_half(nick_block, original_width, config.screen_midline_ratio)
+    side = "left" if left else "right"
+    anchor = _avatar_anchor_for_block(nick_block, avatar_layout, scale_w=scale_w)
+    prd_strict = bool(config.use_prd_strict_avatar_guard)
+    return bool(
+        avatar_roi_pass(
+            bgr_guard,
+            nickname_x1=int(x1),
+            nickname_x2=int(x2),
+            y_top=int(y1),
+            y_bottom=int(y2),
+            avatar_anchor=anchor,
+            prd_strict=prd_strict,
+            side=side,
+            **_avatar_guard_kwargs(config),
+        )
+    )
+
+
+# PRD §7(5)：整行占位类关键词剔除（不包含「[文件]」）。
+# 追加 PRD §6(4)：排除收藏 / 以下为新消息。
+_PLACEHOLDER_EXACT_LINES: frozenset[str] = frozenset({
+    "收藏",
+    "以下为新消息",
+    "[语音]",
+    "[表情]",
+    "[动画表情]",
+    "[图片]",
+    "[视频]",
+    "[位置]",
+    "[链接]",
+    "[红包]",
+    "[转账]",
+    "[撤回了一条消息]",
+})
+
+
+def _strip_placeholder_lines_from_body(text: str) -> str:
+    if not text.strip():
+        return ""
+    kept: list[str] = []
+    for raw_ln in text.split("\n"):
+        stripped_ln = raw_ln.strip()
+        if not stripped_ln:
+            continue
+        if stripped_ln in _PLACEHOLDER_EXACT_LINES:
+            continue
+        kept.append(raw_ln.rstrip())
+    return "\n".join(kept).strip()
+
+
+def _apply_resume_thumb_block_mask(
+    blocks: list["TextBlock"],
+    classes: list[str],
+    screenshot: "Screenshot",
+    *,
+    original_width: int = 1080,
+    screen_midline_ratio: float = 0.45,
+) -> None:
+    """§7：简历微信笔记 thumbnail bbox 相交的 OCR 块强制 drop。
+
+    仅丢弃**右半屏**的块（简历卡片正文在右侧）；左半屏的发言人聊天气泡
+    保留为 ``bubble_text``，供后续 nickname 认领和 thumb binding 使用。
+    """
+    raws = getattr(screenshot, "resume_thumb_bboxes", None) or []
+    thumbs: list[tuple[int, int, int, int]] = []
+    for raw in raws:
+        if raw and len(raw) >= 4:
+            thumbs.append((int(raw[0]), int(raw[1]), int(raw[2]), int(raw[3])))
+    if not thumbs:
+        return
+    for i, b in enumerate(blocks):
+        bb = b.bbox_xyxy
+        if any(_xyxy_intersects(bb, tbb) for tbb in thumbs):
+            if not _is_on_left_half(b, original_width, screen_midline_ratio):
+                classes[i] = "drop"
+
+
+def _load_prd_layout_optional(
+    png_path: Optional[Path],
+    screenshot: "Screenshot",
+    *,
+    config: NicknameOcrConfig,
+) -> Any:
+    if png_path is None or not config.use_prd_chat_vertical_bands:
+        return None
+    try:
+        from processor.chat_bubble_geometry_prd import (
+            build_prd_speaker_vertical_bands,
+            compute_chat_content_vertical_bounds,
+            detect_chat_side_avatar_ytops,
+            merge_avatar_ytops_time_order,
+        )
+        from processor.nickname_avatar_guard import load_png_bgr
+    except ImportError:
+        return None
+    arr = load_png_bgr(str(png_path))
+    if arr is None or getattr(arr, "size", 0) == 0:
+        return None
+    oh = screenshot.original_resolution.height
+    ow = screenshot.original_resolution.width
+    sw = float(ow) / 1080.0
+    bounds = compute_chat_content_vertical_bounds(arr, sw, screen_h=oh)
+    ly, ry = detect_chat_side_avatar_ytops(arr, sw, bounds)
+    timeline = merge_avatar_ytops_time_order(ly, ry)
+    return build_prd_speaker_vertical_bands(timeline, bounds, scale_w=sw)
+
+
+def _finalize_prd_attribution(
+    attr: ChatSpeakerAttribution,
+    *,
+    config: NicknameOcrConfig,
+    blocks: Optional[list["TextBlock"]] = None,
+    layout_opt: Any = None,
+    scale_w: float = 1.0,
+) -> ChatSpeakerAttribution:
+    """§7：占位行剔除、短正文门控、左侧 orphan 昵称继承、「找不到归属昵称」。
+
+    PRD §5 补充：当 orphan 段落在 band 内且无 ``last_left`` 可继承时，
+    通过 band 索引查找该 band 的首个发言人昵称作为归属。
+    """
+    # 0）预计算 band_index → 首个发言人昵称（供 orphan 回退）
+    band_nick: dict[int, str] = {}
+    if layout_opt is not None and blocks is not None:
+        for n in attr.nicknames:
+            bi = n.band_index
+            if bi is not None and bi not in band_nick:
+                band_nick[bi] = n.nickname.strip()
+
+    # 1）占位剔除 + L
+    pruned_segs: list[SpeakerBodySegment] = []
+    for s in attr.speaker_body_segments:
+        body = _strip_placeholder_lines_from_body(s.body_text)
+        stripped_len = len(body.strip())
+        if stripped_len == 0:
+            continue
+        if stripped_len < max(0, int(config.min_bubble_body_chars)):
+            continue
+        pruned_segs.append(dataclass_replace(s, body_text=body))
+
+    # 2）左侧继承同侧上方最近昵称（右半屏不变）
+    #     PRD §5：若 orphan 无 last_left，回退到所在 band 的发言人
+    last_left = ""
+    out2: list[SpeakerBodySegment] = []
+    for s in pruned_segs:
+        disp_raw = (s.speaker_display or "").strip()
+        if s.speaker_display == _OWNER_SPEAKER_LABEL:
+            out2.append(s)
+            continue
+        if s.orphan and not disp_raw:
+            if last_left:
+                out2.append(
+                    dataclass_replace(
+                        s,
+                        speaker_display=last_left,
+                        orphan=False,
+                    ),
+                )
+            elif (
+                band_nick
+                and blocks is not None
+                and layout_opt is not None
+                and s.block_index >= 0
+            ):
+                # PRD §5：进入哪个 band 就归入哪个 band 的发言人
+                blk = blocks[s.block_index]
+                bi = None
+                if layout_opt is not None:
+                    _sb_o = getattr(layout_opt, "speaker_bands", ())
+                    _by1, _by2 = float(blk.bbox_xyxy[1]), float(blk.bbox_xyxy[3])
+                    for _ix, (_b0, _b1) in enumerate(_sb_o):
+                        if _by2 > float(_b0) and _by1 < float(_b1):
+                            bi = _ix
+                            break
+                band_sp = band_nick.get(bi, "") if bi is not None else ""
+                if band_sp:
+                    out2.append(
+                        dataclass_replace(
+                            s,
+                            speaker_display=band_sp,
+                            orphan=False,
+                        ),
+                    )
+                    last_left = band_sp
+                else:
+                    out2.append(
+                        dataclass_replace(
+                            s,
+                            speaker_display=SPEAKER_DISPLAY_UNATTRIBUTED,
+                            orphan=True,
+                        ),
+                    )
+            else:
+                out2.append(
+                    dataclass_replace(
+                        s,
+                        speaker_display=SPEAKER_DISPLAY_UNATTRIBUTED,
+                        orphan=True,
+                    ),
+                )
+        else:
+            out2.append(s)
+            if (
+                disp_raw
+                and disp_raw != SPEAKER_DISPLAY_UNATTRIBUTED
+                and disp_raw != _OWNER_SPEAKER_LABEL
+            ):
+                last_left = disp_raw
+
+    bubbles_owner = sum(1 for s in out2 if s.speaker_display == _OWNER_SPEAKER_LABEL)
+    bubbles_unknown = sum(
+        1 for s in out2 if (s.speaker_display or "").strip() == SPEAKER_DISPLAY_UNATTRIBUTED
+    )
+    bubbles_with_nickname = 0
+    for s in out2:
+        disp_fin = (s.speaker_display or "").strip()
+        if (
+            (not s.orphan)
+            and disp_fin
+            and disp_fin not in (_OWNER_SPEAKER_LABEL, SPEAKER_DISPLAY_UNATTRIBUTED)
+        ):
+            bubbles_with_nickname += 1
+
+    total_bubbles = len(out2)
+    return ChatSpeakerAttribution(
+        screenshot_id=attr.screenshot_id,
+        nicknames=attr.nicknames,
+        total_bubbles=total_bubbles,
+        bubbles_with_nickname=bubbles_with_nickname,
+        bubbles_owner=bubbles_owner,
+        bubbles_unknown=bubbles_unknown,
+        resume_thumb_orphans=attr.resume_thumb_orphans,
+        resume_thumb_bindings=attr.resume_thumb_bindings,
+        speaker_body_segments=tuple(out2),
+    )
+
+
+def _resume_thumb_bindings_and_orphans(
+    screenshot: "Screenshot",
+    blocks: list["TextBlock"],
+    classes: list[str],
+    claimed_indices: set[int],
+    nicknames: tuple[NicknameExtraction, ...],
+    *,
+    original_width: int,
+    config: NicknameOcrConfig,
+    layout_opt: Any = None,
+    scale_w: float = 1.0,
+    image_size: tuple[int, int] | None = None,
+) -> tuple[tuple[ResumeThumbBinding, ...], int, set[int]]:
+    """PRD §7(2)：简历卡 bbox → 所属昵称绑定 + orphan 计数。
+
+    三步逻辑：
+    A. 找到简历卡片所属 band（PRD §5 头像 y-top 纵向筒）
+    B. 在 band 内找第一行符合昵称要求的文字 → 昵称
+    C. 若无，向上找到上一行文字 → 昵称
+       （排除同上；该行文字从所在区域内容里"去除"）
+
+    Returns:
+        (bindings, orphan_count, excluded_indices)
+        excluded_indices 是 Step C 中"去除"的 block 索引，调用方应将其 classes 设为 drop。
+    """
+    raws = getattr(screenshot, "resume_thumb_bboxes", None) or []
+    if not raws:
+        return (), 0, set()
+
+    # ── 将 resume_thumb_bboxes 从手机原生分辨率缩放到 OCR 图像空间 ──
+    if image_size is not None:
+        iw, ih = float(image_size[0]), float(image_size[1])
+        now = float(screenshot.original_resolution.width)
+        noh = float(screenshot.original_resolution.height)
+        sx = iw / now if now > 0 else 1.0
+        sy = ih / noh if noh > 0 else 1.0
+        if abs(sx - 1.0) > 0.0001 or abs(sy - 1.0) > 0.0001:
+            raws = [
+                [raw[0] * sx, raw[1] * sy, raw[2] * sx, raw[3] * sy]
+                for raw in raws if raw and len(raw) >= 4
+            ]
+
+    # OCR bbox 与卡片 bbox 各有 ±2~3px 抖动：卡内标题行可能比卡顶高出 1~3px，
+    # 若按严格包含判定会被误认为"卡外文字"而误绑为昵称（2026-06-11 真实案例）。
+    # 真昵称行整体位于卡片上方（y2 < 卡顶），不受此容差影响。
+    _inside_tol = 4.0 * max(scale_w, 1.0)
+
+    def _completely_inside(block_bbox: tuple, card_bbox: tuple) -> bool:
+        bx1, by1, bx2, by2 = block_bbox
+        cx1, cy1, cx2, cy2 = card_bbox
+        # Use block centre-x rather than both edges: a block may extend a few px
+        # beyond the card's right side but still belong to the card (e.g. long
+        # skill lines), so we shouldn't treat it as "outside" on that basis.
+        bcx = (bx1 + bx2) / 2.0
+        return (
+            cx1 <= bcx <= cx2
+            and by1 >= cy1 - _inside_tol
+            and by2 <= cy2 + _inside_tol
+        )
+
+    def _should_skip_block(b: "TextBlock") -> bool:
+        t = (b.text or "").strip()
+        if not t:
+            return True
+        if t == "收藏" or t == "以下为新消息":
+            return True
+        if t.startswith("姓名：") or t.startswith("姓名:"):
+            return True
+        # 排除"**条新消息"系统提示（如 "69条新消息" 或其 OCR 片段 "69条"）
+        if re.fullmatch(r"\d+条", t) or "条新消息" in t:
+            return True
+        if _is_pure_time(t) or _is_pure_digits(t) or _is_chat_timestamp_or_divider(t):
+            return True
+        if _is_favorite_card_label(t):
+            return True
+        return False
+
+    bindings: list[ResumeThumbBinding] = []
+    orphan = 0
+    excluded_indices: set[int] = set()
+
+    # ── 用 click_coords 虚拟 2×2 区域判定点击源卡片 ──
+    click_source_card_idx: int | None = None
+    _click_ctx = getattr(screenshot, "click_context", None)
+    if _click_ctx is not None:
+        _coords = getattr(_click_ctx, "click_coords", None)
+        if _coords and len(_coords) >= 2:
+            # 按 image_size 缩放 click_coords 到 OCR 空间
+            if image_size is not None:
+                iw, ih = float(image_size[0]), float(image_size[1])
+                now = float(screenshot.original_resolution.width)
+                noh = float(screenshot.original_resolution.height)
+                csx = iw / now if now > 0 else 1.0
+                csy = ih / noh if noh > 0 else 1.0
+            else:
+                csx, csy = 1.0, 1.0
+            cx, cy = _coords[0] * csx, _coords[1] * csy
+            # 构造 2×2 虚拟区域
+            click_area = (cx, cy, cx + 2.0, cy + 2.0)
+            # 找唯一包含该区域的卡片
+            matching_cards: list[int] = []
+            for i, raw in enumerate(raws):
+                if not raw or len(raw) < 4:
+                    continue
+                rx1, ry1, rx2, ry2 = raw[0], raw[1], raw[2], raw[3]
+                if rx1 <= cx <= rx2 and ry1 <= cy <= ry2:
+                    matching_cards.append(i)
+            if len(matching_cards) == 1:
+                click_source_card_idx = matching_cards[0]
+
+    for ci, raw in enumerate(raws):
+        if not raw or len(raw) < 4:
+            continue
+        tbb = (int(raw[0]), int(raw[1]), int(raw[2]), int(raw[3]))
+
+        # ── Step A: 找到简历卡片所属 band ──
+        # PRD §8.A:
+        #   (0) 卡片完全在某个 band 内 → 归该 band
+        #   (1) 卡片同时与 2 个 band 相交 → 归下方 band
+        band_idx: Optional[int] = None
+        if layout_opt is not None:
+            _sb_list = getattr(layout_opt, "speaker_bands", ())
+            _cy1, _cy2 = float(tbb[1]), float(tbb[3])
+            for _bi, (_b0, _b1) in enumerate(_sb_list):
+                if _cy2 > float(_b0) and _cy1 < float(_b1):
+                    band_idx = _bi  # 相交 → 候选；持续覆盖 → 最后一个（下方）胜出
+
+        matched_nickname: Optional[str] = None
+
+        # ── Step B: 在 band 内找第一行符合昵称要求的文字 ──
+        # PRD §7(2) 说明1：规则仅处理块与下方 speaker_band / 简历卡片 bbox 的相交（已去掉上方相交规则）
+        if band_idx is not None and band_idx >= 0:
+            # ── 当前 band 和下方 band / 下方卡片的 Y 范围 ──
+            _sb_list = getattr(layout_opt, "speaker_bands", ())
+            if band_idx >= len(_sb_list):
+                band_idx = None  # 防御：band_idx 越界则跳过 Step B
+            else:
+                _band_y0, _band_y1 = float(_sb_list[band_idx][0]), float(_sb_list[band_idx][1])
+
+                _below_band_y0: Optional[float] = None
+                _below_band_y1: Optional[float] = None
+                if band_idx + 1 < len(_sb_list):
+                    _bb_y0, _bb_y1 = _sb_list[band_idx + 1]
+                    _below_band_y0 = float(_bb_y0)
+                    _below_band_y1 = float(_bb_y1)
+
+                _below_card_y1: Optional[float] = None
+                _below_card_y2: Optional[float] = None
+                if ci + 1 < len(raws):
+                    _next_raw = raws[ci + 1]
+                    if _next_raw and len(_next_raw) >= 4:
+                        _below_card_y1 = float(_next_raw[1])
+                        _below_card_y2 = float(_next_raw[3])
+
+                matched_nickname: Optional[str] = None
+                best_y: float = float('inf')
+                for i, b in enumerate(blocks):
+                    bb = b.bbox_xyxy
+                    _by1, _by2 = float(bb[1]), float(bb[3])
+
+                    # ── 规则 (0)：block 必须与当前 speaker_band 有 Y 交集 ──
+                    if not (_by2 > _band_y0 and _by1 < _band_y1):
+                        continue
+
+                    # ── PRD §8 相交规则 (1)(2)(3) ──
+                    _inter_below_band = False
+                    if _below_band_y0 is not None:
+                        _inter_below_band = _by2 > _below_band_y0 and _by1 < _below_band_y1
+
+                    _inter_below_card = False
+                    if _below_card_y1 is not None:
+                        _inter_below_card = _by2 > _below_card_y1 and _by1 < _below_card_y2
+
+                    # 规则 (1)：与下方 band 相交且不与下方 card 相交 → skip
+                    #          （块位于下方 band 内部，但与该 band 的卡无交集，不属于当前卡）
+                    if _inter_below_band and not _inter_below_card:
+                        continue
+
+                    # 规则 (2)：与下方 band 和下方 card 同时相交 → skip
+                    #          （块夹在 band 分界线和下方 card 顶线之间 → 属下方 band/card）
+                    if _inter_below_band and _inter_below_card:
+                        continue
+
+                    # 规则 (3)：不与下方 band 相交，但与下方 card 相交 → 属于当前 card
+                    #          （隐含：不 continue）
+
+                    if _should_skip_block(b):
+                        continue
+
+                    is_fully_inside = _completely_inside(bb, tbb)
+                    # 排除完全在简历卡片 bbox 内的文字（正文）
+                    if is_fully_inside:
+                        continue
+
+                    # ── 按距离选最优：取 y_bottom 最接近 band 上界的块 ──
+                    if _by2 < best_y:
+                        best_y = _by2
+                        matched_nickname = (b.text or "").strip()
+
+        # ── Step C: 向上找到上一行文字（跨 band） ──
+        if matched_nickname is None:
+            best_i: Optional[int] = None
+            best_bottom: float = -1.0
+            card_top = float(tbb[1])
+            for i, b in enumerate(blocks):
+                bcx = float(b.bbox_xyxy[3])  # block bottom
+                if bcx >= card_top:
+                    continue
+                if _should_skip_block(b):
+                    continue
+                if bcx > best_bottom:
+                    best_bottom = bcx
+                    best_i = i
+
+            if best_i is not None:
+                # PRD §B.1 C：距离检查——文字底部到卡片所属 speaker_band 顶部
+                # 超过阈值（50px baseline × scale_w）则不作为昵称
+                _use_as_nickname = True
+                if band_idx is not None and band_idx >= 0:
+                    _sb_list = getattr(layout_opt, "speaker_bands", ())
+                    if band_idx < len(_sb_list):
+                        _band_y0 = float(_sb_list[band_idx][0])
+                        _gap = _band_y0 - best_bottom  # positive → block above band
+                        _threshold = 50.0 * float(scale_w)
+                        if _gap > _threshold:
+                            _use_as_nickname = False
+                if _use_as_nickname:
+                    matched_nickname = (blocks[best_i].text or "").strip()
+                    # PRD §7(2)：「去除」——这行文字从所在区域内容里移除
+                    excluded_indices.add(best_i)
+
+        if matched_nickname:
+            bindings.append(ResumeThumbBinding(thumb_bbox=tbb, nickname=matched_nickname))
+        else:
+            orphan += 1
+
+    return tuple(bindings), orphan, excluded_indices
+
+
+def _merge_attrib_line_from_seed(
+    blocks: list["TextBlock"],
+    seed_idx: int,
+    *,
+    original_width: int,
+    cfg: NicknameOcrConfig,
+    median_height: float,
+) -> Optional[Tuple[str, tuple[int, int, int, int]]]:
+    """从 seed 块起按阅读序合并同桌昵称行，返回 (text, bbox)。"""
+    ROW_TOL = 30
+    anchor_y = _vertical_center(blocks[seed_idx])
+    merged_blocks: list["TextBlock"] = []
+    for j in range(seed_idx, len(blocks)):
+        b = blocks[j]
+        tb = b.text.strip()
+        if not tb or b.confidence < cfg.min_confidence:
+            break
+        if not _is_on_left_half(b, original_width, cfg.screen_midline_ratio):
+            break
+        if abs(_vertical_center(b) - anchor_y) > ROW_TOL:
+            break
+        if _is_pure_time(tb) or _is_pure_digits(tb) or _is_chat_timestamp_or_divider(tb):
+            break
+        if _is_favorite_card_label(tb):
+            break
+        if _starts_with_system_prefix(tb, _ATTRIBUTION_PREFIX_DROPS):
+            break
+        if j > seed_idx and median_height > 2.0:
+            if _block_height(b) > median_height * 1.12:
+                break
+        merged_blocks.append(b)
+    if not merged_blocks:
+        return None
+    xs1 = min(b.bbox_xyxy[0] for b in merged_blocks)
+    ys1 = min(b.bbox_xyxy[1] for b in merged_blocks)
+    xs2 = max(b.bbox_xyxy[2] for b in merged_blocks)
+    ys2 = max(b.bbox_xyxy[3] for b in merged_blocks)
+    merged_text = "".join(b.text.strip() for b in merged_blocks)
+    if not merged_text:
+        return None
+    return merged_text, (int(xs1), int(ys1), int(xs2), int(ys2))
+
+
+def _iter_first_attrib_seed_indices(
+    blocks: list["TextBlock"],
+    *,
+    original_width: int,
+    cfg: NicknameOcrConfig,
+    median_height: float,
+    avatar_layout: Any = None,
+) -> list[int]:
+    """阅读序下所有通过几何启发式的首归因 seed 索引（供过滤择优）。"""
+    seeds: list[int] = []
+    for idx, b in enumerate(blocks):
+        text = b.text.strip()
+        if not text or b.confidence < cfg.min_confidence:
+            continue
+        if _is_pure_time(text) or _is_pure_digits(text) or _is_chat_timestamp_or_divider(text):
+            continue
+        if _is_favorite_card_label(text):
+            continue
+        if _starts_with_system_prefix(text, _ATTRIBUTION_PREFIX_DROPS):
+            continue
+        if not _is_on_left_half(b, original_width, cfg.screen_midline_ratio):
+            continue
+        if not _is_avatar_column_nickname_row(b, original_width, cfg, avatar_layout):
+            continue
+        seeds.append(idx)
+    return seeds
+
+
+def first_attrib_verbatim_display_line_and_bbox(
+    ocr_result: "OcrPageResult",
+    screenshot: "Screenshot",
+    *,
+    config: Optional[NicknameOcrConfig] = None,
+    png_path: Optional["Path"] = None,
+) -> Optional[Tuple[str, tuple[int, int, int, int]]]:
+    """左栏首条合格昵称：几何候选按阅读序过滤，**第一个**通过 ``avatar_roi_pass`` 的才采纳。"""
+    cfg = config or NicknameOcrConfig()
+    assert screenshot.type == "chat_message", (
+        "first_attrib_verbatim_display_line expects chat_message type; got "
+        f"{screenshot.type!r}"
+    )
+    assert ocr_result.screenshot_id == screenshot.screenshot_id, (
+        f"screenshot_id mismatch ocr_result={ocr_result.screenshot_id!r} vs "
+        f"screenshot={screenshot.screenshot_id!r}"
+    )
+    blocks = list(ocr_result.text_blocks)
+    if not blocks:
+        return None
+
+    original_width = screenshot.original_resolution.width
+    heights = [_block_height(b) for b in blocks if _block_height(b) > 0]
+    median_height = float(median(heights)) if heights else 1.0
+
+    bgr_guard = None
+    avatar_layout = _load_left_avatar_layout(png_path, screenshot)
+    scale_w = float(original_width) / 1080.0
+    if png_path is not None:
+        try:
+            from processor.nickname_avatar_guard import load_png_bgr
+
+            bgr_guard = load_png_bgr(str(png_path))
+        except ImportError:
+            bgr_guard = None
+
+    for seed_idx in _iter_first_attrib_seed_indices(
+        blocks,
+        original_width=original_width,
+        cfg=cfg,
+        median_height=median_height,
+        avatar_layout=avatar_layout,
+    ):
+        merged = _merge_attrib_line_from_seed(
+            blocks,
+            seed_idx,
+            original_width=original_width,
+            cfg=cfg,
+            median_height=median_height,
+        )
+        if merged is None:
+            continue
+        merged_text, bbox = merged
+        seed_block = blocks[seed_idx]
+        if not _nickname_passes_avatar_guard(
+            bgr_guard=bgr_guard,
+            nick_block=seed_block,
+            avatar_layout=avatar_layout,
+            scale_w=scale_w,
+            original_width=original_width,
+            config=cfg,
+        ):
+            continue
+        return merged_text, bbox
+
+    return None
+
+
+def first_attrib_verbatim_display_line(
+    ocr_result: "OcrPageResult",
+    screenshot: "Screenshot",
+    *,
+    config: Optional[NicknameOcrConfig] = None,
+    png_path: Optional["Path"] = None,
+) -> Optional[str]:
+    """左栏第一条「归因展示昵称」行：拼接 OCR Reading order 中同桌邻块原文。
+
+    与 ``extract_nicknames``（气泡归因统计）并行；**不入库**侧的微信昵称是否采纳还应在
+    影像层校验左侧头像 ROI（processor 中与 ``nickname_avatar_guard`` 串联）。
+    """
+    pair = first_attrib_verbatim_display_line_and_bbox(
+        ocr_result, screenshot, config=config, png_path=png_path
+    )
+    return pair[0] if pair else None
+
+
+def _classify(
+    block: "TextBlock",
+    *,
+    original_width: int,
+    config: NicknameOcrConfig,
+    median_height: float,
+    avatar_layout: Any = None,
+) -> str:
+    """Return ``"nickname_candidate"`` / ``"bubble_text"`` / ``"drop"``."""
+    text = block.text.strip()
+    if not text:
+        return "drop"
+    if block.confidence < config.min_confidence:
+        return "drop"
+    if (
+        _is_pure_time(text)
+        or _is_pure_digits(text)
+        or _is_chat_timestamp_or_divider(text)
+        or _is_favorite_card_label(text)
+    ):
+        return "drop"
+
+    is_left = _is_on_left_half(block, original_width, config.screen_midline_ratio)
+
+    if (
+        len(text) <= config.nickname_max_chars
+        and not _starts_with_system_prefix(text, config.system_prefix_drops)
+        and is_left
+        and _is_avatar_column_nickname_row(
+            block, original_width, config, avatar_layout
+        )
+    ):
+        return "nickname_candidate"
+
+    return "bubble_text"
+
+
+def _merge_two_text_blocks(a: TextBlock, b: TextBlock, *, joiner: str) -> TextBlock:
+    ax1, ay1, ax2, ay2 = a.bbox_xyxy
+    bx1, by1, bx2, by2 = b.bbox_xyxy
+    u = (min(ax1, bx1), min(ay1, by1), max(ax2, bx2), max(ay2, by2))
+    ta = a.text.strip()
+    tb = b.text.strip()
+    if joiner == "\n":
+        text = f"{ta}\n{tb}" if ta else tb
+    else:
+        text = f"{ta}{tb}" if ta else tb
+    conf = min(a.confidence, b.confidence)
+    return TextBlock(
+        text=text,
+        bbox_xyxy=tuple(int(x) for x in u),
+        confidence=conf,
+        line_read_index=a.line_read_index or b.line_read_index,
+        paragraph_read_index=a.paragraph_read_index or b.paragraph_read_index,
+    )
+
+
+def _horizontal_gap_left_to_right(a_xyxy: tuple[int, int, int, int], b_xyxy: tuple[int, int, int, int]) -> int:
+    """Non-negative gap when ``a`` is left of ``b`` (``a.x2 <= b.x1``); else ``0``."""
+    ax2 = a_xyxy[2]
+    bx1 = b_xyxy[0]
+    if ax2 <= bx1:
+        return bx1 - ax2
+    return 0
+
+
+def _vertical_axis_overlap_ratio(a_xyxy: tuple[int, int, int, int], b_xyxy: tuple[int, int, int, int]) -> float:
+    ay1, ay2 = a_xyxy[1], a_xyxy[3]
+    by1, by2 = b_xyxy[1], b_xyxy[3]
+    inter = min(ay2, by2) - max(ay1, by1)
+    if inter <= 0:
+        return 0.0
+    ha = max(1, ay2 - ay1)
+    hb = max(1, by2 - by1)
+    return float(inter) / float(min(ha, hb))
+
+
+def _mergeable_bubble_fragments(
+    a: TextBlock,
+    b: TextBlock,
+    *,
+    original_width: int,
+    median_h: float,
+    config: NicknameOcrConfig,
+) -> Optional[str]:
+    """PRD §7(3)：返回 ``''``（水平拼接）或 ``'\\n'``（换行拼接），不可合并则 ``None``。"""
+    if _is_on_left_half(a, original_width, config.screen_midline_ratio) != _is_on_left_half(
+        b,
+        original_width,
+        config.screen_midline_ratio,
+    ):
+        return None
+    if a.confidence < config.min_confidence or b.confidence < config.min_confidence:
+        return None
+
+    y_tol = float(config.bubble_fragment_same_line_y_tol_px)
+    d_centers = abs(_vertical_center(a) - _vertical_center(b))
+    if d_centers <= y_tol:
+        gap = _horizontal_gap_left_to_right(a.bbox_xyxy, b.bbox_xyxy)
+        max_gap = max(
+            float(config.bubble_fragment_horizontal_gap_max_px),
+            median_h * 1.15,
+        )
+        if gap <= max_gap and (
+            _vertical_axis_overlap_ratio(a.bbox_xyxy, b.bbox_xyxy) >= 0.22 or gap == 0
+        ):
+            return ""
+        return None
+
+    return None
+def _prd_merge_adjacent_bubble_text_blocks(
+    blocks: list[TextBlock],
+    *,
+    original_width: int,
+    config: NicknameOcrConfig,
+) -> list[TextBlock]:
+    """PRD §7(3)：在进入 STEP1 分类主循环前，合并同一气泡的 Paddle 碎片（仅 ``bubble_text`` 之间）。"""
+    if len(blocks) < 2:
+        return blocks
+    heights = [_block_height(b) for b in blocks if _block_height(b) > 0]
+    median_h = float(median(heights)) if heights else 1.0
+    classes = [
+        _classify(
+            b,
+            original_width=original_width,
+            config=config,
+            median_height=median_h,
+        )
+        for b in blocks
+    ]
+    out: list[TextBlock] = []
+    i = 0
+    n = len(blocks)
+    while i < n:
+        if classes[i] != "bubble_text":
+            out.append(blocks[i])
+            i += 1
+            continue
+        cur = blocks[i]
+        j = i + 1
+        while j < n:
+            if classes[j] != "bubble_text":
+                break
+            joiner = _mergeable_bubble_fragments(
+                cur,
+                blocks[j],
+                original_width=original_width,
+                median_h=median_h,
+                config=config,
+            )
+            if joiner is None:
+                break
+            cur = _merge_two_text_blocks(cur, blocks[j], joiner=joiner)
+            j += 1
+        out.append(cur)
+        i = j
+    return out
+
+
+def _join_segment_body_lines(blocks: list["TextBlock"], indices: tuple[int, ...]) -> str:
+    parts = [blocks[i].text.strip() for i in indices]
+    return "\n".join(p for p in parts if p)
+
+
+def _speaker_body_segments_from_layout(
+    blocks: list["TextBlock"],
+    classes: list[str],
+    nicknames: tuple[NicknameExtraction, ...],
+    claimed_indices: set[int],
+    *,
+    original_width: int,
+    config: NicknameOcrConfig,
+) -> tuple[SpeakerBodySegment, ...]:
+    """按阅读序构造本页 ``SpeakerBodySegment``（昵称块本身不占正文）。"""
+    min_len = max(0, int(config.min_bubble_body_chars))
+    segments: list[tuple[int, SpeakerBodySegment]] = []
+
+    for n in nicknames:
+        body = _join_segment_body_lines(blocks, n.following_block_indices)
+        stripped = body.strip()
+        if not stripped:
+            continue
+        if len(stripped) < min_len:
+            continue
+        idx = int(n.nickname_block_index)
+        if idx < 0:
+            continue
+        segments.append(
+            (
+                idx,
+                SpeakerBodySegment(
+                    speaker_display=n.nickname.strip(),
+                    body_text=body,
+                    orphan=False,
+                    block_index=idx,
+                ),
+            )
+        )
+
+    for idx, klass in enumerate(classes):
+        if klass != "bubble_text":
+            continue
+        if idx in claimed_indices:
+            continue
+        text = blocks[idx].text.strip()
+        if len(text) < min_len:
+            continue
+        if _is_on_left_half(blocks[idx], original_width, config.screen_midline_ratio):
+            segments.append(
+                (
+                    idx,
+                    SpeakerBodySegment(
+                        speaker_display="",
+                        body_text=text,
+                        orphan=True,
+                        block_index=idx,
+                    ),
+                )
+            )
+        else:
+            segments.append(
+                (
+                    idx,
+                    SpeakerBodySegment(
+                        speaker_display=_OWNER_SPEAKER_LABEL,
+                        body_text=text,
+                        orphan=False,
+                        block_index=idx,
+                    ),
+                )
+            )
+
+    segments.sort(key=lambda t: t[0])
+    return tuple(s for _, s in segments)
+
+
+# ============================================================================
+# Public API
+# ============================================================================
+
+
+def _build_ocr_debug_dict(
+    screenshot: "Screenshot",
+    blocks: list["TextBlock"],
+    classes: list[str],
+    layout_opt: Any,
+    scale_w: float,
+    image_size: tuple[int, int],
+) -> dict[str, Any]:
+    """构建单帧 OCR 归因全量调试数据，供 ``debug_session_derived.json`` 落地。
+
+    所有坐标统一使用 *OCR 实际图像空间*（``image_size``），与
+    ``metadata.json`` 中的手机原生分辨率（``screenshot.original_resolution``）
+    可能不同（采集端可能按 ``renxin.yaml`` 缩放后输出）。
+    """
+    iw, ih = int(image_size[0]), int(image_size[1])
+    now = float(screenshot.original_resolution.width)
+    noh = float(screenshot.original_resolution.height)
+    sx = iw / now if now > 0 else 1.0
+    sy = ih / noh if noh > 0 else 1.0
+    # 所有来自 metadata（手机原生空间）的坐标统一缩放到 OCR 图像空间
+    _remap_bbox = (
+        lambda raw: [int(raw[0] * sx), int(raw[1] * sy),
+                     int(raw[2] * sx), int(raw[3] * sy)]
+    ) if (abs(sx - 1.0) > 0.0001 or abs(sy - 1.0) > 0.0001) else (
+        lambda raw: list(map(int, raw))
+    )
+    _click_ctx = getattr(screenshot, "click_context", None)
+    user_click_area: Any = None
+    if _click_ctx is not None:
+        _coords = getattr(_click_ctx, "click_coords", None)
+        if _coords and len(_coords) >= 2:
+            _cx = int(_coords[0] * sx)
+            _cy = int(_coords[1] * sy)
+            user_click_area = [_cx, _cy, _cx + 2, _cy + 2]
+    debug: dict[str, Any] = {
+        "screen_size": {"width": iw, "height": ih},
+        "scale_w": round(float(iw) / 1080.0, 4),
+        "user_click_area_scaling": user_click_area,
+        "resume_thumb_bboxes_scaling": [
+            _remap_bbox(raw)
+            for raw in (getattr(screenshot, "resume_thumb_bboxes", None) or [])
+            if raw and len(raw) >= 4
+        ],
+        # 经过实际验证，简历卡片正常高度为 260–279 px（占 87%，中位数 273）
+    }
+    if layout_opt is not None:
+        _sb_debug = getattr(layout_opt, "speaker_bands", ())
+        debug["orphan_top_band"] = (
+            [int(ot[0]), int(ot[1])]
+            if (ot := layout_opt.orphan_top_band) is not None
+            else None
+        )
+        debug["speaker_bands"] = [
+            [int(b0), int(b1)] for b0, b1 in _sb_debug
+        ]
+        cb = layout_opt.content_bounds
+        debug["content_bounds"] = {
+            "y_top": int(cb.y_top),
+            "y_bottom_excl": int(cb.y_bottom_excl),
+        }
+        debug["no_avatars_all_orphan"] = bool(
+            getattr(layout_opt, "no_avatars_all_orphan", False)
+        )
+        block_items: list[dict[str, Any]] = []
+        for i, b in enumerate(blocks):
+            bb = b.bbox_xyxy
+            _by1, _by2 = float(bb[1]), float(bb[3])
+            bi = None
+            for _ix, (_b0, _b1) in enumerate(_sb_debug):
+                if _by2 > float(_b0) and _by1 < float(_b1):
+                    bi = _ix
+                    break
+            block_items.append({
+                "bbox_xyxy": list(map(int, bb)),
+                "text": (b.text or "").strip(),
+                "confidence": round(float(b.confidence), 4),
+                "class": classes[i] if i < len(classes) else "unknown",
+                "band": bi,
+            })
+        debug["blocks"] = block_items
+    else:
+        # 无 layout 时仅输出块信息（无 band）
+        debug["orphan_top_band"] = None
+        debug["speaker_bands"] = []
+        debug["content_bounds"] = None
+        debug["no_avatars_all_orphan"] = True
+        block_items: list[dict[str, Any]] = []
+        for i, b in enumerate(blocks):
+            bb = b.bbox_xyxy
+            block_items.append({
+                "bbox_xyxy": list(map(int, bb)),
+                "text": (b.text or "").strip(),
+                "confidence": round(float(b.confidence), 4),
+                "class": classes[i] if i < len(classes) else "unknown",
+                "band": None,
+            })
+        debug["blocks"] = block_items
+    return debug
+
+
+def extract_nicknames(
+    ocr_result: "OcrPageResult",
+    screenshot: "Screenshot",
+    *,
+    config: Optional[NicknameOcrConfig] = None,
+    png_path: Optional[Path] = None,
+) -> ChatSpeakerAttribution:
+    """Simplest viable nickname extraction from one chat-frame OCR result.
+
+    Preconditions:
+        - ``screenshot.type == "chat_message"`` (caller must enforce;
+          we assert).
+        - ``ocr_result.screenshot_id == screenshot.screenshot_id``
+          (we assert — defensive: catches accidental list mismatches
+          in the caller's loop).
+
+    Returns:
+        A frozen :class:`ChatSpeakerAttribution`（计数与段落经 PRD §7 后处理，见
+        :func:`_finalize_prd_attribution`）。
+
+    Side effects / I/O：
+        - 当 ``NicknameOcrConfig.use_prd_chat_vertical_bands`` 为真且提供
+          ``png_path`` 时会读 PNG 做术语§5 纵向筒分段（否则退化为 OCR 间隙启发式）。
+        - 仍为单帧纯函数语义：不写外部存储、不写日志。
+    """
+    assert screenshot.type == "chat_message", (
+        f"extract_nicknames expects chat_message type; got "
+        f"{screenshot.type!r} for screenshot_id={screenshot.screenshot_id!r}"
+    )
+    assert ocr_result.screenshot_id == screenshot.screenshot_id, (
+        f"screenshot_id mismatch: ocr_result={ocr_result.screenshot_id!r} "
+        f"vs screenshot={screenshot.screenshot_id!r}"
+    )
+
+    cfg = config or NicknameOcrConfig()
+    blocks = list(ocr_result.text_blocks)
+
+    if not blocks:
+        return ChatSpeakerAttribution(
+            screenshot_id=screenshot.screenshot_id,
+            resume_thumb_orphans=0,
+            speaker_body_segments=(),
+        )
+
+    original_width = screenshot.original_resolution.width
+    scale_w = float(original_width) / 1080.0
+    layout_opt = _load_prd_layout_optional(png_path, screenshot, config=cfg)
+    avatar_layout = _load_left_avatar_layout(png_path, screenshot)
+
+    # ── y 位置门控：丢弃聊天内容区上界以上 / 下界以下的 OCR 文本块 ──
+    if layout_opt is not None:
+        cb = layout_opt.content_bounds
+        blocks = [
+            b
+            for b in blocks
+            if cb.y_top <= _vertical_center(b) < cb.y_bottom_excl
+        ]
+        if not blocks:
+            return ChatSpeakerAttribution(
+                screenshot_id=screenshot.screenshot_id,
+                resume_thumb_orphans=0,
+                speaker_body_segments=(),
+            )
+
+    blocks = _prd_merge_adjacent_bubble_text_blocks(
+        blocks,
+        original_width=original_width,
+        config=cfg,
+    )
+    if not blocks:
+        return ChatSpeakerAttribution(
+            screenshot_id=screenshot.screenshot_id,
+            resume_thumb_orphans=0,
+            speaker_body_segments=(),
+        )
+
+    heights = [_block_height(b) for b in blocks if _block_height(b) > 0]
+    median_height = float(median(heights)) if heights else 1.0
+
+    classes = [
+        _classify(
+            b,
+            original_width=original_width,
+            config=cfg,
+            median_height=median_height,
+            avatar_layout=avatar_layout,
+        )
+        for b in blocks
+    ]
+    _apply_resume_thumb_block_mask(
+        blocks, classes, screenshot,
+        original_width=original_width,
+        screen_midline_ratio=cfg.screen_midline_ratio,
+    )
+    _apply_prd_nickname_bubble_separation(
+        blocks,
+        classes,
+        original_width=original_width,
+        config=cfg,
+        median_height=median_height,
+    )
+
+    if layout_opt is not None and getattr(layout_opt, "no_avatars_all_orphan", False):
+        bodies: list[str] = []
+        for i, b in enumerate(blocks):
+            if classes[i] == "drop":
+                continue
+            if b.confidence < cfg.min_confidence:
+                continue
+            stripped = _strip_placeholder_lines_from_body(b.text.strip())
+            if stripped:
+                bodies.append(stripped)
+        merged = "\n".join(bodies).strip()
+        claimed_indices: set[int] = set()
+        thumb_bindings, thumb_o, _thumb_excluded = _resume_thumb_bindings_and_orphans(
+            screenshot,
+            blocks,
+            classes,
+            claimed_indices,
+            (),
+            original_width=original_width,
+            config=cfg,
+            layout_opt=layout_opt,
+            scale_w=scale_w,
+            image_size=ocr_result.original_size,
+        )
+        for ei in _thumb_excluded:
+            if classes[ei] != "drop":
+                classes[ei] = "drop"
+        if not merged:
+            debug_d = _build_ocr_debug_dict(
+                screenshot, blocks, classes, layout_opt, scale_w,
+                ocr_result.original_size,
+            )
+            return ChatSpeakerAttribution(
+                screenshot_id=screenshot.screenshot_id,
+                resume_thumb_orphans=thumb_o,
+                resume_thumb_bindings=thumb_bindings,
+                speaker_body_segments=(),
+                ocr_debug=debug_d,
+            )
+        unattributed_seg = SpeakerBodySegment(
+            speaker_display=SPEAKER_DISPLAY_UNATTRIBUTED,
+            body_text=merged,
+            orphan=True,
+        )
+        no_av_attr = ChatSpeakerAttribution(
+            screenshot_id=screenshot.screenshot_id,
+            nicknames=(),
+            total_bubbles=0,
+            bubbles_with_nickname=0,
+            bubbles_owner=0,
+            bubbles_unknown=0,
+            resume_thumb_orphans=thumb_o,
+            resume_thumb_bindings=thumb_bindings,
+            speaker_body_segments=(unattributed_seg,),
+        )
+        debug_d = _build_ocr_debug_dict(
+            screenshot, blocks, classes, layout_opt, scale_w,
+            ocr_result.original_size,
+        )
+        no_av_attr_with_debug = dataclass_replace(no_av_attr, ocr_debug=debug_d)
+        result = _finalize_prd_attribution(no_av_attr_with_debug, config=cfg)
+        # _finalize_prd_attribution 内部构造新实例，debug 需显式带过
+        return dataclass_replace(result, ocr_debug=debug_d)
+
+    layout_active = (
+        layout_opt is not None and not getattr(layout_opt, "no_avatars_all_orphan", False)
+    )
+    nicknames_list: list[NicknameExtraction] = []
+    claimed_indices = set[int]()
+    bgr_guard = None
+    if png_path is not None:
+        try:
+            from processor.nickname_avatar_guard import load_png_bgr
+
+            bgr_guard = load_png_bgr(str(png_path))
+        except ImportError:
+            bgr_guard = None
+
+    for idx, klass in enumerate(classes):
+        if klass != "nickname_candidate":
+            continue
+        nick_block = blocks[idx]
+        if not _nickname_passes_avatar_guard(
+            bgr_guard=bgr_guard,
+            nick_block=nick_block,
+            avatar_layout=avatar_layout,
+            scale_w=scale_w,
+            original_width=original_width,
+            config=cfg,
+        ):
+            continue
+        nick_bottom = _block_bottom(nick_block)
+        bi_n: Optional[int] = None
+        if layout_active:
+            _sb_for_nick = getattr(layout_opt, "speaker_bands", ())
+            _ny1, _ny2 = float(nick_block.bbox_xyxy[1]), float(nick_block.bbox_xyxy[3])
+            for _idx, (_b0, _b1) in enumerate(_sb_for_nick):
+                if _ny2 > float(_b0) and _ny1 < float(_b1):
+                    bi_n = _idx
+                    break
+        followers: list[int] = []
+        for j in range(idx + 1, len(blocks)):
+            if j in claimed_indices:
+                continue
+            if classes[j] == "nickname_candidate":
+                break
+            if classes[j] != "bubble_text":
+                continue
+            bj = blocks[j]
+            if layout_active and bi_n is not None and bi_n >= 0:
+                _sb = getattr(layout_opt, "speaker_bands", ())
+                if bi_n < len(_sb):
+                    _band_y0, _band_y1 = float(_sb[bi_n][0]), float(_sb[bi_n][1])
+                    _bj_top, _bj_bot = float(bj.bbox_xyxy[1]), float(bj.bbox_xyxy[3])
+                    if not (_bj_bot > _band_y0 and _bj_top < _band_y1):
+                        break
+            if not _is_on_left_half(bj, original_width, cfg.screen_midline_ratio):
+                break
+            gap = _block_top(bj) - nick_bottom
+            if gap < 0 or gap > cfg.bubble_vertical_gap_max_px:
+                break
+            followers.append(j)
+            claimed_indices.add(j)
+            nick_bottom = _block_bottom(bj)
+
+        nicknames_list.append(
+            NicknameExtraction(
+                nickname=nick_block.text.strip(),
+                bbox_xyxy=nick_block.bbox_xyxy,
+                confidence=nick_block.confidence,
+                following_block_indices=tuple(followers),
+                nickname_block_index=idx,
+                band_index=bi_n,
+            ),
+        )
+
+    thumb_bindings, thumb_orphans, thumb_excluded = _resume_thumb_bindings_and_orphans(
+        screenshot,
+        blocks,
+        classes,
+        claimed_indices,
+        nicknames_list,
+        original_width=original_width,
+        config=cfg,
+        layout_opt=layout_opt,
+        scale_w=scale_w,
+        image_size=ocr_result.original_size,
+    )
+    # PRD §7(2)：Step C 中"去除"的 block 标记为 drop
+    for ei in thumb_excluded:
+        if classes[ei] != "drop":
+            classes[ei] = "drop"
+
+    body_segments = _speaker_body_segments_from_layout(
+        blocks,
+        classes,
+        tuple(nicknames_list),
+        claimed_indices,
+        original_width=original_width,
+        config=cfg,
+    )
+    bubbles_with_nickname = sum(
+        1
+        for s in body_segments
+        if (not s.orphan)
+        and (s.speaker_display or "").strip()
+        and s.speaker_display != _OWNER_SPEAKER_LABEL
+    )
+    bubbles_owner = sum(
+        1 for s in body_segments if s.speaker_display == _OWNER_SPEAKER_LABEL
+    )
+    bubbles_unknown = sum(1 for s in body_segments if s.orphan)
+    total_bubbles = len(body_segments)
+
+    base_attr = ChatSpeakerAttribution(
+        screenshot_id=screenshot.screenshot_id,
+        nicknames=tuple(nicknames_list),
+        total_bubbles=total_bubbles,
+        bubbles_with_nickname=bubbles_with_nickname,
+        bubbles_owner=bubbles_owner,
+        bubbles_unknown=bubbles_unknown,
+        resume_thumb_orphans=thumb_orphans,
+        resume_thumb_bindings=thumb_bindings,
+        speaker_body_segments=body_segments,
+    )
+    debug_d = _build_ocr_debug_dict(
+        screenshot, blocks, classes, layout_opt, scale_w,
+        ocr_result.original_size,
+    )
+    result = _finalize_prd_attribution(
+        base_attr,
+        config=cfg,
+        blocks=blocks,
+        layout_opt=layout_opt if layout_active else None,
+        scale_w=scale_w,
+    )
+    return dataclass_replace(result, ocr_debug=debug_d)
+
+
+__all__ = [
+    "NicknameOcrConfig",
+    "NicknameExtraction",
+    "ResumeThumbBinding",
+    "SpeakerBodySegment",
+    "ChatSpeakerAttribution",
+    "SPEAKER_DISPLAY_UNATTRIBUTED",
+    "extract_nicknames",
+    "first_attrib_verbatim_display_line",
+    "first_attrib_verbatim_display_line_and_bbox",
+]