前言¶
DeepSeek Harness（DSH）的主窗口適合長時間編排任務；若你經常只是「問一句、看回復、繼續寫代碼」，每次都要找窗口、還原、再最小化，成本不低。社區插件 dsh-desktop-ball（展示名：桌面懸浮球 / Desktop Floating Ball）在 Windows 桌面上放一顆可自定義的小球，單擊即在獨立窗口裏打開完整 DSH 對話，主窗口可以留在後臺。下面介紹它做什麼、怎麼裝、日常怎麼用，以及和主界面、瀏覽器窗口的差異。
這是什麼¶
dsh-desktop-ball 是 DSH 的客戶端類插件，維護者爲 han8421，許可證 MIT，當前包版本 0.18.0（以倉庫 package.json 爲準）。它在 Windows 10/11 上提供系統級置頂懸浮球；聊天層用 WebView2 內嵌 DSH Web 客戶端，沒有地址欄和瀏覽器 chrome。
和常見做法相比，有三點取捨（資料原文表述）：
- 小球是獨立原生窗口，不是主窗口最小化後的替身；DSH 最小化後小球仍在。
- 聊天窗不是普通瀏覽器標籤，而是無 Edge 圖標、無翻譯條的
--app式體驗（優先 WebView2）。 - 不修改 DSH 的
app.asar、不注入 Electron 主進程，升級 DSH 後插件可單獨保留。
核心功能¶
以下能力均來自項目 README 與 package.json 描述，可按需選用。
交互
- 單擊懸浮球：打開或置頂桌面聊天窗口。
- 雙擊：僅隱藏窗口，WebView 與當前對話保留，再點一次恢復，不會重新初始化。
- 拖動小球：位置會記憶；距屏幕邊緣 26px 內鬆手會吸附，留 4px 縫隙。
- 拖動窗口邊或角：縮放聊天窗（最小 360×480），尺寸自動記憶。
對話能力
- 輸入區與主界面一致：模型、權限、推理等級、關閉思考，圖片/附件上傳與拖拽，流式回覆與停止（細節見倉庫
docs/composer.md）。 ask_user_question與approval/request可在小窗內處理；主窗口與快捷窗口誰先響應誰生效。- 快捷窗口使用獨立 DSH 會話，側邊欄可見，可在完整界面繼續；新建會話歸入名爲
ChatWindow的工作區。
外觀
- 圖標支持圖片、GIF、視頻或純色；可裁剪形狀與大小。
- 聊天背景區域、消息顏色、助手名稱可在 右鍵懸浮球 或 DSH 設置 →「懸浮球與外觀」 中調整。
其他
- 鼠標移到球上會預熱加載，點擊時通常已就緒。
- 界面語言可跟隨 DSH、中文或 English。
- 缺少 WebView2 Runtime 時自動退回 Edge / Chrome
--app窗口；macOS / Linux / 瀏覽器無原生小球，用應用內面板與Alt + Q（Harness 窗口內快捷鍵，非系統全局熱鍵）。
安裝與啓用¶
環境要求：Windows 10/11 + DSH Desktop，dsh >= 0.2.1-rc.2 < 0.3.0；原生小球依賴 PowerShell 5.1 與 WPF。
方式 A：插件頁本地路徑（README 推薦）¶
- 打開 DSH Desktop，側邊欄進入 Plugins / 插件。
- 選擇從本地路徑安裝，填入插件目錄的絕對路徑。
- 啓用
dsh-desktop-ball組合包，按提示重啓。 - 重啓後桌面右下角出現懸浮球；DSH 側邊欄不再添加舊的「快捷對話」入口。
方式 B：CLI（在插件包目錄下執行）¶
命令會把當前目錄以 link: 寫入 desktop profile，並把 dsh-desktop-ball 追加到 dsh.profile.bundles：
dsh plugin --profile desktop add .
只檢查配置、不啓動應用：
dsh --profile desktop --dump-config
輸出中應出現 id: quick-chat 與 name: dsh-desktop-ball（內部標識仍沿用 dsh-quick-chat，用於數據目錄與認證 fragment，見倉庫架構文檔）。
方式 C：手動改 profile（進階）¶
插件頁不可用時，需完全退出 DSH Desktop，用 DSH 自帶 pnpm 鏈接目錄並在 %USERPROFILE%\.dsh\profiles\desktop\package.json 的 dsh.profile.bundles 末尾加入 "dsh-desktop-ball"。改前請備份 package.json；完整 PowerShell 示例見 GitHub README 安裝節。
典型用法¶
| 操作 | 效果 |
|---|---|
| 點懸浮球 | 打開 / 置頂桌面聊天窗口 |
| 雙擊懸浮球 | 隱藏聊天窗口（保留 WebView 與對話） |
窗口頂欄 — / 圖釘 / 新建 / ⋯ / ✕ |
最小化到球 / 切換置頂 / 新對話 / 更多 / 關閉 |
Alt + Q |
在主界面展開或收起應用內面板（非 Windows 原生球場景同樣適用） |
Enter / Shift + Enter |
發送 / 換行 |
Esc |
先關菜單，再收起應用內面板 |
桌面入口只有懸浮球；應用內快捷入口爲 Alt + Q。快捷窗口本地 localStorage 最多保留 12 條歷史，完整長會話請在 DSH 完整界面查看。
原理簡述¶
DSH 渲染層插件不能直接創建 Electron BrowserWindow，因此插件分兩塊：index.js 生成帶短期認證 token 的 URL 並啓動 native/ball.ps1（WPF 透明置頂球，監聽 Host PID）；同一 PowerShell 進程內用 WebView2 打開認證 URL，交換 token 後進入聊天面板。狀態與 token 寫在 %LOCALAPPDATA%\dsh-quick-chat\，卸載插件時會刪除；聊天窗使用獨立 profile。
適用場景與注意¶
適合：在 Windows 上長期開着 DSH，又希望用最少窗口切換完成短問答、審批或小範圍改動的開發者。
注意：
- 插件隨當前 DSH 進程權限運行；安裝前請閱讀 源碼 與 MIT 許可證，自行判斷是否滿足安全與合規要求。
- 預熱與隱藏窗口會保留 WebView2 進程（資料稱通常約 100–200 MB），10 分鐘無操作後自動回收。
- 原生懸浮球僅
win32（見package.json的os字段）；其他平臺走應用內面板。 - 社區目錄 SkillHub 插件頁 與 GitHub 由社區維護，與 DeepSeek / 幻方無官方從屬關係；星標等元數據以各站點當時展示爲準（目錄線索爲 2 stars）。
自定義 GIF/圖片後若拖不動小球，README 排查表指出需保證 WPF Ball 網格 Background="Transparent"；更多現象見倉庫 docs/troubleshooting.md。
