Hatch Pet Q版卡通桌面宠物生成器
下载地址
https://www.zhengdianxue.com/wp-content/uploads/skills/user_90a020b6--erdong-hatch-pet.zip将提示词发送给你的 AI 安装该 skills
请根据 https://skillhub.cn/install/skillhub.md,安装 @user_90a020b6/erdong-hatch-pet。Q版卡通桌面宠物生成器。精灵图生成 + tkinter 桌面渲染,支持跟随/观察模式。
阅读全文 (展开查看完整说明)
概述
Hatch Pet – Q版卡通桌面宠物生成器 🐱
一键将人物参考图转化为桌面宠物的完整工具链。
特性
- 🎨 Q版卡通风格,保留人物核心特征
- 🎬 9 个动画状态:idle / running / waving / jumping / failed / waiting / working / review
- 👀 16 方向注视:360° 全方位注视方向
- 📐 标准精灵图:8列×11行, 1536×2288 像素, 单格 192×208
- 🖥️ 桌面显示:
desktop命令在桌面显示动画宠物(tkinter 跨平台) - 🤖 AI Agent 状态监听:实时感知 Reasonix/灵识 等 AI agent 的工具调用状态,自动切换宠物动画并弹气泡消息(文件桥接模式,
--watch) - ✅ 内置校验:validate_atlas.py 严格校验所有规格
- 📦 一键打包:输出 pet.json + spritesheet.webp + zip
快速开始(开箱即用)
本 Skill 已内置完整可运行代码,无需再去别处 clone。装好依赖即可直接跑。
# 1) 安装依赖(仅需 Pillow;托盘图标可选装 pystray)
pip install Pillow
# 可选:系统托盘支持
pip install pystray
# 2) 生成一只占位宠物(无需参考图,先验证整条管线)
python -m hatch_pet generate --name "MyCat" --output ./my-pet/
# 3) 在桌面显示(需要图形界面;无头服务器不行)
python -m hatch_pet desktop --spritesheet ./my-pet/spritesheet.webp --config ./my-pet/pet.json效果预期
SkillHub 不支持 GIF/视频文件上传,所以这里用文字描述运行效果。 想直接看官方猫咪演示动图,见上游仓库:
https://cnb.cool/edrc.shawn/DesktopBuddy→assets/cat/
启动后你会在桌面上看到:
┌────────────────────┐
│ │
│ 🐱 一只卡通宠物 │ ← 无边框透明窗口,始终置顶
│ 在桌面自由活动 │
│ │
│ ╭──────────────╮ │
│ │ 工作中… ✨ │ │ ← 气泡消息(随 AI 状态自动弹出)
│ ╰──────────────╯ │
└────────────────────┘典型交互体验:
| 你的操作 | 宠物反应 |
|---|---|
| 鼠标靠近宠物 | 眼睛跟着鼠标转(16 方向注视) |
| 开启跟随模式 | 宠物追着鼠标跑 |
| AI 开始搜索文件 | 气泡弹出"工作中…",宠物切换敲键盘动画 |
| AI 任务完成 | 宠物庆祝挥手,气泡"搞定了!" |
| 左键拖拽 | 拎起宠物放到任意位置 |
| 右键点击 | 弹出弧形功能菜单(跟随/活动/隐藏/退出) |
| 双击 | 隐藏到系统托盘 |
运行 generate 后的输出:
📁 my-pet/
├── spritesheet.webp ← 精灵图(8列×11行, 1536×2288)
├── pet.json ← 配置文件
└── MyCat-hatch-pet.zip ← 打包文件能力边界:能做什么、不能做什么
✅ 能做的
- 在 Windows / macOS / Linux 桌面显示透明无边框动画宠物
- 支持 9 种动画状态 + 16 方向注视
- AI Agent 状态联动(自动切换动画+气泡)
- 生成标准精灵图(8列×11行, 1536×2288)
- 鼠标交互:拖拽/跟随/观察/右键菜单
⚠️ 需要条件的
- 照片转 Q 版宠物:需要 AI API(
--ai+--api-key),生成效果取决于 API 模型质量 - 最佳参考图:正面、半身、背景干净、光线均匀的照片效果最好;侧脸、全身、背景杂乱的照片可能识别不准
- 桌面显示:必须有图形桌面环境(无头服务器/SSH 不行);需要 Python tkinter(Windows/macOS 自带,Linux 需
apt install python3-tk)
❌ 不能做的
- 不负责 AI 生图——参考图需自己准备或使用内置占位帧
- 不保证照片转 Q 版的 100% 还原——AI 生成有随机性
- 不同桌面宠物框架可能有不同规格,需自行适配
- 不联网——所有操作本地完成(AI 生图除外)
- 不替代专业动画工具——适合快速原型,精细动画需专业工具
使用场景 / 如何触发
| 你想要的 | 用哪个命令 |
|---|---|
| 先跑通管线、不想准备图 | generate(占位帧) |
| 用自己的角色图生成 Q 版宠物 | qpet --image 图.png |
| 在桌面看动画宠物 | desktop --spritesheet … --config … |
| 让宠物跟着 AI agent 状态变 | desktop … --watch |
| 已有逐帧图片要拼精灵图 | build --frames-dir … |
| 校验精灵图规格 | validate --image … --config … |
代码已内置(上游同步)
完整 Python 包 hatch_pet/、校验脚本 validate_atlas.py、依赖声明 pyproject.toml / requirements.txt、演示素材 assets/ 均已随本 Skill 一起发布,开箱即用。
上游源码(用于同步更新 / 提交 Issue):https://cnb.cool/edrc.shawn/DesktopBuddy
# 如需以可编辑模式安装(提供 hatch-pet 命令),在 skill 目录下:
pip install -e .也可直接用
python -m hatch_pet …(从本 skill 目录运行),无需 pip install。
精灵图规格
| 参数 | 值 |
|---|---|
| 列数 × 行数 | 8 × 11 |
| 单格尺寸 | 192 × 208 px |
| 总尺寸 | 1536 × 2288 px |
| 格式 | WebP (RGBA, 透明背景) |
| 动画行 | 9 行(idle, running-right, running-left, waving, jumping, failed, waiting, running, review) |
| 注视行 | 2 行(16 方向) |
安装
# 从源码安装
git clone https://cnb.cool/edrc.shawn/DesktopBuddy
cd DesktopBuddy
pip install -e .用法
一键生成桌面宠物
# 生成桌面宠物(含占位帧,适合测试管线)
python -m hatch_pet generate --name "MyCat" --output ./my-pet/
# 使用参考图(需要 AI 生图支持)
python -m hatch_pet generate --ref reference.png --name "MyCat" --output ./my-pet/桌面显示
# 在桌面显示动画宠物(tkinter 窗口,无边框置顶)
python -m hatch_pet desktop --spritesheet ./my-pet/spritesheet.webp --config ./my-pet/pet.json
# 在桌面显示 + AI Agent 状态监听(文件桥接模式)
python -m hatch_pet desktop --spritesheet ./my-pet/spritesheet.webp --config ./my-pet/pet.json --watch
# 指定自定义状态文件路径
python -m hatch_pet desktop --spritesheet ./my-pet/spritesheet.webp --config ./my-pet/pet.json --watch --status-path "C:/path/to/status.json"桌面宠物功能:
- 🎯 跟随模式 — 宠物跟着鼠标跑,方向随鼠标切换(右键菜单开启)
- 👀 观察模式 — 目光跟着鼠标转,16 方向注视(右键菜单开启)
- 🤖 AI Agent 状态监听 — 自动感知 agent 状态切换动画(
--watch开启)- 思考中 →
waiting(歪头思考) - 工作中 →
running(敲键盘忙碌) - 审阅中 →
review(审阅状态) - 完成 →
waving庆祝后回idle - 出错 →
failed后回idle - 空闲 →
idle(待机)
- 思考中 →
- 左键拖拽移动
- 右键菜单切换动画状态(idle / waving / jumping 等)
- 双击退出
AI Agent 状态联动
桌面宠物内置 StatusWatcher,通过轮询一个 JSON 状态文件感知 AI agent 的活动。
状态文件格式 (~/.hatch-pet/status.json):
{
"state": "working",
"tool": "grep",
"msg": "正在搜索文件…",
"timestamp": "2026-07-28T15:30:00"
}AI agent 侧(灵识/Reasonix)只需在每次工具调用前后写入此文件即可:
import json, time, os
os.makedirs(os.path.expanduser("~/.hatch-pet"), exist_ok=True)
# 工具调用前
with open(os.path.expanduser("~/.hatch-pet/status.json"), "w") as f:
json.dump({"state": "working", "tool": "grep", "msg": "搜索中…", "timestamp": time.strftime("%Y-%m-%dT%H:%M:%S")}, f)
# 工具完成后
with open(os.path.expanduser("~/.hatch-pet/status.json"), "w") as f:
json.dump({"state": "done", "tool": null, "msg": "搜索完成", "timestamp": time.strftime("%Y-%m-%dT%H:%M:%S")}, f)状态映射表:
| agent 状态 | 动画 | 说明 |
|---|---|---|
idle | idle | 待机 |
thinking | waiting | 思考中 |
working | running | 工作中 |
reviewing | review | 审阅中 |
done | waving → idle | 完成(2s 庆祝后回落) |
error | failed → idle | 出错(3s 后回落) |
waiting | waiting | 等待授权 |
talking | idle | 回应中 |
从帧图片构建
python -m hatch_pet build --frames-dir ./frames/ --output ./output/校验
python -m hatch_pet validate --image output/spritesheet.webp --config output/pet.json输出文件
pet.json— 宠物配置文件spritesheet.webp— 精灵图(8列×11行){name}-hatch-pet.zip— 打包文件
项目结构
DesktopBuddy/
├── hatch_pet/ # 核心包
│ ├── __init__.py
│ ├── __main__.py # CLI 主入口
│ ├── config.py # 配置常量
│ ├── pet_config.py # pet.json 生成
│ ├── sprite_builder.py # 精灵图拼接
│ ├── frame_generator.py # 占位帧生成
│ ├── status_watcher.py # AI Agent 状态监听(文件桥接模式)
│ └── desktop_renderer.py # 桌面宠物渲染器(tkinter)
├── validate_atlas.py # 精灵图校验工具
├── pyproject.toml # 项目配置
├── requirements.txt # 依赖
└── README.md依赖
- Python 3.8+
- Pillow(pip install Pillow)
🚫 常见错误与反模式
| 错误做法 | 为什么有问题 | 正确做法 |
|---|---|---|
跳过 generate,直接用 desktop 但没提供精灵图 | desktop 需要精灵图和配置文件才能显示 | 先 generate 生成精灵图,再 desktop 显示 |
在无头服务器/SSH 上跑 desktop | 没有图形界面,tkinter 无法创建窗口 | 只在有显示器的桌面环境运行 desktop |
以为 qpet 能直接生成高质量 Q 版 | 不传 --ai 时只做简单的图像缩放+风格滤镜 | 想要高质量 Q 版效果,加 --ai 并提供 API Key |
照片背景杂乱、光线暗就拿来 qpet | AI 识别不准,生成结果可能变形 | 用正面、半身、背景干净、光线均匀的照片 |
| 不看输出日志,精灵图生成了但不知道下一步 | 日志里写得很清楚:下一步: python -m hatch_pet desktop … | 生成完后看终端最后两行 |
| 把精灵图放大缩小后直接用 | 精灵图是固定 1536×2288 的精确裁剪,缩放会破坏坐标 | 用 --scale 参数调整显示大小,不改原图 |
--watch 启动了但宠物一动不动 | AI 还没写状态文件,或路径不对 | 先确认 ~/.hatch-pet/status.json 存在且有内容 |
| 多台电脑想同步精灵图用 Git | 精灵图是 1-3MB 的二进制文件,Git 不适合 | 用网盘/U 盘复制,或在每台电脑上用 generate 重生成 |
常见问题(FAQ)
Q:只有说明文档,没有代码?A:不会。本 Skill 已内置完整可运行代码(hatch_pet/ 包 + validate_atlas.py + assets/),pip install Pillow 后直接 python -m hatch_pet … 即可。上游仓库 DesktopBuddy 仅用于同步更新。
Q:需要什么环境?A:Python 3.8+ + Pillow(pip install Pillow)。桌面显示需要图形界面(Windows/macOS 均可)。
Q:没有参考图怎么办?A:generate 命令不带 --ref 参数时自动生成占位帧,适合先测试管线。
Q:桌面宠物显示不出来?A:确保有显示器(无头服务器不行),且 Python 安装了 tkinter(Windows/macOS 自带)。
Q:pip install 报错怎么办?A:先确保 Python 3.8+ 已安装,然后单独装 Pillow:pip install Pillow。
Q:如何让宠物更生动?A:用 AI 生图工具(如 Agnes / Midjourney)生成各帧图片,放入 frames/ 目录后用 build 命令构建精灵图。
Q:支持 macOS 吗?A:支持。tkinter 在 macOS 上工作正常,透明窗口和置顶可用。
Q:精灵图规格能改吗?A:可以,修改 hatch_pet/config.py 中的 CELL_WIDTH/CELL_HEIGHT 等参数,但需同步修改 pet.json 配置。
Q:AI Agent 状态监听怎么用?A:启动时加 --watch 参数即可。宠物会轮询 ~/.hatch-pet/status.json 文件,AI agent 每次工具调用前后写入该文件,宠物自动切换动画和弹气泡。详见 [AI Agent 状态联动](#ai-agent-状态联动)。
Q:支持哪些 AI agent?A:任何能写入 JSON 文件的 agent 都可以——Reasonix、灵识、WorkBuddy、Claude Code 等。只需在工具调用前后把状态写进 ~/.hatch-pet/status.json。
Q:版本号到底是多少?为什么 SKILL.md 和代码里写的不一样?A:现在统一为 v2.5.0(本次修复)。之前 SKILL.md 的版本号(文档迭代)和 Python 包的版本号(代码发布)独立维护,导致不一致。从 2.5.0 起所有文件统一版本。
Q:宠物启动了但窗口一闪就没了?A:通常是精灵图路径不对或文件不存在。检查:① spritesheet.webp 和 pet.json 是否在指定路径下;② 用 python -m hatch_pet validate --image ... --config ... 校验;③ 看终端输出的错误信息。
Q:运行时提示"No module named 'PIL'"?A:Pillow 没装。执行 pip install Pillow。
Q:照片转 Q 版效果很差怎么办?A:① 换一张正面、半身、背景干净的照片;② 尝试不同风格(chibi_classic/chibi_cute/chibi_pixel 等);③ 加 --ai 参数使用 AI 增强(需要 API Key);④ Q 版转换本质是创意工具不是精确还原工具,接受一定随机性。
Q:宠物占了太多 CPU?A:主循环 ~60fps,正常占用 2-5% CPU。如果偏高:关掉 --random(随机行为会持续计算路径);确认没有多个宠物实例在同时运行。
Q:启动后桌面出现"magenta"(品红色)色块?A:正常现象——magenta 是透明色标记,用于实现无边框透明窗口。宠物以外的区域都是透明的,你应该只看到宠物本身。如果整个窗口都是 magenta,说明精灵图加载失败。
不做什么
- 不负责 AI 生图 — 参考图需用户自己准备(可用 Stable Diffusion / Midjourney 等生成)
- 不管理宠物安装 — 只生成精灵图和配置文件,不负责安装到桌面宠物框架
- 不保证 100% 适配 — 不同桌面宠物框架可能有不同规格,需自行适配
- 不联网 — 所有操作本地完成,无需网络
- 不替代专业动画工具 — 适合快速原型和测试,精细动画需专业工具