dsh-float-window

DeepSeek Harness（DSH）悬浮窗：始终置顶的会话镜像小窗。把主界面切到后台，Agent 照样在跑，你在前面用一个小窗盯着它——而且 Agent 抓屏时这个浮窗自动隐身，完全不影响它的屏幕操控。

仅支持 Windows。

---

它长什么样

┌──────────────────────────────────────────┐
│ ● DSH 悬浮窗  未连接      📌 🔒 ⬆ ⛶ ⚙ ✕ │  ← 拖动这里移动窗口
├──────────────────────────────────────────┤
│                                          │
│   会话镜像区（消息流 / 工具调用 / 状态）   │
│                                          │
├──────────────────────────────────────────┤
│ [ 给会话发消息 …………………… ]        ↑    │  ← 底部聊天框
├──────────────────────────────────────────┤
│ 轮 12 · 步 34 · 18.2 tok/s · 0.43 M tok  │  ← 计费/状态条
│ 缓存 62% · 上下文 ▓▓▓▓░░░░ 41%           │
└──────────────────────────────────────────┘

功能

需求	实现
悬浮窗模式（不全屏打开）	独立原生顶层窗口，无边框，默认贴在屏幕右侧
始终置顶	TopMost，标题栏 ⬆ 一键开关
固定位置	标题栏 📌（图钉）锁定/解锁拖动
锁定尺寸	标题栏 🔒（小锁）锁定/解锁缩放
自适应调整	布局随窗口尺寸重排；拖动任意边缘和四角都能缩放（系统级 WM_NCHITTEST）
全屏切换	标题栏 ⛶ 或 F11，返回时还原原来的位置与尺寸
抓屏隐身	SetWindowDisplayAffinity(WDA_EXCLUDEFROMCAPTURE)，Agent 截屏里彻底看不到这个窗
底部聊天框	与当前会话互通（随插件启用）
计费/状态条	轮数、步数、tok/s、累计 MTOK、缓存命中率、上下文用量进度条
外观自定义	背景效果：不透明 / 毛玻璃（亚克力）/ 云母 / 模糊 / 半透明；不透明度、界面缩放
按钮触发	运行 shell\run-float.cmd，或 DSH 里点插件入口
Agent 自动打开	注册 float_window 工具，模型可以自己 open / close / pin / fullscreen / hide

快速开始

git clone <repo> dsh-float-window
cd dsh-float-window

# 1) 拉 WebView2 SDK（首次一次即可）
powershell -ExecutionPolicy Bypass -File tools\setup-webview2.ps1

# 2) 直接跑浮窗（不依赖 DSH）
shell\run-float.cmd

# 3) 装进 DSH（获得会话镜像 + Agent 触发能力），然后重启 DSH
dsh plugin --profile desktop add link:.

重启后浮窗会自动连上宿主，标题栏的“未连接”变成 127.0.0.1:<port>，镜像区开始滚动会话内容。

命令行

shell\run-float.cmd                                  # 打开（已开着则前置）
shell\run-float.cmd -NoExclude                       # 调试：允许被截图（否则你截不到它）
shell\run-float.cmd -Backdrop acrylic -Opacity 0.8   # 毛玻璃 + 80% 霜化
shell\run-float.cmd -Action pin                      # 给正在运行的实例下发动作

-Action 支持 pin sizeLock topmost fullscreen hide show close； 已运行的实例每 700ms 读一次 %DSH_HOME%\float-window\command.json，所以插件也能这样遥控它。

架构

┌──────────────────────────────┐        ┌───────────────────────────────┐
│ shell/float-window.ps1       │        │ lib/host.js  (DSH 插件)        │
│  WinForms + WebView2 原生壳   │  HTTP  │  · 写 endpoint.json 给壳       │
│  · 置顶 / 锁定 / 全屏 / 缩放   │◀──────▶│  · SSE /events 会话+指标快照    │
│  · 截图排除 0x11             │  SSE   │  · /cmd 控制通道               │
│  · 位置尺寸记忆 / 单实例      │        │  · float_window 工具（Agent）  │
└──────────────┬───────────────┘        └───────────────────────────────┘
               │ postMessage 桥                    ▲
┌──────────────▼───────────────┐                  │ session/event
│ shell/ui.html （全部界面）     │        ┌─────────┴─────────────────────┐
│  工具栏 / 镜像区 / 聊天框 / 状态条 │        │ DSH 宿主：sessions / tokenMeter │
└──────────────────────────────┘        └───────────────────────────────┘

• 界面完全在 shell/ui.html：原生壳只负责窗口行为，页面通过 WebView2 的 postMessage 桥发 drag / resize / topmost / posLock / sizeLock / fullscreen / opacity / scale / backdrop 等命令。
• 数据来自插件：壳把 endpoint.json 里的地址交给页面，页面用 EventSource 订阅 /dsh-float-window/events，拿到 {messages, metrics} 快照。
• 插件是"探测式"的：ctx.get('sessions' | 'tokenMeter' | 'sessionProjection' | 'tools') 全部 try/catch，缺哪个服务就少几个数字，绝不让插件把 DSH 拖垮。

已实测的关键结论

这台机器（Windows 11 / 150% 缩放 / WebView2 154）上的实测记录：

