nishuoyang/dsh-wallpaper-bg

dsh-wallpaper-bg

v0.3.11 · MIT License

给 DeepSeek Harness（DSH）网页界面加上一层独立的动态壁纸背景的静态双半插件：一条命令装好、刷新页面，整个界面的底层就变成一张会动的壁纸。内置 10 张 Unsplash 高清图，支持本地自定义图片 / 视频上传，还能只读接入本机 Wallpaper Engine 壁纸库——视频、场景（完整场景帧渲染）、网页三类壁纸都能在浏览器里动起来；浅色外观自动铺半透明白雾、深色外观自动压暗遮罩，保证界面细字始终清晰。背景层与桌面 Wallpaper Engine 完全独立：在 DSH 里换壁纸不会动你的桌面壁纸，反之亦然。

暗色外观下的 DSH 界面

更多界面预览（一）

设置面板 · 壁纸选项卡

更多界面预览（二）

更多界面预览（三）

功能

- 三种壁纸来源
- 内置壁纸：10 张 Unsplash 高清图，即装即用，无需任何本地服务；
- 自定义上传：本地图片 / 视频，存入 IndexedDB，刷新后保留。视频自动生成首帧缩略图，并支持按扩展名识别——浏览器 file.type 为空的 .mkv / .mov 等文件也能正确当视频播放，不再黑屏；
- WE 壁纸库：只读接入本机 Wallpaper Engine 已安装壁纸（默认 http://127.0.0.1:8088），并按 Steam 真实订阅清单过滤——在 WE 里退订的壁纸不会残留。
- 播放队列（自定义上传 + WE 壁纸库）：从对应来源的网格把壁纸拖进队列循环播放，每张停留 1–10 分钟（两个队列共用「每张时长」滑杆）；支持队列内拖拽排序（带插入指示条）、点选跳播、× 移除、清空一键重置，队列内容 / 开关 / 播放下标全部持久化到 localStorage。自定义队列支持图片 / 视频，WE 队列支持视频 / 场景 / 网页 / 图片。两个队列都吸顶在各自页签顶部，壁纸再多也只需短距离拖拽即可入队。
- 四种渲染
- 静态图片（cover 铺满）；
- 视频（canvas 渲染、30 FPS 上限、无黑边无变形）；
- 场景（完整场景帧：由 WE API 服务端的纯 JS 场景渲染器解析 scene.pkg，渲染对象树 / 纹理 / puppet 骨骼网格 / 粒子 / shader 效果，按场景正交比例输出；渲染失败自动回退主纹理静态帧 → 再回退工坊预览图 preview.gif / preview.jpg）；
- 网页（web 类型壁纸 iframe 原生渲染 index.html，浏览器里真跑起来）。
- 场景壁纸会动（离线烘焙成循环视频）：场景帧是静态图，粒子不飘、水波不动、角色不呼吸。现在可以把场景烘焙成一段无缝循环 MP4——服务端渲染若干帧、按帧签名自动找循环点、用 ffmpeg 编码，浏览器用原生  播放（60fps、几乎零 CPU 开销）。成本是一次性的且落盘缓存：本机实测 1080p / 24fps / 4 秒，普通场景 3.7 分钟（1.5 秒循环、300KB），骨骼角色场景 6.6 分钟（4.96 秒循环、2.5MB），重效果场景可能 5–25 分钟。需要 WE API 服务 0.3.0（"sceneAnim": 1）。鼠标视差、音频响应、「可触摸」类场景无法烘焙（它们依赖实时输入）。
- 四项调节：浅色雾层 / 深色遮罩（随 DSH 主题自动切换）、背景模糊度（0–20px）、背景亮度（50–150%）、安全放大（0–10%，裁掉边缘黑边）。
- 无黑屏切换：换壁纸（含队列循环切图）采用双层交叉淡入淡出——新壁纸先在自己的图层里预加载、解码 / 起播完成，再与旧壁纸叠化约 0.42 秒，旧层淡出结束才移除。图片、视频、场景、网页四种渲染都适用，切换过程中任何一帧都有画面，不会再闪一下黑屏。
- 下一张预热：队列循环播放时，停留期间就提前把下一张拉好（网络图片提前下载解码、WE 视频提前建好  元素缓冲数据、自定义上传提前读库并建好 objectURL），到点切换几乎立刻开始叠化，不再干等下载。
- 白场片头自动跳过：部分壁纸视频本身开头是一段纯白片头（如《明日方舟》「喧闹法则」前 2 秒整帧纯白），预热时会探出正片起点并直接从那里开始播，切过去不会再看到一大片白。
- 切换不残留后台解码：旧图层淡出时会彻底停掉抽帧定时器并释放视频（pause() + 断开 src），循环列表切多少次都只保留当前这一路解码。实测连续切换 6 次帧率稳定在 58–60 fps（修复前会从 59.7 一路掉到 12.2 fps）。
- 4K 视频不吃性能：视频层用  由合成器（GPU）缩放铺满，不再每帧 drawImage 到 canvas（4K 取一帧要 20–40ms），也去掉了 30fps 抽帧定时器；同时避免挂「恒等滤镜」（blur(0px) brightness(100%) 会禁用 GPU 合成）。实测 4K 壁纸从 22–27 fps 提升到 57–60 fps，每秒长帧从 68–72 降到 3–9。
- 页签只换视图：切换「内置壁纸 / 自定义上传 / WE 壁纸库」只改变面板显示，背景壁纸保持不动——点选某张壁纸、操作播放队列或开启「同步桌面壁纸」（与 WE 队列互斥）时才真正应用。
- 同步桌面壁纸开关：只读跟随 WE 当前桌面壁纸（30 秒轮询）。
- WE 库内筛选：类型（全部 / 视频 / 场景 / 网页）+ 分级（非18+ / 18+，18+ 卡片带红色角标，实时显示计数）；每次进入「WE 壁纸库」页签，分级默认回到「非18+」。
- 设置持久化到 localStorage；界面表面自动半透明化以透出背景。

