npm - android2harmony - Versions diffs - 0.1.4 → 0.1.6 - Mend

android2harmony 0.1.4 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (116) hide show

package/README.md CHANGED Viewed

@@ -1,407 +1 @@
-# 安卓应用迁移鸿蒙指导
-**a2h工具用于辅助鸿蒙开发者完成原生安卓应用迁移到鸿蒙应用，为应用迁移的各个环节提供能力支持。**
-**本文档为使用a2h工具进行应用迁移的流程指导。**
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D%2022.18-339933.svg?logo=node.js&logoColor=white)](https://nodejs.org/en/download)
-[![Claude Code](https://img.shields.io/badge/Claude_Code-supported-blueviolet.svg)](#选择本地editor)
-[![Cursor](https://img.shields.io/badge/Cursor-supported-blueviolet.svg)](#选择本地editor)
-[![OpenCode](https://img.shields.io/badge/OpenCode-supported-blueviolet.svg)](#选择本地editor)
-[![DevEco Code](https://img.shields.io/badge/DevEco_Code-supported-blueviolet.svg)](#选择本地editor)
-[![Codex](https://img.shields.io/badge/Codex-supported-blueviolet.svg)](#选择本地editor)
-[![CodeBuddy](https://img.shields.io/badge/CodeBuddy-supported-blueviolet.svg)](#选择本地editor)
----
-## 安装DevEco Studio以及Android Studio
-1. **安装DevEco Studio** — 下载地址:<https://developer.huawei.com/consumer/cn/download/>。安装完成后,配置以下 **PATH环境变量**:
-   | 工具 | PATH中加入的目录 |
-   |------|------------------|
-   | java | `<DevEco安装目录>\jbr\bin` |
-   | hdc | `<DevEco安装目录>\sdk\default\openharmony\toolchains` |
-   验证方式:执行 `java -version`、`hdc -v` 均返回正常
-2. **安装Android Studio** — 下载地址:<https://developer.android.com/studio>,并在 **SDK Manager** 中安装SDK。
-   验证方式:执行 `adb version` 返回正常
-   被依赖:
-   - 步骤1.1UI迁移(可选,仅自动抓取页面快照时需要)
-   - 步骤1.2UI对齐(必需)
-   注：也可用真机替代模拟器用于UI迁移和对齐。但当前工具不支持部分系统(Android API 16及更早版本、华为emui、部分车机.IOT设备)
-## 安装Node.js
-安装 **Node.js(版本需 >= 22.18)** — 下载地址:<https://nodejs.org/en/download>。
-验证方式:执行 `node -v`、`npm -v`、`npx -v` 均返回正常,且 `node -v` 显示版本不低于 22.18
-## 安装a2h
-执行 `npm install -g android2harmony`。
-验证方式:执行 `a2h --version` 返回正常
-## 环境初始化
-执行 `a2h init`。
-> 如果在PowerShell下运行,命令需要加上 `.cmd` 后缀,如 `a2h.cmd --version`、`a2h.cmd init`。
-### 选择本地editor:
-![choose_editor.png](https://raw.gitcode.com/yang237/a2h/raw/main/resource/choose_editor.png)
-### 参数配置:
-#### 配置鸿蒙SDK:
-![set_sdk.png](https://raw.gitcode.com/yang237/a2h/raw/main/resource/set_sdk.png)
-#### 配置多模态模型(不执行UI对齐以及集成测试可以跳过该配置):
-![set_multimodel.png](https://raw.gitcode.com/yang237/a2h/raw/main/resource/set_multimodel.png)
-  | 参数             | 含义             |
-  |-----------------|---------|
-  | `model_api_key` | 用于模型API请求认证的令牌   |
-  | `model_name`      | 多模态(视觉)模型的名字   |
-  | `model_base_url`       | 模型API服务的基础地址 |
-##### 配置参考
-前往[阿里云百炼平台](https://bailian.console.aliyun.com/)开通服务并申请 API Key,选用 Qwen 系列多模态(视觉)模型(如 `qwen3.5-plus`)。
-| 参数 | 取值                                                  |
-|---|-----------------------------------------------------|
-| `model_api_key` | 百炼控制台申请的 API Key(形如 `sk-xxxxxxxx`)                  |
-| `model_name` | `qwen3.5-plus`                                      |
-| `model_base_url` | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
-#### 将配置信息添加到环境变量:
-![set_environment.png](https://raw.gitcode.com/yang237/a2h/raw/main/resource/set_environment.png)
-### 准备项目
-准备 **Android源项目** 与 **HarmonyOS目标项目目录**。
----
-## 迁移流程
-![migration_process.svg](https://raw.gitcode.com/yang237/a2h/raw/main/resource/migration_process.svg)
----
-## 步骤1:UI迁移
-### 1.1 UI迁移
-> 📦 依赖:Android Studio + 安卓真机/模拟器(可选,仅自动抓取页面快照时需要)。
-打开本地editor(claude code,open code等),在会话中通过 `斜杠/ `或者 `自然语言 `的方式调用skill--hmos-batch-ui-align，并且传递相关参数)
-斜杠调用方式举例
-```
-/hmos-batch-ui-align android_project_dir=<安卓项目路径> harmony_project_dir=<鸿蒙项目路径> ui_info_root=<页面快照目录> apk_path=<安卓apk路径>
-```
-自然语言调用方式举例
-```
-帮我使用skill：hmos-batch-ui-align完成安卓应用页面到鸿蒙应用的迁移，传递的参数是 android_project_dir=<安卓项目路径> harmony_project_dir=<鸿蒙项目路径> ui_info_root=<页面快照目录> apk_path=<安卓apk路径>
-```
-**输入参数**
-| 参数 | 类型 | 说明                                                                                                          |
-|------|------|-------------------------------------------------------------------------------------------------------------|
-| `android_project_dir` | **必选** | Android项目根目录路径                                                                                             |
-| `harmony_project_dir` | **必选** | HarmonyOS项目输出路径                                                                                            |
-| `ui_info_root` | 可选 | 包含 `page_NNNN_ActivityName` 格式子目录的父目录(每子目录含 `meta.json` + `view.xml` + 可选 `screenshot.png`);不提供时自动通过adb抓取 |
-| `pages` | 可选 | 显式列出的页面子集(不提供则处理所有页面)                                                                                       |
-| `apk_path` | 可选 | Android APK文件路径;透传给内部的 `hmos-resources-convert`,提供后跳过Gradle构建,直接用apktool解包该APK提取资源 |
-**输出产物**
-| 产物 | 位置 | 说明 |
-|------|------|------|
-| ArkTS页面文件 | HarmonyOS项目下 | 由Android Activity转换生成的ArkTS页面 |
-| 资源文件 | HarmonyOS项目下 | 页面所需资源(含UI迁移内部触发的资源转换产物) |
-| 批量转换报告 | HarmonyOS项目下 | 各页面转换结果、缺陷与统计 |
-### 1.2 UI对齐(按需)
-> 📦 依赖:DevEco Studio、Android Studio(必需);安卓真机/模拟器 + 鸿蒙真机/模拟器(必需)。
-打开本地editor(claude code,open code等),在会话中通过 `斜杠/ `或者 `自然语言 `的方式调用skill--hmos-incremental-ui-align，并且传递相关参数)
-斜杠调用方式举例
-```
-/hmos-incremental-ui-align android_project_dir=<安卓工程路径> harmony_project_dir=<鸿蒙工程路径>
-```
-自然语言调用方式举例
-```
-帮我使用skill：hmos-incremental-ui-align完成安卓和鸿蒙应用的页面对齐，传递的参数是 android_project_dir=<安卓工程路径> harmony_project_dir=<鸿蒙工程路径>
-```
-**输入参数**
-| 参数 | 类型 | 说明 |
-|------|------|------|
-| `android_project_dir` | 必填 | 安卓源码根目录;用于自动解析安卓app名/包名 |
-| `harmony_project_dir` | 必填 | 鸿蒙工程根目录(会被直接修改);用于自动解析鸿蒙app名/包名 |
-| `capture_output_dir` | 可选 | 采集产物输出目录,默认 `<harmony_project_dir>/.hometrans/capture_output` |
-**输出产物**
-| 产物 | 位置 | 说明 |
-|------|------|------|
-| 修改后的ArkTS页面文件 | HarmonyOS项目下 | 对齐目标页面后的代码改动 |
-| 双端页面截图与视图树 | `capture_output_dir` | Android/HarmonyOS两侧 `screenshot.png` + 视图树文件 |
-| 对齐差异/修复报告 | `capture_output_dir` | 差异分析与修复说明 |
----
-## 步骤2:生成需求规格
-> 📦 依赖:homegraph(必需)。
-> 👤 前置:用户编写 `REQ.txt` 文件 — 以自然语言描述原始需求，如有多个需求则在文件中使用空行进行分隔，需求中建议包含页面跳转路径的说明以及业务逻辑的描述。
-`REQ.txt` 示例:
-```text
-设置-歌词-歌词界面-卡拉OK歌词动画兼容策略（播放页歌词设置同步实现）
-逐字歌词效果，默认是当前行
-    1,当前行：只为前歌曲的歌词中有单字时间戳的歌词行显示逐字特效
-    2,扩展全部：当前歌曲的歌词中只要有一行歌词带单字时间戳，所有歌词行都显示逐字特效
-    3,总是：当前歌曲所有歌词行都显示逐字特效
-设置-用户界面-圆形播放封面（圆形支持旋转）
-开关，默认关闭，打开后，在播放页以圆形展示封面，并且自动旋转
-设置-用户界面-允许不规则封面（支持长方形封面，参考无归）
-开关，默认打开，播放页封面以大小一致的正方形展示，打开后，在播放页封面以原始样式展示
-设置-歌词-悬浮窗状态栏歌词
-开关 ，默认关闭，打开前需要申请悬浮窗权限，打开后在悬浮窗滚动展示歌词
-    1,左右位置：默认0%
-    2,上下位置：默认0px
-    3,宽度：默认150dp
-    4,大小：默认14.0dp
-    5,选择颜色：默认蓝色
-    6,歌词文本居左对齐：开关 默认关闭，歌词在设置的宽度内中对齐
-    7,状态栏歌词不显示翻译：开关 默认关闭
-    8,在播放界面隐藏：开关 默认关闭 打开后如果切换到播放页，则不在悬浮窗区域显示歌词
-```
-打开本地editor(claude code,open code等),在会话中通过 `斜杠/ `或者 `自然语言 `的方式调用skill--hmos-spec-generate，并且传递相关参数)
-斜杠调用方式举例
-```
-/hmos-spec-generate requirement_description_file=<需求描述文件路径> android_project_dir=<安卓项目路径> spec_output_dir=<规格输出目录>
-```
-自然语言调用方式举例
-```
-帮我使用skill：hmos-spec-generate生成需求spec文档，传递的参数是 requirement_description_file=<需求描述文件路径> android_project_dir=<安卓项目路径> spec_output_dir=<规格输出目录>
-```
-**输入参数**
-| 参数 | 类型 | 说明 |
-|------|------|------|
-| `requirement_description_file` | **必选** | 需求描述 `.txt` 文件路径(每段以 `REQ` 开头,空行分隔) |
-| `android_project_dir` | **必选** | Android项目根目录路径(必须位于Git仓库内) |
-| `spec_output_dir` | **必选** | 规格文档输出目录(自动创建;每个REQ生成 `<feature>-SPEC.md` + `.trace/<feature>.md`) |
-**输出产物**
-| 产物 | 位置 | 说明 |
-|------|------|------|
-| `<feature>-SPEC.md` | `spec_output_dir` | 每个REQ对应一份原子场景规格文档 |
-| `.trace/<feature>.md` | `spec_output_dir/.trace/` | 每个REQ对应的代码trace(homegraph探索结果) |
----
-## 步骤3:逻辑代码转换流水线
-> 📦 依赖:DevEco Studio(必需,构建/评审修复);Node.js (≥ 18,运行 `self-test-runner.js` 等编译后的入口) + 鸿蒙真机(集成测试阶段需要,可经 `skip_test` 跳过)。
-> 👤 前置:
-> 1. 如果执行集成测试，需要**准备测试用例文档**:可由 [`hmos-test-case-generation` skill](#测试用例生成可独立运行产出喂给集成测试) 自动生成,其产出的 `test_case.md` 作为 `test_case_path` 传入;`pre_test_case.md` 为前置测试用例(非必须,用于测试用例的环境准备等),作为 `pre_test_case_path` 传入。
-> 2. 如果执行集成测试，需要**连接HarmonyOS真机**并且在DevEco Studio中[**配置签名**](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/networkboost-preparations#%E9%85%8D%E7%BD%AE%E7%AD%BE%E5%90%8D)。
-打开本地editor(claude code,open code等),在会话中通过 `斜杠/ `或者 `自然语言 `的方式调用skill--hmos-convert-pipeline，并且传递相关参数)
-斜杠调用方式举例
-```
-/hmos-convert-pipeline android_project_dir=<安卓项目路径> harmony_project_dir=<鸿蒙项目路径> spec_file_path=<需求规格文档路径>
-```
-自然语言调用方式举例
-```
-帮我使用skill：hmos-convert-pipeline完成逻辑代码开发，代码检视，集成测试，传递的参数是 android_project_dir=<安卓项目路径> harmony_project_dir=<鸿蒙项目路径> spec_file_path=<需求规格文档路径>
-```
-**输入参数**
-| 参数 | 类型 | 说明 |
-|------|------|------|
-| `android_project_dir` | **必选** | Android项目根目录路径 |
-| `harmony_project_dir` | **必选** | HarmonyOS项目根目录路径 |
-| `spec_file_path` | **必选** | 需求规格文档路径(各阶段直接读取,无需复制到输出目录) |
-| `assets_output_path` | 可选 | 输出/报告文件存放目录(默认鸿蒙工程下 `.hometrans`,自动创建) |
-| `test_case_path` | 可选 | 自测用例文件路径(默认读输出目录下 `test_case.md`;不存在则跳过自测循环) |
-| `pre_test_case_path` | 可选 | 前置用例文件路径(默认读输出目录下 `pre_test_case.md`;存在才传给自测) |
-| `max_rounds_review` | 可选 | 代码检视循环最大轮数(正整数 `>= 1`,默认 `2`) |
-| `max_rounds_test` | 可选 | 自测循环最大轮数(正整数 `>= 1`,默认 `2`) |
-| `skip_test` | 可选 | `true` 跳过集成测试阶段(无真机验证环境时设为 `true`,默认 `false`) |
-> 参数按位置传递:要传某个可选参数,需先显式给出它前面的所有可选参数。
-**输出产物**
-| 产物 | 位置 | 说明 |
-|------|------|------|
-| 已签名HAP | HarmonyOS项目下 `build/` | 通过自测/评审循环后的最终发布包 |
-| `pipeline-manifest.md` | `assets_output_path` | 流水线清单:阶段耗时、轮数、缺陷统计 |
-| 构建阶段报告 | `assets_output_path` | 编译错误与修复记录 |
-| 评审阶段报告 | `assets_output_path` | 代码检视报告与修复记录 |
-| 自测阶段报告 | `assets_output_path` | 测试结果、失败用例与修复记录 |
----
-## 步骤4:人工验收
-**输入**
-| 输入 | 说明 |
-|------|------|
-| `pipeline-manifest.md` | 流水线清单与缺陷统计 |
-| 自测报告 | 集成测试skill/步骤3自测阶段产出的测试报告 |
-| 已签名HAP | 步骤3流水线产出的最终发布包 |
-**输出**
-| 产物 | 说明 |
-|------|------|
-| 可发布的HarmonyOS应用 | 已处理报告中的遗留缺陷/TODO,通过核心场景走查 |
-通读 `pipeline-manifest.md` 与自测报告,真机走查核心场景,处理报告中的遗留缺陷/TODO后发布。
----
-## 独立skill能力
-以下能力包含在迁移流程中也可按需独立调用。
-### 资源转换
-> 📦 依赖:DevEco Studio中的java(可选,缺失时回退读取源码 `res/`)。
-> ⚠️ 提示:如果步骤1采用 **UI迁移**(`hmos-batch-ui-align`),则跳过当前能力(UI迁移内部已包含资源转换)。
-打开本地editor(claude code,open code等),在会话中通过 `斜杠/ `或者 `自然语言 `的方式调用skill--hmos-resources-convert，并且传递相关参数)
-斜杠调用方式举例
-```
-/hmos-resources-convert android_project_dir=<安卓项目路径> harmony_project_dir=<鸿蒙项目路径> resource_mapping_path=<资源映射文档路径>
-```
-自然语言调用方式举例
-```
-帮我使用skill：hmos-resources-convert完成安卓应用到鸿蒙应用的资源转换，传递的参数是 android_project_dir=<安卓项目路径> harmony_project_dir=<鸿蒙项目路径> resource_mapping_path=<资源映射文档路径>
-```
-**输入参数**
-| 参数 | 类型 | 说明 |
-|------|------|------|
-| `android_project_dir` | **必选** | Android项目根目录路径(含 `build.gradle` 或 `build.gradle.kts`) |
-| `harmony_project_dir` | **必选** | HarmonyOS项目输出路径 |
-| `resource_mapping_path` | **必选** | Android ↔ HarmonyOS资源映射文档的完整输出路径(`.md`) |
-| `apk_path` | 可选 | Android APK文件路径;提供后跳过Gradle构建,直接用apktool解包该APK提取资源 |
-**输出产物**
-| 产物 | 位置 | 说明 |
-|------|------|------|
-| `resources/` 目录 | HarmonyOS项目下 | 转换后的HarmonyOS资源(strings、colors、dimensions、images等) |
-| 资源映射文档 | `resource_mapping_path` | Android ↔ HarmonyOS资源条目映射(`.md`) |
-| 转换报告 | HarmonyOS项目下 | 资源转换过程与统计 |
-### 测试用例生成(可独立运行;产出喂给集成测试)
-> 📦 依赖:Node.js ≥ 22.18 / 23.6(必需,非LLM校验脚本 `validate.ts`、BFS crawler 和 mapping 转换脚本经 Node 原生类型擦除运行,无需编译、无依赖);ADB + Android 设备/模拟器(可选,仅在需 TCG 自动产 `ui_elements.json` 时需要);其余由LLM编排。
-TCG 的主流程是测试用例生成:输入 spec-generate 产出的 `<feature>-SPEC.md`(`## 场景N` 原子场景块),输出自带四诚实证据的 `test_case.md` / `pre_test_case.md`,可直接作为集成测试skill的 `test_case_path` / `pre_test_case_path`。
-`ui_elements.json` 是这个生成流程的可选软参照,用于把操作具化为真实控件路径。若没有传入 `ui-elements-path`,但提供了 `package` 或 `android-project-dir`,TCG 会先运行 viewtree-based UI elements mapping 生成:使用 `tools/bfs-crawl/android_viewtree_bfs_crawler.ts` 采集 Android 运行时 viewtree dump,再通过转换脚本生成 mapping。
-打开本地editor(claude code,open code等),在会话中通过 `斜杠/ `或者 `自然语言 `的方式调用skill--hmos-test-case-generation，并且传递相关参数)
-斜杠调用方式举例
-```
-/hmos-test-case-generation spec-path=<SPEC文档路径> package=<包名>
-```
-自然语言调用方式举例
-```
-帮我使用skill：hmos-test-case-generation基于规格文档生成测试用例，传递的参数是 spec-path=<SPEC文档路径> package=<包名>
-```
-**输入参数**
-| 参数 | 类型 | 说明 |
-|------|------|------|
-| `spec-path` | **必选** | `<feature>-SPEC.md`(spec-generate 产出,含 `## 场景N` 原子场景块) |
-| `ui-elements-path` | 可选 | `ui_elements.json`(软参照,不保真、可缺;缺但给了 `package` 或 `android-project-dir` 时 TCG 自动产) |
-| `package` | 可选 | Android 应用包名(如 `com.example.app`);`ui-elements-path` 缺时直接用它跑 dump,优先于 `android-project-dir` |
-| `android-project-dir` | 可选 | Android 源码工程根目录;`package` 也缺时从 `build.gradle` 推导包名再跑 dump(需 ADB + 设备) |
-| `references-dir` | 可选 | 参考资料(操作定义/页面描述/模板/可复用前置用例库/特殊测试数据) |
-| `output-path` | 可选 | 输出目录;默认 `spec-path` 同级的 `testcase-output/` |
-**主要交付产物**
-| 产物 | 位置 | 说明 |
-|------|------|------|
-| `test_case.md` | `<output-path>/` 顶层 | 主测试用例(固定文件名,自带四诚实证据,作为下游 `hmos-integration-test` 的 `test_case_path`) |
-| `pre_test_case.md` | `<output-path>/` 顶层 | 前置用例(从「见前置用例」前提反向组装;无命中则不出) |
-| `review_notes.md` | `<output-path>/` 顶层 | 单一人工伴随件(阻塞区 + 非阻塞区合一;不得另产 `manual-intervention.md`) |
-> `output-path` 只放上表中的交付产物。运行时会在其同级创建 `{output-path}.work/`,保存 `_bfs_dump/`、`cases-report.json`、`md-report.json` 等过程产物。
-> 完成时 stdout 最后一行 `TCG_COMPLETE specs={N} ok={K} failed={A} output={output-path}`(N=场景数,K=两门均放行的场景数,A=留记号/FATAL的场景数)。
-### 集成测试(已包含在步骤3的流水线,也可以单独运行)
-> 📦 依赖:DevEco Studio(必需,真机调试);鸿蒙真机(必需)。
-打开本地editor(claude code,open code等),在会话中通过 `斜杠/ `或者 `自然语言 `的方式调用skill--hmos-integration-test，并且传递相关参数)
-斜杠调用方式举例
-```
-/hmos-integration-test test_case_path=<测试用例路径> hap_path=<签名HAP路径>
-```
-自然语言调用方式举例
-```
-帮我使用skill：hmos-integration-test基于测试用例完成鸿蒙应用的集成测试，传递的参数是 test_case_path=<测试用例路径> hap_path=<签名HAP路径>
-```
-**输入参数**
-| 参数 | 类型 | 说明 |
-|------|------|------|
-| `test_case_path` | **必选** | `test_case.md` 测试用例文件路径 |
-| `hap_path` | **必选** | 已签名的HAP文件路径 |
-| `output_path` | 可选 | 报告输出目录 |
-| `pre_test_case_path` | 可选 | 前置用例文件路径 |
-| `android_project_dir` | 可选 | Android项目路径(修复时参考) |
-| `max_rounds` | 可选 | 测试-修复循环最大轮数(默认 `3`) |
-**输出产物**
-| 产物 | 位置 | 说明 |
-|------|------|------|
-| 测试报告 | `output_path` | 测试结果、通过/失败用例统计 |
-| 失败用例详情 | `output_path` | 失败用例的复现步骤与日志 |
-| 修复建议 | `output_path` | 针对失败用例的修复方向(进入测试-修复循环时生效) |
+# HomeTrans integrated into [DevEco Code](https://gitcode.com/openharmony-sig/deveco-code/)