dsh-x9-theme

Readme

# dsh-x9-theme

[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) WebUI 主题插件（bundle 包，走官方插件机制安装，不修改任何 DSH 源码、无需构建前端）。

在设置面板中新增一个带**调色板图标**的 **"主题"** 分区，提供预设风格、明暗模式、分区独立样式（毛玻璃 / 浮雕 / 霓虹……）、背景图片（本地上传 / 本地路径 / URL / 内置渐变与风格层）、四区透明度、**分区自定义 CSS（免 F12 显示当前样式）**、字体、阴影、动效等全套外观定制，全部实时生效并自动持久化。

> 版本：9.3.0 · 纯 JavaScript，无构建步骤
>
> A theme plugin for the DeepSeek Harness Web UI — presets, per-area styles, background images, four-zone translucency, per-area custom CSS, fonts and motion, all persisted to a portable `config.json`.



## 安装

前置要求：已安装 DeepSeek Harness。插件命令随安装方式不同而不同：

- **npm 全局安装**：命令为 `dsh`
- **源码安装**：在仓库根目录用 pnpm 启动，命令为 `pnpm dsh`

```powershell
# 方式一：本地目录安装
dsh plugin --profile web add ./dsh-x9-theme          # npm 安装
pnpm dsh plugin --profile web add ./dsh-x9-theme     # 源码安装

# 方式二：从 GitHub 安装
dsh plugin --profile web add github:X9wd09ncc/dsh-x9-theme          # npm 安装
pnpm dsh plugin --profile web add github:X9wd09ncc/dsh-x9-theme     # 源码安装
```

然后**重启服务**，并在浏览器里**按 Ctrl+F5 强制刷新**页面：

```powershell
dsh web          # npm 安装
pnpm dsh web     # 源码安装
```

> `dsh plugin add` 会把本包加入 profile 的 bundles 层（`package.json` 声明了 `dsh.bundle.patch`
> 自动插入 `ui-x9-theme` 行），并以符号链接方式安装——直接改本仓库文件、重启服务即可生效，无需重复安装。

## 更新

```powershell
# 重新执行 add 即为更新（npm 安装）
dsh plugin --profile web add github:X9wd09ncc/dsh-x9-theme
```

改 `lib/client.js`（浏览器半边）后**只需刷新页面**；改 `lib/index.js`（Host 路由）后需重启服务。

## 卸载

```powershell
dsh plugin --profile web remove dsh-x9-theme
# 重启服务后恢复默认外观；删除插件目录下的 config.json 即彻底清除个人配置
```



## 截图

| 主题面板 | 背景与分区样式 |
| --- | --- |
| ![主题面板](/assets/screenshots/settings-theme.png) | ![背景与分区样式](/assets/screenshots/background.png) |

## 功能特性

- **可折叠设置分区**：每组标题带 ▲/▼ 折叠箭头；预览卡吸顶常驻，改动即见
- **风格预设**：极光 Aurora / 午夜 Midnight / 樱花 Sakura / 森林 Forest / 琥珀 Amber / 石墨 Mono + 默认，每套覆盖 40+ 设计 token（浅色/深色双值）
- **明暗模式**：跟随系统 / 浅色 / 深色（官方 `theme.setTheme`，持久保存）
- **分区独立样式**：

  | 分区 | 可选样式 |
  | --- | --- |
  | 侧边栏 | 默认 / 毛玻璃 / 渐变 / 无底色极简 / 霓虹描边 / 斜纹 |
  | 输入框 | 默认 / 浮雕 / 描边 / 发光 / 毛玻璃 / 渐变 / 霓虹 / 极简无边框 |
  | 对话气泡（用户消息） | 默认圆角 / 毛玻璃 / 描边 / 方角扁平 / 渐变 / 霓虹 / 柔和阴影 |
  | 对话框（AI 输出） | 默认无底 / 卡片 / 毛玻璃 / 描边卡片 / 霓虹卡片 |
  | 页面背景 | 默认 / 赛博网格 / 流光渐变 / 噪点纹理 / 落日 / 深海 / 薄荷 / 糖果 / 星空 |

- **背景图片**：
  - 统一"图片地址"字段：本地路径 / 插件资源 `/x9-theme/asset/` / `https://` 外链 / `data:` URI 智能分流
  - **本地上传**（存入插件 `assets/` 目录，重启不丢；单个上限 20 MB）
  - 本地文件路径直接读取（扩展名白名单 `jpg/jpeg/png/gif/webp/avif/svg/bmp`，不超过 8 MiB）
  - 4 种内置渐变；铺满 / 完整 / 原始 / 平铺、位置、模糊（0–20px）、不透明度、暗色遮罩
  - 输入地址后**真实探测并提示** ✓ 已加载 / ✗ 失败（提示显示在输入框正下方）
