@noob-stupid/dsh-plugin-console 0.5.97 → 0.5.99

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

@@ -0,0 +1,355 @@
+// L1 · domain —— compat-pending-records.js（「真待适配」判据的**唯一真源** + 记录删除的写盘纪律）
+// 分层分组：L1 · domain（边界由 tests/test-architecture-guard.mjs 断言）
+//
+// ── 真机背景（2026-10-28，用户实测）────────────────────────────────────────────────
+// `~/.dsh/plugin-console/compat-pending.json` 自 2026-10-04 之后就没再被写过，里面 24 条记录：
+//   · 20 条 `status:"adopted"`（已适配解锁 —— 历史，不是待办）；
+//   · 3 条 `status:"pending"` 且 `moduleName: null`（web-ui-describe-image / web-ui-doctor /
+//     web-ui-better-sidebar）—— **对应的补丁行早已不存在**，永远不可能被适配；
+//   · 全部 `check:"unknown"`。
+// 结果门控面板照旧把它们算成"待适配的行"，用户看到"有 N 行待适配"，其实**一行都没有**。
+//
+// 两处根因，本模块各治一处：
+//   ① **计数口径错**：数的是 `pending` 数组长度，而不是"status=pending 且该行仍在补丁里"。
+//      → `isActionablePending()` / `countPendingRecords()` 是唯一判据，路由与面板都只认它。
+//   ② **记录从不清理**：adopted 与"行已消失"的记录永久留在文件里。
+//      → `planForgetRecord()` / `planForgetStale()` + `applyPendingForget()` 提供删除（只删记录）。
+//
+// ── 三条硬边界（不许放宽）──────────────────────────────────────────────────────────
+//   · 「行是否存在」只取**补丁解析的既有产物**（`readPatchState()` 的 disables / forced / inserts，
+//     见 domain/patch.js）—— 这里不另写一套正则，避免两套判据分叉（本仓已为分叉付过代价）。
+//   · 删除**只动 compat-pending.json**：不动插件、不动补丁、不动 bundles 清单。
+//     「清理无效记录」只清 stale（status=pending 且行已不存在）；真 pending 与 adopted **保留**。
+//   · 写盘：备份 → 原子写（临时文件 + rename）→ **读回核实** → 失败回滚；坏文件**拒绝覆盖**
+//     （那是用户的文件，覆盖等于丢数据），读侧则降级为空结构并如实报原因。
+import { copyFileSync, existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
+import { compatPendingFile } from './compat-verdict.js'
+
+/** 适配门记录里"待办"这一侧的状态字（其它一切状态都算历史）。 */
+const PENDING_STATUS = 'pending'
+
+/**
+ * 当前补丁里**真实存在**的行 id 集合（唯一真源：`readPatchState()` 的解析结果）。
+ * 三个来源都是"这一行在补丁里有位置"的等价证据：
+ *   inserts —— 本控制台插入的启用行；disables / forced —— 针对该行的禁用/强制覆盖块。
+ * @param {{disables?: string[], forced?: string[], inserts?: string[]}|null} patchState
+ * @returns {Set<string>}
+ */
+function liveRowIdsFromPatch(patchState) {
+  const out = new Set()
+  if (patchState === null || typeof patchState !== 'object') return out
+  for (const key of ['disables', 'forced', 'inserts']) {
+    const list = Array.isArray(patchState[key]) ? patchState[key] : []
+    for (const id of list) if (typeof id === 'string' && id !== '') out.add(id)
+  }
+  return out
+}
+
+const statusOf = (record) => (typeof record?.status === 'string' && record.status !== '' ? record.status : PENDING_STATUS)
+
+/**
+ * 「真待适配」判据（**纯函数、唯一真源**）：status 仍是 pending，**且**该行此刻还在补丁里。
+ * 行已不存在 ⇒ 这条记录永远等不到"适配"（它的行都不在了），所以它不是待办。
+ */
+function isActionablePending(record, liveRowIds) {
+  if (record === null || typeof record !== 'object') return false
+  if (statusOf(record) !== PENDING_STATUS) return false
+  if (typeof record.rowId !== 'string' || record.rowId === '') return false
+  return liveRowIds instanceof Set && liveRowIds.has(record.rowId)
+}
+
+/**
+ * 「失效记录」判据：记录写着待适配，但它的补丁行已经不在了（用户眼前那条"删不掉的待适配"）。
+ * 注意：adopted 记录**不算** stale —— 那是历史，用户明确要求保留、只在历史区展示。
+ */
+function isStalePending(record, liveRowIds) {
+  if (record === null || typeof record !== 'object') return false
+  if (statusOf(record) !== PENDING_STATUS) return false
+  if (typeof record.rowId !== 'string' || record.rowId === '') return false
+  return !(liveRowIds instanceof Set) || !liveRowIds.has(record.rowId)
+}
+
+/**
+ * 计数（面板/接口只认这三个数）：真待适配 / 已失效 / 历史已适配。
+ * @returns {{ totalCount: number, actionableCount: number, staleCount: number, adoptedCount: number }}
+ */
+function countPendingRecords(records, liveRowIds) {
+  const list = Array.isArray(records) ? records : []
+  let actionableCount = 0
+  let staleCount = 0
+  let adoptedCount = 0
+  for (const rec of list) {
+    if (rec === null || typeof rec !== 'object') continue
+    if (statusOf(rec) !== PENDING_STATUS) { adoptedCount += 1; continue }
+    if (isActionablePending(rec, liveRowIds)) actionableCount += 1
+    else staleCount += 1
+  }
+  return { totalCount: list.length, actionableCount, staleCount, adoptedCount }
+}
+
+/**
+ * 给门控明细行补两个**只增不改**的字段（面板据此如实标注"该行已不存在"并给删除入口）：
+ *   rowMissing —— 这一行的 rowId 已不在当前补丁里（null/空 rowId 也算 missing：无所指）
+ *   actionable —— 与 `isActionablePending` 同一个判据（pending 且行还在）
+ */
+function annotateGateRows(rows, liveRowIds) {
+  const list = Array.isArray(rows) ? rows : []
+  return list.map((row) => {
+    const hasRow = typeof row?.rowId === 'string' && row.rowId !== '' && liveRowIds instanceof Set && liveRowIds.has(row.rowId)
+    return { ...row, rowMissing: !hasRow, actionable: isActionablePending(row, liveRowIds) }
+  })
+}
+
+/**
+ * 读记录文件（**只读**）。坏文件/空文件按"没有内容"处理，但**把原因如实带出来**：
+ * 调用方（写动作）据此拒绝覆盖，界面据此如实显示"读不出来，所以没有可清理的记录"。
+ * @returns {{ file: string, exists: boolean, corrupt: boolean, raw: object|null, records: object[], error: string|null }}
+ */
+function readPendingRecords(file = compatPendingFile()) {
+  const empty = { file, exists: false, corrupt: false, raw: null, records: [], error: null }
+  if (typeof file !== 'string' || file === '') return { ...empty, corrupt: true, error: '拿不到记录文件路径' }
+  if (!existsSync(file)) return empty
+  let text = null
+  try {
+    text = readFileSync(file, 'utf8')
+  } catch (error) {
+    return { ...empty, exists: true, corrupt: true, error: `读取失败：${String(error?.message ?? error)}` }
+  }
+  // 空文件（含只有空白 / BOM 的）按**没有内容**处理：它不是坏文件 ⇒ 读侧降级为空结构，
+  // 写侧照旧"没有可删的记录"（绝不为了删一条记录就把空文件改写成别的形状）。
+  if (text.replace(/^\uFEFF/u, '').trim() === '') return { ...empty, exists: true, empty: true, raw: null, records: [] }
+  let raw = null
+  try {
+    raw = JSON.parse(text)
+  } catch (error) {
+    return { ...empty, exists: true, corrupt: true, error: `不是合法 JSON：${String(error?.message ?? error)}` }
+  }
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    return { ...empty, exists: true, corrupt: true, error: '内容不是 JSON 对象' }
+  }
+  const records = (Array.isArray(raw.pending) ? raw.pending : []).filter((r) => r !== null && typeof r === 'object')
+  return { file, exists: true, corrupt: false, raw, records, error: null }
+}
+
+/** 写动作的公共前置校验：坏文件**拒绝覆盖**（保住用户数据），并给出可读原因。 */
+function refuseIfUnsafe(read) {
+  if (read.exists !== true) return { ok: false, status: 404, error: `${read.file} 不存在（没有可删的记录）` }
+  if (read.corrupt === true) {
+    return { ok: false, status: 409, error: `${read.file} 读不出来（${read.error ?? '格式非法'}）；为保住你的数据，本动作已停止（请先手工修好或删掉它）` }
+  }
+  return null
+}
+
+/**
+ * 规划「删掉某一条记录」（**纯函数，不写盘**）。
+ * 不存在的 rowId ⇒ 404 + 明确原因（绝不静默成功）。
+ */
+function planForgetRecord({ read, rowId } = {}) {
+  const base = { ok: false, status: 400, error: null, file: read?.file ?? null, next: null, changed: false, removedRowIds: [], keptRowIds: [] }
+  if (read === null || typeof read !== 'object') return { ...base, error: '内部错误：没有读到记录文件' }
+  const refused = refuseIfUnsafe(read)
+  if (refused !== null) return { ...base, ...refused }
+  if (typeof rowId !== 'string' || rowId === '') return { ...base, error: '缺少 rowId（要删哪一条？）' }
+  const index = read.records.findIndex((r) => r.rowId === rowId)
+  if (index < 0) return { ...base, status: 404, error: `没有 rowId 为 ${rowId} 的记录（文件未改动）` }
+  const kept = read.records.filter((_, i) => i !== index)
+  return {
+    ok: true,
+    status: 200,
+    error: null,
+    file: read.file,
+    next: { ...read.raw, pending: kept },
+    changed: true,
+    removedRowIds: [rowId],
+    keptRowIds: kept.map((r) => r.rowId).filter((id) => typeof id === 'string'),
+  }
+}
+
+/**
+ * 规划「清掉所有失效记录」（**纯函数，不写盘**）：只删 status=pending 且行已不存在的；
+ * 真 pending 与 adopted 一条都不动。没有可清的 ⇒ `changed:false`（**零写盘**，不是错误）。
+ */
+function planForgetStale({ read, liveRowIds } = {}) {
+  const base = { ok: false, status: 400, error: null, file: read?.file ?? null, next: null, changed: false, removedRowIds: [], keptRowIds: [], staleCount: 0 }
+  if (read === null || typeof read !== 'object') return { ...base, error: '内部错误：没有读到记录文件' }
+  const refused = refuseIfUnsafe(read)
+  if (refused !== null) return { ...base, ...refused }
+  const stale = read.records.filter((r) => isStalePending(r, liveRowIds))
+  if (stale.length === 0) {
+    return { ...base, ok: true, status: 200, changed: false, keptRowIds: read.records.map((r) => r.rowId).filter((id) => typeof id === 'string'), staleCount: 0 }
+  }
+  const staleIds = new Set(stale.map((r) => r.rowId))
+  const kept = read.records.filter((r) => !staleIds.has(r.rowId))
+  return {
+    ok: true,
+    status: 200,
+    error: null,
+    file: read.file,
+    next: { ...read.raw, pending: kept },
+    changed: true,
+    removedRowIds: [...staleIds],
+    keptRowIds: kept.map((r) => r.rowId).filter((id) => typeof id === 'string'),
+    staleCount: stale.length,
+  }
+}
+
+/**
+ * 执行写入：备份 → 原子写（临时文件 + rename）→ **读回核实** → 任何一步不过就回滚并如实报错。
+ * `deps` 全是注入缝（写失败 / 读回不符的单测靠它，生产路径不传 ⇒ 真实 fs）。
+ * @returns 计划的字段 + `{ backup, verified, rolledBack }`
+ */
+function applyPendingForget(plan, deps = {}) {
+  if (plan === null || typeof plan !== 'object' || plan.ok !== true || plan.changed !== true) return plan
+  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 { file, next } = plan
+  const stamp = Date.now()
+  const backup = `${file}.bak-forget-${stamp}`
+  const tmp = `${file}.tmp-forget-${stamp}`
+  const rollback = (extra) => {
+    try { if (io.exists(backup)) io.copy(backup, 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(file)) io.copy(file, backup)
+    io.write(tmp, `${JSON.stringify(next, null, 2)}\n`, 'utf8')
+    io.rename(tmp, file)
+  } catch (error) {
+    return rollback({ ok: false, status: 500, error: `写入 ${file} 失败：${String(error?.message ?? error)}（已回滚，文件保持原样）` })
+  }
+  // 读回核实：删掉的那条必须真的不在、保留的每一条必须还在 —— "写了但没生效"是最坏的一种假绿
+  let back = null
+  try {
+    back = JSON.parse(io.read(file, 'utf8'))
+  } catch (error) {
+    return rollback({ ok: false, status: 500, error: `写入后读回失败：${String(error?.message ?? error)}（已回滚）` })
+  }
+  const rows = (Array.isArray(back?.pending) ? back.pending : []).filter((r) => r !== null && typeof r === 'object')
+  const stillThere = plan.removedRowIds.filter((id) => rows.some((r) => r.rowId === id))
+  const lost = plan.keptRowIds.filter((id) => !rows.some((r) => r.rowId === id))
+  if (stillThere.length > 0 || lost.length > 0) {
+    const why = stillThere.length > 0 ? `要删的记录仍在（${stillThere.join('、')}）` : `保留的记录丢了（${lost.slice(0, 5).join('、')}）`
+    return rollback({ ok: false, status: 500, error: `写入后读回内容与期望不一致（${why}），已回滚` })
+  }
+  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,
+  isActionablePending,
+  isStalePending,
+  countPendingRecords,
+  annotateGateRows,
+  readPendingRecords,
+  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) }] }
   }
 }