dsh-progress-overlay：DeepSeek Harness 的 Windows 始终置顶进度浮窗

前言¶

DeepSeek Harness (DSH) 在执行长任务或复杂工作流时，默认行为往往是静默运行。对于开发者来说，想确认当前是“思考中”、“读取文件”还是“跑测试”，通常需要频繁切换窗口或查看终端日志。dsh-progress-overlay 提供了一个独立的系统级浮窗，将任务状态可视化，让你在不打断当前操作的情况下，掌握任务全貌。

这是什么¶

dsh-progress-overlay 是一个 Windows 平台专用的始终置顶进度浮窗插件。它由 jtt0001 维护，采用 MIT 许可证。

它不依附于 DSH 主界面或 Web UI，是一个独立的 OS 窗口。即使 DSH 主窗口被最小化、被遮挡或切到后台，浮窗依然保持显示。它通过订阅 DSH 的 session/event 事件总线获取数据，仅做展示和简单的审批交互，不会干扰任务执行。

核心功能¶

独立窗口与不抢焦点：使用 WS_EX_NOACTIVATE 属性，状态刷新不会打断你正在输入的内容。唯一例外是用户主动点击“打开 DSH 主窗口”菜单。
真实进度展示：不伪造进度百分比。只有当 DSH 的 todo 事件提供真实的 completed/total 时，才会显示进度；否则仅显示阶段和操作。
多任务并行列表：当有多个任务同时运行时，浮窗会逐条列出每个任务（阶段、标题、步骤、耗时），窗口高度自动增长，首条为主任务。
状态闪烁与颜色：
- 浅蓝：任务完成。
- 红：任务失败/出错，浮窗会自动弹出保持显示。
- 橙：需要审批/确认，浮窗会自动弹出。
全屏自动隐藏与鼠标穿透：全屏应用（浏览器/游戏/PPT）时自动隐藏，退出自动恢复。支持开启鼠标穿透功能，避免遮挡全屏内容。
直接审批：DSH 请求审批时，浮窗会显示“需要确认 + 工具名 + 命令/路径/原因”，并提供“允许/拒绝”按钮，点击即可在浮窗完成回答。
DPI 与多屏支持：支持 PerMonitorV2 DPI 缩放、多显示器工作区定位，以及拖动位置的持久化保存。

安装与启用¶

通过 DSH CLI 安装插件。

dsh plugin --profile desktop add github:jtt0001/dsh-progress-overlay
# 安装完成后重启 DeepSeek Harness Desktop

插件会自动尝试加载 resources/dsh-overlay.exe。如果系统安全软件拦截了无签名的 exe，插件会自动回退到 PowerShell 内存编译模式（功能等价，启动稍慢）。此时无需手动处理，只需确保插件目录未被安全软件隔离。

配置与交互¶

安装后，在 DSH 的设置界面中找到 overlay 配置项。

设置项说明¶

键	默认值	说明
`enabled`	true	总开关
`opacity`	0.92	浮窗卡片不透明度
`position`	remember	位置 (top-right / top-left / bottom-right / bottom-left / remember)
`compactMode`	false	启动即折叠单行显示
`autoHideOnComplete`	true	完成后显示 ✓ 数秒自动隐藏
`autoHideDelayMs`	5000	完成后停留时长（毫秒）
`hideOnFullscreen`	true	全屏应用时隐藏
`clickThrough`	false	鼠标穿透（开启后不可拖动/点按钮）
`showElapsedTime`	true	显示已运行时长
`showPercentage`	true	有真实进度时显示百分比
`showTitle`	true	显示任务/会话标题

交互操作¶

移动：拖动卡片空白处可移动位置，松手后自动校验并保存到当前显示器工作区。
折叠/隐藏：使用 - 折叠/展开，使用 ✕ 隐藏浮窗（任务继续运行）。
右键菜单：点击右键可快速调节透明度、开关鼠标穿透、开关自动隐藏等（本地即时生效）。

技术实现与限制¶

平台限制：仅支持 Windows 平台。浮窗本体基于 .NET Framework 4.8 WPF 构建，Windows 10/11 系统自带该运行时。
数据来源：数据来源于 DSH 会话事件总线 (session/event)，与内置的 dsh-tauri-pet 共享数据源。
安全软件：360 等安全软件可能将无签名的 dsh-overlay.exe 标记为威胁并清理。若遇到此问题，请将插件目录加入信任区，或依赖 PowerShell 兜底宿主。
全屏覆盖：对于 DirectX 全屏模式（如 DX 全屏游戏），系统层级由游戏决定，插件无法强制覆盖。

验收¶

插件包含完整的单测与集成测试。

# 归约器单测
node test/state.test.js

# 路由注册与审批桥接测试
node test/smoke-apply.mjs

运行测试可验证事件归约逻辑、审批按钮的回写逻辑以及浮窗与 DSH 主进程的通信是否正常。