@buaa_smat/hometrans 0.1.13 → 0.1.15

package/skills/hmos-incremental-ui-align/SKILL.md

@@ -14,38 +14,57 @@ You are writing ArkTS codes.
 - Do not proceed to Step 3 until every page pair has its `UI_comparison.md` written in Step 2
 - Step 2 MUST be executed by the main agent sequentially (not delegated to background agents). Each sub-step (2.1 → 2.2 → 2.3) must complete and be verified before the next begins.
 - If mock data is required, write them in `{harmony_project_dir}/entry/src/main/ets/model/` according to the hmos MVVM mode.
-- 不要做和用户需求无关的其他修改
-- 
-## Step 0: Load Config
-Resolve the config file in this order — stop at the first hit:
+- Do not make any other changes unrelated to the user's requirements.
 
-1. **`config-path` argument** if the user provided one (e.g., `config-path: D:\path\to\config.json`).
-2. **`config.json` in this skill's own directory** — `ht init` seeds it from `config-example.json` and fills `glm_api_key` + `hmos_sdk_dir` from `~/.hometrans/config.json`.
-3. Neither exists → **ask the user** for a valid path.
+## Step 0: Resolve Inputs
 
-Verify the resolved file with a Read; if it's missing or unreadable, fall through to the next source (or ask the user). Refer to `config-example.json` in this skill's directory for the expected schema.
+This skill takes three path inputs from the invocation and reads its other settings **directly from the OS environment variables**.
 
-Config fields:
+### Skill input arguments (provided by the user when invoking the skill)
 
-| Field | Description |
-|---|---|
-| `android.app_name` | Android app name for navigation |
-| `android.package` | Android app package name |
-| `android.project_dir` | Android source code root path |
-| `harmony.app_name` | HarmonyOS app name for navigation |
-| `harmony.package` | HarmonyOS app package name |
-| `harmony.project_dir` | HarmonyOS project root path |
-| `hmos_sdk_dir` | HarmonyOS SDK path (ETS API reference) |
-| `glm_api_key` | Zhipu GLM API key for phone-agent |
-| `capture_output_dir` | Base directory for captured page data |
+| Argument | Required | Description |
+|---|---|---|
+| `android_project_dir` | yes | Android source code root path |
+| `harmony_project_dir` | yes | HarmonyOS project root path (will be modified) |
+| `capture_output_dir` | no | Base dir for captured page data (screenshots / view trees / analysis). Default: `<harmony_project_dir>/.hometrans/capture_output` under the current working directory |
 
-**Fallbacks for `hmos_sdk_dir` and `glm_api_key`** when empty or missing in the resolved config — stop at the first hit:
+The user may pass them as named args (e.g. `android_project_dir: D:\path\to\android`) or describe them in the request. If `android_project_dir` or `harmony_project_dir` cannot be determined from the invocation, **ask the user** before proceeding.
 
-1. `~/.hometrans/config.json` (on Windows `%USERPROFILE%\.hometrans\config.json`): `hmos_sdk_dir` = `<env.DEVECO_SDK_HOME>/default`; `glm_api_key` = `env.GLM_API_KEY`.
-2. Environment variables: derive `hmos_sdk_dir` from `DEVECO_SDK_HOME` (append `/default`); `glm_api_key` from `GLM_API_KEY`.
-3. **Ask the user** (suggest running `ht init` to persist them).
+### Step 0.0: Environment Variables Check (run first)
 
