@11agents/cli 0.1.23 → 0.1.25

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

@@ -0,0 +1,1143 @@
+from __future__ import annotations
+
+import copy
+import json
+import re
+import time
+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
+
+
+XIAOHONGSHU_PACKAGE = "com.xingin.xhs"
+
+DEFAULT_FLOW_CONFIG = {
+    "package": XIAOHONGSHU_PACKAGE,
+    "coords": {
+        "unlock_swipe": [540, 1850, 540, 550, 350],
+        "home_plus": [540, 2230],
+        "album_drawer_first": [540, 1695],
+        "latest_video_select": [1025, 425],
+        "latest_image_select": [1025, 425],
+        "multi_image_select": [
+            [1028, 424],
+            [665, 424],
+            [302, 424],
+            [1028, 787],
+            [665, 787],
+            [302, 787],
+            [1028, 1150],
+        ],
+        "gallery_next": [800, 2240],
+        "editor_next": [885, 2220],
+        "first_publish": [945, 180],
+        "confirm_publish": [725, 2200],
+        "bottom_me": [972, 2230],
+        "profile_latest_note": [270, 1220],
+        "post_publish_prompt_close": [1020, 1200],
+        "note_share": [988, 186],
+        "copy_link": [137, 2142],
+        "comment_input": [421, 374],
+    },
+    "selectors": {
+        "title": f"{XIAOHONGSHU_PACKAGE}:id/editTitle",
+        "caption": f"{XIAOHONGSHU_PACKAGE}:id/postNoteEditContentView",
+    },
+    "waits": {
+        "after_wake": 1,
+        "after_unlock": 1,
+        "after_launch": 5,
+        "after_plus": 1,
+        "after_album_entry": 3,
+        "after_latest_video_select": 1,
+        "after_gallery_next": 4,
+        "after_editor_next": 4,
+        "after_title_click": 1,
+        "after_caption_click": 1,
+        "after_caption_input": 1,
+        "after_first_publish": 2,
+        "after_confirm_publish": 2,
+        "after_prompt_dismiss": 1,
+        "after_me_tab": 3,
+        "after_latest_note_tap": 3,
+        "after_share_tap": 1,
+        "after_copy_link": 1,
+        "after_comment_input_tap": 1,
+        "after_paste_probe": 1,
+        "detail_load_timeout": 12,
+        "publish_poll_interval": 2,
+        "publish_timeout": 45,
+    },
+    "success_focus_keywords": ["IndexActivityV2"],
+    "detail_focus_keywords": ["NoteDetailActivity"],
+    "post_form_focus_keywords": ["CapaPostNotePlatformActivity"],
+    "in_progress_focus_keywords": [
+        "CapaPostNotePlatformActivity",
+        "VideoEditActivity",
+        "CapaAlbumActivity",
+    ],
+}
+
+FIELD_PLACEHOLDERS = {
+    "title": {
+        "exact": {"添加标题"},
+        "partial": set(),
+        "index": 0,
+    },
+    "caption": {
+        "exact": {"添加正文或发语音"},
+        "partial": {"添加正文"},
+        "index": 1,
+    },
+}
+
+
+@dataclass
+class XiaohongshuAdbPublishResult:
+    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 = ""
+    platform_permalink: str = ""
+    link_status: str = ""
+    link_error: str = ""
+    link_screenshot_path: str = ""
+
+
+@dataclass
+class XiaohongshuLinkResult:
+    device_id: str
+    status: str
+    started_at: str
+    ended_at: str
+    duration_seconds: int
+    platform_permalink: str
+    screenshot_path: str
+    clipboard_method: str = ""
+    error: str = ""
+
+
+class XiaohongshuAdbPublisher:
+    """Xiaohongshu image/video publisher for a configured device flow."""
+
+    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",
+        flow_config_path: str | Path = "configs/platforms/xiaohongshu_d03.json",
+    ) -> None:
+        self.adb = adb
+        self.appium_server = appium_server
+        self.records_path = Path(records_path)
+        self.artifact_root = Path(artifact_root)
+        self.flow_config = _load_flow_config(flow_config_path)
+        self.package = str(self.flow_config.get("package") or XIAOHONGSHU_PACKAGE)
+        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,
+        title: str,
+        caption: str = "",
+        tags: list[str] | None = None,
+        topics: list[str] | None = None,
+        dry_run: bool = False,
+        confirm_no_disclosure_needed: bool = False,
+        copy_link_after_publish: bool = False,
+        resume_post_form: bool = False,
+    ) -> XiaohongshuAdbPublishResult:
+        return self.publish_note(
+            device,
+            media_path=video_path,
+            post_type="video",
+            account_id=account_id,
+            title=title,
+            caption=caption,
+            tags=tags,
+            topics=topics,
+            dry_run=dry_run,
+            confirm_no_disclosure_needed=confirm_no_disclosure_needed,
+            copy_link_after_publish=copy_link_after_publish,
+            resume_post_form=resume_post_form,
+        )
+
+    def publish_image(
+        self,
+        device: Device,
+        *,
+        image_path: str | Path,
+        account_id: str,
+        title: str,
+        caption: str = "",
+        tags: list[str] | None = None,
+        topics: list[str] | None = None,
+        dry_run: bool = False,
+        confirm_no_disclosure_needed: bool = False,
+        copy_link_after_publish: bool = False,
+        resume_post_form: bool = False,
+    ) -> XiaohongshuAdbPublishResult:
+        return self.publish_note(
+            device,
+            media_path=image_path,
+            post_type="image",
+            account_id=account_id,
+            title=title,
+            caption=caption,
+            tags=tags,
+            topics=topics,
+            dry_run=dry_run,
+            confirm_no_disclosure_needed=confirm_no_disclosure_needed,
+            copy_link_after_publish=copy_link_after_publish,
+            resume_post_form=resume_post_form,
+        )
+
+    def publish_note(
+        self,
+        device: Device,
+        *,
+        media_path: str | Path,
+        media_paths: list[str | Path] | None = None,
+        post_type: str,
+        account_id: str,
+        title: str,
+        caption: str = "",
+        tags: list[str] | None = None,
+        topics: list[str] | None = None,
+        dry_run: bool = False,
+        confirm_no_disclosure_needed: bool = False,
+        copy_link_after_publish: bool = False,
+        resume_post_form: bool = False,
+    ) -> XiaohongshuAdbPublishResult:
+        post_type = _normalize_post_type(post_type)
+        locals_ = [Path(item).expanduser() for item in (media_paths or [media_path])]
+        if not locals_:
+            raise ValueError("at least one media path is required")
+        if post_type == "video" and len(locals_) != 1:
+            raise ValueError("Xiaohongshu video notes support exactly one video")
+        if post_type == "image" and len(locals_) > len(self._multi_image_coords()):
+            raise ValueError(f"Xiaohongshu image notes support up to {len(self._multi_image_coords())} images in current flow config")
+        for local in locals_:
+            if not local.exists():
+                raise FileNotFoundError(f"media not found: {local}")
+            if ui.media_kind_from_path(local) != post_type:
+                raise ValueError(f"post_type={post_type} does not match media file suffix: {local}")
+        tag_values = _normalize_hashtag_values(tags or [])
+        topic_values = _normalize_hashtag_values(topics 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}-xiaohongshu-{stamp}"
+        run_dir.mkdir(parents=True, exist_ok=True)
+        remote_paths = [
+            f"/sdcard/DCIM/Camera/groupctl-{device.device_id}-xhs-{stamp}-{idx:02d}{local.suffix}"
+            for idx, local in enumerate(locals_, start=1)
+        ]
+        remote = "current_post_form" if resume_post_form else ",".join(remote_paths)
+        record_id = f"pub_{stamp.replace('-', '')}_{device.device_id.lower()}_xiaohongshu"
+        link_result: XiaohongshuLinkResult | None = None
+
+        try:
+            self._prepare_device(device)
+            if resume_post_form:
+                self._require_current_post_form(device)
+                self.adb.screenshot(device.adb_serial, run_dir / "post-form-resume.png")
+            else:
+                push_pairs = list(zip(locals_, remote_paths))
+                if post_type == "image" and len(push_pairs) > 1:
+                    push_pairs = list(reversed(push_pairs))
+                for local, remote_path in push_pairs:
+                    self.media_helper._push_media(device, local, remote_path)
+                self._launch_xiaohongshu(device)
+                self._open_album_flow(device, run_dir)
+                self._select_latest_media(device, run_dir, post_type, count=len(locals_))
+                self._next_from_gallery(device, run_dir)
+                self._next_from_editor(device, run_dir)
+            self._set_title_and_caption(device, title, caption, tag_values, topic_values, run_dir)
+
+            if dry_run:
+                final_shot = run_dir / "dry-run-post-form.png"
+                self.adb.screenshot(device.adb_serial, final_shot)
+                status = "dry_run"
+            else:
+                self._tap_first_publish(device)
+                self.adb.screenshot(device.adb_serial, run_dir / "disclosure-prompt.png")
+                if not confirm_no_disclosure_needed:
+                    return XiaohongshuAdbPublishResult(
+                        device_id=device.device_id,
+                        status="needs_human",
+                        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(run_dir / "disclosure-prompt.png"),
+                        error="content disclosure prompt needs explicit confirmation",
+                    )
+                self._tap_confirm_publish(device)
+                time.sleep(self._wait("after_confirm_publish"))
+                final_shot = self._wait_for_publish_complete(device, run_dir)
+                status = "published"
+                if copy_link_after_publish:
+                    link_result = self.copy_current_note_link(device, prepare=False, run_dir=run_dir / "link")
+
+            ended_epoch = int(time.time())
+            if status == "published":
+                permalink = link_result.platform_permalink if link_result else ""
+                append_publish_record(
+                    self.records_path,
+                    PublishRecord(
+                        record_id=record_id,
+                        platform="xiaohongshu",
+                        account_id=account_id,
+                        device_id=device.device_id,
+                        post_type=post_type,
+                        local_media_path=",".join(str(item) for item in locals_),
+                        remote_media_path=remote,
+                        platform_permalink=permalink,
+                        caption=_caption(title, _compose_caption_for_record(caption, tag_values, topic_values)),
+                        published_at=utc_now_iso(),
+                        result_screenshot_path=str(final_shot),
+                        status="published",
+                    ),
+                )
+            return XiaohongshuAdbPublishResult(
+                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),
+                platform_permalink=link_result.platform_permalink if link_result else "",
+                link_status=link_result.status if link_result else "",
+                link_error=link_result.error if link_result else "",
+                link_screenshot_path=link_result.screenshot_path if link_result else "",
+            )
+        except Exception as exc:
+            failure_shot = run_dir / "failed.png"
+            self.adb.screenshot(device.adb_serial, failure_shot)
+            return XiaohongshuAdbPublishResult(
+                device_id=device.device_id,
+                status="failed",
+                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=str(exc),
+            )
+
+    def copy_current_note_link(
+        self,
+        device: Device,
+        *,
+        prepare: bool = True,
+        run_dir: Path | None = None,
+    ) -> XiaohongshuLinkResult:
+        started_epoch = int(time.time())
+        started_at = _now_shanghai()
+        if run_dir is None:
+            stamp = datetime.now(ZoneInfo("Asia/Shanghai")).strftime("%Y%m%d-%H%M%S")
+            run_dir = self.artifact_root / f"{device.device_id}-xiaohongshu-link-{stamp}"
+        run_dir.mkdir(parents=True, exist_ok=True)
+
+        try:
+            if prepare:
+                self._prepare_device(device)
+            else:
+                self._ok(self.adb.wake(device.adb_serial), "wake device")
+            focus = self.adb.current_focus(device.adb_serial)
+            if not any(keyword in focus for keyword in self._keywords("detail_focus_keywords")):
+                self._open_latest_own_note_for_link(device, run_dir)
+            self.adb.screenshot(device.adb_serial, run_dir / "before-copy-link.png")
+            self._tap_coord(device, "note_share", self._wait("after_share_tap"))
+            self.adb.screenshot(device.adb_serial, run_dir / "share-sheet.png")
+            self._tap_copy_link(device, run_dir)
+            time.sleep(self._wait("after_copy_link"))
+            final_shot = run_dir / "after-copy-link.png"
+            self.adb.screenshot(device.adb_serial, final_shot)
+
+            permalink, method, error = self._read_copied_link(device, run_dir)
+            if permalink:
+                status = "retrieved"
+            else:
+                status = "needs_human"
+                error = error or "copied link to device clipboard, but automatic clipboard read returned no URL"
+            return XiaohongshuLinkResult(
+                device_id=device.device_id,
+                status=status,
+                started_at=started_at,
+                ended_at=_now_shanghai(),
+                duration_seconds=int(time.time()) - started_epoch,
+                platform_permalink=permalink,
+                screenshot_path=str(final_shot),
+                clipboard_method=method,
+                error=error,
+            )
+        except Exception as exc:
+            failure_shot = run_dir / "failed-copy-link.png"
+            self.adb.screenshot(device.adb_serial, failure_shot)
+            return XiaohongshuLinkResult(
+                device_id=device.device_id,
+                status="failed",
+                started_at=started_at,
+                ended_at=_now_shanghai(),
+                duration_seconds=int(time.time()) - started_epoch,
+                platform_permalink="",
+                screenshot_path=str(failure_shot),
+                error=str(exc),
+            )
+
+    def _prepare_device(self, device: Device) -> None:
+        self._ok(self.adb.wake(device.adb_serial), "wake device")
+        time.sleep(self._wait("after_wake"))
+        x1, y1, x2, y2, duration_ms = self._coord("unlock_swipe")
+        self.adb.swipe(device.adb_serial, x1, y1, x2, y2, duration_ms)
+        time.sleep(self._wait("after_unlock"))
+
+    def _launch_xiaohongshu(self, device: Device) -> None:
+        ui.grant_publish_permissions(self.adb, device, self.package)
+        self._ok(self.adb.launch_package(device.adb_serial, self.package), "launch Xiaohongshu")
+        time.sleep(self._wait("after_launch"))
+
+    def _open_album_flow(self, device: Device, run_dir: Path) -> None:
+        self._tap_coord(device, "home_plus", self._wait("after_plus"))
+        ui.tap_permission_prompt_if_present(self.adb, device, run_dir / "after-plus-permission.xml")
+        self.adb.screenshot(device.adb_serial, run_dir / "after-plus.png")
+        self._tap_coord(device, "album_drawer_first", self._wait("after_album_entry"))
+        ui.tap_permission_prompt_if_present(self.adb, device, run_dir / "gallery-permission.xml")
+        self.adb.screenshot(device.adb_serial, run_dir / "gallery.png")
+
+    def _select_latest_media(self, device: Device, run_dir: Path, post_type: str, *, count: int = 1) -> None:
+        if post_type == "image" and count > 1:
+            for x, y in self._multi_image_coords()[:count]:
+                self._tap(device, x, y, self._wait("after_latest_video_select"))
+            self.adb.screenshot(device.adb_serial, run_dir / "gallery-selected.png")
+            return
+        coord_name = "latest_image_select" if post_type == "image" else "latest_video_select"
+        self._tap_coord(device, coord_name, self._wait("after_latest_video_select"))
+        self.adb.screenshot(device.adb_serial, run_dir / "gallery-selected.png")
+
+    def _next_from_gallery(self, device: Device, run_dir: Path) -> None:
+        self._tap_coord(device, "gallery_next", self._wait("after_gallery_next"))
+        self.adb.screenshot(device.adb_serial, run_dir / "editor.png")
+
+    def _next_from_editor(self, device: Device, run_dir: Path) -> None:
+        self._tap_coord(device, "editor_next", self._wait("after_editor_next"))
+        self.adb.screenshot(device.adb_serial, run_dir / "post-form.png")
+
+    def _set_title_and_caption(
+        self,
+        device: Device,
+        title: str,
+        caption: str,
+        tags: list[str],
+        topics: list[str],
+        run_dir: Path,
+    ) -> None:
+        appium = AppiumClient(self.appium_server)
+        try:
+            appium.start_session(_appium_capabilities(device.adb_serial))
+            self._set_text_field(appium, device, "title", title, run_dir, sleep_after_click=self._wait("after_title_click"))
+            caption_field_id = ""
+            if caption:
+                caption_field_id = self._set_text_field(
+                    appium,
+                    device,
+                    "caption",
+                    caption,
+                    run_dir,
+                    sleep_after_click=self._wait("after_caption_click"),
+                )
+            manual_tags = _format_manual_hashtags([*tags, *topics], existing=caption)
+            if manual_tags:
+                if not caption_field_id:
+                    caption_field_id = self._focus_text_field(
+                        appium,
+                        device,
+                        "caption",
+                        run_dir,
+                        sleep_after_click=self._wait("after_caption_click"),
+                    )
+                if caption:
+                    self._ok(self.adb.keyevent(device.adb_serial, "KEYCODE_MOVE_END"), "move caption cursor to end")
+                    time.sleep(0.2)
+                self._input_hashtags_manually(appium, device, caption_field_id, manual_tags, has_caption=bool(caption))
+            time.sleep(self._wait("after_caption_input"))
+            self.adb.screenshot(device.adb_serial, run_dir / "after-caption.png")
+        finally:
+            try:
+                appium.delete_session()
+            except Exception:
+                pass
+
+    def _set_text_field(
+        self,
+        appium: AppiumClient,
+        device: Device,
+        name: str,
+        text: str,
+        run_dir: Path,
+        *,
+        sleep_after_click: float,
+    ) -> str:
+        selector = self._selector(name)
+        field_id = ""
+        errors: list[str] = []
+        try:
+            field_id = self._find_and_click_text_field(appium, name, selector, errors)
+        except Exception as exc:
+            errors.append(f"appium_find_click failed: {_short(str(exc))}")
+
+        if not field_id and not self._tap_text_field_from_ui_dump(device, name, selector, run_dir):
+            raise RuntimeError(f"{name} input field not found: {'; '.join(errors)}")
+
+        time.sleep(sleep_after_click)
+        if field_id:
+            try:
+                appium.clear(field_id)
+            except Exception as exc:
+                errors.append(f"appium_clear failed: {_short(str(exc))}")
+
+        try:
+            appium.set_clipboard(text)
+            self._ok(self.adb.keyevent(device.adb_serial, "KEYCODE_PASTE"), f"paste {name}")
+            time.sleep(0.5)
+            return field_id
+        except Exception as exc:
+            errors.append(f"clipboard_paste failed: {_short(str(exc))}")
+
+        if field_id:
+            try:
+                appium.send_keys(field_id, text)
+                time.sleep(0.5)
+                return field_id
+            except Exception as exc:
+                errors.append(f"appium_send_keys failed: {_short(str(exc))}")
+
+        raise RuntimeError(f"{name} input failed: {'; '.join(errors)}")
+
+    def _focus_text_field(
+        self,
+        appium: AppiumClient,
+        device: Device,
+        name: str,
+        run_dir: Path,
+        *,
+        sleep_after_click: float,
+    ) -> str:
+        selector = self._selector(name)
+        errors: list[str] = []
+        field_id = self._find_and_click_text_field(appium, name, selector, errors)
+        if not field_id and not self._tap_text_field_from_ui_dump(device, name, selector, run_dir):
+            raise RuntimeError(f"{name} input field not found for manual tags: {'; '.join(errors)}")
+        time.sleep(sleep_after_click)
+        if field_id:
+            return field_id
+        field_id = self._find_and_click_text_field(appium, name, selector, errors)
+        if not field_id:
+            raise RuntimeError(f"{name} input field id not available for manual tags: {'; '.join(errors)}")
+        return field_id
+
+    def _input_hashtags_manually(
+        self,
+        appium: AppiumClient,
+        device: Device,
+        field_id: str,
+        hashtags: list[str],
+        *,
+        has_caption: bool,
+    ) -> None:
+        if has_caption:
+            self._ok(self.adb.keyevent(device.adb_serial, "KEYCODE_ENTER"), "insert tag separator newline")
+            self._ok(self.adb.keyevent(device.adb_serial, "KEYCODE_ENTER"), "insert tag separator newline")
+            time.sleep(0.2)
+        for hashtag in hashtags:
+            tag_text = hashtag[1:] if hashtag.startswith("#") else hashtag
+            self._input_adb_text(device, "#", "type hashtag marker")
+            if tag_text:
+                appium.set_clipboard(tag_text)
+                self._ok(self.adb.keyevent(device.adb_serial, "KEYCODE_PASTE"), "paste hashtag text")
+            self._input_adb_text(device, " ", "type hashtag separator")
+            time.sleep(0.2)
+
+    def _input_adb_text(self, device: Device, text: str, action: str) -> None:
+        result = self.adb.input_text(device.adb_serial, text)
+        if not result.ok:
+            raise RuntimeError(f"{action} failed: {result.stderr or result.stdout}")
+
+    def _find_and_click_text_field(self, appium: AppiumClient, name: str, selector: str, errors: list[str]) -> str:
+        for using, value in self._text_field_locators(name, selector):
+            try:
+                field_id = appium.find_element(using, value)
+                appium.click(field_id)
+                return field_id
+            except Exception as exc:
+                errors.append(f"appium_{using}_find_click failed: {_short(str(exc))}")
+        return ""
+
+    def _text_field_locators(self, name: str, selector: str) -> list[tuple[str, str]]:
+        locators = [("id", selector)]
+        if name == "title":
+            locators.extend(
+                [
+                    ("xpath", "//android.widget.EditText[@text='添加标题']"),
+                    ("xpath", "(//android.widget.EditText)[1]"),
+                ]
+            )
+        elif name == "caption":
+            locators.extend(
+                [
+                    ("xpath", "//android.widget.EditText[contains(@text, '添加正文')]"),
+                    ("xpath", "(//android.widget.EditText)[2]"),
+                ]
+            )
+        return locators
+
+    def _tap_text_field_from_ui_dump(self, device: Device, name: str, selector: str, run_dir: Path) -> bool:
+        try:
+            root = ui.dump_ui(self.adb, device, run_dir / f"{name}-field-before-input.xml")
+            suffix = selector.rsplit(":id/", 1)[-1]
+            node = ui.find_node(root, ids={selector}, id_suffixes={suffix}, clickable_only=False)
+            if node is None:
+                node = self._find_edit_text_from_ui_dump(root, name)
+            if node is None:
+                return False
+            ui.tap_node(self.adb, device, node)
+            return True
+        except Exception:
+            return False
+
+    def _find_edit_text_from_ui_dump(self, root, name: str):
+        fallback = FIELD_PLACEHOLDERS.get(name)
+        if not fallback:
+            return None
+        exact = fallback["exact"]
+        partial = fallback["partial"]
+        edit_texts = []
+        for node in root.iter("node"):
+            if node.attrib.get("class") != "android.widget.EditText" or not ui.is_visible(node):
+                continue
+            text = node.attrib.get("text", "")
+            desc = node.attrib.get("content-desc", "")
+            haystack = f"{text}\n{desc}".lower()
+            if text in exact or desc in exact or any(part.lower() in haystack for part in partial):
+                return node
+            edit_texts.append(node)
+        index = int(fallback["index"])
+        edit_texts = ui.sorted_visible_nodes(edit_texts)
+        if 0 <= index < len(edit_texts):
+            return edit_texts[index]
+        return None
+
+    def _require_current_post_form(self, device: Device) -> None:
+        focus = self.adb.current_focus(device.adb_serial)
+        if not any(keyword in focus for keyword in self._keywords("post_form_focus_keywords")):
+            raise RuntimeError(f"resume_post_form requires Xiaohongshu post form; current_focus={focus}")
+
+    def _open_latest_own_note_for_link(self, device: Device, run_dir: Path) -> None:
+        focus = self.adb.current_focus(device.adb_serial)
+        if self.package not in focus:
+            self._launch_xiaohongshu(device)
+
+        self._dismiss_link_recovery_prompts(device, run_dir)
+        focus = self.adb.current_focus(device.adb_serial)
+        if any(keyword in focus for keyword in self._keywords("detail_focus_keywords")):
+            return
+
+        self._open_me_tab(device, run_dir)
+        self._dismiss_link_recovery_prompts(device, run_dir)
+        self._tap_latest_profile_note(device, run_dir)
+        self._wait_for_detail_screen(device, run_dir)
+
+    def _dismiss_link_recovery_prompts(self, device: Device, run_dir: Path) -> None:
+        for idx in range(2):
+            try:
+                root = ui.dump_ui(self.adb, device, run_dir / f"link-recovery-prompt-{idx + 1}.xml")
+            except Exception:
+                return
+            all_text = ui.all_text(root)
+            node = ui.find_node(
+                root,
+                texts={"关闭", "取消", "以后再说", "跳过"},
+                partial_texts={"以后再说", "暂不", "跳过"},
+            )
+            if node is not None:
+                ui.tap_node(self.adb, device, node, sleep_s=self._wait("after_prompt_dismiss"))
+                continue
+            if any(marker in all_text for marker in ("发布成功", "完善个人资料", "上传头像", "填写名字")):
+                self._tap_coord_or_default(
+                    device,
+                    "post_publish_prompt_close",
+                    self._relative_coord(0.945, 0.5),
+                    self._wait("after_prompt_dismiss"),
+                )
+                continue
+            return
+
+    def _open_me_tab(self, device: Device, run_dir: Path) -> None:
+        try:
+            root = ui.dump_ui(self.adb, device, run_dir / "before-me-tab.xml")
+            node = self._find_bottom_tab(root, {"我"})
+            if node is not None:
+                ui.tap_node(self.adb, device, node, sleep_s=self._wait("after_me_tab"))
+            else:
+                self._tap_coord_or_default(device, "bottom_me", self._relative_coord(0.9, 0.93), self._wait("after_me_tab"))
+        except Exception:
+            self._tap_coord_or_default(device, "bottom_me", self._relative_coord(0.9, 0.93), self._wait("after_me_tab"))
+        self.adb.screenshot(device.adb_serial, run_dir / "profile.png")
+
+    def _tap_latest_profile_note(self, device: Device, run_dir: Path) -> None:
+        for attempt in range(3):
+            root = ui.dump_ui(self.adb, device, run_dir / f"profile-before-latest-note-{attempt + 1}.xml")
+            node = self._find_latest_profile_note_node(root)
+            if node is not None:
+                ui.tap_node(self.adb, device, node, sleep_s=self._wait("after_latest_note_tap"))
+                self.adb.screenshot(device.adb_serial, run_dir / "latest-note-opened.png")
+                return
+            time.sleep(1)
+        self._tap_coord_or_default(
+            device,
+            "profile_latest_note",
+            self._relative_coord(0.25, 0.53),
+            self._wait("after_latest_note_tap"),
+        )
+        self.adb.screenshot(device.adb_serial, run_dir / "latest-note-opened.png")
+
+    def _wait_for_detail_screen(self, device: Device, run_dir: Path) -> None:
+        timeout = self._wait("detail_load_timeout")
+        deadline = time.time() + timeout
+        last_focus = ""
+        while time.time() < deadline:
+            focus = self.adb.current_focus(device.adb_serial)
+            if focus:
+                last_focus = focus
+            if any(keyword in focus for keyword in self._keywords("detail_focus_keywords")):
+                return
+            time.sleep(0.5)
+        self.adb.screenshot(device.adb_serial, run_dir / "latest-note-detail-timeout.png")
+        raise RuntimeError(f"latest own Xiaohongshu note did not open; current_focus={last_focus}")
+
+    def _find_bottom_tab(self, root, labels: set[str]):
+        _width, height = self._screen_size()
+        min_top = int(height * 0.72)
+        for node in root.iter("node"):
+            if not ui.is_visible(node):
+                continue
+            value = node.attrib.get("text", "") or node.attrib.get("content-desc", "")
+            if value not in labels:
+                continue
+            bounds = ui.bounds(node)
+            if bounds and bounds[1] >= min_top:
+                return node
+        return None
+
+    def _find_latest_profile_note_node(self, root):
+        width, height = self._screen_size()
+        min_top = self._profile_note_min_top(root, height)
+        bottom_guard = int(height * 0.08)
+        candidates = []
+        image_candidates = []
+        blocked_text = {"首页", "购物", "发布", "消息", "我", "关注", "编辑资料", "设置"}
+
+        for node in root.iter("node"):
+            bounds = ui.bounds(node)
+            if not bounds or not ui.is_visible(node):
+                continue
+            left, top, right, bottom = bounds
+            node_width = right - left
+            node_height = bottom - top
+            if top < min_top or bottom > height - bottom_guard:
+                continue
+            if node_width < int(width * 0.16) or node_height < 140:
+                continue
+            text = node.attrib.get("text", "")
+            desc = node.attrib.get("content-desc", "")
+            if text in blocked_text or desc in blocked_text:
+                continue
+            item = (top, left, node)
+            if node.attrib.get("clickable") == "true":
+                candidates.append(item)
+            elif node.attrib.get("class") == "android.widget.ImageView":
+                image_candidates.append(item)
+
+        chosen = candidates or image_candidates
+        if not chosen:
+            return None
+        return sorted(chosen, key=lambda item: (item[0], item[1]))[0][2]
+
+    def _profile_note_min_top(self, root, height: int) -> int:
+        min_top = int(height * 0.35)
+        for node in root.iter("node"):
+            value = node.attrib.get("text", "") or node.attrib.get("content-desc", "")
+            if value not in {"笔记", "作品"}:
+                continue
+            bounds = ui.bounds(node)
+            if bounds:
+                min_top = max(min_top, bounds[3] + 20)
+        return min_top
+
+    def _tap_first_publish(self, device: Device) -> None:
+        self._tap_coord(device, "first_publish", 0)
+        time.sleep(self._wait("after_first_publish"))
+
+    def _tap_confirm_publish(self, device: Device) -> None:
+        self._tap_coord(device, "confirm_publish", 0)
+
+    def _tap_copy_link(self, device: Device, run_dir: Path) -> None:
+        xml_path = run_dir / "share-sheet.xml"
+        try:
+            root = ui.dump_ui(self.adb, device, xml_path)
+            node = ui.find_node(root, texts={"复制链接", "Copy link"}, partial_texts={"复制链接", "copy link"})
+            if node is not None:
+                ui.tap_node(self.adb, device, node)
+                return
+        except Exception:
+            pass
+        self._tap_coord(device, "copy_link", 0)
+
+    def _read_copied_link(self, device: Device, run_dir: Path) -> tuple[str, str, str]:
+        errors: list[str] = []
+
+        result = self.adb.shell(device.adb_serial, "cmd", "clipboard", "get")
+        if result.ok:
+            link = _extract_url(result.stdout)
+            if link:
+                return link, "adb_cmd_clipboard", ""
+            errors.append("adb_cmd_clipboard returned no URL")
+        else:
+            errors.append(f"adb_cmd_clipboard failed: {_short(result.stderr or result.stdout)}")
+
+        result = self.adb.shell(device.adb_serial, "dumpsys", "clipboard")
+        if result.ok:
+            link = _extract_url(result.stdout)
+            if link:
+                return link, "adb_dumpsys_clipboard", ""
+            errors.append("adb_dumpsys_clipboard returned no URL")
+        else:
+            errors.append(f"adb_dumpsys_clipboard failed: {_short(result.stderr or result.stdout)}")
+
+        link = self._read_link_by_paste_probe(device, run_dir)
+        if link:
+            return link, "paste_probe_ui_dump", ""
+        errors.append("paste_probe_ui_dump returned no URL")
+
+        appium = AppiumClient(self.appium_server)
+        try:
+            appium.start_session(_appium_capabilities(device.adb_serial))
+            text = appium.get_clipboard()
+            link = _extract_url(text)
+            if link:
+                return link, "appium_get_clipboard", ""
+            errors.append("appium_get_clipboard returned no URL")
+        except Exception as exc:
+            errors.append(f"appium_get_clipboard failed: {_short(str(exc))}")
+        finally:
+            try:
+                appium.delete_session()
+            except Exception:
+                pass
+
+        return "", "", "; ".join(errors)
+
+    def _read_link_by_paste_probe(self, device: Device, run_dir: Path) -> str:
+        opened_input = False
+        try:
+            xml_path = run_dir / "before-paste-probe.xml"
+            root = ui.dump_ui(self.adb, device, xml_path)
+            node = self._find_comment_input_node(root)
+            if node is None:
+                comment_entry = ui.find_node(
+                    root,
+                    id_suffixes={"noteCommentLayout", "commentLayout"},
+                    partial_texts={"评论"},
+                    clickable_only=True,
+                )
+                if comment_entry is not None:
+                    ui.tap_node(self.adb, device, comment_entry, sleep_s=self._wait("after_comment_input_tap"))
+                else:
+                    self._tap_coord_or_default(
+                        device,
+                        "comment_input",
+                        self._relative_coord(0.9, 0.97),
+                        self._wait("after_comment_input_tap"),
+                    )
+                root = ui.dump_ui(self.adb, device, run_dir / "comment-panel-before-paste.xml")
+                node = self._find_comment_input_node(root)
+            if node is not None:
+                ui.tap_node(self.adb, device, node, sleep_s=self._wait("after_comment_input_tap"))
+            opened_input = True
+
+            self.adb.keyevent(device.adb_serial, "KEYCODE_PASTE")
+            time.sleep(self._wait("after_paste_probe"))
+            pasted_xml = run_dir / "paste-probe.xml"
+            root = ui.dump_ui(self.adb, device, pasted_xml)
+            self.adb.screenshot(device.adb_serial, run_dir / "paste-probe.png")
+            return _extract_url(ui.all_text(root))
+        except Exception:
+            return ""
+        finally:
+            if opened_input:
+                self.adb.keyevent(device.adb_serial, "KEYCODE_BACK")
+                time.sleep(0.3)
+                self.adb.keyevent(device.adb_serial, "KEYCODE_BACK")
+                time.sleep(0.3)
+
+    def _find_comment_input_node(self, root):
+        node = ui.find_node(
+            root,
+            id_suffixes={"mContentET", "commentEditText", "commentInputEditText"},
+            partial_texts={"留下你的想法", "留下你的评论", "说点什么", "友善评论"},
+        )
+        if node is not None:
+            return node
+        for candidate in root.iter("node"):
+            if candidate.attrib.get("class") != "android.widget.EditText" or not ui.is_visible(candidate):
+                continue
+            text = candidate.attrib.get("text", "")
+            desc = candidate.attrib.get("content-desc", "")
+            haystack = f"{text}\n{desc}"
+            if any(marker in haystack for marker in ("评论", "想法", "说点")) or not text.strip():
+                return candidate
+        return None
+
+    def _wait_for_publish_complete(self, device: Device, run_dir: Path) -> Path:
+        timeout = self._wait("publish_timeout")
+        interval = max(0.5, self._wait("publish_poll_interval"))
+        success_keywords = self._keywords("success_focus_keywords")
+        in_progress_keywords = self._keywords("in_progress_focus_keywords")
+        deadline = time.time() + timeout
+        last_focus = ""
+
+        while time.time() < deadline:
+            focus = self.adb.current_focus(device.adb_serial)
+            if focus:
+                last_focus = focus
+            if any(keyword in focus for keyword in success_keywords):
+                final_shot = run_dir / "after-post.png"
+                self.adb.screenshot(device.adb_serial, final_shot)
+                return final_shot
+            if self.package in focus and not any(keyword in focus for keyword in in_progress_keywords):
+                final_shot = run_dir / "after-post.png"
+                self.adb.screenshot(device.adb_serial, final_shot)
+                return final_shot
+            time.sleep(interval)
+
+        timeout_shot = run_dir / "after-post-timeout.png"
+        self.adb.screenshot(device.adb_serial, timeout_shot)
+        raise RuntimeError(
+            f"Xiaohongshu publish completion not confirmed within {int(timeout)}s; "
+            f"last_focus={last_focus}"
+        )
+
+    def _tap_coord(self, device: Device, name: str, sleep_s: float) -> None:
+        x, y = self._coord(name)
+        self._tap(device, x, y, sleep_s)
+
+    def _tap_coord_or_default(self, device: Device, name: str, default: tuple[int, int], sleep_s: float) -> None:
+        try:
+            x, y = self._coord(name)
+        except Exception:
+            x, y = default
+        self._tap(device, x, y, sleep_s)
+
+    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)
+
+    def _coord(self, name: str) -> list[int]:
+        coords = self.flow_config.get("coords", {})
+        value = coords.get(name) if isinstance(coords, dict) else None
+        if not isinstance(value, list) or not value or not all(isinstance(item, int) for item in value):
+            raise RuntimeError(f"missing or invalid Xiaohongshu coord: {name}")
+        return value
+
+    def _multi_image_coords(self) -> list[list[int]]:
+        coords = self.flow_config.get("coords", {})
+        value = coords.get("multi_image_select") if isinstance(coords, dict) else None
+        if value is None:
+            value = DEFAULT_FLOW_CONFIG["coords"]["multi_image_select"]
+        if not isinstance(value, list) or not value:
+            raise RuntimeError("missing Xiaohongshu multi_image_select coords")
+        out: list[list[int]] = []
+        for item in value:
+            if not isinstance(item, list) or len(item) != 2 or not all(isinstance(part, int) for part in item):
+                raise RuntimeError("invalid Xiaohongshu multi_image_select coords")
+            out.append(item)
+        return out
+
+    def _selector(self, name: str) -> str:
+        selectors = self.flow_config.get("selectors", {})
+        value = selectors.get(name) if isinstance(selectors, dict) else None
+        if not isinstance(value, str) or not value:
+            raise RuntimeError(f"missing Xiaohongshu selector: {name}")
+        return value
+
+    def _wait(self, name: str) -> float:
+        waits = self.flow_config.get("waits", {})
+        value = waits.get(name) if isinstance(waits, dict) else None
+        if isinstance(value, (int, float)):
+            return float(value)
+        default = DEFAULT_FLOW_CONFIG["waits"].get(name, 0)
+        return float(default)
+
+    def _screen_size(self) -> tuple[int, int]:
+        screen = self.flow_config.get("screen", {})
+        width = screen.get("width") if isinstance(screen, dict) else None
+        height = screen.get("height") if isinstance(screen, dict) else None
+        if isinstance(width, int) and isinstance(height, int) and width > 0 and height > 0:
+            return width, height
+        return 1080, 2400
+
+    def _relative_coord(self, x_ratio: float, y_ratio: float) -> tuple[int, int]:
+        width, height = self._screen_size()
+        return int(width * x_ratio), int(height * y_ratio)
+
+    def _keywords(self, name: str) -> list[str]:
+        value = self.flow_config.get(name)
+        if isinstance(value, list):
+            return [item for item in value if isinstance(item, str) and item]
+        default = DEFAULT_FLOW_CONFIG.get(name, [])
+        return [item for item in default if isinstance(item, str)]
+
+    @staticmethod
+    def _ok(result, action: str) -> None:
+        if not result.ok:
+            raise RuntimeError(f"{action} failed: {result.stderr or result.stdout}")
+
+
+def _load_flow_config(path: str | Path) -> dict:
+    config = copy.deepcopy(DEFAULT_FLOW_CONFIG)
+    config_path = Path(path)
+    if not config_path.exists():
+        return config
+
+    with config_path.open("r", encoding="utf-8") as handle:
+        loaded = json.load(handle)
+    if not isinstance(loaded, dict):
+        raise RuntimeError(f"Xiaohongshu flow config must be a JSON object: {config_path}")
+    _deep_merge(config, loaded)
+    return config
+
+
+def _deep_merge(base: dict, updates: dict) -> None:
+    for key, value in updates.items():
+        if isinstance(value, dict) and isinstance(base.get(key), dict):
+            _deep_merge(base[key], value)
+        else:
+            base[key] = value
+
+
+def _normalize_post_type(value: str) -> str:
+    text = value.strip().lower().replace("_", "-")
+    aliases = {
+        "photo": "image",
+        "picture": "image",
+        "image": "image",
+        "video": "video",
+    }
+    if text in aliases:
+        return aliases[text]
+    raise ValueError("Xiaohongshu post_type must be one of: image, video")
+
+
+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 _caption(title: str, caption: str) -> str:
+    return f"{title} | {caption}" if caption else title
+
+
+def _compose_caption_for_record(caption: str, tags: list[str], topics: list[str]) -> str:
+    body = (caption or "").strip()
+    hashtags = " ".join(_format_manual_hashtags([*tags, *topics], existing=body))
+    if body and hashtags:
+        return f"{body}\n\n{hashtags}"
+    return body or hashtags
+
+
+def _normalize_hashtag_values(values: list[str]) -> list[str]:
+    seen: set[str] = set()
+    out: list[str] = []
+    for value in values:
+        text = re.sub(r"\s+", "", str(value or "").strip())
+        if not text:
+            continue
+        normalized = text[1:] if text.startswith("#") else text
+        if not normalized:
+            continue
+        key = normalized.lower()
+        if key in seen:
+            continue
+        seen.add(key)
+        out.append(normalized)
+    return out
+
+
+def _format_manual_hashtags(values: list[str], *, existing: str = "") -> list[str]:
+    out: list[str] = []
+    for value in _normalize_hashtag_values(values):
+        tag = value if value.startswith("#") else f"#{value}"
+        if tag in existing:
+            continue
+        out.append(tag)
+    return out
+
+
+def _extract_url(text: str) -> str:
+    for raw in re.findall(r"https?://[^\s\"'<>]+", text or ""):
+        url = raw.rstrip(").,;，。]")
+        lowered = url.lower()
+        if any(marker in lowered for marker in ("xiaohongshu", "xhslink", "xhs.cn", "xhs")):
+            return url
+    urls = re.findall(r"https?://[^\s\"'<>]+", text or "")
+    return urls[0].rstrip(").,;，。]") if urls else ""
+
+
+def _short(text: str, limit: int = 220) -> str:
+    one_line = " ".join((text or "").split())
+    return one_line if len(one_line) <= limit else one_line[: limit - 3] + "..."
+
+
+def _now_shanghai() -> str:
+    return datetime.now(ZoneInfo("Asia/Shanghai")).strftime("%Y-%m-%d %H:%M:%S %z")