@buaa_smat/hometrans 0.1.4 → 0.1.6

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 HomeTrans
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025 HomeTrans
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -45,13 +45,15 @@ Requires Node.js **>= 18**.
    - `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`
-3. **Seeds/refreshes the autotest config**: if `agents/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`.
-4. For every selected editor, **copies**:
+   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/` and `test-tools/` subtrees)
-5. **Registers the MCP server** (auto-adapts to editor config format: jsonc-object / jsonc-command-array / codex-cli / toml-section).
-6. Editors whose marker directory is missing are reported as **`skipped`** — nothing is written for them.
-7. 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.
+   - 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
 
@@ -92,15 +94,14 @@ Extracts code context index from a given git commit in a HarmonyOS project (git
 
 | Skill | Trigger phrases | Description |
 |-------|-----------------|-------------|
-| `convert-pipeline` | "full Android-to-HarmonyOS pipeline", "run the conversion pipeline end-to-end", "convert_pipeline" | Runs all conversion agents in sequence with progress tracking, duration stats, and defect recording. 9 stages: Logic Context → Logic Coding → Build → Code Review → Review Fix → Rebuild → Self-Test → Self-Test Fix → Rebuild |
-| `code-dev-review-fix` | "开发并检视", "代码开发检视修复", "实现这个需求并验证", "develop and review", "review and fix this commit" | Flexibly orchestrates HarmonyOS development/build/scenario-review/fix agents from a natural-language request — composes only the needed agents (logic-context-builder → logic-coding → build-fixer → code-reviewer / code-review-fix) instead of running a fixed pipeline |
-| `spec-generator-skill` | "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 |
+| `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. 9 stages: Logic Context → Logic Coding → Build → Code Review → Review Fix → Rebuild → Self-Test → Self-Test Fix → Rebuild |
+| `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 |
 | `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 |
-| `hmos-ui-align` | "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 |
-| `hmos-ui-align-batch` | "把安卓页面迁移到鸿蒙", "Android UI 转鸿蒙", "批量转 ArkTS" | Batch-converts multiple Android Activity UI snapshots (`page_NNNN_ActivityName`) to HarmonyOS ArkUI (ArkTS) pages |
-| `self-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 |
+| `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 |
+| `hmos-batch-ui-align` | "把安卓页面迁移到鸿蒙", "Android UI 转鸿蒙", "批量转 ArkTS" | Batch-converts multiple Android Activity UI snapshots (`page_NNNN_ActivityName`) to HarmonyOS ArkUI (ArkTS) 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 |
 
-### `convert-pipeline` Arguments
+### `hmos-convert-pipeline` Arguments
 
 1. `android-project-path` (required): path to the Android source project
 2. `harmonyos-project-path` (required): path to the target HarmonyOS project
