@xcanwin/manyoyo 5.8.5 → 5.8.9

package/README.md

@@ -128,6 +128,7 @@ manyoyo serve 127.0.0.1:3000
 manyoyo serve 127.0.0.1:3000 -U admin -P 123456
 manyoyo serve 127.0.0.1:3000 -U admin -P 123456 -d
 manyoyo serve 127.0.0.1:3000 -d   # 未设置密码时会打印本次随机密码
+manyoyo serve 127.0.0.1:3000 --stop   # 停止指定后台服务
 
 # 查看配置与命令拼装
 manyoyo config show

package/bin/manyoyo.js

@@ -16,6 +16,12 @@ const { buildImage } = require('../lib/image-build');
 const { resolveAgentResumeArg, buildAgentResumeCommand } = require('../lib/agent-resume');
 const { runPluginCommand, createPlugin } = require('../lib/plugin');
 const { buildManyoyoLogPath } = require('../lib/log-path');
+const { resolveRuntimeConfig } = require('../lib/runtime-resolver');
+const {
+    parseEnvEntry: parseEnvEntryOrThrow,
+    expandHomeAliasPath,
+    normalizeVolume
+} = require('../lib/runtime-normalizers');
 const {
     sanitizeSensitiveData,
     sanitizeServeLogText,
@@ -454,23 +460,13 @@ async function askQuestion(prompt) {
  * @param {string} env - 环境变量字符串 (KEY=VALUE)
  */
 function parseEnvEntry(env) {
-    const envText = String(env);
-    const idx = envText.indexOf('=');
-    if (idx <= 0) {
-        console.error(`${RED}⚠️  错误: env 格式应为 KEY=VALUE: ${envText}${NC}`);
-        process.exit(1);
-    }
-    const key = envText.slice(0, idx);
-    const value = envText.slice(idx + 1);
-    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
-        console.error(`${RED}⚠️  错误: env key 非法: ${key}${NC}`);
-        process.exit(1);
-    }
-    if (/[\r\n\0]/.test(value) || /[;&|`$<>]/.test(value)) {
-        console.error(`${RED}⚠️  错误: env value 含非法字符: ${key}${NC}`);
+    try {
+        return parseEnvEntryOrThrow(env);
+    } catch (e) {
+        const message = e && e.message ? e.message : String(e);
+        console.error(`${RED}⚠️  错误: ${message}${NC}`);
         process.exit(1);
     }
-    return { key, value };
 }
 
 function normalizeJsonEnvMap(envConfig, sourceLabel) {
@@ -570,42 +566,6 @@ function addEnvFile(envFile) {
     return addEnvFileTo(CONTAINER_ENVS, envFile);
 }
 
-function expandHomeAliasPath(filePath) {
-    const text = String(filePath || '').trim();
-    const homeDir = process.env.HOME || os.homedir();
-
-    if (text === '~') {
-        return homeDir;
-    }
-    if (text.startsWith('~/')) {
-        return path.join(homeDir, text.slice(2));
-    }
-    if (text === '$HOME') {
-        return homeDir;
-    }
-    if (text.startsWith('$HOME/')) {
-        return path.join(homeDir, text.slice('$HOME/'.length));
-    }
-
-    return text;
-}
-
-function normalizeVolume(volume) {
-    const text = String(volume || '').trim();
-    if (!text.startsWith('~') && !text.startsWith('$HOME')) {
-        return text;
-    }
-
-    const separatorIndex = text.indexOf(':');
-    if (separatorIndex === -1) {
-        return expandHomeAliasPath(text);
-    }
-
-    const hostPath = text.slice(0, separatorIndex);
-    const rest = text.slice(separatorIndex);
-    return `${expandHomeAliasPath(hostPath)}${rest}`;
-}
-
 function hasEnvKey(targetEnvs, key) {
     for (let i = 0; i < targetEnvs.length; i += 2) {
         if (targetEnvs[i] !== '--env') {
@@ -1004,11 +964,7 @@ function validateShellSuffixPassThroughArgs(command) {
     }
 }
 
-function applyRunStyleOptions(command, options = {}) {
-    const includeRmOnExit = options.includeRmOnExit !== false;
-    const includeServePreview = options.includeServePreview === true;
-    const includeWebAuthOptions = options.includeWebAuthOptions === true;
-
+function applyContainerBaseOptions(command) {
     command
         .option('-r, --run <name>', '加载运行配置 (从 ~/.manyoyo/manyoyo.json 的 runs.<name> 读取)')
         .option('--hp, --host-path <path>', '设置宿主机工作目录 (默认: 当前路径)')
@@ -1023,35 +979,69 @@ function applyRunStyleOptions(command, options = {}) {
     appendArrayOption(command, '-v, --volume <volume>', '绑定挂载卷 XXX:YYY (可多次使用)');
     appendArrayOption(command, '-p, --port <port>', '设置端口映射 XXX:YYY (可多次使用)');
 
+    return command;
+}
+
+function applyExecOptions(command) {
     command
         .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))');
+
+    return command;
+}
+
+function applyFirstExecOptions(command) {
+    command
+        .option('--first-shell-prefix <command>', '首次预执行命令前缀 (仅新建容器生效; 容器已存在时忽略)')
+        .option('--first-shell <command>', '首次预执行命令 (仅新建容器生效; 容器已存在时忽略)')
+        .option('--first-shell-suffix <command>', '首次预执行命令后缀 (仅新建容器生效; 容器已存在时忽略)');
     appendArrayOption(command, '--first-env <env>', '首次预执行环境变量 XXX=YYY (可多次使用)');
     appendArrayOption(command, '--first-env-file <file>', '首次预执行环境变量文件 (仅支持绝对路径，如 /abs/path.env)');
 
+    return command;
+}
+
+function applyQuietOptions(command) {
+    appendArrayOption(command, '-q, --quiet <item>', '静默输出 (可多次使用: cnew, crm, tip, cmd, full)');
+    return command;
+}
+
+function applyServeAuthOptions(command) {
+    command
+        .option('-U, --user <username>', '网页服务登录用户名 (默认 admin)')
+        .option('-P, --pass <password>', '网页服务登录密码 (默认自动生成随机密码)');
+    return command;
+}
+
+function applyRunStyleOptions(command, options = {}) {
+    const includeRmOnExit = options.includeRmOnExit !== false;
+    const includeServePreview = options.includeServePreview === true;
+    const includeWebAuthOptions = options.includeWebAuthOptions === true;
+    const includeFirstExecOptions = options.includeFirstExecOptions !== false;
+
+    applyContainerBaseOptions(command);
+    applyExecOptions(command);
+    if (includeFirstExecOptions) {
+        applyFirstExecOptions(command);
+    }
+
     if (includeRmOnExit) {
         command.option('--rm-on-exit', '退出后自动删除容器 (一次性模式)');
     }
 
-    appendArrayOption(command, '-q, --quiet <item>', '静默输出 (可多次使用: cnew, crm, tip, cmd, full)');
+    applyQuietOptions(command);
 
     if (includeServePreview) {
         command
-            .option('--serve [listen]', '按 serve 模式解析配置 (仅支持 <ip:port>)')
-            .option('-U, --user <username>', '网页服务登录用户名 (默认 admin)')
-            .option('-P, --pass <password>', '网页服务登录密码 (默认自动生成随机密码)');
+            .option('--serve [listen]', '按 serve 模式解析配置 (仅支持 <ip:port>)');
+        applyServeAuthOptions(command);
     }
 
     if (includeWebAuthOptions) {
-        command
-            .option('-U, --user <username>', '网页服务登录用户名 (默认 admin)')
-            .option('-P, --pass <password>', '网页服务登录密码 (默认自动生成随机密码)');
+        applyServeAuthOptions(command);
     }
 
     return command;
@@ -1214,8 +1204,13 @@ Notes:
         .action(() => selectAction('images', { imageList: true }));
 
     const serveCommand = program.command('serve [listen]').description('启动网页交互服务 (默认 127.0.0.1:3000)');
-    applyRunStyleOptions(serveCommand, { includeRmOnExit: false, includeWebAuthOptions: true });
+    applyRunStyleOptions(serveCommand, {
+        includeRmOnExit: false,
+        includeWebAuthOptions: true,
+        includeFirstExecOptions: false
+    });
     serveCommand.option('-d, --detach', '后台启动网页服务并立即返回');
+    serveCommand.option('--stop', '停止后台网页服务；必须显式传入 listen');
     serveCommand.action((listen, options) => {
         selectAction('serve', {
             ...options,
@@ -1259,7 +1254,10 @@ Notes:
     });
 
     const configRunCommand = configCommand.command('command').description('显示将执行的 docker run 命令并退出');
-    applyRunStyleOptions(configRunCommand, { includeRmOnExit: false });
+    applyRunStyleOptions(configRunCommand, {
+        includeRmOnExit: false,
+        includeFirstExecOptions: false
+    });
     enableShellSuffixPassThrough(configRunCommand);
     configRunCommand.action((options, command) => {
         validateShellSuffixPassThroughArgs(command);
@@ -1317,8 +1315,12 @@ Notes:
     const isShowConfigMode = selectedAction === 'config-show';
     const isShowCommandMode = selectedAction === 'config-command';
     const isServerMode = options.server !== undefined;
+    const isServerStopMode = Boolean(selectedAction === 'serve' && options.stop);
 
     const noDockerActions = new Set(['init', 'update', 'install', 'config-show', 'plugin']);
+    if (isServerStopMode) {
+        noDockerActions.add('serve');
+    }
     if (!noDockerActions.has(selectedAction)) {
         ensureDocker();
     }
@@ -1362,145 +1364,96 @@ Notes:
     const globalFirstConfig = normalizeFirstConfig(config.first, '全局配置');
     const runFirstConfig = normalizeFirstConfig(runConfig.first, '运行配置');
 
-    // Merge configs: command line > run config > global config > defaults
-    // Override mode (scalar values): use first defined value
-    HOST_PATH = pickConfigValue(options.hostPath, runConfig.hostPath, config.hostPath, HOST_PATH) || HOST_PATH;
-    const mergedContainerName = pickConfigValue(options.contName, runConfig.containerName, config.containerName);
-    if (mergedContainerName) {
-        CONTAINER_NAME = mergedContainerName;
-    }
-    CONTAINER_NAME = resolveContainerNameTemplate(CONTAINER_NAME);
-    const mergedContainerPath = pickConfigValue(options.contPath, runConfig.containerPath, config.containerPath);
-    if (mergedContainerPath) {
-        CONTAINER_PATH = mergedContainerPath;
-    }
-    IMAGE_NAME = pickConfigValue(options.imageName, runConfig.imageName, config.imageName, IMAGE_NAME) || IMAGE_NAME;
-    const mergedImageVersion = pickConfigValue(options.imageVer, runConfig.imageVersion, config.imageVersion);
-    if (mergedImageVersion) {
-        IMAGE_VERSION = mergedImageVersion;
-    }
-    const mergedShellPrefix = pickConfigValue(options.shellPrefix, runConfig.shellPrefix, config.shellPrefix);
-    if (mergedShellPrefix) {
-        EXEC_COMMAND_PREFIX = `${mergedShellPrefix} `;
-    }
-    const mergedShell = pickConfigValue(options.shell, runConfig.shell, config.shell);
-    if (mergedShell) {
-        EXEC_COMMAND = mergedShell;
-    }
-    const mergedShellSuffix = pickConfigValue(options.shellSuffix, runConfig.shellSuffix, config.shellSuffix);
-    if (mergedShellSuffix) {
-        EXEC_COMMAND_SUFFIX = normalizeCommandSuffix(mergedShellSuffix);
-    }
-    const mergedFirstShellPrefix = pickConfigValue(options.firstShellPrefix, runFirstConfig.shellPrefix, globalFirstConfig.shellPrefix);
-    if (mergedFirstShellPrefix) {
-        FIRST_EXEC_COMMAND_PREFIX = `${mergedFirstShellPrefix} `;
-    }
-    const mergedFirstShell = pickConfigValue(options.firstShell, runFirstConfig.shell, globalFirstConfig.shell);
-    if (mergedFirstShell) {
-        FIRST_EXEC_COMMAND = mergedFirstShell;
-    }
-    const mergedFirstShellSuffix = pickConfigValue(options.firstShellSuffix, runFirstConfig.shellSuffix, globalFirstConfig.shellSuffix);
-    if (mergedFirstShellSuffix) {
-        FIRST_EXEC_COMMAND_SUFFIX = normalizeCommandSuffix(mergedFirstShellSuffix);
-    }
+    const resolvedRuntime = resolveRuntimeConfig({
+        cliOptions: options,
+        globalConfig: config,
+        runConfig,
+        globalFirstConfig,
+        runFirstConfig,
+        defaults: {
+            hostPath: HOST_PATH,
+            containerName: CONTAINER_NAME,
+            containerPath: CONTAINER_PATH,
+            imageName: IMAGE_NAME,
+            imageVersion: IMAGE_VERSION
+        },
+        envVars: process.env,
+        argv: process.argv,
+        isServerMode,
+        isServerStopMode,
+        pickConfigValue,
+        resolveContainerNameTemplate,
+        normalizeCommandSuffix,
+        normalizeJsonEnvMap,
+        normalizeCliEnvMap,
+        mergeArrayConfig,
+        normalizeVolume,
+        parseServerListen
+    });
+
+    HOST_PATH = resolvedRuntime.hostPath;
+    CONTAINER_NAME = resolvedRuntime.containerName;
+    CONTAINER_PATH = resolvedRuntime.containerPath;
+    IMAGE_NAME = resolvedRuntime.imageName;
+    IMAGE_VERSION = resolvedRuntime.imageVersion;
+    EXEC_COMMAND_PREFIX = resolvedRuntime.exec.prefix;
+    EXEC_COMMAND = resolvedRuntime.exec.shell;
+    EXEC_COMMAND_SUFFIX = resolvedRuntime.exec.suffix;
+    FIRST_EXEC_COMMAND_PREFIX = resolvedRuntime.first.exec.prefix;
+    FIRST_EXEC_COMMAND = resolvedRuntime.first.exec.shell;
+    FIRST_EXEC_COMMAND_SUFFIX = resolvedRuntime.first.exec.suffix;
 
     // Basic name validation to reduce injection risk
     validateName('containerName', CONTAINER_NAME, SAFE_CONTAINER_NAME_PATTERN);
     validateName('imageName', IMAGE_NAME, /^[A-Za-z0-9][A-Za-z0-9._/:-]*$/);
     validateImageVersion(IMAGE_VERSION);
 
-    // Merge mode (array values): concatenate all sources
-    const toArray = (val) => Array.isArray(val) ? val : (val ? [val] : []);
-    const envFileList = [
-        ...toArray(config.envFile),
-        ...toArray(runConfig.envFile),
-        ...(options.envFile || [])
-    ].filter(Boolean);
+    const envFileList = resolvedRuntime.envFile;
     envFileList.forEach(ef => addEnvFile(ef));
 
     // env in JSON config uses map type, and is merged by key with CLI priority.
-    const envMap = {
-        ...normalizeJsonEnvMap(config.env, '全局配置'),
-        ...normalizeJsonEnvMap(runConfig.env, '运行配置'),
-        ...normalizeCliEnvMap(options.env)
-    };
+    const envMap = resolvedRuntime.env;
     Object.entries(envMap).forEach(([key, value]) => addEnv(`${key}=${value}`));
 
-    const firstEnvFileList = [
-        ...toArray(globalFirstConfig.envFile),
-        ...toArray(runFirstConfig.envFile),
-        ...(options.firstEnvFile || [])
-    ].filter(Boolean);
+    const firstEnvFileList = resolvedRuntime.first.envFile;
     firstEnvFileList.forEach(ef => addEnvFileTo(FIRST_CONTAINER_ENVS, ef));
 
-    const firstEnvMap = {
-        ...normalizeJsonEnvMap(globalFirstConfig.env, '全局配置 first'),
-        ...normalizeJsonEnvMap(runFirstConfig.env, '运行配置 first'),
-        ...normalizeCliEnvMap(options.firstEnv)
-    };
+    const firstEnvMap = resolvedRuntime.first.env;
     Object.entries(firstEnvMap).forEach(([key, value]) => addEnvTo(FIRST_CONTAINER_ENVS, `${key}=${value}`));
 
     applyPlaywrightCliSessionIntegration(config, runConfig);
 
-    const volumeList = mergeArrayConfig(config.volumes, runConfig.volumes, options.volume)
-        .map(normalizeVolume);
+    const volumeList = resolvedRuntime.volumes;
     volumeList.forEach(v => addVolume(v));
 
-    const portList = mergeArrayConfig(config.ports, runConfig.ports, options.port);
+    const portList = resolvedRuntime.ports;
     portList.forEach(p => addPort(p));
 
-    const buildArgList = mergeArrayConfig(config.imageBuildArgs, runConfig.imageBuildArgs, options.imageBuildArg);
+    const buildArgList = resolvedRuntime.imageBuildArgs;
     buildArgList.forEach(arg => addImageBuildArg(arg));
 
     // Override mode for special options
-    const yoloValue = pickConfigValue(options.yolo, runConfig.yolo, config.yolo);
+    const yoloValue = resolvedRuntime.yolo;
     if (yoloValue) setYolo(yoloValue);
 
-    const contModeValue = pickConfigValue(options.contMode, runConfig.containerMode, config.containerMode);
+    const contModeValue = resolvedRuntime.containerMode;
     if (contModeValue) setContMode(contModeValue);
 
-    const quietValue = pickConfigValue(options.quiet, runConfig.quiet, config.quiet);
+    const quietValue = resolvedRuntime.quiet;
     if (quietValue) setQuiet(quietValue);
 
-    // Handle shell-full (variadic arguments)
-    if (options.shellFull) {
-        EXEC_COMMAND = options.shellFull.join(' ');
-        EXEC_COMMAND_PREFIX = "";
-        EXEC_COMMAND_SUFFIX = "";
-    }
-
-    // Handle -- suffix arguments
-    if (!options.shellFull) {
-        const doubleDashIndex = process.argv.indexOf('--');
-        if (doubleDashIndex !== -1 && doubleDashIndex < process.argv.length - 1) {
-            EXEC_COMMAND_SUFFIX = normalizeCommandSuffix(process.argv.slice(doubleDashIndex + 1).join(' '));
-        }
-    }
-
     if (options.rmOnExit) {
         RM_ON_EXIT = true;
     }
 
     if (isServerMode) {
-        const serverListen = parseServerListen(options.server);
-        SERVER_HOST = serverListen.host;
-        SERVER_PORT = serverListen.port;
-    }
-
-    const serverUserValue = pickConfigValue(options.serverUser, runConfig.serverUser, config.serverUser, process.env.MANYOYO_SERVER_USER);
-    if (serverUserValue) {
-        SERVER_AUTH_USER = String(serverUserValue);
+        SERVER_HOST = resolvedRuntime.serverHost;
+        SERVER_PORT = resolvedRuntime.serverPort;
     }
 
-    const serverPassValue = pickConfigValue(options.serverPass, runConfig.serverPass, config.serverPass, process.env.MANYOYO_SERVER_PASS);
-    if (serverPassValue) {
-        SERVER_AUTH_PASS = String(serverPassValue);
-        SERVER_AUTH_PASS_AUTO = false;
-    }
-
-    if (isServerMode) {
-        ensureWebServerAuthCredentials();
-    }
+    SERVER_AUTH_USER = resolvedRuntime.serverUser || '';
+    SERVER_AUTH_PASS = resolvedRuntime.serverPass || '';
+    SERVER_AUTH_PASS_AUTO = resolvedRuntime.serverPassAuto === true;
 
     if (isShowConfigMode) {
         const finalConfig = {
@@ -1520,9 +1473,9 @@ Notes:
             shellSuffix: EXEC_COMMAND_SUFFIX || "",
             yolo: yoloValue || "",
             quiet: quietValue || [],
-            server: isServerMode,
-            serverHost: isServerMode ? SERVER_HOST : null,
-            serverPort: isServerMode ? SERVER_PORT : null,
+            server: resolvedRuntime.server,
+            serverHost: resolvedRuntime.server ? SERVER_HOST : null,
+            serverPort: resolvedRuntime.server ? SERVER_PORT : null,
             serverUser: SERVER_AUTH_USER || "",
             serverPass: SERVER_AUTH_PASS || "",
             exec: {
@@ -1560,7 +1513,9 @@ Notes:
         isRemoveMode,
         isShowCommandMode,
         isServerMode,
+        isServerStop: isServerStopMode,
         isServerDetach: Boolean(selectedAction === 'serve' && options.detach),
+        isServerListenSpecified: Boolean(isServerMode && options.server !== true),
         isPluginMode: false
     };
 }
@@ -1588,7 +1543,9 @@ function createRuntimeContext(modeState = {}) {
         showCommand: Boolean(modeState.isShowCommandMode),
         rmOnExit: RM_ON_EXIT,
         serverMode: Boolean(modeState.isServerMode),
+        serverStop: Boolean(modeState.isServerStop),
         serverDetach: Boolean(modeState.isServerDetach),
+        serverListenSpecified: Boolean(modeState.isServerListenSpecified),
         serverHost: SERVER_HOST,
         serverPort: SERVER_PORT,
         serverAuthUser: SERVER_AUTH_USER,
@@ -1657,10 +1614,138 @@ function buildDetachedServeEnv(runtime) {
     return env;
 }
 
+function formatServeListenHost(host) {
+    const text = String(host || '').trim() || '127.0.0.1';
+    if (text.includes(':') && !text.startsWith('[')) {
+        return `[${text}]`;
+    }
+    return text;
+}
+
+function buildServeListenLabel(host, port) {
+    return `${formatServeListenHost(host)}:${port}`;
+}
+
+function buildServePidFile(host, port, homeDir = os.homedir()) {
+    const dir = path.join(homeDir, '.manyoyo', 'run', 'serve');
+    const listen = buildServeListenLabel(host, port);
+    const safeName = listen.replace(/[^A-Za-z0-9_.-]+/g, '_');
+    return {
+        dir,
+        listen,
+        path: path.join(dir, `${safeName}.pid`)
+    };
+}
+
+function removeServePidFile(filePath) {
+    if (!filePath) return;
+    try {
+        fs.rmSync(filePath, { force: true });
+    } catch (e) {
+        // ignore cleanup failures
+    }
+}
+
+function isProcessRunning(pid) {
+    if (!Number.isInteger(pid) || pid <= 0) {
+        return false;
+    }
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch (e) {
+        return e && e.code !== 'ESRCH';
+    }
+}
+
+function readServePidFile(filePath) {
+    try {
+        const text = fs.readFileSync(filePath, 'utf-8').trim();
+        if (!/^\d+$/.test(text)) {
+            return 0;
+        }
+        return Number(text);
+    } catch (e) {
+        return 0;
+    }
+}
+
+function getServePidTarget(host, port, homeDir = os.homedir()) {
+    const pidFile = buildServePidFile(host, port, homeDir);
+    const pid = readServePidFile(pidFile.path);
+    if (!Number.isInteger(pid) || pid <= 0 || !isProcessRunning(pid)) {
+        removeServePidFile(pidFile.path);
+        return null;
+    }
+    return {
+        pid,
+        listen: pidFile.listen,
+        path: pidFile.path
+    };
+}
+
+function installServePidCleanup(pidFilePath, logger) {
+    if (!pidFilePath || global.__manyoyoServePidCleanupInstalled) {
+        return;
+    }
+    global.__manyoyoServePidCleanupInstalled = true;
+    process.on('exit', () => {
+        removeServePidFile(pidFilePath);
+        if (logger && typeof logger.info === 'function') {
+            logger.info('serve pid file removed', { pidFilePath });
+        }
+    });
+}
+
+function writeServePidFile(runtime, serverHandle) {
+    const pidFile = buildServePidFile(serverHandle.host, serverHandle.port);
+    fs.mkdirSync(pidFile.dir, { recursive: true });
+    fs.writeFileSync(pidFile.path, `${process.pid}\n`);
+    installServePidCleanup(pidFile.path, runtime && runtime.logger);
+    return pidFile.path;
+}
+
+async function stopServeProcess(runtime) {
+    if (!runtime || !runtime.serverListenSpecified) {
+        throw new Error('serve --stop 必须显式传入 listen，例如 manyoyo serve 127.0.0.1:3000 --stop');
+    }
+    const target = getServePidTarget(runtime.serverHost, runtime.serverPort);
+    if (!target) {
+        const label = buildServeListenLabel(runtime.serverHost, runtime.serverPort);
+        console.log(`${YELLOW}⚠️  未发现运行中的 serve 实例: ${label}${NC}`);
+        return;
+    }
+    try {
+        process.kill(target.pid, 'SIGTERM');
+    } catch (e) {
+        if (!e || e.code !== 'ESRCH') {
+            throw e;
+        }
+    }
+    await sleep(200);
+    if (isProcessRunning(target.pid)) {
+        try {
+            process.kill(target.pid, 'SIGKILL');
+        } catch (e) {
+            if (!e || e.code !== 'ESRCH') {
+                throw e;
+            }
+        }
+    }
+    removeServePidFile(target.path);
+    console.log(`${GREEN}✅ 已停止 serve: ${target.listen} (pid: ${target.pid})${NC}`);
+}
+
 function relaunchServeDetached(runtime) {
     const serveLog = buildManyoyoLogPath('serve');
     fs.mkdirSync(serveLog.dir, { recursive: true });
 
+    const existing = getServePidTarget(runtime.serverHost, runtime.serverPort);
+    if (existing) {
+        console.log(`${YELLOW}⚠️  serve 已在后台运行: ${existing.listen} (pid: ${existing.pid})${NC}`);
+        return;
+    }
+
     const child = spawn(process.argv[0], buildDetachedServeArgv(process.argv.slice(1)), {
         detached: true,
         stdio: 'ignore',
@@ -1954,7 +2039,7 @@ async function runWebServerMode(runtime) {
         runtime.serverAuthPassAuto = SERVER_AUTH_PASS_AUTO;
     }
 
-    await startWebServer({
+    const serverHandle = await startWebServer({
         serverHost: runtime.serverHost,
         serverPort: runtime.serverPort,
         authUser: runtime.serverAuthUser,
@@ -1993,6 +2078,8 @@ async function runWebServerMode(runtime) {
         },
         logger: runtime.logger
     });
+    writeServePidFile(runtime, serverHandle);
+    return serverHandle;
 }
 
 async function main() {
@@ -2015,6 +2102,10 @@ async function main() {
 
         // 2. Start web server mode
         if (runtime.serverMode) {
+            if (runtime.serverStop) {
+                await stopServeProcess(runtime);
+                return;
+            }
             if (runtime.serverDetach) {
                 relaunchServeDetached(runtime);
                 return;