液态玻璃壁纸 XINGRUYU33224/dsh-liquid-glass-wallpaper

液态玻璃壁纸

一个 DSH Web GUI 插件，读取你的本地 Wallpaper Engine 库，并将壁纸渲染为 harness 背后的全视口液态玻璃背景：磨砂扩散、镜面光泽、色彩暗角以及胶片颗粒层，全部可通过设置卡片实时调节。

你的壁纸是你自己的本地文件，插件只在本机读取和播放，不会上传、不会分发。
Workshop 内容版权归原作者所有。

功能说明

- 读取真实的 Wallpaper Engine 库。 通过注册表、每个 libraryfolders.vdf 条目以及持久化的 appmanifest_431960.acf 发现 WE 安装位置（Steam 应用 431960），然后枚举 Workshop 内容、myprojects 和 defaultprojects。可手动添加额外文件夹。
- 渲染为液态玻璃背景。 在 shell 背后有一个固定层，包含：
- backdrop-filter: blur() saturate() 磨砂，
- 柔光镜面光泽，
- 用于提升界面元素可读性的径向暗角，
- 内联 SVG 胶片颗粒，消除模糊色带，
- 可选指针视差（几像素，有深度感而不松散）。
- 实时设置卡片 — 设置 → 液态玻璃壁纸：启用开关、四个玻璃滑块（磨砂 / 饱和度 / 色调 / 暗角）、颗粒 + 视差 + 适配开关、一个可搜索且按类型筛选的所有壁纸网格，以及一条“当前壁纸”栏。
- 跨刷新记忆。 选择和玻璃设置持久化在 localStorage 中，并在启动时恢复。
- 范围流式传输。 视频通过 HTTP 206 提供，因此大型 4K 文件可以跳转和循环播放，而无需缓冲整个文件。

支持的壁纸类型

| 类型 | 渲染方式 | 备注 |
| video | 循环、静音、自动播放 | 液态玻璃效果最佳，也最清晰：4K 源可原生解码。下方会绘制一张静态预览图，因此解码时背景绝不会是黑色。 |
| image | | 以源分辨率直接渲染。 |
| web | 沙盒化的同源 （allow-scripts） | Web 壁纸会以同源方式运行自己的 JS。只安装你信任的壁纸。 |

为什么不提供场景壁纸

它们曾被尝试过，但已被移除。场景的真实内容位于 scene.pkg 中，而本插件无法重放它——唯一可用的静态图是项目自带的 preview.jpg，在真实库中它是 1:1 且最大 1080×1080。用它填满 16:9 窗口意味着中位数 1.56×、最坏情况 11× 的放大，因此无论怎样调整玻璃设置，每个场景看起来都很模糊。

.pkg 本身也无法读取。索引格式已被还原（u32 pathLen | path | u32 offset | u32 length，连续，无填充），并在全部 45 个项目上验证通过，但负载字节无法映射到其声明的文件名，因此仍有一层未知结构。
resourcecompiler64.exe、resourceutil64.dll 和 FreeImage64.dll 都已检查过解码器，但都没有提供。

要正确重放场景，需要一个用于分层 2D/3D 场景的 WebGL 播放器，以及 WE 材质语义——一个独立的项目。该插件不会发布一个总是看起来很柔和的类型，而是完全跳过场景项目，并在此说明。

安装

Windows，一条命令。 克隆并运行安装程序——它会找到你的 DSH 主目录，检测你的 GUI 正在运行哪个配置文件，使用该配置文件自带的 pnpm 从 GitHub 安装，注册 bundle 层，并验证加载树：

git clone https://github.com/XINGRUYU33224/dsh-liquid-glass-wallpaper.git
cd dsh-liquid-glass-wallpaper
pwsh -File install.ps1

然后重启你的 GUI（对于桌面应用：完全退出并重新打开，而不是刷新页面）。该部分会出现在 设置 → 液态玻璃壁纸。

有用的标志：

| 标志 | 效果 |
| -Profile | 指定特定的配置文件，而不是检测到的那个。 |
| -Local | 从此检出目录（link:）安装，而不是从 GitHub——用于开发。 |
| -Ref | 安装特定的 git ref。 |
| -SkipVerify | 跳过安装后的加载树检查。 |

安装程序是幂等的：重新运行它就是更新方式。

任意平台，手动安装

