# CodexPetdexSkins

**Repository Path**: IceSaury/codex-petdex-skins

## Basic Information

- **Project Name**: CodexPetdexSkins
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-23
- **Last Updated**: 2026-07-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CodexPetdex

CodexPetdex 是一个面向 Windows 的 Codex 外观管理工具，用于管理主题、完整皮肤、壁纸、宠物和一键搭配。它不会修改 Codex 的 ASAR 或 MSIX 文件；需要改变原生配置时，会先备份 `~/.codex/config.toml`，皮肤和壁纸预览则通过仅监听 `127.0.0.1` 的本机 CDP 连接完成。

> 平台：Windows 10/11 x64
>
> 前提：已安装官方 Codex Desktop

## 工具展示页面

![皮肤](docs/screenshots/miku.png)

![总览](docs/screenshots/dashboard.png)

![皮肤](docs/screenshots/skins.png)

![壁纸](docs/screenshots/wallpapers.png)

![宠物](docs/screenshots/petdex.png)

## 功能

- 导入、预览、收藏和应用 `codex-theme-v1:` 主题
- 导入兼容 `schemaVersion: 2` 的 `.codexskin` 完整皮肤包
- 通过本机回环 CDP 注入背景、人物、图标、卡片、输入框和非交互装饰层
- 首次建立连接后，皮肤和壁纸支持实时预览、切换和停用
- 管理壁纸透明度，并在“仅工作区覆盖”和“全屏覆盖”之间切换
- 壁纸与完整皮肤互斥，切换时会清理另一种注入效果
- 扫描 `~/.codex/pets`，预览、选择和删除本地宠物
- 通过 Petdex slug 安装宠物，提供真实下载进度、文件写入和主题导入阶段反馈
- 将主题和宠物保存为一键搭配
- 托盘常驻、启动时 CDP 预连接，以及按需重启 Codex

## 安装

1. 在 Release 页面下载 `CodexPetdex-<version>-x64-setup.exe`。
2. 双击安装包，选择安装目录；安装器可创建桌面和开始菜单快捷方式。
3. 启动 CodexPetdex，首次加载完成后即可管理外观。

安装包与 Codex 皮肤也可通过[百度网盘下载](https://pan.baidu.com/s/1gMoYGxd5k8j4J2iz_JLqKA)，提取码：`6v9c`。

## 快速开始

### 1. 主题

1. 打开“主题”。
2. 导入 `codex-theme-v1:` 字符串，或从已有主题中选择。
3. 点击“预览”可立即调整管理器自身配色。
4. 点击“应用”将主题写入 Codex 配置；若开启自动重启，Codex 会立即重新读取配置。

### 2. 完整皮肤

1. 打开“皮肤”，导入 `.codexskin` 文件。
2. 点击“预览”，首次使用会启动一次 Codex 并建立本机 CDP 连接。
3. 在连接存续期间，切换皮肤或停用预览不需要重复重启 Codex。
4. 确认效果后点击“设为当前”，以便下次通过管理器启动或重启 Codex 时恢复该皮肤。

皮肤包中的原生 Accent、字体和代码主题需要 Codex 重启后才能完整读取；可在“设置”中决定设为当前后是否自动重启。

### 3. 壁纸

1. 打开“壁纸”，导入本地图片。
2. 点击“预览”查看实时效果，再点击“设为当前”保存选择。
3. 使用“工作区 / 全屏覆盖”开关控制覆盖范围，默认仅覆盖右侧工作区。
4. 使用“背景透明度”滑块调节图片可见度。

启用完整皮肤时会自动停用壁纸，反之亦然。

### 4. 宠物

1. 打开“宠物”。
2. 在“从 Petdex 安装”输入框填写 Petdex slug，例如 `wangcai`。
3. 点击“安装”，观察资源、配置、精灵图、主题导入和完成进度。
4. 在宠物卡片点击“选择”，将当前宠物写入 Codex 配置。

宠物配置需要 Codex 完全重启后生效。建议使用管理器的“重启 Codex”功能，而不是只关闭窗口，确保后台进程也会退出并重新读取配置。

### 5. 搭配

打开“搭配”，选择一个主题和宠物并保存。以后可一键应用这组组合。

## CDP 与隐私

- CDP 仅绑定 `127.0.0.1`，不会暴露到局域网。
- 连接状态显示在管理器左下角：已连接为绿色，连接中为蓝色，重连为橙色，异常为红色。
- 关闭管理器时只断开 CDP 连接，不会关闭、重启或重新打开 Codex，也不会清除当前已注入的预览效果。

## 完整皮肤格式

`.codexskin` 是 ZIP 容器，根目录包含 `theme.json`、`theme.css`、可选 `chrome.html`、`assets/` 和 `previews/`。

导入阶段会拒绝路径穿越、符号式路径、外部 CSS URL、脚本、事件属性、未声明文件、伪装图片、超大素材和超出作用域的样式。合法但未限定作用域的选择器会自动收敛到 `html.codex-theme-studio`。

## 本地开发

```powershell
npm install
npm run dev
```

## 测试与发布构建

```powershell
npm test
npm run build
npm run pack
```

`npm run pack` 会生成 NSIS 安装包：

```text
release/CodexPetdex-<version>-x64-setup.exe
```

如需生成无需安装的便携版：

```powershell
npm run pack:portable
```

## 自动更新

Windows 安装版会在启动时从 GitHub Release 检查更新，并在发现新版后自动下载；下载完成后可在“设置”中选择“重启并安装”。便携版不支持自动更新。

发布安装版时，请将以下文件一同上传到同一个 GitHub Release：

- `CodexPetdex-<version>-x64-setup.exe`
- `CodexPetdex-<version>-x64-setup.exe.blockmap`
- `latest.yml`

`latest.yml` 是更新器读取版本、下载地址和校验值所必需的发布元数据。

## 项目结构

- `electron/`：主进程、托盘、配置、CDP、皮肤 Runtime 与资源管理
- `src/`：React + Fluent UI 管理器界面
- `plugins/codex-appearance-manager/`：Codex 插件清单、Skill 与启动脚本
- `docs/screenshots/`：README 截图目录，等待补充

## 许可证

本项目采用 [MIT License](LICENSE)。`skins/` 目录中的个人素材不在仓库版本控制和授权范围内。