@xcanwin/manyoyo 7.1.6 → 8.1.0

package/bin/manyoyo.js

@@ -7,15 +7,30 @@ const os = require('os');
 const crypto = require('crypto');
 const net = require('net');
 const readline = require('readline');
-const { Command } = require('commander');
+const { Command, Help } = 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,8 +50,7 @@ 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 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`;
+const IMAGE_VERSION_HELP_EXAMPLE = IMAGE_VERSION_DEFAULT || `${IMAGE_VERSION_BASE}-common`;
 
 // Helper function to format date like bash $(date +%m%d-%H%M)
 function formatDate() {
@@ -47,14 +63,13 @@ 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, '');
 
-    if (baseName === 'docker-manyoyo') {
-        const pluginCommand = String(process.argv[2] || '').trim();
-        return pluginCommand || 'manyoyo';
-    }
-
     return baseName || 'manyoyo';
 }
 
@@ -68,7 +83,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 = "";
@@ -105,6 +120,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) {
@@ -312,6 +337,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 镜像源
  */
@@ -438,7 +466,7 @@ function parseImageVersionTag(version) {
 function validateImageVersion(value) {
     validateName('imageVersion', value, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/);
     if (!parseImageVersionTag(value)) {
-        console.error(`${RED}⚠️  错误: imageVersion 格式必须为 <x.y.z-后缀>，例如 1.7.4-common。当前值: ${value}${NC}`);
+        console.error(`${RED}⚠️  错误: imageVersion 格式必须为 <x.y.z-后缀>，例如 ${IMAGE_VERSION_HELP_EXAMPLE}。当前值: ${value}${NC}`);
         process.exit(1);
     }
 }
@@ -672,17 +700,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) {
@@ -692,25 +742,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) {
@@ -739,11 +770,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;
     }
@@ -764,40 +796,169 @@ function removeContainer(name) {
     if ( !(QUIET.crm || QUIET.full) ) console.log(`${GREEN}✅ 已彻底删除。${NC}`);
 }
 
-function ensureDocker() {
-    const commands = ['docker', 'podman'];
-    for (const cmd of commands) {
+// 运行时子进程执行器：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);
+    }
+    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;
+}
+
+// 升级后让旧版本的后台服务退出（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 磁盘有变化只提示（需要新的完整包）
+    const runtimeHint = appUpdate.describeRuntimeChange(appUpdate.readInstalledRecord(os.homedir()), result.manifest.runtime);
+    if (runtimeHint) console.log(`${YELLOW}ℹ️  ${runtimeHint}${NC}`);
+
+    // 新版本要求的镜像不存在就拉取；仍用旧镜像的容器只列出来，不动
+    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 {
-            runCmd(cmd, ['--version'], { stdio: 'pipe' });
-            DOCKER_CMD = cmd;
-            return true;
-        } catch (e) {
-            // Try next command
+            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}`);
         }
     }
-    console.error("docker/podman not found");
-    process.exit(1);
+    stopBackgroundApp();
 }
 
-function installManyoyo(name) {
-    const MANYOYO_FILE = fs.realpathSync(__filename);
-    switch (name) {
-        case 'docker-cli-plugin':
-            const pluginDir = path.join(process.env.HOME, '.docker/cli-plugins');
-            fs.mkdirSync(pluginDir, { recursive: true });
-            const targetPath = path.join(pluginDir, 'docker-manyoyo');
-            if (fs.existsSync(targetPath)) {
-                fs.unlinkSync(targetPath);
+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);
             }
-            fs.symlinkSync(MANYOYO_FILE, targetPath);
-            break;
-        default:
-            console.log("");
+            throw error;
+        }
+        return;
+    }
+    if (options.rollback) {
+        console.error(`${RED}❌ --rollback 只适用于离线包安装；npm 安装的版本请用 npm install -g @xcanwin/manyoyo@<版本> 回退。${NC}`);
+        process.exit(1);
     }
-    process.exit(0);
-}
 
