界面背景定制rumeng-ming/dsh-background-image

dsh-background-image

License: MIT
CI
DSH
Status

一个用于 DeepSeek Harness
Web GUI 的静态 bundle 插件，它添加了一个“背景图 / Background”设置页面，用于自定义
应用程序背景。安装一次后，它会在重启后继续存在——并且会在重启之间记住
你上次设置的背景。

非官方项目。 与 DeepSeek 无关联，也未获得其认可。
已在 DeepSeek Harness 0.1.0-rc.6 上测试。

功能

- 渐变预设 — 5 个精选渐变，每个都有浅色/深色变体
- 纯色 — 原生颜色选择器
- 图片 URL — 任意直接图片链接
- 本地图片 — Host 半部分读取文件（png/jpg/jpeg/webp/gif，
≤ 5 MB），并通过 /dyn-bgimg/background 提供服务，这是一个普通的同源 URL
- 不透明度滑块 — 背景强度 0–100%，保持文字可读
- 图片尺寸控制 — 适应窗口（cover）、完整显示（contain），或
自定义 30–200% 缩放滑块
- 感知浅色/深色 — 每种配色方案都有独立的浅色和深色值
- 持久化 — 上次设置的背景会通过 DSH settings
服务保存，并在重启后自动恢复
- 可选目录白名单 — 将本地图片加载限制到特定
目录（参见配置）

截图

应用了“极光紫 / Aurora”渐变预设的 Web GUI：

应用了 Aurora 渐变背景的 DeepSeek Harness Web GUI 截图

工作原理

一个双面 bundle 行（cordis.patch.yml）：

- Host 半部分（lib/index.js）— 一个 Cordis 插件（inject: fs, webServer），
注册四个 HTTP 路由：GET /dyn-bgimg/background（提供
内存中的图片）、POST /dyn-bgimg/load（将本地图片文件读入
内存并返回其 URL），以及 POST /dyn-bgimg/save +
GET /dyn-bgimg/state（通过
settings 服务持久化/恢复上次设置的背景；在没有 settings
provider 时回退到内存存储）。
- 浏览器半部分（lib/client.js）— 一个由
dsh.client 声明（平台 web）拾取的 window.__ModuleLoader__.load
bundle。它注册设置页面，通过 fetch 与 Host 通信，并在
html::before 图层上以 z-index: -1 渲染背景（保证位于所有
应用内容之下）。当背景处于活动状态时，应用框架 token（--dsw-alias-bg-base）会被设置为
transparent，并在停止时恢复。

安装

需要 pnpm（npm install -g pnpm）。

从此仓库安装（本地检出或克隆后）：

1. 安装插件自身的依赖（schemastery）
cd C:\path\to\dsh-background-image
npm install

2. 将其链接到 web 配置中
dsh plugin --profile web add link:C:\path\to\dsh-background-image

或者从已发布的注册表包安装（尚未发布）：

dsh plugin --profile web add dsh-background-image

然后重启 DSH。“背景图”部分会永久显示在“设置”下。

卸载：

dsh plugin --profile web remove dsh-background-image

配置

要在首次启动时自动应用本地图片（在保存任何背景之前），请在 lib/client.js 顶部设置 DEFAULT_IMAGE（例如
"C:\\Users\\you\\Desktop\\bg.jpg"）；将其留空以禁用自动加载。
一旦应用了背景，它就会被持久化并优先使用。

要将本地图片加载限制到特定目录（纵深防御；
默认为空，即允许任意路径），请填充 lib/index.js 顶部的
ALLOWED_DIRS：

const ALLOWED_DIRS = ["C:\\Users\\you\\Pictures", "D:\\Wallpapers"]

路径在比较时会忽略大小写并使用规范化分隔符，且在比较前会折叠 ..
路径段。

要求

- DeepSeek Harness 0.1.0-rc.6（API 在 1.0 之前不稳定；其他版本可能会出问题）
- 一个在 Host 上提供 fs 和 webServer 的配置（随附的 web
配置会提供），以及在 Client 上提供 dsh-client-ui-theme / dsh-client-ui-conversation 的配置。

开发

npm test      # 单元测试（node:test，无额外依赖）
npm run check # 对每个模块进行语法检查

测试覆盖了 lib/logic.js 中的共享纯逻辑（路径校验、
保存/恢复映射）、Host 半部分针对模拟的
fs/webServer/settings 服务的四个 HTTP 路由，以及浏览器半部分的真实 bundle
（在带有伪造 DOM 的 Node vm 沙箱中加载），包括尺寸模式、
不透明度钳制、CSS 构建、恢复流程以及 dispose 时的清理。

CI 会在每次推送到
main 以及每个拉取请求时，在 Node 18/20/22 上运行 npm run check + npm test。

仓库布局

├── package.json           # dsh.bundle + dsh.client 声明
├── cordis.patch.yml       # 该 bundle 的唯一双面行
├── CHANGELOG.md
├── docs/
│   └── screenshot.jpg     # README 截图（Aurora 渐变预设）
├── lib/
│   ├── index.js           # Host 半部分（图片路由 + 设置持久化）
│   ├── logic.js           # 共享纯逻辑（校验 + 状态映射）
│   └── client.js          # 浏览器半部分（设置页 + 恢复）
├── test/                  # 单元 + 集成测试（node:test）
├── .github/workflows/     # CI（语法检查 + 测试，Node 18/20/22）
└── legacy-dynamic/        # 早期动态插件源码（已归档）

许可证

MIT — 参见 LICENSE。