codex-dream-skin-workflow-engine

Codex Dream Skin Workflow Engine

English judge copy: README.en.md

本專案同時是兩件事：一套可運作的 macOS Codex 桌面端介面主題引擎，以及一次 Codex / GPT-5.6 能力邊界測試。兩者不是主從關係——正是因為題目要求的技術深度夠，這個測試才有意義。

工程內容不是一張 CSS 皮膚，而是一條 11 段管線加兩條回寫迴圈：視覺需求 → 結構化 theme spec → 素材管線（去背、壓縮、圖示 manifest）→ 模組清單與內容雜湊 → 原生 UI adapter 與幾何驗證 → 掛載契約（surface + collision + lifecycle）→ 靜態檢查（376 條 assertion、資產預算、module matrix）→ 本機 CDP 單次套用 → renderer 模組 → 視覺驗證 → 安裝或範圍化還原。失敗案例回寫 direct/root cause，模組修補走 regression gate。

測試內容是把上述整段——架構、實作、素材管線、驗證、封裝——全部交給模型，只由使用者提供 intent、constraints、缺陷回報與最終判斷，看能推到哪裡、在哪裡會斷。擁有者估算：使用者約 20–30%、模型約 70–80%，見下方佔比表。

受測的五個能力面在單純生成任務中不會出現：CDP 注入與還原、DOM 擁有權替換、靜態存取、記憶體釋放、動態退讓。

運作邊界：透過 127.0.0.1 的 Chromium DevTools Protocol 注入 CSS 與輕量 DOM 狀態，不修改官方 /Applications/ChatGPT.app、app.asar、簽名或使用者登入資料。

這不只是一個桌面換皮工具

技術主體是對兩件事的偵測、實踐與靜態存取：

1. 頁面資料層的 CDP 注入 — 透過 127.0.0.1 的 Chromium DevTools Protocol 完成一次性注入，不修改應用程式本體、不碰簽名、不動使用者登入資料，且保留完整還原路徑。
2. DOM 擁有權辨識 — 判斷每個效果該掛在哪個原生節點，並在不改變 hitbox、不覆蓋文字、不讓 transient panel 穿透的條件下完成替換，而不是往上疊一層遮罩。

兩者都有不連線的靜態存取路徑。macos/scripts/static-black-layer-index.mjs、static-interactive-black-layer-index.mjs、static-color-baseline-compare.mjs 只讀 theme.css、renderer-inject.js、surface-registry.js、runtime-modules.json 等原始碼，就能盤點圖層擁有者與色彩基準；不需要開 CDP、不需要啟動應用程式、不需要截圖。

五個受測的能力面

實作全程放手給 GPT-5.6，使用者只給 intent、constraints 與最終判斷。測的是這五件事能不能被推到可用的程度：

這五項的驗證不是靠宣稱：macos/tests/run-tests.sh 有 376 條 assertion 直接檢查上述識別碼與邊界值，module-boundary-gate.mjs 檢查模組邊界宣告，performance-probe.mjs 量測 runtime 負載。

負載上限是寫死並由 gate 強制的，不是自我約束：

超標由 macos/scripts/module-matrix.mjs 直接判錯。runtime-modules.json 的 policy 另外寫死 rendererMaintenanceMs: 2500、heavyMaintenanceMs: 10000，並禁止 idle backdrop blur 與 per-icon filter stack；素材載入限於「已啟用模組實際引用的部分」。

人機貢獻佔比

以下為專案擁有者依實際協作過程給出的第一手估算，非量測值。列出以保留歸屬透明度；可量測的部分（實作規模、驗證覆蓋、證據層密度）另見 docs/CODEX_CAPABILITY_BOUNDARY_TEST.md。

整體：使用者約 20% – 30%，Codex / GPT-5.6 約 70% – 80%。

更精準的說法：使用者主要貢獻 intent、taste、constraints、approval、defect reports、final judgment；Codex / GPT-5.6 主要貢獻 architecture、implementation、asset pipeline、cutout validation、click testing、layer scanning、performance optimization、restore path、submission packaging。

自我檢測、自我修復的工作流

docs/PINNED_REVISION_LOOP_STANDARD.md 定義的迴圈是可重入的：

