码团：我为 Codex 做了一只会工作的熊猫宠物

我想要的不是一只只会待在角落里的吉祥物，而是一个能跟上 Codex 工作节奏的伙伴：写代码时敲键盘，分析时盯着屏幕，等待确认时抬头看向我，空闲时则靠着沙发一样的工作站休息。

最终，它变成了「码团」——一只软萌毛绒风格的大熊猫，背着竹青色折叠工作站。完整宠物包、安装脚本和场景预览已经发布在 ma-tuan-codex-pet GitHub 仓库。

先把工作状态变成角色动作

角色的关键不只是长什么样，而是每一种系统状态有没有一眼就能看懂的动作。码团最终覆盖了九组标准动画：

• idle：靠着收起的工作站休息，轻微呼吸、眨眼和点头。
• running：打开工作站，持续敲键盘，代表写代码、运行命令或执行任务。
• review：身体前倾并逐段查看屏幕，用来表示分析、审计和测试。
• waiting：停止操作，抬头等待用户确认、授权或补充信息。
• failed：表现任务失败或精疲力尽。
• waving：举起单爪挥手。
• jumping：用高度变化表现开心跳跃。
• running-right / running-left：背着收起的工作站横向移动。

Codex 宠物协议没有为分析、审计、测试分别提供状态，所以它们共用 review 动画。这种约束反而让我更重视动作语言：一个动作必须足够清楚，又不能依赖文字和特效解释。

16 个方向让它真的在「看」

除工作状态外，码团还有从 000° 到 337.5° 的 16 个顺时针注视方向。眼睛先转动，头部随后跟随，耳朵只做轻微偏转。

这里最难的不是多画 16 张图，而是保持角色身份、身体中心和尺度稳定。如果每一帧的头、背包或脚都在漂移，连起来以后就不像转头，更像整个角色在抖动。

图集是一份严格的接口

最终产物遵循 Codex pet protocol v2：

• 图集尺寸：1536 × 2288
• 布局：8 列 × 11 行
• 单元格：192 × 208
• 标准动画：9 组
• 注视方向：16 个
• 图集格式：透明 WebP
• spriteVersionNumber：2

这些数字不是排版建议，而是接口。每一帧必须落在自己的格子里，透明区域、非空单元和色键边缘都要通过检查；角色看起来再可爱，只要越界或漏帧，在应用里就会变成裁切、跳动或错位。

一个不起眼但真实的返工：书包被截断

第一版的休息动画看起来有安全边距，但实际切帧前，六个姿势排得太密。书包外侧已经被相邻槽位截掉，缩放后再检查边缘，只会得到一个误导性的「没有碰边」结果。

修复方式不是继续移动成品帧，而是回到源条带：把每个完整姿势缩窄约 15%，强制角色、提手、背带、双脚和书包都留在独立槽位中，并保留足够的纯色间隔。修复后，休息动画的横向重心偏移从约 16.7px 降到 0.88px。

这次返工提醒我：最终画面边缘正常，并不代表上游切帧正确。验证动画资源时，必须同时检查源条带、切分结果和最终图集。

用量和恢复倒计时为什么不画进宠物

最初的设想还包括剩余用量、可充值次数和恢复倒计时。但宠物包本身没有账户接口，也不应该读取账户信息或把动态数字画死在图集中。

因此，码团只负责状态表达；当前剩余用量、重置或充值次数、恢复倒计时，以及达到限制时的提示，继续由 Codex 原生界面显示。是否在用量耗尽时进入 failed 状态，也由应用决定。

安装码团

macOS 或 Linux：

git clone https://github.com/Zsmboom/ma-tuan-codex-pet.git
cd ma-tuan-codex-pet
chmod +x install.sh
./install.sh

Windows PowerShell：

git clone https://github.com/Zsmboom/ma-tuan-codex-pet.git
cd ma-tuan-codex-pet
Set-ExecutionPolicy -Scope Process Bypass
.\install.ps1

也可以把仓库中的 ma-tuan 文件夹手动复制到 ~/.codex/pets/ma-tuan/。目标目录中必须同时包含 pet.json 和 spritesheet.webp。如果宠物列表没有立即刷新，请重新启动 Codex。

仓库中还包含每个场景的独立预览、休息动画 GIF、安装与卸载说明，以及 qa-summary.json 验证摘要。