WorkBuddy Dream Skin

给 WorkBuddy（基于 VS Code 内核的 Electron 应用）做深度换肤。关键认知：WorkBuddy 大量组件
（首页 header、对话容器、侧边栏列表）不吃 --vscode-* 变量，而是用自己的语义类
（.wb-home-header、.chat-container、.conversation-sidebar …）。所以本 skill 不靠泛变量覆盖，
而是直接覆盖这些真实语义类——这才是「界面真的会变」的保证。

重要前提（已实测验证）：WorkBuddy 的运行时注入全部被硬化拦截——
--remote-debugging-port 被 Node 启动器拒绝、--inspect 被单实例锁拦截、主进程 V8 inspector 上下文
无 require、渲染进程不可调试。因此本 skill 不依赖 CDP / 调试端口，唯一可行的注入面是
改写安装目录里的 app.asar（对其中渲染样式做最小字节手术）。这是有意的、可逆的、且会自动备份。

范式对齐开源项目 CodeDrobe/skills：皮肤以主题包形式组织（theme.json + workbuddy.css + 图片），
背景图通过 CSS 变量 --dream-hero / --dream-texture 注入，支持 generate → preview → apply → restore 闭环。

第 0 步：理解意图（最重要，先理解，再执行）

收到换肤请求后，先不要动手，把用户的话拆成下面几个维度来判断。一句请求往往同时命中多个维度。

规则：
- 命中「电影画面/场景」或「人物」→ 优先生成原创同人图（不要偷懒用真实剧照或演员照片，有版权/肖像权风险）。
- 纯抽象意境词（「星空」「薄荷绿」「赛博朋克」）→ 走纯配色路线，不一定要出图。
- 参考图优先于一切调色板推断。
- 多维度可叠加：「大话西游经典界面，紫霞仙子，水墨风」= 场景 + 人物 + 艺术风格，三个都要做。
- 一句话没说清时，先按最合理的默认（意境/配色）做一版预览，再让用户微调，不要反复追问。

参考图驱动（用户给了一张图时）

1. 把图取到本地绝对路径 IMG（附件可先保存到技能 assets/）。
2. generate-skin.js --ref IMG：程序化解码取主色，并把该图作为全屏背景。
3. 预览：make-preview.js --skin <out>.css --hero IMG。
   > 仅支持 8-bit 非隔行 PNG；JPG 自动降级为「当背景 + 用 --accent/--mode 配色」（不报错）。

第 1 步：生成 / 选取皮肤

$skill = "$env:USERPROFILE\.workbuddy\skills\workbuddy-dream-skin"
$node  = "$env:USERPROFILE\.workbuddy\binaries\node\versions\22.22.2\node.exe"

情况 A：用户给了一张参考图（配色 + 背景）

& $node "$skill\scripts\generate-skin.js" --desc "<用户的原话>" --name <英文id> --ref "C:\path\to\ref.png"

情况 B：纯意境 / 配色（一句话）

& $node "$skill\scripts\generate-skin.js" --desc "<用户的原话>" --name <英文id>

• 自动识别关键词/主色/深浅；--accent "#ff5500" 强制强调色；--mode light/dark 切深浅。
• 自定义文字（皮肤签名 / 标语）：任意情况可加 --text "文字内容"，浮层显示不挡操作。
• 位置 --text-pos：bottom-right(默认) / bottom-left / top-right / top-left / center / watermark
• 颜色 --text-color；字号 --text-size（默认 22）
• 例：--text "我爱易烊千玺" --text-pos bottom-right

情况 C：经典电影 / 场景主题（已有主题包）

预设主题包在 skins/<id>/（含 theme.json + workbuddy.css + assets），直接用，无需重新生成：

> 上表主题包均可直接 --theme-dir 应用；命中风车场景词时 generate-skin.js 也能自动复制对应主题包。

# 直接应用已有主题包（见第 3 步），--theme-dir 指向 skins/kungfu-soccer

新建一个电影主题包（复用模板）

1. 复制 skins/theme-starter/ → skins/<id>/，改名 theme.json 的 id/displayName。
2. 用 ImageGen 生成原创场景图 assets/<id>_scene.png（人物/场景，规避版权）。
3. 在 workbuddy.css 里把 --dream-hero 用到的图换成你的图（apply 时按 theme.json 的 images.hero 注入）。
4. 改 :root.dream-host-workbuddy 的配色变量与组件样式。
5. 扩充 theme.json 的 targets.workbuddy.verification.contexts（声明要验证的 landmark 节点）。

第 2 步：预览，让用户先看到样子

# 主题包预览（全屏背景 + 双头像，用 make-preview 时需手动指定图）
& $node "$skill\scripts\make-preview.js" --skin "$skill\skins\kungfu-soccer\workbuddy.css" `
  --hero "$skill\skins\kungfu-soccer\assets\kungfu_soccer_scene.png" --name "功夫女足经典" `
  --out "$skill\preview-kungfu-soccer.html"

