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

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

@@ -0,0 +1,215 @@
+// L1 · domain —— framework-stale-restore.js（「改名残留」能不能恢复的**判据**；0.5.99 改错）
+//
+// ── 真机现场（2026-11-02，用户实测）────────────────────────────────────────────────
+// 框架包里出现大量「**真名目录存在，但是空壳**（没有 package.json），真正内容被改名成了
+// `<name>.stale-<ver>-<ts>`」：
+//     真名 cordis\                        → 空（无 package.json）
+//     cordis.stale-4.0.4-1793185607671\   → 有内容（package.json + lib）
+//   该目录下总计 564 项，其中 276 个是 .stale-*。后果：`@deepseek-ai/cordis` 解析失败
+//   （`ERR_MODULE_NOT_FOUND`），插件的 `import` 直接起不来；把 178 个空壳从 .stale-* 恢复后成功。
+//
+// ── 旧判据的缺陷（本次修的正是它）──────────────────────────────────────────────────
+// 旧实现是「真名**缺失**（exists=false）才恢复；真名已存在就跳过」。真机现场恰恰是
+// 「真名存在但是空壳」⇒ 被跳过 ⇒ 坏状态一直留着，框架一直起不来。
+//
+// ── 新判据（三条，全部可离线断言）──────────────────────────────────────────────────
+//   ① **可用**的定义是「这个目录里有 package.json」；目录存在但没有 package.json = **空壳 = 不可用**，
+//      在判据里与"缺失"同等对待（都算"真名此刻不可用"）。
+//   ② 恢复前必须校验候选的 `package.json.name` 与真名一致（`<scope>/<real>`）——
+//      不一致一律不动，记 `failed`（防张冠李戴：把别的包改成这个名字）。
+//   ③ 三类结果分开报告：`restore`（可恢复）/ `noCandidate`（真缺内容且没有可用的 .stale-*）/
+//      `failed`（候选名字不符、候选本身不可用等）—— 调用方要能原样写进升级日志。
+//
+// 本模块只做**判据与计划**（读目录 + 读 package.json，纯读、零写盘）；改名/读回核实/回滚在
+// domain/framework-cleanup.js#restoreStaleBackups（动作层），两处调用方共用同一条路。
+import { readdirSync, readFileSync, lstatSync } from 'node:fs'
+import { basename, join } from 'node:path'
+
+/** 空壳挪开后用的后缀（**挪开不删**，保留可回溯）。 */
+const EMPTY_SUFFIX = '.empty-'
+/** 改名残留的后缀（`<real>.stale-<ver>-<ts>`）。 */
+const STALE_MARK = '.stale-'
+
+function errText(error) {
+  return String(error?.message ?? error)
+}
+
+/** 从目录名拆出真名（`cordis.stale-4.0.4-123` → `cordis`）；不是残留就返回 null。 */
+function staleRealNameOf(name) {
+  if (typeof name !== 'string') return null
+  const at = name.indexOf(STALE_MARK)
+  if (at <= 0) return null
+  return name.slice(0, at)
+}
+
+/** 真名对应的**包名**（scope 目录下是 `@scope/real`；不是 scope 目录就用真名本身）。 */
+function expectedPackageName(scopeDir, real) {
+  const scope = basename(String(scopeDir ?? ''))
+  return scope.startsWith('@') ? `${scope}/${real}` : real
+}
+
+/** 空壳挪开后的名字：`<real>.empty-<stamp>`。 */
+function emptyShellName(real, stamp) {
+  return `${real}${EMPTY_SUFFIX}${stamp}`
+}
+
+/** 读 `<dir>/package.json`：`{ ok, name, version, error }`（读不到/解析不了都如实带原因）。 */
+function packageJsonOf(dir, { readText = (p) => readFileSync(p, 'utf8') } = {}) {
+  try {
+    const raw = JSON.parse(readText(join(dir, 'package.json')))
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return { ok: false, name: null, version: null, error: 'package.json 不是对象' }
+    return { ok: true, name: typeof raw.name === 'string' ? raw.name : null, version: typeof raw.version === 'string' ? raw.version : null, error: null }
+  } catch (error) {
+    return { ok: false, name: null, version: null, error: errText(error) }
+  }
+}
+
+/** 名字里那个"被占用"的东西（空壳 / 链接 / 文件 / 真实目录）：lstat 能立住就算被占着。 */
+function isOccupied(dir, { lstat = lstatSync } = {}) {
+  try { lstat(dir); return true } catch { return false }
+}
+
+/**
+ * **可用**的判据（用户 2026-11-02 定案）：目录里有**能读出来的 package.json**。
+ * 注意它不看包名 —— 「是不是这个包」由 `packageJsonOf().name` 与真名比对，两件事分开判。
+ */
+function isUsablePackageDir(dir, deps = {}) {
+  const lstat = deps.lstat ?? lstatSync
+  let stat = null
+  try { stat = lstat(dir) } catch { return false }
+  try { if (stat?.isDirectory?.() === false && stat?.isSymbolicLink?.() !== true) return false } catch {}
+  return packageJsonOf(dir, deps).ok === true
+}
+
+/** 候选排序用的时间戳（`<real>.stale-<ver>-<ts>` 里尾巴那串数字；没有就是 0）。 */
+function candidateStamp(name) {
+  const m = String(name ?? '').match(/-(\d{6,})$/u)
+  return m === null ? 0 : Number(m[1])
+}
+
+/**
+ * 挑要恢复的那份候选：包名必须与真名一致（防张冠李戴），多份时取**时间戳最新**的那份。
+ * 返回 `{ picked, mismatch, unusable }` —— `mismatch` 是"有 package.json 但名字不对"的候选，
+ * 它们不是可以恢复的对象，但**必须**在报告里点名（否则用户不知道为什么没恢复）。
+ */
+function pickRestoreCandidate({ scopeDir, real, candidates, deps = {} } = {}) {
+  const expected = expectedPackageName(scopeDir, real)
+  const usable = []
+  const mismatch = []
+  const unusable = []
+  for (const name of Array.isArray(candidates) ? candidates : []) {
+    const info = packageJsonOf(join(scopeDir, name), deps)
+    if (info.ok !== true) { unusable.push({ name, error: info.error }); continue }
+    if (info.name !== expected) { mismatch.push({ name, nameInPkg: info.name, expected }); continue }
+    usable.push({ name, version: info.version, stamp: candidateStamp(name) })
+  }
+  usable.sort((a, b) => (b.stamp - a.stamp) || (a.name < b.name ? 1 : a.name > b.name ? -1 : 0))
+  return { picked: usable.length > 0 ? usable[0] : null, usableCount: usable.length, mismatch, unusable }
+}
+
+/**
+ * 计划一次「改名残留修复」（**纯读，零写盘**）。返回每个真名一项：
+ *   `{ real, action: 'restore'|'skip'|'noCandidate'|'failed', staleName, reason, detail,
+ *      realOccupied, realUsable, candidates, mismatch, unusable }`
+ *
+ * 分类规则（顺序即优先级）：
+ *   ① 真名**可用** ⇒ `skip`（reason `real-name-exists`）—— 健康树上一个字节都不动（幂等）；
+ *   ② 真名不可用（缺失 **或空壳**）+ 有可用候选 ⇒ `restore`；
+ *   ③ 真名不可用 + 候选里**有名字不符的** ⇒ `failed`（reason `name-mismatch`，一个都不动）；
+ *   ④ 真名不可用 + 候选都不可用（没 package.json）或压根没有候选 ⇒ `noCandidate`。
+ */
+function planStaleRestore({ scopeDir, deps = {} } = {}) {
+  const empty = { ok: false, items: [], problem: null }
+  if (typeof scopeDir !== 'string' || scopeDir === '') return { ...empty, problem: '没有给 scopeDir' }
+  let entries = []
+  try { entries = deps.readdir ? deps.readdir(scopeDir) : readdirSync(scopeDir, { withFileTypes: true }) } catch (error) {
+    const missing = error?.code === 'ENOENT'
+    return { ...empty, ok: missing, problem: missing ? null : '列不出目录：' + errText(error) }
+  }
+  const byReal = new Map()
+  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) continue
+    const real = staleRealNameOf(name)
+    if (real === null || real === '') continue
+    if (!byReal.has(real)) byReal.set(real, [])
+    byReal.get(real).push(name)
+  }
+  // 真名一侧也要扫：**空壳本身没有 .stale-* 兄弟**时（真缺内容）同样要报 `noCandidate`，
+  // 否则升级日志里那批"真名在、内容没了"的行一个字都不会出现（真机就是这样被漏掉的）。
+  const realNames = new Set()
+  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) continue
+    if (name.includes(STALE_MARK) || name.includes(EMPTY_SUFFIX)) continue // 残留/挪开的空壳不是真名
+    realNames.add(name)
+  }
+  for (const real of realNames) if (!byReal.has(real)) byReal.set(real, [])
+  const items = []
+  for (const real of [...byReal.keys()].sort()) {
+    const candidates = byReal.get(real).slice().sort()
+    const target = join(scopeDir, real)
+    const realOccupied = isOccupied(target, deps)
+    const realUsable = realOccupied && isUsablePackageDir(target, deps)
+    const base = { real, staleName: null, realOccupied, realUsable, candidates }
+    if (realUsable) {
+      // 健康行：有候选也只是"旁边留着一份旧残留"，不动（幂等：健康树上零动作、零报告项）
+      if (candidates.length === 0) continue
+      items.push({ ...base, action: 'skip', reason: 'real-name-exists', detail: `真名目录里已有 package.json —— 不动旁边那份 ${candidates[0]}` })
+      continue
+    }
+    const pick = pickRestoreCandidate({ scopeDir, real, candidates, deps })
+    if (pick.picked !== null) {
+      items.push({
+        ...base,
+        action: 'restore',
+        staleName: pick.picked.name,
+        reason: realOccupied ? 'real-name-unusable' : 'real-name-missing',
+        detail: realOccupied
+          ? `真名目录存在但没有可读的 package.json（空壳）—— 用 ${pick.picked.name} 恢复，空壳挪成 ${EMPTY_SUFFIX}<ts>`
+          : `真名缺失 —— 用 ${pick.picked.name} 恢复`,
+        mismatch: pick.mismatch,
+        unusable: pick.unusable,
+      })
+      continue
+    }
+    if (pick.mismatch.length > 0) {
+      items.push({
+        ...base,
+        action: 'failed',
+        reason: 'name-mismatch',
+        detail: `候选的 package.json.name 与真名不符（应为 ${expectedPackageName(scopeDir, real)}）：${pick.mismatch.map((m) => `${m.name}=${String(m.nameInPkg)}`).join('、')} —— 一个都不动`,
+        mismatch: pick.mismatch,
+        unusable: pick.unusable,
+      })
+      continue
+    }
+    items.push({
+      ...base,
+      action: 'noCandidate',
+      reason: 'no-usable-stale',
+      detail: pick.unusable.length > 0
+        ? `真名不可用，且 ${pick.unusable.length} 份 .stale-* 都没有可读的 package.json（不可作为候选）`
+        : '真名不可用，且没有任何 .stale-* 候选（框架真缺内容，需要重装）',
+      mismatch: pick.mismatch,
+      unusable: pick.unusable,
+    })
+  }
+  return { ok: true, items, problem: null }
+}
+
+export {
+  EMPTY_SUFFIX,
+  STALE_MARK,
+  candidateStamp,
+  emptyShellName,
+  expectedPackageName,
+  isOccupied,
+  isUsablePackageDir,
+  packageJsonOf,
+  pickRestoreCandidate,
+  planStaleRestore,
+  staleRealNameOf,
+}

