@11agents/cli 0.1.24 → 0.1.25

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

@@ -0,0 +1,367 @@
+from __future__ import annotations
+
+import json
+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, TikTokAccountMetricsPeriod, TikTokAccountMetricsSnapshot, new_id, utc_now_iso
+from device_control.publishers import ui_helpers as ui
+from device_control.publishers.tiktok_adb import TIKTOK_PACKAGE
+
+
+ACCOUNT_PERIODS: dict[str, int] = {
+    "7d": 7,
+    "28d": 28,
+    "60d": 60,
+}
+
+ACCOUNT_METRIC_KEYS = ("video_views", "profile_views", "total_likes", "total_comments", "shares")
+
+# Coordinates calibrated from a 1080x2245 TikTok Studio analytics screenshot on D01.
+BASE_SCREEN = (1080, 2245)
+PERIOD_TAB_COORDS = {
+    "7d": (121, 473),
+    "28d": (308, 473),
+    "60d": (492, 473),
+}
+
+
+@dataclass(frozen=True)
+class TikTokAccountMetricValues:
+    video_views: int | None = None
+    profile_views: int | None = None
+    total_likes: int | None = None
+    total_comments: int | None = None
+    shares: int | None = None
+    date_range: str = ""
+    raw: dict[str, Any] | None = None
+
+
+class TikTokAccountMetricsAdbCollector:
+    """Read-only ADB collector for TikTok Studio account overview metrics."""
+
+    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,
+        periods: list[str] | None = None,
+        resume_analytics: bool = False,
+        manual_values: dict[str, TikTokAccountMetricValues] | None = None,
+    ) -> TikTokAccountMetricsSnapshot:
+        requested = _normalize_periods(periods)
+        manual_values = manual_values or {}
+        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-account-metrics-{stamp}"
+        run_dir.mkdir(parents=True, exist_ok=True)
+
+        raw: dict[str, Any] = {
+            "resume_analytics": resume_analytics,
+            "requested_periods": requested,
+            "metric_keys": list(ACCOUNT_METRIC_KEYS),
+        }
+        periods_out: dict[str, TikTokAccountMetricsPeriod] = {}
+
+        try:
+            self._prepare_device(device)
+            if not resume_analytics:
+                self._navigate_to_account_analytics(device, run_dir)
+
+            initial_shot = run_dir / "initial.png"
+            self._ok(self.adb.screenshot(device.adb_serial, initial_shot), "capture initial TikTok analytics screenshot")
+            width, height = _png_size(initial_shot) or BASE_SCREEN
+            raw["screen_size"] = {"width": width, "height": height}
+            raw["initial_screenshot_path"] = str(initial_shot)
+            self._scroll_overview_to_metrics_top(device, run_dir, width, height)
+
+            for period_key in requested:
+                x, y = _scale_coord(PERIOD_TAB_COORDS[period_key], width, height)
+                self._ok(self.adb.tap(device.adb_serial, x, y), f"tap TikTok analytics period {period_key}")
+                time.sleep(2)
+
+                screenshot_path = run_dir / f"{period_key}.png"
+                ui_path = run_dir / f"{period_key}.xml"
+                self._ok(self.adb.screenshot(device.adb_serial, screenshot_path), f"capture {period_key} screenshot")
+                dump = self.adb.dump_ui(device.adb_serial, ui_path)
+                if not dump.ok:
+                    ui_path = Path("")
+
+                value = manual_values.get(period_key)
+                periods_out[period_key] = self._build_period(
+                    period_key,
+                    value,
+                    screenshot_path=screenshot_path,
+                    ui_dump_path=ui_path,
+                    tap={"x": x, "y": y},
+                )
+
+            ended_epoch = int(time.time())
+            status = "collected" if all(period.has_all_metrics() for period in periods_out.values()) else "needs_human"
+            raw["extraction_status"] = (
+                "manual_values_recorded" if status == "collected" else "manual_values_required"
+            )
+            return TikTokAccountMetricsSnapshot(
+                snapshot_id=new_id("tkacct"),
+                platform="tiktok",
+                account_id=account_id,
+                device_id=device.device_id,
+                fetched_at=utc_now_iso(),
+                source="tiktok_studio_adb",
+                status=status,
+                periods=periods_out,
+                artifact_dir=str(run_dir),
+                started_at=started_at,
+                ended_at=_now_shanghai(),
+                duration_seconds=ended_epoch - started_epoch,
+                raw=raw,
+            )
+        except Exception as exc:
+            failure_shot = run_dir / "failed.png"
+            self.adb.screenshot(device.adb_serial, failure_shot)
+            ended_epoch = int(time.time())
+            return TikTokAccountMetricsSnapshot(
+                snapshot_id=new_id("tkacct"),
+                platform="tiktok",
+                account_id=account_id,
+                device_id=device.device_id,
+                fetched_at=utc_now_iso(),
+                source="tiktok_studio_adb",
+                status="failed",
+                periods=periods_out,
+                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_period(
+        self,
+        period_key: str,
+        value: TikTokAccountMetricValues | None,
+        *,
+        screenshot_path: Path,
+        ui_dump_path: Path,
+        tap: dict[str, int],
+    ) -> TikTokAccountMetricsPeriod:
+        raw = {"tap": tap}
+        if value is None:
+            raw["extraction_status"] = "manual_values_required"
+            return TikTokAccountMetricsPeriod(
+                period_key=period_key,
+                period_days=ACCOUNT_PERIODS[period_key],
+                screenshot_path=str(screenshot_path),
+                ui_dump_path=str(ui_dump_path),
+                extraction_method="manual_required",
+                raw=raw,
+            )
+
+        raw.update(dict(value.raw or {}))
+        raw["extraction_status"] = "manual_values_recorded"
+        return TikTokAccountMetricsPeriod(
+            period_key=period_key,
+            period_days=ACCOUNT_PERIODS[period_key],
+            date_range=value.date_range,
+            video_views=value.video_views,
+            profile_views=value.profile_views,
+            total_likes=value.total_likes,
+            total_comments=value.total_comments,
+            shares=value.shares,
+            screenshot_path=str(screenshot_path),
+            ui_dump_path=str(ui_dump_path),
+            extraction_method="manual",
+            raw=raw,
+        )
+
+    def _prepare_device(self, device: Device) -> None:
+        self.adb.wake(device.adb_serial)
+        time.sleep(0.5)
+        self.adb.swipe(device.adb_serial, 540, 1850, 540, 550, 350)
+        time.sleep(0.5)
+
+    def _scroll_overview_to_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.42),
+                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_account_analytics(self, device: Device, run_dir: Path) -> None:
+        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_ratio(device, 0.91, 0.96, "open TikTok profile tab")
+        time.sleep(3)
+        self.adb.screenshot(device.adb_serial, run_dir / "profile.png")
+
+        self._tap_ratio(device, 0.94, 0.055, "open TikTok profile menu")
+        time.sleep(2)
+        menu_xml = run_dir / "profile-menu.xml"
+        root = self._dump_or_none(device, menu_xml)
+        if root is not None and ui.tap_first(
+            self.adb,
+            device,
+            root,
+            partial_texts={"TikTok Studio", "创作者工具", "创作者中心"},
+            sleep_s=3,
+        ):
+            pass
+        else:
+            self._tap_ratio(device, 0.25, 0.32, "open TikTok Studio fallback")
+            time.sleep(3)
+        self.adb.screenshot(device.adb_serial, run_dir / "tiktok-studio.png")
+
+        studio_xml = run_dir / "tiktok-studio.xml"
+        root = self._dump_or_none(device, studio_xml)
+        if root is not None and ui.tap_first(
+            self.adb,
+            device,
+            root,
+            partial_texts={"数据分析", "Analytics"},
+            sleep_s=4,
+        ):
+            return
+        self._tap_ratio(device, 0.20, 0.32, "open TikTok Studio analytics fallback")
+        time.sleep(4)
+
+    def _tap_ratio(self, device: Device, x_ratio: float, y_ratio: float, label: str) -> None:
+        width, height = self._screen_size(device)
+        self._ok(self.adb.tap(device.adb_serial, int(width * x_ratio), int(height * y_ratio)), label)
+
+    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 _dump_or_none(self, device: Device, path: Path):
+        result = self.adb.dump_ui(device.adb_serial, path)
+        if not result.ok:
+            return None
+        try:
+            import xml.etree.ElementTree as ET
+
+            return ET.parse(path).getroot()
+        except Exception:
+            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 parse_manual_values_json(raw_json: str) -> dict[str, TikTokAccountMetricValues]:
+    if not raw_json.strip():
+        return {}
+    loaded = json.loads(raw_json)
+    if not isinstance(loaded, dict):
+        raise ValueError("manual values JSON must be an object keyed by period")
+
+    parsed: dict[str, TikTokAccountMetricValues] = {}
+    for raw_period, raw_values in loaded.items():
+        period = normalize_period_key(str(raw_period))
+        if period not in ACCOUNT_PERIODS:
+            raise ValueError(f"unsupported TikTok account metrics period: {raw_period}")
+        if not isinstance(raw_values, dict):
+            raise ValueError(f"manual values for {raw_period} must be an object")
+        parsed[period] = TikTokAccountMetricValues(
+            video_views=_optional_int(raw_values.get("video_views")),
+            profile_views=_optional_int(raw_values.get("profile_views")),
+            total_likes=_optional_int(raw_values.get("total_likes")),
+            total_comments=_optional_int(raw_values.get("total_comments")),
+            shares=_optional_int(raw_values.get("shares")),
+            date_range=str(raw_values.get("date_range", "")),
+            raw=dict(raw_values.get("raw") or {}),
+        )
+    return parsed
+
+
+def normalize_period_key(value: str) -> str:
+    key = value.strip().lower().replace(" ", "")
+    aliases = {
+        "7": "7d",
+        "7d": "7d",
+        "7day": "7d",
+        "7days": "7d",
+        "7天": "7d",
+        "28": "28d",
+        "28d": "28d",
+        "28day": "28d",
+        "28days": "28d",
+        "28天": "28d",
+        "60": "60d",
+        "60d": "60d",
+        "60day": "60d",
+        "60days": "60d",
+        "60天": "60d",
+    }
+    return aliases.get(key, key)
+
+
+def _normalize_periods(periods: list[str] | None) -> list[str]:
+    if not periods:
+        return list(ACCOUNT_PERIODS)
+    normalized: list[str] = []
+    for period in periods:
+        key = normalize_period_key(period)
+        if key not in ACCOUNT_PERIODS:
+            raise ValueError(f"unsupported TikTok account metrics period: {period}")
+        if key not in normalized:
+            normalized.append(key)
+    return normalized
+
+
+def _scale_coord(coord: tuple[int, int], width: int, height: int) -> tuple[int, int]:
+    base_width, base_height = BASE_SCREEN
+    x, y = coord
+    return round(x / base_width * width), round(y / base_height * height)
+
+
+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) -> int | None:
+    if value in (None, ""):
+        return None
+    return int(value)
+
+
+def _now_shanghai() -> str:
+    return datetime.now(ZoneInfo("Asia/Shanghai")).replace(microsecond=0).isoformat()