dsh-ui-appearance

dsh plugin --profile web add dsh-ui-appearance

dsh-ui-appearance

[English](README.en.md) · 中文

DeepSeek Harness 生态中首个支持多维度 UI 参数深度自定义的外观插件 —— 不局限于固定预设，支持面板/输入框/代码块透明度微调、毛玻璃强度、壁纸/视频背景及色板智能衍生；WebUI 与 DSH Desktop 均可使用。







零核心代码改动:完全通过官方插件机制(ctx.theme.overrideTokens() 主题扩展点与 settings.general.item 插槽)实现;卸载后界面完整恢复默认。

界面

设置面板 · 壁纸 + 毛玻璃效果

 · 

在 DSH Desktop(桌面客户端)中同样开箱即用,以下为实拍:

高级模式(桌面原生布局与材质) · 兼容模式(上游默认 Web client)

 · 

官方桌面端新版实拍(社区版截图保留在上方):

官方桌面端(新版高级模式)


效果图中的壁纸素材 © MadYY([原图](docs/wallpaper-madYY.png)),仅作演示;用户上传自己的图片即可。

功能

深浅双模式独立外观 —— 设置面板顶部提供「浅色模式 / 深色模式」独立分段卡，分别配置双模式下的 6 种颜色角色与预设，实时跟随宿主状态与系统 prefers-color-scheme 自适应切换。接入 WCAG 2.1 动态反解算法（次级文字 $\ge 7:1$、三级说明字 $\ge 4.5:1$），彻底杜绝浅色模式“白底淡字”或深色模式图标隐形。

主题颜色 —— 6 个核心颜色角色：主色、背景色、面板色、输入框色、文字色、边框色。每个角色支持原生取色器与 HEX 精确输入，全局色彩严格遵循所见即所得（不隐式篡改你手选的文字色）；主操作按钮、文字选区高亮、键盘焦点环跟随主色，用户消息气泡跟随面板色，并在局部实心/半透明表面自动做可读性对比度兜底。

壁纸与视频背景（最高 200MB） —— 支持上传或拖拽图片（JPG / PNG / WebP / GIF），或粘贴 URL 一键加载（自动按扩展名分流，支持 CORS 友好直链）。原画质通过 IndexedDB Blob 存储（零额外堆内存复制，不占 localStorage 配额；超 4096px 等比缩边，限内 GIF 保留动效）。上传时自动采样平均亮度并智能提取主色衍生周边色阶。支持原生流式硬解动态视频背景（MP4 / WebM，静音循环播放，最高 200MB）。

毛玻璃与多维独立半透明机制 —— 主面板、侧边栏、设置与弹窗、输入框、代码块均拥有独立的 0%~100% 连续不透明度滑块，互不干扰（彻底解决主面板全透时设置弹窗看不清字的问题）。毛玻璃强度（glassBlur）与背景模糊（backgroundBlur）完全解耦：背景模糊仅作用于底层壁纸/视频，而毛玻璃精准作用于侧边栏、输入框、斜杠命令（/）浮层、消息气泡、代码块、设置弹窗及弹窗外围遮罩。行内代码等强调字保留低透明度主色相，配合「强调字浓度」滑块精细微调；中性控件 hover 状态同步烘焙透明度，鼠标悬停平滑自然，绝不闪现死白/死黑的实心水泥块（解决 hover snapped opaque）。

背景三层架构与氛围 —— 独创三层渲染架构：底层基础画布（承载自定义纯色背景）、中层媒体层（承载壁纸/视频的独立不透明度与模糊）、顶层防眩光遮罩（随深浅色模式自动配色的纱帘渐变）。调低壁纸不透明度时平滑融入自定义背景底色，消除白斑；遮罩层有效保证亮图之上的文字易读性。

双模式专属预设 —— 浅色 5 款专属预设（晨曦、云天、薄荷、樱粉、雅灰）+ 深色 6 款经典预设（默认、午夜、海洋、森林、玫瑰、单色），一键应用并支持自由微调。

配色方案分享 —— 一键导出配色 JSON 至剪贴板，粘贴即可导入应用；欢迎在 GitHub Discussions 社区分享交流你的专属配色方案。

所有修改实时生效，无需刷新，无需保存。

安装

方式一：npm 一行命令（推荐）

dsh plugin --profile <name> add dsh-ui-appearance

方式二：一键脚本（Windows，无需 npm 账号与 git）

powershell -ExecutionPolicy Bypass -Command "Invoke-WebRequest 'https://raw.githubusercontent.com/TQSY114514/dsh-ui-appearance/main/install.ps1' -OutFile install.ps1; .\install.ps1"

