壁纸引擎背景 SuuuJV/dsh-wallpaper-engine

给 DeepSeek Harness 用的 Wallpaper Engine 背景

浏览你自己的 Wallpaper Engine 库，把它当作 DeepSeek Harness 应用背景，配上磨砂半透明面板。

和大多数主题插件不同，这个插件读的是你真实的创意工坊库——对于 scene 壁纸，它会从 scene.pkg 里渲染出场景的纹理图层，所以你拿到的是画作本身，而不是其中某一层，也不是约 768 px 的 preview.jpg 缩略图。

想让壁纸真正动起来？ 这个插件每张壁纸只合成一帧静止画面。如果你想要真正的效果——scene 壁纸在 WebGL 里实时渲染（粒子、木偶骨骼、SceneScript、鼠标视差），video 壁纸播放并转码，web 壁纸在 WE API 沙箱里运行，系统音频响应，液态玻璃 UI——请改用 elysia395/dsh-wallpaper-engine。那才是干这活的成熟 DSH 插件，尽管名字相似，它和本项目是两个不同的项目。本仓库还能提供的是一个体积小、无依赖的静止帧合成器，以及一份可读的 scene.pkg / .tex 图层格式参考。

中文说明

功能

- 读取你真实的 Wallpaper Engine 库——指向你的 Steam 创意工坊文件夹，列出所有已订阅壁纸及其标题。
- 全分辨率画作——scene.pkg 把画面存成一叠纹理图层（外加遮罩、精灵图和着色器），Wallpaper Engine 在运行时把它们混合起来。这个插件解析容器，解码各图层——存储的 PNG/JPEG 流、原始 RGBA、DXT5/DXT1、LZ4 压缩与否——再按场景顺序合成。这样你拿到的是原始 1920×1080 / 3840×2160 画作，而不是随便某一层，也不是小小的预览缩略图。
- 动态预览——很多壁纸附带的是动态 preview.gif，而不是静止图。选择器会给这些标上 动 徽章，还有个开关让你优先用动画，而不是更清晰的合成静止图。
- 带搜索的选择器——缩略图网格，可按标题或创意工坊 id 过滤。
- 四个实时滑块——面板不透明度、壁纸模糊、背景变暗、壁纸亮度。所有设置按浏览器持久化。
- 感知明暗主题——叠加色调跟随应用的配色方案，所以两种模式下文字都清晰可读。

要求

- DeepSeek Harness，带 Web GUI 配置档。
- 通过 Steam 安装的 Wallpaper Engine（任何平台）。
- 基于 Chromium 的浏览器或 DSH 桌面应用（需要目录选择器和 Blob URL）。

安装

从本仓库的检出目录：

dsh plugin install /absolute/path/to/dsh-wallpaper-engine

或者在 DSH 会话里，让智能体运行 plugin_manager，action: install_bundle，target 设为本目录。

然后在 Settings → Plugins 里启用 Wallpaper Engine Background，如果它还没开的话。

用法

1. 打开 Settings → Wallpaper Engine 壁纸。
2. 点击 Choose Wallpaper Engine folder，选中你的创意工坊内容目录：
- Windows：C:\Program Files (x86)\Steam\steamapps\workshop\content\431960 （或者你 Steam 库所在的任何位置——文件夹名取自 Wallpaper Engine 的 Steam 应用 id，即 431960）
- Linux：~/.steam/steam/steamapps/workshop/content/431960
- macOS：~/Library/Application Support/Steam/steamapps/workshop/content/431960
3. 从网格里挑一张壁纸，然后拖动滑块调节。

新壁纸。 这里没有文件系统监听器——浏览器不提供目录变更事件——所以你在 Wallpaper Engine 里下载的壁纸不会自己出现。到设置页按一下 Rescan（或者重新加载），它就会被读取。

浏览器重启之后。 文件夹句柄存在 IndexedDB 里。浏览器仍然授予读取权限时，壁纸库会自己重新加载；权限退回「prompt」状态时（需要用户手势），会出现一个一键 Grant access and scan 按钮。这是浏览器的安全规则，不是 bug。

工作原理

整个插件都在客户端运行。

1. 扫描。 读取选中的目录，每张壁纸对应一个子文件夹，里面各有一个 project.json（存着标题），以及 preview.jpg / preview.gif 或 scene.pkg。

2. 列表。 用标题和小缩略图搭出选择器。这一步只读那些很小的预览文件，所以列出一个大壁纸库开销依然很低。

3. 渲染。 你选中 scene 壁纸时，会解析它的 scene.pkg：PKGV 文件表、scene.json 的对象列表，以及每个对象的 model → material → .tex 链路。纹理会解码（存储的 PNG/JPEG 流、raw RGBA、DXT5/DXT1、单通道遮罩——容器标明压缩时用 LZ4 解压），再以 1920 px 宽自下而上合成，得到的就是 Wallpaper Engine 会显示的画面。只有你真正选中的壁纸才会走这一步。

