dsh-ui-background
一键切换 DSH Web 背景：渐变预设（极光/日落/翡翠绿）、本地图片上传、Bing 每日壁纸（4K/UHD、地区、每日自动更新）、不透明度/模糊/填充控制、光 streak 和粒子效果。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:it-kxw/dsh-ui-background#9625a25f281e9b30bbd2ad2e39dcd0b01f549947Ui Background 以 dsh-ui-background 发布，当前版本为 0.5.1。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
点击下方 Badge 复制 Markdown，粘贴到 README 即可。
验证 package.json 声明的 GitHub 仓库，即可管理这个公开页面。认领后，Hub 会优先安排当前版本的安全扫描，并在通过后公开展示结果。
认领这个 Plugin →为 DeepSeek Harness Web GUI（dsh web）提供的一键背景切换插件：内置渐变预设、本地图片上传与路径引用、必应每日壁纸，支持不透明度、模糊、填充方式调节；浅色/深色配色自动适配，背景随手持久化到设置文档。
插件以独立仓库形式自包含构建（不修改 DSH 内核），通过 Web profile 的 patch 层接入运行中的实例即可使用。
$DSH_HOME/ui-background/）cover 铺满全屏$DSH_HOME/settings.yaml，刷新后保持| 位置 | 内容 |
|---|---|
| 设置 → 通用 → 「背景」行 | 按 来源（预设卡片 / 上传图片 / 必应壁纸）、显示（不透明度、模糊、填充方式）、特效（关闭 / 动态流光 / 粒子效果）三组排列；底部为清除背景与比例提示 |
| 界面右下角悬浮胶囊 | 单击循环切换背景（显示当前背景名） |
dsh web 实例（dsh CLI 或从源码运行）本插件为 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 静态兜底里等同"未注册路由"），界面显示「获取必应壁纸失败」。
设置在 $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% 同色系半透明底衬（浅/深自动） │
└─────────────────────────────────────────────────────────────────────┘
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 请遵循其自身许可证。