@xcanwin/manyoyo 7.1.6 → 8.1.0

package/lib/image-version-policy.js

@@ -0,0 +1,26 @@
+'use strict';
+
+/**
+ * manyoyo update 之后该用哪个镜像版本。
+ * 运行时 `imageVersion` 的优先级是 配置 > 包内默认，所以全局配置里的值会盖过新版本的默认：
+ * - 配置里没写：用新版本的默认；
+ * - 配置里的值等于“旧版本的默认”：那是 build / doctor --fix 自动写进去的，不是用户有意固定，
+ *   随新版本前进（调用方据此更新配置），否则用户会永远停在旧镜像；
+ * - 其它值：用户有意固定，尊重它，只提示。
+ *
+ * @param {{configured?: string, previousDefault?: string, nextDefault?: string}} input
+ * @returns {{imageVersion: string, advance: boolean, pinned: boolean}}
+ */
+function resolveUpdateImageVersion({ configured, previousDefault, nextDefault }) {
+    const current = String(configured || '');
+    const next = String(nextDefault || '');
+    if (!current) {
+        return { imageVersion: next, advance: false, pinned: false };
+    }
+    if (current === String(previousDefault || '') && next && current !== next) {
+        return { imageVersion: next, advance: true, pinned: false };
+    }
+    return { imageVersion: current, advance: false, pinned: Boolean(next) && current !== next };
+}
+
+module.exports = { resolveUpdateImageVersion };

package/lib/init-config.js

