MIBO 宠物包制作说明¶

最后更新：2026-08-18

本说明用于把角色图片制作成 MIBO 可直接加载的 .mibo-pet。宠物包不是一张立绘，也不是把 PNG、GIF、视频或 ZIP 改后缀；它包含角色动作、逐帧时长、日夜背景、透明信息、索引、压缩数据和完整性校验，必须使用 MIBO 项目的打包工具生成。

推荐让 Codex 完成素材整理、图片生成或编辑、动作拆分、清单编写、打包和校验。用户负责提供角色要求、合法可用的参考素材，并对角色相似度和最终画面做确认。

1. 最终交付格式¶

项目	要求
正式目录	`/mibo/资源/宠物/`
文件后缀	`.mibo-pet`
当前格式	`mibo.pet-pack/6`，文件头为 `MPET`
逻辑屏幕	`820×320`
包大小上限	24 MiB
包内背景	10–20 张，必须同时有普通白天和普通夜间背景
常用角色帧	透明 PNG，默认画布 `192×208`
大道具动作	可按动作使用 `320×208` 或 `384×256`
打包后帧数据	RGB565 + 透明掩码，逐帧 LZ4 压缩并带 CRC

.mibo-pet 是最终运行文件，不要尝试直接解压修改。需要改角色或动作时，应修改源工程后重新打包。

2. 开始前准备¶

至少准备以下信息：

角色名称和一个稳定的英文 ID，例如 orange-cat。
一到数张清晰参考图，最好包括正面、侧面和典型表情。
必须保留的身份特征：发型、颜色、服装、配饰、轮廓、体型等。
希望采用的视觉风格，例如像素、贴纸、手绘或柔和卡通。
是否有角色专属道具，以及哪些动作需要使用。
背景主题、日夜偏好和不希望出现的元素。
参考图和角色形象的使用授权。

不要要求 Codex 猜测商标、人物或角色的授权状态。没有权利使用的素材，不应制作或分发为宠物包。

3. 推荐的完整宠物基线¶

MIBO 的打包器允许扩展动作数量，但为了获得完整联动体验，建议沿用当前完整模板：14 张背景、 20 个动作、123 张独立帧和 134 个播放步骤。

3.1 标准动作¶

动作 ID	推荐帧数	用途
`idle`	6	待机呼吸和眨眼
`running-right`	8	向右移动
`running-left`	8	向左移动
`waving`	4	打招呼
`jumping`	5	跳跃或庆祝
`failed`	8	失败或失落反应
`waiting`	6	等待状态
`running`	6	角色化的日常忙碌动作
`review`	6	回顾或检查动作
`look-around`	由 16 向注视帧组合	环顾和视线互动

完整 Codex v2 图集使用 1536×2288、8 列 × 11 行、单格 192×208。前 9 行承载标准动作，最后 2 行承载 16 个注视方向。不要通过水平翻转冒充所有方向；左右动作、服装和不对称配饰应逐帧检查。

3.2 MIBO 扩展动作¶

推荐提供以下 10 个动作，每个动作通常使用 6 张透明帧：

accelerate：加速反应。
brake：制动反应。
charging：充电状态，可设计为进入后循环。
clean：清洁或整理。
eat：进食。
evcc-hello：EVCC 欢迎动作。
music-dance-60：接近 60 BPM 的慢速音乐动作。
music-dance：120 BPM 或 BPM 缺失时的主音乐动作。
music-dance-180：接近 180 BPM 的快速音乐动作。
sleep：睡眠或夜间待机。

这些数量是推荐的完整体验基线，不代表每个包都必须机械复制同一种表演。动作应该符合角色性格，但 ID 和事件语义不能随意改变。

3.3 背景¶

推荐 14 张背景：4 组日夜成对场景，加上雨天、春、秋、冬、春节和中秋场景。每张源图必须为 820×320，背景中不要重复画入角色、界面、文字、水印或 Logo。

背景清单的 appearance 必须是：

day：只用于白天。
night：只用于夜间。
both：日夜均可使用的中性场景。

至少要有一张非节日 day 和一张非节日 night 背景。

4. 让 Codex 制作宠物包¶

4.1 导入 MIBO Skill¶

本说明书旁的 mibo-assistant/ 是 MIBO Skill。把整个目录导入 Codex 后，在任务中明确使用 $mibo-assistant。Skill 会让 AI 先读取当前工程和模板，再按 MIBO 的真实格式制作与校验。

如果没有导入 Skill，也可以把本说明和 MIBO 工程一起提供给 Codex，但每次都要提醒它先核对当前打包器，不要凭记忆生成清单。

