dsh-live-backdrop

DSH Web GUI 动态背景 + UI 主题接管插件：静态图 + GIF + MP4/WebM 视频背景，以及不依赖任何皮肤插件的界面外观系统（三个视觉方向预设 + 六色五形参全部可调）。

架构参考 dsh-skins 皮肤体系（皮肤注册 / 路由 / 插槽 / 持久化机制），不含任何皮肤资产，不照搬任何现成皮肤。

特性

与第三方皮肤/插件的关系

• 本插件不依赖任何第三方 UI 包，面板入口在官方设置页（设置 → 插件 → 插件配置 → 动态背景）；
• 主题模块把配置写入 body 内联样式（优先级高于一切样式表规则），并订阅 theme/change 在官方主题写入之后重新覆盖——即「完全接管」，其他皮肤的选择器覆盖压不过本插件；
• 可与其他皮肤/插件共存；即使移除了其他皮肤插件，本插件的背景、主题、面板全部照常工作。注意：若启用了第三方皮肤，移除前先切回官方默认外观，否则启动清单会引用不存在的皮肤包。

安装

# 在项目根目录（本仓库）
pnpm install
pnpm build          # 产出 packages/dsh-live-backdrop/lib/{index.js,client.js}

# 安装进 DSH web profile（link 本地包，改源码后重跑 build 即可）
dsh plugin --profile web add link:$(pwd)/packages/dsh-live-backdrop

# 把插件行写入 profile 用户补丁层（C:\Users\<你>\.dsh\profiles\web\cordis.patch.yml）：
#   - insert:
#       - id: live-backdrop
#         name: 'dsh-live-backdrop'

为什么插件行要写在用户补丁层而不是包的 cordis.patch.yml：DSH 宿主的 HMR 只热监听用户补丁层（profile 的 cordis.patch.yml 与 ~/.dsh/cordis.patch.yml），bundle 补丁层是启动时快照。写在用户补丁层可「装完立即生效、无需重启」，且重启后依然持久。若两层同时写同一 id，会因重复插件 id 导致启动失败（本包内的 cordis.patch.yml 因此留空，仅含说明注释）。

安装后刷新 GUI 页面，进入 设置 → Web UI 插件 → 动态背景。

日常迭代（改代码后如何生效）

卸载：

dsh plugin --profile web remove dsh-live-backdrop
# 并删除 profiles/web/cordis.patch.yml 中 live-backdrop 的 insert 行

素材目录与规格建议（性能关键）

目录：~/.dsh/backgrounds/（可用环境变量 DSH_LIVE_BACKDROP_DIR 覆盖）。

插件的优化只能"少干活、干完就停"，真正决定 CPU/内存的是素材本身。 建议规格：

运行时兜底策略（插件内置，无需配置）：

• visibilitychange：标签页切走 → 视频暂停，切回 → 恢复播放；
• prefers-reduced-motion: reduce → 视频不自动播放（尊重系统无障碍设置）；
• navigator.deviceMemory < 4GB 且开启「低内存降级」→ 视频只显示静态帧（面板可关）；
• 素材加载失败 → 显示纯色底，不会报错刷屏。

素材服务与安全

• 素材经 /api/live-backdrop/media/<文件名> 提供，支持 HTTP Range（视频边下边播、可 seek）；
• 仅白名单扩展名 + 双重的目录穿越校验（文件名单段化 + 解析后必须位于素材目录内）；
• 全部 API 带同源围栏（Sec-Fetch-Site / Origin），拒绝跨站浏览器请求。

API 摘要

项目结构

packages/dsh-live-backdrop/
├─ package.json          # dsh.bundle.patch + dsh.client 声明（DSH 插件标准声明）
├─ cordis.patch.yml      # 留空（插件行见安装步骤，写入 profile 用户补丁层）
├─ build.mjs             # esbuild：host ESM + client __ModuleLoader__ 外壳
└─ src/
   ├─ index.ts           # 宿主：路由挂载 + system prompt 公告
   ├─ store.ts           # 素材扫描 + JSON 持久化 + 三预设主题（原子写入）
   ├─ routes.ts          # /api/live-backdrop/*（含 Range、同源围栏、/theme）
   ├─ theme-shared.ts    # 主题配置共享类型
   └─ client/
      ├─ index.ts        # 浏览器：字典 / body 作用域 / 引擎 / 主题控制器 / 面板插槽
      ├─ engine.ts       # 背景引擎（全部性能与内存策略的落点）
      ├─ theme.ts        # 主题控制器（token 覆盖 + theme/change 重放 + 颜色数学）
      ├─ theme-defaults.ts # 客户端兜底主题（玻璃拟态）
      ├─ api.ts          # 宿主 API 客户端
      ├─ panel.ts        # 设置页面板（React.createElement，无 JSX）
      ├─ styles.ts       # CSS（--dsw-* token + 毛玻璃/圆角/边框注入层）
      └─ locales.ts      # 中英双语文案

与其他皮肤共存

背景层是一个 position:fixed; z-index:-1 的独立图层，位于 body 背景与页面内容之间：

• 覆盖当前皮肤的 body 背景图（含 miku 等会写 background-image 的皮肤），皮肤自带的标题栏 / 状态栏等 chrome 不受影响；
• 面板与皮肤中心同在「Web UI 插件」分组，两套开关互不干扰。