android2harmony 0.1.3 → 0.1.5

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

@@ -0,0 +1,1005 @@
+/**
+ * measure_pack.js —— 把「每页都要重算一遍」的参考量测,前移到父流程一次算完。
+ *
+ * 用法(纯 JavaScript ESM,无需编译、无外部依赖):
+ *   node measure_pack.js --ui-info <page_NNNN_X 目录> [--out <file.json>] [--quiet] [--density 2.625]
+ *
+ * --density 显式给出采集设备密度,优先级最高。通常不需要:android_parse_fast.js 已把
+ * `wm density` 的真值写进每页 meta.json 的 device 字段。两者都没有时才退回节点反解。
+ *
+ * ── 为什么存在 ────────────────────────────────────────────────────────────
+ * 实测一次单页转换(96 次工具调用 / 61.4 min):**工具真实执行合计 17.9 秒,占 0.5%**,
+ * 而「拿到工具结果之后的模型思考+生成」占 71.3%(96 轮 × 均值 27.4s)。
+ * 也就是说成本 ≈ 轮次数 × 单轮延迟,压轮次是唯一有意义的加速方向。
+ *
+ * 那次运行里子 agent 为了测密度、ink bbox、取色,跑了 11 轮 PIL(约 5 min)。
+ * 这些量测有两个特点:(a) 同一采集设备上**每页同值**,(b) 判据纯算术、可复算。
+ * 于是它们属于「父侧一次算完、批内摊薄」的活,不该每页各花若干轮重算。
+ *
+ * ── 职责边界(重要) ──────────────────────────────────────────────────────
+ * 本脚本**只做量测与算术,不做判断**。它不推断沉浸式、不推断锚定方向、不给图标分级 ——
+ * 那些需要回读 Android 源码与约束声明,是 Phase 4/5 的事。
+ * 每个输出值都带 `source` 字段标注来源,便于子 agent 引用与父侧复核。
+ *
+ * 参考:conversion-procedure.md Phase 4.1「LAYOUT_EVIDENCE」与 Phase 4.2「坐标与窗口模式规则」。
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+// 静态 import,不能用 require:本文件是 ESM(同目录 package.json 声明 type=module),require 未定义。
+// 用 require 会让 PNG 解码整个失败,而失败点在 try/catch 里 —— 症状是密度算得出、
+// 而 image/edge_colors/ink 全为空,极易被当成「截图有问题」。
+import * as zlib from 'zlib';
+
+// ---------------------------------------------------------------- 类型
+
+// interface Node {
+  // idx: number;
+  // cls: string;
+  // text: string;
+  // rid: string;
+  // desc: string;
+  // clickable: boolean;
+  // scrollable: boolean;
+  // enabled: boolean;
+  // checkable: boolean;
+  // checked: boolean;
+  // x1: number;
+  // y1: number;
+  // x2: number;
+  // y2: number;
+  // w: number;
+  // h: number;
+// }
+
+// interface Png {
+  // width: number;
+  // height: number;
+  // /** RGBA,每像素 4 字节 */
+  // px: Uint8Array;
+// }
+
+// interface InkBox {
+  // x1: number;
+  // y1: number;
+  // x2: number;
+  // y2: number;
+  // w: number;
+  // h: number;
+  // cx: number;
+  // cy: number;
+  // /**
+   // * 背景不均匀(渐变/图片底)时置位。此时本 ink bbox **不可信** ——
+   // * 「与背景有差异」的判据会把渐变本身也算成墨迹,量出来的往往就是整个区域。
+   // */
+  // unreliable?: boolean;
+  // reason?: string;
+  // /** 四角在最差通道上的色值跨度。0 表示纯色底,越大越说明底是渐变/图片。 */
+  // bgSpread?: number;
+// }
+
+// ---------------------------------------------------------------- view.xml
+
+/**
+ * 解析 uiautomator dump。用正则而非 XML 解析器:该格式是扁平的 <node .../> 与嵌套
+ * <node ...> 混用,属性集固定,正则足够且不引依赖。属性顺序不可假定,逐个按名取。
+ */
+function parseNodes(xml) {
+  const out = [];
+  const re = /<node ([^>]*?)\/?>/g;
+  let m;
+  let i = 0;
+  while ((m = re.exec(xml)) !== null) {
+    const a = m[1];
+    const get = (k) => {
+      const r = new RegExp(k + '="([^"]*)"').exec(a);
+      return r ? r[1] : '';
+    };
+    const b = /bounds="\[(\d+),(\d+)\]\[(\d+),(\d+)\]"/.exec(a);
+    if (!b) {
+      i++;
+      continue;
+    }
+    const x1 = parseInt(b[1], 10);
+    const y1 = parseInt(b[2], 10);
+    const x2 = parseInt(b[3], 10);
+    const y2 = parseInt(b[4], 10);
+    out.push({
+      idx: i++,
+      cls: get('class'),
+      text: get('text'),
+      rid: get('resource-id'),
+      desc: get('content-desc'),
+      clickable: get('clickable') === 'true',
+      scrollable: get('scrollable') === 'true',
+      enabled: get('enabled') === 'true',
+      checkable: get('checkable') === 'true',
+      checked: get('checked') === 'true',
+      x1, y1, x2, y2,
+      w: x2 - x1,
+      h: y2 - y1
+    });
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------- 密度反解
+
+// interface DensityEvidence {
+  // node: number;
+  // sidePx: number;
+  // dp: number;
+  // density: number;
+// }
+
+// interface DensityResult {
+  // density: number | null;
+  // /** 'device'=meta.json 里采集期记录的真值 / 'cli'=--density 显式传入 / 'inferred'=由节点边长反解 */
+  // source: 'device' | 'cli' | 'inferred';
+  // /** 反解是否可信:命中 >= 2 个不同 dp 档,且对次优候选有明确优势。真值来源恒为 true。 */
+  // confident: boolean;
+  // /** 次优候选(通常是谐波混叠的那一档)。null=无竞争者。 */
+  // rival: { density: number; hits: number } | null;
+  // /** 真值与反解冲突、或闸门被放开时的告警;正常为 null。 */
+  // crosscheck: string | null;
+  // /** 反解为 null 或低置信时,说明**为什么** —— 否则调用方只看到一个数字/空值,无从处置。 */
+  // reason: string | null;
+  // evidence: DensityEvidence[];
+// }
+
+/** 标准密度档。含 1.75(280dpi)、3.2 —— 真机上这两档存在,漏掉会给出自信的错值。 */
+const STD_DENSITIES = [1, 1.5, 1.75, 2, 2.25, 2.5, 2.625, 2.75, 3, 3.2, 3.5, 4];
+/** Material/AndroidX 的固有尺寸档(dp)。 */
+const COMMON_DP = [16, 20, 24, 28, 32, 36, 40, 44, 48, 56, 64, 72, 80, 96];
+
+// interface DensityScore {
+  // d: number;
+  // hits: number;
+  // residual: number;
+  // dpKinds: number;
+  // std: boolean;
+  // evidence: DensityEvidence[];
+// }
+
+/**
+ * 给每个候选密度打分。`sides` 已按**不同边长**去重(见 deriveDensity)。
+ *
+ * 排序判据:命中数 → 残差 → 标准档 → **大密度优先**。
+ * 最后一档不可反向:小密度总能用更大的 dp 把同一批 px 混叠解释掉(px=72 → 72dp@1.0),
+ * 平局倒向小密度正是旧实现把 3.0 判成 1.0、2.0 判成 1.0 的直接原因。
+ */
+function scoreDensities(
+  sides,
+  shortPx,
+  longPx,
+  useGate
+) {
+  const cands = new Set(STD_DENSITIES);
+  // 候选表不能写死:把「由数据本身反推出来的档」也加进来,才能覆盖非标准档与
+  // `wm density` 改过的设备。落表外时旧实现不报"测不出",而是给出一个自信的错值。
+  for (const s of sides) {
+    for (const dp of COMMON_DP) {
+      const d = Math.round((s.px / dp) * 1000) / 1000;
+      if (d >= 0.9 && d <= 4.5) { cands.add(d); }
+    }
+  }
+  const out = [];
+  for (const d of [...cands].sort((a, b) => a - b)) {
+    // 屏幕尺寸合理性闸门 —— 节点尺寸只能把密度定到一个**谐波族**内(px=72 被
+    // 24dp@3.0 / 36dp@2.0 / 48dp@1.5 / 72dp@1.0 同等解释,纯算术无法区分),
+    // 唯一的独立信息是屏幕换算成 dp 后必须物理存在。
+    //
+    // **两条边都要卡**:只卡短边不够。实测 1080x2274 的 420dpi 机器上,谐波候选
+    // 1.323 的短边是 816dp(像 10 寸平板,短边闸门放过),但长边 1719dp —— 现实中
+    // 最大的平板长边约 1280dp,不存在 1700dp 的竖屏设备。长边闸门一加即被排除。
+    if (useGate && shortPx > 0 && longPx > 0) {
+      const sDp = shortPx / d;
+      const lDp = longPx / d;
+      if (sDp < 300 || sDp > 840) { continue; }   // 手机 320-480,平板竖屏宽到 ~840
+      if (lDp < 480 || lDp > 1400) { continue; }  // 最大真机长边 ~1280,留余量
+    }
+    let residual = 0;
+    const dpKinds = new Set();
+    const evidence = [];
+    for (const s of sides) {
+      let bestR = Infinity;
+      let bestDp = 0;
+      for (const dp of COMMON_DP) {
+        // 在 **px 空间**比,容忍 ±1px:Android 是 px = round(dp × density),反解回来的
+        // dp 误差可达 0.5/d(≈0.19dp @2.625)。在 dp 空间用固定小容差(旧值 0.02)会把
+        // 非整数密度的真命中大量误杀,而整数密度永不受损 —— 系统性偏向 1/2/3/4。
+        const r = Math.abs(s.px - Math.round(dp * d));
+        if (r < bestR) { bestR = r; bestDp = dp; }
+      }
+      if (bestR <= 1) {
+        residual += bestR;
+        dpKinds.add(bestDp);
+        evidence.push({ node: s.idx, sidePx: s.px, dp: bestDp, density: d });
+      }
+    }
+    if (evidence.length > 0) {
+      out.push({
+        d, hits: evidence.length, residual, dpKinds: dpKinds.size,
+        std: STD_DENSITIES.includes(d), evidence
+      });
+    }
+  }
+  // 把相对距离 <= 1.5% 的候选并成一簇 —— 它们描述的是**同一个物理密度**,差异只是
+  // round() 噪声。簇代表优先取标准档:实测 420dpi 机器上,由 127px/48dp 反推出的
+  // 2.646 与标准档 2.625 同簇,而 2.646 在自己生成的那个 px 上残差为 0,不并簇就会
+  // 让一个 3 位小数的伪档赢过真值。簇的分数取簇内最好值(最多命中、最小残差)。
+  out.sort((a, b) => a.d - b.d);
+  const clusters = [];
+  let group = [];
+  const flush = () => {
+    if (group.length === 0) { return; }
+    const rep = group.find((g) => g.std) ??
+      [...group].sort((a, b) => b.hits - a.hits || a.residual - b.residual || b.d - a.d)[0];
+    const bestHits = [...group].sort((a, b) => b.hits - a.hits)[0];
+    clusters.push({
+      d: rep.d,
+      hits: bestHits.hits,
+      residual: Math.min(...group.map((g) => g.residual)),
+      dpKinds: Math.max(...group.map((g) => g.dpKinds)),
+      std: group.some((g) => g.std),
+      evidence: rep.hits >= bestHits.hits ? rep.evidence : bestHits.evidence
+    });
+    group = [];
+  };
+  for (const c of out) {
+    if (group.length > 0 && (c.d - group[group.length - 1].d) / group[group.length - 1].d > 0.015) {
+      flush();
+    }
+    group.push(c);
+  }
+  flush();
+  // 命中数 → **标准档** → 残差 → 大密度优先。
+  // 标准档必须排在残差之前:由数据反推出的候选在生成它的那个 px 上残差恒为 0,
+  // 若先比残差,伪档与其 1/2 谐波会一起压过真值(实测 2.625 被 2.646 / 1.323 击败)。
+  // 大密度优先也不可反向:小密度总能用更大的 dp 混叠解释同一批 px(px=72 → 72dp@1.0)。
+  clusters.sort((a, b) =>
+    b.hits - a.hits ||
+    (b.std ? 1 : 0) - (a.std ? 1 : 0) ||
+    a.residual - b.residual ||
+    b.d - a.d);
+  return clusters;
+}
+
+/**
+ * 定出屏幕密度:**有真值就用真值**,没有才由 bounds 反解。
+ *
+ * 真值(`meta.json` 的 `device.density`,由 android_parse_fast.js 采集期用 `wm density` 记录;
+ * 或 `--density` 显式传入)优先,因为反解在数学上不唯一 —— 一旦解错,该页所有 vp 整体差
+ * 2~3 倍,而编译、引用检查、跨页一致性全都照样通过(每页错得一样),是最难归因的一类缺陷。
+ *
+ * 反解只看**正方形**节点:矩形的宽高多由约束求解得出,不是声明值。四条硬规则见
+ * scoreDensities 的注释(按不同边长计分 / px 空间 ±1px / 屏宽闸门 / 候选表不写死)。
+ *
+ * 输出 evidence + confident + rival,而非单一数字 —— Phase 5 要求每个尺寸可溯源,
+ * 且"5 路平局"与"12:2 压倒性胜出"必须在输出里长得不一样。
+ */
+function deriveDensity(
+  nodes,
+  known,
+  screen
+) {
+  // 按**不同边长**去重:工具栏上 10 个同尺寸图标不提供 10 份证据,只提供 1 份。
+  // 按节点个数计分会让所有混叠候选一起刷到 10 分,平局锁死后倒向最小密度。
+  // 容忍 1px 的非方误差:round() + 约束求解会让声明为正方形的视图偶尔出现 63x64。
+  const seen = new Set();
+  const sides = [];
+  for (const n of nodes) {
+    if (n.w <= 0 || Math.abs(n.w - n.h) > 1) { continue; }
+    const px = Math.max(n.w, n.h);
+    if (seen.has(px)) { continue; }
+    seen.add(px);
+    sides.push({ px, idx: n.idx });
+  }
+  // 屏幕尺寸优先取 meta.json 的 device(采集期 `wm size` 真值);没有才用节点包围盒 ——
+  // uiautomator 只 dump 获焦窗口,对话框页面的包围盒**不是整屏**,闸门会因此判错。
+  const boundsW = nodes.length > 0 ? Math.max(...nodes.map((n) => n.x2)) : 0;
+  const boundsH = nodes.length > 0 ? Math.max(...nodes.map((n) => n.y2)) : 0;
+  const scrW = screen ? screen.widthPx : boundsW;
+  const scrH = screen ? screen.heightPx : boundsH;
+  const shortPx = Math.min(scrW, scrH);
+  const longPx = Math.max(scrW, scrH);
+
+  // 没有正方形节点时反解无从下手 —— 但**真值仍然可用**,不能因为无法回代验证就把它丢掉。
+  // (这一顺序踩过一次:早退分支写在 known 之前,导致 --density 在这些页面上被静默忽略。)
+  if (sides.length === 0) {
+    if (known) {
+      return {
+        density: known.value, source: known.source, confident: true,
+        rival: null, crosscheck: null, evidence: [],
+        reason: `view tree 里没有正方形节点(共 ${nodes.length} 个),真值无法回代验证 —— ` +
+          '数值本身可信,但本页没有可引用的密度证据行'
+      };
+    }
+    return {
+      density: null, source: 'inferred', confident: false, rival: null, crosscheck: null,
+      evidence: [],
+      reason: `view tree 里没有正方形节点(共 ${nodes.length} 个节点),无法反解密度 —— ` +
+        '请用 `--density <值>` 显式给出(`adb shell wm density` 可查),' +
+        '或重跑采集以把 device.density 写进 meta.json。' +
+        '密度缺失时本包所有 vp 字段均为 null,下游尺寸门禁会整页静默跳过。'
+    };
+  }
+
+  let scored = scoreDensities(sides, shortPx, longPx, true);
+  let gateRelaxed = false;
+  if (scored.length === 0) {
+    // 对话框/分屏/画中画的 dump 里包围盒不是整屏,闸门可能把所有候选滤光 —— 放开重试并降置信度
+    scored = scoreDensities(sides, shortPx, longPx, false);
+    gateRelaxed = true;
+  }
+
+  const top = scored[0] ?? null;
+  const rival = top
+    ? (scored.find((s) => Math.abs(s.d - top.d) / top.d > 0.02) ?? null)
+    : null;
+  const rivalOut =
+    rival ? { density: rival.d, hits: rival.hits } : null;
+  // 兑现"两条独立命中才足以支撑一个密度结论":必须命中两个**不同 dp 档**,
+  // 且对最近的非同族候选有明确优势(命中更多,或残差更小)。
+  const inferredConfident = !!top && !gateRelaxed && top.dpKinds >= 2 &&
+    (!rival || rival.hits < top.hits || rival.residual > top.residual);
+
+  if (known) {
+    const match =
+      scored.find((s) => Math.abs(s.d - known.value) / known.value <= 0.02);
+    let crosscheck = null;
+    if (top && inferredConfident && Math.abs(top.d - known.value) / known.value > 0.02) {
+      crosscheck = `真值 ${known.value}(${known.source})与节点反解 ${top.d}` +
+        `(${top.hits}/${sides.length} 命中,${top.dpKinds} 个 dp 档)不一致 —— ` +
+        '请确认 meta.json 与 view.xml 同源,且采集后未执行过 wm density';
+    }
+    return {
+      density: known.value,
+      source: known.source,
+      confident: true,
+      rival: rivalOut,
+      crosscheck,
+      evidence: (match?.evidence ?? top?.evidence ?? []).slice(0, 8),
+      reason: match ? null : '真值未能被任何正方形节点回代验证(可能该页尺寸档不在 COMMON_DP 里),真值本身仍然可信'
+    };
+  }
+  let reason = null;
+  if (!top) {
+    reason = `${sides.length} 个不同边长都无法用常见 dp 档解释,无法反解密度 —— 请用 --density 显式给出`;
+  } else if (!inferredConfident) {
+    reason = top.dpKinds < 2
+      ? `只命中 1 个 dp 档(${top.evidence.length} 个边长),不足以定档 —— ` +
+        '同一批 px 在整个谐波族里都自洽,请用 --density 或重采集以写入 device.density'
+      : rival
+        ? `次优候选 ${rival.d} 与之势均力敌(命中 ${rival.hits} vs ${top.hits},残差 ${rival.residual} vs ${top.residual})`
+        : '未通过置信判据';
+  }
+  return {
+    density: top ? top.d : null,
+    source: 'inferred',
+    confident: inferredConfident,
+    rival: rivalOut,
+    crosscheck: gateRelaxed
+      ? '屏幕尺寸合理性闸门无候选通过(可能是对话框/分屏/画中画 dump),已放开闸门,结果仅供参考'
+      : null,
+    evidence: top ? top.evidence.slice(0, 8) : [],
+    reason
+  };
+}
+
+// ---------------------------------------------------------------- PNG 解码
+
+/**
+ * 最小 PNG 解码器:zlib inflate + 逐行反滤波。仅支持 8bit 非隔行的
+ * 灰度/RGB/调色板/灰度+A/RGBA(colorType 0/2/3/4/6)。
+ *
+ * 不支持的变体**显式抛错并给出 PIL 回退命令**,绝不静默降级 ——
+ * 一个悄悄返回错像素的量测器,比没有量测器更危险。
+ */
+function decodePng(file) {
+  const buf = fs.readFileSync(file);
+  const SIG = [137, 80, 78, 71, 13, 10, 26, 10];
+  for (let i = 0; i < 8; i++) {
+    if (buf[i] !== SIG[i]) {
+      throw new Error(`不是 PNG 文件: ${file}`);
+    }
+  }
+  let off = 8;
+  let w = 0;
+  let h = 0;
+  let depth = 0;
+  let ctype = 0;
+  let interlace = 0;
+  const idat = [];
+  let plte = null;
+  let trns = null;
+  while (off < buf.length) {
+    const len = buf.readUInt32BE(off);
+    const type = buf.toString('ascii', off + 4, off + 8);
+    const data = buf.subarray(off + 8, off + 8 + len);
+    if (type === 'IHDR') {
+      w = data.readUInt32BE(0);
+      h = data.readUInt32BE(4);
+      depth = data[8];
+      ctype = data[9];
+      interlace = data[12];
+    } else if (type === 'IDAT') {
+      idat.push(data);
+    } else if (type === 'PLTE') {
+      plte = Buffer.from(data);
+    } else if (type === 'tRNS') {
+      trns = Buffer.from(data);
+    } else if (type === 'IEND') {
+      break;
+    }
+    off += 12 + len;
+  }
+  if (depth !== 8 || interlace !== 0 || ![0, 2, 3, 4, 6].includes(ctype)) {
+    throw new Error(
+      `不支持的 PNG 变体 (bitDepth=${depth}, colorType=${ctype}, interlace=${interlace})。\n` +
+      '本解码器只支持 8bit 非隔行的 colorType 0/2/3/4/6。\n' +
+      '回退方案(需 Pillow):\n' +
+      `  python -c "from PIL import Image; im=Image.open(r'${file}').convert('RGBA'); ` +
+      `im.save(r'${file}.rgba8.png')"\n` +
+      '然后对转换后的文件重跑本脚本。'
+    );
+  }
+  const CH = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 };
+  const ch = CH[ctype];
+  const raw = zlib.inflateSync(Buffer.concat(idat));
+  const stride = w * ch;
+  const px = new Uint8Array(w * h * 4);
+  const prev = new Uint8Array(stride);
+  const cur = new Uint8Array(stride);
+  let rp = 0;
+  for (let y = 0; y < h; y++) {
+    const filter = raw[rp++];
+    for (let i = 0; i < stride; i++) {
+      cur[i] = raw[rp + i];
+    }
+    rp += stride;
+    // 反滤波(PNG spec 9.2)
+    for (let i = 0; i < stride; i++) {
+      const a = i >= ch ? cur[i - ch] : 0;
+      const b = prev[i];
+      const c = i >= ch ? prev[i - ch] : 0;
+      let v = cur[i];
+      if (filter === 1) {
+        v = v + a;
+      } else if (filter === 2) {
+        v = v + b;
+      } else if (filter === 3) {
+        v = v + ((a + b) >> 1);
+      } else if (filter === 4) {
+        const p = a + b - c;
+        const pa = Math.abs(p - a);
+        const pb = Math.abs(p - b);
+        const pc = Math.abs(p - c);
+        v = v + (pa <= pb && pa <= pc ? a : (pb <= pc ? b : c));
+      }
+      cur[i] = v & 0xff;
+    }
+    // 转 RGBA
+    for (let x = 0; x < w; x++) {
+      const o = (y * w + x) * 4;
+      const s = x * ch;
+      if (ctype === 3) {
+        const pi = cur[s];
+        if (plte) {
+          px[o] = plte[pi * 3];
+          px[o + 1] = plte[pi * 3 + 1];
+          px[o + 2] = plte[pi * 3 + 2];
+        }
+        px[o + 3] = trns && pi < trns.length ? trns[pi] : 255;
+      } else if (ctype === 0 || ctype === 4) {
+        px[o] = px[o + 1] = px[o + 2] = cur[s];
+        px[o + 3] = ctype === 4 ? cur[s + 1] : 255;
+      } else {
+        px[o] = cur[s];
+        px[o + 1] = cur[s + 1];
+        px[o + 2] = cur[s + 2];
+        px[o + 3] = ctype === 6 ? cur[s + 3] : 255;
+      }
+    }
+    prev.set(cur);
+  }
+  return { width: w, height: h, px };
+}
+
+// ---------------------------------------------------------------- 像素量测
+
+function px(im, x, y) {
+  const o = (y * im.width + x) * 4;
+  return [im.px[o], im.px[o + 1], im.px[o + 2], im.px[o + 3]];
+}
+
+/**
+ * 在给定矩形内求「墨迹」包围盒 —— 即与背景色差异超过 tol 的像素的外接矩形。
+ *
+ * 用途:参考截图里一个元素的**声明框**(view.xml 的 bounds / 语义框)与它**实际画出来的
+ * 图形**往往不同尺寸。区分二者是硬需求:本项目实测中,SeekBar 的语义框左内缩 58px(22.1dp),
+ * 而实际绘制的轨道(含圆角端帽)起于 75px —— 若把 58px 当成声明 padding,会得出 22dp 的
+ * 错误结论,而源码写的是 32dp。ink bbox 是唯一能把两者分开的量测。
+ *
+ * 背景色默认取该矩形四角的中位数,避免取到元素自身。
+ */
+function inkBox(im, x1, y1, x2, y2,
+                tol = 12, bg) {
+  const corners = [
+    px(im, x1, y1), px(im, x2 - 1, y1), px(im, x1, y2 - 1), px(im, x2 - 1, y2 - 1)
+  ];
+  const base = bg || [
+    median(corners.map((c) => c[0])),
+    median(corners.map((c) => c[1])),
+    median(corners.map((c) => c[2]))
+  ];
+  // 背景均匀性自检:四角在任一通道上的跨度若接近/超过容差,说明底不是纯色
+  // (渐变、图片、模糊底),此时「与背景有差异」这个判据本身失效。
+  // 实测:本项目唱片区底为粉色渐变,四角绿通道 248→237(跨度 11,容差 12),
+  // 通用 ink bbox 量出 861x818(几乎整块),而针对图形颜色筛选量出的是 655x724。
+  // 与其把容差调到刚好凑上某个已知答案,不如让工具**自报不可信** ——
+  // 前者是把工具拟合到一个样本,后者才在别的页面上仍然成立。
+  let spread = 0;
+  for (let c = 0; c < 3; c++) {
+    const vals = corners.map((q) => q[c]);
+    spread = Math.max(spread, Math.max(...vals) - Math.min(...vals));
+  }
+  const shaky = spread >= tol * 0.8;
+  let mnx = Number.MAX_SAFE_INTEGER;
+  let mny = Number.MAX_SAFE_INTEGER;
+  let mxx = -1;
+  let mxy = -1;
+  for (let y = y1; y < y2; y++) {
+    for (let x = x1; x < x2; x++) {
+      const p = px(im, x, y);
+      if (Math.abs(p[0] - base[0]) > tol ||
+          Math.abs(p[1] - base[1]) > tol ||
+          Math.abs(p[2] - base[2]) > tol) {
+        if (x < mnx) { mnx = x; }
+        if (x > mxx) { mxx = x; }
+        if (y < mny) { mny = y; }
+        if (y > mxy) { mxy = y; }
+      }
+    }
+  }
+  if (mxx < 0) {
+    return null;
+  }
+  const box = {
+    x1: mnx, y1: mny, x2: mxx, y2: mxy,
+    w: mxx - mnx + 1,
+    h: mxy - mny + 1,
+    cx: (mnx + mxx) / 2,
+    cy: (mny + mxy) / 2
+  };
+  // 底不均匀即判不可信。**不要**试图再用「ink 是否小于声明框」去细分可信与否 ——
+  // 本项目实测证伪过这条思路:SeekBar 区域的 ink 量出 928x42,宽度 x 75..1002 恰好与
+  // 按颜色筛选的结果逐点吻合,看起来「可信」;但高度 42 正是声明框全高,而真实绘制的
+  // 轨道只有 26px —— 宽度对是因为轨道本就近乎满宽,**纯属碰巧**。
+  // 即:同一个 ink bbox 可以一维正确、另一维被渐变污染,不存在能把两者分开的整体判据。
+  //
+  // 于是整页铺渐变时,大多数区域被标记是**事实而非噪声**。如实报出,并附实测跨度,
+  // 由使用者按需对具体元素做颜色筛选 —— 这比给一个看起来精确的错数字诚实得多。
+  box.bgSpread = spread;
+  if (shaky) {
+    box.unreliable = true;
+    box.reason = `区域背景不均匀(四角通道跨度 ${spread},容差 ${tol}),疑为渐变/图片/模糊底。` +
+      'ink bbox 会把底色差异也算成墨迹,**任一维都可能被污染**(实测出现过「宽对高错」),' +
+      '故不可据此断言实绘尺寸。需按图形自身颜色单独筛选后再量。';
+  }
+  return box;
+}
+
+function median(a) {
+  const s = a.slice().sort((p, q) => p - q);
+  return s[Math.floor(s.length / 2)];
+}
+
+// ---------------------------------------------------------------- main
+
+// interface RegionOut {
+  // node: number;
+  // role: string;
+  // boundsPx: string;
+  // wPx: number;
+  // hPx: number;
+  // wVp: number | null;
+  // hVp: number | null;
+  // xRatio: number;
+  // yRatio: number;
+  // wRatio: number;
+  // hRatio: number;
+  // clickable: boolean;
+  // text: string;
+  // desc: string;
+  // ink: InkBox | null;
+  // inkNote?: string;
+  // /** 该区域的前景色(最深像素)与底色(占比最大的像素),十六进制。 */
+  // inkColor?: string;
+  // bgColor?: string;
+// }
+
+/**
+ * 区域取色 —— 前景取**最深像素**,底色取**频次最高**的像素。
+ *
+ * 为什么不能沿用 inkBox 的四角中位数:四角必然落在**底**上,所以它能给底色、
+ * 永远给不出文字/描边的颜色。而"这段文字是什么颜色"是每个 Text 都要回答的问题
+ * (M3 的 onSurface / onSurfaceVariant / primary / tertiary 在截图里只差几十个灰阶,
+ * 靠肉眼看截图分不出来),于是不内置就等于每页都要另起一轮像素探测。
+ *
+ * 成本几乎为零:inkBox 本来就把这些像素走了一遍,这里只是在同一趟里多记两个值。
+ */
+function regionColors(im, x1, y1, x2, y2)
+     {
+  const hex = (r, g, b) =>
+    '#' + [r, g, b].map((v) => v.toString(16).padStart(2, '0').toUpperCase()).join('');
+  let dr = 255, dg = 255, db = 255, dl = 1e9;
+  const hist = new Map();
+  for (let y = y1; y < y2; y++) {
+    for (let x = x1; x < x2; x++) {
+      const o = (y * im.width + x) * 4;
+      const r = im.px[o], g = im.px[o + 1], b = im.px[o + 2];
+      const l = 0.299 * r + 0.587 * g + 0.114 * b;
+      if (l < dl) { dl = l; dr = r; dg = g; db = b; }
+      const k = (r << 16) | (g << 8) | b;
+      hist.set(k, (hist.get(k) || 0) + 1);
+    }
+  }
+  let bk = 0, bn = -1;
+  for (const [k, n] of hist) { if (n > bn) { bn = n; bk = k; } }
+  return {
+    ink: hex(dr, dg, db),
+    bg: hex((bk >> 16) & 255, (bk >> 8) & 255, bk & 255)
+  };
+}
+
+// ---------------------------------------------------------------- 探针模式
+
+/**
+ * `--probe` —— 对一个矩形做**逐像素追问**,回答默认输出的 ink bbox 答不了的问题。
+ *
+ * 为什么必须内置:本包已经有 PNG 解码器(decodePng),但只把它用在 ink bbox 上。
+ * 于是每当需要「这个图标的实际几何是什么」「这个色值是多少」「这条圆角胶囊多大」,
+ * 子 agent 就得自己在 /tmp 里重写一遍解码器 —— 实测**同一次单页转换里重写了 7 遍**
+ * 逐字节相同的 inflate + 反滤波样板,每遍还各占一轮工具往返。
+ * 而这些量测本身是纯算术、对同一台采集设备恒定,正是本包存在的理由。
+ *
+ * 四种输出各对应一类回答不了的问题:
+ *   colors  某几个点/整块区域的真实色值(取最深像素 + 频次直方图,
+ *           而不是四角取样 —— 文字/描边的"主色"永远不在四角)
+ *   runs    逐行的暗像素区间。线条图标(勾、条、箭头)的顶点坐标只能从这里读出;
+ *           ink bbox 只给外接矩形,拿它复原不出折线。
+ *   ascii   把区域渲染成字符画,用于**先看清形状**再决定量什么。
+ *   filter  按**指定颜色**求包围盒,而非"与背景不同"。渐变/图片底上
+ *           bgSpread 会把 ink 判为不可靠(见 InkBox.unreliable),此时只有
+ *           按颜色过滤能量出真实尺寸 —— 例如 M3 选中态胶囊。
+ *
+ * 用法:
+ *   node measure_pack.js --probe <png> --rect x1,y1,x2,y2 --mode colors|runs|ascii|filter
+ *                        [--color RRGGBB] [--tol 14] [--density 2.625]
+ */
+function runProbe(argv, arg) {
+  const file = arg('--probe');
+  const rectS = arg('--rect');
+  const mode = arg('--mode') || 'colors';
+  if (!file || !fs.existsSync(file)) {
+    console.error('--probe 需要一个存在的 png 路径');
+    process.exit(2);
+  }
+  const im = decodePng(file);
+  const r = (rectS || `0,0,${im.width},${im.height}`).split(',').map((v) => parseInt(v, 10));
+  const x1 = Math.max(0, r[0]);
+  const y1 = Math.max(0, r[1]);
+  const x2 = Math.min(im.width - 1, r[2]);
+  const y2 = Math.min(im.height - 1, r[3]);
+  const dens = parseFloat(arg('--density') || '0');
+  const tol = parseInt(arg('--tol') || '14', 10);
+  const hex = (c) =>
+    '#' + c.slice(0, 3).map((v) => v.toString(16).padStart(2, '0').toUpperCase()).join('');
+  const lum = (c) => 0.299 * c[0] + 0.587 * c[1] + 0.114 * c[2];
+  const vp = (n) => (dens > 0 ? ` (${(n / dens).toFixed(2)}vp)` : '');
+
+  if (mode === 'colors') {
+    let dark = [255, 255, 255];
+    const hist = new Map();
+    for (let y = y1; y <= y2; y++) {
+      for (let x = x1; x <= x2; x++) {
+        const c = px(im, x, y);
+        if (lum(c) < lum(dark)) { dark = c; }
+        const k = hex(c);
+        hist.set(k, (hist.get(k) || 0) + 1);
+      }
+    }
+    const top = [...hist.entries()].sort((a, b) => b[1] - a[1]).slice(0, 4)
+      .map((e) => `${e[0]}×${e[1]}`);
+    console.log(`rect [${x1},${y1}][${x2},${y2}]`);
+    console.log(`  darkest : ${hex(dark)}`);
+    console.log(`  top     : ${top.join('  ')}`);
+    console.log('  注:文字/描边取 darkest,底色取 top 里占比最大的那个');
+  } else if (mode === 'runs') {
+    console.log(`rect [${x1},${y1}][${x2},${y2}]  暗像素逐行区间 (lum<${170})`);
+    for (let y = y1; y <= y2; y++) {
+      const runs = [];
+      let s = -1;
+      for (let x = x1; x <= x2 + 1; x++) {
+        const d = x <= x2 && lum(px(im, x, y)) < 170;
+        if (d && s < 0) { s = x; }
+        if (!d && s >= 0) { runs.push(`${s}-${x - 1}`); s = -1; }
+      }
+      if (runs.length > 0) { console.log(`  y=${y}  ${runs.join(' ')}`); }
+    }
+    console.log('  注:折线/条形图标的顶点坐标从区间端点读出,ink bbox 只给外接矩形');
+  } else if (mode === 'ascii') {
+    const ramp = ' .:-=+*#%@';
+    for (let y = y1; y <= y2; y++) {
+      let line = '';
+      for (let x = x1; x <= x2; x++) {
+        const l = lum(px(im, x, y)) / 255;
+        line += ramp[Math.min(9, Math.max(0, Math.round((1 - l) * 9)))];
+      }
+      console.log(String(y).padStart(5) + ' ' + line);
+    }
+  } else if (mode === 'filter') {
+    const want = arg('--color');
+    if (!want) {
+      console.error('--mode filter 需要 --color RRGGBB');
+      process.exit(2);
+    }
+    const t = (want).replace('#', '');
+    const tgt = [0, 2, 4].map((i) => parseInt(t.slice(i, i + 2), 16));
+    let mnx = 1e9, mxx = -1, mny = 1e9, mxy = -1, n = 0;
+    for (let y = y1; y <= y2; y++) {
+      for (let x = x1; x <= x2; x++) {
+        const c = px(im, x, y);
+        if (Math.abs(c[0] - tgt[0]) <= tol && Math.abs(c[1] - tgt[1]) <= tol
+            && Math.abs(c[2] - tgt[2]) <= tol) {
+          n++;
+          if (x < mnx) { mnx = x; } if (x > mxx) { mxx = x; }
+          if (y < mny) { mny = y; } if (y > mxy) { mxy = y; }
+        }
+      }
+    }
+    if (n === 0) {
+      console.log(`未命中颜色 #${t.toUpperCase()} (tol=${tol}) —— 换 --mode colors 先看真实色值`);
+      return;
+    }
+    const w = mxx - mnx + 1;
+    const h = mxy - mny + 1;
+    console.log(`颜色 #${t.toUpperCase()} (tol=${tol}) 命中 ${n}px`);
+    console.log(`  bbox  [${mnx},${mny}][${mxx},${mxy}]`);
+    console.log(`  尺寸  w=${w}${vp(w)}  h=${h}${vp(h)}`);
+    console.log('  注:本模式按颜色过滤,不受 bgSpread/非均匀底影响');
+  } else {
+    console.error(`未知 --mode: ${mode}(可选 colors|runs|ascii|filter)`);
+    process.exit(2);
+  }
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const arg = (k) => {
+    const i = argv.indexOf(k);
+    return i >= 0 && i + 1 < argv.length ? argv[i + 1] : null;
+  };
+  if (argv.includes('--probe')) { runProbe(argv, arg); return; }
+  const dir = arg('--ui-info');
+  const quiet = argv.includes('--quiet');
+  if (!dir) {
+    console.error('用法: node measure_pack.js --ui-info <page_NNNN_X 目录> [--out f.json] [--quiet] [--density N]');
+    process.exit(2);
+  }
+  // 按 meta.json 声明的确切路径取截图/view tree(不靠 Glob 猜)
+  let shot = path.join(dir, 'screenshot.png');
+  let vx = path.join(dir, 'view.xml');
+  const metaP = path.join(dir, 'meta.json');
+  let pageId = path.basename(dir);
+  let metaDensity = null;
+  let metaScreen = null;
+  const cliDensity = parseFloat(arg('--density') || '0');
+  if (fs.existsSync(metaP)) {
+    try {
+      const meta = JSON.parse(fs.readFileSync(metaP, 'utf8'))
+        // page_id?: string; screenshot?: string; view_xml?: string;
+        // device?: { density?: number | null; width_px?: number | null; height_px?: number | null };
+;
+      if (meta.page_id) { pageId = meta.page_id; }
+      const root = path.dirname(dir);
+      if (meta.screenshot) { shot = path.resolve(root, meta.screenshot); }
+      if (meta.view_xml) { vx = path.resolve(root, meta.view_xml); }
+      // 采集期用 `wm density` 记下的真值。有它就不必反解 —— 反解不唯一,解错一次
+      // 整页 vp 差 2~3 倍,且编译与引用检查全部通过,极难归因。
+      if (typeof meta.device?.density === 'number' && meta.device.density > 0) {
+        metaDensity = meta.device.density;
+      }
+      // 整屏尺寸真值:uiautomator 只 dump 获焦窗口,对话框页面的节点包围盒不是整屏,
+      // 拿它去过屏幕尺寸闸门会误判。有 `wm size` 真值就用真值。
+      if (typeof meta.device?.width_px === 'number' && typeof meta.device?.height_px === 'number'
+        && meta.device.width_px > 0 && meta.device.height_px > 0) {
+        metaScreen = { widthPx: meta.device.width_px, heightPx: meta.device.height_px };
+      }
+    } catch (e) {
+      console.error('meta.json 解析失败,回退到默认文件名: ' + String(e));
+    }
+  }
+  if (!fs.existsSync(vx)) {
+    console.error('view tree 不存在: ' + vx);
+    process.exit(2);
+  }
+
+  const nodes = parseNodes(fs.readFileSync(vx, 'utf8'));
+  const root = nodes[0];
+  // 优先级:--density > meta.json 的 device.density > 节点反解
+  const known =
+    cliDensity > 0 ? { value: cliDensity, source: 'cli' }
+      : metaDensity !== null ? { value: metaDensity, source: 'device' }
+        : null;
+  const den = deriveDensity(nodes, known, metaScreen);
+  const d = den.density;
+  const toVp = (v) => (d ? Math.round((v / d) * 100) / 100 : null);
+
+  let im = null;
+  let imErr = '';
+  if (fs.existsSync(shot)) {
+    try {
+      im = decodePng(shot);
+    } catch (e) {
+      imErr = String(e);
+    }
+  } else {
+    imErr = '截图不存在: ' + shot;
+  }
+  // 解码失败必须**显式刺眼**,不能只躺在 JSON 字段里:那样的症状是密度算得出、
+  // 而 ink/edge_colors 全空,看起来像「这页没有可量的东西」,而不是「量测器坏了」。
+  if (imErr) {
+    console.error('!! 像素量测不可用 —— ' + imErr);
+    console.error('!! 本包仅含 view tree 量测;ink bbox 与取色缺失,勿据此断言实绘尺寸。');
+  }
+
+  // 主要区域 = 可交互 / 有文字或描述 / 可滚动 / 已知的控件类。
+  //
+  // 最后一项不可省:实测 `android.widget.SeekBar` 的 clickable=false、text 与
+  // content-desc 均为空、scrollable=false —— 只按前三项过滤会把进度条整条漏掉,
+  // 而它恰是本页需要精确量测的区域之一(声明框 42px 高、实绘轨道 26px)。
+  // 凡「靠交互属性判断重要性」的过滤都有这个盲区,故补一张控件类白名单。
+  const WIDGET = /\.(SeekBar|ProgressBar|Switch|CheckBox|RadioButton|EditText|ImageView|ImageButton|RatingBar|Spinner|ToggleButton|Button|TextView)$/;
+  const picked = nodes.filter((n) =>
+    n.clickable || n.scrollable || n.checkable ||
+    n.text.length > 0 || n.desc.length > 0 || WIDGET.test(n.cls));
+
+  const regions = picked.map((n) => {
+    const r = {
+      node: n.idx,
+      role: n.cls.replace(/^android\.(widget|view)\./, ''),
+      boundsPx: `[${n.x1},${n.y1}][${n.x2},${n.y2}]`,
+      wPx: n.w,
+      hPx: n.h,
+      wVp: toVp(n.w),
+      hVp: toVp(n.h),
+      xRatio: Math.round(((n.x1 - root.x1) / root.w) * 1e4) / 1e4,
+      yRatio: Math.round(((n.y1 - root.y1) / root.h) * 1e4) / 1e4,
+      wRatio: Math.round((n.w / root.w) * 1e4) / 1e4,
+      hRatio: Math.round((n.h / root.h) * 1e4) / 1e4,
+      clickable: n.clickable,
+      text: n.text,
+      desc: n.desc,
+      ink: null
+    };
+    if (im && n.w > 1 && n.h > 1 && n.w <= im.width && n.h <= im.height) {
+      const cx2 = Math.min(n.x2, im.width);
+      const cy2 = Math.min(n.y2, im.height);
+      r.ink = inkBox(im, n.x1, n.y1, cx2, cy2);
+      if (r.ink && (r.ink.w !== n.w || r.ink.h !== n.h)) {
+        r.inkNote = '实绘图形小于声明框 —— 声明框可能是语义/触控框,勿直接当绘制尺寸';
+      }
+      const c = regionColors(im, n.x1, n.y1, cx2, cy2);
+      r.inkColor = c.ink;
+      r.bgColor = c.bg;
+    }
+    return r;
+  });
+
+  // 四边取色:用于判断底色/scrim 合成,以及沉浸式下的边缘着色(仅提供数值,不做判断)
+  const edges = {};
+  if (im) {
+    const mid = Math.floor(im.height / 2);
+    const midx = Math.floor(im.width / 2);
+    edges.top = px(im, midx, 0);
+    edges.bottom = px(im, midx, im.height - 1);
+    edges.left = px(im, 0, mid);
+    edges.right = px(im, im.width - 1, mid);
+    edges.center = px(im, midx, mid);
+  }
+
+  const out = {
+    page_id: pageId,
+    generated_by: 'measure_pack.js',
+    inputs: {
+      view_xml: vx,
+      screenshot: fs.existsSync(shot) ? shot : null,
+      screenshot_error: imErr || null
+    },
+    image: im ? { width: im.width, height: im.height } : null,
+    density: {
+      value: d,
+      source: den.source,
+      source_note: den.source === 'device'
+        ? '采集期 `wm density` 真值(meta.json 的 device 字段)'
+        : den.source === 'cli'
+          ? '调用方通过 --density 显式给出'
+          : '由正方形节点边长反解常见 dp 档得出,下列为独立证据',
+      // confident=false 时**不要**拿本页 vp 当硬性实测值:反解有歧义,
+      // 请用 `adb shell wm density` 核实,或重跑带 device 字段的采集。
+      confident: den.confident,
+      rival: den.rival,
+      crosscheck: den.crosscheck,
+      reason: den.reason,
+      evidence: den.evidence.slice(0, 8)
+    },
+    app_content_bounds: {
+      boundsPx: `[${root.x1},${root.y1}][${root.x2},${root.y2}]`,
+      wPx: root.w,
+      hPx: root.h,
+      wVp: toVp(root.w),
+      hVp: toVp(root.h)
+    },
+    edge_colors: edges,
+    node_count: nodes.length,
+    regions
+  };
+
+  const outFile = arg('--out') || path.join(dir, 'measure_pack.json');
+  fs.writeFileSync(outFile, JSON.stringify(out, null, 2), 'utf8');
+
+  if (!quiet) {
+    console.log(`measure_pack —— ${pageId}`);
+    console.log(`  view tree : ${vx}`);
+    console.log(`  screenshot: ${fs.existsSync(shot) ? shot : '(缺失) ' + imErr}`);
+    if (im) { console.log(`  image     : ${im.width}x${im.height}`); }
+    const dsrc = den.source === 'device' ? '设备真值' : den.source === 'cli' ? '--density' : '节点反解';
+    console.log(`  density   : ${d === null ? '(无法反解)' : d}  [${dsrc}]`);
+    for (const e of den.evidence.slice(0, 4)) {
+      console.log(`      证据: node ${e.node} 边长 ${e.sidePx}px / ${e.dp}dp = ${e.density}`);
+    }
+    // 低置信必须**吵出来**:安静地印一个数字,下游会把它当实测值写进代码。
+    if (d !== null && !den.confident) {
+      console.log('  !! density 低置信 —— 本页 vp 换算不可作为硬性实测依据' +
+        (den.rival ? `;次优候选 ${den.rival.density}(${den.rival.hits} 命中)` : '') +
+        '。请用 `adb shell wm density` 核实,或重跑采集以写入 meta.json 的 device 字段');
+    }
+    if (den.reason) {
+      console.log('     原因: ' + den.reason);
+    }
+    if (den.crosscheck) {
+      console.log('  !! density 交叉校验: ' + den.crosscheck);
+    }
+    console.log(`  app bounds: ${out.app_content_bounds.boundsPx}` +
+      ` = ${out.app_content_bounds.wVp}x${out.app_content_bounds.hVp} vp`);
+    if (im) {
+      console.log('  边缘取色  : ' + Object.keys(edges)
+        .map((k) => `${k}=(${edges[k].slice(0, 3).join(',')})`).join('  '));
+    }
+    console.log(`  区域数    : ${regions.length} / 全节点 ${nodes.length}`);
+    // 带文字区域的取色必须进**打印摘要**:父流程贴进 prompt 的是这段摘要,
+    // 只落在 JSON 里等于没省 —— 子 agent 仍会另起一轮去探色。
+    // 只列有 text/desc 的区域,避免把 37 个区域全刷出来。
+    const painted = regions.filter(
+      (r) => r.inkColor !== undefined && (r.text.length > 0 || r.desc.length > 0));
+    if (painted.length > 0) {
+      console.log('  文本取色  : (前景=最深像素, 底=最高频像素; M3 各 on* 角色仅差几十灰阶,勿肉眼判)');
+      for (const r of painted.slice(0, 14)) {
+        const label = (r.text || r.desc).replace(/\s+/g, ' ').slice(0, 30);
+        console.log(`      node ${String(r.node).padStart(3)}  ${r.inkColor} on ${r.bgColor}  ${r.role}  "${label}"`);
+      }
+      if (painted.length > 14) {
+        console.log(`      ... 另 ${painted.length - 14} 个见 measure_pack.json 的 inkColor/bgColor`);
+      }
+    }
+    console.log(`  已写出    : ${outFile}`);
+    console.log('');
+    console.log('注意:本包只给**量测值**。沉浸式与否、锚点属固定偏移还是由父尺寸推导、');
+    console.log('图标 L1/L2/L3 分级,都必须回读 Android 源码判定(Phase 4.2 / 4.3),不在本包范围。');
+  }
+}
+
+main();
+