dsh-background
DeepSeek Harness Web 背景图片插件:在 设置 → 通用设置 → 外观 的
「背景图片」行填写本地图片文件的绝对路径,即可把该图片设为网页背景
(cover 填充),并提供与默认「外观」控件同尺寸(180 × 88,圆角 16px)的
实时预览。
功能
- 本地路径:输入本地图片文件的绝对路径(支持空格等特殊字符),
回车或失焦生效。图片由宿主端通过
/dsh-background/image 路由提供给
浏览器——浏览器本身无法直接加载本地文件路径。
- 实时预览:预览框尺寸参照默认外观主题立方体(180 × 88);输入框
聚焦时预览跟随输入实时变化;文件不存在或无法读取时显示提示。
- 持久化:配置保存到用户设置文档(
$DSH_HOME/settings.yaml 的
ui-background 段),刷新、重启后自动恢复;启动期由宿主端在
index.html 中先行注入,无默认背景闪烁。未配置时无背景,插件不内置
任何默认图片。
- 跟随明暗主题:背景图不变,兜底色自动跟随浅色/深色静态色板;背景图上
自动叠加一层与主题配对的可读性蒙层(浅色主题白蒙层 / 深色主题深蒙层),
任意亮度的图片上界面文字依然清晰可读,且不影响默认外观。
- 蒙层强度可调:外观行内提供 0–100% 滑块(步进 5,默认 70%),实时
调整蒙层透明度——拉低看得更清楚,拉高文字对比度更强,即时生效并持久化。
- 支持格式:jpg / jpeg / png / gif / webp / avif / svg / bmp / ico,
单个文件上限 25MB。
安装
# 从 npm 安装(推荐)
dsh plugin --profile web add dsh-background
# 或从 GitHub 安装
dsh plugin --profile web add github:luoyu-xingu/dsh-background
# 或克隆后从本地目录安装
dsh plugin --profile web add file:./dsh-background
安装完成后重启 dsh web,刷新页面即可在「设置 → 通用设置 → 外观」
看到「背景图片」行。
使用
- 打开 设置 → 通用设置,在外观下方找到「背景图片」;
- 在输入框粘贴本地图片路径(例如
C:\Users\<你>\Pictures\bg.jpg
或 D:\wallpaper\bg.png),按回车或点击其它位置生效;
- 拖动「蒙层强度」滑块调整文字可读性与图片可见度的平衡;
- 预览框实时反映效果,刷新页面后背景依然保留;
- 点击「清除背景」恢复默认外观。
实现原理
- 宿主端(
lib/index.js):
- 通过
ctx.settings.register 注册 ui-background 命名空间
(path / veil),作为进程内持久化通道;
webServer.register 注册图片路由 /dsh-background/image,按当前
配置读取本地文件并以正确的 content-type 提供;
webServer.tapIndex 注入启动期背景样式与 data-dsh-background
属性,页面首帧即是自定义背景;
connection.rpc.handle 注册配置通道 /dsh-background/config
(get / set),供浏览器端读写。
- 客户端(
lib/client.js):
- 向
settings.general.item 插槽注册外观行(参照内置 ui-theme 的
AppearanceRow 模式);
- 通过
ctx.connection.rpc.call 读写配置;
- 用覆盖 body 上
--dsw-alias-bg-base 别名令牌的方式应用背景
——与主题系统、明暗模式天然兼容;
- 蒙层强度通过 CSS 变量
--dshbg-veil-alpha 实时应用,调整强度
不重写样式表、不重新拉取图片,滑动流畅无闪动;
- 输入框停靠区用
::before 伪元素铺与页面一致的背景(图+蒙层)
并加顶部渐隐 mask,滚动文字不会透到输入框下方,背景图也保持连续。
为什么不直接用 settingsScope?当前版本(dsh 0.1.0-rc.6)的 settings
网关只对硬编码白名单内的命名空间开放浏览器读写,第三方插件注册的
命名空间会收到 settings-not-exposed 拒绝;自定义 RPC 通道是官方
开放给插件的等价通道。
卸载
dsh plugin --profile web remove dsh-background
并在 settings.yaml 中删除 ui-background 段即可清空背景设置。
License
MIT