dsh-deepmoyu 2.3.0 → 2.4.2

package/lib/update.mjs

@@ -0,0 +1,265 @@
+/**
+ * 更新通道（2026-10-30 使用者要求「加一个更新通道，方便及时更新」）。
+ *
+ * ⚠️ 历史教训（必须保留这道闸）：2026-10-21 曾经有过一个「一键升级」按钮，它让宿主跑
+ *   `dsh plugin add dsh-deepmoyu`，把整个包目录重装成 registry 上的版本。当时本机装的是
+ *   **目录联接（junction）指向源码目录的分叉**，一次点击就把所有改动换掉了（m17605）。
+ *
+ * 所以这个模块的职责不是「能升级就行」，而是**先证明这次升级不会毁掉用户手里的东西**：
+ *   1. 只允许「registry 安装」自更新（包目录必须是 profile 的 node_modules 下真实目录）；
+ *      目录联接 / git 检出 / 包目录不在 profile 里 ⇒ 一律锁定，只给检查结果和手动升级建议。
+ *   2. 有刷站/后台/渲染在跑时拒绝：正在跑的进程读的是旧文件，换包会让下一次 import 半新半旧。
+ *   3. 单飞：同一时间只允许一个升级进程。
+ * 纯函数 + 依赖注入，测试不需要网络、不需要真 dsh。
+ */
+import { existsSync, lstatSync, readdirSync, realpathSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+export const PACKAGE_NAME = 'dsh-deepmoyu'
+export const DEFAULT_REGISTRY = 'https://registry.npmjs.org'
+export const MIRROR_REGISTRY = 'https://registry.npmmirror.com'
+export const ACCEPT_PACKUMENT = 'application/vnd.npm.install-v1+json'
+
+const num = (value, fallback = 0) => {
+  const n = Number(value)
+  return Number.isFinite(n) ? n : fallback
+}
+
+/** `2.4.10` / `2.4.1-beta.2` / `v2.4.1` → 可比较结构；非法返回 null。 */
+export function parseVersion(raw) {
+  const text = String(raw ?? '').trim().replace(/^v/i, '')
+  const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(text)
+  if (!match) return null
+  return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]), pre: match[4] || '' }
+}
+
+/**
+ * 比较两个版本：a>b 返回 1，相等 0，a<b 返回 -1。
+ * 预发布版本低于同号正式版（`2.4.1-beta` < `2.4.1`），与 semver 一致；
+ * 预发布段按点分隔逐段比，数字段按数值（`beta.10` > `beta.2`，不能比字符串）。
+ * 无法解析的版本按 0.0.0 处理，绝不因为解析失败就说「有新版」。
+ */
+export function compareVersions(a, b) {
+  const left = parseVersion(a) || { major: 0, minor: 0, patch: 0, pre: '0' }
+  const right = parseVersion(b) || { major: 0, minor: 0, patch: 0, pre: '0' }
+  for (const key of ['major', 'minor', 'patch']) {
+    if (left[key] !== right[key]) return left[key] > right[key] ? 1 : -1
+  }
+  if (left.pre === right.pre) return 0
+  if (!left.pre) return 1
+  if (!right.pre) return -1
+  const lseg = left.pre.split('.')
+  const rseg = right.pre.split('.')
+  for (let i = 0; i < Math.max(lseg.length, rseg.length); i++) {
+    const l = lseg[i], r = rseg[i]
+    if (l === undefined) return -1
+    if (r === undefined) return 1
+    if (l === r) continue
+    const ln = /^\d+$/.test(l), rn = /^\d+$/.test(r)
+    if (ln && rn) return Number(l) > Number(r) ? 1 : -1
+    if (ln) return -1
+    if (rn) return 1
+    return l > r ? 1 : -1
+  }
+  return 0
+}
+
+/** 从 npm packument 里挑出要提示的版本：优先 dist-tags.latest，没有就取最高正式版。 */
+export function pickPublished(packument) {
+  if (!packument || typeof packument !== 'object') return null
+  const tags = packument['dist-tags'] && typeof packument['dist-tags'] === 'object' ? packument['dist-tags'] : {}
+  const latest = String(tags.latest || '').trim()
+  if (parseVersion(latest)) {
+    const time = packument.time && typeof packument.time === 'object' ? String(packument.time[latest] || '') : ''
+    return { version: latest, publishedAt: time, source: 'dist-tags.latest' }
+  }
+  const versions = packument.versions && typeof packument.versions === 'object' ? Object.keys(packument.versions) : []
+  const stable = versions.filter((version) => parseVersion(version) && !parseVersion(version).pre)
+  if (!stable.length) return null
+  stable.sort(compareVersions)
+  const version = stable[stable.length - 1]
+  const time = packument.time && typeof packument.time === 'object' ? String(packument.time[version] || '') : ''
+  return { version, publishedAt: time, source: 'highest-stable' }
+}
+
+/**
+ * 判断这份安装能不能自更新。返回 `{ updatable, mode, reason, profile }`。
+ *
+ * mode:
+ *   `registry`  —— 包目录是 profile/node_modules/<pkg> 下的真实目录（市场或 `dsh plugin add` 装的）⇒ 可自更新
+ *   `link`      —— 目录联接 / 符号链接（本机分叉的接法）⇒ 只检查不升级
+ *   `source`    —— 包目录里带 .git，是源码检出 ⇒ 只检查不升级
+ *   `unknown`   —— 在 DSH_HOME 的 profiles 里找不到对应安装 ⇒ 只检查不升级
+ */
+export function detectInstallMode({ pluginDir, dshHome, packageName = PACKAGE_NAME } = {}) {
+  const dir = String(pluginDir || '')
+  if (!dir) return { updatable: false, mode: 'unknown', reason: '拿不到插件目录，无法判断安装方式', profile: '' }
+  let real = dir
+  try { real = realpathSync(dir) } catch { /* 目录不可读就按原样比 */ }
+  let linked = false
+  try { linked = lstatSync(dir).isSymbolicLink() } catch { linked = false }
+  if (existsSync(join(dir, '.git'))) {
+    return { updatable: false, mode: 'source', profile: '', real,
+      reason: '这是源码检出（目录里有 .git），自更新会用 registry 版本覆盖你的改动；请改用 git pull 后重启 DSH' }
+  }
+  if (linked) {
+    return { updatable: false, mode: 'link', profile: '', real,
+      reason: '这是目录联接安装（包目录指向别处，常见于本机分叉），自更新会把指向的目录换掉；请手动覆盖或重新 link' }
+  }
+  const home = String(dshHome || '')
+  const profilesDir = home ? join(home, 'profiles') : ''
+  let names = []
+  try { names = profilesDir ? readdirSync(profilesDir) : [] } catch { names = [] }
+  for (const name of names) {
+    const candidate = join(profilesDir, name, 'node_modules', packageName)
+    let candidateReal = ''
+    try { candidateReal = realpathSync(candidate) } catch { continue }
+    if (candidateReal !== real) continue
+    let isLink = false
+    try { isLink = lstatSync(candidate).isSymbolicLink() } catch { isLink = false }
+    if (isLink) {
+      return { updatable: false, mode: 'link', profile: name, real,
+        reason: `profile「${name}」里这个包是链接安装（可能指向本机源码），自更新会替换掉它；请手动处理` }
+    }
+    return { updatable: true, mode: 'registry', profile: name, real, reason: '' }
+  }
+  return { updatable: false, mode: 'unknown', profile: '',
+    reason: '没在 DSH 的 profiles 里找到这份安装（可能是手动放置或另装了一份），为避免误覆盖，自更新已锁定' }
+}
+
+/** npm packument 请求（带超时与体积上限，只读）。 */
+export async function fetchPackument({ registry = DEFAULT_REGISTRY, packageName = PACKAGE_NAME, fetchImpl = globalThis.fetch, timeoutMs = 8000, maxBytes = 2 * 1024 * 1024 } = {}) {
+  if (typeof fetchImpl !== 'function') throw new Error('当前 Node 没有 fetch，无法检查更新')
+  const base = String(registry || DEFAULT_REGISTRY).replace(/\/+$/, '')
+  const url = `${base}/${encodeURIComponent(packageName).replace('%40', '@')}`
+  const controller = typeof AbortController === 'function' ? new AbortController() : null
+  const timer = controller ? setTimeout(() => controller.abort(), timeoutMs) : null
+  if (timer?.unref) timer.unref()
+  try {
+    const response = await fetchImpl(url, {
+      headers: { accept: ACCEPT_PACKUMENT, 'user-agent': `${packageName}-update-check` },
+      redirect: 'follow',
+      signal: controller ? controller.signal : undefined,
+    })
+    if (response.status === 404) return { ok: false, code: 'NOT_PUBLISHED', error: 'registry 上还没有这个包（或名称被占用），暂时无法检查更新', registry: base }
+    if (!response.ok) return { ok: false, code: 'HTTP_' + response.status, error: `registry 返回 HTTP ${response.status}`, registry: base }
+    const text = await response.text()
+    if (text.length > maxBytes) return { ok: false, code: 'TOO_LARGE', error: 'registry 响应过大，已放弃解析', registry: base }
+    let body
+    try { body = JSON.parse(text) } catch { return { ok: false, code: 'BAD_JSON', error: 'registry 返回的不是合法 JSON', registry: base } }
+    return { ok: true, body, registry: base }
+  } catch (error) {
+    const aborted = error && (error.name === 'AbortError' || error.code === 'ABORT_ERR')
+    return { ok: false, code: aborted ? 'TIMEOUT' : 'NETWORK', error: aborted ? `连接 registry 超时（${Math.round(timeoutMs / 1000)} 秒）` : `连不上 registry：${error?.message || error}`, registry: base }
+  } finally {
+    if (timer) clearTimeout(timer)
+  }
+}
+
+/**
+ * 组装给界面/工具看的检查结果。纯函数：不联网、不抛错。
+ * `latest` 拿不到时 `ok:false` 但**不当成「已经最新」**——未知就是未知。
+ */
+export function buildUpdateReport({ current, published, install, registry = DEFAULT_REGISTRY, checkedAt = Date.now(), error = '' } = {}) {
+  const cur = String(current || '')
+  const hasCurrent = Boolean(parseVersion(cur))
+  const latest = published && parseVersion(published.version) ? String(published.version) : ''
+  const outdated = Boolean(hasCurrent && latest && compareVersions(latest, cur) > 0)
+  const ahead = Boolean(hasCurrent && latest && compareVersions(cur, latest) > 0)
+  const canUpgrade = Boolean(outdated && install && install.updatable === true)
+  let hint = ''
+  if (error) hint = error
+  else if (!latest) hint = '暂时读不到 registry 上的版本，稍后再试'
+  else if (ahead) hint = `当前 ${cur} 比 registry 上的 ${latest} 还新（本地开发版或未发布提交）`
+  else if (!outdated) hint = '已是最新版本'
+  else if (!install || install.updatable !== true) hint = (install && install.reason) || '当前安装方式不支持自更新，请手动升级'
+  else hint = `可以升级到 ${latest}；升级后需要重启 DSH 才能加载新代码`
+  return {
+    ok: !error,
+    package: PACKAGE_NAME,
+    current: cur,
+    latest,
+    outdated,
+    ahead,
+    canUpgrade,
+    install: install || { updatable: false, mode: 'unknown', profile: '', reason: '无法判断安装方式' },
+    registry: String(registry || DEFAULT_REGISTRY).replace(/\/+$/, ''),
+    publishedAt: published ? String(published.publishedAt || '') : '',
+    checkedAt: num(checkedAt, 0),
+    hint,
+    error: error || '',
+  }
+}
+
+/** 组合：检测安装方式 + 查 registry + 生成结果。检查本身永不抛错。 */
+export async function checkForUpdate({ current, pluginDir, dshHome, registry = DEFAULT_REGISTRY, fetchImpl = globalThis.fetch, packageName = PACKAGE_NAME, timeoutMs = 8000, checkedAt = Date.now() } = {}) {
+  const install = detectInstallMode({ pluginDir, dshHome, packageName })
+  const fetched = await fetchPackument({ registry, packageName, fetchImpl, timeoutMs })
+  if (!fetched.ok) return { ...buildUpdateReport({ current, published: null, install, registry, checkedAt, error: fetched.error }), code: fetched.code }
+  const published = pickPublished(fetched.body)
+  if (!published) return { ...buildUpdateReport({ current, published: null, install, registry, checkedAt, error: 'registry 上的版本信息不完整，无法判断' }), code: 'NO_VERSIONS' }
+  return buildUpdateReport({ current, published, install, registry, checkedAt })
+}
+
+/**
+ * 生成升级命令。只允许 `plugin add <包名>`，不接受任意参数、不接受本地路径。
+ * 返回 `{ command, args, env, profile }` 或 `{ ok:false, code, error }`。
+ */
+export function upgradeCommand({ dshCli, profile, packageName = PACKAGE_NAME, electron = false, registry = '' } = {}) {
+  const cli = String(dshCli || '')
+  if (!cli) return { ok: false, code: 'NO_DSH_CLI', error: '找不到 dsh 命令行，无法自动升级；请在终端手动执行 dsh plugin --profile <名称> add ' + packageName }
+  const name = String(profile || '')
+  if (!/^[A-Za-z0-9._-]{1,64}$/.test(name)) return { ok: false, code: 'NO_PROFILE', error: '不知道这份安装属于哪个 profile，无法安全升级' }
+  const env = { DSH_UPDATE_AT: String(Date.now()) }
+  if (electron) env.ELECTRON_RUN_AS_NODE = '1'
+  const reg = String(registry || '').trim()
+  if (reg) {
+    if (!/^https?:\/\/[^\s]+$/i.test(reg)) return { ok: false, code: 'BAD_REGISTRY', error: 'registry 地址无效' }
+    env.npm_config_registry = reg
+  }
+  return { ok: true, command: process.execPath, args: [cli, 'plugin', '--profile', name, 'add', packageName], env, profile: name, packageName }
+}
+
+/** 升级前必须满足的条件；返回拒绝原因或空串。 */
+export function upgradeBlocker({ report, busy = {}, upgrading = false, runningSend = false } = {}) {
+  if (upgrading) return '已经有一个升级在进行，请等它结束'
+  if (!report || report.ok === false) return '还没成功检查到可用版本，先点「检查更新」'
+  if (!report.outdated) return report.ahead ? '当前版本已经比 registry 上的新，不需要升级' : '已经是最新版本'
+  if (!report.canUpgrade) return (report.install && report.install.reason) || '当前安装方式不支持自更新'
+  if (runningSend) return '刷站任务正在运行，等它停下再升级（避免跑着的进程读到半新半旧的代码）'
+  const active = Object.entries(busy || {}).filter(([, value]) => value === true).map(([key]) => key)
+  if (active.length) return `有任务在运行（${active.join(' / ')}），结束之后再升级`
+  return ''
+}
+
+/** 从升级进程输出里认出结果，给界面一句人话。 */
+export function summarizeUpgrade({ code, output = '', timedOut = false, latest = '' } = {}) {
+  const text = String(output || '')
+  if (timedOut) return { ok: false, code: 'TIMEOUT', message: '升级超时（可能网络慢），请查看日志；已安装的版本没有被删除' }
+  const clean = text.replace(/\[[-=]{4,}\]/g, '').trim()
+  const tail = clean.split(/\r?\n/).filter(Boolean).slice(-6).join(' / ').slice(0, 400)
+  if (code === 0) return { ok: true, code: 'DONE', message: `已安装${latest ? ' ' + latest : '新版本'}；完全重启 DSH 后生效`, tail }
+  const known = [
+    [/E404|404 Not Found/i, 'registry 上找不到这个版本（可能还没发布成功）'],
+    [/E401|E403|ENEEDAUTH|Unauthorized/i, '没有发布/读取权限，检查 npm 登录状态'],
+    [/EBUSY|EPERM|EACCES/i, '文件被占用（通常是 DSH 还在用旧文件）；完全退出 DSH 后重试'],
+    [/ENOTFOUND|ETIMEDOUT|ECONNREFUSED|network/i, '网络连不上 registry，可换镜像或稍后再试'],
+    [/EINTEGRITY|integrity/i, '包完整性校验失败，可能被镜像缓存污染，清缓存后重试'],
+  ]
+  for (const [pattern, message] of known) if (pattern.test(clean)) return { ok: false, code: 'FAILED', message, tail }
+  return { ok: false, code: 'FAILED', message: `升级没有成功（退出码 ${code}）${tail ? '：' + tail : ''}`, tail }
+}
+
+/** 把 npm 退出码/输出整理成可读日志，供界面与 duty.log 共用。 */
+export function upgradeLogLine({ phase, at = Date.now(), detail = '' } = {}) {
+  const stamp = new Date(num(at, Date.now())).toISOString()
+  return `${stamp} [update:${phase}] ${String(detail).slice(0, 2000)}`
+}
+
+/** 目录是否像一份完整安装（用于升级后自检，避免把半截目录当成功）。 */
+export function looksLikeInstall(dir) {
+  try {
+    if (!statSync(dir).isDirectory()) return false
+    return ['package.json', 'index.js', 'client.js', 'selfcheck.mjs'].every((name) => existsSync(join(dir, name)))
+  } catch { return false }
+}

