Codex Theme Studio

为 macOS 官方 Codex 桌面端创建、调试、应用和安全移除个人主题的通用 Skill。

它不修改 Codex 官方 .app、app.asar、可执行文件或代码签名，而是通过受约束的本地运行时加载主题。因此，主题可以反复迭代，也可以完整恢复为官方界面。

效果展示

新建任务与连续背景

同一张背景贯穿侧边栏和主面板；工具栏、输入框与内容区域使用分层磨砂效果，同时保留原生操作能力。

文件、代码与 Terminal 面板

右侧文件树、代码主体、行号区、底部 Terminal 和置顶摘要可以继续显示背景，而不是被纯黑底色遮挡。选中、悬停、焦点、活动行和 Diff 语义色仍会保留。

独立 Dock 启动器与 App Icon

可以创建用户自有的主题启动器、生成完整 ICNS 图标并固定到 Dock。通过该入口启动时，主题会自动恢复；官方 Codex 应用本身保持不变。

能做什么

• 用自定义图片生成 Codex 全窗口背景。
• 配置配色、文字、侧边栏透明度、主面板透明度、顶部栏透明度和模糊强度。
• 添加低成本的轻量动效，并自动兼容 prefers-reduced-motion。
• 处理新建任务、已有任务、状态摘要、文件面板和 Terminal 等不同页面结构。
• 修复输入框黑色衬底、顶部阴影、标签栏遮挡和面板割裂等常见问题。
• 进入开放的 Shadow DOM，精确处理文件树、代码主体和行号区域的底色。
• 创建独立 Dock 启动器和自定义 App Icon，解决 Command + Q 后主题失效的问题。
• 通过结构化检查和截图完成视觉验证，避免仅凭 CSS 推测结果。
• 安全移除主题并恢复官方界面，同时保留用户生成的主题素材。

典型使用方式

可以直接向 Codex 描述目标，例如：

用 codex-theme-studio 给我的 Codex 做一个透明磨砂主题，
背景使用这张图片，动效轻一点，并创建一个可以固定到 Dock 的启动器。

也可以针对现有主题继续迭代：

右侧文件列表和代码行号还是黑底，帮我定位真正的绘制层并修复，
但不要破坏选中、悬停和 Diff 颜色。

核心设计

• 数据与运行时分离：壁纸、配色和图标属于主题数据；注入、校验和清理由统一运行时负责。
• 不修改官方应用：拒绝改写、重签名或替换官方 Codex Bundle。
• 只监听本机回环地址：调试端点限定在 loopback，并验证目标确实是 Codex 渲染进程。
• 最小范围修复：优先使用稳定结构和基础颜色变量，不粗暴清空所有文件行、Diff 单元或 Terminal Canvas。
• 可逆清理：记录被修改的内联值与优先级，热更新和移除时精确恢复。
• 以视觉证据收口：每次修改都应覆盖相关页面、原生控件和窗口状态，而不是只检查脚本返回成功。

主要入口

• SKILL.md：Codex 使用的核心工作流与安全规则。
• scripts/create-theme.mjs：生成并校验主题数据。
• scripts/codex-theme.sh：应用、验证和移除主题。
• scripts/codex-theme-launcher.sh：安装、更新和移除 Dock 启动器。
• references/visual-debugging.md：视觉问题的证据化诊断流程。
• references/runtime-safety.md：运行时、热更新与清理边界。

环境与边界

• 适用于 macOS 官方 Codex 桌面端。
• Codex 更新后内部 DOM 可能变化，应重新执行验证矩阵，不能盲目沿用旧选择器。
• 从官方 Codex Dock 图标启动时会显示官方界面；需要持久主题时，应从生成的主题启动器进入。
• 展示截图仅用于说明主题能力，不是 Skill 的默认主题素材。示例中的角色与品牌权利归各自权利人；实际使用时应确保拥有图片和图标的使用权限。