dsh-ui-customizer · 界面定制

DeepSeek Harness Web GUI 的界面定制插件：在侧边栏设置菜单的正上方添加一个「界面定制」菜单，点击打开配置弹窗，可设置整个 Web 界面的背景图片（支持网络 URL 或本地图片文件）并调节图片透明度。背景图片铺满整个界面、显示在所有内容之下，形成壁纸效果；设置保存在浏览器本地（localStorage），刷新页面后依然保留。

纯展示层客户端插件：不注入服务、不发 Cordis 事件、不触达模型请求。插件卸载 / 热切换时，所有 DOM/CSS 写入（AppFrame 背景透明化、overlay 层级）都会被 effect 销毁器精确还原。

特性

• 侧边栏「界面定制」菜单（位于设置上方，收起时显示圆形图标）
• 配置弹窗：启用开关、图片地址输入、本地图片选择（转为 data URL 内嵌）
• 交互式裁剪预览：滚轮或按住中键上下拖动 = 缩放（光标锚定），左键拖动 = 平移； 「复位」按钮一键恢复整图；只有预览中框选出来的区域会作为背景（以自然像素 的裁剪矩形保存，可精确复现）
• 最近使用：自动保留最近 5 张用过的背景图片，点击缩略图即可直接切换（当前使用的图片高亮）
• 拉伸方式：铺满（cover，默认）/ 适应（contain）/ 平铺（tile）/ 拉伸（fill）； 裁剪生效时平铺回退为铺满（平铺子区域需要重新裁图，暂不支持）
• 模糊（0–24px）与暗化叠加（0–90%）滑杆，让壁纸更柔和或让文字更易读
• 透明度/模糊/暗化滑杆实时生效（无防抖延迟，滑块跟手）；localStorage 写入防抖 合并，不拖累拖动性能
• 背景层挂在布局的 shell.overlay 槽上，z-index: -1 + 透明化 AppFrame 背景，图片真正位于内容之下
• 设置保存在浏览器 localStorage（含多标签页同步），刷新页面后保留
• 中英双语

为什么不用宿主设置文档（settings.yaml）

宿主设置协议目前只把硬编码白名单内的命名空间暴露给浏览器 （dsh-host-apiproxy 的 WEB_SETTINGS_NAMESPACES，含 ui-theme 等官方 命名空间）。第三方插件的命名空间即使注册成功，浏览器也读不到、写不进 （settings-not-exposed），因此本插件的持久化改用浏览器本地 localStorage（键 dsh-ui-customizer:v1），零宿主依赖、热加载即生效。 宿主端仍保留 ui-customizer 命名空间注册（见 lib/index.js），若 DSH 未来放开注册即暴露，可无缝切回 ctx.settingsScope。

本地图片选择上限 10 MB。注意：data URL 会膨胀约 4/3，且 localStorage 单源配额一般只有 5–10 MB，因此接近上限的大图可能无法在 刷新后保留（控制台会提示，界面内仍可临时使用）；想要稳定持久化请用 网络图片地址或较小尺寸的图片。

安装

在 dsh 安装目录（能运行 dsh 的地方）执行：

dsh plugin --profile web add <本插件路径>
# 例如：
dsh plugin --profile web add D:\Work\工作目录\dsh-ui-customizer

然后重启 dsh web（加载即生效；当前运行中的实例不会热加载新 roster）。

热激活（无需重启）：运行中的 dsh web 会热监听 profile 的 cordis.patch.yml，往该文件追加本插件的 insert 行即可让运行中的实例 立即加载插件（刷新页面即生效）：

- insert:
    - id: ui-customizer
      name: '@dsh-external/dsh-client-ui-customizer'

这是 maid-atelier / whale-girl 安装后无需重启的原因；本插件的 cordis.patch.yml（bundle patch）在下次启动时也会自动插入同一行。

说明：本插件不依赖任何 npm 包（schemastery 已 vendor 在 lib/vendor/）， 安装时不需要网络；link: 方式安装后改动源码即同步生效，无需重新构建。

若机器上没有 pnpm（dsh plugin 依赖它），可手工安装：把插件目录 junction 到 $DSH_HOME/profiles/web/node_modules/@dsh-external/dsh-client-ui-customizer， 并在该 profile 的 package.json 中登记依赖与 dsh.profile.bundles 条目。

与其它侧栏插件的共存

「界面定制」占用的 sidebar.footer.action 是列表槽位，可与其它条目共存； 官方 cordis 面板（存在动态插件时才显示）也注册在那里。两者同时可见时会在 侧栏底部并排显示，属预期行为。

卸载

dsh plugin --profile web remove @dsh-external/dsh-client-ui-customizer

结构与构建

lib/
  index.js       宿主(Node)半部：注册 ui-customizer 设置命名空间（当前为休眠态，见上文说明）
  client.js      浏览器半部：loader 格式 bundle（侧栏菜单 + 配置弹窗 + 背景图层 + localStorage 持久化）
  vendor/        内置的 schemastery / cosmokit（MIT，见文件头注释），使本包零依赖
cordis.patch.yml 把本插件的 dsh.client 行插入 web 插件 roster

lib/client.js 是手写的 loader 格式 bundle（与官方 tsdown 产物同构： window.__ModuleLoader__.load({id, factory})），无需构建步骤；样式以内联 <style data-plugin> 注入，符合插件 CSS 约定（HMR 卸载时自动移除）。

冒烟测试：

node tests/smoke-client.mjs   # 验证 bundle 注册、apply 装配与槽位注册形状

许可

MIT。