deveco_hmigbot 0.21.5

package/skills/migrate-core/scripts/lib/scan.mjs

@@ -0,0 +1,315 @@
+/**
+ * scan.mjs — 闭合检查器共享的文本处理层（原三份手拷逐行状态机的替代）。
+ *
+ * 设计不变量：所有"脱敏"变换都做**同长度空格替换、保留换行**——调用方的
+ * 偏移量/行号在变换前后完全一致，可以在脱敏文本上定位、回原文取内容。
+ *
+ * 修复的审查发现：
+ *  - 跨行模板串里的 `//` 被旧逐行状态机当行注释砍掉行尾真实代码；
+ *  - 正则字面量里的 `//`、`/*` 同病；
+ *  - functionBodies 裸括号计数不识字符串里的 {}()，边界错乱；
+ *  - walk 无深度上限/符号链接环 → 栈溢出（transpile 有上限，closure 三件没有）。
+ */
+import { readdirSync, lstatSync, readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const RE_BEFORE = new Set([...'(,=:[!&|?{};+-*%~^<>'.split(''), undefined]);
+const RE_KEYWORDS = /(?:return|typeof|case|in|of|instanceof|new|delete|void|do|else|yield|await)$/;
+
+/**
+ * 单趟全文状态机。mode 栈支持模板串 ${} 内嵌套代码（含再嵌模板串）。
+ * cb(i, ch, state) 逐字符回调，state ∈ code|line|block|str1|str2|tpl|regex|regexClass
+ */
+function scan(code, cb) {
+  const stack = ['code']; // 栈顶为当前态；tpl 的 ${ 会压入 code
+  let i = 0;
+  let prevSig; // 上一个有效代码字符（判断 / 是否正则起点）
+  let word = ''; // 追踪紧邻标识符（return 等关键字后可跟正则）
+  const n = code.length;
+  while (i < n) {
+    const st = stack[stack.length - 1];
+    const c = code[i], c2 = code[i + 1];
+    if (st === 'line') {
+      cb(i, c, st);
+      if (c === '\n') stack.pop();
+      i++; continue;
+    }
+    if (st === 'block') {
+      cb(i, c, st);
+      if (c === '*' && c2 === '/') { cb(i + 1, c2, st); i += 2; stack.pop(); continue; }
+      i++; continue;
+    }
+    if (st === 'str1' || st === 'str2') {
+      cb(i, c, st);
+      if (c === '\\') { if (i + 1 < n) cb(i + 1, code[i + 1], st); i += 2; continue; }
+      if (c === (st === 'str1' ? "'" : '"') || c === '\n') stack.pop(); // 未闭合到行尾也退出
+      i++; continue;
+    }
+    if (st === 'tpl') {
+      if (c === '\\') { cb(i, c, st); if (i + 1 < n) cb(i + 1, code[i + 1], st); i += 2; continue; }
+      if (c === '`') { cb(i, c, st); stack.pop(); i++; continue; }
+      if (c === '$' && c2 === '{') { cb(i, c, st); cb(i + 1, c2, st); stack.push('code'); i += 2; continue; }
+      cb(i, c, st); i++; continue;
+    }
+    if (st === 'regex' || st === 'regexClass') {
+      cb(i, c, st);
+      if (c === '\\') { if (i + 1 < n) cb(i + 1, code[i + 1], st); i += 2; continue; }
+      if (st === 'regexClass') { if (c === ']') { stack.pop(); stack.push('regex'); } }
+      else if (c === '[') { stack.pop(); stack.push('regexClass'); }
+      else if (c === '/' || c === '\n') stack.pop(); // 换行=其实不是正则，放弃（已按原样保留）
+      i++; continue;
+    }
+    // st === 'code'
+    if (c === '/' && c2 === '/') { stack.push('line'); cb(i, c, 'line'); cb(i + 1, c2, 'line'); i += 2; continue; }
+    if (c === '/' && c2 === '*') { stack.push('block'); cb(i, c, 'block'); cb(i + 1, c2, 'block'); i += 2; continue; }
+    if (c === "'") { cb(i, c, 'str1'); stack.push('str1'); i++; continue; }
+    if (c === '"') { cb(i, c, 'str2'); stack.push('str2'); i++; continue; }
+    if (c === '`') { cb(i, c, 'tpl'); stack.push('tpl'); i++; continue; }
+    // 插值闭合 } 是代码结构字符，报 'code'——原报 'tpl' 使 blankStrings 把它空白化而 ${ 却保留，
+    // brace 失衡 → try/catch 等 brace 追踪在含模板串插值的块上整体错位（真实工程假阴性实证）。
+    if (c === '}' && stack.length > 1 && stack[stack.length - 2] === 'tpl') { cb(i, c, 'code'); stack.pop(); i++; continue; }
+    if (c === '/' && (RE_BEFORE.has(prevSig) || RE_KEYWORDS.test(word))) { cb(i, c, 'regex'); stack.push('regex'); i++; continue; }
+    cb(i, c, 'code');
+    if (!/\s/.test(c)) { prevSig = c; word = /[\w$]/.test(c) ? word + c : ''; }
+    i++; continue;
+  }
+}
+
+/**
+ * 枚举工程内全部模块源根。**构建真源优先**：build-profile.json5 的 modules[].srcPath 是模块清单的
+ * 唯一权威（多产品/自定义布局都由它显式声明，不靠目录名猜）；无法解析时退目录兜底
+ * （路径后缀 src/main/ets，任意嵌套——entry、features/x、commons/a/b 通吃）。
+ * 修的盲区：检查器原只扫 entry/src/main/ets，多 HAP/HSP/HAR 工程九成源码不被查（实证：218 文件仅 21 在 entry）。
+ * 找不到任何模块根时回落 [projectRoot]（调用方 walkFiles 自会按扩展名过滤）。
+ */
+export function moduleSrcRoots(projectRoot) {
+  // 1) 构建真源：build-profile.json5 modules[].srcPath
+  const bp = join(projectRoot, 'build-profile.json5');
+  if (existsSync(bp)) {
+    try {
+      const txt = stripComments(readFileSync(bp, 'utf8'));
+      const roots = [];
+      for (const m of txt.matchAll(/["']srcPath["']\s*:\s*["']([^"']+)["']/g)) {
+        const p = join(projectRoot, m[1], 'src', 'main', 'ets');
+        if (existsSync(p)) roots.push(p);
+      }
+      if (roots.length) return roots;
+    } catch { /* 解析失败走目录兜底 */ }
+  }
+  // 2) 目录兜底（无 build-profile 的裸模块/测试夹具）
+  const SKIP = new Set(['build', 'oh_modules', 'node_modules', 'hvigor', 'AppScope']);
+  const roots = [];
+  const walkDir = (d, depth) => {
+    if (depth > 5) return;
+    let entries; try { entries = readdirSync(d, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (!e.isDirectory() || SKIP.has(e.name) || e.name.startsWith('.')) continue;
+      const p = join(d, e.name);
+      if (e.name === 'ets' && d.endsWith(join('src', 'main'))) { roots.push(p); continue; }
+      walkDir(p, depth + 1);
+    }
+  };
+  walkDir(projectRoot, 0);
+  return roots.length ? roots : [projectRoot];
+}
+
+/**
+ * try/catch 区间追踪（brace 精确；输入应已 stripComments+blankStrings 中和）。
+ * 返回 [{start,end,catchStart,catchEnd}]（均为 {} 偏移；无 catch 时 -1）。
+ * 共享层唯一实现——原 api-guards/permissions 各持一份手拷（本库的存在理由就是反手拷）。
+ */
+export function tryCatchRanges(code) {
+  const tries = [];
+  const stack = []; let pendingTry = false;
+  for (let i = 0; i < code.length; i++) {
+    const c = code[i];
+    if (c === 't' && code.slice(i, i + 3) === 'try' && !/[\w$]/.test(code[i - 1] || '') && !/[\w$]/.test(code[i + 3] || '')) {
+      pendingTry = true; i += 2; continue;
+    }
+    if (c === '{') { stack.push({ isTry: pendingTry, start: i }); pendingTry = false; }
+    else if (c === '}') {
+      const top = stack.pop();
+      if (top && top.isTry) {
+        const entry = { start: top.start, end: i, catchStart: -1, catchEnd: -1 };
+        const m = /^\s*catch\s*(\([^)]*\))?\s*\{/.exec(code.slice(i + 1));
+        if (m) {
+          const cs = i + m[0].length;
+          let d = 0;
+          for (let j = cs; j < code.length; j++) {
+            if (code[j] === '{') d++;
+            else if (code[j] === '}') { d--; if (!d) { entry.catchStart = cs; entry.catchEnd = j; break; } }
+          }
+        }
+        tries.push(entry);
+      }
+    } else if (!/\s/.test(c)) { if (pendingTry && c !== '(') pendingTry = false; }
+  }
+  return tries;
+}
+/** off 所在的最内层 try 块（无则 null）。 */
+export function enclosingTry(tries, off) {
+  let best = null;
+  for (const t of tries) if (off > t.start && off < t.end && (!best || t.start > best.start)) best = t;
+  return best;
+}
+
+/**
+ * 函数级上下文区间（输入应已 stripComments+blankStrings 中和）——同步抛落在哪种"栈"上决定后果：
+ *  'async'：async 函数/方法/箭头体——同步抛变成拒绝（模拟器实测：不杀进程、不进 faultlog，静默失败）；
+ *  'then' ：.then/.catch/.finally 的回调（块体箭头按其体、其余按整段实参）——同上；
+ *  'sync' ：其余函数/方法/块体箭头（事件回调、定时器、生命周期）——未捕获即杀进程。
+ * 返回 [{start,end,kind}]（{} 或 () 偏移）；用 innermostContext 取包含 off 的最内层。
+ * 只做"降级"判断：async 体内被同步调用的普通箭头（map/forEach 回调）仍算 'sync'，宁可多报不漏报。
+ */
+export function functionContexts(code) {
+  const out = [];
+  const matchBrace = (open) => { let d = 0; for (let j = open; j < code.length; j++) { if (code[j] === '{') d++; else if (code[j] === '}') { d--; if (!d) return j; } } return -1; };
+  const matchParen = (open) => { let d = 0; for (let j = open; j < code.length; j++) { if (code[j] === '(') d++; else if (code[j] === ')') { d--; if (!d) return j; } } return -1; };
+  const matchParenBack = (close) => { let d = 0; for (let j = close; j >= 0; j--) { if (code[j] === ')') d++; else if (code[j] === '(') { d--; if (!d) return j; } } return -1; };
+  let m;
+  // ① 函数/方法：修饰符 (async)? (function)? name(params) (: T)? {
+  const fre = /(?:static\s+|private\s+|public\s+|protected\s+|export\s+|async\s+)*(?:function\s+)?([A-Za-z_$][\w$]*)\s*\(/g;
+  while ((m = fre.exec(code)) !== null) {
+    if (['if', 'for', 'while', 'switch', 'catch', 'return', 'function', 'async', 'await', 'typeof', 'new', 'else'].includes(m[1])) continue;
+    const close = matchParen(fre.lastIndex - 1); if (close < 0) continue;
+    const bm = /^\s*(?::\s*[^{;=]*?)?\{/.exec(code.slice(close + 1)); if (!bm) continue;
+    const start = close + bm[0].length; const end = matchBrace(start); if (end < 0) continue;
+    out.push({ start, end, kind: /\basync\s/.test(m[0]) ? 'async' : 'sync' });
+  }
+  // ② 块体箭头：(params) => {  /  x => {   ；前缀 async → 'async'；紧跟 .then( / .catch( / .finally( → 'then'
+  const are = /=>\s*\{/g;
+  while ((m = are.exec(code)) !== null) {
+    const start = m.index + m[0].length - 1; const end = matchBrace(start); if (end < 0) continue;
+    const head = code.slice(0, m.index);
+    let ps = -1;
+    const withParen = /\)\s*(?::\s*[\w$<>\[\]|,.?\s]*)?\s*$/.exec(head);
+    if (withParen) ps = matchParenBack(withParen.index);
+    else { const ident = /([A-Za-z_$][\w$]*)\s*$/.exec(head); if (ident) ps = ident.index; }
+    if (ps < 0) continue;
+    const pre = code.slice(0, ps);
+    const isAsync = /\basync\s*$/.test(pre);
+    const isThen = /\.\s*(?:then|catch|finally)\s*\(\s*(?:async\s*)?$/.test(pre);
+    out.push({ start, end, kind: isAsync ? 'async' : isThen ? 'then' : 'sync' });
+  }
+  // ③ then/catch/finally 的整段实参（表达式体箭头、函数引用也覆盖）
+  const tre = /\.\s*(?:then|catch|finally)\s*\(/g;
+  while ((m = tre.exec(code)) !== null) {
+    const open = m.index + m[0].length - 1; const close = matchParen(open); if (close < 0) continue;
+    out.push({ start: open, end: close, kind: 'then' });
+  }
+  return out;
+}
+/** off 所在的最内层函数级上下文（无则 null，视为顶层同步）。 */
+export function innermostContext(ranges, off) {
+  let best = null;
+  for (const r of ranges) if (off > r.start && off < r.end && (!best || r.start > best.start)) best = r;
+  return best;
+}
+
+/** 注释→同长度空格（换行保留）；字符串/模板串/正则原样保留。 */
+export function stripComments(code) {
+  const out = code.split('');
+  scan(code, (i, c, st) => { if ((st === 'line' || st === 'block') && c !== '\n') out[i] = ' '; });
+  return out.join('');
+}
+
+/** 字符串/模板串**内容**→空格（引号与 ${} 内代码保留）——供调用点扫描防"字符串里的调用样例"。 */
+export function blankStrings(code) {
+  const out = code.split('');
+  scan(code, (i, c, st) => {
+    if ((st === 'str1' || st === 'str2') && c !== "'" && c !== '"' && c !== '\n') out[i] = ' ';
+    else if (st === 'tpl' && c !== '`' && c !== '\n' && !(c === '$' && code[i + 1] === '{') && !(code[i - 1] === '$' && c === '{')) out[i] = ' ';
+  });
+  return out.join('');
+}
+
+/**
+ * 函数体抽取（输入应已 stripComments）。字符串感知的括号平衡；
+ * 跳过控制流关键字与**大写开头名**（ArkUI 内置组件/@Builder 构件在表达式位形似函数定义，
+ * 曾把 Column() {…} 抽成"函数"造成包装器污染——包装器/方法按惯例小写开头）。
+ */
+export function* functionBodies(code) {
+  const blanked = blankStrings(code);
+  const re = /(?:static\s+|private\s+|public\s+|export\s+|async\s+)*(?:function\s+)?([A-Za-z_$][\w$]*)\s*\(/g;
+  let m;
+  while ((m = re.exec(blanked)) !== null) {
+    if (['if', 'for', 'while', 'switch', 'catch', 'constructor', 'return'].includes(m[1])) continue;
+    if (/^[A-Z]/.test(m[1])) continue;
+    let depth = 1, i = re.lastIndex;
+    while (i < blanked.length && depth > 0) { if (blanked[i] === '(') depth++; else if (blanked[i] === ')') depth--; i++; }
+    const paramsRaw = code.slice(re.lastIndex, i - 1);
+    const after = blanked.slice(i);
+    const bm = after.match(/^\s*(?::\s*[^{;=]*?)?\{/);
+    if (!bm) continue;
+    const bodyStart = i + bm[0].length;
+    let d = 1, j = bodyStart;
+    while (j < blanked.length && d > 0) { if (blanked[j] === '{') d++; else if (blanked[j] === '}') d--; j++; }
+    const params = [];
+    let pd = 0, cur = '';
+    for (const c of paramsRaw + ',') {
+      if ('({[<'.includes(c)) pd++;
+      else if (')}]>'.includes(c)) pd--;
+      if (c === ',' && pd === 0) { const nm = cur.trim().split(/[?:]/)[0].trim(); if (/^[A-Za-z_$][\w$]*$/.test(nm)) params.push(nm); cur = ''; }
+      else cur += c;
+    }
+    yield { name: m[1], params, start: bodyStart, end: j, body: code.slice(bodyStart, j) };
+  }
+}
+
+/** 目录遍历：深度上限 + 符号链接目录不进（防环）。 */
+export function walkFiles(dir, { exclude, match, maxDepth = 24 } = {}) {
+  const acc = [];
+  // spec/ 是套件自己的迁移工作区（台账、转译参考件、走查证据），不是工程产物——所有扫描器一律不进
+  const ex = exclude || new Set(['oh_modules', 'node_modules', 'build', '.preview', '.deveco', '.git', 'hvigor', 'spec']);
+  (function go(d, depth) {
+    if (depth > maxDepth) return;
+    let es; try { es = readdirSync(d); } catch { return; }
+    for (const e of es) {
+      if (ex.has(e)) continue;
+      const p = join(d, e);
+      let st; try { st = lstatSync(p); } catch { continue; }
+      if (st.isSymbolicLink()) continue;
+      if (st.isDirectory()) go(p, depth + 1);
+      else if (!match || match(p, e)) acc.push(p);
+    }
+  })(dir, 0);
+  return acc;
+}
+
+// ---- 工具链定位（跨平台）：DevEco Studio 的 hvigorw/ohpm 在 Windows 上默认不进 PATH，按"工程本地包装器 → PATH → DevEco 安装根"顺序找。
+// 返回可直接 spawn 的命令（绝对路径或裸名）；Windows 上 .bat 必须经 shell 起（Node ≥18.20 无 shell 直接 spawn .bat 抛 EINVAL）。
+const DEVECO_ROOTS = () => [
+  process.env.DEVECO_HOME,
+  '/Applications/DevEco-Studio.app/Contents',
+  process.env.PROGRAMFILES && join(process.env.PROGRAMFILES, 'Huawei', 'DevEco Studio'),
+  'C:/Program Files/Huawei/DevEco Studio',
+].filter(Boolean);
+function onPath(name) {
+  const exts = process.platform === 'win32' ? ['.bat', '.cmd', '.exe', ''] : [''];
+  for (const dir of (process.env.PATH || '').split(process.platform === 'win32' ? ';' : ':').filter(Boolean)) {
+    for (const ext of exts) if (existsSync(join(dir, name + ext))) return join(dir, name + ext);
+  }
+  return null;
+}
+/** hvigorw：<工程>/hvigorw(.bat) → PATH → <DevEco>/tools/hvigor/bin/hvigorw(.bat)；找不到返回裸名（spawn 报 ENOENT 由调用方处理） */
+export function resolveHvigorw(projectRoot) {
+  const w = process.platform === 'win32';
+  const local = projectRoot && join(projectRoot, w ? 'hvigorw.bat' : 'hvigorw');
+  if (local && existsSync(local)) return local;
+  const p = onPath('hvigorw'); if (p) return p;
+  for (const r of DEVECO_ROOTS()) { const c = join(r, 'tools', 'hvigor', 'bin', w ? 'hvigorw.bat' : 'hvigorw'); if (existsSync(c)) return c; }
+  return w ? 'hvigorw.bat' : 'hvigorw';
+}
+/** ohpm：PATH → <DevEco>/tools/ohpm/bin/ohpm(.bat) */
+export function resolveOhpm() {
+  const w = process.platform === 'win32';
+  const p = onPath('ohpm'); if (p) return p;
+  for (const r of DEVECO_ROOTS()) { const c = join(r, 'tools', 'ohpm', 'bin', w ? 'ohpm.bat' : 'ohpm'); if (existsSync(c)) return c; }
+  return w ? 'ohpm.bat' : 'ohpm';
+}
+/** spawn 选项：Windows 的 .bat/.cmd 必须 shell:true，且含空格路径要加引号 */
+export function spawnOpts(cmd, extra = {}) {
+  const needShell = process.platform === 'win32' && /\.(bat|cmd)$/i.test(cmd);
+  return { ...extra, shell: needShell || extra.shell === true };
+}
+export const quoteIfSpace = (cmd) => (/\s/.test(cmd) && !/^".*"$/.test(cmd) ? `"${cmd}"` : cmd);

package/skills/migrate-core/scripts/smoke/align-sdk.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+/**
+ * align-sdk.mjs — 设备就绪 + 工程 SDK 版本与设备对齐（2a 建工程后立即跑，别等装机才发现装不上）。
+ *
+ * 设备就绪（原 ensure-device，已并入）：hdc 有 target → 直接过；无 → 探测 Emulator 二进制 → -list 枚举已创建设备 →
+ *   后台 -start（优先 phone 型/--name 指定）→ 轮询 hdc 至 boot 完成。分发环境"拉不起模拟器"的常见因（license 未接受、
+ *   设备未创建、镜像未装）都给精确的一条命令指引，不代做大下载与许可决定。
+ * 版本对齐：build-profile.json5 的 compatibleSdkVersion（API 数字）≤ 设备 const.ohos.apiversion。
+ *   脚本只探测+报因（exit 4 附精确改法），改写 build-profile 归模型（版本串格式需上下文判断）。
+ *   仍无设备时 exit 0 跳过（模板默认值直跑，smoke 前会再检）。
+ *
+ * 用法：align-sdk.mjs --project <鸿蒙工程根> [--name <模拟器名>] [--timeout 180]
+ *       align-sdk.mjs --device-only [--name <模拟器名>] [--timeout 180]     只做设备就绪（smoke 无设备时调用）
+ * 退出码：0 匹配/跳过/设备可用 · 4 版本不匹配（按输出改）· 3 用法错或 --device-only 下无法保障设备
+ */
+import { execSync, spawn } from 'node:child_process';
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { homedir } from 'node:os';
+
+const argv = process.argv.slice(2);
+if (argv.includes('--help')) { 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); }
+const argOf = (n, d) => { const i = argv.indexOf(n); return i >= 0 && argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : d; };
+const PROJECT = argOf('--project', null);
+const DEVICE_ONLY = argv.includes('--device-only');
+if (!PROJECT && !DEVICE_ONLY) { console.error('usage: align-sdk.mjs --project <root> [--name 模拟器名] [--timeout 秒] | --device-only'); process.exit(3); }
+const TIMEOUT = Number(argOf('--timeout', '180')) * 1000;
+const NAME = argOf('--name', null);
+
+// 多设备：hdc 连着多个目标时每条命令都要 -t <connect-key>（否则报 need connect-key）。HMIG_HDC_TARGET 指定，否则取列表首个。
+const hdcTargets = () => { try { return execSync('hdc list targets', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 20000 }).split('\n').map(s => s.trim()).filter(s => s && !/\[Empty\]/i.test(s)); } catch { return []; } };
+const hdcKey = (process.env.HMIG_HDC_TARGET || '').trim() || (() => { const t = hdcTargets(); return t.length > 1 ? t[0] : ''; })();
+const sh = (cmd) => { try { return execSync(hdcKey && /^hdc\s(?!list\s+targets)/.test(cmd) ? cmd.replace(/^hdc\s/, `hdc -t ${hdcKey} `) : cmd, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 30000 }).trim(); } catch { return null; } };
+const hasTarget = () => hdcTargets().length > 0;
+const sleep = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+
+// ---- 设备就绪：返回 true=可用 / false=无法保障（已打印指引） ----
+function ensureDevice() {
+  if (hasTarget()) { console.log('[align-sdk] 设备已在线'); return true; }
+  // 探测 Emulator 二进制（env 覆盖 > macOS 默认 > Windows 常见位）
+  const CANDIDATES = [
+    process.env.DEVECO_EMULATOR,
+    '/Applications/DevEco-Studio.app/Contents/tools/emulator/Emulator',
+    process.env.LOCALAPPDATA && join(process.env.LOCALAPPDATA, 'Huawei', 'DevEco Studio', 'tools', 'emulator', 'Emulator.exe'),
+    'C:/Program Files/Huawei/DevEco Studio/tools/emulator/Emulator.exe',
+  ].filter(Boolean);
+  const EMU = CANDIDATES.find(existsSync);
+  if (!EMU) { console.error('[align-sdk] 未找到 DevEco 模拟器程序（设 DEVECO_EMULATOR 环境变量指向 Emulator 二进制，或连真机并开启 USB 调试授权）'); return false; }
+  // 枚举已创建设备：-list JSON 为主，deployed 目录名兜底
+  let devices = [];
+  const listRaw = sh(`"${EMU}" -list`) || '';
+  try { const arr = JSON.parse(listRaw.slice(listRaw.indexOf('['))); devices = arr.map(d => ({ name: d.name || d.hvdName || d.deviceName || '', type: d.deviceType || '' })).filter(d => d.name); } catch { /* 走目录兜底 */ }
+  if (!devices.length) { const dep = join(homedir(), '.Huawei', 'Emulator', 'deployed'); if (existsSync(dep)) devices = readdirSync(dep).filter(f => f.endsWith('.ini')).map(f => ({ name: f.replace(/\.ini$/, ''), type: /wear/i.test(f) ? 'wearable' : 'phone' })); }
+  if (!devices.length) {
+    console.error(`[align-sdk] 无已创建的模拟器设备。按序执行（首次需网络与许可）：
+  1) "${EMU}" -license accept
+  2) "${EMU}" -imageList -deviceType phone          # 查可用镜像版本
+  3) "${EMU}" -install -deviceType phone -osVersion <版本>
+  4) "${EMU}" -create MigPhone -deviceType phone -osVersion <版本>
+  或打开 DevEco Studio → Device Manager 图形化创建；或连真机开 USB 调试。`);
+    return false;
+  }
+  const pick = NAME ? devices.find(d => d.name === NAME) : (devices.find(d => /phone/i.test(d.type)) || devices.find(d => !/wear|watch|tv|pad|book/i.test(d.name)) || devices[0]);
+  if (!pick) { console.error(`[align-sdk] 指定设备 ${NAME} 不存在；已有：${devices.map(d => d.name).join(', ')}`); return false; }
+  console.log(`[align-sdk] 拉起模拟器：${pick.name}（后台，boot 等待至多 ${TIMEOUT / 1000}s）`);
+  const child = spawn(EMU, ['-start', pick.name], { detached: true, stdio: 'ignore' }); child.unref();
+  const t0 = Date.now();
+  while (Date.now() - t0 <= TIMEOUT) { if (hasTarget()) { console.log(`[align-sdk] 设备就绪（${Math.round((Date.now() - t0) / 1000)}s）`); return true; } sleep(5000); }
+  console.error(`[align-sdk] ${TIMEOUT / 1000}s 内未上线。排查：
+  · 许可未接受 → "${EMU}" -license accept 后重试
+  · macOS 虚拟化授权 → 系统设置-隐私与安全性 里允许 Emulator/qemu；公司管控机可能禁虚拟化
+  · 手工前台起看报错 → "${EMU}" -start "${pick.name}"
+  · 或连真机：开发者模式+USB 调试，hdc list targets 确认`);
+  return false;
+}
+
+const deviceOk = ensureDevice();
+if (DEVICE_ONLY) process.exit(deviceOk ? 0 : 3);
+if (!deviceOk) { console.log('[align-sdk] 无设备，跳过版本对齐（smoke 前会再检）'); process.exit(0); }
+
+// ---- 版本对齐 ----
+const devApi = Number((sh('hdc shell param get const.ohos.apiversion') || '').trim()) || null;
+const devVer = (sh('hdc shell param get const.product.software.version') || '').trim();
+const bp = resolve(PROJECT, 'build-profile.json5');
+if (!existsSync(bp)) { console.error(`[align-sdk] 缺 ${bp}`); process.exit(3); }
+const text = readFileSync(bp, 'utf8');
+// json5 键可不带引号、值可用单引号（实证 bikepacking 工程 compatible 读成 null 被跳过）
+const pick = (key) => { const m = text.match(new RegExp(`["']?${key}["']?\\s*:\\s*["']?(?:[\\d.]+\\((\\d+)\\)|(\\d+))["']?`)); return m ? Number(m[1] || m[2]) : null; };
+const compat = pick('compatibleSdkVersion');
+const compile = pick('compileSdkVersion');
+
+if (!devApi || !compat) { console.log(`[align-sdk] 信息不全（设备 API=${devApi} 工程 compatible=${compat}），跳过`); process.exit(0); }
+if (compat <= devApi) {
+  console.log(`[align-sdk] ✓ 版本对齐：设备 API ${devApi}（${devVer}）≥ 工程 compatible ${compat}${compile ? `（compile ${compile}）` : ''}`);
+  process.exit(0);
+}
+// 版本串必须查 hvigor 官方映射（osVersionMapper），禁按设备软件版本号猜——
+// 实证：设备 6.0.0.130 猜成 "6.0.0(22)" 被 hvigor 拒（6.0.0 对应 API 20，22 的版本名是 6.0.2）
+function apiToVersionName(api) {
+  const cands = [
+    process.env.DEVECO_HOME && join(process.env.DEVECO_HOME, 'tools/hvigor/hvigor-ohos-plugin/node_modules/@ohos/hos-sdkmanager-common/build/res/hos-config.json'),
+    '/Applications/DevEco-Studio.app/Contents/tools/hvigor/hvigor-ohos-plugin/node_modules/@ohos/hos-sdkmanager-common/build/res/hos-config.json',
+    process.env.LOCALAPPDATA && join(process.env.LOCALAPPDATA, 'Huawei/DevEco Studio/tools/hvigor/hvigor-ohos-plugin/node_modules/@ohos/hos-sdkmanager-common/build/res/hos-config.json'),
+  ].filter(Boolean);
+  for (const c of cands) {
+    try {
+      const mapper = JSON.parse(readFileSync(c, 'utf8')).osVersionMapper || {};
+      for (const [ver, a] of Object.entries(mapper)) if (Number(a) === api) return ver;
+    } catch { /* 下一个候选 */ }
+  }
+  return null;
+}
+const verName = apiToVersionName(devApi);
+const exact = verName ? `"${verName}(${devApi})"` : `（映射表未找到——从 hvigor 报错的 osVersionMapper 提示中取 API ${devApi} 对应版本名，禁按设备软件版本号猜）`;
+console.error(`[align-sdk] ✗ 工程 compatibleSdkVersion ${compat} > 设备 API ${devApi}（${devVer}）——上机必失败。二选一：
+  · 改 ${PROJECT}/build-profile.json5 的 compatibleSdkVersion${compile && compile > devApi ? ' 与 compileSdkVersion' : ''} 为 ${exact}，改后重构建
+  · 或换高版本镜像：Emulator -imageList -deviceType phone 查版本 → -install/-create 后重试`);
+process.exit(4);

package/skills/migrate-core/scripts/smoke/ensure-sign.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/**
+ * ensure-sign.mjs — 签名保障（幂等三级级联，登录自动化）。
+ *
+ * 级联：① signingConfigs 已配 → 跳过
+ *      ② 官签 devecocli signature generate（真机+verify_ui 全通）——需登录时**自动拉起浏览器登录**
+ *        （auth login 自带浏览器+本地回调，用户点完命令自动返回继续；HMIG_NO_LOGIN=1 禁用，
+ *         纯无人值守场景不弹）→ 登录成功重试官签
+ *      ③ 失败 exit 4 → unsigned+模拟器+hdc uitest 降级链（模拟器面 unsigned 本就全通），提示置顶进最终报告
+ *      （零登录自签工具在套件仓 devtools/oh-selfsign.mjs，特殊场景备件，不进默认级联）
+ *
+ * 用法：ensure-sign.mjs --project <鸿蒙工程根>
+ * 退出码：0 已签/生成成功（stdout 注明档位）· 4 全部失败（unsigned 降级）· 3 用法错
+ */
+import { execSync } from 'node:child_process';
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const argv = process.argv.slice(2);
+const argOf = (n, d) => { const i = argv.indexOf(n); return i >= 0 && argv[i + 1] ? argv[i + 1] : d; };
+const PROJECT = argOf('--project', null);
+if (!PROJECT) { console.error('usage: ensure-sign.mjs --project <root>'); process.exit(3); }
+
+const bp = resolve(PROJECT, 'build-profile.json5');
+if (!existsSync(bp)) { console.error(`[ensure-sign] 缺 ${bp}`); process.exit(3); }
+// JSON5 键名可不带引号：devecocli signature generate 实际写成 `signingConfigs: [{`（回归实证），只认带引号会把官签成功误报成失败
+const hasConfig = () => /["']?signingConfigs["']?\s*:\s*\[\s*\{/.test(readFileSync(bp, 'utf8'));
+if (hasConfig()) { console.log('[ensure-sign] ✓ signingConfigs 已配置（官签态），跳过'); process.exit(0); }
+
+const sh = (cmd, timeout) => {
+  try { return { ok: true, out: execSync(cmd, { cwd: resolve(PROJECT), encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout }) }; }
+  catch (e) { return { ok: false, out: String((e.stdout || '') + (e.stderr || '') + (e.message || '')) }; }
+};
+
+// ② 官签
+let r = sh('devecocli signature generate', 180000);
+if (hasConfig()) { console.log('[ensure-sign] ✓ 官签材料已生成（真机+verify_ui 可用）'); process.exit(0); }
+
+// 需登录 → 自动拉浏览器（auth login 自带浏览器+本地回调等待；限时 180s，无人点自动放弃）
+if (/auth login|sign in|登录/i.test(r.out) && process.env.HMIG_NO_LOGIN !== '1') {
+  console.log('[ensure-sign] 官签需登录——自动打开浏览器（180s 内完成登录即自动继续；HMIG_NO_LOGIN=1 可禁）');
+  const login = sh('devecocli auth login', 180000);
+  if (login.ok) {
+    r = sh('devecocli signature generate', 180000);
+    if (hasConfig()) { console.log('[ensure-sign] ✓ 登录成功，官签材料已生成（真机+verify_ui 可用）'); process.exit(0); }
+  } else {
+    console.log('[ensure-sign] 登录未完成（超时/取消），走 unsigned 降级链');
+  }
+}
+
+console.error(`[ensure-sign] ✗ 官签未成（${r.out.trim().slice(-160)}）
+  本轮走 unsigned+模拟器+hdc uitest 降级链（模拟器面全通）；如需 verify_ui/真机请 devecocli auth login 后重跑。此提示须置顶写入最终报告。`);
+process.exit(4);