# dsh-ui-web

> 为 dsh web GUI 提供「鲸吟」深海主题皮肤：内嵌无文字海洋画作背景、冰蓝冷色系调色板、半透明面板，不影响模型请求与对话数据。

## Metadata

- Author: [@CAPTAIN1275](https://github.com/CAPTAIN1275)
- Repo: <https://github.com/CAPTAIN1275/dsh-ui-web.git>
- GitHub: [CAPTAIN1275/dsh-ui-web](https://github.com/CAPTAIN1275/dsh-ui-web)
- Stars: 34
- Language: TypeScript
- License: [Apache-2.0](https://spdx.org/licenses/Apache-2.0.html)
- Topics: `dsh-plugin`, `dsh-plugin-market`, `dsh-plugins`
- Forks: 2
- Open Issues: 0
- Last push: 2026-08-16T18:08:27.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:CAPTAIN1275/dsh-ui-web/packages/skins/whale-song
```

## Wiki

## 一句话定位
「鲸吟」是 dsh web GUI 的主题皮肤插件，延续「深海鲸语女神」概念图气质：把整个界面背景换成无文字的深海氛围画作，把 dsh 调色板重映射为冰蓝 / 浅青 / 深海军蓝 / 钴蓝冷色系加金色细线点缀。它只改变 DOM 外观，不影响模型请求和对话数据。

## 核心能力
- 在浏览器全视口挂载深海氛围画作背景图（1920×1080 WebP 内嵌为 base64，约 150KB）
- 把 dsh 主题色板重映射为冰蓝 / 浅青 / 深海军蓝 / 钴蓝冷色体系 + 金色细线点缀（亮 / 暗双套）
- 让主面板、侧边栏、菜单等大面积表面变为半透明，背景透光
- 注入官方 DeepSeek 蓝色鲸鱼 favicon（PNG，替换浏览器标签页图标）
- 跟随宿主基础主题实时切换亮 / 暗遮罩，无需重新挂载
- 关闭（dispose）时完整撤回：移除 body 属性、还原原背景图、断开观察器、移除注入的 favicon
- 暴露 `--dsw-skin-scrim` CSS 变量，皮肤中心可通过它实时调整遮罩浓度

## 技术实现
- **语言**: TypeScript + CSS Modules
- **关键依赖**: `@deepseek-ai/cordis`（仅类型导入，effect 生命周期）、`lightningcss`（CSS 编译）、`tsdown`（构建）
- **架构模式**: DSH 客户端半区插件；`apply(ctx)` 通过 `ctx.effect(...)` 注册 disposer，关闭时按 ThemePresenter 规范撤回所有写入；不注入任何 cordis 服务、不发事件；通过 `cordis.patch.yml` 在 bundle 层挂载 `ui-skin-whale-song` 行
- **入口文件**: `src/index.ts`（host 侧空壳）+ `src/client/index.ts`（核心逻辑，106 行）

## 适用场景
喜欢深海氛围和冰蓝冷色系的普通用户，把 dsh web GUI 换成更具个性的视觉风格。安装并激活后，整个界面背景变成无文字的深海氛围画作（蓝发女神与鲸群居左、冰蓝星座网格点缀、右侧大量留白），面板变成带磨砂感的半透明。适合日常长时间使用、希望界面安静不打扰、偏好冷色系视觉的人群。暗色形态可作为深海夜航版本使用。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DSH | >= 0.1.0-rc.6 | 仓库使用官方 NPM SDK 包（`@deepseek-ai/cordis@^4.0.1`），与 `@deepseek-ai/dsh@0.1.0-rc.6` 对齐 |
| Node | 未声明 | 包内和仓库根 `package.json` 均未设置 `engines` |
| 平台 | 跨平台 | 仅作用于 DSH web GUI 浏览器端；macOS / Windows / Linux 均可运行宿主 |
| 原生模块 | 无 | 纯浏览器端实现，无 Node 原生模块依赖 |

## 安装方式

```bash
dsh plugin --profile web add github:CAPTAIN1275/dsh-ui-web/packages/skins/whale-song
```

或者一次性装齐所有皮肤（推荐）：

```bash
dsh plugin --profile web add @captain1275/dsh-skins
```

安装完成后还需要激活：

```bash
dsh-skin use whale-song
```

## 配置项
本插件无需额外配置。`apply()` 内部通过 `ctx.effect(...)` 自动注册 disposer，无需用户手动维护生命周期。

如果想调整背景遮罩浓度，可通过皮肤中心写入 `--dsw-skin-scrim`（0–1，0 即关闭遮罩、显示原图），皮肤本身不需要任何配置字段。

## 常见问题

**Q: 这个皮肤影响我的对话记录和模型请求吗？**

A: 不影响。它只修改浏览器 DOM（背景图、面板颜色、favicon），不注入任何 cordis 服务、不发请求、不触碰模型 API，也不会修改 KV Cache 行为。

**Q: 一次能同时启用多个皮肤吗？**

A: 不能。同一时刻只激活一个皮肤，切换时新皮肤接管、旧皮肤完整卸载；切换用 `dsh-skin use whale-song`。

**Q: 关闭后会留下痕迹吗？**

A: 不会。effect disposer 会撤回它写入的所有内容：移除 body 属性、还原原背景图、断开 MutationObserver、移除注入的 favicon，原页面样式完整恢复。

**Q: 装了之后界面没变是为什么？**

A: 仅安装到 profile 不等于已激活。还需要执行 `dsh-skin use whale-song` 才会套用该皮肤。

**Q: 第一次安装需要先本地构建吗？**

A: 不需要。通过 git 链接安装时 `prepare` 脚本会自动构建 `lib/`；但 pnpm ≥10 首次安装 git 依赖可能需要把打印的包键加入 `pnpm-workspace.yaml` 的 `allowBuilds` 列表再重试。

**Q: 支持深色模式吗？**

A: 支持。皮肤会跟随宿主基础主题切换：深色模式下遮罩换成深海军蓝纱幕，主题色板同时切换为夜航版配色（CSS 中以 `body[data-dsh-whale-song][data-ds-dark-theme]` 选择器分别定义）。

**Q: 跟其它皮肤比有什么不一样？**

A: 这个皮肤的核心是无文字深海氛围画作 + 冰蓝冷色系 + 金线点缀；同仓库还有 blue-fantasy（鲸鱼娘插画 + 靛蓝）、aurora（极光）等其它主题可选。

## 上手难度
入门 — 一条命令安装、一条命令激活，没有任何配置项，普通用户即可上手。

## 已知问题与限制
- 同一时刻只能激活一个皮肤；切换会完全卸载当前皮肤
- 故意不使用 `backdrop-filter` 模糊祖先元素：会破坏 fixed 定位覆盖层（如设置面板）的包含块，使其被锁在父容器内
- 深海氛围画作为内嵌 base64（约 150KB），会增加少量 bundle 体积
- 遮罩透明度通过 `--dsw-skin-scrim` CSS 变量控制，需要皮肤中心或自定义控件才能动态调整
- 当前源码内未发现 TODO / FIXME / HACK 等显式已知问题

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-ui-web](https://deepseek-plugin.org/plugins/CAPTAIN1275/dsh-ui-web/packages/skins/whale-song)
Wiki generated by AI (model: `MiniMax-M3`)