deveco_hmigbot 0.21.5

package/skills/migrate-core/scripts/smoke/walk.mjs

@@ -0,0 +1,480 @@
+#!/usr/bin/env node
+/**
+ * walk.mjs — 4b 运行时走查驱动（确定性·单飞·可证）。取代每轮现场自写的 python/node uitest 脚本：
+ * 实证 20 个基准应用 + 本地试点全在自写同一套东西（qianfeng 一轮 4b 73 分钟，其中 40 分钟在改自写驱动）。
+ * 只依赖 uitest 控件树公共字段（type/text/id/key/bounds/clickable）与 uiInput，无任何应用知识。
+ *
+ * 用法（单条命令，供逐步交互）：
+ *   walk.mjs devices                                   列出 hdc 目标（不取锁、不要求指定设备）
+ *   walk.mjs start <bundle> [--route <名>]             冷启（--route 走 smokeRoute 直达钩子）
+ *   walk.mjs stop <bundle>
+ *   walk.mjs alive <bundle>                            进程在且前台 → 0；否则 4
+ *   walk.mjs dump [<匹配>]                             打印控件树（缩进 type#id "text" bounds [click]）
+ *   walk.mjs tap <匹配> [--nth k] [--within <容器匹配>]  点击命中节点中心：被弹层/对话框盖住的候选自动靠后；--within 只在该容器子树内找（弹层内按钮）；
+ *                                                       多命中且无法消歧 → 并列带序号的候选，--nth k 即序号；步骤数据里 tap 会记 changed（点后控件树是否变化）与 occludedBy
+ *   walk.mjs type <匹配> <文本>                        点中输入框后输入
+ *   walk.mjs back | key <Back|Home|…>
+ *   walk.mjs swipe <up|down|left|right> [--within <匹配>] [--nth k]   定向滑动：在命中容器（缺省整屏）内从 70% 滑到 30%（up=内容上滚）
+ *   walk.mjs scroll <匹配> [--dir up] [--within <匹配>] [--max 8]   反复滑到目标出现（列表深处的项/触底加载/横滑区）；超 max 次未见 → 4
+ *   walk.mjs expect <匹配>...                          全部命中 → 0；缺 → 4 并列出
+ *   walk.mjs probe <匹配>...                           只报出现率（见到/未见清单），永远 0——给不确定该不该在当前状态出现的文案用
+ *   walk.mjs wait <匹配> [--timeout 8000]              轮询等到出现（超时 4）
+ *   walk.mjs shot <名字|路径.png>                       截图落盘：含路径分隔符或绝对路径按路径存，否则存到 --shots 目录（缺省 ./spec/4b/shots）
+ *   walk.mjs faults <bundle>                           列 faultlog 里该包的崩溃文件
+ *   walk.mjs start <bundle> [--route R] [--fresh]      --fresh 先清应用数据（bm clean -d）再冷启：首启/fixture/持久化断言要在干净态验（评测用例每条都清数据）
+ * 用法（步骤数据，供整条路径一次执行并落证据）：
+ *   walk.mjs plan --ledger <ledger.json> --project <工程根> --out <目录>   从台账机械生成逐页计划（每个带 route 的切片一份：
+ *                                                                        直达→存活→probe 该片 ui 断言引用的字面量→截图；无需设备）
+ *     逐页计划是**出现率证据**不是断言：断言天然含空态/校验提示/保存后提示/用户键入等状态相关文案，落地页不可能一次全显
+ *     （实证 6 份计划 5 份假失败），所以用 probe 只记见到/未见；真正的断言写在核心路径计划里。
+ *   walk.mjs run <steps.json> --out <report.json> [--shots <目录>] [--continue]
+ *   steps.json = { "bundle": "...", "name": "<计划名，失败截图用>", "scenarios": ["S12","S13"],   ← 有 PRD 时写本流覆盖的编号场景，ledger render --walks 据此汇总
+ *                  "steps": [ {"op":"start","route":"Timer"}, {"op":"expect","match":["=设置","画中画"]},
+ *                  {"op":"probe","match":["已保存","尚未选择"]}, {"op":"tap","match":"设置"}, {"op":"type","match":"gearNameInput","text":"水壶"},
+ *                  {"op":"wait","match":"已保存"}, {"op":"back"}, {"op":"key","name":"Home"}, {"op":"shot","name":"timer"}, {"op":"alive"}, {"op":"sleep","ms":800},
+ *                  {"op":"swipe","dir":"up","within":"type:List"}, {"op":"scrollUntil","match":"加载更多","dir":"up","max":8},
+ *                  {"op":"tap","match":"=提交","expectNoChange":true}, {"op":"tap","match":"=加入购物车","within":"type:^SheetPage$"},
+ *                  {"op":"start","fresh":true} ] }   ← 本就不该有反馈的点击（禁用态按钮）标 expectNoChange，不计入 tapsNoChange；弹层内目标用 within；fresh 清数据冷启
+ *   报告：每个失败步带 kind（target_missing/target_ambiguous/target_occluded 提示见 occludedBy/expect_missing/process_died/io_error）与页面字典；
+ *         崩溃带 crashDetail（Reason/Error message/首个应用帧）；failStreak=同一 --out 连续失败次数；seen=全程见过的 text/id 并集
+ *   默认首个失败步即停（后续记 skipped，失败现场补一张 fail-<计划名>-step-<i>.png）；--continue 继续跑完。run 结束自动查 faultlog：新增崩溃 → exit 10。
+ * 直达边界：`start --route` 经 smokeRoute 钩子直接推入目标页，**不经过首页**；首页承载的状态恢复（读偏好/数据库）不会执行，看到的是种子/默认态。
+ *   持久化类断言必须 `start`（不带 route）正常冷启 + 应用内导航；重启核持久化前先把状态改成非默认值，否则默认值证明不了任何事。
+ * 匹配：默认正则（不分大小写；非法正则自动退化为原文子串）撞 text/id/key；以 = 开头为全等（text 或 id）；以 type: 开头撞组件类型。
+ * 设备：--device <key> > 环境变量 HMIG_HDC_TARGET > 唯一目标；多目标未指定 → exit 3 列出。命令经 execFile 直达 hdc，不过本机 shell。
+ * 单飞：同设备同一时刻只允许一个 walk（锁目录 <tmp>/hmig-walk-<key>，原子改名建锁，持锁进程死才视为陈旧）——并发 uitest/hdc 实测 8 并发 7 空输出。
+ * 退出码：0 通过 / 3 环境（无设备·多设备未指定·锁等待超时·参数错）/ 4 断言未命中·未存活·等待超时 / 5 匹配歧义或无命中 / 10 崩溃
+ */
+import { execFileSync } from 'node:child_process';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, rmSync, renameSync, mkdtempSync, realpathSync, unlinkSync } from 'node:fs';
+import { join, resolve, dirname, relative, isAbsolute, sep } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { probeOf, escapeRe } from '../lib/literals.mjs';
+
+// ---------- 纯函数（可测） ----------
+export function flatten(tree) {
+  const out = [];
+  (function walk(n, depth) {
+    if (!n || typeof n !== 'object') return;
+    const a = n.attributes || {};
+    out.push({ depth, type: String(a.type || ''), text: String(a.text || ''), id: String(a.id || ''), key: String(a.key || ''), bounds: String(a.bounds || ''), clickable: a.clickable === 'true' || a.clickable === true, enabled: a.enabled !== 'false' });
+    for (const c of n.children || []) walk(c, depth + 1);
+  })(tree, 0);
+  return out;
+}
+export function center(bounds) {
+  const m = String(bounds).match(/\[(-?\d+),(-?\d+)\]\[(-?\d+),(-?\d+)\]/);
+  return m ? [Math.round((+m[1] + +m[3]) / 2), Math.round((+m[2] + +m[4]) / 2)] : null;
+}
+// 非法正则（"C++"、"(1)"、"[未完成"）退化为原文子串，不让一条断言文本炸掉整轮走查
+const safeRe = (p) => { try { return new RegExp(p, 'i'); } catch { return new RegExp(escapeRe(p), 'i'); } };
+export function matchNodes(nodes, pattern) {
+  const p = String(pattern);
+  if (p.startsWith('=')) { const t = p.slice(1); return nodes.filter(n => n.text === t || n.id === t); }
+  if (p.startsWith('type:')) { const re = safeRe(p.slice(5)); return nodes.filter(n => re.test(n.type)); }
+  const re = safeRe(p);
+  return nodes.filter(n => (n.text && re.test(n.text)) || (n.id && re.test(n.id)) || (n.key && re.test(n.key)));
+}
+// 遮挡判定（几何，按 ArkUI 命中测试同序）：bindSheet/CustomDialog/Menu/Popup 的包装层挂在页面之后、盖住大半屏；
+// 节点 N 之后出现、不是 N 后代、bounds 含 N 中心且面积 ≥ 屏幕一半的节点 M → N 被 M 盖住（点击落在 M 上）。
+// 小面积的后续重叠（底栏/FAB 压住列表末项）不算"模态遮挡"——真机复核：弹层页 2 个"加入购物车"只判底栏那个被盖，普通页 0 误判。
+const boxOf = (b) => { const m = String(b).match(/\[(-?\d+),(-?\d+)\]\[(-?\d+),(-?\d+)\]/); return m ? [+m[1], +m[2], +m[3], +m[4]] : null; };
+export function occludedBy(nodes, idx) {
+  const n = nodes[idx]; const c = center(n && n.bounds); if (!c) return null;
+  const rootBox = boxOf((nodes.find(x => boxOf(x.bounds)) || {}).bounds); if (!rootBox) return null;
+  const rootArea = Math.max(1, (rootBox[2] - rootBox[0]) * (rootBox[3] - rootBox[1]));
+  let end = idx + 1; while (end < nodes.length && nodes[end].depth > n.depth) end++;   // 跳过 N 的后代
+  for (let k = end; k < nodes.length; k++) {
+    const b = boxOf(nodes[k].bounds); if (!b) continue;
+    const area = (b[2] - b[0]) * (b[3] - b[1]);
+    if (area < rootArea / 2) continue;
+    if (c[0] > b[0] && c[0] < b[2] && c[1] > b[1] && c[1] < b[3]) return nodes[k];
+  }
+  return null;
+}
+// 点击目标选择：优先可点击且有坐标；多个时先剔被模态层盖住的，再全等文本唯一者优先；仍歧义 → null + 带序号候选（--nth 即该序号）
+// within：把候选限定在某容器子树内（如 --within type:SheetPage 只在弹层里找）
+export function pickTarget(nodes, pattern, nth, within) {
+  let scope = nodes;
+  if (within) {
+    const cont = matchNodes(nodes, within).find(x => center(x.bounds));
+    if (!cont) return { node: null, candidates: [], reason: `within 容器无命中：${within}` };
+    const ci = nodes.indexOf(cont); let end = ci + 1; while (end < nodes.length && nodes[end].depth > cont.depth) end++;
+    scope = nodes.slice(ci + 1, end);
+  }
+  const hit = matchNodes(scope, pattern);
+  if (!hit.length) return { node: null, candidates: [], reason: within ? `容器 ${within} 内无命中` : '无命中' };
+  const clickable = hit.filter(n => n.clickable && center(n.bounds));
+  let pool = clickable.length ? clickable : hit.filter(n => center(n.bounds));
+  if (!pool.length) return { node: null, candidates: hit, reason: '命中节点无坐标' };
+  const cover = (n) => occludedBy(nodes, nodes.indexOf(n));
+  if (nth !== undefined && nth !== null && nth !== '') { const n = pool[Number(nth)]; return n ? { node: n, candidates: pool, occludedBy: cover(n) } : { node: null, candidates: pool, reason: `--nth ${nth} 越界（候选 0..${pool.length - 1}）` }; }
+  const visible = pool.filter(n => !cover(n));
+  if (visible.length && visible.length < pool.length) pool = visible;   // 有未被盖住的就只在它们里选
+  if (pool.length === 1) return { node: pool[0], candidates: pool, occludedBy: cover(pool[0]) };
+  const plain = String(pattern).replace(/^=/, '');
+  const exact = pool.filter(n => n.text === plain || n.id === plain);
+  if (exact.length === 1) return { node: exact[0], candidates: pool, occludedBy: cover(exact[0]) };
+  return { node: null, candidates: pool, reason: `歧义 ${pool.length} 个，用 --nth <序号>、--within <容器> 或更具体的匹配` };
+}
+export const describe = (n, i) => `${i != null ? `[${i}] ` : ''}${'  '.repeat(n.depth)}${n.type}${n.id ? '#' + n.id : ''} "${n.text}" ${n.bounds}${n.clickable ? ' [click]' : ''}`;
+// 页面字典：当前页全部可见文本与 id（去重、保序、各至多 120 条）——写核心路径计划时照它取 text/id，一次写准
+// 几何量测（只量不判）：节点中心相对根节点的归一化坐标 (x,y)，0=左/上边、1=右/下边——位置类断言由模型拿它对照源/PRD 裁决，脚本不划区
+export function relCenter(bounds, root) {
+  const c = center(bounds); const m = root ? String(root).match(/\[(-?\d+),(-?\d+)\]\[(-?\d+),(-?\d+)\]/) : null;
+  if (!c || !m) return null;
+  const r = m.slice(1).map(Number);
+  return [Number(((c[0] - r[0]) / Math.max(1, r[2] - r[0])).toFixed(2)), Number(((c[1] - r[1]) / Math.max(1, r[3] - r[1])).toFixed(2))];
+}
+export const pageDict = (nodes) => {
+  const root = (nodes.find(n => center(n.bounds)) || {}).bounds;
+  const geometry = {};
+  for (const n of nodes) { if (!(n.clickable || n.id)) continue; const k = n.id ? '#' + n.id : n.text.trim(); if (!k || geometry[k]) continue; const g = relCenter(n.bounds, root); if (g) geometry[k] = { center: g, bounds: n.bounds }; if (Object.keys(geometry).length >= 60) break; }
+  return {
+    texts: [...new Set(nodes.map(n => n.text.trim()).filter(Boolean))].slice(0, 120),
+    ids: [...new Set(nodes.map(n => n.id).filter(Boolean))].slice(0, 120),
+    clickable: [...new Set(nodes.filter(n => n.clickable).map(n => n.text.trim() || (n.id ? '#' + n.id : '')).filter(Boolean))].slice(0, 60),
+    geometry,
+  };
+};
+const listCandidates = (cs) => cs.slice(0, 8).map((c, i) => describe(c, i).trim()).join(' | ');
+// 控件树签名：节点数 + 逐节点 type/text/id/bounds 串——同页同态则相同；用于判"这一下点击有没有产生变化"
+export const pageSig = (nodes) => `${nodes.length}|` + nodes.map(n => `${n.type}:${n.text}:${n.id}:${n.bounds}`).join('\n');
+// 滑动几何：容器 = --within 命中的节点（多命中按 --nth，否则取首个有坐标的），缺省整屏（根节点）；线段沿滑动轴 70%→30%、另一轴居中
+export function swipeBox(nodes, within, nth) {
+  if (!within) { const root = nodes.find(n => center(n.bounds)); return root ? root.bounds : null; }
+  const hit = matchNodes(nodes, within).filter(n => center(n.bounds));
+  if (!hit.length) return null;
+  const k = nth !== undefined && nth !== null && nth !== '' ? Number(nth) : 0;
+  return hit[k] ? hit[k].bounds : null;
+}
+export function swipeLine(bounds, dir = 'up') {
+  const m = String(bounds).match(/\[(-?\d+),(-?\d+)\]\[(-?\d+),(-?\d+)\]/); if (!m) return null;
+  const [x0, y0, x1, y1] = [+m[1], +m[2], +m[3], +m[4]]; const cx = Math.round((x0 + x1) / 2), cy = Math.round((y0 + y1) / 2);
+  const at = (a, b, f) => Math.round(a + (b - a) * f);
+  switch (dir) {
+    case 'up': return [cx, at(y0, y1, 0.7), cx, at(y0, y1, 0.3)];
+    case 'down': return [cx, at(y0, y1, 0.3), cx, at(y0, y1, 0.7)];
+    case 'left': return [at(x0, x1, 0.7), cy, at(x0, x1, 0.3), cy];
+    case 'right': return [at(x0, x1, 0.3), cy, at(x0, x1, 0.7), cy];
+    default: return null;
+  }
+}
+
+// 从台账机械生成逐页走查计划：每个带 route 的切片一份 —— 直达该页 → 存活 → probe 该片 ui 断言引用的字面量（parse-cards 抽的）→ 截图。
+// probe 只记出现率不判失败（断言含状态相关文案，落地页不可能一次全显）；不含跨页交互（那是核心路径计划，由 agent 按 PRD 场景写）。
+// 字面量按"前缀：值"只探前缀，正则转义后子串匹配。
+export function buildPlans(ledger, bundle) {
+  const feats = new Map((ledger.features || []).map(f => [f.id, f]));
+  const plans = []; const used = new Set();
+  for (const s of ledger.slices || []) {
+    if (!s.route) continue;
+    const lits = new Set();
+    for (const id of s.featureIds || []) { const f = feats.get(id); if (!f || f.kind !== 'ui' || f.status === 'waived') continue; for (const l of f.literals || []) lits.add(escapeRe(probeOf(l))); }
+    const steps = [{ op: 'start', route: s.route }, { op: 'alive' }];
+    if (lits.size) steps.push({ op: 'probe', match: [...lits] });
+    steps.push({ op: 'shot', name: s.route });
+    let name = String(s.route).replace(/[^\w.-]/g, '_'); if (used.has(name)) name = `${name}__${String(s.id).replace(/[^\w.-]/g, '_')}`; used.add(name);
+    plans.push({ name, plan: { bundle, name, kind: 'skeleton', slice: s.id, route: s.route, generated: 'walk.mjs plan（台账派生，勿手改；probe 只记出现率；跨页交互另写核心路径计划）', steps } });
+  }
+  return plans;
+}
+
+// faultlog 头部解析（jscrash：Error message + 'at xxx entry (entry/…/X.ets:行:列)'；cppcrash：Reason + 首帧）——只取应用可归因的第一帧
+export function parseFault(file, head) {
+  const lines = String(head || '').split(/\r?\n/);
+  const pick = (re) => { const l = lines.find(x => re.test(x)); return l ? l.replace(re, '').trim() : ''; };
+  const reason = pick(/^Reason:/), message = pick(/^Error message:/);
+  const frameLine = lines.find(x => /\bentry\/[^\s)]+\.(ets|ts):\d+/.test(x)) || lines.find(x => /^\s*at\s|^#0?0\s/.test(x)) || '';
+  const fm = frameLine.match(/(entry\/[^\s)]+\.(?:ets|ts):\d+(?::\d+)?)/);
+  return { file, reason, message, frame: fm ? fm[1] : frameLine.trim().slice(0, 160) };
+}
+// 步骤执行器：io = { dump(): nodes[], tap(x,y), input(x,y,text), key(name), swipe(x1,y1,x2,y2,speed?), start(bundle,route,fresh?), stop(bundle), alive(bundle), faults(bundle), faultHead?(file): bool, shot(name): path, sleep(ms), faults(bundle): string[] }
+export function runSteps(plan, io, { stopOnFail = true, label } = {}) {
+  const tag = String(label || plan.name || plan.route || plan.slice || 'plan').replace(/[^\w.-]/g, '_');
+  const report = { bundle: plan.bundle || null, name: tag, steps: [], ok: true, crash: null };
+  const base = new Set(plan.bundle ? io.faults(plan.bundle) : []);
+  // 全程见过的 text/id 并集（上限 3000）：阶段五 render 用它核"静态 passed 的断言字面量真机是否出现过"
+  const seenT = new Set(), seenI = new Set();
+  const dump = () => { const ns = io.dump(); for (const x of ns) { if (seenT.size < 3000 && x.text) seenT.add(x.text); if (seenI.size < 3000 && x.id) seenI.add(x.id); } return ns; };
+  let halted = false;
+  for (const [i, s] of (plan.steps || []).entries()) {
+    const r = { i, op: s.op, ok: true, detail: '' };
+    if (halted) { r.ok = false; r.detail = 'skipped（前步失败）'; r.skipped = true; report.steps.push(r); continue; }
+    const t0 = Date.now();
+    try {
+      switch (s.op) {
+        case 'start': io.start(plan.bundle, s.route || null, !!s.fresh); io.sleep(s.ms || 3000); r.detail = `${s.fresh ? '清数据后' : ''}${s.route ? `直达 ${s.route}` : '冷启'}`; break;
+        case 'stop': io.stop(plan.bundle); break;
+        case 'sleep': io.sleep(s.ms || 500); break;
+        case 'back': io.key('Back'); io.sleep(s.ms || 600); break;
+        case 'key': io.key(s.name); io.sleep(s.ms || 600); break;
+        case 'alive': { const ok = io.alive(plan.bundle); r.ok = ok; r.detail = ok ? '进程在·前台' : '进程不在或不在前台'; if (!ok) r.kind = 'process_died'; break; }
+        case 'shot': r.shot = io.shot(s.name || `step-${i}`); r.detail = r.shot; break;
+        case 'expect': {
+          const nodes = dump(); const pats = Array.isArray(s.match) ? s.match : [s.match];
+          const miss = pats.filter(p => !matchNodes(nodes, p).length);
+          r.ok = !miss.length; r.detail = miss.length ? `缺 [${miss.join(', ')}]（页面 ${nodes.length} 节点）` : `命中 ${pats.length}/${pats.length}`;
+          if (miss.length) { r.kind = 'expect_missing'; r.page = pageDict(nodes); }   // 失败时附页面字典：按实际 text/id 改计划，不用再手工 dump
+          break;
+        }
+        case 'probe': {   // 出现率证据：不判失败，只记见到/未见（状态相关文案给核心路径计划去断言）；附页面字典供写核心路径计划
+          const nodes = dump(); const pats = Array.isArray(s.match) ? s.match : [s.match];
+          const seen = pats.filter(p => matchNodes(nodes, p).length), unseen = pats.filter(p => !seen.includes(p));
+          r.seen = seen; r.unseen = unseen; r.page = pageDict(nodes);
+          r.detail = `出现 ${seen.length}/${pats.length}（页面 ${nodes.length} 节点）${unseen.length ? ` 未见 [${unseen.join(', ')}]` : ''}`;
+          break;
+        }
+        case 'wait': {
+          const deadline = Date.now() + (s.timeout || 8000); let found = false, n = 0;
+          let last = [];
+          while (Date.now() < deadline) { const nodes = dump(); last = nodes; n = nodes.length; if (matchNodes(nodes, s.match).length) { found = true; break; } io.sleep(s.interval || 500); }
+          r.ok = found; r.detail = found ? `出现 ${s.match}` : `等待 ${s.match} 超时（最后 ${n} 节点）`;
+          if (!found) { r.kind = 'expect_missing'; r.page = pageDict(last); }
+          break;
+        }
+        case 'tap': case 'type': {
+          const before = dump();
+          // 点击效果信号需要一个静态基线：点前再取一次树，两次不同 = 页面自变（倒计时/轮播/时钟），信号记 null 不硬判
+          const before2 = s.op === 'tap' ? dump() : null;
+          const { node, candidates, reason, occludedBy: cover } = pickTarget(before, s.match, s.nth, s.within);
+          if (!node) {
+            r.ok = false; r.kind = /歧义/.test(reason) ? 'target_ambiguous' : /越界/.test(reason) ? 'target_out_of_range' : 'target_missing';
+            r.detail = `${reason}：${s.match}${candidates.length ? '；候选 ' + listCandidates(candidates) : ''}`;
+            if (r.kind === 'target_missing') r.page = pageDict(before);   // 无命中附页面字典：照实际 text/id 改计划
+            break;
+          }
+          if (cover) { r.occludedBy = `${cover.type}${cover.id ? '#' + cover.id : ''} ${cover.bounds}`; }
+          const [x, y] = center(node.bounds);
+          if (s.op === 'tap') { io.tap(x, y); r.detail = `点 ${node.type} "${node.text || node.id}" @${x},${y}`; }
+          else { io.input(x, y, String(s.text ?? '')); r.detail = `输入到 ${node.type} "${node.text || node.id}" @${x},${y}`; }
+          io.sleep(s.ms || 800);
+          // 点击效果信号：点前/点后控件树签名不变 = 这一下没产生任何可见变化（不判失败——有的点击本就无界面反馈），
+          // 记 changed:false 供核心路径复盘：连续多步"命中但无变化"是吞点击/接线断的典型体征（实证一轮全应用列表项点击死，
+          // 逐页计划却全"过"，因为只核可达与出现率）
+          if (s.op === 'tap') {
+            const volatile = pageSig(before2) !== pageSig(before);
+            const after = dump();
+            r.changed = volatile ? null : pageSig(after) !== pageSig(before);
+            if (s.expectNoChange) { r.expectNoChange = true; if (r.changed === true) r.detail += '（预期无变化但页面变了）'; }
+            else if (r.changed === false) r.detail += cover ? `（点后页面无变化——命中节点被 ${cover.type} 盖住，点在遮罩上；用 --within 指定弹层内目标）` : '（点后页面无变化）';
+            else if (volatile) r.detail += '（页面自变，无法判定点击效果）';
+          }
+          break;
+        }
+        case 'swipe': {   // 定向滑动（列表翻页/横滑区/触底加载）：within 容器缺省整屏
+          const box = swipeBox(dump(), s.within, s.nth); const line = box && swipeLine(box, s.dir || 'up');
+          if (!line) { r.ok = false; r.kind = box ? 'bad_step' : 'target_missing'; r.detail = box ? `dir 非法：${s.dir}` : `滑动容器无命中：${s.within}`; break; }
+          io.swipe(...line, s.speed); io.sleep(s.ms || 800);
+          r.detail = `滑 ${s.dir || 'up'} ${line[0]},${line[1]}→${line[2]},${line[3]}${s.within ? ` 于 ${s.within}` : ''}`;
+          break;
+        }
+        case 'scrollUntil': {   // 反复滑到目标出现（最多 max 次，默认 8）；未见 → 失败并附页面字典
+          const max = Number.isInteger(s.max) && s.max >= 0 ? s.max : 8; let found = false, n = 0, nodes = dump();
+          for (;;) {
+            if (matchNodes(nodes, s.match).length) { found = true; break; }
+            if (n >= max) break;
+            const box = swipeBox(nodes, s.within, s.nth); const line = box && swipeLine(box, s.dir || 'up');
+            if (!line) { r.detail = box ? `dir 非法：${s.dir}` : `滑动容器无命中：${s.within}`; break; }
+            io.swipe(...line, s.speed); io.sleep(s.ms || 800); n++; nodes = dump();
+          }
+          r.ok = found; r.detail = found ? `滑 ${n} 次后出现 ${s.match}` : (r.detail || `滑 ${n} 次仍未见 ${s.match}（页面 ${nodes.length} 节点）`);
+          if (!found) { r.kind = r.kind || 'expect_missing'; r.page = pageDict(nodes); }
+          break;
+        }
+        default: r.ok = false; r.kind = 'bad_step'; r.detail = `未知 op ${s.op}`;
+      }
+    } catch (e) { r.ok = false; r.kind = 'io_error'; r.detail = `执行异常：${String(e && e.message || e).slice(0, 200)}`; }
+    r.ms = Date.now() - t0;
+    if (!r.ok) {
+      report.ok = false;
+      if (stopOnFail) { halted = true; try { r.shot = io.shot(`fail-${tag}-step-${i}`); } catch { /* 截图失败不改判定 */ } }
+    }
+    report.steps.push(r);
+  }
+  if (plan.bundle) {
+    const fresh = io.faults(plan.bundle).filter(f => !base.has(f));
+    if (fresh.length) {
+      report.crash = fresh; report.ok = false;
+      // 崩溃详情：faultlog 头部的 Reason / Error message / 第一处落在应用源码的栈帧——模型不必再去设备上 cat 再二分
+      report.crashDetail = fresh.map(f => parseFault(f, typeof io.faultHead === 'function' ? io.faultHead(f) : ''));
+      const died = report.steps.filter(x => !x.ok && !x.skipped && x.kind === 'process_died'); for (const x of died) x.crash = report.crashDetail[0];
+    }
+  }
+  report.seen = { texts: [...seenT], ids: [...seenI] };
+  const taps = report.steps.filter(x => x.op === 'tap' && x.ok && !x.skipped);
+  if (taps.length) report.tapsNoChange = taps.filter(x => x.changed === false && !x.expectNoChange).length;   // 未预期的"命中却无变化"点击数，复盘时先看它（禁用态按钮这类写 expectNoChange:true 不计）
+  return report;
+}
+
+// ---------- 参数解析（--continue 是布尔；其余 --flag 取一个值，值不得以 -- 开头） ----------
+const BOOL_FLAGS = new Set(['--continue']);
+export function parseArgs(argv) {
+  const positional = []; const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      if (BOOL_FLAGS.has(a)) { flags[a] = true; continue; }
+      const v = argv[i + 1];
+      if (v === undefined || v.startsWith('--')) { flags[a] = ''; continue; }
+      flags[a] = v; i++;
+    } else positional.push(a);
+  }
+  return { positional, flags };
+}
+
+// ---------- 设备 IO（真机/模拟器） ----------
+function hdc(args, timeout = 60000) {
+  try { return execFileSync('hdc', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout }).trim(); }
+  catch (e) { return ((e.stdout || '') + (e.stderr || '')).trim(); }
+}
+export function listTargets() {
+  const out = hdc(['list', 'targets'], 20000);
+  return out.split('\n').map(s => s.trim()).filter(s => s && !/\[Empty\]|\[Fail\]/i.test(s));
+}
+function makeIo(flags) {
+  const list = listTargets();
+  let key = flags['--device'] || (process.env.HMIG_HDC_TARGET || '').trim();
+  if (!key) {
+    if (!list.length) { console.error('[walk] 环境阻塞（exit 3）：无设备/模拟器'); process.exit(3); }
+    if (list.length > 1) { console.error(`[walk] 环境阻塞（exit 3）：多个设备，--device 或 HMIG_HDC_TARGET 指定其一：${list.join(' ')}`); process.exit(3); }
+    key = list[0];
+  } else if (list.length && !list.includes(key)) { console.error(`[walk] 环境阻塞（exit 3）：设备 ${key} 不在列表：${list.join(' ') || '(空)'}`); process.exit(3); }
+  const shell = (c) => hdc(['-t', key, 'shell', c]);
+  const sleep = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, Math.max(0, ms));
+  const shotsDir = flags['--shots'] || null;
+
+  // 单飞锁：先建临时目录写 pid，再原子改名为锁目录（锁一旦可见 pid 必在）；只有持锁进程已死才视为陈旧；等待上限 60 秒
+  const lock = join(tmpdir(), `hmig-walk-${key.replace(/[^\w.-]/g, '_')}`);
+  const pidOf = () => { try { const n = Number(readFileSync(join(lock, 'pid'), 'utf8').trim()); return Number.isInteger(n) && n > 0 ? n : null; } catch { return null; } };
+  const alivePid = (pid) => { try { process.kill(pid, 0); return true; } catch (e) { return e && e.code === 'EPERM'; } };
+  const acquire = () => {
+    const until = Date.now() + 60000;
+    for (;;) {
+      const tmp = mkdtempSync(join(tmpdir(), 'hmig-walk-tmp-'));
+      writeFileSync(join(tmp, 'pid'), String(process.pid));
+      try { renameSync(tmp, lock); return; } catch { try { rmSync(tmp, { recursive: true, force: true }); } catch { /* 忽略 */ } }
+      const pid = pidOf();
+      if (pid === null || !alivePid(pid)) { try { rmSync(lock, { recursive: true, force: true }); } catch { /* 下轮再试 */ } }
+      if (Date.now() > until) { console.error(`[walk] 环境阻塞（exit 3）：设备 ${key} 的走查锁被进程 ${pid ?? '?'} 持有超过 60 秒（4b 走查必须单飞，不要并行跑 hdc）`); process.exit(3); }
+      sleep(500);
+    }
+  };
+  acquire();
+  const localTree = join(tmpdir(), `hmig-walk-${process.pid}.json`);
+  process.on('exit', () => {
+    if (pidOf() === process.pid) { try { rmSync(lock, { recursive: true, force: true }); } catch { /* 忽略 */ } }
+    try { unlinkSync(localTree); } catch { /* 忽略 */ }
+  });
+  const dumpRaw = () => {
+    for (let i = 0; i < 3; i++) {
+      const out = shell('uitest dumpLayout');
+      const m = out.match(/\/\S+\.json/);
+      if (m) {
+        try { unlinkSync(localTree); } catch { /* 无旧文件 */ }
+        hdc(['-t', key, 'file', 'recv', m[0], localTree]);
+        try { if (existsSync(localTree)) { const nodes = flatten(JSON.parse(readFileSync(localTree, 'utf8'))); if (nodes.length) return nodes; } } catch { /* 重试 */ }
+      }
+      sleep(500);
+    }
+    return [];
+  };
+  const shotPath = (name) => {
+    const s = String(name);
+    if (isAbsolute(s) || s.includes('/') || s.includes(sep)) { const p = resolve(/\.png$/i.test(s) ? s : s + '.png'); mkdirSync(dirname(p), { recursive: true }); return p; }
+    const dir = shotsDir || join(process.cwd(), 'spec', '4b', 'shots'); mkdirSync(dir, { recursive: true });
+    return join(dir, `${s.replace(/\.png$/i, '').replace(/[^\w.-]/g, '_')}.png`);
+  };
+  return {
+    key, list, sleep,
+    dump: dumpRaw,
+    tap: (x, y) => shell(`uitest uiInput click ${x} ${y}`),
+    input: (x, y, text) => { shell(`uitest uiInput click ${x} ${y}`); sleep(300); shell(`uitest uiInput inputText ${x} ${y} '${String(text).replace(/'/g, "'\\''")}'`); },
+    key: (name) => shell(`uitest uiInput keyEvent ${name}`),
+    swipe: (x1, y1, x2, y2, speed) => shell(`uitest uiInput swipe ${x1} ${y1} ${x2} ${y2} ${Number(speed) > 0 ? Number(speed) : 600}`),
+    start: (bundle, route, fresh) => { shell(`aa force-stop ${bundle}`); sleep(500); if (fresh) { shell(`bm clean -n ${bundle} -d`); sleep(500); } shell(`aa start -a EntryAbility -b ${bundle}${route ? ` --ps smokeRoute ${route}` : ''}`); },
+    stop: (bundle) => shell(`aa force-stop ${bundle}`),
+    alive: (bundle) => { const pid = shell(`pidof ${bundle}`); const d = shell('aa dump -l'); return !!pid && d.split(/Mission ID #/).some(b => b.includes(`bundle name [${bundle}]`) && /state #FOREGROUND/.test(b)); },
+    shot: (name) => { const local = shotPath(name); shell('uitest screenCap -p /data/local/tmp/hmig-walk.png'); hdc(['-t', key, 'file', 'recv', '/data/local/tmp/hmig-walk.png', local]); return local; },
+    faults: (bundle) => shell('ls /data/log/faultlog/faultlogger/ 2>/dev/null').split(/\s+/).filter(f => f && /jscrash|cppcrash/.test(f) && f.includes(bundle)),
+    faultHead: (file) => shell(`head -60 /data/log/faultlog/faultlogger/${String(file).replace(/[^\w.-]/g, '')}`),
+  };
+}
+
+// ---------- CLI ----------
+const isMain = (() => { try { return process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url); } catch { return false; } })();
+if (isMain) {
+  const [cmd, ...rest] = process.argv.slice(2);
+  const { positional, flags } = parseArgs(rest);
+  const fail = (code, msg) => { console.error(`[walk] ${msg}`); process.exit(code); };
+  if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') { console.log(readFileSync(new URL(import.meta.url), 'utf8').split('\n').filter(l => /^ \* /.test(l)).map(l => l.slice(3)).join('\n')); process.exit(0); }
+  if (cmd === 'devices') { const t = listTargets(); console.log(t.join('\n') || '(无设备)'); process.exit(0); }
+  if (cmd === 'plan') {
+    const ledgerPath = flags['--ledger'], project = flags['--project'], out = flags['--out'];
+    if (!ledgerPath || !existsSync(ledgerPath) || !out) fail(3, 'plan 需要 --ledger <ledger.json> --out <目录>（--project 取 bundleName，或 --bundle）');
+    let bundle = flags['--bundle'] || null;
+    if (!bundle && project) { const app = join(project, 'AppScope', 'app.json5'); const m = existsSync(app) ? readFileSync(app, 'utf8').match(/"bundleName"\s*:\s*"([^"]+)"/) : null; bundle = m ? m[1] : null; }
+    if (!bundle) fail(3, '解析不到 bundleName：给 --project 或 --bundle');
+    let ledger; try { ledger = JSON.parse(readFileSync(ledgerPath, 'utf8')); } catch (e) { fail(3, `台账解析失败：${e.message}`); }
+    const plans = buildPlans(ledger, bundle);
+    mkdirSync(out, { recursive: true });
+    for (const p of plans) writeFileSync(join(out, `${p.name}.json`), JSON.stringify(p.plan, null, 2));
+    const withProbe = plans.filter(p => p.plan.steps.some(s => s.op === 'probe')).length;
+    const self = relative(process.cwd(), fileURLToPath(import.meta.url)) || fileURLToPath(import.meta.url);
+    console.log(`[walk] 台账 ${(ledger.slices || []).length} 片 → ${plans.length} 份逐页计划（${withProbe} 份带字面量 probe，只记出现率）→ ${out}/`);
+    for (const p of plans) console.log(`  node ${self} run ${join(out, p.name + '.json')} --out ${join(out, p.name + '.report.json')}`);
+    process.exit(0);
+  }
+  const io = makeIo(flags);
+  switch (cmd) {
+    case 'start': { if (!positional[0]) fail(3, 'start 需要 <bundle>'); const route = flags['--route'] || null; io.start(positional[0], route, !!flags['--fresh']); io.sleep(3000); console.log(`started ${positional[0]}${route ? ' → ' + route : ''}`); break; }
+    case 'stop': if (!positional[0]) fail(3, 'stop 需要 <bundle>'); io.stop(positional[0]); console.log('stopped'); break;
+    case 'alive': { if (!positional[0]) fail(3, 'alive 需要 <bundle>'); const ok = io.alive(positional[0]); console.log(ok ? `alive ${positional[0]}（前台）` : `dead/background ${positional[0]}`); process.exit(ok ? 0 : 4); }
+    case 'dump': { const nodes = io.dump(); const pat = positional[0]; const pick = pat ? matchNodes(nodes, pat) : nodes.filter(n => n.text || n.id || n.clickable); for (const n of pick) console.log(describe(n)); const gm = pageDict(nodes).geometry; if (!pat && Object.keys(gm).length) console.log('geometry(center x,y 归一化; 0=左/上 1=右/下): ' + Object.entries(gm).map(([k, v]) => `${k}=(${v.center[0]},${v.center[1]})`).join(' ')); if (!nodes.length) fail(4, '控件树为空（三次重试）'); break; }
+    case 'tap': case 'type': {
+      if (!positional[0]) fail(3, `${cmd} 需要 <匹配>`);
+      const { node, candidates, reason, occludedBy: cover } = pickTarget(io.dump(), positional[0], flags['--nth'], flags['--within']);
+      if (!node) { candidates.slice(0, 8).forEach((c, i) => console.log(describe(c, i))); fail(5, `${reason}：${positional[0]}`); }
+      const [x, y] = center(node.bounds);
+      if (cmd === 'tap') { io.tap(x, y); console.log(`tap ${node.type} "${node.text || node.id}" @${x},${y}${cover ? `（⚠ 该节点被 ${cover.type} 盖住，点击落在遮罩上；弹层内目标用 --within）` : ''}`); }
+      else { io.input(x, y, positional.slice(1).join(' ')); console.log(`type into ${node.type} "${node.text || node.id}" @${x},${y}`); }
+      break;
+    }
+    case 'back': io.key('Back'); console.log('back'); break;
+    case 'key': if (!positional[0]) fail(3, 'key 需要 <键名>'); io.key(positional[0]); console.log(`key ${positional[0]}`); break;
+    case 'swipe': {
+      const dir = positional[0] || 'up'; const box = swipeBox(io.dump(), flags['--within'], flags['--nth']); const line = box && swipeLine(box, dir);
+      if (!line) fail(box ? 3 : 5, box ? `dir 须为 up|down|left|right：${dir}` : `滑动容器无命中：${flags['--within']}`);
+      io.swipe(...line); io.sleep(800); console.log(`swipe ${dir} ${line[0]},${line[1]}→${line[2]},${line[3]}`); break;
+    }
+    case 'scroll': {
+      if (!positional[0]) fail(3, 'scroll 需要 <匹配>');
+      const rep = runSteps({ steps: [{ op: 'scrollUntil', match: positional[0], dir: flags['--dir'] || 'up', within: flags['--within'], nth: flags['--nth'], max: Number(flags['--max'] || 8) }] }, io, { label: 'scroll' });
+      const st = rep.steps[0]; console.log(st.detail); if (!st.ok) { if (st.page) console.log(`页面文本：${st.page.texts.slice(0, 40).join(' | ')}`); process.exit(4); } break;
+    }
+    case 'expect': { if (!positional.length) fail(3, 'expect 需要至少一个 <匹配>'); const nodes = io.dump(); const miss = positional.filter(p => !matchNodes(nodes, p).length); if (miss.length) fail(4, `缺 [${miss.join(', ')}]（页面 ${nodes.length} 节点）`); console.log(`expect 命中 ${positional.length}/${positional.length}`); break; }
+    case 'probe': { if (!positional.length) fail(3, 'probe 需要至少一个 <匹配>'); const nodes = io.dump(); const seen = positional.filter(p => matchNodes(nodes, p).length); const unseen = positional.filter(p => !seen.includes(p)); console.log(`probe 出现 ${seen.length}/${positional.length}（页面 ${nodes.length} 节点）${unseen.length ? ` 未见 [${unseen.join(', ')}]` : ''}`); break; }
+    case 'wait': { if (!positional[0]) fail(3, 'wait 需要 <匹配>'); const deadline = Date.now() + Number(flags['--timeout'] || 8000); let found = false; while (Date.now() < deadline) { if (matchNodes(io.dump(), positional[0]).length) { found = true; break; } io.sleep(500); } if (!found) fail(4, `等待 ${positional[0]} 超时`); console.log(`wait 出现 ${positional[0]}`); break; }
+    case 'shot': { const p = io.shot(positional[0] || 'shot'); console.log(p); break; }
+    case 'faults': { if (!positional[0]) fail(3, 'faults 需要 <bundle>'); const f = io.faults(positional[0]); console.log(f.join('\n') || '(无崩溃日志)'); break; }
+    case 'run': {
+      const planPath = positional[0]; if (!planPath || !existsSync(planPath)) fail(3, 'run 需要 steps.json 路径');
+      let plan; try { plan = JSON.parse(readFileSync(planPath, 'utf8')); } catch (e) { fail(3, `steps.json 解析失败：${e.message}`); }
+      if (!plan.bundle || !Array.isArray(plan.steps) || !plan.steps.length) fail(3, 'steps.json 须含 bundle 与非空 steps');
+      const report = runSteps(plan, io, { stopOnFail: !flags['--continue'], label: plan.name || plan.route || planPath.replace(/^.*[\\/]/, '').replace(/\.json$/i, '') });
+      const out = flags['--out'] || null;
+      // 同一份计划连续失败计数（同 --out 覆盖写时读上一份）：≥2 即"修复循环"信号，4b 纪律按它止损
+      let prevStreak = 0; if (out && existsSync(resolve(out))) { try { prevStreak = Number(JSON.parse(readFileSync(resolve(out), 'utf8')).failStreak) || 0; } catch { prevStreak = 0; } }
+      report.failStreak = report.ok ? 0 : prevStreak + 1;
+      if (out) { mkdirSync(dirname(resolve(out)), { recursive: true }); writeFileSync(resolve(out), JSON.stringify({ plan: relative(process.cwd(), resolve(planPath)) || planPath, device: io.key, at: new Date().toISOString(), ...report }, null, 2)); }
+      for (const s of report.steps) console.log(`  ${s.skipped ? '·' : s.ok ? '✓' : '✗'} [${s.i}] ${s.op} ${s.detail}${s.kind ? ` [${s.kind}]` : ''}${s.ms != null ? ` (${s.ms}ms)` : ''}${s.shot && !s.ok ? ` 现场 ${s.shot}` : ''}`);
+      if (report.failStreak >= 2) console.log(`⚠ 本计划连续第 ${report.failStreak} 次失败——同一缺陷只允许一次定向修+一次复验，仍败即记 failed 交阶段五，不再改代码`);
+      if (report.crash) { console.log(`✗ 走查期间崩溃：${report.crash.join(', ')}`); for (const c of report.crashDetail || []) console.log(`    ${c.file}: ${c.message || c.reason || '?'}${c.frame ? ` @ ${c.frame}` : ''}`); process.exit(10); }
+      const bad = report.steps.filter(s => !s.ok && !s.skipped).length;
+      console.log(`[walk] ${bad ? `${bad} 步未过` : `${report.steps.length} 步全过`}${report.tapsNoChange ? `（${report.tapsNoChange} 次点击命中但页面无变化——查吞点击/接线）` : ''}${out ? ` → ${out}` : ''}`);
+      process.exit(bad ? 4 : 0);
+    }
+    default: fail(3, `未知命令 ${cmd}（walk.mjs help 看用法）`);
+  }
+}

