@agile-team/robot-cli 3.0.2 → 3.0.4

package/CHANGELOG.md

@@ -5,6 +5,30 @@ 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.4] - 2026-03-29
+
+### Changed (Breaking)
+
+- **彻底重写下载策略 — `git clone --depth=1` 作为主方案**
+  - 根本原因分析：HTTP ZIP 下载受到国内网络封锁、Gitee 登录拦截、Content-Type 不一致等各种干扰，是错误的技术路线
+  - `git clone --depth=1` 是 create-vue / create-vite / degit / giget 等所有主流 CLI 的底层实现
+  - 自动继承用户系统级 git 代理配置 (`http.proxy` / `https.proxy`)，无需 CLI 工具自己处理网络问题
+  - 实时显示 git 进度条（解析 git stderr 百分比输出）
+  - 无超时问题：git 自己管理连接，有数据在流就不断
+  - 无 ZIP 解析问题：直接输出目录结构
+
+- **优先顺序**：Gitee git clone（国内快）→ GitHub git clone → HTTP ZIP 兜底（仅当系统无 git 时）
+
+- **缓存前置**：启动时先检查缓存，命中则直接用，不发起任何网络请求
+
+## [3.0.3] - 2026-03-29
+
+### Fixed
+
+- **根治下载超时的真正根因** — `AbortSignal.timeout(ms)` 是总时限（含 body 流式下载），大文件（10-20MB）在国内网络 30 秒内根本下不完，必然中断
+  - 改用 `AbortController` + 手动 `clearTimeout`：只对"连接建立/收到响应头"计时（30s），一旦连接成功立即取消计时器，body 流式下载不再受任何时间限制
+  - 与 v1.x 的 `node-fetch` `timeout` 行为完全一致（活跃超时，而非总时限）
+
 ## [3.0.2] - 2026-03-29
 
 ### Fixed

package/dist/index.js

@@ -18,6 +18,7 @@ import { execSync as execSync2 } from "child_process";
 import fs from "fs-extra";
 import path from "path";
 import os from "os";
+import { spawn } from "child_process";
 import chalk from "chalk";
 import extract from "extract-zip";
 
@@ -404,18 +405,21 @@ function buildDownloadSources(repoUrl, branch, giteeUrl) {
   }
   return sources;
 }
