前言¶
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
