Imported from FB208/OpenBidKit-plugin-pet (AGENTS.md). Install upstream with npx skills add FB208/OpenBidKit-plugin-pet. Copyright stays with the author.

项目定位

本项目是开源项目 FB208/OpenBidKit_Yibiao 的桌宠插件。

主程序源码位于 D:\CodeSpace\SelfSpace\yibiao-simple，可以只读参考。开发插件功能前，必须阅读根目录的 插件API参考.md 和 插件开发指南.md。

插件不能独立运行。需要运行时，使用项目已有的打包、部署脚本安装到易标主程序；除非用户主动要求，不额外执行测试或校验。

通用开发规范

• 始终使用简体中文沟通、编写说明和注释。
• 开发环境为 Windows。新增脚本必须能在 Windows PowerShell 或项目明确采用的 Windows 运行时中执行，并使用 UTF-8 编码。
• 每个函数添加简短注释说明主要职责，不写重复代码含义的冗长注释。
• 不擅自增加降级、回退、旧数据、旧配置或旧图集兼容逻辑。发现兼容问题时必须先询问用户；未确认时按新结构直接实现。
• 讨论方案时优先使用中文业务含义，必要时再在括号中标注函数名、文件名或变量名。
• 除非任务确实很长且可拆成互不影响的独立工作，不使用子代理。
• 不把候选方案、生成过程和调试材料混入正式运行目录。

当前桌宠图集约定

• 单帧固定为 192×208。
• 图集固定为 8 列；当前经典小易图集为 19 行。
• 待命动作使用 24 帧，占 3 行；其他正式动作当前均使用 16 帧，占 2 行。
• 动作起始行、帧数和速度由 pet.js 中的动画表（ANIMATIONS）定义。
• 图集列数和行数由 skin-registry.js 统一提供。当前所有皮肤共用一套图集尺寸和动作布局。
• 正式运行图集使用支持透明通道的无损 WebP。经典小易运行图集为 assets/pet-spritesheet.webp。
• assets/ 会被打包、部署；artwork/ 只保存维护源，不进入发布包。

添加或修改动作

1. 先明确动作语义、触发条件、是否单次播放、帧数和每帧时长。不得通过改变已有动作语义来偷占现有动作槽位。
2. 生成经典小易的新动作时，必须同时读取：
   • artwork/xiaoyi-final/references/canonical-base.png
   • artwork/xiaoyi-final/pet-spec.json
3. 使用 hatch-pet 或图像生成能力时，每个新动作都必须附带该皮肤的高清角色基准图。只有角色基准图本身允许从纯文字开始生成；动作素材不得脱离基准图生成。
4. 保持角色的脸部、身体比例、材质、配色、标志、道具位置和整体轮廓一致。角色必须完整位于单元格内，不得包含文字、场景、投影、光晕、速度线、灰尘或脱离角色的零散特效。
5. 除安全的左右移动镜像外，不得用其他动作变形或复用出新动作。镜像 running-right 得到 running-left 前，必须确认镜像不会改变标志、道具方向或角色身份；镜像时保持帧时间顺序不变。
6. 8 列图集中，一个动作需要的行数为 向上取整(帧数 ÷ 8)。新增动作后必须：
   • 在所有正式皮肤图集中使用相同起始行和帧布局；
   • 更新 pet.js 的动画定义和实际触发逻辑；
   • 更新 skin-registry.js 的图集总行数；
   • 更新相关图集构建脚本中的总行数、动作顺序和帧数；
   • 更新 README.md 中的动作与触发条件说明。
7. 当前换肤系统不支持某个皮肤缺少动作。新增正式动作时必须同步补齐所有已注册皮肤，不得静默回退到经典皮肤或空白帧。
8. 只修改已有动作画面且帧数、起始行不变时，不改变动作布局；需要改变布局时先说明对全部皮肤的影响。

添加皮肤

1. 皮肤标识使用稳定、唯一的英文短横线格式，例如 classic-xiaoyi。发布后不得随意修改标识。

2. 每个新皮肤必须建立独立维护目录：

   artwork/<skin-id>/
     pet-spec.json
     references/
       canonical-base.png

