@noob-stupid/dsh-plugin-console 0.5.30 → 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/components.js

@@ -109,7 +109,7 @@ async function routeRepoLandConfig(req, res, rc) {
   const body = rc.body
     const dir = typeof body.dir === 'string' ? body.dir.trim() : ''
     if (dir === '' || !/^[A-Za-z]:[\\/]/.test(dir) && !/^\\\\/.test(dir)) {
-      // 0.5.28 改错：示例原本写成本机真实目录 `D:\dsh\repos`（把开发者的目录当成了通用示例）。
+      // 0.5.28 改错：示例原本写成本机真实目录（把开发者的目录当成了通用示例）。
       // 换成中性的任意绝对路径示例，并说明"任意绝对路径"——判据是形状（盘符/UNC），不是具体目录。
       sendError(res, 400, '保存路径不合法：请提供绝对路径（任意绝对路径均可，如 C:\\repos 或 \\\\server\\share\\repos）')
       return

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/framework-upgrade.js

@@ -1,7 +1,6 @@
 // L2 · routes —— 框架升级（POST /framework-upgrade）
-// 分层 Step 8b：从 lib/index.js 的 handle() 原样搬出（只搬移未改逻辑）。
-// 注：这个 handler 661 行（内置大段 PowerShell 脚本模板），是守卫「单文件 ≤ 600 行」的受限例外（见守卫 SIZE_EXCEPTIONS）；
-// 待抽包阶段把脚本模板挪进 domain/framework-script.js 后撤销例外。
+// 分层 Step 8b：从 lib/index.js 的 handle() 原样搬出（只搬移未改逻辑）。这个 handler 内置大段
+// PowerShell 脚本模板，是守卫「单文件 ≤ 600 行」的受限例外（见 SIZE_EXCEPTIONS），待抽包阶段撤销。
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs'
 import { writeFile } from 'node:fs/promises'
@@ -11,7 +10,7 @@ import { tmpdir } from 'node:os'
 import { pathToFileURL } from 'node:url'
 import { createRequire } from 'node:module'
 import { readCompatMode, writeCompatMode } from '../domain/compat-state.js'
-import { FRAMEWORK_BACKUP_ROOT, backupProfileSnapshot, checkpointFrameworkTree, preflightDisableIncompatible, relaunchPrelude, resolveDshBin, resolveFrameworkRootNodeModules, resolveFrameworkUpgradePlan, shellHostedRefusal } from '../domain/framework.js'
+import { FRAMEWORK_BACKUP_ROOT, backupProfileSnapshot, checkpointFrameworkTree, platformUpgradeRefusal, preflightDisableIncompatible, relaunchPrelude, resolveDshBin, resolveFrameworkRootNodeModules, resolveFrameworkUpgradePlan, shellHostedRefusal } from '../domain/framework.js'
 import { fwIntegrityCheck } from '../infra/fw-integrity-check.js'
 import { CORE_PATCH_ROW_IDS } from '../domain/patch.js'
 import { migrateAgentConfigsForUpgrade } from '../domain/presets.js'
@@ -80,12 +79,15 @@ async function routeFrameworkUpgrade(req, res, rc) {
       } catch {}
     }
     // 拉元数据 → 候选版本列表 → 本次目标（helper 里同时做「用户自选版本」的白名单校验）
-    const plan = await resolveFrameworkUpgradePlan({ current, wanted: body.version, fetchJson: fetchJsonUrl })
+    const plan = await resolveFrameworkUpgradePlan({ current, wanted: body.version, fetchJson: rc.deps.fetchJson ?? fetchJsonUrl })
     const { latest, next, alpha, versions, tagDefault, registryError } = plan
     if (plan.rejected !== null) {
       sendError(res, 400, `升级目标 ${plan.rejected} 不在可选列表内（只接受比当前 ${current ?? '?'} 更新的已发布版本；降级请用「回滚到上一版」）`)
       return
     }
+    // 平台守卫（2026-09-29 改错）：本通道 = schtasks.exe + PowerShell，只有 win32 有；判据与文案见
+    // domain/framework.js#platformUpgradeRefusal。放在入参校验之后、任何副作用之前 —— 绝不假成功。
+    const platformRefusal = platformUpgradeRefusal(); if (platformRefusal !== null) { sendError(res, 501, platformRefusal.error, platformRefusal.details); return }
     const target = plan.target
     const profileDir = dirname(findPatchPath(ctx))
     // 1) 升级前打包备份现有配置（patch / profile package.json / 插件清单）
@@ -138,17 +140,16 @@ async function routeFrameworkUpgrade(req, res, rc) {
         steps.push(`另有 ${preflight.skipped.length} 行无法预判（受保护行/包信息读不到），保持启用，由升级后的启动失败隔离兜底`)
       }
     }
