@xcanwin/manyoyo 7.1.5 → 8.0.1

package/lib/container-runtime.js

@@ -0,0 +1,121 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const INFO_TIMEOUT_MS = 3000;
+const VERSION_TIMEOUT_MS = 5000;
+const SUPPORTED_RUNTIMES = ['docker', 'podman'];
+
+function getPrivatePodmanPaths(homeDir = os.homedir()) {
+    const root = path.join(homeDir, '.manyoyo', 'runtime', 'podman');
+    return {
+        root,
+        bin: path.join(root, 'bin', 'podman'),
+        configHome: path.join(root, 'config'),
+        dataHome: path.join(root, 'data'),
+        containersConf: path.join(root, 'containers.conf')
+    };
+}
+
+function ensurePrivatePodmanConfig(paths) {
+    fs.mkdirSync(paths.configHome, { recursive: true });
+    fs.mkdirSync(paths.dataHome, { recursive: true });
+    if (!fs.existsSync(paths.containersConf)) {
+        const helperDir = JSON.stringify(path.dirname(paths.bin));
+        fs.writeFileSync(paths.containersConf, `[engine]\nhelper_binaries_dir = [${helperDir}]\n`);
+    }
+}
+
+function normalizeConfigured(configured) {
+    const value = String(configured || '').trim().toLowerCase();
+    if (!value || value === 'auto') return '';
+    if (!SUPPORTED_RUNTIMES.includes(value)) {
+        throw new Error(`containerRuntime 无效: ${configured}（可选 auto / docker / podman）`);
+    }
+    return value;
+}
+
+// 不启动任何子进程：用户显式配置 > 私有 Podman；都没有返回 null。
+function resolveForcedRuntime(options = {}) {
+    const configured = normalizeConfigured(options.configured);
+    if (configured) {
+        return { command: configured, env: {}, source: 'config' };
+    }
+    const paths = getPrivatePodmanPaths(options.homeDir);
+    if (fs.existsSync(paths.bin)) {
+        ensurePrivatePodmanConfig(paths);
+        return {
+            command: paths.bin,
+            env: {
+                XDG_CONFIG_HOME: paths.configHome,
+                XDG_DATA_HOME: paths.dataHome,
+                CONTAINERS_CONF: paths.containersConf
+            },
+            source: 'private-podman'
+        };
+    }
+    return null;
+}
+
+function defaultRun(command, args, options = {}) {
+    const result = spawnSync(command, args, {
+        encoding: 'utf-8',
+        stdio: 'pipe',
+        timeout: options.timeout,
+        env: options.env
+    });
+    if (result.error) throw result.error;
+    if (result.status !== 0) {
+        throw new Error(`${command} ${args.join(' ')} 退出码 ${result.status}`);
+    }
+    return result.stdout || '';
+}
+
+function succeeds(run, command, args, timeout) {
+    try {
+        run(command, args, { timeout });
+        return true;
+    } catch (e) {
+        return false;
+    }
+}
+
+/**
+ * 选择容器运行时。
+ * 优先级：containerRuntime 配置 > 私有 Podman > daemon 可用的 docker > daemon 可用的 podman
+ *        > 仅 --version 可用的第一个 > 抛错。
+ * @returns {{command: string, env: Object<string,string>, source: string}}
+ */
+function selectContainerRuntime(options = {}) {
+    const forced = resolveForcedRuntime(options);
+    if (forced) return forced;
+
+    const run = typeof options.run === 'function' ? options.run : defaultRun;
+    for (const name of SUPPORTED_RUNTIMES) {
+        if (succeeds(run, name, ['info'], INFO_TIMEOUT_MS)) {
+            return { command: name, env: {}, source: `${name}-daemon` };
+        }
+    }
+    for (const name of SUPPORTED_RUNTIMES) {
+        if (succeeds(run, name, ['--version'], VERSION_TIMEOUT_MS)) {
+            return { command: name, env: {}, source: 'version-only' };
+        }
+    }
+    throw new Error('未找到可用的容器运行时 (docker/podman not found)：请安装并启动 Docker Desktop 或 Podman。');
+}
+
+// 只给运行时子进程用：env 为空时返回 undefined（子进程照常继承 process.env）。
+function mergeRuntimeEnv(env, base = process.env) {
+    if (!env || Object.keys(env).length === 0) return undefined;
+    return { ...base, ...env };
+}
+
+module.exports = {
+    selectContainerRuntime,
+    resolveForcedRuntime,
+    getPrivatePodmanPaths,
+    mergeRuntimeEnv
+};

