dsh-ui-background
为 DeepSeek Harness Web GUI（dsh web）提供的一键背景切换插件：内置渐变预设、本地图片上传与路径引用、必应每日壁纸，支持不透明度、模糊、填充方式调节；浅色/深色配色自动适配，背景随手持久化到设置文档。
插件以独立仓库形式自包含构建（不修改 DSH 内核），通过 Web profile 的 patch 层接入运行中的实例即可使用。
目录
特性
- 一键切换：界面右下角悬浮按钮在「无背景 → 预设… → 无背景」间循环切换
- 内置预设：极光 / 落日 / 翡翠三套渐变；每套在浅色/深色配色下各有一套取值，切换主题不失效
- 自定义图片：支持本地文件上传（落盘到
$DSH_HOME/ui-background/） - 比例提示：上传后展示「图片 16:9 · 窗口 16:9」对比；上传默认以
cover铺满全屏 - 必应每日壁纸：一键取必应首页壁纸（可选 4K / 1920×1080、可选地区），支持「换一张」回溯最近 8 天与「每日自动更新」；图片由 Node 半边下载并缓存到本地，因此不依赖热链、断网也能显示已缓存的图
- 精细调节：不透明度（0.05–1）、模糊（0–32 px）、填充方式（铺满 / 适应 / 平铺）
- 持久化：所有选择写入
$DSH_HOME/settings.yaml，刷新后保持 - 可读性保护：面板底色降为 45% 同色系半透明底衬，背景可见同时文字保持对比度
- 动态特效：可在背景之上叠加动态流光（窄亮斜向光带，深色配色加色发光）或粒子（随配色自适应的漂浮亮点）效果（二选一、互斥开启；随背景激活，尊重系统「减少动态效果」）
- 界面细节：设置行按「来源 / 显示 / 特效」分组，全部控件可键盘操作（可见焦点环、滑块朗读百分比与像素值），动效与配色逐项对齐 DSH 自身的设计 token
- 零侵入：不修改 DSH 内核、不占用任何既有 UI 座位；插件卸载后界面完全恢复默认
界面与效果
| 位置 | 内容 |
|---|---|
| 设置 → 通用 → 「背景」行 | 按 来源（预设卡片 / 上传图片 / 必应壁纸）、显示（不透明度、模糊、填充方式）、特效（关闭 / 动态流光 / 粒子效果）三组排列；底部为清除背景与比例提示 |
| 界面右下角悬浮胶囊 | 单击循环切换背景（显示当前背景名） |
安装
前置要求
- Windows / macOS / Linux 上可运行的
dsh web实例（dshCLI 或从源码运行） - 仅当你需要自己从源码构建时才需要 Node.js ≥ 22 与 pnpm ≥ 9；直接安装预构建包不需要
方式一：安装预构建包（推荐，一条命令）
本插件为 dsh.bundle 组合包（内含 Node 半边、浏览器半边与 patch 层），以 npm 发布或本地 tarball 提供。安装（任选其一）：
dsh plugin --profile web add dsh-ui-background # npm 已发布时
dsh plugin --profile web add ./dsh-ui-background-0.5.0.tgz # 或本地打包文件
dsh plugin 会自动：安装依赖 → 把插件追加进 profile 的 bundle 层（dsh.profile.bundles）→ 插件行随组合生效。然后重启一次 dsh web，刷新浏览器即可看到设置 → 通用 →「背景」行与右下角悬浮按钮。
发布前请先在仓库执行
pnpm install && pnpm run build && pnpm pack确保lib/产物打齐（files已限定发布内容）。
卸载：
dsh plugin --profile web remove dsh-ui-background
方式二：从源码接入（开发/调试用）
克隆仓库并构建：
git clone <本仓库地址> dsh-ui-background
cd dsh-ui-background
pnpm install
pnpm run build # 产出 lib/index.js（Node 半边）与 lib/client.js（浏览器半边）
在 $DSH_HOME/profiles/web/cordis.patch.yml 追加（$DSH_HOME 默认 ~/.dsh，可用环境变量确认）：
- insert:
- id: ui-background
name: 'D:/绝对/路径/to/dsh-ui-background/lib/index.js'
生效条件
| 变更内容 | 生效方式 |
|---|---|
首次安装 / Node 半边（lib/index.js：图片读取、上传、必应取图路由） |
重启一次 dsh web（loader 已加载的模块不会热替换） |
仅浏览器半边（lib/client.js，设置行/按钮/渲染） |
浏览器刷新（建议 Ctrl+F5） |
必应取图链路横跨两个半边：新装或改过 Node 半边后必须先重启
dsh web，否则点「获取今日壁纸」会拿到 405（该路径在 DSH 静态兜底里等同"未注册路由"），界面显示「获取必应壁纸失败」。
使用
- 打开设置 → 通用 → 背景：
- 点预设卡片（极光 / 落日 / 翡翠 / 无）切换背景
- 点 上传图片 选择本地照片（自动铺满全屏）
- 点 获取今日壁纸 用必应每日壁纸作为背景；之后按钮变为 换一张（在最近 8 天里换）
- 调节不透明度、模糊、填充方式；清除背景一键还原
- 或直接点界面右下角的悬浮按钮，循环切换背景（必应壁纸不参与循环，避免一键切换触发联网）
- 所有选择自动保存，刷新后保持；浅色/深色配色自动适配
设置项
设置在 $DSH_HOME/settings.yaml 的 ui-background: 节（行内编辑同样生效）：
| 字段 | 类型 | 默认 | 说明 |
|---|---|---|---|
preset |
string | none |
预设 id（none / aurora / sunset / emerald / custom / bing） |
opacity |
number | 1 |
背景不透明度（0.05–1，步进 0.05） |
blur |
number | 0 |
背景模糊半径 px（0–32） |
fill |
cover/contain/tile |
cover |
图片填充方式 |
imagePath |
string | '' |
图片来源型预设（custom/bing）的本地绝对路径；上传或取必应壁纸后自动填写 |
streaks |
boolean | false |
动态流光开关：六条窄亮斜向光带（深色配色加色发光、浅色配色深蓝灰描边）；与粒子互斥，开启其一自动关闭另一 |
particles |
boolean | false |
粒子特效开关（与流光互斥） |
bingMarket |
string | zh-CN |
必应壁纸地区（zh-CN / en-US / en-GB / ja-JP / de-DE），决定壁纸池与标题语言；非法值取图时回退 zh-CN |
bingUhd |
boolean | true |
是否取 4K（UHD）原图；关闭则用接口给出的 1920×1080；该归档缺 4K 时自动回落 |
bingAutoRefresh |
boolean | true |
进入界面时自动对齐「今日」壁纸（命中本地缓存则不重复下载） |
bingTitle |
string | '' |
展示用：当前壁纸标题（随地区语言） |
bingDate |
string | '' |
展示用：当前壁纸日期（YYYY-MM-DD） |
bingCopyright |
string | '' |
展示用：当前壁纸版权信息 |
未知的 preset 值会被安全回退为 none，不会导致设置失效。
工作原理
┌──────────────────────── dsh web 进程 ───────────────────────────────┐
│ Node 半边（lib/index.js） │
│ ├─ 注册 settings 命名空间 ui-background（schemastery schema） │
│ ├─ GET /dsh-ui-background/asset?path=… 图片读取路由 │
│ ├─ POST /dsh-ui-background/upload 图片上传路由 │
│ └─ POST /dsh-ui-background/bing 必应取图路由 │
│ └─ cn.bing.com 归档接口 → 下载图片 → 缓存到 │
│ $DSH_HOME/ui-background/bing/（保留最近 8 张） │
└─────────────────────────────────────────────────────────────────────┘
│ settings.yaml（持久化） │ /plugins/…（client.js）
▼ ▼
┌──────────────────── 浏览器半边（lib/client.js） ──────────────────────┐
│ 设置行（settings.general.item）+ 悬浮按钮（shell.overlay） │
│ 背景层：position:fixed; z-index:-1 铺满视口 │
│ 面板底色：color-mix 45% 同色系半透明底衬（浅/深自动） │
└─────────────────────────────────────────────────────────────────────┘
- 背景层位于 AppFrame 之下、内容之上（负 z-index +
pointer-events: none），不拦截任何交互 - 面板底色以
color-mix降为 45% 同色系半透明底衬：背景透出可见，文字对比度保持 - 上传与读取共用同一扩展名白名单与大小上限，保证能上传的图一定能被读取
- 必应壁纸与上传图片共用同一条渲染通路：浏览器只认
imagePath，图片一律经 asset 路由按已落盘设置授权后读出（因此取图成功后先持久化再发布） - 取图只在两种时机发生：点击「获取今日壁纸/换一张」，或开启自动更新后进入界面时对齐今日；命中本地缓存即零下载
常见问题
升级后原来的「夜空 / 沙丘 / 石板」背景不见了
这三套内置预设已按需求移除，只保留极光 / 落日 / 翡翠。旧的 preset: midnight/sand/slate 设置会被安全回退为无背景（不会报错，也不会卡住界面），在设置里另选一套预设或上传图片即可。
上传返回 413（Payload Too Large）
图片超过 50 MiB 上限。选择更小的图片，或在 src/background-settings.ts 调整 BACKGROUND_ASSET_MAX_BYTES 后重建。
更换背景后文字看不清 / 背景不明显
面板底衬百分比调节（src/client/background.css 中的 color-mix(… 45%, …)，数值越大文字越清晰、背景越弱）。
上传后照片没有铺满 点击「填充方式」的「铺满」（cover）；上传默认即为 cover。
左侧栏 / 右侧面板不显示背景 确认页面已硬刷新；背景层为全屏固定层，面板为半透明底衬，正常应透出背景。
修改 Node 半边后不生效
图片读取 / 上传 / 必应取图路由都属于 Node 半边（lib/index.js），需重启 dsh web。典型症状：点「获取今日壁纸」立即失败，浏览器控制台里该请求是 405（DSH 静态兜底对未注册路径的非 GET 请求回 405）。重启后可先用一条命令自检（期望 400，表示路由在且正确拒绝了非法请求）：
curl -s -o /dev/null -w "%{http_code}" -X POST -H "content-type: application/json" -d "not-json" http://127.0.0.1:3080/dsh-ui-background/bing
点「获取今日壁纸」提示获取失败
按可能性依次排查：① 未重启 dsh web（见上一条）；② 这台机器访问不到 cn.bing.com（代理/防火墙）；③ 必应接口临时异常（会沿用 10 分钟内的归档快照与已缓存图片）。失败不会清空你当前的背景，可稍后点「换一张」重试。
必应壁纸会一直联网吗
不会。只在点击「获取今日壁纸 / 换一张」时请求，以及开启「每日自动更新」后进入界面时对齐今日一次；命中本地缓存（$DSH_HOME/ui-background/bing/，保留最近 8 张）就不下载。取图请求由 Node 半边发起，浏览器不直连必应。
必应壁纸的版权 壁纸版权归原作者与必应所有（设置行会显示标题与日期，接口也返回版权信息）。本插件仅将其作为个人桌面/GUI 背景使用，请勿用于再分发或商业用途。
4K（UHD）开关打开了但还是 1920×1080 必应归档中部分日期没有 4K 版本，此时会自动回落 1080p（不影响使用）。切换地区或 4K 开关时会立即按新设置重取一张。
提示「上传失败：文件格式或大小不符合要求」
扩展名须为 png / jpg / jpeg / gif / webp / avif 且 ≤ 50 MiB。
动态流光/粒子不显示 特效随「背景激活」生效：先选择一个背景（预设或上传图），再开启特效；系统开启「减少动态效果」时特效也会自动停。
特效会耗资源吗
流光/粒子仅在开启且有背景时运行 requestAnimationFrame，粒子数按视口面积自适应（封顶 160）、DPR 封顶 2；全部关闭即零开销。
开发
pnpm install # 安装依赖（@deepseek-ai/* 以 link: 指向本机 DSH 检出）
pnpm run build # tsc 声明 + tsdown 双半边产物
pnpm test # vitest（142 用例：schema/预设/运行时/DOM/组件/特效/必应取图/路由端到端）
pnpm run typecheck
说明：Windows 上 vitest 启动时 vite 会调用
net use探测网络驱动器，若被环境沙箱拦截，请在更宽权限下运行测试。
目录结构见下节。新增 / 修改逻辑后请先 pnpm test 再 pnpm run build。
目录结构
dsh-ui-background/
├── src/
│ ├── index.ts # Node 半边：schema 注册 + asset/upload/bing 路由
│ ├── background-settings.ts # 共享常量/类型（命名空间、边界、白名单）
│ ├── background-schema.ts # schemastery 设置 schema
│ ├── request-body.ts # 带大小上限的请求体读取（上传/必应共用）
│ ├── asset-route.ts # 图片读取路由（按设置授权）
│ ├── upload-route.ts # 图片上传路由（落盘 $DSH_HOME/ui-background/）
│ ├── bing-service.ts # 必应归档解析、下载、缓存与清理（纯逻辑，注入 fetch）
│ ├── bing-route.ts # 必应取图路由（参数校验 + 错误收敛）
│ └── client/
│ ├── index.ts # 浏览器半边 apply：装配 UI 入口与取图回调
│ ├── background-runtime.ts # 状态运行时（写操作/持久化/快照）
│ ├── background-presenter.ts # 背景层 DOM 呈现器
│ ├── background-store.ts # UI 共享 store
│ ├── background.css # 全局背景样式（浅/深底衬）
│ ├── BackgroundRow.tsx # 设置「背景」行
│ ├── BingControls.tsx # 必应壁纸区块（取图按钮/地区/4K/自动更新）
│ ├── BackgroundQuickToggle.tsx # 悬浮一键切换按钮
│ ├── bing.ts # 客户端取图封装（请求 + 响应校验）
│ ├── upload.ts # 客户端上传与图片尺寸读取
│ ├── suggest-fill.ts # 比例格式化（formatAspect）
│ ├── presets.ts # 内置预设表与循环切换
│ ├── locales.ts # 中英文案
│ └── styles.ts # 全局样式生命周期
├── tests/ # vitest 用例（含路由端到端；support/ 为共用夹具）
├── cordis.patch.yml # 接入 overlay 示例
├── tsdown.config.ts # 自包含构建配置（Node + 浏览器双产物）
└── package.json
支持与打赏
如果本项目对你有帮助，欢迎扫码支持（自愿，感谢你的鼓励）：
许可证
本项目为独立开源插件，与 DeepSeek Harness（Apache-2.0 兼容生态）无关的第三方贡献；使用 DeepSeek Harness 请遵循其自身许可证。
No comments yet. Be the first to write one.