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

package/README.md

@@ -4,17 +4,47 @@
 
 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 按模板生成适配**（驻场工程师模式）——不要求三方插件配合。
+面向 [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.
+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). **Extensibility is the point**: this plugin is a *carrier* (protocol + engine + registry) — **everyone can register the buttons of any plugin in their own environment** (LLM one-click registration / right-click deregistration; no plugin source touched, no code written, no cooperation required from third-party plugins).
+
+## 理念：载体 + 驻场 LLM——动态聚合，零代码增删
+
+```
+你的环境 = 插件 A · 插件 B · 插件 C（各自散落的按钮）
+        └── 聚合到本工具栏（一个入口）
+                     ▲
+   注册（➕ 一键，LLM 探查+数据注册）/ 注销（右键删除=移除注册）
+```
+
+- **插件 = 载体**：本插件只提供注册协议（字段/校验/引擎行为）与渲染执行器；不内置任何场景适配——场景无限，没有"完美脚本"能预适配所有环境。
+- **适配 = 驻场 LLM 域**：点击 ➕ 发起「添加按钮」会话，环境里的 LLM 自主探查（浏览器/代码能力验证选择器）→ 生成纯数据注册（一条 JSON）。**添加 = 注册制**（不动插件原代码）。
+- **删除 = 注销制**：右键按钮 → 滑出「删除」→ 移除注册、原按钮恢复显示，环境回到未注册原状（零代码残留、零回滚成本）。
+- **人人可用**：你不需要会写插件——告诉 LLM"把某个按钮加进来"，它替你完成全部探查与注册；任何插件的按钮都能聚合，无论是官方的、社区的还是你自己的。
 
 ## 截图
 
-| SSiD 标题栏（壳） | web 悬浮球 | 聚合面板 |
-|---|---|---|
-| ![SSiD 标题栏](docs/shots/ssid-titlebar.png) | ![web 悬浮球](docs/shots/web-float.png) | ![聚合面板](docs/shots/web-panel.png) |
+### 动态聚合（GIF 实录）
+
+| 聚合面板（内置 + LLM 注册按钮 + ➕） | 右键滑动删除（注销制） |
+|---|---|
+| ![聚合面板](docs/shots/panel-aggregated.gif) | ![滑动删除](docs/shots/panel-slide-delete.gif) |
+
+| 二次点击关闭（引擎探测语义） | ➕ LLM 注册会话（反问 → 探查 → 注册） |
+|---|---|
+| ![二次点击关闭](docs/shots/second-click-open.gif) | ![LLM 注册会话](docs/shots/llm-register-session.gif) |
+
+### 一图两景：聚合面板 × LLM 反问（真实环境）
+
+![面板与 LLM 反问](docs/shots/panel-with-llm.png)
+
+> Remote 为用户 LLM 现场注册的按钮（ds-harness-remote 入口）——演示「任何插件按钮都能聚合进统一入口」；右侧面板同时展示 LLM 按任务书先反问目标、再探查注册的完整流程。
 
-> 截图环境：SSiD 0.1.15 壳（标题栏）与 DSH master web（悬浮球/面板）；聚合面板为 web 右下角悬浮球 morph 展开态。
+| SSiD 标题栏（壳） | web 悬浮球 |
+|---|---|
+| ![SSiD 标题栏](docs/shots/ssid-titlebar.png) | ![web 悬浮球](docs/shots/web-float.png) |
+
+> 截图环境：SSiD 壳（标题栏/聚合面板）与 DSH web（悬浮球）；Remote 为用户 LLM 现场注册的按钮（ds-harness-remote 入口），演示「统一入口聚合散落按钮」。
 
 ## 安装
 
@@ -28,16 +58,47 @@ dsh plugin --profile web add @max-null/dsh-quick-toolbar
 - **聚合按钮**：标题栏/悬浮球点开面板 → 一键触发各插件功能（再点关闭——会话管理探测弹窗关闭按钮；设置面板语义锚点打开/再点关闭）。
 - **内置入口**：悬浮球含「设置」（官方设置面板：引擎按语义锚点定位 footer 触发器，双 locale；再点关闭——DSH trigger 原生只开不关）。
 - **壳环境（SSiD）**：悬浮球默认隐藏（标题栏接管入口）；标题栏「悬浮球」开关按钮（圆圈+圆点图标）可开启。
