主题工作室 marselarts/dsh-theme-studio

dsh-theme-studio

在设置页里定制 Harness Web UI 的颜色和字体，明暗两套配色各自独立，带实时预览、预设，还有自定义 CSS 这个后门。

插件没有另造一套样式系统，改的就是客户端本来就在用的那一套：

- 语义 token —— 全部 107 个 --dsw-alias- 变量（表面、文字、边框、强调色、状态、按钮、代码、diff、菜单、工具提示、滚动条），正是设计系统的 token 表定义的那一套。
- 组件填充 —— 组件自己声明的 11 个 --dsw-specific- 表面（侧边栏列及其行、消息气泡、输入框、菜单材质、选择器）。
- 静态色板 —— 上面那些别名最终解析到的 77 个 --dsw-static- 色阶，改一个色阶就能给整个产品重新上色（比如 --dsw-static-deepseek-500）。
- 排版 —— --dsw-font-family（界面）、--ds-font-family-code（代码、diff、编辑器）、--dsw-font-family-brand（品牌字标），再加上 harness 自己的对话文字大小，通过 theme.setFontSize() 写入。
- 自定义 CSS —— 插件自带一张样式表，token 覆盖不到的地方都归它管。

覆盖值交给 ctx.theme.overrideTokens(id, tokens)，也就是主题服务公开的扩展点。presenter 把这一层折进当前快照，画到 body 上，所以明暗切换、首屏绘制、卸载清理都还是 harness 自己的事。

| 标签页 | 改什么 |
| Colors Simple | 快捷入口，也是页面默认打开的标签页：左侧一列分区（Text、App background、Conversation、Sidebar、Panels、Sidebar… menus、Accent、States、Code and diffs、Controls），选中某个分区后，只显示它自己的相对颜色——背景、文字、边框、悬停等等。每个分区带一个角标，显示你改了几种颜色；两个分区之间不共用任何 token |
| Colors | 完整网格：可搜索、已分组、每套配色（light / dark）一个控件、原生色块加自由填写值（var(...)、color-mix(...)、transparent）、单个 token 重置、「只看已改」筛选。每行只显示标签——设计系统的说明和变量名放在该行的工具提示里 |
| Fonts | 三个 font-family 变量，每个槽位一个候选列表，一个实时样例，还有对话文字大小；本机没有的字体族会标出来 |
| Presets | 五个协调的起点（Warm paper、Nord、Solarized、Rosé Pine、High contrast）、JSON 导出/导入、全部重置 |
| Advanced | 自由填写的样式表，配一键片段（界面缩放、标题颜色、更柔和的圆角、不透明菜单、暖色阅读表面） |

安装

包声明了 dsh.bundle.patch 和 dsh.client，所以官方安装器会自己挂载它，并加进配置档的 bundle 栈：

dsh plugin --profile desktop add <absolute path to this directory>

这会记下一条 link: 依赖，配置档指向本目录而不是复制一份：编辑 src/ 并重新运行 npm run build 就足以更新插件，而移动或删除这个目录会破坏安装。用 dsh plugin --profile desktop remove dsh-theme-studio 卸载，或者从 git URL 重新安装来冻结它。

之后重新加载 Web GUI。页面出现在 Settings → Theme Studio。想在不卸载的情况下停用它，就在配置档的 cordis.patch.yml 里覆盖那一行：

- id: theme-studio
disabled: true

设置存放在哪里

<DSH_HOME>/dsh-theme-studio/theme.json —— 一个文档，装着总开关、覆盖映射和自定义 CSS。它按顺序原子写入，所以拖动取色器不会撕裂文件。客户端还会把文档镜像到 localStorage，用于即时首屏渲染，也用于那些够不到主机的客户端（非回环页面）；对账时主机副本始终优先。

主机存储由共享 /api 通道上一条精确的 Fetch 路由 POST /api/dsh-theme-studio 提供。该通道的网关在请求到达处理器之前先施加 Host/Origin 防护和浏览器认证，处理器在写入前会重新校验每个字段：token 名必须是自定义属性，值有长度上限，不可用的条目会被丢弃而不是持久化。

目录结构

lib/index.js host half: the storage route (hand-written ESM)
lib/client.js generated lazy-CJS bundle the browser loads
src/client.js engine + editor UI (edit this)
src/catalog.js essentials, labels, groups, presets, snippets (edit this)
data/token-defaults.json token directory extracted from the installed design system
scripts/build-client.mjs inlines the catalog + defaults into lib/client.js, validates them
scripts/check-client.mjs offline checks: activation, override layer, every tab, the host route

src/ 是客户端那一半的真相来源；lib/client.js 是生成并提交的，这样插件无需构建步骤就能运行。

npm run build # regenerate lib/client.js (validates tokens, groups, presets and string keys)
npm run check # build --check + offline activation/render/route checks

