@11agents/cli 0.1.24 → 0.1.26

package/mobile-runtime/python/src/device_control/cli.py

@@ -0,0 +1,1608 @@
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from dataclasses import asdict
+from pathlib import Path
+
+from .adb import AdbClient, resolve_adb_bin
+from .adapters import default_registry
+from .appium_manager import AppiumEnsureError, ensure_appium_server, stop_managed_appium
+from .locks import DeviceLockError, device_lock, publish_slot
+from .metrics import (
+    MetricsCollectionError,
+    TikTokAccountMetricsAdbCollector,
+    TikTokVideoMetricsAdbCollector,
+    build_manual_snapshot,
+    collect_with_default_collector,
+    parse_manual_values_json,
+    parse_manual_video_values_json,
+    parse_platform_post_id,
+)
+from .models import PublishRecord, new_id, utc_now_iso
+from .publish_policy import (
+    DEFAULT_PUBLISH_POLICY_PATH,
+    decide_xiaohongshu_publish_package_policy,
+    load_publish_policy,
+    should_auto_confirm_instagram_reels_public,
+    should_auto_confirm_xiaohongshu_no_disclosure,
+    xiaohongshu_package_disclosure_is_strict,
+)
+from .publishers import (
+    FacebookAdbPublisher,
+    InstagramAdbPublisher,
+    RedditAdbPublisher,
+    TikTokAdbPublisher,
+    TikTokAppiumPublisher,
+    XAdbPublisher,
+    XiaohongshuAdbPublisher,
+)
+from .store import (
+    append_metrics_snapshot,
+    append_publish_record,
+    append_tiktok_account_metrics_snapshot,
+    append_tiktok_video_metrics_snapshot,
+    load_devices,
+    load_metrics_snapshots,
+    load_publish_records,
+    load_tiktok_account_metrics_snapshots,
+    load_tiktok_video_metrics_snapshots,
+    load_tasks,
+    write_publish_records,
+)
+
+
+MAX_PARALLEL_DEVICES = 5
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="groupctl")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("doctor", help="Check local CLI prerequisites")
+
+    sub.add_parser("list-adb", help="List currently connected ADB devices")
+
+    ensure_appium_p = sub.add_parser("ensure-appium", help="Start/reuse Appium and verify UiAutomator2 session readiness")
+    ensure_appium_p.add_argument("--devices", default="data/devices.csv")
+    ensure_appium_p.add_argument("--server", default="http://127.0.0.1:4723")
+    ensure_appium_p.add_argument("--device", action="append", default=[], help="Device id for smoke session, e.g. D01. Can be repeated.")
+    ensure_appium_p.add_argument("--udid", action="append", default=[], help="ADB serial for smoke session. Can be repeated.")
+    ensure_appium_p.add_argument("--no-start", action="store_true", help="Only check an existing Appium server.")
+    ensure_appium_p.add_argument("--restart", action="store_true", help="Restart the project-managed Appium server before checking.")
+    ensure_appium_p.add_argument("--no-smoke", action="store_true", help="Skip UiAutomator2 session smoke checks.")
+    ensure_appium_p.add_argument("--json", action="store_true", help="Print JSON")
+
+    stop_appium_p = sub.add_parser("stop-appium", help="Stop the project-managed local Appium server")
+    stop_appium_p.add_argument("--server", default="http://127.0.0.1:4723")
+    stop_appium_p.add_argument(
+        "--allow-unmanaged-appium",
+        action="store_true",
+        help="Also stop a local process on this port if its command line contains appium.",
+    )
+    stop_appium_p.add_argument("--json", action="store_true", help="Print JSON")
+
+    list_devices_p = sub.add_parser("list-devices", help="List managed devices from CSV")
+    list_devices_p.add_argument("--devices", default="data/devices.csv")
+    list_devices_p.add_argument("--health", action="store_true", help="Include online/battery/current focus")
+    list_devices_p.add_argument("--json", action="store_true", help="Print JSON lines")
+
+    init_p = sub.add_parser("init-one-device", help="Write a one-device CSV from first connected ADB device")
+    init_p.add_argument("--out", default="data/devices.csv")
+    init_p.add_argument("--device-id", default="D01")
+
+    connect_p = sub.add_parser("connect", help="Connect devices from CSV")
+    connect_p.add_argument("--devices", default="data/devices.csv")
+
+    health_p = sub.add_parser("health", help="Show device health from CSV")
+    health_p.add_argument("--devices", default="data/devices.csv")
+
+    screenshot_p = sub.add_parser("screenshot", help="Take screenshot from one device")
+    screenshot_p.add_argument("device_id")
+    screenshot_p.add_argument("--devices", default="data/devices.csv")
+    screenshot_p.add_argument("--out-dir", default="artifacts/screenshots")
+
+    dump_p = sub.add_parser("dump-ui", help="Dump uiautomator XML from one device")
+    dump_p.add_argument("device_id")
+    dump_p.add_argument("--devices", default="data/devices.csv")
+    dump_p.add_argument("--out-dir", default="artifacts/ui")
+
+    tap_p = sub.add_parser("tap", help="Tap coordinates on one device")
+    tap_p.add_argument("device_id")
+    tap_p.add_argument("x", type=int)
+    tap_p.add_argument("y", type=int)
+    tap_p.add_argument("--devices", default="data/devices.csv")
+
+    key_p = sub.add_parser("keyevent", help="Send Android keyevent to one device")
+    key_p.add_argument("device_id")
+    key_p.add_argument("keycode")
+    key_p.add_argument("--devices", default="data/devices.csv")
+
+    text_p = sub.add_parser("input-text", help="Input text on one device")
+    text_p.add_argument("device_id")
+    text_p.add_argument("text")
+    text_p.add_argument("--devices", default="data/devices.csv")
+
+    launch_p = sub.add_parser("launch", help="Launch an Android package on one device")
+    launch_p.add_argument("device_id")
+    launch_p.add_argument("package")
+    launch_p.add_argument("--devices", default="data/devices.csv")
+
+    plan_p = sub.add_parser("plan-task", help="Print adapter steps for a task")
+    plan_p.add_argument("--tasks", default="data/tasks.jsonl")
+    plan_p.add_argument("--index", type=int, default=0)
+
+    record_p = sub.add_parser("record-publish", help="Append one published post tracking record")
+    record_p.add_argument("--records", default="data/publish_records.jsonl")
+    record_p.add_argument("--record-id")
+    record_p.add_argument("--task-id", default="")
+    record_p.add_argument("--platform", required=True)
+    record_p.add_argument("--account-id", required=True)
+    record_p.add_argument("--device-id", required=True)
+    record_p.add_argument("--post-type", default="video")
+    record_p.add_argument("--local-media-path", default="")
+    record_p.add_argument("--remote-media-path", default="")
+    record_p.add_argument("--platform-post-id", default="")
+    record_p.add_argument("--platform-permalink", default="")
+    record_p.add_argument("--caption", default="")
+    record_p.add_argument("--published-at")
+    record_p.add_argument("--result-screenshot-path", default="")
+    record_p.add_argument("--status", default="published")
+
+    list_records_p = sub.add_parser("list-publish-records", help="Print publish records")
+    list_records_p.add_argument("--records", default="data/publish_records.jsonl")
+    list_records_p.add_argument("--platform")
+    list_records_p.add_argument("--account-id")
+
+    update_record_p = sub.add_parser("update-publish-record", help="Update post id/permalink for one publish record")
+    update_record_p.add_argument("--records", default="data/publish_records.jsonl")
+    update_record_p.add_argument("--record-id", required=True)
+    update_record_p.add_argument("--platform-post-id", default="")
+    update_record_p.add_argument("--platform-permalink", default="")
+    update_record_p.add_argument("--caption", default=None)
+    update_record_p.add_argument("--published-at", default=None)
+    update_record_p.add_argument("--result-screenshot-path", default=None)
+    update_record_p.add_argument("--status", default=None)
+
+    add_metrics_p = sub.add_parser("add-metrics", help="Append one manual metrics snapshot")
+    add_metrics_p.add_argument("--records", default="data/publish_records.jsonl")
+    add_metrics_p.add_argument("--metrics", default="data/video_metrics.jsonl")
+    add_metrics_p.add_argument("--record-id", required=True)
+    add_metrics_p.add_argument("--views", type=int)
+    add_metrics_p.add_argument("--likes", type=int)
+    add_metrics_p.add_argument("--comments", type=int)
+    add_metrics_p.add_argument("--shares", type=int)
+    add_metrics_p.add_argument("--saves", type=int)
+    add_metrics_p.add_argument("--score", type=int)
+    add_metrics_p.add_argument("--raw-json", default="{}")
+
+    collect_metrics_p = sub.add_parser("collect-metrics", help="Collect metrics for published records")
+    collect_metrics_p.add_argument("--records", default="data/publish_records.jsonl")
+    collect_metrics_p.add_argument("--metrics", default="data/video_metrics.jsonl")
+    collect_metrics_p.add_argument("--record-id")
+    collect_metrics_p.add_argument("--platform")
+    collect_metrics_p.add_argument("--account-id")
+
+    list_metrics_p = sub.add_parser("list-metrics", help="Print metrics snapshots")
+    list_metrics_p.add_argument("--metrics", default="data/video_metrics.jsonl")
+    list_metrics_p.add_argument("--record-id")
+
+    collect_tiktok_account_p = sub.add_parser(
+        "collect-tiktok-account-metrics-adb",
+        help="Collect TikTok Studio account overview metrics through ADB",
+    )
+    collect_tiktok_account_p.add_argument("--devices", default="data/devices.csv")
+    collect_tiktok_account_p.add_argument("--out", default="data/tiktok_account_metrics.jsonl")
+    collect_tiktok_account_p.add_argument("--artifact-root", default="artifacts/screenshots")
+    collect_tiktok_account_p.add_argument("--device", required=True, help="Device id, e.g. D01.")
+    collect_tiktok_account_p.add_argument("--account-id", default="", help="Current logged-in TikTok account id.")
+    collect_tiktok_account_p.add_argument("--account-prefix", default="tiktok", help="Fallback account id prefix.")
+    collect_tiktok_account_p.add_argument(
+        "--period",
+        action="append",
+        choices=["7d", "28d", "60d"],
+        default=[],
+        help="Period to collect. Repeatable; default is 7d, 28d, 60d.",
+    )
+    collect_tiktok_account_p.add_argument(
+        "--resume-analytics",
+        action="store_true",
+        help="Assume TikTok Studio Analytics overview is already open and skip navigation.",
+    )
+    collect_tiktok_account_p.add_argument(
+        "--values-json",
+        default="",
+        help="Manual metric values JSON keyed by 7d/28d/60d after reviewing screenshots.",
+    )
+    collect_tiktok_account_p.add_argument(
+        "--values-file",
+        default="",
+        help="Path to manual metric values JSON keyed by 7d/28d/60d.",
+    )
+    collect_tiktok_account_p.add_argument(
+        "--allow-manual-required",
+        action="store_true",
+        help="Exit 0 after screenshot capture even if values still need human extraction.",
+    )
+    collect_tiktok_account_p.add_argument("--no-append", action="store_true", help="Do not append the snapshot JSONL row.")
+    collect_tiktok_account_p.add_argument("--json", action="store_true", help="Print JSON")
+
+    list_tiktok_account_p = sub.add_parser("list-tiktok-account-metrics", help="Print TikTok account metrics snapshots")
+    list_tiktok_account_p.add_argument("--metrics", default="data/tiktok_account_metrics.jsonl")
+    list_tiktok_account_p.add_argument("--account-id")
+    list_tiktok_account_p.add_argument("--device-id")
+
+    collect_tiktok_video_p = sub.add_parser(
+        "collect-tiktok-video-metrics-adb",
+        help="Collect one TikTok video insights snapshot through ADB",
+    )
+    collect_tiktok_video_p.add_argument("--devices", default="data/devices.csv")
+    collect_tiktok_video_p.add_argument("--out", default="data/tiktok_video_metrics.jsonl")
+    collect_tiktok_video_p.add_argument("--artifact-root", default="artifacts/screenshots")
+    collect_tiktok_video_p.add_argument("--device", required=True, help="Device id, e.g. D01.")
+    collect_tiktok_video_p.add_argument("--account-id", default="", help="Current logged-in TikTok account id.")
+    collect_tiktok_video_p.add_argument("--account-prefix", default="tiktok", help="Fallback account id prefix.")
+    collect_tiktok_video_p.add_argument("--video-order", type=int, default=1, help="1-based profile video order.")
+    collect_tiktok_video_p.add_argument(
+        "--resume-insights",
+        action="store_true",
+        help="Assume a TikTok video insights page is already open and skip navigation.",
+    )
+    collect_tiktok_video_p.add_argument(
+        "--values-json",
+        default="",
+        help="Manual video metric values JSON after reviewing the screenshot.",
+    )
+    collect_tiktok_video_p.add_argument("--values-file", default="", help="Path to manual video metric values JSON.")
+    collect_tiktok_video_p.add_argument(
+        "--allow-manual-required",
+        action="store_true",
+        help="Exit 0 after screenshot capture even if values still need human extraction.",
+    )
+    collect_tiktok_video_p.add_argument("--no-append", action="store_true", help="Do not append the snapshot JSONL row.")
+    collect_tiktok_video_p.add_argument("--json", action="store_true", help="Print JSON")
+
+    list_tiktok_video_p = sub.add_parser("list-tiktok-video-metrics", help="Print TikTok video metrics snapshots")
+    list_tiktok_video_p.add_argument("--metrics", default="data/tiktok_video_metrics.jsonl")
+    list_tiktok_video_p.add_argument("--account-id")
+    list_tiktok_video_p.add_argument("--device-id")
+    list_tiktok_video_p.add_argument("--published-at")
+
+    publish_tiktok_p = sub.add_parser("publish-tiktok-adb", help="Publish one video to TikTok through ADB-only POC flow")
+    publish_tiktok_p.add_argument("--devices", default="data/devices.csv")
+    publish_tiktok_p.add_argument("--records", default="data/publish_records.jsonl")
+    publish_tiktok_p.add_argument("--video", required=True)
+    publish_tiktok_p.add_argument("--caption", default="")
+    publish_tiktok_p.add_argument("--device", action="append", default=[], help="Device id, e.g. D01. Can be repeated.")
+    publish_tiktok_p.add_argument("--range", dest="ranges", action="append", default=[], help="Device range, e.g. 1-10 or D01-D10.")
+    publish_tiktok_p.add_argument("--account-id", default="", help="Single account id. Use only with one target device.")
+    publish_tiktok_p.add_argument("--account-prefix", default="tiktok", help="Fallback account id prefix for multi-device runs.")
+    publish_tiktok_p.add_argument("--dry-run", action="store_true", help="Stop at TikTok post form without tapping publish.")
+    publish_tiktok_p.add_argument(
+        "--allow-caption-fallback",
+        action="store_true",
+        help="Publish even if caption input fails. Without this flag, caption failures stop before publish.",
+    )
+    publish_tiktok_p.add_argument("--parallel", action="store_true", help="Run target devices concurrently. Hard-capped at 5.")
+    publish_tiktok_p.add_argument("--max-concurrency", type=int, default=MAX_PARALLEL_DEVICES, help="Max concurrent devices, 1-5.")
+    publish_tiktok_p.add_argument("--json", action="store_true", help="Print JSON lines")
+
+    publish_tiktok_default_p = sub.add_parser("publish-tiktok", help="Publish one video to TikTok through the default Appium flow")
+    _add_publish_tiktok_appium_args(publish_tiktok_default_p)
+
+    publish_tiktok_appium_p = sub.add_parser("publish-tiktok-appium", help="Publish one video to TikTok through Appium POC flow")
+    _add_publish_tiktok_appium_args(publish_tiktok_appium_p)
+
+    publish_reddit_adb_p = sub.add_parser("publish-reddit-adb", help="Publish one Reddit post through ADB/App selector POC flow")
+    _add_publish_reddit_args(publish_reddit_adb_p)
+
+    publish_reddit_p = sub.add_parser("publish-reddit", help="Publish one Reddit post through the safe local POC flow")
+    _add_publish_reddit_args(publish_reddit_p)
+
+    publish_facebook_p = sub.add_parser("publish-facebook", help="Publish one Facebook Lite post through the local POC flow")
+    _add_publish_facebook_args(publish_facebook_p)
+
+    publish_instagram_p = sub.add_parser("publish-instagram", help="Publish one Instagram Reels or feed Post through the D03 POC flow")
+    _add_publish_instagram_args(publish_instagram_p)
+
+    publish_x_p = sub.add_parser("publish-x", help="Publish one X text, link, or image post through the local POC flow")
+    _add_publish_x_args(publish_x_p)
+
+    publish_xhs_p = sub.add_parser("publish-xiaohongshu", help="Publish one image or video note to Xiaohongshu through a configured device flow")
+    _add_publish_xiaohongshu_args(publish_xhs_p)
+
+    copy_xhs_link_p = sub.add_parser("copy-xiaohongshu-link", help="Copy a Xiaohongshu note link; from home it opens Me and the latest note first")
+    copy_xhs_link_p.add_argument("--devices", default="data/devices.csv")
+    copy_xhs_link_p.add_argument("--records", default="data/publish_records.jsonl")
+    copy_xhs_link_p.add_argument("--appium-server", default="http://127.0.0.1:4723")
+    _add_appium_preflight_args(copy_xhs_link_p)
+    copy_xhs_link_p.add_argument("--flow-config", default="configs/platforms/xiaohongshu_d03.json")
+    copy_xhs_link_p.add_argument("--device", required=True, help="Device id, e.g. D03.")
+    copy_xhs_link_p.add_argument("--record-id", default="", help="Update this publish record when a URL is retrieved.")
+    copy_xhs_link_p.add_argument("--json", action="store_true", help="Print JSON")
+
+    args = parser.parse_args()
+    adb = AdbClient()
+
+    if args.command == "doctor":
+        print(f"adb_bin={resolve_adb_bin()}")
+        try:
+            result = adb.run("version")
+            print(result.stdout or result.stderr)
+        except FileNotFoundError:
+            print("adb_status=missing")
+            print("hint=install Android platform-tools or set ADB_BIN")
+            return
+        devices = adb.list_devices()
+        print(f"connected_devices={len(devices)}")
+        for serial in devices:
+            print(f"- {serial}")
+        return
+
+    if args.command == "list-adb":
+        for serial in adb.list_devices():
+            print(serial)
+        return
+
+    if args.command == "ensure-appium":
+        udids = _resolve_appium_udids(args.devices, args.device, args.udid)
+        try:
+            result = ensure_appium_server(
+                args.server,
+                udids=udids,
+                start=not args.no_start,
+                restart=args.restart,
+                smoke=not args.no_smoke,
+            )
+        except AppiumEnsureError as exc:
+            row = {"status": "failed", "server_url": args.server, "message": str(exc)}
+            if args.json:
+                print(json.dumps(row, ensure_ascii=False, sort_keys=True))
+            else:
+                print(f"status=failed server={args.server} error={exc}")
+            raise SystemExit(1) from exc
+        row = result.to_dict()
+        if args.json:
+            print(json.dumps(row, ensure_ascii=False, sort_keys=True))
+        else:
+            print(
+                f"status={result.status} server={result.server_url} pid={result.pid or ''} "
+                f"sdk={result.android_sdk_root} appium={result.appium_bin} log={result.log_path}"
+            )
+            if result.smoke_udids:
+                print(f"smoke_udids={','.join(result.smoke_udids)}")
+        return
+
+    if args.command == "stop-appium":
+        stopped = stop_managed_appium(args.server, allow_unmanaged_appium=args.allow_unmanaged_appium)
+        row = {"status": "stopped" if stopped else "not_running", "server_url": args.server}
+        if args.json:
+            print(json.dumps(row, ensure_ascii=False, sort_keys=True))
+        else:
+            print(f"status={row['status']} server={args.server}")
+        return
+
+    if args.command == "list-devices":
+        devices = load_devices(args.devices)
+        connected = set(adb.list_devices()) if args.health else set()
+        for device in devices.values():
+            row = {
+                "device_id": device.device_id,
+                "adb_serial": device.adb_serial,
+                "ip_address": device.ip_address,
+                "brand": device.brand,
+                "model": device.model,
+                "android_version": device.android_version,
+                "status": device.status,
+                "notes": device.notes,
+            }
+            if args.health:
+                online = device.adb_serial in connected
+                row["online"] = online
+                if online:
+                    row["battery"] = adb.battery_level(device.adb_serial)
+                    row["focus"] = adb.current_focus(device.adb_serial)
+            if args.json:
+                print(json.dumps(row, ensure_ascii=False, sort_keys=True))
+            else:
+                suffix = ""
+                if args.health:
+                    suffix = f" online={row['online']} battery={row.get('battery', '')} focus={row.get('focus', '')}"
+                print(
+                    f"{device.device_id} serial={device.adb_serial} ip={device.ip_address} "
+                    f"model={device.model} status={device.status}{suffix}"
+                )
+        return
+
+    if args.command == "init-one-device":
+        devices = adb.list_devices()
+        if not devices:
+            raise SystemExit("No connected ADB device. Connect phone by USB, authorize debugging, then retry.")
+        serial = devices[0]
+        out = Path(args.out)
+        out.parent.mkdir(parents=True, exist_ok=True)
+        row = {
+            "device_id": args.device_id,
+            "adb_serial": serial,
+            "ip_address": _ip_from_serial(serial),
+            "brand": adb.getprop(serial, "ro.product.brand"),
+            "model": adb.getprop(serial, "ro.product.model"),
+            "android_version": adb.getprop(serial, "ro.build.version.release"),
+            "status": "active",
+            "notes": "single-device POC",
+        }
+        with out.open("w", newline="") as f:
+            writer = csv.DictWriter(f, fieldnames=list(row.keys()))
+            writer.writeheader()
+            writer.writerow(row)
+        print(f"wrote {out}")
+        return
+
+    if args.command == "connect":
+        devices = load_devices(args.devices)
+        for device in devices.values():
+            if device.status != "active":
+                print(f"{device.device_id}: skipped status={device.status}")
+                continue
+            result = adb.connect(device.adb_serial)
+            status = "ok" if result.ok else "fail"
+            print(f"{device.device_id} {device.adb_serial}: {status} {result.stdout or result.stderr}")
+        return
+
+    if args.command == "health":
+        devices = load_devices(args.devices)
+        connected = set(adb.list_devices())
+        for device in devices.values():
+            online = device.adb_serial in connected
+            if not online:
+                print(f"{device.device_id}: offline serial={device.adb_serial}")
+                continue
+            battery = adb.battery_level(device.adb_serial)
+            model = adb.getprop(device.adb_serial, "ro.product.model")
+            android = adb.getprop(device.adb_serial, "ro.build.version.release")
+            focus = adb.current_focus(device.adb_serial)
+            print(f"{device.device_id}: online battery={battery} model={model} android={android} focus={focus}")
+        return
+
+    if args.command == "screenshot":
+        device = _get_device(args.devices, args.device_id)
+        out = Path(args.out_dir) / f"{device.device_id}.png"
+        result = adb.screenshot(device.adb_serial, out)
+        if result.ok:
+            print(f"saved {out}")
+        else:
+            print(result.stderr or result.stdout)
+        return
+
+    if args.command == "dump-ui":
+        device = _get_device(args.devices, args.device_id)
+        out = Path(args.out_dir) / f"{device.device_id}.xml"
+        result = adb.dump_ui(device.adb_serial, out)
+        if result.ok:
+            print(f"saved {out}")
+        else:
+            print(result.stderr or result.stdout)
+            raise SystemExit(result.code)
+        return
+
+    if args.command == "tap":
+        device = _get_device(args.devices, args.device_id)
+        result = adb.tap(device.adb_serial, args.x, args.y)
+        print(result.stdout or result.stderr)
+        return
+
+    if args.command == "keyevent":
+        device = _get_device(args.devices, args.device_id)
+        result = adb.keyevent(device.adb_serial, args.keycode)
+        print(result.stdout or result.stderr)
+        return
+
+    if args.command == "input-text":
+        device = _get_device(args.devices, args.device_id)
+        result = adb.input_text(device.adb_serial, args.text)
+        print(result.stdout or result.stderr)
+        return
+
+    if args.command == "launch":
+        device = _get_device(args.devices, args.device_id)
+        result = adb.launch_package(device.adb_serial, args.package)
+        print(result.stdout or result.stderr)
+        return
+
+    if args.command == "plan-task":
+        tasks = load_tasks(args.tasks)
+        task = tasks[args.index]
+        registry = default_registry()
+        adapter = registry.get(task.platform)
+        errors = adapter.validate(task)
+        if errors:
+            print("validation errors:")
+            for err in errors:
+                print(f"- {err}")
+            return
+        print(f"task_id={task.task_id}")
+        print(f"platform={task.platform}")
+        print(f"post_type={task.post_type}")
+        print(f"dry_run={task.dry_run}")
+        for i, step in enumerate(adapter.plan(task), start=1):
+            print(f"{i}. {step}")
+        return
+
+    if args.command == "record-publish":
+        record = PublishRecord(
+            record_id=args.record_id or new_id("pub"),
+            task_id=args.task_id,
+            platform=args.platform.lower(),
+            account_id=args.account_id,
+            device_id=args.device_id,
+            post_type=args.post_type.lower(),
+            local_media_path=args.local_media_path,
+            remote_media_path=args.remote_media_path,
+            platform_post_id=args.platform_post_id,
+            platform_permalink=args.platform_permalink,
+            caption=args.caption,
+            published_at=args.published_at or utc_now_iso(),
+            result_screenshot_path=args.result_screenshot_path,
+            status=args.status,
+        )
+        append_publish_record(args.records, record)
+        print(json.dumps(record.to_dict(), ensure_ascii=False, sort_keys=True))
+        return
+
+    if args.command == "list-publish-records":
+        records = _filter_records(load_publish_records(args.records), args.platform, args.account_id, None)
+        for record in records:
+            print(json.dumps(record.to_dict(), ensure_ascii=False, sort_keys=True))
+        return
+
+    if args.command == "update-publish-record":
+        records = load_publish_records(args.records)
+        record = _find_record(records, args.record_id)
+        if args.platform_permalink:
+            record.platform_permalink = args.platform_permalink
+        if args.platform_post_id:
+            record.platform_post_id = args.platform_post_id
+        elif args.platform_permalink and not record.platform_post_id:
+            record.platform_post_id = parse_platform_post_id(record.platform, args.platform_permalink)
+        if args.caption is not None:
+            record.caption = args.caption
+        if args.published_at is not None:
+            record.published_at = args.published_at
+        if args.result_screenshot_path is not None:
+            record.result_screenshot_path = args.result_screenshot_path
+        if args.status is not None:
+            record.status = args.status
+        write_publish_records(args.records, records)
+        print(json.dumps(record.to_dict(), ensure_ascii=False, sort_keys=True))
+        return
+
+    if args.command == "add-metrics":
+        record = _find_record(load_publish_records(args.records), args.record_id)
+        try:
+            raw = json.loads(args.raw_json)
+        except Exception as exc:
+            raise SystemExit(f"Invalid --raw-json: {exc}") from exc
+        snapshot = build_manual_snapshot(
+            record,
+            views=args.views,
+            likes=args.likes,
+            comments=args.comments,
+            shares=args.shares,
+            saves=args.saves,
+            score=args.score,
+            raw=raw,
+        )
+        append_metrics_snapshot(args.metrics, snapshot)
+        print(json.dumps(snapshot.to_dict(), ensure_ascii=False, sort_keys=True))
+        return
+
+    if args.command == "collect-metrics":
+        records = _filter_records(load_publish_records(args.records), args.platform, args.account_id, args.record_id)
+        if not records:
+            print("no matching publish records")
+            return
+        for record in records:
+            if record.status != "published":
+                print(f"skip record_id={record.record_id} status={record.status}")
+                continue
+            try:
+                snapshot = collect_with_default_collector(record)
+            except MetricsCollectionError as exc:
+                print(f"skip record_id={record.record_id} platform={record.platform}: {exc}")
+                continue
+            append_metrics_snapshot(args.metrics, snapshot)
+            print(
+                "ok "
+                f"record_id={snapshot.record_id} source={snapshot.source} "
+                f"views={snapshot.views} likes={snapshot.likes} comments={snapshot.comments} "
+                f"shares={snapshot.shares} saves={snapshot.saves} score={snapshot.score}"
+            )
+        return
+
+    if args.command == "list-metrics":
+        snapshots = load_metrics_snapshots(args.metrics)
+        for snapshot in snapshots:
+            if args.record_id and snapshot.record_id != args.record_id:
+                continue
+            print(json.dumps(snapshot.to_dict(), ensure_ascii=False, sort_keys=True))
+        return
+
+    if args.command == "collect-tiktok-account-metrics-adb":
+        device = _get_device(args.devices, args.device)
+        account_id = args.account_id or f"{args.account_prefix}_{device.device_id.lower()}"
+        manual_values = _load_tiktok_account_metric_values(args.values_json, args.values_file)
+        collector = TikTokAccountMetricsAdbCollector(adb, artifact_root=args.artifact_root)
+        with device_lock(device.device_id):
+            snapshot = collector.collect(
+                device,
+                account_id=account_id,
+                periods=args.period,
+                resume_analytics=args.resume_analytics,
+                manual_values=manual_values,
+            )
+        if not args.no_append:
+            append_tiktok_account_metrics_snapshot(args.out, snapshot)
+        row = snapshot.to_dict()
+        if args.json:
+            print(json.dumps(row, ensure_ascii=False, sort_keys=True))
+        else:
+            complete = sum(1 for period in snapshot.periods.values() if period.has_all_metrics())
+            print(
+                f"{snapshot.device_id}: status={snapshot.status} account_id={snapshot.account_id} "
+                f"periods={complete}/{len(snapshot.periods)} duration={snapshot.duration_seconds}s "
+                f"artifact_dir={snapshot.artifact_dir} out={args.out if not args.no_append else '(not appended)'}"
+            )
+            if snapshot.status == "needs_human":
+                print("manual values required: review period screenshots, then rerun with --values-json or --values-file")
+            if snapshot.status == "failed":
+                print(f"error={snapshot.raw.get('error', '')}")
+        if snapshot.status == "failed" or (snapshot.status == "needs_human" and not args.allow_manual_required):
+            raise SystemExit(1)
+        return
+
+    if args.command == "list-tiktok-account-metrics":
+        snapshots = load_tiktok_account_metrics_snapshots(args.metrics)
+        for snapshot in snapshots:
+            if args.account_id and snapshot.account_id != args.account_id:
+                continue
+            if args.device_id and snapshot.device_id != args.device_id:
+                continue
+            print(json.dumps(snapshot.to_dict(), ensure_ascii=False, sort_keys=True))
+        return
+
+    if args.command == "collect-tiktok-video-metrics-adb":
+        device = _get_device(args.devices, args.device)
+        account_id = args.account_id or f"{args.account_prefix}_{device.device_id.lower()}"
+        manual_values = _load_tiktok_video_metric_values(args.values_json, args.values_file)
+        collector = TikTokVideoMetricsAdbCollector(adb, artifact_root=args.artifact_root)
+        with device_lock(device.device_id):
+            snapshot = collector.collect(
+                device,
+                account_id=account_id,
+                video_order=args.video_order,
+                resume_insights=args.resume_insights,
+                manual_values=manual_values,
+            )
+        if not args.no_append:
+            append_tiktok_video_metrics_snapshot(args.out, snapshot)
+        row = snapshot.to_dict()
+        if args.json:
+            print(json.dumps(row, ensure_ascii=False, sort_keys=True))
+        else:
+            print(
+                f"{snapshot.device_id}: status={snapshot.status} account_id={snapshot.account_id} "
+                f"published_at={snapshot.published_at or '(unknown)'} duration={snapshot.duration_seconds}s "
+                f"artifact_dir={snapshot.artifact_dir} out={args.out if not args.no_append else '(not appended)'}"
+            )
+            if snapshot.status == "needs_human":
+                print("manual values required: review the video-insights screenshot, then rerun with --values-json or --values-file")
+            if snapshot.status == "failed":
+                print(f"error={snapshot.raw.get('error', '')}")
+        if snapshot.status == "failed" or (snapshot.status == "needs_human" and not args.allow_manual_required):
+            raise SystemExit(1)
+        return
+
+    if args.command == "list-tiktok-video-metrics":
+        snapshots = load_tiktok_video_metrics_snapshots(args.metrics)
+        for snapshot in snapshots:
+            if args.account_id and snapshot.account_id != args.account_id:
+                continue
+            if args.device_id and snapshot.device_id != args.device_id:
+                continue
+            if args.published_at and snapshot.published_at != args.published_at:
+                continue
+            print(json.dumps(snapshot.to_dict(), ensure_ascii=False, sort_keys=True))
+        return
+
+    if args.command == "publish-tiktok-adb":
+        devices = load_devices(args.devices)
+        selected = _select_devices(devices, args.device, args.ranges)
+        if not selected:
+            raise SystemExit("No target devices. Use --device D01 or --range 1-10.")
+        if args.account_id and len(selected) != 1:
+            raise SystemExit("--account-id is only allowed with exactly one target device")
+        publisher = TikTokAdbPublisher(adb, records_path=args.records)
+
+        def run_one(device):
+            account_id = args.account_id or f"{args.account_prefix}_{device.device_id.lower()}"
+            return publisher.publish_video(
+                device,
+                video_path=args.video,
+                account_id=account_id,
+                caption=args.caption,
+                dry_run=args.dry_run,
+                allow_caption_fallback=args.allow_caption_fallback,
+            )
+
+        def print_one(result) -> None:
+            row = asdict(result)
+            if args.json:
+                print(json.dumps(row, ensure_ascii=False, sort_keys=True))
+            else:
+                print(
+                    f"{result.device_id}: status={result.status} duration={result.duration_seconds}s "
+                    f"record_id={result.record_id} screenshot={result.screenshot_path}"
+                    + (f" error={result.error}" if result.error else "")
+                )
+
+        any_failed = _run_publish_jobs(selected, args.parallel, args.max_concurrency, run_one, print_one)
+        if any_failed:
+            raise SystemExit(1)
+        return
+
+    if args.command in {"publish-tiktok", "publish-tiktok-appium"}:
+        devices = load_devices(args.devices)
+        selected = _select_devices(devices, args.device, args.ranges)
+        if not selected:
+            raise SystemExit("No target devices. Use --device D03 or --range 1-5.")
+        if args.account_id and len(selected) != 1:
+            raise SystemExit("--account-id is only allowed with exactly one target device")
+        _ensure_appium_preflight(args, selected)
+        publisher = TikTokAppiumPublisher(adb, appium_server=args.appium_server, records_path=args.records)
+
+        def run_one(device):
+            account_id = args.account_id or f"{args.account_prefix}_{device.device_id.lower()}"
+            return publisher.publish_video(
+                device,
+                video_path=args.video,
+                account_id=account_id,
+                caption=args.caption,
+                dry_run=args.dry_run,
+            )
+
+        def print_one(result) -> None:
+            row = asdict(result)
+            if args.json:
+                print(json.dumps(row, ensure_ascii=False, sort_keys=True))
+            else:
+                print(
+                    f"{result.device_id}: status={result.status} duration={result.duration_seconds}s "
+                    f"record_id={result.record_id} screenshot={result.screenshot_path}"
+                    + (f" error={result.error}" if result.error else "")
+                )
+
+        any_failed = _run_publish_jobs(selected, args.parallel, args.max_concurrency, run_one, print_one)
+        if any_failed:
+            raise SystemExit(1)
+        return
+
+    if args.command in {"publish-reddit", "publish-reddit-adb"}:
+        devices = load_devices(args.devices)
+        selected = _select_devices(devices, args.device, args.ranges)
+        if not selected:
+            raise SystemExit("No target devices. Use --device D01 or --range 1-10.")
+        if args.account_id and len(selected) != 1:
+            raise SystemExit("--account-id is only allowed with exactly one target device")
+        if args.reddit_username and len(selected) != 1:
+            raise SystemExit("--reddit-username is only allowed with exactly one target device")
+        publisher = RedditAdbPublisher(adb, records_path=args.records)
+
+        def run_one(device):
+            account_id = args.account_id or f"{args.account_prefix}_{device.device_id.lower()}"
+            return publisher.publish_post(
+                device,
+                post_type=args.post_type,
+                subreddit=args.subreddit,
+                title=args.title,
+                body=args.body,
+                link_url=args.link_url,
+                media_path=_media_path_for_post_type(args, args.post_type),
+                account_id=account_id,
+                reddit_username=args.reddit_username,
+                dry_run=args.dry_run,
+                fetch_permalink=not args.no_fetch_permalink,
+            )
+
+        def print_one(result) -> None:
+            row = asdict(result)
+            if args.json:
+                print(json.dumps(row, ensure_ascii=False, sort_keys=True))
+            else:
+                print(
+                    f"{result.device_id}: status={result.status} duration={result.duration_seconds}s "
+                    f"record_id={result.record_id} subreddit=r/{result.subreddit} screenshot={result.screenshot_path}"
+                    + (f" post_id={result.platform_post_id}" if result.platform_post_id else "")
+                    + (f" permalink={result.platform_permalink}" if result.platform_permalink else "")
+                    + (f" error={result.error}" if result.error else "")
+                )
+
+        any_failed = _run_publish_jobs(selected, args.parallel, args.max_concurrency, run_one, print_one)
+        if any_failed:
+            raise SystemExit(1)
+        return
+
+    if args.command == "publish-facebook":
+        devices = load_devices(args.devices)
+        selected = _select_devices(devices, args.device, args.ranges)
+        if not selected:
+            raise SystemExit("No target devices. Use --device D03 or --range 1-5.")
+        if args.account_id and len(selected) != 1:
+            raise SystemExit("--account-id is only allowed with exactly one target device")
+        publisher = FacebookAdbPublisher(adb, records_path=args.records)
+
+        def run_one(device):
+            account_id = args.account_id or f"{args.account_prefix}_{device.device_id.lower()}"
+            return publisher.publish_post(
+                device,
+                post_type=args.post_type,
+                text=args.caption or args.text,
+                media_path=_media_path_for_post_type(args, args.post_type),
+                link_url=args.link_url,
+                account_id=account_id,
+                dry_run=args.dry_run,
+                app_package=args.app_package,
+            )
+
+        def print_one(result) -> None:
+            row = asdict(result)
+            if args.json:
+                print(json.dumps(row, ensure_ascii=False, sort_keys=True))
+            else:
+                print(
+                    f"{result.device_id}: status={result.status} duration={result.duration_seconds}s "
+                    f"record_id={result.record_id} screenshot={result.screenshot_path}"
+                    + (f" error={result.error}" if result.error else "")
+                )
+
+        any_failed = _run_publish_jobs(selected, args.parallel, args.max_concurrency, run_one, print_one)
+        if any_failed:
+            raise SystemExit(1)
+        return
+
+    if args.command == "publish-instagram":
+        _apply_instagram_publish_policy(args)
+        devices = load_devices(args.devices)
+        selected = _select_devices(devices, args.device, args.ranges)
+        if not selected:
+            raise SystemExit("No target devices. Use --device D03 or --range 1-5.")
+        if args.account_id and len(selected) != 1:
+            raise SystemExit("--account-id is only allowed with exactly one target device")
+        if args.caption_input in {"auto", "appium"}:
+            _ensure_appium_preflight(args, selected)
+        publisher = InstagramAdbPublisher(adb, appium_server=args.appium_server, records_path=args.records)
+
+        def run_one(device):
+            account_id = args.account_id or f"{args.account_prefix}_{device.device_id.lower()}"
+            return publisher.publish_post(
+                device,
+                media_path=_instagram_media_path(args),
+                post_type=args.post_type,
+                account_id=account_id,
+                caption=args.caption,
+                dry_run=args.dry_run,
+                confirm_reels_public=args.confirm_reels_public,
+                caption_input=args.caption_input,
+            )
+
+        def print_one(result) -> None:
+            row = asdict(result)
+            if args.json:
+                print(json.dumps(row, ensure_ascii=False, sort_keys=True))
+            else:
+                print(
+                    f"{result.device_id}: status={result.status} duration={result.duration_seconds}s "
+                    f"record_id={result.record_id} screenshot={result.screenshot_path}"
+                    + (f" error={result.error}" if result.error else "")
+                )
+
+        any_failed = _run_publish_jobs(selected, args.parallel, args.max_concurrency, run_one, print_one)
+        if any_failed:
+            raise SystemExit(1)
+        return
+
+    if args.command == "publish-x":
+        devices = load_devices(args.devices)
+        selected = _select_devices(devices, args.device, args.ranges)
+        if not selected:
+            raise SystemExit("No target devices. Use --device D03 or --range 1-5.")
+        if args.account_id and len(selected) != 1:
+            raise SystemExit("--account-id is only allowed with exactly one target device")
+        post_text = _x_publish_text(args)
+        if args.text_input in {"auto", "appium"} and not post_text.isascii():
+            _ensure_appium_preflight(args, selected)
+        publisher = XAdbPublisher(adb, appium_server=args.appium_server, records_path=args.records)
+
+        def run_one(device):
+            account_id = args.account_id or f"{args.account_prefix}_{device.device_id.lower()}"
+            return publisher.publish_post(
+                device,
+                post_type=args.post_type,
+                text=post_text,
+                link_url=args.link_url,
+                media_path=_media_path_for_post_type(args, args.post_type),
+                account_id=account_id,
+                dry_run=args.dry_run,
+                text_input=args.text_input,
+                verify_profile=not args.no_verify_profile,
+            )
+
+        def print_one(result) -> None:
+            row = asdict(result)
+            if args.json:
+                print(json.dumps(row, ensure_ascii=False, sort_keys=True))
+            else:
+                print(
+                    f"{result.device_id}: status={result.status} duration={result.duration_seconds}s "
+                    f"record_id={result.record_id} screenshot={result.screenshot_path}"
+                    + (f" error={result.error}" if result.error else "")
+                )
+
+        any_failed = _run_publish_jobs(selected, args.parallel, args.max_concurrency, run_one, print_one)
+        if any_failed:
+            raise SystemExit(1)
+        return
+
+    if args.command == "publish-xiaohongshu":
+        _apply_xiaohongshu_publish_package(args)
+        _apply_xiaohongshu_live_publish_policy(args)
+        devices = load_devices(args.devices)
+        selected = _select_devices(devices, args.device, args.ranges)
+        if not selected:
+            raise SystemExit("No target devices. Use --device Dxx or --range 1-5.")
+        if args.account_id and len(selected) != 1:
+            raise SystemExit("--account-id is only allowed with exactly one target device")
+        _ensure_appium_preflight(args, selected)
+        publisher = XiaohongshuAdbPublisher(
+            adb,
+            appium_server=args.appium_server,
+            records_path=args.records,
+            flow_config_path=args.flow_config,
+        )
+
+        def run_one(device):
+            account_id = args.account_id or f"{args.account_prefix}_{device.device_id.lower()}"
+            return publisher.publish_note(
+                device,
+                media_path=_media_path_for_post_type(args, args.post_type),
+                media_paths=_xiaohongshu_media_paths(args),
+                post_type=args.post_type,
+                account_id=account_id,
+                title=args.title,
+                caption=args.caption,
+                tags=args.tags,
+                topics=args.topics,
+                dry_run=args.dry_run,
+                confirm_no_disclosure_needed=args.confirm_no_disclosure_needed,
+                copy_link_after_publish=args.copy_link_after_publish,
+                resume_post_form=args.resume_post_form,
+            )
+
+        def print_one(result) -> None:
+            row = asdict(result)
+            if args.json:
+                print(json.dumps(row, ensure_ascii=False, sort_keys=True))
+            else:
+                print(
+                    f"{result.device_id}: status={result.status} duration={result.duration_seconds}s "
+                    f"record_id={result.record_id} screenshot={result.screenshot_path}"
+                    + (f" error={result.error}" if result.error else "")
+                )
+
+        any_failed = _run_publish_jobs(selected, args.parallel, args.max_concurrency, run_one, print_one)
+        if any_failed:
+            raise SystemExit(1)
+        return
+
+    if args.command == "copy-xiaohongshu-link":
+        device = _get_device(args.devices, args.device)
+        _ensure_appium_preflight(args, [device])
+        publisher = XiaohongshuAdbPublisher(
+            adb,
+            appium_server=args.appium_server,
+            records_path=args.records,
+            flow_config_path=args.flow_config,
+        )
+        with device_lock(device.device_id):
+            result = publisher.copy_current_note_link(device)
+        if result.platform_permalink and args.record_id:
+            records = load_publish_records(args.records)
+            record = _find_record(records, args.record_id)
+            record.platform_permalink = result.platform_permalink
+            write_publish_records(args.records, records)
+        row = asdict(result)
+        if args.json:
+            print(json.dumps(row, ensure_ascii=False, sort_keys=True))
+        else:
+            print(
+                f"{result.device_id}: status={result.status} duration={result.duration_seconds}s "
+                f"screenshot={result.screenshot_path}"
+                + (f" permalink={result.platform_permalink}" if result.platform_permalink else "")
+                + (f" method={result.clipboard_method}" if result.clipboard_method else "")
+                + (f" error={result.error}" if result.error else "")
+            )
+        if result.status in {"failed", "needs_human"}:
+            raise SystemExit(1)
+        return
+
+
+def _get_device(devices_path: str, device_id: str):
+    devices = load_devices(devices_path)
+    if device_id not in devices:
+        raise SystemExit(f"Unknown device_id={device_id}")
+    return devices[device_id]
+
+
+def _resolve_appium_udids(devices_path: str, device_ids: list[str], udids: list[str]) -> list[str]:
+    resolved = [item for item in udids if item]
+    if device_ids:
+        devices = load_devices(devices_path)
+        for device_id in device_ids:
+            if device_id not in devices:
+                raise SystemExit(f"Unknown device_id={device_id}")
+            resolved.append(devices[device_id].adb_serial)
+    seen: set[str] = set()
+    out: list[str] = []
+    for udid in resolved:
+        if udid in seen:
+            continue
+        seen.add(udid)
+        out.append(udid)
+    return out
+
+
+def _ensure_appium_preflight(args, devices) -> None:
+    if getattr(args, "no_ensure_appium", False):
+        return
+    try:
+        ensure_appium_server(
+            args.appium_server,
+            udids=[device.adb_serial for device in devices],
+            smoke=not getattr(args, "no_appium_smoke", False),
+        )
+    except AppiumEnsureError as exc:
+        raise SystemExit(f"Appium preflight failed: {exc}") from exc
+
+
+def _load_tiktok_account_metric_values(values_json: str, values_file: str):
+    if values_json and values_file:
+        raise SystemExit("Use only one of --values-json or --values-file")
+    if values_file:
+        try:
+            values_json = Path(values_file).expanduser().read_text(encoding="utf-8")
+        except Exception as exc:
+            raise SystemExit(f"Could not read --values-file: {exc}") from exc
+    try:
+        return parse_manual_values_json(values_json)
+    except Exception as exc:
+        raise SystemExit(f"Invalid TikTok account metric values JSON: {exc}") from exc
+
+
+def _load_tiktok_video_metric_values(values_json: str, values_file: str):
+    if values_json and values_file:
+        raise SystemExit("Use only one of --values-json or --values-file")
+    if values_file:
+        try:
+            values_json = Path(values_file).expanduser().read_text(encoding="utf-8")
+        except Exception as exc:
+            raise SystemExit(f"Could not read --values-file: {exc}") from exc
+    try:
+        return parse_manual_video_values_json(values_json)
+    except Exception as exc:
+        raise SystemExit(f"Invalid TikTok video metric values JSON: {exc}") from exc
+
+
+def _add_publish_tiktok_appium_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--devices", default="data/devices.csv")
+    parser.add_argument("--records", default="data/publish_records.jsonl")
+    parser.add_argument("--appium-server", default="http://127.0.0.1:4723")
+    _add_appium_preflight_args(parser)
+    parser.add_argument("--video", required=True)
+    parser.add_argument("--caption", default="", help="Caption/description text to enter before publishing.")
+    parser.add_argument("--device", action="append", default=[], help="Device id, e.g. D03. Can be repeated.")
+    parser.add_argument("--range", dest="ranges", action="append", default=[], help="Device range, e.g. 1-5 or D01-D05.")
+    parser.add_argument("--account-id", default="", help="Single account id. Use only with one target device.")
+    parser.add_argument("--account-prefix", default="tiktok", help="Fallback account id prefix for multi-device runs.")
+    parser.add_argument("--dry-run", action="store_true", help="Stop at TikTok post form without tapping publish.")
+    parser.add_argument("--parallel", action="store_true", help="Run target devices concurrently. Hard-capped at 5.")
+    parser.add_argument("--max-concurrency", type=int, default=MAX_PARALLEL_DEVICES, help="Max concurrent devices, 1-5.")
+    parser.add_argument("--json", action="store_true", help="Print JSON lines")
+
+
+def _add_publish_xiaohongshu_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--devices", default="data/devices.csv")
+    parser.add_argument("--records", default="data/publish_records.jsonl")
+    parser.add_argument("--appium-server", default="http://127.0.0.1:4723")
+    _add_appium_preflight_args(parser)
+    parser.add_argument("--flow-config", default="configs/platforms/xiaohongshu_d03.json")
+    parser.add_argument(
+        "--publish-package",
+        default="",
+        help="Path to a Xiaohongshu publish_package*.json file, or a directory containing publish_package.images-ready.json.",
+    )
+    parser.add_argument(
+        "--publish-policy",
+        default=DEFAULT_PUBLISH_POLICY_PATH,
+        help="Publish policy JSON used to auto-confirm live publish prompts and bridge package approval/disclosure defaults.",
+    )
+    parser.add_argument("--post-type", choices=["image", "video"], default="", help="Xiaohongshu note type.")
+    parser.add_argument("--media", default="", help="Media file path. Use with --post-type image/video.")
+    parser.add_argument("--image", default="", help="Image file path for --post-type image.")
+    parser.add_argument("--images", action="append", default=[], help="Image file path for multi-image Xiaohongshu notes. Can be repeated.")
+    parser.add_argument("--video", default="", help="Video file path for --post-type video. Kept for backward compatibility.")
+    parser.add_argument("--title", default="")
+    parser.add_argument("--caption", default="")
+    parser.add_argument("--caption-file", default="", help="Read Xiaohongshu caption/body text from a local file.")
+    parser.add_argument("--tag", dest="tags", action="append", default=[], help="Tag to type manually in the caption as a hashtag. Can be repeated.")
+    parser.add_argument("--topic", dest="topics", action="append", default=[], help="Topic tag to type manually in the caption as a hashtag. Can be repeated.")
+    parser.add_argument("--device", action="append", default=[], help="Device id, e.g. D03. Can be repeated.")
+    parser.add_argument("--range", dest="ranges", action="append", default=[], help="Device range, e.g. 1-5 or D01-D05.")
+    parser.add_argument("--account-id", default="", help="Single account id. Use only with one target device.")
+    parser.add_argument("--account-prefix", default="xhs", help="Fallback account id prefix for multi-device runs.")
+    parser.add_argument("--dry-run", action="store_true", help="Stop at Xiaohongshu post form without tapping publish.")
+    parser.add_argument(
+        "--resume-post-form",
+        action="store_true",
+        help="Continue from the current Xiaohongshu post form and skip media push/selection.",
+    )
+    parser.add_argument(
+        "--confirm-no-disclosure-needed",
+        action="store_true",
+        help="Optional backward-compatible manual confirmation; live publish auto-confirms this from --publish-policy.",
+    )
+    parser.add_argument(
+        "--copy-link-after-publish",
+        action="store_true",
+        help="After a successful publish, open the share sheet, tap copy link, and try to read the copied URL.",
+    )
+    parser.add_argument("--parallel", action="store_true", help="Run target devices concurrently. Hard-capped at 5.")
+    parser.add_argument("--max-concurrency", type=int, default=MAX_PARALLEL_DEVICES, help="Max concurrent devices, 1-5.")
+    parser.add_argument("--json", action="store_true", help="Print JSON lines")
+
+
+def _add_publish_reddit_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--devices", default="data/devices.csv")
+    parser.add_argument("--records", default="data/publish_records.jsonl")
+    parser.add_argument("--post-type", choices=["text", "link", "image", "video"], default="text")
+    parser.add_argument("--subreddit", required=True, help="Target subreddit, e.g. test or r/test.")
+    parser.add_argument("--title", required=True)
+    parser.add_argument("--body", default="")
+    parser.add_argument("--link-url", default="", help="URL for --post-type link.")
+    parser.add_argument("--media", default="", help="Media file path for --post-type image/video.")
+    parser.add_argument("--image", default="", help="Image file path for --post-type image.")
+    parser.add_argument("--video", default="", help="Video file path for --post-type video.")
+    parser.add_argument("--device", action="append", default=[], help="Device id, e.g. D01. Can be repeated.")
+    parser.add_argument("--range", dest="ranges", action="append", default=[], help="Device range, e.g. 1-10 or D01-D10.")
+    parser.add_argument("--account-id", default="", help="Single account id. Use only with one target device.")
+    parser.add_argument("--account-prefix", default="reddit", help="Fallback account id prefix for multi-device runs.")
+    parser.add_argument("--reddit-username", default="", help="Reddit username for post permalink lookup. Use only with one target device.")
+    parser.add_argument("--dry-run", action="store_true", help="Stop at Reddit post form without tapping publish.")
+    parser.add_argument("--no-fetch-permalink", action="store_true", help="Do not query public Reddit JSON after publish.")
+    parser.add_argument("--parallel", action="store_true", help="Run target devices concurrently. Hard-capped at 5.")
+    parser.add_argument("--max-concurrency", type=int, default=MAX_PARALLEL_DEVICES, help="Max concurrent devices, 1-5.")
+    parser.add_argument("--json", action="store_true", help="Print JSON lines")
+
+
+def _add_publish_facebook_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--devices", default="data/devices.csv")
+    parser.add_argument("--records", default="data/publish_records.jsonl")
+    parser.add_argument("--post-type", choices=["text", "link", "image", "video"], default="text")
+    parser.add_argument("--text", default="", help="Text body to publish. Current Facebook Lite POC supports ASCII single-line text.")
+    parser.add_argument("--caption", default="", help="Caption text for image/video/link posts. Overrides --text when present.")
+    parser.add_argument("--link-url", default="", help="URL for --post-type link.")
+    parser.add_argument("--media", default="", help="Media file path for --post-type image/video.")
+    parser.add_argument("--image", default="", help="Image file path for --post-type image.")
+    parser.add_argument("--video", default="", help="Video file path for --post-type video.")
+    parser.add_argument("--device", action="append", default=[], help="Device id, e.g. D03. Can be repeated.")
+    parser.add_argument("--range", dest="ranges", action="append", default=[], help="Device range, e.g. 1-5 or D01-D05.")
+    parser.add_argument("--account-id", default="", help="Single account id. Use only with one target device.")
+    parser.add_argument("--account-prefix", default="facebook", help="Fallback account id prefix for multi-device runs.")
+    parser.add_argument("--app-package", default="com.facebook.lite", help="Facebook package to launch. Current calibrated flow is com.facebook.lite.")
+    parser.add_argument("--dry-run", action="store_true", help="Stop at Facebook post form without tapping POST.")
+    parser.add_argument("--parallel", action="store_true", help="Run target devices concurrently. Hard-capped at 5.")
+    parser.add_argument("--max-concurrency", type=int, default=MAX_PARALLEL_DEVICES, help="Max concurrent devices, 1-5.")
+    parser.add_argument("--json", action="store_true", help="Print JSON lines")
+
+
+def _add_publish_x_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--devices", default="data/devices.csv")
+    parser.add_argument("--records", default="data/publish_records.jsonl")
+    parser.add_argument("--appium-server", default="http://127.0.0.1:4723")
+    _add_appium_preflight_args(parser)
+    parser.add_argument("--post-type", choices=["text", "link", "image"], default="text")
+    parser.add_argument("--title", default="", help=argparse.SUPPRESS)
+    parser.add_argument("--body", default="", help="Post body text.")
+    parser.add_argument("--text", default="", help=argparse.SUPPRESS)
+    parser.add_argument("--caption", default="", help=argparse.SUPPRESS)
+    parser.add_argument("--link-url", default="", help="URL for --post-type link.")
+    parser.add_argument("--media", default="", help="Media file path for --post-type image.")
+    parser.add_argument("--image", default="", help="Image file path for --post-type image.")
+    parser.add_argument("--text-input", choices=["auto", "appium", "adb"], default="auto")
+    parser.add_argument("--device", action="append", default=[], help="Device id, e.g. D03. Can be repeated.")
+    parser.add_argument("--range", dest="ranges", action="append", default=[], help="Device range, e.g. 1-5 or D01-D05.")
+    parser.add_argument("--account-id", default="", help="Single account id. Use only with one target device.")
+    parser.add_argument("--account-prefix", default="x", help="Fallback account id prefix for multi-device runs.")
+    parser.add_argument("--dry-run", action="store_true", help="Stop at X compose form without tapping Post.")
+    parser.add_argument("--no-verify-profile", action="store_true", help="Do not open the X profile page to verify the published post text.")
+    parser.add_argument("--parallel", action="store_true", help="Run target devices concurrently. Hard-capped at 5.")
+    parser.add_argument("--max-concurrency", type=int, default=MAX_PARALLEL_DEVICES, help="Max concurrent devices, 1-5.")
+    parser.add_argument("--json", action="store_true", help="Print JSON lines")
+
+
+def _add_publish_instagram_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--devices", default="data/devices.csv")
+    parser.add_argument("--records", default="data/publish_records.jsonl")
+    parser.add_argument("--appium-server", default="http://127.0.0.1:4723")
+    _add_appium_preflight_args(parser)
+    parser.add_argument(
+        "--publish-policy",
+        default=DEFAULT_PUBLISH_POLICY_PATH,
+        help="Publish policy JSON used to auto-confirm live publish prompts.",
+    )
+    parser.add_argument(
+        "--post-type",
+        choices=["reel", "post-image", "post-video", "image", "video"],
+        default="reel",
+        help="Instagram type. image/video are aliases for ordinary feed Post image/video.",
+    )
+    parser.add_argument("--media", default="", help="Media file path for selected post type.")
+    parser.add_argument("--image", default="", help="Image file path for --post-type post-image/image.")
+    parser.add_argument("--video", default="", help="Video file path. Kept for Reels backward compatibility.")
+    parser.add_argument("--caption", default="")
+    parser.add_argument("--caption-input", choices=["auto", "appium", "adb"], default="auto")
+    parser.add_argument("--device", action="append", default=[], help="Device id, e.g. D03. Can be repeated.")
+    parser.add_argument("--range", dest="ranges", action="append", default=[], help="Device range, e.g. 1-5 or D01-D05.")
+    parser.add_argument("--account-id", default="", help="Single account id. Use only with one target device.")
+    parser.add_argument("--account-prefix", default="instagram", help="Fallback account id prefix for multi-device runs.")
+    parser.add_argument("--dry-run", action="store_true", help="Stop at Instagram share form without tapping share.")
+    parser.add_argument(
+        "--confirm-reels-public",
+        action="store_true",
+        help="Optional backward-compatible manual confirmation; live publish auto-confirms this from --publish-policy.",
+    )
+    parser.add_argument("--parallel", action="store_true", help="Run target devices concurrently. Hard-capped at 5.")
+    parser.add_argument("--max-concurrency", type=int, default=MAX_PARALLEL_DEVICES, help="Max concurrent devices, 1-5.")
+    parser.add_argument("--json", action="store_true", help="Print JSON lines")
+
+
+def _add_appium_preflight_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--no-ensure-appium",
+        action="store_true",
+        help="Do not auto-start/check Appium before this Appium-backed flow.",
+    )
+    parser.add_argument(
+        "--no-appium-smoke",
+        action="store_true",
+        help="Skip the pre-publish UiAutomator2 session smoke check.",
+    )
+
+
+def _load_publish_policy_for_args(args) -> dict:
+    if hasattr(args, "_publish_policy"):
+        return args._publish_policy
+    try:
+        policy = load_publish_policy(getattr(args, "publish_policy", DEFAULT_PUBLISH_POLICY_PATH))
+    except Exception as exc:
+        raise SystemExit(f"Could not read publish policy: {exc}") from exc
+    args._publish_policy = policy
+    return policy
+
+
+def _apply_instagram_publish_policy(args) -> None:
+    if args.dry_run or args.confirm_reels_public:
+        return
+    policy = _load_publish_policy_for_args(args)
+    if should_auto_confirm_instagram_reels_public(policy):
+        args.confirm_reels_public = True
+
+
+def _apply_xiaohongshu_live_publish_policy(args) -> None:
+    if args.dry_run or args.confirm_no_disclosure_needed:
+        return
+    policy = _load_publish_policy_for_args(args)
+    if should_auto_confirm_xiaohongshu_no_disclosure(policy):
+        args.confirm_no_disclosure_needed = True
+
+
+def _apply_xiaohongshu_publish_package(args) -> None:
+    package: dict | None = None
+    package_path: Path | None = None
+    if args.publish_package:
+        package_path = _resolve_xiaohongshu_package_path(args.publish_package)
+        with package_path.open(encoding="utf-8") as handle:
+            loaded = json.load(handle)
+        if not isinstance(loaded, dict):
+            raise SystemExit(f"Xiaohongshu publish package must be a JSON object: {package_path}")
+        package = loaded
+        _apply_xiaohongshu_package_policy(args, package)
+
+    note = dict(package.get("note") or {}) if package else {}
+    instructions = dict(package.get("publish_instructions") or {}) if package else {}
+
+    if not args.post_type:
+        args.post_type = str(instructions.get("post_type") or note.get("post_type") or "video")
+
+    if not args.title:
+        args.title = str(instructions.get("title") or note.get("selected_title") or "")
+    if not args.title.strip():
+        raise SystemExit("Xiaohongshu --title is required unless --publish-package provides note.selected_title or publish_instructions.title")
+
+    if package and args.post_type == "image" and not args.images:
+        raw_images = (
+            package.get("absolute_upload_order")
+            or instructions.get("images")
+            or package.get("upload_order")
+            or package.get("backup_jpg_upload_order")
+            or []
+        )
+        args.images = [str(_resolve_package_relative_path(str(item), package_path)) for item in raw_images]
+        if args.images and not args.image and not args.media:
+            args.image = args.images[0]
+
+    caption = args.caption
+    caption_file = args.caption_file or str(instructions.get("caption_file") or "")
+    if not caption and caption_file:
+        if not package_path:
+            caption_path = Path(caption_file).expanduser()
+        else:
+            caption_path = _resolve_package_relative_path(caption_file, package_path)
+        caption = caption_path.read_text(encoding="utf-8").strip()
+    if not caption:
+        caption = str(note.get("body") or "")
+
+    package_tags = _string_list(instructions.get("tags") or note.get("tags") or [])
+    package_topics = _string_list(instructions.get("topics") or note.get("topics") or [])
+    args.caption = caption.strip()
+    args.tags = [*package_tags, *list(args.tags or [])]
+    args.topics = [*package_topics, *list(args.topics or [])]
+
+
+def _apply_xiaohongshu_package_policy(args, package: dict) -> None:
+    try:
+        policy = _load_publish_policy_for_args(args)
+        decision = decide_xiaohongshu_publish_package_policy(package, policy)
+    except Exception as exc:
+        raise SystemExit(f"Could not apply Xiaohongshu publish policy: {exc}") from exc
+
+    args.xiaohongshu_policy_decision = decision
+    if (
+        args.confirm_no_disclosure_needed
+        and any("requires declaration" in item for item in decision.blockers)
+        and xiaohongshu_package_disclosure_is_strict(policy)
+    ):
+        raise SystemExit(
+            "Xiaohongshu package says a content/commercial declaration is required; "
+            "refusing --confirm-no-disclosure-needed"
+        )
+    if not args.dry_run and not args.confirm_no_disclosure_needed and decision.auto_confirm_no_disclosure_needed:
+        args.confirm_no_disclosure_needed = True
+
+
+def _resolve_xiaohongshu_package_path(value: str) -> Path:
+    path = Path(value).expanduser()
+    if path.is_dir():
+        preferred = path / "publish_package.images-ready.json"
+        if preferred.exists():
+            return preferred
+        matches = sorted(path.glob("publish_package*.json"))
+        if matches:
+            return matches[0]
+        raise SystemExit(f"No publish_package*.json found in {path}")
+    if not path.exists():
+        raise SystemExit(f"Xiaohongshu publish package not found: {path}")
+    return path
+
+
+def _resolve_package_relative_path(value: str, package_path: Path) -> Path:
+    raw = Path(value).expanduser()
+    if raw.is_absolute():
+        return raw
+    candidates = [Path.cwd() / raw, package_path.parent / raw]
+    candidates.extend(parent / raw for parent in package_path.parent.parents)
+    for candidate in candidates:
+        if candidate.exists():
+            return candidate
+    return package_path.parent / raw
+
+
+def _string_list(value) -> list[str]:
+    if isinstance(value, list):
+        return [str(item) for item in value if str(item).strip()]
+    if isinstance(value, str) and value.strip():
+        return [value]
+    return []
+
+
+def _media_path_for_post_type(args, post_type: str) -> str | None:
+    normalized = post_type.strip().lower().replace("_", "-")
+    if normalized in {"image", "photo", "post-image", "post-photo"}:
+        path = getattr(args, "media", "") or getattr(args, "image", "")
+        if not path:
+            raise SystemExit("--post-type image requires --image or --media")
+        return path
+    if normalized in {"video", "reel", "reels", "post-video"}:
+        path = getattr(args, "media", "") or getattr(args, "video", "")
+        if not path:
+            raise SystemExit(f"--post-type {post_type} requires --video or --media")
+        return path
+    return None
+
+
+def _instagram_media_path(args) -> str:
+    normalized = args.post_type.strip().lower().replace("_", "-")
+    if normalized in {"reel", "reels"}:
+        path = args.media or args.video
+        if not path:
+            raise SystemExit("Instagram Reels requires --video or --media")
+        return path
+    if normalized in {"image", "photo", "post", "post-image", "post-photo"}:
+        path = args.media or args.image
+        if not path:
+            raise SystemExit("Instagram image Post requires --image or --media")
+        return path
+    if normalized in {"video", "post-video"}:
+        path = args.media or args.video
+        if not path:
+            raise SystemExit("Instagram video Post requires --video or --media")
+        return path
+    raise SystemExit(f"unsupported Instagram --post-type {args.post_type!r}")
+
+
+def _xiaohongshu_media_paths(args) -> list[str] | None:
+    normalized = args.post_type.strip().lower().replace("_", "-")
+    if normalized != "image" or not getattr(args, "images", []):
+        return None
+    return args.images
+
+
+def _x_publish_text(args) -> str:
+    for value in (args.body, args.text, args.caption, args.title):
+        if value and value.strip():
+            return value.strip()
+    return ""
+
+
+def _find_record(records: list[PublishRecord], record_id: str) -> PublishRecord:
+    for record in records:
+        if record.record_id == record_id:
+            return record
+    raise SystemExit(f"Unknown record_id={record_id}")
+
+
+def _filter_records(
+    records: list[PublishRecord],
+    platform: str | None,
+    account_id: str | None,
+    record_id: str | None,
+) -> list[PublishRecord]:
+    out = records
+    if platform:
+        out = [record for record in out if record.platform == platform.lower()]
+    if account_id:
+        out = [record for record in out if record.account_id == account_id]
+    if record_id:
+        out = [record for record in out if record.record_id == record_id]
+    return out
+
+
+def _run_publish_jobs(devices: list[object], parallel: bool, max_concurrency: int, run_one, print_one) -> bool:
+    if max_concurrency < 1:
+        raise SystemExit("--max-concurrency must be >= 1")
+    if max_concurrency > MAX_PARALLEL_DEVICES:
+        raise SystemExit(f"--max-concurrency is capped at {MAX_PARALLEL_DEVICES}")
+
+    def run_locked(device):
+        with publish_slot(MAX_PARALLEL_DEVICES):
+            with device_lock(device.device_id):
+                return run_one(device)
+
+    any_failed = False
+    if not parallel or len(devices) <= 1:
+        for device in devices:
+            try:
+                result = run_locked(device)
+            except DeviceLockError as exc:
+                print(f"{device.device_id}: status=failed error={exc}")
+                any_failed = True
+                continue
+            print_one(result)
+            any_failed = any_failed or getattr(result, "status", "") in {"failed", "needs_human"}
+        return any_failed
+
+    workers = min(max_concurrency, MAX_PARALLEL_DEVICES, len(devices))
+    with ThreadPoolExecutor(max_workers=workers) as pool:
+        futures = {pool.submit(run_locked, device): device for device in devices}
+        for future in as_completed(futures):
+            device = futures[future]
+            try:
+                result = future.result()
+            except DeviceLockError as exc:
+                print(f"{device.device_id}: status=failed error={exc}")
+                any_failed = True
+                continue
+            print_one(result)
+            any_failed = any_failed or getattr(result, "status", "") in {"failed", "needs_human"}
+    return any_failed
+
+
+def _select_devices(devices: dict[str, object], device_ids: list[str], ranges: list[str]):
+    selected_ids: list[str] = []
+    for device_id in device_ids:
+        selected_ids.append(_normalize_device_id(device_id))
+    for text in ranges:
+        selected_ids.extend(_expand_device_range(text))
+    if not selected_ids:
+        return []
+
+    seen: set[str] = set()
+    selected = []
+    for device_id in selected_ids:
+        if device_id in seen:
+            continue
+        seen.add(device_id)
+        if device_id not in devices:
+            raise SystemExit(f"Unknown device_id={device_id}")
+        device = devices[device_id]
+        if getattr(device, "status", "active") != "active":
+            print(f"{device_id}: skipped status={getattr(device, 'status', '')}")
+            continue
+        selected.append(device)
+    return selected
+
+
+def _expand_device_range(text: str) -> list[str]:
+    raw = text.strip()
+    if "," in raw:
+        ids: list[str] = []
+        for part in raw.split(","):
+            ids.extend(_expand_device_range(part))
+        return ids
+    if "-" not in raw:
+        return [_normalize_device_id(raw)]
+    left, right = raw.split("-", 1)
+    start = _device_number(left)
+    end = _device_number(right)
+    if start > end:
+        raise SystemExit(f"Invalid device range={text!r}")
+    return [f"D{i:02d}" for i in range(start, end + 1)]
+
+
+def _normalize_device_id(text: str) -> str:
+    value = text.strip().upper()
+    if value.startswith("D"):
+        number = _device_number(value)
+        return f"D{number:02d}"
+    if value.isdigit():
+        return f"D{int(value):02d}"
+    return value
+
+
+def _device_number(text: str) -> int:
+    value = text.strip().upper()
+    if value.startswith("D"):
+        value = value[1:]
+    if not value.isdigit():
+        raise SystemExit(f"Invalid device id/range part={text!r}")
+    return int(value)
+
+
+def _ip_from_serial(serial: str) -> str:
+    if ":" in serial:
+        return serial.split(":", 1)[0]
+    return ""
+
+
+if __name__ == "__main__":
+    main()