@buaa_smat/hometrans 0.1.9 → 0.1.11

package/README.md

@@ -1,213 +1,229 @@
-# hometrans
-
-> Skill + agent installer for the **HomeTrans** Android-to-HarmonyOS conversion toolkit. One command (`ht init`) distributes **7 skills**, **9 subagents** (with a script bundle + on-device test tooling), and an **MCP server** into Claude Code, Cursor, OpenCode, and Codex.
-
----
-
-## Install
-
-Global install — exposes both `hometrans` and the short alias `ht` on `PATH`:
-
-```bash
-npm install -g @buaa_smat/hometrans
-ht init
-```
-
-Requires Node.js **>= 18**.
-
----
-
-## Setup Guide
-
-After running `ht init`, follow these steps to complete the installation:
-
-### Step 1: Choose your target editor
-
-`ht init` automatically detects supported editors (Claude Code, Cursor, OpenCode, Codex) and presents an interactive selection prompt. Use **Space** to toggle and **Enter** to confirm.
-
-![Choose target editor](resource/choose_editor.png)
-
-### Step 2: Finish initialization
-
-After confirming your editor selection, HomeTrans installs all bundled **skills**, **agents**, and the **MCP server** into each selected editor's configuration directory. The installation is idempotent — re-running `ht init` overwrites only bundled content.
-
-![Finish initialization](resource/finish_init.png)
-
-> **Tip:** Run `ht init --all` to skip the editor prompt and install to every detected editor automatically.
-
----
-
-## Dependencies
-
-Install GitNexus (code knowledge graph dependency required by the migration agents):
-
-```bash
-npm install -g gitnexus
-gitnexus setup
-```
-
-For more details, see the official GitNexus repository: <https://github.com/abhigyanpatwari/GitNexus>
-
----
-
-## HarmonyOS Migration Guide
-
-鸿蒙软件迁移指导，提供完整的 Android 到 HarmonyOS 迁移流程：
-
-### Step 1: Resource Conversion (资源转换)
-
-> `hmos-batch-ui-align` 内部会自动调用资源转换；如果是批量UI迁移场景则可跳过此步骤。
-
-将 Android 资源文件（图片、字符串、颜色、尺寸等）转换为 HarmonyOS 格式。
-
-```
-/hmos-resources-convert android-project-path=<安卓项目路径> harmonyos-project-path=<鸿蒙项目路径> 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 提取资源 |
-
-### Step 2: UI Migration (UI迁移)
-
-运行以下命令之一完成 Android UI 的全量或增量迁移。
-
-#### 全量迁移 — `hmos-batch-ui-align`
-
-```
-/hmos-batch-ui-align android_project_dir=<安卓项目路径> harmony_project_dir=<鸿蒙项目路径> ui_info_root=<页面快照目录>
-```
-
-| 参数 | 类型 | 说明 |
-|------|------|------|
-| `android_project_dir` | **必选** | Android 项目根目录路径 |
-| `harmony_project_dir` | **必选** | HarmonyOS 项目输出路径 |
-| `ui_info_root` | 可选 | 包含 `page_NNNN_ActivityName` 格式子目录的父目录路径（每子目录含 `meta.json` + `view.xml` + 可选 `screenshot.png`）；不提供时 skill 自动通过 ADB 抓取 |
-| `pages` | 可选 | 显式列出的页面子集（如不提供则处理所有页面） |
-
-#### 增量迁移 — `hmos-incremental-ui-align`
-
-项目路径通过 `config.json` 文件配置（参考 skill 目录下的 `config-example.json`），对齐目标在消息中描述（如 "帮我对齐设置页面的关于页面"）。
-
-```
-/hmos-incremental-ui-align config-path=<config.json路径>
-```
-
-| 参数 | 类型 | 说明 |
-|------|------|------|
-| `config-path` | **必选** | `config.json` 文件路径，包含 `android.project_dir`, `harmony.project_dir`, `hmos_sdk_dir`, `glm_api_key`, `capture_output_dir` 等字段 |
-
-### Step 3: Generate Spec (生成需求规格)
-
-运行 `hmos-spec-generate` 从原始需求描述 `.txt` 文件生成原子场景需求规格文档。
-
-```
-/hmos-spec-generate requirement-description-file=<需求描述文件路径> android-project-path=<安卓项目路径> spec-output-dir=<规格输出目录>
-```
-
-| 参数 | 类型 | 说明 |
-|------|------|------|
-| `requirement-description-file` | **必选** | 需求描述 `.txt` 文件路径（每段以 `REQ` 开头，空行分隔） |
-| `android-project-path` | **必选** | Android 项目根目录路径（必须位于 Git 仓库内） |
-| `spec-output-dir` | **必选** | 规格文档输出目录（自动创建；每个 REQ 生成 `<feature>-SPEC.md` + `.trace/<feature>.md`） |
-
-### Step 4: Convert Pipeline (逻辑代码开发)
-
-运行 `hmos-convert-pipeline` 完成后续的逻辑代码开发、代码检视、集成测试流程。
-
-```
-/hmos-convert-pipeline android-project-path=<安卓项目路径> harmonyos-project-path=<鸿蒙项目路径> assets-output-path=<输出报告目录>
-```
-
-| 参数 | 类型 | 说明 |
-|------|------|------|
-| `android-project-path` | **必选** | Android 项目根目录路径 |
-| `harmonyos-project-path` | **必选** | HarmonyOS 项目根目录路径 |
-| `assets-output-path` | **必选** | 输出/报告文件的存放目录（需包含 `plan.md` 需求规格文件） |
-| `max-rounds-review` | 可选 | 代码检视循环最大轮数（正整数 `>= 1`，默认 `2`） |
-| `max-rounds-test` | 可选 | 自测循环最大轮数（正整数 `>= 1`，默认 `2`） |
-| `skip-test` | 可选 | `true` 跳过集成测试阶段（无真机验证环境时需要设置为true，默认 `false`） |
-
----
-
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `ht init` | Interactive setup: detect installed editors, prompt for SDK paths + test API key, copy skills/agents to target directories, seed/refresh autotest `config.yaml`, register MCP server |
-| `ht mcp` | Start the HomeTrans MCP server (stdio mode), exposing the `extract_commit_context` tool |
-| `ht config` | Display `~/.hometrans/config.json` path, parameters (with masked API key), and full content (read-only; edit the file directly, then re-run `ht init`) |
-| `ht uninstall` | Remove all skills, agents, and MCP entries installed by `ht init` from configured editors |
-| `ht --version` | Show installed version |
-| `ht --help` | List all commands |
-
-> `hometrans` and `ht` are fully equivalent — both point to the same CLI entry.
-
----
-
-## What `ht init` does
-
-1. **Detects** each supported editor by checking whether its standard config directory exists under `$HOME`, then lets you select which ones to configure (detected editors are pre-checked). Use `ht init --all` to skip the prompt and select every editor.
-2. **Prompts for user parameters** and stores them in `~/.hometrans/config.json` (press Enter to keep the current value or leave empty):
-   - `OHOS_SDK_PATH` — OpenHarmony SDK ETS path
-   - `HMS_SDK_PATH` — HMS SDK ETS path
-   - `TEST_API_KEY` — API key written into the autotest `config.yaml`
-   These are stored under a single `env` object in `~/.hometrans/config.json` (alongside `TOOL_PATH`, set in the next step).
-3. **Installs bundled tools** to `~/.hometrans/tools` (the AutoTest toolchain lives at `~/.hometrans/tools/test-tools/autotest`) and records the destination as `env.TOOL_PATH` in `~/.hometrans/config.json`. Agents/skills resolve the AutoTest dir from `env.TOOL_PATH`.
-4. **Seeds/refreshes the autotest config**: if `<TOOL_PATH>/test-tools/autotest/config.yaml` is missing it is created from `config.yaml.example`, and every `api_key:` line is filled with the supplied `TEST_API_KEY`.
-5. For every selected editor, **copies**:
-   - every skill folder under `skills/` (those containing a `SKILL.md`) → `<editor>/skills/<skill-name>/` (recursive — preserves subdirectory structure)
-   - every agent under `agents/` → `<editor>/agents/` (recursive — preserves `<agent>/scripts/` subtrees)
-6. **Registers the MCP server** (auto-adapts to editor config format: jsonc-object / jsonc-command-array / codex-cli / toml-section).
-7. Editors whose marker directory is missing are reported as **`skipped`** — nothing is written for them.
-8. The install is **idempotent** — re-running overwrites bundled content only. It never touches files under `<editor>/skills/` or `<editor>/agents/` that don't share a name with a bundled item.
-
-### Target directories
-
-| Editor | Marker | Skills target | Agents target |
-|--------|--------|---------------|---------------|
-| Claude Code | `~/.claude/` | `~/.claude/skills/` | `~/.claude/agents/` |
-| Cursor | `~/.cursor/` | `~/.cursor/skills/` | `~/.cursor/agents/` |
-| OpenCode | `~/.config/opencode/` | `~/.config/opencode/skills/` | `~/.config/opencode/agents/` |
-| Codex | `~/.codex/` | `~/.agents/skills/` | `~/.codex/agents/` |
-
----
-
-## Skills
-
-| Skill | Trigger phrases | Description | Prerequisites | Arguments | Example |
-|-------|-----------------|-------------|---------------|-----------|--------|
-| `hmos-convert-pipeline` | "full Android-to-HarmonyOS pipeline", "run the conversion pipeline end-to-end", "hmos-convert-pipeline" | Runs all conversion agents in sequence with progress tracking, duration stats, and defect recording. 4 stages: Logic Development (Context Builder) → Logic Coding → Build → Code Review/Fix/Rebuild loop → Self-Test/Fix/Rebuild loop | `assets-output-path` 下需存在 `plan.md` 需求规格文件 | `android-project-path` (required), `harmonyos-project-path` (required), `assets-output-path` (required), `max-rounds-review` (optional, default 2), `max-rounds-test` (optional, default 2), `skip-test` (optional, default false) | `"/hmos-convert-pipeline android-project-path=D:/path/to/android harmonyos-project-path=D:/path/to/harmonyos assets-output-path=D:/path/to/output"` |
-| `hmos-spec-generate` | "spec generation", "generate spec", "requirement to spec", "atomic scenarios", "scenario decomposition", "req to spec" | Generates atomic-scenario requirement specs from raw `.txt` requirement batches. Reads REQ blocks, explores the Android code graph via GitNexus, writes per-REQ trace files, then synthesizes specs from the trace | 需求描述文件 (`.txt`)，每段以 `REQ` 开头 | `requirement-description-file` (required), `android-project-path` (required), `spec-output-dir` (required) | `"/hmos-spec-generate requirement-description-file=D:/path/to/req.txt android-project-path=D:/path/to/android spec-output-dir=D:/path/to/specs"` |
-| `hmos-resources-convert` | "Android resources to HarmonyOS", "migrate Android res", "convert drawables/strings/colors" | Converts Android project resources (strings, colors, dimensions, images, drawables, icons) into HarmonyOS resources, including qualifier directories and XML→JSON format conversion | Android 项目中需包含 `res/` 资源目录 | `android-project-path` (required), `harmonyos-project-path` (required), `resource_mapping_path` (required), `apk-path` (optional) | `"/hmos-resources-convert android-project-path=D:/path/to/android harmonyos-project-path=D:/path/to/harmonyos resource_mapping_path=D:/path/to/resource_mapping.md"` |
-| `hmos-incremental-ui-align` | "UI对齐", "页面对齐", "和安卓对齐", "鸿蒙页面修复", "UI增量开发", "align HarmonyOS with Android" | Automated HarmonyOS-Android UI alignment: navigates to target pages on both devices, captures view trees + screenshots, then aligns HarmonyOS code to match Android | 需连接 Android 设备进行 UI 对比；`config-path` 指向的 `config.json` 中需配置项目路径、SDK 路径、API key | `config-path` (required) | `"/hmos-incremental-ui-align config-path=D:/path/to/config.json 帮我对齐设置页面的关于页面"` |
-| `hmos-batch-ui-align` | "把安卓页面迁移到鸿蒙", "Android UI 转鸿蒙", "批量转 ArkTS" | Batch-converts multiple Android Activity UI snapshots (`page_NNNN_ActivityName`) to HarmonyOS ArkUI (ArkTS) pages | `ui_info_root` 下需包含 `page_NNNN_ActivityName` 格式的页面快照子目录 | `android_project_dir` (required), `harmony_project_dir` (required), `ui_info_root` (optional), `pages` (optional) | `"/hmos-batch-ui-align android_project_dir=D:/path/to/android harmony_project_dir=D:/path/to/harmonyos ui_info_root=D:/path/to/pages"` |
-| `hmos-integration-test` | "跑自测", "运行自测", "自动测试", "设备测试", "self test", "run autotest" | Runs on-device self-test for a HarmonyOS app: parses `test_case.md`, installs the HAP, executes AutoTest, and produces a verification report — optionally entering a test-and-fix loop | 需存在 `test_case.md` 测试用例文件，设备需安装待测 HAP | `test-case-path` (required), `hap-path` (required), `output-path` (optional), `pre-test-case-path` (optional), `android-project-path` (optional), `max-rounds` (optional, default 3) | `"/hmos-integration-test test-case-path=D:/path/to/test_case.md hap-path=D:/path/to/app-signed.hap"` |
-| `hmos-fix-build-errors` | "build HarmonyOS project", "fix compile errors", "auto build and fix", "hmos-fix-build-errors" | Builds a HarmonyOS NEXT project from the command line, parses compile errors, fixes them, and retries in a loop until the build succeeds. Default produces an unsigned HAP; `--signed` produces a signed HAP | 有效的 HarmonyOS 项目（含 `build-profile.json5`、`entry/src`、`oh-package.json5`）+ DevEco Studio 安装目录；`--signed` 时签名配置须已存在于 `build-profile.json5` | `harmonyos-project-path` (required), `deveco-studio-path` (required), `--signed` (optional) | `"/hmos-fix-build-errors D:/MyHmosApp \"D:/DevEco Studio\" --signed"` |
-
----
-
-## Agents
-
-| Agent | Description |
-|-------|-------------|
-| `logic-context-builder` | Constrains HarmonyOS ArkTS app changes into an executable decision contract |
-| `logic-coder` | Executes HarmonyOS ArkTS code implementation from the decision contract (ships with `scripts/platform_context_query.py`) |
-| `build-fixer` | Automatically builds a HarmonyOS project, parses compile errors, fixes them, and retries in a loop until the build succeeds |
-| `code-reviewer` | Reviews HarmonyOS code against user scenarios to validate functional coverage |
-| `review-fixer` | Fixes issues from code review reports — verifies each issue before fixing, references Android source, uses cautious per-scenario fix strategies |
-| `spec-generator` | Generates requirement spec documents for each requirement description file in a folder by exploring the Android codebase and decomposing into atomic user scenarios |
-| `self-tester` | Unified self-test agent — parses `test_case.md` into `testcases.json`, runs on-device AutoTest verification, and produces a report. A `setup` boolean controls whether the parse phase runs (skip on round-2+ to reuse prior artifacts) |
-| `self-test-fixer` | Fixes issues identified by self-testing — reads the self-test report, white-box verifies failures, plans and executes fixes in order |
-
----
-
-
-
-<p align="center">
-<a href="https://gitcode.com/SMAT/HomeTrans">Official Repository</a> •
-<a href="https://gitcode.com/SMAT/HomeTrans/blob/main/LICENSE">MIT License</a>
-</p>
+# 安卓应用迁移鸿蒙指导
+
+本文档为完整的 Android 到 HarmonyOS 迁移流程指导。
+
+---
+
+## 步骤 0:安装依赖
+
+### 0.1 安装依赖并连接设备
+
+按以下顺序安装(`ht init` 会逐项检测,并提示缺失项对各 skill 的影响):
+
+1. **安装 DevEco Studio** — 下载地址:<https://developer.huawei.com/consumer/cn/download/>。安装完成后,配置以下 **PATH 环境变量**(`<DevEco安装目录>` 指 DevEco Studio 的安装根目录):
+
+   | 工具 | PATH 中加入的目录 |
+      |------|------------------|
+   | node / npm / npx | `<DevEco安装目录>\tools\node` |
+   | java | `<DevEco安装目录>\jbr\bin` |
+   | hdc | `<DevEco安装目录>\sdk\default\openharmony\toolchains` |
+
+   验证方式:执行 `node -v`、`java -version`、`hdc -v` 均返回正常
+
+   被依赖:
+   - 步骤 1 资源转换(java 可选,缺失时回退读取源码 `res/`)
+   - 步骤 2.2 增量 UI 迁移(必需)
+   - 步骤 6 逻辑代码转换流水线(必需,构建/评审修复)
+   - 步骤 7 自测回归(必需,真机调试)
+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` 返回正常
+
+   被依赖:
+   - 步骤 6 逻辑代码转换流水线的自测阶段(可经 `skip-test` 跳过)
+   - 步骤 7 自测回归(必需,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`
+
+   验证方式:执行 `gitnexus --version` 返回正常
+
+   被依赖:
+   - 步骤 4 生成需求规格(必需)
+
+6. **连接设备** — 连接安卓和鸿蒙真机,或启动模拟器
+
+   被依赖:
+   - 安卓真机/模拟器 — 步骤 2 UI 迁移
+   - 鸿蒙真机/模拟器 — 步骤 2.2 增量 UI 迁移、步骤 6 流水线自测阶段、步骤 7 自测回归
+
+### 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`。
+
+> 如果在 PowerShell 下运行,命令需要加上 `.cmd` 后缀,如 `hometrans.cmd --version`、`ht.cmd init`。
+
+选择本地 editor:
+
+![选择本地 editor](resource/choose_editor.png)
+
+参数配置:
+
+![参数配置](resource/hometrans_config.png)
+
+- `DEVECO_SDK_HOME` — DevEco Studio 的 sdk 目录(唯一输入),其余路径由它派生并校验存在,示例:
+
+  ```text
+  + DEVECO_SDK_HOME : <DevEco安装目录>\sdk
+  + DEVECO_PATH     : <DevEco安装目录>
+  + OHOS_SDK_PATH   : <DevEco安装目录>\sdk\default\openharmony\ets
+  + HMS_SDK_PATH    : <DevEco安装目录>\sdk\default\hms\ets
+  ```
+
+- `TEST_API_KEY` — 集成测试 agent 执行测试用例所用的 LLM API key
+- `GLM_API_KEY` — UI对齐中过程中GLM phone agent 所用的 LLM API key
+
+### 0.3 准备项目
+
+准备 **Android 源项目** 与 **HarmonyOS 目标项目目录**。
+
+---
+
+## 步骤 1:资源转换(`hmos-resources-convert`)
+
+将 Android 资源(图片、字符串、颜色、尺寸等)转换为 HarmonyOS 资源格式,产出 `resources/` + 资源映射文档 + 转换报告。
+
+> ⚠️ 提示:如果步骤 2 的 UI 迁移采用**全量迁移**(`hmos-batch-ui-align`),则跳过当前步骤(全量UI迁移内部已包含资源转换)。
+
+```
+/hmos-resources-convert android-project-path=<安卓项目路径> harmonyos-project-path=<鸿蒙项目路径> 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 提取资源 |
+
+---
+
+## 步骤 2:UI 迁移
+
+按场景选择全量或增量方式之一。
+
+### 2.1 全量迁移(`hmos-batch-ui-align`)
+
+遍历采集页面快照 → 批量生成 ArkTS 页面 → 统一编译修复。
+
+```
+/hmos-batch-ui-align android_project_dir=<安卓项目路径> harmony_project_dir=<鸿蒙项目路径> ui_info_root=<页面快照目录>
+```
+
+| 参数 | 类型 | 说明                                                                                                          |
+|------|------|-------------------------------------------------------------------------------------------------------------|
+| `android_project_dir` | **必选** | Android 项目根目录路径                                                                                             |
+| `harmony_project_dir` | **必选** | HarmonyOS 项目输出路径                                                                                            |
+| `ui_info_root` | 可选 | 包含 `page_NNNN_ActivityName` 格式子目录的父目录(每子目录含 `meta.json` + `view.xml` + 可选 `screenshot.png`);不提供时自动通过 adb 抓取 |
+| `pages` | 可选 | 显式列出的页面子集(不提供则处理所有页面)                                                                                       |
+
+### 2.2 增量迁移(`hmos-incremental-ui-align`,按需)
+
+双端采集指定页面 → 差异分析 → 对齐修复。
+
+> 👤 前置:需用户预先配置好 `config.json`(双端 app 包名/工程路径等,参考 skill 目录下 `config-example.json`;`ht init` 已预置并填充 `glm_api_key` / `hmos_sdk_dir`)。对齐目标在消息中描述,如 "帮我对齐设置页面的关于页面"。
+
+```
+/hmos-incremental-ui-align config-path=<config.json路径>
+```
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `config-path` | 可选 | `config.json` 路径,含 `android.project_dir`、`harmony.project_dir`、`hmos_sdk_dir`、`glm_api_key`、`capture_output_dir` 等字段;|
+
+---
+
+## 步骤 3:编写原始需求文件(👤 用户介入)
+
+编写 REQ `.txt` 文件:每段一个需求、空行分隔 — 这是下一步规格生成的输入来源。
+
+---
+
+## 步骤 4:生成需求规格(`hmos-spec-generate`)
+
+REQ 文本 → GitNexus 代码图谱探索 → 代码 Trace → 原子场景规格(`*-SPEC.md`)。
+
+```
+/hmos-spec-generate requirement-description-file=<需求描述文件路径> android-project-path=<安卓项目路径> spec-output-dir=<规格输出目录>
+```
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `requirement-description-file` | **必选** | 需求描述 `.txt` 文件路径(每段以 `REQ` 开头,空行分隔) |
+| `android-project-path` | **必选** | Android 项目根目录路径(必须位于 Git 仓库内) |
+| `spec-output-dir` | **必选** | 规格文档输出目录(自动创建;每个 REQ 生成 `<feature>-SPEC.md` + `.trace/<feature>.md`) |
+
+---
+
+## 步骤 5:流水线前置准备(👤 用户介入)
+
+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)。
+
+---
+
+## 步骤 6:逻辑代码转换流水线(`hmos-convert-pipeline`)
+
+逻辑开发 → 编码 → 构建 → 评审修复循环 → 自测修复循环 → 签名 HAP + `pipeline-manifest.md`。内部复用 `hmos-fix-build-errors` 与 `hmos-integration-test`(自测内核)。
+
+```
+/hmos-convert-pipeline android-project-path=<安卓项目路径> harmonyos-project-path=<鸿蒙项目路径> 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`) |
+
+> 参数按位置传递:要传某个可选参数,需先显式给出它前面的所有可选参数。
+
+---
+
+## 步骤 7:自测回归(`hmos-integration-test`,可反复执行)
+
+对任意签名 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`) |
+
+---
+
+## 步骤 8:人工验收(👤 用户介入)
+
+通读 `pipeline-manifest.md` 与自测报告,真机走查核心场景,处理报告中的遗留缺陷/TODO 后发布。

