@buaa_smat/hometrans 0.1.0 → 0.1.2

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

@@ -0,0 +1,180 @@
+# Single-Page Android → HarmonyOS UI 转换流程
+
+> 这是 `hmos-ui-align_batch` 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-ui-align_batch` 会在所有页面转换完后统一调用 `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 文件缺失/为空：用内置知识继续，并在报告中注明