@noob-stupid/dsh-plugin-console 0.5.17 → 0.5.19

package/lib/server/domain/repoland.js

@@ -1,13 +1,14 @@
 // L1 · domain —— repoland.js（仓库落地：落地目录配置 / 已落地列表 / 克隆；分层 Step 4 从 lib/index.js 搬出，只搬移未改逻辑）
 // 分组见 D:\dsh\dsh-plugin-hub-plan\architecture.zh.md 三
 
-import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync, renameSync } from 'node:fs'
+import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync, renameSync, statSync } from 'node:fs'
 import { spawn } from 'node:child_process'
-import { dirname, join } from 'node:path'
+import { dirname, join, resolve } from 'node:path'
 import { homedir } from 'node:os'
 import { gitCloneCandidates } from './sources.js'
+import { archiveRepo } from './archive-source.js'
 import { execFileAsync, gitEnv, killProcessTree } from '../infra/exec.js'
-import { disposeDir, disposeNote } from '../infra/fsx.js'
+import { copyTree, disposeDir, disposeNote } from '../infra/fsx.js'
 import { dshHome, repoLandConfFile } from '../infra/paths.js'
 
 /** 仓库落地根目录（可配置，默认 ~/.dsh/repos）。 */
@@ -120,9 +121,18 @@ function summarizeCloneErrors(errors) {
   const first = errors[0]
   const tried = errors.map((e) => {
     if (e.unclean === true) return `${e.url}（残留目录被占用，已跳过重试）`
-    if (e.skipped === true) return `${e.url}（探活失败，已跳过）`
+    // archive 通道（批次 C-⑨）：把自己的失败摘要（含"下载到多少字节"）原样带出来
+    if (e.archive === true) return `${e.url}（${String(e.message ?? 'archive 通道失败').slice(0, 160)}）`
+    // 批次 B-⑦（2026-09-27）：探活失败的源现在会在**最后一轮**再试一次，文案要说清"它并没有被永久跳过"
+    if (e.deferred === true && e.timedOut !== true) return `${e.url}（探活失败的源，已在本轮末尾重试）`
+    if (e.skipped === true) return `${e.url}（探活失败，已降级到本轮末尾重试）`
     if (e.retrying === true) return `${e.url}（超时，已改用更长超时重试）`
-    if (e.timedOut === true) return `${e.url}（超时，进程已结束）`
+    if (e.timedOut === true) {
+      // 批次 B-⑧（2026-09-27）：超时到底"收到多少字节"必须写出来 —— 0 B 就是镜像只连不传（
+      // 换源即可），有字节则是真在传、只是慢（值得再等）。旧文案只有"超时"两个字，用户无法判断。
+      const bytes = Number.isFinite(Number(e.bytesReceived)) ? Number(e.bytesReceived) : null
+      return `${e.url}（超时，进程已结束${bytes === null ? '' : (bytes > 0 ? `；本次已收到 ${bytes} B` : '；本次仅收到 0 B')}）`
+    }
     return /already exists and is not an empty directory/u.test(e.message) ? `${e.url}（目录非空）` : e.url
   }).join('；')
   const detail = gitErrorDetail(first)
@@ -156,6 +166,72 @@ function waitChildExit(child, timeoutMs, pollMs = 60) {
   })
 }
 
