@max-null/dsh-quick-toolbar 0.1.0 → 0.3.1

package/README.md

@@ -1,8 +1,12 @@
-# @max-null/dsh-quick-toolbar — 插件按钮聚合器
+# @max-null/dsh-quick-toolbar
 
-把三方插件散乱的按钮（插件中心/侧栏/底栏/会话管理…）聚合到**统一入口**：
-SSiD 壳 → 标题栏按钮组；DSH web → **iOS 小白点式悬浮球**（自由定位拖拽、球↔面板 morph 展开、球永远锁定面板屏幕外侧角）。
-适配器驱动：内置适配集开箱即识；**用户环境下 LLM 按模板生成适配**（驻场工程师模式）——不要求三方插件配合。
+本插件属于 **`@max-null/*` 插件系列**——这一系列共同构成 **[SSID（思灵 · Seek Soul in Darkness）](https://github.com/Max-Null/seek-soul-in-darkness)** 桌面体验。SSID 是整合它们的盒：`dsh-capture` · `dsh-chat-rail` · `dsh-chinese-thinking` · `dsh-draft-polish` · `dsh-guardian` · `dsh-habit` · `dsh-memory` · `dsh-node-appearance` · `dsh-plugin-center` · `dsh-quick-toolbar` · `dsh-skill-mcp-center` · `dsh-ssid-panels` · `dsh-ssid-zh-ui`。
+
+This plugin belongs to the **`@max-null/*` family** — a set of plugins that together form the **[SSID (思灵 · Seek Soul in Darkness)](https://github.com/Max-Null/seek-soul-in-darkness)** desktop experience.
+
+面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的**插件按钮聚合器**：把三方插件散乱的按钮（插件中心/侧栏/底栏/会话管理…）聚合到统一入口——SSiD 壳 → 标题栏按钮组；DSH web → **iOS 小白点式悬浮球**（自由定位拖拽、球↔面板 morph 展开、球永远锁定面板屏幕外侧角）。适配器驱动：内置适配集开箱即识；**用户环境下 LLM 按模板生成适配**（驻场工程师模式）——不要求三方插件配合。
+
+A **plugin-button aggregator** for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness): gathers scattered third-party plugin buttons (plugin center / sidebar / bottom bar / session manager …) into one entry — an SSiD title-bar button group in the SSID shell, and an iOS assistive-touch-style floating ball on plain DSH web (free positioning & dragging, ball↔panel morph expand, ball always locked to the panel's screen-outer corner). Adapter-driven: bundled adapters work out of the box; in any user environment, an LLM generates new adapters from a template (the "on-site engineer" mode) — no cooperation required from third-party plugins.
 
 ## 截图
 
@@ -21,18 +25,21 @@ dsh plugin --profile web add @max-null/dsh-quick-toolbar
 
 ## 使用
 
-- **聚合按钮**：标题栏/悬浮球点开面板 → 一键触发各插件功能（再点关闭——会话管理探测弹窗关闭按钮）。
-- **用户适配器**：复制 `adapters.prompt.md` + 环境描述 → 让 LLM 生成 `{ "adapters": [...] }` → 写入 `~/.dsh/quick-toolbar-adapters.json` → 重启/热载生效（schema 校验，非法条目丢弃并报明细）。
+- **聚合按钮**：标题栏/悬浮球点开面板 → 一键触发各插件功能（再点关闭——会话管理探测弹窗关闭按钮；设置面板语义锚点打开/再点关闭）。
+- **内置入口**：悬浮球含「设置」（官方设置面板：引擎按语义锚点定位 footer 触发器，双 locale；再点关闭——DSH trigger 原生只开不关）。
+- **壳环境（SSiD）**：悬浮球默认隐藏（标题栏接管入口）；标题栏「悬浮球」开关按钮（圆圈+圆点图标）可开启。
+- **用户适配器**：复制 `adapters.prompt.md` + 环境描述 → 让 LLM 生成 `{ "adapters": [...] }` → 写入 `~/.dsh/quick-toolbar-adapters.json` → 刷新页面生效（host API 校验，非法条目丢弃并报明细）。
 - 定位失败/插件未装/被禁用 → 静默跳过（绝不误伤、绝不误点）。
+- **状态持久化**：位置/钉住/折叠/壳开关走 host（`/quick-toolbar/api/state` → `~/.dsh/quick-toolbar-state.json`，SSiD 开发手册 §7.10 规则）——内核动态端口不再丢状态。
 
 ## 架构
 
 - `src/adapters.ts`：适配器 schema + 内置适配器集（黄金示例）
-- `src/behaviors.ts`：行为库（click / toggle-panel / dispatch-event / open-settings / command）
+- `src/behaviors.ts`：行为库（click / toggle-panel / dispatch-event / open-settings（语义锚点+再点关闭）/ command（composer 注入）——全部实现，v2 M1）
 - `src/engine.ts`：执行器（防御执行）
 - `src/schema.ts`：用户配置 zod 校验（LLM 产物防线）
-- `src/index.ts`：host 半 `GET /quick-toolbar/api/adapters`
-- 设计文档：`doc/设计/2026-08-30-quick-toolbar-独立化设计方案.md`
+- `src/index.ts`（host 半）：`GET /quick-toolbar/api/adapters`（用户适配器）+ `GET/POST /quick-toolbar/api/state`（状态 host 化，原子写）
+- 设计文档：`doc/设计/2026-08-30-quick-toolbar-独立化设计方案.md`、`doc/设计/2026-08-30-quick-toolbar-v2设计.md`
 
 ## 开发
 

package/lib/client.js

@@ -51,9 +51,139 @@ const BUILTIN_ADAPTERS = [
 			close: ".sm-modal .close"
 		},
 		hide: true
+	},
+	{
+		id: "dsh-settings",
+		button: "button[aria-label=\"设置\"], button[aria-label=\"Settings\"]",
+		icon: {
+			source: "custom",
+			value: "settings"
+		},
+		label: "设置",
+		act: { kind: "open-settings" },
+		hide: false
 	}
 ];
 //#endregion
