插件 API 建议：允许插件创建「无边框 / 置顶 / 可定位」的自有浮窗（桌面端）

[MeteorNOX]

背景

我们在维护 dsh-whale-widget（DeepSeek 余额小鲸鱼挂件，https://github.com/MeteorNOX/DeepSeek-Balance-Whale-Widget）。
用户希望挂件能像"桌宠 / 便签"那样：拖到屏幕边缘停留 0.5 秒 ⇒ 从 DSH 页面脱离出去，成为桌面上的常驻小窗
（可置顶、可贴边）；脱离状态下按压动画、余额显示、音效照旧，只把菜单换成「回到 DSH」；
DSH 页面里留一个小的召回点。

这个诉求其实对任何界面型插件都成立（桌宠、便签、状态浮标、计时器、悬浮终端），不是我们独有。

现状（我们已实测，供参考）

尝试	结果
插件宿主里 require('electron')	宿主是 Node 语义（process.type === 'node'）⇒ Cannot find module 'electron' ✗
渲染进程 window.open()	返回 null（被 setWindowOpenHandler 拒绝）✗
documentPictureInPicture.requestWindow()	InvalidStateError: Internal error: no window ✗（Electron 没有浏览器外壳）
主进程	本来就有 new BrowserWindow / ipcMain.handle，且 PLATFORM_IPC.open / bounds / close 已经在用浮动小窗（平台账号登录）✓

也就是说：能力已经在主进程里，只差"暴露给插件"这一步。

建议（最小可用 API）

Host 侧 Cordis service：

ctx.desktopWindows.open({
  url: '/my-plugin/float.html',   // 必须是本插件自己注册的路由（同源）
  width: 240, height: 300,
  x: 120, y: 80,                  // 可定位 ⇒ 吸附 / 贴边才可能实现
  frameless: true, transparent: true, alwaysOnTop: true, skipTaskbar: true,
}) // → handle { setPosition, setBounds, setAlwaysOnTop, setIgnoreMouseEvents,
   //            show/hide/close, on('moved' | 'closed'), bounds(), displayWorkArea() }

建议的约束：URL 归属校验 / 每插件窗口数上限 / 不可导航 / 不可全屏 / 默认不抢焦点 /
插件卸载与 DSH 退出时自动回收 / 托盘提供「关闭全部浮窗」。

成本评估

复用现有 PLATFORM_IPC.* 的实现路径：主进程加一组 IPC（约 80–120 行）、preload 白名单（约 10 行）、
Host 侧桥接（约 40 行）、校验与回收（约 30 行）。

附：我们的降级方案

在拿到这个能力之前，我们先做了个"宿主 spawn 本机浏览器 --app= 窗口 + Win32 定位"的原型 ——
可跑，但带系统标题栏、多一个任务栏项、依赖用户本机安装了浏览器、生命周期在进程外。
如果 DSH 提供上面这个能力，这些代价都会消失，体验也会回到"原生浮窗"。

需要的话我们可以补一份完整的需求文档（含 API 细节、验收标准、多屏/吸附的边界条件）。

[MeteorNOX]

附：完整需求文档

需求说明：给 DSH 插件开放「浮动窗口」能力

提出方：dsh-whale-widget（DeepSeek 余额小鲸鱼挂件，仓库 MeteorNOX/DeepSeek-Balance-Whale-Widget）
版本：2026-10-23（DSH Desktop 0.2.1-rc.2，Electron 44.7.0）
目的：让插件能把自己的界面放到 DSH 窗口之外，成为一个常驻桌面的浮动窗口

---

1. 一句话诉求

希望 DSH 提供一个插件可调用的窗口 API，允许插件创建"无边框 + 可置顶 + 可设置位置与大小"的
自有页面浮窗（同一套页面/同源），并能在插件侧控制其位置、显隐与关闭。

---

2. 现状与实测证据（为什么插件自己做不到）

