@noob-stupid/dsh-plugin-console 0.5.12 → 0.5.13

package/lib/server/domain/install-verify.js

@@ -0,0 +1,221 @@
+// L1 · domain —— install-verify.js（装后校验 + 下载物摘要校验；2026-09-26 新增，**纯加法**）
+//
+// 解决什么：装完就报成功，用户要到重启后才发现"入口文件不在 / 补丁行指向别的包 / bundle 引用缺失"，
+// 而失败原因常常只是**镜像没同步完整**（本控制台主源是 registry.npmmirror.com）——这类问题重装/换源即可，
+// 但面板在此之前完全不告诉用户。
+//
+// 两条硬规矩（写在最前面，改代码时别越线）：
+//   ① verifyInstalledEntry 只**读**、只产出结构化诊断：**绝不影响既有成功判定** —— 校验失败也只是提示，
+//      不把已经装成功的作业改判失败（安装是否成功由 install-job.js 的既有逻辑决定）。
+//   ② verifyTarballDigest 拿不到摘要时如实记「来源无摘要，未校验」，**绝不因此拒装**（离线/内网源常见）；
+//      摘要不匹配也只记录 + 强烈提示，不拒装（部分镜像会重打包 tarball，拒装会直接破坏这些源的可用性）。
+//
+// 报告里的 mirrorHint 是刻意固化的：主源是镜像站，"文件/引用缺失"最常见的解释就是镜像未同步完整。
+import { existsSync, readFileSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+import { join } from 'node:path'
+import { parseInsertNames } from './patch.js'
+import { deriveEntryId } from './runtime.js'
+
+/** 固定的镜像提示（面板会原样显示给用户）。 */
+const MIRROR_HINT = '镜像可能未同步完整（本控制台主源是 registry.npmmirror.com）：可稍后重试，'
+  + '或在「源管理」里换用 registry.npmjs.org / 其它镜像后重装'
+
+/** 入口字段归一：main（字符串）优先，其次 exports['.']（字符串或 {default}）。
+ * 返回 { field, value } 或 null（包没声明入口 —— 不算问题，很多 bundle/皮肤包没有入口）。 */
+function entryFieldOf(pkg) {
+  if (typeof pkg?.main === 'string' && pkg.main !== '') return { field: 'main', value: pkg.main }
+  const dot = pkg?.exports?.['.']
+  if (typeof dot === 'string' && dot !== '') return { field: 'exports["."]', value: dot }
+  if (dot !== null && typeof dot === 'object' && typeof dot.default === 'string' && dot.default !== '') {
+    return { field: 'exports["."].default', value: dot.default }
+  }
+  if (typeof pkg?.exports === 'string' && pkg.exports !== '') return { field: 'exports', value: pkg.exports }
+  return null
+}
+
+/** 读 profile 的补丁行（id → 包名）；读不到就当没有，不抛。 */
+function readPatchRows(profileDir) {
+  const patchPath = join(profileDir, 'cordis.patch.yml')
+  try {
+    if (!existsSync(patchPath)) return { patchPath, rows: new Map() }
+    return { patchPath, rows: parseInsertNames(readFileSync(patchPath, 'utf8')) }
+  } catch {
+    return { patchPath, rows: new Map() }
+  }
+}
+
+/** profile 清单里声明的 bundle 层（读不到就空数组）。 */
+function readBundles(profileDir) {
+  try {
+    const manifest = JSON.parse(readFileSync(join(profileDir, 'package.json'), 'utf8'))
+    const bundles = manifest?.dsh?.profile?.bundles
+    return Array.isArray(bundles) ? bundles : []
+  } catch {
+    return []
+  }
+}
+
+/**
+ * 装后校验（只读、永不抛）：读回刚装的 package.json，检查
+ *   ① 入口（main / exports）指向的文件确实存在；
+ *   ② profile 补丁里与这个包相关的行**指向的就是这个包名**（id 派生一致但 name 不同 → 明确报错）；
+ *   ③ 若该包声明了 dsh.bundle.patch（或已被写进 profile bundles）：补丁文件存在、且其中引用的包都能解析。
+ * 返回结构化诊断（ok / problems / mirrorHint / suggestions / entry / patch / bundle / version …）。
+ */
+function verifyInstalledEntry(profileDir, packageName) {
+  const safeName = typeof packageName === 'string' ? packageName : String(packageName ?? '')
+  const report = {
+    ok: false,
+    checked: false,
+    packageName,
+    // 用 String() 兜住非法输入：本函数的契约是"永不抛"，连 path.join 的参数类型错误都不许漏出去
+    packageDir: join(String(profileDir ?? ''), 'node_modules', ...safeName.split('/')),
+    version: null,
+    entry: null,
+    patch: { patchPath: null, rows: [], matched: [], mismatched: [] },
+    bundle: { declared: false, inBundles: false, patchFile: null, refs: 0, missingRefs: [] },
+    problems: [],
+    mirrorHint: null,
+    suggestions: [],
+    error: null,
+  }
+  try {
+    const pkgPath = join(report.packageDir, 'package.json')
+    if (!existsSync(pkgPath)) {
+      report.problems.push(`读不到 ${packageName} 的 package.json（${pkgPath}）：可能被 pnpm 还原/删除，或安装目录被占用`)
+      report.mirrorHint = MIRROR_HINT
+      report.suggestions.push('重装一次；若仍失败请确认该包在 registry 上确实存在该版本')
+      report.checked = true
+      report.ok = false
+      return report
+    }
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+    report.checked = true
+    report.version = typeof pkg.version === 'string' ? pkg.version : null
+    if (pkg.name !== packageName) {
+      report.problems.push(`package.json 里的包名（${pkg.name}）与安装目标（${packageName}）不一致：`
+        + '多半是镜像把同名/错误产物发了下来')
+      report.mirrorHint = MIRROR_HINT
+    }
+
+    // ① 入口文件存在性
+    const entry = entryFieldOf(pkg)
+    if (entry === null) {
+      report.entry = { field: null, value: null, exists: null, note: '该包未声明 main/exports（bundle/皮肤类包常见），跳过入口检查' }
+    } else {
+      const target = join(report.packageDir, ...entry.value.split('/'))
+      const exists = existsSync(target)
+      report.entry = { field: entry.field, value: entry.value, exists, note: exists ? null : `入口文件缺失：${target}` }
+      if (!exists) {
+        report.problems.push(`入口文件缺失：${entry.field} = ${entry.value}，但 ${target} 不存在（装了也加载不起来）`)
+        report.mirrorHint = MIRROR_HINT
+      }
+    }
+
+    // ② 补丁行与包名一致
+    const { patchPath, rows } = readPatchRows(profileDir)
+    report.patch.patchPath = patchPath
+    const derivedId = deriveEntryId(packageName, new Set())
+    for (const [id, name] of rows) {
+      report.patch.rows.push({ id, name })
+      const related = id === derivedId || id.startsWith(`${derivedId}-`) || name === packageName
+      if (!related) continue
+      if (name === packageName) report.patch.matched.push({ id, name })
+      else report.patch.mismatched.push({ id, name })
+    }
+    if (report.patch.mismatched.length > 0) {
+      report.problems.push(`补丁行与包名不一致：${report.patch.mismatched.map((r) => `id=${r.id} → name=${r.name}`).join('、')}`
+        + `（期望 name=${packageName}）—— 会让 DSH 启动时加载到别的模块或直接缺失`)
+      report.suggestions.push(`修正 profile 的 cordis.patch.yml：把 ${report.patch.mismatched.map((r) => r.id).join('、')} 行的 name 改成 ${packageName}（或重装一次让控制台重写该行）`)
+    }
+
+    // ③ bundle 引用一致性（只在"该包声明了 bundle 或已在 profile bundles 里"时检查，避免误报）
+    const bundles = readBundles(profileDir)
+    report.bundle.declared = typeof pkg?.dsh?.bundle?.patch === 'string'
+    report.bundle.inBundles = bundles.includes(packageName)
+    if (report.bundle.declared || report.bundle.inBundles) {
+      const rel = typeof pkg?.dsh?.bundle?.patch === 'string' ? pkg.dsh.bundle.patch : null
+      const patchFile = rel === null ? null : join(report.packageDir, rel)
+      report.bundle.patchFile = patchFile
+      if (rel !== null && !existsSync(patchFile)) {
+        report.problems.push(`bundle 补丁文件缺失：dsh.bundle.patch = ${rel}（${patchFile} 不存在）`)
+        report.mirrorHint = MIRROR_HINT
+      } else if (patchFile !== null) {
+        const refs = [...parseInsertNames(readFileSync(patchFile, 'utf8')).values()]
+        report.bundle.refs = refs.length
+        for (const name of refs) {
+          if (name.startsWith('cordis:')) continue
+          if (!existsSync(join(profileDir, 'node_modules', ...name.split('/')))) report.bundle.missingRefs.push(name)
+        }
+        if (report.bundle.missingRefs.length > 0) {
+          report.problems.push(`bundle 引用的包缺失：${report.bundle.missingRefs.join('、')}（启动时会因为缺模块崩溃/自动禁用该行）`)
+          report.mirrorHint = MIRROR_HINT
+          report.suggestions.push('等网络恢复后在面板里重新安装该聚合包（控制台会自动补齐/禁用缺失行）')
+        }
+      }
+    }
+
+    if (report.problems.length > 0) {
+      report.suggestions.push('重装该插件（pnpm 通道会重新下载）；若重复出现同样的缺失，优先怀疑镜像未同步，换源后再装')
+      if (report.mirrorHint !== null && !report.suggestions.includes(MIRROR_HINT)) report.suggestions.unshift(MIRROR_HINT)
+    }
+    report.ok = report.problems.length === 0
+    return report
+  } catch (error) {
+    report.checked = true
+    report.ok = false
+    report.error = error instanceof Error ? error.message : String(error)
+    report.problems.push(`装后校验本身出错（不影响安装结果）：${report.error}`)
+    return report
+  }
+}
+
+/**
+ * 下载物摘要校验（只读、永不抛）：算出 sha256 并尽量与 registry 元数据比对。
+ *   · 元数据有 dist.integrity（SRI，通常 sha512）→ 按该算法校验并记录；
+ *   · 只有 dist.shasum（sha1）→ 按 sha1 校验并记录；
+ *   · 两者都没有 → ok=null + note「来源无摘要，未校验」，**绝不因此拒装**（离线/内网源的常态）。
+ * 摘要不匹配**也不拒装**（部分镜像是重打包的 tarball），只把 ok=false 与提示记进 job 供用户判断。
+ */
+function verifyTarballDigest(tarballPath, dist = null) {
+  const out = { checked: false, ok: null, algorithm: null, expected: null, actual: null, sha256: null, note: null }
+  try {
+    const buf = readFileSync(tarballPath)
+    out.sha256 = createHash('sha256').update(buf).digest('hex')
+    out.checked = true
+    const sri = typeof dist?.integrity === 'string' ? dist.integrity.trim().split(/\s+/u)[0] : null
+    const shasum = typeof dist?.shasum === 'string' ? dist.shasum.trim() : null
+    if (sri !== null && /^[a-z0-9]+-[A-Za-z0-9+/=]+$/u.test(sri)) {
+      const [algorithm, expected] = [sri.slice(0, sri.indexOf('-')), sri.slice(sri.indexOf('-') + 1)]
+      const actual = createHash(algorithm).update(buf).digest('base64')
+      out.algorithm = algorithm
+      out.expected = sri
+      out.actual = `${algorithm}-${actual}`
+      out.ok = actual === expected
+      out.note = out.ok === true
+        ? `已按 registry 元数据的 ${algorithm} 摘要校验通过（sha256=${out.sha256}）`
+        : `摘要不匹配：registry 元数据声明 ${algorithm} 摘要，但下载物算出来不同（疑似镜像重打包或下载损坏）——按"不拒装、只记录"处理，建议重试或换源`
+      return out
+    }
+    if (shasum !== null) {
+      const actual = createHash('sha1').update(buf).digest('hex')
+      out.algorithm = 'sha1'
+      out.expected = shasum
+      out.actual = actual
+      out.ok = actual === shasum
+      out.note = out.ok === true
+        ? `已按 registry 元数据的 sha1 摘要校验通过（sha256=${out.sha256}）`
+        : `摘要不匹配：registry 元数据的 sha1 与下载物不同（疑似镜像重打包或下载损坏）——按"不拒装、只记录"处理`
+      return out
+    }
+    out.ok = null
+    out.note = `来源无摘要，未校验（已记录 sha256=${out.sha256}；离线/内网源常见，不影响安装）`
+    return out
+  } catch (error) {
+    out.note = `摘要校验无法完成（不影响安装）：${error instanceof Error ? error.message : String(error)}`
+    return out
+  }
+}
+
+export { verifyInstalledEntry, verifyTarballDigest, entryFieldOf, MIRROR_HINT }

package/lib/server/domain/install.js

@@ -8,11 +8,12 @@ import { dirname, join, resolve } from 'node:path'
 import { tmpdir } from 'node:os'
 import { sanitizePatchText } from './patch.js'
 import { orderedRegistries, readSources } from './sources.js'
-import { execFileAsync, runPnpmWithFallback } from '../infra/exec.js'
+import { runPnpmAdd, execFileAsync } from '../infra/exec.js'
 import { copyTree, queuedWrite } from '../infra/fsx.js'
 import { fetchJsonUrl } from '../infra/http.js'
 import { dshHome, resolvePackageJson } from '../infra/paths.js'
 import { downloadReleaseArtifact, releaseInstallTarget, selectReleaseInstall } from './release-source.js'
+import { verifyTarballDigest } from './install-verify.js'
 
 /** bundle 包判定：声明 dsh.bundle 的包一律按官方 `dsh plugin add` 行为追加为
  * profile bundle 层（其 cordis.patch.yml 的插入行在下次启动时组合进树）。
@@ -108,29 +109,18 @@ function readGithubAuth() {
   return { loggedIn: false, login: null, token: null }
 }
 
+/** 安装通道的 pnpm 默认超时（毫秒）。install-job.js 的定向重试要按它算出"更长超时"，故导出为常量。 */
+const PNPM_INSTALL_TIMEOUT_MS = 90000
+
 /**
  * 插件安装：与官方 `dsh plugin add` 使用同一管理器——corepack → pnpm add。
  * profile 目录由 pnpm 管理；若用 npm 写入会与 pnpm 的目录重建互相破坏
  * （曾导致入口链接丢失、DSH 启动崩溃）。registry 走国内镜像。
+ * 2026-09-26：执行细节（健壮性 env + pnpm add 选项 + 不支持选项时降级）搬进 infra/exec.js#runPnpmAdd，
+ * 本函数保持"一个通道入口"的角色，签名与成功/失败语义不变（`deps` 只是单测注入口）。
  */
-async function pnpmInstall(profileDir, spec, registry = 'https://registry.npmmirror.com', timeout = 90000, signal = null) {
-  const args = ['add', spec, '--registry', registry]
-  const opts = {
-    cwd: profileDir,
-    timeout,
-    windowsHide: true,
-    maxBuffer: 4 * 1024 * 1024,
-    env: {
-      ...process.env,
-      COREPACK_NPM_REGISTRY: registry,
-      // git 通道禁止交互式凭据：避免 Git Credential Manager 弹登录窗（匿名失败即静默失败）
-      GIT_TERMINAL_PROMPT: '0',
-      GCM_INTERACTIVE: 'never',
-    },
-  }
-  // 跨平台定位 corepack/pnpm（Windows 布局 / Linux npm 全局布局 / PATH 兜底），
-  // 旧代码只认 Windows 布局，Linux 上会生成 MODULE_NOT_FOUND 的命令（2026-09-20 事故）
-  await runPnpmWithFallback(args, { execOpts: opts })
+async function pnpmInstall(profileDir, spec, registry = 'https://registry.npmmirror.com', timeout = PNPM_INSTALL_TIMEOUT_MS, signal = null, deps = {}) {
+  await runPnpmAdd({ profileDir, spec, registry, timeout, signal, deps })
 }
 
 /**
@@ -163,6 +153,9 @@ async function curlManualInstall(profileDir, packageName, registries, signal = n
   try {
     const tgz = join(tmp, 'pkg.tgz')
     await execFileAsync(bin, ['-s', '-L', '-m', '60', '-o', tgz, tarball], { timeout: 70000, windowsHide: true, ...(signal ? { signal } : {}) })
+    // ④ 下载物摘要（加法）：算 sha256 并与 registry 元数据的 dist.integrity/shasum 比对；拿不到摘要就如实记
+    // "来源无摘要，未校验"，**绝不因此拒装**（见 domain/install-verify.js 顶部两条硬规矩）
+    const integrity = verifyTarballDigest(tgz, meta.versions?.[version]?.dist)
     await execFileAsync('tar', ['-xzf', tgz, '-C', tmp], { timeout: 30000, windowsHide: true, ...(signal ? { signal } : {}) })
     let pkgPath = join(tmp, 'package')
     if (!existsSync(join(pkgPath, 'package.json'))) {
@@ -186,7 +179,7 @@ async function curlManualInstall(profileDir, packageName, registries, signal = n
     try {
       writeFileSync(join(target, '.dsh-installed-at'), String(Date.now()), 'utf8')
     } catch {}
-    return { version, missingDeps, boxNote: box.note }
+    return { version, missingDeps, boxNote: box.note, integrity }
   } finally {
     rmSync(tmp, { recursive: true, force: true })
   }
@@ -561,6 +554,11 @@ function installJobView(job) {
         : null,
     // 授权请求（等本地 AI 兜底同意）：面板要显示倒计时 + 同意/取消，所以时间与最后错误一起下发
     aiConsent: { pending: job.aiPending != null, since: job.aiPendingSince ?? null, timeoutMs: job.aiConsentTimeoutMs ?? AI_CONSENT_TIMEOUT_MS, lastError: job.aiPending?.lastError ?? job.lastError ?? null },
+    // 失败分类提示（2026-09-26 加法）：{ kind, hint, retry }（可能带 retried/retryTimeoutMs），
+    // 由 install-diagnose.js 的纯函数产出；只影响展示与"是否已定向重试"的可见性，不参与成功判定
+    diagnosis: job.diagnosis ?? null,
+    // 装后校验与下载物摘要（2026-09-26 加法，见 install-verify.js）：**只提示**，不改变既有成功判定
+    entryCheck: job.entryCheck ?? null, integrity: job.integrity ?? null,
   }
 }
 
@@ -596,4 +594,4 @@ async function syncAggregateSubpackageVersions(profileDir, packageName, registri
   return updated
 }
 
-export { AI_CONSENT_TIMEOUT_MS, DEFAULT_BUNDLES, detectBundleOnly, addBundleToManifest, removeBundleFromManifest, readExtraBundleOwners, readGithubAuth, pnpmInstall, curlManualInstall, raceInstallChannels, verifyPackageBox, parseBundlePatchRefs, backfillMissingDeps, githubReleaseInstall, readBundlePatchRefNames, ensureBundlePatchIntegrity, syncAggregateSubpackageVersions, installJobView }
+export { AI_CONSENT_TIMEOUT_MS, PNPM_INSTALL_TIMEOUT_MS, DEFAULT_BUNDLES, detectBundleOnly, addBundleToManifest, removeBundleFromManifest, readExtraBundleOwners, readGithubAuth, pnpmInstall, curlManualInstall, raceInstallChannels, verifyPackageBox, parseBundlePatchRefs, backfillMissingDeps, githubReleaseInstall, readBundlePatchRefNames, ensureBundlePatchIntegrity, syncAggregateSubpackageVersions, installJobView }

package/lib/server/domain/repoland.js

@@ -1,11 +1,12 @@
 // L1 · domain —— repoland.js（仓库落地：落地目录配置 / 已落地列表 / 克隆；分层 Step 4 从 lib/index.js 搬出，只搬移未改逻辑）
 // 分组见 D:\dsh\dsh-plugin-hub-plan\architecture.zh.md 三
 
-import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync } from 'node:fs'
+import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync, renameSync } from 'node:fs'
+import { spawn } from 'node:child_process'
 import { dirname, join } from 'node:path'
 import { homedir } from 'node:os'
 import { gitCloneUrls } from './sources.js'
-import { execFileAsync, gitEnv } from '../infra/exec.js'
+import { execFileAsync, gitEnv, killProcessTree } from '../infra/exec.js'
 import { removeDirVerified } from '../infra/fsx.js'
 import { repoLandConfFile } from '../infra/paths.js'
 
@@ -71,49 +72,118 @@ function gitErrorDetail(error) {
 }
 
 /** 逐条尝试的错误汇总（纯函数，单测覆盖）：报**第一个**错误（真实原因）+ 尝试清单。
- * 为什么要这样：多源重试时若第一次失败留下半成品目录，第二次会以
- * `fatal: destination path '…' already exists and is not an empty directory` 失败，
- * 旧代码把它当 lastError 抛出去 → 用户只看到"目录非空"，真实原因（镜像/网络不可达）被完全掩盖。
- * 2026-09-20 另一位用户实测报的就是这句。 */
+ * 2026-09-26 真机（官方桌面端里装 git 源插件）：ghproxy 卡死 → 我们的超时到了但**没杀 git 进程**，
+ * 于是 `git clone` / `git remote-https` / `index-pack --shallow-file …\.git\shallow.lock` 常驻，
+ * Windows 不允许删除被打开的文件 → 目标目录清不掉 → 旧代码把它写成"环境禁止删除"并**放弃后续源**。
+ * 现在措辞如实：说清"仍有 git 占用（已尝试结束）"，并给出可复制的手动删除命令。 */
 function summarizeCloneErrors(errors) {
   const first = errors[0]
-  const tried = errors.map((e) => (e.unclean === true
-    ? `${e.url}（目标目录清不掉，未重试）`
-    : (/already exists and is not an empty directory/u.test(e.message) ? `${e.url}（目录非空）` : e.url))).join('；')
+  const tried = errors.map((e) => {
+    if (e.unclean === true) return `${e.url}（残留目录被占用，已跳过重试）`
+    if (e.skipped === true) return `${e.url}（探活失败，已跳过）`
+    if (e.timedOut === true) return `${e.url}（超时，进程已结束）`
+    return /already exists and is not an empty directory/u.test(e.message) ? `${e.url}（目录非空）` : e.url
+  }).join('；')
   const detail = gitErrorDetail(first)
-  const uncleanNote = errors.some((e) => e.unclean === true)
-    ? '；注意：上一次失败留下的半成品目录无法清理（当前环境禁止删除），多源重试因此无效——请手动删除该目录后重试'
-    : ''
-  return `git clone 失败（首个错误：${first?.message ?? '未知'}${detail !== '' ? `；git 说：${detail}` : ''}）；已尝试 ${errors.length} 个源：${tried}${uncleanNote}`
+  const stuck = errors.filter((e) => e.unclean === true)
+  const stuckNote = stuck.length === 0
+    ? ''
+    : `；注意：${stuck[0].message}。可手动删除后重试：Remove-Item -Recurse -Force '${stuck[0].dir}'`
+  return `git clone 失败（首个错误：${first?.message ?? '未知'}${detail !== '' ? `；git 说：${detail}` : ''}）；已尝试 ${errors.length} 个源：${tried}${stuckNote}`
 }
 
-/** git clone（镜像→直连；gitee 直连），返回 { url } 或抛错。 */
-async function gitCloneRepo(repo, dest, source = 'github', timeout = 180000) {
-  const urls = gitCloneUrls(repo, source)
-  const errors = []
-  for (const [attempt, url] of urls.entries()) {
-    // 每次尝试前都清掉目标目录：上一次可能留下半成品（git 会先建目录再传输），
-    // 不清就会让第二次以"目录非空"失败并掩盖真实原因（见 summarizeCloneErrors 注释）。
-    // 关键是**核实**清理结果：清不掉就别再试下一个源——那只会多出一条"目录非空"，
-    // 把第一个源的真实错误一起搅浑（本机 %TEMP% 下删除被静默忽略时就是这样，2026-09-20 实测）。
-    const cleared = removeDirVerified(dest)
-    if (!cleared.ok) {
-      errors.push({ url, message: `克隆目标目录无法清理（环境禁止删除）：${dest}`, unclean: true })
-      break
-    }
+/** 结束**整棵**进程树。超时/中断后必须做：git 会派生 remote-https / index-pack 子进程，
+ * 只 kill 父进程会留下孤儿继续占着 .git 里的文件（2026-09-26 实测占住 pack 临时文件与 shallow.lock）。
+ * 2026-09-26（本次）：实现搬进 infra/exec.js（pnpm 通道复用同一份，domain 不再各留一份拷贝），
+ * 这里保留同名 re-export —— **对外导出名与调用点一个字都没变**。 */
+
+/** 跑一次 git clone：支持超时，且**超时即杀掉整棵树**。返回 { code, stderr, timedOut, pid }。 */
+function runGitClone(url, dest, timeout, { spawnFn = spawn, killTree = killProcessTree } = {}) {
+  return new Promise((resolve) => {
+    let settled = false
+    const finish = (payload) => { if (!settled) { settled = true; resolve(payload) } }
+    let child = null
+    let stderr = ''
     try {
-      // eslint-disable-next-line no-await-in-loop
-      await execFileAsync('git', ['clone', '--depth', '1', '--quiet', url, dest], {
-        timeout,
+      child = spawnFn('git', ['clone', '--depth', '1', '--quiet', url, dest], {
         windowsHide: true,
         env: gitEnv(),
+        detached: process.platform !== 'win32', // POSIX：自成进程组，便于 -pid 整体杀
       })
-      return { url, attempt: attempt + 1 }
     } catch (error) {
-      errors.push({ url, message: error?.message ?? String(error), stderr: error?.stderr })
+      finish({ code: -1, stderr: String(error?.message ?? error), timedOut: false, pid: null })
+      return
+    }
+    const timer = setTimeout(() => {
+      killTree(child.pid)
+      finish({ code: -1, stderr: stderr.trim(), timedOut: true, pid: child.pid })
+    }, timeout)
+    child.stderr?.on?.('data', (chunk) => { stderr += String(chunk) })
+    child.on('error', (error) => { clearTimeout(timer); finish({ code: -1, stderr: String(error?.message ?? error), timedOut: false, pid: child.pid }) })
+    child.on('close', (code) => { clearTimeout(timer); finish({ code: typeof code === 'number' ? code : -1, stderr: stderr.trim(), timedOut: false, pid: child.pid }) })
+  })
+}
+
+/** 源探活：镜像站"连得上但传不动"探不出来，但**域名挂掉/被墙**能提前识别，省掉一整个克隆超时的白等。 */
+async function probeSourceAlive(url, timeoutMs = 4000) {
+  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 }
+}
+
+/** git clone（镜像→直连；gitee 直连），返回 { url, attempt, dir } 或抛错。
+ * 每次尝试都用**全新唯一目录** `.tryN`，成功后才 rename 到 dest —— 这样即使上一轮残留目录被占用，
+ * 也不会再出现"一个源失败 → 后面所有源都因目录非空而无效"的连锁失效。 */
+async function gitCloneRepo(repo, dest, source = 'github', timeout = 180000, deps = {}) {
+  const {
+    spawnFn = spawn,
+    killTree = killProcessTree,
+    probe = probeSourceAlive,
+    removeDir = removeDirVerified,
+    renameDir = renameSync,
+  } = deps
+  const urls = gitCloneUrls(repo, source)
+  const errors = []
+  for (const [attempt, url] of urls.entries()) {
+    const part = `${dest}.try${attempt + 1}`
+    // eslint-disable-next-line no-await-in-loop
+    const alive = await probe(url)
+    if (!alive) {
+      errors.push({ url, message: `源探活失败（连不上）：${url}`, skipped: true, dir: part })
+      continue
+    }
+    try { removeDir(part) } catch {}
+    // eslint-disable-next-line no-await-in-loop
+    const res = await runGitClone(url, part, timeout, { spawnFn, killTree })
+    if (res.code === 0) {
+      try {
+        removeDir(dest)
+        renameDir(part, dest)
+        return { url, attempt: attempt + 1, dir: dest }
+      } catch (error) {
+        errors.push({ url, message: `克隆成功但落地失败（${error instanceof Error ? error.message : String(error)}）`, dir: part })
+        continue
+      }
+    }
+    // 失败：先尽力清掉半成品目录；清不掉就**如实说明**（这次不再谎报"环境禁止删除"）
+    const cleared = removeDir(part)
+    if (cleared && cleared.ok === false) {
+      errors.push({
+        url,
+        message: res.timedOut === true
+          ? `克隆超时，且残留目录仍被 git 占用（进程已尝试结束）：${part}`
+          : `克隆失败，且残留目录无法清理（可能仍被 git 占用）：${part}`,
+        stderr: res.stderr,
+        unclean: true,
+        timedOut: res.timedOut === true,
+        dir: part,
+      })
+      continue // **继续试下一个源**（新目录不受影响），不再像旧代码那样直接 break
     }
+    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 })
   }
   throw new Error(summarizeCloneErrors(errors))
 }
 
-export { reposDirCache, getReposDir, setReposDir, listLandedRepos, gitCloneRepo, summarizeCloneErrors }
+export { reposDirCache, getReposDir, setReposDir, listLandedRepos, gitCloneRepo, summarizeCloneErrors, killProcessTree, probeSourceAlive }