@xcanwin/manyoyo 8.3.0 → 8.3.2

package/lib/plugin/playwright.js

@@ -1,128 +1,43 @@
 'use strict';
 
+// Playwright 插件：容器内的浏览器怎么来，只有 4 种模式、同一时间只有一个。
+//   default  容器内 Xvfb 里的有头浏览器（无需宿主机进程）
+//   headed   宿主机有窗口的浏览器
+//   chrome   用户正在使用的 Chrome（经本机中继）
+//   vnc      独立容器里的浏览器，用 noVNC 网页观看
+// 宿主机目录 current/ 以目录方式只读挂进容器的 /run/manyoyo-playwright/，里面的 config.json 一律原子替换，
+// 因此切换模式后已运行的容器自动跟随，不需要重建。
+
 const fs = require('fs');
 const net = require('net');
 const os = require('os');
 const path = require('path');
 const crypto = require('crypto');
 const { spawn, spawnSync } = require('child_process');
-const { playwrightCliVersion: PLAYWRIGHT_CLI_VERSION } = require('../../package.json');
-const { resolveForcedRuntime } = require('../container-runtime');
-
-const EXTENSIONS = [
-    ['ublock-origin-lite', 'ddkjiahejlhfcafbddmgiahcphecmpfh'],
-    ['adguard', 'bgnkhhnnamicmpeenaelnjfhikgbkllg'],
-    ['privacy-badger', 'pkehgijcmpdhfbdbbnkijodmdjhbjlgp'],
-    ['webrtc-leak-shield', 'bppamachkoflopbagkdoflbgfjflfnfl'],
-    ['webgl-fingerprint-defender', 'olnbjpaejebpnokblkepbphhembdicik']
+const { writeConfigFileSecure } = require('../secure-file');
+const fingerprint = require('./fingerprint');
+const extensions = require('./playwright-extensions');
+const { findDevToolsActivePort } = require('./playwright-relay');
+
+const MODES = ['headed', 'chrome', 'vnc'];
+const MODE_HELP = [
+    ['(默认)', '容器内虚拟屏里的有头浏览器，无需任何命令'],
+    ['headed', '宿主机上有窗口的浏览器，亲眼看着 Agent 操作'],
+    ['chrome', '你正在用的 Chrome，沿用登录状态（有风险）'],
+    ['vnc', '独立容器里的浏览器，通过 noVNC 网页观看（无桌面的机器）']
 ];
+const VNC_CONTAINER = 'my-playwright-vnc';
+const VNC_ASSET_DIR = path.join(__dirname, 'playwright-assets');
+const VNC_MOUNT_DIR = '/run/manyoyo-playwright-vnc';
+const DEFAULT_PORTS = { port: 8935, vncPort: 5900, novncPort: 6080 };
+const PROXY_BYPASS_HOSTS = ['host.docker.internal', 'host.containers.internal'];
+const SERVER_START_TIMEOUT_MS = 30000;
+const PROBE_TIMEOUT_MS = 5000;
+// chrome 首次连接要等用户在 Chrome 弹出的“要允许远程调试吗？”里点允许
+const CHROME_APPROVAL_TIMEOUT_MS = 60000;
 
-const SCENE_ORDER = ['mcp-cont-headless', 'mcp-cont-headed', 'mcp-host-headless', 'mcp-host-headed', 'cli-host-headless', 'cli-host-headed', 'dev-host-headed'];
-
-const SCENE_DEFS = {
-    'mcp-cont-headless': {
-        type: 'container',
-        engine: 'mcp',
-        configFile: 'mcp-cont-headless.json',
-        composeFile: 'compose-headless.yaml',
-        projectName: 'my-playwright-mcp-cont-headless',
-        containerName: 'my-playwright-mcp-cont-headless',
-        portKey: 'mcpContHeadless',
-        headless: true,
-        listenHost: '0.0.0.0'
-    },
-    'mcp-cont-headed': {
-        type: 'container',
-        engine: 'mcp',
-        configFile: 'mcp-cont-headed.json',
-        composeFile: 'compose-headed.yaml',
-        projectName: 'my-playwright-mcp-cont-headed',
-        containerName: 'my-playwright-mcp-cont-headed',
-        portKey: 'mcpContHeaded',
-        headless: false,
-        listenHost: '0.0.0.0'
-    },
-    'mcp-host-headless': {
-        type: 'host',
-        engine: 'mcp',
-        configFile: 'mcp-host-headless.json',
-        portKey: 'mcpHostHeadless',
-        headless: true,
-        listenHost: '127.0.0.1'
-    },
-    'mcp-host-headed': {
-        type: 'host',
-        engine: 'mcp',
-        configFile: 'mcp-host-headed.json',
-        portKey: 'mcpHostHeaded',
-        headless: false,
-        listenHost: '127.0.0.1'
-    },
-    'cli-host-headless': {
-        type: 'host',
-        engine: 'cli',
-        configFile: 'cli-host-headless.json',
-        portKey: 'cliHostHeadless',
-        headless: true,
-        listenHost: '0.0.0.0'
-    },
-    'cli-host-headed': {
-        type: 'host',
-        engine: 'cli',
-        configFile: 'cli-host-headed.json',
-        portKey: 'cliHostHeaded',
-        headless: false,
-        listenHost: '0.0.0.0'
-    },
-    'dev-host-headed': {
-        type: 'host',
-        engine: 'dev',
-        configFile: 'dev-host-headed.json',
-        headless: false
-    }
-};
-
-const VALID_RUNTIME = new Set(['container', 'host', 'mixed']);
-const VALID_ACTIONS = new Set(['up', 'down', 'status', 'health', 'logs']);
-const CONTAINER_EXTENSION_ROOT = '/app/extensions';
-const DEFAULT_FINGERPRINT_PROFILE = {
-    userAgent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36',
-    locale: 'zh-CN',
-    acceptLanguage: 'zh-CN,zh;q=0.9',
-    timezoneId: 'Asia/Shanghai',
-    width: 1366,
-    height: 768
-};
-const DISABLE_WEBRTC_LAUNCH_ARGS = ['--disable-webrtc'];
-
-function isMcpScene(sceneName) {
-    return Boolean(SCENE_DEFS[sceneName] && SCENE_DEFS[sceneName].engine === 'mcp');
-}
-
-function isCliScene(sceneName) {
-    return Boolean(SCENE_DEFS[sceneName] && SCENE_DEFS[sceneName].engine === 'cli');
-}
-
-function isDevScene(sceneName) {
-    return Boolean(SCENE_DEFS[sceneName] && SCENE_DEFS[sceneName].engine === 'dev');
-}
-
-function isCliSessionScene(sceneName) {
-    return isCliScene(sceneName) || isDevScene(sceneName);
-}
-
-function platformFromUserAgent(userAgent) {
-    const ua = String(userAgent || '').toLowerCase();
-    if (ua.includes('macintosh') || ua.includes('mac os x')) {
-        return 'MacIntel';
-    }
-    if (ua.includes('windows')) {
-        return 'Win32';
-    }
-    if (ua.includes('android') || ua.includes('linux')) {
-        return 'Linux x86_64';
-    }
-    return 'MacIntel';
+function asObject(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
 }
 
 function sleep(ms) {
@@ -130,1913 +45,877 @@ function sleep(ms) {
 }
 
 function tailText(filePath, lineCount) {
-    if (!fs.existsSync(filePath)) {
+    try {
+        return fs.readFileSync(filePath, 'utf8').split(/\r?\n/).slice(-lineCount).join('\n');
+    } catch {
         return '';
     }
-    const lines = fs.readFileSync(filePath, 'utf8').split(/\r?\n/);
-    return lines.slice(-lineCount).join('\n');
 }
 
-function asObject(value) {
-    if (!value || typeof value !== 'object' || Array.isArray(value)) {
-        return {};
+function randomAlnum(length) {
+    const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+    let out = '';
+    for (let i = 0; i < length; i += 1) {
+        out += chars[crypto.randomInt(0, chars.length)];
     }
-    return value;
+    return out;
 }
 
-function asStringArray(value, fallback) {
-    if (!Array.isArray(value)) {
-        return fallback;
-    }
-    return value
-        .map(item => String(item || '').trim())
-        .filter(Boolean);
+function shellValue(value) {
+    const text = String(value);
+    return /^[A-Za-z0-9_@%+=:,./~-]+$/.test(text) ? text : `'${text.replace(/'/g, "'\\''")}'`;
 }
 
-function asBoolean(value, fallback = false) {
-    if (typeof value === 'boolean') {
-        return value;
-    }
-    if (typeof value === 'string') {
-        const normalized = value.trim().toLowerCase();
-        if (normalized === 'true') {
-            return true;
-        }
-        if (normalized === 'false') {
-            return false;
-        }
-    }
-    return fallback;
+function portReady(port, host = '127.0.0.1', timeout = 300) {
+    return new Promise(resolve => {
+        const socket = net.createConnection({ host, port });
+        const finish = value => {
+            socket.destroy();
+            resolve(value);
+        };
+        socket.setTimeout(timeout);
+        socket.once('connect', () => finish(true));
+        socket.once('timeout', () => finish(false));
+        socket.once('error', () => finish(false));
+    });
 }
 
-function uniqueStrings(values) {
-    const out = [];
-    const seen = new Set();
-    for (const value of values) {
-        const text = String(value || '').trim();
-        if (!text || seen.has(text)) {
-            continue;
-        }
-        seen.add(text);
-        out.push(text);
+function pidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0) {
+        return false;
     }
-    return out;
-}
-
-function isHostPermission(value) {
-    if (value === '<all_urls>') {
+    try {
+        process.kill(pid, 0);
         return true;
+    } catch (error) {
+        return error.code === 'EPERM';
     }
-    return /^(?:\*|http|https|file|ftp):\/\//.test(value);
-}
-
-function scriptSourcesFromHtml(htmlFile) {
-    const content = fs.readFileSync(htmlFile, { encoding: 'utf8' });
-    const scripts = [...content.matchAll(/<script[^>]+src=["']([^"']+)["']/gi)].map(m => m[1]);
-    return scripts.filter(src => !/^(?:https?:)?\/\//.test(src));
 }
 
-function convertManifestV2ToV3(extDir) {
-    const manifestFile = path.join(extDir, 'manifest.json');
-    const manifest = JSON.parse(fs.readFileSync(manifestFile, 'utf8'));
-    if (manifest.manifest_version !== 2) {
+// pid 可能在重启后被不相干的进程复用：确认它的命令行还是我们起的服务脚本
+function pidIsOurs(pid) {
+    if (!pidAlive(pid)) {
         return false;
     }
+    const result = spawnSync('ps', ['-p', String(pid), '-o', 'args='], { encoding: 'utf8' });
+    return /playwright-(server|relay)\.js/.test(result.stdout || '');
+}
 
-    manifest.manifest_version = 3;
-
-    if (manifest.browser_action && !manifest.action) {
-        manifest.action = manifest.browser_action;
-        delete manifest.browser_action;
-    }
-    if (manifest.page_action && !manifest.action) {
-        manifest.action = manifest.page_action;
-        delete manifest.page_action;
-    }
-
-    const background = manifest.background;
-    if (background && typeof background === 'object' && !Array.isArray(background)) {
-        let scripts = [];
-        if (Array.isArray(background.scripts)) {
-            scripts = background.scripts.filter(s => typeof s === 'string');
-        } else if (typeof background.page === 'string') {
-            const pagePath = path.join(extDir, background.page);
-            if (fs.existsSync(pagePath)) {
-                scripts = scriptSourcesFromHtml(pagePath);
-            }
-        }
-
-        if (scripts.length > 0) {
-            const swName = 'generated_background_sw.js';
-            const swFile = path.join(extDir, swName);
-            const swLines = [
-                '// Auto-generated by manyoyo playwright ext-download for MV3.',
-                `importScripts(${scripts.map(s => JSON.stringify(s)).join(', ')});`,
-                ''
-            ];
-            fs.writeFileSync(swFile, swLines.join('\n'), 'utf8');
-            manifest.background = { service_worker: swName };
-        } else {
-            delete manifest.background;
-        }
-    }
-
-    if (typeof manifest.content_security_policy === 'string') {
-        manifest.content_security_policy = { extension_pages: manifest.content_security_policy };
-    }
-
-    if (Array.isArray(manifest.permissions)) {
-        const hostPermissions = Array.isArray(manifest.host_permissions) ? [...manifest.host_permissions] : [];
-        const keptPermissions = [];
-
-        for (const perm of manifest.permissions) {
-            if (typeof perm === 'string' && isHostPermission(perm)) {
-                if (!hostPermissions.includes(perm)) {
-                    hostPermissions.push(perm);
-                }
-            } else {
-                keptPermissions.push(perm);
-            }
-        }
-
-        manifest.permissions = keptPermissions;
-        if (hostPermissions.length > 0) {
-            manifest.host_permissions = hostPermissions;
-        }
-    }
+// 宿主机监听地址：macOS 的容器能访问宿主机 loopback；Linux 容器只能访问 0.0.0.0
+function defaultListenHost(platform = process.platform) {
+    return platform === 'darwin' ? '127.0.0.1' : '0.0.0.0';
+}
 
-    const war = manifest.web_accessible_resources;
-    if (Array.isArray(war) && war.length > 0 && war.every(v => typeof v === 'string')) {
-        manifest.web_accessible_resources = [
-            {
-                resources: war,
-                matches: ['<all_urls>']
-            }
-        ];
-    }
+// headed 的浏览器服务必须监听 0.0.0.0：playwright 只绑 loopback 时会按 Host 头做 DNS 重绑定防护，
+// 容器用 host.containers.internal 访问会被 403（macOS 上实测）；监听 0.0.0.0 则不检查 Host，靠 token 保护
+function headedListenHost() {
+    return '0.0.0.0';
+}
 
-    fs.writeFileSync(manifestFile, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
-    return true;
+function runtimeKind(runtimeCommand) {
+    return path.basename(String(runtimeCommand || '').trim()).toLowerCase() === 'podman' ? 'podman' : 'docker';
 }
 
-function buildCrxUrl(extId, prodversion) {
-    return (
-        'https://clients2.google.com/service/update2/crx' +
-        `?response=redirect&prodversion=${prodversion}` +
-        '&acceptformat=crx2,crx3' +
-        `&x=id%3D${extId}%26installsource%3Dondemand%26uc`
-    );
+function connectHostFor(runtimeCommand) {
+    return runtimeKind(runtimeCommand) === 'podman' ? 'host.containers.internal' : 'host.docker.internal';
 }
 
-function crxZipOffset(data) {
-    if (data.subarray(0, 4).toString('ascii') !== 'Cr24') {
-        throw new Error('not a CRX file');
+function appendNoProxy(existing) {
+    const parts = String(existing || '').split(',').map(item => item.trim()).filter(Boolean);
+    for (const host of PROXY_BYPASS_HOSTS) {
+        if (!parts.includes(host)) {
+            parts.push(host);
+        }
     }
+    return parts.join(',');
+}
 
-    const version = data.readUInt32LE(4);
-    if (version === 2) {
-        const pubLen = data.readUInt32LE(8);
-        const sigLen = data.readUInt32LE(12);
-        return 16 + pubLen + sigLen;
-    }
-    if (version === 3) {
-        const headerLen = data.readUInt32LE(8);
-        return 12 + headerLen;
+function envEntryValue(entries, key) {
+    for (let i = entries.length - 1; i >= 0; i -= 1) {
+        const text = String(entries[i]);
+        if (text.startsWith(`${key}=`)) {
+            return text.slice(key.length + 1);
+        }
     }
-    throw new Error(`unsupported CRX version: ${version}`);
+    return undefined;
 }
 
 class PlaywrightPlugin {
     constructor(options = {}) {
-        this.projectRoot = options.projectRoot || path.join(__dirname, '..', '..');
         this.stdout = options.stdout || process.stdout;
         this.stderr = options.stderr || process.stderr;
-        this.globalConfig = asObject(options.globalConfig);
-        this.runConfig = asObject(options.runConfig);
         this.rootGlobalConfig = asObject(options.rootGlobalConfig);
         this.rootRunConfig = asObject(options.rootRunConfig);
-        this.runtimeEnv = {};
-        this.config = this.resolveConfig();
-    }
-
-    resolveConfig() {
-        const homeDir = os.homedir();
-        const pluginRootDir = path.join(homeDir, '.manyoyo', 'plugin', 'playwright');
-        const defaultConfig = {
-            homeDir,
-            runtime: 'mixed',
-            enabledScenes: [...SCENE_ORDER],
-            cliSessionScene: 'cli-host-headless',
-            mcpDefaultHost: 'host.docker.internal',
-            dockerTag: process.env.PLAYWRIGHT_MCP_DOCKER_TAG || 'latest',
-            containerRuntime: '',
-            vncPasswordEnvKey: 'VNC_PASSWORD',
-            headedImage: 'localhost/xcanwin/manyoyo-playwright-headed',
-            configDir: path.join(pluginRootDir, 'config'),
-            runDir: path.join(pluginRootDir, 'run'),
-            extensionProdversion: '132.0.0.0',
-            navigatorPlatform: platformFromUserAgent(DEFAULT_FINGERPRINT_PROFILE.userAgent),
-            disableWebRTC: false,
-            devtoolsActivePortPath: '',
-            devtoolsCdpTimeout: 60000,
-            composeDir: path.join(__dirname, 'playwright-assets'),
-            ports: {
-                mcpContHeadless: 8931,
-                mcpContHeaded: 8932,
-                mcpHostHeadless: 8933,
-                mcpHostHeaded: 8934,
-                cliHostHeadless: 8935,
-                cliHostHeaded: 8936,
-                mcpContHeadedNoVnc: 6080
-            }
+        this.runtime = options.runtime || null;
+        this.homeDir = options.homeDir || os.homedir();
+        this.root = path.join(this.homeDir, '.manyoyo', 'plugin', 'playwright');
+        this.currentDir = path.join(this.root, 'current');
+        this.runDir = path.join(this.root, 'run');
+        this.config = this.resolveConfig(asObject(options.globalConfig), asObject(options.runConfig));
+    }
+
+    resolveConfig(globalConfig, runConfig) {
+        const merged = { ...globalConfig, ...runConfig };
+        const host = fingerprint.detectHostProfile();
+        const port = name => {
+            const value = Number(merged[name] || DEFAULT_PORTS[name]);
+            if (!Number.isInteger(value) || value <= 0 || value > 65535) {
+                throw new Error(`plugins.playwright.${name} 无效: ${merged[name]}`);
+            }
+            return value;
         };
-
-        const merged = {
-            ...defaultConfig,
-            ...this.globalConfig,
-            ...this.runConfig,
-            ports: {
-                ...defaultConfig.ports,
-                ...asObject(this.globalConfig.ports),
-                ...asObject(this.runConfig.ports)
-            }
+        return {
+            port: port('port'),
+            vncPort: port('vncPort'),
+            novncPort: port('novncPort'),
+            locale: String(merged.locale || '').trim() || host.locale,
+            timezoneId: String(merged.timezoneId || '').trim() || host.timezoneId,
+            navigatorPlatform: String(merged.navigatorPlatform || '').trim(),
+            disableWebRTC: merged.disableWebRTC === true || String(merged.disableWebRTC).toLowerCase() === 'true',
+            devtoolsActivePortPath: String(merged.devtoolsActivePortPath || '').trim(),
+            extensionProdversion: String(merged.extensionProdversion || '').trim() || '132.0.0.0'
         };
-
-        merged.runtime = String(merged.runtime || defaultConfig.runtime).trim().toLowerCase();
-        if (!VALID_RUNTIME.has(merged.runtime)) {
-            throw new Error(`playwright.runtime 无效: ${merged.runtime}`);
-        }
-
-        merged.enabledScenes = asStringArray(
-            this.runConfig.enabledScenes,
-            asStringArray(this.globalConfig.enabledScenes, [...defaultConfig.enabledScenes])
-        );
-        merged.containerRuntime = this.resolveContainerRuntime(merged.containerRuntime);
-        merged.cliSessionScene = String(merged.cliSessionScene || defaultConfig.cliSessionScene).trim();
-        merged.navigatorPlatform = String(merged.navigatorPlatform || defaultConfig.navigatorPlatform).trim() || defaultConfig.navigatorPlatform;
-        merged.disableWebRTC = asBoolean(merged.disableWebRTC, defaultConfig.disableWebRTC);
-
-        if (merged.enabledScenes.length === 0) {
-            throw new Error('playwright.enabledScenes 不能为空');
-        }
-
-        const invalidScene = merged.enabledScenes.find(scene => !SCENE_DEFS[scene]);
-        if (invalidScene) {
-            throw new Error(`playwright.enabledScenes 包含未知场景: ${invalidScene}`);
-        }
-        merged.devtoolsActivePortPath = String(merged.devtoolsActivePortPath || '').trim();
-        merged.devtoolsCdpTimeout = Number(merged.devtoolsCdpTimeout) || defaultConfig.devtoolsCdpTimeout;
-
-        if (merged.cliSessionScene && !isCliSessionScene(merged.cliSessionScene)) {
-            throw new Error(`playwright.cliSessionScene 无效: ${merged.cliSessionScene}`);
-        }
-
-        return merged;
     }
 
-    resolveContainerRuntime(configuredRuntime) {
-        const configured = String(configuredRuntime || '').trim().toLowerCase();
-        if (configured) {
-            return configured;
-        }
-
-        const forced = resolveForcedRuntime({ configured: this.rootGlobalConfig.containerRuntime });
-        if (forced) {
-            this.runtimeEnv = forced.env;
-            return forced.command;
-        }
-
-        const candidates = ['docker', 'podman'];
-        for (const cmd of candidates) {
-            if (this.ensureCommandAvailable(cmd)) {
-                return cmd;
-            }
-        }
-
-        return 'docker';
+    profile() {
+        const { locale, timezoneId, navigatorPlatform, disableWebRTC } = this.config;
+        return { locale, timezoneId, navigatorPlatform, disableWebRTC };
     }
 
-    writeStdout(line = '') {
+    out(line = '') {
         this.stdout.write(`${line}\n`);
     }
 
-    writeStderr(line = '') {
+    err(line = '') {
         this.stderr.write(`${line}\n`);
     }
 
-    remindCliSessionScene(sceneName) {
-        if (!isCliScene(sceneName)) {
-            return;
-        }
-        if (sceneName !== 'cli-host-headed') {
-            return;
-        }
-        if (this.cliHostContainerAttachConfigReady()) {
-            return;
+    // ---------- 路径与状态 ----------
+
+    statePath() { return path.join(this.runDir, 'state.json'); }
+    tokenPath() { return path.join(this.runDir, 'token'); }
+    logPath() { return path.join(this.runDir, 'server.log'); }
+    hostConfigPath() { return path.join(this.root, 'host.json'); }
+
+    ensureDirs() {
+        for (const dir of [this.root, this.currentDir, this.runDir]) {
+            fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
         }
-        this.writeStdout('[tip] 如果希望容器内 manyoyo run 自动附着到当前 CLI 宿主场景，请在 ~/.manyoyo/manyoyo.json 中设置:');
-        this.writeStdout('{');
-        this.writeStdout('    "volumes": [');
-        this.writeStdout('        "~/.manyoyo/.cache/ms-playwright:/root/.cache/ms-playwright"');
-        this.writeStdout('    ],');
-        this.writeStdout('    "plugins": {');
-        this.writeStdout('        "playwright": {');
-        this.writeStdout('            "cliSessionScene": "cli-host-headed"');
-        this.writeStdout('        }');
-        this.writeStdout('    }');
-        this.writeStdout('}');
     }
 
-    remoteDebuggingPageUrl() {
-        return 'chrome://inspect/#remote-debugging';
+    readState() {
+        try {
+            const state = JSON.parse(fs.readFileSync(this.statePath(), 'utf8'));
+            return state && MODES.includes(state.mode) ? state : { mode: 'default' };
+        } catch {
+            return { mode: 'default' };
+        }
     }
 
-    openChromeRemoteDebuggingPage() {
-        const url = this.remoteDebuggingPageUrl();
-        const platform = process.platform;
-        let commands = [];
-
-        if (platform === 'darwin') {
-            commands = [
-                ['open', '-a', 'Google Chrome', url],
-                ['open', url]
-            ];
-        } else if (platform === 'win32') {
-            commands = [
-                ['cmd', '/c', 'start', '', 'chrome', url]
-            ];
-        } else {
-            commands = [
-                ['google-chrome', url],
-                ['google-chrome-stable', url],
-                ['chromium', url],
-                ['chromium-browser', url]
-            ];
-        }
+    writeState(state) {
+        this.ensureDirs();
+        writeConfigFileSecure(this.statePath(), `${JSON.stringify(state, null, 4)}\n`);
+    }
 
-        for (const args of commands) {
-            const result = this.runCmd(args, { check: false, captureOutput: true });
-            if (result.returncode === 0) {
-                return true;
+    // token 首次生成后持久化，重启服务不换；只有 down 才会让它失效
+    ensureToken() {
+        this.ensureDirs();
+        try {
+            const token = fs.readFileSync(this.tokenPath(), 'utf8').trim();
+            if (/^[0-9a-f]{64}$/.test(token)) {
+                return token;
             }
+        } catch {
+            // 还没有，下面生成
         }
-        return false;
+        const token = crypto.randomBytes(32).toString('hex');
+        writeConfigFileSecure(this.tokenPath(), `${token}\n`);
+        return token;
     }
 
-    writeDevHostUsage(configPath) {
-        this.writeStdout('');
-        this.writeStdout('若用容器 Agent 操作宿主机浏览器，在宿主机执行:');
-        ['claude', 'codex', 'gemini'].forEach(runName => {
-            this.writeStdout(`my run -r ${runName}`);
-        });
-        this.writeStdout('');
-        this.writeStdout('若用宿主机 Agent 操作宿主机浏览器，在宿主机执行:');
-        ['claude', 'codex', 'gemini'].forEach(command => {
-            this.writeStdout(this.devHostAttachCommand(configPath, command));
-        });
+    readPersisted(name) {
+        try {
+            return fs.readFileSync(path.join(this.runDir, name), 'utf8').trim();
+        } catch {
+            return '';
+        }
     }
 
-    randomAlnum(length = 16) {
-        const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
-        let out = '';
-        for (let i = 0; i < length; i += 1) {
-            out += chars[crypto.randomInt(0, chars.length)];
+    ensureVncPassword() {
+        const existing = this.readPersisted('vnc-password');
+        if (existing) {
+            return existing;
         }
-        return out;
+        const password = randomAlnum(8);
+        writeConfigFileSecure(path.join(this.runDir, 'vnc-password'), `${password}\n`);
+        return password;
     }
 
-    runCmd(args, { env = null, captureOutput = false, check = true } = {}) {
-        const isRuntimeCommand = args[0] === this.config.containerRuntime;
-        const result = spawnSync(args[0], args.slice(1), {
-            encoding: 'utf8',
-            env: isRuntimeCommand ? { ...(env || process.env), ...this.runtimeEnv } : (env || process.env),
-            stdio: captureOutput ? ['ignore', 'pipe', 'pipe'] : 'inherit'
-        });
-
-        const completed = {
-            returncode: result.status === null ? 1 : result.status,
-            stdout: typeof result.stdout === 'string' ? result.stdout : '',
-            stderr: typeof result.stderr === 'string' ? result.stderr : ''
-        };
+    // ---------- 容器侧配置（挂载目录里的 config.json） ----------
 
-        if (result.error) {
-            if (check) {
-                throw result.error;
-            }
-            completed.returncode = 1;
-            return completed;
+    containerConfigFor(state, runtimeCommand) {
+        const profile = this.profile();
+        const host = connectHostFor(runtimeCommand);
+        if (state.mode === 'chrome') {
+            return fingerprint.buildContainerConfig('cdp', {
+                ...profile,
+                endpoint: `ws://${host}:${state.port}/${this.ensureToken()}`
+            });
         }
-
-        if (check && completed.returncode !== 0) {
-            const error = new Error(`command failed with exit code ${completed.returncode}`);
-            error.returncode = completed.returncode;
-            error.stdout = completed.stdout;
-            error.stderr = completed.stderr;
-            throw error;
+        if (state.mode === 'headed' || state.mode === 'vnc') {
+            return fingerprint.buildContainerConfig('ws', {
+                ...profile,
+                endpoint: `ws://${host}:${state.port}/${this.ensureToken()}`
+            });
         }
-
-        return completed;
+        return fingerprint.buildContainerConfig('default', profile);
     }
 
-    ensureCommandAvailable(command) {
-        const name = String(command || '').trim();
-        if (path.isAbsolute(name)) {
-            return fs.existsSync(name);
+    // 原子替换：目录挂载能看到 rename 之后的新文件
+    writeCurrentConfig(state, runtimeCommand) {
+        this.ensureDirs();
+        const config = `${JSON.stringify(this.containerConfigFor(state, runtimeCommand), null, 4)}\n`;
+        const initScript = fingerprint.buildInitScript(this.profile());
+        const configPath = path.join(this.currentDir, 'config.json');
+        const initPath = path.join(this.currentDir, 'stealth.init.js');
+        const same = (file, content) => {
+            try {
+                return fs.readFileSync(file, 'utf8') === content;
+            } catch {
+                return false;
+            }
+        };
+        if (!same(initPath, initScript)) {
+            writeConfigFileSecure(initPath, initScript);
         }
-        if (!/^[A-Za-z0-9._-]+$/.test(name)) {
-            return false;
+        if (!same(configPath, config)) {
+            writeConfigFileSecure(configPath, config);
         }
-        const result = spawnSync('sh', ['-c', `command -v ${name}`], {
-            encoding: 'utf8',
-            stdio: ['ignore', 'ignore', 'ignore']
-        });
-        return result.status === 0;
-    }
-
-    scenePort(sceneName) {
-        const def = SCENE_DEFS[sceneName];
-        return Number(this.config.ports[def.portKey]);
+        return configPath;
     }
 
-    sceneConfigPath(sceneName) {
-        const def = SCENE_DEFS[sceneName];
-        return path.join(this.config.configDir, def.configFile);
+    // 宿主机上的 Agent 用的配置（路径与端点都是宿主机视角）
+    writeHostConfig(state) {
+        const profile = this.profile();
+        const endpoint = `ws://127.0.0.1:${state.port}/${this.ensureToken()}`;
+        const initPath = path.join(this.root, 'host.init.js');
+        writeConfigFileSecure(initPath, fingerprint.buildInitScript(profile));
+        const config = state.mode === 'chrome'
+            ? fingerprint.buildContainerConfig('cdp', { endpoint })
+            : fingerprint.buildContainerConfig('ws', { ...profile, endpoint });
+        config.outputDir = path.join(os.tmpdir(), '.playwright-cli');
+        if (config.browser.initScript) {
+            config.browser.initScript = [initPath];
+        }
+        writeConfigFileSecure(this.hostConfigPath(), `${JSON.stringify(config, null, 4)}\n`);
+        return this.hostConfigPath();
     }
 
-    sceneConfigMissing(sceneName) {
-        return !fs.existsSync(this.sceneConfigPath(sceneName));
+    userDisplayPath(filePath) {
+        return filePath.startsWith(`${this.homeDir}${path.sep}`) ? `~${filePath.slice(this.homeDir.length)}` : filePath;
     }
 
-    sceneEndpointPath(sceneName) {
-        return path.join(this.config.runDir, `${sceneName}.endpoint.json`);
-    }
+    // ---------- 容器集成（CLI 与 Web 共用） ----------
 
-    readSceneEndpoint(sceneName) {
-        const filePath = this.sceneEndpointPath(sceneName);
-        if (!fs.existsSync(filePath)) {
-            return null;
+    // 模式是否真的还活着（只看进程与端口，足够快；真实探测见 probe）
+    async modeAlive(state) {
+        if (state.mode === 'default') {
+            return true;
         }
-        try {
-            return JSON.parse(fs.readFileSync(filePath, 'utf8'));
-        } catch {
-            return null;
+        if (state.mode === 'vnc') {
+            // 发布端口由运行时转发，容器没了端口也可能还能连上，所以看容器状态
+            try {
+                const inspect = this.runtimeCall(['inspect', '--format', '{{.State.Running}}', VNC_CONTAINER]);
+                return inspect.status === 0 && inspect.stdout.trim() === 'true' && await portReady(state.port);
+            } catch {
+                return false;
+            }
         }
+        return pidIsOurs(state.pid) && await portReady(state.port);
     }
 
-    writeSceneEndpoint(sceneName, payload) {
-        fs.mkdirSync(this.config.runDir, { recursive: true });
-        fs.writeFileSync(this.sceneEndpointPath(sceneName), `${JSON.stringify(payload, null, 4)}\n`, 'utf8');
-    }
-
-    removeSceneEndpoint(sceneName) {
-        fs.rmSync(this.sceneEndpointPath(sceneName), { force: true });
-    }
-
-    sceneCliAttachConfigPath(sceneName) {
-        return path.join(this.config.runDir, `${sceneName}.cli-attach.json`);
+    // 返回 { env, volumes, extraArgs, warning }；永远不抛错，不因 playwright 让 run 退出
+    async buildContainerIntegration({ runtimeCommand, envEntries = [], dryRun = false } = {}) {
+        let warning = '';
+        try {
+            // 预览命令（dryRun）不写任何文件、不改状态
+            if (!dryRun) {
+                this.ensureDirs();
+            }
+            let state = this.readState();
+            if (dryRun) {
+                state = { mode: 'default' };
+            } else if (!(await this.modeAlive(state))) {
+                warning = `Playwright ${state.mode} 模式已失效，容器内浏览器已回退到默认模式。恢复: manyoyo playwright up ${state.mode}`;
+                state = { mode: 'default' };
+                this.writeState(state);
+            }
+            if (!dryRun) {
+                this.writeCurrentConfig(state, runtimeCommand);
+            }
+        } catch (error) {
+            return { env: [], volumes: [], extraArgs: [], warning: `Playwright 集成不可用: ${error.message || String(error)}` };
+        }
+        const noProxy = appendNoProxy(envEntryValue(envEntries, 'NO_PROXY') ?? envEntryValue(envEntries, 'no_proxy')
+            ?? process.env.NO_PROXY ?? process.env.no_proxy);
+        return {
+            env: [
+                `PLAYWRIGHT_MCP_CONFIG=${fingerprint.CONTAINER_CONFIG_PATH}`,
+                'NO_UPDATE_NOTIFIER=1',
+                `NO_PROXY=${noProxy}`,
+                `no_proxy=${noProxy}`
+            ],
+            volumes: [`${this.currentDir}:${fingerprint.CONTAINER_CONFIG_DIR}:ro`],
+            extraArgs: runtimeKind(runtimeCommand) === 'docker' ? ['--add-host', 'host.docker.internal:host-gateway'] : [],
+            warning
+        };
     }
 
-    writeSceneCliAttachConfig(sceneName, payload) {
-        fs.mkdirSync(this.config.runDir, { recursive: true });
-        fs.writeFileSync(this.sceneCliAttachConfigPath(sceneName), `${JSON.stringify(payload, null, 4)}\n`, 'utf8');
-    }
+    // ---------- 运行时与命令 ----------
 
-    removeSceneCliAttachConfig(sceneName) {
-        fs.rmSync(this.sceneCliAttachConfigPath(sceneName), { force: true });
+    resolveRuntime() {
+        if (!this.runtime) {
+            const { selectContainerRuntime } = require('../container-runtime');
+            this.runtime = selectContainerRuntime({ configured: this.rootGlobalConfig.containerRuntime });
+        }
+        return this.runtime;
     }
 
-    buildDevHostAttachConfig(endpoint, cdpHost) {
+    runtimeCall(args, { capture = true } = {}) {
+        const runtime = this.resolveRuntime();
+        const result = spawnSync(runtime.command, args, {
+            encoding: 'utf8',
+            env: { ...process.env, ...runtime.env },
+            stdio: capture ? ['ignore', 'pipe', 'pipe'] : 'inherit'
+        });
         return {
-            outputDir: '/tmp/.playwright-cli',
-            browser: {
-                cdpEndpoint: `ws://${cdpHost}:${endpoint.port}${endpoint.wsPath}`,
-                cdpHeaders: {
-                    Host: `127.0.0.1:${endpoint.port}`
-                },
-                cdpTimeout: this.config.devtoolsCdpTimeout
-            }
+            status: result.error ? 1 : (result.status === null ? 1 : result.status),
+            stdout: result.stdout || '',
+            stderr: result.stderr || (result.error ? String(result.error.message) : '')
         };
     }
 
-    writeDevHostAttachConfig(sceneName, endpoint) {
-        fs.mkdirSync(this.config.configDir, { recursive: true });
-        const filePath = this.sceneConfigPath(sceneName);
-        fs.writeFileSync(filePath, `${JSON.stringify(this.buildDevHostAttachConfig(endpoint, '127.0.0.1'), null, 4)}\n`, 'utf8');
-        return filePath;
+    corePath() {
+        const cliPackage = require.resolve('@playwright/cli/package.json');
+        return path.dirname(require.resolve('playwright-core/package.json', { paths: [path.dirname(cliPackage)] }));
     }
 
-    removeDevHostAttachConfig(sceneName) {
-        fs.rmSync(this.sceneConfigPath(sceneName), { force: true });
+    coreCli() {
+        return path.join(this.corePath(), 'cli.js');
     }
 
-    userDisplayPath(filePath) {
-        const normalizedPath = path.resolve(filePath);
-        const normalizedHome = path.resolve(this.config.homeDir);
-        if (normalizedPath === normalizedHome) {
-            return '~';
-        }
-        if (normalizedPath.startsWith(`${normalizedHome}${path.sep}`)) {
-            return `~${normalizedPath.slice(normalizedHome.length)}`;
-        }
-        return filePath;
+    // 浏览器与探测都用 @playwright/cli 自带的 playwright-core，保证与容器内版本一致
+    installCommand(args) {
+        return `node ${shellValue(this.coreCli())} ${args}`;
     }
 
-    shellValue(value) {
-        const text = String(value);
-        if (/^[A-Za-z0-9_@%+=:,./~-]+$/.test(text)) {
-            return text;
+    ensureBrowserInstalled() {
+        const result = spawnSync(process.execPath, [this.coreCli(), 'install', '--no-shell', 'chromium'], { stdio: 'inherit' });
+        if (result.status !== 0) {
+            throw new Error(`浏览器安装失败，请手动执行: ${this.installCommand('install --no-shell chromium')}`);
         }
-        return `'${text.replace(/'/g, "'\\''")}'`;
     }
 
-    devHostAttachEnvEntries(configPath) {
-        return [
-            `PLAYWRIGHT_MCP_CONFIG=${this.shellValue(this.userDisplayPath(configPath))}`
-        ];
-    }
+    // ---------- 探测 ----------
 
-    devHostAttachCommand(configPath, command) {
-        return `${this.devHostAttachEnvEntries(configPath).join(' ')} ${command}`;
+    probe(kind, endpoint, timeout = PROBE_TIMEOUT_MS) {
+        return new Promise(resolve => {
+            const child = spawn(process.execPath, [path.join(__dirname, 'playwright-probe.js')], {
+                env: {
+                    ...process.env,
+                    MANYOYO_PROBE: JSON.stringify({ core: this.corePath(), kind, endpoint, timeout })
+                },
+                stdio: ['ignore', 'pipe', 'ignore']
+            });
+            let output = '';
+            const timer = setTimeout(() => child.kill('SIGKILL'), timeout + 3000);
+            child.stdout.on('data', chunk => { output += chunk; });
+            child.on('error', () => {
+                clearTimeout(timer);
+                resolve({ ok: false, error: '无法启动探测进程' });
+            });
+            child.on('close', () => {
+                clearTimeout(timer);
+                try {
+                    resolve(JSON.parse(output.trim().split('\n').pop()));
+                } catch {
+                    resolve({ ok: false, error: '探测超时或无输出' });
+                }
+            });
+        });
     }
 
-    expandHomePath(value) {
-        const text = String(value || '').trim();
-        if (text === '~') {
-            return this.config.homeDir;
-        }
-        if (text.startsWith('~/')) {
-            return path.join(this.config.homeDir, text.slice(2));
-        }
-        return text;
+    async probeState(state) {
+        const endpoint = `ws://127.0.0.1:${state.port}/${this.ensureToken()}`;
+        return state.mode === 'chrome'
+            ? await this.probe('cdp', endpoint, CHROME_APPROVAL_TIMEOUT_MS)
+            : await this.probe('ws', endpoint);
     }
 
-    parseVolumeEntry(value) {
-        const parts = String(value || '').split(':');
-        if (parts.length < 2) {
-            return null;
-        }
-        return {
-            hostPath: path.resolve(this.expandHomePath(parts[0])),
-            containerPath: parts[1]
-        };
-    }
+    // ---------- 进程管理 ----------
 
-    mergedRootVolumes() {
-        return [
-            ...asStringArray(this.rootGlobalConfig.volumes, []),
-            ...asStringArray(this.rootRunConfig.volumes, []),
-            ...asStringArray(this.globalConfig.volumes, []),
-            ...asStringArray(this.runConfig.volumes, [])
-        ];
+    spawnDetached(command, args, logPath) {
+        fs.mkdirSync(path.dirname(logPath), { recursive: true });
+        const logFd = fs.openSync(logPath, 'a', 0o600);
+        const child = spawn(command, args, { detached: true, stdio: ['ignore', logFd, logFd] });
+        fs.closeSync(logFd);
+        child.unref();
+        return child;
     }
 
-    hasRootVolume(required) {
-        const parsedRequired = this.parseVolumeEntry(required);
-        if (!parsedRequired) {
-            return false;
+    async killGroup(pid, { verify = true } = {}) {
+        if (verify ? !pidIsOurs(pid) : !pidAlive(pid)) {
+            return;
+        }
+        for (const signal of ['SIGTERM', 'SIGKILL']) {
+            try {
+                process.kill(-pid, signal);
+            } catch {
+                try {
+                    process.kill(pid, signal);
+                } catch {
+                    return;
+                }
+            }
+            for (let i = 0; i < 20; i += 1) {
+                if (!pidAlive(pid)) {
+                    return;
+                }
+                // eslint-disable-next-line no-await-in-loop
+                await sleep(100);
+            }
         }
-        return this.mergedRootVolumes().some(item => {
-            const parsed = this.parseVolumeEntry(item);
-            return parsed
-                && parsed.hostPath === parsedRequired.hostPath
-                && parsed.containerPath === parsedRequired.containerPath;
-        });
     }
 
-    cliHostContainerAttachConfigReady() {
-        return this.config.cliSessionScene === 'cli-host-headed'
-            && this.hasRootVolume('~/.manyoyo/.cache/ms-playwright:/root/.cache/ms-playwright');
+    async waitForPort(port, child) {
+        const deadline = Date.now() + SERVER_START_TIMEOUT_MS;
+        while (Date.now() < deadline) {
+            if (child && child.exitCode !== null) {
+                return false;
+            }
+            // eslint-disable-next-line no-await-in-loop
+            if (await portReady(port)) {
+                return true;
+            }
+            // eslint-disable-next-line no-await-in-loop
+            await sleep(300);
+        }
+        return false;
     }
 
-    devtoolsActivePortCandidates() {
-        const homeDir = this.config.homeDir;
-        const configured = this.config.devtoolsActivePortPath;
-        return uniqueStrings([
-            configured,
-            path.join(homeDir, 'Library', 'Application Support', 'Google', 'Chrome', 'DevToolsActivePort'),
-            path.join(homeDir, 'Library', 'Application Support', 'Google', 'Chrome Canary', 'DevToolsActivePort'),
-            path.join(homeDir, 'Library', 'Application Support', 'Chromium', 'DevToolsActivePort'),
-            path.join(homeDir, 'Library', 'Application Support', 'BraveSoftware', 'Brave-Browser', 'DevToolsActivePort'),
-            path.join(homeDir, '.config', 'google-chrome', 'DevToolsActivePort'),
-            path.join(homeDir, '.config', 'chromium', 'DevToolsActivePort'),
-            path.join(homeDir, '.config', 'google-chrome-beta', 'DevToolsActivePort'),
-            path.join(homeDir, '.config', 'google-chrome-unstable', 'DevToolsActivePort'),
-            path.join(homeDir, '.config', 'BraveSoftware', 'Brave-Browser', 'DevToolsActivePort'),
-            path.join(homeDir, 'AppData', 'Local', 'Google', 'Chrome', 'User Data', 'DevToolsActivePort'),
-            path.join(homeDir, 'AppData', 'Local', 'Google', 'Chrome Beta', 'User Data', 'DevToolsActivePort'),
-            path.join(homeDir, 'AppData', 'Local', 'Google', 'Chrome SxS', 'User Data', 'DevToolsActivePort'),
-            path.join(homeDir, 'AppData', 'Local', 'Chromium', 'User Data', 'DevToolsActivePort'),
-            path.join(homeDir, 'AppData', 'Local', 'BraveSoftware', 'Brave-Browser', 'User Data', 'DevToolsActivePort')
-        ]);
+    async stopCurrent(state) {
+        if (state.mode === 'vnc') {
+            this.runtimeCall(['rm', '-f', VNC_CONTAINER]);
+        } else if (state.mode === 'headed' || state.mode === 'chrome') {
+            await this.killGroup(state.pid);
+        }
     }
 
-    parseDevToolsActivePort(content, filePath = 'DevToolsActivePort') {
-        const lines = String(content || '')
-            .split(/\r?\n/)
-            .map(line => line.trim())
-            .filter(Boolean);
-        const port = Number(lines[0]);
-        const wsPath = lines[1] || '';
+    // ---------- 各模式启动 ----------
 
-        if (!Number.isInteger(port) || port <= 0 || port > 65535) {
-            throw new Error(`${filePath} 内容无效: 第一行必须是端口号`);
+    startFailure(mode, message, extra = '') {
+        this.err(`[up] ${mode} 失败: ${message}`);
+        if (extra) {
+            this.err(extra);
         }
-        if (!wsPath.startsWith('/devtools/browser/')) {
-            throw new Error(`${filePath} 内容无效: 第二行必须是 /devtools/browser/...`);
-        }
-
-        return { port, wsPath };
+        return 1;
     }
 
-    readDevToolsActivePort() {
-        const candidates = this.devtoolsActivePortCandidates();
-        for (const candidate of candidates) {
-            if (!fs.existsSync(candidate)) {
-                continue;
-            }
-            const content = fs.readFileSync(candidate, 'utf8');
-            return {
-                ...this.parseDevToolsActivePort(content, candidate),
-                filePath: candidate
-            };
+    async portPreflight(mode, port) {
+        if (await portReady(port)) {
+            this.startFailure(mode, `端口 ${port} 已被占用。`,
+                '换一个端口: 在 ~/.manyoyo/manyoyo.json 设置 "plugins": { "playwright": { "port": 9335 } }，或先停掉占用它的进程。');
+            return false;
         }
-
-        throw new Error(`未找到 DevToolsActivePort，请先在 Chrome 启用 remote debugging，并挂载或配置 devtoolsActivePortPath。已检查: ${candidates.join(', ')}`);
+        return true;
     }
 
-    sceneInitScriptPath(sceneName) {
-        const configFile = path.basename(this.sceneConfigPath(sceneName), '.json');
-        return path.join(this.config.configDir, `${configFile}.init.js`);
+    async startHeaded(extensionPaths) {
+        if (process.platform === 'linux' && !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY) {
+            return this.startFailure('headed', '当前没有图形界面（DISPLAY / WAYLAND_DISPLAY 为空）。', '没有桌面的机器请改用: manyoyo playwright up vnc');
+        }
+        const { port } = this.config;
+        if (!(await this.portPreflight('headed', port))) {
+            return 1;
+        }
+        try {
+            this.ensureBrowserInstalled();
+        } catch (error) {
+            return this.startFailure('headed', error.message);
+        }
+        const token = this.ensureToken();
+        const serverConfigPath = path.join(this.runDir, 'server.json');
+        // 优先开沙箱；系统禁止非特权用户命名空间（如 Ubuntu 23.10+ 的 AppArmor 限制）时退回无沙箱
+        let child = null;
+        for (const chromiumSandbox of [true, false]) {
+            writeConfigFileSecure(serverConfigPath, `${JSON.stringify(fingerprint.buildServerConfig({
+                host: headedListenHost(),
+                port,
+                wsPath: `/${token}`,
+                chromiumSandbox,
+                extensionArgs: extensions.buildExtensionLaunchArgs(extensionPaths),
+                ...this.profile()
+            }), null, 4)}\n`);
+            fs.rmSync(this.logPath(), { force: true });
+            child = this.spawnDetached(process.execPath,
+                [path.join(__dirname, 'playwright-server.js'), this.corePath(), serverConfigPath], this.logPath());
+            if (await this.waitForPort(port, child)) {
+                break;
+            }
+            await this.killGroup(child.pid, { verify: false });
+            if (!chromiumSandbox || !tailText(this.logPath(), 200).includes('No usable sandbox')) {
+                return this.startFailure('headed', '浏览器服务没有启动成功。',
+                    `${tailText(this.logPath(), 20)}\n缺系统依赖时执行: sudo ${this.installCommand('install-deps chromium')}`);
+            }
+            this.out('[up] 系统不允许非特权用户命名空间，Chromium 沙箱不可用，改为无沙箱启动。');
+        }
+        return { mode: 'headed', port, pid: child.pid, listenHost: headedListenHost(), extensionPaths };
+    }
+
+    async startChrome() {
+        const { port } = this.config;
+        const candidates = this.devtoolsCandidates();
+        const enableHint = '请在 Chrome 地址栏进入 chrome://inspect/#remote-debugging，勾选“Allow remote debugging”（Chrome 没开就先打开它），然后重试。\n'
+            + '（自定义用户目录时，用 plugins.playwright.devtoolsActivePortPath 指定 DevToolsActivePort 文件。）';
+        const target = findDevToolsActivePort(candidates);
+        if (!target) {
+            return this.startFailure('chrome', '没有找到开启了远程调试的 Chrome。', enableHint);
+        }
+        // Chrome 退出后会留下旧的 DevToolsActivePort，所以还要确认调试端口真的在监听
+        if (!(await portReady(target.port))) {
+            return this.startFailure('chrome', 'Chrome 没有在运行（只找到上次留下的调试端口记录）。', enableHint);
+        }
+        if (!(await this.portPreflight('chrome', port))) {
+            return 1;
+        }
+        fs.rmSync(this.logPath(), { force: true });
+        const relayConfigPath = path.join(this.runDir, 'relay.json');
+        writeConfigFileSecure(relayConfigPath, `${JSON.stringify({
+            host: defaultListenHost(), port, token: this.ensureToken(), candidates
+        }, null, 4)}\n`);
+        const child = this.spawnDetached(process.execPath,
+            [path.join(__dirname, 'playwright-relay.js'), relayConfigPath], this.logPath());
+        if (!(await this.waitForPort(port, child))) {
+            await this.killGroup(child.pid, { verify: false });
+            return this.startFailure('chrome', '中继没有启动成功。', tailText(this.logPath(), 20));
+        }
+        return { mode: 'chrome', port, pid: child.pid, listenHost: defaultListenHost() };
     }
 
-    buildInitScriptContent() {
-        const lines = [
-            "'use strict';",
-            '(function () {',
-            `    const platformValue = ${JSON.stringify(this.config.navigatorPlatform)};`,
-            '    try {',
-            '        const navProto = Object.getPrototypeOf(navigator);',
-            "        Object.defineProperty(navProto, 'platform', {",
-            '            configurable: true,',
-            '            get: () => platformValue',
-            '        });',
-            '    } catch (_) {}'
+    devtoolsCandidates() {
+        const h = this.homeDir;
+        const local = path.join(h, 'AppData', 'Local');
+        return [
+            this.config.devtoolsActivePortPath,
+            path.join(h, 'Library', 'Application Support', 'Google', 'Chrome', 'DevToolsActivePort'),
+            path.join(h, 'Library', 'Application Support', 'Google', 'Chrome Canary', 'DevToolsActivePort'),
+            path.join(h, 'Library', 'Application Support', 'Chromium', 'DevToolsActivePort'),
+            path.join(h, 'Library', 'Application Support', 'BraveSoftware', 'Brave-Browser', 'DevToolsActivePort'),
+            path.join(h, '.config', 'google-chrome', 'DevToolsActivePort'),
+            path.join(h, '.config', 'google-chrome-beta', 'DevToolsActivePort'),
+            path.join(h, '.config', 'google-chrome-unstable', 'DevToolsActivePort'),
+            path.join(h, '.config', 'chromium', 'DevToolsActivePort'),
+            path.join(h, '.config', 'BraveSoftware', 'Brave-Browser', 'DevToolsActivePort'),
+            path.join(local, 'Google', 'Chrome', 'User Data', 'DevToolsActivePort'),
+            path.join(local, 'Google', 'Chrome Beta', 'User Data', 'DevToolsActivePort'),
+            path.join(local, 'Chromium', 'User Data', 'DevToolsActivePort'),
+            path.join(local, 'BraveSoftware', 'Brave-Browser', 'User Data', 'DevToolsActivePort')
+        ].filter(Boolean);
+    }
+
+    baseImageRef() {
+        const global = this.rootGlobalConfig;
+        const run = this.rootRunConfig;
+        const name = String(run.imageName || global.imageName || 'ghcr.io/xcanwin/manyoyo').trim();
+        const version = String(run.imageVersion || global.imageVersion || require('../../package.json').imageVersion).trim();
+        return { name, version, ref: `${name}:${version}` };
+    }
+
+    // vnc 容器直接用当前 manyoyo 镜像（已带 xvfb / x11vnc / noVNC），不需要额外构建
+    ensureBaseImage() {
+        const { ref } = this.baseImageRef();
+        if (this.runtimeCall(['image', 'inspect', '--format', '{{.Id}}', ref]).status !== 0) {
+            throw new Error(`镜像 ${ref} 不存在，请先运行一次 manyoyo run 拉取或构建镜像。`);
+        }
+        return ref;
+    }
+
+    async startVnc(extensionPaths) {
+        const { port, vncPort, novncPort } = this.config;
+        for (const item of [port, vncPort, novncPort]) {
+            if (await portReady(item)) {
+                return this.startFailure('vnc', `端口 ${item} 已被占用。`,
+                    '在 ~/.manyoyo/manyoyo.json 的 plugins.playwright 里改 port / vncPort / novncPort，或先停掉占用它的进程。');
+            }
+        }
+        let image;
+        try {
+            image = this.ensureBaseImage();
+        } catch (error) {
+            return this.startFailure('vnc', error.message);
+        }
+        const token = this.ensureToken();
+        const password = this.ensureVncPassword();
+        const mountDir = path.join(this.runDir, 'vnc');
+        fs.mkdirSync(mountDir, { recursive: true, mode: 0o700 });
+        const mounts = extensions.buildContainerExtensionMounts(extensionPaths);
+        for (const name of ['vnc-entry.sh', 'playwright-server.js']) {
+            const source = path.join(name === 'vnc-entry.sh' ? VNC_ASSET_DIR : __dirname, name);
+            writeConfigFileSecure(path.join(mountDir, name), fs.readFileSync(source, 'utf8'));
+        }
+        writeConfigFileSecure(path.join(mountDir, 'server.json'), `${JSON.stringify(fingerprint.buildServerConfig({
+            host: '0.0.0.0',
+            port,
+            wsPath: `/${token}`,
+            window: 'virtual',
+            chromiumSandbox: false,
+            extensionArgs: extensions.buildExtensionLaunchArgs(mounts.containerPaths),
+            ...this.profile()
+        }), null, 4)}\n`);
+        const envFile = path.join(mountDir, 'env');
+        const noProxy = appendNoProxy(process.env.NO_PROXY ?? process.env.no_proxy);
+        writeConfigFileSecure(envFile, `VNC_PASSWORD=${password}\nNO_PROXY=${noProxy}\nno_proxy=${noProxy}\n`);
+        this.runtimeCall(['rm', '-f', VNC_CONTAINER]);
+        const listenHost = defaultListenHost();
+        const args = [
+            'run', '-d', '--name', VNC_CONTAINER,
+            '--env-file', envFile,
+            '--publish', `${listenHost}:${port}:${port}`,
+            '--publish', `127.0.0.1:${vncPort}:5900`,
+            '--publish', `127.0.0.1:${novncPort}:6080`,
+            '--volume', `${mountDir}:${VNC_MOUNT_DIR}:ro`,
+            ...mounts.volumes.flatMap(volume => ['--volume', volume]),
+            '--entrypoint', 'sh',
+            image, `${VNC_MOUNT_DIR}/vnc-entry.sh`
         ];
-
-        if (this.config.disableWebRTC) {
-            lines.push(
-                '    try {',
-                '        const scope = globalThis;',
-                "        const blocked = ['RTCPeerConnection', 'webkitRTCPeerConnection', 'RTCIceCandidate', 'RTCRtpSender', 'RTCRtpReceiver', 'RTCRtpTransceiver', 'RTCDataChannel'];",
-                '        for (const name of blocked) {',
-                "            Object.defineProperty(scope, name, { configurable: true, writable: true, value: undefined });",
-                '        }',
-                '        if (navigator.mediaDevices) {',
-                '            const errorFactory = () => {',
-                '                try {',
-                "                    return new DOMException('WebRTC is disabled', 'NotAllowedError');",
-                '                } catch (_) {',
-                "                    const error = new Error('WebRTC is disabled');",
-                "                    error.name = 'NotAllowedError';",
-                '                    return error;',
-                '                }',
-                '            };',
-                "            Object.defineProperty(navigator.mediaDevices, 'getUserMedia', {",
-                '                configurable: true,',
-                '                writable: true,',
-                '                value: async () => { throw errorFactory(); }',
-                '            });',
-                '        }',
-                '    } catch (_) {}'
-            );
+        const run = this.runtimeCall(args);
+        if (run.status !== 0) {
+            return this.startFailure('vnc', '容器启动失败。', run.stderr.trim());
+        }
+        // 发布端口由运行时转发，容器没起来时 TCP 也能连上，所以以浏览器服务打印的 ready 为准
+        const isReady = () => /^ready$/m.test(this.runtimeCall(['logs', '--tail', '200', VNC_CONTAINER]).stdout);
+        let started = false;
+        for (let i = 0; i < 100 && !started; i += 1) {
+            started = isReady();
+            if (!started) {
+                // eslint-disable-next-line no-await-in-loop
+                await sleep(300);
+            }
         }
-
-        lines.push('})();', '');
-        return lines.join('\n');
+        if (!started) {
+            const logs = this.runtimeCall(['logs', '--tail', '30', VNC_CONTAINER]);
+            this.runtimeCall(['rm', '-f', VNC_CONTAINER]);
+            return this.startFailure('vnc', '浏览器服务没有启动成功。', `${logs.stdout}${logs.stderr}`.trim());
+        }
+        return { mode: 'vnc', port, container: VNC_CONTAINER, listenHost, novncPort, vncPort, extensionPaths };
     }
 
-    ensureSceneInitScript(sceneName) {
-        const filePath = this.sceneInitScriptPath(sceneName);
-        const content = this.buildInitScriptContent();
-        fs.writeFileSync(filePath, content, 'utf8');
-        return filePath;
+    novncUrl() {
+        return `http://127.0.0.1:${this.config.novncPort}/vnc.html?autoconnect=1&resize=scale&password=${this.readPersisted('vnc-password')}`;
     }
 
-    defaultBrowserName(sceneName) {
-        if (isCliScene(sceneName)) {
-            return 'chromium';
+    // ---------- 命令 ----------
+
+    printOverview() {
+        this.out('Playwright 浏览器模式（同一时间只有一个）:');
+        for (const [name, desc] of MODE_HELP) {
+            this.out(`  ${name.padEnd(8)}${desc}`);
         }
-        const cfg = this.buildSceneConfig(sceneName);
-        const browserName = cfg && cfg.browser && cfg.browser.browserName;
-        return String(browserName || 'chromium');
+        this.out('');
+        this.out('用法: manyoyo playwright up <headed|chrome|vnc>    切换模式');
+        this.out('      manyoyo playwright down                     回到默认模式');
+        this.out('      manyoyo playwright status                   查看当前模式与真实可用性');
     }
 
-    ensureContainerScenePrerequisites(sceneName) {
-        if (!this.sceneConfigMissing(sceneName)) {
+    printUsage(state) {
+        this.out('');
+        this.out('容器内 Agent: 自动生效，直接 manyoyo run；已打开浏览器的会话先执行 playwright-cli close 再重新 open。');
+        if (state.mode === 'default') {
             return;
         }
-        const tag = String(this.config.dockerTag || 'latest').trim() || 'latest';
-        const image = `mcr.microsoft.com/playwright/mcp:${tag}`;
-        this.runCmd([this.config.containerRuntime, 'pull', image], { check: true });
+        const configPath = this.userDisplayPath(this.writeHostConfig(state));
+        this.out(`宿主机上的 Agent: PLAYWRIGHT_MCP_CONFIG=${shellValue(configPath)} claude`);
+        if (state.mode === 'vnc') {
+            this.out(`noVNC 观看: ${this.novncUrl()}`);
+            this.out(`原生 VNC: 127.0.0.1:${state.vncPort}（密码见 manyoyo playwright status）`);
+        }
+        if (state.mode === 'chrome') {
+            this.out('⚠️  风险: 容器内 Agent 能操作你 Chrome 里已登录的所有网站。Chrome 每次新连接（每次 playwright-cli open、每次 status）都会弹出“要允许远程调试吗？”，请点“允许”。');
+        }
+        if (state.mode !== 'default' && !(process.platform === 'darwin' && state.mode !== 'headed')) {
+            this.out(`安全: 端口 ${state.port} 监听 0.0.0.0，仅靠 token 保护；建议用防火墙限制来源。`);
+        }
     }
 
-    ensureHostScenePrerequisites(sceneName) {
-        if (!isCliScene(sceneName) && !this.sceneConfigMissing(sceneName)) {
-            return;
+    async up(mode, { extensionPaths = [], extensionNames = [] } = {}) {
+        if (!MODES.includes(mode)) {
+            this.printOverview();
+            if (mode) {
+                this.err('');
+                this.err(`未知模式: ${mode}，可用: ${MODES.join(', ')}`);
+            }
+            return 1;
+        }
+        const extPaths = extensions.resolveExtensionInputs(this.root, { extensionPaths, extensionNames });
+        if (extPaths.length > 0 && mode === 'chrome') {
+            this.err('chrome 模式控制的是你自己的 Chrome，不支持 --ext-path / --ext-name；扩展只支持 headed、vnc。');
+            return 1;
+        }
+        this.ensureDirs();
+        await this.stopCurrent(this.readState());
+        this.writeState({ mode: 'default' });
+
+        const started = mode === 'headed' ? await this.startHeaded(extPaths)
+            : mode === 'chrome' ? await this.startChrome()
+                : await this.startVnc(extPaths);
+        if (typeof started === 'number') {
+            this.writeCurrentConfig({ mode: 'default' }, this.runtimeCommand());
+            return started;
+        }
+        const state = { ...started, startedAt: new Date().toISOString() };
+        this.writeState(state);
+        this.writeCurrentConfig(state, this.runtimeCommand());
+
+        if (mode === 'chrome') {
+            this.out('等待 Chrome 确认：请在 Chrome 弹出的“要允许远程调试吗？”里点“允许”（最多等 60 秒）…');
+        }
+        const result = await this.probeState(state);
+        if (!result.ok) {
+            if (mode === 'chrome') {
+                this.err('[up] chrome 失败: 连不上 Chrome 的调试接口。');
+                this.err('请确认已在 chrome://inspect/#remote-debugging 开启远程调试，并在 Chrome 弹出的“要允许远程调试吗？”里点“允许”（60 秒内），然后重试。');
+            } else {
+                this.err(`[up] ${mode} 失败: 浏览器服务已启动，但打不开页面（${result.error}）。`);
+                this.err(tailText(this.logPath(), 10));
+            }
+            // 回滚：不让坏掉的模式留在配置里
+            await this.stopCurrent(state);
+            this.writeState({ mode: 'default' });
+            this.writeCurrentConfig({ mode: 'default' }, this.runtimeCommand());
+            this.err('已回到默认模式。');
+            return 1;
         }
-        this.runCmd([this.playwrightBinPath(sceneName), 'install', '--with-deps', this.defaultBrowserName(sceneName)], { check: true });
+        this.out(`✅ ${mode} 模式已就绪（真实探测通过，${result.ms}ms）`);
+        this.printUsage(state);
+        return 0;
     }
 
-    scenePidFile(sceneName) {
-        return path.join(this.config.runDir, `${sceneName}.pid`);
+    runtimeCommand() {
+        try {
+            return this.resolveRuntime().command;
+        } catch {
+            return 'docker';
+        }
     }
 
-    sceneLogFile(sceneName) {
-        return path.join(this.config.runDir, `${sceneName}.log`);
+    async down() {
+        const state = this.readState();
+        await this.stopCurrent(state);
+        this.ensureDirs();
+        fs.rmSync(this.tokenPath(), { force: true });
+        fs.rmSync(this.hostConfigPath(), { force: true });
+        this.writeState({ mode: 'default' });
+        this.writeCurrentConfig({ mode: 'default' }, this.runtimeCommand());
+        this.out(state.mode === 'default'
+            ? '当前已是默认模式（容器内虚拟屏里的有头浏览器）。'
+            : `已停止 ${state.mode} 模式，回到默认模式；已打开浏览器的容器会话先 playwright-cli close 再重新 open。`);
+        return 0;
     }
 
-    localBinPath(binName) {
-        const filename = process.platform === 'win32' ? `${binName}.cmd` : binName;
-        const binPath = path.join(this.projectRoot, 'node_modules', '.bin', filename);
-        if (!fs.existsSync(binPath)) {
-            throw new Error(`local binary not found: ${binPath}. Run npm install first.`);
+    // 配置文件被删（或整个目录被删）时重建；返回是否重建过
+    ensureCurrentFiles(state) {
+        const missing = ['config.json', 'stealth.init.js'].some(name => !fs.existsSync(path.join(this.currentDir, name)));
+        if (missing) {
+            this.writeCurrentConfig(state, this.runtimeCommand());
         }
-        return binPath;
+        return missing;
     }
 
-    playwrightBinPath(sceneName) {
-        if (!isCliScene(sceneName)) {
-            return this.localBinPath('playwright');
+    async status() {
+        let state = this.readState();
+        if (this.ensureCurrentFiles(state)) {
+            this.out('[status] 容器内浏览器的配置文件缺失，已重建；运行中的容器会自动恢复（整个 ~/.manyoyo/plugin/playwright 目录被删过的容器需要重建）。');
         }
-
-        const filename = process.platform === 'win32' ? 'playwright.cmd' : 'playwright';
-        const candidates = [
-            path.join(this.projectRoot, 'node_modules', '@playwright', 'mcp', 'node_modules', '.bin', filename),
-            path.join(this.projectRoot, 'node_modules', '.bin', filename)
-        ];
-
-        for (const candidate of candidates) {
-            if (fs.existsSync(candidate)) {
-                return candidate;
+        if (state.mode === 'default') {
+            this.out('当前模式: default（容器内虚拟屏里的有头浏览器，无需宿主机进程）');
+            this.out('想换模式: manyoyo playwright   查看全部模式');
+            return 0;
+        }
+        this.out(`当前模式: ${state.mode}（端口 ${state.port}${state.pid ? `，pid ${state.pid}` : ''}）`);
+        const alive = await this.modeAlive(state);
+        const result = alive ? await this.probeState(state) : { ok: false, error: state.mode === 'vnc' ? 'vnc 容器没有在运行' : '浏览器服务进程已不在' };
+        if (result.ok) {
+            this.out(`真实探测: 通过（${result.ms}ms）`);
+            if (state.mode === 'vnc') {
+                this.out(`noVNC: ${this.novncUrl()}`);
             }
+            return 0;
         }
-
-        throw new Error(`local binary not found for ${sceneName}. Run npm install first.`);
-    }
-
-    extensionDirPath() {
-        return path.join(this.config.homeDir, '.manyoyo', 'plugin', 'playwright', 'extensions');
+        this.err(`真实探测: 失败（${result.error}）`);
+        state = { mode: 'default' };
+        this.writeState(state);
+        this.writeCurrentConfig(state, this.runtimeCommand());
+        this.err('已把容器内浏览器回退到默认模式。恢复: manyoyo playwright up <headed|chrome|vnc>；排查: manyoyo playwright logs');
+        return 1;
     }
 
-    extensionTmpDirPath() {
-        return path.join(this.config.homeDir, '.manyoyo', 'plugin', 'playwright', 'tmp-crx');
+    logs() {
+        const state = this.readState();
+        if (state.mode === 'vnc') {
+            const logs = this.runtimeCall(['logs', '--tail', '80', VNC_CONTAINER]);
+            this.out(`${logs.stdout}${logs.stderr}`.trimEnd() || '[logs] 没有日志');
+            return logs.status === 0 ? 0 : 1;
+        }
+        this.out(tailText(this.logPath(), 80).trimEnd() || '[logs] 没有日志');
+        return 0;
     }
 
-    cliBrowserCacheDirPath() {
-        return path.join(this.config.homeDir, '.manyoyo', '.cache', 'ms-playwright');
+    // 想用 MCP 的 Agent：在容器内以 stdio 注册，读同一个 $PLAYWRIGHT_MCP_CONFIG，自动跟随当前模式
+    mcpAdd() {
+        this.out('# 在容器内执行（playwright-mcp 随当前模式自动切换，无需重新注册）');
+        this.out('claude mcp add -s user playwright -- playwright-mcp');
+        this.out('codex mcp add playwright -- playwright-mcp');
+        this.out('gemini mcp add -s user playwright playwright-mcp');
+        return 0;
     }
 
-    ensureCliHostHeadedCacheDir(sceneName) {
-        if (sceneName !== 'cli-host-headed') {
-            return;
-        }
-        fs.mkdirSync(this.cliBrowserCacheDirPath(), { recursive: true });
-    }
-
-    resolveTargets(sceneName = 'all') {
-        const requested = String(sceneName || 'all').trim();
-        const enabledSet = new Set(this.config.enabledScenes);
-        const runtime = this.config.runtime;
-
-        const isAllowedByRuntime = (scene) => {
-            const type = SCENE_DEFS[scene].type;
-            if (runtime === 'mixed') {
-                return true;
-            }
-            return runtime === type;
-        };
-
-        if (requested !== 'all') {
-            if (!SCENE_DEFS[requested]) {
-                throw new Error(`未知场景: ${requested}`);
-            }
-            if (!enabledSet.has(requested)) {
-                throw new Error(`场景未启用: ${requested}`);
-            }
-            if (!isAllowedByRuntime(requested)) {
-                throw new Error(`当前 runtime=${runtime}，不允许场景: ${requested}`);
-            }
-            return [requested];
-        }
-
-        return SCENE_ORDER
-            .filter(scene => enabledSet.has(scene))
-            .filter(scene => isAllowedByRuntime(scene));
-    }
-
-    resolveExtensionPaths(extensionArgs = []) {
-        const inputs = asStringArray(extensionArgs, []);
-        const uniquePaths = [];
-        const seen = new Set();
-
-        for (const item of inputs) {
-            const absPath = path.resolve(item);
-            if (!fs.existsSync(absPath)) {
-                throw new Error(`扩展路径不存在: ${absPath}`);
-            }
-            const stat = fs.statSync(absPath);
-            if (!stat.isDirectory()) {
-                throw new Error(`扩展路径必须是目录: ${absPath}`);
-            }
-
-            const manifestPath = path.join(absPath, 'manifest.json');
-            if (fs.existsSync(manifestPath)) {
-                if (!seen.has(absPath)) {
-                    seen.add(absPath);
-                    uniquePaths.push(absPath);
-                }
-                continue;
-            }
-
-            const children = fs.readdirSync(absPath, { withFileTypes: true })
-                .filter(dirent => dirent.isDirectory())
-                .map(dirent => path.join(absPath, dirent.name))
-                .filter(child => fs.existsSync(path.join(child, 'manifest.json')));
-
-            if (children.length === 0) {
-                throw new Error(`目录下未找到扩展(manifest.json): ${absPath}`);
-            }
-
-            for (const childPath of children) {
-                if (!seen.has(childPath)) {
-                    seen.add(childPath);
-                    uniquePaths.push(childPath);
-                }
-            }
-        }
-
-        return uniquePaths;
-    }
-
-    resolveNamedExtensionPaths(extensionNames = []) {
-        const names = asStringArray(extensionNames, []);
-        const extensionRoot = path.resolve(this.extensionDirPath());
-
-        return names.map(name => {
-            if (name.includes('/') || name.includes('\\') || name === '.' || name === '..') {
-                throw new Error(`扩展名称无效: ${name}`);
-            }
-            return path.join(extensionRoot, name);
-        });
-    }
-
-    resolveExtensionInputs(options = {}) {
-        const extensionPaths = asStringArray(options.extensionPaths, []);
-        const namedPaths = this.resolveNamedExtensionPaths(options.extensionNames || []);
-        return this.resolveExtensionPaths([...extensionPaths, ...namedPaths]);
-    }
-
-    buildExtensionLaunchArgs(extensionPaths) {
-        const joined = extensionPaths.join(',');
-        return [
-            `--disable-extensions-except=${joined}`,
-            `--load-extension=${joined}`
-        ];
-    }
-
-    sanitizeExtensionMountName(value) {
-        const sanitized = String(value || '')
-            .trim()
-            .replace(/[^A-Za-z0-9._-]/g, '-')
-            .replace(/-+/g, '-')
-            .replace(/^-|-$/g, '');
-        return sanitized || 'ext';
-    }
-
-    buildContainerExtensionMounts(extensionPaths = []) {
-        const hostPaths = asStringArray(extensionPaths, []);
-        const containerPaths = [];
-        const volumeMounts = [];
-
-        hostPaths.forEach((hostPath, idx) => {
-            const safeName = this.sanitizeExtensionMountName(path.basename(hostPath));
-            const containerPath = path.posix.join(CONTAINER_EXTENSION_ROOT, `ext-${idx + 1}-${safeName}`);
-            containerPaths.push(containerPath);
-            volumeMounts.push(`${hostPath}:${containerPath}:ro`);
-        });
-
-        return { containerPaths, volumeMounts };
-    }
-
-    baseLaunchArgs() {
-        return [
-            `--user-agent=${DEFAULT_FINGERPRINT_PROFILE.userAgent}`,
-            `--lang=${DEFAULT_FINGERPRINT_PROFILE.locale}`,
-            `--window-size=${DEFAULT_FINGERPRINT_PROFILE.width},${DEFAULT_FINGERPRINT_PROFILE.height}`,
-            '--disable-blink-features=AutomationControlled',
-            '--force-webrtc-ip-handling-policy=disable_non_proxied_udp'
-        ];
-    }
-
-    buildMcpSceneConfig(sceneName, options = {}) {
-        const def = SCENE_DEFS[sceneName];
-        const port = this.scenePort(sceneName);
-        const extensionPaths = asStringArray(options.extensionPaths, []);
-        const initScript = asStringArray(options.initScript, []);
-        const launchOptions = {
-            channel: 'chromium',
-            headless: def.headless,
-            args: [...this.baseLaunchArgs()]
-        };
-
-        if (extensionPaths.length > 0) {
-            launchOptions.args.push(...this.buildExtensionLaunchArgs(extensionPaths));
-        }
-        if (this.config.disableWebRTC) {
-            launchOptions.args.push(...DISABLE_WEBRTC_LAUNCH_ARGS);
-        }
-
-        const contextOptions = {
-            userAgent: DEFAULT_FINGERPRINT_PROFILE.userAgent,
-            locale: DEFAULT_FINGERPRINT_PROFILE.locale,
-            timezoneId: DEFAULT_FINGERPRINT_PROFILE.timezoneId,
-            extraHTTPHeaders: {
-                'Accept-Language': DEFAULT_FINGERPRINT_PROFILE.acceptLanguage
-            }
-        };
-        if (sceneName !== 'mcp-host-headed') {
-            contextOptions.viewport = {
-                width: DEFAULT_FINGERPRINT_PROFILE.width,
-                height: DEFAULT_FINGERPRINT_PROFILE.height
-            };
-            contextOptions.screen = {
-                width: DEFAULT_FINGERPRINT_PROFILE.width,
-                height: DEFAULT_FINGERPRINT_PROFILE.height
-            };
-        }
-
-        return {
-            outputDir: '/tmp/.playwright-mcp',
-            server: {
-                host: def.listenHost,
-                port,
-                allowedHosts: [
-                    `localhost:${port}`,
-                    `127.0.0.1:${port}`,
-                    `host.docker.internal:${port}`,
-                    `host.containers.internal:${port}`
-                ]
-            },
-            browser: {
-                chromiumSandbox: true,
-                browserName: 'chromium',
-                initScript,
-                launchOptions,
-                contextOptions
-            }
-        };
-    }
-
-    buildCliSceneConfig(sceneName, options = {}) {
-        const def = SCENE_DEFS[sceneName];
-        const extensionPaths = asStringArray(options.extensionPaths, []);
-        const payload = {
-            host: def.listenHost,
-            port: this.scenePort(sceneName),
-            wsPath: `/${sceneName}-${crypto.randomBytes(8).toString('hex')}`,
-            headless: def.headless,
-            channel: 'chromium',
-            chromiumSandbox: true,
-            args: [...this.baseLaunchArgs()]
-        };
-
-        if (extensionPaths.length > 0) {
-            payload.args.push(...this.buildExtensionLaunchArgs(extensionPaths));
-        }
-        if (this.config.disableWebRTC) {
-            payload.args.push(...DISABLE_WEBRTC_LAUNCH_ARGS);
-        }
-
-        return payload;
-    }
-
-    buildSceneConfig(sceneName, options = {}) {
-        if (isCliScene(sceneName)) {
-            return this.buildCliSceneConfig(sceneName, options);
-        }
-        return this.buildMcpSceneConfig(sceneName, options);
-    }
-
-    ensureSceneConfig(sceneName, options = {}) {
-        fs.mkdirSync(this.config.configDir, { recursive: true });
-        if (isCliScene(sceneName)) {
-            const payload = this.buildCliSceneConfig(sceneName, options);
-            const filePath = this.sceneConfigPath(sceneName);
-            fs.writeFileSync(filePath, `${JSON.stringify(payload, null, 4)}\n`, 'utf8');
-            return filePath;
-        }
-        const initScriptPath = this.ensureSceneInitScript(sceneName);
-        const configuredInitScript = asStringArray(options.initScript, []);
-        const initScript = configuredInitScript.length > 0 ? configuredInitScript : [initScriptPath];
-        const payload = this.buildSceneConfig(sceneName, {
-            ...options,
-            initScript
-        });
-        const filePath = this.sceneConfigPath(sceneName);
-        fs.writeFileSync(filePath, `${JSON.stringify(payload, null, 4)}\n`, 'utf8');
-        return filePath;
-    }
-
-    async portReady(port) {
-        return await new Promise((resolve) => {
-            let settled = false;
-            const socket = net.createConnection({ host: '127.0.0.1', port });
-
-            const finish = (value) => {
-                if (settled) {
-                    return;
-                }
-                settled = true;
-                socket.destroy();
-                resolve(value);
-            };
-
-            socket.setTimeout(300);
-            socket.once('connect', () => finish(true));
-            socket.once('timeout', () => finish(false));
-            socket.once('error', () => finish(false));
-        });
-    }
-
-    async waitForPort(port) {
-        for (let i = 0; i < 60; i += 1) {
-            // eslint-disable-next-line no-await-in-loop
-            if (await this.portReady(port)) {
-                return true;
-            }
-            // eslint-disable-next-line no-await-in-loop
-            await sleep(500);
-        }
-        return false;
-    }
-
-    containerEnv(sceneName, cfgPath, options = {}) {
-        const def = SCENE_DEFS[sceneName];
-        const requireVncPassword = options.requireVncPassword === true;
-        const env = {
-            ...process.env,
-            PLAYWRIGHT_MCP_DOCKER_TAG: this.config.dockerTag,
-            PLAYWRIGHT_MCP_PORT: String(this.scenePort(sceneName)),
-            PLAYWRIGHT_MCP_CONFIG_PATH: cfgPath,
-            PLAYWRIGHT_MCP_CONTAINER_NAME: def.containerName,
-            PLAYWRIGHT_MCP_IMAGE: this.config.headedImage,
-            PLAYWRIGHT_MCP_NOVNC_PORT: String(this.config.ports.mcpContHeadedNoVnc)
-        };
-
-        if (sceneName === 'mcp-cont-headed') {
-            const envKey = this.config.vncPasswordEnvKey;
-            let password = process.env[envKey];
-            if (!password) {
-                password = this.randomAlnum(16);
-                if (requireVncPassword) {
-                    this.writeStdout(`[up] mcp-cont-headed ${envKey} not set; generated random 16-char password: ${password}`);
-                }
-            }
-            env.VNC_PASSWORD = password;
-        }
-
-        return env;
-    }
-
-    containerComposePath(sceneName) {
-        const def = SCENE_DEFS[sceneName];
-        return path.join(this.config.composeDir, def.composeFile);
-    }
-
-    sceneComposeOverridePath(sceneName) {
-        return path.join(this.config.runDir, `${sceneName}.compose.override.yaml`);
-    }
-
-    ensureContainerComposeOverride(sceneName, volumeMounts = []) {
-        const overridePath = this.sceneComposeOverridePath(sceneName);
-        if (!Array.isArray(volumeMounts) || volumeMounts.length === 0) {
-            fs.rmSync(overridePath, { force: true });
-            return '';
-        }
-
-        fs.mkdirSync(this.config.runDir, { recursive: true });
-        const lines = [
-            'services:',
-            '  playwright:',
-            '    volumes:'
-        ];
-        volumeMounts.forEach(item => {
-            lines.push(`      - ${JSON.stringify(String(item))}`);
-        });
-        fs.writeFileSync(overridePath, `${lines.join('\n')}\n`, 'utf8');
-        return overridePath;
-    }
-
-    buildCliSessionIntegration(dockerCmd) {
-        const sceneName = this.config.cliSessionScene;
-        if (!sceneName) {
-            return { envEntries: [], extraArgs: [], volumeEntries: [] };
-        }
-
-        if (isDevScene(sceneName)) {
-            return this.buildDevHostCliSessionIntegration(dockerCmd, sceneName);
-        }
-
-        const endpoint = this.readSceneEndpoint(sceneName);
-        if (!endpoint || !Number.isInteger(endpoint.port) || endpoint.port <= 0 || typeof endpoint.wsPath !== 'string' || !endpoint.wsPath) {
-            return { envEntries: [], extraArgs: [], volumeEntries: [] };
-        }
-
-        const normalizedDockerCmd = path.basename(String(dockerCmd || '').trim()).toLowerCase();
-        const connectHost = normalizedDockerCmd === 'podman' ? 'host.containers.internal' : 'host.docker.internal';
-        const remoteEndpoint = `ws://${connectHost}:${endpoint.port}${endpoint.wsPath}`;
-        const hostConfigPath = this.sceneCliAttachConfigPath(sceneName);
-        const containerConfigPath = `/tmp/manyoyo-playwright/${sceneName}.cli-attach.json`;
-        this.writeSceneCliAttachConfig(sceneName, {
-            outputDir: '/tmp/.playwright-cli',
-            browser: {
-                // launch-server（非 shared）不预创建 context；remoteEndpoint 存在时
-                // playwright-cli 默认 isolated=false 会走 contexts()[0] 并报
-                // "unable to connect to a browser that does not have any contexts"，
-                // 因此容器内会话必须以 isolated 模式自建 context。
-                remoteEndpoint,
-                isolated: true
-            }
-        });
-        const envEntries = [
-            `PLAYWRIGHT_MCP_CONFIG=${containerConfigPath}`
-        ];
-        const extraArgs = normalizedDockerCmd === 'docker'
-            ? ['--add-host', 'host.docker.internal:host-gateway']
-            : [];
-        const volumeEntries = ['--volume', `${hostConfigPath}:${containerConfigPath}:ro`];
-        return { envEntries, extraArgs, volumeEntries };
-    }
-
-    buildDevHostCliSessionIntegration(dockerCmd, sceneName) {
-        const endpoint = this.readDevToolsActivePort();
-        const normalizedDockerCmd = path.basename(String(dockerCmd || '').trim()).toLowerCase();
-        const connectHost = normalizedDockerCmd === 'podman' ? 'host.containers.internal' : 'host.docker.internal';
-        const hostConfigPath = this.sceneCliAttachConfigPath(sceneName);
-        const containerConfigPath = `/tmp/manyoyo-playwright/${sceneName}.cli-attach.json`;
-
-        this.writeSceneCliAttachConfig(sceneName, this.buildDevHostAttachConfig(endpoint, connectHost));
-
-        const envEntries = [
-            `PLAYWRIGHT_MCP_CONFIG=${containerConfigPath}`
-        ];
-        const extraArgs = normalizedDockerCmd === 'docker'
-            ? ['--add-host', 'host.docker.internal:host-gateway']
-            : [];
-        const volumeEntries = ['--volume', `${hostConfigPath}:${containerConfigPath}:ro`];
-        return { envEntries, extraArgs, volumeEntries };
-    }
-
-    async startContainer(sceneName, options = {}) {
-        const runtime = this.config.containerRuntime;
-        if (!this.ensureCommandAvailable(runtime)) {
-            this.writeStderr(`[up] ${sceneName} failed: ${runtime} command not found.`);
-            return 1;
-        }
-
-        try {
-            this.ensureContainerScenePrerequisites(sceneName);
-        } catch (error) {
-            return error.returncode || 1;
-        }
-
-        const incomingExtensionPaths = asStringArray(options.extensionPaths, []);
-        const hostInitScriptPath = this.sceneInitScriptPath(sceneName);
-        const containerInitScriptPath = path.posix.join('/app/config', path.basename(hostInitScriptPath));
-        let configOptions = {
-            ...options,
-            extensionPaths: incomingExtensionPaths,
-            initScript: [containerInitScriptPath]
-        };
-        const composeFiles = [this.containerComposePath(sceneName)];
-        const volumeMounts = [`${hostInitScriptPath}:${containerInitScriptPath}:ro`];
-
-        if (incomingExtensionPaths.length > 0) {
-            const mapped = this.buildContainerExtensionMounts(incomingExtensionPaths);
-            volumeMounts.push(...mapped.volumeMounts);
-            configOptions = {
-                ...options,
-                extensionPaths: mapped.containerPaths,
-                initScript: [containerInitScriptPath]
-            };
-        }
-        const cfgPath = this.ensureSceneConfig(sceneName, configOptions);
-        const overridePath = this.ensureContainerComposeOverride(sceneName, volumeMounts);
-        if (overridePath) {
-            composeFiles.push(overridePath);
-        }
-
-        const env = this.containerEnv(sceneName, cfgPath, { requireVncPassword: true });
-        const def = SCENE_DEFS[sceneName];
-
-        try {
-            const args = [
-                runtime,
-                'compose',
-                '-p',
-                def.projectName
-            ];
-            composeFiles.forEach(filePath => {
-                args.push('-f', filePath);
-            });
-            args.push('up', '-d');
-            this.runCmd(args, { env, check: true });
-        } catch (error) {
-            return error.returncode || 1;
-        }
-
-        const port = this.scenePort(sceneName);
-        if (await this.waitForPort(port)) {
-            this.writeStdout(`[up] ${sceneName} ready on 127.0.0.1:${port}`);
-            return 0;
-        }
-
-        this.writeStderr(`[up] ${sceneName} did not become ready on 127.0.0.1:${port}`);
-        return 1;
-    }
-
-    stopContainer(sceneName) {
-        const runtime = this.config.containerRuntime;
-        if (!this.ensureCommandAvailable(runtime)) {
-            this.writeStderr(`[down] ${sceneName} failed: ${runtime} command not found.`);
-            return 1;
-        }
-
-        this.ensureContainerComposeOverride(sceneName, []);
-        const cfgPath = this.sceneConfigPath(sceneName);
-        const env = this.containerEnv(sceneName, cfgPath);
-        const def = SCENE_DEFS[sceneName];
-
-        try {
-            this.runCmd([
-                runtime,
-                'compose',
-                '-p',
-                def.projectName,
-                '-f',
-                this.containerComposePath(sceneName),
-                'down'
-            ], { env, check: true });
-        } catch (error) {
-            return error.returncode || 1;
-        }
-
-        this.writeStdout(`[down] ${sceneName}`);
-        return 0;
-    }
-
-    statusContainer(sceneName) {
-        const runtime = this.config.containerRuntime;
-        if (!this.ensureCommandAvailable(runtime)) {
-            this.writeStderr(`[status] ${sceneName} failed: ${runtime} command not found.`);
-            return 1;
-        }
-
-        const def = SCENE_DEFS[sceneName];
-        const cp = this.runCmd([
-            runtime,
-            'ps',
-            '--filter',
-            `name=${def.containerName}`,
-            '--format',
-            '{{.Names}}'
-        ], { captureOutput: true, check: false });
-
-        const names = new Set(
-            cp.stdout
-                .split(/\r?\n/)
-                .map(line => line.trim())
-                .filter(Boolean)
-        );
-
-        if (names.has(def.containerName)) {
-            this.writeStdout(`[status] ${sceneName} running`);
-        } else {
-            this.writeStdout(`[status] ${sceneName} stopped`);
-        }
-        return 0;
-    }
-
-    logsContainer(sceneName) {
-        const runtime = this.config.containerRuntime;
-        if (!this.ensureCommandAvailable(runtime)) {
-            this.writeStderr(`[logs] ${sceneName} failed: ${runtime} command not found.`);
-            return 1;
-        }
-
-        const def = SCENE_DEFS[sceneName];
-        const cp = this.runCmd([
-            runtime,
-            'logs',
-            '--tail',
-            '80',
-            def.containerName
-        ], { captureOutput: true, check: false });
-
-        const output = cp.stdout || cp.stderr;
-        if (output.trim()) {
-            this.writeStdout(output.trimEnd());
-        } else {
-            this.writeStdout(`[logs] ${sceneName} no logs`);
-        }
-
-        return cp.returncode === 0 ? 0 : 1;
-    }
-
-    hostLaunchCommand(sceneName, cfgPath) {
-        if (isCliScene(sceneName)) {
-            return {
-                command: this.playwrightBinPath(sceneName),
-                args: ['launch-server', '--browser', this.defaultBrowserName(sceneName), '--config', String(cfgPath)]
-            };
-        }
-        return {
-            command: this.localBinPath('playwright-mcp'),
-            args: ['--config', String(cfgPath)]
-        };
-    }
-
-    spawnHostProcess(command, args, logFd) {
-        return spawn(command, args, {
-            detached: true,
-            stdio: ['ignore', logFd, logFd]
-        });
-    }
-
-    stopHostStarter(pid) {
-        if (!Number.isInteger(pid) || pid <= 0) {
-            return;
-        }
-        try {
-            process.kill(-pid, 'SIGTERM');
-            return;
-        } catch {
-            // no-op
-        }
-        try {
-            process.kill(pid, 'SIGTERM');
-        } catch {
-            // no-op
-        }
-    }
-
-    hostScenePids(sceneName) {
-        const cfgPath = this.sceneConfigPath(sceneName);
-        const pattern = isCliScene(sceneName)
-            ? `playwright.*launch-server.*--config ${cfgPath}`
-            : `playwright-mcp.*--config ${cfgPath}`;
-        const cp = this.runCmd(['pgrep', '-f', pattern], { captureOutput: true, check: false });
-
-        if (cp.returncode !== 0 || !cp.stdout.trim()) {
-            return [];
-        }
-
-        const pids = [];
-        for (const line of cp.stdout.split(/\r?\n/)) {
-            const text = line.trim();
-            if (/^\d+$/.test(text)) {
-                pids.push(Number(text));
-            }
-        }
-        return pids;
-    }
-
-    async waitForHostPids(sceneName, fallbackPid) {
-        for (let i = 0; i < 5; i += 1) {
-            const pids = this.hostScenePids(sceneName);
-            if (pids.length > 0) {
-                return pids;
-            }
-            // eslint-disable-next-line no-await-in-loop
-            await sleep(100);
-        }
-        if (Number.isInteger(fallbackPid) && fallbackPid > 0) {
-            return [fallbackPid];
-        }
-        return [];
-    }
-
-    async startHost(sceneName, options = {}) {
-        try {
-            this.ensureCliHostHeadedCacheDir(sceneName);
-            this.ensureHostScenePrerequisites(sceneName);
-        } catch (error) {
-            this.writeStderr(`[up] ${sceneName} failed: ${error.message || String(error)}`);
-            return error.returncode || 1;
-        }
-
-        fs.mkdirSync(this.config.runDir, { recursive: true });
-        const cfgPath = this.ensureSceneConfig(sceneName, options);
-        const pidFile = this.scenePidFile(sceneName);
-        const logFile = this.sceneLogFile(sceneName);
-        const port = this.scenePort(sceneName);
-        this.removeSceneEndpoint(sceneName);
-        this.removeSceneCliAttachConfig(sceneName);
-
-        let managedPids = this.hostScenePids(sceneName);
-        if (managedPids.length > 0 && (await this.portReady(port))) {
-            this.writeStdout(`[up] ${sceneName} already running (pid(s) ${managedPids.join(' ')})`);
-            return 0;
-        }
-
-        if (await this.portReady(port)) {
-            this.writeStderr(`[up] ${sceneName} failed: port ${port} is already in use by another process.`);
-            this.writeStderr('Stop the conflicting process first, then retry.');
-            return 1;
-        }
-
-        fs.rmSync(pidFile, { force: true });
-        const logFd = fs.openSync(logFile, 'a');
-        let launchCommand = null;
-        try {
-            launchCommand = this.hostLaunchCommand(sceneName, cfgPath);
-        } catch (error) {
-            fs.closeSync(logFd);
-            this.writeStderr(`[up] ${sceneName} failed: ${error.message || String(error)}`);
-            return 1;
-        }
-
-        const starter = this.spawnHostProcess(launchCommand.command, launchCommand.args, logFd);
-        fs.closeSync(logFd);
-        if (typeof starter.unref === 'function') {
-            starter.unref();
-        }
-
-        if (await this.waitForPort(port)) {
-            if (isCliScene(sceneName)) {
-                const cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
-                this.writeSceneEndpoint(sceneName, {
-                    port,
-                    wsPath: String(cfg.wsPath || '')
-                });
-            }
-            managedPids = await this.waitForHostPids(sceneName, starter.pid);
-            if (managedPids.length > 0) {
-                fs.writeFileSync(pidFile, `${managedPids[0]}`, 'utf8');
-                this.writeStdout(`[up] ${sceneName} ready on 127.0.0.1:${port} (pid(s) ${managedPids.join(' ')})`);
-                this.remindCliSessionScene(sceneName);
-                return 0;
-            }
-        }
-
-        this.writeStderr(`[up] ${sceneName} failed to start. tail ${logFile}:`);
-        const tail = tailText(logFile, 30);
-        if (tail) {
-            this.writeStderr(tail);
-        }
-
-        if (starter.exitCode === null && !starter.killed) {
-            this.stopHostStarter(starter.pid);
-        }
-
-        return 1;
-    }
-
-    async startDevHost(sceneName) {
-        this.openChromeRemoteDebuggingPage();
-        try {
-            const endpoint = this.readDevToolsActivePort();
-            if (!(await this.portReady(endpoint.port))) {
-                throw new Error(`DevToolsActivePort 指向 127.0.0.1:${endpoint.port}，但该端口不可连接；请确认 Chrome remote debugging 已启用，或重新打开 Chrome 后再试。`);
-            }
-            const cfgPath = this.writeDevHostAttachConfig(sceneName, endpoint);
-            this.writeStdout(`[up] ${sceneName} ready via DevToolsActivePort (${endpoint.filePath}, 127.0.0.1:${endpoint.port})`);
-            this.writeStdout(`[tip] 已尝试打开 ${this.remoteDebuggingPageUrl()}，请确认 remote debugging 已启用。`);
-            this.writeDevHostUsage(cfgPath);
-            return 0;
-        } catch (error) {
-            this.writeStderr(`[up] ${sceneName} failed: ${error.message || String(error)}`);
-            return 1;
-        }
-    }
-
-    async stopHost(sceneName) {
-        const pidFile = this.scenePidFile(sceneName);
-        const port = this.scenePort(sceneName);
-        const managedPids = this.hostScenePids(sceneName);
-        this.removeSceneEndpoint(sceneName);
-        this.removeSceneCliAttachConfig(sceneName);
-
-        for (const pid of managedPids) {
-            try {
-                process.kill(pid, 'SIGTERM');
-            } catch {
-                // no-op
-            }
-        }
-
-        if (managedPids.length > 0) {
-            await sleep(300);
-        }
-
-        if (fs.existsSync(pidFile)) {
-            const text = fs.readFileSync(pidFile, 'utf8').trim();
-            if (/^\d+$/.test(text)) {
-                try {
-                    process.kill(Number(text), 'SIGTERM');
-                } catch {
-                    // no-op
-                }
-            }
-            fs.rmSync(pidFile, { force: true });
-        }
-
-        if (await this.portReady(port)) {
-            this.writeStderr(`[down] ${sceneName} warning: port ${port} is still in use (possibly unmanaged process)`);
-            return 1;
-        }
-
-        this.writeStdout(`[down] ${sceneName}`);
-        return 0;
-    }
-
-    stopDevHost(sceneName) {
-        this.removeSceneEndpoint(sceneName);
-        this.removeSceneCliAttachConfig(sceneName);
-        this.removeDevHostAttachConfig(sceneName);
-        this.writeStdout(`[down] ${sceneName} no managed process`);
-        return 0;
-    }
-
-    async statusHost(sceneName) {
-        const pidFile = this.scenePidFile(sceneName);
-        const port = this.scenePort(sceneName);
-        const managedPids = this.hostScenePids(sceneName);
-
-        if (managedPids.length > 0 && (await this.portReady(port))) {
-            this.writeStdout(`[status] ${sceneName} running (pid(s) ${managedPids.join(' ')})`);
-            const pidfileValid = fs.existsSync(pidFile) && /^\d+$/.test(fs.readFileSync(pidFile, 'utf8').trim());
-            if (!pidfileValid) {
-                fs.mkdirSync(path.dirname(pidFile), { recursive: true });
-                fs.writeFileSync(pidFile, `${managedPids[0]}`, 'utf8');
-            }
-            return 0;
-        }
-
-        if (managedPids.length > 0 && !(await this.portReady(port))) {
-            this.writeStdout(`[status] ${sceneName} degraded (pid(s) ${managedPids.join(' ')}, port ${port} not reachable)`);
-            return 0;
-        }
-
-        fs.rmSync(pidFile, { force: true });
-        if (await this.portReady(port)) {
-            this.writeStdout(`[status] ${sceneName} conflict (port ${port} in use by unmanaged process)`);
-        } else {
-            this.writeStdout(`[status] ${sceneName} stopped`);
-        }
-        return 0;
-    }
-
-    statusDevHost(sceneName) {
-        try {
-            const endpoint = this.readDevToolsActivePort();
-            this.writeStdout(`[status] ${sceneName} configured (${endpoint.filePath}, 127.0.0.1:${endpoint.port})`);
-        } catch {
-            this.writeStdout(`[status] ${sceneName} not configured`);
-        }
-        return 0;
-    }
-
-    async healthScene(sceneName) {
-        if (isDevScene(sceneName)) {
-            try {
-                const endpoint = this.readDevToolsActivePort();
-                this.writeStdout(`[health] ${sceneName} ok (DevToolsActivePort 127.0.0.1:${endpoint.port})`);
-                return 0;
-            } catch (error) {
-                this.writeStdout(`[health] ${sceneName} fail (${error.message || String(error)})`);
-                return 1;
-            }
-        }
-
-        const port = this.scenePort(sceneName);
-        if (await this.portReady(port)) {
-            this.writeStdout(`[health] ${sceneName} ok (127.0.0.1:${port})`);
-            return 0;
-        }
-        this.writeStdout(`[health] ${sceneName} fail (127.0.0.1:${port})`);
-        return 1;
-    }
-
-    logsHost(sceneName) {
-        if (isDevScene(sceneName)) {
-            this.writeStdout(`[logs] ${sceneName} no managed process`);
-            return 0;
-        }
-
-        const logFile = this.sceneLogFile(sceneName);
-        if (!fs.existsSync(logFile)) {
-            this.writeStdout(`[logs] ${sceneName} no log file: ${logFile}`);
-            return 0;
-        }
-
-        const tail = tailText(logFile, 80);
-        if (tail) {
-            this.writeStdout(tail);
-        }
-        return 0;
-    }
-
-    async downloadFile(url, output, retries = 3, timeoutMs = 60_000) {
-        const timeoutSec = Math.max(1, Math.ceil(timeoutMs / 1000));
-        if (!this.ensureCommandAvailable('curl')) {
-            throw new Error('curl command not found');
-        }
-
-        let lastError = null;
-        for (let i = 1; i <= retries; i += 1) {
-            try {
-                const result = this.runCmd([
-                    'curl',
-                    '--fail',
-                    '--location',
-                    '--silent',
-                    '--show-error',
-                    '--connect-timeout',
-                    String(timeoutSec),
-                    '--max-time',
-                    String(timeoutSec),
-                    '--output',
-                    output,
-                    url
-                ], { captureOutput: true, check: false });
-                if (result.returncode !== 0) {
-                    throw new Error(result.stderr || `curl failed with exit code ${result.returncode}`);
-                }
-                return;
-            } catch (error) {
-                lastError = error;
-                if (i < retries) {
-                    // eslint-disable-next-line no-await-in-loop
-                    await sleep(1000);
-                }
-            }
-        }
-
-        throw new Error(`download failed after ${retries} attempts: ${url}; ${String(lastError)}`);
-    }
-
-    extractZipBuffer(zipBuffer, outDir) {
-        fs.mkdirSync(outDir, { recursive: true });
-        const tempZip = path.join(os.tmpdir(), `manyoyo-playwright-ext-${process.pid}-${Date.now()}.zip`);
-        fs.writeFileSync(tempZip, zipBuffer);
-
-        const result = spawnSync('unzip', ['-oq', tempZip, '-d', outDir], { encoding: 'utf8' });
-        fs.rmSync(tempZip, { force: true });
-
-        if (result.error) {
-            throw result.error;
-        }
-        if (result.status !== 0) {
-            throw new Error(result.stderr || `unzip failed with exit code ${result.status}`);
-        }
-    }
-
-    extractCrx(crxFile, outDir) {
-        const data = fs.readFileSync(crxFile);
-        const offset = crxZipOffset(data);
-        const zipBuffer = data.subarray(offset);
-
-        this.extractZipBuffer(zipBuffer, outDir);
-
-        const manifest = path.join(outDir, 'manifest.json');
-        if (!fs.existsSync(manifest)) {
-            throw new Error(`${crxFile} extracted but manifest.json missing`);
-        }
-
-        if (convertManifestV2ToV3(outDir)) {
-            this.writeStdout(`[manifest] upgraded to MV3: ${path.basename(outDir)}`);
-        }
-    }
-
-    async downloadExtensions(options = {}) {
-        if (!this.ensureCommandAvailable('unzip')) {
-            this.writeStderr('[ext-download] failed: unzip command not found.');
-            return 1;
-        }
-
-        const prodversion = String(options.prodversion || this.config.extensionProdversion || '132.0.0.0').trim();
-        const extDir = path.resolve(this.extensionDirPath());
-        const tmpDir = path.resolve(this.extensionTmpDirPath());
-
-        fs.rmSync(tmpDir, { recursive: true, force: true });
-        fs.mkdirSync(extDir, { recursive: true });
-        fs.mkdirSync(tmpDir, { recursive: true });
-
-        try {
-            this.writeStdout(`[info] ext dir: ${extDir}`);
-            this.writeStdout(`[info] tmp dir: ${tmpDir}`);
-
-            for (const [name, extId] of EXTENSIONS) {
-                const url = buildCrxUrl(extId, prodversion);
-                const crxFile = path.join(tmpDir, `${name}.crx`);
-                const outDir = path.join(extDir, name);
-
-                this.writeStdout(`[download] ${name}`);
-                // eslint-disable-next-line no-await-in-loop
-                await this.downloadFile(url, crxFile);
-
-                this.writeStdout(`[extract] ${name}`);
-                fs.rmSync(outDir, { recursive: true, force: true });
-                this.extractCrx(crxFile, outDir);
-            }
-        } finally {
-            fs.rmSync(tmpDir, { recursive: true, force: true });
-            this.writeStdout(`[cleanup] removed ${tmpDir}`);
-        }
-
-        this.writeStdout(`[done] all extensions are ready: ${extDir}`);
-        return 0;
-    }
-
-    detectCurrentIPv4() {
-        const interfaces = os.networkInterfaces();
-        for (const values of Object.values(interfaces)) {
-            if (!Array.isArray(values)) {
-                continue;
-            }
-            for (const item of values) {
-                if (!item || item.internal) {
-                    continue;
-                }
-                if (item.family === 'IPv4') {
-                    return item.address;
-                }
-            }
-        }
-        return '';
-    }
-
-    resolveMcpAddHost(hostArg) {
-        if (!hostArg) {
-            return this.config.mcpDefaultHost;
-        }
-        const value = String(hostArg).trim();
-        if (!value) {
-            return '';
-        }
-        if (value === 'current-ip') {
-            return this.detectCurrentIPv4();
-        }
-        return value;
-    }
-
-    printMcpAdd(hostArg) {
-        const host = this.resolveMcpAddHost(hostArg);
-        if (!host) {
-            this.writeStderr('[mcp-add] failed: cannot determine host. Use --host <host> to set one explicitly.');
-            return 1;
-        }
-
-        const scenes = this.resolveTargets('all').filter(sceneName => isMcpScene(sceneName));
-        this.writeStdout('# 在容器中执行');
-        for (const sceneName of scenes) {
-            const url = `http://${host}:${this.scenePort(sceneName)}/mcp`;
-            this.writeStdout(`claude mcp add -t http -s user playwright-${sceneName} ${url}`);
-        }
-        this.writeStdout('');
-        for (const sceneName of scenes) {
-            const url = `http://${host}:${this.scenePort(sceneName)}/mcp`;
-            this.writeStdout(`codex mcp add playwright-${sceneName} --url ${url}`);
-        }
-        this.writeStdout('');
-        for (const sceneName of scenes) {
-            const url = `http://${host}:${this.scenePort(sceneName)}/mcp`;
-            this.writeStdout(`gemini mcp add -t http -s user playwright-${sceneName} ${url}`);
-        }
-
-        return 0;
-    }
-
-    printCliAdd() {
-        const lines = [
-            '# 在宿主机中执行',
-            'PLAYWRIGHT_CLI_INSTALL_DIR="${TMPDIR:-/tmp}/manyoyo-playwright-cli-install-$$"',
-            'mkdir -p "$PLAYWRIGHT_CLI_INSTALL_DIR/.playwright"',
-            'cd "$PLAYWRIGHT_CLI_INSTALL_DIR"',
-            `npm install -g @playwright/cli@${PLAYWRIGHT_CLI_VERSION}`,
-            'playwright-cli install --skills',
-            'PLAYWRIGHT_CLI_SKILL_SOURCE="$PLAYWRIGHT_CLI_INSTALL_DIR/.claude/skills/playwright-cli"',
-            'for target in ~/.claude/skills/playwright-cli ~/.codex/skills/playwright-cli ~/.gemini/skills/playwright-cli; do',
-            '    mkdir -p "$target"',
-            '    cp -R "$PLAYWRIGHT_CLI_SKILL_SOURCE/." "$target/"',
-            'done',
-            'cd "$OLDPWD"',
-            'rm -rf "$PLAYWRIGHT_CLI_INSTALL_DIR"'
-        ];
-        this.writeStdout(lines.join('\n'));
-        return 0;
-    }
-
-    printSummary() {
-        const scenes = this.resolveTargets('all');
-        this.writeStdout(`playwright\truntime=${this.config.runtime}\tscenes=${scenes.join(',')}`);
-        return 0;
-    }
-
-    async runOnScene(action, sceneName, options = {}) {
-        const def = SCENE_DEFS[sceneName];
-        if (isDevScene(sceneName)) {
-            if (action === 'up') {
-                return await this.startDevHost(sceneName);
-            }
-            if (action === 'down') {
-                return this.stopDevHost(sceneName);
-            }
-            if (action === 'status') {
-                return this.statusDevHost(sceneName);
-            }
-            if (action === 'health') {
-                return await this.healthScene(sceneName);
-            }
-            if (action === 'logs') {
-                return this.logsHost(sceneName);
-            }
+    async run({ action, mode = '', extensionPaths = [], extensionNames = [], prodversion = '' }) {
+        if (action === 'overview') {
+            this.printOverview();
+            return await this.status();
         }
         if (action === 'up') {
-            return def.type === 'container'
-                ? await this.startContainer(sceneName, options)
-                : await this.startHost(sceneName, options);
+            return await this.up(mode, { extensionPaths, extensionNames });
         }
         if (action === 'down') {
-            return def.type === 'container'
-                ? this.stopContainer(sceneName)
-                : await this.stopHost(sceneName);
+            return await this.down();
         }
         if (action === 'status') {
-            return def.type === 'container'
-                ? this.statusContainer(sceneName)
-                : await this.statusHost(sceneName);
-        }
-        if (action === 'health') {
-            return await this.healthScene(sceneName);
+            return await this.status();
         }
         if (action === 'logs') {
-            return def.type === 'container'
-                ? this.logsContainer(sceneName)
-                : this.logsHost(sceneName);
+            return this.logs();
         }
-        this.writeStderr(`unknown action: ${action}`);
-        return 1;
-    }
-
-    async run({ action, scene = 'mcp-host-headless', host = '', extensionPaths = [], extensionNames = [], prodversion = '' }) {
-        if (action === 'ls') {
-            return this.printSummary();
-        }
-
         if (action === 'mcp-add') {
-            return this.printMcpAdd(host);
+            return this.mcpAdd();
         }
-
-        if (action === 'cli-add') {
-            return this.printCliAdd();
-        }
-
         if (action === 'ext-download') {
-            return await this.downloadExtensions({ prodversion });
-        }
-
-        if (!VALID_ACTIONS.has(action)) {
-            throw new Error(`未知 plugin 动作: ${action}`);
-        }
-
-        const targets = this.resolveTargets(scene);
-        if (targets.length === 0) {
-            this.writeStderr('没有可执行场景，请检查 runtime 与 enabledScenes 配置');
-            return 1;
-        }
-
-        const resolvedExtensionPaths = action === 'up'
-            ? this.resolveExtensionInputs({ extensionPaths, extensionNames })
-            : [];
-
-        let rc = 0;
-        for (const sceneName of targets) {
-            // eslint-disable-next-line no-await-in-loop
-            const code = await this.runOnScene(action, sceneName, { extensionPaths: resolvedExtensionPaths });
-            if (code !== 0) {
-                rc = 1;
-            }
+            return await extensions.downloadExtensions({
+                pluginRoot: this.root,
+                prodversion: prodversion || this.config.extensionProdversion,
+                log: line => this.out(line),
+                logError: line => this.err(line)
+            });
         }
-
-        return rc;
+        throw new Error(`未知 playwright 动作: ${action}`);
     }
 }
 
 module.exports = {
-    EXTENSIONS,
-    SCENE_ORDER,
-    SCENE_DEFS,
-    PlaywrightPlugin
+    MODES,
+    PlaywrightPlugin,
+    appendNoProxy,
+    connectHostFor,
+    defaultListenHost,
+    headedListenHost
 };