-function updateManyoyo() {
     let isLocalFileInstall = false;
     let currentVersion = 'unknown';
 
@@ -902,47 +1063,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}`);
-}
-
-function maybeHandleDockerPluginMetadata(argv) {
-    if (argv[2] !== 'docker-cli-plugin-metadata') {
-        return false;
-    }
-    console.log(JSON.stringify({
-        "SchemaVersion": "0.1.0",
-        "Vendor": "xcanwin",
-        "Version": "v1.0.0",
-        "Description": "AI Agent CLI Sandbox"
-    }, null, 4));
-    return true;
-}
-
-function normalizeDockerPluginArgv(argv) {
-    const dockerPluginPath = path.join(process.env.HOME || '', '.docker/cli-plugins/docker-manyoyo');
-    if (argv[1] === dockerPluginPath && argv[2] === 'manyoyo') {
-        argv.splice(2, 1);
-    }
+    pruneDanglingImagesSafely({
+        dockerExecArgs,
+        log: line => console.log(line),
+        colors: { YELLOW, GREEN, NC }
+    });
 }
 
 function normalizeShellFullArgv(argv) {
@@ -1006,7 +1131,7 @@ function applyRunStyleOptions(command, options = {}) {
         .option('--cp, --cont-path <path>', '设置容器工作目录')
         .option('-m, --cont-mode <mode>', '设置容器嵌套模式 (common, dind, sock; 注意: sock 模式可访问宿主机 Docker socket，风险较高)')
         .option('--in, --image-name <name>', '指定镜像名称')
-        .option('--iv, --image-ver <version>', '指定镜像版本 (格式: x.y.z-后缀，如 1.7.4-common)');
+        .option('--iv, --image-ver <version>', `指定镜像版本 (格式: x.y.z-后缀，如 ${IMAGE_VERSION_HELP_EXAMPLE})`);
 
     appendArrayOption(command, '-e, --env <env>', '设置环境变量 XXX=YYY (可多次使用)');
     appendArrayOption(command, '--ef, --env-file <file>', '从环境文件加载变量 (仅支持绝对路径，如 /abs/path.env; 相对路径会报错)');
@@ -1023,7 +1148,7 @@ function applyRunStyleOptions(command, options = {}) {
         .option('--first-shell <command>', '首次预执行命令 (仅新建容器生效; 容器已存在时忽略)')
         .option('--first-shell-suffix <command>', '首次预执行命令后缀 (仅新建容器生效; 容器已存在时忽略)')
         .option('-x, --shell-full <command...>', '完整命令 (与 --sp/-s/--ss/-- 互斥)')
-        .option('-y, --yolo <cli>', '使 AGENT 无需确认 (claude(c), gemini(gm), codex(cx), opencode(oc))');
+        .option('-y, --yolo <cli>', '以免确认模式启动 Agent: c=Claude, cx=Codex, gm=Gemini, oc=OpenCode');
     appendArrayOption(command, '--first-env <env>', '首次预执行环境变量 XXX=YYY (可多次使用)');
     appendArrayOption(command, '--first-env-file <file>', '首次预执行环境变量文件 (仅支持绝对路径，如 /abs/path.env)');
 
@@ -1031,7 +1156,7 @@ function applyRunStyleOptions(command, options = {}) {
         command.option('--rm-on-exit', '退出后自动删除容器 (一次性模式)');
     }
 
-    appendArrayOption(command, '-q, --quiet <item>', '静默输出 (可多次使用: cnew, crm, tip, cmd, full)');
+    appendArrayOption(command, '-q, --quiet <item>', '隐藏部分输出 (可多次使用，可选项见下方“-q 可选项”)');
 
     if (includeServePreview) {
         command
@@ -1136,46 +1261,82 @@ async function setupCommander() {
 
     program
         .name(MANYOYO_NAME)
+        .optionsGroup('选项:')
+        .commandsGroup('其他:')
         .version(BIN_VERSION, '-v, --version', '显示版本')
-        .description('MANYOYO - AI Agent CLI Sandbox\nhttps://github.com/xcanwin/manyoyo')
+        .helpOption('-h, --help', '显示帮助')
+        .helpCommand('help [command]', '显示指定命令的帮助')
+        .configureHelp({
+            optionDescription(option) {
+                return Help.prototype.optionDescription.call(this, option).replace(/\s*\(default: \[\]\)/, '');
+            }
+        })
+        .description(`MANYOYO - AI Agent CLI Sandbox
+https://github.com/xcanwin/manyoyo
+
+不带参数直接运行，打开网页界面（首次使用进入配置向导）:
+  ${MANYOYO_NAME}              自动判断有无图形界面
+  ${MANYOYO_NAME} --headless   强制按无图形界面处理（不打开浏览器，用密码登录）
+  ${MANYOYO_NAME} --gui        强制按有图形界面处理（自动打开浏览器）`)
         .addHelpText('after', `
