android2harmony 0.1.2 → 0.1.3

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

@@ -0,0 +1,365 @@
+---
+name: hmos-incremental-ui-align
+description: "Automated HarmonyOS-Android UI alignment pipeline. Takes a natural language task description, automatically navigates to the target pages on both Android and HarmonyOS devices, captures view trees and screenshots, then aligns HarmonyOS code to match Android. Use this skill whenever the user wants to align a HarmonyOS page with its Android counterpart, fix visual differences between Android and HarmonyOS, add missing HarmonyOS pages based on Android, or describes a page path like '首页-设置-关于' that needs UI alignment. Also trigger on phrases like 'UI对齐', '页面对齐', '和安卓对齐', '鸿蒙页面修复','UI增量开发'，'align HarmonyOS with Android', or any request involving comparing and fixing HarmonyOS UI to match Android."
+---
+
+# HarmonyOS-Android UI Alignment 
+You are a senior engineer proficient in Android and HarmonyOS app development, with expertise in HarmonyOS technologies such as ArkTS and ArkUI.
+You must follow the pipeline in this document, executing the steps one by one.
+You are writing ArkTS codes.
+
+# Rules
+- Use Mock Data unless the user tell you to implement/align the feature together**
+- you can not start Step 2 until Step 1 is completely finished
+- Do not proceed to Step 3 until every page pair has its `UI_comparison.md` written in Step 2
+- Step 2 MUST be executed by the main agent sequentially (not delegated to background agents). Each sub-step (2.1 → 2.2 → 2.3) must complete and be verified before the next begins.
+- If mock data is required, write them in `{harmony_project_dir}/entry/src/main/ets/model/` according to the hmos MVVM mode (V1 or V2, per the paradigm detected in Step 3.1).
+- Do not make any other changes unrelated to the user's requirements.
+
+**Skill scripts** (TypeScript, run directly with `node` — Node ≥ 22.18/23.6, no build step, no third-party deps; all paths relative to this skill's root):
+- `navigation_tool` = `./scripts/app_feature_verify.ts`
+- `capture_tool` = `./scripts/page_capture.ts`
+- `burst_capture_tool` = `./scripts/page_capture_burst.ts` — continuous view-tree+screenshot capture at ~1s intervals, for multi-state components (Step 1.5)
+- `checklist_tool` = `./scripts/extract_checklist.ts` — deterministically extracts all diffs from `UI_comparison.md` files into `fix_checklist.md` (used in Step 3)
+
+## Step 0: Resolve Inputs
+
+This skill takes three path inputs from the invocation and resolves its other settings along the standard chain — **OS environment variable → `~/.hometrans/config.json` → ask the user** (see Step 0.0).
+
+### Skill input arguments (provided by the user when invoking the skill)
+
+| Argument | Required | Description |
+|---|---|---|
+| `android_project_dir` | yes | Android source code root path |
+| `harmony_project_dir` | yes | HarmonyOS project root path (will be modified) |
+| `capture_output_dir` | no | Base dir for captured page data (screenshots / view trees / analysis). Default: `<harmony_project_dir>/.hometrans/capture_output` under the current working directory |
+
+The user may pass them as named args (e.g. `android_project_dir: D:\path\to\android`) or describe them in the request. If `android_project_dir` or `harmony_project_dir` cannot be determined from the invocation, **ask the user** before proceeding.
+
+### Step 0.0: Environment Variables Check (run first)
+
+Resolve each value along the standard chain — **OS environment variable first, then `~/.hometrans/config.json`, then ask the user** (read env vars with `echo "$VAR"` on macOS/Linux; `$env:VAR` in PowerShell / `echo %VAR%` in cmd on Windows).
+
+| Variable | config.json fallback | Purpose | Valid when |
+|---|---|---|---|
+| `HOMETRANS_MODEL_*` (`HOMETRANS_MODEL_API_KEY` / `_NAME` / `_BASE_URL`) | `autotest.unified_model.{api_key,name,base_url}`（provider 默认 openai；再兜底 `GLM_API_KEY` → 智谱 GLM 端点） | 统一多模态模型（UI 对齐 + 自测共用） | 插件场景：由 `a2h_app_feature_verify` 工具经 stdin 注入（host 解析，无需手动设）；直接 `node` 运行：`HOMETRANS_MODEL_API_KEY` 非空或 config.json 已配置或 `GLM_API_KEY` 已设置 |
+| `OHOS_SDK_PATH` | `env.OHOS_SDK_PATH` | HarmonyOS SDK ETS API reference (Step 3) | path exists on disk |
+| `HMS_SDK_PATH` | `env.HMS_SDK_PATH` | HMS SDK ETS API reference (Step 3) | path exists on disk |
+
+The model config is injected automatically: in the plugin context the `a2h_app_feature_verify` tool resolves the key from the host and pipes it to `scripts/app_feature_verify.ts` over stdin (`--model-stdin`), so the key never sits in an env var and is not visible to the spawned adb/hdc subprocesses — you do not read or pass the key by hand. For a direct `node scripts/app_feature_verify.ts` run (no tool, e.g. debugging), the script still resolves `--api-key` → `HOMETRANS_MODEL_*` env → `~/.hometrans/config.json` → `GLM_API_KEY`; ensure one of those is set. For `OHOS_SDK_PATH` / `HMS_SDK_PATH`, if both the env var and `~/.hometrans/config.json` are empty but `DEVECO_SDK_HOME` is set (env or `env.DEVECO_SDK_HOME` in config.json), derive them as `<DEVECO_SDK_HOME>/default/openharmony/ets` and `<DEVECO_SDK_HOME>/default/hms/ets`.
+
+For each value that is still missing/empty (or a path that does not exist) after both the env var and `~/.hometrans/config.json`, **stop and ask the user to provide a value**, then use what they give for this run. Suggest running `ht init` to persist them as machine environment variables for next time.
+
+### Step 0.1: Auto-derive App Names & Package Names
+
+`android.app_name` / `android.package` / `harmony.app_name` / `harmony.package` are required for navigation (passed to the `a2h_app_feature_verify` tool as `--app` / `--package`). They are not provided as inputs — resolve them from the project dirs (`android_project_dir` / `harmony_project_dir`) as follows.
+
+**`app_name` matters because it is the launcher label the navigator taps to open the app** — when the resolved label is a localized resource and a Chinese (`zh`) variant exists, prefer the Chinese value (devices are typically zh-CN).
+
+#### Android (from `android_project_dir`)
+1. **`android.package`** — locate the application module (the module whose Gradle file applies `com.android.application`, usually `app/`):
+   - Read `applicationId` from `{module}/build.gradle` (Groovy: `applicationId "com.x"`) or `build.gradle.kts` (Kotlin DSL: `applicationId = "com.x"`). Use the default/base `applicationId`; ignore flavor-specific `applicationIdSuffix`.
+   - Fallback: the `package="..."` attribute in `{module}/src/main/AndroidManifest.xml`.
+2. **`android.app_name`** — in `{module}/src/main/AndroidManifest.xml`, read `android:label`. Prefer the launcher `<activity>` label (the activity whose `<intent-filter>` has `android.intent.action.MAIN` + `android.intent.category.LAUNCHER`); if it has none, use the `<application>` label.
+   - If the label is a literal string, use it directly.
+   - If it is `@string/<name>`, resolve `<name>` in the string resources: prefer a Chinese variant (`{module}/src/main/res/values-zh-rCN/strings.xml`, else `values-zh/strings.xml`), falling back to the default `values/strings.xml`. Use the matching `<string name="<name>">…</string>` value.
+
+#### HarmonyOS (from `harmony_project_dir`)
+1. **`harmony.package`** — read `app.bundleName` from `{harmony_project_dir}/AppScope/app.json5`.
+2. **`harmony.app_name`** — read `app.label` from `{harmony_project_dir}/AppScope/app.json5`.
+   - If it is a literal string, use it directly.
+   - If it is `$string:<name>`, resolve `<name>`: prefer a Chinese element dir (`{harmony_project_dir}/AppScope/resources/zh_CN/element/string.json`, else `zh/element/string.json`), falling back to `base/element/string.json`. Find the entry in `string[]` whose `name` equals `<name>` and use its `value`.
+
+After resolving all four, briefly echo them to the user (e.g. `android.app_name="…", android.package="…", harmony.app_name="…", harmony.package="…"`) before starting Step 1. If any value cannot be resolved from the project dir, ask the user to supply it.
+
+## Step 1: Capture All Related Pages on Android & HarmonyOS Devices
+
+Read `scripts/navigation-capure.md` to learn the usage of `scripts/app_feature_verify.ts` (navigation) and `scripts/page_capture.ts` (capture).
+
+### Step 1.1: Parse User Request and Build Capture Plan
+Analyze the user's description and build a list of **base pages** to capture.
+- **Specific path** (e.g., "首页 → 设置 → 关于"): add it directly as a base page with the given click path.
+- **Ambiguous scope** (e.g., "播放列表歌曲页的所有二级弹窗"): identify one determinable base page first — interactive sub-states (tabs, popups, etc.) will be discovered automatically in Step 1.3.
+
+For each base page, define:
+- `page_name`: short identifier (e.g., `enterprise_detail`)
+- `android_nav_path` / `hmos_nav_path`: the navigation prompt for each device
+
+Create the timestamped output directory and per-page sub-directories following the pattern in `scripts/navigation-capure.md`.
+
+### Step 1.2: Capture Base Pages
+For each base page in the plan, on **both** Android and HarmonyOS devices:
+1. Use the `a2h_app_feature_verify` tool to navigate to the page (it runs `scripts/app_feature_verify.ts` with the model key piped over stdin, so the key is not leaked into env/argv).
+2. On success, use `scripts/page_capture.ts` to capture the view tree and screenshot.
+3. For HarmonyOS pages that don't exist yet, navigation will fail — leave the directory empty (expected).
+
+### Step 1.3: Discover and Capture Interactive States
+After capturing each base page, scan its view tree for **interactive elements that change the visible UI**, including but not limited to:
+- Tabs / Segmented controls (each tab shows different content)
+- Filter / Sort / Dropdown trigger buttons (clicking opens a popup, bottom sheet, or dropdown)
+- Expandable / Collapsible sections ("展开"/"收起", accordion)
+- Any other clickable element that reveals content not visible in the current capture (toggle, switch-mode button, etc.)
+
+**For each interactive element found:**
+1. Create a separate capture directory: `{platform}_page_{i}_{base_name}_{state_type}_{state_name}` (e.g., `android_page_1_detail_tab_city`, `android_page_1_detail_popup_filter_identity`).
+2. Navigate to the base page (reuse the same nav path), then append the click action to trigger the state change. Capture with `scripts/page_capture.ts`.
+3. Repeat for **both** Android and HarmonyOS devices.
+4. Each captured state is treated as a separate page pair in Step 2 and Step 3.
+
+**Skip condition**: Only skip this step for a specific page if the user explicitly says to ignore interactive states (e.g., "只对齐主页面，不管弹窗和tab").
+
+### Step 1.4: Source Code Scan for Dynamic / Transient / Non-Touch UI
+
+Static screenshots and view trees cannot capture animations, transient UI (Toast, Snackbar), or UI triggered by voice/sensors. This step extracts those effects from source code.
+
+**Scan scope**: Only scan source files related to the pages captured in Step 1.2/1.3 (use Activity/Fragment names from navigation to locate relevant files).
+
+**Search patterns** (in `android_project_dir`):
+
+| Category | Grep patterns |
+|----------|--------------|
+| Animation | `ObjectAnimator`, `ValueAnimator`, `AnimatorSet`, `@anim/`, `animateLayoutChanges`, `MotionLayout`, `Transition`, `LottieAnimationView`, `setAnimation` |
+| Transient UI | `Toast.makeText`, `Snackbar.make`, `PopupWindow`, `ToolTip`, `postDelayed.*GONE\|VISIBLE`, `CountDownTimer` |
+| Voice/Sensor | `SpeechRecognizer`, `VoiceInteractionService`, `SensorManager`, `MediaRecorder` |
+| External event UI | `BroadcastReceiver`+UI updates, `onMessageReceived` (FCM/JPush) |
+
+**Output**: Write `{task_dir}/dynamic_ui_inventory.md` with this format:
+```markdown
+# Dynamic UI Inventory
+| Type | Trigger | Source File:Line | Target UI Component | Effect Description | Duration/Timing |
+|------|---------|-----------------|--------------------|--------------------|-----------------|
+| animation | page enter | LoginActivity.kt:45 | logo_image | scale 0→1 + fade in | 400ms, overshoot |
+| Toast | login success | LoginActivity.kt:112 | — | "登录成功" | 2000ms auto-dismiss |
+| voice input | mic button click | SearchActivity.kt:78 | voice_wave_view | shows waveform animation | until recognition ends |
+```
+
+**Skip condition**: If grep finds zero matches across all patterns for a page's related source files, note "No dynamic UI found" for that page and proceed.
+
+### Step 1.5: Stateful Component Analysis (Multi-State UI)
+
+This step identifies components with multiple distinct UI states driven by user interaction (e.g., voice input: idle → recording → cancelling → recognized) and builds a state transition model from source code.
+
+#### Step 1.5.1: Identify Multi-State Components
+
+**Trigger conditions** (any one):
+- User description explicitly mentions state changes ("语音输入各状态", "按住说话的录音和取消", "各个弹窗状态")
+- Step 1.4 source scan discovers ≥3 distinct UI state values in the same component
+
+**Grep patterns (Android)**:
+- `enum.*State` / `sealed class.*State` / `companion object.*STATE`
+- `when.*state` / `switch.*state` / `if.*state ==`
+- `setVisibility.*GONE|VISIBLE` (multiple occurrences in same method)
+- `LiveData<.*State>` / `MutableStateFlow<.*State>`
+
+**Grep patterns (HarmonyOS)**:
+- `@State.*state` / `enum.*State`
+- `if.*this.state` / `switch.*this.state`
+- `.visibility(this.state ===`
+- `@Watch` decorators on state variables
+
+**Output**: List of multi-state components to analyze.
+
+#### Step 1.5.2: Build State Transition Model
+
+For each identified multi-state component, read the relevant source code and produce a state model following the template in `references/State_Model_Template.md`.
+
+The model MUST include:
+1. **State enumeration** — all possible states with UI descriptions
+2. **Transitions** — from/to/trigger/gesture type/threshold/duration, each with source file:line
+3. **Per-state UI properties** — visibility, background, text, color, border, animation, all traced to source
+4. **Animations between states** — property/from/to/duration/easing
+
+**Key constraint**: Every UI property and transition condition MUST reference a source code location. No estimation from screenshots.
+
+**Output**: Write `{task_dir}/state_model.md`
+
+#### Step 1.5.3: Capture State Snapshots
+
+**For auto-capturable states** (single tap, simple long-press then release):
+1. Navigate to the component's page
+2. Start `scripts/page_capture_burst.ts` (see `scripts/navigation-capure.md` for burst workflow)
+3. Trigger the state via the `a2h_app_feature_verify` tool
+4. Select representative frames from burst output
+
+**For non-auto-capturable states** (long-press hold, drag, pan, sensor, voice):
+Generate manual capture instructions and present them to the user. Wait for user confirmation before proceeding.
+
+**Auto-capture feasibility rules**:
+| Gesture | Auto? | Reason |
+|---------|-------|--------|
+| Single tap | Yes | phone-agent supports directly |
+| Long-press then release | Yes | decompose to press → wait → release |
+| Long-press and hold | **No** | must maintain pressure during burst |
+| Drag/Pan with threshold | **No** | requires precise coordinates + simultaneous capture |
+| Sensor/Voice input | **No** | requires physical input |
+
+#### Step 1.5.4: Expand States into Virtual Page Pairs
+
+Each captured state becomes a standalone page pair for Step 2:
+```
+{platform}_page_{i}_{base_name}_state_{state_id}_{state_name}/
+  screenshot_001.png   (representative frame from burst or manual capture)
+  view_001.xml
+  state_context.md     (state's entry from state_model.md)
+```
+
+These virtual page pairs follow the same naming convention and enter Step 2 identically to base pages.
+
+#### Step 1.5.5: Skip Condition
+If no multi-state components are identified (neither from user description nor from Step 1.4 grep results), skip Step 1.5 entirely and proceed to Navigation Rules → Step 2.
+
+### Navigation Rules (apply to all capture operations in Step 1)
+
+**Click path extraction**: do not replace or translate key operations of hdc/adb (such as drag, swipe).
+**When navigation fails**:
+Firstly, make sure whether the page exists, then:
+1. Page does not exist → record the result and skip the capture.
+2. Page exists but click path is wrong → force-stop and restart the app, retry with the corrected path.
+3. Page exists, path is correct, but the tool reports failure → review the screenshot yourself and decide whether the target was actually reached.
+**Must Remember**: Do not skip any page on Android/HarmonyOS unless navigation fails more than twice.
+
+## Step 2: UI Diff Analysis 
+
+**CRITICAL RULES for Step 2**:
+- Android `UI_Analysis.md` MUST be generated for EVERY page, even if HarmonyOS capture is empty
+- HarmonyOS `UI_Analysis.md` (or `UI_Analysis_from_code.md`) MUST be generated for EVERY page
+- `UI_comparison.md` MUST contain a real markdown diff table (not just a status note)
+
+ **Dimension rule (applies to Step 2.1, 2.2, and 2.3)**:
+ All size/position values must include:
+ - raw px value (from view tree bounds)
+ - device density (read from the page's `meta.json` → `density_factor`; e.g. 3.0)
+ - converted dp/vp value (px ÷ density_factor)
+ Format: "126px (3.0x → 42vp)". Never write bare px or vp without the other.
+ **Density source**: `scripts/page_capture.ts` records the real device density into each capture directory's `meta.json` (`dpi` and `density_factor`). Read `density_factor` from there per page — do NOT assume 3x. Android and HarmonyOS captures may have different densities, so convert each side using its own `meta.json`. If a page's `meta.json` is missing `density_factor`, fall back to 3.0 and note the assumption.
+ **MANDATORY OUTPUT**: Write the result to `android_page_{i}_{name}/UI_Analysis.md`，写完后确认文件已创建。
+ **This step is NEVER skippable** — even if the HarmonyOS counterpart is empty, the Android analysis must still be written.
+
+For each page  <`android_page_{i}_{name}`,`hmos_page_{i}_{name}`> collected in {Step 1}, write UI Analysis using the Analysis Template in `references/UI_Analysis_Template.md`:
+### Step 2.1 UI Analysis of `android_page_{i}_{name}`
+ Read `android_page_{i}_{name}` 目录下的 screenshot(_n) 和 view tree(_n) 信息，以 table 形式列举出该页面所有组件，每个组件包含位置、颜色、icon、大小、形状、文字内容、alignment(居中、靠左、靠右等)等一切视觉要素。
+ Additionally, check `{task_dir}/dynamic_ui_inventory.md` for any dynamic/transient effects related to this page and include them in the analysis under a "Dynamic / Transient UI Effects" section (see template).
+ **MANDATORY OUTPUT**:  following the template `references/UI_Analysis_Template.md` to write the result to `android_page_{i}_{name}/UI_Analysis.md`，写完后确认文件已创建。
+
+### Step 2.2 UI Analysis of `hmos_page_{i}_{name}`
+ if `hmos_page_{i}_{name}` has screenshots and view trees:
+    Read `hmos_page_{i}_{name}` 目录下的 screenshot 和 view tree 信息，以 table 形式列举出该页面所有组件，每个组件包含位置、颜色、icon、大小、形状、文字内容、alignment(居中、靠左、靠右等)等一切视觉要素。
+    Additionally, analyze the HarmonyOS source code for any dynamic/transient effects (e.g., `animateTo()`, `promptAction.showToast()`, `.transition()`) and include them in the "Dynamic / Transient UI Effects" section.
+    **MANDATORY OUTPUT**:  following the template `references/UI_Analysis_Template.md` to Write the result to `hmos_page_{i}_{name}/UI_Analysis.md`，写完后确认文件已创建。
+ if `hmos_page_{i}_{name}` is empty (no screenshots/view trees captured):
+    Read the HarmonyOS source code at `harmony_project_dir` to find the corresponding page implementation. Analyze the source code to extract all UI components, their properties, layout structure, colors, dimensions, and text content. Also extract any dynamic/transient effects from the code. Create a comprehensive component table from the code analysis.
+    **MANDATORY OUTPUT**:  following the template `references/UI_Analysis_Template.md` to Write the result to `hmos_page_{i}_{name}/UI_Analysis_from_code.md`，写完后确认文件已创建。
+    **DO NOT** write a placeholder like "page not captured" — you must actually read the source code and produce a real analysis.
+### Step 2.3 Make UI Diff Analysis and Write the Comparison Table
+**Input requirement**: You MUST Read the already-written `android_page_{i}_{name}/UI_Analysis.md` and `hmos_page_{i}_{name}/UI_Analysis.md` (or `UI_Analysis_from_code.md`) files using the Read tool before writing the comparison. Do NOT generate the comparison from raw view trees, screenshots, or source code directly — the comparison must be derived from the two Analysis documents.
+
+Using `android_page_{i}_{name}/UI_Analysis.md` as the ground truth, compare the detailed differences of each component between `android_page_{i}_{name}/UI_Analysis.md` and `hmos_page_{i}_{name}/UI_Analysis.md` (or `hmos_page_{i}_{name}/UI_Analysis_from_code.md` if hmos page was empty), and list them in a table like `references/Comparison_Template.md`
+
+**Quality requirement for UI_comparison.md**:
+- The file MUST contain a markdown table with `|` delimiters listing every component
+- If HarmonyOS page is missing entirely, each diff column must state the Android target value as the implementation spec, not just "缺失". Format: "HarmonyOS: 缺失 → 目标: {Android的具体值}". Example: Alignment Diff = "HarmonyOS: 缺失 → 目标: 左对齐". Example: Text Color Diff = "HarmonyOS: 缺失 → 目标: #333333". A column that only says "缺失" without a target value is INVALID.
+- A comparison that only says "page not captured" or "needs implementation" without a component-level table is INVALID
+- **Dynamic UI Diff**: After the static component table, include a separate "Dynamic / Transient UI Comparison" table comparing animation parameters (duration, easing, properties), transient UI (Toast text, duration, trigger condition), and non-touch input support (voice, sensor). Format same as static diff: "HarmonyOS: {current} → 目标: {Android value}".
+- **State Machine Diff** (for Step 1.5 components only): After the Dynamic UI table, include a "State Machine Comparison" section following `references/Comparison_Template.md`. This must cover: state count diff, per-transition trigger/threshold diff, and per-state visual property diff. Each diff must reference the source line from `state_model.md`.
+
+**MANDATORY OUTPUT**: Write the comparison table into `hmos_page_{i}_{name}/UI_comparison.md`
+
+### Step 2.4 Output Verification (Main Agent)
+MUST verify:
+1. Use Glob to list all `**/UI_Analysis*.md` files — confirm one exists for every `android_page_*` and every `hmos_page_*` directory
+2. Use Glob to list all `**/UI_comparison.md` files — confirm one exists for every `hmos_page_*` directory
+3. For each `UI_comparison.md`, Read the first 10 lines and confirm it contains a markdown table (has `|` characters)
+4. If ANY file is missing or invalid, re-run Step 2 for that specific page pair before proceeding
+
+## Step 3: Fix UI Diffs or Implement Missed Pages (MainAgent)
+
+**CHECKPOINT — before proceeding, you MUST**:
+1. For every page pair, use the Read tool to open `hmos_page_{i}_{name}/UI_comparison.md` and confirm it exists and contains a markdown diff table (has `|` delimiters with component rows).
+2. If any `UI_comparison.md` is missing or contains only a status note without a component table, go back to Step 2 and complete it. For pages where HarmonyOS was not captured, read the source code to generate `UI_Analysis_from_code.md` first, then regenerate the comparison with a proper component-level diff table.
+3. Generate `{task_dir}/fix_checklist.md` **deterministically** by running the extraction script — do NOT hand-enumerate diffs from the comparison tables (manual enumeration is the main cause of missed items):
+```bash
+node ./scripts/extract_checklist.ts --task-dir "{task_dir}"
+```
+The script parses ALL five table types in every `UI_comparison.md` (main static component table, Dynamic / Transient UI, State Machine, Per-Transition, Per-State Visual), skips rows whose Diff cell is empty / "一致" / "-", splits a row carrying multiple diffs (separated by `；`, `;`, or `<br>`) into separate items, and tags items with `[DYNAMIC]` / `[STATE]` / `[TRANSITION]` prefixes. It prints a per-page reconciliation table (`diff_rows` vs `items`).
+
+4. **Reconciliation gate** — read the script's stdout report and the generated `fix_checklist.md`:
+   - For every page, confirm `items >= diff_rows`. Any row flagged `<-- CHECK` means a diff row produced no item → open that `UI_comparison.md` and find why (malformed Diff cell, missing Diff column). Fix the comparison file and re-run the script.
+   - If the report shows `total diff rows: 0` or a page shows `tables=0` (only a status note, no real table), that page's Step 2 is incomplete → go back to Step 2, generate `UI_Analysis_from_code.md` from HarmonyOS source if the page was not captured, regenerate the comparison with a real component-level diff table, then re-run the script.
+   - Only after the script output covers every page with no `<-- CHECK` flags is the checklist trustworthy.
+
+5. **Review pass (human-readable refinement)** — the script output is a faithful but raw draft. Edit `fix_checklist.md` to: merge exact duplicates, make terse cells read as actionable instructions, and keep the auto-generated `<!-- source: ... -->` comment line under each page heading (it records the provenance and row/item counts for the final review in Step 3.4). Do NOT delete any item during this pass — only merge true duplicates.
+
+This checklist is your single source of truth for what needs to be fixed. The format is:
+```
+# Fix Checklist
+## hmos_page_{i}_{name}
+<!-- source: ... | tables=N | diff_rows=N | items=N -->
+- [ ] {diff description 1}
+- [ ] [DYNAMIC] {effect}: {diff}
+- [ ] [STATE] {state}: {diff}
+...
+```
+
+For **multi-state components** (from Step 1.5), use tagged prefixes in the checklist:
+```
+## Component: {name} (Stateful)
+- [ ] [STATE] 实现 {state_name} 状态 ({state_id}): {UI description}
+- [ ] [TRANSITION] {from}→{to}: {gesture type} {threshold/condition}
+- [ ] [ANIMATION] {state}: {animation description with params}
+```
+
+### Step 3.1: Analyze Project Architecture and load knowledge (Main Agent)
+    1. understand the existing HarmonyOS project's architecture, analyze existing patterns and identify {reusable components}.
+    2. **Detect the project's state-management paradigm (V1 vs V2)** before loading MVVM docs — decide once at project level and keep it for the whole task:
+       - Scan existing `.ets` under `{harmony_project_dir}/entry/src/main/ets/` for decorators:
+         - `@Component` + `@State`/`@Prop`/`@Link`/`@Provide`/`@Consume`/`@Observed`/`@ObjectLink`/`@Watch` → **V1**
+         - `@ComponentV2` + `@Local`/`@Param`/`@Once`/`@Event`/`@ObservedV2`/`@Trace`/`@Monitor`/`@Provider`/`@Consumer` → **V2**
+       - Empty project / 0→1 fresh conversion / no state decorators → **default V2**; only-V1 → V1; only-V2 → V2; both → follow the majority and match the target page's existing directory, note it in the report.
+       - Do NOT mix V1 and V2 decorators in the same project/component. Detection rule detailed in `./references/MVVM开发文档V2/_范式选择说明.md`.
+    3. Load the matching MVVM docs:
+       - **V1** → read `./references/MVVM开发文档/MVVM模式V1.md` (and other V1 decorator docs in that dir as needed)
+       - **V2** → read `./references/MVVM开发文档V2/MVVM模式（V2）.md` (and other V2 decorator docs in that dir as needed)
+**Note**: If mock data is required, add them in **Model Layer** according to the detected MVVM paradigm.
+
+### Step 3.2: Learn typical transformation rules
+    read `page_align.md` to learn typical transformation rules
+
+### Step 3.3 Fix all Diffs
+    Read `{task_dir}/fix_checklist.md` and **Fix Every Diffs (No Matter significant or minor)**，
+    Use {reusable components} if it is available and has been aligned with Android
+    Following the MVVM mode
+
+**Value tracing rule**: Before fixing any dimension/size/icon-size/alignment diff, you MUST trace the target value back to Android source code (layout XML `layout_width`/`layout_height`/`padding`/`src`, drawable intrinsic size, or style definition). Write the source reference (file:line or resource name) next to the checklist item. Estimating from screenshots or "looks about right" is NOT acceptable — if the Android source cannot be located, flag the item and ask the user.
+**Alignment rule**: When implementing a new component or fixing an existing one, explicitly set alignment/justification for EVERY text and container element. Copy the alignment value directly from the Android UI_Analysis.md (e.g., "左对齐" → `.textAlign(TextAlign.Start)` + `.width('100%')`). Never rely on default alignment — always set it explicitly.
+**Stateful component rule** (for [STATE]/[TRANSITION]/[ANIMATION] items):
+- State enumerations must map 1:1 with Android states (same count, same semantics)
+- Transition conditions (gesture type, threshold in vp, delay in ms) must be traced to Android source — copy values exactly
+- Animation parameters (duration, easing, property, from/to values) must match Android precisely — refer to `state_model.md` for source references
+- Implement state changes using HarmonyOS `@State` + conditional rendering or `.visibility()` per the MVVM pattern
+- For gesture-triggered transitions, use ArkUI gesture APIs: `LongPressGesture`, `PanGesture`, `TapGesture` per `references/android-to-harmonyOS-ui-interaction-mapping-reference.md`
+**After fixing each diff, update `fix_checklist.md`**: change `- [ ]` to `- [x]` for the completed item.
+**CRITICAL RULE**: 
+- Do not skip any diff item in `fix_checklist.md`, regardless of the priority.
+- Fixing compile errors does NOT count as fixing UI diffs. After the build passes, you MUST return to `fix_checklist.md` and continue fixing any remaining unchecked items. The task is not complete until every item in the checklist is marked `[x]`.
+
+### Step 3.4 Final Checklist Review
+Read `fix_checklist.md` and verify every item is marked `[x]`. If any items remain unchecked:
+1. List the unchecked items
+2. For each, explain why it was not fixed (blocked by missing API, requires backend, etc.) or fix it now
+3. Items that genuinely cannot be fixed should be marked with `- [~]` and a reason
+
+**Coverage re-check**: For each page, the `<!-- source: ... | items=N -->` comment records how many items the script extracted. Confirm the number of `- [x]`/`- [~]` lines under each page heading still matches that `items=N` count — if fewer, items were silently dropped during the review pass; recover them from the page's `UI_comparison.md`.
+
+## Step 4 validate and build (Main Agent)
+if available, use `hmos-fix-build-errors` skill to verify the project is compilable, do not deploy.
+
+## Guidelines
+- **Preserve existing code**: When editing existing files, make targeted edits — never rewrite an entire file from scratch. Respect the existing code structure, variable names, and patterns.
+- **Follow existing conventions**: All new code must match the HarmonyOS project's established naming conventions, import patterns, state management approach, and component composition style.
+- **Reuse rather than creating**: Always check for existing shared components, viewmodels, and models before creating new ones.
+- **Resource references must match exactly**: every color, string, dimension, image, and other resource used in the Android source must have a corresponding HarmonyOS resource. Do not hardcode values.
+- Use `$r('app.type.name')` for all resource references available in the resource list.
+- Handle responsive layouts: prefer percentage widths and `Flex` over fixed dimensions where appropriate.
+- Maintain accessibility: convert `content-desc` to `.accessibilityText()`, convert meaningful `text` to proper labels.
+- Group related UI into `@Component` sub-components when the hierarchy is deep (> 5 nesting levels).
+- **鸿蒙 API 可参考 `OHOS_SDK_PATH` / `HMS_SDK_PATH`（HarmonyOS SDK 的 ETS 目录，取自 OS 环境变量）；鸿蒙 MVVM 开发模式：V1 参考 `./references/MVVM开发文档/`，V2 参考 `./references/MVVM开发文档V2/`（按 Step 3.1 探测到的工程范式二选一，详见 `./references/MVVM开发文档V2/_范式选择说明.md`）**

package/skills/hmos-incremental-ui-align/diff_analysis.md

@@ -0,0 +1,53 @@
+### Diff Analysis 
+use `{android_page_info}`, `{hmos_page_info}`,`{android_project_dir}`,`{harmony_project_dir}` to make a detailed comparison on visual effects
+
+#### Step 1: Parse Android View Hierarchy
+
+Read `{android_page_info}/view.xml` and build a structural understanding:
+- Parse the XML node tree to understand the full view hierarchy
+- Identify the key structural containers (root layouts, toolbar, content area, bottom navigation)
+- Map each Android widget node to its attributes: `class`, `resource-id`, `text`, `content-desc`, `bounds`, `clickable`, `scrollable`, `checkable`, `checked`, `enabled`
+- Calculate layout relationships from `bounds` (parent-child containment, sibling positioning)
+- Identify recurring patterns (list items, grid items, card layouts)
+
+If there exist `view_scroll_n.xml` files (n = 1, 2, 3, ...), read each one and merge their structural understanding with `view.xml` (the Android UI is longer than one screen).
+
+Read the Android `screenshot.png` (and `screenshot_scroll_n.png` if they exist) to visually understand the target UI.
+
+Additionally, find and read the static XML layout files and Kotlin/Java code files in `{android_project_dir}` that correspond to this page. Use atomic Android components to replace user-defined and third-party components, building a **final Android structural understanding**.
+
+
+#### Step 2: Parse HarmonyOS Current State
+
+Read the HarmonyOS view tree XML and screenshot from `{hmos_page_info}/`:
+- Parse the HarmonyOS view hierarchy to understand the current UI structure
+- Read the screenshot to visually understand the current state
+
+Also read the corresponding `.ets` source file(s) in `{harmony_project_dir}` for this page:
+- Identify the existing component structure, state variables, child components
+- Understand how the page is currently implemented
+
+Build a **current HarmonyOS structural understanding**.
+
+#### Step 3: Diff Analysis 
+
+Compare the Android final structural understanding (Step 4.1) against the HarmonyOS current structural understanding (Step 4.2):
+Android pages and Harmony pages may be running on different devices, so be robust to the differences caused by devices (e.g., 组件间的间距、截图上显示的颜色等等)
+
+1. **Structural diff**:
+   - Missing pages/components (in Android but not in HarmonyOS)
+   - Extra pages/components (in HarmonyOS but not in Android)
+   - Wrong nesting / layout structure differences
+   - Incorrect component type mappings
+
+2. **Visual diff**:
+   - Color mismatches (background, foreground, fill)
+   - Size / spacing differences
+   - Position / alignment issues 
+   - Shape mismatches (rounded corners, borders)
+   - Text content or font differences
+   - Icon / image mismatches
+
+3. **Interaction diff** — compare clickable elements, navigation targets, gestures
+
+Return a diff analysis report which lists all diffs

package/skills/hmos-incremental-ui-align/page_align.md

@@ -0,0 +1,62 @@
+# Page Align Insruction
+
+Based on the diff analysis, flexibly combine editing and creation as needed — a single page may require both aligning existing code and adding new components/files:
+
+**For existing files that need alignment:**
+- Read the existing `.ets` file(s) for this page
+- For each discrepancy identified in the diff, make **targeted edits** using the Edit tool:
+  - Fix layout structure mismatches (wrong container type, missing nesting)
+  - Add missing components
+  - Remove extra components that don't exist in the Android UI
+  - Fix styling (colors, sizes, spacing, shapes)
+  - Fix resource references to use correct `$r('app.xxx.yyy')`
+
+**For new files that need to be created** (new pages, new sub-components, new viewmodels/models):
+- Generate new `.ets` files following the conventions discovered in Phase 1:
+  - Use the same import patterns as existing pages
+  - Use the same state management patterns
+  - Reuse existing shared components from `components/`
+  - Reuse or extend existing viewmodels/models
+  - Follow the same naming conventions
+- Write page files to `{harmony_project_dir}/entry/src/main/ets/pages/`
+- Write component files to `{harmony_project_dir}/entry/src/main/ets/components/`
+- Write viewmodel files to `{harmony_project_dir}/entry/src/main/ets/viewmodel/`
+- Write model files to `{harmony_project_dir}/entry/src/main/ets/model/`
+- Register any new page in the router configuration
+
+## For all changes, apply these conversion rules:
+
+**Resource Conversion:**
+- For each resource referenced by the Android UI, find the corresponding mapping in `{harmony_project_dir}/entry/src/main/resources`
+- If a needed resource does not exist, use the **`hmos-resources-convert`** skill to convert it
+
+**Layout Conversion:**
+- Consult `./references/android-to-harmonyOS-ui-layout-mapping-reference.md` for all layout container mappings and layout attribute mappings
+- Apply the layout property mappings (e.g., `layout_weight` → `.layoutWeight()`, `padding` → `.padding()`, visibility handling, etc.)
+
+**Widget Conversion:**
+- Consult `./references/android-to-harmonyOS-ui-atomic-component-mapping-reference.md` for all atomic widget mappings
+- Apply the detailed attribute-level mappings for each component
+
+**Interaction Conversion:**
+- Consult `./references/android-to-harmonyOS-ui-interaction-mapping-reference.md` for all event and gesture mappings
+- Apply touch event mappings, click event mappings, gesture mappings, and animation mappings
+
+**Always consult the reference files first** — they contain project-specific and comprehensive mappings that take priority over built-in knowledge.
+
+**Styling Conversion:**
+- Android `dp` → HarmonyOS `vp`
+- Android `sp` → HarmonyOS `fp`
+- Calculate dimensions from `bounds` in the XML: `width = x2 - x1`, `height = y2 - y1`
+- Convert absolute pixel values to `vp` using the **device density recorded in the page's `meta.json`** (`density_factor`): `vp = px ÷ density_factor`. Do NOT hardcode 3x — read `density_factor` from the Android capture's `meta.json` for Android values and from the HarmonyOS capture's `meta.json` for HarmonyOS values (they may differ). Only fall back to `3.0` if `meta.json` is missing.
+- Use `$r('app.color.xxx')` for colors when available in the resource list
+- Use `$r('app.string.xxx')` for text strings when available in the resource list
+- Use `$r('app.media.xxx')` for images when available in the resource list
+
+**Router Conversion:**
+- Convert router relationships among UIs and components
+- Register new page routes in the router configuration when new pages are created
+- Fix any incorrect router targets in existing pages
+
+**Interactive Elements:**
+- **Prefer real implementation over mocking**: before mocking any click event, navigation jump, or interaction, first check whether the target component or page already exists in the HarmonyOS project. If the target is already implemented, wire up the real event handler (e.g., actual `router.pushUrl()` with the correct page path). **Only mock when the related component or page has not yet been implemented** — in that case, use placeholder implementations to ensure the program compiles (e.g., `console.info('TODO: navigate to SettingsActivity — target page not yet implemented')`)

package/skills/hmos-incremental-ui-align/references/Comparison_Template.md

@@ -0,0 +1,38 @@
+| UI Component | 文本内容 | 尺寸与布局 | 颜色与背景 | 边框与轮廓 | 文本样式 | 变换与效果 | 状态与交互反馈 | Diff |
+|:-------------|:-----|:------|:------|:------|:-----|:------|:--------|:--------|
+
+## Dynamic / Transient UI Comparison
+
+| Effect | Android (Target) | HarmonyOS (Current) | Diff |
+|:-------|:-----------------|:--------------------|:-----|
+| e.g., page enter animation | alpha 0→1, 300ms ease-out (LoginActivity.kt:45) | 缺失 → 目标: animateTo alpha 0→1, 300ms ease-out | Missing |
+| e.g., Toast on save | "保存成功", 2000ms, bottom (EditActivity.kt:88) | promptAction.showToast "已保存", 1500ms | Duration mismatch: 1500ms → 2000ms; Text: "已保存" → "保存成功" |
+| e.g., voice input UI | mic click → waveform + overlay (SearchActivity.kt:78) | 缺失 → 目标: implement voice recognition with waveform | Missing |
+
+Omit this section if `dynamic_ui_inventory.md` has no entries for this page.
+
+## State Machine Comparison (Multi-State Components Only)
+
+Include this section when the component was analyzed in Step 1.5 (has a `state_model.md` entry).
+
+| Dimension | Android | HarmonyOS | Diff |
+|:----------|:--------|:----------|:-----|
+| 状态数量 | {N} ({state1}/{state2}/...) | {M} ({state1}/...) | {e.g., "缺少 cancelling, recognized"} |
+| 状态变量类型 | {enum/sealed class/Int} | {enum/@State/未实现} | {diff or "一致"} |
+
+### Per-Transition Comparison
+
+| Transition | Android Trigger | Android Params | HarmonyOS Trigger | HarmonyOS Params | Diff |
+|:-----------|:---------------|:---------------|:------------------|:-----------------|:-----|
+| S0→S1 | {gesture type} | {threshold/duration} (Source:Line) | {gesture or "缺失"} | {params} | {diff description} |
+| S1→S2 | {gesture type} | {threshold/duration} (Source:Line) | {gesture or "缺失"} | {params} | {HarmonyOS: 缺失 → 目标: {Android value}} |
+
+### Per-State Visual Diff
+
+| State | Property | Android Value | HarmonyOS Value | Diff |
+|:------|:---------|:-------------|:----------------|:-----|
+| S1 | background | #FFFFFF (Source:Line) | #F5F5F5 | HarmonyOS: #F5F5F5 → 目标: #FFFFFF |
+| S1 | animation | waveform, realtime amplitude (Source:Line) | 静态 icon | HarmonyOS: 静态 → 目标: animateTo amplitude |
+| S2 | border | 2vp dashed #FF4444 (Source:Line) | 缺失 | HarmonyOS: 缺失 → 目标: 2vp dashed #FF4444 |
+
+Omit this section if no multi-state components were identified in Step 1.5.