@ohos-cpf/3rdloop 0.0.11 → 0.0.13

package/vendor/Server/Skills/flutter-build-test/scripts/build-matrix.cjs

@@ -0,0 +1,374 @@
+#!/usr/bin/env node
+/**
+ * build-matrix.cjs — flvm 多版本编译矩阵：切换 Flutter 版本并逐版本编译验证 ohos hap
+ *
+ * 每版本执行序列:
+ *   1. flvm use <分支> （未安装自动安装，失败回退模糊匹配 flvm use <主.次>）
+ *   2. flutter --version 校验主.次版本一致
+ *   3. example 目录: flutter clean → 备份并删除 pubspec.lock → flutter pub get
+ *   4. flutter build hap --{mode}
+ *   5. 校验 hap 产物存在；按错误特征分类失败原因
+ *   6. 结果增量写入 {output}/build-matrix-results.json，日志存 {output}/logs/{版本}.log
+ *
+ * 用法:
+ *   node build-matrix.cjs --source <libRoot> [--example <dir>] [--versions "3.7,3.22"] \
+ *     [--mode debug|release] [--output <dir>] [--resume] [--codesign] \
+ *     [--build-timeout <sec>] [--install-timeout <sec>] [--no-fresh-resolve]
+ *
+ * 默认 --no-codesign（无头验证编译链；签名构建需工程已配置 DevEco 调试签名）
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+// ── 版本-分支映射（与 flvm 远程分支对应；过期时以 `flvm list -r` 为准修正） ──
+
+const PREFERRED_BRANCHES = {
+  '3.7': ['br_3.7.12-ohos-1.1.3', 'br_3.7.12-ohos-dev'],
+  '3.22': ['oh-3.22.3-release', 'oh-3.22.3-dev'],
+  '3.27': ['oh-3.27.4-dev', 'oh-3.27.0-release'],
+  '3.32': ['oh-3.32.0-release', 'oh-3.32.4-dev'],
+  '3.35': ['oh-3.35.7-dev', 'oh-3.35.7-release'],
+  '3.41': ['oh-3.41.9-release', 'oh-3.41.9-dev'],
+};
+
+const DEFAULT_VERSIONS = ['3.7', '3.22', '3.27', '3.32', '3.35', '3.41'];
+
+// ── 失败分类规则 ─────────────────────────────────────────
+
+const ERROR_PATTERNS = [
+  { type: 'sdk-constraint', label: 'Dart SDK 约束不兼容', re: /requires SDK version|current Dart SDK version|Dart SDK version.*(?:does not|not compatible)/i },
+  { type: 'dependency-conflict', label: '依赖版本冲突', re: /version solving failed|Because .+ depends on|incompatible dependency|dependency conflict/i },
+  { type: 'pubspec-invalid', label: 'pubspec.yaml 配置错误', re: /Error on line \d+ .*(?:pubspec\.yaml|yaml)/i },
+  // hvigor-crash 须先于 ohos-arkts-error：ProcessException/exit 255 崩溃特征更具体，
+  // 避免被泛化的 hvigor.*error 模式抢先匹配
+  { type: 'hvigor-crash', label: 'hvigor 任务异常退出（exit 255 等）', re: /ProcessException.*hvigorw|exit code:?\s*255|hvigorw[,\s]+(?:failed|OS error)/i },
+  { type: 'ohos-arkts-error', label: '鸿蒙工程编译错误（ArkTS/NAPI/hvigor）', re: /ArkTS|\.ets\(\d+,\d+\)|hvigor.*(?:ERROR|FAIL)|ERROR:.*\.ets|napi_/i },
+  { type: 'signing-error', label: '签名错误', re: /signature|signing|\.p12|\.cer\b|profile.*invalid/i },
+  { type: 'network', label: '网络/镜像故障', re: /Failed to fetch|network .*unreachable|timed? ?out|ECONNREFUSED|ECONNRESET|socket hang up|Connection refused|Failed host lookup/i },
+  { type: 'toolchain-env', label: '工具链环境问题', re: /hvigorw.*(?:not found|No such file)|ohpm.*(?:not found|No such file)|(?:JAVA_HOME|TOOL_HOME|DEVECO_SDK_HOME).*(?:not|undefined|missing)/i },
+  { type: 'build-failed', label: '构建失败（通用）', re: /Build process failed|BUILD FAILED|Compilation failed|Compilation error/i },
+];
+
+function classifyError(logText) {
+  const lines = logText.split(/\r?\n/);
+  const tail = lines.slice(-200).join('\n');
+  for (const p of ERROR_PATTERNS) {
+    if (p.re.test(tail)) return p;
+  }
+  return { type: 'unknown', label: '未分类失败' };
+}
+
+// ── 参数解析 ─────────────────────────────────────────────
+
+function parseArgs(argv) {
+  if (argv.length > 0 && typeof argv[0] === 'string' && argv[0].startsWith('{')) {
+    try { return JSON.parse(argv[0]); } catch (e) { return {}; }
+  }
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    switch (argv[i]) {
+      case '--source': args.source = argv[++i]; break;
+      case '--example': args.example = argv[++i]; break;
+      case '--versions': args.versions = argv[++i]; break;
+      case '--mode': args.mode = argv[++i]; break;
+      case '--output': args.output = argv[++i]; break;
+      case '--resume': args.resume = true; break;
+      case '--codesign': args.codesign = true; break;
+      case '--no-fresh-resolve': args.freshResolve = false; break;
+      case '--build-timeout': args.buildTimeout = parseInt(argv[++i], 10); break;
+      case '--install-timeout': args.installTimeout = parseInt(argv[++i], 10); break;
+    }
+  }
+  return args;
+}
+
+// ── 子进程封装 ───────────────────────────────────────────
+
+function run(cmd, cmdArgs, opts) {
+  const r = spawnSync(cmd, cmdArgs, {
+    cwd: opts.cwd || process.cwd(),
+    encoding: 'utf-8',
+    timeout: (opts.timeoutSec || 600) * 1000,
+    maxBuffer: 64 * 1024 * 1024,
+    env: process.env,
+  });
+  return {
+    code: r.status,
+    error: r.error ? String(r.error.message) : null,
+    stdout: r.stdout || '',
+    stderr: r.stderr || '',
+    get output() { return `${this.stdout}\n${this.stderr}`; },
+  };
+}
+
+// ── hap 产物查找 ─────────────────────────────────────────
+
+function findHap(exampleDir) {
+  const ohosDir = path.join(exampleDir, 'ohos');
+  if (!fs.existsSync(ohosDir)) return null;
+  const haps = [];
+  const walk = (dir, depth) => {
+    if (depth > 6) return;
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (e) { return; }
+    for (const ent of entries) {
+      const full = path.join(dir, ent.name);
+      if (ent.isDirectory()) walk(full, depth + 1);
+      else if (ent.name.endsWith('-signed.hap') || ent.name.endsWith('.hap')) haps.push(full);
+    }
+  };
+  walk(ohosDir, 0);
+  const signed = haps.find((h) => h.endsWith('-signed.hap'));
+  return signed || haps[0] || null;
+}
+
+// ── git 状态快照（构建副作用记录） ────────────────────────
+
+function gitStatusSnapshot(dir) {
+  const r = run('git', ['status', '--short'], { cwd: dir, timeoutSec: 60 });
+  if (r.code !== 0) return null;
+  return r.stdout.split(/\r?\n/).filter(Boolean);
+}
+
+// ── 主流程 ───────────────────────────────────────────────
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const libRoot = args.source ? path.resolve(args.source) : null;
+  if (!libRoot || !fs.existsSync(path.join(libRoot, 'pubspec.yaml'))) {
+    console.error('[build-matrix] 错误: --source 必须为含 pubspec.yaml 的库根目录');
+    process.exit(1);
+  }
+  const mode = args.mode === 'release' ? 'release' : 'debug';
+  const versions = (args.versions ? args.versions.split(',').map((v) => v.trim()) : DEFAULT_VERSIONS).filter(Boolean);
+  const outputDir = path.resolve(args.output || path.join(libRoot, 'flutter-build-test'));
+  const logsDir = path.join(outputDir, 'logs');
+  const backupDir = path.join(outputDir, 'backups');
+  fs.mkdirSync(logsDir, { recursive: true });
+  fs.mkdirSync(backupDir, { recursive: true });
+
+  // example 目录：--example > buildEnv.sh BUILD_PKG_DIR > example/
+  let exampleDir;
+  if (args.example) {
+    exampleDir = path.resolve(args.example);
+  } else {
+    const envFile = path.join(libRoot, 'buildEnv.sh');
+    let pkgDir = null;
+    if (fs.existsSync(envFile)) {
+      const m = fs.readFileSync(envFile, 'utf-8').match(/^\s*BUILD_PKG_DIR\s*=\s*(.+)$/m);
+      if (m) pkgDir = m[1].trim().replace(/^["']|["']$/g, '');
+    }
+    exampleDir = pkgDir ? path.resolve(libRoot, pkgDir) : path.join(libRoot, 'example');
+  }
+  if (!fs.existsSync(path.join(exampleDir, 'pubspec.yaml'))) {
+    console.error(`[build-matrix] 错误: example 目录无效（无 pubspec.yaml）: ${exampleDir}`);
+    console.error('[build-matrix] 请先用 locate-example.cjs 定位并用 --example 指定');
+    process.exit(1);
+  }
+  if (!fs.existsSync(path.join(exampleDir, 'ohos'))) {
+    console.error(`[build-matrix] 错误: example 目录缺少 ohos 工程代码: ${exampleDir}`);
+    process.exit(1);
+  }
+
+  // flvm 可用性检查
+  const flvmVer = run('flvm', ['--version'], { timeoutSec: 30 });
+  if (flvmVer.code !== 0) {
+    console.error('[build-matrix] 错误: flvm 不可用，请先安装并执行 flvm init（见 references/FLVM_GUIDE.md）');
+    process.exit(1);
+  }
+
+  // 环境体检快照
+  const doctor = run('flvm', ['doctor'], { timeoutSec: 120 });
+  fs.writeFileSync(path.join(outputDir, 'env-doctor.txt'), doctor.output, 'utf-8');
+
+  // 结果文件（增量）
+  const resultsFile = path.join(outputDir, 'build-matrix-results.json');
+  let results = { libRoot, exampleDir, mode, codesign: !!args.codesign, startedAt: new Date().toISOString(), versions: {} };
+  if (args.resume && fs.existsSync(resultsFile)) {
+    try {
+      results = JSON.parse(fs.readFileSync(resultsFile, 'utf-8'));
+      results.exampleDir = exampleDir;
+      results.mode = mode;
+    } catch (e) { /* 损坏则重建 */ }
+  }
+
+  // pubspec.lock 原件备份（fresh-resolve 模式）
+  const lockFile = path.join(exampleDir, 'pubspec.lock');
+  const origBackup = path.join(backupDir, 'pubspec.lock.original');
+  const freshResolve = args.freshResolve !== false;
+  if (freshResolve && fs.existsSync(lockFile) && !fs.existsSync(origBackup)) {
+    fs.copyFileSync(lockFile, origBackup);
+  }
+
+  // git 状态前后快照（flutter 工具会自动修改 example/ohos 的 build-profile/oh-package 注册插件模块，如实记录）
+  const gitBefore = gitStatusSnapshot(libRoot);
+  const gitAfter = () => {
+    const after = gitStatusSnapshot(libRoot) || [];
+    const beforeSet = new Set(gitBefore || []);
+    return after.filter((l) => !beforeSet.has(l));
+  };
+
+  console.log(`[build-matrix] 库根目录: ${libRoot}`);
+  console.log(`[build-matrix] example: ${exampleDir}`);
+  console.log(`[build-matrix] 版本列表: ${versions.join(', ')}  模式: ${mode}  续跑: ${args.resume ? '是' : '否'}`);
+  console.log('');
+
+  const saveResults = () => fs.writeFileSync(resultsFile, JSON.stringify(results, null, 2), 'utf-8');
+  const buildTimeout = args.buildTimeout || 1800;
+  const installTimeout = args.installTimeout || 3600;
+
+  for (const ver of versions) {
+    const key = ver;
+    const prev = results.versions[key];
+    if (args.resume && prev && (prev.status === 'pass' || prev.status === 'fail')) {
+      console.log(`⏭️  [${ver}] 已有结论 (${prev.status})，跳过（--resume）`);
+      continue;
+    }
+
+    console.log(`\n========== Flutter ${ver} ==========`);
+    const entry = { version: ver, branch: null, flutterVersion: null, pubGet: 'skip', build: 'skip', status: 'running', hapArtifact: null, failure: null, startedAt: new Date().toISOString() };
+    results.versions[key] = entry;
+    saveResults();
+    const logParts = [];
+
+    // 1. flvm 切换（首选分支 → 回退分支 → 模糊匹配）
+    let switched = false;
+    const branches = PREFERRED_BRANCHES[ver] || [ver];
+    for (const branch of branches) {
+      console.log(`[flvm] use ${branch} ...`);
+      const r = run('flvm', ['use', branch], { timeoutSec: installTimeout });
+      logParts.push(`$ flvm use ${branch}\n${r.output}`);
+      if (r.code === 0) { entry.branch = branch; switched = true; break; }
+      console.log(`[flvm] use ${branch} 失败 (exit ${r.code})，尝试下一候选`);
+    }
+    if (!switched) {
+      console.log(`[flvm] 首选分支均失败，回退模糊匹配: flvm use ${ver}`);
+      const r = run('flvm', ['use', ver], { timeoutSec: installTimeout });
+      logParts.push(`$ flvm use ${ver}\n${r.output}`);
+      if (r.code !== 0) {
+        entry.status = 'env-error';
+        entry.failure = { type: 'flvm-install', label: `flvm 无法安装/切换 ${ver} 版本` };
+        entry.build = 'skip';
+        entry.pubGet = 'skip';
+        saveResults();
+        fs.writeFileSync(path.join(logsDir, `${ver}.log`), logParts.join('\n\n'), 'utf-8');
+        console.log(`❌ [${ver}] flvm 切换失败，记为 env-error`);
+        continue;
+      }
+      entry.branch = ver;
+    }
+
+    // 2. flutter --version 校验
+    const fv = run('flutter', ['--version'], { timeoutSec: 300 });
+    logParts.push(`$ flutter --version\n${fv.output}`);
+    const vm = (fv.stdout || '').match(/Flutter (\d+)\.(\d+)\.(\d+)/);
+    entry.flutterVersion = vm ? `${vm[1]}.${vm[2]}.${vm[3]}` : null;
+    if (fv.code !== 0 || !entry.flutterVersion || `${vm[1]}.${vm[2]}` !== ver) {
+      entry.status = 'env-error';
+      entry.failure = { type: 'flvm-version-mismatch', label: `切换后 Flutter 版本异常（期望 ${ver}.x，实际 ${entry.flutterVersion || '未知'}）` };
+      saveResults();
+      fs.writeFileSync(path.join(logsDir, `${ver}.log`), logParts.join('\n\n'), 'utf-8');
+      console.log(`❌ [${ver}] 版本校验失败: 实际 ${entry.flutterVersion}`);
+      continue;
+    }
+    console.log(`[flutter] ${entry.flutterVersion} (${entry.branch}) ✓`);
+
+    // 3. flutter clean + fresh pubspec.lock + pub get
+    const clean = run('flutter', ['clean'], { cwd: exampleDir, timeoutSec: 300 });
+    logParts.push(`$ flutter clean\n${clean.output}`);
+    if (freshResolve && fs.existsSync(lockFile)) fs.rmSync(lockFile, { force: true });
+
+    const pubGet = run('flutter', ['pub', 'get'], { cwd: exampleDir, timeoutSec: 900 });
+    logParts.push(`$ flutter pub get\n${pubGet.output}`);
+    entry.pubGet = pubGet.code === 0 ? 'pass' : 'fail';
+    if (pubGet.code !== 0) {
+      const cls = classifyError(pubGet.output);
+      entry.status = 'fail';
+      entry.build = 'skip';
+      entry.failure = { type: cls.type, label: cls.label, stage: 'pub-get' };
+      saveResults();
+      fs.writeFileSync(path.join(logsDir, `${ver}.log`), logParts.join('\n\n'), 'utf-8');
+      console.log(`❌ [${ver}] pub get 失败: ${cls.label}`);
+      continue;
+    }
+    console.log(`[pub get] ✓`);
+
+    // 4. flutter build hap（版本差异处理：3.7/3.27 等 fork 不支持 --no-codesign 参数，
+    //    需探测后决定是否附加；不支持的版本构建后由 flutter 工具强制签名检查，
+    //    编译链已通过且产出 unsigned hap 时按通过计——见 references/BUILD_TROUBLESHOOTING.md §3.6）
+    const help = run('flutter', ['build', 'hap', '--help'], { timeoutSec: 120 });
+    logParts.push(`$ flutter build hap --help (探测 codesign 参数支持)\n${(help.stdout || '').slice(0, 2000)}`);
+    const supportsCodesignFlag = /--\[no-\]codesign/.test(help.stdout || '');
+    const hapArgs = ['build', 'hap', `--${mode}`];
+    if (!args.codesign && supportsCodesignFlag) hapArgs.push('--no-codesign');
+    const build = run('flutter', hapArgs, { cwd: exampleDir, timeoutSec: buildTimeout });
+    logParts.push(`$ flutter ${hapArgs.join(' ')}\n${build.output}`);
+    entry.build = build.code === 0 ? 'pass' : 'fail';
+
+    // 5. 产物校验 + 结论
+    const hap = findHap(exampleDir);
+    entry.hapArtifact = hap;
+    const signedRejected = /配置调试签名|Automatically generate signature/.test(build.output);
+    if (build.code === 0 && hap) {
+      entry.status = 'pass';
+      console.log(`✅ [${ver}] 编译通过 (${path.relative(exampleDir, hap)})`);
+    } else if (build.code !== 0 && !supportsCodesignFlag && signedRejected && hap) {
+      // 不支持 --no-codesign 的版本：flutter 工具签名检查拒绝，但 hvigor 编译链已完成且产出 unsigned hap
+      entry.status = 'pass';
+      entry.build = 'pass';
+      entry.note = '该 Flutter 版本不支持 --no-codesign，flutter 工具签名检查拒绝退出；hvigor 编译链已完成并产出 unsigned hap，按编译验证通过计';
+      console.log(`✅ [${ver}] 编译通过（unsigned hap，签名检查跳过） (${path.relative(exampleDir, hap)})`);
+    } else if (build.code === 0 && !hap) {
+      // 命令成功但产物缺失：可疑，记为 fail（warning 类）
+      entry.status = 'fail';
+      entry.failure = { type: 'artifact-missing', label: '构建命令成功但未找到 hap 产物', stage: 'build' };
+      console.log(`⚠️ [${ver}] 构建成功但未找到 hap 产物，记为 fail`);
+    } else {
+      const cls = classifyError(build.output);
+      entry.status = 'fail';
+      entry.failure = { type: cls.type, label: cls.label, stage: 'build' };
+      console.log(`❌ [${ver}] 编译失败: ${cls.label}`);
+    }
+    entry.finishedAt = new Date().toISOString();
+    saveResults();
+    fs.writeFileSync(path.join(logsDir, `${ver}.log`), logParts.join('\n\n'), 'utf-8');
+  }
+
+  // 恢复原 pubspec.lock
+  if (freshResolve && fs.existsSync(origBackup)) {
+    fs.copyFileSync(origBackup, lockFile);
+    console.log('\n[build-matrix] 已恢复原 pubspec.lock');
+  }
+
+  // 汇总
+  results.finishedAt = new Date().toISOString();
+  const repoChanges = gitAfter();
+  results.repoChangesDuringBuild = repoChanges;
+  if (repoChanges.length > 0) {
+    console.log('\n[build-matrix] ⚠️ 构建期间仓库出现的变更（flutter 工具自动注册插件模块等，属正常副作用，报告中需列出）:');
+    for (const l of repoChanges.slice(0, 20)) console.log(`    ${l}`);
+    if (repoChanges.length > 20) console.log(`    ... 共 ${repoChanges.length} 条`);
+  }
+  saveResults();
+  const passVersions = Object.values(results.versions).filter((v) => v.status === 'pass');
+  console.log('\n========== 汇总 ==========');
+  console.log('版本 | 分支 | pub get | build | 结论 | 失败原因');
+  for (const ver of versions) {
+    const v = results.versions[ver];
+    if (!v) continue;
+    console.log(`${ver} | ${v.branch || '-'} | ${v.pubGet} | ${v.build} | ${v.status} | ${v.failure ? v.failure.label : '-'}`);
+  }
+  console.log('');
+  console.log(`支持版本: ${passVersions.length ? passVersions.map((v) => v.version).sort((a, b) => parseFloat(a) - parseFloat(b)).join(', ') : '无'}`);
+  if (passVersions.length === 0) {
+    console.log('[build-matrix] ⚠️ 无任何版本通过——请先排查环境类失败（env-error 条目），修复后 --resume 重跑');
+    process.exit(2);
+  }
+  process.exit(0);
+}
+
+main();

