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,刷新页面即可在「设置 → 通用设置 → 外观」
看到「背景图片」行。

使用

1. 打开 设置 → 通用设置,在外观下方找到「背景图片」;
2. 在输入框粘贴本地图片路径(例如 C:\Users\<你>\Pictures\bg.jpg
   或 D:\wallpaper\bg.png),按回车或点击其它位置生效;
3. 拖动「蒙层强度」滑块调整文字可读性与图片可见度的平衡;
4. 预览框实时反映效果,刷新页面后背景依然保留;
5. 点击「清除背景」恢复默认外观。

实现原理

• 宿主端(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