-- **用户适配器**：复制 `adapters.prompt.md` + 环境描述 → 让 LLM 生成 `{ "adapters": [...] }` → 写入 `~/.dsh/quick-toolbar-adapters.json` → 刷新页面生效（host API 校验，非法条目丢弃并报明细）。
+- **用户适配器**：点面板 ➕ 或复制 `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 规则）——内核动态端口不再丢状态。
 
+## 教程：迁移 / 新增一个按钮（开一个会话，让 LLM 来做）
+
+> **核心观念：迁移按钮不是自己写配置，而是开一个会话，把任务交给环境里的 LLM。**
+> 本插件是「载体」，不内置扫描器、不预设所有场景——**适配由你环境里的 LLM 现场完成**
+> （驻场工程师模式）；你只需要告诉它要哪个按钮。此设计不是社区主流，但它承诺：
+> 环境里任何按钮都能被聚合，无需第三方插件配合、无需等待本插件适配。
+
+**推荐路径（三步，约 1 分钟）：**
+
+1. **点击工具栏面板里的 ➕「添加按钮」**——插件创建「添加按钮」会话并把注册任务书注入其中（自动执行，无需你打字；服务不可用时退化为输入框草稿，按 Enter 发送）。若环境支持复制，也可直接复制 `adapters.prompt.md` 到任意会话。
+2. **回答 LLM 的反问**——它会先问清楚目标：*迁移*（哪个按钮？在哪个面板/插件里？）
+   还是*新增*（图标/文字/点击后发生什么？）。回答后 LLM 才会动手——它不会猜。
+3. **LLM 自主探查并注册**——它用自己的浏览器/代码能力找到目标、验证选择器，
+   把最小注册 `{ "adapters": [{ "id": "...", "button": "..." }] }` 写入
+   `~/.dsh/quick-toolbar-adapters.json`。你**刷新页面**，按钮即出现在工具栏。
+   若未出现，告诉 LLM，它会修正重试。
+
+**手动方式（高级用户）**：跳过会话，直接编辑 `~/.dsh/quick-toolbar-adapters.json`
+（同 id 覆盖既有注册；非法条目被 host 校验丢弃并报明细——详见 `adapters.prompt.md` 字段表）。
+
+**说明**：注册结果是**纯数据**（图标/文字/点击由载体派生或按声明执行），不是代码——
+LLM 注册完就无需在场；那份 JSON 可导出、可备份、可随环境迁移。
+
+**删除按钮**：在工具栏面板里**右键点击该按钮 → 「删除此按钮」**（仅用户注册的按钮；
+内置按钮不可删）。删除后原按钮恢复显示、配置写回 `~/.dsh/quick-toolbar-adapters.json`
+（也可直接手动编辑该 JSON）。**SSiD 壳环境路径**：标题栏「悬浮球」开关（圆圈+圆点）→
+球显示 → 点球展开面板 → 右键按钮 → 滑出「删除」。
+
+> **English quick start** — *Moving a button in is NOT a settings task: open a session and let the on-site LLM do it.* Click the **➕ "Add button"** in the toolbar panel; the plugin creates an "Add button" session and injects the registration brief into it (auto-runs; falls back to a composer draft if the session service is unavailable). The LLM will first ask you which button to migrate / what new button you want, then it explores the environment, verifies the selector, writes `{ "adapters": [...] }` to `~/.dsh/quick-toolbar-adapters.json`, and you refresh the page. Registration results are plain data — the carrier derives icon/text/click from the original button, and the LLM is no longer needed afterwards.
+
 ## 架构
 
 - `src/adapters.ts`：适配器 schema + 内置适配器集（黄金示例）
 - `src/behaviors.ts`：行为库（click / toggle-panel / dispatch-event / open-settings（语义锚点+再点关闭）/ command（composer 注入）——全部实现，v2 M1）
 - `src/engine.ts`：执行器（防御执行）
 - `src/schema.ts`：用户配置 zod 校验（LLM 产物防线）
+- `src/register-brief.ts`：➕ 按钮注入的注册任务书（先反问 → 探查 → 最小注册，与协议字段同步，锚点测试防漂移）
 - `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

