# elysia

**Repository Path**: liuwei_com/elysia

## Basic Information

- **Project Name**: elysia
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-24
- **Last Updated**: 2026-05-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Elysia Codex Pet

`Elysia` 是一个面向 Codex 使用场景制作的二次元 Q 版桌面宠物资源项目。仓库同时保留了可直接查看的成品产物，以及用于继续迭代的提示词、分帧素材、拼装脚本和 QA 校验结果。

对外展示上，这个仓库可以理解为：

- 一个已经做好的 Codex 宠物成品仓库
- 一个可继续修图、重建、校验的宠物制作工程

## 项目亮点

- 已产出完整宠物图集：`spritesheet.png`、`spritesheet.webp`
- 已拆分 9 组状态动画，便于预览、替换和继续修正
- 保留了提示词、参考图、布局导图、重建脚本和标准化脚本
- 附带 QA 预览图、逐状态 GIF 和校验 JSON，便于提交前自检

## 效果预览

### 总览图集

![spritesheet](elysia-pet-run/final/spritesheet.webp)

### 状态预览

`idle`

![idle](elysia-pet-run/qa/normalized-previews/idle.gif)

`waiting`

![waiting](elysia-pet-run/qa/normalized-previews/waiting.gif)

`review`

![review](elysia-pet-run/qa/normalized-previews/review.gif)

`jumping`

![jumping](elysia-pet-run/qa/normalized-previews/jumping.gif)

## 这是什么

这是一个围绕 `Elysia` 角色制作的 Codex 宠物资源仓库，角色定位是：

- 粉发蓝眼的 Q 版二次元少女
- 白色裙装，带浅紫色翼状肩部装饰
- 风格偏柔和、轻贴纸感、轮廓清晰、适合小尺寸阅读
- 状态表达覆盖待机、运行、挥手、等待、失败、审阅等 Codex 常见交互语义

当前仓库更偏向“宠物成品 + 可追溯工程文件”的组合形式，而不是单纯的展示图包。

## 成品产物

核心输出位于 `elysia-pet-run/final/`：

- `spritesheet.png`：主图集
- `spritesheet.webp`：便于展示与分发的 WebP 版本
- `normalized-atlas.png`：标准化后图集
- `validation.json`：图集校验结果
- `normalized-validation.json`：标准化图集校验结果

辅助 QA 产物位于 `elysia-pet-run/qa/`：

- `contact-sheet.png`：状态接触表预览
- `normalized-contact-sheet.png`：标准化版本总览
- `normalized-previews/*.gif`：每个状态的 GIF 预览
- `installed-readback.png`、`webp-readback.png`：导出/回读检查图

## 动画状态

图集规格来自 `elysia-pet-run/pet_request.json`：

- 图集尺寸：`1536 x 1872`
- 网格规格：`8 列 x 9 行`
- 单格尺寸：`192 x 208`

状态列表如下：

| State | Frames | 用途 |
| --- | ---: | --- |
| `idle` | 6 | 低干扰待机、呼吸、眨眼 |
| `running-right` | 8 | 向右拖拽移动 |
| `running-left` | 8 | 向左拖拽移动 |
| `waving` | 4 | 打招呼、吸引注意 |
| `jumping` | 5 | 轻跳/悬浮反馈 |
| `failed` | 8 | 失败、阻塞、取消反馈 |
| `waiting` | 6 | 等待输入、审批、响应 |
| `running` | 6 | 执行任务、处理中 |
| `review` | 6 | 审阅结果、准备完成 |

## 仓库结构

```text
F:\elysia
├─ build_elysia_pet.py                     # 主拼装脚本
├─ normalize_elysia_from_installed_atlas.py# 图集标准化脚本
├─ rebuild_elysia_hover_jumping.py         # jumping 行的局部重建脚本
├─ patch_elysia_jumping_row.py             # 局部替换 jumping 行
├─ elysia-pet-run
│  ├─ final                                # 最终图集与校验结果
│  ├─ frames                               # 各状态拆分后的单帧 PNG
│  ├─ normalized-frames                    # 标准化后的单帧 PNG
│  ├─ prompts                              # 角色与各状态提示词
│  ├─ qa                                   # 预览图、GIF、review、summary
│  └─ references                           # 参考图与布局导图
└─ pydeps                                  # 本地依赖相关目录
```

## 工程说明

这个仓库不只是放成品，还保留了完整的制作链路：

- `prompts/base-pet.md`：基础角色提示词
- `prompts/rows/*.md`：各状态生成提示词
- `prompts/row-retries/*.md`：状态重试提示词
- `frames/`：各状态导出的帧图
- `references/layout-guides/`：不同状态对应的布局导图
- `final/*.json`：图集透明像素、格子占用等校验结果

这意味着你既可以把它当成一个现成的 Codex 宠物成品仓库，也可以把它当成一个“如何做出这个宠物”的工程记录。

## 构建与维护说明

当前脚本基于 `Python` 和 `Pillow`，并且已经改成默认使用仓库内的相对目录：

- `build_elysia_pet.py`
- `normalize_elysia_from_installed_atlas.py`
- `rebuild_elysia_hover_jumping.py`
- `patch_elysia_jumping_row.py`

这些脚本现在默认围绕仓库内的 `elysia-pet-run/` 工作，不再依赖提交者本机盘符路径。

当前可复用的维护方式是：

1. 直接使用仓库中已保存的 `frames/`、`final/`、`qa/` 产物
2. 基于已存在帧图重建图集或重新生成标准化结果
3. 在需要时继续微调局部状态，例如 `jumping`

适合继续使用的脚本包括：

- `build_elysia_pet.py`：重建主图集
- `rebuild_elysia_hover_jumping.py`：修正 `jumping` 状态
- `patch_elysia_jumping_row.py`：局部替换跳跃行
- `normalize_elysia_from_installed_atlas.py`：基于已安装图集重新做标准化

需要说明的是，这个仓库当前更偏“成品与现有帧图可复用”，而不是“从最原始外部素材一键全流程再生成”。也就是说，继续维护没有问题，但最早期的外部临时素材来源信息已经被清理，不再作为对外发布内容保留。

## 适用场景

- 作为 Codex 宠物成品仓库提交到 Gitee / GitHub
- 继续微调角色动作、状态语义和画面稳定性
- 作为个人宠物制作流程样例保存
- 作为后续扩展其他 Codex 宠物时的参考模板