@xcanwin/manyoyo 7.1.5 → 8.0.1

package/lib/proxy-config.js

@@ -0,0 +1,138 @@
+'use strict';
+
+// 私有 Podman 设了 CONTAINERS_CONF，不会再读用户自己的 ~/.config/containers/containers.conf，
+// 所以安装时把其中“有用的”代理设置抄过来：只抄代理相关项，其它（仓库、存储路径等）一概不碰。
+// 用法（安装器调用）：node proxy-config.js --write-conf <私有podman目录> <用户HOME>
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const PROXY_NAMES = ['http_proxy', 'https_proxy', 'no_proxy', 'all_proxy'];
+
+function isSafeValue(value) {
+    // 会写进 TOML 字符串，也可能进命令环境：拒绝换行、引号、反斜杠与控制字符
+    return typeof value === 'string' && value.length > 0 && value.length < 2048 && !/[\r\n\0"'\\`$]/.test(value);
+}
+
+function sectionBody(text, name) {
+    const lines = text.split('\n');
+    let current = '';
+    const body = [];
+    for (const line of lines) {
+        const header = line.match(/^\s*\[([^\]]+)\]\s*$/);
+        if (header) { current = header[1].trim(); continue; }
+        if (current === name) body.push(line);
+    }
+    return body.join('\n');
+}
+
+/**
+ * 从用户的 containers.conf 文本里取出代理环境变量（[engine] env = [...]，可多行）与 [containers] http_proxy 开关。
+ * @returns {{env: Object<string,string>, passToContainers: boolean|null}}
+ */
+function parseUserContainersConf(text) {
+    const result = { env: {}, passToContainers: null, dropped: [] };
+    const engine = sectionBody(String(text || ''), 'engine');
+    // 数组里的字符串可能含 ]（如 IPv6 代理 http://[::1]:7890），所以按“引号串 或 非 ] 字符”匹配
+    const envMatch = engine.match(/^\s*env\s*=\s*\[((?:"(?:[^"\\\n]|\\.)*"|[^\]"])*)\]/m);
+    if (envMatch) {
+        for (const entry of envMatch[1].matchAll(/"((?:[^"\\\n]|\\.)*)"/g)) {
+            const index = entry[1].indexOf('=');
+            if (index <= 0) continue;
+            const name = entry[1].slice(0, index).trim().toLowerCase();
+            const value = entry[1].slice(index + 1).trim();
+            if (!PROXY_NAMES.includes(name)) continue;
+            if (isSafeValue(value)) result.env[name] = value;
+            else if (value) result.dropped.push(name);
+        }
+    }
+    const containers = sectionBody(String(text || ''), 'containers');
+    const flag = containers.match(/^\s*http_proxy\s*=\s*(true|false)\s*$/m);
+    if (flag) result.passToContainers = flag[1] === 'true';
+    return result;
+}
+
+function proxyFromEnvironment(env, dropped = []) {
+    const found = {};
+    for (const name of PROXY_NAMES) {
+        const value = env[name] || env[name.toUpperCase()];
+        if (isSafeValue(value)) found[name] = value;
+        else if (value) dropped.push(name);
+    }
+    return found;
+}
+
+/**
+ * 汇总代理：用户的 containers.conf 优先（那是对 Podman 实际生效的配置），环境变量补缺。
+ */
+function collectProxySettings({ homeDir = os.homedir(), env = process.env, readFile = file => fs.readFileSync(file, 'utf8') } = {}) {
+    let fromFile = { env: {}, passToContainers: null };
+    const userConf = path.join(homeDir, '.config', 'containers', 'containers.conf');
+    try {
+        fromFile = parseUserContainersConf(readFile(userConf));
+    } catch (error) {
+        // 没有用户配置很正常
+    }
+    const dropped = [];
+    const fromEnv = proxyFromEnvironment(env, dropped);
+    const merged = { ...fromEnv, ...fromFile.env };
+    // 被丢弃的项只有在最终没有可用值时才算“丢了”（只报名字，不打印值：可能带密码）
+    return {
+        env: merged,
+        passToContainers: fromFile.passToContainers,
+        dropped: [...new Set([...dropped, ...(fromFile.dropped || [])])].filter(name => !(name in merged))
+    };
+}
+
+function renderContainersConf({ podmanRoot, proxy }) {
+    const lines = ['[engine]', `helper_binaries_dir = [${JSON.stringify(path.join(podmanRoot, 'bin'))}]`];
+    const entries = Object.entries(proxy.env).map(([name, value]) => JSON.stringify(`${name}=${value}`));
+    if (entries.length > 0) lines.push(`env = [${entries.join(', ')}]`);
+    if (proxy.passToContainers !== null) lines.push('', '[containers]', `http_proxy = ${proxy.passToContainers}`);
+    return `${lines.join('\n')}\n`;
+}
+
+/**
+ * 写 <podmanRoot>/containers.conf。每次安装都重新生成（代理会变），
+ * 但只覆盖带本工具标记的文件，用户手改过的不动。
+ */
+function writePrivateContainersConf({ podmanRoot, homeDir, env = process.env }) {
+    const target = path.join(podmanRoot, 'containers.conf');
+    const marker = '# generated by manyoyo installer';
+    if (fs.existsSync(target) && !fs.readFileSync(target, 'utf8').startsWith(marker)) {
+        const legacy = fs.readFileSync(target, 'utf8');
+        // lib/container-runtime.js 首次选择时写的最小配置（只有 helper_binaries_dir）可以安全升级
+        if (/^\[engine\]\nhelper_binaries_dir = \[[^\n]*\]\n$/.test(legacy) === false) {
+            return { path: target, written: false, reason: 'user-modified' };
+        }
+    }
+    const proxy = collectProxySettings({ homeDir, env });
+    fs.mkdirSync(podmanRoot, { recursive: true });
+    // 代理 URL 里可能带账号密码，和用户自己的 containers.conf 一样只给本人读写
+    fs.writeFileSync(target, `${marker}\n${renderContainersConf({ podmanRoot, proxy })}`, { mode: 0o600 });
+    fs.chmodSync(target, 0o600);
+    return { path: target, written: true, proxyNames: Object.keys(proxy.env), passToContainers: proxy.passToContainers, droppedNames: proxy.dropped };
+}
+
+module.exports = {
+    parseUserContainersConf,
+    collectProxySettings,
+    renderContainersConf,
+    writePrivateContainersConf
+};
+
+if (require.main === module) {
+    const [flag, podmanRoot, homeDir] = process.argv.slice(2);
+    if (flag !== '--write-conf' || !podmanRoot) {
+        console.error('用法: node proxy-config.js --write-conf <私有podman目录> [用户HOME]');
+        process.exit(2);
+    }
+    const result = writePrivateContainersConf({ podmanRoot, homeDir: homeDir || os.homedir() });
+    console.log(result.written
+        ? `已生成 ${result.path}（代理项: ${result.proxyNames.join(', ') || '无'}）`
+        : `保留用户修改过的 ${result.path}`);
+    if (result.droppedNames && result.droppedNames.length > 0) {
+        console.log(`注意：以下代理项含引号、反斜杠、$ 或反引号等不安全字符，没有抄进私有 Podman 配置: ${result.droppedNames.join(', ')}（需要的话请手动编辑 ${result.path}）`);
+    }
+}

