WorkBuddy 自定义皮肤技能

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 .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//（含 theme.json + workbuddy.css + assets），直接用，无需重新生成：

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

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

1. 复制 skins/theme-starter/ → skins//，改名 theme.json 的 id/displayName。
2. 用 ImageGen 生成原创场景图 assets/_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\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
& $node "$skill\scripts\asar-patch.js" `
  --asar "C:\Users\qingc\AppData\Local\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。

还原（一键）

把备份复制回去即可，无需任何脚本：

Copy-Item "C:\Users\qingc\AppData\Local\Programs\WorkBuddy\resources\app.asar.bak" `
  "C:\Users\qingc\AppData\Local\Programs\WorkBuddy\resources\app.asar" -Force
# 重启 WorkBuddy 即恢复官方外观（也可直接删掉 app.asar 后重装/更新）

还原后官方自动更新恢复正常（改写 app.asar 会使官方签名失效，更新前请先还原）。

---

Guardrails（必须遵守）

• 改写 app.asar 是预期行为，但属于修改宿主程序文件：操作前自动备份 app.asar.bak； 改写会使官方代码签名失效，官方自动更新可能拒绝，直到还原。务必保留备份。
• 会重启 WorkBuddy（关闭当前所有窗口）。非交互/agent 场景直接运行 apply.js，它会自动注册计划任务完成重启，避免杀掉调用方。
• 不开启任何网络监听、不上传用户参考图、不连外部图床；仅本地文件读写。
• 主题包当不可信输入：不执行主题内 JS，不加载外部 CSS 资源（图片仅限本地 file:///）。
• 装饰层 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（仅一次）、用改包覆盖、重启。 路径全部可省略，自动定位；若调用方是 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// — 主题包（theme.json + workbuddy.css + assets/）。已有：kungfu-soccer（功夫女足，完整）、 theme-starter（中性起点模板）。
• assets/ — 原创角色/场景图。

---

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

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 ，本地只校验 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。
• assets/ 图均为原创同人（非真实剧照/演员照片），规避版权与肖像权。
• 技能目录 ≤ 50MB（不含 _patched.asar 等生成物）。
• app.asar.bak 机制可用，能一键还原。