前言¶
DSH 可以通过插件扩展 DSH Web 的功能。下面介绍 leavestring/awesome-dsh-background-plugin，一个由 leavestring 维护的 DSH 背景设置插件。
它为 DSH Web 提供可上传图片 / 预设氛围的背景设置，设置持久化，重启不丢失。如果你希望在 DSH Web 中调整工作区背景，它把背景调整放到设置入口里：可以上传 JPG / PNG / WEBP / GIF，也可以切换到极光、余烬、宣纸三种预设氛围，并在设置面板内实时预览。
这是什么¶
awesome-dsh-background-plugin 是 DSH 插件，许可证为 MIT。资料中当前版本为 0.1.9。
它解决的问题是：在 DSH Web 中提供一个背景设置项，用于调整背景图片、预设氛围和显示参数。
已核实的能力包括：
- 支持上传图片，并在浏览器本地处理，不发送给第三方图片服务。
- 支持三种预设氛围一键切换。
- 支持图像存在感、暗色遮罩、柔焦、适配方式、焦点位置五维细调。
- 设置面板内实时预览，所见即所得。
- 设置持久化，重启不丢失。
- 支持中文 / English 双语界面。
- 浅色 / 深色主题下正常工作。
核心功能¶
图片上传与本地处理¶
插件支持上传 JPG / PNG / WEBP / GIF 图片。
图片在浏览器本地压缩，长边 ≤ 1600px，输出为 WEBP。图片在浏览器本地处理，不发送给第三方图片服务。
预设氛围¶
支持三种预设氛围：
- 极光
- 余烬
- 宣纸
点一个预设即可切换。
显示参数细调¶
支持五维细调：
- 图像存在感
- 暗色遮罩
- 柔焦
- 适配方式
- 焦点位置
这些参数可以在设置面板内拖动预览，所见即所得。
持久化与移除¶
设置持久化，重启不丢失。上传自动持久化自 0.1.6 及以上版本提供；资料中当前版本为 0.1.9。
想移除背景时，可以关闭「已启用」开关，或点击「恢复默认」。资料说明关闭「已启用」开关或点击「恢复默认」即可完全移除。
安装与启用¶
资料中同时给出一键安装命令与手动安装流程，安装方式不止一种。先准备环境，再按资料中的流程安装。
环境要求¶
Node.js ≥ 18
pnpm
DSH
获取代码¶
仓库地址：
https://github.com/leavestring/awesome-dsh-background-plugin
一键安装¶
在仓库目录中运行：
node scripts/install.mjs
手动安装¶
手动安装命令引用本地插件包 awesome-dsh-background-plugin-0.1.9.tgz。按资料中的手动流程准备好该文件后，运行：
dsh plugin --profile web add ./awesome-dsh-background-plugin-0.1.9.tgz
该命令将插件安装到 web profile。
白名单配置¶
必须把 ui-background 加入 dsh-host-apiproxy 的 WEB_SETTINGS_NAMESPACES 白名单，否则保存会被拒绝。
涉及的命名空间和字段如下：
ui-background
WEB_SETTINGS_NAMESPACES
重启与刷新¶
安装后需完全停止并重启 DSH。浏览器可能需 Ctrl+F5 强制刷新。
经过上面的步骤，打开：
设置 → 通用设置 → 背景
即可看到背景设置。
典型用法¶
1、打开 设置 → 通用设置 → 背景。
2、点一个预设，或上传一张图片。上传后立即生效并持久化，无需点保存。
3、拖动「图像存在感 / 暗色遮罩 / 柔焦」滑块实时预览，满意后点 保存背景 持久化参数。
4、想移除背景：点 恢复默认，或关闭「已启用」开关后保存。
适用场景与注意¶
适合使用 DSH Web、希望调整背景外观、并偏好本地图片处理的开发者。安装前建议先检查源码与许可证；插件以当前 dsh 进程权限运行。
需要注意：
- 资料中当前版本为
0.1.9，上传自动持久化自0.1.6及以上版本提供。 - 若未配置
ui-background白名单，保存会被拒绝。 - 安装后需完全停止并重启 DSH，浏览器可能需
Ctrl+F5强制刷新。 - 社区目录页是独立站点，与 DeepSeek / 幻方无官方从属关系。