@@ -109,7 +110,7 @@ Extracts code context index from a given git commit in a HarmonyOS project (git
 5. `max-rounds-test` (optional, default `2`): max Self-Test → Fix loop rounds
 6. `variant` (optional, default `enhanced`): `enhanced` | `baseline` — selects the Stage 1/1a agent family
 
-### `spec-generator-skill` Arguments
+### `hmos-spec-generate` Arguments
 
 1. `requirement-description-file` (required): absolute path to a single `.txt` file containing one or more REQ blocks separated by blank lines
 2. `android-project-path` (required): absolute path to the Android project root (must be inside a Git repo)
@@ -122,11 +123,9 @@ Extracts code context index from a given git commit in a HarmonyOS project (git
 | Agent | Description |
 |-------|-------------|
 | `logic-context-builder` | Constrains HarmonyOS ArkTS app changes into an executable decision contract |
-| `logic-coding` | Executes HarmonyOS ArkTS code implementation from the decision contract (ships with `scripts/platform_context_query.py`) |
+| `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 |
-| `code-review-fix` | One-pass review-fix-build cycle — reviews code, verifies and fixes confirmed issues, rebuilds the project |
-| `review-fixer` | Fixes issues from code review reports — verifies each issue before fixing, references Android source, uses cautious per-scenario fix strategies |
+| `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 |

package/agents/build-fixer.md

@@ -36,15 +36,16 @@ Read the config file written by `ht init` at `~/.hometrans/config.json` (`$HOME/
 ```jsonc
 {
   "editors": [ /* ... */ ],
-  "params": {
+  "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"
-    "TEST_API_KEY": "..."
+    "TEST_API_KEY": "...",
+    "TOOL_PATH": "..."        // HomeTrans tools dir, e.g. "C:/Users/<you>/.hometrans/tools"
   }
 }
 ```
 
-Read `params.OHOS_SDK_PATH` from this file.
+Read `env.OHOS_SDK_PATH` from this file.
 
 ### 0b. Derive the DevEco Studio root and tool paths
 
@@ -58,11 +59,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 `params.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. (Fall back to `env.HMS_SDK_PATH` — stripping `/sdk/default/hms/ets` — if `OHOS_SDK_PATH` is absent but `HMS_SDK_PATH` is present.)
 
 ### 0c. Auto-detect if config is missing or invalid
 
-If `~/.hometrans/config.json` is missing, has empty `params.OHOS_SDK_PATH`/`HMS_SDK_PATH`, or the derived paths don't point to real files, auto-detect:
+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:
 
 1. **Find DevEco Studio installation**:
    - Search common locations: `D:\DevEco Studio`, `C:\DevEco Studio`, `C:\Program Files\DevEco Studio`

package/agents/{logic-coding.md → logic-coder.md}

@@ -1,5 +1,5 @@
 ---
-name: logic-coding
+name: logic-coder
 description: "Execute the HarmonyOS ArkTS app contract without reopening design choices."
 color: blue
 min-model: sonnet
@@ -10,7 +10,7 @@ min-model: sonnet
 - `plan-file` = `{output_path}/plan.md`
 - `harmonyos-project-path` (abs)
 - `output-path` (abs)
-- `plugin-path` (abs) — plugin root; `{scripts}` = `{plugin-path}/agents/logic-coding/scripts/`
+- `plugin-path` (abs) — plugin root; `{scripts}` = `{plugin-path}/agents/logic-coder/scripts/`
 
 ## Tools
 

package/agents/logic-context-builder.md

@@ -10,7 +10,7 @@ min-model: sonnet
 - `spec-file` (abs)
 - `harmonyos-project-path` (abs)
 - `output-path` (abs)
-- `plugin-path` (abs) — plugin root; `{scripts}` = `{plugin-path}/agents/logic-coding/scripts/`
+- `plugin-path` (abs) — plugin root; `{scripts}` = `{plugin-path}/agents/logic-coder/scripts/`
 
 ## Tools
 

package/agents/self-tester.md

@@ -38,25 +38,36 @@ You are a self-tester for HarmonyOS applications. You run a single pipeline: par
 
 ### AutoTest Directory Locator
 
-Used independently by S5 and T4. **Anchor the search at `<output-path>` — sub-agent cwd is not guaranteed to sit anywhere in particular.** Walk up from `<output-path>` looking for a sibling `agents/test-tools/autotest`:
+Used independently by S5 and T4. The AutoTest tools are installed by `ht init` under the HomeTrans tools dir; resolve their location from config rather than searching the filesystem.
+
+**Primary — read `env.TOOL_PATH` from the HomeTrans config** at `~/.hometrans/config.json` (`$HOME/.hometrans/config.json`; on Windows `%USERPROFILE%\.hometrans\config.json`). The autotest dir is `<TOOL_PATH>/test-tools/autotest`:
+
+```bash
+cfg="$HOME/.hometrans/config.json"; [ -n "$USERPROFILE" ] && [ -f "$USERPROFILE/.hometrans/config.json" ] && cfg="$USERPROFILE/.hometrans/config.json"
+tool_path="$(python -c "import json,os;print(json.load(open(os.path.expanduser(r'$cfg'),encoding='utf-8')).get('env',{}).get('TOOL_PATH',''))" 2>/dev/null)"
+if [ -n "$tool_path" ] && [ -d "$tool_path/test-tools/autotest" ]; then echo "$tool_path/test-tools/autotest"; fi
+```
+
+If config is missing or `TOOL_PATH` is empty/invalid, **fall back** to walking up from `<output-path>` for a sibling `test-tools/autotest` (then `agents/test-tools/autotest` for legacy layouts) — **anchor the search at `<output-path>`, the sub-agent cwd is not guaranteed**:
 
 ```bash
 d="<output-path>"; while [ "$d" != "/" ] && [ "$d" != "" ]; do \
+  if [ -d "$d/test-tools/autotest" ]; then echo "$d/test-tools/autotest"; break; fi; \
   if [ -d "$d/agents/test-tools/autotest" ]; then echo "$d/agents/test-tools/autotest"; break; fi; \
   d="$(dirname "$d")"; \
 done
 ```
 
-If the walk-up yields nothing, fall back to a `$(pwd)`-anchored search **only as a last resort**:
+As a last resort, a `$(pwd)`-anchored search:
 
 ```bash
-find "$(pwd)" -type d -path "*/agents/test-tools/autotest" -print -quit 2>/dev/null
+find "$(pwd)" -type d -path "*/test-tools/autotest" -print -quit 2>/dev/null
 ```
 
 | Caller | Purpose | On failure |
 |--------|---------|------------|
-| S5 | Locate then run testcases_tool.py | Emit `Error: cannot locate agents/test-tools/autotest from <output-path>` and exit |
-| T4 | Locate then verify config.yaml | Write `self-test-report.md` with status **FAIL** and reason "AutoTest directory not found from output-path", then exit |
+| S5 | Locate then run testcases_tool.py | Emit `Error: cannot locate test-tools/autotest from config env.TOOL_PATH or <output-path>` and exit |
+| T4 | Locate then verify config.yaml | Write `self-test-report.md` with status **FAIL** and reason "AutoTest directory not found from config TOOL_PATH or output-path", then exit |
 
 ### Input Validation Template
 
@@ -173,7 +184,7 @@ Write to `<output-path>/_extracted.json`:
 
 ### S5 — Generate testcases.json via Python script
 
-Find the `agents/test-tools/autotest` directory using the **AutoTest Directory Locator** in Shared Utilities (walk up from `<output-path>`). Set `<autotest_dir>` to the resolved path. If not found, emit the documented error and exit. Run:
+Find the `test-tools/autotest` directory using the **AutoTest Directory Locator** in Shared Utilities (prefer config `env.TOOL_PATH`, fall back to walking up from `<output-path>`). Set `<autotest_dir>` to the resolved path. If not found, emit the documented error and exit. Run:
 
 ```bash
 cd "<autotest_dir>" && uv run python testcases_tool.py generate "<output-path>/_extracted.json" "<output-path>/testcases.json" --validate
@@ -236,7 +247,7 @@ Record the device serial number.
 
 ### T4 — Locate AutoTest Directory & Verify config.yaml
 
-Find the `agents/test-tools/autotest` directory using the **AutoTest Directory Locator** in Shared Utilities (walk up from `<output-path>`). If not found, write a `self-test-report.md` with the sentinel format (`status: FAIL` / `reason: AutoTest directory not found from output-path`), then stop.
+Find the `test-tools/autotest` directory using the **AutoTest Directory Locator** in Shared Utilities (prefer config `env.TOOL_PATH`, fall back to walking up from `<output-path>`). If not found, write a `self-test-report.md` with the sentinel format (`status: FAIL` / `reason: AutoTest directory not found from config TOOL_PATH or output-path`), then stop.
 
 Set `<autotest_dir>` to the found path. Check config.yaml:
 
@@ -370,7 +381,7 @@ cd "<autotest_dir>" && uv run python report_tool.py validate "<output-path>/self
 - **Two-phase architecture**: When the parse phase runs, the LLM writes `_extracted.json` → `testcases_tool.py` writes `testcases.json`. Never write `testcases.json` directly. If `testcases.json` already exists at the output path and the parse phase runs, `testcases_tool.py` overwrites it — never skip the script.
 - **App name → bundle_name is critical**: `test_steps` must use `bundle_name` (e.g., `com.example.tuku`), NOT the display name. AutoTest uses this to launch the correct app. Using the display name instead may launch the wrong app entirely.
 - **JSON contract**: `app-metadata.json` and `testcases.json` always live at `<output-path>/app-metadata.json` and `<output-path>/testcases.json`. T2 reads from the file (not from memory).
-- **AutoTest directory locator**: Walk up from `<output-path>` (see Shared Utilities). Do not assume `$(pwd)` is anchored anywhere in particular.
+- **AutoTest directory locator**: Resolve `<TOOL_PATH>/test-tools/autotest` from `~/.hometrans/config.json` (`env.TOOL_PATH`); fall back to walking up from `<output-path>` (see Shared Utilities). Do not assume `$(pwd)` is anchored anywhere in particular.
 - **Sentinel-format early-exit reports**: When T1 / T3 / T4 / T7 write a degraded FAIL report (config error, no device, missing autotest dir, crashed batch, timeout, or `setup=false` precondition failure), the report's first non-frontmatter line MUST be `status: FAIL` and the second MUST be `reason: <one-line reason>`. This lets callers detect early-exit reports without parsing a case table.
 - **Quote all paths** — paths may contain spaces.
 - **Capture complete output** — never truncate command output; it is essential for diagnosis.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buaa_smat/hometrans",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "HomeTrans (Android-to-HarmonyOS) skill + agent installer. Run `ht init` to distribute conversion skills and subagents into AI editors.",
   "license": "MIT",
   "type": "module",

package/skills/{hmos-ui-align-batch → hmos-batch-ui-align}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: hmos-ui-align-batch
-description: Batch-convert multiple Android Activity UI snapshots to HarmonyOS ArkUI (ArkTS) pages. Use when the user wants to migrate Android UI pages to HarmonyOS in bulk, port multiple Activity screens to ArkTS, or run an Android-to-HarmonyOS UI conversion across a folder of page snapshots (page_NNNN_ActivityName). Triggers on phrases like "把安卓页面迁移到鸿蒙", "Android UI 转鸿蒙", "批量转 ArkTS", "hmos-ui-align_batch", or any request that supplies an Android project path + Harmony project path + a directory of page snapshots.
+name: hmos-batch-ui-align
+description: Batch-convert multiple Android Activity UI snapshots to HarmonyOS ArkUI (ArkTS) pages. Use when the user wants to migrate Android UI pages to HarmonyOS in bulk, port multiple Activity screens to ArkTS, or run an Android-to-HarmonyOS UI conversion across a folder of page snapshots (page_NNNN_ActivityName). Triggers on phrases like "把安卓页面迁移到鸿蒙", "Android UI 转鸿蒙", "批量转 ArkTS", "hmos-batch-ui-align", or any request that supplies an Android project path + Harmony project path + a directory of page snapshots.
 ---
 
-# hmos-ui-align_batch — Android → HarmonyOS UI Batch Conversion
+# hmos-batch-ui-align — Android → HarmonyOS UI Batch Conversion
 
 Batch-convert a set of Android page snapshots (each snapshot is a `page_NNNN_ActivityName/` directory containing `meta.json` + `view.xml` + optional `screenshot.png`) into HarmonyOS ArkTS pages following MVVM architecture.
 

package/skills/{hmos-ui-align-batch → hmos-batch-ui-align}/references/conversion-procedure.md

@@ -1,6 +1,6 @@
 # Single-Page Android → HarmonyOS UI 转换流程
 
-> 这是 `hmos-ui-align_batch` skill 在每个子 agent 中执行的单页转换流程。基于 `a2h-ui-conversion-new` agent 改写：去掉 Phase 6 build 修复（由父 skill 统一在最后做一次）。
+> 这是 `hmos-batch-ui-align` skill 在每个子 agent 中执行的单页转换流程。基于 `a2h-ui-conversion-new` agent 改写：去掉 Phase 6 build 修复（由父 skill 统一在最后做一次）。
 
 你是一个 **UI Activity 转换器**，专门把单个 Android Activity 的某一页 UI 迁移到 HarmonyOS ArkUI（ArkTS）。
 
@@ -128,7 +128,7 @@ dialog/fragment/adapter 等必须从主页面拆出去到 `{harmony_project_dir}
 
 ## Phase 6 — Build 修复
 
-**跳过**。父 skill `hmos-ui-align_batch` 会在所有页面转换完后统一调用 `hmos_fix_build_errors` 修一次。
+**跳过**。父 skill `hmos-batch-ui-align` 会在所有页面转换完后统一调用 `hmos_fix_build_errors` 修一次。
 
 ## 返回转换报告
 

package/skills/{hmos-ui-align-batch → hmos-batch-ui-align}/references/mappings/android-to-harmonyOS-ui-atomic-component-mapping-reference.md

@@ -2524,11 +2524,9 @@ Column() {
 
 ## 参考链接
 
-1. **Android UI 组件全量清单**: `/docs/android-ui-components-full-list.md`
-2. **HarmonyOS ArkUI 组件全量清单**: `/docs/harmonyos-arkui-components-full-list.md`
-3. **HarmonyOS 开发者文档**: https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/
-4. **Android UI 组件总览**: https://developer.android.com/develop/ui
-5. **Material Design 3 规范**: https://m3.material.io/components
+1. **HarmonyOS 开发者文档**: https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/
+2. **Android UI 组件总览**: https://developer.android.com/develop/ui
+3. **Material Design 3 规范**: https://m3.material.io/components
 
 ---
 

package/skills/{convert_pipeline → hmos-convert-pipeline}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: convert-pipeline
-description: "Run the Android-to-HarmonyOS conversion pipeline — all agents in sequence with progress, duration, and defect tracking. Trigger phrases include 'full Android-to-HarmonyOS pipeline', 'run the conversion pipeline end-to-end', 'convert_pipeline', 'HarmonyOS conversion', or any request to convert an Android project to HarmonyOS with all stages (logic → build → review → fix → rebuild → self-test loop)."
+name: hmos-convert-pipeline
+description: "Run the Android-to-HarmonyOS conversion pipeline — all agents in sequence with progress, duration, and defect tracking. Trigger phrases include 'full Android-to-HarmonyOS pipeline', 'run the conversion pipeline end-to-end', 'hmos-convert-pipeline', 'HarmonyOS conversion', or any request to convert an Android project to HarmonyOS with all stages (logic → build → review → fix → rebuild → self-test loop)."
 ---
 
 # Full Conversion Pipeline
@@ -20,7 +20,7 @@ Parse `$ARGUMENTS` as positional tokens:
 - **Arg 3** (`assets-output-path`): Directory to store all output/report files (required)
 - **Arg 4** (`max-rounds-review`): Maximum number of Stage 3→3a→3b code-review-fix rounds to run (optional, default `2`). Must be a positive integer `>= 1`.
 - **Arg 5** (`max-rounds-test`): Maximum number of Stage 4→4a→4b self-test rounds to run (optional, default `2`). Must be a positive integer `>= 1`.
-- **Arg 6** (`variant`): `enhanced` or `baseline` (optional, default `enhanced`). Selects the Stage 1 / 1a agent family. `enhanced` uses the full `logic-context-builder` + `logic-coding` agents; `baseline` uses the pure-LLM `logic-context-builder-minimal` + `logic-coding-minimal` agents for A/B capability comparison. All other stages and their agents are unchanged. To pass this arg, provide explicit values for Args 4 and 5 first.
+- **Arg 6** (`variant`): `enhanced` or `baseline` (optional, default `enhanced`). Selects the Stage 1 / 1a agent family. `enhanced` uses the full `logic-context-builder` + `logic-coder` agents; `baseline` uses the pure-LLM `logic-context-builder-minimal` + `logic-coding-minimal` agents for A/B capability comparison. All other stages and their agents are unchanged. To pass this arg, provide explicit values for Args 4 and 5 first.
 - **Arg 7** (`skip-test`): `true` or `false` (optional, default `false`). When `true`, skip Stage 4 / 4a / 4b (Self-Testing Loop) entirely. Use this when no real HarmonyOS device is available for on-device testing. To pass this arg, provide explicit values for Args 4, 5, and 6 first.
 
 If any required argument is missing, ask the user before proceeding. If `max-rounds-review` or `max-rounds-test` is provided but is not a positive integer, ask the user before proceeding. If `variant` is provided but is not `enhanced` or `baseline`, ask the user before proceeding. If `skip-test` is provided but is not `true` or `false`, ask the user before proceeding.
@@ -167,7 +167,7 @@ Prompt format (applies to both Stage 1 and Stage 1a): ONLY the key-value lines b
    ```
    # VARIANT=enhanced (default) — full agent
    Agent(
-     subagent_type="logic-coding",
+     subagent_type="logic-coder",
      prompt="harmonyos-project-path: HMOS\nplan-file: OUTPUT/logic/plan.md\noutput-path: OUTPUT/logic"
    )
 

package/skills/hmos-fix-build-errors/SKILL.md

@@ -0,0 +1,265 @@
+---
+name: hmos-fix-build-errors
+description: Build a HarmonyOS project via CLI and automatically fix compile errors in a loop until the build succeeds. Default unsigned HAP; pass --signed to build a signed HAP (signing config must already exist in the project's build-profile.json5).
+argument-hint: <harmonyos-project-path> <deveco-studio-path> [--signed]
+allowed-tools: Agent, Read, Write, Edit, Glob, Grep, Bash
+type: tool
+domain: engineering
+---
+
+# HarmonyOS Auto Build & Fix
+
+Automatically build a HarmonyOS NEXT project from the command line, parse compile errors, fix them, and retry — repeating until the build succeeds.
+
+- **HarmonyOS Project**: `$ARGUMENTS[0]` (the HarmonyOS project root, e.g. `D:/MyHmosApp`)
+- **DevEco Studio Path**: `$ARGUMENTS[1]` (DevEco Studio installation root, e.g. `D:/DevEco Studio`)
+- **--signed** (optional): `$ARGUMENTS[2]` — if set to `--signed`, the build produces a **signed HAP**. If omitted, the build produces an **unsigned HAP** (default).
+
+---
+
+## Step 0: Validate Inputs & Setup Environment
+
+1. **Verify project exists** — Check that `$ARGUMENTS[0]` contains a valid HarmonyOS project (look for `build-profile.json5`, `entry/src` directory, `oh-package.json5`).
+
+2. **Verify DevEco installation** — Check that `$ARGUMENTS[1]` contains:
+   - `tools/node/node.exe`
+   - `tools/hvigor/bin/hvigorw.js`
+   - `tools/ohpm/bin/ohpm`
+   - `sdk/` directory
+
+3. **Set up `local.properties`** — Ensure the project root has `local.properties` with:
+   ```properties
+   hwsdk.dir=<deveco-path>/sdk
+   ```
+   Create it if missing. Use forward slashes in the path.
+
+4. **Run `ohpm install`** — Install dependencies before first build:
+   ```bash
+   cd "<project-dir>"
+   export PATH="<deveco-path>/tools/ohpm/bin:$PATH"
+   "<deveco-path>/tools/ohpm/bin/ohpm" install
+   ```
+
+5. **Determine Build Mode** — Check if `$ARGUMENTS[2]` equals `--signed`:
+   - **If NOT `--signed`** → **Unsigned build mode**. Ensure `build-profile.json5` does NOT have `signingConfigs` or `signingConfig` references in products (remove them if present). Go to Step 1.
+   - **If `--signed`** → **Signed build mode**. Proceed to Step 0.5 to validate signing config.
+
+---
+
+## Step 0.5: Validate Signing Config (Only for --signed Builds)
+
+This step is ONLY executed when `--signed` is specified.
+
+Signing information is read directly from the project's own `build-profile.json5`. The user must have already configured signing in DevEco Studio before running this skill.
+
+### Steps:
+
+1. **Read `build-profile.json5`** in the project root.
+
+2. **Check for `signingConfigs`** — Look for `app.signingConfigs` array in the file.
+   - If `signingConfigs` exists and has at least one entry with valid `material` fields (`certpath`, `storeFile`, `profile`), proceed to step 3.
+   - If `signingConfigs` is missing or empty, **STOP and report to the user**:
+     > Signing configuration not found in `build-profile.json5`.
+     > Please open the project in DevEco Studio, go to **File → Project Structure → Signing Configs**, enable **Automatically generate signature**, then re-run this skill with `--signed`.
+
+3. **Validate signing material files exist** — For the first entry in `signingConfigs`, check that the files referenced by `material.certpath`, `material.storeFile`, and `material.profile` actually exist on disk.
+   - If any file is missing, **STOP and report** which files are missing. Suggest the user re-open DevEco Studio and re-generate the signing config.
+
+4. **Ensure product references signing** — Check that the product entry in `products` array has `"signingConfig": "default"` (or matching the signing config name). Add it if missing.
+
+5. Proceed to Step 1.
+
+---
+
+## Step 1: Build-Fix Loop
+
+Execute the following loop. **Maximum 20 iterations** to prevent infinite loops.
+
+### 1.1 Run CLI Build
+
+**IMPORTANT (Windows)**: On Windows, bash `export PATH` does NOT propagate to Windows native child processes. You **must** use a temporary `.bat` file to set `PATH` and `JAVA_HOME`.
+
+1. **Write a temporary batch file** (e.g. `<project-dir>/build_temp.bat`):
+
+   **For unsigned builds** (no `--signed`):
+   ```bat
+   @echo off
+   set "DEVECO_SDK_HOME=<deveco-path>\sdk"
+   cd /d "<project-dir>"
+   "<deveco-path>\tools\node\node.exe" "<deveco-path>\tools\hvigor\bin\hvigorw.js" assembleHap --mode module -p module=entry --no-daemon
+   ```
+
+   **For signed builds** (`--signed`):
+   ```bat
+   @echo off
+   set "PATH=<deveco-path>\jbr\bin;%PATH%"
+   set "JAVA_HOME=<deveco-path>\jbr"
+   set "DEVECO_SDK_HOME=<deveco-path>\sdk"
+   cd /d "<project-dir>"
+   "<deveco-path>\tools\node\node.exe" "<deveco-path>\tools\hvigor\bin\hvigorw.js" assembleHap --mode module -p module=entry --no-daemon
+   ```
+   Note: Signed builds need `JAVA_HOME` and `jbr\bin` in PATH because the `SignHap` step spawns `java` as a child process.
+
+   Use backslashes (`\`) in paths inside the `.bat` file (Windows convention).
+
+2. **Run the batch file** via `cmd.exe`:
+   ```bash
+   cmd.exe //c "<project-dir>/build_temp.bat" 2>&1
+   ```
+
+3. **Delete the batch file** after the build completes (success or failure).
+
+- Capture the **full output** into a variable.
+- The build command may take 1-3 minutes. Use a timeout of 300000ms (5 minutes).
+
+### 1.2 Check Build Result
+
+- If output contains `BUILD SUCCESSFUL` → **Build succeeded!** Exit the loop, go to Step 2.
+- If output contains `ERROR` or `BUILD FAILED` → Parse errors and continue to 1.3.
+
+### 1.3 Parse Errors
+
+Extract error information from the build output. Errors typically appear in these formats:
+
+```
+ERROR: <file-path>:<line>:<col> - <error-code>: <message>
+```
+
+or
+
+```
+ArkTS:ERROR File: <file-path>:<line>:<col>
+  <error message>
+```
+
+Group errors by file. Focus on **actual errors**, not warnings.
+
+### 1.4 Fix Errors
+
+Read each file that has errors and apply fixes. Use the error reference table below to identify and fix common issues:
+
+| Error Code / Pattern | Message | Fix |
+|---|---|---|
+| `arkts-limited-throw` | "throw statements cannot accept values of arbitrary types" | Change `throw err` to `throw (err instanceof Error) ? err : new Error(String(err))` |
+| `arkts-no-obj-literals-as-types` | "Object literals cannot be used as type declarations" | Define a named `interface` instead of inline `{ key: Type }` |
+| `arkts-no-untyped-obj-literals` | "Object literal must correspond to some explicitly declared class or interface" | Assign to typed variable: `const r: MyInterface = {...}; return r;` |
+| `arkts-no-any-type` / `any` type usage | "Use explicit types instead of any" | Replace `any` with the correct concrete type or `object` |
+| `arkts-no-var` | "Use 'let' or 'const' instead of 'var'" | Replace `var` with `let` or `const` |
+| `10903329` | "Unknown resource name 'xxx'" | Verify resource exists in `resources/base/media/` or `element/*.json`. Use `layered_image` as fallback for missing images. **Special case**: `$r('sys.media.ohos_ic_public_xxx')` references system icons by SDK-specific names that may not exist in the build SDK — replace with `$r('app.media.ic_public_xxx')` and add the icon file to `resources/base/media/` |
+| `10505001` | "Resource[] is not assignable to ResourceColor" | Remove array brackets: `.fontColor($r('app.color.x'))` not `.fontColor([$r('app.color.x')])` |
+| `00303221` | "permission must be a value that is predefined within the SDK" | Remove invalid permission from `module.json5`. See valid permissions list below |
+| Missing import | "Cannot find name 'xxx'" | Add the correct import (see import reference below) |
+| Missing `async` | "await expression requires async function" | Add `async` to the enclosing function |
+| Missing `build()` | "@Component must have build() method" | Add a `build() {}` method to the @Component struct |
+| Type mismatch | Various type errors | Fix the type annotation or cast appropriately |
+| Duplicate identifier | "Duplicate identifier 'xxx'" | Remove or rename the duplicate declaration |
+
+**For errors NOT in the table above**: Read the error message carefully, read the relevant source file, understand the context, and apply an appropriate fix. Use your knowledge of ArkTS/HarmonyOS to determine the correct solution.
+
+### 1.5 Log Progress
+
+After each fix iteration, briefly report:
+- Iteration number
+- Number of errors found
+- Summary of fixes applied
+- Whether re-building
+
+Then go back to **1.1** and rebuild.
+
+---
+
+## Step 2: Build Success Report
+
+When the build succeeds, present a summary:
+
+1. **Build Status**: SUCCESS
+2. **Build Type**: Signed HAP or Unsigned HAP
+3. **Signing** (if signed): Confirm signing config from `build-profile.json5` was used
+4. **Iterations**: How many build-fix cycles were needed
+5. **Total Errors Fixed**: Count of errors fixed across all iterations
+6. **Summary of Changes**: List of files modified and what was fixed in each
+7. **Output HAP Path**:
+   - Signed: `<project>/entry/build/default/outputs/default/entry-default-signed.hap`
+   - Unsigned: `<project>/entry/build/default/outputs/default/entry-default-unsigned.hap`
+
+---
+
+## Reference: Common HarmonyOS Imports
+
+```typescript
+// Network
+import { http } from '@kit.NetworkKit';
+
+// Data persistence
+import { preferences } from '@kit.ArkData';
+import { relationalStore } from '@kit.ArkData';
+
+// UI utilities
+import { router } from '@kit.ArkUI';
+import { promptAction } from '@kit.ArkUI';
+
+// Ability & Context
+import { UIAbility, AbilityConstant, Want } from '@kit.AbilityKit';
+import { common } from '@kit.AbilityKit';
+
+// File I/O
+import { fileIo } from '@kit.CoreFileKit';
+
+// Logging
+import { hilog } from '@kit.PerformanceAnalysisKit';
+
+// JSON parsing — built-in, no import needed
+// ArkUI built-in components (Text, Column, Row, List, Button, Image, etc.) — NO import needed
+```
+
+## Reference: Valid Permission Names
+
+Commonly used SDK-validated permissions for `module.json5`:
+
+- `ohos.permission.INTERNET`
+- `ohos.permission.GET_NETWORK_INFO`
+- `ohos.permission.GET_WIFI_INFO`
+- `ohos.permission.KEEP_BACKGROUND_RUNNING`
+- `ohos.permission.PUBLISH_AGENT_REMINDER`
+- `ohos.permission.CAMERA`
+- `ohos.permission.MICROPHONE`
+- `ohos.permission.APPROXIMATELY_LOCATION`
+- `ohos.permission.LOCATION`
+- `ohos.permission.READ_MEDIA`
+- `ohos.permission.WRITE_MEDIA`
+- `ohos.permission.USE_BLUETOOTH`
+- `ohos.permission.VIBRATE`
+
+**Note**: `ohos.permission.NOTIFICATION` does NOT exist. When in doubt, omit the permission.
+
+## Reference: ArkTS Strict Mode Rules
+
+All code must comply with ArkTS strict mode:
+
+1. **No `any` type** — Use explicit types or `object`
+2. **No `var`** — Only `let` and `const`
+3. **No dynamic property access** — Use typed interfaces instead of `obj['key']` on typed objects
+4. **`throw` must throw Error instances** — Never `throw 'string'` or `throw unknownVar`
+5. **All object literals must match declared interfaces** — No anonymous `{ key: val }` returns without a matching interface
+6. **No inline object literal types** — `function(): { a: string }` is forbidden; define a named `interface`
+7. **All `@Component` structs must have `build()`** — Missing build method is a compile error
+8. **`$r()` resource references validated at compile time** — All referenced resources must exist
+9. **`fontColor()` expects `ResourceColor`**, not `Resource[]` — Don't wrap in array brackets (exception: `SymbolGlyph`)
+10. **Permission names in `module.json5`** — Must be SDK-predefined values
+
+## Important Notes
+
+- **Timeout**: Individual build commands may take up to 5 minutes. Use a 300000ms timeout.
+- **Max iterations**: Stop after 20 iterations to prevent infinite loops. If build still fails after 20 attempts, report the remaining errors to the user.
+- **Don't over-fix**: Only fix errors reported by the compiler. Don't proactively refactor unrelated code.
+- **Read before edit**: Always read a file before modifying it. Understand the surrounding context.
+- **One error can cause many**: A single root-cause fix (like adding a missing interface) may resolve multiple reported errors. After fixing root causes, rebuild to see remaining issues.
+- **ohpm errors**: If the build fails because of missing packages, run `ohpm install` again.
+
+---
+
+## References
+
+- `references/arkts-strict-patterns.md` — ArkTS 严格模式编译错误的确定性修复 Pattern（throw/any/var/interface 等）
+- `references/known-patterns.md` — 已知常见编译错误 Pattern 及修复方案
+- `references/rdb-entity-pattern.md` — RDB 实体类编译错误 Pattern（数据库实体相关）