dsh-plugin-wallpaper-engine

English | 中文 | 小白向指南

🆕 没用过命令行？先看这里：小白向使用指南（新手快速上手）→ —— 给完全没接触过命令行的用户准备的简化说明。

一个 DSH bundle，把你电脑上的 Wallpaper Engine 壁纸变成 DSH 网页界面（dsh web）的背景。

壁纸 + 磨砂遮罩 + iOS 液态玻璃，渲染在 DSH 界面后方。

目录

• 能做什么 · 更新前置条件 · 支持哪些壁纸类型 · 工作原理
• 安装 · 使用 · 配置 · 与 dsh-better-sidebar 的兼容适配 · 已知限制 · 开发 / 重建 · 联系方式 · 致谢
• 版本号、issue 号与性能数字见 docs/CHANGELOG.md；升级前置条件见 docs/UPGRADING.md。
• 📦 npm 包不带 docs/（随包的是运行期文件：lib/**、cordis.patch.yml 与三份 README）⇒ 上面这些 docs/… 链接在 npm / 插件市场里点不开，请到源码仓库 https://github.com/elysia395/dsh-wallpaper-engine 的同名路径阅读。

能做什么

它会自动发现你本机的 Wallpaper Engine 安装，列出你的壁纸，并把可移植的类型渲染到 DSH 对话界面后方的固定图层，配以 iOS 风格的液态玻璃界面改造。

版本号、issue 号与性能数字一律记在 docs/CHANGELOG.md。

壁纸渲染（核心）

• 三类壁纸，三条渲染路径：Video 直接播放；Web / HTML 走内置 WebWallGL 的网页挂载（宿主注入 WE API + 严格沙箱隔离）；Scene（场景） 由内置 WebWallGL 实时 WebGL 引擎渲染 —— 粒子系统、puppet 骨骼模型、SceneScript 脚本、鼠标视差与点击交互、包内音频与音频反应。
• 实时优先、逐级降级：场景 / 网页壁纸由内置渲染器实时渲染；渲染页有心跳看护，真的出不了帧就按一条降级链逐级回退，首帧之前不留黑屏，最后一级允许诚实留空。

  降级链的顺序、看护判据、失败记忆分层与垫底画面来源只在 docs/HOW-IT-WORKS.md 定义一处 —— 本文只承诺"不会黑屏、不会被一张坏帧永久卡住"， 不重复它的步骤（重复一份就会在下一次改动时漏改一处）。

• 高帧率源可降载：帧率上限把 4K120 这类源一次性转成上限帧率（4K 保留 + AV1），显著降低 GPU 占用；遮挡暂停三档在最小化 / 失焦 / 电池供电时直接停解码。
• 能搬的都搬：本地 JPG / PNG / MP4 可直接上传当壁纸；自定义轮播列表按各自的间隔与顺序自动换壁纸（就绪后才切，不黑屏）。

界面改造（核心）

• 跟随 DSH 的界面语言：插件界面接进宿主的语言设置（设置 → 通用 → 语言）—— 语言目录与 dsh web 完全一致（内置 中文 / English，装了语言包也一并跟随）；切换即时生效，不需要重载页面，设置页、选择器、右栏 / 抽屉、吉祥物、字体集与更新说明全部跟着换。
• 整个设置窗口液态玻璃（恒开）：DSH 原生设置窗口整体（对话框 + 左导航 + 全部原生分区）都走玻璃配方 —— 原先那个"设置窗口液态玻璃"总开关已退役（实测那个"关"回不到原生纯色），配色 / 玻璃底色 / 透明度 / 雾化仍可调；逐面细调见「设置窗口玻璃·独立配置」。
• 文字面保底：承载文字的面固定压一层主题底色，最坏情况正文对比度 4.63:1 —— 滑条调到极端也不会把字压得看不清。
• 字体与光标可细调：字体按颜色角色 / 排版角色 / 组件三层细化（字号、字重、字族各自可设）；输入光标独立取色。整套外观可存成字体集（随包自带预设，可新建 / 重命名 / 删除 / 恢复原样，也能导出导入 .json 分享）。
• 预设 = 整机配置快照：「外观」页的配置预设一键套用整套配置 —— 不再只是玻璃：全部观感与行为设置总是携带，字体 / 吉祥物立绘 / 会话头像按需勾选一并带上；预设可导出 / 导入 .json 在用户之间流转（导入不立刻应用）。旧版只存玻璃子集的预设已作废，升级后重新保存一份即可。
• 壁纸与界面融合可细调：壁纸模糊、亮度 / 对比度 / 饱和度、壁纸透明度、暗化、边框、雾化，全部即时生效。

特色功能

• 吉祥物：聊天顶部一条可拖拽的拉绳，向下拉出壁纸仓库抽屉（两套立绘、可缩放），快捷调节随身可用。
• 侧边栏液态玻璃：为 dsh-better-sidebar 的侧边栏专门适配（毛玻璃、高光与层级统一），另有一组独立的侧栏玻璃控制。

更新前置条件

⚠️ 本插件要求 DSH 内核 ≥ 0.1.5（0.1.5-rc.1 起——官方桌面端线与 DSH Desktop ≥ 2.0.7 线都满足；实测下限）。dsh-better-sidebar 不再有版本限制（装了的话建议顺手更新到最新）。版本矩阵与升级注意事项见 docs/UPGRADING.md。

支持哪些壁纸类型？

Wallpaper Engine 本体把壁纸分四种类型；本插件支持其中的三类：

四类壁纸各自的渲染路径、优雅降级、出图来源链与空帧门禁、以及排查用的诊断行， 见 docs/HOW-IT-WORKS.md。

工作原理

一句话：宿主（lib/index.js + lib/routes/*.js）负责找到 Wallpaper Engine 与你的壁纸库、 把媒体按需喂给浏览器；客户端（lib/client.js）负责把选中的壁纸挂到应用三列后方的固定图层， 并在「设置」里注册一个一级页签「Wallpaper Engine」。

出图来源链（实时渲染 → 内嵌 MP4 → 实时抓帧 → 自定义画面 → 空态）、宿主/客户端分工、 全部 HTTP 路由表、以及"为什么没有 CPU 兜底出图"的设计理由，都在 docs/HOW-IT-WORKS.md。实现细节以代码注释为准（本仓「代码即真相」）。

安装

普通用户（安装已发布版本，推荐）

如果你只是想用这个插件，直接装 npm 上已发布的包即可：

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

装完重启 dsh web，打开 设置 → Wallpaper Engine 就能用。

macOS / Linux 用户：本插件在 Windows / macOS / Linux 上原生可用 —— 三平台装的是同一个包、同一条命令（媒体链路也各自原生：GSMTC / MediaRemote / MPRIS）。

macOS 没有 Wallpaper Engine 客户端，因此扫不到 Steam 壁纸库：把「自定义壁纸」的存储位置指到一个装着 WE 工程目录的文件夹（project.json + scene.pkg / index.html / *.mp4），里面的场景 / 网页 / 视频壁纸会照常收录、场景同样实时渲染；也可以直接上传图片 / 视频。

开发者（运行你本地的一份代码）

用 link: 装本地一份代码、构建与验证、热挂载与编码铁律（含 lib/client.js 到底是什么）见 CONTRIBUTING.md。宿主端改动要重启 DSH 才生效（CLI 装的走 --profile web，桌面端走 --profile desktop 且必须先完全关闭应用）。

安装失败排查

装不上（ERR_PNPM_UNEXPECTED_VIRTUAL_STORE 等）的逐步处置，见 docs/TROUBLESHOOTING.md。

使用

1. 打开 dsh web，进入 DSH 界面。
2. 打开 设置，左侧导航里找到 Wallpaper Engine（一级设置页，侧边栏独立入口）；聊天顶部的拉绳吉祥物也能拉出「壁纸仓库」抽屉，两处共用同一套页签与调节项。
3. 点 选择壁纸 在页内展开库视图（不是弹窗、也没有遮罩），在缩略图网格里点选一张（**Application（应用）**类壁纸不支持，不显示在网格中）；从库视图退出即回到设置页。
4. 用 暂停/播放 控制视频壁纸，用 关闭 清除壁纸。全部选择与调节都会即时生效并持久保存（见 配置）。

设置界面：液态玻璃卡片，六个页签（壁纸库 / 外观 / 播放 / 系统 / 扩展 / 关于）。

选择弹窗：浏览全部壁纸缩略图，支持批量隐藏与已隐藏恢复。

设置的页签

设置页分六个页签 —— 壁纸库（选择 / 轮播 / 自定义上传）· 外观（配色 / 玻璃 / 光标 / 配置预设 —— 整机配置快照，可导出导入；全局字体与玻璃细调节在侧栏「外观」页，默认收起）· 播放（效果 + 声音）· 系统（吉祥物 —— 可导入自己的立绘替下内置形态（再导入即覆盖上一次；两个形态卡片在自定义生效时禁用，清除后恢复可选）+ 高级）· 扩展（后续功能的模块容器：目前挂着自定义会话头像（第一项，总开关默认关）—— 开启后宿主的会话界面被"排成好友聊天"：你的消息靠右、带头像，助手的靠左、带它自己的；头像可以导入自己的图片（只存在本机：宿主数据目录的 avatars/，导入前先缩到 512px 以内），没导入就画内置的默认头像（我方 = 人像、助手 = 四角星），形状默认正圆、大小（24–72px）与圆角强度（0–100%，100% = 正圆、0% = 直角方形）各一个滑块；关掉开关，会话立刻恢复原样（注入的节点与标记全部摘掉），它对壁纸、玻璃、字体那些设置一概不碰）与点击效果与拖尾效果（总开关默认关、按需开启）—— 它是跟着指针走的霓虹光效：点击按「涟漪」（从落点扩散的两圈圆环）/「星火」（一簇亮点向四周飞散）/「两者」在落点炸开，拖尾按「彗尾」（一条逐段收细、尾部渐隐的光带）/「星尘」（按步距留在原地的亮点）记下指针划过的一路，轨迹按「拖尾时长」自行淡完（指针停住也照淡）；整层用 lighter 叠加，颜色可跟主题色 / 彩虹（每个实例一个色相、还随时间流转）/ 自定义，不透明度与混合模式（滤色 = 只把画面加亮，最像霓虹；也可手选正常 / 叠加 / 正片叠底 / 变亮）都写在宿主元素上；点在自己的界面控件上不炸光效，监听是 passive 的、绝不拦指针；这一层刻意不读壁纸像素（所以它没有「自动」档），层级恒在壁纸之上、暗化层之上；点击 / 拖尾各有一个子开关，任一开着即生效，总开关默认关；三号 3D 效果是随光标移动的视差纵深：光标偏离屏幕中心时，壁纸与吉祥物沿关于中心对称的方向轻轻偏移，偏移量按最长对角线的百分比计（光标贴在屏幕角上时 ⇒ 该层挪它那个百分点的对角线）—— 壁纸默认 1%、吉祥物跟着壁纸一起（可单独关掉）、缓动平滑可调（0 = 立刻跟手，越大越柔和）；壁纸会同时按同样多放大，免得边上露出底色；界面元素跟随（子开关，默认关）打开后，输入卡片 / 会话文本区 / 侧栏作为整块跟着挪 —— 文字与底下的玻璃一起动（离眼睛越近走得越多：界面与壁纸同向，读起来像镜头横移；四个区域的距离各自独立（没有总倍率：会话文本区 / 输入卡片 / 侧栏 / 用户气泡各一个滑块，0 = 那一块完全不缓动）），位移量化到整设备像素（带迟滞：缓动尾巴在零附近不再来回翻，这正是「经过屏幕中线时发抖」的来路）、停下就把属性摘掉（translate 整条摘掉；属性在就成立包含块），组里有固定定位后代就整组不动；只有左上角那一列例外 —— 宿主的「收起侧边栏」按钮是它里面的固定定位后代，所以那一列走相对定位（left / top）而从不写 translate；点击与拖尾那一层刻意不参与 —— 这一层一个 DOM 节点都不建，每帧只把算完的最终位移直接写进要动的那几层自己的 CSS 独立属性 translate（不走继承型自定义属性：写在 body 上等于每帧让整棵文档树重算样式；body 上只剩一个"壁纸补边系数"，只在设置变了时写一次），位移与配比不再由样式表算；帧里零测量、跟随显示器真实刷新率；这一层还按"动的那几帧才提合成层、到位立刻摘掉"省开销（到位按屏上还剩多少位移判、系数全 0 时一帧都不排、页面不可见不排帧）；后续功能只往注册表里加一项）· 关于（项目简介 / 仓库与实时 Star 数 / 交流群二维码 / 贡献者致谢），每页只保留与它相关的控件，不再是一列三十项的长滚动。页签指示胶囊随选中项平滑滑动，长说明一律收进控件悬停提示（tooltip），行内只保留一句话简述。「关于」不读面板状态、不写设置：文案 + 两张二维码（随包 PNG，走插件自己的路由，离线也显示得出来），外部输入只有那行 star 数与这两张图 —— 切进本页时由宿主代取 GitHub API（带缓存，拉不到就显示上一次的值）。一键 Star 不做：GitHub 点星必须有你的凭据，插件不存 token —— 按钮打开仓库页，旁边另有可复制的地址。

选择与过滤

• 隐藏 / 恢复：卡片右上角的「隐藏」只把壁纸从列表移除，不删除源文件；弹窗的「已隐藏」标签可单张恢复或全部恢复，「批量」进入多选模式。隐藏当前壁纸不会打断播放，自动轮播也会跳过它。
• 内容分级：按壁纸的 contentrating 字段（WE 壁纸读 project.json，自上传内容读 uploads/.meta.json）分 全部 / Everyone（默认）/ PG13 / Mature / 未分级；自上传内容未标注时按 Everyone 处理。这个字段由插件直接扫盘读取，不跟随 WE 客户端里的成人内容开关。
• 类型：按可内嵌类型筛选 —— 全部 / 视频 / 网页 / 图片（自上传）/ 场景。
• 每个选项都带当前可播放数量；被过滤掉的壁纸会从网格、轮播编辑器与轮播候选中整体剔除，也不会被自动选中或轮换。

卡片样式与播放控制

• 紧凑布局（「系统」→「高级」里的开关）：开启即 CD 架效果 —— 卡片纵向层叠、悬停放大置顶、一页到底不翻页；关闭为常规网格（默认）。
• 黑胶唱片：选择界面旁旋转的黑胶把当前壁纸封面当唱片标签，播放时旋转、暂停即停；经典与紧凑两种卡片样式下都显示。
• 倍速：视频壁纸可选播放倍速档位，基于浏览器原生 playbackRate，即时生效、不重载不黑屏。
• 水平翻转：视频、网页与上传的图片 / 视频都生效（CSS scaleX(-1)，零主线程开销）。
• 切换过场：换壁纸（手动点选与自动轮播共用）可选的转场动画 —— 硬切（默认） / 交叉淡化 / 推移 / 擦除 / 光圈 / 缩放 / 条带，每种自带基准时长，再乘「快 / 标准 / 慢」三档，方向型过场另有方向可选；系统开启「减少动态效果」时一律按硬切处理。

适配目标（宿主形态）

「系统」→「高级」里的适配段自动识别插件跑在 原生浏览器 / 非官方桌面端 / 官方桌面端 哪一种里，并显示「检测到：… · 有 / 无能力头栅栏」；检测不准时可手选覆盖 —— 手选优先于检测。判定与操作系统无关：宿主按请求头与 UA 观测（能力头 x-dsh-desktop-renderer ⇒ 非官方桌面端，UA 含 Electron/ ⇒ 桌面壳，两者皆无 ⇒ 原生浏览器），观测结果用只增不减的闩锁记住。它同时决定四件事：网页壁纸载荷走独立媒体源还是应用源（原生浏览器没有栅栏，就不再多开一个 loopback 监听）、桌面壳材质规则是否生效（一律经 [data-we-adapter^="desktop-"] 门控，浏览器形态不吃壳层材质）、「窗口失焦时暂停」是否提供（见下），以及面板各行的显隐与警示（手选与检测冲突时直接说明后果，例如手选浏览器却观测到栅栏 ⇒ 网页壁纸会 403）。

省电与降载

「系统」→「高级」里的遮挡暂停三档（最小化 / 切页、窗口失焦、使用电池；各档默认值见控件本身）：命中时机时视频壁纸直接停解码（不靠浏览器节流，解码引擎归零），场景实时渲染同时暂停渲染循环；回到界面 / 接通电源自动继续（手动暂停过的不会被自动恢复）。其中**「窗口失焦时暂停」只在适配目标为「原生浏览器」时提供** —— 桌面壳失焦时壁纸多半仍整块可见，按失焦暂停会定格可见画面；该档的值不会被删掉，切回浏览器目标即恢复生效。

「播放」→「效果」里的帧率上限（可选档位见控件本身）针对高帧率源：宿主用 ffmpeg 一次性把源转成上限帧率（时间线保持正常速度、与倍速完全解耦），输出 4K 保留 + AV1，缓存后同一张壁纸只付一次成本。播放时先播原片、转好自动切换，设置页有实时进度条；源帧率已在上限内会自动跳过，转码失败自动回退原片。

ffmpeg 三档供给：显式指定（DSH_WE_FFMPEG 或插件目录下的 ffmpeg/）→ 自动下载（npmmirror + GitHub 双源竞速，校验后缓存）→ 系统 PATH。编码器优先 NVENC（av1_nvenc → h264_nvenc），无 NVIDIA 显卡时回落 libx264 软件编码（慢，但能出片）；只有连 ffmpeg 都拿不到时该功能才自动关闭，壁纸保持原片，不影响其它任何功能。

缓存位置（把几个 GB 挪出系统盘）

抽帧 / 转码 / 实时抓帧 / 视频缩略图这些可再生产物默认落在 ~/.dsh-wallpaper-engine/cache，也就是系统盘 —— 用得久了能堆到几个 GB。「系统」→「高级」→「缓存位置」可以把它改到任意盘符的目录（绝对路径，支持 ~）：点「更改」会弹出目录浏览器（列盘符与子目录，点着进出，地址栏也支持直接粘贴路径），改完已有缓存自动迁移过去（逐文件搬，跨盘也搬得动），旧目录只留空壳、不删。

迁移只搬插件自己的那几个缓存子目录，不认识的文件原地不动 —— 目标可以是你已有的任意目录（例如 D:\WallpaperEngineCache），插件不会去动里面的别的东西。缓存全是可再生的（所以设置页的提示是"随时可删"），最坏情况只是重跑一次转码，不会丢你的壁纸或设置。

优先级：DSH_WE_CACHE_DIR 环境变量 → 设置里的「缓存位置」→ 默认 ~/.dsh-wallpaper-engine/cache。环境变量在场时它优先，设置页显示的是实际生效的那条路径（两者不一致就是它被覆盖了）。

设置存在 config.json 的根字段 cacheDir。自定义壁纸的存储位置（默认 ~/.dsh-wallpaper-engine/uploads）在「壁纸库」页签改，同一条迁移逻辑（见上）；要把整个数据目录（含设置与头像 / 字体 / 吉祥物这些）挪走，用环境变量 DSH_WE_DATA_DIR —— 见「配置」的环境变量表。

画面调节

画面相关的十一个滑动条分居两处：「播放」→「效果」（壁纸激活后）九个 —— 壁纸模糊 · 亮度 / 对比度 / 饱和度（壁纸媒体滤镜）· 水平 / 垂直 / 缩放（壁纸层取景：位移与缩放，与 WE 壁纸属性面板那三条同名滑条同量程，右侧数值可直接键入、双击标签回默认）· 壁纸透明度（整层淡出、融向页面底色，与暗化互补）· 暗化（加深壁纸与文字之间的遮罩）；「外观」页签两个 —— 边框（「细节」段，边框 / 分割线对比度）与雾化（「玻璃 UI」节，玻璃面板模糊半径）。全部即时生效、持久保存，无需刷新页面；每个控件的取值范围与默认值直接看控件本身。

浅色 / 深色由壁纸自己决定 —— 换壁纸后插件会自动切到与壁纸相配的那一侧（取色顺序：作者的 schemecolor → 画面占比最大色（作者预览图与真实渲染帧各判一次，不一致时取深色）→ 取不到就保持不动；判定按颜色深浅，只有明显偏亮才用浅色。作者填的恰好纯黑算"没填"，会改用画面主色）。你也可以随时在 DSH 里手动改主题 —— 改过之后本张壁纸不再自动，换下一张恢复。偏亮或花纹复杂的壁纸看不清字时调高 暗化 / 边框（必要时加一点 壁纸模糊），嫌壁纸抢眼则调高 壁纸透明度。滑条再怎么调也不会把正文压到看不清 —— 承载文字的面都有可读性下限（见上）。

实时渲染与壁纸属性

场景 / 网页壁纸默认走内置 WebWallGL 实时渲染（lib/webwallgl/，MIT，源自 webwallgl）：粒子系统、puppet 骨骼模型、SceneScript 脚本、鼠标视差 / 点击交互、包内音频与音频反应完整还原。渲染页跑在同源隔离 iframe 里并有心跳看护，失败按壁纸记住并自动降级（设置里重开开关即重试）。网页壁纸另有注入的 WE API（音频监听 / 属性 / 媒体），并强制 sandbox="allow-scripts" —— 第三方 HTML 拿不到 DSH 的 origin。

当前壁纸是场景或网页时，「当前壁纸」卡片上会出现绿色的 壁纸属性 按钮：列出作者在 WE 编辑器里定义的可调属性（颜色 / 开关 / 滑块 / 下拉 / 文本 / 文件），改一下立刻生效并按壁纸记住，「恢复默认」一键清掉这张壁纸的全部改动；面板显示的是真正生效的值（从渲染页读回）。

自定义壁纸与自动轮播

• 自定义壁纸：上传本地 JPG / PNG / MP4 当壁纸（浏览器与宿主端双重校验）。存储位置默认 ~/.dsh-wallpaper-engine/uploads，可改到任意盘符（绝对路径，支持 ~）并自动迁移已有文件；适配模式有覆盖 / 填充 / 居中 / 拉伸四种。上传的 MP4 按需抽帧生成缩略图；重复上传同一文件按内容识别、直接复用已有的那张。
• WE 项目目录：存储位置里含 project.json 的壁纸项目目录（含 scene.pkg / index.html / *.mp4）会被自动收录成对应类型，场景壁纸同样走实时渲染；这些目录只读，不参与上传管理，也不会被删除。
• 自动轮播：轮转基于自定义轮播列表 —— 用 新建 建任意多个列表，从库存勾选壁纸加入，每个列表单独设切换间隔（按分钟，范围与默认见控件本身）与播放顺序（顺序 / 随机），再勾选 自动轮转 只在该列表内循环。每个列表至少需要 2 张可播放壁纸；首次使用时插件会把第一个可播放的 WE 播放列表导入成一个列表，编辑时也可用 从 WE 播放列表导入。
• 就绪后切换：到点先在后台把下一张准备到完全就绪（实时渲染首帧 / 视频可播放 / 图片解码完成）才落实切换 —— 旧壁纸在准备期间原样保持，就绪瞬间新旧两层交叉淡化，上屏即是活画面、不黑屏闪烁；准备失败的候选自动跳过、链式尝试下一张。

液态玻璃外观（整个设置窗口 + 配色 + 透明度）

「外观」页签控制整个 DSH 原生设置窗口的观感（参照 dsh-web-ui-all 皮肤中心的设计）：

所有控件即时生效并持久保存；不支持 backdrop-filter 的浏览器自动回退到高不透明实色，保证文字可读。

默认值与取值范围以控件本身为准。设置的唯一真源是 lib/settings-schema.js（DEFAULTS 默认值 / KINDS 校验范围 / 枚举表），宿主与客户端都从它派生，面板直接读它渲染 —— 因此本文与其它文档一律不抄写这些数值：抄一份就等于多一个会腐化的副本。

配置预设（整机配置快照）

「外观」页签顶部的配置预设不再是"玻璃子集"，而是这个插件整套配置的快照：一键套用，观感与行为设置（含轮播、播放、特效、视差、头像形状等全部设置）总是完整生效；字体 / 吉祥物立绘 / 会话头像三类实体资产在保存 / 导出时按需勾选携带（不勾的项落到接收方自己当前那份 —— 勾选只决定图片与字体要不要一并带走，数值配置总是完整保存）。预设可导出成 .json 文件、再在别处导入（导入只进列表、不立刻应用 —— 去列表里点它才生效），供用户之间流转。出厂自带若干套预设；升级前保存的旧版预设只含玻璃子集、已作废 —— 面板会点名版本作废，重新保存一份即可。

吉祥物（聊天顶部拉绳）

「系统」→「吉祥物」控制聊天的拉绳吉祥物 —— 一条可拖拽的拉绳沿顶部吸附，向下拉即拉出壁纸仓库抽屉（当前壁纸黑胶、轮播与自定义壁纸管理随手可及）。形态以卡片呈现，卡片直接渲染当前形态的立绘并按「吉祥物大小」实时缩放，选形态与看大小在同一处完成：

点击顶部拉绳吉祥物即可拉出「壁纸仓库」抽屉。两幅立绘在打包时都已内联为 base64（透明背景），单文件客户端资源依然自包含；大小只改变拉绳自身的盒尺寸，不影响下方的抽屉。

字体与输入光标

两个互不依赖的分区。全局字体住在侧栏「外观」页（默认收起的折叠块 —— 设置页对话框会挡住主页面、调完看不到实时效果，所以字体与玻璃细调都挪到了侧栏）；输入光标两处（设置页与侧栏）都能调：

• 全局字体（侧栏「外观」页 · 折叠块） —— 总开关默认关闭（即 dsh 原生外观）。开启后按角色 / 按组件细化，另有一个默认字体（没有全局字重 —— 一个全局值会把 DSH 的粗细层次压成一档）：
  • 默认字体（全局）：整套界面的默认字族，含本机已安装字体（宿主枚举系统字体清单，可下拉选择、可「重新扫描」）。它是默认不是强制 —— 任何角色 / 组件单独设过字族都以那里为准，而且不会改动任何角色的字号；
  • 终端字体：一处管两处终端 —— ① 对话里的终端块（官方 --dsl-terminal-font 钩子）② 侧栏 / SSH 的终端面板（dsh-ssh 的 xterm，走它给皮肤留的 --dsh-ssh-terminal-font 钩子）。⚠️ 它与「高级字体设置 → 终端」是同一项的两处入口；若在 dsh-ssh 自己的设置里填过 terminalFontFamily，那个值优先级更高。Nerd Font 图标（Powerline 那种）只有 Nerd Font 能画 —— 选了它才不出「口」；
  • 文字颜色角色：按 DSH 的颜色角色分别上色（未设置 = 用 DSH 默认色）；
  • 排版角色：一行一个角色，列出字号 / 字重 / 字体三项 —— 字号是绝对值 px（输入框直接显示 DSH 官方字号，留空 = 不改），字重 100–900，字族可选内置族键或本机字体（「跟随」= 不覆盖），另有「只看改过的」过滤器；
  • 高级字体设置（子开关）：按组件细化 代码块 / 终端 / markdown / 表格 四项 —— 只对启动自探测命中的组件生效（DSH 改名即整条降级，不误伤）。
  • 字体集预设：把整套字体外观存成一份字体集 —— 随包自带预设，可新建（以当前外观）/ 重命名 / 删除；改任何一项都只落到当前这一套，随时可以「恢复原样」回到它本来的样子；也能导出 / 导入 .json（导出走系统「另存为」）。它是「字体自定义」的附属：关掉总开关即整块收起。 报错 / 危险 / 警告语义元素强制保留系统红字；「恢复默认」一键清掉全部字体自定义项（不影响「只看改过的」这类视图开关）。
• 输入光标 —— 壁纸透过液态玻璃输入框衬在光标后面、两者颜色相近时光标会「隐形」（#83），这里给光标一个独立颜色：自动（默认，恢复 dsh 原生）/ 6 种预设 / 自定义取色，经 caret-color 作用于所有文本输入位。

系统音频反应与歌曲信息（Now Playing）

「播放」→「声音」三项（前两项默认开启，第三项默认关闭）：

• 系统音频反应 —— 把系统正在播放的声音（任何 App，不只是浏览器标签）做成频谱喂给壁纸的音频反应效果。采集的是系统输出回环、不是麦克风，macOS / Windows / Linux 三平台都内置（Windows 走 WASAPI 回环，不再需要「立体声混音」或虚拟声卡）；拿不到音频时壁纸自动回落内置的模拟频谱。
• 媒体信息 —— 把系统 Now Playing（歌名 / 歌手 / 专辑 / 播放态 / 进度 / 时长 / 封面）交给壁纸：依赖 WE 官方 wallpaperRegisterMediaPropertiesListener / …ThumbnailListener / …PlaybackListener（以及 …TimelineListener），识别这些 API 的工坊网页壁纸会自动显示歌曲信息与封面。
• 在线歌词 —— 优先取本地的（音频同目录的 .lrc 与已缓存歌词）；开启后本地没有才向 lrclib.net 查一次 —— 那次请求会把歌名 / 歌手 / 专辑发出去，所以默认关闭。

反向控制（随「媒体信息」生效）：场景壁纸里 Now Playing 组件自带的 ▶ / ⏸ / ⏮ / ⏭ 按钮，点击会控制系统真实播放器（播放 / 暂停 / 上下曲）—— 只对带该组件按钮的壁纸生效（全库同组件共三张）；控制面与数据面同源：中间件不可用时按钮落到渲染器自己的模拟源，内置实现（纯读取）不提供控制。

这些数据由宿主侧自带的 Rust 中间件 media-bridge 子进程提供（随插件按需下载、校验 sha256 后执行，缓存在 ~/.dsh-wallpaper-engine/bin/）：macOS 用 MediaRemote、Windows 用系统媒体会话（GSMTC）、Linux 用 MPRIS over D-Bus。因此不再需要 brew install media-control、playerctl 或 VB-Cable，macOS 也不再需要 Xcode Command Line Tools；中间件取不到或起不来时自动回落到内置实现，原因写在 GET /wallpaper-engine/media-status 的 fallback 字段里。

配置

本插件不会向模型暴露任何工具或提示文本，对 agent 零 token 开销，也不写入任何 DSH 自身的设置。本地落盘只有三类：宿主端配置文件 ~/.dsh-wallpaper-engine/config.json（选择、隐藏、轮播、配色、字体等全部设置，以及你选的上传目录与缓存位置）、自定义壁纸文件本身，以及 ~/.dsh-wallpaper-engine/ 下的缓存与按需下载的运行时（抽帧转码 / 实时抓帧 / 视频缩略图缓存、ffmpeg 与媒体中间件的二进制）。其中占盘的缓存根与上传目录都能在设置里改到别的盘（见上「缓存位置」），整个数据目录也能用 DSH_WE_DATA_DIR 一次挪走。

环境变量：

设置存在哪：从 v0.4.0 起全部设置存在宿主端文件 ~/.dsh-wallpaper-engine/config.json（与浏览器端口无关， 重启 / 换端口 / 清浏览器数据都不会丢；老版本的 localStorage 配置会自动迁移）。文件位置、多设备共享与读写行为见 docs/UPGRADING.md 的「设置持久化」。

与 dsh-better-sidebar 的兼容适配

本插件的液态玻璃效果对 dsh-better-sidebar 的侧边栏面板做了专门适配（毛玻璃、高光与层级统一），让侧边栏与对话区共享同一套「壁纸 + 遮罩」背景，三列视觉一致、不再割裂。

「外观」页签还提供一组独立于会话玻璃和当前壁纸的侧栏玻璃细粒度控制：即使没有启用 Wallpaper Engine 壁纸，也可以在普通 DSH 背景或其他背景来源上调整侧栏。它只作用于 dsh-better-sidebar 的侧边栏子树；不支持 backdrop-filter 的浏览器会自动回退到高不透明实色。

侧栏玻璃与设置窗口玻璃是两套独立参数：会话玻璃的「玻璃」滑杆只管输入栏/气泡，侧栏玻璃滑杆管侧边栏。关闭「侧栏液态玻璃」会连同编辑器/终端内容面一起恢复原生样式（插件直接画的毛玻璃 / 模糊整组退场）；页面令牌级的玻璃配方不在此开关的管辖内 —— 按宿主规范读 --dsw-alias-* 上色的面（含第三方插件）仍会拿到玻璃配方，这一层要等玻璃总开关（现状、自查与共存四态见 docs/COEXISTENCE.md）。侧边栏默认较透（与背景观感一致、避免面板发白）；编辑器/终端等内容面另有独立的近不透明底色 + 透明度控制，保证窄面板里文字可读。

侧边栏液态玻璃适配与「外观」页签的字体自定义（行楷）同时生效的实际观感。

已知限制

• **Application（应用）**类壁纸不支持 —— 它要宿主直接运行第三方可执行程序，本插件不提供该能力，因此不显示在缩略图选择器和轮播候选中。**Scene（场景）**壁纸由内置 WebWallGL 引擎实时渲染，不需要 Wallpaper Engine 在后台运行。
• 浏览器需能自动播放静音 <video>（DSH 跑在 loopback，现代浏览器允许静音自动播放）。
• 媒体从你本机的 Wallpaper Engine 安装路径提供；host 只提供它已枚举过的文件，不会暴露任意文件系统。自定义上传的文件同样只存在于本机，不上传任何服务器。
• 抽帧转码依赖 ffmpeg：编码器优先 NVENC（av1_nvenc → h264_nvenc），无 NVIDIA 显卡时回落 libx264 软件编码（慢但可用）；只有拿不到 ffmpeg（含自动下载不可用，如 musl/Alpine 等未覆盖平台）时，帧率上限功能才自动关闭，壁纸保持原片播放，不影响其它任何功能。
• 桌面端最小化 / 还原时仍可能有极短的白帧（壳侧）：壁纸激活期间插件会给根元素垫一层不透明的壁纸代表色，于是「壁纸层的像素没送到屏上」这一类会退化成同色底而不是白闪；但窗口一帧都没有可提交的那一瞬，露出的是桌面壳的窗口底板（Windows 上 BrowserWindow 用的是默认底板色 = 白；壳侧只给 macOS 设了透明底板）。这一条要壳侧配合，插件侧改不动。
• 遮挡暂停对视频壁纸与场景实时渲染生效：视频壁纸直接暂停解码；场景实时渲染经控制面暂停渲染循环（GPU 占用随之回落）。纯网页（iframe）壁纸无法从外部暂停，只能随页面隐藏被浏览器节流。

开发 / 重建

想跑本地一份代码（link: 安装、构建与验证、热挂载与编码铁律、以及 lib/client.js 到底是什么）见 CONTRIBUTING.md。

联系方式

有问题、想反馈，或者想第一时间拿到新版本，欢迎加入交流群（插件里 设置 → 壁纸引擎 → 关于 页显示的就是下面这两张码）：

图片用的是随包资源 lib/about/*.png（插件运行时由自己的路由提供同一份字节）；源截图与派生口径见 assets/about/README.md。

致谢

本插件是许多人贡献的成果，感谢他们：

• oneincase —— 内置 WebWallGL 实时渲染引擎与 media-bridge 媒体中间件的作者（#103、#104）：场景 / 网页壁纸的实时渲染与 Windows / macOS / Linux 三平台原生媒体链路都建立在它们之上。
• YV3507 —— 提交量最大的贡献者：从早期场景渲染器起步，到静态帧系列修复、液态玻璃令牌体系、live 帧链路与多轮大型重构与文档 / 守卫体系，几乎每个里程碑都有他。
• yuxilao —— scene-gl Linux 实时渲染管线（WebGL2 官方 shader 驱动 + 多轮性能优化）与轮换交接 / GPU 帧回填 / 官方资源路径（#65、#108）。
• Jerry —— 在三平台原生支持落地之前，macOS 侧的适配与贡献路径由他维护（WaifuX 工坊目录扫描、黑胶缩略图兜底、上游移植与 macOS 贡献路径梳理，#44、#45、#52、#54）。
• 还有 SiriLee（壁纸亮度 / 对比度 / 饱和度调节、吉祥物拉绳开关、WSL 下探测 Steam 根目录）、libiwolve（内容分级与类型过滤）、0-007pro（自动轮播）、jujubaoj646-star（字体与气泡样式自定义面板）、xiahou001（壁纸音轨音量控制）、wilianyichen（MP4 按需缩略图与自上传内容分级）、hecoococ（侧栏玻璃与活动壁纸解耦）、ShamSky88（玻璃模糊定位修复）、Rekk0（玻璃透明度令牌化、注册表定位 Steam）、Y1X1n（小白向使用指南）、wwexplorer（壁纸层取景：水平 / 垂直 / 缩放，数值可直接键入），以及所有通过 issue 反馈与 PR 参与改进的朋友 —— 谢谢你们！

Star History