@noob-stupid/dsh-plugin-console 0.5.31 → 0.5.33

package/lib/server/domain/settings-api-scan.js

@@ -0,0 +1,251 @@
+// L1 · domain —— settings-api-scan.js（「已删除 dsh-settings API」源码扫描；0.5.33 改错时从 compat.js 搬出）
+// 分层分组：L1 · domain（边界由 tests/test-architecture-guard.mjs 断言）
+//
+// 为什么单独成模块：判据从"源码里出现过这个名字"改成"这个名字**真的从
+// `@deepseek-ai/dsh-settings` 绑定进来**"——要先剥注释/字符串字面量，再解析 import/require 的
+// 绑定子句，逻辑比原先的按行子串匹配长得多，而 compat.js 已经 544 行（守卫上限 600）。
+// 搬移保持对外契约不变：`REMOVED_SETTINGS_SYMBOLS` / `referencesRemovedSymbol` /
+// `scanSettingsApiUsage` 三个名字照旧由 compat.js 导出。
+//
+// ── 0.5.33 改错（真机误报，证据充分）────────────────────────────────────────────────
+// 现症：`dshmarket` 被判 `check:'fail'`（= 「源码仍引用 0.1.2 起已删除的 dsh-settings API」），
+// 于是**框架升级预扫会把这个好插件自动禁用**。逐条核对它的三处命中：
+//   · dshmarket/lib/settings.js:45 / :53 / :73 —— 全在**注释**里；
+//   · dshmarket/lib/routes.js:3136 `settingsNamespace: settingsNamespaceState(),` —— 一个
+//     **HTTP 载荷对象的属性名**（值是自己的局部函数 `settingsNamespaceState`，与本包无关）；
+//   · 该包对 `@deepseek-ai/dsh-settings` 的 **import 零命中**（它早已把那两个 helper 内联）。
+// 旧判据（`text.includes(sym)` → v0.3.35 换成标识符边界 + 排除局部定义）挡不住这两类：
+// 注释里的名字与对象键上的名字都不是"引用"，但它们都在**代码行**上、也不是本地定义。
+//
+// 新判据（更严格，不放宽任何真引用）：
+//   ① 先掩掉注释、字符串/模板字面量、正则字面量（等长空格替换，保留换行与列偏移）；
+//      唯一保留的是**模块说明符字符串**（`from 'x'` / `require('x')` / `import('x')`），
+//      否则没法知道某个绑定来自哪个包。
+//   ② 只在**真的对这个包**的 import/require 绑定子句里取名字：
+//      `import { settingsNamespace } from '@deepseek-ai/dsh-settings'`、
+//      `import settingsNamespace from …`、`import * as s from …` 后的 `s.settingsNamespace`、
+//      `const { settingsNamespace } = require('@deepseek-ai/dsh-settings')`、
+//      `const { installSettingsSection } = await import('@deepseek-ai/dsh-settings')`。
+//   ③ 对象键、局部同名函数、别的模块的同名导入、注释与字符串里的名字 —— 一律不算。
+
+import { readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** 0.1.2-rc.1 起被官方删除的 dsh-settings API（命中即"实际不兼容"）。 */
+const REMOVED_SETTINGS_SYMBOLS = ['settingsNamespace', 'installSettingsSection']
+
+/** 这些 API 原本来自哪个包（只有真的从它绑定进来的名字才算引用）。 */
+const SETTINGS_MODULE = '@deepseek-ai/dsh-settings'
+
+const SPECIFIER_RE = `['"]${SETTINGS_MODULE.replace(/[/\\^$*+?.()|[\]{}]/gu, '\\$&')}['"]`
+
+/**
+ * 把注释、字符串/模板字面量、正则字面量掩成**等长空格**（换行/回车保留，行号与列偏移不变）。
+ * `keepSpecifier` 为真时保留"模块说明符"字符串的原样内容（`from 'x'` / `require('x')` / `import('x')`）。
+ *
+ * 这是**掩码**而不是删除：后续判据仍然按整份源码做正则，位置对得上才好排查。
+ */
+function maskLiterals(text, keepSpecifier) {
+  const src = String(text ?? '')
+  const out = src.split('')
+  const blank = (from, to) => {
+    for (let k = from; k < to; k += 1) if (out[k] !== '\n' && out[k] !== '\r') out[k] = ' '
+  }
+  const isWordChar = (ch) => ch !== undefined && /[A-Za-z0-9_$]/u.test(ch)
+  const wordBefore = (index) => {
+    let j = index
+    while (j > 0 && (src[j - 1] === ' ' || src[j - 1] === '\t')) j -= 1
+    let k = j
+    while (k > 0 && isWordChar(src[k - 1])) k -= 1
+    return src.slice(k, j)
+  }
+  const prevMeaningful = (index) => {
+    for (let k = index - 1; k >= 0; k -= 1) {
+      const ch = src[k]
+      if (ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r') continue
+      return ch
+    }
+    return ''
+  }
+  /** 当前位置若是 `word(` 的第一个实参，返回 `word`（用于 require(...) / import(...) 的说明符判定）。 */
+  const callWordBefore = (index) => {
+    let k = index - 1
+    while (k >= 0 && (src[k] === ' ' || src[k] === '\t')) k -= 1
+    if (k < 0 || src[k] !== '(') return ''
+    k -= 1
+    while (k >= 0 && (src[k] === ' ' || src[k] === '\t')) k -= 1
+    const end = k + 1
+    while (k >= 0 && isWordChar(src[k])) k -= 1
+    return src.slice(k + 1, end)
+  }
+  // 正则字面量的判定沿用仓库既有启发式（tests/test-architecture-guard.mjs 的 stripCode 同款）：
+  // 前一个有效字符说明这里不可能是除法，或者前一个词是 return/typeof 这类关键字。
+  const REGEX_PREV = new Set(['(', ',', '=', ':', '[', '!', '&', '|', '?', '{', '}', ';', '\n', ''])
+  const REGEX_KEYWORDS = new Set(['return', 'typeof', 'case', 'in', 'of', 'do', 'else', 'void', 'delete', 'new', 'instanceof', 'yield', 'await'])
+  let i = 0
+  while (i < src.length) {
+    const c = src[i]
+    const n = src[i + 1]
+    if (c === '/' && n === '/') {
+      const end = src.indexOf('\n', i)
+      const to = end < 0 ? src.length : end
+      blank(i, to)
+      i = to
+      continue
+    }
+    if (c === '/' && n === '*') {
+      const end = src.indexOf('*/', i + 2)
+      const to = end < 0 ? src.length : end + 2
+      blank(i, to)
+      i = to
+      continue
+    }
+    if (c === "'" || c === '"' || c === '`') {
+      let j = i + 1
+      while (j < src.length && src[j] !== c) {
+        if (src[j] === '\\') j += 1
+        j += 1
+      }
+      const end = j < src.length ? j + 1 : src.length
+      // 说明符字符串保留：紧跟在 `from` 之后，或作为 require(...) / import(...) 的第一个实参。
+      const asCallArgument = /^(?:require|import)$/u.test(callWordBefore(i))
+      const isSpecifier = keepSpecifier === true && c !== '`' && (wordBefore(i) === 'from' || asCallArgument)
+      if (!isSpecifier) blank(i + 1, end - 1)
+      i = end
+      continue
+    }
+    if (c === '/') {
+      const pm = prevMeaningful(i)
+      if (REGEX_PREV.has(pm) || REGEX_KEYWORDS.has(wordBefore(i))) {
+        let j = i + 1
+        let inClass = false
+        while (j < src.length) {
+          const ch = src[j]
+          if (ch === '\\') { j += 2; continue }
+          if (ch === '[') inClass = true
+          else if (ch === ']') inClass = false
+          else if (ch === '/' && !inClass) { j += 1; break }
+          else if (ch === '\n') break
+          j += 1
+        }
+        blank(i, j)
+        i = j
+        continue
+      }
+    }
+    i += 1
+  }
+  return out.join('')
+}
+
+/** 从一个绑定子句里取出**被导入的名字**（`a as b` 取 `a`；默认导入取它自己；`*` 交给命名空间那条路）。 */
+function importedNamesOf(clause) {
+  const names = new Set()
+  const text = String(clause ?? '')
+  const brace = text.match(/\{([^}]*)\}/u)
+  if (brace !== null) {
+    for (const part of brace[1].split(',')) {
+      const seg = part.trim()
+      if (seg === '') continue
+      const imported = seg.split(/\s+as\s+/u)[0].trim()
+      if (/^[A-Za-z_$][\w$]*$/u.test(imported)) names.add(imported)
+    }
+  }
+  const rest = brace === null ? text : text.replace(brace[0], ' ')
+  for (const seg of rest.split(',')) {
+    const t = seg.trim()
+    if (t === '' || t === '*' || /\s/u.test(t)) continue
+    if (/^[A-Za-z_$][\w$]*$/u.test(t)) names.add(t)
+  }
+  return names
+}
+
+/**
+ * 从源码里取出「真的从 `@deepseek-ai/dsh-settings` 绑定进来的名字」。
+ * 返回 `{ named, namespaces }`：`named` 是直接绑定的符号，`namespaces` 是包级命名空间
+ * （`import * as s` / `const s = require(…)`），它们的成员访问 `s.settingsNamespace` 也算引用。
+ */
+function settingsApiBindings(text) {
+  // 掩码只做一次：注释/字符串/正则变空格，模块说明符字符串保留 —— 判据据此认包。
+  const code = maskLiterals(text, true)
+  const named = new Set()
+  const namespaces = new Set()
+  // ① ESM 命名空间导入：`import * as s from '<mod>'`
+  for (const m of code.matchAll(new RegExp(`\\bimport\\s*\\*\\s*as\\s+([A-Za-z_$][\\w$]*)\\s+from\\s*${SPECIFIER_RE}`, 'gu'))) {
+    namespaces.add(m[1])
+  }
+  // ② ESM 具名/默认导入：`import { a, b as c } from '<mod>'` / `import d from '<mod>'`
+  //    子句里不允许再出现 import/from，长度封顶 2000 —— 挡住"跨到上一条 import 语句"的假匹配。
+  for (const m of code.matchAll(new RegExp(`\\bimport\\s+(?!\\*)((?:(?!\\bimport\\b|\\bfrom\\b)[\\s\\S]){0,2000}?)\\s+from\\s*${SPECIFIER_RE}`, 'gu'))) {
+    for (const name of importedNamesOf(m[1])) named.add(name)
+  }
+  // ③ CJS / 动态导入的解构绑定：`const { a } = require('<mod>')` / `= await import('<mod>')`
+  const callRe = `(?:require|import)\\s*\\(\\s*${SPECIFIER_RE}\\s*\\)`
+  for (const m of code.matchAll(new RegExp(`(?:const|let|var)\\s*\\{([^}]*)\\}\\s*=\\s*(?:await\\s+)?${callRe}`, 'gu'))) {
+    for (const name of importedNamesOf(`{${m[1]}}`)) named.add(name)
+  }
+  // ④ CJS / 动态导入的命名空间绑定：`const s = require('<mod>')`
+  for (const m of code.matchAll(new RegExp(`(?:const|let|var)\\s+([A-Za-z_$][\\w$]*)\\s*=\\s*(?:await\\s+)?${callRe}`, 'gu'))) {
+    namespaces.add(m[1])
+  }
+  return { named, namespaces }
+}
+
+/** 命中的已删除符号列表（空数组 = 干净）。判据见文件头：只有真绑定/真成员访问才算。 */
+function settingsApiReferences(text) {
+  const { named, namespaces } = settingsApiBindings(text)
+  const found = []
+  for (const sym of REMOVED_SETTINGS_SYMBOLS) {
+    if (named.has(sym)) { found.push(sym); continue }
+    for (const ns of namespaces) {
+      if (new RegExp(`(?<![\\w$.])${ns}\\s*\\.\\s*${sym}(?![\\w$])`, 'u').test(maskLiterals(text, true))) { found.push(sym); break }
+    }
+  }
+  return found
+}
+
+/** 源码是否**引用**了某个已删除符号（对外契约不变；判据已收紧到"真绑定/真成员访问"）。 */
+function referencesRemovedSymbol(text, sym) {
+  return settingsApiReferences(text).includes(sym)
+}
+
+/**
+ * 扫描已安装包源码，检测对已删除的 dsh-settings API 的引用。
+ *
+ * 2026-09-04 教训：0.1.2-rc.1 起 settingsNamespace / installSettingsSection 已删除，
+ * 静态声明检查判 pass 是假通过；真实兼容性只有模块 import 时见分晓，而 loader 单行失败
+ * = 整个服务启动崩溃。
+ *
+ * 扫描预算（未改）：限深 3 层、上限 120 个文件、单文件读前 400KB。
+ */
+function scanSettingsApiUsage(pkgDir) {
+  const found = []
+  const seen = new Set()
+  const walk = (dir, depth) => {
+    if (depth > 3) return
+    let entries = []
+    try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return }
+    for (const entry of entries) {
+      const full = join(dir, entry.name)
+      if (entry.isDirectory()) {
+        if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue
+        walk(full, depth + 1)
+        continue
+      }
+      if (!entry.isFile() || !/\.(?:js|mjs|cjs)$/u.test(entry.name)) continue
+      if (seen.has(full)) continue
+      seen.add(full)
+      if (seen.size > 120) return
+      try {
+        const text = readFileSync(full, 'utf8').slice(0, 400000)
+        for (const sym of settingsApiReferences(text)) {
+          if (!found.includes(sym)) found.push(sym)
+        }
+      } catch {}
+    }
+  }
+  walk(pkgDir, 0)
+  return found
+}
+
+export { REMOVED_SETTINGS_SYMBOLS, SETTINGS_MODULE, maskLiterals, settingsApiBindings, settingsApiReferences, referencesRemovedSymbol, scanSettingsApiUsage }

