WorkBuddy Skin

简体中文 | English

WorkBuddy Skin 是一个 非官方、非破坏式 的 WorkBuddy macOS 主题应用。v0.3.0 提供原生主题选择界面、6 个自适应内置主题，以及本地图片导入；日常使用不需要打开终端。

它不会修改 WorkBuddy.app、app.asar、WorkBuddy 签名或用户数据。本项目与腾讯无隶属、合作或背书关系。

安装 macOS 应用

1. 从 GitHub Releases 下载 WorkBuddy-Skin-0.3.0-arm64.dmg。
2. 打开 DMG，把 WorkBuddy Skin 拖入 应用程序（Applications）。
3. 当前应用采用临时签名，未经过 Apple 公证。第一次启动时，请按住 Control 点击或右键点击 WorkBuddy Skin，选择 打开，再确认 打开。以后可以正常双击启动。

安装和使用均不需要管理员密码。当前版本仅支持 Apple Silicon Mac，需要 macOS 13 或更高版本；WorkBuddy 应安装在 /Applications/WorkBuddy.app。

选择和更换主题

1. 从“应用程序”打开 WorkBuddy Skin。
2. 选择 Aurora、Dream、Forest、Midnight、Paper 或 Sakura。所有内置主题都会跟随 macOS 浅色/深色外观调整；新版 Midnight 在浅色模式下保持明亮柔和。
3. 如果 WorkBuddy 正在运行，确认提示。应用只会请求正常退出，最多等待 15 秒，绝不会强制结束 WorkBuddy。
4. 主题验证成功后，WorkBuddy 才会以新主题重新打开。

再次选择当前主题只会执行校验，不会重启 WorkBuddy；选择另一个主题会在确认后正常重启一次。关闭 WorkBuddy Skin 窗口不会停止已经运行的主题 watcher。

点击 Restore Official Appearance，应用会停止 watcher、仅删除 WorkBuddy Skin 自己创建的界面标记，并在不带调试参数的情况下正常重启 WorkBuddy，同时关闭该主题会话的 CDP 监听。

导入自己的图片

1. 点击 Import Image…，选择本机 PNG、JPEG 或 WebP 图片。
2. 图片通过格式和大小校验后，会作为新主题卡片出现；点击卡片即可应用。
3. 点击卡片右上角的删除按钮可移除导入副本，不会修改原始图片。正在使用的主题不能直接删除，请先切换主题或恢复官方外观。

单张图片最大 8 MB。应用会验证扩展名和真实文件签名、拒绝符号链接，并把通过校验的副本保存到仅当前用户可访问的应用目录。自定义主题使用固定安全样式，不接受 SVG、远程图片或自定义 CSS。

状态与兼容性

• 版本：v0.3.0
• 平台：Apple Silicon、macOS 13+
• 已验证 WorkBuddy 版本：5.2.6
• 适配范围：WorkBuddy 5.x；未验证的升级版本会安全拒绝注入
• 运行时：复用 WorkBuddy 自带的 Node 模式，应用不要求额外安装 Node

当窗口 URL、WorkBuddy DOM 探针或主界面选择器不匹配时，适配器会拒绝注入。WorkBuddy 升级后可能需要先更新适配器。

安全模型

主题引擎只在 127.0.0.1 的随机端口监听 Chrome DevTools Protocol（CDP）。CDP 本身没有认证：主题会话运行期间，其他不可信的本机进程理论上可以连接该端口并控制渲染器。不再使用主题时，请恢复官方外观。

注入器不会读取或记录对话、凭据、存储、文件、提示词或页面求值结果。只有渲染器 URL 和 WorkBuddy 专属 DOM 探针同时匹配时才会连接。内置 CSS 不能导入资源、使用 url(...)、远程/文件/JavaScript 协议或 CSS 反斜杠转义；主题文件不能执行 JavaScript。

设置、导入主题、会话所有权记录和日志以仅当前用户可访问的权限保存在 ~/Library/Application Support/WorkBuddy Skin/。界面的 Open Logs 按钮只打开固定日志目录，不显示端口或进程 ID。

常见问题

• **macOS 阻止打开应用：**按上面的步骤进行一次“右键 → 打开”；当前版本未公证。
• **WorkBuddy 未正常退出：**保存工作并手动正常退出 WorkBuddy，然后重新选择主题。WorkBuddy Skin 不会强制结束它。
• **提示 WorkBuddy 不受支持：**当前界面已经与安全适配规则不匹配；应更新适配器，不要放宽目标校验。
• **主题会话异常：**从应用打开日志，先恢复官方外观，再重新尝试。

高级开发与命令行

普通用户应安装 DMG。贡献者可以克隆仓库并执行：

./scripts/test.sh
cd app && xcrun swift run WorkBuddySkinAppTests
cd .. && ./scripts/release-check.sh

开发场景仍可使用 CLI：

bin/workbuddy-skin doctor
bin/workbuddy-skin list-themes --json
bin/workbuddy-skin verify --json
bin/workbuddy-skin restore --restart

请把发布产物构建到源码目录之外：

./scripts/build-app.sh --output-dir /发布输出目录
./scripts/build-dmg.sh \
  --app "/发布输出目录/WorkBuddy Skin.app" \
  --output-dir /发布输出目录
./scripts/release-artifact-check.sh \
  --app "/发布输出目录/WorkBuddy Skin.app" \
  --dmg /发布输出目录/WorkBuddy-Skin-0.3.0-arm64.dmg

许可证

MIT，详见 LICENSE 和 NOTICE.md。