前言¶
DSH 的界面背景默認是固定的。想在開發工作臺裏放幾張自己的圖片、或者一段視頻循環播放，通常要手改主題文件和 CSS，改完順序、間隔、透明度也都沒處調。dsh-bg-carousel 把這件事做成了一個標準插件：把媒體文件丟進一個目錄，界面背景就能自動輪換，目錄、順序、間隔、透明度都在面板裏配置。
下面介紹這個插件的定位、核心功能、安裝步驟和典型用法。
這是什麼¶
dsh-bg-carousel 是一個標準 dsh bundle 插件，由 Jonah-Wu23 維護，當前版本 v0.3.0，npm 包名 @jonahwu/dsh-bg-carousel，代碼採用 MIT License。一句話定位：圖片與視頻自動輪換的 DeepSeek Harness 界面背景。
它適配 dsh v0.1.2-rc.1 的 web 界面，架構分兩端：
- 宿主端掃描媒體目錄，通過 webServer 提供媒體路由與 API；
- 客戶端在側邊欄底部註冊「背景」入口，負責控制面板與背景渲染。
核心功能¶
圖片與視頻背景¶
圖片支持 JPEG、PNG、WebP、SVG、GIF，按 body 背景渲染，表面疊一層壓暗色，隨亮暗主題自動取值。視頻支持 MP4、WebM、MOV、HLS、FLV，靜音自動播放，以 cover 方式鋪滿視口。
格式兼容性有環境差異：HLS 由 Safari 原生支持；FLV 需要 MSE 類擴展（如 flv.js）；Chromium 環境下這兩類文件自動跳過，輪播繼續。MOV 能否播放取決於容器內編碼，H.264 通常可以播放。
混合輪換¶
圖片和視頻在同一個隊列裏輪換，推進規則如下：
- 間隔短於視頻時長：截斷當前視頻並切換下一個；
- 間隔長於視頻時長：視頻播完後立即切換；
- 視頻卡死：由定時器兜底推進。
環境限制自動播放時，視頻停在首幀，定時器照常推進；無法解碼的文件自動跳過並在瀏覽器控制檯記錄原因；全部媒體失敗時暫停輪播並在面板提示。
順序與透明度¶
縮略圖支持拖拽排序，順序立即生效並持久化到服務端設置，新增文件按字母序排在末尾。「面板不透明」滑桿即時調整界面 token 透明度，對圖片和視頻同樣生效。
目錄與縮略圖¶
媒體目錄可以在面板內手輸，也可以點「選擇」按鈕調起宿主原生目錄選擇器（Windows 爲系統文件夾對話框），支持絕對路徑與工作區相對路徑。「打開文件夾」由宿主在系統文件管理器中打開當前媒體目錄，不依賴瀏覽器 file:// 鏈接。目錄不可用時回退默認目錄（工作區 backgrounds）並提示，輪播照常。
大圖在宿主端按 320px 生成 JPEG 縮略圖緩存（Windows 走 PowerShell System.Drawing），緩存目錄在 ~/.dsh/bg-carousel/thumbs/；縮略圖懶加載 + 異步解碼，上百張高清圖面板也不卡。
安裝與啓用¶
插件需要 webServer 與 client UI，建議安裝到 web profile（或任何包含 @deepseek-ai/dsh-web-app 的 profile）；裝到其他 profile 時插件靜默待命，不影響啓動。「選擇目錄」與「打開文件夾」依賴 dsh v0.1.2-rc.1 組合的 directoryPicker / openWorkspacePath 能力，插件不兼容 dsh v0.1.1-rc2 與 v0.1.2-alpha.1 之前的版本，安裝前先確認 dsh 版本。
以下安裝命令需要 pnpm 在 PATH 中，三種方式任選其一，每次只執行一條。
git 源安裝：
dsh plugin --profile web add github:Jonah-Wu23/dsh-bg-carousel
或者直接裝 GitHub Release 裏的 tgz：
dsh plugin --profile web add https://github.com/Jonah-Wu23/dsh-bg-carousel/releases/download/v0.3.0/jonahwu-dsh-bg-carousel-0.3.0.tgz
也可以用本地路徑，<...> 處填 tgz 文件路徑或插件目錄路徑：
dsh plugin --profile web add <本地 tgz 或目錄路徑>
安裝後重啓 dsh 生效。卸載執行：
dsh plugin --profile web remove @jonahwu/dsh-bg-carousel
想從源碼構建，需要一份 dsh 源碼 checkout，PATH 中有 bash 與 Node.js，然後執行：
DSH_CHECKOUT=<dsh 源碼 checkout> bash scripts/build.sh
腳本使用 checkout 內的 tsc 編譯宿主端，tsdown 打包 client。運行時零新增依賴：client 只 require 平臺種子模塊 react，未引入 hls.js 或 flv.js，環境不支持的格式自動跳過。
典型用法¶
1、把圖片和視頻複製到媒體目錄。默認是工作區的 backgrounds 目錄，可以在面板裏修改。注意大小限制：圖片上限 64 MiB、視頻 256 MiB。
2、重啓 dsh 後，點擊側邊欄底部的「背景」入口打開控制面板，面板會自動加載當前目錄的媒體清單。
3、點擊縮略圖切換背景；拖拽縮略圖排序；勾選「自動輪播」按設定間隔循環（intervalMs 取值 1500–120000 毫秒）；拖動「面板不透明」滑桿調整界面透明度（panelOpacity 取值 0.1–0.95）。
服務端 API¶
做二次開發或排查問題時，宿主在 {workspaceRoot} 下掛載了這些媒體路由與 API：
| 方法 | 路徑 | 說明 |
|---|---|---|
| GET | /dsh-bg/img/<name> |
按文件名返回媒體字節，緩存 1 小時，圖片上限 64 MiB、視頻 256 MiB |
| GET | /dsh-bg/thumb/<name> |
返回 320px JPEG 縮略圖，未命中先回退原圖字節並後臺補生成 |
| GET | /dsh-bg/api/list |
返回 images、videos、media（混合清單）、dir、dirError 與設置 |
| POST | /dsh-bg/api/image |
按文件名返回 base64 data URL，限制 12 MiB，兼容舊版 client |
| POST | /dsh-bg/api/settings |
更新 intervalMs（1500–120000）、enabled、panelOpacity（0.1–0.95）、mediaDir、order |
media 爲 {name, kind: 'image' | 'video'}[]，已按 order 排序；dirError 非空表示配置目錄不可用、已回退默認目錄。
適用場景與注意¶
適合的人羣：想在 DSH 工作臺放個人化背景又不想手改主題文件的開發者；有一批壁紙想按順序或定時間隔輪換的；想在背景放一段循環視頻的。
使用前注意：
- 插件以當前 dsh 進程權限運行，會讀取媒體目錄、寫入縮略圖緩存與服務端設置。安裝前建議檢查源碼與許可證（MIT），確認無誤再裝；
- 插件基於 dsh v0.1.2-rc.1 開發，舊版本 dsh 下「選擇目錄」與「打開文件夾」不可用，甚至無法正常安裝；
- 視頻格式的可播性取決於瀏覽器環境，Chromium 下 HLS 與 FLV 會被自動跳過。
結尾¶
dsh-bg-carousel 用一個媒體目錄加一個控制面板，把 DSH 界面背景的替換、圖片視頻混合輪播、排序和透明度這幾件事串了起來，輪換推進和格式兼容的處理也比較細。裝好插件、把文件複製進目錄就能用。
- 社區插件目錄（獨立站點）：https://www.skillhub.cn/plugins/Jonah-Wu23/dsh-bg-carousel
- GitHub 倉庫：https://github.com/Jonah-Wu23/dsh-bg-carousel
