dsh-bg-image

DeepSeek Harness（dsh） Web UI 的自定义背景图片插件。

• Wallpaper Engine 集成：自动发现 Steam 创意工坊目录（注册表 + libraryfolders.vdf，也支持手动绑定），在设置卡片里浏览全部壁纸缩略图，点一下即设为 DSH 背景（image 类型用原图，scene/video/web 类型用预览图，gif 预览会动）
• 内置默认背景：插件自带一张渐变图（assets/default-bg.png），“恢复默认背景”一键切回
• 自定义上传：点“选择图片…”从电脑选图立即应用，或直接填本机绝对路径
• 明暗主题自动适配（浅色叠白遮罩、深色叠黑遮罩），遮罩不透明度可调，侧边栏可选择透出背景

浏览器端（任何打开 dsh web 的浏览器）与 DSH 桌面壳共用同一插件。

工作原理

• Host 半边（lib/index.js）：注册 bg-image settings namespace（持久化到 ~/.dsh/settings.yaml），并在 webserver 上挂三条路由：
  • GET /dsh-bg/image —— 按 imagePath 读本地图片流式返回（按扩展名设置 content-type）
  • GET/POST /dsh-bg/config —— 读取/整段写入本插件的配置（POST 经 schemastery schema 校验后落盘）
  • POST /dsh-bg/upload?name=<文件名> —— 接收图片字节（≤20MB，扩展名白名单校验），存到 ~/.dsh/bg-image/backgrounds/<安全文件名> 并自动设为当前背景
  • GET /dsh-bg/wallpapers —— 枚举 Wallpaper Engine 创意工坊壁纸（自动发现或用配置的 workshopPath；读各文件夹 project.json 的标题/类型/预览，标注当前生效项）
  • GET /dsh-bg/wallpaper-file?id=<工坊ID>&kind=preview|bg —— 安全地提供壁纸预览/背景文件（解析结果必须落在工坊目录内，防路径穿越）
  • POST /dsh-bg/wallpaper-apply {id} —— 一键把某壁纸设为背景（保留透明度等其他设置）

imagePath 留空即使用内置默认背景；host 侧动态解析插件包内 assets/default-bg.png 的路径。

• 浏览器半边（lib/client.js，window.__ModuleLoader__.load 自包含 bundle）：
  • 启动时 fetch 配置，调用官方主题 API ctx.theme.overrideTokens() 把 --dsw-alias-bg-base 覆盖成 linear-gradient(遮罩), url(图片) center/cover，--dsw-specific-sidebar-fill 覆盖为透明；深浅色各自一对值，随主题切换自动重渲染
  • 在 settings.plugin.item 槽位注册配置卡片（React，平台模块表里的 react，无额外依赖）：
    • 选择图片…：隐藏 <input type="file"> 触发系统文件对话框；选中后先用 URL.createObjectURL 即时预览，再把文件字节 POST 到 /dsh-bg/upload，host 保存并自动更新配置，背景立即生效
    • 路径输入框、透明度滑杆、两个开关走「保存」按钮（POST /dsh-bg/config）
  • 图片 URL 带 nonce 破缓存；窗口重新获得焦点时自动重拉配置

为什么不用官方 settingsScope？

dsh 的 wire 面 settings.describe 对浏览器只暴露硬编码白名单的 namespace（ui-theme、agent-loop 等，见 dsh-host-apiproxy 源码注释——插件自暴露是 deferred work），第三方 namespace 读不到。所以本插件经自己的 /dsh-bg/config 路由传输配置，与 client-modules 服务 bundle 的做法同理。

配置字段

字段	类型	默认	说明
enabled	bool	false	总开关
imagePath	string	""	本地图片绝对路径（png/jpg/webp/gif/bmp/avif）
opacity	number	0.35	遮罩不透明度 0–0.9；深色模式自动 +0.15
sidebarTransparent	bool	true	侧边栏填充透明，透出背景

安装（一键）

dsh plugin --profile web add github:mhwww/dsh-bg-image

重启 dsh --profile web 后，设置页 →「插件」里即可配置。升级：dsh plugin --profile web update dsh-bg-image。

需要已安装 dsh 和 pnpm（corepack enable pnpm）。从 git 安装时 pnpm 会自动解析依赖（@deepseek-ai/dsh-settings、schemastery 均在 npm 公开仓库）。

视频壁纸“高清帧”功能需要系统 PATH 里有 ffmpeg（缺失时自动回退预览图）；Steam 创意工坊目录自动发现依赖 Windows 注册表（其他平台请用卡片里的手动绑定）。

网络说明（国内用户）

github: 依赖安装时，pnpm 会先用自己的 HTTPS 探测解析 commit（读的是 npm/pnpm 代理配置，不读 git 的），再回退到 git ls-remote（读 git 自己的代理配置）。因此：

• 直连不稳的网络下，安装开头可能出现 2 行 ETIMEDOUT 重试警告——最终仍会成功（git 步骤通常可通）；个别失败重跑一次命令即可
• 想彻底避免警告，任选其一配好代理：

  pnpm config set proxy      http://127.0.0.1:7897   # 换成你的代理端口
  pnpm config set https-proxy http://127.0.0.1:7897
  # 或只给 git 配（pnpm 探测仍会警告，但克隆不受影响）：
  # git config --global http.https://github.com.proxy http://127.0.0.1:7897
  

开发安装（本仓库克隆后）

dsh plugin --profile web add <本仓库路径> --registry=https://registry.npmmirror.com
cd <本仓库路径> && pnpm install        # link: 安装下依赖在源码目录解析
dsh --profile web                      # 重启服务生效

dsh plugin add 会自动把包加进 profile 的 dsh.profile.bundles（本包带 dsh.bundle 声明与自带的 cordis.patch.yml，无需手工编辑组合层）。link: 方式安装时，修改 lib/ 下的代码重启服务即生效。

卸载

dsh plugin --profile web remove dsh-bg-image

已知边界

• 卡片文案当前为中文硬编码（locale 字典已预留）
• 直接编辑 settings.yaml 中的 bg-image 段后，切回浏览器窗口会自动生效（focus 时重拉）
• 图片路径填错时预览隐藏、背景不应用，不会影响 dsh 本体

License

MIT