安装

前提条件

- Windows / macOS / Linux，Node.js ≥ 20（node -v 检查）；
- 已装好 DeepSeek Harness，且能用 dsh web 正常启动网页界面；
- 仅「WE 壁纸库」来源需要 Windows + 本机 Wallpaper Engine（可选组件，见下文）。

安装方式：官方 dsh 命令

dsh plugin --profile web add dsh-wallpaper-bg

本地开发建议直接链接仓库：
dsh plugin --profile web add link: —— 之后改 lib/client.js / lib/host.js 只需普通刷新页面即可生效，无需重启服务。

可选组件：WE 壁纸库服务（Windows）

「WE 壁纸库」来源需要 wallpaper-engine-api/ 服务，它把 Wallpaper Engine 已安装壁纸列表以只读 HTTP API 暴露在 127.0.0.1:8088：

1. 进入 wallpaper-engine-api/ 目录，执行 npm install；
2. 双击 启动服务.bat（首次运行会引导写入安装路径；也可用 启动服务-静默.vbs 静默启动）；
3. 可选：双击 设置开机自启.bat，把静默启动脚本注册到注册表（HKCU\...\Run），登录 Windows 时后台自动启动；取消请双击 取消开机自启.bat（脚本直接引用本目录的 启动服务-静默.vbs，移动过目录后请重新设置一次）；
4. 之后升级 / 重启服务一律双击 重启服务(管理员).bat：自动请求管理员权限、结束旧进程并静默重启，等待端口就绪（全程日志见 restart-debug.log）。

服务只读：仅调用列表 / 当前壁纸查询，绝不触碰设置或播放接口；未检测到 WE 运行时也不会拉起 WE 主程序。列表按 Steam 真实订阅清单（431960_subscriptions.vdf）过滤——在 WE 里退订 / 本地禁用的壁纸即使文件夹残留也不会再出现，与 WE 界面一致。

除列表 / 预览 / 网页文件路由外，服务还提供场景帧渲染：GET /scene-frame/?w=&h=&t=&refresh=1 返回该场景壁纸的完整场景帧 PNG（w 默认 2560，h 缺省按场景正交比例；t 为渲染时刻，默认 2.5s；refresh=1 强制重渲染；auto=0 关闭「自动避开眨眼闭眼相位」，见下）。渲染在 worker 线程执行并落盘缓存，响应头 X-Scene-Mode 为 scene（完整场景渲染）或 main-texture（回退主纹理），X-Scene-Still-Time 为实际使用的时刻。视频纹理场景会先用 ffmpeg 抽一帧（可选依赖，见下）。缓存目录：~/.dsh-wallpaper-bg/cache/scene-frames/ 与 .../video-frames/（DSH_WB_CACHE_DIR 可覆盖）。

场景渲染默认关闭（服务 0.3.1 起）：场景帧渲染与动画烘焙会把结果缓存到 ~/.dsh-wallpaper-bg，为避免只装壁纸插件的用户被自动创建该目录，/scene-frame、/scene-anim 默认返回 403、服务启动与 /health 也不会创建缓存目录，场景壁纸由插件端回退到工坊预览图。需要完整场景帧 / 烘焙动画时，在 we-api.config（或环境变量）里设置 WE_SCENE_RENDER=1 并重启服务（首次运行 启动服务.bat 的向导已默认写入 WE_SCENE_RENDER=0；旧配置文件没有该键 = 默认关）。

服务 0.3.0 起新增场景动画烘焙：GET /scene-anim/?w=&h=&fps=&dur=&bake=1&cancel=1 入队/查询异步任务（返回 {state: idle|queued|running|done|static|error, done, total, percent, meta}），GET /scene-anim//video.mp4 提供烘焙好的无缝循环 MP4（带 Range + ETag），GET /scene-anim/status 列出全部任务。逐帧渲染写临时目录（不占内存），按帧签名自动挑循环点，ffmpeg 编码 H.264（yuv420p + faststart）。缓存目录：~/.dsh-wallpaper-bg/cache/scene-anim/（.mp4 + .json）。同一时刻只跑一个任务，其余排队。

验证：浏览器打开 http://127.0.0.1:8088/health 返回 JSON 即正常（"sceneRender" 默认是 0=场景渲染关闭；设置 WE_SCENE_RENDER=1 后为 1=支持场景渲染；"puppetAnim": 2 表示骨骼动画已完整——旧版角色眼睛会闭着或错位）；插件侧打开 http://127.0.0.1:3080/dsh-wallpaper-bg/health 可看插件版本。端口 8088 是历史选择（8080 曾被 Jenkins 占用）；换端口用环境变量 WEAPI_PORT，并在插件设置面板里把基地址改成对应值。

设置面板说明

| 项 | 说明 |
| --- | --- |
| 内置壁纸 / 自定义上传 / WE 壁纸库 | 来源页签：只切换面板视图，点选某张壁纸（或操作队列 / 同步桌面）才应用背景 |
| 上传自定义壁纸 | 图片 / 视频，存入 IndexedDB；视频自动生成首帧缩略图 |
| 播放队列 | 自定义上传与 WE 壁纸库各有独立队列，吸顶在页签顶部：拖入壁纸循环播放，「每张时长」滑杆 1–10 分钟（两队列共用），队列项可拖拽排序、点选跳播、× 移除、清空 |
| WE 基地址 + 刷新 | WE API 地址（默认 http://127.0.0.1:8088） |
| 类型筛选 | 全部 / 视频 / 场景 / 网页，按壁纸真实类型过滤 WE 壁纸库 |
| 分级筛选 | 全部 / 非18+ / 18+（基于 project.json 的 contentrating：18+ = Mature + Questionable），18+ 卡片带红色角标，面板实时显示筛选计数；每次进入 WE 页签默认回到「非18+」 |
| 同步桌面壁纸 | 只读跟随 WE 当前桌面壁纸（与 WE 队列互斥） |
| 浅色雾层 / 深色遮罩 | 0–100%，随 DSH 主题自动切换：浅色外观铺半透明白雾垫在内容下方提升细字可读性，深色外观压黑遮罩 |
| 背景模糊度 / 背景亮度 | 0–20px / 50–150% |
| 安全放大 | 0–10%，按比例放大背景以裁掉边缘黑边 |
| 场景壁纸播放烘焙动画 / 选中时自动烘焙 | 场景壁纸优先播放烘焙好的无缝循环视频（而不是静态帧）；「选中时自动烘焙」在选到未烘焙的场景壁纸时自动开始烘焙。同一行还显示当前状态（未烘焙 / 烘焙中 42% / 已烘焙 4.96 秒循环 1920×1080 24fps / 该壁纸本身没有动画）并提供「烘焙动画 / 重新烘焙 / 取消烘焙」按钮 |
| 恢复默认 | 一键重置全部设置 |

原理

本包是 DSH 静态双半插件，并作为 profile 补丁层（bundle）组合进 DSH 的 host 平面：

| 半边 | 文件 | 职责 |
| --- | --- | --- |
| 宿主半（Node） | lib/host.js | 注册同源路由：/dsh-wallpaper-bg/asset（本地文件流式代理，支持 Range）、/dsh-wallpaper-bg/we（WE API 只读代理，带缓存，透传 hasFrame / previewFile）、/dsh-wallpaper-bg/scene-frame（场景帧同源代理，可选）、/dsh-wallpaper-bg/health |
| 浏览器半 | lib/client.js | 单文件 client bundle（window.__ModuleLoader__ 工厂形式），注入背景层与遮罩、注册设置面板「壁纸」选项卡；场景壁纸优先加载渲染帧，失败回退预览图 |
| 组合层 | cordis.patch.yml | dsh.bundle 补丁：把插件行插入 profile 组合的 host 平面，随 dsh web 启动即生效，首次加载页面就带背景 |
| 场景渲染 | wallpaper-engine-api/lib/ | 纯 JS 场景渲染器（we-renderer/：对象树 / 纹理 / puppet 骨骼 / 粒子 / shader 效果 / GLSL 转译），由 WE API 服务的 scene-frame.js 在 worker 线程调用 |

两端零构建：lib/client.js 是手写的单文件 bundle，无需任何打包工具；另附 dsh-wallpaper-bg CLI（install / status / uninstall）完成一键安装。

常见问题

