DeepSeek Harness (DSH) 采用“一切皆插件”的架构理念。在使用 Web GUI 或桌面端（Electron）进行长时间工作或开发时，默认的界面背景往往较为单调。dsh-bg-plugin 插件允许开发者通过远程 URL 或本地文件为 DSH 添加自定义背景图片或视频，同时通过半透明遮罩层和豁免机制，确保设置面板保持默认外观，不影响操作体验。
核心功能¶
- 媒体源支持：支持远程 URL（图片/视频）与本地文件（图片/视频）作为背景。
- 视觉调节：支持背景清晰度调节（0–100%），通过覆盖 DSH 主题 Token 实现半透明效果。
- 设置面板豁免：设置面板（
[role="dialog"][aria-modal="true"]）内部强制恢复默认外观，不受背景影响。 - 安装形态：提供静态安装版（推荐，重启后常驻）与动态插件版（会话级，重启后消失）。
- 多平台支持：支持 DSH 网页端与桌面端，但两端需分别安装。
- 框选展示区域：仅针对图片，支持在预览图上框选展示区域，支持拖动、缩放，比例锁定。
- 悬浮球支持：提供悬浮球面板背景补丁，支持与主应用背景双向同步。
安装与启用¶
静态安装是推荐的方式。通过 dsh 命令将插件目录链接到 Web profile。
- 确保插件源码目录在本地。
- 执行安装命令，将本目录绝对路径作为参数传入：
dsh plugin --profile web add link:<本目录绝对路径>
- 重启 DSH（运行
dsh web）以加载插件。
若需卸载：
dsh plugin --profile web remove dsh-bg-plugin
桌面端（Electron）支持¶
桌面端与网页端是两个独立的 DSH 实例，Profile 不同，因此需分别安装。
- Profile：
$DSH_HOME/profiles/desktop - CLI：桌面端自带 CLI 位于
<安装目录>\resources\runtime\cli\bin\dsh.cmd
桌面端安装示例（Windows）：
& "D:\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd" plugin --profile desktop add link:D:\DSH插件\dsh-bg-plugin
安装后需重启桌面端应用。
状态持久化¶
静态安装模式下，所有配置（媒体源、框选区域、清晰度）自动保存到状态文件：
$DSH_HOME/.dsh-bg-state.json
刷新页面或重启 DSH 后，插件会自动恢复上次的设置并重应用背景。
悬浮球面板背景补丁¶
悬浮球展开面板的背景渲染由其自身代码控制。本插件通过写入补丁的方式，为面板注入背景层。
- 补丁机制：通过浏览器弹窗确认后，插件会将原文件备份至
$DSH_HOME/.dsh-bg-orb-backup/<时间戳>/。 - 修改文件：覆盖
dist/helper/assets/floating.html（放宽 CSP）和dist/helper/lib/main.js（注入背景控制器）。 - 渲染方式：背景层使用
z-index: -1垫在面板内容之下，并设置isolation: isolate建立层叠上下文，确保背景随面板展开/收起动画移动，且被裁剪为面板形状。 - 功能：支持悬浮球背景设置、与主应用背景双向同步、比例锁定框选。
自动更新¶
插件内置自动更新功能，默认开启。
- 检查：打开设置页底部会检查 GitHub
main分支版本。 - 下载与覆盖：发现新版本会自动下载并覆盖插件文件（包括
package.json、lib/等）。 - 备份：覆盖前会将现有文件备份到
$DSH_HOME/.dsh-bg-update-backup/<时间戳>/。 - 手动操作：支持手动点击“检查更新”或“立即更新”。
注意事项¶
- 重启生效：无论是静态安装还是动态安装，修改配置或安装后通常需要重启 DSH 才能生效。
- 动态版限制：动态插件版为会话级，重启 DSH 后配置会消失。
- 文件权限：悬浮球补丁涉及修改 DSH 安装目录下的文件，请确保有写入权限。
- 路径限制：
fs沙箱仅拦截写入，读取任意目录均可；若无法使用系统文件夹选择器，可直接粘贴路径。
