android2harmony 0.1.4 → 0.1.6

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

@@ -0,0 +1,741 @@
+/**
+ * app_identity.js —— 应用标识（应用图标 + 应用名）迁移。
+ *
+ * 为什么单独一个脚本：a2h_resource_convert.js 把 mipmap 图标和 app_name 字符串
+ * 都转成了 HarmonyOS 资源，但它们全部落在 `<ui_module>/src/main/resources` 下，
+ * 而桌面图标与应用名由 `AppScope/app.json5` 决定，其 `$media:` / `$string:`
+ * 解析域是 `AppScope/resources`，不是 entry 模块。加上没有任何环节解析过
+ * AndroidManifest 的 `android:icon` / `android:label`（也就无从知道哪个 mipmap
+ * 才是启动图标），结果是素材都在、配置仍是 DevEco 模板默认值：默认图标 + "label"。
+ *
+ * 这个缺口过不了任何既有 gate：主转换的校验都是存在性/保真度检查，而模板里的
+ * `$media:layered_image` 指向模板自带的合法文件，引用检查照样全绿。所以本脚本
+ * 自带 `--check`，把「配置确实指向了 Android 侧那个图标/名字」变成可阻塞的判定。
+ *
+ * 无第三方依赖（本包 dependencies 恒为空）。json5 一律定点正则改写字符串值，
+ * 不做 parse + 重新序列化：模板注释和缩进要原样保留，diff 也才看得懂。
+ *
+ * 用法：
+ *   node app_identity.js --manifest <decoded>/AndroidManifest.xml --res <decoded>/res \
+ *       --harmony <harmony_project_dir> --ui-module <ui_module> \
+ *       --json <work_dir>/app_identity.json [--dry-run] [--quiet]
+ *   node app_identity.js --check --json <work_dir>/app_identity.json
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const TAG = '[app_identity]';
+
+function fail(msg) {
+  console.error(`${TAG} ${msg}`);
+  process.exit(2);
+}
+
+// ─────────────────────────────────────────────
+// 常量表（与 a2h_resource_convert.js 保持一致）
+// ─────────────────────────────────────────────
+
+/** Android 密度限定符 → HarmonyOS 密度限定符。见 conversion-rules.md「Density Qualifiers」。 */
+const DENSITY = {
+  ldpi: 'sdpi', mdpi: 'mdpi', tvdpi: 'ldpi', hdpi: 'ldpi',
+  xhdpi: 'xldpi', xxhdpi: 'xxldpi', xxxhdpi: 'xxxldpi',
+  nodpi: null, anydpi: null,
+};
+
+/** 取「最像原图」的一份拷进 AppScope：AppScope 侧只需要一个源文件。 */
+const DENSITY_RANK = ['xxxhdpi', 'xxhdpi', 'xhdpi', 'hdpi', 'tvdpi', 'mdpi', 'ldpi', 'nodpi', 'anydpi', ''];
+
+const STRIP_RE = /^(v\d+|ldrtl|ldltr|round|notround|highdr|lowdr|long|notlong)$/;
+const SKIP_RE = /^(sw\d+dp|w\d+dp|h\d+dp|small|normal|large|xlarge)$/;
+const ORIENTATION = { land: 'horizontal', port: 'vertical' };
+const COLORMODE = { night: 'dark', notnight: 'light' };
+const DEVICE = { watch: 'wearable', television: 'tv', car: 'car', desk: 'phone', appliance: 'phone' };
+
+const IMAGE_EXT = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp', '.svg']);
+
+// ─────────────────────────────────────────────
+// 极简 XML 解析（只覆盖 manifest / values / adaptive-icon 需要的语法）
+// ─────────────────────────────────────────────
+
+const ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ' };
+
+function decodeEntities(s) {
+  return s.replace(/&(#x?[0-9a-fA-F]+|[a-zA-Z]+);/g, (m, body) => {
+    if (body[0] === '#') {
+      const code = body[1] === 'x' || body[1] === 'X'
+        ? parseInt(body.slice(2), 16)
+        : parseInt(body.slice(1), 10);
+      return Number.isFinite(code) ? String.fromCodePoint(code) : m;
+    }
+    return ENTITIES[body] ?? m;
+  });
+}
+
+function parseXml(src) {
+  let i = 0;
+  const n = src.length;
+
+  function skipUntil(marker) {
+    const at = src.indexOf(marker, i);
+    i = at < 0 ? n : at + marker.length;
+  }
+
+  function parseAttrs(end) {
+    const attrs = {};
+    const re = /([^\s=/>]+)\s*=\s*("([^"]*)"|'([^']*)')/g;
+    const slice = src.slice(i, end);
+    let m;
+    while ((m = re.exec(slice)) !== null) attrs[m[1]] = decodeEntities(m[3] ?? m[4] ?? '');
+    return attrs;
+  }
+
+  function parseNode() {
+    while (i < n) {
+      const lt = src.indexOf('<', i);
+      if (lt < 0) return null;
+      i = lt;
+      if (src.startsWith('<!--', i)) { skipUntil('-->'); continue; }
+      if (src.startsWith('<?', i)) { skipUntil('?>'); continue; }
+      if (src.startsWith('<!DOCTYPE', i) || src.startsWith('<!', i)) { skipUntil('>'); continue; }
+      if (src.startsWith('</', i)) return null;
+      break;
+    }
+    if (i >= n) return null;
+
+    const gt = src.indexOf('>', i);
+    if (gt < 0) return null;
+    const selfClosing = src[gt - 1] === '/';
+    const head = src.slice(i + 1, selfClosing ? gt - 1 : gt);
+    const name = head.split(/[\s/]/, 1)[0];
+    const attrs = parseAttrs(gt);
+    i = gt + 1;
+
+    const node = { name, attrs, children: [], inner: '' };
+    if (selfClosing) return node;
+
+    const innerStart = i;
+    while (i < n) {
+      const lt = src.indexOf('<', i);
+      if (lt < 0) { i = n; break; }
+      if (src.startsWith('<![CDATA[', lt)) { i = lt; skipUntil(']]>'); continue; }
+      if (src.startsWith('<!--', lt)) { i = lt; skipUntil('-->'); continue; }
+      if (src.startsWith(`</${name}`, lt)) {
+        node.inner = src.slice(innerStart, lt);
+        i = src.indexOf('>', lt);
+        i = i < 0 ? n : i + 1;
+        return node;
+      }
+      i = lt;
+      const child = parseNode();
+      if (child) node.children.push(child);
+      else i = lt + 1;
+    }
+    node.inner = src.slice(innerStart);
+    return node;
+  }
+
+  return parseNode() ?? { name: '', attrs: {}, children: [], inner: '' };
+}
+
+/** 属性按 localName 取值（忽略 `android:` 之类的前缀）。 */
+function attr(node, local) {
+  for (const [k, v] of Object.entries(node.attrs)) {
+    if (k === local || k.endsWith(`:${local}`)) return v;
+  }
+  return undefined;
+}
+
+function findChild(node, name) {
+  return node.children.find((c) => c.name === name);
+}
+
+/** Android 字符串字面量 → HarmonyOS 字符串值。剥外层引号那步见 SKILL.md Step 6.11。 */
+function normalizeString(inner) {
+  let s = inner;
+  const cdata = [...s.matchAll(/<!\[CDATA\[([\s\S]*?)\]\]>/g)];
+  if (cdata.length > 0) s = cdata.map((m) => m[1]).join('');
+  s = decodeEntities(s);
+  s = s.replace(/\\(['"@?\\])/g, '$1').replace(/\\n/g, '\n').replace(/\\t/g, '\t');
+  if (s.length >= 2 && s.startsWith('"') && s.endsWith('"')) s = s.slice(1, -1);
+  return s;
+}
+
+// ─────────────────────────────────────────────
+// 限定符
+// ─────────────────────────────────────────────
+
+/**
+ * `values-zh-rCN` / `mipmap-xxhdpi` → HarmonyOS 限定符目录名 + 原始密度段。
+ * 与 a2h_resource_convert.js 的 planQualifiers 同规则，额外回传 density
+ * 原名，供 DENSITY_RANK 择优。
+ */
+function planQualifiers(dirName) {
+  const segs = dirName.split('-');
+  const type = segs[0];
+  let language = '';
+  let script = '';
+  let region = '';
+  let orientation = '';
+  let device = '';
+  let colormode = '';
+  let density = '';
+  let rawDensity = '';
+
+  for (const q of segs.slice(1)) {
+    if (SKIP_RE.test(q)) return { type, dir: '', skip: true, rawDensity };
+    if (STRIP_RE.test(q)) continue;
+    if (q in DENSITY) { rawDensity = q; if (DENSITY[q]) density = DENSITY[q]; continue; }
+    if (q in ORIENTATION) { orientation = ORIENTATION[q]; continue; }
+    if (q in COLORMODE) { colormode = COLORMODE[q]; continue; }
+    if (q in DEVICE) { device = DEVICE[q]; continue; }
+    if (/^b\+/.test(q)) {
+      const parts = q.slice(2).split('+');
+      language = parts[0] ?? '';
+      if (parts[1] && parts[1].length === 4) script = parts[1];
+      if (parts[2]) region = parts[2];
+      continue;
+    }
+    if (/^r(?:[A-Z]{2}|\d{3})$/.test(q) && language) { region = q.slice(1); continue; }
+    if (/^[a-z]{2,3}$/.test(q) && !language) { language = q; continue; }
+  }
+
+  const locale = [language, script, region].filter(Boolean).join('_');
+  const dir = [locale, orientation, device, colormode, density].filter(Boolean).join('-') || 'base';
+  return { type, dir, skip: false, rawDensity };
+}
+
+// ─────────────────────────────────────────────
+// AndroidManifest：应用图标与应用名
+// ─────────────────────────────────────────────
+
+/**
+ * 取 `<application>` 的 android:icon / android:roundIcon / android:label。
+ *
+ * 解码产物里这些属性可能已经被 aapt 解析成字面量（SKILL.md Step 4 说明解码时
+ * id 引用已解析），也可能仍是 `@mipmap/ic_launcher` / `@string/app_name`，
+ * 两种形态都要接：只按引用形态处理会在一半的工程上什么都取不到。
+ */
+function readManifestIdentity(manifestPath) {
+  if (!fs.existsSync(manifestPath)) fail(`--manifest 路径不存在: ${manifestPath}`);
+  const root = parseXml(fs.readFileSync(manifestPath, 'utf8'));
+  const app = root.name === 'application' ? root : findChild(root, 'application');
+  if (!app) fail(`${manifestPath} 中找不到 <application> 元素`);
+  return {
+    icon: attr(app, 'icon') ?? '',
+    roundIcon: attr(app, 'roundIcon') ?? '',
+    label: attr(app, 'label') ?? '',
+  };
+}
+
+/** `@mipmap/ic_launcher` / `@drawable/x` → `ic_launcher`；非引用返回 null。 */
+function drawableRefName(raw) {
+  const m = /^@(?:[a-zA-Z0-9._]+:)?(?:drawable|mipmap)\/(.+)$/.exec(raw || '');
+  return m ? m[1] : null;
+}
+
+/** `@string/app_name` → `app_name`；非引用返回 null。 */
+function stringRefName(raw) {
+  const m = /^@(?:[a-zA-Z0-9._]+:)?string\/(.+)$/.exec(raw || '');
+  return m ? m[1] : null;
+}
+
+// ─────────────────────────────────────────────
+// 解码 res/ 索引
+// ─────────────────────────────────────────────
+
+/**
+ * 扫描 res/ 下所有 drawable* / mipmap* 目录，建立 资源名 → 候选文件列表。
+ * 候选带上原始密度段，便于按 DENSITY_RANK 择优。
+ */
+function indexDrawables(resDir) {
+  const index = new Map();
+  for (const dirName of fs.readdirSync(resDir)) {
+    const abs = path.join(resDir, dirName);
+    if (!fs.statSync(abs).isDirectory()) continue;
+    const q = planQualifiers(dirName);
+    if (q.skip) continue;
+    if (q.type !== 'drawable' && q.type !== 'mipmap') continue;
+    for (const file of fs.readdirSync(abs)) {
+      const ext = path.extname(file).toLowerCase();
+      const name = path.basename(file, path.extname(file)).replace(/\.9$/, '');
+      if (!index.has(name)) index.set(name, []);
+      index.get(name).push({ abs: path.join(abs, file), dirName, ext, rawDensity: q.rawDensity });
+    }
+  }
+  return index;
+}
+
+function bestByDensity(candidates) {
+  const scored = candidates.map((c) => ({ c, rank: DENSITY_RANK.indexOf(c.rawDensity) }));
+  scored.sort((a, b) => (a.rank < 0 ? 99 : a.rank) - (b.rank < 0 ? 99 : b.rank));
+  return scored.length > 0 ? scored[0].c : null;
+}
+
+// ─────────────────────────────────────────────
+// 应用名：所有语言变体
+// ─────────────────────────────────────────────
+
+/**
+ * 在 `res/values…/strings.xml` 里找 `<string name="<key>">`，返回
+ * HarmonyOS 限定符目录 → 值。base 之外的语言变体一并带出：
+ * 应用名是最该本地化的一条字符串，只写 base 等于把多语言丢掉。
+ */
+function collectLabelStrings(resDir, key) {
+  const out = new Map();
+  for (const dirName of fs.readdirSync(resDir)) {
+    const abs = path.join(resDir, dirName);
+    if (!fs.statSync(abs).isDirectory()) continue;
+    const q = planQualifiers(dirName);
+    if (q.skip || q.type !== 'values') continue;
+    for (const file of fs.readdirSync(abs)) {
+      if (path.extname(file).toLowerCase() !== '.xml') continue;
+      const root = parseXml(fs.readFileSync(path.join(abs, file), 'utf8'));
+      for (const el of root.children) {
+        if (el.name !== 'string' || attr(el, 'name') !== key) continue;
+        // 同一限定符下先出现的优先：与主转换的同名冲突处理方向一致
+        if (!out.has(q.dir)) out.set(q.dir, normalizeString(el.inner));
+      }
+    }
+  }
+  return out;
+}
+
+// ─────────────────────────────────────────────
+// json5 定点改写
+// ─────────────────────────────────────────────
+
+/**
+ * 把 `<key>: "<旧值>"` 的字符串值换成 newValue，只在 [from, to) 区间内找。
+ *
+ * 刻意不 parse json5 再序列化：DevEco 模板里的注释会全部丢掉，且整文件重排的
+ * diff 无法审阅。键名可能带引号也可能不带，两种都要匹配；`\b` 保证 `icon`
+ * 不会误命中 `startWindowIcon`。返回改写后的文本与旧值，改不到则 changed=false。
+ */
+function patchJson5Value(text, key, newValue, from = 0, to = text.length) {
+  const region = text.slice(from, to);
+  const re = new RegExp(`((?:"${key}"|'${key}'|\\b${key})\\s*:\\s*)(?:"([^"]*)"|'([^']*)')`);
+  const m = re.exec(region);
+  if (!m) return { text, changed: false, oldValue: null };
+  const oldValue = m[2] ?? m[3] ?? '';
+  if (oldValue === newValue) return { text, changed: false, oldValue, alreadySet: true };
+  const patchedRegion = region.slice(0, m.index)
+    + m[1] + JSON.stringify(newValue)
+    + region.slice(m.index + m[0].length);
+  return { text: text.slice(0, from) + patchedRegion + text.slice(to), changed: true, oldValue };
+}
+
+/** 读 `<key>: "<值>"` 而不改写。--check 用。 */
+function readJson5Value(text, key, from = 0, to = text.length) {
+  const re = new RegExp(`(?:"${key}"|'${key}'|\\b${key})\\s*:\\s*(?:"([^"]*)"|'([^']*)')`);
+  const m = re.exec(text.slice(from, to));
+  return m ? (m[1] ?? m[2] ?? '') : null;
+}
+
+/**
+ * 定位 `abilities: [ { … } ]` 里第一个对象的字节区间。
+ *
+ * module.json5 顶层也有 icon / label（模块自身的），直接全文替换会改错对象，
+ * 所以先框出 abilities[0] 再在区间内改。用括号配对而不是正则：ability 对象内
+ * 嵌套了 skills 数组等结构，正则数不清层级。
+ */
+function firstAbilityRange(text) {
+  const key = /(?:"abilities"|'abilities'|\babilities)\s*:\s*\[/.exec(text);
+  if (!key) return null;
+  let i = key.index + key[0].length;
+  while (i < text.length && /\s/.test(text[i])) i++;
+  if (text[i] !== '{') return null;
+  const start = i;
+  let depth = 0;
+  let inStr = null;
+  for (; i < text.length; i++) {
+    const ch = text[i];
+    if (inStr) {
+      if (ch === '\\') { i++; continue; }
+      if (ch === inStr) inStr = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") { inStr = ch; continue; }
+    if (ch === '{') depth++;
+    else if (ch === '}') { depth--; if (depth === 0) return { start, end: i + 1 }; }
+  }
+  return null;
+}
+
+// ─────────────────────────────────────────────
+// element/string.json 写入
+// ─────────────────────────────────────────────
+
+/** 合并写入一条 string 条目，保留文件里已有的其它条目。 */
+function upsertString(file, name, value, dryRun) {
+  let doc = { string: [] };
+  if (fs.existsSync(file)) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+      if (parsed && Array.isArray(parsed.string)) doc = parsed;
+    } catch (e) {
+      fail(`${file} 不是合法 JSON，无法写入应用名: ${e.message}`);
+    }
+  }
+  const existing = doc.string.find((s) => s && s.name === name);
+  if (existing) existing.value = value;
+  else doc.string.push({ name, value });
+  if (!dryRun) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify(doc, null, 2)}\n`, 'utf8');
+  }
+  return Boolean(existing);
+}
+
+// ─────────────────────────────────────────────
+// 媒体拷贝
+// ─────────────────────────────────────────────
+
+/** 在某个 media 目录里找 `<name>.<任意扩展名>`。 */
+function findMedia(mediaDir, name) {
+  if (!fs.existsSync(mediaDir)) return null;
+  for (const f of fs.readdirSync(mediaDir)) {
+    if (path.basename(f, path.extname(f)) === name) return path.join(mediaDir, f);
+  }
+  return null;
+}
+
+function copyInto(src, destDir, destName, dryRun, written) {
+  const dest = path.join(destDir, destName);
+  if (!dryRun) {
+    fs.mkdirSync(destDir, { recursive: true });
+    fs.copyFileSync(src, dest);
+  }
+  written.push(dest);
+  return dest;
+}
+
+/**
+ * 把 `<name>_layered_image.json` 及其 background / foreground 两层引用到的媒体
+ * 文件一起拷进 AppScope。只拷 json 不拷层文件的话，AppScope 侧引用悬空，
+ * 图标渲染为空白——而 json 本身存在且合法，任何存在性检查都发现不了。
+ */
+function copyLayeredImage(uiMediaDir, appScopeMediaDir, jsonName, dryRun, written, warnings) {
+  const src = path.join(uiMediaDir, jsonName);
+  if (!fs.existsSync(src)) return false;
+  copyInto(src, appScopeMediaDir, jsonName, dryRun, written);
+
+  let doc;
+  try { doc = JSON.parse(fs.readFileSync(src, 'utf8')); }
+  catch (e) { warnings.push(`${jsonName} 解析失败，层文件未随拷: ${e.message}`); return true; }
+  const layers = (doc && doc['layered-image']) || {};
+  for (const layer of ['background', 'foreground']) {
+    const ref = layers[layer];
+    if (typeof ref !== 'string') continue;
+    const m = /^\$media:(.+)$/.exec(ref);
+    if (!m) { warnings.push(`${jsonName} 的 ${layer} 引用 ${ref} 非 $media 形式，未随拷`); continue; }
+    const layerSrc = findMedia(uiMediaDir, m[1]);
+    if (!layerSrc) { warnings.push(`${jsonName} 的 ${layer} 引用 ${m[1]} 在 ui 模块 media 下不存在，未随拷`); continue; }
+    copyInto(layerSrc, appScopeMediaDir, path.basename(layerSrc), dryRun, written);
+  }
+  return true;
+}
+
+// ─────────────────────────────────────────────
+// 主流程
+// ─────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith('--')) fail(`无法识别的参数: ${a}`);
+    const next = argv[i + 1];
+    if (next && !next.startsWith('--')) { args[a.slice(2)] = next; i++; }
+    else args[a.slice(2)] = true;
+  }
+  return args;
+}
+
+function moduleSegs(uiModule) {
+  return uiModule.split(/[\\/]+/).filter(Boolean);
+}
+
+function run(args) {
+  const manifestPath = typeof args.manifest === 'string' ? args.manifest : fail('缺少 --manifest');
+  const resDir = typeof args.res === 'string' ? args.res : fail('缺少 --res');
+  const harmony = typeof args.harmony === 'string' ? args.harmony : fail('缺少 --harmony');
+  const uiModule = typeof args['ui-module'] === 'string' ? args['ui-module'] : 'entry';
+  const dryRun = Boolean(args['dry-run']);
+  if (!fs.existsSync(resDir)) fail(`--res 路径不存在: ${resDir}`);
+
+  const appScope = path.join(harmony, 'AppScope');
+  const appJson5 = path.join(appScope, 'app.json5');
+  const appScopeMedia = path.join(appScope, 'resources', 'base', 'media');
+  const uiResources = path.join(harmony, ...moduleSegs(uiModule), 'src', 'main', 'resources');
+  const uiMedia = path.join(uiResources, 'base', 'media');
+  const moduleJson5 = path.join(harmony, ...moduleSegs(uiModule), 'src', 'main', 'module.json5');
+  if (!fs.existsSync(appJson5)) fail(`找不到 ${appJson5}——确认 --harmony 指向 HarmonyOS 工程根目录`);
+
+  const warnings = [];
+  const written = [];
+  const ident = readManifestIdentity(manifestPath);
+  const drawables = indexDrawables(resDir);
+
+  // ── 应用图标 ──
+  const iconName = drawableRefName(ident.icon) ?? drawableRefName(ident.roundIcon);
+  let appIconRef = null;
+  let startWindowIconRef = null;
+  if (!iconName) {
+    warnings.push(`AndroidManifest 的 <application android:icon> 取值为 "${ident.icon}"，`
+      + '不是 @drawable/@mipmap 引用，无法定位启动图标——应用图标保持原值');
+  } else {
+    const candidates = drawables.get(iconName) ?? [];
+    if (candidates.length === 0) {
+      warnings.push(`启动图标 ${iconName} 在解码 res/ 下找不到任何文件——应用图标保持原值`);
+    } else {
+      // adaptive-icon（`mipmap-anydpi-v26/`）已由主转换产出 layered-image JSON，
+      // 这里复用它；没有 adaptive-icon 才退到最高密度位图。
+      const layeredName = `${iconName}_layered_image.json`;
+      const hasAdaptive = candidates.some((c) => c.ext === '.xml')
+        && copyLayeredImage(uiMedia, appScopeMedia, layeredName, dryRun, written, warnings);
+      if (hasAdaptive) appIconRef = `$media:${iconName}_layered_image`;
+
+      const bitmap = bestByDensity(candidates.filter((c) => IMAGE_EXT.has(c.ext)));
+      if (bitmap) {
+        const destName = `${iconName}${bitmap.ext}`;
+        copyInto(bitmap.abs, appScopeMedia, destName, dryRun, written);
+        startWindowIconRef = `$media:${iconName}`;
+        if (!appIconRef) appIconRef = `$media:${iconName}`;
+      } else if (hasAdaptive) {
+        // 只有 adaptive-icon、没有位图：startWindowIcon 需要单张图片，
+        // 退到 foreground 层（layered JSON 不能直接当 startWindowIcon 用）。
+        const fg = findMedia(appScopeMedia, `${iconName}_foreground`)
+          ?? findMedia(uiMedia, `${iconName}_foreground`);
+        if (fg) startWindowIconRef = `$media:${path.basename(fg, path.extname(fg))}`;
+        else warnings.push(`${iconName} 只有 adaptive-icon 且无 foreground 位图，startWindowIcon 保持原值`);
+      } else {
+        warnings.push(`启动图标 ${iconName} 无可用位图或 layered-image——应用图标保持原值`);
+      }
+    }
+  }
+
+  // ── 应用名 ──
+  const labelKey = stringRefName(ident.label);
+  const labelName = labelKey ?? 'app_name';
+  let appLabelRef = null;
+  let resolvedLabel = null;
+  const labelLocales = [];
+  if (labelKey) {
+    const variants = collectLabelStrings(resDir, labelKey);
+    if (variants.size === 0) {
+      warnings.push(`应用名 @string/${labelKey} 在解码 res/ 的 values 下找不到——应用名保持原值`);
+    } else {
+      for (const [qdir, value] of variants) {
+        upsertString(path.join(appScope, 'resources', qdir, 'element', 'string.json'), labelName, value, dryRun);
+        labelLocales.push(qdir);
+        if (qdir === 'base') resolvedLabel = value;
+      }
+      if (resolvedLabel === null) resolvedLabel = variants.values().next().value;
+      appLabelRef = `$string:${labelName}`;
+    }
+  } else if (ident.label) {
+    // manifest 里写的是字面量（或解码时已被 aapt 解析）：仍要落成资源，
+    // app.json5 的 label 只接受 $string: 引用形式。
+    resolvedLabel = normalizeString(ident.label);
+    upsertString(path.join(appScope, 'resources', 'base', 'element', 'string.json'), labelName, resolvedLabel, dryRun);
+    labelLocales.push('base');
+    appLabelRef = `$string:${labelName}`;
+  } else {
+    warnings.push('AndroidManifest 的 <application> 没有 android:label——应用名保持原值');
+  }
+
+  // ── 回写 AppScope/app.json5 ──
+  const patches = [];
+  let appText = fs.readFileSync(appJson5, 'utf8');
+  for (const [key, value] of [['icon', appIconRef], ['label', appLabelRef]]) {
+    if (!value) continue;
+    const r = patchJson5Value(appText, key, value);
+    appText = r.text;
+    patches.push({
+      file: 'AppScope/app.json5', key, newValue: value,
+      oldValue: r.oldValue, changed: r.changed, alreadySet: Boolean(r.alreadySet),
+    });
+    if (!r.changed && !r.alreadySet) warnings.push(`AppScope/app.json5 中找不到 ${key} 键，未改写`);
+  }
+  if (!dryRun) fs.writeFileSync(appJson5, appText, 'utf8');
+
+  // ── 回写 <ui_module>/src/main/module.json5 的 abilities[0] ──
+  // 这里的 icon / label 解析域是模块自身的 resources，主转换已经写进去了，
+  // 因此只需引用，不需要再拷一份。
+  const abilityPatches = [];
+  if (fs.existsSync(moduleJson5)) {
+    let modText = fs.readFileSync(moduleJson5, 'utf8');
+    const abilityIconName = appIconRef && findMedia(uiMedia, `${iconName}_layered_image`)
+      ? `${iconName}_layered_image`
+      : (iconName && findMedia(uiMedia, iconName) ? iconName : null);
+    const abilityStartIcon = iconName && findMedia(uiMedia, iconName) ? iconName : abilityIconName;
+    // 主转换本该把这个图标写进 ui 模块的 media；找不到说明两步的输入不一致，
+    // 静默跳过等于把「桌面图标是默认值」这个缺陷原样留下——必须报出来。
+    if (iconName && !abilityIconName) {
+      warnings.push(`${iconName} 在 ${uiModule} 的 base/media 下不存在（主转换未产出？），`
+        + 'ability 的 icon/startWindowIcon 未改写');
+    }
+
+    // ability 的 label 引用模块自身的 string.json；主转换通常已写入该键，
+    // 缺失时补一条——否则 module.json5 引用悬空，编译期就报错。
+    if (appLabelRef && resolvedLabel !== null) {
+      const uiStringJson = path.join(uiResources, 'base', 'element', 'string.json');
+      upsertString(uiStringJson, labelName, resolvedLabel, dryRun);
+    }
+
+    const range = firstAbilityRange(modText);
+    if (!range) {
+      warnings.push(`${moduleJson5} 中定位不到 abilities[0]，ability 的 icon/label 未改写`);
+    } else {
+      let offsetDelta = 0;
+      for (const [key, value] of [
+        ['icon', abilityIconName ? `$media:${abilityIconName}` : null],
+        ['label', appLabelRef],
+        ['startWindowIcon', abilityStartIcon ? `$media:${abilityStartIcon}` : null],
+      ]) {
+        if (!value) continue;
+        const r = patchJson5Value(modText, key, value, range.start + offsetDelta, range.end + offsetDelta);
+        if (r.changed) offsetDelta += r.text.length - modText.length;
+        modText = r.text;
+        abilityPatches.push({
+          file: path.posix.join(...moduleSegs(uiModule), 'src/main/module.json5'),
+          key, newValue: value, oldValue: r.oldValue,
+          changed: r.changed, alreadySet: Boolean(r.alreadySet),
+        });
+        if (!r.changed && !r.alreadySet) warnings.push(`module.json5 的 abilities[0] 中找不到 ${key} 键，未改写`);
+      }
+      if (!dryRun) fs.writeFileSync(moduleJson5, modText, 'utf8');
+    }
+  } else {
+    warnings.push(`找不到 ${moduleJson5}——ability 的 icon/label 未改写`);
+  }
+
+  const record = {
+    harmony, uiModule, dryRun,
+    android: { icon: ident.icon, roundIcon: ident.roundIcon, label: ident.label },
+    resolved: {
+      iconName, appIcon: appIconRef, appLabel: appLabelRef,
+      labelName, labelValue: resolvedLabel, labelQualifiers: labelLocales,
+      startWindowIcon: startWindowIconRef,
+    },
+    patches: [...patches, ...abilityPatches],
+    appScopeFilesWritten: written.map((p) => path.relative(harmony, p).split(path.sep).join('/')),
+    warnings,
+  };
+
+  if (typeof args.json === 'string' && !dryRun) {
+    fs.writeFileSync(args.json, `${JSON.stringify(record, null, 1)}\n`, 'utf8');
+  }
+
+  if (!args.quiet) {
+    console.log(TAG + (dryRun ? ' (dry-run)' : ''));
+    console.log(`  Android 图标 / 名字 : ${ident.icon || '(none)'} / ${ident.label || '(none)'}`);
+    console.log(`  app.json5 icon      : ${appIconRef ?? '(未改写)'}`);
+    console.log(`  app.json5 label     : ${appLabelRef ?? '(未改写)'}${resolvedLabel !== null ? ` = "${resolvedLabel}"` : ''}`);
+    console.log(`  应用名限定符        : ${labelLocales.join(', ') || '(none)'}`);
+    console.log(`  AppScope 写入文件   : ${written.length}`);
+    console.log(`  json5 字段改写      : ${[...patches, ...abilityPatches].filter((p) => p.changed).length}`);
+    for (const w of warnings) console.log(`  ⚠️ ${w}`);
+  }
+
+  // 图标或名字任一没落地，就是用户可见的错误产物，按失败退出让调用方必须处理。
+  return appIconRef && appLabelRef ? 0 : 1;
+}
+
+/**
+ * --check：复读两个 json5，确认它们仍指向 record 记录的值，且引用目标真实存在。
+ *
+ * 校验「与 record 一致」而不是「不等于模板默认值」：默认值随 DevEco 版本变化，
+ * 靠猜会漏。record 是本次运行从 AndroidManifest 实际解析出来的结果，比对它
+ * 才能同时抓住「没写成功」和「后续步骤把它改回去了」两种情况。
+ */
+function check(args) {
+  const jsonPath = typeof args.json === 'string' ? args.json : fail('--check 需要 --json <app_identity.json>');
+  if (!fs.existsSync(jsonPath)) fail(`--json 路径不存在: ${jsonPath}（先不带 --check 运行一次）`);
+  const rec = JSON.parse(fs.readFileSync(jsonPath, 'utf8'));
+  const harmony = rec.harmony;
+  const uiModule = rec.uiModule ?? 'entry';
+  const appScope = path.join(harmony, 'AppScope');
+  const uiResources = path.join(harmony, ...moduleSegs(uiModule), 'src', 'main', 'resources');
+  const failures = [];
+
+  /** `$media:x` / `$string:x` 是否能在给定 resources 根下解析到。 */
+  function resolvable(ref, resourcesRoot) {
+    const media = /^\$media:(.+)$/.exec(ref);
+    if (media) {
+      for (const qdir of fs.existsSync(resourcesRoot) ? fs.readdirSync(resourcesRoot) : []) {
+        if (findMedia(path.join(resourcesRoot, qdir, 'media'), media[1])) return true;
+      }
+      return false;
+    }
+    const str = /^\$string:(.+)$/.exec(ref);
+    if (str) {
+      for (const qdir of fs.existsSync(resourcesRoot) ? fs.readdirSync(resourcesRoot) : []) {
+        const f = path.join(resourcesRoot, qdir, 'element', 'string.json');
+        if (!fs.existsSync(f)) continue;
+        try {
+          const doc = JSON.parse(fs.readFileSync(f, 'utf8'));
+          if (Array.isArray(doc.string) && doc.string.some((s) => s && s.name === str[1])) return true;
+        } catch { /* 交给主转换的 JSON 校验去报 */ }
+      }
+      return false;
+    }
+    return false;
+  }
+
+  const appJson5 = path.join(appScope, 'app.json5');
+  if (!fs.existsSync(appJson5)) failures.push(`缺少 ${appJson5}`);
+  else {
+    const text = fs.readFileSync(appJson5, 'utf8');
+    for (const [key, expect] of [['icon', rec.resolved?.appIcon], ['label', rec.resolved?.appLabel]]) {
+      if (!expect) { failures.push(`app.json5 的 ${key} 从未成功写入（本次转换未能从 AndroidManifest 解析出来）`); continue; }
+      const actual = readJson5Value(text, key);
+      if (actual !== expect) failures.push(`AppScope/app.json5 的 ${key} 是 "${actual}"，期望 "${expect}"`);
+      else if (!resolvable(expect, path.join(appScope, 'resources'))) {
+        failures.push(`AppScope/app.json5 的 ${key} = "${expect}" 在 AppScope/resources 下解析不到目标`);
+      }
+    }
+  }
+
+  const moduleJson5 = path.join(harmony, ...moduleSegs(uiModule), 'src', 'main', 'module.json5');
+  if (!fs.existsSync(moduleJson5)) failures.push(`缺少 ${moduleJson5}`);
+  else {
+    const text = fs.readFileSync(moduleJson5, 'utf8');
+    const range = firstAbilityRange(text);
+    if (!range) failures.push(`${moduleJson5} 中定位不到 abilities[0]`);
+    else {
+      for (const p of (rec.patches ?? []).filter((x) => x.file.endsWith('module.json5'))) {
+        const actual = readJson5Value(text, p.key, range.start, range.end);
+        if (actual !== p.newValue) failures.push(`module.json5 abilities[0].${p.key} 是 "${actual}"，期望 "${p.newValue}"`);
+        else if (!resolvable(p.newValue, uiResources)) {
+          failures.push(`module.json5 abilities[0].${p.key} = "${p.newValue}" 在 ${uiModule} 的 resources 下解析不到目标`);
+        }
+      }
+    }
+  }
+
+  for (const rel of rec.appScopeFilesWritten ?? []) {
+    if (!fs.existsSync(path.join(harmony, rel))) failures.push(`记录已写入但文件不存在: ${rel}`);
+  }
+
+  if (!args.quiet) {
+    console.log(`${TAG} --check`);
+    console.log(`  应用图标 : ${rec.resolved?.appIcon ?? '(未写入)'}`);
+    console.log(`  应用名   : ${rec.resolved?.appLabel ?? '(未写入)'}`
+      + (rec.resolved?.labelValue != null ? ` = "${rec.resolved.labelValue}"` : ''));
+    if (failures.length === 0) console.log('  GATE: PASS');
+    else {
+      console.log(`  GATE: FAIL（${failures.length} 项）`);
+      for (const f of failures) console.log(`   ✗ ${f}`);
+    }
+  }
+  return failures.length === 0 ? 0 : 1;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  process.exit(args.check ? check(args) : run(args));
+}
+
+main();