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 主進程的通信是否正常。