@buaa_smat/hometrans 0.1.14 → 0.1.16

package/resource/migration_process_transparent.svg

@@ -0,0 +1,93 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1120 1080" width="1120" height="1080">
+  <style>
+    text { font-family: 'Helvetica Neue', Helvetica, Arial, 'PingFang SC', 'Microsoft YaHei', 'Microsoft JhengHei', 'SimHei', sans-serif; }
+    .title { font-size: 20px; font-weight: 600; fill: #111827; }
+    .sub   { font-size: 12px; fill: #6b7280; }
+    .banner{ font-size: 12px; fill: #047857; font-weight: 600; }
+    .nt    { font-size: 14px; font-weight: 600; fill: #111827; }
+    .ns    { font-size: 11px; fill: #6b7280; }
+    .pin   { font-size: 11px; fill: #1d4ed8; }
+    .pout  { font-size: 11px; fill: #047857; }
+    .dlab  { font-size: 11px; font-weight: 600; fill: #047857; }
+    .lg    { font-size: 12px; fill: #374151; }
+  </style>
+  <defs>
+    <marker id="arrow" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+      <polygon points="0 0, 10 3.5, 0 7" fill="#2563eb"/>
+    </marker>
+    <marker id="arrowg" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+      <polygon points="0 0, 10 3.5, 0 7" fill="#059669"/>
+    </marker>
+  </defs>
+  <text x="40" y="40" class="title">Android → HarmonyOS 迁移流程 · 含参数传递</text>
+  <text x="40" y="62" class="sub">蓝箭头=执行顺序；绿色=参数/产物传递；橙色框=人工介入</text>
+  <rect x="280" y="70" width="560" height="44" rx="8" fill="#ecfdf5" stroke="#10b981" stroke-width="1.4" stroke-dasharray="6,4"/>
+  <text x="560" y="90" text-anchor="middle" class="banner">公共入参（所有步骤共享）：android_project_dir · harmony_project_dir</text>
+  <text x="560" y="106" text-anchor="middle" class="banner">步骤2 产物写入 harmony_project_dir，步骤4 据此构建</text>
+  <rect x="340" y="140" width="440" height="50" rx="25.0" fill="#f0fdf4" stroke="#16a34a" stroke-width="1.6"/>
+  <text x="560" y="170" text-anchor="middle" class="nt">开始：准备 Android 源项目 + 鸿蒙目标项目</text>
+  <rect x="100" y="292" width="440" height="96" rx="9" fill="#eff6ff" stroke="#2563eb" stroke-width="1.6"/>
+  <text x="320" y="310" text-anchor="middle" class="nt">步骤1.1 UI 迁移</text>
+  <text x="320" y="328" text-anchor="middle" class="ns">skill:hmos-batch-ui-align</text>
+  <text x="320" y="348" text-anchor="middle" class="pin">入参: 公共入参 + [ui_info_root, pages]</text>
+  <text x="320" y="367" text-anchor="middle" class="pout">出参: ArkTS页面 + 资源(含资源转换) + 批量报告</text>
+  <rect x="580" y="292" width="440" height="96" rx="9" fill="#f5f9ff" stroke="#2563eb" stroke-width="1.6" stroke-dasharray="6,4"/>
+  <text x="800" y="310" text-anchor="middle" class="nt">步骤1.2 UI 对齐</text>
+  <text x="800" y="328" text-anchor="middle" class="ns">skill:hmos-incremental-ui-align</text>
+  <text x="800" y="348" text-anchor="middle" class="pin">入参: 公共入参 + [capture_output_dir]</text>
+  <text x="800" y="367" text-anchor="middle" class="pout">出参: 修改后ArkTS页面 + 双端截图/视图树 + 对齐报告</text>
+  <rect x="330" y="448" width="460" height="64" rx="9" fill="#fff7ed" stroke="#ea580c" stroke-width="1.6"/>
+  <circle cx="354.0" cy="473" r="4.5" fill="#ea580c"/>
+  <path d="M 347.0,488 Q 354.0,479 361.0,488" fill="none" stroke="#ea580c" stroke-width="2.2" stroke-linecap="round"/>
+  <text x="574" y="472" text-anchor="middle" class="nt">编写 REQ.txt（需求描述）</text>
+  <text x="574" y="492" text-anchor="middle" class="ns">使用自然语言描述原始需求，用空行分隔多个需求</text>
+  <text x="574" y="509" text-anchor="middle" class="pout">产出: REQ.txt</text>
+  <rect x="310" y="562" width="500" height="96" rx="9" fill="#eff6ff" stroke="#2563eb" stroke-width="1.6"/>
+  <text x="560" y="580" text-anchor="middle" class="nt">步骤2 生成需求规格</text>
+  <text x="560" y="598" text-anchor="middle" class="ns">skill:hmos-spec-generate</text>
+  <text x="560" y="618" text-anchor="middle" class="pin">入参: 公共入参 + requirement_description_file(=REQ.txt) + spec_output_dir</text>
+  <text x="560" y="637" text-anchor="middle" class="pout">出参: 〈feature〉-SPEC.md + .trace/〈feature〉.md</text>
+  <rect x="310" y="710" width="500" height="80" rx="9" fill="#fff7ed" stroke="#ea580c" stroke-width="1.6"/>
+  <circle cx="334.0" cy="743" r="4.5" fill="#ea580c"/>
+  <path d="M 327.0,758 Q 334.0,749 341.0,758" fill="none" stroke="#ea580c" stroke-width="2.2" stroke-linecap="round"/>
+  <text x="574" y="734" text-anchor="middle" class="nt">编写测试用例 + 连鸿蒙真机 / 配置签名</text>
+  <text x="574" y="754" text-anchor="middle" class="ns">如果不执行步骤4中的集成测试（skip_test=true）可跳过此步骤</text>
+  <text x="574" y="771" text-anchor="middle" class="pout">产出: test_case.md / pre_test_case.md</text>
+  <rect x="300" y="842" width="520" height="96" rx="9" fill="#eff6ff" stroke="#2563eb" stroke-width="1.6"/>
+  <text x="560" y="860" text-anchor="middle" class="nt">步骤3 逻辑代码转换流水线</text>
+  <text x="560" y="878" text-anchor="middle" class="ns">skill:hmos-convert-pipeline</text>
+  <text x="560" y="898" text-anchor="middle" class="pin">入参: 公共入参 + spec_file_path(=SPEC.md) + [test_case_path, pre_test_case_path, skip_test …]</text>
+  <text x="560" y="917" text-anchor="middle" class="pout">出参: 已签名HAP + pipeline-manifest.md + 各阶段报告</text>
+  <rect x="400" y="983" width="320" height="54" rx="9" fill="#ede9fe" stroke="#7c3aed" stroke-width="1.6"/>
+  <text x="560" y="1015" text-anchor="middle" class="nt">产物：已签名 HAP</text>
+  <path d="M560,190 V250 H320 V292" fill="none" stroke="#2563eb" stroke-width="1.6" marker-end="url(#arrow)"/>
+  <path d="M560,190 V250 H800 V292" fill="none" stroke="#2563eb" stroke-width="1.6" marker-end="url(#arrow)"/>
+  <path d="M320,388 V418 H558 V448" fill="none" stroke="#2563eb" stroke-width="1.6" marker-end="url(#arrow)"/>
+  <path d="M800,388 V418 H562 V448" fill="none" stroke="#2563eb" stroke-width="1.6" marker-end="url(#arrow)"/>
+  <path d="M560,512 V562" fill="none" stroke="#2563eb" stroke-width="1.6" marker-end="url(#arrow)"/>
+  <path d="M560,658 V710" fill="none" stroke="#2563eb" stroke-width="1.6" marker-end="url(#arrow)"/>
+  <path d="M560,790 V842" fill="none" stroke="#2563eb" stroke-width="1.6" marker-end="url(#arrow)"/>
+  <path d="M560,938 V983" fill="none" stroke="#2563eb" stroke-width="1.6" marker-end="url(#arrow)"/>
+  <path d="M810,610 H865 V890 H822" fill="none" stroke="#059669" stroke-width="1.6" stroke-dasharray="6,4" marker-end="url(#arrowg)"/>
+  <rect x="415" y="528" width="290" height="16" rx="3" fill="#ffffff" opacity="0.92"/>
+  <text x="560" y="540" text-anchor="middle" class="dlab">REQ.txt ⇒ requirement_description_file</text>
+  <rect x="445" y="797" width="230" height="16" rx="3" fill="#ffffff" opacity="0.92"/>
+  <text x="560" y="809" text-anchor="middle" class="dlab">test_case.md ⇒ test_case_path</text>
+  <rect x="415" y="815" width="290" height="16" rx="3" fill="#ffffff" opacity="0.92"/>
+  <text x="560" y="827" text-anchor="middle" class="dlab">pre_test_case.md ⇒ pre_test_case_path</text>
+  <rect x="440" y="949" width="240" height="16" rx="3" fill="#ffffff" opacity="0.92"/>
+  <text x="560" y="961" text-anchor="middle" class="dlab">已签名HAP · pipeline-manifest.md</text>
+  <text x="872" y="745" class="dlab">〈feature〉-SPEC.md ⇒ spec_file_path</text>
+  <g transform="translate(40,920)">
+    <line x1="0" y1="6" x2="26" y2="6" stroke="#2563eb" stroke-width="1.6" marker-end="url(#arrow)"/>
+    <text x="34" y="10" class="lg">执行顺序</text>
+    <line x1="0" y1="26" x2="26" y2="26" stroke="#059669" stroke-width="1.6" stroke-dasharray="6,4" marker-end="url(#arrowg)"/>
+    <text x="34" y="30" class="lg">参数 / 产物传递</text>
+    <rect x="0" y="42" width="20" height="14" rx="3" fill="#eff6ff" stroke="#2563eb" stroke-width="1.4"/>
+    <text x="34" y="53" class="lg">自动化步骤（skill）</text>
+    <rect x="0" y="64" width="20" height="14" rx="3" fill="#fff7ed" stroke="#ea580c" stroke-width="1.4"/>
+    <text x="34" y="75" class="lg">人工介入</text>
+    <rect x="0" y="86" width="20" height="14" rx="3" fill="#f5f9ff" stroke="#2563eb" stroke-width="1.4" stroke-dasharray="6,4"/>
+    <text x="34" y="97" class="lg">可选 / 按需</text>
+  </g>
+</svg>

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

@@ -1,109 +1,109 @@
----
-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-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.
-
-## Step 0 — Environment Variables Check (run first)
-
-The final build (Step 6, via `hmos_fix_build_errors`) reads the DevEco location **directly from the OS environment variables** (`echo "$VAR"` on macOS/Linux; `$env:VAR` in PowerShell on Windows):
-
-| Variable | Needed for | Valid when |
-|---|---|---|
-| `DEVECO_HOME` *(or `DEVECO_SDK_HOME`)* | Step 6 unified build | resolves to a valid DevEco install |
-
-If neither `DEVECO_HOME` nor `DEVECO_SDK_HOME` is set, **ask the user** for the DevEco Studio install path before proceeding (suggest running `ht init` to persist it as a machine environment variable).
-
-## Step 1 — Parse User Request
-
-Extract 4 paths from the user's message (natural language, no fixed format):
-
-| Variable | Meaning | Typical Phrases |
-|---|---|---|
-| `android_project_dir` | Android source project root | "Android project path", "安卓项目", "source project" |
-| `harmony_project_dir` | HarmonyOS target project root | "target Harmony project", "鸿蒙项目", "output project" |
-| `ui_info_root` | **Parent directory containing all `page_NNNN_*` subdirectories** | "page screenshots and view tree", "page snapshots", "page folder" |
-| `pages` (optional) | User-explicitly listed page subset | When user lists `1. .../page_0001_X` ... take these |
-
-**`references_dir` and MVVM document directories always use skill-bundled relative paths** — **do not** accept user-provided overrides:
-
-- mappings: `./references/mappings/`
-- mvvm: `./references/mvvm/`
-
-If any required path cannot be extracted from the user's message, **ask the user** — do not guess.
-
-## Step 2 — Resource Conversion
-
-Invoke the `hmos-resources-convert` skill with the following parameters:
-1. **Android project path** = `android_project_dir`
-2. **HarmonyOS project output path** = `harmony_project_dir`
-3. **resource_mapping_path** = generate the resource mapping document under `harmony_project_dir` at `${harmony_project_dir}/resource_mapping.md`
-
-This skill batch-converts Android resources (strings, colors, drawables, images, etc.) to HarmonyOS resource format and generates the mapping document.
-
-## Step 3 — Page Exploration
-
-1. Check if `ui_info_root` already contains `page_*` subdirectories. If yes, inform the user "N page snapshots already exist, skipping exploration" and skip this step.
-2. Otherwise, determine the target App package name (`package`). If the user didn't provide it, extract the `package` attribute from `AndroidManifest.xml` in `android_project_dir`; if still unavailable, ask the user.
-3. Execute with Bash:
-   ```
-   python ./scripts/android_parse_fast.py --package <package_name> --output <ui_info_root_absolute_path>
-   ```
-   This script connects to the Android emulator via ADB, BFS-traverses all reachable pages in the App, and for each page saves `screenshot.png`, `view.xml`, `meta.json` into `page_NNNN_ActivityName/` subdirectories. It also generates `index.json` and `report.html` under `ui_info_root`.
-4. After execution, confirm that `index.json` has been generated under `ui_info_root`. If not, report an error and abort.
-
-## Step 4 — Discover Pages
-
-If the user did not explicitly list pages: use Glob `page_*_*` under `ui_info_root` to find all page subdirectories, sorted by name (`page_0001_*` first).
-
-If the user explicitly listed pages (e.g. "1. .../page_0001_MainActivity ... 19. .../page_0019_MainActivity"): use the user's list.
-
-After discovery, create a task for each page via TaskCreate to track progress.
-
-## Step 5 — Per-Page Conversion
-
-**For each page**, invoke the Agent tool (`subagent_type: general-purpose`) to perform conversion. The prompt must include:
-
-1. The page's `ui_info` absolute path (`{ui_info_root}/page_NNNN_ActivityName`)
-2. `android_project_dir`, `harmony_project_dir`
-3. Absolute paths for mappings and mvvm directories (skill-bundled)
-4. **Copy the full contents of `references/conversion-procedure.md` as the sub-agent's work instructions** (use Read to read it and paste into the prompt)
-
-Why use sub-agents: single-page conversion reads many mapping/MVVM documents + Android source code. Sub-agents isolate context to avoid overwhelming the main session.
-
-After receiving a sub-agent's conversion report, append a brief summary to a cumulative report and mark the corresponding task as completed.
-
-**Execute serially** — do not parallelize (multiple sub-agents modifying the same Harmony project simultaneously will conflict).
-
-## Step 6 — Unified Build Fix
-
-After all page conversions are complete, call the `hmos_fix_build_errors` skill **only once at the end** (passing `harmony_project_dir`) to make the entire project compile. Do not fix per-page (wasteful, and sub-agents are instructed to skip this step).
-
-## Step 7 — Summary Report
-
-Output an overview:
-
-```
-## Batch Conversion Overview
-- Pages processed: N
-- Successful: M   Failed/partial: K
-- Final build status: SUCCESS / PARTIAL
-
-### Per-Page Results
-| Page | Activity | Output File | Status |
-|---|---|---|---|
-| 0001 | MainActivity | pages/MainPage.ets | ✓ |
-| ... | | | |
-
-### Manual Follow-up TODOs
-- (Aggregate mocked items / unimplemented navigation / business logic from sub-reports)
-```
-
-## Key Constraints
-
-- **Never** let a per-page sub-agent call `hmos_fix_build_errors`; do it once in Step 6 only.
-- If the user's `harmony_project_dir` lacks entry/resources subdirectories or the target project doesn't exist, stop and ask — do not generate code.
+---
+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-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.
+
+## Step 0 — Environment Variables Check (run first)
+
+The final build (Step 6, via `hmos_fix_build_errors`) resolves the DevEco location along the standard chain — **OS environment variable first, then `~/.hometrans/config.json`, then ask the user** (read env vars with `echo "$VAR"` on macOS/Linux; `$env:VAR` in PowerShell on Windows):
+
+| Variable | config.json fallback | Needed for | Valid when |
+|---|---|---|---|
+| `DEVECO_HOME` *(or `DEVECO_SDK_HOME`)* | `env.DEVECO_HOME` / `env.DEVECO_SDK_HOME` | Step 6 unified build | resolves to a valid DevEco install |
+
+If neither the env var nor `~/.hometrans/config.json` yields a valid DevEco install, **ask the user** for the DevEco Studio install path before proceeding (suggest running `ht init` to persist it as a machine environment variable).
+
+## Step 1 — Parse User Request
+
+Extract 4 paths from the user's message (natural language, no fixed format):
+
+| Variable | Meaning | Typical Phrases |
+|---|---|---|
+| `android_project_dir` | Android source project root | "Android project path", "安卓项目", "source project" |
+| `harmony_project_dir` | HarmonyOS target project root | "target Harmony project", "鸿蒙项目", "output project" |
+| `ui_info_root` | **Parent directory containing all `page_NNNN_*` subdirectories** | "page screenshots and view tree", "page snapshots", "page folder" |
+| `pages` (optional) | User-explicitly listed page subset | When user lists `1. .../page_0001_X` ... take these |
+
+**`references_dir` and MVVM document directories always use skill-bundled relative paths** — **do not** accept user-provided overrides:
+
+- mappings: `./references/mappings/`
+- mvvm: `./references/mvvm/`
+
+If any required path cannot be extracted from the user's message, **ask the user** — do not guess.
+
+## Step 2 — Resource Conversion
+
+Invoke the `hmos-resources-convert` skill with the following parameters:
+1. **Android project path** = `android_project_dir`
+2. **HarmonyOS project output path** = `harmony_project_dir`
+3. **resource_mapping_path** = generate the resource mapping document under `harmony_project_dir` at `${harmony_project_dir}/resource_mapping.md`
+
+This skill batch-converts Android resources (strings, colors, drawables, images, etc.) to HarmonyOS resource format and generates the mapping document.
+
+## Step 3 — Page Exploration
+
+1. Check if `ui_info_root` already contains `page_*` subdirectories. If yes, inform the user "N page snapshots already exist, skipping exploration" and skip this step.
+2. Otherwise, determine the target App package name (`package`). If the user didn't provide it, extract the `package` attribute from `AndroidManifest.xml` in `android_project_dir`; if still unavailable, ask the user.
+3. Execute with Bash:
+   ```
+   uv run --no-project python ./scripts/android_parse_fast.py --package <package_name> --output <ui_info_root_absolute_path>
+   ```
+   This script connects to the Android emulator via ADB, BFS-traverses all reachable pages in the App, and for each page saves `screenshot.png`, `view.xml`, `meta.json` into `page_NNNN_ActivityName/` subdirectories. It also generates `index.json` and `report.html` under `ui_info_root`.
+4. After execution, confirm that `index.json` has been generated under `ui_info_root`. If not, report an error and abort.
+
+## Step 4 — Discover Pages
+
+If the user did not explicitly list pages: use Glob `page_*_*` under `ui_info_root` to find all page subdirectories, sorted by name (`page_0001_*` first).
+
+If the user explicitly listed pages (e.g. "1. .../page_0001_MainActivity ... 19. .../page_0019_MainActivity"): use the user's list.
+
+After discovery, create a task for each page via TaskCreate to track progress.
+
+## Step 5 — Per-Page Conversion
+
+**For each page**, invoke the Agent tool (`subagent_type: general-purpose`) to perform conversion. The prompt must include:
+
+1. The page's `ui_info` absolute path (`{ui_info_root}/page_NNNN_ActivityName`)
+2. `android_project_dir`, `harmony_project_dir`
+3. Absolute paths for mappings and mvvm directories (skill-bundled)
+4. **Copy the full contents of `references/conversion-procedure.md` as the sub-agent's work instructions** (use Read to read it and paste into the prompt)
+
+Why use sub-agents: single-page conversion reads many mapping/MVVM documents + Android source code. Sub-agents isolate context to avoid overwhelming the main session.
+
+After receiving a sub-agent's conversion report, append a brief summary to a cumulative report and mark the corresponding task as completed.
+
+**Execute serially** — do not parallelize (multiple sub-agents modifying the same Harmony project simultaneously will conflict).
+
+## Step 6 — Unified Build Fix
+
+After all page conversions are complete, call the `hmos_fix_build_errors` skill **only once at the end** (passing `harmony_project_dir`) to make the entire project compile. Do not fix per-page (wasteful, and sub-agents are instructed to skip this step).
+
+## Step 7 — Summary Report
+
+Output an overview:
+
+```
+## Batch Conversion Overview
+- Pages processed: N
+- Successful: M   Failed/partial: K
+- Final build status: SUCCESS / PARTIAL
+
+### Per-Page Results
+| Page | Activity | Output File | Status |
+|---|---|---|---|
+| 0001 | MainActivity | pages/MainPage.ets | ✓ |
+| ... | | | |
+
+### Manual Follow-up TODOs
+- (Aggregate mocked items / unimplemented navigation / business logic from sub-reports)
+```
+
+## Key Constraints
+
+- **Never** let a per-page sub-agent call `hmos_fix_build_errors`; do it once in Step 6 only.
+- If the user's `harmony_project_dir` lacks entry/resources subdirectories or the target project doesn't exist, stop and ask — do not generate code.
 - If input paths are Windows paths (with backslashes), pass them as-is to sub-agents; internal Read/Glob support them.