@noob-stupid/dsh-plugin-console 0.4.1 → 0.5.0

package/README.md

@@ -249,6 +249,7 @@ The floating "Sources" button (right of the title row, semi-transparent) opens t
 
 - [AI Empower 与服务器组件控制](docs/ai-empower.md)
 - [Framework upgrade safety & plugin adapt gate](docs/upgrade-safety-adapt-gate.md)
+- [**契约规则库 Upgrade contract rules**](docs/contracts/README.md) — 框架每次变更会打断什么、怎么发现、怎么修（数据在 `lib/contracts/rules.json`，**欢迎 PR 补充**：每个事故都应该变成一条规则）
 - [How it works](docs/how-it-works.md) · [Compatibility](docs/compatibility.md) · [Project layout](docs/project-layout.md)
 - [HTTP endpoints](docs/http-endpoints.md) · [Local AI fallback & consent](docs/ai-fallback.md)
 - [Framework patch (cordis.patch.yml)](docs/framework-patch.md) · [Security & disclaimer](docs/security-disclaimer.md)

package/lib/client.js

@@ -90,6 +90,37 @@ window.__ModuleLoader__.load({
 		//#region locales
 		const zh = {
 			tab: "插件管理",
+			safetyTab: "升级安全",
+			safetyMode: "运行模式",
+			safetyModeManaged: "托管：框架升级与回滚由本控制台负责（默认，行为与之前一致）",
+			safetyModeManagedOn: "已切到托管模式：框架升级与回滚仍由本控制台负责",
+			safetyModeObserver: "观察者：只做预检、门控与回滚点守护，不接管框架升级",
+			safetyModeObserverOn: "已切到观察者模式：不再接管框架升级，只守门",
+			safetyModeSwitch: "切换托管 / 观察者",
+			safetySwitchFailed: "操作失败",
+			safetyFrameworkTitle: "框架版本",
+			safetyFrameworkDesc: "当前 {v} —— 换版本、换安装根（npx 缓存 / 桌面端自带运行时）、框架树包数变化，都会记为一次环境变更",
+			safetyRollbackTitle: "回滚点",
+			safetyRollbackOk: "可用：{from} → {to}",
+			safetyRollbackNone: "不可用：{reason}",
+			safetyFpTitle: "环境指纹",
+			safetyFpStable: "环境未变化（与上次基线一致）",
+			safetyFpChanged: "检测到环境变更（谁改的都算）：{reasons}",
+			safetyFpAck: "知道了，记为基线",
+			safetyFpAcked: "已记为基线",
+			safetyAdaptTitle: "会话格式契约预检",
+			safetyAdaptDesc: "升级前后都能跑：扫本地生产方（agent 预设 + 已装插件）里的旧形状，能改的先备份再改",
+			safetyPreflightFound: "预检发现 {n} 处必须适配（点右侧按钮可自动适配并逐个备份）",
+			safetyPreflightPatched: "已适配 {n} 处（每个文件都留了 .bak-preflight-*）",
+			safetyJumpHint: "打开控制台功能（就地展开，不跳走、不换页）",
+			safetyJumpMarket: "插件市场",
+			safetyJumpSkills: "技能市场",
+			safetyJumpFramework: "框架升级 / 回滚",
+			safetyJumpGate: "门控明细",
+			safetyJumpSources: "软件源",
+			safetyJumpAi: "AI 部署",
+			safetyEmbedded: "控制台（就地展开，原有功能一个不少）",
+			safetyUnknown: "未知",
 			loading: "正在读取插件…",
 			error: "暂时无法读取插件。",
 			retry: "重试",
@@ -516,6 +547,37 @@ window.__ModuleLoader__.load({
 		};
 		const en = {
 			tab: "Plugin console",
+			safetyTab: "Upgrade safety",
+			safetyMode: "Operating mode",
+			safetyModeManaged: "Managed: this console owns framework upgrade and rollback (default, unchanged behaviour)",
+			safetyModeManagedOn: "Switched to managed: framework upgrade and rollback stay with this console",
+			safetyModeObserver: "Observer: preflight, gating and rollback-point guard only — does not take over upgrades",
+			safetyModeObserverOn: "Switched to observer: no longer takes over framework upgrades, only gates",
+			safetyModeSwitch: "Switch managed / observer",
+			safetySwitchFailed: "Action failed",
+			safetyFrameworkTitle: "Framework version",
+			safetyFrameworkDesc: "Currently {v} — a version change, a different install root (npx cache / bundled desktop runtime), or a tree size change all count as an environment change",
+			safetyRollbackTitle: "Rollback point",
+			safetyRollbackOk: "Available: {from} → {to}",
+			safetyRollbackNone: "Unavailable: {reason}",
+			safetyFpTitle: "Environment fingerprint",
+			safetyFpStable: "Unchanged since the last baseline",
+			safetyFpChanged: "Environment changed (whoever did it): {reasons}",
+			safetyFpAck: "Got it — set as baseline",
+			safetyFpAcked: "Baseline updated",
+			safetyAdaptTitle: "Session-format contract preflight",
+			safetyAdaptDesc: "Runs before or after an upgrade: scans local producers (agent presets + installed plugins) for legacy shapes; fixes are backed up first",
+			safetyPreflightFound: "{n} place(s) must be adapted (use the button to adapt with per-file backups)",
+			safetyPreflightPatched: "Adapted {n} place(s); every file kept a .bak-preflight-* backup",
+			safetyJumpHint: "Open console features (expanded in place — no navigation away)",
+			safetyJumpMarket: "Plugin market",
+			safetyJumpSkills: "Skill market",
+			safetyJumpFramework: "Framework upgrade / rollback",
+			safetyJumpGate: "Gating detail",
+			safetyJumpSources: "Registries",
+			safetyJumpAi: "AI deploy",
+			safetyEmbedded: "Console (expanded in place, nothing removed)",
+			safetyUnknown: "unknown",
 			loading: "Reading plugins…",
 			error: "Plugins are temporarily unavailable.",
 			retry: "Retry",
@@ -1240,7 +1302,7 @@ window.__ModuleLoader__.load({
 				return false;
 			}
 		}
-		function PluginConsoleTab({ t }) {
+		function PluginConsoleTab({ t, section = null }) {
 			const [state, setState] = react.useState({ status: "loading" });
 			const [busy, setBusy] = react.useState(null);
 			const [adaptUnlocking, setAdaptUnlocking] = react.useState(null);
@@ -1821,6 +1883,17 @@ window.__ModuleLoader__.load({
 			const [editGit, setEditGit] = react.useState(null);
 			// 软件源弹窗折叠分区：软件源默认展开，其余收起（避免弹窗过长）
 			const [openSections, setOpenSections] = react.useState({ registries: true, index: false, git: false, search: false, gitee: false });
+			// 官方风格入口（新 tab）传入 section 时就地展开对应功能。
+			// 不传 section 时（= 原有 tab 的调用方式）行为与改动前**完全一致** —— 纯加法。
+			react.useEffect(() => {
+				if (section === null) return;
+				if (section === "framework") setFwPanelOpen(true);
+				else if (section === "gate") setGateOpen(true);
+				else if (section === "sources") setSourcesOpen(true);
+				else if (section === "ai") setAiOpen(true);
+				else if (section === "market") setMode("plugins");
+				else if (section === "skills") setMode("skills");
+			}, [section]);
 			// 搜索源列表（内置 + 自定义，来自配置）
 			const [searchSourcesList, setSearchSourcesList] = react.useState(null);
 			// Git 源列表（「仓库落地」提示动态显示当前主源，避免写死 GitHub）
@@ -4772,6 +4845,93 @@ setMessage(t("failed") + "：" + (data?.reason ?? "未知"));
 					: null,
 			);
 		}
+		// 官方风格「升级安全」页（2026-09-24）：**纯加法**。
+		// 原 tab（id=console）与悬浮面板一行不动；这里把门控常驻化的状态、模式开关、一键适配与各功能入口
+		// 用官方卡片风呈现，并把控制台功能**就地展开**（官方 settings.plugins.tab 插槽的 owner props 是空的，
+		// 没有「切到兄弟 tab」的 API，所以就地承载而不是跳页）。
+		// 触发源已从「我们的升级动作」换成环境指纹变化（服务端 domain/compat-state.js）：
+		// 官方桌面端自带升级器 / 官方只发桌面端时，门控依然守得住。
+		function PluginSafetyTab({ t }) {
+			const [status, setStatus] = react.useState(null);
+			const [busy, setBusy] = react.useState(false);
+			const [note, setNote] = react.useState(null);
+			const [section, setSection] = react.useState(null);
+			const load = async () => {
+				try { const data = await call("/plugin-console/compat-status"); if (data !== null) setStatus(data); } catch {}
+			};
+			react.useEffect(() => { load(); }, []);
+			const switchMode = async (mode) => {
+				if (busy) return;
+				setBusy(true);
+				try {
+					const data = await call("/plugin-console/compat-mode", { mode: mode });
+					setNote({ text: mode === "observer" ? t("safetyModeObserverOn") : t("safetyModeManagedOn") });
+					if (data !== null) setStatus(null);
+					await load();
+				} catch (error) { setNote({ text: (error && error.message) || t("safetySwitchFailed") }); }
+				finally { setBusy(false); }
+			};
+			const ack = async () => {
+				try { await call("/plugin-console/compat-stamp", {}); await load(); setNote({ text: t("safetyFpAcked") }); } catch {}
+			};
+			const preflight = async (apply) => {
+				if (busy) return;
+				setBusy(true);
+				setNote({ text: t("fwPreflightRunning") });
+				try {
+					const pre = await call("/plugin-console/framework-preflight", {});
+					const blockers = (pre && pre.scan && pre.scan.blockers) || 0;
+					if (!apply || blockers === 0) {
+						const patched = await call("/plugin-console/framework-preflight-patch", { mode: "plan" });
+						const planCount = (patched && patched.changes && patched.changes.length) || 0;
+						setNote({ text: blockers === 0 ? t("fwPreflightClean") : fill(t("safetyPreflightFound"), [["n", planCount || blockers]]) });
+					} else {
+						const done = await call("/plugin-console/framework-preflight-patch", { mode: "apply" });
+						const changed = (done && done.changes && done.changes.length) || 0;
+						setNote({ text: fill(t("safetyPreflightPatched"), [["n", changed]]) });
+					}
+				} catch (error) { setNote({ text: (error && error.message) || t("safetySwitchFailed") }); }
+				finally { setBusy(false); }
+			};
+			const fill = (text, pairs) => {
+				let out = String(text);
+				for (const pair of pairs) out = out.split("{" + pair[0] + "}").join(String(pair[1]));
+				return out;
+			};
+			const card = (icon, title, desc, control) => el("div", { style: { display: "flex", alignItems: "center", gap: "14px", padding: "14px 16px", borderRadius: "14px", border: "1px solid var(--dsw-alias-border-secondary, rgba(127,127,127,.18))", background: "var(--dsw-alias-bg-elevated, rgba(127,127,127,.06))" } },
+				el("div", { style: { width: "40px", height: "40px", borderRadius: "12px", display: "flex", alignItems: "center", justifyContent: "center", background: "var(--dsw-alias-bg-secondary, rgba(127,127,127,.12))", fontSize: "18px", flex: "0 0 auto" } }, icon),
+				el("div", { style: { flex: "1 1 auto", minWidth: "0" } },
+					el("div", { style: { fontSize: "14px", fontWeight: 500 } }, title),
+					el("div", { style: { fontSize: "12.5px", opacity: .72, marginTop: "2px", wordBreak: "break-word" } }, desc)),
+				control === undefined ? null : control);
+			const sw = (on, onClick, title) => el("button", { type: "button", title: title, onClick: onClick, disabled: busy, style: { width: "42px", height: "24px", borderRadius: "999px", border: "none", padding: 0, cursor: busy ? "default" : "pointer", background: on ? "var(--dsw-alias-bg-accent, #4d6bfe)" : "var(--dsw-alias-bg-secondary, rgba(127,127,127,.35))", position: "relative", flex: "0 0 auto" } },
+				el("span", { style: { position: "absolute", top: "3px", left: on ? "21px" : "3px", width: "18px", height: "18px", borderRadius: "50%", background: "#fff", transition: "left .18s ease" } }));
+			const jump = (id, label) => el("button", { key: id, type: "button", className: styles.toggle, style: { marginRight: "8px", marginBottom: "8px" }, onClick: () => setSection(id) }, label);
+			const mode = status !== null && status.mode === "observer" ? "observer" : "managed";
+			const fp = status !== null && status.fingerprint !== null && status.fingerprint !== undefined ? status.fingerprint : {};
+			const rb = status !== null && status.rollback !== null && status.rollback !== undefined ? status.rollback : {};
+			const fw = status !== null && typeof status.frameworkVersion === "string" && status.frameworkVersion !== "" ? status.frameworkVersion : t("safetyUnknown");
+			return el("div", { style: { display: "flex", flexDirection: "column", gap: "12px", maxWidth: "760px" } },
+				card("🛡️", t("safetyMode"), mode === "managed" ? t("safetyModeManaged") : t("safetyModeObserver"), sw(mode === "observer", () => switchMode(mode === "managed" ? "observer" : "managed"), t("safetyModeSwitch"))),
+				card("📌", t("safetyFrameworkTitle"), fill(t("safetyFrameworkDesc"), [["v", fw]])),
+				card("⏪", t("safetyRollbackTitle"), rb.applicable === true ? fill(t("safetyRollbackOk"), [["from", rb.from], ["to", rb.to]]) : fill(t("safetyRollbackNone"), [["reason", rb.reason === null || rb.reason === undefined ? "-" : rb.reason]])),
+				card("🔎", t("safetyFpTitle"), fp.changed === true ? fill(t("safetyFpChanged"), [["reasons", (fp.reasons || []).join("；")]]) : t("safetyFpStable"), fp.changed === true ? el("button", { type: "button", className: styles.toggle, onClick: ack, disabled: busy }, t("safetyFpAck")) : null),
+				card("🩺", t("safetyAdaptTitle"), t("safetyAdaptDesc"), el("div", { style: { display: "flex", gap: "8px", flex: "0 0 auto" } },
+					el("button", { type: "button", className: styles.toggle, disabled: busy, onClick: () => preflight(false) }, t("fwPreflightBtn")),
+					el("button", { type: "button", className: styles.toggle, disabled: busy, onClick: () => preflight(true) }, t("fwPreflightPatch")))),
+				note === null ? null : el("div", { style: { fontSize: "12.5px", opacity: .85 } }, note.text),
+				el("div", null,
+					el("div", { style: { fontSize: "12.5px", opacity: .6, margin: "4px 0 8px" } }, t("safetyJumpHint")),
+					jump("market", t("safetyJumpMarket")),
+					jump("skills", t("safetyJumpSkills")),
+					jump("framework", t("safetyJumpFramework")),
+					jump("gate", t("safetyJumpGate")),
+					jump("sources", t("safetyJumpSources")),
+					jump("ai", t("safetyJumpAi"))),
+				section === null ? null : el("div", { style: { marginTop: "4px", borderTop: "1px solid var(--dsw-alias-border-secondary, rgba(127,127,127,.18))", paddingTop: "12px" } },
+					el("div", { style: { fontSize: "12.5px", opacity: .6, marginBottom: "8px" } }, t("safetyEmbedded")),
+					el(PluginConsoleTab, { t: t, section: section, key: section })));
+		}
 		function apply(ctx) {
 			ctx.effect(() => ctx.locale.register(NS, { zh, en }), "plugin-console: dictionaries");
 			const t = ctx.locale.bind(NS);
@@ -4783,6 +4943,15 @@ setMessage(t("failed") + "：" + (data?.reason ?? "未知"));
 				locale: NS,
 				inject: () => ({}),
 			}, PluginConsoleTab));
+			// 官方风格「升级安全」入口（纯加法）：原 tab id=console 保持不变，这里只是多挂一个
+			ctx.slots.inject("settings.plugins.tab", () => ctx.slots.register({
+				name: "settings.plugins.tab",
+				id: "console-safety",
+				order: 21,
+				label: () => t("safetyTab"),
+				locale: NS,
+				inject: () => ({}),
+			}, PluginSafetyTab));
 		}
 		exports.NS = NS;
 		exports.apply = apply;

package/lib/contracts/rules.json

@@ -0,0 +1,72 @@
+{
+  "version": 1,
+  "updatedAt": "2026-09-24",
+  "summary": "DSH 升级契约规则库：把「框架某次变更会打断什么」沉淀成数据。预检读它，因此规则库对任何来源的框架变更都生效（我们的升级器、官方桌面端自带升级器、手动 pnpm 都一样）。欢迎 PR 补充——每个事故都应该变成一条规则。",
+  "fields": {
+    "id": "稳定标识（小写连字符），被测试与文档引用，改名等于破坏兼容",
+    "since": "从哪个框架版本开始成立（用于判定「目标版本是否需要这条规则」）",
+    "kind": "contract-edge | dependency-api | config-schema | removed-api | loader-contract",
+    "severity": "blocker（不改就会炸）| warn（提示，不影响可用）",
+    "detect": "怎么发现（人话描述，便于 PR 评审与用户理解）",
+    "fix": "怎么修（能自动修的要写清楚改前备份策略）",
+    "implementedBy": "本控制台里承担检测的实现（模块名或探针 id）；留空表示「仅登记、尚未自动检测」",
+    "evidence": "真实报错原文或事故编号——没有证据的规则不收"
+  },
+  "rules": [
+    {
+      "id": "session-message-source-kind",
+      "since": "0.1.7-rc.1",
+      "kind": "contract-edge",
+      "severity": "blocker",
+      "title": "会话消息来源需要 producer-owned kind（V3 → V4）",
+      "detect": "扫描本地生产方（agent 预设 + 已装插件）里仍写 `kind: 'plugin'` 的 V3 包装形状；框架只迁移磁盘历史会话，运行期生产方不迁移",
+      "fix": "把 V3 包装改写成 producer-owned kind；本控制台可一键适配，逐文件备份 .bak-preflight-*，名单外文件拒绝写入",
+      "implementedBy": "domain/format-scan.js（planSourceKindRewrites）",
+      "evidence": "format v4 message requires a producer-owned source kind"
+    },
+    {
+      "id": "schemastery-volatile-api",
+      "since": "3.18.4",
+      "kind": "dependency-api",
+      "severity": "warn",
+      "title": "@deepseek-ai/schemastery 的 Schema.prototype.volatile()",
+      "detect": "插件源码调用 .volatile()，但它实际解析到的 schemastery 副本低于声明版本（常见于 profile 里被手工铺了陈旧真实副本）",
+      "fix": "把该副本对齐到声明版本即可，**不必改插件源码**（带依赖探针，修好后自动静默）",
+      "implementedBy": "domain/format-scan.js（KNOWN_BREAKAGES.probe = schemastery-volatile）",
+      "evidence": ".volatile is not a function（2026-09-24 实测 7 个插件导入失败）"
+    },
+    {
+      "id": "preset-persona-text-to-prefix",
+      "since": "0.1.5-rc.1",
+      "kind": "config-schema",
+      "severity": "blocker",
+      "title": "agent 预设 persona.text → persona.prefix",
+      "detect": "升级前扫描全部 agent 预设与 host 组合里的 persona.text 字段",
+      "fix": "就地改名并留 .bak 备份（v0.3.33 起内置；包级适配门扫不到预设，这是当时事故的真正短板）",
+      "implementedBy": "domain/presets.js（migrateAgentConfigsForUpgrade）",
+      "evidence": "issue #18（0.1.2-rc.1 → 0.1.5-rc.1 升级后服务起不来）"
+    },
+    {
+      "id": "dsh-settings-namespace-removed",
+      "since": "0.1.5-rc.1",
+      "kind": "removed-api",
+      "severity": "blocker",
+      "title": "dsh-settings 命名空间 API 被移除",
+      "detect": "扫描已装包源码里对已删除 API 的引用（要求标识符边界，并排除本地定义同行无引用的情况，避免误伤框架自带的 settings 控制器）",
+      "fix": "改用 ctx.get('名字') 读取或声明 inject；未 inject 的名字做属性式访问在真实 ctx 上会同步抛错",
+      "implementedBy": "domain/compat.js（checkPluginFrameworkCompat）",
+      "evidence": "0.3.59 注入缝缺陷（属性式读取未声明的名字 → 安装全灭）"
+    },
+    {
+      "id": "patch-overlay-toplevel-array",
+      "since": "0.1.5-rc.1",
+      "kind": "loader-contract",
+      "severity": "blocker",
+      "title": "cordis.patch.yml 必须是顶层 YAML 数组",
+      "detect": "解析 profile 与各 bundle 的补丁层，空文件/只有注释会解析成 null 而被拒",
+      "fix": "留 `[]` 占位（或写成 `- insert:` 列表）；本控制台的补丁写入已统一走该形态",
+      "implementedBy": "domain/patch.js（sanitizePatchText）",
+      "evidence": "overlay <path> must be a top-level YAML array of loader patch entries"
+    }
+  ]
+}

package/lib/server/domain/compat-state.js

@@ -0,0 +1,126 @@
+// L1 · domain —— 门控常驻化的状态层：运行模式（托管 / 观察者）+ 环境指纹 + 回滚点读取
+//
+// 为什么需要它（2026-09-24 桌面端复盘）：门控此前**寄生在我们自己的升级流程**上 ——
+// 「我们点升级」才跑兼容扫描、才产出隔离清单。一旦官方桌面端自带升级器，或官方只发桌面端
+// 而不再单独更新框架，我们就失去了触发点。这里把触发源从「升级动作」换成「环境指纹变化」：
+// 任何来源的框架变更（官方升级器 / 桌面端自带运行时 / 手动 pnpm / npx 缓存变化）都会被发现，
+// 门控因此不再依赖我们是否执行了升级。
+//
+// 纯状态层：不做扫描、不装东西、不碰 ctx。扫描仍走 domain/compat.js 与 domain/format-scan.js。
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { dshHome } from '../infra/paths.js'
+
+/** 运行模式。managed = 托管（我们负责框架升级与回滚，既有行为）；observer = 观察者（只守门，不碰升级）。 */
+const COMPAT_MODES = ['managed', 'observer']
+const DEFAULT_MODE = 'managed'
+
+const stateDir = () => join(dshHome(), 'plugin-console')
+const modeFile = () => join(stateDir(), 'compat-mode.json')
+const fingerprintFile = () => join(stateDir(), 'env-fingerprint.json')
+const rollbackFile = () => join(stateDir(), 'framework-rollback.json')
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+function writeJson(path, value) {
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, 'utf8')
+}
+
+/**
+ * 读运行模式。**默认托管** —— 纯加法：没有设置过的机器行为与之前完全一致。
+ * @returns {{ mode: string, at: number|null, source: 'file'|'default' }}
+ */
+function readCompatMode() {
+  const rec = readJson(modeFile())
+  const mode = typeof rec?.mode === 'string' && COMPAT_MODES.includes(rec.mode) ? rec.mode : DEFAULT_MODE
+  return { mode, at: typeof rec?.at === 'number' ? rec.at : null, source: rec === null ? 'default' : 'file' }
+}
+
+/**
+ * 写运行模式（只接受白名单值，避免拼错导致「模式静默失效」）。
+ * @returns {{ ok: boolean, mode: string, error?: string }}
+ */
+function writeCompatMode(mode) {
+  if (typeof mode !== 'string' || !COMPAT_MODES.includes(mode)) {
+    return { ok: false, mode: readCompatMode().mode, error: `未知模式 ${String(mode)}（可选：${COMPAT_MODES.join(' / ')}）` }
+  }
+  writeJson(modeFile(), { mode, at: Date.now() })
+  return { ok: true, mode }
+}
+
+/**
+ * 算一份环境指纹。字段刻意取「便宜且稳定」的信号：
+ *   · frameworkVersion —— 框架自报版本（换版本必变）
+ *   · pnpmEntities —— 框架树里 @deepseek-ai 实体数（半装/损坏/换包会变）
+ *   · pnpmRoot —— 框架树根路径（换运行时/换安装位置会变：npx 缓存 ↔ 桌面端自带运行时）
+ * @param {{ frameworkVersion?: string|null, pnpmRoot?: string|null }} input
+ */
+function computeFingerprint(input = {}) {
+  const frameworkVersion = typeof input.frameworkVersion === 'string' && input.frameworkVersion !== '' ? input.frameworkVersion : null
+  const pnpmRoot = typeof input.pnpmRoot === 'string' && input.pnpmRoot !== '' ? input.pnpmRoot : null
+  let pnpmEntities = null
+  if (pnpmRoot !== null) {
+    try {
+      pnpmEntities = readdirSync(join(pnpmRoot, '.pnpm'), { withFileTypes: true })
+        .filter((d) => d.isDirectory() && d.name.startsWith('@deepseek-ai+')).length
+    } catch {
+      pnpmEntities = null
+    }
+  }
+  return { frameworkVersion, pnpmEntities, pnpmRoot, at: Date.now() }
+}
+
+function readFingerprint() {
+  const rec = readJson(fingerprintFile())
+  return rec === null ? null : rec
+}
+
+/** 把当前指纹记为基线（启动时 / 用户确认变更后调用）。 */
+function stampFingerprint(fp) {
+  const rec = { ...fp, at: Date.now() }
+  writeJson(fingerprintFile(), rec)
+  return rec
+}
+
+/**
+ * 比对新旧指纹 —— 这就是「环境变更事件」的判定：**谁改的都算**。
+ * @returns {{ changed: boolean, reasons: string[], baselineAt: number|null }}
+ */
+function compareFingerprint(current, previous) {
+  if (previous === null || previous === undefined) return { changed: false, reasons: [], baselineAt: null }
+  const reasons = []
+  if (previous.frameworkVersion !== current.frameworkVersion) {
+    reasons.push(`框架版本 ${previous.frameworkVersion ?? '未知'} → ${current.frameworkVersion ?? '未知'}`)
+  }
+  if (previous.pnpmRoot !== current.pnpmRoot) reasons.push('框架运行时位置变化（换了安装根：npx 缓存 / 桌面端自带运行时 / 自定义）')
+  if (previous.pnpmEntities !== current.pnpmEntities) reasons.push(`框架树包数 ${previous.pnpmEntities ?? '?'} → ${current.pnpmEntities ?? '?'}`)
+  return { changed: reasons.length > 0, reasons, baselineAt: typeof previous.at === 'number' ? previous.at : null }
+}
+
+/** 回滚点：记录存在 **且** 其 checkpoint 目录仍在（记录在、目录没了 = 实际不可用，不能骗用户）。 */
+function readRollbackRecord() {
+  const rec = readJson(rollbackFile())
+  if (rec === null) return { from: null, to: null, at: null, applicable: false, reason: '没有回滚记录' }
+  const fwRoot = typeof rec.fwRoot === 'string' ? rec.fwRoot : null
+  const checkpoint = fwRoot === null ? false : existsSync(join(stateDir(), 'framework-backups'))
+  const applicable = fwRoot !== null && existsSync(fwRoot)
+  return {
+    from: rec.from ?? null,
+    to: rec.to ?? null,
+    at: typeof rec.at === 'number' ? rec.at : null,
+    fwRoot,
+    checkpoint,
+    applicable,
+    reason: applicable ? null : '框架树路径不存在（可能已被清理或换了安装根）',
+  }
+}
+
+export { COMPAT_MODES, DEFAULT_MODE, compareFingerprint, computeFingerprint, readCompatMode, readFingerprint, readRollbackRecord, stampFingerprint, writeCompatMode }

package/lib/server/domain/contract-rules.js

@@ -0,0 +1,85 @@
+// L1 · domain —— 契约规则库的读取层
+//
+// 为什么把规则做成「数据」而不是散在代码里（2026-09-24 桌面端复盘）：
+//   门控此前寄生在「我们自己的升级流程」上；官方桌面端一旦自带升级器、或官方只发桌面端，
+//   触发点就没了。规则外置之后，**预检对任何来源的框架变更都成立**：只要有人把框架版本从 A
+//   变成 B，就能拿规则库比对（我们的升级器、官方升级器、手动 pnpm 都一样）。
+//   同时规则库是唯一能被社区直接 PR 的产物 —— 事故进规则、规则进测试。
+//
+// 数据文件随包发布（lib/contracts/rules.json，`files` 白名单已含 lib/**），
+// 因此用户装到的是同一份规则；仓库侧另有 docs/contracts/README.md 说明格式与收录方式。
+//
+// 读不到文件时退化为**空规则库**（如实回报 source='unavailable'），绝不让预检因为规则文件
+// 缺失而假装「零发现」——调用方拿 source 字段判断可信度。
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { pluginRoot } from '../infra/paths.js'
+
+const RULES_RELATIVE = join('lib', 'contracts', 'rules.json')
+const KINDS = ['contract-edge', 'dependency-api', 'config-schema', 'removed-api', 'loader-contract']
+const SEVERITIES = ['blocker', 'warn']
+
+function rulesPath() {
+  return join(pluginRoot(), RULES_RELATIVE)
+}
+
+/** 只保留字段齐全、取值合法的规则（脏数据宁可丢一条，也不要让预检报错或误报）。 */
+function normalizeRule(raw) {
+  if (raw === null || typeof raw !== 'object') return null
+  const id = typeof raw.id === 'string' && raw.id !== '' ? raw.id : null
+  const since = typeof raw.since === 'string' && raw.since !== '' ? raw.since : null
+  if (id === null || since === null) return null
+  return {
+    id,
+    since,
+    kind: KINDS.includes(raw.kind) ? raw.kind : 'contract-edge',
+    severity: SEVERITIES.includes(raw.severity) ? raw.severity : 'warn',
+    title: typeof raw.title === 'string' ? raw.title : id,
+    detect: typeof raw.detect === 'string' ? raw.detect : '',
+    fix: typeof raw.fix === 'string' ? raw.fix : '',
+    implementedBy: typeof raw.implementedBy === 'string' && raw.implementedBy !== '' ? raw.implementedBy : null,
+    evidence: typeof raw.evidence === 'string' ? raw.evidence : '',
+  }
+}
+
+/**
+ * 读规则库。
+ * @returns {{ source: 'pack'|'unavailable', version: number|null, updatedAt: string|null, rules: object[], error: string|null }}
+ */
+function loadContractRules() {
+  const path = rulesPath()
+  if (!existsSync(path)) {
+    return { source: 'unavailable', version: null, updatedAt: null, rules: [], error: `规则库文件不存在：${RULES_RELATIVE}` }
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'))
+    const rules = Array.isArray(parsed?.rules) ? parsed.rules.map(normalizeRule).filter((r) => r !== null) : []
+    return {
+      source: 'pack',
+      version: typeof parsed?.version === 'number' ? parsed.version : null,
+      updatedAt: typeof parsed?.updatedAt === 'string' ? parsed.updatedAt : null,
+      rules,
+      error: null,
+    }
+  } catch (error) {
+    return { source: 'unavailable', version: null, updatedAt: null, rules: [], error: `规则库解析失败：${error instanceof Error ? error.message : String(error)}` }
+  }
+}
+
+/** 规则摘要（给面板/接口用，避免把整段说明塞进响应）。 */
+function summarizeContractRules(pack) {
+  const blockers = pack.rules.filter((r) => r.severity === 'blocker').length
+  return {
+    source: pack.source,
+    version: pack.version,
+    updatedAt: pack.updatedAt,
+    total: pack.rules.length,
+    blockers,
+    autoDetected: pack.rules.filter((r) => r.implementedBy !== null).length,
+    ids: pack.rules.map((r) => r.id),
+    error: pack.error,
+  }
+}
+
+export { KINDS, RULES_RELATIVE, SEVERITIES, loadContractRules, normalizeRule, rulesPath, summarizeContractRules }

package/lib/server/domain/install-job.js

@@ -7,7 +7,7 @@ import { readFile } from 'node:fs/promises'
 import { basename, dirname, join, resolve } from 'node:path'
 import { aiRepair } from './ai-run.js'
 import { maybeAutoAdaptCompat } from './compat.js'
-import { DEFAULT_BUNDLES, AI_CONSENT_TIMEOUT_MS, addBundleToManifest, backfillMissingDeps, curlManualInstall, detectBundleOnly, ensureBundlePatchIntegrity, githubReleaseInstall, pnpmInstall, raceInstallChannels, readBundlePatchRefNames, readGithubAuth, syncAggregateSubpackageVersions } from './install.js'
+import { DEFAULT_BUNDLES, AI_CONSENT_TIMEOUT_MS, addBundleToManifest, backfillMissingDeps, curlManualInstall, declareProfileDependency, detectBundleOnly, ensureBundlePatchIntegrity, githubReleaseInstall, pnpmInstall, raceInstallChannels, readBundlePatchRefNames, readGithubAuth, syncAggregateSubpackageVersions } from './install.js'
 import { fetchRepoPackage, fetchRepoPackageEx, fetchSubpackageNames, packageProbeErrorText, subpackageCandidates } from './market.js'
 import { appendInsert, readPatchState, syncNameFromNote } from './patch.js'
 import { deriveEntryId, listEntries } from './runtime.js'
@@ -490,17 +490,26 @@ async function runInstallJob(job, ports) {
       } else {
         job.bundleNote = (job.bundleNote ? job.bundleNote + '；' : '') + `${installedName} 已由已安装聚合包提供，仅更新包本身，不再注册重复行`
       }
+      // 安装即声明：即便是「已由聚合包提供」的分支也要声明本轮真实安装的版本，
+      // 否则官方面板看不见它、pnpm 也会按旧清单把它还原回去（2026-09-24 根因）。
+      const declaredBundle = await declareProfileDependency(profileDir, installedName)
+      if (declaredBundle.changed) job.declared = declaredBundle.version
       job.status = 'done'
       return
     }
     if (alreadyServed) {
       job.note = `${installedName} 已由已安装条目提供，仅更新包本身，不重复注册`
+      const declaredServed = await declareProfileDependency(profileDir, installedName)
+      if (declaredServed.changed) job.declared = declaredServed.version
       job.status = 'done'
       return
     }
     const entryId = deriveEntryId(installedName, taken)
     await appendInsert(patchPath, entryId, installedName)
     job.entryId = entryId
+    // 安装即声明（同上）：普通插件装完把依赖写进 profile 清单
+    const declared = await declareProfileDependency(profileDir, installedName)
+    if (declared.changed) job.declared = declared.version
     job.status = 'done'
   } catch (error) {
     job.status = 'failed'

package/lib/server/domain/install.js

@@ -6,6 +6,7 @@ import { readFile, writeFile } from 'node:fs/promises'
 import { execFile } from 'node:child_process'
 import { dirname, join, resolve } from 'node:path'
 import { tmpdir } from 'node:os'
+import { DEFAULT_BUNDLES, addBundleToManifest, declareProfileDependency, removeBundleFromManifest, undeclareProfileDependency } from './manifest.js'
 import { sanitizePatchText } from './patch.js'
 import { orderedRegistries, readSources } from './sources.js'
 import { execFileAsync, runPnpmWithFallback } from '../infra/exec.js'
@@ -29,23 +30,6 @@ async function detectBundleOnly(profileDir, packageName) {
   }
 }
 
-/** 把包追加进 profile 的 dsh.profile.bundles 层（与官方 dsh plugin add 的 reconcile 一致）。 */
-async function addBundleToManifest(profileDir, packageName) {
-  return queuedWrite(async () => {
-    const manifestPath = join(profileDir, 'package.json')
-    const manifest = JSON.parse(await readFile(manifestPath, 'utf8'))
-    const bundles = manifest.dsh?.profile?.bundles ?? []
-    if (!bundles.includes(packageName)) {
-      bundles.push(packageName)
-      manifest.dsh = { ...(manifest.dsh ?? {}), profile: { ...(manifest.dsh?.profile ?? {}), bundles } }
-      await writeFile(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf8')
-    }
-  })
-}
-
-/** 官方 profile 模板自带的 bundle（其余 bundle 视为用户额外添加）。 */
-const DEFAULT_BUNDLES = ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app']
-
 /** 读取用户额外 bundle 的插入行归属表：行 id / 包名 → 所属 bundle 包名。 */
 async function readExtraBundleOwners(profileDir) {
   const owners = new Map()
@@ -80,20 +64,6 @@ async function readExtraBundleOwners(profileDir) {
   return owners
 }
 
-/** 从 profile manifest 移除一个 bundle。 */
-async function removeBundleFromManifest(profileDir, bundlePkg) {
-  return queuedWrite(async () => {
-    const manifestPath = join(profileDir, 'package.json')
-    const manifest = JSON.parse(await readFile(manifestPath, 'utf8'))
-    const bundles = manifest.dsh?.profile?.bundles ?? []
-    const next = bundles.filter((name) => name !== bundlePkg)
-    if (next.length !== bundles.length) {
-      manifest.dsh = { ...(manifest.dsh ?? {}), profile: { ...(manifest.dsh?.profile ?? {}), bundles: next } }
-      await writeFile(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf8')
-    }
-  })
-}
-
 /**
  * 读取 dsh-github-login（独立登录工具）写入的 GitHub 令牌文件。
  * 只对外暴露登录状态（login），绝不下发令牌本身。
@@ -596,4 +566,4 @@ async function syncAggregateSubpackageVersions(profileDir, packageName, registri
   return updated
 }
 
-export { AI_CONSENT_TIMEOUT_MS, DEFAULT_BUNDLES, detectBundleOnly, addBundleToManifest, removeBundleFromManifest, readExtraBundleOwners, readGithubAuth, pnpmInstall, curlManualInstall, raceInstallChannels, verifyPackageBox, parseBundlePatchRefs, backfillMissingDeps, githubReleaseInstall, readBundlePatchRefNames, ensureBundlePatchIntegrity, syncAggregateSubpackageVersions, installJobView }
+export { AI_CONSENT_TIMEOUT_MS, DEFAULT_BUNDLES, detectBundleOnly, addBundleToManifest, removeBundleFromManifest, declareProfileDependency, undeclareProfileDependency, readExtraBundleOwners, readGithubAuth, pnpmInstall, curlManualInstall, raceInstallChannels, verifyPackageBox, parseBundlePatchRefs, backfillMissingDeps, githubReleaseInstall, readBundlePatchRefNames, ensureBundlePatchIntegrity, syncAggregateSubpackageVersions, installJobView }

package/lib/server/domain/manifest.js

@@ -0,0 +1,120 @@
+// L1 · domain —— profile 清单（<profile>/package.json）的写入层：bundles 层 + dependencies 声明
+//
+// 为什么单独成模块（2026-09-24）：安装落点原本散在 install.js 里，而 install.js 已经贴着
+// 架构守卫的 600 行上限；更重要的是，「装了但没声明」这一类问题反复出现（官方面板看不见 /
+// pnpm 按清单还原 / 我们的清理判据误当孤儿），把「怎么写清单」收口到一处才好统一保证。
+//
+// 规矩：
+//   · 所有写操作走 fsx 的写队列（queuedWrite），避免并发读改写互相覆盖；
+//   · **安装即声明**：装到哪版就把 dependencies 写成哪版（读磁盘真实版本，不猜）；
+//   · **卸载即撤销**：否则清单留幽灵依赖，下次 pnpm 操作把它装回来；
+//   · 来源型 spec（link:/file:/git:/URL）绝不改写成版本号 —— 改写等于丢来源。
+
+import { readFile, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { queuedWrite } from '../infra/fsx.js'
+import { resolvePackageJson } from '../infra/paths.js'
+
+/** 官方 profile 模板自带的 bundle（其余 bundle 视为用户额外添加）。 */
+const DEFAULT_BUNDLES = ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app']
+
+/** 读磁盘上真实安装的版本（读不到返回 null，绝不猜）。 */
+async function installedVersionOf(profileDir, packageName) {
+  try {
+    const pkgPath = resolvePackageJson(packageName, profileDir)
+    if (pkgPath === null) return null
+    const version = JSON.parse(await readFile(pkgPath, 'utf8')).version
+    return typeof version === 'string' && version !== '' ? version : null
+  } catch {
+    return null
+  }
+}
+
+async function readManifest(profileDir) {
+  return JSON.parse(await readFile(join(profileDir, 'package.json'), 'utf8'))
+}
+
+async function writeManifest(profileDir, manifest) {
+  await writeFile(join(profileDir, 'package.json'), `${JSON.stringify(manifest, null, 2)}\n`, 'utf8')
+}
+
+/**
+ * 把包追加进 profile 的 `dsh.profile.bundles` 层（与官方 `dsh plugin add` 的 reconcile 一致），
+ * 同一把写锁内**顺手声明 dependencies**（安装即声明）。
+ * @returns {{ version: string|null }}
+ */
+async function addBundleToManifest(profileDir, packageName) {
+  return queuedWrite(async () => {
+    const manifest = await readManifest(profileDir)
+    const bundles = manifest.dsh?.profile?.bundles ?? []
+    let touched = false
+    if (!bundles.includes(packageName)) {
+      bundles.push(packageName)
+      manifest.dsh = { ...(manifest.dsh ?? {}), profile: { ...(manifest.dsh?.profile ?? {}), bundles } }
+      touched = true
+    }
+    const version = await installedVersionOf(profileDir, packageName)
+    if (version !== null) {
+      const deps = { ...(manifest.dependencies ?? {}) }
+      if (deps[packageName] !== version) { deps[packageName] = version; manifest.dependencies = deps; touched = true }
+    }
+    if (touched) await writeManifest(profileDir, manifest)
+    return { version }
+  })
+}
+
+/** 从 profile manifest 移除一个 bundle（同时撤销 dependencies 声明，避免留下幽灵依赖）。 */
+async function removeBundleFromManifest(profileDir, bundlePkg) {
+  return queuedWrite(async () => {
+    const manifest = await readManifest(profileDir)
+    const bundles = manifest.dsh?.profile?.bundles ?? []
+    const next = bundles.filter((name) => name !== bundlePkg)
+    let touched = false
+    if (next.length !== bundles.length) {
+      manifest.dsh = { ...(manifest.dsh ?? {}), profile: { ...(manifest.dsh?.profile ?? {}), bundles: next } }
+      touched = true
+    }
+    const deps = { ...(manifest.dependencies ?? {}) }
+    if (bundlePkg in deps) { delete deps[bundlePkg]; manifest.dependencies = deps; touched = true }
+    if (touched) await writeManifest(profileDir, manifest)
+    return { changed: touched }
+  })
+}
+
+/**
+ * 安装即声明：把包写进 profile 清单的 `dependencies`。
+ *
+ * 三个现象同一个根因（2026-09-24 复盘）：
+ *   · 官方「设置 → 插件」的**已安装**分区只显示清单里声明过的包 —— 我们手铺的包在那里看不见；
+ *   · 任何一次 pnpm 操作都会按清单 + lock 重装，未声明的包会被**还原/清掉**；
+ *   · 连我们自己的「清理残余」也按「有没有被声明」判孤儿 —— 判据病根也在这里。
+ * @returns {{ changed: boolean, version: string|null, reason: string|null }}
+ */
+async function declareProfileDependency(profileDir, packageName, version = null) {
+  return queuedWrite(async () => {
+    const manifest = await readManifest(profileDir)
+    const resolved = typeof version === 'string' && version !== '' ? version : await installedVersionOf(profileDir, packageName)
+    if (resolved === null) return { changed: false, version: null, reason: '读不到已安装版本' }
+    const deps = { ...(manifest.dependencies ?? {}) }
+    if (deps[packageName] === resolved) return { changed: false, version: resolved, reason: null }
+    deps[packageName] = resolved
+    manifest.dependencies = deps
+    await writeManifest(profileDir, manifest)
+    return { changed: true, version: resolved, reason: null }
+  })
+}
+
+/** 卸载即撤销声明。 */
+async function undeclareProfileDependency(profileDir, packageName) {
+  return queuedWrite(async () => {
+    const manifest = await readManifest(profileDir)
+    const deps = { ...(manifest.dependencies ?? {}) }
+    if (!(packageName in deps)) return { changed: false }
+    delete deps[packageName]
+    manifest.dependencies = deps
+    await writeManifest(profileDir, manifest)
+    return { changed: true }
+  })
+}
+
+export { DEFAULT_BUNDLES, addBundleToManifest, declareProfileDependency, installedVersionOf, removeBundleFromManifest, undeclareProfileDependency }

package/lib/server/domain/selfupdate.js

@@ -10,7 +10,7 @@
 // 现在的顺序：① spec 是版本范围 → `pnpm update <pkg>`（spec 不变、lock 提到范围内最新）
 //            ② 仍不是 latest（超出范围 / spec 是 git·file 来源）→ `pnpm add <pkg>@<latest>`（spec 与 lock 同步改写）
 //            ③ 回读核实 readInstalledVersion / lockVersion；都不匹配才回落手铺文件，且**必须**带 lockNote 警告。
-import { existsSync, readFileSync } from 'node:fs'
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { linkSpecFor, linkSpecIsIntact, materializePackageForLink, probeRegistryPackage } from './dep-source.js'
 import { pnpmInstall } from './install.js'
@@ -150,10 +150,34 @@ async function selfUpdateToLatest({ profileDir, latest, registries, curlManualIn
   }
 
   const sourceSwitch = spec !== null && !isRegistryRange(spec) ? `安装来源已从 ${spec} 变为 registry 版本 ${latest}` : null
+
+  // ④ 清单 spec 也要跟上（2026-09-24 实测踩到：lock 写了、spec 还钉着 0.3.57，
+  //    于是下一次 pnpm 操作会把控制台「降级」回 0.3.57 —— 包管理器通道 ①② 通常会顺手改写 spec，
+  //    但手铺兜底不会，所以这里统一收口：装到哪版就把 spec 写成哪版（来源型 spec 除外，绝不丢来源）。
+  let specUpdated = null
+  if (installed === latest && (spec === null || isRegistryRange(spec))) {
+    try {
+      const manifestPath = join(profileDir, 'package.json')
+      const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
+      const deps = { ...(manifest.dependencies ?? {}) }
+      if (deps[CONSOLE_PACKAGE] !== latest) {
+        deps[CONSOLE_PACKAGE] = latest
+        manifest.dependencies = deps
+        writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8')
+        specUpdated = latest
+      }
+    } catch (error) {
+      errors.push(`清单 spec 同步失败：${label(error)}`)
+    }
+  } else if (installed === latest && spec !== null && !isRegistryRange(spec)) {
+    errors.push(`清单 spec 是来源型（${spec}），按约定保留不改写`)
+  }
+
   const noteParts = [lockUpdated ? '已写入 pnpm-lock.yaml，重启服务后生效' : '已铺入文件但未写入 pnpm-lock.yaml：重启后可用，但会被 pnpm 还原']
   if (sourceSwitch !== null) noteParts.push(sourceSwitch)
+  if (specUpdated !== null) noteParts.push(`清单 spec 已同步为 ${specUpdated}（防 pnpm 降级）`)
 
-  return { method, spec, installedVersion: installed, lockVersion: lock, lockUpdated, lockNote, command, note: noteParts.join('；'), errors }
+  return { method, spec: specUpdated ?? spec, installedVersion: installed, lockVersion: lock, lockUpdated, lockNote, command, note: noteParts.join('；'), errors }
 }
 
 /**

package/lib/server/routes/compat.js

@@ -0,0 +1,69 @@
+// L2 · routes —— 门控常驻化（观察者/托管模式 · 环境指纹 · 回滚点）
+//   GET  /plugin-console/compat-status   一次拿齐：模式 + 框架版本 + 指纹变化 + 回滚点可用性
+//   POST /plugin-console/compat-mode     切换运行模式（managed / observer）
+//   POST /plugin-console/compat-stamp    把当前指纹记为基线（用户确认「环境变更」后调用）
+//
+// 与 /framework-preflight 的分工：预检负责「扫什么」，这里负责「什么时候扫、以什么模式守门」。
+// 触发源不再是我们的升级按钮，而是环境指纹变化 —— 官方桌面端自带升级器 / 官方只发桌面端 /
+// 手动 pnpm 操作，都会在这里被发现（见 domain/compat-state.js 头注释）。
+
+import { dirname } from 'node:path'
+import { compareFingerprint, computeFingerprint, readCompatMode, readFingerprint, readRollbackRecord, stampFingerprint, writeCompatMode } from '../domain/compat-state.js'
+import { currentFrameworkVersion } from '../domain/framework.js'
+import { sendError, sendJson } from '../infra/httpd.js'
+import { baseDirOf, profileDirOf, resolvePackageJson } from '../infra/paths.js'
+
+/** 框架运行时根（含 .pnpm 的那层）：换了安装根（npx 缓存 ↔ 桌面端自带运行时）指纹必变。 */
+function frameworkPnpmRoot(ports, profileDir) {
+  try {
+    const baseDir = baseDirOf(ports?.baseUrl ?? 'file:///')
+    const pkgPath = resolvePackageJson('@deepseek-ai/dsh', baseDir, profileDir)
+    if (pkgPath === null) return null
+    return dirname(dirname(pkgPath))
+  } catch {
+    return null
+  }
+}
+
+function currentVersion(rc) {
+  try { return currentFrameworkVersion(rc.ctx) } catch { return null }
+}
+
+/** 当前环境指纹（每次调用都现场算，不做缓存 —— 缓存会让「变更」永远滞后一拍）。 */
+function currentFingerprint(rc) {
+  const profileDir = profileDirOf(rc.ctx)
+  return computeFingerprint({
+    frameworkVersion: currentVersion(rc),
+    pnpmRoot: frameworkPnpmRoot(rc.ctx, profileDir),
+  })
+}
+
+async function routeCompatStatusGet(req, res, rc) {
+  const mode = readCompatMode()
+  const current = currentFingerprint(rc)
+  const previous = readFingerprint()
+  const { changed, reasons, baselineAt } = compareFingerprint(current, previous)
+  sendJson(res, 200, {
+    ok: true,
+    mode: mode.mode,
+    modeSource: mode.source,
+    modeChangedAt: mode.at,
+    frameworkVersion: current.frameworkVersion,
+    fingerprint: { current, previous, changed, reasons, baselineAt },
+    rollback: readRollbackRecord(),
+  })
+}
+
+async function routeCompatMode(req, res, rc) {
+  const wanted = rc.body?.mode
+  const result = writeCompatMode(wanted)
+  if (!result.ok) { sendError(res, 400, result.error); return }
+  sendJson(res, 200, { ok: true, mode: result.mode, note: result.mode === 'observer' ? '观察者模式：只做预检与门控，不接管框架升级' : '托管模式：框架升级与回滚由本控制台负责' })
+}
+
+async function routeCompatStamp(req, res, rc) {
+  const stamped = stampFingerprint(currentFingerprint(rc))
+  sendJson(res, 200, { ok: true, fingerprint: stamped })
+}
+
+export { routeCompatMode, routeCompatStamp, routeCompatStatusGet }

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

@@ -10,6 +10,7 @@
 import { readFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { isFrameworkOwnedPackage } from '../domain/compat.js'
+import { loadContractRules, summarizeContractRules } from '../domain/contract-rules.js'
 import { discoverFormatContract, summarizeContract } from '../domain/format-contract.js'
 import { applyFormatPatch, collectProducerTargets, scanProducerFiles } from '../domain/format-scan.js'
 import { currentFrameworkVersion } from '../domain/framework.js'
@@ -107,6 +108,9 @@ async function routeFrameworkPreflight(req, res, rc) {
     contractWarnings,
     contractSummary: contract === null ? null : summarizeContract(contract),
     sessionFormatVersion: contract?.sessionFormatVersion ?? null,
+    // 规则库覆盖情况（2026-09-24）：预检读的是**数据化规则**，所以它对我们没发过升级包的
+    // 框架版本同样有效；source='unavailable' 时说明规则文件缺失，调用方不应把它当「零发现」。
+    rules: summarizeContractRules(loadContractRules()),
     roots: roots.map((r) => ({ root: r.root, kind: r.kind, moduleName: r.moduleName ?? null })),
     scan,
   })

package/lib/server/routes/index.js

@@ -14,6 +14,7 @@ import { runSuiteInstallJob } from '../domain/suite.js'
 import { readBody, sendError } from '../infra/httpd.js'
 import { routeAiConsent, routeAiEmpowerCancel, routeAiEmpowerList, routeAiEmpowerPlan, routeAiEmpowerRun, routeAiEmpowerStatus } from './ai.js'
 import { routeComponentAutostart, routeComponentStart, routeComponentStatus, routeComponentStop, routeComponents, routeRepoClone, routeRepoLandConfig, routeRepoList, routeRepoOpen, routeRepoRemove } from './components.js'
+import { routeCompatMode, routeCompatStamp, routeCompatStatusGet } from './compat.js'
 import { routeFrameworkUpgrade } from './framework-upgrade.js'
 import { routeFrameworkPreflight, routeFrameworkPreflightPatch } from './framework-preflight.js'
 import { routeCheckUpdate, routeCompatGate, routeFrameworkCheck, routeFrameworkRelaunch, routeFrameworkRollback, routeFrameworkUpgradeStatusGet, routeRestart } from './framework.js'
@@ -33,6 +34,7 @@ const ROUTES_EARLY = [
   { methods: ['GET'], path: `${ROUTE_PREFIX}/gitee-oauth-url`, handler: routeGiteeOauthUrlGet },
   { methods: ['GET'], path: `${ROUTE_PREFIX}/gitee-oauth-callback`, handler: routeGiteeOauthCallbackGet },
   { methods: ['GET'], path: `${ROUTE_PREFIX}/skills-installed`, handler: routeSkillsInstalledGet },  { methods: ['GET'], path: `${ROUTE_PREFIX}/framework-upgrade-status`, handler: routeFrameworkUpgradeStatusGet },
+  { methods: ['GET'], path: `${ROUTE_PREFIX}/compat-status`, handler: routeCompatStatusGet },
   { methods: ['POST'], path: `${ROUTE_PREFIX}/framework-relaunch`, handler: routeFrameworkRelaunch },
 
 ]
@@ -91,6 +93,8 @@ const ROUTES = [
   { methods: ['POST'], path: `${ROUTE_PREFIX}/framework-upgrade`, handler: routeFrameworkUpgrade },
   { methods: ['POST'], path: `${ROUTE_PREFIX}/framework-preflight`, handler: routeFrameworkPreflight },
   { methods: ['POST'], path: `${ROUTE_PREFIX}/framework-preflight-patch`, handler: routeFrameworkPreflightPatch },
+  { methods: ['POST'], path: `${ROUTE_PREFIX}/compat-mode`, handler: routeCompatMode },
+  { methods: ['POST'], path: `${ROUTE_PREFIX}/compat-stamp`, handler: routeCompatStamp },
   { methods: ['POST'], path: `${ROUTE_PREFIX}/framework-rollback`, handler: routeFrameworkRollback },
   { methods: ['POST'], path: `${ROUTE_PREFIX}/restart`, handler: routeRestart },
   { methods: ['POST'], path: `${ROUTE_PREFIX}/toggle`, handler: routeToggle },

package/lib/server/routes/plugins.js

@@ -8,6 +8,7 @@ import { checkPluginFrameworkCompat, probePluginImport, readCompatPending, rowId
 import { pnpmRemove } from '../domain/install-job.js'
 import { curlManualInstall, readExtraBundleOwners } from '../domain/install.js'
 import { disableEntry, enableEntry, readPatchState, removeDisableBlock, removeInsertRow } from '../domain/patch.js'
+import { undeclareProfileDependency } from '../domain/manifest.js'
 import { markPendingAdopted } from '../domain/quarantine.js'
 import { pendingRestartJobs, packageDirIn, needsPnpmRemove, revokePendingInstall } from '../domain/revoke.js'
 import { deriveEntryId, isProtectedModule, listEntries } from '../domain/runtime.js'
@@ -280,7 +281,11 @@ async function routeUninstall(req, res, rc) {
       }
     }
     // 任务记录是否作废看**事实**（包目录真的没了），不看 pnpm 的退出码；删不干净时留着让用户重试
-    if (!existsSync(packageDirIn(profileDir, moduleName))) markJobsRevoked(moduleName, rowId)
+    if (!existsSync(packageDirIn(profileDir, moduleName))) {
+      // 卸载即撤销声明（2026-09-24）：清单里留幽灵依赖的话，下一次 pnpm 操作会把它装回来
+      await undeclareProfileDependency(profileDir, moduleName)
+      markJobsRevoked(moduleName, rowId)
+    }
     sendJson(res, 200, { ok: true, removed: 'entry', packageName: moduleName, restart: false, uninstallError })
     return
 }

package/package.json

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