package/skills/migrate-core/scripts/transpile/mapping.json

@@ -0,0 +1,76 @@
+{
+  "version": "0.1.0",
+  "_doc": "布局转译映射表（数据即语料）。规则来源：references/ui-alignment（组件映射/布局映射 301 行）与 references/flow/ui-layout-semantics.md。新控件=加条目→过 benchmarks 转译率靶。widget.kind: container(容器)|leaf(叶子)|scroll(滚动容器)|list(列表)|passthrough(透传children)。",
+  "widgets": {
+    "LinearLayout": { "kind": "container", "byOrientation": { "vertical": "Column", "horizontal": "Row" }, "default": "Column" },
+    "FrameLayout": { "kind": "container", "component": "Stack" },
+    "RelativeLayout": { "kind": "container", "component": "Stack", "todo": "RelativeLayout 相对约束简化为 Stack——切片阶段按源约束改 RelativeContainer 或对齐修正" },
+    "androidx.constraintlayout.widget.ConstraintLayout": { "kind": "container", "component": "Column", "todo": "ConstraintLayout 约束未转译——切片阶段按源约束重排（参考 ui-layout-semantics §2）" },
+    "ScrollView": { "kind": "scroll", "component": "Scroll" },
+    "androidx.core.widget.NestedScrollView": { "kind": "scroll", "component": "Scroll" },
+    "HorizontalScrollView": { "kind": "scroll", "component": "Scroll", "todo": "水平滚动：.scrollable(ScrollDirection.Horizontal)" },
+    "TextView": { "kind": "leaf", "component": "Text", "contentAttr": "android:text" },
+    "Button": { "kind": "leaf", "component": "Button", "contentAttr": "android:text" },
+    "com.google.android.material.button.MaterialButton": { "kind": "leaf", "component": "Button", "contentAttr": "android:text" },
+    "ImageView": { "kind": "leaf", "component": "Image", "contentAttr": "android:src" },
+    "ImageButton": { "kind": "leaf", "component": "Image", "contentAttr": "android:src", "todo": "ImageButton：外包可点击语义（onClick 由切片接）" },
+    "EditText": { "kind": "leaf", "component": "TextInput", "placeholderAttr": "android:hint" },
+    "androidx.appcompat.widget.AppCompatEditText": { "kind": "leaf", "component": "TextInput", "placeholderAttr": "android:hint" },
+    "CheckBox": { "kind": "leaf", "component": "Checkbox" },
+    "Switch": { "kind": "leaf", "component": "Toggle", "todo": "Toggle(type: ToggleType.Switch)" },
+    "androidx.appcompat.widget.SwitchCompat": { "kind": "leaf", "component": "Toggle", "todo": "Toggle(type: ToggleType.Switch)" },
+    "RadioButton": { "kind": "leaf", "component": "Radio" },
+    "ProgressBar": { "kind": "leaf", "component": "Progress", "todo": "不定进度用 LoadingProgress" },
+    "SeekBar": { "kind": "leaf", "component": "Slider" },
+    "Spinner": { "kind": "leaf", "component": "Select" },
+    "View": { "kind": "leaf", "component": "Divider", "onlyWhenThin": true, "fallback": "Blank" },
+    "Space": { "kind": "leaf", "component": "Blank" },
+    "androidx.recyclerview.widget.RecyclerView": { "kind": "list", "component": "List", "todo": "列表项模板与数据源由切片接（LazyForEach）" },
+    "ListView": { "kind": "list", "component": "List", "todo": "列表项模板与数据源由切片接" },
+    "GridView": { "kind": "list", "component": "Grid", "todo": "列宽/项模板由切片接" },
+    "androidx.viewpager2.widget.ViewPager2": { "kind": "container", "component": "Swiper" },
+    "androidx.viewpager.widget.ViewPager": { "kind": "container", "component": "Swiper" },
+    "WebView": { "kind": "leaf", "component": "Web", "todo": "Web({src, controller}) 控制器由切片接" },
+    "androidx.cardview.widget.CardView": { "kind": "container", "component": "Column", "extraMods": [".borderRadius(8)", ".shadow({ radius: 4, color: '#1F000000' })"], "todo": "CardView 阴影/圆角按源值核对" },
+    "com.google.android.material.card.MaterialCardView": { "kind": "container", "component": "Column", "extraMods": [".borderRadius(8)", ".shadow({ radius: 4, color: '#1F000000' })"] },
+    "androidx.appcompat.widget.Toolbar": { "kind": "container", "component": "Row", "todo": "Toolbar：标题/导航钮/菜单由切片按源接（或用 Navigation 标题栏）" },
+    "com.google.android.material.appbar.AppBarLayout": { "kind": "passthrough" },
+    "com.google.android.material.floatingactionbutton.FloatingActionButton": { "kind": "leaf", "component": "Button", "extraMods": [".type(ButtonType.Circle)"], "contentAttr": "android:src" },
+    "com.google.android.material.textfield.TextInputLayout": { "kind": "passthrough" },
+    "com.google.android.material.textfield.TextInputEditText": { "kind": "leaf", "component": "TextInput", "placeholderAttr": "android:hint" },
+    "merge": { "kind": "passthrough" },
+    "Toolbar": { "kind": "container", "component": "Row", "todo": "Toolbar：标题/导航钮/菜单由切片按源接" },
+    "include": { "kind": "include" },
+    "ViewAnimator": { "kind": "container", "component": "Stack", "todo": "ViewAnimator 子视图切换：切片用 if/visibility 控制" },
+    "ViewFlipper": { "kind": "container", "component": "Stack", "todo": "同 ViewAnimator" },
+    "androidx.coordinatorlayout.widget.CoordinatorLayout": { "kind": "container", "component": "Stack", "todo": "Coordinator 行为（折叠/锚定）由切片按源实现" },
+    "TableLayout": { "kind": "container", "component": "Column", "todo": "表格列对齐由切片核对" },
+    "TableRow": { "kind": "container", "component": "Row" },
+    "CheckedTextView": { "kind": "leaf", "component": "Text", "contentAttr": "android:text", "todo": "选中态由切片接" },
+    "RadioGroup": { "kind": "container", "component": "Column", "todo": "互斥选择语义由切片接" },
+    "AutoCompleteTextView": { "kind": "leaf", "component": "TextInput", "placeholderAttr": "android:hint", "todo": "补全弹层由切片接" },
+    "ViewStub": { "kind": "leaf", "component": "Blank", "todo": "懒加载占位：切片按需装配" },
+    "TextureView": { "kind": "leaf", "component": "XComponent", "todo": "渲染表面：切片接控制器" },
+    "SurfaceView": { "kind": "leaf", "component": "XComponent", "todo": "渲染表面：切片接控制器" },
+    "fragment": { "kind": "leaf", "component": "Column", "todo": "fragment 容器：宿主页面由切片装配" },
+    "androidx.fragment.app.FragmentContainerView": { "kind": "leaf", "component": "Column", "todo": "fragment 容器：宿主页面由切片装配" },
+    "androidx.swiperefreshlayout.widget.SwipeRefreshLayout": { "kind": "passthrough", "todo": "下拉刷新：切片外包 Refresh({refreshing}) 并把源 onRefresh 接到 onRefreshing" },
+    "androidx.drawerlayout.widget.DrawerLayout": { "kind": "container", "component": "Stack", "todo": "抽屉导航：切片按 SideBarContainer(SideBarContainerType.Overlay) 重构（主内容+抽屉两子）" },
+    "com.google.android.material.bottomnavigation.BottomNavigationView": { "kind": "leaf", "component": "Row", "todo": "底部导航：壳层用 Tabs+TabContent 重构（menu XML 项→tabBar），本节点仅占位" }
+  },
+  "fallbackSuffixes": {
+    "_doc": "未知控件按类名后缀回退到标准词条（自定义子类极常见：MyTextView/CurrencyTextView→TextView）。命中即按标准词条转译并加『custom subclass』注记。顺序即优先级；不含裸 View（过于贪婪）。",
+    "order": ["RecyclerView", "AutoCompleteTextView", "TextInputEditText", "TextInputLayout", "EditText", "TextView", "ImageButton", "ImageView", "MaterialSwitch", "Switch", "Checkbox", "CheckBox", "RadioButton", "RadioGroup", "FloatingActionButton", "MaterialButton", "Button", "AppBarLayout", "Toolbar", "ProgressBar", "SeekBar", "Spinner", "ViewPager2", "ViewPager", "NestedScrollView", "ScrollView", "CardView", "LinearLayout", "FrameLayout", "RelativeLayout", "ConstraintLayout", "CoordinatorLayout", "ListView", "GridView", "WebView", "TableLayout", "TableRow", "SwipeRefreshLayout", "DrawerLayout", "BottomNavigationView"],
+    "alias": { "MaterialSwitch": "Switch", "Checkbox": "CheckBox", "ConstraintLayout": "androidx.constraintlayout.widget.ConstraintLayout", "CoordinatorLayout": "androidx.coordinatorlayout.widget.CoordinatorLayout", "NestedScrollView": "androidx.core.widget.NestedScrollView", "ViewPager2": "androidx.viewpager2.widget.ViewPager2", "ViewPager": "androidx.viewpager.widget.ViewPager", "RecyclerView": "androidx.recyclerview.widget.RecyclerView", "CardView": "androidx.cardview.widget.CardView", "FloatingActionButton": "com.google.android.material.floatingactionbutton.FloatingActionButton", "MaterialButton": "com.google.android.material.button.MaterialButton", "TextInputLayout": "com.google.android.material.textfield.TextInputLayout", "TextInputEditText": "com.google.android.material.textfield.TextInputEditText", "AppBarLayout": "com.google.android.material.appbar.AppBarLayout", "SwipeRefreshLayout": "androidx.swiperefreshlayout.widget.SwipeRefreshLayout", "DrawerLayout": "androidx.drawerlayout.widget.DrawerLayout", "BottomNavigationView": "com.google.android.material.bottomnavigation.BottomNavigationView" }
+  },
+  "dimenUnits": { "dp": "vp", "dip": "vp", "sp": "fp", "px": "px" },
+  "gravity": {
+    "_doc": "gravity → 主轴 justifyContent / 交叉轴 alignItems，由代码按容器方向分派",
+    "center": { "h": "Center", "v": "Center" },
+    "center_horizontal": { "h": "Center" },
+    "center_vertical": { "v": "Center" },
+    "start": { "h": "Start" }, "left": { "h": "Start" },
+    "end": { "h": "End" }, "right": { "h": "End" },
+    "top": { "v": "Start" }, "bottom": { "v": "End" }
+  }
+}