feat(desktop): 新增「皮肤」系统 — 在现有主题之上支持背景图/字体/颜色的便携皮肤包
- Dominant language
- TypeScript
- Stars
- 2.7k
- Forks
- 395
- Avg merge
- 21h 48m
- Merged PRs (30d)
- 776
Description
**客户端版本**: 0.1.35
**反馈类型**: feature
---
## 背景
在 Codex 社区里,「给桌面端换皮肤」是很有吸引力的玩法:有人用第三方工具(如 Codex Dream Skin)通过 CDP 向桌面应用运行时注入 CSS + 背景图,做出动漫背景等个性化外观。但这类注入式方案非官方、脆弱,随客户端版本升级容易失效,也不安全。
Codex 官方的能力其实只有:Settings → Appearance 里选择基础主题、调整 accent / 前景 / 背景色、换 UI / 代码字体、设置语义 diff 颜色,以及用 `codex-theme-v1:{...}` 便携 JSON 字符串导入 / 分享主题。官方并不支持背景图。
希望 Cindy 把「皮肤」做成官方一等公民:在现有主题系统之上,增加可选的背景图 / 字体 / 颜色一体的**便携皮肤包**,安全、可分享、可持续,而不是让用户去依赖注入式 hack。
## 现状盘点(已核对代码)
Cindy Desktop 已有很完整的主题系统:
- 11 个内置主题(cindy / default / atom-one-light / eclipse / github-dark / material-ocean-hc / monokai-pro / one-dark-pro / solarized-light 等),语义 token 驱动,CSS 变量运行时注入(`apps/desktop/src/renderer/themes/`)。
- 主题家族(light / dark 配对)、主题模式(亮 / 暗 / 跟随系统)。
- 本地主题:导出当前主题副本、导入 VSCode / Obsidian 主题文件、打开主题目录、刷新(设置 → 外观,`AppearanceSection.tsx`)。
- 本地主题已支持品牌 icon / logo(新建对话页品牌区),说明「主题挂图片」的管道已存在。
- UI / 代码字体与字号设置。
**缺失的能力**:
- 工作区背景图 / 壁纸支持(工作界面目前没有任何背景图)。
- token 之外的自定义样式。
- 可直接复制分享的单串导入 / 导出格式(现在导出的是本地文件)。
**设计约束**:`docs/design-rules/DESIGN.md` §1 规定工作界面不出现装饰性图案(极简、近单色、零阴影)。因此皮肤必须是**显式 opt-in 的覆盖层**,未启用时默认观感零变化。
## 提议
1. **皮肤包格式(便携可分享)**:对标 `codex-theme-v1`,用单串 JSON(或 `.cindy-skin` 文件)承载:颜色(映射现有 token 槽位)、字体(UI / 代码)、背景图(本地路径或内嵌)、light / dark 双态。
2. **背景图层**:至少覆盖聊天 / 工作区,提供压暗、模糊强度参数,保证前景可读性与对比度;登录页等关键链路不受影响(沿用 `--login-*` 只随基础双态切换的原则)。
3. **安全边界**:v1 默认不做任意 CSS 注入(Electron 下样式注入有安全与维护风险),先走 token + 受控背景图参数;任意 CSS 留作 v2 讨论。
4. **导入 / 导出 / 分享**:设置 → 外观新增「皮肤」区块(从剪贴板 / 文件导入、导出为分享串、删除 / 管理);现有本地主题可一键转为皮肤。
5. **设置 UI**:皮肤选择器(缩略图预览)、背景图预览(含压暗 / 模糊效果)、light / dark 分别预览。
6. **平台**:桌面优先;移动端后续复用同一格式与 token。
## 验收标准(建议)
- 皮肤包可导入 / 导出 / 启用 / 停用;背景图 + 颜色 + 字体一次生效。
- Light / Dark 双模式均可目检通过(沿用双模式交付门槛)。
- 未启用皮肤时默认观感零变化(回归测试)。
- 对比度守护沿用现有 `switchThemeContrast` 等测试体系。
## 开放问题(可放 v2)
- 是否允许任意 CSS。
- 是否需要社区皮肤仓库 / 市场。
- 背景图体积与格式限制(建议 ≤10MB,png / jpg / webp)。
- 移动端跟随节奏。
> 术语说明:仓库里「皮肤」目前是内部术语(CINDY 皮肤族,指默认配色家族);本 issue 的「皮肤」指用户可安装分享的外观包(背景图 + 颜色 + 字体),两者需要区分。
---
**OS**: win32 x64 (10.0.26200)
**界面语言**: zh-CN
Contributor guide
Research direction
Start by reading apps/desktop/src/renderer/themes/ and AppearanceSection.tsx, then review docs/design-rules/DESIGN.md §1 and the existing theme import/export behavior. The proposed work spans a portable skin format, controlled background layers, settings UI, and light/dark handling; completion requires import, export, enable/disable, regression coverage for unchanged defaults, and the existing switchThemeContrast checks.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- electron, typescript
- Domain
- design, desktop
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100