@buaa_smat/hometrans 0.1.13 → 0.1.14

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

@@ -1,200 +1,219 @@
----
-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.
-- 不要做和用户需求无关的其他修改
-- 
-## Step 0: Load Config
-Resolve the config file in this order — stop at the first hit:
-
-1. **`config-path` argument** if the user provided one (e.g., `config-path: D:\path\to\config.json`).
-2. **`config.json` in this skill's own directory** — `ht init` seeds it from `config-example.json` and fills `glm_api_key` + `hmos_sdk_dir` from `~/.hometrans/config.json`.
-3. Neither exists → **ask the user** for a valid path.
-
-Verify the resolved file with a Read; if it's missing or unreadable, fall through to the next source (or ask the user). Refer to `config-example.json` in this skill's directory for the expected schema.
-
-Config fields:
-
-| Field | Description |
-|---|---|
-| `android.app_name` | Android app name for navigation |
-| `android.package` | Android app package name |
-| `android.project_dir` | Android source code root path |
-| `harmony.app_name` | HarmonyOS app name for navigation |
-| `harmony.package` | HarmonyOS app package name |
-| `harmony.project_dir` | HarmonyOS project root path |
-| `hmos_sdk_dir` | HarmonyOS SDK path (ETS API reference) |
-| `glm_api_key` | Zhipu GLM API key for phone-agent |
-| `capture_output_dir` | Base directory for captured page data |
-
-**Fallbacks for `hmos_sdk_dir` and `glm_api_key`** when empty or missing in the resolved config — stop at the first hit:
-
-1. `~/.hometrans/config.json` (on Windows `%USERPROFILE%\.hometrans\config.json`): `hmos_sdk_dir` = `<env.DEVECO_SDK_HOME>/default`; `glm_api_key` = `env.GLM_API_KEY`.
-2. Environment variables: derive `hmos_sdk_dir` from `DEVECO_SDK_HOME` (append `/default`); `glm_api_key` from `GLM_API_KEY`.
-3. **Ask the user** (suggest running `ht init` to persist them).
-
-Validate that `hmos_sdk_dir` exists on disk before use; if it doesn't, continue down the fallback list.
-
-## Step 1: Capture All Related Pages on Android & HarmonyOS Devices
-
-Read `scripts/navigation-capure.md` to learn the usage of `scripts/app_feature_verify.py` (navigation) and `scripts/page_capture.py` (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 `scripts/app_feature_verify.py` to navigate to the page.
-2. On success, use `scripts/page_capture.py` 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.py`.
-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").
-
-### 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 (e.g. 3x)
- - converted dp/vp value (px ÷ density)
- Format: "126px (3x → 42vp)". Never write bare px or vp without the other.
- **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(居中、靠左、靠右等)等一切视觉要素。
- **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(居中、靠左、靠右等)等一切视觉要素。
-    **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. 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
-
-**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. Extract EVERY diff items from ALL comparison tables and write them into `{task_dir}/fix_checklist.md` in this format:
-```
-# Fix Checklist
-## Page 1: {name}
-- [ ] {diff description 1}
-- [ ] {diff description 2}
-- [ ] {diff description 3}
-## Page 2: {name}
-- [ ] {diff description 1}
-...
-```
-This checklist is your single source of truth for what needs to be fixed.
-
-### 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. read `./references/MVVM开发文档/MVVM模式V1.md` to understand the MVVM mode
-**Note**: If mock data is required, add them in **Model Layer** according to the MVVM mode.
-
-### 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.
-**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
-
-## 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 可参考 `{hmos_sdk_dir}`, 鸿蒙MVVM开发模式可参考`./references/MVVM开发文档/`**
+---
+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.
+- Do not make any other changes unrelated to the user's requirements.
+
+## Step 0: Resolve Inputs
+
+This skill takes three path inputs from the invocation and reads its other settings **directly from the OS environment variables**.
+
+### 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)
+
+Read each variable below **directly from the OS environment** (`echo "$VAR"` on macOS/Linux; `$env:VAR` in PowerShell / `echo %VAR%` in cmd on Windows).
+
+| Variable | Purpose | Valid when |
+|---|---|---|
+| `GLM_API_KEY` | Zhipu GLM key for the phone-agent (Step 1 navigation) | non-empty |
+| `OHOS_SDK_PATH` | HarmonyOS SDK ETS API reference (Step 3) | path exists on disk |
+| `HMS_SDK_PATH` | HMS SDK ETS API reference (Step 3) | path exists on disk |
+
+For `OHOS_SDK_PATH` / `HMS_SDK_PATH`, if unset but `DEVECO_SDK_HOME` is set, derive them as `<DEVECO_SDK_HOME>/default/openharmony/ets` and `<DEVECO_SDK_HOME>/default/hms/ets`.
+
+For each variable that is still missing/empty (or a path that does not exist), **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 `scripts/app_feature_verify.py` 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 phone-agent 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.py` (navigation) and `scripts/page_capture.py` (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 `scripts/app_feature_verify.py` to navigate to the page.
+2. On success, use `scripts/page_capture.py` 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.py`.
+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").
+
+### 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 (e.g. 3x)
+ - converted dp/vp value (px ÷ density)
+ Format: "126px (3x → 42vp)". Never write bare px or vp without the other.
+ **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(居中、靠左、靠右等)等一切视觉要素。
+ **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(居中、靠左、靠右等)等一切视觉要素。
+    **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. 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
+
+**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. Extract EVERY diff items from ALL comparison tables and write them into `{task_dir}/fix_checklist.md` in this format:
+```
+# Fix Checklist
+## Page 1: {name}
+- [ ] {diff description 1}
+- [ ] {diff description 2}
+- [ ] {diff description 3}
+## Page 2: {name}
+- [ ] {diff description 1}
+...
+```
+This checklist is your single source of truth for what needs to be fixed.
+
+### 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. read `./references/MVVM开发文档/MVVM模式V1.md` to understand the MVVM mode
+**Note**: If mock data is required, add them in **Model Layer** according to the MVVM mode.
+
+### 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.
+**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
+
+## 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开发模式可参考`./references/MVVM开发文档/`**

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

@@ -1,53 +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
-
+### 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