android2harmony 0.1.4 → 0.1.6

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

@@ -0,0 +1,607 @@
+#!/usr/bin/env node
+/**
+ * 代码内定义矢量图标提取与合成工具
+ *
+ * Jetpack Compose 应用的图标来自 `androidx.compose.material:material-icons-*`，
+ * 是 Kotlin 代码生成的 `ImageVector`，编译进 `classes*.dex`，**不进** `res/drawable`，
+ * 也不进 `resources.arsc`。因此本 skill 其余所有基于 `res/` 的步骤都看不见它们：
+ * 转换报告显示「依赖全部满足」，而迁移后的页面一个图标都不显示。
+ *
+ * 本工具做三件事：
+ *   1. 从 `classes*.dex` 字符串池提取图标引用清单（权威范围，含库内部使用）
+ *   2. 从 Android 源码 `.kt` 提取归属（哪个页面用哪个图标）——dex 无法提供
+ *   3. 按确定性规则解析到上游 Material Icons 图形，写出 HarmonyOS `base/media/*.svg`
+ *
+ * 规则依据见 ../references/code-vector-icon-rules.md。
+ *
+ * 零第三方依赖，仅使用 Node 内置模块，可独立分发。
+ * 纯 JavaScript（ESM），直接 `node code_vector_icons.js` 运行，无需编译、无依赖。
+ *
+ * 用法:
+ *   node code_vector_icons.js --dex <decoded apk dir> --out <base/media dir>
+ *                             [--android-src <android_project_dir>]
+ *                             (--fetch | --snapshot <local icons dir>)
+ *                             [--ref <commit>] [--json <report path>]
+ *                             [--attributed-only] [--dry-run] [--quiet]
+ *
+ * --attributed-only: 只为源码中真正引用到的图标产出图形。用于图标库未被 R8 裁剪、
+ *                    整库被打进 APK 的工程（工具会在检测到时给出提示）。
+ *
+ * 退出码:
+ *   0  全部图标解析成功（或无代码内图标）
+ *   1  存在无法解析的图标（必须记入报告的 unmappable 行）
+ *   2  用法错误 / 路径不存在 / 图形来源不可用
+ *
+ * 注意：--attributed-only 主动跳过的图标不算失败，不影响退出码。
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+// ─────────────────────────────────────────────
+// 常量
+// ─────────────────────────────────────────────
+
+/** 上游 google/material-design-icons 固定 commit。移动分支不可复现，必须 pin。 */
+const DEFAULT_REF = '50f0603134ce7b70b2d71b686cc13e8b57ccb74c';
+
+const RAW_BASE = 'https://raw.githubusercontent.com/google/material-design-icons/';
+
+/** Compose 风格 → 上游目录名 / 产物文件名后缀 */
+const STYLE = {
+  Filled: { dir: 'materialicons', suffix: 'filled' },
+  Outlined: { dir: 'materialiconsoutlined', suffix: 'outlined' },
+  Rounded: { dir: 'materialiconsround', suffix: 'round' },
+  Sharp: { dir: 'materialiconssharp', suffix: 'sharp' },
+  TwoTone: { dir: 'materialiconstwotone', suffix: 'twotone' },
+};
+
+/**
+ * dex 字符串池中的图标名。`Icons.Default` 在 dex 中总是记为 `Filled.*`。
+ *
+ * 名字必须以大写字母或 `_` 开头：Compose 图标名是 PascalCase，数字开头的加 `_` 前缀。
+ * 这条约束用于排除 `Outlined.kt` 这类误命中——dex 里存在 Kotlin 源文件名字符串，
+ * 形如 `<Style>.kt`，正好套进图标名的形状。在 Tasks 上实测到 3 例。
+ */
+const DEX_ICON_RE = /(AutoMirrored\.)?(Filled|Outlined|Rounded|Sharp|TwoTone)\.[A-Z_][A-Za-z0-9_]*/g;
+
+/** Kotlin 源码中的图标引用。源码侧才会出现 `Default`，需归一到 `Filled`。 */
+const SRC_ICON_RE = /Icons\.(AutoMirrored\.)?(Filled|Outlined|Rounded|Sharp|TwoTone|Default)\.([A-Z_][A-Za-z0-9_]*)/g;
+
+/**
+ * 上游改过名的图标：Compose 侧沿用旧名，`src/` 下已经是新名。
+ * 只收录实测确认的条目，不猜。
+ */
+const ALIASES = {
+  motorcycle: 'two_wheeler',
+  leave_bags_at_home: 'no_luggage',
+};
+
+/** 判定「图标库未被 R8 裁剪」的阈值：总量大且绝大多数无源码引用。 */
+const UNSHRUNK_MIN_REFS = 300;
+const UNSHRUNK_UNKNOWN_RATIO = 0.8;
+
+/** 上游 SVG 开头的透明占位边界框，无视觉信息，去掉。两种写法都要覆盖。 */
+const GUARD_PATH_RE = /<path\s+d="M0 0h24v24H0(?:V0)?z"\s+fill="none"\s*\/>/g;
+
+const SKIP_DIRS = new Set(['.git', 'build', '.gradle', 'node_modules', '.idea', 'out']);
+
+// ─────────────────────────────────────────────
+// 类型
+// ─────────────────────────────────────────────
+
+// interface IconRef {
+  // /** dex/源码中的原始形式，如 `AutoMirrored.Outlined.Label` */
+  // compose: string;
+  // style: string;
+  // pascal: string;
+  // autoMirrored: boolean;
+  // /** material snake_case 名，如 `label` */
+  // material: string;
+  // category: string | null;
+  // /** 同名多 category 时的备选，需写入 notes */
+  // otherCategories: string[];
+  // upstream: string | null;
+  // media: string | null;
+  // screens: string[];
+  // suggestedPage: string | null;
+  // sourceRefs: string[];
+  // resolved: boolean;
+  // /** 仅在 resolved=false 时填写：为什么没有产出图形 */
+  // reason: string;
+  // /** 必须写进 mapping notes 的事实：改名、多 category、RTL 镜像 */
+  // notes: string[];
+  // bytes?: number;
+// }
+
+// interface Report {
+  // ref: string;
+  // artworkSource: string;
+  // dexDir: string;
+  // androidSrc: string | null;
+  // outDir: string;
+  // /** dex 清单远大于源码引用 → 图标库很可能未被 R8 裁剪，整库被打进包 */
+  // libraryLikelyUnshrunk: boolean;
+  // attributedOnly: boolean;
+  // counts: {
+    // referencesFound: number;
+    // resolved: number;
+    // unresolved: number;
+    // mediaFilesWritten: number;
+    // autoMirrored: number;
+    // screenAttributed: number;
+    // screenUnknown: number;
+  // };
+  // icons: IconRef[];
+// }
+
+// ─────────────────────────────────────────────
+// 工具函数
+// ─────────────────────────────────────────────
+
+function fail(msg) {
+  console.error(`[code_vector_icons] ${msg}`);
+  process.exit(2);
+}
+
+/**
+ * PascalCase → 候选 snake_case（只按大小写边界断词，不碰数字）。
+ *
+ * 数字周围的断词在上游没有统一规则：`Filter1`→`filter_1` 但 `Co2`→`co2`，
+ * `Rotate90DegreesCcw`→`rotate_90_degrees_ccw` 但 `StarPurple500`→`star_purple500`，
+ * `Crop169`→`crop_16_9`。任何固定的数字断词规则都会错一批，所以数字交给
+ * 「去下划线后比对」的索引查找去解决，见 resolveName()。
+ */
+function caseTransform(pascal) {
+  let n = pascal.replace(/^_+/, ''); // Compose 给数字开头的名字加 `_` 前缀：_360 → 360
+  n = n.replace(/(?<=[a-z0-9])(?=[A-Z])/g, '_');
+  n = n.replace(/(?<=[A-Z])(?=[A-Z][a-z])/g, '_');
+  return n.toLowerCase();
+}
+
+/** 索引：既有精确名，也有「去下划线」名，后者吸收全部数字断词差异。 */
+// interface IconIndex {
+  // exact: Map<string, string[]>;
+  // squashed: Map<string, string[]>;
+// }
+
+// interface Resolution {
+  // material: string | null;
+  // categories: string[];
+  // how: string;
+// }
+
+/**
+ * 解析顺序（每一步都是确定性的）：
+ *   1. 大小写边界变换后精确命中
+ *   2. 去下划线后命中（吸收 crop_16_9 / grid_3x3 / star_purple500 这类不规则数字断词）
+ *   3. 上游改名别名表
+ */
+function resolveName(pascal, idx) {
+  const direct = caseTransform(pascal);
+  const exact = idx.exact.get(direct);
+  if (exact) return { material: direct, categories: exact, how: 'exact' };
+
+  const squashed = idx.squashed.get(direct.replace(/_/g, ''));
+  if (squashed && squashed.length > 0) {
+    // squashed 的值是「索引中的规范名」列表；上游仅有 add_chart/addchart 一组重名，
+    // 取字典序首项保证确定性。
+    const canonical = [...squashed].sort()[0];
+    const cats = idx.exact.get(canonical) ?? [];
+    return { material: canonical, categories: cats, how: 'underscore-insensitive' };
+  }
+
+  const alias = ALIASES[direct];
+  if (alias) {
+    const cats = idx.exact.get(alias);
+    if (cats) return { material: alias, categories: cats, how: `alias (upstream renamed ${direct})` };
+  }
+
+  return { material: null, categories: [], how: 'unresolved' };
+}
+
+/** `MoreScreen` → `MorePage`，与 lottie-conversion-rules.md 的页面命名建议保持一致。 */
+function toHarmonyPage(screen) {
+  const base = screen.replace(/(Screen|Activity|Fragment|Tab|Dialog)$/, '');
+  return base ? `${base}Page` : screen;
+}
+
+function walk(dir, ext, out = []) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of entries) {
+    if (e.isDirectory()) {
+      if (!SKIP_DIRS.has(e.name)) walk(path.join(dir, e.name), ext, out);
+    } else if (e.name.endsWith(ext)) {
+      out.push(path.join(dir, e.name));
+    }
+  }
+  return out;
+}
+
+// ─────────────────────────────────────────────
+// 1. 从 dex 提取清单
+// ─────────────────────────────────────────────
+
+function scanDex(dexDir) {
+  const found = new Set();
+  let dexFiles;
+  try {
+    dexFiles = fs.readdirSync(dexDir).filter((f) => /^classes\d*\.dex$/.test(f));
+  } catch {
+    fail(`--dex 目录不可读: ${dexDir}`);
+  }
+  if (dexFiles.length === 0) return found;
+
+  for (const f of dexFiles) {
+    // latin1 保证字节与字符一一对应；DEX 字符串池中这些名字是纯 ASCII。
+    const text = fs.readFileSync(path.join(dexDir, f)).toString('latin1');
+    for (const m of text.matchAll(DEX_ICON_RE)) found.add(m[0]);
+  }
+  return found;
+}
+
+// ─────────────────────────────────────────────
+// 2. 从源码提取归属
+// ─────────────────────────────────────────────
+
+// interface Attribution {
+  // screens: Set<string>;
+  // files: Set<string>;
+// }
+
+function scanSource(srcDir) {
+  const byIcon = new Map();
+  for (const file of walk(srcDir, '.kt')) {
+    let text;
+    try {
+      text = fs.readFileSync(file, 'utf8');
+    } catch {
+      continue;
+    }
+    if (!text.includes('Icons.')) continue;
+
+    const fileBase = path.basename(file, '.kt');
+    for (const m of text.matchAll(SRC_ICON_RE)) {
+      const auto = Boolean(m[1]);
+      const style = m[2] === 'Default' ? 'Filled' : m[2]; // Default 是 Filled 的别名
+      const key = `${auto ? 'AutoMirrored.' : ''}${style}.${m[3]}`;
+
+      // 归属证据优先级：最近的上文 `fun <Name>(` > 文件名
+      const before = text.slice(0, m.index ?? 0);
+      const funMatches = [...before.matchAll(/\bfun\s+([A-Za-z_][A-Za-z0-9_]*)\s*\(/g)];
+      const enclosing = funMatches.length > 0 ? funMatches[funMatches.length - 1][1] : null;
+      const screen =
+        enclosing && /(Screen|Page|Tab|Dialog)$/.test(enclosing) ? enclosing : fileBase;
+
+      let a = byIcon.get(key);
+      if (!a) {
+        a = { screens: new Set(), files: new Set() };
+        byIcon.set(key, a);
+      }
+      a.screens.add(screen);
+      a.files.add(path.relative(srcDir, file).split(path.sep).join('/'));
+    }
+  }
+  return byIcon;
+}
+
+// ─────────────────────────────────────────────
+// 3. 解析到上游图形
+// ─────────────────────────────────────────────
+
+/** name → [category]，排除 `symbols`（Material Symbols 平行副本，目录布局不同）。 */
+function buildIndex(raw) {
+  const exact = new Map();
+  for (const key of Object.keys(JSON.parse(raw))) {
+    const sep = key.indexOf('::');
+    if (sep < 0) continue;
+    const cat = key.slice(0, sep);
+    const name = key.slice(sep + 2);
+    if (cat === 'symbols') continue;
+    const list = exact.get(name);
+    if (list) list.push(cat);
+    else exact.set(name, [cat]);
+  }
+  for (const list of exact.values()) list.sort();
+
+  const squashed = new Map();
+  for (const name of exact.keys()) {
+    const k = name.replace(/_/g, '');
+    const list = squashed.get(k);
+    if (list) list.push(name);
+    else squashed.set(k, [name]);
+  }
+  return { exact, squashed };
+}
+
+function parseRef(compose) {
+  const parts = compose.split('.');
+  const autoMirrored = parts[0] === 'AutoMirrored';
+  const rest = autoMirrored ? parts.slice(1) : parts;
+  return { style: rest[0], pascal: rest[1], autoMirrored };
+}
+
+// ─────────────────────────────────────────────
+// 主流程
+// ─────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith('--')) fail(`无法识别的参数: ${a}`);
+    const key = a.slice(2);
+    const next = argv[i + 1];
+    if (next && !next.startsWith('--')) {
+      args[key] = next;
+      i++;
+    } else {
+      args[key] = true;
+    }
+  }
+  return args;
+}
+
+async function loadArtwork(
+  args,
+  ref,
+) {
+  const snapshot = typeof args.snapshot === 'string' ? args.snapshot : null;
+
+  if (snapshot) {
+    const indexPath = path.join(snapshot, 'update', 'current_versions.json');
+    if (!fs.existsSync(indexPath)) fail(`--snapshot 下缺少 update/current_versions.json: ${indexPath}`);
+    return {
+      index: fs.readFileSync(indexPath, 'utf8'),
+      label: `vendored snapshot: ${snapshot}`,
+      get: async (upstream) => fs.readFileSync(path.join(snapshot, upstream), 'utf8'),
+    };
+  }
+
+  if (!args.fetch) {
+    fail('必须提供 --fetch（常规方式，从 pinned commit 拉取，需要访问 raw.githubusercontent.com）'
+       + ' 或 --snapshot <dir>（仅用于无外网的机器）');
+  }
+
+  const base = `${RAW_BASE}${ref}/`;
+  const res = await fetch(`${base}update/current_versions.json`);
+  if (!res.ok) fail(`拉取上游索引失败: HTTP ${res.status}`);
+  return {
+    index: await res.text(),
+    label: `upstream google/material-design-icons@${ref}`,
+    get: async (upstream) => {
+      const r = await fetch(base + upstream);
+      if (!r.ok) throw new Error(`HTTP ${r.status}`);
+      return r.text();
+    },
+  };
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const quiet = Boolean(args.quiet);
+  const dryRun = Boolean(args['dry-run']);
+
+  const dexDir = typeof args.dex === 'string' ? args.dex : null;
+  const outDir = typeof args.out === 'string' ? args.out : null;
+  const androidSrc = typeof args['android-src'] === 'string' ? args['android-src'] : null;
+  const ref = typeof args.ref === 'string' ? args.ref : DEFAULT_REF;
+  const attributedOnly = Boolean(args['attributed-only']);
+
+  if (!dexDir) fail('缺少 --dex <decoded apk dir>');
+  if (!outDir && !dryRun) fail('缺少 --out <base/media dir>（或使用 --dry-run）');
+  if (!fs.existsSync(dexDir)) fail(`--dex 路径不存在: ${dexDir}`);
+  if (androidSrc && !fs.existsSync(androidSrc)) fail(`--android-src 路径不存在: ${androidSrc}`);
+
+  // 1. 清单
+  const names = scanDex(dexDir);
+  if (names.size === 0) {
+    if (!quiet) console.log('[code_vector_icons] 未在 classes*.dex 中检出代码内定义图标引用。');
+    if (typeof args.json === 'string') {
+      const empty = {
+        ref,
+        artworkSource: 'n/a',
+        dexDir,
+        androidSrc,
+        outDir: outDir ?? '',
+        libraryLikelyUnshrunk: false,
+        attributedOnly,
+        counts: {
+          referencesFound: 0, resolved: 0, unresolved: 0,
+          mediaFilesWritten: 0, autoMirrored: 0,
+          screenAttributed: 0, screenUnknown: 0,
+        },
+        icons: [],
+      };
+      fs.writeFileSync(args.json, `${JSON.stringify(empty, null, 2)}\n`, 'utf8');
+    }
+    process.exit(0);
+  }
+
+  // 2. 归属
+  const attribution = androidSrc ? scanSource(androidSrc) : new Map();
+
+  // 3. 图形来源
+  const artwork = await loadArtwork(args, ref);
+  const index = buildIndex(artwork.index);
+
+  const allNames = [...names].sort();
+  const unknownCount = allNames.filter((n) => !attribution.has(n)).length;
+  const libraryLikelyUnshrunk =
+    allNames.length >= UNSHRUNK_MIN_REFS && unknownCount / allNames.length >= UNSHRUNK_UNKNOWN_RATIO;
+
+  // 未裁剪判定必须在抓取循环之前生效，而不是循环之后才提示。
+  // 循环会为清单里每个名字发一次网络请求并落一个 svg：在未裁剪的 debug dex 上
+  // 这是数千次请求、数十分钟，且产物是整库图标而非应用实际用到的图标。等抓完
+  // 再打印「建议加 --attributed-only」，代价已经付掉了，且 base/media 已被污染，
+  // 必须人工清理后重跑。所以这里直接拒绝，把取舍交回调用方显式表达。
+  if (libraryLikelyUnshrunk && !attributedOnly) {
+    fail(
+      `dex 清单 ${allNames.length} 个图标中有 ${unknownCount} 个在源码中找不到引用` +
+        `（≥${Math.round(UNSHRUNK_UNKNOWN_RATIO * 100)}%），图标库很可能未被 R8 裁剪，整库被打进了 APK。\n` +
+        '  此时 dex 清单不等于「应用实际使用的图标」，照单抓取会产出数千个无用图形并污染 base/media。\n' +
+        '  请二选一：\n' +
+        '    1) 加 --attributed-only，只为源码真正引用到的图标产出图形（推荐）；\n' +
+        '    2) 换用开启了 minify 的 release 包解码目录作为 --dex。',
+    );
+  }
+
+  const icons = [];
+  for (const compose of allNames) {
+    const { style, pascal, autoMirrored } = parseRef(compose);
+    const res = resolveName(pascal, index);
+    const cats = res.categories;
+    const attr = attribution.get(compose);
+    const screens = attr ? [...attr.screens].sort() : [];
+
+    const icon = {
+      compose, style, pascal,
+      autoMirrored,
+      material: res.material ?? caseTransform(pascal),
+      category: cats.length > 0 ? cats[0] : null,
+      otherCategories: cats.slice(1),
+      upstream: null,
+      media: null,
+      screens: screens.length > 0 ? screens : ['Unknown'],
+      suggestedPage: screens.length === 1 ? toHarmonyPage(screens[0]) : null,
+      sourceRefs: attr ? [...attr.files].sort() : [],
+      resolved: false,
+      reason: '',
+      notes: [],
+    };
+
+    if (autoMirrored) {
+      icon.notes.push('AutoMirrored: mirror horizontally under right-to-left locales');
+    }
+    if (!attr) {
+      icon.notes.push('dex-only; no source reference found (likely used by a library)');
+    }
+    if (res.how !== 'exact' && res.material) {
+      icon.notes.push(`name resolved by ${res.how}`);
+    }
+
+    if (!res.material) {
+      icon.reason = 'not found in Material Icons index';
+    } else if (attributedOnly && !attr) {
+      // 图标库未裁剪时，dex 清单包含整个库；只为源码真正引用的图标产出图形，
+      // 其余仍然留行，但标记为不产出。
+      icon.reason = 'packaged by an unshrunk icon library; not referenced by application code';
+    } else {
+      if (cats.length > 1) {
+        icon.notes.push(`ambiguous category, alternatives: ${cats.slice(1).join(', ')}`);
+      }
+      icon.upstream = `src/${cats[0]}/${res.material}/${STYLE[style].dir}/24px.svg`;
+      icon.media = `ic_${res.material}_${STYLE[style].suffix}.svg`;
+    }
+    icons.push(icon);
+  }
+
+  // 4. 取图形并落盘（同一 media 文件只取一次）
+  const wanted = new Map();
+  for (const i of icons) if (i.media && i.upstream) wanted.set(i.media, i.upstream);
+
+  if (outDir && !dryRun) fs.mkdirSync(outDir, { recursive: true });
+
+  const written = new Map();
+  for (const [media, upstream] of wanted) {
+    let body;
+    try {
+      body = await artwork.get(upstream);
+    } catch (e) {
+      for (const i of icons) {
+        if (i.media === media) i.reason = `artwork unavailable: ${(e).message}`;
+      }
+      continue;
+    }
+    if (!body.trimStart().startsWith('<svg') || !body.includes('viewBox="0 0 24 24"')) {
+      for (const i of icons) if (i.media === media) i.reason = 'upstream file is not a 24x24 svg';
+      continue;
+    }
+    const cleaned = `${body.replace(GUARD_PATH_RE, '').trim()}\n`;
+
+    if (outDir && !dryRun) {
+      const target = path.join(outDir, media);
+      // 不覆盖 res/ 转换产出的同名资源：改名并在 notes 记录（见 rules §7）
+      if (fs.existsSync(target)) {
+        const renamed = media.replace(/\.svg$/, '_material.svg');
+        for (const i of icons) {
+          if (i.media === media) {
+            i.media = renamed;
+            i.notes.push(`renamed to avoid collision with a res/-derived media file (${media})`);
+          }
+        }
+        fs.writeFileSync(path.join(outDir, renamed), cleaned, 'utf8');
+        written.set(renamed, { bytes: cleaned.length });
+        continue;
+      }
+      fs.writeFileSync(target, cleaned, 'utf8');
+    }
+    written.set(media, { bytes: cleaned.length });
+  }
+
+  for (const i of icons) {
+    if (i.media && written.has(i.media)) {
+      i.resolved = true;
+      i.bytes = written.get(i.media).bytes;
+    } else if (!i.reason) {
+      i.reason = 'artwork not retrieved';
+    }
+  }
+
+  const unresolved = icons.filter((i) => !i.resolved);
+  const report = {
+    ref,
+    artworkSource: artwork.label,
+    dexDir,
+    androidSrc,
+    outDir: outDir ?? '',
+    libraryLikelyUnshrunk,
+    attributedOnly,
+    counts: {
+      referencesFound: icons.length,
+      resolved: icons.length - unresolved.length,
+      unresolved: unresolved.length,
+      mediaFilesWritten: written.size,
+      autoMirrored: icons.filter((i) => i.autoMirrored).length,
+      screenAttributed: icons.filter((i) => i.screens[0] !== 'Unknown').length,
+      screenUnknown: icons.filter((i) => i.screens[0] === 'Unknown').length,
+    },
+    icons,
+  };
+
+  if (typeof args.json === 'string') {
+    fs.writeFileSync(args.json, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+  }
+
+  if (!quiet) {
+    const c = report.counts;
+    console.log(`[code_vector_icons] artwork: ${artwork.label}`);
+    console.log(`  references found (dex) : ${c.referencesFound}`);
+    console.log(`  resolved               : ${c.resolved}`);
+    console.log(`  unresolved             : ${c.unresolved}`);
+    console.log(`  media files written    : ${c.mediaFilesWritten}${dryRun ? ' (dry-run)' : ''}`);
+    console.log(`  auto-mirrored          : ${c.autoMirrored}`);
+    console.log(`  screen attributed      : ${c.screenAttributed} (unknown: ${c.screenUnknown})`);
+    if (libraryLikelyUnshrunk) {
+      // 走到这里说明已显式加了 --attributed-only（否则上面的闸门已退出）。
+      console.log(
+        '  NOTE: 图标库未被 R8 裁剪，dex 清单包含整库图标；已按 --attributed-only\n' +
+        '        只为源码引用到的图标产出图形，其余留行标记为 unmappable。',
+      );
+    }
+    for (const i of unresolved) {
+      console.log(`  UNRESOLVED  ${i.compose}  (${i.material})  ${i.reason}`);
+    }
+  }
+
+  // --attributed-only 主动跳过的不算失败：它是有意的取舍，且仍然留了记录行。
+  const hardUnresolved = unresolved.filter((i) => !i.reason.startsWith('packaged by an unshrunk'));
+  process.exit(hardUnresolved.length > 0 ? 1 : 0);
+}
+
+main().catch((e) => fail(String(e && (e).stack ? (e).stack : e)));

package/skills/a2h-resource-convert/scripts/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}