-配置文件:
-  ~/.manyoyo/manyoyo.json   全局配置文件 (JSON5格式，支持注释)
-  ~/.manyoyo/run/c.json     运行配置示例
-
-路径规则:
-  run -r name               → ~/.manyoyo/manyoyo.json 的 runs.name
-  run --ef /abs/path.env    → 绝对路径环境文件
-  run --ss "<args>"         → 显式设置命令后缀
-  run -- <args...>          → 直接透传命令后缀（优先级最高）
-
 示例:
-  ${MANYOYO_NAME} update                              更新 MANYOYO 到最新版本
-  ${MANYOYO_NAME} build --iv ${IMAGE_VERSION_HELP_EXAMPLE} --yes       构建镜像
-  ${MANYOYO_NAME} build --update-agents --yes         仅更新已有镜像内已存在的 Agent CLI
-  ${MANYOYO_NAME} init all                            从本机 Agent 配置初始化 ~/.manyoyo
-  ${MANYOYO_NAME} run -r claude                       使用 manyoyo.json 的 runs.claude 快速启动
-  ${MANYOYO_NAME} run -r codex --ss "resume --last"   使用命令后缀
-  ${MANYOYO_NAME} run -n test --ef /path/ab.env -y c  使用绝对路径环境变量文件
-  ${MANYOYO_NAME} run -n test -- -c                   恢复之前会话
-  ${MANYOYO_NAME} run -x "echo 123"                   使用完整命令
-  ${MANYOYO_NAME} serve 127.0.0.1:3000                启动本机网页服务
-  ${MANYOYO_NAME} serve 127.0.0.1:3000 -d             后台启动；未设密码时会打印本次随机密码
-  ${MANYOYO_NAME} serve 0.0.0.0:3000 -U admin -P 123 -d  后台启动并监听全部网卡
-  ${MANYOYO_NAME} serve 0.0.0.0:3000 -U admin -P 123 -d --restart  重启指定后台网页服务
-  ${MANYOYO_NAME} playwright up mcp-host-headless     启动 playwright MCP 宿主场景（默认/推荐）
-  ${MANYOYO_NAME} playwright up cli-host-headless     启动 playwright CLI 宿主场景（供容器内 playwright-cli 附着）
-  ${MANYOYO_NAME} run -n test -q tip -q cmd           多次使用静默选项
+  ${MANYOYO_NAME}                          打开网页界面
+  ${MANYOYO_NAME} init all                 导入本机已有的 Agent 配置
+  ${MANYOYO_NAME} run -y c                 在沙箱里以免确认模式启动 Claude Code
+  ${MANYOYO_NAME} run -r claude            使用 manyoyo.json 的 runs.claude 启动
+  ${MANYOYO_NAME} update                   升级到最新版本
+
+配置文件: ~/.manyoyo/manyoyo.json (JSON5 格式，支持注释)
+各命令的更多用法: ${MANYOYO_NAME} <命令> --help
         `);
 
-    const runCommand = program.command('run').description('启动（容器不存在时）或连接（容器已存在时）容器并执行命令');
+    // 日常
+    program.command('update')
+        .helpGroup('日常:')
+        .description('升级到最新版本')
+        .option('--rollback', '回到上一版本')
+        .action(options => selectAction('update', { update: true, rollback: Boolean(options.rollback) }));
+
+    program.command('uninstall')
+        .helpGroup('日常:')
+        .description('卸载 MANYOYO（配置和数据默认保留）')
+        .option('--yes', '确认卸载程序本身，不再询问（不会删除配置、历史、日志、工作目录和外部运行时里的容器镜像）')
+        .action(options => selectAction('uninstall', options));
+
+    program.command('setup')
+        .helpGroup('日常:')
+        .description('命令行配置向导（无图形界面时使用）')
+        .action(() => selectAction('setup', {}));
+
+    program.command('doctor')
+        .helpGroup('日常:')
+        .description('诊断容器运行时、镜像、配置和端口')
+        .option('-r, --run <name>', '加载运行配置 (从 ~/.manyoyo/manyoyo.json 的 runs.<name> 读取)')
+        .option('--port <port>', '检查指定监听端口')
+        .option('--json', '以 JSON 输出稳定诊断结果')
+        .option('--fix', '自动修复可修复项（启动容器环境、拉取镜像、生成默认配置，端口占用时给出建议端口）')
+        .action(options => selectAction('doctor', { ...options, doctor: true }));
+
+    // 命令行运行
+    const runCommand = program.command('run').helpGroup('命令行运行:').description('启动容器并运行命令（容器已存在则连接）');
     runCommand.addHelpText('after', `