ORIENT -> CDP_CHECK -> SCAN_QUEUE -> LAYER_CLASSIFY -> 決策
  決策：保護原生 / 替換擁有者 / 合併選擇器 / 重掃精確路由
  -> STATIC_GATE（語法、測試、workflow gate、diff check）
  -> 預算檢查（超標先壓縮，不先套用）
  -> APPLY_ONCE（一次性注入，不留常駐程序）
  -> VERIFY（live DOM 掃描、截圖、路由狀態、像素稽核）

驗證不通過時回到「替換擁有者」再跑一輪；CDP 中斷則記錄 blocker，不做任何 live 宣稱；截圖與路由對不上時強制重掃，不接受過期證據。macos/scripts/revision-loop-one-click.sh 是這個迴圈的單一入口。這個迴圈是文件化的決策流程，由人或 agent 依標準重跑，不是自動重試的常駐程式。

可轉用的技術範圍

這條路徑不限於換皮：

• 網頁資料層偵測 — 同一套 CDP 附著加 DOM 擁有權辨識，可用來盤點一個頁面實際渲染出什麼、由哪個節點擁有、哪些是動態掛載、哪些是原生受保護區。
• 數據層結構盤點（與爬蟲同類問題） — interface-field-inventory.mjs 盤點介面欄位與動態邊界覆蓋率，live-surface-audit.mjs 透過 CDP 稽核現行 renderer 表面，native-module-scan.mjs 可持續取樣原生模組。爬蟲的「先辨識結構、再決定取什麼值」是同一類問題。

界線要講清楚：本專案只在本機 loopback 對使用者自己的應用程式操作，target 另有 chatgpt|codex 白名單，不對任何外部站點發出請求，也不內建抓取或儲存第三方網站內容的功能。上述是技術路徑的可轉用性說明，不是本 repo 附帶的爬蟲工具。

Codex Dream Skin Workflow Engine

Codex Dream Skin 不是單一 CSS 皮膚，而是一套由 Codex 協助運作的主題工作流：把視覺需求轉為結構化 theme spec，處理並壓縮素材，依模組套用，驗證原生介面幾何與互動，最後可完整還原。cyber-mecha cat 是用來操練並證明這套流程的樣本主題，流程本身才是產品。

使用者不需要先寫好專門提示詞。可以從不完整的想法開始，和 Codex 一起探索變體、逐項修正、選擇場景，再把接受的結果組成可測試的互動工作區。架構圖不是事後文件，而是限制模組歸屬、原生掛載位置、碰撞、效能與還原行為的控制平面。

OpenAI Build Week 定位：

• 主賽道：Developer Tools
• 價值對齊：Work & Productivity
• 提交定位：一套可運作的主題工作流引擎，同時是一次能力邊界測試。技術深度與測試價值互為條件——題目不夠硬，測試就沒有意義；模型撐不住，工具就做不出來。
• 單一產品：安全主題工具鏈與工作舒適度改善是同一套 workflow 的技術面與使用者價值面，不拆成兩個專案。
• 證據：協作分工與人機佔比見下方表格；可量測的實作規模、驗證覆蓋與證據層密度見 docs/CODEX_CAPABILITY_BOUNDARY_TEST.md，數值釘在 commit e9bd85e 可複驗。

統一流程：

需求與圖片
  -> 主題規格
  -> 去背與 runtime 素材最佳化
  -> 獨立模組與內容雜湊
  -> 原生 UI adapter 與掛載契約
  -> 位置、碰撞與生命週期策略
  -> 靜態測試與資產預算
  -> CDP 單次套用
  -> 幾何、可讀性、碰撞與動畫驗證
  -> 接受安裝或範圍化還原
  -> 證據與競賽提交包

相關成果與獨立實作

實作前曾查看 Fei-Away/Codex-Dream-Skin 的公開成果，作為可行性與產品方向參考。本專案沒有複製、內嵌或依賴該 repository 的原始碼或視覺素材；本 repo 的本機 CDP bridge、原生介面辨識、幾何驗證、碰撞退讓、事件策略、動畫延遲載入、payload cache、驗證與還原流程均為獨立實作。

真正的工程問題不是換一張桌布，而是判斷每個效果應掛在哪個 Codex 原生節點，並確保不覆蓋文字、不改變 hitbox、不讓 transient panel 穿透，也不引入高頻常駐程序。

框架圖

原生掛載模型

技術棧

模組邊界

開發歷程框架

這張圖整理自本機開發日誌 docs/PROJECT_LOG.md 的開發摘要，不是事後憑印象重寫。該日誌記錄本機絕對路徑與截圖證據，因此只保留在本機、不隨 repo 發布。它描述這個專案從「單張主題圖」演進成可驗證、可還原、低負載工作流的實際路徑。

