@xcanwin/manyoyo 7.1.6 → 8.0.1

package/lib/setup.js

@@ -0,0 +1,188 @@
+'use strict';
+
+const { AGENT_ENV_SCHEMA } = require('./init-config');
+const { parseEnvEntry } = require('./runtime-normalizers');
+
+const SETUP_AGENTS = Object.keys(AGENT_ENV_SCHEMA);
+
+function isPlainObject(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function listSetupAgents() {
+    return SETUP_AGENTS.map(id => {
+        const spec = AGENT_ENV_SCHEMA[id];
+        return {
+            id,
+            label: spec.label,
+            yolo: spec.yolo,
+            modelKey: spec.modelKey,
+            requiredAnyOf: [...spec.requiredAnyOf],
+            baseUrlKey: spec.baseUrlKey,
+            baseUrlPresets: spec.baseUrlPresets.map(item => ({ ...item })),
+            env: spec.env.map(item => ({ ...item }))
+        };
+    });
+}
+
+function hasNonEmptyRequiredKey(spec, env) {
+    const source = isPlainObject(env) ? env : {};
+    return spec.requiredAnyOf.some(key => typeof source[key] === 'string' && source[key].trim() !== '');
+}
+
+// 已有可用 runs.<agent>：run 存在，且必填变量（任意一个）非空
+function getConfiguredAgents(config) {
+    const runs = isPlainObject(config && config.runs) ? config.runs : {};
+    return SETUP_AGENTS.filter(id => isPlainObject(runs[id]) && hasNonEmptyRequiredKey(AGENT_ENV_SCHEMA[id], runs[id].env));
+}
+
+/**
+ * 校验请求里的 env 并合并到已有 run 上，返回要写入的 runs.<agent> 对象。
+ * - agent 必须在 schema 内，env key 必须属于该 agent，值按 parseEnvEntry 校验；
+ * - 空字符串表示“不改动/不设置”，已有 run 的其它字段（volumes、ports…）原样保留。
+ */
+function buildAgentRunProfile(agent, envInput, options = {}) {
+    const spec = AGENT_ENV_SCHEMA[agent];
+    if (!spec) {
+        throw new Error(`不支持的 Agent: ${agent}`);
+    }
+    if (!isPlainObject(envInput)) {
+        throw new Error('env 必须是对象(map)');
+    }
+    const allowed = new Set(spec.env.map(item => item.name));
+    const provided = {};
+    for (const [key, rawValue] of Object.entries(envInput)) {
+        if (!allowed.has(key)) {
+            throw new Error(`${agent} 不支持的变量: ${key}`);
+        }
+        if (typeof rawValue !== 'string') {
+            throw new Error(`env 值必须是字符串: ${key}`);
+        }
+        const value = rawValue.trim();
+        if (!value) continue;
+        parseEnvEntry(`${key}=${value}`);
+        provided[key] = value;
+    }
+
+    const existing = isPlainObject(options.existingRun) ? options.existingRun : {};
+    const existingEnv = isPlainObject(existing.env) ? existing.env : {};
+    const profile = { ...existing };
+    profile.env = { ...existingEnv, ...provided };
+    if (!hasNonEmptyRequiredKey(spec, profile.env)) {
+        throw new Error(`请填写 ${spec.requiredAnyOf.join(' 或 ')}`);
+    }
+    if (profile.containerName === undefined) profile.containerName = `my-${agent}-{now}`;
+    if (profile.yolo === undefined) profile.yolo = spec.yolo;
+    if (options.hostPath) profile.hostPath = options.hostPath;
+    else if (profile.hostPath === undefined && options.defaultHostPath) profile.hostPath = options.defaultHostPath;
+    return profile;
+}
+
+const CONNECTION_RULES = [
+    {
+        category: 'auth',
+        pattern: /\b(401|403)\b|unauthori[sz]ed|invalid[ _-]?(x-)?api[ _-]?key|incorrect api key|authentication[ _](failed|error)|forbidden|permission_denied|invalid[ _]token/i,
+        message: '认证失败：Key 或令牌无效，请检查后重新填写'
+    },
+    {
+        category: 'network',
+        pattern: /ENOTFOUND|ECONNREFUSED|ECONNRESET|ETIMEDOUT|EAI_AGAIN|EHOSTUNREACH|ENETUNREACH|fetch failed|getaddrinfo|could not resolve|network (is )?unreachable|connection (refused|reset|timed out)|socket hang up|unable to connect/i,
+        message: '网络不可达：无法连接到 API 地址，请检查网络、代理或 Base URL'
+    }
+];
+
+/**
+ * 把容器内最小请求的结果归类为 success / network / auth / other。
+ * 返回值只含固定文案和经过脱敏的尾部片段，不回传完整输出。
+ */
+function classifyConnectionResult(result, secrets = []) {
+    const exitCode = result && Number.isInteger(result.exitCode) ? result.exitCode : 1;
+    const output = String(result && result.output || '');
+    if (exitCode === 0) {
+        return { category: 'success', message: '连接成功', detail: '' };
+    }
+    const detail = redactSecrets(output.trim().slice(-300), secrets);
+    if (exitCode === 124) {
+        return { category: 'network', message: '请求超时：60 秒内没有得到响应，请检查网络、代理或 Base URL', detail };
+    }
+    for (const rule of CONNECTION_RULES) {
+        if (rule.pattern.test(output)) {
+            return { category: rule.category, message: rule.message, detail };
+        }
+    }
+    return { category: 'other', message: '测试失败，请查看详情', detail };
+}
+
+function redactSecrets(text, secrets = []) {
+    let result = String(text || '');
+    for (const secret of secrets) {
+        const value = String(secret || '');
+        if (value.length >= 4) {
+            result = result.split(value).join('****');
+        }
+    }
+    return result
+        .replace(/\b(sk|pk|key)-[A-Za-z0-9_-]{8,}/g, '$1-****')
+        .replace(/(Bearer\s+)[A-Za-z0-9._~+/=-]{8,}/gi, '$1****')
+        .replace(/(api[_-]?key["'=:\s]+)[A-Za-z0-9._-]{8,}/gi, '$1****');
+}
+
+// 软件源预设（单一数据源，经 /api/setup/agents 下发给向导）；“官方默认”与“自定义”由前端补。
+// apt 只填镜像站主机（保留 /ubuntu、/ubuntu-ports 路径）。value 都必须通过 normalizeMirrors。
+const MIRROR_PRESETS = {
+    apt: [
+        { label: '阿里云', value: 'https://mirrors.aliyun.com' },
+        { label: '清华', value: 'https://mirrors.tuna.tsinghua.edu.cn' },
+        { label: '中科大', value: 'https://mirrors.ustc.edu.cn' },
+        { label: '腾讯云', value: 'https://mirrors.tencent.com' }
+    ],
+    npm: [
+        { label: '阿里云', value: 'https://registry.npmmirror.com/' },
+        { label: '腾讯云', value: 'https://mirrors.tencent.com/npm/' },
+        { label: '华为云', value: 'https://repo.huaweicloud.com/repository/npm/' }
+    ],
+    pip: [
+        { label: '阿里云', value: 'https://mirrors.aliyun.com/pypi/simple/' },
+        { label: '清华', value: 'https://pypi.tuna.tsinghua.edu.cn/simple' },
+        { label: '中科大', value: 'https://pypi.mirrors.ustc.edu.cn/simple/' },
+        { label: '腾讯云', value: 'https://mirrors.tencent.com/pypi/simple' }
+    ]
+};
+
+function listMirrorPresets() {
+    return Object.fromEntries(Object.entries(MIRROR_PRESETS).map(([tool, items]) => [tool, items.map(item => ({ ...item }))]));
+}
+
+const PASSWORD_MIN_LENGTH = 8;
+const PASSWORD_MAX_LENGTH = 128;
+
+// 返回空字符串表示通过，否则是给用户看的原因
+function validateSetupPassword(password) {
+    if (typeof password !== 'string') {
+        return '请填写登录密码';
+    }
+    if (password.length < PASSWORD_MIN_LENGTH) {
+        return `密码至少 ${PASSWORD_MIN_LENGTH} 位`;
+    }
+    if (password.length > PASSWORD_MAX_LENGTH) {
+        return `密码不能超过 ${PASSWORD_MAX_LENGTH} 位`;
+    }
+    if (/[\u0000-\u001f\u007f]/.test(password)) {
+        return '密码不能包含换行、制表符等控制字符';
+    }
+    return '';
+}
+
+module.exports = {
+    MIRROR_PRESETS,
+    listMirrorPresets,
+    PASSWORD_MIN_LENGTH,
+    PASSWORD_MAX_LENGTH,
+    validateSetupPassword,
+    SETUP_AGENTS,
+    listSetupAgents,
+    getConfiguredAgents,
+    buildAgentRunProfile,
+    classifyConnectionResult,
+    redactSecrets
+};

package/lib/uninstall.js

@@ -0,0 +1,296 @@
+'use strict';
+
+// manyoyo uninstall：卸载离线包安装的 MANYOYO（方案 4.4）。
+// 所有副作用（询问、执行命令、杀进程、日志）都从参数注入，便于用临时 HOME 测试。
+// 只会碰 ~/.manyoyo 下的约定目录和 shell 配置里带标记的 manyoyo 块，绝不碰其它路径。
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { isImportProcess } = require('./offline-import');
+
+const MACHINE_NAME = 'podman-machine-manyoyo';
+const BLOCK_START = '# >>> manyoyo >>>';
+const BLOCK_END = '# <<< manyoyo <<<';
+const SHELL_FILES = ['.zprofile', '.zshrc', '.bash_profile', '.bash_login', '.profile', '.bashrc'];
+// run/ 里只有 serve -d 的 pid 文件，属于程序状态
+const PROGRAM_DIRS = ['bin', 'app', 'runtime', '.install', 'serve', 'run'];
+const CONFIG_AND_HISTORY = ['manyoyo.json', 'web-history', 'logs', 'plugin'];
+const MANYOYO_IMAGE_REPOS = ['ghcr.io/xcanwin/manyoyo', 'localhost/xcanwin/manyoyo'];
+
+/**
+ * 精确移除安装器写入的 PATH 块（含它前面那一个空行）。
+ * 只认独占一行的起止标记；用户自己的内容、仅仅提到 manyoyo 的行都不会被动。
+ */
+function removeManagedBlock(text) {
+    const lines = String(text).split('\n');
+    const result = [];
+    let index = 0;
+    let removed = 0;
+    while (index < lines.length) {
+        if (lines[index] === BLOCK_START) {
+            const end = lines.indexOf(BLOCK_END, index + 1);
+            if (end !== -1) {
+                if (result.length > 0 && result[result.length - 1] === '') result.pop();
+                index = end + 1;
+                removed += 1;
+                continue;
+            }
+        }
+        result.push(lines[index]);
+        index += 1;
+    }
+    return { text: result.join('\n'), removed };
+}
+
+function defaultRun(command, args, options = {}) {
+    const result = spawnSync(command, args, { encoding: 'utf-8', timeout: options.timeout || 60000, env: options.env });
+    if (result.error) throw result.error;
+    if (result.status !== 0) throw new Error(String(result.stderr || result.stdout || '').trim() || `${command} 退出码 ${result.status}`);
+    return result.stdout || '';
+}
+
+function defaultIsManyoyoServe(pid) {
+    try {
+        const command = spawnSync('ps', ['-o', 'command=', '-p', String(pid)], { encoding: 'utf-8' }).stdout || '';
+        return /manyoyo/.test(command) && /\bserve\b/.test(command);
+    } catch (error) {
+        return false;
+    }
+}
+
+function defaultKill(pid) {
+    try {
+        process.kill(pid, 'SIGTERM');
+        return true;
+    } catch (error) {
+        return false;
+    }
+}
+
+function readPid(file) {
+    try {
+        const text = fs.readFileSync(file, 'utf-8');
+        const json = text.trim().startsWith('{') ? JSON.parse(text).pid : Number(text.trim());
+        return Number.isInteger(json) && json > 0 ? json : 0;
+    } catch (error) {
+        return 0;
+    }
+}
+
+function removePath(target) {
+    // symlink 只删链接本身，不会顺着删到目标
+    fs.rmSync(target, { recursive: true, force: true });
+}
+
+const isYes = answer => /^y(es)?$/i.test(String(answer || '').trim());
+
+async function runUninstall(options = {}) {
+    const homeDir = options.homeDir || os.homedir();
+    const root = path.join(homeDir, '.manyoyo');
+    const ask = options.ask || (async () => '');
+    const log = options.log || (() => {});
+    const run = options.run || defaultRun;
+    const yes = Boolean(options.yes);
+    const isManyoyoServe = options.isManyoyoServe || defaultIsManyoyoServe;
+    const isImporter = options.isImporter || isImportProcess;
+    const kill = options.kill || defaultKill;
+    const selectExternalRuntime = options.selectExternalRuntime || (() => null);
+    const summary = { aborted: false, stopped: [], removed: [], kept: [], shellFiles: [], externalRemoved: { containers: [], images: [] } };
+
+    const privatePodmanRoot = path.join(root, 'runtime', 'podman');
+    const hasPrivatePodman = fs.existsSync(path.join(privatePodmanRoot, 'bin', 'podman'));
+
+    if (!fs.existsSync(root)) {
+        log(`没有找到 ${root}，无需卸载。`);
+        summary.aborted = true;
+        return summary;
+    }
+
+    if (!yes) {
+        log(`将停止 MANYOYO 的后台服务${hasPrivatePodman ? '与私有 Podman 虚拟机' : ''}，并删除：`);
+        log(`  ${PROGRAM_DIRS.filter(dir => fs.existsSync(path.join(root, dir))).map(dir => `~/.manyoyo/${dir}`).join('、') || '（没有程序目录）'}`);
+        log('  shell 配置里由安装器添加的 PATH 块');
+        if (hasPrivatePodman) log('  注意：私有 Podman 里的容器与镜像会一并删除（工作目录里的文件不受影响）。');
+        log('你的配置、会话历史、日志与工作目录会在后面逐项询问。');
+        if (!isYes(await ask('❔ 确认卸载? [y/N]: '))) {
+            log('已取消，什么都没有改动。');
+            summary.aborted = true;
+            return summary;
+        }
+    }
+
+    if (yes && hasPrivatePodman) {
+        log('提示：私有 Podman 里的容器与镜像会随虚拟机一起删除；需要保留里面的内容请先取消并导出。');
+    }
+
+    // 1. 停止后台服务（pid 必须确实是 manyoyo serve，避免 pid 复用误杀）
+    const pidFiles = [path.join(root, 'serve', 'app.json')];
+    const runServeDir = path.join(root, 'run', 'serve');
+    if (fs.existsSync(runServeDir)) {
+        for (const name of fs.readdirSync(runServeDir)) if (name.endsWith('.pid')) pidFiles.push(path.join(runServeDir, name));
+    }
+    for (const file of pidFiles) {
+        const pid = readPid(file);
+        if (pid && pid !== process.pid && isManyoyoServe(pid) && kill(pid)) {
+            summary.stopped.push(`serve(pid ${pid})`);
+            log(`已停止后台服务 (pid ${pid})`);
+        }
+    }
+    const importPid = readPid(path.join(root, 'runtime', 'import', 'loading.json'));
+    if (importPid && importPid !== process.pid && isImporter(importPid) && kill(importPid)) {
+        summary.stopped.push(`镜像导入(pid ${importPid})`);
+        log(`已停止后台镜像导入 (pid ${importPid})`);
+    }
+
+    // 2. 停止私有 Podman machine（尽力而为；之后整个 runtime/ 会被删除）
+    if (hasPrivatePodman) {
+        try {
+            run(path.join(privatePodmanRoot, 'bin', 'podman'), ['machine', 'stop', MACHINE_NAME], {
+                env: {
+                    ...process.env,
+                    XDG_CONFIG_HOME: path.join(privatePodmanRoot, 'config'),
+                    XDG_DATA_HOME: path.join(privatePodmanRoot, 'data'),
+                    CONTAINERS_CONF: path.join(privatePodmanRoot, 'containers.conf')
+                }
+            });
+            summary.stopped.push(`虚拟机 ${MACHINE_NAME}`);
+            log(`已停止虚拟机 ${MACHINE_NAME}`);
+        } catch (error) {
+            log(`提示：停止虚拟机时出错（${String(error.message).split('\n')[0]}），继续卸载。`);
+        }
+    }
+
+    // 3. 复用的外部 Docker/Podman：只处理 manyoyo 的容器与镜像，运行时本身不动
+    if (!hasPrivatePodman) {
+        const external = selectExternalRuntime();
+        if (external) {
+            const containers = String(safeRun(run, external.command, ['ps', '-a', '--filter', 'label=manyoyo.default_cmd', '--format', '{{.Names}}'], external)).split('\n').map(s => s.trim()).filter(Boolean);
+            const images = String(safeRun(run, external.command, ['images', '--format', '{{.Repository}}:{{.Tag}}'], external)).split('\n').map(s => s.trim())
+                .filter(ref => MANYOYO_IMAGE_REPOS.some(repo => ref.startsWith(`${repo}:`)));
+            if (containers.length + images.length > 0) {
+                log(`在你的 ${external.command} 里发现 ${containers.length} 个 manyoyo 容器、${images.length} 个 manyoyo 镜像。`);
+                // --yes 只确认程序本身的卸载；容器里可能有未保存的工作，不在 --yes 范围内
+                if (!yes && isYes(await ask('❔ 删除这些容器与镜像（不会动 Docker/Podman 本身）? [y/N]: '))) {
+                    for (const name of containers) { if (tryRun(run, external.command, ['rm', '-f', name], external)) summary.externalRemoved.containers.push(name); }
+                    for (const ref of images) { if (tryRun(run, external.command, ['rmi', ref], external)) summary.externalRemoved.images.push(ref); }
+                    const failed = containers.length + images.length - summary.externalRemoved.containers.length - summary.externalRemoved.images.length;
+                    log(failed > 0 ? `已删除 ${summary.externalRemoved.containers.length} 个容器、${summary.externalRemoved.images.length} 个镜像，${failed} 项删除失败（仍在使用或已不存在）。` : '已删除 manyoyo 的容器与镜像。');
+                } else {
+                    summary.kept.push('外部运行时里的 manyoyo 容器与镜像');
+                }
+            }
+        }
+    }
+
+    // 4. 删除程序目录
+    for (const dir of PROGRAM_DIRS) {
+        const target = path.join(root, dir);
+        if (fs.existsSync(target) || isDanglingLink(target)) {
+            removePath(target);
+            summary.removed.push(`~/.manyoyo/${dir}`);
+        }
+    }
+
+    // 5. 移除 shell 配置里的 PATH 块
+    for (const name of SHELL_FILES) {
+        const file = path.join(homeDir, name);
+        if (!fs.existsSync(file)) continue;
+        const { text, removed } = removeManagedBlock(fs.readFileSync(file, 'utf-8'));
+        if (removed > 0) {
+            fs.writeFileSync(file, text);
+            summary.shellFiles.push(name);
+        }
+    }
+    if (summary.shellFiles.length > 0) log(`已从 ${summary.shellFiles.join('、')} 移除 PATH 块（新开终端后生效）`);
+
+    // 6. 用户数据：逐项询问，默认保留；--yes 不会删除任何用户数据
+    const dataItems = CONFIG_AND_HISTORY.filter(name => fs.existsSync(path.join(root, name)));
+    if (dataItems.length > 0) {
+        if (!yes && isYes(await ask(`❔ 同时删除配置、会话历史与日志（${dataItems.join('、')}）? [y/N]: `))) {
+            dataItems.forEach(name => { removePath(path.join(root, name)); summary.removed.push(`~/.manyoyo/${name}`); });
+        } else {
+            summary.kept.push(...dataItems.map(name => `~/.manyoyo/${name}`));
+        }
+    }
+    // 默认工作目录：work（8.0 起），workpath 是 7.x 快捷对话留下的旧目录；都是用户的项目文件，逐个询问、默认保留
+    for (const name of ['work', 'workpath']) {
+        const dir = path.join(root, name);
+        if (!fs.existsSync(dir) && !isDanglingLink(dir)) continue;
+        if (!yes && isYes(await ask(`❔ 删除默认工作目录 ~/.manyoyo/${name}（里面是你的项目文件，默认保留）? [y/N]: `))) {
+            removePath(dir);
+            summary.removed.push(`~/.manyoyo/${name}`);
+        } else {
+            summary.kept.push(`~/.manyoyo/${name}`);
+        }
+    }
+    if (yes && summary.kept.length > 0) log('--yes 只确认程序本身的卸载，没有删除任何用户数据。');
+
+    // 收掉遗留的空目录（如日志按天分的空子目录）；还有保留的数据就留着
+    pruneEmptyDirs(root);
+    try {
+        if (fs.readdirSync(root).length === 0) fs.rmdirSync(root);
+    } catch (error) {
+        // 保留
+    }
+    if (summary.kept.length > 0) log(`已保留：${summary.kept.join('、')}`);
+    log('卸载完成。');
+    return summary;
+}
+
+// 只删空目录，不碰任何文件和符号链接
+function pruneEmptyDirs(dir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch (error) {
+        return;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory() || entry.isSymbolicLink()) continue;
+        const child = path.join(dir, entry.name);
+        pruneEmptyDirs(child);
+        try {
+            if (fs.readdirSync(child).length === 0) fs.rmdirSync(child);
+        } catch (error) {
+            // 保留
+        }
+    }
+}
+
+function isDanglingLink(target) {
+    try {
+        return fs.lstatSync(target).isSymbolicLink();
+    } catch (error) {
+        return false;
+    }
+}
+
+function tryRun(run, command, args, external) {
+    try {
+        run(command, args, { env: external && external.env ? { ...process.env, ...external.env } : undefined });
+        return true;
+    } catch (error) {
+        return false;
+    }
+}
+
+function safeRun(run, command, args, external) {
+    try {
+        return run(command, args, { env: external && external.env ? { ...process.env, ...external.env } : undefined });
+    } catch (error) {
+        return '';
+    }
+}
+
+module.exports = {
+    runUninstall,
+    readPid,
+    defaultIsManyoyoServe,
+    defaultKill,
+    removeManagedBlock,
+    MACHINE_NAME,
+    BLOCK_START,
+    BLOCK_END
+};

package/lib/update-check.js

@@ -0,0 +1,91 @@
+'use strict';
+
+// serve 的“有新版本”检查：每天最多问一次 GitHub Release，结果缓存在 ~/.manyoyo/serve/update-check.json。
+// updateCheck=false 时完全不发请求；请求只带固定的 User-Agent，不附带任何本机信息。
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { compareVersions } = require('./app-update');
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const FAILURE_RETRY_MS = 60 * 60 * 1000;
+
+function cachePath(homeDir) {
+    return path.join(homeDir, '.manyoyo', 'serve', 'update-check.json');
+}
+
+function readCache(homeDir) {
+    try {
+        return JSON.parse(fs.readFileSync(cachePath(homeDir), 'utf-8'));
+    } catch (error) {
+        return {};
+    }
+}
+
+function writeCache(homeDir, data) {
+    try {
+        fs.mkdirSync(path.dirname(cachePath(homeDir)), { recursive: true });
+        fs.writeFileSync(cachePath(homeDir), `${JSON.stringify(data)}\n`);
+    } catch (error) {
+        // 缓存写不进去不影响功能
+    }
+}
+
+/**
+ * @param {{homeDir?: string, currentVersion: string, installMode: string, enabled: boolean, fetchLatest: () => Promise<{version: string}>, now?: () => number}} options
+ */
+function createUpdateChecker(options) {
+    const homeDir = options.homeDir || os.homedir();
+    const now = options.now || Date.now;
+    const enabled = options.enabled !== false;
+    let inflight = null;
+
+    function snapshot() {
+        const cache = readCache(homeDir);
+        const latest = typeof cache.latest === 'string' ? cache.latest : '';
+        return {
+            enabled,
+            installMode: options.installMode,
+            current: options.currentVersion,
+            latest,
+            updateAvailable: Boolean(latest) && compareVersions(latest, options.currentVersion) > 0,
+            checkedAt: cache.checkedAt || null,
+            error: cache.error || ''
+        };
+    }
+
+    function isStale(cache) {
+        const age = now() - (Number(cache.checkedAtMs) || 0);
+        return age >= (cache.error ? FAILURE_RETRY_MS : DAY_MS);
+    }
+
+    function refresh() {
+        if (inflight) return inflight;
+        inflight = (async () => {
+            const previous = readCache(homeDir);
+            try {
+                const release = await options.fetchLatest();
+                writeCache(homeDir, { latest: release.version, checkedAtMs: now(), checkedAt: new Date(now()).toISOString() });
+            } catch (error) {
+                // 失败也记一次检查时间，别每次打开页面都去敲 GitHub；上一次成功的版本信息保留
+                writeCache(homeDir, { latest: previous.latest || '', checkedAtMs: now(), checkedAt: new Date(now()).toISOString(), error: String(error.message || error).slice(0, 200) });
+            } finally {
+                inflight = null;
+            }
+        })();
+        return inflight;
+    }
+
+    return {
+        // 立即返回缓存；缓存过期就在后台刷新，不阻塞请求
+        getInfo() {
+            if (enabled && isStale(readCache(homeDir))) refresh();
+            return snapshot();
+        },
+        refresh,
+        snapshot
+    };
+}
+
+module.exports = { createUpdateChecker, cachePath, DAY_MS, FAILURE_RETRY_MS };