@xcanwin/manyoyo 7.1.5 → 8.0.1

package/bin/manyoyo.js

@@ -11,11 +11,26 @@ const { Command } = require('commander');
 const { startWebServer } = require('../lib/web/server');
 const { buildContainerRunArgs, buildContainerRunCommand } = require('../lib/container-run');
 const { getManyoyoConfigPath, readManyoyoConfig, syncGlobalImageVersion } = require('../lib/global-config');
+const { resolveUpdateImageVersion } = require('../lib/image-version-policy');
+const { selectContainerRuntime, mergeRuntimeEnv } = require('../lib/container-runtime');
+const { describeError } = require('../lib/error-hints');
+const { ensureRuntimeReady, runCommandAsync } = require('../lib/runtime-heal');
+const { ensureImagePresent, pullImageProcess } = require('../lib/image-pull');
+const { readImportState, waitForImport } = require('../lib/offline-import');
+const { runPodmanCommand } = require('../lib/podman-passthrough');
+const { detectHeadless, parseLauncherArgs } = require('../lib/headless');
+const { runSetupCli, createPrompter } = require('../lib/setup-cli');
+const { pruneDanglingImages: pruneDanglingImagesSafely } = require('../lib/image-prune');
+const { runUninstall, readPid, defaultIsManyoyoServe, defaultKill } = require('../lib/uninstall');
+const appUpdate = require('../lib/app-update');
+const { createUpdateChecker } = require('../lib/update-check');
+const { getLoginTokenDir, issueLoginToken } = require('../lib/login-token');
+const { launchApp, getAppStatePath, openBrowser } = require('../lib/app-launcher');
 const { initAgentConfigs } = require('../lib/init-config');
 const { buildImage } = require('../lib/image-build');
 const { resolveAgentResumeArg, buildAgentResumeCommand } = require('../lib/agent-resume');
 const { resolveYoloCommand } = require('../lib/agent-adapters');
-const { runDoctorChecks } = require('../lib/doctor');
+const { runDoctorChecks, applyDoctorFixes } = require('../lib/doctor');
 const { resolveContainerMode } = require('../lib/container-modes');
 const { runPluginCommand, createPlugin } = require('../lib/plugin');
 const { buildManyoyoLogPath } = require('../lib/log-path');
@@ -23,8 +38,10 @@ const { resolveRuntimeConfig } = require('../lib/runtime-resolver');
 const { resolveWorktreeSupport } = require('../lib/worktrees');
 const {
     parseEnvEntry: parseEnvEntryOrThrow,
-    normalizeVolume
+    normalizeVolume,
+    normalizeMirrors
 } = require('../lib/runtime-normalizers');
