前言¶
在 DSH 裏跑大文件下載時，進度往往分散在不同地方：主會話裏一條命令、子代理另起一條、你自己在終端裏用腳本拉取。生態裏已有 dsh-download-progress、dsh-smart-dl、dsh-task-progress、dsh-job-progress 等插件，多數只覆蓋「本會話」或「當前工作區」，README 裏也會寫明這類範圍限制。主會話右側看不到子代理或外部終端裏的同一次下載，排查「到底下完沒有」就要來回切會話或查磁盤。
下面介紹維護者 LemRic1117 的 dsh-download-dashboard（GitHub：LemRic1117/dsh-download-dashboard）。它在對話區右側掛一塊浮窗，只展示 300MB 及以上 的下載，進度、速度、剩餘時間實時更新；數據來源是系統臨時目錄下的狀態快照，因此 不區分是誰發起的下載——主會話、子代理、本機終端裏只要有人按約定寫入狀態，都會出現在同一塊看板上。
這是什麼¶
dsh-download-dashboard 是 DSH 的本地插件包（private: true，未發佈到 npm），當前版本 1.0.1，許可證 MIT，要求 Node >=20。社區目錄 SkillHub 將其歸類爲「記憶」；功能上它解決的是 大文件下載進度的集中、跨上下文可見，而不是會話記憶存儲。
插件分 host 與 client 兩半：index.js 註冊只讀路由彙總狀態目錄；client.js 掛在框架的 shell.overlay 上繪製浮窗。前提是你使用的下載器會把機器可讀快照寫到約定路徑——倉庫自帶的 tools/dl.ps1 即其一；舊版不寫狀態的 dl.ps1 會導致「裝了但浮窗一直爲空」，這是 README 裏最常見的無反應原因。
界面與行爲¶
浮窗停在對話區 右側：不佔聊天寬度、不搶焦點、不擋輸入框。每一行對應一個下載項，包含文件名（懸停顯示完整保存路徑）、百分比與進度條、已下載/總量、速度、剩餘時間。
狀態用顏色區分：藍爲進行中，綠爲已完成，紅爲失敗（並顯示失敗原因）。若下載被 Ctrl+C、進程被殺或斷電等打斷，快照可能長期停在 running；規則是 90 秒無進度更新 則標爲「已中斷」（黃色），保留中斷時的字節數，再過 5 分鐘從面板消失；若只是短暫卡住又繼續，會自動回到進行中。
沒有符合閾值（默認 300MB）的下載時，整個浮窗不渲染，不佔位、不攔截鼠標。完成或失敗後條目保留 5 分鐘 再消失。窗口縮放時位置由 CSS 處理；右側欄打開時浮窗會自動向左讓位。
數據從哪來：狀態目錄與契約¶
配套下載器每次刷新進度，向系統臨時目錄寫入 JSON 快照：
%TEMP%\dsh-downloads\state\<id>.json (Windows)
$TMPDIR/dsh-downloads/state/<id>.json (macOS / Linux)
host 側路由 GET /dsh-downloads/state 彙總該目錄，跳過解析失敗與超過 24 小時的記錄。client 側在有下載進行時約 1.5 秒 拉取一次，空閒時 6 秒，頁面隱藏時暫停輪詢。
狀態文件主要字段如下（路由對外只返回白名單字段，不暴露 URL、會話 id、命令行等）：
| 字段 | 說明 |
|---|---|
id |
唯一標識 |
name |
浮窗顯示的文件名 |
out |
完整保存路徑（懸停提示） |
totalBytes |
總字節；無 Content-Length 時爲 null |
doneBytes |
已下載字節 |
speedBps |
字節/秒 |
etaSec |
剩餘秒數 |
status |
starting / running / retrying / done / failed |
error |
失敗原因 |
startedAt / updatedAt |
ISO 8601；updatedAt 影響何時從面板消失 |
安裝與啓用¶
本包未發佈到 npm，需先取得倉庫目錄，再在 DSH 桌面端或 Web 端側欄 Plugins 頁粘貼該目錄的 絕對路徑（例如 D:\plugins\dsh-download-dashboard），裝完後 刷新頁面（Ctrl+R）。
資料中的獲取方式：
git clone https://github.com/LemRic1117/dsh-download-dashboard
將 tools/dl.ps1 放到 ~/.dsh/tools/dl.ps1 或任意順手位置，大文件下載時用該腳本（PowerShell 5.1+，支持換行式進度、斷點續傳、重試，結束時校驗落盤字節與 Content-Length）：
powershell -NoProfile -ExecutionPolicy Bypass -File tools\dl.ps1 -Url <url> -Out <path> -Resume
插件以當前 DSH 進程權限運行；安裝前建議通讀倉庫源碼並確認 MIT 許可證與上述只讀路由的安全模型是否符合你的環境。
可調參數¶
默認值在 client.js 頂部，改完後重新安裝或等待 HMR：
| 常量 | 默認 | 含義 |
|---|---|---|
MIN_BYTES |
300 MB | 顯示閾值 |
LINGER_MS |
5 分鐘 | 完成/失敗後保留時長 |
ACTIVE_STALE_MS |
90 秒 | 無更新則視爲已中斷 |
POLL_ACTIVE_MS |
1500 ms | 有下載時的輪詢間隔 |
POLL_IDLE_MS |
6000 ms | 空閒輪詢間隔 |
GAP_PX |
12 | 與右邊緣、右側欄間距 |
若希望進度僅限單會話，可將 index.js 頂部的 STATE_DIR 改爲每會話目錄（README 說明爲一行改動）。
安全模型（簡要）¶
路由 只讀，無 POST/PUT/DELETE，也不能代爲下載或取消。訪問需通過迴環地址、Host/Origin 與 Sec-Fetch-Site 等柵欄；對外響應字段白名單，不返回可能帶簽名的下載 URL。狀態目錄位於當前用戶的系統臨時目錄，ACL 限本用戶；「跨會話可見」指的是 同一用戶、同一臺機器上誰往約定目錄寫誰就被展示，並非讀取其他會話私有數據。若 DSH Web 服務綁定到 0.0.0.0，應理解 README 中對 Host 僞造與真正邊界（socket 迴環）的說明。
適用場景與注意¶
適合：經常在 DSH 主會話、子代理和本機終端混用下載器拉 300MB 以上 文件，且希望在同一塊右側浮窗裏看全局進度，而不想依賴「只盯當前會話」的進度插件。
注意：
- 必須有用會寫狀態 JSON 的下載器；僅安裝插件、仍用舊腳本或不寫狀態的命令，看板會空。
- 小文件默認不顯示；要改閾值請改
MIN_BYTES。 - 卸載時在 Plugins 頁關閉或移除 bundle 即可，路由與浮層隨生命週期消失。
- README 標明部分 UI 層級（如 dockkit 浮動面板、皮膚中心）尚未在真機全部驗證。
與同生態插件的差異（據 README「相關項目」）：dsh-download-progress 追蹤 shell 與工作區文件、閾值約 64KB 且偏本會話；dsh-smart-dl 狀態寫在會話 cwd 下；dsh-task-progress 刻意不做跨會話讀取。本插件用全局臨時目錄狀態，補的是 跨會話、跨子代理、跨終端 這一維。
結尾¶
dsh-download-dashboard 把「大文件下載進度」從分散的會話與工作區，收斂到對話區右側一塊只讀浮窗：約定目錄、白名單字段、配套 dl.ps1，主會話與子代理、終端裏的下載只要寫入同一套狀態，就能一起看見。
- 社區目錄：https://www.skillhub.cn/plugins/LemRic1117/dsh-download-dashboard
- 源碼與說明：https://github.com/LemRic1117/dsh-download-dashboard
SkillHub 爲社區插件目錄站點，與 DeepSeek / 幻方無官方從屬關係；DSH 本身遵循「一切皆插件」，具體能力以你本地安裝的 bundle 與下載器爲準。