-Validate that `hmos_sdk_dir` exists on disk before use; if it doesn't, continue down the fallback list.
+Read each variable below **directly from the OS environment** (`echo "$VAR"` on macOS/Linux; `$env:VAR` in PowerShell / `echo %VAR%` in cmd on Windows).
+
+| Variable | Purpose | Valid when |
+|---|---|---|
+| `GLM_API_KEY` | Zhipu GLM key for the phone-agent (Step 1 navigation) | non-empty |
+| `OHOS_SDK_PATH` | HarmonyOS SDK ETS API reference (Step 3) | path exists on disk |
+| `HMS_SDK_PATH` | HMS SDK ETS API reference (Step 3) | path exists on disk |
+
+For `OHOS_SDK_PATH` / `HMS_SDK_PATH`, if unset but `DEVECO_SDK_HOME` is set, derive them as `<DEVECO_SDK_HOME>/default/openharmony/ets` and `<DEVECO_SDK_HOME>/default/hms/ets`.
+
+For each variable that is still missing/empty (or a path that does not exist), **stop and ask the user to provide a value**, then use what they give for this run. Suggest running `ht init` to persist them as machine environment variables for next time.
+
+### Step 0.1: Auto-derive App Names & Package Names
+
+`android.app_name` / `android.package` / `harmony.app_name` / `harmony.package` are required for navigation (passed to `scripts/app_feature_verify.py` as `--app` / `--package`). They are not provided as inputs — resolve them from the project dirs (`android_project_dir` / `harmony_project_dir`) as follows.
+
+**`app_name` matters because it is the launcher label phone-agent taps to open the app** — when the resolved label is a localized resource and a Chinese (`zh`) variant exists, prefer the Chinese value (devices are typically zh-CN).
+
+#### Android (from `android_project_dir`)
+1. **`android.package`** — locate the application module (the module whose Gradle file applies `com.android.application`, usually `app/`):
+   - Read `applicationId` from `{module}/build.gradle` (Groovy: `applicationId "com.x"`) or `build.gradle.kts` (Kotlin DSL: `applicationId = "com.x"`). Use the default/base `applicationId`; ignore flavor-specific `applicationIdSuffix`.
+   - Fallback: the `package="..."` attribute in `{module}/src/main/AndroidManifest.xml`.
+2. **`android.app_name`** — in `{module}/src/main/AndroidManifest.xml`, read `android:label`. Prefer the launcher `<activity>` label (the activity whose `<intent-filter>` has `android.intent.action.MAIN` + `android.intent.category.LAUNCHER`); if it has none, use the `<application>` label.
+   - If the label is a literal string, use it directly.
+   - If it is `@string/<name>`, resolve `<name>` in the string resources: prefer a Chinese variant (`{module}/src/main/res/values-zh-rCN/strings.xml`, else `values-zh/strings.xml`), falling back to the default `values/strings.xml`. Use the matching `<string name="<name>">…</string>` value.
+
+#### HarmonyOS (from `harmony_project_dir`)
+1. **`harmony.package`** — read `app.bundleName` from `{harmony_project_dir}/AppScope/app.json5`.
+2. **`harmony.app_name`** — read `app.label` from `{harmony_project_dir}/AppScope/app.json5`.
+   - If it is a literal string, use it directly.
+   - If it is `$string:<name>`, resolve `<name>`: prefer a Chinese element dir (`{harmony_project_dir}/AppScope/resources/zh_CN/element/string.json`, else `zh/element/string.json`), falling back to `base/element/string.json`. Find the entry in `string[]` whose `name` equals `<name>` and use its `value`.
+
+After resolving all four, briefly echo them to the user (e.g. `android.app_name="…", android.package="…", harmony.app_name="…", harmony.package="…"`) before starting Step 1. If any value cannot be resolved from the project dir, ask the user to supply it.
 
 ## Step 1: Capture All Related Pages on Android & HarmonyOS Devices
 
