TheChengXi/dsh-shell

DSH 悬浮框壳子（dsh-shell）

一个“只承载官方 DSH Web UI”的悬浮窗壳子：Electron 无边框置顶窗口（一窗一框），渲染层 React + shadcn/ui + Tailwind CSS；内容区 iframe 内嵌官方 DeepSeek Harness Web UI，通过 ?focus= 聚焦到任意插槽——消息流、输入区、会话列表、详情面板，或任意第三方插件注册的插槽。

多窗口同连一个 dsh 实例，经官方 events.mux 广播实现数据同步显示：在一个窗口选择会话、输入内容、发送消息，其他窗口同步呈现。目标端口未连接 dsh 时，内容区透明透出 Windows 桌面（v0.2.0）。已连接时可选「空闲自动隐藏标题栏」——悬停顶部热区即时唤出、移出延迟淡出（v0.3.0）。

只兼容官方 DSH Web UI：第三方 UI 必须基于官方插槽系统（@deepseek-ai/dsh-client-ui-slots）扩展，随官方界面照常渲染；不兼容任意第三方页面——内容源白名单在构造层拒绝一切非官方形态的 URL。

特性

| 能力 | 说明 |
|---|---|
| 🪟 悬浮窗 | 无边框、置顶（alwaysOnTop）、标题栏拖拽、边缘缩放、最小化/还原、关闭 |
| 🎯 插槽聚焦 | ?focus= 只显示目标插槽；focus-plugin 动态插槽清单 + 第三方插件来源标注 + 自定义路径输入；预置快照 5 项（单一事实源，随 focus 内置规则自动跟随） |
| 🔒 内容源白名单 | iframe src 唯一经 lib/frameUrl.ts 构造——只允许「目标 origin 根路径 + focus 参数」，第三方页面一律拒绝 |
| 🔗 目标连接管理 | 默认 http://127.0.0.1:3081，UI 可改并记忆（localStorage），storage 事件跨窗口同步 |
| 📡 多窗口数据同步 | 所有窗口同连一个 dsh 实例，共享服务端会话状态 + events.mux 广播，一个窗口操作、全部窗口同步显示 |
| 🧩 第三方 UI 兼容 | 基于官方插槽注册的 DSH UI 插件在聚焦视图内照常渲染 |
| 👻 空端口透明显示 | 目标 dsh 未启动/中断/地址非法时内容区透明透出桌面（标题栏常驻整条可拖拽、内容区点击穿透）；主进程低频探活 + 点击窗口快速自检自动回连（v0.2.0，拖拽增强 v0.4.0） |
| 🎞 标题栏自动隐藏 | 已连接 dsh 时标题栏按「始终显示 / 空闲时自动隐藏」运行——悬停顶部热区即时唤出、移出延迟淡出，浮层展开自动钉住；覆盖式真透明露出内容，热区高度与收起延迟可在「配置」里调（v0.3.0） |
| ⚙️ 插槽配置 | 每个插槽独立记忆壳子尺寸/位置（拖拽调宽高/移动自动写回）；插槽下拉内点齿轮进入「替换式配置页」——改尺寸、设为默认启动、以此插槽新建壳子、位置只读（v0.4.0） |

兼容性（重要）

- 只兼容官方 DSH Web UI（deepseek-ai/deepseek-harness 的 web 客户端，含 @deepseek-ai/dsh-client-app-shell 装配与 @deepseek-ai/dsh-client-ui-slots 插槽注册表）
- 聚焦效果依赖目标 dsh 已挂载 @dsh-focus/focus-plugin（?focus= 的 CSS 聚焦由官方页面内的插件实现，壳子只构造 URL）；未挂载时 ?focus= 无聚焦效果，页面完整正常显示
- 安装联动：本仓库 dependencies 声明 @dsh-focus/focus-plugin（file:../dsh-focus）——装 shell 即装 focus 包，二者需平级位于 D:/w_dev；focus 的挂载（bundle patch）仍由 dsh 实例管理。壳子内置清单（预置 5 项）构建期直引 focus 的 src/client/slot-manifest.ts 源文件（单一事实源），运行时零依赖
- 多窗口「当前选中会话」跟随依赖目标 dsh 已挂载 dsh-session-sync（不同窗口之间的选中态实时跟随由它接管；未挂载时窗口间会话选择不自动跟随）
- 版本基线：@deepseek-ai/dsh@0.1.0-rc.6；壳子只依赖 URL 参数协议与 data-slot 语义，不锚定官方编译产物类名
- 目标 dsh 默认回环地址（127.0.0.1）；跨机器部署需在 dsh 侧配置 trustedHosts

