# HomeTrans
**HomeTrans工具用于辅助鸿蒙开发者完成原生安卓应用迁移到鸿蒙应用，为应用迁移的各个环节提供能力支持。**
[](LICENSE)
[](https://nodejs.org/en/download)
[](https://developer.huawei.com/consumer/cn/download/)
[](https://developer.android.com/studio)
[](https://gitcode.com/openharmony-sig/deveco-cli)
[](#选择本地editor)
[](#选择本地editor)
[](#选择本地editor)
[](#选择本地editor)
[](#选择本地editor)
[](#选择本地editor)
## 能力全景图
---
## 安卓应用迁移鸿蒙指导
> 💡 提示:为了提升迁移效果,请尽可能选择上下文窗口大的模型。
## 安装DevEco Studio以及Android Studio
1. **安装DevEco Studio** — 下载地址:。安装完成后,配置以下 **PATH环境变量**:
| 工具 | PATH中加入的目录 |
|------|------------------|
| hdc | `\sdk\default\openharmony\toolchains` |
验证方式:执行 `hdc -v` 返回正常
2. **安装Android Studio** — 下载地址:,并在 **SDK Manager** 中安装SDK。
验证方式:执行 `adb version` 返回正常
被依赖:
- UI迁移(通过adb获取页面信息)
- UI对齐(通过adb获取页面信息)
注：UI迁移与UI对齐使用安卓真机/模拟器均可,两者可互相替代。但当前工具不支持部分系统(Android API 16及更早版本、华为emui、部分车机.IOT设备)
## 安装Node.js
安装 **Node.js(版本需 >= 22.18)** — 下载地址:。
验证方式:执行 `node -v`、`npm -v`、`npx -v` 均返回正常,且 `node -v` 显示版本不低于 22.18
## 安装HomeTrans
执行 `npm install -g @buaa_smat/hometrans`。
验证方式:执行 `hometrans --version` 或 `ht --version` 返回正常
## 环境初始化
执行 `hometrans init` 或 `ht init`。
> 如果在PowerShell下运行,命令需要加上 `.cmd` 后缀,如 `hometrans.cmd --version`、`ht.cmd init`。
>
> `ht init` 的 Dependency Installation 阶段只自动安装 git;`homegraph`、`arkanalysis`、`devecocli` 等 Node CLI 由各 skill 在需要时通过 `npx` 按需拉起,无需预先全局安装。
### 选择本地editor:
### 参数配置:
#### 配置鸿蒙SDK:
#### 配置多模态模型(不执行UI对齐以及集成测试可以跳过该配置):
| 参数 | 含义 |
|-----------------|---------|
| `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` |
#### 集成测试 Agent 模式配置
集成测试（`hmos-integration-test`）支持两种 Agent 架构。集成测试首次运行时，skill 自动从 `ht init` 导出的 `HOMETRANS_MODEL_*` 环境变量生成 `~/.hometrans/autotest.yaml`（AutoTestAgent 原生格式），后续运行直接读取。
**Single 模式（默认）**：单 Agent 同时负责决策和执行，`ht init` 完成后即可使用，无需额外配置。
**Layered 模式（Planner + Executor 双 Agent）**：Planner 负责任务规划，Executor 负责操作执行，适合复杂测试场景。编辑 `~/.hometrans/autotest.yaml`，将 `agent.mode` 改为 `"layered"`，并在 `model:` 下添加 `execute` 和 `decision` 槽位（含 `name`、`base_url`、`api_key`、`provider` 四个字段）。
| 槽位 | 角色 | 说明 |
|------|------|------|
| `unified` | 通用模型 | Single 模式下必填，Agent 同时用于决策和执行 |
| `execute` | 执行模型 | Layered 模式下必填，Executor 负责屏幕操作，需 `name` 和 `api_key` 非空 |
| `decision` | 决策模型 | Layered 模式下必填，Planner 负责任务规划，需 `name` 和 `api_key` 非空 |
> Single 模式下只需 `unified`；Layered 模式下只需 `execute` + `decision`。未填写必填槽位会在集成测试启动时报错。
>
> `HOMETRANS_MODEL_API_KEY` 环境变量轮换只会刷新 `unified` 槽位。Layered 模式下 `execute` / `decision` 槽位的 `api_key` 需直接编辑 `~/.hometrans/autotest.yaml`——skill 不会用环境变量覆盖这两个槽位（它们可能使用不同的 key）。
#### 将配置信息添加到环境变量:
### 准备项目
准备 **Android源项目** 与 **HarmonyOS目标项目目录**。
---
## 迁移流程
---
## UI迁移
### UI迁移
> 📦 依赖:Android Studio + 安卓真机/模拟器(可选,仅自动抓取页面快照时需要)。
> 👤 前置:准备好待迁移应用的 **APK**(对应必选参数 `apk_path`)。UI迁移内部会调用资源转换,以该APK解码出的完整合并资源集(含库依赖资源)作为转换来源。
打开本地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`,由其用 `a2h-resource` 解码,提取完整合并资源集(含库依赖资源) |
**输出产物**
| 产物 | 位置 | 说明 |
|------|------|------|
| ArkTS页面文件 | HarmonyOS项目下 | 由Android Activity转换生成的ArkTS页面 |
| 资源文件 | HarmonyOS项目下 | 页面所需资源(含UI迁移内部触发的资源转换产物) |
| 批量转换报告 | HarmonyOS项目下 | 各页面转换结果、缺陷与统计 |
### 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` | 可选 | 采集产物输出目录,默认 `/.hometrans/capture_output` |
**输出产物**
| 产物 | 位置 | 说明 |
|------|------|------|
| 修改后的ArkTS页面文件 | HarmonyOS项目下 | 对齐目标页面后的代码改动 |
| 双端页面截图与视图树 | `capture_output_dir` | Android/HarmonyOS两侧 `screenshot.png` + 视图树文件 |
| 对齐差异/修复报告 | `capture_output_dir` | 差异分析与修复说明 |
---
## 生成需求规格
> 📦 依赖:homegraph(必需,经 `npx` 拉起)。
> 👤 前置:用户编写 `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` | **必选** | 需求描述文件路径。支持两类:表格(`.xlsx` / `.xlsm` / `.csv`,一行 = 一个需求)与文本(`.txt` / `.md`,空行分隔的一段 = 一个需求)。样例见 `skills/hmos-spec-generate/template/REQ.xlsx` 与 `REQ.txt` |
| `android_project_dir` | **必选** | Android项目根目录路径 |
| `spec_output_dir` | **必选** | 规格文档输出目录(自动创建;每个需求生成一份 `-SPEC.md`) |
**输出产物**
| 产物 | 位置 | 说明 |
|------|------|------|
| `-SPEC.md` | `spec_output_dir` | 每个需求对应一份原子场景规格文档;文件名固定以 `-SPEC.md` 结尾,可直接作为 `hmos-test-case-generation` 的 `spec-path` |
---
## 逻辑代码转换流水线
> 📦 依赖:DevEco Studio(必需,构建/评审修复);Node.js (>= 22.18) + 鸿蒙真机/模拟器(集成测试阶段需要,可经 `skip_test` 跳过)。
> 👤 前置:
> 如果执行集成测试，需要**准备测试用例文档**:可由 [`hmos-test-case-generation` skill](#测试用例生成可独立运行产出喂给集成测试) 自动生成,其产出的 `test_case.md` 作为 `test-case-path` 传入;`pre_test_case.md` 为前置测试用例(非必须,用于测试用例的环境准备等),作为 `pre-test-case-path` 传入。
打开本地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` | 测试结果、失败用例与修复记录 |
---
## 人工验收
**输入**
| 输入 | 说明 |
|------|------|
| `pipeline-manifest.md` | 流水线清单与缺陷统计 |
| 自测报告 | 集成测试skill/自测阶段产出的测试报告 |
| HAP | 流水线产出的最终发布包(真机走查需已签名包,见「集成测试」段的签名说明) |
**输出**
| 产物 | 说明 |
|------|------|
| 可发布的HarmonyOS应用 | 已处理报告中的遗留缺陷/TODO,通过核心场景走查 |
通读 `pipeline-manifest.md` 与自测报告,在鸿蒙真机/模拟器上走查核心场景,处理报告中的遗留缺陷/TODO后发布。
---
## 独立skill能力
以下能力包含在迁移流程中也可按需独立调用。
### 资源转换
> 📦 依赖:Node.js(解码器 `a2h-resource` 经 `npx` 拉起)。
> 👤 前置:准备好待转换的 **APK**,以及一个**已初始化的鸿蒙工程**(在DevEco Studio中新建)。
> ⚠️ 提示:如果采用 **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=<资源映射文档路径> apk_path=<安卓apk路径>
```
自然语言调用方式举例
```
帮我使用skill：hmos-resources-convert完成安卓应用到鸿蒙应用的资源转换，传递的参数是 android_project_dir=<安卓项目路径> harmony_project_dir=<鸿蒙项目路径> resource_mapping_path=<资源映射文档路径> apk_path=<安卓apk路径>
```
**输入参数**
| 参数 | 类型 | 说明 |
|------|------|------|
| `android_project_dir` | **必选** | Android项目根目录路径(含 `build.gradle` 或 `build.gradle.kts`) |
| `harmony_project_dir` | **必选** | HarmonyOS工程根目录;转换后的资源写入该工程 |
| `resource_mapping_path` | **必选** | Android ↔ HarmonyOS资源映射文档的完整输出路径(`.md`) |
| `apk_path` | **必选** | Android APK文件路径;用 `a2h-resource` 解码该APK提取完整合并资源集(含库依赖资源) |
**输出产物**
| 产物 | 位置 | 说明 |
|------|------|------|
| `resources/` 目录 | HarmonyOS项目下 | 转换后的HarmonyOS资源(strings、colors、dimensions、images等) |
| 资源映射文档 | `resource_mapping_path` | Android ↔ HarmonyOS资源条目映射(`.md`) |
| 转换报告 | HarmonyOS项目下 | 资源转换过程与统计 |
### 测试用例生成(可独立运行;产出喂给集成测试)
> 📦 依赖:Node.js >= 22.18(必需,非LLM校验脚本 `validate.ts`、BFS crawler 和 mapping 转换脚本经 Node 原生类型擦除运行,无需编译、无依赖);ADB + 安卓真机/模拟器(可选,仅在需 TCG 自动产 `ui_elements.json` 时需要);其余由LLM编排。
TCG 的主流程是测试用例生成:输入 spec-generate 产出的 `-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= package=<包名>
```
自然语言调用方式举例
```
帮我使用skill：hmos-test-case-generation基于规格文档生成测试用例，传递的参数是 spec-path= package=<包名>
```
**输入参数**
| 参数 | 类型 | 说明 |
|------|------|------|
| `spec-path` | **必选** | `-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` | `/` 顶层 | 主测试用例(固定文件名,自带四诚实证据,作为下游 `hmos-integration-test` 的 `test-case-path`) |
| `pre_test_case.md` | `/` 顶层 | 前置用例(从「见前置用例」前提反向组装;无命中则不出) |
| `review_notes.md` | `/` 顶层 | 单一人工伴随件(阻塞区 + 非阻塞区合一;不得另产 `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的场景数)。
### 集成测试(已包含在流水线中,也可以单独运行)
> 📦 依赖:DevEco Studio(必需,设备调试);鸿蒙真机/模拟器(必需)。
> 👤 前置:
> - **真机测试**：HAP 需签名。在 DevEco Studio 中配置签名：File → Project Structure → Signing Configs → 勾选 Automatically generate signature，构建后获得已签名 HAP。
> - **模拟器测试**：HAP 无需签名，直接用未签名 HAP 即可安装测试。
打开本地editor(claude code,open code等),在会话中通过 `斜杠/ `或者 `自然语言 `的方式调用skill--hmos-integration-test，并且传递相关参数)
斜杠调用方式举例
```
/hmos-integration-test test-case-path=<测试用例路径> hap-path=<包路径>
```
自然语言调用方式举例
```
帮我使用skill：hmos-integration-test基于测试用例完成鸿蒙应用的集成测试，传递的参数是 test-case-path=<测试用例路径> hap-path=<包路径>
```
**输入参数**
| 参数 | 类型 | 说明 |
|------|------|------|
| `test-case-path` | **必选** | `test_case.md` 测试用例文件路径 |
| `hap-path` | **必选** | 包路径,支持**一个或多个**(逗号分隔);每一项可以是 `.hap`/`.hsp` 文件或目录。所有项汇总起来需凑齐完整包集合:恰好一个 entry HAP + 其余 feature HAP / 应用内 HSP(应用内HSP不能单独安装,须与主包同一事务) |
| `project-dir` | 可选 | 鸿蒙工程根目录(含 `AppScope/app.json5`),用于解析 `bundle_name` / `app_name`;不传时自动从 `hap-path` / `test-case-path` 向上查找,推导失败才询问 |
| `output-path` | 可选 | 报告输出目录;默认为 `test-case-path` 所在目录 |
| `pre-test-case-path` | 可选 | 前置用例文件路径 |
| `android-project-path` | 可选 | Android项目路径(修复时参考) |
| `max-rounds` | 可选 | 测试-修复循环最大轮数(正整数 `>= 1`,默认 `3`) |
**输出产物**
| 产物 | 位置 | 说明 |
|------|------|------|
| 测试报告 | `output-path` | 测试结果、通过/失败用例统计 |
| 失败用例详情 | `output-path` | 失败用例的复现步骤与日志 |
| 修复建议 | `output-path` | 针对失败用例的修复方向(进入测试-修复循环时生效) |