界面美化 vi0let-dev/dsh-ui-beautify

dsh-ui-beautify

给 DeepSeek Harness（DSH）Web 界面加一层可配置的外观层：风格预设、表面透明度、背景图、界面/代码字体。

它只通过 DSH 官方 Client theme 服务的 overrideTokens 覆盖设计令牌，并用插件自己的 绘制背景图；不替换 app root、不追加第二个应用、不联网、不读会话内容。

状态：源码已完成，28 项单元测试、结构自检与安全扫描通过；尚未在你的 DSH 中安装、启用或做视觉验证。安装与验收由你自行完成。

仓库：<https://github.com/vi0let-dev/dsh-ui-beautify>

版本：0.1.2 —— 设置页固定 100% 不透明，表面透明度只影响设置页之外的界面；0.1.1 起背景图改为 IndexedDB Blob 存储（原文件上限 40 MB，解除 localStorage 字符上限）。

功能

| 功能 | 说明 |
| 风格预设 | 跟随 DSH / 玻璃 / 暖纸 / 樱花 / 极简；每套都定义明亮与深色两组取值 |
| 表面透明度 | 0–100%，作用于主背景、卡片、侧栏、气泡、代码块等表面 |
| 设置页不透明 | 无论表面透明度调到多少，设置面板始终 100% 不透明，方便边调边看 |
| 背景图 | 本地上传（浏览器内压缩后保存）或 http(s) 图片链接；支持 0–24px 模糊、0–70% 遮罩 |
| 界面字体 | 跟随 DSH / 系统无衬线 / 衬线（宋体）/ 圆体 / 等宽 / 自定义字体列表 |
| 代码字体 | 跟随 DSH / 等宽 / 系统无衬线 / 自定义字体列表 |
| 圆角风格 | 随预设改变 --dsw-radius-；不改 DSH 的语义状态色 |
| 恢复默认 | 两次点击确认后恢复“跟随 DSH + 不透明 + 无背景图 + 跟随字体” |

设置入口：侧边栏 → 设置 → 界面美化。所有修改即时生效。

环境要求

- DSH >=0.2.1-rc.2 <0.3.0（见 package.json 的 engines.dsh）
- Node.js ^22.19.0 || >=24.0.0
- 仅适用于 Web 界面（dsh.client.platform = "web"）

插件没有运行时依赖；react 由 DSH 浏览器模块表提供，不额外打包第二份 React。

契约按 DSH 0.2.1-rc.2 核对，使用的扩展点：

| 扩展点 | 用途 |
| Client ctx.theme.overrideTokens(source, tokens) | 以 { light, dark } 双套值覆盖设计令牌，卸载时移除该层 |
| settings.section | “界面美化”整页设置 |
| ctx.locale | 设置页与插件管理器文案 |
| | 背景图与设置页样式，卸载时移除 |

安装

以下命令需要你自己执行：本仓库不包含安装脚本，也不会自动修改你的 profile。

GitHub 仓库（公开）：<https://github.com/vi0let-dev/dsh-ui-beautify>

方式一：插件页安装（推荐）

1. 侧边栏 → 插件 → 添加插件
2. 输入 github:vi0let-dev/dsh-ui-beautify
3. 按提示启用，完全退出 DSH 并重启，然后硬刷新页面（Windows/Linux Ctrl+F5，macOS Cmd+Shift+R）
4. 侧边栏 → 设置，左侧出现 界面美化，即安装成功

方式二：GitHub 命令行安装

先确认自己的 profile 名，不要照抄 $env:DSH_PROFILE

dsh plugin --profile <profile> add github:vi0let-dev/dsh-ui-beautify

锁定到本次发布的 tag：

dsh plugin --profile <profile> add "github:vi0let-dev/dsh-ui-beautify#v0.1.2"

当前分支为 main。插件页/命令行安装的是仓库默认分支 main 的最新提交；仓库更新后需要重新执行一次 dsh plugin ... add 才会拉取新版本。

本地开发调试：

dsh plugin --profile <profile> add "<项目绝对路径>"

本地目录是链接安装，不要移动或删除原目录，否则插件随之失效。

升级：GitHub 直装会在 profile 里放一份副本。升级到 0.1.2（设置页固定不透明）时，重新执行一次 dsh plugin --profile <profile> add github:vi0let-dev/dsh-ui-beautify（或锁定 #v0.1.2），完全退出 DSH 并重启，然后硬刷新页面；本地链接安装改完刷新页面即可。

