小窗模式 Aik358/dsh-mini-window

dsh-mini-window

A mini-window mode for DeepSeek Harness (DSH) — install it and a floating ball pops out a real, always-on-top browser window. 给 DeepSeek Harness（DSH）的小窗模式插件 —— 装上就有一个悬浮球，点一下弹出真正的置顶浏览器小窗。

Zero download · no Electron · no third-party plugins · zero impact when off. 零额外下载 · 不需要 Electron · 不依赖任何第三方插件 · 不带参数时对主界面零影响。

English · 中文

What it is

dsh-mini-window gives DSH a mini window. Install the plugin and a floating ball appears
in the page; click it and DSH opens in a separate, always-on-top browser window at 520×720 — a real OS window you can move and pin over other apps.

The same layout is also reachable in-page with ?dsh-mini=1, where the three-column UI collapses
into a compact single-column view styled as a floating card.

When ?dsh-mini=1 is absent, the attribute html[data-dsh-mini] never exists, so every rule
is inert and the official layout is untouched.

Features

| Feature | Description |
| Standalone mini window | A real browser window in app mode: no address bar, no tab strip, exactly 520×720. Driven via --app=, so nothing is downloaded |
| Pin on top | Toggle always-on-top from the top bar — a real Win32 SetWindowPos, with the state read back to confirm |
| Floating ball | Appears automatically (draggable, snaps to the nearest edge, remembers its position). Pure DOM. |
| Mini-window mode | Open /?dsh-mini=1 for the same compact single-column layout in-page |
| Top-bar controls | Minimize / pin-on-top / sidebar toggle / compact float / more menu (includes 80%–150% UI zoom) |
| Does not fight the official layout | At narrow viewports DSH already collapses the sidebar into an overlay; this plugin deliberately does not reimplement responsive behavior |
| Verifiable zero-impact | With no ?dsh-mini=1 none of the mini CSS applies |

What you get after installing

| dsh plugin --profile add @a9i5k4/dsh-mini-window | Floating ball + 520×720 always-on-top browser mini window |
| Extra download | 0 bytes — it drives the Chrome/Edge you already have |
| Requirement | Chrome or Edge installed (Chrome preferred, Edge as fallback) |
| Not included | Tray icon. Close the mini window and click the ball again to reopen |

Install

npm (recommended)
dsh plugin --profile <your-profile> add @a9i5k4/dsh-mini-window

or with pnpm directly
pnpm add @a9i5k4/dsh-mini-window

or from GitHub
dsh plugin --profile <your-profile> add github:Aik358/dsh-mini-window

Restart the DSH host after installing (the plugin roster is assembled at startup).

Then either:

- Click the floating ball in the page → the 520×720 always-on-top window pops out, or
- open http://127.0.0.1:19387/?dsh-mini=1 for the in-page mini layout.

- With ?dsh-mini=1 → mini-window mode
- 不启用 → 官方三栏布局，零影响

环境要求

必须装好 Chrome 或 Edge。两个都找不到时，插件会报明确的错误，而不是默默什么都不做。需要的话可以覆盖路径：

$env:DSH_MINI_BROWSER = "D:\path\to\chrome.exe"

如果 DSH_MINI_BROWSER 已设置，但指向的文件不存在，插件会明确失败，不会退回默认浏览器，所以配置错误永远不会被悄悄忽略。

设计取舍

1. 为什么用浏览器，不用 Electron

最早的设计会另起一个 Electron 进程。这要付出约 235 MB 的下载量，而且不属于 DSH 插件契约。浏览器窗口本来就是系统窗口，所以插件改为驱动应用模式下的 Chrome/Edge：

chrome.exe --app=<handoff-url> --window-size=520,720 --user-data-dir=<isolated profile>

- 应用模式给出独立窗口，没有地址栏。
- 插件跑一个一次性回环服务，写入会话 cookie 并重定向到 DSH，所以迷你窗口启动时已经登录。
- Cookie 不区分端口，所以交接服务和 DSH 可以用不同端口。
- 独立配置档放在 ~/.dsh/dsh-mini-window-browser 下 —— 你自己的浏览器配置档完全不受影响。