GPT-5.6 / Codex 使用證據

官方 Build Week 規則要求專案使用 Codex 與 GPT-5.6，demo 影片與 README 也要說明使用方式。FAQ 進一步要求這個使用必須是有意義的，不可以只是裝飾性標註；也可以搭配標準函式庫、框架或其他已授權工具，但 Codex 與 GPT-5.6 要是核心工作的一部分。

本專案的對應證據：

官方參考：

• OpenAI Build Week Official Rules
• OpenAI Build Week FAQ
• OpenAI Build Week project update

專案內 Codex 技能：$codex-dream-skin-workflow

bash .agents/skills/codex-dream-skin-workflow/scripts/workflow-gate.sh --runtime

最終送件前使用嚴格模式；只要影片、repository、README、feedback session ID 或 judge path 仍未完成，就會阻擋送件：

bash .agents/skills/codex-dream-skin-workflow/scripts/workflow-gate.sh --submission

目前本機偵測到的官方 app：

• App path: /Applications/ChatGPT.app
• Bundle id: com.openai.codex
• Bundled Node: /Applications/ChatGPT.app/Contents/Resources/cua_node/bin/node

安全邊界

• 不讀取或改寫 ~/.codex/auth.json
• 不修改 app.asar 或官方 .app
• 不自動改寫 API Key、Base URL 或模型供應商設定
• CDP 僅綁定 127.0.0.1
• 主題資料放在 ~/Library/Application Support/DreamSkinForge
• 安裝後引擎放在 ~/.codex/dream-skin-forge

快速使用

先在本 repo 跑檢查：

macos/tests/run-tests.sh

安裝到固定引擎位置：

macos/scripts/install.sh

安裝固定啟動器到 ~/Applications/Dream Skin Forge.app：

macos/scripts/install-launcher.sh

之後從 Finder / Spotlight 開啟 Dream Skin Forge。啟動器會在 Codex 尚未開啟時，用主題引擎啟動 Codex 並套用 active theme；如果 Codex 已經開著但沒有 debug port，它只會提示，不會強制關閉目前視窗。

手動啟動 Codex 並套用主題。此工具直接執行官方 bundle executable 以保留 CDP 啟動參數，不修改官方 app：

~/.codex/dream-skin-forge/scripts/start.sh

如果 Codex 已經開著，先正常關閉 Codex，或明確要求重啟：

~/.codex/dream-skin-forge/scripts/start.sh --restart

如果官方 app 沒有在 20 秒內回應 graceful quit，才使用：

~/.codex/dream-skin-forge/scripts/start.sh --restart --force-quit

切換模式或套用自己的背景圖：

~/.codex/dream-skin-forge/scripts/customize.sh --mode sidebar-art
~/.codex/dream-skin-forge/scripts/customize.sh --image "/absolute/path/to/background.png" --name "My Theme" --safe-area sides --task-mode ambient
~/.codex/dream-skin-forge/scripts/start.sh --restart

驗證目前 renderer 是否有主題標記：

~/.codex/dream-skin-forge/scripts/verify.sh

不重啟移除目前 renderer 裡的主題層：

~/.codex/dream-skin-forge/scripts/restore.sh --port 9341

若要同時關閉帶 CDP 的 Codex session，使用：

~/.codex/dream-skin-forge/scripts/restore.sh --quit

三個公開熱抽換版本

公開 runtime 固定依 theme-packs/public-pack-set.json 的順序提供三個版本；缺少任一 manifest 或其中任何 runtime 素材時，loader、module matrix 與公開打包都會直接失敗，不會退化成兩個版本繼續執行。

先列出版本，再用唯讀 plan 檢查將要寫入的 active theme。activate 只會更新本機 Dream Skin Forge 的 active theme 並建立備份，不會啟動、重啟或注入 Codex：

node theme-packs/scripts/activate-pack.mjs list --format text
node theme-packs/scripts/activate-pack.mjs plan --pack knife-shield-dog --format json
node theme-packs/scripts/activate-pack.mjs activate --pack knife-shield-dog --format json

下一次 one-shot apply 後，左側 compact cycle control 會依上表順序熱抽換三包；idle 狀態不預載動畫 DOM。

評審快速測試

支援平台：macOS。評審不需要重建官方 Codex 或修改官方 app：