事实	证据
插件宿主是纯 Node 语义	宿主进程 process.type === 'node'；require('electron') → Cannot find module 'electron'
宿主里没有窗口 API	dsh-desktop-host/lib/index.js 仅做 dsh-app-boot / profile-boot 引导，无 Electron 依赖
渲染进程的 window.open 被拒	实测返回 null；主进程 lib/main.js 中有 7 处 setWindowOpenHandler 拦截
Document Picture-in-Picture 不可用	documentPictureInPicture.requestWindow() → InvalidStateError: Internal error: no window（Electron 无浏览器外壳）
主进程本来就有建窗能力	lib/main.js 中有 new BrowserWindow ×4、ipcMain.handle ×30、Tray；其中 PLATFORM_IPC.open/bounds/close 已在用浮动小窗（平台账号登录）

⇒ 结论：能力只差"暴露给插件"这一步；机制已经在跑。

---

3. 目标场景（我们的插件）

小鲸鱼挂件目前只能活在整个 DSH 页面里。我们希望：

1. 用户把挂件拖到屏幕边缘并停留 0.5 秒 ⇒ 出现「钉到桌面」提示；
2. 点它 ⇒ 挂件脱离 DSH 页面，成为桌面上一个无边框小窗（置顶、可拖动、贴边）；
3. 脱离态：菜单按钮换成「回到 DSH」；按压动画、余额显示、音效全部照旧；
4. DSH 页面里留一个小悬浮点，点它把挂件召回；
5. 关闭浮窗 / 关闭页面 ⇒ 自动回收，不留下孤儿窗口。

这类需求（桌宠、便签、状态浮标、计时器）对任何"界面型"插件都成立，不是我们独有。

---

4. 建议 API（草案）

4.1 Host 侧（插件宿主 Node 进程内的 Cordis service，推荐）

理由：插件的主要逻辑与状态都在 Host 侧；Client 侧只需要"叫一声"。

// 由 DSH 提供，插件通过 ctx.get('desktopWindows') / ctx.desktopWindows 取用
interface DesktopWindows {
  /** 打开一个属于本插件的浮窗；url 必须解析到本插件自有路由（同源、不可外站） */
  open(options: FloatingWindowOptions): Promise<FloatingWindowHandle>
  /** 当前本插件已开的浮窗 */
  list(): FloatingWindowInfo[]
  /** 关闭某个/全部 */
  close(id?: string): Promise<void>
}

interface FloatingWindowOptions {
  /** 相对 URL（如 '/dsh-whale/float.html'），必须由本插件注册的路由提供 */
  url: string
  width: number
  height: number
  /** 打开位置；省略则由系统决定。给出后必须"尽力"精确到位（吸附功能依赖它） */
  x?: number
  y?: number
  /** 默认 false。为 true 时使用系统级置顶（默认不抢焦点） */
  alwaysOnTop?: boolean
  /** 默认 true：无系统边框（由页面自己画外观） */
  frameless?: boolean
  /** 默认 true：背景透明（配合页面透明区域实现"异形窗口"） */
  transparent?: boolean
  /** 默认 true：不出现在任务栏 */
  skipTaskbar?: boolean
  /** 默认 true：不可缩放 */
  resizable?: boolean
  /** 打开时不抢焦点（置顶浮窗应当默认不抢） */
  focusable?: boolean
  title?: string
}

interface FloatingWindowHandle {
  id: string
  /** 移动窗口（吸附/贴边必需）；返回是否成功 */
  setPosition(x: number, y: number): Promise<boolean>
  setSize(width: number, height: number): Promise<boolean>
  setAlwaysOnTop(on: boolean): Promise<void>
  setIgnoreMouseEvents(ignore: boolean, forward?: boolean): Promise<void>  // 异形窗口点击穿透
  show(): Promise<void>; hide(): Promise<void>; close(): Promise<void>
  /** 事件：窗口被用户移动/缩放/关闭 */
  on(event: 'moved' | 'resized' | 'closed', cb: (info: FloatingWindowInfo) => void): () => void
  /** 当前几何（屏幕坐标） */
  bounds(): Promise<{ x: number; y: number; width: number; height: number }>
  /** 所在显示器的工作区（吸附要按"当前屏幕"算，多屏必须支持） */
  displayWorkArea(): Promise<{ x: number; y: number; width: number; height: number }>
}

4.2 Client 侧（可选，便于"页面内按钮直接开浮窗"）

如果 Host 侧服务不方便，至少在 preload-app.cjs 的白名单里加一个：

window.dshDesktop.openFloatingWindow(options): Promise<{ id: string }>
window.dshDesktop.floatingWindows(): Promise<FloatingWindowInfo[]>
window.dshDesktop.closeFloatingWindow(id?: string): Promise<void>

