@noob-stupid/dsh-plugin-console 0.3.66 → 0.4.0

package/lib/server/domain/suite.js

@@ -0,0 +1,220 @@
+// L1 · domain —— suite.js（聚合套装：.gitmodules 解析 / 预设目录发现 / 包入口存在性；分层 Step 5 从 lib/index.js 搬出，只搬移未改逻辑。注：runSuiteInstallJob 含 ctx，留到 Step 8）
+// 分组见 D:\dsh\dsh-plugin-hub-plan\architecture.zh.md 三
+
+import { readFileSync, existsSync, rmSync, readdirSync, mkdirSync } from 'node:fs'
+import { dirname, join, basename } from 'node:path'
+import { tmpdir } from 'node:os'
+import { appendInsert } from './patch.js'
+import { gitCloneRepo } from './repoland.js'
+import { deriveEntryId, listEntries } from './runtime.js'
+import { copyTree } from '../infra/fsx.js'
+import { looksLikeGitmodules, rawTextWithFallback } from '../infra/http.js'
+import { dshHome, findPatchPath } from '../infra/paths.js'
+
+/** 解析 .gitmodules：返回 [{name, path, url}]（submodule 套装识别用）。 */
+function readGitmodules(dir) {
+  const file = join(dir, '.gitmodules')
+  if (!existsSync(file)) return []
+  const text = readFileSync(file, 'utf8')
+  const subs = []
+  let cur = null
+  for (const line of text.split(/\r?\n/u)) {
+    const m = line.match(/^\[submodule\s+"([^"]+)"\]/u)
+    if (m) {
+      cur = { name: m[1], path: '', url: '' }
+      subs.push(cur)
+      continue
+    }
+    if (!cur) continue
+    const pm = line.match(/^\s*path\s*=\s*(.+)$/u)
+    if (pm) { cur.path = pm[1].trim(); continue }
+    const um = line.match(/^\s*url\s*=\s*(.+)$/u)
+    if (um) cur.url = um[1].trim()
+  }
+  return subs.filter((s) => s.path !== '' && s.url !== '')
+}
+
+/** 递归找含 preset.yml + agent.cordis.yml 的 agent 预设目录（深度 ≤ maxDepth）。 */
+function findPresetDirs(root, maxDepth = 2) {
+  const out = []
+  const walk = (dir, depth) => {
+    if (depth > maxDepth) return
+    let entries = []
+    try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return }
+    if (existsSync(join(dir, 'preset.yml')) && existsSync(join(dir, 'agent.cordis.yml'))) {
+      out.push(dir)
+      return
+    }
+    for (const e of entries) {
+      if (!e.isDirectory() || e.name.startsWith('.')) continue
+      walk(join(dir, e.name), depth + 1)
+    }
+  }
+  walk(root, 0)
+  return out
+}
+
+/** 包是否有构建产物（main/module/exports/bin 或 lib/index.js 任一存在）。
+ * 排除类型声明（.d.ts）与 package.json 自身——exports 的 "./package.json" 是合法导出但不是运行时入口。 */
+function packageEntryExists(dir, pkg) {
+  const isEntry = (p) => typeof p === 'string' && p !== '' && !p.endsWith('.d.ts') && p !== './package.json' && p !== 'package.json'
+  const candidates = []
+  if (isEntry(pkg.main)) candidates.push(pkg.main)
+  if (isEntry(pkg.module)) candidates.push(pkg.module)
+  if (isEntry(pkg.bin)) candidates.push(pkg.bin)
+  if (pkg.bin && typeof pkg.bin === 'object') Object.values(pkg.bin).forEach((v) => { if (isEntry(v)) candidates.push(v) })
+  if (pkg.exports && typeof pkg.exports === 'object') {
+    const collect = (v) => {
+      if (typeof v === 'string') { if (isEntry(v)) candidates.push(v) }
+      else if (v && typeof v === 'object') Object.values(v).forEach(collect)
+    }
+    collect(pkg.exports)
+  }
+  candidates.push('lib/index.js', 'dist/index.js')
+  return candidates.some((c) => existsSync(join(dir, c)))
+}
+
+/** 套装探测（唯一入口）：main → master，且**必须内容像 .gitmodules**（含 [submodule "x"] 段）才算套装。
+ * 判据是内容、不是"探测非 null"：2026-09-19 用户反馈装 dsh-whale-widget 被判成 submodule 套装置仓库、
+ * clone 后报「未找到 .gitmodules」——根因就是代理/CDN 对**不存在的文件**回 2xx（空 body 也算"读到"）。 */
+async function probeGitmodules(repo) {
+  const main = await rawTextWithFallback(repo, 'main', '.gitmodules')
+  if (looksLikeGitmodules(main)) return main
+  const master = await rawTextWithFallback(repo, 'master', '.gitmodules')
+  return looksLikeGitmodules(master) ? master : null
+}
+
+/** 安装类型决策（纯函数，单测覆盖）：`.gitmodules` 的**内容**说了算——
+ * 显式 suite 请求若探测内容不像 .gitmodules 也回落普通插件安装（前端标记可能来自 24h 缓存的误判，
+ * 不能当判据）；技能请求不受影响。 */
+function resolveInstallKind(requestKind, probeText) {
+  if (requestKind === 'skill') return 'skill'
+  return looksLikeGitmodules(probeText) ? 'suite' : 'plugin'
+}
+
+/** 套装安装（submodule 聚合仓库）：照仓库 install.ps1/README 语义——
+ * clone 套装 → 手动镜像拉取子模块 → 按类型装配（bundle 插件含 Release tgz 兜底 / 普通插件 / 技能 / agent 预设）。
+ * 不执行第三方脚本本体（安全护栏：脚本型只读语义不运行）。 */
+async function runSuiteInstallJob(job, ports) {
+  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)
+    const subs = readGitmodules(tmpDir)
+    if (subs.length === 0) {
+      // 探测与仓库实际内容不符（假阳性 / 仓库已重构）：**不报失败**，把决定权交回调用方
+      // 回落普通插件安装（npm → Release → git 规格），用户不该因为一次误判装不上插件。
+      job.stage = 'detecting'
+      return { notASuite: true }
+    }
+    job.stage = 'detecting'
+    const patchPath = findPatchPath(ports)
+    const profileDir = dirname(patchPath)
+    // 手动拉取子模块（git 的 insteadOf 重写对 submodule 不生效，按镜像 URL 逐个 clone）
+    // 套装级进度：套装动辄几分钟（clone 每个子模块 + 逐个装配），面板要能显示"第 i/n 个子模块"
+    for (let si = 0; si < subs.length; si += 1) {
+      const sub = subs[si]
+      job.suiteProgress = { phase: 'clone', index: si + 1, total: subs.length, name: sub.name, done: false }
+      const subRepo = sub.url.replace(/^https?:\/\/[^/]+\//u, '').replace(/\.git$/u, '')
+      const dest = join(tmpDir, sub.path)
+      try {
+        mkdirSync(dirname(dest), { recursive: true })
+        await gitCloneRepo(subRepo, dest, sub.url.includes('gitee.com') ? 'gitee' : 'github', 120000)
+      } catch (error) {
+        report.push({ component: sub.name, type: 'clone', ok: false, note: `子模块拉取失败：${error.message}` })
+      }
+    }
+    for (let pi = 0; pi < subs.length; pi += 1) {
+      const sub = subs[pi]
+      job.suiteProgress = { phase: 'assemble', index: pi + 1, total: subs.length, name: sub.name, done: false }
+      const subDir = join(tmpDir, sub.path)
+      if (!existsSync(subDir)) continue
+      const subRepo = sub.url.replace(/^https?:\/\/[^/]+\//u, '').replace(/\.git$/u, '')
+      let pkg = null
+      try {
+        const pkgPath = join(subDir, 'package.json')
+        if (existsSync(pkgPath)) pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+      } catch {}
+      let handled = false
+      // a. bundle 型插件（如 injector）：自动装配默认**跳过**并给出官方装配指引——
+      // 第三方 bundle 需与当前 DSH 版本严格兼容（peer 依赖、client inject 模块、patch 语义），
+      // 自动写入 bundles 曾导致启动崩溃；预设/技能/普通插件不受影响。
+      if (pkg && typeof pkg.name === 'string' && pkg.dsh?.bundle) {
+        report.push({ component: sub.name, type: 'bundle', ok: false, note: `${pkg.name} 是 bundle 型插件，自动装配已跳过（避免 bundle 不兼容导致启动失败）；请按详情面板「官方安装方式」命令手动装配（clone 套装后运行 install.ps1，或构建后加入 profile 的 dsh.profile.bundles）` })
+        handled = true
+      }
+      // b. 技能（根或第一层子目录 SKILL.md）
+      if (!handled) {
+        let skillDir0 = ''
+        if (existsSync(join(subDir, 'SKILL.md'))) {
+          skillDir0 = ''
+        } else {
+          let found = null
+          try {
+            found = readdirSync(subDir, { withFileTypes: true })
+              .find((d) => d.isDirectory() && existsSync(join(subDir, d.name, 'SKILL.md')))
+          } catch {}
+          skillDir0 = found ? found.name : null
+        }
+        if (skillDir0 !== null) {
+          const skillsRoot = join(dshHome(), 'skills')
+          mkdirSync(skillsRoot, { recursive: true })
+          const dest = join(skillsRoot, sub.name)
+          if (existsSync(dest)) rmSync(dest, { recursive: true, force: true })
+          copyTree(join(subDir, skillDir0), dest)
+          report.push({ component: sub.name, type: 'skill', ok: true, note: `已安装技能 ~/.dsh/skills/${sub.name}` })
+          handled = true
+        }
+      }
+      // c. agent 预设（含 preset.yml + agent.cordis.yml 的目录；预设优先于普通 npm 包——
+      // 如 dsh-router-standard 既是 npm 包又带预设目录，install.ps1 意图是复制预设）
+      const presets = findPresetDirs(subDir, 2)
+      for (const p of presets) {
+        const pname = basename(p)
+        const presetsRoot = join(dshHome(), '.agent-presets')
+        mkdirSync(presetsRoot, { recursive: true })
+        const dest = join(presetsRoot, pname)
+        if (existsSync(dest)) rmSync(dest, { recursive: true, force: true })
+        copyTree(p, dest)
+        report.push({ component: sub.name, type: 'preset', ok: true, note: `已安装预设 ${pname}（新建会话可选）` })
+        handled = true
+      }
+      // d. 普通 npm 插件（无 bundle 且无预设/技能）
+      if (!handled && pkg && typeof pkg.name === 'string') {
+        const target = join(profileDir, 'node_modules', pkg.name)
+        if (existsSync(target)) rmSync(target, { recursive: true, force: true })
+        mkdirSync(dirname(target), { recursive: true })
+        copyTree(subDir, target)
+        const taken = new Set(listEntries(ports).map((e) => e.rowId))
+        const entryId = deriveEntryId(pkg.name, taken)
+        await appendInsert(patchPath, entryId, pkg.name)
+        // 记下套装装配出的包名：它们是 copyTree 铺进去的、不在 pnpm-lock.yaml 里，交给调用方统一对账
+        if (!Array.isArray(job.suiteInstalled)) job.suiteInstalled = []
+        if (!job.suiteInstalled.includes(pkg.name)) job.suiteInstalled.push(pkg.name)
+        report.push({ component: sub.name, type: 'plugin', ok: true, note: `已安装 ${pkg.name}（HMR 生效）` })
+        handled = true
+      }
+      if (!handled) {
+        report.push({ component: sub.name, type: 'unknown', ok: false, note: '未识别组件类型（无 package.json / SKILL.md / 预设）' })
+      }
+    }
+    job.status = 'done'
+    job.stage = 'done'
+    job.suiteReport = report
+    // 装配全部走完：进度标记完成（保留最后一轮的 i/n 与名字，前端显示"已完成 n/n 个子模块"）
+    if (job.suiteProgress) job.suiteProgress = { ...job.suiteProgress, done: true }
+    const okCount = report.filter((r) => r.ok).length
+    const failCount = report.filter((r) => !r.ok).length
+    const bundleCount = report.filter((r) => r.type === 'bundle' && r.ok).length
+    job.suiteNote = `套装安装完成：${okCount} 个组件成功${failCount > 0 ? `，${failCount} 个失败（详见报告）` : ''}${bundleCount > 0 ? '。bundle 组件需重启服务生效' : ''}；预设需新建会话时选择。`
+  } catch (error) {
+    job.status = 'failed'
+    job.error = error instanceof Error ? error.message : String(error)
+  } finally {
+    try { rmSync(tmpDir, { recursive: true, force: true }) } catch {}
+    job.finishedAt = Date.now()
+  }
+}
+export { readGitmodules, findPresetDirs, packageEntryExists, runSuiteInstallJob, probeGitmodules, resolveInstallKind }

