@asiainfo-sdd/multica-cli 0.2.1 → 0.3.2

package/README.md

@@ -1,98 +1,129 @@
-# @asiainfo-sdd/multica-cli — aido（daemon 客户端）安装帮助包
-
-通过 npm 安装数字工厂 aido 命令（daemon 客户端二进制，含主机线能力）。
-安装后对外命令名是 **`aido`**（`multica` 作为兼容别名同时可用，内部等价）。
-**本包负责安装二进制与部署级配置**：npm install 时按平台自动下载、sha256 校验、落位，
-并把 `server_url` / `app_url` 合并写入 `~/.multica/config.json`（只填空，不覆盖已有值）；
-**不写 token、不登录、不启动/停止 daemon**——个人凭据与 daemon 生命周期始终由用户掌控。
-
-## 部署级配置的取值优先级
-
-```
-MULTICA_SERVER_URL / MULTICA_APP_URL 环境变量（安装时）
-  > manifest.json 顶层 server_url / app_url（运维改下载源即可，无需重发 npm 包）
-  > 包内 lib/dist-config.json（发布时固化）
-```
-
-当前测试环境默认值（lib/dist-config.json）：`server_url = http://10.19.198.57:8080`（multica 测试环境）、`app_url = http://10.19.198.57:8080`（daemon login 浏览器 OAuth 流的基准地址）。
-
-用户 `~/.multica/config.json` 中已有的值（如指向测试服）**一律不覆盖**，仅提示。
-
-## 适用人群与前置
-
-- 内网办公电脑/服务器上的开发者，机器可访问下载源（默认 Nexus raw，可覆盖）
-- 已安装 Node.js ≥ 18 与 npm
-- 支持平台：darwin / linux / windows × amd64 / arm64
-
-## 安装
-
-```bash
-# 全局安装（推荐：npm 全局 bin 目录已在 PATH）
-npm i -g @asiainfo-sdd/multica-cli
-
-# 或项目内安装（用 npx 调用）
-npm i @asiainfo-sdd/multica-cli
-npx aido version
-```
-
-安装完成后按提示自行完成剩余步骤（若下载源已带 server_url 则只需两步）：
-
-```bash
-aido config set server_url https://<服务器地址>   # 仅当安装时未自动写入
-aido login --token mul_<个人令牌>                  # 令牌在 Web 端“设置→令牌”生成
-aido daemon start                                 # 需本机已装至少一个 agent CLI（claude/codex/opencode…）
-```
-
-日常管理：`aido daemon status` / `aido daemon logs` / `aido daemon stop`。
-
-> `multica xxx` 与 `aido xxx` 完全等价（同一二进制、同一配置），文档统一用 `aido`。
-
-## 环境变量
-
-| 变量 | 作用 |
-| --- | --- |
-| `MULTICA_DOWNLOAD_BASE` | 覆盖二进制下载源基址（默认内网 Nexus raw 地址；源根需有 `manifest.json` 与 `v<版本>/` 目录） |
-| `MULTICA_SERVER_URL` / `MULTICA_APP_URL` | 安装时写入 `~/.multica/config.json` 的部署级配置（优先级高于 manifest 与包内置；不覆盖已有值） |
-| `MULTICA_SKIP_BINARY_INSTALL=1` | 跳过 postinstall 下载（`--ignore-scripts` 环境或自备二进制时用） |
-| `http_proxy` / `https_proxy` / `NO_PROXY` | 走内网代理时识别（Node 自带 fetch 不认这些变量，本包已自实现） |
-
-## 故障恢复
-
-| 症状 | 处理 |
-| --- | --- |
-| 安装时看不到“上手”提示 | npm ≥ 7 默认隐藏 postinstall 输出（脚本失败时才显示）；加 `--foreground-scripts` 参数即可看到，或安装后执行 `aido version` 确认可用 |
-| 执行 `aido` 提示二进制未下载 | `npm rebuild @asiainfo-sdd/multica-cli`（常见于 `--ignore-scripts` 安装或当时下载源不可达） |
-| 提示“aido 不是命令” | 重新打开终端；或用 `npx aido ...` |
-| 升级时提示文件被占用 | daemon 正在运行：先 `aido daemon stop`，再 `npm i -g @asiainfo-sdd/multica-cli@<版本>` |
-| 下载源不可达 | 确认 `MULTICA_DOWNLOAD_BASE`；检查代理变量 |
-
-## 升级
-
-```bash
-npm i -g @asiainfo-sdd/multica-cli@<新版本>
-```
-
-npm 包版本与二进制版本一一对应；postinstall 检测到版本变化会重新下载。
-daemon 的 auto-reload 默认开启：二进制替换后运行中的 daemon 会自动重启到新版本。
-
-## 版本发布（维护者）
-
-1. multica 仓 `server/extensions/agentfoundry/build/build.sh cli-all <版本>`：
-   6 平台 CLI 产物 + `manifest.json` 落 `dist/cli/`
-2. 如需随包分发部署级配置，在 `manifest.json` 顶层加 `server_url` / `app_url`
-3. 将 `dist/cli/` 整目录同步到 HTTP 静态源根（Nexus raw `repository/multica-cli/`）
-4. 同步更新本仓 `package.json` 的 `version` 与 `lib/manifest.fallback.json`（兜底清单）、`lib/dist-config.json`（包内置默认配置），`npm publish`
-
-## FAQ
-
-**Q: 为什么不把二进制打进 npm 包？**
-每个平台 17-68MB，6 平台约 200MB；HTTP 运行时下载让 npm 包保持 KB 级，且安装哪台机器才拉哪个平台。
-
-**Q: postinstall 下载失败了怎么办？**
-安装不会失败到阻断——失败时打印修复指引，之后 `npm rebuild @asiainfo-sdd/multica-cli` 重试。
-
-**Q: aido 和 multica 什么关系？**
-`aido` 是对外品牌命令，`multica` 是兼容别名；两者指向同一二进制与配置，输出完全一致。对用户统一推荐 `aido`。
-
-**Q: daemon 会自动升级吗？**
-self-host 场景下 daemon 的 auto-update 默认关闭；升级由你通过 npm 主动控制。
+# @asiainfo-sdd/multica-cli — multica（daemon 客户端）安装帮助包
+
+通过 npm 安装数字工厂 multica 命令（daemon 客户端二进制，含主机线能力）。
+**本包负责安装二进制与部署级配置**：npm install 时按平台自动下载、sha256 校验、落位，
+并把 `server_url` / `app_url` 合并写入 `~/.multica/config.json`（只填空，不覆盖已有值）；
+**不写 token、不登录、不启动/停止 daemon**——个人凭据与 daemon 生命周期始终由用户掌控。
+
+## 部署级配置的取值优先级
+
+```
+MULTICA_SERVER_URL / MULTICA_APP_URL 环境变量（安装时）
+  > manifest.json 顶层 server_url / app_url（运维改下载源即可，无需重发 npm 包）
+  > 包内 lib/dist-config.json（发布时按 profile 固化）
+```
+
+二进制下载源基址同样三级：`MULTICA_DOWNLOAD_BASE` 环境变量 > manifest 对应环境的 `lib/dist-config.json` 的 `download_base` > 包内置默认。
+
+用户 `~/.multica/config.json` 中已有的值**一律不覆盖**，仅提示。
+
+## 适用人群与前置
+
+- 内网办公电脑/服务器上的开发者，机器可访问下载源（可覆盖）
+- 已安装 Node.js ≥ 18 与 npm
+- 支持平台：darwin / linux / windows × amd64 / arm64
+
+## 安装
+
+```bash
+# 全局安装（推荐：npm 全局 bin 目录已在 PATH）
+npm i -g @asiainfo-sdd/multica-cli
+
+# 或项目内安装（用 npx 调用）
+npm i @asiainfo-sdd/multica-cli
+npx multica version
+```
+
+安装完成后按提示自行完成剩余步骤（若下载源已带 server_url 则只需两步）：
+
+```bash
+multica config set server_url https://<服务器地址>   # 仅当安装时未自动写入
+multica login --token mul_<个人令牌>                  # 令牌在 Web 端“设置→令牌”生成
+multica daemon start                                 # 需本机已装至少一个 agent CLI（claude/codex/opencode…）
+```
+
+日常管理：`multica daemon status` / `multica daemon logs` / `multica daemon stop`。
+
+## 环境变量
+
+| 变量 | 作用 |
+| --- | --- |
+| `MULTICA_DOWNLOAD_BASE` | 覆盖二进制下载源基址（源根需有 `manifest.json` 与 `v<版本>/` 目录） |
+| `MULTICA_SERVER_URL` / `MULTICA_APP_URL` | 安装时写入 `~/.multica/config.json` 的部署级配置（优先级高于 manifest 与包内置；不覆盖已有值） |
+| `MULTICA_SKIP_BINARY_INSTALL=1` | 跳过 postinstall 下载（`--ignore-scripts` 环境或自备二进制时用） |
+| `http_proxy` / `https_proxy` / `NO_PROXY` | 走内网代理时识别（Node 自带 fetch 不认这些变量，本包已自实现） |
+
+## 故障恢复
+
+| 症状 | 处理 |
+| --- | --- |
+| 安装时看不到“上手”提示 | npm ≥ 7 默认隐藏 postinstall 输出（脚本失败时才显示）；加 `--foreground-scripts` 参数即可看到，或安装后执行 `multica version` 确认可用 |
+| 执行 `multica` 提示二进制未下载 | `npm rebuild @asiainfo-sdd/multica-cli`（常见于 `--ignore-scripts` 安装或当时下载源不可达） |
+| 提示“multica 不是命令” | 重新打开终端；或用 `npx multica ...` |
+| 升级时提示文件被占用 | daemon 正在运行：先 `multica daemon stop`，再 `npm i -g @asiainfo-sdd/multica-cli@<版本>` |
+| 下载源不可达 | 确认 `MULTICA_DOWNLOAD_BASE`；检查代理变量 |
+
+## 升级
+
+```bash
+npm i -g @asiainfo-sdd/multica-cli@<新版本>
+```
+
+npm 包版本与二进制版本一一对应；postinstall 检测到版本变化会重新下载。
+daemon 的 auto-reload 默认开启：二进制替换后运行中的 daemon 会自动重启到新版本。
+
+## 卸载
+
+**用 `multica-uninstall`，不要只用 `npm un -g`**。原因：
+
+- npm v7 起不再执行 `preuninstall` 等卸载生命周期脚本，`npm un -g` 只能移除 npm 包，
+  不会停 daemon、不会删 `~/.multica` 配置、也不会删独立安装的 `~/.local/bin/multica`；
+- 同机可能同时存在多个 npm 全局目录（nvm prefix、`%APPDATA%\npm`、历史 prefix），
+  而 `npm root -g` 只报当前一个 —— 会出现“卸了还能用”。
+
+`multica-uninstall` 一次覆盖全部安装产物：
+
+```bash
+multica-uninstall            # 交互确认后卸载
+multica-uninstall --yes      # 非交互（脚本/CI）
+multica-uninstall --keep-config   # 保留 ~/.multica（保留登录令牌与配置）
+multica-uninstall --dry-run  # 只打印将执行的操作，不改动任何文件
+```
+
+执行内容依次为：停 daemon → 删 `~/.multica`（除非 `--keep-config`）→ 删独立二进制
+`~/.local/bin/multica[.exe]` → 删 PATH 上的命令入口（npm shim）→ 逐个前缀卸载 npm 全局包。
+
+卸载后请**重开终端**以确保 PATH 刷新；再执行 `multica version` 应提示命令不存在。
+
+> 若某 npm 包因文件占用未能删除（Windows 常见），脚本会打印出对应
+> `npm uninstall -g --prefix <prefix> <包名>` 命令，重开终端后手动执行即可。
+
+## 版本发布（维护者）
+
+本包位于 multica 仓 `apps/multica-cli-installer/`（与 `server/` 同仓管理，随主仓 git 提交发布）。
+同一份源码按 profile 发布两个 npm 包（差异仅包名与内置部署级配置），发布流程：
+
+1. 本仓 `server/extensions/agentfoundry/build/build.sh cli-all <版本>`：
+   6 平台 CLI 产物 + `manifest.json` 落 `server/extensions/agentfoundry/dist/cli/`
+2. 如需随包分发部署级配置，在 `manifest.json` 顶层加 `server_url` / `app_url`
+3. 将 `dist/cli/` 整目录同步到目标环境下载源的 HTTP 静态根（MinIO `daemon-download/` 前缀）
+4. 在 `apps/multica-cli-installer/` 下按 profile 发布：
+   - 生产包：`node scripts/publish.mjs prod [版本]`
+   - 测试包：`node scripts/publish.mjs test`（连接测试环境，配置见 `publish/profiles.json`）
+   - 加 `--dry-run` 只打 tarball 检查，不实际发布
+5. 版本号在源 `package.json` 上推进（`lib/dist-config.json` 保持生产默认值；测试包的差异由 profile 注入）
+
+> 两包 bin 命令名均为 `multica`，同一台机器互斥安装；切换环境用
+> `npm rm -g <A> && npm i -g <B>`，安装时会自动覆盖式更新 `~/.multica/config.json`
+> 的 server_url/app_url 并提示（token 需重新登录生成）。
+
+## FAQ
+
+**Q: 为什么不把二进制打进 npm 包？**
+每个平台 17-68MB，6 平台约 200MB；HTTP 运行时下载让 npm 包保持 KB 级，且安装哪台机器才拉哪个平台。
+
+**Q: postinstall 下载失败了怎么办？**
+安装不会失败到阻断——失败时打印修复指引，之后 `npm rebuild @asiainfo-sdd/multica-cli` 重试。
+
+**Q: daemon 会自动升级吗？**
+self-host 场景下 daemon 的 auto-update 默认关闭；升级由你通过 npm 主动控制。

