# 豆包（Doubao）— ChatGPT Codex Desktop Pet

一个用于 **ChatGPT Codex 桌面应用**的社区自定义宠物：圆润豆型身材、短棕发、大眼睛和黑色连体服。它是一个本地资源包，安装后可在 Codex 的“宠物”设置中选择、唤醒和拖动。

![豆包精灵图](./spritesheet.webp)

> 这是独立的社区项目，与 OpenAI 无隶属、赞助或认可关系。

## 特性

- 待机、左右走动、挥手、跳跃、等待、困惑/失败、跑动和查看等动画。
- 透明 WebP 精灵图，适合桌面悬浮宠物显示。
- 不需要 `OPENAI_API_KEY`；仅复制并选择本地宠物资源即可使用。
- 宠物只改变外观，不会影响 Codex 的模型、权限、审批或任务行为。

## 兼容性

- 当前包面向 Windows 版 ChatGPT Codex 的本地自定义宠物目录。
- 使用 `spriteVersionNumber: 2`：精灵图尺寸为 **1536 × 2288 px**，固定为 **8 列 × 11 行**，每格 **192 × 208 px**。
- 文件是带 alpha 透明通道的 WebP，约 1.9 MiB。

ChatGPT Codex 的宠物功能可能随版本演进。如果列表未识别资源，请先更新应用，然后在 **设置 → 宠物** 中点击 **刷新**。

## 安装

1. 下载本仓库的 Release，或克隆仓库：

   ```powershell
   git clone https://github.com/YChao18/ChatGPT-Codex-Desktop-Pet-Doubao.git
   ```

2. 在 ChatGPT Codex 中打开 **设置 → 宠物**，点击页面底部的 **打开文件夹**，确认本机自定义宠物目录。Windows 默认位置为：

   ```text
   C:\Users\<你的用户名>\.codex\pets\
   ```

3. 将仓库中的整个 `doubao` 宠物文件夹内容复制为：

   ```text
   C:\Users\<你的用户名>\.codex\pets\doubao\
   ├── pet.json
   └── spritesheet.webp
   ```

4. 返回 **设置 → 宠物**，点击 **刷新**，选择 **豆包**。
5. 点击 **唤醒宠物**，或在任务中输入 `/pet`。再次输入 `/pet`、使用命令菜单，或点击 **收起宠物** 可隐藏它。

宠物的选择和桌面位置会在重启应用后保留。

## 使用

豆包根据 Codex 任务状态自动显示相应动画：

| 任务状态 | 含义 |
| --- | --- |
| 运行中 | 任务正在执行。 |
| 需要输入 | 任务等待批准、回答或其他决定。 |
| 就绪 | 任务已完成，且有未读活动。 |
| 已阻塞 | 任务失败或遇到系统错误。 |

点击悬浮宠物可返回 Codex；有多个任务活动时，可从活动托盘选择任务。桌面版允许将宠物拖到任意屏幕位置。

## 宠物包格式

### 文件结构

```text
doubao/
├── pet.json
└── spritesheet.webp
```

### `pet.json`

```json
{
  "id": "doubao",
  "displayName": "豆包",
  "description": "豆包：友善、好奇、贴心的黑衣短发桌面伙伴。",
  "spriteVersionNumber": 2,
  "spritesheetPath": "spritesheet.webp"
}
```

| 字段 | 说明 |
| --- | --- |
| `id` | 宠物的稳定唯一标识；建议使用小写字母、数字和连字符。 |
| `displayName` | 在宠物列表中显示的名称。 |
| `description` | 在宠物列表中显示的简短介绍。 |
| `spriteVersionNumber` | 精灵图布局版本；本项目固定为 `2`。 |
| `spritesheetPath` | 相对 `pet.json` 的精灵图路径。 |

### `spritesheet.webp`

本项目的本地图集是 **1536 × 2288 px**、**8 × 11 格**。所有帧都必须保持透明背景、统一角色比例和相近的脚线位置。不要裁掉、缩放、重新排列或压缩成不支持 alpha 的格式。

| 行（从 0 开始） | 动画状态 | 常用帧数 |
| --- | --- | --- |
| 0 | `idle` 待机、呼吸、眨眼 | 6 |
| 1 | `running-right` 向右走 | 8 |
| 2 | `running-left` 向左走 | 8 |
| 3 | `waving` 挥手 | 4 |
| 4 | `jumping` 跳跃 | 5 |
| 5 | `failed` 困惑、低落或失败反应 | 8 |
| 6 | `waiting` 等待、困倦 | 6 |
| 7 | `running` 跑动、开心弹跳 | 6 |
| 8 | `review` 查看、思考 | 6 |
| 9–10 | v2 布局兼容帧 | 保留当前内容 |

### 与“上传宠物”入口的区别

官方 **Upload pet / 上传宠物** 流程使用另一种上传规格：透明 PNG/WebP、严格 **1536 × 1872 px（8 × 9）**、不超过 20 MiB。

因此，**不要直接上传本仓库的 `spritesheet.webp`**；它是本地 `spriteVersionNumber: 2` 包所需的 1536 × 2288 图集。若要使用上传入口，请单独导出 8 × 9 的上传版并先在应用中测试。

## 自定义与二次创作

1. 复制 `doubao` 目录并换成新名称，例如 `my-pet`。
2. 修改 `pet.json` 的 `id`、`displayName`、`description`。
3. 保持 1536 × 2288 的透明 8 × 11 图集布局，替换 `spritesheet.webp`。
4. 将新目录放到 `C:\Users\<用户名>\.codex\pets\`。
5. 回到 **设置 → 宠物** 点击 **刷新**，选择新宠物。

为减少播放跳动，请保持每一帧的头身比例、基准脚线和角色中心一致，只改变必要的表情或姿势。

## 故障排查

### 设置里看不到豆包

- 确认路径是 `C:\Users\<用户名>\.codex\pets\doubao\pet.json`，没有多嵌套一层目录。
- 确认 `spritesheetPath` 与真实文件名完全一致。
- 在 **设置 → 宠物** 点击 **刷新**；必要时重启 Codex。
- 更新到支持宠物功能的 ChatGPT Codex 桌面版。

### 宠物不动

- 检查系统辅助功能中的“减少动画”。开启后，Codex 会使用静态帧。
- 确认图集仍为 1536 × 2288，且未改变其 8 × 11 布局。

### 出现黑底或边缘异常

- 导出时保留 alpha 透明通道；不要转为 JPEG 或不透明背景。
- 避免阴影、地面或半透明光晕越过单帧边界。

## 发布与贡献

- 本仓库采用 [MIT License](./LICENSE)。
- Issue 和 Pull Request 均欢迎；请避免提交账号数据、`C:\Users\...` 路径或应用安装文件。
- 提交新的精灵图前，请验证尺寸、透明通道、文件体积和动作行顺序。

## 参考

- [ChatGPT Codex Pets 官方说明](https://learn.chatgpt.com/docs/pets.md)
- [ChatGPT Codex 桌面应用设置](https://learn.chatgpt.com/docs/reference/settings#pets)