@buaa_smat/hometrans 0.1.0 → 0.1.2

package/skills/hmos-ui-align/scripts/page_capture.py

@@ -0,0 +1,592 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+统一页面采集工具 —— 单次采集当前设备页面的 View Tree (XML)、截图，支持滚动采集。
+
+支持 Android (ADB) 和 HarmonyOS (HDC) 两种设备。
+
+用法:
+  # HarmonyOS
+  python page_capture.py --device hdc -o ./output
+
+  # Android
+  python page_capture.py --device adb -o ./output --serial emulator-5554
+"""
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+import time
+import xml.etree.ElementTree as ET
+from datetime import datetime
+from pathlib import Path
+
+# 强制设置 UTF-8 编码以避免 Windows GBK 编码问题
+if sys.platform == 'win32':
+    import io
+    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8', errors='replace')
+    sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8', errors='replace')
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+SCROLL_DURATION_MS = 300
+HDC_SWIPE_SPEED = 600  # pixels/second for hdc uitest uiInput swipe
+IDLE_POLL_INTERVAL = 0.2
+IDLE_TIMEOUT = 5
+
+SKIP_RESOURCE_ID_PATTERNS = [
+    "statusBarBackground",
+    "navigationBarBackground",
+    "action_bar_container",
+    "status_bar",
+    "navigation_bar",
+]
+
+# HarmonyOS: skip system UI node types / bundles
+HMOS_SKIP_TYPES = {"WindowScene", "__Common__", "EffectComponent", "metaballNode"}
+HMOS_SKIP_BUNDLES = {"com.huawei.systemui", "com.ohos.systemui", "com.huawei.android.launcher"}
+
+
+# ---------------------------------------------------------------------------
+# ADB helpers
+# ---------------------------------------------------------------------------
+def adb(*args, serial=None, timeout=15) -> str:
+    cmd = ["adb"]
+    if serial:
+        cmd += ["-s", serial]
+    cmd += list(args)
+    try:
+        result = subprocess.run(cmd, capture_output=True, timeout=timeout,
+                                encoding="utf-8", errors="replace")
+        return (result.stdout or "").strip()
+    except subprocess.TimeoutExpired:
+        print(f"  [WARN] adb timeout: {' '.join(args)}")
+        return ""
+
+
+def adb_shell(*args, serial=None, timeout=15) -> str:
+    return adb("shell", *args, serial=serial, timeout=timeout)
+
+
+def adb_wait_idle(serial=None):
+    deadline = time.time() + IDLE_TIMEOUT
+    prev_focus = None
+    interval = IDLE_POLL_INTERVAL
+    while time.time() < deadline:
+        time.sleep(interval)
+        interval = min(interval * 1.5, 0.5)
+        focus_out = adb_shell("dumpsys", "window", serial=serial)
+        current_focus = ""
+        for line in focus_out.splitlines():
+            if "mCurrentFocus" in line:
+                current_focus = line.strip()
+                break
+        if current_focus and current_focus == prev_focus:
+            return
+        prev_focus = current_focus
+
+
+# ---------------------------------------------------------------------------
+# HDC helpers
+# ---------------------------------------------------------------------------
+def hdc(*args, timeout=15) -> str:
+    cmd = ["hdc"] + list(args)
+    try:
+        result = subprocess.run(cmd, shell=True, capture_output=True,
+                                text=True, timeout=timeout)
+        if result.returncode != 0 and result.stderr.strip():
+            print(f"  [WARN] hdc stderr: {result.stderr.strip()}")
+        return (result.stdout or "").strip()
+    except subprocess.TimeoutExpired:
+        print(f"  [WARN] hdc timeout: {' '.join(args)}")
+        return ""
+
+
+def hdc_shell(*args, timeout=15) -> str:
+    return hdc("shell", *args, timeout=timeout)
+
+
+def hdc_wait_idle():
+    time.sleep(1)
+
+
+# ---------------------------------------------------------------------------
+# XML utilities (shared)
+# ---------------------------------------------------------------------------
+def find_scrollable_containers(xml_content: str) -> list[dict]:
+    containers = []
+    if not xml_content:
+        return containers
+    try:
+        root = ET.fromstring(xml_content)
+    except ET.ParseError:
+        return containers
+    for node in root.iter("node"):
+        if node.get("scrollable") != "true":
+            continue
+        cls = node.get("class", "")
+        if cls in {"android.widget.HorizontalScrollView", "HorizontalScrollView"}:
+            continue
+        bounds_str = node.get("bounds", "")
+        m = re.findall(r"\d+", bounds_str)
+        if len(m) != 4:
+            continue
+        x1, y1, x2, y2 = map(int, m)
+        if y2 - y1 < 200:
+            continue
+        containers.append({
+            "bounds": (x1, y1, x2, y2),
+            "class": cls,
+            "resource-id": node.get("resource-id", ""),
+        })
+    containers.sort(
+        key=lambda c: (c["bounds"][2] - c["bounds"][0]) * (c["bounds"][3] - c["bounds"][1]),
+        reverse=True,
+    )
+    return containers
+
+
+def _extract_node_keys(xml_content: str) -> set[tuple]:
+    keys = set()
+    if not xml_content:
+        return keys
+    try:
+        root = ET.fromstring(xml_content)
+    except ET.ParseError:
+        return keys
+    for node in root.iter("node"):
+        keys.add((
+            node.get("class", ""),
+            node.get("resource-id", ""),
+            node.get("text", ""),
+            node.get("content-desc", ""),
+            node.get("bounds", ""),
+        ))
+    return keys
+
+
+def parse_bounds_center(bounds: str):
+    m = re.findall(r"\d+", bounds)
+    if len(m) == 4:
+        x1, y1, x2, y2 = map(int, m)
+        return ((x1 + x2) // 2, (y1 + y2) // 2)
+    return None
+
+
+def get_clickable_elements(xml_content: str) -> list[dict]:
+    elements = []
+    if not xml_content:
+        return elements
+    try:
+        root = ET.fromstring(xml_content)
+
+        listview_child_set = set()
+        for node in root.iter("node"):
+            cls = node.get("class", "")
+            if "ListView" in cls or "GridView" in cls or "List" == cls:
+                for child in node:
+                    listview_child_set.add(child)
+
+        def extract_text(node):
+            text = node.get("text", "")
+            if text:
+                return text
+            for child in node.iter("node"):
+                t = child.get("text", "")
+                if t:
+                    return t
+            return ""
+
+        for node in root.iter("node"):
+            if node.get("enabled") != "true":
+                continue
+            is_clickable = node.get("clickable") == "true"
+            is_long_clickable = node.get("long-clickable") == "true"
+            is_listview_item = node in listview_child_set
+            is_checkable = node.get("checkable") == "true"
+            if not (is_clickable or is_long_clickable or is_listview_item or is_checkable):
+                continue
+            bounds = node.get("bounds", "")
+            text = node.get("text", "")
+            if not text:
+                text = extract_text(node)
+            base_info = {
+                "class": node.get("class", ""),
+                "text": text,
+                "resource-id": node.get("resource-id", ""),
+                "content-desc": node.get("content-desc", ""),
+                "bounds": bounds,
+                "center": parse_bounds_center(bounds),
+            }
+            if is_clickable or is_listview_item or is_checkable:
+                elements.append({**base_info, "long-clickable": False})
+            if is_long_clickable:
+                elements.append({**base_info, "long-clickable": True})
+    except ET.ParseError as e:
+        print(f"  [WARN] XML parse error: {e}")
+    return elements
+
+
+# ---------------------------------------------------------------------------
+# HarmonyOS: JSON → XML conversion
+# ---------------------------------------------------------------------------
+def hmos_to_xml(node, parent=None):
+    attrs = node.get("attributes", {})
+    t = attrs.get("type", "")
+    bundle = attrs.get("bundleName", "")
+    if t in HMOS_SKIP_TYPES:
+        return None
+    if bundle in HMOS_SKIP_BUNDLES:
+        return None
+    xml_attrs = {
+        "class": t,
+        "resource-id": attrs.get("key", ""),
+        "text": attrs.get("text", ""),
+        "content-desc": attrs.get("description", ""),
+        "clickable": attrs.get("clickable", "false"),
+        "long-clickable": attrs.get("longClickable", "false"),
+        "scrollable": attrs.get("scrollable", "false"),
+        "enabled": attrs.get("enabled", "true"),
+        "focused": attrs.get("focused", "false"),
+        "bounds": attrs.get("bounds", ""),
+        "package": bundle,
+    }
+    el = ET.SubElement(parent, "node", xml_attrs) if parent is not None \
+        else ET.Element("node", xml_attrs)
+    for child in node.get("children", []):
+        hmos_to_xml(child, el)
+    return el
+
+
+# ---------------------------------------------------------------------------
+# Android capture
+# ---------------------------------------------------------------------------
+def _adb_dump_xml(output_dir: Path, serial=None) -> str:
+    remote_path = "/sdcard/ui_dump.xml"
+    adb_shell("rm -f /sdcard/ui_dump.xml && uiautomator dump /sdcard/ui_dump.xml",
+              serial=serial, timeout=20)
+    for _ in range(6):
+        check = adb_shell("ls", remote_path, serial=serial)
+        if remote_path in check:
+            break
+        time.sleep(0.2)
+    xml_content = adb_shell("cat", remote_path, serial=serial, timeout=15)
+    if xml_content:
+        (output_dir / "view.xml").write_text(xml_content, encoding="utf-8")
+    return xml_content
+
+
+def _adb_dump_xml_quick(serial=None) -> str:
+    remote_path = "/sdcard/ui_dump.xml"
+    adb_shell("rm -f /sdcard/ui_dump.xml && uiautomator dump /sdcard/ui_dump.xml",
+              serial=serial, timeout=20)
+    for _ in range(6):
+        check = adb_shell("ls", remote_path, serial=serial)
+        if remote_path in check:
+            break
+        time.sleep(0.2)
+    return adb_shell("cat", remote_path, serial=serial, timeout=15)
+
+
+def _adb_screenshot(output_dir: Path, filename="screenshot.png", serial=None):
+    local_path = output_dir / filename
+    cmd = ["adb"]
+    if serial:
+        cmd += ["-s", serial]
+    cmd += ["exec-out", "screencap", "-p"]
+    try:
+        result = subprocess.run(cmd, capture_output=True, timeout=15)
+        if result.stdout:
+            local_path.write_bytes(result.stdout)
+    except subprocess.TimeoutExpired:
+        print(f"  [WARN] screenshot timeout")
+
+
+def _adb_get_activity(serial=None) -> dict:
+    info = {}
+    act_out = adb_shell("dumpsys", "activity", "activities", serial=serial)
+    win_out = adb_shell("dumpsys", "window", serial=serial)
+    for line in act_out.splitlines():
+        if re.search(r"ResumedActivity|topActivity", line, re.IGNORECASE):
+            info["resumed_activity"] = line.strip()
+            break
+    for line in win_out.splitlines():
+        if "mCurrentFocus" in line:
+            info["current_focus"] = line.strip()
+            break
+        if "mFocusedApp" in line:
+            info.setdefault("focused_app", line.strip())
+    return info
+
+
+def _adb_scroll_and_capture(output_dir: Path, container_bounds, max_scrolls, initial_xml, serial=None):
+    x1, y1, x2, y2 = container_bounds
+    cx = (x1 + x2) // 2
+    height = y2 - y1
+    swipe_from_y = y1 + int(height * 0.7)
+    swipe_to_y = y1 + int(height * 0.3)
+
+    xml_list = []
+    prev_keys = _extract_node_keys(initial_xml) if initial_xml else None
+    scroll_count = 0
+
+    for i in range(max_scrolls):
+        adb_shell("input", "swipe",
+                  str(cx), str(swipe_from_y), str(cx), str(swipe_to_y),
+                  str(SCROLL_DURATION_MS), serial=serial)
+        adb_wait_idle(serial)
+
+        new_xml = _adb_dump_xml_quick(serial=serial)
+        new_keys = _extract_node_keys(new_xml)
+
+        if prev_keys is not None and new_keys == prev_keys:
+            print(f"  Reached bottom after {i + 1} scroll(s)")
+            break
+        prev_keys = new_keys
+        scroll_count += 1
+        xml_list.append(new_xml)
+
+        xml_path = output_dir / f"view_scroll_{i + 1}.xml"
+        xml_path.write_text(new_xml, encoding="utf-8")
+
+        _adb_screenshot(output_dir, f"screenshot_scroll_{i + 1}.png", serial=serial)
+        print(f"  Scroll {i + 1}: XML + screenshot saved")
+
+    if scroll_count > 0:
+        print(f"  Restoring initial position: scrolling back {scroll_count} time(s)...")
+        for i in range(scroll_count):
+            adb_shell("input", "swipe",
+                      str(cx), str(swipe_to_y), str(cx), str(swipe_from_y),
+                      str(SCROLL_DURATION_MS), serial=serial)
+            adb_wait_idle(serial)
+
+    return xml_list
+
+
+def capture_android(output_dir: Path, serial=None, max_scrolls=10):
+    output_dir.mkdir(parents=True, exist_ok=True)
+    print("[1/4] Dumping view XML...")
+    xml_content = _adb_dump_xml(output_dir, serial=serial)
+    if not xml_content:
+        print("[ERR] Failed to dump XML")
+        return
+
+    print("[2/4] Taking screenshot...")
+    _adb_screenshot(output_dir, serial=serial)
+
+    print("[3/4] Checking scrollable containers...")
+    containers = find_scrollable_containers(xml_content)
+    all_xml_contents = [xml_content]
+    if containers:
+        container = containers[0]
+        print(f"  Found scrollable: {container['class']} {container.get('resource-id', '')}")
+        scroll_xmls = _adb_scroll_and_capture(
+            output_dir, container["bounds"], max_scrolls, xml_content, serial=serial,
+        )
+        all_xml_contents.extend(scroll_xmls)
+        print(f"  Scroll capture done: {len(scroll_xmls)} scroll(s)")
+    else:
+        print("  No scrollable container found")
+
+    print("[4/4] Building meta.json...")
+    activity_info = _adb_get_activity(serial=serial)
+
+    seen_clickable = set()
+    clickable = []
+    for idx, xc in enumerate(all_xml_contents):
+        for elem in get_clickable_elements(xc):
+            key = (
+                elem.get("resource-id", ""),
+                elem.get("text", ""),
+                elem.get("content-desc", ""),
+                elem.get("class", ""),
+                elem.get("bounds", ""),
+                elem.get("long-clickable", False),
+            )
+            if key not in seen_clickable:
+                seen_clickable.add(key)
+                elem["scroll_index"] = idx
+                clickable.append(elem)
+
+    meta = {
+        "timestamp": datetime.now().isoformat(),
+        "device": "adb",
+        "activity_info": activity_info,
+        "clickable_count": len(clickable),
+        "clickable_elements": clickable,
+    }
+    (output_dir / "meta.json").write_text(
+        json.dumps(meta, ensure_ascii=False, indent=2), encoding="utf-8",
+    )
+
+    print(f"\nDone! Files saved to {output_dir}")
+
+
+# ---------------------------------------------------------------------------
+# HarmonyOS capture
+# ---------------------------------------------------------------------------
+def _hdc_dump_layout(output_dir: Path) -> tuple[str, str]:
+    """Dump layout JSON, convert to XML. Returns (xml_string, page_name)."""
+    out = hdc_shell("uitest dumpLayout")
+    match = re.search(r"saved to:(.+\.json)", out)
+    if not match:
+        raise RuntimeError(f"Cannot parse dumpLayout output: {out}")
+    remote_json = match.group(1).strip()
+
+    local_json = str(output_dir / "_tmp_layout.json")
+    hdc("file", "recv", remote_json, local_json)
+
+    with open(local_json, "r", encoding="utf-8") as f:
+        data = json.load(f)
+
+    page_name = ""
+    if data.get("children"):
+        page_name = data["children"][0].get("attributes", {}).get("pagePath", "")
+        page_name = page_name.split("/")[-1] if page_name else "unknown"
+
+    root_el = hmos_to_xml(data)
+    tree = ET.ElementTree(root_el)
+    ET.indent(tree, space="  ")
+
+    xml_path = output_dir / "view.xml"
+    tree.write(str(xml_path), encoding="unicode", xml_declaration=True)
+
+    xml_str = ET.tostring(root_el, encoding="unicode")
+
+    os.remove(local_json)
+    return xml_str, page_name
+
+
+def _hdc_dump_layout_quick(output_dir: Path) -> str:
+    """Dump layout and return XML string without saving to view.xml."""
+    out = hdc_shell("uitest dumpLayout")
+    match = re.search(r"saved to:(.+\.json)", out)
+    if not match:
+        return ""
+    remote_json = match.group(1).strip()
+
+    local_json = str(output_dir / "_tmp_layout.json")
+    hdc("file", "recv", remote_json, local_json)
+
+    try:
+        with open(local_json, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        root_el = hmos_to_xml(data)
+        xml_str = ET.tostring(root_el, encoding="unicode") if root_el else ""
+    finally:
+        if os.path.exists(local_json):
+            os.remove(local_json)
+    return xml_str
+
+
+def _hdc_screenshot(output_dir: Path, filename="screenshot.jpeg"):
+    remote_img = "/data/local/tmp/screenshot.jpeg"
+    hdc_shell(f"snapshot_display -f {remote_img}")
+    local_path = output_dir / filename
+    hdc("file", "recv", remote_img, str(local_path))
+
+
+def _hdc_scroll_and_capture(output_dir: Path, container_bounds, max_scrolls, initial_xml):
+    x1, y1, x2, y2 = container_bounds
+    cx = (x1 + x2) // 2
+    height = y2 - y1
+    swipe_from_y = y1 + int(height * 0.7)
+    swipe_to_y = y1 + int(height * 0.3)
+
+    xml_list = []
+    prev_keys = _extract_node_keys(initial_xml) if initial_xml else None
+    scroll_count = 0
+
+    for i in range(max_scrolls):
+        hdc_shell(
+            "uitest", "uiInput", "swipe",
+            str(cx), str(swipe_from_y), str(cx), str(swipe_to_y),
+            str(HDC_SWIPE_SPEED),
+        )
+        hdc_wait_idle()
+
+        new_xml = _hdc_dump_layout_quick(output_dir)
+        new_keys = _extract_node_keys(new_xml)
+
+        if prev_keys is not None and new_keys == prev_keys:
+            print(f"  Reached bottom after {i + 1} scroll(s)")
+            break
+        prev_keys = new_keys
+        scroll_count += 1
+        xml_list.append(new_xml)
+
+        xml_path = output_dir / f"view_scroll_{i + 1}.xml"
+        xml_path.write_text(new_xml, encoding="utf-8")
+
+        _hdc_screenshot(output_dir, f"screenshot_scroll_{i + 1}.jpeg")
+        print(f"  Scroll {i + 1}: XML + screenshot saved")
+
+    if scroll_count > 0:
+        print(f"  Restoring initial position: scrolling back {scroll_count} time(s)...")
+        for i in range(scroll_count):
+            hdc_shell(
+                "uitest", "uiInput", "swipe",
+                str(cx), str(swipe_to_y), str(cx), str(swipe_from_y),
+                str(HDC_SWIPE_SPEED),
+            )
+            hdc_wait_idle()
+
+    return xml_list
+
+
+def capture_hdc(output_dir: Path, max_scrolls=10):
+    output_dir.mkdir(parents=True, exist_ok=True)
+    print("[1/3] Dumping layout (JSON -> XML)...")
+    xml_content, page_name = _hdc_dump_layout(output_dir)
+    if not xml_content:
+        print("[ERR] Failed to dump layout")
+        return
+    print(f"  Page: {page_name}")
+
+    print("[2/3] Taking screenshot...")
+    _hdc_screenshot(output_dir)
+
+    print("[3/3] Checking scrollable containers...")
+    containers = find_scrollable_containers(xml_content)
+    if containers:
+        container = containers[0]
+        print(f"  Found scrollable: {container['class']} {container.get('resource-id', '')}")
+        scroll_xmls = _hdc_scroll_and_capture(
+            output_dir, container["bounds"], max_scrolls, xml_content,
+        )
+        print(f"  Scroll capture done: {len(scroll_xmls)} scroll(s)")
+    else:
+        print("  No scrollable container found")
+
+    print(f"\nDone! Files saved to {output_dir}")
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+def main():
+    parser = argparse.ArgumentParser(description="Capture current page: view tree XML + screenshots (Android / HarmonyOS)")
+    parser.add_argument("--device", choices=["hdc", "adb"], default="hdc",
+                        help="Device type: hdc=HarmonyOS, adb=Android (default: hdc)")
+    parser.add_argument("--output-dir", "-o", type=str, required=True,
+                        help="Output directory for captured files")
+    parser.add_argument("--max-scrolls", type=int, default=10,
+                        help="Max scroll count per container (default: 10)")
+    parser.add_argument("--serial", type=str, default=None,
+                        help="ADB device serial (optional, for multi-device)")
+    args = parser.parse_args()
+
+    output_dir = Path(args.output_dir)
+
+    if args.device == "adb":
+        capture_android(output_dir, serial=args.serial, max_scrolls=args.max_scrolls)
+    else:
+        capture_hdc(output_dir, max_scrolls=args.max_scrolls)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/hmos-ui-align-batch/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: hmos-ui-align-batch
+description: Batch-convert multiple Android Activity UI snapshots to HarmonyOS ArkUI (ArkTS) pages. Use when the user wants to migrate Android UI pages to HarmonyOS in bulk, port multiple Activity screens to ArkTS, or run an Android-to-HarmonyOS UI conversion across a folder of page snapshots (page_NNNN_ActivityName). Triggers on phrases like "把安卓页面迁移到鸿蒙", "Android UI 转鸿蒙", "批量转 ArkTS", "hmos-ui-align_batch", or any request that supplies an Android project path + Harmony project path + a directory of page snapshots.
+---
+
+# hmos-ui-align_batch — Android → HarmonyOS UI Batch Conversion
+
+Batch-convert a set of Android page snapshots (each snapshot is a `page_NNNN_ActivityName/` directory containing `meta.json` + `view.xml` + optional `screenshot.png`) into HarmonyOS ArkTS pages following MVVM architecture.
+
+## Step 1 — Parse User Request
+
+Extract 4 paths from the user's message (natural language, no fixed format):
+
+| Variable | Meaning | Typical Phrases |
+|---|---|---|
+| `android_project_dir` | Android source project root | "Android project path", "安卓项目", "source project" |
+| `harmony_project_dir` | HarmonyOS target project root | "target Harmony project", "鸿蒙项目", "output project" |
+| `ui_info_root` | **Parent directory containing all `page_NNNN_*` subdirectories** | "page screenshots and view tree", "page snapshots", "page folder" |
+| `pages` (optional) | User-explicitly listed page subset | When user lists `1. .../page_0001_X` ... take these |
+
+**`references_dir` and MVVM document directories always use skill-bundled relative paths** — **do not** accept user-provided overrides:
+
+- mappings: `./references/mappings/`
+- mvvm: `./references/mvvm/`
+
+If any required path cannot be extracted from the user's message, **ask the user** — do not guess.
+
+## Step 2 — Resource Conversion
+
+Invoke the `hmos-resources-convert` skill with the following parameters:
+1. **Android project path** = `android_project_dir`
+2. **HarmonyOS project output path** = `harmony_project_dir`
+3. **resource_mapping_path** = generate the resource mapping document under `harmony_project_dir` at `${harmony_project_dir}/resource_mapping.md`
+
+This skill batch-converts Android resources (strings, colors, drawables, images, etc.) to HarmonyOS resource format and generates the mapping document.
+
+## Step 3 — Page Exploration
+
+1. Check if `ui_info_root` already contains `page_*` subdirectories. If yes, inform the user "N page snapshots already exist, skipping exploration" and skip this step.
+2. Otherwise, determine the target App package name (`package`). If the user didn't provide it, extract the `package` attribute from `AndroidManifest.xml` in `android_project_dir`; if still unavailable, ask the user.
+3. Execute with Bash:
+   ```
+   python ./scripts/android_parse_fast.py --package <package_name> --output <ui_info_root_absolute_path>
+   ```
+   This script connects to the Android emulator via ADB, BFS-traverses all reachable pages in the App, and for each page saves `screenshot.png`, `view.xml`, `meta.json` into `page_NNNN_ActivityName/` subdirectories. It also generates `index.json` and `report.html` under `ui_info_root`.
+4. After execution, confirm that `index.json` has been generated under `ui_info_root`. If not, report an error and abort.
+
+## Step 4 — Discover Pages
+
+If the user did not explicitly list pages: use Glob `page_*_*` under `ui_info_root` to find all page subdirectories, sorted by name (`page_0001_*` first).
+
+If the user explicitly listed pages (e.g. "1. .../page_0001_MainActivity ... 19. .../page_0019_MainActivity"): use the user's list.
+
+After discovery, create a task for each page via TaskCreate to track progress.
+
+## Step 5 — Per-Page Conversion
+
+**For each page**, invoke the Agent tool (`subagent_type: general-purpose`) to perform conversion. The prompt must include:
+
+1. The page's `ui_info` absolute path (`{ui_info_root}/page_NNNN_ActivityName`)
+2. `android_project_dir`, `harmony_project_dir`
+3. Absolute paths for mappings and mvvm directories (skill-bundled)
+4. **Copy the full contents of `references/conversion-procedure.md` as the sub-agent's work instructions** (use Read to read it and paste into the prompt)
+
+Why use sub-agents: single-page conversion reads many mapping/MVVM documents + Android source code. Sub-agents isolate context to avoid overwhelming the main session.
+
+After receiving a sub-agent's conversion report, append a brief summary to a cumulative report and mark the corresponding task as completed.
+
+**Execute serially** — do not parallelize (multiple sub-agents modifying the same Harmony project simultaneously will conflict).
+
+## Step 6 — Unified Build Fix
+
+After all page conversions are complete, call the `hmos_fix_build_errors` skill **only once at the end** (passing `harmony_project_dir`) to make the entire project compile. Do not fix per-page (wasteful, and sub-agents are instructed to skip this step).
+
+## Step 7 — Summary Report
+
+Output an overview:
+
+```
+## Batch Conversion Overview
+- Pages processed: N
+- Successful: M   Failed/partial: K
+- Final build status: SUCCESS / PARTIAL
+
+### Per-Page Results
+| Page | Activity | Output File | Status |
+|---|---|---|---|
+| 0001 | MainActivity | pages/MainPage.ets | ✓ |
+| ... | | | |
+
+### Manual Follow-up TODOs
+- (Aggregate mocked items / unimplemented navigation / business logic from sub-reports)
+```
+
+## Key Constraints
+
+- **Never** let a per-page sub-agent call `hmos_fix_build_errors`; do it once in Step 6 only.
+- If the user's `harmony_project_dir` lacks entry/resources subdirectories or the target project doesn't exist, stop and ask — do not generate code.
+- If input paths are Windows paths (with backslashes), pass them as-is to sub-agents; internal Read/Glob support them.