package/lib/runtime-heal.js

@@ -0,0 +1,175 @@
+'use strict';
+
+const path = require('path');
+const { spawn } = require('child_process');
+
+// 离线安装器给私有 Podman 建的 machine 名字；列表里有它就优先启动它
+const PRIVATE_MACHINE_NAME = 'podman-machine-manyoyo';
+// 冷启动或磁盘忙时 info 可能超过 3 秒但 daemon 是好的
+const PROBE_TIMEOUT_MS = 10000;
+const DEFAULT_READY_TIMEOUT_MS = 120000;
+const DEFAULT_POLL_MS = 2000;
+
+function defaultSleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * 运行时 daemon 不可用时尝试自愈：
+ * - Podman：machine 已存在但未运行 → podman machine start
+ * - macOS 上的 Docker：open -a Docker 并等待就绪
+ * 其余情况只报告，不猜。
+ *
+ * @param {Object} options
+ * @param {{command: string, env?: Object}} options.runtime selectContainerRuntime 的结果
+ * @param {(command: string, args: string[], opts: {env?: Object, timeout?: number}) => string|Promise<string>} options.run 执行器（同步或异步均可），失败抛错；serve 里必须传异步实现，避免阻塞事件循环
+ * @param {(state: {status: string, message: string}) => void} [options.onStatus]
+ * @returns {Promise<{status: 'ready'|'started'|'unavailable'|'failed'|'timeout', message: string}>}
+ */
+async function ensureRuntimeReady(options) {
+    const { runtime, run } = options;
+    const platform = options.platform || process.platform;
+    const sleep = options.sleep || defaultSleep;
+    const now = options.now || Date.now;
+    const onStatus = options.onStatus || (() => {});
+    const timeoutMs = options.timeoutMs || DEFAULT_READY_TIMEOUT_MS;
+    const pollMs = options.pollMs || DEFAULT_POLL_MS;
+    const env = runtime.env || {};
+    const kind = path.basename(runtime.command);
+
+    let lastProbeTimedOut = false;
+    const isReady = async () => {
+        try {
+            await run(runtime.command, ['info'], { env, timeout: PROBE_TIMEOUT_MS });
+            lastProbeTimedOut = false;
+            return true;
+        } catch (e) {
+            lastProbeTimedOut = Boolean(e && (e.code === 'ETIMEDOUT' || e.timedOut || e.killed));
+            return false;
+        }
+    };
+
+    if (await isReady()) {
+        return { status: 'ready', message: '' };
+    }
+
+    let startMessage;
+    if (kind === 'podman') {
+        let machines = [];
+        try {
+            machines = JSON.parse(await run(runtime.command, ['machine', 'list', '--format', 'json'], { env, timeout: 10000 }));
+        } catch (e) {
+            machines = [];
+        }
+        if (!Array.isArray(machines) || machines.length === 0) {
+            return { status: 'unavailable', message: '未找到 Podman machine，请先执行: podman machine init' };
+        }
+        const starting = machines.some(machine => machine && machine.Starting);
+        if (!starting && machines.some(machine => machine && machine.Running)) {
+            return {
+                status: 'unavailable',
+                message: lastProbeTimedOut
+                    ? 'Podman machine 已在运行但响应超时，请稍后重试；持续超时再执行: podman machine stop && podman machine start'
+                    : 'Podman machine 已在运行但连接不可用，请执行: podman machine stop && podman machine start'
+            };
+        }
+        const clean = machine => String(machine && machine.Name || '').replace(/\*$/, '');
+        const target = machines.find(machine => clean(machine) === PRIVATE_MACHINE_NAME)
+            || machines.find(machine => machine && machine.Default) || machines[0];
+        const name = String(target.Name || '').replace(/\*$/, '');
+        startMessage = '正在启动容器环境 (podman machine start)';
+        onStatus({ status: 'starting', message: startMessage });
+        // 别处（另一个 CLI/serve）已经在启动同一台 machine：不再重复 start，直接轮询等待
+        if (!starting) {
+            try {
+                await run(runtime.command, name ? ['machine', 'start', name] : ['machine', 'start'], { env, timeout: timeoutMs });
+            } catch (e) {
+                // 并发启动时 start 会报 already starting/running 之类：先重探一次再判失败
+                if (await isReady()) {
+                    onStatus({ status: 'ready', message: '' });
+                    return { status: 'started', message: startMessage };
+                }
+                const message = `podman machine start 失败: ${String(e && e.message || e).split('\n')[0]}`;
+                onStatus({ status: 'failed', message });
+                return { status: 'failed', message };
+            }
+        }
+    } else if (kind === 'docker' && platform === 'darwin') {
+        startMessage = '正在启动容器环境 (Docker Desktop)';
+        onStatus({ status: 'starting', message: startMessage });
+        try {
+            await run('open', ['-a', 'Docker'], { timeout: 10000 });
+        } catch (e) {
+            const message = '无法启动 Docker Desktop，请手动打开后重试';
+            onStatus({ status: 'failed', message });
+            return { status: 'failed', message };
+        }
+    } else {
+        return { status: 'unavailable', message: `${kind} daemon 不可用，请先启动后重试` };
+    }
+
+    const deadline = now() + timeoutMs;
+    while (now() < deadline) {
+        if (await isReady()) {
+            onStatus({ status: 'ready', message: '' });
+            return { status: 'started', message: startMessage };
+        }
+        await sleep(pollMs);
+    }
+    const message = `等待容器环境就绪超时（${Math.round(timeoutMs / 1000)} 秒），请确认 ${kind === 'podman' ? 'Podman machine' : 'Docker Desktop'} 已启动后重试`;
+    onStatus({ status: 'failed', message });
+    return { status: 'timeout', message };
+}
+
+/**
+ * 异步执行命令（不阻塞事件循环）。语义与同步执行器一致：非 0 退出或超时都抛错，
+ * 超时的错误带 code=ETIMEDOUT。serve 里的自愈必须用它，不能用 spawnSync。
+ * @returns {Promise<string>} stdout
+ */
+function runCommandAsync(command, args, options = {}) {
+    return new Promise((resolve, reject) => {
+        let child;
+        try {
+            child = spawn(command, args, { env: options.env, stdio: ['ignore', 'pipe', 'pipe'] });
+        } catch (e) {
+            reject(e);
+            return;
+        }
+        let stdout = '';
+        let stderr = '';
+        let timedOut = false;
+        const timer = options.timeout ? setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGKILL');
+        }, options.timeout) : null;
+        child.stdout.on('data', chunk => { stdout += chunk; });
+        child.stderr.on('data', chunk => { stderr += chunk; });
+        child.on('error', error => {
+            if (timer) clearTimeout(timer);
+            reject(error);
+        });
+        child.on('close', code => {
+            if (timer) clearTimeout(timer);
+            if (timedOut) {
+                const error = new Error(`Command timed out: ${command} ${args.join(' ')}`);
+                error.code = 'ETIMEDOUT';
+                error.stdout = stdout;
+                error.stderr = stderr;
+                reject(error);
+            } else if (code !== 0) {
+                const error = new Error(`Command failed: ${command} ${args.join(' ')}`);
+                error.status = code;
+                error.stdout = stdout;
+                error.stderr = stderr;
+                reject(error);
+            } else {
+                resolve(stdout);
+            }
+        });
+    });
+}
+
+module.exports = {
+    ensureRuntimeReady,
+    runCommandAsync
+};

