前言¶
在 DSH 的插件生態中，下載進度曾經依賴右下角懸浮窗展示。這種方式會遮擋會話內容，需要手動拖拽躲避，且與 DSH 自身的側邊欄體系割裂。dsh-sidebar-downloads 是 dsh-better-sidebar 的附屬插件，它將 aria2 的下載進度以正式頁面形式接入側邊欄，與資源管理器、終端等頁面並列，由底座統一管理。
是什麼¶
這是一個把 aria2 下載進度顯示在側邊欄的插件。它是 aria2 下載通道的側邊欄視圖：讀取 aria2-dl.js 寫的任務賬本（~/.dsh/downloads/tasks/*.json），並對帶 gid 的記錄查詢 aria2 RPC 進行補正，不重複實現下載器，只負責將真實狀態渲染成側邊欄頁面。它與 dsh-download-guard 配套使用：守衛負責攔截非 aria2 路徑，本插件負責展示路徑狀態。
核心功能¶
- 實時進度：進度條 + 百分比，按狀態着色（進行中 / 完成 / 失敗 / 已取消）。
- 速度與剩餘時間：MB/s 與 ETA，僅在任務進行中顯示。
- 未知大小的下載：服務器不返回
Content-Length時顯示脈衝條，而非僞造百分比。 - 歷史記錄：完成 / 失敗的任務保留在列表裏，可切換「只看進行中」。
- 字節數取真實磁盤值：無寬度信息的任務以磁盤實際大小爲準，進程被殺掉也不會顯示錯數字。
- aria2 實時補正：對帶
gid的任務直接查 aria2 RPC，--no-wait入隊的陳舊記錄也能顯示真實進度與速度。 - 暫停狀態：手動暫停的任務顯示「已暫停 · 百分比」並以琥珀色區分，計入「N 個已暫停」而非「進行中」。
- 在文件夾中顯示：一鍵在資源管理器中定位已下載文件。
- 操作反饋常駐可見：失敗 / 提示錨定在面板底部浮層，不會被列表滾動帶走。
- 記錄失效自動清理：點擊失效記錄自動移除並說明原因。
- 賬本缺失明確提示：下載記錄目錄不存在時顯示「文件丟失」與具體路徑。
- 移除記錄：只刪除賬本記錄，已下載的文件保留。
- 詳情展開：點擊任意任務行展開：輸出路徑、來源 URL、耗時、錯誤信息。
安裝與啓用¶
前置依賴：已安裝 dsh-better-sidebar（>=0.19.0）。
cd ~/.dsh && dsh plugin --profile <your-profile> add dsh-better-sidebar && dsh plugin --profile <your-profile> add "dsh-sidebar-downloads@github:BeiWay1145/dsh-sidebar-downloads"
安裝後重啓 DSH，然後點擊側邊欄的 + 菜單，選擇「下載」。構建產物已隨倉庫提交，無需在本地編譯。
數據來源與配置¶
本插件讀取 ~/.dsh/downloads/tasks/<taskId>.json 任務賬本（每個下載任務一個 JSON 文件），不抓取網絡、不寫文件。賬本現在只有 一個 寫入方——aria2-dl.cjs（隨 dsh-download-guard 包分發）。
面板與 aria2-dl.cjs 使用同一套環境變量與默認值，兩邊必須指向同一個引擎：
| 變量 | 默認 | 說明 |
|---|---|---|
ARIA2_RPC_URL |
— | 完整 URL；設置後優先於下面兩項 |
ARIA2_RPC_HOST |
127.0.0.1 |
引擎主機 |
ARIA2_RPC_PORT |
16800 |
引擎端口（Motrix Next 開箱即用） |
ARIA2_RPC_TIMEOUT_MS |
1500 |
狀態查詢超時 |
若你的 aria2 用其他端口（例如常見的 6800），改這個變量即可。引擎不可達時，面板會顯示常駐提示（含嘗試的地址與要改的變量名），而不是讓進度靜靜停住。
注意事項¶
- 插件以當前 DSH 進程權限運行，安裝前應檢查源碼與許可證。
- 移除記錄只刪除賬本記錄，不刪除已下載文件。
- 引擎不可達時自動降級爲「照賬本顯示」，不會報錯。
結語¶
dsh-sidebar-downloads 將下載狀態從右下角懸浮窗中解放出來，通過側邊欄統一管理。它解決了歷史記錄保留、未知大小下載顯示、RPC 實時補正等具體問題，與 dsh-download-guard 共同構成下載閉環。
- 源碼倉庫：https://github.com/BeiWay1145/dsh-sidebar-downloads
- 生態目錄：https://www.skillhub.cn/plugins/BeiWay1145/dsh-sidebar-downloads