-Examples:
+示例:
   ${MANYOYO_NAME} run -r codex
+  ${MANYOYO_NAME} run -n test --ef /path/ab.env -y c
+  ${MANYOYO_NAME} run -n test -- -c
+  ${MANYOYO_NAME} run -r codex --ss "resume --last"
   ${MANYOYO_NAME} run --rm-on-exit -x /bin/bash -lc "node -v"
   ${MANYOYO_NAME} run -n demo --first-shell "npm ci" -s "npm test"
 
-Notes:
+-q 可选项（可多次使用）:
+  cnew     隐藏“创建/连接容器”提示
+  crm      隐藏“删除容器”提示
+  tip      隐藏首次命令与恢复会话提示
+  cmd      隐藏将执行的命令
+  askkeep  简化“是否保留容器”的提问
+  full     隐藏以上全部
+
+说明:
   参数优先级与合并规则（标量覆盖、数组追加、env 按 key 合并）请用 ${MANYOYO_NAME} config show --help 或查看文档。
 `);
     applyRunStyleOptions(runCommand);
@@ -1185,30 +1346,85 @@ Notes:
         selectAction('run', options);
     });
 
-    const buildCommand = program.command('build').description('构建 manyoyo 沙箱镜像');
+    const initCommand = program.command('init [agents]').helpGroup('命令行运行:').description('导入本机已有的 Agent 配置到 ~/.manyoyo');
+    initCommand
+        .option('--yes', '所有提示自动确认 (用于CI/脚本)')
+        .action((agents, options) => selectAction('init', { ...options, initConfig: agents === undefined ? 'all' : agents }));
+
+    const configCommand = program.command('config').helpGroup('命令行运行:').description('查看生效的配置或将执行的命令');
+    const configShowCommand = configCommand.command('show').description('显示最终生效的配置');
+    applyRunStyleOptions(configShowCommand, { includeRmOnExit: false, includeServePreview: true });
+    enableShellSuffixPassThrough(configShowCommand);
+    configShowCommand.action((options, command) => {
+        validateShellSuffixPassThroughArgs(command);
+        const finalOptions = {
+            ...options,
+            showConfig: true
+        };
+        if (options.serve !== undefined) {
+            finalOptions.server = options.serve;
+            finalOptions.serverUser = options.user;
+            finalOptions.serverPass = options.pass;
+        }
+        selectAction('config-show', finalOptions);
+    });
+
+    const configRunCommand = configCommand.command('command').description('显示将执行的容器命令');
+    applyRunStyleOptions(configRunCommand, { includeRmOnExit: false });
+    enableShellSuffixPassThrough(configRunCommand);
+    configRunCommand.action((options, command) => {
+        validateShellSuffixPassThroughArgs(command);
+        selectAction('config-command', options);
+    });
+
+    // 容器与镜像
+    program.command('ps')
+        .helpGroup('容器与镜像:')
+        .description('列出容器')
+        .action(() => selectAction('ps', { contList: true }));
+
+    program.command('images')
+        .helpGroup('容器与镜像:')
+        .description('列出镜像')
+        .action(() => selectAction('images', { imageList: true }));
+
+    const removeCommand = program.command('rm <name>').helpGroup('容器与镜像:').description('删除指定容器');
+    removeCommand
+        .option('-r, --run <name>', '加载运行配置 (从 ~/.manyoyo/manyoyo.json 的 runs.<name> 读取)')
+        .action((name, options) => selectAction('rm', { ...options, contName: name }));
+
+    const buildCommand = program.command('build').helpGroup('容器与镜像:').description('构建沙箱镜像');
     buildCommand
         .option('-r, --run <name>', '加载运行配置 (从 ~/.manyoyo/manyoyo.json 的 runs.<name> 读取)')
         .option('--in, --image-name <name>', '指定镜像名称')
-        .option('--iv, --image-ver <version>', '指定镜像版本 (格式: x.y.z-后缀，如 1.7.4-common)')
+        .option('--iv, --image-ver <version>', `指定镜像版本 (格式: x.y.z-后缀，如 ${IMAGE_VERSION_HELP_EXAMPLE})`)
         .option('--update-agents', '仅更新已有镜像内 Agent CLI 到 latest (Claude/Codex/Gemini/OpenCode)')
         .option('--yes', '所有提示自动确认 (用于CI/脚本)');
     appendArrayOption(buildCommand, '--iba, --image-build-arg <arg>', '构建镜像时传参给dockerfile (可多次使用)');
     buildCommand.action(options => selectAction('build', options));
 
-    const removeCommand = program.command('rm <name>').description('删除指定容器');
-    removeCommand
-        .option('-r, --run <name>', '加载运行配置 (从 ~/.manyoyo/manyoyo.json 的 runs.<name> 读取)')
-        .action((name, options) => selectAction('rm', { ...options, contName: name }));
-
-    program.command('ps')
-        .description('列举容器')
-        .action(() => selectAction('ps', { contList: true }));
-
-    program.command('images')
-        .description('列举镜像')
-        .action(() => selectAction('images', { imageList: true }));
+    program.command('prune')
+        .helpGroup('容器与镜像:')
+        .description('清理悬空镜像')
+        .action(() => selectAction('prune', { imageRemove: true }));
 
-    const serveCommand = program.command('serve [listen]').description('启动网页交互服务 (默认 127.0.0.1:3000)');
+    program.command('podman [args...]')
+        .helpGroup('容器与镜像:')
+        .description('用私有 Podman 执行命令（参数原样传入）')
+        .helpOption(false)
+        .allowUnknownOption()
+        .passThroughOptions()
+        .action(args => selectAction('podman', { podmanArgs: args || [] }));
+
+    // 网页服务与插件
+    const serveCommand = program.command('serve [listen]').helpGroup('网页服务与插件:').description('启动网页服务 (默认 127.0.0.1:3000)');
+    serveCommand.addHelpText('after', `
+示例:
+  ${MANYOYO_NAME} serve 127.0.0.1:3000                   启动本机网页服务
+  ${MANYOYO_NAME} serve 127.0.0.1:3000 -d                后台启动；未设密码时会打印本次随机密码
+  ${MANYOYO_NAME} serve 0.0.0.0:3000 -U admin -P <密码> -d  后台启动并监听全部网卡
+  ${MANYOYO_NAME} serve 0.0.0.0:3000 -U admin -P <密码> -d --restart  重启指定后台网页服务
+`);
     applyRunStyleOptions(serveCommand, { includeRmOnExit: false, includeWebAuthOptions: true });
     serveCommand.option('-d, --detach', '后台启动网页服务并立即返回');
     serveCommand.option('--stop', '停止后台网页服务；必须显式传入 listen');
@@ -1222,10 +1438,15 @@ Notes:
         });
     });
 
-    const playwrightCommand = program.command('playwright').description('管理 playwright 插件服务（推荐）');
+    const playwrightCommand = program.command('playwright').helpGroup('网页服务与插件:').description('管理 Playwright 插件服务');
+    playwrightCommand.addHelpText('after', `
+示例:
+  ${MANYOYO_NAME} playwright up mcp-host-headless     启动 MCP 宿主场景（默认/推荐）
+  ${MANYOYO_NAME} playwright up cli-host-headless     启动 CLI 宿主场景（供容器内 playwright-cli 附着）
+`);
     registerPlaywrightAliasCommands(playwrightCommand);
 
-    const pluginCommand = program.command('plugin').description('管理 manyoyo 插件');
+    const pluginCommand = program.command('plugin', { hidden: true }).description('管理 manyoyo 插件');
     pluginCommand.command('ls')
         .description('列出可用插件与启用场景')
         .option('-r, --run <name>', '加载运行配置 (从 ~/.manyoyo/manyoyo.json 的 runs.<name> 读取)')
@@ -1237,67 +1458,10 @@ Notes:
     const pluginPlaywrightCommand = pluginCommand.command('playwright').description('管理 playwright 插件服务');
     registerPlaywrightAliasCommands(pluginPlaywrightCommand);
 
-    const configCommand = program.command('config').description('查看解析后的配置或命令');
-    const configShowCommand = configCommand.command('show').description('显示最终生效配置并退出');
-    applyRunStyleOptions(configShowCommand, { includeRmOnExit: false, includeServePreview: true });
-    enableShellSuffixPassThrough(configShowCommand);
-    configShowCommand.action((options, command) => {
-        validateShellSuffixPassThroughArgs(command);
-        const finalOptions = {
-            ...options,
-            showConfig: true
-        };
-        if (options.serve !== undefined) {
-            finalOptions.server = options.serve;
-            finalOptions.serverUser = options.user;
-            finalOptions.serverPass = options.pass;
-        }
-        selectAction('config-show', finalOptions);
-    });
-
-    const configRunCommand = configCommand.command('command').description('显示将执行的 docker run 命令并退出');
-    applyRunStyleOptions(configRunCommand, { includeRmOnExit: false });
-    enableShellSuffixPassThrough(configRunCommand);
-    configRunCommand.action((options, command) => {
-        validateShellSuffixPassThroughArgs(command);
-        selectAction('config-command', options);
-    });
-
-    const initCommand = program.command('init [agents]').description('初始化 Agent 配置到 ~/.manyoyo');
-    initCommand
-        .option('--yes', '所有提示自动确认 (用于CI/脚本)')
-        .action((agents, options) => selectAction('init', { ...options, initConfig: agents === undefined ? 'all' : agents }));
-
-    program.command('doctor')
-        .description('诊断容器运行时、镜像、配置、Agent、模式、插件和端口')
-        .option('-r, --run <name>', '加载运行配置 (从 ~/.manyoyo/manyoyo.json 的 runs.<name> 读取)')
-        .option('--port <port>', '检查指定监听端口')
-        .option('--json', '以 JSON 输出稳定诊断结果')
-        .action(options => selectAction('doctor', { ...options, doctor: true }));
-
-    program.command('update')
-        .description('更新 MANYOYO（若检测为本地 file 安装则跳过）')
-        .action(() => selectAction('update', { update: true }));
-
-    program.command('install <name>')
-        .description(`安装 ${MANYOYO_NAME} 命令 (docker-cli-plugin)`)
-        .action(name => selectAction('install', { install: name }));
-
-    program.command('prune')
-        .description('清理悬空镜像和 <none> 镜像')
-        .action(() => selectAction('prune', { imageRemove: true }));
-
-    // Docker CLI plugin metadata check
-    if (maybeHandleDockerPluginMetadata(process.argv)) {
-        process.exit(0);
-    }
-
-    // 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
@@ -1330,16 +1494,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', '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);
     }
 
@@ -1483,6 +1689,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 || "",
@@ -1525,8 +1733,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,
@@ -1535,11 +1748,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);
@@ -1548,7 +1799,6 @@ Notes:
     if (isPsMode) { getContList(); process.exit(0); }
     if (isImagesMode) { getImageList(); process.exit(0); }
     if (isPruneMode) { pruneDanglingImages(); process.exit(0); }
-    if (selectedAction === 'install') { installManyoyo(options.install); process.exit(0); }
 
     return {
         yesMode,
@@ -1581,6 +1831,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,
@@ -1816,8 +2067,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;
 
@@ -1830,6 +2082,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);
@@ -1838,11 +2093,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);
 }
@@ -1875,7 +2134,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;
     }
@@ -1908,6 +2167,8 @@ async function createNewContainer(runtime) {
         process.exit(0);
     }
 
+    await ensureRunImage(runtime);
+
     // 使用数组参数执行命令（安全方式）
     try {
         const args = buildDockerRunArgs(runtime);
@@ -1920,6 +2181,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);
 
@@ -1942,6 +2210,7 @@ function buildDockerRunArgs(runtime) {
         containerEnvs: runtime.containerEnvs,
         containerVolumes: runtime.containerVolumes,
         containerPorts: runtime.containerPorts,
+        mirrors: runtime.mirrors,
         defaultCommand: runtime.execCommand
     });
 }
@@ -2017,9 +2286,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 });
     }
 }
 
@@ -2080,6 +2349,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();
@@ -2088,6 +2389,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,
@@ -2096,6 +2439,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,
@@ -2115,6 +2483,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'),
@@ -2129,6 +2498,9 @@ async function runWebServerMode(runtime) {
         logger: runtime.logger
     });
     writeServePidFile(runtime, serverHandle);
+    if (needRuntimeHeal) {
+        startServeRuntimeHeal();
+    }
     return serverHandle;
 }
 
@@ -2190,6 +2562,7 @@ async function main() {
                 yesMode: Boolean(modeState.yesMode),
                 updateAgents: Boolean(modeState.updateAgents),
                 dockerCmd: DOCKER_CMD,
+                dockerEnv: DOCKER_ENV,
                 rootDir: path.join(__dirname, '..'),
                 loadConfig,
                 runCmd,