package/lib/server/infra/paths.js

@@ -1,7 +1,7 @@
 // L0 · infra（paths.js）—— 分层 Step 从 lib/index.js 搬出，只搬移未改逻辑
 // 分层分组：L0 · infra（边界由 tests/test-architecture-guard.mjs 断言）
 
-import { readFileSync, existsSync, statSync } from 'node:fs'
+import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 import { homedir } from 'node:os'
 import { fileURLToPath } from 'node:url'
@@ -12,10 +12,39 @@ function dshHome() {
   return process.env.DSH_HOME?.trim() || join(homedir(), '.dsh')
 }
 
-/** 默认 profile 用户补丁层路径（无 include 条目可推导时的兜底）。 */
+/**
+ * 默认 profile 用户补丁层路径（无 include 条目可推导时的兜底）。
+ *
+ * 硬编码 `profiles/web` 是真实事故（issue #27）：桌面端机器上 `cordis.yml` 里没有
+ * `cordis:include` 条目时兜底必然生效，于是所有补丁写入都落到早已废弃的 `web` profile，
+ * 正在用的 `desktop` 静默收不到——开关插件、改禁用都没反应，而且不报错。
+ *
+ * 现在按可信度排候选，绝不写死 profile 名：
+ *   ① DSH_PROFILE_DIR（桌面端/CLI 会显式设置，最可信）
+ *   ② DSH_PROFILE（只给名字时拼路径）
+ *   ③ `profiles/` 下真实存在补丁文件的目录（desktop 优先，其余按名字排序保证确定性）
+ */
 function defaultPatchPath() {
   const home = dshHome()
-  return join(home, 'profiles', 'web', 'cordis.patch.yml')
+  const explicitDir = process.env.DSH_PROFILE_DIR?.trim()
+  if (explicitDir !== undefined && explicitDir !== '') return join(explicitDir, 'cordis.patch.yml')
+  const candidates = []
+  const profileName = process.env.DSH_PROFILE?.trim()
+  if (profileName !== undefined && profileName !== '') candidates.push(join(home, 'profiles', profileName, 'cordis.patch.yml'))
+  candidates.push(join(home, 'profiles', 'desktop', 'cordis.patch.yml'))
+  try {
+    const base = join(home, 'profiles')
+    for (const name of readdirSync(base).sort()) {
+      if (name === 'node_modules' || name === 'desktop') continue
+      candidates.push(join(base, name, 'cordis.patch.yml'))
+    }
+  } catch {
+    // profiles 读不到就只用已知候选
+  }
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate
+  }
+  return candidates[0]
 }
 
 /** 从 loader 树推导 profile 的 cordis.patch.yml 绝对路径。 */

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