- 场景类壁纸显示的是预览图而不是完整场景帧？ 插件 0.3.12 起，WE API 服务的场景渲染默认关闭（WE_SCENE_RENDER，默认 0）——关闭时不创建 ~/.dsh-wallpaper-bg 缓存目录，场景壁纸回退工坊预览图。需要完整场景帧 / 烘焙动画：编辑 wallpaper-engine-api/we-api.config 加一行 WE_SCENE_RENDER=1，然后双击 重启服务(管理员).bat。
- 场景类壁纸不动？ WE 场景壁纸是 scene.pkg 编译字节码（场景逻辑、shader、粒子系统都在里面），浏览器无法直接执行。本插件 0.3.9 起改为在 WE API 服务里用纯 JS 场景渲染器把 scene.pkg 真正渲染出来（借鉴 dsh-plugin-wallpaper-engine 的 lib/we-renderer/），渲染结果是一张完整场景帧静态图（不是动画），首次渲染 8–35 秒、之后走磁盘缓存秒开。实测本机 134 张场景壁纸：109 张输出完整场景帧、21 张回退主纹理、4 张回退工坊预览图。
- 想让它真的动起来？ 0.3.11 起可以把场景烘焙成无缝循环视频（设置 → 壁纸 → 「场景壁纸播放烘焙动画」/「烘焙动画」按钮）：服务端逐帧渲染 → 自动检测循环点 → ffmpeg 编码 MP4，浏览器原生 60fps 播放。1080p 下普通场景约 1–4 分钟、重效果场景 5–25 分钟，后台进行、烘焙一次永久缓存；打开「选中时自动烘焙」可省掉点按钮。鼠标视差 / 音频响应 / 可触摸类场景无法烘焙。
- 需要 WE API 服务 0.2.7+（骨骼动画 / 眼睛修复与颜色混合 / 质量门禁修复需要 0.2.9，场景动画需要 0.3.0）：http://127.0.0.1:8088/health 应含 "sceneRender": 1。服务 0.3.1 起场景渲染默认关闭：/health 默认是 "sceneRender": 0，需在 wallpaper-engine-api/we-api.config 加一行 WE_SCENE_RENDER=1 再双击 重启服务(管理员).bat。未开启 / 旧版服务下场景壁纸自动退回原来的 preview.gif / preview.jpg 显示。
- 角色眼睛闭着 / 眼睛位置不对？ 0.3.10 已修（需要服务 0.2.8，/health 含 "puppetAnim": 2）：原来 MDLA 骨骼动画头靠扫描 30.0f 浮点特征定位，fps≠30 的模型动画整段丢失；动画帧里的缩放（眨眼就靠眼睑骨骼 scaleY 收缩）也被忽略。修好后角色会按动画摆姿势、眨眼。另外壁纸当背景只取一帧，如果这一帧正好落在闭眼相位，看起来仍像「没有眼睛」——现在服务会自动避开闭眼时刻（X-Scene-Still-Time 报出实际时刻，&auto=0 可关闭）。
- 视频纹理场景（主画面是内嵌 MP4 或独立视频文件的场景）：服务会用 ffmpeg 抽一帧再渲染。ffmpeg 来自 WE_FFMPEG / FFMPEG_PATH 环境变量或系统 PATH；没装 ffmpeg 也能用，只是这类场景会退回预览图。
- 壁纸上盖着一大块黑色矩形 / 菱形？ 0.3.10 已修（需要服务 0.2.9）。镜头光晕这类素材本身就是「黑底 + 一圈彩虹弧」，完全靠 colorBlendMode（屏幕 / 亮化 / 叠加）把黑底消掉；而渲染器的旋转绘制分支没有混合模式参数，于是每个「旋转 + 有混合模式」的图层都被当成不透明矩形画出来——那个黑菱形就是旋转 42.6° 的镜头光晕层。本机 134 张场景里有 26 张含这类图层。同一版还堵住了「渲染成功但其实是白屏 / 灰屏」的情况：这类退化帧不再显示，改为回退主纹理或工坊预览图，并且会被负缓存，重复加载秒回。
- 仍然是静态帧：场景里的动画（粒子飘动、水面波动、角色呼吸）不会动——本实现只渲染单个时刻的画面。想要完整动态效果：用 WE 托盘菜单的屏幕录制（或 OBS）把该场景录 30 秒左右导出成 MP4，再通过「自定义上传」传进来，浏览器里就是 100% 保真的动态壁纸。
- 少部分场景仍是预览图：主纹理是纯色 / 纯遮罩、或使用了不支持的纹理格式。
- 网页类壁纸（web 类型）能正常显示吗？ 能——web 壁纸本来就是 HTML/JS 网页，插件会用 iframe 全屏原生渲染 index.html 及其相对资源（由 WE API 的 /files//... 目录路由只读提供，仅限已订阅壁纸目录）。WE API 0.2.6 起还会给网页注入一层 WE 私有接口垫片：把 project.json 里的默认用户属性喂给 applyUserProperties（否则只在属性回调里设置背景图的壁纸会只剩角色立在纯黑底上，看起来像一张竖屏壁纸），并提供音频 / 媒体接口占位与「已画出内容」上报——插件据此在壁纸真正有画面时才叠化入场，不再黑屏或空等。注意：背景层不拦截鼠标，所以壁纸的鼠标交互（点击、拖拽）不会生效，仅视觉效果；音频可视化会以静音数据运行（浏览器里没有 WE 的音频采集）。
- 网页壁纸黑屏 / 半天不出画面？ 先确认 WE API 服务已升级到 0.2.6 并重启（http://127.0.0.1:8088/health 应含 "webShim": 1），旧版服务没有垫片，也没修 ../assets/... 这类按 file:// 写的相对路径。
- 网页壁纸切换时资源反复重下？ 0.3.8 已修：服务 /files 路由原来整读文件且返回 no-store，现在流式发送 + ETag / Last-Modified 条件请求（HTML no-cache、静态资源 300 秒缓存）并支持 Range。
- 视频有黑边？ 用「安全放大」拉 2–3% 即可裁掉画面自带的黑边（渲染层的 cover 裁剪已保证不自造黑边）。
- 上传的视频黑屏 / 黑色占位？ 浏览器 file.type 为空的视频（常见于 .mkv / .mov）现在会按扩展名识别并走视频渲染，且每个视频都会自动生成首帧缩略图；若个别文件仍是黑的，多半是该编码浏览器不支持。
- 改了代码不生效？ 只改 lib/client.js / lib/host.js 内容时，普通刷新页面（F5）即可——客户端 bundle 每次请求都从磁盘现读（cache-control: no-cache），无需重启服务；只有增删插件行、修改 dsh.client 声明等插件集合变化时才需要重启 DSH。
- WE 壁纸库报错？ 确认 wallpaper-engine-api 服务在 8088 端口运行（浏览器访问 http://127.0.0.1:8088/health 验证），且插件设置里的基地址一致。
- 在 WE 里删掉的壁纸还在插件里？ 服务会按 Steam 订阅清单过滤，退订的壁纸不再列出；若服务还是旧版本（/health 没有 subscriptionsFile 字段），双击 重启服务(管理员).bat 升级，然后点插件里的「刷新」。

开源

MIT License，见 LICENSE。欢迎 issue / PR。

发布流程

仓库自带一键发布脚本 scripts/release.ps1，固化「版本校验 → 打包预检 → 提交 → 打标签 → 推送 → npm publish → GitHub Release（附 tarball）」：

.\scripts\release.ps1 -DryRun              # 先预演：只检查不产生改动
.\scripts\release.ps1 -Version 0.3.8       # 改版本号并发布
.\scripts\release.ps1                      # 发布 package.json 里的当前版本

预检会拒绝重复发布（本地 / 远端已有标签、npm 上已有该版本），并校验 CHANGELOG.md 已写好对应版本条目——Release 说明直接取自该条目。另有 -SkipNpm / -SkipGitHub / -SkipPush / -Yes 可选。

legacy/ 目录存放 v0.1.0 之前的动态插件（Cordis dynamic package）时代源码，仅作归档。