- **四区透明度滑块**：主区 / 侧边栏 / 卡片浮层 / 输入区各自独立调节（0%–100%，0 = 完全透明）；启用背景后自动调到参考值（55% / 60% / 85% / 85%）让背景透出，手动拖动后以手动值为准
- **分区自定义 CSS（免 F12）**：侧边栏 / 输入框 / 用户气泡 / AI 输出 / 页面背景各自独立编辑器；
  打开即显示该区域**当前页面实际样式**（自动读取计算值并格式化成 CSS，可直接复制修改），
  选择器模板随占位提示给出；输入即生效、与预设同优先级时以自定义为准；清空即恢复；随 `config.json` 分享
- **字体**：界面字体下拉（霞鹜文楷 / 思源宋体 / 鸿蒙黑体 / 微软雅黑 / 衬线经典）+ 自定义栈；
  代码字体下拉（JetBrains Mono / Fira Code / Cascadia Code / Consolas / SF Mono）+ 自定义栈；字号缩放 85%–120%
- **配色**：强调色浅色/深色分设（✕ 一键恢复跟随预设）
- **动效与阴影**：动画速度 25%–150%、阴影强度 0–200%（0 = 扁平）
- **持久化与分享**：所有设置自动写入插件目录 `config.json`（本地路径经 `import.meta.url` 定位，与宿主设置白名单无关）；
  面板"高级"区提供配置 JSON 导出 / 复制 / 导入 / 一键重置——把 `config.json` 发给别人即可复刻整套主题

## 使用指南

设置 → **主题**（调色板图标）。所有控件改动即生效、自动保存，顶部预览卡实时预览配色与背景。

### 分区自定义 CSS 示例

每个分区底部有折叠的"自定义 CSS"编辑器，打开后上半部分是**当前实际样式**（页面计算值，可复制修改），下半部分直接填写：

```css
/* 侧边栏：圆角 + 半透明毛玻璃 */
.pI_x6G_sidebarCol {
  border-radius: 0 20px 20px 0;
}
.hHd-Xa_root {
  background: rgba(255, 255, 255, 0.6);
}

/* 用户气泡：强调色发光 */
.gdEzaW_bubble {
  box-shadow: 0 0 12px var(--x9-accent-soft);
}

/* 输入框：更圆润 */
.uV2eYG_card {
  border-radius: 24px;
}
```

支持 `--dsw-*` 主题变量与本插件变量（如 `--x9-accent-soft`）；清空对应编辑框即恢复预设。

### 背景风格层说明

赛博网格、星空等 8 种**背景风格层均为深色底**：选择后自动切换深色模式保证文字可读；切回"默认（纯色/图片）"时恢复你选择的明暗模式。

## 目录结构

```
dsh-x9-theme/
├── package.json        # dsh.bundle + dsh.client 声明（v9.3.0）
├── cordis.patch.yml    # 组合层：插入 ui-x9-theme 行
├── lib/
│   ├── index.js        # Host 半边：/x9-theme 路由（config / asset / upload / bg）
│   └── client.js       # 浏览器半边：主题引擎 + 设置页
├── assets/
│   ├── screenshots/    # README 截图
│   └── (本地运行时)     # 上传的背景图片也存于此目录，默认不随仓库分发
├── config.json         # 运行时生成：个人配置持久化（已 gitignore，可复制给他人导入）
├── LICENSE
└── README.md
```

> 仓库不附带默认背景图（避免分发版权不明的图片）。安装后在主题面板"背景 → 选择图片文件"上传即可（存入本地 `assets/`，重启不丢）；也可自己放一张图进 `assets/`，再在"图片地址"填 `/x9-theme/asset/<文件名>`。

## config.json 字段（节选）

配置自动生成，无需手写；分享时直接复制整个文件，对方在"高级 → 导入配置"粘贴即可：