package/lib/server/routes/compat.js

@@ -8,20 +8,45 @@
 // 触发源不再是我们的升级按钮，而是环境指纹变化 —— 官方桌面端自带升级器 / 官方只发桌面端 /
 // 手动 pnpm 操作，都会在这里被发现（见 domain/compat-state.js 头注释）。
 //
+// 0.5.32 加法（用户 2026-09-29 诉求「走别的更新通道改了框架后仍要自动守门 / 能挽救改完打不开」）：
+//   · D1：指纹变化 → **自动跑一次只读预检**（不下载/不安装/不改补丁），落成「兼容清单 + 隔离计划 +
+//         变更摘要」；同一指纹只自动跑一次（以指纹为 key 持久化），失败/超时如实记录且可重试，
+//         **绝不阻塞状态查询**（超时降级为「未完成，可手动重跑」）；
+//   · D2：每次确认服务正常（状态查询成功 + 指纹未变 + 补丁结构合法）落一份 last-known-good 快照到
+//         `dshHome()/plugin-console/safe-boot/`（**不是** profile 目录），原子写 + sha256 + 保留 N 份；
+//   · D4：检测到桌面端宿主形态时，把**非用户手动设定**的运行模式自动拨回观察者（用户手动优先）。
+//
 // declare-installed 存在的理由（2026-09-24 用户实测）：第三方插件管理器与 pnpm 都只认清单里的
 // 依赖，手铺安装的包在它们眼里不存在（看不见 + 会被还原）。老规矩：先 plan 再 apply。
 