-async function fetchWithRetry(downloadUrl, timeout, retries, extraHeaders) {
+async function fetchWithRetry(downloadUrl, connectionTimeoutMs, retries, extraHeaders) {
   let lastError;
   for (let attempt = 1; attempt <= retries; attempt++) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), connectionTimeoutMs);
     try {
       const response = await fetch(downloadUrl, {
-        signal: AbortSignal.timeout(timeout),
+        signal: controller.signal,
         redirect: "follow",
         headers: {
           "User-Agent": "Robot-CLI/3.0",
           ...extraHeaders
         }
       });
+      clearTimeout(timer);
       if (!response.ok) {
         if (response.status === 404) throw new Error(`\u4ED3\u5E93\u4E0D\u5B58\u5728 (404)`);
         throw new Error(`HTTP ${response.status}`);
@@ -426,6 +430,7 @@ async function fetchWithRetry(downloadUrl, timeout, retries, extraHeaders) {
       }
       return response;
     } catch (error) {
+      clearTimeout(timer);
       lastError = error;
       if (lastError.message.includes("404")) throw lastError;
       if (attempt < retries) {
@@ -478,6 +483,43 @@ function assertZipBuffer(buffer, sourceName) {
     );
   }
 }
+async function gitCloneTemplate(repoUrl, branch, targetDir, spinner) {
+  return new Promise((resolve, reject) => {
+    if (spinner) spinner.text = `\u8FDE\u63A5\u4E2D...`;
+    const args = [
+      "clone",
+      "--depth=1",
+      "--single-branch",
+      "--branch",
+      branch,
+      repoUrl,
+      targetDir
+    ];
+    const proc = spawn("git", args, { stdio: ["ignore", "ignore", "pipe"] });
+    proc.stderr?.on("data", (chunk) => {
+      if (!spinner) return;
+      const text3 = chunk.toString();
+      const pctMatch = text3.match(/(\d+)%\s*\((\d+)\/(\d+)\)/);
+      if (pctMatch) {
+        const pct = parseInt(pctMatch[1]);
+        const filled = Math.round(pct / 5);
+        const bar = "\u2588".repeat(filled) + "\u2591".repeat(20 - filled);
+        const speed = text3.match(/([\d.]+\s*[KMG]iB\/s)/)?.[1] ?? "";
+        spinner.text = `\u4E0B\u8F7D\u4E2D [${bar}] ${pct}%${speed ? "  " + speed : ""}`;
+      } else {
+        const line = text3.split(/\r?\n/).find((l) => l.trim())?.trim() ?? "";
+        if (line && line.length < 80) spinner.text = `\u514B\u9686\u4E2D... ${line}`;
+      }
+    });
+    proc.on("error", (err) => {
+      reject(new Error(err.code === "ENOENT" ? "GIT_NOT_FOUND" : `git \u542F\u52A8\u5931\u8D25: ${err.message}`));
+    });
+    proc.on("close", (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`git clone \u5931\u8D25 (exit ${code})`));
+    });
+  });
+}
 async function downloadTemplate(template, options = {}) {
   const { spinner, noCache, giteeUrl: optGiteeUrl } = options;
   const branch = template.branch || "main";
@@ -485,15 +527,56 @@ async function downloadTemplate(template, options = {}) {
   if (!template?.repoUrl) {
     throw new Error(`\u6A21\u677F\u914D\u7F6E\u65E0\u6548: ${JSON.stringify(template)}`);
   }
+  if (!noCache) {
+    const cached = await getCachedTemplate(template.repoUrl);
+    if (cached) {
+      if (spinner) spinner.text = "\u5DF2\u4F7F\u7528\u7F13\u5B58\u6A21\u677F\uFF0C\u5982\u9700\u66F4\u65B0\u8BF7\u8FD0\u884C robot cache clear";
+      return cached;
+    }
+  }
+  const cloneSources = [];
+  if (giteeUrl) cloneSources.push({ url: giteeUrl, name: "Gitee" });
+  cloneSources.push({ url: template.repoUrl, name: "GitHub" });
+  let noGit = false;
+  const cloneErrors = [];
+  for (const { url: cloneUrl, name: srcName } of cloneSources) {
+    const tempDir = path.join(os.tmpdir(), `robot-git-${Date.now()}`);
+    try {
+      if (spinner) spinner.text = `\u8FDE\u63A5 ${srcName}...`;
+      await gitCloneTemplate(cloneUrl, branch, tempDir, spinner);
+      await fs.remove(path.join(tempDir, ".git")).catch(() => {
+      });
+      if (spinner) spinner.text = "\u9A8C\u8BC1\u6A21\u677F\u5B8C\u6574\u6027...";
+      if (!fs.existsSync(path.join(tempDir, "package.json"))) {
+        throw new Error("\u6A21\u677F\u7F3A\u5C11 package.json");
+      }
+      if (!noCache) saveToCache(template.repoUrl, tempDir, branch).catch(() => {
+      });
+      if (spinner) spinner.text = `\u6A21\u677F\u4E0B\u8F7D\u5B8C\u6210 (${srcName})`;
+      return tempDir;
+    } catch (err) {
+      await fs.remove(tempDir).catch(() => {
+      });
+      const msg = err.message;
+      if (msg === "GIT_NOT_FOUND") {
+        noGit = true;
+        break;
+      }
+      cloneErrors.push(`${srcName}: ${msg}`);
+      if (spinner) spinner.text = `${srcName} \u514B\u9686\u5931\u8D25\uFF0C\u5C1D\u8BD5\u4E0B\u4E00\u4E2A\u6E90...`;
+      await new Promise((r) => setTimeout(r, 500));
+    }
+  }
+  if (noGit && spinner) spinner.text = "\u7CFB\u7EDF\u672A\u5B89\u88C5 git\uFF0C\u5207\u6362\u5230 HTTP \u4E0B\u8F7D...";
   try {
-    if (spinner) spinner.text = "\u5F00\u59CB\u4E0B\u8F7D\u6700\u65B0\u6A21\u677F...";
+    if (spinner) spinner.text = "HTTP \u4E0B\u8F7D\u6A21\u677F\u4E2D...";
     const { response, sourceName } = await tryDownload(
       template.repoUrl,
       branch,
       spinner,
       giteeUrl
     );
-    if (spinner) spinner.text = "\u4FDD\u5B58\u4E0B\u8F7D\u6587\u4EF6...";
+    if (spinner) spinner.text = "\u4FDD\u5B58\u6587\u4EF6...";
     const timestamp = Date.now();
     const tempZip = path.join(os.tmpdir(), `robot-template-${timestamp}.zip`);
     const tempExtract = path.join(os.tmpdir(), `robot-extract-${timestamp}`);
@@ -513,7 +596,7 @@ async function downloadTemplate(template, options = {}) {
         const bar = "\u2588".repeat(filled) + "\u2591".repeat(20 - filled);
         const sizeMB = (received / 1024 / 1024).toFixed(1);
         const totalMB = (totalSize / 1024 / 1024).toFixed(1);
-        spinner.text = `\u4E0B\u8F7D\u4E2D [${bar}] ${pct}% ${sizeMB}MB/${totalMB}MB (${sourceName})`;
+        spinner.text = `\u4E0B\u8F7D\u4E2D [${bar}] ${pct}% ${sizeMB}/${totalMB}MB (${sourceName})`;
       }
       const buffer = Buffer.concat(chunks);
       assertZipBuffer(buffer, sourceName);
@@ -525,59 +608,48 @@ async function downloadTemplate(template, options = {}) {
     }
     if (spinner) spinner.text = "\u89E3\u538B\u6A21\u677F\u6587\u4EF6...";
     await extract(tempZip, { dir: tempExtract });
-    if (spinner) spinner.text = "\u67E5\u627E\u9879\u76EE\u7ED3\u6784...";
     const extractedItems = await fs.readdir(tempExtract);
     const repoName = template.repoUrl.split("/").pop() || "";
     const projectDir = extractedItems.find(
       (item) => item === `${repoName}-${branch}` || item.endsWith(`-${branch}`) || item.endsWith("-main") || item.endsWith("-master") || item === repoName
     );
     if (!projectDir) {
-      throw new Error(
-        `\u89E3\u538B\u540E\u627E\u4E0D\u5230\u9879\u76EE\u76EE\u5F55\uFF0C\u53EF\u7528\u76EE\u5F55: ${extractedItems.join(", ")}`
-      );
+      throw new Error(`\u89E3\u538B\u540E\u627E\u4E0D\u5230\u9879\u76EE\u76EE\u5F55\uFF0C\u53EF\u7528\u76EE\u5F55: ${extractedItems.join(", ")}`);
     }
     const sourcePath = path.join(tempExtract, projectDir);
-    if (spinner) spinner.text = "\u9A8C\u8BC1\u6A21\u677F\u5B8C\u6574\u6027...";
     if (!fs.existsSync(path.join(sourcePath, "package.json"))) {
       throw new Error("\u6A21\u677F\u7F3A\u5C11 package.json \u6587\u4EF6");
     }
-    if (!noCache) {
-      saveToCache(template.repoUrl, sourcePath, branch).catch(() => {
-      });
-    }
-    if (spinner) spinner.text = `\u6A21\u677F\u4E0B\u8F7D\u5B8C\u6210 (via ${sourceName})`;
+    if (!noCache) saveToCache(template.repoUrl, sourcePath, branch).catch(() => {
+    });
+    if (spinner) spinner.text = `\u6A21\u677F\u4E0B\u8F7D\u5B8C\u6210 (HTTP/${sourceName})`;
     await fs.remove(tempZip).catch(() => {
     });
     return sourcePath;
-  } catch (downloadError) {
+  } catch (httpError) {
     if (!noCache) {
       const cached = await getCachedTemplate(template.repoUrl);
       if (cached) {
         if (spinner) spinner.text = "\u7F51\u7EDC\u4E0D\u53EF\u7528\uFF0C\u4F7F\u7528\u7F13\u5B58\u6A21\u677F...";
-        console.log();
-        console.log(`  ${chalk.yellow("  \u6CE8\u610F: \u4F7F\u7528\u7F13\u5B58\u7248\u672C\uFF08\u975E\u6700\u65B0\uFF09")}`);
+        console.log(`
+  ${chalk.yellow("\u6CE8\u610F: \u5DF2\u4F7F\u7528\u7F13\u5B58\u7248\u672C\uFF08\u975E\u6700\u65B0\uFF09")}`);
         return cached;
       }
     }
     try {
       const tmpFiles = await fs.readdir(os.tmpdir());
       for (const f of tmpFiles.filter(
-        (x) => x.includes("robot-template-") || x.includes("robot-extract-")
+        (x) => x.includes("robot-template-") || x.includes("robot-extract-") || x.includes("robot-git-")
       )) {
         await fs.remove(path.join(os.tmpdir(), f)).catch(() => {
         });
       }
     } catch {
     }
-    const errMsg = downloadError.message;
-    const isTimeout = errMsg.includes("aborted") || errMsg.includes("timeout") || downloadError.name === "TimeoutError";
-    let msg = `\u6A21\u677F\u4E0B\u8F7D\u5931\u8D25: ${errMsg}`;
-    if (isTimeout) {
-      msg += "\n\n  \u5EFA\u8BAE:\n  1. \u5F53\u524D\u7F51\u7EDC\u8FDE\u63A5\u8F83\u6162\uFF0C\u8BF7\u7A0D\u540E\u91CD\u8BD5\n  2. \u5982\u679C\u5728\u56FD\u5185\uFF0C\u5C1D\u8BD5\u4F7F\u7528\u4EE3\u7406\u6216\u79D1\u5B66\u4E0A\u7F51\n  3. \u4F7F\u7528 robot doctor \u68C0\u67E5\u7F51\u7EDC\u8FDE\u63A5";
-    } else if (downloadError.code === "ENOTFOUND") {
-      msg += "\n\n  \u5EFA\u8BAE:\n  1. \u68C0\u67E5\u7F51\u7EDC\u8FDE\u63A5\u662F\u5426\u6B63\u5E38\n  2. \u5982\u679C\u5728\u56FD\u5185\uFF0C\u5C1D\u8BD5\u4F7F\u7528\u4EE3\u7406\n  3. \u7A0D\u540E\u91CD\u8BD5";
-    }
-    throw new Error(msg);
+    const errMsg = httpError.message;
+    const allErrors = [...cloneErrors, `HTTP: ${errMsg}`].map((e) => `  - ${e}`).join("\n");
+    throw new Error(`\u6A21\u677F\u4E0B\u8F7D\u5931\u8D25\uFF0C\u6240\u6709\u65B9\u5F0F\u5747\u4E0D\u53EF\u7528:
+${allErrors}`);
   }
 }
 

package/package.json

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