@buaa_smat/hometrans 0.1.14 → 0.1.16

package/README.md

@@ -2,162 +2,102 @@
 
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D%2022-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)
 
 本文档为完整的Android到HarmonyOS迁移流程指导。
 
 ---
 
-## 步骤0:安装依赖
-
-### 0.1安装依赖并连接设备
-
-按以下顺序安装(`ht init` 会逐项检测,并提示缺失项对各skill的影响)。各依赖下方均列出了「被依赖」的步骤:如果你不需要执行某依赖所对应的步骤,则可以不安装该依赖(相应skill会显示为受限或不可用,但不影响其它步骤)。
+## 安装DevEco Studio以及Android Studio
 
-1. **安装DevEco Studio** — 下载地址:<https://developer.huawei.com/consumer/cn/download/>。安装完成后,配置以下 **PATH环境变量**(`<DevEco安装目录>` 指DevEco Studio的安装根目录):
+1. **安装DevEco Studio** — 下载地址:<https://developer.huawei.com/consumer/cn/download/>。安装完成后,配置以下 **PATH环境变量**:
 
    | 工具 | PATH中加入的目录 |
       |------|------------------|
-   | node / npm / npx | `<DevEco安装目录>\tools\node` |
    | java | `<DevEco安装目录>\jbr\bin` |
    | hdc | `<DevEco安装目录>\sdk\default\openharmony\toolchains` |
 
-   验证方式:执行 `node -v`、`java -version`、`hdc -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](https://github.com/abhigyanpatwari/GitNexus)** — 执行 `npm install -g gitnexus && gitnexus setup`
+   - 步骤1.1UI迁移(可选,仅自动抓取页面快照时需要)
+   - 步骤1.2UI对齐(必需)
 
-   验证方式:执行 `gitnexus --version` 返回正常
+## 安装Node.js
 
-   被依赖:
-   - 步骤3生成需求规格(必需)
-6. **连接设备** — 连接安卓和鸿蒙真机,或启动模拟器
+安装 **Node.js(版本需 >= 22)** — 下载地址:<https://nodejs.org/en/download>。
 
-   被依赖:
-   - 安卓真机/模拟器 — 步骤2 UI迁移
-   - 鸿蒙真机/模拟器 — 步骤2.2增量UI对齐
-   - 鸿蒙**真机** — 步骤4流水线自测阶段、步骤5自测回归
+验证方式:执行 `node -v`、`npm -v`、`npx -v` 均返回正常,且 `node -v` 显示版本不低于 22
 
-### 0.2安装hometrans
+## 安装HomeTrans
 
 执行 `npm install -g @buaa_smat/hometrans`。
 
 验证方式:执行 `hometrans --version` 或 `ht --version` 返回正常
 
-然后执行 `hometrans init` 或 `ht init`。
+## 环境初始化
 
+执行 `hometrans init` 或 `ht init`。
 
 > 如果在PowerShell下运行,命令需要加上 `.cmd` 后缀,如 `hometrans.cmd --version`、`ht.cmd init`。
 
-### 0.2.1选择本地editor:
-![choose_editor.png](resource/choose_editor.png)
-
-### 0.2.2通用配置:
-![common_config.png](resource/common_config.png)
-- `DEVECO_SDK_HOME` — DevEco Studio的sdk目录,其余路径由它派生并校验存在。示例:
-
-  ```text
-  + DEVECO_SDK_HOME : <DevEco安装目录>\sdk
-  + DEVECO_HOME     : <DevEco安装目录>
-  + OHOS_SDK_PATH   : <DevEco安装目录>\sdk\default\openharmony\ets
-  + HMS_SDK_PATH    : <DevEco安装目录>\sdk\default\hms\ets
-  ```
-### 0.2.3 UI对齐配置(如果不执行步骤2.2增量UI对齐,则可以不配置):
-![ui_align_config.png](resource/ui_align_config.png)
-- `GLM_API_KEY` — UI对齐中过程中GLM phone agent所用的LLM API key。
-
-  申请方式：在[智谱官方网站](https://bigmodel.cn/apikey/platform)注册用户后，申请一个API KEY即可，调用的是免费的auto-glm模型，无需充值。
-
-### 0.2.4集成测试配置(如果不执行步骤4的自测阶段与步骤5自测回归,则可以不配置):
-![integration_test_config.png](resource/integration_test_config.png)
-- `autotest api_key` — 集成测试agent执行测试用例(真机自测)所用的多模态大模型API key。各配置项含义如下,`init` 环节只配置前4项,其余参数在`config.json`中配置。
-
-  | 参数                | 示例 / 默认值 | 含义 |
-  |-------------------|--------------|------|
-  | `name`            | `""` | 多模态(视觉)模型的名字 |
-  | `base_url`        | `""` | 模型API服务的基础地址 |
-  | `api_key`         | (需填写) | 用于模型API请求认证的令牌 |
-  | `provider`        | `openai` | 模型API服务的提供方标识,如openai;Azure服务填azure |
-  | `temperature`     | `0.1` | 采样温度 |
-  | `top_p`           | `0.9` | 核采样阈值 |
-  | `frequency_penalty` | `0.5` | 重复惩罚 |
-  | `device_sn`       | `null` | 设备序列号;`null` 表示自动选用当前连接的设备 |
-  | `ip`              | `127.0.0.1` | 设备连接IP(hdc) |
-  | `port`            | `8710` | 设备连接端口(hdc) |
-  | `device_log_level` | `debug` | 设备日志级别:debug/info/... |
-  | `max_steps`       | `50` | 单条用例最大执行步数 |
-  | `verbose`         | `true` | 是否输出详细日志 |
-  | `lang`            | `zh` | 输出语言:zh/en |
-  | `enable_preprocess` | `false` | 执行前是否先用unified_model把用例拆成步骤序列(多一次LLM调用,默认关) |
-  | `debug_mode`      | `null` | 调试会话:`null` 关闭 / `memory` 内存 / `file` 存盘并跑完后起调试服务(:5000) |
-
-### 0.2.5将配置信息添加到环境变量:
-![set_env.png](resource/set_env.png)
-
-### 0.3准备项目
+### 选择本地editor:
+![choose_editor.png](https://raw.gitcode.com/SMAT/HomeTrans/raw/main/resource/choose_editor.png)
 
-准备 **Android源项目** 与 **HarmonyOS目标项目目录**。
+### 参数配置:
 
----
+#### 配置鸿蒙SDK:
+![set_sdk.png](https://raw.gitcode.com/SMAT/HomeTrans/raw/main/resource/set_sdk.png)
 
-## 步骤1:资源转换(`hmos-resources-convert`)
+#### 配置多模态模型(不执行UI对齐以及集成测试可以跳过该配置):
+![set_multimodel.png](https://raw.gitcode.com/SMAT/HomeTrans/raw/main/resource/set_multimodel.png)
 
-> 📦 依赖:DevEco Studio中的java(可选,缺失时回退读取源码 `res/`)。
+  | 参数             | 含义             |
+  |-----------------|---------|
+  | `model_api_key` | 用于模型API请求认证的令牌   |
+  | `model_name`      | 多模态(视觉)模型的名字   |
+  | `model_base_url`       | 模型API服务的基础地址 |
 
-> ⚠️ 提示:如果步骤2的UI迁移采用**全量迁移**(`hmos-batch-ui-align`),则跳过当前步骤(全量UI迁移内部已包含资源转换)。
+##### 配置参考
 
-```
-/hmos-resources-convert android_project_dir=<安卓项目路径> harmony_project_dir=<鸿蒙项目路径> resource_mapping_path=<资源映射文档路径>
-```
+前往[阿里云百炼平台](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` |
 
