dsh-mpkg-wallpaper — DSH 壁纸引擎 mpkg 背景插件

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

给 DeepSeek Harness Web 界面（dsh web）添加背景壁纸的插件，功能非常丰富——从 Wallpaper Engine .mpkg 解析、多源壁纸、整屏虚化体系，到本地壁纸库与自动轮换，几乎每一个外观细节都可以调节。

核心能力

📦 多源背景（mpkg / 视频 / 图片 / URL）

Wallpaper Engine .mpkg：浏览器内直接解析容器（纯客户端，不上传第三方）；视频类壁纸自动播放内嵌 mp4 / 视频纹理；场景类壁纸使用作者生成的 preview.gif 动态预览；多时段自动切换（按系统当前时间选素材）；可调参数（只读展示）供对照壁纸引擎 App
图片/GIF 直接导入：本地图片文件（png/jpg/webp/gif）或图片链接 URL（含 data:image）都能作为背景——大文件自动存浏览器存储，GIF 动画可靠循环
视频文件：直接选择 mp4/webm 文件作为视频背景

🌊 整屏虚化（磨砂）体系

统一虚化：一个条控制整屏壁纸模糊度（0 = 壁纸清晰，拉高 = 越来越模糊），表面白雾厚度统一跟随「不透明度」条
对话框 / 弹层 / 遮罩虚化：三个独立开关 + 程度条（屏幕中央窗口 / 弹出菜单 / 背景遮罩各管各的）
磨砂模糊条（统一虚化开启时被接管并提示）、面板不透明度、标题栏磨砂程度（独立可调）

🎬 镜头与外观

镜头缩放（10–2000%）与平移、侧边栏/标题栏透出壁纸开关、轻度锐化、Deep diving 背景框

🚀 大文件混合模式（hybrid）

开启后 mpkg 流式上传到 DSH 宿主 → 磁盘存储 → HTTP Range 流式播放，支持 >600MB 的大文件，内存占用极低
关闭则回到纯浏览器模式（600MB 上限）

🖼️ 本地壁纸库（Windows + 跨平台）

Steam 自动发现：自动定位壁纸引擎安装（含非默认盘符，读注册表 + libraryfolders.vdf），列出 video/web 壁纸
自定义本地壁纸目录：任意文件夹都能作为壁纸库，内置跨平台目录选择器（逐级浏览文件夹）
壁纸切换与轮换：一键「上一个/下一个壁纸」，或定时自动轮换（间隔可调）；轮换范围含自定义目录 + Steam 自动发现的视频壁纸

🛡️ 安全与共存

冲突检测：检测到其他壁纸/主题插件自动关闭本功能，避免叠加
第三方插件共存：与 DSH-better-sidebar、dsh-chat-import、dsh-sidebar-qa 等共存无冲突（CSS 只命中 DSH 原生区域，不覆盖插件注入内容）
安全边界：.exe/application 壁纸完全排除（防病毒注入），自定义目录只读图片/视频，宿主路由有路径穿越校验
纯客户端解析在浏览器沙箱内完成，恶意 mpkg 无法触达宿主文件系统

🔄 检查更新与一键热更新

「检查更新」对比实际代码内容哈希（README 变更不触发），只认真实功能变化
发现新版本 → 「一键更新」：从 GitHub 自动下载最新代码 + 版本号写回本机 → 重启 dsh web 即生效

功能与设置分组

背景来源：总开关、大文件混合模式（hybrid）、mpkg 文件、图片链接、本地图片/动图、本地壁纸库（Steam 自动发现 + 自定义目录 + 目录选择器）、壁纸切换与轮换
外观：面板不透明度、磨砂模糊、镜头缩放、镜头位置
界面虚化：统一虚化程度、对话框/弹层/遮罩虚化开关 + 程度、Deep diving 背景框、标题栏磨砂/透出壁纸（磨砂程度独立可调）
其他：侧边栏透出壁纸、轻度锐化、第三方 UI 圆角兼容（默认关）、检查更新/一键热更新、恢复默认

支持的输入

Wallpaper Engine .mpkg（PKGM0014 视频类 / PKGM0018 场景类）
mp4/webm 视频文件（直接选择）
图片/GIF 文件（png/jpg/webp/gif，本地文件）与 图片链接 URL（含 data:image）
大小限制取决于运行模式：

