主题工作台 kjx-talesofai/dsh-plugin-theme-workbench

dsh-plugin-theme-workbench

五套主题，给 DeepSeek Harness Web 客户端用。每套都带浅色与深色两套配色，所以你自己设的浅色 / 深色 / 跟随系统仍然决定用哪一档——而且这个选择会存成真正的 Host 偏好，不放在浏览器存储里。

= 0.2.0-rc.1">

dsh-plugin-theme-workbench — 五套主题，每套都带浅色与深色，米白是默认

中文说明（点开） —— 五套主题，每套都带明暗两套配色，米白是默认

它是什么：DSH Web 客户端的主题插件。在「设置 → 通用」里加一行选择器，五套主题任选：米白（默认，暖米白纸感）、书卷（旧纸棕墨）、静谧（柔和鼠尾草绿）、现代经典（冷调纸白 + 深蓝点缀）、深度工作（近黑白）。

为什么做：DSH 内置的「外观」那一行是写死的三个方块（浅色／深色／跟随系统），第三方主题永远挤不进去；而且 ctx.theme.setTheme(第三方id) 在源码里只把 light|dark|system 三个值写进设置，其余不落盘——选了，重启就没了。所以第三方主题这个扩展点，官方文档自己写着「是扩展点，不是产品」。这个插件把这条缝补齐：自己画一行选择器，并且把选择真正存起来。

和其他主题插件的分工：社区里多数主题要么自己往页面塞 硬盖（只能靠 !important，DSH 一改样式就崩），要么走 register() ——而 register() 正是上面那条死路。这个插件走的是官方通道 ctx.theme.overrideTokens()：它只在当前生效的内置主题之上叠一层 token，所以你的明暗偏好照常工作，系统切换主题时配色也跟着切。代价是它只能改配色，不能改字体、圆角、壁纸。

怎么装（在 DSH「添加插件」里填，不需要 npm 账号、也无需发布）：

| 填入 | 形式 |
| GitHub | github:kjx-talesofai/dsh-plugin-theme-workbench#v0.1.3（当前可用） |
| 本地目录 | 绝对路径，例如 /path/to/dsh-plugin-theme-workbench |

装完重启桌面端（host 半边只在启动时加载）。之后换主题不用刷新、也不用再重启。

怎么用：设置 → 通用 → 主题 → 点色块。每块色块左边是浅色、右边是深色，中间一点是强调色。

注意事项：

- macOS 的侧边栏只能「染色」：它是系统级的半透明毛玻璃（Electron vibrancy），插件那条 sidebar token 只占到一层 40% 透明混合里的 38.8%，底下还有一条写死的蓝紫渐变。硬要它变成不透明的米白，等于把系统的通透感干掉，会更难看，所以不做。侧边栏的图标、hover、选中态都是跟着主题走的。
- 阴影改不了：DSH 把阴影配方声明在 body, body 上，每个元素都自己重新声明一遍，body 级覆盖被屏蔽。只有它的发丝线颜色跟着主题。（所以每一块面都得靠填充色和发丝线把层次说清楚，这也是本插件把表面阶梯做得很讲究的原因。）
- 非 loopback 页面不落盘：DSH 在非回环地址下把设置作用域放在内存里，主题这次会生效，刷新就没了。
- 只改了配色：字体、圆角、语法高亮、壁纸都不在范围内。

卸载：DSH「插件」列表里卸载 dsh-plugin-theme-workbench → 重启。主题选择留在你 profile 的 cordis.patch.yml 里，想一起清掉就把那段 - id: theme-workbench 删掉。

老实说（实测范围）：只在 macOS（Apple Silicon）+ DSH Desktop 0.2.0-rc.2 上端到端跑过（浅色、深色、切换、落盘、卡片观感都实际看过）。Windows / Linux 未测；DSH 升级后上游契约可能变化，见下方 Compatibility。

为什么

DSH 内置的 Appearance 行渲染的是一组硬编码的 Light / Dark / System 方块，第三方主题无处可显。而 ctx.theme.setTheme 只会在同一个三值联合类型里持久化 id——所以通过 ctx.theme.register() 注册的主题，既在自带的选色器里看不见，重启后也会丢失选择。上游 README 对此很坦诚：第三方主题是「扩展点，不是产品」。

这个插件只补上这两个缺口，别的什么都不做：

