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

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,94 @@ 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" } }));
+					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(id) }, label);
-			const mode = status !== null && status.mode === "observer" ? "observer" : "managed";
+			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 trigger = el("button", { type: "button", "aria-expanded": open ? "true" : "false", onClick: () => setOpen((prev) => !prev), 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 +5017,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,25 +1,44 @@
-// 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'
+import { join } from 'node:path'
 
-/** 框架运行时根（含 .pnpm 的那层）：换了安装根（npx 缓存 ↔ 桌面端自带运行时）指纹必变。 */
+/** 框架运行时根（含 .pnpm 的那层）：换了安装根（npx 缓存 ↔ 桌面端自带运行时）指纹必变。
+ *  `@deepseek-ai/dsh` 既可能解析到 `<root>/node_modules/@deepseek-ai/dsh`（顶层投影），
+ *  也可能落在 `<root>/.pnpm/@deepseek-ai+dsh@…/node_modules/…`（实体内部）—— 后者直接
+ *  `dirname(dirname())` 会停在 `.pnpm` **内部**、数不到包数（门槛实测 `entities=null`）。
+ *  所以向上逐级找「含 .pnpm 的那一层」为止。 */
 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))
+    const direct = dirname(dirname(pkgPath))
+    let dir = direct
+    for (let i = 0; i < 6; i += 1) {
+      if (existsSync(join(dir, '.pnpm'))) return dir
+      const parent = dirname(dir)
+      if (parent === dir) break
+      dir = parent
+    }
+    return direct
   } catch {
     return null
   }
@@ -48,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(),
@@ -66,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.0",
+  "version": "0.5.2",
   "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",