卸载 / 恢复原始外观：在插件页停用并卸载，重启 DSH 后刷新页面。插件卸载时会移除 token 图层、背景图样式、根节点属性和 CSS 变量；浏览器 localStorage 里的两个键需要手动清除（见下方「配置」）。

使用

1. 打开 设置 → 界面美化。设置面板始终 100% 不透明，透明度滑块只改变面板之外的界面。
2. 在「外观风格」里选一套预设，或保持“跟随 DSH”。
3. 需要背景图时：选择本地图片，或粘贴 http(s) 图片链接后点「使用链接」。
4. 调「表面透明度」让背景图透出；文字不清楚时调高「背景遮罩」或降低「背景模糊」。
5. 在「字体」里选择界面字体/代码字体；选「自定义…」后输入逗号分隔的字体名。

典型组合：

- 玻璃 + 背景图 + 60% 透明度 + 20% 遮罩：半透明磨砂感，背景图可见且文字可读。
- 暖纸 + 不透明 + 衬线字体：接近纸张的阅读界面。
- 极简 + 不透明 + 等宽字体：低装饰、高信息密度。

配置

没有 Host 配置项，cordis.patch.yml 的 config 保持空对象。所有偏好保存在浏览器：

| 存放位置 | 内容 | 清理方式 |
| IndexedDB dsh-ui-beautify → store wallpaper | 背景图 Blob + 名称/尺寸/字节数（优先使用） | 设置页「清除背景图」，或 DevTools → Application → IndexedDB 删除 dsh-ui-beautify |
| localStorage['dsh-ui-beautify:settings'] | 风格、透明度、模糊、遮罩、字体选择（JSON） | 设置页「恢复默认」，或控制台 localStorage.removeItem('dsh-ui-beautify:settings') |
| localStorage['dsh-ui-beautify:wallpaper'] | 旧版/回退：背景图 data URL 或图片链接（仅当 IndexedDB 不可用时使用） | 设置页「清除背景图」，或控制台 localStorage.removeItem('dsh-ui-beautify:wallpaper') |

默认值：

| 字段 | 默认值 | 范围 |
| style | follow | follow / glass / paper / sakura / minimal |
| surfaceOpacity | 100 | 0–100 |
| wallpaperBlur | 0 | 0–24 |
| wallpaperDim | 0 | 0–70 |
| fontText | follow | follow / sans / serif / rounded / mono / custom |
| fontCode | follow | follow / mono / sans / custom |

- 非法/越界值在读取时回落到默认值。
- 本地背景图优先存到 IndexedDB（Blob），因此不再受 localStorage 的字符上限限制。原文件最大 40 MB；最长边超过 2560px 或原文件超过 8 MB 时，会先缩到最长边 2560px 并按质量阶梯压成 WebP，压缩结果上限 12 MB。
- IndexedDB 不可用时回退到 localStorage data URL，此时仍受约 180 万字符上限，并在存储配额不足时提示「仅本次会话生效」。
- 浏览器存储不可用或配额不足时，设置仍会在本次会话生效，但刷新后丢失。

项目结构

dsh-ui-beautify/
├── package.json # bundle 声明：dsh.bundle.patch + dsh.client ├── cordis.patch.yml # 把插件插入 profile 组合树 ├── index.js # Host 半边：空实现（本插件没有 Host 逻辑） ├── client.js # 全部实现：token 图层、背景图、字体、设置页 ├── locale/{zh,en}.json # 插件管理器显示的标题与描述 ├── icon.svg # 插件图标 ├── docs/banner.png # README 顶部 banner ├── test/client.test.mjs # node:test + node:vm 行为测试 ├── AUDIT.md # 代码审计与隐私检查报告 ├── README.md ├── LICENSE ├── .gitignore └── .gitattributes

依赖

运行时零依赖。开发/测试只使用 Node 内置的 node:test、node:vm、node:assert、node:fs。

隐私说明

| 问题 | 回答 |
| 读取哪些数据 | 只读取你在设置页主动选择的本地图片；不读会话内容、文件系统或其他插件数据 |
| 数据发往哪里 | 插件 JavaScript 不发任何网络请求；若你填写远程图片链接，浏览器会按该地址请求图片 |
| 是否持久化 | 背景图 Blob 写入本机 IndexedDB dsh-ui-beautify；设置写入 localStorage dsh-ui-beautify:settings；IndexedDB 不可用时背景图回退到 localStorage dsh-ui-beautify:wallpaper |
| 是否采集遥测 | 无 |
| 如何清除数据 | 设置页「恢复默认」/「清除背景图」，或删除 IndexedDB 数据库 dsh-ui-beautify 与上述 localStorage 键 |