@@ -0,0 +1,123 @@
+// L2 · routes —— 门控的「按需检查」（0.5.100 加法）：`POST /plugin-console/compat-gate {action:'scan-current'}`
+//
+// 用户 2026-11-02 原话：「我们一般情况下都不预检吧」——compat-pending 只在升级前预扫与启动失败
+// 隔离时写入，平时门控一条记录都没有，而"0 条"会被误读成"全部兼容"。这个动作让用户随时查一次：
+// 对当前补丁里的行逐行跑适配判定，把**判为不适配**的结论记进 compat-pending（`source: 'manual-scan'`），
+// 并回一份统计（检查了几行 / 通过 / 不适配 / 无法判定）。
+//
+// 三条硬边界（判据在 domain/compat-scan.js，写盘纪律在 domain/compat-pending-records.js）：
+//   · 判据复用 `checkPluginFrameworkCompat`（与框架升级预扫同一条链），本文件不新写任何判据；
+//   · **绝不禁用任何行、绝不碰补丁文件** —— 禁用是用户的动作（/toggle）；
+//   · 写盘：备份 → 原子写 → 读回核实 → 失败回滚；坏文件 ⇒ 409 拒绝覆盖（保住用户数据）。
+import { dirname } from 'node:path'
+import { planCurrentScan, recordsFromScan } from '../domain/compat-scan.js'
+import { applyPendingWrite, countPendingRecords, liveRowIdsFromPatch, planScanMerge, readPendingRecords } from '../domain/compat-pending-records.js'
+import { currentFrameworkVersion } from '../domain/framework.js'
+import { readPatchState } from '../domain/patch.js'
+import { listEntries } from '../domain/runtime.js'
+import { sendError, sendJson } from '../infra/httpd.js'
+import { findPatchPath } from '../infra/paths.js'
+
+/** 读回核实的判据：本次写进去的每条 fail 记录都必须真的在盘上，且 check === 'fail'。 */
+function verifyScanWrite(expected) {
+  return (back) => {
+    const rows = (Array.isArray(back?.pending) ? back.pending : []).filter((r) => r !== null && typeof r === 'object')
+    const missing = expected.filter((id) => !rows.some((r) => r.rowId === id && r.check === 'fail'))
+    if (missing.length > 0) return `这些记录没真正落盘：${missing.slice(0, 5).join('、')}`
+    return null
+  }
+}
+
+async function routeCompatScanCurrent(req, res, rc) {
+  const at = Date.now()
+  let profileDir = null
+  let patchRowIds = new Set()
+  try {
+    const patchPath = findPatchPath(rc.ctx)
+    profileDir = dirname(patchPath)
+    patchRowIds = liveRowIdsFromPatch(await readPatchState(patchPath))
+  } catch {
+    sendError(res, 503, '读不到 profile 目录/补丁文件，无法确定要检查的行；本次扫描没有写任何东西', { ok: false, code: 'patch-unreadable' })
+    return
+  }
+  let entries = []
+  try { entries = listEntries(rc.ctx) } catch { entries = [] }
+  let frameworkVersion = null
+  try { frameworkVersion = currentFrameworkVersion(rc.ctx) } catch { frameworkVersion = null }
+  const scan = planCurrentScan({ entries, profileDir, frameworkVersion })
+  const records = recordsFromScan(scan, { at })
+  const read = readPendingRecords()
+  const merge = planScanMerge({
+    read,
+    records,
+    frameworkVersion,
+    lastScan: {
+      at,
+      frameworkVersion: scan.frameworkVersion,
+      checked: scan.checked,
+      pass: scan.pass,
+      fail: scan.fail,
+      unknown: scan.unknown,
+      skipped: scan.skipped.length,
+      source: 'manual-scan',
+    },
+  })
+  const counts = (() => {
+    try { return countPendingRecords(read.records, patchRowIds) } catch { return null }
+  })()
+  const base = {
+    ok: true,
+    action: 'scan-current',
+    frameworkVersion: scan.frameworkVersion,
+    // 扫描统计（面板只放一句短句；明细在 skipped/results 里）
+    checked: scan.checked,
+    pass: scan.pass,
+    fail: scan.fail,
+    unknown: scan.unknown,
+    skipped: scan.skipped,
+    results: scan.results,
+    // 落盘情况
+    recorded: records.length,
+    added: merge.added ?? [],
+    updated: merge.updated ?? [],
+    changed: false,
+    file: read.file,
+    backup: null,
+    verified: false,
+    counts,
+    error: scan.error,
+    note: null,
+  }
+  if (merge.ok !== true) {
+    // 坏文件：结论不写盘，但扫描统计照样如实回（用户至少知道"现在查出来是什么"）
+    sendError(res, merge.status ?? 500, merge.error ?? '扫描结果写入失败', { ...base, error: merge.error ?? scan.error })
+    return
+  }
+  if (merge.changed !== true) {
+    sendJson(res, 200, {
+      ...base,
+      changed: false,
+      note: scan.checked === 0
+        ? '没有可检查的行（补丁里没有可判定的插件行），未写任何记录'
+        : `检查 ${scan.checked} 行：通过 ${scan.pass} / 不适配 ${scan.fail} / 无法判定 ${scan.unknown}；记录没有变化（无需写盘）`,
+    })
+    return
+  }
+  const write = applyPendingWrite({ file: read.file, next: merge.next, verify: verifyScanWrite(records.map((r) => r.rowId)), tag: 'scan' })
+  const payload = {
+    ...base,
+    ok: write.ok === true,
+    changed: write.ok === true,
+    backup: write.backup ?? null,
+    verified: write.verified === true,
+    error: write.error ?? scan.error,
+    note: write.ok === true
+      ? `检查 ${scan.checked} 行：通过 ${scan.pass} / 不适配 ${scan.fail} / 无法判定 ${scan.unknown}`
+        + (records.length > 0 ? `；已记下 ${records.length} 条待适配结论（只记录，未禁用任何行）` : '；没有不适配的行，未新增记录')
+      : null,
+  }
+  if (write.ok === true) sendJson(res, 200, payload)
+  else sendError(res, write.status ?? 500, write.error ?? '扫描结果写入失败', payload)
+}
+
+export { routeCompatScanCurrent }

