Improve repository discoverability

README.md

@@ -1,171 +1,212 @@
-# Codex Dream Skin
+<h1 align="center">Codex Dream Skin</h1>
 
 <p align="center">
-  <strong>中文</strong> · <a href="./README.en.md">English</a>
+  <strong>给 Codex 桌面端换上主题、静态壁纸和动态壁纸。</strong><br>
+  保留原生侧栏、任务、项目选择器与输入框，不修改官方安装包。
 </p>
 
-> 本仓库是 [Fei-Away/Codex-Dream-Skin](https://github.com/Fei-Away/Codex-Dream-Skin) 的增强派生版本，保留完整上游历史；当前重点维护新版 Windows Codex 的 DOM、边栏与系统托盘兼容性。
-
 <p align="center">
-  <strong>给 Codex 桌面端换一张会呼吸的脸。</strong><br>
-  外部主题 / 换肤工具 · 本机 CDP 注入 · 不改官方安装包
+  <strong>中文</strong> · <a href="./README.en.md">English</a>
 </p>
 
 <p align="center">
-  一张图，一种心情 · 写代码，也要有氛围感
+  <a href="https://github.com/CCDawn/Codex-Dream-Skin-Enhanced/releases/latest"><img alt="最新版本" src="https://img.shields.io/github/v/release/CCDawn/Codex-Dream-Skin-Enhanced?style=flat-square&color=f47f9c"></a>
+  <a href="https://github.com/CCDawn/Codex-Dream-Skin-Enhanced/releases"><img alt="累计下载" src="https://img.shields.io/github/downloads/CCDawn/Codex-Dream-Skin-Enhanced/total?style=flat-square&color=ad6fe8"></a>
+  <a href="https://github.com/CCDawn/Codex-Dream-Skin-Enhanced/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/CCDawn/Codex-Dream-Skin-Enhanced/ci.yml?branch=main&style=flat-square&label=CI"></a>
+  <a href="./LICENSE"><img alt="MIT License" src="https://img.shields.io/github/license/CCDawn/Codex-Dream-Skin-Enhanced?style=flat-square"></a>
 </p>
 
 <p align="center">
-  非 OpenAI 官方产品。不修改 <code>.app</code> / <code>app.asar</code> / WindowsApps。
+  <img src="docs/images/social-preview.png" alt="Codex Dream Skin：Codex 桌面主题与动态壁纸" width="100%">
 </p>
 
-## 赞助商
-
 <p align="center">
-  <a href="https://passion8.cc/register?aff=TuPe">
-    <img src="docs/images/sponsor-passion8.png" alt="Passion8" height="72">
-  </a>
+  <a href="https://github.com/CCDawn/Codex-Dream-Skin-Enhanced/releases/latest/download/CodexDreamSkinManager.exe"><strong>下载 Windows EXE</strong></a>
+  ·
+  <a href="#macos-安装">macOS 安装</a>
+  ·
+  <a href="./docs/showcase.md">查看效果展厅</a>
+  ·
+  <a href="https://github.com/CCDawn/Codex-Dream-Skin-Enhanced/issues">反馈问题</a>
 </p>
 
-<p align="center">
-  <strong>更智能的连接 · 更热爱的创造</strong><br>
-  <sub>热爱驱动 · 无限可能 · Connect AI · Power Creation</sub>
-</p>
+> 非 OpenAI 官方产品。Codex Dream Skin 通过仅绑定 `127.0.0.1` 的本机 CDP 注入主题，不修改 WindowsApps、`.app`、`app.asar` 或官方代码签名。
 
-<p align="center">
-  感谢 <a href="https://passion8.cc/register?aff=TuPe"><strong>passion8.cc</strong></a> 赞助本项目。<br>
-  满血 AI 中转：官方模型直连，无降智、无套壳；一行配置接入 Codex / Claude Code / Grok。
-</p>
+## 为什么用它
 
-<p align="center">
-  <sub>
-    换肤与 API 配置互相独立，本项目不会自动改写你的模型供应商设置。
-  </sub>
-</p>
+- **原生 UI 保持可用**：不是把一张假界面贴满窗口；侧栏、聊天、任务和输入框仍可正常交互。
+- **Codex 内部动态壁纸**：Windows 支持本地 MP4/WebM 静音循环，不是修改桌面壁纸。
+- **一键式 Windows 管理器**：浏览、搜索、预览和切换壁纸，调整透出度，暂停或恢复官方外观。
+- **图片变主题**：导入喜欢的 PNG、JPEG 或 WebP，自动适配全窗背景与内容可读性。
+- **可恢复、可审计**：不改官方二进制；随时停止注入并恢复 Codex 官方外观。
+- **Windows + macOS**：Windows 提供自包含 EXE，macOS 提供菜单栏 Studio 与安装脚本。
 
-## 实测精选预设：桥本有菜
+## Windows：30 秒开始
 
-下面这套「桥本有菜 / Arina Hashimoto」已经在真实 Codex 首页分别验证浅色和暗色外观。用户提供的源 PNG 为 `1672 × 941`，主题包在保持源图近 16:9 构图的前提下派生导出 `2560 × 1440` JPEG，并不代表增加了源图细节。截图中的侧栏、卡片、项目选择和输入框都是 Codex 原生控件。
+1. 下载 [`CodexDreamSkinManager.exe`](https://github.com/CCDawn/Codex-Dream-Skin-Enhanced/releases/latest/download/CodexDreamSkinManager.exe)。
+2. 双击运行，在壁纸库选择 PNG、JPEG、WebP、MP4 或 WebM。
+3. 点击「应用到 Codex」。需要时点击「启动 / 重新应用」。
 
-<p align="center">
-  <img src="docs/images/presets/romantic-rose-light.jpg" alt="桥本有菜主题浅色实机效果" width="900"><br>
-  <sub>浅色 · 真实注入截图（未发送输入已在截图时遮蔽，仅预览）</sub>
-</p>
+管理器是自包含的单文件程序，内置经过测试的 Dream Skin 引擎与 Node.js 运行时；最终用户不需要安装 .NET SDK、Node.js 或手动执行 PowerShell。
 
-<p align="center">
-  <img src="docs/images/presets/romantic-rose-dark.jpg" alt="桥本有菜主题暗色实机效果" width="900"><br>
-  <sub>暗色 · 真实注入截图（未发送输入已在截图时遮蔽，仅预览）</sub>
-</p>
+> 当前发布版尚未进行代码签名，Windows 可能显示“未知发布者”。请只从本仓库的 [Releases](https://github.com/CCDawn/Codex-Dream-Skin-Enhanced/releases) 下载，并使用同页 `.sha256` 文件核对。
+
+### 壁纸透出
+
+右侧滑杆控制主题蒙层与壁纸的关系：
+
+- `100%`：显示原始壁纸/视频画面，整页主题蒙层降为零。
+- 较低数值：提高文字区与主题蒙层可见度，适合任务页或高对比背景。
+
+## macOS 安装
+
+在仓库的 [`macos/`](./macos/) 目录双击：
+
+```text
+Install Codex Dream Skin.command
+```
 
-从仓库安装并一键切换（macOS）：
+也可在终端执行：
 
 ```bash
 cd macos
-./scripts/install-dream-skin-macos.sh --no-launch
-~/.codex/codex-dream-skin-studio/scripts/switch-theme-macos.sh \
-  --id preset-romantic-rose
+./scripts/install-dream-skin-macos.sh
 ```
 
-Windows 使用本地主题仓库与系统托盘，并会预置同一套「桥本有菜」。首次从仓库使用：
+安装后通过菜单栏 Studio 导入、保存和切换图片主题。完整说明见 [`macos/README.md`](./macos/README.md)。
+
+## 功能对照
+
+| 功能 | Windows | macOS |
+|---|:---:|:---:|
+| PNG / JPEG / WebP 图片主题 | ✅ | ✅ |
+| MP4 / WebM 动态壁纸 | ✅ | — |
+| 图形化主题管理 | ✅ 独立 EXE | ✅ 菜单栏 Studio |
+| 壁纸库搜索与预览 | ✅ | ✅ |
+| 保存与切换主题 | ✅ | ✅ |
+| 壁纸透出度 | ✅ | — |
+| 暂停注入 / 恢复官方外观 | ✅ | ✅ |
+| 修改官方应用文件 | **不会** | **不会** |
+
+## 真实效果
+
+| Windows / 通用主题 | macOS 暗色主题 |
+|---|---|
+| ![Codex Dream Skin 红白科幻主题](docs/images/screenshot-demo-art.png) | ![Codex Dream Skin macOS 暗色主题](docs/images/screenshot-macos-home.png) |
+
+更多实机截图、人物预设与八种概念方向见 [`docs/showcase.md`](./docs/showcase.md)。
+
+## 工作原理
+
+```text
+本地壁纸 / 主题配置
+          ↓
+Codex Dream Skin 本地主题仓库
+          ↓
+127.0.0.1 回环 CDP
+          ↓
+Codex renderer 中的独立背景层
+          ↓
+原生侧栏、任务与输入框继续交互
+```
+
+Windows 视频会分块传入 renderer 并组装为 Blob URL；切换、暂停或清理时会释放播放器与 Blob。页面隐藏后自动暂停视频，避免无意义播放。
+
+## 安全边界
+
+- CDP 只绑定 `127.0.0.1`，不会对局域网开放调试端口。
+- 不修改 WindowsApps、`.app`、`app.asar` 或官方签名。
+- 不读取或改写 API Key、Base URL、模型供应商或 Codex 聊天内容。
+- 主题运行期间不要运行来路不明的本机程序；本机恶意进程可能尝试访问调试端口。
+- Codex 官方更新可能改变 DOM。若主题失效，请先使用管理器「启动 / 重新应用」，再查看 [Issues](https://github.com/CCDawn/Codex-Dream-Skin-Enhanced/issues)。
+
+## 从源码运行与构建
+
+### Windows 脚本入口
 
 ```powershell
-powershell -ExecutionPolicy Bypass -File .\windows\scripts\install-dream-skin.ps1
-powershell -ExecutionPolicy Bypass -File .\windows\scripts\start-dream-skin.ps1
+powershell.exe -ExecutionPolicy Bypass -File .\windows\scripts\install-dream-skin.ps1
+powershell.exe -ExecutionPolicy Bypass -File .\windows\scripts\start-dream-skin.ps1
 ```
 
-启动后可直接从「已保存主题 → 桥本有菜」切换；不需要跨目录手动导入。增强版托盘里的「更换背景图或视频」支持 PNG/JPEG/WebP 与静音循环的 MP4/WebM，保存后可继续一键切换。
+### 构建单文件 EXE
 
-> 可下载的用户源图是 [`docs/images/presets/romantic-rose-source.png`](./docs/images/presets/romantic-rose-source.png)（`1672 × 941`）；macOS 一键预设使用 [`macos/presets/preset-romantic-rose/background.jpg`](./macos/presets/preset-romantic-rose/background.jpg)（规范化派生 `2560 × 1440`）。上面两个效果图包含真实 UI，**只作预览，绝不能当背景导入**。背景为用户提供的 AI 生成示例，不代表 OpenAI/Codex 官方视觉或背书；公开再分发前请确认人物与素材权利。
+需要 .NET 8 SDK 和 Node.js 22+：
 
-## 概念效果图（不可直接导入）
+```powershell
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\windows\app\build-manager.ps1
+```
 
-下面八张图用于表达可实现的视觉方向，但它们是带界面的概念效果图，不是可直接使用的主题背景。需要同类效果时，先按[参考生图提示词](./docs/reference-background-prompt-guide.md)生成无 UI 的 `2560 × 1440` 素材；八种风格的详细拆解见[概念图提示词](./docs/background-generation-prompts.md)。
+输出位于 `windows/dist/`。构建会运行 Windows 回归测试、发布自包含 `win-x64` EXE，并执行发布后自检。
 
-<p align="center">
-  <img src="docs/images/gallery/skin-01.jpg" alt="粉系定制" width="900"><br>
-  <sub>粉系定制</sub>
-</p>
+### 测试
 
-<p align="center">
-  <img src="docs/images/gallery/skin-02.jpg" alt="财神打工" width="900"><br>
-  <sub>财神打工版</sub>
-</p>
+```powershell
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\windows\tests\run-tests.ps1
+```
 
-<p align="center">
-  <img src="docs/images/gallery/skin-03.jpg" alt="红白科幻" width="900"><br>
-  <sub>红白科幻</sub>
-</p>
+```bash
+bash macos/tests/run-tests.sh
+```
 
-<p align="center">
-  <img src="docs/images/gallery/skin-04.jpg" alt="清透定制" width="900"><br>
-  <sub>清透定制</sub>
-</p>
+## 常见问题
 
-<p align="center">
-  <img src="docs/images/gallery/skin-05.jpg" alt="灵感小宇宙" width="900"><br>
-  <sub>灵感小宇宙</sub>
-</p>
+<details>
+<summary><strong>这是 Wallpaper Engine 的替代品吗？</strong></summary>
 
-<p align="center">
-  <img src="docs/images/gallery/skin-06.jpg" alt="紫夜限定" width="900"><br>
-  <sub>紫夜限定</sub>
-</p>
+不是。它只控制 Codex 应用内部的主题背景。Windows 管理器可以导入普通 MP4/WebM，但不渲染 Wallpaper Engine 的 Scene、Web 或打包项目。
+</details>
 
-<p align="center">
-  <img src="docs/images/gallery/skin-07.jpg" alt="青蓝虚拟歌姬" width="900"><br>
-  <sub>青蓝虚拟歌姬</sub>
-</p>
+<details>
+<summary><strong>为什么 Codex 更新后主题可能失效？</strong></summary>
 
-<p align="center">
-  <img src="docs/images/gallery/skin-08.jpg" alt="舞台黑金" width="900"><br>
-  <sub>舞台黑金</sub>
-</p>
+Dream Skin 依赖 Codex 的 renderer DOM 和本机 CDP。官方更新可能调整结构；通常点击「启动 / 重新应用」即可恢复，兼容性修复会持续发布在本仓库。
+</details>
 
-## 它能做什么
+<details>
+<summary><strong>能否恢复完全原生的 Codex？</strong></summary>
 
-- **真·可交互**：侧栏、建议卡、项目选择、输入框都是原生控件，不是整窗假截图贴上去
-- **真背景层**：一张 16:9 纯壁纸连续铺满整窗，首页突出氛围，任务页自动降低干扰
-- **可换图**：换一张喜欢的纯背景，自适应焦点、安全区和配色后变成你的主题
-- **可播视频**：Windows 增强版支持本地 MP4/WebM 静音循环动态壁纸，页面隐藏时自动暂停
-- **可存主题**：macOS 菜单栏与 Windows 系统托盘都能保存/切换本地主题
-- **可恢复**：一键还原官方外观
-- **相对安全**：本机回环 CDP 注入，不改官方二进制与签名
+可以。Windows 管理器提供「恢复官方外观」，macOS Studio 也提供卸载/恢复入口。项目不会修改官方应用包。
+</details>
 
-## 快速开始
+<details>
+<summary><strong>壁纸文件会上传吗？</strong></summary>
 
-仓库内按平台放了现成脚本（实现细节不同，效果都是「主题化 Codex」）：
+不会。壁纸与主题保存在本机，注入只通过本机回环连接完成。
+</details>
 
-| 平台 | 目录 | 入口 |
-|------|------|------|
-| Apple Silicon / Intel Mac | [`macos/`](./macos/) | 双击 `Install Codex Dream Skin.command` |
-| Windows | [`windows/`](./windows/) | `scripts/install-dream-skin.ps1` → `start-dream-skin.ps1` |
+## 文档
 
-更细的说明：
+- [Windows 使用说明](./windows/README.md)
+- [macOS 使用说明](./macos/README.md)
+- [平台与路径对照](./docs/platforms.md)
+- [效果展厅](./docs/showcase.md)
+- [参考生图提示词](./docs/reference-background-prompt-guide.md)
+- [概念图提示词](./docs/background-generation-prompts.md)
+- [项目记录](./docs/PROJECT.md)
 
-- Mac：[`macos/README.md`](./macos/README.md)
-- Windows：[`windows/SKILL.md`](./windows/SKILL.md)
-- 路径对照：[`docs/platforms.md`](./docs/platforms.md)
-- 可直接复制的参考生图模板：[`docs/reference-background-prompt-guide.md`](./docs/reference-background-prompt-guide.md)
-- 八种概念方向详细提示词：[`docs/background-generation-prompts.md`](./docs/background-generation-prompts.md)
-- 项目记录：[`docs/PROJECT.md`](./docs/PROJECT.md)
+## 赞助商
 
-## 反馈与贡献
+<p align="center">
+  <a href="https://passion8.cc/register?aff=TuPe">
+    <img src="docs/images/sponsor-passion8.png" alt="Passion8" height="64">
+  </a>
+</p>
 
-- **Issue：** 请用 [Issue 模板](./.github/ISSUE_TEMPLATE/)（Bug / 功能）；已关闭空白 Issue。提交前建议先跑 Verify / Restore 自检。
-- **PR：** 请按 [PR 模板](./.github/pull_request_template.md) 写清改动，并勾选对应自测（如 `macos/tests/run-tests.sh`、verify / restore）。
+感谢 [passion8.cc](https://passion8.cc/register?aff=TuPe) 赞助本项目。换肤与 API 配置互相独立，本项目不会自动改写模型供应商设置。
 
-## 安全边界
+## 反馈与贡献
+
+- 使用 [Bug / 功能 Issue 模板](./.github/ISSUE_TEMPLATE/) 提交问题。
+- PR 请说明平台、复现或目标、验证命令与恢复测试。
+- 贡献指南：[中文](./.github/CONTRIBUTING.md) · [English](./.github/CONTRIBUTING.en.md)
 
-- CDP 只绑 `127.0.0.1`，主题运行期间勿跑来路不明的本机程序
-- 不修改官方安装目录与代码签名
-- **不会**自动改写 API Key / Base URL；中转与换肤分开
+本仓库是 [Fei-Away/Codex-Dream-Skin](https://github.com/Fei-Away/Codex-Dream-Skin) 的增强派生版本，并保留完整上游历史。
 
 ## 许可与声明
 
-- 见 [`macos/LICENSE`](./macos/LICENSE)（MIT）与 [`macos/NOTICE.md`](./macos/NOTICE.md)
-- 非 OpenAI 官方产品；Codex 及相关权利归其权利人
-- 随仓库预设及效果图中的人物 / IP 素材仅作主题示意；商用或公开再分发请自行确认肖像、素材与商标权利
+[MIT License](./LICENSE)。非 OpenAI 官方产品；Codex 及相关商标归其权利人。随仓库预设与效果图中的人物/IP 素材仅作主题示意，公开再分发前请自行确认肖像、素材和商标权利。
 
 ---
 
-Star 一下，然后挑一张图，把你的 Codex 变成今天想要的样子。
+如果 Dream Skin 让你的 Codex 更像自己的工作空间，欢迎点一个 **Star**，也欢迎分享你的主题截图。