bash .agents/skills/codex-dream-skin-workflow/scripts/workflow-gate.sh --runtime
bash macos/scripts/install.sh
bash macos/scripts/start.sh --no-launch --once --port 9341 --wait-ms 8000
bash macos/scripts/verify.sh --port 9341
bash macos/scripts/restore.sh --port 9341

若 Codex 尚未以本機 CDP port 啟動，才使用已安裝的 Dream Skin Forge.app 啟動器。不要為套主題直接修改官方 bundle，也不要在已有可用 renderer 時重啟。

設計原則

第一版只做 macOS。原因是目前工作機上確認存在 com.openai.codex 的 /Applications/ChatGPT.app，而 Windows 的 Store app 啟動、AppUserModelId、路徑 ACL 與 tray 生命週期需要分開設計。

主題分三層：

• assets/theme.css：介面外觀與透明/霧化層
• assets/renderer-inject.js：renderer 內的 idempotent 注入與還原
• scripts/injector.mjs：CDP 連線、注入、驗證、截圖與 daemon

目前主題模式分三種：

• chrome-only：只裝飾 sidebar、header、hover、focus、popover 等 Codex 外框區域。
• sidebar-art：在 chrome-only 基礎上，允許 sidebar 內的去背 icon/badge 與左上角機甲裝甲感角標。
• wallpaper：保留給未來安全區完整驗證後使用；目前不作為預設。

預設 source theme 使用 sidebar-art 與 safe-area=sides。背景圖只會以低透明方式出現在左側 / 右側安全區、sidebar 霧化底層與右側 project/resource panel 底層；main 工作區、conversation、composer 主體仍維持原生可讀，不放全頁壁紙。大型角色是獨立 body 層，放在 sidebar 右側展示區，不壓在功能欄文字後面。

模組化配色欄位放在 assets/theme.json：

• modules.sidebar：青色系，負責左側導覽與列表辨識。
• modules.header：金橘系，負責上方標題列與機甲裝甲感。
• modules.composer：低透明黑鈦玻璃底搭配金橘、洋紅、青色薄光漸層，負責輸入區與 focus。
• modules.popover：洋紅系，負責選單、彈窗與跳色層。
• modules.mecha：黑鈦/槍灰骨架與金橘裝甲語言。
• modules.status：success、warning、danger、info 狀態色。

背景圖套件資產：

• assets/backgrounds/cyber-ruins-pale.png：淡色賽博廢墟背景，保留中央低對比工作區。
• 舊版 code-rain 橘貓實驗背景：只保留在本地歷史；不列入公開 package。
• 左側安全區使用淡色廢墟、破損面板與微弱資料雨。
• 右側安全區使用廢墟走廊與淡洋紅光，不放角色進背景圖。
• 大型角色使用 assets/icons/cyber-mecha-cat-male-helmet-900.png，不透明放在 sidebar 右側展示區。
• 中央工作區不直接鋪圖，避免再次蓋住內容。

去背貓 icon 已包在 assets/icons/，並由 assets/icons/icon-manifest.json 管理。胖橘貓只能作為 sidebar badge，小型 UI 按鈕只用抽象符號；大型駭客貓角色只能作為 sidebar 右側展示區前景，不可再當作全頁背景，也不可整批貼到每個按鈕。

按鈕圖示採用抽象貓系符號，而不是重複使用橘貓本體：

• cat-eye-search.svg：搜尋，貓眼鏡片。
• cat-paw-new-task.svg：新增任務，爪掌加號。
• cat-tail-back.svg / cat-tail-forward.svg：返回/前進，尾巴動線。
• claw-stop.svg：停止，爪痕止動。
• mecha-ear-settings.svg：設定，機甲貓耳齒輪。
• neko-chip-project.svg：專案，貓耳晶片。
• whisker-send.svg：送出，鬍鬚飛行線。
• collar-tag-task.svg：任務標籤，項圈吊牌。
• fishbone-files.svg：檔案/資料，魚骨。
• yarn-thread.svg：對話/線程，毛線球。
• litter-scoop-clean.svg：清理/整理，貓砂鏟。
• food-bowl-run.svg：執行/餵食，食碗。
• cat-can-package.svg：套件/封裝，罐頭。
• teaser-wand-spark.svg：提示/亮點，逗貓棒。

這組按鈕資產目前只打包在 assets/icons/buttons/，theme.json 內 icons.buttons.enabled 預設為 false，不會自動替換 live Codex 按鈕。