dsh plugin 会转发给 pnpm，因此 git 规格可以直接使用——而且由于该包声明了 dsh.bundle，dsh 会自动将其添加到配置文件的 bundle 列表中：

dsh plugin --profile add github:XINGRUYU33224/dsh-liquid-glass-wallpaper

哪个配置文件是我的？ 它是正在运行的主机进程的最后一个路径参数。desktop 配置文件会被 CLI 按名称 拒绝（managed exclusively by the Electron application），尽管它是一个普通的 cordis 配置文件。install.ps1 通过直接驱动应用自带的 pnpm 来处理这一点；手动操作则是：

cd "$DSH_HOME/profiles/desktop"
"/resources/runtime/bin/node/node.exe" \
"/resources/runtime/pnpm/bin/pnpm.mjs" \
add github:XINGRUYU33224/dsh-liquid-glass-wallpaper

然后将 "dsh-liquid-glass-wallpaper" 添加到该配置文件的 package.json 中的 dsh.profile.bundles。写入时不要带 BOM——BOM 会导致启动加载器失败并报 Unexpected token。

要求

- 通过 Steam 安装的 Wallpaper Engine（应用 431960）。没有它，该部分仍会加载并说明未找到库。
- Node 20+——仅用于安装程序/测试。该插件运行在 DSH 自己的运行时上，并且没有运行时依赖。
- Windows 用于壁纸发现（Steam 注册表 + libraryfolders.vdf）。背景引擎本身是平台中立的；在其他平台上，手动库文件夹是后备方案。

验证你的安装

npm run verify # 85 checks: host, client, bundle, Range, lifecycle
python scripts/verify-final.py shots/ # live end-to-end in a real browser
python scripts/verify-coverage.py shots/ # media covers the viewport

浏览器测试套件需要 Playwright（pip install playwright && playwright install
chromium）；插件本身除了 Node 的标准库之外不需要任何东西。

配置

该卡片会写入 localStorage["liquid-glass-wallpaper/v1"]：

| 键 | 默认值 | 含义 |
| enabled | true | 整个背景层的总开关。 |
| activeId | null | 选中的壁纸 id（workshop: / local: / manual:）。 |
| blur | 28 | 磨砂半径，0–60 px。 |
| saturation | 118 | 背景饱和度，60–220 %。 |
| tint | 12 | 玻璃上的深色着色，0–60 %。 |
| vignette | 34 | 边角衰减，0–80 %。 |
| grain | true | 胶片颗粒叠加层。 |
| parallax | true | 指针驱动的视差。 |
| fit | cover | cover 或 contain。 |

手动库文件夹也可以作为插件配置传入（manualDirs: string[]）。

HTTP API

所有路由都位于 /api/liquid-glass/ 下，同源防护（跨站 Sec-Fetch-Site/Origin 会以 403 拒绝；非 GET 请求以 405 拒绝）。

| 路由 | 用途 |
| GET /api/liquid-glass/inventory[?refresh=1] | 库清单，带有令牌化的媒体 URL。 |
| GET /api/liquid-glass/media/ | 支持 Range 流式传输的视频/图像。 |
| GET /api/liquid-glass/preview/ | 预览静帧。 |
| GET /api/liquid-glass/web// | 网页壁纸文档。 |

不透明令牌，绝不是路径。 媒体通过每次清单响应时生成的随机 144 位令牌来寻址，并通过一个内存中的、有上限的映射（4096 个条目，淘汰最旧的）来解析。有两点很重要：

- 令牌不是路径的编码。它不可逆，因此同源脚本（网页壁纸就是同源脚本）无法将 /inventory 解码为用户本地目录结构；
- 该映射从不写入磁盘，因此进程之外的任何东西都不会得知这些路径，而且它在多次重新扫描之间也不会无限制增长。

无论如何，客户端提供的路径都绝不可能到达文件系统。

Range 支持

Accept-Ranges: bytes 并具有正确的 206/416 行为，已在 17 个用例中验证：开放式（bytes=500-）、后缀式（bytes=-500 → 根据 RFC 9110，为最后 500 字节）、末端截断、无法满足时返回带 Content-Range: bytes /N 的 416，以及多范围或未知单位请求回退为完整的 200，而不是误导性的截断 206。视频拖动进度依赖于此。

布局

