wallpaper-engine-dsh

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

wallpaper-engine-dsh

[English](README.md) | [中文](README.zh.md)


一个 DSH bundle:把本机 Wallpaper Engine 壁纸库变成 DSH web GUI(dsh web)的动态背景。视频壁纸在聊天界面背后播放,网页壁纸直接渲染。交叉淡入、液态玻璃面板、随壁纸自适应的可读性遮罩、手动取景、轮播列表、搜索与中英双语界面,集中在一个专门的设置分区里。

功能

只列出能真实播放的壁纸。 网格中列出浏览器可以真实渲染的全部类型——视频与网页壁纸。场景/应用壁纸是 Wallpaper Engine 私有的 .pkg 场景包,浏览器无法执行,因此直接过滤,不以降级的静态图代替。列出的每张壁纸都真实播放,并按 视频/网页 标注类型;搜索框可按标题或创意工坊 ID 筛选较大的壁纸库。

任何壁纸上文字都可读。 遮罩颜色始终与文字颜色相反:深色主题用黑色遮罩,浅色主题用白色遮罩,因此过亮或过暗的壁纸都不会盖住文字。在此基础上,「智能可视」每隔几秒采样一次壁纸亮度,亮度过高或过低时自动加强遮罩(网页壁纸的像素在沙箱中读不到,改用其预览图作为采样依据)。壁纸激活时,下拉菜单、斜杠命令提示框、队列面板、设置弹窗与图片灯箱统一为磨砂玻璃:外壳的菜单原语自身带隔离属性,其内部模糊层在宿主原样下并不生效,插件改为在 surface 元素上施加模糊,并把菜单底色加深,保证浮层文字在任意壁纸上可读。玻璃材质本身对齐苹果液态玻璃(Liquid Glass)的构成:非对称边缘高光(顶边受光多于侧边,四边等亮会扁成描边框)、随同一份亮度采样自适应的明暗(壁纸偏亮时压暗熔融;偏暗时仅极轻微提亮,暗场景保持通透、不发灰)、一层颗粒贴图防止模糊背景出现色带,以及仅在 Chromium 系引擎下启用的边缘折射——由圆角矩形距离场生成一张位移贴图,经 feDisplacementMap 叠在模糊链最前级,光在玻璃边缘弯折。「熔融」不止覆盖插件亲手改造的表面:外壳其余锚定浮层消费的 --dsw-menu-backdrop-filter 令牌被插件重指向滑杆驱动的滤镜链,所有浮层同一强度。第三方全页表面若直接把应用底色画为自己背景(透明化覆盖会把它们变成「洞」),同样按弹窗材质适配——ds-harness-remote 的工作台页面即通过其稳定的 dshRemotePage 类名适配。输入卡与消息气泡按 HIG 的「clear」变体处理(浮在媒体上的高透玻璃):采样亮度威胁当前主题文字时,玻璃内部的暗化层自动升起,上限 0.35,即 HIG 对该场景给出的数值。关闭壁纸后恢复宿主原样。

手动取景。 先选基础排布(填充、适应、拉伸、原始、自由),再手动调整画面:点「调整画面」将壁纸全屏展开,滚轮缩放,拖动平移。填充等无缝排布下,画面在 100% 倍率时已铺满屏幕,先滚轮放大后拖动平移才会生效(提示条会同步说明)。前四种排布下裁剪范围经过限制,画面始终铺满屏幕,不露出边缘;「自由」把壁纸按原始大小放在黑色画布上,可拖动到任意位置,缩放范围 0.1–4×,并可旋转任意角度(±90° 按钮或 Alt+拖动),同时始终保留一小块在屏幕内,不会拖丢。「镜像」水平翻转壁纸,所有排布下都可用——翻转不会破坏铺满。按 Esc 或点「完成」退出,取景设置会保存,「重置裁剪」可一键恢复默认。网页壁纸使用相同的排布下拉与缩放/平移/旋转取景(变换直接作用于 iframe)。

