@noob-stupid/dsh-plugin-console 0.5.107 → 0.5.109

package/lib/client.js

@@ -739,6 +739,23 @@ window.__ModuleLoader__.load({
 			compActionDone: "{action}：{name}",
 			noComponents: "暂无已识别的服务器组件（用 AI 赋能部署后自动出现）",
 			aiFallbackTitle: "关闭后：常规通道失败将直接取消安装，不再调用模型 API（零费用）",
+			// ★ 加法（用户 2026-11-04 第 2 项）：功能包里的 [自更新] 开关 —— **只更新控制台自己**。
+			selfUpdateLabel: "自更新",
+			selfUpdateAria: "自更新：只自动更新控制台自己（不碰任何别的插件）；点一下切换开关",
+			selfUpdateCheckLabel: "立即检查",
+			selfUpdateCheckHint: "立刻查一次有没有新版本（只更新控制台自己；装完要重启服务才生效）",
+			selfUpdateLastCheck: "上次检查",
+			selfUpdateLastResult: "上次结果",
+			selfUpdateNever: "从未检查",
+			selfUpdateResultNever: "还没有跑过检查",
+			selfUpdateUpToDate: "已是最新",
+			selfUpdateUpdated: "已更新到 {version}（重启服务后生效）",
+			selfUpdateSkipped: "本轮跳过：{reason}",
+			selfUpdateFailed: "失败：{reason}",
+			selfUpdateChecking: "正在检查控制台的新版本…",
+			selfUpdateSaving: "正在写入开关…",
+			selfUpdateOn: "自更新已开启（只自动更新控制台自己）",
+			selfUpdateOff: "自更新已关闭（不会再自动更新任何东西）",
 			aiFallbackOff: "已按设置关闭 AI 兜底，本次安装已取消（零费用）",
 			aiConsentRemember: "以后不再提醒（自动同意 AI 兜底，可能产生费用；可随时在插件市场页面最底部恢复提醒）",
 			aiRememberNote: "已按设置自动同意本地 AI 兜底（如需恢复弹窗提醒，请到市场底部修改）",
@@ -1542,6 +1559,23 @@ window.__ModuleLoader__.load({
 			compActionDone: "{action}: {name}",
 			noComponents: "No server components yet (they appear after an AI Empower deployment)",
 			aiFallbackTitle: "When off: if regular channels fail, the install is cancelled directly without calling the model API (zero cost)",
+			// ★ additive: the [Self-update] switch in the feature-pack toolbar — updates the console itself only.
+			selfUpdateLabel: "Self-update",
+			selfUpdateAria: "Self-update: auto-update the console itself only (never other plugins); click to toggle",
+			selfUpdateCheckLabel: "Check now",
+			selfUpdateCheckHint: "Check for a new console version right now (self only; restart the service to apply)",
+			selfUpdateLastCheck: "Last checked",
+			selfUpdateLastResult: "Last result",
+			selfUpdateNever: "Never checked",
+			selfUpdateResultNever: "No check has run yet",
+			selfUpdateUpToDate: "Up to date",
+			selfUpdateUpdated: "Updated to {version} (takes effect after restarting the service)",
+			selfUpdateSkipped: "Skipped this round: {reason}",
+			selfUpdateFailed: "Failed: {reason}",
+			selfUpdateChecking: "Checking for a new console version…",
+			selfUpdateSaving: "Saving the switch…",
+			selfUpdateOn: "Self-update is on (updates the console itself only)",
+			selfUpdateOff: "Self-update is off (nothing is auto-updated anymore)",
 			aiFallbackOff: "AI fallback is disabled by your setting; this install was cancelled (zero cost)",
 			aiConsentRemember: "Don't ask again (auto-approve the AI fallback, may incur costs; restore reminders anytime at the very bottom of the market)",
 			aiRememberNote: "AI fallback auto-approved per your setting (restore reminders at the market bottom)",
@@ -2412,6 +2446,34 @@ const RESTART_FAILED_NOTE = "重启请求失败";
 			if (/[\\/]$/u.test(text)) return text;
 			return text + (text.includes("\\") ? "\\" : "/");
 		}
+		// ── [自更新] 开关的四个**纯函数**（用户 2026-11-04 第 2 项，加法）──────────────────────
+		//  为什么拆成纯函数：面板里那段渲染一旦写错，只有开浏览器才看得见（本仓为此吃过"整块空白"的亏）。
+		//  这四件都只吃 `/state` 下发的 `selfAutoUpdate`（+ 字典），**不写盘、不发请求、不编造**：
+		//    · 字段缺失（老服务端 / 还没刷新）⇒ 按**默认开启**显示，但**绝不**因此写回服务端；
+		//    · 上次检查 / 上次结果拿不到 ⇒ 一律显示「—」，有结果才照服务端原话念。
+		function selfAutoUpdateEnabledOf(info) {
+			if (info === null || info === undefined) return true; // 默认开启；**不**写回
+			return info.enabled !== false;
+		}
+		function selfAutoUpdateLastCheckOf(info, neverText) {
+			if (info === null || info === undefined) return "—"; // 拿不到就是「—」，不编造一个时间
+			const at = Number(info.lastCheckAt);
+			if (!Number.isFinite(at) || at <= 0) return neverText;
+			try { return new Date(at).toLocaleString(); } catch { return "—"; }
+		}
+		function selfAutoUpdateLastResultOf(info, t) {
+			if (info === null || info === undefined) return "—";
+			return selfUpdateOutcomeText(info.lastResult, t);
+		}
+		/** 「一次检查的结果」→ 一句话（`checkAndUpdate` 的结构与 `lastResult` 同形，两处共用这一份）。 */
+		function selfUpdateOutcomeText(outcome, t) {
+			if (outcome === null || outcome === undefined || typeof outcome !== "object") return t("selfUpdateResultNever");
+			if (outcome.updated === true) return t("selfUpdateUpdated").replace("{version}", String(outcome.to ?? outcome.version ?? "?"));
+			if (outcome.skipped === "up-to-date") return t("selfUpdateUpToDate");
+			if (outcome.ok === false) return t("selfUpdateFailed").replace("{reason}", String(outcome.reason ?? ""));
+			if (typeof outcome.skipped === "string" && outcome.skipped !== "") return t("selfUpdateSkipped").replace("{reason}", String(outcome.reason ?? outcome.skipped));
+			return t("selfUpdateUpToDate");
+		}
 		function PluginConsoleTab({ t, section = null }) {
 			const [state, setState] = react.useState({ status: "loading" });
 			// ★ 0.5.59：健康摘要**可关掉**（用户 2026-10-17「这个提示可以关掉」）。
@@ -2780,6 +2842,57 @@ const RESTART_FAILED_NOTE = "重启请求失败";
 			const [aiFallback, setAiFallback] = react.useState(() => {
 				try { return localStorage.getItem("pc-ai-fallback-v2") !== "off"; } catch { return true; }
 			});
+			// ★ 加法（用户 2026-11-04 第 2 项）：功能包工具栏里的 **[自更新]** 开关 —— 只更新控制台自己。
+			//   读的是 `/state.selfAutoUpdate`（服务端判据全在 domain/self-auto-update.js）；这里只负责：
+			//     · 默认开启（字段缺失也按开启**显示**，但绝不因为"没读到"就往服务端写回一个值）；
+			//     · 点一下 → POST `{action:"toggle", enabled:<下一值>}`；写请求期间**禁用并显示进行中**；
+			//     · 成败都有反馈：失败把服务端错误原文念出来（绝不静默，也绝不假装切过去了）。
+			const [selfUpdateBusy, setSelfUpdateBusy] = react.useState(false);
+			const selfUpdateInfo = state.status === "ready" && state.data !== null && state.data !== undefined
+				&& state.data.selfAutoUpdate !== null && state.data.selfAutoUpdate !== undefined ? state.data.selfAutoUpdate : null;
+			const selfUpdateEnabled = selfAutoUpdateEnabledOf(selfUpdateInfo);
+			const selfUpdateTitleText = () => t("selfUpdateAria") + "\n"
+				+ t("selfUpdateLastCheck") + "：" + selfAutoUpdateLastCheckOf(selfUpdateInfo, t("selfUpdateNever")) + "\n"
+				+ t("selfUpdateLastResult") + "：" + selfAutoUpdateLastResultOf(selfUpdateInfo, t);
+			const selfUpdateToggle = () => {
+				if (selfUpdateBusy) return;
+				const next = !selfUpdateEnabled;
+				setSelfUpdateBusy(true);
+				setMessage(t("selfUpdateSaving"));
+				call("/plugin-console/self-auto-update", { action: "toggle", enabled: next }).then(
+					(data) => {
+						setSelfUpdateBusy(false);
+						const view = data !== null && data !== undefined ? data.selfAutoUpdate : null;
+						const nowOn = view !== null && view !== undefined ? view.enabled === true : next;
+						setMessage((nowOn ? t("selfUpdateOn") : t("selfUpdateOff")) + (data !== null && data !== undefined && typeof data.note === "string" && data.note !== "" ? "（" + data.note + "）" : ""));
+						refresh();
+					},
+					(error) => {
+						setSelfUpdateBusy(false);
+						setMessage(t("safetySwitchFailed") + "：" + ((error !== null && error !== undefined && typeof error.message === "string" && error.message !== "") ? error.message : t("safetySwitchFailed")));
+						refresh();
+					},
+				);
+			};
+			// 「立即检查」：与定时器同一条路（服务端单飞，正在跑时直接回 skipped:'busy'）
+			const selfUpdateCheckNow = () => {
+				if (selfUpdateBusy) return;
+				setSelfUpdateBusy(true);
+				setMessage(t("selfUpdateChecking"));
+				call("/plugin-console/self-auto-update", { action: "check" }).then(
+					(data) => {
+						setSelfUpdateBusy(false);
+						const check = data !== null && data !== undefined ? data.check : null;
+						setMessage(selfUpdateOutcomeText(check, t));
+						refresh();
+					},
+					(error) => {
+						setSelfUpdateBusy(false);
+						setMessage(t("safetySwitchFailed") + "：" + ((error !== null && error !== undefined && typeof error.message === "string" && error.message !== "") ? error.message : t("safetySwitchFailed")));
+						refresh();
+					},
+				);
+			};
 			// AI 赋能：来源输入 / 计划确认 / 执行进度
 			const [aiOpen, setAiOpen] = react.useState(false);
 			const [aiSource, setAiSource] = react.useState("");
@@ -7576,6 +7689,29 @@ const RESTART_FAILED_NOTE = "重启请求失败";
 								return next;
 							}),
 						}, t("aiFallbackLabel")),