package/lib/uvfetch.mjs

@@ -1,179 +1,191 @@
-/**
- * lib/uvfetch.mjs —— 「机器上连 uv 和 Python 都没有」时，**插件自己把 uv 弄到手**
- * ============================================================================
- * 为什么值得单独做：uv 是**单个可执行文件**（Windows 上 ~32MB 的 uv.exe ✓），
- * **解压就能用、不用管理员、不用进 PATH** ✓，而且它还能自己把 Python 拉下来 ✓
- * ⇒ 只要拿到它，"首次安装"就从「先去装个 Python」变成「点一下就好」✓
- *
- * 两个源，按顺序试：
- *   ① **GitHub 官方 release**（`uv-x86_64-pc-windows-msvc.zip`）—— 有加速器时最快 ✓
- *   ② ⭐ **PyPI 清华镜像的 uv wheel** —— wheel 本身就是个 zip，里面装着 `uv.exe` ✓
- *      （国内速度快、不依赖 GitHub ✓）
- *
- * 解压：优先用 **系统自带的 `tar`**（Windows 10+ 的 bsdtar 能直接读 zip ✓），
- *       再退到 `unzip`；然后**在解压出来的整棵树里按文件名找** ✓
- *       —— 不管官方把它放在哪一层都能找着 ✓
- * ============================================================================
- */
-import { spawnSync } from 'node:child_process'
-import { createWriteStream, existsSync, mkdirSync, readdirSync, statSync, copyFileSync, chmodSync, rmSync, readFileSync, renameSync } from 'node:fs'
-import { createHash } from 'node:crypto'
-import { join } from 'node:path'
-import { Readable } from 'node:stream'
-import { pipeline } from 'node:stream/promises'
+/** Verified, bounded uv bootstrap. User data and install artifacts stay outside the package. */
+import { execFile } from 'node:child_process'
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, copyFileSync, chmodSync, rmSync, readFileSync, renameSync } from 'node:fs'
+import { randomUUID, createHash } from 'node:crypto'
+import { join, resolve } from 'node:path'
+import { open, unlink } from 'node:fs/promises'
 