-| 参数 | 类型 | 说明 |
-|------|------|------|
-| `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提取资源 |
+#### 将配置信息添加到环境变量:
+![set_environment.png](https://raw.gitcode.com/SMAT/HomeTrans/raw/main/resource/set_environment.png)
 
-**输出产物**
+### 准备项目
 
-| 产物 | 位置 | 说明 |
-|------|------|------|
-| `resources/` 目录 | HarmonyOS项目下 | 转换后的HarmonyOS资源(strings、colors、dimensions、images等) |
-| 资源映射文档 | `resource_mapping_path` | Android ↔ HarmonyOS资源条目映射(`.md`) |
-| 转换报告 | HarmonyOS项目下 | 资源转换过程与统计 |
+准备 **Android源项目** 与 **HarmonyOS目标项目目录**。
 
 ---
+## 迁移流程
+![migration_process.svg](https://raw.gitcode.com/SMAT/HomeTrans/raw/main/resource/migration_process.svg)
 
-## 步骤2:UI迁移
+---
+
+## 步骤1:UI迁移
 
-### 2.1全量迁移(`hmos-batch-ui-align`)
+### 1.1UI迁移(`hmos-batch-ui-align`)
 
-> 📦 依赖:python(必需,页面快照解析脚本);Android Studio + 安卓真机/模拟器(可选,仅自动抓取页面快照时需要)。
+> 📦 依赖:uv(必需,页面快照解析脚本经 `uv run` 运行,uv 自带 Python);Android Studio + 安卓真机/模拟器(可选,仅自动抓取页面快照时需要)。
 
 ```
 /hmos-batch-ui-align android_project_dir=<安卓项目路径> harmony_project_dir=<鸿蒙项目路径> ui_info_root=<页面快照目录>
@@ -177,12 +117,12 @@
 | 产物 | 位置 | 说明 |
 |------|------|------|
 | ArkTS页面文件 | HarmonyOS项目下 | 由Android Activity转换生成的ArkTS页面 |
-| 资源文件 | HarmonyOS项目下 | 页面所需资源(含全量迁移内部触发的资源转换产物) |
+| 资源文件 | HarmonyOS项目下 | 页面所需资源(含UI迁移内部触发的资源转换产物) |
 | 批量转换报告 | HarmonyOS项目下 | 各页面转换结果、缺陷与统计 |
 
-### 2.2增量对齐(`hmos-incremental-ui-align`,按需)
+### 1.2UI对齐(`hmos-incremental-ui-align`,按需)
 