预览是独立 HTML（自包含 base64 图），不影响真实 WorkBuddy。用 present_files 呈现预览 + 皮肤 CSS，
说明配色、深浅、是否含背景图/角色，并询问是否调整。

第 3 步：应用（让界面真正变化）

本步对安装目录的 app.asar 做最小字节手术：把皮肤 CSS 作为一个标记块追加进渲染样式文件，
其余文件（含原生模块、unpacked 外部文件）字节级不动。会自动备份 app.asar → app.asar.bak。

方式一：一步生成并改写（推荐）

# 1) 生成自包含静态 CSS + 对真实 app.asar 做字节手术，产出改包到 %TEMP%/wb-dream-skin/_patched.asar
#    （自动定位 WorkBuddy 安装、自动选目标 CSS、无需手填路径）
& $node "$skill\scripts\asar-patch.js" --theme-dir "$skill\skins\kungfu-soccer" --marker kungfu-soccer

# 2) 应用：备份 + 覆盖 + 重启（路径全部自动定位，可直接无参运行）
& $node "$skill\scripts\apply.js"

> apply.js 会先写 app.asar.bak（仅首次），再用改包覆盖 app.asar，然后重启 WorkBuddy。
> 如果调用方是 WorkBuddy 自身子进程，apply.js 会在覆盖后自动注册一次性计划任务完成重启，避免杀掉调用方。重启后界面即换肤。

方式二：分步（想先看改写产物时）

# 先只生成静态 CSS（自包含，hero 内联为 base64）
& $node "$skill\scripts\gen-static-css.js" --theme-dir "$skill\skins\kungfu-soccer" --out "$env:TEMP\wb-dream-skin\workbuddy.static.css"
# 再显式改写 app.asar（--asar 可省略，会自动定位安装目录；下面仅演示显式写法）
& $node "$skill\scripts\asar-patch.js" `
  --asar "$env:LOCALAPPDATA\Programs\WorkBuddy\resources\app.asar" `
  --target "renderer/assets/index-.*\.css" `
  --inject "$env:TEMP\wb-dream-skin\workbuddy.static.css" `
  --marker kungfu-soccer --out "$env:TEMP\wb-dream-skin\_patched.asar"
# 再应用（同上方式一的 apply.js）

方式三：调用方是 WorkBuddy 自身子进程时（如 agent 直接执行）

apply.js 默认已处理此情况：它会先覆盖 app.asar，再注册一个一次性计划任务来
完成「杀主进程 + 重启」，这样当前 agent 会话被结束时，重启动作已在独立任务里继续。

& $node "$skill\scripts\apply.js"

> 计划任务大约 1 分钟后触发。期间 agent 可能被重启断开，可稍后手动检查界面是否生效，
> 或查看 %USERPROFILE%\.workbuddy\skills\workbuddy-dream-skin\applied-asar-log.txt。

还原（一键恢复官方默认外观）

换肤前 apply.js 已自动把原版 app.asar 备份成 app.asar.bak。一条命令即还原：

& $node "$skill\scripts\apply.js" --restore

它会自动：① 结束 WorkBuddy 进程（解锁文件）→ ② 把 app.asar.bak 复制回 app.asar → ③ 重启 WorkBuddy。
约 1 分钟后生效（由一次性计划任务执行，避免杀掉当前 agent 会话）。重启后界面即回到官方原样，
官方自动更新也恢复正常（改写 app.asar 会使官方签名失效，更新前请先还原）。

> 提示：apply.js --restore 找不到 app.asar.bak 时会直接报错并停下，不会破坏任何文件。

手动还原（兜底，无需脚本）：直接把备份复制回去再重开 WorkBuddy 即可。