package/lib/server/infra/exec.js

@@ -0,0 +1,98 @@
+// 由 Step 1 搬运工具从 lib/index.js 原样切出（只移动、未改逻辑）
+// 分组见 D:\dsh\dsh-plugin-hub-plan\architecture.zh.md §三 L0 · infra
+
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { homedir } from 'node:os'
+
+/** git 可执行名（跨平台）。事故（2026-09-20，另一位用户：Android + proot Ubuntu）：
+ * 「仓库落地」硬编码 `git.exe` → 非 Windows 环境 spawn git.exe ENOENT，克隆必然失败。 */
+function gitBin() {
+  return process.platform === 'win32' ? 'git.exe' : 'git'
+}
+
+/** pnpm 执行方式定位（跨平台，纯函数便于单测 → 按优先级返回列表，逐个尝试）。
+ * 事故（2026-09-20，同一位用户，node v24 + Linux）：只按 Windows 布局找 corepack.js
+ * （`<node bin>/node_modules/corepack/dist/corepack.js`），而 Linux 的 npm 全局布局在
+ * `<prefix>/lib/node_modules/corepack/...` → AI 赋能的 install-npm 生成
+ * `node /usr/local/bin/node_modules/corepack/dist/corepack.js pnpm add …` →
+ * `Error: Cannot find module …`（MODULE_NOT_FOUND）。这里把三种布局 + PATH 兜底都列出来。 */
+function resolvePnpmRunners({ platform = process.platform, execPath = process.execPath, comspec = process.env.ComSpec ?? 'cmd.exe', exists = existsSync } = {}) {
+  const binDir = dirname(execPath)
+  const corepackCandidates = [
+    join(binDir, 'node_modules', 'corepack', 'dist', 'corepack.js'), // Windows 官方安装器 / nvm-windows
+    join(binDir, '..', 'lib', 'node_modules', 'corepack', 'dist', 'corepack.js'), // Linux/macOS npm 全局
+    join(binDir, '..', 'libexec', 'lib', 'node_modules', 'corepack', 'dist', 'corepack.js'), // brew / 自编译布局
+  ]
+  const runners = []
+  for (const js of corepackCandidates) {
+    if (exists(js)) {
+      runners.push({ kind: 'node-corepack', note: `node ${js} pnpm`, run: (args) => ({ bin: execPath, argv: [js, 'pnpm', ...args] }) })
+    }
+  }
+  if (platform === 'win32') {
+    // .cmd 批处理不能直接 execFile（EINVAL）→ 经 cmd.exe 调用（整条命令作为一个参数）
+    runners.push({
+      kind: 'cmd-corepack',
+      note: 'cmd /c corepack pnpm',
+      run: (args) => ({ bin: comspec, argv: ['/d', '/s', '/c', ['corepack', 'pnpm', ...args].map((a) => JSON.stringify(a)).join(' ')] }),
+    })
+  } else {
+    runners.push({ kind: 'corepack', note: 'corepack pnpm', run: (args) => ({ bin: 'corepack', argv: ['pnpm', ...args] }) })
+    runners.push({ kind: 'pnpm', note: 'pnpm', run: (args) => ({ bin: 'pnpm', argv: args }) })
+  }
+  return runners
+}
+
+/** 依次尝试各执行方式；只有"执行方式本身不可用"（ENOENT / MODULE_NOT_FOUND）才换下一个，
+ * 真正的安装失败（网络、依赖冲突等）立即抛出，并附上已尝试的清单便于排查。 */
+async function runPnpmWithFallback(args, { execOpts = {}, runners = resolvePnpmRunners() } = {}) {
+  let lastError = null
+  for (const runner of runners) {
+    const { bin, argv } = runner.run(args)
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      await execFileAsync(bin, argv, execOpts)
+      return { runner }
+    } catch (error) {
+      lastError = error
+      const message = String(error?.message ?? '')
+      if (!/ENOENT|Cannot find module/u.test(message)) throw error
+    }
+  }
+  const tried = runners.map((r) => r.note).join(' → ')
+  throw new Error(`${lastError?.message ?? 'pnpm 执行失败'}（已尝试：${tried}）`)
+}
+
+/** git 非交互环境：禁止任何登录/凭据窗口弹出（私有仓库或不可达源直接失败，不做交互式重试）。 */
+
+function gitEnv() {
+  return {
+    ...process.env,
+    GIT_TERMINAL_PROMPT: '0',
+    GCM_INTERACTIVE: 'never',
+    GIT_ASKPASS: 'echo',
+    SSH_ASKPASS: 'echo',
+  }
+}
+function processAlive(pid) {
+  try {
+    process.kill(Number(pid), 0)
+    return true
+  } catch {
+    return false
+  }
+}
+const execFileAsync = promisify(execFile)
+/** gh CLI 通道：api.github.com 黑洞期（node:https 全部超时）时的最后兜底。
+ * 服务进程 PATH 可能不含 gh（桌面壳环境）：依次尝试 gh、常见安装路径。 */
+const GH_BIN_CANDIDATES = [
+  'gh',
+  'C:\\Program Files\\GitHub CLI\\gh.exe',
+  join(homedir(), 'AppData', 'Local', 'Microsoft', 'WinGet', 'Links', 'gh.exe'),
+  join(homedir(), 'scoop', 'shims', 'gh.exe'),
+]
+
+export { GH_BIN_CANDIDATES, gitEnv, gitBin, processAlive, execFileAsync, resolvePnpmRunners, runPnpmWithFallback }