说句实话，代价是： 应用模式会保留系统标题栏（不像 Electron 的 frame:false）。要彻底去掉标题栏，就得重新打包 Electron，那又违背了零下载的目标。

2. 为什么不自己写响应式 CSS

DSH 前端本来就是响应式的。实测数据：

| 视口宽度 | 侧边栏 | 会话区 |
| ≥1024 | 展开 280px | @x=280 |
| 920–760 | 自动折叠为 56px 窄栏 | @x=56 |
| ≤760 | 浮层，pointer-events:none | 全宽 @x=0 |

在左侧条带上，elementFromPoint 命中侧边栏 0/9 次 —— 官方 UI 已经让会话区占满宽度。再写一套折叠规则，只会和官方机制打架，冒出各种随机症状。所以这里刻意不做。

3. 所有规则都限定在 html[data-dsh-mini] 下

没有这个参数，属性就不存在 ⇒ 什么都不生效。正因如此，「零影响」这个说法才可验证，而不是一句空话。

4. 规格只有一份来源

plugin/lib/mini-spec.cjs 存放几何尺寸和颜色。样式表和应用侧共用同一份，数字不会写两遍然后各自跑偏。

5. 没有构建步骤

lib/client.js 是手写的经典脚本，通过官方的 __ModuleLoader__.load({ id, factory }) 注册。已对照真实 bundle 验证 —— 改完刷新即可，不用打包。

6. 绝不向上抛异常

宿主靠某个条目是否激活来判断启动成功。任何未捕获的异常都会让整个应用打不开 —— 所以宿主侧每条路径都包在 try/catch 里，降级处理，不抛异常。
7. 回读状态，验证窗口操作

SetWindowPos 跨进程是异步的：设置 WS_EX_TOPMOST 后立刻读取，拿到的是旧值。插件会先等一会儿再回读，并且遍历所有候选窗口，而不是猜一个 —— 否则一次过期的读取，看起来就和「图钉按钮没反应」这个 bug 一模一样。

项目结构

plugin/ ← 可发布的 DSH 插件 package.json ← dsh.client 声明（platform / inject） lib/client.js ← 浏览器入口（手写，无构建） lib/index.js ← 宿主入口 lib/host-routes.js ← 宿主路由（/dsh-mini-window/） lib/browser-window.js ← 浏览器应用模式窗口（launch / fit / pin） lib/host-window.js ← Electron 窗口路径（兜底） lib/ls-extract.cjs ← 零依赖的 Chromium localStorage 提取器 lib/mini-spec.cjs ← 规格的唯一事实来源 cordis.patch.yml ← 宿主侧挂载 tests/smoke/ ← 运行时守卫

companion/ ← 旧的独立 Electron 小窗（未发布到 npm） main.js ← 主进程（auth / injection / window / tray） preload.js renderer/ ← 悬浮球 + 窗口外壳

companion/ 是更早的 Electron 方案。现在发布的小窗已经不需要它；留在仓库里仅供参照，构建它要花约 151 MB。

evidence/ 和 probe/ 放的是本地开发期的埋点工具。它们依赖这台机器的 DSH 宿主和截图，已通过 .gitignore 排除，不随包分发。

开发

Runtime guard: actually executes the factory and verifies DSH can load the plugin
node plugin/tests/smoke/client-factory-guard.cjs

Syntax check
node --check plugin/lib/client.js

以本地链接方式安装时（link:<path>/plugin），改客户端代码刷新页面就够了 —— 但改宿主侧代码（lib/index.js、lib/host-routes.js、lib/browser-window.js）需要重启宿主。

兼容性

- 平台：web（DSH 桌面端和网页端共用同一套前端）
- 浏览器：优先 Chrome，Edge 兜底
- 对等依赖：@deepseek-ai/cordis
- 运行时依赖：无（只用 Node 内置模块）
- 不需要任何第三方插件 —— 自包含，在任何 DSH 环境里都能加载