package/lib/server/routes/compat.js

@@ -26,6 +26,11 @@ import { DEFAULT_TIMEOUT_MS, autoPreflightView, runAutoPreflight } from '../doma
 import { runAutoPreflightScan } from '../domain/auto-preflight-run.js'
 import { NOTICE_MODES, detectCompat, readCompatAck, readCompatGate, readCompatPending, rowIdModuleMap, writeCompatAck, writeCompatGate, writeCompatPending } from '../domain/compat.js'
 import { compareFingerprint, computeFingerprint, planDesktopHostSwitch, readCompatMode, readFingerprint, readRollbackRecord, stampFingerprint, writeCompatMode } from '../domain/compat-state.js'
+// 0.5.98 加法：适配门**记录**的删除（真待适配判据 + 写盘纪律都在该模块；本路由只映射状态码）
+import { applyPendingForget, countPendingRecords, liveRowIdsFromPatch, planForgetRecord, planForgetStale, readPendingRecords } from '../domain/compat-pending-records.js'
+import { readPatchState } from '../domain/patch.js'
+// 0.5.100 加法：门控的「按需检查」（只记录结论，绝不禁用任何行）
+import { routeCompatScanCurrent } from './compat-scan.js'
 import { currentFrameworkVersion, detectHostShape } from '../domain/framework.js'
 import { applyDependencyBackfill, planDependencyBackfill } from '../domain/manifest.js'
 import { isProtectedModule } from '../domain/runtime.js'
