黑毛 Codex Pet

钱大妈“黑毛”品牌 IP 的 Codex App 自定义宠物包。

本项目由钱大妈员工基于公开品牌形象制作，用于本地 Codex App 个性化展示，不代表钱大妈官方软件产品或技术支持承诺。品牌信息见钱大妈品牌页面。

角色预览

八个角色均提供 idle 动画预览；完整动作、方向图和验证记录见 qa/。

黑毛	品控官	大管家	厨师
美食家	配送员	福气官	旅行家

快速安装

安装后都需要在 Codex App 中打开“设置 -> 外观 -> 宠物”，点击“刷新（Refresh）”，再选择角色。安装命令不会自动切换当前宠物。

PetDex（推荐）

需要 Node.js 20 或更新版本：

npx -y petdex@latest install hei-mao

把 hei-mao 换成下方角色表中的其他 slug，也可以在命令末尾并列多个 slug。PetDex 使用已审核的公共版本；修复版在审核或 CDN 传播期间可能暂时尚未可见。

项目安装脚本

脚本会下载仓库发布的文件并校验 SHA，默认写入 ~/.codex/pets/<slug>/；设置 CODEX_HOME 后会使用该目录。

macOS / Linux：

curl --connect-timeout 10 --max-time 120 -fsSL https://raw.githubusercontent.com/MisonL/hei-mao/main/install.sh | bash -s -- hei-mao

Windows PowerShell：

& ([scriptblock]::Create((irm -TimeoutSec 120 https://raw.githubusercontent.com/MisonL/hei-mao/main/install.ps1))) -PetId hei-mao

Codex App 原生安装

适合需要使用本仓库当前图集的场景：

从 pets/<slug>/ 复制 pet.json 和 spritesheet.webp。
放入 ~/.codex/pets/<slug>/（Windows 为 %USERPROFILE%\.codex\pets\<slug>\）。
回到 Codex App，执行“刷新（Refresh）”并选择角色。

不要把整个 pets/ 父目录当作单个宠物导入，也不要使用历史 slug hei-mao-2 或 submit --force 创建重复条目。

角色

slug	角色	定位
`hei-mao`	黑毛	根角色，小猪形象
`hei-mao-quality`	品控官	品质检查与稳定性
`hei-mao-butler`	大管家	日常事务与整理
`hei-mao-chef`	厨师	食材与烹饪主题
`hei-mao-foodie`	美食家	美食探索与品尝
`hei-mao-delivery`	配送员	社区食材配送
`hei-mao-fortune`	福气官	新鲜、丰盛与好彩头
`hei-mao-traveler`	旅行家	社区连接与食材探索

每个角色都包含 pet.json 和 v2 精灵图，标准动作包括 idle、running-right、running-left、waving、jumping、failed、waiting、running 和 review，另有 16 个观察方向。

创建与发布

在 ChatGPT 桌面应用安装 Hatch Pet，输入 /pet 描述角色和动作。
在 Codex App 中先检查动画、比例和透明背景。
确认目录根部包含 pet.json 与 spritesheet.webp；本项目采用 v2 图集（1536x2288、8x11）。
登录 PetDex 中文文档的提交入口，上传目录或 ZIP 并等待审核。

命令行用户可以运行：

npx -y petdex@latest login && npx -y petdex@latest submit ~/.codex/pets/<slug>

提交前请确认素材版权或发布授权，避免重复 slug。需要制作参考图时，可选用 Visual Journal；它不替代 Hatch Pet 的图集生成和 PetDex 校验。

当前验证

八个角色均通过 v2 结构门禁：1536x2288、8x11、RGBA WebP、spriteVersionNumber: 2。
安装器回归覆盖支持 slug、重装、冲突保护、失败回滚和路径规范化；最新结果为 30 passed。
当前媒体、视觉和安装器证据集中在 qa/README.md；静态 QA 不替代 Codex App 实时刷新、动画播放、多角色和多屏验收。
PetDex 的管理员审核和公共 CDN 传播是外部流程；公共版本与仓库图集可能暂时不同步。

项目结构

路径	内容
`pets/<slug>/`	可分发的 `pet.json` 和 `spritesheet.webp`
`prompts/`	基础形象和动画行提示词
`qa/`	结构、媒体、视觉和发布证据
`install.sh` / `install.ps1`	macOS、Linux、Windows 安装器
`ASSETS-LICENSE.md` / `NOTICE` / `LICENSES/`	资产条款、声明和代码许可证

开发与验证

这是资产包，没有传统的应用构建步骤。修改安装器后运行：

bash -n install.sh
shellcheck -S warning install.sh
node --test tests/installers.test.mjs

修改精灵图时，按 qa/README.md 使用 hatch-pet bundled runtime 重新生成媒体和验证证据，不要用裸系统 Python 替代。

许可证

安装器及其独立功能代码采用 Apache License 2.0。
黑毛品牌名称、角色图集、图片、视频、描述和提示词适用品牌资产使用条款，不属于 Apache-2.0 授权范围。
Apache-2.0 不授予钱大妈或黑毛相关商标权。

MisonL/hei-mao

README