# DSH 护眼主题插件

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

一款面向 DeepSeek Harness Web 的高度可自定义护眼主题插件。插件通过 DSH 官方 Theme Service 和公开的 `--dsw-*` 主题 Token 工作，不查询或修改产品 DOM，也不依赖产品内部 CSS 选择器。

> **关键词：** DeepSeek Harness · DSH · DeepSeek · Harness 插件 · Cordis 插件 · Web UI 主题 · 护眼配色 · 无障碍对比度

已在 DeepSeek Harness `0.1.0-rc.6` 上完成验证。

## 功能

- 内置 11 套协调完整的主题：4 套亮色和 7 套深色。
- 点击预设后立即切换，并在刷新页面后保留选择。
- 可以单独调整页面、表面层级、侧栏、输入区、文字、边界、状态色、Markdown、消息气泡和滚动条。
- 提供高级 JSON 编辑器，可覆盖任意公开的 `--dsw-*` Token。
- 支持启用、停用和重置自定义覆盖。
- 插件卸载时通过 Theme Service disposer 自动撤销主题覆盖。

## 快速安装与卸载

安装：

```sh
dsh plugin --profile web add "github:Cocowwy/dsh-plugin-eyecare-theme#v0.2.0"
```

卸载：

```sh
dsh plugin --profile web remove dsh-plugin-eyecare-theme
```

