@11agents/cli 0.1.23 → 0.1.25

package/mobile-runtime/python/src/device_control/metrics/tiktok_video_adb.py

@@ -0,0 +1,714 @@
+from __future__ import annotations
+
+import json
+import re
+import struct
+import time
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+from zoneinfo import ZoneInfo
+
+from device_control.adb import AdbClient, CommandResult
+from device_control.models import Device, TikTokVideoMetricsSnapshot, new_id, utc_now_iso
+from device_control.publishers import ui_helpers as ui
+from device_control.publishers.tiktok_adb import TIKTOK_PACKAGE
+
+
+BASE_SCREEN = (1080, 2245)
+VIDEO_INSIGHTS_TEXT_MARKERS = {
+    "More insights",
+    "View insights",
+    "Analytics",
+    "数据分析",
+    "更多数据",
+}
+VIDEO_MORE_MENU_TEXT_MARKERS = {
+    "More",
+    "More options",
+    "更多",
+    "更多选项",
+}
+PROFILE_PROMPT_TEXT_MARKERS = {
+    "Your avatar, your style",
+    "Create your TikTok avatar",
+}
+PROFILE_VIDEO_SCROLL_LIMIT = 12
+PROFILE_VIDEO_SCROLL_ADVANCE = 3
+
+
+@dataclass(frozen=True)
+class TikTokVideoMetricValues:
+    published_at: str = ""
+    published_at_raw: str = ""
+    video_views: int | None = None
+    likes: int | None = None
+    comments: int | None = None
+    shares: int | None = None
+    saves: int | None = None
+    total_play_time_seconds: int | None = None
+    total_play_time_raw: str = ""
+    average_watch_time_seconds: float | None = None
+    average_watch_time_raw: str = ""
+    completion_rate: float | None = None
+    completion_rate_raw: str = ""
+    new_followers: int | None = None
+    top_counters: dict[str, int | None] | None = None
+    raw: dict[str, Any] | None = None
+
+
+class TikTokVideoMetricsAdbCollector:
+    """Read-only ADB collector for one TikTok video's Studio analytics page."""
+
+    def __init__(self, adb: AdbClient, *, artifact_root: str | Path = "artifacts/screenshots") -> None:
+        self.adb = adb
+        self.artifact_root = Path(artifact_root)
+
+    def collect(
+        self,
+        device: Device,
+        *,
+        account_id: str,
+        video_order: int = 1,
+        resume_insights: bool = False,
+        manual_values: TikTokVideoMetricValues | None = None,
+    ) -> TikTokVideoMetricsSnapshot:
+        started_epoch = int(time.time())
+        started_at = _now_shanghai()
+        stamp = datetime.now(ZoneInfo("Asia/Shanghai")).strftime("%Y%m%d-%H%M%S")
+        run_dir = self.artifact_root / f"{device.device_id}-tiktok-video-metrics-{stamp}"
+        run_dir.mkdir(parents=True, exist_ok=True)
+        raw: dict[str, Any] = {
+            "resume_insights": resume_insights,
+            "video_order": video_order,
+            "metric_keys": [
+                "video_views",
+                "likes",
+                "comments",
+                "shares",
+                "saves",
+                "average_watch_time_seconds",
+                "completion_rate",
+            ],
+        }
+
+        try:
+            self._prepare_device(device)
+            if not resume_insights:
+                self._navigate_to_video_insights(device, run_dir, video_order=video_order)
+            width, height = self._screen_size(device)
+            self._scroll_insights_to_key_metrics_top(device, run_dir, width, height)
+
+            screenshot_path = run_dir / "video-insights.png"
+            ui_dump_path = run_dir / "video-insights.xml"
+            self._ok(self.adb.screenshot(device.adb_serial, screenshot_path), "capture TikTok video insights screenshot")
+            dump = self.adb.dump_ui(device.adb_serial, ui_dump_path)
+            if not dump.ok:
+                ui_dump_path = Path("")
+            width, height = _png_size(screenshot_path) or (width, height)
+            raw["screen_size"] = {"width": width, "height": height}
+
+            ended_epoch = int(time.time())
+            snapshot = self._build_snapshot(
+                account_id=account_id,
+                device=device,
+                video_order=video_order,
+                manual_values=manual_values,
+                screenshot_path=screenshot_path,
+                ui_dump_path=ui_dump_path,
+                run_dir=run_dir,
+                started_at=started_at,
+                ended_at=_now_shanghai(),
+                duration_seconds=ended_epoch - started_epoch,
+                raw=raw,
+            )
+            return snapshot
+        except Exception as exc:
+            failure_shot = run_dir / "failed.png"
+            self.adb.screenshot(device.adb_serial, failure_shot)
+            ended_epoch = int(time.time())
+            return TikTokVideoMetricsSnapshot(
+                snapshot_id=new_id("tkvideo"),
+                platform="tiktok",
+                account_id=account_id,
+                device_id=device.device_id,
+                fetched_at=utc_now_iso(),
+                source="tiktok_video_insights_adb",
+                status="failed",
+                video_order=video_order,
+                screenshot_path=str(failure_shot),
+                artifact_dir=str(run_dir),
+                started_at=started_at,
+                ended_at=_now_shanghai(),
+                duration_seconds=ended_epoch - started_epoch,
+                raw={**raw, "error": str(exc), "failure_screenshot_path": str(failure_shot)},
+            )
+
+    def _build_snapshot(
+        self,
+        *,
+        account_id: str,
+        device: Device,
+        video_order: int,
+        manual_values: TikTokVideoMetricValues | None,
+        screenshot_path: Path,
+        ui_dump_path: Path,
+        run_dir: Path,
+        started_at: str,
+        ended_at: str,
+        duration_seconds: int,
+        raw: dict[str, Any],
+    ) -> TikTokVideoMetricsSnapshot:
+        if manual_values is None:
+            return TikTokVideoMetricsSnapshot(
+                snapshot_id=new_id("tkvideo"),
+                platform="tiktok",
+                account_id=account_id,
+                device_id=device.device_id,
+                fetched_at=utc_now_iso(),
+                source="tiktok_video_insights_adb",
+                status="needs_human",
+                video_order=video_order,
+                screenshot_path=str(screenshot_path),
+                ui_dump_path=str(ui_dump_path),
+                artifact_dir=str(run_dir),
+                started_at=started_at,
+                ended_at=ended_at,
+                duration_seconds=duration_seconds,
+                raw={**raw, "extraction_status": "manual_values_required"},
+            )
+
+        combined_raw = dict(manual_values.raw or {})
+        combined_raw.update(raw)
+        combined_raw["extraction_status"] = "manual_values_recorded"
+        if manual_values.top_counters:
+            combined_raw["top_counters"] = manual_values.top_counters
+        snapshot = TikTokVideoMetricsSnapshot(
+            snapshot_id=new_id("tkvideo"),
+            platform="tiktok",
+            account_id=account_id,
+            device_id=device.device_id,
+            fetched_at=utc_now_iso(),
+            source="tiktok_video_insights_adb",
+            status="collected",
+            published_at=manual_values.published_at,
+            published_at_raw=manual_values.published_at_raw,
+            video_order=video_order,
+            video_views=manual_values.video_views,
+            likes=manual_values.likes,
+            comments=manual_values.comments,
+            shares=manual_values.shares,
+            saves=manual_values.saves,
+            total_play_time_seconds=manual_values.total_play_time_seconds,
+            total_play_time_raw=manual_values.total_play_time_raw,
+            average_watch_time_seconds=manual_values.average_watch_time_seconds,
+            average_watch_time_raw=manual_values.average_watch_time_raw,
+            completion_rate=manual_values.completion_rate,
+            completion_rate_raw=manual_values.completion_rate_raw,
+            new_followers=manual_values.new_followers,
+            screenshot_path=str(screenshot_path),
+            ui_dump_path=str(ui_dump_path),
+            artifact_dir=str(run_dir),
+            started_at=started_at,
+            ended_at=ended_at,
+            duration_seconds=duration_seconds,
+            raw=combined_raw,
+        )
+        if not snapshot.has_key_metrics():
+            snapshot.status = "needs_human"
+        return snapshot
+
+    def _prepare_device(self, device: Device) -> None:
+        self.adb.wake(device.adb_serial)
+        time.sleep(0.5)
+
+    def _scroll_insights_to_key_metrics_top(self, device: Device, run_dir: Path, width: int, height: int) -> None:
+        for index in range(3):
+            self.adb.swipe(
+                device.adb_serial,
+                width // 2,
+                int(height * 0.40),
+                width // 2,
+                int(height * 0.82),
+                450,
+            )
+            time.sleep(0.8)
+            self.adb.screenshot(device.adb_serial, run_dir / f"scroll-top-{index + 1}.png")
+
+    def _navigate_to_video_insights(self, device: Device, run_dir: Path, *, video_order: int) -> None:
+        width, height = self._screen_size(device)
+        self.adb.shell(device.adb_serial, "am", "force-stop", TIKTOK_PACKAGE)
+        time.sleep(1)
+        self._ok(self.adb.launch_package(device.adb_serial, TIKTOK_PACKAGE), "launch TikTok")
+        time.sleep(5)
+        self._tap(device, int(width * 0.92), int(height * 0.96), "open profile tab")
+        time.sleep(3)
+        self.adb.screenshot(device.adb_serial, run_dir / "profile.png")
+        self._dismiss_profile_prompt_if_present(device, run_dir, width, height)
+        self._select_profile_posts_tab(device, run_dir, width, height)
+
+        self._open_profile_video_by_order(device, run_dir, width, height, video_order)
+        time.sleep(3)
+        self.adb.screenshot(device.adb_serial, run_dir / "video-open.png")
+        self._open_video_insights_from_video_page(device, run_dir, width, height)
+
+    def _open_video_insights_from_video_page(
+        self,
+        device: Device,
+        run_dir: Path,
+        width: int,
+        height: int,
+    ) -> None:
+        video_root = self._dump_or_none(device, run_dir / "video-open.xml")
+        if video_root is not None and self._tap_visible_video_insights(device, video_root, width, height):
+            time.sleep(4)
+            self.adb.screenshot(device.adb_serial, run_dir / "after-more-insights.png")
+            return
+        if self._tap_visible_video_insights_fallback(device, run_dir, width, height):
+            return
+
+        self._open_video_more_menu(device, run_dir, width, height, video_root)
+        time.sleep(2)
+        self.adb.screenshot(device.adb_serial, run_dir / "video-more-menu.png")
+        root = self._dump_or_none(device, run_dir / "video-more-menu.xml")
+        if root is not None and ui.tap_first(
+            self.adb,
+            device,
+            root,
+            partial_texts={"数据分析", "Analytics", "More insights", "更多数据"},
+            sleep_s=4,
+        ):
+            return
+        self.adb.screenshot(device.adb_serial, run_dir / "video-analytics-entry-missing.png")
+        raise RuntimeError("TikTok video analytics entry was not found after opening the video more menu")
+
+    def _tap_visible_video_insights(self, device: Device, root, width: int, height: int) -> bool:
+        node = _find_video_insights_button(root, width, height)
+        if node is not None:
+            ui.tap_node(self.adb, device, node, sleep_s=0)
+            return True
+        if not _has_video_insights_text(root):
+            return False
+        self._tap(device, int(width * 0.82), int(height * 0.945), "open visible More insights button fallback")
+        return True
+
+    def _tap_visible_video_insights_fallback(
+        self,
+        device: Device,
+        run_dir: Path,
+        width: int,
+        height: int,
+    ) -> bool:
+        self._tap(device, int(width * 0.82), int(height * 0.955), "open lower-right More insights fallback")
+        time.sleep(4)
+        self.adb.screenshot(device.adb_serial, run_dir / "after-more-insights.png")
+        # TikTok renders this analytics page as a Spark/WebView surface on D05, so
+        # the UI dump may not expose visible labels like "Key metrics".
+        return True
+
+    def _open_video_more_menu(
+        self,
+        device: Device,
+        run_dir: Path,
+        width: int,
+        height: int,
+        video_root,
+    ) -> None:
+        node = _find_video_more_menu_button(video_root, width, height) if video_root is not None else None
+        if node is not None:
+            ui.tap_node(self.adb, device, node, sleep_s=0)
+            return
+
+        # D05/OnePlus 8 owned-video layout: the three-dot action is on the right rail
+        # above the bottom music/avatar button. The previous lower tap hit the sound page.
+        self._tap(device, int(width * 0.92), int(height * 0.77), "open video more menu fallback")
+
+    def _dismiss_profile_prompt_if_present(self, device: Device, run_dir: Path, width: int, height: int) -> None:
+        root = self._dump_or_none(device, run_dir / "profile-prompt-check.xml")
+        if root is None or not ui.contains_any(ui.all_text(root), PROFILE_PROMPT_TEXT_MARKERS):
+            return
+        node = _find_profile_prompt_close_button(root, width, height)
+        if node is not None:
+            ui.tap_node(self.adb, device, node, sleep_s=1.5)
+        else:
+            self._tap(device, int(width * 0.85), int(height * 0.47), "close TikTok profile prompt fallback")
+            time.sleep(1.5)
+        self.adb.screenshot(device.adb_serial, run_dir / "profile-prompt-closed.png")
+
+    def _select_profile_posts_tab(self, device: Device, run_dir: Path, width: int, height: int) -> None:
+        root = self._dump_or_none(device, run_dir / "profile-posts-tab-check.xml")
+        if root is not None and _profile_posts_tab_is_selected(root):
+            self.adb.screenshot(device.adb_serial, run_dir / "profile-posts-tab.png")
+            return
+        node = _find_profile_posts_tab(root, width, height) if root is not None else None
+        if node is not None:
+            ui.tap_node(self.adb, device, node, sleep_s=1)
+        else:
+            self._tap(device, int(width * 0.11), int(height * 0.50), "select profile posts tab fallback")
+            time.sleep(1)
+        self.adb.screenshot(device.adb_serial, run_dir / "profile-posts-tab.png")
+
+    def _open_profile_video_by_order(
+        self,
+        device: Device,
+        run_dir: Path,
+        width: int,
+        height: int,
+        video_order: int,
+    ) -> None:
+        index = video_order - 1
+        if index < 0:
+            raise ValueError("video_order must be >= 1")
+        visible_start_order = 1
+        last_layout_signature: tuple[tuple[int, int, int, int, str], ...] | None = None
+        last_content_signature: tuple[str, ...] | None = None
+        visible_count = 0
+        for attempt in range(PROFILE_VIDEO_SCROLL_LIMIT + 1):
+            xml_name = "profile-video-grid.xml" if attempt == 0 else f"profile-video-grid-scroll-{attempt}.xml"
+            root = self._dump_or_none(device, run_dir / xml_name)
+            nodes = _find_profile_video_nodes(root, width, height) if root is not None else []
+            visible_count = len(nodes)
+            layout_signature = _profile_video_nodes_signature(nodes)
+            content_signature = _profile_video_nodes_content_signature(nodes)
+            if last_content_signature is not None and content_signature != last_content_signature:
+                visible_start_order += PROFILE_VIDEO_SCROLL_ADVANCE
+            if last_layout_signature is not None and layout_signature == last_layout_signature:
+                break
+            if root is not None and _profile_all_posts_previewed(root):
+                last_visible_order = visible_start_order + len(nodes) - 1
+                if video_order > last_visible_order:
+                    break
+
+            local_index = video_order - visible_start_order
+            if 0 <= local_index < len(nodes):
+                ui.tap_node(self.adb, device, nodes[local_index], sleep_s=0)
+                return
+
+            if attempt >= PROFILE_VIDEO_SCROLL_LIMIT:
+                break
+            last_layout_signature = layout_signature
+            last_content_signature = content_signature
+            self._scroll_profile_video_grid(device, run_dir, width, height, attempt + 1)
+
+        self.adb.screenshot(device.adb_serial, run_dir / "profile-video-not-visible.png")
+        raise RuntimeError(
+            f"profile video order {video_order} is not visible; "
+            f"visible_start_order={visible_start_order} visible_video_count={visible_count}"
+        )
+
+    def _scroll_profile_video_grid(
+        self,
+        device: Device,
+        run_dir: Path,
+        width: int,
+        height: int,
+        attempt: int,
+    ) -> None:
+        self.adb.swipe(
+            device.adb_serial,
+            width // 2,
+            int(height * 0.84),
+            width // 2,
+            int(height * 0.63),
+            450,
+        )
+        time.sleep(1.2)
+        self.adb.screenshot(device.adb_serial, run_dir / f"profile-video-grid-scroll-{attempt}.png")
+
+    def _screen_size(self, device: Device) -> tuple[int, int]:
+        result = self.adb.shell(device.adb_serial, "wm", "size")
+        if result.ok:
+            for part in result.stdout.split():
+                if "x" not in part:
+                    continue
+                left, right = part.split("x", 1)
+                if left.isdigit() and right.isdigit():
+                    return int(left), int(right)
+        return BASE_SCREEN
+
+    def _tap(self, device: Device, x: int, y: int, label: str) -> None:
+        self._ok(self.adb.tap(device.adb_serial, x, y), label)
+
+    def _dump_or_none(self, device: Device, path: Path):
+        import xml.etree.ElementTree as ET
+
+        for attempt in range(3):
+            result = self.adb.dump_ui(device.adb_serial, path)
+            if result.ok:
+                try:
+                    return ET.parse(path).getroot()
+                except Exception:
+                    pass
+            if attempt < 2:
+                time.sleep(0.6)
+        return None
+
+    def _ok(self, result: CommandResult, label: str) -> None:
+        if not result.ok:
+            raise RuntimeError(f"{label} failed: {result.stderr or result.stdout}")
+
+
+def _find_video_insights_button(root, width: int, height: int):
+    candidates = []
+    for node in root.iter("node"):
+        if not ui.is_visible(node):
+            continue
+        text = node.attrib.get("text", "")
+        desc = node.attrib.get("content-desc", "")
+        haystack = f"{text}\n{desc}".lower()
+        if not any(marker.lower() in haystack for marker in VIDEO_INSIGHTS_TEXT_MARKERS):
+            continue
+        value = ui.bounds(node)
+        if not value:
+            continue
+        left, top, right, bottom = value
+        # The direct owned-video insights pill is in the lower-right region.
+        # This filter avoids matching unrelated Studio or profile labels.
+        if left < int(width * 0.45) or top < int(height * 0.72):
+            continue
+        candidates.append(node)
+    sorted_candidates = ui.sorted_visible_nodes(candidates)
+    return sorted_candidates[0] if sorted_candidates else None
+
+
+def _has_video_insights_text(root) -> bool:
+    text = ui.all_text(root)
+    return ui.contains_any(text, VIDEO_INSIGHTS_TEXT_MARKERS)
+
+
+def _find_video_more_menu_button(root, width: int, height: int):
+    candidates = []
+    for node in root.iter("node"):
+        if not ui.is_visible(node):
+            continue
+        text = node.attrib.get("text", "")
+        desc = node.attrib.get("content-desc", "")
+        haystack = f"{text}\n{desc}".lower()
+        if not any(marker.lower() in haystack for marker in VIDEO_MORE_MENU_TEXT_MARKERS):
+            continue
+        if any(marker.lower() in haystack for marker in VIDEO_INSIGHTS_TEXT_MARKERS):
+            continue
+        value = ui.bounds(node)
+        if not value:
+            continue
+        left, top, right, bottom = value
+        center_x = (left + right) // 2
+        center_y = (top + bottom) // 2
+        if center_x < int(width * 0.78):
+            continue
+        if center_y < int(height * 0.45) or center_y > int(height * 0.88):
+            continue
+        candidates.append(node)
+    sorted_candidates = ui.sorted_visible_nodes(candidates)
+    return sorted_candidates[-1] if sorted_candidates else None
+
+
+def _find_profile_prompt_close_button(root, width: int, height: int):
+    candidates = []
+    for node in root.iter("node"):
+        if not ui.is_visible(node) or node.attrib.get("clickable") != "true":
+            continue
+        value = ui.bounds(node)
+        if not value:
+            continue
+        left, top, right, bottom = value
+        center_x = (left + right) // 2
+        center_y = (top + bottom) // 2
+        if center_x < int(width * 0.75):
+            continue
+        if center_y < int(height * 0.35) or center_y > int(height * 0.65):
+            continue
+        candidates.append(node)
+    sorted_candidates = ui.sorted_visible_nodes(candidates)
+    return sorted_candidates[0] if sorted_candidates else None
+
+
+def _profile_posts_tab_is_selected(root) -> bool:
+    for node in root.iter("node"):
+        desc = node.attrib.get("content-desc", "")
+        if desc not in {"Videos", "Posts", "视频", "作品"}:
+            continue
+        if node.attrib.get("selected") == "true":
+            return True
+    return False
+
+
+def _find_profile_posts_tab(root, width: int, height: int):
+    candidates = []
+    for node in root.iter("node"):
+        if not ui.is_visible(node) or node.attrib.get("clickable") != "true":
+            continue
+        value = ui.bounds(node)
+        if not value:
+            continue
+        left, top, right, bottom = value
+        center_x = (left + right) // 2
+        center_y = (top + bottom) // 2
+        if center_x > int(width * 0.22):
+            continue
+        if center_y < int(height * 0.42) or center_y > int(height * 0.62):
+            continue
+        candidates.append(node)
+    sorted_candidates = ui.sorted_visible_nodes(candidates)
+    return sorted_candidates[0] if sorted_candidates else None
+
+
+def _find_profile_video_nodes(root, width: int, height: int):
+    nodes = []
+    for node in root.iter("node"):
+        if not ui.is_visible(node) or node.attrib.get("clickable") != "true":
+            continue
+        resource_id = node.attrib.get("resource-id", "")
+        if resource_id and not resource_id.endswith(":id/ekl"):
+            continue
+        if resource_id.endswith(":id/ekl") and node.attrib.get("long-clickable") != "true":
+            continue
+        value = ui.bounds(node)
+        if not value:
+            continue
+        left, top, right, bottom = value
+        node_width = right - left
+        node_height = bottom - top
+        if top < int(height * 0.25):
+            continue
+        if bottom > int(height * 0.93):
+            continue
+        if node_width < int(width * 0.20) or node_height < int(height * 0.10):
+            continue
+        if node_width > int(width * 0.38):
+            continue
+        nodes.append(node)
+    return ui.sorted_visible_nodes(nodes)
+
+
+def _profile_video_nodes_signature(nodes) -> tuple[tuple[int, int, int, int, str], ...]:
+    signature = []
+    for node in nodes:
+        left, top, right, bottom = ui.bounds(node) or (0, 0, 0, 0)
+        signature.append((left, top, right, bottom, _node_text_signature(node)))
+    return tuple(signature)
+
+
+def _profile_video_nodes_content_signature(nodes) -> tuple[str, ...]:
+    return tuple(_node_text_signature(node) for node in nodes)
+
+
+def _node_text_signature(node) -> str:
+    parts: list[str] = []
+    for child in node.iter("node"):
+        text = child.attrib.get("text", "")
+        desc = child.attrib.get("content-desc", "")
+        if text:
+            parts.append(text)
+        if desc:
+            parts.append(desc)
+    return "|".join(parts)
+
+
+def _profile_all_posts_previewed(root) -> bool:
+    return ui.contains_any(ui.all_text(root), {"You've previewed all posts", "已浏览所有作品"})
+
+
+def parse_manual_video_values_json(raw_json: str) -> TikTokVideoMetricValues | None:
+    if not raw_json.strip():
+        return None
+    loaded = json.loads(raw_json)
+    if not isinstance(loaded, dict):
+        raise ValueError("manual video values JSON must be an object")
+    total_play_time_raw = str(loaded.get("total_play_time_raw") or loaded.get("total_play_time") or "")
+    average_watch_time_raw = str(loaded.get("average_watch_time_raw") or loaded.get("average_watch_time") or "")
+    completion_rate_raw = str(loaded.get("completion_rate_raw") or loaded.get("completion_rate") or "")
+    top_counters = dict(loaded.get("top_counters") or {})
+    return TikTokVideoMetricValues(
+        published_at=str(loaded.get("published_at", "")),
+        published_at_raw=str(loaded.get("published_at_raw") or loaded.get("published_at") or ""),
+        video_views=_optional_int(loaded.get("video_views", loaded.get("views", top_counters.get("views")))),
+        likes=_optional_int(loaded.get("likes", top_counters.get("likes"))),
+        comments=_optional_int(loaded.get("comments", top_counters.get("comments"))),
+        shares=_optional_int(loaded.get("shares", top_counters.get("shares"))),
+        saves=_optional_int(loaded.get("saves", top_counters.get("saves"))),
+        total_play_time_seconds=_optional_int(
+            loaded.get("total_play_time_seconds"),
+            default=parse_duration_seconds(total_play_time_raw),
+        ),
+        total_play_time_raw=total_play_time_raw,
+        average_watch_time_seconds=_optional_float(
+            loaded.get("average_watch_time_seconds"),
+            default=parse_seconds_value(average_watch_time_raw),
+        ),
+        average_watch_time_raw=average_watch_time_raw,
+        completion_rate=_optional_float(
+            loaded.get("completion_rate"),
+            default=parse_percent_value(completion_rate_raw),
+        ),
+        completion_rate_raw=completion_rate_raw,
+        new_followers=_optional_int(loaded.get("new_followers")),
+        top_counters={
+            "views": _optional_int(loaded.get("video_views", loaded.get("views", top_counters.get("views")))),
+            "likes": _optional_int(loaded.get("likes", top_counters.get("likes"))),
+            "comments": _optional_int(loaded.get("comments", top_counters.get("comments"))),
+            "shares": _optional_int(loaded.get("shares", top_counters.get("shares"))),
+            "saves": _optional_int(loaded.get("saves", top_counters.get("saves"))),
+        },
+        raw=dict(loaded.get("raw") or {}),
+    )
+
+
+def parse_duration_seconds(value: str) -> int | None:
+    if not value.strip():
+        return None
+    text = value.strip()
+    total = 0
+    matched = False
+    for pattern, multiplier in (
+        (r"(\d+)\s*(?:小时|h|hour|hours)", 3600),
+        (r"(\d+)\s*(?:分钟|m|min|minute|minutes)", 60),
+        (r"(\d+)\s*(?:秒|s|sec|second|seconds)", 1),
+    ):
+        match = re.search(pattern, text, flags=re.IGNORECASE)
+        if match:
+            total += int(match.group(1)) * multiplier
+            matched = True
+    if matched:
+        return total
+    if text.isdigit():
+        return int(text)
+    return None
+
+
+def parse_seconds_value(value: str) -> float | None:
+    match = re.search(r"(\d+(?:\.\d+)?)", value)
+    return float(match.group(1)) if match else None
+
+
+def parse_percent_value(value: str) -> float | None:
+    match = re.search(r"(\d+(?:\.\d+)?)", value)
+    return float(match.group(1)) / 100 if match else None
+
+
+def _png_size(path: Path) -> tuple[int, int] | None:
+    try:
+        with path.open("rb") as handle:
+            header = handle.read(24)
+        if len(header) < 24 or header[:8] != b"\x89PNG\r\n\x1a\n":
+            return None
+        return struct.unpack(">II", header[16:24])
+    except Exception:
+        return None
+
+
+def _optional_int(value: Any, *, default: int | None = None) -> int | None:
+    if value in (None, ""):
+        return default
+    return int(value)
+
+
+def _optional_float(value: Any, *, default: float | None = None) -> float | None:
+    if value in (None, ""):
+        return default
+    return float(value)
+
+
+def _now_shanghai() -> str:
+    return datetime.now(ZoneInfo("Asia/Shanghai")).replace(microsecond=0).isoformat()