# 与 Codex Pets 的差距分析

> 对照基准：[`docs/Codex-Pet-能力分析.md`](Codex-Pet-能力分析.md)（官方源码 + 官方 hatch-pet 契约 + 社区生态）。
> 状态图例：✅ 已复刻 · 🟡 部分/降级复刻 · ❌ 未复刻（含原因）

## 1. 状态动画（9 行 V1 图集）

| Codex 能力 | 状态 | 说明 |
| --- | --- | --- |
| idle / running / waiting / failed / review 五行驱动 | ✅ | 与官方行序、帧数、逐帧时长一致 |
| jumping（完成庆祝） | ✅ | running `true→false` 边沿触发约 2.6s |
| waving（打招呼） | ✅ | 会话切换/打开时触发约 1.7s（对应 SessionStart 瞬时态） |
| running-right / running-left（移动方向） | ✅ | 拖拽时按水平方向播放对应行走行 |
| 官方逐帧时长表 | ✅ | `STATE_DURATIONS_MS` 与 `animation-rows.md` 逐帧一致 |

## 2. 与 agent 状态的联动（ambient.rs）

| Codex 能力 | 状态 | 说明 |
| --- | --- | --- |
| 通知→动画映射（Running/Waiting/Review/Failed） | ✅ | DSH 侧信号：`summary.running` / `pendingInteraction` / `completed` / `snapshot.lastAgentError` |
| 状态标签 Running / Needs input / Ready / Blocked | ✅ | 与 ambient.rs 文案一致（曾用 "Working"，已对齐） |
| 状态存活期（Running 3min / Failed 1h / Waiting 24h / Review 7d → idle） | ✅ | `decaySignals` + 各信号首见时间戳实现，超时回退 idle |
| 减少动态模式（固定 idle 第一帧） | ✅ | 跟随系统 `prefers-reduced-motion`，设置里可手动锁定 |
| transient / sticky / release 三模式事件流 | 🟡 | DSH 提供的是会话级快照而非事件流；用「首见时间戳 + TTL」等价表达 sticky/decay，transient（wave/celebrate）用 until 时间戳表达 |

## 3. 包格式（pet.json + 图集）

| Codex 能力 | 状态 | 说明 |
| --- | --- | --- |
| pet.json 全字段解析（id/displayName/description/spritesheetPath/frame/animations/spriteVersionNumber） | ✅ | `parsePetJson` 与官方 model.rs 默认值/校验一致 |
| 行优先图集、无独立 atlas 文件 | ✅ | `index = row×columns + col` |
| AnimationSpec（frames/fps/loop/fallback） | ✅ | 含 `loop:false` 播完停在末帧 |
| V2 图集（1536×2288、16 注视方向、`spriteVersionNumber: 2`） | ❌ | 官方 TUI 源码未实现，支持度「待确认」；字段会被解析保留但不消费 |

## 4. 宠物形态与管理

| Codex 能力 | 状态 | 说明 |
| --- | --- | --- |
| 多只内置宠物 + 选择器 | 🟡 | 内置 5 只（Dee/Amber/Berry 同模配色 + 灰鲸 Harness / 蓝鲸 DeepSeek 两只 logo 鲸鱼），设置面板切换；官方约 8 只不同造型的图集无法直接分发（版权/资产来源），用自定义导入替代 |
| 自定义宠物包加载 | ✅ | 设置面板导入 `pet.json` + 图集图片（如 `~/.codex/pets/` 下 hatch-pet 产物），校验入库存 localStorage，可切换/删除 |
| 孵化机制（按使用语言孵化形态） | ❌ | 依赖跨会话使用统计与生成管线，超出本插件范围；可用官方 hatch-pet 生成后导入 |
| `/pet` 管理命令 | 🟡 | DSH 客户端插件没有斜杠命令贡献点；以点击宠物弹出的菜单/设置面板承载同等管理职能 |

## 5. 超出 Codex 的本插件特性

- 🍗 喂食 / 🎾 玩耍交互（经官方 `animations` 覆写在第 9–11 行声明，Codex 包格式兼容）。
- 拖拽换位 + 位置持久化；尺寸 / 透明度 / 动画模式设置。
- 无二进制资产：内置宠物运行时 canvas 生成，`pnpm`/离线均可用。

## 6. 仍值得做的后续项（非官方能力差距，属于打磨）

1. ~~会话切换时的 waving 目前在每次切换都触发~~ —— 已收敛（同一 sessionId 不重复挥手）。
2. 自定义宠物大图集（192×208 网格）按 96px 归一化缩放，超小图集上限 1.5×；如需更大宠物可开放缩放设置。
3. localStorage 自定义宠物上限约 3MB/只（data URL），超大图集需自行压缩为 WebP。
4. 若 DSH 后续暴露斜杠命令或通知贡献点，可补 `/pet` 命令与「完成时系统通知」。
5. ~~eat/play 只是装饰~~ —— 已做成养成数值（饱食/心情随墙钟衰减，喂玩恢复，低值待机冒提示）。