@noob-stupid/dsh-plugin-console 0.5.1 → 0.5.3

package/README.md

@@ -154,6 +154,29 @@ Requires: DSH ≥ 0.1.0-rc.6 (web profile, with `dsh-client-modules` / `dsh-host
 
 ---
 
+## Screenshots · 界面一览
+
+> 入口挂在**官方插件管理页自己的插槽**（`plugins.bundle.config`，key = 包名）：装完之后它出现在
+> 「设置 → 插件 → 已安装」里我们这一条下面，用的是官方容器与官方风格 —— 不是 DOM 注入，官方更新也不怕。
+
+**1 · 已安装列表里的入口**（官方页，点开我们这条即见）
+
+![Entry inside the official plugins page](docs/images/official-plugins-page.png)
+
+**2 · 「升级安全」面板**（就地展开：运行模式 / 框架版本 / 回滚点 / 环境指纹 / 补声明 / 契约预检 / 各功能入口）
+
+![Upgrade safety panel expanded in place](docs/images/upgrade-safety-panel.png)
+
+**3 · 框架升级 / 回滚**（可选目标版本、常驻的升级进度、一键回滚上一版）
+
+![Framework upgrade and rollback panel](docs/images/framework-upgrade-rollback.png)
+
+**4 · 门控明细**（谁被隔离、为什么：升级预扫 or 启动失败隔离，附来源与时间）
+
+![Compatibility gate detail list](docs/images/compat-gate-detail.png)
+
+---
+
 ## Features
 
 ### Installed plugins (one-click toggle + details)

package/lib/client.js

@@ -91,6 +91,14 @@ window.__ModuleLoader__.load({
 		const zh = {
 			tab: "插件管理",
 			safetyTab: "升级安全",
+			safetyModeManagedShort: "托管",
+			safetyModeObserverShort: "观察者",
+			safetyBackfillTitle: "补声明（已装未声明）",
+			safetyBackfillShort: "{n} 项待补声明",
+			safetyBackfillDesc: "有 {n} 个已装插件没写进 profile 清单 —— 官方/第三方插件页看不见它们，pnpm 操作还可能把它们还原。补声明会把磁盘上的真实版本写进清单（不改包、不重装）。",
+			safetyBackfillNone: "已装插件都在清单里声明过了（官方面板的「已安装」与 pnpm 都能看见）",
+			safetyBackfillBtn: "补声明（{n} 项）",
+			safetyBackfillDone: "补声明完成",
 			safetyMode: "运行模式",
 			safetyModeManaged: "托管：框架升级与回滚由本控制台负责（默认，行为与之前一致）",
 			safetyModeManagedOn: "已切到托管模式：框架升级与回滚仍由本控制台负责",
@@ -366,6 +374,7 @@ window.__ModuleLoader__.load({
 			consentWaiting: "等待授权确认…",
 			dismissFailure: "关闭此条提示",
 			sourcesBtn: "软件源",
+			sourcesTimeout: "读取软件源超时（DSH 可能正在重启或繁忙）——点重试即可",
 			sourcesTitle: "软件源管理",
 			sourcesDesc: "分工：① 软件源 = 下载 npm 包（安装用）；② 索引源 = 市场首页清单 JSON；③ Git 源 = 克隆仓库代码（无 npm 包时）；④ 搜索源 = 搜索时查哪个平台——搜到之后仍按 ①/③ 下载",
 			sourcePrimary: "主源",
@@ -548,6 +557,14 @@ window.__ModuleLoader__.load({
 		const en = {
 			tab: "Plugin console",
 			safetyTab: "Upgrade safety",
+			safetyModeManagedShort: "managed",
+			safetyModeObserverShort: "observer",
+			safetyBackfillTitle: "Missing dependency declarations",
+			safetyBackfillShort: "{n} to declare",
+			safetyBackfillDesc: "{n} installed plugins are not declared in the profile manifest — third-party plugin pages cannot see them and a pnpm operation may restore them. Declaring writes the on-disk version into the manifest (no repack, no reinstall).",
+			safetyBackfillNone: "Every installed plugin is declared in the manifest (visible to plugin pages and pnpm)",
+			safetyBackfillBtn: "Declare {n}",
+			safetyBackfillDone: "Declarations written",
 			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",
@@ -824,6 +841,7 @@ window.__ModuleLoader__.load({
 			dismissFailure: "Dismiss this notice",
 			sourcesBtn: "Sources",
 			sourcesTitle: "Software sources",
+			sourcesTimeout: "Timed out reading sources (the DSH service may be restarting or busy) — hit retry",
 			sourcesDesc: "Roles: ① registry = download npm packages (install); ② index sources = market list JSON; ③ git sources = clone repo code (when no npm package); ④ search sources = where to search — results are still downloaded via ①/③",
 			sourcePrimary: "Primary",
 			setPrimary: "Set primary",
@@ -1943,6 +1961,9 @@ window.__ModuleLoader__.load({
 			react.useEffect(() => {
 				call("/plugin-console/sources").then(
 					(data) => {
+						// 2026-09-24 用户实测：软件源弹窗每次打开都重新请求 → 展开要等（右侧「功能包」里的软件源因为是复用已取到的数据，所以很快）。
+						// 这里把挂载时取到的整份配置缓存下来，弹窗直接渲染缓存；保存/恢复默认后再刷新缓存。
+						setSourcesData((prev) => (prev === null ? data.sources : prev));
 						setSearchSourcesList(data.sources.searchSources ?? []);
 						setGitSourcesList(data.sources.gitSources ?? []);
 					},
@@ -2744,8 +2765,14 @@ window.__ModuleLoader__.load({
 			/** 软件源管理：打开时拉取当前配置。 */
 			const openSources = () => {
 				setSourcesOpen(true);
-				call("/plugin-console/sources").then(
+				// 已有缓存（挂载时取过 / 上次打开取过）→ 立即渲染，不再白等一次往返
+				if (sourcesData !== null && sourcesData.error === undefined) return;
+				// 2026-09-24（图1 复现）：请求若一直不落地，弹窗体只看 sourcesData === null 就会永远显示
+				// 「正在读取插件…」——界面把失败吞掉，用户只能干等。这里给 15s 上限，超时/失败都落到可重试错误态。
+				const timeout = new Promise((resolve) => setTimeout(() => resolve({ __timeout: true }), 15000));
+				Promise.race([call("/plugin-console/sources"), timeout]).then(
 					(data) => {
+						if (data !== null && data.__timeout === true) { setSourcesData({ error: t("sourcesTimeout") }); return }
 						setSourcesData(data.sources);
 						setSearchSourcesList(data.sources.searchSources ?? []);
 						setGiteeClientId(data.sources.gitee?.clientId ?? "");
@@ -2753,7 +2780,7 @@ window.__ModuleLoader__.load({
 						// 未配置时为空表单引导首次填写
 						setGiteeClientSecret("");
 					},
-					(error) => { setSourcesOpen(false); setMessage(t("failed") + "：" + friendlyGithubError(error).message); },
+					(error) => { setSourcesData({ error: friendlyGithubError(error).message }); },
 				);
 			};
 			const saveGiteeSetup = () => {
@@ -4692,7 +4719,11 @@ setMessage(t("failed") + "：" + (data?.reason ?? "未知"));
 							el("p", { className: styles.message }, t("sourcesDesc")),
 							sourcesData === null
 								? el("p", { className: styles.status }, t("loading"))
-								: el("div", { className: styles.accWrap },
+								: sourcesData.error !== undefined
+									? el("div", null,
+										el("p", { className: styles.status }, t("failed") + "：" + sourcesData.error),
+										el("button", { type: "button", className: styles.toggle, onClick: () => { setSourcesData(null); openSources(); } }, t("retry")))
+									: el("div", { className: styles.accWrap },
 									accSection("registries", t("sourcesBtn"), [
 									...sourcesData.registries.map((src) =>
 										editReg !== null && editReg.id === src.id
@@ -4845,28 +4876,32 @@ setMessage(t("failed") + "：" + (data?.reason ?? "未知"));
 					: null,
 			);
 		}
-		// 官方风格「升级安全」页（2026-09-24）：**纯加法**。
-		// 原 tab（id=console）与悬浮面板一行不动；这里把门控常驻化的状态、模式开关、一键适配与各功能入口
-		// 用官方卡片风呈现，并把控制台功能**就地展开**（官方 settings.plugins.tab 插槽的 owner props 是空的，
-		// 没有「切到兄弟 tab」的 API，所以就地承载而不是跳页）。
-		// 触发源已从「我们的升级动作」换成环境指纹变化（服务端 domain/compat-state.js）：
-		// 官方桌面端自带升级器 / 官方只发桌面端时，门控依然守得住。
+		// 「升级安全」入口（2026-09-24 按用户要求改造为**长按钮 + 抽屉**）：纯加法。
+		//   默认只渲染一个长按钮，点开右侧抽屉 —— 里面才是模式开关、状态、一键适配、补声明与各功能入口。
+		//   为什么不直接塞进「图2」那一页：那一页是第三方插件的 tab（@linxin666 的 family-plugins），
+		//   它没有开放任何子插槽；官方 settings.plugins.tab 的 owner props 也是空的（没有切兄弟 tab 的 API）。
+		//   所以做法是「就地抽屉」，而不是往别人的 DOM 里注入（注入会在对方更新时碎掉）。
+		//   原 tab（id=console）与悬浮面板一行未动。
 		function PluginSafetyTab({ t }) {
+			const [open, setOpen] = react.useState(false);
 			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 [backfill, setBackfill] = 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 loadBackfill = async () => {
+				try { const data = await call("/plugin-console/declare-installed", { mode: "plan" }); if (data !== null) setBackfill(data); } catch {}
+			};
+			react.useEffect(() => { ensureSafetyStyle(); load(); loadBackfill(); }, []);
 			const switchMode = async (mode) => {
 				if (busy) return;
 				setBusy(true);
 				try {
-					const data = await call("/plugin-console/compat-mode", { mode: mode });
+					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); }
@@ -4882,55 +4917,99 @@ setMessage(t("failed") + "：" + (data?.reason ?? "未知"));
 					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]]) });
+						const planned = await call("/plugin-console/framework-preflight-patch", { mode: "plan" });
+						const n = (planned && planned.changes && planned.changes.length) || 0;
+						setNote({ text: blockers === 0 ? t("fwPreflightClean") : fill(t("safetyPreflightFound"), [["n", n || 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]]) });
+						const n = (done && done.changes && done.changes.length) || 0;
+						setNote({ text: fill(t("safetyPreflightPatched"), [["n", n]]) });
 					}
 				} catch (error) { setNote({ text: (error && error.message) || t("safetySwitchFailed") }); }
 				finally { setBusy(false); }
 			};
+			const applyBackfill = async () => {
+				if (busy) return;
+				setBusy(true);
+				try {
+					const done = await call("/plugin-console/declare-installed", { mode: "apply" });
+					setNote({ text: (done && done.note) || t("safetyBackfillDone") });
+					await loadBackfill();
+				} 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),
+			// 图标：16px 线条 SVG（用户反馈：emoji 当 logo 太差）
+			const stroke = { width: 16, height: 16, viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: 1.6, strokeLinecap: "round", strokeLinejoin: "round", style: { flex: "0 0 auto", opacity: .8, marginTop: "2px" } };
+			const ICONS = {
+				shield: "M12 3l7 3v6c0 4-3 7-7 9-4-2-7-5-7-9V6z",
+				pin: "M12 17v4M7 4h10l-1 6 3 3H5l3-3z",
+				back: "M11 19l-7-7 7-7M4 12h11a5 5 0 015 5v1",
+				scan: "M4 8V6a2 2 0 012-2h2M20 8V6a2 2 0 00-2-2h-2M4 16v2a2 2 0 002 2h2M20 16v2a2 2 0 01-2 2h-2M9 12h6",
+				list: "M8 6h12M8 12h12M8 18h12M4 6h.01M4 12h.01M4 18h.01",
+				pulse: "M3 12h4l2-5 4 10 2-5h6"
+			};
+			const icon = (key) => el("svg", stroke, el("path", { d: ICONS[key] || ICONS.shield }));
+			const row = (key, title, desc, control) => el("div", { style: { display: "flex", alignItems: "flex-start", gap: "10px", padding: "10px 12px" } },
+				icon(key),
 				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";
+					el("div", { style: { fontSize: "13px", fontWeight: 500 } }, title),
+					el("div", { style: { fontSize: "12px", opacity: .7, marginTop: "2px", wordBreak: "break-word" } }, desc)),
+				control === undefined || control === null ? null : control);
+			const sw = (on, onClick, title) => el("button", { type: "button", title: title, onClick: onClick, disabled: busy, style: { width: "40px", height: "22px", 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", marginTop: "2px" } },
+				el("span", { style: { position: "absolute", top: "3px", left: on ? "21px" : "3px", width: "16px", height: "16px", borderRadius: "50%", background: "#fff", transition: "left .18s cubic-bezier(.34,1.56,.64,1)" } }));
+			const jump = (id, label) => el("button", { key: id, type: "button", className: styles.toggle, style: { marginRight: "8px", marginBottom: "8px" }, onClick: () => setSection((prev) => (prev === id ? null : id)) }, label);
+			const mode = status !== null && status.mode === "observer" ? "observer" : status !== null && status.mode === "managed" ? "managed" : "observer";
 			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" } },
+			const pending = backfill !== null && typeof backfill.count === "number" ? backfill.count : 0;
+			// 触发条：默认只看到这一行（点开在**原地**展开，功能包那种下拉，不走右侧固定抽屉）
+			// 收起/展开：收起时**清掉就地分区**，否则再展开时内嵌控制台会重新挂载并把上次那个面板自动打开一遍
+			// （用户实测：点过「框架升级/回滚」→ 关掉弹窗 → 收起 → 再展开，弹窗又自己弹出来了）
+			const toggleOpen = () => {
+				if (open) { setOpen(false); setSection(null); } else { setOpen(true); }
+			};
+			const trigger = el("button", { type: "button", "aria-expanded": open ? "true" : "false", onClick: toggleOpen, style: { width: "100%", display: "flex", alignItems: "center", gap: "10px", padding: "12px 14px", borderRadius: "12px", border: "1px solid var(--dsw-alias-border-secondary, rgba(127,127,127,.18))", background: "var(--dsw-alias-bg-layer-4, rgba(127,127,127,.10))", cursor: "pointer", textAlign: "left", color: "inherit" } },
+				icon("shield"),
+				el("div", { style: { flex: "1 1 auto", minWidth: "0" } },
+					el("div", { style: { fontSize: "13px", fontWeight: 500 } }, t("safetyTab")),
+					el("div", { style: { fontSize: "12px", opacity: .7, marginTop: "2px" } }, (mode === "observer" ? t("safetyModeObserverShort") : t("safetyModeManagedShort")) + " · " + fw + (pending > 0 ? " · " + fill(t("safetyBackfillShort"), [["n", pending]]) : ""))),
+				el("span", { style: { opacity: .5, flex: "0 0 auto", transform: open ? "rotate(90deg)" : "none", transition: "transform .2s cubic-bezier(.34,1.56,.64,1)" } }, el("svg", { width: 14, height: 14, viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: 2, strokeLinecap: "round", strokeLinejoin: "round" }, el("path", { d: "M9 6l6 6-6 6" }))));
+			const panel = el("div", { className: "pc-safety-panel", style: { marginTop: "8px", padding: "8px", borderRadius: "12px", border: "1px solid var(--dsw-alias-border-secondary, rgba(127,127,127,.18))", background: "var(--dsw-alias-bg-layer-4, rgba(127,127,127,.10))", display: "flex", flexDirection: "column", gap: "4px" } },
+				row("shield", t("safetyMode"), mode === "observer" ? t("safetyModeObserver") : t("safetyModeManaged") + (status !== null && typeof status.modeReason === "string" && status.modeReason !== "" ? "（" + status.modeReason + "）" : ""), sw(mode === "observer", () => switchMode(mode === "observer" ? "managed" : "observer"), t("safetyModeSwitch"))),
+				row("pin", t("safetyFrameworkTitle"), fill(t("safetyFrameworkDesc"), [["v", fw]])),
+				row("back", 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]])),
+				row("scan", 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),
+				row("list", t("safetyBackfillTitle"), pending > 0 ? fill(t("safetyBackfillDesc"), [["n", pending]]) : t("safetyBackfillNone"), pending > 0 ? el("button", { type: "button", className: styles.toggle, disabled: busy, onClick: applyBackfill }, fill(t("safetyBackfillBtn"), [["n", pending]])) : null),
+				row("pulse", 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")),
+				note === null ? null : el("div", { style: { fontSize: "12px", opacity: .8, padding: "0 12px 6px" } }, note.text),
+				el("div", { style: { padding: "4px 12px 2px" } },
 					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")),
+				section === null ? null : el("div", { style: { margin: "4px 12px 8px", borderTop: "1px solid var(--dsw-alias-border-secondary, rgba(127,127,127,.18))", paddingTop: "10px" } },
 					el(PluginConsoleTab, { t: t, section: section, key: section })));
+			return el("div", null, trigger, open ? panel : null);
+		}
+		// 「功能包」那种就地展开的 Q 弹动画（一次性注入，不依赖外部 CSS）
+		function ensureSafetyStyle() {
+			try {
+				if (typeof document === "undefined" || document.querySelector("style[data-pc-safety]") !== null) return;
+				const tag = document.createElement("style");
+				tag.dataset.pcSafety = "1";
+				tag.textContent = "@keyframes pcSafetyPop{0%{opacity:0;transform:translateY(-6px) scaleY(.96)}60%{opacity:1;transform:translateY(0) scaleY(1.02)}100%{transform:translateY(0) scaleY(1)}}.pc-safety-panel{animation:pcSafetyPop .28s cubic-bezier(.34,1.56,.64,1);transform-origin:top center}";
+				document.head.appendChild(tag);
+			} catch {}
 		}
 		function apply(ctx) {
 			ctx.effect(() => ctx.locale.register(NS, { zh, en }), "plugin-console: dictionaries");
@@ -4943,12 +5022,16 @@ 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"),
+			// 「升级安全」入口：注册进**官方插件管理页自己的子插槽**（2026-09-24 落点更正）。
+			// 官方页 @deepseek-ai/dsh-client-ui-plugin-manager 占 main + sidebar.panellist，
+			// 并声明了 children 子插槽；其中 `plugins.bundle.config` 按**包名**挂该 bundle 的配置卡片：
+			//   渲染点 = renderSlot("plugins.bundle.config", { view: "page" }, { entryKey: pkg.name })
+			//   且仅当 configured = ledger.bundles.has(pkg.name) 为真 —— 我们是 profile bundle，天然满足。
+			// 所以入口长在那一页「已安装 → 我们的 bundle」详情里，用的是官方容器与官方风格，不是 DOM 注入。
+			// 之前那个独立的「升级安全」tab 已按用户要求关闭（错误落点不占位）；原 tab(id=console) 一行未动。
+			ctx.slots.inject("plugins.bundle.config", () => ctx.slots.register({
+				name: "plugins.bundle.config",
+				key: "@noob-stupid/dsh-plugin-console",
 				locale: NS,
 				inject: () => ({}),
 			}, PluginSafetyTab));

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

@@ -14,7 +14,8 @@ import { dshHome } from '../infra/paths.js'
 
 /** 运行模式。managed = 托管（我们负责框架升级与回滚，既有行为）；observer = 观察者（只守门，不碰升级）。 */
 const COMPAT_MODES = ['managed', 'observer']
-const DEFAULT_MODE = 'managed'
+// 默认**观察者**（用户 2026-09-24 定）：只守门、不接管框架升级；一旦用户走了本控制台的框架升级，服务端会自动切回托管
+const DEFAULT_MODE = 'observer'
 
 const stateDir = () => join(dshHome(), 'plugin-console')
 const modeFile = () => join(stateDir(), 'compat-mode.json')
@@ -41,18 +42,18 @@ function writeJson(path, value) {
 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' }
+  return { mode, at: typeof rec?.at === 'number' ? rec.at : null, reason: typeof rec?.reason === 'string' ? rec.reason : null, source: rec === null ? 'default' : 'file' }
 }
 
 /**
  * 写运行模式（只接受白名单值，避免拼错导致「模式静默失效」）。
  * @returns {{ ok: boolean, mode: string, error?: string }}
  */
-function writeCompatMode(mode) {
+function writeCompatMode(mode, meta = {}) {
   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() })
+  writeJson(modeFile(), { mode, at: Date.now(), reason: typeof meta.reason === 'string' ? meta.reason : null })
   return { ok: true, mode }
 }
 

package/lib/server/domain/manifest.js

@@ -117,4 +117,50 @@ async function undeclareProfileDependency(profileDir, packageName) {
   })
 }
 
-export { DEFAULT_BUNDLES, addBundleToManifest, declareProfileDependency, installedVersionOf, removeBundleFromManifest, undeclareProfileDependency }
+/**
+ * 扫描「已装但未声明」的插件（补声明用）。
+ *
+ * 判据刻意保守：只看 profile 的 `dsh.profile.bundles` 里**非默认**且**真装在磁盘上**的包。
+ * 为什么不扫整个 node_modules：那会把框架自带包、传递依赖一并卷进来（它们本来就不该出现在
+ * 用户清单里）。bundles 是「用户显式加进组合树的东西」—— 正是该被声明的那一批。
+ *
+ * 为什么值得做（2026-09-24 用户实测）：第三方插件管理器（如 @linxin666 的插件页）与 pnpm
+ * 都只认清单里的依赖 —— 手铺安装的包在它们眼里不存在：看不见，还会被 pnpm 还原。
+ * @returns {{ candidates: {name: string, version: string}[], skipped: {name: string, reason: string}[] }}
+ */
+async function planDependencyBackfill(profileDir) {
+  const manifest = await readManifest(profileDir)
+  const bundles = Array.isArray(manifest.dsh?.profile?.bundles) ? manifest.dsh.profile.bundles : []
+  const deps = manifest.dependencies ?? {}
+  const candidates = []
+  const skipped = []
+  for (const name of bundles) {
+    if (typeof name !== 'string' || name === '') continue
+    if (DEFAULT_BUNDLES.includes(name)) continue
+    if (typeof deps[name] === 'string' && deps[name] !== '') continue
+    const version = await installedVersionOf(profileDir, name)
+    if (version === null) {
+      skipped.push({ name, reason: '磁盘上读不到已安装版本（可能已卸载）' })
+      continue
+    }
+    candidates.push({ name, version })
+  }
+  return { candidates, skipped }
+}
+
+/** 执行补声明：逐条写入清单（每条独立走写队列，一条失败不影响其它）。 */
+async function applyDependencyBackfill(profileDir) {
+  const { candidates, skipped } = await planDependencyBackfill(profileDir)
+  const declared = []
+  for (const item of candidates) {
+    const result = await declareProfileDependency(profileDir, item.name, item.version)
+    if (result.changed) declared.push({ name: item.name, version: result.version })
+    else skipped.push({ name: item.name, reason: result.reason ?? '无需改动' })
+  }
+  return { declared, skipped }
+}
+
+export {
+  DEFAULT_BUNDLES, addBundleToManifest, applyDependencyBackfill, declareProfileDependency,
+  installedVersionOf, planDependencyBackfill, removeBundleFromManifest, undeclareProfileDependency,
+}

package/lib/server/routes/compat.js

@@ -1,15 +1,20 @@
-// L2 · routes —— 门控常驻化（观察者/托管模式 · 环境指纹 · 回滚点）
-//   GET  /plugin-console/compat-status   一次拿齐：模式 + 框架版本 + 指纹变化 + 回滚点可用性
-//   POST /plugin-console/compat-mode     切换运行模式（managed / observer）
-//   POST /plugin-console/compat-stamp    把当前指纹记为基线（用户确认「环境变更」后调用）
+// L2 · routes —— 门控常驻化（观察者/托管模式 · 环境指纹 · 回滚点）+ 官方互操作
+//   GET  /plugin-console/compat-status      一次拿齐：模式 + 框架版本 + 指纹变化 + 回滚点可用性
+//   POST /plugin-console/compat-mode        切换运行模式（managed / observer）
+//   POST /plugin-console/compat-stamp       把当前指纹记为基线（用户确认「环境变更」后调用）
+//   POST /plugin-console/declare-installed  补声明：把「已装但未声明」的插件写进 profile 依赖
 //
 // 与 /framework-preflight 的分工：预检负责「扫什么」，这里负责「什么时候扫、以什么模式守门」。
 // 触发源不再是我们的升级按钮，而是环境指纹变化 —— 官方桌面端自带升级器 / 官方只发桌面端 /
 // 手动 pnpm 操作，都会在这里被发现（见 domain/compat-state.js 头注释）。
+//
+// declare-installed 存在的理由（2026-09-24 用户实测）：第三方插件管理器与 pnpm 都只认清单里的
+// 依赖，手铺安装的包在它们眼里不存在（看不见 + 会被还原）。老规矩：先 plan 再 apply。
 
 import { dirname } from 'node:path'
 import { compareFingerprint, computeFingerprint, readCompatMode, readFingerprint, readRollbackRecord, stampFingerprint, writeCompatMode } from '../domain/compat-state.js'
 import { currentFrameworkVersion } from '../domain/framework.js'
+import { applyDependencyBackfill, planDependencyBackfill } from '../domain/manifest.js'
 import { sendError, sendJson } from '../infra/httpd.js'
 import { baseDirOf, profileDirOf, resolvePackageJson } from '../infra/paths.js'
 import { existsSync } from 'node:fs'
@@ -62,6 +67,7 @@ async function routeCompatStatusGet(req, res, rc) {
     mode: mode.mode,
     modeSource: mode.source,
     modeChangedAt: mode.at,
+    modeReason: mode.reason ?? null,
     frameworkVersion: current.frameworkVersion,
     fingerprint: { current, previous, changed, reasons, baselineAt },
     rollback: readRollbackRecord(),
@@ -80,4 +86,29 @@ async function routeCompatStamp(req, res, rc) {
   sendJson(res, 200, { ok: true, fingerprint: stamped })
 }
 
-export { routeCompatMode, routeCompatStamp, routeCompatStatusGet }
+/** 补声明：plan 只报「有几项要补」，apply 真写清单（逐条写、逐条回报）。 */
+async function routeDeclareInstalled(req, res, rc) {
+  const mode = rc.body?.mode === 'apply' ? 'apply' : 'plan'
+  const profileDir = profileDirOf(rc.ctx)
+  try {
+    if (mode === 'apply') {
+      const result = await applyDependencyBackfill(profileDir)
+      sendJson(res, 200, {
+        ok: true,
+        mode,
+        declared: result.declared,
+        skipped: result.skipped,
+        note: result.declared.length === 0
+          ? '没有需要补声明的插件'
+          : `已补声明 ${result.declared.length} 项 —— 它们现在会出现在官方/第三方插件页的「已安装」里，也不会再被 pnpm 还原`,
+      })
+      return
+    }
+    const plan = await planDependencyBackfill(profileDir)
+    sendJson(res, 200, { ok: true, mode, candidates: plan.candidates, skipped: plan.skipped, count: plan.candidates.length })
+  } catch (error) {
+    sendError(res, 500, `补声明失败：${error instanceof Error ? error.message : String(error)}`)
+  }
+}
+
+export { routeCompatMode, routeCompatStamp, routeCompatStatusGet, routeDeclareInstalled }

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

@@ -10,6 +10,7 @@ import { dirname, join } from 'node:path'
 import { tmpdir } from 'node:os'
 import { pathToFileURL } from 'node:url'
 import { createRequire } from 'node:module'
+import { readCompatMode, writeCompatMode } from '../domain/compat-state.js'
 import { FRAMEWORK_BACKUP_ROOT, backupProfileSnapshot, checkpointFrameworkTree, preflightDisableIncompatible, relaunchPrelude, resolveDshBin, resolveFrameworkRootNodeModules, resolveFrameworkUpgradePlan } from '../domain/framework.js'
 import { fwIntegrityCheck } from '../infra/fw-integrity-check.js'
 import { CORE_PATCH_ROW_IDS } from '../domain/patch.js'
@@ -22,6 +23,21 @@ import { sendError, sendJson } from '../infra/httpd.js'
 import { dshHome, findPatchPath, pluginRoot } from '../infra/paths.js'
 import { setFwCheckCache } from '../state.js'
 
+/**
+ * 用户语义（2026-09-24）：「运行模式」默认开启 = **观察者**（只守门、不接管升级）；
+ * 但只要有人走了本控制台这条框架升级路径，就**自动切回托管** —— 此时升级确实由我们负责。
+ * 返回提示文案（无切换时返回 null）。
+ */
+function autoSwitchToManaged(reason) {
+  try {
+    if (readCompatMode().mode === 'managed') return null
+    writeCompatMode('managed', { reason })
+    return '检测到使用本控制台的框架升级：运行模式已自动切回「托管」'
+  } catch {
+    return null
+  }
+}
+
 async function routeFrameworkUpgrade(req, res, rc) {
   const backupProfileSnapshot = rc.deps.backupProfileSnapshot
   const preflightDisableIncompatible = rc.deps.preflightDisableIncompatible
@@ -103,6 +119,9 @@ async function routeFrameworkUpgrade(req, res, rc) {
     // 保证新框架 boot 时不会被某行 import 失败拖垮（loader 单行失败 = 整个服务起不来）。
     let preflight = { disabled: [], skipped: [] }
     if (hasUpdate) {
+      // 用户语义（2026-09-24）：走本控制台这条升级路径 = 升级由我们负责 → 自动从观察者切回托管
+      const switched = autoSwitchToManaged('使用本控制台执行框架升级')
+      if (switched !== null) steps.push(switched)
       try {
         preflight = await preflightDisableIncompatible({ ports: ctx, profileDir, patchPath: findPatchPath(ctx), targetVersion: target })
       } catch (error) {

package/lib/server/routes/index.js

@@ -14,7 +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 { routeCompatMode, routeCompatStamp, routeCompatStatusGet, routeDeclareInstalled } 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'
@@ -95,6 +95,7 @@ const ROUTES = [
   { 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}/declare-installed`, handler: routeDeclareInstalled },
   { 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/package.json

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