壁纸引擎背景pbadgpmeb22791-sketch/dsh-we-wallpaper

dsh-we-wallpaper

将你的本地 Wallpaper Engine
库用作 DeepSeek Harness
Web GUI 的背景——视频壁纸会播放、网页壁纸会渲染，并且场景壁纸会从 Wallpaper Engine 获得一次性高分辨率动态缓存。
支持热插拔、无依赖、无需修改 dsh 源码。

- 语言：简体中文.md)

Screenshots / 演示

壁纸库卡片以及一张作为 GUI 背景应用的场景壁纸：

设置卡片与应用到界面背景的场景壁纸：

demo-1

demo-2

功能特性

- 将壁纸作为 GUI 背景播放
- video 壁纸会作为循环播放的静音  播放（原生分辨率）
- web 壁纸会在沙盒化、可点击穿透的  中渲染
- image 壁纸按原样显示
- 在动态优先模式下，scene 壁纸首先由 Wallpaper Engine 以真正的
全屏方式渲染（无边框、置顶、原生显示器
分辨率、捕获时隐藏任务栏），并通过
Windows.Graphics.Capture 录制为 12 秒的 H.264 循环视频；后续加载会使用
缓存，绝不会放大 160px 的创意工坊预览图
- HD 静态模式和失败回退仍使用无依赖的 .pkg
/ TEX 解码器来提取精确的 4K–8K 背景纹理
- 官方插件配置区域中的设置卡片
（设置 → 插件配置）：浏览带实时预览的库、搜索、
一键应用，以及标记当前正在你的桌面上运行的壁纸的徽章
- 可读性控制：深色 scrim、面板半透明（官方
表面 token 被重新声明为半透明——在浅色和深色
主题下均可用）、cover / contain 适配、锐化（用于
回退预览源的 SVG 卷积滤镜），以及 动态优先 / HD 静态 场景模式
- 注重资源的播放：壁纸未更改时会复用媒体元素——
拖动滑块绝不会重启视频流
或产生另一个解码管线（此处修复了一个内存泄漏崩溃问题）
- 持久化选择保存在 ~/.dsh/we-wallpaper.json 中；提取的场景
画面缓存于 ~/.dsh/we-wallpaper-cache/

动态缓存

- HD 录制文件位于 ~/.dsh/we-wallpaper-cache/hd-video/ 下，以
Wallpaper Engine 创意工坊 ID 为键，并使用 JSON 元数据进行失效判断。
- 这是一个持久、可重建的缓存，而不是一次性的临时
文件。源文件或录制器版本变化会重新生成它；手动删除它
是安全的。
- 首次生成会将 Wallpaper Engine 场景窗口置于前台约 15
秒。之后启动 DSH 时会读取缓存的 MP4，不会再次录制。

快速开始

git clone https://github.com/pbadgpmeb22791-sketch/dsh-we-wallpaper.git
dsh plugin --profile desktop add "\new"

使用 dsh-super-injector 时，将插件路径指向 \new 作为
好的。仓库根目录保留旧版本以便回滚。

重启（或热重载）dsh 宿主，刷新 GUI 页面，打开
设置 → 插件配置 → 动态壁纸，选择一个壁纸，按喜好调整遮罩 / 半透明
效果。

所有安装方式（包括手动编辑 cordis.patch.yml 和 dsh-super-injector）请参见
docs/INSTALL.md，所有选项和故障排除指南请参见
docs/USAGE.md。

工作原理

| 部分 | 文件 | 作用 |
| --- | --- | --- |
| 宿主 | src/we-scanner.ts | 发现 WE 安装位置（环境变量 → Steam 注册表 → libraryfolders.vdf → 默认值）并解析每个 project.json |
| 宿主 | src/pkg-tex.ts | WE 包解码器：目录表、TEXV/TEXB 容器、LZ4、DXT1/3/5、内嵌 PNG/JPEG、PNG 编码 |
| 宿主 | src/pkg-preview.ts | 提取缓存（~/.dsh/we-wallpaper-cache/） |
| 宿主 | src/scene-video.ts | 通过官方 CLI + wcap 构建/缓存高清 H.264 循环视频 |
| 宿主 | src/routes.ts | /api/we-wallpaper/ 路由族 — 同源防护、路径穿越防护 |
| 宿主 | src/state.ts | 选择持久化（~/.dsh/we-wallpaper.json） |
| 浏览器 | src/client/layer.ts | 固定背景层：按类型显示媒体、令牌快照半透明、遮罩、锐化 |
| 浏览器 | src/client/WallpaperCard.tsx | 库卡片（预览、搜索、应用、选项） |

