elysia395/dsh-wallpaper-engine · 上手攻略

  • 仓库：elysia395/dsh-wallpaper-engine
  • 链接：https://github.com/elysia395/dsh-wallpaper-engine
  • 分类：DSH 插件 · 桌面美化
  • 作者：Tom
  • 更新：2026-08-21

这是什么

dsh-wallpaper-engine 是一个 DeepSeek Harness（DSH）bundle（插件），其核心功能是：把你电脑上 Wallpaper Engine 的壁纸"搬"到 DSH 网页界面的后方，让 AI 对话界面自带动态桌面背景。

它的工作方式并非简单地把图片塞进 HTML 背景，而是真正地读取引擎素材——.mp4 视频壁纸直接用 <video> 标签播放，网页壁纸用 <iframe> 嵌入，Scene（场景）壁纸则提取主纹理作为静态帧（3D 粒子/着色器动画本身无法在浏览器内重放）。整个设置界面还自带 iOS 风格的液态玻璃（glassmorphism）UI，包括配色、透明度、玻璃色调均可自定义。

一句话总结：DSH 用户终于可以在 AI 对话界面里跑动态壁纸了。

解决什么问题

DSH 默认界面是纯色的，没有桌面壁纸功能。如果你已经为 Wallpaper Engine 投入了大量壁纸收藏（Steam 工坊 thousands of items），又希望在 AI 对话时也有沉浸感的视觉背景，这个插件填补了这个空白。

相比直接用 Wallpaper Engine 原生客户端，本插件的优势在于： - AI + 壁纸共存：在 DSH 对话界面的三列布局后方渲染壁纸，不干扰正常使用 - 液态玻璃设置 UI：iOS 风格的磨砂玻璃卡片，比原生设置页更好看 - 壁纸管理：隐藏/恢复、上传自定义、倍速播放、镜像翻转、内容分级过滤（WE 工坊 G/PG13/R 三档） - 跨浏览器持久化：v0.4.0 起配置写入宿主端 ~/.dsh-wallpaper-engine/config.json，不受浏览器 localStorage 隔离问题影响（DSH Desktop 每次随机端口导致 localStorage 隔离的问题就此解决）

快速安装

前提：已安装 dsh 并运行 dsh web。

标准安装（npm 发布包）：

dsh plugin --profile web add dsh-plugin-wallpaper-engine
# 或完整写法
dsh plugin --profile web add elysia395/dsh-wallpaper-engine

装完后重启 dsh web，打开浏览器访问 DSH 界面，进入 设置 → Wallpaper Engine（左侧导航独立一级入口）即可。

macOS 用户注意：macOS 原生没有 Wallpaper Engine 客户端，需要用社区维护的 macOS 版插件（由 Jerry 维护，WaifuX + 散装媒体支持）：

dsh plugin --profile web add dsh-plugin-wallpaper-engine-mac
# 仓库：https://github.com/ruijiaang-lab/dsh-wallpaper-engine

本地开发版安装（改代码用）：

# 1. 克隆源码
git clone https://github.com/elysia395/dsh-wallpaper-engine.git
cd dsh-wallpaper-engine

# 2. link 安装（改代码后实时生效）
# Windows 示例
dsh plugin --profile web add link:D:\dev\dsh-wallpaper-engine
# macOS/Linux 示例
dsh plugin --profile web add link:./dsh-wallpaper-engine

⚠️ link: 后必须是包含 package.json 的文件夹的绝对路径，不能是文件本身路径。

核心用法

1. 选择壁纸

  1. 打开 DSH web，进入 设置 → Wallpaper Engine
  2. 点击 「选择壁纸」 按钮，弹出缩略图网格
  3. 点击任意一张 Video/Web/图片壁纸，它会立即出现在 DSH 界面后方
  4. 点遮罩、按 ESC 或点「关闭」收起弹窗

2. 场景壁纸（Scene）特殊处理

Scene 壁纸的 3D 粒子/着色器动画无法在浏览器内重放，但主纹理（通常是背景艺术图）可以被提取出来。插件会：

  1. 解析 scene.pkg（PKGV 容器 + LZ4 条目链）或松散 scene.json 目录
  2. 定位主纹理（TEX 容器），支持 TEXV0005/TEXI0001/TEXB0001-4 格式
  3. 解码为 RGBA8888/R8/RG88/DXT1/DXT3/DXT5，或直接输出内嵌 JPEG/PNG
  4. 约 80%+ 的 Scene 壁纸能提取出接近原图的彩色主图

不支持的 Scene 类型：纯 shader 粒子/程序生成类（无主纹理）、BC7/RGB565/16 位浮点纹理格式、video-texture 驱动的动态场景——这些会回退显示工坊预览图（preview.jpg），属预期行为。

3. 壁纸效果控制

在设置页的「壁纸效果」分区：

功能 操作
暂停/播放 暂停视频壁纸；关闭壁纸则清除后方背景
倍速 0.5× / 0.75× / 1× / 1.25× / 1.5× / 2× 六档，即时生效不重载
水平翻转 镜像画面（视频/网页/上传图片均适用）
隐藏/恢复 不想显示的壁纸一键隐藏（仅从列表移除，不删源文件），可随时恢复；批量多选可用工具栏「批量」按钮

4. 内容分级过滤

选择壁纸弹窗顶部有两个下拉框，复刻 Wallpaper Engine 工坊分类：

  • 内容分级：读取 project.json 的 contentrating 字段，筛 G（Everyone）/PG13/ R（Mature）/未分级
  • 类型：全部 / 视频 / 网页 / 图片（自上传）

