# 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/aurora
```

## Wiki

## 一句话定位
极光（Aurora）皮肤是 DSH Web GUI 的一款官方皮肤包，把默认界面替换为半透明毛玻璃风格：支持自定义本地或远端的背景图与视频，留空时回退到自带的极光渐变；同时附送一块替代默认推理等级列表的滑块面板。

## 核心能力
- 自定义背景：填入任意 http(s) 图片/视频 URL，或在设置里"选择文件…"上传本地文件
- 自动适配深浅主题：留空背景时分别渲染深色蓝紫极光渐变与浅色蓝紫极光渐变
- 调节透明度与模糊：背景层提供 0.1–1 的不透明度和 0–40px 的模糊滑块
- 视频背景：自动循环静音播放，支持 HTTP Range 流式加载（视频可拖动进度条）
- 毛玻璃面板：基于 aqua 机制，玻璃模糊与磨砂可由皮肤中心滑块调
- 推理等级滑块面板：点击官方模型菜单里的"推理等级/Effort"行，弹出替代默认列表的连续滑块面板

## 技术实现
- **语言**: TypeScript
- **关键依赖**: @deepseek-ai/cordis（插件运行时）、@deepseek-ai/dsh-client-runtime（客户端框架）、@deepseek-ai/dsh-client-ui-settings（设置集成）、@deepseek-ai/dsh-client-ui-settings-general（设置插槽）
- **架构模式**: 双半区插件——宿主半区通过 `ctx.inject(['webServer'])` 注册 `/api/skin-aurora/*` 路由负责配置读写与媒体存储；浏览器半区通过 `apply(ctx)` 挂 body 属性、背景层与事件联动；样式集中在 CSS Modules + token 覆盖，全部作用在 `body[data-dsh-aurora]` 作用域内
- **入口文件**: 宿主 `src/index.ts`，浏览器 `src/client/index.ts`，皮肤设置卡片 `src/client/AuroraCard.tsx`

## 适用场景
DSH Web GUI 的重度使用者，希望让聊天界面不再单调：用喜欢的壁纸、动图或视频做底，叠加半透明面板获得"毛玻璃"质感；同时希望在不离开界面的情况下，用滑块精细调节官方模型的推理等级。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DSH | >= 0.1.0-rc.6 | peerDependencies 显式声明使用此 SDK 版本 |
| Node | 未声明 | 源码未设置 engines |
| 平台 | 跨平台 | 未声明 os/cpu 限制 |
| 原生模块 | 无 | 仅使用 Node 内置的 fs/path/os/crypto |

## 安装方式
```bash
dsh plugin --profile web add github:CAPTAIN1275/dsh-ui-web/packages/skins/aurora
```

## 配置项
| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| enabled | 开关 | 是否启用极光皮肤整体效果；关闭后回到原生外观 | true |
| backgroundUrl | 字符串 | 背景图或视频的地址；可填 http(s) URL 或本地媒体路径，留空时使用内置极光渐变 | "" |
| opacity | 0.1–1 | 背景层的不透明度 | 0.8 |
| blur | 0–40 | 背景层的模糊半径（像素） | 0 |
| mediaType | image / video | 背景的媒体类型；按 URL 自动识别，也可手动选择视频 | image |
| muted | 开关 | 视频背景是否静音循环播放；取消勾选后视频带声音 | true |
| 玻璃模糊（blur） | 0–40 | 毛玻璃面板的模糊半径（皮肤中心滑块，写 localStorage） | 14 |
| 玻璃磨砂（frost） | 0–100 | 毛玻璃的磨砂程度（皮肤中心滑块，写 localStorage） | 50 |

## 常见问题
**Q: 安装后皮肤没有立即生效怎么办？**

A: 检查 DSH「设置 - 通用」里"极光皮肤（自定义背景图）"卡片的开关是否被关闭；若安装后界面仍是原生外观，刷新浏览器页面或重启 DSH 即可，配置会在 `~/.dsh/skin-aurora.json` 里持久化。

**Q: 视频能正常播放但进度条拖不动？**

A: 视频通过宿主 `/api/skin-aurora/media/<file>` 提供，并实现 HTTP Range 流式返回。如果进度条拖不动，多半是 DSH 主机被反向代理且代理吃掉了 `Range` 头，请确认代理透传 Range / Accept-Ranges。

**Q: 上传失败或媒体丢失如何排查？**

A: 服务端最大允许 200MB 请求体；图片会自动压缩到 1920 像素内再上传。媒体文件存放在 `DSH_HOME/skin-aurora-media/`（默认 `~/.dsh/skin-aurora-media/`）；卸载插件不会自动删除该目录，请手工清理。

**Q: "推理等级"面板打开后没有反应或不可用？**

A: 面板只拦截官方模型菜单里 label 为"推理等级 / Effort"的那一行；面板需要先通过 `sessions.models` 拿到当前会话的模型目录，加载完成前显示"模型目录加载中…"，加载完成后面板才会进入可用状态。

**Q: 配置会同步到云端或 DSH 官方设置桥吗？**

A: 不会。极光配置完全保存在宿主本地的 `~/.dsh/skin-aurora.json` 文件（绕开设置桥的命名空间白名单），换设备不会自动同步。

**Q: 如何彻底移除皮肤以及所有数据？**

A: 在 DSH 里移除插件后，手工删除 `~/.dsh/skin-aurora.json` 与 `~/.dsh/skin-aurora-media/` 目录即可；glass 的 blur/frost 数值存在浏览器 localStorage，可在开发者工具里清理 `dsh.ui-skin-aurora.*` 键。

## 上手难度
入门 — 安装即默认启用，配置项集中在设置卡片里，无需改任何代码；想自定义时再进入设置调整 URL、透明度、模糊与玻璃效果即可。

## 已知问题与限制
- 上传请求体上限 200MB（`src/index.ts:115-119`），大于此体积的本地视频无法上传，需自行托管 URL
- 玻璃模糊最大 40、磨砂最大 100，超过会被服务端钳制到上限（`src/client/aqua/theme-layer.ts:51-55`），超出值不会持久化生效
- 玻璃模糊/磨砂数值仅保存到浏览器 localStorage，不在多浏览器或多设备之间同步
- 侧边栏折叠状态通过 `localStorage['dsh.ui-skin-aurora.sidebar-collapsed']` 记忆，清缓存或隐私模式会丢失折叠记忆

---

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/aurora)
Wiki generated by AI (model: `MiniMax-M3`)