@noob-stupid/dsh-plugin-console 0.5.49 → 0.5.50

package/lib/server/infra/fw-root-detect.js

@@ -0,0 +1,209 @@
+// L0 · infra —— fw-root-detect.js（框架树根的**多基准探测**；0.5.50 加法）
+//
+// 为什么要多基准（真机实证，2026-10-14）：
+//   这套代码会在**两种完全不同的位置**被运行，解析语义天然不同：
+//     ① 插件装在 profile 里（正常形态）—— 从插件自己的 `lib/index.js` 能解析到
+//        `@deepseek-ai/dsh`（本机实测：profile 的 node_modules 把它指向 npx 缓存的
+//        `D:\node_cache\_npx\<hash>\node_modules\@deepseek-ai\dsh`）；
+//     ② 在**开发仓库**里直接跑（`node scripts/fw-preflight.mjs`）—— 仓库根没有 node_modules，
+//        `require.resolve('@deepseek-ai/dsh/package.json')` 直接 `MODULE_NOT_FOUND`。
+//        **而"服务起不来"时最可能的调用方式恰恰是这一种**（用户手里只有一条命令）。
+//   ⇒ 只写一种基准等于在最需要它的场景里失效。本模块把候选收在一处，按"最准 → 最宽"排序。
+//
+// 与 domain/framework-root.js 的分工（**不是同一件事，别合并**）：
+//   · 那边：给**补丁自愈/只读体检**判断"某个 `@deepseek-ai/*` 包在不在"，产出**多个**解析基准；
+//   · 这边：给**预检治包**判断"框架树根本身在哪"，产出**一个**根目录（供走闭包与定 .pnpm 位置）。
+//
+// 分层：L0 · infra（不得 import domain/routes/index —— tests/test-architecture-guard.mjs 断言②）。
+
+import { existsSync, readdirSync, realpathSync, statSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { homedir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { candidateCacheRoots } from './npm-cache.js'
+
+/** 该目录像不像一棵框架树：有 `@deepseek-ai/dsh/lib/bin.js`，或有 `.pnpm` 且其中有 dsh 实体。 */
+function looksLikeFwRoot(dir, { deps = {} } = {}) {
+  const exists = deps.exists ?? existsSync
+  if (typeof dir !== 'string' || dir === '') return false
+  if (exists(join(dir, '@deepseek-ai', 'dsh', 'lib', 'bin.js'))) return true
+  try {
+    for (const name of readdirSync(join(dir, '.pnpm'))) {
+      if (!name.startsWith('@deepseek-ai+dsh@')) continue
+      if (exists(join(dir, '.pnpm', name, 'node_modules', '@deepseek-ai', 'dsh', 'lib', 'bin.js'))) return true
+    }
+  } catch {}
+  return false
+}
+
+/** 从某个基准文件/目录解析 `@deepseek-ai/dsh`，成功则反推承载它的那层 `node_modules`。 */
+function fwRootFromBase(base, { deps = {} } = {}) {
+  const exists = deps.exists ?? existsSync
+  const realpath = deps.realpath ?? ((p) => realpathSync(p))
+  const makeReq = deps.createRequire ?? createRequire
+  let pkgPath = null
+  try { pkgPath = makeReq(base).resolve('@deepseek-ai/dsh/package.json') } catch { return null }
+  if (typeof pkgPath !== 'string') return null
+  // `<…>/node_modules/@deepseek-ai/dsh/package.json` → 退三层 = 那层 node_modules
+  let nm = dirname(dirname(dirname(pkgPath)))
+  // ★ 必须 resolve 成**真身**：profile 侧的 `node_modules/@deepseek-ai/dsh` 常是 junction 投影
+  //   （真机实测：`C:\Users\<u>\.dsh\profiles\node_modules\@deepseek-ai\dsh` → `D:\node_cache\_npx\<hash>\…`）。
+  //   拿投影当框架树根 ⇒ `--repair` 会按"投影的 node_modules / .pnpm"去算目标路径 ⇒ 写到不存在的
+  //   结构里，或者把包装进投影层而不是真身所在的那棵树。解析到真身才能与"服务实际加载的那棵树"对齐。
+  try { nm = dirname(dirname(dirname(realpath(pkgPath)))) } catch {}
+  if (looksLikeFwRoot(nm, { deps })) return nm
+  // rc.1 之后实体在 .pnpm 内层：再向上找最近的含 .pnpm 的 node_modules
+  let dir = nm
+  for (let i = 0; i < 8; i += 1) {
+    if (exists(join(dir, '.pnpm'))) return dir
+    const parent = dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return exists(nm) ? nm : null
+}
+
+/** 扫 npx 缓存（`<cacheBase>/_npx/<hash>/node_modules`），按 dsh 的 bin.js 修改时间取最新那个。 */
+function fwRootFromNpxCache({ env = process.env, home = homedir(), deps = {} } = {}) {
+  const exists = deps.exists ?? existsSync
+  const stat = deps.stat ?? ((p) => statSync(p))
+  const readdir = deps.readdir ?? ((p) => readdirSync(p))
+
+  const bases = []
+  const pushBase = (dir) => {
+    if (typeof dir !== 'string' || dir === '') return
+    if (!bases.includes(dir)) bases.push(dir)
+  }
+  pushBase(env.npm_config_cache)
+  pushBase(env.NPM_CONFIG_CACHE)
+  pushBase('D:\\node_cache')
+  pushBase(join(env.LOCALAPPDATA ?? '', 'npm-cache'))
+  pushBase(join(home, 'AppData', 'Local', 'npm-cache'))
+  // npm cacache 的根通常就是 `<cacheBase>/_cacache`，故从它的父目录取 `_npx`
+  for (const cacache of candidateCacheRoots({ env, home })) pushBase(dirname(cacache))
+
+  const hits = []
+  for (const base of bases) {
+    const npxRoot = join(base, '_npx')
+    if (!exists(npxRoot)) continue
+    let dirs = []
+    try { dirs = readdir(npxRoot) } catch { continue }
+    for (const d of dirs) {
+      const nm = join(npxRoot, d, 'node_modules')
+      const bin = join(nm, '@deepseek-ai', 'dsh', 'lib', 'bin.js')
+      if (!exists(bin)) continue
+      let mtime = 0
+      try { mtime = stat(bin).mtimeMs ?? 0 } catch { mtime = 0 }
+      hits.push({ fwRoot: nm, via: 'npx-cache', mtime })
+    }
+  }
+  if (hits.length === 0) return null
+  // 桌面端启动器就是按 mtime 取最新的那个 —— 这里沿用同一取舍，保证"预检的树"与"会被启动的树"一致
+  hits.sort((a, b) => b.mtime - a.mtime)
+  return hits[0]
+}
+
+/** 扫 `<dshHome>/profiles/**` 与各类 node_modules，找一棵像框架树的。 */
+function fwRootFromDshHome({ env = process.env, home = homedir(), deps = {} } = {}) {
+  const exists = deps.exists ?? existsSync
+  const readdir = deps.readdir ?? ((p) => readdirSync(p))
+  const dshHome = (typeof env.DSH_HOME === 'string' && env.DSH_HOME.trim() !== '') ? env.DSH_HOME.trim() : join(home, '.dsh')
+
+  const cands = []
+  // ① 显式 profile 目录（桌面端/CLI 都会设 DSH_PROFILE_DIR）
+  if (typeof env.DSH_PROFILE_DIR === 'string' && env.DSH_PROFILE_DIR.trim() !== '') cands.push(env.DSH_PROFILE_DIR.trim())
+  // ② 按 profile 名
+  if (typeof env.DSH_PROFILE === 'string' && env.DSH_PROFILE.trim() !== '') cands.push(join(dshHome, 'profiles', env.DSH_PROFILE.trim()))
+  // ③ 共享投影层与各 profile
+  cands.push(join(dshHome, 'profiles', 'node_modules'))
+  try {
+    for (const d of readdir(join(dshHome, 'profiles'))) {
+      if (d === 'node_modules') continue
+      cands.push(join(dshHome, 'profiles', d, 'node_modules'))
+    }
+  } catch {}
+
+  for (const dir of cands) {
+    if (!looksLikeFwRoot(dir, { deps })) continue
+    return { fwRoot: dir, via: 'dsh-home' }
+  }
+  return null
+}
+
+/**
+ * 把"看起来像框架树根"的目录**归一到真身**。
+ *
+ * 为什么必须单独做这一步（真机实测 2026-10-14）：
+ *   `C:\Users\<u>\.dsh\profiles\node_modules` **本身是真实目录**（不是链接），但它下面的
+ *   `@deepseek-ai\dsh` 是 **junction** → `D:\node_cache\_npx\<hash>\node_modules\@deepseek-ai\dsh`。
+ *   于是"这个目录像框架树"与"框架包的真身在哪"是两件事：只对根目录做 realpath 什么也变不了。
+ *   ⇒ 拿投影当根，`--repair` 会按"投影的 node_modules / .pnpm"去算目标路径，写到不存在的结构里；
+ *     而服务实际加载的是**真身那棵树**（启动器命令行 = `…\_npx\<hash>\node_modules\@deepseek-ai\dsh\lib\bin.js`）。
+ *   ⇒ 归一到真身，预检的那棵树才与"会被启动的那棵树"一致。
+ */
+function realRootOf(dir, { deps = {} } = {}) {
+  const exists = deps.exists ?? existsSync
+  const realpath = deps.realpath ?? ((p) => realpathSync(p))
+  if (typeof dir !== 'string' || dir === '') return dir
+  const pkg = join(dir, '@deepseek-ai', 'dsh', 'package.json')
+  if (exists(pkg)) {
+    try { return dirname(dirname(dirname(realpath(pkg)))) } catch { return dir }
+  }
+  // `.pnpm` 内层形态：解析 store 里那份 dsh 的清单，同样退三层
+  try {
+    for (const name of readdirSync(join(dir, '.pnpm'))) {
+      if (!name.startsWith('@deepseek-ai+dsh@')) continue
+      const inner = join(dir, '.pnpm', name, 'node_modules', '@deepseek-ai', 'dsh', 'package.json')
+      if (!exists(inner)) continue
+      return dirname(dirname(dirname(realpath(inner))))
+    }
+  } catch {}
+  return dir
+}
+
+/**
+ * 探测框架树根（**有序**，先准后宽）。返回 `{ fwRoot, via, tried }`；一个都拿不到时
+ * `fwRoot: null` 且 `tried` 列出试过的基准 —— 调用方据此如实报"探测不到"，而不是猜一个。
+ *
+ * 所有分支的返回值都过一道 `realRootOf` —— 保证调用方拿到的永远是**真身所在的那棵树**。
+ *
+ * @param {object} p
+ * @param {string} [p.pluginDir]   插件包根（调用方传 `<repo>/`，用于第 ① 基准）。
+ *                                 ★ 名字不叫 `pluginRoot`：那是 infra/paths.js 的导出名，
+ *                                   同名参数会被架构守卫断言⑧（导入绑定只读）判成"给导出绑定赋值"。
+ * @param {string} [p.entryHint]   已知的入口文件（如 `dsh/lib/bin.js`）—— 给了就优先用它反推。
+ */
+function detectFrameworkRoot({ pluginDir = null, entryHint = null, env = process.env, home = homedir(), deps = {} } = {}) {
+  const realpath = deps.realpath ?? ((p) => realpathSync(p))
+  const tried = []
+  const real = (p) => { try { return realpath(p) } catch { return p } }
+
+  // ⓪ 调用方直接给了入口文件：它所在的那层 node_modules 最准（同样要落到真身）
+  if (typeof entryHint === 'string' && entryHint !== '') {
+    const nm = real(dirname(dirname(dirname(resolve(entryHint)))))
+    tried.push({ via: 'entry-hint', base: nm })
+    if (looksLikeFwRoot(nm, { deps })) return { fwRoot: nm, via: 'entry-hint', tried }
+  }
+
+  // ① 从插件自己解析（插件装在 profile 里时最准）
+  if (typeof pluginDir === 'string' && pluginDir !== '') {
+    const base = join(pluginDir, 'lib', 'index.js')
+    tried.push({ via: 'plugin-root', base })
+    const hit = fwRootFromBase(base, { deps })
+    if (hit !== null) return { fwRoot: realRootOf(hit, { deps }), via: 'plugin-root', tried }
+  }
+
+  // ② DSH_HOME / profile 环境变量
+  tried.push({ via: 'dsh-home', base: '(DSH_HOME/profiles)' })
+  const fromHome = fwRootFromDshHome({ env, home, deps })
+  if (fromHome !== null) return { fwRoot: realRootOf(fromHome.fwRoot, { deps }), via: fromHome.via, tried }
+
+  // ③ npx 缓存（开发仓库里直接跑时的主要出路；与桌面端启动器同一取舍）
+  tried.push({ via: 'npx-cache', base: '(cacheBase/_npx/*)' })
+  const fromNpx = fwRootFromNpxCache({ env, home, deps })
+  if (fromNpx !== null) return { fwRoot: realRootOf(fromNpx.fwRoot, { deps }), via: fromNpx.via, tried }
+
+  return { fwRoot: null, via: null, tried }
+}
+
+export { detectFrameworkRoot, fwRootFromBase, fwRootFromDshHome, fwRootFromNpxCache, looksLikeFwRoot, realRootOf }

package/lib/server/infra/npm-cache.js

@@ -0,0 +1,173 @@
+// L0 · infra —— npm-cache.js（npm cacache **直读** + 零依赖解 tgz；0.5.50 加法）
+//
+// 为什么需要它（2026-10-14 真机停机事故的修复侧）：
+//   框架包被掏空后，`node_modules` 里只剩空壳，但**本地 npm 缓存里通常还留着原始 tarball**。
+//   实测本机：`cordis` / `dsh-llm` / `dsh-tools` / `dsh-web` 四个包的 tarball 全在
+//   `D:\node_cache\_cacache`，按 `package-lock.json` 的 `integrity` **逐字节命中**，110KB 的包
+//   从"发现"到"装回"在 1 秒内完成 —— 全程离线、不联网、不 spawn、不需要 pnpm。
+//
+// 两条硬约束（都是真机踩出来的）：
+//   ① **零依赖**：不 require npm 自带的 `cacache` / `tar`。
+//      实测在 `D:\dsh` 目录下 `require('npm/node_modules/cacache')` 会炸
+//      `ERR_INVALID_PACKAGE_CONFIG`（那儿有个 0 字节的 `package.json`）—— 靠 npm 内部模块
+//      就等于把"打不开时唯一的出路"押在另一个可能坏的东西上。
+//   ② **cacache 布局是确定性的**，直接按哈希路径取文件即可：
+//      `content-v2/sha512/<hex[0:2]>/<hex[2:4]>/<hex[4:]>`，其中 `hex = base64 解码 integrity 后的十六进制`。
+//      这条路不依赖 index-v5 的元数据，也不受 registry 地址（npmjs / npmmirror）影响。
+//
+// 解 tgz 自带一个最小 tar 解析器（ustar + GNU 长名 + pax 头跳过）——见 extractTgz。
+//
+// 分层：L0 · infra（不得 import domain/routes/index —— tests/test-architecture-guard.mjs 断言②）。
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve, sep } from 'node:path'
+import { homedir } from 'node:os'
+import { gunzipSync } from 'node:zlib'
+
+/**
+ * 候选 npm 缓存根（按"最可能先命中"排序）。
+ * 显式 env 优先（`npm_config_cache` / `NPM_CONFIG_CACHE`），再退到用户 .npmrc 的常见落点。
+ */
+function candidateCacheRoots({ env = process.env, home = homedir() } = {}) {
+  const out = []
+  const push = (dir) => {
+    if (typeof dir !== 'string' || dir === '') return
+    const withCache = dir.endsWith('_cacache') ? dir : join(dir, '_cacache')
+    if (!out.includes(withCache)) out.push(withCache)
+  }
+  push(env.npm_config_cache)
+  push(env.NPM_CONFIG_CACHE)
+  push('D:\\node_cache')
+  push(join(env.LOCALAPPDATA ?? '', 'npm-cache'))
+  push(join(home, 'AppData', 'Local', 'npm-cache'))
+  push(join(home, '.npm'))
+  // 只要真的存在 `content-v2` 才算数（光有目录名不算）
+  return out.filter((p) => existsSync(join(p, 'content-v2')))
+}
+
+/**
+ * `sha512-<base64>` → cacache 内容文件的绝对路径。
+ * 非法 integrity / 长度不对时返回 null（**不猜**：宁可报"取不到"，也不去读一个碰巧存在的路径）。
+ */
+function integrityToContentPath(cacheRoot, integrity) {
+  const m = /^sha512-(.+)$/u.exec(String(integrity ?? ''))
+  if (m === null) return null
+  let hex = ''
+  try { hex = Buffer.from(m[1], 'base64').toString('hex') } catch { return null }
+  if (hex.length !== 128 || !/^[0-9a-f]+$/u.test(hex)) return null
+  return join(cacheRoot, 'content-v2', 'sha512', hex.slice(0, 2), hex.slice(2, 4), hex.slice(4))
+}
+
+/** 按 integrity 从缓存读出 tarball 字节；取不到返回 null（绝不抛）。 */
+function readTarball(cacheRoot, integrity, { deps = {} } = {}) {
+  const exists = deps.exists ?? existsSync
+  const read = deps.read ?? ((p) => readFileSync(p))
+  const p = integrityToContentPath(cacheRoot, integrity)
+  if (p === null) return null
+  try { return exists(p) ? read(p) : null } catch { return null }
+}
+
+/** 依次在多个缓存根里找同一个 integrity，返回第一个命中的 `{ buf, cacheRoot }`。 */
+function readTarballFromAny(roots, integrity, { deps = {} } = {}) {
+  for (const root of Array.isArray(roots) ? roots : []) {
+    const buf = readTarball(root, integrity, { deps })
+    if (buf !== null && buf.length > 0) return { buf, cacheRoot: root }
+  }
+  return null
+}
+
+/** 读 tar 头里的一个数值字段（八进制，容忍空格/NUL 结尾与 GNU base-256）。 */
+function tarNumber(header, offset, length) {
+  const raw = header.subarray(offset, offset + length)
+  if ((raw[0] & 0x80) !== 0) {
+    // GNU base-256（大文件/长数字）：低位大端
+    let value = 0
+    for (const byte of raw) value = value * 256 + (byte & 0x7f)
+    return value
+  }
+  const text = raw.toString('utf8').replace(/\0.*$/u, '').trim()
+  const n = parseInt(text, 8)
+  return Number.isFinite(n) ? n : 0
+}
+
+/** 读 tar 头里的一个字符串字段（NUL 截断）。 */
+function tarString(header, offset, length) {
+  return header.subarray(offset, offset + length).toString('utf8').replace(/\0.*$/u, '')
+}
+
+/**
+ * 解开 tar 归档（**零依赖**最小实现：ustar 前缀 + GNU longname/longlink + pax 头跳过）。
+ *
+ * 安全：条目路径必须落在 `destDir` 内（拒绝绝对路径与 `..` 穿越）—— 归档来自本地缓存，
+ * 但仍按"不可信输入"处理，避免一次坏缓存把文件写到树外。
+ *
+ * @returns {{ files: number, dirs: number, skipped: number }}
+ */
+function extractTar(tarBuf, destDir, { deps = {} } = {}) {
+  const mkdir = deps.mkdir ?? ((d) => mkdirSync(d, { recursive: true }))
+  const write = deps.write ?? ((p, data) => writeFileSync(p, data))
+  const root = resolve(destDir)
+  const rootWithSep = root.endsWith(sep) ? root : root + sep
+
+  let files = 0
+  let dirs = 0
+  let skipped = 0
+  let offset = 0
+  let longName = null
+  let longLink = null
+
+  while (offset + 512 <= tarBuf.length) {
+    const header = tarBuf.subarray(offset, offset + 512)
+    // 全零块 = 归档结束
+    let allZero = true
+    for (const byte of header) { if (byte !== 0) { allZero = false; break } }
+    if (allZero) break
+
+    const size = tarNumber(header, 124, 12)
+    const type = String.fromCharCode(header[156] === 0 ? 48 : header[156])
+    const prefix = tarString(header, 345, 155)
+    const rawName = tarString(header, 0, 100)
+    const body = tarBuf.subarray(offset + 512, offset + 512 + size)
+    offset += 512 + Math.ceil(size / 512) * 512
+
+    // GNU 长名/长链接：内容即下一条目的真名，本条自身不落盘
+    if (type === 'L') { longName = body.toString('utf8').replace(/\0.*$/u, ''); continue }
+    if (type === 'K') { longLink = body.toString('utf8').replace(/\0.*$/u, ''); continue }
+    // pax 扩展头：按"不认识就跳过"处理（不改判据、不猜语义）
+    if (type === 'x' || type === 'g') { skipped += 1; continue }
+
+    const name = longName !== null ? longName : (prefix === '' ? rawName : `${prefix}/${rawName}`)
+    longName = null
+    longLink = null
+    if (name === '') { skipped += 1; continue }
+
+    // npm tarball 统一带 `package/` 前缀 —— 剥掉后落到目标目录
+    const rel = name.replace(/^package\//u, '').replace(/^\.\//u, '')
+    if (rel === '') { skipped += 1; continue }
+
+    const out = resolve(join(root, rel))
+    if (out !== root && !out.startsWith(rootWithSep)) { skipped += 1; continue }
+
+    if (type === '5') { mkdir(out); dirs += 1; continue }
+    if (type === '1' || type === '2' || type === '3' || type === '4' || type === '6') { skipped += 1; continue }
+    mkdir(dirname(out))
+    write(out, body)
+    files += 1
+  }
+  return { files, dirs, skipped }
+}
+
+/** 解开 `.tgz`（gunzip + extractTar）。 */
+function extractTgz(tgzBuf, destDir, { deps = {} } = {}) {
+  const gunzip = deps.gunzip ?? gunzipSync
+  return extractTar(gunzip(tgzBuf), destDir, { deps })
+}
+
+export {
+  candidateCacheRoots,
+  extractTar,
+  extractTgz,
+  integrityToContentPath,
+  readTarball,
+  readTarballFromAny,
+}

package/lib/server/infra/pnpm-release-gate.js

@@ -9,6 +9,21 @@
 //   桌面壳/服务进程给的是**永不关闭的 stdin 管道** ⇒ 不抛错、不超时，**永久挂住**
 //   （实测两次分别挂到 90s / 180s 被杀）。
 //
+// ★ 2026-10-14（实测更正上面这段"现场描述"，**本模块行为未动**）：
+//   上述因果链里"pnpm 弹提问 ⇒ 读 stdin 到 EOF ⇒ 挂住"这一段**实测不成立**：
+//     · pnpm 的 canPrompt = `!inCi && Boolean(process.stdin.isTTY)`（L194277-278）；
+//       管道下 isTTY 恒假 ⇒ pnpm **从不**走 prompt 分支，直接 `throw failOnImmature`。
+//     · 实测（pnpm 11.7.0，minimumReleaseAge 设成天文数字 + 管道 stdin）：无 ci 位 / CI=true /
+//       npm_config_ci=true / --config.ci=true / 两者齐上 —— **五种配置全部快速失败，无一挂住**。
+//     · 真正读 stdin 等人的是 **corepack 的下载提问**（corepack.cjs L22083：
+//       `if (process.stdin.isTTY && !process.env.CI) { stderr.write('? Do you want to continue?');
+//        stdin.resume(); await once(stdin,'data') }`）—— 判据恰恰是 `process.env.CI`。
+//   ⇒ 本模块的定位不变（**识别 + 翻译成可操作错误**，绝不绕过闸门），仍然有价值；
+//     只是"为什么会挂住"要记在 corepack 头上，不是 pnpm 的供应链闸。
+//     顺带更正另两处（详见 infra/exec.js#pnpmEnvOverrides 上方的完整说明）：
+//       · `npm_config_ci=true` 对 pnpm 自己的配置项是**空操作**（只认 `pnpm_config_*`）；
+//       · `CI=true` **确实**点亮 ci 位（pnpm 配置默认值 `ci: isCI`，L145865）。
+//
 // 闸门实现（本机 pnpm 11.7.0 `dist/pnpm.mjs`，只读反编译取证）：
 //   L194277  const inCi = opts3.ci ?? isCI
 //   L194278  const canPrompt = !inCi && Boolean(process.stdin.isTTY)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noob-stupid/dsh-plugin-console",
-  "version": "0.5.49",
+  "version": "0.5.50",
   "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",
@@ -50,7 +50,9 @@
     "lib",
     "cordis.patch.yml",
     "SECURITY.md",
-    "icon.svg"
+    "icon.svg",
+    "scripts/safe-boot.mjs",
+    "scripts/fw-preflight.mjs"
   ],
   "license": "MIT",
   "scripts": {

package/scripts/fw-preflight.mjs

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+// scripts/fw-preflight.mjs —— **服务起不来时的预检与治包**（0.5.50 加法）
+//
+// 为什么要在**服务之外**再来一条命令（真机停机事故 2026-10-14）：
+//   那次的坏法是「框架包被掏空」—— `cordis` 顶层 junction 还在、它指向的 `.pnpm` 实体被清空；
+//   `dsh-llm` / `dsh-tools` / `dsh-web` 直接成了空目录。后果是 dsh 启动即
+//   `54 个插件 failed to import`、web 服务 exit code=1。
+//
+//   而既有的 safe-boot 快照恢复的是 **`cordis.patch.yml` 的文本**（配置层）—— 那次补丁好端端的，
+//   恢复它等于"把一份没坏的配置换成另一份没坏的配置"，四个空目录纹丝不动；
+//   指纹数的是 `.pnpm` 里的**目录个数** —— "壳还在、里面被掏空"⇒ 计数不变 ⇒ 不触发。
+//   最根本的是：**控制台插件是跑在 dsh 里的**，dsh 起不来它就从未加载（事故日志里出现 0 次）。
+//   ⇒ 这类事故必须在**服务之外**有一条出路。这就是本脚本。
+//
+// 三条硬约束（与 scripts/safe-boot.mjs 同族）：
+//   · **零依赖**：只用 Node 内置模块 + 本插件自己的 infra/domain 纯函数（不装包、**不联网**）；
+//   · **服务未运行也能跑**：不读端口、不连 webServer、不需要 profile 正被使用；
+//   · **绝不 kill / spawn / 抢端口 / 建计划任务**：只做文件级修复。
+//     （2026-10-10 的教训：那套"按端口 kill 再拉起"会与宿主争端口 ⇒ `listen EADDRINUSE`，
+//      或让桌面端外壳弹出「应用无法启动或已意外停止」。跑完要不要重启，由你自己决定。）
+//
+// 用法（在插件目录下，或 `node <插件目录>/scripts/fw-preflight.mjs`）：
+//   node scripts/fw-preflight.mjs --check              只诊断，列出坏掉的包（**一个字节都不写**）
+//   node scripts/fw-preflight.mjs --repair             从本地 npm 缓存把缺的包装回来，再复验
+//   node scripts/fw-preflight.mjs --check --json       机器可读输出
+//   可选：--fw-root <dir>  指定框架树（默认自动探测：从本插件解析 @deepseek-ai/dsh 反推）
+//         --cache <dir>   指定 npm 缓存根（默认自动找 npm_config_cache / %LOCALAPPDATA%\npm-cache / 常见位置）
+//         --help          显示本帮助
+
+import { isAbsolute, resolve } from 'node:path'
+import { dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { detectFrameworkRoot } from '../lib/server/infra/fw-root-detect.js'
+import { runFwPreflight } from '../lib/server/domain/fw-preflight.js'
+
+const PLUGIN_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+
+const HELP = `框架闭包预检与治包（fw-preflight）—— 服务起不来时用这个，不需要服务在跑。
+
+用法：
+  node scripts/fw-preflight.mjs --check
+      只诊断：从 dsh 的 lib/bin.js 出发走一遍 @deepseek-ai/* 依赖闭包，
+      列出**解析不了**的包（= 真正的损坏面）。一个字节都不写。
+
+  node scripts/fw-preflight.mjs --repair
+      把解析不了的包装回来：按 package-lock.json 的 integrity 从**本地 npm 缓存**取 tarball 解开。
+      改前若目标已有内容，先改名成 <name>.preflight-bak-<时间戳>（绝不直接删）。
+      装完**重新走一遍闭包复验**，不靠"我装完了"自证。
+
+可选参数：
+  --fw-root <dir>   框架树根（含 @deepseek-ai/ 与 .pnpm/）。默认自动探测。
+  --cache <dir>     npm 缓存根（含 content-v2/）。默认自动探测，可重复。
+  --json            机器可读输出（面板/子代理可直接解析）。
+  --help            显示本帮助。
+
+判据为什么是"能不能解析"而不是"目录空不空"：
+  这次事故的形态是「目录壳还在、里面被掏空」—— 数目录个数完全看不见
+  （2026-10-14 实测：按"目录空不空"粗扫本机会误报 237 个；换成闭包判据后 287 个包精准通过，
+   清空一个立刻只点名那一个）。
+
+它不做什么：
+  不 kill 进程、不 spawn 服务、不抢端口、不建计划任务、不联网。
+  修完请自己重启服务（桌面端：完全退出再打开；独立 dsh web：终端里 Ctrl+C 后重跑）。
+`
+
+/** 解析命令行（只认本脚本声明的这几个开关；未知参数如实报错，不静默忽略）。 */
+function parseArgv(argv) {
+  const out = { mode: null, fwRoot: null, caches: [], json: false, help: false, bad: [] }
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i]
+    if (a === '--check') out.mode = 'check'
+    else if (a === '--repair') out.mode = 'repair'
+    else if (a === '--json') out.json = true
+    else if (a === '--help' || a === '-h') out.help = true
+    else if (a === '--fw-root') { out.fwRoot = argv[i + 1] ?? null; i += 1 }
+    else if (a === '--cache') { const v = argv[i + 1]; if (v) out.caches.push(v); i += 1 }
+    else out.bad.push(a)
+  }
+  return out
+}
+
+/**
+ * 探测框架树根：多基准（见 lib/server/infra/fw-root-detect.js 的头注释）。
+ * 这里只做转发，判据收在 infra 一处 —— 脚本与（日后的）路由不会分叉。
+ */
+function detectFwRoot() {
+  return detectFrameworkRoot({ pluginDir: PLUGIN_ROOT })
+}
+
+/** 把探测结果 + 修复结果渲染成人读报告。 */
+function renderReport(report, { attempted }) {
+  const lines = []
+  const bad = report.before?.broken ?? []
+  lines.push(`框架树 : ${report.fwRoot ?? '(未探测到)'}`)
+  lines.push(`解析入口: ${report.entry ?? '(无)'}${report.entryVia === null || report.entryVia === undefined ? '' : `  [${report.entryVia}]`}`)
+  lines.push(`npm 缓存: ${(report.cacheRoots ?? []).join(' ; ') || '(未找到 —— 只能诊断，不能修复)'}`)
+  lines.push('')
+  if (report.error !== undefined && report.error !== null) {
+    lines.push(`✗ ${report.error}`)
+    return lines.join('\n')
+  }
+  const walked = report.before?.walked?.length ?? 0
+  lines.push(attempted ? `① 修复前：走了 ${walked} 个包，${bad.length} 个解析不了` : `走了 ${walked} 个包，${bad.length} 个解析不了`)
+  for (const b of bad) lines.push(`   ✗ ${b.name}   ← ${b.from}  (${b.reason})`)
+  if (bad.length === 0) lines.push('   ✓ 依赖闭包完整 —— 框架树是好的，起不来的原因不在这里')
+
+  if (!attempted) {
+    if (bad.length > 0) lines.push('\n用 --repair 试着把它们装回来（只动文件，不碰任何进程）。')
+    return lines.join('\n')
+  }
+
+  lines.push('')
+  lines.push(`② 本次修复：成功 ${report.repaired.length} 个，失败 ${report.failed.length} 个，不可修 ${report.skipped.length} 个`)
+  for (const r of report.repaired) lines.push(`   ✓ ${r.name}@${r.version}  → ${r.via}  ${r.note}`)
+  for (const f of report.failed) lines.push(`   ✗ ${f.name}  (${f.action})  ${f.note}`)
+  for (const s of report.skipped) {
+    const why = { 'no-lock-entry': 'package-lock.json 里没有它的记录 —— 不猜版本', 'no-integrity': '记录里没有 integrity 校验和', 'no-target': '定不出该装到哪个目录' }[s.reason] ?? s.reason
+    lines.push(`   · ${s.name}  ${why}`)
+  }
+
+  lines.push('')
+  const after = report.after?.broken ?? []
+  lines.push(`③ 复验：走了 ${report.after?.walked?.length ?? 0} 个包，${after.length} 个仍解析不了`)
+  for (const b of after) lines.push(`   ✗ ${b.name}   ← ${b.from}`)
+  if (report.okAfter === true) {
+    lines.push('   ✓ 闭包已完整')
+    lines.push('')
+    lines.push('接下来：重启服务让修复生效（本脚本**不会**替你 kill / 拉起进程）。')
+    lines.push('  · 桌面端：完全退出 DeepSeek Harness，再重新打开')
+    lines.push('  · 独立 dsh web：在启动它的终端里 Ctrl+C，然后重新运行 dsh web')
+  } else {
+    lines.push('')
+    lines.push('仍有包解析不了。可能原因：本地 npm 缓存里也没有那些 tarball（本脚本不联网）。')
+    lines.push('可对该包单独装一次（会联网）：dsh plugin --profile <名> add <包名>')
+  }
+  return lines.join('\n')
+}
+
+async function main() {
+  const args = parseArgv(process.argv.slice(2))
+  if (args.help) { process.stdout.write(HELP); return 0 }
+  if (args.bad.length > 0) {
+    process.stderr.write(`未知参数：${args.bad.join(' ')}\n\n${HELP}`)
+    return 2
+  }
+  if (args.mode === null) {
+    process.stderr.write(`请指定 --check 或 --repair（或 --help）。\n\n${HELP}`)
+    return 2
+  }
+
+  let fwRoot = args.fwRoot
+  let via = 'explicit'
+  let tried = []
+  if (typeof fwRoot !== 'string' || fwRoot === '') {
+    const d = detectFwRoot()
+    fwRoot = d.fwRoot
+    via = d.via
+    tried = d.tried ?? []
+  } else {
+    fwRoot = isAbsolute(fwRoot) ? fwRoot : resolve(process.cwd(), fwRoot)
+  }
+
+  if (fwRoot === null || fwRoot === undefined || fwRoot === '') {
+    const msg = '探测不到框架树根 —— 请用 --fw-root <dir> 显式指定（该目录下应有 @deepseek-ai/ 与 .pnpm/）。'
+    const detail = tried.map((t) => `  · 试过 ${t.via}: ${t.base}`).join('\n')
+    if (args.json) process.stdout.write(`${JSON.stringify({ ok: false, error: msg, tried }, null, 2)}\n`)
+    else process.stderr.write(`✗ ${msg}\n${detail}\n`)
+    return 1
+  }
+
+  const cacheRoots = args.caches.length > 0 ? args.caches.map((c) => (isAbsolute(c) ? c : resolve(process.cwd(), c))) : null
+  const report = runFwPreflight({ fwRoot, repair: args.mode === 'repair', cacheRoots })
+  const payload = { ...report, fwRootVia: via, mode: args.mode }
+
+  if (args.json) process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`)
+  else process.stdout.write(`${renderReport(payload, { attempted: args.mode === 'repair' })}\n`)
+
+  // 退出码：诊断模式 = 闭包是否完整；修复模式 = 修复后是否完整（供脚本/CI 判断）
+  const good = args.mode === 'repair' ? report.okAfter === true : report.ok === true
+  return good ? 0 : 1
+}
+
+main().then((code) => { process.exitCode = code }, (error) => {
+  process.stderr.write(`fw-preflight 异常：${error?.stack ?? error}\n`)
+  process.exitCode = 1
+})