@xcanwin/manyoyo 8.5.0 → 8.6.0

package/README.md

@@ -3,35 +3,36 @@
 </p>
 
 # <p align="center"><a href="https://github.com/xcanwin/manyoyo">MANYOYO（慢悠悠）</a></p>
-<p align="center"><b>MANYOYO – open-source sandbox for running AI coding agents (Claude Code / Codex / Gemini) safely in Docker/Podman</b></p>
-<p align="center">开源 AI Agent 沙箱：让 Claude Code / Codex / Gemini / OpenCode 在容器里放心跑 YOLO 模式，AI 随便折腾，伤不到你的电脑。</p>
+<p align="center"><b>Open-source sandbox for AI coding agents: run Claude Code, Codex, Gemini CLI and OpenCode in YOLO mode safely inside Docker/Podman</b></p>
+<p align="center">开源 AI 编程智能体安全沙箱：让 Claude Code / Codex / Gemini CLI / OpenCode 在 Docker/Podman 容器里放心跑 YOLO 模式，AI 随便折腾，伤不到你的电脑。</p>
 <p align="center">
   <a href="https://www.npmjs.com/package/@xcanwin/manyoyo"><img alt="npm" src="https://img.shields.io/npm/v/@xcanwin/manyoyo?style=flat-square" /></a>
   <a href="https://github.com/xcanwin/manyoyo/actions/workflows/npm-publish.yml"><img alt="Build status" src="https://img.shields.io/github/actions/workflow/status/xcanwin/manyoyo/npm-publish.yml?style=flat-square" /></a>
-  <a href="https://github.com/xcanwin/manyoyo/blob/main/LICENSE"><img alt="license" src="https://img.shields.io/badge/License-MIT-yellow.svg" /></a>
+  <a href="https://github.com/xcanwin/manyoyo/blob/main/LICENSE"><img alt="license" src="https://img.shields.io/badge/License-Apache--2.0-blue.svg" /></a>
 </p>
 
 <p align="center">
-  <a href="README.md"><b>中文</b></a> |
-  <a href="README.en.md">English</a>
-</p>
-<p align="center">
-  文档：<a href="https://xcanwin.github.io/manyoyo/">https://xcanwin.github.io/manyoyo/</a>
+  <a href="#中文"><b>中文</b></a> |
+  <a href="#english">English</a>
 </p>
 
 ---
 
-## 安装
+<a name="中文"></a>
 
-### macOS / Linux（推荐）
+## 安装（二选一即可）
+
+### 1. macOS / Linux（推荐）
 
 ```bash
-curl -fsSL https://github.com/xcanwin/manyoyo/raw/main/scripts/install.sh | sh
+curl -fsSL https://xcanwin.github.io/manyoyo/install.sh | sh
 ```
 
 装完按屏幕提示完成配置。macOS 不需要预装任何东西。Linux：缺少容器环境时，安装器会说明原因，征得你同意后用 sudo 自动安装。
 