4.2 第一次提示词¶

可以直接复制以下内容，再补充角色信息：

请使用 $mibo-assistant，在当前 MIBO 工程中制作一个正式 MPET v6 宠物包。

角色名称：<名称>
稳定 ID：<小写英文 ID>
视觉风格：<像素/贴纸/手绘等>
必须保留的身份特征：<发型、颜色、服装、配饰、轮廓>
专属道具：<没有则写“无”>
背景方向：<场景和日夜偏好>
参考素材：<文件路径；这些素材已经获得使用授权>

先读取 tools/build_pet_pack.py、tf-card/mibo/资源/宠物/README.md，以及
assets/pet-concepts/codex-mibo 中一个通过 QA 的完整模板。先输出制作计划、缺失输入、
动作清单和背景清单，不要覆盖现有宠物或复制到正式 TF 目录。得到我确认后再生成素材。

这一步的目标不是立刻生成 123 张图片，而是先锁定角色身份、动作语义、背景方案和交付范围。

4.3 分阶段生成¶

让 Codex 按以下顺序工作，每一阶段确认后再进入下一阶段：

身份基准：制作正面、侧面、背面、配色和表情表，确认角色不会漂移。
标准动作：先做待机、左右移动、挥手、跳跃和失败等 9 组动作。
注视方向：补齐两行 16 向注视，检查瞳孔、脸型和不对称配饰。
扩展动作：制作车辆、音乐、EVCC 和照料动作。
背景：制作 10–20 张背景，并正确标注白天、夜间、季节和节日。
清单与播放：编写动作清单、逐帧时长、循环方式、优先级和冷却时间。
视觉 QA：生成接触表、逐动作 GIF 和背景总览，逐项修复。
打包 QA：两次独立构建、比较 SHA-256、解析成品并运行测试。
部署 QA：复制到 TF 后，在实体 MIBO 上检查动作、背景和长时间运行。

如果 Codex 具备图片生成或编辑能力，应让它直接生成或编辑光栅素材，并查看每轮成品原图。提示词本身、低分辨率缩略图或单张参考图都不能代替逐帧检查。

4.4 视觉复核提示词¶

继续使用 $mibo-assistant。请先不要打包，生成以下 QA 资料：
1. 所有标准动作接触表；
2. 16 向注视表；
3. 每个扩展动作的透明背景 GIF；
4. 14 张背景总览；
5. 角色叠加到每张背景上的 820×320 预览。

逐项检查角色身份漂移、左右方向、帧间跳动、脚底基线、透明边缘、裁切、道具归属、
可读文字和水印。列出问题和修复证据，未经我确认不要复制到正式宠物目录。

4.5 最终打包提示词¶

视觉稿已确认。请使用 $mibo-assistant 按当前 tools/build_pet_pack.py 的契约完成打包。
先在临时输出位置连续构建两次并比较 SHA-256；然后记录打包器输出摘要、检查 MPET 文件头，
运行 python3 tools/test_pet_pack.py，并汇总背景数、动作数、帧数、播放步骤、包大小和校验结果。
只有两次构建字节一致且所有检查通过后，才建议我把成品复制到
/mibo/资源/宠物/。不要删除或覆盖现有包，除非先列出目标并得到确认。

5. 宠物源工程结构¶

推荐以已经通过 QA 的概念工程为模板复制一份，不要从空目录猜字段：

