前言¶

DSH 網頁端跑久了，界面就是一片實色：畫布底色、側邊欄底色都是固定的語義色 token。想換張背景圖，通常只有兩條路：要麼改主題文件覆蓋 --dsw-alias-bg-base、--dsw-specific-sidebar-fill，改完哪些組件會跟着變、深淺色模式各是什麼效果，往往要靠反覆試；要麼乾脆不動，接受默認外觀。

dsh-wallpaper 走的是另一條路：照片放在頁面最底層的固定圖層上，畫布和側邊欄改成半透明語義色讓圖透出來，其餘卡片、按鈕、文字配色原樣不動。所有參數集中在「設置 → 壁紙」裏實時調。下面介紹它的定位、安裝和用法。

這是什麼¶

dsh-wallpaper 是 DSH 生態裏的一個網頁端客戶端插件，維護者是 dingzhen-114514，倉庫在 https://github.com/dingzhen-114514/dsh-wallpaper ，社區目錄頁在 https://www.skillhub.cn/plugins/dingzhen-114514/dsh-wallpaper 。它解決的問題很窄：給 DSH 網頁端（桌面版或 dsh web）加一張照片背景，並提供一組不用重啓就能生效的實時設置。

它屬於「趣味換裝」分類，倉庫當前 1 star，license 爲 MIT。

核心功能¶

下面是 README 中列出的能力，均可覈對。

• 真實背景圖：一個 background-size: cover 的固定圖層，窗口縮放、頁面滾動都不跑位。
• 只覆蓋兩個語義色：畫布 --dsw-alias-bg-base 和側邊欄 --dsw-specific-sidebar-fill。組件自身的卡片、按鈕、文字配色不動，深淺色主題各自保留原色相。
• 五個可調參數：畫布透明、側邊欄透明、薄紗、亮度、柔化（模糊）。拖動即時生效，防抖後寫入 Host。
• 換圖：點「選擇圖片…」或把圖片拖進面板，支持 webp / png / jpg / jpeg / gif / avif / bmp，單張上限 24 MB，按擴展名給出正確 Content-Type。
• 一鍵恢復內置圖：清空當前圖片，回到倉庫自帶的 assets/placeholder.webp。
• 失敗隔離：Host 半邊零靜態 import、逐條路由 try/catch；瀏覽器半邊聲明 inject: ['slots']。任何一步失敗只會讓設置頁或背景消失，插件條目照常激活。

安裝與啓用¶

前置條件是 DSH 0.2.1 及以上，桌面版和 dsh web 都適用，插件跑在網頁端。

README 給出的安裝方式是把倉庫克隆到本地，然後用自帶的腳本掛進 profile：

git clone https://github.com/dingzhen-114514/dsh-wallpaper.git
cd dsh-wallpaper
node scripts/install.mjs            # 默認裝進 desktop 配置
# node scripts/install.mjs --profile work    # 或者指定另一個 profile

腳本只做三件事，全部是本地目錄操作，不發佈到 npm：

1. 在 ~/.dsh/profiles/desktop/node_modules/@local/dsh-wallpaper 建一個指向本倉庫的目錄鏈接（不復制文件，改代碼立即生效）；
2. 給 profile 的 package.json 加上 "@local/dsh-wallpaper": "link:<本倉庫路徑>"；
3. 把包名加進 dsh.profile.bundles，包內自帶的 cordis.patch.yml 會在啓動時插入加載行。

然後要重啓 DSH。 配置裏的 bundle 列表只在啓動時讀取、不監聽變化；重啓後打開「設置 → 壁紙」。包名帶 @local/ 作用域，是因爲它通過 link: 裝進 profile、不發佈到 npm，clone 到哪個目錄都行。

卸載同樣走腳本：

node scripts/install.mjs --remove   # 移出 bundles、刪掉依賴與鏈接

重啓 DSH 即恢復原樣。個人設置仍在 ~/.dsh/wallpaper/，想徹底清掉連這個目錄一起刪。

典型用法¶

打開「設置 → 壁紙」，界面是下面的一組控件，括號裏是 README 給出的默認值：

「圖片」卡片裏可以預覽當前圖、選擇新圖（或拖放）、恢復內置圖。底部狀態行會顯示「已保存」「已恢復內置圖」這類結果。

換成自己的圖¶

README 給了三種方式，任選其一：

