android2harmony 0.1.3 → 0.1.5

package/skills/hmos-incremental-ui-align/scripts/page_capture_burst.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { pathToFileURL } from "node:url";
+function sleep(seconds) {
+  const end = Date.now() + seconds * 1e3;
+  const sab = new SharedArrayBuffer(4);
+  const ia = new Int32Array(sab);
+  while (Date.now() < end) {
+    Atomics.wait(ia, 0, 0, Math.min(50, end - Date.now()));
+  }
+}
+function adb(args, serial = null, timeout = 15) {
+  const full = [];
+  if (serial) full.push("-s", serial);
+  full.push(...args);
+  const res = spawnSync("adb", full, {
+    timeout: timeout * 1e3,
+    maxBuffer: 128 * 1024 * 1024,
+    windowsHide: true
+  });
+  if (res.error && res.error.code === "ETIMEDOUT") {
+    console.log(`  [WARN] adb timeout: ${args.join(" ")}`);
+    return "";
+  }
+  const out = res.stdout ?? Buffer.alloc(0);
+  return out.toString("utf-8").trim();
+}
+function adbShell(args, serial = null, timeout = 15) {
+  return adb(["shell", ...args], serial, timeout);
+}
+function adbScreenshot(outputDir, filename, serial = null) {
+  const localPath = path.join(outputDir, filename);
+  const args = [];
+  if (serial) args.push("-s", serial);
+  args.push("exec-out", "screencap", "-p");
+  const res = spawnSync("adb", args, {
+    timeout: 15 * 1e3,
+    maxBuffer: 128 * 1024 * 1024,
+    windowsHide: true
+  });
+  if (res.error && res.error.code === "ETIMEDOUT") {
+    console.log("  [WARN] screenshot timeout");
+    return false;
+  }
+  const stdoutBuf = res.stdout ?? Buffer.alloc(0);
+  if (stdoutBuf.length > 0) {
+    fs.writeFileSync(localPath, stdoutBuf);
+    return true;
+  }
+  return false;
+}
+function adbDumpXml(outputDir, filename, serial = null) {
+  const remotePath = "/sdcard/ui_dump.xml";
+  adbShell(["rm", "-f", "/sdcard/ui_dump.xml", "&&", "uiautomator", "dump", "/sdcard/ui_dump.xml"], serial, 20);
+  for (let i = 0; i < 6; i++) {
+    const check = adbShell(["ls", remotePath], serial);
+    if (check.includes(remotePath)) break;
+    sleep(0.2);
+  }
+  const xmlContent = adbShell(["cat", remotePath], serial, 15);
+  if (xmlContent) {
+    fs.writeFileSync(path.join(outputDir, filename), xmlContent, "utf-8");
+  }
+  return xmlContent;
+}
+function parseArgs(argv) {
+  const args = { device: "adb", outputDir: "", duration: 10, serial: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = () => {
+      if (i + 1 >= argv.length) {
+        console.error(`Missing value for ${a}`);
+        process.exit(2);
+      }
+      return argv[++i];
+    };
+    if (a === "--device") {
+      const v = next();
+      if (v !== "adb") {
+        console.error("--device must be adb (currently adb only)");
+        process.exit(2);
+      }
+      args.device = v;
+    } else if (a === "--output-dir" || a === "-o") {
+      args.outputDir = next();
+    } else if (a === "--duration" || a === "-d") {
+      args.duration = parseInt(next(), 10);
+    } else if (a === "--serial") {
+      args.serial = next();
+    } else if (a === "-h" || a === "--help") {
+      printHelp();
+      process.exit(0);
+    } else {
+      console.error(`Unknown argument: ${a}`);
+      process.exit(2);
+    }
+  }
+  if (!args.outputDir) {
+    console.error("error: --output-dir/-o is required");
+    process.exit(2);
+  }
+  return args;
+}
+function printHelp() {
+  console.log(
+    [
+      "Burst capture: take view tree + screenshot every 1s for N seconds",
+      "",
+      "Usage: node page_capture_burst.ts --device adb -o <dir> [--duration N] [--serial S]",
+      "",
+      "  --device        Device type (currently adb only)",
+      "  --output-dir,-o Output directory for captured files (required)",
+      "  --duration,-d   Total capture duration in seconds (default: 10)",
+      "  --serial        ADB device serial (optional)"
+    ].join("\n")
+  );
+}
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  fs.mkdirSync(args.outputDir, { recursive: true });
+  console.log(`[Burst Capture] duration=${args.duration}s, output=${args.outputDir}`);
+  console.log("[Burst Capture] Starting continuous capture...");
+  const startTime = Date.now();
+  let frame = 0;
+  while (true) {
+    const elapsed = (Date.now() - startTime) / 1e3;
+    if (elapsed >= args.duration) break;
+    frame += 1;
+    const frameStart = Date.now();
+    const frameStr = String(frame).padStart(3, "0");
+    process.stdout.write(`  Frame ${frame} (t=${elapsed.toFixed(1)}s)... `);
+    const xmlOk = !!adbDumpXml(args.outputDir, `view_${frameStr}.xml`, args.serial);
+    const shotOk = adbScreenshot(args.outputDir, `screenshot_${frameStr}.png`, args.serial);
+    console.log(xmlOk && shotOk ? "OK" : "partial");
+    const frameElapsed = (Date.now() - frameStart) / 1e3;
+    const sleepTime = Math.max(0, 1 - frameElapsed);
+    if (sleepTime > 0 && (Date.now() - startTime) / 1e3 + sleepTime < args.duration) {
+      sleep(sleepTime);
+    }
+  }
+  console.log(`
+[Burst Capture] Done. ${frame} frames captured to ${args.outputDir}`);
+  return 0;
+}
+const isEntry = process.argv[1] !== void 0 && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isEntry) {
+  process.exit(main());
+}
+export {
+  adbDumpXml,
+  adbScreenshot,
+  parseArgs
+};

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