1. 截图排除确实可行：GDI 抓屏下
   • WDA_NONE → 抓到窗口本身（对照组）
   • WDA_MONITOR (0x1) → 抓到一个纯黑方块（窗口还在，只是变黑，观感很差）
   • WDA_EXCLUDEFROMCAPTURE (0x11) → 窗口完全消失，抓到的是它背后的画面
   • 只对本进程自己的顶层窗口生效（跨进程调用返回 False），所以浮窗必须是我们自己起的进程。
2. 毛玻璃模式顺带也是"抓屏隐身"的：DWMWA_SYSTEMBACKDROP_TYPE + DwmExtendFrameIntoClientArea 的窗口，GDI 抓屏同样拿不到它（抓到的是底下内容）。
3. WebView2 SDK 用 Assembly.LoadFrom 会报 0x80131515（本机 PowerShell 5.1），改用 [Reflection.Assembly]::Load(bytes) 加载托管 DLL，再把原生 WebView2Loader.dll 放进 PATH 就好。
4. 初始化不能阻塞 UI 线程：EnsureCoreWebView2Async(...).GetAwaiter().GetResult() 会死锁，必须用 CoreWebView2InitializationCompleted 事件。
5. CoreWebView2Environment.CreateAsync 的参数顺序是 (browserExecutableFolder, userDataFolder, options)，传错会得到 "Couldn't find a compatible Webview2 Runtime"。
6. 高 DPI：WinForms 会把逻辑尺寸按缩放放大，位置要按真实 Width/Height 夹回屏幕内。
7. .ps1 里出现中文时必须存成 UTF-8 with BOM，否则 PowerShell 5.1 按 GBK 读会把脚本解析坏（tools/fix-bom.ps1 专门干这个）。
8. cordis：ctx.set 之前必须 ctx.provide。漏了会抛 cannot set property "floatWindow" without provide，后果不是"少个功能"而是整个插件树加载失败、DSH 进程直接退出。本轮就是在隔离实例里实测复现后修掉的。
9. PowerShell 事件处理器里参数不能叫 $args：它是自动变量，会把整个事件参数数组占住，于是 $e.TryGetWebMessageAsString() 变成"数组没有这个方法"——表现为页面所有按钮（含右下角缩放、置顶、锁定、全屏、设置）全部失效。正确写法是 param($s, $e)。
10. profile 的 package.json 不能带 BOM：Node 读 JSON 会报 SyntaxError: Unexpected token '锘?。用 [IO.File]::WriteAllText(..., UTF8Encoding($false)) 写。

怎么验证（可复现）

不需要动你正在用的 DSH：

# 1) 造一个隔离的 DSH_HOME，profile 只装 base + web-app + 本插件
$t = '.runtime\testhome'
New-Item -ItemType Directory -Force -Path "$t\profiles\web\node_modules" | Out-Null
# package.json(bundles 只留三个) + cordis.yml/cordis.patch.yml 见 README 上文
cmd /c mklink /J "$t\profiles\web\node_modules\dsh-float-window" "$PWD"

# 2) 起第二个实例（8099），观察插件是否被加载
$env:DSH_HOME = (Resolve-Path $t)
node <dsh bin.js> web --port 8099
#   -> 出现 endpoint.json 且无 "plugin tree failed to load" 即通过

# 3) 直接打插件路由
curl http://127.0.0.1:8099/dsh-float-window/health
curl http://127.0.0.1:8099/dsh-float-window/state
curl -N http://127.0.0.1:8099/dsh-float-window/events     # SSE，每秒一帧

# 4) 让浮窗连到这个测试实例（看视觉效果时再加 -NoExclude）
shell\run-float.cmd -DshHome $t -NoExclude
#   标题栏应变成绿点 + 127.0.0.1:8099

tools/smoke-host.mjs 则是更轻的一层：假 ctx 直接调 apply()，验证路由/SSE/工具注册不抛异常。

配置

持久化在 %DSH_HOME%\float-window\window.json（不可写时自动降到 %LOCALAPPDATA%\dsh-float-window 或仓库内 .runtime）：

{ "x": 1895, "y": 36, "w": 420, "h": 720, "topmost": true,
  "posLock": false, "sizeLock": false, "opacity": 0.92,
  "exclude": true, "scale": 1.0, "backdrop": "opaque" }

日志：%DSH_HOME%\float-window\float-window.log（每次启动都会记，排障先看它）。

目录

dsh-float-window/
├─ package.json          DSH bundle 插件元数据（dsh.bundle.patch）
├─ cordis.patch.yml      挂载声明
├─ lib/host.js           插件 Host 半（路由 + SSE + float_window 工具）
├─ shell/float-window.ps1 原生壳（窗口行为 + 互操作）
├─ shell/ui.html         浮窗界面（自适应、工具栏、聊天框、状态条、设置）
├─ shell/run-float.cmd   启动器（用户双击 / 插件拉起）
├─ tools/setup-webview2.ps1  拉取 WebView2 SDK
├─ tools/fix-bom.ps1     给所有 .ps1 补 BOM（中文脚本必备）
└─ tools/smoke-host.mjs  插件 Host 半的假 ctx 冒烟测试

已知限制 / 路线图

• 仅 Windows（macOS 的排除要换 NSWindow.sharingType，且 ScreenCaptureKit 是否遵守需要单独实测）。
• 聊天框要真正把消息发进会话，还需要接宿主侧“发送到会话”的服务（当前只做只读镜像）。
• 背景效果里的“半透明”依赖整窗 alpha，WebView2 子窗口在这种模式下的观感不如毛玻璃，建议优先用亚克力/云母。
• 还没做托盘图标与全局热键。

License

MIT