+/** git 停滞判据（2026-09-27 加法，真机实测：ghproxy 下 **git 协议 0 B/s** 却能挂满整个超时）。
+ * 交给 git 自己判：连续 20 秒平均速率 < 1 B/s 即中止传输并报 `Operation too slow`。
+ * 这是 `-c` 全局选项，必须排在子命令 `clone` **之前**（`git -c k=v clone …`）。
+ * 效果：一个"只连不传"的源从"每个源白等 60/180 秒"变成"≈20 秒判死 → 立刻换下一个源"。 */
+const GIT_STALL_ARGS = ['-c', 'http.lowSpeedLimit=1', '-c', 'http.lowSpeedTime=20']
+
+/** 已落地仓库复用（批次 C-⑩，2026-09-27 加法）：克隆前先看 `<reposDir>/<owner>/<repo>`。
+ * 为什么：用户在「仓库落地」里已经把仓库拉到本地（reposDir，默认 ~/.dsh/repos），
+ * 安装/套装装配时再去网上拉一遍纯属浪费——本机直连不通时甚至是"白等一场空"。
+ * 命中条件：目录存在、看起来是仓库（有 .git 或 .gitmodules）、且**含 package.json**
+ * （没有 package.json 的多半是半成品/技能仓库，交给正常通道更稳）。
+ * 返回 `{ hit, path }`；deps 只为单测注入。 */
+function findLandedRepo(repo, deps = {}) {
+  const exists = deps.exists ?? existsSync
+  const list = deps.listLanded ?? listLandedRepos
+  const full = String(repo ?? '').trim().replace(/\.git$/u, '')
+  if (full === '' || !full.includes('/')) return { hit: false, path: null }
+  let landed = []
+  try { landed = list() ?? [] } catch { landed = [] }
+  const match = landed.find((r) => String(r.repo).toLowerCase() === full.toLowerCase())
+  if (match === undefined) return { hit: false, path: null }
+  try {
+    if (!exists(join(match.path, 'package.json'))) return { hit: false, path: match.path }
+  } catch {
+    return { hit: false, path: match.path }
+  }
+  return { hit: true, path: match.path }
+}
+
+/** git 克隆的默认首轮超时（2026-09-27 下调 180 秒 → 60 秒）。
+ * 为什么能降：停滞判据（GIT_STALL_ARGS）已经把"连得上但不传"这一类提前到 ≈20 秒判死，
+ * 剩下的真实传输有进度就继续跑；真正慢但**有进度**的源由 gitCloneRepo 的"同源更长超时重试"接手
+ * （只在有进度时才重试，见 measureProgressBytes）。 */
+const GIT_CLONE_TIMEOUT_MS = 60000
+
+/** 统计目录树里的文件字节数（best-effort：任何一层读不到就跳过，绝不抛）。 */
+function measureDirBytes(dir, { readdir = readdirSync, stat = statSync } = {}) {
+  let total = 0
+  const walk = (p, depth) => {
+    if (depth > 8) return
+    let entries = []
+    try { entries = readdir(p, { withFileTypes: true }) } catch { return }
+    for (const entry of entries) {
+      const child = join(p, entry.name)
+      try {
+        if (entry.isDirectory()) walk(child, depth + 1)
+        else if (entry.isFile()) total += stat(child).size
+      } catch {}
+    }
+  }
+  walk(String(dir), 0)
+  return total
+}
+
+/** 本次尝试"收到了多少字节"（2026-09-27 加法）——决定**这个源配不配用更长超时再试一次**。
+ * 真机证据：ghproxy 卡死是 0 B/s（一点进度都没有），再用 1.75 倍超时重试只是把白等拉长；
+ * 而"慢但在长"的源（比如大仓库首包）值得再给一次机会。
+ * 先量 `.git/objects`（git 边下边写 pack/tmp_pack，这里就是进度条），没有就退化成量整个目标目录。 */
+function measureProgressBytes(part, deps = {}) {
+  const exists = deps.exists ?? existsSync
+  const measure = deps.measureDir ?? measureDirBytes
+  const objects = join(String(part), '.git', 'objects')
+  const bytes = exists(objects) ? measure(objects) : 0
+  return bytes > 0 ? bytes : measure(part)
+}
+
 /** 跑一次 git clone：支持超时，且**超时即杀掉整棵树并等它真的退出**。返回 { code, stderr, timedOut, pid, exited }。 */
 function runGitClone(url, dest, timeout, { spawnFn = spawn, killTree = killProcessTree, exitWaitMs = 800, exitWaitMs2 = 300 } = {}) {
   return new Promise((resolve) => {
@@ -165,7 +241,7 @@ function runGitClone(url, dest, timeout, { spawnFn = spawn, killTree = killProce
     let child = null
     let stderr = ''
     try {
-      child = spawnFn('git', ['clone', '--depth', '1', '--quiet', url, dest], {
+      child = spawnFn('git', [...GIT_STALL_ARGS, 'clone', '--depth', '1', '--quiet', url, dest], {
         windowsHide: true,
         env: gitEnv(),
         detached: process.platform !== 'win32', // POSIX：自成进程组，便于 -pid 整体杀
@@ -192,12 +268,64 @@ function runGitClone(url, dest, timeout, { spawnFn = spawn, killTree = killProce
   })
 }
 
-/** 源探活：镜像站"连得上但传不动"探不出来，但**域名挂掉/被墙**能提前识别，省掉一整个克隆超时的白等。 */
-async function probeSourceAlive(url, timeoutMs = 4000) {
+/** git 智能 HTTP 的探活地址（批次 B-⑦②，2026-09-27 改错）：从 `HEAD /` 改成
+ * `GET <url>/info/refs?service=git-upload-pack` —— 后者是 git 协议的**真实入口**，
+ * 响应首行必须是以 4 位十六进制长度开头的 pkt-line（如 `001e# service=git-upload-pack`），
+ * 这样至少能把"根本不是 git 服务的镜像/错误页/登录页"提前滤掉（旧 HEAD 判据只验可达性）。 */
+function gitInfoRefsUrl(url) {
+  const base = String(url ?? '')
+  if (base === '') return ''
+  return `${base.replace(/\/+$/u, '')}/info/refs?service=git-upload-pack`
+}
+
+/** 探活失败的归因（纯函数，单测覆盖）：把"网络不可达"与"本地代理/证书拦截"分开。
+ * 为什么必须分开（批次 B-⑦③）：本机装了 Steam++ 这类加速器后会改 hosts / 装自签根证书，
+ * 表现是 `unable to get local issuer certificate` / `self signed certificate` —— 这种情况让用户
+ * "重试"是没用的，必须提示他关掉加速器/代理。 */
+function classifyProbeFailure(error) {
+  const text = String(error?.cause?.message ?? error?.message ?? error ?? '')
+  if (/certificate|CERT_|self[- ]signed|UNABLE_TO_VERIFY|SSL|TLS|proxy|ECONNREFUSED|ERR_PROXY/iu.test(text)) {
+    return { kind: 'intercepted', note: `本地代理/证书拦截（${text.slice(0, 90)}）—— 检测到本机加速器/代理，建议关闭后重试` }
+  }
+  return { kind: 'unreachable', note: `网络不可达（${text.slice(0, 90) || '连接失败'}）` }
+}
+
+/** 源探活（带归因）：返回 { alive, kind, status, note }。
+ * 判据（沿用旧语义 + 新增 pkt-line 校验）：
+ *   · `file://` 本地裸仓库：直接算活着（旧代码对 file:// 一律判死 → 完全离线/内网共享盘场景永远用不上）
+ *   · 403 / 405：部分镜像不支持该探测，按活着处理（老判据保留，不误杀镜像）
+ *   · 其他非 2xx：不存活（域名在但仓库/路径没了）
+ *   · 2xx：校验响应首行是 pkt-line；响应体读不到时保守地按活着处理（别误杀）
+ * `deps.fetch` 只为单测注入，生产调用不传。 */
+async function probeSourceAliveDetail(url, timeoutMs = 4000, deps = {}) {
+  const fetchFn = deps.fetch ?? fetch
+  const target = String(url ?? '')
+  if (/^file:/iu.test(target)) return { alive: true, kind: 'local', status: null, note: '本地裸仓库' }
   try {
-    const res = await fetch(url, { method: 'HEAD', redirect: 'follow', signal: AbortSignal.timeout(timeoutMs) })
-    return res.ok || res.status === 403 || res.status === 405 // 部分站点不支持 HEAD，按"活着"处理
-  } catch { return false }
+    const res = await fetchFn(gitInfoRefsUrl(target), {
+      method: 'GET',
+      redirect: 'follow',
+      headers: { accept: '*/*' },
+      signal: AbortSignal.timeout(timeoutMs),
+    })
+    if (res.status === 403 || res.status === 405) return { alive: true, kind: 'http', status: res.status, note: `HTTP ${res.status}（该镜像不支持智能 HTTP 探测，按活着处理）` }
+    if (res.ok !== true) return { alive: false, kind: 'http', status: res.status, note: `HTTP ${res.status}` }
+    let head = ''
+    try { if (typeof res.text === 'function') head = String(await res.text()).slice(0, 64) } catch {}
+    if (head === '') return { alive: true, kind: 'http', status: res.status, note: '响应体不可读，按活着处理' }
+    return /^[0-9a-f]{4}# service=git-upload-pack/u.test(head)
+      ? { alive: true, kind: 'git', status: res.status, note: '' }
+      : { alive: false, kind: 'not-git', status: res.status, note: `响应不像 git 服务（首行：${head.split(/\r?\n/u)[0].slice(0, 40)}）` }
+  } catch (error) {
+    const reason = classifyProbeFailure(error)
+    return { alive: false, kind: reason.kind, status: null, note: reason.note }
+  }
+}
+
+/** 源探活：镜像站"连得上但传不动"探不出来，但**域名挂掉/被墙/根本不是 git 服务**能提前识别，
+ * 省掉一整个克隆超时的白等。返回布尔（老签名不变；需要归因文案请用 probeSourceAliveDetail）。 */
+async function probeSourceAlive(url, timeoutMs = 4000, deps = {}) {
+  return (await probeSourceAliveDetail(url, timeoutMs, deps)).alive === true
 }
 
 /** git clone（镜像→直连；gitee 直连），返回 { url, attempt, dir, source, retried } 或抛错。
@@ -211,33 +339,67 @@ async function probeSourceAlive(url, timeoutMs = 4000) {
  * 一旦它超时就"整次安装彻底失败"——现在先重试它一次，再谈别的源）。
  * 2026-09-26（本次改错）：清理默认实现由 removeDirVerifiedWithRetry 换成 **disposeDir**
  * （删不掉就改名降级成同父目录的 `.trash-<ts>-<rand>`，见 infra/fsx.js）——残留目录不再需要用户
- * 手动删除，也不再因为"清不掉"而放弃后面本来可用的源。`deps.removeDir` 这个注入口名字没变。 */
-async function gitCloneRepo(repo, dest, source = 'github', timeout = 180000, deps = {}) {
+ * 手动删除，也不再因为"清不掉"而放弃后面本来可用的源。`deps.removeDir` 这个注入口名字没变。
+ * 2026-09-27（本次改错）：① 首轮超时 180 秒 → 60 秒（停滞判据已把"只连不传"提前到 ≈20 秒判死）；
+ *                        ② "同源 1.75 倍长超时重试"从**无条件**改成**只对"有进度"的源**——
+ *                        每个失败记录都带上 `bytesReceived`（.git/objects 落盘字节数），0 B 就说明
+ *                        这个源一点都没传，再用更长超时重试只是把白等拉长（真机 ghproxy 实测 0 B/s）。
+ * 2026-09-27（批次 B-⑦）：③ 探活判据换成 `GET <url>/info/refs?service=git-upload-pack` + pkt-line 校验，
+ *                        并把失败归因（网络不可达 / 本地代理·证书拦截）写进错误清单；
+ *                        ④ **探活失败的源不再"一次定生死"**：降级到**最后一轮**再试一次
+ *                        （探活本身可能只是瞬时抖动；真正挂掉的源也只有一次克隆的代价）。 */
+async function gitCloneRepo(repo, dest, source = 'github', timeout = GIT_CLONE_TIMEOUT_MS, deps = {}) {
   const {
     spawnFn = spawn,
     killTree = killProcessTree,
-    probe = probeSourceAlive,
+    probe = null,
+    probeDetail = null,
     removeDir = disposeDir,
     renameDir = renameSync,
     exitWaitMs = 800,
     retryFactor = 1.75,
     readMemo = readGitSourceMemo,
     writeMemo = rememberGitSource,
+    measureBytes = measureProgressBytes,
+    archive = archiveRepo,
+    archiveBranch = 'main',
+    reuseLanded = true,
+    findLanded = findLandedRepo,
+    copyLanded = copyTree,
   } = deps
+  // ★ 已落地仓库优先复用（批次 C-⑩）：命中就直接把本地那份搬到 dest，一个网络请求都不发。
+  // 跳过 .git 是有意的（copyTree 的既有语义）：上层要的是仓库**内容**（package.json/.gitmodules），
+  // 本机已有完整仓库，没必要把几百 MB 的 .git 再复制一份。
+  if (reuseLanded === true) {
+    try {
+      const landed = findLanded(repo)
+      if (landed.hit === true && landed.path !== null) {
+        if (resolve(landed.path) === resolve(dest)) {
+          return { url: `file://${landed.path}`, attempt: 0, tries: 0, dir: dest, source: 'landed', retried: false, reused: true }
+        }
+        try { removeDir(dest) } catch {}
+        copyLanded(landed.path, dest)
+        return { url: `file://${landed.path}`, attempt: 0, tries: 0, dir: dest, source: 'landed', retried: false, reused: true, from: landed.path }
+      }
+    } catch {}
+  }
+  // 兼容旧的 `deps.probe`（单测/调用方注入的布尔探活）：它优先于新的带归因探活
+  const probeOne = typeof probeDetail === 'function'
+    ? probeDetail
+    : (typeof probe === 'function'
+        ? async (url) => ({ alive: (await probe(url)) === true, kind: 'probe', status: null, note: '连不上（探活失败）' })
+        : (url) => probeSourceAliveDetail(url))
   let preferred = ''
   try { preferred = readMemo() } catch { preferred = '' }
   const candidates = orderGitCandidates(gitCloneCandidates(repo, source), preferred)
   const retryTimeout = Math.max(timeout + 1, Math.round(timeout * retryFactor))
   const errors = []
   let partSeq = 0
-  for (const [sourceIndex, cand] of candidates.entries()) {
+  const deferred = []
+  /** 试一个源（最多两轮：正常超时 → 有进度才用更长超时重试）。
+   * 返回 `{ result }` 表示克隆成功；返回 null 表示这个源用完了，继续下一个源。 */
+  const attemptSource = async (cand, sourceIndex, isDeferred) => {
     const url = cand.url
-    const alive = await probe(url)
-    if (!alive) {
-      partSeq += 1
-      errors.push({ url, message: `源探活失败（连不上）：${url}`, skipped: true, dir: `${dest}.try${partSeq}` })
-      continue
-    }
     // 同一个源最多两次：正常超时 → 更长超时重试一次
     for (let round = 0; round < 2; round += 1) {
       partSeq += 1
@@ -251,14 +413,18 @@ async function gitCloneRepo(repo, dest, source = 'github', timeout = 180000, dep
           removeDir(dest)
           renameDir(part, dest)
           try { writeMemo(cand.urlTemplate) } catch {}
-          return { url, attempt: sourceIndex + 1, tries: partSeq, dir: dest, source: cand.id, retried: round > 0 }
+          return { result: { url, attempt: sourceIndex + 1, tries: partSeq, dir: dest, source: cand.id, retried: round > 0, deferred: isDeferred } }
         } catch (error) {
-          errors.push({ url, message: `克隆成功但落地失败（${error instanceof Error ? error.message : String(error)}）`, dir: part })
-          break
+          errors.push({ url, message: `克隆成功但落地失败（${error instanceof Error ? error.message : String(error)}）`, dir: part, deferred: isDeferred })
+          return null
         }
       }
-      // 失败：先尽力清掉半成品目录（带重试的核实删除 → 删不掉则**改名降级**成 .trash-*）；
+      // 失败：先量**本次到底收到了多少字节**（决定"配不配长超时重试"，也是给用户看的事实），
+      // 再尽力清掉半成品目录（带重试的核实删除 → 删不掉则**改名降级**成 .trash-*）；
       // 只有连改名都失败才如实说明（不再谎报"环境禁止删除"，也不再让用户去命令行手动删）
+      let bytesReceived = 0
+      try { bytesReceived = measureBytes(part) } catch { bytesReceived = 0 }
+      const hasProgress = bytesReceived > 0
       const cleared = removeDir(part)
       const trashNote = cleared !== null && cleared !== undefined && typeof cleared.trashPath === 'string' && cleared.trashPath !== ''
         ? disposeNote(cleared)
@@ -276,20 +442,92 @@ async function gitCloneRepo(repo, dest, source = 'github', timeout = 180000, dep
           unclean: true,
           timedOut: res.timedOut === true,
           exited: res.exited !== false,
+          bytesReceived,
           dir: part,
+          deferred: isDeferred,
         })
-        break // 清不掉的残留和这个源绑着，换下一个源（新目录不受影响）
+        return null // 清不掉的残留和这个源绑着，换下一个源（新目录不受影响）
       }
-      if (res.timedOut === true && round === 0) {
-        // ★ 同源、更长超时，重试一次（真机：ghproxy 卡死时短超时不够，长超时能过）
-        errors.push({ url, message: `克隆超时（${useTimeout}ms），改用 ${retryTimeout}ms 同源重试`, stderr: res.stderr, timedOut: true, retrying: true, dir: part, ...trashField })
+      if (res.timedOut === true && round === 0 && hasProgress) {
+        // ★ 同源、更长超时，重试一次 —— **只对真有进度的源**（0 B 的源再等一次只是把白等拉长）
+        errors.push({ url, message: `克隆超时（${useTimeout}ms，本次已收到 ${bytesReceived} B），改用 ${retryTimeout}ms 同源重试`, stderr: res.stderr, timedOut: true, retrying: true, bytesReceived, dir: part, deferred: isDeferred, ...trashField })
         continue
       }
-      errors.push({ url, message: res.timedOut === true ? `克隆超时（${url}）` : (res.stderr !== '' ? res.stderr : `git clone 退出码 ${res.code}`), stderr: res.stderr, timedOut: res.timedOut === true, dir: part, ...trashField })
-      break
+      errors.push({
+        url,
+        message: res.timedOut === true
+          ? `克隆超时（${url}${hasProgress ? `，本次已收到 ${bytesReceived} B` : '，本次收到 0 B（无进度，不再用更长超时重试）'}）`
+          : (res.stderr !== '' ? `${res.stderr}（本次收到 ${bytesReceived} B）` : `git clone 退出码 ${res.code}（本次收到 ${bytesReceived} B）`),
+        stderr: res.stderr,
+        timedOut: res.timedOut === true,
+        bytesReceived,
+        noProgress: !hasProgress,
+        dir: part,
+        deferred: isDeferred,
+        ...trashField,
+      })
+      return null
+    }
+    return null
+  }
+  for (const [sourceIndex, cand] of candidates.entries()) {
+    // eslint-disable-next-line no-await-in-loop
+    const detail = await probeOne(cand.url)
+    if (detail.alive !== true) {
+      partSeq += 1
+      errors.push({
+        url: cand.url,
+        message: `源探活失败（${detail.note ?? '连不上'}）：${cand.url}`,
+        skipped: true,
+        probeKind: detail.kind ?? null,
+        probeNote: detail.note ?? '',
+        dir: `${dest}.try${partSeq}`,
+      })
+      deferred.push({ cand, sourceIndex })
+      continue
+    }
+    // eslint-disable-next-line no-await-in-loop
+    const done = await attemptSource(cand, sourceIndex, false)
+    if (done !== null) return done.result
+  }
+  // ★ archive 通道（批次 C-⑨，2026-09-27 加法）：git 源全部失败后，改用**普通 HTTP 下载压缩包**。
+  // 真机依据：同一个 ghproxy 域名下 archive GET 4 MB/s、git 协议 0 B/s —— 少了这一步，
+  // "git 协议被镜像掐死"就等于"这个仓库装不上"。顺序放在**探活失败的降级轮之前**：
+  // archive 是已知能跑满带宽的传输，而降级轮里的源大多是探测时就不可达的（希望更小）。
+  if (typeof archive === 'function') {
+    try {
+      const got = await archive(repo, dest, { branch: archiveBranch, ...(deps.archiveOptions ?? {}), deps: deps.archiveDeps ?? {} })
+      return {
+        url: got.url,
+        attempt: candidates.length + 1,
+        tries: partSeq + (got.tries ?? 1),
+        dir: got.dir ?? dest,
+        source: got.sourceId !== undefined && got.sourceId !== '' ? `archive:${got.sourceId}` : 'archive',
+        retried: false,
+        archive: true,
+        branch: got.branch ?? archiveBranch,
+        bytes: got.bytes ?? null,
+        gitNote: got.gitNote ?? null,
+      }
+    } catch (error) {
+      const raw = String(error?.message ?? error).replace(/\s+/gu, ' ')
+      errors.push({
+        url: `archive://${repo}`,
+        archive: true,
+        message: `archive 通道失败：${raw.slice(0, 400)}`,
+        timedOut: /超时/u.test(raw),
+        bytesReceived: 0,
+      })
     }
   }
+  // ★ 最后一轮（批次 B-⑦④）：探活失败的源降级到这里**再试一次**（不再永久跳过）。
+  // 对真挂掉的源，代价只是一次克隆（有停滞判据 + 预算封顶）；对瞬时抖动的源，这是唯一的机会。
+  for (const { cand, sourceIndex } of deferred) {
+    // eslint-disable-next-line no-await-in-loop
+    const done = await attemptSource(cand, sourceIndex, true)
+    if (done !== null) return done.result
+  }
   throw new Error(summarizeCloneErrors(errors))
 }
 
-export { reposDirCache, getReposDir, setReposDir, listLandedRepos, gitCloneRepo, summarizeCloneErrors, orderGitCandidates, readGitSourceMemo, rememberGitSource, killProcessTree, probeSourceAlive }
+export { reposDirCache, getReposDir, setReposDir, listLandedRepos, findLandedRepo, gitCloneRepo, summarizeCloneErrors, orderGitCandidates, readGitSourceMemo, rememberGitSource, killProcessTree, probeSourceAlive, probeSourceAliveDetail, gitInfoRefsUrl, classifyProbeFailure, GIT_STALL_ARGS, GIT_CLONE_TIMEOUT_MS, measureDirBytes, measureProgressBytes }

package/lib/server/domain/sources.js

@@ -80,6 +80,22 @@ function readSources() {
         return gitSources
       })()
       : defaults.gitSources
+    // archive 通道源（批次 C-⑨，2026-09-27 加法）：形状与 gitSources 一致（{owner}/{repo} 占位符，
+    // 可选 {branch}），主→备依次尝试；老配置没有该字段 → 用默认（行为与改动前一致）。
+    const archiveSources = (Array.isArray(data.archiveSources) ? data.archiveSources : [])
+      .filter((s) => s && typeof s.urlTemplate === 'string' && s.urlTemplate.includes('{owner}') && s.urlTemplate.includes('{repo}') && isAllowedGitSourceUrl(s.urlTemplate))
+      .map((s) => ({
+        id: String(s.id ?? '').slice(0, 40) || `arc-${Math.random().toString(36).slice(2, 8)}`,
+        name: String(s.name ?? s.urlTemplate).slice(0, 60) || s.urlTemplate,
+        urlTemplate: s.urlTemplate,
+        primary: s.primary === true,
+      }))
+    const archiveFinal = archiveSources.length > 0
+      ? (() => {
+        if (!archiveSources.some((s) => s.primary)) archiveSources[0].primary = true
+        return archiveSources
+      })()
+      : defaults.archiveSources
     const gitee = {
       ...giteeBase,
       clientSecret: secrets.gitee?.clientSecret ?? giteeBase.clientSecret,
@@ -87,7 +103,7 @@ function readSources() {
     }
     if (registries.length > 0) {
       if (!registries.some((r) => r.primary)) registries[0].primary = true
-      return { registries, searchSources, indexSources: indexFinal, gitSources: gitFinal, indexMerge: data.indexMerge === true, gitee }
+      return { registries, searchSources, indexSources: indexFinal, gitSources: gitFinal, archiveSources: archiveFinal, indexMerge: data.indexMerge === true, gitee }
     }
   } catch {}
   return defaults
@@ -132,6 +148,7 @@ function maskSources(sources) {
     indexSources: sources.indexSources ?? DEFAULT_SOURCES.indexSources,
     indexMerge: sources.indexMerge === true,
     gitSources: sources.gitSources ?? DEFAULT_SOURCES.gitSources,
+    archiveSources: sources.archiveSources ?? DEFAULT_SOURCES.archiveSources,
     searchSources: (sources.searchSources ?? []).map((s) => {
       if (s && typeof s.headers === 'object' && Object.keys(s.headers).length > 0) {
         const masked = {}
@@ -262,6 +279,13 @@ const DEFAULT_SOURCES = {
     { id: 'ghproxy-git', name: 'ghproxy 镜像', urlTemplate: 'https://ghproxy.net/https://github.com/{owner}/{repo}.git', primary: true },
     { id: 'github-git', name: 'GitHub 直连', urlTemplate: 'https://github.com/{owner}/{repo}.git', primary: false },
   ],
+  // archive 通道源（批次 C-⑨，2026-09-27 加法）：git 协议拉不动时的等价替代 —— 直接 HTTP 下载
+  // 仓库压缩包。真机实测：同一个 ghproxy 域名下 archive 4 MB/s、git 协议 0 B/s。
+  // {branch} 占位符可选；模板里没有它时该 URL 对任何分支都成立（由站点自己决定）。
+  archiveSources: [
+    { id: 'ghproxy-archive', name: 'ghproxy 镜像（archive）', urlTemplate: 'https://ghproxy.net/https://github.com/{owner}/{repo}/archive/refs/heads/{branch}.tar.gz', primary: true },
+    { id: 'codeload-archive', name: 'GitHub codeload', urlTemplate: 'https://codeload.github.com/{owner}/{repo}/tar.gz/refs/heads/{branch}', primary: false },
+  ],
   // 索引合并模式：true = 所有索引源结果合并去重（公共索引 + 内网私有索引同时可见）；
   // false = 主→备只用一个（内网优先，更快）
   indexMerge: false,
@@ -322,4 +346,4 @@ const GITEE_AUTH_URL = 'https://gitee.com/oauth/authorize'
 
 const GITEE_TOKEN_URL = 'https://gitee.com/oauth/token'
 const DEFAULT_SEARCH = 'dsh-plugin'
-export { readSources, writeSources, maskSources, readSourceSecrets, writeSourceSecrets, isAllowedSourceUrl, isAllowedGitSourceUrl, readGiteeConfig, giteeStatusView, orderedRegistries, createGiteeOAuthState, consumeGiteeOAuthState, DEFAULT_SOURCES, GITEE_OAUTH_STATES, gitCloneUrls, gitCloneCandidates, GITEE_AUTH_URL, GITEE_TOKEN_URL, DEFAULT_SEARCH }
+export { readSources, writeSources, maskSources, readSourceSecrets, writeSourceSecrets, isAllowedSourceUrl, isAllowedGitSourceUrl, readGiteeConfig, giteeStatusView, orderedRegistries, createGiteeOAuthState, consumeGiteeOAuthState, DEFAULT_SOURCES, GITEE_OAUTH_STATES, gitCloneUrls, gitCloneCandidates, GITEE_AUTH_URL, GITEE_TOKEN_URL, DEFAULT_SEARCH }

package/lib/server/domain/suite.js

@@ -7,8 +7,10 @@ import { tmpdir } from 'node:os'
 import { appendInsert } from './patch.js'
 import { gitCloneRepo } from './repoland.js'
 import { deriveEntryId, listEntries } from './runtime.js'
+import { noteChannel } from './git-channel.js'
+import { orderedRegistries, readSources } from './sources.js'
 import { copyTree } from '../infra/fsx.js'
-import { looksLikeGitmodules, rawTextWithFallback } from '../infra/http.js'
+import { GITHUB_API, META_BUDGET_MS, curlJson, fetchJsonUrl, githubJson, looksLikeGitmodules, rawTextWithFallback } from '../infra/http.js'
 import { dshHome, findPatchPath } from '../infra/paths.js'
 
 /** 解析 .gitmodules：返回 [{name, path, url}]（submodule 套装识别用）。 */
@@ -92,16 +94,140 @@ function resolveInstallKind(requestKind, probeText) {
   return looksLikeGitmodules(probeText) ? 'suite' : 'plugin'
 }
 
+/** 仓库元数据（默认分支）探测：githubJson 与 curlJson 竞速 + META_BUDGET_MS 降级（黑洞期不卡 40s）。
+ * 0.5.19 从 install-job.js 原样搬来（**只搬移，表达式一字未改**）：套装判定前要先读根包名
+ * （见 shouldRunSuiteInstall），这次探测的结果缓存在 job.repoMeta 上供下游复用，同一个作业不重复联网。
+ * 8s 而非旧值 3s：IPv6 无路由的环境里单条通道就要 5.4s，3s 预算必输 → branch 恒为 main，
+ * 默认分支为 dev 的仓库会取错分支（2026-09-20 另一位用户实测）。 */
+async function fetchRepoMeta(repo) {
+  const meta = await Promise.race([
+    Promise.any([
+      githubJson(`${GITHUB_API}/repos/${repo}`),
+      curlJson(`${GITHUB_API}/repos/${repo}`, 12000, {}, { ipv4: true }),
+    ]),
+    new Promise((resolve) => setTimeout(() => resolve(null), META_BUDGET_MS)),
+  ]).catch(() => null)
+  return meta ?? null
+}
+
+/** 这个包名在 registry 上**确实存在**吗？只有确定性命中才算"存在"：404 / 超时 / 不可达一律当"查不到"。
+ * 口径必须这么窄的理由：查不到不能推翻 .gitmodules 判据 —— 网络问题不该把套装安装变成插件安装。
+ * 用既有 npm 元数据能力（与 market.js 读 packument 同一套：配置里的软件源顺序 + fetchJsonUrl），
+ * 最多看前 2 个源、每源 6 秒封顶；测试用 probes.namePublished 替换（见 test-suite-fallback.mjs）。 */
+async function namePublishedOnRegistry(name) {
+  const encoded = name.startsWith('@')
+    ? `@${encodeURIComponent(name.slice(1).split('/')[0])}%2f${encodeURIComponent(name.split('/').slice(1).join('/'))}`
+    : encodeURIComponent(name)
+  for (const reg of orderedRegistries(readSources()).slice(0, 2)) {
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      const data = await fetchJsonUrl(`${reg}/${encoded}`, 6000)
+      const hasLatest = typeof data?.['dist-tags']?.latest === 'string'
+      const hasVersions = data !== null && typeof data === 'object' && data.versions !== null && typeof data.versions === 'object' && Object.keys(data.versions).length > 0
+      if (hasLatest || hasVersions) return true
+    } catch {}
+  }
+  return false
+}
+
+/** 套装判定（唯一入口，0.5.19 改错）：**先看根包是否已发布，再决定要不要按 .gitmodules 走套装**。
+ * 真机事故（2026-09-27，用户点装 zhu1090093659/dsh-web 全家桶）：市场卡片点「添加到本地」只带 owner/repo、
+ * 不带包名 → candidates=[] → 旧流程直接探 .gitmodules（该仓库根目录确实有一份）→ 第一步就 clone 整个仓库
+ * （429 MB），而真正能装上的子包 @linxin666/dsh-web-all（5.97 MB）根本没机会被尝试。
+ * 判据顺序（每一步都只做"确认"，不做"猜测"）：
+ *   ① 读根 package.json（下游本来也要读，结果缓存进 job 复用）→ 有 name 且 registry 上存在 → **插件通道**；
+ *   ② 否则按 .gitmodules **内容**判（内容不像 gitmodules 就不是套装 —— 2026-09-19 事故的口径不变）；
+ *   ③ 判成套装后再问一句 registry：根包没发布、但**子包**已发布（真机 dsh-web 就是这种）→ 插件通道。
+ *      理由：仓库里有已发布的可安装单元时，按包名装才是"装得上 + 能随 lock 更新"的那条路；
+ *      子包也都没发布（子模块是纯 git 组件）→ 照旧走套装装配，能力一点没少。
+ * 返回 true = 走套装安装。副作用：job.repoMeta / job.defaultBranch / job.rootPkgProbe / job.subpackageProbe
+ * 缓存本次探测结果，下游候选循环直接复用（install-job.js 里带 `??` 的那几行）。 */
+async function shouldRunSuiteInstall(job, probes = {}) {
+  // 同一作业只判一次：缓存下来后 install-job（判定套装分支）与套装作业入口（显式「安装套装」）
+  // 共用同一个结论，第二次调用零联网 —— 见 runSuiteInstallJob 顶部的同一道判据。
+  if (job.suiteDecision !== undefined) return job.suiteDecision
+  const decide = (value, reason) => {
+    job.suiteDecision = value
+    job.suiteDecisionReason = reason
+    return value
+  }
+  if (job.kind === 'skill') return decide(false, '技能请求不走套装通道')
+  const gmProbe = typeof probes.probeGitmodules === 'function' ? probes.probeGitmodules : probeGitmodules
+  const meta = await fetchRepoMeta(job.repo).catch(() => null)
+  job.repoMeta = meta
+  const branch = meta?.default_branch ?? 'main'
+  job.defaultBranch = branch
+  let root = null
+  if (typeof probes.fetchRepoPackageEx === 'function') {
+    // 探测异常不改变结论：回落成"按 .gitmodules 判"（旧行为），不让一次探测把安装打挂
+    try { root = await probes.fetchRepoPackageEx(job.repo, branch) } catch { root = null }
+    job.rootPkgProbe = root
+  }
+  const rootPkg = root !== null && root !== undefined && root.pkg !== null && typeof root.pkg === 'object' ? root.pkg : null
+  const name = rootPkg !== null && typeof rootPkg.name === 'string' ? rootPkg.name : ''
+  const published = async (pkgName) => (typeof probes.namePublished === 'function'
+    ? (await probes.namePublished(pkgName)) === true
+    : namePublishedOnRegistry(pkgName))
+  if (name !== '' && (await published(name)) === true) {
+    job.rootPublished = name
+    noteChannel(job, `根包 ${name} 已发布到 npm：优先插件通道（不判套装、不克隆仓库）`)
+    return decide(false, `根包 ${name} 已发布到 npm`)
+  }
+  if (resolveInstallKind(job.kind, await gmProbe(job.repo)) !== 'suite') return decide(false, '仓库根目录没有有效的 .gitmodules（不是 submodule 套装仓库）')
+  if (name !== '' && typeof probes.subpackageCandidates === 'function') {
+    let subs = []
+    try { subs = await probes.subpackageCandidates(job.repo, branch) } catch { subs = [] }
+    if (Array.isArray(subs) && subs.length > 0) {
+      job.subpackageProbe = subs
+      for (const cand of subs.slice(0, 3)) {
+        // eslint-disable-next-line no-await-in-loop
+        if ((await published(cand)) === true) {
+          job.subpackagePreferred = cand
+          noteChannel(job, `根包未发布到 npm，但子包 ${cand} 已发布：优先插件通道（跳过套装克隆，避免白拉整个仓库）`)
+          return decide(false, `根包未发布到 npm，但子包 ${cand} 已发布到 npm`)
+        }
+      }
+    }
+  }
+  return decide(true, '')
+}
+
 /** 套装安装（submodule 聚合仓库）：照仓库 install.ps1/README 语义——
  * clone 套装 → 手动镜像拉取子模块 → 按类型装配（bundle 插件含 Release tgz 兜底 / 普通插件 / 技能 / agent 预设）。
  * 不执行第三方脚本本体（安全护栏：脚本型只读语义不运行）。 */
-async function runSuiteInstallJob(job, ports) {
+async function runSuiteInstallJob(job, ports, deps = {}) {
+  // 根克隆的实现可注入（测试注入缝，沿用 runInstallJob 的 deps 风格：生产调用方不传第三个参数）
+  const gitClone = typeof deps.gitClone === 'function' ? deps.gitClone : gitCloneRepo
+  // 0.5.19：套装作业入口的**同一道判据** —— 前端 hasSuite=true 的卡片点「添加到本地」时发的是
+  // kind=suite，路由会直接调到这里（routes/install.js 的 runSuiteThenFallback），根本不经过 install-job
+  // 的候选循环；真机 dsh-web 的 429 MB 就是这条路拉起来的。判定结论缓存在 job.suiteDecision 上：
+  // install-job 已经判过（并注入过探测桩）时这里零联网直接复用；路由调用时由它把真实探测传进来。
+  const decided = job.suiteDecision === undefined
+    ? await shouldRunSuiteInstall(job, deps.probes ?? {})
+    : job.suiteDecision
+  if (decided === false) {
+    job.stage = 'detecting'
+    return { notASuite: true, reason: `${job.suiteDecisionReason ?? '该仓库有已发布到 npm 的可安装包'}，已自动回落普通插件安装` }
+  }
   const tmpDir = join(tmpdir(), `dsh-suite-${job.id}-${Date.now()}`)
   const report = []
   try {
     job.stage = 'preparing'
     mkdirSync(tmpDir, { recursive: true })
-    await gitCloneRepo(job.repo, tmpDir, job.source)
+    try {
+      await gitClone(job.repo, tmpDir, job.source)
+    } catch (cloneError) {
+      // 0.5.19（改错）：套装仓库**克隆失败**不再把作业判 failed。
+      // 旧代码整个函数只有一个 try/catch → 根克隆一失败就 job.status='failed'（真机 dsh-web：429 MB 巨仓、
+      // ghproxy 的 git 协议 0 B/s，必然失败），而 notASuite（把决定权交回普通通道）**只在"克隆成功但
+      // .gitmodules 为空"时才返回** → 克隆失败等于没有任何回落，用户只看到一个失败的任务。
+      // 克隆失败只证明"这条路走不通"，不证明"装不上"：回落普通通道（npm → Release → git，按包名施工）。
+      job.stage = 'detecting'
+      return {
+        notASuite: true,
+        reason: `套装仓库克隆失败（${cloneError instanceof Error ? cloneError.message : String(cloneError)}），已自动回落普通插件安装`,
+      }
+    }
     const subs = readGitmodules(tmpDir)
     if (subs.length === 0) {
       // 探测与仓库实际内容不符（假阳性 / 仓库已重构）：**不报失败**，把决定权交回调用方
@@ -217,4 +343,4 @@ async function runSuiteInstallJob(job, ports) {
     job.finishedAt = Date.now()
   }
 }
-export { readGitmodules, findPresetDirs, packageEntryExists, runSuiteInstallJob, probeGitmodules, resolveInstallKind }
+export { readGitmodules, findPresetDirs, packageEntryExists, runSuiteInstallJob, probeGitmodules, resolveInstallKind, fetchRepoMeta, shouldRunSuiteInstall }

package/lib/server/infra/exec.js

@@ -90,9 +90,18 @@ async function runPnpmWithFallback(args, { execOpts = {}, runners = resolvePnpmR
 
 /** git 非交互环境：禁止任何登录/凭据窗口弹出（私有仓库或不可达源直接失败，不做交互式重试）。 */
 
+/** git 停滞判据的 **env 形式**（2026-09-27 加法）：与 domain/repoland.js 的
+ * `-c http.lowSpeedLimit=1 -c http.lowSpeedTime=20` 同一语义（连续 20 秒 <1 B/s 就让 git 自己退出），
+ * 用途是覆盖**我们没有直接 spawn git** 的路径 —— 主要是 `pnpm add git+https://…`（pnpm 内部自己跑
+ * git，我们管不到它的命令行），以及 ai-run / skills / components 里其它 git 调用点。
+ * 实测（本机"只连不传"的 TCP 桩源）：只带这两个 env、**不带** `-c`，git 同样在 20.4 秒退出并报
+ * `Operation too slow. Less than 1 bytes/sec transferred the last 20 seconds`（见 tests/test-git-stall-guard.mjs）。 */
+const GIT_LOW_SPEED_ENV = { GIT_HTTP_LOW_SPEED_LIMIT: '1', GIT_HTTP_LOW_SPEED_TIME: '20' }
+
 function gitEnv() {
   return {
     ...process.env,
+    ...GIT_LOW_SPEED_ENV,
     GIT_TERMINAL_PROMPT: '0',
     GCM_INTERACTIVE: 'never',
     GIT_ASKPASS: 'echo',
@@ -355,6 +364,9 @@ function buildPnpmEnv(registry, base = process.env) {
     // git 通道禁止交互式凭据（与 gitEnv 同一语义）：避免 Git Credential Manager 弹登录窗
     GIT_TERMINAL_PROMPT: '0',
     GCM_INTERACTIVE: 'never',
+    // pnpm 的 git 依赖（`git+https://…`）由 pnpm 自己 spawn git，我们传不了命令行选项 →
+    // 用 env 给它同一套停滞判据（否则一个 0 B/s 的镜像能挂满 pnpm 的 fetch 超时）
+    ...GIT_LOW_SPEED_ENV,
     ...pnpmEnvOverrides(registry),
   }
 }
@@ -422,4 +434,4 @@ const GH_BIN_CANDIDATES = [
   join(homedir(), 'scoop', 'shims', 'gh.exe'),
 ]
 
-export { GH_BIN_CANDIDATES, gitEnv, gitBin, processAlive, execFileAsync, resolvePnpmRunners, runPnpmWithFallback, killProcessTree, posixDescendants, execFileWithKillTree, KILL_WAIT_MS, KILL_WAIT_POLL_MS, pnpmEnvOverrides, buildPnpmEnv, pnpmFetchArgs, pnpmAddArgs, unknownPnpmOption, runPnpmAdd }
+export { GH_BIN_CANDIDATES, gitEnv, gitBin, processAlive, execFileAsync, resolvePnpmRunners, runPnpmWithFallback, killProcessTree, posixDescendants, execFileWithKillTree, KILL_WAIT_MS, KILL_WAIT_POLL_MS, GIT_LOW_SPEED_ENV, pnpmEnvOverrides, buildPnpmEnv, pnpmFetchArgs, pnpmAddArgs, unknownPnpmOption, runPnpmAdd }