@@ -455,4 +460,88 @@ async function routeCompatAck(req, res, rc) {
   const ack = writeCompatAck(version)
   sendJson(res, 200, { ok: true, ack, noticeMode: readCompatGate().noticeMode })
 }
-export { hostShapeOf, maybeSwitchToObserver, maybeWriteSnapshot, preflightTimeoutMs, resetHostSwitchChecked, routeCompatAck, routeCompatMode, routeCompatStamp, routeCompatStatusGet, routeDeclareInstalled, scheduleAutoPreflight }
+/**
+ * POST /plugin-console/compat-gate 的**动作分派**（0.5.98 起；0.5.100 多一个 `scan-current`）。
+ *
+ *   `{ action: 'forget', rowId }`    删一条记录          → 见下（routeCompatPendingForget 的本体）
+ *   `{ action: 'forget-stale' }`     清掉失效记录        → 同上
+ *   `{ action: 'scan-current' }`     **按需检查**（0.5.100 加法，用户「平时不预检」的痛点）
+ *                                    → routes/compat-scan.js（只记录结论，绝不禁用任何行）
+ *   没有 `action`（或不是已知动作）⇒ **逐字**走原来的总开关逻辑（既有契约零变化）
+ *
+ * 为什么都挤在**既有的 /compat-gate** 上而不新开路由：门控面板的所有写入口必须同源
+ * （否则又要登记一份路由清单，两处判据迟早分叉）。装配层的分流见 routes/index.js#routeCompatGateAny。
+ */
+async function routeCompatGateAction(req, res, rc) {
+  const action = typeof rc.body?.action === 'string' ? rc.body.action.trim() : ''
+  if (action === 'scan-current') return routeCompatScanCurrent(req, res, rc)
+  return routeCompatPendingForget(req, res, rc)
+}
+
+/**
+ * POST /plugin-console/compat-gate `{ action: 'forget' | 'forget-stale' }`
+ *   —— 适配门**记录**的删除（0.5.98 加法，用户 2026-10-28 明确要求）。
+ *
+ * 语义（三条硬边界，用户定案）：
+ *   · 只删 **记录**：不动插件、不动补丁文件、不动 bundles 清单；
+ *   · `forget` 删指定 rowId；`forget-stale` 只清「status=pending 且该行已不在补丁里」的失效记录，
+ *     真 pending 与 adopted 一条都不动；没有可清的 ⇒ `changed:false` 且**零写盘**；
+ *   · 删不存在的 rowId ⇒ 404 + 明确原因（绝不静默成功）；坏文件 ⇒ 409 拒绝覆盖（保住用户数据）。
+ *
+ * 写盘纪律全在 domain/compat-pending-records.js：备份 → 原子写（临时文件 + rename）→ 读回核实 → 失败回滚。
+ * 「行是否存在」只取补丁解析的既有产物（domain/patch.js#readPatchState），不另写一套正则。
+ */
+async function routeCompatPendingForget(req, res, rc) {
+  const body = rc.body ?? {}
+  const action = typeof body.action === 'string' ? body.action.trim() : ''
+  if (action !== 'forget' && action !== 'forget-stale') {
+    sendError(res, 400, `未知动作 ${JSON.stringify(body.action)}（可选 forget / forget-stale）`, { ok: false, error: '未知动作', code: 'unknown-action' })
+    return
+  }
+  const read = readPendingRecords()
+  // 判据唯一真源：补丁此刻真实存在的行（与 /state 里 patch.disables/forced/inserts 同源）
+  let liveRowIds = new Set()
+  try {
+    const patchPath = findPatchPath(rc.ctx)
+    liveRowIds = liveRowIdsFromPatch(await readPatchState(patchPath))
+  } catch {
+    // 读不到补丁 ⇒ 只能认定"没有任何行存在"；此时 forget-stale 会把 pending 全判成 stale，
+    // 那等于凭一个读失败删用户记录 —— 所以这条通道**必须停下**（宁可红，也不报假的绿）。
+    sendError(res, 503, '读不到 profile 补丁文件，无法判断哪些记录还指向真实的行；本次删除已停止（文件未改动）', { ok: false, code: 'patch-unreadable' })
+    return
+  }
+  const plan = action === 'forget'
+    ? planForgetRecord({ read, rowId: body.rowId })
+    : planForgetStale({ read, liveRowIds })
+  const result = plan.ok === true && plan.changed === true ? applyPendingForget(plan) : plan
+  const removed = Array.isArray(result.removedRowIds) ? result.removedRowIds : []
+  const removedCount = removed.length
+  const note = result.ok !== true
+    ? null
+    : (action === 'forget'
+      ? `已删除记录 ${String(body.rowId)}（其余记录原样保留；插件与补丁一个字都没动）`
+      : (removedCount > 0
+        ? `已清理 ${removedCount} 条失效记录（真实待适配与历史记录一条没动；插件与补丁一个字都没动）`
+        : '没有可清理的失效记录（文件未改动）'))
+  const payload = {
+    ok: result.ok === true,
+    action,
+    changed: result.changed === true,
+    removed,
+    removedCount,
+    keptCount: Array.isArray(result.keptRowIds) ? result.keptRowIds.length : 0,
+    // 删完之后按**同一判据**重算一遍（面板据此重绘；不复用旧计数，避免"删了但数字没动"）
+    counts: (() => {
+      try { return countPendingRecords(readPendingRecords().records, liveRowIds) } catch { return null }
+    })(),
+    file: read.file,
+    backup: result.backup ?? null,
+    verified: result.verified === true,
+    error: result.error ?? null,
+    note,
+  }
+  if (result.ok === true) sendJson(res, 200, payload)
+  else sendError(res, result.status ?? 400, result.error ?? '删除记录失败', payload)
+}
+
+export { hostShapeOf, maybeSwitchToObserver, maybeWriteSnapshot, preflightTimeoutMs, resetHostSwitchChecked, routeCompatAck, routeCompatGateAction, routeCompatMode, routeCompatPendingForget, routeCompatStamp, routeCompatStatusGet, routeDeclareInstalled, scheduleAutoPreflight }