4. 应用。 画面变成一个 Blob URL，放在应用背后一层 position: fixed; z-index: -1 上。由于这一层的每个祖先都会把自己的背景画在负 z-index 子元素之上，所以要把框架的背景清掉，再用 theme.overrideTokens() 把面板 token 调成半透明——这是唯一能改它们的办法，因为主题呈现器把它们写成 <body> 上的内联样式。

开发

插件就是一个手写的浏览器文件 client.js，没有构建步骤：改完重新加载 DSH 窗口即可（要硬刷新，因为客户端模块有缓存）。

场景渲染器——#region scene-renderer 和 #endregion scene-renderer 之间的全部代码——刻意不依赖 React，也不碰 DOM API，除了 document.createElement('canvas')、createImageBitmap 和 Blob，这样它就能脱离浏览器运行：

node test/scene-render.mjs 2372608028 # composite -> test/out/.pngbash
node test/scene-render.mjs 2372608028 --layers # 逐对象放置报告
WPE_LIBRARY=~/.steam/steam/steamapps/workshop/content/431960 node test/scene-render.mjs ...

测试框架把 canvas 垫进 Node，所以它跑的是浏览器同一套渲染代码；只有 JPEG mip 需要真正的浏览器（createImageBitmap），这就是为什么壁纸画面只是一条 JPEG 流时，那里会报 no layers。这个渲染器就是靠它对照 Python 参考实现、以及壁纸自带的预览图做校验：抽样库里全部 63 个 scene 包，层栈完全一致；抽样的 id 合成结果逐像素相同（通道平均差 ≤ 2.2）。

限制

- 视频壁纸不会播放。 类型为 video 的壁纸带的是 .mp4，不是 scene.pkg。在 UI 背后解码视频会持续吃 CPU，所以这个插件改用它们的预览文件——如果预览文件是 preview.gif，它恰好能免费动起来。
- 动画选项拿清晰度换动态。 preview.gif 只有几百像素宽，优先用它而不是合成出来的 scene.pkg 画面，肉眼可见地更糊。抽样库里 86 张壁纸有 36 张带动态预览，其中 21 张同时有 scene.pkg——也就是说这个开关对它们确实会改变结果。
- 有些场景会退回预览图。 场景主体是 puppet（骨骼形变网格，本身就是一套光栅化器）或脚本驱动图层时，合成出来是残缺或扁平的画面。这时改用预览图——糊，但至少是真正的画面。抽样库里 63 个 scene 包中有 2 个属于这种情况。
- 精灵图集跳过。 整张画出来的动画图集会把每一帧同时显示，所以这些对象直接略过；它们是飘落的花瓣和火花，从来不是画面主体。
- 清晰度在不同壁纸之间差别很大，设置页也如实说明：它会报告合成尺寸和层数，并对低于 1280 px 的标出警告。原因有两个。第一，源头本身：抽样库里 Wallpaper Engine 的 preview.jpg 从 160 px 到 1080 px 都有，而画面只是一张小纹理的 scene.pkg 也一直很小。第二，background-size: cover 按需要放大的那一轴缩放，所以 正方形* 的 728×728 预览图放进宽窗口时，会按宽度放大——比 1920×1080 的图放大得多。调高 wallpaper blur 能相当好地盖住低分辨率源。
- 重新加载后可能需要重新选一次文件夹，取决于浏览器怎么持久化目录句柄。
- Steam 的逐壁纸文件夹以 workshop id 为键，而 id 说明不了画面内容；标题来自各自的 project.json。

致谢与免责声明

这个插件是非官方的。它与 Wallpaper Engine（Kristjan Skutta）和 DeepSeek 没有关联，也未获其认可或赞助；文中使用它们的名字描述性地说明这个插件能配合什么使用、在哪里运行。

本仓库不附带任何美术资源。插件读取你本机已有的壁纸文件，在内存中合成，再把结果以 Blob URL 的形式放到界面后面 —— 不上传、不复制进仓库、不再分发。你展示的内容仍归其各自的许可协议管，Wallpaper Engine 的条款也继续适用于它下载的那些文件。

场景渲染器背后的文件格式知识 —— PKGV 容器、TEXV/TEXB 纹理容器、LZ4 块布局、DXT 块 —— 来自公开的社区逆向工程。这里的实现是照着文件布局本身写的，并逐层对照真实包做了校验；没有包含任何其他项目的代码。值得提一下的先行工作，如果你想从另一个角度理解同样的格式，也值得一读：RePKG 和 linux-wallpaperengine。

License

