tzy168/dsh-web-theme-packs

dsh-web-theme-packs

树外 Web 插件：把主题文件夹（颜色、附加 CSS、字体、图片）放入被扫描的目录后，插件通过 ThemeRuntime 注册它们，由现有 layout 呈现器应用 --dsw- token。可以同时放置多套主题包；设置 → 通用 → 主题包 负责切换。本包是独立 bundle，后续会迁到单独仓库，不属于随附的 dsh-web-app 名册。

Codex 那种替换窗口边框、图标集和布局的皮肤是另一种格式。DSH 主题包覆盖语义 token，并可在现有三栏 Web 客户端上附加 CSS／资源；它不能替换 React 图标组件，也不能重排栏目。

安装

在本仓库完成根目录 pnpm install 之后：

pnpm --filter dsh-web-theme-packs bundle
pnpm dsh plugin --profile web add ./dsh-web-theme-packs
pnpm dsh web

dsh plugin add 把该 bundle 记入 profile。移除：pnpm dsh plugin --profile web remove dsh-web-theme-packs。

主题包格式

每个主题包是一个含 theme.json 的目录。默认扫描根为本包的 themes/（随附示例）和 $DSH_HOME/theme-packs（首次加载时创建）。把新文件夹放入用户根目录即可；Host 监视该目录，浏览器会刷新目录清单。

theme.json：

{
"id": "aero-blue",
"name": "Aero Blue",
"description": "Optional one-line label",
"colorScheme": "light",
"tokens": {
"--dsw-alias-bg-base": "#c5e4f7",
"--dsw-alias-brand-primary": "#1a5f9e"
},
"css": "theme.css",
"preview": "preview.svg",
"fonts": [
{ "family": "PackSans", "file": "fonts/pack.woff2", "weight": 400 }
]
}

规则：

- id 匹配 ^[a-z][a-z0-9-]$，且不能是 light、dark 或 system。
- colorScheme 是基础调色板（body[data-ds-dark-theme]）。
- tokens 的键是 CSS 自定义属性，值是字符串。相对 url(...) 会被改写为 /dsh-theme-packs//...。
- css、preview 和字体 file 必须是包内相对路径（禁止 .. 与绝对路径）。缺失文件会跳过该包，其余包照常加载。
- 附加 CSS 可以针对 body[data-dsh-theme-pack=""]。其中的相对 url() 按同样规则改写。
- 主题包的 JSON 与 CSS 只作为数据；加载器不会执行包内的 JavaScript。

可用 Cordis 工具查看实时 token 目录（theme.exportInspectTokens），或阅读 design-platform.css。token 映射可以不完整；未给出的别名沿用内置样式表。

随附示例：themes/aero-blue（浅色光泽蓝）、themes/ink-night（深色海军蓝）和 themes/misty-forest（浅色雾林壁纸）。

配置

- id: web-theme-packs
name: dsh-web-theme-packs
config:
roots:
- !!js dshHomePath('theme-packs')
routePrefix: /dsh-theme-packs

roots 为空（默认）时，先扫描随附 themes/，再扫描 $DSH_HOME/theme-packs。后列出的根在 id 冲突时胜出。routePrefix 必须以 / 开头，不能是 /，也不能以 / 结尾。

Host 提供 GET {prefix}/catalog.json、GET {prefix}/events（SSE 修订流）、改写后的 {prefix}/{id}/theme.css 以及其他包内文件。当前选中的包 id 存在 theme-packs.active 设置段；外观中的浅色／深色／跟随系统会清空它。

模型体验

无；本插件管理浏览器偏好与静态资源，没有任何内容进入模型请求。

KV Cache 影响

无；该包既不组装也不发送提供方请求。

已知限制与暂缓事项

- 主题包只覆盖 token 和可选 CSS，不覆盖布局或图标组件。 Codex 那种重绘窗口边框与拟物图标的 QQ 2007 皮肤，在本客户端没有对应的资源映射。
- 第三方 token 集不做完整性校验。 不完整的覆盖会留下内置别名，可能造成调色板混用。
- 自定义包 id 不进入内置 ui-theme.preference schema。 选中包的持久化由本插件的 theme-packs.active 字段承担；移除本插件会丢掉该选择，但不会改写最后一次外观偏好。