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

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/safe-boot.js

@@ -0,0 +1,139 @@
+// L2 · routes —— **安全启动材料**恢复入口（0.5.32 加法 D3-①；服务在跑时用这条）
+//   POST /plugin-console/safe-boot   { action: 'list' | 'restore-last-good' | 'disable-suspects' | 'mark-good', ... }
+//
+// 为什么要有它（用户 2026-09-29 诉求：「能挽救改完打不开的局面」）：
+//   走了别的更新通道（官方桌面端更新器 / 手动 pnpm / npx 缓存变化）把框架换坏之后，
+//   用户需要**在服务还能应答的时候**有一条一键出路；服务起不来时则走 `scripts/safe-boot.mjs`
+//   （同一个 domain 模块，同一套判据）。
+//
+// 白名单动作（**只认这四个字符串**，绝不接受任何命令串/路径）：
+//   · list              列快照（不返回补丁正文）
+//   · restore-last-good 把补丁恢复成快照（改前再备份一份当前状态 + 读回核实 + 严格 YAML 闸门）
+//   · disable-suspects  **只**给点名的可疑行追加 `disabled: true`（不删任何行）；点名来源：
+//                       请求里的 rowIds，或 D1 自动预检落下的隔离计划（`?usePlan=1` 默认）
+//   · mark-good         把某份快照标记为「良好」（永不随保留策略删除）
+//
+// 一律返回**可复制的命令**与影响面摘要；不做任何未点名的改动。
+
+import { readFileSync } from 'node:fs'
+import { readStore } from '../domain/auto-preflight.js'
+import { readCompatMode } from '../domain/compat-state.js'
+import { CORE_PATCH_ROW_IDS } from '../domain/patch.js'
+import { readSafeBootState, disableSuspects, listSnapshots, markSnapshotGood, restoreLastGood, snapshotView, validatePatchYaml } from '../domain/safe-boot.js'
+import { sendError, sendJson } from '../infra/httpd.js'
+import { findPatchPath, pluginRoot } from '../infra/paths.js'
+
+const ACTIONS = ['list', 'restore-last-good', 'disable-suspects', 'mark-good']
+const PREFLIGHT_FILE_HINT = 'D1 自动预检的结论（同一份记录，面板与离线脚本共用）'
+
+function patchPathOf(rc) {
+  try { return findPatchPath(rc.ctx) } catch { return null }
+}
+
+function pluginVersionOf() {
+  try { return JSON.parse(readFileSync(`${pluginRoot()}/package.json`, 'utf8')).version ?? null } catch { return null }
+}
+
+/** 最近一次「done」的自动预检记录（按当前指纹取；取不到就退回最新一条 done）。 */
+function latestPlan() {
+  try {
+    const records = readStore().records
+    return records.find((r) => r.state === 'done' && Array.isArray(r.suspects) && r.suspects.length > 0)
+      ?? records.find((r) => r.state === 'done')
+      ?? null
+  } catch { return null }
+}
+
+/** 可复制命令（用户能直接粘到终端；服务起不来时就是这一条救回来）。 */
+function commands({ id = null } = {}) {
+  const script = 'node scripts/safe-boot.mjs'
+  return {
+    list: `${script} --list`,
+    restore: id === null ? `${script} --restore-last-good` : `${script} --restore-last-good --id ${id}`,
+    disable: `${script} --disable-suspects`,
+    markGood: id === null ? `${script} --mark-good` : `${script} --mark-good --id ${id}`,
+    note: { zh: '服务打不开时在插件目录下执行（无需服务在跑）', en: 'Run this in the plugin directory when the service cannot start (no running server needed)' },
+  }
+}
+
+async function routeSafeBoot(req, res, rc) {
+  const body = rc.body ?? {}
+  const action = typeof body.action === 'string' ? body.action.trim() : ''
+  const patchPath = patchPathOf(rc)
+  if (!ACTIONS.includes(action)) {
+    sendError(res, 400, `未知动作 ${action === '' ? '(空)' : action}（可选：${ACTIONS.join(' / ')}）—— 本接口只认白名单动作，不接受命令串`)
+    return
+  }
+  const state = readSafeBootState()
+  if (action === 'list') {
+    const plan = latestPlan()
+    sendJson(res, 200, {
+      ok: true,
+      action,
+      patchPath,
+      patch: patchPath === null ? null : { exists: true, check: (() => { try { return validatePatchYaml(readFileSync(patchPath, 'utf8')) } catch { return null } })() },
+      snapshots: listSnapshots(),
+      lastGoodId: state.lastGoodId,
+      lastAutoId: state.lastAutoId,
+      mode: readCompatMode().mode,
+      lastPlan: plan === null ? null : { at: plan.at, key: plan.key, state: plan.state, suspects: (plan.suspects ?? []).map((s) => s.rowId), affectedCount: (plan.affected ?? []).length, note: PREFLIGHT_FILE_HINT },
+      commands: commands(),
+      pluginVersion: pluginVersionOf(),
+    })
+    return
+  }
+  if (action === 'mark-good') {
+    const id = typeof body.id === 'string' && body.id !== '' ? body.id : null
+    const result = markSnapshotGood({ id })
+    if (result.ok !== true) { sendError(res, 404, result.error); return }
+    sendJson(res, 200, { ok: true, action, snapshot: result.snapshot, note: result.note, commands: commands({ id: result.snapshot?.id ?? null }) })
+    return
+  }
+  if (action === 'restore-last-good') {
+    const id = typeof body.id === 'string' && body.id !== '' ? body.id : null
+    const result = restoreLastGood({ patchPath, id })
+    if (result.ok !== true) { sendError(res, 409, result.error, { code: result.code, snapshot: result.snapshot ?? null, commands: commands({ id }) }); return }
+    sendJson(res, 200, {
+      ok: true, action, ...result,
+      impact: {
+        patchPath: result.patchPath,
+        changed: result.changed === true,
+        backupPath: result.backupPath ?? null,
+        sha256: result.sha256 ?? null,
+        snapshotId: result.snapshot?.id ?? null,
+        snapshotAt: result.snapshot?.at ?? null,
+        enabledCount: result.snapshot?.enabledCount ?? null,
+        disabledCount: result.snapshot?.disabledCount ?? null,
+      },
+      commands: commands({ id: result.snapshot?.id ?? null }),
+      next: { zh: '重启服务让补丁生效（观察者模式下本控制台不代你重启）', en: 'Restart the service for the patch to take effect (Observer mode does not restart it for you)' },
+    })
+    return
+  }
+  // disable-suspects
+  const plan = latestPlan()
+  const explicit = Array.isArray(body.rowIds) ? body.rowIds.filter((x) => typeof x === 'string') : null
+  const usePlan = body.usePlan !== false
+  const rowIds = explicit !== null && explicit.length > 0 ? explicit : (usePlan && plan !== null ? (plan.suspects ?? []).map((s) => s.rowId) : [])
+  if (rowIds.length === 0) {
+    sendJson(res, 200, {
+      ok: true, action, changed: false, added: [], skipped: [], backupPath: null,
+      reason: 'no-suspects',
+      note: { zh: '没有点名的可疑行（自动预检尚未跑出结论，或它没点名任何行）—— 需要的话请在 rowIds 里显式给出', en: 'No named suspect rows (auto-preflight has no conclusion yet, or named none) — pass rowIds explicitly if needed' },
+      coreRowIds: [...CORE_PATCH_ROW_IDS].slice(0, 8),
+      commands: commands(),
+    })
+    return
+  }
+  const result = disableSuspects({ patchPath, rowIds })
+  if (result.ok !== true) { sendError(res, 409, result.error, { code: result.code, problems: result.problems ?? null, commands: commands() }); return }
+  sendJson(res, 200, {
+    ok: true, action, ...result,
+    source: explicit !== null && explicit.length > 0 ? 'request' : 'auto-preflight-plan',
+    planAt: plan?.at ?? null,
+    impact: { requested: rowIds.length, added: result.added ?? [], skipped: result.skipped ?? [], backupPath: result.backupPath ?? null, prefixUnchanged: result.prefixSame === true },
+    commands: commands(),
+  })
+}
+
+export { ACTIONS, commands, latestPlan, routeSafeBoot }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noob-stupid/dsh-plugin-console",
-  "version": "0.5.31",
+  "version": "0.5.32",
   "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",