- 它叠加一层 token，用 ctx.theme.overrideTokens() 覆盖当前生效的内置主题，而不是自己注册一个主题。你的 light / dark / system 偏好照常工作，系统配色也会继续切换调色板——所以这里的每个主题都自带两套调色板，而不是被锁死在一套上。
- 它自己画一行，因为想要开关的主题就得自己画。
- 它把选择存成 Host preference，和其他所有 DSH 设置放在一起，而不是塞进 localStorage。
- 它是调色板插件，不是换皮。 字体、圆角、语法高亮和壁纸都还是 DSH 的。

主题

| 主题 | 浅色画布 | 深色画布 | 特点 |
| Cream（默认） | #f7f3ea | #1b1917 | 温暖的米白纸感，柔和的陶土色点缀 |
| Novel | #f6f0e2 | #1d1a15 | 做旧纸张，棕褐墨色，暗沉牛血红 |
| Calm | #f2f5f2 | #111614 | 柔和鼠尾草绿，低对比，边缘安静 |
| Modern Classic | #f7f8fa | #15171b | 冷调纸张，近黑墨色，深蓝点缀 |
| Deep Work | #f6f6f5 | #0c0e11 | 近单色，高对比，暗哑青铜 |

每个主题每种模式只有三个种子色——画布、墨色、点缀色——全部 117 个 token 都由它们推导出来。没有别的手工罗列，所以主题不会跑出自己的色相，也不会悄悄丢掉自己的温度。

安装

用 DSH 的插件安装对话框（Add plugin）填入下面任意一项，然后重启桌面应用：

github:kjx-talesofai/dsh-plugin-theme-workbench#v0.1.3 # GitHub, pinned to this release
/absolute/path/to/dsh-plugin-theme-workbench # local checkout (dev)

这个插件没有发布到 npm registry。DSH 会拒绝相对路径（a local path must be absolute），所以要用绝对路径。在本地检出目录里跑 npm pack 会生成一个 .tgz，可以直接发给别人。

命令行等价写法：

dsh plugin --profile desktop add github:kjx-talesofai/dsh-plugin-theme-workbench#v0.1.3

升级时，先卸载再安装新版本——不支持在已有行上直接重装。

用法

1. Settings → General → Theme。
2. 点一个色块。每个色块左半边显示浅色调色板，右半边显示深色调色板，点缀色是那个圆点。
3. 在 Settings → General → Appearance 里切换 Light 和 Dark，就能看到另一套调色板。不用刷新，不用重启。

选择会写进你配置档的 cordis.patch.yml，所以也可以不用 UI 直接设置：

- id: theme-workbench
name: 'dsh-plugin-theme-workbench'
config:
theme: cream # cream | novel | calm | modern-classic | deep-work

工作原理

Settings row ──▶ ctx.configForms ──▶ host Config ──▶ ~/.dsh/profiles/PROFILE/cordis.patch.yml
│ (the row id IS the settings namespace)
│
└──▶ ctx.theme.overrideTokens(source, { token: { light, dark } })
│
▼
ThemePresenter writes them as inline custom properties on <body>,
retracting the previous set first — so unloading restores everything.

index render ──▶ webserver/index-inject { kind: 'global' }
│
▼
globalThis.__DSH_THEME_WORKBENCH__ = <persisted id>
│
└──▶ the plugin's FIRST overrideTokens call is already correct,
instead of the schema default followed by a repaint.

| 应用 | ctx.theme.overrideTokens，按包 id 分一层（重新应用是替换，绝不叠加） |
| 持久化 | Host 半边的 .volatile() Config 字段；dsh-settings 从 Loader 行 id 推导命名空间 |
| 首帧绘制 | 持久化的 id 作为 global 行推入每次 index 渲染 |
| 行 | settings.general.item 的增量占位者，独立 id，order: 13 |
| 拆除 | 覆盖层、行的 标签、语言字典、插槽注入都返回真正的 disposer |

设计规则

调色板是推导出来的，不是查表得来的，规则本身就是重点——它们对照已发布的设计系统做过研究，又用数值验证过。其中两条足够反直觉，值得单独说明。

浅色模式下，内容表面从画布往下走。 卡片、输入框、侧边栏、代码块、气泡都比页面略暗；只有真正浮起的表面（菜单、浮层、对话框）才高于页面，且上限为 L\ 98.5。纸感调色板实际就是这么做的——Material 3 的容器阶梯往下走 2 个色调单位，Solarized、Everforest、Kanagawa、Catppuccin、Radix 也全都往下走。原因有两个：抬起的纸面是带阴影的；而在 L\* 97–99 区间，sRGB 几乎没剩下多少彩度空间，所以更亮的暖色表面受色彩空间所迫就是白色，无论本意如何。深色模式方向相反，因为发光是加光。