package/bin/multica-uninstall.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+'use strict';
+
+// multica-uninstall 命令入口：委托 lib/uninstall.js。
+require('../lib/uninstall.js');

package/bin/multica.js

@@ -2,25 +2,22 @@
 'use strict';
 
 // bin wrapper：把参数原样转给 vendor/ 下的平台二进制。
-// multica 是兼容别名入口（对外品牌命令是 aido，见 bin/aido.js）。
+// 对外唯一命令名是 multica（aido 入口已移除）。
 // 二进制的子命令（daemon/login/config/...）与参数原样透传。
 
 const { spawn } = require('child_process');
 const fs = require('fs');
 const path = require('path');
 const { detectPlatform, vendorBinaryPath } = require('../lib/platform');
-
-// 对外命令名：默认 aido；用户通过 multica 别名调用时保持 multica 提示。
-const invokedAs = path.basename(process.argv[1] || '', '.js').replace(/\.(cmd|ps1)$/, '') || 'aido';
-const brand = invokedAs === 'multica' ? 'multica' : 'aido';
+const pkg = require('../package.json');
 
 const plat = detectPlatform();
 const binary =
   plat && vendorBinaryPath(path.join(__dirname, '..', 'vendor'), plat);
 
 if (!binary || !fs.existsSync(binary)) {
-  console.error(`✗ ${brand} 二进制尚未下载。`);
-  console.error('  修复方式：npm rebuild @asiainfo-sdd/multica-cli');
+  console.error('✗ multica 二进制尚未下载。');
+  console.error(`  修复方式：npm rebuild ${pkg.name}`);
   console.error('  （或设置 MULTICA_SKIP_BINARY_INSTALL=1 显式跳过后自备二进制）');
   process.exit(127);
 }
