安卓应用迁移鸿蒙指导

本文档为完整的 Android 到 HarmonyOS 迁移流程指导。

步骤 0:安装依赖

0.1 安装依赖并连接设备

按以下顺序安装(ht init 会逐项检测,并提示缺失项对各 skill 的影响)。各依赖下方均列出了「被依赖」的步骤:如果你不需要执行某依赖所对应的步骤,则可以不安装该依赖(相应 skill 会显示为受限或不可用,但不影响其它步骤)。

1. 安装 DevEco Studio — 下载地址:https://developer.huawei.com/consumer/cn/download/。安装完成后,配置以下 PATH 环境变量(<DevEco安装目录> 指 DevEco Studio 的安装根目录):

   | 工具 | PATH 中加入的目录 | |------|------------------| | node / npm / npx | <DevEco安装目录>\tools\node | | java | <DevEco安装目录>\jbr\bin | | hdc | <DevEco安装目录>\sdk\default\openharmony\toolchains |

   验证方式:执行 node -v、java -version、hdc -v 均返回正常

   被依赖:

   • 步骤 1 资源转换(java 可选,缺失时回退读取源码 res/)
   • 步骤 2.2 增量 UI 迁移(必需)
   • 步骤 4 逻辑代码转换流水线(必需,构建/评审修复)
   • 步骤 5 自测回归(必需,真机调试)

2. 安装 Android Studio — 下载地址:https://developer.android.com/studio,并在 SDK Manager 中安装 SDK。

   验证方式:执行 adb version 返回正常

   被依赖:

   • 步骤 2.1 全量 UI 迁移(可选,仅自动抓取页面快照时需要)
   • 步骤 2.2 增量 UI 迁移(必需)

3. 安装 uv — 安装指引:https://docs.astral.sh/uv/getting-started/installation/。

   验证方式:执行 uv --version 返回正常

   被依赖:

   • 步骤 4 逻辑代码转换流水线的自测阶段(可经 skip-test 跳过)
   • 步骤 5 自测回归(必需,AutoTest 在 uv 下运行)

4. 安装 python — 安装指引:https://www.python.org/downloads/,要求 ≥ 3.10。

   验证方式:执行 python --version 返回正常

   被依赖:

   • 步骤 2.1 全量 UI 迁移(必需,页面快照解析脚本)
   • 步骤 2.2 增量 UI 迁移(必需,双端页面采集脚本)

5. 安装 GitNexus — 执行 npm install -g gitnexus && gitnexus setup

   验证方式:执行 gitnexus --version 返回正常

   被依赖:

   • 步骤 3 生成需求规格(必需)

6. 连接设备 — 连接安卓和鸿蒙真机,或启动模拟器

   被依赖:

   • 安卓真机/模拟器 — 步骤 2 UI 迁移
   • 鸿蒙真机/模拟器 — 步骤 2.2 增量 UI 迁移
   • 鸿蒙真机 — 步骤 4 流水线自测阶段、步骤 5 自测回归

0.2 安装 hometrans

执行 npm install -g @buaa_smat/hometrans。

验证方式:执行 hometrans --version 或 ht --version 返回正常

然后执行 hometrans init 或 ht init,配置 DEVECO_SDK_HOME、TEST_API_KEY、GLM_API_KEY。

如果在 PowerShell 下运行,命令需要加上 .cmd 后缀,如 hometrans.cmd --version、ht.cmd init。

选择本地 editor:

参数配置:

• DEVECO_SDK_HOME — DevEco Studio 的 sdk 目录(唯一输入),其余路径由它派生并校验存在,示例:

  + DEVECO_SDK_HOME : <DevEco安装目录>\sdk
  + DEVECO_PATH     : <DevEco安装目录>
  + OHOS_SDK_PATH   : <DevEco安装目录>\sdk\default\openharmony\ets
  + HMS_SDK_PATH    : <DevEco安装目录>\sdk\default\hms\ets