package/lib/server/routes/index.js

@@ -16,7 +16,7 @@ import { readBody, sendError } from '../infra/httpd.js'
 import { routeAiConsent, routeAiEmpowerCancel, routeAiEmpowerList, routeAiEmpowerPlan, routeAiEmpowerRun, routeAiEmpowerStatus } from './ai.js'
 import { routeRunSuggested } from './actions.js'
 import { routeComponentAutostart, routeComponentStart, routeComponentStatus, routeComponentStop, routeComponents, routeRepoClone, routeRepoLandConfig, routeRepoList, routeRepoOpen, routeRepoRemove } from './components.js'
-import { routeCompatAck, routeCompatMode, routeCompatStamp, routeCompatStatusGet, routeDeclareInstalled } from './compat.js'
+import { routeCompatAck, routeCompatGateAction, routeCompatMode, routeCompatPendingForget, routeCompatStamp, routeCompatStatusGet, routeDeclareInstalled } from './compat.js'
 import { routeSafeBoot } from './safe-boot.js'
 // issue #22 ②③ 加法：用户备注 / 用户徽章 / 用户自建分组（独立文件，与插件列表完全解耦）
 import { routeAnnotationsGet, routeAnnotationsPost } from './annotations.js'
@@ -81,6 +81,23 @@ function routeDeps() {
   return { runInstallJob, runSuiteInstallJob, webPort, readExtraBundleRows, detectAdoptablePending, listEntries, detectCompat, detectFrameworkUpgrade, DEFAULT_SEARCH, aiEmpowerExecute, aiEmpowerPlan, backupProfileSnapshot, currentFrameworkVersion, frameworkCompatReportFor, isProtectedModule, pnpmRemove, preflightDisableIncompatible, rowIdModuleMap, fetchJson: fetchJsonUrl }
 }
 