package/lib/server/infra/fsx.js

@@ -0,0 +1,163 @@
+// 由 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 { dirname, join, basename } from 'node:path'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+
+const execFileAsync = promisify(execFile)
+
+/**
+ * 递归复制目录树（绕开 fs.cpSync 在本环境的目录复制 EIO bug：
+ * cpSync 复制含子目录的树必报 `EIO, Access is denied`，而逐文件 copyFileSync 正常）。
+ * 跳过 .git（技能/包副本不需要版本库元数据）。
+ */
+
+/** 清理陈旧包目录与 pnpm _tmp_ 残留（Windows 原子替换 EPERM 的根因），返回清理数量。 */
+
+/** 串行化补丁文件写入，避免并发 toggle 的读改写竞争。 */
+
+function copyTree(src, dest) {
+  mkdirSync(dest, { recursive: true })
+  for (const entry of readdirSync(src, { withFileTypes: true })) {
+    if (entry.name === '.git') continue
+    const from = join(src, entry.name)
+    const to = join(dest, entry.name)
+    if (entry.isDirectory()) {
+      copyTree(from, to)
+    } else if (entry.isFile()) {
+      copyFileSync(from, to)
+    }
+  }
+}
+function queuedWrite(fn) {
+  const run = writeQueue.then(fn, fn)
+  writeQueue = run.then(() => undefined, () => undefined)
+  return run
+}
+function cleanupStalePackageDir(profileDir, packageName) {
+  const segments = packageName.startsWith('@') ? packageName.split('/') : [packageName]
+  const dir = join(profileDir, 'node_modules', ...segments)
+  const base = basename(dir)
+  const parent = dirname(dir)
+  let removed = 0
+  try {
+    if (existsSync(dir)) {
+      rmSync(dir, { recursive: true, force: true })
+      removed += 1
+    }
+  } catch {}
+  try {
+    for (const entry of readdirSync(parent)) {
+      if (entry.startsWith(`${base}_tmp_`)) {
+        try {
+          rmSync(join(parent, entry), { recursive: true, force: true })
+          removed += 1
+        } catch {}
+      }
+    }
+  } catch {}
+  return removed
+}
+let writeQueue = Promise.resolve()
+
+/**
+ * 删除目录树并**核实删除结果**。
+ * 为什么要核实：本机某些环境（受限令牌/沙箱/杀软占用）下 `rmSync` 会**静默落空**——不抛错、目录仍在。
+ * 路由若删完直接 `{ok:true}` 就是对用户撒谎（2026-09-20 多类型演练实测：同一个 `rmSync` 在
+ * `D:\dsh\repos` 删得掉，在 `C:\Users\<user>\.dsh\...` 下返回成功但目录原封不动）。
+ * 返回 `{ok, attempts, error}`；`ok:false` 时调用方必须如实报错，不能吞。
+ */
+function removeDirVerified(dir) {
+  let lastError = null
+  for (let attempt = 1; attempt <= 2; attempt += 1) {
+    try {
+      rmSync(dir, { recursive: true, force: true, maxRetries: 3, retryDelay: 120 })
+    } catch (error) {
+      lastError = error
+    }
+    if (!existsSync(dir)) return { ok: true, attempts: attempt }
+  }
+  return { ok: false, attempts: 2, error: lastError instanceof Error ? lastError.message : null }
+}
+
+/**
+ * 清掉树里的只读位（Windows 上 `rmSync` 遇只读文件直接 EPERM，`force` **不会**替你清属性）。
+ * 返回清掉的文件数，供日志核对。
+ */
+function clearReadonly(dir) {
+  let cleared = 0
+  const walk = (p) => {
+    let st = null
+    try { st = lstatSync(p) } catch { return }
+    try {
+      if (st.isDirectory()) {
+        for (const name of readdirSync(p)) walk(join(p, name))
+      } else if ((st.mode & 0o200) === 0) {
+        chmodSync(p, 0o666)
+        cleared += 1
+      }
+    } catch {}
+  }
+  walk(dir)
+  return cleared
+}
+
+/** 轮询等待目录真的消失（Windows「删除挂起」期间名字仍可见，立刻 existsSync 会误判失败）。 */
+function waitGone(dir, timeoutMs) {
+  return new Promise((resolve) => {
+    const startedAt = Date.now()
+    const tick = () => {
+      if (!existsSync(dir)) { resolve(true); return }
+      if (Date.now() - startedAt >= timeoutMs) { resolve(false); return }
+      setTimeout(tick, 100)
+    }
+    tick()
+  })
+}
+
+/** 外部删除兜底：实测本机 PowerShell/.NET 能删掉 Node `rmSync` 静默删不掉的树。 */
+async function removeViaShell(dir) {
+  try {
+    if (process.platform === 'win32') {
+      await execFileAsync('cmd.exe', ['/c', 'rmdir', '/s', '/q', dir], { windowsHide: true, timeout: 120000 })
+      return { ok: true, method: 'rmdir' }
+    }
+    await execFileAsync('rm', ['-rf', '--', dir], { timeout: 120000 })
+    return { ok: true, method: 'rm' }
+  } catch (error) {
+    return { ok: false, method: null, error: error instanceof Error ? error.message : String(error) }
+  }
+}
+
+/**
+ * 强化版目录删除（清理残余专用，2026-09-24 真机诊断后新增）：
+ *   ① 清只读位 → ② `rmSync` → ③ **轮询核实**（容忍删除挂起）→ ④ 失败则外部 `rmdir /s /q` 兜底 → ⑤ 再核实。
+ * 为什么不能只用 `rmSync` + 立刻 `existsSync`：真机上出现过「`rmSync` 不抛错、目录仍在」，
+ * 面板于是报「有 N 项没能删除（目录仍存在）——当前环境可能禁止删除」，把用户引向并不存在的权限问题；
+ * 实测同一棵树用 .NET/PowerShell 能删掉，所以这里补上兜底与轮询，并把真实错误码带回去。
+ */
+async function removeDirVerifiedAsync(dir, { attempts = 2, pollMs = 600 } = {}) {
+  let lastError = null
+  let method = null
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    if (!existsSync(dir)) return { ok: true, attempts: attempt, method: method ?? 'already-gone', error: null }
+    try { clearReadonly(dir) } catch {}
+    try {
+      rmSync(dir, { recursive: true, force: true, maxRetries: 3, retryDelay: 120 })
+    } catch (error) {
+      lastError = error
+    }
+    if (await waitGone(dir, pollMs)) return { ok: true, attempts: attempt, method: 'rmSync', error: null }
+    const shell = await removeViaShell(dir)
+    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
+  }
+  const detail = lastError === null
+    ? '删除后目录仍存在（未抛出错误：Windows 删除挂起或占用）'
+    : `${lastError.code ?? ''} ${lastError.message ?? lastError}`.trim()
+  return { ok: false, attempts, method: null, error: detail }
+}
+
+export { copyTree, queuedWrite, cleanupStalePackageDir, removeDirVerified, removeDirVerifiedAsync, clearReadonly, waitGone, removeViaShell, writeQueue }

