@harmonyos-arkts/d2h 0.1.2 → 0.1.5

package/scripts/check-environment.mjs

@@ -0,0 +1,321 @@
+#!/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 D2H_VERSION = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+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'], `运行 npx --yes @harmonyos-arkts/d2h@${D2H_VERSION} 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; }
+}

package/skills/android2hmos_resources_convert/SKILL.md

@@ -27,17 +27,40 @@ values 资源（strings/colors/dimens 的迁移）、布局、Lottie、字体明
 | Android XML Drawable（vector/shape/layer-list/selector）转 SVG | `references/xml-drawable-to-svg-rules.md` |
 | 修复 SVG 显示问题（空白/不可见/尺寸错误/残留 Android 语法） | `references/svg-fix-patterns.md` |
 
-## 输入
+## 输入与统一领域结果
 
 1. **Android 工程路径** — Android Gradle 工程根目录（含 `build.gradle` 或 `build.gradle.kts`）。
-2. **HarmonyOS 工程路径** — 由 Preflight 创建或复用的工程（见 `preparing-migration-workspace`），通常是迁移工作区下的 `ohos/`，或 `.migration/config.json` 中 `--harmony-project` 配置的路径。图片写入 `<harmony>/entry/src/main/resources/`。本 skill 不创建工程壳；`ohos/` 尚不存在时先运行 Preflight。
+2. **HarmonyOS 工程路径** — 由 Preflight 创建或复用的工程（见 `preparing-migration-workspace`），通常是迁移工作区下的 `ohos/`，或 `.migration/config.json` 中 `--harmony-project` 配置的路径。图片写入 `<harmony>/entry/src/main/resources/`。本 skill 不创建工程壳；`ohos/` 尚不存在时由调用方先完成 Preflight。
+
+始终返回统一领域结果：
+
+```json
+{
+  "status": "completed | partial | failed",
+  "changedFiles": [],
+  "sourceFiles": [],
+  "evidence": [],
+  "domainChecks": [],
+  "unresolved": [],
+  "verificationRequests": [],
+  "suggestedRemediation": [],
+  "details": {
+    "convertedResources": [],
+    "qualifierMappings": [],
+    "unmappedResources": [],
+    "unresolvedReferences": []
+  }
+}
+```
+
+`status` 只表示图片资源转换和静态完整性检查的领域状态，不代表工程已构建、设备显示已验证或迁移已完成。`changedFiles`、`sourceFiles`、`unmappedResources` 和 `unresolvedReferences` 必须列出真实路径或资源标识。构建、设备显示和交互影响核对写入 `verificationRequests`，由调用方选择执行方式。
 
 ## 工作流
 
 ### 第 1 步：校验输入
 
 1. 确认 Android 工程路径存在且含 `build.gradle` 或 `build.gradle.kts`。
-2. 通过 `droid2hmos status <ANDROID_PROJECT>` 或 `.migration/config.json` 确认 HarmonyOS 工程位置，并确认 `entry/src/main/resources/` 存在；不存在时停止并先补 Preflight，不要猜测工程结构。
+2. 通过 `droid2hmos status <ANDROID_PROJECT>` 或 `.migration/config.json` 确认 HarmonyOS 工程位置，并确认 `entry/src/main/resources/` 存在；不存在时返回 `failed`，把缺少工程壳写入 `unresolved` 和 `suggestedRemediation`，不要猜测工程结构或自行调度 Preflight。
 
 ### 第 2 步：确定资源来源
 
@@ -47,7 +70,7 @@ values 资源（strings/colors/dimens 的迁移）、布局、Lottie、字体明
 - 多模块工程同时检查其它模块目录
 - 使用 flavor source set 时一并纳入（如 `app/src/debug/res/`、`app/src/flavor/res/`）
 
-恒定从源码 `res/` 转换：仅由库依赖（AAR）提供的图片不在源码 `res/` 中，这类引用在报告中记为 unresolved，不尝试回收。
+恒定从源码 `res/` 转换：仅由库依赖（AAR）提供的图片不在源码 `res/` 中，这类引用在统一结果中记为 unresolved，不尝试回收。
 
 ### 第 3 步：清点与分类
 
@@ -60,7 +83,7 @@ values 资源（strings/colors/dimens 的迁移）、布局、Lottie、字体明
 | XML drawable：vector/shape/layer-list | `.xml`，根 `<vector>` / `<shape>` / `<layer-list>` | 转 SVG（第 4.2 步） |
 | XML drawable：selector | `.xml`，根 `<selector>` | 提取默认状态 → SVG（第 4.2 步） |
 | 自适应图标 | `.xml`，根 `<adaptive-icon>` | 转 layered-image JSON（第 4.3 步） |
