# DSH 个性化主题插件

[English](README.md) | **简体中文**

[![verify](https://github.com/SolvasHQ/dsh-theme/actions/workflows/verify.yml/badge.svg)](https://github.com/SolvasHQ/dsh-theme/actions/workflows/verify.yml)

为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) Web GUI 提供
主题配色、DIY 调色、字体与界面字号自定义，入口在侧边栏左下角的调色盘图标。

明暗双模：每套预设和每项 DIY 颜色都同时带浅色与深色两套值，因此原生外观在
浅色 / 深色 / 跟随系统之间切换时依然生效。

## 界面截图

| 中文界面 | 英文界面 |
|:---:|:---:|
| <img src="docs/screenshots/panel-zh.png" width="300" alt="中文个性化面板"> | <img src="docs/screenshots/panel-en.png" width="300" alt="英文个性化面板"> |
| <img src="docs/screenshots/panel-zh-custom.png" width="300" alt="中文自定义主题编辑器"> | <img src="docs/screenshots/panel-en-custom.png" width="300" alt="英文自定义主题编辑器"> |

**入口：侧边栏左下角的调色盘图标**——就是 Settings 按钮上方那一行图标。
点击即可在左下角弹出面板；同样的选项也在 **设置 → 个性化** 页面中。

界面文案跟随通用设置里的语言（简体中文 / English）。

## 功能

- **左下角入口**：侧边栏底部（Settings 按钮上方的图标行）新增调色盘图标，点击在
  左下角弹出紧凑面板。
- **设置页**：同样内容作为独立「个性化」页出现在 设置 中。
- **10 套主题配色**：默认（原生外观）、暖白、单色、克劳德、克劳德+、朱红、
  琥珀单色、粗暴极简、墨青、暗紫，另有「自定义」。
- **DIY 调色编辑器**：浅色/深色分开编辑——背景、卡片、弹层、侧栏、文字、边框，
  以及该模式自己的强调色；错误/成功/警告状态色共用；另有「加粗边框」开关
  （全局 1px 边框 + 墨色边框 token）。未手动指定的槽位会从背景/文字自动派生。
- **字体**：英文、中文、代码字体独立选择，作用于界面、对话与代码。
- **界面字号**：10–22px，走原生主题服务，重载后保留，并与 Ctrl/Cmd `+`/`-`
  快捷键同步。
- **中英双语**：跟随通用设置里的语言自动切换。
- **重启不丢失**：选择写入 DSH 的 Host 设置文档（volatile config），重启应用、
  更换本地端口后依然保留。

## 调色板参考

十套预设的浅色 / 深色配色对照：

![调色板参考图](research/preview.png)

## 安装

> 这是一个 **本地 DSH bundle**，不是 npm 包。安装方式是把克隆下来的目录链接进
> DSH profile 的 bundle 列表。运行需要 Node.js 20+ 与 pnpm。

1. 克隆仓库到固定位置：

   ```bash
   git clone https://github.com/SolvasHQ/dsh-theme.git
   cd dsh-theme
   ```

2. 安装插件自身的运行时依赖：

   ```bash
   pnpm install --prod
   ```

3. 在 DSH profile 中注册该 bundle。推荐让 DSH 的 Agent 用 Plugin Manager 的
   bundle 安装方式安装这个目录（传绝对路径）。也可以手动编辑
   `<profile>/package.json`：

   ```json
   {
     "dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "@local/dsh-personalization"] } },
     "dependencies": { "@local/dsh-personalization": "link:/绝对路径/dsh-personalization" }
   }
   ```

   然后在 profile 目录执行 `pnpm install` 并重启 DSH。

4. 打开 Web GUI：左下角出现调色盘图标；设置中也出现「个性化」页。

之后修改 `client.js` 会被 DSH 的客户端 HMR 在约一秒内热替换；修改 Host 侧代码
需要重启 DSH。

## 实现要点

- **主题覆盖层**：客户端用 `ctx.theme.overrideTokens('@local/dsh-personalization', tokens)`
  注册单一 token 覆盖层，每个 token 都是 `{ light, dark }` 对，因此叠加在原生
  配色之上，系统明暗切换无需重新注册主题。
- **token 生成**：每套配色/模式用 14 个锚点色生成约 97 个
  `--dsw-alias-*` / `--dsw-specific-*` 语义 token（表面、边框、文字、按钮、状态、
  Markdown/代码、diff、滚动条、toast、侧栏），并带对比度保护。
- **DIY 配色**：运行时从所选背景、边框、文字色与各模式强调色派生；改背景时未
  固定的槽位会自动跟随。
- **字体**：`--dsh-font-family-text` / `--dsh-font-family-code` 随 token 层下发，
  中英文字体栈自动拼接，未选的一侧回落到内置字体栈。
- **字号**：使用主题服务持久化的 `setFontSize('text', px)`。
- **持久化**：Host 半边在插件 entry 上声明一个 `.volatile()` 字符串字段，客户端
  通过 `ctx.configForms` 读写，DSH 会把它写入当前 profile 的 patch 并按浏览器
  身份持久化。明暗偏好与字号仍由原生主题设置管理。

## 开发

```bash
# 修改 src/client.template.js 或 research/palettes.json 后重新生成 client.js
node build/build-client.mjs
node --check client.js

# 静态检查（manifest、locale、图标、生成产物）
node tools/check-manifest.mjs

# 全量 token / 对比度检查（含 DIY 用例）
node tools/verify-tokens.mjs

# 面板组件功能测试（渲染 → 点击 → 断言，中英文）
node tools/check-panel.mjs
```

浏览器模块加载器不能 import 本地文件，因此
`build/build-client.mjs` 会把 `research/palettes.json` 内联进 `client.js`。
`client.js` 是提交进仓库的构建产物，CI 会重新构建并检查它是否最新。

## 目录结构

```
client.js                 浏览器端构建产物（提交）
index.js                  Host 半边：volatile 设置字段
cordis.patch.yml          bundle patch，插入插件行
locale/                   插件元数据（中/英）
src/client.template.js    客户端源码模板
build/build-client.mjs    构建脚本（palettes → client.js）
research/                 配色锚点、设计说明、调色板图
tools/                    manifest、token、面板验证脚本
```

## 兼容性

在 DeepSeek Harness 桌面版 `0.2.1-rc.2`（Web GUI）上验证。插件只使用公开的
客户端扩展点（`slots`、`theme`、`locale`、`configForms`）与 Host volatile
config，不修改 Harness 本身、不读取其他插件的 DOM。

## 许可证

MIT，见 [LICENSE](LICENSE)。

[更新日志](CHANGELOG.md) · [问题反馈](https://github.com/SolvasHQ/dsh-theme/issues)