<pet-id>/
├── action-director.json
├── backgrounds/
│   ├── manifest.json
│   └── 820x320/*.png
├── frames/
│   ├── idle/*.png
│   ├── running-right/*.png
│   ├── running-left/*.png
│   └── ...其他标准动作...
├── final/
│   └── spritesheet-extended.webp
├── extended-clips/
│   ├── manifest.json
│   └── frames/<clip-id>/*.png
└── qa/
    ├── contact-sheet.png
    ├── extended-clips-contact-sheet.png
    └── background-contact-sheet.png

可参考：

assets/pet-concepts/codex-mibo/：多个完整宠物源工程和汇总 QA。
assets/pet-concepts/mibao-style-review-v2-cute/：单个宠物的动作、清单和视觉检查示例。

绝对路径、临时目录和某台电脑上的缓存路径不应写进可交付清单。

6. 动作素材规则¶

同一角色在所有动作中必须保持配色、比例、服装和配饰一致。
每一帧使用透明背景，不要带棋盘格、绿幕残色或整图阴影。
默认画布为 192×208；只有道具确实越界时才使用支持的大画布。
同一动作的所有帧必须使用相同画布、锚点和脚底基线。
球、电脑、食物、麦克风、被褥等必须画入对应透明帧，不能指望 MIBO 运行时补画。
不要让道具在相邻帧中忽隐忽现或穿过角色身体。
循环动作的最后一帧回到第一帧时不能明显跳动。
动作中不要加入可读文字、商标、水印或独立漂浮光效。
标准帧和注视图集应使用一致的像素缩放方法；像素风通常采用最近邻缩放。

7. 背景清单示例¶

backgrounds/manifest.json 使用 mibo.backgrounds/1：

{
  "schema": "mibo.backgrounds/1",
  "petId": "orange-cat",
  "canvas": [820, 320],
  "backgrounds": [
    {
      "id": "day-window",
      "file": "820x320/day-window.png",
      "appearance": "day",
      "tags": ["day", "default"],
      "ambient": "clouds"
    },
    {
      "id": "night-window",
      "file": "820x320/night-window.png",
      "appearance": "night",
      "tags": ["night", "default"],
      "ambient": "stars"
    }
  ]
}

所有 ID 使用稳定 ASCII 名称。文件改名、ID 改名和标签变化都会影响运行时选择，正式发布后不要随意修改。

8. 打包与校验¶

在 MIBO 工程根目录运行：

python3 tools/build_pet_pack.py \
  --concept <宠物源工程目录> \
  --output <输出目录>/<宠物名称>.mibo-pet

python3 tools/test_pet_pack.py

build_pet_pack.py 会在构建过程中校验当前源工程，并输出本次成品的背景、动作、帧、步骤、大小和 CRC 摘要。test_pet_pack.py 是对当前打包器和仓库标准包的回归测试，不会仅因传入一个新文件就替代成品专属检查；因此仍要核对本次构建摘要、文件头、双构建摘要和实体设备结果。

推荐在两个不同的临时输出路径各构建一次，再比较：

shasum -a 256 <第一次输出>.mibo-pet <第二次输出>.mibo-pet

两个摘要应完全一致。还应确认：

文件头为 MPET，运行格式为 v6。
包不超过 24 MiB。
背景为 10–20 张，日夜候选都存在。
所有动作 ID 唯一，帧数和播放步骤没有越界。
每个动作的画布、锚点、透明掩码和 CRC 都能被解析。
接触表、GIF 和背景预览与打包前确认的素材一致。

项目测试通过只证明主机端格式和解析符合预期，不证明实体屏幕显示已经通过。

9. 部署到 TF 卡¶

保留当前正在使用的宠物包。
把新 .mibo-pet 复制到 /mibo/资源/宠物/，不要建立子目录。
安全推出 TF 卡，或等待恢复模式上传完整结束。
启动 MIBO，执行“系统维护 → 重建 TF 索引”。
在 EVCC 的宠物页面配置中选择新包。

不要用同名文件直接覆盖正在验证的唯一可用包。更稳妥的做法是先使用不同文件名并行安装，验收通过后再删除旧包。

10. 实体 MIBO 验收¶

至少检查：

宠物包能够被发现、选择和重新加载。
待机和移动动画流畅，左右方向正确。
角色靠近边缘或放大互动时没有裁切、错位或透明黑边。
加速、制动、充电、音乐和照料动作能正确触发和结束。
三档音乐动作都能播放；缺少 BPM 时能回到主音乐动作。
白天/夜间切换会进入正确背景池。
季节和节日背景不会参与错误的普通轮换。
连续运行和多次切包不会黑屏、花屏或丢失上一包。

11. 常见错误¶

错误	结果	修正
给 ZIP、PNG 或 GIF 改成 `.mibo-pet`	MIBO 拒绝加载	使用 `build_pet_pack.py` 正式打包
只制作一张角色立绘	没有可运行的动作	按标准与扩展动作逐帧制作
角色每个动作长得不同	切换时身份漂移	先锁定身份表，再逐动作生成和复核
左跑由右跑简单镜像	配饰、服装或方向错误	单独检查并修正左右动作
道具单独保存	MIBO 不会自动合成	把道具画入该动作的每个透明帧
背景没有 `appearance`	打包失败	为每张背景标注 `day/night/both`
背景少于 10 张	打包失败	补足到 10–20 张并包含普通日夜图
只看静态接触表	看不出循环跳帧	同时生成 GIF 并逐动作播放检查
只构建一次	难以发现非确定性输出	构建两次并比较 SHA-256
测试通过就宣称真机通过	证据不足	最后完成实体 MIBO 验收