-import { dirname } from 'node:path'
-import { compareFingerprint, computeFingerprint, readCompatMode, readFingerprint, readRollbackRecord, stampFingerprint, writeCompatMode } from '../domain/compat-state.js'
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { applyEvidenceDisable } from '../domain/auto-disable.js'
+import { DEFAULT_TIMEOUT_MS, autoPreflightView, runAutoPreflight } from '../domain/auto-preflight.js'
+import { runAutoPreflightScan } from '../domain/auto-preflight-run.js'
 import { NOTICE_MODES, detectCompat, readCompatAck, readCompatGate, writeCompatAck, writeCompatGate } from '../domain/compat.js'
-import { currentFrameworkVersion } from '../domain/framework.js'
+import { compareFingerprint, computeFingerprint, planDesktopHostSwitch, readCompatMode, readFingerprint, readRollbackRecord, stampFingerprint, writeCompatMode } from '../domain/compat-state.js'
+import { currentFrameworkVersion, detectHostShape } from '../domain/framework.js'
 import { applyDependencyBackfill, planDependencyBackfill } from '../domain/manifest.js'
-import { preferredRegistries } from '../domain/sources.js'
+import { isProtectedModule } from '../domain/runtime.js'
+import { listSnapshots, readSafeBootState, validatePatchYaml, writeSnapshot } from '../domain/safe-boot.js'
 import { reconcileLockfile } from '../domain/selfupdate.js'
