dsh-window-drag-probe：在 macOS DSH Desktop 恢復窗口拖拽與診斷

前言¶

在 macOS 上，DSH Desktop 是一個 hiddenInset 窗口，沒有原生標題欄，窗口拖拽完全依賴頁面中通過 -webkit-app-region: drag 聲明的區域。殼層會將 Chrome 行標記爲 data-window-drag，ui-web 的 base.css 將其轉換爲拖拽規則。然而，頁面中大量的交互式 no-drag 選擇器（如按鈕、[tabindex] 容器、ARIA 組件）會覆蓋這些標記。只要有一個 no-drag 元素與 Chrome 行重疊，就會減去該區域的拖拽能力，最終導致頂部拖拽區域變得極窄，無法正常拖動。

這是什麼¶

dsh-window-drag-probe 是一個 DeepSeek Harness (DSH) 客戶端插件，由 adamcjm 維護。它通過在 document.body 追加 DOM 元素來恢復 macOS DSH Desktop 的窗口拖拽功能，並提供一個診斷面板，用於讀取窗口的 DOM 狀態（如 computed app-region、recall 標記、窗口位移記錄）以排查拖拽失效的原因。

核心功能¶

該插件具備以下能力：

• 頂部拖拽帶：在窗口頂部添加一個 16px 寬的透明拖拽帶。該元素以文檔流最後一位插入，並帶有內聯 app-region: drag 樣式，確保不會被頁面中較早的 no-drag 元素覆蓋。
• 診斷面板：提供一個懸浮面板，讀取並展示以下信息：
  • 平臺標記（data-platform）。
  • Chrome 行的 computed app-region 值。
  • recall 標記狀態。
  • 窗口位移記錄（window.screenX/screenY）。
  • 所有 app-region 盒子及其文檔順序。
  • 頂部可拖性矩陣與採樣點命中鏈。
• 本地讀取：僅讀取本地 DOM 狀態，不向外部發送任何數據。

安裝與啓用¶

在安裝前，請確認 DSH Desktop 版本。該插件已驗證在 DSH Desktop 0.2.0-rc.2 / Electron 44.0.0 上運行。DSH 客戶端 API 不向前兼容，如果宿主版本與驗證版本不同，可能導致崩潰。

通過命令行安裝（需要指定 profile）：

dsh plugin --profile <profile> add dsh-window-drag-probe

安裝完成後，需要完全退出 DSH Desktop（使用 ⌘Q）並重新打開，因爲客戶端 bundle 僅在啓動時組裝一次。

典型用法¶

啓用插件後，窗口頂部 16px 區域即爲拖拽帶。該區域在靜止時完全透明，僅在鼠標懸停時顯示微弱的藍色提示。

通過插件頁面打開診斷面板，可以使用以下按鈕進行操作：
1. 重新採集：刷新診斷數據。
2. 插入/移除頂部拖拽帶：動態調整拖拽帶的存在狀態。
3. 復位位置：恢復面板默認位置。
4. 隱藏面板：關閉診斷界面。

適用場景與注意¶

• 適用場景：需要解決 macOS DSH Desktop 窗口無法拖拽的問題，或需要通過診斷面板查看 app-region 渲染細節的開發者。
• 注意事項：
  • 該插件僅作爲變通方案和診斷工具，並非上游修復。如果矩陣顯示可拖拽但仍無法移動，說明問題不在頁面 DOM 層，需等待上游修復。
  • 插件聲明無硬服務依賴（inject: []），不會因缺少服務而掛起。
  • 插件遵循 MIT 許可證。

短結尾¶

dsh-window-drag-probe 通過簡單的 DOM 追加解決了 macOS 下的 CSS 優先級導致的拖拽失效問題，並提供了直觀的調試視圖。對於遇到拖拽異常的開發者，這是一個可靠的排查與修復工具。

• 插件目錄：dsh-window-drag-probe
• 源碼倉庫：adamcjm/dsh-window-drag-probe