lib/
index.js 宿主入口：注入 ["webServer"]，注册路由族 we-library.js Steam/WE 发现 + project.json 枚举（无依赖） routes.js 不透明令牌、同源防护、支持 Range 的 HTTP 路由 client.js 已构建的 bundle（window.__ModuleLoader__.load）——请勿手动编辑 src/ client.js 客户端源码（纯 ESM）；build-client.mjs 会将其包装 scripts/ build-client.mjs 将 src/client.js 包装进加载器 bundle（+ --check） verify.mjs 运行所有测试套件 test-build.mjs 构建完整性 + 证明防护会拒绝错误输入 test-imports.mjs 每个模块都能加载并暴露其契约 test-client.mjs 打包契约 + apply() 接线 + 背景 DOM test-lifecycle.mjs 无 时的启动安全性 test-host.mjs 清单 + 流式传输 + 令牌不透明性 + 围栏，真实库 test-range.mjs Range 边界情况（后缀、钳制、416、多范围） verify-.py 实时 Chromium 检查（卡片、背景、玻璃层级、泄漏）

为什么客户端是构建出来的

DSH 客户端加载器将客户端插件发现为单个自注册打包文件：

window.__ModuleLoader__.load({ id: 'dsh-liquid-glass-wallpaper', factory: (require) => { … } })

src/client.js 保持可读的 ESM（export const name/inject、export function apply），而 scripts/build-client.mjs 执行封装转换。编辑源文件，然后运行 node scripts/build-client.mjs。直接编辑 lib/client.js 会被覆盖。

为什么该层要重新装饰外壳

外壳在其自身的容器上绘制了硬编码的 rgb(255,255,255) / rgb(249,250,251)。
这些容器是该层的兄弟节点，而非祖先节点，因此背景上的任何 z-index 都无法胜出：在 z-index: 0 时它被覆盖，而在负 z-index 时它会落到文档背景之后。

因此，该层不是与绘制顺序对抗，而是在其激活期间重新装饰外壳，分两个按几何范围划分的处理阶段：

| 表面 | 测试 | 处理 |
| 背景根节点 | 覆盖视口的 ≥70% | background-color: transparent |
| 界面面板（侧边栏轨道、对话记录列） | 全高（≥视口的 80%），宽度 120 px–75% | 磨砂玻璃：半透明表面 + backdrop-filter |

这两个阶段都不会触及卡片、按钮、输入框或对话框：它们既不是背景尺寸，也不是面板形状。每个元素先前的内联 background-color 都会被记录，并且玻璃面板携带单个类，因此拆除（禁用该层或 destroy()）会恢复确切的先前状态。MutationObserver 会在外壳重新渲染后重新应用（打开设置、切换会话），合并为每动画帧一次处理。

这一点很重要，因为原版配置没有皮肤来使外壳透明——这正是 desktop 的情况。web 配置之所以看起来有效，是因为 maid-atelier 处于激活状态，并且它的皮肤 CSS 为我们完成了这件事。

媒体尺寸调整

媒体元素精确覆盖视口，并让 object-fit 处理所有宽高比处理。早期版本还应用了 inset: -6% + width: 112% + scale(1.06)：三个不同原点的过度缩放，导致媒体偏离中心并留下一条裸露的条带——在更宽的窗口中使用 16:9 壁纸时最为明显。视差现在是在单一均匀的
scale(1.06) 之上的纯平移，因此每条边缘都保持覆盖。
verify-coverage.py 针对视频和图像壁纸在三种窗口形状下断言了这一点。

值得了解的坑

- inject 必须列出你触及的每一项服务。 读取 ctx.locale 而不声明它会抛出 cannot get property "locale" without inject，并导致整个

