@11agents/cli 0.1.24 → 0.1.26

package/mobile-runtime/python/src/device_control/publishers/instagram_adb.py

@@ -0,0 +1,663 @@
+from __future__ import annotations
+
+import re
+import time
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from zoneinfo import ZoneInfo
+
+from device_control.adb import AdbClient
+from device_control.appium_client import AppiumClient
+from device_control.models import Device, PublishRecord, utc_now_iso
+from device_control.publishers import ui_helpers as ui
+from device_control.publishers.tiktok_adb import TikTokAdbPublisher
+from device_control.store import append_publish_record
+
+
+INSTAGRAM_PACKAGE = "com.instagram.android"
+INSTAGRAM_SHARE_BUTTON_IDS = {
+    "com.instagram.android:id/share_button",
+    "com.instagram.android:id/share_footer_button",
+}
+
+
+class NeedsHumanError(RuntimeError):
+    pass
+
+
+@dataclass
+class InstagramAdbPublishResult:
+    device_id: str
+    status: str
+    record_id: str
+    started_at: str
+    ended_at: str
+    duration_seconds: int
+    post_type: str
+    remote_media_path: str
+    screenshot_path: str
+    error: str = ""
+
+
+class InstagramAdbPublisher:
+    """Instagram Reels video publisher for the D03 POC layout."""
+
+    def __init__(
+        self,
+        adb: AdbClient,
+        *,
+        appium_server: str = "http://127.0.0.1:4723",
+        records_path: str | Path = "data/publish_records.jsonl",
+        artifact_root: str | Path = "artifacts/screenshots",
+    ) -> None:
+        self.adb = adb
+        self.appium_server = appium_server
+        self.records_path = Path(records_path)
+        self.artifact_root = Path(artifact_root)
+        self.media_helper = TikTokAdbPublisher(adb, records_path=records_path, artifact_root=artifact_root)
+
+    def publish_video(
+        self,
+        device: Device,
+        *,
+        video_path: str | Path,
+        account_id: str,
+        caption: str = "",
+        dry_run: bool = False,
+        confirm_reels_public: bool = False,
+        caption_input: str = "auto",
+    ) -> InstagramAdbPublishResult:
+        return self.publish_post(
+            device,
+            media_path=video_path,
+            post_type="reel",
+            account_id=account_id,
+            caption=caption,
+            dry_run=dry_run,
+            confirm_reels_public=confirm_reels_public,
+            caption_input=caption_input,
+        )
+
+    def publish_post(
+        self,
+        device: Device,
+        *,
+        media_path: str | Path,
+        post_type: str,
+        account_id: str,
+        caption: str = "",
+        dry_run: bool = False,
+        confirm_reels_public: bool = False,
+        caption_input: str = "auto",
+    ) -> InstagramAdbPublishResult:
+        post_type = _normalize_post_type(post_type)
+        local = Path(media_path).expanduser()
+        if not local.exists():
+            raise FileNotFoundError(f"media not found: {local}")
+        if caption_input not in {"auto", "appium", "adb"}:
+            raise ValueError("caption_input must be one of: auto, appium, adb")
+        media_kind = "video" if post_type in {"reel", "post-video"} else "image"
+        if media_kind == "video" and ui.media_kind_from_path(local) != "video":
+            raise ValueError(f"post_type={post_type} requires a video file")
+        if media_kind == "image" and ui.media_kind_from_path(local) != "image":
+            raise ValueError(f"post_type={post_type} requires an image file")
+
+        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}-instagram-{stamp}"
+        run_dir.mkdir(parents=True, exist_ok=True)
+        remote = f"/sdcard/DCIM/Camera/groupctl-{device.device_id}-instagram-{stamp}{local.suffix}"
+        record_id = f"pub_{stamp.replace('-', '')}_{device.device_id.lower()}_instagram"
+
+        try:
+            self._prepare_device(device)
+            self.media_helper._push_media(device, local, remote)
+            self._launch_instagram(device, run_dir)
+            self._open_new_post(device, run_dir)
+            self._select_destination(device, run_dir, post_type)
+            self._select_first_visible_media(device, run_dir, media_kind)
+            self._continue_to_share_form(device, run_dir, post_type)
+            if caption:
+                self._set_caption(device, caption, run_dir, caption_input)
+
+            if dry_run:
+                final_shot = run_dir / "dry-run-share-form.png"
+                self.adb.screenshot(device.adb_serial, final_shot)
+                status = "dry_run"
+            else:
+                final_shot, status = self._share(device, run_dir, confirm_reels_public)
+
+            ended_epoch = int(time.time())
+            if status == "published":
+                append_publish_record(
+                    self.records_path,
+                    PublishRecord(
+                        record_id=record_id,
+                        platform="instagram",
+                        account_id=account_id,
+                        device_id=device.device_id,
+                        post_type=post_type,
+                        local_media_path=str(local),
+                        remote_media_path=remote,
+                        caption=caption,
+                        published_at=utc_now_iso(),
+                        result_screenshot_path=str(final_shot),
+                        status="published",
+                    ),
+                )
+            return InstagramAdbPublishResult(
+                device_id=device.device_id,
+                status=status,
+                record_id=record_id,
+                started_at=started_at,
+                ended_at=_now_shanghai(),
+                duration_seconds=ended_epoch - started_epoch,
+                post_type=post_type,
+                remote_media_path=remote,
+                screenshot_path=str(final_shot),
+            )
+        except NeedsHumanError as exc:
+            return self._failure_result(
+                device,
+                run_dir,
+                record_id,
+                started_at,
+                started_epoch,
+                remote,
+                post_type=post_type,
+                status="needs_human",
+                error=str(exc),
+            )
+        except Exception as exc:
+            return self._failure_result(
+                device,
+                run_dir,
+                record_id,
+                started_at,
+                started_epoch,
+                remote,
+                post_type=post_type,
+                status="failed",
+                error=str(exc),
+            )
+
+    def _failure_result(
+        self,
+        device: Device,
+        run_dir: Path,
+        record_id: str,
+        started_at: str,
+        started_epoch: int,
+        remote: str,
+        *,
+        post_type: str,
+        status: str,
+        error: str,
+    ) -> InstagramAdbPublishResult:
+        failure_shot = run_dir / f"{status}.png"
+        self.adb.screenshot(device.adb_serial, failure_shot)
+        return InstagramAdbPublishResult(
+            device_id=device.device_id,
+            status=status,
+            record_id=record_id,
+            started_at=started_at,
+            ended_at=_now_shanghai(),
+            duration_seconds=int(time.time()) - started_epoch,
+            post_type=post_type,
+            remote_media_path=remote,
+            screenshot_path=str(failure_shot),
+            error=error,
+        )
+
+    def _prepare_device(self, device: Device) -> None:
+        self._ok(self.adb.wake(device.adb_serial), "wake device")
+        time.sleep(1)
+        self.adb.swipe(device.adb_serial, 540, 1850, 540, 550, 350)
+        time.sleep(1)
+
+    def _launch_instagram(self, device: Device, run_dir: Path) -> None:
+        ui.grant_publish_permissions(self.adb, device, INSTAGRAM_PACKAGE)
+        self.adb.shell(device.adb_serial, "am", "force-stop", INSTAGRAM_PACKAGE)
+        time.sleep(1)
+        self._ok(self.adb.launch_package(device.adb_serial, INSTAGRAM_PACKAGE), "launch Instagram")
+        time.sleep(6)
+        self.adb.screenshot(device.adb_serial, run_dir / "home.png")
+        focus = self.adb.current_focus(device.adb_serial)
+        if INSTAGRAM_PACKAGE not in focus:
+            raise NeedsHumanError("Instagram is not foreground after launch; check install/login/verification state")
+        self._raise_if_blocked(device, run_dir / "home.xml")
+
+    def _open_new_post(self, device: Device, run_dir: Path) -> None:
+        root = self._dump(device, run_dir / "before-new-post.xml")
+        node = _find_node(root, texts={"新建", "Create", "New"}, clickable_only=False)
+        if node is not None:
+            x, y = _center(_bounds(node))
+            self._tap(device, x, y, 3)
+        else:
+            self._tap(device, 72, 190, 3)
+        self._tap_permission_button_if_present(device, run_dir / "media-permission.xml", {"允许", "Allow"})
+        time.sleep(3)
+        self.adb.screenshot(device.adb_serial, run_dir / "gallery.png")
+        self._raise_if_blocked(device, run_dir / "gallery.xml")
+        if not self._has_any_text(device, run_dir / "gallery-check.xml", {"新帖子", "New post"}):
+            raise NeedsHumanError("Instagram gallery did not open; check login, verification, prompts, or layout calibration")
+
+    def _select_destination(self, device: Device, run_dir: Path, post_type: str) -> None:
+        target_id = "com.instagram.android:id/cam_dest_clips" if post_type == "reel" else "com.instagram.android:id/cam_dest_feed"
+        root = self._dump(device, run_dir / f"gallery-destination-{post_type}.xml")
+        node = _find_node(root, ids={target_id}, clickable_only=False)
+        if node is not None:
+            x, y = _center(_bounds(node))
+            self._tap(device, x, y, 1)
+            self.adb.screenshot(device.adb_serial, run_dir / f"after-destination-{post_type}.png")
+
+    def _select_first_visible_media(self, device: Device, run_dir: Path, media_kind: str) -> None:
+        xml_path = run_dir / "gallery-before-select.xml"
+        root = self._dump(device, xml_path)
+        media_node = _find_first_visible_media_thumbnail(root, media_kind)
+        if media_node is None:
+            self.adb.screenshot(device.adb_serial, run_dir / f"no-visible-{media_kind}.png")
+            raise NeedsHumanError(f"No visible {media_kind} thumbnail found in Instagram gallery")
+        x, y = _center(_bounds(media_node))
+        self._tap(device, x, y, 1)
+        self.adb.screenshot(device.adb_serial, run_dir / "gallery-selected.png")
+
+    def _continue_to_share_form(self, device: Device, run_dir: Path, post_type: str) -> None:
+        if not self._tap_node(device, run_dir / "gallery-selected.xml", ids={"com.instagram.android:id/next_button_textview"}):
+            self._tap(device, 996, 190, 0)
+        time.sleep(5)
+        self.adb.screenshot(device.adb_serial, run_dir / "after-gallery-continue.png")
+        self._raise_if_blocked(device, run_dir / "after-gallery-continue.xml")
+        self._allow_camera_microphone_if_needed(device, run_dir)
+
+        if post_type == "reel":
+            self._next_from_editor(device, run_dir)
+            return
+
+        self._next_until_share_form(device, run_dir)
+
+    def _next_until_share_form(self, device: Device, run_dir: Path) -> None:
+        deadline = time.time() + 45
+        attempt = 0
+        while time.time() < deadline:
+            attempt += 1
+            root = self._dump(device, run_dir / f"post-next-{attempt}.xml")
+            if self._tap_post_public_sheet_if_present(device, root, run_dir, attempt):
+                time.sleep(2)
+                continue
+            if _find_node(root, ids={"com.instagram.android:id/caption_input_text_view"}) is not None and _find_node(
+                root, ids=INSTAGRAM_SHARE_BUTTON_IDS
+            ) is not None:
+                self.adb.screenshot(device.adb_serial, run_dir / "share-form.png")
+                return
+            node = _find_node(
+                root,
+                ids={
+                    "com.instagram.android:id/next_button_textview",
+                    "com.instagram.android:id/next_button",
+                    "com.instagram.android:id/creation_next_button",
+                    "com.instagram.android:id/media_thumbnail_tray_button",
+                },
+                texts={"下一步", "继续", "Next", "Continue"},
+                clickable_only=False,
+            )
+            if node is not None:
+                x, y = _center(_bounds(node))
+                self._tap(device, x, y, 4)
+                continue
+            time.sleep(2)
+        self.adb.screenshot(device.adb_serial, run_dir / "post-share-form-timeout.png")
+        raise NeedsHumanError("Instagram Post share form was not detected after selecting media")
+
+    def _tap_post_public_sheet_if_present(self, device: Device, root: ET.Element, run_dir: Path, attempt: int) -> bool:
+        text = _all_text(root)
+        if not _contains_any(text, {"分享帖子", "你的账户是公开的", "Share post", "Your account is public"}):
+            return False
+        node = _find_node(root, texts={"确定", "OK"}, clickable_only=False)
+        if node is None:
+            return False
+        self.adb.screenshot(device.adb_serial, run_dir / f"post-public-sheet-{attempt}.png")
+        x, y = _center(_bounds(node))
+        self._tap(device, x, y, 0)
+        return True
+
+    def _allow_camera_microphone_if_needed(self, device: Device, run_dir: Path) -> None:
+        if self._tap_permission_button_if_present(device, run_dir / "camera-mic-permission.xml", {"确定", "OK", "Allow"}):
+            time.sleep(3)
+            self.adb.screenshot(device.adb_serial, run_dir / "after-camera-mic-permission.png")
+
+    def _next_from_editor(self, device: Device, run_dir: Path) -> None:
+        deadline = time.time() + 35
+        while time.time() < deadline:
+            if self._tap_node(device, run_dir / "editor.xml", ids={"com.instagram.android:id/clips_right_action_button"}):
+                time.sleep(5)
+                self.adb.screenshot(device.adb_serial, run_dir / "share-form.png")
+                self._raise_if_blocked(device, run_dir / "share-form.xml")
+                if self._has_any_id(device, run_dir / "share-form-check.xml", {"com.instagram.android:id/caption_input_text_view"}):
+                    return
+            time.sleep(2)
+        raise NeedsHumanError("Instagram editor next button/share form was not detected")
+
+    def _set_caption(self, device: Device, caption: str, run_dir: Path, caption_input: str) -> None:
+        last_error = ""
+        if caption_input in {"auto", "appium"}:
+            try:
+                self._set_caption_with_appium(device, caption)
+                self._dismiss_caption_keyboard(device, run_dir)
+                self.adb.screenshot(device.adb_serial, run_dir / "after-caption.png")
+                return
+            except Exception as exc:
+                last_error = str(exc)
+                if caption_input == "appium":
+                    raise RuntimeError(f"caption input via Appium failed: {last_error}") from exc
+
+        if not _adb_text_safe(caption):
+            raise RuntimeError(
+                "caption contains characters that adb input text cannot safely enter; "
+                "start Appium and use --caption-input appium"
+                + (f"; Appium error: {last_error}" if last_error else "")
+            )
+        if not self._tap_node(device, run_dir / "caption-field.xml", ids={"com.instagram.android:id/caption_input_text_view"}):
+            self._tap(device, 150, 340, 0)
+        time.sleep(1)
+        result = self.adb.input_text(device.adb_serial, caption)
+        if not result.ok:
+            raise RuntimeError(f"caption input via adb failed: {result.stderr or result.stdout}")
+        time.sleep(1)
+        self.adb.keyevent(device.adb_serial, "KEYCODE_BACK")
+        time.sleep(1)
+        self.adb.screenshot(device.adb_serial, run_dir / "after-caption.png")
+
+    def _set_caption_with_appium(self, device: Device, caption: str) -> None:
+        appium = AppiumClient(self.appium_server)
+        try:
+            appium.start_session(_appium_capabilities(device.adb_serial))
+            field = appium.find_element("id", "com.instagram.android:id/caption_input_text_view")
+            appium.click(field)
+            time.sleep(1)
+            appium.send_keys(field, caption)
+            time.sleep(1)
+        finally:
+            try:
+                appium.delete_session()
+            except Exception:
+                pass
+
+    def _dismiss_caption_keyboard(self, device: Device, run_dir: Path) -> None:
+        self.adb.keyevent(device.adb_serial, "KEYCODE_BACK")
+        time.sleep(1)
+        root = self._dump(device, run_dir / "after-caption-dismiss-keyboard.xml")
+        done = _find_node(root, ids={"com.instagram.android:id/next_button_textview"}, texts={"确定", "Done"})
+        if done is not None and _find_node(root, ids=INSTAGRAM_SHARE_BUTTON_IDS) is None:
+            x, y = _center(_bounds(done))
+            self._tap(device, x, y, 1)
+
+    def _share(self, device: Device, run_dir: Path, confirm_reels_public: bool) -> tuple[Path, str]:
+        if not self._tap_share_button(device, run_dir / "before-share.xml"):
+            self._tap(device, 800, 2202, 0)
+        time.sleep(3)
+        self.adb.screenshot(device.adb_serial, run_dir / "after-share-tap.png")
+
+        if self._is_facebook_crosspost_prompt(device, run_dir / "facebook-crosspost-prompt.xml"):
+            self.adb.screenshot(device.adb_serial, run_dir / "facebook-crosspost-prompt.png")
+            if not self._tap_node(
+                device,
+                run_dir / "facebook-crosspost-prompt.xml",
+                ids={"com.instagram.android:id/igds_headline_secondary_action_text_button"},
+                texts={"以后再说", "Not now"},
+            ):
+                self._tap(device, 540, 2185, 0)
+            time.sleep(5)
+
+        if self._is_reels_public_sheet(device, run_dir / "reels-public-sheet.xml"):
+            self.adb.screenshot(device.adb_serial, run_dir / "reels-public-sheet.png")
+            if not confirm_reels_public:
+                raise NeedsHumanError("Instagram Reels public sharing prompt needs explicit confirmation")
+            if not self._tap_node(
+                device,
+                run_dir / "reels-public-sheet.xml",
+                ids={"com.instagram.android:id/clips_nux_sheet_share_button"},
+                texts={"分享", "Share"},
+            ):
+                self._tap(device, 540, 2094, 0)
+            time.sleep(4)
+
+        final_shot = self._wait_for_publish_complete(device, run_dir)
+        return final_shot, "published"
+
+    def _tap_share_button(self, device: Device, xml_path: Path) -> bool:
+        root = self._dump(device, xml_path)
+        node = _find_node(root, ids=INSTAGRAM_SHARE_BUTTON_IDS, clickable_only=False)
+        if node is None:
+            return False
+        x, y = _center(_bounds(node))
+        if node.attrib.get("resource-id") == "com.instagram.android:id/share_footer_button" and y < 2260:
+            y = 2285
+        self._tap(device, x, y, 0)
+        return True
+
+    def _wait_for_publish_complete(self, device: Device, run_dir: Path) -> Path:
+        deadline = time.time() + 90
+        last_xml = run_dir / "publish-poll.xml"
+        while time.time() < deadline:
+            time.sleep(5)
+            root = self._dump(device, last_xml)
+            text = _all_text(root)
+            if _contains_any(text, {"出错", "重试", "失败", "无法发布", "couldn't post", "try again", "failed"}):
+                raise RuntimeError("Instagram publish appears failed or retryable")
+            if _contains_any(text, {"正在发布", "正在上传", "Posting", "Uploading"}):
+                continue
+            if _contains_any(
+                text,
+                {
+                    "发布了video",
+                    "posted a video",
+                    "发布了 reel",
+                    "posted a reel",
+                    "发布了照片",
+                    "posted a photo",
+                    "posted a post",
+                    "已分享",
+                },
+            ):
+                final_shot = run_dir / "after-post.png"
+                self.adb.screenshot(device.adb_serial, final_shot)
+                return final_shot
+            focus = self.adb.current_focus(device.adb_serial)
+            if INSTAGRAM_PACKAGE in focus and ("InstagramMainActivity" in focus or "MainTabActivity" in focus):
+                final_shot = run_dir / "after-post.png"
+                self.adb.screenshot(device.adb_serial, final_shot)
+                return final_shot
+        timeout_shot = run_dir / "after-post-timeout.png"
+        self.adb.screenshot(device.adb_serial, timeout_shot)
+        raise RuntimeError("Instagram publish completion not confirmed within 90s")
+
+    def _raise_if_blocked(self, device: Device, xml_path: Path) -> None:
+        root = self._dump(device, xml_path)
+        text = _all_text(root)
+        if _contains_any(
+            text,
+            {
+                "验证码",
+                "人机",
+                "验证",
+                "登录",
+                "Log in",
+                "Login",
+                "captcha",
+                "suspicious",
+                "restriction",
+                "restricted",
+            },
+        ):
+            raise NeedsHumanError("Instagram needs login, verification, captcha, or account review")
+
+    def _is_reels_public_sheet(self, device: Device, xml_path: Path) -> bool:
+        root = self._dump(device, xml_path)
+        if _find_node(root, ids={"com.instagram.android:id/clips_nux_sheet_share_button"}) is not None:
+            return True
+        return _contains_any(_all_text(root), {"关于 Reels", "About Reels"})
+
+    def _is_facebook_crosspost_prompt(self, device: Device, xml_path: Path) -> bool:
+        root = self._dump(device, xml_path)
+        if _find_node(root, ids={"com.instagram.android:id/igds_headline_secondary_action_text_button"}) is not None:
+            return _contains_any(_all_text(root), {"同时分享到 Facebook", "Share to Facebook"})
+        return False
+
+    def _has_any_text(self, device: Device, xml_path: Path, texts: set[str]) -> bool:
+        return _contains_any(_all_text(self._dump(device, xml_path)), texts)
+
+    def _has_any_id(self, device: Device, xml_path: Path, ids: set[str]) -> bool:
+        return _find_node(self._dump(device, xml_path), ids=ids) is not None
+
+    def _tap_permission_button_if_present(self, device: Device, xml_path: Path, texts: set[str]) -> bool:
+        return ui.tap_permission_prompt_if_present(self.adb, device, xml_path)
+
+    def _tap_node(
+        self,
+        device: Device,
+        xml_path: Path,
+        *,
+        ids: set[str] | None = None,
+        texts: set[str] | None = None,
+    ) -> bool:
+        root = self._dump(device, xml_path)
+        node = _find_node(root, ids=ids, texts=texts, clickable_only=True)
+        if node is None:
+            return False
+        x, y = _center(_bounds(node))
+        self._tap(device, x, y, 0)
+        return True
+
+    def _dump(self, device: Device, xml_path: Path) -> ET.Element:
+        dump = self.adb.dump_ui(device.adb_serial, xml_path)
+        if not dump.ok:
+            raise RuntimeError(f"dump ui failed: {dump.stderr or dump.stdout}")
+        return ET.parse(xml_path).getroot()
+
+    def _tap(self, device: Device, x: int, y: int, sleep_s: float) -> None:
+        self._ok(self.adb.tap(device.adb_serial, x, y), f"tap {x},{y}")
+        if sleep_s:
+            time.sleep(sleep_s)
+
+    @staticmethod
+    def _ok(result, action: str) -> None:
+        if not result.ok:
+            raise RuntimeError(f"{action} failed: {result.stderr or result.stdout}")
+
+
+def _normalize_post_type(value: str) -> str:
+    text = value.strip().lower().replace("_", "-")
+    aliases = {
+        "reels": "reel",
+        "feed": "post-image",
+        "post": "post-image",
+        "image": "post-image",
+        "photo": "post-image",
+        "post-image": "post-image",
+        "post-photo": "post-image",
+        "video": "post-video",
+        "post-video": "post-video",
+    }
+    if text in aliases:
+        return aliases[text]
+    raise ValueError("Instagram post_type must be one of: reel, post-image, post-video")
+
+
+def _find_first_visible_media_thumbnail(root: ET.Element, media_kind: str) -> ET.Element | None:
+    candidates: list[tuple[int, int, ET.Element]] = []
+    for node in root.iter("node"):
+        if node.attrib.get("resource-id") != "com.instagram.android:id/gallery_grid_item_thumbnail":
+            continue
+        desc = node.attrib.get("content-desc", "")
+        if media_kind == "video" and "视频缩略图" not in desc and "Video thumbnail" not in desc:
+            continue
+        if media_kind == "image" and "照片缩略图" not in desc and "Photo thumbnail" not in desc:
+            continue
+        bounds = _bounds(node)
+        if not bounds:
+            continue
+        left, top, right, bottom = bounds
+        if right <= left or bottom <= top or bottom < 280:
+            continue
+        candidates.append((top, left, node))
+    if not candidates:
+        return None
+    candidates.sort(key=lambda item: (item[0], item[1]))
+    return candidates[0][2]
+
+
+def _find_node(
+    root: ET.Element,
+    *,
+    ids: set[str] | None = None,
+    texts: set[str] | None = None,
+    clickable_only: bool = False,
+) -> ET.Element | None:
+    for node in root.iter("node"):
+        if clickable_only and node.attrib.get("clickable") != "true":
+            continue
+        if ids and node.attrib.get("resource-id") in ids:
+            return node
+        if texts and (node.attrib.get("text") in texts or node.attrib.get("content-desc") in texts):
+            return node
+    return None
+
+
+def _bounds(node: ET.Element) -> tuple[int, int, int, int] | None:
+    match = re.fullmatch(r"\[(\d+),(\d+)\]\[(\d+),(\d+)\]", node.attrib.get("bounds", ""))
+    if not match:
+        return None
+    return tuple(int(part) for part in match.groups())
+
+
+def _center(bounds: tuple[int, int, int, int] | None) -> tuple[int, int]:
+    if not bounds:
+        raise RuntimeError("node has no valid bounds")
+    left, top, right, bottom = bounds
+    return (left + right) // 2, (top + bottom) // 2
+
+
+def _all_text(root: ET.Element) -> str:
+    parts: list[str] = []
+    for node in root.iter("node"):
+        text = node.attrib.get("text", "")
+        desc = node.attrib.get("content-desc", "")
+        if text:
+            parts.append(text)
+        if desc:
+            parts.append(desc)
+    return "\n".join(parts)
+
+
+def _contains_any(text: str, needles: set[str]) -> bool:
+    lowered = text.lower()
+    return any(needle.lower() in lowered for needle in needles)
+
+
+def _adb_text_safe(text: str) -> bool:
+    allowed = set("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789 .,!?:;'\"_@#%()+-/|")
+    return all(char in allowed for char in text)
+
+
+def _appium_capabilities(serial: str) -> dict:
+    return {
+        "platformName": "Android",
+        "appium:automationName": "UiAutomator2",
+        "appium:udid": serial,
+        "appium:noReset": True,
+        "appium:newCommandTimeout": 120,
+        "appium:disableWindowAnimation": True,
+        "appium:skipDeviceInitialization": True,
+        "appium:ignoreHiddenApiPolicyError": True,
+        "appium:disableSuppressAccessibilityService": True,
+        "appium:settings[enableNotificationListener]": False,
+        "appium:autoLaunch": False,
+    }
+
+
+def _now_shanghai() -> str:
+    return datetime.now(ZoneInfo("Asia/Shanghai")).strftime("%Y-%m-%d %H:%M:%S %z")