四个实时滑杆。 壁纸模糊、暗化、边框、玻璃,每一步调节立即生效并保存。模糊在原位渲染:任意模糊度下,画面的比例、排布与取景完全一致;屏幕边缘一个模糊半径内的画面向遮罩过渡,被界面边饰覆盖,通常不可见。模糊时叠加轻微噪声,消除渐变色带;模糊为零时媒体完全绕过滤镜管线,像素保持不变。玻璃滑杆的「色彩熔融」在 40px 满档时正好等于外壳官方菜单材质的配方(blur(40px) saturate(150%)),满档玻璃与外壳原生磨砂观感一致;低于满档则在「液态」(约 8–12px,即默认值)与「磨砂」之间调节,饱和度全程保持外壳的 150%。同一个滑杆同时驱动边缘高光强度(玻璃越厚,受光越多)与折射透镜的开关;归零时玻璃滤镜链整体退为 none,各表面回到半透明底色。

轮播列表。 可以创建任意多个列表,各自指定壁纸集合、切换间隔(1–120 分钟)与顺序(顺序/随机)。当前列表至少有两张可用壁纸时才会自动轮转;状态行始终显示轮转是否正在运行。首次运行会自动导入第一个可播放的 Wallpaper Engine 播放列表,其他播放列表也可随时导入到任意列表。

资源监控。 实时帧率读数与低帧率提示,页面隐藏或电量不足时可选自动暂停。系统开启 prefers-reduced-motion 时视频默认暂停。

中英双语。 界面跟随 DSH 的「语言」设置(中/英),也可在面板中手动指定。

播放出错自动恢复。 切换与关闭均以淡入淡出过渡。媒体连续解码失败时,先使用新令牌重试一次;仍失败则改用预览图,并在状态行说明;没有预览可用的条目则清空选择,避免黑屏。下次「刷新」会重新尝试原媒体。刷新会更新全部 URL,并直接替换正在播放的元素的地址,播放进度保留。后台重建清单时复用相同 URL,不会中断正在播放的流。

安装

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

或从源码检出安装(便于开发,改动即时生效):

git clone https://github.com/Weilv-D/wallpaper-engine-dsh.git
dsh plugin --profile web add link:<克隆文件夹的绝对路径>

重启 dsh web,在左侧会话列表点「设置」,侧栏选 壁纸背景。

使用

1. 从缩略图网格选择壁纸,它会在界面背后淡入。壁纸库较大时用搜索框快速定位。

2. 暂停/播放 控制视频播放;关闭 淡出壁纸;刷新 重新扫描壁纸库——新订阅的创意工坊壁纸无需重载页面即可出现,已改用预览图的壁纸也会重新尝试播放原媒体。

3. 用滑杆调节融合效果。壁纸画面复杂时调高 暗化 和 边框 直到文字清晰;开启智能可视后这些自动完成。界面跟随 DSH 明暗主题,无需手动适配。

4. 排布 一行决定基础摆放,点「调整画面」在画布上直接拖动平移、滚轮缩放取景。

5. 用 新建 创建轮播列表,从网格挑选或导入 WE 播放列表,然后开启 自动轮转。

6. 资源行显示当前帧率与两个自动暂停开关。

你的选择与每一项调节都持久化在浏览器的 localStorage 中。

桌面端

桌面端与浏览器共用同一前端和同一注入管道,platform: "web" 声明即可生效,无需单独的桌面包。

• Windows:主窗口不透明,壁纸渲染在 DOM 层。顶部窗口控制按钮条是宿主维护的实色 overlay,插件用一条与 overlay 同色的短渐变把壁纸衔接过去,弱化接缝;进入全屏时自动关闭。
• macOS:外壳侧栏为系统原生 vibrant 材质,壁纸在其后播放时透出的是系统材质而非壁纸本身,为外壳既定行为。
• 系统关闭透明效果(prefers-reduced-transparency)时,玻璃与模糊全部退为实色表面,壁纸保留,可读性由遮罩与实色表面保证。系统开启增强对比度(prefers-contrast: more)时,玻璃底色接近不透明、发丝环升级为实线边框,模糊本身保留。

工作原理

bundle 分为两半:

