@buaa_smat/hometrans 0.1.14 → 0.1.15

package/README.md

@@ -24,43 +24,43 @@
    验证方式:执行 `node -v`、`java -version`、`hdc -v` 均返回正常
 
    被依赖:
-   - 步骤1资源转换(java可选,缺失时回退读取源码 `res/`)
-   - 步骤2.2增量UI对齐(必需)
-   - 步骤4逻辑代码转换流水线(必需,构建/评审修复)
-   - 步骤5自测回归(必需,真机调试)
+   - 资源转换skill(java可选,缺失时回退读取源码 `res/`)
+   - 步骤1.2UI对齐(必需)
+   - 步骤3逻辑代码转换流水线(必需,构建/评审修复)
+   - 集成测试skill(必需,真机调试)
 2. **安装Android Studio** — 下载地址:<https://developer.android.com/studio>,并在 **SDK Manager** 中安装SDK。
 
    验证方式:执行 `adb version` 返回正常
 
    被依赖:
-   - 步骤2.1全量UI迁移(可选,仅自动抓取页面快照时需要)
-   - 步骤2.2增量UI对齐(必需)
+   - 步骤1.1UI迁移(可选,仅自动抓取页面快照时需要)
+   - 步骤1.2UI对齐(必需)
 3. **安装uv** — 安装指引:<https://docs.astral.sh/uv/getting-started/installation/>。
 
    验证方式:执行 `uv  --version` 返回正常
 
    被依赖:
-   - 步骤4逻辑代码转换流水线的自测阶段(可经 `skip_test` 跳过)
-   - 步骤5自测回归(必需,AutoTest在uv下运行)
+   - 步骤3逻辑代码转换流水线的自测阶段(可经 `skip_test` 跳过)
+   - 集成测试skill(必需,AutoTest在uv下运行)
 4. **安装python** — 安装指引:<https://www.python.org/downloads/>,要求 ≥ 3.10。
 
    验证方式:执行 `python  --version` 返回正常
 
    被依赖:
-   - 步骤2.1全量UI迁移(必需,页面快照解析脚本)
-   - 步骤2.2增量UI对齐(必需,双端页面采集脚本)
+   - 步骤1.1UI迁移(必需,页面快照解析脚本)
+   - 步骤1.2UI对齐(必需,双端页面采集脚本)
 5. **安装 [GitNexus](https://github.com/abhigyanpatwari/GitNexus)** — 执行 `npm install -g gitnexus && gitnexus setup`
 
    验证方式:执行 `gitnexus --version` 返回正常
 
    被依赖:
-   - 步骤3生成需求规格(必需)
+   - 步骤2生成需求规格(必需)
 6. **连接设备** — 连接安卓和鸿蒙真机,或启动模拟器
 
    被依赖:
-   - 安卓真机/模拟器 — 步骤2 UI迁移
-   - 鸿蒙真机/模拟器 — 步骤2.2增量UI对齐
-   - 鸿蒙**真机** — 步骤4流水线自测阶段、步骤5自测回归
+   - 安卓真机/模拟器 — 步骤1 UI迁移
+   - 鸿蒙真机/模拟器 — 步骤1.2UI对齐
+   - 鸿蒙**真机** — 步骤3流水线自测阶段、集成测试skill
 
 ### 0.2安装hometrans
 
@@ -86,13 +86,13 @@
   + OHOS_SDK_PATH   : <DevEco安装目录>\sdk\default\openharmony\ets
   + HMS_SDK_PATH    : <DevEco安装目录>\sdk\default\hms\ets
   ```
-### 0.2.3 UI对齐配置(如果不执行步骤2.2增量UI对齐,则可以不配置):
+### 0.2.3 UI对齐配置(如果不执行步骤1.2UI对齐,则可以不配置):
 ![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自测回归,则可以不配置):
+### 0.2.4集成测试配置(如果不执行步骤3的自测阶段与集成测试skill,则可以不配置):
 ![integration_test_config.png](resource/integration_test_config.png)
 - `autotest api_key` — 集成测试agent执行测试用例(真机自测)所用的多模态大模型API key。各配置项含义如下,`init` 环节只配置前4项,其余参数在`config.json`中配置。
 
@@ -123,39 +123,14 @@
 准备 **Android源项目** 与 **HarmonyOS目标项目目录**。
 
 ---
-
-## 步骤1:资源转换(`hmos-resources-convert`)
-
-> 📦 依赖:DevEco Studio中的java(可选,缺失时回退读取源码 `res/`)。
-
-> ⚠️ 提示:如果步骤2的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项目下 | 资源转换过程与统计 |
+## 迁移流程
+![migration_process.svg](resource/migration_process.svg)
 
 ---
 
-## 步骤2:UI迁移
+## 步骤1:UI迁移
 
-### 2.1全量迁移(`hmos-batch-ui-align`)
+### 1.1UI迁移(`hmos-batch-ui-align`)
 
 > 📦 依赖:python(必需,页面快照解析脚本);Android Studio + 安卓真机/模拟器(可选,仅自动抓取页面快照时需要)。
 
@@ -177,10 +152,10 @@
 | 产物 | 位置 | 说明 |
 |------|------|------|
 | 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(必需,双端页面采集脚本);安卓真机/模拟器 + 鸿蒙真机/模拟器(必需)。
 
@@ -206,7 +181,7 @@
 
 ---
 
-## 步骤3:生成需求规格(`hmos-spec-generate`)
+## 步骤2:生成需求规格(`hmos-spec-generate`)
 
 > 📦 依赖:GitNexus(必需)。
 
@@ -260,7 +235,7 @@
 
 ---
 
-## 步骤4:逻辑代码转换流水线(`hmos-convert-pipeline`)
+## 步骤3:逻辑代码转换流水线(`hmos-convert-pipeline`)
 
 > 📦 依赖:DevEco Studio(必需,构建/评审修复);uv + 鸿蒙真机(集成测试阶段需要,可经 `skip_test` 跳过)。
 
@@ -300,7 +275,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 +352,3 @@
 | 测试报告 | `output_path` | 测试结果、通过/失败用例统计 |
 | 失败用例详情 | `output_path` | 失败用例的复现步骤与日志 |
 | 修复建议 | `output_path` | 针对失败用例的修复方向(进入测试-修复循环时生效) |
-
----
-
-## 步骤6:人工验收(👤 用户介入)
-
-**输入**
-
-| 输入 | 说明 |
-|------|------|
-| `pipeline-manifest.md` | 流水线清单与缺陷统计 |
-| 自测报告 | 步骤5/步骤4自测阶段产出的测试报告 |
-| 已签名HAP | 步骤4流水线产出的最终发布包 |
-
-**输出**
-
-| 产物 | 说明 |
-|------|------|
-| 可发布的HarmonyOS应用 | 已处理报告中的遗留缺陷/TODO,通过核心场景走查 |
-
-通读 `pipeline-manifest.md` 与自测报告,真机走查核心场景,处理报告中的遗留缺陷/TODO后发布。