[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-93403":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":13,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":15,"stars7d":16,"stars30d":16,"stars90d":14,"forks30d":14,"starsTrendScore":17,"compositeScore":18,"rankGlobal":9,"rankLanguage":9,"license":19,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":22,"hasPages":20,"topics":23,"createdAt":9,"pushedAt":9,"updatedAt":37,"readmeContent":38,"aiSummary":39,"trendingCount":14,"starSnapshotCount":14,"syncStatus":40,"lastSyncTime":41,"discoverSource":42},93403,"heige-codex-skin-studio","HeiGeAi\u002Fheige-codex-skin-studio","HeiGeAi","给 Codex Desktop 一键换肤：OpenAI Codex\u002FChatGPT 桌面端主题工具，CDP 注入零修改应用，Miku\u002F原神\u002F鸣潮\u002F火影\u002F恋与深空 9 预设+自定义图片取色 | One-click theme & skin switcher for OpenAI Codex Desktop (macOS\u002FWindows)",null,"JavaScript",298,47,1,0,14,182,79,95.04,"MIT License",false,"main",true,[24,25,26,27,28,29,30,31,32,33,34,35,36],"agent-skill","anime","chatgpt","codex","codex-desktop","customization","devtools-protocol","electron","hatsune-miku","macos","skin","theme","theme-switcher","2026-07-22 04:02:09","# HeiGe Codex Skin Studio | Codex 换肤工作室\n\n\u003Cdiv align=\"center\">\n\n**给 Codex Desktop 一键换肤：一张图片就是一个主题，顶部菜单即时切换深浅外观，安装包内还自带可选的 Miku Future Pet。**\n\n*A local CDP-based skin switcher for Codex Desktop on macOS and Windows, with explicit next-launch persistence control.*\n\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-blue.svg)](LICENSE)\n![Platform](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fplatform-macOS%20%7C%20Windows-black)\n![Codex Desktop](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FCodex-Desktop-10a37f)\n\n[中文](#这是什么) · [English](#english)\n\n\u003C\u002Fdiv>\n\n![真机截图：Miku 主题 + 顶部一键切换菜单](docs\u002Fimages\u002Fmiku-switcher-live.jpg)\n\n*真机截图：Miku 488137 高精度主题（品牌 Logo + 肖像背景 + 拍立得挂件），顶部中间的 🎨 菜单一键切换全部主题和自定义上传。*\n\n## 这是什么\n\n一个效率优先的 Codex Desktop 换肤工具。它通过本机回环 CDP 把主题实时注入 Codex 界面，不修改 `app.asar`、应用二进制或签名资源。未来 Codex Desktop 若改变启动参数、renderer 结构或界面选择器，本项目仍可能需要适配。\n\n- **一键切换**：应用皮肤后 Codex 顶部中间出现 🎨 菜单，所有已装主题和原生界面即点即换。预设主题会同步切换 Codex 自身的浅色或深色外观，不再需要进入设置手动搭配。嫌按钮碍眼？菜单底部「隐藏此按钮」把它收成一颗半透明小圆点，点圆点即恢复。\n- **自定义上传**：菜单里选「＋ 自定义图片」直接上传本地图片，自动按图片风格取色（主色、辅色、面板底色、文字色），并根据图片亮度同步 Codex 深浅外观。「自定义图片」是单个本地快捷槽，再次上传会覆盖，行尾 × 可删除；它不是可分发的正式主题，也不会改写启动器记录的最近正式主题。renderer 本地存储可在自动补针或常驻启动时继续显示该快捷图，清除本地数据后会丢失。\n- **一张图片就是一个主题**：任意 PNG、JPG、JPEG、WebP 直接生成皮肤（配色 + 背景底图）。\n- **10 个内置预设**：高精度定制的 `Miku 488137`，原神、鸣潮、火影忍者、恋与深空各两款轻量主题，外加彩蛋预设「大佬 · 点烟」。\n- **AI 生成主题**：把 Skill 交给 Codex，让它先用生图能力产出主图，再自动做成皮肤，无需额外 API Key。\n- **自带可选 Pet**：安装包内附独立的 `Miku Future` 动画桌面宠物，包含待机、奔跑、挥手、跳跃、等待、审查等动作，不覆盖 Codex 内置宠物，也不会在只安装皮肤时强制启用。\n- **生命周期分离**：`pause` 只暂停当前会话，`resume` 恢复当前会话；`restore` 关闭常驻，活跃皮肤会话才重启为原生界面，已关闭或已原生时不额外拉起。\n- **用户决定是否常驻**：顶部菜单「皮肤常驻」开关是唯一受支持的开启常驻入口。关闭后本次继续使用；下次启动恢复原生界面。想再次常驻时，先打开「HeiGe 皮肤启动器」恢复当前会话，再在顶部菜单显式打开常驻开关。\n\n| 项目 | 参数 |\n|---|---|\n| 适用应用 | OpenAI Codex Desktop（ChatGPT 桌面端） |\n| 支持平台 | macOS 自动化与真机验证；Windows 跨 PowerShell 自动化，Microsoft Store\u002FMSIX 真机待验证 |\n| 注入方式 | Chrome DevTools Protocol，调试端口仅绑定本机回环 `127.0.0.1:9341` |\n| 内置主题 | 10 个（1 个高精度 Miku 488137 + 8 个游戏轻量主题 + 1 个彩蛋「大佬 · 点烟」） |\n| 运行时依赖 | 不安装 npm 运行时依赖；优先使用可信的 Codex 内置 Node，使用系统 Node 时要求 Node.js 22 或更新版本 |\n| 开发依赖 | `happy-dom` 与 `yazl` 均锁定精确版本，只用于测试与确定性打包 |\n| 自动化验证 | Node、macOS、Windows、安装包与文档门禁，不在文档中写死易过期的测试数量 |\n| 协议 | 代码 MIT，角色素材权利归各自权利人 |\n| 最近更新 | 2026-07-17 |\n\n![真机截图：鸣潮主题](docs\u002Fimages\u002Fwuthering-live.jpg)\n\n*真机截图：鸣潮 轻量主题（深色赛博场景底图 + 自动配色）。*\n\n![真机截图：原神破晓主题](docs\u002Fimages\u002Fgenshin-dawn-live.jpg)\n\n*真机截图：原神 · 破晓 轻量主题（浅色场景底图 + 自动配色），配合 Codex 浅色外观。*\n\n![真机截图：原神星夜主题](docs\u002Fimages\u002Fgenshin-night-live.jpg)\n\n*真机截图：原神 · 星夜 轻量主题（无文字干净底图 + 自动配色），选择后会同步切换 Codex 深色外观。*\n\n![真机截图：大佬点烟彩蛋主题](docs\u002Fimages\u002Fdalao-live.jpg)\n\n*真机截图：大佬 · 点烟 彩蛋主题（纯黑场 + 火光琥珀配色）。*\n\n## 最快使用\n\nmacOS 安装需要已安装的 Codex Desktop。下载本仓库后：\n\n```bash\nopen \"\u003C仓库路径>\u002Fscripts\u002Finstall.command\"\n```\n\n安装脚本会把工具放到 `~\u002F.codex\u002Fheige-codex-skin-studio`，并默认应用 Miku 预设。应用皮肤时 Codex 会被正常退出并以本机调试模式重新打开，当前任务请先保存。\n\n之后的日常切换都在 Codex 顶部中间的 🎨 菜单里完成。想用自己的图片做皮肤：\n\n```bash\nopen \"$HOME\u002F.codex\u002Fheige-codex-skin-studio\u002Fscripts\u002Fcustomize.command\"\n```\n\n想安装随包附带的 `Miku Future` Pet：\n\n```bash\nopen \"$HOME\u002F.codex\u002Fheige-codex-skin-studio\u002Fscripts\u002Finstall-pet.command\"\n```\n\n安装 Pet 后，完全退出并重新打开 Codex，再到「设置 → 宠物」选择 `Miku Future`。\n\n只暂停当前会话：\n\n```bash\nopen \"$HOME\u002F.codex\u002Fheige-codex-skin-studio\u002Fscripts\u002Fpause.command\"\n```\n\n恢复当前会话：\n\n```bash\nopen \"$HOME\u002F.codex\u002Fheige-codex-skin-studio\u002Fscripts\u002Fresume.command\"\n```\n\n彻底关闭常驻并恢复原生状态。Codex 已关闭时保持关闭，已是原生状态时不额外拉起：\n\n```bash\nopen \"$HOME\u002F.codex\u002Fheige-codex-skin-studio\u002Fscripts\u002Frestore.command\"\n```\n\n`apply.command` 只应用本次会话，不会暗中打开下次启动常驻。\n安装生成的本地「HeiGe 皮肤启动器」调用的就是这个入口：它会恢复 `lastNonNativeThemeId` 记录的最近非原生主题，但保持常驻选择不变。\n\n### 常驻开关与恢复（macOS）\n\n只能在 Codex 顶部菜单打开「皮肤常驻」开关。打开后，当前用户的 LaunchAgent 运行统一控制器，负责状态恢复、目标识别和漂移修复。关闭开关时会先确认，并明确提醒：关闭后本次继续使用；下次启动恢复原生界面。关闭命令：\n\n```bash\n\"$HOME\u002F.codex\u002Fheige-codex-skin-studio\u002Fscripts\u002Flib\u002Frun-cli.zsh\" set-persistence false --port 9341\n```\n\n关闭后若想只在当前会话再次拉起最近的皮肤，可打开安装时生成的本地应用：\n\n```bash\nopen \"$HOME\u002FApplications\u002FHeiGe 皮肤启动器.app\"\n```\n\n这个本地应用只调用稳定的 `apply.command`，不会下载代码、请求管理员权限或将 `persistenceEnabled` 改为 `true`。「启用 HeiGe 皮肤」表示恢复当前会话。`enable-skin.command` 是只恢复当前会话的兼容名，常驻选择保持不变。`enable-persist.command` 是弃用的非零退出入口，不再执行任何启用动作。\n\n### Windows（新增，待实机验收）\n\nWindows 入口位于 `scripts\\windows`。安装只写当前用户目录，并创建「HeiGe Codex Skin Studio\\HeiGe 皮肤启动器」开始菜单快捷方式；`apply.bat` 和兼容名 `enable-skin.bat` 都只作用于当前会话，`pause.bat`、`resume.bat` 与 `restore.bat` 分别暂停、恢复和彻底还原。若要下次启动仍恢复皮肤，必须在已恢复的 Codex 中手动打开顶部常驻开关。系统 Node 必须为 Node.js 22 或更新版本。\n\n传统安装与任务计划程序行为由 Windows PowerShell 5.1、PowerShell 7、32 位解析和隔离的 GUID 任务测试覆盖。Microsoft Store\u002FMSIX 的包发现与激活代码已实现，但真实 Store 应用能否完整接收 CDP 参数仍标记为真机待验证，不能把自动化结果冒充真机结论。\n\n## 交给 Codex 使用\n\n把 `output\u002Fheige-codex-skin-studio.skill` 交给 Codex，可以直接说：\n\n> 用这张图片给 Codex 做一个皮肤并应用。\n\n或者：\n\n> 先生成一张蓝紫色赛博城市主图，再把它做成 Codex 皮肤。\n\nSkill 会优先调用 Codex 当前可用的图片生成能力产出主图，然后调用本地确定性工具创建并应用主题。换肤本身不需要额外 API Key。\n\n## 极简主题格式\n\n```json\n{\n  \"schemaVersion\": 1,\n  \"id\": \"my-skin\",\n  \"name\": \"My Skin\",\n  \"hero\": \"hero.webp\",\n  \"appearance\": \"dark\",\n  \"colors\": {\n    \"accent\": \"#24C9D7\",\n    \"secondary\": \"#EF8FD3\",\n    \"surface\": \"#F7FBFF\",\n    \"text\": \"#17344F\"\n  },\n  \"copy\": {\n    \"brand\": \"My Codex\",\n    \"headline\": \"今天构建什么？\"\n  }\n}\n```\n\n只有 `schemaVersion`、`id`、`name` 和 `hero` 必填。图片必须位于主题目录内，颜色、文案和 `appearance` 都可省略；`appearance` 可设为 `light`、`dark` 或 `system`。\n\n## 主题概念图库\n\n这些 4K 概念图展示「一张图就是一个皮肤方向」的设计效果，内置的 8 款轻量预设使用同场景的无文字干净壁纸版本。\n\n| 原神 | 原神 |\n| --- | --- |\n| ![原神 Codex UI 概念一](assets\u002Fpreviews\u002Fgenshin-impact-codex-ui-1.webp) | ![原神 Codex UI 概念二](assets\u002Fpreviews\u002Fgenshin-impact-codex-ui-2.webp) |\n\n| 鸣潮 | 鸣潮 |\n| --- | --- |\n| ![鸣潮 Codex UI 概念一](assets\u002Fpreviews\u002Fwuthering-waves-codex-ui-1.webp) | ![鸣潮 Codex UI 概念二](assets\u002Fpreviews\u002Fwuthering-waves-codex-ui-2.webp) |\n\n| 火影忍者 | 火影忍者 |\n| --- | --- |\n| ![火影忍者 Codex UI 概念一](assets\u002Fpreviews\u002Fnaruto-codex-ui-1.webp) | ![火影忍者 Codex UI 概念二](assets\u002Fpreviews\u002Fnaruto-codex-ui-2.webp) |\n\n| 恋与深空 | 恋与深空 |\n| --- | --- |\n| ![恋与深空 Codex UI 概念一](assets\u002Fpreviews\u002Flove-and-deepspace-codex-ui-1.webp) | ![恋与深空 Codex UI 概念二](assets\u002Fpreviews\u002Flove-and-deepspace-codex-ui-2.webp) |\n\n## 命令行\n\n下面的 Node CLI 主要用于源码开发与诊断。macOS 生命周期操作优先使用 `scripts` 下对应的 `.command` 稳定入口。Windows 必须使用 `scripts\u002Fwindows\u002Fapply.ps1` 或 `scripts\u002Fwindows\u002Fapply.bat`、`scripts\u002Fwindows\u002Fenable-skin.ps1` 或 `scripts\u002Fwindows\u002Fenable-skin.bat`、`scripts\u002Fwindows\u002Fpause.ps1`、`scripts\u002Fwindows\u002Fresume.ps1`、`scripts\u002Fwindows\u002Frestore.ps1` 或 `scripts\u002Fwindows\u002Frestore.bat`；这些入口负责 Windows Store\u002FMSIX 激活与进程重启。直接运行 Node CLI 遇到需要启动或重启 Codex 的场景会安全拒绝，不会生成 macOS 生命周期动作。\n\n```bash\nnode src\u002Fcli.mjs list\nnode src\u002Fcli.mjs create --image \"\u002Fabsolute\u002Fpath\u002Fhero.webp\" --name \"My Skin\"\nnode src\u002Fcli.mjs apply --theme my-skin-id\nnode src\u002Fcli.mjs enable-skin --theme my-skin-id # 兼容名，只恢复当前会话\nnode src\u002Fcli.mjs set-persistence false\nnode src\u002Fcli.mjs status\nnode src\u002Fcli.mjs pause\nnode src\u002Fcli.mjs resume\nnode src\u002Fcli.mjs restore\nnode src\u002Fcli.mjs doctor\n```\n\n## 常见问题\n\n### 换肤会弄坏 Codex 或破坏签名吗？\n\n本工具本身不修改 `app.asar`、二进制或签名资源。皮肤通过 [Chrome DevTools Protocol](https:\u002F\u002Fchromedevtools.github.io\u002Fdevtools-protocol\u002F) 在运行时注入；选择关闭常驻后，本次会话仍保留皮肤，下次正常启动回到官方原生界面。\n\n### 支持 Windows 吗？\n\n支持传统安装，并实现了 Microsoft Store\u002FMSIX 的确定性发现与系统激活路径。Windows 自动化覆盖 Windows PowerShell 5.1、PowerShell 7、32 位解析与隔离任务，但 Microsoft Store 真机待验证。商店版和使用系统运行时的安装要求 Node.js 22 或更新版本。不要使用内置 Administrator 账户启动 Store 应用。\n\n### 装完 ChatGPT 桌面端提示「Windows 安装未完成」怎么办？\n\n这是 ChatGPT 应用自身的初始化步骤（需要一次性管理员权限），和本工具无关，但不过这一步就用不上皮肤。先试用户实测有效的修法：删除用户目录下的 Codex 配置文件（路径 `C:\\Users\\你的用户名\\.codex\\config.toml`，删除前先改名成 `config.toml.bak` 备份），再重启应用。这个文件损坏或含新版本不认的配置项时，初始化会一直失败，且重装也治不了（重装不清用户目录）。仍不行再按顺序排查：弹出的用户账户控制对话框里默认高亮的是「否」，直接回车等于拒绝，要明确点「是」；别用内置 Administrator 账户，换普通管理员账户；如果系统把 UAC 整个关了（EnableLUA=0），授权弹窗永远出不来，先把用户账户控制调回默认档再重试。都不行可以点「继续受限访问」先把应用用起来再跑换肤脚本，受限模式对注入的影响未经实机验证，遇到问题开 Issue 反馈。\n\n### 怎么用自己的图片做主题？\n\n三条路：顶部中间的 🎨 菜单选「＋ 自定义图片」直接上传（自动按图片取色）；双击 `customize.command` 走图形界面；或用命令行 `node src\u002Fcli.mjs create --image 图片路径 --name 主题名`。\n\n### 自定义图片的文字或底色有色差、看不清怎么办？\n\n从 `5.2.1` 开始，内置主题和菜单上传的自定义图片都会自动同步 Codex 深浅外观。若图片主体亮度与背景差异很大，自动判断仍可能不符合你的偏好，此时可在 Codex 自己的「设置 → 外观 → 主题」里手动调整。\n\n![外观主题配色设置](docs\u002Fimages\u002Fappearance-theme-contrast.jpg)\n\n*Codex 设置 → 外观：自动联动不符合预期时，可在这里手动切换系统／浅色／深色。*\n\n同一页下方的「深色主题」区还能改强调色、背景、前景和对比度，可以进一步微调。\n\n### Codex 更新版本后主题还能用吗？\n\n多数只更新内容的版本不需要重新打补丁，因为本项目不修改安装包。但 CDP 启动参数、renderer 分类和界面选择器仍属于兼容边界；未来 Codex Desktop 变化时可能需要更新本项目。若升级后失败，请先运行 `doctor` 并在 Issue 中附上脱敏结果。\n\n### 提示「端口未就绪」「无法注入」怎么办？\n\n九成是旧实例没退干净：Codex 有任务在跑时退出会弹确认框，老实例还活着，新实例的调试参数会被它接管丢弃。手动完全退出 Codex（Cmd+Q 并确认，活动监视器里确认没有 ChatGPT 进程）再重跑脚本即可。如果报错说「已带调试参数启动但端口未开放」，说明你的 Codex 版本可能禁用了本机调试端口，请开 Issue 附上版本号，我们会跟进启动兼容方案。\n\n### 怎么让皮肤重启后也一直在？\n\n只能在顶部菜单打开常驻开关。关闭开关会先确认，并提示「关闭后本次继续使用；下次启动恢复原生界面」。以后先打开「HeiGe 皮肤启动器」恢复当前会话，再由用户打开顶部菜单常驻开关，才会恢复下次启动常驻。\n\n### 本机回环端口是否等于安全？\n\n不等于。CDP 只绑定 `127.0.0.1`，可以减少网络暴露，但 CDP 本身无认证；本机同权限进程仍可能访问调试端口并调用 `Runtime.evaluate`。菜单控制接口另有 token、严格 schema 与 revision 校验，但它不能给 CDP 增加浏览器级隔离。完整边界见 [SECURITY.md](SECURITY.md)。\n\n## 设计边界\n\n这是一个本机工具，不是安全沙箱。控制器只修复被严格分类为 Codex 主 renderer 的目标，并对图片、manifest、菜单数据和日志设置上限。macOS 验证日期与证据见 `docs\u002Frelease`；Windows 自动化证据与 Microsoft Store 真机待验证状态分开记录。\n\n本仓库前身走 ASAR 修改路线，当前实现已改为 CDP。远程 `v4.0.0` 与 `v5-asar-legacy` 在 2026-07-16 仍指向同一 commit，因此不能把后者当成已经核实的独立遗留快照；远程处置建议见 [审计加固处置报告](docs\u002Frelease\u002F2026-07-16-audit-hardening-disposition.md)。\n\n## 开发\n\n```bash\nnpm test\nnpm run doctor\n```\n\n## English\n\n**HeiGe Codex Skin Studio** reskins Codex Desktop through loopback CDP injection without modifying `app.asar`, binaries, or signature resources. A top menu switches themes, synchronizes Codex light or dark appearance, and controls next-launch persistence. The package also includes the optional `Miku Future` animated Pet without replacing built-in pets. Turning persistence off keeps the current session skinned and restores the native UI on the next launch. The local `HeiGe 皮肤启动器` and the compatibility `enable-skin` entry restore the last skin for the current session only. The top-menu switch is the only supported way to enable next-launch persistence.\n\nQuick start: run `scripts\u002Finstall.command` on macOS or `scripts\\\\windows\\\\install.bat` on Windows. macOS has dated live evidence in `docs\u002Frelease`. Windows PowerShell automation is covered, while Microsoft Store\u002FMSIX activation remains pending live-machine validation. A system Node runtime must be Node.js 22 or newer. CDP is unauthenticated even on loopback, so local same-user processes remain inside the threat boundary.\n\n## 交流群\n\n扫码进微信群「Codex 皮肤共创交流」：纯技术交流，非盈利，互相学习。分享你做的主题、聊实现、提问题都欢迎。二维码过期了就开个 Issue，我会换新的。\n\n\u003Cimg src=\"docs\u002Fimages\u002Fwechat-group-qr.png\" width=\"340\" alt=\"Codex 皮肤共创交流微信群二维码\">\n\n## 作者\n\n由 [黑哥AI（HeiGeAi）](https:\u002F\u002Fgithub.com\u002FHeiGeAi) 打造，公众号「黑哥Ai」。同系开源项目见 [HeiGeAi 组织主页](https:\u002F\u002Fgithub.com\u002FHeiGeAi)，内容被 AI 引用优化用的是自家的 [HeiGe-GEO-SEO](https:\u002F\u002Fgithub.com\u002FHeiGeAi\u002FHeiGe-GEO-SEO)。\n\n## 许可证与素材\n\n代码使用 [MIT License](LICENSE)。该许可只覆盖软件代码，不授权角色、商标或第三方视觉素材。逐文件来源与授权状态见 [ASSET_PROVENANCE.md](ASSET_PROVENANCE.md)，发布边界见 [NOTICE.md](NOTICE.md)。\n\n**素材风险提示**：免责声明与非商业用途声明不能替代转载、再分发或商标使用许可。来源或授权无法核实的素材在 provenance 表中标为未验证，分发者应自行取得许可或替换。若涉及安全问题，请按 [SECURITY.md](SECURITY.md) 私密报告；一般素材权利问题可提交 [Issue](https:\u002F\u002Fgithub.com\u002FHeiGeAi\u002Fheige-codex-skin-studio\u002Fissues)。\n","HeiGe Codex Skin Studio 是一款专为 OpenAI Codex Desktop（ChatGPT 桌面客户端）设计的本地主题换肤工具。它基于 Chrome DevTools Protocol（CDP）实现零修改注入，支持一键切换预设主题（含初音未来、原神、鸣潮等9款动漫\u002F游戏风格主题）及上传任意图片自动生成配色+背景皮肤，并同步适配 Codex 的深\u002F浅色外观模式。所有操作无需篡改应用二进制、asar 包或签名资源，具备常驻控制、菜单隐藏、会话生命周期管理等实用功能。适用于追求个性化界面、高效主题切换与轻量定制体验的 Codex Desktop 用户。",2,"2026-07-17 02:30:11","CREATED_QUERY"]