徐風沐雨

Appearance

Codex Theme

閱讀 5 次

給 Codex 桌面端換一張臉，而且換得安全一點：不改官方包、不塞腳本、一鍵能回到原樣。

Codex Theme（倉庫 xu-theme + xu-theme-web）是一個非官方的 Codex 主題管理器，macOS 和 Windows 都能用，Tauri 寫的。起因很直白：Codex 只有一套深色外殼，看兩週就膩了。上游 Codex-Dream-Skin 已經解決了「怎麼安全地換皮膚」—— 走 CDP 注入，不碰 .app、不碰 app.asar、不碰 WindowsApps、不動代碼簽名 —— 但它本質是一套腳本加手動流程，主題得自己拼 CSS。於是把「發現主題 → 導入 → 應用 → 驗證 → 恢復」做成一個 App，外面再套一個網頁主題目錄。

這個項目不是 OpenAI 官方產品，也沒有獲得任何認可或授權。

Theme Studio 創建主題頁面

它能做什麼 ​

一句話：選一張圖，或者點一個網頁連結，Codex 就換好臉了；不想要了一鍵還原。

  1. 主題發現：Next.js 寫的目錄站列主題和詳情，詳情頁用 codextheme:// 深鏈接把主題交給桌面端
  2. 導入：深鏈接只帶一份版本化 JSON 清單，桌面端校驗通過才落盤，寫入是原子的
  3. 本地做主題：Theme Studio 選一張壁紙（PNG / JPEG / WebP，最大 16 MiB），調壁紙焦點、頭像位置和裁切、文字朝向、主題文案，中間是一個實時 Codex 窗口預覽
  4. 一鍵應用：走上游的固定動作橋 —— 環境檢查、安裝、結果驗證，三段都要過
  5. 一鍵恢復：還原官方外觀。Codex 正在跑、操作可能觸發重啟時，應用會先彈確認

在安全上跟自己較真的地方 ​

這部分是這個項目真正花時間的地方，不是裝飾：

  • 遠程主題不許帶代碼。只接受版本化 JSON 清單和圖片，CSS / JavaScript / Shell / PowerShell 一個字段都沒有
  • 導入前六道校驗：公網 HTTPS、拒絕私網地址、許可字段、文件大小、真實圖片格式（看字節不看擴展名）、尺寸和 SHA-256
  • 內核是釘死的。src-tauri/resources/dream-skin/ 是上游的清理副本，UPSTREAM_REVISION 記著提交號，禁止手改；升級只允許跑 scripts/sync-dream-skin.sh，然後 npm run check:engine 校驗版本、權限守衛和運行時閉包
  • 自己的視覺層不進內核文件。0.2.2 把 v1.2.0 時期手改的樣式整體搬進 scripts/patches/codex-theme-visual-layer.css（現在 119 行），由同步腳本逐字追加到兩端 assets/dream-skin.css。這樣下次升內核不會把手改蓋掉，也不會把上游改動吃掉 —— 0.2.4 升 v1.5.21 就是這條機制的第一次實戰檢驗：手工補丁該刪的刪掉、該留的留著，內核文件全程沒被人改過一個字節
  • 上游排除在 MIT 之外的人物素材，既不進倉庫也不進安裝包，THIRD_PARTY_NOTICES.md 老老實實記了固定提交、許可和全部下游改動
  • 校驗鏈全在 Rust 側，前端只負責顯示

版本記錄 ​

版本號是 App 的 semver，下面的日期是從 git 提交和設計文檔回溯出來的，一條對應一次能跑的改動。

2026-10-22

0.2.4 發包，內核 v1.5.18 → v1.5.21（6fc42df）。三處改動。上游 v1.5.19 修好了 0.2.1 我們手工兜住的頂部漸變誤傷，sync-dream-skin.sh 裡那一步補丁隨之刪除，改由 check-dream-skin.sh 斷言 [data-app-shell-main-content-top-fade] 必須帶 :not(:has(*)) 守衛；同一版起上游按平台分叉了 assets/dream-skin.css（Windows 多出 group/home-composer-layout 限定），跨端逐字節比對不再包含它，改比新增的 assets/theme-preferences.mjs。真正值得單獨說的是 loopback-proxy-bypass.json：Codex 自帶的 Node 24.21 在 NODE_USE_ENV_PROXY=1 + HTTP_PROXY 下會把回環 fetch() 和 WebSocket 一起塞進代理，注入器讀 /json/list 直接 fetch failed，任何主題都應用不了 —— 上游 v1.5.21 只解決了 PowerShell 把 UNDICI-EHPA 警告當成失敗，沒有為回環繞過代理，所以補丁在兩端注入器裡追加 NO_PROXY/no_proxy 的回環項，且不動用戶原有的條目。另一處 Windows 阻塞：上游安裝契約無條件要求 assets\theme-manager\DreamSkin.ThemeManager.exe，而我們不分發那個 C# 托盤程序，windows-theme-manager-optional.json 把該必需項移除。

