bgx-dynamic-background

Readme

# 🎨 动态背景切换器 (Dynamic Background Switcher)

> DeepSeek Harness (DSH) 动态背景插件：上传 GIF/WebP 动图与静态图、内置 12 色纯色调色板，定时丝滑交叉淡入淡出切换页面背景，聊天区自动叠加主题色保护层。

![Banner](assets/banner.svg)

[![License: MIT](https://img.shields.io/badge/license-MIT-3da639.svg)](LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/njuptlzf/dsh-dynamic-background?style=flat&color=3da639)](https://github.com/njuptlzf/dsh-dynamic-background/stargazers)
[![Repo size](https://img.shields.io/github/repo-size/njuptlzf/dsh-dynamic-background?color=8b5cf6)](https://github.com/njuptlzf/dsh-dynamic-background)
[![DSH Plugin](https://img.shields.io/badge/DSH%20Plugin-dsh--plugin-3b82f6.svg)](https://github.com/topics/dsh-plugin)
[![DeepSeek Harness](https://img.shields.io/badge/DeepSeek%20Harness-plugin-06b6d4.svg)](https://github.com/topics/deepseek-harness)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/njuptlzf/dsh-dynamic-background/pulls)

---

## ✨ 特性

- **上传动图/静态图**：GIF / WebP / APNG 动图与 PNG / JPG / SVG 等静态图，支持**多选**与**拖拽**上传，带进度条，缩略图**逐张即时**出现（单张 ≤25MB）
- **内置纯色调色板**：赤橙黄绿青蓝紫粉白灰黑棕 12 色，点击即添加并立即应用，可与上传图片**混合轮换**
- **定时丝滑切换**：间隔 3–120s，顺序 / 随机模式，双图层 **opacity 交叉淡入淡出** + 慢速 Ken Burns 缩放（默认 1.4s 过渡），尊重系统"减少动态"偏好
- **自动可读性保护层**（主题自适应 `color-mix`）：
  - 聊天内容列 `[data-chat-flow]`
  - 状态栏（输入框下方统计行）
  - 会话头部整条带（会话名 / 模式标签 / 「对话·轨迹」导航）
- **完整显示模式**：默认 `contain`（图片等比缩放、整张可见、居中），可选 `cover` 铺满
- **可选美化**：背景虚化（0–12px）、遮罩强度（0–90%）
- **常驻运行**：状态与定时器挂在插件实例上，**关闭设置页后背景仍自动切换**
- **数据持久化**：图片与设置存入浏览器 IndexedDB，**重启 DSH / 刷新页面后自动恢复**（随浏览器数据存储；清浏览器数据会一并清除）
- 全程无后端依赖：上传走浏览器 `File.arrayBuffer()` + 纯 JS base64，不依赖受限全局

## 📸 截图

> 占位：将真实截图（PNG）放入 `assets/` 后替换下面的链接。

| 设置页 | 背景效果 |
| --- | --- |
| ![设置页](assets/screenshot-settings.png) | ![背景效果](assets/screenshot-bg.png) |

## 📦 安装（插件市场 / 一键安装）

本插件是**标准 DSH bundle 插件**（npm 包结构，带 `dsh.client` 声明与 `cordis.patch.yml`），可被 `dsh-plugin` 社区市场收录，并通过官方命令一键安装：

```bash
dsh plugin --profile web add github:njuptlzf/dsh-dynamic-background
# 无全局 dsh 时：
npx @deepseek-ai/dsh plugin --profile web add github:njuptlzf/dsh-dynamic-background
```

安装后**重启 `dsh web`**，打开 **设置 → 动态背景** 即可使用。

- 市场收录：仓库带 `dsh-plugin` / `deepseek-harness` topic，社区市场（如 [awesome-dsh-plugin 每日爬虫](https://github.com/wgd753/awesome-dsh-plugin)、[dsh-plugin-market](https://github.com/TheYoungChen/dsh-plugin-market)）会自动收录；
- `lib/` 已预编译提交，git 安装零构建步骤；
- 旧版**动态插件**源码保留在 [`legacy/dynamic-plugin.client.js`](legacy/dynamic-plugin.client.js)（会话内 `cordis_define` + `cordis_run` 方式）。

## 🎛️ 使用

激活后进入 **设置 → 动态背景** 页：

| 控件 | 说明 |
| --- | --- |
| 开启背景 | 总开关 |
| 纯色背景 | 12 色色板，点击添加并立即应用 |
| 选择图片 / 拖拽 | 上传动图与静态图（多选，Ctrl/Shift） |
| 显示模式 | 完整显示（contain，默认）/ 铺满（cover） |
| 切换间隔 | 3–120s（默认 15s） |
| 过渡时长 | 0.3–3s 交叉淡入淡出（默认 1.4s） |
| 背景虚化 / 遮罩强度 | 可选美化 |
| 随机 / 顺序 · 播放 / 暂停 · 下一张 · 清空 | 播放控制与列表管理 |

## 🧩 技术要点

- **背景舞台**：动态插入 `<style>` 维护 `body::before` / `body::after` 两个 `z-index:-1` 固定图层，切换时旧图淡出、新图淡入；图层规则 = rgba 兜底 + `color-mix` 主题自适应渐变（含 Ken Burns 与 `prefers-reduced-motion`）
- **画布透明**：`theme.overrideTokens` 将 `--dsw-alias-bg-base` 置为 `transparent`，背景图在非保护区域完整透出
- **保护层选择器**全部基于稳定 `data-*` 属性与结构选择器（无哈希类名依赖），默认 84% 主题表面色
- **架构**：bundle 插件——node half 空存根 + client half（`window.__ModuleLoader__.load` 契约，`dsh.client.inject` 声明依赖），`dsh.bundle.patch` 指向 `cordis.patch.yml`；`lib/` 预编译提交，`dsh plugin add github:<owner>/<repo>` 即可安装
- **上传**：`file.arrayBuffer()` + 纯 JS base64 编码（bundle 环境亦可直接用 FileReader / URL）

## 📁 目录结构

```
bgx-dynamic-background/
├── package.json                       # bundle 包元数据（dsh.client / dsh.bundle.patch 声明）
├── cordis.patch.yml                   # 挂载行：注册进 profile 浏览器 roster
├── tsdown.config.ts                   # 独立构建配置（node ESM + client ModuleLoader CJS）
├── src/
│   ├── index.ts                       # node half 存根（纯 UI 插件）
│   └── client/index.js                # 客户端源码（设置页 UI + 背景舞台 + 上传）
├── lib/
│   ├── index.mjs                      # 预编译 node half
│   └── client.js                      # 预编译 client half（window.__ModuleLoader__ 契约）
├── legacy/dynamic-plugin.client.js    # 旧版动态插件源码（cordis_define 方式）
├── assets/
│   ├── banner.svg                     # 仓库 Banner
│   └── screenshot-*.png               # 截图（待替换为真实截图）
├── README.md
└── LICENSE                            # MIT
```

> 打包：`npm pack` 生成 `bgx-dynamic-background-<version>.tgz`；`lib/` 为预编译产物（与 Aqua / dsh-plugin-market 等社区插件一致），安装走 `dsh plugin add`，无构建步骤。npm registry 发布需 `npm login` 后 `npm publish`。

## 📜 版本历史

- **v1.2.0**（当前）：IndexedDB 持久化——图片与设置重启后自动恢复
- **v1.1.0**：bundle 插件化——node half + client half（ModuleLoader 契约）、`dsh plugin add` 一键安装、可被插件市场收录
- 动态插件迭代：`pkg-1` 初版（聊天区浮窗）→ `pkg-2` 迁入设置页 → `pkg-3` 修复 clearAll 崩溃 → `pkg-4` 修复缩略图刷新 / 多选 / 进度条 → `pkg-5` 默认可读保护层 → `pkg-7` 自适应亮度 + 完整显示 → `pkg-8` 保护层收窄到聊天列 → `pkg-9` 状态栏保护层 → `pkg-10` 头部保护层 + 侧边栏半透明 → `pkg-11` 修复 override 层覆盖 → `pkg-13` 移除侧边栏样式 + 纯色调色板（归档于 `legacy/`）

## 🤝 贡献

欢迎 Issue 与 PR：新色板、动效优化、更多保护区域、性能改进等。

## 📄 License

[MIT](LICENSE) © 2025 Kasakaze (njuptlzf)