@buaa_smat/hometrans 0.1.13 → 0.1.14

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

@@ -1,62 +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')`)
+# 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-incremental-ui-align/readme.md

@@ -1,230 +1,237 @@
-# 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`
-
-首次使用前，自行准备一份 `config.json`（放任何位置都可以），调用 skill 时把它的**绝对路径**作为参数传给 skill。可复制同目录下的 `config-example.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，**必须把准备好的 `config.json` 的绝对路径附在需求里**：
-
-```
-/hmos-ui-align config: <绝对路径/config.json>  <自然语言需求，描述要对齐的页面+点击路径>
-```
-
-### 写需求的三个要点
-
-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-example.json         # 配置样例（实际使用的 config.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 偏差
+# 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/ 申请，有免费额度。设为 OS 环境变量 `GLM_API_KEY`（`ht init` 可帮你写入机器环境变量）。
+
+4. **鸿蒙 SDK 路径**（给改码阶段查 API 用）
+   取自 OS 环境变量 `OHOS_SDK_PATH` / `HMS_SDK_PATH`（为空时由 `DEVECO_SDK_HOME` 派生），由 `ht init` 写入机器环境变量；例如 DevEco Studio 自带的 `E:\DevEco Studio\sdk\default\openharmony\ets`。
+
+---
+
+## 入参与配置
+
+本 skill 需要两类信息：
+
+**① 调用时传入的入参**（每次按需提供）：
+
+| 入参 | 必填 | 说明                                                                 |
+|---|---|--------------------------------------------------------------------|
+| `android_project_dir` | 是 | 安卓源码根目录                                                            |
+| `harmony_project_dir` | 是 | 鸿蒙工程根目录（会被直接修改）                                                    |
+| `capture_output_dir` | 否 | 采集产物输出目录（截图/view tree/分析报告）。默认 `<harmony_project_dir>/.hometrans/capture_output` |
+
+**② 从 OS 环境变量直接读取的全局配置**（由 `ht init` 写入机器环境变量，无需每次传）：
+
+- GLM key ← 环境变量 `GLM_API_KEY`
+- 鸿蒙 SDK ETS API 目录 ← 环境变量 `OHOS_SDK_PATH` / `HMS_SDK_PATH`（为空时由 `DEVECO_SDK_HOME` 派生为 `<DEVECO_SDK_HOME>/default/openharmony/ets`、`.../hms/ets`）
+
+> **Step 0.0** 会在执行前检查这些环境变量是否存在；缺失时会要求用户输入。
+
+> 安卓/鸿蒙两端的 **App 显示名**（`android.app_name` / `harmony.app_name`）和 **包名**（`android.package` / `harmony.package`）也无需提供——skill 的 **Step 0.1** 会按 `android_project_dir` / `harmony_project_dir` 自动解析：
+> - 安卓包名取自 app 模块 `build.gradle(.kts)` 的 `applicationId`（兜底 `AndroidManifest.xml` 的 `package`）；App 名取自启动 Activity / `<application>` 的 `android:label`（`@string/xxx` 会去 `res/values*/strings.xml` 解析，优先中文）。
+> - 鸿蒙包名取自 `AppScope/app.json5` 的 `bundleName`；App 名取自 `app.json5` 的 `label`（`$string:xxx` 会去 `AppScope/resources/**/element/string.json` 解析，优先中文）。
+>
+> 若某项无法从工程目录解析，skill 会回到询问用户。
+
+---
+
+## 使用方式
+
+在 Claude Code 里直接调用 skill，**把两个工程目录附在需求里**（可作为命名参数，也可在自然语言里说明）：
+
+```
+/hmos-ui-align android_project_dir: <安卓工程绝对路径> harmony_project_dir: <鸿蒙工程绝对路径>
+<自然语言需求，描述要对齐的页面+点击路径>
+```
+
+### 写需求的三个要点
+
+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 · 解析入参
+读取调用入参 `android_project_dir` / `harmony_project_dir` / `capture_output_dir`，并从 OS 环境变量直接读取 `GLM_API_KEY` 与 `OHOS_SDK_PATH` / `HMS_SDK_PATH`（**Step 0.0** 会先做存在性检查，缺失则要求用户输入）。随后 **Step 0.1** 按两个工程目录自动解析两端的 App 显示名与包名（无需手动配置）。
+
+### 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                   # 本文档
+├── 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-incremental-ui-align/references/Comparison_Template.md

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