@buaa_smat/hometrans 0.1.10 → 0.1.11

package/dist/cli/config.js

@@ -17,16 +17,15 @@ export async function configCommand() {
     console.log(`  Path: ${configPath}`);
     console.log('');
     // User parameters
-    const maskedKey = config.env.TEST_API_KEY
-        ? config.env.TEST_API_KEY.slice(0, 4) +
-            '***' +
-            config.env.TEST_API_KEY.slice(-4)
-        : '(not set)';
+    const mask = (key) => key ? key.slice(0, 4) + '***' + key.slice(-4) : '(not set)';
     console.log('  Parameters:');
-    console.log(`    OHOS_SDK_PATH : ${config.env.OHOS_SDK_PATH || '(not set)'}`);
-    console.log(`    HMS_SDK_PATH  : ${config.env.HMS_SDK_PATH || '(not set)'}`);
-    console.log(`    TEST_API_KEY  : ${maskedKey}`);
-    console.log(`    TOOL_PATH     : ${config.env.TOOL_PATH || '(not set)'}`);
+    console.log(`    DEVECO_SDK_HOME : ${config.env.DEVECO_SDK_HOME || '(not set)'}`);
+    console.log(`    DEVECO_PATH     : ${config.env.DEVECO_PATH || '(not set)'} (derived)`);
+    console.log(`    OHOS_SDK_PATH   : ${config.env.OHOS_SDK_PATH || '(not set)'} (derived)`);
+    console.log(`    HMS_SDK_PATH    : ${config.env.HMS_SDK_PATH || '(not set)'} (derived)`);
+    console.log(`    TEST_API_KEY    : ${mask(config.env.TEST_API_KEY)}`);
+    console.log(`    GLM_API_KEY     : ${mask(config.env.GLM_API_KEY)}`);
+    console.log(`    TOOL_PATH       : ${config.env.TOOL_PATH || '(not set)'}`);
     console.log('');
     // Full config content
     console.log('  Full Content:');

package/dist/cli/init.js

@@ -7,13 +7,14 @@
  */
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import os from 'node:os';
+import { execFileSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import chalk from 'chalk';
 import figlet from 'figlet';
 import inquirer from 'inquirer';
+import { parseTree, modify, applyEdits } from 'jsonc-parser';
 import { setupMcpForAllEditors } from './mcp-setup.js';
-import { expandHome, getConfigPath, getToolsDir, loadHomeTransConfig, saveHomeTransConfig, } from './config-store.js';
+import { deriveSdkPaths, expandHome, getConfigPath, getToolsDir, loadHomeTransConfig, saveHomeTransConfig, } from './config-store.js';
 function ensureChalkColor() {
     if (process.stdout.isTTY && chalk.level === 0) {
         chalk.level = 1;
@@ -130,6 +131,70 @@ async function refreshAutotestConfig(autotestDir, apiKey) {
         ? `autotest config.yaml seeded + api_key filled`
         : `autotest config.yaml api_key refreshed`;
 }
+const UI_ALIGN_SKILL = 'hmos-incremental-ui-align';
+/**
+ * Initialize / refresh `<skillsDir>/hmos-incremental-ui-align/config.json`
+ * in an editor's installed skills dir — same semantics as the autotest
+ * config.yaml handling:
+ *   - If config.json does not exist, seed it from config-example.json.
+ *   - If it exists, surgically overwrite ONLY the `glm_api_key` and
+ *     `hmos_sdk_dir` values (via jsonc edits), preserving every other
+ *     field the user has set. `hmos_sdk_dir` = `<DEVECO_SDK_HOME>/default`.
+ *
+ * Returns a status string for the result summary, or null if nothing was
+ * done (skill not installed there, or no values to write into an existing file).
+ */
+export async function refreshUiAlignConfig(skillsDir, glmApiKey, hmosSdkDir) {
+    const skillDir = path.join(skillsDir, UI_ALIGN_SKILL);
+    const examplePath = path.join(skillDir, 'config-example.json');
+    const configPath = path.join(skillDir, 'config.json');
+    const hasExample = await fs
+        .access(examplePath)
+        .then(() => true)
+        .catch(() => false);
+    if (!hasExample)
+        return null;
+    let seeded = false;
+    const hasConfig = await fs
+        .access(configPath)
+        .then(() => true)
+        .catch(() => false);
+    if (!hasConfig) {
+        await fs.copyFile(examplePath, configPath);
+        seeded = true;
+    }
+    const updates = [];
+    if (glmApiKey)
+        updates.push(['glm_api_key', glmApiKey]);
+    if (hmosSdkDir)
+        updates.push(['hmos_sdk_dir', hmosSdkDir]);
+    if (updates.length === 0) {
+        return seeded
+            ? `${UI_ALIGN_SKILL}/config.json seeded (glm_api_key / hmos_sdk_dir left empty)`
+            : null;
+    }
+    let raw = await fs.readFile(configPath, 'utf-8');
+    const parseErrors = [];
+    const tree = parseTree(raw, parseErrors);
+    if (!tree || tree.type !== 'object' || parseErrors.length > 0) {
+        // Corrupt config — never regenerate over user content; just report.
+        return `${UI_ALIGN_SKILL}/config.json NOT updated (file is not valid JSON — fix it manually)`;
+    }
+    const original = raw;
+    for (const [key, value] of updates) {
+        const edits = modify(raw, [key], value, {
+            formattingOptions: { tabSize: 2, insertSpaces: true },
+        });
+        raw = applyEdits(raw, edits);
+    }
+    if (raw !== original) {
+        await fs.writeFile(configPath, raw, 'utf-8');
+    }
+    const what = updates.map(([k]) => k).join(' + ');
+    return seeded
+        ? `${UI_ALIGN_SKILL}/config.json seeded + ${what} filled`
+        : `${UI_ALIGN_SKILL}/config.json ${what} refreshed`;
+}
 async function installSkillsTo(skillsRoot, targetDir) {
     let entries;
     try {
@@ -180,7 +245,7 @@ async function installAgentsTo(agentsRoot, targetDir) {
     }
     return installed;
 }
-async function installForEditor(editor, skillsRoot, agentsRoot, result) {
+async function installForEditor(editor, skillsRoot, agentsRoot, glmApiKey, hmosSdkDir, result) {
     const marker = expandHome(editor.markerDir);
     if (marker && !(await dirExists(marker))) {
         result.skipped.push(`${editor.name} (not installed)`);
@@ -197,6 +262,17 @@ async function installForEditor(editor, skillsRoot, agentsRoot, result) {
     catch (err) {
         result.errors.push(`${editor.name} skills: ${err.message}`);
     }
+    // Seed / refresh the incremental-ui-align per-skill config.json with the
+    // GLM key + SDK dir from ~/.hometrans/config.json (existing files: key-only update).
+    try {
+        const status = await refreshUiAlignConfig(skillsDir, glmApiKey, hmosSdkDir);
+        if (status) {
+            result.configured.push(`${editor.name} ${status}`);
+        }
+    }
+    catch (err) {
+        result.errors.push(`${editor.name} ${UI_ALIGN_SKILL}/config.json: ${err.message}`);
+    }
     try {
         const agents = await installAgentsTo(agentsRoot, agentsDir);
         if (agents.length > 0) {
@@ -207,12 +283,185 @@ async function installForEditor(editor, skillsRoot, agentsRoot, result) {
         result.errors.push(`${editor.name} agents: ${err.message}`);
     }
 }
+/**
+ * Display paths as full absolute OS-native paths (e.g. on Windows:
+ * `C:\Users\<you>\.claude\skills`) — no `~` abbreviation, no separator
+ * rewriting, so output matches what the user can copy into their shell.
+ */
 export function prettyHome(p) {
-    const home = os.homedir();
-    if (p.startsWith(home)) {
-        return '~' + p.slice(home.length).replace(/\\/g, '/');
+    return p;
+}
+/** Locate a command on PATH (`where` on Windows, `which` elsewhere). */
+function whichSync(cmd) {
+    const isWin = process.platform === 'win32';
+    try {
+        const out = execFileSync(isWin ? 'where' : 'which', [cmd], {
+            encoding: 'utf-8',
+            timeout: 5000,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        const lines = out.split('\n').map((l) => l.trim()).filter(Boolean);
+        return lines[0] || null;
+    }
+    catch {
+        return null;
+    }
+}
+function captureVersion(cmd, args) {
+    try {
+        const out = execFileSync(cmd, args, {
+            encoding: 'utf-8',
+            timeout: 5000,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        return out.split('\n')[0].trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+async function fileExists(p) {
+    try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Install hints shown when a tool is missing. */
+const TOOL_HINTS = {
+    deveco: 'set DEVECO_SDK_HOME via `ht init` (DevEco Studio install)',
+    adb: 'Android SDK platform-tools (needed for Android-device capture)',
+    hdc: 'ships with DevEco: <sdk>/default/openharmony/toolchains',
+    python: 'install Python >= 3.10 and add to PATH (UI-align capture/parse scripts)',
+    uv: 'https://docs.astral.sh/uv (AutoTest runs under uv)',
+    java: 'any JDK 17+, or reuse DevEco jbr: <deveco>/jbr/bin',
+    gitnexus: 'npm i -g gitnexus && gitnexus setup',
+};
+/**
+ * Detect external tools. `hdc` falls back to the DevEco toolchains dir and
+ * `java` to DevEco's bundled jbr when not on PATH, mirroring how the
+ * skills/agents themselves resolve them.
+ */
+async function detectEnvironment(env) {
+    const status = new Map();
+    const isWin = process.platform === 'win32';
+    const sdkOk = env.DEVECO_SDK_HOME ? await dirExists(env.DEVECO_SDK_HOME) : false;
+    status.set('deveco', {
+        found: sdkOk,
+        path: sdkOk ? env.DEVECO_SDK_HOME : undefined,
+    });
+    for (const cmd of ['adb', 'python', 'uv', 'gitnexus']) {
+        const p = whichSync(cmd);
+        const st = { found: !!p, path: p ?? undefined };
+        if (cmd === 'python' && p) {
+            const v = captureVersion('python', ['--version']);
+            if (v) {
+                st.note = v;
+                const m = v.match(/(\d+)\.(\d+)/);
+                if (m && (Number(m[1]) < 3 || (Number(m[1]) === 3 && Number(m[2]) < 10))) {
+                    st.note += '  (UI-align scripts require >= 3.10)';
+                }
+            }
+        }
+        status.set(cmd, st);
+    }
+    // hdc: PATH first, then DevEco toolchains.
+    let hdcPath = whichSync('hdc');
+    if (!hdcPath && sdkOk) {
+        const cand = path.join(env.DEVECO_SDK_HOME, 'default', 'openharmony', 'toolchains', isWin ? 'hdc.exe' : 'hdc');
+        if (await fileExists(cand))
+            hdcPath = cand;
+    }
+    status.set('hdc', { found: !!hdcPath, path: hdcPath ?? undefined });
+    // java: PATH first, then DevEco jbr.
+    let javaPath = whichSync('java');
+    let javaNote;
+    if (!javaPath && env.DEVECO_PATH) {
+        const cand = path.join(env.DEVECO_PATH, 'jbr', 'bin', isWin ? 'java.exe' : 'java');
+        if (await fileExists(cand)) {
+            javaPath = cand;
+            javaNote = 'via DevEco jbr';
+        }
+    }
+    status.set('java', { found: !!javaPath, path: javaPath ?? undefined, note: javaNote });
+    return status;
+}
+/**
+ * Which tools each skill/agent needs. `required` missing → BLOCKED;
+ * only `optional` missing → LIMITED. Kept in sync with the README
+ * "Per-skill environment requirements" matrix.
+ */
+const IMPACT_MATRIX = [
+    { name: 'hmos-spec-generate', kind: 'skill', required: ['gitnexus'], optional: [] },
+    { name: 'hmos-resources-convert', kind: 'skill', required: [], optional: ['java'], note: 'no java -> falls back to source res/' },
+    { name: 'hmos-batch-ui-align', kind: 'skill', required: ['python'], optional: ['adb'], note: 'adb only for page exploration' },
+    { name: 'hmos-incremental-ui-align', kind: 'skill', required: ['deveco', 'python', 'hdc', 'adb'], optional: [] },
+    { name: 'hmos-integration-test', kind: 'skill', required: ['deveco', 'uv', 'hdc'], optional: [] },
+    { name: 'hmos-fix-build-errors', kind: 'skill', required: ['deveco'], optional: [] },
+    { name: 'hmos-convert-pipeline', kind: 'skill', required: ['deveco'], optional: ['uv', 'hdc'], note: 'test stage skippable via skip-test' },
+    { name: 'logic-context-builder', kind: 'agent', required: [], optional: ['python'] },
+    { name: 'logic-coder', kind: 'agent', required: [], optional: ['python'] },
+    { name: 'spec-generator', kind: 'agent', required: ['gitnexus'], optional: [] },
+    { name: 'build-fixer', kind: 'agent', required: ['deveco'], optional: [] },
+    { name: 'code-reviewer', kind: 'agent', required: [], optional: ['deveco'] },
+    { name: 'review-fixer', kind: 'agent', required: [], optional: [] },
+    { name: 'self-tester', kind: 'agent', required: ['uv', 'hdc'], optional: [] },
+    { name: 'self-test-fixer', kind: 'agent', required: [], optional: [] },
+];
+/** Print detected tools + the per-skill/agent impact table. */
+export async function runEnvironmentCheck(env) {
+    console.log('');
+    console.log(chalk.blue('  Environment Check'));
+    const tools = await detectEnvironment(env);
+    const order = ['deveco', 'adb', 'hdc', 'python', 'uv', 'java', 'gitnexus'];
+    for (const name of order) {
+        const st = tools.get(name);
+        if (st.found) {
+            const note = st.note ? chalk.gray(`  (${st.note})`) : '';
+            console.log(`    ${chalk.green('+')} ${name.padEnd(9)} ${st.path ?? ''}${note}`);
+        }
+        else {
+            console.log(`    ${chalk.yellow('!')} ${name.padEnd(9)} ${chalk.yellow('not found')}  ${chalk.gray(TOOL_HINTS[name] ?? '')}`);
+        }
+    }
+    const missing = order.filter((n) => !tools.get(n).found);
+    console.log('');
+    console.log(chalk.blue('  Impact on skills/agents:'));
+    const nameW = 28;
+    console.log(chalk.gray(`    ${'Name'.padEnd(nameW)} ${'Kind'.padEnd(6)} ${'Status'.padEnd(8)} Missing`));
+    for (const row of IMPACT_MATRIX) {
+        const missReq = row.required.filter((t) => missing.includes(t));
+        const missOpt = row.optional.filter((t) => missing.includes(t));
+        let plain;
+        let color;
+        let parts;
+        if (missReq.length > 0) {
+            plain = 'BLOCKED';
+            color = chalk.red;
+            parts = [...missReq, ...missOpt.map((t) => `${t}(optional)`)];
+        }
+        else if (missOpt.length > 0) {
+            plain = 'LIMITED';
+            color = chalk.yellow;
+            parts = missOpt.map((t) => `${t}(optional)`);
+        }
+        else {
+            plain = 'OK';
+            color = chalk.green;
+            parts = [];
+        }
+        const noteStr = parts.length > 0 && row.note ? chalk.gray(`  — ${row.note}`) : '';
+        console.log(`    ${row.name.padEnd(nameW)} ${row.kind.padEnd(6)} ${color(plain.padEnd(8))} ${parts.join(', ')}${noteStr}`);
+    }
+    console.log('');
+    if (missing.length === 0) {
+        console.log(chalk.green('  All environment dependencies found — every skill/agent is fully usable.'));
+    }
+    else {
+        console.log(chalk.gray('  Install the missing tools above and re-run `ht init` to clear the impact list.'));
     }
-    return p.replace(/\\/g, '/');
 }
 async function detectInstalledEditors(editors) {
     const status = new Map();
@@ -309,33 +558,72 @@ export async function initCommand(options = {}) {
         const answers = await inquirer.prompt([
             {
                 type: 'input',
-                name: 'OHOS_SDK_PATH',
-                message: 'OHOS_SDK_PATH:',
-                default: config.env.OHOS_SDK_PATH || undefined,
+                name: 'DEVECO_SDK_HOME',
+                message: 'DEVECO_SDK_HOME (DevEco Studio SDK dir):',
+                default: config.env.DEVECO_SDK_HOME || undefined,
             },
             {
                 type: 'input',
-                name: 'HMS_SDK_PATH',
-                message: 'HMS_SDK_PATH:',
-                default: config.env.HMS_SDK_PATH || undefined,
+                name: 'TEST_API_KEY',
+                message: 'TEST_API_KEY (LLM API key used by the integration-test agent to run test cases):',
+                default: config.env.TEST_API_KEY || undefined,
             },
             {
                 type: 'input',
-                name: 'TEST_API_KEY',
-                message: 'TEST_API_KEY (for autotest config.yaml):',
-                default: config.env.TEST_API_KEY || undefined,
+                name: 'GLM_API_KEY',
+                message: 'GLM_API_KEY (LLM API key for the GLM phone-agent used in UI alignment):',
+                default: config.env.GLM_API_KEY || undefined,
             },
         ]);
-        config.env.OHOS_SDK_PATH = answers.OHOS_SDK_PATH.trim();
-        config.env.HMS_SDK_PATH = answers.HMS_SDK_PATH.trim();
+        const sdk = deriveSdkPaths(answers.DEVECO_SDK_HOME);
+        config.env.DEVECO_SDK_HOME = sdk.DEVECO_SDK_HOME;
+        config.env.DEVECO_PATH = sdk.DEVECO_PATH;
+        config.env.OHOS_SDK_PATH = sdk.OHOS_SDK_PATH;
+        config.env.HMS_SDK_PATH = sdk.HMS_SDK_PATH;
         config.env.TEST_API_KEY = answers.TEST_API_KEY.trim();
+        config.env.GLM_API_KEY = answers.GLM_API_KEY.trim();
         await saveHomeTransConfig(config);
+        // Echo the derived paths and validate each exists on disk; missing ones are
+        // a strong signal of a typo'd DEVECO_SDK_HOME or a broken DevEco install.
+        if (sdk.DEVECO_SDK_HOME) {
+            const checks = [
+                ['DEVECO_SDK_HOME', sdk.DEVECO_SDK_HOME],
+                ['DEVECO_PATH', sdk.DEVECO_PATH],
+                ['OHOS_SDK_PATH', sdk.OHOS_SDK_PATH],
+                ['HMS_SDK_PATH', sdk.HMS_SDK_PATH],
+            ];
+            console.log('');
+            console.log(chalk.blue('  Derived from DEVECO_SDK_HOME:'));
+            let missingCount = 0;
+            for (const [name, p] of checks) {
+                const exists = await dirExists(p);
+                if (!exists)
+                    missingCount++;
+                const mark = exists ? chalk.green('+') : chalk.yellow('!');
+                const note = exists ? '' : chalk.yellow('  (not found on disk)');
+                console.log(`    ${mark} ${name.padEnd(15)} : ${p}${note}`);
+            }
+            if (missingCount > 0) {
+                console.log('');
+                console.log(chalk.yellow('  ! Check DEVECO_SDK_HOME (it should be the "sdk" folder inside your DevEco Studio install)'));
+                console.log(chalk.yellow('    and re-run `ht init` after fixing it. Skills that build or'));
+                console.log(chalk.yellow('    review code will not work until these paths resolve.'));
+            }
+        }
     }
     catch (err) {
         if (isPromptAbort(err))
             abortInit();
         console.log(chalk.yellow('  Parameter prompts skipped (non-interactive mode).'));
     }
+    // Detect external tools (adb / hdc / python / uv / java / gitnexus + DevEco)
+    // and report which skills/agents are impacted by anything missing.
+    try {
+        await runEnvironmentCheck(config.env);
+    }
+    catch (err) {
+        console.log(chalk.yellow(`  ! environment check skipped: ${err.message}`));
+    }
     // Copy bundled tools/ into ~/.hometrans/tools and record env.TOOL_PATH.
     // Must run before the autotest config step below, which seeds config.yaml
     // into the installed tools dir (the location agents read via env.TOOL_PATH).
@@ -369,9 +657,13 @@ export async function initCommand(options = {}) {
     console.log('');
     const editorsToSetup = editors.filter((e) => selectedEditors.includes(e.name));
     const result = { configured: [], skipped: [], errors: [] };
+    // hmos_sdk_dir consumed by incremental-ui-align = <DEVECO_SDK_HOME>/default.
+    const hmosSdkDir = config.env.DEVECO_SDK_HOME
+        ? path.join(config.env.DEVECO_SDK_HOME, 'default')
+        : '';
     for (const editor of editorsToSetup) {
         console.log(chalk.blue(`  Configuring ${editor.name}...`));
-        await installForEditor(editor, skillsRoot, agentsRoot, result);
+        await installForEditor(editor, skillsRoot, agentsRoot, config.env.GLM_API_KEY, hmosSdkDir, result);
     }
     await setupMcpForAllEditors(editorsToSetup, result);
     console.log('');

package/dist/cli/mcp-setup.js

@@ -227,12 +227,8 @@ async function writeTomlSection(editor, result) {
     }
 }
 function prettyConfigPath(p) {
-    // 与 init.ts 中 prettyHome 行为一致，但避免循环引用：就地实现。
-    const home = process.env.HOME || process.env.USERPROFILE || '';
-    if (home && p.startsWith(home)) {
-        return '~' + p.slice(home.length).replace(/\\/g, '/');
-    }
-    return p.replace(/\\/g, '/');
+    // 与 init.ts 中 prettyHome 行为一致：完整绝对路径、OS 原生分隔符，不做 ~ 缩写。
+    return p;
 }
 async function setupOneEditor(editor, result) {
     const marker = expandHome(editor.markerDir);

package/dist/context/index.js

@@ -13,6 +13,29 @@ import {
 import fs from "node:fs/promises";
 import path from "node:path";
 import os from "node:os";
+function deriveSdkPaths(devecoSdkHome) {
+  const home = devecoSdkHome.trim().replace(/[\\/]+$/, "");
+  if (!home) {
+    return { DEVECO_SDK_HOME: "", DEVECO_PATH: "", OHOS_SDK_PATH: "", HMS_SDK_PATH: "" };
+  }
+  return {
+    DEVECO_SDK_HOME: home,
+    DEVECO_PATH: path.dirname(home),
+    OHOS_SDK_PATH: path.join(home, "default", "openharmony", "ets"),
+    HMS_SDK_PATH: path.join(home, "default", "hms", "ets")
+  };
+}
+function sdkHomeFromLegacyPaths(env) {
+  const tryStrip = (p, suffix) => {
+    if (!p) return "";
+    const norm = p.replace(/[\\/]+$/, "").split(/[\\/]/);
+    if (norm.length <= suffix.length) return "";
+    const tail = norm.slice(-suffix.length).map((s) => s.toLowerCase());
+    if (tail.join("/") !== suffix.join("/")) return "";
+    return norm.slice(0, -suffix.length).join(path.sep);
+  };
+  return tryStrip(env.OHOS_SDK_PATH, ["default", "openharmony", "ets"]) || tryStrip(env.HMS_SDK_PATH, ["default", "hms", "ets"]);
+}
 function getConfigDir() {
   return path.join(os.homedir(), ".hometrans");
 }
@@ -99,9 +122,12 @@ async function fileExists(p) {
 }
 function defaultEnv() {
   return {
+    DEVECO_SDK_HOME: "",
+    DEVECO_PATH: "",
     OHOS_SDK_PATH: "",
     HMS_SDK_PATH: "",
     TEST_API_KEY: "",
+    GLM_API_KEY: "",
     TOOL_PATH: ""
   };
 }
@@ -145,6 +171,26 @@ async function loadHomeTransConfig() {
   delete anyParsed.sdkPaths;
   delete anyParsed.params;
   delete anyParsed.tool_path;
+  let envDirty = false;
+  if (!config.env.DEVECO_SDK_HOME) {
+    const migrated = sdkHomeFromLegacyPaths(config.env);
+    if (migrated) {
+      config.env.DEVECO_SDK_HOME = migrated;
+      envDirty = true;
+    }
+  }
+  if (config.env.DEVECO_SDK_HOME) {
+    const derived = deriveSdkPaths(config.env.DEVECO_SDK_HOME);
+    for (const key of ["DEVECO_PATH", "OHOS_SDK_PATH", "HMS_SDK_PATH"]) {
+      if (!config.env[key]) {
+        config.env[key] = derived[key];
+        envDirty = true;
+      }
+    }
+  }
+  if (envDirty) {
+    await saveHomeTransConfig(config);
+  }
   const existingNames = new Set(config.editors.map((e) => e.name));
   const missingEditors = defaultEditors().filter(
     (e) => !existingNames.has(e.name)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buaa_smat/hometrans",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "HomeTrans (Android-to-HarmonyOS) skill + agent installer. Run `ht init` to distribute conversion skills and subagents into AI editors.",
   "license": "MIT",
   "repository": {

package/skills/hmos-convert-pipeline/SKILL.md

@@ -17,12 +17,17 @@ Parse `$ARGUMENTS` as positional tokens:
 
 - **Arg 1** (`android-project-path`): Path to the Android source project (required)
 - **Arg 2** (`harmonyos-project-path`): Path to the target HarmonyOS project directory (required)
-- **Arg 3** (`assets-output-path`): Directory to store all output/report files (required)
-- **Arg 4** (`max-rounds-review`): Maximum number of Stage 3→3a→3b code-review-fix rounds to run (optional, default `2`). Must be a positive integer `>= 1`.
-- **Arg 5** (`max-rounds-test`): Maximum number of Stage 4→4a→4b self-test rounds to run (optional, default `2`). Must be a positive integer `>= 1`.
-- **Arg 6** (`skip-test`): `true` or `false` (optional, default `false`). When `true`, skip Stage 4 / 4a / 4b (Self-Testing Loop) entirely. Use this when no real HarmonyOS device is available for on-device testing. To pass this arg, provide explicit values for Args 4 and 5 first.
+- **Arg 3** (`spec-file-path`): Path to the requirement spec document (required). This is the plan/spec that drives Stage 1 logic development and Stage 3 code review — both stages read it directly from this path.
+- **Arg 4** (`assets-output-path`): Directory to store all output/report files (optional). When omitted, default to `<harmonyos-project-path>/.hometrans_output` — create the directory if it does not exist.
+- **Arg 5** (`test-case-path`): Path to the self-test case file driving the Stage 4 self-testing loop (optional). When omitted, default to `OUTPUT/test_case.md`. If the resolved file does not exist, the Stage 4 loop is skipped (see Loop Setup).
+- **Arg 6** (`pre-test-case-path`): Path to the pre-test case file (optional). When omitted, default to `OUTPUT/pre_test_case.md`. Only passed to the self-tester when the resolved file exists.
+- **Arg 7** (`max-rounds-review`): Maximum number of Stage 3→3a→3b code-review-fix rounds to run (optional, default `2`). Must be a positive integer `>= 1`.
+- **Arg 8** (`max-rounds-test`): Maximum number of Stage 4→4a→4b self-test rounds to run (optional, default `2`). Must be a positive integer `>= 1`.
+- **Arg 9** (`skip-test`): `true` or `false` (optional, default `false`). When `true`, skip Stage 4 / 4a / 4b (Self-Testing Loop) entirely. Use this when no real HarmonyOS device is available for on-device testing.
 
-If any required argument is missing, ask the user before proceeding. If `max-rounds-review` or `max-rounds-test` is provided but is not a positive integer, ask the user before proceeding. If `skip-test` is provided but is not `true` or `false`, ask the user before proceeding.
+Args are positional: to pass any optional arg, provide explicit values for all optional args before it (e.g., passing `test-case-path` requires an explicit `assets-output-path`; passing `skip-test` requires explicit Args 4–8).
+
+If any required argument is missing, ask the user before proceeding. If `spec-file-path` does not exist or is not a readable file, ask the user before proceeding. If `max-rounds-review` or `max-rounds-test` is provided but is not a positive integer, ask the user before proceeding. If `skip-test` is provided but is not `true` or `false`, ask the user before proceeding.
 
 Define shorthand variables for the instructions below:
 
@@ -30,7 +35,10 @@ Define shorthand variables for the instructions below:
 |----------|---------|
 | `ANDROID` | android-project-path |
 | `HMOS` | harmonyos-project-path |
-| `OUTPUT` | assets-output-path (resolved or generated) |
+| `SPEC` | spec-file-path — requirement spec document, consumed directly by Stage 1 (`spec-file`) and Stage 3 (`test-case-path`) |
+| `OUTPUT` | assets-output-path; defaults to `HMOS/.hometrans_output` when not provided (created on demand) |
+| `TEST_CASE` | test-case-path; defaults to `OUTPUT/test_case.md` when not provided |
+| `PRE_TEST_CASE` | pre-test-case-path; defaults to `OUTPUT/pre_test_case.md` when not provided |
 | `MAX_ROUNDS_REVIEW` | max-rounds-review — positive integer (default `2`). Controls Stage 3→3a→3b code-review-fix loop. |
 | `MAX_ROUNDS_TEST`   | max-rounds-test — positive integer (default `2`). Controls Stage 4→4a→4b self-test loop. |
 | `SKIP_TEST` | skip-test — `true` or `false` (default `false`). When `true`, skip Stage 4 / 4a / 4b entirely (no real device available). |
@@ -147,7 +155,7 @@ Prompt format (applies to both Stage 1 and Stage 1a): ONLY the key-value lines b
    ```
    Agent(
      subagent_type="logic-context-builder",
-     prompt="harmonyos-project-path: HMOS\nspec-file: OUTPUT/plan.md\noutput-path: OUTPUT/logic"
+     prompt="harmonyos-project-path: HMOS\nspec-file: SPEC\noutput-path: OUTPUT/logic"
    )
    ```
 2. Verify `OUTPUT/logic/plan.md` exists.
@@ -200,7 +208,7 @@ For each `review_round` from `1..MAX_ROUNDS_REVIEW`, set `REVIEW_ROUND_DIR = OUT
    - `harmonyos-project-path`: `HMOS`
    - `commit-id`: For Round 1, use `REVIEW_COMMIT_ID`. For Round 2+, review the project holistically (omit `commit-id` or pass `none`) since fixes have modified the codebase beyond the original commit scope.
    - `output-path`: `REVIEW_ROUND_DIR`
-   - `test-case-path`: `OUTPUT/plan.md`
+   - `test-case-path`: `SPEC`
 3. If a valid `commit-id` is available, the agent will automatically call the `extract_commit_context` MCP tool to extract commit-scoped code context before reviewing. If the MCP call fails, the agent falls back to direct git-diff analysis. If no `commit-id` is available, the agent reviews the project holistically without commit-scoped extraction.
 4. The agent writes `REVIEW_ROUND_DIR/code-review-report.md` with per-scenario verdicts.
 5. **Extract defect stats**: Read `REVIEW_ROUND_DIR/code-review-report.md`, extract the verdict breakdown (PASS/PARTIAL/FAIL/UNABLE TO VERIFY counts) and overall verdict.
@@ -277,7 +285,7 @@ Treat Stage 4 → 4a → 4b as a loop that runs up to `MAX_ROUNDS_TEST` times.
 
 1. **Locate the initial HAP file**: Use the `.hap` mirrored to `OUTPUT/` by the Stage 3 review loop finalization (or from Stage 2 if the review loop did not produce one). The default location is `OUTPUT/entry-default-signed.hap`. If that file does not exist, search for `*-signed.hap` files in `OUTPUT/` and use the first match. If no `.hap` is found in `OUTPUT/`, fall back to searching `HMOS/entry/build/default/outputs/default/`.
 2. Store the resolved path as `CURRENT_HAP`.
-3. **`OUTPUT/test_case.md` existence guard**: If `OUTPUT/test_case.md` does not exist, mark Stage 4 / 4a / 4b as failed with note "No test case file available" and skip the loop entirely.
+3. **`TEST_CASE` existence guard**: If `TEST_CASE` does not exist, mark Stage 4 / 4a / 4b as failed with note "No test case file available" and skip the loop entirely.
 4. Initialize loop state:
    - `round = 1`
    - `rounds_executed = 0`
@@ -297,8 +305,8 @@ For each `round` from `1..MAX_ROUNDS_TEST`, set `ROUND_DIR = OUTPUT/round-{round
 3. Input (round 1):
    - `hap-path`: `CURRENT_HAP`
    - `output-path`: `OUTPUT` (the ROOT — the agent always writes here)
-   - `test-case-path`: `OUTPUT/test_case.md`
-   - `pre-test-case-path`: `OUTPUT/pre_test_case.md` (only include this line when the file exists)
+   - `test-case-path`: `TEST_CASE`
+   - `pre-test-case-path`: `PRE_TEST_CASE` (only include this line when the file exists)
    - `setup`: `true`
 4. Input (round 2+):
    - `hap-path`: `CURRENT_HAP`

package/skills/hmos-fix-build-errors/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: hmos-fix-build-errors
 description: Build a HarmonyOS project via CLI and automatically fix compile errors in a loop until the build succeeds. Default unsigned HAP; pass --signed to build a signed HAP (signing config must already exist in the project's build-profile.json5).
-argument-hint: <harmonyos-project-path> <deveco-studio-path> [--signed]
+argument-hint: <harmonyos-project-path> [deveco-studio-path] [--signed]
 allowed-tools: Agent, Read, Write, Edit, Glob, Grep, Bash
 type: tool
 domain: engineering
@@ -12,8 +12,8 @@ domain: engineering
 Automatically build a HarmonyOS NEXT project from the command line, parse compile errors, fix them, and retry — repeating until the build succeeds.
 
 - **HarmonyOS Project**: `$ARGUMENTS[0]` (the HarmonyOS project root, e.g. `D:/MyHmosApp`)
-- **DevEco Studio Path**: `$ARGUMENTS[1]` (DevEco Studio installation root, e.g. `D:/DevEco Studio`)
-- **--signed** (optional): `$ARGUMENTS[2]` — if set to `--signed`, the build produces a **signed HAP**. If omitted, the build produces an **unsigned HAP** (default).
+- **DevEco Studio Path** (optional): `$ARGUMENTS[1]` (DevEco Studio installation root, e.g. `D:/DevEco Studio`) — when omitted, resolved automatically (see Step 0.2)
+- **--signed** (optional): if any argument equals `--signed`, the build produces a **signed HAP**. If omitted, the build produces an **unsigned HAP** (default).
 
 ---
 
@@ -21,12 +21,20 @@ Automatically build a HarmonyOS NEXT project from the command line, parse compil
 
 1. **Verify project exists** — Check that `$ARGUMENTS[0]` contains a valid HarmonyOS project (look for `build-profile.json5`, `entry/src` directory, `oh-package.json5`).
 
-2. **Verify DevEco installation** — Check that `$ARGUMENTS[1]` contains:
+2. **Resolve `<deveco-path>`** — stop at the first source that yields a valid path:
+   1. `$ARGUMENTS[1]` if provided (and not `--signed`).
+   2. `~/.hometrans/config.json` (on Windows `%USERPROFILE%\.hometrans\config.json`): `env.DEVECO_PATH`; else parent dir of `env.DEVECO_SDK_HOME`; else strip the trailing `/sdk/default/openharmony/ets` from `env.OHOS_SDK_PATH` (legacy).
+   3. Environment variables, same precedence: `DEVECO_PATH` → parent of `DEVECO_SDK_HOME` → strip suffix from `OHOS_SDK_PATH`.
+   4. **Ask the user** for the DevEco Studio install path (suggest running `ht init` to persist it).
+
+   **Verify the resolved `<deveco-path>`** contains:
    - `tools/node/node.exe`
    - `tools/hvigor/bin/hvigorw.js`
    - `tools/ohpm/bin/ohpm`
    - `sdk/` directory
 
+   If verification fails for a config/env-sourced path, treat that source as invalid and continue down the list; if it fails for a user-supplied path, report what is missing and ask again.
+
 3. **Set up `local.properties`** — Ensure the project root has `local.properties` with:
    ```properties
    hwsdk.dir=<deveco-path>/sdk
@@ -40,7 +48,7 @@ Automatically build a HarmonyOS NEXT project from the command line, parse compil
    "<deveco-path>/tools/ohpm/bin/ohpm" install
    ```
 
-5. **Determine Build Mode** — Check if `$ARGUMENTS[2]` equals `--signed`:
+5. **Determine Build Mode** — Check if any argument equals `--signed` (it may be `$ARGUMENTS[1]` when the DevEco path is omitted, or `$ARGUMENTS[2]` when it is provided):
    - **If NOT `--signed`** → **Unsigned build mode**. Ensure `build-profile.json5` does NOT have `signingConfigs` or `signingConfig` references in products (remove them if present). Go to Step 1.
    - **If `--signed`** → **Signed build mode**. Proceed to Step 0.5 to validate signing config.