-| ripple/animated-vector/animated-selector/transition/level-list 等 | `.xml`，对应根元素 | 不可映射 — 记入报告 |
+| ripple/animated-vector/animated-selector/transition/level-list 等 | `.xml`，对应根元素 | 不可映射 — 记入统一结果 |
 
 忽略 `values*/`、`layout*/`、`menu/`、`raw/`、`font/`、`xml/`、`anim*/`、`color/` — 超出范围。只有 `values*/colors.xml` 和 `values*/dimens.xml` 被读取，用于解析 drawable 内的 `@color:`/`@dimen:` 引用（第 4.4 步）。
 
@@ -70,7 +93,7 @@ values 资源（strings/colors/dimens 的迁移）、布局、Lottie、字体明
 
 **4.1 位图与 nine-patch → `media/`**
 - 拷贝到限定符映射后的 `media/` 目录（完整限定符算法见 image-conversion-rules.md）
-- `.9.png` → 重命名为 `<name>_9.png`（HarmonyOS 禁止资源文件名中含 `.`，仅允许最后扩展名分隔符）。nine-patch 拉伸语义丢失 — 报告中记录
+- `.9.png` → 重命名为 `<name>_9.png`（HarmonyOS 禁止资源文件名中含 `.`，仅允许最后扩展名分隔符）。nine-patch 拉伸语义丢失 — 在统一结果中记录
 
 **4.2 XML drawable → `media/` 中的 `.svg`**
 - 严格按 `references/xml-drawable-to-svg-rules.md` 执行 — 尤其是强制保留 `clip-path`、三分支 `fill` 规则和渐变处理
@@ -84,19 +107,19 @@ values 资源（strings/colors/dimens 的迁移）、布局、Lottie、字体明
 **4.4 解析 drawable 内引用**
 - SVG 填充/描边中的 `@color/name` → 从 `values*/colors.xml` 解析（沿引用链；兜底 `#000000` + 记录）
 - SVG 尺寸中的 `@dimen/name` → 从 `values*/dimens.xml` 解析（兜底：合理默认值 + 记录）
-- 未解析引用（库专属资源不在源码 `res/`）记入报告，绝不静默丢弃
+- 未解析引用（库专属资源不在源码 `res/`）记入统一结果，绝不静默丢弃
 
 ### 第 5 步：完整性校验
 
-1. 第 3 步发现的每个文件都有且只有一个结局：已转换，或在报告中列为 unmappable/unmapped
+1. 第 3 步发现的每个文件都有且只有一个结局：已转换，或在统一结果中列为 unmappable/unmapped
 2. 每个转换产物都实际存在于 HarmonyOS 工程
 3. 生成的 layered-image JSON 中每个 `$media:xxx` 引用都指向 `media/` 中存在的文件
 4. 每个转换后的 SVG 通过 `references/xml-drawable-to-svg-rules.md` 的自检
 5. HarmonyOS 工程已有 `.ets` 文件时，扫描 `$r('app.media.xxx')` 并核对每个引用的图片存在（已有 media 文件**不覆盖** — 合并，冲突记录）
 
-### 第 6 步：生成报告
+### 第 6 步：组装领域结果
 
-按 `maintaining-migration-report` 的轻量原则，把转换报告落盘到迁移工作区（如 `.migration/` 下）或直接向用户呈现，结构如下：
+把转换清单和静态校验结果写入统一领域结果；如需可读审计附件，可生成以下结构并把路径列入 `evidence`：
 
 ```
 # Android to HarmonyOS Image Conversion Report
@@ -134,15 +157,9 @@ values 资源（strings/colors/dimens 的迁移）、布局、Lottie、字体明
 - SVG self-checks passed: Yes/No
 ```
 
-影响行为的结论（不可映射资源、丢失的 nine-patch 语义、未解析引用）必须回流到对应报告分片的说明，或按 orchestrator 约定写入 `discoveries.json`；不要只留在一次性报告里。
-
-### 第 7 步：Git 检查点
+影响行为的结论（不可映射资源、丢失的 nine-patch 语义、未解析引用）必须进入 `unresolved`，并标明 `blocking`、来源、用户影响和建议补救。需要回流报告 ref 或 discoveries 的项通过结果交给调用方，本 skill 不直接更新迁移报告。
 
-一个连贯、已校验的转换批次完成后，按仓库约定创建检查点（只纳入 HarmonyOS 工程内的资源文件）：
-
-```text
-droid2hmos checkpoint create <ANDROID_PROJECT> --message <MESSAGE> --include <harmony>/entry/src/main/resources
-```
+转换完成后，将实际生成或修改的 HarmonyOS 资源写入 `changedFiles`，把对应 Android 源资源写入 `sourceFiles`；不要只返回计数。静态校验写入 `domainChecks`，待构建和设备核对写入 `verificationRequests`。
 
 ## 重要说明
 
