@buaa_smat/hometrans 0.1.0 → 0.1.2

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

@@ -0,0 +1,182 @@
+---
+name: hmos-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
+Read `config.json` from this skill's directory. The config provides all fixed paths so the user only describes what needs to be aligned.
+Key config fields:
+- `android.app_name`, `android.package` — Android app info for navigation
+- `android.project_dir` — Android source code root
+- `harmony.app_name`, `harmony.package` — HarmonyOS app info for navigation
+- `harmony.project_dir` — HarmonyOS project root
+- `hmos_sdk_dir` — HarmonyOS SDK path for API reference
+- `glm_api_key` — Zhipu GLM API key for phone-agent
+- `capture_output_dir` — base directory for captured page data
+- `navigation_tool` = `scripts/app_feature_verify.py`                                                                                   
+- `capture_tool` = `scripts/page_capture.py`
+
+## Step 1: Capture All Related Pages on Android & HarmonyOS Devices
+
+Read `scripts/navigation-capure.md` to learn the usage of `navigation_tool` and `capture_tool`.
+
+### 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 `navigation_tool` to navigate to the page.
+2. On success, use `capture_tool` 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 `capture_tool`.
+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开发文档/`**

package/skills/hmos-ui-align/config-example.json

@@ -0,0 +1,11 @@
+{
+  "android.app_name": "Salt Player",
+  "android.package": "com.salt.music",
+  "android.project_dir": "E:\\SaltPlayerAndroid-main\\SuvineMusicX",
+  "harmony.app_name": "Salt Player",
+  "harmony.package": "com.xuncorp.sp2",
+  "harmony.project_dir": "E:\\SPH_branches\\SaltPlayerHarmony",
+  "hmos_sdk_dir": "E:\\DevEco Studio\\sdk\\default",
+  "glm_api_key": "",
+  "capture_output_dir": "E:\\tmp_saltplayer"
+}

package/skills/hmos-ui-align/config.json

@@ -0,0 +1,11 @@
+{
+  "android.app_name": "Salt Player",
+  "android.package": "com.salt.music",
+  "android.project_dir": "E:\\SaltPlayerAndroid-main\\SuvineMusicX",
+  "harmony.app_name": "Salt Player",
+  "harmony.package": "com.xuncorp.sp2",
+  "harmony.project_dir": "E:\\SPH",
+  "hmos_sdk_dir": "E:\\DevEco Studio\\sdk\\default",
+  "glm_api_key": "",
+  "capture_output_dir": "./tmp_saltplayer"
+}

package/skills/hmos-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-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 (assume 3x density: `1vp ≈ 3px`)
+- 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-ui-align/readme.md

@@ -0,0 +1,231 @@
+# hmos-ui-align
+
+HarmonyOS-Android UI 自动对齐流水线。
+
+## 它解决什么问题
+
+以往对齐鸿蒙和安卓 UI 的流程需要：
+1. 人工把设备点到目标页面
+2. 手动跑 parse 脚本截图 + dump view tree
+3. 肉眼对比差异
+4. 手写改鸿蒙源码
+
+每多一个页面/弹窗/tab，上述步骤都要重复一遍，非常费时。
+
+本 skill 做了三件事：
+- 用智谱 GLM 驱动的 phone-agent 自动**寻路**（根据自然语言点到指定页面）
+- 自动**采集** view tree + 截图（安卓走 adb、鸿蒙走 hdc）
+- 自动**对比 + 改码**，并按 MVVM 模式把 mock 数据放到 Model 层
+
+用户只需要一句自然语言 + 点击路径。
+
+> ⚠️ 当前只保证 **UI 对齐**，不保证功能行为对齐。
+
+---
+
+## 前置条件
+
+1. **设备连接**
+   - 安卓设备：已装目标 App，`adb devices` 能看到
+   - 鸿蒙设备：已装目标 App，`hdc list targets` 能看到
+   - 两台设备建议都保持亮屏解锁
+
+2. **Python 依赖**
+   ```bash
+   pip install openpyxl phone-agent
+   ```
+
+3. **智谱 GLM API Key**（phone-agent 调用的模型）
+   到 https://open.bigmodel.cn/ 申请，有免费额度，填到 `config.json` 的 `glm_api_key`。
+
+4. **鸿蒙 SDK 路径**（给改码阶段查 API 用）
+   例如 DevEco Studio 自带的 `E:\DevEco Studio\sdk\default`。
+
+---
+
+## 配置 `config.json`
+
+首次使用前必须改 `Agents/hmos-ui-align/config.json`。字段说明：
+
+| 字段 | 说明 | 示例 |
+|---|---|---|
+| `android.app_name` | 安卓端 App 显示名（桌面上看到的名字，phone-agent 打开 app 时用） | `"Salt Player"` |
+| `android.package` | 安卓包名 | `"com.salt.music"` |
+| `android.project_dir` | 安卓源码根目录 | `"E:\\SaltPlayerAndroid-main\\SuvineMusicX"` |
+| `harmony.app_name` | 鸿蒙端 App 显示名 | `"Salt Player"` |
+| `harmony.package` | 鸿蒙包名 | `"com.xuncorp.sp2"` |
+| `harmony.project_dir` | 鸿蒙工程根目录（会被直接修改） | `"E:\\SPH"` |
+| `hmos_sdk_dir` | 鸿蒙 SDK 路径 | `"E:\\DevEco Studio\\sdk\\default"` |
+| `glm_api_key` | 智谱 GLM API Key | `"xxx.yyy"` |
+| `capture_output_dir` | 采集产物输出目录（截图/view tree/分析报告都在这） | `"./tmp_saltplayer"` |
+
+可以直接参考同目录下的 `config-example.json`。
+
+---
+
+## 使用方式
+
+在 Claude Code 里直接调用 skill：
+
+```
+/hmos-ui-align <自然语言需求，描述要对齐的页面+点击路径>
+```
+
+### 写需求的三个要点
+
+1. **页面路径写清楚**
+   用「→」或「-」标注一级一级的点击步骤，比如 `首页 → 点击"AI智能填报" → 点击"专业"筛选按钮`。路径越具体，phone-agent 寻路成功率越高。
+
+2. **说明是否要覆盖交互态**
+   默认会自动扫描 tab、弹窗、下拉等交互元素并逐个采集。如果只想对齐主页面，请明确说「只对齐主页面，不管弹窗和 tab」。
+
+3. **说明是否用 Mock 数据**
+   默认用 mock 数据。如果想调真实后台，在需求里写「不要 mock 数据，调用真实后台」。
+
+### 例子
+
+**例 1（单个弹窗对齐）**
+```
+/hmos-ui-align 鸿蒙版本app(登录状态下，进入首页-点击"AI智能填报"-点击"专业"筛选按钮)
+得到的弹窗样式和安卓同样路径得到的页面不一致，请修改鸿蒙源码将上述页面与安卓版本完全对齐
+```
+
+**例 2（补齐缺失页面 + 调真实后台）**
+```
+/hmos-ui-align 鸿蒙版本app(点击我的-超级会员组件)显示与安卓不一致，且安卓版本在超级会员
+上点击"会员中心"会跳到超级会员弹窗页，鸿蒙也没有这页。请修改鸿蒙源码将这些页面与安卓版本
+完全对齐，不要mock数据，调用真实后台数据
+```
+
+**例 3（多级路径 + 多个页面）**
+```
+/hmos-ui-align 鸿蒙版本（点击底部高考按钮 -> 带年纪查专业 -> 点击某一具体专业(如临床医学)
+-> 点击就业分析，到达"专业就业健康度"展示页面）以及在"专业就业健康度"页面上点击"完整数
+据指标"到达的就业健康度详情页都和安卓同一路径的不一致。比较这些页面的差别并将他们在视觉
+效果上完全对齐，不要用mock数据，调用后台真实逻辑
+```
+
+---
+
+## 运行过程中会发生什么
+
+skill 会严格按 `SKILL.md` 里的 5 步流水线跑：
+
+### Step 0 · 加载 config
+读 `config.json`，解析出所有路径和 API Key。
+
+### Step 1 · 双端页面采集
+1.1 解析你的需求，拆成一组「基础页」，每个基础页有 `android_nav_path` 和 `hmos_nav_path`
+1.2 对每个基础页，两端分别：phone-agent 寻路 → 成功后 `page_capture.py` 截图 + dump view tree
+1.3 扫描基础页 view tree，发现 tab、弹窗、下拉等交互元素，自动对每个子状态再采集一遍
+1.4 鸿蒙端页面不存在时，寻路会失败，对应目录留空（Step 2 会改从源码读）
+
+产物目录结构：
+```
+{capture_output_dir}/
+  task_{timestamp}/
+    android_page_1_{name}/
+      screenshot.png
+      view_tree.xml
+    hmos_page_1_{name}/
+      screenshot.png
+      view_tree.xml
+    android_page_1_{name}_popup_filter/
+      ...
+```
+
+### Step 2 · UI 差异分析
+主 agent 串行执行，不会下放给子 agent（保证质量）：
+- **2.1** 读安卓 screenshot + view tree，写 `android_page_*/UI_Analysis.md`（组件清单 + 位置 / 颜色 / icon / 尺寸 / 对齐方式等）
+- **2.2** 读鸿蒙 screenshot + view tree，写 `hmos_page_*/UI_Analysis.md`；鸿蒙页不存在时改读源码写 `UI_Analysis_from_code.md`
+- **2.3** 两份 Analysis 对比，按 `references/Comparison_Template.md` 生成 `UI_comparison.md`（markdown diff 表）
+- **2.4** 验证所有 `UI_Analysis*.md` 和 `UI_comparison.md` 都已写全
+
+所有尺寸都会以 `126px (3x → 42vp)` 的格式同时给出原始 px、设备密度、换算后的 vp。
+
+### Step 3 · 改鸿蒙源码
+- 把每个 `UI_comparison.md` 里的 diff 项汇总到 `{task_dir}/fix_checklist.md`（唯一 source of truth）
+- 读 `references/MVVM开发文档/` 学习 MVVM 模式
+- 读 `page_align.md` 学习转换规则
+- 逐条修 diff，每修一个把 `- [ ]` 改成 `- [x]`
+- 每个尺寸 / icon / alignment 都要回溯到安卓源码的 XML 或资源值，不允许"看起来差不多"
+
+### Step 4 · 编译校验
+若可用，调 `hmos-fix-build-errors` skill 确保工程能编过。**不会自动部署**。
+
+---
+
+## 目录结构
+
+```
+Agents/hmos-ui-align/
+├── SKILL.md                    # 流水线定义（主 agent 执行逻辑）
+├── readme.md                   # 本文档
+├── config.json                 # 用户配置
+├── config-example.json         # 配置样例
+├── page_align.md               # Step 3 的转换规则
+├── diff_analysis.md            # 内部说明
+├── scripts/
+│   ├── app_feature_verify.py   # phone-agent 寻路工具
+│   ├── page_capture.py         # view tree + 截图采集工具
+│   └── navigation-capure.md    # 两个脚本的调用约定
+└── references/
+    ├── UI_Analysis_Template.md                # Step 2 分析模板
+    ├── Comparison_Template.md                 # Step 2.3 对比模板
+    ├── MVVM开发文档/                           # 鸿蒙 MVVM 参考
+    ├── 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
+```
+
+---
+
+## 单独运行脚本（调试用）
+
+跳过 skill 手动跑采集：
+
+```powershell
+# 安卓寻路
+$env:PYTHONIOENCODING="utf-8"
+python Agents/hmos-ui-align/scripts/app_feature_verify.py `
+  --device adb `
+  --app "Salt Player" `
+  --package "com.salt.music" `
+  --prompt "进入首页-点击AI智能填报-点击专业筛选按钮" `
+  --api-key "$env:GLM_API_KEY" `
+  --max-steps 15
+
+# 安卓采集
+python Agents/hmos-ui-align/scripts/page_capture.py --device adb -o ./tmp/android_page_1_xxx
+
+# 鸿蒙同理，把 --device adb 换成 --device hdc
+```
+
+> 注意：`--prompt` 模式会自动在前面加「打开{app_name}，」，所以 prompt 里不要再写"打开"。
+
+---
+
+## 常见问题
+
+**Q: phone-agent 寻路失败怎么办？**
+A: skill 默认重试两次。流水线的内部规则：①先看页面是否存在；②路径错了就 force-stop 重试；③路径对但工具报错就让 agent 自己看截图判断是否到了。超过两次仍失败才会跳过该页。
+
+**Q: 鸿蒙端页面根本不存在，能新建吗？**
+A: 可以。Step 2.2 会改从鸿蒙源码读，Step 3 会按安卓的实现规格新建 `.ets` 文件到 `entry/src/main/ets/pages/`，并登记路由。
+
+**Q: 为什么同一次任务会采集多个页面？**
+A: Step 1.3 默认扫描交互元素（tab / 弹窗 / 展开收起等）并递归采集。想关掉请在需求里写「只对齐主页面」。
+
+**Q: 改完会自动部署吗？**
+A: 不会。Step 4 只跑编译验证（如果 `hmos-fix-build-errors` skill 可用）。部署自己来。
+
+**Q: 能不能只做差异分析、不改码？**
+A: 目前流水线是端到端的。如果只想要分析产物，跑完 Step 2 后手动中断即可，所有 `UI_Analysis.md` 和 `UI_comparison.md` 都会落盘在 `{capture_output_dir}/task_{timestamp}/` 下。
+
+---
+
+## 已知限制
+
+- 只对齐 UI，不对齐功能/数据流
+- phone-agent 寻路依赖 GLM 模型对页面文本的识别，小字体或非标准控件可能识别不准
+- 双端设备的分辨率/密度差异会影响像素到 vp 的换算，流水线已显式带上 density，但同一个 Figma 规格下仍可能出现 ±1vp 偏差

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

@@ -0,0 +1,2 @@
+| UI Component | 文本内容 | 尺寸与布局 | 颜色与背景 | 边框与轮廓 | 文本样式 | 变换与效果 | 状态与交互反馈 | Diff |
+|:-------------|:-----|:------|:------|:------|:-----|:------|:--------|:--------|