2026-09-30

0.2.3 補上 polaroid 的「頭像裁切」鏈路 —— 這一版當天提交完沒有發包，擱了快一個月。上游從 v1.4.0 起把 Theme Studio 存的第二個坐標 art.portraitFocusX/portraitFocusY 整條丟掉了：注入器不解析、渲染器不發佈，應用側寫進 theme.json 的裁切值到不了頁面，所以「點頭像裁切選中的位置」和「右下角相框裡的位置」始終差一截。修復按平台把坐標穿過 injector.mjs 與 renderer-inject.js，發佈 --dream-portrait-focus-x/y 和 data-dream-portrait-ready，polaroid 規則改掛在該屬性上（未設裁切的主題不再顯示裝飾），macOS 橋接在引擎寫完後把裁切覆蓋回 theme.json（Windows 直接傳應用自己的 theme.json，不需要覆蓋）；相框縮放與 Theme Studio 預覽統一成 260%，同一個坐標在預覽和實機框住同一片畫面。錨點用 exactly-once 斷言兜著 —— 上游一改寫就讓同步失敗，而不是把功能靜默丟掉。

2026-09-30

0.2.2 發包。v1.2.0 時期手改在內核裡的視覺層，整體搬進 scripts/patches/codex-theme-visual-layer.css，由同步腳本逐字追加到兩端 —— 手改內核文件意味著每次升內核都要重做一遍。順帶查清「圖片看不清」的真正原因是 Codex 26.924 在窗口圖和外殼之間還壓著三層原生遮罩（整窗 80% 中性暗加側欄 65%），清掉後側欄像素由 (28,33,37) 回到 (46,87,118)；上游為帶遮罩內核調的暗色權重相應調淺，會話右側面板改主題面板色加模糊，頭像 polaroid 用兩個定位置偽元素重建，不再依賴 v1.5 已刪除的注入宿主。參數全取自 1920×988 實機截圖。

2026-09-29

內核升級到 Dream Skin v1.5.18。修掉一個上游缺陷：寬畫主題的「移除頂部漸變」規則把 data-app-shell-main-content-top-fade 當成漸變元素，而 Codex 是把它作為狀態標記打在會話內容容器上，display: none !important 於是把整個會話列折疊了，輸入框和消息全塌成 0×0。修復以補丁落在 sync-dream-skin.sh 裡，check-dream-skin.sh 會擋住它被同步覆蓋回去。順帶清掉目錄裡的版權素材。

2026-07-22

淺色模式可讀性連修三處：終端文字在淺色下必須保持可辨、三級按鈕別被背景吃掉。

2026-07-21

macOS 包改 ad-hoc 簽名；Windows 端視覺對齊 macOS；引擎狀態缺字段時容錯。

2026-07-20

一天的玻璃攻堅：首頁玻璃控件、右側工具面板、文件查看器、上下文面板全部換成主題色玻璃而不是死黑；文件樹截斷背景清掉；寵物疊層跨路由保持透明；粘性內容滾動時不再被擋。結尾把「我的主題」提成桌面端首頁。所有參數取自 1920×988 實機截圖。

2026-07-19

修回主題應用流程和 App 圖標。

2026-07-18

項目起步，當天跑通 MVP：平台設計規格 + 實施計劃、Tauri 腳手架、vendored 清理內核、安全主題清單管線、macOS / Windows 動作橋、codextheme:// 深鏈接、已安裝庫裡直接應用，外加主題市場和本地自定義。

技術棧 ​

  • 桌面端：Tauri（Rust 後端 + 系統 WebView）、React + TypeScript + Vite，測試走 vitest 和 cargo test
  • 內核：vendored 的 Codex Dream Skin（MIT），釘在 v1.5.21（上游提交 6fc42df），macOS / Windows 兩套 bridge 資源
  • 目錄站：Next.js（App Router）→ OpenNext → Cloudflare Workers；主題原圖和清單單獨走 Cloudflare Pages 項目 codex-theme-assets，發到 https://theme-img.xuguopeng.com
  • 源碼分兩個倉庫：桌面端 xu-theme、目錄站 xu-theme-web，倉庫邊界寫死在 README 裡，目錄站不會混進桌面倉庫