许可证

MIT

这是什么

dsh-mini-window 给 DSH 加了一个小窗。装上插件后，页面里会出现一个悬浮球；点它，DSH 就会在一个独立的、可置顶的浏览器窗口里打开，尺寸 520×720 ——是一个真正的操作系统窗口，可以拖动，也可以钉在其他应用最上层。

同一套版面也能在页面内触发：带 ?dsh-mini=1 打开时，三栏布局会收成一个紧凑的单栏视图，外观是一张悬浮卡片。

不带 ?dsh-mini=1 时，html[data-dsh-mini] 这个属性根本不存在，所以所有规则都不生效，官方布局完全不受影响。

特性

| 能力 | 说明 |
| 独立小窗 | 真正的浏览器应用模式窗口：无地址栏、无标签栏，尺寸恰好 520×720。用 --app= 驱动，不下载任何东西 |
| 置顶 | 顶栏的图钉可切换「钉在最上层」—— 真正的 Win32 SetWindowPos，并回读状态确认 |
| 悬浮球 | 自动出现（可拖动、松手吸附最近的边、记住位置）。纯 DOM。 |
| 小窗模式 | 打开 /?dsh-mini=1 在页面内得到同一套紧凑单栏版面 |
| 顶栏控件 | 最小化 / 置顶 / 侧栏开关 / 紧凑浮窗 / 更多菜单（含 80%–150% 界面缩放） |
| 不抢官方布局 | 窄视口下 DSH 官方已把侧栏折叠成浮层；本插件刻意不重复实现响应式 |
| 可验证的零影响 | 不带 ?dsh-mini=1 时小窗相关规则一条都不生效 |

装完你会得到什么

| dsh plugin --profile add @a9i5k4/dsh-mini-window | 悬浮球 + 520×720 可置顶的浏览器小窗 |
| 额外下载 | 0 字节 —— 它驱动你已经装好的 Chrome / Edge |
| 前提 | 装了 Chrome 或 Edge（优先 Chrome，退 Edge） |
| 不含 | 托盘图标。小窗关掉后再点球即可重开 |

安装

npm（推荐）
dsh plugin --profile <你的 profile> add @a9i5k4/dsh-mini-window

或直接用 pnpm 装
pnpm add @a9i5k4/dsh-mini-window

或从 GitHub
dsh plugin --profile <你的 profile> add github:Aik358/dsh-mini-window

安装后需要重启 DSH 宿主（插件清单在启动时装配）。

然后二选一：

- 点页面里的悬浮球 → 弹出 520×720 置顶小窗；
- 或打开 http://127.0.0.1:19387/?dsh-mini=1 用页面内的小窗版面。

- 带 ?dsh-mini=1 → 小窗模式
- 不带 → 保持官方三栏布局，零影响

前提条件

必须装了 Chrome 或 Edge。两个都没有时插件会明确报错，而不是静默什么都不做。
需要时可覆盖浏览器路径：

$env:DSH_MINI_BROWSER = "D:\路径\到\chrome.exe"

如果 DSH_MINI_BROWSER 指向的文件不存在，插件会明确失败而不是回退到默认浏览器，避免配置写错却被静默忽略。

设计取舍

1. 为什么用浏览器，不用 Electron

最早的设计是另起一个 Electron 进程。那要多下载约 235 MB，而且不属于 DSH 插件契约。
既然浏览器窗口本来就是普通的系统窗口，插件改为直接驱动 Chrome/Edge 的应用模式：

chrome.exe --app=<交接地址> --window-size=520,720 --user-data-dir=<独立 profile>

- 应用模式给出的是没有地址栏的独立窗口。
- 插件临时起一个只监听回环的一次性服务，签发会话 cookie 后跳转到 DSH ⇒ 小窗一开出来就已经是登录态。
- cookie 不区分端口，所以交接服务与 DSH 可以用不同端口。
- 独立 profile 落在 ~/.dsh/dsh-mini-window-browser，绝不碰你自己的浏览器数据。