-const ASSETS = {
-  win32: { name: 'uv-x86_64-pc-windows-msvc.zip', bin: 'uv.exe' },
-  darwin: { name: 'uv-aarch64-apple-darwin.tar.gz', bin: 'uv' },
-  linux: { name: 'uv-x86_64-unknown-linux-gnu.tar.gz', bin: 'uv' },
-}
-
-/** 算一个文件的 sha256 */
-function sha256Of(file) {
-  return createHash('sha256').update(readFileSync(file)).digest('hex')
-}
+const inflight = new Map()
+const MAX_ARCHIVE = 192 * 1024 * 1024
+const SHA = /^[0-9a-f]{64}$/i
+const nativeRun = (command, args, options = {}) => new Promise(resolveRun => {
+  execFile(command, args, { timeout: 15_000, maxBuffer: 1024 * 1024, windowsHide: true, ...options }, error => {
+    resolveRun({ status: error ? error.code || 1 : 0, error })
+  })
+})
 
-/**
- * 取"官方期望的 sha256"（2026-10-26 收紧）：
- *   · PyPI wheel：镜像 JSON 里自带的 `digests.sha256`（拿不到 ⇒ 这个源作废，不再"跳过校验"）
- *   · GitHub 资产：**永远从 GitHub 官方地址**取 `<文件名>.sha256` ——
- *     ⚠️ 不能跟着下载走同一个代理：恶意代理可以把压缩包和校验值一起换掉，
- *     那份"校验"只是给使用者虚假的安全感。取不到官方值 ⇒ 拒绝使用这个源。
- */
-async function expectedSha(source, officialUrl) {
-  if (source.sha) return String(source.sha).toLowerCase()
-  try {
-    const r = await fetch(String(officialUrl || source.url) + '.sha256')
-    if (!r.ok) return null
-    const m = /([0-9a-f]{64})/i.exec(await r.text())
-    return m ? m[1].toLowerCase() : null
-  } catch { return null }
+export function uvAssetFor(platform = process.platform, arch = process.arch, libc = 'gnu') {
+  const cpu = { x64: 'x86_64', arm64: 'aarch64', ia32: 'i686' }[arch]
+  if (!cpu) return null
+  if (platform === 'win32') return { name: `uv-${cpu}-pc-windows-msvc.zip`, bin: 'uv.exe', wheel: { x64: 'win_amd64', arm64: 'win_arm64', ia32: 'win32' }[arch] }
+  if (platform === 'darwin' && arch !== 'ia32') return { name: `uv-${cpu}-apple-darwin.tar.gz`, bin: 'uv' }
+  if (platform === 'linux') return { name: `uv-${cpu}-unknown-linux-${libc === 'musl' ? 'musl' : 'gnu'}.tar.gz`, bin: 'uv' }
+  return null
 }
 
-/** 在目录树里按文件名找可执行文件（递归） */
 export function findBin(name, dir) {
-  let entries = []
+  let entries
   try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return null }
-  for (const e of entries) {
-    const p = join(dir, e.name)
-    if (e.isDirectory()) { const hit = findBin(name, p); if (hit) return hit }
-    else if (e.name === name) return p
+  for (const entry of entries) {
+    if (entry.isSymbolicLink()) continue
+    const path = join(dir, entry.name)
+    if (entry.isDirectory()) { const hit = findBin(name, path); if (hit) return hit }
+    else if (entry.isFile() && entry.name === name) return path
   }
   return null
 }
 
-/** 解压一个压缩包并找出目标文件（tar 优先 —— Windows 自带那份能读 zip） */
-export function extractArchive(binName, archive, into) {
+export async function extractArchive(name, archive, into, run = nativeRun) {
   const attempts = [['tar', ['-xf', archive, '-C', into]], ['unzip', ['-o', archive, '-d', into]]]
-  for (const [cmd, args] of attempts) {
+  for (const [command, args] of attempts) {
     try {
-      const r = spawnSync(cmd, args, { stdio: 'ignore' })
-      if (r.status === 0) { const hit = findBin(binName, into); if (hit) return hit }
-    } catch { /* 换下一个工具 */ }
+      const result = await run(command, args, { timeout: 90_000 })
+      if (result.status === 0) { const hit = findBin(name, into); if (hit) return hit }
+    } catch { /* An unavailable extractor must not hide the next supported one. */ }
   }
   return null
 }
 
-/**
- * 确保家目录里有一份可用的 uv，返回它的路径（拿不到就返回 null）。
- * @param {{ dir: string, log?: (m: string) => void }} opts
- */
-export async function ensureUv({ dir, log = () => {} }) {
-  const a = ASSETS[process.platform] || ASSETS.linux
-  const target = join(dir, a.bin)
-  // ⭐ 2026-10-26：已存在的目标先验一下能不能跑 —— 上次中断/被 AV 拦下的半截文件不该永远被当可用
-  if (existsSync(target)) {
-    let runnable = false
-    try { const r = spawnSync(target, ['--version'], { stdio: 'ignore', timeout: 15_000 }); runnable = r.status === 0 } catch { runnable = false }
-    if (runnable) return target
-    log('  → 家里已有的 uv 跑不起来（上次没下完？被安全软件动过？）⇒ 重新弄一份')
-    try { rmSync(target, { force: true }) } catch { /* 删不掉就走下面的覆盖 */ }
+/** The deadline covers headers and the whole streamed response, including slow bodies. */
+async function consumeUvResponse(url, { fetchImpl = globalThis.fetch, timeoutMs = 120_000, maxBytes = MAX_ARCHIVE } = {}, consume) {
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(new Error('UV_DOWNLOAD_TIMEOUT')), timeoutMs)
+  try {
+    const response = await fetchImpl(url, { signal: controller.signal, redirect: 'follow' })
+    if (!response.ok) throw new Error('UV_HTTP_' + response.status)
+    if (Number(response.headers.get('content-length')) > maxBytes) throw new Error('UV_DOWNLOAD_TOO_LARGE')
+    if (!response.body) throw new Error('UV_EMPTY_RESPONSE')
+    let total = 0
+    for await (const chunk of response.body) {
+      total += chunk.length
+      if (total > maxBytes) { controller.abort(); throw new Error('UV_DOWNLOAD_TOO_LARGE') }
+      await consume(chunk)
+    }
+    if (!total) throw new Error('UV_EMPTY_RESPONSE')
+    return total
+  } finally { clearTimeout(timer); controller.abort() }
+}
+
+export async function fetchUvBytes(url, options = {}) {
+  const chunks = []
+  const length = await consumeUvResponse(url, { maxBytes: 8 * 1024 * 1024, ...options }, chunk => { chunks.push(Buffer.from(chunk)) })
+  return Buffer.concat(chunks, length)
+}
+
+/** Large binaries stream to a private exclusive file rather than buffering hundreds of MB in the host. */
+export async function downloadUvArchive(url, file, options = {}) {
+  const handle = await open(file, 'wx', 0o600)
+  const digest = createHash('sha256')
+  let complete = false
+  try {
+    await consumeUvResponse(url, options, async chunk => {
+      digest.update(chunk)
+      let offset = 0
+      while (offset < chunk.length) {
+        const { bytesWritten } = await handle.write(chunk, offset, chunk.length - offset)
+        if (!bytesWritten) throw new Error('UV_DOWNLOAD_WRITE_FAILED')
+        offset += bytesWritten
+      }
+    })
+    await handle.sync()
+    complete = true
+    return digest.digest('hex')
+  } finally {
+    await handle.close()
+    if (!complete) try { await unlink(file) } catch { /* Only this newly created file is ours. */ }
   }
+}
 
-  mkdirSync(dir, { recursive: true })
-  const tmp = join(dir, '_tmp')
-  rmSync(tmp, { recursive: true, force: true })
-  mkdirSync(tmp, { recursive: true })
+function linuxLibc() {
+  if (process.platform !== 'linux') return 'gnu'
+  try { return process.report.getReport().header.glibcVersionRuntime ? 'gnu' : 'musl' } catch { return 'gnu' }
+}
 
-  // 源按顺序试：直连 → 两个国内能用的 GitHub 加速代理（2026-10-14 实测这两条能出真 zip ✓）
-  //          → 最后兜底是 PyPI 镜像上的 uv wheel（⚠️ 那个停在 0.2.33/2024-08，能用但不是最新 ✗）
-  const asset = `https://github.com/astral-sh/uv/releases/latest/download/${a.name}`
+export function officialUvWheel(metadata, wheel) {
+  const candidates = (Array.isArray(metadata?.urls) ? metadata.urls : []).filter(entry => {
+    const filename = String(entry.filename || '')
+    if (!new RegExp('^uv-\\d+\\.\\d+\\.\\d+-py3-none-' + wheel + '\\.whl$').test(filename) || !SHA.test(String(entry.digests?.sha256 || ''))) return false
+    try { const url = new URL(entry.url); return url.protocol === 'https:' && url.hostname === 'files.pythonhosted.org' && !url.username && !url.password && !url.port } catch { return false }
+  })
+  candidates.sort((a, b) => {
+    const x = a.filename.split('-')[1].split('.').map(Number), y = b.filename.split('-')[1].split('.').map(Number)
+    return y[0] - x[0] || y[1] - x[1] || y[2] - x[2]
+  })
+  return candidates[0] || null
+}
+
+async function installUv({ dir, log, asset, fetchImpl, run, timeoutMs }) {
+  const target = join(dir, asset.bin)
+  const usable = async path => {
+    try { return (await run(path, ['--version'], { timeout: 15_000 })).status === 0 } catch { return false }
+  }
+  if (existsSync(target) && await usable(target)) return target
+  mkdirSync(dir, { recursive: true })
+  // Each installer owns its extraction tree and staging file; concurrent hosts
+  // cannot delete another installer's archive or partially overwrite uv.exe.
+  const tmp = mkdtempSync(join(dir, '.uv-install-'))
+  const staged = `${target}.${process.pid}.${randomUUID()}.staging`
+  const official = `https://github.com/astral-sh/uv/releases/latest/download/${asset.name}`
   const sources = [
-    { label: 'GitHub 直连', url: asset, file: join(tmp, a.name) },
-    { label: 'GitHub 加速代理 gh-proxy.com', url: `https://gh-proxy.com/${asset}`, file: join(tmp, a.name), official: asset },
-    { label: 'GitHub 加速代理 ghproxy.net', url: `https://ghproxy.net/${asset}`, file: join(tmp, a.name), official: asset },
+    { label: 'GitHub 官方', url: official, file: asset.name },
+    { label: 'GitHub 下载代理 gh-proxy.com', url: `https://gh-proxy.com/${official}`, file: asset.name },
+    { label: 'GitHub 下载代理 ghproxy.net', url: `https://ghproxy.net/${official}`, file: asset.name },
   ]
-  if (process.platform === 'win32') {
-    try {
-      const r = await fetch('https://pypi.tuna.tsinghua.edu.cn/pypi/uv/json')
-      const j = await r.json()
-      // ⚠️ PyPI 的 urls 顺序**不保证最新在前** ⇒ 必须按版本号自己排序挑最新（踩过：取到了 0.2.33 的老版本 ✗）
-      const verOf = (name) => { const m = /-(\d+\.\d+\.\d+(?:[.-][0-9A-Za-z.]+)?)-py3-none-win_amd64\.whl$/.exec(String(name)); return m ? m[1] : '0.0.0' }
-      const cmpVer = (a, b) => {
-        const A = verOf(a).split(/[.-]/).map(Number), B = verOf(b).split(/[.-]/).map(Number)
-        for (let i = 0; i < 4; i++) { if ((A[i] || 0) !== (B[i] || 0)) return (B[i] || 0) - (A[i] || 0) }
-        return 0
-      }
-      const w = (j.urls || [])
-        .filter((u) => /win_amd64\.whl$/.test(String(u.filename)))
-        .sort((x, y) => cmpVer(x.filename, y.filename))[0]
-      // ⭐ 2026-10-26：镜像 JSON 里的文件名要消毒后再拼路径（`..\x` / 绝对分量不能进 tmp），
-      //    且必须自带 sha256 —— 没有 digest 的源直接不用（fail closed，见下面的校验段）
-      if (w?.url && /^[\w.-]+$/.test(String(w.filename)) && w.digests?.sha256) {
-        sources.push({ label: 'PyPI 清华镜像（uv wheel）', url: w.url, file: join(tmp, String(w.filename)), sha: w.digests.sha256 })
-        log(`  （备选源已就绪：${w.filename}）`)
-      }
-    } catch (e) {
-      log(`  列 PyPI 版本时出错（不影响，继续试别的源）：${e?.message ?? e}`)
+  const bytes = (url, limit = MAX_ARCHIVE, deadline = timeoutMs) => fetchUvBytes(url, { fetchImpl, maxBytes: limit, timeoutMs: deadline })
+  let githubDigest
+  try {
+    if (asset.wheel) {
+      try {
+        // Trust metadata from PyPI itself, never a mirror that can replace both
+        // a wheel and its claimed checksum. Download hosts are restricted too.
+        const metadata = JSON.parse((await bytes('https://pypi.org/pypi/uv/json', 8 * 1024 * 1024, 20_000)).toString())
+        const wheel = officialUvWheel(metadata, asset.wheel)
+        if (wheel) sources.push({ label: 'PyPI 官方 wheel', url: wheel.url, file: wheel.filename, sha: wheel.digests.sha256.toLowerCase() })
+      } catch (error) { log('PyPI 元数据不可用，继续其他来源：' + String(error.message)) }
     }
-  }
-
-  for (const s of sources) {
-    try {
-      log(`正在下载 uv —— ${s.label}`)
-      const res = await fetch(s.url)
-      if (!res.ok) { log(`  → 返回 ${res.status}，换下一个源`); continue }
-      await pipeline(Readable.fromWeb(res.body), createWriteStream(s.file))
-      const mb = (statSync(s.file).size / 1048576).toFixed(1)
-      log(`  → 下载完成 ${mb} MB`)
-      // ⭐ 完整性校验：下载下来是要**被执行**的，必须跟官方 sha256 对上（防的是第三方代理动过包 ✗）
-      //   2026-10-26 起从"拿不到就算了"改成 **fail closed**：拿不到官方校验值 ⇒ 这个源作废，
-      //   绝不执行未校验的二进制（uv 会拉起整个 Python venv，投毒等于完整 RCE 链）。
-      const want = await expectedSha(s, s.official || asset)
-      if (!want) {
-        log('  → 拿不到官方 sha256 ⇒ 拒绝使用这个源（不执行未校验的二进制）')
-        continue
-      }
-      const gotSha = sha256Of(s.file)
-      if (gotSha !== want) {
-        log(`  → ⚠️ sha256 校验不过（期望 ${want.slice(0, 12)}… 实际 ${gotSha.slice(0, 12)}…）⇒ 丢弃这个源`)
-        continue
-      }
-      log('  → 官方 sha256 校验通过 ✓')
-      log('  → 开始解压')
-      const hit = extractArchive(a.bin, s.file, tmp)
-      if (!hit) { log('  → 解压后没找到可执行文件，换下一个源'); continue }
-      // ⭐ 原子落盘（2026-10-26）：直接 copyFileSync 被中断会留半截 uv.exe，
-      //    下次启动 `existsSync(target)` 又把它当好的（上面的可跑检查只能兜住一部分）
-      const staging = `${target}.staging`
-      copyFileSync(hit, staging)
-      try { chmodSync(staging, 0o755) } catch { /* Windows 上不需要 */ }
-      renameSync(staging, target)
+    for (const source of sources) {
       try {
-        const r = spawnSync(target, ['--version'], { stdio: 'ignore', timeout: 15_000 })
-        if (r.status !== 0) { log('  → 下载的 uv 跑不起来 ✗（校验过了但执行失败——多半是安全软件拦了）'); continue }
-        log('  → 版本检查：能跑 ✓')
-      } catch { /* 跑不起来也别拦着，后面自己会报错 */ }
-      rmSync(tmp, { recursive: true, force: true })
-      log(`  → uv 已就位：${target}`)
-      return target
-    } catch (e) {
-      log(`  → ${s.label} 失败：${e?.message ?? e}`)
+        log('正在下载 uv：' + source.label)
+        if (!source.sha && githubDigest === undefined) {
+          try {
+            const text = (await bytes(official + '.sha256', 4096, 20_000)).toString()
+            githubDigest = /\b([0-9a-f]{64})\b/i.exec(text)?.[1]?.toLowerCase() || null
+          } catch { githubDigest = null }
+        }
+        const wanted = source.sha || githubDigest
+        if (!SHA.test(String(wanted || ''))) { log('缺少官方 SHA-256，已跳过该来源'); continue }
+        const file = join(tmp, randomUUID() + '-' + source.file)
+        const digest = await downloadUvArchive(source.url, file, { fetchImpl, timeoutMs, maxBytes: MAX_ARCHIVE })
+        if (digest !== wanted) { log('SHA-256 不一致，已拒绝该文件'); continue }
+        const into = mkdtempSync(join(tmp, 'extract-'))
+        const executable = await extractArchive(asset.bin, file, into, run)
+        if (!executable) { log('归档中缺少可执行文件'); continue }
+        copyFileSync(executable, staged)
+        try { chmodSync(staged, 0o755) } catch { /* Windows permissions differ. */ }
+        if (!await usable(staged)) { log('uv 版本检查失败，未替换目标文件'); continue }
+        renameSync(staged, target)
+        if (!await usable(target)) { log('uv 安装后不可执行'); continue }
+        log('uv 已通过官方校验和版本检查')
+        return target
+      } catch (error) { log(source.label + ' 失败：' + String(error.message)) }
     }
+    log('未获得通过官方校验且可执行的 uv。可手动安装 Python/uv 后重试。')
+    return null
+  } finally {
+    try { rmSync(staged, { force: true }) } catch { /* Never remove another installer staging file. */ }
+    rmSync(tmp, { recursive: true, force: true })
   }
-
-  rmSync(tmp, { recursive: true, force: true })
-  log('所有源都没拿到**通过官方校验**的 uv（网络到不了 GitHub / PyPI 镜像，或代理给的包校验不过）。'
-    + '可以手动下载 uv 放进上面那个目录，或先在机器上装好 uv 再点安装。')
-  return null
 }
+
+/** Optional I/O implementations make install failures testable without executing a downloaded binary. */
+export function ensureUv({ dir, log = () => {}, fetchImpl = globalThis.fetch, run = nativeRun,
+  platform = process.platform, arch = process.arch, libc = linuxLibc(), timeoutMs = 120_000 }) {
+  const asset = uvAssetFor(platform, arch, libc)
+  if (!asset) { log(`当前平台不支持自动下载 uv：${platform}/${arch}`); return Promise.resolve(null) }
+  const destination = resolve(dir)
+  const key = destination + '/' + asset.name
+  if (inflight.has(key)) return inflight.get(key)
+  const pending = installUv({ dir: destination, log, asset, fetchImpl, run, timeoutMs }).finally(() => inflight.delete(key))
+  inflight.set(key, pending)
+  return pending
+}