在使用 Hermes 桌面端时，宠物偶尔会出现“罢工”现象——比如不显示、卡在某个动作上无法切换、气泡文字空白或动画撕裂。遇到这类渲染问题，不必急着重启或重装，先按照这套终端级诊断流程排查，定位到底是配置缺失、服务无响应还是资源加载失败。

检查 Sidecar 服务状态：确保宠物渲染服务正常运行

打开终端，执行：
curl -s http://localhost:7777/health | jq .status

如果返回 【error: command not found】，说明系统中未安装 jq，改用以下命令替代：
curl -s http://localhost:7777/health | grep -q '"status":"ok"' && echo "alive" || echo "dead"

返回 dead 表示 Sidecar 服务未启动。此时不必急着重启应用，先确认进程是否仍在运行：
ps aux | grep sidecar | grep -v grep

如果没有任何输出，说明服务已经崩溃，或者从未被 init 命令拉起。这种情况常见于首次安装后忘记执行 npx petdex init，或手动 kill 过相关进程。

验证宠物资源完整性：检查宠物文件是否加载完整

路径正确后，还要确认文件齐全。

方法一：查看本地宠物目录结构
ls -l ~/.petdex/pets/$(npx petdex select --current 2>/dev/null)

必须存在 【pet.json 和 spritesheet.webp】 两个文件。缺少任何一个，渲染都会直接中断。常见原因是 npx petdex install boba 执行过程中断网，导致 JSON 下载成功但精灵图没有拉取下来。

方法二：直接请求宠物元数据接口
curl -s "http://localhost:7777/pet/current" | jq '.name,.state,.bubble'

如果返回空对象或 404，说明 Petdex CLI 与 Hermes Agent 的状态同步已断开。此时需要重置当前宠物：
npx petdex select → 用方向键选中当前宠物 → 回车确认

强制刷新渲染上下文：彻底解决宠物卡顿或异常显示

资源和服务都正常，但宠物依然表现异常？执行以下强制刷新三步操作。

第一步：清空运行时缓存
rm -f ~/.petdex/runtime/state.json ~/.petdex/runtime/bubble.json

第二步：触发 Sidecar 重载配置
kill -SIGUSR2 $(pgrep -f "sidecar/server.js")

第三步：在 Hermes 桌面端设置中关闭再开启「宠物」开关（路径：设置 → 外观 → 宠物）

注意：SIGUSR2 信号仅对 Node.js 进程有效。如果 pgrep 没有输出，请先执行 npx petdex init 确保 Sidecar 已注册为守护进程。