@noob-stupid/dsh-plugin-console 0.5.16 → 0.5.18

package/lib/server/infra/exec.js

@@ -66,7 +66,8 @@ async function runPnpmWithFallback(args, { execOpts = {}, runners = resolvePnpmR
     const wrapped = new Error(`${String(error?.message ?? 'pnpm 执行失败')}｜真实输出：${detail}`)
     // 保真：包装新 Error 时别把"结构性信息"丢掉（是不是超时/被杀、哪个 pid、哪个退出码）。
     // 丢了这些字段，上层就无法只对"网络类超时"做定向长超时重试（见 domain/install-diagnose.js）。
-    for (const key of ['killed', 'timedOut', 'timeoutMs', 'signal', 'code', 'pid', 'cmd']) {
+    // 2026-09-26（加法）：waitedMs / exited 也要带上 —— 上一条修复靠它们说明"树是不是真的退出了"。
+    for (const key of ['killed', 'timedOut', 'timeoutMs', 'signal', 'code', 'pid', 'cmd', 'waitedMs', 'exited']) {
       if (error?.[key] !== undefined) wrapped[key] = error[key]
     }
     return wrapped
@@ -89,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',
@@ -174,23 +184,49 @@ function killProcessTree(pid, deps = {}) {
   } catch { return false }
 }
 
+/** 「杀完树要等它真退出」的默认上限与轮询间隔（2026-09-26 本次改错，见 execFileWithKillTree 注释）。 */
+const KILL_WAIT_MS = 2000
+const KILL_WAIT_POLL_MS = 60
+
 /** 带"超时/中断即杀整棵进程树"的 execFile 替身（2026-09-26 新增，**只加不改**：`execFileAsync` 原样保留，
  * curl / tar / gh 等调用点继续用它）。
  * 与 execFileAsync 的差别**只在失败路径**：① 超时（opts.timeout）② AbortSignal 中断 —— 两条都先
  * `killProcessTree(child.pid)` 收掉整棵树，再把"超时多少毫秒 + 已终止的 pid"写进错误消息
  * （旧代码超时只 kill 父进程，报错也只有一句 `Command failed: …`，用户与日志都看不出发生了什么）。
  * 成功路径的 resolve 形状（{stdout, stderr}）与既有异常字段（message/stderr/stdout/code/killed/signal）
- * 保持一致，调用方无需改动；`detached` 仅为 POSIX 成组（Windows 上保持 false，避免弹新控制台窗口）。 */
+ * 保持一致，调用方无需改动；`detached` 仅为 POSIX 成组（Windows 上保持 false，避免弹新控制台窗口）。
+ *
+ * 2026-09-26（本次改错）：杀完树后**有界等待它真的退出**，然后才 resolve/reject。
+ * 旧代码是 `killTreeNow(); finish(killedError(…))` —— 同一个 tick 完成，**约 +1ms 就抛**"已终止整棵进程树"，
+ * 而整棵树实际还要一会儿才从进程表/句柄表消失：POSIX 上 SIGKILL 的"投递 → 目标被调度死亡 → 被 init 收割"
+ * 是异步的（CI run 36246293996 实测约 120ms，见 tests/test-pnpm-kill-tree.mjs 注释）；本机 Windows 上
+ * taskkill /F /T 虽是同步等待，但目录项/句柄释放仍会晚一拍（2026-09-26 探针实测 278ms 才可删）。
+ * 于是调用方（pnpmRemove 后立刻删目录、install 失败清场、.tryN 残留清理）仍会撞"文件被占用"。
+ * 现在：轮询 `processAlive(pid)`，最多 killWaitMs（默认 2000ms）、每 killWaitPollMs（默认 60ms）一次；
+ * 到点仍未退出**不阻塞**，照原路径收尾，并把 waitedMs / exited 如实写在错误对象上（上层可据此判断）。
+ * 成功路径一个字没改 —— 只有超时/中断/超 maxBuffer 这三条失败路径会走到收尾逻辑。
+ * `deps.alive / deps.sleep / deps.now` 只为单测注入，生产调用不传。 */
 function execFileWithKillTree(bin, argv, opts = {}, deps = {}) {
-  const { killTree = killProcessTree, spawnFn = spawn, platform = process.platform } = deps
+  const {
+    killTree = killProcessTree,
+    spawnFn = spawn,
+    platform = process.platform,
+    alive = processAlive,
+    sleep = (ms) => new Promise((resolved) => { setTimeout(resolved, ms) }),
+    now = Date.now,
+  } = deps
   const timeout = Number.isFinite(opts.timeout) && opts.timeout > 0 ? opts.timeout : 0
   const maxBuffer = Number.isFinite(opts.maxBuffer) && opts.maxBuffer > 0 ? opts.maxBuffer : 1024 * 1024
+  const killWaitMs = Number.isFinite(opts.killWaitMs) && opts.killWaitMs >= 0 ? opts.killWaitMs : KILL_WAIT_MS
+  const killWaitPollMs = Number.isFinite(opts.killWaitPollMs) && opts.killWaitPollMs > 0 ? opts.killWaitPollMs : KILL_WAIT_POLL_MS
   const signal = opts.signal ?? null
   return new Promise((resolve, reject) => {
     const cmd = `${bin} ${argv.join(' ')}`
     let child = null
     let timer = null
     let settled = false
+    let terminating = false // 收尾进行中（要先把"树真的退出"等完）→ close/error 不许抢答
+    let terminatePromise = null
     let stdout = ''
     let stderr = ''
     const baseError = () => {
@@ -200,20 +236,49 @@ function execFileWithKillTree(bin, argv, opts = {}, deps = {}) {
       err.stderr = stderr
       return err
     }
-    const killTreeNow = () => {
-      try { return killTree(child?.pid) } catch { return false }
-    }
-    /** 超时/中断错误：必须说清"已经终止了整棵树、pid 是多少"，否则用户只能看到一句 Command failed。 */
-    const killedError = (reason) => {
+    /** 超时/中断错误：必须说清"已经终止了整棵树、pid 是多少、等它的结果是怎样"，
+     * 否则用户只能看到一句 Command failed，上层也无法判断"现在删目录安不安全"。 */
+    const killedError = (reason, waited = null) => {
       const err = baseError()
+      const waitedMs = waited === null ? 0 : waited.waitedMs
+      const exited = waited === null ? true : waited.exited === true
       err.killed = true
       err.signal = 'SIGTERM'
       err.timedOut = reason === 'timeout'
       err.timeoutMs = timeout
       err.pid = child?.pid ?? null
-      err.message += `\n（${reason === 'timeout' ? `超时 ${timeout}ms` : '收到中断信号'}：已终止整棵进程树 pid=${child?.pid ?? '?'}）`
+      err.waitedMs = waitedMs // 为"树真的退出"等了多久（加法字段，旧调用方读不到也不受影响）
+      err.exited = exited // 等到上限时树是否已经退出（true=句柄已释放，可以立刻删目录）
+      const why = reason === 'timeout' ? `超时 ${timeout}ms` : (reason === 'abort' ? '收到中断信号' : 'stdout 超过 maxBuffer')
+      err.message += `\n（${why}：已终止整棵进程树 pid=${child?.pid ?? '?'}，等待 ${waitedMs}ms 后${exited ? '确认已退出' : '仍未退出（到点不阻塞，按原路径继续）'}）`
       return err
     }
+    /** 轮询等"整棵树真的退出"（有界）。进程号拿不到/已退出 → 0ms 返回 exited:true。 */
+    const waitTreeGone = async (targetPid) => {
+      const startedAt = now()
+      if (typeof targetPid !== 'number' || targetPid <= 0) return { waitedMs: 0, exited: true }
+      for (;;) {
+        let up = false
+        try { up = alive(targetPid) === true } catch { up = false }
+        if (!up) return { waitedMs: now() - startedAt, exited: true }
+        const elapsed = now() - startedAt
+        if (elapsed >= killWaitMs) return { waitedMs: elapsed, exited: false }
+        // eslint-disable-next-line no-await-in-loop
+        await sleep(Math.max(1, Math.min(killWaitPollMs, killWaitMs - elapsed)))
+      }
+    }
+    /** 收尾（杀树 + 等退出）：同一轮里只做一次（重复调用复用同一个 promise）。 */
+    const terminate = () => {
+      if (terminatePromise !== null) return terminatePromise
+      terminating = true
+      terminatePromise = (async () => {
+        let killed = false
+        try { killed = killTree(child?.pid) === true } catch { killed = false }
+        const waited = await waitTreeGone(child?.pid)
+        return { killed, waitedMs: waited.waitedMs, exited: waited.exited }
+      })()
+      return terminatePromise
+    }
     const cleanup = () => {
       if (timer !== null) { clearTimeout(timer); timer = null }
       if (signal !== null && typeof signal.removeEventListener === 'function') signal.removeEventListener('abort', onAbort)
@@ -225,7 +290,7 @@ function execFileWithKillTree(bin, argv, opts = {}, deps = {}) {
       if (error === null) resolve(value)
       else reject(error)
     }
-    const onAbort = () => { killTreeNow(); finish(killedError('abort'), null) }
+    const onAbort = () => { void terminate().then((waited) => finish(killedError('abort', waited), null)) }
     if (signal !== null) {
       if (signal.aborted === true) { finish(killedError('abort'), null); return }
       if (typeof signal.addEventListener === 'function') signal.addEventListener('abort', onAbort, { once: true })
@@ -239,16 +304,23 @@ function execFileWithKillTree(bin, argv, opts = {}, deps = {}) {
       })
     } catch (error) { finish(error, null); return }
     const overflow = () => {
-      killTreeNow()
-      const err = baseError()
-      err.code = 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER'
-      err.message = `stdout maxBuffer length exceeded\n${err.message}`
-      finish(err, null)
+      if (terminating) return // 收尾中：复用同一次杀树+等待，不重复触发
+      void terminate().then((waited) => {
+        const err = baseError()
+        err.code = 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER'
+        err.message = `stdout maxBuffer length exceeded\n${err.message}`
+        err.waitedMs = waited.waitedMs
+        err.exited = waited.exited
+        finish(err, null)
+      })
     }
     child.stdout?.on?.('data', (chunk) => { stdout += String(chunk); if (stdout.length + stderr.length > maxBuffer) overflow() })
     child.stderr?.on?.('data', (chunk) => { stderr += String(chunk); if (stdout.length + stderr.length > maxBuffer) overflow() })
-    child.on('error', (error) => { finish(error, null) })
+    // 收尾（超时/中断/超限）要先把"树真的退出"等完才 settle → 这期间 close/error 不许抢答，
+    // 否则 killedError（含 pid/timedOut/exited/waitedMs）会被一句 `code=null 的普通失败` 顶掉。
+    child.on('error', (error) => { if (terminating) return; finish(error, null) })
     child.on('close', (code) => {
+      if (terminating) return
       if (code === 0) { finish(null, { stdout, stderr }); return }
       const err = baseError()
       err.code = typeof code === 'number' ? code : null
@@ -256,7 +328,7 @@ function execFileWithKillTree(bin, argv, opts = {}, deps = {}) {
       err.signal = null
       finish(err, null)
     })
-    if (timeout > 0) timer = setTimeout(() => { killTreeNow(); finish(killedError('timeout'), null) }, timeout)
+    if (timeout > 0) timer = setTimeout(() => { void terminate().then((waited) => finish(killedError('timeout', waited), null)) }, timeout)
   })
 }
 
@@ -292,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),
   }
 }
@@ -359,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, 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 }

package/lib/server/infra/fsx.js

@@ -1,8 +1,9 @@
 // 由 Step 1 搬运工具从 lib/index.js 原样切出（只移动、未改逻辑）
 // 分组见 D:\dsh\dsh-plugin-hub-plan\architecture.zh.md §三 L0 · infra
 
-import { existsSync, rmSync, readdirSync, mkdirSync, copyFileSync, chmodSync, lstatSync } from 'node:fs'
+import { existsSync, rmSync, readdirSync, mkdirSync, copyFileSync, chmodSync, lstatSync, renameSync } from 'node:fs'
 import { dirname, join, basename } from 'node:path'
+import { tmpdir } from 'node:os'
 import { execFile } from 'node:child_process'
 import { execFileSync } from 'node:child_process'
 import { promisify } from 'node:util'
@@ -119,13 +120,13 @@ function waitGone(dir, timeoutMs) {
 }
 
 /** 外部删除兜底：实测本机 PowerShell/.NET 能删掉 Node `rmSync` 静默删不掉的树。 */
-async function removeViaShell(dir) {
+async function removeViaShell(dir, timeoutMs = 120000) {
   try {
     if (process.platform === 'win32') {
-      await execFileAsync('cmd.exe', ['/c', 'rmdir', '/s', '/q', dir], { windowsHide: true, timeout: 120000 })
+      await execFileAsync('cmd.exe', ['/c', 'rmdir', '/s', '/q', dir], { windowsHide: true, timeout: timeoutMs })
       return { ok: true, method: 'rmdir' }
     }
-    await execFileAsync('rm', ['-rf', '--', dir], { timeout: 120000 })
+    await execFileAsync('rm', ['-rf', '--', dir], { timeout: timeoutMs })
     return { ok: true, method: 'rm' }
   } catch (error) {
     return { ok: false, method: null, error: error instanceof Error ? error.message : String(error) }
@@ -138,8 +139,9 @@ async function removeViaShell(dir) {
  * 为什么不能只用 `rmSync` + 立刻 `existsSync`：真机上出现过「`rmSync` 不抛错、目录仍在」，
  * 面板于是报「有 N 项没能删除（目录仍存在）——当前环境可能禁止删除」，把用户引向并不存在的权限问题；
  * 实测同一棵树用 .NET/PowerShell 能删掉，所以这里补上兜底与轮询，并把真实错误码带回去。
- */
-async function removeDirVerifiedAsync(dir, { attempts = 2, pollMs = 600 } = {}) {
+ * `shellTimeoutMs` 是 2026-09-26 的加法参数（默认 120000＝旧行为），只为后台清理用：它不想让一条
+ * 卡住的 `rmdir` 占着两分钟。 */
+async function removeDirVerifiedAsync(dir, { attempts = 2, pollMs = 600, shellTimeoutMs = 120000 } = {}) {
   let lastError = null
   let method = null
   for (let attempt = 1; attempt <= attempts; attempt += 1) {
@@ -151,7 +153,7 @@ async function removeDirVerifiedAsync(dir, { attempts = 2, pollMs = 600 } = {})
       lastError = error
     }
     if (await waitGone(dir, pollMs)) return { ok: true, attempts: attempt, method: 'rmSync', error: null }
-    const shell = await removeViaShell(dir)
+    const shell = await removeViaShell(dir, shellTimeoutMs)
     if (shell.ok && await waitGone(dir, pollMs * 3)) return { ok: true, attempts: attempt, method: shell.method, error: null }
     if (shell.error !== undefined && shell.error !== null) lastError = shell.error
   }
@@ -209,4 +211,188 @@ function removeDirVerifiedWithRetry(dir, { attempts = 3, pollMs = 250, remover =
   return { ok: false, attempts: last?.attempts ?? 0, rounds: attempts, method: null, error: last?.error ?? null }
 }
 
-export { copyTree, queuedWrite, cleanupStalePackageDir, removeDirVerified, removeDirVerifiedAsync, removeDirVerifiedWithRetry, removeViaShellSync, sleepSync, clearReadonly, waitGone, removeViaShell, writeQueue }
+/** 「删除失败就改名降级」用的占用判据（2026-09-26 加法）。
+ * 借自 2BingLing/dsh-market 的 plugin/core/src/installer.ts#isLockFailure（正则逐字沿用）：
+ * 命中即"占用/权限类失败"——这类失败**重试也不会好**，该做的是把目录改名让开、交给后台清理，
+ * 而不是把「请手动删除」甩给用户。 */
+function isLockFailure(outputOrMessage) {
+  return /EPERM|EACCES|EBUSY|being used by another process|resource busy|in use by another|Access is denied|Cannot create file/iu.test(String(outputOrMessage ?? ''))
+}
+
+const TRASH_PREFIX = '.trash-'
+const TRASH_RE = /^\.trash-\d+-[A-Za-z0-9]{1,16}$/u
+const TRASH_SCAN_MAX_DEPTH = 2
+const TRASH_CLEAN_LIMIT = 20
+const TRASH_CLEAN_ITEM_MS = 1000
+
+/** `.trash-<时间戳>-<随机>`：与目标**同父目录**（同卷 rename 才可能成功）。 */
+function trashPathFor(dir, { now = Date.now, random = Math.random } = {}) {
+  const suffix = Math.floor(random() * 0xffffffff).toString(36).slice(0, 8) || '0'
+  return join(dirname(dir), `${TRASH_PREFIX}${now()}-${suffix}`)
+}
+
+/**
+ * 目录删除的唯一健壮入口（2026-09-26 加法）：**先删，删不掉就改名降级**。
+ *   ① `removeDirVerifiedWithRetry`（清只读位 → rmSync → 轮询核实 → `rmdir /s /q` 兜底，3 轮 × 250ms）
+ *   ② 仍失败 → 同父目录 rename 成 `.trash-<ts>-<rand>`，返回 `{ status:'trashed', trashPath }`
+ * 为什么 rename 能救（做法借自 2BingLing/dsh-market 的 `.bak-<ts>` + renameSync）：
+ * rename **不动目录内容**、只改目录项，所以"目录里有进程正在用的文件"这类占用通常挡不住它；
+ * 改完原路径就空出来了，调用方可以继续（install 能落新包、`.tryN` 能重来、卸载能收尾）。
+ * ⚠️ 实测边界（2026-09-26 本机探针，真机段见 tests/test-trash-fallback.mjs）——占用形态决定成败：
+ *    · 目录里有**正在运行的 exe**（该文件句柄带 FILE_SHARE_DELETE）→ 删不掉，但**改名成功** ✅
+ *    · 目录是活进程的 cwd → 改名 EBUSY（内核不允许改 cwd 的名字）
+ *    · 目录内有以 share=None 打开的**文件句柄** → 改名 EPERM（父目录项被锁）
+ *   后两种改名也失败时如实返回 `status:'failed'` + 明确原因；**任何分支都不再出现「请手动删除」**，
+ *   因为后台清理（cleanupTrashDirs）会继续试、下一次安装前也会再试。
+ * 返回：`{ status:'removed'|'trashed'|'failed', removed, trashed, ok, path, trashPath, reason,
+ *          attempts, rounds, method, lockFailure }` —— `ok` 的含义是"**原路径已经让开**"。
+ * deps（remover/removerOpts/rename/exists/now/random）只为单测注入，生产调用不传。 */
+function disposeDir(dir, deps = {}) {
+  const {
+    remover = removeDirVerifiedWithRetry,
+    removerOpts = {},
+    rename = renameSync,
+    exists = existsSync,
+    now = Date.now,
+    random = Math.random,
+  } = deps
+  const target = String(dir ?? '')
+  const base = { path: target, trashPath: null, attempts: 0, rounds: 0, method: null, lockFailure: false }
+  if (target === '') return { ...base, status: 'failed', removed: false, trashed: false, ok: false, reason: '没有给出目录路径' }
+  if (!exists(target)) return { ...base, status: 'removed', removed: true, trashed: false, ok: true, reason: 'already-gone', method: 'already-gone' }
+  let first = null
+  try {
+    first = remover(target, removerOpts)
+  } catch (error) {
+    first = { ok: false, attempts: 0, rounds: 0, error: error instanceof Error ? error.message : String(error) }
+  }
+  const attempts = first?.attempts ?? 0
+  const rounds = first?.rounds ?? 0
+  const reason = first?.error ?? '删除后目录仍存在（未抛出错误：Windows 删除挂起或占用）'
+  if (first?.ok === true) {
+    return { ...base, status: 'removed', removed: true, trashed: false, ok: true, reason: first.method ?? 'rmSync', attempts, rounds, method: first.method ?? 'rmSync' }
+  }
+  // ② 改名降级：同父目录（同卷）；候选名撞了就换一个（最多 3 次）
+  // lockFailure 的判据除了 isLockFailure 的正则，还包括"**没报错但目录仍在**"这种静默失败 ——
+  // removeDirVerifiedWithRetry 自己把这种形态注释为「Windows 删除挂起或占用」，真机实测也确实如此
+  // （占用中 rmSync 不抛、目录原封不动）。判成占用，前端口径才与事实一致；判错的代价只是措辞。
+  const lockFailure = isLockFailure(reason) || first?.error === null || first?.error === undefined
+  let trashPath = null
+  let renameError = null
+  for (let round = 0; round < 3 && trashPath === null; round += 1) {
+    const candidate = trashPathFor(target, { now, random })
+    try {
+      if (exists(candidate)) { renameError = new Error(`降级目标名已存在：${basename(candidate)}`); continue }
+      rename(target, candidate)
+      trashPath = candidate
+    } catch (error) { renameError = error }
+  }
+  if (trashPath === null) {
+    const detail = renameError instanceof Error ? renameError.message : String(renameError ?? '未知')
+    return { ...base, status: 'failed', removed: false, trashed: false, ok: false, attempts, rounds, lockFailure, reason: `${lockFailure ? '目录被占用' : '删除未成功'}，改名降级也失败（${detail}）；原删除失败原因：${reason}` }
+  }
+  return { ...base, status: 'trashed', removed: false, trashed: true, ok: true, trashPath, reason, attempts, rounds, method: 'rename', lockFailure }
+}
+
+/** 面向前端的短句（纯函数，单测覆盖）：**不再出现「请手动删除」**——
+ * 删不掉时我们自己做了 rename 降级 + 后台重试，用户不需要去命令行干活。 */
+function disposeNote(result) {
+  const status = result?.status
+  if (status === 'removed') return '已删除'
+  if (status === 'trashed') {
+    const name = basename(String(result?.trashPath ?? '')) || `${TRASH_PREFIX}*`
+    return `${result?.lockFailure === true ? '目录正被占用' : '删除未成功'}，已改名降级为 ${name}（${TRASH_PREFIX}*），稍后自动清理`
+  }
+  return `删除未成功，改名降级也没成（${result?.reason ?? '原因未知'}）；控制台会在后台自动重试清理`
+}
+
+/** 常见降级目录扫描根：系统 tmpdir + profile 的 node_modules（含一级作用域目录）+ 调用方补充的目录（如 repos 根）。 */
+function trashScanRoots({ profileDir = '', extra = [] } = {}) {
+  const roots = [tmpdir()]
+  if (typeof profileDir === 'string' && profileDir !== '') roots.push(join(profileDir, 'node_modules'))
+  for (const dir of Array.isArray(extra) ? extra : [extra]) if (typeof dir === 'string' && dir !== '') roots.push(dir)
+  return roots
+}
+
+/** 扫出根目录下（深度 ≤ maxDepth）的 `.trash-*`，按名字升序（= 由旧到新，先清最老的）。
+ * 任何一步读不到就跳过、绝不抛 —— 后台清理是尽力而为，不能让一个坏目录把主流程带崩。 */
+function findTrashDirs(roots, { maxDepth = TRASH_SCAN_MAX_DEPTH, limit = 40, readdir = readdirSync, exists = existsSync } = {}) {
+  const out = []
+  const walk = (dir, depth) => {
+    if (out.length >= limit || depth > maxDepth) return
+    let entries
+    try { entries = readdir(dir, { withFileTypes: true }) } catch { return }
+    for (const entry of entries) {
+      if (out.length >= limit) return
+      if (!entry.isDirectory()) continue
+      if (TRASH_RE.test(entry.name)) { out.push(join(dir, entry.name)); continue }
+      if (depth < maxDepth) walk(join(dir, entry.name), depth + 1)
+    }
+  }
+  for (const root of Array.isArray(roots) ? roots : [roots]) {
+    const dir = String(root ?? '')
+    if (dir === '') continue
+    try { if (exists(dir)) walk(dir, 1) } catch {}
+  }
+  return out.sort()
+}
+
+/** 后台清理 `.trash-*`（2026-09-26 加法：尽力而为、绝不阻塞主流程、绝不抛）：
+ * 扫 tmpdir / profile node_modules / repos 等根目录下的降级目录，能删就删，删不掉留着下次；
+ * 上限：最多处理 limit 个（默认 20）、单个最多等 perItemMs（默认 1000ms，到点就不管它、继续下一个）；
+ * 任何异常都吞掉只记日志。返回 `{ scanned, removed, kept, skipped, more, ms, dirs, error }`（如实，不假装成功）：
+ * `scanned` 是本次**扫到**的数量（扫到 limit+1 就收手 → `more:true` 表示盘上还有更多）、
+ * `skipped` = 扫到但没处理的数量。deps（remover/find/now/log）只为单测注入。 */
+async function cleanupTrashDirs({
+  roots = [tmpdir()],
+  limit = TRASH_CLEAN_LIMIT,
+  perItemMs = TRASH_CLEAN_ITEM_MS,
+  maxDepth = TRASH_SCAN_MAX_DEPTH,
+  remover = removeDirVerifiedAsync,
+  find = findTrashDirs,
+  now = Date.now,
+  log = null,
+} = {}) {
+  const startedAt = now()
+  const stats = { scanned: 0, removed: 0, kept: 0, skipped: 0, more: false, ms: 0, dirs: [], error: null }
+  try {
+    const found = find(roots, { maxDepth, limit: limit + 1 }) ?? []
+    stats.scanned = found.length
+    stats.skipped = Math.max(0, found.length - limit)
+    stats.more = found.length > limit // 扫到 limit+1 就收手：盘上至少还有更多（如实标注，不假装扫全了）
+    for (const dir of found.slice(0, limit)) {
+      try {
+        const timeout = new Promise((resolved) => {
+          // 注意：这里**不能** unref —— 单个删不掉的降级目录会让事件循环无事可做，
+          // unref 过的定时器不阻止退出，本函数就会"永远不 settle"（本测试抓到的真实缺陷）。
+          setTimeout(() => resolved({ ok: false, method: null, error: `超过 ${perItemMs}ms 没删完（留到下次）` }), perItemMs)
+        })
+        // eslint-disable-next-line no-await-in-loop
+        const r = await Promise.race([remover(dir, { attempts: 1, pollMs: Math.min(400, Math.max(0, perItemMs)), shellTimeoutMs: Math.max(4000, perItemMs * 4) }), timeout])
+        if (r?.ok === true) { stats.removed += 1; stats.dirs.push({ path: dir, ok: true, method: r.method ?? null }) }
+        else { stats.kept += 1; stats.dirs.push({ path: dir, ok: false, error: r?.error ?? null }) }
+      } catch (error) {
+        stats.kept += 1
+        stats.dirs.push({ path: dir, ok: false, error: error instanceof Error ? error.message : String(error) })
+      }
+    }
+  } catch (error) {
+    stats.error = error instanceof Error ? error.message : String(error)
+  }
+  stats.ms = now() - startedAt
+  try {
+    if (typeof log === 'function') log(`[trash] 扫描 ${stats.scanned} 个 ${TRASH_PREFIX}*，删除 ${stats.removed}、保留 ${stats.kept}、跳过 ${stats.skipped}，用时 ${stats.ms}ms`)
+  } catch {}
+  return stats
+}
+
+/** 启动钩子/安装前调用的**即发即忘**入口：绝不抛、绝不阻塞调用方（返回的 promise 自带兜底 catch）。 */
+function startTrashCleanup(opts = {}) {
+  try {
+    return Promise.resolve(cleanupTrashDirs(opts)).catch((error) => ({ scanned: 0, removed: 0, kept: 0, skipped: 0, ms: 0, dirs: [], error: error instanceof Error ? error.message : String(error) }))
+  } catch (error) {
+    return Promise.resolve({ scanned: 0, removed: 0, kept: 0, skipped: 0, ms: 0, dirs: [], error: error instanceof Error ? error.message : String(error) })
+  }
+}
+
+export { copyTree, queuedWrite, cleanupStalePackageDir, removeDirVerified, removeDirVerifiedAsync, removeDirVerifiedWithRetry, removeViaShellSync, sleepSync, clearReadonly, waitGone, removeViaShell, writeQueue, isLockFailure, trashPathFor, disposeDir, disposeNote, trashScanRoots, findTrashDirs, cleanupTrashDirs, startTrashCleanup, TRASH_PREFIX, TRASH_RE, TRASH_CLEAN_LIMIT, TRASH_CLEAN_ITEM_MS }

package/lib/server/routes/components.js

@@ -8,7 +8,7 @@ import { compFind, compStart, compStatus, compStop, compUiUrl, compUpsert, findC
 import { getReposDir, listLandedRepos, setReposDir } from '../domain/repoland.js'
 import { gitCloneUrls } from '../domain/sources.js'
 import { execFileAsync, gitBin, gitEnv } from '../infra/exec.js'
-import { removeDirVerified } from '../infra/fsx.js'
+import { disposeDir, disposeNote } from '../infra/fsx.js'
 import { sendError, sendJson } from '../infra/httpd.js'
 
 async function routeComponents(req, res, rc) {
@@ -75,7 +75,8 @@ async function routeRepoClone(req, res, rc) {
         } catch (error) {
           lastError = error
           // 失败可能留下半成品目录，清理后再试下一个源，否则会因目标已存在而连环失败
-          removeDirVerified(target)
+          // （删不掉时 disposeDir 会改名降级成 .trash-*，原路径照样让开）
+          disposeDir(target)
         }
       }
       if (!cloned) throw lastError ?? new Error('未知错误')
@@ -135,12 +136,16 @@ async function routeRepoRemove(req, res, rc) {
     }
     // 核实删除结果：本机环境可能让 rmSync 静默落空（见 removeDirVerified 注释），
     // 删不掉却回 {ok:true} 会让用户以为仓库已清理。
-    const result = removeDirVerified(target)
-    if (!result.ok) {
-      sendError(res, 500, `删除失败：目录仍存在（${target}）${result.error ? `，原因：${result.error}` : ''}——当前环境可能禁止删除该目录，请手动删除`)
+    // 2026-09-26（本次改错）：走 disposeDir —— 删不掉就改名降级成同父目录的 `.trash-<ts>`，
+    // 原路径已经让开就算成功，并如实把降级结果告诉用户（不再出现「请手动删除」）。
+    const result = disposeDir(target)
+    if (result.ok !== true) {
+      sendError(res, 500, `删除失败：目录仍存在（${target}）——${disposeNote(result)}`)
       return
     }
-    sendJson(res, 200, { ok: true })
+    sendJson(res, 200, result.trashed === true
+      ? { ok: true, trashed: true, trashPath: result.trashPath, note: disposeNote(result) }
+      : { ok: true })
     return
 }
 

package/lib/server/routes/skills.js

@@ -4,7 +4,7 @@
 import { existsSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 import { listInstalledSkills, setSkillEnabled } from '../domain/skills.js'
-import { removeDirVerified } from '../infra/fsx.js'
+import { disposeDir, disposeNote } from '../infra/fsx.js'
 import { sendError, sendJson } from '../infra/httpd.js'
 import { dshHome } from '../infra/paths.js'
 
@@ -56,12 +56,16 @@ async function routeSkillRemove(req, res, rc) {
     }
     // 删完必须核实：本机环境可能让 rmSync 静默落空（见 removeDirVerified 注释），
     // 旧代码删完直接 {ok:true} → 用户以为删了，技能其实还在（2026-09-20 演练实测）。
-    const result = removeDirVerified(dest)
-    if (!result.ok) {
-      sendError(res, 500, `删除技能失败：目录仍存在（${dest}）${result.error ? `，原因：${result.error}` : ''}——当前环境可能禁止删除该目录，请手动删除它`)
+    // 2026-09-26（本次改错）：走 disposeDir —— 删不掉就改名降级成同父目录的 `.trash-<ts>`，
+    // 原路径让开即算完成；失败文案只讲真实原因与"后台会自动重试"，不再要求用户手动删除。
+    const result = disposeDir(dest)
+    if (result.ok !== true) {
+      sendError(res, 500, `删除技能失败：目录仍存在（${dest}）——${disposeNote(result)}`)
       return
     }
-    sendJson(res, 200, { ok: true, name })
+    sendJson(res, 200, result.trashed === true
+      ? { ok: true, name, trashed: true, trashPath: result.trashPath, note: disposeNote(result) }
+      : { ok: true, name })
     return
 }
 

package/lib/server/routes/sources.js

@@ -401,6 +401,85 @@ async function routeSources(req, res, rc) {
       sendJson(res, 200, { ok: true, sources: maskSources(sources) })
       return
     }
+    if (action === 'add-archive') {
+      // archive 通道源（批次 C-⑨）：模板必须含 {owner}/{repo}（{branch} 可选）
+      const name = typeof body.name === 'string' ? body.name.trim() : ''
+      const urlTemplate = typeof body.urlTemplate === 'string' ? body.urlTemplate.trim() : ''
+      if (!urlTemplate.includes('{owner}') || !urlTemplate.includes('{repo}')) {
+        sendError(res, 400, 'archive 源模板必须同时包含 {owner} 与 {repo} 占位符（{branch} 可选）')
+        return
+      }
+      if (!isAllowedGitSourceUrl(urlTemplate)) {
+        sendError(res, 400, 'archive 源地址必须是 https://（或本机/私网 http://、file://）的合法 URL')
+        return
+      }
+      if ((sources.archiveSources ?? []).some((s) => s.urlTemplate === urlTemplate)) {
+        sendError(res, 400, '该 archive 源已存在')
+        return
+      }
+      sources.archiveSources = [...(sources.archiveSources ?? []), {
+        id: `arc-${Date.now().toString(36)}`,
+        name: name || urlTemplate,
+        urlTemplate,
+        primary: (sources.archiveSources ?? []).length === 0,
+      }]
+      await writeSources(sources)
+      sendJson(res, 200, { ok: true, sources: maskSources(sources) })
+      return
+    }
+    if (action === 'edit-archive') {
+      const id = typeof body.id === 'string' ? body.id : ''
+      const name = typeof body.name === 'string' ? body.name.trim() : ''
+      const urlTemplate = typeof body.urlTemplate === 'string' ? body.urlTemplate.trim() : ''
+      if (!urlTemplate.includes('{owner}') || !urlTemplate.includes('{repo}')) {
+        sendError(res, 400, 'archive 源模板必须同时包含 {owner} 与 {repo} 占位符（{branch} 可选）')
+        return
+      }
+      if (!isAllowedGitSourceUrl(urlTemplate)) {
+        sendError(res, 400, 'archive 源地址必须是 https://（或本机/私网 http://、file://）的合法 URL')
+        return
+      }
+      const target = (sources.archiveSources ?? []).find((s) => s.id === id)
+      if (!target) {
+        sendError(res, 404, '没有这个 archive 源')
+        return
+      }
+      target.name = name || urlTemplate
+      target.urlTemplate = urlTemplate
+      await writeSources(sources)
+      sendJson(res, 200, { ok: true, sources: maskSources(sources) })
+      return
+    }
+    if (action === 'set-archive-primary') {
+      const id = typeof body.id === 'string' ? body.id : ''
+      const list = sources.archiveSources ?? []
+      if (!list.some((s) => s.id === id)) {
+        sendError(res, 404, '没有这个 archive 源')
+        return
+      }
+      for (const s of list) s.primary = s.id === id
+      await writeSources(sources)
+      sendJson(res, 200, { ok: true, sources: maskSources(sources) })
+      return
+    }
+    if (action === 'remove-archive') {
+      const id = typeof body.id === 'string' ? body.id : ''
+      const list = sources.archiveSources ?? []
+      if (!list.some((s) => s.id === id)) {
+        sendError(res, 404, '没有这个 archive 源')
+        return
+      }
+      const rest = list.filter((s) => s.id !== id)
+      if (rest.length === 0) {
+        sendError(res, 400, '至少保留一个 archive 源（可先添加自建镜像再删除默认源）')
+        return
+      }
+      if (!rest.some((s) => s.primary)) rest[0].primary = true
+      sources.archiveSources = rest
+      await writeSources(sources)
+      sendJson(res, 200, { ok: true, sources: maskSources(sources) })
+      return
+    }
     if (action === 'reset') {
       const defaults = JSON.parse(JSON.stringify(DEFAULT_SOURCES))
       setMarketIndexCache(null)
@@ -430,7 +509,7 @@ async function routeSources(req, res, rc) {
       sendJson(res, 200, { ok: true, sources: maskSources(sources) })
       return
     }
-    sendError(res, 400, '未知操作（add / edit / set-primary / remove / add-search / remove-search / add-index / edit-index / set-index-primary / remove-index / set-index-merge / add-git / edit-git / set-git-primary / remove-git / gitee-setup / gitee-clear / reset）')
+    sendError(res, 400, '未知操作（add / edit / set-primary / remove / add-search / remove-search / add-index / edit-index / set-index-primary / remove-index / set-index-merge / add-git / edit-git / set-git-primary / remove-git / add-archive / edit-archive / set-archive-primary / remove-archive / gitee-setup / gitee-clear / reset）')
     return
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noob-stupid/dsh-plugin-console",
-  "version": "0.5.16",
+  "version": "0.5.18",
   "description": "DSH 框架升级安全与插件升级门控：一键升级、失败自动回滚、升级后回滚上版、旧插件不适配自动禁用；内置多源插件市场为发现层，插件源全部可自定义，可指向公司内网私有源 / 私有索引 / 本地 Git 仓库，纯内网离线可用 | Framework upgrade safety & plugin version gating for DSH, with a customizable multi-source plugin market: point every source at internal mirrors or a local file:// repo for intranet-only, offline installs.",
   "repository": {
     "type": "git",