@agile-team/robot-cli 3.0.0 → 3.0.2

package/CHANGELOG.md

@@ -5,6 +5,28 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [3.0.2] - 2026-03-29
+
+### Fixed
+
+- **根治 ZIP 下载内容校验问题** — 新增两层防护:
+  1. `Content-Type` 检测: 若服务器返回 `text/html`（登录页/CAPTCHA/跳转页）立即报错，`tryDownload` 自动切换到下一个源（codeload CDN → GitHub API → github.com）
+  2. ZIP 魔术字节校验 (`PK 50 4B`): 写入磁盘前检查 buffer 头部，若不是合法 ZIP 抛出含内容预览的可读错误，而非让 `extract-zip` 报 `end of central directory record signature not found`
+
+## [3.0.1] - 2026-03-28
+
+### Fixed
+
+- **下载策略全面重写** — 参考 giget (unjs/giget, 306k+ 项目使用) 的下载方式:
+  - Gitee 备用源提升为首选 (国内用户最快)
+  - 使用 `codeload.github.com` 直连 CDN 替代 `github.com/archive/` (跳过 302 重定向)
+  - 使用 `api.github.com` REST API 作为二级备选 (与 giget 一致)
+  - `github.com` 原始链接降为最后兜底
+- **移除不稳定第三方镜像** — 移除 `hub.gitmirror.com` 和 `ghproxy.net` (不可控第三方代理)
+- **超时优化** — 快速源 (Gitee/codeload) 30s, 慢速源 (API/github.com) 60s, 不再需要 120s
+- **重试缩减** — 每源 2 次重试 (原 3 次), 退避时间 1s/2s (原 2s/4s), 快速失败切换下一源
+- **错误信息增强** — 失败时列出每个源的具体错误原因
+
 ## [3.0.0] - 2026-03-28
 
 ### ⚠️ BREAKING CHANGES

package/dist/index.js