渲染检查需要 ReactDOM，而随附的 web 客户端是打包它而不是安装它：

npm --prefix .devdeps install react@18.3.1 react-dom@18.3.1

没有它，npm run check 会跳过渲染断言并报告跳过。

字体真的会变吗？

会，而且这是从已安装的构建里读出来的消费链，不是猜的：

- 外壳样式表（@deepseek-ai/dsh-web-frontend/dist/assets/index-.css）开头是
body{font-family:var( --dsw-font-family, -apple-system, …) —— 整个界面的字体都来自那一个变量，所有没有自己 font-family 的东西都继承它。
- --dsw-font-family 还供给 ui-theme 里的对话文本阶梯（--dsw-font-markdown-base-font-family、--dsw-font-markdown-h1-font-family……也就是 h1–h6 和正文），还有输入框、侧边栏文档预览和代码块横幅。
- --ds-font-family-code 光在 shell 样式表里就有九个使用点，另外还有代码块、行内代码、JSON 树、web 块、diff 和编辑器。
- --dsw-font-family-brand 支撑欢迎页和品牌字标。

覆盖能触达所有这些地方，是因为 theme.overrideTokens 让 presenter 写入 body.style.setProperty('--dsw-font-family', …)：body 上的行内声明优先级高于样式表规则，所有后代都会继承它，而移除覆盖时又会撤回。

两点如实说明：本机没装的字体族会落到字体栈的下一个条目，另外少数组件把字体族硬编码在变量前面（ui-conversation 的计数和预览用的是 Inter, var(--dsw-font-family)），所以这些地方只要 Inter 存在就优先用 Inter。

正因为第一点，编辑器会用 canvas 度量逐个探测候选项，并标出本机没有的那些（「Roboto · not installed」），当前值以缺失字体族开头时还会在字段下方给出警告。全新安装的 Windows 只带精选列表里的 Segoe UI、Consolas 和 Microsoft YaHei；在那里选 Roboto 不会带来任何可见变化，这正是标记现在提前说明的事。

在界面旁边编辑

设置对话框会盖住窗口，所以在里面改的颜色看不到实际落点。编辑器工具栏里的 Open beside the interface 会关闭对话框，把同一个编辑器作为可移动面板显示在应用一角之上，这样拖动色块时对话仍然可见。该面板与设置页是同一个组件、同一个 store，所以两者永远不会不一致：用 ✕ 关闭，用 ▾ 折叠到标题栏，拖动标题栏移动，重新加载后它会回到你离开的位置——位置、折叠状态和打开标志按浏览器存在 localStorage，从不写进主题文档。

它注册到 shell.overlay，这是布局自带的浮动表面列表槽位：一个绝对定位的层，位于框架之上，其中的占用者自己管理几何形状并重新启用指针事件。面板关闭时它什么都不渲染，所以这一层保持干净。

右侧边栏的标签页 API（ctx.sidebarRightTabs.register 加上带键的 sidebar.right.pane.tab 视图席位）本可以让它变成停靠标签页而不是浮动面板。那条路需要一个实时客户端来验证：它涉及带键的会话作用域槽位，以及一个指南条目，其确切形状只有已发布的标签页包才有文档。

设计说明

- 没有以模块形式导入任何 Harness Client 包。控件在这里编写，用宿主自己的配方（switch、input、segmented control、settings row）来设定样式，只用 --dsw-alias-* token，所以 token 改名只会让外观降级，而不会破坏渲染。
- 每个字符串都走客户端 locale 服务；英文和俄文随 bundle 一起发布。
- 所有注册都归 ctx.effect 所有：卸载或重新加载插件时，会移除样式表、覆盖层、slot 注册和 store 订阅。
- 目录在加载时完成分区：essentials 是显式的，其余每个 token 都落到第一个匹配的分组，所以未来 harness 版本里新增的 token 仍然会出现在某个位置。
- 该区块包在错误边界里，所以将来出 bug 会就地报错，而不是让设置入口变成空白。React 的服务端渲染器从不查询边界，所以这是离线检查唯一覆盖不到的行为。
- 字体 slot 用 加自由文本字段，绝不用 ：浏览器会按字段当前文本过滤 datalist 选项，所以第一次选完之后，列表就只剩那一条，控件也就成了死路。

验证状态

npm run check 离线跑真实产物：bundle 通过 loader 的懒加载工厂加载，并针对一个替身客户端上下文激活；覆盖层按 scheme 逐一断言；每个标签页都在三种 store 状态下用 React 渲染；目录被证明对 token 目录的每个 token 恰好分区一次；宿主路由端到端跑通（信封校验、保存/加载/重置、清洗、在临时 DSH_HOME 下原子写入）。

它无法确认的是：套上你的主题之后页面长什么样。那需要跑起 GUI。