| 字段 | 含义 |
| --- | --- |
| `presetId` / `scheme` | 预设风格（`none` 或预设 id）/ 明暗模式（`system`/`light`/`dark`） |
| `accentL` / `accentD` | 强调色（浅色/深色），空 = 跟随预设 |
| `sidebarStyle` / `inputStyle` / `bubbleStyle` / `aiStyle` | 四分区样式 |
| `bgStyle` | 背景风格层（`default`/`cyber`/`aurora`/`noise`/`sunset`/`ocean`/`mint`/`candy`/`galaxy`） |
| `bgMode` / `bgUrl` | 背景来源（`none`/`g1`–`g4`/`url`）与图片地址 |
| `bgSize` / `bgPos` / `bgBlur` / `bgOpacity` / `bgTint` | 背景显示方式 / 位置 / 模糊 / 不透明度 / 遮罩浓度 |
| `opacityMain` / `opacitySidebar` / `opacityCard` / `opacityInput` + `glassAuto` | 四区透明度与自动参考值开关 |
| `fontFamily` / `codeFont` / `fontScale` | 界面字体栈 / 代码字体栈 / 字号缩放 |
| `shadowScale` / `motionScale` | 阴影强度 / 动画速度 |
| `cssSidebar` / `cssInput` / `cssBubble` / `cssAi` / `cssBg` | 分区自定义 CSS（旧版 `customCss` 全局字段仍兼容生效） |

## HTTP 端点（Host 半边）

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET / POST | `/x9-theme/config` | 读取 / 校验并保存 `config.json`（无则返回 `{}`） |
| GET | `/x9-theme/asset/<file>` | 伺服 `assets/` 下图片（路径穿越防护） |
| POST | `/x9-theme/upload` | 上传 data URI 图片 → `assets/`（不超过 25 MiB），返回 `{ url }` |
| GET | `/x9-theme/bg?p=<路径>` | 按本地路径伺服图片（扩展名白名单，不超过 8 MiB） |

## 常见问题

**Q：安装并重启后，设置里没有"主题"分区？**
页面的客户端插件清单只在**整页加载**时获取，服务器重启后的自动重连不会更新它。请按 **Ctrl+F5** 或关闭标签页重新打开页面。（"插件"列表里能看到本插件是实时查询服务器的结果，不代表页面已加载它。）

**Q：升级 DSH 后某个分区样式失效了？**
分区样式依赖少量产品 CSS 类名（如 `.pI_x6G_sidebarCol`、`.uV2eYG_card`），DSH 大版本升级后哈希类名可能变化。打开对应分区的"自定义 CSS"编辑器，顶部"当前实际样式"里显示的就是新选择器，参照它即可适配；也欢迎提 Issue。

**Q：本地路径背景不显示？**
检查扩展名是否在白名单（jpg/jpeg/png/gif/webp/avif/svg/bmp）且文件不超过 8 MiB。图片地址框下方会实时显示 ✓/✗ 探测结果；上传到插件 `assets/` 的图片不受此限制。

**Q：背景太淡 / 太浓 / 看不清？**
调节"四区透明度"（主区 55% / 侧边栏 60% / 卡片 85% / 输入 85% 为参考值）与背景分区的"不透明度""遮罩浓度"；背景风格层会自动切深色模式保证可读。

**Q：第三方插件的样式怎么改（例如 better-sidebar）？**
在任意分区的"自定义 CSS"里写它的选择器即可（属性选择器同样有效，如 `[data-dsh-better-sidebar] { ... }`）。本插件会把自定义 CSS 自动保持在样式表末尾，级联顺序优于后注入的第三方样式；个别插件用了更高优先级写法时，加 `!important` 即可。

**Q：背景图在第三方侧边栏里"出现两份"？**
9.3 起整个页面只有**一层视口级背景**（`html body::before`），所有区域（含第三方面板）看到的是同一张连续背景。若某个第三方面板开了 `backdrop-filter` 毛玻璃，会把背后的背景重新采样，看起来像第二张图——在"自定义 CSS"里写 `[data-dsh-better-sidebar] { backdrop-filter: none !important; }` 即可恢复连续背景。

**Q：改配置后明暗模式被重置回"跟随系统"？**
9.3 已修复：明暗模式只在主题面板里显式切换时生效（或按背景风格层自动切换），不会再因为编辑 CSS 等普通改动被强制重置。

**Q：配置想恢复默认？**
面板"高级 → 重置全部"，或删除插件目录下的 `config.json` 后刷新页面。

## 开发

- 纯 JavaScript，无构建步骤；`node --check lib/client.js` 可做语法自检
- 安装方式为符号链接（`link:`），直接改源码目录即可；`lib/client.js` 改动刷新页面生效，`lib/index.js` 改动需重启服务
- 分区样式选择器集中在 `lib/client.js` 的 `effectsCss()`；"自定义 CSS"编辑器会动态展示页面上的真实选择器，便于适配
- 设置导航"主题"分区的调色板图标按导航第 2 项定位（`.VOzbGW_navCell:nth-of-type(2)`）；如有其他插件以更小 `order` 插入设置分区，需相应调整该序号
- README 截图放 `assets/screenshots/`，界面大改后替换同名文件

## License

[MIT](LICENSE)