dsh-mistblue

Readme

# Glassic Mist · 雾蓝主题（dsh-mistblue）

> DeepSeek Harness 的 **Glassic（玻璃 × 经典）雾蓝皮肤插件** —— 极浅雾蓝蒙版 + 实时流动的白色云雾动效 + 全弹窗毛玻璃质感。

以 Harness 默认日间皮肤为底，叠加一层**雾蓝蒙版**色调与**实时流动的白色云雾**；所有弹窗、菜单、面板统一获得**毛玻璃（高斯模糊）**质感。**不改系统默认皮肤、不压暗页面、不覆盖内容**——雾蓝只是浮在默认皮肤之上的一层「雾」。

[English overview](#english-overview) · [安装说明](#安装说明) · [设计批注](#设计批注)

---

## 介绍

`dsh-mistblue` 是一个纯客户端（浏览器端）的 DeepSeek Harness 主题插件：

- **蒙版式主题**：注册为 `mist-blue` 主题（浅色系），以默认皮肤为基底，不替换、不压暗
- **云雾动效**：白色云雾以 74s 周期缓慢漂移，`prefers-reduced-motion` 时自动停用
- **全弹窗毛玻璃**：菜单、上下文用量面板、Modal（含 Full access 确认框）、设置面板、HoverCard、Toast、Tooltip、cordis 插件界面、聊天输入框、代码块——按 ARIA 角色 + 类名双重覆盖，一处不漏
- **设置持久化开关**：设置 → 通用 →「雾蓝主题」，状态写入 `localStorage`，刷新/重启自动恢复
- **雾蓝浓度滑块**：设置行内置滑块（10%~100%），实时调节蒙版与云雾浓度，`localStorage` 持久化（键 `dsh-mistblue.intensity.v2`）；50% 为默认观感，100% 浓度翻倍
- **`/misttheme` 命令**：输入框输入 `/misttheme` 即可「开启 / 关闭」快速切换
- **作用域隔离**：全部自定义 CSS 以 `body[style*='--dsh-mistblue']` 限定，仅在雾蓝激活时生效；默认浅色/深色主题零影响
- **外挂兼容**：适配第三方插件（如 `dsh-reasoning-effort` 的开关与模型菜单）

## 特性一览

| 特性 | 说明 |
|---|---|
| 🌫️ 雾蓝蒙版 | 近白雾蓝底色 + 白色柔光斑，位于 `#root` 之下，不遮内容 |
| ☁️ 云雾动效 | 多层 radial-gradient 白色云雾，`translate3d + scale` 漂移（74s 往返） |
| 🧊 毛玻璃 | `backdrop-filter` 分档强度：输入框 20px / 上下文面板 24px / Modal 28px / 深色模块 16px |
| 🎛️ 设置开关 | 设置 → 通用 →「雾蓝主题」，`localStorage` 持久化（键 `dsh-mistblue.enabled`） |
| 🎚️ 浓度滑块 | 设置行内 10%~100% 实时调节；50% 默认、100% 浓度翻倍（蒙版 `saturate ×2`）；100ms 防抖无卡顿 |
| ⌨️ 快捷命令 | `/misttheme` →「开启雾蓝主题 / 关闭雾蓝主题」 |
| 🔒 零侵入 | 默认主题完全不受影响；关闭后不留任何自定义样式 |

## 安装说明

本插件作为 DeepSeek Harness **web profile 的 bundle** 挂载（客户端插件，仅浏览器端生效）。

### 方法 A：bundle 挂载（推荐）

1. 把本仓库放到 profile 的 `node_modules` 下：

   ```bash
   # 以 ~/.dsh/profiles/web 为例
   mkdir -p ~/.dsh/profiles/web/node_modules/dsh-mistblue
   cp -R <本仓库目录>/. ~/.dsh/profiles/web/node_modules/dsh-mistblue/
   ```

2. 在 profile 的 `package.json` 中注册 bundle 与依赖：

   ```json
   {
     "dsh": {
       "profile": {
         "bundles": ["...", "dsh-mistblue"]
       }
     },
     "dependencies": {
       "dsh-mistblue": "file:./node_modules/dsh-mistblue"
     }
   }
   ```

3. 重启 Harness（组合在启动时读取）。

`cordis.patch.yml` 会自动把 `mistblue` 行插入组合，无需手动编辑 cordis.yml。

### 启用主题

- **设置开关**：设置 → 通用 →「雾蓝主题」→「启用 雾蓝」（再点一次或选择默认主题即可关闭）
- **命令**：输入框输入 `/misttheme` → 选择「开启雾蓝主题 / 关闭雾蓝主题」
- **浓度调节**：拖动「雾蓝主题」行内的「雾蓝浓度」滑块（10%~100%），实时生效并持久化（键 `dsh-mistblue.intensity.v2`）；50% 为默认观感，100% 浓度翻倍
- 选择结果持久化在 `localStorage`（键 `dsh-mistblue.enabled`），下次启动自动恢复

## 设计批注

> 代码中的关键决策与原因，方便二次开发与审查。

### 1. 蒙版式而非替换式

主题不替换默认皮肤，而是注册为 `mist-blue`（`colorScheme: light`）并把整套视觉叠在默认皮肤之上。好处：默认浅色/深色主题完全不受影响，切换/关闭零残留（见 `src/client/index.js` 的 `TOKENS` 与 `CSS`）。

### 2. 作用域隔离

所有自定义 CSS 都以 `body[style*='--dsh-mistblue']` 开头——主题激活时框架会在 `body` 上写入该 style 标记，CSS 才生效；关闭后选择器失配，无任何样式残留。这是「零侵入」的关键实现。

### 3. 云雾动效的性能与可访问性

- `::after` 伪元素使用 `will-change: transform, opacity`，动画仅用 `translate3d + scale`（合成器友好），避免重排
- 动画周期 74s、漂移幅度 ≤2.4%，克制不抢戏
- `@media (prefers-reduced-motion: reduce)` 下动画关闭，尊重系统减弱动态效果偏好

### 4. 毛玻璃的分档强度

不同层级使用不同模糊档位（输入框 `blur(20px)` / 上下文面板 `blur(24px) saturate(1.25)` / Modal `blur(28px) saturate(1.3)` / 深色模块走 `--dsh-mistblue-glass-blur` 变量默认 `16px`），并全部带 `-webkit-` 前缀以兼容 Safari。

### 5. Safari 的已知例外

审批卡 / 问题卡（`.bqrRRG_card` 等）使用近不透明底 `rgba(248, 251, 254, 0.97)`——这是**有意为之**：Safari 的 `backdrop-filter` 与 `overflow: hidden` 组合会裁切子元素，半透明底会导致内容异常。可读性优先于「全透明」。

### 6. 持久化与启动恢复

开关状态写入 `localStorage`（键 `dsh-mistblue.enabled`），插件启动时读取并自动应用；`theme/change` 事件同步回写，保证设置行与真实主题状态一致。

### 7. 浓度滑块与实时覆盖

浓度滑块通过 `theme.overrideTokens("intensity", {...})` 实时覆盖 `--dsh-mistblue-veil-opacity` / `--dsh-mistblue-mist-opacity` / `--dsh-mistblue-veil-saturate` 三个私有令牌（动态包门面会自动把 source 替换为包 ID，重复调用替换同一层）。

- 档位映射：50% → 透明度 1 / 饱和 1（默认观感）；100% → 透明度 1 / 饱和 2（浓度翻倍）；低于 50% 按比例降透明度
- 开启雾蓝时叠加 +8% 增深，开关切换反馈更明显
- 拖动采用 100ms 防抖，避免频繁重算全量令牌造成卡顿；图层不带过渡动画
- 切回默认主题时覆盖层自动卸载，私有令牌随之清除，浅色/深色主题不受影响

### 8. 服务集成方式

插件注入 `slots`（设置行）、`theme`（主题注册/切换）、`commandUi`（/misttheme 命令）三个客户端服务：

- `slots.inject("settings.general.item", ...)` 在设置 → 通用下插入开关行（`order: 11`）
- `theme.register({ id: "mist-blue", ... })` 注册主题
- `commandUi.register(...)` 注册 `popupSelect` 类型的 `/misttheme` 命令

### 9. 第三方插件兼容

对 `dsh-reasoning-effort` 的开关（`.re-setting-switch`）做了雾蓝轨道适配（`.is-on` 态为 `rgb(58, 132, 216)` 蓝色），同类插件的开关样式可参考此模式扩展。

### 10. 构建管线

`src/` 是可读源码，`lib/` 是运行时产物：

- `scripts/build-client.mjs` 把 `src/client/index.js`（CommonJS 风格）包装为 `window.__ModuleLoader__.load({ id, factory })` 工厂，输出 `lib/client/index.js`
- `src/index.js`（host 空实现）直接复制为 `lib/index.js`，使包成为合法插件行，浏览器半区通过 `dsh.client` 清单解析

## 目录结构

```
dsh-glassic-mist-theme/
├── src/                      # 可读源代码
│   ├── index.js              # host 空实现（包为合法插件行）
│   └── client/index.js       # 客户端插件：令牌表 + 皮肤 CSS + 设置行 + 浓度滑块 + /misttheme 命令
├── scripts/build-client.mjs  # 构建脚本（src → lib）
├── lib/                      # 运行时产物（由构建生成）
│   ├── index.js
│   └── client/index.js       # window.__ModuleLoader__.load 包装
├── cordis.patch.yml          # bundle patch（插入插件行）
├── package.json
├── README.md
├── CHANGELOG.md
└── LICENSE
```

## 构建

```bash
npm run build   # 等价于 node scripts/build-client.mjs
```

## 自定义

全部视觉参数集中在 `src/client/index.js` 的 `TOKENS` 与 `CSS` 两个常量中：

- `TOKENS` —— 主题令牌（背景透明度、蒙版/云雾开关、毛玻璃强度、按钮与选中态配色）
- `CSS` —— 皮肤样式（蒙版渐变、云雾动画、各弹窗的 `backdrop-filter` 规则）
- 浓度档位映射在 `intensityParams()`，滑块范围在 `MistBlueRow` 的 `input[type=range]`

修改后运行 `npm run build` 并重启 Harness 生效。更多细节见上文的[设计批注](#设计批注)。

## 兼容性

- 目标平台：DeepSeek Harness Web 界面（浏览器端插件）
- 主题注册为浅色系 `mist-blue`；深色系统用户建议在浅色主题下使用
- 依赖 Harness 的 `dsh.client` 客户端清单机制（见 `package.json` 的 `dsh.client` 字段）

## English Overview

**Glassic Mist** is a client-side theme plugin for DeepSeek Harness. It overlays a mist-blue veil, drifting white-cloud animation, and frosted-glass (backdrop-filter) surfaces on top of the default light skin — without replacing or dimming it.

- **Mount**: copy the package into your profile's `node_modules` (e.g. `~/.dsh/profiles/web/node_modules/dsh-mistblue`), add `"dsh-mistblue": "file:./node_modules/dsh-mistblue"` and the bundle name to the profile `package.json`, then restart.
- **Toggle**: Settings → General → “雾蓝主题”, or type `/misttheme` in the input box.
- **Intensity**: drag the “雾蓝浓度” slider (10%~100%) in the settings row to tune the veil/cloud strength in real time (50% default, 100% doubles it).
- **Persistence**: `localStorage` keys `dsh-mistblue.enabled` and `dsh-mistblue.intensity.v2`.
- **Scope**: all custom CSS is guarded by `body[style*='--dsh-mistblue']`, so default light/dark themes are untouched.
- **Build**: `npm run build` (wraps `src/client/index.js` into `lib/client/index.js`).

## 许可证

[MIT](./LICENSE) © 2026 Vlan_Channel