@xcanwin/manyoyo 5.3.1 → 5.3.6

package/README.md

@@ -46,7 +46,7 @@
 ```bash
 npm install -g @xcanwin/manyoyo    # 安装
 podman pull ubuntu:24.04           # 仅 Podman 需要
-manyoyo build --iv 1.8.0-common     # 构建镜像
+manyoyo build --iv 1.8.4-common     # 构建镜像
 manyoyo init all          # 从本机 Agent 配置迁移到 ~/.manyoyo
 manyoyo run -r claude                  # 使用 manyoyo.json 的 runs.claude 启动
 ```
@@ -97,10 +97,10 @@ npm install -g @xcanwin/manyoyo
 
 ```bash
 # 构建 common 版本（推荐）
-manyoyo build --iv 1.8.0-common
+manyoyo build --iv 1.8.4-common
 
 # 构建 full 版本
-manyoyo build --iv 1.8.0-full
+manyoyo build --iv 1.8.4-full
 
 # 构建自定义版本
 manyoyo build --iba TOOL=go,codex,java,gemini
@@ -126,8 +126,8 @@ manyoyo ps
 manyoyo images
 manyoyo run -n my-dev -x /bin/bash
 manyoyo rm my-dev
-manyoyo serve 3000
-manyoyo serve 3000 -u admin -P 123456
+manyoyo serve 127.0.0.1:3000
+manyoyo serve 127.0.0.1:3000 -U admin -P 123456
 
 # 调试配置与命令拼装
 manyoyo config show
@@ -136,7 +136,7 @@ manyoyo config command
 
 ## 配置
 
-配置优先级：命令行参数 > runs.<name> > 全局配置 > 默认值  
+配置优先级：命令行参数 > runs.<name> > 全局配置 > 默认值
 详细说明请参考：
 - [配置系统概览](https://xcanwin.github.io/manyoyo/zh/configuration/)
 - [环境变量详解](https://xcanwin.github.io/manyoyo/zh/configuration/environment)

package/bin/manyoyo.js

@@ -15,6 +15,7 @@ const { initAgentConfigs } = require('../lib/init-config');
 const { buildImage } = require('../lib/image-build');
 const { resolveAgentResumeArg, buildAgentResumeCommand } = require('../lib/agent-resume');
 const { runPluginCommand } = require('../lib/plugin');
+const { buildManyoyoLogPath } = require('../lib/log-path');
 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`;
