dsh-mpkg-wallpaper

dsh plugin --profile web add dsh-mpkg-wallpaper

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


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

给 DeepSeek Harness Web 界面（dsh web）添加背景壁纸的插件：Wallpaper Engine .mpkg 解析、Steam 创意工坊目录、视频/网页/图片壁纸、时间变化壁纸的多时段切换、整屏虚化体系、主题色与玻璃外观、本地壁纸库、定时轮换、Now playing 控件、一键更新。外观细节几乎全部可调。

• 仓库：<https://github.com/XHR666/dsh-mpkg-wallpaper>（已发布 npm 包 dsh-mpkg-wallpaper）
• 配套渲染器（纯 Scene 壁纸用，GPL-3.0-or-later，另行安装）：本包不包含它，也不 import/内嵌其任何代码；

获取方式见本插件仓库主页的链接与 docs/ 说明

• 许可：MIT（见[许可与归属](#13-许可与归属)）；第三方台账见 THIRD-PARTY.md

版本口径：本文件描述的是 package.json 里的 3.16.6（= npm latest）。

发布面以 npm pack --dry-run 实测为准：16 个文件（9 个 lib/*.js 运行时文件 + package.json、icon.svg、cordis.patch.yml、README.md、README.en.md、THIRD-PARTY.md、LICENSE）；

lib/liquid-glass/、lib/liquid-glass-bundle.js、dist/、tools/、docs/ 都不进** npm 包（package.json 的 files 负向模式）。

历史发布记录见 [docs/RELEASE.md](docs/RELEASE.md)。

---

1. 下载 · 安装

四种装载方式——先按这张表选一条，再看对应小节：

方式 · 适合谁 · 更新怎么做 · 客户端界面

一 dsh plugin add（推荐） · 默认选择；市场能识别「已安装」 · dsh plugin --profile web update dsh-mpkg-wallpaper · 完整

二 pnpm 手动装 · 自己管 profile 的依赖表 · 同上（走依赖表） · 完整

三 GitHub 克隆 · 开发者 / 离线 / 要改代码 · git pull · 完整

四 单文件 bundle · 离线应急；给非 DSH 宿主复用路由 · 重新生成并替换那个 .mjs · 只有宿主端

方式一：dsh plugin add（推荐，市场可识别）

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

方式二：pnpm 手动安装

pnpm --dir $DSH_HOME/profiles/<profile> add dsh-mpkg-wallpaper
# 重启 dsh web，浏览器 Ctrl+F5 生效

与方式一同源，只是不经 dsh plugin 包装。

方式三：GitHub 克隆（开发者 / 离线）

git clone https://github.com/XHR666/dsh-mpkg-wallpaper.git $DSH_HOME/profiles/<profile>/node_modules/dsh-mpkg-wallpaper
# 然后在 profile 的 cordis.patch.yml 注册：
#   - insert:
#       - id: dsh-mpkg-wallpaper
#         name: dsh-mpkg-wallpaper
# 重启后生效

方式三不写依赖表 ⇒ 市场不显示「已安装」（只影响显示，不影响功能）。

方式四：单文件 bundle（离线 / 拷文件即装；只装宿主端）

把宿主端内联成一个自包含 ESM 再登记：

cd /path/to/dsh-mpkg-wallpaper
node tools/build-bundle.mjs          # 产物：dist/dsh-mpkg-wallpaper.bundle.mjs（大小以该命令输出为准）
node tools/build-bundle.mjs --check  # 与源码对拍：导出面 / 路由表 / ping JSON 形状
node tools/bundle-equivalence-test.mjs  # 更全的等价性门禁（构建可复现 + 路由逐字段对拍 + 装载布局 + 变异对照）

把 dist/dsh-mpkg-wallpaper.bundle.mjs 拷到任意目录（例如 ~/.dsh/plugins/），在 profile 的 cordis.patch.yml 里按绝对路径登记，然后重开 dsh web：

# $DSH_HOME/profiles/<profile>/cordis.patch.yml
- insert:
    - id: dsh-mpkg-wallpaper
      name: /绝对路径/dsh-mpkg-wallpaper.bundle.mjs   # ← 指向那个 .mjs 文件本身

这条路装载了什么 / 没装载什么（都是代码与门禁事实）：

项 · 方式四的行为 · 依据

宿主端（上传/Range 流式播放、场景提取、音频清单、设置持久化、诊断上报、系统媒体会话等路由） · 完整（lib/index.js 及其相对 import 全部内联；外部依赖只有 node 内建） · node tools/bundle-equivalence-test.mjs：路由表（kind + path）逐条相同

/api/mpkg-wallpaper/ping · {ok, version, betterSidebar, betterSidebarVersion} 键集合与源码一致 · 同上 + build-bundle.mjs --check

客户端半（设置面板 / 壁纸层 / 磨砂 / Now playing） · 不装载。单文件里只有宿主端导出面（apply / inject / __mpwTest） · 客户端半由 DSH 客户端模块系统按包发现：扫描宿主 Loader 条目里声明了 dsh.client 的包并解析其 exports["./client"]；裸 .mjs 没有 package.json ⇒ 没有 dsh.client 声明

GET /api/mpkg-wallpaper/lg/*（遗留 WebGL 托管路由，客户端已不调用） · bundle 旁边没有 liquid-glass/ 时 404；cp -r lib/liquid-glass <bundle 目录>/ 即与源码逐字节一致 · 该路由以 import.meta.url 定位同目录 liquid-glass/；门禁两种布局都断言过

ping.version · 上一级目录没有 package.json 时返回 null（只影响版本号显示） · new URL('../package.json', import.meta.url)

「检查更新 / 一键更新」 · 无伴生 package.json 时 update-check 返回 500，update-apply 会往 bundle 同级/上级目录写文件 ⇒ 不建议在方式四下使用 · lib/index.js 的更新路由

结论：方式四是"宿主端能力"的降级装载（离线/应急/给非 DSH 宿主复用路由时好用）；要完整界面请用方式一/二/三。产物不入库（dist/ 在 .gitignore 里：它是 lib/*.js 的纯派生物，发布时现生成）。

桌面版（DSH Desktop）怎么装

DSH 桌面包目前只有 macOS / Windows。官方口径：**desktop 这个 profile 名由 Electron 壳独占，

CLI 会拒绝它的 boot / config-dump / 插件管理请求 ⇒ 桌面上不能**照抄 dsh plugin --profile desktop add …。

桌面档请按下面两条之一走（按你手上那个桌面版本的界面为准）：

1. 桌面 App 自带的插件入口（若有）：在设置/插件页添加 npm 包名 dsh-mpkg-wallpaper；

2. 手动装进桌面 profile 的依赖树：把包放进该 profile 的 node_modules/（或在其 package.json 里加依赖后装），

并在该 profile 的 cordis.patch.yml 里保留本包的挂载行（与「方式三」同形，只是 profile 换成一个由桌面壳管理的目录）。

桌面档还有一条与网页档不同的前提：宿主页面源可能不是回环 HTTP（Electron 用 file:// + IPC）。

3.11.0 起客户端已按 DSH 第一方口径兜底（location.origin 缺失或为 "null" ⇒ http://dsh.internal），

所以宿主路由在桌面档也能解析；若仍然连不上宿主，请跑 window.__mpwCompat() 与 GET /api/mpkg-wallpaper/compat

把两段 JSON 发给我们。

更新

# 方式一 / 二：走 npm 的 latest 标签
dsh plugin --profile web update dsh-mpkg-wallpaper

# 方式三：在克隆目录里
git pull

# 方式四：重新生成并替换那个 .mjs
node tools/build-bundle.mjs

更新后都要：重启 dsh web → 浏览器 Ctrl+F5。

卸载

方式一/二/三：dsh plugin --profile web remove dsh-mpkg-wallpaper。

方式四：删 .mjs + cordis.patch.yml 里那一行。

残留数据（可选清理，注意是两处不同目录）：

• 浏览器 localStorage['dsh.mpkg-wallpaper.v2']
• 主数据目录 $DSH_HOME/.dsh-mpkg-wallpaper/（未设 DSH_HOME 时是 ~/.dsh-mpkg-wallpaper/）：settings.json、web-store.json、media-audio.json、上传的 mpkg、转码缓存
• 诊断/缩略图目录 ~/.dsh/.dsh-mpkg-wallpaper/：diag-*.json、thumbs/

---

2. 30 秒快速开始

装完到看见壁纸，只走三步：

1. 装好并重启：按上一节任选一种方式装完，重启 dsh web，浏览器 Ctrl+F5。

2. 打开面板：左侧栏「设置」→「壁纸引擎背景」。

3. 选一张壁纸，任选其一：

• 拖入 .mpkg 文件（视频类直接播；场景类走静态帧/图层合成）
• 选本地图片 / 视频，或填一个图片链接
• 「自定义目录」选一个文件夹（可直接选 Steam 的 steamapps/workshop/content/431960，每个子文件夹算一张）

默认档就已经能用：总开关开（enabled）、大文件混合模式开（hybrid）、整屏虚化开（unifyAmount = 30）、Now playing 挂在左侧栏（npNowPlaying 开）。

想微调，先动这三处就够：壁纸设置 → 磨砂模糊（0–40）、界面统一 → 整屏虚化程度（0–40）、壁纸设置 → 镜头缩放（10–2000%）。

没反应时先去「其他」tab 点一次 一键诊断上报（宿主不可用会自动下载 JSON），再带上它去[反馈](#14-反馈-bug)。

---

3. 主要特性

按你能感知到的东西分组（来源、时间变化、虚化、外观、播放、库与轮换、安全、备份），不按代码模块。

📦 壁纸来源

• Wallpaper Engine .mpkg：浏览器内直接解析容器（不上传第三方）；视频类播放内嵌 mp4 / 视频纹理；场景类解析容器提取素材；时间变化按系统时间选时段素材
• Steam 创意工坊目录：自动发现 WE 安装（注册表 + `libraryfol

…(truncated)