@buaa_smat/hometrans 0.1.12 → 0.1.14

package/README.md

@@ -1,23 +1,21 @@
 # 安卓应用迁移鸿蒙指导
 
-[English](README.en.md) · **简体中文**
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-![Platform](https://img.shields.io/badge/platform-windows-blue.svg)
 
-本文档为完整的 Android 到 HarmonyOS 迁移流程指导。
+本文档为完整的Android到HarmonyOS迁移流程指导。
 
 ---
 
-## 步骤 0:安装依赖
+## 步骤0:安装依赖
 
-### 0.1 安装依赖并连接设备
+### 0.1安装依赖并连接设备
 
-按以下顺序安装(`ht init` 会逐项检测,并提示缺失项对各 skill 的影响)。各依赖下方均列出了「被依赖」的步骤:如果你不需要执行某依赖所对应的步骤,则可以不安装该依赖(相应 skill 会显示为受限或不可用,但不影响其它步骤)。
+按以下顺序安装(`ht init` 会逐项检测,并提示缺失项对各skill的影响)。各依赖下方均列出了「被依赖」的步骤:如果你不需要执行某依赖所对应的步骤,则可以不安装该依赖(相应skill会显示为受限或不可用,但不影响其它步骤)。
 
-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环境变量**(`<DevEco安装目录>` 指DevEco Studio的安装根目录):
 
-   | 工具 | PATH 中加入的目录 |
+   | 工具 | PATH中加入的目录 |
       |------|------------------|
    | node / npm / npx | `<DevEco安装目录>\tools\node` |
    | java | `<DevEco安装目录>\jbr\bin` |
@@ -26,113 +24,138 @@
    验证方式:执行 `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。
+   - 步骤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/>。
+   - 步骤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。
+   - 步骤4逻辑代码转换流水线的自测阶段(可经 `skip_test` 跳过)
+   - 步骤5自测回归(必需,AutoTest在uv下运行)
+4. **安装python** — 安装指引:<https://www.python.org/downloads/>,要求 ≥ 3.10。
 
    验证方式:执行 `python  --version` 返回正常
 
    被依赖:
-   - 步骤 2.1 全量 UI 迁移(必需,页面快照解析脚本)
-   - 步骤 2.2 增量 UI 迁移(必需,双端页面采集脚本)
+   - 步骤2.1全量UI迁移(必需,页面快照解析脚本)
+   - 步骤2.2增量UI对齐(必需,双端页面采集脚本)
 5. **安装 [GitNexus](https://github.com/abhigyanpatwari/GitNexus)** — 执行 `npm install -g gitnexus && gitnexus setup`
 
    验证方式:执行 `gitnexus --version` 返回正常
 
    被依赖:
-   - 步骤 3 生成需求规格(必需)
+   - 步骤3生成需求规格(必需)
 6. **连接设备** — 连接安卓和鸿蒙真机,或启动模拟器
 
    被依赖:
-   - 安卓真机/模拟器 — 步骤 2 UI 迁移
-   - 鸿蒙真机/模拟器 — 步骤 2.2 增量 UI 迁移
-   - 鸿蒙**真机** — 步骤 4 流水线自测阶段、步骤 5 自测回归
+   - 安卓真机/模拟器 — 步骤2 UI迁移
+   - 鸿蒙真机/模拟器 — 步骤2.2增量UI对齐
+   - 鸿蒙**真机** — 步骤4流水线自测阶段、步骤5自测回归
 
-### 0.2 安装 hometrans
+### 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`。
+然后执行 `hometrans init` 或 `ht init`。
 
 
-> 如果在 PowerShell 下运行,命令需要加上 `.cmd` 后缀,如 `hometrans.cmd --version`、`ht.cmd init`。
+> 如果在PowerShell下运行,命令需要加上 `.cmd` 后缀,如 `hometrans.cmd --version`、`ht.cmd init`。
 
-选择本地 editor:
+### 0.2.1选择本地editor:
+![choose_editor.png](resource/choose_editor.png)
 
-![选择本地 editor](resource/choose_editor.png)
-
-参数配置:
-
-![参数配置](resource/hometrans_config.png)
-
-- `DEVECO_SDK_HOME` — DevEco Studio 的 sdk 目录(唯一输入),其余路径由它派生并校验存在,示例:
+### 0.2.2通用配置:
+![common_config.png](resource/common_config.png)
+- `DEVECO_SDK_HOME` — DevEco Studio的sdk目录,其余路径由它派生并校验存在。示例:
 
   ```text
   + DEVECO_SDK_HOME : <DevEco安装目录>\sdk
-  + DEVECO_PATH     : <DevEco安装目录>
+  + DEVECO_HOME     : <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 目标项目目录**。
+### 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准备项目
+
+准备 **Android源项目** 与 **HarmonyOS目标项目目录**。
 
 ---
 
-## 步骤 1:资源转换(`hmos-resources-convert`)
+## 步骤1:资源转换(`hmos-resources-convert`)
 
-> 📦 依赖:DevEco Studio 中的 java(可选,缺失时回退读取源码 `res/`)。
+> 📦 依赖:DevEco Studio中的java(可选,缺失时回退读取源码 `res/`)。
 
-> ⚠️ 提示:如果步骤 2 的 UI 迁移采用**全量迁移**(`hmos-batch-ui-align`),则跳过当前步骤(全量UI迁移内部已包含资源转换)。
+> ⚠️ 提示:如果步骤2的UI迁移采用**全量迁移**(`hmos-batch-ui-align`),则跳过当前步骤(全量UI迁移内部已包含资源转换)。
 
 ```
-/hmos-resources-convert android-project-path=<安卓项目路径> harmonyos-project-path=<鸿蒙项目路径> resource_mapping_path=<资源映射文档路径>
+/hmos-resources-convert android_project_dir=<安卓项目路径> harmony_project_dir=<鸿蒙项目路径> 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 提取资源 |
+| `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 项目下 | 资源转换过程与统计 |
+| `resources/` 目录 | HarmonyOS项目下 | 转换后的HarmonyOS资源(strings、colors、dimensions、images等) |
+| 资源映射文档 | `resource_mapping_path` | Android ↔ HarmonyOS资源条目映射(`.md`) |
+| 转换报告 | HarmonyOS项目下 | 资源转换过程与统计 |
 
 ---
 
-## 步骤 2:UI 迁移
+## 步骤2:UI迁移
 
-### 2.1 全量迁移(`hmos-batch-ui-align`)
+### 2.1全量迁移(`hmos-batch-ui-align`)
 
 > 📦 依赖:python(必需,页面快照解析脚本);Android Studio + 安卓真机/模拟器(可选,仅自动抓取页面快照时需要)。
 
@@ -144,97 +167,124 @@
 
 | 参数 | 类型 | 说明                                                                                                          |
 |------|------|-------------------------------------------------------------------------------------------------------------|
-| `android_project_dir` | **必选** | Android 项目根目录路径                                                                                             |
-| `harmony_project_dir` | **必选** | HarmonyOS 项目输出路径                                                                                            |
-| `ui_info_root` | 可选 | 包含 `page_NNNN_ActivityName` 格式子目录的父目录(每子目录含 `meta.json` + `view.xml` + 可选 `screenshot.png`);不提供时自动通过 adb 抓取 |
+| `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 项目下 | 各页面转换结果、缺陷与统计 |
+| ArkTS页面文件 | HarmonyOS项目下 | 由Android Activity转换生成的ArkTS页面 |
+| 资源文件 | HarmonyOS项目下 | 页面所需资源(含全量迁移内部触发的资源转换产物) |
+| 批量转换报告 | HarmonyOS项目下 | 各页面转换结果、缺陷与统计 |
 
-### 2.2 增量迁移(`hmos-incremental-ui-align`,按需)
+### 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路径>
+/hmos-incremental-ui-align android_project_dir=<安卓工程路径> harmony_project_dir=<鸿蒙工程路径>
 ```
 
 **输入参数**
 
 | 参数 | 类型 | 说明 |
 |------|------|------|
-| `config-path` | 可选 | `config.json` 路径,含 `android.project_dir`、`harmony.project_dir`、`hmos_sdk_dir`、`glm_api_key`、`capture_output_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` + 视图树文件 |
+| 修改后的ArkTS页面文件 | HarmonyOS项目下 | 对齐目标页面后的代码改动 |
+| 双端页面截图与视图树 | `capture_output_dir` | Android/HarmonyOS两侧 `screenshot.png` + 视图树文件 |
 | 对齐差异/修复报告 | `capture_output_dir` | 差异分析与修复说明 |
 
 ---
 
-## 步骤 3:生成需求规格(`hmos-spec-generate`)
+## 步骤3:生成需求规格(`hmos-spec-generate`)
 
 > 📦 依赖:GitNexus(必需)。
 
-> 👤 前置:用户编写 REQ `.txt` 文件 — 每段一个需求、空行分隔,作为本步骤规格生成的输入来源。
+> 👤 前置:用户编写 `REQ.txt` 文件 — 以自然语言描述原始需求，如有多个需求则在文件中使用空行进行分隔，需求中建议包含页面跳转路径的说明以及业务逻辑的描述。
+
+`REQ.txt` 示例:
+
+```text
+设置-歌词-歌词界面-卡拉OK歌词动画兼容策略（播放页歌词设置同步实现）
+逐字歌词效果，默认是当前行
+    1,当前行：只为前歌曲的歌词中有单字时间戳的歌词行显示逐字特效
+    2,扩展全部：当前歌曲的歌词中只要有一行歌词带单字时间戳，所有歌词行都显示逐字特效
+    3,总是：当前歌曲所有歌词行都显示逐字特效
+
+设置-用户界面-圆形播放封面（圆形支持旋转）
+开关，默认关闭，打开后，在播放页以圆形展示封面，并且自动旋转
+
+设置-用户界面-允许不规则封面（支持长方形封面，参考无归）
+开关，默认打开，播放页封面以大小一致的正方形展示，打开后，在播放页封面以原始样式展示
+
+设置-歌词-悬浮窗状态栏歌词
+开关 ，默认关闭，打开前需要申请悬浮窗权限，打开后在悬浮窗滚动展示歌词
+    1,左右位置：默认0%
+    2,上下位置：默认0px
+    3,宽度：默认150dp
+    4,大小：默认14.0dp
+    5,选择颜色：默认蓝色
+    6,歌词文本居左对齐：开关 默认关闭，歌词在设置的宽度内中对齐
+    7,状态栏歌词不显示翻译：开关 默认关闭
+    8,在播放界面隐藏：开关 默认关闭 打开后如果切换到播放页，则不在悬浮窗区域显示歌词
+```
 
 ```
-/hmos-spec-generate requirement-description-file=<需求描述文件路径> android-project-path=<安卓项目路径> spec-output-dir=<规格输出目录>
+/hmos-spec-generate requirement_description_file=<需求描述文件路径> android_project_dir=<安卓项目路径> spec_output_dir=<规格输出目录>
 ```
 
 **输入参数**
 
 | 参数 | 类型 | 说明 |
 |------|------|------|
-| `requirement-description-file` | **必选** | 需求描述 `.txt` 文件路径(每段以 `REQ` 开头,空行分隔) |
-| `android-project-path` | **必选** | Android 项目根目录路径(必须位于 Git 仓库内) |
-| `spec-output-dir` | **必选** | 规格文档输出目录(自动创建;每个 REQ 生成 `<feature>-SPEC.md` + `.trace/<feature>.md`) |
+| `requirement_description_file` | **必选** | 需求描述 `.txt` 文件路径(每段以 `REQ` 开头,空行分隔) |
+| `android_project_dir` | **必选** | 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 探索结果) |
+| `<feature>-SPEC.md` | `spec_output_dir` | 每个REQ对应一份原子场景规格文档 |
+| `.trace/<feature>.md` | `spec_output_dir/.trace/` | 每个REQ对应的代码trace(GitNexus探索结果) |
 
 ---
 
-## 步骤 4:逻辑代码转换流水线(`hmos-convert-pipeline`)
+## 步骤4:逻辑代码转换流水线(`hmos-convert-pipeline`)
 
-> 📦 依赖:DevEco Studio(必需,构建/评审修复);uv + 鸿蒙真机(自测阶段需要,可经 `skip-test` 跳过)。
+> 📦 依赖:DevEco Studio(必需,构建/评审修复);uv + 鸿蒙真机(集成测试阶段需要,可经 `skip_test` 跳过)。
 
 > 👤 前置:
-> 1. **编写测试用例文档**(自测阶段的依据),路径经可选参数 `test-case-path` 传入(默认读输出目录下 `test_case.md`;前置用例同理 `pre-test-case-path`)。
-> 2. 连接 HarmonyOS 真机,在 DevEco Studio 中[**配置签名**](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/networkboost-preparations#%E9%85%8D%E7%BD%AE%E7%AD%BE%E5%90%8D)。
+> 1. 如果执行集成测试，需要**编写测试用例文档**输出前置测试用例（非必须，用于测试用例的环境准备等）通过pre_test_case_path参数传递,测试用例通过test_case_path参数传递。
+> 2. 如果执行集成测试，需要**连接HarmonyOS真机**并且在DevEco Studio中[**配置签名**](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/networkboost-preparations#%E9%85%8D%E7%BD%AE%E7%AD%BE%E5%90%8D)。
 
 ```
-/hmos-convert-pipeline android-project-path=<安卓项目路径> harmonyos-project-path=<鸿蒙项目路径> spec-file-path=<需求规格文档路径>
+/hmos-convert-pipeline android_project_dir=<安卓项目路径> harmony_project_dir=<鸿蒙项目路径> 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`) |
+| `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`) |
 
 > 参数按位置传递:要传某个可选参数,需先显式给出它前面的所有可选参数。
 
@@ -242,57 +292,57 @@
 
 | 产物 | 位置 | 说明 |
 |------|------|------|
-| 已签名 HAP | HarmonyOS 项目下 `build/` | 通过自测/评审循环后的最终发布包 |
-| `pipeline-manifest.md` | `assets-output-path` | 流水线清单:阶段耗时、轮数、缺陷统计 |
-| 构建阶段报告 | `assets-output-path` | 编译错误与修复记录 |
-| 评审阶段报告 | `assets-output-path` | 代码检视报告与修复记录 |
-| 自测阶段报告 | `assets-output-path` | 测试结果、失败用例与修复记录 |
+| 已签名HAP | HarmonyOS项目下 `build/` | 通过自测/评审循环后的最终发布包 |
+| `pipeline-manifest.md` | `assets_output_path` | 流水线清单:阶段耗时、轮数、缺陷统计 |
+| 构建阶段报告 | `assets_output_path` | 编译错误与修复记录 |
+| 评审阶段报告 | `assets_output_path` | 代码检视报告与修复记录 |
+| 自测阶段报告 | `assets_output_path` | 测试结果、失败用例与修复记录 |
 
 ---
 
-## 步骤 5:自测回归(`hmos-integration-test`,可反复执行)
+## 步骤5:集成测试(`hmos-integration-test`，已包含在步骤4，也可以单独运行)
 
-> 📦 依赖:DevEco Studio(必需,真机调试);uv(必需,AutoTest 在 uv 下运行);鸿蒙真机(必需)。
+> 📦 依赖:DevEco Studio(必需,真机调试);uv(必需,AutoTest在uv下运行);鸿蒙真机(必需)。
 
 ```
-/hmos-integration-test test-case-path=<测试用例路径> hap-path=<签名HAP路径>
+/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`) |
+| `test_case_path` | **必选** | `test_case.md` 测试用例文件路径 |
+| `hap_path` | **必选** | 已签名的HAP文件路径 |
+| `output_path` | 可选 | 报告输出目录 |
+| `pre_test_case_path` | 可选 | 前置用例文件路径 |
+| `android_project_dir` | 可选 | Android项目路径(修复时参考) |
+| `max_rounds` | 可选 | 测试-修复循环最大轮数(默认 `3`) |
 
 **输出产物**
 
 | 产物 | 位置 | 说明 |
 |------|------|------|
-| 测试报告 | `output-path` | 测试结果、通过/失败用例统计 |
-| 失败用例详情 | `output-path` | 失败用例的复现步骤与日志 |
-| 修复建议 | `output-path` | 针对失败用例的修复方向(进入测试-修复循环时生效) |
+| 测试报告 | `output_path` | 测试结果、通过/失败用例统计 |
+| 失败用例详情 | `output_path` | 失败用例的复现步骤与日志 |
+| 修复建议 | `output_path` | 针对失败用例的修复方向(进入测试-修复循环时生效) |
 
 ---
 
-## 步骤 6:人工验收(👤 用户介入)
+## 步骤6:人工验收(👤 用户介入)
 
 **输入**
 
 | 输入 | 说明 |
 |------|------|
 | `pipeline-manifest.md` | 流水线清单与缺陷统计 |
-| 自测报告 | 步骤 5/步骤 4 自测阶段产出的测试报告 |
-| 已签名 HAP | 步骤 4 流水线产出的最终发布包 |
+| 自测报告 | 步骤5/步骤4自测阶段产出的测试报告 |
+| 已签名HAP | 步骤4流水线产出的最终发布包 |
 
 **输出**
 
 | 产物 | 说明 |
 |------|------|
-| 可发布的 HarmonyOS 应用 | 已处理报告中的遗留缺陷/TODO,通过核心场景走查 |
+| 可发布的HarmonyOS应用 | 已处理报告中的遗留缺陷/TODO,通过核心场景走查 |
 
-通读 `pipeline-manifest.md` 与自测报告,真机走查核心场景,处理报告中的遗留缺陷/TODO 后发布。
+通读 `pipeline-manifest.md` 与自测报告,真机走查核心场景,处理报告中的遗留缺陷/TODO后发布。