（页面内的客户端插件即可直接调用；建议同时限制"只有被激活的插件页面可以调用"。）

---

5. 行为与安全约定（建议）

1. 同源/白名单：url 必须由该插件自己注册的路由提供（DSH 侧校验路由归属），禁止外站 URL、禁止 file:；
2. 窗口归属：一个窗口必须绑定到"插件 + 会话/profile"；插件卸载或页面关闭 ⇒ 自动关闭其全部浮窗；
3. 数量与尺寸上限：每插件最多 N 个（建议 4）、最大尺寸不超过工作区、不允许全屏（与 PiP 规范一致，防欺骗）；
4. 不可导航：浮窗内禁止导航到其他文档（同 PiP 的 location/history 处理）；
5. 默认不抢焦点：alwaysOnTop: true 时必须能"显示但不激活"，避免打断用户输入；
6. 状态可发现：list() 要能让插件在启动时接管/清理遗留窗口（DSH 重启后不应留孤儿）；
7. 可关闭：系统级提供"关闭全部浮窗"的快捷入口（例如托盘菜单），以防页面卡死时窗口无法关闭；
8. 审计：alwaysOnTop 与"点击穿透"属于会影响其他应用的强能力，建议记一条可查的日志（谁开的、开了多久）。

---

6. 最小实现建议（成本评估：小）

主进程已有完整能力，按"复用"的思路大致是：

改动点	内容	量级
lib/main.js	新增一组 IPC：pluginWindow:open / configure / close / list，内部用 new BrowserWindow({...})；位置用 setPosition，多屏用 screen.getDisplayNearestPoint()	~80–120 行
lib/preload-app.cjs（若做 Client 侧）	exposeInMainWorld('dshDesktop') 里加 3 个方法（沿用现有 invoke(DESKTOP_IPC.*) 写法）	~10 行
Host 侧（若做 4.1）	新增一个 Cordis service，把上述 IPC 桥接给插件	~40 行
约束/校验	URL 归属校验、数量上限、卸载回收	~30 行

参考：PLATFORM_IPC.open / bounds / close 已经是"浮动小窗 + 定位 + 关闭"的现成实现，可直接抽公共部分。

---

7. 兼容与降级

• 能力探测：建议 ctx.desktopWindows 存在即为支持；我们在插件里已做了"能力探测 + 缺能力自动降级"（见下）；
• 降级路径（我们会自己实现，不需要 DSH 关心）：
  • 有该能力 ⇒ 原生浮窗（无边框 + 置顶 + 贴边，全部需求满足）；
  • 没有 ⇒ 网页端用 Document PiP（能置顶、不能定位），或干脆只保留窗口内吸附。

---

8. 验收标准（我们会照这个写自测）

1. 插件创建 240×300 / frameless / transparent / alwaysOnTop / skipTaskbar 浮窗 ⇒ 屏幕上出现无边框、置顶的小窗，任务栏无新项；
2. setPosition 生效（读回 bounds() 与设置值误差 ≤ 2px）⇒ 吸附可用；
3. 拖动浮窗后能收到 moved，displayWorkArea() 在多屏下返回正确工作区；
4. 关闭 DSH 主窗口/退出 DSH ⇒ 浮窗随之关闭，不留孤儿进程；
5. 卸载插件 ⇒ 其浮窗全部关闭；
6. url 非本插件路由 ⇒ 拒绝并给出可诊断错误。

---

9. 附：为什么"做一个插件来给 DSH 加这个能力"行不通

（这是提出方自己的查证，供参考，避免上游重复讨论。）

插件运行在 dsh-desktop-host（纯 Node），既没有 Electron API，也没有通往主进程的通用 IPC 通道；
渲染进程只有 preload 白名单内的固定 API，window.open 被 setWindowOpenHandler 拒绝。
⇒ 只有 DSH 本体能授予这个能力；第三方插件无解（除非改 app.asar，那会被升级覆盖且不可分发）。

[fant98k]

我就说，star这么高的插件，为什么不做桌面悬浮，搞得很多人一个agent，还有几个悬浮宠物

[MeteorNOX]

主要是想做dsh内的原生悬浮，可惜上游暂时没开放插件可调用的窗口API