codex-theme-switcher

切换当前 Codex 主题

将托管本地库 ~/.codexthemes/themes/<theme-id>/ 中的主题应用到正在运行的 Codex 桌面应用，在已安装的主题之间切换、恢复原生外观，并验证实际生效的主题。此技能独立运行：其 TypeScript 脚本负责管理可逆的注入运行时。它不会创建或编辑主题（codex-theme-creator）、从图库安装主题（codex-theme-installer），也不会发布主题（codex-theme-submitter）。所需的本地工具只有 Node.js 20+、npx 和官方 Codex 桌面应用。

所有命令都要在已安装的技能目录中运行。运行时只会通过 Codex 仅限 loopback 访问的调试端点注入自有的 <style> 元素；它绝不会修改经过签名的应用包，并且会为所有已打开的 Codex 页面应用主题，而不只是某一个窗口。

第 1 步：选择主题

npx tsx scripts/switch-theme.ts list

列出所有已安装的主题（ID、名称、布局模式）以及当前激活的主题。主题由 codex-theme-creator（在本地创建）或 codex-theme-installer（从 codexthemes.ai 下载）加入库中。如果用户想要的主题未列出，请转交给这些技能处理，不要猜测路径。

第 2 步：应用或切换

npx tsx scripts/switch-theme.ts apply <theme-id>

• 如果 Codex 已开放其调试端点（此前任何一次应用主题后都会开放），此命令会就地热切换所有已打开页面的主题，无需重启，输出 {"status": "active", "pagesThemed": n}。
• 如果没有端点（本次应用会话中首次应用主题，或 Codex 已完全退出），请征得用户明确同意后再重启 Codex，然后使用 --launch 重新运行：

npx tsx scripts/switch-theme.ts apply <theme-id> --launch

--launch 会输出 {"status": "scheduled"}，并将退出 → 重新启动 → 注入这一流程交给一个独立运行的辅助程序；该程序会在重启后继续运行（托管在 Codex 内部的 Agent 会随 Codex 一起退出；工具调用可能会被中断）。切勿自行构建重启机制——不要使用 shell 包装脚本、launchd 或计划任务，也不要复制脚本；辅助程序本身就能在重启后继续运行。

启动器支持 macOS 和 Windows。在 Windows 上，它会查找 Codex/ChatGPT 可执行文件（运行中进程的路径、%LOCALAPPDATA%\Programs\... 或 WindowsApps 执行别名；如果检测失败，请使用完整的 .exe 路径传入 --app），使用 taskkill 优雅地关闭程序（绝不使用 /F），然后通过调试标志重新启动。如果重启后端点始终未出现，说明该安装版本（例如 Microsoft Store 包）会丢弃调试标志——请如实说明此限制；绝不要修改 WindowsApps 或安装目录中的文件。

内置可读性检查

每次应用主题后，都会测量注入后实际渲染的像素（基于截图检测可见文本的对比度）。如果主题导致文本无法阅读，应用操作会自动恢复到此前激活的主题（或原生外观），并报告 {"status": "reverted", "failures": [...]} 以及测量结果。请告知用户该主题发布时就存在问题，并提出使用 codex-theme-creator 修复；只有用户明确表示仍想保留这个无法阅读的主题时，才传入 --force。

第 3 步：验证——scheduled 不代表成功

npx tsx scripts/switch-theme.ts status

status 会探测所有正在运行的 Codex 页面，并报告 active（所有页面都已应用主题，且主题 ID 相同）、partial（页面之间不一致——请重新应用以使其一致）或 inactive，并提供每个页面的证据。只有当 status 显示 active 且主题 ID 符合预期时，才能向用户报告成功。如果 --launch 后仍显示 inactive，请查看 ~/.codexthemes/state/launch.log，了解辅助程序的结果。

如果成功热切换后旧主题仍不断出现（先前任务留下的过期会话仍在重新注入该主题，且无法从该会话外部移除其注册项），请先征得用户同意后再强制干净地重新启动——绝不要让用户手动退出应用：

npx tsx scripts/switch-theme.ts apply <theme-id> --launch --relaunch

即使端点已在运行，--relaunch 也会重启 Codex，从而清除所有过期会话，然后注入所请求的主题。该操作遵循相同的 scheduled → status 验证流程。

第 4 步：始终告知用户如何恢复

每次成功应用主题后，都必须说明 active 输出中的背景作用范围，让用户不会意外发现插图仅显示在主页上。用通俗语言转述 backgroundScopeNote，例如：“背景插图仅显示在主页上；颜色会应用于所有页面。若要让插图也显示在对话页面上，请让 codex-theme-creator 使用 backgroundScope: workspace 重新构建。”然后提供撤销提示，例如：“回复 rollback 可恢复到之前使用的主题，回复 restore 可恢复 Codex 原生外观——完全退出 Codex 也会移除主题。”如果用户不喜欢效果，绝不能让他们还得询问如何撤销或更改作用范围。

每次应用都会记录之前启用的主题。当用户回复 rollback（或表示新主题无法使用、不美观或不合心意）时：

npx tsx scripts/switch-theme.ts rollback

这会重新应用之前启用的主题；如果没有之前的主题，则恢复原生外观。该操作会经过相同的应用流程，因此仍会执行可读性检查和 status 验证。（未通过可读性检查的主题不需要手动回滚——应用流程会自动恢复。）

当用户要求恢复原生外观（或回复 restore）时：

npx tsx scripts/switch-theme.ts restore

这会从所有页面移除注入的样式和页面标记，并清除运行时状态——无需重启。完全退出应用也会移除主题；用户想重新启用时，可使用 --launch 重新应用。如果恢复后主题仍不断出现，说明有过期会话在重新注入主题——在征得用户同意后，使用第 2 步中的 --launch --relaunch 流程，或者让用户完全退出并重新打开 Codex。

限制

• 任何重启前都必须征得用户同意；热切换无需请求用户请求之外的额外许可。
• 涉及重启时，绝不能仅凭 apply 输出声称主题已启用——请使用 status 验证。
• 绝不修改 app.asar、已签名的应用程序包、用户任务或身份验证数据。
• 请勿在此处编辑主题源文件；设计修改请交由 codex-theme-creator 处理。