@noob-stupid/dsh-plugin-console 0.5.31 → 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

@@ -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/patch-yaml-check.js

@@ -0,0 +1,151 @@
+// L1 · domain —— patch-yaml-check.js（`cordis.patch.yml` 的**结构校验**；0.5.32 加法 D3）
+//
+// 为什么不能直接复用 `domain/preset-yaml.js#validateAgentConfig`（**真机实测**，2026-09-29）：
+//   那把尺子是按 **agent 预设文件**（顶层 `- id:` 序列）校准的，拿它量真机补丁会**整片误杀**：
+//   两个 live profile 的 `cordis.patch.yml`（web 56 KB / desktop 55 KB）实测各被判 17 / 12 条问题，
+//   全部是**合法写法**：
+//     · `description: '第一行…` + 后续行 `  续行…'` —— YAML 的**多行引号标量**（跨行合法），
+//       逐行判「引号未闭合」→ 假红；
+//     · 续行缩进比父级深 → 逐行判「缩进跳级/文件被截断」→ 假红。
+//   误杀的代价在这里同样是反向的：D3 的恢复入口拿它当写盘前闸门 → **一恢复就被自家校验拒掉**。
+//
+// 所以这里只钉**能确证损坏**的形态（全部离线可判定，且对真机补丁 0 误报）：
+//   ① 行首缩进里有 **tab** —— YAML 明确禁止用 tab 缩进（框架解析器必然报错）；
+//   ② **顶层空数组占位符 `[]`**（issue #7 事故形态）：模板初始化的 `[]` 后面再追加 `- id:` 条目，
+//      同一文档流里「数组结束符 + 后续项」= 非法 YAML → dsh 启动直接崩；
+//   ③ 顶层（缩进 0）出现**不是** `- ` 序列项的行（既不是注释/空行/占位符）—— 补丁文件的形状是
+//      「序列项 + 其子键」，顶层键值对说明文件被拼坏/截断；
+//   ④ **多行引号标量未闭合**（真正的截断）：跨行扫描引号状态，直到文件末尾仍未闭合才判红
+//      —— 这一条恰好是②之外最常见的"写坏"形态；
+//   ⑤ 块标量（`|` / `>`）整段跳过判据（其内容是散文，不是 YAML 结构）。
+//
+// 分层：L1 domain —— 纯函数、无 IO、永不抛（解析失败是正常结局，调用方按 ok=false 处理）。
+
+/** 缩进宽度（空格数；tab 会在 ① 里单独判掉，不参与计数）。 */
+function indentWidth(line) {
+  const m = String(line).match(/^ */u)
+  return m === null ? 0 : m[0].length
+}
+
+/** 行首缩进里有没有 tab（YAML 禁止；框架解析器会直接报错）。 */
+function hasTabIndent(line) {
+  return /^[ \t]*\t/u.test(String(line))
+}
+
+/** 剥掉行尾注释（只认**不在引号里**且 `#` 前有空白或行首的 `#`）。 */
+function stripTrailingComment(line) {
+  const text = String(line)
+  let quote = null
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i]
+    if (quote !== null) {
+      if (quote === '"' && ch === '\\') { i += 1; continue }
+      if (ch === quote) quote = null
+      continue
+    }
+    if (ch === "'" || ch === '"') { quote = ch; continue }
+    if (ch === '#' && (i === 0 || /\s/u.test(text[i - 1]))) return text.slice(0, i)
+  }
+  return text
+}
+
+/** 块标量指示符（`|`、`>`、`|-`、`>+2`…）：只有**整个值**就是指示符时才算（`> foo` 是普通标量）。 */
+function blockScalarIndicator(value) {
+  const m = String(value).trim().match(/^([|>])([+-]?\d*|\d*[+-]?)$/u)
+  return m === null ? null : m[0]
+}
+
+/**
+ * 从一行里取出「值起点之后的引号状态」：
+ *   · 值不以引号开头 → `{ opens: false, quote: null }`（引号在标量中间不算跨行开始）；
+ *   · 以单/双引号开头 → 逐字符推进（双引号吃 `\\` 转义，单引号吃 `''`），返回是否仍未闭合。
+ */
+function scanValueQuotes(value, initialQuote = null) {
+  const text = String(value)
+  let quote = initialQuote
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i]
+    if (quote === null) {
+      if (ch === "'" || ch === '"') quote = ch
+      continue
+    }
+    if (quote === '"' && ch === '\\') { i += 1; continue }
+    if (ch === quote) {
+      if (quote === "'" && text[i + 1] === "'") { i += 1; continue }
+      quote = null
+    }
+  }
+  return { quote }
+}
+
+/**
+ * 结构校验（**纯函数**，永不抛）。返回 `{ ok, problems, summary }`。
+ * `summary` 只放"看得懂的事实"（行数 / 顶层项数 / 多行标量数），供报告与面板短句使用。
+ */
+function validatePatchYaml(text) {
+  const source = typeof text === 'string' ? text : String(text ?? '')
+  const lines = source.replace(/\r\n/gu, '\n').split('\n')
+  const problems = []
+  let topItems = 0
+  let multilineScalars = 0
+  let placeholderLines = 0
+  let inBlockScalar = false
+  let blockIndent = 0
+  let openQuote = null
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const raw = lines[i]
+    const lineNo = i + 1
+    if (raw.trim() === '') continue
+    if (/^\s*#/u.test(raw)) continue
+    // ① tab 缩进（无论在哪一层都不合法）
+    if (hasTabIndent(raw)) { problems.push(`第 ${lineNo} 行的缩进里有 tab（YAML 禁止用 tab 缩进）`); continue }
+    const indent = indentWidth(raw)
+    // 多行引号标量的续行：内容不参与结构判定，只继续找闭合
+    if (openQuote !== null) {
+      multilineScalars += 1
+      const st = scanValueQuotes(raw, openQuote)
+      openQuote = st.quote
+      continue
+    }
+    // 块标量内容：整段跳过（缩进 ≤ 块首行缩进的非空行 = 块结束）
+    if (inBlockScalar) {
+      if (indent > blockIndent) continue
+      inBlockScalar = false
+    }
+    const content = stripTrailingComment(raw)
+    if (content.trim() === '') continue
+    // ② 顶层空数组占位符（issue #7：`[]` 后面再跟条目 = 非法 YAML，启动直接崩）
+    if (/^\s*\[\s*\]\s*$/u.test(content)) { placeholderLines += 1; continue }
+    // ③ 顶层必须是序列项（补丁文件的形状：`- id:` / `- insert:` + 其子键）
+    if (indent === 0) {
+      if (!/^-\s/u.test(content) && content.trim() !== '-') {
+        problems.push(`第 ${lineNo} 行是顶层键值对（补丁文件顶层必须是 \`- \` 序列项）：${content.trim().slice(0, 60)}`)
+        continue
+      }
+      topItems += 1
+    }
+    // ④ / ⑤ 值里的块标量与跨行引号
+    const kv = content.match(/^(\s*)(?:-\s+)?[^\s:#][^:]*:\s*(.*)$/u)
+    if (kv === null) continue
+    const value = kv[2].trim()
+    if (blockScalarIndicator(value) !== null) { inBlockScalar = true; blockIndent = indent; continue }
+    const st = scanValueQuotes(value, null)
+    if (st.quote !== null) openQuote = st.quote
+  }
+  // ④ 收尾：跨行引号到文件末尾仍未闭合 = 真截断
+  if (openQuote !== null) {
+    problems.push(`文件末尾仍有未闭合的引号（${openQuote === "'" ? '单引号' : '双引号'}）—— 文件被截断或写坏`)
+  }
+  // ② 收尾：占位符与真实条目共存（真实事故形态）
+  if (placeholderLines > 0 && topItems > 0) {
+    problems.push(`顶层空数组占位符 \`[]\` 与 ${topItems} 个序列项共存（同一文档流非法，框架解析会崩）—— 写入前必须移除占位符`)
+  }
+  return {
+    ok: problems.length === 0,
+    problems,
+    summary: { lines: lines.length, topItems, multilineScalars, placeholderLines },
+  }
+}
+
+export { blockScalarIndicator, hasTabIndent, indentWidth, scanValueQuotes, stripTrailingComment, validatePatchYaml }