@@ -3,6 +3,73 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const { writeConfigFileSecure } = require('./secure-file');
+
+// 每个 Agent 需要哪些环境变量：CLI init 与 Web 首次向导共用的单一数据源。
+// requiredAnyOf：其中任意一个非空即视为该 Agent 可用。
+const AGENT_ENV_SCHEMA = {
+    claude: {
+        label: 'Claude Code',
+        yolo: 'c',
+        modelKey: 'ANTHROPIC_MODEL',
+        requiredAnyOf: ['ANTHROPIC_AUTH_TOKEN', 'CLAUDE_CODE_OAUTH_TOKEN'],
+        baseUrlKey: 'ANTHROPIC_BASE_URL',
+        baseUrlPresets: [{ label: 'Anthropic 官方', value: 'https://api.anthropic.com' }],
+        env: [
+            { name: 'ANTHROPIC_AUTH_TOKEN', description: 'Anthropic API Key 或兼容服务的令牌', secret: true },
+            { name: 'CLAUDE_CODE_OAUTH_TOKEN', description: 'Claude Code OAuth 令牌（订阅登录）', secret: true },
+            { name: 'ANTHROPIC_BASE_URL', description: 'API 地址（使用官方服务可留空）', secret: false },
+            { name: 'ANTHROPIC_MODEL', description: '默认模型', secret: false },
+            { name: 'ANTHROPIC_DEFAULT_OPUS_MODEL', description: 'Opus 档位对应的模型', secret: false },
+            { name: 'ANTHROPIC_DEFAULT_SONNET_MODEL', description: 'Sonnet 档位对应的模型', secret: false },
+            { name: 'ANTHROPIC_DEFAULT_HAIKU_MODEL', description: 'Haiku 档位对应的模型', secret: false },
+            { name: 'CLAUDE_CODE_SUBAGENT_MODEL', description: '子 Agent 使用的模型', secret: false }
+        ]
+    },
+    codex: {
+        label: 'Codex',
+        yolo: 'cx',
+        modelKey: 'OPENAI_MODEL',
+        requiredAnyOf: ['OPENAI_API_KEY'],
+        baseUrlKey: 'OPENAI_BASE_URL',
+        baseUrlPresets: [{ label: 'OpenAI 官方', value: 'https://api.openai.com/v1' }],
+        env: [
+            { name: 'OPENAI_API_KEY', description: 'OpenAI API Key 或兼容服务的令牌', secret: true },
+            { name: 'OPENAI_BASE_URL', description: 'API 地址（使用官方服务可留空）', secret: false },
+            { name: 'OPENAI_MODEL', description: '默认模型', secret: false }
+        ]
+    },
+    gemini: {
+        label: 'Gemini',
+        yolo: 'gm',
+        modelKey: 'GEMINI_MODEL',
+        requiredAnyOf: ['GEMINI_API_KEY'],
+        baseUrlKey: 'GOOGLE_GEMINI_BASE_URL',
+        baseUrlPresets: [{ label: 'Google 官方', value: 'https://generativelanguage.googleapis.com' }],
+        env: [
+            { name: 'GEMINI_API_KEY', description: 'Gemini API Key', secret: true },
+            { name: 'GOOGLE_GEMINI_BASE_URL', description: 'API 地址（使用官方服务可留空）', secret: false },
+            { name: 'GEMINI_MODEL', description: '默认模型', secret: false }
+        ]
+    },
+    opencode: {
+        label: 'OpenCode',
+        yolo: 'oc',
+        modelKey: 'OPENAI_MODEL',
+        requiredAnyOf: ['OPENAI_API_KEY'],
+        baseUrlKey: 'OPENAI_BASE_URL',
+        baseUrlPresets: [{ label: 'OpenAI 官方', value: 'https://api.openai.com/v1' }],
+        env: [
+            { name: 'OPENAI_API_KEY', description: 'OpenAI API Key 或兼容服务的令牌', secret: true },
+            { name: 'OPENAI_BASE_URL', description: 'API 地址（使用官方服务可留空）', secret: false },
+            { name: 'OPENAI_MODEL', description: '默认模型', secret: false }
+        ]
+    }
+};
+
+function agentEnvKeys(agent) {
+    return AGENT_ENV_SCHEMA[agent].env.map(item => item.name);
+}
 
 function readJsonFileSafely(filePath, label, ctx) {
     if (!fs.existsSync(filePath)) return null;
@@ -138,16 +205,7 @@ function normalizeInitConfigAgents(rawAgents, ctx) {
 }
 
 function collectClaudeInitData(homeDir, ctx) {
-    const keys = [
-        'ANTHROPIC_AUTH_TOKEN',
-        'CLAUDE_CODE_OAUTH_TOKEN',
-        'ANTHROPIC_BASE_URL',
-        'ANTHROPIC_MODEL',
-        'ANTHROPIC_DEFAULT_OPUS_MODEL',
-        'ANTHROPIC_DEFAULT_SONNET_MODEL',
-        'ANTHROPIC_DEFAULT_HAIKU_MODEL',
-        'CLAUDE_CODE_SUBAGENT_MODEL'
-    ];
+    const keys = agentEnvKeys('claude');
     const values = {};
     fillValuesFromEnv(keys, values);
 
@@ -160,7 +218,7 @@ function collectClaudeInitData(homeDir, ctx) {
 }
 
 function collectGeminiInitData(homeDir) {
-    const keys = ['GOOGLE_GEMINI_BASE_URL', 'GEMINI_API_KEY', 'GEMINI_MODEL'];
+    const keys = agentEnvKeys('gemini');
     const values = {};
     const notes = [];
     const volumes = [];
@@ -177,7 +235,7 @@ function collectGeminiInitData(homeDir) {
 }
 
 function collectCodexInitData(homeDir, ctx) {
-    const keys = ['OPENAI_API_KEY', 'OPENAI_BASE_URL', 'OPENAI_MODEL'];
+    const keys = agentEnvKeys('codex');
     const values = {};
     const notes = [];
     const volumes = [];
@@ -206,7 +264,7 @@ function collectCodexInitData(homeDir, ctx) {
 }
 
 function collectOpenCodeInitData(homeDir, ctx) {
-    const keys = ['OPENAI_API_KEY', 'OPENAI_BASE_URL', 'OPENAI_MODEL'];
+    const keys = agentEnvKeys('opencode');
     const values = {};
     const notes = [];
     const volumes = [];
@@ -253,19 +311,19 @@ function collectOpenCodeInitData(homeDir, ctx) {
 
 const AGENT_INIT_SPECS = {
     claude: {
-        yolo: 'c',
+        yolo: AGENT_ENV_SCHEMA.claude.yolo,
         collect: (homeDir, ctx) => collectClaudeInitData(homeDir, ctx)
     },
     codex: {
-        yolo: 'cx',
+        yolo: AGENT_ENV_SCHEMA.codex.yolo,
         collect: (homeDir, ctx) => collectCodexInitData(homeDir, ctx)
     },
     gemini: {
-        yolo: 'gm',
+        yolo: AGENT_ENV_SCHEMA.gemini.yolo,
         collect: (homeDir) => collectGeminiInitData(homeDir)
     },
     opencode: {
-        yolo: 'oc',
+        yolo: AGENT_ENV_SCHEMA.opencode.yolo,
         collect: (homeDir, ctx) => collectOpenCodeInitData(homeDir, ctx)
     }
 };
@@ -393,10 +451,12 @@ async function initAgentConfigs(rawAgents, options = {}) {
 
     if (hasConfigChanged || !fs.existsSync(manyoyoConfigPath)) {
         manyoyoConfig.runs = runsMap;
-        fs.writeFileSync(manyoyoConfigPath, `${JSON.stringify(manyoyoConfig, null, 4)}\n`);
+        writeConfigFileSecure(manyoyoConfigPath, `${JSON.stringify(manyoyoConfig, null, 4)}\n`);
     }
 }
 
 module.exports = {
-    initAgentConfigs
+    initAgentConfigs,
+    AGENT_ENV_SCHEMA,
+    agentEnvKeys
 };

package/lib/login-token.js

@@ -0,0 +1,92 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+
+const LOGIN_TOKEN_TTL_MS = 60 * 1000;
+const TOKEN_PATTERN = /^[0-9a-f]{64}$/;
+
+function getLoginTokenDir(homeDir = os.homedir()) {
+    return path.join(homeDir, '.manyoyo', 'serve', 'login-tokens');
+}
+
+function hashToken(token) {
+    return crypto.createHash('sha256').update(token).digest('hex');
+}
+
+function isLoopbackHost(host) {
+    const text = String(host || '').trim().toLowerCase();
+    return text === '127.0.0.1' || text === '::1' || text === '[::1]' || text === 'localhost';
+}
+
+// 删除过期（或无法读取）的令牌文件；目录不存在视为无事可做
+function pruneLoginTokens(dir, options = {}) {
+    const now = options.now || Date.now();
+    const ttlMs = options.ttlMs || LOGIN_TOKEN_TTL_MS;
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    } catch (e) {
+        return;
+    }
+    for (const name of names) {
+        const filePath = path.join(dir, name);
+        try {
+            if (now - fs.lstatSync(filePath).mtimeMs > ttlMs) {
+                fs.unlinkSync(filePath);
+            }
+        } catch (e) {
+            // 被并发消费/清理，忽略
+        }
+    }
+}
+
+/**
+ * 启动器侧：生成一次性令牌，只把 sha256(令牌) 落盘成空文件。
+ * 目录 0700、文件 0600；顺带清理过期文件。
+ */
+function issueLoginToken(dir, options = {}) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    fs.chmodSync(dir, 0o700);
+    pruneLoginTokens(dir, options);
+    const token = crypto.randomBytes(32).toString('hex');
+    fs.writeFileSync(path.join(dir, hashToken(token)), '', { mode: 0o600, flag: 'wx' });
+    return token;
+}
+
+/**
+ * serve 侧：令牌有效则消费（删除文件）并返回 true。
+ * 格式不符、文件不存在、不是普通文件、已过期、被并发消费，都返回 false；过期文件会被顺手删掉。
+ */
+function consumeLoginToken(dir, token, options = {}) {
+    if (!dir || typeof token !== 'string' || !TOKEN_PATTERN.test(token)) {
+        return false;
+    }
+    const now = options.now || Date.now();
+    const ttlMs = options.ttlMs || LOGIN_TOKEN_TTL_MS;
+    const filePath = path.join(dir, hashToken(token));
+    let stat;
+    try {
+        stat = fs.lstatSync(filePath);
+    } catch (e) {
+        return false;
+    }
+    const fresh = stat.isFile() && now - stat.mtimeMs <= ttlMs;
+    try {
+        fs.unlinkSync(filePath);
+    } catch (e) {
+        return false;
+    }
+    return fresh;
+}
+
+module.exports = {
+    LOGIN_TOKEN_TTL_MS,
+    getLoginTokenDir,
+    isLoopbackHost,
+    pruneLoginTokens,
+    issueLoginToken,
+    consumeLoginToken
+};

package/lib/mirrors.js

@@ -0,0 +1,71 @@
+'use strict';
+
+const { normalizeMirrors } = require('./runtime-normalizers');
+
+function hasEnvKey(envArgs, key) {
+    const list = Array.isArray(envArgs) ? envArgs : [];
+    for (let i = 0; i < list.length; i += 1) {
+        if (list[i] !== '--env' && list[i] !== '-e') continue;
+        const text = String(list[i + 1] || '');
+        const idx = text.indexOf('=');
+        if ((idx > 0 ? text.slice(0, idx) : text) === key) return true;
+    }
+    return false;
+}
+
+/**
+ * npm / pip 源通过容器环境变量生效（镜像本身不变）。用户在 env 里自己设了同名变量时以用户为准。
+ * @param {{apt?: string, npm?: string, pip?: string}} mirrors 已归一化的 mirrors
+ * @param {string[]} existingEnvArgs 已有的 --env 参数
+ * @returns {string[]} 追加的 --env 参数
+ */
+function buildMirrorEnvArgs(mirrors, existingEnvArgs = []) {
+    const source = mirrors && typeof mirrors === 'object' ? mirrors : {};
+    const pairs = [];
+    if (source.npm) pairs.push(['NPM_CONFIG_REGISTRY', source.npm]);
+    if (source.pip) {
+        pairs.push(['PIP_INDEX_URL', source.pip]);
+        if (/^http:\/\//i.test(source.pip)) {
+            pairs.push(['PIP_TRUSTED_HOST', new URL(source.pip).hostname]);
+        }
+    }
+    const args = [];
+    for (const [key, value] of pairs) {
+        if (!hasEnvKey(existingEnvArgs, key)) args.push('--env', `${key}=${value}`);
+    }
+    return args;
+}
+
+// 固定脚本：镜像地址只从环境变量读取，不拼接进脚本。
+// 第一次执行时备份原文件（.manyoyo-orig，apt 不读这个后缀），之后每次都从备份还原再替换，所以重复执行、换源都幂等。
+// 只替换主机部分，保留 /ubuntu、/ubuntu-ports 路径（amd64 与 arm64 通用）。
+const APT_MIRROR_SCRIPT = [
+    '[ -n "$MANYOYO_APT_MIRROR" ] || exit 0',
+    'for f in /etc/apt/sources.list.d/ubuntu.sources /etc/apt/sources.list; do',
+    '  [ -f "$f" ] || continue',
+    '  [ -f "$f.manyoyo-orig" ] || cp -p "$f" "$f.manyoyo-orig" || exit 1',
+    '  cp -p "$f.manyoyo-orig" "$f" || exit 1',
+    '  sed -i -E "s|https?://[^/ ]*\\.ubuntu\\.com|${MANYOYO_APT_MIRROR%/}|g" "$f" || exit 1',
+    'done'
+].join('\n');
+
+function buildAptMirrorExecArgs(containerName, aptMirror) {
+    return ['exec', '--user', 'root', '--env', `MANYOYO_APT_MIRROR=${aptMirror}`, containerName, '/bin/sh', '-c', APT_MIRROR_SCRIPT];
+}
+
+/**
+ * 容器创建后让 apt 源生效；失败只警告，不阻断创建。
+ */
+function applyAptMirror({ dockerExecArgs, containerName, mirrors, warn = () => {} }) {
+    const apt = mirrors && typeof mirrors.apt === 'string' ? mirrors.apt : '';
+    if (!apt) return false;
+    try {
+        dockerExecArgs(buildAptMirrorExecArgs(containerName, apt), { stdio: 'pipe' });
+        return true;
+    } catch (error) {
+        warn(`apt 软件源配置失败（不影响使用，容器内仍是默认源）: ${String(error && error.message || error).split('\n')[0]}`);
+        return false;
+    }
+}
+
+module.exports = { normalizeMirrors, buildMirrorEnvArgs, buildAptMirrorExecArgs, applyAptMirror, APT_MIRROR_SCRIPT };

package/lib/offline-import.js

@@ -0,0 +1,60 @@
+'use strict';
+
+// 离线安装器在后台导入镜像时会写 ~/.manyoyo/runtime/import/loading.json（含 pid）。
+// serve / CLI 看到它就等待，不要同时去 ghcr 拉同一个镜像；导入失败或进程消失则视为没有进行中的导入。
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+function getImportMarkerPath(homeDir = os.homedir()) {
+    return path.join(homeDir, '.manyoyo', 'runtime', 'import', 'loading.json');
+}
+
+function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch (error) {
+        return error && error.code === 'EPERM';
+    }
+}
+
+// pid 可能在导入器被强杀后被无关进程复用：必须确认命令行里是后台导入脚本 finish.sh
+function isImportProcess(pid) {
+    try {
+        const command = spawnSync('ps', ['-o', 'command=', '-p', String(pid)], { encoding: 'utf-8' }).stdout || '';
+        return /finish\.sh/.test(command);
+    } catch (error) {
+        return false;
+    }
+}
+
+function readImportState(homeDir = os.homedir(), options = {}) {
+    const isImporter = options.isImporter || isImportProcess;
+    try {
+        const marker = JSON.parse(fs.readFileSync(getImportMarkerPath(homeDir), 'utf-8'));
+        if (Number.isInteger(marker.pid) && marker.pid > 0 && isAlive(marker.pid) && isImporter(marker.pid)) {
+            return { active: true, message: String(marker.message || '正在导入离线镜像') };
+        }
+    } catch (error) {
+        // 没有标记文件就是没有导入
+    }
+    return { active: false, message: '' };
+}
+
+async function waitForImport({ homeDir, readState, sleep = ms => new Promise(resolve => setTimeout(resolve, ms)), onWait = () => {}, timeoutMs = 10 * 60 * 1000, pollMs = 1000 } = {}) {
+    let waited = 0;
+    const read = readState || (() => readImportState(homeDir));
+    let state = read();
+    if (state.active) onWait(state);
+    while (state.active && waited < timeoutMs) {
+        await sleep(pollMs);
+        waited += pollMs;
+        state = read();
+    }
+    return !state.active;
+}
+
+module.exports = { getImportMarkerPath, readImportState, waitForImport, isImportProcess };

package/lib/plugin/playwright.js

@@ -7,6 +7,7 @@ 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'],
@@ -314,6 +315,7 @@ class PlaywrightPlugin {
         this.runConfig = asObject(options.runConfig);
         this.rootGlobalConfig = asObject(options.rootGlobalConfig);
         this.rootRunConfig = asObject(options.rootRunConfig);
+        this.runtimeEnv = {};
         this.config = this.resolveConfig();
     }
 
@@ -398,6 +400,12 @@ class PlaywrightPlugin {
             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)) {
@@ -498,9 +506,10 @@ class PlaywrightPlugin {
     }
 
     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: env || process.env,
+            env: isRuntimeCommand ? { ...(env || process.env), ...this.runtimeEnv } : (env || process.env),
             stdio: captureOutput ? ['ignore', 'pipe', 'pipe'] : 'inherit'
         });
 
@@ -531,6 +540,9 @@ class PlaywrightPlugin {
 
     ensureCommandAvailable(command) {
         const name = String(command || '').trim();
+        if (path.isAbsolute(name)) {
+            return fs.existsSync(name);
+        }
         if (!/^[A-Za-z0-9._-]+$/.test(name)) {
             return false;
         }
@@ -1240,7 +1252,7 @@ class PlaywrightPlugin {
             return { envEntries: [], extraArgs: [], volumeEntries: [] };
         }
 
-        const normalizedDockerCmd = String(dockerCmd || '').trim().toLowerCase();
+        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);
@@ -1268,7 +1280,7 @@ class PlaywrightPlugin {
 
     buildDevHostCliSessionIntegration(dockerCmd, sceneName) {
         const endpoint = this.readDevToolsActivePort();
-        const normalizedDockerCmd = String(dockerCmd || '').trim().toLowerCase();
+        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`;

package/lib/podman-passthrough.js

@@ -0,0 +1,80 @@
+'use strict';
+
+const { spawnSync } = require('child_process');
+const { getPrivatePodmanPaths } = require('./container-runtime');
+
+function shQuote(value) {
+    return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+function privateEnv(paths) {
+    return {
+        XDG_CONFIG_HOME: paths.configHome,
+        XDG_DATA_HOME: paths.dataHome,
+        CONTAINERS_CONF: paths.containersConf
+    };
+}
+
+/**
+ * 输出可以 eval 的 shell 代码：只在当前终端定义一个 podman 函数（带上私有 Podman 的绝对路径与环境变量），
+ * 不改全局 PATH / XDG_*，不影响用户自己的其它工具。
+ */
+function buildShellFunction(paths, shell = 'sh') {
+    const env = privateEnv(paths);
+    if (shell === 'fish') {
+        const assigns = Object.entries(env).map(([key, value]) => `${key}=${shQuote(value)}`).join(' ');
+        return `function podman\n    env ${assigns} ${shQuote(paths.bin)} $argv\nend\n`;
+    }
+    const assigns = Object.entries(env).map(([key, value]) => `${key}=${shQuote(value)}`).join(' ');
+    return `podman() { env ${assigns} ${shQuote(paths.bin)} "$@"; }\n`;
+}
+
+function usageText(commandName) {
+    return [
+        `用法:`,
+        `  ${commandName} podman <podman 参数...>     用 ${commandName} 的私有 Podman 执行一次，参数原样传给 podman`,
+        `  eval "$(${commandName} podman env)"        在当前终端定义 podman 函数，之后直接输入 podman ps -a`,
+        `  ${commandName} podman env --shell fish     fish 终端使用这个形式`,
+        `说明: 函数只在当前终端有效，关闭终端即失效；不修改 PATH，也不影响你自己安装的 Podman。`
+    ].join('\n');
+}
+
+/**
+ * @returns {number} 退出码
+ */
+function runPodmanCommand(args, options = {}) {
+    const log = options.log || (line => console.log(line));
+    const errLog = options.errLog || (line => console.error(line));
+    const commandName = options.commandName || 'manyoyo';
+    const paths = getPrivatePodmanPaths(options.homeDir);
+    const exists = options.exists || (file => require('fs').existsSync(file));
+    if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+        log(usageText(commandName));
+        return 0;
+    }
+    if (!exists(paths.bin)) {
+        errLog(`没有找到 ${commandName} 的私有 Podman（${paths.bin}）。当前没有使用私有 Podman：离线完整包安装后才有；使用你自己的 docker / podman 时直接用它们即可。`);
+        return 1;
+    }
+    if (args[0] === 'env') {
+        const rest = args.slice(1);
+        let shell = '';
+        for (let i = 0; i < rest.length; i += 1) {
+            if (rest[i] === '--shell') { shell = rest[i + 1] || ''; i += 1; }
+            else { errLog(`未知参数: ${rest[i]}`); return 2; }
+        }
+        if (!shell) shell = require('path').basename(String(options.shell || process.env.SHELL || 'sh'));
+        log(buildShellFunction(paths, shell === 'fish' ? 'fish' : 'sh').trimEnd());
+        return 0;
+    }
+    const run = options.spawnSync || spawnSync;
+    const result = run(paths.bin, args, { stdio: 'inherit', env: { ...process.env, ...privateEnv(paths) } });
+    if (result.error) {
+        errLog(`无法执行私有 Podman: ${result.error.message}`);
+        return 1;
+    }
+    if (result.signal) return 1;
+    return result.status === null || result.status === undefined ? 1 : result.status;
+}
+
+module.exports = { runPodmanCommand, buildShellFunction, usageText };