Codex Skin Studio

一个面向 Codex Desktop 的本地可视化主题编辑器。它使用 Tauri 2 与 Next.js 构建，可以在隔离预览中实时调整主题，并通过本机 Chrome DevTools Protocol（CDP）把样式应用到正在运行的 Codex。

Important

本项目是非官方社区项目，与 OpenAI 无隶属、授权或背书关系。“OpenAI”和“Codex”是其各自权利人的名称或商标。

当前状态

项目仍处于早期阶段，当前主要适配 Windows x64 的 Microsoft Store 版 OpenAI.Codex。代码中包含 macOS 适配与打包配置，但尚未完成与 Windows 同等程度的端到端验证；Linux 暂不支持。

在公开发布前，请先阅读安全说明和下方的已知限制。

功能

• 从用户明确选择的本地目录加载主题，不依赖远程主题仓库或云服务。
• 在 sandbox iframe 中实时预览主题，主题 CSS/JS 不会进入 Studio 主文档。
• 根据主题定义动态生成编辑器，支持文件、颜色、渐变、范围、输入框、文本域、开关和选择器八类控件。
• 支持 Codex 首页、会话页、工作区首页和聊天首页四类预览页面。
• 支持保存、另存为、导出、删除个人主题，以及手动重新加载本地主题目录。
• 通过只绑定 127.0.0.1 的 CDP 注入主题，不修改 Codex 安装包、app.asar 或代码签名。
• 可以通过“恢复原版”只清理本项目创建的样式和运行时资源。
• 不包含账户系统、认证服务、遥测、云同步或远程主题加载。

界面展示

下列截图展示了 Studio 中不同本地主题在首页与任务页的效果。主题由独立的 kiss-keray/codex-theme 仓库维护，需要自行克隆到本地后再加载。

主题	首页	任务页
毛玻璃默认
玫瑰柔光
纸鹤微光
虚空脉冲
雷朋 99
青蓝电子歌姬

工作原理

本地主题目录
    │
    ├── types/  ── 主题结构与 CSS/JS 运行时
    └── datas/  ── 主题名称、描述和控件原始值
             │
             ▼
       前端校验并合成 UnifiedTheme v2
          ├── sandbox iframe 实时预览
          └── Tauri → 127.0.0.1:9335 → Codex app: 页面

真实应用主题时，Studio 会：

1. 检查 Codex 是否安装、是否运行以及本机调试端口是否可用。
2. 必要时使用 --remote-debugging-address=127.0.0.1 和固定端口 9335 启动 Codex。
3. 只接受 ws://127.0.0.1:9335/devtools/page/... 形式的 CDP 页面地址。
4. 确认目标是 app: 页面且存在预期主界面节点后，再执行主题运行时。
5. 恢复时只移除 codex-skin-studio / --skin- 命名空间下由本项目创建的资源。

扩展到其他 CDP 应用

Codex Skin Studio 的 CDP 连接、主题 JSON 桥接和注入生命周期在架构上可以复用于其他支持 CDP 的桌面应用。后端通过 src-tauri/src/app/mod.rs 中的 App trait 隔离应用发现、启动和进程状态：

#[async_trait]
pub trait App {
    fn port(&self) -> u16;
    fn name(&self) -> String;
    async fn start_app(&self) -> StartAppStatus;
    async fn close_app(&self) -> bool;
    async fn app_status(&self) -> RuntimeStatus;
    async fn apply_lock(&self) -> Arc<Mutex<u8>>;
}

适配一个新的 CDP 应用时，核心后端工作是：

1. 在 src-tauri/src/app/ 下新增应用模块并实现 App。
2. 在 APPS 注册表中登记应用名称和适配器实例。
3. 为目标应用保留严格的 CDP 地址、页面身份和 DOM 校验，不能为了兼容而放宽回环地址安全边界。
4. 如果目标应用的页面协议、DOM 或主题选择器与 Codex 不同，在对应适配器或运行时中提供应用专属判断。
5. 在前端登记应用名称、显示名称和 CDP 端口。

