@xcanwin/manyoyo 8.0.1 → 8.2.0

package/bin/manyoyo.js

@@ -7,7 +7,7 @@ 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');
@@ -50,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() {
@@ -71,11 +70,6 @@ function detectCommandName() {
     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';
 }
 
@@ -472,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);
     }
 }
@@ -849,24 +843,6 @@ async function ensureDocker(configuredRuntime, options = {}) {
     return true;
 }
 
-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);
-            }
-            fs.symlinkSync(MANYOYO_FILE, targetPath);
-            break;
-        default:
-            console.log("");
-    }
-    process.exit(0);
-}
-
 // 升级后让旧版本的后台服务退出（pid 必须确实是 manyoyo serve），下次执行 manyoyo 就会启动新版本
 function stopBackgroundApp({ quiet = false } = {}) {
     const pid = readPid(path.join(os.homedir(), '.manyoyo', 'serve', 'app.json'));
@@ -918,16 +894,8 @@ async function updateOfflineInstall(mode, options, globalConfig) {
     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 runtimeHint = appUpdate.describeRuntimeChange(appUpdate.readInstalledRecord(os.homedir()), result.manifest.runtime);
+    if (runtimeHint && appUpdate.markRuntimeHintShown(os.homedir(), result.manifest.runtime)) console.log(`${YELLOW}ℹ️  ${runtimeHint}${NC}`);
 
     // 新版本要求的镜像不存在就拉取；仍用旧镜像的容器只列出来，不动
     const imageName = String(globalConfig.imageName || 'ghcr.io/xcanwin/manyoyo');
@@ -1102,26 +1070,6 @@ function pruneDanglingImages() {
     });
 }
 
-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);
-    }
-}
-
 function normalizeShellFullArgv(argv) {
     const shellFullIndex = argv.findIndex(arg => arg === '-x' || arg === '--shell-full');
     if (shellFullIndex !== -1 && shellFullIndex < argv.length - 1) {
@@ -1183,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; 相对路径会报错)');
@@ -1200,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)');
 
@@ -1208,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
@@ -1313,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);
@@ -1362,60 +1346,13 @@ Notes:
         selectAction('run', options);
     });
 
-    const buildCommand = program.command('build').description('构建 manyoyo 沙箱镜像');
-    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('--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 }));
-
-    const serveCommand = program.command('serve [listen]').description('启动网页交互服务 (默认 127.0.0.1:3000)');
-    applyRunStyleOptions(serveCommand, { includeRmOnExit: false, includeWebAuthOptions: true });
-    serveCommand.option('-d, --detach', '后台启动网页服务并立即返回');
-    serveCommand.option('--stop', '停止后台网页服务；必须显式传入 listen');
-    serveCommand.option('--restart', '重启后台网页服务；必须显式传入 listen');
-    serveCommand.action((listen, options) => {
-        selectAction('serve', {
-            ...options,
-            server: listen === undefined ? true : listen,
-            serverUser: options.user,
-            serverPass: options.pass
-        });
-    });
-
-    const playwrightCommand = program.command('playwright').description('管理 playwright 插件服务（推荐）');
-    registerPlaywrightAliasCommands(playwrightCommand);
-
-    const pluginCommand = program.command('plugin').description('管理 manyoyo 插件');
-    pluginCommand.command('ls')
-        .description('列出可用插件与启用场景')
-        .option('-r, --run <name>', '加载运行配置 (从 ~/.manyoyo/manyoyo.json 的 runs.<name> 读取)')
-        .action(options => selectPluginAction({
-            action: 'ls',
-            pluginName: 'playwright',
-            scene: 'all'
-        }, options));
-    const pluginPlaywrightCommand = pluginCommand.command('playwright').description('管理 playwright 插件服务');
-    registerPlaywrightAliasCommands(pluginPlaywrightCommand);
+    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').description('查看解析后的配置或命令');
-    const configShowCommand = configCommand.command('show').description('显示最终生效配置并退出');
+    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) => {
@@ -1432,7 +1369,7 @@ Notes:
         selectAction('config-show', finalOptions);
     });
 
-    const configRunCommand = configCommand.command('command').description('显示将执行的 docker run 命令并退出');
+    const configRunCommand = configCommand.command('command').description('显示将执行的容器命令');
     applyRunStyleOptions(configRunCommand, { includeRmOnExit: false });
     enableShellSuffixPassThrough(configRunCommand);
     configRunCommand.action((options, command) => {
@@ -1440,55 +1377,86 @@ Notes:
         selectAction('config-command', options);
     });
 