没有任何东西是靠向白色混合推导出来的。 表面是从画布重新取样：保留色相，移动明度，按显式系数缩放彩度。旧的混合方式从构造上就耗掉了画布的彩度——输入框那一档只保住了 cream 画布 13.4% 的暖意，最后落在 #fefdfc。
文本层级与语义状态是解算出来的，不是继承来的。 每个文本层级都按内置调色板能达到的对比度解算（浅色 5.8 / 3.71 / 2.13），所以柔和的棕褐或鼠尾草墨色，和随包发布的近黑色一样清晰可读。内置语义状态是按 #ffffff 调的，放到暖色纸上就是可读性灾难——在奶油色画布上实测，state-warn-primary 是 1.94:1，state-warn-label 2.52:1，state-success-primary 2.06:1，state-error-primary 4.06:1——所以每个主题都提供暖纸等价色。焦点环在全部六十组表面对上都能过 4.5:1。

每个当背景用的 token，都按画在它上面的所有文字解算，而不是按它自己的名字。 三块底色和一枚徽章就是这么处理的。失败模式每次都一样：token 的名字描述的是角色（sidebar-nav-item-active-accent、state-success-tertiary），于是从角色出发推导——把强调色以 12–22 % 混进侧边栏，以固定比例混进画布——结果标签就落在自己的颜色上，徽章在全部十套调色板里都是 1.25–1.53:1，成功色小片是 4.21–4.48:1。徽章那种情况不是淡，是看不见。这四处现在都取「能让画在它们上面的每种颜色都保持 4.5:1」的最大色调，而且是整体一起解算，不是逐段文字分别解算，因为哪种文字构成约束会随模式变化（同一枚小片，内置配色在浅色模式下只能到 3.60:1）。

这套清单是从归档里枚举出来的，不是猜的：tools/audit-contrast.mjs 会挖出随包发布的 bundle 里每一条「在背景上涂颜色」的规则，再在全部十套调色板下重新测量。徽章就是这么被发现的，也是 npm test 单靠自己做不到的事——测试只能检查某个人已经知道的配对。

装饰性图形同样是推导出来的，不是继承来的。 引导流程的强调色和它的三条渐变坡道在上游只声明一次，没有深色版本，所以在暖色纸上、两种模式下都保持它们的紫/蓝/青。这里坡道变成主题自己强调色的三次旋转——一个更暖的邻居、一个更冷的邻居，停靠点几何沿用随包发布的版本——这样三张卡片仍然能分辨，又不必引入主题并不拥有的两种颜色。它们所栖身的磨砂卡片从画布重新采样，工具栏蒙层取自墨色，而不是随包发布的中灰色——那个中灰色在暖色纸上是一颗冷色药丸，在深色上几乎看不见。

以上一切都有测试套件测量：每一步的方向、浅色调色板内 6 L\* 的上限、L\* 98.5 的暖色域上限、整条坡道上的彩度保持、文本阶梯、装饰坡道的色相族，以及每一处对比度下限。

它触及不到的地方

- macOS 侧边栏只做染色。 它是 Electron 的毛玻璃效果，不是刷上去的填充色：唯一的 CSS 是一段 color-mix，把本插件的侧边栏 token 稀释到 40% alpha 图层的 38.8%，叠在写死的蓝色渐变上，再叠在窗口背后的内容上。想给它换色，就等于放弃平台本身的半透明。它的图标、悬停和激活态确实跟随主题。
- 阴影是固定的。 --dsw-elevation-stroke/-panel/-prominent/-soft 在 body, body 上重新声明，所以每个元素都叠加了一层 body 级覆盖，配方的几何与 alpha 原样生效。它们的细线颜色确实跟随主题，因为那部分是 body 级的。
- 少数只在 macOS 上出现的字面量，比如新建会话按钮的 #ffffff8c，没有任何 token 供给它。
- 表格预览保持白色。 它的样式表是第三方样式表（fortune-sheet，在 client.excel.js 里），带 233 条颜色声明，却没有一个深色模式选择器，所以在右侧面板打开 .xlsx，你看到的是深色主题里套着一个白色应用。没有任何自定义属性传得进去。PDF 预览和终端跟随主题；终端的输入法浮层不跟随。
- 代码和文件 diff 保留自带的绿色和红色。 这些色相承载含义（新增 / 删除），自带的值本身已经区分明暗模式，审计也没测出可读性或适配缺陷。保持原样。
- --dsw-alias-button-tool-bar-fill-invisible 写了但没人读。 自带样式表声明了它，0.2.0-rc.2 里没有任何地方消费它。这里仍然覆盖了它，免得将来出现消费方时工具栏这一族只做了一半主题。
- 字体、圆角和语法高亮。 :root 自定义属性仍会继承进 body，所以从这里技术上够得着；本插件刻意不碰它们。