+//#region src/behaviors.ts
+/**
+* 直接点击目标（定位失败/禁用 → 静默跳过；称「防御执行」）。
+*/
+function actClick(target) {
+	if (target === null || target === void 0 || target.disabled === true) return false;
+	target.click();
+	return true;
+}
+/**
+* 面板开/关：再点关闭（探测 close 选择器内的「关闭」按钮——原生无
+* 再点关闭的插件（如 dsh-session-manager 0.4.x）走此行为。
+*/
+function actTogglePanel(panel, closeTarget) {
+	if (panel.isOpen()) {
+		if (closeTarget !== null && closeTarget !== void 0 && closeTarget.disabled !== true) {
+			closeTarget.click();
+			return true;
+		}
+		return false;
+	}
+	panel.open();
+	return true;
+}
+/** 官方设置触发器锚点链（v2 调研点① 结论：DSH 面板 open 状态由 shell 私有，
+*  公开语义入口 = sidebar.settings 槽的触发按钮——SettingsRoot.tsx onClick
+*  setOpen(true)，footer 触发器类后缀 `_trigger`、无 aria。 */
+const SETTINGS_ANCHORS = [
+	"[class$=\"_trigger\"]",
+	"button[aria-label=\"设置\"]",
+	"button[aria-label=\"Settings\"]",
+	"[role=\"button\"][aria-label=\"设置\"]",
+	"[role=\"button\"][aria-label=\"Settings\"]",
+	"button[title=\"设置\"]",
+	"button[title=\"Settings\"]"
+];
+/** 官方设置关闭目标锚点链（面板开着时二次点击应关闭——trigger onClick 只
+*  setOpen(true) 原生不 toggle，2026-08-30 用户实测「再点关闭失败」）。 */
+const SETTINGS_CLOSE_ANCHORS = [
+	"button[class$=\"_close\"]",
+	"button[aria-label=\"关闭\"]",
+	"button[title=\"关闭\"]"
+];
+/** 设置面板打开判定（modal mask；SettingsRoot.tsx：mask div onClick=onClose）。 */
+const SETTINGS_MASK_SELECTOR = "[class$=\"_mask\"]";
+/** 打开/关闭官方设置面板：开着（mask 存在）→ 关闭（close 按钮 → mask 兜底）；
+*  关着 → 文本语义定位优先（footer trigger）→ 锚点链兜底。 */
+function actOpenSettings(env) {
+	const mask = env.find(SETTINGS_MASK_SELECTOR);
+	if (mask !== null && mask !== void 0) {
+		for (let i = 0; i < SETTINGS_CLOSE_ANCHORS.length; i++) {
+			const closeBtn = env.find(SETTINGS_CLOSE_ANCHORS[i]);
+			if (closeBtn !== null && closeBtn !== void 0 && closeBtn.disabled !== true) {
+				closeBtn.click();
+				return true;
+			}
+		}
+		mask.click();
+		return true;
+	}
+	if (env.findByText !== void 0) {
+		const byText = env.findByText(["设置", "Settings"]);
+		if (byText !== null && byText !== void 0 && byText.disabled !== true) {
+			byText.click();
+			return true;
+		}
+	}
+	for (let i = 0; i < SETTINGS_ANCHORS.length; i++) {
+		const target = env.find(SETTINGS_ANCHORS[i]);
+		if (target !== null && target !== void 0 && target.disabled !== true) {
+			target.click();
+			return true;
+		}
+	}
+	return false;
+}
+/** 触发 dsh-commands 文本命令（空白名防御；执行语义由环境实现——v2 调研点②）。 */
+function actCommand(env, name) {
+	if (name === void 0 || name === null || name.trim() === "") return false;
+	return env.execute(name.trim());
+}
+//#endregion
+//#region src/engine.ts
+/**
+* @max-null/dsh-quick-toolbar — 适配器执行器（DOM 绑定层）
+*
+* 引擎运行时：按适配器定位目标元素 → 调行为库 → 防御执行。
+* 行为库保持窄接口（可测）；本层唯一负责 DOM 绑定（browser 环境，
+* 不在 node:test 的范围里——DOM 交互留给 L2 环境验证）。
+*/
+/** 选择器转义（不依赖 CSS 全局——node:test 无 DOM/CSS，行为库测试可用） */
+function cssEscape(name) {
+	return name.replace(/[^a-zA-Z0-9_-]/g, (c) => `\\${c}`);
+}
+/** 按内置定义执行一条适配器（防御执行：定位失败/禁用 → false，绝不误伤） */
+function runAdapter(adapter, env) {
+	switch (adapter.act.kind) {
+		case "click": return actClick(env.find(adapter.button));
+		case "dispatch-event": return env.dispatch(adapter.act.event, adapter.act.detail);
+		case "toggle-panel": {
+			const panel = env.findPanel(`#${cssEscape(adapter.id)}-panel`);
+			if (panel !== null) return actTogglePanel(panel, adapter.act.close !== void 0 ? env.find(adapter.act.close) : null);
+			return false;
+		}
+		case "open-settings":
+			if (adapter.act.path !== void 0) console.warn(`quick-toolbar: open-settings path '${adapter.act.path}' 暂不支持（v2 深链待入）`);
+			return actOpenSettings({
+				find: env.find,
+				...env.findByText !== void 0 ? { findByText: env.findByText } : {}
+			});
+		case "command":
+			if (env.runCommand === void 0) {
+				console.warn("quick-toolbar: command 环境无 runCommand 通道（旧版 DSH/未注入）");
+				return false;
+			}
+			return actCommand({ execute: env.runCommand }, adapter.act.name);
+	}
+}
+//#endregion
 //#region src/client.ts
 /**
 * @max-null/dsh-quick-toolbar — browser half.
@@ -258,9 +388,40 @@ window.__ModuleLoader__.load({
 			applyLocale();
 		}
 		var TOOLBAR_ID = "ssid-toolbar";
-		var TOOLBAR_POS_KEY = "ssid-toolbar-pos";
-		var TOOLBAR_COLLAPSED_KEY = "ssid-toolbar-collapsed";
-		var TOOLBAR_PINNED_KEY = "ssid-toolbar-pinned";
+		var qtState = {
+			pos: null,
+			collapsed: true,
+			pinned: false,
+			shellVisible: false
+		};
+		var loadState = function(done) {
+			fetch("/quick-toolbar/api/state").then(function(r) {
+				return r.json();
+			}).then(function(data) {
+				var s = data !== null && typeof data === "object" && data.ok === true ? data.state : void 0;
+				if (s !== void 0 && s !== null) {
+					if (s.pos !== null && s.pos !== void 0 && typeof s.pos.x === "number" && typeof s.pos.y === "number") qtState.pos = {
+						x: s.pos.x,
+						y: s.pos.y
+					};
+					if (typeof s.collapsed === "boolean") qtState.collapsed = s.collapsed;
+					if (typeof s.pinned === "boolean") qtState.pinned = s.pinned;
+					if (typeof s.shellVisible === "boolean") qtState.shellVisible = s.shellVisible;
+				}
+				done();
+			}).catch(function() {
+				done();
+			});
+		};
+		var saveState = function() {
+			try {
+				fetch("/quick-toolbar/api/state", {
+					method: "POST",
+					headers: { "Content-Type": "application/json" },
+					body: JSON.stringify(qtState)
+				}).catch(function() {});
+			} catch (_e) {}
+		};
 		var TOOLBAR_CSS = [
 			"#ssid-toolbar{position:fixed;z-index:9999;font-family:system-ui,\"Segoe UI\",sans-serif;user-select:none;-webkit-user-select:none;box-sizing:border-box;width:36px;height:36px;border-radius:18px;background:var(--dsw-alias-bg-layer-3,#10151f);border:1px solid var(--dsw-alias-border-l2,#1e2836);box-shadow:0 4px 16px rgba(0,0,0,.3);overflow:hidden;transition:width .28s cubic-bezier(.25,.8,.25,1),height .28s cubic-bezier(.25,.8,.25,1),left .28s cubic-bezier(.25,.8,.25,1),top .28s cubic-bezier(.25,.8,.25,1),border-radius .28s cubic-bezier(.25,.8,.25,1)}",
 			"#ssid-toolbar *{box-sizing:border-box}",
@@ -288,10 +449,61 @@ window.__ModuleLoader__.load({
 				sessions: "<svg viewBox=\"0 0 16 16\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.5\"><rect x=\"2\" y=\"3\" width=\"12\" height=\"10\" rx=\"1.5\"/><path d=\"M5 6.5h6M5 9.5h4\" stroke-linecap=\"round\"/></svg>",
 				collapse: "<svg viewBox=\"0 0 16 16\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.5\"><path d=\"M3 5.5h10M6.5 8.5h3M8 11.5h1\" stroke-linecap=\"round\"/></svg>",
 				menu: "<svg viewBox=\"0 0 16 16\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.5\"><path d=\"M3 5h10M3 8h10M3 11h10\" stroke-linecap=\"round\"/></svg>",
-				pin: "<svg viewBox=\"0 0 16 16\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.5\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><path d=\"M9.8 2.2l4 4-2.6 1.4-1.8 1.8.4 2.6-1.4 1.4-2.6-3L3.9 13l-1-1 3-3.9-3-2.6 1.4-1.4 2.6.4 1.8-1.8z\"/></svg>"
+				pin: "<svg viewBox=\"0 0 16 16\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.5\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><path d=\"M9.8 2.2l4 4-2.6 1.4-1.8 1.8.4 2.6-1.4 1.4-2.6-3L3.9 13l-1-1 3-3.9-3-2.6 1.4-1.4 2.6.4 1.8-1.8z\"/></svg>",
+				settings: "<svg viewBox=\"0 0 16 16\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.5\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><circle cx=\"8\" cy=\"8\" r=\"2.2\"/><path d=\"M8 1.8v2M8 12.2v2M1.8 8h2M12.2 8h2M3.6 3.6l1.4 1.4M11 11l1.4 1.4M12.4 3.6L11 5M5 11l-1.4 1.4\"/></svg>"
 			};
 			return ICONS[name] || ICONS.grid;
 		}
+		var toolbarEnv = function() {
+			return {
+				find: function(s) {
+					return document.querySelector(s);
+				},
+				findPanel: function(s) {
+					return null;
+				},
+				dispatch: function(event, detail) {
+					window.dispatchEvent(new CustomEvent(event, { detail }));
+					return true;
+				},
+				findByText: function(texts) {
+					var buttons = document.querySelectorAll("button");
+					for (var bi = 0; bi < buttons.length; bi++) {
+						var label = (buttons[bi].textContent || "").trim();
+						for (var ti = 0; ti < texts.length; ti++) if (label === texts[ti]) return buttons[bi];
+					}
+					return null;
+				},
+				runCommand: function(name) {
+					return typeCommandIntoComposer(name);
+				}
+			};
+		};
+		function typeCommandIntoComposer(name) {
+			var seat = document.querySelector("[data-composer-seat]");
+			var el = seat !== null && seat !== void 0 ? seat.querySelector("textarea, [contenteditable=\"true\"]") : document.querySelector("textarea, [contenteditable=\"true\"]");
+			if (el === null || el === void 0) return false;
+			var text = "/" + name;
+			if (el instanceof HTMLTextAreaElement) {
+				var setter = Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, "value");
+				if (setter !== void 0 && setter.set !== void 0) setter.set.call(el, text);
+				else el.value = text;
+			} else if (el.isContentEditable) el.textContent = text;
+			else return false;
+			el.dispatchEvent(new InputEvent("input", {
+				bubbles: true,
+				inputType: "insertText",
+				data: text
+			}));
+			el.focus();
+			el.dispatchEvent(new KeyboardEvent("keydown", {
+				key: "Enter",
+				code: "Enter",
+				bubbles: true,
+				cancelable: true
+			}));
+			return true;
+		}
 		function toolbarAction(kind) {
 			if (kind === "plugin") {
 				closeSidePanelsBeforePluginCenter();
@@ -317,7 +529,7 @@ window.__ModuleLoader__.load({
 			}
 		}
 		function createToolbar() {
-			if (win.__SSID_SHELL__ === true) return;
+			if (win.__SSID_SHELL__ === true && !qtState.shellVisible) return;
 			if (document.getElementById(TOOLBAR_ID) !== null) return;
 			var root = document.createElement("div");
 			root.id = TOOLBAR_ID;
@@ -341,33 +553,66 @@ window.__ModuleLoader__.load({
 				"dsh-better-sidebar.bottom": "bottom",
 				"dsh-session-manager": "sessions"
 			};
-			var items = [];
-			for (var ai = 0; ai < BUILTIN_ADAPTERS.length; ai++) {
-				var adapter = BUILTIN_ADAPTERS[ai];
-				var kind = TOOLBAR_KIND_BY_ADAPTER[adapter.id];
-				if (kind === void 0) continue;
-				items.push({
-					kind,
-					adapter
-				});
-			}
-			for (var i = 0; i < items.length; i++) {
+			var adapterIconHtml = function(adapter, kind) {
+				if (adapter.icon.source === "custom") {
+					var value = adapter.icon.value;
+					if (value.indexOf("<") === 0) return value;
+					return toolbarIcon(value);
+				}
+				return kind !== null ? toolbarIcon(kind) : toolbarIcon("grid");
+			};
+			var renderButton = function(adapter, kind) {
 				var b = document.createElement("button");
 				b.type = "button";
 				b.className = "ssid-tb-btn";
-				b.innerHTML = toolbarIcon(items[i].kind) + "<span></span>";
-				b.setAttribute("aria-label", "");
-				b.title = "";
-				trackLocale(b, "tb." + items[i].kind, "text-span");
-				trackLocale(b, "tb." + items[i].kind, "aria");
-				trackLocale(b, "tb." + items[i].kind, "title");
-				(function(kind) {
-					b.addEventListener("click", function() {
+				b.setAttribute("data-adapter-id", adapter.id);
+				b.innerHTML = adapterIconHtml(adapter, kind) + "<span></span>";
+				if (kind !== null) {
+					b.setAttribute("aria-label", "");
+					b.title = "";
+					trackLocale(b, "tb." + kind, "text-span");
+					trackLocale(b, "tb." + kind, "aria");
+					trackLocale(b, "tb." + kind, "title");
+				} else {
+					var label = adapter.label !== void 0 ? adapter.label : adapter.id;
+					var textSpan = b.querySelector("span");
+					if (textSpan !== null) textSpan.textContent = label;
+					b.setAttribute("aria-label", label);
+					b.title = label;
+				}
+				b.addEventListener("click", function() {
+					if (kind !== null) {
 						toolbarAction(kind);
-					});
-				})(items[i].kind);
+						return;
+					}
+					runAdapter(adapter, toolbarEnv());
+				});
 				panel.appendChild(b);
+			};
+			for (var ai = 0; ai < BUILTIN_ADAPTERS.length; ai++) {
+				var adapter = BUILTIN_ADAPTERS[ai];
+				var kind = TOOLBAR_KIND_BY_ADAPTER[adapter.id];
+				renderButton(adapter, kind !== void 0 ? kind : null);
 			}
+			var fetchUserAdapters = function() {
+				fetch("/quick-toolbar/api/adapters").then(function(r) {
+					return r.json();
+				}).then(function(data) {
+					var envelope = data !== null && typeof data === "object" ? data : void 0;
+					var rows = envelope !== void 0 && envelope.ok === true && envelope.value !== null && typeof envelope.value === "object" ? envelope.value.adapters : void 0;
+					if (!Array.isArray(rows)) return;
+					for (var ui = 0; ui < rows.length; ui++) {
+						var user = rows[ui];
+						if (user === null || typeof user !== "object") continue;
+						var userKind = TOOLBAR_KIND_BY_ADAPTER[user.id];
+						try {
+							var old = panel.querySelector("[data-adapter-id=\"" + user.id.replace(/"/g, "\\\"") + "\"]");
+							if (old !== null && old.parentNode === panel) panel.removeChild(old);
+						} catch (_e) {}
+						renderButton(user, userKind !== void 0 ? userKind : null);
+					}
+				}).catch(function() {});
+			};
 			var ball = document.createElement("button");
 			ball.type = "button";
 			ball.id = TOOLBAR_ID + "-ball";
@@ -384,13 +629,10 @@ window.__ModuleLoader__.load({
 			var BALL_R = 18;
 			var expanded = false;
 			var ballX = 0, ballY = 0;
-			try {
-				var savedPos = JSON.parse(String(localStorage.getItem(TOOLBAR_POS_KEY) || "null"));
-				if (savedPos !== null && typeof savedPos.x === "number" && typeof savedPos.y === "number") {
-					ballX = savedPos.x;
-					ballY = savedPos.y;
-				}
-			} catch (_e) {}
+			if (qtState.pos !== null) {
+				ballX = qtState.pos.x;
+				ballY = qtState.pos.y;
+			}
 			if (ballX === 0 && ballY === 0) {
 				ballX = window.innerWidth - BALL_SIZE - 16;
 				ballY = window.innerHeight - BALL_SIZE - 16;
@@ -475,14 +717,22 @@ window.__ModuleLoader__.load({
 				}
 				var kids = panel.children;
 				for (var ki = 0; ki < kids.length; ki++) kids[ki].style.transitionDelay = collapsed ? "0ms" : 40 + ki * 24 + "ms";
-				try {
-					localStorage.setItem(TOOLBAR_COLLAPSED_KEY, collapsed ? "1" : "0");
-				} catch (_e) {}
+				qtState.collapsed = collapsed;
+				saveState();
 			};
-			var pinned = false;
 			try {
-				pinned = localStorage.getItem(TOOLBAR_PINNED_KEY) === "1";
+				new ResizeObserver(function() {
+					if (!expanded) return;
+					var w2 = panel.offsetWidth + 2;
+					var h2 = panel.offsetHeight + 2;
+					if (root.offsetWidth !== w2 || root.offsetHeight !== h2) {
+						root.style.width = w2 + "px";
+						root.style.height = h2 + "px";
+					}
+				}).observe(panel);
 			} catch (_e) {}
+			var pinned = false;
+			pinned = qtState.pinned;
 			var applyPin = function() {
 				pinBtn.style.color = pinned ? "var(--dsw-alias-interactive-accent, #4d9fff)" : "";
 				pinBtn.style.opacity = pinned ? "1" : "";
@@ -500,11 +750,11 @@ window.__ModuleLoader__.load({
 			setCollapsed(pinned ? false : true);
 			applyPin();
 			applyLocale();
+			fetchUserAdapters();
 			pinBtn.addEventListener("click", function() {
 				pinned = !pinned;
-				try {
-					localStorage.setItem(TOOLBAR_PINNED_KEY, pinned ? "1" : "0");
-				} catch (_e) {}
+				qtState.pinned = pinned;
+				saveState();
 				applyPin();
 				setCollapsed(pinned ? false : true);
 			});
@@ -575,12 +825,11 @@ window.__ModuleLoader__.load({
 					ballY = Math.max(4, Math.min(Math.round(sp.by), vh - BALL_SIZE - 4));
 					ball.style.left = ballX + "px";
 					ball.style.top = ballY + "px";
-					try {
-						localStorage.setItem(TOOLBAR_POS_KEY, JSON.stringify({
-							x: ballX,
-							y: ballY
-						}));
-					} catch (_e) {}
+					qtState.pos = {
+						x: ballX,
+						y: ballY
+					};
+					saveState();
 				};
 				document.addEventListener("mousemove", onMove);
 				document.addEventListener("mouseup", onUp);
@@ -598,16 +847,25 @@ window.__ModuleLoader__.load({
 			tbStyle.setAttribute("data-dsh-quick-toolbar-toolbar", "");
 			tbStyle.textContent = TOOLBAR_CSS;
 			document.head.appendChild(tbStyle);
-			createToolbar();
-			window.addEventListener("load", function() {
-				if (win.__SSID_SHELL__ !== true) return;
+			loadState(function() {
+				if (win.__SSID_SHELL__ === true && !qtState.shellVisible) return;
+				createToolbar();
+			});
+			var hideIfShell = function() {
+				if (win.__SSID_SHELL__ !== true) return false;
+				if (qtState.shellVisible) return false;
 				var tb = document.getElementById(TOOLBAR_ID);
 				if (tb !== null) tb.remove();
 				var tbBall = document.getElementById(TOOLBAR_ID + "-ball");
 				if (tbBall !== null) tbBall.remove();
-				var st = document.querySelector("style[data-dsh-quick-toolbar]");
-				if (st !== null) st.textContent = BASE_CSS + "\n" + SHELL_CSS.join("\n");
-			});
+				return true;
+			};
+			window.addEventListener("load", hideIfShell);
+			var shellTries = 0;
+			var shellTimer = setInterval(function() {
+				shellTries++;
+				if (hideIfShell() || shellTries >= 5) clearInterval(shellTimer);
+			}, 1500);
 			mountSmHeaderButton();
 			new MutationObserver(function() {
 				applyLocale();
@@ -621,6 +879,19 @@ window.__ModuleLoader__.load({
 			});
 			window.addEventListener("ssid:titlebar", function(event) {
 				var detail = event !== null && typeof event === "object" ? event.detail : void 0;
+				if (detail === "quick-toolbar-toggle") {
+					var nextOn = !qtState.shellVisible;
+					qtState.shellVisible = nextOn;
+					saveState();
+					if (nextOn) createToolbar();
+					else {
+						var tbEl = document.getElementById(TOOLBAR_ID);
+						if (tbEl !== null) tbEl.remove();
+						var tbBallEl = document.getElementById(TOOLBAR_ID + "-ball");
+						if (tbBallEl !== null) tbBallEl.remove();
+					}
+					return;
+				}
 				if (detail === "session-manager") {
 					clickSmOpenButton();
 					return;

package/lib/index.js

@@ -1,6 +1,6 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { readFileSync } from "node:fs";
+import { readFileSync, renameSync, writeFileSync } from "node:fs";
 import { z } from "zod";
 //#region src/schema.ts
 /**
@@ -114,10 +114,89 @@ const adaptersRouteDefinition = {
 		}
 	}
 };
+const STATE_PATH = join(process.env.DSH_HOME ?? join(homedir(), ".dsh"), "quick-toolbar-state.json");
+const STATE_ROUTE = "/quick-toolbar/api/state";
+/** 默认状态（文件缺失/字段缺失时取默认，宽松向下兼容）。 */
+function defaultState() {
+	return {
+		pos: null,
+		collapsed: true,
+		pinned: false,
+		shellVisible: false
+	};
+}
+/** 归一化（防御非法文件：字段级回退默认，不因一条坏字段全丢）。 */
+function normalizeState(raw) {
+	const d = defaultState();
+	const s = raw !== null && typeof raw === "object" ? raw : {};
+	const pos = s.pos;
+	if (pos !== null && pos !== void 0 && typeof pos === "object" && pos !== null) {
+		const p = pos;
+		if (typeof p.x === "number" && typeof p.y === "number") d.pos = {
+			x: p.x,
+			y: p.y
+		};
+	}
+	if (typeof s.collapsed === "boolean") d.collapsed = s.collapsed;
+	if (typeof s.pinned === "boolean") d.pinned = s.pinned;
+	if (typeof s.shellVisible === "boolean") d.shellVisible = s.shellVisible;
+	return d;
+}
+/** 读状态文件（缺失/非法 → 默认；不抛）。 */
+function readStateFile() {
+	try {
+		return normalizeState(JSON.parse(readFileSync(STATE_PATH, "utf8")));
+	} catch {
+		return defaultState();
+	}
+}
+/** 原子写状态文件（tmp + rename，防中断半写）。 */
+function writeStateFile(state) {
+	const tmp = STATE_PATH + ".tmp";
+	writeFileSync(tmp, JSON.stringify(state));
+	renameSync(tmp, STATE_PATH);
+}
+const stateRouteDefinition = {
+	kind: "exact",
+	path: STATE_ROUTE,
+	handler: async (req, res) => {
+		if (req.method === "GET") {
+			sendJson(res, 200, {
+				ok: true,
+				state: readStateFile()
+			});
+			return;
+		}
+		if (req.method === "POST") {
+			let raw = "";
+			req.on("data", (chunk) => {
+				raw += chunk;
+			});
+			await new Promise((resolve) => req.on("end", () => {
+				resolve();
+			}));
+			try {
+				writeStateFile(normalizeState(JSON.parse(raw)));
+				sendJson(res, 200, { ok: true });
+			} catch {
+				sendJson(res, 200, {
+					ok: false,
+					error: "invalid-state"
+				});
+			}
+			return;
+		}
+		sendJson(res, 405, {
+			ok: false,
+			error: "method-not-allowed"
+		});
+	}
+};
 function apply(ctx) {
 	ctx.inject(["webServer"], ((wsCtx) => {
 		wsCtx.webServer.register(adaptersRouteDefinition);
+		wsCtx.webServer.register(stateRouteDefinition);
 	}));
 }
 //#endregion
-export { apply, name };
+export { apply, defaultState, name, normalizeState, readStateFile, writeStateFile };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@max-null/dsh-quick-toolbar",
-  "version": "0.1.0",
+  "version": "0.3.1",
   "description": "插件按钮聚合器：聚合三方插件散乱按钮（插件中心/侧栏/底栏/会话管理…）到统一入口——SSiD 标题栏 / web 悬浮球（iOS 小白点式）；适配器驱动，内置适配集；LLM 可生成适配（驻场工程师模式）",
   "type": "module",
   "main": "lib/index.js",