-    program.command('uninstall')
-        .description('卸载离线包安装的 MANYOYO：停止服务，删除程序与 PATH 配置，用户数据逐项询问（--yes 不会删用户数据）')
-        .option('--yes', '确认卸载程序本身，不再询问（不会删除配置、历史、日志、工作目录和外部运行时里的容器镜像）')
-        .action(options => selectAction('uninstall', options));
+    // 容器与镜像
+    program.command('ps')
+        .helpGroup('容器与镜像:')
+        .description('列出容器')
+        .action(() => selectAction('ps', { contList: true }));
 
-    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('images')
+        .helpGroup('容器与镜像:')
+        .description('列出镜像')
+        .action(() => selectAction('images', { imageList: true }));
 
-    program.command('doctor')
-        .description('诊断容器运行时、镜像、配置、Agent、模式、插件和端口')
+    const removeCommand = program.command('rm <name>').helpGroup('容器与镜像:').description('删除指定容器');
+    removeCommand
         .option('-r, --run <name>', '加载运行配置 (从 ~/.manyoyo/manyoyo.json 的 runs.<name> 读取)')
-        .option('--port <port>', '检查指定监听端口')
-        .option('--json', '以 JSON 输出稳定诊断结果')
-        .option('--fix', '自动修复可修复项（启动容器环境、拉取镜像、生成默认配置，端口占用时给出建议端口）')
-        .action(options => selectAction('doctor', { ...options, doctor: true }));
+        .action((name, options) => selectAction('rm', { ...options, contName: name }));
 
-    program.command('update')
-        .description('更新 MANYOYO（离线包安装只下载变化部分并保留上一版本；若检测为本地 file 安装则跳过）')
-        .option('--rollback', '离线包安装：切回上一版本')
-        .action(options => selectAction('update', { update: true, rollback: Boolean(options.rollback) }));
+    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-后缀，如 ${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));
+
+    program.command('prune')
+        .helpGroup('容器与镜像:')
+        .description('清理悬空镜像')
+        .action(() => selectAction('prune', { imageRemove: true }));
 
     program.command('podman [args...]')
-        .description('用 MANYOYO 的私有 Podman 执行命令（参数原样传给 podman）；eval "$(manyoyo podman env)" 可在当前终端定义 podman 函数')
+        .helpGroup('容器与镜像:')
+        .description('用私有 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)`)
-        .action(name => selectAction('install', { install: name }));
-
-    program.command('prune')
-        .description('清理悬空镜像和 <none> 镜像')
-        .action(() => selectAction('prune', { imageRemove: true }));
+    // 网页服务与插件
+    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');
+    serveCommand.option('--restart', '重启后台网页服务；必须显式传入 listen');
+    serveCommand.action((listen, options) => {
+        selectAction('serve', {
+            ...options,
+            server: listen === undefined ? true : listen,
+            serverUser: options.user,
+            serverPass: options.pass
+        });
+    });
 
-    // Docker CLI plugin metadata check
-    if (maybeHandleDockerPluginMetadata(process.argv)) {
-        process.exit(0);
-    }
+    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);
 
-    // Docker CLI plugin mode - remove first arg if running as plugin
-    normalizeDockerPluginArgv(process.argv);
+    const pluginCommand = program.command('plugin', { hidden: true }).description('管理 manyoyo 插件');
+    pluginCommand.command('ls')
+        .description('列出可用插件与启用场景')
+        .option('-r, --run <name>', '加载运行配置 (从 ~/.manyoyo/manyoyo.json 的 runs.<name> 读取)')
+        .action(options => selectPluginAction({
+            action: 'ls',
+            pluginName: 'playwright',
+            scene: 'all'
+        }, options));
+    const pluginPlaywrightCommand = pluginCommand.command('playwright').description('管理 playwright 插件服务');
+    registerPlaywrightAliasCommands(pluginPlaywrightCommand);
 
     // 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));
@@ -1528,7 +1496,7 @@ Notes:
 
     UPDATE_CHECK_ENABLED = config.updateCheck !== false;
     MIRRORS = normalizeMirrors(config.mirrors);
-    const noDockerActions = new Set(['init', 'update', 'install', 'config-show', 'plugin', 'doctor', 'uninstall', 'podman', 'setup']);
+    const noDockerActions = new Set(['init', 'update', 'config-show', 'plugin', 'doctor', 'uninstall', 'podman', 'setup']);
     if (isServerStopMode) {
         noDockerActions.add('serve');
     }
@@ -1831,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,

package/lib/app-update.js

@@ -125,11 +125,11 @@ function parseSha256Sums(text) {
     return result;
 }
 
+// Release 里只有一个校验清单 SHA256SUMS，列出全部安装包与升级包
 function releaseAssetNames(version, targetArch, targetOs = 'macos') {
     return {
         app: `manyoyo-${version}-${targetOs}-${targetArch}-app.tar.gz`,
-        sums: `SHA256SUMS-${targetOs}-${targetArch}`,
-        manifest: `release-manifest-${targetOs}-${targetArch}.json`
+        sums: 'SHA256SUMS'
     };
 }
 
