@noob-stupid/dsh-plugin-console 0.5.29 → 0.5.30

package/lib/client.js

@@ -342,6 +342,17 @@ window.__ModuleLoader__.load({
 			githubLoginFail: "登录失败",
 			hubUpdateAvailable: "下载更新",
 			cleanResiduals: "清理残余备份",
+			cleanFrameworkResiduals: "清理框架残留",
+			cfStale: "旧目录 {n} 个",
+			cfBackups: "可清备份 {n} 条（约 {mb} MB）",
+			cfEntities: "旧 store 实体 {n} 个（只报告）",
+			cfConfirm: "确认执行？旧目录会改名备份并重建链接；超出保留数量的框架备份会被删除。",
+			cfNothing: "没有需要清理的项",
+			cfCancelled: "已取消（未改动任何文件）",
+			cfRunning: "正在执行清理…",
+			cfDone: "已改名 {renamed} / 重建链接 {linked} / 删备份 {removed} 条（释放约 {mb} MB）",
+			cfFailed: "{n} 项失败（详见 fw/console 日志）",
+			compatNoticeDismiss: "我知道了（此版本不再提示）",
 					searchInstalledPlaceholder: "搜索已安装插件（名称或 id）",
 			extraFilter: "已装",
 			extraFilterAll: "全部",
@@ -871,6 +882,17 @@ window.__ModuleLoader__.load({
 			githubLoggedIn: "GitHub signed in: ",
                     hubUpdateAvailable: "Download update",
                     cleanResiduals: "Clean residual backups",
+                    cleanFrameworkResiduals: "Clean framework residuals",
+                    cfStale: "{n} stale dirs",
+                    cfBackups: "{n} backups removable (~{mb} MB)",
+                    cfEntities: "{n} old store entities (report only)",
+                    cfConfirm: "Proceed? Stale dirs get renamed+relinked; framework backups beyond the keep count are deleted.",
+                    cfNothing: "nothing to clean",
+                    cfCancelled: "cancelled (nothing changed)",
+                    cfRunning: "cleaning…",
+                    cfDone: "renamed {renamed} / relinked {linked} / backups removed {removed} (~{mb} MB freed)",
+                    cfFailed: "{n} failed (see fw/console logs)",
+     compatNoticeDismiss: "Got it (hide for this version)",
 			githubCornerOut: "Not signed in to GitHub",
 			githubLoginViaApp: "GitHub login",
 			githubLoginOpened: "Authorization window opened — enter the code on the GitHub page to finish",
@@ -4038,6 +4060,7 @@ window.__ModuleLoader__.load({
 			const gatePendingCount = gateReady ? (state.data.compatPending?.pending ?? []).length : 0;
 			// 门控明细清单（用户 2026-09-24 要求：面板要显示"是哪些插件"，不只是数量）
 			const [gateShowAll, setGateShowAll] = react.useState(false);
+			const [compatNoticeClosed, setCompatNoticeClosed] = react.useState(false);
 			const gateRows = gateReady ? (state.data.gating ?? null) : null;
 			const gateTime = (ms) => (typeof ms === "number" && ms > 0 ? new Date(ms).toLocaleString() : "—");
 			// 「功能包 → 框架」按钮角标：升级进行中 ⟳ / 上次失败 ✕ / 有可用更新 ↑（优先级从高到低）
@@ -4045,9 +4068,29 @@ window.__ModuleLoader__.load({
 				&& frameworkStatus.status !== "idle" && frameworkStatus.status !== "done" && frameworkStatus.status !== "failed";
 			const fwBadge = fwRunning ? " ⟳" : (frameworkStatus?.status === "failed" ? " ✕" : (fwCheck?.target ? " ↑" : ""));
 			return el("section", { ref: sectionRef, className: styles.section, "aria-busy": state.status === "loading" },
-				state.status === "ready" && state.data.compat && !state.data.compat.supported
-					? el("p", { className: styles.message, "data-error": "true" }, state.data.compat.notice)
-					: null,
+				// 兼容提示（2026-09-28 加法）：以前是纯 <p>，关不掉。现在按服务端的 noticeVisible 显示
+				// （老服务端没有该字段时回落 !supported），并给一个手动关闭入口 —— 关闭只影响展示：
+				// 服务端记的是「这个框架版本我看过了」，版本一变会重新提示；supported 与门控语义一个字都不变。
+				state.status === "ready" && state.data.compat
+				  && (state.data.compat.noticeVisible === undefined
+				    ? !state.data.compat.supported
+				    : state.data.compat.noticeVisible === true)
+				  && !compatNoticeClosed
+				  ? el("p", { className: styles.message, "data-error": "true" },
+				      state.data.compat.notice,
+				      " ",
+				      el("button", {
+				        type: "button",
+				        style: { marginLeft: "8px", cursor: "pointer" },
+				        title: t("compatNoticeDismiss"),
+				        onClick: () => {
+				          // 失败不收起（关了却还在服务端显示会造成「点了没反应」的错觉）
+				          call("/plugin-console/compat-ack", { webAppVersion: state.data.compat?.webAppVersion })
+				            .then(() => setCompatNoticeClosed(true), () => {});
+				        },
+				      }, t("compatNoticeDismiss")),
+				    )
+				  : null,
 				state.status === "ready" && comps.length > 0 && details === null && repoInfo === null
 					? el("button", {
 						type: "button",
@@ -4393,6 +4436,49 @@ window.__ModuleLoader__.load({
 							);
 						},
 					}, "🧹 " + t("cleanResiduals")),
+      el("button", {
+        type: "button",
+        style: { position: "fixed", left: 12, bottom: 44, zIndex: 1000, opacity: 0.75 },
+        title: t("cleanFrameworkResiduals"),
+        onClick: () => {
+          // 2026-09-28 加法：框架残留清理（顶层旧版本目录 / framework-backups）。两步走：
+          // 先 dryRun 出报告 → window.confirm 让用户看清要动什么 → 才带 confirm:true 真执行。
+          // 服务端默认 dryRun，所以「误点一下」不会动任何文件。
+          const SCOPES = ["framework", "frameworkBackups", "pnpmEntities"];
+          setMessage(t("cleanFrameworkResiduals") + "…");
+          call("/plugin-console/clean-residuals", { scope: SCOPES }).then(
+            (report) => {
+              const fw = report && report.framework ? report.framework : null;
+              const bk = report && report.frameworkBackups ? report.frameworkBackups : null;
+              const pe = report && report.pnpmEntities ? report.pnpmEntities : null;
+              const stale = fw && Array.isArray(fw.planned) ? fw.planned.length : 0;
+              const pend = bk && Array.isArray(bk.plannedRemove) ? bk.plannedRemove : [];
+              const mb = Math.round(pend.reduce((s, it) => s + (it && Number.isFinite(it.sizeBytes) ? it.sizeBytes : 0), 0) / 1048576);
+              const entities = pe && Number.isFinite(pe.entityCount) ? pe.entityCount : 0;
+              const head = t("cleanFrameworkResiduals") + "：" + t("cfStale").replace("{n}", String(stale))
+                + "、" + t("cfBackups").replace("{n}", String(pend.length)).replace("{mb}", String(mb))
+                + (entities > 0 ? "；" + t("cfEntities").replace("{n}", String(entities)) : "");
+              if (stale === 0 && pend.length === 0) { setMessage(head + "；" + t("cfNothing")); return; }
+              if (!window.confirm(head + "\n" + t("cfConfirm"))) { setMessage(head + "；" + t("cfCancelled")); return; }
+              setMessage(t("cfRunning"));
+              call("/plugin-console/clean-residuals", { scope: SCOPES, confirm: true, keep: 1 }).then(
+                (done) => {
+                  const renamed = done && done.framework && Array.isArray(done.framework.renamed) ? done.framework.renamed.length : 0;
+                  const relinked = done && done.framework && Array.isArray(done.framework.relinked) ? done.framework.relinked.length : 0;
+                  const removed = done && done.frameworkBackups && Array.isArray(done.frameworkBackups.removed) ? done.frameworkBackups.removed.length : 0;
+                  const freed = done && done.frameworkBackups && Number.isFinite(done.frameworkBackups.freedBytes) ? Math.round(done.frameworkBackups.freedBytes / 1048576) : 0;
+                  const failed = (done && done.framework && Array.isArray(done.framework.failed) ? done.framework.failed.length : 0)
+                    + (done && done.frameworkBackups && Array.isArray(done.frameworkBackups.failed) ? done.frameworkBackups.failed.length : 0);
+                  setMessage(t("cfDone").replace("{renamed}", String(renamed)).replace("{linked}", String(relinked)).replace("{removed}", String(removed)).replace("{mb}", String(freed))
+                    + (failed > 0 ? "；" + t("cfFailed").replace("{n}", String(failed)) : ""));
+                },
+                (error) => setMessage(t("failed") + "：" + friendlyGithubError(error).message),
+              );
+            },
+            (error) => setMessage(t("failed") + "：" + friendlyGithubError(error).message),
+          );
+        },
+      }, "🧰 " + t("cleanFrameworkResiduals")),
 				fwShowCard
 					? el("div", { className: styles.detail },
 						el("div", { className: styles.rowTop },

package/lib/server/domain/compat.js

@@ -197,7 +197,7 @@ function writeCompatPending(payload) {
  *  autoDetect  —— 打开控制台时是否自动检测「已适配」（关掉 = 不显示可解锁提示） */
 const COMPAT_GATE_FILE = () => join(dshHome(), 'plugin-console', 'compat-gate.json')
 
-const COMPAT_GATE_DEFAULTS = { autoDisable: true, autoDetect: true }
+const COMPAT_GATE_DEFAULTS = { autoDisable: true, autoDetect: true, noticeMode: 'once-per-version' }
 
 function readCompatGate() {
   try {
@@ -205,6 +205,8 @@ function readCompatGate() {
     return {
       autoDisable: raw?.autoDisable !== false,
       autoDetect: raw?.autoDetect !== false,
+      // 兼容提示的展示模式（2026-09-28 加法）：非法/缺失一律回落默认，**不影响 supported 判定**
+      noticeMode: NOTICE_MODES.includes(raw?.noticeMode) ? raw.noticeMode : DEFAULT_NOTICE_MODE,
     }
   } catch { return { ...COMPAT_GATE_DEFAULTS } }
 }
@@ -218,6 +220,49 @@ function writeCompatGate(patch) {
   return next
 }
 
+/** 兼容提示的展示模式（2026-09-28 加法）：
+ *  · `always`           每次都提示
+ *  · `once-per-version` 同一框架版本只提示一次（默认；用户点「我知道了」后不再出现，**版本一变重新提示**）
+ *  · `off`              不提示（需显式设置）
+ * ⚠ 它只影响**展示** —— `supported` 的判定与门控语义一个字都不变（披露不能被"关掉"成看不见的风险）。 */
+const NOTICE_MODES = ['always', 'once-per-version', 'off']
+const DEFAULT_NOTICE_MODE = 'once-per-version'
+
+const COMPAT_ACK_FILE = () => join(dshHome(), 'plugin-console', 'compat-ack.json')
+
+/** 读「已确认看过」的框架版本（按版本记：换版本自动重新提示）。 */
+function readCompatAck() {
+  try {
+    const raw = JSON.parse(readFileSync(COMPAT_ACK_FILE(), 'utf8'))
+    return {
+      version: typeof raw?.version === 'string' && raw.version !== '' ? raw.version : null,
+      at: Number.isFinite(raw?.at) ? raw.at : null,
+    }
+  } catch { return { version: null, at: null } }
+}
+
+/** 写 ack（整文件覆盖：只记最后一个确认过的版本，语义就是"这个版本我看过了"）。 */
+function writeCompatAck(version) {
+  const next = { version: String(version), at: Date.now() }
+  try {
+    mkdirSync(dirname(COMPAT_ACK_FILE()), { recursive: true })
+    writeFileSync(COMPAT_ACK_FILE(), JSON.stringify(next, null, 2), 'utf8')
+  } catch {}
+  return next
+}
+
+/** 提示该不该显示（纯函数，离线可断言）。**绝不修改 supported**。 */
+function resolveNoticeState({ supported, notice, webAppVersion, noticeMode, ackVersion } = {}) {
+  if (notice === null || notice === undefined || notice === '') return { visible: false, reason: 'no-notice' }
+  if (supported === true) return { visible: false, reason: 'supported' }
+  const mode = NOTICE_MODES.includes(noticeMode) ? noticeMode : DEFAULT_NOTICE_MODE
+  if (mode === 'off') return { visible: false, reason: 'mode-off' }
+  if (mode === 'always') return { visible: true, reason: 'mode-always' }
+  const acked = typeof ackVersion === 'string' && ackVersion !== ''
+    && typeof webAppVersion === 'string' && webAppVersion !== ''
+    && ackVersion === webAppVersion
+  return acked ? { visible: false, reason: 'version-acked' } : { visible: true, reason: 'first-sight' }
+}
 /** 把框架适配检测结果格式化为给子代理的提示段。 */
 function frameworkCheckPromptText(fc) {
   if (fc === null || fc === undefined) return '（不可用）'
@@ -263,6 +308,27 @@ async function detectCompat(baseUrl) {
     result.supported = false
     result.notice = `当前 DSH web 包版本 ${result.webAppVersion} 不在受支持的 0.1.x 系列内，插件控制台的部分功能可能因官方破坏性更新而失效；请到 https://github.com/Noob-stupid/dsh-plugin-gating-hub 获取匹配的更新`
   }
+  // 展示层（2026-09-28 加法）：`supported` 与 `notice` 保持原样，这里只额外给出"该不该显示 + 为什么"。
+  try {
+    const gate = readCompatGate()
+    const ack = readCompatAck()
+    const resolved = resolveNoticeState({
+      supported: result.supported,
+      notice: result.notice,
+      webAppVersion: result.webAppVersion,
+      noticeMode: gate.noticeMode,
+      ackVersion: ack.version,
+    })
+    result.noticeMode = gate.noticeMode
+    result.noticeVisible = resolved.visible
+    result.noticeReason = resolved.reason
+    result.noticeAckedAt = ack.version !== null && ack.version === result.webAppVersion ? ack.at : null
+  } catch {
+    result.noticeMode = DEFAULT_NOTICE_MODE
+    result.noticeVisible = result.supported === false
+    result.noticeReason = 'fallback'
+    result.noticeAckedAt = null
+  }
   return result
 }
 
@@ -471,4 +537,4 @@ async function frameworkCompatReportFor(source, ports, profileDir) {
     summary: parts.length > 0 ? parts.join('；') : `框架 ${fwVer}，无待适配记录`,
   }
 }
-export { gatingSummary, COMPAT_PENDING_FILE, COMPAT_GATE_FILE, COMPAT_GATE_DEFAULTS, REMOVED_SETTINGS_SYMBOLS, FIBER_STATE, FIBER_PHASE, SUPPORTED_WEB_APP_PATTERN, referencesRemovedSymbol, scanSettingsApiUsage, isFrameworkOwnedPackage, checkPluginFrameworkCompat, probePluginImport, readCompatPending, writeCompatPending, readCompatGate, writeCompatGate, frameworkCheckPromptText, CONSOLE_VERSION, detectCompat, detectAdoptablePending, rowIdModuleMap, frameworkCompatReportFor, maybeAutoAdaptCompat }
+export { gatingSummary, COMPAT_PENDING_FILE, COMPAT_GATE_FILE, COMPAT_ACK_FILE, COMPAT_GATE_DEFAULTS, NOTICE_MODES, DEFAULT_NOTICE_MODE, REMOVED_SETTINGS_SYMBOLS, FIBER_STATE, FIBER_PHASE, SUPPORTED_WEB_APP_PATTERN, referencesRemovedSymbol, scanSettingsApiUsage, isFrameworkOwnedPackage, checkPluginFrameworkCompat, probePluginImport, readCompatPending, writeCompatPending, readCompatGate, writeCompatGate, readCompatAck, writeCompatAck, resolveNoticeState, frameworkCheckPromptText, CONSOLE_VERSION, detectCompat, detectAdoptablePending, rowIdModuleMap, frameworkCompatReportFor, maybeAutoAdaptCompat }

package/lib/server/domain/framework-cleanup.js

@@ -0,0 +1,225 @@
+// L1 · domain —— framework-cleanup.js（框架树残留的**动作**层：顶层版本漂移 / 框架备份保留；0.5.30 加法）
+//
+// 判据在 domain/framework-residuals.js（纯函数）；这里只负责「读现场 → 执行 → 如实回报」。
+// 真机背景见该模块头注释（顶层 239 个 0.1.5-rc.2 真实目录；framework-backups 12 条快照约 5.1 GB）。
+//
+// 三条安全约定（对齐仓库既有纪律）：
+//   ① **一律先改名备份**：顶层旧目录 → `<name>.stale-<ver>-<ts>`，绝不直接删（可回滚）。
+//   ② 重建 junction 只在**目标确实存在**时做：目标从 `dsh` junction 的同级目录推（运行树的真实位置）；
+//      推不到或目标不存在就只改名，并如实记进 `relinkSkipped`（不假装成功）。
+//   ③ 框架备份只删 `fw-tree/<ts>` 目录，**绝不碰** `dsh-package-backup` 与目录下的快照文件。
+
+import { existsSync, readdirSync, readFileSync, readlinkSync, renameSync, statSync, symlinkSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { removeDirVerifiedAsync } from '../infra/fsx.js'
+import { dshHome, resolvePackageJson } from '../infra/paths.js'
+import { classifyTopLevel, planBackupRetention } from './framework-residuals.js'
+
+/** 目录体积（失败返回 0；只用于报告「能释放多少」）。 */
+function dirSizeBytes(dir) {
+  let total = 0
+  const walk = (d) => {
+    let entries = []
+    try { entries = readdirSync(d, { withFileTypes: true }) } catch { return }
+    for (const entry of entries) {
+      const full = join(d, entry.name)
+      try {
+        if (entry.isDirectory()) walk(full)
+        else if (entry.isFile()) total += statSync(full).size
+      } catch {}
+    }
+  }
+  walk(dir)
+  return total
+}
+
+/** 是不是链接（Windows 的 junction 在 dirent 上不一定报 symbolic link → readlink 兜底）。 */
+function isLinkEntry(full, dirent, readLink = readlinkSync) {
+  try { if (dirent.isSymbolicLink()) return true } catch {}
+  try { readLink(full); return true } catch { return false }
+}
+
+/**
+ * A 档：顶层投影里的旧版本真实目录 → 改名备份（+ 可选重建 junction）。
+ * `topScopeDir` = `<frameworkRoot>/node_modules/@deepseek-ai`；`dshLinkPath` = 同目录下的 `dsh`（运行树入口）。
+ */
+async function cleanFrameworkTopLevel({ topScopeDir, dshLinkPath = null, runningVersion = null, relink = true, dryRun = false, stamp = null, deps = {} } = {}) {
+  const {
+    exists = existsSync, readdir = readdirSync, readText = (f) => readFileSync(f, 'utf8'),
+    rename = renameSync, link = symlinkSync, readLink = readlinkSync,
+  } = deps
+  if (topScopeDir === null || topScopeDir === undefined || !exists(topScopeDir)) {
+    return { ok: false, error: '框架顶层目录不存在（拿不到 @deepseek-ai/* 的真实位置）', renamed: [], relinked: [], relinkSkipped: [], failed: [] }
+  }
+  const entries = []
+  for (const dirent of readdir(topScopeDir, { withFileTypes: true })) {
+    const full = join(topScopeDir, dirent.name)
+    let version = null
+    try { version = JSON.parse(readText(join(full, 'package.json'))).version ?? null } catch { version = null }
+    entries.push({
+      name: dirent.name,
+      version,
+      isLink: isLinkEntry(full, dirent, readLink),
+      sizeBytes: dirSizeBytes(full),
+    })
+  }
+  const classified = classifyTopLevel(entries, { runningVersion })
+  const runningScopeDir = (() => {
+    if (dshLinkPath === null) return null
+    try { return dirname(readLink(dshLinkPath)) } catch { return null }
+  })()
+  const ts = stamp === null ? String(Date.now()) : String(stamp)
+  const renamed = []
+  const relinked = []
+  const relinkSkipped = []
+  const failed = []
+  for (const item of (dryRun === true ? [] : classified.stale)) {
+    const backupName = item.name + '.stale-' + item.version + '-' + ts
+    try {
+      rename(join(topScopeDir, item.name), join(topScopeDir, backupName))
+    } catch (error) {
+      failed.push({ name: item.name, error: String(error?.message ?? error) })
+      continue
+    }
+    renamed.push({ name: item.name, version: item.version, backup: backupName, sizeBytes: item.sizeBytes ?? null })
+    if (relink !== true) { relinkSkipped.push({ name: item.name, reason: 'relink-off' }); continue }
+    if (runningScopeDir === null) { relinkSkipped.push({ name: item.name, reason: 'no-running-scope' }); continue }
+    const target = join(runningScopeDir, item.name)
+    let targetExists = false
+    try { targetExists = exists(target) } catch { targetExists = false }
+    if (!targetExists) { relinkSkipped.push({ name: item.name, reason: 'target-missing' }); continue }
+    try {
+      link(target, join(topScopeDir, item.name), 'junction')
+      relinked.push({ name: item.name, target })
+    } catch (error) {
+      failed.push({ name: item.name, error: '已改名但重建链接失败：' + String(error?.message ?? error) })
+    }
+  }
+  return {
+    ok: failed.length === 0,
+    renamed,
+    relinked,
+    relinkSkipped,
+    failed,
+    staleCount: classified.stale.length,
+    sameVersionCount: classified.sameVersion.length,
+    missingVersion: classified.missingVersion,
+    dryRun,
+    planned: classified.stale.map((s) => ({ name: s.name, version: s.version, sizeBytes: s.sizeBytes ?? null })),
+  }
+}
+
+/**
+ * C 档：`framework-backups/<版本>/fw-tree/<ts>` 快照按「回滚点那条 ∪ 最近 N 条」保留，其余删除。
+ * 只删 fw-tree 快照目录；`dsh-package-backup` 与目录下的快照文件一律不碰。
+ */
+async function cleanFrameworkBackups({ backupsRoot, referenced = [], keep = 1, dryRun = false, deps = {} } = {}) {
+  const { exists = existsSync, readdir = readdirSync, stat = statSync, remove = removeDirVerifiedAsync, sizeOf = dirSizeBytes } = deps
+  if (backupsRoot === null || backupsRoot === undefined || !exists(backupsRoot)) {
+    return { ok: false, error: '没有框架备份目录（无需清理）', snapshots: 0, kept: [], removed: [], failed: [], freedBytes: 0 }
+  }
+  const snapshots = []
+  for (const versionDir of readdir(backupsRoot, { withFileTypes: true })) {
+    if (!versionDir.isDirectory()) continue
+    const fwTree = join(backupsRoot, versionDir.name, 'fw-tree')
+    if (!exists(fwTree)) continue
+    for (const snap of readdir(fwTree, { withFileTypes: true })) {
+      if (!snap.isDirectory()) continue
+      const full = join(fwTree, snap.name)
+      let mtimeMs = 0
+      try { mtimeMs = stat(full).mtimeMs } catch { mtimeMs = 0 }
+      let sizeBytes = 0
+      try { sizeBytes = sizeOf(full) } catch { sizeBytes = 0 }
+      snapshots.push({ path: full, version: versionDir.name, id: snap.name, mtimeMs, sizeBytes })
+    }
+  }
+  const plan = planBackupRetention(snapshots, { referenced, keep })
+  const removed = []
+  const failed = []
+  for (const snap of (dryRun === true ? [] : plan.remove)) {
+    try {
+      const res = await remove(snap.path)
+      if (res !== null && res !== undefined && res.ok === false) failed.push({ path: snap.path, error: res.error ?? '删除失败' })
+      else removed.push({ path: snap.path, sizeBytes: snap.sizeBytes ?? 0 })
+    } catch (error) {
+      failed.push({ path: snap.path, error: String(error?.message ?? error) })
+    }
+  }
+  const freedBytes = removed.reduce((sum, item) => sum + (Number.isFinite(item.sizeBytes) ? item.sizeBytes : 0), 0)
+  return {
+    ok: failed.length === 0,
+    snapshots: snapshots.length,
+    kept: plan.kept.map((s) => ({ path: s.path, reason: s.reason, sizeBytes: s.sizeBytes ?? 0 })),
+    removed,
+    failed,
+    freedBytes,
+    dryRun,
+    plannedRemove: plan.remove.map((s) => ({ path: s.path, version: s.version, sizeBytes: s.sizeBytes ?? 0 })),
+  }
+}
+
+/**
+ * B 档（**只报告，不删**）：`.pnpm` 里版本 ≠ 运行版本的框架包实体。
+ * 手删 `.pnpm` 会让 lockfile 与实际不一致（真机教训：9/24 一个 package.json 缺失 → framework.version=null），
+ * 所以这里只点名 + 给建议（用 pnpm 自己同步），不提供删除。
+ */
+function reportFrameworkEntities({ pnpmDir, runningVersion = null } = {}) {
+  if (pnpmDir === null || pnpmDir === undefined || !existsSync(pnpmDir)) {
+    return { ok: false, error: '拿不到 .pnpm 目录', groups: [], entityCount: 0 }
+  }
+  const groups = new Map()
+  for (const dirent of readdirSync(pnpmDir, { withFileTypes: true })) {
+    if (!dirent.isDirectory()) continue
+    const m = dirent.name.match(/^@deepseek-ai\+dsh(?:-[a-z0-9]+)*@(\d+\.\d+\.\d+[^_]*)_/u)
+    if (m === null) continue
+    const version = m[1]
+    if (runningVersion !== null && version === String(runningVersion)) continue
+    if (!groups.has(version)) groups.set(version, [])
+    groups.get(version).push(dirent.name)
+  }
+  const out = [...groups.entries()]
+    .map(([version, names]) => ({ version, count: names.length, sample: names.slice(0, 3) }))
+    .sort((a, b) => a.version.localeCompare(b.version))
+  return {
+    ok: true,
+    groups: out,
+    entityCount: out.reduce((sum, g) => sum + g.count, 0),
+    hint: '这些是历史版本的虚拟 store 实体；建议用 pnpm 自己同步（在该框架根跑 pnpm install），不要手删目录',
+  }
+}
+
+
+/** 框架布局推导（compat.js 同款取法）：找「含 .pnpm 的那层 node_modules」= 顶层投影目录。
+ *  返回 { fwRoot, topScopeDir, dshLinkPath, pnpmDir } —— 顶层 239 个旧真实目录就在 topScopeDir 下。 */
+function resolveFrameworkLayout({ baseDir, profileDir, deps = {} } = {}) {
+  const { exists = existsSync, resolvePkg = resolvePackageJson } = deps
+  let fwRoot = null
+  try {
+    const pkgPath = resolvePkg('@deepseek-ai/dsh', baseDir, profileDir)
+    if (pkgPath !== null && pkgPath !== undefined) {
+      let dir = dirname(dirname(pkgPath))
+      for (let i = 0; i < 6; i += 1) {
+        if (exists(join(dir, '.pnpm'))) { fwRoot = dir; break }
+        const up = dirname(dir)
+        if (up === dir) break
+        dir = up
+      }
+    }
+  } catch {}
+  return {
+    fwRoot,
+    topScopeDir: fwRoot === null ? null : join(fwRoot, '@deepseek-ai'),
+    dshLinkPath: fwRoot === null ? null : join(fwRoot, '@deepseek-ai', 'dsh'),
+    pnpmDir: fwRoot === null ? null : join(fwRoot, '.pnpm'),
+  }
+}
+
+/** 回滚点引用的路径（framework-rollback.json 的 checkpointDir / cliBackupDir）—— 这些永远不删。 */
+function readRollbackReferenced({ home = undefined, deps = {} } = {}) {
+  const { readText = (p) => readFileSync(p, 'utf8'), base = dshHome() } = deps
+  try {
+    const raw = JSON.parse(readText(join(home ?? base, 'plugin-console', 'framework-rollback.json')))
+    return [raw?.checkpointDir, raw?.cliBackupDir].filter((p) => typeof p === 'string' && p !== '')
+  } catch { return [] }
+}
+export { cleanFrameworkBackups, cleanFrameworkTopLevel, dirSizeBytes, isLinkEntry, readRollbackReferenced, reportFrameworkEntities, resolveFrameworkLayout }

package/lib/server/domain/framework-residuals.js

@@ -0,0 +1,59 @@
+// L1 · domain —— framework-residuals.js（框架树残留判据 + 备份保留策略；0.5.30 加法）
+//
+// 真机背景（2026-09-28）：
+//   ① 框架树顶层 `@deepseek-ai/` 有 **239 个非 junction 的真实目录**，其中 230 个还停在
+//      0.1.5-rc.2（npm 时代残留）：`dsh` 一个被 junction 到 0.2.0-rc.1 → 于是"从顶层解析"与
+//      "从运行树解析"会拿到**不同版本**（9/10 桌面端扫描错配、9/24 schemastery 3.18.1 漂移同族）。
+//   ② `~/.dsh/plugin-console/framework-backups` 堆了 12 条 fw-tree 快照（约 5.1 GB），
+//      而回滚只需要**回滚点引用的那一条** + **最近 N 条**。
+//
+// 本模块只做纯判据（IO 全由调用方注入），动作在 routes/plugins.js 的 clean-residuals scope 里：
+//   · `classifyTopLevel`      → 哪些顶层真实目录属于"旧版本残留"（同版本/链接一律不动 —— 宁可少动）
+//   · `planBackupRetention`   → 保留「回滚点那一条 ∪ 最近 N 条」，其余进删除清单 + 可释放字节
+//
+// 行数预算：独立模块，留在 600 行架构硬顶内。
+
+/**
+ * 顶层条目分类（纯函数）。
+ * `entries` 形如 `[{ name, version, isLink, sizeBytes }]`；`isLink` 为真表示已被 junction/符号链接接管。
+ * **保守取舍**：同版本保留；缺版本（读不到 package.json）保留并单列 —— 判不准就不动。
+ */
+function classifyTopLevel(entries, { runningVersion = null } = {}) {
+  const stale = []
+  const sameVersion = []
+  const missingVersion = []
+  for (const entry of (Array.isArray(entries) ? entries : [])) {
+    if (entry === null || typeof entry !== 'object' || typeof entry.name !== 'string' || entry.name === '') continue
+    if (entry.name.startsWith('.')) continue
+    if (entry.isLink === true) continue
+    const version = entry.version === undefined || entry.version === null ? '' : String(entry.version)
+    if (version === '') { missingVersion.push({ name: entry.name, sizeBytes: entry.sizeBytes ?? null }); continue }
+    if (runningVersion !== null && version === String(runningVersion)) { sameVersion.push({ name: entry.name, version }); continue }
+    stale.push({ name: entry.name, version, sizeBytes: entry.sizeBytes ?? null })
+  }
+  return { stale, sameVersion, missingVersion }
+}
+
+/**
+ * 备份保留策略（纯函数）：保留集合 = 「回滚点引用的路径」∪「按 mtime 最近的 N 条」。
+ * `keep` 非法/缺失时按 1 处理（最小保留）。返回 `{ kept, remove, freedBytes }`，
+ * `kept` 每条带 `reason: 'rollback-point' | 'recent'`（面板要说清为什么留）。
+ */
+function planBackupRetention(snapshots, { referenced = [], keep = 1 } = {}) {
+  const keepCount = Number.isFinite(keep) && keep >= 0 ? Math.floor(keep) : 1
+  const pinned = new Set((Array.isArray(referenced) ? referenced : []).filter((p) => typeof p === 'string' && p !== ''))
+  const list = (Array.isArray(snapshots) ? snapshots : [])
+    .filter((s) => s !== null && typeof s === 'object' && typeof s.path === 'string' && s.path !== '')
+    .sort((a, b) => (Number.isFinite(b.mtimeMs) ? b.mtimeMs : 0) - (Number.isFinite(a.mtimeMs) ? a.mtimeMs : 0))
+  const kept = []
+  const remove = []
+  list.forEach((snap, index) => {
+    if (pinned.has(snap.path)) { kept.push({ ...snap, reason: 'rollback-point' }); return }
+    if (index < keepCount) { kept.push({ ...snap, reason: 'recent' }); return }
+    remove.push(snap)
+  })
+  const freedBytes = remove.reduce((sum, snap) => sum + (Number.isFinite(snap.sizeBytes) ? snap.sizeBytes : 0), 0)
+  return { kept, remove, freedBytes }
+}
+
+export { classifyTopLevel, planBackupRetention }