android2harmony 0.1.6 → 0.1.8

package/skills/a2h-spec-implement/scripts/utils/ensure_app.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+// ensure_app.mjs — guarantee the project's app is installed on a device (Phase 1 grounding gate).
+//
+//   node scripts/utils/ensure_app.mjs --project <harmonyos-project-path> --device <serial> [--bundle <name>]
+//
+// Deterministic, idempotent: probe installed → done; absent → devecocli build (release, signed
+// per rules/pipeline/build/build.md) → hdc install -r (cd + basename, per testing/test-core.md
+// § Device channel & install) → re-probe. Never uninstalls, never reinstalls an installed app
+// (an app-HAP reinstall re-signs and drops persisted URI grants — measured).
+//
+// stdout contract: exactly ONE line —
+//   ENSURE_APP: installed bundle=<b> device=<d>
+//   ENSURE_APP: built+installed bundle=<b> device=<d> haps=<n>
+//   ENSURE_APP: FAILED <stage>: <reason>
+// Diagnostics (build-log tail etc.) go to stderr. Exit 0 on installed/built+installed, 1 on FAILED.
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { ensureHdcOnPath, hdcRun } from "../device_ui_core.mjs";
+
+// ---------- args ----------
+function parseArgs(argv) {
+  const a = { project: "", device: "", bundle: "" };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--project") a.project = argv[++i];
+    else if (t === "--device") a.device = argv[++i];
+    else if (t === "--bundle") a.bundle = argv[++i];
+    else if (t === "-h" || t === "--help") a.help = true;
+  }
+  return a;
+}
+const args = parseArgs(process.argv.slice(2));
+if (args.help || !args.project || !args.device) {
+  console.error("Usage: node scripts/utils/ensure_app.mjs --project <harmonyos-project-path> --device <serial> [--bundle <name>]");
+  process.exit(args.help ? 0 : 1);
+}
+
+function ok(line) { console.log(line); process.exit(0); }
+function fail(stage, reason) { console.log(`ENSURE_APP: FAILED ${stage}: ${reason}`); process.exit(1); }
+
+const project = path.resolve(args.project);
+if (!fs.existsSync(project)) fail("args", `project not found: ${project}`);
+
+// ---------- bundle name (AppScope/app.json5) ----------
+let bundle = args.bundle;
+if (!bundle) {
+  const appJson = path.join(project, "AppScope", "app.json5");
+  try {
+    const m = fs.readFileSync(appJson, "utf8").match(/"bundleName"\s*:\s*"([^"]+)"/);
+    if (m) bundle = m[1];
+  } catch { /* fall through */ }
+  if (!bundle) fail("args", `bundleName not resolvable from ${appJson} (pass --bundle)`);
+}
+
+// ---------- probe installed ----------
+if (!ensureHdcOnPath()) fail("probe", "hdc not on PATH and not locatable via conf.yaml DEVECO_PATH/DEVECO_SDK_HOME");
+// hdc exits 0 even on an unreachable device (error text on stdout) — verify the target is
+// actually connected before trusting any shell output.
+const targets = hdcRun(null, ["list", "targets"], 15000);
+if (targets.error || !(targets.stdout || "").split(/\r?\n/).some((l) => l.trim() === args.device)) {
+  fail("probe", `device ${args.device} not in \`hdc list targets\`: ${((targets.stdout || targets.stderr || "") + "").trim().slice(0, 200)}`);
+}
+function isInstalled() {
+  const p = hdcRun(args.device, ["shell", "bm", "dump", "-a"], 30000);
+  const out = p.stdout || "";
+  if (p.error || p.status !== 0 || /\[Fail\]/i.test(out)) {
+    fail("probe", `bm dump failed on ${args.device}: ${((p.stderr || out || String(p.error)) + "").trim().slice(0, 200)}`);
+  }
+  // `bm dump -a` lists bundle names one per line; exact-token match (avoid prefix collisions).
+  return out.split(/\r?\n/).some((l) => l.trim() === bundle);
+}
+if (isInstalled()) ok(`ENSURE_APP: installed bundle=${bundle} device=${args.device}`);
+
+// ---------- build (release = signed output; debug is compile-check only per build.md) ----------
+console.error(`[ensure_app] ${bundle} not installed on ${args.device} — building current code (devecocli build, release)…`);
+const build = spawnSync("devecocli build", {
+  cwd: project, shell: true, encoding: "utf8", timeout: 600000,
+  windowsHide: true, maxBuffer: 64 * 1024 * 1024,
+});
+const buildLog = (build.stdout || "") + (build.stderr || "");
+if (build.error || build.status !== 0 || !/BUILD SUCCESSFUL/i.test(buildLog)) {
+  console.error(buildLog.split(/\r?\n/).slice(-30).join("\n"));
+  fail("build", `devecocli build rc=${build.status ?? build.error} (log tail on stderr)`);
+}
+
+// ---------- collect package set (per-module <mod>/build/default/outputs/default) ----------
+// Signing mode follows the project: a product referencing a signingConfig emits *-signed.hap,
+// `app.signingConfigs: []` emits *-unsigned.hap and cannot emit anything else. Take signed when
+// present, else unsigned — rejecting the unsigned variant yields no package set at all, which
+// disables the device layer and misreports a build-config fact as a missing artifact.
+const outDirs = [];
+for (const mod of fs.readdirSync(project, { withFileTypes: true })) {
+  if (!mod.isDirectory()) continue;
+  const out = path.join(project, mod.name, "build", "default", "outputs", "default");
+  if (fs.existsSync(out)) outDirs.push(out);
+}
+const collect = (suffix) => {
+  const acc = []; // { dir, name }
+  for (const dir of outDirs) {
+    for (const f of fs.readdirSync(dir)) {
+      if (f.endsWith(`-${suffix}.hap`) || f.endsWith(".hsp")) acc.push({ dir, name: f });
+    }
+  }
+  return acc;
+};
+let mode = "signed";
+let pkgs = collect("signed");
+if (!pkgs.some((p) => p.name.endsWith(".hap"))) {
+  const unsignedPkgs = collect("unsigned");
+  if (unsignedPkgs.some((p) => p.name.endsWith(".hap"))) {
+    mode = "unsigned";
+    pkgs = unsignedPkgs;
+    console.error("[ensure_app] no signed HAP — installing the unsigned package set; a device that refuses it is an environment result, not a code defect");
+  }
+}
+if (!pkgs.length) fail("install", "build produced no *-signed.hap and no *-unsigned.hap (see build.md § Pinned command)");
+
+// ---------- install (one transaction; cd + basename — hdc mangles non-Windows paths) ----------
+const byDir = new Map();
+for (const p of pkgs) { if (!byDir.has(p.dir)) byDir.set(p.dir, []); byDir.get(p.dir).push(p.name); }
+for (const [dir, names] of byDir) {
+  const p = spawnSync("hdc", ["-t", args.device, "install", "-r", ...names], {
+    cwd: dir, encoding: "utf8", timeout: 120000, windowsHide: true,
+  });
+  const outText = ((p.stdout || "") + (p.stderr || "")).trim();
+  if (p.error || p.status !== 0 || /error|fail/i.test(outText)) {
+    fail("install", `hdc install -r ${names.join(" ")}: ${outText.slice(0, 300)}`);
+  }
+}
+
+// ---------- re-probe ----------
+if (!isInstalled()) fail("install", `install reported success but ${bundle} still absent in bm dump -a`);
+ok(`ENSURE_APP: built+installed bundle=${bundle} device=${args.device} haps=${pkgs.length} mode=${mode}`);

package/skills/a2h-ui-transfer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: a2h-ui-transfer
-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). Includes Lottie animation handling — greps the Lottie Animation Resources section out of the conversion report produced by a2h-resource-convert, binds each Lottie JSON to the host Activity/Fragment, and passes only the relevant entries to each per-page sub-agent so the generated ArkTS page implements the animation with @ohos/lottie (loaded from rawfile/lottie/) mirroring the Android hosting logic. Triggers on phrases like "把安卓页面迁移到鸿蒙", "Android UI 转鸿蒙", "批量转 ArkTS", "a2h-ui-transfer", or any request that supplies an Android project path + Harmony project path + a directory of page snapshots.
+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. Triggers on phrases like "把安卓页面迁移到鸿蒙", "Android UI 转鸿蒙", "批量转 ArkTS", "a2h-ui-transfer", or any request that supplies an Android project path + Harmony project path + a directory of page snapshots.
 ---
 
 # a2h-ui-transfer — Android → HarmonyOS UI Batch Conversion
@@ -39,7 +39,7 @@ Extract these from the user's message (natural language, no fixed format):
 
 If a **required** path (`android_project_dir`, `harmony_project_dir`, `apk_path`) cannot be extracted from the user's message, **ask the user** — do not guess. `ui_info_root` and `pages` are optional and have the defaults described above; do not ask for them.
 
-## Step 2 — Resource Conversion
+## Step 2 — Resource Conversion (use a sub-agent, type: general)
 
 Invoke the `a2h-resource-convert` skill with the following parameters (all snake_case, matching that skill's declared inputs):
 1. `android_project_dir` = `android_project_dir`
@@ -50,16 +50,16 @@ Invoke the `a2h-resource-convert` skill with the following parameters (all snake
 
 This skill batch-converts Android resources (strings, colors, drawables, images, etc.) to HarmonyOS resource format and generates the mapping document.
 
-**Two documents come out of that skill and they are not interchangeable — record both paths.** The **conversion report** (`<work_dir>/resource_conversion_report.md`, observed at `${harmony_project_dir}/.hometrans/resource_conversion_report.md`, ~180 KB) is aggregated and holds the **Vector Fidelity Issues** / **Lottie Animation Resources** / **Code-Defined Vector Icons** sections that Steps 4.5 and 5 need. The **mapping document** (`resource_mapping_path`) is the per-resource audit surface, **4–22 MB by design** (one observed file: 2.3 MB) and has **no Lottie section** — always `Grep <name>` it, never `Read` it whole: a truncated read drops rows that then look exactly like "that resource does not exist", and the page substitutes something that compiles.
+**Two documents come out of that skill and they are not interchangeable — record both paths.** The **conversion report** (`<work_dir>/resource_conversion_report.md`, observed at `${harmony_project_dir}/.hometrans/resource_conversion_report.md`,) is aggregated and holds the **Vector Fidelity Issues** / **Lottie Animation Resources** / **Code-Defined Vector Icons** sections that Steps 4.5 and 5 need. The **mapping document** (`resource_mapping_path`) is the per-resource audit surface, **4–22 MB by design**   — always `Grep <name>` it, never `Read` it whole: a truncated read drops rows that then look exactly like "that resource does not exist", and the page substitutes something that compiles.
 
-**Resolve `<app_module>` while you are here** — the module whose Gradle file applies the `com.android.application` plugin (grep `com.android.application` across `<android_project_dir>/*/build.gradle` and `*/build.gradle.kts`). It is **usually** `app/`, but do not assume that name: many projects use `mobile/`, `client/`, `androidApp/`, or a nested path. Store it relative to `<android_project_dir>` and use it everywhere below instead of a literal `app`. If several modules apply the plugin, ask the user which one corresponds to `apk_path`. This matches the resolution `a2h-resource-convert` does in its Step 2, so the two skills agree on the module.
+**Resolve `<app_module>` ** — the module whose Gradle file applies the `com.android.application` plugin (grep `com.android.application` across `<android_project_dir>/*/build.gradle` and `*/build.gradle.kts`). It is **usually** `app/`, but do not assume that name: many projects use `mobile/`, `client/`, `androidApp/`, or a nested path. Store it relative to `<android_project_dir>` and use it everywhere below instead of a literal `app`. If several modules apply the plugin, ask the user which one corresponds to `apk_path`. This matches the resolution `a2h-resource-convert` does in its Step 2, so the two skills agree on the module.
 
-**Resolve `<ui_module>` here as well — the Harmony-side UI module, which is *not* always `entry`.** Read `${harmony_project_dir}/build-profile.json5` and take the `modules[]` entry whose `srcPath` holds a `module.json5` with `"type": "entry"`; store that `srcPath` relative to `harmony_project_dir`. A single-module project yields `entry`; a layered one yields a multi-segment path such as `products/phone`. **Every Harmony path from here on uses `<ui_module>`, never a literal `entry`** — pages, resources, the Step 6.0 static check, and the fidelity checker below. Getting this wrong is silent rather than loud: resources land in the module `a2h-resource-convert` resolved while pages are written to `entry/`, so every resource reference in every page dangles, and the static check — pointed at an `ets` directory that does not exist — scans zero files and reports a clean GATE. If several modules are `type: entry`, ask the user which one to convert into.
+**Resolve `<ui_module>` — the Harmony-side UI module, which is *not* always `entry`.** Read `${harmony_project_dir}/build-profile.json5` and take the `modules[]` entry whose `srcPath` holds a `module.json5` with `"type": "entry"`; store that `srcPath` relative to `harmony_project_dir`. A single-module project yields `entry`; a layered one yields a multi-segment path such as `products/phone`. **Every Harmony path from here on uses `<ui_module>`, never a literal `entry`** — pages, resources, the Step 6.0 static check, and the fidelity checker below. Getting this wrong is silent rather than loud: resources land in the module `a2h-resource-convert` resolved while pages are written to `entry/`, so every resource reference in every page dangles, and the static check — pointed at an `ets` directory that does not exist — scans zero files and reports a clean GATE. If several modules are `type: entry`, ask the user which one to convert into.
 
 **Resource-fidelity gate before Step 5.** When that skill's report contains a **Vector Fidelity Issues** section with `error`-severity rows, fix the resources before starting per-page conversion. A drawable whose `clip-path` was dropped, or whose stroke-only path was given a solid `fill`, still has the correct file name — so every page that references it will pass Phase 5's reference checks and compile cleanly while rendering wrong. Fixing it after the pages are written means re-verifying every page that consumed it. If resources were converted in an earlier session (so no fresh report exists), you can run that skill's checker directly — it is static and needs no device:
 
 ```
-node <a2h-resource-convert-skill>/scripts/svg_fidelity_check.js \
+node <a2h-resource-convert>/scripts/svg_fidelity_check.js \
     --android-res <android_project_dir>/<app_module>/src/main/res \
     --harmony-media <harmony_project_dir>/<ui_module>/src/main/resources/base/media
 ```
@@ -67,7 +67,7 @@ node <a2h-resource-convert-skill>/scripts/svg_fidelity_check.js \
 **App-identity gate — also before Step 5.** That skill's Toolchain step 2 points `AppScope/app.json5` and `abilities[0]` at the Android launcher icon and app name. Confirm it passed; nothing in Steps 5-7 covers it, and the failure is invisible to every check here — the pages compile and render fine while the app shows the DevEco default icon and is named `label` on the desktop. If resources were converted in an earlier session, run the gate directly (static, no device):
 
 ```
-node <a2h-resource-convert-skill>/scripts/app_identity.js --check --json <work_dir>/app_identity.json
+node <a2h-resource-convert>/scripts/app_identity.js --check --json <work_dir>/app_identity.json
 ```
 
 `GATE: FAIL`, or a missing `app_identity.json` (the step never ran), means re-running that skill's Toolchain step 2 before continuing.
@@ -245,7 +245,7 @@ Why it exists: on a measured single-page run the sub-agent spent **11 turns (~5
 
 The unit of work is the **state group** from Step 4.2 — a group of one page (the common case) or of several isomorphic pages. Skip a whole group only when *every* member is `done` with its `output` present; otherwise convert the group, treating the already-done members as context. For a multi-state group, items 1-4 below apply **once per member state**, each labelled with its page id, and Phase 5 evidence is required per state.
 
-**For each page to convert**:
+**Invoke a sub-agent(type:general) for each page to convert**:
 
 **The per-page conversion procedure lives in `./references/conversion-procedure.md`, and the sub-agent is the one that reads it** — the parent passes its absolute path (input 0 below). 
 
@@ -317,6 +317,7 @@ After each page's conversion :
 | Resource keys exist in every qualifier group the page needs | script the lookup across `base/` and each locale dir |
 | Forbidden patterns absent | `.position(`/`.offset(`, `$r(\``, V1 decorators in a V2 project |
 | **V1 only: no `@Track` class exposes a getter to the UI** | `grep -n "get [a-zA-Z]*(" ` every `@Observed` class that contains `@Track`. A getter cannot be `@Track`ed, so reading it in `build()` throws `BusinessError 140110` on the **first frame** — while the field-side completeness check passes, the build succeeds, and GATE is clean. Backstop: GATE rule `track-class-getter-in-ui` |
+| **Self-contained component wired into its host** | discharged at Step 5.5 (batch-level, not per-page): the parent imports each component and binds its trigger; a page's `done` during the batch is provisional for its triggers until Step 5.5 completes — GATE `orphan-component` zero is the batch-level discharge |
 
 When a sub-agent dies after writing code but before reporting, do not re-run it blindly: verify what is on disk against this list, and reconstruct only the missing evidence. Record in `batch_progress.json` which parts of the evidence were parent-reconstructed rather than sub-agent-attested, so a later reader can tell the two apart.
 
@@ -343,12 +344,20 @@ The conflict surface is narrow — the entry page plus shared VM/Model. A group
 **Rules when running concurrently:**
 1. **The first host-chain group goes first, alone.** It creates the entry page and the shared VM/Model that later groups extend, and it establishes the conventions (decorator paradigm, naming, resource style) that every later prompt cites. Do not start anything concurrently with it.
 2. After it completes, dispatch the remaining host-chain groups **serially** and the self-contained groups **concurrently alongside them**.
-3. **A self-contained group's prompt must state that it may not edit the entry page or shared VM/Model.** If it discovers it genuinely needs to, it must report that instead of writing — the parent then does the wiring after the concurrent group completes, or reclassifies the group as host-chain on a later run. This is what keeps the static classification true at runtime.
+3. **A self-contained group's prompt must state that it may not edit the entry page or shared VM/Model.** If it discovers it genuinely needs to, it must report that instead of writing — the parent then does that wiring in **Step 5.5**, or reclassifies the group as host-chain on a later run. This is what keeps the static classification true at runtime.
 4. **`batch_progress.json` writes must be serialized by the parent.** Never let a sub-agent write it. Read-modify-write it yourself, one group at a time, after each group returns.
 5. If any group's actual write set turns out to violate its classification, treat the batch's parallel assumption as broken: finish serially and record it, so the next run classifies correctly.
 
 When in doubt, serialize — a wrong parallel call costs a corrupted file and a re-run, which is worse than the time saved.
 
+### Step 5.5 — Parent Wiring (after all groups return, before Step 6)
+
+Self-contained groups write only their own component files — Scheduling rule 3 forbids their sub-agents from editing the entry page or shared VM/Model. That makes wiring each component into its host **the parent's job, and no one else's**: import the component in the host page, instantiate it, add a `@Local` show flag, and bind the trigger (the button / icon / menu entry that opens it) to toggle that flag; navigation-bearing triggers get `router.pushUrl`. A trigger that still calls a placeholder ViewModel method is unwired.
+
+This was previously a subordinate clause in Scheduling rule 3, protected by no gate — and the failure is silent: every component file legal, the build green, resource checks green, while every trigger on the host page does nothing (observed: 11 components converted, 0 responsive icons). Hence the numbered step.
+
+**Mechanical gate:** run `scripts/arkts_static_check.js`; GATE `orphan-component` (an exported struct that no file imports and no file instantiates can never render) must be **zero** before Step 6 begins. Wire components until it is.
+
 ## Step 6 — Unified Build Fix
 
 ### Step 6.0 — Static check first (cheap, runs before the build)
@@ -374,6 +383,8 @@ Three `[GATE]` rules read the *content* of referenced SVGs rather than the code,
 
 One `[GATE]` rule catches a defect that survives the entire pipeline otherwise: `entry-route-not-converted`. Registering a page in `main_pages.json` only makes it *routable*; what determines the launch screen is `loadContent()` in the `UIAbility`. When those disagree, every page converts correctly, the build succeeds, reference checks pass — and launching the app shows the DevEco scaffold's Hello World, with the converted work never displayed at all. The rule fires only when the project already contains converted pages, so a not-yet-converted project is not nagged.
 
+Another `[GATE]` rule closes the assembly gap that `entry-route-not-converted` cannot see: `orphan-component`. A self-contained dialog or sheet component is written by a sub-agent forbidden to touch the host page; until the parent wires it in (Step 5.5), it is a legal file that nothing can ever render — every other check green, every trigger dead. The rule fires when an exported struct appears in no import and no instantiation, so an unwired batch cannot reach the build.
+
 Two of its GATE rules exist purely to turn a **compile error** into a sub-second lexical hit, so running the checker before the first build (not after it fails) is now worth real wall clock: `state-name-shadows-attribute` — a state field named `size`/`width`/`margin`/… collides with the `CustomComponent` base method, and the compiler's `10505001` text talks about type assignability while never hinting "rename it"; and `builder-invokes-callback-param` — a `@Builder` taking a `() => void` param and invoking it bare, which is `10905204`. Measured on one page: those two classes were **6 of the 8 errors in the first build**, each build round trip costing 45-70s against under a second for the checker. Both recur across pages — `size` is the most natural name any icon component reaches for.
 
 - **`[GATE]`** — zero-ambiguity defects. **Fix every one before building.** Doing this first is a real saving: an unterminated JSDoc block (a `*/` sequence inside a comment, e.g. from writing an evidence path like `foo_*/view.xml`) makes the compiler emit *hundreds* of errors whose line/column coordinates point into comment prose, so diagnosing it from build output means reverse-engineering phantom errors. The checker names it directly. Also gated: `$r()` template strings, `width('100%')` + horizontal margin on one element, V1/V2 paradigm mixing, `@ObservedV2`/`@Trace` used without its partner, missing window layer while pages declare `expandSafeArea`, and literal quote leakage in `element/string.json`.

package/skills/a2h-ui-transfer/scripts/arkts_static_check.js

@@ -31,6 +31,14 @@
  * 检查全过,唯一症状是启动后停在脚手架的 Hello World,转换成果一次也没显示过 ——
  * 只有真机启动能看见,但判据完全是词法的,故定为 GATE。
  * 它以「工程内已有转换产出页」为前提:空工程加载脚手架页是正确状态,不报。
+ *
+ * R13(orphan-component)针对第三个同源模式:**「写出来了」不等于「接上去了」**。
+ * 调度器把对话框/面板组判为 self-contained 时,子代理只写自己的组件文件、被禁止
+ * 改宿主页,接线责任落在父代理「并发组完成后的统一接线」上 —— 而那一步没有任何
+ * 门禁保护。一旦父级跳过:每个组件文件都合法、编译通过、资源闭环全绿,宿主页的
+ * 触发按钮却什么都不做,唯一症状是真机上「图标点了没反应」。判据完全词法:
+ * 非 @Entry 文件里 export struct 的名字,未出现在任何 import 中、也未在本文件内
+ * 实例化 —— 该组件永远不可能被渲染。同为 GATE。
  */
 
 import * as fs from 'fs';
@@ -1302,6 +1310,77 @@ function checkEntryRoute(scans, etsDir) {
   }
 }
 
+/**
+ * GATE R13:孤儿组件 —— 已导出的自定义组件从未被 import,也从未在本文件内实例化。
+ *
+ * 失效模式(实测):批调度把对话框/底部弹窗/菜单组判为 self-contained,每个子代理
+ * 只写自己的 `components/Xxx.ets` 且被禁止改宿主页;接线是父代理在并发组完成后的
+ * 职责,但该步骤无门禁。父级一旦跳过,产出「每个零件都合格、但没装配」的工程:
+ * 组件文件合法、编译通过、资源引用闭环全绿 —— 宿主页触发按钮调用的还是占位逻辑,
+ * 症状只有真机上「点了没反应」。和 R11 同源:编译门禁抓不到、判据却纯词法。
+ *
+ * 判据(全部词法,零歧义):
+ *   文件不含 @Entry(经 main_pages.json 路由加载的页不需要被 import);
+ *   且其中 `export struct X` 的名字 X:
+ *     (1) 未出现在任何文件的 import 语句中(ArkTS 里 struct 非全局,不 import 就用不到);
+ *     (2) 也未在本文件内实例化(排除「导出仅供测试、本文件自用」的合法形态)。
+ *
+ * 豁免与边界:
+ *   - @Entry 文件整体豁免:入口 struct 靠路由加载,同文件的辅助 struct 通常由入口消费;
+ *   - 别名导入(`import { X as Y }`)按消费 X 计(取 as 之前的名字);
+ *   - `import type` 不算消费 —— 类型导入无法让组件渲染;
+ *   - 组件被另一个孤儿组件 import 时不报被引用方,只报顶层孤儿(责任指向可操作的那一层);
+ *   - 前置条件:工程内至少存在一个 @Entry 文件 —— 纯库模块(无页面)不适用本判据。
+ */
+function checkOrphanComponents(scans) {
+  if (!scans.some((s) => /@Entry\b/.test(s.text))) {
+    return;
+  }
+
+  // 1. 汇总所有 import 进来的名字(跨文件消费面)
+  const namedImportRe = /import\s+(?:[A-Za-z_$][\w$]*\s*,\s*)?\{([^}]*)\}\s*from/g;
+  const defaultImportRe = /import\s+([A-Za-z_$][\w$]*)\s+from/g;
+  const importedNames = new Set();
+  for (const s of scans) {
+    let m;
+    namedImportRe.lastIndex = 0;
+    while ((m = namedImportRe.exec(s.text)) !== null) {
+      // [^}]* 覆盖多行 import;`X as Y` 取 X(消费的是导出名)
+      for (const part of m[1].split(',')) {
+        const name = part.trim().split(/\s+as\s+/)[0].trim();
+        if (name !== '') { importedNames.add(name); }
+      }
+    }
+    defaultImportRe.lastIndex = 0;
+    while ((m = defaultImportRe.exec(s.text)) !== null) {
+      importedNames.add(m[1]);
+    }
+  }
+
+  // 2. 逐文件找未被消费的 export struct
+  for (const s of scans) {
+    if (/@Entry\b/.test(s.text)) { continue; }
+    const lines = s.text.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const dm = /export\s+struct\s+([A-Za-z_$][\w$]*)/.exec(lines[i]);
+      if (dm === null) { continue; }
+      const name = dm[1];
+      if (importedNames.has(name)) { continue; }
+      // 本文件内自用:声明行之外的 `Name(` 实例化(ArkUI 组件实例化形态 Name() / Name({...}))
+      let selfUsed = false;
+      const useRe = new RegExp('\\b' + name + '\\s*\\(');
+      for (let j = 0; j < lines.length; j++) {
+        if (j !== i && useRe.test(lines[j])) { selfUsed = true; break; }
+      }
+      if (selfUsed) { continue; }
+      report('GATE', 'orphan-component', s.rel, i + 1,
+        `导出的自定义组件 '${name}' 未被任何文件 import,也未在本文件内实例化 —— ` +
+        '它永远无法被渲染。self-contained 调度的对话框/面板组件必须在宿主页' +
+        '(或父级接线阶段)被 import 并挂到触发器上;若确为预留,请移出本批转换产物');
+    }
+  }
+}
+
 /**
  * GATE R12: 代码字面尺寸与 measure_pack.json 实测值偏差超阈值。
  *
@@ -1561,6 +1640,7 @@ function main() {
     checkAndroidImmersive(scans, androidDir);
   }
   checkEntryRoute(scans, etsDir);
+  checkOrphanComponents(scans);
 
   // GATE R12: 代码字面尺寸与 measure_pack 实测偏差超阈值。
   // --ui-info 显式指定 ui_info_root;不给时按 SKILL.md 的默认位置

package/skills/hmos-convert-pipeline/SKILL.md

@@ -58,6 +58,8 @@ The pipeline's sub-agents resolve each setting from the **OS environment variabl
 
 For each value, if the env var is unset, **ask the user**: for the DevEco path / model api_key, **ask the user** (for the api_key they may instead pass `skip_test=true`). Suggest setting the corresponding machine environment variable directly (`DEVECO_SDK_HOME` / `HOMETRANS_MODEL_API_KEY` / `HOMETRANS_TOOL_PATH`).
 
+**External skill dependency.** Stage 2, 3b, and 4b delegate the signed build to the `a2h-fix-build-errors` skill, which is **not bundled in this plugin edition** — it ships with the broader HomeTrans distribution. Verify it is available in the same upfront pass; if it is not, stop and tell the user rather than substituting a guessed `hvigor` invocation. Every build gate in this pipeline (and the `AUTHORITATIVE_ENTRY` / `CURRENT_HAP` handoffs that depend on it) assumes a real signed build actually ran.
+
 ---
 
 ## Progress Tracking
@@ -163,10 +165,10 @@ For the Stage 4 loop, combine test and fix results into one row per round plus o
 Several stages below need the **full signed package set** — the entry HAP plus any in-app HSPs (and any feature HAP the build freshly produced) — so the self-tester installs them in one `hdc install -r` transaction (in-app HSPs cannot install standalone). Those stages call this procedure.
 
 **Inputs:**
-- `BUILD_ROOT` — the project root rebuilt by `hmos-fix-build-errors` (= `HMOS`).
+- `BUILD_ROOT` — the project root rebuilt by `a2h-fix-build-errors` (= `HMOS`).
 - `DEST` — a dedicated `package-set/` directory to populate; **must never be the directory where you mirror the authoritative entry HAP** (step 1 clears `DEST`).
 - `BUILD_START` — a marker captured **immediately before** invoking the build stage, e.g. `touch "<DEST>/../.build_start_marker"` (or record a timestamp). Used to tell freshly-rebuilt artifacts from stale ones. A touched marker + `find -newer` avoids clock-skew between the build stage and the host.
-- `AUTHORITATIVE_ENTRY` — the authoritative signed entry HAP resolved directly from `HMOS/entry/build/default/outputs/default/` after `hmos-fix-build-errors` succeeds. Once resolved for the stage, treat it as authoritative regardless of mtime.
+- `AUTHORITATIVE_ENTRY` — the authoritative signed entry HAP resolved directly from `HMOS/entry/build/default/outputs/default/` after `a2h-fix-build-errors` succeeds. Once resolved for the stage, treat it as authoritative regardless of mtime.
 
 **Procedure:**
 1. **Clear/create `DEST`** (remove prior contents, recreate) so stale packages never leak forward. `DEST` is a dedicated `package-set/` subdir, distinct from the location where you mirror the authoritative entry for this stage.
@@ -216,7 +218,7 @@ Prompt format (applies to both Stage 1 and Stage 1a): ONLY the key-value lines b
 
 ### Stage 2 — Compilation and Build
 
-1. Invoke the `hmos-fix-build-errors` skill for a signed build of `HMOS`.
+1. Invoke the `a2h-fix-build-errors` skill for a signed build of `HMOS`.
 2. Capture `BUILD_START` just before invoking the skill.
 3. Treat the build stage as a compile/fix gate only — do **not** expect build-stage report or commit-info artifacts.
 4. After a successful build, resolve `AUTHORITATIVE_ENTRY` directly from `HMOS/entry/build/default/outputs/default/` (prefer `entry-default-signed.hap`, else the first `*-signed.hap`) and note it in the manifest.
@@ -267,7 +269,7 @@ For each `review_round` from `1..MAX_ROUNDS_REVIEW`, set `REVIEW_ROUND_DIR = OUT
 ##### Review Round Step B — Stage 3b Rebuild after Review Fix
 
 1. Mark Stage 3b `in_progress` when the first Stage 3b round begins.
-2. Capture `BUILD_START` (touch a marker), then invoke the `hmos-fix-build-errors` skill for a signed rebuild of `HMOS`.
+2. Capture `BUILD_START` (touch a marker), then invoke the `a2h-fix-build-errors` skill for a signed rebuild of `HMOS`.
 3. Treat this as a compile/fix gate only — do **not** expect a rebuild report artifact in `REVIEW_ROUND_DIR`.
 4. If the build succeeds, resolve `AUTHORITATIVE_ENTRY` directly from `HMOS/entry/build/default/outputs/default/` (prefer `entry-default-signed.hap`, else the first `*-signed.hap`), note it in the manifest, and **then run Package-Set Collection** with `BUILD_ROOT = HMOS`, `DEST = REVIEW_ROUND_DIR/package-set/`, the resolved `AUTHORITATIVE_ENTRY`, and the captured `BUILD_START`; on success set `LAST_GOOD_REVIEW_SET = REVIEW_ROUND_DIR/package-set/`. **If the 3b build failed, do NOT run collection and keep the previous `LAST_GOOD_REVIEW_SET`** (a failed rebuild leaves stale sibling-module outputs on disk; the mtime gate already prevents harvesting them, and skipping collection avoids re-touching `LAST_GOOD_REVIEW_SET` with an entry-less set).
 5. Append one Defect Summary row for this round using the parsed Stage 3 stats, labeled `3 Loop - Round {review_round}`.
@@ -374,7 +376,7 @@ For each `round` from `1..MAX_ROUNDS_TEST`, set `ROUND_DIR = OUTPUT/round-{round
 ##### Round Step C — Stage 4b Rebuild after Self-Test Fix
 
 1. Mark Stage 4b `in_progress` when the first Stage 4b round begins.
-2. Capture `BUILD_START` (touch a marker), then invoke the `hmos-fix-build-errors` skill for a signed rebuild of `HMOS`.
+2. Capture `BUILD_START` (touch a marker), then invoke the `a2h-fix-build-errors` skill for a signed rebuild of `HMOS`.
 3. Treat this as a compile/fix gate only — do **not** expect rebuild-stage report or commit-info artifacts in `ROUND_DIR`.
 4. ⚠️ **CRITICAL — Update `CURRENT_HAP` for the next round**: If the build succeeds, resolve `AUTHORITATIVE_ENTRY` directly from `HMOS/entry/build/default/outputs/default/` (prefer `entry-default-signed.hap`, else the first `*-signed.hap`), **run Package-Set Collection** with `BUILD_ROOT = HMOS`, `DEST = ROUND_DIR/package-set/`, that resolved `AUTHORITATIVE_ENTRY`, and the captured `BUILD_START`, and then set `CURRENT_HAP = ROUND_DIR/package-set/` so the next round's Stage 4 self-tester uses the freshly built set. If collection **fails** or yields zero HAPs, **keep the previous `CURRENT_HAP`** (the prior round's full set — fresher than any legacy single-file resolution) and record that this round produced no fresh package set.
 5. Append one Defect Summary row for this round by combining the parsed Stage 4 and Stage 4a results into a single row labeled `4 Loop - Round {round}`.

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

@@ -1,4 +1,4 @@
-# hmos-ui-align
+# hmos-incremental-ui-align
 
 HarmonyOS-Android UI 自动对齐流水线。
 
@@ -73,7 +73,7 @@ HarmonyOS-Android UI 自动对齐流水线。
 在 Claude Code 里直接调用 skill，**把两个工程目录附在需求里**（可作为命名参数，也可在自然语言里说明）：
 
 ```
-/hmos-ui-align android_project_dir: <安卓工程绝对路径> harmony_project_dir: <鸿蒙工程绝对路径>
+/hmos-incremental-ui-align android_project_dir: <安卓工程绝对路径> harmony_project_dir: <鸿蒙工程绝对路径>
 <自然语言需求，描述要对齐的页面+点击路径>
 ```
 
@@ -92,20 +92,20 @@ HarmonyOS-Android UI 自动对齐流水线。
 
 **例 1（单个弹窗对齐）**
 ```
-/hmos-ui-align 鸿蒙版本app(登录状态下，进入首页-点击"AI智能填报"-点击"专业"筛选按钮)
+/hmos-incremental-ui-align 鸿蒙版本app(登录状态下，进入首页-点击"AI智能填报"-点击"专业"筛选按钮)
 得到的弹窗样式和安卓同样路径得到的页面不一致，请修改鸿蒙源码将上述页面与安卓版本完全对齐
 ```
 
 **例 2（补齐缺失页面 + 调真实后台）**
 ```
-/hmos-ui-align 鸿蒙版本app(点击我的-超级会员组件)显示与安卓不一致，且安卓版本在超级会员
+/hmos-incremental-ui-align 鸿蒙版本app(点击我的-超级会员组件)显示与安卓不一致，且安卓版本在超级会员
 上点击"会员中心"会跳到超级会员弹窗页，鸿蒙也没有这页。请修改鸿蒙源码将这些页面与安卓版本
 完全对齐，不要mock数据，调用真实后台数据
 ```
 
 **例 3（多级路径 + 多个页面）**
 ```
-/hmos-ui-align 鸿蒙版本（点击底部高考按钮 -> 带年纪查专业 -> 点击某一具体专业(如临床医学)
+/hmos-incremental-ui-align 鸿蒙版本（点击底部高考按钮 -> 带年纪查专业 -> 点击某一具体专业(如临床医学)
 -> 点击就业分析，到达"专业就业健康度"展示页面）以及在"专业就业健康度"页面上点击"完整数
 据指标"到达的就业健康度详情页都和安卓同一路径的不一致。比较这些页面的差别并将他们在视觉
 效果上完全对齐，不要用mock数据，调用后台真实逻辑
@@ -164,7 +164,7 @@ skill 会严格按 `SKILL.md` 里的流水线跑：
 - 每个尺寸 / icon / alignment 都要回溯到安卓源码的 XML 或资源值，不允许"看起来差不多"
 
 ### Step 4 · 编译校验
-若可用，调 `hmos-fix-build-errors` skill 确保工程能编过。**不会自动部署**。
+若可用，调 `a2h-fix-build-errors` skill 确保工程能编过。**不会自动部署**。
 
 ---
 
@@ -230,7 +230,7 @@ A: 可以。Step 2.2 会改从鸿蒙源码读，Step 3 会按安卓的实现规
 A: Step 1.3 默认扫描交互元素（tab / 弹窗 / 展开收起等）并递归采集。想关掉请在需求里写「只对齐主页面」。
 
 **Q: 改完会自动部署吗？**
-A: 不会。Step 4 只跑编译验证（如果 `hmos-fix-build-errors` skill 可用）。部署自己来。
+A: 不会。Step 4 只跑编译验证（如果 `a2h-fix-build-errors` skill 可用）。部署自己来。
 
 **Q: 能不能只做差异分析、不改码？**
 A: 目前流水线是端到端的。如果只想要分析产物，跑完 Step 2 后手动中断即可，所有 `UI_Analysis.md` 和 `UI_comparison.md` 都会落盘在 `{capture_output_dir}/task_{timestamp}/` 下。

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

@@ -351,7 +351,7 @@ Read `fix_checklist.md` and verify every item is marked `[x]`. If any items rema
 **Coverage re-check**: For each page, the `<!-- source: ... | items=N -->` comment records how many items the script extracted. Confirm the number of `- [x]`/`- [~]` lines under each page heading still matches that `items=N` count — if fewer, items were silently dropped during the review pass; recover them from the page's `UI_comparison.md`.
 
 ## Step 4 validate and build (Main Agent)
-if available, use `hmos-fix-build-errors` skill to verify the project is compilable, do not deploy.
+if available, use `a2h-fix-build-errors` skill to verify the project is compilable, do not deploy.
 
 ## Guidelines
 - **Preserve existing code**: When editing existing files, make targeted edits — never rewrite an entire file from scratch. Respect the existing code structure, variable names, and patterns.

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

@@ -28,7 +28,7 @@ Based on the diff analysis, flexibly combine editing and creation as needed —
 
 **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
+- If a needed resource does not exist, use the **`a2h-resource-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

package/skills/hmos-spec-generate/SKILL.md

@@ -36,7 +36,7 @@ You are a **Spec Generator** that produces high-quality requirement specificatio
 
 ## Expected Output
 
-- One markdown spec file per requirement split out of `requirement_description_file`, written under `spec_output_dir` as **`<feature>-SPEC.md`**, where `<feature>` is the requirement title. The `-SPEC.md` suffix is required by the downstream `hmos-test-case-generation` skill, which only accepts a `spec-path` ending in it.
+- One markdown spec file per requirement split out of `requirement_description_file`, written under `spec_output_dir` as **`<feature>-SPEC.md`**, where `<feature>` is the requirement title. The `-SPEC.md` suffix is required by the downstream `a2h-test-case-generation` skill, which only accepts a `spec-path` ending in it.
 
 ---
 
@@ -365,7 +365,7 @@ These are the authoring rules the final spec MUST follow:
 ### Step 0 — Validate inputs and split requirements
 
 1. Verify `requirement_description_file` exists and is a readable file, then split its content into individual requirements by input type. Keep each requirement's text verbatim and record them in order; do NOT analyze them yet. If no requirement can be extracted, stop and report the error.
-   - **Excel type (`.xlsx` / `.xlsm` / `.csv`)**: run `node <skill-dir>/scripts/parse_requirements.ts --input <requirement_description_file> --json` via `Bash` to read the file content. Each item of the returned JSON array is one raw requirement: `uiPath` is the title, `description` is the requirement body. If the script errors, surface it verbatim and stop.
+   - **Excel type (`.xlsx` / `.xlsm` / `.csv`)**: run `node <skill-dir>/scripts/parse_requirements.mjs --input <requirement_description_file> --json` via `Bash` to read the file content. Each item of the returned JSON array is one raw requirement: `uiPath` is the title, `description` is the requirement body. If the script errors, surface it verbatim and stop.
    - **Text type (`.txt` / `.md`)**: read the content directly and split it into individual requirements (each requirement starts with a title line followed by its description; requirements are separated by blank lines).
 2. Verify `android_project_dir` exists and is a directory.
 3. Ensure `spec_output_dir` exists (create it if it does not).