@@ -266,12 +266,29 @@ var START_COMMAND_MAP = {
 // src/download.ts
 var CACHE_DIR = path.join(os.homedir(), ".robot-cli", CACHE_DIR_NAME);
 var CACHE_INDEX_PATH = path.join(CACHE_DIR, "index.json");
+function parseGitHubRepo(repoUrl) {
+  try {
+    const url = new URL(repoUrl);
+    if (url.hostname !== "github.com") return null;
+    const parts = url.pathname.replace(/^\/|\/$/g, "").split("/");
+    if (parts.length >= 2) return { owner: parts[0], repo: parts[1] };
+    return null;
+  } catch {
+    return null;
+  }
+}
 function buildDownloadUrl(repoUrl, branch = "main") {
   try {
     const url = new URL(repoUrl);
     const host = url.hostname;
     const cleanUrl = repoUrl.replace(/\/+$/, "");
-    if (host === "github.com") return `${cleanUrl}/archive/refs/heads/${branch}.zip`;
+    if (host === "github.com") {
+      const gh = parseGitHubRepo(cleanUrl);
+      if (gh) return `https://codeload.github.com/${gh.owner}/${gh.repo}/zip/refs/heads/${branch}`;
+      return `${cleanUrl}/archive/refs/heads/${branch}.zip`;
+    }
+    if (host === "codeload.github.com") return `${cleanUrl}/zip/refs/heads/${branch}`;
+    if (host === "api.github.com") return cleanUrl;
     if (host === "gitee.com")
       return `${cleanUrl}/repository/archive/${branch}.zip`;
     if (host === "gitlab.com") {
@@ -343,76 +360,123 @@ async function getCacheStats() {
 async function clearCache() {
   await fs.remove(CACHE_DIR);
 }
-var TIMEOUT_PRIMARY = 12e4;
-var TIMEOUT_MIRROR = 6e4;
-var MAX_RETRIES = 3;
-function getGitHubMirrors(repoUrl, giteeUrl) {
-  const mirrors = [
-    repoUrl,
-    // 1. 原始 GitHub
-    repoUrl.replace("github.com", "hub.gitmirror.com"),
-    // 2. gitmirror
-    `https://ghproxy.net/${repoUrl}`
-    // 3. ghproxy.net
-  ];
-  if (giteeUrl) mirrors.push(giteeUrl);
-  return mirrors;
+var TIMEOUT_FAST = 3e4;
+var TIMEOUT_SLOW = 6e4;
+var MAX_RETRIES = 2;
+function buildDownloadSources(repoUrl, branch, giteeUrl) {
+  const sources = [];
+  const gh = parseGitHubRepo(repoUrl);
+  if (giteeUrl) {
+    sources.push({
+      url: giteeUrl,
+      name: "gitee.com",
+      timeout: TIMEOUT_FAST
+    });
+  }
+  if (gh) {
+    sources.push({
+      url: `https://codeload.github.com/${gh.owner}/${gh.repo}/zip/refs/heads/${branch}`,
+      name: "codeload.github.com",
+      timeout: TIMEOUT_FAST,
+      isDirect: true
+    });
+    sources.push({
+      url: `https://api.github.com/repos/${gh.owner}/${gh.repo}/zipball/${branch}`,
+      name: "api.github.com",
+      timeout: TIMEOUT_SLOW,
+      isDirect: true,
+      headers: {
+        Accept: "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28"
+      }
+    });
+    sources.push({
+      url: repoUrl,
+      name: "github.com",
+      timeout: TIMEOUT_SLOW
+    });
+  } else {
+    sources.push({
+      url: repoUrl,
+      name: new URL(repoUrl).hostname,
+      timeout: TIMEOUT_SLOW
+    });
+  }
+  return sources;
 }
-async function fetchWithRetry(downloadUrl, timeout, retries) {
+async function fetchWithRetry(downloadUrl, timeout, retries, extraHeaders) {
   let lastError;
   for (let attempt = 1; attempt <= retries; attempt++) {
     try {
       const response = await fetch(downloadUrl, {
         signal: AbortSignal.timeout(timeout),
-        headers: { "User-Agent": "Robot-CLI" }
+        redirect: "follow",
+        headers: {
+          "User-Agent": "Robot-CLI/3.0",
+          ...extraHeaders
+        }
       });
       if (!response.ok) {
         if (response.status === 404) throw new Error(`\u4ED3\u5E93\u4E0D\u5B58\u5728 (404)`);
         throw new Error(`HTTP ${response.status}`);
       }
+      const ct = response.headers.get("content-type") ?? "";
+      if (ct.includes("text/html")) {
+        throw new Error(`\u6536\u5230 HTML \u54CD\u5E94\u800C\u975E ZIP \u6587\u4EF6\uFF08\u8BE5\u6E90\u53EF\u80FD\u9700\u8981\u8BA4\u8BC1\uFF09`);
+      }
       return response;
     } catch (error) {
       lastError = error;
       if (lastError.message.includes("404")) throw lastError;
       if (attempt < retries) {
-        await new Promise((r) => setTimeout(r, 2e3 * attempt));
+        await new Promise((r) => setTimeout(r, 1e3 * attempt));
       }
     }
   }
   throw lastError;
 }
 async function tryDownload(repoUrl, branch = "main", spinner, giteeUrl) {
-  const url = new URL(repoUrl);
-  const host = url.hostname;
-  const mirrors = host === "github.com" ? getGitHubMirrors(repoUrl, giteeUrl) : [repoUrl];
-  for (let i = 0; i < mirrors.length; i++) {
-    const current = mirrors[i];
-    const isOriginal = i === 0;
-    let sourceName;
-    try {
-      sourceName = isOriginal ? host : new URL(current.replace(/^(https?:\/\/[^/]+)\/.*/, "$1")).hostname;
-    } catch {
-      sourceName = `\u955C\u50CF ${i}`;
-    }
+  const sources = buildDownloadSources(repoUrl, branch, giteeUrl);
+  const errors = [];
+  for (let i = 0; i < sources.length; i++) {
+    const source = sources[i];
     try {
-      if (spinner) spinner.text = `\u8FDE\u63A5 ${sourceName} ...`;
-      const downloadUrl = current.endsWith(".zip") ? current : buildDownloadUrl(current, branch);
-      const timeout = isOriginal ? TIMEOUT_PRIMARY : TIMEOUT_MIRROR;
-      if (spinner) spinner.text = `\u4ECE ${sourceName} \u4E0B\u8F7D\u6A21\u677F (\u6700\u591A\u91CD\u8BD5${MAX_RETRIES}\u6B21)...`;
-      const response = await fetchWithRetry(downloadUrl, timeout, MAX_RETRIES);
+      if (spinner) spinner.text = `\u8FDE\u63A5 ${source.name} ...`;
+      const downloadUrl = source.isDirect ? source.url : buildDownloadUrl(source.url, branch);
+      if (spinner) spinner.text = `\u4ECE ${source.name} \u4E0B\u8F7D\u6A21\u677F...`;
+      const response = await fetchWithRetry(
+        downloadUrl,
+        source.timeout,
+        MAX_RETRIES,
+        source.headers
+      );
       if (spinner) {
         const len = response.headers.get("content-length");
         const sizeInfo = len ? `${(parseInt(len) / 1024 / 1024).toFixed(1)}MB ` : "";
-        spinner.text = `\u4E0B\u8F7D\u4E2D ${sizeInfo}(${sourceName})`;
+        spinner.text = `\u4E0B\u8F7D\u4E2D ${sizeInfo}(${source.name})`;
       }
-      return { response, sourceName };
+      return { response, sourceName: source.name };
     } catch (error) {
-      if (i === mirrors.length - 1) throw error;
-      if (spinner) spinner.text = `${sourceName} \u4E0D\u53EF\u7528\uFF0C\u5207\u6362\u4E0B\u4E00\u4E2A\u6E90...`;
-      await new Promise((r) => setTimeout(r, 1e3));
+      const errMsg = error.message || String(error);
+      errors.push(`${source.name}: ${errMsg}`);
+      if (i < sources.length - 1 && spinner) {
+        spinner.text = `${source.name} \u4E0D\u53EF\u7528\uFF0C\u5207\u6362\u5230 ${sources[i + 1].name}...`;
+        await new Promise((r) => setTimeout(r, 500));
+      }
     }
   }
-  throw new Error("\u6240\u6709\u4E0B\u8F7D\u6E90\u5747\u4E0D\u53EF\u7528");
+  throw new Error(
+    `\u6240\u6709\u4E0B\u8F7D\u6E90\u5747\u4E0D\u53EF\u7528:
+${errors.map((e) => `  - ${e}`).join("\n")}`
+  );
+}
+function assertZipBuffer(buffer, sourceName) {
+  if (buffer.length < 4 || buffer[0] !== 80 || buffer[1] !== 75) {
+    const preview = buffer.slice(0, 100).toString("utf8").replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\xff]/g, "\xB7").replace(/\s+/g, " ").slice(0, 80);
+    throw new Error(
+      `${sourceName} \u8FD4\u56DE\u7684\u4E0D\u662F\u6709\u6548 ZIP \u6587\u4EF6 (\u5185\u5BB9: "${preview}")`
+    );
+  }
 }
 async function downloadTemplate(template, options = {}) {
   const { spinner, noCache, giteeUrl: optGiteeUrl } = options;
@@ -452,9 +516,11 @@ async function downloadTemplate(template, options = {}) {
         spinner.text = `\u4E0B\u8F7D\u4E2D [${bar}] ${pct}% ${sizeMB}MB/${totalMB}MB (${sourceName})`;
       }
       const buffer = Buffer.concat(chunks);
+      assertZipBuffer(buffer, sourceName);
       await fs.writeFile(tempZip, buffer);
     } else {
       const buffer = Buffer.from(await response.arrayBuffer());
+      assertZipBuffer(buffer, sourceName);
       await fs.writeFile(tempZip, buffer);
     }
     if (spinner) spinner.text = "\u89E3\u538B\u6A21\u677F\u6587\u4EF6...";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agile-team/robot-cli",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "description": "现代化项目脚手架工具，支持多技术栈快速创建项目 - 优先 bun，兼容 npm/pnpm/yarn",
   "type": "module",
   "bin": {