说清楚代价：应用模式保留系统标题栏（不像 Electron 的 frame:false）。
要彻底去掉它就得重新引入 Electron，与「零下载」的目标冲突。

2. 为什么不用自己写响应式 CSS

DSH 官方前端自带响应式，实测：

| 视口宽 | 侧栏 | 对话区 |
| ≥1024 | 280px 展开 | @x=280 |
| 920–760 | 自动折叠成 56px 轨道 | @x=56 |
| ≤760 | 浮层，pointer-events:none | 满宽 @x=0 |

elementFromPoint 在左侧窄带 9 个采样点 0/9 命中侧栏 —— 官方已让对话区满宽。
再叠一套收缩 CSS 只会与官方机制互相覆盖（症状随机），因此明确不做。

3. 全部规则挂在 html[data-dsh-mini] 下

不带参数时该属性不存在 ⇒ 零生效。这是「零影响」这句话可验证而不是口号的前提。

4. 规格常量单一真相源

plugin/lib/mini-spec.cjs 集中定义几何与配色，样式表与应用侧共用同一份，避免同一数值在多处各写一遍而漂移。

5. 免构建

lib/client.js 是手写 classic script，经官方 __ModuleLoader__.load({ id, factory }) 注册。
已用真实 bundle 验证 —— 改完刷新页面即可，不需要打包步骤。

6. 绝不冒泡

宿主以「entry 是否 activate」判定启动成败。任何未捕获异常都会导致整个应用打不开 ——因此宿主侧每条路径都有 try/catch 兜底，宁可降级也不抛。

7. 窗口操作必须回读验证

SetWindowPos 是跨进程异步的：设置完立即回读 WS_EX_TOPMOST 会读到旧值。
插件设置后会等一拍再读，并且遍历全部候选窗口而不是猜一个 ——否则「读到旧值」和「图钉点了没反应」在现象上完全一样，无法区分。

目录结构

plugin/ ← 要发布的 DSH 插件 package.json ← dsh.client 声明（platform / inject） lib/client.js ← 浏览器侧入口（手写，免构建） lib/index.js ← host 侧入口 lib/host-routes.js ← host 路由（/dsh-mini-window/） lib/browser-window.js ← 浏览器应用模式窗口（启动 / 校正尺寸 / 置顶） lib/host-window.js ← Electron 窗口路径（兜底） lib/ls-extract.cjs ← 零依赖的 Chromium localStorage 提取器 lib/mini-spec.cjs ← 规格常量单一真相源text cordis.patch.yml ← host 侧挂载 tests/smoke/ ← 运行时守卫

companion/ ← 早期的独立 Electron 小窗（不随 npm 包发布） main.js ← 主进程（认证 / 注入 / 窗口 / 托盘） preload.js renderer/ ← 悬浮球 + 小窗外壳

companion/ 是更早的 Electron 方案。现在发布的小窗已经不需要它，保留在仓库里供参考；自己构建它要花约 151 MB 下载。

evidence/ 与 probe/ 是本机开发期的实测数据与工具，依赖本机 DSH 宿主与截图，已通过 .gitignore 排除，不随仓库分发。

开发 bash

运行时守卫：真执行 factory，验证插件能被 DSH 正确加载

node plugin/tests/smoke/client-factory-guard.cjs

语法检查

node --check plugin/lib/client.js

以本地链接方式安装时（link:<path>/plugin），前端改动刷新页面即生效；但 host 侧改动（lib/index.js、lib/host-routes.js、lib/browser-window.js）需要重启宿主。

兼容性

- 平台：web（DSH 桌面端与 Web 端共用同一前端）
- 浏览器：优先 Chrome，退 Edge
- peer 依赖：@deepseek-ai/cordis
- 运行时依赖：无（只用 Node 内置模块）
- 不依赖任何第三方生态插件 —— 交付物自持，任何 DSH 环境都能加载

License

MIT