• TEST_API_KEY — 集成测试 agent 执行测试用例(真机自测)所用的 LLM API key。目前 AutoTest 仅支持单层模式(agent_mode: single),走阿里云百炼(DashScope)兼容接口下的通义模型 qwen3.5-plus(见用户目录下 ~/.hometrans/tools/test-tools/autotest/config.yaml 的 unified_model;Windows 即 C:\Users\<用户名>\.hometrans\tools\test-tools\autotest\config.yaml)。该文件由 ht init 在首次运行时从同目录的 config.yaml.example 自动生成,并把此处填写的 TEST_API_KEY 写入其中的 api_key。在阿里云百炼平台 https://bailian.console.aliyun.com/ 申请 API Key 并开通对应模型,按量计费。如需更换模型,可直接编辑上述 config.yaml 中 unified_model 的 name/base_url/provider/api_key。

• GLM_API_KEY — UI对齐中过程中GLM phone agent 所用的 LLM API key。GLM_API_KEY在智谱官方网站https://bigmodel.cn/apikey/platform申请API KEY即可，调用的是免费的auto-glm模型，无需充值。

0.3 准备项目

准备 Android 源项目 与 HarmonyOS 目标项目目录。

步骤 1:资源转换(hmos-resources-convert)

📦 依赖:DevEco Studio 中的 java(可选,缺失时回退读取源码 res/)。

⚠️ 提示:如果步骤 2 的 UI 迁移采用全量迁移(hmos-batch-ui-align),则跳过当前步骤(全量UI迁移内部已包含资源转换)。

/hmos-resources-convert android-project-path=<安卓项目路径> harmonyos-project-path=<鸿蒙项目路径> resource_mapping_path=<资源映射文档路径>

输入参数

| 参数 | 类型 | 说明 | |------|------|------| | android-project-path | 必选 | Android 项目根目录路径(含 build.gradle 或 build.gradle.kts) | | harmonyos-project-path | 必选 | 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 项目下 | 资源转换过程与统计 |

步骤 2:UI 迁移

2.1 全量迁移(hmos-batch-ui-align)

📦 依赖:python(必需,页面快照解析脚本);Android Studio + 安卓真机/模拟器(可选,仅自动抓取页面快照时需要)。

/hmos-batch-ui-align android_project_dir=<安卓项目路径> harmony_project_dir=<鸿蒙项目路径> ui_info_root=<页面快照目录>

输入参数

| 参数 | 类型 | 说明 | |------|------|-------------------------------------------------------------------------------------------------------------| | android_project_dir | 必选 | Android 项目根目录路径 | | harmony_project_dir | 必选 | HarmonyOS 项目输出路径 | | ui_info_root | 可选 | 包含 page_NNNN_ActivityName 格式子目录的父目录(每子目录含 meta.json + view.xml + 可选 screenshot.png);不提供时自动通过 adb 抓取 | | pages | 可选 | 显式列出的页面子集(不提供则处理所有页面) |

输出产物

| 产物 | 位置 | 说明 | |------|------|------| | ArkTS 页面文件 | HarmonyOS 项目下 | 由 Android Activity 转换生成的 ArkTS 页面 | | 资源文件 | HarmonyOS 项目下 | 页面所需资源(含全量迁移内部触发的资源转换产物) | | 批量转换报告 | HarmonyOS 项目下 | 各页面转换结果、缺陷与统计 |

2.2 增量迁移(hmos-incremental-ui-align,按需)

📦 依赖:DevEco Studio、Android Studio、python(必需,双端页面采集脚本);安卓真机/模拟器 + 鸿蒙真机/模拟器(必需)。

👤 前置:需用户预先配置好 config.json(双端 app 包名/工程路径等,参考 skill 目录下 config-example.json;ht init 已预置并填充 glm_api_key / hmos_sdk_dir)。对齐目标在消息中描述,如 "帮我对齐设置页面的关于页面"。

