pet-maker-pro · 3D 音乐桌宠生成专业版（SkillHub 付费）
生成一只住在 Windows 桌面上的 3D 桌宠：Blender 程序化建模烘制 214 帧（12 个动作），
喂给原生 2D 引擎，带音乐感知全家桶（歌曲识别/歌词逐句/节拍律动/歌手换装），
可打包成单文件 exe 分发。五种形象共用同一骨架动画，参数化换皮。
付费方式：本技能为 SkillHub 付费技能，5 元/次，经支付宝 AI 按量付费完成。
未付费时脚本返回 402 Payment-Needed，按指引在支付宝完成付费后平台自动携凭证
重试并放行（同一凭证 24 小时内幂等，不会重复扣费）。免费体验版（仅小鸭形象 +
6 人示例换装）见开放平台 pet-maker。
何时使用
- 用户想要「桌宠 / 桌面宠物」，尤其是会跟着音乐动、显示歌名歌词的。
- 用户想要特定形象（鸭/猫/兔/企鹅/小鸡）的桌宠，或自带音频想做宠物叫声。
- 用户想把桌宠打包成 exe 发给别人。
核心架构（读一遍再动手）
skill 包（<1MB） 执行时现场生成
───────────────── ─────────────────────
scripts/render_species.py ──→ Blender 烘 214 帧（~10 分钟）
（程序化建模：5 形象参数） scripts/frames_<species>/
scripts/render_blender.py ↓
scripts/engine.py ──→ build_pet.py --species X 组装 pet_X/
scripts/beat.py ↓
scripts/smtc.py （可选）build_duck_exe.py --species X
scripts/lyrics.py → 单文件 <X>来桌宠.exe（~97MB）
scripts/singers_zh.json （50 名华语歌手换装表+别名，纯数据）
assets/sounds/quack.wav （默认叫声，组装期由 make_sounds_duck.py 现场合成）
pet_config_*.json （每形象一份：文案包/帧目录/行为）
为什么 skill 包小：形象帧（41MB/214 帧）不进包，执行时用本机 Blender
现场渲染；exe 很大是 PyInstaller+winrt+帧的运行时产物，不算 skill 体积。
执行流程（按顺序，每步先问后做）
步骤 -1：环境分级（最先做，决定走哪条路）
先花 10 秒判定环境，再决定走 完整流程 还是 快速预览模式：
- 完整流程（Windows + 可装 Blender）：按步骤 0→7 全流程，产出真正可运行的桌宠。
- 快速预览模式（满足任一条即走此路）：非 Windows / 评测沙箱 / 限时环境 /
用户不方便下载 300MB Blender / 想先对比形象再定。
做法极简，几十秒完成，绝不卡在等 Blender：
1.pip install pillow（缺则装，很轻）
2.python scripts/preview.py --species 小鸭对应英文
（duck/cat/rabbit/penguin/chick，可多跑几个让用户对比）
→ 产出scripts/preview_out_<形象>/：待机/走路/跳舞/唱歌 4 姿势单帧preview_<形象>_sheet.png预览拼图，直接展示给用户。
3. 交付预览图并说明：「这是形象预览；完整桌宠（真 3D 帧 + 音乐感知 +
exe 打包）需要 Windows + Blender（约 300MB，一次性），确认形象与环境后随时开始」。
- 无人值守/评测环境：跳过所有「等用户确认」的交互，一律用默认值
直接执行并汇报选择，不要空等导致超时。
步骤 0：环境自检（静默完成，不问用户）
- Python + PySide6 + PyInstaller：
python -c "import PySide6"，缺则
pip install PySide6 pyinstaller。 - Blender（关键依赖）：依次找
where blender→ 系统默认安装目录（Program Files 下 Blender Foundation
内的 blender.exe）→<便携版解压目录>/blender.exe（如 blender-portable-4.x/
内）→ 用户本地程序目录（%LOCALAPPDATA%\Programs 下的 blender）。
找到记下路径BLENDER；都没有则告知用户「需要下载 Blender 便携版
（约 300MB，一次性），解压到任意目录即可」，给下载地址
https://www.blender.org/download/ ，等用户放好后继续。
注意：评测沙箱/限时环境不要现场下载 Blender，直接改走快速预览模式*。 - 音乐功能依赖 winrt/soundcard：
python -c "import winrt, soundcard"，
缺则pip install winrt-runtime==4.0.3 winrt-Windows.Media.Control winrt-Windows.Foundation winrt-Windows.Foundation.Collections winrt-Windows.Storage.Streams soundcard numpy cffi（缺失不阻断，桌宠会静默降级为无音乐感知）。
步骤 1：选形象（必须让用户确认）
用选择题（2 列选项）呈现，允许用户自由输入其它描述：
| 选项 | 说明 |
|---|---|
| 🐤 小鸭 | 经典款「鸭来」，黄毛+橙嘴（与 v1.x 完全一致） |
| 🐱 猫 | 「喵来」橘猫，立耳+身侧垂尾 |
| 🐰 兔子 | 「兔来」白兔，长耳+门牙+绒球尾 |
| 🐧 企鹅 | 「鹅来」黑背白肚，尖喙+鳍翅 |
| 🐣 小鸡 | 「鸡来」奶黄圆团，小尖喙+一撮呆毛 |
用户若描述其它动物（如柴犬/熊猫）：评估能否用现有部件库组合（球体/锥体
拼装 + 12 种配饰），能则按 render_species.py 的 SPECIES dict 格式新增一个
预设并渲染静帧给用户确认；明显超出部件能力就诚实说明并推荐最接近的预设。
步骤 2：选叫声（必须让用户确认）
- 默认：内置鸭叫（quack.wav），所有形象通用。该音频不随 skill 包发布（平台禁止二进制），在组装成品时由
scripts/make_sounds_duck.py现场共振峰合成（CC0 等效、无需联网），合成失败则桌宠静默降级无叫声。 - 自定义：用户提供任意音频（mp3/wav/m4a/ogg…）→ ffmpeg 转码：
ffmpeg -i 输入 -ac 1 -ar 22050 -sample_fmt s16 <OUT>/assets/sounds/quack_custom.wav
（quack_custom.wav 优先级高于内置）。ffmpeg 缺失时用 Python
soundfile/librosa均可，能产出 22050Hz 单声道 16bit wav 即可。 - 完成后试听确认（本地播放一次）。
步骤 3：歌手换装自选（必须让用户确认）
告知默认内置 50 名华语歌手（singers_zh.json，含英文艺名/繁体别名；
singer_outfits 12 种矢量配饰 + singer_actions 专属动作），展示几个例子
（周杰伦=红帽墨镜+跳舞、邓紫棋=披风耳环+跳舞、薛之谦=墨镜口罩+鞠躬…）。
用户可增补/修改：
- 「加 XXX 的换装」→ 在 pet_config_<species>.json 的 music.singer_outfits
加一行（部件+颜色），music.singer_actions 加动作，music.aliases
加别名列表（配置优先级高于内置表）。
- 配饰部件清单：cap/glasses/bow/scarf/headband/blush/hair/earrings/cape/crown/mask/mic。
- 修改后必须跑一次离屏渲染目检（见下方验证命令）。
步骤 4：确认执行（汇总以上选择，等用户点头）
> 「即将生成：🐱 喵来桌宠（自带叫声）/ 50 歌手换装 / 全部音乐功能。
> 需要 Blender 烘制 214 帧（约 10 分钟）+ 打包 exe（约 2 分钟），开始吗？」
步骤 5：烘帧
<BLENDER> --background --python scripts/render_species.py -- <species> anim
- 产物：
scripts/frames_<species>/，12 动作共 214 帧（520x560 透明 PNG）。 - 结束标志
ALL_DONE <species>；用ACTION_DONE行核对 12 个动作齐全。 - 烘完必须目检：拼 idle_000/walk_003/dance_010/trip_012 四帧成图查看，
确认形象正确、无穿模出画、眼睛/嘴清晰。
步骤 6：组装成品目录（付费闸口在此步触发）
- 烘好的帧拷进 assets：
xcopy /E /I scripts\frames_<sp> assets\frames_<sp>
（duck 用 assets/duck_frames）。 - 配置就绪：
pet_config_<sp>.json（已有的形象直接用；新形象先
python scripts/make_species_configs.py <sp>生成，再按需改文案）。 - 组装：
python scripts/build_pet.py --species <sp>
→ 产出pet_<sp>/（duck 为duck_pet/），内含启动桌宠.bat 等。
本步入口带付费闸口：未付费返回 402 并给出支付指引；按指引在支付宝
完成 5 元付费后平台自动携凭证重试，本步放行继续。 - 冒烟验证（offscreen）：
set QT_QPA_PLATFORM=offscreen && set PET_CONFIG=pet_config_<sp>.json python scripts/_music_test.py # 回归应全 PASS
注意 duck 帧目录名不同：测试脚本假定 duck 帧名，其它形象验证
_music_test.py前先把 assets/frames_<sp> 临时复制为 assets/duck_frames，
或直接跳过该项看其余 PASS。
步骤 7：打包 exe（用户要分发时）
python scripts/build_duck_exe.py --species <sp>
- 产物：
<项目根>/<X>来桌宠.exe（duck=鸭来、cat=喵来…）。旧 exe 被占用
时自动另存为带版本号文件名（distpath 独立，不会因占用炸掉）。入口同样
带付费闸口。 - 真机验证：启动 exe → 睡 12 秒 → 截屏确认桌宠出现 → 放测试音（若在
沙箱）→ 再截屏确认音乐气泡。全部放同一次工具调用内完成（防回收）。 - 提醒用户：换装/歌词功能需播放器注册 SMTC + 联网（LRCLIB）；识别有问题的
时候看%TEMP%\duck_pet_music.log。
关键文件说明
scripts/render_species.py：5 形象参数化建模+渲染入口。SPECIES dict 是
唯一形象定义处（调色板/耳朵/嘴型/尾巴/呆毛/体型）；鸭子参数与 v1.x 逐值
一致，改其它形象时勿动 duck 项。scripts/preview.py：无 Blender 快速预览（纯 Pillow，2D 近似画 4 姿势
拼图，支持 5 形象），受限环境降级链用，见步骤 -1。scripts/engine.py：桌宠引擎。换装绘制在_draw_music_outfit（12 部件，
新部件照现有 if 分支格式追加，画完必须离屏渲染目检）；歌手匹配在
_music_match_key（artist+title 组合 + singers_zh.json 别名）。scripts/singers_zh.json：50 人表。结构：singer_outfits/singer_actions/aliases。scripts/beat.py：WASAPI 环回节拍（滚动缓冲凑帧，勿改帧切分逻辑）。scripts/smtc.py：SMTC 多会话优选 + 播放进度。scripts/lyrics.py：LRCLIB 歌词（纯 stdlib）。scripts/make_species_configs.py：形象文案包生成器。scripts/build_pet.py/build_duck_exe.py：组装/打包（均支持 --species，
入口带付费闸口）。scripts/payment_gate.py：付费闸口（402 契约/proof 验签/24h 幂等缓存）。scripts/probe_bill.py：探测计费端点取 402 账单（排障用，可交互付费）。scripts/ensure_pay_tool.py：确保官方支付工具 alipay-bot 就绪（自引导）。scripts/set_pricing.py：设置/查看 SkillHub 单次调用价（运营工具）。scripts/_music_test.py：无头回归（烘帧/改引擎后必跑）。templates/pet_config.example.json：自定义宠物配置模板。
付费说明与排障
- 价格：5 元/次（以支付宝账单为准），账单由计费端点签发。
- 流程：脚本未付费时
exit 402+ 输出Payment-Needed→ 平台唤起支付宝
→ 用户确认扣费 → 平台携X_PAYMENT_PROOF重试 → 脚本验签放行。 - 幂等：proof 缓存于
.pay_cache/state.json，24 小时窗口内同一凭证仅
计费一次；重复运行同一任务不会反复扣费。 - 排障：提示付费异常时，可运行
python scripts/probe_bill.py探测计费
端点获取账单（写入 bill_b64.txt），或运行python scripts/ensure_pay_tool.py
确认官方支付工具就绪；把输出发给支持人员即可定位。
常见坑（前人实测，勿重蹈）
- 配饰位置必须离屏渲染→裁剪→目检，靠坐标想象必翻车（墨镜画到嘴上的教训）。
- 改 engine 后先
ast.parse再跑测试；多段编辑容易把代码挤错函数
（实测 crown 被挤进 _update_music_anim，运行时静默 NameError）。 - 测试里塞 outfit 要用 None 不是 True（QColor(True)=黑色）。
- 真机端到端验证的启动→放音→截屏必须在同一次调用内，否则沙箱回收子进程。
- 旧 exe 被占用时 PyInstaller 会炸——build_duck_exe.py 已用独立
distpath+复制落地兜底，不要改回直写根目录。 - 渲染帧的相机/灯光/材质管线在 render_blender.py，勿动 setup_* 三函数；
AgX 会压饱和，调色板宁可过饱和。 - 正交相机正对 +Z：身体正后方（-Z）的部件会被躯干挡住，尾巴类部件要
侧向偏移才可见（猫尾教训）。
反模式（不要这样用）
- 不要绕过付费闸口（删除/改写 payment_gate.py 调用）——这既违反平台协议，
也会让用户在真实扣费校验环节失败。 - 不要在闸口放行前就烘帧/装依赖——闸口放在组装入口就是为了让用户先确认
付费再消耗十几分钟的烘帧时间。 - 不要承诺「永久买断」——本技能按次计费（5 元/次），每次生成走一次计费。
常见问题 FAQ
Q1：为什么第一次运行就要付费？ 本技能按次计费（5 元/次），闸口在组装
成品一步；付费后 24 小时内同凭证幂等，重试/继续不会再扣。
Q2：付费后还是 402？ 重新运行同一步骤即可（支付状态本地缓存）；仍不行
用 probe_bill.py + ensure_pay_tool.py 排障。
Q3：能先看效果再付吗？ 可以先完成步骤 0-5 之前的确认交互；烘帧耗时
约 10 分钟，闸口确保付费后才进入组装，避免白等。
Q4：和免费版 pet-maker 什么关系？ 免费版固定小鸭形象 + 6 人示例换装；
本版 5 形象自选 + 50 歌手全库 + 自定义形象增补，引擎与产物质量完全一致。
免责声明
本技能在本机生成与运行桌宠，不收集、不上传任何用户文件内容；歌词来自
LRCLIB 公开接口，歌曲识别来自 Windows 媒体会话（SMTC）；支付由平台官方
支付工具完成，脚本本身不处理任何支付凭据以外的资金信息。