package/agents/build-fixer.md

@@ -37,21 +37,28 @@ Read the config file written by `ht init` at `~/.hometrans/config.json` (`$HOME/
 {
   "editors": [ /* ... */ ],
   "env": {
-    "OHOS_SDK_PATH": "...",   // OpenHarmony SDK ETS path, e.g. "D:/DevEco Studio/sdk/default/openharmony/ets"
-    "HMS_SDK_PATH": "...",    // HMS SDK ETS path, e.g. "D:/DevEco Studio/sdk/default/hms/ets"
+    "DEVECO_SDK_HOME": "...", // DevEco sdk dir, e.g. "D:/DevEco Studio/sdk" — single source of truth
+    "DEVECO_PATH": "...",     // DevEco install root, e.g. "D:/DevEco Studio" (derived from DEVECO_SDK_HOME)
+    "OHOS_SDK_PATH": "...",   // <DEVECO_SDK_HOME>/default/openharmony/ets (derived)
+    "HMS_SDK_PATH": "...",    // <DEVECO_SDK_HOME>/default/hms/ets (derived)
     "TEST_API_KEY": "...",
     "TOOL_PATH": "..."        // HomeTrans tools dir, e.g. "C:/Users/<you>/.hometrans/tools"
   }
 }
 ```
 
-Read `env.OHOS_SDK_PATH` from this file.
+### 0b. Resolve the DevEco root `<deveco>` — config first, then env vars, then ask
 
-### 0b. Derive the DevEco Studio root and tool paths
+Stop at the **first** source that yields a path:
 
-The DevEco Studio installation root is the part of `OHOS_SDK_PATH` before the SDK suffix. Strip the trailing `/sdk/default/openharmony/ets` (or `\sdk\default\openharmony\ets`) from `OHOS_SDK_PATH` to get `<deveco>`.
+1. **Config file** (`~/.hometrans/config.json`):
+   - `env.DEVECO_PATH` if non-empty → that is `<deveco>`.
+   - else `env.DEVECO_SDK_HOME` → `<deveco>` is its **parent directory**.
+   - else (legacy configs) strip the trailing `/sdk/default/openharmony/ets` from `env.OHOS_SDK_PATH` (or `/sdk/default/hms/ets` from `env.HMS_SDK_PATH`) to get `<deveco>`.
+2. **Environment variables** (same precedence): `DEVECO_PATH` → `DEVECO_SDK_HOME` (parent dir) → `OHOS_SDK_PATH` / `HMS_SDK_PATH` (strip suffix as above).
+3. **Auto-detect** (0c below). If that also fails, **ask the user** for the DevEco Studio install path.
 
-> Example: `OHOS_SDK_PATH = D:/DevEco Studio/sdk/default/openharmony/ets` → `<deveco> = D:/DevEco Studio`.
+> Example: `DEVECO_SDK_HOME = D:/DevEco Studio/sdk` → `<deveco> = D:/DevEco Studio`.
 
 From `<deveco>`, derive:
 - **Node executable**: `<deveco>/tools/node/node.exe`
@@ -59,11 +66,11 @@ From `<deveco>`, derive:
 - **ohpm**: `<deveco>/tools/ohpm/bin/ohpm`
 - **SDK directory**: `<deveco>/sdk`
 
-Verify these files exist. If they do, use them and skip auto-detection. (Fall back to `env.HMS_SDK_PATH` — stripping `/sdk/default/hms/ets` — if `OHOS_SDK_PATH` is absent but `HMS_SDK_PATH` is present.)
+Verify these files exist. If they do, use them and skip auto-detection. If a config-sourced path does **not** exist on disk, treat that source as invalid and continue down the resolution order.
 
-### 0c. Auto-detect if config is missing or invalid
+### 0c. Auto-detect if config and env vars are missing or invalid
 
-If `~/.hometrans/config.json` is missing, has empty `env.OHOS_SDK_PATH`/`HMS_SDK_PATH`, or the derived paths don't point to real files, auto-detect:
+If neither the config file nor environment variables yield a valid install, auto-detect:
 
 1. **Find DevEco Studio installation**:
    - Search common locations: `D:\DevEco Studio`, `C:\DevEco Studio`, `C:\Program Files\DevEco Studio`
@@ -74,7 +81,7 @@ If `~/.hometrans/config.json` is missing, has empty `env.OHOS_SDK_PATH`/`HMS_SDK
    - `where node` (Windows) or `which node` (Unix)
    - Verify it runs: `node --version`
 
-If auto-detection fails for any critical path, **stop and report clearly** what is missing so the user can run `ht init` to configure it.
+If auto-detection fails for any critical path, **ask the user directly** for the DevEco Studio install path (and suggest running `ht init` to persist it for next time).
 
 ### 0d. Store resolved paths
 

package/agents/code-reviewer.md

@@ -33,8 +33,10 @@ Before starting the review, extract the code context for the commit via the `ext
    - `projectPath`: `<harmonyos-project-path>` (absolute path to the HarmonyOS project root containing the `.git` directory)
    - `commitId`: `<commit-id>` (the git commit to analyze — diffs against its first parent)
    - `mode`: `"default"` (builds full call graph for call-chain context)
-   - `ohosSdkPath`: the OpenHarmony SDK ETS directory path if known (e.g. `D:/DevEco Studio/sdk/default/openharmony/ets`); omit to let the tool read `OHOS_SDK_PATH` from the environment
-   - `hmsSdkPath`: the HMS SDK ETS directory path if known (e.g. `D:/DevEco Studio/sdk/default/hms/ets`); omit to let the tool read `HMS_SDK_PATH` from the environment
+   - `ohosSdkPath` / `hmsSdkPath`: the OpenHarmony / HMS SDK ETS directory paths. Resolve each in this order, stop at the first hit:
+     1. `env.OHOS_SDK_PATH` / `env.HMS_SDK_PATH` from `~/.hometrans/config.json` (on Windows `%USERPROFILE%\.hometrans\config.json`); if those are empty but `env.DEVECO_SDK_HOME` is set, derive them as `<DEVECO_SDK_HOME>/default/openharmony/ets` and `<DEVECO_SDK_HOME>/default/hms/ets`.
+     2. Omit the parameter to let the tool read `OHOS_SDK_PATH` / `HMS_SDK_PATH` from the environment variables.
+     3. If neither config nor environment provides a path that exists on disk, **ask the user** for the DevEco `sdk` directory (and suggest `ht init` to persist it).
 
 2. **On success** — the tool returns the affected code context (diffs, call graphs, impacted files). Treat this response as the **code context** for the review.