前言¶
用 DeepSeek Harness（DSH）跑長任務時，目標 phase、Todo 清單和「待確認 / 已完成未查看」往往都在主窗口裏。最小化或切到別的應用後，要再點開 DSH 才能掃一眼狀態。若你希望在桌面上常駐一塊小區域顯示同一套信息，並在 DSH 裏用開關控制啓停，社區插件 dsh-task-overlay 就是面向這個場景的客戶端擴展。
下面介紹它做什麼、怎麼裝、怎麼用，以及 Windows 桌面浮窗與跨平臺側欄各自負責什麼。
這是什麼¶
dsh-task-overlay 由維護者 gg947919490-byte 發佈，分類爲客戶端插件。它在 DSH 窗口之外放一個桌面懸浮窗，實時展示當前任務狀態；同時在 DSH 側欄提供「桌面浮窗」啓停開關。
桌面浮窗部分基於 PowerShell + WPF，僅支持 Windows。DSH 內的開關與 GUI 向浮窗推送狀態，這部分邏輯隨 DSH 客戶端跨平臺可用（非 Windows 上仍可使用側欄開關與狀態推送，但無桌面 WPF 窗口）。
核心功能¶
目標與 Todo¶
浮窗與 DSH 側同步的內容包括：
- 目標狀態：phase（進行中 / 已暫停 / 受阻 / 已完成）、objective、第 N/M 輪、受阻原因
- Todo 進度：進度條與清單（已完成 / 進行中 / 待辦）
- 提醒：跨所有會話統計——N 個會話等待確認、N 個會話已完成未查看
生命週期行爲¶
- 最小化或關閉 DSH 窗口後，桌面浮窗仍可存在
- DSH 完全退出後，浮窗不會自動消失，但會顯示「DSH 未運行」
DSH 側控制¶
安裝並刷新頁面後，側欄底部會出現「桌面浮窗」開關（綠點表示運行中），用於啓停桌面浮窗進程。
安裝與啓用¶
插件要求 Node >= 20、DSH >= 0.2.0-0（見倉庫 package.json）。許可證爲 MIT。
插件市場（推薦）¶
先安裝市場插件 dshmarket，在 DSH 中打開 設置 → Plugin Market，搜索 dsh-task-overlay 一鍵安裝。
DSH 官方插件頁¶
在安裝框填寫：
github:gg947919490-byte/dsh-task-overlay
或粘貼 Release 中 dsh-task-overlay.tgz 的直鏈。
CLI¶
dsh plugin add gg947919490-byte/dsh-task-overlay
安裝完成後刷新一次 DSH 頁面（F5），側欄底部應出現「桌面浮窗」開關。
典型用法¶
| 入口 | 操作 |
|---|---|
| DSH 側欄底部「桌面浮窗」開關 | 點擊啓停桌面浮窗（綠點=運行中） |
浮窗標題欄 ▾ / ▸ |
展開詳情 / 收成 190×32 迷你膠囊 |
| 拖動浮窗標題欄 | 移動位置（位置與摺疊狀態會記住） |
浮窗 ✕ |
關閉浮窗進程（可在 DSH 側欄開關重新打開） |
不經過 DSH 開關首次啓動：雙擊 desktop\launch-overlay.cmd 或 desktop\launch-overlay.vbs。
開機自啓：將 launch-overlay.vbs 的快捷方式放入 shell:startup。
工作原理（簡要）¶
數據不由宿主從 root 上下文投影（讀不到會話作用域的 todos / goal），而由 DSH GUI 客戶端推送：
DSH GUI（客戶端插件，擁有完整會話狀態）
│ POST 壓縮快照 → 127.0.0.1:45123（2 秒心跳，變化即時推送）
▼
桌面浮窗（獨立 WPF 進程 + 內置 TCP 監聽）
▲
│ 側欄開關 → 同源相對路徑 /task-overlay/control（start/stop/toggle/status）
DSH 宿主（本包宿主半邊）—— start 用 spawn 拉起浮窗，stop 發 {"cmd":"stop"} 優雅關閉
浮窗判斷 DSH 是否存活採用三段式：≤20 秒視爲實時；>20 秒保留最後一幀並標註數據年齡；>150 秒且宿主端口拒連才顯示「DSH 未運行」。
配置與排查¶
常用配置¶
| 位置 | 參數 | 默認 | 說明 |
|---|---|---|---|
dsh/client.js |
BRIDGE_URL |
http://127.0.0.1:45123/task-overlay |
客戶端推送地址，需與浮窗 -Port 一致 |
desktop/task-overlay.ps1 |
-Port |
45123 |
橋接監聽端口 |
| 同上 | -DshPort |
19387 |
宿主端口，用於存活探測 |
| 同上 | -Width |
300 |
展開態寬度（200–520） |
| 同上 | -StateFile |
~/.dsh/task-overlay/desktop-window.json |
位置/摺疊記憶 |
端口被佔用時：修改 -Port，並同步 dsh/client.js 的 BRIDGE_URL。
排查¶
- 最近一幀快照：
~/.dsh/task-overlay/last-payload.json - 浮窗未出現：確認已 F5 刷新、側欄開關爲「開」；或手動運行
desktop\launch-overlay.cmd
安全說明（使用前應瞭解）¶
- 宿主控制接口綁定 webServer 自身監聽地址（默認
127.0.0.1），並校驗請求Origin爲同源或dsh-app://app - 橋接端口（45123）無鑑權，僅綁定迴環；本機其他進程理論上可僞造顯示數據或觸發關閉，屬 README 中說明的已知限制
適用場景與注意¶
適合：在 Windows 上長時間跑 DSH 任務、希望桌面一角常駐目標 / Todo / 會話提醒，又不想反覆切回主窗口的開發者。
注意：
- 桌面 WPF 浮窗僅 Windows；其他系統只能依賴 DSH 內開關與客戶端推送邏輯
- 插件以當前 DSH 進程權限運行；安裝前建議閱讀 GitHub 倉庫 源碼與 MIT 許可證
- 社區目錄 SkillHub 插件頁 爲獨立生態站點，與 DeepSeek / 幻方無官方從屬關係
結尾¶
dsh-task-overlay 把 DSH 會話裏的 goal、Todo 進度和跨會話確認提醒，推到獨立桌面浮窗，並用側欄開關統一管理啓停。Windows 用戶按上述 CLI 或插件市場安裝、刷新後即可試用。
