@harmonyos-arkts/d2h 0.1.11 → 0.1.13

package/scripts/check-environment.mjs

@@ -1,320 +1,320 @@
-#!/usr/bin/env node
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import { spawn, spawnSync } from 'node:child_process';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-import { parseArgs } from 'node:util';
-
-const DEFAULT_REQUIREMENTS = fileURLToPath(new URL('../skills/managing-d2h-toolchain/environment-requirements.json', import.meta.url));
-const VERSION_TOOLS = ['node', 'python', 'git', 'npm', 'java', 'python-json5', 'appgraph', 'droid2hmos', 'hvigor', 'ohpm', 'devecocli'];
-
-function versionParts(value) {
-  if (typeof value !== 'string' || !/^\d+(?:\.\d+){0,3}$/.test(value)) throw new Error(`无效版本：${value}`);
-  const parts = value.split('.').map(Number);
-  if (parts.some(part => !Number.isSafeInteger(part))) throw new Error(`无效版本：${value}`);
-  return [...parts, ...Array(4 - parts.length).fill(0)];
-}
-
-function compareVersions(left, right) {
-  const a = versionParts(left);
-  const b = versionParts(right);
-  for (let index = 0; index < a.length; index++) {
-    if (a[index] !== b[index]) return a[index] < b[index] ? -1 : 1;
-  }
-  return 0;
-}
-
-export function loadRequirements(file = DEFAULT_REQUIREMENTS) {
-  const config = JSON.parse(fs.readFileSync(file, 'utf8').replace(/^\uFEFF/, ''));
-  if (config?.schemaVersion !== 1 || !config.tools || typeof config.tools !== 'object' || Array.isArray(config.tools)) {
-    throw new Error('版本配置必须包含 schemaVersion: 1 和 tools 对象');
-  }
-  for (const key of Object.keys(config)) {
-    if (!['schemaVersion', 'tools'].includes(key)) throw new Error(`未知配置字段：${key}`);
-  }
-  for (const key of Object.keys(config.tools)) {
-    if (!VERSION_TOOLS.includes(key)) throw new Error(`未知工具：${key}`);
-  }
-  for (const key of VERSION_TOOLS) {
-    if (!Object.hasOwn(config.tools, key)) throw new Error(`版本配置缺少工具：${key}；不约束版本请设为 null`);
-    const rule = config.tools[key];
-    if (rule === null) continue;
-    if (typeof rule !== 'object' || Array.isArray(rule) || !Object.keys(rule).length) throw new Error(`无效工具约束：${key}`);
-    for (const bound of Object.keys(rule)) {
-      if (!['minimum', 'maximumExclusive'].includes(bound)) throw new Error(`未知版本边界：${key}.${bound}`);
-      versionParts(rule[bound]);
-    }
-    if (rule.minimum && rule.maximumExclusive && compareVersions(rule.minimum, rule.maximumExclusive) >= 0) {
-      throw new Error(`版本区间为空：${key}`);
-    }
-  }
-  return config;
-}
-
-function constraintLabel(rule) {
-  return rule ? [rule.minimum && `>=${rule.minimum}`, rule.maximumExclusive && `<${rule.maximumExclusive}`].filter(Boolean).join(' ') : '仅检查可用性';
-}
-
-export function meetsVersionRule(output, rule, id = '') {
-  if (!rule) return true;
-  const match = output.match(/\d+\.\d+(?:\.\d+){0,2}/);
-  if (!match) return false;
-  let version = match[0];
-  if (id === 'java' && version.startsWith('1.')) version = version.slice(2);
-  return (!rule.minimum || compareVersions(version, rule.minimum) >= 0) &&
-    (!rule.maximumExclusive || compareVersions(version, rule.maximumExclusive) < 0);
-}
-
-export function resolveExecutable(command, env = process.env, platform = process.platform) {
-  // npm ships Unix shims beside .cmd files; Windows cannot spawn the shims.
-  const extensions = platform === 'win32' && !path.extname(command)
-    ? (env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';') : [''];
-  const directories = /[/\\]/.test(command) ? [''] : (env.PATH || '').split(platform === 'win32' ? ';' : ':');
-  for (const directory of directories) {
-    for (const extension of extensions) {
-      const candidate = directory ? path.join(directory, command + extension) : command + extension;
-      try {
-        if (!fs.statSync(candidate).isFile()) continue;
-        if (platform !== 'win32') fs.accessSync(candidate, fs.constants.X_OK);
-        return path.resolve(candidate);
-      } catch { /* Try the next candidate. */ }
-    }
-  }
-  return command;
-}
-
-export function invocation(executable, args, platform = process.platform, env = process.env) {
-  const resolved = resolveExecutable(executable, env, platform);
-  if (/\.m?js$/i.test(resolved)) return [process.execPath, resolved, ...args];
-  if (platform === 'win32' && /\.(cmd|bat)$/i.test(resolved)) {
-    const quote = (value) => `'${String(value).replaceAll("'", "''")}'`;
-    const source = `& ${[resolved, ...args].map(quote).join(' ')}; exit $LASTEXITCODE`;
-    return ['powershell.exe', '-NoProfile', '-NonInteractive', '-EncodedCommand', Buffer.from(source, 'utf16le').toString('base64')];
-  }
-  return [resolved, ...args];
-}
-
-export async function probe(executable, args, timeout = 15, options = {}) {
-  const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'd2h-env-'));
-  const log = fs.openSync(path.join(directory, 'output.log'), 'w+');
-  const errorLog = fs.openSync(path.join(directory, 'error.log'), 'w+');
-  let exitCode = null;
-  let error = null;
-  try {
-    const [command, ...commandArgs] = invocation(executable, args);
-    await new Promise((resolve) => {
-      // Files and the exit event avoid waiting on inherited output handles.
-      const child = spawn(command, commandArgs, {
-        cwd: options.cwd || directory, windowsHide: true, detached: process.platform !== 'win32',
-        env: { ...process.env, DEVECO_CLI_SKIP_VERSION_CHECK: '1' }, stdio: ['ignore', log, errorLog],
-      });
-      const timer = setTimeout(() => {
-        error = 'timeout';
-        if (child.pid) {
-          if (process.platform === 'win32') {
-            spawnSync('taskkill.exe', ['/PID', String(child.pid), '/T', '/F'], { windowsHide: true, stdio: 'ignore', timeout: 5000 });
-          } else {
-            try { process.kill(-child.pid, 'SIGKILL'); } catch { /* Already exited. */ }
-          }
-        }
-        clearTimeout(timer);
-        resolve();
-      }, timeout * 1000);
-      child.once('error', (err) => { error ??= err.message; clearTimeout(timer); resolve(); });
-      child.once('exit', (code) => { exitCode = code; clearTimeout(timer); resolve(); });
-    });
-    const read = (descriptor) => {
-      const buffer = Buffer.alloc(65536);
-      const length = fs.readSync(descriptor, buffer, 0, buffer.length, 0);
-      return buffer.subarray(0, length).toString('utf8').trim();
-    };
-    const stdout = read(log);
-    const stderr = read(errorLog);
-    return { command: [executable, ...args], exitCode, ok: exitCode === 0 && !error, error, stdout, stderr, output: [stdout, stderr].filter(Boolean).join('\n') };
-  } catch (err) {
-    return { command: [executable, ...args], exitCode, ok: false, error: err.message, output: '' };
-  } finally {
-    fs.closeSync(log);
-    fs.closeSync(errorLog);
-    try { fs.rmSync(directory, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); }
-    catch { /* Windows scanners may retain a handle briefly; do not hide the probe result. */ }
-  }
-}
-
-function isDirectory(value) {
-  try { return Boolean(value && fs.statSync(value).isDirectory()); } catch { return false; }
-}
-
-function isFile(value) {
-  try { return Boolean(value && fs.statSync(value).isFile()); } catch { return false; }
-}
-
-export function firstDirectory(values) {
-  const found = values.find(isDirectory);
-  return found ? path.resolve(found) : null;
-}
-
-export function pythonJson5Required(source) {
-  function visit(directory) {
-    if (!isDirectory(directory)) return false;
-    return fs.readdirSync(directory, { withFileTypes: true }).some((entry) => {
-      if (['__pycache__', 'node_modules', '.git', 'tests'].includes(entry.name)) return false;
-      const file = path.join(directory, entry.name);
-      return entry.isDirectory() ? visit(file) : entry.name.endsWith('.py') &&
-        /^\s*(?:import\s+json5\b|from\s+json5\b)/m.test(fs.readFileSync(file, 'utf8'));
-    });
-  }
-  return visit(path.join(source, 'skills'));
-}
-
-export function parseDevEcoJson(output) {
-  // DevEco CLI 1.3.3 appends its updater notice to stdout even with --format json.
-  // Strip only that known trailing line; unrelated malformed output still fails.
-  return JSON.parse(output.replace(/\r?\n\s*New version [\w.+-]+ available, run `devecocli update` to upgrade\s*$/, '').trim());
-}
-
-export async function collect(options, { runner = probe, env = process.env, platform = process.platform, home = os.homedir(), directoryFinder = firstDirectory, nodeVersion = process.version } = {}) {
-  const requirementsFile = path.resolve(options.requirementsFile || DEFAULT_REQUIREMENTS);
-  const requirements = loadRequirements(requirementsFile);
-  const ruleFor = id => requirements.tools[id];
-  const checks = [];
-  const add = (id, required, passed, summary, remediation = '', evidence = [], skipped = false) => {
-    checks.push({ id, required, status: skipped ? 'skipped' : passed ? 'passed' : required ? 'failed' : 'warning', summary,
-      remediation: passed ? '' : remediation, evidence });
-  };
-  const tool = async (id, executable, params, remediation, predicate = () => true) => {
-    const result = await runner(executable, params, options.timeout);
-    const rule = ruleFor(id);
-    const passed = result.ok && predicate(result.output) && meetsVersionRule(result.output, rule, id);
-    const summary = result.output.split(/\r?\n/)[0] || result.error || '命令未成功';
-    add(id, true, passed, `${summary}${rule ? `（要求 ${constraintLabel(rule)}）` : ''}`,
-      `${remediation}${rule ? ` 版本须满足 ${constraintLabel(rule)}。` : ''}`, [result]);
-    return result;
-  };
-  add('node', true, meetsVersionRule(nodeVersion, ruleFor('node')), `${nodeVersion} (${process.execPath})（要求 ${constraintLabel(ruleFor('node'))}）`,
-    `请安装满足 ${constraintLabel(ruleFor('node'))} 的 Node.js，然后重新运行脚本。`);
-  await tool('git', 'git', ['--version'], '安装 Git 并将 git 加入 PATH。');
-  await tool('npm', 'npm', ['--version'], '使用 Node.js 自带的 npm，检查 PATH。');
-  await tool('java', 'java', ['-version'], '安装项目 Gradle/DevEco 所需 JDK，设置 JAVA_HOME 和 PATH；本检查不限定 JDK 主版本。');
-  // Python is a migration dependency, no longer a prerequisite to run this doctor.
-  const candidates = [...new Set([env.PYTHON_BINARY, platform === 'win32' ? 'python' : 'python3', 'python',
-    platform === 'darwin' ? '/opt/homebrew/bin/python3' : null, platform === 'darwin' ? '/usr/local/bin/python3' : null,
-    platform === 'darwin' ? '/opt/homebrew/anaconda3/bin/python3' : null].filter(Boolean))];
-  const pythonProbes = [];
-  let python = null;
-  for (const candidate of candidates) {
-    const result = await runner(candidate, ['--version'], options.timeout);
-    pythonProbes.push(result);
-    if (result.ok && meetsVersionRule(result.output, ruleFor('python'))) { python = candidate; break; }
-  }
-  add('python', true, Boolean(python), `${python ? `${pythonProbes.at(-1).output} (${python})` : '未找到符合要求的 Python'}（要求 ${constraintLabel(ruleFor('python'))}）`,
-    `安装满足 ${constraintLabel(ruleFor('python'))} 的 Python 并加入 PATH，或设置 PYTHON_BINARY 为解释器路径。`, pythonProbes);
-  if (pythonJson5Required(path.resolve(options.pluginRoot))) {
-    if (python) {
-      await tool('python-json5', python, ['-c', 'import json5; from importlib.metadata import version; print("json5 " + version("json5"))'],
-        `用检测到的 Python 安装：${platform === 'win32' ? '& ' : ''}'${python.replaceAll("'", platform === 'win32' ? "''" : "'\\''")}' -m pip install json5`);
-    } else {
-      add('python-json5', true, false, 'Python 不可用，尚未检查 json5', '安装 Python 后重新检查；使用同一解释器执行 -m pip install json5。', [], true);
-    }
-  }
-  for (const name of ['appgraph', 'droid2hmos']) {
-    await tool(name, name, ['--version'], '运行 managing-d2h-toolchain Skill 中的 node scripts/manage-toolchain.mjs install 安装精确版本；本地 npm link 需由开发者显式管理。');
-  }
-  const deveco = directoryFinder([env.DEVECO_STUDIO_HOME, env.DEVECO_HOME,
-    platform === 'darwin' ? '/Applications/DevEco-Studio.app/Contents' : null,
-    ...(platform === 'win32' ? ['C:/Program Files/Huawei/DevEco Studio', 'D:/Program Files/Huawei/DevEco Studio'] : [])]);
-  add('deveco', true, Boolean(deveco), deveco || '未找到 DevEco Studio', '安装 DevEco Studio，设置 DEVECO_STUDIO_HOME 为安装根目录（macOS 为 Contents）。');
-  for (const [id, variable, relative, fallback] of [
-    ['hvigor', 'DROID2HMOS_HVIGOR', 'tools/hvigor/bin/hvigorw.js', 'hvigorw'],
-    ['ohpm', 'DROID2HMOS_OHPM', 'tools/ohpm/bin/pm-cli.js', 'ohpm'],
-  ]) {
-    const bundled = deveco && path.join(deveco, relative);
-    await tool(id, env[variable] || (isFile(bundled) ? bundled : fallback), ['--version'], `安装 DevEco 配套工具；设置 ${variable} 为可执行文件或 JS 入口路径。`);
-  }
-  const sdk = directoryFinder([options.sdkPath, env.HARMONYOS_SDK_HOME, env.OHOS_SDK_HOME, env.DEVECO_SDK_HOME, deveco && path.join(deveco, 'sdk')]);
-  add('harmony-sdk-location', false, Boolean(sdk), sdk || '未发现声明 SDK 根目录', '设置 HARMONYOS_SDK_HOME 或 --sdk-path；实际声明有效性由 droid2hmos preflight 检查。');
-  const cli = env.DEVECO_CLI_BINARY || 'devecocli';
-  await tool('devecocli', cli, ['--version'], '安装 npm install -g @deveco/deveco-cli。');
-  const auth = await runner(cli, ['auth', 'status'], options.timeout);
-  const loggedIn = auth.ok && /Current user:\s*[^\r\n]+/i.test(auth.output) && !/Not logged in/i.test(auth.output);
-  add('devecocli-auth', true, loggedIn, loggedIn ? '已登录' : '未登录或无法确认登录状态',
-    '运行 droid2hmos auth login <android-project>，在浏览器完成授权；不要并发登录。',
-    [{ command: auth.command, exitCode: auth.exitCode, error: auth.error }]);
-  if (options.harmonyProject) {
-    const project = path.resolve(options.harmonyProject);
-    const versions = await runner(cli, ['check', 'compat', 'versions', '--format', 'json'], options.timeout, { cwd: project });
-    let available = [];
-    try { const value = parseDevEcoJson(versions.stdout ?? versions.output); available = Array.isArray(value.versions) ? value.versions.filter((v) => typeof v === 'string') : []; } catch { /* Keep diagnostic. */ }
-    add('harmony-sdk-compatibility', false, versions.ok && available.length > 0,
-      available.length ? `DevEco CLI 可识别 SDK：${available.join(', ')}` : '无法确认工程可用 SDK 版本',
-      '在 DevEco 中安装工程所需 SDK；构建与 API 兼容性仍由项目 preflight 验证。', [versions]);
-  }
-  if (options.androidProject) {
-    const root = path.resolve(options.androidProject);
-    add('android-source-root', true, ['settings.gradle', 'settings.gradle.kts', 'build.gradle', 'build.gradle.kts'].some((f) => isFile(path.join(root, f))),
-      root, '用 --android-project 指向包含 Gradle 配置标记的 Android 源码根目录；不要求 Wrapper 或 Android 编译环境。');
-  }
-  const result = checks.some((c) => c.required && c.status === 'failed') ? 'failed'
-    : checks.some((c) => c.required && c.status === 'skipped') ? 'incomplete' : 'passed';
-  return { schemaVersion: '1.0.0', createdAt: new Date().toISOString(), platform: `${platform} ${os.arch()} ${os.release()}`, result, checks,
-    requirementsFile, versionRequirements: requirements.tools,
-    scope: '主机依赖检查；不证明构建、签名、SDK API 匹配或端到端验收成功。' };
-}
-
-export function markdown(report) {
-  const escape = (value) => String(value).replaceAll('|', '\\|').replaceAll('\r', '').replaceAll('\n', '<br>');
-  return ['# Android → HarmonyOS 环境检查', '', `结果：**${report.result}**`, '', report.scope, '', `版本配置：${report.requirementsFile || ''}`, '',
-    '| 检查 | 必需 | 状态 | 说明 |', '| --- | --- | --- | --- |',
-    ...report.checks.map((c) => `| ${c.id} | ${c.required ? '是' : '否'} | ${c.status} | ${escape(c.summary)} |`),
-    '', '## 修复指导', '', ...report.checks.filter((c) => c.remediation).map((c) => `- **${c.id}**：${c.remediation}`), '',
-    '修复后重新运行本脚本。主机检查通过后，运行 `droid2hmos preflight <android-project>` 验证真实项目门禁；该命令可能初始化工程并执行构建。', ''].join('\n');
-}
-
-export function parseOptions(argv) {
-  const { values } = parseArgs({ args: argv, options: {
-    'plugin-root': { type: 'string' },
-    requirements: { type: 'string' },
-    'android-project': { type: 'string' }, 'harmony-project': { type: 'string' }, 'sdk-path': { type: 'string' },
-    timeout: { type: 'string', default: '15' }, 'output-dir': { type: 'string' }, help: { type: 'boolean', short: 'h' },
-  } });
-  if (!/^\d+$/.test(values.timeout) || Number(values.timeout) < 1 || Number(values.timeout) > 60) throw new Error('--timeout 必须为 1–60 的整数');
-  return { pluginRoot: values['plugin-root'] || fileURLToPath(new URL('../', import.meta.url)),
-    requirementsFile: values.requirements ? path.resolve(values.requirements) : DEFAULT_REQUIREMENTS,
-    androidProject: values['android-project'], sdkPath: values['sdk-path'],
-    harmonyProject: values['harmony-project'],
-    timeout: Number(values.timeout),
-    outputDir: path.resolve(values['output-dir'] || 'environment-report'), help: values.help };
-}
-
-export async function main(argv = process.argv.slice(2)) {
-  let options;
-  try { options = parseOptions(argv); } catch (error) { console.error(error.message); return 2; }
-  if (options.help) {
-    console.log('用法：node scripts/check-environment.mjs [--plugin-root <path>] [--android-project <path>]\n  [--harmony-project <path>] [--sdk-path <path>] [--requirements <json>]\n  [--timeout <1–60 秒>] [--output-dir <path>]\n默认版本约束来自 skills/managing-d2h-toolchain/environment-requirements.json。只写报告，不自动安装依赖或修改配置。');
-    return 0;
-  }
-  const report = await collect(options);
-  fs.mkdirSync(options.outputDir, { recursive: true });
-  fs.writeFileSync(path.join(options.outputDir, 'environment.json'), JSON.stringify(report, null, 2) + '\n');
-  fs.writeFileSync(path.join(options.outputDir, 'environment.md'), markdown(report));
-  const passed = report.checks.filter((check) => check.status === 'passed').length;
-  const failures = report.checks.filter((check) => check.status === 'failed');
-  const warnings = report.checks.filter((check) => check.status === 'warning').length;
-  const skipped = report.checks.filter((check) => check.status === 'skipped').length;
-  const resultLabel = { passed: '通过', failed: '未通过', incomplete: '未完成' }[report.result];
-  console.log(`环境检查：${resultLabel}（通过 ${passed}，失败 ${failures.length}${warnings ? `，提醒 ${warnings}` : ''}${skipped ? `，未检查 ${skipped}` : ''}）`);
-  const statusLabels = { passed: '通过', failed: '未通过', warning: '提醒', skipped: '未检查' };
-  for (const check of report.checks) {
-    console.log(`[${statusLabels[check.status] || check.status}] ${check.id}：${check.summary}`);
-    if (check.status !== 'passed' && check.remediation) {
-      console.log(`  修复：${check.remediation}`);
-    }
-  }
-  console.log(`详细报告：${path.join(options.outputDir, 'environment.md')}`);
-  return report.result === 'failed' ? 1 : report.result === 'incomplete' ? 2 : 0;
-}
-
-if (process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url) {
-  try { process.exitCode = await main(); } catch (error) { console.error(`环境检查失败：${error.message}`); process.exitCode = 1; }
-}
+#!/usr/bin/env node
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { parseArgs } from 'node:util';
+
+const DEFAULT_REQUIREMENTS = fileURLToPath(new URL('../skills/managing-d2h-toolchain/environment-requirements.json', import.meta.url));
+const VERSION_TOOLS = ['node', 'python', 'git', 'npm', 'java', 'python-json5', 'appgraph', 'droid2hmos', 'hvigor', 'ohpm', 'devecocli'];
+
+function versionParts(value) {
+  if (typeof value !== 'string' || !/^\d+(?:\.\d+){0,3}$/.test(value)) throw new Error(`无效版本：${value}`);
+  const parts = value.split('.').map(Number);
+  if (parts.some(part => !Number.isSafeInteger(part))) throw new Error(`无效版本：${value}`);
+  return [...parts, ...Array(4 - parts.length).fill(0)];
+}
+
+function compareVersions(left, right) {
+  const a = versionParts(left);
+  const b = versionParts(right);
+  for (let index = 0; index < a.length; index++) {
+    if (a[index] !== b[index]) return a[index] < b[index] ? -1 : 1;
+  }
+  return 0;
+}
+
+export function loadRequirements(file = DEFAULT_REQUIREMENTS) {
+  const config = JSON.parse(fs.readFileSync(file, 'utf8').replace(/^\uFEFF/, ''));
+  if (config?.schemaVersion !== 1 || !config.tools || typeof config.tools !== 'object' || Array.isArray(config.tools)) {
+    throw new Error('版本配置必须包含 schemaVersion: 1 和 tools 对象');
+  }
+  for (const key of Object.keys(config)) {
+    if (!['schemaVersion', 'tools'].includes(key)) throw new Error(`未知配置字段：${key}`);
+  }
+  for (const key of Object.keys(config.tools)) {
+    if (!VERSION_TOOLS.includes(key)) throw new Error(`未知工具：${key}`);
+  }
+  for (const key of VERSION_TOOLS) {
+    if (!Object.hasOwn(config.tools, key)) throw new Error(`版本配置缺少工具：${key}；不约束版本请设为 null`);
+    const rule = config.tools[key];
+    if (rule === null) continue;
+    if (typeof rule !== 'object' || Array.isArray(rule) || !Object.keys(rule).length) throw new Error(`无效工具约束：${key}`);
+    for (const bound of Object.keys(rule)) {
+      if (!['minimum', 'maximumExclusive'].includes(bound)) throw new Error(`未知版本边界：${key}.${bound}`);
+      versionParts(rule[bound]);
+    }
+    if (rule.minimum && rule.maximumExclusive && compareVersions(rule.minimum, rule.maximumExclusive) >= 0) {
+      throw new Error(`版本区间为空：${key}`);
+    }
+  }
+  return config;
+}
+
+function constraintLabel(rule) {
+  return rule ? [rule.minimum && `>=${rule.minimum}`, rule.maximumExclusive && `<${rule.maximumExclusive}`].filter(Boolean).join(' ') : '仅检查可用性';
+}
+
+export function meetsVersionRule(output, rule, id = '') {
+  if (!rule) return true;
+  const match = output.match(/\d+\.\d+(?:\.\d+){0,2}/);
+  if (!match) return false;
+  let version = match[0];
+  if (id === 'java' && version.startsWith('1.')) version = version.slice(2);
+  return (!rule.minimum || compareVersions(version, rule.minimum) >= 0) &&
+    (!rule.maximumExclusive || compareVersions(version, rule.maximumExclusive) < 0);
+}
+
+export function resolveExecutable(command, env = process.env, platform = process.platform) {
+  // npm ships Unix shims beside .cmd files; Windows cannot spawn the shims.
+  const extensions = platform === 'win32' && !path.extname(command)
+    ? (env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';') : [''];
+  const directories = /[/\\]/.test(command) ? [''] : (env.PATH || '').split(platform === 'win32' ? ';' : ':');
+  for (const directory of directories) {
+    for (const extension of extensions) {
+      const candidate = directory ? path.join(directory, command + extension) : command + extension;
+      try {
+        if (!fs.statSync(candidate).isFile()) continue;
+        if (platform !== 'win32') fs.accessSync(candidate, fs.constants.X_OK);
+        return path.resolve(candidate);
+      } catch { /* Try the next candidate. */ }
+    }
+  }
+  return command;
+}
+
+export function invocation(executable, args, platform = process.platform, env = process.env) {
+  const resolved = resolveExecutable(executable, env, platform);
+  if (/\.m?js$/i.test(resolved)) return [process.execPath, resolved, ...args];
+  if (platform === 'win32' && /\.(cmd|bat)$/i.test(resolved)) {
+    const quote = (value) => `'${String(value).replaceAll("'", "''")}'`;
+    const source = `& ${[resolved, ...args].map(quote).join(' ')}; exit $LASTEXITCODE`;
+    return ['powershell.exe', '-NoProfile', '-NonInteractive', '-EncodedCommand', Buffer.from(source, 'utf16le').toString('base64')];
+  }
+  return [resolved, ...args];
+}
+
+export async function probe(executable, args, timeout = 15, options = {}) {
+  const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'd2h-env-'));
+  const log = fs.openSync(path.join(directory, 'output.log'), 'w+');
+  const errorLog = fs.openSync(path.join(directory, 'error.log'), 'w+');
+  let exitCode = null;
+  let error = null;
+  try {
+    const [command, ...commandArgs] = invocation(executable, args);
+    await new Promise((resolve) => {
+      // Files and the exit event avoid waiting on inherited output handles.
+      const child = spawn(command, commandArgs, {
+        cwd: options.cwd || directory, windowsHide: true, detached: process.platform !== 'win32',
+        env: { ...process.env, DEVECO_CLI_SKIP_VERSION_CHECK: '1' }, stdio: ['ignore', log, errorLog],
+      });
+      const timer = setTimeout(() => {
+        error = 'timeout';
+        if (child.pid) {
+          if (process.platform === 'win32') {
+            spawnSync('taskkill.exe', ['/PID', String(child.pid), '/T', '/F'], { windowsHide: true, stdio: 'ignore', timeout: 5000 });
+          } else {
+            try { process.kill(-child.pid, 'SIGKILL'); } catch { /* Already exited. */ }
+          }
+        }
+        clearTimeout(timer);
+        resolve();
+      }, timeout * 1000);
+      child.once('error', (err) => { error ??= err.message; clearTimeout(timer); resolve(); });
+      child.once('exit', (code) => { exitCode = code; clearTimeout(timer); resolve(); });
+    });
+    const read = (descriptor) => {
+      const buffer = Buffer.alloc(65536);
+      const length = fs.readSync(descriptor, buffer, 0, buffer.length, 0);
+      return buffer.subarray(0, length).toString('utf8').trim();
+    };
+    const stdout = read(log);
+    const stderr = read(errorLog);
+    return { command: [executable, ...args], exitCode, ok: exitCode === 0 && !error, error, stdout, stderr, output: [stdout, stderr].filter(Boolean).join('\n') };
+  } catch (err) {
+    return { command: [executable, ...args], exitCode, ok: false, error: err.message, output: '' };
+  } finally {
+    fs.closeSync(log);
+    fs.closeSync(errorLog);
+    try { fs.rmSync(directory, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); }
+    catch { /* Windows scanners may retain a handle briefly; do not hide the probe result. */ }
+  }
+}
+
+function isDirectory(value) {
+  try { return Boolean(value && fs.statSync(value).isDirectory()); } catch { return false; }
+}
+
+function isFile(value) {
+  try { return Boolean(value && fs.statSync(value).isFile()); } catch { return false; }
+}
+
+export function firstDirectory(values) {
+  const found = values.find(isDirectory);
+  return found ? path.resolve(found) : null;
+}
+
+export function pythonJson5Required(source) {
+  function visit(directory) {
+    if (!isDirectory(directory)) return false;
+    return fs.readdirSync(directory, { withFileTypes: true }).some((entry) => {
+      if (['__pycache__', 'node_modules', '.git', 'tests'].includes(entry.name)) return false;
+      const file = path.join(directory, entry.name);
+      return entry.isDirectory() ? visit(file) : entry.name.endsWith('.py') &&
+        /^\s*(?:import\s+json5\b|from\s+json5\b)/m.test(fs.readFileSync(file, 'utf8'));
+    });
+  }
+  return visit(path.join(source, 'skills'));
+}
+
+export function parseDevEcoJson(output) {
+  // DevEco CLI 1.3.3 appends its updater notice to stdout even with --format json.
+  // Strip only that known trailing line; unrelated malformed output still fails.
+  return JSON.parse(output.replace(/\r?\n\s*New version [\w.+-]+ available, run `devecocli update` to upgrade\s*$/, '').trim());
+}
+
+export async function collect(options, { runner = probe, env = process.env, platform = process.platform, home = os.homedir(), directoryFinder = firstDirectory, nodeVersion = process.version } = {}) {
+  const requirementsFile = path.resolve(options.requirementsFile || DEFAULT_REQUIREMENTS);
+  const requirements = loadRequirements(requirementsFile);
+  const ruleFor = id => requirements.tools[id];
+  const checks = [];
+  const add = (id, required, passed, summary, remediation = '', evidence = [], skipped = false) => {
+    checks.push({ id, required, status: skipped ? 'skipped' : passed ? 'passed' : required ? 'failed' : 'warning', summary,
+      remediation: passed ? '' : remediation, evidence });
+  };
+  const tool = async (id, executable, params, remediation, predicate = () => true) => {
+    const result = await runner(executable, params, options.timeout);
+    const rule = ruleFor(id);
+    const passed = result.ok && predicate(result.output) && meetsVersionRule(result.output, rule, id);
+    const summary = result.output.split(/\r?\n/)[0] || result.error || '命令未成功';
+    add(id, true, passed, `${summary}${rule ? `（要求 ${constraintLabel(rule)}）` : ''}`,
+      `${remediation}${rule ? ` 版本须满足 ${constraintLabel(rule)}。` : ''}`, [result]);
+    return result;
+  };
+  add('node', true, meetsVersionRule(nodeVersion, ruleFor('node')), `${nodeVersion} (${process.execPath})（要求 ${constraintLabel(ruleFor('node'))}）`,
+    `请安装满足 ${constraintLabel(ruleFor('node'))} 的 Node.js，然后重新运行脚本。`);
+  await tool('git', 'git', ['--version'], '安装 Git 并将 git 加入 PATH。');
+  await tool('npm', 'npm', ['--version'], '使用 Node.js 自带的 npm，检查 PATH。');
+  await tool('java', 'java', ['-version'], '安装项目 Gradle/DevEco 所需 JDK，设置 JAVA_HOME 和 PATH；本检查不限定 JDK 主版本。');
+  // Python is a migration dependency, no longer a prerequisite to run this doctor.
+  const candidates = [...new Set([env.PYTHON_BINARY, platform === 'win32' ? 'python' : 'python3', 'python',
+    platform === 'darwin' ? '/opt/homebrew/bin/python3' : null, platform === 'darwin' ? '/usr/local/bin/python3' : null,
+    platform === 'darwin' ? '/opt/homebrew/anaconda3/bin/python3' : null].filter(Boolean))];
+  const pythonProbes = [];
+  let python = null;
+  for (const candidate of candidates) {
+    const result = await runner(candidate, ['--version'], options.timeout);
+    pythonProbes.push(result);
+    if (result.ok && meetsVersionRule(result.output, ruleFor('python'))) { python = candidate; break; }
+  }
+  add('python', true, Boolean(python), `${python ? `${pythonProbes.at(-1).output} (${python})` : '未找到符合要求的 Python'}（要求 ${constraintLabel(ruleFor('python'))}）`,
+    `安装满足 ${constraintLabel(ruleFor('python'))} 的 Python 并加入 PATH，或设置 PYTHON_BINARY 为解释器路径。`, pythonProbes);
+  if (pythonJson5Required(path.resolve(options.pluginRoot))) {
+    if (python) {
+      await tool('python-json5', python, ['-c', 'import json5; from importlib.metadata import version; print("json5 " + version("json5"))'],
+        `用检测到的 Python 安装：${platform === 'win32' ? '& ' : ''}'${python.replaceAll("'", platform === 'win32' ? "''" : "'\\''")}' -m pip install json5`);
+    } else {
+      add('python-json5', true, false, 'Python 不可用，尚未检查 json5', '安装 Python 后重新检查；使用同一解释器执行 -m pip install json5。', [], true);
+    }
+  }
+  for (const name of ['appgraph', 'droid2hmos']) {
+    await tool(name, name, ['--version'], '运行 managing-d2h-toolchain Skill 中的 node scripts/manage-toolchain.mjs install 安装精确版本；本地 npm link 需由开发者显式管理。');
+  }
+  const deveco = directoryFinder([env.DEVECO_STUDIO_HOME, env.DEVECO_HOME,
+    platform === 'darwin' ? '/Applications/DevEco-Studio.app/Contents' : null,
+    ...(platform === 'win32' ? ['C:/Program Files/Huawei/DevEco Studio', 'D:/Program Files/Huawei/DevEco Studio'] : [])]);
+  add('deveco', true, Boolean(deveco), deveco || '未找到 DevEco Studio', '安装 DevEco Studio，设置 DEVECO_STUDIO_HOME 为安装根目录（macOS 为 Contents）。');
+  for (const [id, variable, relative, fallback] of [
+    ['hvigor', 'DROID2HMOS_HVIGOR', 'tools/hvigor/bin/hvigorw.js', 'hvigorw'],
+    ['ohpm', 'DROID2HMOS_OHPM', 'tools/ohpm/bin/pm-cli.js', 'ohpm'],
+  ]) {
+    const bundled = deveco && path.join(deveco, relative);
+    await tool(id, env[variable] || (isFile(bundled) ? bundled : fallback), ['--version'], `安装 DevEco 配套工具；设置 ${variable} 为可执行文件或 JS 入口路径。`);
+  }
+  const sdk = directoryFinder([options.sdkPath, env.HARMONYOS_SDK_HOME, env.OHOS_SDK_HOME, env.DEVECO_SDK_HOME, deveco && path.join(deveco, 'sdk')]);
+  add('harmony-sdk-location', false, Boolean(sdk), sdk || '未发现声明 SDK 根目录', '设置 HARMONYOS_SDK_HOME 或 --sdk-path；实际声明有效性由 droid2hmos preflight 检查。');
+  const cli = env.DEVECO_CLI_BINARY || 'devecocli';
+  await tool('devecocli', cli, ['--version'], '安装 npm install -g @deveco/deveco-cli。');
+  const auth = await runner(cli, ['auth', 'status'], options.timeout);
+  const loggedIn = auth.ok && /Current user:\s*[^\r\n]+/i.test(auth.output) && !/Not logged in/i.test(auth.output);
+  add('devecocli-auth', true, loggedIn, loggedIn ? '已登录' : '未登录或无法确认登录状态',
+    '运行 droid2hmos auth login <android-project>，在浏览器完成授权；不要并发登录。',
+    [{ command: auth.command, exitCode: auth.exitCode, error: auth.error }]);
+  if (options.harmonyProject) {
+    const project = path.resolve(options.harmonyProject);
+    const versions = await runner(cli, ['check', 'compat', 'versions', '--format', 'json'], options.timeout, { cwd: project });
+    let available = [];
+    try { const value = parseDevEcoJson(versions.stdout ?? versions.output); available = Array.isArray(value.versions) ? value.versions.filter((v) => typeof v === 'string') : []; } catch { /* Keep diagnostic. */ }
+    add('harmony-sdk-compatibility', false, versions.ok && available.length > 0,
+      available.length ? `DevEco CLI 可识别 SDK：${available.join(', ')}` : '无法确认工程可用 SDK 版本',
+      '在 DevEco 中安装工程所需 SDK；构建与 API 兼容性仍由项目 preflight 验证。', [versions]);
+  }
+  if (options.androidProject) {
+    const root = path.resolve(options.androidProject);
+    add('android-source-root', true, ['settings.gradle', 'settings.gradle.kts', 'build.gradle', 'build.gradle.kts'].some((f) => isFile(path.join(root, f))),
+      root, '用 --android-project 指向包含 Gradle 配置标记的 Android 源码根目录；不要求 Wrapper 或 Android 编译环境。');
+  }
+  const result = checks.some((c) => c.required && c.status === 'failed') ? 'failed'
+    : checks.some((c) => c.required && c.status === 'skipped') ? 'incomplete' : 'passed';
+  return { schemaVersion: '1.0.0', createdAt: new Date().toISOString(), platform: `${platform} ${os.arch()} ${os.release()}`, result, checks,
+    requirementsFile, versionRequirements: requirements.tools,
+    scope: '主机依赖检查；不证明构建、签名、SDK API 匹配或端到端验收成功。' };
+}
+
+export function markdown(report) {
+  const escape = (value) => String(value).replaceAll('|', '\\|').replaceAll('\r', '').replaceAll('\n', '<br>');
+  return ['# Android → HarmonyOS 环境检查', '', `结果：**${report.result}**`, '', report.scope, '', `版本配置：${report.requirementsFile || ''}`, '',
+    '| 检查 | 必需 | 状态 | 说明 |', '| --- | --- | --- | --- |',
+    ...report.checks.map((c) => `| ${c.id} | ${c.required ? '是' : '否'} | ${c.status} | ${escape(c.summary)} |`),
+    '', '## 修复指导', '', ...report.checks.filter((c) => c.remediation).map((c) => `- **${c.id}**：${c.remediation}`), '',
+    '修复后重新运行本脚本。主机检查通过后，运行 `droid2hmos preflight <android-project>` 验证真实项目门禁；该命令可能初始化工程并执行构建。', ''].join('\n');
+}
+
+export function parseOptions(argv) {
+  const { values } = parseArgs({ args: argv, options: {
+    'plugin-root': { type: 'string' },
+    requirements: { type: 'string' },
+    'android-project': { type: 'string' }, 'harmony-project': { type: 'string' }, 'sdk-path': { type: 'string' },
+    timeout: { type: 'string', default: '15' }, 'output-dir': { type: 'string' }, help: { type: 'boolean', short: 'h' },
+  } });
+  if (!/^\d+$/.test(values.timeout) || Number(values.timeout) < 1 || Number(values.timeout) > 60) throw new Error('--timeout 必须为 1–60 的整数');
+  return { pluginRoot: values['plugin-root'] || fileURLToPath(new URL('../', import.meta.url)),
+    requirementsFile: values.requirements ? path.resolve(values.requirements) : DEFAULT_REQUIREMENTS,
+    androidProject: values['android-project'], sdkPath: values['sdk-path'],
+    harmonyProject: values['harmony-project'],
+    timeout: Number(values.timeout),
+    outputDir: path.resolve(values['output-dir'] || 'environment-report'), help: values.help };
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  let options;
+  try { options = parseOptions(argv); } catch (error) { console.error(error.message); return 2; }
+  if (options.help) {
+    console.log('用法：node scripts/check-environment.mjs [--plugin-root <path>] [--android-project <path>]\n  [--harmony-project <path>] [--sdk-path <path>] [--requirements <json>]\n  [--timeout <1–60 秒>] [--output-dir <path>]\n默认版本约束来自 skills/managing-d2h-toolchain/environment-requirements.json。只写报告，不自动安装依赖或修改配置。');
+    return 0;
+  }
+  const report = await collect(options);
+  fs.mkdirSync(options.outputDir, { recursive: true });
+  fs.writeFileSync(path.join(options.outputDir, 'environment.json'), JSON.stringify(report, null, 2) + '\n');
+  fs.writeFileSync(path.join(options.outputDir, 'environment.md'), markdown(report));
+  const passed = report.checks.filter((check) => check.status === 'passed').length;
+  const failures = report.checks.filter((check) => check.status === 'failed');
+  const warnings = report.checks.filter((check) => check.status === 'warning').length;
+  const skipped = report.checks.filter((check) => check.status === 'skipped').length;
+  const resultLabel = { passed: '通过', failed: '未通过', incomplete: '未完成' }[report.result];
+  console.log(`环境检查：${resultLabel}（通过 ${passed}，失败 ${failures.length}${warnings ? `，提醒 ${warnings}` : ''}${skipped ? `，未检查 ${skipped}` : ''}）`);
+  const statusLabels = { passed: '通过', failed: '未通过', warning: '提醒', skipped: '未检查' };
+  for (const check of report.checks) {
+    console.log(`[${statusLabels[check.status] || check.status}] ${check.id}：${check.summary}`);
+    if (check.status !== 'passed' && check.remediation) {
+      console.log(`  修复：${check.remediation}`);
+    }
+  }
+  console.log(`详细报告：${path.join(options.outputDir, 'environment.md')}`);
+  return report.result === 'failed' ? 1 : report.result === 'incomplete' ? 2 : 0;
+}
+
+if (process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url) {
+  try { process.exitCode = await main(); } catch (error) { console.error(`环境检查失败：${error.message}`); process.exitCode = 1; }
+}