@dsh-use/wallpaper-engine

dsh plugin --profile web add @dsh-use/wallpaper-engine

@dsh-use/wallpaper-engine







把 Wallpaper Engine 的 scene（场景）壁纸搬进 DeepSeek Harness 的 Web GUI —— 在浏览器里实时渲染粒子、水波、云卷、布料摆动，让动态壁纸成为你写代码时的背景。

不需要 Wallpaper Engine 在后台运行，不需要 WebGPU，不重新分发任何第三方素材。

# 一行安装（dsh web；桌面版 App 请用侧边栏「插件」页，不能用 CLI）
dsh plugin --profile web add "@dsh-use/wallpaper-engine" && dsh plugin --profile web install

⭐ 如果它让你的界面好看了，点个 Star 就是最大的支持。

发现哪张壁纸渲染不正常，欢迎提 Issue —— 壁纸写法千差万别，你的反馈是项目改进的主要来源。

---

🎬 在 DSH 里的真实效果

下面两段动图都是在 DSH Web GUI 的真实页面上录的（不是离线贴图，也不是设计稿）：壁纸由插件在浏览器里实时渲染 / 播放，DSH 界面叠加在其上。

<table>

<tr>

<td width="50%" align="center">

yuki恋冢爱

_{Video · Girls}

_{[▶ 完整视频（9s / mp4）](docs/videos/yuki-koizuka-dsh.mp4)}

</td>

<td width="50%" align="center">

Knight in a red cloak · 红披风骑士

_Anime

_{[▶ 完整视频（9s / mp4）](docs/videos/knight-red-cloak-dsh.mp4)}

</td>

</tr>

</table>

录制方式（如实说明）：两段动图与视频都是在真实运行的 DSH 页面上、由本插件的生产构建（lib/）实时渲染本机 workshop 壁纸后录制的浏览器画面，未做后期合成；壁纸通过插件自身的切换入口 window.__wallpaperEngine.select(id) 切换，因此画面里只有 DSH 界面与壁纸本身。画面已裁掉浏览器窗口边框（地址栏 / 标题栏）。yuki恋冢爱 是 HEVC（H.265）视频壁纸，这段用 Chrome 录制 —— 浏览器能否解码播放视频壁纸取决于它自身的解码能力：同一系统上 Edge 缺少 HEVC 解码会回退到预览图并提示（v0.8 起），Chrome 正常播放。壁纸素材版权归原作者所有，此处仅作效果展示，不再分发。

---

✨ 能做什么

· 能力 · 说明

🎨 · Scene 动态壁纸 · 在浏览器里实时算出来，不是静态图贴上去：背景图层与粒子系统各司其职，背景的缩放、透明度、亮度按原作者的设定还原

🌊 · 粒子效果基本完整 · 雪、雨、花瓣、火星、雾、气泡等都按壁纸里的原始参数运动：重力、风向、湍流、寿命、颜色与大小渐变；沿速度方向拉伸的拖尾（雨丝、风痕、余烬，即 WE 的 spritetrail）也已实现；起播相位（starttime）按原设定预推进，对象级实例覆盖（instanceoverride，含编辑器的 {user · script,value} 包装）同样生效 —— 加色雪层不再变黑；子粒子（子发射器）与绳索类拖尾（ropetrail）尚未支持，见「使用前请了解」

🖼️ · 各种纹理都能解 · 主流压缩格式（DXT1/3/5、RGBA、R8、RG88）与多帧精灵动画（火把、雾、光晕）都能正确解出原图，不糊、不露黑边；标记为精灵表的 image 只显示当前帧：有作者脚本的按脚本帧（可 pause / setFrame），无脚本的按约 1 帧/秒自动循环，不再把整张帧表压进一个图标

🎞️ · 视频 / 网页 / 图片壁纸 · 视频循环播放（编码不支持时自动回退预览并提示；视频壁纸自带音轨跟随「声音」开关播放，无音轨素材会提示）；网页壁纸在沙箱里加载，页内 <audio>/<video> 声音同样跟随「声音」开关与音量（Web Audio 自建声源控制不到）；图片壁纸用预览图 + 缓慢缩放动效

🪜 · 多级降级链 · scene 渲染失败时依次尝试 内嵌 MP4 → 抓帧 PNG → 作者预览图 → 空态；每级失败只跳过，不白屏、不黑屏卡死

🎬 · 视频编码兜底 · HEVC / H.265 等浏览器解不了的编码会回退到预览图，并在面板提示原因与自救建议，不再停在黑背景

🧩 · 常见特效会动 · 水波、涟漪、水流、云飘、植物摆动、抖动、脉冲、淡入淡出，以及模糊、泛光、光轴、局部对比度这类需要多趟渲染的特效（少数特效仍然看不到，见下节）

🌟 · 壁纸级 bloom · 作者在 scene 里开的泛光（general.bloom*，阈值/强度按原参数）会叠加到画面上，亮部外溢；与面板「光晕」是两个独立开关

🔉 · 音效音量与播放模式 · 音效对象的音量按原设定生效；single 播一次、random 随机选一首，多文件不再同时叠播

