前言¶
如果你在用 DSH（DeepSeek Harness），並且桌面裝了 Wallpaper Engine，大概率遇到過這種情況：創意工坊裏囤了幾百張壁紙，但 DSH 的 Web 界面背景還是默認那一張，兩邊互不相通。手動導出圖片再改配置太繁瑣，動態壁紙（視頻、3D 場景）更沒法直接用。
dsh-wallpaper-engine 解決的就是這個問題：它讀取本機 Wallpaper Engine 的素材庫，在 DSH 界面裏提供一個壁紙選擇面板，選中即可一鍵應用到 DSH 背景，還能按壁紙亮度聯動切換 DSH 的深色 / 淺色主題。
這是什麼¶
dsh-wallpaper-engine（npm 包名 @marlonlau/dsh-wallpaper-engine，當前版本 0.1.2）是 marlonLau 開發的 DSH Web GUI 換背景插件，採用 MIT 許可證，源碼託管在 GitHub：https://github.com/marlonLau/dsh-wallpaper-engine。
它的定位一句話可以說清：以本機 Wallpaper Engine 的圖片 / 視頻素材爲源，一鍵切換 DSH 界面背景。注意它目前只支持圖片和視頻兩種素材，3D 場景和網頁壁紙只能取其 preview.jpg 做靜態展示。
核心功能¶
壁紙選擇面板：在 DSH 側邊欄底部按鈕打開面板，以縮略圖網格展示壁紙庫，支持搜索。
兩種素材來源，通過 GET /we/list?source=auto 自動選擇：
- Wallpaper Engine Web API（默認
http://localhost:26384/api/wallpaper/list）：僅在 WE 正在運行且其本地 Web 服務可用時生效； - 目錄掃描（回退）：當 API 未啓用或不可用時自動回退。它讀取註冊表和
libraryfolders.vdf自動發現所有 Steam 庫，掃描steamapps/workshop/content/431960/*（創意工坊）和steamapps/common/wallpaper_engine/projects/myprojects/*（本地項目），解析其中的project.json。
一鍵應用：圖片應用爲 CSS 背景；視頻應用爲靜音循環的 <video>；3D 場景 / 網頁壁紙用其 preview.jpg 靜態展示。應用後 App 框架與側邊欄變爲半透明加毛玻璃（backdrop-filter），壁紙從底下透出。
明暗跟隨：勾選後按壁紙亮度自動調用 theme.setTheme 切換 DSH 深 / 淺色主題。
持久化：當前壁紙與設置存 localStorage，刷新不丟；額外目錄等配置存 $DSH_HOME/storages/dsh-wallpaper-engine.json。
隨機與恢復：支持一鍵隨機換壁紙，或一鍵恢復 DSH 默認背景。
安裝與啓用¶
推薦從 npm 安裝：
dsh plugin --profile web add @marlonlau/dsh-wallpaper-engine
這條命令會寫入依賴，並自動把包追加進 dsh.profile.bundles，隨後重啓 dsh web 生效。之後只改客戶端代碼時，刷新頁面即可。
如果要開發調試，可以從 GitHub 倉庫安裝（需要 Node.js >= 18 與 git）：
# 1. 克隆倉庫
git clone https://github.com/marlonLau/dsh-wallpaper-engine.git
cd dsh-wallpaper-engine
# 2. 把插件包鏈接進 web profile（單包、零依賴、無構建步驟）
dsh plugin --profile web add "link:$PWD"
# 3. 重啓 dsh web
dsh web
等價的手動方式：在 profile 的 package.json 里加依賴 "@marlonlau/dsh-wallpaper-engine": "link:<倉庫絕對路徑>"，並把它追加進 dsh.profile.bundles，然後 pnpm install。
典型用法¶
插件安裝後主要交互有三種：選壁紙、看診斷、改配置，全部通過宿主路由暴露：
| 路由 | 說明 |
|---|---|
GET /we/list |
壁紙列表，source=auto\|api\|scan，refresh=1 強制重掃 |
GET /we/status |
API 可用性 / 根目錄 / 數量診斷 |
GET /we/file?p=… |
媒體文件（圖片 / 視頻，支持 HTTP Range） |
GET /we/preview?p=… |
預覽縮略圖 |
GET/POST /we/config |
配置額外目錄、API 地址、API 開關 |
日常操作在界面上完成：側邊欄底部按鈕打開面板，搜索或翻頁選中壁紙，點擊應用即可。如果壁紙列表不對，可以用 GET /we/status 查看當前走的是 API 還是目錄掃描、根目錄在哪、掃到了多少張，再用 POST /we/config 補充額外目錄或調整 API 地址與開關。
開發者視角¶
插件分爲兩個半區：
- 宿主半區
lib/index.js（Node 端，inject: ['webServer']），負責路由、目錄掃描和文件服務； - 客戶端半區
lib/client.js（瀏覽器端，inject: ['theme', 'workspaces']，手寫 CJS bundle，通過window.__ModuleLoader__.load(...)加載），負責面板與背景渲染。
改動規則很直接：改 lib/client.js 後刷新頁面即生效，改 lib/index.js 需要重啓 dsh web。整個包零依賴、無構建步驟，想讀懂或改造源碼的門檻不高。
適用場景與注意¶
適合的人羣很明確：Windows 上同時使用 DSH Web GUI 和 Wallpaper Engine、想讓界面背景動起來（或至少換掉默認背景）的用戶。如果你的創意工坊壁紙大多是 3D 場景或網頁類型，要知道這些目前只能以 preview.jpg 靜態展示，動態效果不會搬到 DSH 裏。
幾點安全與邊界說明：
- 所有宿主路由有迴環 / 內網信任圍欄；文件路由只允許壁紙項目目錄內的媒體擴展名，不會越界讀文件。
- Wallpaper Engine Web API 僅在 WE 運行且本地 Web 服務可用時生效，否則自動回退目錄掃描，不需要手動切換。
- 和所有 DSH 插件一樣，插件以當前
dsh進程的權限運行。安裝前建議查看源碼與許可證（本項目爲 MIT），確認沒有問題再裝。
結尾¶
dsh-wallpaper-engine 做的事不復雜，但路徑選得務實：優先複用 Wallpaper Engine 自帶的本地 Web 服務，不可用就自己掃目錄，素材類型按圖片、視頻、3D / 網頁三級降級處理。對於想在 DSH 界面上用上自己壁紙庫的用戶，這是一條現成的路。
- 目錄頁：https://www.skillhub.cn/plugins/marlonLau/dsh-wallpaper-engine
- 源碼：https://github.com/marlonLau/dsh-wallpaper-engine