+import { listEntries } from '../domain/runtime.js'
+import { preferredRegistries } from '../domain/sources.js'
 import { sendError, sendJson } from '../infra/httpd.js'
-import { baseDirOf, profileDirOf, resolvePackageJson } from '../infra/paths.js'
-import { existsSync } from 'node:fs'
-import { join } from 'node:path'
+import { baseDirOf, dshHome, findPatchPath, pluginRoot, profileDirOf, resolvePackageJson } from '../infra/paths.js'
+import { preflightRoots } from './framework-preflight.js'
+
+const PREFLIGHT_TIMEOUT_ENV = 'DSH_AUTO_PREFLIGHT_TIMEOUT_MS'
+/** 自动预检的预算：到点降级成「未完成，可手动重跑」，状态查询照常返回（env 可调）。 */
+function preflightTimeoutMs() {
+  const raw = Number(process.env[PREFLIGHT_TIMEOUT_ENV])
+  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_TIMEOUT_MS
+}
+
+function pluginVersionOf() {
+  try { return JSON.parse(readFileSync(join(pluginRoot(), 'package.json'), 'utf8')).version ?? null } catch { return null }
+}
 
 /** 框架运行时根（含 .pnpm 的那层）：换了安装根（npx 缓存 ↔ 桌面端自带运行时）指纹必变。
  *  `@deepseek-ai/dsh` 既可能解析到 `<root>/node_modules/@deepseek-ai/dsh`（顶层投影），
@@ -60,28 +85,217 @@ function currentFingerprint(rc) {
   })
 }
 
+/** 桌面端宿主形态（复用既有判据 `detectHostShape`；`rc.deps` 可注入替身，生产路径即真判据）。 */
+function hostShapeOf(rc) {
+  const detect = rc?.deps?.detectHostShape ?? detectHostShape
+  try { return detect() } catch { return { hosted: false, kind: 'standalone', reasons: [] } }
+}
+
+/** D4 只在「启动 / 首次状态查询」判定一次（与用户要求的触发时机一致）；之后的状态查询不重复判定。
+ *  `resetHostSwitchChecked()` 只给测试用：让"首次判定"这件事可被独立驱动（生产路径不调用它）。 */
+let hostSwitchChecked = false
+function resetHostSwitchChecked() { hostSwitchChecked = false }
+
+/** D4：桌面端宿主启动 → 非用户手动设定的模式自动拨回观察者（幂等；已是 observer 时零写盘）。 */
+function maybeSwitchToObserver(rc, { force = false } = {}) {
+  if (hostSwitchChecked && force !== true) return { switched: false, reason: 'already-checked', note: null }
+  hostSwitchChecked = true
+  try {
+    const current = readCompatMode()
+    const verdict = planDesktopHostSwitch(current, { hosted: hostShapeOf(rc).hosted === true })
+    if (verdict.action !== 'switch-to-observer') return { switched: false, reason: verdict.reason, note: null }
+    const written = writeCompatMode('observer', { source: 'auto:desktop-host', reason: verdict.note.zh })
+    return { switched: written.ok === true && written.changed === true, reason: verdict.reason, note: verdict.note }
+  } catch (error) {
+    return { switched: false, reason: `判定失败：${error instanceof Error ? error.message : String(error)}`, note: null }
+  }
+}
+
+/**
+ * D1：指纹变化 → 后台跑一次只读预检（**不 await**：状态查询该返回什么还返回什么）。
+ * 节流闸门在 `runAutoPreflight` 内部**同步**写下的 pending 占位 —— 同指纹的第二次查询会看到
+ * pending/done，因此「同一指纹只自动跑一次」与「绝不阻塞」两件事同时成立。
+ */
+function scheduleAutoPreflight(rc, { current, previous, reasons, profileDir, patchPath }) {
+  const scan = rc?.deps?.autoPreflightScan ?? runAutoPreflightScan
+  let roots = []
+  const entries = (() => { try { return listEntries(rc.ctx) } catch { return [] } })()
+  try { roots = preflightRoots(rc.ctx, profileDir, { listEntries: () => entries, resolvePackageJson, pluginRoot }) } catch { roots = [] }
+  const timeoutMs = preflightTimeoutMs()
+  void runAutoPreflight({
+    current,
+    previous,
+    timeoutMs,
+    scan: ({ current: cur, previous: prev }) => scan({
+      profileDir,
+      patchPath,
+      current: cur,
+      previous: prev,
+      presetRoots: [join(dshHome(), '.agent-presets')],
+      roots,
+      reasons,
+      previousPackages: [],
+      networkAllowed: false,
+    }),
+  }).then((result) => {
+    // D5：预检**出结论之后**再看要不要自动禁用（有确证证据 + 开关开着 → 禁前快照 → 写盘 → 留记录）
+    if (result?.ok === true && result.record !== null && result.record !== undefined) maybeAutoDisable({ rc, current, previous, reasons, patchPath, record: result.record })
+  }).catch(() => {})
+  return { scheduled: true, timeoutMs, roots: roots.length }
+}
+
+/**
+ * D5 的接线：把 D1 预检结论里的**确证证据**交给自动禁用入口（`domain/auto-disable.js`）。
+ * 开关（`compat-gate.json#autoDisableOnEvidence`，默认启用）关闭时只记录候选、不写盘。
+ * 结果**只留在内存里给下一次状态查询用**（一次性提示；不新增任何常驻 UI/文件）。
+ */
+let lastAutoDisable = null
+function maybeAutoDisable({ rc, current, previous, reasons, patchPath, record }) {
+  try {
+    const evidence = record.evidence ?? null
+    const hasEvidence = Array.isArray(evidence?.rows) && evidence.rows.some((r) => r.code === 'package-unresolvable' || r.code === 'file-target-missing')
+    const hasBoot = Array.isArray(evidence?.bootRows) && evidence.bootRows.length > 0
+    if (!hasEvidence && !hasBoot) return null
+    if (typeof patchPath !== 'string' || patchPath === '' || !existsSync(patchPath)) return null
+    const gate = readCompatGate()
+    const plan = rc?.deps?.autoDisableApply ?? applyEvidenceDisable
+    const result = plan({
+      patchPath,
+      affected: Array.isArray(evidence?.rows) ? evidence.rows : [],
+      bootRows: Array.isArray(evidence?.bootRows) ? evidence.bootRows : [],
+      enabled: gate.autoDisableOnEvidence === true,
+      uncertainty: evidence?.uncertainty ?? null,
+      fingerprint: current,
+      frameworkVersion: current?.frameworkVersion ?? null,
+      reasons,
+      isProtected: isProtectedModule,
+    })
+    lastAutoDisable = { at: Date.now(), snapshotId: result?.snapshot?.id ?? null, ...result }
+    return result
+  } catch (error) {
+    lastAutoDisable = { at: Date.now(), ok: false, disabled: [], error: error instanceof Error ? error.message : String(error) }
+    return null
+  }
+}
+
+/** 一次性提示文案（中英双语短句；**不新增常驻 UI**：由客户端沿用既有的瞬时 note 通道显示）。
+ *  ★ 开关是**读时判据**：关掉之后，之前那次"已自动禁用 N 行"的提示**不许再冒出来**
+ *    （否则用户会以为刚又被禁了一次；实测就是这么发现的）。 */
+function autoDisableNotice(entry = lastAutoDisable, { enabled = null } = {}) {
+  const on = enabled === null ? readCompatGate().autoDisableOnEvidence === true : enabled === true
+  if (entry === null || entry === undefined) return null
+  if (on !== true && entry.code === 'auto-disabled') return null
+  const added = Array.isArray(entry.disabled) ? entry.disabled : []
+  const restore = 'node scripts/safe-boot.mjs --restore-last-good'
+  if (added.length > 0) {
+    return {
+      at: entry.at ?? null,
+      zh: `已自动禁用 ${added.length} 行（确证解析不到 / 上次把服务搞挂）：${added.join('、')}；如需恢复：${restore}`,
+      en: `Auto-disabled ${added.length} row(s) (confirmed unresolvable / crashed the service last time): ${added.join(', ')}; to restore: ${restore}`,
+      disabled: added, snapshotId: entry.snapshotId ?? null, restoreCommand: restore, kind: 'auto-disabled',
+    }
+  }
+  if (entry.code === 'switch-off') {
+    return {
+      at: entry.at ?? null,
+      zh: `检测到需禁用的行，但自动禁用开关已关闭：${(entry.candidates ?? []).join('、')}（保持原样，等你手动处理）`,
+      en: `Rows need disabling, but the auto-disable switch is off: ${(entry.candidates ?? []).join(', ')} (left untouched)`,
+      disabled: [], candidates: entry.candidates ?? [], restoreCommand: restore, kind: 'switch-off',
+    }
+  }
+  return null
+}
+
+/**
+ * D2：确认服务正常后落一份 last-known-good 快照。
+ * 「确认正常」的判据（不吹牛）：状态查询跑到了这一步 **且** 指纹与基线一致（环境没变）
+ * **且** 补丁通过结构校验（不是写坏的）。任一不满足就如实说明，不写快照。
+ */
+function maybeWriteSnapshot({ current, changed, patchPath }) {
+  try {
+    if (typeof patchPath !== 'string' || patchPath === '' || !existsSync(patchPath)) return { written: false, reason: 'no-patch-file' }
+    const patchText = readFileSync(patchPath, 'utf8')
+    if (changed === true) return { written: false, reason: 'environment-changed' }
+    const check = validatePatchYaml(patchText)
+    if (check.ok !== true) return { written: false, reason: 'patch-not-yaml-valid', problems: check.problems.slice(0, 3) }
+    const result = writeSnapshot({
+      patchPath,
+      patchText,
+      fingerprint: current,
+      frameworkVersion: current?.frameworkVersion ?? null,
+      reasons: [],
+      kind: 'auto',
+      pluginVersion: pluginVersionOf(),
+      note: `自动快照（模式 ${readCompatMode().mode}，服务响应正常，环境未变）`,
+    })
+    if (result.ok !== true) return { written: false, reason: 'write-failed', error: result.error }
+    return { written: result.written === true, reason: result.written === true ? null : (result.reason ?? 'unchanged'), snapshot: result.snapshot ?? null }
+  } catch (error) {
+    return { written: false, reason: 'error', error: error instanceof Error ? error.message : String(error) }
+  }
+}
+
 async function routeCompatStatusGet(req, res, rc) {
+  // D4：桌面端宿主启动 → 自动拨回观察者（只在启动/首次查询判定一次；用户手动拨过的机器一动不动）
+  const auto = maybeSwitchToObserver(rc)
   const mode = readCompatMode()
   const current = currentFingerprint(rc)
   const previous = readFingerprint()
   const { changed, reasons, baselineAt } = compareFingerprint(current, previous)
+  const patchPath = (() => { try { return findPatchPath(rc.ctx) } catch { return null } })()
+
+  // D1：变了就自动跑一次只读预检（后台，不阻塞；同一指纹只跑一次）
+  const autoRun = changed === true ? scheduleAutoPreflight(rc, { current, previous, reasons, profileDir: profileDirOf(rc.ctx), patchPath }) : null
+
+  // D2：确认服务正常 → 落 last-known-good 快照（节流：指纹与补丁都没变时零写盘）
+  const snapshot = maybeWriteSnapshot({ current, changed, patchPath })
+
+  const autoPreflight = autoPreflightView({ changed, current })
   sendJson(res, 200, {
     ok: true,
     mode: mode.mode,
-    modeSource: mode.source,
+    modeSource: mode.fileSource,
     modeChangedAt: mode.at,
     modeReason: mode.reason ?? null,
+    // D4 加法字段：本次是否自动拨回了观察者 + 一句短句（中英双语）；没自动改就是 null
+    modeAuto: auto.switched === true ? { switched: true, note: auto.note, at: Date.now() } : null,
     frameworkVersion: current.frameworkVersion,
     fingerprint: { current, previous, changed, reasons, baselineAt },
     rollback: readRollbackRecord(),
+    // D1 加法字段：自动预检的状态/结论（面板只放一句短句，长文进详情）
+    autoPreflight: { ...autoPreflight, scheduled: autoRun !== null, scheduledAt: autoRun === null ? null : Date.now(), timeoutMs: autoRun?.timeoutMs ?? preflightTimeoutMs() },
+    // D5 加法字段：自动禁用的开关状态 + **本次一次性提示**（客户端走既有瞬时 note 通道；
+    // 服务端不新增任何常驻面板元素/按钮/文件）
+    autoDisable: {
+      onEvidence: readCompatGate().autoDisableOnEvidence === true,
+      switch: { file: 'compat-gate.json', key: 'autoDisableOnEvidence', route: '/plugin-console/compat-ack', body: { autoDisableOnEvidence: false } },
+      notice: autoDisableNotice(),
+      restore: { route: { path: '/plugin-console/safe-boot', body: { action: 'restore-last-good' } }, command: 'node scripts/safe-boot.mjs --restore-last-good' },
+      logHint: '记录落在 dshHome()/plugin-console/auto-disable.log（追加式 JSONL）',
+    },
+    // D2 加法字段：安全启动材料（last-known-good 快照 + 恢复入口提示）
+    safeBoot: {
+      snapshot: { written: snapshot.written === true, reason: snapshot.reason ?? null, id: snapshot.snapshot?.id ?? null, at: snapshot.snapshot?.at ?? null, sha256: snapshot.snapshot?.patchSha256 ?? null },
+      snapshots: listSnapshots().slice(0, 5),
+      lastGoodId: readSafeBootState().lastGoodId,
+      command: { list: 'node scripts/safe-boot.mjs --list', restore: 'node scripts/safe-boot.mjs --restore-last-good', disable: 'node scripts/safe-boot.mjs --disable-suspects' },
+      route: { action: 'restore-last-good | disable-suspects | list | mark-good', path: '/plugin-console/safe-boot' },
+    },
   })
 }
 
 async function routeCompatMode(req, res, rc) {
   const wanted = rc.body?.mode
-  const result = writeCompatMode(wanted)
+  // 用户手动拨动 → 来源记 `manual`（此后**永不自动改**：D4 的"不抢用户意图"就靠这一笔）
+  const result = writeCompatMode(wanted, { source: 'manual', reason: '用户手动切换' })
   if (!result.ok) { sendError(res, 400, result.error); return }
-  sendJson(res, 200, { ok: true, mode: result.mode, note: result.mode === 'observer' ? '观察者模式：只做预检与门控，不接管框架升级' : '托管模式：框架升级与回滚由本控制台负责' })
+  sendJson(res, 200, {
+    ok: true,
+    mode: result.mode,
+    source: result.source,
+    changed: result.changed === true,
+    note: result.mode === 'observer' ? '观察者模式：只做预检与门控，不接管框架升级' : '托管模式：框架升级与回滚由本控制台负责',
+  })
 }
 
 async function routeCompatStamp(req, res, rc) {
@@ -143,6 +357,21 @@ async function routeDeclareInstalled(req, res, rc) {
  */
 async function routeCompatAck(req, res, rc) {
   const body = rc.body ?? {}
+  // D5 加法：自动禁用（有确证证据时）的开关——同一把锁（compat-gate.json）里再记一个布尔。
+  // 它与既有的 `autoDisable`（我们升级时）是两个独立开关；这里只动 `autoDisableOnEvidence`，
+  // **不碰** 既有字段（一个字都不改旧语义）。
+  if (typeof body.autoDisableOnEvidence === 'boolean') {
+    const gate = writeCompatGate({ autoDisableOnEvidence: body.autoDisableOnEvidence })
+    sendJson(res, 200, {
+      ok: true,
+      autoDisableOnEvidence: gate.autoDisableOnEvidence,
+      autoDisable: gate.autoDisable,
+      note: gate.autoDisableOnEvidence === true
+        ? '指纹变化 / 启动失败记录给出确证证据时，会自动禁用被点名的行（禁前先存快照，可一条命令回滚）'
+        : '已关闭自动禁用：只在面板/接口里报告点名行，改由你手动点「只禁可疑行」',
+    })
+    return
+  }
   if (typeof body.mode === 'string') {
     const mode = body.mode.trim().toLowerCase()
     if (!NOTICE_MODES.includes(mode)) {
@@ -167,4 +396,4 @@ async function routeCompatAck(req, res, rc) {
   const ack = writeCompatAck(version)
   sendJson(res, 200, { ok: true, ack, noticeMode: readCompatGate().noticeMode })
 }
-export { routeCompatAck, routeCompatMode, routeCompatStamp, routeCompatStatusGet, routeDeclareInstalled }
+export { hostShapeOf, maybeSwitchToObserver, maybeWriteSnapshot, preflightTimeoutMs, resetHostSwitchChecked, routeCompatAck, routeCompatMode, routeCompatStamp, routeCompatStatusGet, routeDeclareInstalled, scheduleAutoPreflight }

package/lib/server/routes/framework-preflight.js

@@ -24,6 +24,14 @@ import { baseDirOf, dshHome, findPatchPath, pluginRoot, profileDirOf, resolvePac
 
 const REGISTRY = 'https://registry.npmmirror.com'
 
+/** `preflightRoots` 的默认依赖（0.5.32：把这段抽成可注入形式，让"指纹变化自动预检"与离线脚本
+ *  复用**同一套扫描面**推导，而不是各写一份 —— 两套推导迟早会分叉，而分叉的表现是"自动预检看不见
+ *  用户装的那个包"，属于静默漏报）。生产路径不传 deps，行为与抽取前一字不差。 */
+const defaultListEntries = listEntries
+const defaultResolvePackageJson = resolvePackageJson
+const defaultIsFrameworkOwned = isFrameworkOwnedPackage
+const defaultPluginRoot = pluginRoot
+
 /** 预检的两个扫描面：用户预设目录 + profile 内每个已装插件包。
  *  框架自带包（解析到 profile 之外，即 npx 缓存里的 @deepseek-ai/*）标成 kind='framework'：
  *  仍然扫（能暴露框架自身的契约不一致），但**只报告不改**——改它等于污染框架安装树。
@@ -36,7 +44,12 @@ function userPresetsRoot(home = undefined) {
   return join(home ?? dshHome(), '.agent-presets')
 }
 
-function preflightRoots(ports, profileDir) {
+function preflightRoots(ports, profileDir, deps = {}) {
+  const userPresetsRoot = deps.userPresetsRoot ?? ((home = undefined) => join(home ?? dshHome(), '.agent-presets'))
+  const listEntries = deps.listEntries ?? defaultListEntries
+  const resolvePackageJson = deps.resolvePackageJson ?? defaultResolvePackageJson
+  const isFrameworkOwnedPackage = deps.isFrameworkOwnedPackage ?? defaultIsFrameworkOwned
+  const pluginRoot = deps.pluginRoot ?? defaultPluginRoot
   const roots = [{ root: userPresetsRoot(), kind: 'preset' }]
   // 控制台自身排除在外：它是工具、不是会话消息生产方，而它的报错文案/文档里本身就含
   // `kind: 'plugin'`、`.volatile(` 这类字样 —— 发版门槛自扫时正是这些字串报出了无意义条目。

package/lib/server/routes/index.js

@@ -17,6 +17,7 @@ import { routeAiConsent, routeAiEmpowerCancel, routeAiEmpowerList, routeAiEmpowe
 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 { routeSafeBoot } from './safe-boot.js'
 import { routePatchAuditGet } from './patch-audit.js'
 import { routePresetAuditGet } from './preset-audit.js'
 import { routeFrameworkUpgrade } from './framework-upgrade.js'
@@ -114,6 +115,9 @@ const ROUTES = [
   { methods: ['POST'], path: `${ROUTE_PREFIX}/compat-stamp`, handler: routeCompatStamp },
   { methods: ['POST'], path: `${ROUTE_PREFIX}/compat-ack`, handler: routeCompatAck },
   { methods: ['POST'], path: `${ROUTE_PREFIX}/declare-installed`, handler: routeDeclareInstalled },
+  // 安全启动材料恢复入口（2026-09-29 加法 D3-①，0.5.32）：白名单动作 list / restore-last-good /
+  // disable-suspects / mark-good；只认动作名，绝不接受命令串；服务起不来时走 scripts/safe-boot.mjs
+  { methods: ['POST'], path: `${ROUTE_PREFIX}/safe-boot`, handler: routeSafeBoot },
   { methods: ['POST'], path: `${ROUTE_PREFIX}/framework-rollback`, handler: routeFrameworkRollback },
   { methods: ['POST'], path: `${ROUTE_PREFIX}/restart`, handler: routeRestart },
   { methods: ['POST'], path: `${ROUTE_PREFIX}/toggle`, handler: routeToggle },

package/lib/server/routes/plugins.js

@@ -327,7 +327,9 @@ async function routeAdaptUnlock(req, res, rc) {
     const fwVer = typeof pending.frameworkVersion === 'string' ? pending.frameworkVersion : '?'
     const check = pkg !== null ? checkPluginFrameworkCompat(pkg, fwVer, pkgDir) : { decision: 'unknown', reason: '无法读取包信息' }
     if (check.decision === 'fail') {
-      sendError(res, 409, `适配校验未通过：${check.reason}`)
+      // 0.5.33 改错 ①-2：文案必须写清「为什么不行 + 出路」——旧文案只有一句"适配校验未通过"，
+      // 用户在界面上根本不知道下一步该做什么（而按钮此前又只在 adoptable 时出现，容易变成对不上的承诺）。
+      sendError(res, 409, `适配校验未通过：${String(check.reason ?? '适配校验未通过')}。出路：先点「检测更新」把它更新到兼容当前框架 ${fwVer} 的版本（更新完成会自动重跑源码扫描，通过即解锁）；若它已不再需要，可在补丁里删掉/禁用这一行。本次未改动补丁与适配门清单。`)
       return
     }
     await removeDisableBlock(patchPath, rowId)