MIT。壁纸美术资源归其各自作者所有 —— 本插件读取你本机上的文件，不分发其中任何一个。

中文说明

把你自己的 Wallpaper Engine 壁纸库用作 DeepSeek Harness 的应用背景，面板半透明磨砂。

和大多数主题插件不同，这个插件读的是你真实的创意工坊壁纸库；对于 scene 类型的壁纸，它会把 scene.pkg 里的图层合成成完整原画，而不是只取其中一层、也不是将就那张约 768px 的 preview.jpg 缩略图。

想让壁纸真的动起来？ 本插件每张壁纸只合成一张静态帧。如果你要的是完整效果 —— 场景壁纸用 WebGL 实时渲染（粒子、puppet 骨骼、SceneScript 脚本、鼠标视差）、视频壁纸直接播放并转码、网页壁纸沙箱挂载 + WE API、系统音频反应、液态玻璃界面 —— 请用 elysia395/dsh-wallpaper-engine。那才是做这件事的成熟 DSH 插件；它和本项目只是名字相近，是两个不同项目。本仓库的价值在于：一个无依赖的小型静态帧合成器，以及一份可读的 scene.pkg / .tex 图层格式参考实现。

特点

- 读取你真实的壁纸库 —— 指向你的 Steam 创意工坊目录，列出每一张订阅壁纸的名称。
- 全分辨率原图 —— scene.pkg 里的画面其实是一堆贴图图层（外加遮罩、精灵图集、着色器），由 Wallpaper Engine 在运行时按顺序混合而成。本插件解析 PKGV 容器，解码各图层（内嵌 PNG/JPEG 流、原始 RGBA、DXT5/DXT1、单通道遮罩，按标记决定是否 LZ4 解压），再按场景顺序合成。拿到的是原始 1920×1080 / 3840×2160 画面，而不是随便一层贴图或小预览图。
- 支持动态壁纸 —— 不少壁纸用的是会动的 preview.gif 而不是静态图。选择器会给这类壁纸打上「动」标记，并有开关让你在「动图」和「更清晰的合成原图」之间二选一。
- 带搜索的选择器 —— 缩略图网格，可按名称或创意工坊 ID 过滤。
- 四个实时滑块 —— 面板透明度、壁纸模糊、背景压暗、壁纸亮度。设置按浏览器保存。
- 适配明暗主题 —— 叠加色调跟随应用配色，两种模式下文字都清晰。

安装

在仓库目录下执行： sh
dsh plugin install /本仓库的绝对路径/dsh-wallpaper-engine

或者，在 DSH 会话里让 agent 调用 plugin_manager，action: install_bundle，target 指向本目录。

然后在 设置 → 插件 里确认「Wallpaper Engine 壁纸」已启用。

使用

1. 打开 设置 → Wallpaper Engine 壁纸。
2. 点 选择文件夹…，选中你的创意工坊内容目录：
- Windows：C:\Program Files (x86)\Steam\steamapps\workshop\content\431960 （或者你 Steam 库所在的位置；431960 是 Wallpaper Engine 的 Steam app id）
- Linux：~/.steam/steam/steamapps/workshop/content/431960
- macOS：~/Library/Application Support/Steam/steamapps/workshop/content/431960
3. 在网格里选一张壁纸，然后用滑块调整观感。

新下载的壁纸。 没有文件系统监听 —— 浏览器不提供目录变更事件 —— 所以你在 Wallpaper Engine 里新下载的壁纸不会自己冒出来。在设置页点一下 「重新扫描」（或者刷新页面）就会读到。
浏览器重启后。 文件夹句柄存在 IndexedDB 里。浏览器仍保留读取授权时，壁纸库会自动恢复；授权回退成「需要询问」时（这种情况必须要用户点一下），界面会显示一个 「恢复授权并扫描」 按钮，点一次即可。这是浏览器的安全规定，不是 bug。

工作原理

整个插件都在客户端运行。

1. 扫描：读你选中的目录，每张壁纸是一个子文件夹，里面有 project.json（存标题），以及 preview.jpg / preview.gif 或 scene.pkg。
2. 列清单：标题 + 小缩略图构成选择器。这一步只读很小的预览文件，所以即使壁纸库很大也很快。
3. 合成：当你选中一张 scene 壁纸时，解析它的 scene.pkg：PKGV 文件表、scene.json 的对象列表，以及每个对象的 模型 → 材质 → .tex 链路。贴图被逐一解码（内嵌 PNG/JPEG 流、原始 RGBA、DXT5/DXT1、单通道遮罩，容器标记为 LZ4 时先解压），然后自下而上合成成 1920px 宽的整幅画面 —— 也就是 Wallpaper Engine 会显示的那张图。只对你实际选中的那张做这件事。
4. 应用：原画变成一个 Blob URL，放在 position: fixed; z-index: -1 的层上。由于 CSS 绘制顺序里所有普通块级元素（html、body、#root、应用框架）都画在负层级元素之上，必须把框架背景清成透明，并用 theme.overrideTokens() 把面板 token 改成半透明 —— 这是唯一可行的办法，因为主题呈现器把这些 token 作为内联样式写在 <body> 上，CSS 规则（哪怕加了 !important）都盖不过它。