@@ -1,141 +0,0 @@
----
-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. State management follows the target project's paradigm — **V2 for new 0→1 conversions, V1 when the existing Harmony project already uses V1** (detected per project; see Step 5).
-
-## Step 0 — Environment Variables Check (run first)
-
-The final build (Step 6, via `hmos_fix_build_errors`) resolves the DevEco location from the **OS environment variable** — then asks the user if unset (read env vars with `echo "$VAR"` on macOS/Linux; `$env:VAR` in PowerShell on Windows):
-
-| Variable | Needed for | Valid when |
-|---|---|---|
-| `DEVECO_SDK_HOME` | Step 6 unified build | resolves to a valid DevEco install (derive the install root as its parent dir) |
-
-If the env var does not yield a valid DevEco install, **ask the user** for the DevEco Studio install path before proceeding (suggest setting `DEVECO_SDK_HOME` 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 |
-| `apk_path` (optional) | Full path of the Android APK corresponding to `android_project_dir`. Passed through to `hmos-resources-convert` in Step 2 to skip the Gradle build and decompile this APK directly with apktool to extract resources | "APK path", "apk文件", "安卓apk" |
-
-**`references_dir` and MVVM document directories always use skill-bundled relative paths** — **do not** accept user-provided overrides:
-
-- mappings: `./references/mappings/`
-- mvvm (V1): `./references/mvvm/`
-- mvvm (V2): `./references/mvvm-v2/`
-
-The per-page sub-agent first **detects whether the target Harmony project uses state-management V1 or V2** (project-level, decided once), then reads only the matching doc set. New 0→1 conversions default to V2; a project already on V1 stays on V1. See `./references/mvvm-v2/_范式选择说明.md` for the detection rule.
-
-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 (all snake_case, matching that skill's declared inputs):
-1. `android_project_dir` = `android_project_dir`
-2. `harmony_project_dir` = `harmony_project_dir`
-3. `resource_mapping_path` = generate the resource mapping document under `harmony_project_dir` at `${harmony_project_dir}/resource_mapping.md`
-4. `apk_path` = `apk_path` — **only if the user provided it**. When passed through, `hmos-resources-convert` skips the Gradle build and decodes this APK directly to extract resources. Omit this parameter entirely when `apk_path` was not provided.
-
-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 (TypeScript version, run directly with Node ≥ 22.18 / 23.6 which natively strips types — no build step, no dependencies):
-   ```
-   node ./scripts/android_parse_fast.ts --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.
-
-### Resume from progress (checkpoint)
-
-The batch persists progress to `${ui_info_root}/batch_progress.json` so an interrupted run can continue instead of restarting from scratch. Schema:
-
-```json
-{
-  "harmony_project_dir": "<abs path>",
-  "updated_at": "<ISO timestamp>",
-  "pages": {
-    "page_0001_MainActivity": { "status": "done",    "output": "pages/MainPage.ets", "summary": "..." },
-    "page_0002_LoginActivity": { "status": "failed",  "error": "..." },
-    "page_0003_SettingsActivity": { "status": "pending" }
-  }
-}
-```
-
-- `status` is one of `pending` | `done` | `failed`.
-- If `batch_progress.json` exists **and** its `harmony_project_dir` matches the current one, read it back and merge into the discovered page set: pages marked `done` are skipped in Step 5; `pending`/`failed` pages are (re)processed.
-- If it does not exist, or `harmony_project_dir` differs (different target project), start fresh — initialize every discovered page to `pending` and write the file.
-- Before skipping a `done` page, sanity-check that its recorded `output` file still exists under `harmony_project_dir`. If the output is missing, treat the page as `pending` (re-convert).
-
-After discovery, create a task for each page via TaskCreate to track progress, initializing already-`done` pages as completed. Report to the user how many pages are being resumed vs. freshly processed (e.g. "Resuming: 7 done, 12 remaining").
-
-## Step 5 — Per-Page Conversion
-
-**Idempotency gate (check before converting each page):** consult `batch_progress.json`. If the page's `status` is `done` and its recorded `output` file still exists under `harmony_project_dir`, **skip it** (do not spawn a sub-agent) and go to the next page. Only pages with status `pending`/`failed` (or a `done` page whose output went missing) are converted.
-
-**For each page to convert**, 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, mvvm (V1: `references/mvvm/`) and mvvm-v2 (V2: `references/mvvm-v2/`) directories (skill-bundled) — pass both so the sub-agent can pick the set matching the project's detected paradigm
-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:
-1. **Update `batch_progress.json` immediately** (before moving to the next page) — set the page's `status` to `done` (with `output` = generated `.ets` path and a one-line `summary`) or `failed` (with `error`), and refresh `updated_at`. Writing after every page is what makes the batch resumable: a crash or interruption loses at most the one in-flight page.
-2. 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). Serial execution also keeps `batch_progress.json` writes free of races.
-
-## 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.
-- `batch_progress.json` is the single source of truth for resume. Write it after **every** page (Step 5), keyed by the target `harmony_project_dir`. Do not delete it mid-batch; it is safe to leave in place after completion (a re-run with all pages `done` becomes a no-op). To force a full re-conversion, delete `batch_progress.json` (or point at a fresh `harmony_project_dir`).
-- The Step 6 build fix runs regardless of resume state — resuming skips per-page conversion, not the final unified build.

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

@@ -1,217 +0,0 @@
-# Single-Page Android → HarmonyOS UI 转换流程
-
-> 这是 `hmos-batch-ui-align` skill 在每个子 agent 中执行的单页转换流程。基于 `a2h-ui-conversion-new` agent 改写：去掉 Phase 6 build 修复（由父 skill 统一在最后做一次）。
-
-你是一个 **UI Activity 转换器**，专门把单个 Android Activity 的某一页 UI 迁移到 HarmonyOS ArkUI（ArkTS）。
-
-## 输入（由父 skill 传入 prompt）
-
-1. `activity_name` — Android Activity 类名
-2. `android_project_dir` — Android 源项目根
-3. `ui_info` — **单个** `page_NNNN_ActivityName/` 目录绝对路径（含 `meta.json` + `view.xml` + 可能的 `view_scroll_n.xml` / `screenshot.png`）
-4. `harmony_project_dir` — HarmonyOS 项目根
-5. `mappings_dir` — 三份映射表所在目录（skill 自带）
-6. `mvvm_dir` — V1 状态管理文档目录（skill 自带 `references/mvvm/`，13 份）
-7. `mvvm_v2_dir` — V2 状态管理文档目录（skill 自带 `references/mvvm-v2/`，14 份）
-
-## 输出
-
-- ArkTS `.ets` 页面写到 `{harmony_project_dir}/entry/src/main/ets/pages/`
-- dialog/fragment/adapter 等组件写到 `.../ets/components/`
-- ViewModel 写到 `.../ets/viewmodel/`，Model 写到 `.../ets/model/`
-- 文本格式的转换报告（不落盘，作为最终回复返回给父 skill）
-
-## Phase 1 — 定位页面
-
-`ui_info` 已是单个页面目录，无需再筛选。
-
-## Phase 2 — 探测工程范式 + 加载 MVVM 参考
-
-### 2.0 探测目标工程采用 V1 还是 V2（先做，决定后续读哪套文档）
-
-状态管理 V1、V2 **不在同一工程内混用**。以**工程级**粒度判定一次，后续全程沿用：
-
-1. 扫 `{harmony_project_dir}/entry/src/main/ets/` 下已有 `.ets` 的状态管理装饰器：
-   - 命中 `@Component` + `@State`/`@Prop`/`@Link`/`@Provide`/`@Consume`/`@Observed`/`@ObjectLink`/`@Watch` → **V1**
-   - 命中 `@ComponentV2` + `@Local`/`@Param`/`@Once`/`@Event`/`@ObservedV2`/`@Trace`/`@Monitor`/`@Provider`/`@Consumer` → **V2**
-2. 判定：
-   - **空工程 / 0→1 全新转换 / 无任何状态装饰器 → 默认 V2**（新项目优先 V2）
-   - 只有 V1 → **V1**；只有 V2 → **V2**
-   - V1、V2 都有 → 以占多数者为准；新增代码贴合**目标页所在目录**的既有范式，并在转换报告中标注
-3. 输出判定结果（`范式 = V1 | V2`），Phase 4 全程据此选装饰器。
-
-> 详见 `{mvvm_v2_dir}/_范式选择说明.md`。
-
-### 2.1 加载对应范式的 MVVM 文档
-
-**若判定为 V1**，读 `{mvvm_dir}/` 下全部 13 份：
-- `MVVM模式（V1）.md`
-- `@Track装饰器：class对象属性级更新.md`
-- `@State装饰器：组件内状态.md`
-- `@Prop装饰器：父子单向同步.md`
-- `@Link装饰器：父子双向同步.md`
-- `@Provide装饰器和@Consume装饰器：与后代组件双向同步.md`
-- `@Observed装饰器和@ObjectLink装饰器：嵌套类对象属性变化.md`
-- `@Watch装饰器：状态变量更改通知.md`
-- `管理应用拥有的状态概述.md`
-- `LocalStorage：页面级UI状态存储.md`
-- `AppStorage：应用全局的UI状态存储.md`
-- `PersistentStorage：持久化存储UI状态.md`
-- `Environment：设备环境查询.md`
-
-**若判定为 V2**，读 `{mvvm_v2_dir}/` 下全部 14 份：
-- `MVVM模式（V2）.md`
-- `@Local装饰器：组件内部状态.md`（组件内状态，对应 V1 `@State`）
-- `@Param装饰器：组件外部输入.md` / `@Once装饰器：初始化同步一次.md`（父子输入，对应 V1 `@Prop`）
-- `@Event装饰器：规范组件输出.md`（子→父回调，配合 `!!` 实现双向，对应 V1 `@Link`）
-- `@Provider装饰器和@Consumer装饰器：跨组件层级双向同步.md`（对应 V1 `@Provide`/`@Consume`）
-- `@ObservedV2装饰器和@Trace装饰器：类属性变化观测.md`（对应 V1 `@Observed`/`@ObjectLink` + `@Track`）
-- `@Monitor装饰器：状态变量修改异步监听.md`（对应 V1 `@Watch`）
-- `@Computed装饰器：计算属性.md` / `@Type装饰器：标记类属性的类型.md`
-- `AppStorageV2：应用全局UI状态存储.md` / `PersistenceV2：持久化存储UI状态.md`
-- `!!语法：双向绑定.md`
-- `状态管理V1向V2迁移与混用指导.md`（仅当遇到既有 V1 工程需局部扩展时参考）
-
-## Phase 3 — 加载映射参考
-
-读 `{mappings_dir}/` 下：
-1. `android-to-harmonyOS-ui-layout-mapping-reference.md` — 布局容器与布局属性映射（LinearLayout→Column/Row、FrameLayout→Stack、RecyclerView→List、layout_weight→.layoutWeight()、padding→.padding() 等）
-2. `android-to-harmonyOS-ui-atomic-component-mapping-reference.md` — 原子组件映射（TextView→Text、EditText→TextInput/TextArea、Button→Button），含属性级映射（文本/样式/对齐/省略 等）
-3. `android-to-harmonyOS-ui-interaction-mapping-reference.md` — 交互映射（onClick→.onClick()、onLongClick→LongPressGesture、touch、gesture、animation）
-
-> 这三份映射是**首要依据**，优先于内置知识。
-
-## Phase 4 — 单页转换
-
-### 4.1 解析 meta.json
-
-提取：`page_id`、`label`、`clickable_elements`（含 class/resource-id/text/content-desc/bounds）、`click_path`、`came_from`/`trigger_element`。
-
-### 4.2 解析视图树
-
-读 `view.xml`，建立结构化理解：根布局、toolbar、content、bottom nav、各 widget 的 class/resource-id/text/content-desc/bounds/clickable/scrollable/checkable/checked/enabled、由 bounds 推断父子+兄弟关系、识别复用模式（list item / card）。
-
-若存在 `view_scroll_n.xml`（n=1,2,...）：表示 Android UI 太长需滚动捕获，按编号 1→n 依次读取，**以 `view.xml` 为根**合并所有 `view_scroll_n.xml` 得到合并结构。
-
-合并结构仍可能不完整（某些组件未出现在任何快照中）。**必须**在 `android_project_dir` 中查找并阅读与 `meta.json`、合并结构最相关的静态 XML 布局文件 + Kotlin/Java 代码，以静态源码为主结构，把合并结构作为动态信息补充，并把用户自定义/三方组件展开成原子 Android 布局/组件，得到**最终结构理解**。输出该理解。
-
-可选：调用 `android-ui-graph-query` skill 补充 UI 图谱信息（widget 详细属性、样式、theme）。
-
-### 4.3 生成 ArkUI 代码
-
-**与现有 Harmony 文件冲突处理**：转换前若目标 .ets 已存在，三种情形——
-1. 动态刷新组件（toolbar 不同状态显示不同图标）
-2. 增量实现
-3. 现有代码或最终结构理解有错
-
-无论哪种，必须通过对照静态 XML/Kotlin/Java + view.xml + view_scroll_n.xml 验证。**不要删除已有 Harmony 代码**。
-
-dialog/fragment/adapter 等必须从主页面拆出去到 `{harmony_project_dir}/entry/src/main/ets/components/`。
-
-**架构**：
-- MVVM：page/component 用 viewmodel，viewmodel 用 model
-- 转换前先扫 `{harmony_project_dir}` 找可复用组件/VM/Model；toolbar 等通用组件抽到 components 复用；相关 model/viewmodel 合并复用，不要每页新建一份
-- **按 Phase 2.0 判定的范式选装饰器，全程保持同一套，不混用**：
-  - **V1**：`@Component` 组件；组件内状态 `@State`，父子 `@Prop`(单向)/`@Link`(双向)，跨层级 `@Provide`/`@Consume`；ViewModel/Model 类用 `@Observed` + 属性 `@Track`；副作用监听 `@Watch`
-  - **V2**：`@ComponentV2` 组件；组件内状态 `@Local`，父子输入 `@Param`(+ 可选 `@Once`)、子→父 `@Event`(配合 `!!` 双向绑定)，跨层级 `@Provider`/`@Consumer`；ViewModel/Model 类用 `@ObservedV2` + 属性 `@Trace`；监听 `@Monitor`，计算属性 `@Computed`
-
-**资源**：每个 Android UI 引用的资源（图片/字符串/颜色/尺寸等）必须使用 `{harmony_project_dir}\entry\src\main\resources` 中**同名**的转换后资源。
-
-**布局**：查 layout mapping ref。
-
-**组件**：查 atomic component mapping ref。
-
-**交互**：查 interaction mapping ref。
-
-**始终先查映射文件**（项目专属、覆盖更全），覆盖内置知识。
-
-**单位与样式**：
-- `dp` → `vp`，`sp` → `fp`
-- 由 bounds 算尺寸：`width = x2 - x1`，`height = y2 - y1`
-- 假定 3x 密度：`1vp ≈ 3px`
-- 资源用 `$r('app.color.xxx')` / `$r('app.string.xxx')` / `$r('app.media.xxx')`
-
-**路由**：实现 UI 与组件之间的路由关系。
-
-**交互元素**：
-- 给每个 `clickable_element` 挂 `.onClick()`
-- `click_path` 显示跳到另一 Activity → `router.pushUrl()`
-- 状态切换（dialog/menu/toggle）→ 用 `@State` 管理
-- **优先真实实现**：mock 之前先在 `{harmony_project_dir}` 搜目标页面/组件 .ets 是否存在；存在则接真实 `router.pushUrl()`；**仅当目标尚未实现**才 mock + `console.info('TODO: ...')`
-
-### 4.4 截图复核（如有）
-
-`screenshot.png` 仅覆盖屏内 UI，**不要**用它去校验屏外组件。
-
-存在则读取：视觉校验布局理解，对照视图层级，调整 `view.xml` 未捕获的间距/对齐/样式。`screenshot_scroll_n.png` 同理对照 `view_scroll_n.xml`。
-
-## Phase 5 — 一致性校验（关键，必跑 3 轮）
-
-列出转换后 HarmonyOS UI 中所有 layout/component/resource reference，对每一个**逐项**走完以下检查（不可省略）：
-
-- **观测装饰器缺失**（按 Phase 2.0 判定的范式分支）：
-  - V1：`@Observed` 类中所有在 UI 中使用的属性是否都加了 `@Track`？没有则补
-  - V2：`@ObservedV2` 类中所有在 UI 中使用的属性是否都加了 `@Trace`？没有则补（`@ObservedV2` 与 `@Trace` 必须配合，单独使用任一个都不生效）
-  - 范式一致性：本页新增/修改的组件与 VM/Model 是否与工程判定范式一致？严禁 V1/V2 装饰器混用（如 `@Component` 里用 `@Local`、`@ComponentV2` 里用 `@State`）
-- **颜色冲突**：fill/background/foreground 颜色是否冲突导致不可见（白底白图）？有则修
-- **颜色设置**：背景/填充/前景色是否与 Android UI 一致（漏设、错设）？有则修
-- **资源引用错用**：资源引用是否与 Android UI 一致；不存在的资源要重新查找正确名
-- **形状错用**：圆角/直角等形状是否与 Android UI 一致
-- **尺寸问题**：图标/组件大小是否一致
-- **位置问题**：toolbar 是否在顶部、图标位置是否过左/过右等
-- **路由关系**：UI 与组件间路由是否正确实现
-
-**必须跑 3 轮验证迭代，并输出验证报告**。
-
-## Phase 6 — Build 修复
-
-**跳过**。父 skill `hmos-batch-ui-align` 会在所有页面转换完后统一调用 `hmos_fix_build_errors` 修一次。
-
-## 返回转换报告
-
-```
-## Conversion Report: {ActivityName} (page_NNNN)
-
-### Page Processed
-| Page ID | Label | Type | Output File |
-|---------|-------|------|-------------|
-| page_NNNN_XXX | ...  | Base Page | XxxPage.ets |
-
-### Component Mapping Decisions
-- ...
-
-### State Variables
-- ...
-
-### Resources Converted
-- ...
-
-### Implemented Interactions
-- ...（接通真实跳转的事件）
-
-### TODOs & Mocked Items
-- ...（mock 的事件、未实现的目标页）
-
-### Navigation
-- ...（从 click_path 抽取的导航目标）
-
-### Validation Report (3 iterations)
-- 第 1 轮：发现/修复 N 项
-- 第 2 轮：发现/修复 M 项
-- 第 3 轮：稳定/剩余 K 项
-```
-
-## 全局准则
-
-- **一个 Activity = 一个主页面文件**（仅最小编号那张快照）
-- **严格保真**：layout 结构、组件层级、资源引用必须与 Android 源一一对应；不增删/重排 UI 元素
-- **资源精确匹配**：所有 color/string/dimension/image 必须有对应 HarmonyOS 资源；不要硬编码
-- **可编译性是必须的**：已实现目标接真实事件；未实现才 mock 至可编译
-- 仅用声明式 ArkUI；绝不写命令式 DOM 操作
-- 保留原 Android 视觉与 UX 保真度
-- 资源一律 `$r('app.type.name')`
-- 留 `// TODO:` 注释给：业务逻辑、ViewModel 数据绑定、未转换的目标 Activity
-- 响应式布局：优先百分比宽度 + Flex，少用固定尺寸
-- 无障碍：`content-desc` → `.accessibilityText()`，有意义的 `text` → 正确的 label
-- 嵌套 > 5 层时把相关 UI 拆为 `@Component` 子组件
-- 任一 mapping 文件缺失/为空：用内置知识继续，并在报告中注明