因此，支持 CDP 是复用这套架构的基础，但不代表任意应用无需适配即可直接使用。当前仓库只内置了 CodexApp，欢迎贡献其他应用适配器。

快速开始

环境要求

• Node.js 20 或更高版本
• npm 10 或更高版本
• Rust stable 工具链
• 对应平台的 Tauri 2 系统依赖
• 已安装 Codex Desktop（只有运行桌面版时才需要）

安装

git clone https://github.com/kiss-keray/Codex-Skin-Studio.git
cd Codex-Skin-Studio
npm install

只启动浏览器预览：

npm run dev

启动完整 Tauri 桌面开发版：

npm run tauri:dev

浏览器模式只用于检查工作台界面和静态预览。由于浏览器没有原生目录读取与 CDP 权限，它不能选择本地主题目录、管理本机主题文件或把皮肤应用到 Codex。

使用方式

1. 运行桌面版，在左侧“本地主题目录”中选择一个同时包含 types/ 和 datas/ 的目录。
2. 从“本地目录主题”中选择主题，使用右侧检查器调整参数。
3. 修改本地主题源码后，点击“重新加载”即可立即读取当前目录，不需要重启 Studio。
4. 点击“另存为”把当前主题保存到个人主题库；目录主题本身不会被 Studio 覆盖。
5. 确认 Codex 已通过本机调试端口连接，然后点击“应用皮肤”。
6. 需要撤销时点击“恢复原版”。

个人主题默认保存到用户主目录下的 .cache/codex-skin/。导出会生成 .codexskin.json 文件；当前版本不提供导入功能。

本地主题目录

已经开发完成的主题单独维护在 kiss-keray/codex-theme。可以先把主题仓库克隆到本地：

git clone https://github.com/kiss-keray/codex-theme.git

然后在 Codex Skin Studio 的“本地主题目录”中选择该仓库内同时包含 types/ 和 datas/ 的主题根目录。主题仓库和 Studio 主程序彼此独立，Studio 不会在后台联网下载或自动更新主题。

最小目录结构如下：

my-themes/
├── types/
│   └── my-theme-type/
│       ├── config.json
│       ├── init.css
│       ├── init.js
│       ├── ready.css
│       └── ready.js
└── datas/
    └── my-theme.json

• types/<type>/config.json 定义编辑器 Tab、分组和控件。
• init.css / ready.css 是主题样式源码，可通过运行时生成的 --data-<控件 ID> 变量读取转换值。
• init.js / ready.js 是接收主题上下文的 JavaScript 函数源码。
• datas/**/*.json 只保存主题元信息、所属 type 和控件原始值。

完整字段、示例和安全约束请参阅主题开发指南。实现主题的视觉与运行时逻辑时，还可参考主题仓库的 theme-config.md，其中提供了完整的主题配置、CSS 与 JavaScript 示例。

使用 Codex 协助创建主题

可以让 Codex 参考 theme-config.md 协助创建或调整主题。例如：

请参考 https://github.com/kiss-keray/codex-theme/blob/main/theme-config.md，为 Codex Skin Studio 创建一个「主题名称」主题；遵循本仓库 docs/theme-format.md 的 types/ 与 datas/ 目录结构、UnifiedTheme v2 契约和安全限制，并在生成后说明需要放入的文件及其用途。

theme-config.md 用于参考主题的实现方式；Studio 实际读取的目录结构、字段规则和安全限制仍以本仓库的主题开发指南为准。

Warning

主题的 CSS 和 JavaScript 会在本地预览 iframe 与 Codex 渲染进程中执行。只加载你信任、且已审查源码的主题目录。

开发命令