@@ -119,7 +138,7 @@ For each page  <`android_page_{i}_{name}`,`hmos_page_{i}_{name}`> collected in {
     Read `hmos_page_{i}_{name}` 目录下的 screenshot 和 view tree 信息，以 table 形式列举出该页面所有组件，每个组件包含位置、颜色、icon、大小、形状、文字内容、alignment(居中、靠左、靠右等)等一切视觉要素。
     **MANDATORY OUTPUT**:  following the template `references/UI_Analysis_Template.md` to Write the result to `hmos_page_{i}_{name}/UI_Analysis.md`，写完后确认文件已创建。
  if `hmos_page_{i}_{name}` is empty (no screenshots/view trees captured):
-    Read the HarmonyOS source code at `harmony.project_dir` to find the corresponding page implementation. Analyze the source code to extract all UI components, their properties, layout structure, colors, dimensions, and text content. Create a comprehensive component table from the code analysis.
+    Read the HarmonyOS source code at `harmony_project_dir` to find the corresponding page implementation. Analyze the source code to extract all UI components, their properties, layout structure, colors, dimensions, and text content. Create a comprehensive component table from the code analysis.
     **MANDATORY OUTPUT**:  following the template `references/UI_Analysis_Template.md` to Write the result to `hmos_page_{i}_{name}/UI_Analysis_from_code.md`，写完后确认文件已创建。
     **DO NOT** write a placeholder like "page not captured" — you must actually read the source code and produce a real analysis.
 ### Step 2.3 Make UI Diff Analysis and Write the Comparison Table
@@ -197,4 +216,4 @@ if available, use `hmos-fix-build-errors` skill to verify the project is compila
 - Handle responsive layouts: prefer percentage widths and `Flex` over fixed dimensions where appropriate.
 - Maintain accessibility: convert `content-desc` to `.accessibilityText()`, convert meaningful `text` to proper labels.
 - Group related UI into `@Component` sub-components when the hierarchy is deep (> 5 nesting levels).
-- **鸿蒙 API 可参考 `{hmos_sdk_dir}`, 鸿蒙MVVM开发模式可参考`./references/MVVM开发文档/`**
+- **鸿蒙 API 可参考 `OHOS_SDK_PATH` / `HMS_SDK_PATH`（HarmonyOS SDK 的 ETS 目录，取自 OS 环境变量），鸿蒙MVVM开发模式可参考`./references/MVVM开发文档/`**

package/skills/hmos-incremental-ui-align/diff_analysis.md

@@ -1,53 +1,53 @@
-### Diff Analysis 
-use `{android_page_info}`, `{hmos_page_info}`,`{android_project_dir}`,`{harmony_project_dir}` to make a detailed comparison on visual effects
-
-#### Step 1: Parse Android View Hierarchy
-
-Read `{android_page_info}/view.xml` and build a structural understanding:
-- Parse the XML node tree to understand the full view hierarchy
-- Identify the key structural containers (root layouts, toolbar, content area, bottom navigation)
-- Map each Android widget node to its attributes: `class`, `resource-id`, `text`, `content-desc`, `bounds`, `clickable`, `scrollable`, `checkable`, `checked`, `enabled`
-- Calculate layout relationships from `bounds` (parent-child containment, sibling positioning)
-- Identify recurring patterns (list items, grid items, card layouts)
-
-If there exist `view_scroll_n.xml` files (n = 1, 2, 3, ...), read each one and merge their structural understanding with `view.xml` (the Android UI is longer than one screen).
-
-Read the Android `screenshot.png` (and `screenshot_scroll_n.png` if they exist) to visually understand the target UI.
-
-Additionally, find and read the static XML layout files and Kotlin/Java code files in `{android_project_dir}` that correspond to this page. Use atomic Android components to replace user-defined and third-party components, building a **final Android structural understanding**.
-
-
-#### Step 2: Parse HarmonyOS Current State
-
-Read the HarmonyOS view tree XML and screenshot from `{hmos_page_info}/`:
-- Parse the HarmonyOS view hierarchy to understand the current UI structure
-- Read the screenshot to visually understand the current state
-
-Also read the corresponding `.ets` source file(s) in `{harmony_project_dir}` for this page:
-- Identify the existing component structure, state variables, child components
-- Understand how the page is currently implemented
-
-Build a **current HarmonyOS structural understanding**.
-
-#### Step 3: Diff Analysis 
-
-Compare the Android final structural understanding (Step 4.1) against the HarmonyOS current structural understanding (Step 4.2):
-Android pages and Harmony pages may be running on different devices, so be robust to the differences caused by devices (e.g., 组件间的间距、截图上显示的颜色等等)
-
-1. **Structural diff**:
-   - Missing pages/components (in Android but not in HarmonyOS)
-   - Extra pages/components (in HarmonyOS but not in Android)
-   - Wrong nesting / layout structure differences
-   - Incorrect component type mappings
-
-2. **Visual diff**:
-   - Color mismatches (background, foreground, fill)
-   - Size / spacing differences
-   - Position / alignment issues 
-   - Shape mismatches (rounded corners, borders)
-   - Text content or font differences
-   - Icon / image mismatches
-
-3. **Interaction diff** — compare clickable elements, navigation targets, gestures
-
+### Diff Analysis 
+use `{android_page_info}`, `{hmos_page_info}`,`{android_project_dir}`,`{harmony_project_dir}` to make a detailed comparison on visual effects
+
+#### Step 1: Parse Android View Hierarchy
+
+Read `{android_page_info}/view.xml` and build a structural understanding:
+- Parse the XML node tree to understand the full view hierarchy
+- Identify the key structural containers (root layouts, toolbar, content area, bottom navigation)
+- Map each Android widget node to its attributes: `class`, `resource-id`, `text`, `content-desc`, `bounds`, `clickable`, `scrollable`, `checkable`, `checked`, `enabled`
+- Calculate layout relationships from `bounds` (parent-child containment, sibling positioning)
+- Identify recurring patterns (list items, grid items, card layouts)
+
+If there exist `view_scroll_n.xml` files (n = 1, 2, 3, ...), read each one and merge their structural understanding with `view.xml` (the Android UI is longer than one screen).
+
+Read the Android `screenshot.png` (and `screenshot_scroll_n.png` if they exist) to visually understand the target UI.
+
+Additionally, find and read the static XML layout files and Kotlin/Java code files in `{android_project_dir}` that correspond to this page. Use atomic Android components to replace user-defined and third-party components, building a **final Android structural understanding**.
+
+
+#### Step 2: Parse HarmonyOS Current State
+
+Read the HarmonyOS view tree XML and screenshot from `{hmos_page_info}/`:
+- Parse the HarmonyOS view hierarchy to understand the current UI structure
+- Read the screenshot to visually understand the current state
+
+Also read the corresponding `.ets` source file(s) in `{harmony_project_dir}` for this page:
+- Identify the existing component structure, state variables, child components
+- Understand how the page is currently implemented
+
+Build a **current HarmonyOS structural understanding**.
+
+#### Step 3: Diff Analysis 
+
+Compare the Android final structural understanding (Step 4.1) against the HarmonyOS current structural understanding (Step 4.2):
+Android pages and Harmony pages may be running on different devices, so be robust to the differences caused by devices (e.g., 组件间的间距、截图上显示的颜色等等)
+
+1. **Structural diff**:
+   - Missing pages/components (in Android but not in HarmonyOS)
+   - Extra pages/components (in HarmonyOS but not in Android)
+   - Wrong nesting / layout structure differences
+   - Incorrect component type mappings
+
+2. **Visual diff**:
+   - Color mismatches (background, foreground, fill)
+   - Size / spacing differences
+   - Position / alignment issues 
+   - Shape mismatches (rounded corners, borders)
+   - Text content or font differences
+   - Icon / image mismatches
+
+3. **Interaction diff** — compare clickable elements, navigation targets, gestures
+
 Return a diff analysis report which lists all diffs

package/skills/hmos-incremental-ui-align/page_align.md

@@ -1,62 +1,62 @@
-# Page Align Insruction
-
-Based on the diff analysis, flexibly combine editing and creation as needed — a single page may require both aligning existing code and adding new components/files:
-
-**For existing files that need alignment:**
-- Read the existing `.ets` file(s) for this page
-- For each discrepancy identified in the diff, make **targeted edits** using the Edit tool:
-  - Fix layout structure mismatches (wrong container type, missing nesting)
-  - Add missing components
-  - Remove extra components that don't exist in the Android UI
-  - Fix styling (colors, sizes, spacing, shapes)
-  - Fix resource references to use correct `$r('app.xxx.yyy')`
-
-**For new files that need to be created** (new pages, new sub-components, new viewmodels/models):
-- Generate new `.ets` files following the conventions discovered in Phase 1:
-  - Use the same import patterns as existing pages
-  - Use the same state management patterns
-  - Reuse existing shared components from `components/`
-  - Reuse or extend existing viewmodels/models
-  - Follow the same naming conventions
-- Write page files to `{harmony_project_dir}/entry/src/main/ets/pages/`
-- Write component files to `{harmony_project_dir}/entry/src/main/ets/components/`
-- Write viewmodel files to `{harmony_project_dir}/entry/src/main/ets/viewmodel/`
-- Write model files to `{harmony_project_dir}/entry/src/main/ets/model/`
-- Register any new page in the router configuration
-
-## For all changes, apply these conversion rules:
-
-**Resource Conversion:**
-- For each resource referenced by the Android UI, find the corresponding mapping in `{harmony_project_dir}/entry/src/main/resources`
-- If a needed resource does not exist, use the **`hmos-resources-convert`** skill to convert it
-
-**Layout Conversion:**
-- Consult `./references/android-to-harmonyOS-ui-layout-mapping-reference.md` for all layout container mappings and layout attribute mappings
-- Apply the layout property mappings (e.g., `layout_weight` → `.layoutWeight()`, `padding` → `.padding()`, visibility handling, etc.)
-
-**Widget Conversion:**
-- Consult `./references/android-to-harmonyOS-ui-atomic-component-mapping-reference.md` for all atomic widget mappings
-- Apply the detailed attribute-level mappings for each component
-
-**Interaction Conversion:**
-- Consult `./references/android-to-harmonyOS-ui-interaction-mapping-reference.md` for all event and gesture mappings
-- Apply touch event mappings, click event mappings, gesture mappings, and animation mappings
-
-**Always consult the reference files first** — they contain project-specific and comprehensive mappings that take priority over built-in knowledge.
-
-**Styling Conversion:**
-- Android `dp` → HarmonyOS `vp`
-- Android `sp` → HarmonyOS `fp`
-- Calculate dimensions from `bounds` in the XML: `width = x2 - x1`, `height = y2 - y1`
-- Convert absolute pixel values to `vp` using the device density (assume 3x density: `1vp ≈ 3px`)
-- Use `$r('app.color.xxx')` for colors when available in the resource list
-- Use `$r('app.string.xxx')` for text strings when available in the resource list
-- Use `$r('app.media.xxx')` for images when available in the resource list
-
-**Router Conversion:**
-- Convert router relationships among UIs and components
-- Register new page routes in the router configuration when new pages are created
-- Fix any incorrect router targets in existing pages
-
-**Interactive Elements:**
-- **Prefer real implementation over mocking**: before mocking any click event, navigation jump, or interaction, first check whether the target component or page already exists in the HarmonyOS project. If the target is already implemented, wire up the real event handler (e.g., actual `router.pushUrl()` with the correct page path). **Only mock when the related component or page has not yet been implemented** — in that case, use placeholder implementations to ensure the program compiles (e.g., `console.info('TODO: navigate to SettingsActivity — target page not yet implemented')`)
+# Page Align Insruction
+
+Based on the diff analysis, flexibly combine editing and creation as needed — a single page may require both aligning existing code and adding new components/files:
+
+**For existing files that need alignment:**
+- Read the existing `.ets` file(s) for this page
+- For each discrepancy identified in the diff, make **targeted edits** using the Edit tool:
+  - Fix layout structure mismatches (wrong container type, missing nesting)
+  - Add missing components
+  - Remove extra components that don't exist in the Android UI
+  - Fix styling (colors, sizes, spacing, shapes)
+  - Fix resource references to use correct `$r('app.xxx.yyy')`
+
+**For new files that need to be created** (new pages, new sub-components, new viewmodels/models):
+- Generate new `.ets` files following the conventions discovered in Phase 1:
+  - Use the same import patterns as existing pages
+  - Use the same state management patterns
+  - Reuse existing shared components from `components/`
+  - Reuse or extend existing viewmodels/models
+  - Follow the same naming conventions
+- Write page files to `{harmony_project_dir}/entry/src/main/ets/pages/`
+- Write component files to `{harmony_project_dir}/entry/src/main/ets/components/`
+- Write viewmodel files to `{harmony_project_dir}/entry/src/main/ets/viewmodel/`
+- Write model files to `{harmony_project_dir}/entry/src/main/ets/model/`
+- Register any new page in the router configuration
+
+## For all changes, apply these conversion rules:
+
+**Resource Conversion:**
+- For each resource referenced by the Android UI, find the corresponding mapping in `{harmony_project_dir}/entry/src/main/resources`
+- If a needed resource does not exist, use the **`hmos-resources-convert`** skill to convert it
+
+**Layout Conversion:**
+- Consult `./references/android-to-harmonyOS-ui-layout-mapping-reference.md` for all layout container mappings and layout attribute mappings
+- Apply the layout property mappings (e.g., `layout_weight` → `.layoutWeight()`, `padding` → `.padding()`, visibility handling, etc.)
+
+**Widget Conversion:**
+- Consult `./references/android-to-harmonyOS-ui-atomic-component-mapping-reference.md` for all atomic widget mappings
+- Apply the detailed attribute-level mappings for each component
+
+**Interaction Conversion:**
+- Consult `./references/android-to-harmonyOS-ui-interaction-mapping-reference.md` for all event and gesture mappings
+- Apply touch event mappings, click event mappings, gesture mappings, and animation mappings
+
+**Always consult the reference files first** — they contain project-specific and comprehensive mappings that take priority over built-in knowledge.
+
+**Styling Conversion:**
+- Android `dp` → HarmonyOS `vp`
+- Android `sp` → HarmonyOS `fp`
+- Calculate dimensions from `bounds` in the XML: `width = x2 - x1`, `height = y2 - y1`
+- Convert absolute pixel values to `vp` using the device density (assume 3x density: `1vp ≈ 3px`)
+- Use `$r('app.color.xxx')` for colors when available in the resource list
+- Use `$r('app.string.xxx')` for text strings when available in the resource list
+- Use `$r('app.media.xxx')` for images when available in the resource list
+
+**Router Conversion:**
+- Convert router relationships among UIs and components
+- Register new page routes in the router configuration when new pages are created
+- Fix any incorrect router targets in existing pages
+
+**Interactive Elements:**
+- **Prefer real implementation over mocking**: before mocking any click event, navigation jump, or interaction, first check whether the target component or page already exists in the HarmonyOS project. If the target is already implemented, wire up the real event handler (e.g., actual `router.pushUrl()` with the correct page path). **Only mock when the related component or page has not yet been implemented** — in that case, use placeholder implementations to ensure the program compiles (e.g., `console.info('TODO: navigate to SettingsActivity — target page not yet implemented')`)

package/skills/hmos-incremental-ui-align/references/Comparison_Template.md

@@ -1,2 +1,2 @@
-| UI Component | 文本内容 | 尺寸与布局 | 颜色与背景 | 边框与轮廓 | 文本样式 | 变换与效果 | 状态与交互反馈 | Diff |
-|:-------------|:-----|:------|:------|:------|:-----|:------|:--------|:--------|
+| UI Component | 文本内容 | 尺寸与布局 | 颜色与背景 | 边框与轮廓 | 文本样式 | 变换与效果 | 状态与交互反馈 | Diff |
+|:-------------|:-----|:------|:------|:------|:-----|:------|:--------|:--------|