-### 已有 Node.js 和 Docker/Podman
+下载慢或打不开 GitHub？先在终端设置代理（`export https_proxy=http://127.0.0.1:7890`，macOS 的系统代理会自动识别），或见[安装文档](https://xcanwin.github.io/manyoyo/guide/quick-start)里的手动下载办法。
+
+### 2. 已有 Node.js 和 Docker/Podman
 
 ```bash
 npm install -g @xcanwin/manyoyo
@@ -63,26 +64,66 @@ manyoyo run -y c   # 在沙箱里以 YOLO 模式启动 Claude Code
 - **统一配置**：运行配置、环境变量、挂载与镜像参数集中在 `~/.manyoyo/manyoyo.json`
 - **一条命令**安装、升级、卸载
 
-| 对比项 | 裸跑 Agent CLI | MANYOYO |
-| --- | --- | --- |
-| 宿主机暴露面 | 高 | 更低 |
-| 运行边界 | 分散 | 集中到容器与配置 |
-| 环境复现 | 弱 | 强（镜像 + 配置） |
-| 高风险模式说明 | 通常依赖工具自身 | 明确提示 YOLO / SOLO / sock 风险 |
-
 ## 安全须知
 
 MANYOYO 降低风险，但不是“绝对安全”：主要隔离手段是容器而不是虚拟机；`YOLO / SOLO` 仍可能执行危险命令；`sock` 模式会暴露宿主机 Docker socket；对外监听必须设强密码。详见[安全须知](https://xcanwin.github.io/manyoyo/guide/security)。
 
 ## 文档
 
-- 中文：<https://xcanwin.github.io/manyoyo/>（[安装](https://xcanwin.github.io/manyoyo/guide/quick-start)、[命令速查](https://xcanwin.github.io/manyoyo/reference/cli-options)、[配置](https://xcanwin.github.io/manyoyo/configuration/)、[故障排查](https://xcanwin.github.io/manyoyo/troubleshooting/)）
-- English: <https://xcanwin.github.io/manyoyo/en/>
+<https://xcanwin.github.io/manyoyo/>：[安装](https://xcanwin.github.io/manyoyo/guide/quick-start)、[命令速查](https://xcanwin.github.io/manyoyo/reference/cli-options)、[配置](https://xcanwin.github.io/manyoyo/configuration/)、[故障排查](https://xcanwin.github.io/manyoyo/troubleshooting/)
+
+---
+
+<a name="english"></a>
+
+## Install (pick one)
+
+### 1. macOS / Linux (recommended)
+
+```bash
+curl -fsSL https://xcanwin.github.io/manyoyo/install.sh | sh
+```
+
+When it finishes, follow the on-screen prompts to finish setup. macOS needs nothing installed first. Linux: if the container runtime is missing, the installer explains why and, with your consent, installs it with sudo.
+
+Slow or cannot reach GitHub? Set a proxy in the terminal first (`export https_proxy=http://127.0.0.1:7890`; the macOS system proxy is detected automatically), or see the manual download steps in the [install guide](https://xcanwin.github.io/manyoyo/en/guide/quick-start).
+
+### 2. Already have Node.js and Docker/Podman
+
+```bash
+npm install -g @xcanwin/manyoyo
+manyoyo
+```
+
+## Daily use
+
+```bash
+manyoyo            # open the web UI
+manyoyo update     # upgrade
+manyoyo uninstall  # uninstall (config and data are kept by default)
+```
+
+## Command line (optional)
+
+```bash
+manyoyo init all   # import the agent configs already on this machine
+manyoyo run -y c   # start Claude Code in YOLO mode inside the sandbox
+```
+
+The default image `ghcr.io/xcanwin/manyoyo` is pulled automatically on first use; run `manyoyo build --iv 2.2.0-common` only if you need a custom image. More commands: [CLI reference](https://xcanwin.github.io/manyoyo/en/reference/cli-options).
+
+## What it does
+
+- **Multiple agents**: `claude`, `codex`, `gemini`, `opencode` behind one entry point
+- **Container isolation**: Docker / Podman; the agent only sees the work directory you give it
+- **Web UI**: chat, browse files and open a terminal in the browser, phone friendly
+- **One config**: run profiles, environment variables, mounts and image arguments in `~/.manyoyo/manyoyo.json`
+- **One command** to install, upgrade and uninstall
 
-## 许可证
+## Security notes
 
-MIT
+MANYOYO reduces risk but is not "absolutely safe": the main isolation is a container, not a virtual machine; `YOLO / SOLO` can still run dangerous commands; `sock` mode exposes the host Docker socket; set a strong password before listening on a public address. See [Security notes](https://xcanwin.github.io/manyoyo/en/guide/security).
 
-## 贡献
+## Docs
 
-欢迎提交 [Issue](https://github.com/xcanwin/manyoyo/issues) 和 Pull Request。
+<https://xcanwin.github.io/manyoyo/en/>: [Install](https://xcanwin.github.io/manyoyo/en/guide/quick-start), [CLI reference](https://xcanwin.github.io/manyoyo/en/reference/cli-options), [Configuration](https://xcanwin.github.io/manyoyo/en/configuration/), [FAQ](https://xcanwin.github.io/manyoyo/en/troubleshooting/)

package/bin/manyoyo.js

@@ -26,6 +26,7 @@ const { listServeInstances, formatServeTable } = require('../lib/serve-instances
 const { pruneDanglingImages: pruneDanglingImagesSafely } = require('../lib/image-prune');
 const { runUninstall, readPid, defaultIsManyoyoServe, defaultKill } = require('../lib/uninstall');
 const appUpdate = require('../lib/app-update');
+const { getGithubFetch } = require('../lib/net-proxy');
 const { createUpdateChecker } = require('../lib/update-check');
 const { getLoginTokenDir, issueLoginToken } = require('../lib/login-token');
 const { launchApp, getAppStatePath, openBrowser } = require('../lib/app-launcher');
@@ -48,7 +49,7 @@ const { applyAptMirror } = require('../lib/mirrors');
 const containerState = require('../lib/container-state');
 const { buildExecArgs, resolveContainerId } = require('../lib/container-exec');
 const { createNetworkManager, NETWORK_NAME } = require('../lib/container-network');
-const { normalizePolicy } = require('../lib/network-policy');
+const { normalizePolicy, isUnrestricted: isUnrestrictedPolicy } = require('../lib/network-policy');
 const { withEnvEndpoints } = require('../lib/network-endpoints');
 const { resolveManageOptions } = require('../lib/container-manage-options');
 const {
@@ -353,7 +354,7 @@ function installServeProcessDiagnostics(logger) {
  * @property {string} [containerRuntime] - 容器运行时（auto/docker/podman，默认 auto；仅全局配置生效）
  * @property {string} [autostart] - 容器每次启动时由容器内 init 执行的 bash 脚本（新建容器时写入状态目录）
  * @property {boolean} [autostartOnServe] - serve 启动时自动拉起此容器
- * @property {object} [network] - 网络策略（preset / host / egress / peers，见 lib/network-policy.js），不写为默认收紧
+ * @property {object} [network] - 网络策略（preset / outbound / inbound / expose，见 lib/network-policy.js），不写为默认收紧
  * @property {{apt?: string, npm?: string, pip?: string}} [mirrors] - 容器内 apt/npm/pip 软件源（http/https URL，空/缺省为官方默认；仅全局配置生效）
  * @property {boolean} [updateCheck] - serve 是否每天检查一次新版本（默认 true；仅全局配置生效，请求不附带任何本机信息）
  * @property {number} [cacheTTL] - 缓存过期天数
@@ -836,6 +837,18 @@ async function prepareRuntimeForUpdate(configuredRuntime) {
     return true;
 }
 
+// 网络失败后的“下一步”：先说代理，再给手动下载升级包的办法（地址写完整，能直接复制）
+function updateNetworkNextSteps(proxy, release) {
+    const lines = [proxy && proxy.proxyEnv
+        ? `当前代理: ${proxy.display}，请确认代理可用`
+        : '有代理的话先在终端设置: export https_proxy=http://127.0.0.1:7890'];
+    const names = appUpdate.releaseAssetNames(release ? release.version : '<版本>', appUpdate.arch(), appUpdate.platformOs());
+    lines.push(`也可以手动下载这两个文件到同一目录，再执行: ${MANYOYO_NAME} update --file <下载的 ${names.app}>`);
+    const base = release ? `https://github.com/xcanwin/manyoyo/releases/download/v${release.version}` : 'https://github.com/xcanwin/manyoyo/releases/latest';
+    lines.push(release ? `${base}/${names.app}` : base, release ? `${base}/${names.sums}` : '');
+    return `\n   ${lines.filter(Boolean).join('\n   ')}`;
+}
+
 async function updateOfflineInstall(mode, options, globalConfig) {
     const { appRoot } = mode;
     if (options.rollback) {
@@ -847,14 +860,33 @@ async function updateOfflineInstall(mode, options, globalConfig) {
 
     const installed = appUpdate.currentVersion(appRoot) || mode.version;
     console.log(`${CYAN}🔄 当前版本: ${installed}${NC}`);
-    console.log(`${CYAN}🔄 正在查询最新版本...${NC}`);
-    const release = await appUpdate.fetchLatestRelease();
-    if (appUpdate.compareVersions(release.version, installed) <= 0) {
-        console.log(`${GREEN}✅ 已是最新版本 ${installed}${NC}`);
-        return;
+    let result;
+    if (options.file) {
+        const info = appUpdate.parseAppFileName(options.file);
+        if (info && appUpdate.compareVersions(info.version, installed) <= 0) {
+            console.log(`${GREEN}✅ 已是最新版本 ${installed}${NC}`);
+            return;
+        }
+        console.log(`${CYAN}⬇️  安装本地升级包 ${path.basename(options.file)}${NC}`);
+        result = await appUpdate.installAppFile({ appRoot, file: path.resolve(options.file), targetOs: appUpdate.platformOs() });
+    } else {
+        const github = getGithubFetch();
+        if (github.notice) console.log(`${CYAN}🌐 ${github.notice}${NC}`);
+        let release = null;
+        try {
+            console.log(`${CYAN}🔄 正在查询最新版本...${NC}`);
+            release = await appUpdate.fetchLatestRelease({ fetchImpl: github.fetch });
+            if (appUpdate.compareVersions(release.version, installed) <= 0) {
+                console.log(`${GREEN}✅ 已是最新版本 ${installed}${NC}`);
+                return;
+            }
+            console.log(`${CYAN}⬇️  发现新版本 ${release.version}，只下载 manyoyo 本体（数十 MB）${NC}`);
+            result = await appUpdate.installAppUpdate({ appRoot, release, fetchImpl: github.fetch, targetOs: appUpdate.platformOs(), log: line => console.log(`   ${line}`) });
+        } catch (error) {
+            if (error instanceof appUpdate.UpdateError && error.code === 'NETWORK') error.message += updateNetworkNextSteps(github.proxy, release);
+            throw error;
+        }
     }
-    console.log(`${CYAN}⬇️  发现新版本 ${release.version}，只下载 manyoyo 本体（数十 MB）${NC}`);
-    const result = await appUpdate.installAppUpdate({ appRoot, release, targetOs: appUpdate.platformOs(), log: line => console.log(`   ${line}`) });
     console.log(`${GREEN}✅ 更新完成: ${installed} → ${result.version}（上一版本 ${result.previous || '无'} 已保留，可用 ${MANYOYO_NAME} update --rollback 回滚）${NC}`);
 
     // Podman / VM 磁盘有变化只提示（需要新的完整包）
@@ -922,6 +954,10 @@ async function updateManyoyo(options = {}, globalConfig = {}) {
         console.error(`${RED}❌ --rollback 只适用于离线包安装；npm 安装的版本请用 npm install -g @xcanwin/manyoyo@<版本> 回退。${NC}`);
         process.exit(1);
     }
+    if (options.file) {
+        console.error(`${RED}❌ --file 只适用于离线包安装；npm 安装请用 npm install -g @xcanwin/manyoyo 升级。${NC}`);
+        process.exit(1);
+    }
 
     let isLocalFileInstall = false;
     let currentVersion = 'unknown';
@@ -1187,7 +1223,8 @@ https://github.com/xcanwin/manyoyo
         .helpGroup('日常:')
         .description('升级到最新版本')
         .option('--rollback', '回到上一版本')
-        .action(options => selectAction('update', { update: true, rollback: Boolean(options.rollback) }));
+        .option('--file <path>', '安装手动下载的升级包（manyoyo-<版本>-<系统>-<架构>-app.tar.gz，同目录需有 SHA256SUMS）')
+        .action(options => selectAction('update', { update: true, rollback: Boolean(options.rollback), file: options.file || '' }));
 
     program.command('uninstall')
         .helpGroup('日常:')
@@ -2104,8 +2141,8 @@ async function createNewContainer(runtime) {
 
     await ensureRunImage(runtime);
 
-    const networkPolicy = await withEnvEndpoints(normalizePolicy(runtime.network), [...userEnvLines, ...containerState.readEnvFilePaths(runtime.envFiles || []).flatMap(file => file.entries.map(entry => `${entry.key}=${entry.value}`))]);
     const networkManager = createCliNetworkManager(runtime);
+    const networkPolicy = await withEnvEndpoints(await networkManager.resolveRefs(normalizePolicy(runtime.network)), [...userEnvLines, ...containerState.readEnvFilePaths(runtime.envFiles || []).flatMap(file => file.entries.map(entry => `${entry.key}=${entry.value}`))]);
     if (!hasNetworkArg([...(runtime.contModeArgs || []), ...(runtime.containerExtraArgs || [])])) {
         try {
             await networkManager.ensureBridgeNetwork();
@@ -2119,7 +2156,7 @@ async function createNewContainer(runtime) {
         envFiles: runtime.envFiles,
         autostart: runtime.autostart,
         network: networkPolicy,
-        netRequired: networkPolicy.preset !== 'open',
+        netRequired: !isUnrestrictedPolicy(networkPolicy),
         meta: { name: runtime.containerName }
     });
 
@@ -2434,7 +2471,7 @@ async function runWebServerMode(runtime) {
         currentVersion: require('../package.json').version,
         installMode: appUpdate.detectInstallMode({ scriptPath: __filename }).mode,
         enabled: UPDATE_CHECK_ENABLED,
-        fetchLatest: () => appUpdate.fetchLatestRelease()
+        fetchLatest: () => appUpdate.fetchLatestRelease({ fetchImpl: getGithubFetch().fetch })
     });
 
     // 启动时检查 Playwright 当前模式是否还活着，失效就回退到默认模式（只警告，不阻塞启动）

package/lib/app-update.js

@@ -18,12 +18,30 @@ const VERSION_PATTERN = /^\d+\.\d+\.\d+$/;
 const FETCH_TIMEOUT_MS = 15000;
 
 class UpdateError extends Error {
-    constructor(code, message) {
+    constructor(code, message, extra = {}) {
         super(message);
         this.code = code;
+        Object.assign(this, extra);
     }
 }
 
+// 网络错误码 → 中文原因；没见过的显示原始 code
+function describeNetworkReason(error) {
+    const code = error && (error.cause && error.cause.code || error.code) || '';
+    const name = error && (error.cause && error.cause.name || error.name) || '';
+    if (/TIMEOUT|ETIMEDOUT|ABORT/i.test(code) || /TimeoutError|AbortError/.test(name)) return '连接超时';
+    if (code === 'ECONNRESET') return '连接被重置';
+    if (code === 'ECONNREFUSED') return '连接被拒绝';
+    if (code === 'ENOTFOUND' || code === 'EAI_AGAIN') return '域名解析失败';
+    if (/CERT|SELF_SIGNED|UNABLE_TO_VERIFY|ERR_TLS/i.test(code)) return '证书校验失败';
+    return code || name || '网络错误';
+}
+
+function networkError(url, error, prefix = '连不上') {
+    const host = (() => { try { return new URL(url).host; } catch (e) { return String(url); } })();
+    return new UpdateError('NETWORK', `${prefix} ${host}（${describeNetworkReason(error)}）\n   地址: ${url}`, { url });
+}
+
 function parseVersion(text) {
     const match = String(text || '').trim().replace(/^v/, '').match(/^(\d+)\.(\d+)\.(\d+)/);
     return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
@@ -80,7 +98,7 @@ async function request(fetchImpl, url, options = {}) {
             headers: { Accept: 'application/vnd.github+json', 'User-Agent': 'manyoyo-update', ...(options.headers || {}) }
         });
     } catch (error) {
-        throw new UpdateError('NETWORK', `无法连接 GitHub（${error && error.cause && error.cause.code || error.name || '网络错误'}）。请检查网络或代理后重试。`);
+        throw networkError(url, error);
     }
 }
 
@@ -135,7 +153,7 @@ function releaseAssetNames(version, targetArch, targetOs = 'macos') {
 
 async function fetchText(fetchImpl, url) {
     const response = await request(fetchImpl, url);
-    if (!response.ok) throw new UpdateError('HTTP', `下载 ${url.split('/').pop()} 失败（HTTP ${response.status}）。`);
+    if (!response.ok) throw new UpdateError('HTTP', `下载 ${url.split('/').pop()} 失败（HTTP ${response.status}）。\n   地址: ${url}`, { url });
     return response.text();
 }
 
@@ -183,6 +201,44 @@ function pruneApps(appRoot, keep) {
     }
 }
 
+/**
+ * 解开已校验过的 -app.tar.gz 并切换 current（网络下载与 --file 共用）。包不完整/内容不符都在切换前中止。
+ */
+async function installFromArchive({ appRoot, archive, version, targetArch, targetOs, run = defaultRun }) {
+    const staging = path.join(appRoot, `.tmp-${version}-${process.pid}`);
+    try {
+        fs.rmSync(staging, { recursive: true, force: true });
+        fs.mkdirSync(staging, { recursive: true });
+        run(TAR_COMMAND, ['-xzf', archive, '-C', staging]);
+
+        for (const required of ['node/bin/node', 'manyoyo/bin/manyoyo.js', 'manifest.json']) {
+            if (!fs.existsSync(path.join(staging, required))) throw new UpdateError('BAD_PACKAGE', `升级包不完整（缺少 ${required}），已中止升级。`);
+        }
+        let manifest;
+        try {
+            manifest = JSON.parse(fs.readFileSync(path.join(staging, 'manifest.json'), 'utf-8'));
+        } catch (error) {
+            throw new UpdateError('BAD_PACKAGE', '升级包的 manifest.json 无法解析，已中止升级。');
+        }
+        if (manifest.version !== version || manifest.kind !== 'app' || manifest.arch !== targetArch || (manifest.os && manifest.os !== targetOs)) {
+            throw new UpdateError('BAD_PACKAGE', `升级包内容与预期不符（版本 ${manifest.version}、类型 ${manifest.kind}、架构 ${manifest.arch}、系统 ${manifest.os || targetOs}），已中止升级。`);
+        }
+        fs.writeFileSync(path.join(staging, '.installed'), await sha256File(path.join(staging, 'manifest.json')));
+
+        const previous = currentVersion(appRoot);
+        const target = path.join(appRoot, version);
+        if (version !== previous) fs.rmSync(target, { recursive: true, force: true });
+        if (version !== previous) fs.renameSync(staging, target);
+        switchCurrent(appRoot, version);
+        writeUpdateRecord(appRoot, { previous: previous && previous !== version ? previous : readUpdateRecord(appRoot).previous || '', current: version, updatedAt: new Date().toISOString() });
+        const record = readUpdateRecord(appRoot);
+        pruneApps(appRoot, [version, record.previous].filter(Boolean));
+        return { version, previous: record.previous || '', manifest };
+    } finally {
+        fs.rmSync(staging, { recursive: true, force: true });
+    }
+}
+
 /**
  * 下载并安装 -app.tar.gz，成功后切换 current。校验失败/包不完整都在切换前中止，不留半成品。
  */
@@ -194,57 +250,56 @@ async function installAppUpdate({ appRoot, release, fetchImpl = fetch, targetArc
         throw new UpdateError('NO_ASSET', `Release ${release.version} 里没有适合这台机器（${targetOs}-${targetArch}）的升级包（需要 ${names.app} 与 ${names.sums}）。`);
     }
 
-    log(`校验清单: ${names.sums}`);
+    log(`校验清单: ${sumsUrl}`);
     const sums = parseSha256Sums(await fetchText(fetchImpl, sumsUrl));
     const expected = sums[names.app];
     if (!expected) throw new UpdateError('CHECKSUM', `校验清单里没有 ${names.app}，已中止升级。`);
 
     const workDir = fs.mkdtempSync(path.join(tmpRoot, 'manyoyo-update-'));
-    const staging = path.join(appRoot, `.tmp-${release.version}-${process.pid}`);
     try {
-        log(`下载升级包: ${names.app}`);
         const archive = path.join(workDir, names.app);
         try {
             await downloadVerified({ url: appUrl, sha256: expected, dest: archive, fetchImpl: (url, options) => request(fetchImpl, url, { ...options, noTimeout: true }), log });
         } catch (error) {
             if (/SHA256 校验失败/.test(error.message)) throw new UpdateError('CHECKSUM', `升级包 SHA256 校验失败，已中止升级，当前版本不受影响。`);
             if (error instanceof UpdateError) throw error;
-            throw new UpdateError('NETWORK', `下载升级包失败：${error.message}`);
-        }
-
-        fs.rmSync(staging, { recursive: true, force: true });
-        fs.mkdirSync(staging, { recursive: true });
-        run(TAR_COMMAND, ['-xzf', archive, '-C', staging]);
-
-        for (const required of ['node/bin/node', 'manyoyo/bin/manyoyo.js', 'manifest.json']) {
-            if (!fs.existsSync(path.join(staging, required))) throw new UpdateError('BAD_PACKAGE', `升级包不完整（缺少 ${required}），已中止升级。`);
-        }
-        let manifest;
-        try {
-            manifest = JSON.parse(fs.readFileSync(path.join(staging, 'manifest.json'), 'utf-8'));
-        } catch (error) {
-            throw new UpdateError('BAD_PACKAGE', '升级包的 manifest.json 无法解析，已中止升级。');
+            throw networkError(appUrl, error, '下载中断，连不上');
         }
-        if (manifest.version !== release.version || manifest.kind !== 'app' || manifest.arch !== targetArch || (manifest.os && manifest.os !== targetOs)) {
-            throw new UpdateError('BAD_PACKAGE', `升级包内容与预期不符（版本 ${manifest.version}、类型 ${manifest.kind}、架构 ${manifest.arch}、系统 ${manifest.os || targetOs}），已中止升级。`);
-        }
-        fs.writeFileSync(path.join(staging, '.installed'), await sha256File(path.join(staging, 'manifest.json')));
 
-        const previous = currentVersion(appRoot);
-        const target = path.join(appRoot, release.version);
-        if (release.version !== previous) fs.rmSync(target, { recursive: true, force: true });
-        if (release.version !== previous) fs.renameSync(staging, target);
-        switchCurrent(appRoot, release.version);
-        writeUpdateRecord(appRoot, { previous: previous && previous !== release.version ? previous : readUpdateRecord(appRoot).previous || '', current: release.version, updatedAt: new Date().toISOString() });
-        const record = readUpdateRecord(appRoot);
-        pruneApps(appRoot, [release.version, record.previous].filter(Boolean));
-        return { version: release.version, previous: record.previous || '', manifest };
+        return await installFromArchive({ appRoot, archive, version: release.version, targetArch, targetOs, run });
     } finally {
         fs.rmSync(workDir, { recursive: true, force: true });
-        fs.rmSync(staging, { recursive: true, force: true });
     }
 }
 
+const APP_FILE_PATTERN = /^manyoyo-(\d+\.\d+\.\d+)-(macos|linux)-(arm64|x64)-app\.tar\.gz$/;
+
+/** 从升级包文件名解析版本 / 系统 / 架构，不符合命名就返回 null。 */
+function parseAppFileName(file) {
+    const match = path.basename(String(file)).match(APP_FILE_PATTERN);
+    return match ? { version: match[1], os: match[2], arch: match[3] } : null;
+}
+
+/**
+ * 安装手动下载的 -app.tar.gz：同目录的 SHA256SUMS 必须列出它且哈希一致（没有跳过校验的办法），之后与网络升级走同一段安装逻辑。
+ */
+async function installAppFile({ appRoot, file, targetArch = arch(), targetOs = 'macos', run = defaultRun }) {
+    const info = parseAppFileName(file);
+    if (!info) throw new UpdateError('BAD_FILE', `文件名不符合升级包命名（manyoyo-<版本>-<系统>-<架构>-app.tar.gz）: ${path.basename(String(file))}`);
+    if (info.os !== targetOs || info.arch !== targetArch) {
+        throw new UpdateError('BAD_FILE', `这个升级包是 ${info.os}-${info.arch} 的，这台机器需要 ${targetOs}-${targetArch}。`);
+    }
+    if (!fs.existsSync(file)) throw new UpdateError('BAD_FILE', `找不到文件: ${file}`);
+    const sumsFile = path.join(path.dirname(path.resolve(file)), 'SHA256SUMS');
+    if (!fs.existsSync(sumsFile)) {
+        throw new UpdateError('CHECKSUM', `同目录下没有 SHA256SUMS，无法校验。\n   请从 https://github.com/${REPO}/releases/download/v${info.version}/SHA256SUMS 下载，放到升级包旁边再试。`);
+    }
+    const expected = parseSha256Sums(fs.readFileSync(sumsFile, 'utf-8'))[path.basename(file)];
+    if (!expected) throw new UpdateError('CHECKSUM', `SHA256SUMS 里没有 ${path.basename(file)}，已中止升级。`);
+    if (await sha256File(file) !== expected) throw new UpdateError('CHECKSUM', '升级包 SHA256 校验失败，已中止升级，当前版本不受影响。');
+    return installFromArchive({ appRoot, archive: file, version: info.version, targetArch, targetOs, run });
+}
+
 function rollbackApp({ appRoot }) {
     const current = currentVersion(appRoot);
     const record = readUpdateRecord(appRoot);
@@ -334,6 +389,9 @@ module.exports = {
     parseSha256Sums,
     releaseAssetNames,
     installAppUpdate,
+    installAppFile,
+    parseAppFileName,
+    networkError,
     rollbackApp,
     currentVersion,
     describeRuntimeChange,