@@ -40,7 +37,7 @@ process.on('exit', () => {
 });
 
 child.on('error', (err) => {
-  console.error(`✗ 无法执行 ${brand} 二进制：${err.message}`);
+  console.error(`✗ 无法执行 multica 二进制：${err.message}`);
   process.exit(126);
 });
 

package/lib/dist-config.json

@@ -1,4 +1,5 @@
 {
   "server_url": "https://aido.asiainfo.com/runtime-svc",
-  "app_url": "https://aido.asiainfo.com/runtime-svc"
+  "app_url": "https://aido.asiainfo.com/runtime-svc",
+  "download_base": "https://aido.asiainfo.com/aird-api/business/api/v1/external/daemon-download"
 }

package/lib/http.js

@@ -1,174 +1,174 @@
-'use strict';
-
-// 零依赖 HTTP 客户端：Node 自带 fetch（undici）不认 http_proxy/https_proxy
-// 环境变量，内网代理场景必须自己处理。支持：
-//   - 直连 http/https
-//   - http_proxy / https_proxy / HTTP_PROXY / HTTPS_PROXY
-//   - NO_PROXY（逗号分隔主机名，支持后缀匹配）
-//   - https over proxy：CONNECT 隧道
-// 流式响应，供下载侧边收边算 sha256。
-
-const http = require('http');
-const https = require('https');
-const { URL } = require('url');
-
-const KEEP_ALIVE_AGENT_OPTIONS = { keepAlive: false };
-
-function proxyFromEnv(targetURL) {
-  const url = new URL(targetURL);
-  if (matchesNoProxy(url.hostname)) return null;
-  const proto = url.protocol === 'https:' ? 'https' : 'http';
-  const raw =
-    process.env[`${proto}_proxy`] || process.env[`${proto}_PROXY`] || '';
-  if (!raw) return null;
-  try {
-    const proxy = new URL(raw);
-    if (!/^https?:$/.test(proxy.protocol)) return null;
-    return proxy;
-  } catch {
-    return null;
-  }
-}
-
-function matchesNoProxy(hostname) {
-  const list = (process.env.NO_PROXY || process.env.NO_PROXY === '' ? process.env.NO_PROXY : process.env.no_proxy) || '';
-  if (!list) return false;
-  return list
-    .split(',')
-    .map((s) => s.trim().toLowerCase())
-    .filter(Boolean)
-    .some((entry) => {
-      if (entry === '*') return true;
-      if (entry.startsWith('.')) return hostname.endsWith(entry);
-      return hostname === entry || hostname.endsWith(`.${entry}`);
-    });
-}
-
-// http 目标 + http 代理：向代理发绝对 URI 的 GET。
-// https 目标 + 任意代理：先 CONNECT 隧道再在隧道上发 GET。
-function request(targetURL, { headers = {}, timeoutMs = 120000 } = {}) {
-  return new Promise((resolve, reject) => {
-    let url;
-    try {
-      url = new URL(targetURL);
-    } catch (err) {
-      reject(new Error(`invalid URL: ${targetURL}`));
-      return;
-    }
-    const proxy = proxyFromEnv(targetURL);
-
-    const onConnectError = (err) =>
-      reject(new Error(`proxy connect failed: ${err.message}`));
-
-    if (url.protocol === 'https:' && proxy) {
-      const proxyPort = Number(proxy.port) || (proxy.protocol === 'https:' ? 443 : 80);
-      const connectReq = http.request({
-        host: proxy.hostname,
-        port: proxyPort,
-        method: 'CONNECT',
-        path: `${url.hostname}:${url.port || 443}`,
-        headers: { Host: `${url.hostname}:${url.port || 443}` },
-        timeout: timeoutMs,
-      });
-      connectReq.on('connect', (res, socket) => {
-        if (res.statusCode !== 200) {
-          socket.destroy();
-          reject(new Error(`proxy CONNECT failed: ${res.statusCode}`));
-          return;
-        }
-        const agent = new https.Agent({ ...KEEP_ALIVE_AGENT_OPTIONS, socket });
-        const req = https.get(
-          {
-            host: url.hostname,
-            port: url.port || 443,
-            path: url.pathname + url.search,
-            headers,
-            agent,
-            timeout: timeoutMs,
-          },
-          resolve,
-        );
-        req.on('timeout', () => {
-          req.destroy(new Error(`request timed out after ${timeoutMs}ms`));
-        });
-        req.on('error', reject);
-      });
-      connectReq.on('error', onConnectError);
-      connectReq.on('timeout', () => {
-        connectReq.destroy(new Error(`proxy connect timed out after ${timeoutMs}ms`));
-      });
-      connectReq.end();
-      return;
-    }
-
-    const isHttps = url.protocol === 'https:';
-    const mod = isHttps ? https : http;
-    const options = {
-      host: proxy ? proxy.hostname : url.hostname,
-      port: proxy
-        ? Number(proxy.port) || (proxy.protocol === 'https:' ? 443 : 80)
-        : Number(url.port) || (isHttps ? 443 : 80),
-      method: 'GET',
-      path: proxy ? targetURL : url.pathname + url.search,
-      headers,
-      timeout: timeoutMs,
-    };
-    // https 代理入口（少见于内网）不支持时直接报错，不做二次降级。
-    if (proxy && proxy.protocol === 'https:') {
-      reject(new Error('https proxy entry is not supported'));
-      return;
-    }
-    const req = mod.get(options, resolve);
-    req.on('timeout', () => {
-      req.destroy(new Error(`request timed out after ${timeoutMs}ms`));
-    });
-    req.on('error', reject);
-  });
-}
-
-function checkStatus(res, what) {
-  if (res.statusCode < 200 || res.statusCode >= 300) {
-    res.resume();
-    throw new Error(`${what} failed: HTTP ${res.statusCode} ${res.statusMessage || ''}`.trim());
-  }
-  return res;
-}
-
-async function fetchText(url, { timeoutMs = 10000 } = {}) {
-  const res = checkStatus(await request(url, { timeoutMs }), `fetch ${url}`);
-  const chunks = [];
-  for await (const chunk of res) chunks.push(chunk);
-  return Buffer.concat(chunks).toString('utf8');
-}
-
-// 流式下载到可写流，返回 { statusCode 后已校验的响应流 }。
-// onProgress(bytesDone, totalOrNull) 仅在有内容时回调。
-function downloadToStream(url, dest, { timeoutMs = 300000, onProgress } = {}) {
-  return new Promise(async (resolve, reject) => {
-    let res;
-    try {
-      res = await request(url, { timeoutMs });
-      checkStatus(res, `download ${url}`);
-    } catch (err) {
-      reject(err);
-      return;
-    }
-    const total = Number(res.headers['content-length']) || null;
-    let done = 0;
-    let lastTick = 0;
-    res.on('data', (chunk) => {
-      done += chunk.length;
-      const now = Date.now();
-      if (onProgress && (now - lastTick > 200 || done === total)) {
-        lastTick = now;
-        onProgress(done, total);
-      }
-    });
-    res.on('error', reject);
-    dest.on('error', reject);
-    res.pipe(dest);
-    dest.on('finish', () => resolve());
-  });
-}
-
-module.exports = { request, fetchText, downloadToStream };
+'use strict';
+
+// 零依赖 HTTP 客户端：Node 自带 fetch（undici）不认 http_proxy/https_proxy
+// 环境变量，内网代理场景必须自己处理。支持：
+//   - 直连 http/https
+//   - http_proxy / https_proxy / HTTP_PROXY / HTTPS_PROXY
+//   - NO_PROXY（逗号分隔主机名，支持后缀匹配）
+//   - https over proxy：CONNECT 隧道
+// 流式响应，供下载侧边收边算 sha256。
+
+const http = require('http');
+const https = require('https');
+const { URL } = require('url');
+
+const KEEP_ALIVE_AGENT_OPTIONS = { keepAlive: false };
+
+function proxyFromEnv(targetURL) {
+  const url = new URL(targetURL);
+  if (matchesNoProxy(url.hostname)) return null;
+  const proto = url.protocol === 'https:' ? 'https' : 'http';
+  const raw =
+    process.env[`${proto}_proxy`] || process.env[`${proto}_PROXY`] || '';
+  if (!raw) return null;
+  try {
+    const proxy = new URL(raw);
+    if (!/^https?:$/.test(proxy.protocol)) return null;
+    return proxy;
+  } catch {
+    return null;
+  }
+}
+
+function matchesNoProxy(hostname) {
+  const list = (process.env.NO_PROXY || process.env.NO_PROXY === '' ? process.env.NO_PROXY : process.env.no_proxy) || '';
+  if (!list) return false;
+  return list
+    .split(',')
+    .map((s) => s.trim().toLowerCase())
+    .filter(Boolean)
+    .some((entry) => {
+      if (entry === '*') return true;
+      if (entry.startsWith('.')) return hostname.endsWith(entry);
+      return hostname === entry || hostname.endsWith(`.${entry}`);
+    });
+}
+
+// http 目标 + http 代理：向代理发绝对 URI 的 GET。
+// https 目标 + 任意代理：先 CONNECT 隧道再在隧道上发 GET。
+function request(targetURL, { headers = {}, timeoutMs = 120000 } = {}) {
+  return new Promise((resolve, reject) => {
+    let url;
+    try {
+      url = new URL(targetURL);
+    } catch (err) {
+      reject(new Error(`invalid URL: ${targetURL}`));
+      return;
+    }
+    const proxy = proxyFromEnv(targetURL);
+
+    const onConnectError = (err) =>
+      reject(new Error(`proxy connect failed: ${err.message}`));
+
+    if (url.protocol === 'https:' && proxy) {
+      const proxyPort = Number(proxy.port) || (proxy.protocol === 'https:' ? 443 : 80);
+      const connectReq = http.request({
+        host: proxy.hostname,
+        port: proxyPort,
+        method: 'CONNECT',
+        path: `${url.hostname}:${url.port || 443}`,
+        headers: { Host: `${url.hostname}:${url.port || 443}` },
+        timeout: timeoutMs,
+      });
+      connectReq.on('connect', (res, socket) => {
+        if (res.statusCode !== 200) {
+          socket.destroy();
+          reject(new Error(`proxy CONNECT failed: ${res.statusCode}`));
+          return;
+        }
+        const agent = new https.Agent({ ...KEEP_ALIVE_AGENT_OPTIONS, socket });
+        const req = https.get(
+          {
+            host: url.hostname,
+            port: url.port || 443,
+            path: url.pathname + url.search,
+            headers,
+            agent,
+            timeout: timeoutMs,
+          },
+          resolve,
+        );
+        req.on('timeout', () => {
+          req.destroy(new Error(`request timed out after ${timeoutMs}ms`));
+        });
+        req.on('error', reject);
+      });
+      connectReq.on('error', onConnectError);
+      connectReq.on('timeout', () => {
+        connectReq.destroy(new Error(`proxy connect timed out after ${timeoutMs}ms`));
+      });
+      connectReq.end();
+      return;
+    }
+
+    const isHttps = url.protocol === 'https:';
+    const mod = isHttps ? https : http;
+    const options = {
+      host: proxy ? proxy.hostname : url.hostname,
+      port: proxy
+        ? Number(proxy.port) || (proxy.protocol === 'https:' ? 443 : 80)
+        : Number(url.port) || (isHttps ? 443 : 80),
+      method: 'GET',
+      path: proxy ? targetURL : url.pathname + url.search,
+      headers,
+      timeout: timeoutMs,
+    };
+    // https 代理入口（少见于内网）不支持时直接报错，不做二次降级。
+    if (proxy && proxy.protocol === 'https:') {
+      reject(new Error('https proxy entry is not supported'));
+      return;
+    }
+    const req = mod.get(options, resolve);
+    req.on('timeout', () => {
+      req.destroy(new Error(`request timed out after ${timeoutMs}ms`));
+    });
+    req.on('error', reject);
+  });
+}
+
+function checkStatus(res, what) {
+  if (res.statusCode < 200 || res.statusCode >= 300) {
+    res.resume();
+    throw new Error(`${what} failed: HTTP ${res.statusCode} ${res.statusMessage || ''}`.trim());
+  }
+  return res;
+}
+
+async function fetchText(url, { timeoutMs = 10000 } = {}) {
+  const res = checkStatus(await request(url, { timeoutMs }), `fetch ${url}`);
+  const chunks = [];
+  for await (const chunk of res) chunks.push(chunk);
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+// 流式下载到可写流，返回 { statusCode 后已校验的响应流 }。
+// onProgress(bytesDone, totalOrNull) 仅在有内容时回调。
+function downloadToStream(url, dest, { timeoutMs = 300000, onProgress } = {}) {
+  return new Promise(async (resolve, reject) => {
+    let res;
+    try {
+      res = await request(url, { timeoutMs });
+      checkStatus(res, `download ${url}`);
+    } catch (err) {
+      reject(err);
+      return;
+    }
+    const total = Number(res.headers['content-length']) || null;
+    let done = 0;
+    let lastTick = 0;
+    res.on('data', (chunk) => {
+      done += chunk.length;
+      const now = Date.now();
+      if (onProgress && (now - lastTick > 200 || done === total)) {
+        lastTick = now;
+        onProgress(done, total);
+      }
+    });
+    res.on('error', reject);
+    dest.on('error', reject);
+    res.pipe(dest);
+    dest.on('finish', () => resolve());
+  });
+}
+
+module.exports = { request, fetchText, downloadToStream };