1. 設置頁裏點「選擇圖片…」或拖放，存到 ~/.dsh/wallpaper/wallpaper-<時間戳>.<擴展名>；
2. 把圖直接存成倉庫根目錄的 wallpaper.webp，這個文件已被 .gitignore 忽略，不會誤提交別人的圖；
3. 不想要內置圖時什麼都不用做，assets/placeholder.webp 自動兜底。

實現上值得留意的一點¶

照片本身在固定層，應用本體在上一層。瀏覽器半邊把設置寫成 documentElement 上的 CSS 變量：--dw-canvas-a、--dw-sidebar-a、--dw-veil-a、--dw-brightness、--dw-blur、--dw-image。樣式表用這些變量合成淺色（rgb(255 255 255 / var(--dw-canvas-a))）和深色（rgb(21 21 23 / var(--dw-canvas-a))，由 body[data-ds-dark-theme] 區分）兩版底色。因爲只改語義別名，任何依賴 --dsw-alias-* 的組件都會自動得到正確的對比度，不需要逐個組件打補丁。

圖片 URL 帶 ?rev=<mtime>-<size>，換圖後瀏覽器不會拿舊緩存。

Host 和瀏覽器兩邊的配合大致如下。數據落在 ~/.dsh/wallpaper/state.json（$DSH_HOME 優先），啓動診斷寫 ~/.dsh/wallpaper/boot.log。插件提供四條路由：

state.json 的字段是 enabled、image（絕對路徑或 null）、canvas、sidebar、veil（0–100）、brightness（50–150）、blur（0–12）。

README 還寫了兩條寫 DSH 客戶端插件時的硬約束，值得單獨記：

1. 瀏覽器半邊必須在自己導出的插件對象上寫 inject: ['slots']。Cordis 的 context 是代理，讀未聲明的服務屬性會直接拋 cannot get property "slots" without inject，這個異常會讓整個客戶端條目激活失敗，桌面殼報成 web boot: 1 entry did not activate，頁面起不來，只能禁用插件。
2. Host 半邊不要寫靜態 import，路由逐條 try/catch。某條路由註冊失敗時插件仍然激活，錯誤落在 boot.log，不至於把裝飾性插件變成啓動阻斷。

排錯入口有兩個：~/.dsh/wallpaper/boot.log 看 Host 激活與每條路由的結果；桌面殼的網頁端啓動崩潰報告在 %APPDATA%\@deepseek-ai\dsh-desktop\logs\crash-*-web-boot.log。

適用場景與注意¶

適合的場景很明確：想在 DSH 網頁端或個人配置裏放一張背景圖，同時不希望卡片、按鈕、文字的顏色被背景對比度帶跑。它只動畫布和側邊欄兩處語義色，改的是視覺氛圍，不是主題。

安裝前需要注意幾件事：

• 這個插件是社區插件，與 DeepSeek / 幻方沒有官方從屬關係，目錄頁也是獨立站點。插件以當前 DSH 進程的權限運行，會讀寫 ~/.dsh/wallpaper/ 下的文件並提供 HTTP 路由，安裝前應讀完源碼、確認許可證（MIT）和 files 裏打包的腳本。
• README 聲明的驗證環境是 Windows + DSH 桌面版 0.2.1-rc.5（Electron 44 / Node 24）。Host 半邊只用 ctx.webServer.register 與 node:fs，路徑全部走 DSH_HOME，據稱 dsh web 與桌面版通用，但其他平臺沒有列出驗證結論。
• 安裝腳本在非 Windows 上退化爲普通符號鏈接，junction 類型僅在 Windows 生效。
• 如果同時裝了別的改主題插件，兩邊都寫 --dsw-alias-bg-base，最終效果取決於加載順序。
• 倉庫自帶的 assets/placeholder.webp 是程序生成的漸變圖，可直接使用。自己提交圖片時只提交擁有權利的文件。

結尾¶

dsh-wallpaper 做的事情很小：一張照片、兩個語義色、五個可調參數，換來的是一個不用重啓就能反覆試的網頁端背景。它把失敗面控制在裝飾層，不會把啓動流程拖住，這纔是它真正值得借鑑的地方。

目錄頁：https://www.skillhub.cn/plugins/dingzhen-114514/dsh-wallpaper

GitHub：https://github.com/dingzhen-114514/dsh-wallpaper