dsh-theme-studio

dsh-theme-studio

给 DeepSeek Harness（DSH）界面做整体外观美化的插件：背景、字体、面板透明、毛玻璃、圆角、主题色，集中在设置页「主题美化」里调，改完即时生效并持久化。

• 目标 DSH：0.2.1-rc.2（已在本机核实）
• Node：>= 22.19.0
• 运行时依赖：无；无构建步骤（纯 ESM + 手写 Client factory）

名称声明：本项目与 GitHub 上同名的 dsh-theme-studio 仓库无任何关联，是独立实现。

功能

设计原则：默认值 = 不写任何 CSS 规则。没调过的项不会改变你现在的界面。

安装

仓库地址：https://github.com/vi0let-dev/dsh-theme-studio

方式一：DSH 直接从 GitHub 安装（推荐）

# 跟随 main 分支
dsh plugin --profile desktop add github:vi0let-dev/dsh-theme-studio

# 锁定 tag（可复现，推荐）
dsh plugin --profile desktop add github:vi0let-dev/dsh-theme-studio#v0.1.0

--profile 换成你自己的 profile 名（桌面版通常是 desktop，Web 版通常是 web）。不确定时看 $env:DSH_PROFILE_DIR 的最后一段。

方式二：界面安装

侧栏 插件 → 添加插件，输入：

github:vi0let-dev/dsh-theme-studio

方式三：本地目录（开发调试）

git clone https://github.com/vi0let-dev/dsh-theme-studio.git
dsh plugin --profile desktop add "<克隆下来的目录绝对路径>"

安装后 bundle 行不会热加载，请完全退出并重启 DSH，再硬刷新页面（Ctrl+Shift+R）。装完到 设置 → 主题美化 里调。

本包是纯 ESM JavaScript、零运行时依赖、无构建步骤，因此 GitHub 直装拉取源码后可直接运行，不需要 prepare 构建授权。

使用

1. 打开 设置 → 主题美化。
2. 所有改动会立刻在当前窗口预览（标记为「有未保存的改动」）。
3. 点 保存 写入 $DSH_HOME/dsh-theme-studio/config.json。
4. 恢复默认 会把所有项还原为“不改变界面”的状态并保存。

背景图片

• 本地图片：点「选择图片…」，浏览器读取后存进 IndexedDB（上限 8 MB），CSS 用 blob: URL 显示。插件从不读取你的文件路径，图片也不会离开本机。
• https URL：由浏览器直接加载，DSH 进程不发起请求。
• 代价：图片字节只存在当前浏览器。换浏览器/清站点数据后，配置仍在但图片缺失，此时自动回退为渐变并给出提示。

多窗口

配置是全局的（写在 $DSH_HOME）。保存后当前窗口立即生效；其他窗口刷新后才更新——插件不做后台轮询。

配置项

持久化文件 $DSH_HOME/dsh-theme-studio/config.json（DSH_HOME 未设置时用 ~/.dsh）：

{
  "version": 1,
  "background": {
    "mode": "none | gradient | image",
    "gradient": "aurora | dawn | ink | mint",
    "source": { "type": "none | url | stored", "url": "https://…", "imageId": "img…" },
    "opacity": 70,      // 0-100
    "blur": 0,          // 0-40 px
    "pageAlpha": 82     // 0-100
  },
  "typography": { "textFamily": "", "codeFamily": "", "weight": 400, "lineHeight": 1.5, "antialias": false },
  "transparency": { "page": 100, "card": 100, "overlay": 100 },
  "glass": { "enabled": false, "blur": 40, "saturation": 150 },
  "color": { "accent": "" },
  "shape": { "radiusScale": 1 },
  "motion": { "animations": true }
}

校验：越界数值 报错且不写入（不会偷偷改成边界值）；accent 必须是 #rrggbb；图片 URL 必须是绝对 https://；字体名只允许字母/数字/空格/逗号/连字符/引号。

实现方式（为什么不会把界面搞坏）

插件只做两类事：

1. 覆盖已核实的 DSH 设计令牌：--dsw-alias-bg-*、--dsw-menu-backdrop-filter、--dsw-radius-*、--dsw-alias-state-business-primary、--dsh-font-family-*、--ds-transition-duration*。
2. 画一层自己的固定背景层：html::before，position: fixed; z-index: -1，不参与布局。

透明度用 color-mix(in srgb, var(--dsw-static-neutral-bluish-*) N%, transparent) 表达，引用静态调色板而不是被覆盖的别名，因此不产生自引用循环，并自动跟随明暗主题。

上游若重命名令牌：对应效果静默失效，不会抛错、不会让页面空白。插件不替换 #root，不读其他插件的 DOM。

安全与隐私

• 不联网：插件自身不发起任何外部请求；只有你填的 https 图片 URL 由浏览器直连。
• 不读文件：Host 半侧只读写 $DSH_HOME/dsh-theme-studio/config.json；背景图由浏览器选、浏览器存。
• 路由只对本机开放：/api/dsh-theme-studio/* 要求回环 Host（127.0.0.0/8、localhost、[::1]）+ 自定义头 x-dsh-theme-studio: 1；PUT 还要求 application/json 且 body ≤ 64 KiB。
• 无遥测、无后台轮询、无子进程、无 eval/new Function/innerHTML。
• 日志只记阶段与错误码，不打印路径、配置全文或图片内容。

已知限制

• 密度/间距未实现：本版 DSH 设计令牌中不存在 --dsw-spacing/--dsw-gap/--dsw-density，无法用令牌安全表达；强行改组件 padding 会随上游 DOM 变化失效。当前只提供圆角缩放与动画开关。
• 行高是尽力而为：body { line-height } 只影响未自带行高的元素。
• 主题色不自动适配明暗：你选一个色值，深色/浅色两套都用它，请挑对比度足够的颜色。
• 桌面版 /api 可达性未在本机验证：桌面 index.html 由自定义协议 dsh-app:// 直出。插件按 DSH 既有约定使用根绝对路径 /api/...；若你的桌面壳不转发该前缀，配置读写会失败，但插件会退回本地缓存、样式仍生效（设置页会提示「无法连接 Host」）。
• 未在 macOS / Linux 上测试，仅 Windows 实测。

开发与测试

node --check index.js
node --check client.js
node --test                                  # 若沙箱禁止 fork 子进程，改用：
node test/plugin.test.mjs                    # 同进程执行，效果等价
npm pack --dry-run                           # 核对发布文件
python <skill-dir>/scripts/audit_plugin.py .  # 静态审计

测试覆盖：配置校验（越界/类型/格式/版本）、配置持久化（原子写、损坏文件、并发）、路由（栅栏、415、400、413、404）、CSS 构建（默认零规则、透明、毛玻璃、字体注入防护、圆角、动效）、apply 的样式注入与卸载清理。

docs/ 下有需求、设计、审计与测试报告。

常见问题

装完设置页没有「主题美化」？ dsh.client 的 bundle 只在启动时收集。请完全退出 DSH（不是关窗口）再启动，然后硬刷新页面。

背景图没出现？ 先看设置页是否提示「当前浏览器里没有这张图」。图片存在浏览器里，换浏览器/清站点数据会丢；重新选一次即可。

改了字体没生效？ 官方「设置 → 通用」里的字体行与本插件写同一个 CSS 变量。清空本插件的字体输入（或恢复默认）即回退官方设置。

透明调很低后看不清字？ 提高「页面底色不透明度」，或降低背景不透明度。极端值组合本来就会牺牲可读性。

许可证

MIT，见 LICENSE。