命令	用途
npm run dev	启动 Next.js 浏览器开发模式
npm run lint	运行 ESLint
npm run build	构建并压缩静态前端产物到 out/
npm run tauri:dev	启动完整桌面开发版
npm run tauri:build	构建当前平台的桌面安装产物
cargo check --manifest-path src-tauri/Cargo.toml	检查 Rust 后端
cargo test --manifest-path src-tauri/Cargo.toml	运行 Rust 测试
npm audit --omit=dev --registry=https://registry.npmjs.org	审计生产依赖

提交前建议至少执行：

npm run lint
npm run build
cargo check --manifest-path src-tauri/Cargo.toml
cargo test --manifest-path src-tauri/Cargo.toml

涉及界面时，还应在 1280 × 720 和 1540 × 960 下检查三栏布局、检查器滚动及四类预览页面。涉及 CDP 运行时时，请在真实 Codex 上验证应用与恢复流程。

项目结构

src/
├── app/                    # 工作台页面与 Studio 自身样式
├── lib/                    # 前端唯一的 Tauri command 调用边界
└── themes/
    ├── inspector/          # 动态主题检查器与八类输入控件
    ├── preview/            # sandbox iframe 预览桥接
    ├── provider.ts         # 用户所选本地目录的主题读取适配器
    ├── registry.ts         # 类型定义与数据实例的合成入口
    ├── schema.ts           # UnifiedTheme v2 校验
    └── types.ts            # 主题领域类型

public/preview/             # 自包含的预览文档与运行时

src-tauri/src/
├── app/codex.rs            # Codex 安装发现、启动与状态适配
├── cdp.rs                  # CDP 目标校验与表达式执行
├── themes/runtime.rs       # 主题 JSON 到 CDP 表达式的桥接
├── themes/runtime/         # apply / ready / probe / restore 脚本
└── themes/storage.rs       # 本地主题目录与个人主题文件操作

安全边界

• CDP 只绑定回环地址，不会监听局域网或公网。
• WebSocket 目标必须匹配固定协议、主机、端口和 DevTools 页面路径。
• 注入前会验证 app: 协议和 Codex 主界面节点。
• 图片限制为 PNG、JPEG、WebP，最大 16 MB，并校验文件头、MIME、像素边长与总像素数。
• 主题 JSON 和本地文件路径均有大小、格式及路径穿越限制。
• “恢复原版”只清理本项目登记的节点、样式、变量、对象 URL 和观察器。
• 应用不会修改 Codex 的 API Key、Base URL、模型供应商或账户配置。

如果发现安全问题，请不要创建公开 Issue，按 SECURITY.md 中的方式私下报告。

已知限制

• Windows Store 版 Codex 是当前主要目标；macOS 的完整文件流程和真实注入仍需更多回归测试。
• Codex 更新可能改变页面 DOM，使部分主题选择器失效。
• 重新加载 Codex 页面会清除当前渲染进程中的注入，需要在 Studio 中再次点击“应用皮肤”。
• iframe 使用本地静态预览结构，不保证与每个 Codex 版本像素级一致。
• 自定义主题脚本拥有较强的页面修改能力，恶意或错误脚本可能破坏当前页面布局。
• 恢复操作清理当前 DOM 注入；如需彻底关闭调试端口，应正常重启 Codex。

参与贡献

欢迎提交问题、主题格式改进和平台适配。在开始前请阅读：

• 贡献指南
• 行为准则
• 安全策略
• 公开发布检查清单
• 更新日志

致谢

项目在架构思路上参考了 Fei-Away/Codex-Dream-Skin 使用回环 CDP、运行时 CSS 注入、页面重载后重新应用及恢复原版的思路。本仓库不依赖、不内嵌该项目，也不把它作为运行时资源。

许可证

本项目采用 PolyForm Noncommercial License 1.0.0 发布：允许非商业用途的使用、修改和分发；未经单独授权，不得将本项目或其衍生成果用于商业或营利目的。该许可证含有商业用途限制，因此本项目属于公开源码（source-available），而非 OSI 定义的开源软件。