A2H UI Pipeline — Android to HarmonyOS UI Migration

Automated pipeline for migrating Android XML/View-based app UIs to HarmonyOS ArkUI (ArkTS).

Prerequisites / Required Inputs

Input	Description	How to Obtain
android_source_root	Android project root (contains app/src/main/)	Your Android project directory
bfs_output_dir	BFS traversal output (contains page_NNNN_* folders with meta.json + view.xml + screenshot.png)	Strongly recommended: use pre-generated BFS output. Running BFS live requires a connected Android device, is slow (~10-30 min), and may miss pages. Use the BFS script at D:\A2H323\BFS\android_parse.py to generate in advance, or reuse existing output.
harmony_project_dir	Target HarmonyOS project directory	A DevEco Studio project (can be created from template)
reference_tables_dir	Component/layout/interaction mapping tables	Directory containing: android-to-harmonyOS-ui-layout-mapping-reference.md, android-to-harmonyOS-ui-atomic-component-mapping-reference.md, android-to-harmonyOS-ui-interaction-mapping-reference.md

Important: The bfs_output_dir should be prepared before running the pipeline. Each page_NNNN_ActivityName/ folder must contain:

• meta.json — clickable elements, navigation path, activity info
• view.xml — full Android view hierarchy dump
• screenshot.png — screenshot of the page state (optional but recommended)

Generating BFS on-the-fly is not supported by the pipeline. Use existing BFS captures for best results.

Usage

/a2h-ui-pipeline <android_source_root> <bfs_output_dir> <harmony_project_dir> <reference_tables_dir>

Directory Structure

a2h-ui-pipeline/
├── activity-ui-convertor4proj.md                              # Orchestrator (entry point)
├── README.md
├── scripts/
│   └── process_bfs.py                    # Deterministic BFS XML parser
├── skills/
│   ├── converter/SKILL.md                # Core: Single-page UI converter (opus)
│   ├── view_tree_analyzer/SKILL.md       # Source code UI hierarchy analyzer (opus)
│   ├── code_auditor/SKILL.md             # Static code analysis (opus)
│   ├── bfs_parser/SKILL.md               # BFS data parser (sonnet, fallback)
│   ├── resource_preconvert/SKILL.md      # Phase 1.5: Global resource pre-conversion (opus)
│   ├── cross_validator/SKILL.md          # BFS vs Code cross-validation (sonnet)
│   ├── source_comparator/SKILL.md        # Verification: converted vs source (sonnet)
│   ├── build_fixer/SKILL.md              # Build error fixing — full hvigor build loop (opus)
│   ├── ui_repair/SKILL.md                # UI gap repair (opus)
│   ├── check_bfs_parser/SKILL.md         # Self-healing check: BFS output quality
│   ├── check_code_auditor/SKILL.md       # Self-healing check: code audit quality
│   ├── check_cross_validator/SKILL.md    # Self-healing check: cross-validation quality
│   ├── check_converter/SKILL.md          # Self-healing check: conversion quality (per Activity)
│   ├── check_build/SKILL.md              # Self-healing check: build fix integrity
│   ├── check_verify/SKILL.md             # Self-healing check: verification consistency
│   └── android2hmos_resources_convert/   # Resource conversion sub-skill
│       ├── SKILL.md
│       ├── references/                   # Conversion rules, SVG rules, dependency rules
│       └── tools/                        # apktool for APK decompilation
└── references/
    └── README.md

Pipeline Flow

Phase 1: Extract (parallel)
├── 1a: process_bfs.py ──→ pages.json            ──→ Check 1a (self-healing)
├── 1b: Code Auditor   ──→ manifest.json          ──→ Check 1b (self-healing)
└── 1c: View Tree (xN) ──→ {Activity}.ui.json

Phase 1.5: Resource Pre-Conversion
└── Resource Pre-Converter ──→ all shared resources converted to HarmonyOS

Phase 2: Cross-Validate
└── Cross Validator ──→ gaps.json (+ menu_placement) ──→ Check 2 (self-healing)

Phase 3: Convert (per Activity, per Page)
├── 3.0: Group pages by Activity (base page + sub-windows)
├── 3.1: Convert base pages (parallel x N Activities)
│   └── Converter (per page) ──→ .ets + report
├── 3.2: Convert sub-window pages (sequential per Activity, parallel across Activities)
│   └── Converter (per page) ──→ .ets + report
├── 3.3: Wire up cross-page events per Activity
└── Check 3 (self-healing, per Activity — dispatches repair immediately)

Phase 4: Build Fix
└── Build Fixer (full hvigor loop) ──→ compilable project ──→ Check 4 (self-healing)

Phase 5: Verify
└── Source Comparator ──→ source_diff.json ──→ Check 5 (self-healing — dispatches repair directly)

Phase 6: Final Safety Net (max 1 loop, only if gaps remain after self-healing)
└── UI Repair → back to Phase 4

Key Design Principles

• BFS > Code for runtime layout (toolbar buttons, menu items, conditional visibility)
• Code > BFS for widget structure, resources, handler logic
• Every phase has a self-healing Check — issues detected and auto-fixed immediately, not deferred
• Global resource pre-conversion — shared resources converted once in Phase 1.5, not per-Activity
• All results written to files — full audit trail in {work_dir}/
• Checkpoint/resume — restart from last completed phase
• Per-page conversion — each converter handles one page at a time (base page or sub-window)
• Parallel execution — Phase 1 (3-way), Phase 3 (base pages across Activities; sub-windows across Activities)
• Build Fixer is self-contained — full hvigor CLI build loop with error table, no external skill dependency

Work Directory Output

All intermediate and final results are written to {work_dir} (default: <android_source_root>/../.a2h-ui-pipeline/):

.a2h-ui-pipeline/
├── checkpoint.json
├── pages.json                       # BFS parser output
├── manifest.json                    # Code auditor output
├── custom_view_mapping.json
├── gaps.json                        # Cross-validation output
├── source_diff.json                 # Verification output
├── resource_preconvert_report.json  # Phase 1.5 resource conversion report
├── build_fix_report.json            # Build fixer report
├── view_trees/                      # Per-Activity source analysis
│   ├── MainActivity.ui.json
│   ├── MainActivity.analysis.md
│   └── MainActivity.viewtree.md
├── resources_staging/               # Per-Activity staged resources (fallback only)
├── conversion_reports/              # Per-Activity conversion reports (.md)
├── repair_reports/                  # Per-Activity repair reports (.md)
├── checks/                          # All check outputs (.json)
│   ├── check_bfs.json
│   ├── check_code.json
│   ├── check_crossval.json
│   ├── check_convert_{Activity}.json
│   ├── check_build.json
│   └── check_verify.json
├── loop_history/                    # Archived diffs per repair loop
└── final_report.json