脚本直接从 npm registry 拉取已构建的发布包（lib/ 预构建产物随包分发），链接进 profile 自己的 node_modules 并在该 profile 的 package.json 中注册（dependencies 条目 + dsh.profile.bundles，与 dsh plugin add 的产物一致）——幂等，可重复执行。可选参数：

.\install.ps1 -Version '0.1.27'     # 固定版本（默认装最新发布版）
.\install.ps1 -DshHome 'D:\.dsh'    # 自定义 DSH 主目录（默认 %DSH_HOME% 或 %USERPROFILE%\.dsh）
.\install.ps1 -ProfileName 'web'    # 目标 profile（默认 web；profile 需已初始化）

方式三：源码安装（已验证端到端）

git clone https://github.com/TQSY114514/dsh-ui-appearance.git
dsh plugin --profile <name> add file:<克隆到的本地路径>

卸载：dsh plugin --profile <name> remove dsh-ui-appearance（脚本安装则删除 profile node_modules 下的 junction 与 package.json 中对应的 dependencies/bundles 条目）。

更新：新版本发布后，重新执行 add 命令或安装脚本即可升级到最新版。

DSH Desktop 用户：Desktop 的 profile 与 Web 版相互独立——三种方式都可用，但要把插件装进 Desktop 实际激活的 profile（默认名为 desktop；Desktop 内置终端里直接跑 dsh plugin 即可，默认作用于当前激活的 profile）。

安装流程已验证端到端:npm registry 与 file: 源码直装两种方式均实测可用(host 半部零 @deepseek-ai 运行时依赖,浏览器与 Host 均能正确加载)。克隆后 pnpm install 会自动构建;修改代码后重新执行 pnpm install && pnpm prepare 并重启 dsh web。

版本演进见 [CHANGELOG.md](CHANGELOG.md)。

使用

1. 打开 WebUI,进入侧栏「设置」→「通用」

2. 在「外观」行下方找到「个性化外观」,点击展开

3. 点预设快速换肤 → 用取色器或 HEX 微调 6 个颜色角色 → 上传或拖入壁纸/视频 → 拖动氛围与界面滑块

4. 完成。所有调整实时生效,无需刷新、无需保存

设置面板内容一览:

区块 · 控件

模式与预设 · 浅色模式（默认 / 晨曦 / 云天 / 薄荷 / 樱粉 / 雅灰）与深色模式（默认 / 午夜 / 海洋 / 森林 / 玫瑰 / 单色）独立切换，一键应用后可继续微调

主题颜色 · 6 个角色 × (取色器 + HEX 输入)：主色、背景色、面板色、输入框色、文字色、边框色（全局所见即所得，气泡/按钮/选区内置智能对比度兜底）

背景 · 图片上传/更换/删除、视频上传/删除、URL 加载(图片/视频)、背景不透明度、背景模糊、背景遮罩

界面 · 面板不透明度、侧边栏不透明度、设置与弹窗不透明度、输入框不透明度、代码块不透明度、强调字浓度、毛玻璃强度

配色方案 · 导出配色、导入配色(JSON 文本)

持久化与恢复

• 设置保存在浏览器 localStorage(键 dsh-ui-appearance.settings),刷新与重启后保留,多标签页自动同步
• 从 profile 移除插件后界面恢复默认:卸载时自动回收所有覆写 token、样式表与背景图层
• 注意:设置跟随浏览器,换浏览器或清除站点数据会丢失;壁纸原图存 IndexedDB(localStorage 只存记录键),不受 localStorage 配额约束,并已向浏览器申请持久化存储降低被清理概率

工作原理

能力 · 机制

颜色与对比度 · ctx.theme.overrideTokens() 覆写 --dsw-alias-* 语义 Token，支持深浅双模式独立配置与所见即所得色彩还原。内置 WCAG 2.1 动态反解算法（a11yLabelStep）保证次级文字 $\ge 7:1$、三级文字 $\ge 4.5:1$；针对用户消息气泡（bubbleInk，综合面板透明度与底层画布/壁纸合成色）、文字选区（selectionColors）及主色按钮提供局部对比度自动兜底，既保留自定义文字色又杜绝撞色隐形

背景三层架构 · 自主研发三层独立图层（底层纯色画布 + 中层媒体层 + 顶层防眩光遮罩），沉底在 position: fixed; z-index: -1。当壁纸/视频生效时，自动对宿主底座（--dsw-alias-bg-base）进行透明打孔，绝不给 #root 赋予 position/z-index，从原理上消除层叠上下文（Stacking Context）陷阱，保证宿主与设置弹窗永远位于最顶层

组件级毛玻璃与边缘抗虚 · 背景模糊采用底层画布 filter: blur 配合 inset: -48px 外扩延伸，彻底消除屏幕

…(truncated)