dsh-bg-carousel

Readme

# dsh-bg-carousel

> DeepSeek Harness 组合包（Bundle）：对话页面背景壁纸轮播 + 定时自动换图

为 DeepSeek Harness 的 Web 界面（对话页面）提供全屏背景幻灯片：
- 每 **30 秒**自动交叉淡入淡出切换一张壁纸
- 每 **24 小时**自动从内置浅色系候选图池拉取一批新图（无需手动维护）
- 深浅主题自动适配遮罩，保证文字清晰可读

![screenshot placeholder](https://img.shields.io/badge/dsh-plugin-bg--carousel-4d6bfe)

## ✨ 功能特性

- **背景轮播**：全屏背景层，1.6s 交叉淡入淡出，`interval` 秒一张
- **定时自动换图**：启动时 + 每 `intervalHours` 小时，从 20 张精选浅色图池随机下载 `count` 张
- **本地图片优先**：你手动放进图片目录的文件永远保留，只有插件自己下载的 `auto-*.jpg` 会被清理
- **安全路由**：`/bg/*` 只服务指定目录内的图片，拒绝路径穿越
- **零配置启动**：默认图片目录为 `~/Pictures/dsh-bg-carousel`（不存在会自动创建）

## 📦 安装

```bash
# 方式一：通过 dsh 插件命令安装（推荐）
dsh plugin --profile web add dsh-bg-carousel

# 方式二：本地 bundle 加载（开发调试）
dsh --profile web --patch ./dsh-bg-carousel/cordis.patch.yml
```

安装后**重启 web profile**（或触发一次配置热重载），刷新页面即可看到效果。

## ⚙️ 配置

安装者可以在自己 profile 的 `cordis.patch.yml` 中按 id 覆盖配置：

```yaml
- id: bg-carousel
  config:
    directory: D:/我的壁纸     # 图片目录（绝对路径；默认 ~/Pictures/dsh-bg-carousel）
    interval: 30              # 轮播切换间隔（秒）
    intervalHours: 24         # 自动拉取新图间隔（小时）
    count: 8                  # 每批自动下载张数
```

| 配置项 | 默认值 | 说明 |
| --- | --- | --- |
| `directory` | `~/Pictures/dsh-bg-carousel` | 背景图片目录；支持 jpg/png/webp/gif |
| `interval` | `30` | 轮播切换间隔（秒，最小 3） |
| `intervalHours` | `24` | 自动拉取新图间隔（小时，最小 1） |
| `count` | `8` | 每批自动下载张数（最大不超过候选池大小） |

## 🖼️ 自定义图片

- **手动放图**：把图片丢进图片目录，刷新页面即加入轮播，永远不会被自动清理
- **自动换图**：定时任务从内置候选池随机挑选；想彻底关闭自动拉取，把 `intervalHours` 设为很大的值，或在 patch 中 `disabled: true`

## 🗑️ 卸载

```bash
dsh plugin --profile web remove dsh-bg-carousel
```

或删除 profile `cordis.patch.yml` 中的对应行。已下载的图片文件不会被删除，可手动清理。

## 🔧 开发

```bash
# 本地验证（不修改现有 profile 的持久配置）
dsh --profile web --patch ./cordis.patch.yml --port 0 --no-open

# 组合配置检查（不启动服务器）
dsh --profile web --patch ./cordis.patch.yml --dump-config
```

## 📄 发布到 npm

```bash
npm login
npm publish --access public
```

发布前确认：

- `files` 字段包含 `index.js`、`cordis.patch.yml`、`README.md` ✅（见 `package.json`）
- `dsh.bundle.patch` 指向 `./cordis.patch.yml` ✅
- 包名符合 npm 命名规范

## 🏷️ 仓库话题

在插件的 GitHub 仓库 Settings → Topics 中添加 `dsh-plugin`（以及 `deepseek-harness`、`dsh-bundle`），方便社区发现。

## 📜 许可

MIT

## 致谢

壁纸来自 [Unsplash](https://unsplash.com) 的公开图片（稳定 CDN 链接）。