开发

整个插件就是一个手写的浏览器文件 client.js，没有构建步骤：改完刷新 DSH 窗口即可（要硬刷新，客户端模块有缓存）。

场景合成器（client.js 里 #region scene-renderer 到 #endregion scene-renderer 之间）刻意不依赖 React，除 document.createElement('canvas')、createImageBitmap、Blob 外不碰 DOM，所以可以脱离浏览器跑： sh
node test/scene-render.mjs 2372608028 # 合成，输出到 test/out/*.png
node test/scene-render.mjs 2372608028 --layers # 逐对象打印摆放结果
WPE_LIBRARY=~/.steam/steam/steamapps/workshop/content/431960 node test/scene-render.mjs ...

这个 harness 在 Node 里垫了一个 canvas，跑的是浏览器里同一份代码；只有 JPEG 的 mip 需要真正的浏览器（createImageBitmap），所以「原画本身就是单张 JPEG」的壁纸在这里会报 no layers。当初就是用它跟一份 Python 参考实现、以及壁纸自带的预览图逐张核对的：抽样库里 63 个场景包的图层栈完全一致，抽样的 id 合成结果逐像素一致（平均通道差 ≤ 2.2）。

已知限制

- 视频类壁纸不会被播放。 video 类型的壁纸是 .mp4 而不是 scene.pkg。在界面背后持续解码视频会一直占用 CPU，所以这类壁纸用它们的预览文件 —— 而当预览文件是 preview.gif 时，它正好是动的，等于白捡了动态效果。
- 动态选项是拿清晰度换动作。 preview.gif 只有几百像素宽，所以优先用它会明显比合成的 scene.pkg 原图糊。在抽样的壁纸库里，86 张中有 36 张带动态预览，其中 21 张同时也有 scene.pkg —— 也就是说对它们而言这个开关是真的会改变效果的。
- 少数场景会回退到预览图。 如果一张场景壁纸的主体是 puppet（骨骼形变网格，需要单独的网格光栅化器）或者位置由脚本驱动的图层，合成出来就会缺主体、或者是一片纯色；这时改用预览图 —— 糊，但至少是原画。抽样库里 63 个场景包中有 2 个属于这种情况。
- 精灵图集会被跳过。 动画图集整张贴上去会把所有帧一次显示出来，所以这类对象不参与合成；它们都是飘落的花瓣、火星之类的点缀，从来不是画面主体。
- 不同壁纸的清晰度差别很大，设置页也会如实告诉你：它会显示合成尺寸和图层数，低于 1280px 的会标黄提醒。原因有两个。一是源图本身：抽样库里 Wallpaper Engine 的 preview.jpg 从 160px 到 1080px 不等，而某些 scene.pkg 的原画本来就是一张小贴图。二是 background-size: cover 会按“需要放大更多的那条边”来缩放，所以一张方形的 728×728 预览图在宽窗口里是按宽度放大的，放大倍数远高于 1920×1080 的图。把「壁纸模糊」调高能相当有效地掩盖低分辨率源图。
- 刷新后可能需要重新选文件夹，取决于浏览器对目录句柄的持久化行为。
- Steam 的每张壁纸文件夹以创意工坊 ID 命名，看不出画面内容；标题来自各自的 project.json。

致谢与免责

本插件是非官方作品，与 Wallpaper Engine（作者 Kristjan Skutta）及 DeepSeek 均无隶属、赞助或背书关系；提及二者的名字只是为了说明它适配什么、跑在哪里。

仓库内不附带任何壁纸素材。插件只读取你自己机器上已有的壁纸文件，在内存里合成后作为 Blob URL 放到界面后面 —— 不上传、不复制进仓库、不再分发。你显示的画面版权仍属原作者，Wallpaper Engine 自身的条款也照旧适用于它下载的那些文件。

场景合成用到的格式知识（PKGV 容器、TEXV/TEXB 贴图容器、LZ4 块结构、DXT 块）属于社区公开的逆向成果；本项目的实现是照着文件结构本身写的，并用真实壁纸包逐层验证过，未包含任何第三方项目的代码。值得一提的前作（换个角度讲同一套格式，值得一读）：RePKG 与 linux-wallpaperengine。

许可

MIT。壁纸画面的版权属于各自的作者 —— 本插件只读取你自己机器上的文件，不附带任何壁纸。