deveco_hmigbot 0.21.5

package/skills/migrate-core/scripts/front.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+/**
+ * front.mjs — 2a 静态前场一条命令（确定性环节首尾相接，根会话一次调用、只处置报出来的问题）。
+ *
+ * 顺序（与研发面干跑基准同一条代码路径——基准验证的就是这里执行的）：
+ *   ⓪ --feasibility 时先跑 feasibility --gate（红=exit 5 停下让你定改道/尽力而为；黄=记录继续，逐项处置归 2b）
+ *   ① setup-arkts-test（hypium 脚手架）② convert-resources ③ wire-routes（--src 三轨合并）+ main_pages 并入
+ *   ④ transpile-layout（参考件，落 spec/front/layouts，不进编译树——实证 45 工程 244/244 份骨架从未被页面 import，进工程只产死代码与悬空立案）
+ *   ⑤ align-sdk（设备就绪 + API 对齐）⑥ ensure-sign ⑦ hvigorw assembleHap
+ *   ⑧ closure-suite --stage slice（转译布局的资源悬空在前场清零）⑨ smoke（首屏冒烟）
+ * 每步退出码+摘要进 <spec>/front/front-report.json；某步失败不掩盖后续（构建红则跳过冒烟）。
+ * 单个脚本保持可独立重跑（定向修完只重跑该步），本脚本不改任何一步的判定逻辑，各步退出码原样入报告。
+ * 阶段一不必再单独跑 align-sdk / ensure-sign（实证一轮里被跑了两遍）：建好骨架工程后直接跑本命令。
+ *
+ * 用法：node front.mjs --src <安卓根> --dst <鸿蒙工程根> [--feasibility] [--spec <dst>/spec] [--extra-res a,b] [--no-sign] [--no-smoke] [--json out]
+ * 退出码：0 全绿（冒烟 scaffold 属预期）/ 5 可行性红（未进后续步）/ 10 构建红或闭合硬违规 / 2 冒烟立案（崩溃除外）/ 3 环境阻塞 / 1 某步脚本异常
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync } from 'node:fs';
+import { resolveHvigorw, quoteIfSpace } from './lib/scan.mjs';
+import { join, resolve, dirname } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+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 SRC = argOf('--src', null), DST = argOf('--dst', null);
+if (!SRC || !DST) { console.error('usage: front.mjs --src <android root> --dst <harmony root> [--feasibility] [--spec dir] [--extra-res a,b] [--no-sign] [--no-smoke] [--json out]'); process.exit(3); }
+const SPEC = argOf('--spec', join(DST, 'spec'));
+const EXTRA = argOf('--extra-res', null);
+const NO_SIGN = argv.includes('--no-sign'), NO_SMOKE = argv.includes('--no-smoke'), FEAS = argv.includes('--feasibility');
+const JSON_OUT = argOf('--json', join(SPEC, 'front', 'front-report.json'));
+mkdirSync(join(SPEC, 'front'), { recursive: true });
+mkdirSync(join(SPEC, 'smoke'), { recursive: true });
+
+// 入口模块目录从 build-profile 派生（modules[].srcPath 中 module.json5 type=entry），不写死 entry
+function entryModule() {
+  try {
+    const bp = readFileSync(join(DST, 'build-profile.json5'), 'utf8').replace(/\/\/.*$/gm, '');
+    for (const m of bp.matchAll(/["']?srcPath["']?\s*:\s*["']([^"']+)["']/g)) {
+      const mj = join(DST, m[1], 'src', 'main', 'module.json5');
+      if (existsSync(mj) && /["']?type["']?\s*:\s*["']entry["']/.test(readFileSync(mj, 'utf8'))) return m[1].replace(/^\.\//, '');
+    }
+  } catch { /* 回退默认 */ }
+  return 'entry';
+}
+const MOD = entryModule();
+const ETS = join(DST, MOD, 'src', 'main', 'ets');
+const strip = (s) => String(s || '').replace(/\x1b\[[0-9;]*m/g, '');
+const tail = (s, n = 3) => strip(s).trim().split('\n').filter(Boolean).slice(-n).join(' | ').slice(0, 300);
+
+const steps = [];
+function run(name, cmd, args, opts = {}) {
+  const t0 = Date.now();
+  const r = spawnSync(cmd, args, { encoding: 'utf8', timeout: opts.timeout || 600000, cwd: opts.cwd, shell: opts.shell || false, env: process.env });
+  const out = (r.stdout || '') + (r.stderr || '');
+  // status===null 有两种：超时被杀，或根本没起来（ENOENT：hvigorw/node 不在 PATH）——后者按 timeout 报会把环境问题写成"构建超时"
+  const st = { name, exit: r.status === null ? (r.error && r.error.code ? `spawn:${r.error.code}` : 'timeout') : r.status, seconds: Math.round((Date.now() - t0) / 1000), tail: tail(out) || (r.error ? String(r.error.message || r.error) : ''), ...(opts.keep ? { lines: strip(out).trim().split('\n').filter(l => opts.keep.test(l)).slice(0, 40) } : {}) };
+  steps.push(st);
+  console.log(`[front] ${st.exit === 0 ? '✓' : '▲'} ${name} exit=${st.exit} ${st.seconds}s${st.exit !== 0 ? ' — ' + st.tail : ''}`);
+  return st;
+}
+const node = (script, args, opts) => run(script.split('/').pop().replace('.mjs', ''), process.execPath, [join(HERE, script), ...args], opts);
+
+// ⓪ 可行性：红（exit 5）就停——改道还是尽力而为是人的决定，不在这里替人做；黄（4）记录继续，逐项处置归 2b
+let feas = null;
+if (FEAS) {
+  mkdirSync(SPEC, { recursive: true });
+  feas = node('feasibility/feasibility.mjs', ['--src', SRC, '--json', join(SPEC, 'feasibility.json'), '--gate'], { timeout: 300000, keep: /^\s*(🟢|🟡|🔴|\?)/ });
+  if (feas.exit === 5) {
+    const report = { src: SRC, dst: DST, exit: 5, steps, next: '可行性红：先定改道或尽力而为（见 spec/feasibility.json），再不带 --feasibility 重跑本命令继续前场' };
+    mkdirSync(dirname(resolve(JSON_OUT)), { recursive: true }); writeFileSync(resolve(JSON_OUT), JSON.stringify(report, null, 2));
+    console.log(`[front] exit=5 · ${report.next}`); process.exit(5);
+  }
+}
+node('vectors/setup-arkts-test.mjs', ['--project', DST]);
+node('convert/convert-resources.mjs', ['--src', SRC, '--dst', DST, '--out', join(SPEC, 'front'), ...(EXTRA ? ['--extra-res', EXTRA] : [])]);
+const wr = node('wire/wire-routes.mjs', ['--src', SRC, '--out', ETS, '--json', join(SPEC, 'front', 'wiring-report.json')]);
+try {
+  const gen = join(ETS, 'main_pages.json.generated');
+  if (existsSync(gen)) { const dst = join(DST, MOD, 'src', 'main', 'resources', 'base', 'profile', 'main_pages.json'); mkdirSync(dirname(dst), { recursive: true }); copyFileSync(gen, dst); }
+} catch (e) { steps.push({ name: 'main_pages', exit: 1, tail: String(e.message) }); }
+node('transpile/transpile-layout.mjs', ['--src', SRC, '--out', join(SPEC, 'front', 'layouts'), '--json', join(SPEC, 'front', 'transpile-report.json'), ...(EXTRA ? ['--extra-res', EXTRA] : [])]);
+node('smoke/align-sdk.mjs', ['--project', DST], { timeout: 300000 });
+if (!NO_SIGN) node('smoke/ensure-sign.mjs', ['--project', DST], { timeout: 400000 });
+const HVIGORW = resolveHvigorw(DST);   // 工程本地 → PATH → DevEco 安装根；报告里记下解析结果，后续 args 的 build/selfTest 照抄这个命令
+const build = run('build', quoteIfSpace(HVIGORW), ['assembleHap', '--no-daemon'], { cwd: DST, shell: process.platform === 'win32', timeout: 900000, keep: /Error Message|ERROR:/ });
+const closure = node('closure/closure-suite.mjs', ['--project', DST, '--stage', 'slice', '--json', join(SPEC, 'front', 'closure-slice.json')], { keep: /^\s*✗/ });
+let smoke = null;
+if (!NO_SMOKE && build.exit === 0) smoke = node('smoke/smoke.mjs', ['--project', DST, '--out', join(SPEC, 'smoke'), '--json', join(SPEC, 'smoke', 'smoke-2a.json')], { timeout: 600000, keep: /^\s*[✓▲✗]|\[smoke\]/ });
+
+// 汇总：构建/闭合是硬门；冒烟 3=环境阻塞（如实记）、10=崩溃、2=立案；其余步骤非 0 记异常
+let exit = 0;
+const scriptFail = steps.filter(s => !['build', 'closure-suite', 'smoke', 'align-sdk', 'ensure-sign', 'feasibility'].includes(s.name) && s.exit !== 0);
+if (build.exit !== 0 || closure.exit === 10) exit = 10;
+else if (smoke && smoke.exit === 10) exit = 10;
+else if (smoke && smoke.exit === 3) exit = 3;
+else if (smoke && smoke.exit === 2) exit = 2;
+else if (scriptFail.length) exit = 1;
+let wiring = null; try { const w = JSON.parse(readFileSync(join(SPEC, 'front', 'wiring-report.json'), 'utf8')); wiring = { routes: w.routes.length, launcher: w.launcher, sources: w.sources }; } catch { /* wire 失败已在 steps */ }
+const report = { src: SRC, dst: DST, module: MOD, exit, feasibility: feas ? feas.exit : null, wiring, steps, toolchain: { hvigorw: HVIGORW, buildCmd: `${quoteIfSpace(HVIGORW)} assembleHap --no-daemon` },
+  next: exit === 0 ? '前场绿：进 2b' : exit === 10 ? '先修构建红/闭合硬违规（转译布局悬空资源：补 --extra-res 或改 TODO(res)），只重跑涉事步骤' : exit === 3 ? '冒烟环境阻塞（设备/装机/hap）：报告如实记"未冒烟"，不当通过' : exit === 2 ? '冒烟立案：按 smoke 报告处置（崩溃/着陆错当场修）' : '某步脚本异常退出，见 steps.tail' };
+mkdirSync(dirname(resolve(JSON_OUT)), { recursive: true });
+writeFileSync(resolve(JSON_OUT), JSON.stringify(report, null, 2));
+console.log(`[front] exit=${exit} · 路由 ${wiring ? wiring.routes + ' 首页 ' + wiring.launcher : '?'} · ${report.next} · 报告 ${JSON_OUT}`);
+process.exit(exit);

package/skills/migrate-core/scripts/interface/ark-extract.mjs

@@ -0,0 +1,172 @@
+/**
+ * ark-extract.mjs — ArkAnalyzer 抽取适配器（接口派生的 AST 级增强，正则的兜底超集）。
+ *
+ * 契约靠派生：正则抽取有盲区（export async function / export type{}from / export * / 字符串内假符号），
+ * ArkAnalyzer 建 SceneGraph 后拿真实导出/种类/跨文件 import 解析。本适配器只做一件事：
+ *   extractSymbols(project, dirs) → { symbols:{name:{kind,file}}, fileCount, engine } 或 null（不可用/出错）。
+ * 由 interface.mjs 与正则基线**并集**（正则恒跑保底，Ark 成功则并入其超集），故对 ArkAnalyzer 版本漂移免疫。
+ *
+ * 解析顺序（免装优先）：环境变量 HMIGBOT_ARKANALYZER → DevEco Studio 自带 → 套件本地 → 工程本地 → 裸 require。
+ * 找不到或任一 API 抛错 → 返回 null → 上游纯回退正则。全程不污染 stdout（log4js 噪音静音）。
+ */
+import { createRequire } from 'node:module';
+import { resolve, relative, join } from 'node:path';
+import { existsSync, realpathSync, readdirSync, readFileSync } from 'node:fs';
+
+const require = createRequire(import.meta.url);
+const HERE = (await import('node:path')).dirname((await import('node:url')).fileURLToPath(import.meta.url));
+
+// 枚举整数→名（不在顶层 export，按 .d.ts 定值硬编码；集中此处，版本升级只改这里）
+// 3='local'（ArkAnalyzer 对 export const/let 的分类）统一回 'const'，与正则词表一致（class/interface/enum/const/function/struct/type/namespace）
+const EXPORT_TYPE = { 0: 'namespace', 1: 'class', 2: 'function', 3: 'const', 4: 'type', 9: 'unknown' };
+const CLASS_CATEGORY = { 0: 'class', 1: 'struct', 2: 'interface', 3: 'enum', 4: 'type', 5: 'object', 6: 'union' };
+const NAME_RE = /^[A-Za-z_$][\w$]*$/;
+
+// 解析 arkanalyzer 包目录：DevEco 内置优先（用户偏好，免装）→ 环境覆盖 → 套件本地。命中路径缓存。
+let _arkDir; // undefined=未探测 / null=确认无 / string=命中路径
+function arkPackageDir() {
+  if (_arkDir !== undefined) return _arkDir;
+  if (process.env.HMIGBOT_NO_ARKANALYZER) { _arkDir = null; return null; } // 显式关闭：强制纯正则
+  const cands = [
+    process.env.HMIGBOT_ARKANALYZER,          // 显式覆盖（最高优先）
+    ...devecoStudioArkDirs(),                  // DevEco Studio 内置（免装，首选）
+    join(HERE, '..', '..', 'node_modules', 'arkanalyzer'), // 套件本地（仅当显式装过）
+  ].filter(Boolean);
+  for (const c of cands) { try { if (existsSync(join(c, 'package.json'))) { _arkDir = c; return c; } } catch { /* next */ } }
+  _arkDir = null; return null;
+}
+
+// DevEco Studio 安装根候选（跨平台：mac/win/linux；DEVECO_STUDIO_HOME 覆盖最高优先）
+function devecoStudioBases() {
+  const bases = [];
+  if (process.env.DEVECO_STUDIO_HOME) bases.push(process.env.DEVECO_STUDIO_HOME);
+  const HOME = process.env.HOME || process.env.USERPROFILE;
+  if (process.platform === 'darwin') {
+    bases.push('/Applications/DevEco-Studio.app');
+    if (HOME) bases.push(join(HOME, 'Applications', 'DevEco-Studio.app'));
+  } else if (process.platform === 'win32') {
+    for (const pf of [process.env.ProgramFiles, process.env['ProgramFiles(x86)'], process.env.LOCALAPPDATA]) {
+      if (pf) bases.push(join(pf, 'Huawei', 'DevEco Studio'));
+    }
+  } else { // linux 及其他
+    bases.push('/opt/deveco-studio', '/usr/local/deveco-studio');
+    if (HOME) bases.push(join(HOME, 'deveco-studio'));
+  }
+  return bases;
+}
+
+// DevEco Studio 内置 arkanalyzer（跨平台 + 跨版本鲁棒）：已知子路径命中即用，失效则在 codelinter 插件下定深兜底搜。
+// mac 插件在 Contents/ 下，win/linux 直接在安装根下——两种前缀都试。
+function devecoStudioArkDirs() {
+  const SUB = ['plugins', 'codelinter', 'arkPerfCheck', 'node_modules', 'arkanalyzer'];
+  const out = [];
+  for (const b of devecoStudioBases()) {
+    for (const mid of [[], ['Contents']]) {
+      const known = join(b, ...mid, ...SUB);
+      if (existsSync(known)) { out.push(known); continue; }
+      try { out.push(...shallowFindArk(join(b, ...mid, 'plugins', 'codelinter'), 4)); } catch { /* ignore */ }
+    }
+  }
+  return out;
+}
+
+function shallowFindArk(dir, depth) {
+  const hits = [];
+  if (depth < 0 || !existsSync(dir)) return hits;
+  let entries = [];
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return hits; }
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    if (e.name === 'arkanalyzer') hits.push(join(dir, e.name));
+    else if (depth > 0) hits.push(...shallowFindArk(join(dir, e.name), depth - 1));
+  }
+  return hits;
+}
+
+/** require arkanalyzer 模块（DevEco 内置优先），找不到/加载失败返回 null。 */
+export function loadArkAnalyzer() {
+  const dir = arkPackageDir();
+  if (!dir) return null;
+  try { return require(dir); } catch { return null; }
+}
+
+/** 命中的 arkanalyzer 版本（用于 manifest 记账），取不到返回 undefined。 */
+export function arkVersion() {
+  const dir = arkPackageDir();
+  if (!dir) return undefined;
+  try { return JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).version; } catch { return undefined; }
+}
+
+function refineKind(e) {
+  try {
+    const ax = e.getArkExport?.();
+    if (ax && typeof ax.getCategory === 'function') { const c = ax.getCategory(); if (CLASS_CATEGORY[c]) return CLASS_CATEGORY[c]; }
+    if (ax && ax.constructor?.name === 'ArkMethod') return 'function';
+    if (ax && ax.constructor?.name === 'ArkNamespace') return 'namespace';
+  } catch { /* ignore */ }
+  const t = e.getExportClauseType?.();
+  return EXPORT_TYPE[t] ?? 'unknown';
+}
+
+/**
+ * 用 ArkAnalyzer 提取 project 下、位于 dirs 任一目录内的文件的导出符号。
+ * @returns {{symbols:Object, fileCount:number, engine:string, arkVersion?:string}|null}
+ */
+export function extractSymbols(project, dirs) {
+  const ark = loadArkAnalyzer();
+  if (!ark) return null;
+  const { SceneConfig, Scene } = ark;
+  if (typeof SceneConfig !== 'function' || typeof Scene !== 'function') return null;
+
+  // log4js 噪音静音：建图期屏蔽 console.log/info（业务无输出走这里）
+  const savedLog = console.log, savedInfo = console.info;
+  console.log = () => {}; console.info = () => {};
+  try {
+    // realpath 归一：ArkAnalyzer 返回真实路径，projRoot 若在符号链接下（如 macOS /tmp→/private/var）
+    // 会让 relative() 算出 ../.. 前缀导致 inScope 全落空、静默回退。两端归一即修。
+    let projRoot;
+    try { projRoot = realpathSync(resolve(project)); } catch { projRoot = resolve(project); }
+    const config = new SceneConfig();
+    config.buildFromProjectDir(projRoot);
+    const scene = new Scene();
+    scene.buildSceneFromProjectDir(config);
+    try { scene.inferTypes(); } catch { /* SDK 缺失可忽略，仅影响 @ 依赖类型 */ }
+
+    const files = scene.getFiles?.() || [];
+    if (!files.length) return null; // 建图空 = 视为不可用，回退正则
+
+    const dirPrefixes = (dirs || []).map(d => d.replace(/^\.\//, '').replace(/\\/g, '/').replace(/\/$/, ''));
+    const inScope = (relPath) => dirPrefixes.length === 0 || dirPrefixes.some(d => relPath === d || relPath.startsWith(d + '/'));
+
+    const symbols = {};
+    let fileCount = 0;
+    for (const f of files) {
+      let fp;
+      try {
+        let abs = f.getFilePath();
+        try { abs = realpathSync(abs); } catch { /* 用原路径 */ }
+        fp = relative(projRoot, abs).replace(/\\/g, '/');
+      } catch { continue; }
+      if (!inScope(fp)) continue;
+      fileCount++;
+      let exps = [];
+      try { exps = f.getExportInfos?.() || []; } catch { exps = []; }
+      for (const e of exps) {
+        let name;
+        try { name = e.getExportClauseName?.() ?? e.getOriginName?.(); } catch { name = null; }
+        if (!name) continue;
+        if (name === 'default' || name === '%dflt') {
+          try { const bn = e.getArkExport?.()?.getName?.(); if (bn && bn !== '%dflt') name = bn; } catch { /* ignore */ }
+        }
+        if (!NAME_RE.test(name)) continue; // 防御脏名
+        if (!symbols[name]) symbols[name] = { kind: refineKind(e), file: fp };
+      }
+    }
+    if (Object.keys(symbols).length === 0) return null; // 一个都没提到 = 视为失败，回退
+    return { symbols, fileCount, engine: 'arkanalyzer', arkVersion: arkVersion() };
+  } catch {
+    return null; // 任一步抛错 → 回退正则
+  } finally {
+    console.log = savedLog; console.info = savedInfo;
+  }
+}

package/skills/migrate-core/scripts/interface/interface.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+/**
+ * interface.mjs — 跨切片接口的"派生 + 一致性检查"（契约靠派生不靠预测，见
+ * docs/design-2026-09-06-derived-contract.md）。
+ *
+ * 病根：Android→HarmonyOS 的跨切片接口无法提前准确预测，模型预测的契约会带错一路向下。
+ * 对策：地基先建，从地基**真实代码**提取导出符号成 interface-manifest.json（派生，不是预测）；
+ *       下游切片只准 import 这份 manifest 里的符号；一致性检查把"契约冲突"从末端 verify
+ *       降到检查点的确定性门（更早、更廉价、可重跑同答案）。
+ *
+ * 子命令：
+ *   extract --project <工程> --dirs <地基目录,逗号分隔> --out spec/interface-manifest.json
+ *           → 遍历地基目录 .ets，提取 export 符号（class/interface/enum/const/function/struct/type）
+ *   check   --project <工程> --manifest spec/interface-manifest.json [--slice <目录>] [--json out]
+ *           → 下游文件对地基模块的 import 必须解析到 manifest 符号；否则 violation（下游假设了
+ *             地基没提供的接口=发散）。退出码 0 通过 / 10 有违规 / 3 用法错。
+ *
+ * 契约演进：地基接口要改时 extract 重跑（manifest 版本自然更新），受影响下游由台账 debts
+ * 定向复验——受控传播，不是冻死。
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join, dirname, resolve, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { stripComments, walkFiles } from '../lib/scan.mjs';
+import { extractSymbols as arkExtractSymbols } from './ark-extract.mjs';
+
+const argv = process.argv.slice(2);
+const CMDS = ['extract', 'check'];
+const cmd = argv.find(a => CMDS.includes(a));
+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 (!cmd || !PROJECT) { console.error('usage: interface.mjs <extract|check> --project <root> ...'); process.exit(3); }
+const rel = f => relative(resolve(PROJECT), f).replace(/\\/g, '/');
+
+// 导出声明：export [default] (class|interface|enum|const|function|struct|type|namespace) Name
+// 含 @Component 前缀的 struct（export @Component struct X 不合法，ArkTS 是 export struct X）。
+const EXPORT_RE = /\bexport\s+(?:default\s+)?(?:declare\s+)?(?:abstract\s+)?(?:async\s+)?(class|interface|enum|const|let|var|function|struct|type|namespace)\s+([A-Za-z_$][\w$]*)/g;   // async function（语料 45 工程 108 处）/var 也认
+// 具名再导出：export { A, B as C } from '...'
+const REEXPORT_RE = /\bexport\s*\{([^}]+)\}/g;
+
+function extractExports(code) {
+  const out = [];
+  for (const m of code.matchAll(EXPORT_RE)) out.push({ name: m[2], kind: m[1] === 'let' ? 'const' : m[1] });
+  for (const m of code.matchAll(REEXPORT_RE)) {
+    for (const part of m[1].split(',')) {
+      const nm = part.trim().split(/\s+as\s+/).pop().trim();
+      if (/^[A-Za-z_$][\w$]*$/.test(nm)) out.push({ name: nm, kind: 'reexport' });
+    }
+  }
+  return out;
+}
+
+if (cmd === 'extract') {
+  const dirs = (argOf('--dirs', '') || '').split(',').map(s => s.trim()).filter(Boolean);
+  if (!dirs.length) { console.error('extract 需 --dirs <地基目录,..>'); process.exit(3); }
+  const symbols = {};
+  let fileCount = 0;
+  // ① 正则基线（零依赖保底，恒跑）——即便 ArkAnalyzer 缺失/版本不符也保证不劣于旧版
+  for (const d of dirs) {
+    const root = resolve(PROJECT, d);
+    for (const f of walkFiles(root, { match: (_p, e) => e.endsWith('.ets') || e.endsWith('.ts') })) {
+      fileCount++;
+      const code = stripComments(readFileSync(f, 'utf8'));
+      for (const s of extractExports(code)) {
+        if (!symbols[s.name]) symbols[s.name] = { kind: s.kind, file: rel(f) };
+      }
+    }
+  }
+  // ② ArkAnalyzer 超集增强（AST 级，可用则并入）：补正则盲区（export async function /
+  //    export type{}from / export * / 字符串内假符号误报），并给精确种类。名覆盖是并集，故恒 ≥ 正则。
+  let engine = 'regex', arkAdded = 0, arkVer;
+  try {
+    const ark = arkExtractSymbols(PROJECT, dirs);
+    if (ark && ark.symbols && Object.keys(ark.symbols).length) {
+      engine = 'arkanalyzer+regex';
+      arkVer = ark.arkVersion;
+      for (const [name, info] of Object.entries(ark.symbols)) {
+        if (!symbols[name]) arkAdded++;
+        symbols[name] = info; // Ark 优先（种类更准）；正则独有的名保留 → 并集
+      }
+    }
+  } catch { /* 保持正则基线，静默回退 */ }
+  const manifest = { version: '0.1.0', engine, ...(arkVer ? { arkVersion: arkVer } : {}), sources: dirs, fileCount, symbolCount: Object.keys(symbols).length, symbols };
+  const out = argOf('--out', null);
+  if (out) { mkdirSync(dirname(resolve(out)), { recursive: true }); writeFileSync(out, JSON.stringify(manifest, null, 2)); }
+  console.log(`[interface:extract] 地基 ${fileCount} 文件 → 导出符号 ${manifest.symbolCount} 个（引擎 ${engine}${engine !== 'regex' ? `，AST 补 ${arkAdded} 个正则盲区符号` : '，ArkAnalyzer 不可达'}）${out ? ` → ${out}` : ''}`);
+  const bykind = {};
+  for (const s of Object.values(symbols)) bykind[s.kind] = (bykind[s.kind] || 0) + 1;
+  console.log(`  ${Object.entries(bykind).map(([k, n]) => `${k}:${n}`).join(' ')}`);
+} else if (cmd === 'check') {
+  const manifestPath = argOf('--manifest', null);
+  if (!manifestPath) { console.error('check 需 --manifest'); process.exit(3); }
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  const known = new Set(Object.keys(manifest.symbols || {}));
+  // 地基源文件（manifest 里记录的文件）——这些文件自身不算"下游"
+  const foundationFiles = new Set(Object.values(manifest.symbols || {}).map(s => s.file));
+  const foundationDirs = (manifest.sources || []).map(d => d.replace(/\\/g, '/'));
+  const isFoundation = (relPath) => foundationFiles.has(relPath) || foundationDirs.some(d => relPath.startsWith(d.replace(/^\.\//, '')));
+
+  const sliceDir = argOf('--slice', null);
+  const scanRoot = sliceDir ? resolve(PROJECT, sliceDir) : resolve(PROJECT);
+  const findings = [];
+  let importsChecked = 0;
+  // 目标文件真实导出（按需提取，缓存）：manifest 是派生时刻的快照，切片后来在地基目录里新建的文件、
+  // 地基新增的导出都不在里面——这不是下游漂移，是 manifest 过期，两者要分开判。
+  const exportCache = new Map();
+  const realExportsOf = (target) => {
+    const file = [target + '.ets', target + '.ts', join(target, 'index.ets')].find(p => existsSync(p));
+    if (!file) return null;
+    if (!exportCache.has(file)) exportCache.set(file, { file, names: new Set(extractExports(stripComments(readFileSync(file, 'utf8'))).map(s => s.name)) });
+    return exportCache.get(file);
+  };
+  const staleFiles = new Set();
+  for (const f of walkFiles(scanRoot, { match: (_p, e) => e.endsWith('.ets') })) {
+    const relf = rel(f);
+    if (isFoundation(relf)) continue; // 地基自身不查
+    const code = stripComments(readFileSync(f, 'utf8'));
+    for (const m of code.matchAll(/import\s*\{([^}]+)\}\s*from\s*['"](\.[^'"]+)['"]/g)) {
+      // 只查指向地基模块的 import：解析路径落在地基目录/文件内
+      const target = resolve(dirname(f), m[2]);
+      const targetRel = rel(target) + '.ets';
+      const pointsToFoundation = foundationDirs.some(d => rel(target).startsWith(d.replace(/^\.\//, ''))) || foundationFiles.has(targetRel);
+      if (!pointsToFoundation) continue;
+      for (const raw of m[1].split(',')) {
+        const nm = raw.trim().split(/\s+as\s+/)[0].trim();
+        if (!/^[A-Za-z_$][\w$]*$/.test(nm)) continue;
+        importsChecked++;
+        if (known.has(nm)) continue;
+        // manifest 没有：核对目标文件——真实导出 → manifest 过期（立案，按文件一次）；不存在/未导出 → 真漂移（违规）
+        const real = realExportsOf(target);
+        if (real && real.names.has(nm)) { staleFiles.add(rel(real.file)); continue; }
+        findings.push({ severity: 'violation', type: 'interface_drift', name: nm, evidence: `${relf}: import { ${nm} } from '${m[2]}' —— 地基未导出该符号（下游假设了不存在的接口；地基改了就 extract 重派生，或修下游对齐）` });
+      }
+    }
+  }
+  for (const sf of staleFiles) {
+    findings.push({ severity: 'case', type: 'manifest_stale', name: sf,
+      basis: '判据：下游 import 的符号确在该文件真实导出，只是不在 manifest 快照里（地基增长或切片在地基目录内新建文件）——不是下游漂移',
+      evidence: `${sf} 的导出不在 manifest 里——重跑 interface.mjs extract 重派生即可；下游 import 与真实导出一致，不判漂移` });
+  }
+  const report = { project: relative(process.cwd(), resolve(PROJECT)) || '.', manifestSymbols: known.size, importsChecked, findings };
+  const outJson = argOf('--json', null);
+  if (outJson) writeFileSync(outJson, JSON.stringify(report, null, 2));
+  const vio = findings.filter(f => f.severity === 'violation');
+  const cas = findings.filter(f => f.severity === 'case');
+  console.log(`[interface:check] 地基符号 ${known.size} · 下游对地基 import ${importsChecked} 处 · 漂移 ${vio.length}${cas.length ? ` · manifest 过期文件 ${cas.length}（立案）` : ''}`);
+  for (const v of vio.slice(0, 15)) console.log(`  ✗ ${v.evidence}`);
+  if (vio.length > 15) console.log(`  …共 ${vio.length} 条`);
+  for (const c of cas.slice(0, 8)) console.log(`  ▲ CASE ${c.type} — ${c.evidence}`);
+  if (!vio.length) console.log('  ✓ 下游全部对齐地基派生接口（零漂移）');
+  process.exit(vio.length ? 10 : 0);
+}