兼容性

在 macOS（Apple Silicon）· DSH Desktop 0.2.0-rc.2 上做了端到端验证，明暗两套配色、实时切换和持久化都用肉眼确认过，也检查了运行中的主题服务。

本插件依赖的上游契约，全部由测试套件锁定：

| 契约 | 来源 |
| overrideTokens(source, {light, dark}) 按 source 替换 | dsh-client-ui-theme |
| token 层以内联方式作用在 body 上，变更时撤回 | dsh-client-ui-layout（ThemePresenter） |
| Config 需要 toJSON；命名空间就是 Loader 行 id；只有 .volatile() 字段可被页面写入 | dsh-settings |
| kind: 'global' 的 index-injection 行 | dsh-host-webserver |
| 客户端 bundle 需要 dsh.client.platform 和 exports["./client"] | dsh-client-modules |
| 107 个 --dsw-alias- 名称及其明暗取值 | dsh-client-ui-theme |

未测试：Windows、Linux，以及 0.2.0-rc.2 以外的 DSH 版本。DSH 升级后先跑 npm test —— token 名称白名单是刻意做的快照，所以上游改名会直接报错，而不是悄悄漏出内置颜色。

开发

下面的 npm 就是 Node 自带的命令行，不需要账号，也没有发布任何东西。

npm test # 49 tests; no install step needed, run it on a bare checkout
npm pack --dry-run # what actually ships (9 files)

npm test 不需要 node_modules：测试套件把浏览器那一半当作脚本放进 node:vm 里执行，把 Host 那一半当文本读取，所以它从不导入那唯一的运行时依赖。CI 正是靠这一点。

仓库结构 —— 源码与产物：

| 路径 | 是什么 | 是否随包发给用户 |
| index.js | host 那一半：.volatile() 设置 schema + 索引注入行 | ✓ |
| client.js | 浏览器那一半：手写的客户端 bundle（没有构建步骤） | ✓ |
| cordis.patch.yml | bundle 层：插入本插件的 Loader 行 | ✓ |
| assets/icon.svg | DSH 插件管理器里显示的插件图标 | ✓ |
| locale/{en,zh}.json | 插件管理器的标题和描述 | ✓ |
| tests/plugin.test.mjs | 整套测试：bundle 形态、slot 契约、token 推导、对比度下限、选择流水线 | ✗ |
| docs/token-inventory.md | DSH 0.2.0-rc.2 的 token 面：浅色/深色调色板放在哪、快照如何到达 DOM、全部 107 个别名，以及那些坑 | ✗ |
| docs/surface-map.md | 哪个 token 涂哪个表面、哪些在本地重新声明、body 级覆盖永远够不到什么 | ✗ |
| docs/design-notes.md | 表面阶梯所依据的暖纸设计规范：带出处的参考调色板、高度配方、色度与色相纪律、反模式 | ✗ |
| docs/readability-audit.md | 那次审计发现了什么、覆盖范围的局限，以及唯一一个悬而未决的问题 | ✗ |
| tools/asar.mjs | 只读 ASAR 读取器，用来检查应用 bundle | ✗ |
| tools/audit-contrast.mjs | 全归档可读性审计：每一条在背景上涂颜色的规则，都在全部十套调色板下重新测量 | ✗ |

docs/ 里的资料是这些数字背后的研究，特意留在仓库里：两份描述平台（什么能换主题、什么不能），第三份是设计论证，第四份是拿已发布的归档重新核对结果的审计。它们都不随包发布。

卸载

在 DSH 的插件列表里移除插件并重启。主题选择仍留在你配置档的 cordis.patch.yml 里；删掉 - id: theme-workbench 块即可一并移除。

许可证

MIT © 2026 Jiaxin Kou

由 Jiaxin Kou 构建 · GitHub