package/lib/runtime-normalizers.js

@@ -58,7 +58,57 @@ function normalizeVolume(volume, homeDir = os.homedir()) {
     return `${expandHomeAliasPath(hostPath, homeDir)}${rest}`;
 }
 
+const MIRROR_KEYS = ['apt', 'npm', 'pip'];
+const MIRROR_URL_MAX_LENGTH = 256;
+
+/**
+ * 归一化全局配置 mirrors：{ apt, npm, pip }，空/缺省 = 官方默认（返回空字符串）。
+ * 只接受 http/https URL；这些值会进入容器环境变量或 apt 配置，所以严格拒绝空白和 shell 元字符。
+ */
+function normalizeMirrors(value) {
+    const result = { apt: '', npm: '', pip: '' };
+    if (value === undefined || value === null) {
+        return result;
+    }
+    if (typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('mirrors 必须是对象，例如 { "npm": "https://registry.npmmirror.com/" }');
+    }
+    for (const key of Object.keys(value)) {
+        if (!MIRROR_KEYS.includes(key)) {
+            throw new Error(`mirrors 不支持的键: ${key}（只支持 ${MIRROR_KEYS.join(' / ')}）`);
+        }
+        const raw = value[key];
+        if (raw === undefined || raw === null) {
+            continue;
+        }
+        if (typeof raw !== 'string') {
+            throw new Error(`mirrors.${key} 必须是字符串`);
+        }
+        const text = raw.trim();
+        if (!text) {
+            continue;
+        }
+        if (!/^https?:\/\//i.test(text)) {
+            throw new Error(`mirrors.${key} 必须以 http:// 或 https:// 开头: ${text.slice(0, 40)}`);
+        }
+        if (text.length > MIRROR_URL_MAX_LENGTH) {
+            throw new Error(`mirrors.${key} 过长（最多 ${MIRROR_URL_MAX_LENGTH} 个字符）`);
+        }
+        if (/[\s\0;&|`$<>'"\\]/.test(text)) {
+            throw new Error(`mirrors.${key} 含非法字符（不允许空白、引号、反斜杠和 ; & | \` $ < >）`);
+        }
+        try {
+            new URL(text);
+        } catch (e) {
+            throw new Error(`mirrors.${key} 不是有效的 URL`);
+        }
+        result[key] = text;
+    }
+    return result;
+}
+
 module.exports = {
+    normalizeMirrors,
     parseEnvEntry,
     expandHomeAliasPath,
     normalizeVolume

package/lib/secure-file.js

@@ -0,0 +1,38 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+/**
+ * 写含凭据的配置文件：文件 0600、目录 0700，临时文件 + rename 原子替换（崩溃不会留下被截断的配置）。
+ * 目录只在“新建”或名为 .manyoyo 时收紧，不去改动用户指定的其它已有目录的权限。
+ * @param {string} filePath
+ * @param {string} data
+ */
+function writeConfigFileSecure(filePath, data) {
+    if (typeof data !== 'string') {
+        throw new TypeError('配置内容必须是字符串');
+    }
+    const dir = path.dirname(filePath);
+    const existed = fs.existsSync(dir);
+    if (!existed) {
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    if (!existed || path.basename(dir) === '.manyoyo') {
+        try { fs.chmodSync(dir, 0o700); } catch (e) { /* 非属主等情况忽略 */ }
+    }
+    let target = filePath;
+    try { target = fs.realpathSync(filePath); } catch (e) { /* 新文件 */ }
+    const tmp = `${target}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
+    try {
+        fs.writeFileSync(tmp, data, { mode: 0o600, flag: 'wx' });
+        fs.chmodSync(tmp, 0o600);
+        fs.renameSync(tmp, target);
+    } catch (error) {
+        try { fs.rmSync(tmp, { force: true }); } catch (e) { /* 尽力清理 */ }
+        throw error;
+    }
+}
+
+module.exports = { writeConfigFileSecure };

package/lib/setup-cli.js

@@ -0,0 +1,215 @@
+'use strict';
+
+// `manyoyo setup`：无头环境（SSH、没有图形界面）的命令行配置向导，等价于网页向导的几个步骤。
+// 配置文本的构造复用 lib/setup-config.js 与 lib/setup.js（和 /api/setup/* 同源），写入走 secure-file（0600、原子）。
+// 所有 IO 都从 deps 注入，便于测试；密钥与密码不回显、不写日志、不打印。
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+const { Writable } = require('stream');
+const JSON5 = require('json5');
+const { listSetupAgents, buildAgentRunProfile, validateSetupPassword, listMirrorPresets } = require('./setup');
+const { baseRawOf, buildAgentConfigRaw, buildPasswordConfigRaw, shouldWriteMirrors, buildMirrorsConfigRaw } = require('./setup-config');
+const { normalizeMirrors } = require('./runtime-normalizers');
+const { writeConfigFileSecure } = require('./secure-file');
+const { getManyoyoConfigPath } = require('./global-config');
+
+class InputClosedError extends Error {}
+
+/**
+ * 读 stdin 的提示器。askSecret 输入不回显：提示文字直接写到真实 output，
+ * 回显通道（readline 的 output）在读密码期间静音。
+ */
+function createPrompter({ input = process.stdin, output = process.stdout, terminal = Boolean(input.isTTY) } = {}) {
+    let muted = false;
+    const echo = new Writable({
+        write(chunk, encoding, callback) {
+            if (!muted) output.write(chunk, encoding);
+            callback();
+        }
+    });
+    const rl = readline.createInterface({ input, output: echo, terminal });
+    let closed = false;
+    let rejectPending = null;
+    rl.on('close', () => {
+        closed = true;
+        if (rejectPending) rejectPending(new InputClosedError('输入已结束'));
+    });
+    const question = prompt => new Promise((resolve, reject) => {
+        if (closed) {
+            reject(new InputClosedError('输入已结束'));
+            return;
+        }
+        rejectPending = reject;
+        rl.question(prompt, answer => {
+            rejectPending = null;
+            resolve(answer);
+        });
+    });
+    return {
+        ask: text => question(text),
+        async askSecret(text) {
+            output.write(text);
+            muted = true;
+            try {
+                return await question('');
+            } finally {
+                muted = false;
+                output.write('\n');
+            }
+        },
+        close: () => rl.close()
+    };
+}
+
+async function chooseNumber(prompter, log, title, items, { defaultIndex = 0, allowSkip = false } = {}) {
+    log(title);
+    items.forEach((item, index) => log(`  ${index + 1}) ${item}`));
+    if (allowSkip) log('  0) 跳过 / 官方默认');
+    for (;;) {
+        const answer = String(await prompter.ask(`请选择${allowSkip ? '' : ` [${defaultIndex + 1}]`}: `)).trim();
+        if (answer === '' && !allowSkip) return defaultIndex;
+        if (allowSkip && (answer === '' || answer === '0')) return -1;
+        const index = Number(answer) - 1;
+        if (Number.isInteger(index) && index >= 0 && index < items.length) return index;
+        log('请输入列表里的编号。');
+    }
+}
+
+async function askMirrors(prompter, log) {
+    const presets = listMirrorPresets();
+    const toolNames = { apt: 'apt（Ubuntu 软件包）', npm: 'npm', pip: 'pip（Python）' };
+    const mirrors = {};
+    for (const tool of ['apt', 'npm', 'pip']) {
+        const items = [...presets[tool].map(item => `${item.label}  ${item.value}`), '自定义地址'];
+        const choice = await chooseNumber(prompter, log, `${toolNames[tool]} 软件源：`, items, { allowSkip: true });
+        if (choice === -1) continue;
+        if (choice < presets[tool].length) {
+            mirrors[tool] = presets[tool][choice].value;
+            continue;
+        }
+        for (;;) {
+            const value = String(await prompter.ask('请输入 http(s) 地址（留空取消）: ')).trim();
+            if (!value) break;
+            try {
+                mirrors[tool] = normalizeMirrors({ [tool]: value })[tool];
+                break;
+            } catch (error) {
+                log(error.message);
+            }
+        }
+    }
+    return mirrors;
+}
+
+async function askPassword(prompter, log) {
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        const first = await prompter.askSecret('设置登录密码（至少 8 位，输入不回显）: ');
+        const reason = validateSetupPassword(first);
+        if (reason) {
+            log(reason);
+            continue;
+        }
+        const second = await prompter.askSecret('再输入一次: ');
+        if (first !== second) {
+            log('两次输入不一致，请重新设置。');
+            continue;
+        }
+        return first;
+    }
+    throw new Error('登录密码设置失败次数过多，已退出。');
+}
+
+/**
+ * @returns {Promise<number>} 退出码
+ */
+async function runSetupCli(deps) {
+    const log = deps.log || (line => console.log(line));
+    const commandName = deps.commandName || 'manyoyo';
+    if (!deps.isTTY) {
+        log(`${commandName} setup 需要在交互式终端里运行（当前输入不是终端）。`);
+        log('可选做法：');
+        log('  1. 在能交互的终端（例如 ssh 登录后的 shell）里重新运行 setup；');
+        log(`  2. 在有图形界面的环境里运行 ${commandName}，用网页向导完成配置；`);
+        log(`  3. 直接编辑 ${deps.configPath}（可先用 ${commandName} init 生成默认配置）。`);
+        return 1;
+    }
+    const prompter = deps.prompter;
+    try {
+        const agents = listSetupAgents();
+        const agentIndex = await chooseNumber(prompter, log, '选择要配置的 Agent：', agents.map(item => `${item.label}（${item.id}）`));
+        const agent = agents[agentIndex];
+
+        const env = {};
+        let keyName = agent.requiredAnyOf[0];
+        if (agent.requiredAnyOf.length > 1) {
+            const keyIndex = await chooseNumber(prompter, log, '使用哪种凭据：', agent.requiredAnyOf.map(name => {
+                const entry = agent.env.find(item => item.name === name);
+                return `${name}  ${entry ? entry.description : ''}`;
+            }));
+            keyName = agent.requiredAnyOf[keyIndex];
+        }
+        const key = String(await prompter.askSecret(`${keyName}（输入不回显）: `)).trim();
+        if (!key) {
+            log('凭据不能为空，已退出，没有改动任何配置。');
+            return 1;
+        }
+        env[keyName] = key;
+
+        const baseUrlItems = [...agent.baseUrlPresets.map(item => `${item.label}  ${item.value}`), '自定义地址'];
+        const baseIndex = await chooseNumber(prompter, log, 'API 地址：', baseUrlItems, { allowSkip: true });
+        if (baseIndex >= 0 && baseIndex < agent.baseUrlPresets.length) {
+            env[agent.baseUrlKey] = agent.baseUrlPresets[baseIndex].value;
+        } else if (baseIndex === agent.baseUrlPresets.length) {
+            const custom = String(await prompter.ask('请输入 API 地址: ')).trim();
+            if (custom) env[agent.baseUrlKey] = custom;
+        }
+        const model = String(await prompter.ask(`默认模型 ${agent.modelKey}（可留空）: `)).trim();
+        if (model) env[agent.modelKey] = model;
+
+        const defaultWork = deps.defaultWorkpath;
+        let hostPath = String(await prompter.ask(`工作目录（Agent 只能看到这里）[${defaultWork}]: `)).trim() || defaultWork;
+        if (!path.isAbsolute(hostPath)) {
+            log('工作目录必须是绝对路径，已退出，没有改动任何配置。');
+            return 1;
+        }
+        hostPath = path.resolve(hostPath);
+        fs.mkdirSync(hostPath, { recursive: true });
+        deps.validateHostPath(hostPath);
+
+        const password = await askPassword(prompter, log);
+
+        let mirrors = {};
+        if (/^y(es)?$/i.test(String(await prompter.ask('配置 apt / npm / pip 软件源吗？默认官方源 [y/N]: ')).trim())) {
+            mirrors = await askMirrors(prompter, log);
+        }
+
+        // 一次性构造并校验新配置，通过后原子写入；任何一步出错都不会留下半份配置
+        const configPath = deps.configPath;
+        const exists = fs.existsSync(configPath);
+        const snapshot = { exists, raw: exists ? fs.readFileSync(configPath, 'utf-8') : '' };
+        const parsed = exists && snapshot.raw.trim() ? JSON5.parse(snapshot.raw) : {};
+        const existingRun = parsed.runs && typeof parsed.runs === 'object' ? parsed.runs[agent.id] : undefined;
+        const profile = buildAgentRunProfile(agent.id, env, { existingRun, hostPath });
+        let nextRaw = buildAgentConfigRaw(baseRawOf(snapshot), agent.id, profile);
+        nextRaw = buildPasswordConfigRaw(nextRaw, password);
+        if (shouldWriteMirrors(parsed, mirrors)) nextRaw = buildMirrorsConfigRaw(nextRaw, normalizeMirrors(mirrors));
+        JSON5.parse(nextRaw);
+        writeConfigFileSecure(configPath, nextRaw);
+        log(`已保存到 ${configPath}（权限 0600）：Agent ${agent.id}、工作目录 ${hostPath}、登录密码${Object.keys(mirrors).length > 0 ? '、软件源' : ''}。`);
+    } catch (error) {
+        if (error instanceof InputClosedError) {
+            log('输入已结束，没有改动任何配置。');
+            return 1;
+        }
+        log(`配置失败：${error.message}`);
+        return 1;
+    } finally {
+        prompter.close();
+    }
+    if (deps.afterSave) await deps.afterSave();
+    return 0;
+}
+
+module.exports = { runSetupCli, createPrompter, getManyoyoConfigPath };

package/lib/setup-config.js

@@ -0,0 +1,32 @@
+'use strict';
+
+// 向导写配置的“构造新文本”部分：Web 接口（/api/setup/*）与命令行 `manyoyo setup` 共用，保证两边写出同样的配置。
+// 只负责在原文上做局部替换（保留注释与其它字段），读写文件与校验由调用方负责。
+
+const { upsertValueByPath } = require('./json5-text-edit');
+
+const EMPTY_CONFIG_RAW = '{\n}\n';
+
+function baseRawOf(snapshot) {
+    return snapshot && snapshot.exists && String(snapshot.raw || '').trim() ? snapshot.raw : EMPTY_CONFIG_RAW;
+}
+
+function buildAgentConfigRaw(baseRaw, agent, profile) {
+    return upsertValueByPath(baseRaw, ['runs', agent], JSON.stringify(profile, null, 4));
+}
+
+function buildPasswordConfigRaw(baseRaw, password) {
+    return upsertValueByPath(baseRaw, ['serverPass'], JSON.stringify(password));
+}
+
+// 全部为官方默认且配置里本来没有 mirrors 时不需要写任何东西
+function shouldWriteMirrors(parsedConfig, mirrors) {
+    const hasExisting = Object.prototype.hasOwnProperty.call(parsedConfig || {}, 'mirrors');
+    return hasExisting || Boolean(mirrors.apt || mirrors.npm || mirrors.pip);
+}
+
+function buildMirrorsConfigRaw(baseRaw, mirrors) {
+    return upsertValueByPath(baseRaw, ['mirrors'], JSON.stringify(mirrors, null, 4));
+}
+
+module.exports = { EMPTY_CONFIG_RAW, baseRawOf, buildAgentConfigRaw, buildPasswordConfigRaw, shouldWriteMirrors, buildMirrorsConfigRaw };