package/lib/server/infra/fw-integrity-check.js

@@ -0,0 +1,37 @@
+// L0 · infra —— 框架升级脚本里的「安装后结构完整性校验」生成器（2026-09-24）
+//
+// 为什么单独放一个模块：这段是升级脚本里唯一需要**逐项验结构**的地方，而 routes/framework-upgrade.js
+// 已经贴着架构守卫的行数上限（那一段 600+ 行的 PowerShell 模板是历史遗留）。抽出来既守住上限，
+// 也让这段逻辑能被单独读、单独审 —— 它是"升级完却没装全"这类事故的最后一道闸。
+//
+// 自包含：只用 target / nodePath / fwRoot 三个值（路径由调用方用 ps() 算好传进来），不依赖任何宿主上下文。
+
+/** 生成"安装后结构校验"的 PowerShell 片段（返回单个字符串，供升级脚本数组作为一个元素展开）。 */
+function fwIntegrityCheck(params) {
+  const { target, nodePath, fwRoot } = params
+  return [
+    `  // 安装后结构完整性校验：版本号对 ≠ 装完整。2026-09-24 事故：一次升级的 pnpm 安装被中断，`,
+    `  // 顶层 @deepseek-ai\\dsh 目录整个消失、.pnpm 实体只剩 lib 里几个硬链接 —— 只对版本号的校验`,
+    `  // 有可能被"package.json 写成功但 lib 没落全"骗过，等下次重启才发现服务起不来。`,
+    `  if ($code -eq 0) {`,
+    `    try {`,
+    `      $fwDsh = Join-Path '${fwRoot}' '@deepseek-ai\\dsh'`,
+    `      $binA = Join-Path $fwDsh 'lib\\bin.js'`,
+    `      $binB = $null`,
+    `      $ent = Get-ChildItem -Path (Join-Path '${fwRoot}' '.pnpm') -Directory -Filter '@deepseek-ai+dsh@${target}*' -ErrorAction SilentlyContinue | Select-Object -First 1`,
+    `      if ($ent) { $binB = Join-Path $ent.FullName 'node_modules\\@deepseek-ai\\dsh\\lib\\bin.js' }`,
+    `      $bin = $null`,
+    `      if (Test-Path -LiteralPath $binA) { $bin = $binA } elseif ($binB -and (Test-Path -LiteralPath $binB)) { $bin = $binB }`,
+    `      if (-not (Test-Path -LiteralPath (Join-Path $fwDsh 'package.json'))) { Log '结构校验失败：顶层 @deepseek-ai\\dsh\\package.json 不存在（安装不完整）'; $code = 1 }`,
+    `      elseif (-not $bin) { Log '结构校验失败：找不到 dsh 的 lib/bin.js（顶层与 .pnpm 都没有）——装完也拉不起来，按失败处理'; $code = 1 }`,
+    `      else {`,
+    `        $probe = (& '${nodePath}' $bin --version 2>&1 | Out-String).Trim()`,
+    `        if ($probe -ne '${target}') { Log ('结构校验失败：CLI 自报版本 ' + $probe + '，目标 ${target}（安装不完整或被其它副本顶替），按失败处理'); $code = 1 }`,
+    `        else { Log ('结构校验通过：package.json + bin.js 就位，CLI 自报 ' + $probe) }`,
+    `      }`,
+    `    } catch { Log ('结构校验异常，按失败处理：' + $_.Exception.Message); $code = 1 }`,
+    `  }`,
+  ].join('\r\n')
+}
+
+export { fwIntegrityCheck }