@qipenglin/dsh-theme-spectrum

Readme

# @qipenglin/dsh-theme-spectrum

中文 | [English](README.en.md)

Spectrum 是一个可独立安装的 DeepSeek Harness Web 主题插件。它提供十套配色预设，每套均有浅色与深色方案，同时保留 DSH 内置的浅色、深色和跟随系统设置。

## 安装

```sh
dsh plugin --profile web add github:qipenglin/dsh-theme-spectrum
```

该命令直接从 GitHub 仓库的默认分支安装插件。仓库已包含经过验证的 `lib` 产物，安装过程无需执行构建脚本。安装后重启 Web Profile，Spectrum 会出现在「设置 → 通用 → 主题风格」。

### 供应链发布时间检查

每次增删插件时，DSH 都会让 pnpm 校验整个 Web Profile。GitHub 来源本身不依赖 registry 发布时间，但某个已经安装且发布时间短于当前 `minimumReleaseAge` 的依赖仍可能让整次安装失败。请先核对错误中点名的包；可以等待它达到规定时长，也可以仅对一次已审计的重试命令临时关闭发布时间门槛：

```sh
env PNPM_CONFIG_MINIMUM_RELEASE_AGE=0 \
  dsh plugin --profile web add github:qipenglin/dsh-theme-spectrum
```

这个环境变量不会写入持久配置。失败的 add 可能在 DSH 回滚 Profile manifest 后，仍在 `pnpm-lock.yaml` 或 `node_modules` 中留下 Git 来源记录；随后用同一个 add 命令成功重试即可收敛该半安装状态。命令最终成功退出时，peer dependency 警告只是提示信息。

## 主题预设

| Id | 名称 | 风格 |
|---|---|---|
| `graphite` | 石墨 | 中性、专注 |
| `tide` | 澄海 | 冷蓝、专业 |
| `pine` | 松雾 | 安静的自然绿 |
| `dune` | 暖砂 | 温暖的编辑风格中性色 |
| `vesper` | 暮紫 | 精致、受控的紫色 |
| `signal` | 信号 | 工业灰与朱红 |
| `brass` | 黄铜 | 冷调仪器灰与古金 |
| `cobalt` | 钴蓝 | 建筑感长春花蓝与正蓝 |
| `rosewood` | 玫木 | 灰粉与酒红 |
| `volt` | 电光 | 实验性黄绿与青柠 |

石墨是默认预设。预设选择与 `ui-theme.preference` 相互独立，因此十套预设可分别搭配浅色、深色或跟随系统，共三十种有效组合。Spectrum 只改变颜色；布局、排版、间距、密度、圆角和动效仍由 DSH 负责。

## 扩展窗口主题变量

普通 DOM、挂载在 `body` 下的 Portal，以及主动消费继承变量的 Shadow DOM 内容，都会自动跟随 Spectrum，且不受插件挂载顺序影响。扩展插件作者可使用以下稳定变量：

| 变量 | 用途 |
|---|---|
| `--dsh-theme-spectrum-surface` | 窗口或面板背景 |
| `--dsh-theme-spectrum-surface-raised` | 卡片或工具栏背景 |
| `--dsh-theme-spectrum-surface-overlay` | 菜单或浮动表面 |
| `--dsh-theme-spectrum-border` | 普通边框 |
| `--dsh-theme-spectrum-border-strong` | 高对比分隔线 |
| `--dsh-theme-spectrum-text` | 主要文字 |
| `--dsh-theme-spectrum-text-muted` | 次要文字 |
| `--dsh-theme-spectrum-accent` | 主要操作或强调色 |
| `--dsh-theme-spectrum-accent-contrast` | 强调色上的内容 |
| `--dsh-theme-spectrum-focus-ring` | 键盘焦点指示 |
| `--dsh-theme-spectrum-hover` | 悬停背景 |
| `--dsh-theme-spectrum-active` | 激活背景 |
| `--dsh-theme-spectrum-code-surface` | 文件与代码背景 |
| `--dsh-theme-spectrum-terminal-surface` | 终端容器背景 |
| `--dsh-theme-spectrum-selection` | 辅助选中背景 |
| `--dsh-theme-spectrum-success` | 成功状态 |
| `--dsh-theme-spectrum-warning` | 警告状态 |
| `--dsh-theme-spectrum-error` | 错误状态 |

选中颜色不能作为唯一的选中信号；应同时提供描边、图标、勾选或等价的非颜色提示。终端变量只覆盖容器。xterm、Monaco、canvas、iframe、硬编码颜色和封闭 Shadow DOM 必须由所属插件配合，无法由全局主题安全重染。

Spectrum 还为当前 DSH Feature 样式、`dshmarket@1.11.3` 和 `@deepseek-ai/dsh-profile-plugin-manager@0.1.0-rc.5` 提供少量有证据的兼容别名。它不会扫描 DOM、监听 DOM 变更、定位 CSS Module 哈希类，也不会应用全局 `!important` 规则。

## 配置

```yaml
ui-theme:
  preference: system
ui-theme-presets:
  preset: graphite
```

Host 面注册设置 schema，并在 Client 树加载前注入浅色与深色两套变量。Client 面贡献一层可撤销的 `ctx.theme.overrideTokens()` 和一个「通用」设置行。插件释放时会移除引导样式、主题覆盖、语言字典、设置订阅和设置行。

## 兼容策略

DSH peer dependency 刻意不设置版本上限。当前版本的开发锁文件已在官方 DSH `0.1.1-rc.2` 上验证；DSH 出现破坏性变化时，由后续 Spectrum 版本适配。安装归档验收会在测试输出中记录实际 DSH 版本，不会回写并改变已经验收的归档。

## 开发

```sh
pnpm install --frozen-lockfile
pnpm run typecheck
pnpm run lint
pnpm run test
pnpm run build
pnpm run pack:check
```

`pnpm run pack:check` 会清空并重建 `dist/`，其中只保留已校验的 `dist/qipenglin-dsh-theme-spectrum-0.1.3.tgz`。

`pnpm run test:installed` 是显式启用的默认 home 验收，不属于普通检查，且不会发布或推送代码。

## 已知限制

- 预设目录固定，没有 token 编辑器或预设导入格式。
- 选择对浏览器 profile 全局生效，不支持按工作区或会话设置。
- 非回环浏览器遵循 DSH SettingsScope 的内存策略。
- 无法保证未知第三方硬编码 UI 自动跟随主题。

## 许可证

本项目采用 [MIT License](LICENSE)。