heige-codex-skin-studio

name	heige-codex-skin-studio
description	在 macOS 上用一张本地图片或 Codex 生成的图片快速制作、应用、暂停 Codex Desktop 皮肤。用户提到 Codex 换肤、主题、皮肤主图、初音未来预设或 Miku Future 宠物时使用。

HeiGe Codex Skin Studio

目标是快速完成换肤。不要扩展成设计平台，不要拆分多层素材，不要修改 app.asar。

首次安装

运行：

open "$HOME/.agents/skills/heige-codex-skin-studio/scripts/install.command"

安装位置固定为 ~/.codex/heige-codex-skin-studio。

用户给了一张图片

1. 确认图片是非空的 PNG、JPG、JPEG 或 WebP。
2. 使用 Codex 自带的 Node 创建主题：

"/Applications/ChatGPT.app/Contents/Resources/cua_node/bin/node" \
  "$HOME/.codex/heige-codex-skin-studio/src/cli.mjs" create \
  --image "/绝对路径/hero.webp" --name "主题名"

3. 从返回 JSON 读取 id。
4. 告知用户应用操作会正常退出并重新打开当前 Codex。
5. 用户已要求立即应用时，打开应用脚本并传入 id：

open "$HOME/.codex/heige-codex-skin-studio/scripts/apply.command" --args "主题-id"

用户只给了创意描述

先使用当前环境可用的 imagegen 技能生成一张完整的横向 UI 主图。画面要预留左侧导航和底部输入区的可读空间，不要把按钮、菜单文字或聊天内容烘焙进图片。拿到本地图片路径后，继续执行「用户给了一张图片」。

图片生成不可用时，直接请用户给一张本地图片，不要要求额外 API Key。

内置预设

默认预设是高精度定制的 miku-488137，另有 9 个轻量预设（配色 + 背景底图）： genshin-dawn、genshin-night、wuthering-tide、wuthering-echo、naruto-hokage、naruto-sasuke、deepspace-dawn、deepspace-star、dalao-dianyan（大佬 · 点烟彩蛋）。

open "$HOME/.codex/heige-codex-skin-studio/scripts/apply.command" --args "miku-488137"

应用任意一个后，其余预设都在顶部中间的 🎨 菜单里一键切换。

给在 Codex 内运行的 Agent 的关键规则

应用皮肤会正常退出并重启 Codex 本体，你的当前任务会被中断。重启即成功，这是预期行为：

1. 安装阶段一律用 HEIGE_SKIP_APPLY=1 环境变量跳过自动应用。
2. 把 apply 作为整个任务的最后一步执行，执行前告知用户「Codex 即将重启，重启后皮肤生效」。
3. 重启后绝对不要重试 install 或 apply，否则会造成无限重启循环。验证交给用户肉眼确认，或由 Codex 外部的工具执行。
4. 用户想要皮肤「常驻/重启不丢」时，让用户运行 scripts/enable-persist.command（macOS）。它装一个带 10 分钟冷却的 launchd 看门狗负责自动恢复，Codex 内的 Agent 仍然不得自行重试 apply。关闭用 scripts/disable-persist.command。
5. 若重启后调试端口一直不开（apply 报端口未就绪），不要循环排查。两种情况：老实例没退干净接管了新实例（让用户手动 Cmd+Q 完全退出后重跑脚本）；参数在命令行里但端口仍不开（当前 Codex 版本可能禁用了调试端口，让用户带版本号到 GitHub 开 Issue）。排障第一步是跑 node src/cli.mjs doctor：输出里的 diagnosis 字段直接给出分类结论（ok / flag-present-port-closed / running-no-flag / not-running），报 Issue 时把整份 doctor JSON 附上。脚本报错信息已内置各类指引，原样转述给用户即可。

界面内切换菜单

应用任意主题后，Codex 顶部中间会出现一个 🎨 按钮。点开可以在所有已装主题和原生界面之间即时切换，不需要再跑命令。菜单底部的「隐藏此按钮」会把按钮收成一颗半透明小圆点（状态跨重启保留），点小圆点即可恢复完整按钮。新建主题后重新执行一次 apply.command，菜单列表会刷新。

菜单里的「＋ 自定义图片」支持用户直接上传本地图片：页面内自动压缩、按图片风格提取配色并立即应用，结果存在 Codex 本地存储里，重启后重新 apply 会自动回到菜单；菜单里该行行尾的 × 可随时删除。自定义槽位只有一个，再次上传会覆盖上一张。用户只是想快速试一张图时优先推荐这个入口；要做成可分发的正式主题再走 create 命令。

暂停或恢复原界面

open "$HOME/.codex/heige-codex-skin-studio/scripts/pause.command"

这里只移除实时注入的 <style> 和切换菜单，因为工具从未修改 Codex 应用文件。

可选宠物

仅当用户明确需要 Miku Future 宠物时运行：

open "$HOME/.codex/heige-codex-skin-studio/custom-pet/install.command"

边界

• 当前只支持 macOS。
• CDP 固定监听 127.0.0.1，默认端口 9341。
• Codex 完整重载 renderer 后需要重新应用一次。
• 不修改应用包，不做 ASAR 注入，不处理 Windows 或 Linux。