原理

┌──────────────────────── Electron 主进程 ────────────────────────┐
│  window-manager：无边框置顶悬浮窗创建/最小化/关闭/多窗口         │
│  connection-manager：低频探活 + focus 快速自检（connection:state）│
│  ipc：window:minimize/close/create + set-target/set-click-through│
└───────────────▲───────────────────────────────┬─────────────────┘
IPC invoke（preload contextBridge）      │ ?slot= URL 参数
┌───────────────┴───────────────────────────────▼─────────────────┐
│                     渲染层（React + shadcn/ui）                  │
│  TitleBar / SlotPicker / SettingsDialog / DSHFrame              │
│  lib/frameUrl：白名单 src 唯一构造入口                           │
│  lib/connectionState：连接态纯判定与推送校验                     │
│  DSHFrame：iframe 承载 + postMessage 接收（source/origin/schema 三重校验） │
│  useClickThrough：空端口内容区点击穿透（标题栏命中间键）          │
│  store/config：目标地址 localStorage + 跨窗口 storage 同步        │
└───────────────┬─────────────────────────────────────────────────┘
│ iframe src = /?focus=
┌───────────────▼─────────────────────────────────────────────────┐
│          官方 DSH Web UI（同源 iframe，数据完全一致）            │
│  插槽树 sidebar | conversation | details + 第三方注册插槽        │
└─────────────────────────────────────────────────────────────────┘

- 数据同步：所有窗口连同一个 dsh 进程，会话状态只存在 host 侧一份；每次变更经 /api/events.mux、/api/events.host 下行 WebSocket 广播给所有连接的窗口。会话「列表增删」由这些广播自动同步；但「当前选中会话」是各窗口的本地 UI 态，DSH 不自动跨窗跟随——需另挂 dsh-session-sync 才实时同步。?focus= 只是纯 CSS 显示裁剪，数据流不变——"显示不同插槽，数据完全同步"。
- 白名单边界：壳子只约束 iframe 的初始 src（导航层）；iframe 文档内部的 /api、WebSocket 请求同源于 DSH host，不受壳子约束。
- 空端口透明：主进程 connection-manager 低频 GET 目标 origin 根路径判 up/down 并广播；渲染层在 down/加载失败时卸载 iframe（避免 Chromium 错误页白块破坏透明）并让内容区透明 + setIgnoreMouseEvents 穿透，标题栏常驻可拖拽/设置；窗口 focus 触发一次快速自检。
- 标题栏自动隐藏：无边框窗口的 -webkit-app-region: drag 区域会吞掉 DOM 悬停事件，故由主进程 cursor-manager 以 40ms 轮询全局光标坐标，经 titlebar:hover 推送 { inside, offsetY } 几何给渲染层；渲染层 useTitlebarAutoHide + lib/titlebarAutoHide 纯函数做「唤出/保持」不对称迟滞判定，覆盖模式下整条标题栏淡出为透明、露出下方内容，设置/插槽选择器浮层展开时钉住。

快速开始

前置条件：

1. 已启动一个 dsh 实例（默认 http://127.0.0.1:3081）
2. 目标实例已挂载 @dsh-focus/focus-plugin（聚焦效果依赖；未挂载也可运行，页面正常显示）
powershell
npm install        # 安装依赖
npm run dev        # 启动悬浮窗（默认聚焦 conversation.session 消息流）

生产构建与打包：
powershell
npm run build      # electron-vite 构建（out/）
npm run package    # electron-builder 打包（dist/：portable 便携版 + NSIS 安装包）

打包产物（dist/）：

| 文件 | 说明 |
|---|---|
| dsh-shell--portable.exe | 便携版：单文件双击即用，无需安装 |
| dsh-shell Setup .exe | NSIS 安装器：可选安装目录 |
| win-unpacked/ | 解包目录（调试用） |

Windows 打包注意：若 electron-builder 下载工具链时报 unable to verify the first certificate（企业代理/本地 CA 所致），先 $env:NODE_OPTIONS = "--use-system-ca" 再 npx electron-builder 重试；仍失败可临时 $env:NODE_TLS_REJECT_UNAUTHORIZED = "0" 后再试。

Windows 注意：若 shell 环境注入了 ELECTRON_RUN_AS_NODE=1，先执行 Remove-Item Env:ELECTRON_RUN_AS_NODE 再 npm run dev（否则 Electron 会被当纯 Node 运行）。

使用

| 操作 | 说明 |
|---|---|
| 拖动标题栏 | 移动悬浮窗 |
| 拖窗口边缘/角落 | 缩放 |
| 最小化 / 关闭 | 窗口控制按钮（右上） |
| ＋ 新建悬浮框 | 打开第二个悬浮窗（一窗一框，可再选插槽） |
| 插槽下拉 | focus-plugin 动态发现清单（经 postMessage 三重校验后展示），第三方插件注册项带「插件」角标；未装/枚举失败时回落预置 5 项：会话列表 / 对话区 / 消息流 / 输入区 / 详情面板（随 focus 内置规则自动跟随，已废弃的消息全宽不在列） |
| 自定义路径… | 输入任意 data-slot 路径（含第三方插件注册的插槽）；未知路径按官方 no-op 语义完整显示 |
| 插槽配置（齿轮） | 插槽下拉每个插槽行右侧点齿轮进入该插槽配置页：改壳子宽高（「保存尺寸」两字段合法保存、空/非法则清除该插槽尺寸）、设为默认启动、以此插槽新建壳子、只读位置；顶部返回或保存后回列表 |
| 设置按钮 | 「配置」面板：修改目标 DSH 地址（白名单校验，非法拒绝）+ 标题栏显示模式与自动隐藏调优（唤出热区高度 / 隐藏延迟） |
| 标题栏自动隐藏 | 已连接 dsh 且设为「空闲时自动隐藏」时：悬停顶部热区即时唤出、移出延迟收起；设置/插槽选择器浮层展开时钉住；顶部保留 3px 提示细条 |
| 空端口（未连接 dsh） | 内容区透明透出桌面、点击穿透到桌面；标题栏常驻可拖拽/设置。启动 dsh 后自动回连，或点标题栏快速自检 |
配置持久化于渲染层 localStorage（dsh-shell.target 目标地址、dsh-shell.titlebarMode 标题栏模式、dsh-shell.titlebarSettings 标题栏调优），同源多窗口经 storage 事件自动同步。

开发

npm run typecheck  # tsc --noEmit（main/preload/renderer 双 tsconfig）
npm run test       # vitest 单测（白名单/插槽/slot 消息 schema/连接态/标题栏显隐与调优/节点尺寸·位置·穿透判定/配置持久化，117 用例）
npm run dev        # electron-vite dev（渲染层 HMR + 主进程热重载）

结构（electron-vite 三段构建）：

src/
├── shared/ipc-channels.ts   # IPC 契约（通道名 + WindowApi 类型）
├── main/                    # 主进程：窗口管理 / IPC / 连接探活 / 光标轮询 / 生命周期
│   ├── connection-manager.ts # 低频探活 + focus 快速自检 + 状态广播
│   └── cursor-manager.ts     # 40ms 光标轮询 → titlebar:hover 推送（标题栏悬停）
├── preload/                 # contextBridge 暴露最小 window.api
└── renderer/src/
├── components/          # 壳子 UI（含 shadcn ui 原语）+ useClickThrough / useTitlebarAutoHide hook
├── lib/                 # 业务纯函数：frameUrl 白名单 / slots / slotDiscovery / connectionState / titlebarMode·AutoHide·Settings / nodeConfig·nodePosition
└── store/               # 数据存取：config / ipc / windowParams / titlebarConfig / titlebarSettings / defaultSlot / nodeConfigs / nodePositions

已知限制与演进方向