按鈕總覽在 button-glyphs-preview.svg。

目前可本地檢查的模組 preview：

• 側邊導覽：sidebar-navigation-test.html
• 右側資料列：project-panel-rows-test.html
• 映射表：button-action-map.json

第一個測試替換模組是 sidebar navigation。它已具備 sidebar-only runtime 接線，但預設關閉；沒有明確啟用與注入時不會碰 live Codex：

若要準備 sidebar navigation 的 runtime 測試設定，只開第一個模組：

~/.codex/dream-skin-forge/scripts/customize.sh \
  --icon-buttons-enabled true \
  --icon-buttons-apply-mode module \
  --icon-buttons-sidebar-navigation-enabled true

關回預設：

~/.codex/dream-skin-forge/scripts/customize.sh \
  --icon-buttons-enabled false \
  --icon-buttons-apply-mode opt-in \
  --icon-buttons-sidebar-navigation-enabled false

verify.sh 會回報 buttonIcons 與 buttonSidebarNavigation，用來確認 sidebar 模組替換狀態。

第二個測試替換模組是 titlebar navigation，只處理左上可見的返回/前進按鈕。它使用貓尾方向符號和黑金機甲小控制件樣式，預設關閉：

~/.codex/dream-skin-forge/scripts/customize.sh \
  --icon-buttons-enabled true \
  --icon-buttons-apply-mode module \
  --icon-buttons-sidebar-navigation-enabled true \
  --icon-buttons-titlebar-navigation-enabled true

verify.sh 會另外回報 buttonTitlebarNavigation，期望值是 2。

右側資源 / project panel 先做 chrome，不做 icon 替換。它會在 runtime 只標記可見的右側 summary/resource panel，套透明鍵盤外殼、RGB 薄邊線和資料晶片列；verify.sh 會回報 projectPanels。

composer controls 是輸入區的 icon replacement 模組，只替換輸入區內可見的 run、stop、send 控制，不碰打字框底色、模型選單、聽寫或附件選單。送出/停止按鈕會因狀態改變 label；runtime 只在 composer 範圍內使用右側小按鈕 fallback，不會掃到工作區或右側 panel：

~/.codex/dream-skin-forge/scripts/customize.sh \
  --icon-buttons-enabled true \
  --icon-buttons-apply-mode module \
  --icon-buttons-sidebar-navigation-enabled true \
  --icon-buttons-titlebar-navigation-enabled true \
  --icon-buttons-composer-controls-enabled true

verify.sh 會另外回報 buttonComposerControls。

top utility actions 是上方工具列 / 面板切換 / 文件工具模組，只替換可見的小型工具按鈕，不碰 sidebar、composer、訊息操作列或 breadcrumb 文字連結。message actions 是訊息區可見操作列模組，只替換 copy、feedback、continue、guide、delete、more、scroll-bottom 等小按鈕，不碰 minimap jump rows。

projectPanelRows 是右側 project/resource panel 內的資料列模組。它必須先看到已標記且完整在 viewport 內的 .codex-interface-theme-project-panel，才會替換 row icon；隱藏或偏出畫面外的 panel 會正確回報 buttonProjectPanelRows = 0，避免把樣式套到工作區或 offscreen layer。

右側資料列的本地設計預覽在 project-panel-rows-test.html。此 preview 只用抽象貓系與寵物用品 glyph，不把橘貓本體貼到 row 上。

可調整的範例：

~/.codex/dream-skin-forge/scripts/customize.sh \
  --mode sidebar-art \
  --sidebar-accent '#00d5ff' \
  --header-accent '#ffb000' \
  --composer-accent '#ffb000' \
  --composer-surface 'rgba(9, 10, 12, 0.68)' \
  --composer-border 'rgba(255, 176, 0, 0.14)' \
  --popover-accent '#ff4fd8' \
  --mecha-armor '#f2a23a' \
  --image "$PWD/macos/assets/backgrounds/cyber-ruins-pale.png" \
  --safe-area sides \
  --task-mode ambient \
  --icon-badge-enabled true \
  --icon-badge-size 58 \
  --character-enabled true \
  --character-path 'icons/cyber-mecha-cat-male-helmet-900.png' \
  --character-placement sidebar-hero \
  --character-size 350 \
  --character-opacity 1

專案紀錄

所有 .md 檔案與階段決策集中登記在本機開發日誌 docs/PROJECT_LOG.md（本機限定，不隨 repo 發布）。