安装或卸载后，都需要重启当前 `dsh web` 进程并刷新页面。详细步骤见下方的[安装](#安装)和[卸载](#卸载)章节。

## 内置配色

| 亮色主题 | 深色主题 |
| --- | --- |
| 柔和亮色 | 柔和深色 |
| 霜白青 | 低蓝光深色 |
| 纸张灰 | 深海青 |
| 雾蓝 | 森林夜 |
|  | 午夜墨蓝 |
|  | 樱墨 |
|  | 石墨灰 |

每套主题都会统一协调以下视觉元素，而不是只替换页面背景：

- 页面基础背景和三级表面
- 侧栏、菜单和输入区域
- 主要、次要和弱化文字
- 常规边界和交互状态
- 品牌强调色
- 错误、警告和成功状态
- Markdown 代码块和行内代码
- 消息气泡和滚动条

## 环境要求

- 已安装 DeepSeek Harness，并使用 `web` profile。
- `dsh` 和 `pnpm` 可以通过 `PATH` 直接调用。
- 运行 DSH 的机器能够访问 GitHub。

可以分别检查：

```sh
dsh --version
pnpm --version
```

如果已安装 Node Corepack 但没有全局 `pnpm`，可先执行：

```sh
corepack enable
```

## 安装

### 安装最新版本

```sh
dsh plugin --profile web add "github:Cocowwy/dsh-plugin-eyecare-theme"
```

也可以使用完整 Git URL：

```sh
dsh plugin --profile web add "git+https://github.com/Cocowwy/dsh-plugin-eyecare-theme.git"
```

### 安装固定版本

为了让安装结果可复现，建议固定 Release 标签：

```sh
dsh plugin --profile web add "github:Cocowwy/dsh-plugin-eyecare-theme#v0.2.0"
```

安装完成后：

1. 停止当前运行中的 `dsh web` 进程。
2. 在工作目录中重新启动 `dsh web`。
3. 刷新原有 DSH Web 页面。
4. 打开 **Settings > 护眼主题**。

仅刷新浏览器不会重新加载 Web profile 的插件列表，首次安装后必须重启 `dsh web`。

## 升级

如果安装时没有固定标签或 Commit：

```sh
dsh plugin --profile web update dsh-plugin-eyecare-theme
```

升级后重启 `dsh web` 并刷新页面。

如果安装时固定了标签或 Commit，建议移除旧版本，再安装目标版本：

```sh
dsh plugin --profile web remove dsh-plugin-eyecare-theme
dsh plugin --profile web add "github:Cocowwy/dsh-plugin-eyecare-theme#v0.2.0"
```

## 卸载

### 1. 移除插件

使用插件的包名卸载：

```sh
dsh plugin --profile web remove dsh-plugin-eyecare-theme
```

### 2. 重启 DSH Web

停止当前运行中的 `dsh web`，重新启动后刷新页面。仅刷新浏览器不会重新加载 Web profile 的插件列表。

插件卸载后，Theme Service 覆盖层会自动撤销，DSH 将恢复自身主题。

### 3. 可选：彻底清理配色配置

浏览器中保存的配色选择默认不会删除，因此在相同 DSH 地址重新安装后，会恢复之前的配置。如果希望完全清理，请通过浏览器开发者工具删除以下 `localStorage` 项：

```text
dsh-plugin-eyecare-theme.config.v1
```

不删除该存储项不会继续影响已经卸载插件的 DSH 页面。

## 常用颜色调整

设置页中的常用颜色区域可以直接调整：

- 页面背景
- 一级、二级和浮层表面
- 侧栏和输入区域
- 主要、次要和弱化文字
- 常规边界
- 品牌强调色
- 错误、警告和成功状态
- 代码块背景
- 消息气泡
- 滚动条

颜色输入框支持常规 CSS 颜色值，例如：

```text
#1b1e1f
rgb(215, 220, 216)
rgba(209, 221, 214, 0.12)
```

## 高级 Token 覆盖

高级编辑器用于修改常用颜色区域没有直接展示的 DSH 主题 Token。它会在当前预设之上应用额外覆盖。

JSON 的 Key 必须以 `--dsw-` 开头，Value 必须是字符串：

```json
{
  "--dsw-alias-bg-base": "#1b1e1f",
  "--dsw-alias-label-primary": "rgb(215, 220, 216)",
  "--dsw-alias-border-l2": "rgba(209, 221, 214, 0.12)",
  "--dsw-alias-tooltip-bg": "#303634"
}
```

最终优先级为：

```text
DSH 内置主题 -> 当前插件预设 -> 高级 Token 覆盖
```

点击 **应用 JSON** 后生效。点击 **重置覆盖** 会删除高级覆盖和常用颜色的手动修改，但保留当前选中的预设。

## 配置存储

配置保存在当前网页 Origin 对应的浏览器 `localStorage` 中：

```text
dsh-plugin-eyecare-theme.config.v1
```

存储与以下因素绑定：

- 浏览器及浏览器用户目录
- 协议，例如 `http` 或 `https`
- 主机名，例如 `127.0.0.1` 或 `localhost`
- 端口，例如 `3080`

因此，从 `http://127.0.0.1:3080` 换到 `http://localhost:3080` 时，浏览器会将其视为不同的配置空间。

DSH `0.1.0-rc.6` 的 Host settings API 使用固定命名空间白名单，第三方插件无法公开自己的可写命名空间。因此本插件有意使用浏览器存储，而不是 Host settings API。

## 实现原理

Client 插件通过官方 Theme Service 调用：

```js
ctx.theme.overrideTokens('dsh-plugin-eyecare-theme', overrides)
```

插件只提交主题 Token 数据：

```text
用户选择主题
  -> 插件读取预设和自定义覆盖
  -> 调用 Theme Service
  -> DSH 发布新的 Theme Snapshot
  -> DSH 自身布局系统更新页面颜色
```

插件不会执行以下操作：

```js
document.querySelector(...)
document.body.style...
```

每次切换主题前，插件会先调用上一层覆盖的 disposer。插件停止或卸载时也会调用最终 disposer，从而完整恢复底层主题。

## 故障排查

### 设置中没有“护眼主题”

检查插件是否安装在 Web profile：

```sh
dsh plugin --profile web why dsh-plugin-eyecare-theme
```

如果能够查到插件，请重启 `dsh web` 并刷新页面。确认安装命令中使用了：

```text
--profile web
```

### 提示找不到 pnpm

确认 `pnpm` 已进入 `PATH`：

```sh
pnpm --version
```

如果使用 Corepack：

```sh
corepack enable
corepack pnpm --version
```

### Git 安装提示构建被阻止

按照 pnpm 输出的准确提示，在 Web profile 的 `pnpm-workspace.yaml` 中加入它要求的 `allowBuilds` 项，然后重新执行相同的安装命令。不要自行猜测包名。

本插件自身没有 build 或 prepare 脚本，但不同环境的依赖安全策略可能不同。

### 点击主题后没有变化

1. 刷新一次页面，确保浏览器加载的是最新插件脚本。
2. 打开 **Settings > 护眼主题**，确认“启用主题”已勾选。
3. 检查浏览器是否允许使用 `localStorage`。
4. 如果刚升级插件，请重启 `dsh web`。

### 刷新后主题选择丢失

确认页面仍使用相同 Origin，并检查浏览器隐私设置是否阻止 `localStorage`。

### 卸载后仍然看到旧主题

重启 `dsh web` 并刷新页面。只有在不希望以后恢复配置时，才需要删除 `dsh-plugin-eyecare-theme.config.v1`。

## 开源协议

MIT