還沒解決的問題 ​

不裝：

  1. 兩項視覺層從 v1.2.0 一路欠到 v1.5.21：xterm 終端文字配色、文件樹與文件查看器表面。v1.2.0 時期這兩處是手改在內核文件裡的，同步 v1.5.18 時被蓋掉；0.2.2 把其餘視覺層搬進補丁文件救了回來，唯獨這兩項一直沒進去。我在 0.2.4 的補丁文件裡查過，xterm 命中 0，內核 CSS 裡也是 0 —— 不是文檔沒更新，是真的還欠著。在意它們的話，0.1.0 是目前唯一好的那一版
  2. 0.2.2 在代理環境下完全不能用。Codex 自帶的 Node 24 在 NODE_USE_ENV_PROXY=1 + HTTP_PROXY 下把回環請求也塞進代理，注入器讀不到 /json/list，點「應用」沒有任何反應 —— 不是效果差，是整個功能不工作。0.2.4 繞過了，但 0.2.2 還掛在下載區，所以下面把它降成「舊版」並把這條寫在臉上看見的位置。一句實話：我自己這台機器當前環境裡沒有代理變量，這個 bug 我復現不出來，它是照上游代碼路徑推出來的
  3. Windows 沒過實機驗證。0.2.4 新加的 windows-theme-manager-optional.json 正是替 Windows 移除那條滿足不了的安裝必需項（上游無條件要求我們不分發的 DreamSkin.ThemeManager.exe）—— 補丁寫了，同樣沒在真機上跑過。受管引擎也不帶上游的 runtime/node，安裝時要求用戶 PATH 上有經簽名的 Node.js 22+
  4. 「從圖片創建」還沒接系統文件選擇器，目前是瀏覽器預覽模式
  5. 線上導入鏈路沒通。目錄站和資源站都要單獨部署，codextheme:// 那條鏈接在線上還喚不起東西
  6. 沒有開發者簽名和公證，首次打開要在「系統設置 → 隱私與安全性」裡點「仍要打開」；包只有 Apple Silicon
  7. 提交和發包之間沒有機制對齊。0.2.3 九月三十號提交完就擱著，快一個月後才隨 0.2.4 一起發出去；倉庫裡也沒有 CHANGELOG，版本說明只寫在 README 的段落裡，線上的下載區是第幾版這件事沒有任何地方會提醒我

下載 ​

  • 0.2.4 · 推薦版 —— CodexTheme-0.2.4-macos-arm64.dmg（24 MB） 內核 v1.5.21。修掉代理環境下主題完全應用不了的那個坑（回環請求被 Node 24 塞進代理），補上頭像裁切到 polaroid 相框的整條鏈路，並把 0.2.1 手工兜住的頂部漸變誤傷交還給上游修復、改由腳本斷言守衛。仍然缺 xterm 終端文字配色與文件樹／文件查看器表面那兩項。
  • 0.2.2 · 舊版 —— CodexTheme-0.2.2-macos-arm64.dmg（24 MB） 內核 v1.5.18。如果你機器上設了 HTTP_PROXY 之類的代理變量，這一版點「應用」是不會有任何反應的，請直接拿 0.2.4。留著只是為了對照。
  • 0.1.0 · 舊內核備用 —— CodexTheme-0.1.0-macos.dmg（14.5 MB） 內核還停在 v1.2.0。0.2.x 有兩項沒重新移植：xterm 終端文字配色、文件樹與文件查看器表面。日常在意這兩處的話，這版還是好的。

三包都是 macOS Apple Silicon（arm64），自己打的包、沒有開發者簽名：首次打開要在「系統設置 → 隱私與安全性」裡點「仍要打開」。Windows 版還在等實機驗證，驗證過再放上來。

SHA-256 校驗：

5dc163ea387d1f8e6408c48a1c58ffb7dd92766e1fc5918a87ec9d1db02922dc  CodexTheme-0.2.4-macos-arm64.dmg
a8d733d81b57b7d12cc73c6095367d42bed7fdfb93e0f6dd187a711588efe39b  CodexTheme-0.2.2-macos-arm64.dmg
b25922b166e8273da89cecf8f5d52ea63b8410701f9146525475d78f18e999c9  CodexTheme-0.1.0-macos.dmg

下一個目標：把那兩項視覺層補回補丁層，讓 0.1.0 可以真正退役；然後把目錄站的線上導入鏈路跑通 —— 現在它是一個只能本機打開的目錄。

上次更新於: