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

package/lib/server/domain/auto-preflight.js

@@ -0,0 +1,345 @@
+// L1 · domain —— auto-preflight.js（环境指纹变化 → 自动预检的**判定与记录层**；0.5.32 加法 D1）
+//
+// 为什么要有它（用户 2026-09-29 诉求，原话）：
+//   「走**别的**更新通道（官方桌面端更新器 / 手动 pnpm / npx 缓存变化）改了框架后，我们**仍要自动守门**」。
+// 现状（0.5.31）：`domain/compat-state.js` 的 `compareFingerprint` 已经能**发现**任何来源的框架变更
+//   （`routes/compat.js` 每次状态查询现场算指纹并与基线比对），但发现之后**只上报一行文案**，
+//   不会自动跑预检；而「启动失败隔离」（`domain/quarantine.js`）的输入是我们自己的升级脚本留下的
+//   记录 —— 别人升级时**没有这份记录**，兜底因此不触发。本模块补上中间那一段：
+//
+//   指纹变化（changed=true）→ **自动跑一次只读预检** → 落成三样东西：
+//     ① 兼容清单（受影响行 + 判据）  ② 隔离计划（建议禁用哪些行、为什么）  ③ 本次变更摘要（版本 from→to / 新增消失的包 / 指纹 reasons）
+//
+// 四条硬约束（全部可离线断言，见 tests/test-auto-preflight.mjs）：
+//   · **只读**：不下载、不安装、不改补丁、不碰 loader —— 本模块连 ctx/ports 都不认识（只吃注入的窄接口）；
+//   · **同一指纹只自动跑一次**：以指纹为 key 持久化「已扫过」标记；失败**如实记录原因**且**允许重试**；
+//   · **绝不阻塞状态查询**：超时/异常一律降级成「未完成，可手动重跑」，状态查询该返回什么还返回什么；
+//   · 纯函数为主：判定（shouldAutoRun）、超时包裹（withTimeout）、增量（summarizeDelta）、
+//     记录合并（upsertRecord）都不做 IO，IO 只出现在 store 读写与 runAutoPreflight 的调用缝上。
+//
+// 分层：L1 domain —— 无 ctx、无 HTTP、不抛（异常在 runAutoPreflight 内被收成 state='failed'）。
+
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { dshHome } from '../infra/paths.js'
+
+/** 记录文件（与我们其余的常驻状态同住 `dshHome()/plugin-console/`，不碰用户 profile）。 */
+const autoPreflightFile = () => join(dshHome(), 'plugin-console', 'auto-preflight.json')
+
+/** 保留最近的扫描记录条数（防止指纹频繁抖动把状态文件撑大）。 */
+const MAX_RECORDS = 12
+
+/** 自动预检的默认超时（毫秒）。宁可降级成「未完成，可手动重跑」，也不让状态查询等它。 */
+const DEFAULT_TIMEOUT_MS = 4000
+
+const STATES = ['pending', 'done', 'failed', 'timeout']
+
+/**
+ * 指纹的**稳定 key**：只取参与变更判定的三个字段（`at` 每次都变，绝不能进 key）。
+ * 归一化：字符串去空白 + 小写（win32 路径大小写不敏感；两个指纹「实际相同」时不许各跑一次）。
+ */
+function fingerprintKey(fp) {
+  const norm = (value, lower = false) => {
+    if (value === null || value === undefined) return ''
+    const text = String(value).trim()
+    return lower ? text.toLowerCase() : text
+  }
+  // 空包数按 '?' 归一：null 与 undefined 是同一件事（数不出来），别当成"变了"
+  const entities = fp?.pnpmEntities === null || fp?.pnpmEntities === undefined ? '?' : String(fp.pnpmEntities)
+  // 路径：反斜杠归一成正斜杠（Windows 的 `C:\x` 与 `C:/x` 是同一棵树）+ 小写（win32 不区分大小写）
+  const root = norm(fp?.pnpmRoot, true).replace(/\\/gu, '/')
+  return [norm(fp?.frameworkVersion), root, entities].join('|')
+}
+
+/** 两份指纹是否「实际相同」（同一 key）。 */
+function sameFingerprint(a, b) {
+  return fingerprintKey(a) === fingerprintKey(b)
+}
+
+function readStore(file = autoPreflightFile()) {
+  try {
+    const rec = JSON.parse(readFileSync(file, 'utf8'))
+    if (rec === null || typeof rec !== 'object') return { schema: 1, records: [] }
+    return { schema: 1, records: Array.isArray(rec.records) ? rec.records : [] }
+  } catch {
+    return { schema: 1, records: [] }
+  }
+}
+
+/** 只增不删的合并：同 key 记录用新值覆盖，别的 key 原样保留；按 at 倒序裁剪到 MAX_RECORDS。 */
+function upsertRecord(records, record, limit = MAX_RECORDS) {
+  const list = Array.isArray(records) ? records.filter((r) => r !== null && typeof r === 'object') : []
+  const key = typeof record?.key === 'string' ? record.key : fingerprintKey(record?.fingerprint)
+  const next = list.filter((r) => (typeof r.key === 'string' ? r.key : fingerprintKey(r.fingerprint)) !== key)
+  next.push({ ...record, key })
+  next.sort((a, b) => (Number(b?.at ?? 0) - Number(a?.at ?? 0)))
+  return next.slice(0, limit)
+}
+
+function writeStore(store, file = autoPreflightFile()) {
+  mkdirSync(dirname(file), { recursive: true })
+  writeFileSync(file, `${JSON.stringify({ schema: 1, updatedAt: new Date().toISOString(), records: store.records }, null, 2)}\n`, 'utf8')
+}
+
+/** 从记录集里取某个指纹的那条记录（没有则 null）。 */
+function findRecord(records, fp) {
+  const key = fingerprintKey(fp)
+  return (Array.isArray(records) ? records : []).find((r) => (typeof r?.key === 'string' ? r.key : fingerprintKey(r?.fingerprint)) === key) ?? null
+}
+
+/**
+ * 自动预检的**执行判定**（纯函数）。三种「不跑」：
+ *   · state='done'    → 同一指纹已经扫过（这就是"同指纹只自动跑一次"的闸门）；
+ *   · state='pending' → 上一次还挂在超时边缘（没有结论），交给手动重跑，不叠加并发；
+ *   · state='failed' / 'timeout' → **允许重试一次**（失败要能重试），但同一指纹最多自动重试 limit 次。
+ * @returns {{ run: boolean, reason: string, attempt: number }}
+ */
+function shouldAutoRun(record, { retryLimit = 1 } = {}) {
+  if (record === null || record === undefined) return { run: true, reason: 'first-seen', attempt: 1 }
+  const state = typeof record.state === 'string' ? record.state : 'failed'
+  const attempts = Number.isFinite(Number(record.attempts)) ? Number(record.attempts) : 0
+  if (state === 'done') return { run: false, reason: 'already-scanned', attempt: attempts }
+  if (state === 'pending') return { run: false, reason: 'in-flight', attempt: attempts }
+  if (attempts >= retryLimit + 1) return { run: false, reason: 'retry-exhausted', attempt: attempts }
+  return { run: true, reason: state === 'timeout' ? 'retry-after-timeout' : 'retry-after-failure', attempt: attempts + 1 }
+}
+
+/**
+ * 超时包裹（纯函数，**不抛**）：到点就返回 `{ timedOut: true }`，绝不把异常甩给调用方。
+ * 注意它**不会取消**底层 promise（JS 没有取消语义）—— 底层跑完后的写盘由 runAutoPreflight 收口，
+ * 但那不影响状态查询：调用方拿到 timedOut 就立刻回响应。
+ */
+function withTimeout(promise, ms, onTimeout = null) {
+  const limit = Number.isFinite(Number(ms)) && Number(ms) > 0 ? Number(ms) : DEFAULT_TIMEOUT_MS
+  let timer = null
+  const timeout = new Promise((resolve) => {
+    timer = setTimeout(() => {
+      if (typeof onTimeout === 'function') { try { onTimeout() } catch {} }
+      resolve({ timedOut: true, value: null })
+    }, limit)
+    if (typeof timer?.unref === 'function') timer.unref()
+  })
+  const wrapped = Promise.resolve(promise).then(
+    (value) => ({ timedOut: false, value }),
+    (error) => ({ timedOut: false, value: null, error: error instanceof Error ? error.message : String(error) }),
+  )
+  return Promise.race([wrapped, timeout]).finally(() => { if (timer !== null) clearTimeout(timer) })
+}
+
+/**
+ * 兼容清单：把补丁体检与源码扫描的结论收敛成**受影响行**（面板按行显示，一行一句）。
+ * 只做汇总与排序，不新增判据（判据留在 patch-composition-audit / format-scan 两个模块里）。
+ */
+function affectedRows({ patchReport = null, scan = null, rows = [], limit = 40 } = {}) {
+  const out = []
+  const nameById = new Map((Array.isArray(rows) ? rows : []).map((r) => [r?.id, r?.name ?? null]))
+  for (const item of (patchReport?.blockers ?? [])) {
+    out.push({
+      rowId: item.row ?? null, moduleName: item.name ?? nameById.get(item.row) ?? null, severity: 'blocker',
+      code: item.code ?? 'patch-row', line: item.line ?? null, detail: item.detail ?? null,
+      hint: item.hint ?? null, suggestions: item.suggestions ?? [],
+    })
+  }
+  for (const item of (patchReport?.warnings ?? [])) {
+    out.push({
+      rowId: item.row ?? null, moduleName: item.name ?? nameById.get(item.row) ?? null, severity: 'warn',
+      code: item.code ?? 'patch-row', line: item.line ?? null, detail: item.detail ?? null,
+      hint: item.hint ?? null, suggestions: item.suggestions ?? [],
+    })
+  }
+  for (const f of (scan?.findings ?? [])) {
+    out.push({
+      rowId: null, moduleName: f.moduleName ?? null, severity: f.severity ?? 'warn',
+      code: f.rule ?? 'source-scan', line: f.line ?? null,
+      detail: `${f.file ?? '?'}${f.line === null || f.line === undefined ? '' : `:${f.line}`}${f.before === undefined ? '' : ` → ${f.after ?? ''}`}`,
+      hint: f.reason ?? f.note ?? null, suggestions: [],
+    })
+  }
+  const rank = { blocker: 0, warn: 1 }
+  out.sort((a, b) => (rank[a.severity] ?? 9) - (rank[b.severity] ?? 9) || String(a.rowId ?? '').localeCompare(String(b.rowId ?? '')))
+  return out.slice(0, limit)
+}
+
+/**
+ * 隔离计划：**建议**禁用哪些行 + 为什么（绝不自动写盘；真正落盘只走用户显式触发的
+ * `POST /plugin-console/safe-boot {action:'disable-suspects'}` 或离线脚本）。
+ * 只收「点名 + 可开关 + 非核心」的行：核心行禁掉只会让服务更起不来（正确动作是回滚框架）。
+ */
+function planSuspectRows(affected, { coreRowIds = new Set(), toggleableById = new Map(), limit = 20 } = {}) {
+  const suspects = []
+  const skipped = []
+  for (const item of (Array.isArray(affected) ? affected : [])) {
+    if (item.severity !== 'blocker' || typeof item.rowId !== 'string' || item.rowId === '') continue
+    if (coreRowIds.has(item.rowId)) { skipped.push({ rowId: item.rowId, reason: 'core-row' }); continue }
+    if (item.rowId === 'plugin-console') { skipped.push({ rowId: item.rowId, reason: 'self' }); continue }
+    if (toggleableById.has(item.rowId) && toggleableById.get(item.rowId) === false) { skipped.push({ rowId: item.rowId, reason: 'not-toggleable' }); continue }
+    if (suspects.some((s) => s.rowId === item.rowId)) continue
+    if (suspects.length >= limit) break
+    suspects.push({ rowId: item.rowId, moduleName: item.moduleName ?? null, reason: item.code, detail: item.detail ?? null, line: item.line ?? null })
+  }
+  return { suspects, skipped }
+}
+
+/** 本次变更摘要：框架版本 from→to + 新增/消失的包 + 指纹 reasons（面板一句话，详情放长文）。 */
+function summarizeDelta({ current = null, previous = null, currentPackages = [], previousPackages = [] } = {}) {
+  const from = previous?.frameworkVersion ?? null
+  const to = current?.frameworkVersion ?? null
+  const before = new Set((Array.isArray(previousPackages) ? previousPackages : []).filter((n) => typeof n === 'string' && n !== ''))
+  const after = new Set((Array.isArray(currentPackages) ? currentPackages : []).filter((n) => typeof n === 'string' && n !== ''))
+  const added = [...after].filter((n) => !before.has(n)).sort()
+  const removed = [...before].filter((n) => !after.has(n)).sort()
+  return {
+    frameworkVersionFrom: from,
+    frameworkVersionTo: to,
+    versionChanged: from !== to,
+    packagesAdded: added.slice(0, 50),
+    packagesRemoved: removed.slice(0, 50),
+    packagesAddedCount: added.length,
+    packagesRemovedCount: removed.length,
+    rootChanged: (previous?.pnpmRoot ?? null) !== (current?.pnpmRoot ?? null),
+    entitiesChanged: (previous?.pnpmEntities ?? null) !== (current?.pnpmEntities ?? null),
+    rationaleAvailable: before.size > 0 || after.size > 0,
+  }
+}
+
+/** 面板/离线脚本共用的一句话短句（中英双语；面板只放这一句，长文进 detail）。 */
+function autoPreflightNote(state, { blockers = 0, suspects = 0 } = {}) {
+  const zh = {
+    pending: '环境变了，正在自动预检…',
+    done: blockers > 0 ? `环境变了：预检发现 ${blockers} 行受影响${suspects > 0 ? `，建议禁用 ${suspects} 行` : ''}` : '环境变了：自动预检未发现受影响行',
+    failed: '环境变了，但自动预检失败（可手动重跑）',
+    timeout: '环境变了，自动预检超时（可手动重跑）',
+    idle: '环境未变化，无需自动预检',
+  }
+  const en = {
+    pending: 'Environment changed — auto-preflight running…',
+    done: blockers > 0 ? `Environment changed: ${blockers} affected row(s)${suspects > 0 ? `, ${suspects} suggested for disable` : ''}` : 'Environment changed: auto-preflight found no affected rows',
+    failed: 'Environment changed, but auto-preflight failed (you can re-run it)',
+    timeout: 'Environment changed; auto-preflight timed out (you can re-run it)',
+    idle: 'No environment change — auto-preflight not needed',
+  }
+  const key = Object.prototype.hasOwnProperty.call(zh, state) ? state : 'idle'
+  return { state: key, zh: zh[key], en: en[key] }
+}
+
+/**
+ * 自动预检收口（**这条路径不阻塞任何调用方**：调用方不 await 它）。
+ * 流程：判定是否该跑 → 写 state='pending' 占位（同指纹只跑一次的闸门立刻生效）→ 跑注入的扫描
+ *       → 落 `{state:'done', preflight, affected, suspects, delta}`；失败/超时如实落 `failed`/`timeout` + reason。
+ * 写盘失败也不抛（返回 `{ok:false, error}`），因为它的调用方是只读状态查询。
+ *
+ * ★ 并发纪律（2026-09-29 实测踩到）：**终态写入必须只落自己的那一条**。
+ *   早先的写法是"读整份 store → push → 整份写回"，两个指纹的扫描同时收尾时会互相覆盖
+ *   （谁后写谁赢，另一条的终态**永远停在 pending** —— 面板就永远显示"正在自动预检…"）。
+ *   现在终态写盘只 upsert **当前 key 的那一条**，其余记录原样保留。
+ */
+async function runAutoPreflight({ current, previous, scan, timeoutMs = DEFAULT_TIMEOUT_MS, now = () => Date.now(), file = autoPreflightFile() } = {}) {
+  const key = fingerprintKey(current)
+  const startedAt = now()
+  try {
+    const store = readStore(file)
+    const existing = findRecord(store.records, current)
+    const verdict = shouldAutoRun(existing)
+    if (!verdict.run) return { ok: true, ran: false, reason: verdict.reason, key, state: existing?.state ?? 'idle' }
+    const pendingRecord = {
+      ...(existing ?? {}), key, at: startedAt, startedAt, finishedAt: null, state: 'pending',
+      attempts: verdict.attempt, reason: verdict.reason,
+      fingerprint: current ?? null, previousFingerprint: previous ?? null,
+    }
+    writeStore({ records: upsertRecord(store.records, pendingRecord) }, file)
+    let result = null
+    const raced = await withTimeout(
+      Promise.resolve().then(() => scan({ current, previous, key })),
+      timeoutMs,
+    )
+    if (raced.timedOut) {
+      result = { ok: false, state: 'timeout', reason: `自动预检超过 ${timeoutMs}ms 未完成（已降级为「未完成，可手动重跑」，未阻塞状态查询）` }
+    } else if (raced.error !== undefined && raced.error !== null) {
+      result = { ok: false, state: 'failed', reason: `自动预检抛错：${raced.error}` }
+    } else {
+      const value = raced.value ?? {}
+      result = value.ok === false
+        ? { ok: false, state: 'failed', reason: value.reason ?? '自动预检未产出结论' }
+        : { ok: true, state: 'done', preflight: value }
+    }
+    const finishedAt = now()
+    const record = {
+      ...pendingRecord,
+      finishedAt,
+      state: result.state,
+      error: result.ok ? null : result.reason,
+      summary: result.ok ? (result.preflight?.summary ?? null) : null,
+      affected: result.ok ? (result.preflight?.affected ?? []) : [],
+      suspects: result.ok ? (result.preflight?.suspects ?? []) : [],
+      evidence: result.ok ? (result.preflight?.evidence ?? null) : null,
+      delta: result.ok ? (result.preflight?.delta ?? null) : null,
+      skipped: result.ok ? (result.preflight?.skipped ?? []) : [],
+    }
+    // 终态写盘：只 upsert 自己这条（读最新一份 + 只替换同 key），不覆盖别的指纹已经写好的结论
+    const after = readStore(file)
+    writeStore({ records: upsertRecord(after.records, record) }, file)
+    return { ok: result.ok, ran: true, key, state: result.state, record, error: result.ok ? null : result.reason, reason: verdict.reason }
+  } catch (error) {
+    return { ok: false, ran: false, key, state: 'failed', error: `自动预检记录写入失败：${error instanceof Error ? error.message : String(error)}` }
+  }
+}
+
+/**
+ * 状态查询下发的视图（**加法字段**，不改 `/compat-status` 既有字段）：
+ * 面板只需要一句短句 + 是否有结论 + 有几行受影响；长文（reasons/affected/delta）放在详情里。
+ */
+function autoPreflightView({ changed, current, records = null, file = autoPreflightFile() } = {}) {
+  const list = Array.isArray(records) ? records : readStore(file).records
+  // 指纹没变 → 不下发任何「上次的扫描结论」：那是上一个环境的结论，混在一起会让面板说假话。
+  const record = changed === true ? findRecord(list, current) : null
+  const state = record === null ? 'idle' : (STATES.includes(record.state) ? record.state : 'idle')
+  const preflight = record === null ? null : {
+    state: record.state ?? null,
+    startedAt: record.startedAt ?? null,
+    finishedAt: record.finishedAt ?? null,
+    attempts: record.attempts ?? 0,
+    error: record.error ?? null,
+    summary: record.summary ?? null,
+    affected: record.affected ?? [],
+    suspects: record.suspects ?? [],
+    skipped: record.skipped ?? [],
+    evidence: record.evidence ?? null,
+    delta: record.delta ?? null,
+  }
+  const blockers = (preflight?.affected ?? []).filter((a) => a.severity === 'blocker').length
+  return {
+    changed: changed === true,
+    state,
+    key: fingerprintKey(current),
+    ranAt: record?.startedAt ?? null,
+    scannedAt: record?.finishedAt ?? null,
+    blockers,
+    affectedCount: (preflight?.affected ?? []).length,
+    suspects: (preflight?.suspects ?? []).map((s) => s.rowId),
+    note: autoPreflightNote(state, { blockers, suspects: (preflight?.suspects ?? []).length }),
+    error: record?.error ?? null,
+    retryable: state === 'failed' || state === 'timeout',
+    preflight,
+  }
+}
+
+export {
+  DEFAULT_TIMEOUT_MS,
+  MAX_RECORDS,
+  STATES,
+  affectedRows,
+  autoPreflightFile,
+  autoPreflightNote,
+  autoPreflightView,
+  findRecord,
+  fingerprintKey,
+  planSuspectRows,
+  readStore,
+  runAutoPreflight,
+  sameFingerprint,
+  shouldAutoRun,
+  summarizeDelta,
+  upsertRecord,
+  withTimeout,
+  writeStore,
+}

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

@@ -17,6 +17,44 @@ const COMPAT_MODES = ['managed', 'observer']
 // 默认**观察者**（用户 2026-09-24 定）：只守门、不接管框架升级；一旦用户走了本控制台的框架升级，服务端会自动切回托管
 const DEFAULT_MODE = 'observer'
 
+/**
+ * 模式写入的**来源**（0.5.32 加法 D4；缺字段一律按 `manual` 兼容 —— 老记录等于"用户手动设定过"，永不自动改）：
+ *   · `manual`               用户在本控制台手动拨过（`POST /compat-mode`）→ 之后**永不自动改**
+ *   · `auto:console-upgrade` 走了本控制台的框架升级 → 自动切托管（可被桌面端启动拨回）
+ *   · `auto:desktop-host`    检测到桌面端宿主形态 → 自动切观察者
+ */
+const MODE_SOURCES = ['manual', 'auto:console-upgrade', 'auto:desktop-host']
+const DEFAULT_MODE_SOURCE = 'manual'
+
+/** 自动切换的判定（纯函数）：**只在"上次不是用户手动设定"时才自动改**。 */
+const AUTO_MODE_SOURCES = ['auto:console-upgrade', 'auto:desktop-host']
+
+/**
+ * 「桌面端宿主启动 → 自动拨回观察者」的判定（纯函数，加法 D4）。
+ * 规则（三条，全部可离线断言）：
+ *   ① 不是桌面端宿主 → 不动（`standalone` 实例的既有行为一字不改）；
+ *   ② 当前已经是 observer → 不动（**零写盘**：连 source 都不刷新）；
+ *   ③ 当前模式的来源是 `manual`（含缺字段的老记录）→ **不动**（用户手动优先，绝不抢用户意图）。
+ * @returns {{ action: 'none'|'switch-to-observer', mode: string, from: string, reason: string|null, note: {zh,en}|null }}
+ */
+function planDesktopHostSwitch(modeRecord, { hosted = false } = {}) {
+  const mode = typeof modeRecord?.mode === 'string' && COMPAT_MODES.includes(modeRecord.mode) ? modeRecord.mode : DEFAULT_MODE
+  const source = typeof modeRecord?.source === 'string' && MODE_SOURCES.includes(modeRecord.source) ? modeRecord.source : DEFAULT_MODE_SOURCE
+  if (hosted !== true) return { action: 'none', mode, from: source, reason: 'not-desktop-host', note: null }
+  if (mode === 'observer') return { action: 'none', mode, from: source, reason: 'already-observer', note: null }
+  if (!AUTO_MODE_SOURCES.includes(source)) return { action: 'none', mode, from: source, reason: 'user-set-manual', note: null }
+  return {
+    action: 'switch-to-observer',
+    mode: 'observer',
+    from: source,
+    reason: 'desktop-host-detected',
+    note: {
+      zh: '检测到桌面端托管，已切观察者：不接管框架升级',
+      en: 'Desktop host detected — switched to Observer: framework upgrades are not taken over',
+    },
+  }
+}
+
 const stateDir = () => join(dshHome(), 'plugin-console')
 const modeFile = () => join(stateDir(), 'compat-mode.json')
 const fingerprintFile = () => join(stateDir(), 'env-fingerprint.json')
@@ -36,25 +74,36 @@ function writeJson(path, value) {
 }
 
 /**
- * 读运行模式。**默认托管** —— 纯加法：没有设置过的机器行为与之前完全一致。
- * @returns {{ mode: string, at: number|null, source: 'file'|'default' }}
+ * 读运行模式。**默认观察者** —— 纯加法：没有设置过的机器行为与之前完全一致。
+ * `source` 缺字段（0.5.32 之前写下的记录）按 `manual` 兼容：视为用户手动设定过，绝不自动改。
+ * @returns {{ mode: string, at: number|null, source: 'manual'|'auto:console-upgrade'|'auto:desktop-host', reason: string|null, fileSource: 'file'|'default' }}
  */
 function readCompatMode() {
   const rec = readJson(modeFile())
   const mode = typeof rec?.mode === 'string' && COMPAT_MODES.includes(rec.mode) ? rec.mode : DEFAULT_MODE
-  return { mode, at: typeof rec?.at === 'number' ? rec.at : null, reason: typeof rec?.reason === 'string' ? rec.reason : null, source: rec === null ? 'default' : 'file' }
+  const source = typeof rec?.source === 'string' && MODE_SOURCES.includes(rec.source) ? rec.source : DEFAULT_MODE_SOURCE
+  return { mode, at: typeof rec?.at === 'number' ? rec.at : null, source, reason: typeof rec?.reason === 'string' ? rec.reason : null, fileSource: rec === null ? 'default' : 'file' }
 }
 
 /**
  * 写运行模式（只接受白名单值，避免拼错导致「模式静默失效」）。
- * @returns {{ ok: boolean, mode: string, error?: string }}
+ * **幂等零写盘**（0.5.32 加法 D4）：模式与来源都没变时一个字节都不写 —— 否则"桌面端每次启动都重写一份
+ * 状态文件"，而用户看不出任何区别（也破坏"已是 observer 时零写盘"的断言）。
+ * @returns {{ ok: boolean, mode: string, source: string, changed: boolean, error?: string }}
  */
 function writeCompatMode(mode, meta = {}) {
   if (typeof mode !== 'string' || !COMPAT_MODES.includes(mode)) {
-    return { ok: false, mode: readCompatMode().mode, error: `未知模式 ${String(mode)}（可选：${COMPAT_MODES.join(' / ')}）` }
+    const current = readCompatMode()
+    return { ok: false, mode: current.mode, source: current.source, changed: false, error: `未知模式 ${String(mode)}（可选：${COMPAT_MODES.join(' / ')}）` }
+  }
+  const source = typeof meta.source === 'string' && MODE_SOURCES.includes(meta.source) ? meta.source : DEFAULT_MODE_SOURCE
+  const reason = typeof meta.reason === 'string' ? meta.reason : null
+  const current = readCompatMode()
+  if (current.mode === mode && current.source === source && current.reason === reason && current.at !== null) {
+    return { ok: true, mode, source, changed: false }
   }
-  writeJson(modeFile(), { mode, at: Date.now(), reason: typeof meta.reason === 'string' ? meta.reason : null })
-  return { ok: true, mode }
+  writeJson(modeFile(), { mode, at: Date.now(), source, reason })
+  return { ok: true, mode, source, changed: true }
 }
 
 /**
@@ -124,4 +173,4 @@ function readRollbackRecord() {
   }
 }
 
-export { COMPAT_MODES, DEFAULT_MODE, compareFingerprint, computeFingerprint, readCompatMode, readFingerprint, readRollbackRecord, stampFingerprint, writeCompatMode }
+export { AUTO_MODE_SOURCES, COMPAT_MODES, DEFAULT_MODE, DEFAULT_MODE_SOURCE, MODE_SOURCES, compareFingerprint, computeFingerprint, planDesktopHostSwitch, readCompatMode, readFingerprint, readRollbackRecord, stampFingerprint, writeCompatMode }

package/lib/server/domain/compat.js

@@ -1,5 +1,5 @@
 // L1 · domain —— compat.js（框架兼容判定与适配门：设置 API 扫描 / 兼容门读写 / 待适配记录 / 隔离记录合并的前置部分 / 启动失败分析；分层 Step 6 从 lib/index.js 搬出，只搬移未改逻辑。注：detectCompat 等吃运行上下文的留到 Step 8）
-// 分组见 D:\dsh\dsh-plugin-hub-plan\architecture.zh.md 三
+// 分层分组：L1 · domain（边界由 tests/test-architecture-guard.mjs 断言）
 
 import { readFileSync, writeFileSync, readdirSync, mkdirSync, realpathSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
@@ -194,10 +194,13 @@ function writeCompatPending(payload) {
 
 /** 兼容门总开关（用户定案 2026-09-11）：用户可关掉自动行为，回到纯手动。
  *  autoDisable —— 升级前是否自动禁用判定不适配的行（关掉 = 只提示不动开关）
- *  autoDetect  —— 打开控制台时是否自动检测「已适配」（关掉 = 不显示可解锁提示） */
+ *  autoDetect  —— 打开控制台时是否自动检测「已适配」（关掉 = 不显示可解锁提示）
+ *  autoDisableOnEvidence —— 0.5.32 加法 D5：**指纹变化自动预检 / 启动失败记录**给出**确证证据**时
+ *    是否自动写 `disabled: true`（默认启用 = 按用户意图；关掉 = 只报告 + 等用户点「只禁可疑行」）。
+ *    它与 autoDisable 是两个独立开关：后者管"我们升级时"，前者管"别人升级 / 启动失败时"。 */
 const COMPAT_GATE_FILE = () => join(dshHome(), 'plugin-console', 'compat-gate.json')
 
-const COMPAT_GATE_DEFAULTS = { autoDisable: true, autoDetect: true, noticeMode: 'once-per-version' }
+const COMPAT_GATE_DEFAULTS = { autoDisable: true, autoDetect: true, autoDisableOnEvidence: true, noticeMode: 'once-per-version' }
 
 function readCompatGate() {
   try {
@@ -205,6 +208,7 @@ function readCompatGate() {
     return {
       autoDisable: raw?.autoDisable !== false,
       autoDetect: raw?.autoDetect !== false,
+      autoDisableOnEvidence: raw?.autoDisableOnEvidence !== false,
       // 兼容提示的展示模式（2026-09-28 加法）：非法/缺失一律回落默认，**不影响 supported 判定**
       noticeMode: NOTICE_MODES.includes(raw?.noticeMode) ? raw.noticeMode : DEFAULT_NOTICE_MODE,
     }

package/lib/server/domain/components.js

@@ -1,5 +1,5 @@
 // L1 · domain —— components.js（服务器组件：注册表 / 增删改 / 进程启停 / 状态 / 自启动；分层 Step 4 从 lib/index.js 搬出，只搬移未改逻辑）
-// 分组见 D:\dsh\dsh-plugin-hub-plan\architecture.zh.md 三
+// 分层分组：L1 · domain（边界由 tests/test-architecture-guard.mjs 断言）
 
 import { readFileSync, writeFileSync, mkdirSync } from 'node:fs'
 import { spawn } from 'node:child_process'

package/lib/server/domain/dep-source.js

@@ -11,7 +11,7 @@
 //   lock（删 lock / 清 node_modules / 换机 / CI）→ `ERR_PNPM_FETCH_404`，而报错指向 npm registry，
 //   用户根本联想不到是几周前面板安装改写造成的。
 //
-// 两条硬约束（本机真 pnpm 10.34.5 实测矩阵见 D:\dsh\dsh-plugin-hub-plan\refactor-bugs.zh.md 第 23 节）：
+// 两条硬约束（真 pnpm 10.34.5 实测矩阵见仓库外私有方案稿第 23 节）：
 //   ① 写回前必须确认「这个包的**这个版本**」在 registry 可解析，否则**绝不**写裸版本号；
 //   ② 不可解析时**也不能**写 tarball URL：pnpm 10 对 direct-URL 依赖只在冷缓存真下载时记 integrity，
 //      命中缓存重写 lock 时 resolution 里没有 integrity → `ERR_PNPM_MISSING_TARBALL_INTEGRITY`，

package/lib/server/domain/framework.js

@@ -1,5 +1,5 @@
 // L1 · domain —— framework.js（升级三件套的可搬部分：状态/备份路径、dsh 可执行文件定位、app boot 定位、容忍补丁、版本比较、重启前奏；分层 Step 6 从 lib/index.js 搬出，只搬移未改逻辑。注：detectFrameworkUpgrade / backupProfileSnapshot / currentFrameworkVersion 吃运行上下文，留到 Step 8）
-// 分组见 D:\dsh\dsh-plugin-hub-plan\architecture.zh.md 三
+// 分层分组：L1 · domain（边界由 tests/test-architecture-guard.mjs 断言）
 
 import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync, copyFileSync } from 'node:fs'
 import { execFile } from 'node:child_process'
@@ -27,6 +27,27 @@ const FRAMEWORK_STATE_FILE = () => join(dshHome(), 'plugin-console', 'framework-
 
 const FRAMEWORK_BACKUP_ROOT = () => join(dshHome(), 'plugin-console', 'framework-backups')
 
+/** npm 缓存下的 npx 缓存目录候选（**不写死盘符/用户名**）。
+ *  npm 的 cache 位置本来就是用户配置（把 cache 指到别的盘是常见做法），所以按 npm 自己的
+ *  配置来源读取：环境变量 npm_config_cache / NPM_CONFIG_CACHE，以及用户级 ~/.npmrc 的 `cache=`。
+ *  （原实现把开发机上某个盘符下的 `node_cache\_npx` 直接写进源码，随 npm 发给所有用户。） */
+function npmNpxCacheRoots() {
+  const roots = []
+  const push = (value) => {
+    if (typeof value !== 'string') return
+    const dir = value.trim().replace(/^["']|["']$/gu, '').replace(/^~(?=[\\/]|$)/u, homedir())
+    if (dir !== '') roots.push(join(dir, '_npx'))
+  }
+  for (const key of ['npm_config_cache', 'NPM_CONFIG_CACHE']) push(process.env[key])
+  try {
+    for (const line of readFileSync(join(homedir(), '.npmrc'), 'utf8').split(/\r?\n/u)) {
+      const hit = /^\s*cache\s*=\s*(.*?)\s*$/iu.exec(line)
+      if (hit) push(hit[1])
+    }
+  } catch {}
+  return roots
+}
+
 /** 定位 @deepseek-ai/dsh-app-boot（与 @deepseek-ai/dsh 同级）。 */
 function locateAppBootFile(baseUrl) {
   try {
@@ -35,15 +56,26 @@ function locateAppBootFile(baseUrl) {
     const candidate = join(dirname(dshPkg), 'dsh-app-boot', 'lib', 'index.js')
     if (existsSync(candidate)) return candidate
   } catch {}
+  // 缓存根一律由「环境变量 / 用户配置 / 用户目录」派生，**不含任何写死的盘符或开发机路径**：
+  //   · NODE_CACHE：npx 缓存根的可选覆盖（直接就是 _npx 那一层）
+  //   · npm_config_cache / ~/.npmrc 的 cache=：npm 自己配置的缓存根（下面挂 _npx）
+  //   · ~/.npm/_npx：npm/npx 的默认用户级缓存（POSIX 与 Windows 同一处）
+  //   · %LOCALAPPDATA%\node_cache\_npx：缓存被重定向到 LOCALAPPDATA 时的位置（仅 Windows 有意义）
+  // 原实现第一条写死开发机上的缓存绝对路径（某个盘符下的 node_cache\_npx），且 LOCALAPPDATA
+  // 缺失时会拼出**相对路径** 'node_cache/_npx'（相对 CWD）——两处都已去掉。
   const cacheRoots = [
     process.env.NODE_CACHE || '',
-    'D:\\node_cache\\_npx',
+    ...npmNpxCacheRoots(),
     join(homedir(), '.npm', '_npx'),
-    join(process.env.LOCALAPPDATA || '', 'node_cache', '_npx'),
+    process.env.LOCALAPPDATA ? join(process.env.LOCALAPPDATA, 'node_cache', '_npx') : '',
   ].filter(Boolean)
   for (const root of cacheRoots) {
     if (!existsSync(root)) continue
-    for (const entry of readdirSync(root, { withFileTypes: true })) {
+    // 读目录失败（权限/竞态）只跳过这一条候选，绝不抛给调用方——本函数的契约是
+    // 「定位不到就返回 null」（调用方据此如实报「dsh-app-boot 未找到」）。
+    let entries = []
+    try { entries = readdirSync(root, { withFileTypes: true }) } catch { continue }
+    for (const entry of entries) {
       if (!entry.isDirectory()) continue
       const candidate = join(root, entry.name, 'node_modules', '@deepseek-ai', 'dsh-app-boot', 'lib', 'index.js')
       if (existsSync(candidate)) return candidate
@@ -141,7 +173,7 @@ function checkpointFrameworkTree(fwRoot, destRoot) {
  *
  * 事故现场（官方桌面端实例，127.0.0.1:19387，20:28）：
  *   桌面端里 DSH host 是 **Electron 二进制**跑的 asar 内入口
- *   （`D:\dsh-desktop\DeepSeek Harness.exe --expose-internals …\app.asar\dsh\node_modules\@deepseek-ai\dsh-desktop-host\lib\index.js …`），
+ *   （`<桌面端安装目录>\DeepSeek Harness.exe --expose-internals …\app.asar\dsh\node_modules\@deepseek-ai\dsh-desktop-host\lib\index.js …`），
  *   不是 `node bin.js web`。我们的「重启服务 / 回滚 / 框架升级重启」那一套会
  *   `Stop-Process` 掉 host，然后 `Resolve-DshBin` 三种方式全找不到 bin.js
  *   （桌面端 profile 的 node_modules 里根本没有 `@deepseek-ai` 作用域）→ 拉不起来 →
@@ -212,6 +244,33 @@ function shellHostedRefusal(deps) {
   }
 }
 
+/**
+ * 非 Windows 平台的标准拒绝载荷（**纯数据，不碰 HTTP**）：路由层负责翻成响应。
+ * 返回 null = win32（放行，行为与旧实现一字不改）。
+ *
+ * 为什么必须拒绝（2026-09-29 改错）：一键升级/回滚通道整体建立在 Windows 机制上 ——
+ * `schtasks.exe` 计划任务（脱离服务进程树）+ PowerShell 脚本 + `Get-NetTCPConnection` 探端口。
+ * 非 Windows 上 execFile('schtasks.exe') 必然 ENOENT，而旧实现先 writeFileSync 一个
+ * 「脚本已通过 detached 启动」的状态文件、再去 exec 不存在的 powershell.exe，
+ * 最后**照样** `upgraded = true` 并回 `ok: true, steps: ['框架升级脚本已启动…']` ——
+ * 用户看到"已启动"，实际一个字节都没动（静默失败 + 假成功）。宁可明确说"不支持"。
+ */
+function platformUpgradeRefusal() {
+  if (process.platform === 'win32') return null
+  return {
+    error: '当前平台暂不支持「一键框架升级/回滚」：该通道依赖 Windows 计划任务（schtasks.exe）与 PowerShell',
+    details: {
+      code: 'unsupported-platform',
+      platform: process.platform,
+      manual: [
+        '手动升级框架：npm i -g @deepseek-ai/dsh@latest（用 npx 的实例：清掉 npx 缓存后重跑 npx @deepseek-ai/dsh web）',
+        '升级前请自行备份 profile 目录（~/.dsh/profiles/<profile>）与 cordis.patch.yml',
+        '升级完成后本控制台仍会自动：备份新版本配置快照、重打框架补丁（issue #5 容错）、给出适配提示',
+      ],
+    },
+  }
+}
+
 /**
  * 生成「拉起 DSH 服务」的 PowerShell 前导块（升级脚本 / 回滚脚本共用，v0.3.37 事故修复）。
  *
@@ -477,4 +536,4 @@ async function preflightDisableIncompatible({ ports, profileDir, patchPath, targ
   }
   return { disabled, skipped }
 }
-export { FRAMEWORK_STATE_FILE, FRAMEWORK_BACKUP_ROOT, SHELL_HOSTED_NOTICE, detectHostShape, shellHostedRefusal, cleanupStaleFwTasks, resolveDshBin, locateAppBootFile, applyFrameworkTolerancePatchOnce, resolveFrameworkRootNodeModules, checkpointFrameworkTree, relaunchPrelude, isVersionAtLeast, pickFrameworkTarget, resolveFrameworkUpgradePlan, currentFrameworkVersion, backupProfileSnapshot, detectFrameworkUpgrade, preflightDisableIncompatible }
+export { FRAMEWORK_STATE_FILE, FRAMEWORK_BACKUP_ROOT, SHELL_HOSTED_NOTICE, detectHostShape, shellHostedRefusal, platformUpgradeRefusal, cleanupStaleFwTasks, resolveDshBin, locateAppBootFile, applyFrameworkTolerancePatchOnce, resolveFrameworkRootNodeModules, checkpointFrameworkTree, relaunchPrelude, isVersionAtLeast, pickFrameworkTarget, resolveFrameworkUpgradePlan, currentFrameworkVersion, backupProfileSnapshot, detectFrameworkUpgrade, preflightDisableIncompatible }

package/lib/server/domain/install-job.js

@@ -1,6 +1,6 @@
 // L1 · domain —— install-job.js（安装任务编排：多通道安装 + 套装补丁 + 适配门 + 收尾）。
 // 分层 Step 8c-2 从 lib/index.js 搬出；形参由 ctx 收窄为 ports（调用方注入的窄接口），只搬移未改逻辑。
-// 分组见 D:\dsh\dsh-plugin-hub-plan\architecture.zh.md 三
+// 分层分组：L1 · domain（边界由 tests/test-architecture-guard.mjs 断言）
 
 import { readFileSync, existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'

package/lib/server/domain/install.js

@@ -1,5 +1,5 @@
 // L1 · domain —— install.js（插件安装/卸载全链路：pnpm / curl 手动 / GitHub Release 三通道 + 包盒校验 + 套装补丁完整性；分层 Step 5 从 lib/index.js 搬出，只搬移未改逻辑）
-// 分组见 D:\dsh\dsh-plugin-hub-plan\architecture.zh.md 三
+// 分层分组：L1 · domain（边界由 tests/test-architecture-guard.mjs 断言）
 
 import { readFileSync, writeFileSync, existsSync, rmSync, readdirSync, mkdirSync } from 'node:fs'
 import { readFile, writeFile } from 'node:fs/promises'

package/lib/server/domain/jobs.js

@@ -1,5 +1,5 @@
 // L1 · domain —— jobs.js（任务辅助：日志追加 + 健康等待轮询）。方案原稿把 jobLog 归 ai.js、waitHealth 归 components.js，但这俩是 install / suite / ai 三个域共用的，埋在任何一个域里都会造成跨域反向依赖 —— 故单独成模块（偏离已记录）
-// 分组见 D:\dsh\dsh-plugin-hub-plan\architecture.zh.md 三
+// 分层分组：L1 · domain（边界由 tests/test-architecture-guard.mjs 断言）
 
 
 function jobLog(job, line) {

package/lib/server/domain/market.js

@@ -1,5 +1,5 @@
 // L1 · domain —— market.js（分层 Step 从 lib/index.js 搬出，只搬移未改逻辑）
-// 分组见 D:\dsh\dsh-plugin-hub-plan\architecture.zh.md §三
+// 分层分组：L1 · domain（边界由 tests/test-architecture-guard.mjs 断言）
 
 import { readFileSync, writeFileSync, mkdirSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'