# dsh-dream-skin

> 为 DeepSeek Harness 提供 8 套原创皮肤、壁纸与主题包分享的标准双面换肤插件，跨重启不丢设置。

## Metadata

- Author: [@RevolutionLA](https://github.com/RevolutionLA)
- Repo: <https://github.com/RevolutionLA/dsh-dream-skin.git>
- GitHub: [RevolutionLA/dsh-dream-skin](https://github.com/RevolutionLA/dsh-dream-skin)
- Stars: 68
- Language: JavaScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Topics: `deepseek-harness`, `dsh`, `dsh-plugin`, `dsh-plugin-theme`, `skin`, `theme`, `wallpaper`
- Forks: 6
- Open Issues: 2
- Last push: 2026-08-19T18:23:08.000Z
- Added: 2026-08-16T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:RevolutionLA/dsh-dream-skin
```

## Wiki

## 一句话定位
为 DeepSeek Harness 换上 8 套 iOS / Linear 风格的清透冷调皮肤、壁纸与强调色，并把「换肤」做成可分享、可导入、可回滚的标准主题包生态。

## 核心能力
- 提供 8 套内置皮肤（沉静蓝、极光青、星云紫、余烬橙、午夜黑、iOS 扁平、液态玻璃、Material 粉），覆盖浅色与深色
- 支持本地图、图片 URL、CSS 渐变三种壁纸来源，并可独立调节透明度、模糊、侧边栏透明度与自动弱化
- 提供每用户强调色 Accent，可在当前皮肤上叠加任意品牌色，不破坏皮肤本身
- 通过 `*.dsh-theme.json` 主题包实现导入、导出、分享链接与本地主题库，附带格式校验与回滚
- 在「设置 → 外观 / Theme」下注册独立分节，包含皮肤、壁纸、高级壁纸、强调色、主题包五个功能行
- 持久化跨 DSH 重启：localStorage + 宿主 `~/.dsh/dream-skin.json` 双写，状态文件丢失也能从浏览器侧恢复

## 技术实现
- **语言**: JavaScript（Node 端 ESM + 浏览器端 CJS via `__ModuleLoader__`）
- **关键依赖**: `@deepseek-ai/cordis`（插件宿主框架）、`@deepseek-ai/dsh-client-runtime` / `dsh-client-locale` / `dsh-client-ui-theme`（DSH 官方客户端包）、`react` ^18.2
- **架构模式**: 标准 DSH 双面插件——Host 端通过 `cordis.patch.yml` 插入 `dream-skin` 加载器条目，挂载 `/dream-skin/api` 受信任 JSON 持久化接口；Browser 端通过 `dsh.client` 声明被 `dsh-client-modules` 拉起，注册主题、slots、locale 字典
- **入口文件**: `lib/index.js`（Host apply）、`lib/client.js`（Browser apply，含 8 套皮肤 token 与 8 语言字典）

## 适用场景
希望把 DeepSeek Harness 调成符合自己审美的清透冷调视觉风格、又不想装桌面端注入型换肤工具的普通用户。适合每天长时间盯 DSH Web 写作 / 编码，需要更柔和的对比、更克制的强调色、更耐看的浅深组合，并能随时切换或分享给同事一套自配色方案。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DeepSeek Harness (DSH) | `^0.1.0-rc.6` | 由 `peerDependencies` 锁定，宿主扩展点 `ctx.theme` / `ctx.slots` / `ctx.locale` 必需 |
| Node.js | `>=18` | 由 `engines.node` 声明，仅用于本地开发与测试运行时 |
| 浏览器 | 现代 Chromium / WebKit | 设置面板依赖原生 CSS 变量、`backdrop-filter`、`matchMedia`（README 声明） |
| 操作系统 | macOS / Windows / Linux | 跨平台；Host 文件路径使用 `process.env.DSH_HOME` 或回退到 `~/.dsh/`，无平台限制字段 |

## 安装方式
```bash
dsh plugin --profile web add github:RevolutionLA/dsh-dream-skin
```

## 配置项
本插件无需额外配置。所有可调项都在 **设置 → 外观（Theme）** 面板下，以图形化方式呈现，常用项包括：

| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| 皮肤（Skin） | 单选 | 在 8 套内置皮肤与已导入主题包之间切换 | 跟随系统外观 |
| 壁纸（Wallpaper） | 单选 / 文件 / 滑块 | 选择本地图（自动压缩到 data URL）、粘贴图片 URL 或挑内置渐变 | 无 |
| 壁纸透明度 | 0–100 滑块 | 主内容区与侧边栏的半透明底的可视强度 | 80% |
| 壁纸模糊 | 0–60 滑块 | 给壁纸叠 backdrop-filter 模糊 | 0 px |
| 侧边栏透明度 | 0–100 滑块 | 侧边栏自己的半透明底；可独立于主画布 | 与主画布联动 |
| 强调色（Accent） | 选色盘 / 随机 | 在当前皮肤上叠加一个品牌色，不改皮肤本身 | 跟随主题 |
| 自动弱化 | 开关 | 聚焦任务时让壁纸淡出、不抢注意力 | 关闭 |
| 最近使用壁纸 | 历史 | 最多保留 5 张，点一下换回 | — |

> 持久化键全部带 `dsh-dream-skin:` 前缀，存在浏览器 `localStorage`；并在每次变更后防抖 200ms 推送到宿主文件 `~/.dsh/dream-skin.json`，固定 origin 的官方 Web 与随机端口的 DSH Desktop 都能跨重启保留。

## 常见问题

**Q: 安装完打开 DSH 看不到「外观 / Theme」分节怎么办？**

A: 一定要重启 DSH Web（运行 `dsh web`），新插件才会被插件管理器发现并加载。重启后进 **设置 → 外观（Theme）** 即可看到皮肤、壁纸、强调色、主题包五个功能行。

**Q: 换好的皮肤 / 壁纸，重启 DSH 后为什么看起来回到默认了？**

A: 0.4.0 起插件默认走三层持久化：内存缓存 → `localStorage` → 宿主文件 `~/.dsh/dream-skin.json`。重启时浏览器侧会从宿主文件把保存的皮肤 / 壁纸 / 强调色 / 主题包重新拉回并应用。如果仍丢，请确认 `DSH_HOME` 是否指向预期目录、或 Web 进程确实被重启过。

**Q: 这个插件跟 Codex-Dream-Skin 一样吗？**

A: 致敬但实现路径不同。Codex-Dream-Skin 通过 CDP 注入桌面客户端 CSS，本插件走 DSH 官方的 `ctx.theme.register` / `ctx.slots.inject` 扩展点，**不注入、不改二进制**，因此不因 DSH 更新而失效。

**Q: 怎么把自配色方案分享给同事？**

A: 在设置里点「主题包 → 导入」加载一个 `*.dsh-theme.json`，或者自己写一个（参考 `docs/examples/sample-theme-pack.json`），再点「复制分享链接」即可把整包编码进 URL hash 发出去；也可导出文件后用任意渠道分发。导入时会校验格式与必要字段，失败时安全回退，不破坏现有设置。

**Q: 卸载后会不会留下残留？**

A: 卸载只是停止加载。`localStorage` 里 `dsh-dream-skin:*` 的键与 `~/.dsh/dream-skin.json` 都还在；重新安装会自动接管，或手动删除即可彻底清理。

**Q: 为什么切换皮肤后背景没跟着换？**

A: 默认逻辑是「皮肤没自带背景时自动套用该皮肤的 iOS 弥散光渐变」。一旦你手动选过图片 / URL / 渐变，插件会标记为「自定义壁纸」，以后切皮肤就不再覆盖它了——切回「跟随皮肤」需要清掉自定义壁纸。

**Q: 能不能完全删掉壁纸回到官方外观？**

A: 在「高级壁纸」或主壁纸行点「清除壁纸 / 移除图片」即可，主画布与侧边栏会恢复为该皮肤的不透明色。

## 上手难度
入门 — 装好之后只在设置面板里点几下，没有命令、没有配置文件、没有需要重启的额外步骤；想自己写主题包再深入看 `docs/themes-spec.md`。

## 已知问题与限制
- **首帧可能闪烁（FOUC）**：插件首次挂载前的瞬间，主题尚未应用，仍是默认外观；现状是「以同源 localStorage 为兜底先渲染再覆盖」，完全消除 FOUC 仍是 Roadmap 项目（README.md:321）。
- **请求体上限 32 MB**：`/dream-skin/api` 单次 `set` 超过 32 MB 时返回 413。壁纸以 base64 data URL 存 localStorage，已自动压缩到 ≤2 MB，因此基本不会触达，但单次批量导入大量主题包时需注意。
- **Host 通道在随机端口的部署下才有意义**：官方 Web 的 origin 固定，理论上 localStorage 够用；`$DSH_HOME/dream-skin.json` 主要为「每次启动端口都变」的 DSH Desktop 服务，两端行为略有差异。
- **不暴露用户级配置 schema**：所有设置都在 UI 上，没有 `ctx.config.*` 形式的可注入配置项；想换 token 需新增内置皮肤或写主题包。

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-dream-skin](https://deepseek-plugin.org/plugins/RevolutionLA/dsh-dream-skin)
Wiki generated by AI (model: `MiniMax-M3`)