# dsh-web-theme-packs

[English](README.md) | 中文

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

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

## 安装

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

```sh
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`：

```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/<id>/...`。
- `css`、`preview` 和字体 `file` 必须是包内相对路径（禁止 `..` 与绝对路径）。缺失文件会跳过该包，其余包照常加载。
- 附加 CSS 可以针对 `body[data-dsh-theme-pack="<id>"]`。其中的相对 `url()` 按同样规则改写。
- 主题包的 JSON 与 CSS 只作为数据；加载器不会执行包内的 JavaScript。

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

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

## 配置

```yaml
- 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` 字段承担；移除本插件会丢掉该选择，但不会改写最后一次外观偏好。