Copy-Item "$env:LOCALAPPDATA\Programs\WorkBuddy\resources\app.asar.bak" `
  "$env:LOCALAPPDATA\Programs\WorkBuddy\resources\app.asar" -Force
# 重启 WorkBuddy 即恢复官方外观（或删掉 app.asar 后重装/更新）

排错小贴士（小白向）
- 报 找不到 WorkBuddy 安装目录：把 WorkBuddy 装到默认位置，或设置环境变量
WORKBUDDY_ROOT 指向安装目录（含 resources/app.asar 的那一层）。
- 报 找不到改包：先跑 asar-patch.js 生成 _patched.asar 再 apply.js。
- 报 找不到 app.asar.bak：说明从没成功换肤过，无需还原；或备份被手动删了，可重装 WorkBuddy 恢复。
- 报 覆盖 app.asar 失败 / 文件被占用：确认 WorkBuddy 已关闭，或由计划任务自动处理（推荐）。
- 想看详细日志：%TEMP%/wb-dream-skin/apply.log（不会写进技能目录）。
- 不确定参数：node scripts/apply.js --help 打印全部用法。

Guardrails（必须遵守）

• 改写 app.asar 是预期行为，但属于修改宿主程序文件：操作前自动备份 app.asar.bak；
  改写会使官方代码签名失效，官方自动更新可能拒绝，直到还原。务必保留备份。
• 会重启 WorkBuddy（关闭当前所有窗口）。非交互/agent 场景直接运行 apply.js，它会自动注册计划任务完成重启，避免杀掉调用方。
• 不开启任何网络监听、不上传用户参考图、不连外部图床；仅本地文件读写。
• 主题包当不可信输入：不执行主题内 JS，不加载外部 CSS 资源（图片仅限本地 file:///）。
• 经典电影 / 角色主题以 AI 生成的原创同人致敬图呈现（大话西游、功夫女足、千与千寻、英雄本色等），
  属二次创作致敬，不直接搬运剧照或演员照片，规避版权与肖像权风险。
• 装饰层 pointer-events: none，保留原生导航、输入、菜单、无障碍行为。
• 不把皮肤发布到 improvised 端点；上架走官方市场并如实声明「本技能会修改宿主 app.asar」。

原理与文件

• scripts/asar-patch.js — 最小字节手术：asar = [uint32 size][chromium-pickle(header JSON)][body]。
  只把皮肤块追加进目标渲染 CSS，并把其后所有文件偏移 +blockLen，unpacked/原生文件零改动。
  自动定位 app.asar 与「最大的 renderer/assets/index-*.css」；改写后自检（标记块 + base64 hero 存在、
  公共 asar.getRawHeader 能重解析）。子命令式 CLI：--theme-dir（一步生成并改写）或 --asar/--target/--inject/--out（显式）。
• scripts/gen-static-css.js — 把主题包变成自包含静态 CSS（去作用域前缀、hero PNG 内联为 base64）。
  标记块由 asar-patch.js 独占，这里只输出裸 CSS。
• scripts/apply.js — 备份 app.asar→app.asar.bak（仅一次）、用改包覆盖、重启。
  支持子命令：--restore 一键还原官方外观（从 app.asar.bak 恢复并重启）；--help 打印用法。
  路径全部可省略，自动定位；若调用方是 WorkBuddy 子进程，则注册一次性计划任务完成重启，
  避免杀掉调用方。纯 Node 实现， skill 包里不再包含 .bat/.ps1 文件，以便通过市场文件类型检查。
• scripts/generate-skin.js — 一句话/参考图 → 配色背景 CSS（含 --text 自定义文字、经典主题复制）；依赖 lib/png-palette.js。
• scripts/make-preview.js — 界面仿真预览（自包含 HTML）。
• scripts/lib/png-palette.js — 零依赖 PNG 主色调提取（Node 内置 zlib）。
• skins/<id>/ — 主题包（theme.json + workbuddy.css + assets/ 原创图，相对路径引用，可移植）。已有：
  kungfu-soccer（功夫女足）、dahua-xiyou（大话西游）、cyberpunk（赛博朋克）、
  spirited-away（千与千寻）、ying-xiong-ben-se（英雄本色）、theme-starter（中性起点模板）。

已知限制（务必告知用户）

1. 版本敏感：渲染 CSS 文件名是按版本哈希的（如 index-B1I-AkRx.css），随 WorkBuddy 大版本变化；
   asar-patch.js 自动选「最大的 renderer/assets/index-*.css」，但个别组件类名若随之调整，皮肤可能需微调 CSS。
2. 改写 app.asar：部分杀软/EDR 可能告警该写入；公司管控机可能禁止写 Program Files。遇阻用 app.asar.bak 还原。
3. 重启才生效：注入在文件里，重启即加载；当前窗口会关闭。
4. 参考图只支持 8-bit 非隔行 PNG（JPG 自动降级为当背景 + 手动配色）。
5. 市场审核风险：因改写宿主程序文件，公共市场安全扫描可能拦截或要求人工审核（见发布/上架）。

发布 / 上架

• 本机私用：整目录放 ~/.workbuddy/skills/workbuddy-dream-skin/，WorkBuddy 自动加载。
• 打包：用 skill-creator/scripts/package_skill.py <skill目录>，本地只校验 frontmatter（name 须 hyphen-case、
  description 无尖括号）；真实体积上限 50MB 由市场在上传时执行。务必保持目录精简：
  改包 _patched.asar（~256MB）和生成的静态 CSS 都在 %TEMP% 下、由 apply 时现生成，不要提交进技能目录。
• 公共市场：ClawHub（clawhub.ai）或 SkillHub（skillhub.cn / cnb.cool/skills），需实名/审核。
  本技能会改写宿主 app.asar，上架时须如实声明此行为，可能面临安全扫描拦截或人工审核；
  若被拒，可改为私有/团队市场分发。

上架前自查

• [ ] 真机跑一次第 3 步（方式一），确认界面真的换肤、重启后生效。
• [ ] generate-skin.js 三种路径（参考图 / 配色 / 经典场景）均产出合法 CSS。
• [ ] skins/<id>/assets/ 图均为 AI 生成的原创同人致敬图（非直接搬运剧照/演员照片），规避版权与肖像权。
• [ ] 技能目录 ≤ 50MB（不含 _patched.asar 等生成物）。
• [ ] app.asar.bak 机制可用，能一键还原。