dsh-skin-live

把一张图片或一段视频铺满整个 DSH Web 界面 —— 只改背景，不动布局。

插件在页面最底层挂一个固定画布，把应用本身的底色透明化，于是主区域和侧栏共用同一张背景；卡片、输入框、弹层仍留在原位置、原尺寸，只是变成了半透明玻璃。所有参数存在浏览器本地，素材不上传、不联网。

• 图片：PNG JPG JPEG WebP GIF AVIF BMP SVG
• 视频：MP4 WebM OGV MOV M4V MKV（静音、循环、自动播放）
• 也可以直接填一个图片 / 视频 URL，素材不用下载到本地
• 四项独立调节：面板不透明度、素材不透明度、模糊、暗化
• 停用或卸载插件后，背景层被移除、主题变量还原，界面回到默认外观

目录

• 安装
• 使用
• 参数说明
• 兼容范围
• 卸载与回滚
• 数据与隐私
• 与其它皮肤插件共存
• 本地开发
• 许可

安装

DSH 自带插件管理器，三种来源都支持。任选一种即可，不需要手改配置文件。

方式一：Web 插件页（推荐，不用命令行）

1. 打开 DSH Web 界面（默认 http://127.0.0.1:3080）。

2. 左侧栏进入 插件（Plugins）页。

3. 在安装输入框里粘贴下面这一行，确认安装：

   github:zhaochaorui-study/dsh-skin-live
   

4. 安装完成后插件会默认启用；如果列表里显示未启用，手动打开它的开关。

5. 刷新页面（Cmd/Ctrl + R），设置里就会出现「皮肤」。

方式二：命令行

dsh plugin --profile web add github:zhaochaorui-study/dsh-skin-live

发布到 npm 之后，也可以直接用包名：

dsh plugin --profile web add dsh-skin-live

--profile web 是目标 profile 名。桌面版换用 --profile desktop（尚未验证）。

方式三：离线安装包 .tgz

不想联网或想固定版本时，从 Releases 下载 dsh-skin-live-1.0.0.tgz，然后：

dsh plugin --profile web add /绝对路径/dsh-skin-live-1.0.0.tgz

也可以在插件页选择这个本地文件安装。

验证安装

dsh plugin --profile web list | grep dsh-skin-live
dsh --profile web --dump-config | grep -A2 'dsh-skin-live'

预期能看到 dsh-skin-live 这一条依赖，以及一个 id: dsh-skin-live 的加载项。

使用

界面里的路径是 设置 → 皮肤。

1. 选择背景 —— 点「选择文件」上传，或把图片 / 视频直接拖进虚线框；也可以在输入框里粘贴素材 URL。
2. 调节参数 —— 按下面的表格拖动滑块，画面实时变化。
3. 自动保存 —— 参数写入 localStorage，素材写入 IndexedDB，刷新或重启 DSH 后自动恢复。

首版的完整流程就是这三步：安装插件 → 选择背景 → 调整模糊和暗化。

参数说明

控件	范围	作用
启用皮肤	开 / 关	临时关掉背景层并还原主题，素材和参数都保留，随时开回来
背景来源	文件 / URL	本地文件存进 IndexedDB；URL 每次加载时直接引用
铺满方式	铺满 / 完整 / 拉伸	对应 object-fit: cover / contain / fill
面板不透明度	0–100%	只作用于卡片、输入框、弹层等面板表面；0% 为全透明，100% 为当前主题原色
素材不透明度	10–100%	背景图片 / 视频本身的透明度
模糊	0–40px	只模糊背景层，文字保持清晰（模糊时自动放大 6% 避免边缘露白）
暗化	0–80%	在背景上叠一层黑色蒙版，深色主题下更好读

侧栏属于全局背景画布，所以它跟随背景显示；「面板不透明度」不会把它单独盖掉。

兼容范围

环境	状态
DSH 0.2.0-rc.2 + Web / PWA	✅ 已实测
DSH Desktop（--profile desktop）	⚠️ 未验证，按需自行确认
更早的 DSH 版本	未验证；插件依赖 slots / theme / locale 三个客户端服务

实现上刻意不声明 peerDependencies，避免 DSH 运行时升级后出现版本互斥拒绝安装；服务缺失或接口变化时，插件会退化为无背景，不会影响主界面正常使用。

主题相关的实现依赖 DSH 的主题服务（theme.overrideTokens）、调色板变量（--dsw-alias-*、--dsw-specific-*）和插槽 / 语言服务，DSH 升级后如果变量被重命名，面板不透明度会回落到主题默认值（不会出现错误颜色）。

卸载与回滚

停用（保留数据）：插件页关掉开关，或在设置里关掉「启用皮肤」——背景立刻还原，参数和素材都还在。

彻底卸载：

dsh plugin --profile web remove dsh-skin-live

然后在插件页确认它已从列表消失，刷新页面。卸载后 localStorage / IndexedDB 里的参数与素材可以手动清理：

// 浏览器开发者工具 Console
localStorage.removeItem('dsh-skin-live:settings:v1');
indexedDB.deleteDatabase('dsh-skin-live:media');

数据与隐私

• 参数：localStorage 键 dsh-skin-live:settings:v1
• 素材：IndexedDB 库 dsh-skin-live:media，对象仓库 blobs，键 current
• 插件不发起任何网络请求，也不上报数据。填 URL 时，素材由浏览器按该地址直接加载。

从早期本地版 @local/dsh-skin-live 升级过来时，旧键 @local/dsh-skin-live:settings:v1 和旧库 @local/dsh-skin-live:media 里的内容会被自动沿用并复制一份到新名字下；旧数据不会被删除，方便回退到旧版本。

与其它皮肤插件共存

如果同时装了另一套皮肤系统（例如 @linxin666/dsh-client-ui-skin-center），两边都会改写背景和主题变量，会互相覆盖。建议只保留一套。

本地开发

仓库结构：

.
├── package.json        # dsh 清单：bundle patch、client 入口、注入的客户端服务
├── index.js            # Host 半边：只提供 Loader 条目，不做事
├── client.js           # Client 半边：背景层、主题 token、设置页（全部逻辑）
├── client.test.js      # 回归测试（node:test + 最小 DOM/IndexedDB 夹具）
├── cordis.patch.yml    # 插件挂载声明
├── locale/             # 设置页文案
└── icon.svg            # 插件图标

跑检查：

npm run check   # 两个入口的语法检查
npm test        # 9 项回归测试
npm pack        # 产出可安装的 .tgz

手工 link 到本机 profile 调试、以及从旧版本迁移本机配置的完整步骤，见 INSTALL.md。

设计取舍

• 背景层是 position: fixed; z-index: -1 且 pointer-events: none 的独立节点，挂在 document.body 上 —— 这是既能垫在整个应用之下、又不影响页面原有布局的唯一位置。
• 面板半透明走主题变量覆盖（theme.overrideTokens），逐个 token 读取当前主题的真实色值再混入透明度；主题没定义的 token 直接跳过，而不是猜一个颜色。
• 所有副作用都挂在 ctx.effect 上，插件卸载时移除 DOM、撤销 token 覆盖、释放对象 URL。
• 插件本体很轻（几十 KB），不带任何素材；皮肤素材由用户自己提供，因此安装包可以保持小体积。

许可

MIT