dsh-wallpaper-engine README

The project's README from github.com/elysia395/dsh-wallpaper-engine. As one markdown file: README.md.

dsh-plugin-wallpaper-engine

English | 中文

🆕 没用过命令行?先看这里:小白向使用指南(新手快速上手)→ —— 给完全没接触过命令行的用户准备的简化说明。

一个 DSH bundle,把你电脑上的 Wallpaper Engine 壁纸变成 DSH 网页界面(dsh web)的背景。

✅ 已优化:沉浸式全屏窗口偶尔全屏闪白(v0.6.4,保留完整毛玻璃) 早期版本在桌面快捷方式打开的沉浸式全屏窗口(独立应用 / kiosk 窗口)里,点击对话或输入文字时可能整屏闪白一下——这是该窗口 + 硬件加速下,Chromium 合成器对壁纸重绘时偶发把整屏画白。 v0.6.4 继续按「减少合成层」处理:仓库面板关闭时懒加载、拉绳无永久滤镜、壁纸媒体默认下不再强制一个变换合成层——同时完整保留毛玻璃;普通浏览器标签页完全不受影响,保持完整毛玻璃与硬件加速。 插件更新后会弹一次提示,告知此优化(每个新版本仅出现一次)。

它会自动发现你本机的 Wallpaper Engine 安装,列出你的壁纸,并把可移植的类型渲染到 DSH 对话界面的后方,配以 iOS 风格液态玻璃效果:Video(.mp4)动态播放、Web/HTML 以 iframe 加载,Scene(场景)由内置渲染器输出完整场景帧(对象树/纹理/粒子/shader 效果)。v0.2 起还支持:

主界面效果展示

壁纸 + 磨砂遮罩 + iOS 液态玻璃,渲染在 DSH 界面后方。

⚠️ 升级顺序:先更新 DeepSeek Harness,再更新本插件(v0.7.1 起)

在旧版 DeepSeek Harness 上请勿升级本插件。 v0.7.1 适配 DeepSeek Harness 0.1.2-rc.1(对应 DSH Desktop v2.0.5,2026-09-03 发布——该版本起桌面端内置的 harness 由 0.1.2-alpha.1 切换为 0.1.2-rc.1)。正确的升级顺序:

  1. 先把 DeepSeek Harness / DSH Desktop 更新到最新版:DSH Desktop 在「顶部导航栏 → 版本信息」检查更新,或到 GitHub Releases 下载对应平台安装包;
  2. 再更新本插件:dsh plugin --profile web add dsh-plugin-wallpaper-engine(或插件市场里点更新)。

💡 同时建议把其它 DSH 插件也一并更新:旧版插件在 harness 0.1.2-rc.1 下可能直接加载失败(实测 web profile 里的旧版 dsh-better-sidebar 会因 API 变更而启动报错)。

顺序反了(harness 还是旧版就升了插件)时,先把 harness 更新到最新即可恢复;无需回滚插件。插件更新后会在界面里弹一次提示(每个新版本仅出现一次),漏看也没关系。

✅ v0.7.1 已在 DSH Desktop v2.0.5(harness 0.1.2-rc.1)上完成实测:壁纸宿主路由(inventory / media / scene-frame)、设置一级分区、选择器弹窗、视频与场景壁纸播放、拉绳抽屉、液态玻璃在「兼容模式」与「增强模式」下均正常。本插件依赖的 slots / webserver / 主题变量等 API 在 0.1.2-alpha.1 → 0.1.2-rc.1 之间保持稳定。

