@buaa_smat/hometrans 0.1.5 → 0.1.7

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

@@ -13,13 +13,111 @@ npm install -g @buaa_smat/hometrans
 ht init
 ```
 
-One-shot via `npx` (no global install required):
+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.
+
+---
+
+## HarmonyOS Migration Guide
+
+鸿蒙软件迁移指导，提供完整的 Android 到 HarmonyOS 迁移流程：
+
+### Step 1: Resource Conversion (资源转换)
+
+> `hmos-batch-ui-align` 内部会自动调用资源转换；如果是批量UI迁移场景则可跳过此步骤。
+
+将 Android 资源文件（图片、字符串、颜色、尺寸等）转换为 HarmonyOS 格式。
 
-```bash
-npx hometrans init
+```
+/hmos-resources-convert android-project-path=<安卓项目路径> harmonyos-project-path=<鸿蒙项目路径> resource_mapping_path=<资源映射文档路径>
 ```
 
-Requires Node.js **>= 18**.
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `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`） |
+| `variant` | 可选 | `enhanced`（默认，全功能 agent）或 `baseline`（纯 LLM baseline agent） |
+| `skip-test` | 可选 | `true` 跳过集成测试阶段（无真机验证环境时需要设置为true，默认 `false`） |
 
 ---
 
@@ -66,56 +164,16 @@ Requires Node.js **>= 18**.
 
 ---
 
-## What `ht mcp` does
-
-Starts a stdio-mode MCP server exposing the following tool:
-
-### `extract_commit_context`
-
-Extracts code context index from a given git commit in a HarmonyOS project (git diff + ArkTS semantic dependency analysis), for use during AI-assisted Android-to-HarmonyOS code review.
-
-**Input parameters:**
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `projectPath` | string | Yes | Absolute path to HarmonyOS project root (must contain `.git`) |
-| `commitId` | string | Yes | Git commit ID (diffs against its first parent) |
-| `mode` | string | No | `"default"` builds full call graph; other values skip (default: `"default"`) |
-| `ohosSdkPath` | string | No | OpenHarmony SDK ETS path; falls back to env var `OHOS_SDK_PATH` |
-| `hmsSdkPath` | string | No | HMS SDK ETS path; falls back to env var `HMS_SDK_PATH` |
-
-**Output:** `{path, kind, ranges?, resourceNames?}[]`
-- `source` files: 1-based `[start, end]` line-range arrays
-- `resource` files: list of referenced resource names
-
----
-
 ## Skills
 
-| 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-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 |
-
-### `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
-3. `assets-output-path` (required): directory for output/report files
-4. `max-rounds-review` (optional, default `2`): max Code Review → Fix loop rounds
-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
-
-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)
-3. `spec-output-dir` (required): absolute path to the directory where spec files will be written
+| 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), `variant` (optional, default enhanced), `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"` |
 
 ---
 
@@ -124,10 +182,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 |
 | `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) |
@@ -135,7 +192,7 @@ Extracts code context index from a given git commit in a HarmonyOS project (git
 
 ---
 
-MIT
+
 
 <p align="center">
 <a href="https://gitcode.com/SMAT/HomeTrans">Official Repository</a> •

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buaa_smat/hometrans",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "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（数据库实体相关）