@buaa_smat/hometrans 0.1.13 → 0.1.14

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

@@ -1,99 +1,109 @@
----
-name: hmos-batch-ui-align
-description: Batch-convert multiple Android Activity UI snapshots to HarmonyOS ArkUI (ArkTS) pages. Use when the user wants to migrate Android UI pages to HarmonyOS in bulk, port multiple Activity screens to ArkTS, or run an Android-to-HarmonyOS UI conversion across a folder of page snapshots (page_NNNN_ActivityName). Triggers on phrases like "把安卓页面迁移到鸿蒙", "Android UI 转鸿蒙", "批量转 ArkTS", "hmos-batch-ui-align", or any request that supplies an Android project path + Harmony project path + a directory of page snapshots.
----
-
-# hmos-batch-ui-align — Android → HarmonyOS UI Batch Conversion
-
-Batch-convert a set of Android page snapshots (each snapshot is a `page_NNNN_ActivityName/` directory containing `meta.json` + `view.xml` + optional `screenshot.png`) into HarmonyOS ArkTS pages following MVVM architecture.
-
-## Step 1 — Parse User Request
-
-Extract 4 paths from the user's message (natural language, no fixed format):
-
-| Variable | Meaning | Typical Phrases |
-|---|---|---|
-| `android_project_dir` | Android source project root | "Android project path", "安卓项目", "source project" |
-| `harmony_project_dir` | HarmonyOS target project root | "target Harmony project", "鸿蒙项目", "output project" |
-| `ui_info_root` | **Parent directory containing all `page_NNNN_*` subdirectories** | "page screenshots and view tree", "page snapshots", "page folder" |
-| `pages` (optional) | User-explicitly listed page subset | When user lists `1. .../page_0001_X` ... take these |
-
-**`references_dir` and MVVM document directories always use skill-bundled relative paths** — **do not** accept user-provided overrides:
-
-- mappings: `./references/mappings/`
-- mvvm: `./references/mvvm/`
-
-If any required path cannot be extracted from the user's message, **ask the user** — do not guess.
-
-## Step 2 — Resource Conversion
-
-Invoke the `hmos-resources-convert` skill with the following parameters:
-1. **Android project path** = `android_project_dir`
-2. **HarmonyOS project output path** = `harmony_project_dir`
-3. **resource_mapping_path** = generate the resource mapping document under `harmony_project_dir` at `${harmony_project_dir}/resource_mapping.md`
-
-This skill batch-converts Android resources (strings, colors, drawables, images, etc.) to HarmonyOS resource format and generates the mapping document.
-
-## Step 3 — Page Exploration
-
-1. Check if `ui_info_root` already contains `page_*` subdirectories. If yes, inform the user "N page snapshots already exist, skipping exploration" and skip this step.
-2. Otherwise, determine the target App package name (`package`). If the user didn't provide it, extract the `package` attribute from `AndroidManifest.xml` in `android_project_dir`; if still unavailable, ask the user.
-3. Execute with Bash:
-   ```
-   python ./scripts/android_parse_fast.py --package <package_name> --output <ui_info_root_absolute_path>
-   ```
-   This script connects to the Android emulator via ADB, BFS-traverses all reachable pages in the App, and for each page saves `screenshot.png`, `view.xml`, `meta.json` into `page_NNNN_ActivityName/` subdirectories. It also generates `index.json` and `report.html` under `ui_info_root`.
-4. After execution, confirm that `index.json` has been generated under `ui_info_root`. If not, report an error and abort.
-
-## Step 4 — Discover Pages
-
-If the user did not explicitly list pages: use Glob `page_*_*` under `ui_info_root` to find all page subdirectories, sorted by name (`page_0001_*` first).
-
-If the user explicitly listed pages (e.g. "1. .../page_0001_MainActivity ... 19. .../page_0019_MainActivity"): use the user's list.
-
-After discovery, create a task for each page via TaskCreate to track progress.
-
-## Step 5 — Per-Page Conversion
-
-**For each page**, invoke the Agent tool (`subagent_type: general-purpose`) to perform conversion. The prompt must include:
-
-1. The page's `ui_info` absolute path (`{ui_info_root}/page_NNNN_ActivityName`)
-2. `android_project_dir`, `harmony_project_dir`
-3. Absolute paths for mappings and mvvm directories (skill-bundled)
-4. **Copy the full contents of `references/conversion-procedure.md` as the sub-agent's work instructions** (use Read to read it and paste into the prompt)
-
-Why use sub-agents: single-page conversion reads many mapping/MVVM documents + Android source code. Sub-agents isolate context to avoid overwhelming the main session.
-
-After receiving a sub-agent's conversion report, append a brief summary to a cumulative report and mark the corresponding task as completed.
-
-**Execute serially** — do not parallelize (multiple sub-agents modifying the same Harmony project simultaneously will conflict).
-
-## Step 6 — Unified Build Fix
-
-After all page conversions are complete, call the `hmos_fix_build_errors` skill **only once at the end** (passing `harmony_project_dir`) to make the entire project compile. Do not fix per-page (wasteful, and sub-agents are instructed to skip this step).
-
-## Step 7 — Summary Report
-
-Output an overview:
-
-```
-## Batch Conversion Overview
-- Pages processed: N
-- Successful: M   Failed/partial: K
-- Final build status: SUCCESS / PARTIAL
-
-### Per-Page Results
-| Page | Activity | Output File | Status |
-|---|---|---|---|
-| 0001 | MainActivity | pages/MainPage.ets | ✓ |
-| ... | | | |
-
-### Manual Follow-up TODOs
-- (Aggregate mocked items / unimplemented navigation / business logic from sub-reports)
-```
-
-## Key Constraints
-
-- **Never** let a per-page sub-agent call `hmos_fix_build_errors`; do it once in Step 6 only.
-- If the user's `harmony_project_dir` lacks entry/resources subdirectories or the target project doesn't exist, stop and ask — do not generate code.
+---
+name: hmos-batch-ui-align
+description: Batch-convert multiple Android Activity UI snapshots to HarmonyOS ArkUI (ArkTS) pages. Use when the user wants to migrate Android UI pages to HarmonyOS in bulk, port multiple Activity screens to ArkTS, or run an Android-to-HarmonyOS UI conversion across a folder of page snapshots (page_NNNN_ActivityName). Triggers on phrases like "把安卓页面迁移到鸿蒙", "Android UI 转鸿蒙", "批量转 ArkTS", "hmos-batch-ui-align", or any request that supplies an Android project path + Harmony project path + a directory of page snapshots.
+---
+
+# hmos-batch-ui-align — Android → HarmonyOS UI Batch Conversion
+
+Batch-convert a set of Android page snapshots (each snapshot is a `page_NNNN_ActivityName/` directory containing `meta.json` + `view.xml` + optional `screenshot.png`) into HarmonyOS ArkTS pages following MVVM architecture.
+
+## Step 0 — Environment Variables Check (run first)
+
+The final build (Step 6, via `hmos_fix_build_errors`) reads the DevEco location **directly from the OS environment variables** (`echo "$VAR"` on macOS/Linux; `$env:VAR` in PowerShell on Windows):
+
+| Variable | Needed for | Valid when |
+|---|---|---|
+| `DEVECO_HOME` *(or `DEVECO_SDK_HOME`)* | Step 6 unified build | resolves to a valid DevEco install |
+
+If neither `DEVECO_HOME` nor `DEVECO_SDK_HOME` is set, **ask the user** for the DevEco Studio install path before proceeding (suggest running `ht init` to persist it as a machine environment variable).
+
+## Step 1 — Parse User Request
+
+Extract 4 paths from the user's message (natural language, no fixed format):
+
+| Variable | Meaning | Typical Phrases |
+|---|---|---|
+| `android_project_dir` | Android source project root | "Android project path", "安卓项目", "source project" |
+| `harmony_project_dir` | HarmonyOS target project root | "target Harmony project", "鸿蒙项目", "output project" |
+| `ui_info_root` | **Parent directory containing all `page_NNNN_*` subdirectories** | "page screenshots and view tree", "page snapshots", "page folder" |
+| `pages` (optional) | User-explicitly listed page subset | When user lists `1. .../page_0001_X` ... take these |
+
+**`references_dir` and MVVM document directories always use skill-bundled relative paths** — **do not** accept user-provided overrides:
+
+- mappings: `./references/mappings/`
+- mvvm: `./references/mvvm/`
+
+If any required path cannot be extracted from the user's message, **ask the user** — do not guess.
+
+## Step 2 — Resource Conversion
+
+Invoke the `hmos-resources-convert` skill with the following parameters:
+1. **Android project path** = `android_project_dir`
+2. **HarmonyOS project output path** = `harmony_project_dir`
+3. **resource_mapping_path** = generate the resource mapping document under `harmony_project_dir` at `${harmony_project_dir}/resource_mapping.md`
+
+This skill batch-converts Android resources (strings, colors, drawables, images, etc.) to HarmonyOS resource format and generates the mapping document.
+
+## Step 3 — Page Exploration
+
+1. Check if `ui_info_root` already contains `page_*` subdirectories. If yes, inform the user "N page snapshots already exist, skipping exploration" and skip this step.
+2. Otherwise, determine the target App package name (`package`). If the user didn't provide it, extract the `package` attribute from `AndroidManifest.xml` in `android_project_dir`; if still unavailable, ask the user.
+3. Execute with Bash:
+   ```
+   python ./scripts/android_parse_fast.py --package <package_name> --output <ui_info_root_absolute_path>
+   ```
+   This script connects to the Android emulator via ADB, BFS-traverses all reachable pages in the App, and for each page saves `screenshot.png`, `view.xml`, `meta.json` into `page_NNNN_ActivityName/` subdirectories. It also generates `index.json` and `report.html` under `ui_info_root`.
+4. After execution, confirm that `index.json` has been generated under `ui_info_root`. If not, report an error and abort.
+
+## Step 4 — Discover Pages
+
+If the user did not explicitly list pages: use Glob `page_*_*` under `ui_info_root` to find all page subdirectories, sorted by name (`page_0001_*` first).
+
+If the user explicitly listed pages (e.g. "1. .../page_0001_MainActivity ... 19. .../page_0019_MainActivity"): use the user's list.
+
+After discovery, create a task for each page via TaskCreate to track progress.
+
+## Step 5 — Per-Page Conversion
+
+**For each page**, invoke the Agent tool (`subagent_type: general-purpose`) to perform conversion. The prompt must include:
+
+1. The page's `ui_info` absolute path (`{ui_info_root}/page_NNNN_ActivityName`)
+2. `android_project_dir`, `harmony_project_dir`
+3. Absolute paths for mappings and mvvm directories (skill-bundled)
+4. **Copy the full contents of `references/conversion-procedure.md` as the sub-agent's work instructions** (use Read to read it and paste into the prompt)
+
+Why use sub-agents: single-page conversion reads many mapping/MVVM documents + Android source code. Sub-agents isolate context to avoid overwhelming the main session.
+
+After receiving a sub-agent's conversion report, append a brief summary to a cumulative report and mark the corresponding task as completed.
+
+**Execute serially** — do not parallelize (multiple sub-agents modifying the same Harmony project simultaneously will conflict).
+
+## Step 6 — Unified Build Fix
+
+After all page conversions are complete, call the `hmos_fix_build_errors` skill **only once at the end** (passing `harmony_project_dir`) to make the entire project compile. Do not fix per-page (wasteful, and sub-agents are instructed to skip this step).
+
+## Step 7 — Summary Report
+
+Output an overview:
+
+```
+## Batch Conversion Overview
+- Pages processed: N
+- Successful: M   Failed/partial: K
+- Final build status: SUCCESS / PARTIAL
+
+### Per-Page Results
+| Page | Activity | Output File | Status |
+|---|---|---|---|
+| 0001 | MainActivity | pages/MainPage.ets | ✓ |
+| ... | | | |
+
+### Manual Follow-up TODOs
+- (Aggregate mocked items / unimplemented navigation / business logic from sub-reports)
+```
+
+## Key Constraints
+
+- **Never** let a per-page sub-agent call `hmos_fix_build_errors`; do it once in Step 6 only.
+- If the user's `harmony_project_dir` lacks entry/resources subdirectories or the target project doesn't exist, stop and ask — do not generate code.
 - If input paths are Windows paths (with backslashes), pass them as-is to sub-agents; internal Read/Glob support them.

