z827439974/dsh-background-plugin

dsh-plugin-webui-bg

一个 DeepSeek Harness (DSH) WebUI
插件：选择一张本地图片作为 WebUI 背景，并叠加一层与当前主题（浅色 / 深色）匹配的半透明
遮罩，使图片永远不会干扰 UI 的可读性。

功能特性

- 在 设置 → 通用 中新增一行 背景图片：
- 选择一张本地图片（浏览器文件选择器），或使用内置的 示例
图片立即试用
- 图片在持久化之前会被缩小（最长边 1920px）并重新编码（WebP，JPEG
作为回退）
- 实时预览缩略图
- 启用 / 禁用开关
- 遮罩不透明度滑块（50%–100%，默认 75%）
- 背景模糊滑块（0–40px，默认 0）
- 一键 移除背景
- 遮罩颜色使用主题令牌 --dsw-alias-bg-base，因此会自动跟随
浅色/深色主题。
- 两个背景层都是 pointer-events: none 的固定层——它们永远不会
阻挡交互。
- 隐私：图片永远不会离开你的浏览器。它存储在
localStorage（键名 dsh.webui-bg）中；不会发起任何网络请求。

工作原理

DSH 布局框架及其占满视口的子元素（body、侧边栏列、
会话根节点……）带有各自的不透明背景，否则会绘制
覆盖在背景层之上。该插件：

1. 向 document.body 追加两个固定层：图片在后，
主题色遮罩在前（两者均为 pointer-events: none）。
2. 中和它在布局框架下找到的每一个大型完全
不透明的“表面”容器（基于尺寸启发式，不依赖哈希类名），使这些
层能够透出。卡片、按钮和气泡保留各自的背景
以保证可读性。
3. 跳过类似覆盖层的子树（模态框、弹出框、工具提示——任何
fixed/absolute 或具有正 z-index 的元素），因此对话框保持不透明。
4. 使用 MutationObserver 监视 DOM，并在重新挂载时重新中和；
当背景被禁用时恢复原始背景。

持久化刻意采用浏览器本地存储：DSH 的 API 网关只向配置客户端
暴露白名单中的设置命名空间，因此第三方
命名空间会在传输层被拒绝。

兼容性

⚠️ 此插件针对 DSH 内部 API，这些 API 可能在不同
版本之间发生变化。它是在 @deepseek-ai/dsh 0.1.0-rc.6 上构建并验证的。

对 DSH 内部实现的依赖：

| 接口 | 所依赖的内容 |
| --- | --- |
| 客户端 bundle 格式 | window.__ModuleLoader__.load、package.json 中的 dsh.client |
| 设置行 | settings.general.item 插槽以及 slots / locale 服务 |
| 主题遮罩 | --dsw-alias-bg-base CSS 令牌和 body[data-ds-dark-theme] |
| 表面中和 | 布局框架结构（[data-shell-overlay] 父级）以及尺寸/不透明度启发式 |

如果 DSH 更新改变了其中任何一项，该插件可能需要调整。

安装

需要在目标机器上有一个 DSH web profile（$DSH_HOME/profiles/web，
例如 \.dsh\profiles\web；如果它尚不存在，用 dsh web 启动一次）。无需构建步骤，无运行时依赖。

一键安装器（推荐）

最简单：双击 scripts\install.cmd —— 它用 -ExecutionPolicy Bypass 包装了 PowerShell 安装器，因此即使在禁止运行 .ps1 脚本的环境中也能工作。

或者直接从插件目录运行 PowerShell 安装器：

powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1

如果你在直接运行 .\install.ps1 时遇到 "…禁止运行脚本"（执行策略） 错误，
可以使用上面的 .cmd 包装器、传入 -ExecutionPolicy Bypass，
或者为你的用户一次性允许本地脚本：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

安装器会将包链接到配置文件的模块目录中（junction，回退为复制），并将加载器插入行追加到 cordis.patch.yml（幂等 —— 可安全重复运行）。使用 -ProfileName 和 -DshHome 自定义配置文件 / DSH 主目录。

通过 pnpm

从你的插件检出目录
dsh plugin --profile web add "file:"

手动（不使用 pnpm）

1. 将包链接到配置文件的模块目录中（一个 junction，无需链接依赖 —— node 部分为空操作）：

New-Item -ItemType Junction -Path "$env:USERPROFILE\.dsh\profiles\node_modules\dsh-plugin-webui-bg" -Target ""

2. 向 profiles\web\cordis.patch.yml 追加一个插入行（补丁层会热重载，无需重启进程）：

- insert:
- id: webui-bg
name: dsh-plugin-webui-bg

安装后（所有方法）

1. 硬刷新浏览器页面（Ctrl+Shift+R）。
2. 打开 设置 → 通用 —— 背景图片 行会出现在那里；选择一张本地图片（或内置的 示例）。
3. 持久化是按浏览器进行的（localStorage），因此新机器在未选择背景之前不会存储背景。

卸载

- 从 cordis.patch.yml 中移除 insert 行。
- 删除 profiles\node_modules\dsh-plugin-webui-bg 链接。
- 可选：在浏览器控制台运行 localStorage.removeItem("dsh.webui-bg") 以清除存储的图片。

包结构

| 文件 | 用途 |
| --- | --- |
| lib/index.js | 宿主部分：一个空操作的 apply，以便加载器挂载入口并提供客户端 bundle。 |
| lib/client.js | 浏览器部分（dsh.client.platform: "web" 客户端 bundle）：背景层、设置行、localStorage 持久化。 |
| package.json | 插件清单：dsh.client 声明、./client 导出。 |

lib/client.js 是一个手写的 bundle，采用 DSH 的 lazy-CJS 客户端格式（无需构建步骤）—— 如果你重构它，请保持与格式同步。

许可证

MIT —— 参见 LICENSE。