dsh-background-plugin
为 DeepSeek Harness（DSH Desktop / Web）提供的「背景图片」插件：把任意图片或内置渐变设为应用背景，并调节透明度、适应方式、模糊与暗化。背景覆盖主区域和左侧栏，状态持久化在宿主，重启/换端口都不丢。
A background plugin for the DeepSeek Harness Web UI: use an image or a built-in gradient as the app background, with opacity, fit, blur and dim controls. The state lives on the Host, so it survives restarts.
设置页 / Settings
功能 / Features
- 6 个内置渐变：晨曦、深海、暮色、极光、暗夜、粉黛。
- 动态背景：GIF / 动态 WebP / APNG 动图，以及 ≤15 秒的 MP4/WebM 短视频（≤8MB）。页面隐藏时自动暂停，
prefers-reduced-motion 时只显示静帧。
- 背景库：上传或导入的背景会自动收藏（最多 24 个，带缩略图），一点即切换，可单个移除。
- 本地图片上传：静态图自动压缩到长边 ≤1920、大于 800KB 的 PNG 转 JPEG；动图与视频按原字节保存（避免重编码把动画压成静帧）。
- 网址导入：导入前用图片探测校验，失败会提示而不是静默。
- 透明度 / 模糊 / 暗化 / 适应方式（铺满·完整显示）。
- 宿主持久化：状态保存在
<DSH_HOME>/storages/dsh-background.json，图片二进制保存在宿主附件库；重启、换端口、多窗口都不丢。
- Agent 工具：模型可以调用
background_set 直接换背景（set / clear / status）。
- 中英文文案：跟随 Harness 的语言设置。
- 无第三方运行时依赖：
react 由 Harness 客户端提供；宿主只用 Node 内置模块。
安装 / Install
前提：DSH Desktop 或 dsh CLI，profile 位于 %USERPROFILE%\.dsh\profiles\<name>（默认 desktop）。
安装后需要重启 DSH Desktop（或重启 dsh 进程）让宿主半部分加载。
方式 1：让 Agent 安装（推荐）
在 DSH 里对 Agent 说：
帮我安装 dsh-background-plugin 这个 bundle
Agent 会调用 plugin_manager install_bundle，自动完成依赖安装与 bundle 注册。
方式 2：插件管理页
设置 → 插件 / Plugins → 添加（安装 bundle），选择本包或输入包名。安装成功后启用并重启。
方式 3：命令行（CLI）
# 在 profile 里安装依赖（pnpm 透传）
dsh plugin --profile desktop add <本包路径或包名>
随后把包名加入该 profile package.json 的 dsh.profile.bundles，再执行 pnpm install，重启 DSH。
方式 4：一键脚本（Windows / macOS / Linux）
克隆仓库后运行：
# Windows
powershell -ExecutionPolicy Bypass -File .\install.ps1 -Profile desktop
# macOS / Linux
bash ./install.sh
脚本会：把包复制到 <DSH_HOME>\plugins-src\dsh-background-plugin，把依赖与 bundle 写入 profile 清单，执行 pnpm install，然后提示重启。
从 Git 直接安装（pnpm 支持 git 依赖）
dsh plugin --profile desktop add github:<your-gh-user>/dsh-background-plugin
同样需要把包名加入 dsh.profile.bundles 并重启。
配置 / Configuration
bundle 的行配置在 cordis.patch.yml 的 config 里，可在 profile 补丁层覆盖：
- insert:
- id: background-plugin
name: dsh-background-plugin
config:
defaultPreset: '' # 首次运行使用的预设名（如 深海）
defaultOpacity: 0.6 # 0..1
fit: cover # cover | contain
blur: 0 # 0..40
dim: 0 # 0..0.9
这些是首次运行的默认值；用户之后在设置页里改的值优先。
使用 / Usage
设置 → 背景图片：
- 点任一内置渐变，或「选择图片 / 动图 / 视频」，或粘贴图片/视频网址后「导入」。
- 用滑块调透明度 / 模糊 / 暗化，用「适应方式」切换铺满与完整显示。
- 「移除背景」清除。
动图与视频的限制：单文件 ≤8MB，视频 ≤15 秒，推荐 MP4(H.264) / WebM。
上传或导入过的背景会出现在「背景库」里，点缩略图即可换回，右上角 × 可移除。
也可以直接对 Agent 说：「把背景换成暮色，透明度 40%」。
结构 / Layout
package.json # dsh.bundle + dsh.client 声明
cordis.patch.yml # 插入 background-plugin 行
index.js # 宿主：状态持久化 + /api/background/* + background_set 工具
client.js # 浏览器：设置页 + html::before 背景层
locale/{zh,en}.json # 插件显示名与描述
icon.svg # 插件图标
HTTP API（宿主）
| 方法 | 路径 | 说明 |
|---|
| GET | /api/background/state | 读取当前状态与预设 |
| PUT | /api/background/state | 修改 opacity/fit/blur/dim/preset/url/clear |
| POST | /api/background/image | 上传 { dataUrl }，存入附件库 |
| GET | /api/background/image | 读取当前背景图 |
| POST | /api/background/media | 上传动图/视频 { dataUrl }，逐字节保存（≤8MB） |
| GET | /api/background/media | 读取动图/视频（支持 Range，视频可正常循环/seek） |
| POST | /api/background/clear | 清除背景 |
发布 / Publish
发布到 npm（任选其一）：
npm publish --access public
或使用 GitHub Actions：在仓库 Secrets 里配置 NPM_TOKEN（npm 发布令牌），然后推 tag：
git tag v1.0.0
git push origin v1.0.0
.github/workflows/publish.yml 会在 tag 推送时自动发布。
开发 / Development
纯 JavaScript，无构建步骤：
node --check index.js
node --check client.js
安装到本地 profile（推荐用 Agent 的 plugin_manager，或运行 install.ps1），重启后即可在设置里看到。
兼容性 / Compatibility
- 需要较新的 DSH（插件系统含
plugin_manager、dsh.client 与 settings.section slot 的版本）。
- 旧的
dsh-client-ui-slots / settingsScope 时代不适用。
License
MIT