- 窗口位置/大小不记忆、无托盘常驻、无一键拉起 dsh、每窗口共享同一目标地址——均为 v1 边界，演进项见 .intentflow/floating-frame/later-on.md；空端口透明态的演进项（选中标识、探测升级 /api、慢自检退避等）见 .intentflow/empty-port/later-on.md；标题栏自动隐藏的演进项（每插槽/每节点独立配置、上下文触发、profile 持久化体系、观感打磨等）见 .intentflow/titlebar-autohide/later-on.md
- 连接判定 = 主进程低频探活（GET 目标 origin 根路径，任意 HTTP 响应即 up）+ iframe onLoad；跨源限制下无法读取官方页面内部状态
- 空端口透明基于 Windows 窗口级 transparent，静止态无碍；拖拽/缩放仍有已知闪烁/性能瑕疵（有内容时不受影响）

版本历史

v0.5.0

- 插槽清单契约共享（slot-manifest）：预置清单从 focus 的 src/client/slot-manifest.ts 派生（单一事实源，删除本地 6 条硬编码拷贝），conversation.chat.node（消息全宽）废弃注释并从清单剔除
- 发现协议升级：dsh-shell:slots 清单项必带 topSlot / source（供分组与来源标注），缺字段整条拒绝（免历史兼容，单人同步升级）
- UI 来源标注：第三方插件注册项带「插件」角标（不做按插槽分层的组头展示，避免组头与唯一项 label 重复的冗余）
- 安装联动：dependencies 声明 @dsh-focus/focus-plugin（file:../dsh-focus），装 shell 即装 focus 包

v0.4.0

- 插槽级配置（slot-config）：每插槽独立记忆壳子尺寸，插槽下拉内配置可改宽高（保存尺寸）、设为默认启动、以此插槽新建壳子；切换聚焦/新建/首启按配置还原几何
- 插槽几何记忆（slot-geometry）：拖边缘调宽高自动写回该插槽尺寸、拖标题栏移动自动写回位置（相对工作区比例）；位置只读展示
- 插槽配置页化（slot-config-page）：配置承载从「悬停二级浮层面板」重构为「下拉内替换式配置页」——单栏列表每行齿轮入口，同宽配置页替换列表（改尺寸/设默认/新建/只读位置 + 顶部返回），返回/保存回列表、设默认/新建留页，消除二级浮层点击不稳定与超窗裁剪
- 空端口标题栏整条可拖拽（empty-port-drag）：主进程光标几何托管穿透 click-through，grab 光标拖拽提示，浮层打开期间整体禁穿透

v0.3.0

- 标题栏自动隐藏：已连接 dsh 时按「始终显示 / 空闲时自动隐藏」运行——悬停顶部热区即时唤出、移出延迟淡出，浮层展开自动钉住
- 覆盖式真透明显隐（隐藏时透出内容而非桌面）+ 顶部 3px 提示细条
- 主进程光标轮询（cursor-manager）绕开无边框拖拽区吞 DOM 悬停事件；悬停判定下放渲染层纯函数（titlebarAutoHide），含「唤出/保持」不对称迟滞
- 「配置」面板新增标题栏调优（唤出热区高度 + 隐藏延迟）；设置入口「连接设置」更名「配置」

v0.2.0

- 新增空端口透明显示：目标 dsh 未启动/中断/地址非法时内容区透明透出桌面，标题栏常驻、内容区点击穿透
- 主进程低频探活（connection-manager）+ 窗口 focus 快速自检自动回连
- 连接态纯判定与推送校验（lib/connectionState.ts）+ 单测

v0.1.0

- 首个版本：Electron 无边框置顶悬浮窗壳子 + 官方 DSH iframe 承载 + 插槽聚焦 + 多窗口

相关项目

- dsh-focus — 本壳子的聚焦引擎：?focus= 纯 CSS 聚焦插件（需挂载到目标 dsh 实例）
- dsh-session-sync — 多窗口会话选择同步：跨窗口实时跟随「当前选中会话」（需挂载到目标 dsh 实例）
- deepseek-ai/deepseek-harness — 官方 DeepSeek Harness（本壳子唯一兼容的 Web UI）

许可证

MIT