- 启动时插件已停止。
- settings.section 需要 inject 属性提供者。 不带它注册会成功并返回一个 disposer，但该行永远不会出现在设置导航中。
- 卡片的 CSS 带有 !important。 一个活跃的目录皮肤会附带 L3 补丁，重新样式化通用选择器；普通的行内 display:grid 会失效。所有结构规则都限定在 [data-lgw-card] 作用域内。
- 桌面配置文件是按名称而非结构被 CLI 锁定的。 dsh plugin --profile desktop … 会被拒绝（managed exclusively by the Electron application），但该配置文件是一个普通的 cordis 配置文件：使用应用自带的 pnpm 安装 —— 在 $DSH_HOME/profiles/desktop 下运行 node /pnpm/bin/pnpm.mjs install。
- 桌面配置文件没有主题令牌。 --dsw-alias- 在那里解析不到任何值，因此卡片会回退到其字面颜色；这是预期行为，不是 bug。
- cordis.patch.yml 条目可能缺少插件。 默认的桌面补丁引用了 ui-settings-account，它随 @linxin666/dsh-web-all 一起发布；没有该包时，该条目会记录 not found 并被跳过。无害，且是既有问题。
- 带空格的路径会破坏 link: 安装。 pnpm 会拆分参数并安装一个被截断的路径，因此请克隆到无空格的目录中。

安全模型

- /api/liquid-glass/ 针对回环 CSRF 威胁模型进行了防护：
- 当存在 Sec-Fetch-Site 时，它必须是 same-origin 或 none（跨站页面无法抑制它）；
- 当存在 Origin 时，它必须是服务端口上的回环权威，并对照服务器端列表进行检查。它刻意不与请求自身的 Host 头进行比较 —— 后者受攻击者控制，因此 Origin: http://evil.test 搭配 Host: evil.test（DNS 重绑定场景）会以 403 被拒绝；
- 两个头都不存在的请求是非浏览器客户端（curl、原生应用）。它们不在该防护所针对的浏览器威胁模型范围内，也无法被恶意网页驱动。
- 任何客户端提供的路径都不会到达文件系统（不透明令牌间接寻址）。
- 令牌是随机的且仅存在于内存中 —— 见上文“不透明令牌”。
- 媒体文件以只读方式打开并流式传输；不会写入插件自身缓存之外的任何内容。
- 网页壁纸是沙箱化的 iframe（allow-scripts），但以同源方式运行脚本 —— 请将网页壁纸视为你选择运行的代码。
- 不会上传任何内容。没有遥测，也没有网络出口。

测试覆盖

node scripts/verify.mjs 在 7 个套件中运行 85 项检查：

| 套件 | 检查数 | 覆盖范围 |
| 构建客户端包 | — | 生成 lib/client.js |
| 构建完整性 + 守卫 | 18 | UTF-8 保真度、CJK 标签保留、--check 陈旧性、守卫拒绝无导出 / 游离导出 / 重复导出 |
| 导入契约 | 4 | 每个模块都能加载并暴露其 API |
| 客户端包契约 | 20 | __ModuleLoader__ 形态、apply() 接线、背景 DOM、样式表注入 |
| 启动生命周期安全性 | 4 | apply() 能在没有 的文档中存活 |
| 宿主路由 + 库 | 26 | 真实的 119 张壁纸库、Range 流式传输、不透明不可逆令牌、跨站/重绑定拒绝 |
| HTTP range 边界情况 | 17 | 后缀、开放式、钳制、416、多范围 |

实时浏览器测试套件（verify-card.py、verify-final.py、verify-coverage.py、 verify-visible.py、test-leaks.py）还会驱动真实 GUI：卡片渲染、壁纸选择、持久化恢复、0→60 px 的毛玻璃模糊、三种窗口形状下的媒体覆盖、遮挡，以及 24 次切换的泄漏检查。

贡献

客户端部分已构建完成：编辑 src/client.js，然后运行 npm run build。不要手动编辑 lib/client.js —— 它是生成文件，当它过期时 npm run check 会失败。
在提交 PR 之前，运行 npm run verify；所有测试套件都必须通过。

有两个值得了解的陷阱，它们在这里都耗费了真实的调试时间：

- src/client.js 中的 CSS 和 HTML 字符串是反引号模板字面量。注释或 CSS 值中的反引号会静默结束字面量，并在远离原因的地方产生语法错误。构建脚本会检测到这一点并指出位置。
- inject 必须列出你触及的每一个客户端服务（slots、locale、……）。读取一个未声明的服务会在启动时抛出异常，并导致整个插件崩溃。

隐私

无遥测、无网络出口、无分析。该插件读取你本地的 Wallpaper Engine 库，并通过回环将其提供给你自己的 GUI。没有任何内容离开本机。

许可证

MIT —— 关于壁纸内容边界，请参见 NOTICE。

壁纸文件不属于本项目，且绝不会被再分发。创意工坊内容归其作者所有；该插件只读取你磁盘上已有的内容。