HomeTrans

HomeTrans工具用于辅助鸿蒙开发者完成原生安卓应用迁移到鸿蒙应用，为应用迁移的各个环节提供能力支持。

能力全景图

安卓应用迁移鸿蒙指导

💡 提示:为了提升迁移效果,请尽可能选择上下文窗口大的模型。

安装DevEco Studio以及Android Studio

1. 安装DevEco Studio — 下载地址:https://developer.huawei.com/consumer/cn/download/。安装完成后,配置以下 PATH环境变量:

   | 工具 | PATH中加入的目录 | |------|------------------| | hdc | <DevEco安装目录>\sdk\default\openharmony\toolchains |

   验证方式:执行 hdc -v 返回正常

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

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

   被依赖:

   • UI迁移(通过adb获取页面信息)
   • UI对齐(通过adb获取页面信息)

   注：UI迁移与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

安装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服务的基础地址 |

配置参考

前往阿里云百炼平台开通服务并申请 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 | 可选 | 采集产物输出目录,默认 <harmony_project_dir>/.hometrans/capture_output |

输出产物

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

生成需求规格

📦 依赖:homegraph(必需,经 npx 拉起)。

👤 前置:用户编写 REQ.txt 文件 — 以自然语言描述原始需求，如有多个需求则在文件中使用空行进行分隔，需求中建议包含页面跳转路径的说明以及业务逻辑的描述。

REQ.txt 示例:

设置-歌词-歌词界面-卡拉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 | 必选 | 规格文档输出目录(自动创建;每个需求生成一份 <feature>-SPEC.md) |

输出产物

| 产物 | 位置 | 说明 | |------|------|------| | <feature>-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 产出的 <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的场景数)。

集成测试(已包含在流水线中,也可以单独运行)

📦 依赖: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 | 针对失败用例的修复方向(进入测试-修复循环时生效) |