壁纸持久化wuweiran-web/dsh-beauty-persist

dsh-beauty-persist

在 DSH Desktop 重启后保留 dsh-dream-skin / dsh-liquid-glass 的壁纸与主题。

为什么需要它

DSH Desktop shell 启动其 Web 载体时使用操作系统分配的随机端口
（--port 0），因此浏览器源（origin）在每次重启后都会改变。浏览器的
localStorage 是按源隔离的——像壁纸图片这样的视觉状态
（由 dream-skin / liquid-glass 存储在 localStorage 中）在每次重启后都会消失，
即使它从未被删除。

dsh-beauty-persist 将这些视觉状态迁移到一个服务端 JSON 文件中，
该文件与端口无关。它在每次页面加载时恢复状态，并在你于 UI 中调整设置时
将更改推送回服务器。

它的功能

- 宿主端（lib/index.js）
- 提供 GET /beauty-persist/state（当前持久化状态）和
POST /beauty-persist/state（替换持久化状态）。
- 提供 GET /beauty-persist/wallpaper.gif（已存储的 GIF 壁纸）和
POST /beauty-persist/wallpaper.gif（上传新的 GIF 壁纸）。
- 将持久化状态作为 window.__DSH_BEAUTY_PERSIST_STATE__ 注入到 index.html
响应中，且位于启动清单（boot manifest）之前，这样浏览器端就能在
dream-skin/liquid-glass 初始化之前同步恢复状态。
- 浏览器端（lib/client.js）
- 在页面加载时，从服务器注入的状态中恢复每一个
dsh-dream-skin: / dsh-liquid-glass: 的 localStorage 键。
- 挂钩 Storage.prototype.setItem / removeItem，并将之后的任何更改
镜像回服务器（防抖处理），因此你的壁纸/皮肤选择会持续保留，
无需你做任何额外操作。
- 暴露 uploadGifWallpaper(gif) 以设置动态 GIF 壁纸。

状态存储在 ~/.dsh/beauty-persist-state.json；GIF 壁纸文件
位于 ~/.dsh/beauty-persist-wallpaper.gif。

安装

适用于任何已经运行 dsh-dream-skin 和/或
dsh-liquid-glass 的 profile（通常是 DSH Desktop 使用的 desktop profile）。

cd ~/.dsh/profiles/desktop

添加依赖（将仓库 URL / tag 调整为你所安装的内容）
pnpm add dsh-beauty-persist@github:/

在 package.json 的 dsh.profile.bundles 中注册该 bundle
"dsh-beauty-persist",

然后重启 DSH Desktop，以便加载新的 bundle。

用法

无需任何配置。安装后：

1. 重启 DSH Desktop（加载 bundle 所必需）。
2. 在 GUI 中打开 Settings → Theme / 外观，像往常一样选择你的壁纸 / 皮肤。
3. 该选择现在已持久化到服务端——它能在重启、端口变化、
浏览器缓存清除，甚至切换浏览器后依然保留。

如果你在之前会话的 localStorage 中已经设置了壁纸
（现在孤立在旧端口下），要么在安装后重新选择一次，要么
手动为服务器状态播种：

示例：将 data-URL 或 URL 放入状态文件json
echo '{"dsh-dream-skin:wallpaper":"https://example.com/wall.jpg"}' \
~/.dsh/beauty-persist-state.json

动画 GIF 壁纸

dream-skin 的“选择图片”流程会通过 canvas 重新编码，并将动画 GIF 压平为静态 JPEG。若要改用动画 GIF，请将其上传到此插件——浏览器会原生渲染该 GIF（它会播放），并且文件存储在服务端，因此重启后依然保留。

在 GUI 中（无需命令行）： 安装后，打开
设置 → 主题 / 外观——外观部分会出现一行 “GIF 壁纸上传（动图）”。
点击 选择 GIF…，选择一个本地 .gif，它就会被上传、激活并持久化。刷新 GUI 即可看到动画。

从命令行：
sh
在此仓库中——脚本会自动发现 DSH Desktop GUI 端口
node scripts/set-gif-wallpaper.mjs "C:\path\to\my-wallpaper.gif"

或者，如果你的 GUI 在其他位置提供服务，则显式传入基础 URL
node scripts/set-gif-wallpaper.mjs "C:\path\to\my-wallpaper.gif" http://127.0.0.1:8080

上传后，刷新 GUI（或重启 DSH Desktop）：该 GIF 会作为壁纸播放，并在重启后依然保留。随时可以通过使用不同的 GIF 重新运行脚本来更换它。

MP4 视频壁纸

CSS background-image 无法播放视频，因此 MP4 壁纸由此插件渲染为一个全视口的  图层（静音、循环、object-fit cover）。

在 GUI 中： “MP4 视频壁纸（动效）” 行（同样位于
设置 → 主题 / 外观下）允许你选择一个本地 .mp4 并激活它，或移除视频壁纸。

从命令行：
sh
node scripts/set-mp4-wallpaper.mjs "C:\path\to\my-wallpaper.mp4"
可选，显式指定基础 URL：
node scripts/set-mp4-wallpaper.mjs "C:\path\to\my-wallpaper.mp4" http://127.0.0.1:8080

MP4 存储在 ~/.dsh/beauty-persist-wallpaper.mp4（最大 50 MB），并在重启后依然保留。

🎨 皮肤中心（素材库）

构建你自己的壁纸库：上传一次图片 / GIF / MP4，然后随时一键切换——所有内容都存储在服务端，并在重启后依然保留。

在 GUI 中： “🎨 皮肤中心” 行（位于设置 → 主题 / 外观下）为你提供：

- 上传素材…——选择一个本地图片 / GIF / MP4，将其添加到素材库
（存储在 ~/.dsh/beauty-persist-assets/，每个最大 50 MB）。
- 素材的缩略图网格——点击任意缩略图即可立即将其应用为壁纸（图片/GIF 渲染为背景图层，GIF 会原生播放动画；MP4 渲染为循环视频图层）。
- 缩略图上的 ✕ 会从素材库中删除该素材。

当前应用的素材会记录在服务端状态中，因此重启后相同的壁纸会自动恢复。

要求

- @deepseek-ai/dsh-client-runtime、@deepseek-ai/dsh-client-locale、
@deepseek-ai/dsh-client-ui-theme（标准 Web 客户端技术栈；存在于
每个已发布的 Web 组合中）。
- 宿主部分需要 Node >= 18。

许可证

MIT