- 混合模式（hybrid，默认开）：mpkg 流式上传到 DSH 宿主 → 磁盘存储 + HTTP Range 流式播放，>600MB 的大文件也支持（大小只受磁盘空间限制），内存占用极低 - 纯浏览器模式（hybrid 关闭）：整个文件 >600MB 拒绝；独立视频 >600MB、视频纹理 >250MB、图片/GIF >200MB 无法处理（会提示并回退预览图）；浏览器存储配额（IndexedDB）也可能受限

导入后显示效果取决于壁纸内容：

- 视频类壁纸（内嵌 mp4 / 独立 mp4）：直接播放视频作为背景 - 场景类壁纸（Live2D 等）：使用作者生成的 preview.gif（浏览器无法渲染 WE 场景） - 蓝幕/绿幕抠像层：回退使用预览图（直接播原片会显示蓝/绿背景）

限制

场景类壁纸（Live2D 木偶 + shader + 粒子）：完整动态场景只能在壁纸引擎 App 渲染，浏览器取用的 preview.gif 是作者生成的动画预览，全屏可能偏模糊（缩放/锐化可缓解）
可调参数为只读展示：浏览器显示的是预渲染素材，修改参数不会改变画面；如需生效请在壁纸引擎 App 中调整
超大素材（纯浏览器模式）：独立视频 >600MB、视频纹理 >250MB、图片 >200MB 无法处理（会提示并回退预览图）。混合模式下大文件走宿主流式播放，无此限制

截图演示

![侧边栏收起 · 新会话界面](screenshots/dhsw1.jpg)

动态壁纸铺满整个界面。此状态下侧边栏收起，聊天框位于屏幕中央并带有磨砂模糊效果；侧边栏呈全透明状态，壁纸完整透出，画面干净通透。

![侧边栏展开](screenshots/dshw2.jpg)

通过「面板不透明度」与「统一虚化」滑条调节后的效果（图为调节后）：大部分界面区域的不透明度均可调节，侧边栏半透明，壁纸在后方隐约透出。

![设置页](screenshots/dshw3.jpg)

壁纸引擎背景的设置界面。截图之外，外观几乎全部可调：统一虚化（一个条控制整屏壁纸模糊度）、对话框/弹层/遮罩虚化、镜头缩放与平移、侧边栏/标题栏透出壁纸、标题栏磨砂程度、轻度锐化，以及部分壁纸的按时间自动切换。

截图中的壁纸来自 B 站 UP 主【-夜莺Night】的壁纸作品：作者主页

使用

设置 → 壁纸引擎背景：

控件	说明
选择 .mpkg 文件	自动取 preview.gif（或按时间取素材）作动态背景；也可直接选 mp4/webm
大文件混合模式	开：>600MB 也支持（流式上传宿主播放）；关：纯浏览器模式（600MB 上限）
可调参数	壁纸自带的参数与当前值（只读展示，供对照壁纸引擎 App）
图片链接 / 本地图片	普通图片或 GIF
面板不透明度	50–100%
磨砂模糊	整张壁纸的模糊程度 0–40px（0=清晰）
统一虚化	一个条控制整屏壁纸模糊度（0=清晰，拉高=更模糊）；表面白雾统一跟随「不透明度」条
对话框/弹层/遮罩虚化	三个独立开关+程度条
镜头缩放/位置	背景画面放大（10–2000%）与平移；缩小可看到画面边缘的组件
侧边栏/标题栏透出壁纸	开关；关闭后对应区域纯色不透明；标题栏磨砂程度独立可调
本地壁纸库	Steam 自动发现（Windows）+ 自定义目录（任意文件夹 + 目录选择器）
壁纸切换与轮换	「下一个壁纸」一键切换；定时自动轮换（间隔可调）
轻度锐化	提升低清观感；GIF 卡顿就关

安装

方式一：dsh plugin add（推荐）

dsh plugin --profile web add dsh-mpkg-wallpaper
# 重启 dsh web 后浏览器 Ctrl+F5 生效

方式二：手动复制

把插件目录（或 GitHub 下载的 zip 解压）放到 $DSH_HOME/profiles/node_modules/dsh-mpkg-wallpaper/，并在 profile 的 cordis.patch.yml 注册一行：

- insert:
    - id: dsh-mpkg-wallpaper
      name: dsh-mpkg-wallpaper

方式三：GitHub 克隆

git clone https://github.com/XHR666/dsh-mpkg-wallpaper.git $DSH_HOME/profiles/node_modules/dsh-mpkg-wallpaper

卸载：dsh plugin --profile web remove dsh-mpkg-wallpaper（或删除挂载行 + 插件目录 + 重启）。

官方文档