/hmos-incremental-ui-align config-path=<config.json路径>

输入参数

| 参数 | 类型 | 说明 | |------|------|------| | config-path | 可选 | config.json 路径,含 android.project_dir、harmony.project_dir、hmos_sdk_dir、glm_api_key、capture_output_dir 等字段;|

输出产物

| 产物 | 位置 | 说明 | |------|------|------| | 修改后的 ArkTS 页面文件 | HarmonyOS 项目下 | 对齐目标页面后的代码改动 | | 双端页面截图与视图树 | capture_output_dir | Android/HarmonyOS 两侧 screenshot.png + 视图树文件 | | 对齐差异/修复报告 | capture_output_dir | 差异分析与修复说明 |

步骤 3:生成需求规格(hmos-spec-generate)

📦 依赖:GitNexus(必需)。

👤 前置:用户编写 REQ .txt 文件 — 每段一个需求、空行分隔,作为本步骤规格生成的输入来源。

/hmos-spec-generate requirement-description-file=<需求描述文件路径> android-project-path=<安卓项目路径> spec-output-dir=<规格输出目录>

输入参数

| 参数 | 类型 | 说明 | |------|------|------| | requirement-description-file | 必选 | 需求描述 .txt 文件路径(每段以 REQ 开头,空行分隔) | | android-project-path | 必选 | 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(GitNexus 探索结果) |

步骤 4:逻辑代码转换流水线(hmos-convert-pipeline)

📦 依赖:DevEco Studio(必需,构建/评审修复);uv + 鸿蒙真机(自测阶段需要,可经 skip-test 跳过)。

👤 前置:

1. 编写测试用例文档(自测阶段的依据),路径经可选参数 test-case-path 传入(默认读输出目录下 test_case.md;前置用例同理 pre-test-case-path)。
2. 连接 HarmonyOS 真机,在 DevEco Studio 中配置签名。

/hmos-convert-pipeline android-project-path=<安卓项目路径> harmonyos-project-path=<鸿蒙项目路径> spec-file-path=<需求规格文档路径>

输入参数

| 参数 | 类型 | 说明 | |------|------|------| | android-project-path | 必选 | Android 项目根目录路径 | | harmonyos-project-path | 必选 | HarmonyOS 项目根目录路径 | | spec-file-path | 必选 | 需求规格文档路径(各阶段直接读取,无需复制到输出目录) | | assets-output-path | 可选 | 输出/报告文件存放目录(默认鸿蒙工程下 .hometrans_output,自动创建) | | 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 | 测试结果、失败用例与修复记录 |

步骤 5:自测回归(hmos-integration-test,可反复执行)

📦 依赖:DevEco Studio(必需,真机调试);uv(必需,AutoTest 在 uv 下运行);鸿蒙真机(必需)。

/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-path | 可选 | Android 项目路径(修复时参考) | | max-rounds | 可选 | 测试-修复循环最大轮数(默认 3) |

输出产物

| 产物 | 位置 | 说明 | |------|------|------| | 测试报告 | output-path | 测试结果、通过/失败用例统计 | | 失败用例详情 | output-path | 失败用例的复现步骤与日志 | | 修复建议 | output-path | 针对失败用例的修复方向(进入测试-修复循环时生效) |

步骤 6:人工验收(👤 用户介入)

输入

| 输入 | 说明 | |------|------| | pipeline-manifest.md | 流水线清单与缺陷统计 | | 自测报告 | 步骤 5/步骤 4 自测阶段产出的测试报告 | | 已签名 HAP | 步骤 4 流水线产出的最终发布包 |

输出

| 产物 | 说明 | |------|------| | 可发布的 HarmonyOS 应用 | 已处理报告中的遗留缺陷/TODO,通过核心场景走查 |

通读 pipeline-manifest.md 与自测报告,真机走查核心场景,处理报告中的遗留缺陷/TODO 后发布。