HTTP API

| 路由 | 用途 |
| --- | --- |
| GET  /api/we-wallpaper/list | 壁纸库（id/标题/类型/来源/桌面激活状态） |
| GET/POST /api/we-wallpaper/state | 持久化的选择 + 选项 |
| GET  /api/we-wallpaper/preview/ | 本地预览文件（GIF/JPG/PNG） |
| GET  /api/we-wallpaper/pkg/ | 提取的场景背景（PNG/JPEG，已缓存） |
| GET  /api/we-wallpaper/media/ | 主媒体文件（支持范围请求的视频流） |
| GET  /api/we-wallpaper/web// | Web 壁纸的静态文件 |
| POST /api/we-wallpaper/scene-video/generate/ | 生成首个高清动画缓存 |
| GET  /api/we-wallpaper/scene-video/status/ | 读取进度 / 失败状态 |
| GET  /api/we-wallpaper/scene-video/media/ | 支持范围请求的缓存 H.264 流 |

安全说明

- 每个路由都会拒绝跨站请求（Sec-Fetch-Site / Origin
防护）— 随机网页无法通过 localhost CSRF 读取你的壁纸库
- 壁纸 id 仅针对扫描映射进行解析；Web 文件路径有
路径穿越防护
- Web 壁纸在沙盒化、点击穿透的 iframe 中运行 — 它们仍然是
你自己的本地文件，请以你在 Wallpaper Engine 中给予工坊内容的同等信任对待它们
- 动态场景仅由本地安装的 Wallpaper Engine 打开。
捆绑的录制器是公有领域的 wcap
二进制文件；其许可证包含在 tools/wcap/LICENSE。

已知限制

- 高清动画缓存需要 Windows 桌面 Harness 以及正在运行的
Wallpaper Engine。首次生成时，场景窗口会进入前台约 15 秒。对于随机/非周期性场景，12 秒循环可能会出现可见接缝。失败时会安全回退到精确的 HD 静态图或本地预览。
- 静态提取首先遵循 scene.json → model → material → TEX 依赖链。仅当场景关系无法识别背景时，才使用尺寸/宽高比启发式方法，因此未知场景仍可能选错纹理。
- 音频已静音（浏览器自动播放策略）
- 半透明重映射覆盖官方 --dsw-alias- 令牌；带有硬编码背景的第三方插件可能仍保持不透明

本次更新修复了什么

旧版可以直接播放视频壁纸，但场景壁纸通常不得不放大一个约 160px 的创意工坊预览图。这保留了动态效果，但看起来明显模糊。v0.3.0 让 Wallpaper Engine 渲染真实场景，然后将最终 HD 输出录制并缓存为 H.264。这样既保留了动画，也保留了清晰度，而无需尝试重新实现完整的 Wallpaper Engine 场景渲染器。

当录制被禁用或失败时，内置静态路径仍可从场景包中解析出真实背景纹理。示例 3409595232 会选择 3840×2160 的 materials/背景.tex，而不是前景角色纹理。未知或受保护的包不会被强制解密；它们会安全失败并返回诊断信息。

路线图

可能的后续工作包括可配置的捕获时长/比特率、缓存空间管理和一键清理、循环接缝改进，以及对更多旧式或特殊 TEX 容器的支持。参见 docs/SUMMARY.md。

开发

npm install
npm run typecheck   # tsc over host + client programs
npm test            # vitest (pkg decoder, LZ4, DXT, cache, scanner)
npm run build       # lib/index.js (host) + lib/client.js (browser bundle)

诊断脚本位于 scripts/（probe-pkg.mjs、probe-previews.mjs、survey-extract.mjs）。完整细节见 docs/DEVELOPMENT.md。

许可证

MIT — DXT 解码包含来自 RePKG 的 LibSquish 衍生 MIT 代码的 TypeScript 移植版（Xalcon @ mmowned.com）。