Wallpaper Engine 官方帮助站 help.wallpaperengine.io 有移动端章节（与 Windows 配对等）；mpkg 容器格式为专有格式，官方未公开文档。

反馈 Bug

反馈问题时请附带：

原始 .mpkg 源文件（复现问题所必需）
浏览器控制台输出（F12 → Console），如有
你的 DSH 版本与平台（Windows / Linux / 移动端）

安全说明

无对外网络请求：插件不访问任何外部网络；唯一网络行为是：① 用户手动输入的图片 URL 由浏览器加载；② 混合模式下与本机 DSH 宿主（127.0.0.1）的 HTTP 通信（上传 mpkg / 流式播放壁纸），不经过任何第三方
无敏感内容：源码不含路径、密钥、令牌、个人信息
无第三方闭源代码：仅依赖 DSH 自带 react + 官方 slots/locale 接口
参考项目（均开源）：dsh-bg-image（MIT，模板）、unmpkg（GPL-3.0，仅参考 mpkg 二进制格式）、repkg（GPL，仅研究 .tex 格式）、astc-encoder（Apache-2.0，本地解码实验）
数据边界：所有解析在浏览器本地完成；localStorage 只存背景图 data URL 与参数编辑

文件结构

dsh-mpkg-wallpaper/
├── package.json      # dsh.bundle + dsh.client 声明
├── cordis.patch.yml  # 插件安装声明（dsh plugin add 使用）
├── lib/
│   ├── index.js      # 宿主端：大文件上传/流式播放 + Steam 自动发现 + 自定义目录
│   └── client.js     # 浏览器端：mpkg 解析 + 设置页 + 背景 DOM + 虚化体系 + 壁纸库
├── tools/            # mpkg/tex/mdl 逆向解析工具（供开发者参考）
├── README.md         # 本文件（中文）
└── README.en.md      # 英文说明

GitHub 发布说明

可移植性（在他人的设备上也能用）

无绝对路径、无本机端口、无环境专属配置；依赖仅 DSH 自带 react + 官方 slots/locale 接口
自定义导航图标：lib/client.js 里的 NAV_ICON 常量（默认是自绘的"风景画"SVG，无商标）可替换——改成你自己的图标即可（20×20，推荐 SVG data URL 或 base64 PNG）

包含的逆向工具（tools/）

工具	用途
`unmpkg.py`	mpkg 容器解析/提取（PKGM0014/0018）
`tex2png.py`	TEXV0005 纹理解码（DXT5/R8 等）
`mdl_explorer.py`	.mdl 结构探索（块标签/网格/浮点区段）
`xref.py`	wallpaper64.exe 字符串 xref + 反汇编（capstone）
`MDL-格式分析笔记.md`	.mdl 格式逆向进展（容器/网格已破解，骨骼=JSON，动画待续）

壁纸格式研究摘要（供其他开发者）

mpkg：PKGM0014（视频类：mp4+gif+json）/ PKGM0018（场景类：scene.json+tex+mdl+shader）
tex：TEXV0005，格式 5=DXT 家族，格式 34=内嵌 MP4 视频纹理（customize 壁纸的 4K 动画直接在里面）
mdl：MDLV00xx 块容器；网格=8 float/顶点；MDLS0003/0004 含 JSON 骨骼姿态；MDLA=动画

渲染可行性研究

完整场景（含 Live2D 木偶）只能由专有渲染器完成：壁纸引擎 App 的原生库 libscenejni.so（40MB，内嵌 Chromium + 专有 puppet 渲染）；开源方案 we-layerd（Rust）打包了官方渲染器，但仅限 Linux Wayland 桌面（GNOME/niri/Hyprland/KDE Plasma），Windows 与 Termux proot 都跑不了
浏览器端没有成熟的 WE 场景渲染器（wallgl 是雏形且不支持木偶；pixeltris/wallpaper-engine-web 已消失）——与操作系统无关，任何浏览器都无法直接渲染 Live2D 场景
可行路径（跨平台通用）：外部渲染成视频 → 插件视频背景（MP4/WebM 存 IndexedDB，<video> 循环播放）：

- Windows：Wallpaper Engine 官方版（Steam，Windows 原生渲染全部场景）或开源 Lively Wallpaper（支持视频/网页壁纸，不解析 WE 场景格式）→ 录屏导出 mp4 - Linux 桌面：we-layerd 渲染 → 录屏 - 移动端：壁纸引擎 App 录屏

插件在任意平台（Windows/Linux/macOS/移动端）的 dsh web 上功能一致：preview.gif / 内嵌视频纹理 / 多时段切换全部可用