package/skills/hmos-batch-ui-align/references/conversion-procedure.md

@@ -1,180 +1,180 @@
-# Single-Page Android → HarmonyOS UI 转换流程
-
-> 这是 `hmos-batch-ui-align` skill 在每个子 agent 中执行的单页转换流程。基于 `a2h-ui-conversion-new` agent 改写：去掉 Phase 6 build 修复（由父 skill 统一在最后做一次）。
-
-你是一个 **UI Activity 转换器**，专门把单个 Android Activity 的某一页 UI 迁移到 HarmonyOS ArkUI（ArkTS）。
-
-## 输入（由父 skill 传入 prompt）
-
-1. `activity_name` — Android Activity 类名
-2. `android_project_dir` — Android 源项目根
-3. `ui_info` — **单个** `page_NNNN_ActivityName/` 目录绝对路径（含 `meta.json` + `view.xml` + 可能的 `view_scroll_n.xml` / `screenshot.png`）
-4. `harmony_project_dir` — HarmonyOS 项目根
-5. `mappings_dir` — 三份映射表所在目录（skill 自带）
-6. `mvvm_dir` — 13 份 MVVM 装饰器文档所在目录（skill 自带）
-
-## 输出
-
-- ArkTS `.ets` 页面写到 `{harmony_project_dir}/entry/src/main/ets/pages/`
-- dialog/fragment/adapter 等组件写到 `.../ets/components/`
-- ViewModel 写到 `.../ets/viewmodel/`，Model 写到 `.../ets/model/`
-- 文本格式的转换报告（不落盘，作为最终回复返回给父 skill）
-
-## Phase 1 — 定位页面
-
-`ui_info` 已是单个页面目录，无需再筛选。
-
-## Phase 2 — 加载 MVVM 参考
-
-读 `{mvvm_dir}/` 下全部 13 份文档：
-- `MVVM模式（V1）.md`
-- `@Track装饰器：class对象属性级更新.md`
-- `@State装饰器：组件内状态.md`
-- `@Prop装饰器：父子单向同步.md`
-- `@Link装饰器：父子双向同步.md`
-- `@Provide装饰器和@Consume装饰器：与后代组件双向同步.md`
-- `@Observed装饰器和@ObjectLink装饰器：嵌套类对象属性变化.md`
-- `@Watch装饰器：状态变量更改通知.md`
-- `管理应用拥有的状态概述.md`
-- `LocalStorage：页面级UI状态存储.md`
-- `AppStorage：应用全局的UI状态存储.md`
-- `PersistentStorage：持久化存储UI状态.md`
-- `Environment：设备环境查询.md`
-
-## Phase 3 — 加载映射参考
-
-读 `{mappings_dir}/` 下：
-1. `android-to-harmonyOS-ui-layout-mapping-reference.md` — 布局容器与布局属性映射（LinearLayout→Column/Row、FrameLayout→Stack、RecyclerView→List、layout_weight→.layoutWeight()、padding→.padding() 等）
-2. `android-to-harmonyOS-ui-atomic-component-mapping-reference.md` — 原子组件映射（TextView→Text、EditText→TextInput/TextArea、Button→Button），含属性级映射（文本/样式/对齐/省略 等）
-3. `android-to-harmonyOS-ui-interaction-mapping-reference.md` — 交互映射（onClick→.onClick()、onLongClick→LongPressGesture、touch、gesture、animation）
-
-> 这三份映射是**首要依据**，优先于内置知识。
-
-## Phase 4 — 单页转换
-
-### 4.1 解析 meta.json
-
-提取：`page_id`、`label`、`clickable_elements`（含 class/resource-id/text/content-desc/bounds）、`click_path`、`came_from`/`trigger_element`。
-
-### 4.2 解析视图树
-
-读 `view.xml`，建立结构化理解：根布局、toolbar、content、bottom nav、各 widget 的 class/resource-id/text/content-desc/bounds/clickable/scrollable/checkable/checked/enabled、由 bounds 推断父子+兄弟关系、识别复用模式（list item / card）。
-
-若存在 `view_scroll_n.xml`（n=1,2,...）：表示 Android UI 太长需滚动捕获，按编号 1→n 依次读取，**以 `view.xml` 为根**合并所有 `view_scroll_n.xml` 得到合并结构。
-
-合并结构仍可能不完整（某些组件未出现在任何快照中）。**必须**在 `android_project_dir` 中查找并阅读与 `meta.json`、合并结构最相关的静态 XML 布局文件 + Kotlin/Java 代码，以静态源码为主结构，把合并结构作为动态信息补充，并把用户自定义/三方组件展开成原子 Android 布局/组件，得到**最终结构理解**。输出该理解。
-
-可选：调用 `android-ui-graph-query` skill 补充 UI 图谱信息（widget 详细属性、样式、theme）。
-
-### 4.3 生成 ArkUI 代码
-
-**与现有 Harmony 文件冲突处理**：转换前若目标 .ets 已存在，三种情形——
-1. 动态刷新组件（toolbar 不同状态显示不同图标）
-2. 增量实现
-3. 现有代码或最终结构理解有错
-
-无论哪种，必须通过对照静态 XML/Kotlin/Java + view.xml + view_scroll_n.xml 验证。**不要删除已有 Harmony 代码**。
-
-dialog/fragment/adapter 等必须从主页面拆出去到 `{harmony_project_dir}/entry/src/main/ets/components/`。
-
-**架构**：
-- MVVM：page/component 用 viewmodel，viewmodel 用 model
-- 转换前先扫 `{harmony_project_dir}` 找可复用组件/VM/Model；toolbar 等通用组件抽到 components 复用；相关 model/viewmodel 合并复用，不要每页新建一份
-
-**资源**：每个 Android UI 引用的资源（图片/字符串/颜色/尺寸等）必须使用 `{harmony_project_dir}\entry\src\main\resources` 中**同名**的转换后资源。
-
-**布局**：查 layout mapping ref。
-
-**组件**：查 atomic component mapping ref。
-
-**交互**：查 interaction mapping ref。
-
-**始终先查映射文件**（项目专属、覆盖更全），覆盖内置知识。
-
-**单位与样式**：
-- `dp` → `vp`，`sp` → `fp`
-- 由 bounds 算尺寸：`width = x2 - x1`，`height = y2 - y1`
-- 假定 3x 密度：`1vp ≈ 3px`
-- 资源用 `$r('app.color.xxx')` / `$r('app.string.xxx')` / `$r('app.media.xxx')`
-
-**路由**：实现 UI 与组件之间的路由关系。
-
-**交互元素**：
-- 给每个 `clickable_element` 挂 `.onClick()`
-- `click_path` 显示跳到另一 Activity → `router.pushUrl()`
-- 状态切换（dialog/menu/toggle）→ 用 `@State` 管理
-- **优先真实实现**：mock 之前先在 `{harmony_project_dir}` 搜目标页面/组件 .ets 是否存在；存在则接真实 `router.pushUrl()`；**仅当目标尚未实现**才 mock + `console.info('TODO: ...')`
-
-### 4.4 截图复核（如有）
-
-`screenshot.png` 仅覆盖屏内 UI，**不要**用它去校验屏外组件。
-
-存在则读取：视觉校验布局理解，对照视图层级，调整 `view.xml` 未捕获的间距/对齐/样式。`screenshot_scroll_n.png` 同理对照 `view_scroll_n.xml`。
-
-## Phase 5 — 一致性校验（关键，必跑 3 轮）
-
-列出转换后 HarmonyOS UI 中所有 layout/component/resource reference，对每一个**逐项**走完以下检查（不可省略）：
-
-- **@Track 缺失**：`@Observed` 类中所有在 UI 中使用的属性是否都加了 `@Track`？没有则补
-- **颜色冲突**：fill/background/foreground 颜色是否冲突导致不可见（白底白图）？有则修
-- **颜色设置**：背景/填充/前景色是否与 Android UI 一致（漏设、错设）？有则修
-- **资源引用错用**：资源引用是否与 Android UI 一致；不存在的资源要重新查找正确名
-- **形状错用**：圆角/直角等形状是否与 Android UI 一致
-- **尺寸问题**：图标/组件大小是否一致
-- **位置问题**：toolbar 是否在顶部、图标位置是否过左/过右等
-- **路由关系**：UI 与组件间路由是否正确实现
-
-**必须跑 3 轮验证迭代，并输出验证报告**。
-
-## Phase 6 — Build 修复
-
-**跳过**。父 skill `hmos-batch-ui-align` 会在所有页面转换完后统一调用 `hmos_fix_build_errors` 修一次。
-
-## 返回转换报告
-
-```
-## Conversion Report: {ActivityName} (page_NNNN)
-
-### Page Processed
-| Page ID | Label | Type | Output File |
-|---------|-------|------|-------------|
-| page_NNNN_XXX | ...  | Base Page | XxxPage.ets |
-
-### Component Mapping Decisions
-- ...
-
-### State Variables
-- ...
-
-### Resources Converted
-- ...
-
-### Implemented Interactions
-- ...（接通真实跳转的事件）
-
-### TODOs & Mocked Items
-- ...（mock 的事件、未实现的目标页）
-
-### Navigation
-- ...（从 click_path 抽取的导航目标）
-
-### Validation Report (3 iterations)
-- 第 1 轮：发现/修复 N 项
-- 第 2 轮：发现/修复 M 项
-- 第 3 轮：稳定/剩余 K 项
-```
-
-## 全局准则
-
-- **一个 Activity = 一个主页面文件**（仅最小编号那张快照）
-- **严格保真**：layout 结构、组件层级、资源引用必须与 Android 源一一对应；不增删/重排 UI 元素
-- **资源精确匹配**：所有 color/string/dimension/image 必须有对应 HarmonyOS 资源；不要硬编码
-- **可编译性是必须的**：已实现目标接真实事件；未实现才 mock 至可编译
-- 仅用声明式 ArkUI；绝不写命令式 DOM 操作
-- 保留原 Android 视觉与 UX 保真度
-- 资源一律 `$r('app.type.name')`
-- 留 `// TODO:` 注释给：业务逻辑、ViewModel 数据绑定、未转换的目标 Activity
-- 响应式布局：优先百分比宽度 + Flex，少用固定尺寸
-- 无障碍：`content-desc` → `.accessibilityText()`，有意义的 `text` → 正确的 label
-- 嵌套 > 5 层时把相关 UI 拆为 `@Component` 子组件
-- 任一 mapping 文件缺失/为空：用内置知识继续，并在报告中注明
+# Single-Page Android → HarmonyOS UI 转换流程
+
+> 这是 `hmos-batch-ui-align` skill 在每个子 agent 中执行的单页转换流程。基于 `a2h-ui-conversion-new` agent 改写：去掉 Phase 6 build 修复（由父 skill 统一在最后做一次）。
+
+你是一个 **UI Activity 转换器**，专门把单个 Android Activity 的某一页 UI 迁移到 HarmonyOS ArkUI（ArkTS）。
+
+## 输入（由父 skill 传入 prompt）
+
+1. `activity_name` — Android Activity 类名
+2. `android_project_dir` — Android 源项目根
+3. `ui_info` — **单个** `page_NNNN_ActivityName/` 目录绝对路径（含 `meta.json` + `view.xml` + 可能的 `view_scroll_n.xml` / `screenshot.png`）
+4. `harmony_project_dir` — HarmonyOS 项目根
+5. `mappings_dir` — 三份映射表所在目录（skill 自带）
+6. `mvvm_dir` — 13 份 MVVM 装饰器文档所在目录（skill 自带）
+
+## 输出
+
+- ArkTS `.ets` 页面写到 `{harmony_project_dir}/entry/src/main/ets/pages/`
+- dialog/fragment/adapter 等组件写到 `.../ets/components/`
+- ViewModel 写到 `.../ets/viewmodel/`，Model 写到 `.../ets/model/`
+- 文本格式的转换报告（不落盘，作为最终回复返回给父 skill）
+
+## Phase 1 — 定位页面
+
+`ui_info` 已是单个页面目录，无需再筛选。
+
+## Phase 2 — 加载 MVVM 参考
+
+读 `{mvvm_dir}/` 下全部 13 份文档：
+- `MVVM模式（V1）.md`
+- `@Track装饰器：class对象属性级更新.md`
+- `@State装饰器：组件内状态.md`
+- `@Prop装饰器：父子单向同步.md`
+- `@Link装饰器：父子双向同步.md`
+- `@Provide装饰器和@Consume装饰器：与后代组件双向同步.md`
+- `@Observed装饰器和@ObjectLink装饰器：嵌套类对象属性变化.md`
+- `@Watch装饰器：状态变量更改通知.md`
+- `管理应用拥有的状态概述.md`
+- `LocalStorage：页面级UI状态存储.md`
+- `AppStorage：应用全局的UI状态存储.md`
+- `PersistentStorage：持久化存储UI状态.md`
+- `Environment：设备环境查询.md`
+
+## Phase 3 — 加载映射参考
+
+读 `{mappings_dir}/` 下：
+1. `android-to-harmonyOS-ui-layout-mapping-reference.md` — 布局容器与布局属性映射（LinearLayout→Column/Row、FrameLayout→Stack、RecyclerView→List、layout_weight→.layoutWeight()、padding→.padding() 等）
+2. `android-to-harmonyOS-ui-atomic-component-mapping-reference.md` — 原子组件映射（TextView→Text、EditText→TextInput/TextArea、Button→Button），含属性级映射（文本/样式/对齐/省略 等）
+3. `android-to-harmonyOS-ui-interaction-mapping-reference.md` — 交互映射（onClick→.onClick()、onLongClick→LongPressGesture、touch、gesture、animation）
+
+> 这三份映射是**首要依据**，优先于内置知识。
+
+## Phase 4 — 单页转换
+
+### 4.1 解析 meta.json
+
+提取：`page_id`、`label`、`clickable_elements`（含 class/resource-id/text/content-desc/bounds）、`click_path`、`came_from`/`trigger_element`。
+
+### 4.2 解析视图树
+
+读 `view.xml`，建立结构化理解：根布局、toolbar、content、bottom nav、各 widget 的 class/resource-id/text/content-desc/bounds/clickable/scrollable/checkable/checked/enabled、由 bounds 推断父子+兄弟关系、识别复用模式（list item / card）。
+
+若存在 `view_scroll_n.xml`（n=1,2,...）：表示 Android UI 太长需滚动捕获，按编号 1→n 依次读取，**以 `view.xml` 为根**合并所有 `view_scroll_n.xml` 得到合并结构。
+
+合并结构仍可能不完整（某些组件未出现在任何快照中）。**必须**在 `android_project_dir` 中查找并阅读与 `meta.json`、合并结构最相关的静态 XML 布局文件 + Kotlin/Java 代码，以静态源码为主结构，把合并结构作为动态信息补充，并把用户自定义/三方组件展开成原子 Android 布局/组件，得到**最终结构理解**。输出该理解。
+
+可选：调用 `android-ui-graph-query` skill 补充 UI 图谱信息（widget 详细属性、样式、theme）。
+
+### 4.3 生成 ArkUI 代码
+
+**与现有 Harmony 文件冲突处理**：转换前若目标 .ets 已存在，三种情形——
+1. 动态刷新组件（toolbar 不同状态显示不同图标）
+2. 增量实现
+3. 现有代码或最终结构理解有错
+
+无论哪种，必须通过对照静态 XML/Kotlin/Java + view.xml + view_scroll_n.xml 验证。**不要删除已有 Harmony 代码**。
+
+dialog/fragment/adapter 等必须从主页面拆出去到 `{harmony_project_dir}/entry/src/main/ets/components/`。
+
+**架构**：
+- MVVM：page/component 用 viewmodel，viewmodel 用 model
+- 转换前先扫 `{harmony_project_dir}` 找可复用组件/VM/Model；toolbar 等通用组件抽到 components 复用；相关 model/viewmodel 合并复用，不要每页新建一份
+
+**资源**：每个 Android UI 引用的资源（图片/字符串/颜色/尺寸等）必须使用 `{harmony_project_dir}\entry\src\main\resources` 中**同名**的转换后资源。
+
+**布局**：查 layout mapping ref。
+
+**组件**：查 atomic component mapping ref。
+
+**交互**：查 interaction mapping ref。
+
+**始终先查映射文件**（项目专属、覆盖更全），覆盖内置知识。
+
+**单位与样式**：
+- `dp` → `vp`，`sp` → `fp`
+- 由 bounds 算尺寸：`width = x2 - x1`，`height = y2 - y1`
+- 假定 3x 密度：`1vp ≈ 3px`
+- 资源用 `$r('app.color.xxx')` / `$r('app.string.xxx')` / `$r('app.media.xxx')`
+
+**路由**：实现 UI 与组件之间的路由关系。
+
+**交互元素**：
+- 给每个 `clickable_element` 挂 `.onClick()`
+- `click_path` 显示跳到另一 Activity → `router.pushUrl()`
+- 状态切换（dialog/menu/toggle）→ 用 `@State` 管理
+- **优先真实实现**：mock 之前先在 `{harmony_project_dir}` 搜目标页面/组件 .ets 是否存在；存在则接真实 `router.pushUrl()`；**仅当目标尚未实现**才 mock + `console.info('TODO: ...')`
+
+### 4.4 截图复核（如有）
+
+`screenshot.png` 仅覆盖屏内 UI，**不要**用它去校验屏外组件。
+
+存在则读取：视觉校验布局理解，对照视图层级，调整 `view.xml` 未捕获的间距/对齐/样式。`screenshot_scroll_n.png` 同理对照 `view_scroll_n.xml`。
+
+## Phase 5 — 一致性校验（关键，必跑 3 轮）
+
+列出转换后 HarmonyOS UI 中所有 layout/component/resource reference，对每一个**逐项**走完以下检查（不可省略）：
+
+- **@Track 缺失**：`@Observed` 类中所有在 UI 中使用的属性是否都加了 `@Track`？没有则补
+- **颜色冲突**：fill/background/foreground 颜色是否冲突导致不可见（白底白图）？有则修
+- **颜色设置**：背景/填充/前景色是否与 Android UI 一致（漏设、错设）？有则修
+- **资源引用错用**：资源引用是否与 Android UI 一致；不存在的资源要重新查找正确名
+- **形状错用**：圆角/直角等形状是否与 Android UI 一致
+- **尺寸问题**：图标/组件大小是否一致
+- **位置问题**：toolbar 是否在顶部、图标位置是否过左/过右等
+- **路由关系**：UI 与组件间路由是否正确实现
+
+**必须跑 3 轮验证迭代，并输出验证报告**。
+
+## Phase 6 — Build 修复
+
+**跳过**。父 skill `hmos-batch-ui-align` 会在所有页面转换完后统一调用 `hmos_fix_build_errors` 修一次。
+
+## 返回转换报告
+
+```
+## Conversion Report: {ActivityName} (page_NNNN)
+
+### Page Processed
+| Page ID | Label | Type | Output File |
+|---------|-------|------|-------------|
+| page_NNNN_XXX | ...  | Base Page | XxxPage.ets |
+
+### Component Mapping Decisions
+- ...
+
+### State Variables
+- ...
+
+### Resources Converted
+- ...
+
+### Implemented Interactions
+- ...（接通真实跳转的事件）
+
+### TODOs & Mocked Items
+- ...（mock 的事件、未实现的目标页）
+
+### Navigation
+- ...（从 click_path 抽取的导航目标）
+
+### Validation Report (3 iterations)
+- 第 1 轮：发现/修复 N 项
+- 第 2 轮：发现/修复 M 项
+- 第 3 轮：稳定/剩余 K 项
+```
+
+## 全局准则
+
+- **一个 Activity = 一个主页面文件**（仅最小编号那张快照）
+- **严格保真**：layout 结构、组件层级、资源引用必须与 Android 源一一对应；不增删/重排 UI 元素
+- **资源精确匹配**：所有 color/string/dimension/image 必须有对应 HarmonyOS 资源；不要硬编码
+- **可编译性是必须的**：已实现目标接真实事件；未实现才 mock 至可编译
+- 仅用声明式 ArkUI；绝不写命令式 DOM 操作
+- 保留原 Android 视觉与 UX 保真度
+- 资源一律 `$r('app.type.name')`
+- 留 `// TODO:` 注释给：业务逻辑、ViewModel 数据绑定、未转换的目标 Activity
+- 响应式布局：优先百分比宽度 + Flex，少用固定尺寸
+- 无障碍：`content-desc` → `.accessibilityText()`，有意义的 `text` → 正确的 label
+- 嵌套 > 5 层时把相关 UI 拆为 `@Component` 子组件
+- 任一 mapping 文件缺失/为空：用内置知识继续，并在报告中注明