@buaa_smat/hometrans 0.1.14 → 0.1.16

package/dist/cli/init.js

@@ -13,7 +13,7 @@ import chalk from 'chalk';
 import figlet from 'figlet';
 import inquirer from 'inquirer';
 import { setupMcpForAllEditors } from './mcp-setup.js';
-import { deriveSdkPaths, expandHome, getConfigDir, getConfigPath, getToolsDir, loadHomeTransConfig, saveHomeTransConfig, } from './config-store.js';
+import { deriveSdkPaths, expandHome, getConfigDir, getConfigPath, getToolsDir, isPlaceholderApiKey, loadHomeTransConfig, saveHomeTransConfig, syncModelEnvIntoConfig, } from './config-store.js';
 import { persistEnvVars } from './env-vars.js';
 function ensureChalkColor() {
     if (process.stdout.isTTY && chalk.level === 0) {
@@ -88,176 +88,51 @@ function maskKey(key) {
         return key || '';
     return key.length <= 8 ? '***' : `${key.slice(0, 4)}***${key.slice(-4)}`;
 }
-/** Inline notes for each autotest field, shown in the table's Description column. */
-const AUTOTEST_FIELD_NOTES = {
-    name: '多模态(视觉)模型的名字',
-    base_url: '模型API服务的基础地址',
-    api_key: '用于模型API请求认证的令牌',
-    provider: '模型API服务的提供方标识，如openai',
-    temperature: '采样温度',
-    top_p: '核采样阈值',
-    frequency_penalty: '重复惩罚',
-    device_sn: '设备序列号；null 表示自动选用当前连接的设备',
-    ip: '设备连接 IP（hdc）',
-    port: '设备连接端口（hdc）',
-    device_log_level: '设备日志级别：debug/info/...',
-    max_steps: '单条用例最大执行步数',
-    verbose: '是否输出详细日志',
-    lang: '输出语言：zh/en',
-    enable_preprocess: '执行前是否先用 unified_model 把用例拆成步骤序列（多一次 LLM 调用，默认关）',
-    debug_mode: '调试会话：null 关闭 / memory 内存 / file 存盘并跑完后起调试服务(:5000)',
-};
-/** Visual width of a string in a monospace terminal (CJK / fullwidth glyphs = 2). */
-function displayWidth(s) {
-    let w = 0;
-    for (const ch of s) {
-        const cp = ch.codePointAt(0) ?? 0;
-        const wide = (cp >= 0x1100 && cp <= 0x115f) ||
-            (cp >= 0x2e80 && cp <= 0xa4cf) ||
-            (cp >= 0xac00 && cp <= 0xd7a3) ||
-            (cp >= 0xf900 && cp <= 0xfaff) ||
-            (cp >= 0xfe30 && cp <= 0xfe4f) ||
-            (cp >= 0xff00 && cp <= 0xff60) ||
-            (cp >= 0xffe0 && cp <= 0xffe6) ||
-            (cp >= 0x20000 && cp <= 0x3fffd);
-        w += wide ? 2 : 1;
-    }
-    return w;
-}
-/** padEnd by visual width so columns with CJK content still line up. */
-function padEndDisplay(s, width) {
-    return s + ' '.repeat(Math.max(0, width - displayWidth(s)));
-}
 /**
- * Render the current/default autotest block as a table so the user sees every
- * field, its current/default value, and a short description. Section label shows
- * only on the first row of each group for readability.
+ * Model Configuration step — configures the single multimodal (vision) LLM
+ * shared by BOTH the on-device self-test agent AND the UI-alignment phone-agent.
+ * Stored once in the `autotest.unified_model` block of ~/.hometrans/config.json
+ * and additionally exported as the HOMETRANS_MODEL_* machine environment
+ * variables (see maybePersistMachineEnv), so each runtime reads the same config:
+ *   - self_test_runner.py reads autotest.unified_model from config.json;
+ *   - app_feature_verify.py reads the HOMETRANS_MODEL_* env vars (falling back
+ *     to config.json).
+ * Prompts for the four essentials (api_key / name / base_url / provider);
+ * all other parameters (device / agent, temperature, …) keep their defaults —
+ * edit config.json to tune them.
  */
-function printAutotestTable(at) {
-    const fmt = (v) => (v === null ? 'null' : String(v));
-    const um = at.unified_model;
-    const data = [
-        ['unified_model', 'name', um.name],
-        ['unified_model', 'base_url', um.base_url],
-        ['unified_model', 'provider', um.provider],
-        ['unified_model', 'api_key', maskKey(um.api_key)],
-        ['unified_model', 'temperature', fmt(um.temperature)],
-        ['unified_model', 'top_p', fmt(um.top_p)],
-        ['unified_model', 'frequency_penalty', fmt(um.frequency_penalty)],
-        ['device', 'device_sn', fmt(at.device.device_sn)],
-        ['device', 'ip', at.device.ip],
-        ['device', 'port', fmt(at.device.port)],
-        ['device', 'device_log_level', at.device.device_log_level],
-        ['agent', 'max_steps', fmt(at.agent.max_steps)],
-        ['agent', 'verbose', fmt(at.agent.verbose)],
-        ['agent', 'lang', at.agent.lang],
-        ['agent', 'enable_preprocess', fmt(at.agent.enable_preprocess)],
-        ['agent', 'debug_mode', fmt(at.agent.debug_mode)],
-    ];
-    const header = ['Section', 'Field', 'Current/Default', 'Description'];
-    // Section label only on the first row of each group.
-    const rows = [];
-    let prevSection = '';
-    for (const [s, f, v] of data) {
-        rows.push([s === prevSection ? '' : s, f, v, AUTOTEST_FIELD_NOTES[f] ?? '']);
-        prevSection = s;
-    }
-    const cols = header.map((h) => displayWidth(h));
-    for (const r of rows) {
-        for (let i = 0; i < cols.length; i++) {
-            cols[i] = Math.max(cols[i], displayWidth(r[i]));
-        }
-    }
-    const border = (l, m, r) => `    ${l}` + cols.map((w) => '─'.repeat(w + 2)).join(m) + r;
-    const row = (cells) => '    │ ' + cells.map((c, i) => padEndDisplay(c, cols[i])).join(' │ ') + ' │';
-    console.log(chalk.gray(border('┌', '┬', '┐')));
-    console.log(chalk.gray(row(header)));
-    console.log(chalk.gray(border('├', '┼', '┤')));
-    for (const r of rows)
-        console.log(chalk.gray(row(r)));
-    console.log(chalk.gray(border('└', '┴', '┘')));
-}
-/**
- * Test Configuration step — configures the `autotest` block in
- * ~/.hometrans/config.json (used by the on-device self-test agent). Shows the
- * default content, then prompts for the model essentials. The api_key (formerly
- * TEST_API_KEY) is stored here and NOT written to the system environment;
- * self_test_runner.py reads it from config.json at run time.
- *
- * device / agent stay at their defaults (shown above) — edit config.json to tune.
- */
-async function promptTestConfig(config) {
-    const at = config.autotest;
-    const um = at.unified_model;
-    console.log('');
-    console.log(chalk.blue('  Test Configuration'));
-    printAutotestTable(at);
-    console.log(chalk.gray('  This step configures only the parameters prompted below; configure all other'));
-    console.log(chalk.gray(`  parameters in config.json: ${getConfigPath()}`));
+async function promptModelConfig(config) {
+    const um = config.autotest.unified_model;
     console.log('');
+    console.log(chalk.blue('  MultiModel LLM Configuration'));
     try {
         const answers = await inquirer.prompt([
             {
                 type: 'input',
-                name: 'api_key',
-                message: 'autotest api_key (LLM key the self-test agent uses to run test cases):',
-                default: um.api_key && um.api_key !== 'YOUR_API_KEY_HERE' ? um.api_key : undefined,
-            },
-            { type: 'input', name: 'name', message: 'model name:', default: um.name },
-            { type: 'input', name: 'base_url', message: 'base_url:', default: um.base_url },
-            {
-                type: 'input',
-                name: 'provider',
-                message: 'provider (openai / azure / ...):',
-                default: um.provider,
+                name: 'model_api_key',
+                message: 'model_api_key (multimodal LLM key for ui alignment + integration test):',
+                default: isPlaceholderApiKey(um.api_key) ? undefined : um.api_key,
             },
+            { type: 'input', name: 'model_name', message: 'model_name:', default: um.name },
+            { type: 'input', name: 'model_base_url', message: 'model_base_url:', default: um.base_url },
         ]);
-        if (answers.api_key.trim())
-            um.api_key = answers.api_key.trim();
-        if (answers.name.trim())
-            um.name = answers.name.trim();
-        if (answers.base_url.trim())
-            um.base_url = answers.base_url.trim();
-        if (answers.provider.trim())
-            um.provider = answers.provider.trim();
+        if (answers.model_api_key.trim())
+            um.api_key = answers.model_api_key.trim();
+        if (answers.model_name.trim())
+            um.name = answers.model_name.trim();
+        if (answers.model_base_url.trim())
+            um.base_url = answers.model_base_url.trim();
+        // provider is no longer prompted — default to openai when unset.
+        if (!um.provider || !um.provider.trim())
+            um.provider = 'openai';
+        // Mirror into config.env.HOMETRANS_MODEL_* so config.json stays consistent.
+        syncModelEnvIntoConfig(config);
         await saveHomeTransConfig(config);
-        const note = um.api_key && um.api_key !== 'YOUR_API_KEY_HERE'
-            ? `api_key ${maskKey(um.api_key)}`
-            : 'api_key left as placeholder — self-test will not run until it is set';
-        console.log(chalk.green(`  + autotest config saved (${note})`));
     }
     catch (err) {
         if (isPromptAbort(err))
             abortInit();
-        console.log(chalk.yellow('  Test configuration skipped (non-interactive mode).'));
-    }
-}
-/**
- * UI Migration Configuration step — configures the GLM key used by the
- * incremental UI-alignment skill's phone-agent. GLM_API_KEY is read from the OS
- * environment at run time (app_feature_verify.py), so it stays in config.env and
- * is persisted as a machine env var by maybePersistMachineEnv.
- */
-async function promptUiAlignConfig(config) {
-    console.log('');
-    console.log(chalk.blue('  UI Migration Configuration'));
-    console.log(chalk.gray('  GLM_API_KEY: Zhipu GLM key for the UI-alignment phone-agent (read from the OS env at run time).'));
-    try {
-        const answers = await inquirer.prompt([
-            {
-                type: 'input',
-                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.GLM_API_KEY = answers.GLM_API_KEY.trim();
-        await saveHomeTransConfig(config);
-    }
-    catch (err) {
-        if (isPromptAbort(err))
-            abortInit();
-        console.log(chalk.yellow('  UI migration configuration skipped (non-interactive mode).'));
+        console.log(chalk.yellow('  Model configuration skipped (non-interactive mode).'));
     }
 }
 async function installSkillsTo(skillsRoot, targetDir, skipNames = new Set()) {
@@ -287,7 +162,78 @@ async function installSkillsTo(skillsRoot, targetDir, skipNames = new Set()) {
     }
     return installed;
 }
-async function installAgentsTo(agentsRoot, targetDir, skipNames = new Set()) {
+/**
+ * Named ANSI/agent colors → `#RRGGBB`. DevEco Code and opencode reject the named
+ * form (`cyan`, `blue`, …) in agent frontmatter `color:` and only accept hex, so
+ * for those editors we rewrite the named value to its hex equivalent instead of
+ * dropping it — the agent keeps its color.
+ */
+const AGENT_COLOR_HEX = {
+    black: '#000000',
+    red: '#ff0000',
+    green: '#008000',
+    yellow: '#ffff00',
+    blue: '#0000ff',
+    magenta: '#ff00ff',
+    purple: '#800080',
+    cyan: '#00ffff',
+    white: '#ffffff',
+    gray: '#808080',
+    grey: '#808080',
+    orange: '#ffa500',
+    pink: '#ffc0cb',
+};
+/**
+ * Map a named `color:` in a markdown agent's YAML frontmatter to its `#RRGGBB`
+ * hex form. Only the leading frontmatter block is touched; an already-hex or
+ * unknown color is left untouched, as is a file without frontmatter.
+ */
+export function mapAgentMarkdownColorToHex(content) {
+    const fm = content.match(/^---\r?\n[\s\S]*?\r?\n---/);
+    if (!fm)
+        return content;
+    const block = fm[0];
+    const mapped = block.replace(/^(color:[ \t]*)(\S+)([ \t]*\r?\n)/m, (whole, prefix, value, suffix) => {
+        const hex = AGENT_COLOR_HEX[value.trim().toLowerCase()];
+        return hex ? `${prefix}"${hex}"${suffix}` : whole;
+    });
+    return mapped === block ? content : content.replace(block, mapped);
+}
+/**
+ * opencode-style editors (DevEco Code, OpenCode) only accept hex `color:` in
+ * agent frontmatter — they're exactly the ones using the OpenCode `{type,
+ * command:[]}` MCP format. Identify them by that format so no per-editor config
+ * flag is needed.
+ */
+function needsHexAgentColor(editor) {
+    return editor.mcp?.format === 'jsonc-command-array';
+}
+/** Copy one agent file, mapping the frontmatter color to hex for `.md` when requested. */
+async function copyAgentFile(src, dest, mapColorToHex) {
+    if (mapColorToHex && src.endsWith('.md')) {
+        const raw = await fs.readFile(src, 'utf-8');
+        await fs.writeFile(dest, mapAgentMarkdownColorToHex(raw), 'utf-8');
+    }
+    else {
+        await fs.copyFile(src, dest);
+    }
+}
+/** Recursively copy an agent subdirectory, mapping colors to hex in `.md` files. */
+async function copyAgentDirRecursive(src, dest, mapColorToHex) {
+    await fs.mkdir(dest, { recursive: true });
+    const entries = await fs.readdir(src, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = path.join(src, entry.name);
+        const destPath = path.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            await copyAgentDirRecursive(srcPath, destPath, mapColorToHex);
+        }
+        else {
+            await copyAgentFile(srcPath, destPath, mapColorToHex);
+        }
+    }
+}
+async function installAgentsTo(agentsRoot, targetDir, skipNames = new Set(), mapColorToHex = false) {
     let entries;
     try {
         entries = await fs.readdir(agentsRoot, { withFileTypes: true });
@@ -303,10 +249,10 @@ async function installAgentsTo(agentsRoot, targetDir, skipNames = new Set()) {
         const srcPath = path.join(agentsRoot, entry.name);
         const destPath = path.join(targetDir, entry.name);
         if (entry.isDirectory()) {
-            await copyDirRecursive(srcPath, destPath);
+            await copyAgentDirRecursive(srcPath, destPath, mapColorToHex);
         }
         else if (entry.isFile()) {
-            await fs.copyFile(srcPath, destPath);
+            await copyAgentFile(srcPath, destPath, mapColorToHex);
             if (entry.name.endsWith('.md')) {
                 installed.push(entry.name.slice(0, -3));
             }
@@ -426,7 +372,7 @@ async function installForEditor(editor, skillsRoot, agentsRoot, result) {
         result.skipped.push(`${editor.name} existing kept: ${skipSkills.size} skills, ${skipAgents.size} agents (new items installed)`);
     }
     try {
-        const agents = await installAgentsTo(agentsRoot, agentsDir, skipAgents);
+        const agents = await installAgentsTo(agentsRoot, agentsDir, skipAgents, needsHexAgentColor(editor));
         if (agents.length > 0) {
             result.configured.push(`${editor.name} agents (${agents.length} -> ${prettyHome(agentsDir)})`);
         }
@@ -666,7 +612,7 @@ function evaluateDependency(dep, spec, tools) {
 /** Print detected tools + the per-skill/agent impact table. */
 export async function runEnvironmentCheck(env) {
     console.log('');
-    console.log(chalk.blue('  Environment Check'));
+    console.log(chalk.cyan('  Environment Check'));
     const spec = await loadEnvRequirements();
     if (!spec)
         return;
@@ -675,20 +621,21 @@ export async function runEnvironmentCheck(env) {
     for (const name of order) {
         const st = tools.get(name);
         const tool = spec.tools[name];
+        const label = (tool.label ?? name).padEnd(12);
         if (st.found) {
             let note = st.note ?? '';
             if (st.version && tool.version && !versionInRange(st.version, tool.version)) {
                 note += `  (requires ${describeRange(tool.version)})`;
             }
             const noteStr = note ? chalk.gray(`  (${note})`) : '';
-            console.log(`    ${chalk.green('+')} ${name.padEnd(9)} ${st.path ?? ''}${noteStr}`);
+            console.log(`    ${chalk.green('+')} ${label} ${st.path ?? ''}${noteStr}`);
         }
         else {
-            console.log(`    ${chalk.yellow('!')} ${name.padEnd(9)} ${chalk.yellow('not found')}  ${chalk.gray(tool.hint ?? '')}`);
+            console.log(`    ${chalk.yellow('!')} ${label} ${chalk.yellow('not found')}  ${chalk.gray(tool.hint ?? '')}`);
         }
     }
     console.log('');
-    console.log(chalk.blue('  Impact on skills/agents:'));
+    console.log(chalk.cyan('  Impact on skills/agents:'));
     const nameW = 28;
     console.log(chalk.gray(`    ${'Name'.padEnd(nameW)} ${'Kind'.padEnd(6)} ${'Status'.padEnd(8)} Missing`));
     let allOk = true;
@@ -727,11 +674,8 @@ export async function runEnvironmentCheck(env) {
         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 (allOk) {
-        console.log(chalk.green('  All environment dependencies found — every skill/agent is fully usable.'));
-    }
-    else {
+    if (!allOk) {
+        console.log('');
         console.log(chalk.gray('  Install the missing tools above and re-run `ht init` to clear the impact list.'));
     }
 }
@@ -750,14 +694,14 @@ async function detectInstalledEditors(editors) {
 }
 /**
  * Config env keys that are useful as real OS environment variables (the SDK
- * paths + tool dir + GLM key). PATH entries for node/java/hdc are not included
- * here — those are documented as manual PATH setup.
+ * paths + tool dir). PATH entries for node/java/hdc are not included here —
+ * those are documented as manual PATH setup.
  *
- * TEST_API_KEY is intentionally absent: the self-test api_key now lives in the
- * `autotest` block of config.json (configured by the Test Configuration step)
- * and is read from there by self_test_runner.py — never from the system env.
- * GLM_API_KEY stays, because the UI-alignment phone-agent reads it from the OS
- * environment at run time.
+ * The multimodal model config (HOMETRANS_MODEL_*) is included too: its canonical
+ * store is the `autotest.unified_model` block, but those four fields are mirrored
+ * into config.env by syncModelEnvIntoConfig so this one list is the single source
+ * for both config.json's `env` block and the machine env vars. Shared by UI
+ * alignment and self-test.
  */
 export const MACHINE_ENV_KEYS = [
     'DEVECO_SDK_HOME',
@@ -765,7 +709,9 @@ export const MACHINE_ENV_KEYS = [
     'OHOS_SDK_PATH',
     'HMS_SDK_PATH',
     'HOMETRANS_TOOL_PATH',
-    'GLM_API_KEY',
+    'HOMETRANS_MODEL_API_KEY',
+    'HOMETRANS_MODEL_NAME',
+    'HOMETRANS_MODEL_BASE_URL',
 ];
 /** Mask API-key values for display; show paths in full. */
 function maskEnvValue(name, value) {
@@ -777,26 +723,43 @@ function maskEnvValue(name, value) {
 /**
  * Show the resolved config values that would become machine environment
  * variables, then ask Y/N before writing them (Windows: setx; macOS/Linux:
- * shell rc block). Non-interactive shells skip without changing anything.
- * Re-throws ExitPromptError so the caller can abort init on Ctrl-C.
+ * shell rc block). Variables already present in the OS environment with the
+ * exact same value are skipped — they are neither shown nor re-written, and if
+ * nothing needs updating the prompt is skipped entirely. Non-interactive shells
+ * skip without changing anything. Re-throws ExitPromptError so the caller can
+ * abort init on Ctrl-C.
  */
-async function maybePersistMachineEnv(env) {
-    const vars = MACHINE_ENV_KEYS.map((k) => [k, (env[k] ?? '').trim()]).filter(([, value]) => value.length > 0);
-    if (vars.length === 0)
+async function maybePersistMachineEnv(config) {
+    // Refresh the mirrored HOMETRANS_MODEL_* in config.env from autotest.unified_model
+    // (the Model Configuration step above just edited the latter), so config.env is
+    // the single source for both config.json and the machine env vars below.
+    syncModelEnvIntoConfig(config);
+    const env = config.env;
+    const allVars = MACHINE_ENV_KEYS.map((k) => [k, (env[k] ?? '').trim()]).filter(([, value]) => value.length > 0);
+    if (allVars.length === 0)
         return;
+    // Skip variables already set in the OS environment with the same value — no
+    // need to re-write them or re-ask. process.env reflects the environment this
+    // process launched with, so a prior `ht init` (seen from a fresh terminal)
+    // already shows up here.
+    const sameValue = ([name, value]) => (process.env[name] ?? '').trim() === value;
+    const alreadySet = allVars.filter(sameValue);
+    const vars = allVars.filter((v) => !sameValue(v));
+    if (vars.length === 0) {
+        console.log('');
+        console.log(chalk.green('  + Machine environment variables already set with the current values — nothing to add.'));
+        return;
+    }
     console.log('');
-    console.log(chalk.blue('  Add these to your machine environment variables?'));
-    console.log(chalk.gray(process.platform === 'win32'
-        ? '  (Windows: persisted via setx to your user environment)'
-        : '  (macOS/Linux: written as an export block to your shell profile)'));
+    console.log(chalk.blue('  Add these to your machine environment variables? Skills and MCP tools read these from the OS environment at runtime.'));
     for (const [name, value] of vars) {
         console.log(`    ${chalk.cyan(name)} = ${maskEnvValue(name, value)}`);
     }
-    console.log('');
-    console.log(chalk.yellow('  Recommended: skills and MCP tools read these from the OS environment at runtime.'));
-    console.log(chalk.gray('  If you choose No, they are NOT set as system variables — skills/tools that rely on\n' +
-        '  them (self-test, UI alignment, commit-context analysis) may fail until you set them\n' +
-        '  yourself or re-run `ht init`.'));
+    if (alreadySet.length > 0) {
+        console.log(chalk.gray(`    (${alreadySet.length} already set with the same value — skipped: ${alreadySet
+            .map(([name]) => name)
+            .join(', ')})`));
+    }
     let confirmed;
     try {
         const answers = await inquirer.prompt([
@@ -824,6 +787,199 @@ async function maybePersistMachineEnv(env) {
     const note = await persistEnvVars(vars);
     console.log(chalk.green(`  + Environment variables ${note}`));
 }
+/**
+ * Run `homegraph --version`. Returns the trimmed first output line on success
+ * (an empty string still counts as success — exit 0), or null when the command
+ * is missing or exits non-zero. On Windows the global npm bin is a `.cmd` shim,
+ * so the command is run through the shell there.
+ */
+function homegraphVersion() {
+    try {
+        const out = execFileSync('homegraph', ['--version'], {
+            encoding: 'utf-8',
+            timeout: 15000,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            shell: process.platform === 'win32',
+        });
+        return (out ?? '').split('\n').map((l) => l.trim()).filter(Boolean)[0] ?? '';
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Run `uv --version`. Returns the trimmed first output line on success (exit 0),
+ * or null when uv is missing / exits non-zero. Probes `uv` on PATH first, then
+ * the standalone installer's default location (`~/.local/bin/uv[.exe]`) — that
+ * binary exists right after a fresh install, before the current process PATH is
+ * refreshed, so verification works within the same `ht init` run.
+ */
+function uvVersion() {
+    const home = process.env.HOME || process.env.USERPROFILE || '';
+    const isWin = process.platform === 'win32';
+    const candidates = ['uv'];
+    if (home)
+        candidates.push(path.join(home, '.local', 'bin', isWin ? 'uv.exe' : 'uv'));
+    for (const cmd of candidates) {
+        try {
+            const out = execFileSync(cmd, ['--version'], {
+                encoding: 'utf-8',
+                timeout: 15000,
+                stdio: ['ignore', 'pipe', 'ignore'],
+            });
+            return (out ?? '').split('\n').map((l) => l.trim()).filter(Boolean)[0] ?? '';
+        }
+        catch {
+            // try next candidate
+        }
+    }
+    return null;
+}
+/**
+ * Node-CLI part of the Dependency Installation step — installs the global Node
+ * CLIs the spec-generation skill needs (step 2「生成需求规格」): `homegraph` plus
+ * `arkanalyzer` (arkanalyzer parses ArkTS `.ets` and must be installed globally
+ * alongside homegraph). Verifies the result with `homegraph --version`.
+ * Idempotent: if homegraph already reports a version, the install is skipped.
+ * Never throws — failures are reported and `ht init` continues. The
+ * "Dependency Installation" section header is printed once by the caller.
+ */
+async function installNodeDependencies() {
+    console.log(chalk.gray('  homegraph + arkanalyzer'));
+    // Idempotent: a working `homegraph --version` means the deps are already there.
+    const existing = homegraphVersion();
+    if (existing !== null) {
+        console.log(chalk.green(`  + homegraph already installed (${existing || 'version unknown'}) — skipping.`));
+        return;
+    }
+    if (!whichSync('npm')) {
+        console.log(chalk.yellow('  ! npm not found on PATH — cannot install homegraph / arkanalyzer.'));
+        console.log(chalk.gray('    Install Node.js (bundles npm), then run: npm install -g homegraph arkanalyzer'));
+        return;
+    }
+    let proceed = true;
+    try {
+        const answers = await inquirer.prompt([
+            {
+                type: 'confirm',
+                name: 'install',
+                message: 'Install homegraph + arkanalyzer globally now (npm install -g homegraph arkanalyzer)?',
+                default: true,
+            },
+        ]);
+        proceed = answers.install;
+    }
+    catch (err) {
+        if (isPromptAbort(err))
+            abortInit();
+        console.log(chalk.yellow('  Non-interactive: proceeding with install.'));
+    }
+    if (!proceed) {
+        console.log(chalk.yellow('  Skipped — install later with:'));
+        console.log(chalk.gray('    npm install -g homegraph arkanalyzer'));
+        return;
+    }
+    console.log(chalk.gray('  Running: npm install -g homegraph arkanalyzer ...'));
+    try {
+        // Use the bare command name (not a resolved path) so the Windows shell can
+        // resolve the `npm.cmd` shim; shell:true is required on Windows for that.
+        execFileSync('npm', ['install', '-g', 'homegraph', 'arkanalyzer'], {
+            stdio: 'inherit',
+            timeout: 5 * 60 * 1000,
+            shell: process.platform === 'win32',
+        });
+    }
+    catch (err) {
+        console.log(chalk.red(`  ! npm install failed: ${err.message}`));
+        console.log(chalk.gray('    Re-run manually: npm install -g homegraph arkanalyzer'));
+        return;
+    }
+    // Verify install: `homegraph --version` must return normally (exit 0).
+    const version = homegraphVersion();
+    if (version !== null) {
+        console.log(chalk.green(`  + homegraph installed & verified (${version || 'version unknown'}).`));
+    }
+    else {
+        console.log(chalk.yellow('  ! Installed, but `homegraph --version` did not return successfully.'));
+        console.log(chalk.gray('    Open a new terminal (PATH refresh), then verify: homegraph --version'));
+    }
+}
+/**
+ * uv part of the Dependency Installation step — uv is the only Python toolchain
+ * HomeTrans needs: every Python script runs via `uv run`, and uv provides the
+ * Python interpreter on demand (no standalone Python install required). Uses the
+ * official standalone installer (https://docs.astral.sh/uv/getting-started/installation/):
+ *   - Windows:     powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+ *   - macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh   (wget fallback)
+ * Idempotent: a working `uv --version` skips the install. Never throws —
+ * failures are reported and `ht init` continues. The "Dependency Installation"
+ * section header is printed once by the caller.
+ */
+async function installUv() {
+    console.log(chalk.gray('  uv'));
+    // Idempotent: a working `uv --version` means uv is already there.
+    const existing = uvVersion();
+    if (existing !== null) {
+        console.log(chalk.green(`  + uv already installed (${existing || 'version unknown'}) — skipping.`));
+        return;
+    }
+    const isWin = process.platform === 'win32';
+    const installCmdText = isWin
+        ? 'powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"'
+        : 'curl -LsSf https://astral.sh/uv/install.sh | sh';
+    const docs = 'https://docs.astral.sh/uv/getting-started/installation/';
+    let proceed = true;
+    try {
+        const answers = await inquirer.prompt([
+            {
+                type: 'confirm',
+                name: 'install',
+                message: `uv not found. Install it now via the official installer?\n    ${installCmdText}`,
+                default: true,
+            },
+        ]);
+        proceed = answers.install;
+    }
+    catch (err) {
+        if (isPromptAbort(err))
+            abortInit();
+        console.log(chalk.yellow('  Non-interactive: proceeding with install.'));
+    }
+    if (!proceed) {
+        console.log(chalk.yellow('  Skipped — install later with:'));
+        console.log(chalk.gray(`    ${installCmdText}`));
+        console.log(chalk.gray(`    Docs: ${docs}`));
+        return;
+    }
+    console.log(chalk.gray(`  Running: ${installCmdText} ...`));
+    try {
+        if (isWin) {
+            execFileSync('powershell', ['-ExecutionPolicy', 'ByPass', '-c', 'irm https://astral.sh/uv/install.ps1 | iex'], { stdio: 'inherit', timeout: 5 * 60 * 1000 });
+        }
+        else {
+            // `curl | sh` needs a shell to pipe; prefer curl, fall back to wget so the
+            // installer also works on minimal systems that ship only one of them.
+            const script = 'if command -v curl >/dev/null 2>&1; then curl -LsSf https://astral.sh/uv/install.sh | sh; ' +
+                'else wget -qO- https://astral.sh/uv/install.sh | sh; fi';
+            execFileSync('sh', ['-c', script], { stdio: 'inherit', timeout: 5 * 60 * 1000 });
+        }
+    }
+    catch (err) {
+        console.log(chalk.red(`  ! uv install failed: ${err.message}`));
+        console.log(chalk.gray(`    Re-run manually: ${installCmdText}`));
+        console.log(chalk.gray(`    Docs: ${docs}`));
+        return;
+    }
+    // Verify install: `uv --version` must return (PATH or standalone-install path).
+    const version = uvVersion();
+    if (version !== null) {
+        console.log(chalk.green(`  + uv installed & verified (${version || 'version unknown'}).`));
+    }
+    else {
+        console.log(chalk.yellow('  ! Installed, but `uv --version` did not return successfully.'));
+        console.log(chalk.gray('    Open a new terminal (PATH refresh), then verify: uv --version'));
+    }
+}
 export async function initCommand(options = {}) {
     ensureChalkColor();
     const banner = figlet.textSync('HomeTrans', { font: 'Standard' });
@@ -845,7 +1001,7 @@ export async function initCommand(options = {}) {
     // Generate an initial ~/.hometrans/config.json up front (first-use scenario):
     // loadHomeTransConfig writes a complete default file (editors + env + autotest)
     // when none exists, and saveHomeTransConfig flushes it again to be certain it is
-    // on disk before any later step (e.g. Test Configuration) points the user at it.
+    // on disk before any later step (e.g. Model Configuration) points the user at it.
     const configPath = getConfigPath();
     const configExisted = await pathExists(configPath);
     const config = await loadHomeTransConfig();
@@ -909,8 +1065,7 @@ export async function initCommand(options = {}) {
     }
     // --- User parameters (SDK paths) ---
     console.log('');
-    console.log(chalk.blue('  Parameter Configuration'));
-    console.log(chalk.gray('  (press Enter to keep current value or leave empty)\n'));
+    console.log(chalk.blue('  Harmony SDK Configuration'));
     try {
         const answers = await inquirer.prompt([
             {
@@ -935,16 +1090,12 @@ export async function initCommand(options = {}) {
                 ['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:'));
+            // Validate the derived paths on disk silently — the listing itself is not
+            // printed; only a warning surfaces when one or more paths fail to resolve.
             let missingCount = 0;
-            for (const [name, p] of checks) {
-                const exists = await dirExists(p);
-                if (!exists)
+            for (const [, p] of checks) {
+                if (!(await dirExists(p)))
                     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('');
@@ -959,15 +1110,37 @@ export async function initCommand(options = {}) {
             abortInit();
         console.log(chalk.yellow('  Parameter prompts skipped (non-interactive mode).'));
     }
-    // UI Migration Configuration — configure the GLM key for the UI-alignment
-    // phone-agent. Stays in config.env (read from the OS env at run time).
-    await promptUiAlignConfig(config);
-    // Test Configuration — configure the autotest block (self-test api_key etc.)
-    // in config.json. Replaces the old TEST_API_KEY env prompt; never written to
-    // the system environment.
-    await promptTestConfig(config);
-    // Detect external tools (adb / hdc / python / uv / java / gitnexus + DevEco)
+    // Model Configuration — configure the single multimodal LLM shared by UI
+    // alignment and self-test. Stored in autotest.unified_model (config.json) and
+    // exported as HOMETRANS_MODEL_* env vars by maybePersistMachineEnv below.
+    await promptModelConfig(config);
+    // Dependency Installation — auto-provisionable deps: the global npm CLIs the
+    // spec-generation skill needs (homegraph + arkanalyzer) and uv (the Python
+    // toolchain every script runs under). The section header is printed once here;
+    // each sub-install prints its own gray sub-line. Runs before the Environment
+    // Check so the check reflects anything freshly installed.
+    console.log('');
+    console.log(chalk.cyan('  Dependency Installation'));
+    try {
+        await installNodeDependencies();
+    }
+    catch (err) {
+        if (isPromptAbort(err))
+            abortInit();
+        console.log(chalk.yellow(`  ! homegraph / arkanalyzer install skipped: ${err.message}`));
+    }
+    try {
+        await installUv();
+    }
+    catch (err) {
+        if (isPromptAbort(err))
+            abortInit();
+        console.log(chalk.yellow(`  ! uv install skipped: ${err.message}`));
+    }
+    // Detect external tools (adb / hdc / uv / java / homegraph + DevEco)
     // and report which skills/agents are impacted by anything missing.
+    // (Python is no longer detected separately — every script runs via `uv run`,
+    // and uv provides the interpreter on demand.)
     try {
         await runEnvironmentCheck(config.env);
     }
@@ -976,36 +1149,21 @@ export async function initCommand(options = {}) {
     }
     // Copy bundled tools/ into ~/.hometrans/tools and record env.HOMETRANS_TOOL_PATH.
     // self_test_runner.py (under the installed tools dir) reads the autotest
-    // config from ~/.hometrans/config.json at run time — see promptTestConfig.
-    let installedToolPath = null;
+    // config from ~/.hometrans/config.json at run time — see promptModelConfig.
     try {
-        installedToolPath = await installTools(toolsRoot, config);
-        if (installedToolPath) {
-            console.log(chalk.green(`  + tools copied -> ${prettyHome(installedToolPath)}`));
-            console.log(chalk.gray(`    HOMETRANS_TOOL_PATH set in ${prettyHome(getConfigPath())}`));
-        }
+        await installTools(toolsRoot, config);
     }
     catch (err) {
         console.log(chalk.red(`  ! tools copy: ${err.message}`));
     }
-    // Copy env-requirements.json into ~/.hometrans, next to config.json, so the
-    // declared environment requirements live alongside the user's config.
-    try {
-        const envReqDest = await installEnvRequirements();
-        if (envReqDest) {
-            console.log(chalk.green(`  + env-requirements.json copied -> ${prettyHome(envReqDest)}`));
-        }
-    }
-    catch (err) {
-        console.log(chalk.red(`  ! env-requirements.json copy: ${err.message}`));
-    }
-    // (The autotest block in config.json was already configured by the Test
-    // Configuration step above; self_test_runner.py reads it at run time.)
+    // (The autotest.unified_model block in config.json was already configured by
+    // the Model Configuration step above; self_test_runner.py reads it at run time
+    // and the UI-alignment phone-agent reads the exported HOMETRANS_MODEL_* vars.)
     // Offer to persist the resolved config values as real OS environment
     // variables (Windows: setx; macOS/Linux: shell rc block). Shows what will be
     // written and asks Y/N first; runs after HOMETRANS_TOOL_PATH is finalized above.
     try {
-        await maybePersistMachineEnv(config.env);
+        await maybePersistMachineEnv(config);
     }
     catch (err) {
         if (isPromptAbort(err))
@@ -1016,7 +1174,7 @@ export async function initCommand(options = {}) {
     const editorsToSetup = editors.filter((e) => selectedEditors.includes(e.name));
     const result = { configured: [], skipped: [], errors: [] };
     for (const editor of editorsToSetup) {
-        console.log(chalk.blue(`  Configuring ${editor.name}...`));
+        console.log(chalk.cyan(`  Configuring ${editor.name}...`));
         await installForEditor(editor, skillsRoot, agentsRoot, result);
     }
     await setupMcpForAllEditors(editorsToSetup, result);