+						// ★ 加法（用户 2026-11-04 第 2 项）：**[自更新]** —— 只更新控制台自己，**默认开启**。
+						//   data-active 反映服务端下发的开关值（字段缺失 ⇒ 按开启显示）；写请求期间 disabled +
+						//   data-busy（那颗按钮不会"点了没反应"：先给一句"正在写入"，回来再报结果）。
+						el("button", {
+							type: "button",
+							className: styles.toolItem,
+							"data-active": selfUpdateEnabled ? "true" : "false",
+							"data-busy": selfUpdateBusy ? "true" : "false",
+							disabled: selfUpdateBusy,
+							title: selfUpdateTitleText(),
+							"aria-label": t("selfUpdateAria"),
+							onClick: () => selfUpdateToggle(),
+						}, t("selfUpdateLabel") + (selfUpdateEnabled ? " ✓" : "") + (selfUpdateBusy ? " …" : "")),
+						// 「立即检查」：同一组里的第二颗（用户要的那一颗按钮仍然是上面的 [自更新]）
+						el("button", {
+							type: "button",
+							className: styles.toolItem,
+							"data-busy": selfUpdateBusy ? "true" : "false",
+							disabled: selfUpdateBusy,
+							title: t("selfUpdateCheckHint"),
+							"aria-label": t("selfUpdateCheckHint"),
+							onClick: () => selfUpdateCheckNow(),
+						}, t("selfUpdateCheckLabel") + (selfUpdateBusy ? " …" : "")),
 						el("button", {
 							type: "button",
 							className: styles.toolItem,

package/lib/server/domain/self-auto-update.js

@@ -0,0 +1,555 @@
+// L1 · domain —— self-auto-update.js（控制台**只更新它自己**的自动更新：配置 + 检查 + 覆盖式安装 + 退避 + 调度）
+//
+// ── 用户原话（2026-11-04）────────────────────────────────────────────────────────────
+//   「我的意思是，自更新我们的插件本身」「然后弄功能包一个按钮，[自更新]，默认打开」。
+//   范围**严格限定**在 `@noob-stupid/dsh-plugin-console` 自己：任何别的插件都绝不自动更新。
+//
+// ── 本模块做什么（一切"装"的动作都复用既有实现，这里只做编排）─────────────────────────────
+//   ① 配置持久化 `~/.dsh/plugin-console/auto-update.json`：`{ enabled, intervalHours, lastCheckAt, lastResult }`，
+//      `enabled` 默认 **true**；写盘走"临时文件 + rename"（原子）；读坏文件**降级为默认值并且绝不覆盖用户文件**。
+//   ② `checkAndUpdate()`：纯编排 —— 关掉 ⇒ 不动；有安装作业 / 拿不到锁 ⇒ 不动；框架升级中 ⇒ 不动；
+//      远端**严格高于**本地才装；装走 `install-self-overlay.js`（下载 tarball → 只覆盖不清空 → 读回核对版本）；
+//      备份 / 失败自愈 / manualCommand 走 `self-update-guard.js`（唯一实现）。**全程不调用 pnpm**，
+//      也**绝不重启服务**（宿主不能安全地重启自己）—— 结果里写明"重启后生效"。
+//   ③ 失败退避：同一目标版本失败过一次，6 小时内不再重试（防无限循环刷日志）；成功后清空。
+//   ④ 进程内定时器：启动后延迟约 2 分钟首检，之后每 `intervalHours` 一次；**单飞**（上一轮没跑完不叠下一轮）；
+//      定时器一律 `unref()`，绝不阻塞进程退出。
+//
+// ── 硬规矩（改代码时别越线）────────────────────────────────────────────────────────
+//   ① **只对自己生效**：目标包名恒等于 `selfPackageNameOf()`；调用方就算点名别的包，也只会拿到
+//      `skipped:'not-self'` 的如实拒绝（`tests/test-self-auto-update.mjs` ⑨ 钉住：放宽成任意包必须变红）。
+//   ② **零 pnpm**：装包只走覆盖式（`runSelfOverlayInstall`）；本文件里不出现任何包管理器调用
+//      （⑨ 的变异断言：把 pnpm 加回来必须变红 —— 运行期有 exec 记录桩，静态还有源码扫描）。
+//   ③ 绝不因为自动更新失败而影响宿主：调度里每一步都 catch 成**一条如实记录**，路由层也只回结果。
+//   ④ 不谎报：`updated:true` 只在"读回的版本 === 目标版本"时成立；探测不到、不可比、装失败都如实说。
+//   ⑤ domain 层不认识 cordis（分层断言），profileDir / 作业表这类宿主信息一律由调用方注入。
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { compareSemverText, parseSemverText } from '../infra/semver.js'
+import { dshHome, pluginRoot } from '../infra/paths.js'
+import { probeRegistryPackage } from './dep-source.js'
+import { preferredRegistries } from './sources.js'
+import { installLockHolder, withInstallLockOr } from './install-lock.js'
+import { runSelfOverlayInstall } from './install-self-overlay.js'
+import { beginSelfUpdateGuard, isSelfUpdate, selfPackageNameOf, settleSelfUpdateGuard } from './self-update-guard.js'
+import { readInstalledVersion } from './selfupdate-read.js'
+
+/** 配置文件（与其它控制台状态文件同目录：`<DSH_HOME>/plugin-console/`）。 */
+const CONFIG_FILE = 'auto-update.json'
+/** 默认检查间隔（小时）。用户没改过就是这个值。 */
+const DEFAULT_INTERVAL_HOURS = 6
+/** 首检延迟：**启动后约 2 分钟**（先把宿主自己的启动活干完，再谈更新）。 */
+const DEFAULT_FIRST_DELAY_MS = 2 * 60 * 1000
+/** 失败退避窗口：同一目标版本 6 小时内不重试。 */
+const RETRY_BACKOFF_MS = 6 * 60 * 60 * 1000
+const HOUR_MS = 60 * 60 * 1000
+/** 框架升级状态文件的"仍在进行中"窗口 —— 与 `/framework-upgrade-status` 的 15 分钟残留清理同一口径。 */
+const FW_STATE_STALE_MS = 15 * 60 * 1000
+/** 框架升级的终止状态（与 routes/framework.js#routeFrameworkUpgradeStatusGet 同一批；那边贴着 600 行
+ *  棘轮、import 不出来，本文件只在**窗口判定**上复述这份名单，取值口径逐字相同）。 */
+const FW_TERMINAL_STATUS = new Set(['idle', 'done', 'failed', 'ready'])
+
+const label = (error) => (error instanceof Error ? error.message : String(error))
+const nowOf = (deps = {}) => (typeof deps.now === 'function' ? Number(deps.now()) : Date.now())
+
+// ── ① 配置：路径 / 默认值 / 归一化 / 原子读 / 原子写 ────────────────────────────────────
+function autoUpdateConfigPath(home = undefined) {
+  return join(home ?? dshHome(), 'plugin-console', CONFIG_FILE)
+}
+
+/** 默认配置（`enabled: true` —— 用户要的"默认打开"）。 */
+function defaultAutoUpdateConfig() {
+  return { enabled: true, intervalHours: DEFAULT_INTERVAL_HOURS, lastCheckAt: null, lastResult: null }
+}
+
+/** 把磁盘上的原始对象归一成合法配置：不合法的项按默认值、并逐项记下"哪里说不过去"。 */
+function normalizeAutoUpdateConfig(raw) {
+  const base = defaultAutoUpdateConfig()
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return { config: base, problems: ['顶层不是对象'] }
+  const problems = []
+  const out = { ...base }
+  if (typeof raw.enabled === 'boolean') out.enabled = raw.enabled
+  else if (raw.enabled !== undefined) problems.push('enabled 不是布尔值')
+  if (Number.isFinite(Number(raw.intervalHours)) && Number(raw.intervalHours) > 0) {
+    out.intervalHours = Math.min(168, Math.max(1, Number(raw.intervalHours)))
+  } else if (raw.intervalHours !== undefined) problems.push('intervalHours 不是正数')
+  if (Number.isFinite(Number(raw.lastCheckAt)) && Number(raw.lastCheckAt) > 0) out.lastCheckAt = Number(raw.lastCheckAt)
+  else if (raw.lastCheckAt !== undefined && raw.lastCheckAt !== null) problems.push('lastCheckAt 不是时间戳')
+  if (raw.lastResult !== null && raw.lastResult !== undefined) {
+    if (typeof raw.lastResult === 'object' && raw.lastResult !== null && !Array.isArray(raw.lastResult)) out.lastResult = raw.lastResult
+    else problems.push('lastResult 不是对象')
+  }
+  return { config: out, problems }
+}
+
+/**
+ * 读配置。**只读**：读坏/形状不对 ⇒ 回默认值 + 一条如实 note，**绝不在这一步写盘**
+ * （用户的文件不能被"读一下就改掉"，规矩见本文件头 ①）。
+ * 返回 `{ config, file, present, corrupt, note }`。
+ */
+function readAutoUpdateConfig({ home = undefined, deps = {} } = {}) {
+  const dir = home ?? deps.home
+  const file = autoUpdateConfigPath(dir)
+  const read = typeof deps.readFile === 'function' ? deps.readFile : readFileSync
+  const exists = typeof deps.exists === 'function' ? deps.exists : existsSync
+  if (exists(file) !== true) return { config: defaultAutoUpdateConfig(), file, present: false, corrupt: false, note: null }
+  let raw = null
+  try {
+    raw = JSON.parse(read(file, 'utf8'))
+  } catch (error) {
+    return {
+      config: defaultAutoUpdateConfig(), file, present: true, corrupt: true,
+      note: `自动更新配置读不出来（${file}）：${label(error)} —— 本次按默认值（开启、每 ${DEFAULT_INTERVAL_HOURS} 小时）继续，**没有覆盖你的文件**`,
+    }
+  }
+  const { config, problems } = normalizeAutoUpdateConfig(raw)
+  if (problems.length === 0) return { config, file, present: true, corrupt: false, note: null }
+  return {
+    config, file, present: true, corrupt: true,
+    note: `自动更新配置有 ${problems.length} 处说不过去（${problems.join('；')}，文件 ${file}）—— 这几项按默认值处理，**没有覆盖你的文件**`,
+  }
+}
+
+/**
+ * 写配置（**原子**：临时文件 + rename；失败只回 note，绝不抛）。
+ * 只覆盖调用方点名的字段，其余沿用磁盘上的现值（读坏了就按默认值）。
+ * `patch.lastResult === null` 表示**清空**该字段；`undefined` 表示不动它。
+ */
+function writeAutoUpdateConfig(patch = {}, { home = undefined, deps = {} } = {}) {
+  const dir = home ?? deps.home
+  const file = autoUpdateConfigPath(dir)
+  const read = readAutoUpdateConfig({ home: dir, deps })
+  const next = { ...read.config }
+  if (typeof patch.enabled === 'boolean') next.enabled = patch.enabled
+  if (Number.isFinite(Number(patch.intervalHours)) && Number(patch.intervalHours) > 0) {
+    next.intervalHours = Math.min(168, Math.max(1, Number(patch.intervalHours)))
+  }
+  if (Number.isFinite(Number(patch.lastCheckAt)) && Number(patch.lastCheckAt) > 0) next.lastCheckAt = Number(patch.lastCheckAt)
+  if (patch.lastResult !== undefined) next.lastResult = patch.lastResult
+  const tmp = `${file}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 8)}`
+  let keepNote = null
+  // 磁盘上那份**读不出来**时，先把原件改名留档再写 —— 用户的内容一个字都不丢（规矩见 readAutoUpdateConfig）：
+  // 换个名字放着，并如实写进 note（`auto-update.json.corrupt-<时间戳>`）。
+  if (read.corrupt === true && read.present === true) {
+    const kept = `${file}.corrupt-${String(nowOf(deps)).padStart(13, '0')}`
+    try {
+      renameSync(file, kept)
+      keepNote = `原来那份读不出来的配置已改名保留为 ${kept}（没有删除）`
+    } catch (error) {
+      keepNote = `原来那份读不出来的配置没能改名保留（${label(error)}）`
+    }
+  }
+  try {
+    mkdirSync(dirname(file), { recursive: true })
+    writeFileSync(tmp, `${JSON.stringify(next, null, 2)}\n`, 'utf8')
+    renameSync(tmp, file) // 同目录 rename：要么旧文件、要么新文件，不会读到写了一半的 JSON
+    return { ok: true, config: next, file, note: [read.note, keepNote].filter((x) => typeof x === 'string' && x !== '').join('；') || null }
+  } catch (error) {
+    try { rmSync(tmp, { force: true }) } catch {}
+    return { ok: false, config: next, file, note: `写自动更新配置失败（${file}）：${label(error)}` }
+  }
+}
+
+// ── ② 忙判据（都是既有实现的复用，不自己猜状态）───────────────────────────────────────
+/** 正在运行的这一份包根的版本（profile 里读不到时用它兜底；读不到返回 null）。 */
+function runningVersionOf(deps = {}) {
+  const read = typeof deps.readFile === 'function' ? deps.readFile : readFileSync
+  try {
+    const pkg = JSON.parse(read(join(pluginRoot(), 'package.json'), 'utf8'))
+    return typeof pkg?.version === 'string' && pkg.version !== '' ? pkg.version : null
+  } catch { return null }
+}
+
+/** 框架升级状态（`<DSH_HOME>/plugin-console/fw-upgrade-state.txt`，格式 `status|message`）。 */
+function readFrameworkUpgradeStatus({ home = undefined, deps = {} } = {}) {
+  const file = join(home ?? deps.home ?? dshHome(), 'plugin-console', 'fw-upgrade-state.txt')
+  const exists = typeof deps.exists === 'function' ? deps.exists : existsSync
+  if (exists(file) !== true) return null
+  let raw = ''
+  try { raw = String((typeof deps.readFile === 'function' ? deps.readFile : readFileSync)(file, 'utf8')) } catch { return null }
+  if (raw.charCodeAt(0) === 0xFEFF) raw = raw.slice(1) // PS5.1 Set-Content -Encoding UTF8 会写 BOM
+  const head = String(raw.split('|')[0] ?? '').trim()
+  let at = null
+  try { at = statSync(file).mtimeMs } catch { at = null }
+  return { status: head === '' ? 'idle' : head, at }
+}
+
+/**
+ * 框架升级是否**正在进行中**（是 ⇒ 返回 `{ status, ageMs }`，否则 null）。
+ * 判据与 `/framework-upgrade-status` 同口径：非终止状态 + 状态文件在 15 分钟窗口内。
+ * 为什么要窗口：那条路由把"非终止状态但超过 15 分钟没动静"判为上次升级的残留并自愈成 idle，
+ * 这里如果照旧当"在升级"，自动更新会被一份陈旧记录永久挡住。
+ */
+function frameworkUpgradeBusy({ home = undefined, deps = {} } = {}) {
+  const state = readFrameworkUpgradeStatus({ home, deps })
+  if (state === null) return null
+  if (FW_TERMINAL_STATUS.has(state.status) === true) return null
+  if (state.at === null) return { status: state.status, ageMs: null }
+  const ageMs = nowOf(deps) - state.at
+  if (ageMs > FW_STATE_STALE_MS) return null
+  return { status: state.status, ageMs }
+}
+
+/** 有安装作业在跑？宿主侧能注入 `deps.installBusy`（内存作业表最准）；没注入就只看**包锁**。 */
+function installBusyOf({ profileDir = '', packageName = '', deps = {} } = {}) {
+  if (typeof deps.installBusy === 'function') {
+    let verdict = null
+    try { verdict = deps.installBusy() } catch (error) { return `安装作业表读不出来：${label(error)}` }
+    if (typeof verdict === 'string' && verdict !== '') return verdict
+    if (verdict !== null && verdict !== undefined && verdict !== false) return '有安装作业正在跑'
+  }
+  const holder = installLockHolder(profileDir, packageName)
+  if (holder === null) return null
+  return `这个包正在安装中（另一个作业 ${holder.jobId ?? '未命名'} 从 ${holder.since ?? '?'} 起占着锁）`
+}
+
+/** 远端是否**严格高于**本地：`1` 是、`0/-1` 否、`null` = 版本号不可比（不敢动）。 */
+function compareVersions(remote, local) {
+  const a = parseSemverText(remote)
+  const b = parseSemverText(local)
+  if (a === null || b === null) return null
+  return compareSemverText(a, b)
+}
+
+// ── ③ 一次检查 + 一次安装（编排；装/备份/自愈全是既有实现）──────────────────────────────
+/**
+ * 在**包锁**里做一次真实的覆盖式安装（拿不到锁 ⇒ 什么都不做）。
+ * 返回 `{ ok, reason, version, backedUp, healed, manualCommand, overlay, entry }`。
+ */
+async function attemptOverlayUpdate({ target, latest, profileDir, registries, deps = {} } = {}) {
+  const overlay = typeof deps.runOverlay === 'function' ? deps.runOverlay : runSelfOverlayInstall
+  const beginGuard = typeof deps.beginGuard === 'function' ? deps.beginGuard : beginSelfUpdateGuard
+  const settleGuard = typeof deps.settleGuard === 'function' ? deps.settleGuard : settleSelfUpdateGuard
+  const out = { ok: false, reason: null, version: null, backedUp: false, healed: false, manualCommand: null, overlay: null }
+  const locked = await withInstallLockOr(
+    { profileDir, packageName: target, waitMs: 0 }, // waitMs=0：有人占着就立刻放弃，绝不排队等
+    async () => {
+      // 更新前备份 + "磁盘上本来就有可解析的自身副本"这道闸都在 beginSelfUpdateGuard 里（规矩② 的既有实现）
+      const session = beginGuard({ packageName: target, profileDir, targetVersion: latest, deps })
+      if (session === null) {
+        return { noSession: true }
+      }
+      out.backedUp = session.backedUp === true
+      // 点名目标版本 ⇒ 覆盖式安装自己会跳过 registry 探测，并按"读回版本 === 目标版本"核对（既有实现）
+      const overlayResult = await overlay({
+        job: { packageName: target, version: latest },
+        packageName: target, profileDir, registries, deps,
+      })
+      out.overlay = overlayResult
+      out.version = overlayResult?.version ?? null
+      out.ok = overlayResult?.ok === true && out.version === latest
+      // 收尾（**无论成败都跑**）：校验 → 不过就改名挪开 + 从备份恢复 + 同一判据复核 → 产出 manualCommand。
+      // 期望版本只在"这次真装上了"时才要求是 latest；装失败时期望值置空 =
+      // "目录里得仍是一份完整的自身副本"，坏了才自愈 —— 否则每失败一次就把好目录改名成 .broken-。
+      const settled = settleGuard(session, { targetVersion: out.ok === true ? latest : null, landed: out.ok === true, deps })
+      out.healed = settled?.healed === true
+      out.manualCommand = settled?.manualCommand ?? null
+      if (out.ok !== true) {
+        const parts = [overlayResult?.reason ?? '覆盖式安装没有成功']
+        if (settled?.healed === true) parts.push(`已从更新前的备份恢复成 v${settled.restoredVersion ?? '?'}（本次更新**没有生效**）`)
+        else if (settled?.verified === true) parts.push(`磁盘上仍是完整的一份旧副本（v${settled.restoredVersion ?? '?'}），没有动它`)
+        else parts.push(`校验也没过：${settled?.reason ?? '原因未知'}`)
+        out.reason = parts.join('；')
+      } else {
+        out.reason = null
+      }
+      return { done: true }
+    },
+    (error) => ({ lockTimeout: true, error }),
+  )
+  if (locked?.lockTimeout === true) {
+    return { ...out, ok: false, busy: true, reason: `拿不到安装锁（${label(locked.error)}）—— 本轮不做自更新` }
+  }
+  if (locked?.noSession === true) {
+    return {
+      ...out, ok: false, noSession: true,
+      reason: `磁盘上没有可解析的自身副本（${join(profileDir, 'node_modules', ...String(target).split('/'))}）—— `
+        + '自动更新不接管首次安装 / 链接安装；需要时请用卡片上的「更新」按钮',
+    }
+  }
+  return out
+}
+
+/**
+ * **一次检查（必要时安装）** —— 本模块的唯一编排入口。
+ * 返回 `{ checked, from, to, updated, reason, skipped? }`（另附 ok/at/version/backedUp/healed/manualCommand/
+ * packageName/channel/configNote 等如实字段，只增不删）。
+ * `targetPackage` 只用于**拒绝**：不是本插件自己的包名一律 `skipped:'not-self'`（规矩 ①）。
+ */
+async function checkAndUpdate({ deps = {}, profileDir = null, targetPackage = null } = {}) {
+  const io = deps
+  const at = nowOf(io)
+  const selfName = selfPackageNameOf(io)
+  const dir = typeof profileDir === 'string' && profileDir !== ''
+    ? profileDir
+    : (typeof io.profileDir === 'string' ? io.profileDir : '')
+  const out = {
+    checked: false, from: null, to: null, updated: false, reason: null, skipped: null,
+    ok: false, at, version: null, channel: null, packageName: null,
+    backedUp: false, healed: false, manualCommand: null, configNote: null,
+  }
+  const target = typeof targetPackage === 'string' && targetPackage !== '' ? targetPackage : selfName
+  out.packageName = target
+  if (isSelfUpdate(target, io) !== true) {
+    out.skipped = 'not-self'
+    out.reason = `自动更新只对控制台自己生效（${target} 不是 ${selfName}），已拒绝`
+    return out
+  }
+  const read = readAutoUpdateConfig({ deps: io })
+  out.configNote = read.note
+  const config = read.config
+  out.from = readInstalledVersion(dir, target) ?? runningVersionOf(io)
+  if (config.enabled !== true) {
+    out.skipped = 'disabled'
+    out.reason = '自动更新已关闭（功能包 → [自更新] 开关）'
+    return out
+  }
+  // ② 忙判据：有安装作业 / 包锁被占 ⇒ 本轮零动作（连 registry 都不打）
+  const installBusy = installBusyOf({ profileDir: dir, packageName: target, deps: io })
+  if (installBusy !== null) {
+    out.skipped = 'busy'
+    out.reason = `${installBusy} —— 本轮不做自更新`
+    return out
+  }
+  // ③ 框架升级进行中 ⇒ 本轮零动作（框架正在换整棵树，这时候动插件目录毫无意义）
+  const fwBusy = typeof io.frameworkUpgradeBusy === 'function' ? io.frameworkUpgradeBusy() : frameworkUpgradeBusy({ deps: io })
+  if (fwBusy !== null && fwBusy !== undefined && fwBusy !== false) {
+    out.skipped = 'framework-upgrade'
+    out.reason = `框架升级进行中（状态 ${typeof fwBusy === 'object' ? (fwBusy.status ?? '?') : String(fwBusy)}）—— 本轮不做自更新`
+    return out
+  }
+  // ④ 查远端版本（复用既有探针 probeRegistryPackage：与 install-self-overlay 同一个口径）
+  const registries = Array.isArray(io.registries) ? io.registries : preferredRegistries()
+  const probe = typeof io.probeRegistry === 'function' ? io.probeRegistry : probeRegistryPackage
+  out.checked = true
+  let latest = null
+  try {
+    const found = await probe(target, registries, { fetchJson: io.fetchJson, timeoutMs: io.metaTimeoutMs })
+    latest = typeof found?.latest === 'string' && found.latest !== '' ? found.latest : null
+    if (found?.resolvable !== true || latest === null) {
+      const tried = Array.isArray(found?.tried) && found.tried.length > 0 ? `（${found.tried.join('；')}）` : ''
+      out.reason = `探测不到 ${target} 的最新版本${tried}`
+      return persistResult(out, { deps: io })
+    }
+  } catch (error) {
+    out.reason = `探测最新版本失败：${label(error)}`
+    return persistResult(out, { deps: io })
+  }
+  out.to = latest
+  // ⑤ 只在远端**严格更高**时才装（相等 / 更低 / 不可比 ⇒ 不装）
+  const cmp = compareVersions(latest, out.from)
+  if (cmp === null) {
+    out.reason = `版本号不可比（本地 ${out.from ?? '读不到'}，远端 ${latest}）—— 不敢自动更新`
+    return persistResult(out, { deps: io })
+  }
+  if (cmp <= 0) {
+    out.skipped = 'up-to-date'
+    out.ok = true
+    out.reason = `已是最新（本地 ${out.from}，远端 ${latest}）`
+    return persistResult(out, { deps: io, lastResult: { failedVersion: null, failedAt: null } })
+  }
+  // ⑥ 失败退避：同一个目标版本在 6 小时窗口内失败过 ⇒ 不重试（防无限循环刷日志）
+  const last = config.lastResult !== null && typeof config.lastResult === 'object' ? config.lastResult : null
+  const failedVersion = last !== null && typeof last.failedVersion === 'string' ? last.failedVersion : null
+  const failedAt = last !== null && Number.isFinite(Number(last.failedAt)) ? Number(last.failedAt) : null
+  if (failedVersion !== null && failedVersion === latest && failedAt !== null && at - failedAt < RETRY_BACKOFF_MS) {
+    const minutes = Math.max(1, Math.round((RETRY_BACKOFF_MS - (at - failedAt)) / 60000))
+    out.skipped = 'backoff'
+    out.ok = true
+    out.reason = `${latest} 这个版本上次装失败了，${Math.round(RETRY_BACKOFF_MS / HOUR_MS)} 小时冷却中（还要等约 ${minutes} 分钟）`
+    return persistResult(out, { deps: io })
+  }
+  // ⑦ 真装（覆盖式，零 pnpm）
+  out.channel = 'manual-overlay'
+  const attempt = await attemptOverlayUpdate({ target, latest, profileDir: dir, registries, deps: io })
+  out.backedUp = attempt.backedUp === true
+  out.healed = attempt.healed === true
+  out.manualCommand = attempt.manualCommand ?? null
+  out.version = attempt.version ?? null
+  out.ok = attempt.ok === true
+  out.updated = attempt.ok === true
+  out.reason = attempt.ok === true
+    ? `已用覆盖式安装升到 v${latest}（只覆盖、没有清空目录，全程没有调用包管理器）—— **重启服务后生效**`
+    : (attempt.reason ?? '覆盖式安装没有成功')
+  if (attempt.ok !== true && attempt.manualCommand !== null) out.reason += `；要手动处理可直接复制运行：${attempt.manualCommand}`
+  return persistResult(out, { deps: io })
+}
+
+/**
+ * 把本轮结论落盘（`lastCheckAt` + `lastResult`）。写盘失败只并入 note，绝不抛。
+ * `failedVersion/failedAt`：装失败时记下（退避要用）；成功时清空；"没装"的轮次沿用上一轮（不能把退避弄丢）。
+ * 只有真的**查过**（`checked === true`）才写盘 —— 关闭 / 忙 / 框架升级中的轮次零写盘。
+ */
+function persistResult(out, { deps = {}, lastResult = null } = {}) {
+  if (out.checked !== true) return out
+  const previous = readAutoUpdateConfig({ deps }).config.lastResult
+  const prevFailedVersion = previous !== null && typeof previous === 'object' && typeof previous.failedVersion === 'string' ? previous.failedVersion : null
+  const prevFailedAt = previous !== null && typeof previous === 'object' && Number.isFinite(Number(previous.failedAt)) ? Number(previous.failedAt) : null
+  const installed = out.updated === true
+  const attempted = out.channel !== null
+  const next = {
+    at: out.at,
+    ok: out.ok === true,
+    updated: out.updated === true,
+    from: out.from ?? null,
+    to: out.to ?? null,
+    version: out.version ?? null,
+    skipped: out.skipped ?? null,
+    reason: out.reason ?? null,
+    channel: out.channel ?? null,
+    failedVersion: installed ? null : (attempted === true ? (out.to ?? null) : (lastResult?.failedVersion ?? prevFailedVersion)),
+    failedAt: installed ? null : (attempted === true ? out.at : (lastResult?.failedAt ?? prevFailedAt)),
+  }
+  const written = writeAutoUpdateConfig({ lastCheckAt: out.at, lastResult: next }, { deps })
+  // 写盘那边可能有话要说（比如"读不出来的原件已改名留档"）—— 如实并进 configNote，绝不错过
+  if (typeof written.note === 'string' && written.note !== '') {
+    out.configNote = [out.configNote, written.note].filter((x) => typeof x === 'string' && x !== '').join('；')
+  }
+  if (written.ok !== true) out.reason = `${out.reason ?? ''}${out.reason === null ? '' : '；'}${written.note ?? '写配置失败'}`
+  return out
+}
+
+// ── ④ 给 /state 与面板用的只读视图 ─────────────────────────────────────────────────
+/** `/state.selfAutoUpdate` 的形状（字段固定，**不编造**：拿不到的项就是 null，界面显示"—"）。 */
+function selfAutoUpdateState({ deps = {}, profileDir = null } = {}) {
+  const read = readAutoUpdateConfig({ deps })
+  const selfName = selfPackageNameOf(deps)
+  const dir = typeof profileDir === 'string' && profileDir !== ''
+    ? profileDir
+    : (typeof deps.profileDir === 'string' ? deps.profileDir : '')
+  const currentVersion = readInstalledVersion(dir, selfName) ?? runningVersionOf(deps)
+  const view = {
+    enabled: read.config.enabled === true,
+    intervalHours: read.config.intervalHours,
+    lastCheckAt: read.config.lastCheckAt,
+    lastResult: read.config.lastResult,
+    currentVersion,
+  }
+  if (read.note !== null) view.note = read.note
+  return view
+}
+
+// ── ⑤ 调度：进程内定时器（单飞 / unref / 异常吞成一条记录）──────────────────────────────
+const scheduler = { started: false, timer: null, running: false, deps: null, runs: 0, lastError: null }
+
+/** 下一轮间隔（每次现读配置：用户改 intervalHours 立刻生效）。读不到就按默认值。 */
+function nextIntervalMs(deps = {}) {
+  const read = readAutoUpdateConfig({ deps })
+  const hours = Number.isFinite(Number(read.config.intervalHours)) && Number(read.config.intervalHours) > 0
+    ? Number(read.config.intervalHours) : DEFAULT_INTERVAL_HOURS
+  return Math.max(1, hours) * HOUR_MS
+}
+
+/** 调度里出的任何异常都只变成**一条如实记录**（绝不影响宿主，也绝不静默）。 */
+function recordSchedulerFailure(error, { deps = {} } = {}) {
+  const at = nowOf(deps)
+  try {
+    const previous = readAutoUpdateConfig({ deps }).config.lastResult
+    writeAutoUpdateConfig({
+      lastCheckAt: at,
+      lastResult: {
+        at, ok: false, updated: false, from: null, to: null, version: null, skipped: null,
+        reason: `自更新检查抛错：${label(error)}`, channel: null,
+        failedVersion: previous !== null && typeof previous === 'object' ? (previous.failedVersion ?? null) : null,
+        failedAt: previous !== null && typeof previous === 'object' ? (previous.failedAt ?? null) : null,
+      },
+    }, { deps })
+  } catch { /* 连记录都写不进去：那也不许影响宿主 */ }
+}
+
+/** 单飞的一次检查（`/self-auto-update` 的"立即检查"与定时器共用）：上一轮没跑完就直接回 busy。 */
+async function runCheckOnce({ deps = {}, profileDir = null } = {}) {
+  if (scheduler.running === true) {
+    return {
+      checked: false, from: null, to: null, updated: false, ok: true, skipped: 'busy',
+      at: nowOf(deps), reason: '上一轮自更新检查还没跑完（单飞，不叠下一轮）',
+      version: null, channel: null, packageName: null, backedUp: false, healed: false, manualCommand: null, configNote: null,
+    }
+  }
+  scheduler.running = true
+  try {
+    const result = await checkAndUpdate({ deps, profileDir })
+    scheduler.runs += 1
+    return result
+  } finally {
+    scheduler.running = false
+  }
+}
+
+function clearSchedulerTimer() {
+  if (scheduler.timer !== null) {
+    try { clearTimeout(scheduler.timer) } catch {}
+    scheduler.timer = null
+  }
+}
+
+function scheduleNext(delayMs, deps) {
+  clearSchedulerTimer()
+  const timer = setTimeout(() => {
+    scheduler.timer = null
+    void tick(deps)
+  }, Math.max(0, Number(delayMs) || 0))
+  // 绝不阻塞进程退出（宿主关掉就该立刻退出，不等这一轮）
+  if (typeof timer?.unref === 'function') timer.unref()
+  scheduler.timer = timer
+  return timer
+}
+
+/** 一轮定时检查：异常吞成记录，之后永远排下一轮（除非已 stop）。 */
+async function tick(deps) {
+  if (scheduler.started !== true) return
+  try {
+    await runCheckOnce({ deps })
+  } catch (error) {
+    scheduler.lastError = label(error)
+    recordSchedulerFailure(error, { deps })
+  } finally {
+    if (scheduler.started === true) scheduleNext(nextIntervalMs(deps), deps)
+  }
+}
+
+/**
+ * 启动调度（**幂等**：重复调用只返回"已经启动过"，不会再排一个定时器）。
+ * 首检延迟默认 2 分钟（`deps.firstDelayMs` 可注入），之后按配置的 intervalHours 轮转。
+ */
+function startSelfAutoUpdateScheduler({ deps = {} } = {}) {
+  if (scheduler.started === true) return { started: true, alreadyStarted: true, firstDelayMs: null }
+  scheduler.started = true
+  scheduler.deps = deps
+  const firstDelayMs = Number.isFinite(Number(deps.firstDelayMs)) && Number(deps.firstDelayMs) >= 0
+    ? Number(deps.firstDelayMs) : DEFAULT_FIRST_DELAY_MS
+  try {
+    scheduleNext(firstDelayMs, deps)
+  } catch (error) {
+    scheduler.lastError = label(error)
+    scheduler.started = false
+    return { started: false, alreadyStarted: false, firstDelayMs, note: `自更新调度没能启动：${label(error)}` }
+  }
+  return { started: true, alreadyStarted: false, firstDelayMs }
+}
+
+/** 停掉调度（宿主卸载 / 测试收尾用；不抛）。 */
+function stopSelfAutoUpdateScheduler() {
+  scheduler.started = false
+  clearSchedulerTimer()
+  return { stopped: true }
+}
+
+/** 调度现状（诊断 / 测试用；`ref` = 定时器是否还"引用"着事件循环，`false` 才是不阻塞进程退出）。 */
+function selfAutoUpdateSchedulerState() {
+  const timer = scheduler.timer
+  return {
+    started: scheduler.started, running: scheduler.running, hasTimer: timer !== null,
+    ref: timer !== null && typeof timer.hasRef === 'function' ? timer.hasRef() : null,
+    runs: scheduler.runs, lastError: scheduler.lastError,
+  }
+}
+
+export {
+  CONFIG_FILE, DEFAULT_FIRST_DELAY_MS, DEFAULT_INTERVAL_HOURS, RETRY_BACKOFF_MS, FW_STATE_STALE_MS,
+  autoUpdateConfigPath, defaultAutoUpdateConfig, normalizeAutoUpdateConfig, readAutoUpdateConfig, writeAutoUpdateConfig,
+  readFrameworkUpgradeStatus, frameworkUpgradeBusy, installBusyOf, runningVersionOf, compareVersions,
+  attemptOverlayUpdate, checkAndUpdate, persistResult, selfAutoUpdateState,
+  nextIntervalMs, runCheckOnce, startSelfAutoUpdateScheduler, stopSelfAutoUpdateScheduler, selfAutoUpdateSchedulerState,
+  recordSchedulerFailure,
+}

package/lib/server/routes/index.js

@@ -40,6 +40,13 @@ import { routeGiteeOauthCallbackGet, routeGiteeOauthUrlGet, routeRegistryScan, r
 import { routeCompatExempt, routeDetails, routeDevRoots, routeLinksGet, routePinDevDir, routeStateGet } from './state.js'
 // 0.5.87 加法：link 面板的写动作（补依赖/垫片 + 取消钉住）—— 判据在 domain 层，这里只做白名单与回包
 import { routeLinkRepair, routeUnpinDevDir } from './link-actions.js'
+// ★ 加法（用户 2026-11-04：功能包里的 [自更新] 开关）：控制台**只更新它自己**的自动更新。
+//   写动作单独一条路由（能给这个动作腾行数的三个文件都在 600 行棘轮上，见 routes/self-auto-update.js 顶部）。
+import { routeSelfAutoUpdate } from './self-auto-update.js'
+// 调度：进程内定时器（启动后约 2 分钟首检 + 每 intervalHours 一次，单飞、unref，异常只吞成一条记录）。
+// 为什么在这里启动而不是 lib/index.js 的 apply()：那个文件贴着 142/142 行棘轮**一行都加不了**
+// （tests/test-architecture-guard.mjs 的 INDEX_LIMIT 只允许下调），而本文件被它 import ⇒ 加载即插件启动。
+import { startSelfAutoUpdateScheduler } from '../domain/self-auto-update.js'
 
 const ROUTE_PREFIX = '/plugin-console'
 
@@ -208,7 +215,18 @@ const ROUTES = [
   { methods: ['POST'], path: `${ROUTE_PREFIX}/disk-cleanup`, handler: routeDiskCleanup },
   // 结构化建议动作（2026-09-27 加法）：只认白名单动作类型，argv 由服务端自拼（绝不接受命令字符串）
   { methods: ['POST'], path: `${ROUTE_PREFIX}/run-suggested`, handler: routeRunSuggested },
+  // ★ 加法（用户 2026-11-04）：[自更新] 开关的读写 + 「立即检查」。
+  //   只对控制台自己生效：请求体里的 packageName 只用于**拒绝**非自身的包名（判据在 domain 层）。
+  { methods: ['POST'], path: `${ROUTE_PREFIX}/self-auto-update`, handler: routeSelfAutoUpdate },
 
 ]
 
+// ── 自更新调度（★ 加法）────────────────────────────────────────────────────────────
+// 模块加载 = 插件启动：排一次首检（默认 2 分钟后），之后每 intervalHours 一轮。
+// 三道保险，任何一道都不许省：
+//   ① try/catch —— 调度起不来**绝不影响宿主启动**（用户红线：自动更新失败不能拖垮服务）；
+//   ② 幂等 —— 重复加载只启动一次（startSelfAutoUpdateScheduler 自带 started 标记）；
+//   ③ unref —— 定时器不阻塞进程退出（见 domain/self-auto-update.js#scheduleNext）。
+try { startSelfAutoUpdateScheduler() } catch { /* 静默：调度器自己会把失败记成一条 lastResult */ }
+
 export { ROUTE_PREFIX, handle }

package/lib/server/routes/self-auto-update.js

@@ -0,0 +1,78 @@
+// L2 · routes —— POST /plugin-console/self-auto-update（「自更新」开关的读写 + 「立即检查」；2026-11-04 加法）
+//
+// 为什么新开一条路由而不是塞进既有路由：能给这个动作腾位置的三个文件都贴着行数棘轮
+// （`routes/framework.js` 600/600、`routes/framework-upgrade.js` 699/700、`domain/self-update-guard.js` 600/600），
+// `/self-update` 所在的 `routes/plugins.js` 又只表示"按 latest 装一次"、语义不同（那个动作不看开关、不排队、不等定时器）。
+// 所以按仓库既有做法**新开一条**，并同步登记 `tests/test-route-inventory.mjs`（漏登记会红）。
+//
+// 契约（只增不减）：
+//   · `{ action: 'toggle' | 'set-enabled', enabled?: boolean }` → `{ ok, selfAutoUpdate, note }`
+//     不给 `enabled` 就是"翻转当前值"（面板点一下的语义）；给了就照给的值设。
+//   · `{ action: 'check' | 'check-now' }` → `{ ok, check, selfAutoUpdate }`
+//     `check` 是 domain/self-auto-update.js#checkAndUpdate 的**完整原样结构**
+//     （`{ checked, from, to, updated, reason, skipped? }` + 如实字段）。
+//   · 都认 `packageName`，但**只用于拒绝**：只要不是控制台自己 ⇒ `check.skipped = 'not-self'`。
+//     本文件绝不把请求体里的包名当成"要装的目标"（自动更新只对自己生效）。
+//   · 入参不认识 ⇒ 400 + 可读原因（绝不 200 假装做过什么）。
+//
+// 判据全部在 domain 层（配置读坏降级、忙判据、版本比对、覆盖式安装、退避、自愈）；这里只做
+// 「取宿主信息 → 调 domain → 回包」，一个判断都不自己写。
+import { dirname } from 'node:path'
+import { readAutoUpdateConfig, runCheckOnce, selfAutoUpdateState, writeAutoUpdateConfig } from '../domain/self-auto-update.js'
+import { findPatchPath } from '../infra/paths.js'
+import { sendError, sendJson } from '../infra/httpd.js'
+import { installJobs } from '../state.js'
+
+/**
+ * 宿主侧要注入给 domain 的两件事（domain 不认识 cordis，所以由这一层取好传下去）：
+ *   · profileDir —— 覆盖式安装的落点（与 /install、/self-update 同一个推导方式）；
+ *   · installBusy —— 内存里的作业表最准：只要还有作业在 `installing`，本轮就别动目录
+ *     （包锁只覆盖"正在动这个目录"的那一小段，作业在换通道 / 等授权时锁是空的）。
+ */
+function autoUpdateDeps(ctx) {
+  let profileDir = ''
+  try { profileDir = dirname(findPatchPath(ctx)) } catch { profileDir = '' }
+  return {
+    profileDir,
+    installBusy: () => {
+      try {
+        for (const job of installJobs.values()) {
+          if (job !== null && job !== undefined && job.status === 'installing') {
+            return `有安装作业正在跑（${job.id ?? '未命名作业'}：${job.packageName ?? job.repo ?? '未知目标'}）`
+          }
+        }
+      } catch { /* 作业表读不出来 ⇒ 交给包锁那道闸，别在这里编一个"忙" */ }
+      return null
+    },
+  }
+}
+
+async function routeSelfAutoUpdate(req, res, rc) {
+  const action = typeof rc.body?.action === 'string' ? rc.body.action.trim() : ''
+  const deps = autoUpdateDeps(rc.ctx)
+  const requested = typeof rc.body?.packageName === 'string' ? rc.body.packageName.trim() : ''
+  if (action === 'toggle' || action === 'set-enabled') {
+    const read = readAutoUpdateConfig({ deps })
+    const wanted = typeof rc.body?.enabled === 'boolean' ? rc.body.enabled : read.config.enabled !== true
+    const written = writeAutoUpdateConfig({ enabled: wanted }, { deps })
+    if (written.ok !== true) {
+      // 写不进去就如实失败（面板显示错误原文），绝不回一个"看起来切过去了"的状态
+      sendError(res, 500, written.note ?? '写自更新配置失败')
+      return
+    }
+    const note = [read.note, written.note].filter((x) => typeof x === 'string' && x !== '').join('；')
+    sendJson(res, 200, { ok: true, selfAutoUpdate: selfAutoUpdateState({ deps }), note: note === '' ? null : note })
+    return
+  }
+  if (action === 'check' || action === 'check-now') {
+    // 点「立即检查」与定时器是**同一条路**（单飞：定时器正在跑时这里回 skipped:'busy'，不叠第二轮）
+    const check = await runCheckOnce({ deps, targetPackage: requested === '' ? null : requested })
+    sendJson(res, 200, { ok: true, check, selfAutoUpdate: selfAutoUpdateState({ deps }) })
+    return
+  }
+  sendError(res, 400, action === ''
+    ? '没有提供 action（可用：toggle / set-enabled / check / check-now）'
+    : `不认识的 action：${action}（可用：toggle / set-enabled / check / check-now）`)
+}
+
+export { autoUpdateDeps, routeSelfAutoUpdate }

package/lib/server/routes/state.js

@@ -23,6 +23,9 @@ import { readBundlesSync } from '../domain/persist.js'
 import { lockAutofixStatus, scheduleLockAutofix } from '../domain/lock-autofix.js'
 import { failedJobEvidence } from '../domain/install-verify.js'
 import { installJobView, readGithubAuth } from '../domain/install.js'
+// ★ 加法（用户 2026-11-04 第 2 项）：功能包里的 [自更新] 开关 —— /state **只增**这一个字段，
+//   形状 { enabled, intervalHours, lastCheckAt, lastResult, currentVersion }（判据全在 domain/self-auto-update.js）。
+import { selfAutoUpdateState } from '../domain/self-auto-update.js'
 import { readPluginDetails } from '../domain/market.js'
 import { healPatchSafety, readPatchState } from '../domain/patch.js'
 import { pendingRestartJobs } from '../domain/revoke.js'
@@ -294,7 +297,7 @@ async function routeStateGet(req, res, rc) {
         loadFailedCount: loadFailed.length,
       }
     })()
-    sendJson(res, 200, { ok: true, entries: allEntries, skippedBundles, host, health, patchPath, compat, installJobs: jobs, recentFailures, pendingRestart, github: { loggedIn: auth.loggedIn, login: auth.login }, patch: { disables: patch.disables, forced: patch.forced, inserts: patch.inserts }, framework, lockAutofix, patchHeal: patchHeal === null ? null : { healed: patchHeal.healed ?? [], autoDisabled: patchHeal.autoDisabled ?? [], healedAt: patchHeal.healedAt ?? 0, written: patchHeal.written === true, writeError: patchHeal.writeError ?? null, skippedFrameworkOwned: (patchHeal.skipped ?? []).map((s) => s.id ?? null), uncertain: (patchHeal.uncertain ?? []).map((u) => u.id ?? null) }, gating: gatingOut, compatPending: compatPending === null ? null : { frameworkVersion: compatPending.frameworkVersion ?? null, upgradeFrom: compatPending.upgradeFrom ?? null, pending: (compatPending.pending ?? []).filter((p) => (p.status ?? 'pending') === 'pending').map((p) => ({ rowId: p.rowId, moduleName: p.moduleName, version: p.version ?? null, checkNote: p.checkNote ?? null, check: p.check ?? null, riskyApprovedAt: p.riskyApprovedAt ?? null, adoptable: adoptable.get(p.rowId) ?? null, verdict: compatVerdicts.get(p.rowId) ?? null })), verdictRefresh: pendingState.refresh === null ? null : { version: pendingState.refresh.version ?? null, updated: pendingState.refresh.updated ?? [], unchanged: pendingState.refresh.unchanged ?? [], unresolved: pendingState.refresh.unresolved ?? [], wrote: pendingState.refresh.wrote === true, writeError: pendingState.refresh.writeError ?? null }, actionableCount: pendingCounts.actionableCount, staleCount: pendingCounts.staleCount, lastScan: compatPending.lastScan ?? null }, compatGate, rollback: rollbackRec, selfVersion, components: findComponents().map((c) => ({ id: c.id, name: c.name, kind: c.kind ?? 'server', pid: c.pid ?? null, port: c.port ?? null, healthUrl: c.healthUrl ?? null, uiUrl: compUiUrl(c), autoStart: c.autoStart === true })) })
+    sendJson(res, 200, { ok: true, entries: allEntries, skippedBundles, host, health, patchPath, compat, installJobs: jobs, recentFailures, pendingRestart, github: { loggedIn: auth.loggedIn, login: auth.login }, patch: { disables: patch.disables, forced: patch.forced, inserts: patch.inserts }, framework, lockAutofix, patchHeal: patchHeal === null ? null : { healed: patchHeal.healed ?? [], autoDisabled: patchHeal.autoDisabled ?? [], healedAt: patchHeal.healedAt ?? 0, written: patchHeal.written === true, writeError: patchHeal.writeError ?? null, skippedFrameworkOwned: (patchHeal.skipped ?? []).map((s) => s.id ?? null), uncertain: (patchHeal.uncertain ?? []).map((u) => u.id ?? null) }, gating: gatingOut, compatPending: compatPending === null ? null : { frameworkVersion: compatPending.frameworkVersion ?? null, upgradeFrom: compatPending.upgradeFrom ?? null, pending: (compatPending.pending ?? []).filter((p) => (p.status ?? 'pending') === 'pending').map((p) => ({ rowId: p.rowId, moduleName: p.moduleName, version: p.version ?? null, checkNote: p.checkNote ?? null, check: p.check ?? null, riskyApprovedAt: p.riskyApprovedAt ?? null, adoptable: adoptable.get(p.rowId) ?? null, verdict: compatVerdicts.get(p.rowId) ?? null })), verdictRefresh: pendingState.refresh === null ? null : { version: pendingState.refresh.version ?? null, updated: pendingState.refresh.updated ?? [], unchanged: pendingState.refresh.unchanged ?? [], unresolved: pendingState.refresh.unresolved ?? [], wrote: pendingState.refresh.wrote === true, writeError: pendingState.refresh.writeError ?? null }, actionableCount: pendingCounts.actionableCount, staleCount: pendingCounts.staleCount, lastScan: compatPending.lastScan ?? null }, compatGate, rollback: rollbackRec, selfVersion, selfAutoUpdate: selfAutoUpdateState({ deps: { profileDir } }), components: findComponents().map((c) => ({ id: c.id, name: c.name, kind: c.kind ?? 'server', pid: c.pid ?? null, port: c.port ?? null, healthUrl: c.healthUrl ?? null, uiUrl: compUiUrl(c), autoStart: c.autoStart === true })) })
     return
 }
 

package/package.json

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