WorkBuddy Palette
通过本机 CDP 注入为 WorkBuddy 桌面端做可还原的换肤。工具以 --remote-debugging-port=9223
启动 WorkBuddy，发现其 renderer（renderer/index.html），把 CSS 和一个 🎨 调色盘菜单注入到
实时界面里。不触碰任何官方文件。
何时使用本技能
- 用户发来
workbuddy-palette（或类似）的 GitHub 地址，让你安装 / 应用 / 使用它来给 WorkBuddy 换肤。 - 用户想在不修改官方应用的前提下改变 WorkBuddy 的外观（配色、背景图、自定义上传图片）。
- 用户反映 WorkBuddy 重启后调色盘消失、想重新应用，或想还原到原生外观。
前置条件
- 已安装 WorkBuddy 桌面端（换的是桌面端，不是网页版）。
- PATH 上有 Node.js 18+（注入器是纯 Node、跨平台）。WorkBuddy 自带 node 在
~/.workbuddy/binaries/下，所以通常不必全局安装。 - macOS 或 Windows（WorkBuddy 桌面端不支持 Linux）。
- 提醒用户一次：应用会重启 WorkBuddy，应用内未保存的工作会丢失，请先保存。
按意图选择参考文档
先检测平台，然后只读与用户需求对应的那一份参考文档，不要全读。
- 应用 / 换色 →
references/apply.md（macOS + Windows 步骤，跨平台） - 切换调色盘、上传自定义图片、palette.json 格式 →
references/manage-palettes.md - 还原原生 / 重启后重新应用 →
references/restore.md - 出问题了 →
references/troubleshoot.md（doctor、CDP 端口、找不到应用 / node） - 想懂注入原理、文件地图、设计边界 →
references/how-it-works.md
流程概览
- 检测平台：PowerShell
$IsWindows/$env:OS = Windows_NT-> Windows；uname= Darwin ->
macOS。确切命令见references/apply.md。 - 应用调色盘。要指定 id 时，先跑
node lib/palette/cli.mjs list拿到真实可用 id，
不要凭记忆猜（写错会直接报错）。不带--palette则用config.mjs里的
DEFAULT_PALETTE_ID。选调色盘或自定义图片见references/manage-palettes.md。 - 验证：
node lib/palette/cli.mjs status-> 期望看到注入/激活状态并列出 WorkBuddy 的 renderer。 - WorkBuddy 右上角会出现 🎨 按钮。告诉用户可以从这个菜单切换调色盘、上传自定义图片或还原原生。
> 首次 paint 重启 WorkBuddy 后，会自动把 --remote-debugging-port=9223 固化到 Windows
> 快捷方式（任务栏 / 开始菜单 / 桌面）。之后用户日常启动 WorkBuddy 自带调试端口，再跑 paint
> 不再需要重启，秒注入。--no-patch-shortcut 可跳过此行为。
> apply 和 pause 仍是 paint 和 restore 的隐藏别名（兼容旧指令）。
在 WorkBuddy 对话内调用（技能模式）
当本工具作为技能被 WorkBuddy AI agent 调用时，paint 会自动检测自身是否在 WorkBuddy 进程树内。
如果是、且 CDP 尚未就绪（需要重启 WorkBuddy），会 spawn 一个完全独立的后台进程来完成
"杀 WorkBuddy -> 重启带 CDP -> 注入调色盘"，主进程立即返回提示。
这是因为 taskkill /F /IM WorkBuddy.exe 会杀掉 WorkBuddy 及其所有子进程（包括 AI agent
本身），无法在同一个进程内同步完成"杀+重启+注入"。后台进程不受影响，能独立完成全部工作。
返回结果中 detached: true 表示已启动后台进程，告诉用户等待几秒 WorkBuddy 重新打开即可。
暂停 / 还原原生
node lib/palette/cli.mjs restore
移除已注入的调色盘并正常重开 WorkBuddy。官方安装始终原封不动。细节见 references/restore.md。
护栏
- 绝不替换、编辑或夺取
WorkBuddy.app、app.asar或 Windows 安装目录的所有权。本工具只注入到活的 renderer。 - CDP 仅绑定回环
127.0.0.1。提醒用户：调色盘生效期间不要运行不受信任的本机软件（Chromium CDP 对同用户进程无鉴权）。 - 注入只随 renderer 生命周期存活。手动重启 WorkBuddy 后调色盘会消失（设计如此）——重跑
paint恢复。 - 不要把 README/预览截图或自带 UI 焙烧的图片当作调色盘背景；用干净的壁纸 / 角色立绘。
自检（报告完成前的健全性检查）
node lib/palette/cli.mjs doctor # 平台、app 路径、CDP 端口、renderer 特征、默认调色盘
node lib/palette/cli.mjs status # 注入状态
node --check lib/palette/cli.mjs # 语法
doctor 应报告：平台正确、appFound: true、renderer 特征为 renderer/index.html、
且 defaultPalette.exists: true。
> defaultPalette.exists: false 意味着 config.mjs 的 DEFAULT_PALETTE_ID 指向了一个
> palettes/ 下不存在的目录——这会让不带 --palette 的 paint 直接失败。修 config.mjs
> 或改用 defaultPalette.available 里列出的 id。
排障顺序（换肤"没反应"时按此逐层排除）：
1. doctor -> 确认 app 找得到、defaultPalette.exists: true
2. curl http://127.0.0.1:9223/json/list -> 确认 CDP 在监听且有 renderer/index.html 目标；
没有就说明 WorkBuddy 没带 --remote-debugging-port 启动
3. paint --palette <真实id> --restart false -> 期望 applied: 1
4. status -> 期望 installed: true、menu: true
给用户的一句话总结
> 我克隆了 workbuddy-palette，以调试模式重启 WorkBuddy 并注入了调色盘。用右上角的 🎨 按钮
> 切换或还原。如果手动重启了 WorkBuddy，重跑一次 paint 即可恢复。