🖌️ · 场景底色 · 纯文本/透明场景按作者的 general.clearcolor 铺底（兼容 WE 的 0-1 色值），不再是恒黑

🕒 · 文本对象会显示 · 壁纸里的时间/日期文本会实时走字（如 VHS 时间与日期），不再是空一块；作者挂在文字上的效果链（模糊、VHS、水波）现在也会执行；带脚本的文本写法差异见下节

🔋 · 省电与画质档位 · 一键暂停壁纸；切到后台自动暂停；渲染分辨率可降到 0.5× 省显存、提流畅

🔁 · 自动轮播 · 收藏 ≥2 张时只轮播收藏，否则轮播全部非隐藏壁纸；1 / 5 / 10 / 30 分钟、顺序或随机；暂停联动、手动选择重置计时、本轮失败跳过

🔎 · 壁纸库管理 · 标题搜索、类型筛选、仅收藏、隐藏 / 恢复、最近使用排序；收藏与隐藏只存本地，不改壁纸文件、不打断当前播放

🎛️ · 显示效果面板 · 遮罩不透明度、背景模糊、Ken Burns、画面适配（裁剪铺满 / 完整显示 / 拉伸铺满）都在面板里直接调，改完立即生效

🎚️ · 用户属性面板 · 壁纸自带的属性（bool / slider / color / combo 可调，只显示当前壁纸真正引用的属性，不出现假控件）在面板里直接调；切换/调整后自动重装配生效，滑块与取色防抖提交（不逐帧重建）

🎵 · 系统媒体集成 · 在 Windows 上读取系统媒体会话（SMTC），让壁纸的专辑封面 / 歌名 / 歌手 / 主色与播放状态实时联动；仅内存、不落盘，面板可关

🎥 · 开机动画 · 打开 DSH / 新窗口时全屏播一段片头：素材可用 WE 库的视频 / 图片壁纸或本地视频文件（桌面端可直接用系统文件选择器选视频），四种展示方式，播完或到上限淡出；声音默认开启（面板可关，桌面版直接出声、浏览器首次交互后出声），片头播放期间壁纸声音自动静音、播完按设置恢复，每次会话只播一次，8 秒未就绪静默跳过；DSH 启动加载页（Loading plugins…）显示期间持续接管（视频循环 / 图片保持），主界面就绪后淡出

🛡️ · 失败不砸界面 · scene 渲染失败走多级降级链（内嵌 MP4 → 抓帧 → 预览图）；video 解码失败 / 首帧超时回退预览图并提示。web 壁纸目前没有失败回退（跨源 iframe 探测不到子帧错误，失败会停在空白）；界面本身始终可用

⚙️ · 开箱即用 · 自动探测 Steam 壁纸目录（注册表 + Steam 库配置 + 常见路径），也可手动填写；改设置立刻生效，不用重启

🚫 · 不依赖运行时 · 不需要 Wallpaper Engine 在后台运行；所需的引擎内置素材在你本机读取，不随插件分发第三方素材

💬 换了几张壁纸却发现某张显示不正常？ 那是我们需要知道的——请按下方「使用前请了解」末尾的说明提交 Issue，附上壁纸名称与 ID 即可。

---

🚀 快速开始

1. 安装插件

桌面版 App：用侧边栏「插件」页

⚠️ 桌面版不能用下面那几条 dsh plugin 命令 —— 桌面版 profile（desktop）由 App 独占管理，CLI 会直接拒绝：profile "desktop" is managed exclusively by the Electron application。

1. 打开桌面版，点左侧栏的 插件 页。「设置 → 内置插件」是只读清单，装不了东西。

2. 点 添加插件，在包名框里填下面任一种 —— 写法就是 dsh plugin add 后面那一段：

装法 · 填什么

npm（稳定版） · @dsh-use/wallpaper-engine

GitHub（最新） · github:yu502950715yang/dsh-use-wallpaper

本地仓库（改码即时生效） · E:\code\dsh-use-wallpaper（绝对路径即可，不必写 link:；装好后记为 link:）

输入框下方的 插件安装引导和示例 给出这三种形式的示例，填入示例 可一键填入（GitHub 与本地路径记得替换成实际值）。

3. 点 安装。首次使用会先探测 npm 官方源与国内镜像、选最先响应者；GitHub 连不上时会提示 无法访问 GitHub，可点 改用国内镜像。

4. 装完刷新页面即可生效（新装插件会即时挂载，不必重启 App）。

例外：装的是本地仓库、且随后改了它的 dist/client.js 时，必须整个 App 重启（托盘退出再启动）—— 桌面版 host 在启动时就把客户端 bundle 拍成内存快照，刷新页面拿不到新代码。

5. 接着做下面的「2. 启用并选择壁纸」。

可能挡住你的两个环节：① 插件声明的 DSH 版本不兼容时会被拦下，放行等于接受「可能崩溃或损坏数据」的风险，需要你明确确认；② 插件带 prepare / postinstall 安装脚本时 pnpm 会拦下，插件页会问你是否允许执行这些脚本。

卸载也在这一页（会二次确认）；「官方」分组里随安装提供的组合

…(truncated)