+/**
+ * `/compat-gate` 的**只增不改**分流（0.5.98 加法）。
+ *
+ * 为什么分流装在这一层：门控面板的写入口必须挂在**既有的 /compat-gate** 上（不新开路由，
+ * 否则又要登记一份清单）；而那条路由的 handler（routes/framework.js#routeCompatGate）所在文件
+ * 已顶格 600/600 行（tests/test-architecture-guard.mjs 的硬门槛），**一个字都不能加**。
+ * 于是"分流"留在装配层，"动作实现"落在 routes/compat.js（适配门记录那一族）。
+ *
+ * 契约：body 里没有 `action`（或不是非空字符串）⇒ **逐字**走原来的总开关逻辑，
+ * 既有请求/响应一字不变；带 `action` 才进动作分派那一族（0.5.98 删记录 / 0.5.100 按需检查）。
+ */
+async function routeCompatGateAny(req, res, rc) {
+  const action = typeof rc.body?.action === 'string' ? rc.body.action : ''
+  if (action !== '') return routeCompatGateAction(req, res, rc)
+  return routeCompatGate(req, res, rc)
+}
+
 async function handle(ctx, req, res) {
   const url = new URL(req.url ?? '/', 'http://x')
   const pathname = url.pathname
@@ -126,7 +143,7 @@ const ROUTES = [
   { methods: ['POST'], path: `${ROUTE_PREFIX}/skill-toggle`, handler: routeSkillToggle },
   { methods: ['POST'], path: `${ROUTE_PREFIX}/install`, handler: routeInstall },
   { methods: ['POST'], path: `${ROUTE_PREFIX}/install-status`, handler: routeInstallStatus },  { methods: ['POST'], path: `${ROUTE_PREFIX}/framework-check`, handler: routeFrameworkCheck },
-  { methods: ['POST'], path: `${ROUTE_PREFIX}/compat-gate`, handler: routeCompatGate },
+  { methods: ['POST'], path: `${ROUTE_PREFIX}/compat-gate`, handler: routeCompatGateAny },
   { methods: ['POST'], path: `${ROUTE_PREFIX}/check-update`, handler: routeCheckUpdate },
   // issue #22 ① 加法：批量检测（已安装列表的「一键检测全部更新」）。
   // ★ 与 /check-update 共用同一个探针（probePackageUpdate），判据不分叉；并发上限在 domain/update-batch.js。

package/lib/server/routes/state.js

@@ -12,6 +12,8 @@ import { bundleVetoList } from '../domain/bundle-veto.js'
 import { buildLinkInventory } from '../domain/link-inventory.js'
 import { buildInstallHealth } from '../domain/install-health.js'
 import { applyExemption } from '../domain/compat-exempt.js'
+// 0.5.98 加法：适配门记录的「真待适配」计数（唯一真源，见 domain/compat-pending-records.js）
+import { annotateGateRows, countPendingRecords, liveRowIdsFromPatch } from '../domain/compat-pending-records.js'
 import { addDevRoot, readDevRoots, removeDevRoot } from '../domain/dev-roots.js'
 import { applyPinDevDir, planPinDevDir } from '../domain/pin-dev-dir.js'
 import { reconcileLockfile } from '../domain/selfupdate.js'
@@ -68,6 +70,13 @@ async function routeStateGet(req, res, rc) {
     const compatPending = pendingState.pending
     const compatVerdicts = pendingState.verdicts
     const compatPendingRows = new Set((compatPending?.pending ?? []).filter((p) => (p.status ?? 'pending') === 'pending').map((p) => p.rowId))
+    // ★ 0.5.98 加法（用户 2026-10-28 实测）：**「真待适配」的唯一口径**。
+    //   现场：compat-pending.json 里 20 条 adopted + 3 条 pending 且 moduleName 为 null（补丁行早已不存在），
+    //   面板把 `pending` 数组长度当"待适配"，用户看到"有 N 行待适配"，其实一行都没有。
+    //   判据只认 domain/compat-pending-records.js#isActionablePending（status=pending 且该行仍在补丁里）；
+    //   「行是否存在」取的是**补丁解析的既有产物**（上面 patch 的 disables/forced/inserts），不另写正则。
+    const patchRowIds = liveRowIdsFromPatch(patch)
+    const pendingCounts = countPendingRecords(compatPending?.pending ?? [], patchRowIds)
     // 兼容门总开关 + 自动检测（只提示不自动开）
     const compatGate = readCompatGate()
     const adoptable = compatGate.autoDetect ? detectAdoptablePending(ctx) : new Map()
@@ -264,7 +273,28 @@ async function routeStateGet(req, res, rc) {
     } catch (error) {
       lockAutofix = { error: error instanceof Error ? error.message : String(error), scheduled: false }
     }
-    sendJson(res, 200, { ok: true, entries: allEntries, skippedBundles, host, health, patchPath, compat, installJobs: jobs, recentFailures, pendingRestart, github: { loggedIn: auth.loggedIn, login: auth.login }, patch: { disables: patch.disables, forced: patch.forced, inserts: patch.inserts }, framework, lockAutofix, patchHeal: patchHeal === null ? null : { healed: patchHeal.healed ?? [], autoDisabled: patchHeal.autoDisabled ?? [], healedAt: patchHeal.healedAt ?? 0, written: patchHeal.written === true, writeError: patchHeal.writeError ?? null, skippedFrameworkOwned: (patchHeal.skipped ?? []).map((s) => s.id ?? null), uncertain: (patchHeal.uncertain ?? []).map((u) => u.id ?? null) }, gating: gatingSummary(ctx, compatPending, entries, compatVerdicts), compatPending: compatPending === null ? null : { frameworkVersion: compatPending.frameworkVersion ?? null, upgradeFrom: compatPending.upgradeFrom ?? null, pending: (compatPending.pending ?? []).filter((p) => (p.status ?? 'pending') === 'pending').map((p) => ({ rowId: p.rowId, moduleName: p.moduleName, version: p.version ?? null, checkNote: p.checkNote ?? null, check: p.check ?? null, riskyApprovedAt: p.riskyApprovedAt ?? null, adoptable: adoptable.get(p.rowId) ?? null, verdict: compatVerdicts.get(p.rowId) ?? null })), verdictRefresh: pendingState.refresh === null ? null : { version: pendingState.refresh.version ?? null, updated: pendingState.refresh.updated ?? [], unchanged: pendingState.refresh.unchanged ?? [], unresolved: pendingState.refresh.unresolved ?? [], wrote: pendingState.refresh.wrote === true, writeError: pendingState.refresh.writeError ?? null } }, compatGate, rollback: rollbackRec, selfVersion, components: findComponents().map((c) => ({ id: c.id, name: c.name, kind: c.kind ?? 'server', pid: c.pid ?? null, port: c.port ?? null, healthUrl: c.healthUrl ?? null, uiUrl: compUiUrl(c), autoStart: c.autoStart === true })) })
+    // ★ 0.5.98 加法：门控明细行补两个**只增不改**的字段 —— `rowMissing`（这一行的 rowId 已不在
+    //   当前补丁里）与 `actionable`（与计数同一个判据）。面板据此如实标注「该行已不存在」并给删除入口；
+    //   既有字段（pendingCount / rows 的全部旧字段）一个不少、语义不变。
+    // ★ 0.5.101 加法（用户 2026-11-02）：**运行期加载失败**的行（`fiberPhase === 'failed'`）。
+    //   真机现场：`experimental-inspector` 因 `@deepseek-ai/cordis` 解析失败而挂载失败，而门控**完全
+    //   看不到它** —— 因为这条失败不经过预扫/隔离链。这里只补一个**视图**字段：
+    //   **绝不写 compat-pending.json**（那是适配裁决记录，不能被运行期故障污染）、不改任何既有字段。
+    const loadFailed = entries
+      .filter((e) => e.fiberPhase === 'failed' && typeof e.rowId === 'string' && e.rowId !== '')
+      .map((e) => ({ rowId: e.rowId, moduleName: e.moduleName ?? null, version: e.version ?? null, fiberPhase: 'failed', enabled: e.enabled === true }))
+    const gatingOut = (() => {
+      const g = gatingSummary(ctx, compatPending, entries, compatVerdicts)
+      return {
+        ...g,
+        pending: annotateGateRows(g.pending, patchRowIds),
+        adopted: annotateGateRows(g.adopted, patchRowIds),
+        // 只增字段：加载失败的行 + 计数（面板据此决定分区显不显示）
+        loadFailed,
+        loadFailedCount: loadFailed.length,
+      }
+    })()
+    sendJson(res, 200, { ok: true, entries: allEntries, skippedBundles, host, health, patchPath, compat, installJobs: jobs, recentFailures, pendingRestart, github: { loggedIn: auth.loggedIn, login: auth.login }, patch: { disables: patch.disables, forced: patch.forced, inserts: patch.inserts }, framework, lockAutofix, patchHeal: patchHeal === null ? null : { healed: patchHeal.healed ?? [], autoDisabled: patchHeal.autoDisabled ?? [], healedAt: patchHeal.healedAt ?? 0, written: patchHeal.written === true, writeError: patchHeal.writeError ?? null, skippedFrameworkOwned: (patchHeal.skipped ?? []).map((s) => s.id ?? null), uncertain: (patchHeal.uncertain ?? []).map((u) => u.id ?? null) }, gating: gatingOut, compatPending: compatPending === null ? null : { frameworkVersion: compatPending.frameworkVersion ?? null, upgradeFrom: compatPending.upgradeFrom ?? null, pending: (compatPending.pending ?? []).filter((p) => (p.status ?? 'pending') === 'pending').map((p) => ({ rowId: p.rowId, moduleName: p.moduleName, version: p.version ?? null, checkNote: p.checkNote ?? null, check: p.check ?? null, riskyApprovedAt: p.riskyApprovedAt ?? null, adoptable: adoptable.get(p.rowId) ?? null, verdict: compatVerdicts.get(p.rowId) ?? null })), verdictRefresh: pendingState.refresh === null ? null : { version: pendingState.refresh.version ?? null, updated: pendingState.refresh.updated ?? [], unchanged: pendingState.refresh.unchanged ?? [], unresolved: pendingState.refresh.unresolved ?? [], wrote: pendingState.refresh.wrote === true, writeError: pendingState.refresh.writeError ?? null }, actionableCount: pendingCounts.actionableCount, staleCount: pendingCounts.staleCount, lastScan: compatPending.lastScan ?? null }, compatGate, rollback: rollbackRec, selfVersion, components: findComponents().map((c) => ({ id: c.id, name: c.name, kind: c.kind ?? 'server', pid: c.pid ?? null, port: c.port ?? null, healthUrl: c.healthUrl ?? null, uiUrl: compUiUrl(c), autoStart: c.autoStart === true })) })
     return
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noob-stupid/dsh-plugin-console",
-  "version": "0.5.97",
+  "version": "0.5.99",
   "description": "DSH 框架升级安全与插件升级门控：一键升级、失败自动回滚、升级后回滚上版、旧插件不适配自动禁用；内置多源插件市场为发现层，插件源全部可自定义，可指向公司内网私有源 / 私有索引 / 本地 Git 仓库，纯内网离线可用 | Framework upgrade safety & plugin version gating for DSH, with a customizable multi-source plugin market: point every source at internal mirrors or a local file:// repo for intranet-only, offline installs.",
   "repository": {
     "type": "git",