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 起还支持：
- 壁纸选择弹窗：缩略图网格收纳进独立弹窗，设置页不再被长列表占满；
- 隐藏 / 恢复：不想看的壁纸一键隐藏（软删除），随时恢复，不碰源文件；
- 视频倍速：0.5x – 2x 六档原生调速，即时生效、不重载；
- 水平翻转：镜像画面（视频 / 网页 / 上传图片均适用）；
- 自定义壁纸：直接上传本地 JPG / PNG / MP4 当壁纸，可选存储位置与画面适配模式；
- 场景壁纸完整场景帧（v0.6）：Scene 壁纸由纯 JS 场景渲染器完整重放（对象树/纹理/粒子/shader 效果），不再是主纹理静态帧。
- 液态玻璃设置页（v0.3.1）：设置页升级为一级设置页（参照 dsh-web-ui-all 皮肤中心的设计），整页是可自定义的液态玻璃卡片 —— 配色（6 种预设 + 自定义取色）与玻璃透明度（0–60%）即时生效、持久保存。
- 整个设置窗口液态玻璃化（v0.3.2）：一键把 DSH 原生设置窗口整体（对话框 + 左侧导航 + General / 模型 / 插件等全部原生分区）换成液态玻璃 + 自定义配色 —— 开启「设置窗口液态玻璃」开关后，窗口背景、导航选中/悬停、按钮、开关、链接等全部跟随 配色 与 玻璃透明度，关闭则恢复原生样式。
- 玻璃调节统一（v0.3.3–v0.3.5）：设置窗口的玻璃模糊与对话栏共用同一套调节参数（「玻璃」滑动条 0–60 px 同时控制设置窗口与输入栏/气泡的模糊半径，饱和度/亮度/对比度配方一致）；新增「玻璃颜色」—— 设置窗口玻璃的底色色调可自定义（6 预设 + 自定义取色，默认浅色白 / 深色深夜蓝，选定后两种主题统一使用该色），与「配色」（交互元素）分工：配色管控件、玻璃颜色管玻璃本身。
- 设置持久化到宿主端文件（v0.4.0）：全部设置（已选壁纸、配色、透明度、布局、轮播、隐藏、倍速/翻转等）改存
~/.dsh-wallpaper-engine/config.json，不再依赖浏览器 localStorage —— 重启、换端口（含 DSH Desktop 的随机端口）、清浏览器数据、换浏览器都不再丢失；旧版 localStorage 配置首次启动自动迁移。
- Edge 兼容渲染：Edge（且仅 Edge）会在页面里任何"可见的
<video>"上绘制浏览器自带的「下载 / 投屏」悬浮工具栏，且没有官方开关可以关闭；插件因此在 Edge 中默认把视频壁纸改为 canvas 渲染来规避。「紧凑布局」同一行右侧新增「Edge 兼容」开关（默认开启），关闭后所有浏览器一律回退到原生 <video>。
- 媒体流句柄修复 + 扫描提速（v0.4.1）：媒体/预览/场景帧流在客户端断开时立即释放文件句柄（修复反复切壁纸/刷新累积句柄、Windows 上壁纸文件被锁无法删除/移动的问题）；壁纸库扫描改全异步（fs.promises 线程池），不再阻塞事件循环（WSL / 大壁纸库下启动明显更快）；WSL 支持：自动探测
/mnt/<盘符> 挂载的 Windows Steam 库，WSL 里也能发现壁纸。
- 遮挡暂停（省电三档）：类似 Wallpaper Engine 的「被遮挡时暂停」——最小化 / 切页、窗口失焦、使用电池供电时自动暂停视频壁纸，解码引擎直接归零；回到界面 / 接通电源自动继续（网页壁纸仅随页面隐藏被浏览器节流）。三档开关均持久保存。
- 解码帧率上限（抽帧转码）：高帧率源（如 4K120 H.264）的硬解是 GPU 占用大头（4060 实测 1.0x 达
60% Video Decode）。「壁纸效果」区设置 帧率上限（无限制 / 60 / 48 / 30 / 24 fps），宿主端用 ffmpeg 一次性重编码为上限帧率（时间线保持 1.0x 正常速度、与倍速完全解耦），输出 4K 保留 + AV1，带下载 / 转码实时进度条；实测 4K120→24fps 后占用从 ~60% 降至 **15%**。ffmpeg 三档供给：显式指定 → 自动下载（npmmirror + GitHub 双源竞速，跨平台资产表已验证）→ 系统 PATH。
- 壁纸效果调节条扩充（v0.6.x）：「壁纸效果」区新增 亮度 / 对比度 / 饱和度 三个滑动条（作用于壁纸媒体滤镜），与壁纸模糊 / 暗化等配合，任意壁纸都能调到与界面融合舒服的状态；全部即时生效、持久保存。
- 字体自定义（v0.6.7）：设置新增「字体」分区——总开关默认关闭（即 dsh 原生外观），开启后可调 字体颜色 / 字重(100–900) / 字体族（默认 · 雅黑 · 楷体 · 宋体 · 黑体 · 行楷 · 等宽，选项按钮以各自字体实时预览）；报错红字不受染色影响，关闭总开关即一键恢复默认。
壁纸 + 磨砂遮罩 + 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）。正确的升级顺序：
- 先把 DeepSeek Harness / DSH Desktop 更新到最新版：DSH Desktop 在「顶部导航栏 → 版本信息」检查更新，或到 GitHub Releases 下载对应平台安装包；
- 再更新本插件：
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），属预期行为，不视为缺陷。
场景渲染：怎么工作的
- 对象树：解析
scene.pkg（PKGV 容器 + LZ4 条目链）或松散 scene.json 目录，按 dependencies/parent 拓扑排序全部对象（image / particle / text / sound）。
- image 层：加载材质主纹理（RGBA8888 / DXT1/3/5 等），按 scene 坐标定位（origin/scale/angle 父链累积），应用 alpha/brightness。
- puppet 网格：MDL（MDLV）网格 + 绑定姿态光栅化（软件光栅 + 双线性 UV 采样 + 透明合成），人物/后发等骨骼模型正确显示。
- shader 效果链：waterwaves（含 DUALWAVES 双波乘积）/ waterripple / shake 按 shader 精确数学在 CPU 实现；mask 纹理支持。
- 粒子系统：boxrandom/sphererandom 发射器、color/size/alpha/lifetime/velocity/rotation 等初始化器、movement/alphafade/sizechange/turbulence/oscillate* 等运算符、sprite 精灵绘制。
- 缓存：渲染结果按
<版本>_<路径>_<mtime> 缓存到 ~/.dsh-wallpaper-engine/cache/frames/（可用 DSH_WE_CACHE_DIR 覆盖），工坊更新后自动失效重建；首次渲染约 3-4 秒，之后秒级命中。
工作原理
- Host 端（
lib/index.js）：一个 Cordis 插件，负责
- 通过读取 Steam 的
libraryfolders.vdf 定位 Wallpaper Engine 安装位置（所以 Steam 装在非默认盘也能用）；
- 从
projects/defaultprojects、projects/myprojects 以及 steamapps/workshop/content/431960/* 枚举壁纸；
- 在 DSH webserver 上注册同源 HTTP 路由，让浏览器端直接获取数据和流式加载媒体：
GET /wallpaper-engine/inventory → 壁纸 JSON 列表GET /wallpaper-engine/media/<token> → 视频 / HTML（支持 Range）GET /wallpaper-engine/preview/<token> → 预览图GET /wallpaper-engine/scene-frame/<token> → 场景壁纸完整场景帧（纯 JS 渲染器输出 3840×2160，失败回退主纹理提取，PNG 磁盘缓存）POST /wallpaper-engine/upload → 上传自定义壁纸（JPG / PNG / MP4，原始字节流）POST /wallpaper-engine/remove → 移除已上传的壁纸POST /wallpaper-engine/upload-dir → 更改上传目录（持久化到 ~/.dsh-wallpaper-engine/config.json，自动迁移已有文件）GET /wallpaper-engine/settings → 读取插件设置（v0.4.0）PUT /wallpaper-engine/settings → 保存插件设置（v0.4.0，写入 ~/.dsh-wallpaper-engine/config.json）GET /wallpaper-engine/media-info/<token> → 媒体元数据（分辨率 / 编码 / 帧率 / 时长，moov 探测）GET /wallpaper-engine/transcoded/<token>?fps=N → 抽帧转码流（ffmpeg 一次性重编码，磁盘缓存）GET /wallpaper-engine/transcode-progress/<token>?fps=N → 下载 / 转码进度（进度条轮询）
- Client 端（
lib/client.js）：一个浏览器模块，拉取壁纸列表，把选中壁纸渲染到应用三列后方的固定图层，并在「设置」里注册一个一级设置页「Wallpaper Engine」（含液态玻璃卡片、选择弹窗、隐藏/恢复、倍速/翻转、配色/透明度与自定义壁纸管理）。
- 自定义壁纸存储：上传的文件写入插件管理的本地目录（默认
~/.dsh-wallpaper-engine/uploads，可在设置里改到任意盘符），经同一套 /media、/preview 路由服务——与 WE 媒体走完全相同的管道，天然跨重启持久、无浏览器配额限制。
设置持久化（v0.4.0）
你的全部设置（已选壁纸、配色、透明度、布局、轮播、隐藏、倍速/翻转等）从 v0.4.0 起保存在宿主端文件里，不再依赖浏览器 localStorage。
- 存在哪里：
~/.dsh-wallpaper-engine/config.json（与「上传目录」的配置是同一个文件）。具体位置：
- Windows：
C:\Users\<你的用户名>\.dsh-wallpaper-engine\config.json
- WSL / Linux / macOS：
~/.dsh-wallpaper-engine/config.json
- 为什么改：此前设置存在浏览器 localStorage，而 localStorage 按「地址 + 端口」隔离——DSH Desktop 每次启动用随机端口，等于每次进入一个全新的存储空间，配置全部恢复默认（Web 端固定端口则无此问题）。改存宿主端文件后与端口无关。
- 带来的好处：重启 / 换端口 / 清浏览器数据 / 换浏览器 / 无痕模式都不再丢失配置。
- 旧数据迁移：老版本存在 localStorage 里的配置会在首次启动时自动迁移到该文件，无需任何手动操作。
- 需要知道的行为变化：同一台电脑上，多个浏览器（如 Chrome 和 Edge）或手机等设备访问同一个 dsh 时，共享同一份配置（此前各存各的）；如果你回滚到旧版本，它仍会读取 localStorage 里的缓存副本，配置不会丢。
- 配置文件的读写：每次修改设置会自动写入（200ms 防抖合并）；文件损坏时插件回退默认值且不会覆盖你的文件。
安装
普通用户（安装已发布版本，推荐）
如果你只是想用这个插件，直接装 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（DeepSeek Harness）插件，把你电脑上已安装的 Wallpaper Engine 壁纸渲染成 dsh web 聊天界面的动态背景，并在上面叠加 iOS 风格的磨砂「液态玻璃」效果。