🐛 v0.7.1 修复 rc.1 的「色板 / 黑胶唱片变圆角矩形」(#74):rc.1 主题层新增 corner-shape.css,给所有元素统一加了 corner-shape: superellipse(1.5)(方圆形角),任何 border-radius:50% 的正圆都被渲染成圆角矩形。插件现已对自身绘制的全部正圆 / 胶囊控件(色板、黑胶唱片、滑杆圆点、开关滑块、字体 chip 等)显式重置 corner-shape: round,在旧版 harness 上该声明会被自动忽略、无副作用。

支持哪些壁纸类型?

Wallpaper Engine 的壁纸分四种类型:

类型 由谁渲染 能否搬到 DSH
Scene(场景) Wallpaper Engine 自带的 3D 引擎 ✅ 完整场景帧 — 纯 JS 场景渲染器(对象树/纹理/粒子/shader 效果),见下文

Scene 壁纸的 3D 场景由本插件内置的纯 JS 场景渲染器(lib/scene-renderer.js,参考 linux-wallpaperengine / repkg 逆向成果)完整重放:解析 scene.pkg 的对象树,渲染全部 image 层(含 waterwaves/waterripple/shake 等 shader 效果的 CPU 实现)、puppet 骨骼网格(绑定姿态)、以及粒子系统(发射器/初始化器/运算符/精灵绘制)。选择器里场景卡片带有「静态帧」徽标,可与动态壁纸区分。

展现效果:渲染器输出 3840×2160 完整场景帧(背景+水+后发+人物+伞+粒子),对摄影、插画、动画截图类场景壁纸效果接近原版;渲染失败(纯 shader 生成类/特殊纹理格式)时自动回退旧的主纹理提取,再失败回退工坊预览图(preview.jpg),属预期行为,不视为缺陷。

场景渲染:怎么工作的

工作原理

设置持久化(v0.4.0)

你的全部设置(已选壁纸、配色、透明度、布局、轮播、隐藏、倍速/翻转等)从 v0.4.0 起保存在宿主端文件里,不再依赖浏览器 localStorage。

安装

普通用户(安装已发布版本,推荐)

如果你只是想用这个插件,直接装 npm 上已发布的包即可:

dsh plugin --profile web add dsh-plugin-wallpaper-engine

装完重启 dsh web,打开 设置 → Wallpaper Engine 就能用。

macOS 用户:macOS 没有 Wallpaper Engine 客户端,本插件的 macOS 版(WaifuX + 散装媒体支持)由社区维护者 Jerry 维护,发布为独立 npm 包:

dsh plugin --profile web add dsh-plugin-wallpaper-engine-mac

仓库:https://github.com/ruijiaang-lab/dsh-wallpaper-engine

开发者(运行你本地的一份代码)

大多数读者可以跳过本节。 只有当你打算自己改这个插件的代码时才需要。下面的步骤假定你已了解命令行、以及「仓库 / repository」是什么(一份用 Git 做版本管理的代码文件夹)。

第 1 步:取得源码(checkout)

这里 checkout 的意思很简单:就是「把源代码下载/复制一份到你电脑的某个文件夹里」。通常在这个 GitHub 页面点 Code → Download ZIP 下载并解压,或用 Git 克隆:

git clone https://github.com/elysia395/dsh-wallpaper-engine.git

完成后你会得到一个包含 package.json、lib/、src/、cordis.patch.yml 的文件夹。下文把这个文件夹称作插件文件夹。

第 2 步:用文件夹路径安装(link:)

这里的 link: 表示:告诉 dsh(它会把命令转发给 pnpm)去连接你本地那个插件文件夹,而不是从网上下载一个包。好处是:你改完代码并重新构建后,改动能直接生效,不用反复重装。

把下面命令里的 <插件文件夹绝对路径> 替换成你插件文件夹的完整路径(就是你在资源管理器/文件管理器里打开那个文件夹时,地址栏显示的那串路径):

dsh plugin --profile web add link:<插件文件夹绝对路径>

具体示例——假设你的插件文件夹路径像 D:\dev\dsh-wallpaper-engine 这样:

dsh plugin --profile web add link:D:\dev\dsh-wallpaper-engine

如果你已经用命令行 cd 到了插件文件夹的上一级,也可以用相对路径:

dsh plugin --profile web add link:./dsh-wallpaper-engine

该填哪个确切的路径? 必须是包含 package.json 的那个文件夹——不是 package.json 文件本身的路径,也不是它里面任何单个文件的路径。它就是你在资源管理器地址栏里打开那个文件夹时显示的那串路径。

为什么推荐 link: 而不用 file:?link: 是和你的源码文件夹建立实时连接,改完 src/client.js 并 npm run build 后直接生效,无需重装;file: 则是打包成一份静态快照,每次改动都要重新 add。首次安装两者都可以。

然后重启 dsh web。host 端会成为 bundle 层,client 端会自动加载(dsh.client.immediately: true)。

如果 Steam 装在非标准位置,host 会通过 libraryfolders.vdf 自动探测,无需额外配置。

安装失败排查

dsh plugin --profile web add ... 会把命令转发给 pnpm。如果你遇到下面的错误:

[ERR_PNPM_UNEXPECTED_VIRTUAL_STORE] Unexpected virtual store location
dsh: pnpm failed in profile directory C:\Users\xxx\.dsh-desktop\profiles\web

这不是插件本身的问题(换任何一个插件安装都会失败),而是该 profile 目录的 pnpm 依赖状态失效了:pnpm 在 node_modules\.modules.yaml 里记录了安装时的虚拟存储位置(绝对路径),一旦 profile 目录被移动 / 复制 / 备份恢复过,或 pnpm 版本 / virtual-store-dir 配置发生变化,记录值与当前路径不一致,pnpm 就会拒绝继续安装任何插件。

修复(Windows PowerShell):

# 1) 先退出 DSH 桌面端
# 2) 删除该 profile 的依赖目录(只删 node_modules 即可,配置/已装插件名不会丢)
Remove-Item "$env:USERPROFILE\.dsh-desktop\profiles\web\node_modules" -Recurse -Force
# 3) 重新安装本插件
dsh plugin --profile web add dsh-plugin-wallpaper-engine

只删除 node_modules\.modules.yaml 一个文件也能修复(pnpm 会自动重建并继续),删除整个 node_modules 更彻底。如果 .dsh-desktop 被 OneDrive / 云同步 / 迁移工具动过,建议把它加入同步排除,避免复发。

如果遇到下面的错误:

[ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED] ... The git-hosted package "[email protected]"
needs to execute build scripts but is not in the "allowBuilds" allowlist.

说明你用了 github: 形式的安装命令(例如 dsh plugin --profile web add github:elysia395/dsh-wallpaper-engine)。pnpm 11 出于供应链安全,默认拒绝从 git 安装的包执行构建脚本,而本插件的 git checkout 需要 prepare 脚本构建 client,因此 github: 直装必然失败。请改用 npm 包名安装(npm 发布包已预构建,无需安

dsh-wallpaper-engine (elysia395/dsh-wallpaper-engine)

Searching Database…

What is this?It is a DSH (DeepSeek Harness) plugin that takes the Wallpaper Engine wallpapers already installed on your PC and renders them as the animated background of the dsh web chat interface, with an iOS-style frosted 'liquid glass' overlay on top.
Is this a standalone app or does it plug into something else?It is not a standalone app. It is a DSH bundle made of a host-side Cordis plugin (lib/index.js) that reads your Wallpaper Engine library and serves routes, plus a browser-side client module that renders the wallpaper behind the dsh web UI.
How do I install it and get it running?Run 'dsh plugin --profile web add dsh-plugin-wallpaper-engine' (or install it from the plugin marketplace), then restart dsh web and open Settings → Wallpaper Engine.
Do I need Wallpaper Engine itself installed, and does this work on macOS?On Windows/Linux it auto-detects your Wallpaper Engine install by reading Steam's libraryfolders.vdf, so no manual config is needed. There is no Wallpaper Engine client on macOS, so the macOS version is a separate, community-maintained npm package built on WaifuX instead.
Does every Wallpaper Engine scene render perfectly?No. Scene wallpapers are replayed by a custom pure-JS renderer, and purely shader-generated or special texture formats can fail to render; the plugin then automatically falls back to a static main-texture frame, and if that also fails, to the Workshop preview image. This fallback is considered expected behavior, not a bug.
What wallpaper types does it support?Scene wallpapers are fully replayed by a built-in pure-JS renderer (object tree, particles, puppet skeletons, shader effects). Video (.mp4) plays natively and Web/HTML wallpapers load in a sandboxed iframe. You can also upload your own JPG/PNG/MP4 as a custom wallpaper.
What does the 'liquid glass' customization actually offer?It is an iOS-style frosted-glass skin with 6 color presets plus custom color pickers, adjustable blur/opacity sliders, and an option to apply the same glass styling to the entire native DSH Desktop settings window.
Does it try to save power?Yes - it automatically pauses video decoding when the window is minimized, unfocused, or the device is on battery, and lets you cap frame rate (e.g. 4K120 down to 24fps) via one-time ffmpeg transcoding, cutting GPU decode usage dramatically.
Does any of this cost the AI agent tokens?No. All wallpaper logic and settings run and persist on the host side, so the plugin adds zero token overhead for the agent.
Creator
elysia395
Size
94.8 MB
Stars
1.5K
Age
2mo
Commits · 90 Days