• 宿主插件 负责发现 Wallpaper Engine 安装位置(Steam 注册表项、libraryfolders.vdf、Windows/macOS/Linux 标准探测路径),从默认项目、我的项目和创意工坊目录枚举壁纸,只保留浏览器可渲染的类型,并通过同源路由提供 JSON 清单与媒体数据:
• GET /we-background/inventory[?refresh=1]
• GET /we-background/media/<token>[/<入口文件或子资源>…] —— 支持 HTTP Range,视频可拖动进度。网页壁纸的 URL 直接定位到入口文件(如 …/media/<token>/index.html),文档 URL 与壁纸目录结构一一对应,壁纸内部的相对引用(脚本、样式、图片、fetch)按 Wallpaper Engine 自身的规则解析;媒体响应带 Access-Control-Allow-Origin: *,沙箱 iframe(不透明源)里的壁纸也能 fetch 自己的资源
• GET /we-background/preview/<token>
• 浏览器插件 把选中的壁纸渲染在应用框架之下的固定层,提供设置界面,所有视觉效果都读取 DSH 设计令牌,主题切换时自动适配。

媒体服务在多个层面做了防护:令牌是无法猜测的 72 位随机值,清单重建时保持不变(后台刷新不会中断正在播放的流),只在显式刷新时重新生成;子资源路径先做词法包含检查,再对照真实文件系统复核,符号链接无法指向壁纸目录之外;HTML 与 SVG 响应带 sandbox CSP,不能以 DSH 源的身份执行;壁纸 iframe 固定使用中性 color-scheme,外壳的深色主题不会泄漏进(并破坏)第三方壁纸应用;媒体响应的 CORS 通配只允许持有令牌的一方读取其本来就能请求的文件,访问权限仍由令牌决定,且整个服务只监听本机回环地址;长度不足的响应会直接中断,而不是悄悄截断。清单由宿主缓存 30 秒;安装位置的发现过程在请求路径之外异步执行,并缓存 10 分钟。本插件不注册模型工具,不占用 prompt。

限制

• 场景与应用壁纸不出现在列表中:它们是 Wallpaper Engine 私有的 .pkg 场景包,动态渲染只能由桌面端的 Wallpaper Engine 完成。
• 网页壁纸与页面存储隔离,需要跨加载保存状态的壁纸无法保留状态。
• 带声音的网页壁纸可能在你与页面交互前保持静默——浏览器对沙箱文档的音频有自动播放限制;依赖 Wallpaper Engine 系统音频输入的壁纸(如音频可视化)在浏览器中没有信号可画。
• 视频编码受浏览器解码能力约束。浏览器可以直接播放 H.264/AVC、VP8/VP9 与 AV1;创意工坊中用 H.265/HEVC 压缩的视频在多数机器上无法软解——之前表现为只有一片黑色,现在检测到「声称在播放但解不出任何帧」时会自动降级为预览图并在状态行说明。手工转码为 H.264 的 mp4 或 VP9 的 webm 即可完整播放。
• 玻璃效果读 DSH 设计令牌;若未来外壳重构重命名令牌,磨砂会退化为普通半透明。

开发

npm install        # prepare 钩子自动构建 lib/client.js
npm test           # 纯核心单元测试 + 线级宿主集成测试
npm run build      # 从 src/client.js 重新生成 lib/client.js
npm run verify     # 在 vm 沙箱中启动产物并断言行为

目录结构:lib/core.js(纯逻辑,有测试)、lib/index.js(宿主插件)、src/client.js(浏览器源码)→ lib/client.js(构建产物,请勿手改)。npm run prepublishOnly 执行完整门禁:test → build → verify。

发布

发布由 GitHub Actions 通过 npm Trusted Publishing(OIDC,无需存储令牌)自动完成。本地只需一条命令:

npm run release          # 补丁版本;另有 release:minor / release:major

它会提升版本号、提交、打 v<版本号> 标签并一并推送。标签推送触发发布工作流:完整门禁 → 校验标签与版本一致 → npm publish --provenance → 自动创建带更新说明的 GitHub Release。