前言¶

智能體開發時，我們經常需要盯着進程狀態：輪次走到第幾步、當前在執行什麼工具、todo 完成度、審批是否在等。DSH 的任務進度是持久化在日誌裏的，要查就得去翻日誌或看 UI，不夠順手。

大肥魚桌面掛件（Fat Fish desktop widget）給桌面加了一隻「常駐」的魚娘：它是一個懸浮在 Windows 桌面上的透明窗口，始終置頂，獨立於 DSH 進程，關掉 DSH 窗口甚至程序，魚還在桌面上繼續顯示當前會話的進度和審批提醒。

插件定位¶

• 維護者：danheng383-commits
• 分類：客戶端
• 插件：danheng383-commits/dsh-widget

這是一款 Windows 桌面掛件插件，通過讀取本機 state.json 來展示最近活躍會話的輪次、步驟、工具調用、todo 進度、後臺任務與團隊任務，並提供審批提醒和窗口拉起功能。

核心功能¶

桌面級置頂¶

掛件是一個獨立的 WinForms 分層窗口（per-pixel alpha），浮在所有應用之上，不屬於 DSH 窗口。窗口最小化或關閉 DSH，都不會帶走這隻魚。

實時進度¶

DSH Host 會把最近活躍會話的進度寫入 %LOCALAPPDATA%\dsh-fat-fish\state.json。掛件讀取該文件，顯示當前階段（排隊 / 思考 / 輸出 / 執行工具 / 完成 / 出錯）、輪次、步驟、工具次數、耗時。

當前工具與目標¶

展開面板會顯示當前工具名（如 grep、pwsh、todo_write 等）以及目標參數，工具名支持中文別名。

任務清單¶

面板顯示 todo 的完成度百分比、進度條與逐條清單（✓ / ◐ / ○）。

更多上下文¶

• 後臺任務（jobs）：顯示正在跑的子任務及其狀態。
• 會話目標：當前在第 n/m 輪。
• 團隊任務：展示團隊任務信息。
• 其它正在跑的會話數：如果有多個會話在跑，會提示總數。

交互¶

• 拖動：按住魚拖到任意虛擬屏幕位置，位置會自動記住。
• 展開/收起：單擊魚，或在右鍵菜單中選擇「展開詳情 / 收起」。
• 大小：右鍵菜單裏提供「大小 → 小 / 中 / 大」。掛件內部有一個全局縮放 $script:UiScale（默認 1.12），幾何與字號一起等比放大。
• 歸位：右鍵菜單「回到默認位置」（默認在右下角，避開其它掛件）。
• 退出：右鍵菜單「退出」，或結束進程 powershell.exe（窗口標題 FatFishDesktop）。
• 狀態存儲：位置與狀態保存在 %LOCALAPPDATA%\dsh-fat-fish\widget.json。

關掉 DSH 後的行爲¶

• 超過 7 秒沒有新數據，氣泡會變成「DSH 未運行 / 大肥魚在桌面上等你回來」，魚繼續留在桌面。
• DSH 再次啓動後，掛件會自動接上數據。

審批提醒¶

DSH 將審批請求作爲持久化事件（approval/asked / approval/decided）寫入日誌，Host 讀取這兩類事件，不攔截 approval/request 瀑布。

• 有待審批項時：氣泡變琥珀色卡片，標題「需要你審批」，下方顯示工具名 + 原因。如果收起，卡片本身就是彈窗。
• 魚右上角掛一個琥珀色的「!」角標。
• 展開面板頂部會插入「等待你審批」的提示區。
• 點卡片會把 DSH 窗口提到最前，直接去處理「允許/拒絕」。
• 新審批出現時會播一次系統提示音；右鍵菜單「審批提示音」可關閉（持久化在 widget.json 的 alertSound）。
• 審批有結果時會閃 6 秒確認：approval/decided 的 outcome 映射成「已允許 / 已拒絕 / 已取消 / 審批未完成」，面板標題和氣泡變色，魚上角標換成 ✓ / ✗ / —。
• 卡片、角標隨後消失；回合結束或 DSH 停止寫入時也會自動清理。

安裝與啓用¶

本插件通過 plugin_manager 安裝，安裝後 Host 會在加載插件後的 1.5 秒內自動拉起桌面掛件。

{
  "name": "@local/dsh-fat-fish-widget",
  "version": "0.4.0",
  "description": "大肥魚桌面掛件:一隻常駐 Windows 桌面的懸浮魚娘,始終置頂顯示當前會話的輪次、步驟、工具調用、todo、後臺任務與團隊任務;可自選開機自啓與關閉 DSH 後是否保留。",
  "type": "module",
  "repository": {
    "type": "git",
    "url": "git+https://github.com/danheng383-commits/dsh-widget.git"
  },
  "homepage": "https://github.com/danheng383-commits/dsh-widget#readme",
  "dsh": {
    "bundle": {
      "patch": "./cordis.patch.yml"
    }
  }
}

安裝命令示例（需要使用當前 profile 的 plugin_manager）：

# 在本目錄執行（target 爲本目錄絕對路徑）
dsh plugin_manager install_bundle ./danheng383-commits-dsh-widget

安裝後，掛件由 Host 通過 desktop\launch-widget.vbs（wscript → WScript.Shell.Run）靜默啓動。這種方式與直接 spawn 不同，它將進程交給外殼管理，從而能在 DSH 關閉後依然留在桌面。

典型用法¶

• 隨 DSH 啓動：打開 DSH，1.5 秒內桌面掛件會自動出現。
• 拖拽位置：按住魚拖動到合適位置，自動保存。
• 展開/收起：單擊魚或右鍵選擇。
• 調整大小：右鍵 → 大小 → 小 / 中 / 大。
• 設置開機自啓：右鍵 → 「開機自啓」打勾/取消。打勾會在啓動文件夾創建指向 desktop\launch-widget.vbs 的快捷方式，取消則刪除。
• 控制掛件是否在 DSH 退出後保留：右鍵 → 「DSH 退出後保留懸浮窗」打開（默認）/ 關閉。關閉後掛件會在檢測到 Host 停止寫快照約 30 秒後退出。
• 調試：在 %LOCALAPPDATA%\dsh-fat-fish\ 創建空文件 debug-on，會輸出每個會話事件和快照寫入日誌到 debug.log。刪除 debug-on 即停止。

適用場景與注意¶

• 平臺：只支持 Windows（WinForms + 分層窗口 API），其它平臺不啓動掛件。
• 掛件是置頂窗口，會覆蓋全屏遊戲或全屏視頻，需要時可右鍵退出或臨時收起。
• 進度展示的是「最近活躍的會話」：多個會話同時跑時，面板會提示其它會話數，但只詳細展示最活躍的那個。
• 掛件不聯網，不讀取會話日誌，只讀取本機 state.json。
• 插件以當前 DSH 進程權限運行，安裝前建議查看源碼與許可證。

短結尾¶

大肥魚桌面掛件通過透明置頂窗口，把 DSH 的任務進度和審批信息直接搬到桌面上，適合需要持續監控智能體執行狀態、及時處理審批的開發者。更多信息見目錄頁與 GitHub 倉庫。