dsh-theme-studio

Name: vi0let-dev/dsh-theme-studio
Author: vi0let-dev

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

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

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

功能

分组	能力
背景	无 / 内置渐变（4 套）/ 本地图片 / https 图片 URL；背景不透明度、模糊、页面底色不透明度
字体	文本字体与代码字体（CSS 字体栈）、字重（300/400/500）、行高、抗锯齿
透明	页面底色、卡片、浮层的独立不透明度
毛玻璃	开关 + 模糊半径（0–40px）+ 饱和度（100–200%）
主题色	自定义强调色（`#rrggbb`），同步覆盖焦点环颜色
圆角与动效	圆角整体缩放（0.5–2.0）、界面动画开关

设计原则：默认值 = 不写任何 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 构建授权。

使用

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

背景图片

本地图片：点「选择图片…」，浏览器读取后存进 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://；字体名只允许字母/数字/空格/逗号/连字符/引号。

安全与隐私

不联网：插件自身不发起任何外部请求；只有你填的 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」）。

实现方式（为什么默认不改界面，改了就压得住）

插件只做两类事：

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

三条关键细节（v0.1.1 / v0.1.2 修复）：

层叠优先级：DSH 的令牌样式以可构造样式表（adoptedStyleSheets）注入，按 CSS 规范排在页面 <style> 之后，普通 body { … } 会被主题压掉。所以本插件的每条覆盖都写成 :root:root:root body 并带 !important——先比优先级、再比顺序，两个层面都赢。
背景层是「透出来」而不是「盖上去」：背景图/渐变画在 html::before，页面底色通过 --dsw-alias-bg-base 的 color-mix(... N%, transparent) 变半透明才看得见。启用背景时还会把 #root 的背景设为透明，避免应用根节点自己画了一层不透明底把背景挡住。
面板必须一起透：会话页的三栏框架和卡片用 --dsw-alias-bg-layer-1/2、--dsw-alias-bg-overlay 上色，默认 100% 不透明会把壁纸整块盖住（启动页没有面板，所以看起来“只有启动页生效”）。启用背景时，这三个值在你还没显式调整的情况下自动按 72% 生效。注意透明度是相乘的：页面 82% × 面板 82% 会让壁纸只剩约 3%，所以想看清背景，请把「页面底色不透明度」调到 30–40、卡片留在 70–80。

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

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

未在 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。

dsh-theme-studio

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

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

功能

分组	能力
背景	无 / 内置渐变（4 套）/ 本地图片 / https 图片 URL；背景不透明度、模糊、页面底色不透明度
字体	文本字体与代码字体（CSS 字体栈）、字重（300/400/500）、行高、抗锯齿
透明	页面底色、卡片、浮层的独立不透明度
毛玻璃	开关 + 模糊半径（0–40px）+ 饱和度（100–200%）
主题色	自定义强调色（`#rrggbb`），同步覆盖焦点环颜色
圆角与动效	圆角整体缩放（0.5–2.0）、界面动画开关

设计原则：默认值 = 不写任何 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 构建授权。

使用

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

背景图片

本地图片：点「选择图片…」，浏览器读取后存进 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 }
}

安全与隐私

不联网：插件自身不发起任何外部请求；只有你填的 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」）。

实现方式（为什么默认不改界面，改了就压得住）

插件只做两类事：

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

三条关键细节（v0.1.1 / v0.1.2 修复）：

层叠优先级：DSH 的令牌样式以可构造样式表（adoptedStyleSheets）注入，按 CSS 规范排在页面 <style> 之后，普通 body { … } 会被主题压掉。所以本插件的每条覆盖都写成 :root:root:root body 并带 !important——先比优先级、再比顺序，两个层面都赢。
背景层是「透出来」而不是「盖上去」：背景图/渐变画在 html::before，页面底色通过 --dsw-alias-bg-base 的 color-mix(... N%, transparent) 变半透明才看得见。启用背景时还会把 #root 的背景设为透明，避免应用根节点自己画了一层不透明底把背景挡住。
面板必须一起透：会话页的三栏框架和卡片用 --dsw-alias-bg-layer-1/2、--dsw-alias-bg-overlay 上色，默认 100% 不透明会把壁纸整块盖住（启动页没有面板，所以看起来“只有启动页生效”）。启用背景时，这三个值在你还没显式调整的情况下自动按 72% 生效。注意透明度是相乘的：页面 82% × 面板 82% 会让壁纸只剩约 3%，所以想看清背景，请把「页面底色不透明度」调到 30–40、卡片留在 70–80。

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

未在 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 .  # 静态审计

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

常见问题

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

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

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

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

许可证

MIT，见 LICENSE。

vi0let-dev/dsh-theme-studio

dsh-theme-studio

功能

安装

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

方式二：界面安装

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

使用

背景图片

多窗口

配置项

安全与隐私

已知限制

实现方式（为什么默认不改界面，改了就压得住）

开发与测试

常见问题

许可证

Community comments

vi0let-dev/dsh-theme-studio

dsh-theme-studio

功能

安装

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

方式二：界面安装

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

使用

背景图片

多窗口

配置项

安全与隐私

已知限制

实现方式（为什么默认不改界面，改了就压得住）

开发与测试

常见问题

许可证

Community comments