安全注意事项

- 不执行动态代码：没有 eval、new Function、innerHTML、document.write。
- 背景图只接受 http(s) 链接或 data:image/(png|jpeg|webp|gif|avif);base64,...；拒绝 javascript:、file:、SVG data URL、带用户名/密码的 URL。
- 不替换 DSH 的 app root，不向 document.body 追加第二个应用；背景图只画在 body::before / body::after 两个插件自有伪元素上。
- 所有注册（locale、slot、样式、token 图层、CSS 变量、订阅）都挂在 ctx.effect 上并返回清理函数。
- 透明度过低会降低可读性；菜单/弹出层保留至少 88% 不透明度。
- 远程图片由浏览器加载，受你的浏览器 CSP、代理与网络策略约束；插件无法验证远端图片是否可用。

开发说明

node --check index.js
node --check client.js
node test/client.test.mjs # 28 项测试，直接运行（无需 spawn 子进程）

也可以 node --test test，但在某些受限沙箱里跑测试 runner 会因 spawn EPERM 失败，直接执行测试文件即可。
测试覆盖：模块注册 id、依赖声明、settings.section 注册参数、locale 字典、设置归一化与越界回退、hex→rgba 换算、预设 token 明暗双套、透明度表面覆盖、设置面板不透明 token、字体预设与自定义、背景图 URL/data URL 安全校验、背景图 CSS 生成与转义、本地图片的 IndexedDB Blob 路径与 localStorage 回退路径、超尺寸缩放、损坏图片拒绝、apply/cleanup 行为、存储异常兜底、token 图层去重、设置页 CSS token 使用，以及「无网络 / 无 eval / 无 HTML 注入」的静态断言。

改造指引：

- 五套调色板集中在 client.js 的 STYLES，每套含 palette.light / palette.dark / radius。改值即改观感。
- 字体预设集中在 FONT_TEXT_PRESETS / FONT_CODE_PRESETS。
- 新增预设需要同时更新 STYLE_IDS（按钮、校验、token 构建都读它）与 locale/{zh,en}.json 的 meta（插件管理器显示）。
- token 名必须与当前 DSH 版本一致；升级 DSH 后先用主题 inspect 复核 --dsw-alias- 与 --dsh-font-family-*。

已知限制

1. 尚未做真机视觉验证：本仓库只做了静态核对与单元测试。settings.section 是否正常渲染、五个预设的实际观感、深色模式下的对比度，都需要你在真实 DSH 中确认。
2. 只覆盖已知/常用的设计令牌：主背景、层、侧栏、气泡、代码块、边框、标签、品牌色与圆角。部分嵌套组件（菜单、对话框、第三方面板）可能保留自己的不透明表面。
3. 透明度需要背景图才明显：没有背景图时，透明表面露出的是画布底色（白/深），观感变化较小。
4. 菜单/弹出层有 88% 不透明度下限：避免为了透明而牺牲可读性，因此它们不会完全透明。
5. 背景图存储：优先存 IndexedDB Blob（原文件上限 40 MB，压缩结果上限 12 MB）；IndexedDB 不可用时回退到 localStorage data URL，此时约 180 万字符上限，超限会提示改用图片链接。隐私模式或存储被禁用时，设置只在本次会话生效。
6. 远程图片受 CSP/网络影响：插件只校验 URL 协议；图片能否加载由浏览器决定。
7. 第三方 DSH 主题：透明表面与设置面板使用插件自带的明暗中性/预设色，不读取第三方主题的原始色值；换用第三方主题后，设置面板与透明表面的底色可能与主题不完全一致。
8. 字体覆盖优先于 DSH 字体设置：选择非「跟随 DSH」的字体后，DSH 自带的字体设置会被本插件覆盖；想恢复 DSH 字体请选「跟随 DSH」。
9. 未做动效：预设只改色彩、圆角与透明度，不做消息入场/悬停动画，避免依赖构建期哈希类名。
10. macOS 窗口样式差异：DSH 在 macOS 上让 AppFrame 透明、侧栏使用渐变；本插件按 Windows/Web 的令牌路径设计，macOS 上的透明表现可能不同。

许可证

MIT，见 LICENSE。