@@ -20,7 +20,10 @@ const BUILTIN_ADAPTERS = [
 	{
 		id: "dsh-better-sidebar.sidebar",
 		button: "[class*=\"toggleCluster\"]",
-		icon: { source: "from-button" },
+		icon: {
+			source: "custom",
+			value: "sidebar"
+		},
 		label: "侧栏",
 		act: {
 			kind: "dispatch-event",
@@ -32,7 +35,10 @@ const BUILTIN_ADAPTERS = [
 	{
 		id: "dsh-better-sidebar.bottom",
 		button: "[class*=\"toggleCluster\"]",
-		icon: { source: "from-button" },
+		icon: {
+			source: "custom",
+			value: "bottom"
+		},
 		label: "底栏",
 		act: {
 			kind: "dispatch-event",
@@ -75,18 +81,21 @@ function actClick(target) {
 	return true;
 }
 /**
-* 面板开/关：再点关闭（探测 close 选择器内的「关闭」按钮——原生无
-* 再点关闭的插件（如 dsh-session-manager 0.4.x）走此行为。
+* 面板开/关（v0.8.0 探测语义——替代已废弃的面板容器协议 findPanel/#id-panel，
+* 该协议从未有环境实现：client 半 findPanel 恒 null，内置项走 toolbarAction 桥接，
+* 用户适配器因此死路——「添加按钮2」会话 LLM 源码实测发现）：
+* close 目标**可见** = 弹窗开着 → 点它关闭；**不可见/不存在** = 弹窗关着 → 点原按钮打开。
+* @param openTarget 原按钮（弹窗关着时点击它打开）
+* @param closeTarget 弹窗内关闭按钮（LLM 探测、随弹窗显隐）
+* @param probeVisible 可见性探测（DOM 环境 = rect/computedStyle；测试可 stub）
 */
-function actTogglePanel(panel, closeTarget) {
-	if (panel.isOpen()) {
-		if (closeTarget !== null && closeTarget !== void 0 && closeTarget.disabled !== true) {
-			closeTarget.click();
-			return true;
-		}
-		return false;
+function actTogglePanel(openTarget, closeTarget, probeVisible) {
+	if (closeTarget !== null && closeTarget !== void 0 && closeTarget.disabled !== true && probeVisible(closeTarget)) {
+		closeTarget.click();
+		return true;
 	}
-	panel.open();
+	if (openTarget === null || openTarget === void 0 || openTarget.disabled === true) return false;
+	openTarget.click();
 	return true;
 }
 /** 官方设置触发器锚点链（v2 调研点① 结论：DSH 面板 open 状态由 shell 私有，
@@ -155,22 +164,60 @@ function actCommand(env, name) {
 * 行为库保持窄接口（可测）；本层唯一负责 DOM 绑定（browser 环境，
 * 不在 node:test 的范围里——DOM 交互留给 L2 环境验证）。
 */
-/** 选择器转义（不依赖 CSS 全局——node:test 无 DOM/CSS，行为库测试可用） */
-function cssEscape(name) {
-	return name.replace(/[^a-zA-Z0-9_-]/g, (c) => `\\${c}`);
+/** 遮罩关闭候选链（第二次点击的 mask 通道——DSH 弹窗多为遮罩交互） */
+const MASK_CHAINS = [
+	"[class$=\"_backdrop\"]",
+	"[class*=\"backdrop\"]",
+	"[class$=\"_mask\"]",
+	"[class*=\"modal-mask\"]"
+];
+/**
+* 归一 secondClick 通道（v0.8.0「二次点击事件」）：secondClick 优先，close 旧字段
+* 兼容（字符串简写 = 点击关闭按钮）。
+*/
+function closeTargetOf(act, env) {
+	const spec = act.secondClick ?? act.close ?? null;
+	if (spec === null) return null;
+	if (typeof spec === "string") return env.find(spec);
+	if (spec.kind === "mask") {
+		const probe = env.isVisible ?? defaultIsVisible;
+		for (let i = 0; i < MASK_CHAINS.length; i++) {
+			const el = env.find(MASK_CHAINS[i]);
+			if (el !== null && probe(el)) return el;
+		}
+		return null;
+	}
+	return env.find(spec.selector);
 }
-/** 按内置定义执行一条适配器（防御执行：定位失败/禁用 → false，绝不误伤） */
+/** 缺省可见性探测（DOM：offset 尺寸优先，computedStyle 兜底） */
+function defaultIsVisible(el) {
+	if (el === null || typeof el !== "object") return false;
+	const node = el;
+	if (typeof node.offsetWidth === "number") {
+		if (node.offsetWidth > 0 || node.offsetHeight > 0) return true;
+		return false;
+	}
+	if (typeof getComputedStyle === "function") try {
+		const style = getComputedStyle(node);
+		return style.display !== "none" && style.visibility !== "hidden";
+	} catch {
+		return false;
+	}
+	return false;
+}
+/** 按内置定义执行一条适配器（防御执行：定位失败/禁用 → false，绝不误伤）
+*  「换位置」缺省：act 未填 → click（点击原按钮）。 */
 function runAdapter(adapter, env) {
-	switch (adapter.act.kind) {
+	const act = adapter.act ?? { kind: "click" };
+	switch (act.kind) {
 		case "click": return actClick(env.find(adapter.button));
-		case "dispatch-event": return env.dispatch(adapter.act.event, adapter.act.detail);
+		case "dispatch-event": return env.dispatch(act.event, 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;
+			const closeEl = closeTargetOf(act, env);
+			return actTogglePanel(env.find(adapter.button), closeEl, env.isVisible ?? defaultIsVisible);
 		}
 		case "open-settings":
-			if (adapter.act.path !== void 0) console.warn(`quick-toolbar: open-settings path '${adapter.act.path}' 暂不支持（v2 深链待入）`);
+			if (act.path !== void 0) console.warn(`quick-toolbar: open-settings path '${act.path}' 暂不支持（v2 深链待入）`);
 			return actOpenSettings({
 				find: env.find,
 				...env.findByText !== void 0 ? { findByText: env.findByText } : {}
@@ -180,10 +227,116 @@ function runAdapter(adapter, env) {
 				console.warn("quick-toolbar: command 环境无 runCommand 通道（旧版 DSH/未注入）");
 				return false;
 			}
-			return actCommand({ execute: env.runCommand }, adapter.act.name);
+			return actCommand({ execute: env.runCommand }, act.name);
 	}
 }
 //#endregion
+//#region src/register-brief.ts
+/**
+* 注册任务书（v0.5.1）——「➕ 按钮」注入的 prompt 文本。
+*
+* 设计（V2-9 载体哲学 + 安装教程闭环）：
+* 用户点击工具栏「➕」→ 首选经 sessions/workspaces/uiWorkspace 服务创建
+* 「添加按钮」会话并把本任务书以 queue 模式注入（自动执行）——同款机制 =
+* 插件中心 LLM 更新（ensureLlmUpdateSession，2026-08-30 实证修正：早期
+* inject=[] 令 apply 只见 {fiber}，「无会话通道」判断是错结论）；
+* 服务缺失/失败 → 降级为当前 composer 草稿注入（用户 Enter 发送）。
+* 任务书必须自包含（环境 LLM 不一定能访问本仓库文件）——协议要点全部内嵌。
+*
+* 同步纪律：字段与 src/adapters.ts / src/schema.ts 保持一致；
+* 漂移即教程失效（tests/register-brief.spec.ts 有锚点断言防退化）。
+*/
+const REGISTER_BRIEF = `# 任务：为「工具栏插件」迁移 / 新增一个按钮
+
+你是 DSH 环境的驻场工程师。用户想把某个按钮**迁移**到工具栏
+（@max-null/dsh-quick-toolbar：SSiD 标题栏按钮组 / web 悬浮球·聚合面板），
+或者**新增**一个自定义按钮。工具栏是「载体」——你注册的是**数据**
+（图标/文字/点击由载体从原按钮派生或按声明执行），不是代码。
+
+## 第一步（现在就要做）：先反问用户，不要猜
+
+用一句话向用户确认目标，等回答后再动手：
+
+- **迁移**：要迁移的是哪个按钮？它在哪个面板/页面/插件里，长什么样？
+- **新增**：要新增什么样的按钮？图标 / 文字 / 点击后应发生什么？
+
+## 第二步（确认目标后）：自主探查并验证
+
+- **探查通道**：经 ➕ 注入的本任务书开头附有「探查通道」段（当前 DSH 页面完整
+  URL，含认证 token）——用浏览器直接打开它即可访问用户环境；**不要裸访问
+  内核端口（会 401）**。手工粘贴本文件时若无附带 URL，向用户要页面地址。
+- 用你的浏览器 / 代码能力找到目标按钮元素（DOM 查询、截图、读源码都行），
+  **自己验证 CSS 选择器确实可用**——不要凭猜测写选择器，不要依赖用户给 DOM 快照。
+- 提示：场景无限，没有"完美脚本"能预适配所有环境——探查正是你在场的原因，
+  载体不内置扫描器，这个活由你做。
+
+## 第三步：注册（数据，不是代码）
+
+**最小注册（迁移——推荐起点）**：被整合的按钮自带图标/文字/点击事件，聚合就是
+"换个位置"，两条就够了：
+
+\`\`\`json
+{ "id": "dsh-some-plugin", "button": ".some-btn" }
+\`\`\`
+
+\`\`\`json
+{ "adapters": [ { "id": "dsh-some-plugin", "button": ".some-btn" } ] }
+\`\`\`
+
+- 图标 = 扣取原按钮视觉（svg/img/背景）；文字 = 扣取原按钮文案；
+  点击 = 点击原按钮（act 缺省 \`click\`）。
+- **原按钮自动隐藏**（换位置 = 双入口无意义；缺省隐藏，显式 \`"hide": false\` 才保留——
+  若原按钮被隐藏后其弹窗定位错位，改用 \`hide: false\`）。
+- **自定义按钮**（无原按钮可扣）才需要显式字段：
+  \`\`\`json
+  { "id": "my-btn", "button": "#app-shell", "icon": { "source": "custom", "value": "emoji 或 svg" },
+    "label": "文字", "act": { "kind": "click" }, "hide": false }
+  \`\`\`
+
+**行为枚举（只能选这些，禁止写代码）**：
+
+| kind | 语义 |
+|---|---|
+| \`click\` | 直接点击 |
+| \`toggle-panel\` | **二次点击事件**：弹窗开 → 按 \`secondClick\` 通道关闭；关 → 点原按钮打开。\`secondClick\` 推荐 \`{ "kind": "mask" }\`（点遮罩关闭——DSH 弹窗通用交互）；或点关闭按钮 \`{ "kind": "click", "selector": "验证过的关闭按钮" }\`（也可直接写选择器字符串） |
+| \`dispatch-event\` | 派发 CustomEvent（\`event\`、\`detail?\`） |
+| \`open-settings\` | 打开设置面板（引擎语义锚点定位，再点关闭） |
+| \`command\` | 向输入框注入斜杠命令草稿（\`name\`，不含 \`/\`） |
+
+## 探测闭环（注册前必须完成——别让用户点出"开得关不掉"）
+
+用你的浏览器能力实测原按钮行为，按结果选 act：
+
+1. 点击一次：开的是**弹窗/面板**还是普通页面？
+2. **用 JS \`.click()\` 验证 toggle 性**（DOM 事件触发、穿透遮罩）——Playwright 物理点击
+   可能被弹窗遮罩（backdrop）**拦截而误判**"不能再点关闭"（remote 案例实测：物理点不到
+   ≠ 不能 toggle，JS 点击下原按钮可能是天然开关）：
+   - \`document.querySelector(原按钮选择器).click()\` 连点两次：开→关 → **天然 toggle** → \`click\` 就够；
+   - 仍开→关不掉 → act 用 \`toggle-panel\` 并探测关闭通道（下一步）。
+3. \`toggle-panel\` 关闭通道：**优先 \`secondClick: { "kind": "mask" }\`（点遮罩）——
+   但必须探测验证遮罩点击真的会关闭**（remote 弹窗遮罩实测不响应）；不行换
+   \`{ "kind": "click", "selector": "弹窗内唯一×按钮选择器" }\`。
+4. **\`close\` 旧字段兼容**：\`"close": "关闭按钮选择器"\`（字符串简写，v0.8.0 前写法）
+   与 secondClick 等效，schema 仍接受——旧任务书/注册可读，不必改写。
+5. 记录原按钮是否会在意「隐藏」（见第三步 hide 说明）。
+
+## 第四步：写入配置，让用户刷新
+
+把完整 JSON（含 \`adapters\` 数组）写入：
+\`~/.dsh/quick-toolbar-adapters.json\`（DSH 环境即 \`$DSH_HOME/quick-toolbar-adapters.json\`；
+重复 \`id\` = 覆盖既有注册）。写入后告知用户**刷新页面**，按钮即出现在工具栏；
+若未出现，修正选择器后重试。协议全文见仓库 \`adapters.prompt.md\`（如可访问请先读一遍）。
+
+## 注册后验证清单（刷新后逐项确认）
+
+① 按钮已出现在工具栏（图标/文字来自原按钮） ② 点击可开启 ③ 再点能关闭
+（toggle-panel 场景） ④ 原按钮已隐藏（或按 hide:false 保留）。任一项不满足 → 修正后重试。
+
+## 纪律
+
+- 只写数据，不提供函数/代码（schema 拒绝一切非枚举行为）。
+- 一次只注册 1–2 个按钮，验证后再扩展；定位失败无害（引擎静默跳过，绝不误点）。`;
+//#endregion
 //#region src/client.ts
 /**
 * @max-null/dsh-quick-toolbar — browser half.
@@ -292,6 +445,8 @@ window.__ModuleLoader__.load({
 			"tb.sidebar": ["侧栏", "Sidebar"],
 			"tb.bottom": ["底栏", "Bottom panel"],
 			"tb.sessions": ["会话管理", "Sessions"],
+			"tb.add": ["添加按钮", "Add button"],
+			"tb.addAria": ["添加/迁移按钮（让 LLM 来注册）", "Add / migrate a button (let the LLM register it)"],
 			"sm.open": ["会话管理", "Sessions"],
 			"sm.openTitle": ["打开会话管理面板", "Open session manager"]
 		};
@@ -438,19 +593,28 @@ window.__ModuleLoader__.load({
 			"#ssid-toolbar .ssid-tb-pin svg{width:15px;height:15px}",
 			"#ssid-toolbar .ssid-tb-btn{border:0;background:transparent;color:var(--dsw-alias-label-primary,#d8e0ea);border-radius:8px;height:30px;display:flex;align-items:center;gap:8px;padding:0 10px;font-size:12px;line-height:18px;cursor:pointer;white-space:nowrap;text-align:left}",
 			"#ssid-toolbar .ssid-tb-btn:hover{background:var(--dsw-alias-interactive-bg-hover,rgba(128,148,168,.14))}",
-			"#ssid-toolbar .ssid-tb-btn svg{flex:none;width:15px;height:15px;color:var(--dsw-alias-label-secondary,#98a2b3)}"
+			"#ssid-toolbar .ssid-tb-btn svg{flex:none;width:15px;height:15px;color:var(--dsw-alias-label-secondary,#98a2b3)}",
+			"#ssid-toolbar .ssid-tb-add{border:1px dashed var(--dsw-alias-border-strong,rgba(128,148,168,.45));background:transparent;color:var(--dsw-alias-label-tertiary,#7b8494);border-radius:8px;height:30px;display:flex;align-items:center;gap:8px;padding:0 10px;font-size:12px;line-height:18px;cursor:pointer;white-space:nowrap;text-align:left;margin-top:2px;transition:color .15s,border-color .15s,background .15s}",
+			"#ssid-toolbar .ssid-tb-add:hover{color:var(--dsw-alias-label-primary,#d8e0ea);border-color:var(--dsw-alias-label-secondary,#98a2b3);background:var(--dsw-alias-interactive-bg-hover,rgba(128,148,168,.14))}",
+			"#ssid-toolbar .ssid-tb-add svg{flex:none;width:15px;height:15px;color:var(--dsw-alias-label-secondary,#98a2b3)}",
+			".ssid-tb-row{position:relative;overflow:hidden;border-radius:8px}",
+			".ssid-tb-slide{display:flex;position:relative;width:100%;transition:transform .2s ease}",
+			".ssid-tb-row .ssid-tb-btn{flex:1 1 auto;min-width:0;position:relative;z-index:1;box-sizing:border-box;background:transparent}",
+			".ssid-tb-row.ssid-tb-row-open .ssid-tb-slide{transform:translateX(-56px)}",
+			".ssid-tb-del{position:absolute;right:-56px;top:0;bottom:0;width:56px;border:0;background:var(--dsw-alias-state-error-primary,#e5484d);color:#fff;font-size:12px;cursor:pointer;font-weight:500;border-radius:8px 0 0 8px}"
 		].join("\n");
 		function toolbarIcon(name) {
 			var ICONS = {
 				grid: "<svg viewBox=\"0 0 16 16\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.5\"><rect x=\"2\" y=\"2\" width=\"5\" height=\"5\" rx=\"1\"/><rect x=\"9\" y=\"2\" width=\"5\" height=\"5\" rx=\"1\"/><rect x=\"2\" y=\"9\" width=\"5\" height=\"5\" rx=\"1\"/><rect x=\"9\" y=\"9\" width=\"5\" height=\"5\" rx=\"1\"/></svg>",
 				plugin: "<svg viewBox=\"0 0 16 16\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.5\"><rect x=\"2\" y=\"2\" width=\"5\" height=\"5\" rx=\"1\"/><rect x=\"9\" y=\"2\" width=\"5\" height=\"5\" rx=\"1\"/><rect x=\"2\" y=\"9\" width=\"5\" height=\"5\" rx=\"1\"/><rect x=\"9\" y=\"9\" width=\"5\" height=\"5\" rx=\"1\"/></svg>",
-				sidebar: "<svg viewBox=\"0 0 16 16\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.5\"><rect x=\"2\" y=\"2\" width=\"12\" height=\"12\" rx=\"1\"/><path d=\"M10 2v12\"/></svg>",
-				bottom: "<svg viewBox=\"0 0 16 16\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.5\"><rect x=\"2\" y=\"2\" width=\"12\" height=\"12\" rx=\"1\"/><path d=\"M2 10h12\"/></svg>",
+				sidebar: "<svg viewBox=\"0 0 16 16\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\"><rect x=\"1.5\" y=\"2\" width=\"13\" height=\"12\" rx=\"2.5\" stroke=\"currentColor\" stroke-width=\"1.5\"/><rect x=\"10.5\" y=\"3.25\" width=\"2.75\" height=\"9.5\" rx=\"1\" fill=\"currentColor\" stroke=\"none\"/></svg>",
+				bottom: "<svg viewBox=\"0 0 16 16\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\"><rect x=\"1.5\" y=\"2\" width=\"13\" height=\"12\" rx=\"2.5\" stroke=\"currentColor\" stroke-width=\"1.5\"/><rect x=\"3.25\" y=\"10\" width=\"9.5\" height=\"2.75\" rx=\"1\" fill=\"currentColor\" stroke=\"none\"/></svg>",
 				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>",
-				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>"
+				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>",
+				add: "<svg viewBox=\"0 0 16 16\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.5\" stroke-linecap=\"round\"><path d=\"M8 3.5v9M3.5 8h9\"/></svg>"
 			};
 			return ICONS[name] || ICONS.grid;
 		}
@@ -459,8 +623,20 @@ window.__ModuleLoader__.load({
 				find: function(s) {
 					return document.querySelector(s);
 				},
-				findPanel: function(s) {
-					return null;
+				isVisible: function(el) {
+					if (el === null || typeof el !== "object") return false;
+					var node = el;
+					if (typeof node.getBoundingClientRect === "function") {
+						var r = node.getBoundingClientRect();
+						if (r.width > 0 || r.height > 0) return true;
+					}
+					if (typeof getComputedStyle === "function") try {
+						var s = getComputedStyle(node);
+						return s.display !== "none" && s.visibility !== "hidden";
+					} catch (_e) {
+						return false;
+					}
+					return false;
 				},
 				dispatch: function(event, detail) {
 					window.dispatchEvent(new CustomEvent(event, { detail }));
@@ -479,11 +655,10 @@ window.__ModuleLoader__.load({
 				}
 			};
 		};
-		function typeCommandIntoComposer(name) {
+		function injectComposerDraft(text) {
 			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);
@@ -496,14 +671,11 @@ window.__ModuleLoader__.load({
 				data: text
 			}));
 			el.focus();
-			el.dispatchEvent(new KeyboardEvent("keydown", {
-				key: "Enter",
-				code: "Enter",
-				bubbles: true,
-				cancelable: true
-			}));
 			return true;
 		}
+		function typeCommandIntoComposer(name) {
+			return injectComposerDraft("/" + name);
+		}
 		function toolbarAction(kind) {
 			if (kind === "plugin") {
 				closeSidePanelsBeforePluginCenter();
@@ -531,6 +703,7 @@ window.__ModuleLoader__.load({
 		function createToolbar() {
 			if (win.__SSID_SHELL__ === true && !qtState.shellVisible) return;
 			if (document.getElementById(TOOLBAR_ID) !== null) return;
+			var addBtn = null;
 			var root = document.createElement("div");
 			root.id = TOOLBAR_ID;
 			var panel = document.createElement("div");
@@ -554,13 +727,32 @@ window.__ModuleLoader__.load({
 				"dsh-session-manager": "sessions"
 			};
 			var adapterIconHtml = function(adapter, kind) {
-				if (adapter.icon.source === "custom") {
+				if (adapter.icon !== void 0 && adapter.icon.source === "custom") {
 					var value = adapter.icon.value;
 					if (value.indexOf("<") === 0) return value;
 					return toolbarIcon(value);
 				}
+				try {
+					var el = document.querySelector(adapter.button);
+					if (el !== null) {
+						var svg = el.querySelector("svg");
+						if (svg !== null) return svg.outerHTML;
+						var img = el.querySelector("img");
+						if (img !== null) return img.outerHTML;
+						var bg = getComputedStyle(el).backgroundImage;
+						if (bg !== null && bg !== "none") return "<span style=\"display:inline-block;width:15px;height:15px;background:" + bg + ";background-size:contain;background-repeat:no-repeat\"></span>";
+					}
+				} catch (_e) {}
 				return kind !== null ? toolbarIcon(kind) : toolbarIcon("grid");
 			};
+			var adapterLabel = function(adapter) {
+				if (adapter.label !== void 0 && adapter.label !== "") return adapter.label;
+				try {
+					var el = document.querySelector(adapter.button);
+					if (el !== null && (el.textContent || "").trim() !== "") return (el.textContent || "").trim().slice(0, 12);
+				} catch (_e) {}
+				return adapter.id;
+			};
 			var renderButton = function(adapter, kind) {
 				var b = document.createElement("button");
 				b.type = "button";
@@ -574,7 +766,7 @@ window.__ModuleLoader__.load({
 					trackLocale(b, "tb." + kind, "aria");
 					trackLocale(b, "tb." + kind, "title");
 				} else {
-					var label = adapter.label !== void 0 ? adapter.label : adapter.id;
+					var label = adapterLabel(adapter);
 					var textSpan = b.querySelector("span");
 					if (textSpan !== null) textSpan.textContent = label;
 					b.setAttribute("aria-label", label);
@@ -587,13 +779,91 @@ window.__ModuleLoader__.load({
 					}
 					runAdapter(adapter, toolbarEnv());
 				});
-				panel.appendChild(b);
+				if (addBtn !== null && addBtn.parentNode === panel) panel.insertBefore(b, addBtn);
+				else panel.appendChild(b);
+				if (adapter.hide !== false) try {
+					var origBtn = document.querySelector(adapter.button);
+					if (origBtn !== null) origBtn.style.display = "none";
+				} catch (_e) {}
+				return 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 slideCloseAll = function() {
+				var rows = panel.querySelectorAll(".ssid-tb-row.ssid-tb-row-open");
+				for (var ri = 0; ri < rows.length; ri++) rows[ri].classList.remove("ssid-tb-row-open");
+			};
+			document.addEventListener("mousedown", function(e) {
+				var t = e.target;
+				if (t === null) return;
+				if (!(t instanceof Element ? t.closest(".ssid-tb-row") !== null : false)) slideCloseAll();
+			});
+			function removeUserAdapter(ad) {
+				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;
+					var next = rows.filter(function(a) {
+						return a.id !== ad.id;
+					});
+					return fetch("/quick-toolbar/api/adapters", {
+						method: "POST",
+						headers: { "Content-Type": "application/json" },
+						body: JSON.stringify({ adapters: next })
+					}).then(function(r) {
+						return r.json();
+					}).then(function(res) {
+						if (res === null || typeof res !== "object" || res.ok !== true) return;
+						try {
+							var btn = panel.querySelector("[data-adapter-id=\"" + ad.id.replace(/"/g, "\\\"") + "\"]");
+							var row = btn !== null && typeof btn.closest === "function" ? btn.closest(".ssid-tb-row") : null;
+							if (row !== null && row.parentNode === panel) panel.removeChild(row);
+						} catch (_e) {}
+						try {
+							var orig = document.querySelector(ad.button);
+							if (orig !== null) orig.style.display = "";
+						} catch (_e2) {}
+					});
+				}).catch(function() {});
+			}
+			function wrapAdapterRow(btn, ad) {
+				var row = document.createElement("div");
+				row.className = "ssid-tb-row";
+				var slide = document.createElement("div");
+				slide.className = "ssid-tb-slide";
+				if (btn.parentNode !== null) btn.parentNode.removeChild(btn);
+				slide.appendChild(btn);
+				var delBtn = document.createElement("button");
+				delBtn.type = "button";
+				delBtn.className = "ssid-tb-del";
+				delBtn.textContent = "删除";
+				delBtn.addEventListener("click", function() {
+					row.classList.remove("ssid-tb-row-open");
+					setTimeout(function() {
+						removeUserAdapter(ad);
+					}, 220);
+				});
+				slide.appendChild(delBtn);
+				row.appendChild(slide);
+				panel.insertBefore(row, addBtn);
+				btn.setAttribute("data-user-adapter", "1");
+				row.addEventListener("contextmenu", function(e) {
+					e.preventDefault();
+					e.stopPropagation();
+					if (row.classList.contains("ssid-tb-row-open")) {
+						row.classList.remove("ssid-tb-row-open");
+						return;
+					}
+					slideCloseAll();
+					row.classList.add("ssid-tb-row-open");
+				});
+				return row;
+			}
 			var fetchUserAdapters = function() {
 				fetch("/quick-toolbar/api/adapters").then(function(r) {
 					return r.json();
@@ -607,12 +877,33 @@ window.__ModuleLoader__.load({
 						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);
+							var oldRow = old !== null && typeof old.closest === "function" ? old.closest(".ssid-tb-row") : null;
+							if (oldRow !== null && oldRow.parentNode === panel) panel.removeChild(oldRow);
+							else if (old !== null && old.parentNode === panel) panel.removeChild(old);
 						} catch (_e) {}
-						renderButton(user, userKind !== void 0 ? userKind : null);
+						wrapAdapterRow(renderButton(user, userKind !== void 0 ? userKind : null), user);
 					}
 				}).catch(function() {});
 			};
+			addBtn = document.createElement("button");
+			addBtn.type = "button";
+			addBtn.className = "ssid-tb-add";
+			addBtn.setAttribute("aria-label", "添加/迁移按钮");
+			addBtn.title = "添加按钮";
+			addBtn.innerHTML = toolbarIcon("add") + "<span></span>";
+			trackLocale(addBtn, "tb.addAria", "aria");
+			trackLocale(addBtn, "tb.add", "title");
+			var addSpan = addBtn.querySelector("span");
+			if (addSpan !== null) addSpan.textContent = "添加按钮";
+			trackLocale(addBtn, "tb.add", "text-span");
+			addBtn.addEventListener("click", function() {
+				ensureRegisterSession().then(function(ok) {
+					if (!ok) registerBriefWithSessionUrl().then(function(brief) {
+						injectComposerDraft(brief);
+					});
+				});
+			});
+			panel.appendChild(addBtn);
 			var ball = document.createElement("button");
 			ball.type = "button";
 			ball.id = TOOLBAR_ID + "-ball";
@@ -835,10 +1126,71 @@ window.__ModuleLoader__.load({
 				document.addEventListener("mouseup", onUp);
 			});
 		}
-		exports.inject = [];
+		exports.inject = [
+			"sessions",
+			"workspaces",
+			"uiWorkspace"
+		];
+		var sessionsSvc = null;
+		var workspacesSvc = null;
+		var uiWorkspaceSvc = null;
+		function buildRegisterBrief(url) {
+			return "## 探查通道（已为你的浏览器认证好）：\n- 用浏览器打开下面这个 URL 即可直达当前 DSH 页面（首次访问会换 cookie 并自动重定向到干净根路径；token 仅本会话使用，勿写入文件/回复）:\n" + url + "\n\n" + REGISTER_BRIEF;
+		}
+		function registerBriefWithSessionUrl() {
+			return fetch("/quick-toolbar/api/auth-url").then(function(r) {
+				return r.json();
+			}).then(function(d) {
+				return buildRegisterBrief(d !== null && typeof d === "object" && d.ok === true && typeof d.url === "string" ? d.url : "");
+			}).catch(function() {
+				return buildRegisterBrief("");
+			});
+		}
+		function ensureRegisterSession() {
+			var svc = sessionsSvc;
+			var wsvc = workspacesSvc;
+			var uws = uiWorkspaceSvc;
+			if (svc === null || wsvc === null || uws === null) return Promise.resolve(false);
+			if (typeof uws.connectWorkspace !== "function") return Promise.resolve(false);
+			var snapshot = wsvc.list !== void 0 && typeof wsvc.list.getSnapshot === "function" ? wsvc.list.getSnapshot() : void 0;
+			var items = snapshot !== void 0 && snapshot !== null && snapshot.items !== void 0 && snapshot.items !== null ? snapshot.items : [];
+			var wsId = items.length > 0 ? items[0].workspaceId : void 0;
+			if (wsId === void 0 || wsId === "") return Promise.resolve(false);
+			return uws.connectWorkspace(wsId).then(function(sid) {
+				if (typeof sid !== "string" || sid === "") return false;
+				var svc3 = svc;
+				if (svc3 === null || svc3 === void 0) return false;
+				var face = typeof svc3.binding === "function" ? svc3.binding(sid) : void 0;
+				var s = face !== void 0 && face !== null && face.session !== void 0 && face.session !== null ? face.session : void 0;
+				if (s === void 0 || s === null || typeof s.prompt !== "function") return false;
+				return registerBriefWithSessionUrl().then(function(brief) {
+					var sess2 = s;
+					if (sess2 === void 0 || sess2 === null || typeof sess2.prompt !== "function") return Promise.resolve({ ok: false });
+					return sess2.prompt([{
+						type: "text",
+						text: brief
+					}], "queue");
+				}).then(function(res) {
+					if (res === void 0 || res === null || res.ok !== true) return false;
+					var sess = s;
+					var svc2 = svc;
+					if (sess === void 0 || sess === null) return false;
+					if (svc2 === null || svc2 === void 0) return false;
+					if (typeof sess.rename === "function") sess.rename("添加按钮").catch(function() {});
+					if (typeof svc2.open === "function") svc2.open(sid);
+					return true;
+				});
+			}).catch(function() {
+				return false;
+			});
+		}
 		exports.apply = function(ctx) {
 			if (win.__dshQuickToolbarInstalled === true) return;
 			win.__dshQuickToolbarInstalled = true;
+			var svcCtx = ctx !== null && typeof ctx === "object" ? ctx : {};
+			sessionsSvc = svcCtx.sessions ?? null;
+			workspacesSvc = svcCtx.workspaces ?? null;
+			uiWorkspaceSvc = svcCtx.uiWorkspace ?? null;
 			var style = document.createElement("style");
 			style.setAttribute("data-dsh-quick-toolbar", "");
 			style.textContent = BASE_CSS + (SHELL_CSS.length > 0 && win.__SSID_SHELL__ === true ? "\n" + SHELL_CSS.join("\n") : "");

package/lib/index.js

@@ -16,12 +16,20 @@ const adapterSchema = z.object({
 	icon: z.discriminatedUnion("source", [z.object({ source: z.literal("from-button") }), z.object({
 		source: z.literal("custom"),
 		value: z.string().min(1)
-	})]),
+	})]).optional(),
 	label: z.string().optional(),
 	act: z.discriminatedUnion("kind", [
 		z.object({ kind: z.literal("click") }),
 		z.object({
 			kind: z.literal("toggle-panel"),
+			secondClick: z.union([
+				z.string().min(1),
+				z.object({ kind: z.literal("mask") }),
+				z.object({
+					kind: z.literal("click"),
+					selector: z.string().min(1)
+				})
+			]).optional(),
 			close: z.string().optional()
 		}),
 		z.object({
@@ -37,7 +45,7 @@ const adapterSchema = z.object({
 			kind: z.literal("command"),
 			name: z.string()
 		})
-	]),
+	]).optional(),
 	hide: z.boolean().optional(),
 	enabled: z.boolean().optional()
 });
@@ -85,33 +93,66 @@ const adaptersRouteDefinition = {
 	kind: "exact",
 	path: ROUTE_PATH,
 	handler: async (req, res) => {
-		if (req.method !== "GET") {
-			sendJson(res, 405, {
-				ok: false,
-				error: "method-not-allowed"
-			});
+		if (req.method === "GET") {
+			try {
+				const parsed = parseUserAdapters(readFileSync(ADAPTERS_PATH, "utf8"));
+				if (!parsed.ok) {
+					sendJson(res, 200, {
+						ok: false,
+						error: "invalid-schema",
+						detail: parsed.issues
+					});
+					return;
+				}
+				sendJson(res, 200, {
+					ok: true,
+					value: parsed.value
+				});
+			} catch {
+				sendJson(res, 200, {
+					ok: true,
+					value: { adapters: [] }
+				});
+			}
 			return;
 		}
-		try {
-			const parsed = parseUserAdapters(readFileSync(ADAPTERS_PATH, "utf8"));
-			if (!parsed.ok) {
+		if (req.method === "POST") {
+			let raw = "";
+			req.on?.("data", (chunk) => {
+				raw += chunk;
+			});
+			await new Promise((resolve) => req.on?.("end", () => {
+				resolve();
+			}));
+			try {
+				const parsed = parseUserAdapters(raw);
+				if (!parsed.ok) {
+					sendJson(res, 200, {
+						ok: false,
+						error: "invalid-schema",
+						detail: parsed.issues
+					});
+					return;
+				}
+				const tmp = ADAPTERS_PATH + ".tmp";
+				writeFileSync(tmp, raw, "utf8");
+				renameSync(tmp, ADAPTERS_PATH);
+				sendJson(res, 200, {
+					ok: true,
+					value: parsed.value
+				});
+			} catch {
 				sendJson(res, 200, {
 					ok: false,
-					error: "invalid-schema",
-					detail: parsed.issues
+					error: "write-failed"
 				});
-				return;
 			}
-			sendJson(res, 200, {
-				ok: true,
-				value: parsed.value
-			});
-		} catch {
-			sendJson(res, 200, {
-				ok: true,
-				value: { adapters: [] }
-			});
+			return;
 		}
+		sendJson(res, 405, {
+			ok: false,
+			error: "method-not-allowed"
+		});
 	}
 };
 const STATE_PATH = join(process.env.DSH_HOME ?? join(homedir(), ".dsh"), "quick-toolbar-state.json");
@@ -192,10 +233,38 @@ const stateRouteDefinition = {
 		});
 	}
 };
+let wsSvc = null;
+const authUrlRouteDefinition = {
+	kind: "exact",
+	path: "/quick-toolbar/api/auth-url",
+	handler: async (_req, res) => {
+		const w = wsSvc;
+		if (w === null || w === void 0) {
+			sendJson(res, 200, {
+				ok: false,
+				error: "auth-url-unavailable"
+			});
+			return;
+		}
+		try {
+			sendJson(res, 200, {
+				ok: true,
+				url: w.connection.authenticatedUrl("http://" + w.webServer.host + ":" + String(w.webServer.port) + "/")
+			});
+		} catch {
+			sendJson(res, 200, {
+				ok: false,
+				error: "auth-url-unavailable"
+			});
+		}
+	}
+};
 function apply(ctx) {
-	ctx.inject(["webServer"], ((wsCtx) => {
+	ctx.inject(["webServer", "connection"], ((wsCtx) => {
+		wsSvc = wsCtx;
 		wsCtx.webServer.register(adaptersRouteDefinition);
 		wsCtx.webServer.register(stateRouteDefinition);
+		wsCtx.webServer.register(authUrlRouteDefinition);
 	}));
 }
 //#endregion

package/package.json

@@ -1,54 +1,54 @@
-{
-  "name": "@max-null/dsh-quick-toolbar",
-  "version": "0.3.1",
-  "description": "插件按钮聚合器：聚合三方插件散乱按钮（插件中心/侧栏/底栏/会话管理…）到统一入口——SSiD 标题栏 / web 悬浮球（iOS 小白点式）；适配器驱动，内置适配集；LLM 可生成适配（驻场工程师模式）",
-  "type": "module",
-  "main": "lib/index.js",
-  "exports": {
-    ".": "./lib/index.js",
-    "./client": "./lib/client.js",
-    "./cordis.patch.yml": "./cordis.patch.yml",
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "lib",
-    "cordis.patch.yml",
-    "README.md",
-    "LICENSE",
-    "docs/shots"
-  ],
-  "dsh": {
-    "bundle": {
-      "patch": "./cordis.patch.yml"
-    },
-    "client": {
-      "inject": [],
-      "platform": "web"
-    }
-  },
-  "scripts": {
-    "build": "tsdown",
-    "typecheck": "tsc --noEmit",
-    "watch": "tsdown --watch",
-    "test": "node --import tsx/esm --test tests/**/*.spec.ts"
-  },
-  "license": "MIT",
-  "peerDependencies": {
-    "cordis": "^4.0.0-rc.7",
-    "dsh-better-sidebar": ">=0.13.0"
-  },
-  "peerDependenciesMeta": {
-    "dsh-better-sidebar": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "tsdown": "^0.22.2",
-    "tsx": "^4.0.0",
-    "typescript": "^5.6.0"
-  },
-  "dependencies": {
-    "zod": "^4.5.4"
-  }
-}
+{
+  "name": "@max-null/dsh-quick-toolbar",
+  "version": "0.8.3",
+  "description": "插件按钮聚合器（高度可扩展）：把三方插件散乱按钮聚合到统一入口——SSiD 标题栏 / web 悬浮球；载体+驻场 LLM 范式——任何人都能把自己环境里任何插件的按钮动态聚合（LLM 一键注册、右键删除=注销，纯数据零代码，不动插件源码）",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE",
+    "docs/shots"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [],
+      "platform": "web"
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "watch": "tsdown --watch",
+    "test": "node --import tsx/esm --test tests/**/*.spec.ts"
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "cordis": "^4.0.0-rc.7",
+    "dsh-better-sidebar": ">=0.13.0"
+  },
+  "peerDependenciesMeta": {
+    "dsh-better-sidebar": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsdown": "^0.22.2",
+    "tsx": "^4.0.0",
+    "typescript": "^5.6.0"
+  },
+  "dependencies": {
+    "zod": "^4.5.4"
+  }
+}