3. canonical-base.png 必须是用户最终确认的高清角色身份基准图，不得使用从 192×208 成品帧放大的图片替代高清原稿。

   经典小易当前没有“三圆球”造型的独立高清原稿，其 canonical-base.png 是从正式无损 WebP 精确提取的最终帧。不得用头顶凸起的旧版高清图替换；以后如重建高清基准，必须先由用户确认与正式角色一致。

4. pet-spec.json 至少记录角色身份、身体结构、颜色、材质、标志、禁止修改项、色键、单帧尺寸和图集尺寸。

5. 新皮肤必须提供当前全部动作，并与 pet.js 使用完全相同的起始行、帧数和动作含义。不同皮肤不得各自定义不兼容的图集结构。

6. 正式运行资源统一放在：

   assets/skins/<skin-id>/spritesheet.webp
   assets/skins/<skin-id>/preview.png

   经典小易现有的 assets/pet-spritesheet.webp 和 assets/icon.png 保持不变，除非用户明确要求迁移。

7. 在 skin-registry.js 中注册皮肤名称、说明、正式图集和预览图。配置页面直接读取注册表，不为单个皮肤硬编码额外界面逻辑。

8. 皮肤图集必须使用透明背景、无损 WebP，并且只包含最终采用的动作帧。

文件保留规则

以下文件属于长期维护源，禁止在任务清理时删除：

• 正在被代码引用的正式图集、预览图和其他运行资源。
• 每个正式皮肤唯一且与正式角色一致的 canonical-base.png；新增皮肤必须保留高清原稿，经典小易保留当前正式图集精确帧。
• 每个正式皮肤的 pet-spec.json。
• 无法从正式图集反推的唯一手绘原稿、分层源文件或用户提供且后续仍需使用的原始参考图。
• 当前使用的构建、打包、部署脚本，以及运行代码、插件文档和开发规范。

如果正式 WebP 明确以无损方式生成，可以删除从它逐帧拆出的重复 PNG；如果图集改为有损格式，则必须保留无损 PNG 主图或逐帧源文件，不能只留有损成品。

以下文件只需保留到当前生成、修复或用户确认完成：

• 本轮最终入选但尚未合成的动作条带和逐帧文件。
• 联系表、动作预览、检查报告、修复记录和生成任务清单。
• 用于继续修复当前问题的提示词、布局引导图和失败原因记录。

执行完成后的清理规则

成稿被采用且不再需要继续修复后，必须删除：

• 多份可选方案中未被采用的图片及其源图。
• 失败的生成结果、旧版动作条带、被替换的修复版本和重复副本。
• prompts/、重试提示词、imagegen-jobs.json、临时请求文件和生成工具留下的任务记录。
• references/layout-guides/、decoded/、临时拆帧目录和可由正式无损 WebP 重新生成的逐帧 PNG。
• 临时联系表、洋葱皮图、预览 GIF、检查报告和运行摘要；用户明确要求保留审阅记录时除外。
• 与正式 WebP 内容完全相同的重复 WebP，以及可由正式无损 WebP 重建的 spritesheet.png。
• 已为空的生成、原型和临时目录。

清理时遵守以下约束：

• 先确认正式代码和打包清单没有引用目标文件，再删除。
• 多处内容完全相同的角色基准图只保留一份，但不得把唯一高清原稿替换成图集裁切帧。
• pet_request.json 中仍有有效角色信息时，先把必要字段整理进 pet-spec.json，再删除过程请求文件。
• 动作或皮肤仍在修复、等待用户选择时，不执行最终清理。
• 不删除当前正式运行资源、角色基准图、角色规范或不可重建的唯一源文件。

打包与部署

• 本地打包使用 scripts/package.ps1，本地部署使用 scripts/deploy-local.ps1。
• 打包脚本只收集运行代码、assets/ 和 config-ui/；不得把 artwork/、候选方案或过程材料加入发布包。
• 部署会整体替换 %APPDATA%\yibiao-client\plugins\openbidkit-pet，执行前必须确认目标确实是该插件目录。