@@ -122,13 +123,12 @@ function mergeArrayConfig(globalValue, runValue, cliValue) {
 function validateServerHost(host, rawServer) {
     const value = String(host || '').trim();
     const isIp = net.isIP(value) !== 0;
-    const isHostName = /^[A-Za-z0-9.-]+$/.test(value);
 
-    if (isIp || isHostName) {
+    if (isIp) {
         return value;
     }
 
-    console.error(`${RED}⚠️  错误: serve 地址格式应为 端口 或 host:port (例如 3000 / 0.0.0.0:3000): ${rawServer}${NC}`);
+    console.error(`${RED}⚠️  错误: serve 地址格式必须为 <ip:port> (例如 127.0.0.1:3000 / 0.0.0.0:3000): ${rawServer}${NC}`);
     process.exit(1);
 }
 
@@ -142,8 +142,8 @@ function parseServerListen(rawServer) {
         return { host: '127.0.0.1', port: 3000 };
     }
 
-    let host = '127.0.0.1';
-    let portText = value;
+    let host = '';
+    let portText = '';
 
     const ipv6Match = value.match(/^\[([^\]]+)\]:(\d+)$/);
     if (ipv6Match) {
@@ -151,12 +151,14 @@ function parseServerListen(rawServer) {
         portText = ipv6Match[2].trim();
     } else {
         const lastColonIndex = value.lastIndexOf(':');
-        if (lastColonIndex > 0) {
-            const maybePort = value.slice(lastColonIndex + 1).trim();
-            if (/^\d+$/.test(maybePort)) {
-                host = value.slice(0, lastColonIndex).trim();
-                portText = maybePort;
-            }
+        if (lastColonIndex <= 0) {
+            console.error(`${RED}⚠️  错误: serve 地址格式必须为 <ip:port> (例如 127.0.0.1:3000 / 0.0.0.0:3000): ${rawServer}${NC}`);
+            process.exit(1);
+        }
+        const maybePort = value.slice(lastColonIndex + 1).trim();
+        if (/^\d+$/.test(maybePort)) {
+            host = value.slice(0, lastColonIndex).trim();
+            portText = maybePort;
         }
     }
 
@@ -231,6 +233,138 @@ function sanitizeSensitiveData(obj) {
     return result;
 }
 
+function stripAnsi(text) {
+    if (typeof text !== 'string') return '';
+    return text.replace(/\x1b\[[0-9;]*m/g, '');
+}
+
+function sanitizeServeLogText(input) {
+    let text = stripAnsi(String(input || ''));
+    if (!text) return text;
+
+    text = text.replace(/(--pass|-P)\s+\S+/gi, '$1 ****');
+    text = text.replace(
+        /\b(MANYOYO_SERVER_PASS|OPENAI_API_KEY|ANTHROPIC_AUTH_TOKEN|GEMINI_API_KEY|GOOGLE_API_KEY|OPENCODE_API_KEY)\s*=\s*([^\s'"]+)/gi,
+        '$1=****'
+    );
+    text = text.replace(
+        /("?(?:password|pass|token|api[_-]?key|authorization|cookie)"?\s*[:=]\s*)("[^"]*"|'[^']*'|[^,\s]+)/gi,
+        '$1"****"'
+    );
+    return text;
+}
+
+function formatServeLogValue(value) {
+    if (value instanceof Error) {
+        return sanitizeServeLogText(value.stack || value.message || String(value));
+    }
+    if (typeof value === 'object' && value !== null) {
+        try {
+            return sanitizeServeLogText(JSON.stringify(sanitizeSensitiveData(value)));
+        } catch (e) {
+            return sanitizeServeLogText(String(value));
+        }
+    }
+    return sanitizeServeLogText(String(value));
+}
+
+function getServeProcessSnapshot() {
+    return {
+        pid: process.pid,
+        ppid: process.ppid,
+        cwd: process.cwd(),
+        argv: Array.isArray(process.argv) ? process.argv.slice() : []
+    };
+}
+
+function createServeLogger() {
+    function formatLocalTimestamp(date = new Date()) {
+        const y = date.getFullYear();
+        const m = String(date.getMonth() + 1).padStart(2, '0');
+        const d = String(date.getDate()).padStart(2, '0');
+        const hh = String(date.getHours()).padStart(2, '0');
+        const mm = String(date.getMinutes()).padStart(2, '0');
+        const ss = String(date.getSeconds()).padStart(2, '0');
+        const ms = String(date.getMilliseconds()).padStart(3, '0');
+        const offsetMinutes = -date.getTimezoneOffset();
+        const sign = offsetMinutes >= 0 ? '+' : '-';
+        const abs = Math.abs(offsetMinutes);
+        const offH = String(Math.floor(abs / 60)).padStart(2, '0');
+        const offM = String(abs % 60).padStart(2, '0');
+        return `${y}-${m}-${d}T${hh}:${mm}:${ss}.${ms}${sign}${offH}:${offM}`;
+    }
+
+    const serveLog = buildManyoyoLogPath('serve');
+    const logDir = serveLog.dir;
+    fs.mkdirSync(logDir, { recursive: true });
+    const logPath = serveLog.path;
+
+    function write(level, message, extra) {
+        const ts = formatLocalTimestamp();
+        const parts = [
+            `[${ts}]`,
+            `[pid:${process.pid}]`,
+            `[${String(level || 'INFO').toUpperCase()}]`,
+            formatServeLogValue(message)
+        ];
+        if (extra !== undefined) {
+            parts.push(formatServeLogValue(extra));
+        }
+        fs.appendFileSync(logPath, `${parts.join(' ')}\n`);
+    }
+
+    return {
+        path: logPath,
+        info: (message, extra) => write('INFO', message, extra),
+        warn: (message, extra) => write('WARN', message, extra),
+        error: (message, extra) => write('ERROR', message, extra)
+    };
+}
+
+function installServeProcessDiagnostics(logger) {
+    if (!logger || typeof logger.info !== 'function') return;
+    if (global.__manyoyoServeDiagInstalled) return;
+    global.__manyoyoServeDiagInstalled = true;
+
+    const signalExitCode = {
+        SIGINT: 130,
+        SIGTERM: 143,
+        SIGHUP: 129
+    };
+
+    process.on('uncaughtException', err => {
+        logger.error('uncaughtException', {
+            error: err,
+            process: getServeProcessSnapshot()
+        });
+        process.exit(1);
+    });
+
+    process.on('unhandledRejection', reason => {
+        logger.error('unhandledRejection', {
+            reason,
+            process: getServeProcessSnapshot()
+        });
+        process.exit(1);
+    });
+
+    ['SIGINT', 'SIGTERM', 'SIGHUP'].forEach(signal => {
+        process.on(signal, () => {
+            logger.warn(`received ${signal}, process will exit`, {
+                signal,
+                process: getServeProcessSnapshot()
+            });
+            process.exit(signalExitCode[signal] || 1);
+        });
+    });
+
+    process.on('exit', code => {
+        logger.info(`process exit with code=${code}`, {
+            process: getServeProcessSnapshot()
+        });
+    });
+}
+
 /**
  * @typedef {Object} Config
  * @property {string} [containerName] - 容器名称
@@ -838,41 +972,46 @@ function applyRunStyleOptions(command, options = {}) {
 
     command
         .option('-r, --run <name>', '加载运行配置 (从 ~/.manyoyo/manyoyo.json 的 runs.<name> 读取)')
-        .option('--hp, --host-path <path>', '设置宿主机工作目录 (默认当前路径)')
+        .option('--hp, --host-path <path>', '设置宿主机工作目录 (默认: 当前路径)')
         .option('-n, --cont-name <name>', '设置容器名称')
         .option('--cp, --cont-path <path>', '设置容器工作目录')
-        .option('-m, --cont-mode <mode>', '设置容器嵌套容器模式 (common, dind, sock)')
+        .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)');
 
     appendArrayOption(command, '-e, --env <env>', '设置环境变量 XXX=YYY (可多次使用)');
-    appendArrayOption(command, '--ef, --env-file <file>', '设置环境变量通过文件 (仅支持绝对路径，如 /abs/path.env)');
+    appendArrayOption(command, '--ef, --env-file <file>', '从环境文件加载变量 (仅支持绝对路径，如 /abs/path.env; 相对路径会报错)');
     appendArrayOption(command, '-v, --volume <volume>', '绑定挂载卷 XXX:YYY (可多次使用)');
     appendArrayOption(command, '-p, --port <port>', '设置端口映射 XXX:YYY (可多次使用)');
 
     command
-        .option('--sp, --shell-prefix <command>', '临时环境变量 (作为-s前缀)')
-        .option('-s, --shell <command>', '指定命令执行')
-        .option('--ss, --shell-suffix <command>', '指定命令后缀 (追加到-s之后，等价于 -- <args>)')
-        .option('-x, --shell-full <command...>', '指定完整命令执行 (代替--sp和-s和--命令)')
-        .option('-y, --yolo <cli>', '使AGENT无需确认 (claude/c, gemini/gm, codex/cx, opencode/oc)');
+        .option('--sp, --shell-prefix <command>', '主命令前缀 (常用于临时环境变量)')
+        .option('-s, --shell <command>', '主命令')
+        .option('--ss, --shell-suffix <command>', '主命令后缀 (追加到 -s 之后，等价于 -- <args>)')
+        .option('--first-shell-prefix <command>', '首次预执行命令前缀 (仅新建容器生效; 容器已存在时忽略)')
+        .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))');
+    appendArrayOption(command, '--first-env <env>', '首次预执行环境变量 XXX=YYY (可多次使用)');
+    appendArrayOption(command, '--first-env-file <file>', '首次预执行环境变量文件 (仅支持绝对路径，如 /abs/path.env)');
 
     if (includeRmOnExit) {
         command.option('--rm-on-exit', '退出后自动删除容器 (一次性模式)');
     }
 
-    appendArrayOption(command, '-q, --quiet <item>', '静默显示 (可多次使用: cnew,crm,tip,cmd,full)');
+    appendArrayOption(command, '-q, --quiet <item>', '静默输出 (可多次使用: cnew, crm, tip, cmd, full)');
 
     if (includeServePreview) {
         command
-            .option('--serve [listen]', '按 serve 模式解析配置 (支持 port 或 host:port)')
-            .option('-u, --user <username>', '网页服务登录用户名 (默认 admin)')
+            .option('--serve [listen]', '按 serve 模式解析配置 (仅支持 <ip:port>)')
+            .option('-U, --user <username>', '网页服务登录用户名 (默认 admin)')
             .option('-P, --pass <password>', '网页服务登录密码 (默认自动生成随机密码)');
     }
 
     if (includeWebAuthOptions) {
         command
-            .option('-u, --user <username>', '网页服务登录用户名 (默认 admin)')
+            .option('-U, --user <username>', '网页服务登录用户名 (默认 admin)')
             .option('-P, --pass <password>', '网页服务登录密码 (默认自动生成随机密码)');
     }
 
@@ -917,7 +1056,7 @@ async function setupCommander() {
         const actions = ['up', 'down', 'status', 'health', 'logs'];
         actions.forEach(action => {
             const sceneCommand = command.command(`${action} [scene]`)
-                .description(`${action} playwright 场景，scene 默认 host-headless`)
+                .description(`执行 playwright ${action} 场景（scene 默认 host-headless）`)
                 .option('-r, --run <name>', '加载运行配置 (从 ~/.manyoyo/manyoyo.json 的 runs.<name> 读取)');
 
             if (action === 'up') {
@@ -962,14 +1101,14 @@ async function setupCommander() {
         .description('MANYOYO - AI Agent CLI Sandbox\nhttps://github.com/xcanwin/manyoyo')
         .addHelpText('after', `
 配置文件:
-  ~/.manyoyo/manyoyo.json    全局配置文件 (JSON5格式，支持注释)
-  ~/.manyoyo/run/c.json      运行配置示例
+  ~/.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...>    → 直接透传命令后缀（优先级最高）
+  run -r name               → ~/.manyoyo/manyoyo.json 的 runs.name
+  run --ef /abs/path.env    → 绝对路径环境文件
+  run --ss "<args>"         → 显式设置命令后缀
+  run -- <args...>          → 直接透传命令后缀（优先级最高）
 
 示例:
   ${MANYOYO_NAME} update                              更新 MANYOYO 到最新版本
@@ -977,17 +1116,26 @@ async function setupCommander() {
   ${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 /abs/path/myenv.env -y c  使用绝对路径环境变量文件
+  ${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 3000 -u admin -P 123456       启动带登录认证的网页服务
-  ${MANYOYO_NAME} serve 0.0.0.0:3000                  监听全部网卡，便于局域网访问
+  ${MANYOYO_NAME} run -x "echo 123"                   使用完整命令
+  ${MANYOYO_NAME} serve 127.0.0.1:3000                启动本机网页服务
+  ${MANYOYO_NAME} serve 0.0.0.0:3000 -U admin -P 123 &>/dev/null &  后台启动并监听全部网卡
   ${MANYOYO_NAME} playwright up host-headless         启动 playwright 默认场景（推荐）
   ${MANYOYO_NAME} plugin playwright up host-headless  通过 plugin 命名空间启动
   ${MANYOYO_NAME} run -n test -q tip -q cmd           多次使用静默选项
         `);
 
-    const runCommand = program.command('run').description('启动或连接容器并执行命令');
+    const runCommand = program.command('run').description('启动（容器不存在时）或连接（容器已存在时）容器并执行命令');
+    runCommand.addHelpText('after', `
+Examples:
+  ${MANYOYO_NAME} run -r codex
+  ${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:
+  参数优先级与合并规则（标量覆盖、数组追加、env 按 key 合并）请用 ${MANYOYO_NAME} config show --help 或查看文档。
+`);
     applyRunStyleOptions(runCommand);
     runCommand.action(options => selectAction('run', options));
 
@@ -1069,7 +1217,7 @@ async function setupCommander() {
         .action(() => selectAction('update', { update: true }));
 
     program.command('install <name>')
-        .description(`安装${MANYOYO_NAME}命令 (docker-cli-plugin)`)
+        .description(`安装 ${MANYOYO_NAME} 命令 (docker-cli-plugin)`)
         .action(name => selectAction('install', { install: name }));
 
     program.command('prune')
@@ -1184,15 +1332,15 @@ async function setupCommander() {
     if (mergedShellSuffix) {
         EXEC_COMMAND_SUFFIX = normalizeCommandSuffix(mergedShellSuffix);
     }
-    const mergedFirstShellPrefix = pickConfigValue(runFirstConfig.shellPrefix, globalFirstConfig.shellPrefix);
+    const mergedFirstShellPrefix = pickConfigValue(options.firstShellPrefix, runFirstConfig.shellPrefix, globalFirstConfig.shellPrefix);
     if (mergedFirstShellPrefix) {
         FIRST_EXEC_COMMAND_PREFIX = `${mergedFirstShellPrefix} `;
     }
-    const mergedFirstShell = pickConfigValue(runFirstConfig.shell, globalFirstConfig.shell);
+    const mergedFirstShell = pickConfigValue(options.firstShell, runFirstConfig.shell, globalFirstConfig.shell);
     if (mergedFirstShell) {
         FIRST_EXEC_COMMAND = mergedFirstShell;
     }
-    const mergedFirstShellSuffix = pickConfigValue(runFirstConfig.shellSuffix, globalFirstConfig.shellSuffix);
+    const mergedFirstShellSuffix = pickConfigValue(options.firstShellSuffix, runFirstConfig.shellSuffix, globalFirstConfig.shellSuffix);
     if (mergedFirstShellSuffix) {
         FIRST_EXEC_COMMAND_SUFFIX = normalizeCommandSuffix(mergedFirstShellSuffix);
     }
@@ -1221,13 +1369,15 @@ async function setupCommander() {
 
     const firstEnvFileList = [
         ...toArray(globalFirstConfig.envFile),
-        ...toArray(runFirstConfig.envFile)
+        ...toArray(runFirstConfig.envFile),
+        ...(options.firstEnvFile || [])
     ].filter(Boolean);
     firstEnvFileList.forEach(ef => addEnvFileTo(FIRST_CONTAINER_ENVS, ef));
 
     const firstEnvMap = {
         ...normalizeJsonEnvMap(globalFirstConfig.env, '全局配置 first'),
-        ...normalizeJsonEnvMap(runFirstConfig.env, '运行配置 first')
+        ...normalizeJsonEnvMap(runFirstConfig.env, '运行配置 first'),
+        ...normalizeCliEnvMap(options.firstEnv)
     };
     Object.entries(firstEnvMap).forEach(([key, value]) => addEnvTo(FIRST_CONTAINER_ENVS, `${key}=${value}`));
 
@@ -1378,7 +1528,8 @@ function createRuntimeContext(modeState = {}) {
         serverPort: SERVER_PORT,
         serverAuthUser: SERVER_AUTH_USER,
         serverAuthPass: SERVER_AUTH_PASS,
-        serverAuthPassAuto: SERVER_AUTH_PASS_AUTO
+        serverAuthPassAuto: SERVER_AUTH_PASS_AUTO,
+        logger: null
     };
 }
 
@@ -1716,7 +1867,8 @@ async function runWebServerMode(runtime) {
             BLUE,
             CYAN,
             NC
-        }
+        },
+        logger: runtime.logger
     });
 }
 
@@ -1740,6 +1892,16 @@ async function main() {
 
         // 2. Start web server mode
         if (runtime.serverMode) {
+            const serveLogger = createServeLogger();
+            runtime.logger = serveLogger;
+            installServeProcessDiagnostics(serveLogger);
+            serveLogger.info('serve startup requested', {
+                host: runtime.serverHost,
+                port: runtime.serverPort,
+                user: runtime.serverAuthUser || 'admin(auto/default)',
+                process: getServeProcessSnapshot()
+            });
+            console.log(`${CYAN}📝 serve 日志文件: ${YELLOW}${serveLogger.path}${NC}`);
             await runWebServerMode(runtime);
             return;
         }

package/lib/log-path.js

@@ -0,0 +1,41 @@
+const os = require('os');
+const path = require('path');
+
+function pad2(n) {
+    return String(n).padStart(2, '0');
+}
+
+function getLocalDateTag(date = new Date()) {
+    const y = date.getFullYear();
+    const m = pad2(date.getMonth() + 1);
+    const d = pad2(date.getDate());
+    return `${y}-${m}-${d}`;
+}
+
+function normalizeLogScope(scope) {
+    return String(scope || 'general')
+        .trim()
+        .replace(/[^A-Za-z0-9_.-]+/g, '-')
+        .replace(/^-+|-+$/g, '') || 'general';
+}
+
+function buildManyoyoLogPath(scope, date = new Date(), homeDir = os.homedir()) {
+    const safeScope = normalizeLogScope(scope);
+    const rootDir = path.join(homeDir, '.manyoyo', 'logs');
+    const dir = path.join(rootDir, safeScope);
+    const file = `${safeScope}-${getLocalDateTag(date)}.log`;
+
+    return {
+        rootDir,
+        dir,
+        path: path.join(dir, file),
+        scope: safeScope,
+        file
+    };
+}
+
+module.exports = {
+    getLocalDateTag,
+    normalizeLogScope,
+    buildManyoyoLogPath
+};

package/lib/web/server.js

@@ -1746,6 +1746,11 @@ async function handleWebApi(req, res, pathname, ctx, state) {
 }
 
 async function startWebServer(options) {
+    const fallbackLogger = {
+        info: () => {},
+        warn: () => {},
+        error: () => {}
+    };
     const ctx = {
         serverHost: options.serverHost || '127.0.0.1',
         serverPort: options.serverPort,
@@ -1773,6 +1778,7 @@ async function startWebServer(options) {
         dockerExecArgs: options.dockerExecArgs,
         showImagePullHint: options.showImagePullHint,
         removeContainer: options.removeContainer,
+        logger: options.logger && typeof options.logger.info === 'function' ? options.logger : fallbackLogger,
         colors: options.colors || {
             GREEN: '',
             CYAN: '',
@@ -1799,6 +1805,9 @@ async function startWebServer(options) {
         noServer: true,
         maxPayload: 1024 * 1024
     });
+    wsServer.on('error', err => {
+        ctx.logger.error('ws server error', err);
+    });
 
     wsServer.on('connection', (ws, req, meta = {}) => {
         const containerName = meta.containerName;
@@ -1869,6 +1878,11 @@ async function startWebServer(options) {
 
             sendHtml(res, 404, '<h1>404 Not Found</h1>');
         } catch (e) {
+            ctx.logger.error('http request error', {
+                method: req && req.method ? req.method : '',
+                url: req && req.url ? req.url : '',
+                message: e && e.message ? e.message : 'Server Error'
+            });
             if ((req.url || '').startsWith('/api/')) {
                 sendJson(res, 500, { error: e.message || 'Server Error' });
             } else {
@@ -1876,6 +1890,12 @@ async function startWebServer(options) {
             }
         }
     });
+    server.on('error', err => {
+        ctx.logger.error('http server error', err);
+    });
+    server.on('close', () => {
+        ctx.logger.warn('http server closed');
+    });
 
     server.on('upgrade', (req, socket, head) => {
         const fallbackHost = `${formatUrlHost(ctx.serverHost)}:${ctx.serverPort}`;
@@ -1956,7 +1976,10 @@ async function startWebServer(options) {
     let listenPort = ctx.serverPort;
 
     await new Promise((resolve, reject) => {
-        server.once('error', reject);
+        server.once('error', err => {
+            ctx.logger.error('http server listen failed', err);
+            reject(err);
+        });
         server.listen(ctx.serverPort, ctx.serverHost, () => {
             const address = server.address();
             if (address && typeof address === 'object' && typeof address.port === 'number') {
@@ -1975,6 +1998,12 @@ async function startWebServer(options) {
             } else {
                 console.log(`${CYAN}🔐 登录密码: 使用你配置的 serve -P / serverPass / MANYOYO_SERVER_PASS${NC}`);
             }
+            ctx.logger.info('web server started', {
+                host: ctx.serverHost,
+                port: listenPort,
+                authUser: ctx.authUser,
+                authPassAuto: Boolean(ctx.authPassAuto)
+            });
             resolve();
         });
     });
@@ -1985,6 +2014,7 @@ async function startWebServer(options) {
         host: ctx.serverHost,
         port: listenPort,
         close: () => new Promise(resolve => {
+            ctx.logger.info('web server closing');
             for (const session of state.terminalSessions.values()) {
                 const ptyProcess = session && session.ptyProcess;
                 if (ptyProcess && !ptyProcess.killed) {

package/{config.example.json → manyoyo.example.json}

@@ -1,38 +1,48 @@
 {
     // MANYOYO 全局配置文件，保存到 ~/.manyoyo/manyoyo.json
 
-    // 覆盖型参数（命令行 > runs.<name> > 全局配置）
+    // 容器基础参数（覆盖型：命令行 > runs.<name> > 全局配置 > 默认值）
     "containerName": "my-dev",
     "hostPath": "/path/to/your/project",
     "containerPath": "/path/to/your/project",
     "imageName": "localhost/xcanwin/manyoyo",
-    "imageVersion": "1.8.0-common",
+    "imageVersion": "1.8.4-common",
     "containerMode": "common",
-    "shellPrefix": "",
-    "shell": "",
-    "shellSuffix": "",
-    "agentPromptCommand": "",
+
+    // 容器启动环境（env 按 key 合并覆盖；其余数组参数会累加）
+    // 仅支持绝对路径，如 /abs/path.env
+    "envFile": [],
+    "env": {
+        "IS_SANDBOX": "1"
+    },
+    "volumes": [],
+    "ports": ["8888:8888"],
+
     // 仅首次创建容器时执行一次（创建后、常规 shell 前）
     "first": {
+        // 仅支持绝对路径，如 /abs/path.env
+        "envFile": [],
+        "env": {},
         "shellPrefix": "",
         "shell": "",
-        "shellSuffix": "",
-        "env": {},
-        "envFile": []
+        "shellSuffix": ""
     },
+
+    // 常规命令参数（覆盖型：命令行 > runs.<name> > 全局配置 > 默认值）
+    "shellPrefix": "",
+    "shell": "",
+    "shellSuffix": "",
+    "agentPromptCommand": "",
     "yolo": "",
-    "serverUser": "admin",
-    "serverPass": "change-this-password",
+    "quiet": ["tip", "cmd"],
 
-    // 合并型参数（env 按 key 合并覆盖；其余数组参数会累加）
-    "env": {
-        "IS_SANDBOX": "1"
-    },
-    "envFile": [],
-    "volumes": [],
-    "ports": ["8888:8888"],
+    // 构建参数（数组累加）
     "imageBuildArgs": [],
-    "quiet": ["tip", "cmd"],
+
+    // 网页认证参数（覆盖型；支持环境变量兜底）
+    // 优先级：命令行 > runs.<name> > 全局配置 > 环境变量 > 默认值
+    "serverUser": "admin",
+    "serverPass": "change-this-password",
 
     // 可选插件（manyoyo playwright / manyoyo plugin playwright）
     "plugins": {
@@ -65,15 +75,15 @@
     "runs": {
         "claude": {
             "containerName": "my-claude-{now}",
-            "yolo": "c",
-            "shell": "claude",
-            "agentPromptCommand": "claude -p {prompt}",
-            "first": {
-                "shell": "echo first-init"
-            },
             "env": {
                 "ANTHROPIC_MODEL": "claude-sonnet-4-5"
             },
+            "first": {
+                "shell": "echo first-init"
+            },
+            "shell": "claude",
+            "agentPromptCommand": "claude -p {prompt}",
+            "yolo": "c",
             "plugins": {
                 "playwright": {
                     "runtime": "container"

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@xcanwin/manyoyo",
-    "version": "5.3.1",
+    "version": "5.3.6",
     "imageVersion": "1.8.4-common",
     "description": "AI Agent CLI Security Sandbox for Docker and Podman",
     "keywords": [
@@ -50,7 +50,7 @@
         "README.md",
         "LICENSE",
         "docker/manyoyo.Dockerfile",
-        "config.example.json"
+        "manyoyo.example.json"
     ],
     "dependencies": {
         "@playwright/mcp": "0.0.68",