界面外观定制 cyk1009/dsh-plugin-custom-ui

dsh-plugin-custom-ui

为 DeepSeek Harness（DSH）Web GUI 提供可持久化的外观定制：

- 在「设置 → 外观定制」里选择纯色、渐变或图片作为全窗口背景；
- 调整背景遮罩、模糊、界面表面不透明度；
- 调整强调色和全局圆角；
- 注入自定义 CSS；
- 保存后立即生效，刷新/重启后保持，可一键停用或恢复默认。

这是一个独立社区插件，不是 DeepSeek 官方产品。当前适配 DSH 0.2.1-rc.2；它依赖的 settings/slot/theme 接口属于客户端插件面，升级 DSH 时请先跑测试并在真实 GUI 中回归。

功能

- 背景：无、纯色、CSS 渐变、图片链接、浏览器本地图片。
- 可读性：遮罩颜色/浓度、背景模糊、单层表面不透明度。
- 界面：强调色（链接、选中态、焦点环）、全局圆角倍率。
- 高级：全局自定义 CSS。
- 持久化：除本地图片外写入 DSH profile settings，跨浏览器/重启保留。
- 安全默认：安装后保持无视觉变化；本地图片不上传 Host；所有样式/覆盖可完整撤回。

安装

要求：DSH 0.2.1-rc.2 左右、Node.js 20+、已有一个可用的 web profile。

方式一：手动链接（推荐本地开发）

set -eu
git clone https://github.com/cyk1009/dsh-plugin-custom-ui.git
cd dsh-plugin-custom-ui

PLUGIN_DIR="$(pwd)"
DSH_HOME="${DSH_HOME:-$HOME/.dsh}"
PROFILE="$DSH_HOME/profiles/web"
PATCH="$PROFILE/cordis.patch.yml"

test -f "$PATCH" || { echo "profile patch not found: $PATCH" >&2; exit 1; }
mkdir -p "$PROFILE/node_modules"
ln -sfn "$PLUGIN_DIR" "$PROFILE/node_modules/dsh-plugin-custom-ui"

if grep -q 'id: custom-ui' "$PATCH"; then
echo 'custom-ui row already present'
else
cp "$PATCH" "$PATCH.bak-custom-ui-$(date +%Y%m%d-%H%M%S)"
cat >> "$PATCH" <<'YAML'

custom-ui: wallpaper, surfaces, accent, radius, custom CSS (settings section).
- insert:
- id: custom-ui
name: 'dsh-plugin-custom-ui'
YAML
fi

行 id 必须是 custom-ui：设置页和客户端运行时都按这个 id 读写 Host settings 命名空间。

修改 profile patch 后，已启用的 dsh-hmr 会重新组合配置；浏览器页面会通过 Client HMR 收到新的插件模块。若页面没有自动更新，刷新一次浏览器；仍不生效时再重启 dsh web。

方式二：插件管理器

在 Web GUI 的 插件 → 添加插件 → 安装第三方插件 中填入仓库地址：

https://github.com/cyk1009/dsh-plugin-custom-ui

插件包声明了 dsh.bundle.patch，管理器会按其中的 custom-ui 行安装。它与方式一手动插入二选一，不要重复添加同一个行 id。

卸载

删除 cordis.patch.yml 里的 insert 段和 node_modules/dsh-plugin-custom-ui 符号链接，刷新页面即可。浏览器里的本地图片可以留在原处，也可以在设置页清除。

使用

打开 设置 → 外观定制。页面分为：

| 区块 | 内容 |
| 启用 | 总开关。关闭后立即恢复 DSH 默认外观，已保存字段保留。 |
| 预览 | 16:9 预览，模拟壁纸、遮罩、模糊和两层半透明界面表面。 |
| 背景 | 无 / 纯色 / 渐变 / 图片；图片支持链接或本地文件；可设置遮罩、模糊、适配方式。 |
| 界面 | 表面不透明度、强调色、圆角缩放。 |
| 高级 | 全局自定义 CSS。 |

修改后点「保存」才会写入 Host settings 并应用到整个页面；「恢复默认」会清除所有用户层覆盖和浏览器本地图片。

字段

