WorkBuddy 换肤 (ym-wb-skin)
把 WorkBuddy 界面换成用户想要的样子：给一张图（或一句话颜色描述），自动生成壁纸与整套配色，
写进 WorkBuddy 自己的皮肤缓存里 —— 不用常驻进程、不用开调试端口，重启也在。
何时使用
- 用户说「换肤 / 换皮肤 / 换个界面风格」
- 用户丢来一张图说「用这张当皮肤 / 当背景」
- 用户说「换成深蓝 / 暖金 / 莫兰迪色」这类颜色描述
- 用户抱怨「皮肤又变回去了」（跑自检修复）
第 0 步 · 版本自检（每次动手前先跑）
python scripts/sync.py --json
只读比对线上版本：退出码 0 最新 · 10 有新版建议重装 · 20 主版本不同必须重装 · 30 联网失败按旧版继续。
本技能不自动更新自己 —— 换版本只有一条路：用户明确重装 （skillhub install ym-wb-skin）。
运行前提
- 依赖：
Pillow；首次使用先跑python scripts/setup.py - 本机 WorkBuddy 桌面端（Windows / macOS 均可，脚本用
~/.workbuddy定位配置，不写死盘符） - 外观面板里至少下载过一个服务器主题（内置浅色/深色不落盘，不能当载体）
- 无运行时配置与本地数据之外的额外要求；运行时产物一律放
~/.workbuddy/wb-skin/（壁纸、暂存 CSS、清单）
执行步骤
A. 有图片时
- 做壁纸 —
python scripts/make_wallpaper.py <图片路径>
竖图自动走「虚化铺底 + 原片贴右侧」构图，横图直接裁切。产出~/.workbuddy/wb-skin/wallpaper.jpg。 - 生成皮肤 —
python scripts/gen_skin.py --wallpaper <壁纸路径> --source-image <原图>
自动从图片算主色相，套用到官方原版配色的全部色值上；背景图去重内嵌；附带侧栏可见性修复。
产出~/.workbuddy/wb-skin/skin.css（超过快照限额会自动压壁纸重试）。 - 落盘 —
python scripts/apply_skin.py
默认写入所有服务器主题目录（每个目录先备份官方原版为skin.css.ym-official）；
只想改一个目录加--carrier <目录名子串>。 - 让用户生效 — 提示：设置 → 外观 点一下当前主题（若已选中先切到别的再切回来），或重启 WorkBuddy。
官方应用成功后会自己把皮肤写进启动快照，之后每次冷启动自动恢复。
B. 只有颜色描述时
- 出壁纸 —
python scripts/make_wallpaper.py --color "#3A6EA5"（生成同色系柔和渐变，无需图片）。
想要更有画面感时，可先用图像生成能力出一张横版图，再走 A 的第 1 步。 - 其余同 A 的第 2–4 步。
C. 皮肤被官方覆盖了
python scripts/check_skin.py 查看漂移情况，python scripts/check_skin.py --repair 自动补回
（退出码 10 = 有漂移）。建议挂一个每日定时任务跑 --repair，服务器刷新主题版本、限时皮肤到期
都能自动恢复。
D. 还原官方原版
python scripts/restore_skin.py（全部目录）或加 --carrier <目录名子串> 只还原一个。
还原后同样需要点一次主题或重启才生效。
目录说明
scripts/— 执行逻辑（make_wallpaper.py做壁纸、gen_skin.py生成皮肤 CSS、
apply_skin.py落盘、check_skin.py自检修复、restore_skin.py还原、
scripts/sync.py版本自检、scripts/setup.py依赖安装）references/— 按需加载的参考文档
（mechanism.md皮肤机制源码级结论，改机制或排查不生效时读它；
pitfalls.md踩坑清单，出现「颜色变了图没了」「改了没反应」时读它）
版本历史
v1.0.0 (2026-09-22)
- 首版：图片 → 壁纸（竖图虚化延伸构图、横图裁切）→ 自动配色（色相圆周平均映射）→ 皮肤 CSS → 落盘生效。
- 附带侧栏可见性修复、启动快照限额自查（512KB）、自检修复（
check_skin.py --repair）与一键还原。 - 支持「只给颜色」的用法：
make_wallpaper.py --color生成同色系渐变壁纸，无需图片。
常见坑
- 颜色变了、背景图没了 —— 把图片地址换成变量时只替换了地址部分，产出非法的
url("var(--ym-bg)")，整条声明被丢弃。必须连同url(...)一起替换。 - 改了 skin.css 界面没反应 —— 三个原因：主题 key 不该带版本时间戳；当前是内置浅色/深色
（官方会主动清掉自定义皮肤，内置主题不能当载体）；点了已经选中的主题（同主题是 no-op）。 - 重启后第一帧没皮肤 —— 启动快照有 512KB 硬上限且超限静默失败，背景图必须去重内嵌成一份。
- 侧栏看着消失了 —— 官方把侧栏底色设成 transparent，DOM 一直在；CSS 末尾已强制给回面板实色。
- 服务器刷新 / 皮肤到期后被打回原形 —— 目录名带版本时间戳会变、限时皮肤到期会回落浅色；
靠每日跑check_skin.py --repair自愈。 - Windows 的 Git Bash 会把
~路径转成怪样子 —— 传脚本参数时用显式完整路径。
完整清单与源码级机制说明见 references/pitfalls.md 与 references/mechanism.md。
