dsh-wallpaper-plugin

Readme

# dsh-wallpaper-plugin

为 [DeepSeek Harness](https://github.com/deepseek-ai/DeepSeek-Harness)（DSH）提供**全窗口个性化背景壁纸**的 Cordis 插件。

Custom full-window wallpaper plugin for DeepSeek Harness (DSH).

[![GitHub topic](https://img.shields.io/badge/topic-dsh--plugin-blue)](https://github.com/topics/dsh-plugin)
[![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)

---

## 特性 / Features

- **全窗口壁纸** — 覆盖标题栏、左侧栏、右侧栏与聊天区，而不是只作用于聊天区
- **10 个精选预设** — 5 个深色渐变（深邃极光、赛博霓虹、落日晚霞、幽蓝深海、暗夜微芒）+ 5 张摄影壁纸（清晨薄雾、星辰宇宙、静谧雪山、赛博都市、晨雾密林）
- **三种壁纸来源** — 精选预设 / 网络图片链接 / 本地图片上传
- **亚克力磨砂面板** — 可调遮罩不透明度、实时背景模糊
- **主题自适应顶部渐变** — 跟随 DSH 主题自动切换为暗色 `#151517` 或亮色 `#FFFFFF`
- **作用域可选** — 全部（含侧栏）或仅聊天区
- **适配方式** — `cover` / `contain` / `repeat`
- **配置持久化** — 保存在 `localStorage` 的 `dsh_wallpaper_config_v2`

## 安装 / Installation

### 方式一：从 GitHub 安装（推荐）

```sh
dsh plugin --profile <profile> add github:Sostay/dsh-wallpaper
```

> **本插件是纯 JavaScript、零构建。** 源码本身就是发布产物，因此与需要编译的 TypeScript 插件不同：
> 它**不需要** `prepare` 脚本，pnpm ≥10 也**不会**要求你为构建脚本授权，安装后即可直接使用。

生产环境建议锁定 commit，避免后续推送悄悄改变实际运行的内容：

```sh
dsh plugin --profile <profile> add github:Sostay/dsh-wallpaper#<commit-sha>
```

### 方式二：通过 DSH Web GUI

打开 **设置 → 插件 → 添加插件**，填入本仓库地址即可。

### 方式三：从 tarball 安装

```sh
pnpm pack
dsh plugin --profile <profile> add ./dsh-wallpaper-plugin-1.0.2.tgz
```

## 使用 / Usage

安装并启用后，进入 **设置 → 通用 → 背景壁纸** 打开配置面板。

| 配置项 | 说明 |
|---|---|
| 启用壁纸 | 总开关，关闭后不注入任何样式 |
| 壁纸来源 | 精选预设 / 网络图片链接 / 本地图片上传 |
| 预设 | 10 个内置背景（5 渐变 + 5 图片） |
| 自定义链接 | 任意可访问的图片 URL |
| 本地上传 | 选择本地图片文件（转为 Data URL 存储） |
| 不透明度 | 壁纸本身的透明度 |
| 遮罩不透明度 | 磨砂面板的遮盖强度；侧栏会自动取该值的 60%，比聊天区更通透 |
| 模糊 | 壁纸的 `blur()` 半径 |
| 适配方式 | `cover` / `contain` / `repeat` |
| 作用域 | 全部（含侧栏）或仅聊天区 |

## 实现说明 / Implementation notes

这是一个 **UI 插件（Client half）**，遵循 DSH 的 bundle 约定：

- `index.js` — Host 半边，`export function apply() {}`，本身不注册任何 Host 资源
- `client.js` — 浏览器半边，通过 `window.__ModuleLoader__.load({ id: 'dsh-wallpaper-plugin', ... })` 注册懒工厂，工厂 id 与包名一致
- `cordis.patch.yml` — 按包名插入插件行（而非相对路径），使 Node 模块解析能定位到已安装代码
- `locale/{zh,en}.json` — 插件卡片标题与描述（`meta.title` / `meta.description`）
- `icon.svg` — 插件图标，路径相对 manifest

样式实现要点：

- **CSS 变量动态驱动**：全套动态参数（图片地址、透明度、模糊度、遮罩浓度等）均走 `--dsh-wp-*` CSS 变量，拖动滑块时仅通过 `style.setProperty` 更新变量，不重新生成或解析整张样式表，操作无卡顿。
- **高斯模糊边缘补偿**：壁纸层采用边界外扩（`-40px`）与适度缩放补偿采样暗角，移除全屏模糊过渡动画，保障拖曳滑块时的流畅度。
- **本地上传防超限**：上传图片在前端通过 Offscreen Canvas 自动等比缩放至合适尺寸并压缩，杜绝超出 `localStorage` 配额导致的壁纸丢失问题。
- **主面板全面适配**：中间栏统一作为磨砂承载面，对话区、插件页以及 DSH 新增的**自动化任务（Schedules）**页面（`[data-slot="main"] > div`）均自动透出磨砂壁纸。
- **主题自适应顶部渐变**：顶部渐变由 RGB 分量变量驱动，严格匹配 `body[data-ds-dark-theme]` 属性，跟随 DSH 的 `light` / `dark` / `system` 偏好无缝切换。
- **底部无缝透出**：覆盖 DSH 默认的底部渐变遮罩节点（会话列表 `*_fade`、输入区 `*_composerSeat`），壁纸一路延伸至窗口底边。

插件不导入任何外部运行时包，React 由浏览器模块表提供。

## 卸载 / Uninstall

```sh
dsh plugin --profile <profile> remove dsh-wallpaper-plugin
```

## 兼容性 / Compatibility

- DSH：需要支持 `dsh.bundle` 与 `dsh.client` 的版本
- 平台：Web GUI（Electron PWA 与浏览器）
- 主题：亮色与暗色均已适配

## 许可证 / License

[MIT](./LICENSE) © Sostay