package/lib/doctor.js

@@ -7,35 +7,47 @@ function createCheck(code, status, summary, action = '', detail = '') {
     return { code, status, summary, action, detail };
 }
 
-function runDoctorChecks(options = {}) {
+// 卡死的 daemon（如无响应的 Docker Desktop）不能让诊断无限挂起
+const COMMAND_TIMEOUT_MS = 10000;
+
+// runCommand 可以是同步或异步执行器；serve 里传异步的，避免阻塞事件循环
+async function runDoctorChecks(options = {}) {
     const checks = [];
     const runCommand = typeof options.runCommand === 'function' ? options.runCommand : () => {
         throw new Error('未配置命令执行器');
     };
+    const selectRuntime = typeof options.selectRuntime === 'function' ? options.selectRuntime : () => {
+        throw new Error('未配置运行时选择器');
+    };
     let runtimeCommand = '';
+    let runtimeSource = null;
+    let runtimeEnv = {};
 
-    for (const candidate of (options.runtimeCandidates || ['docker', 'podman'])) {
+    try {
+        const selection = selectRuntime();
+        runtimeCommand = selection.command;
+        runtimeSource = selection.source;
+        runtimeEnv = selection.env || {};
+    } catch (error) {
+        checks.push(createCheck('RUNTIME_UNAVAILABLE', 'error', '未找到 Docker 或 Podman', '安装并启动 Docker Desktop 或 Podman。', error.message || ''));
+    }
+    if (runtimeCommand) {
+        let versionDetail = '';
         try {
-            const detail = String(runCommand(candidate, ['--version']) || '').trim();
-            runtimeCommand = candidate;
-            checks.push(createCheck('RUNTIME_AVAILABLE', 'ok', `检测到 ${candidate}`, '', detail));
-            break;
+            versionDetail = String(await runCommand(runtimeCommand, ['--version'], { env: runtimeEnv, timeout: COMMAND_TIMEOUT_MS }) || '').trim();
         } catch (error) {
-            // 尝试下一个受支持运行时。
+            // 版本信息只是补充，daemon 检查会给出真正的结论。
         }
-    }
-    if (!runtimeCommand) {
-        checks.push(createCheck('RUNTIME_UNAVAILABLE', 'error', '未找到 Docker 或 Podman', '安装并启动 Docker Desktop 或 Podman。'));
-    } else {
+        checks.push(createCheck('RUNTIME_AVAILABLE', 'ok', `容器运行时: ${runtimeCommand}（来源: ${runtimeSource}）`, '', versionDetail));
         try {
-            const detail = String(runCommand(runtimeCommand, ['info']) || '').trim();
+            const detail = String(await runCommand(runtimeCommand, ['info'], { env: runtimeEnv, timeout: COMMAND_TIMEOUT_MS }) || '').trim();
             checks.push(createCheck('DAEMON_AVAILABLE', 'ok', `${runtimeCommand} daemon 可用`, '', detail));
         } catch (error) {
             checks.push(createCheck('DAEMON_UNAVAILABLE', 'error', `${runtimeCommand} daemon 不可用`, `启动 ${runtimeCommand} daemon 后重试。`, error.message || ''));
         }
         try {
             const image = `${options.imageName || ''}:${options.imageVersion || ''}`;
-            const detail = String(runCommand(runtimeCommand, ['image', 'inspect', image]) || '').trim();
+            const detail = String(await runCommand(runtimeCommand, ['image', 'inspect', image], { env: runtimeEnv, timeout: COMMAND_TIMEOUT_MS }) || '').trim();
             checks.push(createCheck('IMAGE_AVAILABLE', 'ok', `镜像可用: ${image}`, '', detail));
         } catch (error) {
             checks.push(createCheck('IMAGE_MISSING', 'warning', '目标镜像尚不可用', '执行 manyoyo build，或拉取匹配镜像。', error.message || ''));
@@ -74,11 +86,62 @@ function runDoctorChecks(options = {}) {
     return {
         version: 1,
         runtimeCommand: runtimeCommand || null,
+        runtimeSource,
         ok: !checks.some(check => check.status === 'error'),
         checks
     };
 }
 
+async function attemptFix(handler) {
+    if (typeof handler !== 'function') {
+        return { attempted: false, fixed: false, message: '' };
+    }
+    try {
+        const result = await handler();
+        return { attempted: true, fixed: Boolean(result && result.fixed), message: String(result && result.message || '') };
+    } catch (error) {
+        return { attempted: true, fixed: false, message: String(error && error.message || error).split('\n')[0] };
+    }
+}
+
+/**
+ * 对 runDoctorChecks 的报告执行修复：每个未通过的检查项都带 fix: {attempted, fixed, message}。
+ * handlers: startRuntime / pullImage / createConfig / suggestPort，各返回 {fixed, message}。
+ */
+async function applyDoctorFixes(report, handlers = {}) {
+    const checks = report.checks.map(check => ({ ...check }));
+    const find = code => checks.find(check => check.code === code);
+
+    const daemon = find('DAEMON_UNAVAILABLE');
+    if (daemon) daemon.fix = await attemptFix(handlers.startRuntime);
+
+    const image = find('IMAGE_MISSING');
+    if (image) {
+        image.fix = daemon && !daemon.fix.fixed
+            ? { attempted: false, fixed: false, message: '需先修复容器运行时' }
+            : await attemptFix(handlers.pullImage);
+    }
+
+    const config = find('CONFIG_MISSING');
+    if (config) config.fix = await attemptFix(handlers.createConfig);
+
+    const port = find('PORT_OCCUPIED');
+    if (port) port.fix = await attemptFix(handlers.suggestPort);
+
+    checks.forEach(check => {
+        if (check.status !== 'ok' && !check.fix) {
+            check.fix = { attempted: false, fixed: false, message: '' };
+        }
+    });
+
+    return {
+        ...report,
+        ok: !checks.some(check => check.status === 'error' && !(check.fix && check.fix.fixed)),
+        checks
+    };
+}
+
 module.exports = {
-    runDoctorChecks
+    runDoctorChecks,
+    applyDoctorFixes
 };

package/lib/download-verified.js

@@ -0,0 +1,48 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { pipeline } = require('stream/promises');
+const { Readable } = require('stream');
+
+function sha256File(filePath) {
+    return new Promise((resolve, reject) => {
+        const hash = crypto.createHash('sha256');
+        fs.createReadStream(filePath)
+            .on('data', chunk => hash.update(chunk))
+            .on('error', reject)
+            .on('end', () => resolve(hash.digest('hex')));
+    });
+}
+
+/**
+ * 下载并校验 SHA256。缓存命中（文件存在且哈希一致）直接复用；
+ * 哈希不符一律删除并报错，绝不保留不可信文件。
+ */
+async function downloadVerified({ url, sha256, dest, fetchImpl = fetch, log = () => {} }) {
+    if (!/^[0-9a-f]{64}$/.test(sha256 || '')) {
+        throw new Error(`缺少有效的 SHA256: ${url}`);
+    }
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    if (fs.existsSync(dest) && await sha256File(dest) === sha256) {
+        log(`缓存命中: ${path.basename(dest)}`);
+        return dest;
+    }
+    log(`下载: ${url}`);
+    const response = await fetchImpl(url, { redirect: 'follow' });
+    if (!response.ok || !response.body) {
+        throw new Error(`下载失败 (${response.status}): ${url}`);
+    }
+    const partial = `${dest}.partial`;
+    await pipeline(Readable.fromWeb(response.body), fs.createWriteStream(partial));
+    const actual = await sha256File(partial);
+    if (actual !== sha256) {
+        fs.rmSync(partial, { force: true });
+        throw new Error(`SHA256 校验失败: ${path.basename(dest)}（期望 ${sha256}，实际 ${actual}）`);
+    }
+    fs.renameSync(partial, dest);
+    return dest;
+}
+
+module.exports = { sha256File, downloadVerified };

package/lib/error-hints.js

@@ -0,0 +1,96 @@
+'use strict';
+
+// 原始运行时/系统错误 -> “原因 + 下一步”。新增映射只改这里。
+const RULES = [
+    {
+        code: 'PODMAN_MACHINE_UNAVAILABLE',
+        pattern: /Cannot connect to Podman|unable to connect to Podman socket|podman machine start|podman system connection/i,
+        describe: ({ command }) => ({
+            reason: `当前 ${command} 命令正在连接 Podman machine，但连接不可用。`,
+            action: '请先在宿主机执行: podman machine start'
+        })
+    },
+    {
+        code: 'DOCKER_DAEMON_UNAVAILABLE',
+        pattern: /Cannot connect to the Docker daemon|docker daemon is not running|Is the docker daemon running/i,
+        describe: ({ command }) => ({
+            reason: `当前 ${command} 命令无法连接容器运行时。`,
+            action: '请先启动 Docker Desktop / Docker daemon，或确认 Podman machine 已启动。'
+        })
+    },
+    {
+        code: 'IMAGE_PULL_RATE_LIMITED',
+        pattern: /toomanyrequests|too many requests|rate limit/i,
+        describe: ({ imageRef }) => ({
+            reason: `拉取镜像${imageRef ? ` ${imageRef}` : ''}被镜像仓库限流（请求过于频繁）。`,
+            action: '稍等几分钟后重试；若在公共网络/代理出口下反复出现，换一个网络，或用离线安装包里自带的镜像。'
+        })
+    },
+    {
+        code: 'IMAGE_UNAUTHORIZED',
+        pattern: /\bunauthorized\b|authentication required|permission_denied|denied: installation not allowed/i,
+        describe: ({ imageRef }) => ({
+            reason: `镜像仓库拒绝了对${imageRef ? ` ${imageRef} ` : ' 镜像'}的匿名访问（未授权）。`,
+            action: '确认镜像名与版本无误；若是私有仓库，先执行 docker login / podman login；公开镜像仍报此错时，可能是过期的登录凭据，执行 logout 后重试。'
+        })
+    },
+    {
+        code: 'IMAGE_NOT_FOUND',
+        pattern: /manifest unknown|repository does not exist|pull access denied|requested access to the resource is denied|name unknown|not found: manifest/i,
+        describe: ({ imageRef }) => ({
+            reason: `镜像${imageRef ? ` ${imageRef}` : ''}不存在（仓库里没有这个版本，或没有访问权限）。`,
+            action: '检查 ~/.manyoyo/manyoyo.json 的 imageName / imageVersion；或先执行 manyoyo build --iv <x.y.z-后缀> 本地构建。'
+        })
+    },
+    {
+        code: 'IMAGE_PULL_FAILED',
+        pattern: /localhost\/v2|pinging container registry|connection refused|dial tcp .*:443|TLS handshake timeout|no such host|i\/o timeout/i,
+        describe: ({ imageRef }) => ({
+            reason: `拉取镜像${imageRef ? ` ${imageRef}` : ''}失败，无法连接镜像仓库。`,
+            action: '检查网络或代理后重试（国内网络可能需要代理或镜像加速）；也可以先执行 manyoyo build 本地构建。'
+        })
+    },
+    {
+        code: 'PORT_IN_USE',
+        pattern: /port is already allocated|address already in use|EADDRINUSE/i,
+        describe: ({ port }) => ({
+            reason: `端口${port ? ` ${port}` : ''}已被占用。`,
+            action: '换一个端口，或关闭占用该端口的程序后重试。'
+        })
+    },
+    {
+        code: 'XCODE_CLT_MISSING',
+        // 只认真正的 CLT 缺失输出，不能因为输出里提到 xcode-select 就误判
+        pattern: /xcode-select: (error|note)|invalid active developer path|xcrun: error|command line tools are (not installed|required)/i,
+        describe: () => ({
+            reason: '该功能需要 Xcode 命令行工具。',
+            action: '请在终端执行: xcode-select --install，安装完成后重试。'
+        })
+    }
+];
+
+/**
+ * @param {string} text 命令失败的原始输出
+ * @param {{command?: string, imageRef?: string, port?: number|string}} [context]
+ * @returns {{code: string, reason: string, action: string}|null}
+ */
+function describeError(text, context = {}) {
+    const raw = String(text || '');
+    const ctx = { command: 'docker', imageRef: '', port: '', ...context };
+    for (const rule of RULES) {
+        if (rule.pattern.test(raw)) {
+            return { code: rule.code, ...rule.describe(ctx) };
+        }
+    }
+    return null;
+}
+
+function formatErrorHint(text, context = {}) {
+    const info = describeError(text, context);
+    return info ? `\n提示: ${info.reason}\n${info.action}` : '';
+}
+
+module.exports = {
+    describeError,
+    formatErrorHint
+};

package/lib/global-config.js

@@ -5,6 +5,7 @@ const os = require('os');
 const path = require('path');
 const JSON5 = require('json5');
 const { findTopLevelPropertyValueRange } = require('./json5-text-edit');
+const { writeConfigFileSecure } = require('./secure-file');
 
 function getManyoyoConfigPath(homeDir = os.homedir()) {
     return path.join(homeDir, '.manyoyo', 'manyoyo.json');
@@ -91,17 +92,16 @@ function syncGlobalImageVersion(imageVersion, options = {}) {
         imageVersion
     };
 
-    fs.mkdirSync(path.dirname(configPath), { recursive: true });
     if (result.exists) {
         const currentText = fs.readFileSync(configPath, 'utf-8');
         const updatedText = updateImageVersionText(currentText, imageVersion);
         if (updatedText) {
-            fs.writeFileSync(configPath, updatedText.endsWith('\n') ? updatedText : `${updatedText}\n`);
+            writeConfigFileSecure(configPath, updatedText.endsWith('\n') ? updatedText : `${updatedText}\n`);
         } else {
-            fs.writeFileSync(configPath, `${JSON.stringify(nextConfig, null, 4)}\n`);
+            writeConfigFileSecure(configPath, `${JSON.stringify(nextConfig, null, 4)}\n`);
         }
     } else {
-        fs.writeFileSync(configPath, `${JSON.stringify(nextConfig, null, 4)}\n`);
+        writeConfigFileSecure(configPath, `${JSON.stringify(nextConfig, null, 4)}\n`);
     }
 
     return {

package/lib/headless.js

@@ -0,0 +1,53 @@
+'use strict';
+
+// 有头 / 无头判定：安装器与无参 `manyoyo` 启动器共用这一份规则。
+// 有头 = 本机有图形界面且不是 SSH 会话，可以直接打开浏览器；无头 = 走命令行配置与端口转发。
+
+function isSet(value) {
+    return typeof value === 'string' && value.trim() !== '';
+}
+
+function parseEnvForce(value) {
+    const text = String(value === undefined ? '' : value).trim().toLowerCase();
+    if (['1', 'true', 'yes'].includes(text)) return true;
+    if (['0', 'false', 'no'].includes(text)) return false;
+    return null;
+}
+
+/**
+ * @param {{env?: Object, platform?: string, force?: boolean|null}} [options]
+ *   force：命令行 --headless(true) / --gui(false)，优先于环境变量 MANYOYO_HEADLESS，再优先于自动判定
+ * @returns {{headless: boolean, reason: string}}
+ */
+function detectHeadless(options = {}) {
+    const env = options.env || process.env;
+    const platform = options.platform || process.platform;
+    if (options.force === true) return { headless: true, reason: '命令行指定了 --headless' };
+    if (options.force === false) return { headless: false, reason: '命令行指定了 --gui' };
+    const forced = parseEnvForce(env.MANYOYO_HEADLESS);
+    if (forced !== null) return { headless: forced, reason: `环境变量 MANYOYO_HEADLESS=${forced ? 1 : 0}` };
+    if (isSet(env.SSH_CONNECTION) || isSet(env.SSH_TTY)) return { headless: true, reason: '当前是 SSH 会话' };
+    if (platform === 'linux' && !isSet(env.DISPLAY) && !isSet(env.WAYLAND_DISPLAY)) {
+        return { headless: true, reason: '没有检测到图形界面（DISPLAY / WAYLAND_DISPLAY 都为空）' };
+    }
+    return { headless: false, reason: '检测到图形界面' };
+}
+
+// 从 argv 取出 --headless / --gui；两者都出现或夹杂别的参数时返回 null，让调用方按普通子命令处理
+function parseLauncherArgs(args) {
+    let force = null;
+    for (const arg of args) {
+        if (arg === '--headless') {
+            if (force === false) return null;
+            force = true;
+        } else if (arg === '--gui') {
+            if (force === true) return null;
+            force = false;
+        } else {
+            return null;
+        }
+    }
+    return { force };
+}
+
+module.exports = { detectHeadless, parseLauncherArgs, parseEnvForce };

package/lib/image-build.js

@@ -207,7 +207,8 @@ function prepareGoplsBuildCache(ctx, cache, imageTool, arch) {
         cleanupGoTmpPath(ctx, tmpGoPath, false);
         ensureDirectoryIfMissing(tmpGoPath);
 
-        ctx.runCmd('go', ['install', 'golang.org/x/tools/gopls@latest'], {
+        // -trimpath：不把宿主机的绝对路径（如 /Users/<用户名>/go）编进公开分发的二进制
+        ctx.runCmd('go', ['install', '-trimpath', 'golang.org/x/tools/gopls@latest'], {
             stdio: 'inherit',
             env: { ...process.env, GOPATH: tmpGoPath, GOOS: 'linux', GOARCH: arch }
         });
@@ -346,8 +347,8 @@ function runCmdPipeline(leftCmd, leftArgs, rightCmd, rightArgs, options = {}) {
 
     return new Promise((resolve, reject) => {
         let settled = false;
-        const left = spawn(leftCmd, leftArgs, { stdio: ['ignore', 'pipe', 'pipe'] });
-        const right = spawn(rightCmd, rightArgs, { stdio: ['pipe', 'pipe', 'pipe'] });
+        const left = spawn(leftCmd, leftArgs, { stdio: ['ignore', 'pipe', 'pipe'], env: options.env });
+        const right = spawn(rightCmd, rightArgs, { stdio: ['pipe', 'pipe', 'pipe'], env: options.env });
         right.stdin.on('error', () => {});
         left.stdout.pipe(right.stdin);
 
@@ -498,7 +499,7 @@ async function updateAgentsInExistingImage(ctx, fullImageTag) {
             fullImageTag,
             '--format',
             '{{json .Config}}'
-        ], { stdio: 'pipe' }));
+        ], { stdio: 'pipe', env: ctx.dockerEnv }));
     } catch (e) {
         ctx.error(`${RED}错误: 找不到本地镜像 ${fullImageTag}${NC}`);
         ctx.error(`${YELLOW}请先执行 ${ctx.manyoyoName} build --iv ${fullImageTag.split(':').pop()} --yes 构建镜像。${NC}`);
@@ -538,8 +539,8 @@ async function updateAgentsInExistingImage(ctx, fullImageTag) {
 
     const updateStartTime = Date.now();
     try {
-        ctx.runCmd(ctx.dockerCmd, runArgs, { stdio: 'inherit' });
-        await ctx.runCmdPipeline(ctx.dockerCmd, ['export', containerName], ctx.dockerCmd, importArgs, { stdio: 'inherit' });
+        ctx.runCmd(ctx.dockerCmd, runArgs, { stdio: 'inherit', env: ctx.dockerEnv });
+        await ctx.runCmdPipeline(ctx.dockerCmd, ['export', containerName], ctx.dockerCmd, importArgs, { stdio: 'inherit', env: ctx.dockerEnv });
         const updateDuration = ((Date.now() - updateStartTime) / 1000).toFixed(1);
         ctx.log(`\n${GREEN}✅ Agent CLI 更新成功: ${fullImageTag}${NC}`);
         ctx.log(`${GREEN}⏱️  更新耗时: ${updateDuration} 秒${NC}`);
@@ -548,7 +549,7 @@ async function updateAgentsInExistingImage(ctx, fullImageTag) {
         ctx.exit(1);
     } finally {
         try {
-            ctx.runCmd(ctx.dockerCmd, cleanupArgs, { stdio: 'inherit', ignoreError: true });
+            ctx.runCmd(ctx.dockerCmd, cleanupArgs, { stdio: 'inherit', ignoreError: true, env: ctx.dockerEnv });
         } catch (e) {}
     }
 }
@@ -566,6 +567,7 @@ async function buildImage(options = {}) {
         updateAgents: Boolean(options.updateAgents),
         agentUpdateContainerName: options.agentUpdateContainerName || '',
         dockerCmd: options.dockerCmd || 'docker',
+        dockerEnv: options.dockerEnv,
         rootDir: options.rootDir || process.cwd(),
         loadConfig: options.loadConfig || (() => ({})),
         runCmd: options.runCmd,
@@ -649,7 +651,7 @@ async function buildImage(options = {}) {
     }
 
     try {
-        ctx.runCmd(ctx.dockerCmd, buildArgs, { stdio: 'inherit' });
+        ctx.runCmd(ctx.dockerCmd, buildArgs, { stdio: 'inherit', env: ctx.dockerEnv });
         logBuildSuccess();
         return;
     } catch (e) {
@@ -676,7 +678,7 @@ async function buildImage(options = {}) {
     }
 
     try {
-        await ctx.runCmdPipeline(ctx.dockerCmd, buildkitRunArgs, ctx.dockerCmd, ['load'], { stdio: 'inherit' });
+        await ctx.runCmdPipeline(ctx.dockerCmd, buildkitRunArgs, ctx.dockerCmd, ['load'], { stdio: 'inherit', env: ctx.dockerEnv });
         logBuildSuccess();
     } catch (e) {
         ctx.error(`${RED}错误: 镜像构建失败${NC}`);

package/lib/image-prune.js

@@ -0,0 +1,44 @@
+'use strict';
+
+// 清理悬空镜像。绝不能用 `rmi -f`：Podman 的 `rmi --force` 会连带删除正在用该镜像的容器，
+// 用户的旧容器（里面可能有没导出的工作成果）就这样没了。这里只做不带 -f 的清理，
+// 被容器引用的镜像删不掉是预期行为，直接跳过。
+
+function pruneDanglingImages({ dockerExecArgs, log = () => {}, colors = {} }) {
+    const { YELLOW = '', GREEN = '', NC = '' } = colors;
+    log(`\n${YELLOW}清理悬空镜像...${NC}`);
+    // image prune 只清未被任何容器引用的悬空镜像
+    try {
+        dockerExecArgs(['image', 'prune', '-f'], { stdio: 'inherit' });
+    } catch (error) {
+        // daemon 不可用等：清理是尽力而为，不要把一次维护命令变成异常
+        log(`${YELLOW}⚠️  image prune 失败，已跳过: ${String(error && error.message || error).split('\n')[0]}${NC}`);
+        return;
+    }
+
+    try {
+        const imagesOutput = dockerExecArgs(['images', '-a', '--format', '{{.ID}} {{.Repository}}']);
+        const noneImages = [...new Set(String(imagesOutput)
+            .split('\n')
+            .filter(line => line.includes('<none>'))
+            .map(line => line.split(' ')[0])
+            .filter(id => id))];
+
+        if (noneImages.length > 0) {
+            log(`${YELLOW}尝试清理剩余的 <none> 镜像 (${noneImages.length} 个，仍被容器使用的会自动跳过)...${NC}`);
+            for (const id of noneImages) {
+                try {
+                    dockerExecArgs(['rmi', id], { stdio: 'pipe' });
+                } catch (error) {
+                    // 被容器使用或被其它镜像依赖：保留
+                }
+            }
+        }
+    } catch (error) {
+        // 列不出镜像就算了
+    }
+
+    log(`${GREEN}✅ 清理完成${NC}`);
+}
+
+module.exports = { pruneDanglingImages };

package/lib/image-pull.js

@@ -0,0 +1,76 @@
+'use strict';
+
+const { spawn } = require('child_process');
+const { describeError } = require('./error-hints');
+
+const OUTPUT_TAIL_CHARS = 4096;
+
+/**
+ * 拉取镜像，输出实时回调（CLI 直接透传终端，Web 取最后一行当进度）。
+ * 失败时 reject，err.output 是输出末尾，供分类提示。
+ */
+function pullImageProcess(options) {
+    const { command, env, imageRef, onOutput } = options;
+    const spawnFn = options.spawnFn || spawn;
+    return new Promise((resolve, reject) => {
+        let tail = '';
+        const child = spawnFn(command, ['pull', imageRef], { env, stdio: ['ignore', 'pipe', 'pipe'] });
+        const collect = stream => chunk => {
+            const text = chunk.toString('utf-8');
+            tail = (tail + text).slice(-OUTPUT_TAIL_CHARS);
+            if (onOutput) onOutput(text, stream);
+        };
+        child.stdout.on('data', collect('stdout'));
+        child.stderr.on('data', collect('stderr'));
+        child.on('error', error => {
+            const err = new Error(error.message);
+            err.output = `${tail}\n${error.message}`;
+            reject(err);
+        });
+        child.on('close', code => {
+            if (code === 0) {
+                resolve();
+                return;
+            }
+            const err = new Error(`${command} pull ${imageRef} 退出码 ${code}`);
+            err.output = tail;
+            reject(err);
+        });
+    });
+}
+
+function toFriendlyPullError(error, imageRef, command) {
+    const text = `${error && error.output || ''}\n${error && error.message || ''}`;
+    const info = describeError(text, { imageRef, command });
+    const friendly = new Error(info
+        ? `${info.reason}\n${info.action}`
+        : `拉取镜像 ${imageRef} 失败: ${String(error && error.message || error).split('\n')[0]}`);
+    friendly.code = info ? info.code : 'IMAGE_PULL_FAILED';
+    friendly.cause = error;
+    return friendly;
+}
+
+/**
+ * 本地没有镜像就拉取；已有则什么都不做。
+ * 失败抛出带“原因 + 下一步”的错误：运行时不可用 / 镜像不存在 / 网络问题。
+ * @returns {Promise<{pulled: boolean}>}
+ */
+async function ensureImagePresent(options) {
+    const { imageRef, command, isPresent, pull, onStart } = options;
+    if (await isPresent()) {
+        return { pulled: false };
+    }
+    if (onStart) onStart();
+    try {
+        await pull();
+    } catch (error) {
+        throw toFriendlyPullError(error, imageRef, command);
+    }
+    return { pulled: true };
+}
+
+module.exports = {
+    pullImageProcess,
+    toFriendlyPullError,
+    ensureImagePresent
+};