前言¶
DeepSeek Harness（DSH）使用者在本地調試或日常使用 dsh web 時，有時只希望更換背景，不想直接改前端代碼。@starryhui/dsh-background 是一個自定義 DSH WebUI 背景插件，由 StarryHui 維護，用於把本地圖片文件夾接入 DSH WebUI 的背景設置。
它把圖庫掃描、裁切、透明度、模糊、輪播等選項集中到「設置 → 背景」中，調整即時生效，重啓後配置仍保留。
插件定位¶
@starryhui/dsh-background 的許可證是 MIT。它面向已經安裝 DeepSeek Harness 並且 dsh web 可正常啓動的環境。
安裝後，插件會讀取本地圖片文件夾，並把配置保存在 settings.yaml 的 background 命名空間，因此重啓後不丟。
核心功能¶
圖庫背景¶
插件支持指定本地文件夾，自動掃描其中的圖片，支持的文件類型包括：
png/jpg/webp/gif/bmp/avif/svg
選擇圖片時支持縮略圖點選，也支持「隨機一張」。
自由拉伸裁切框¶
在預覽圖上，可以拖拽 4 角 / 4 邊進行自由拉伸，也可以在框內平移。調整過程會即時預覽背景。
效果調節¶
可以調節以下項目：
- 水平縮放
- 垂直縮放
- 位置
- 背景不透明度
- 面板透明度
- 高斯模糊
顯示模式¶
插件提供三種顯示模式：
cover：鋪滿裁剪contain：完整顯示fill：拉伸填充
多圖交叉淡化輪播¶
如果圖庫中有多張圖片，切換時會使用雙圖層交叉淡化過渡。也可以選擇按圖庫順序定時切換。
即時生效¶
所有調整都會即時刷新背景。配置持久化在 settings.yaml 的 background 命名空間，重啓後不丟。
安裝與啓用¶
npm 安裝¶
先使用 npm 包安裝。下面命令把 @starryhui/dsh-background@latest 安裝到 web profile：
dsh plugin --profile web add @starryhui/dsh-background@latest
安裝完成後重啓 dsh web：
dsh web
然後打開「設置 → 背景」，配置圖庫與效果。
裝到舊版本時的處理¶
如果安裝到了舊版本，可能與 pnpm 11+ 的發佈年齡門禁有關。pnpm 11+ 默認的發佈年齡門禁 minimumReleaseAge 內置 24 小時，可能把新發布版本靜默隔離。
可以在 profile 的 pnpm-workspace.yaml 中設置：
minimumReleaseAge: 0
或者把 @starryhui/* 加進 minimumReleaseAgeExclude。
完成配置後，再執行更新命令：
dsh plugin --profile web update @starryhui/dsh-background@latest
從 GitHub 倉庫安裝¶
從 GitHub 倉庫安裝主要用於開發調試。先克隆倉庫並進入目錄：
git clone https://github.com/StarryHui/dsh-custom-background.git
cd dsh-custom-background
然後把當前目錄安裝到 web profile，並啓動：
dsh plugin --profile web add link:$(pwd)
dsh web
從倉庫安裝需要 Node.js >= 22 與 pnpm。
如果修改了 src/，需要到 DSH 源碼 checkout 的 packages/client 中重新構建：
tsc -b
tsdown --env.DSH_BUILD_FACE client
構建完成後，把新的 lib/ 複製回本倉庫。
配置與運行說明¶
插件的 background 配置通過自建同源路由讀寫，路由包括：
/dsh-bg/state
/dsh-bg/save
/dsh-bg/css
它不依賴官方 settings RPC 的命名空間白名單。
系統要求如下：
- 已安裝 DeepSeek Harness，
dsh web可正常啓動。 - npm 安裝方式無額外要求。
- 從倉庫安裝需要
Node.js >= 22與pnpm。
適用場景與注意¶
這個插件適合本地已有圖片、想自定義 DSH WebUI 背景的使用者。
安裝前建議檢查源碼與 MIT 許可證。插件加載後會以當前 dsh 進程權限運行，因此請確認安裝來源可信。
結尾¶
@starryhui/dsh-background 的價值在於把 DSH WebUI 背景調整做成可持久化的本地配置：指定圖庫、拖拽裁切框、調節透明度和高斯模糊、啓用交叉淡化輪播，配置會寫入 settings.yaml 的 background 命名空間。
GitHub 倉庫：https://github.com/StarryHui/dsh-custom-background