@@ -152,6 +169,7 @@ droid2hmos checkpoint create <ANDROID_PROJECT> --message <MESSAGE> --include <ha
 - **转换恒定从源码 `res/` 出发**：仅库依赖（AAR）提供的图片不在其中；对它们的引用按 unresolved 报告，不做恢复。
 - 资源名保持 Android 原拼写 — 它们是标识符。
 - 解析 Android XML 时正确处理命名空间、注释和 CDATA；按 local name 匹配属性。
+- 本 skill 不更新迁移报告、不暂存或提交文件、不创建 checkpoint、不调用 `complete`，也不选择仓库级构建、测试或设备命令。调用方消费统一领域结果并决定外层动作。
 
 ## 与其他 skill 的关系
 
@@ -159,4 +177,4 @@ droid2hmos checkpoint create <ANDROID_PROJECT> --message <MESSAGE> --include <ha
 - **arkts-app-identity**：它处理 App 级身份资源（app.json5 图标字段、版本号、包名）；本 skill 负责 res/ 全量图片资产进 `media/`。启动器图标的位图/分层资产由本 skill 转换，app.json5 的接线归它。
 - **arkts-icon-sizing**：图片资产就位后，它修 `.ets` 消费侧丢失的 `.width()/.height()`；本 skill 只管资源侧。
 - **arkts-i18n**：values 资源（string.json 等）的迁移归它；本 skill 只把 colors.xml/dimens.xml 当查找源。
-- **maintaining-migration-report**：转换结论回流报告分片的轻量约定。
+- **maintaining-migration-report**：调用方可把本 skill 返回的行为影响项、源码和证据映射到报告分片；本 skill 不直接写报告。

package/skills/appgraph-rule-audit/SKILL.md

@@ -7,13 +7,13 @@ description: Review fresh AppGraph and SPEC results after Android analysis, iden
 
 Review the latest deterministic Android analysis and produce maintainable rule-improvement candidates. This is a read-only diagnostic step. Do not edit AppGraph, SPEC facts, Android source, rule packs, or analyzers.
 
-All `.migration/...` paths below live in the sibling migration workspace `<android-project>-migration/.migration/`. Fall back to the legacy `<android-project>/.migration/` only when the sibling workspace does not exist.
+All `.migration/...` paths below live in the sibling migration workspace `<android-project>-migration/.migration/`. Never fall back to the legacy `<android-project>/.migration/`; if the sibling workspace or required artifacts are absent, return a structured unavailable/stale result.
 
 ## Preconditions
 
-1. Run `droid2hmos analyze android <android-project>` successfully before this Skill.
+1. The caller must supply artifacts from a successful `droid2hmos analyze android <android-project>` run; this Skill does not run analysis itself.
 2. Locate `.migration/spec/index.json`, `.migration/spec/facts/`, and `.migration/appgraph/app-graph.json`.
-3. Check that the SPEC `generation.sourceRevision`, when present, matches the Android Git HEAD. Treat a mismatch or missing required artifact as stale analysis: write no recommendations and ask for a new analysis run.
+3. Check that the SPEC `generation.sourceRevision`, when present, matches the Android Git HEAD. Treat a mismatch or missing required artifact as stale analysis: write no recommendations and return the structured result below. Do not run analysis or ask the user whether to run it.
 4. Keep all source and generated data local. Network access is unnecessary.
 
 ## Review workflow
@@ -34,7 +34,25 @@ All `.migration/...` paths below live in the sibling migration workspace `<andro
 
 ## Outputs
 
-Create or replace:
+When analysis is missing or stale, return without creating or replacing opportunity reports:
+
+```json
+{
+  "status": "stale",
+  "workspace": "<android-project>-migration/.migration/",
+  "staleReasons": [],
+  "requiredAction": "reanalyze-android",
+  "expectedArtifacts": [
+    ".migration/spec/index.json",
+    ".migration/spec/facts/",
+    ".migration/appgraph/app-graph.json"
+  ]
+}
+```
+
+The caller consumes `requiredAction` and decides the workflow transition. This Skill does not invoke `droid2hmos analyze android`, pause for a user choice, or continue against legacy/stale artifacts.
+
+When inputs are fresh, create or replace:
 
 ```text
 .migration/rule-audit/rule-opportunities.json
@@ -55,4 +73,5 @@ When no evidence-backed rule improvement exists, write valid outputs with an emp
 - Do not turn host relationships into navigation edges.
 - Do not mark multiple targets as resolved.
 - Do not implement recommendations. A maintainer may later pass an accepted opportunity to the separate `appgraph-navigation-rules` Skill.
-- Audit failure is advisory and must not block HarmonyOS migration. Record the limitation and allow the orchestrator to continue to `report init`.
+- With fresh inputs, an audit execution failure is advisory: record the limitation and return it to the caller. Missing or stale analysis is not an audit failure; return `requiredAction: reanalyze-android` as defined above.
+- Do not advance an outer state, create a checkpoint, update the migration report, or invoke completion. Return findings or the stale result to the caller.