-> 📦 依赖:DevEco Studio、Android Studio、python(必需,双端页面采集脚本);安卓真机/模拟器 + 鸿蒙真机/模拟器(必需)。
+> 📦 依赖:DevEco Studio、Android Studio、uv(必需,双端页面采集脚本经 `uv run` 运行,uv 自带 Python);安卓真机/模拟器 + 鸿蒙真机/模拟器(必需)。
 
 ```
 /hmos-incremental-ui-align android_project_dir=<安卓工程路径> harmony_project_dir=<鸿蒙工程路径>
@@ -206,9 +146,9 @@
 
 ---
 
-## 步骤3:生成需求规格(`hmos-spec-generate`)
+## 步骤2:生成需求规格(`hmos-spec-generate`)
 
-> 📦 依赖:GitNexus(必需)。
+> 📦 依赖:homegraph(必需)。
 
 > 👤 前置:用户编写 `REQ.txt` 文件 — 以自然语言描述原始需求，如有多个需求则在文件中使用空行进行分隔，需求中建议包含页面跳转路径的说明以及业务逻辑的描述。
 
@@ -256,13 +196,13 @@
 | 产物 | 位置 | 说明 |
 |------|------|------|
 | `<feature>-SPEC.md` | `spec_output_dir` | 每个REQ对应一份原子场景规格文档 |
-| `.trace/<feature>.md` | `spec_output_dir/.trace/` | 每个REQ对应的代码trace(GitNexus探索结果) |
+| `.trace/<feature>.md` | `spec_output_dir/.trace/` | 每个REQ对应的代码trace(homegraph探索结果) |
 
 ---
 
-## 步骤4:逻辑代码转换流水线(`hmos-convert-pipeline`)
+## 步骤3:逻辑代码转换流水线(`hmos-convert-pipeline`)
 
-> 📦 依赖:DevEco Studio(必需,构建/评审修复);uv + 鸿蒙真机(集成测试阶段需要,可经 `skip_test` 跳过)。
+> 📦 依赖:DevEco Studio(必需,构建/评审修复);uv + 鸿蒙真机(集成测试阶段需要,可经 `skip_test` 跳过;uv 经 `uv run` 运行 `self_test_runner.py` 并自带 Python)。
 
 > 👤 前置:
 > 1. 如果执行集成测试，需要**编写测试用例文档**输出前置测试用例（非必须，用于测试用例的环境准备等）通过pre_test_case_path参数传递,测试用例通过test_case_path参数传递。
@@ -300,7 +240,58 @@
 
 ---
 
-## 步骤5:集成测试(`hmos-integration-test`，已包含在步骤4，也可以单独运行)
+## 步骤4:人工验收(👤 用户介入)
+
+**输入**
+
+| 输入 | 说明 |
+|------|------|
+| `pipeline-manifest.md` | 流水线清单与缺陷统计 |
+| 自测报告 | 集成测试skill/步骤3自测阶段产出的测试报告 |
+| 已签名HAP | 步骤3流水线产出的最终发布包 |
+
+**输出**
+
+| 产物 | 说明 |
+|------|------|
+| 可发布的HarmonyOS应用 | 已处理报告中的遗留缺陷/TODO,通过核心场景走查 |
+
+通读 `pipeline-manifest.md` 与自测报告,真机走查核心场景,处理报告中的遗留缺陷/TODO后发布。
+
+---
+
+## 独立skill能力
+
+以下能力包含在迁移流程中也可按需独立调用。
+
+### 资源转换(`hmos-resources-convert`)
+
+> 📦 依赖:DevEco Studio中的java(可选,缺失时回退读取源码 `res/`)。
+
+> ⚠️ 提示:如果步骤1采用 **UI迁移**(`hmos-batch-ui-align`),则跳过当前能力(UI迁移内部已包含资源转换)。
+
+```
+/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项目下 | 资源转换过程与统计 |
+
+### 集成测试(`hmos-integration-test`,已包含在步骤3的流水线,也可以单独运行)
 
 > 📦 依赖:DevEco Studio(必需,真机调试);uv(必需,AutoTest在uv下运行);鸿蒙真机(必需)。
 
@@ -326,23 +317,3 @@
 | 测试报告 | `output_path` | 测试结果、通过/失败用例统计 |
 | 失败用例详情 | `output_path` | 失败用例的复现步骤与日志 |
 | 修复建议 | `output_path` | 针对失败用例的修复方向(进入测试-修复循环时生效) |
-
----
-
-## 步骤6:人工验收(👤 用户介入)
-
-**输入**
-
-| 输入 | 说明 |
-|------|------|
-| `pipeline-manifest.md` | 流水线清单与缺陷统计 |
-| 自测报告 | 步骤5/步骤4自测阶段产出的测试报告 |
-| 已签名HAP | 步骤4流水线产出的最终发布包 |
-
-**输出**
-
-| 产物 | 说明 |
-|------|------|
-| 可发布的HarmonyOS应用 | 已处理报告中的遗留缺陷/TODO,通过核心场景走查 |
-
-通读 `pipeline-manifest.md` 与自测报告,真机走查核心场景,处理报告中的遗留缺陷/TODO后发布。