package/vendor/Server/Skills/flutter-build-test/scripts/locate-example.cjs

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+/**
+ * locate-example.cjs — 定位 Flutter 三方库的 example 工程并校验 ohos 工程代码
+ *
+ * 行为：
+ *   1. 优先读取 {libRoot}/buildEnv.sh 的 BUILD_PKG_DIR（部分库 example 不在根下）
+ *   2. 扫描根目录及两层深度内含 pubspec.yaml 的 example 类目录
+ *   3. 校验候选目录存在 ohos/ 子目录且含鸿蒙工程特征（build-profile.json5 / oh-package.json5 / AppScope）
+ *   4. 输出 JSON 结论（stdout 最后一行以 JSON: 开头）
+ *
+ * 用法:
+ *   node locate-example.cjs --source /path/to/libRoot
+ *   node locate-example.cjs '{"source":"/path/to/libRoot"}'
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// ── 参数解析（兼容 MCP Gateway JSON 模式与 CLI 模式） ──────
+
+function parseArgs(argv) {
+  if (argv.length > 0 && typeof argv[0] === 'string' && argv[0].startsWith('{')) {
+    try { return JSON.parse(argv[0]); } catch (e) { return {}; }
+  }
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--source') args.source = argv[++i];
+    else if (argv[i] === '--example') args.example = argv[++i];
+  }
+  return args;
+}
+
+// ── 工具函数 ─────────────────────────────────────────────
+
+function exists(p) {
+  try { return fs.existsSync(p); } catch (e) { return false; }
+}
+
+function isDir(p) {
+  try { return fs.existsSync(p) && fs.statSync(p).isDirectory(); } catch (e) { return false; }
+}
+
+/** 从 buildEnv.sh 解析 BUILD_PKG_DIR（无引号值） */
+function readBuildEnv(source) {
+  const file = path.join(source, 'buildEnv.sh');
+  if (!exists(file)) return null;
+  const result = { file, pkgDir: null, flutterSdkVersion: null };
+  const text = fs.readFileSync(file, 'utf-8');
+  const m1 = text.match(/^\s*BUILD_PKG_DIR\s*=\s*(.+)$/m);
+  if (m1) result.pkgDir = m1[1].trim().replace(/^["']|["']$/g, '');
+  const m2 = text.match(/^\s*FLUTTER_SDK_VERSION\s*=\s*(.+)$/m);
+  if (m2) result.flutterSdkVersion = m2[1].trim().replace(/^["']|["']$/g, '');
+  return result;
+}
+
+/** 校验目录是否为鸿蒙工程（ohos/ 下含工程特征文件） */
+function checkOhosProject(dir) {
+  const features = ['build-profile.json5', 'oh-package.json5', 'hvigorfile.ts'];
+  const hasFeature = features.some((f) => exists(path.join(dir, f)));
+  const hasAppScope = isDir(path.join(dir, 'AppScope'));
+  return hasFeature || hasAppScope;
+}
+
+/** 候选 example 目录名匹配（大小写不敏感） */
+function looksLikeExample(name) {
+  return /^(example|examples|example_app|exampleapp|demo)$/i.test(name) || /^example[-_]/i.test(name);
+}
+
+/** 扫描候选 example 目录（两层深度，跳过 node_modules/build 等） */
+function scanCandidates(source) {
+  const candidates = [];
+  const SKIP = new Set(['node_modules', 'build', '.dart_tool', '.git', '.idea', 'ohos', 'android', 'ios', 'linux', 'macos', 'windows', 'web', 'test', 'lib', 'src']);
+  const scan = (dir, depth) => {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (e) { return; }
+    for (const ent of entries) {
+      if (!ent.isDirectory()) continue;
+      if (SKIP.has(ent.name)) continue;
+      const full = path.join(dir, ent.name);
+      if (exists(path.join(full, 'pubspec.yaml'))) {
+        candidates.push(full);
+      }
+      if (depth < 2) scan(full, depth + 1);
+    }
+  };
+  scan(source, 0);
+  // example 命名的优先
+  candidates.sort((a, b) => {
+    const ea = looksLikeExample(path.basename(a)) ? 0 : 1;
+    const eb = looksLikeExample(path.basename(b)) ? 0 : 1;
+    if (ea !== eb) return ea - eb;
+    return a.split(path.sep).length - b.split(path.sep).length;
+  });
+  return candidates;
+}
+
+// ── 主流程 ───────────────────────────────────────────────
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const source = args.source;
+  if (!source || !isDir(source)) {
+    console.error('[locate-example] 错误: --source 必须为存在的目录');
+    process.exit(1);
+  }
+  let libRoot = path.resolve(source);
+
+  // monorepo 兜底：根目录无 pubspec.yaml 但 buildEnv.sh 的 BUILD_PKG_DIR 有效时，
+  // 以 BUILD_PKG_DIR 向上回溯到仓库根范围内最高的含 pubspec.yaml 目录作为有效包根
+  // （如 BUILD_PKG_DIR=YFree_Flutter/Lite/example → 包根 YFree_Flutter/Lite，而非 example 自身）
+  let packageRootOverride = null;
+  if (!exists(path.join(libRoot, 'pubspec.yaml'))) {
+    const env = readBuildEnv(libRoot);
+    if (env && env.pkgDir) {
+      let probe = path.resolve(libRoot, env.pkgDir);
+      const repoTop = path.resolve(libRoot);
+      while (probe.length >= repoTop.length && probe.startsWith(repoTop)) {
+        if (exists(path.join(probe, 'pubspec.yaml'))) packageRootOverride = probe;
+        const parent = path.dirname(probe);
+        if (parent === probe) break;
+        probe = parent;
+      }
+    }
+    if (!packageRootOverride) {
+      console.error(`[locate-example] 错误: ${libRoot} 下未找到 pubspec.yaml，不是 Flutter 库根目录`);
+      console.error('[locate-example] 提示: monorepo 请将 --source 指向含 pubspec.yaml 的包根目录');
+      process.exit(1);
+    }
+    console.log(`[locate-example] 提示: 根目录无 pubspec.yaml，依据 buildEnv.sh BUILD_PKG_DIR 推导有效包根: ${packageRootOverride}`);
+    libRoot = packageRootOverride;
+  }
+
+  const buildEnv = readBuildEnv(libRoot);
+  const repoBuildEnv = packageRootOverride ? readBuildEnv(path.resolve(source)) : buildEnv;
+  const summary = { repoRoot: path.resolve(source), libRoot, buildEnv: repoBuildEnv ? { file: repoBuildEnv.file, pkgDir: repoBuildEnv.pkgDir, flutterSdkVersion: repoBuildEnv.flutterSdkVersion } : null, exampleDir: null, ohosDir: null, buildPkgDir: repoBuildEnv ? repoBuildEnv.pkgDir : null, hasOhos: false, candidates: [], selected: null };
+
+  // 候选构造：显式 --example > buildEnv.BUILD_PKG_DIR > 扫描
+  // （buildEnv 的 pkgDir 相对 buildEnv.sh 所在目录解析）
+  const envBaseDir = repoBuildEnv ? path.dirname(repoBuildEnv.file) : null;
+  const ordered = [];
+  if (args.example) ordered.push({ dir: path.resolve(libRoot, args.example), origin: '--example 参数' });
+  if (repoBuildEnv && repoBuildEnv.pkgDir) ordered.push({ dir: path.resolve(envBaseDir, repoBuildEnv.pkgDir), origin: 'buildEnv.sh BUILD_PKG_DIR' });
+  for (const c of scanCandidates(libRoot)) ordered.push({ dir: c, origin: '目录扫描' });
+  if (exists(path.join(libRoot, 'example', 'pubspec.yaml')) && !ordered.some((o) => o.dir === path.join(libRoot, 'example'))) {
+    ordered.push({ dir: path.join(libRoot, 'example'), origin: '默认 example 目录' });
+  }
+
+  for (const cand of ordered) {
+    if (!exists(path.join(cand.dir, 'pubspec.yaml'))) {
+      summary.candidates.push({ dir: cand.dir, origin: cand.origin, hasPubspec: false, hasOhos: false, verdict: 'reject-no-pubspec' });
+      continue;
+    }
+    const ohosDir = path.join(cand.dir, 'ohos');
+    const hasOhos = isDir(ohosDir) && checkOhosProject(ohosDir);
+    summary.candidates.push({ dir: cand.dir, origin: cand.origin, hasPubspec: true, hasOhos, ohosValid: hasOhos, verdict: hasOhos ? 'accept' : 'reject-no-ohos' });
+    if (hasOhos && !summary.exampleDir) {
+      summary.exampleDir = cand.dir;
+      summary.ohosDir = ohosDir;
+      summary.hasOhos = true;
+      summary.selected = cand;
+    }
+  }
+
+  console.log('[locate-example] 候选评估:');
+  for (const c of summary.candidates) {
+    console.log(`  ${c.verdict === 'accept' ? '✅' : '❌'} ${path.relative(libRoot, c.dir) || '.'} (来源: ${c.origin}) — ${c.verdict}`);
+  }
+
+  if (summary.exampleDir) {
+    console.log(`[locate-example] 选定 example 工程: ${summary.exampleDir}`);
+    console.log(`[locate-example] ohos 工程目录: ${summary.ohosDir}`);
+    if (repoBuildEnv && repoBuildEnv.pkgDir) {
+      const envResolved = path.resolve(envBaseDir, repoBuildEnv.pkgDir);
+      if (envResolved !== summary.exampleDir) {
+        console.log(`[locate-example] ⚠️ buildEnv.sh BUILD_PKG_DIR (${repoBuildEnv.pkgDir}) 与实际选定目录不一致，建议在 Phase 4 修正`);
+      }
+    }
+  } else {
+    console.error('[locate-example] 未找到含 ohos 工程代码的 example 目录');
+    console.error('[locate-example] 可尝试: 在 example 目录执行 flutter create --platforms ohos . 生成鸿蒙工程后重试');
+  }
+
+  console.log('JSON: ' + JSON.stringify(summary));
+  process.exit(summary.exampleDir ? 0 : 1);
+}
+
+main();