@@ -189,7 +189,7 @@ function pruneApps(appRoot, keep) {
 async function installAppUpdate({ appRoot, release, fetchImpl = fetch, targetArch = arch(), targetOs = 'macos', run = defaultRun, log = () => {}, tmpRoot = os.tmpdir() }) {
     const names = releaseAssetNames(release.version, targetArch, targetOs);
     const appUrl = release.assets[names.app];
-    const sumsUrl = release.assets[names.sums] || release.assets.SHA256SUMS;
+    const sumsUrl = release.assets[names.sums];
     if (!appUrl || !sumsUrl) {
         throw new UpdateError('NO_ASSET', `Release ${release.version} 里没有适合这台机器（${targetOs}-${targetArch}）的升级包（需要 ${names.app} 与 ${names.sums}）。`);
     }
@@ -262,20 +262,40 @@ function rollbackApp({ appRoot }) {
 
 /**
  * Podman / VM 磁盘版本变化只提示，不自动替换（需要下载新的完整包）。
- * installed：安装器写的 ~/.manyoyo/.install/installed.json；remoteManifest：Release 里的 release-manifest（含完整包 manifest）。
+ * installed：安装器写的 ~/.manyoyo/.install/installed.json；remoteRuntime：升级包 manifest.json 里的 runtime（{ podmanVersion, vmDiskSha256 }，仅 macOS 包有）。
  */
-function describeRuntimeChange(installed, remoteManifest) {
-    const remote = remoteManifest && remoteManifest.manifest && remoteManifest.manifest.components;
-    if (!installed || !installed.podmanVersion || !remote || !remote.podman) return '';
-    const podmanChanged = remote.podman.version !== installed.podmanVersion;
-    const vmChanged = Boolean(installed.vmDiskSha256) && remote.vmDisk && remote.vmDisk.sha256 !== installed.vmDiskSha256;
+function describeRuntimeChange(installed, remoteRuntime) {
+    if (!installed || !installed.podmanVersion || !remoteRuntime || !remoteRuntime.podmanVersion) return '';
+    const podmanChanged = remoteRuntime.podmanVersion !== installed.podmanVersion;
+    const vmChanged = Boolean(installed.vmDiskSha256) && Boolean(remoteRuntime.vmDiskSha256) && remoteRuntime.vmDiskSha256 !== installed.vmDiskSha256;
     if (!podmanChanged && !vmChanged) return '';
     const parts = [];
-    if (podmanChanged) parts.push(`Podman ${installed.podmanVersion} → ${remote.podman.version}`);
+    if (podmanChanged) parts.push(`Podman ${installed.podmanVersion} → ${remoteRuntime.podmanVersion}`);
     if (vmChanged) parts.push('虚拟机磁盘有更新');
     return `新版本捆绑的运行环境有变化（${parts.join('，')}）。本次只升级了 manyoyo 本体；要换 Podman / 虚拟机，请下载新的完整安装包重新安装。`;
 }
 
+/**
+ * 同一份新运行环境的提示只显示一次（每次 update 都重复提示只是噪音）：
+ * 记下已提示过的 runtime（~/.manyoyo/.install/runtime-hint.json），返回这次是否应该显示。
+ */
+function markRuntimeHintShown(homeDir, runtime) {
+    const file = path.join(homeDir, '.manyoyo', '.install', 'runtime-hint.json');
+    const key = JSON.stringify({ podmanVersion: runtime && runtime.podmanVersion || '', vmDiskSha256: runtime && runtime.vmDiskSha256 || '' });
+    try {
+        if (fs.readFileSync(file, 'utf-8').trim() === key) return false;
+    } catch (error) {
+        // 没有记录或记录损坏：当作没提示过
+    }
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, `${key}\n`);
+    } catch (error) {
+        // 记录写不进去不影响升级，最多下次再提示一次
+    }
+    return true;
+}
+
 function readInstalledRecord(homeDir) {
     try {
         return JSON.parse(fs.readFileSync(path.join(homeDir, '.manyoyo', '.install', 'installed.json'), 'utf-8'));
@@ -317,6 +337,7 @@ module.exports = {
     rollbackApp,
     currentVersion,
     describeRuntimeChange,
+    markRuntimeHintShown,
     readInstalledRecord,
     findOutdatedContainers,
     fetchText,

package/lib/podman-passthrough.js

@@ -48,14 +48,14 @@ function runPodmanCommand(args, options = {}) {
     const commandName = options.commandName || 'manyoyo';
     const paths = getPrivatePodmanPaths(options.homeDir);
     const exists = options.exists || (file => require('fs').existsSync(file));
-    if (!exists(paths.bin)) {
-        errLog(`没有找到 ${commandName} 的私有 Podman（${paths.bin}）。当前没有使用私有 Podman：离线完整包安装后才有；使用你自己的 docker / podman 时直接用它们即可。`);
-        return 1;
-    }
     if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
         log(usageText(commandName));
         return 0;
     }
+    if (!exists(paths.bin)) {
+        errLog(`没有找到 ${commandName} 的私有 Podman（${paths.bin}）。当前没有使用私有 Podman：离线完整包安装后才有；使用你自己的 docker / podman 时直接用它们即可。`);
+        return 1;
+    }
     if (args[0] === 'env') {
         const rest = args.slice(1);
         let shell = '';

package/lib/web/AGENTS.md

@@ -1,6 +1,6 @@
 # lib/web/ 协作指引
 
-根目录 `AGENTS.md` 的补充，仅在改动 Web 服务端时适用。前端在 `frontend-shadcn/`，见该目录的 `AGENTS.md`。
+根目录 `AGENTS.md` 的补充，仅在改动 Web 服务端时适用。前端在 `frontend/`，见该目录的 `AGENTS.md`。
 
 ## lib/web/server.js（6000+ 行单文件）
 
@@ -9,7 +9,7 @@
 - `resolveYoloCommand()` 委托到 `lib/agent-adapters/index.js`，与 `bin/manyoyo.js` 共用同一份映射，无需分别维护。
 - Agent 会话恢复参数：Claude/Gemini → `-r`，Codex → `resume`，OpenCode → `-c`。
 - 会话控制事件：`/agent/stream`、`/agent/stop` 通过 `createWebStreamEmitter()` / `appendWebSessionControlEvent()` 写入 `lib/core/event-store.js`（`FileEventStore`），`GET /api/sessions/:name/audit` 导出该会话的事件与投影。
-- **`/agent/stream` 的 NDJSON 事件协议是跨前后端的契约**，改一处必须同步另一处：服务端 `lib/web/server.js`、前端 `frontend-shadcn/src/lib/api.ts` 的 `StreamEvent` + `workspace-panel.tsx` 的事件分支
+- **`/agent/stream` 的 NDJSON 事件协议是跨前后端的契约**，改一处必须同步另一处：服务端 `lib/web/server.js`、前端 `frontend/src/lib/api.ts` 的 `StreamEvent` + `workspace-panel.tsx` 的事件分支
   - `content_chunk`：token 级增量，前端**追加**；`reset: true` 表示换了一条 assistant 消息、从空白重新开始。只发新增片段，不要改成重发累计全文（几千个增量就是 O(n²) 流量）。
   - `content_delta`：每条 assistant 消息落地时下发一次的权威全文，前端**整体覆盖**。
   - `trace`：**不保证带结构化 `traceEvent`**。stderr 行（`emitStderrTraceLine`）和解析不出 JSON 的 stdout 行只有 `text` + `stream`，前端靠 `toTraceEvent()` 兜底成 `kind="output"` 的事件展示。新增只认 `traceEvent` 的分支等于把自定义 CLI、CLI 报错的输出全吞掉。
@@ -21,11 +21,9 @@
 - 空闲保活是 `/agent/stream` 那条心跳规则的同类问题，**两个入口都要守**：终端侧服务端每 `WEB_TERMINAL_PING_INTERVAL_MS`（30s）发 WebSocket ping 帧，连续 `WEB_TERMINAL_MAX_MISSED_PONGS`（3 次，约 90s）无 pong 才判死；前端另发应用层 `ping`（浏览器 JS 发不出 ping 帧，上行需要自己造流量）。判死阈值不要收紧到一个周期：手机切后台会让连接短暂挂起，误杀等于用户的 shell 没了。升级后的 socket 还要 `setTimeout(0)` + `setKeepAlive`，解除 HTTP 侧空闲超时。
 - 新增接口/页面必须走全局认证网关，禁止在业务路由里零散补认证；匿名白名单见根 `AGENTS.md` 的安全约束。
 
-## lib/web/frontend/
+## lib/web/index.html
 
-只剩一个文件：`shadcn.html`，是 `npm run build:web-shadcn` 的产物（已 `.gitignore`），由 `loadTemplate()` 在每次请求时读取。服务端不再托管其它前端静态资源，别往这个目录里放新的散装 js/css。
-
-目录里没有任何被跟踪的文件，而 git 不记录空目录——**全新检出（CI、别人第一次 clone）是没有 `lib/web/frontend/` 这个目录的**。任何往这里写文件的构建步骤都必须自己 `mkdir -p`（见 `frontend-shadcn/scripts/emit-shadcn-html.mjs`），否则本地有目录跑得好好的，CI 上直接 ENOENT。
+前端构建产物（`npm run build:web`，已 `.gitignore`），由 `loadIndexHtml()` 在每次请求时读取，`/` 与登录页 `/auth/login` 共用。服务端不托管其它前端静态资源，别往 `lib/web/` 里放散装 js/css。
 
 ## 测试