@noob-stupid/dsh-plugin-console 0.5.98 → 0.5.100

package/lib/client.js

@@ -1,4 +1,4 @@
-window.__ModuleLoader__.load({
+window.__ModuleLoader__.load({
 	id: "@noob-stupid/dsh-plugin-console",
 	factory: (require) => {
 		var module = { exports: {} };
@@ -405,6 +405,29 @@
 			gateForgetDoneStale: "已清理 {n} 条失效记录（插件与补丁一个字都没动）",
 			gateForgetNone: "没有可删除的记录（文件未改动）",
 			gateForgetFailed: "删除失败：",
+			// ★ 0.5.100 加法（用户 2026-11-02）：「按需检查」—— 预检只在升级前跑，平时门控是空的，
+			//   0 条会被误读成"全部兼容"。这里给一个"现在查一次"的入口 + 空态说明 + 上次检查摘要。
+			gateScanBtn: "检查当前是否适配",
+			gateScanBusy: "正在检查…",
+			gateScanTitle: "对当前补丁里的行跑一次适配判定：只记录结论，不禁用任何行",
+			gateScanNoTargets: "当前没有可检查的行（补丁里没有可判定的插件行），所以不显示检查按钮",
+			gateScanDone: "检查 {n} 行：通过 {p} / 不适配 {f} / 无法判定 {u}",
+			gateScanFailed: "检查失败：",
+			gateNoRecordsHint: "本次没有裁决记录（预检只在升级前运行，可点上面按钮检查）",
+			gateLastScan: "上次检查（{at}）：{n} 行 · 通过 {p} / 不适配 {f} / 无法判定 {u}",
+			// ★ 0.5.101 加法（用户 2026-11-02）：**加载失败的行**（运行期挂载失败）分区 + 两段式停用。
+			//   与"适配裁决"分开：这类失败不经过预扫/隔离链，**不写 compat-pending.json**。
+			gateLoadFailedTitle: "加载失败的行（{n} 行 · 运行期挂载失败）",
+			gateLoadFailedHint: "这些行是**运行期加载失败**（例：某个依赖包解析不到），不是适配裁决，也不会写进适配记录；可在此停用它们。",
+			gateLoadDisable: "停用",
+			gateLoadDisableTitle: "停用这一行（会往补丁里写一条 disabled 块；点一下先确认）",
+			gateLoadArmRow: "将停用 {id}（{name}）。",
+			gateLoadSafety: "这会往 profile 补丁里写一条 disabled 块（可随时在列表里重新启用）；不会卸载包、不会动其它行。",
+			gateLoadConfirm: "确认停用",
+			gateLoadCancel: "取消",
+			gateLoadFailedDone: "已请求停用 {id}（补丁已更新，HMR 应用后列表会随之变化）",
+			gateLoadFailedGone: "该行已不在运行时列表里（可能已被删除），本动作没有发请求",
+			gateLoadFailedFailed: "停用失败：",
 			// ★ 0.5.x 加法（用户 2026-10-18）：「安全启动」在界面上的入口 —— 门控面板里的一个分区。
 			//   用户原话「现在这能力藏得太深，只有命令行能用」；这里只做展示 + 两段式上膛，
 			//   判据与动作白名单全在服务端 POST /plugin-console/safe-boot。
@@ -1198,6 +1221,27 @@
 			gateForgetDoneStale: "Removed {n} invalid record(s) (plugins and patch file untouched)",
 			gateForgetNone: "Nothing to delete (file unchanged)",
 			gateForgetFailed: "Delete failed: ",
+			// ★ 0.5.100 additive (user 2026-11-02): on-demand adaptation check in the gating panel.
+			gateScanBtn: "Check current compatibility",
+			gateScanBusy: "Checking…",
+			gateScanTitle: "Runs the adaptation verdict over the rows in the current patch: records conclusions only, disables nothing",
+			gateScanNoTargets: "No rows to check (the patch has no judgeable plugin rows), so the check button is not shown",
+			gateScanDone: "Checked {n} row(s): pass {p} / incompatible {f} / undecidable {u}",
+			gateScanFailed: "Check failed: ",
+			gateNoRecordsHint: "No verdict records yet (the pre-scan only runs before an upgrade — use the button above to check now)",
+			gateLastScan: "Last check ({at}): {n} row(s) · pass {p} / incompatible {f} / undecidable {u}",
+			// ★ 0.5.101 additive (user 2026-11-02): rows that FAILED TO LOAD at runtime.
+			gateLoadFailedTitle: "Rows that failed to load ({n} · runtime mount failure)",
+			gateLoadFailedHint: "These rows failed to load at runtime (e.g. a dependency cannot be resolved). This is not an adaptation verdict and is never written to the adaptation records; you can disable them here.",
+			gateLoadDisable: "Disable",
+			gateLoadDisableTitle: "Disable this row (writes a disabled block into the patch; click once to confirm)",
+			gateLoadArmRow: "Row {id} ({name}) will be disabled.",
+			gateLoadSafety: "This writes one disabled block into the profile patch (you can re-enable it from the list at any time); it does not uninstall the package and does not touch other rows.",
+			gateLoadConfirm: "Confirm disable",
+			gateLoadCancel: "Cancel",
+			gateLoadFailedDone: "Disable requested for {id} (the patch is updated; the list follows once HMR applies)",
+			gateLoadFailedGone: "This row is no longer in the runtime list (it may have been removed), so no request was sent",
+			gateLoadFailedFailed: "Disable failed: ",
 			gateRowAt: " · {t}",
 			gateRowAdoptable: " · passed the source scan, can be unlocked",
 			safeBootSectionTitle: "Safe boot",
@@ -5854,6 +5898,56 @@ const RESTART_FAILED_NOTE = "重启请求失败";
 			const [gateForgetArmed, setGateForgetArmed] = react.useState(null); // { kind: "row", rowId, moduleName } | { kind: "stale" }
 			const [gateForgetBusy, setGateForgetBusy] = react.useState(false);
 			const [gateForgetNote, setGateForgetNote] = react.useState(null); // { text, level }
+			// ★ 0.5.100 加法：「按需检查」的按钮状态与结果反馈（用户 2026-11-02「平时不预检」）。
+			//   `gateScanTargets` = 当前**可检查**的行数（有 rowId 且不是控制台自己）：为 0 时不摆按钮。
+			const gateScanTargets = gateReady && Array.isArray(state.data.entries)
+				? state.data.entries.filter((e) => typeof e?.rowId === "string" && e.rowId !== "" && e.rowId !== "plugin-console").length
+				: 0;
+			const gateLastScan = gateReady && state.data.compatPending !== null && state.data.compatPending !== undefined
+				? (state.data.compatPending.lastScan ?? null)
+				: null;
+			const [gateScanBusy, setGateScanBusy] = react.useState(false);
+			const [gateScanNote, setGateScanNote] = react.useState(null); // { text, level }
+			/** 一键「检查当前是否适配」：服务端只记录结论、绝不禁用任何行；成功/失败都要有明确反馈。 */
+			const gateScanSend = () => {
+				if (gateScanBusy) return;
+				setGateScanBusy(true);
+				setGateScanNote(null);
+				call("/plugin-console/compat-gate", { action: "scan-current" }).then(
+					(data) => {
+						const n = Number(data?.checked ?? 0);
+						const p = Number(data?.pass ?? 0);
+						const f = Number(data?.fail ?? 0);
+						const u = Number(data?.unknown ?? 0);
+						setGateScanNote({ text: t("gateScanDone").replace("{n}", String(n)).replace("{p}", String(p)).replace("{f}", String(f)).replace("{u}", String(u)), level: null });
+						refresh(); // 结论落盘了 ⇒ 重拉 /state（列表、计数、"上次检查"一起变）
+					},
+					(error) => setGateScanNote({ text: t("gateScanFailed") + friendlyGithubError(error).message, level: "error" }),
+				).finally(() => setGateScanBusy(false));
+			};
+			// ★ 0.5.101 加法（用户 2026-11-02）：**运行期加载失败**的行（`fiberPhase === 'failed'`）。
+			//   真机：`experimental-inspector` 因 `@deepseek-ai/cordis` 解析失败挂载失败，门控完全看不到
+			//   —— 那条失败不经过预扫/隔离链。这里只做**视图**（服务端 gating.loadFailed；**从不**写
+			//   compat-pending.json，那是适配裁决记录）；停用仍是用户的动作（两段式，落到既有 /toggle）。
+			const gateLoadFailed = gateReady && gateRows !== null && Array.isArray(gateRows.loadFailed) ? gateRows.loadFailed : [];
+			const [gateLoadArmed, setGateLoadArmed] = react.useState(null); // { rowId, name }
+			const [gateLoadNote, setGateLoadNote] = react.useState(null); // { text, level }
+			const gateLoadEntry = (rowId) => (gateReady && Array.isArray(state.data.entries)
+				? (state.data.entries.find((e) => e.rowId === rowId) ?? null)
+				: null);
+			/** 两段式第一段：只上膛（零请求）。 */
+			const gateLoadArm = (next) => { setGateLoadNote(null); setGateLoadArmed(next); };
+			/** 确认后才真发：走**既有** /toggle（enabled:false），成功后刷新。 */
+			const gateLoadDisable = (armed) => {
+				const entry = armed === null ? null : gateLoadEntry(armed.rowId);
+				setGateLoadArmed(null);
+				setGateLoadNote(null);
+				if (entry === null) { setGateLoadNote({ text: t("gateLoadFailedFailed") + t("gateLoadFailedGone"), level: "error" }); return; }
+				call("/plugin-console/toggle", { entryId: entry.entryId, enabled: false }).then(
+					() => { setGateLoadNote({ text: t("gateLoadFailedDone").replace("{id}", String(armed.rowId)), level: null }); refresh(); },
+					(error) => setGateLoadNote({ text: t("gateLoadFailedFailed") + friendlyGithubError(error).message, level: "error" }),
+				);
+			};
 			/** 两段式的第一段：只上膛，一个请求都不发（换目标 = 换载荷，旧载荷不会跟着发出去）。 */
 			const gateForgetArm = (next) => { setGateForgetNote(null); setGateForgetArmed(next); };
 			/** 唯一出口：真发删除请求（成功后刷新 /state，列表与计数一起变）。 */
@@ -6808,6 +6902,43 @@ const RESTART_FAILED_NOTE = "重启请求失败";
 								el("p", { className: styles.message }, t("compatGateHint")),
 								el("p", { className: styles.status, "data-pending": gatePendingCount > 0 ? "true" : undefined, "data-gate-pending": String(gatePendingCount), "data-gate-stale": String(gateStaleCount) },
 									gatePendingCount > 0 ? t("gatePendingInfo").replace("{n}", String(gatePendingCount)) : t("gatePendingNone")),
+								// ★ 0.5.100 加法（用户 2026-11-02「我们一般情况下都不预检吧」）：
+								//   预检只在**升级前**跑，所以平时门控是空的 —— 而 0 条会被误读成"全部兼容"。
+								//   这里给两件事：① 一个「现在查一次」的按钮（判据复用服务端框架升级预扫那条链，
+								//   **只记录结论、不禁用任何行**）；② 没有裁决记录时的说明 + 上次检查的摘要。
+								//   零行可查时**不摆按钮**，并说明为什么（不许出现点了必然没反应的按钮）。
+								gateScanTargets === 0
+									? el("p", { className: styles.status, "data-gate-scan-none": "true" }, t("gateScanNoTargets"))
+									: el("div", { style: { flexDirection: "row", gap: 8, display: "flex", alignItems: "center" } },
+										el("button", {
+											type: "button",
+											className: styles.toggle,
+											"aria-label": "gateScanCurrent",
+											disabled: gateScanBusy,
+											title: t("gateScanTitle"),
+											onClick: () => { gateScanSend(); },
+										}, gateScanBusy ? t("gateScanBusy") : t("gateScanBtn"))),
+								gateScanNote === null
+									? null
+									: el("p", {
+										className: styles.message,
+										"data-gate-scan-note": "true",
+										"data-error": gateScanNote.level === "error" ? "true" : undefined,
+										style: gateScanNote.level === "error" ? undefined : { color: "var(--dsw-alias-state-success-primary)" },
+									}, String(gateScanNote.text ?? "—")),
+								gateLastScan === null
+									? null
+									: el("p", { className: styles.status, "data-gate-lastscan": "true" },
+										t("gateLastScan")
+											.replace("{at}", gateTime(gateLastScan.at))
+											.replace("{n}", String(gateLastScan.checked ?? 0))
+											.replace("{p}", String(gateLastScan.pass ?? 0))
+											.replace("{f}", String(gateLastScan.fail ?? 0))
+											.replace("{u}", String(gateLastScan.unknown ?? 0))),
+								// 门控为空时的明确文案：不让 0 条看起来像"全绿"（用户 2026-11-02 点名）
+								gateRows === null || gateRows.pendingCount + gateRows.adoptedCount === 0
+									? el("p", { className: styles.status, "data-gate-empty-hint": "true" }, t("gateNoRecordsHint"))
+									: null,
 																			// 明细清单（2026-09-24 用户要求：面板要能看到是哪些插件，有列表数据）
 							gateRows !== null && gateRows.pendingCount + gateRows.adoptedCount > 0
 								? el("div", { style: { flexDirection: "column", gap: 6, display: "flex" } },
@@ -6890,6 +7021,64 @@ const RESTART_FAILED_NOTE = "重启请求失败";
 												: null)
 										: null)
 								: null,
+							// ★ 0.5.101 加法（用户 2026-11-02）：**加载失败的行**分区。
+							//   与"适配裁决"是两件事：这些行是**运行期挂载失败**（例：某个依赖包解析不到），
+							//   不经过预扫/隔离链，所以也**不会写进 compat-pending.json**；这里给的是视图 +
+							//   「停用」（两段式，落到既有 /toggle，真的写补丁 disabled 块）。
+							//   零失败行时整个分区不出现（不摆空壳）。
+							gateLoadFailed.length === 0
+								? null
+								: el("div", {
+									"data-gate-loadfailed": "true",
+									style: { flexDirection: "column", gap: 6, display: "flex", marginTop: 4, paddingTop: 8, borderTop: "1px solid var(--dsw-alias-border-l2)" },
+								},
+									el("strong", { className: styles.name }, t("gateLoadFailedTitle").replace("{n}", String(gateLoadFailed.length))),
+									el("p", { className: styles.status }, t("gateLoadFailedHint")),
+									gateLoadFailed.map((r) => el("div", {
+										key: "lf-" + String(r.rowId),
+										"data-gate-loadfailed-row": String(r.rowId),
+										style: { flexDirection: "column", gap: 2, display: "flex", padding: "4px 0" },
+									},
+										el("span", { className: styles.name }, "⛔ " + String(r.moduleName ?? r.rowId) + (r.version ? "  v" + r.version : "")),
+										el("span", { className: styles.status, "data-gate-loadfailed-module": "true" },
+											t("gateRowModule") + " " + (typeof r.moduleName === "string" && r.moduleName !== "" ? r.moduleName : "—")
+											+ " · " + String(r.fiberPhase ?? "failed"),
+											el("button", {
+												type: "button",
+												className: styles.toggle,
+												style: { marginLeft: 8, fontSize: 11, padding: "1px 6px" },
+												"aria-label": "gateLoadDisable",
+												"data-gate-load-disable": String(r.rowId),
+												title: t("gateLoadDisableTitle"),
+												onClick: () => gateLoadArm({ rowId: String(r.rowId), name: typeof r.moduleName === "string" ? r.moduleName : null }),
+											}, t("gateLoadDisable"))))),
+									gateLoadArmed === null
+										? null
+										: el("div", { "data-gate-load-armed": "true", style: { flexDirection: "column", gap: 6, display: "flex", borderLeft: "2px solid var(--dsw-alias-state-warning-primary)", paddingLeft: 8 } },
+											el("p", { className: styles.message, "data-warn": "true", "data-gate-load-text": "true" },
+												t("gateLoadArmRow").replace("{id}", String(gateLoadArmed.rowId)).replace("{name}", String(gateLoadArmed.name ?? "—"))),
+											el("p", { className: styles.status }, t("gateLoadSafety")),
+											el("div", { style: { flexDirection: "row", gap: 8, display: "flex" } },
+												el("button", {
+													type: "button",
+													className: styles.toggle,
+													"aria-label": "gateLoadConfirm",
+													onClick: () => { gateLoadDisable(gateLoadArmed); },
+												}, t("gateLoadConfirm")),
+												el("button", {
+													type: "button",
+													className: styles.toggle,
+													"aria-label": "gateLoadCancel",
+													onClick: () => { setGateLoadArmed(null); setGateLoadNote(null); },
+												}, t("gateLoadCancel")))),
+									gateLoadNote === null
+										? null
+										: el("p", {
+											className: styles.message,
+											"data-gate-load-note": "true",
+											"data-error": gateLoadNote.level === "error" ? "true" : undefined,
+											style: gateLoadNote.level === "error" ? undefined : { color: "var(--dsw-alias-state-success-primary)" },
+										}, String(gateLoadNote.text ?? "—"))),
 							// ★ 0.5.98 加法：删除的**两段式**确认区 + 结果反馈（都留在面板上，不弹系统对话框）。
 							//   上膛时把"要删什么、不会动什么"写清楚：只删记录，不动插件、不动补丁文件。
 							gateForgetArmed === null

package/lib/server/domain/compat-pending-records.js

@@ -241,6 +241,104 @@ function applyPendingForget(plan, deps = {}) {
   return { ...plan, backup, verified: true, rolledBack: false }
 }
 
+/**
+ * 规划一次「把扫描结论并进记录」（**纯函数，不写盘**；0.5.100 加法）。
+ *
+ * 语义（只加不删）：
+ *   · 传入的记录按 `rowId` **合并**进 `pending` 数组：已有则覆盖结论字段（并保持**同一条记录**的位置），
+ *     没有则追加；其余记录（含历史 adopted、别人的记录）**一个字都不动**；
+ *   · 只接受 `status`/`check`/`checkNote`/`version`/`moduleName`/`source`/`scanVerdict` 这些结论字段的更新；
+ *   · 额外写一条 `lastScan` 摘要（`{ at, frameworkVersion, checked, pass, fail, unknown, skipped, source }`）——
+ *     它让面板能说"上次检查了几个、结果如何"，而不是让 0 条记录看起来像"全绿"；
+ *   · 没有变化时 `changed:false` ⇒ 调用方**零写盘**（幂等）。
+ */
+function planScanMerge({ read, records, lastScan, frameworkVersion = null } = {}) {
+  const base = { ok: false, status: 400, error: null, file: read?.file ?? null, next: null, changed: false, added: [], updated: [], lastScan: lastScan ?? null }
+  if (read === null || typeof read !== 'object') return { ...base, error: '内部错误：没有读到记录文件' }
+  if (read.exists === true && read.corrupt === true) {
+    return { ...base, status: 409, error: `${read.file} 读不出来（${read.error ?? '格式非法'}）；为保住你的数据，本次扫描结果**没有写盘**（请先手工修好或删掉它）` }
+  }
+  const incoming = (Array.isArray(records) ? records : []).filter((r) => r !== null && typeof r === 'object' && typeof r.rowId === 'string' && r.rowId !== '')
+  const raw = read.raw === null || typeof read.raw !== 'object' ? { pending: [] } : read.raw
+  const current = (Array.isArray(raw.pending) ? raw.pending : []).filter((r) => r !== null && typeof r === 'object')
+  const next = { ...raw, pending: [...current] }
+  const added = []
+  const updated = []
+  // 「结论」= 只有这些字段变了才算真的变了；`scannedAt` 之类的时间戳**不算**变化 ——
+  // 否则每点一次「检查」都会重写一遍文件（也就每次留一份备份），幂等就名存实亡了。
+  const conclusionKey = (r) => JSON.stringify([
+    r?.status ?? null, r?.check ?? null, r?.checkNote ?? null, r?.version ?? null,
+    r?.moduleName ?? null, r?.source ?? null, r?.frameworkVersion ?? null,
+    r?.scanVerdict?.version ?? null, r?.scanVerdict?.decision ?? null,
+  ])
+  for (const rec of incoming) {
+    const at = next.pending.findIndex((p) => p?.rowId === rec.rowId)
+    if (at < 0) {
+      next.pending.push({ ...rec })
+      added.push(rec.rowId)
+      continue
+    }
+    const before = next.pending[at]
+    if (conclusionKey(before) === conclusionKey(rec)) continue // 结论没变 ⇒ 这条记录一个字都不动
+    next.pending[at] = { ...before, ...rec }
+    updated.push(rec.rowId)
+  }
+  if (typeof frameworkVersion === 'string' && frameworkVersion !== '') next.frameworkVersion = frameworkVersion
+  // lastScan 摘要：只在**摘要本身**变了（或还没有摘要）时才更新 —— 时间戳不算变化
+  if (lastScan !== null && lastScan !== undefined) {
+    const summaryKey = (s) => (s === null || s === undefined ? '' : JSON.stringify([s.checked, s.pass, s.fail, s.unknown, s.skipped, s.frameworkVersion, s.source]))
+    if (summaryKey(raw.lastScan) !== summaryKey(lastScan)) next.lastScan = lastScan
+  }
+  // 文件还不存在、也没有任何结论要写 ⇒ **连文件都不建**（零行可查时不留空壳文件）
+  if (read.exists !== true && added.length === 0 && updated.length === 0) {
+    return { ...base, ok: true, status: 200, next: raw, changed: false, added, updated }
+  }
+  const changed = JSON.stringify(next) !== JSON.stringify(raw)
+  return { ...base, ok: true, status: 200, next: changed ? next : raw, changed, added, updated }
+}
+
+/**
+ * 执行一次「整份记录的安全写入」：备份 → 原子写（临时文件 + rename）→ **读回核实** → 失败回滚。
+ * `verify(back)` 返回 `null` 表示核实通过，返回字符串表示为什么不通过（写进错误信息）。
+ * 与 `applyPendingForget` 同一套纪律，只是判据由调用方给（扫描合并与删除要核实的东西不一样）。
+ */
+function applyPendingWrite({ file, next, verify = null, tag = 'scan', deps = {} } = {}) {
+  const plan = { ok: true, status: 200, error: null, file: typeof file === 'string' ? file : null, changed: true, backup: null, verified: false, rolledBack: false }
+  if (plan.file === null || next === null || typeof next !== 'object') {
+    return { ...plan, ok: false, status: 400, error: '内部错误：缺少目标文件或内容' }
+  }
+  const io = {
+    copy: deps.copyFileSync ?? copyFileSync,
+    write: deps.writeFileSync ?? writeFileSync,
+    rename: deps.renameSync ?? renameSync,
+    remove: deps.unlinkSync ?? unlinkSync,
+    exists: deps.existsSync ?? existsSync,
+    read: deps.readFileSync ?? readFileSync,
+  }
+  const stamp = Date.now()
+  const backup = `${plan.file}.bak-${tag}-${stamp}`
+  const tmp = `${plan.file}.tmp-${tag}-${stamp}`
+  const rollback = (extra) => {
+    try { if (io.exists(backup)) io.copy(backup, plan.file) } catch {}
+    try { if (io.exists(tmp)) io.remove(tmp) } catch {}
+    return { ...plan, ...extra, backup, verified: false, rolledBack: io.exists(backup) }
+  }
+  try {
+    if (io.exists(plan.file)) io.copy(plan.file, backup)
+    io.write(tmp, `${JSON.stringify(next, null, 2)}\n`, 'utf8')
+    io.rename(tmp, plan.file)
+  } catch (error) {
+    return rollback({ ok: false, status: 500, error: `写入 ${plan.file} 失败：${String(error?.message ?? error)}（已回滚，文件保持原样）` })
+  }
+  let back = null
+  try { back = JSON.parse(io.read(plan.file, 'utf8')) } catch (error) {
+    return rollback({ ok: false, status: 500, error: `写入后读回失败：${String(error?.message ?? error)}（已回滚）` })
+  }
+  const why = typeof verify === 'function' ? verify(back) : null
+  if (why !== null && why !== undefined) return rollback({ ok: false, status: 500, error: `写入后读回内容与期望不一致（${String(why)}），已回滚` })
+  return { ...plan, backup, verified: true, rolledBack: false }
+}
+
 export {
   PENDING_STATUS,
   liveRowIdsFromPatch,
@@ -252,4 +350,6 @@ export {
   planForgetRecord,
   planForgetStale,
   applyPendingForget,
+  planScanMerge,
+  applyPendingWrite,
 }

package/lib/server/domain/compat-scan.js

@@ -0,0 +1,106 @@
+// L1 · domain —— compat-scan.js（门控的「按需检查」：对当前补丁里的行跑一次适配判定；0.5.100 加法）
+//
+// ── 为什么需要（用户 2026-11-02 原话：「我们一般情况下都不预检吧」）──────────────────────────
+// compat-pending 只在**框架升级前预扫**与**启动失败隔离**时写入。平时门控里一条记录都没有，
+// 而"0 条"会被误读成"全部兼容" —— 这不是事实，只是**没人裁决过**。
+// 这个模块给门控一个「现在查一下」的入口：对当前补丁里的行逐行跑判定，把结论如实记下来。
+//
+// ── 三条硬约束（一条都不许放宽）──────────────────────────────────────────────────────
+//   ① **判据只有一份**：复用 `checkPluginFrameworkCompat`（框架升级预扫那条唯一链路里的判定函数，
+//      含"源码里是否还引用已删除的 dsh-settings API"这条硬判据）。这里不新增任何兼容判据。
+//   ② **只记录结论，绝不禁用任何行**：禁用是用户的动作（`/toggle`）。本模块不 import
+//      `disableEntry`、不碰补丁文件 —— 扫描前后补丁必须逐字节不变。
+//   ③ **只把判为不适配（fail）的行写进记录**：pass / unknown 只进统计。
+//      为什么不能全写：`status:'pending'` 的记录会让 `/toggle` 对该行走"软禁"确认流程（409 +
+//      风险确认），把通过的行也写进去等于凭空给用户加一道墙 —— 那是行为变更，不是记录。
+//
+// 读/写 compat-pending.json 的纪律在 domain/compat-pending-records.js（备份 → 原子写 → 读回核实 → 回滚）。
+import { readFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+import { resolvePackageJson } from '../infra/paths.js'
+import { SCANNER_VERSION } from './compat-verdict.js'
+import { checkPluginFrameworkCompat, isFrameworkOwnedPackage } from './compat.js'
+
+/** 记录里标注的来源（面板/日志靠它区分"这次是谁裁决的"）。 */
+const SCAN_SOURCE = 'manual-scan'
+/** 控制台自己永不参与扫描（它要是被判 fail，用户连面板都打不开）。 */
+const SELF_ROW_ID = 'plugin-console'
+
+/**
+ * 对**当前 loader 行**逐行跑一次适配判定（纯读：不写盘、不禁用、不改补丁）。
+ *
+ * @param {object} p
+ * @param {Array<object>} p.entries  loader 条目（`listEntries()` 的结果）
+ * @param {string} p.profileDir      profile 目录（解析已装包用）
+ * @param {string|null} p.frameworkVersion 当前框架版本（拿不到 => 全部 unknown，如实标注）
+ * @param {object} [p.deps]          注入缝：`resolvePkg` / `readPkg`
+ * @returns {{ ok: boolean, results: Array<object>, checked: number, pass: number, fail: number, unknown: number,
+ *             skipped: Array<{rowId: string|null, reason: string}>, frameworkVersion: string|null, error: string|null }}
+ */
+function planCurrentScan({ entries, profileDir, frameworkVersion = null, deps = {} } = {}) {
+  const resolvePkg = deps.resolvePkg ?? resolvePackageJson
+  const readPkg = deps.readPkg ?? ((p) => JSON.parse(readFileSync(p, 'utf8')))
+  const results = []
+  const skipped = []
+  const fwVer = typeof frameworkVersion === 'string' && frameworkVersion !== '' ? frameworkVersion : null
+  for (const entry of Array.isArray(entries) ? entries : []) {
+    const rowId = typeof entry?.rowId === 'string' ? entry.rowId : ''
+    if (rowId === '') { skipped.push({ rowId: null, reason: 'no-row-id' }); continue }
+    if (rowId === SELF_ROW_ID) { skipped.push({ rowId, reason: 'console-self' }); continue }
+    const moduleName = typeof entry?.moduleName === 'string' ? entry.moduleName : ''
+    let pkgPath = null
+    try { pkgPath = moduleName === '' ? null : resolvePkg(moduleName, profileDir) } catch { pkgPath = null }
+    if (pkgPath === null) { skipped.push({ rowId, reason: 'package-unreadable', moduleName }); continue }
+    let pkg = null
+    try { pkg = readPkg(pkgPath) } catch { pkg = null }
+    if (pkg === null || typeof pkg !== 'object') { skipped.push({ rowId, reason: 'package-unreadable', moduleName }); continue }
+    const pkgDir = dirname(pkgPath)
+    let check = null
+    if (fwVer === null) check = { decision: 'unknown', reason: '拿不到当前框架版本（无法判定，不是"兼容"）' }
+    else {
+      try { check = checkPluginFrameworkCompat(pkg, fwVer, pkgDir) } catch (error) { check = { decision: 'unknown', reason: '判定出错：' + String(error?.message ?? error) } }
+    }
+    const decision = check?.decision === 'pass' || check?.decision === 'fail' ? check.decision : 'unknown'
+    results.push({
+      rowId,
+      moduleName: moduleName === '' ? null : moduleName,
+      version: typeof pkg.version === 'string' ? pkg.version : null,
+      decision,
+      reason: check?.reason ?? null,
+      frameworkOwned: isFrameworkOwnedPackage(pkgDir, profileDir),
+      enabled: entry?.enabled === true,
+    })
+  }
+  const count = (d) => results.filter((r) => r.decision === d).length
+  return {
+    ok: true,
+    results,
+    checked: results.length,
+    pass: count('pass'),
+    fail: count('fail'),
+    unknown: count('unknown'),
+    skipped,
+    frameworkVersion: fwVer,
+    error: fwVer === null ? '拿不到当前框架版本：本次所有行都只能判成"无法判定"' : null,
+  }
+}
+
+/** 要写进 compat-pending 的记录（**只有 fail**；pass/unknown 只进统计，见模块头注释 ③）。 */
+function recordsFromScan(scan, { at = Date.now() } = {}) {
+  const list = Array.isArray(scan?.results) ? scan.results : []
+  return list.filter((r) => r.decision === 'fail').map((r) => ({
+    rowId: r.rowId,
+    moduleName: r.moduleName,
+    version: r.version,
+    status: 'pending',
+    check: 'fail',
+    checkNote: r.reason,
+    source: SCAN_SOURCE,
+    scannedAt: at,
+    frameworkVersion: scan?.frameworkVersion ?? null,
+    // 判据戳：这次用的就是**当前**判据（SCANNER_VERSION），所以"读取代发"不会把它当过期结论重算
+    scanVerdict: { version: SCANNER_VERSION, decision: 'fail', reason: r.reason, at, previous: null, rescinded: false, evidence: null },
+  }))
+}
+
+export { SCAN_SOURCE, SELF_ROW_ID, planCurrentScan, recordsFromScan }

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

@@ -35,6 +35,8 @@ import { basename, dirname, join, resolve, sep } from 'node:path'
 import { removeDirVerifiedAsync } from '../infra/fsx.js'
 import { dshHome, resolvePackageJson } from '../infra/paths.js'
 import { FRAMEWORK_BOOT_PACKAGES, classifyTopLevel, planBackupRetention, relinkTargetCandidates } from './framework-residuals.js'
+// 0.5.99 改错：改名残留能不能恢复的**判据**（可用 = 目录里有 package.json；候选包名必须与真名一致）
+import { emptyShellName, isUsablePackageDir, planStaleRestore } from './framework-stale-restore.js'
 
 /** 目录体积（失败返回 0；只用于报告「能释放多少」）。 */
 function dirSizeBytes(dir) {
@@ -424,54 +426,87 @@ function readRollbackReferenced({ home = undefined, deps = {} } = {}) {
   } catch { return [] }
 }
 /**
- * 升级失败后的补偿：把 `<name>.stale-<ver>-<ts>` **改回真名** —— 但只在真名缺失时。
+ * 升级失败后的补偿：把 `<name>.stale-<ver>-<ts>` **改回真名**。
  *
  * 背景（2026-10-28 真机）：升级在「拉起」阶段失败，向上层报「自动回滚未生效」，而清扫步
  * 已经把 10 个框架包改名成 `.stale-*`、真名处什么都没有。结果框架起不来：
  *   `Cannot find package '@deepseek-ai/cordis' imported from @deepseek-ai/dsh-app-boot`
  * 那一刻用户只能手改目录名 —— 这个函数就是那条手改的自动化版本。
  *
- * 纪律：
+ * ★ 0.5.99 改错（真机 2026-11-02，用户实测）：旧判据是「真名**缺失**才恢复；真名存在就跳过」，
+ *   而现场恰恰是「真名存在但是**空壳**（没有 package.json），内容在 `.stale-*` 里」⇒ 被跳过 ⇒
+ *   框架一直解析不到包（`ERR_MODULE_NOT_FOUND`），用户只能手工把 178 个空壳恢复回来。
+ *   现在判据收敛到 domain/framework-stale-restore.js：**可用 = 目录里有 package.json**，
+ *   空壳在判据里与"缺失"同等对待；候选还必须 `package.json.name === <scope>/<real>`（防张冠李戴）。
+ *   空壳**挪成 `<real>.empty-<ts>`**（挪开不删，可回溯），恢复后**读回核实**，不成就回滚并如实报。
+ *
+ * 纪律（一条都没放宽）：
  *   · **绝不删除**任何东西（只 rename）；
- *   · **真名已存在就跳过**（宁可不动，也不覆盖可能更新的目录）；
- *   · 幂等：重复调用第二次什么都不做；
- *   · 只看 `@deepseek-ai` 这一层（顶层 scope），不递归、不碰 `.pnpm` 内部。
+ *   · 真名**可用**就跳过（宁可不动，也不覆盖可能更新的目录）—— 健康树上零动作（幂等）；
+ *   · 只看 `@deepseek-ai` 这一层（顶层 scope），不递归、不碰 `.pnpm` 内部；
+ *   · 三类结果分开回报：`restored` / `noCandidate`（真缺内容，无可用候选）/ `failed`（名字不符、改名失败、读回不符）。
  */
-function restoreStaleBackups({ scopeDir, deps = {} } = {}) {
+function restoreStaleBackups({ scopeDir, stamp = null, deps = {} } = {}) {
   const exists = deps.exists ?? existsSync
-  const readdir = deps.readdir ?? ((dir) => readdirSync(dir, { withFileTypes: true }))
   const rename = deps.rename ?? renameSync
   const restored = []
   const skipped = []
+  const noCandidate = []
+  const emptied = []
   const failed = []
-  if (typeof scopeDir !== 'string' || scopeDir === '') return { ok: false, restored, skipped, failed, problem: '没有给 scopeDir' }
-  let entries = []
-  try { entries = readdir(scopeDir) } catch (error) {
-    const missing = error?.code === 'ENOENT'
-    return { ok: missing, restored, skipped, failed, problem: missing ? null : '列不出目录：' + errText(error) }
+  const io = { lstat: deps.lstat, readText: deps.readText, readdir: deps.readdir }
+  const plan = planStaleRestore({ scopeDir, deps: io })
+  if (plan.problem !== null) {
+    const missing = typeof scopeDir === 'string' && scopeDir !== '' && !exists(scopeDir)
+    return { ok: missing, restored, skipped, noCandidate, emptied, failed, problem: missing ? null : plan.problem }
   }
-  for (const entry of entries) {
-    const name = typeof entry === 'string' ? entry : entry?.name
-    const isDir = typeof entry === 'string' ? true : entry?.isDirectory?.() === true
-    if (typeof name !== 'string' || !isDir || !name.includes('.stale-')) continue
-    const real = name.replace(/\.stale-.*$/u, '')
-    if (real === '' || real === name) continue
-    const target = join(scopeDir, real)
-    const source = join(scopeDir, name)
-    let targetExists = false
-    try { targetExists = exists(target) } catch { targetExists = false }
-    if (targetExists) {
-      skipped.push({ name, real, reason: 'real-name-exists' })
-      continue
+  const ts = stamp === null ? String(Date.now()) : String(stamp)
+  for (const item of plan.items) {
+    const target = join(scopeDir, item.real)
+    if (item.action === 'skip') { skipped.push({ name: item.candidates[0], real: item.real, reason: 'real-name-exists' }); continue }
+    if (item.action === 'noCandidate') { noCandidate.push({ real: item.real, candidates: item.candidates, reason: item.reason, detail: item.detail, unusable: item.unusable ?? [] }); continue }
+    if (item.action === 'failed') { failed.push({ name: item.candidates[0] ?? item.real, real: item.real, reason: item.reason, error: item.detail }); continue }
+    // ① 空壳（存在但不可用）先挪开 —— **改个名，不删**；挪不动（或改名没生效）就整条不动
+    const source = join(scopeDir, item.staleName)
+    let emptyFull = null
+    if (item.realOccupied && item.realUsable !== true) {
+      const aside = join(scopeDir, emptyShellName(item.real, ts))
+      try {
+        rename(target, aside)
+      } catch (error) {
+        failed.push({ name: item.staleName, real: item.real, reason: 'empty-shell-move-failed', error: `真名是空壳但挪不开（${errText(error)}）—— 本次不动它` })
+        continue
+      }
+      // 挪开这个动作也要核实：注入桩/文件系统异常下"调用成功但没生效"不能当成功（否则报告会编造 emptied）
+      if (exists(target) || !exists(aside)) {
+        failed.push({ name: item.staleName, real: item.real, reason: 'empty-shell-move-failed', error: '把空壳挪成 .empty-* 没有生效（真名处仍有东西）—— 本次不动它' })
+        continue
+      }
+      emptyFull = aside
     }
+    // ② 候选 → 真名
     try {
       rename(source, target)
-      restored.push({ from: name, to: real })
     } catch (error) {
-      failed.push({ name, real, error: errText(error) })
+      // 挪开的空壳放回去（尽力而为；失败也要写在 failed 里，绝不静默）
+      let back = true
+      if (emptyFull !== null) { try { rename(emptyFull, target) } catch { back = false } }
+      failed.push({ name: item.staleName, real: item.real, reason: 'rename-failed', error: `改回真名失败：${errText(error)}${emptyFull === null ? '' : (back ? '（空壳已放回原处）' : '（**空壳没能放回原处**，现场可能不一致）')}` })
+      continue
+    }
+    // ③ 读回核实：真名目录里必须真的有 package.json（"改了名"不等于"能解析"）
+    if (isUsablePackageDir(target, io)) {
+      if (emptyFull !== null) emptied.push({ from: item.real, to: basename(emptyFull) })
+      restored.push({ from: item.staleName, to: item.real, emptied: emptyFull === null ? null : basename(emptyFull) })
+      continue
     }
+    // ④ 核实不过：把候选改回去、空壳放回原处，如实报失败（绝不谎报已恢复）
+    let rolledBack = true
+    try { if (!exists(source)) rename(target, source) } catch { rolledBack = false }
+    if (emptyFull !== null) { try { rename(emptyFull, target) } catch { rolledBack = false } }
+    failed.push({ name: item.staleName, real: item.real, reason: 'verify-failed', error: `改名后读回核实不通过（${item.real} 里仍读不到 package.json）${rolledBack ? '；已回滚到操作前' : '；**回滚未完成**，现场可能不一致'}` })
   }
-  return { ok: failed.length === 0, restored, skipped, failed, problem: null }
+  return { ok: failed.length === 0, restored, skipped, noCandidate, emptied, failed, problem: null }
 }
 
 export { cleanFrameworkBackups, cleanFrameworkTopLevel, dirSizeBytes, isLinkEntry, readRollbackReferenced, removeLinkSafe, reportFrameworkEntities, resolveFrameworkLayout, restoreStaleBackups, verifyFrameworkTreeResolvable }

package/lib/server/domain/framework-stale-repair.js

@@ -4,27 +4,42 @@
 // 真名处什么都没有 ⇒ 框架起不来：`Cannot find package '@deepseek-ai/cordis'`。
 // 当时只能手工改目录名；这里把那件事自动化，并**只返回人类可读的步骤**，
 // 让调用方（routes/framework-upgrade.js）保持精简（那个文件有 700 行硬顶）。
+//
+// ★ 0.5.99 改错（真机 2026-11-02）：「真名存在但只是空壳（没有 package.json）」以前被当成
+//   "已存在 ⇒ 跳过"，于是坏状态一直留着。判据已收敛到 domain/framework-stale-restore.js
+//   （可用 = 目录里有 package.json；候选包名必须与真名一致）。本文件把三类结果**都**翻成
+//   升级日志里的可读步骤：restored / noCandidate（真缺内容，无可用候选）/ failed。
 import { join } from 'node:path'
 import { restoreStaleBackups } from './framework-cleanup.js'
 
+/** 一列名字最多列几个（升级日志是单行步骤，别把几百个包名全塞进去）。 */
+const LIST_LIMIT = 8
+const brief = (names) => (names.length <= LIST_LIMIT ? names.join('、') : `${names.slice(0, LIST_LIMIT).join('、')} 等 ${names.length} 个`)
+
 /**
- * @returns {{ steps: string[], restored: Array<{from: string, to: string}>, failed: Array<object> }}
+ * @returns {{ steps: string[], restored: Array<object>, emptied: Array<object>, noCandidate: Array<object>, failed: Array<object> }}
  */
-function repairStaleRenameResidue({ fwRoot } = {}) {
+function repairStaleRenameResidue({ fwRoot, deps = {} } = {}) {
   const steps = []
-  if (typeof fwRoot !== 'string' || fwRoot === '') return { steps, restored: [], failed: [] }
+  const empty = { steps, restored: [], emptied: [], noCandidate: [], failed: [] }
+  if (typeof fwRoot !== 'string' || fwRoot === '') return empty
   try {
-    const repair = restoreStaleBackups({ scopeDir: join(fwRoot, '@deepseek-ai') })
+    const repair = restoreStaleBackups({ scopeDir: join(fwRoot, '@deepseek-ai'), deps })
     if (repair.restored.length > 0) {
-      steps.push(`修复上次失败留下的改名残留：${repair.restored.length} 个包已改回真名（${repair.restored.map((r) => r.to).join('、')}）`)
+      steps.push(`修复上次失败留下的改名残留：${repair.restored.length} 个包已改回真名（${brief(repair.restored.map((r) => r.to))}）`
+        + (Array.isArray(repair.emptied) && repair.emptied.length > 0 ? `；${repair.emptied.length} 个空壳已挪成 .empty-*（未删除）` : ''))
+    }
+    // ★ 0.5.99：真缺内容（真名不可用且没有可用候选）必须**说出来** —— 否则"框架解析不到包"在日志里无声无息
+    if (Array.isArray(repair.noCandidate) && repair.noCandidate.length > 0) {
+      steps.push(`有 ${repair.noCandidate.length} 个框架包真名不可用、且没有可用的 .stale-* 候选（真缺内容，需要重装/重新安装该版本）：${brief(repair.noCandidate.map((n) => n.real))}`)
     }
     if (repair.failed.length > 0) {
-      steps.push(`改名残留修复未全部成功：${repair.failed.map((f) => f.real).join('、')}（不阻塞升级）`)
+      steps.push(`改名残留修复未全部成功：${brief(repair.failed.map((f) => `${f.real}${f.reason ? `(${f.reason})` : ''}`))}（不阻塞升级）`)
     }
-    return { steps, restored: repair.restored, failed: repair.failed }
+    return { steps, restored: repair.restored, emptied: repair.emptied ?? [], noCandidate: repair.noCandidate ?? [], failed: repair.failed }
   } catch (error) {
     steps.push(`改名残留修复失败（不阻塞升级）：${error instanceof Error ? error.message : String(error)}`)
-    return { steps, restored: [], failed: [{ error: String(error) }] }
+    return { ...empty, steps, failed: [{ error: String(error) }] }
   }
 }