# dsh-wallpaper

[English](README.md) | [简体中文](README.zh-CN.md)

为 DeepSeek Harness Web 提供持久化自定义背景图的插件。

`dsh-wallpaper` 会在 **设置 -> 通用** 中增加一个背景图设置项，可用于：

- 选择本地图片或 MP4 视频作为背景；
- 调整界面表层透明度和背景模糊度；
- 随时移除背景图。

图片会在浏览器本地压缩。最大 300 MB 的 MP4 视频仅上传给本机运行的 DSH Host。
检测到本机的 `ffmpeg` 与 `ffprobe` 时，视频会以单遍快速编码压缩为高质量 H.264
背景视频：目标约 18 MB、最高 1080p、最高 30fps。背景视频会静音，因此会移除音轨。
未检测到这些可选工具时，插件会直接保留原始 MP4，使视频背景仍可使用，但可能占用
更多磁盘空间。上传内容会直接流式写入本地临时文件，不会完整缓存在 DSH Host 内存中。
结果保存在 `~/.dsh/wallpapers`，`localStorage` 只保存本机媒体 URL。替换或移除视频时会删除旧文件，插件启动时也会清理未被当前背景引用的历史视频。视频背景会静音、循环和自动播放，重启后自动恢复。插件的 bundle patch 还会把 Web 服务固定到 `9191`
端口。浏览器存储按“协议 + 域名 + 端口”隔离；随机端口会导致重启后看似丢失背景
设置。

## 前置条件

图片背景不需要额外软件。视频背景在未安装额外软件时也可直接保存原始 MP4 使用。
若 DSH Host 所在设备安装了 `ffmpeg` 与 `ffprobe`，且二者可从 `PATH` 调用，则会启用本机压缩。

## 截图

Web profile 中的壁纸效果（图片背景 + 调整后的表层透明度）：

![壁纸效果](https://raw.githubusercontent.com/Frog755/dsh-wallpaper/main/assets/wallpaper-effect.png)

**设置 -> 通用** 中的壁纸设置卡片：

![壁纸设置](https://raw.githubusercontent.com/Frog755/dsh-wallpaper/main/assets/wallpaper-settings.png)

## 兼容性

- 目标环境：DeepSeek Harness 的 **Web profile**（`dsh web` 或桌面版内嵌的 Web UI）。
  设置卡片由 DSH client runtime 渲染，需要支持 `localStorage` 的现代浏览器。
- bundle patch 会把 Web 服务固定到 `http://127.0.0.1:9191`；原因及端口被占用时的
  处理方式见下文[固定地址](#固定地址)。
- 图片背景无需外部工具。视频背景接受最大 300 MB 的 MP4：未检测到
  `ffmpeg`/`ffprobe` 时保留原始文件，检测到时在本机压缩为 H.264（目标约 18 MB、
  最高 1080p、最高 30fps、移除音轨）。
- 对等依赖：`react ^18.2.0`、`@deepseek-ai/cordis ^4.0.1` 及 `package.json` 中列出的
  DSH client 包。这些由 DSH 宿主安装提供，无需手动安装。

## 安装

从 npm 直接一行安装：

```powershell
dsh plugin --profile web add -w @frog755/dsh-wallpaper
```

首次安装后，重启 `dsh web` 或 DeepSeek Harness 桌面端，使 Host 重新读取 bundle
patch。随后打开 **设置 -> 通用 -> 背景图片** 选择图片。

如需从克隆的仓库本地开发，请在仓库根目录执行：

```powershell
dsh plugin --profile web add -w .
```

之后修改 `lib/client.js` 时，DSH 的 client HMR 链会尝试加载新 bundle；若浏览器
仍使用旧模块，请硬刷新页面。

## 固定地址

插件会把 DSH Web 固定到 `http://127.0.0.1:9191`。这是有意设计：`localStorage`
按 origin 隔离，而端口属于 origin 的一部分。

如果 `9191` 已被占用，请先停止占用端口的进程，或在启动 DSH 前修改
`cordis.patch.yml` 中的端口。换端口后会使用新的浏览器存储命名空间，因此需要在
新地址上重新选择一次背景图。

## 本地保存的数据

所有数据只保存在当前浏览器 profile 中：

- `dsh-wallpaper:image`
- `dsh-wallpaper:opacity`
- `dsh-wallpaper:blur`

首次运行时，如果没有 `dsh-wallpaper` 自己的保存值，插件会自动迁移旧
`dsh-skin` 插件保存的背景图、透明度和模糊度，无需重新选择背景。

图片不会上传到服务器。它们以压缩 data URL 保存在浏览器中，并会缩放以控制
本地存储占用。

## 开发

客户端 bundle 使用 DSH 的 `window.__ModuleLoader__.load` 格式，因此无需构建步骤。
它由 `dsh-client-modules` 提供，并由 `dsh-client-hmr` 监视内容变化后通知浏览器。

## 署名

本独立背景图插件源自并大幅重构自
[KinGao294/dsh-skin](https://github.com/KinGao294/dsh-skin) 的背景图组件，遵循 MIT
许可。原始版权声明保留在 [LICENSE](LICENSE) 中。