-    // 2) 自动升级框架：运行中的服务锁着 dsh/lib 目录（EBUSY 无法原地替换），
-    //    因此生成独立升级脚本（kill 服务 → npm 升级 → 失败回滚 → 拉起服务），后台执行。
-    //    与 /restart 同款自守护模式：端口无监听会自动拉起，不会留下"服务起不来"。
+    // 2) 自动升级框架：运行中的服务锁着 dsh/lib 目录（EBUSY 无法原地替换）→ 生成独立升级脚本
+    //    （kill 服务 → npm 升级 → 失败回滚 → 拉起服务）后台执行；与 /restart 同款自守护，不会留下"服务起不来"。
     if (hasUpdate && dshDir !== null) {
       const port = webPort(ctx)
       const nodePath = process.execPath
       const binPath = resolveDshBin()
       const npmCli = join(dirname(process.execPath), 'node_modules', 'npm', 'bin', 'npm-cli.js')
       // 事故教训：npm 的 lib/cli.js 是「函数模块」（module.exports = (process) => validateEngines(...)），
-      // 直跑 `node lib/cli.js` 只加载函数定义、不执行命令——立即退出 exit 0（假成功，曾导致
-      // "npm 退出码 0 但版本未更新"）。唯一正确入口是 bin/npm-cli.js（它调用 cli.js 函数）。
+      // 直跑它只加载函数定义、不执行命令——立即退出 exit 0（假成功，"npm 退出码 0 但版本未更新"）。
+      // 唯一正确入口是 bin/npm-cli.js（它调用 cli.js 函数）。
       const corepackJs = join(dirname(process.execPath), 'node_modules', 'corepack', 'dist', 'corepack.js')
       // 预检（事故教训）：corepack（pnpm 通道）/ dsh bin.js 缺失时**拒绝生成升级脚本**（不 kill 服务）——
       // 避免"kill 后升级/拉起双双失败，服务永久 down"
@@ -640,16 +641,14 @@ async function routeFrameworkUpgrade(req, res, rc) {
       setFwCheckCache(null)
       // UTF-8 BOM：powershell 5.1 按 ANSI 读无 BOM 文件，中文会乱码——加 BOM 保证解析正确。
       // 执行方式：schtasks 一次性计划任务（Task Scheduler 启动，独立于服务进程树/Job Object）——
-      // 服务进程被杀时，其子进程（execFile/detached 的 powershell）会被 Job/进程树连带杀死，
-      // 曾多次卡死在「停止服务」之后；计划任务彻底脱离，杀服务绝对影响不到升级脚本。
+      // 服务进程被杀时其子进程（execFile/detached 的 powershell）会被 Job 连带杀死，
+      // 计划任务彻底脱离，杀服务影响不到升级脚本。
       writeFile(ps1, `\uFEFF${lines}`, 'utf8').then(
         () => {
           const ps1Posix = ps1.replace(/\\/gu, '/')
-          // 无引号 /tr（重要）：Task Scheduler 对带引号命令的解析会把 Command 拆坏成
-          // `"powershell ... -File \"`（非有效可执行文件）——任务显示 Ready、/run 报 SUCCESS
-          // 但永不执行（曾导致升级/重启脚本反复"已启动"却不动作、服务不停止）。实测无引号
-          // 格式（exe 与脚本路径均无空格时）任务正常执行、脚本完整跑通。仅当脚本路径含空格
-          // 时才退回带引号格式（schtasks 引号解析在服务 execFile 上下文不可靠，此时宁可用它）。
+          // 无引号 /tr（重要）：Task Scheduler 会把带引号命令的 Command 拆坏成 `"powershell … -File \"`
+          // （非有效可执行文件）——任务显示 Ready、/run 报 SUCCESS 但永不执行（曾导致脚本反复"已启动"
+          // 却不动作）。实测无引号格式（exe 与脚本路径均无空格时）正常；仅脚本路径含空格时才退回带引号格式。
           const tr = / /.test(ps1Posix)
             ? `"powershell -NoProfile -WindowStyle Hidden -ExecutionPolicy Bypass -File \\"${ps1Posix}\\""`
             : `C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe -NoProfile -WindowStyle Hidden -ExecutionPolicy Bypass -File ${ps1Posix}`

package/lib/server/routes/framework.js

@@ -8,7 +8,7 @@ import { dirname, join, resolve } from 'node:path'
 import { tmpdir } from 'node:os'
 import { createRequire } from 'node:module'
 import { readCompatGate, writeCompatGate } from '../domain/compat.js'
-import { cleanupStaleFwTasks, currentFrameworkVersion, pickFrameworkTarget, relaunchPrelude, resolveDshBin, resolveFrameworkRootNodeModules, shellHostedRefusal } from '../domain/framework.js'
+import { cleanupStaleFwTasks, currentFrameworkVersion, pickFrameworkTarget, platformUpgradeRefusal, relaunchPrelude, resolveDshBin, resolveFrameworkRootNodeModules, shellHostedRefusal } from '../domain/framework.js'
 import { readGithubAuth } from '../domain/install.js'
 import { webPort } from '../domain/runtime.js'
 import { fetchJsonUrl } from '../infra/http.js'
@@ -32,6 +32,21 @@ function refuseWhenShellHosted(res) {
   return true
 }
 
+/**
+ * 平台守卫（2026-09-29 改错，与宿主守卫同形）：一键升级/回滚脚本整体依赖 Windows 机制 ——
+ * `schtasks.exe` 计划任务 + PowerShell + `Get-NetTCPConnection`；非 Windows 上 execFile 必然 ENOENT，
+ * 而旧实现会先写一个「脚本已启动」的状态文件、再去 exec 不存在的 powershell.exe，**最后仍回 ok:true**
+ * （用户以为在跑，实际零动作）。判据与文案见 domain/framework.js#platformUpgradeRefusal。
+ * 命中时：不写状态文件、不 spawn、不建计划任务，直接 501 + 手动升级出路。
+ * 返回 true = 已拒绝（调用方直接 return）；false = win32，原路径一字不改。
+ */
+function refuseWhenPlatformUnsupported(res) {
+  const refusal = platformUpgradeRefusal()
+  if (refusal === null) return false
+  sendError(res, 501, refusal.error, refusal.details)
+  return true
+}
+
 async function routeFrameworkUpgradeStatusGet(req, res, rc) {
   const ctx = rc.ctx
   const url = rc.url
@@ -355,6 +370,7 @@ async function routeFrameworkRollback(req, res, rc) {
       sendError(res, 409, '没有可用的框架全树回滚点（framework-rollback.json 缺失或 checkpoint 已清理）')
       return
     }
+    if (refuseWhenPlatformUnsupported(res)) return // 平台守卫（改错）：回滚脚本同样是 schtasks+PowerShell，非 win32 一律拒绝而不是假成功（放在只读状态校验之后、任何写盘/exec 之前）
     const port = webPort(ctx)
     const nodePath = process.execPath
     const taskName = `DSH-FW-Rollback-${process.pid}`
@@ -576,4 +592,4 @@ async function routeFrameworkStatusClear(req, res, rc) {
   }
   sendJson(res, 200, { ok: true, removed, status: 'idle', message: null })
 }
-export { refuseWhenShellHosted, routeFrameworkStatusClear, routeFrameworkUpgradeStatusGet, routeFrameworkRelaunch, routeFrameworkCheck, routeCompatGate, routeCheckUpdate, routeFrameworkRollback, routeRestart }
+export { refuseWhenShellHosted, refuseWhenPlatformUnsupported, routeFrameworkStatusClear, routeFrameworkUpgradeStatusGet, routeFrameworkRelaunch, routeFrameworkCheck, routeCompatGate, routeCheckUpdate, routeFrameworkRollback, routeRestart }

package/lib/server/routes/github-login.js

@@ -149,8 +149,8 @@ function shortOpenError(error) {
  * POST /plugin-console/github-open-login —— 唤起 dsh-github-login 的设备码登录窗口。
  *
  * 为什么失败也回 200（而不是 500）：这个能力是**外挂**的，装没装、装的是不是带 exe 的版本、
- * 当前 profile 有没有把它挂到 webServer 上，全都不由本插件决定（2026-09-20 实测：本机虽然装了
- * 该插件、exe 也在 D:\dsh\dsh-github-login\dist\，但当前 profile 下 GET /github-auth/status 仍是
+ * 当前 profile 有没有把它挂到 webServer 上，全都不由本插件决定（2026-09-20 实测：某个 profile 里虽然装了
+ * 该插件、exe 也在，但当前 profile 下 GET /github-auth/status 仍是
  * 404）。这些都是"这个通道现在不可用"，不是"服务端出错"：
  *   · 回 500 → 前端弹一句看不懂的报错，还看不出"该走 token 兜底"这条正路；
  *   · 回 200 + started:false + reason → 前端照原样把原因念给用户，并自动展开 token 粘贴面板。

package/lib/server/routes/index.js

@@ -11,11 +11,13 @@ import { pnpmRemove, readExtraBundleRows, runInstallJob } from '../domain/instal
 import { isProtectedModule, listEntries, webPort } from '../domain/runtime.js'
 import { DEFAULT_SEARCH } from '../domain/sources.js'
 import { runSuiteInstallJob } from '../domain/suite.js'
+import { fetchJsonUrl } from '../infra/http.js'
 import { readBody, sendError } from '../infra/httpd.js'
 import { routeAiConsent, routeAiEmpowerCancel, routeAiEmpowerList, routeAiEmpowerPlan, routeAiEmpowerRun, routeAiEmpowerStatus } from './ai.js'
 import { routeRunSuggested } from './actions.js'
 import { routeComponentAutostart, routeComponentStart, routeComponentStatus, routeComponentStop, routeComponents, routeRepoClone, routeRepoLandConfig, routeRepoList, routeRepoOpen, routeRepoRemove } from './components.js'
 import { routeCompatAck, routeCompatMode, routeCompatStamp, routeCompatStatusGet, routeDeclareInstalled } from './compat.js'
+import { routeSafeBoot } from './safe-boot.js'
 import { routePatchAuditGet } from './patch-audit.js'
 import { routePresetAuditGet } from './preset-audit.js'
 import { routeFrameworkUpgrade } from './framework-upgrade.js'
@@ -53,7 +55,9 @@ const ROUTES_EARLY = [
 ]
 
 function routeDeps() {
-  return { runInstallJob, runSuiteInstallJob, webPort, readExtraBundleRows, detectAdoptablePending, listEntries, detectCompat, detectFrameworkUpgrade, DEFAULT_SEARCH, aiEmpowerExecute, aiEmpowerPlan, backupProfileSnapshot, currentFrameworkVersion, frameworkCompatReportFor, isProtectedModule, pnpmRemove, preflightDisableIncompatible, rowIdModuleMap }
+  // fetchJson：registry 元数据取数的注入缝（默认就是真通道）。测试要断言「非 win32 拒绝且零副作用」
+  // 时用它喂固定元数据，免得把网络与 CI 稳定性绑在一起（与其余 deps 同一种注入风格）。
+  return { runInstallJob, runSuiteInstallJob, webPort, readExtraBundleRows, detectAdoptablePending, listEntries, detectCompat, detectFrameworkUpgrade, DEFAULT_SEARCH, aiEmpowerExecute, aiEmpowerPlan, backupProfileSnapshot, currentFrameworkVersion, frameworkCompatReportFor, isProtectedModule, pnpmRemove, preflightDisableIncompatible, rowIdModuleMap, fetchJson: fetchJsonUrl }
 }
 
 async function handle(ctx, req, res) {
@@ -111,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 },