+const { applyAptMirror } = require('../lib/mirrors');
 const {
     sanitizeSensitiveData,
     sanitizeServeLogText,
@@ -33,7 +50,8 @@ const {
 } = require('../lib/serve-log');
 const { version: BIN_VERSION, imageVersion: IMAGE_VERSION_DEFAULT } = require('../package.json');
 const IMAGE_VERSION_BASE = String(IMAGE_VERSION_DEFAULT || '1.0.0').split('-')[0];
-const IMAGE_VERSION_HELP_EXAMPLE = IMAGE_VERSION_DEFAULT || `${IMAGE_VERSION_BASE}-common`;
+const GLOBAL_CONFIG_IMAGE_VERSION = String(readManyoyoConfig().config.imageVersion || '').trim();
+const IMAGE_VERSION_HELP_EXAMPLE = GLOBAL_CONFIG_IMAGE_VERSION || IMAGE_VERSION_DEFAULT || `${IMAGE_VERSION_BASE}-common`;
 
 // Helper function to format date like bash $(date +%m%d-%H%M)
 function formatDate() {
@@ -46,6 +64,10 @@ function formatDate() {
 }
 
 function detectCommandName() {
+    // 离线安装器生成的 manyoyo / my 包装脚本都指向同一个 manyoyo.js，用环境变量区分显示的命令名
+    const fromEnv = String(process.env.MANYOYO_COMMAND_NAME || '').trim();
+    if (/^[A-Za-z][A-Za-z0-9_-]*$/.test(fromEnv)) return fromEnv;
+
     const rawArgv1 = process.argv[1] || '';
     const baseName = path.basename(rawArgv1).replace(/\.(cjs|mjs|js)$/i, '');
 
@@ -67,7 +89,7 @@ const CONFIG = {
 let CONTAINER_NAME = `my-${formatDate()}`;
 let HOST_PATH = process.cwd();
 let CONTAINER_PATH = HOST_PATH;
-let IMAGE_NAME = "localhost/xcanwin/manyoyo";
+let IMAGE_NAME = "ghcr.io/xcanwin/manyoyo";
 let IMAGE_VERSION = IMAGE_VERSION_DEFAULT || `${IMAGE_VERSION_BASE}-common`;
 let EXEC_COMMAND = "";
 let EXEC_COMMAND_PREFIX = "";
@@ -104,6 +126,16 @@ const IMAGE_VERSION_TAG_PATTERN = /^(\d+\.\d+\.\d+)-([A-Za-z0-9][A-Za-z0-9_.-]*)
 
 // Docker command (will be set by ensure_docker)
 let DOCKER_CMD = 'docker';
+// 仅运行时子进程使用的完整 env（私有 Podman 才有值），不要写回 process.env
+let DOCKER_ENV;
+let CONTAINER_RUNTIME = null;
+// 全局配置 updateCheck（默认 true）：serve 是否每天检查一次新版本
+let UPDATE_CHECK_ENABLED = true;
+// 全局配置 mirrors（apt/npm/pip 软件源，空 = 官方默认）：容器创建时在容器层生效，镜像不变
+let MIRRORS = { apt: '', npm: '', pip: '' };
+// serve 的容器环境状态，供 GET /api/system/runtime 读取
+const RUNTIME_STATE = { status: 'ready', message: '' };
+const DOCKER_DAEMON_ERROR_CODES = new Set(['PODMAN_MACHINE_UNAVAILABLE', 'DOCKER_DAEMON_UNAVAILABLE', 'PORT_IN_USE']);
 const SUPPORTED_INIT_AGENTS = ['claude', 'codex', 'gemini', 'opencode'];
 
 function sleep(ms) {
@@ -311,6 +343,9 @@ function installServeProcessDiagnostics(logger) {
  * @property {Object.<string, Object>} [runs] - 运行配置映射（-r <name>）
  * @property {string} [yolo] - YOLO 模式
  * @property {string} [containerMode] - 容器模式
+ * @property {string} [containerRuntime] - 容器运行时（auto/docker/podman，默认 auto；仅全局配置生效）
+ * @property {{apt?: string, npm?: string, pip?: string}} [mirrors] - 容器内 apt/npm/pip 软件源（http/https URL，空/缺省为官方默认；仅全局配置生效）
+ * @property {boolean} [updateCheck] - serve 是否每天检查一次新版本（默认 true；仅全局配置生效，请求不附带任何本机信息）
  * @property {number} [cacheTTL] - 缓存过期天数
  * @property {string} [nodeMirror] - Node.js 镜像源
  */
@@ -671,17 +706,39 @@ function setContMode(mode) {
     }
 }
 
+// 本地没有镜像时自动拉取（终端显示拉取进度），失败给出原因与下一步
+async function ensureRunImage(runtime) {
+    const imageRef = `${runtime.imageName}:${runtime.imageVersion}`;
+    // 离线安装器还在后台导入镜像时先等它，避免重复去仓库拉
+    await waitForImport({ onWait: state => console.log(`${YELLOW}⏳ ${state.message}，等待完成...${NC}`) });
+    await ensureImagePresent({
+        imageRef,
+        command: DOCKER_CMD,
+        isPresent: () => {
+            try {
+                dockerExecArgs(['image', 'inspect', imageRef], { stdio: 'pipe' });
+                return true;
+            } catch (e) {
+                return false;
+            }
+        },
+        pull: () => pullImageProcess({
+            command: DOCKER_CMD,
+            env: DOCKER_ENV,
+            imageRef,
+            onOutput: (text, stream) => (stream === 'stderr' ? process.stderr : process.stdout).write(text)
+        }),
+        onStart: () => console.log(`${YELLOW}⏬ 本地没有镜像 ${imageRef}，正在拉取...${NC}`)
+    });
+}
+
 function showImagePullHint(err) {
-    const stderr = err && err.stderr ? err.stderr.toString() : '';
-    const stdout = err && err.stdout ? err.stdout.toString() : '';
-    const message = err && err.message ? err.message : '';
-    const combined = `${message}\n${stderr}\n${stdout}`;
-    if (!/localhost\/v2|pinging container registry localhost|connection refused|dial tcp .*:443/i.test(combined)) {
+    const info = describeError(getCommandFailureText(err), { imageRef: `${IMAGE_NAME}:${IMAGE_VERSION}` });
+    if (!info || !['IMAGE_PULL_FAILED', 'IMAGE_NOT_FOUND'].includes(info.code)) {
         return;
     }
-    const image = `${IMAGE_NAME}:${IMAGE_VERSION}`;
-    console.log(`${YELLOW}💡 提示: 本地未找到镜像 ${image}，并且从 localhost 注册表拉取失败。${NC}`);
-    console.log(`${YELLOW}   你可以: (1) 更新 ~/.manyoyo/manyoyo.json 的 imageVersion。 (2) 或先执行 ${MANYOYO_NAME} build --iv <x.y.z-后缀> 构建镜像。${NC}`);
+    console.log(`${YELLOW}💡 提示: ${info.reason}${NC}`);
+    console.log(`${YELLOW}   ${info.action}${NC}`);
 }
 
 function getCommandFailureText(err) {
@@ -691,25 +748,6 @@ function getCommandFailureText(err) {
     return `${message}\n${stderr}\n${stdout}`;
 }
 
-function getContainerRuntimeUnavailableHint(command, err) {
-    const text = getCommandFailureText(err);
-    if (/Cannot connect to Podman|unable to connect to Podman socket|podman machine start|podman system connection/i.test(text)) {
-        return [
-            '',
-            `提示: 当前 ${command} 命令正在连接 Podman machine，但连接不可用。`,
-            '请先在宿主机执行: podman machine start'
-        ].join('\n');
-    }
-    if (/Cannot connect to the Docker daemon|docker daemon is not running|Is the docker daemon running/i.test(text)) {
-        return [
-            '',
-            `提示: 当前 ${command} 命令无法连接容器运行时。`,
-            '请先启动 Docker Desktop / Docker daemon，或确认 Podman machine 已启动。'
-        ].join('\n');
-    }
-    return '';
-}
-
 function runCmd(cmd, args, options = {}) {
     const result = spawnSync(cmd, args, { encoding: 'utf-8', ...options });
     if (result.error) {
@@ -738,11 +776,12 @@ function checkPortAvailability(port) {
 
 function dockerExecArgs(args, options = {}) {
     try {
-        return runCmd(DOCKER_CMD, args, options);
+        return runCmd(DOCKER_CMD, args, { env: DOCKER_ENV, ...options });
     } catch (e) {
-        const hint = getContainerRuntimeUnavailableHint(DOCKER_CMD, e);
-        if (hint && e && e.message && !e.message.includes(hint)) {
-            e.message = `${e.message}${hint}`;
+        const info = describeError(getCommandFailureText(e), { command: DOCKER_CMD });
+        if (info && DOCKER_DAEMON_ERROR_CODES.has(info.code) && e && e.message) {
+            const hint = `\n提示: ${info.reason}\n${info.action}`;
+            if (!e.message.includes(hint)) e.message = `${e.message}${hint}`;
         }
         throw e;
     }
@@ -763,19 +802,51 @@ function removeContainer(name) {
     if ( !(QUIET.crm || QUIET.full) ) console.log(`${GREEN}✅ 已彻底删除。${NC}`);
 }
 
-function ensureDocker() {
-    const commands = ['docker', 'podman'];
-    for (const cmd of commands) {
-        try {
-            runCmd(cmd, ['--version'], { stdio: 'pipe' });
-            DOCKER_CMD = cmd;
-            return true;
-        } catch (e) {
-            // Try next command
-        }
+// 运行时子进程执行器：env 只是增量，合并后仅传给这个子进程
+function runRuntimeCommand(command, args, options = {}) {
+    return runCmd(command, args, {
+        stdio: 'pipe',
+        timeout: options.timeout,
+        env: mergeRuntimeEnv(options.env)
+    });
+}
+
+// serve 里的自愈用异步执行器：machine start 最长 120s，同步执行会冻住整个事件循环（向导进度、登录页都没响应）
+function runRuntimeCommandAsync(command, args, options = {}) {
+    return runCommandAsync(command, args, { timeout: options.timeout, env: mergeRuntimeEnv(options.env) });
+}
+
+function healContainerRuntime(onStatus, options = {}) {
+    return ensureRuntimeReady({ runtime: CONTAINER_RUNTIME, run: options.async ? runRuntimeCommandAsync : runRuntimeCommand, onStatus });
+}
+
+// 选择阶段已确认 daemon 可用（info 通过）时无需再自愈
+function isRuntimeProven() {
+    return /-daemon$/.test(CONTAINER_RUNTIME.source);
+}
+
+async function ensureDocker(configuredRuntime, options = {}) {
+    try {
+        CONTAINER_RUNTIME = selectContainerRuntime({ configured: configuredRuntime });
+    } catch (e) {
+        console.error(e.message);
+        process.exit(1);
     }
-    console.error("docker/podman not found");
-    process.exit(1);
+    DOCKER_CMD = CONTAINER_RUNTIME.command;
+    DOCKER_ENV = mergeRuntimeEnv(CONTAINER_RUNTIME.env);
+    if (options.deferHeal || isRuntimeProven()) {
+        return true;
+    }
+
+    const result = await healContainerRuntime(state => {
+        if (state.status === 'starting') console.log(`${YELLOW}⏳ ${state.message}...${NC}`);
+    });
+    if (result.status === 'started') {
+        console.log(`${GREEN}✅ 容器环境已就绪${NC}`);
+    } else if (result.status !== 'ready') {
+        console.log(`${YELLOW}⚠️  ${result.message}${NC}`);
+    }
+    return true;
 }
 
 function installManyoyo(name) {
@@ -796,7 +867,130 @@ function installManyoyo(name) {
     process.exit(0);
 }
 
-function updateManyoyo() {
+// 升级后让旧版本的后台服务退出（pid 必须确实是 manyoyo serve），下次执行 manyoyo 就会启动新版本
+function stopBackgroundApp({ quiet = false } = {}) {
+    const pid = readPid(path.join(os.homedir(), '.manyoyo', 'serve', 'app.json'));
+    if (pid && pid !== process.pid && defaultIsManyoyoServe(pid) && defaultKill(pid)) {
+        if (!quiet) console.log(`${GREEN}✅ 已停止旧版本的后台服务 (pid ${pid})，下次执行 ${MANYOYO_NAME} 会启动新版本。${NC}`);
+    }
+}
+
+// 升级流程里准备容器运行时：和 ensureDocker 一样选择并（必要时）自愈，但没有运行时也不退出进程
+async function prepareRuntimeForUpdate(configuredRuntime) {
+    try {
+        CONTAINER_RUNTIME = selectContainerRuntime({ configured: configuredRuntime });
+    } catch (error) {
+        return false;
+    }
+    DOCKER_CMD = CONTAINER_RUNTIME.command;
+    DOCKER_ENV = mergeRuntimeEnv(CONTAINER_RUNTIME.env);
+    if (!isRuntimeProven()) {
+        const result = await healContainerRuntime(state => {
+            if (state.status === 'starting') console.log(`${YELLOW}⏳ ${state.message}...${NC}`);
+        });
+        if (result.status !== 'ready' && result.status !== 'started') {
+            console.log(`${YELLOW}⚠️  ${result.message}${NC}`);
+            return false;
+        }
+    }
+    return true;
+}
+
+async function updateOfflineInstall(mode, options, globalConfig) {
+    const { appRoot } = mode;
+    if (options.rollback) {
+        const result = appUpdate.rollbackApp({ appRoot });
+        console.log(`${GREEN}✅ 已回滚: ${result.from || '未知'} → ${result.to}${NC}`);
+        stopBackgroundApp();
+        return;
+    }
+
+    const installed = appUpdate.currentVersion(appRoot) || mode.version;
+    console.log(`${CYAN}🔄 当前版本: ${installed}${NC}`);
+    console.log(`${CYAN}🔄 正在查询最新版本...${NC}`);
+    const release = await appUpdate.fetchLatestRelease();
+    if (appUpdate.compareVersions(release.version, installed) <= 0) {
+        console.log(`${GREEN}✅ 已是最新版本 ${installed}${NC}`);
+        return;
+    }
+    console.log(`${CYAN}⬇️  发现新版本 ${release.version}，只下载 manyoyo 本体（数十 MB）${NC}`);
+    const result = await appUpdate.installAppUpdate({ appRoot, release, targetOs: appUpdate.platformOs(), log: line => console.log(`   ${line}`) });
+    console.log(`${GREEN}✅ 更新完成: ${installed} → ${result.version}（上一版本 ${result.previous || '无'} 已保留，可用 ${MANYOYO_NAME} update --rollback 回滚）${NC}`);
+
+    // Podman / VM 磁盘有变化只提示（需要新的完整包）
+    try {
+        const names = appUpdate.releaseAssetNames(release.version, appUpdate.arch(), appUpdate.platformOs());
+        if (release.assets[names.manifest]) {
+            const remote = JSON.parse(await appUpdate.fetchText(fetch, release.assets[names.manifest]));
+            const hint = appUpdate.describeRuntimeChange(appUpdate.readInstalledRecord(os.homedir()), remote);
+            if (hint) console.log(`${YELLOW}ℹ️  ${hint}${NC}`);
+        }
+    } catch (error) {
+        // 提示信息拿不到不影响升级
+    }
+
+    // 新版本要求的镜像不存在就拉取；仍用旧镜像的容器只列出来，不动
+    const imageName = String(globalConfig.imageName || 'ghcr.io/xcanwin/manyoyo');
+    const versionPolicy = resolveUpdateImageVersion({
+        configured: globalConfig.imageVersion,
+        previousDefault: require('../package.json').imageVersion,
+        nextDefault: result.manifest.imageVersion
+    });
+    const imageVersion = versionPolicy.imageVersion;
+    if (versionPolicy.advance) {
+        const synced = syncGlobalImageVersion(imageVersion);
+        console.log(`${CYAN}ℹ️  配置里的 imageVersion（${globalConfig.imageVersion}）是旧版本默认值，已随新版本更新为 ${imageVersion}${synced.updated ? '' : '（写入配置失败，请手动修改）'}${NC}`);
+    } else if (versionPolicy.pinned) {
+        console.log(`${YELLOW}ℹ️  你在配置里固定了 imageVersion=${imageVersion}，新版本默认是 ${result.manifest.imageVersion}；如需使用新镜像请修改 ~/.manyoyo/manyoyo.json${NC}`);
+    }
+    if (imageVersion && await prepareRuntimeForUpdate(globalConfig.containerRuntime)) {
+        const imageRef = `${imageName}:${imageVersion}`;
+        try {
+            await ensureImagePresent({
+                imageRef,
+                command: DOCKER_CMD,
+                isPresent: () => {
+                    try {
+                        dockerExecArgs(['image', 'inspect', imageRef], { stdio: 'pipe' });
+                        return true;
+                    } catch (e) {
+                        return false;
+                    }
+                },
+                pull: () => pullImageProcess({ command: DOCKER_CMD, env: DOCKER_ENV, imageRef, onOutput: (text, stream) => (stream === 'stderr' ? process.stderr : process.stdout).write(text) }),
+                onStart: () => console.log(`${YELLOW}⏬ 新版本需要镜像 ${imageRef}，正在拉取...${NC}`)
+            });
+        } catch (error) {
+            console.log(`${YELLOW}⚠️  镜像还没准备好：${error.message}${NC}`);
+        }
+        const outdated = appUpdate.findOutdatedContainers({ run: runCmd, runtime: { command: DOCKER_CMD, env: DOCKER_ENV }, imageRef });
+        if (outdated.length > 0) {
+            console.log(`${YELLOW}ℹ️  有 ${outdated.length} 个容器还在用旧镜像：${outdated.map(item => `${item.name}(${item.image})`).join('、')}${NC}`);
+            console.log(`${YELLOW}   它们可以继续使用；想换成新镜像，请新建容器（会话历史与凭据都在宿主机上，不会丢）。${NC}`);
+        }
+    }
+    stopBackgroundApp();
+}
+
+async function updateManyoyo(options = {}, globalConfig = {}) {
+    const mode = appUpdate.detectInstallMode({ scriptPath: __filename });
+    if (mode.mode === 'offline') {
+        try {
+            await updateOfflineInstall(mode, options, globalConfig);
+        } catch (error) {
+            if (error instanceof appUpdate.UpdateError) {
+                console.error(`${RED}❌ ${error.message}${NC}`);
+                process.exit(1);
+            }
+            throw error;
+        }
+        return;
+    }
+    if (options.rollback) {
+        console.error(`${RED}❌ --rollback 只适用于离线包安装；npm 安装的版本请用 npm install -g @xcanwin/manyoyo@<版本> 回退。${NC}`);
+        process.exit(1);
+    }
+
     let isLocalFileInstall = false;
     let currentVersion = 'unknown';
 
@@ -901,27 +1095,11 @@ function getImageList() {
 }
 
 function pruneDanglingImages() {
-    console.log(`\n${YELLOW}清理悬空镜像...${NC}`);
-    dockerExecArgs(['image', 'prune', '-f'], { stdio: 'inherit' });
-
-    // Remove remaining <none> images
-    try {
-        const imagesOutput = dockerExecArgs(['images', '-a', '--format', '{{.ID}} {{.Repository}}']);
-        const noneImages = imagesOutput
-            .split('\n')
-            .filter(line => line.includes('<none>'))
-            .map(line => line.split(' ')[0])
-            .filter(id => id);
-
-        if (noneImages.length > 0) {
-            console.log(`${YELLOW}清理剩余的 <none> 镜像 (${noneImages.length} 个)...${NC}`);
-            dockerExecArgs(['rmi', '-f', ...noneImages], { stdio: 'inherit' });
-        }
-    } catch (e) {
-        // Ignore errors if no <none> images found
-    }
-
-    console.log(`${GREEN}✅ 清理完成${NC}`);
+    pruneDanglingImagesSafely({
+        dockerExecArgs,
+        log: line => console.log(line),
+        colors: { YELLOW, GREEN, NC }
+    });
 }
 
 function maybeHandleDockerPluginMetadata(argv) {
@@ -1262,6 +1440,11 @@ Notes:
         selectAction('config-command', options);
     });
 
+    program.command('uninstall')
+        .description('卸载离线包安装的 MANYOYO：停止服务，删除程序与 PATH 配置，用户数据逐项询问（--yes 不会删用户数据）')
+        .option('--yes', '确认卸载程序本身，不再询问（不会删除配置、历史、日志、工作目录和外部运行时里的容器镜像）')
+        .action(options => selectAction('uninstall', options));
+
     const initCommand = program.command('init [agents]').description('初始化 Agent 配置到 ~/.manyoyo');
     initCommand
         .option('--yes', '所有提示自动确认 (用于CI/脚本)')
@@ -1272,11 +1455,24 @@ Notes:
         .option('-r, --run <name>', '加载运行配置 (从 ~/.manyoyo/manyoyo.json 的 runs.<name> 读取)')
         .option('--port <port>', '检查指定监听端口')
         .option('--json', '以 JSON 输出稳定诊断结果')
+        .option('--fix', '自动修复可修复项（启动容器环境、拉取镜像、生成默认配置，端口占用时给出建议端口）')
         .action(options => selectAction('doctor', { ...options, doctor: true }));
 
     program.command('update')
-        .description('更新 MANYOYO（若检测为本地 file 安装则跳过）')
-        .action(() => selectAction('update', { update: true }));
+        .description('更新 MANYOYO（离线包安装只下载变化部分并保留上一版本；若检测为本地 file 安装则跳过）')
+        .option('--rollback', '离线包安装：切回上一版本')
+        .action(options => selectAction('update', { update: true, rollback: Boolean(options.rollback) }));
+
+    program.command('podman [args...]')
+        .description('用 MANYOYO 的私有 Podman 执行命令（参数原样传给 podman）；eval "$(manyoyo podman env)" 可在当前终端定义 podman 函数')
+        .helpOption(false)
+        .allowUnknownOption()
+        .passThroughOptions()
+        .action(args => selectAction('podman', { podmanArgs: args || [] }));
+
+    program.command('setup')
+        .description('命令行配置向导（无头环境：SSH、没有图形界面）：选 Agent、填 Key、设登录密码，可选软件源')
+        .action(() => selectAction('setup', {}));
 
     program.command('install <name>')
         .description(`安装 ${MANYOYO_NAME} 命令 (docker-cli-plugin)`)
@@ -1294,9 +1490,10 @@ Notes:
     // Docker CLI plugin mode - remove first arg if running as plugin
     normalizeDockerPluginArgv(process.argv);
 
-    // No args: show help instead of starting container
-    if (process.argv.length <= 2) {
-        program.help();
+    // No args (or only --headless / --gui): start (or reuse) the local web app; open the browser already logged in unless headless
+    const launcherArgs = parseLauncherArgs(process.argv.slice(2));
+    if (launcherArgs) {
+        await runAppLauncher({ force: launcherArgs.force });
     }
 
     // Pre-handle -x/--shell-full: treat all following args as a single command
@@ -1329,16 +1526,58 @@ Notes:
         throw new Error('serve --stop 与 --restart 不能同时使用');
     }
 
-    const noDockerActions = new Set(['init', 'update', 'install', 'config-show', 'plugin', 'doctor']);
+    UPDATE_CHECK_ENABLED = config.updateCheck !== false;
+    MIRRORS = normalizeMirrors(config.mirrors);
+    const noDockerActions = new Set(['init', 'update', 'install', 'config-show', 'plugin', 'doctor', 'uninstall', 'podman', 'setup']);
     if (isServerStopMode) {
         noDockerActions.add('serve');
     }
     if (!noDockerActions.has(selectedAction)) {
-        ensureDocker();
+        await ensureDocker(config.containerRuntime, { deferHeal: selectedAction === 'serve' });
     }
 
     if (options.update) {
-        updateManyoyo();
+        await updateManyoyo(options, config);
+        process.exit(0);
+    }
+
+    if (selectedAction === 'setup') {
+        const interactive = Boolean(process.stdin.isTTY);
+        const code = await runSetupCli({
+            isTTY: interactive,
+            prompter: interactive ? createPrompter() : null,
+            configPath: getManyoyoConfigPath(),
+            defaultWorkpath: path.join(os.homedir(), '.manyoyo', 'work'),
+            validateHostPath: value => validateHostPathOrThrow(value),
+            commandName: MANYOYO_NAME,
+            log: line => console.log(line),
+            // 新密码要让后台服务重新读配置：先停掉旧的，再按当前环境（有头 / 无头）启动
+            afterSave: async () => {
+                stopBackgroundApp({ quiet: true });
+                await runAppLauncher({ exit: false });
+            }
+        });
+        process.exit(code);
+    }
+
+    if (selectedAction === 'podman') {
+        process.exit(runPodmanCommand(options.podmanArgs, { commandName: MANYOYO_NAME }));
+    }
+
+    if (selectedAction === 'uninstall') {
+        await runUninstall({
+            yes: yesMode,
+            ask: askQuestion,
+            log: line => console.log(line),
+            selectExternalRuntime: () => {
+                try {
+                    const selected = selectContainerRuntime({ configured: config.containerRuntime });
+                    return selected.source === 'private-podman' ? null : selected;
+                } catch (error) {
+                    return null;
+                }
+            }
+        });
         process.exit(0);
     }
 
@@ -1482,6 +1721,8 @@ Notes:
             worktreeRepoRoot: resolvedRuntime.worktreeRepoRoot,
             worktreeMainRepoRoot: resolvedRuntime.worktreeMainRepoRoot,
             containerMode: contModeValue || "",
+            containerRuntime: config.containerRuntime || "auto",
+            mirrors: MIRRORS,
             shellPrefix: EXEC_COMMAND_PREFIX.trim(),
             shell: EXEC_COMMAND || "",
             shellSuffix: EXEC_COMMAND_SUFFIX || "",
@@ -1524,8 +1765,13 @@ Notes:
         const portStatus = Number.isInteger(parsedPort) && parsedPort > 0 && parsedPort <= 65535
             ? await checkPortAvailability(parsedPort)
             : undefined;
-        const report = runDoctorChecks({
-            runCommand: runCmd,
+        let doctorRuntime = null;
+        let report = await runDoctorChecks({
+            selectRuntime: () => {
+                doctorRuntime = selectContainerRuntime({ configured: config.containerRuntime });
+                return doctorRuntime;
+            },
+            runCommand: runRuntimeCommand,
             configExists: fs.existsSync(getManyoyoConfigPath()),
             imageName: IMAGE_NAME,
             imageVersion: IMAGE_VERSION,
@@ -1534,11 +1780,49 @@ Notes:
             pluginConfig: config.plugins,
             portStatus
         });
+        if (options.fix) {
+            report = await applyDoctorFixes(report, {
+                startRuntime: async () => {
+                    const result = await ensureRuntimeReady({ runtime: doctorRuntime, run: runRuntimeCommand });
+                    return { fixed: result.status === 'started' || result.status === 'ready', message: result.message };
+                },
+                pullImage: async () => {
+                    const image = `${IMAGE_NAME}:${IMAGE_VERSION}`;
+                    try {
+                        console.error(`正在拉取 ${image} ...`);
+                        await pullImageProcess({
+                            command: doctorRuntime.command,
+                            env: mergeRuntimeEnv(doctorRuntime.env),
+                            imageRef: image,
+                            onOutput: text => process.stderr.write(text)
+                        });
+                    } catch (e) {
+                        throw new Error(`拉取 ${image} 失败；可执行 ${MANYOYO_NAME} build --iv ${IMAGE_VERSION} 本地构建`);
+                    }
+                    return { fixed: true, message: `已拉取 ${image}` };
+                },
+                createConfig: () => {
+                    const result = syncGlobalImageVersion(IMAGE_VERSION);
+                    return { fixed: result.reason === 'created', message: result.reason === 'created' ? `已生成 ${result.path}` : `未生成配置: ${result.reason}` };
+                },
+                suggestPort: async () => {
+                    for (let candidate = parsedPort + 1; candidate <= Math.min(parsedPort + 50, 65535); candidate += 1) {
+                        if (await checkPortAvailability(candidate) === 'available') {
+                            return { fixed: false, message: `建议使用空闲端口 ${candidate}` };
+                        }
+                    }
+                    return { fixed: false, message: '附近没有空闲端口，请手动指定' };
+                }
+            });
+        }
         if (options.json) {
             console.log(JSON.stringify(report, null, 4));
         } else {
             report.checks.forEach(check => {
                 console.log(`[${check.status.toUpperCase()}] ${check.code}: ${check.summary}${check.action ? ` (${check.action})` : ''}`);
+                if (check.fix && check.fix.attempted) {
+                    console.log(`    ${check.fix.fixed ? '已修复' : '未修复'}: ${check.fix.message}`);
+                }
             });
         }
         process.exit(report.ok ? 0 : 1);
@@ -1580,6 +1864,7 @@ function createRuntimeContext(modeState = {}) {
         contModeArgs: CONT_MODE_ARGS,
         containerExtraArgs: CONTAINER_EXTRA_ARGS,
         containerEnvs: CONTAINER_ENVS,
+        mirrors: MIRRORS,
         firstContainerEnvs: FIRST_CONTAINER_ENVS,
         containerVolumes: CONTAINER_VOLUMES,
         containerPorts: CONTAINER_PORTS,
@@ -1815,8 +2100,9 @@ function relaunchServeDetached(runtime) {
 /**
  * 等待容器就绪（使用指数退避算法）
  * @param {string} containerName - 容器名称
+ * @param {{throwOnFailure?: boolean}} [options] serve 路径传 true：失败抛错而不是 process.exit，调用方才能清理容器
  */
-async function waitForContainerReady(containerName) {
+async function waitForContainerReady(containerName, options = {}) {
     const MAX_RETRIES = CONFIG.CONTAINER_READY_MAX_RETRIES;
     let retryDelay = CONFIG.CONTAINER_READY_INITIAL_DELAY;
 
@@ -1829,6 +2115,9 @@ async function waitForContainerReady(containerName) {
             }
 
             if (status === 'exited') {
+                if (options.throwOnFailure) {
+                    throw Object.assign(new Error('容器启动后立即退出'), { containerExited: true });
+                }
                 console.log(`${RED}⚠️  错误: 容器启动后立即退出。${NC}`);
                 dockerExecArgs(['logs', containerName], { stdio: 'inherit' });
                 process.exit(1);
@@ -1837,11 +2126,15 @@ async function waitForContainerReady(containerName) {
             await sleep(retryDelay);
             retryDelay = Math.min(retryDelay * 2, CONFIG.CONTAINER_READY_MAX_DELAY);
         } catch (e) {
+            if (e && e.containerExited) throw e;
             await sleep(retryDelay);
             retryDelay = Math.min(retryDelay * 2, CONFIG.CONTAINER_READY_MAX_DELAY);
         }
     }
 
+    if (options.throwOnFailure) {
+        throw new Error('容器启动超时');
+    }
     console.log(`${RED}⚠️  错误: 容器启动超时。${NC}`);
     process.exit(1);
 }
@@ -1874,7 +2167,7 @@ function executeFirstCommand(runtime) {
         '-c',
         firstCommand
     ];
-    const firstExecResult = spawnSync(`${DOCKER_CMD}`, firstExecArgs, { stdio: 'inherit' });
+    const firstExecResult = spawnSync(`${DOCKER_CMD}`, firstExecArgs, { stdio: 'inherit', env: DOCKER_ENV });
     if (firstExecResult.error) {
         throw firstExecResult.error;
     }
@@ -1907,6 +2200,8 @@ async function createNewContainer(runtime) {
         process.exit(0);
     }
 
+    await ensureRunImage(runtime);
+
     // 使用数组参数执行命令（安全方式）
     try {
         const args = buildDockerRunArgs(runtime);
@@ -1919,6 +2214,13 @@ async function createNewContainer(runtime) {
     // Wait for container to be ready
     await waitForContainerReady(runtime.containerName);
 
+    applyAptMirror({
+        dockerExecArgs,
+        containerName: runtime.containerName,
+        mirrors: runtime.mirrors,
+        warn: message => console.warn(`${YELLOW}⚠️ ${message}${NC}`)
+    });
+
     // Run one-time bootstrap command for newly created containers only.
     executeFirstCommand(runtime);
 
@@ -1941,6 +2243,7 @@ function buildDockerRunArgs(runtime) {
         containerEnvs: runtime.containerEnvs,
         containerVolumes: runtime.containerVolumes,
         containerPorts: runtime.containerPorts,
+        mirrors: runtime.mirrors,
         defaultCommand: runtime.execCommand
     });
 }
@@ -2016,9 +2319,9 @@ function executeInContainer(runtime, defaultCommand) {
 
     // Execute command in container
     if (runtime.execCommand) {
-        spawnSync(`${DOCKER_CMD}`, ['exec', '-it', runtime.containerName, '/bin/bash', '-c', runtime.execCommand], { stdio: 'inherit' });
+        spawnSync(`${DOCKER_CMD}`, ['exec', '-it', runtime.containerName, '/bin/bash', '-c', runtime.execCommand], { stdio: 'inherit', env: DOCKER_ENV });
     } else {
-        spawnSync(`${DOCKER_CMD}`, ['exec', '-it', runtime.containerName, '/bin/bash'], { stdio: 'inherit' });
+        spawnSync(`${DOCKER_CMD}`, ['exec', '-it', runtime.containerName, '/bin/bash'], { stdio: 'inherit', env: DOCKER_ENV });
     }
 }
 
@@ -2079,6 +2382,38 @@ async function handlePostExit(runtime, defaultCommand) {
     }
 }
 
+async function runAppLauncher({ force = null, exit = true } = {}) {
+    try {
+        const { headless } = detectHeadless({ force });
+        await launchApp({
+            headless,
+            authUser: String(readManyoyoConfig().config.serverUser || '').trim() || 'admin',
+            statePath: getAppStatePath(),
+            isProcessRunning,
+            spawnServe: port => {
+                // 登录走一次性令牌；未配置密码时 serve 自己生成随机密码（标记为自动生成，向导据此让用户设置）
+                const child = spawn(process.argv[0], [process.argv[1], 'serve', `127.0.0.1:${port}`], {
+                    detached: true,
+                    stdio: 'ignore'
+                });
+                child.unref();
+                return child;
+            },
+            issueToken: () => issueLoginToken(getLoginTokenDir()),
+            open: url => openBrowser(url),
+            log: line => console.log(line),
+            logPathHint: buildManyoyoLogPath('serve').path,
+            commandName: MANYOYO_NAME
+        });
+    } catch (e) {
+        console.error(`${RED}${e.message}${NC}`);
+        if (!exit) return false;
+        process.exit(1);
+    }
+    if (!exit) return true;
+    process.exit(0);
+}
+
 async function runWebServerMode(runtime) {
     if (!runtime.serverAuthUser || !runtime.serverAuthPass) {
         ensureWebServerAuthCredentials();
@@ -2087,6 +2422,48 @@ async function runWebServerMode(runtime) {
         runtime.serverAuthPassAuto = SERVER_AUTH_PASS_AUTO;
     }
 
+    const updateChecker = createUpdateChecker({
+        currentVersion: require('../package.json').version,
+        installMode: appUpdate.detectInstallMode({ scriptPath: __filename }).mode,
+        enabled: UPDATE_CHECK_ENABLED,
+        fetchLatest: () => appUpdate.fetchLatestRelease()
+    });
+
+    const needRuntimeHeal = !isRuntimeProven();
+    if (needRuntimeHeal) {
+        RUNTIME_STATE.status = 'starting';
+        RUNTIME_STATE.message = '正在检查容器环境';
+    }
+
+    // 自愈失败/超时不是终态：用户手动修好（或点向导里的“重试”）后可以再来一次
+    let runtimeHealing = false;
+    function startServeRuntimeHeal() {
+        if (runtimeHealing) return false;
+        runtimeHealing = true;
+        RUNTIME_STATE.status = 'starting';
+        RUNTIME_STATE.message = '正在检查容器环境';
+        healContainerRuntime(state => {
+            RUNTIME_STATE.status = state.status;
+            RUNTIME_STATE.message = state.message;
+            if (state.status === 'starting') console.log(`${YELLOW}⏳ ${state.message}...${NC}`);
+        }, { async: true }).then(result => {
+            if (result.status === 'ready' || result.status === 'started') {
+                RUNTIME_STATE.status = 'ready';
+                RUNTIME_STATE.message = '';
+            } else {
+                RUNTIME_STATE.status = 'failed';
+                RUNTIME_STATE.message = result.message;
+                console.log(`${YELLOW}⚠️  ${result.message}${NC}`);
+            }
+        }).catch(error => {
+            RUNTIME_STATE.status = 'failed';
+            RUNTIME_STATE.message = String(error && error.message || error);
+        }).finally(() => {
+            runtimeHealing = false;
+        });
+        return true;
+    }
+
     const serverHandle = await startWebServer({
         serverHost: runtime.serverHost,
         serverPort: runtime.serverPort,
@@ -2095,6 +2472,31 @@ async function runWebServerMode(runtime) {
         authPassAuto: runtime.serverAuthPassAuto,
         serveTitle: runtime.serveTitle,
         dockerCmd: DOCKER_CMD,
+        dockerEnv: DOCKER_ENV,
+        runtimeState: RUNTIME_STATE,
+        retryRuntimeHeal: () => (needRuntimeHeal ? startServeRuntimeHeal() : false),
+        autoPullImage: true,
+        importState: () => readImportState(),
+        updateInfo: () => updateChecker.getInfo(),
+        loginTokenDir: getLoginTokenDir(),
+        doctorCheck: async () => runDoctorChecks({
+            selectRuntime: () => CONTAINER_RUNTIME,
+            runCommand: runRuntimeCommandAsync,
+            configExists: fs.existsSync(getManyoyoConfigPath()),
+            imageName: runtime.imageName,
+            imageVersion: runtime.imageVersion,
+            containerMode: 'common',
+            pluginConfig: {}
+        }),
+        doctorStartRuntime: async () => {
+            const result = await ensureRuntimeReady({ runtime: CONTAINER_RUNTIME, run: runRuntimeCommandAsync });
+            const fixed = result.status === 'started' || result.status === 'ready';
+            if (fixed) {
+                RUNTIME_STATE.status = 'ready';
+                RUNTIME_STATE.message = '';
+            }
+            return { fixed, message: result.message };
+        },
         hostPath: runtime.hostPath,
         containerPath: runtime.containerPath,
         imageName: runtime.imageName,
@@ -2114,6 +2516,7 @@ async function runWebServerMode(runtime) {
         getContainerStatus,
         waitForContainerReady,
         dockerExecArgs,
+        dockerExecAsync: (args, options = {}) => runCommandAsync(DOCKER_CMD, args, { env: DOCKER_ENV, timeout: options.timeout }),
         showImagePullHint,
         removeContainer,
         webHistoryDir: path.join(os.homedir(), '.manyoyo', 'web-history'),
@@ -2128,6 +2531,9 @@ async function runWebServerMode(runtime) {
         logger: runtime.logger
     });
     writeServePidFile(runtime, serverHandle);
+    if (needRuntimeHeal) {
+        startServeRuntimeHeal();
+    }
     return serverHandle;
 }
 
@@ -2189,6 +2595,7 @@ async function main() {
                 yesMode: Boolean(modeState.yesMode),
                 updateAgents: Boolean(modeState.updateAgents),
                 dockerCmd: DOCKER_CMD,
+                dockerEnv: DOCKER_ENV,
                 rootDir: path.join(__dirname, '..'),
                 loadConfig,
                 runCmd,