| 字段 | 默认 | 说明 |
| enabled | true | 总开关 |
| backgroundKind | none | none / color / gradient / image |
| solidColor | #0b1020 | 纯色背景 |
| backgroundGradient | 深海渐变 | 单个 CSS gradient 值 |
| imageSource | url | url / local |
| imageUrl | 空 | http(s)、data:image 或站内绝对路径 |
| imageFit | cover | cover / contain / repeat |
| overlayColor | #000000 | 壁纸遮罩颜色 |
| overlayOpacity | 0.25 | 遮罩浓度，0–0.9 |
| backgroundBlur | 0 | 背景模糊，0–30 px |
| surfaceOpacity | 0.55 | 单层表面 alpha，0.3–1；越低背景越明显 |
| accentColor | 空 | 强调色；空表示 DSH 默认 |
| radiusScale | 1 | 圆角倍率，0.5–2 |
| customCss | 空 | 全局 CSS，≤ 20000 字符 |

字段也可以通过 profile patch 的 config: 直接编辑，例如：

- id: custom-ui
name: 'dsh-plugin-custom-ui'
config:
enabled: true
backgroundKind: image
imageUrl: 'https://example.com/wallpaper.jpg'
overlayOpacity: 0.35
surfaceOpacity: 0.5

手改后保存文件即可；Host HMR 会重新组合。非法颜色/URL/渐变会在运行时容错回退，不会让插件崩溃。

本地图片

「图片 → 本地图片」支持 PNG、JPEG、WebP、GIF、AVIF，单文件 ≤ 20 MB。插件会在浏览器内按最长边 2560 → 1920 → 1600 逐步缩放并编码（优先 WebP，回退 JPEG），最终 data URL 需 ≤ 4 MB。

- 图片只写入当前浏览器的 localStorage（键 dsh-plugin-custom-ui:local-image:v1），不会上传到 DSH Host。
- 图片按浏览器/源隔离：换浏览器、换端口或清理站点数据后需要重新选择；此时会回退到 imageUrl，或保持无背景。
- 其他设置仍保存在 Host settings 中，连接同一 DSH 的浏览器共享。只有本地图片是浏览器本地的。

自定义 CSS

自定义 CSS 通过 的 textContent 注入，追加在内置生成样式之后，因此可以覆盖大部分视觉规则。它是全局的，也可以加载外部资源；错误规则可能破坏布局。

- 留空表示不注入。
- 清除方式：把文本框清空后保存，或「恢复默认」。
- 常用场景：改字体间距、隐藏某个元素、微调某个 token、添加自己的 body::before 层。

例如：

body {
letter-spacing: 0.01em;
}

/* 让 composer 更透明一点 /
[data-composer-seat] {
--dsw-specific-input-major: rgba(255, 255, 255, 0.6);
}

实现方式

- Host 半侧（lib/index.js）：声明 14 个 .volatile() 字段的 schemastery Config，让 Host settings 服务暴露 custom-ui 命名空间；调用 settings.configure({ auto: false }) 关闭自动生成的配置页。
- Client 运行时（lib/client.js）：订阅 ctx.configForms.get("custom-ui")；壁纸写入插件拥有的 的 body::before，界面半透明/强调色/圆角通过 ctx.theme.overrideTokens("dsh-plugin-custom-ui", ...) 以 { light, dark } 成对覆盖。
- 不覆盖菜单、卡片、composer、代码块：只覆盖 --dsw-alias-bg-base 和 --dsw-specific-sidebar-fill，让主画布和侧栏透出壁纸，同时保持可读性。
- 清理：所有样式、body 属性、token 覆盖、事件监听都挂在 ctx.effect 上；停用/卸载/HMR 时会完整撤回。

为什么表面要叠两层

Web 壳的 frame 和 chat/sidebar 各有一层背景。插件对同一 token 给出 alpha 值后，两层会叠加，实际不透明度高于滑杆显示的单层值。设置页预览按两层模拟，默认 surfaceOpacity=0.55 对应的实际观感约为 80%。把滑杆拉到 100% 会完全遮住背景。

兼容性与已知限制

- 版本绑定：在 DSH 0.2.1-rc.2 上开发/测试；configForms、settings.section、theme.overrideTokens 等接口变更时需要适配。
- 首屏闪烁：配置通过 settings RPC 返回后才应用壁纸，刷新时可能短暂看到默认背景。
- 第三方主题：表面色使用内置浅/深色值；第三方主题下若开启半透明表面，会覆盖其 base/sidebar 颜色。把表面不透明度设为 100% 可保留主题原色。
- body::before 层级：依赖当前 Web 壳的 body { isolation: isolate }。若未来移除，壁纸层可能落到根画布之后，需要改为真实 DOM 层。
- 设置共享：除本地图片外，外观设置连接同一 DSH 的浏览器共享。
- 非目标：按会话背景、视频壁纸、Host 本地文件路由、配置导入导出、独立主题市场。

开发

npm test # node --test
npm run check # node --check lib/.js

测试覆盖：

- bundle 注册、导出、默认值与 lib/defaults.js 同步；
- normalizeSettings 的默认值、钳制、非法颜色/URL/渐变回退；
- validateImageUrl、isValidGradient；
- buildRuntimeCss 的壁纸/遮罩/模糊/自定义 CSS 输出；
- buildTokenOverrides 的 light/dark 成对覆盖、accent/radius 独立生效；
- buildSettingsOps 的 base-aware set/unset 与“只写已编辑字段”；
- validateSettings 的错误/警告；
- zh/en 字典键一致；
- apply 用 mock ctx 验证设置页注册、样式注入、token 覆盖与 dispose 清理；
- 设置页 ready 分支的渲染冒烟（含图片链接控件）；
- package/patch/node --check。
GitHub Actions 在 Node 20/22/24 上跑同一套测试。

离线验证 Host schema

不碰真实 profile，复制一份到临时 DSH_HOME，加入 custom-ui 行后再 dump schema：

CHECK="$(mktemp -d)"
mkdir -p "$CHECK/profiles"
cp -a "${DSH_HOME:-$HOME/.dsh}/profiles/web" "$CHECK/profiles/web"
ln -sfn "$PWD" "$CHECK/profiles/web/node_modules/dsh-plugin-custom-ui"

cat >> "$CHECK/profiles/web/cordis.patch.yml" <<'YAML'

- insert:
- id: custom-ui
name: 'dsh-plugin-custom-ui'
YAML

DSH_HOME="$CHECK" dsh --profile web --dump-config-schema
没有 dsh 命令时：npx @deepseek-ai/dsh --profile web --dump-config-schema

确认输出里出现 custom-ui 行、14 个字段和默认值，且没有针对该行的 diagnostics。

在线验证

DSH_WEB_URL="${DSH_WEB_URL:-http://127.0.0.1:3080}"
curl -sN --max-time 3 "$DSH_WEB_URL/plugins/events" | grep -o 'dsh-plugin-custom-ui[^"]*' | head

从 graph 里取该插件的 url，用 curl 拉取，返回内容应以 window.__ModuleLoader__.load({ id: "dsh-plugin-custom-ui" 开头。

安全与隐私

- 本地图片只存在浏览器 localStorage，不经过 Host 网络。
- 外观设置写入 DSH profile 的 settings 文档；自定义 CSS 是用户自己提供的全局 CSS，可能加载外部资源。
- 发现安全问题请按 SECURITY.md 私下报告，不要开公开 issue。

贡献

欢迎 issue / PR。开始前请读 CONTRIBUTING.md；改动用户可见行为时请同步更新中英文 README。

许可

MIT。独立社区项目，与 DeepSeek 官方无关。

文件

| 文件 | 作用 |
| lib/index.js | Host 入口、Config schema、关闭自动配置页 |
| lib/defaults.js | 默认值与枚举，供 Host schema 和测试使用 |
| lib/client.js | 懒加载 CJS 客户端 bundle：运行时、设置页、纯函数 |
| cordis.patch.yml | bundle 形态的默认插入行 |
| test/client.test.mjs | bundle/运行时/设置的单元与接线测试 |
| test/package.test.mjs | package/patch/语法检查 |
| .github/workflows/test.yml | GitHub Actions 测试矩阵 |