dsh-client-ui-theme-manager

Readme

# dsh-client-ui-theme-manager

给 **DeepSeek Harness Web** 用的**可视化换肤插件**。装好后在 **设置 → Dream Skin 换肤** 里：
点击主题卡片即换肤，刷新页面不丢失、不闪官方浅色；支持创建/导入(zip)/导出主题、
背景图、暂停换肤——全部在浏览器内完成，**无需命令行、无需重启 dsh**。

> 主题无关：内置 10 套风格 + 任意自定义配色；导入兼容 DreamSkin 主题包（.zip）。
<img width="1279" height="589" alt="image" src="https://github.com/user-attachments/assets/9e247e59-c333-41f2-9ded-d37998d86512" />
## ✨ 功能

| 功能 | 说明 |
|---|---|
| 🎨 内置 10 套主题 | 财神金 / 深空红 / 米金白 / 极夜蓝 / 青竹绿 / 樱花粉 / 薄荷苏打 / 紫晶 / 柠檬汽水 / 石墨灰 |
| 🎛️ 创建主题 | 填主题名 + 深/浅外观 + 配色（颜色已预填默认值，只改背景色也能出主题） |
| 📦 导入主题 | **直接选 .zip（DreamSkin 主题包，浏览器原生解压）或 theme.json**，导入即应用 |
| 📤 导出主题 | 下载当前主题的 `theme.json`（含背景图时一并下载） |
| 🖼️ 背景图 | 给主题配背景图（自动压缩 ≤1600px）+ 文字遮罩（安全区左/右）+ 实时预览；无图时自动生成主题色渐变背景 |
| ⏸️ 暂停 / 继续 | 暂停 = 回到官方外观但保留记忆；继续 = 恢复上次选择 |
| 🔄 还原官方 | 跟随系统 + 清除记忆 |
| 🩺 轻量体检 | 背景挂载类名失效时状态条会提示（dsh 升级后可能出现） |
| ⚡ 零闪烁 | 刷新/重开页面主题即时生效，全程不出现官方浅色 |
|  主题社区|https://dreamskin.cc/gallery|

<img width="1141" height="888" alt="image" src="https://github.com/user-attachments/assets/86617fdf-b0a9-4da5-a33b-f53ba4151793" />

## 📦 安装

### 方式 A · 原生插件（dsh 插件管理）

插件以 npm 包发布后：

```powershell
dsh plugin --profile web add dsh-client-ui-theme-manager
```

装完重启 dsh web + Ctrl+F5。插件会出现在 dsh 的插件管理/设置里。

> 原生方式通过包内的 `cordis.patch.yml`（`dsh.bundle`）注册客户端入口；
> 但它**不注入首帧引导样式**，加载瞬间可能闪一下官方浅色（约 0-8ms）。
> 想要完全零闪烁请看方式 B。

### 方式 B · zip 一键安装（推荐，含零闪烁首帧引导）

1. 从 **Release 页面** 下载最新版压缩包（如 `dsh-client-ui-theme-manager-1.4.0.zip`），解压到任意目录；
2. 在该目录里运行（右键 → 用 PowerShell 运行，或命令行执行）：
   ```powershell
   powershell -ExecutionPolicy RemoteSigned -File .\install.ps1
   ```
3. **重启 dsh web**（关掉正在跑的 dsh 进程重新启动），然后浏览器 **Ctrl+F5** 硬刷新。

打开 **设置 → Dream Skin 换肤** 即可开始换肤。

> ⚠️ 两种方式**二选一**，不要混用（会产生重复入口）。若曾用方式 A，先
> `dsh plugin --profile web rm dsh-client-ui-theme-manager` 再用方式 B；反之先跑方式 B 的卸载。

### 卸载

```powershell
# 方式 A（原生）：
dsh plugin --profile web rm dsh-client-ui-theme-manager
# 方式 B（zip）：
powershell -ExecutionPolicy RemoteSigned -File .\install.ps1 -Uninstall
```

然后重启 dsh web + Ctrl+F5。

## ✅ 兼容性

- **dsh**：0.1.0-rc.6（基于 `~/.dsh/profiles/web` 的 profile 结构）
- **浏览器**：Chrome / Edge 111+（zip 导入需要原生 `DecompressionStream`；更老的浏览器请先解压 zip 取 theme.json）
- **系统**：Windows / macOS / Linux（脚本为 PowerShell，Windows 直接可用；其他平台手动执行等价步骤）

## 🧩 工作原理

这是一个标准的 dsh **客户端插件**（`dsh.client` 双面包）：

- `lib/index.js` —— 宿主半（no-op，让 Loader 有可激活的入口）
- `lib/client.js` —— 浏览器半，按 `window.__ModuleLoader__.load` 协议注册：
  1. 向官方 theme 服务注册主题（`--dsw-alias-*` token 派生）
  2. 在设置面板注册「Dream Skin 换肤」页面
  3. **持久 `<style>` 标签（`!important`）写入 token + 背景 + 明暗信号**——官方主题管线无法清除，刷新/重开页面主题恒在，零闪烁
  4. 自定义主题 / 背景图 / 状态存在浏览器 localStorage

只依赖 dsh 平台种子模块（`react`、`react/jsx-runtime`、`dsh-client-web-react`），**无任何 npm 依赖**。

`install.ps1` 只做三件事（全部幂等、UTF-8 无 BOM）：

1. 复制插件到 `~/.dsh/profiles/web/node_modules/dsh-client-ui-theme-manager/`
2. 在 `~/.dsh/profiles/web/cordis.patch.yml` 注册入口行（不修改 profile 的 `package.json`）
3. 往 dsh 前端入口注入极简深色兜底样式（消除首帧白屏，无 `!important`、token 兼容）

> 升级 dsh 后建议重跑一次 `install.ps1`（前端入口的引导样式和插件副本需要刷新）。

## ❓ 常见问题

| 问题 | 处理 |
|---|---|
| 设置里没有「Dream Skin 换肤」 | 确认已重启 dsh + Ctrl+F5；若 `/plugins/dsh-client-ui-theme-manager/client.js` 404，重跑 `install.ps1` |
| 刷新后主题没保持 | 不可能发生（持久样式）；若出现，按 F12 看 `[ui-theme-manager:...]` 日志发给我们 |
| 自定义主题/背景图没了 | 它们存在**浏览器 localStorage**：换浏览器、清缓存或换设备会丢；用「导出主题」备份 |
| 导入 zip 报"浏览器不支持" | 用新版 Chrome/Edge，或先解压 zip 取 theme.json 单独导入 |
| 背景图没显示 | 状态条会提示"背景类名缺失"（dsh 升级导致类名变化）——更新后重装插件即可 |
| 和旧版命令行换肤工具混用 | **二选一**；若混用后不生效，先跑旧工具的 `restore.ps1` 还原前端入口 |

## 🛠️ 开发

```powershell
# 改完 lib/client.js 后验证语法 + 冒烟 + 集成（需本机已安装插件）
node --check lib/client.js
node dev/smoke-test-client.cjs
node dev/integration-test.cjs
# 重新安装到 profile
powershell -ExecutionPolicy RemoteSigned -File .\install.ps1
```

> `dev/` 下的测试脚本引用本机 dsh 路径，仅用于开发自检，不参与发布包。

## 📄 License

[MIT](LICENSE)