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、簽名或使用者登入資料。
這不只是一個桌面換皮工具
技術主體是對兩件事的偵測、實踐與靜態存取：
- 頁面資料層的 CDP 注入 — 透過
127.0.0.1 的 Chromium DevTools Protocol 完成一次性注入，不修改應用程式本體、不碰簽名、不動使用者登入資料，且保留完整還原路徑。
- 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 與最終判斷。測的是這五件事能不能被推到可用的程度：
| 能力面 |
具體要求 |
對應實作 |
| CDP |
從 127.0.0.1 附著並一次性注入，不改應用程式本體、不碰簽名、不動登入狀態，且必須留完整還原路徑 |
macos/scripts/injector.mjs、restore.sh、verify.sh |
| DOM 擁有權 |
判斷效果該掛哪個原生節點，替換該節點的擁有者，而不是往上疊遮罩；不改 hitbox、不覆蓋文字、不讓 transient panel 穿透 |
macos/assets/surface-registry.js、renderer-inject.js 的 owner marking |
| 靜態存取 |
不連 CDP、不啟動程式、不截圖，只讀原始碼就盤點圖層擁有者與色彩基準；另有 runtime 端的 DOM 快取避免重複查詢 |
static-black-layer-index.mjs、static-interactive-black-layer-index.mjs、static-color-baseline-compare.mjs；模組 staticAccess（kind: dom-cache） |
| 記憶體釋放 |
動畫一次性播放：點擊才查快取載入，播完清 timer、移除 class 與 deadline 屬性、node.remove() 播放節點，不留常駐動畫、不做 idle 迴圈；素材以 content hash 分組，過期組自動剪除 |
releaseTableFlipPlaybackNode()、loadGroup() 延遲載入、assetGroupsPruned；模組 tableFlipCat（loadPolicy: static-cache-click） |
| 動態退讓 |
角色與裝飾層必須依即時幾何避開 composer、面板與文字，碰撞判斷要有界限、不能無上限輪詢 |
characterRetreat（kind: dom-geometry）、collisionScheduler（kind: scheduler），兩者 loadPolicy: no-extra-asset |
這五項的驗證不是靠宣稱：macos/tests/run-tests.sh 有 376 條 assertion 直接檢查上述識別碼與邊界值，module-boundary-gate.mjs 檢查模組邊界宣告，performance-probe.mjs 量測 runtime 負載。
負載上限是寫死並由 gate 強制的，不是自我約束：
| 項目 |
目前 |
上限 |
用量 |
theme.css |
83,170 B |
130,000 B |
64.0% |
renderer-inject.js |
116,581 B |
120,000 B |
97.2% |
超標由 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。
| 階段 |
使用者 input |
Codex / GPT-5.6 output |
佔比估算 |
| 起點定義 |
提出想做 Codex desktop skin / Dream Skin |
判斷應升級成可回復 runtime engine |
使用者 70% / Codex 30% |
| 視覺方向 |
橘貓、駭客、Matrix、cyberpunk、機甲、撞色 |
拆成 theme language、safe area、色彩角色、模組順序 |
使用者 45% / Codex 55% |
| 素材生成 |
提供少量截圖、參考、審美方向 |
生成背景、角色、badge、table-flip 素材變體 |
使用者 25% / Codex 75% |
| 去背與素材處理 |
要求乾淨、可用、不遮擋 |
建立 chroma / cutout / runtime 尺寸，檢查 alpha |
使用者 10% / Codex 90% |
| Runtime 架構 |
要求不要破壞 Codex |
設計 CDP one-shot injection、restore、verify、engine/state 分層 |
使用者 15% / Codex 85% |
| 截圖與圖層除錯 |
回報黑框、遮擋、不乾淨 |
掃 DOM、圖層、owner boundary、direct/root cause |
使用者 20% / Codex 80% |
| 點擊與互動驗證 |
要求可點、不要擋、要確認 |
sidebar / composer / right panel / workspace picker / table-flip lifecycle 測試 |
使用者 10% / Codex 90% |
| 動畫生命週期 |
想要互動效果 |
改成 click-time load、播完釋放、避免常駐 |
使用者 15% / Codex 85% |
| 效能治理 |
要求不要卡、不影響使用 |
WebP、content-hash cache、移除 blur / idle animation / daemon |
使用者 10% / Codex 90% |
| Build Week 提交 |
決定參賽、提供最終判斷 |
README、Devpost 文案、asset inventory、demo timeline、judge path |
使用者 25% / Codex 75% |
整體：使用者約 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 穿透，也不引入高頻常駐程序。
框架圖
flowchart LR
A["視覺需求 / 圖片"] --> B["主題規格 theme.json"]
B --> C["素材管線<br/>去背、壓縮、圖示 manifest"]
C --> D["模組清單 runtime-modules.json"]
D --> E["原生 UI adapter<br/>錨點 + 幾何驗證"]
E --> F["掛載契約<br/>surface + collision + lifecycle"]
F --> G["靜態檢查<br/>測試、預算、module matrix"]
G --> H["本機 CDP 單次套用<br/>injector.mjs"]
H --> I["Renderer 模組<br/>CSS + DOM markers"]
I --> J{"視覺驗證"}
J -->|通過| K["安裝 / 送件包"]
J -->|失敗| L["範圍化還原 / 單模組修補"]
L --> B
K --> M["restore.sh 還原"]
原生掛載模型
| 平面 |
掛載規則 |
範例 |
| 場景底層 |
只畫在 document body，不建立覆蓋工作內容的全頁遮罩 |
背景圖與低成本色彩層 |
| 原生 surface |
標記並就地處理真正的 Codex 節點，不重建其尺寸 |
Sidebar、composer、對話泡泡、project panel |
| 獨立裝飾 |
掛在 body 的 pointer-safe 元件，必須有 safe area 與退讓規則 |
機甲角色與小型 badge |
| 動態 portal |
互動後辨識可見外殼，只標記該外殼，關閉後清理 |
Dialog、menu、listbox、workspace picker |
| 手動互動 |
Idle 只保留 trigger，點擊後才建立播放狀態，完成後釋放 |
翻桌貓動畫 |
技術棧
| 層級 |
技術 / 檔案 |
職責 |
| 桌面端 |
macOS Codex desktop / /Applications/ChatGPT.app |
被套用主題的官方應用程式；本專案不修改它 |
| Runtime bridge |
Chromium DevTools Protocol on 127.0.0.1 |
只連本機 renderer，做一次性注入、驗證與還原 |
| CLI / scripts |
Bash + Node.js ESM |
安裝、啟動、CDP 連線、payload 傳輸、驗證 |
| Theme schema |
macos/assets/theme.json |
主題色、模式、資產、角色、按鈕與模組開關 |
| Module policy |
macos/assets/runtime-modules.json |
模組啟用條件、payload 群組、效能預算、載入策略 |
| Visual layer |
macos/assets/theme.css |
sidebar、composer、右側面板、泡泡對話、玻璃與邊框樣式 |
| Renderer logic |
macos/assets/renderer-inject.js |
idempotent DOM 標記、角色退讓、手動動畫、低頻維持、cleanup |
| Asset formats |
PNG / WebP / SVG / sprite / GIF fallback |
背景、機甲貓、貓系語意圖示、手動動畫 |
| Verification |
macos/tests/run-tests.sh, verify.sh, workflow gate |
語法、預算、互動、截圖、還原與 regression gate |
| Submission |
submission/, competition-manifest.json |
Devpost 文案、素材庫、demo 影片、公開打包邊界 |
模組邊界
| 模組 |
主要責任 |
載入策略 |
background |
工作安全區背景與左右視覺分區 |
active theme only |
iconBadge |
sidebar badge / 小型橘貓標記 |
enabled only |
buttonGlyphs |
抽象貓系按鈕圖示 |
opt-in module |
character |
大型機甲貓前景角色 |
enabled only |
characterRetreat |
右側面板與文字碰撞退讓 |
無額外素材 |
composerSurface |
輸入框玻璃層與邊界 |
DOM class |
conversationSurface |
泡泡對話視窗與可讀性保護 |
DOM class |
workspacePickers |
工作欄位 picker 黑底 / 防穿透 |
事件觸發，短暫維持 |
projectPanels |
右側環境 / 來源 panel 玻璃與 row 樣式 |
DOM class |
tableFlipCat |
右下生氣 icon 與翻桌動畫 |
點擊後載入，播完釋放 |
開發歷程框架
這張圖整理自本機開發日誌 docs/PROJECT_LOG.md 的開發摘要，不是事後憑印象重寫。該日誌記錄本機絕對路徑與截圖證據，因此只保留在本機、不隨 repo 發布。它描述這個專案從「單張主題圖」演進成可驗證、可還原、低負載工作流的實際路徑。
flowchart TD
A["2026-07-17<br/>空 repo / 官方 app 邊界<br/>不改 ChatGPT.app、不改 app.asar"] --> B["視覺需求<br/>橘貓、綠色 code-rain 駭客風格、機甲賽博、撞色工作區"]
B --> C["GPT-5.6 + Codex 設計拆解<br/>主題語言、safe area、模組順序、除錯假設"]
C --> D["Image2 素材生成與選型<br/>背景、橘貓 badge、機甲貓角色、翻桌動作素材"]
D --> E["結構化規格<br/>theme.json、icon manifest、runtime-modules.json"]
E --> F["本機 CDP 單次套用<br/>127.0.0.1 renderer、content hash、restore path"]
F --> G["截圖 / 錄影矩陣除錯<br/>背景缺失、遮罩、黑框、跑版、閃爍、碰撞"]
G --> H["小模組修補<br/>backdrop element、composer glass、right panel、workspace picker shell"]
H --> I["互動與退讓<br/>機甲貓碰撞退讓、右下生氣 icon、點擊後翻桌動畫"]
I --> J["低負載重構<br/>WebP、asset-group cache、零 idle 動畫、無常駐 daemon"]
J --> K["送件包<br/>README、Devpost 文案、asset library、demo 影片、workflow gate"]
G -. "失敗案例回寫 direct/root cause" .-> E
H -. "regression gate" .-> F
GPT-5.6 / Codex 使用證據
官方 Build Week 規則要求專案使用 Codex 與 GPT-5.6，demo 影片與 README 也要說明使用方式。FAQ 進一步要求這個使用必須是有意義的，不可以只是裝飾性標註；也可以搭配標準函式庫、框架或其他已授權工具，但 Codex 與 GPT-5.6 要是核心工作的一部分。
本專案的對應證據：
| 階段 |
GPT-5.6 / Codex 參與點 |
專案證據 |
| 視覺拆解 |
把橘貓、綠色 code-rain 駭客風格、機甲與賽博龐克參考拆成主題語言、safe area、撞色分區與模組順序 |
2026-07-17 22:36 Theme Background Asset, 2026-07-18 00:15 Closeout Governance |
| 生圖與選型 |
使用 GPT-5.6 輔助 prompt/變體判斷，透過 Image2 生成原創機甲貓、橘貓 badge 與動畫方向，保留來源與 runtime 版本 |
2026-07-19 10:45 Stage 1 Provenance Correction, 2026-07-19 10:50 Generated Character Family Correction, submission/asset-inventory.json |
| 截圖除錯 |
根據使用者截圖與錄影定位背景沒蓋上、黑框、透明度、文字穿透與 composer 閃爍來源 |
2026-07-17 23:27, 2026-07-19 Composer Black Frame Historical Trace, 2026-07-19 Composer Native Floor Fade Removal |
| 動畫調整 |
把翻桌貓從預載 / 常駐改成右下生氣 icon 點擊後才載入、CSS steps 播放、播完清理 |
2026-07-19 Modular Runtime Compression And Lazy Animation Closeout |
| 退讓機制 |
用碰撞判斷讓大型機甲貓在文字或右側 panel 侵入時退讓，而不是遮住工作內容 |
2026-07-19 Mecha Character Retreat Recovery Stabilization |
| 效能優化 |
壓縮背景、換 runtime WebP、分 asset group hash、移除 live blur / fixed wallpaper / idle animation / daemon |
2026-07-19 Runtime Badge Asset Right-Sizing, 2026-07-19 Low-GPU Glass Composition And Live Probe, 2026-07-19 Subtractive Effects, Opaque Transients, And One-Shot Launcher |
| 工作流封裝 |
把生圖、套版、除錯、驗證、還原、送件打包成同一個技能與 gate，而不是散落的一次性腳本 |
2026-07-19 09:39 Build Week Unified Workflow Framework, .agents/skills/codex-dream-skin-workflow/ |
官方參考：
專案內 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 與公開打包都會直接失敗，不會退化成兩個版本繼續執行。
| 順序 |
Pack ID |
場景 |
手動互動 |
| 1 |
knife-shield-dog |
Knife Shield Dog: Castle City Guard |
forward-slash |
| 2 |
orbital-stargazer-black-cat |
Black Cat: Orbital Stargazer |
roll-and-groom |
| 3 |
orange-mecha-cat |
Orange Mecha Cat: Cyber Ruins |
table-flip |
先列出版本，再用唯讀 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。它已具備 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 發布）。
评论