android2harmony 0.1.5 → 0.1.6

package/skills/a2h-resource-convert/SKILL.md

@@ -42,7 +42,20 @@ node ./scripts/a2h_resource_convert.js \
     --ui-module <ui_module> \
     --records <work_dir>/records.json
 
-# 2. Code-defined vector icons — REQUIRED for any Jetpack Compose app (see Step 4.1.3)
+# 2. App identity: launcher icon + app name → AppScope/app.json5 + abilities[0]
+#    Step 1 converts the icon *assets* and the app-name string, but writes them into
+#    <ui_module>/…/resources — while the desktop icon and app name are decided by
+#    AppScope/app.json5, whose $media:/$string: domain is AppScope/resources. Nothing
+#    else reads AndroidManifest's android:icon / android:label either, so without this
+#    step the DevEco template defaults survive: default icon and the name "label".
+#    Runs after step 1 because it reuses the layered-image JSON that step produces.
+node ./scripts/app_identity.js \
+    --manifest <decoded_output_path>/AndroidManifest.xml \
+    --res <decoded_output_path>/res \
+    --harmony <harmony_project_dir> --ui-module <ui_module> \
+    --json <work_dir>/app_identity.json
+
+# 3. Code-defined vector icons — REQUIRED for any Jetpack Compose app (see Step 4.1.3)
 #    --fetch pulls artwork from a pinned upstream commit, never a moving branch.
 #    Requires network access to raw.githubusercontent.com.
 #    Prefer a *minified* (release) APK's decoded dir. On a debug APK the icon library
@@ -54,23 +67,24 @@ node ./scripts/code_vector_icons.js \
     --out <harmony_project_dir>/<ui_module>/src/main/resources/base/media \
     --fetch --json <work_dir>/icons.json
 
-# 3. Vector fidelity gate — any error blocks completion
+# 4. Vector fidelity gate — any error blocks completion
 node ./scripts/svg_fidelity_check.js \
     --android-res <decoded_output_path>/res \
     --harmony-media <harmony_project_dir>/<ui_module>/src/main/resources/base/media \
     --json <work_dir>/fidelity.json
 
-# 4. Documents, rebuilt from the records of step 1 plus the results of steps 2-3
+# 5. Documents, rebuilt from the records of step 1 plus the results of steps 3-4
 node ./scripts/a2h_resource_convert.js --docs-only \
     --records <work_dir>/records.json \
     --icons-json <work_dir>/icons.json --fidelity-json <work_dir>/fidelity.json \
+    --app-identity-json <work_dir>/app_identity.json \
     --report <work_dir>/resource_conversion_report.md \
     --mapping <resource_mapping_path> \
     --apk <apk_path> --android-commit <commit> --app-module <app_module> \
     --harmony <harmony_project_dir>
 ```
 
-Step 4 is separate because the documents need the fidelity and icon results, which in turn need the artifacts step 1 produces. It re-reads `records.json` rather than re-running the conversion.
+Step 5 is separate because the documents need the fidelity and icon results, which in turn need the artifacts step 1 produces. It re-reads `records.json` rather than re-running the conversion.
 
 **What remains your job:**
 
@@ -606,7 +620,7 @@ After resolution, scan all converted resources for any remaining unresolved refe
 
 ### Step 6: Verify Completeness
 
-Items 1-9 and 11 below are performed by `scripts/a2h_resource_convert.js` and reported in `records.json`; items 10 and 12 are the two separate gates (`svg_fidelity_check.js` and `code_vector_icons.js`). Your job is to confirm each one actually ran and to act on what it found — a gate whose output nobody read is not a gate.
+Items 1-9 and 11 below are performed by `scripts/a2h_resource_convert.js` and reported in `records.json`; items 10, 12 and 13 are the three separate gates (`svg_fidelity_check.js`, `code_vector_icons.js` and `app_identity.js`). Your job is to confirm each one actually ran and to act on what it found — a gate whose output nobody read is not a gate.
 
 The checks are:
 
@@ -644,6 +658,15 @@ The checks are:
     c. The pinned snapshot ref used for artwork is recorded in the report and in the mapping document metadata. A run whose artwork came from a moving branch is not reproducible and must be re-run against a pinned ref.
 
     Unlike item 10, a failure here does not block completion — an unresolved icon is a recorded gap, not a corrupt asset. But an *unrecorded* icon does block: it reproduces exactly the defect this step exists to catch.
+13. **App identity (launcher icon + app name), blocking**: items 1-12 all reason about the `<ui_module>` resource tree. The desktop icon and app name live somewhere else — `AppScope/app.json5`, whose `$media:`/`$string:` domain is `AppScope/resources` — and no other item touches them. Run Toolchain step 2's gate:
+
+    ```
+    node ./scripts/app_identity.js --check --json <work_dir>/app_identity.json
+    ```
+
+    It re-reads both `json5` files and requires that `AppScope/app.json5`'s `icon`/`label` and `abilities[0]`'s `icon`/`label`/`startWindowIcon` still hold the values resolved from `AndroidManifest.xml`, and that each reference resolves to a file that exists in the *right* resource root. **`GATE: FAIL` blocks completion** — this is a user-visible wrong product (default icon, app named "label"), not a recorded gap.
+
+    It compares against the recorded values rather than against "not equal to the template default" on purpose: template defaults change between DevEco versions, so a default-value check misses. Note this is the one item existing checks structurally cannot catch — the template's `$media:layered_image` points at a template-supplied file that really exists, so every existence and reference check upstream passes while the icon is still wrong.
 
 **Placeholder SVG template** (for missing media resources):
 ```svg
@@ -656,7 +679,7 @@ Replace `RESOURCE_NAME` with the actual resource name (truncated if too long).
 
 ### Step 7: Generate Report
 
-The report is written by Toolchain step 4 (`--docs-only --report`). It is deliberately **aggregated** so a human can read it end to end: counts by type, qualifier mappings, the full reference-resolution table, unmappable reasons grouped by cause, fidelity findings, code-defined icons, and warnings grouped by kind with a per-kind sample. The exhaustive per-resource listing belongs in the mapping document (Step 8), not here.
+The report is written by Toolchain step 5 (`--docs-only --report`). It is deliberately **aggregated** so a human can read it end to end: counts by type, qualifier mappings, the full reference-resolution table, unmappable reasons grouped by cause, fidelity findings, code-defined icons, and warnings grouped by kind with a per-kind sample. The exhaustive per-resource listing belongs in the mapping document (Step 8), not here.
 
 Your job is to read it and act on what it says — an unresolved reference, a fidelity error, or a target collision is a finding, not a formatting detail.
 
@@ -704,6 +727,12 @@ Libraries declared in the project's build.gradle that may provide resources:
 - Code-defined icon media files written: <count>
 - Code-defined icons screen-attributed / Unknown: <count> / <count>
 - Material Icons snapshot ref: <pinned commit or vendored snapshot path>
+- App icon: <AndroidManifest android:icon> → <AppScope/app.json5 icon value> | "未改写（原因）"
+- App name: <AndroidManifest android:label> → <app.json5 label value> = "<resolved text>" | "未改写（原因）"
+- App name locales written to AppScope: <qualifier dirs, e.g. base, zh_CN>
+- App identity gate: <PASS | FAIL（n 项）>
+
+Take these five lines from `app_identity.json` (Toolchain step 2). `a2h-ui-transfer` greps them as its App-identity gate, so keep the labels verbatim.
 
 ## Conversion Details
 
@@ -836,7 +865,7 @@ Media resources referenced in `.ets` UI code but not found in converted resource
 
 ### Step 8: Generate Resource Mapping Document
 
-The second document, at `resource_mapping_path`, is written by the same Toolchain step 4 invocation (`--mapping`). It is the audit surface: **every** observed Android resource appears as its own row, `values` at entry granularity. It does not sample, summarise, or aggregate — those are the report's job. Expect it to be large (measured range: 4 MB to 22 MB); that size is the cost of the no-omission requirement, and the dataset tracks these files with Git LFS for exactly that reason.
+The second document, at `resource_mapping_path`, is written by the same Toolchain step 5 invocation (`--mapping`). It is the audit surface: **every** observed Android resource appears as its own row, `values` at entry granularity. It does not sample, summarise, or aggregate — those are the report's job. Expect it to be large (measured range: 4 MB to 22 MB); that size is the cost of the no-omission requirement, and the dataset tracks these files with Git LFS for exactly that reason.
 
 Do not hand-write or hand-trim this document. If it looks too large, that is not a reason to sample it.
 

package/skills/a2h-resource-convert/scripts/a2h_resource_convert.js

@@ -1832,6 +1832,25 @@ class DocWriter {
     } else {
       p('- Code-defined vector icons: not analysed (run scripts/code_vector_icons.js)');
     }
+    // 应用图标 / 应用名。这几行 a2h-ui-transfer 会 grep 作为 App-identity gate，
+    // 标签文字不要改。
+    const idn = this.ctx.appIdentity;
+    if (idn) {
+      const r = idn.resolved ?? {};
+      // 原因要按字段挑，不能一律取 warnings[0]：图标的告警贴到应用名那行上，
+      // 读者会照着错的原因去排查。
+      const why = (re) => {
+        const hit = (idn.warnings ?? []).find((w) => re.test(w));
+        return hit ? `未改写（${hit}）` : '未改写';
+      };
+      p(`- App icon: ${idn.android?.icon || '(none)'} → ${r.appIcon ?? why(/图标/)}`);
+      p(`- App name: ${idn.android?.label || '(none)'} → ${r.appLabel ?? why(/应用名|label/)}`
+        + (r.labelValue != null ? ` = "${r.labelValue}"` : ''));
+      p(`- App name locales written to AppScope: ${(r.labelQualifiers ?? []).join(', ') || '(none)'}`);
+      p(`- App identity gate: ${r.appIcon && r.appLabel ? 'PASS' : 'FAIL（应用图标或应用名未落地）'}`);
+    } else {
+      p('- App identity (launcher icon + app name): not run (run scripts/app_identity.js)');
+    }
     p();
 
     p('## Conversion Details');
@@ -2154,6 +2173,7 @@ function emitDocs(
       buildResult: typeof args['build-result'] === 'string' ? args['build-result'] : '(not run by this script)',
       icons: readJson('icons-json'),
       fidelity: readJson('fidelity-json'),
+      appIdentity: readJson('app-identity-json'),
     });
     if (typeof args.report === 'string') fs.writeFileSync(args.report, `${doc.report()}
 `, 'utf8');