dsh-webui-background

Readme

# dsh-webui-background

[English](README.en.md)

`dsh-webui-background` 是一个独立的 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 插件，为 Web UI 提供可配置的背景图。它通过 Harness 的组合包与客户端插件扩展点安装，不需要修改或替换 `website/public`、`apps/web/public` 中的文件。

## 功能

- 设置页面内嵌“Web UI 背景”标签页，可上传、拖放和预览图片。
- 支持 PNG、JPEG、GIF 和 WebP，按文件内容识别格式，最大 20 MiB。
- 分别调整浅色模式与深色模式遮罩，保存后立即生效。
- 可以暂时停用背景而保留图片，也可以一键删除图片并恢复默认界面。
- 设置与图片按 Harness profile 独立保存；多个 profile 互不影响。
- 远程页面可以查看设置，只有回环地址页面能够修改，避免受信任 Host 被远程网页写入。

## 安装

需要支持外部组合包与浏览器客户端插件的 DeepSeek Harness `0.1.0-rc.5` 或更高版本。

```sh
pnpm dsh plugin --profile web add dsh-webui-background@next
pnpm dsh web
```

以上命令需要在 DeepSeek Harness 源码仓库根目录执行。如果 `dsh` 已经全局安装并加入系统 `PATH`，也可以去掉命令开头的 `pnpm`。PowerShell 提示“无法将 dsh 项识别为 cmdlet”时应使用 `pnpm dsh`；`npm dsh` 不是有效的 npm 命令。

如果 Web UI 已经在运行，请重启它。打开“设置 → 插件 → Web UI 背景”，选择图片并保存。

卸载：

```sh
pnpm dsh plugin --profile web remove dsh-webui-background
```

卸载不会主动删除 profile 数据。需要清除图片时，请先在插件页面点击“恢复默认”。

## 关于文件名

上传源文件可以使用普通的 `.webp`、`.png` 等扩展名。插件会读取文件内容并自动识别格式；保存到 profile 后会使用内容哈希作为内部文件名且不带扩展名，这是正常行为。浏览器通过插件的 `/webui-background` 路由取得正确的 `Content-Type`，所以不依赖磁盘扩展名。

每个 profile 的数据位于该 profile 目录下的 `data/webui-background/`。`state.json` 保存开关、遮罩和修订号，图片以 `background-<sha256>` 保存。

## 从源码安装

```sh
git clone https://github.com/lx963/dsh-webui-background.git
cd dsh-webui-background
pnpm install
pnpm test
pnpm build

# 切换到 DeepSeek Harness 源码仓库根目录，再传入插件源码的绝对路径
cd /path/to/deepseek-harness
pnpm dsh plugin --profile web add /path/to/dsh-webui-background
```

发布包在 `prepack` 阶段生成 Host ESM、浏览器 CJS 和类型声明。源码使用 Node.js `^22.19.0 || >=24` 与 pnpm 10。

## 安全与限制

- SVG 不受支持，因为它可以包含主动内容。
- 图片必须通过魔数校验；扩展名与浏览器传入的 MIME 类型不作为信任依据。
- 图片响应使用 `no-store` 与 `nosniff`；URL 中的修订号仅用于页面刷新当前图片。
- 插件每个 profile 只保留一张当前图片，并使用乐观修订号避免多个页面静默覆盖彼此的设置。

## 许可证

[MIT](LICENSE)