5. 布局切换

设置页顶部有「紧凑布局」开关： - 关闭（默认）：常规网格，固定高度防重叠 + 分页 - 开启：CD 架效果——卡片纵向层叠（下排上沿盖住上排下沿），每行约 7 个，一页到底不翻页；鼠标悬停放大置顶

6. 自定义壁纸上传

无需 Steam 工坊，直接上传本地 JPG/PNG/MP4：

# 上传后通过 POST API 触发（设置页 UI 也可操作）
# 文件写入 ~/.dsh-wallpaper-engine/uploads/
# 通过 /wallpaper-engine/media/ 路由服务，与 WE 媒体走同一管道

7. 设置持久化（v0.4.0 起）

之前（v0.4.0 前）：设置存在浏览器 localStorage，按「地址+端口」隔离 → DSH Desktop 随机端口 = 每次新存储空间 = 配置全丢。

现在（v0.4.0 起）：配置写入宿主端文件：

Windows：C:\Users\<用户名>\.dsh-wallpaper-engine\config.json
Linux/macOS/WSL：~/.dsh-wallpaper-engine/config.json

与端口无关，重启/换端口/清浏览器/换浏览器/无痕模式均不丢。旧版 localStorage 配置首次启动自动迁移，无需手动操作。

Host 端 API（开发者参考）

插件在 DSH webserver 上注册以下同源 HTTP 路由（浏览器端通过 /wallpaper-engine/* 调用）：

方法 路由 说明
GET /wallpaper-engine/inventory 返回壁纸 JSON 列表
GET /wallpaper-engine/media/ 视频/HTML 媒体文件（支持 Range 断点续传）
GET /wallpaper-engine/preview/ 预览图
GET /wallpaper-engine/scene-frame/ Scene 壁纸提取的静态帧（磁盘缓存）
POST /wallpaper-engine/upload 上传自定义壁纸（JPG/PNG/MP4）
POST /wallpaper-engine/remove 移除已上传壁纸
PUT /wallpaper-engine/settings 保存插件设置（写入 ~/.dsh-wallpaper-engine/config.json）
GET /wallpaper-engine/settings 读取插件设置

自动定位 Steam：通过读取 libraryfolders.vdf 定位 Steam 安装目录，自动找到 Wallpaper Engine，无需手动配置路径。

典型适用场景

  1. AI 对话沉浸感增强：将你最爱的动态壁纸设为 DSH 背景，工作/聊天时更有氛围感
  2. 双屏用户：主屏跑 Wallpaper Engine，副屏（DSH 界面）也能显示同一壁纸
  3. 壁纸收藏管理：用 DSH 的弹窗界面浏览 Steam 工坊壁纸，带内容分级过滤，比原生客户端更便捷
  4. DSH 美化：液态玻璃设置 UI 让 DSH 看起来更像 macOS/iOS 原生应用
  5. 自动化壁纸切换：配合 DSH 插件系统，可实现定时自动更换壁纸等自动化场景

坑与注意

⚠️ DSH 版本要求：需要 dsh web 版本 0.1.0-rc.6 或更新。旧版本插件会静默禁用（不渲染任何 UI），表现为设置里看不到 Plugin Market 入口，尤其是 Desktop build 捆绑旧版 DSH 的情况。注意：设置页的 Plugin Market 自管理功能还需要 0.1.0-rc.7 或更新。

⚠️ Scene 壁纸 ≠ 3D 动画：静态帧只是主纹理，粒子/水波/着色器动画不会出现。BC7/RGB565/16 位浮点纹理无法解码，会回退到 preview.jpg，这不是 bug。

⚠️ macOS 版独立维护：macOS 版插件由社区维护（ruijiaang-lab/dsh-wallpaper-engine），功能和 Windows/macOS 版不完全一致。

⚠️ Application 类型壁纸无法使用：Wallpaper Engine 的 Application 类型（注入外部窗口）不支持，插件不会显示这类壁纸。

⚠️ 配置共享行为变化（v0.4.0）：同一台电脑上多个浏览器现在共享同一份配置（此前各存各的），回滚到旧版仍读 localStorage 副本，配置不会丢。

⚠️ 首次启动 localStorage 迁移：旧版用户在 v0.4.0+ 首次启动时，localStorage 中的配置会自动迁移到 config.json，无需手动操作，但如果迁移失败插件会回退默认值并保留原文件。

与同类对比

功能 dsh-wallpaper-engine DSH 原生设置 Wallpaper Engine 客户端
DSH 界面内动态壁纸 ✅ ❌ ❌（独立窗口）
液态玻璃 UI ✅（v0.3+） ❌ ❌
Scene 主纹理提取 ✅（v0.3+） ❌ ❌
壁纸内容分级过滤 ✅ ❌ ✅
配置跨浏览器持久化 ✅（v0.4.0） ❌ —
倍速/镜像控制 ✅ ❌ ✅
自定义壁纸上传 ✅ ❌ ✅
macOS 支持 ✅（独立插件） — ❌

目前没有其他 DSH 插件提供类似功能，这是一个垂直细分领域的独占方案。

一句话推荐结论

DSH 用户如果已经在 Steam 工坊囤了大量 Wallpaper Engine 壁纸，装上 dsh-wallpaper-engine 后 AI 对话界面瞬间变成沉浸式动态桌面，液态玻璃 UI 还能顺带美化整个 DSH 设置页——装机即用，零门槛提升 DSH 颜值。