equipment-system-workflow

name	equipment-system-workflow
description	FantasyWord 换装功能工作流。用于 EquipmentSystem、装备工作台、FrameData 帧编辑器、Body/Head UV Map、布衣/帽子/护目镜/手套/武器槽、Idle/Walk/Attack 换装错位、运行时截图验收和截图站发布前核验。

Equipment System Workflow（换装功能工作流）

适用范围

• FantasyWord 的 MiniFantasy 换装系统、装备表现资产、帧编辑器配置和运行时换装验收。
• 典型任务：新增或修正装备层、配置角色帧数据、生成 Body/Head UV 图、排查 Idle/Walk/Attack 换装错位、用装备测试场景截图验收。
• 不适用：普通角色动画状态机重构、正式战斗技能逻辑、非 MiniFantasy 素材迁移；这些任务先回到对应 Unity / GAS / 素材 skill。

前提锁定

修改代码、资源、场景或发布截图前，先锁定四项：

1. 问题对象：明确是身体、头部、眼睛、手脚、服装、头部装备、武器槽，还是工作台 UI。
2. 真相来源：优先用正式 CharacterFrameData、装备资产、EquipmentRenderer 运行时输出和 Unity PlayMode 截图；离线合成图只能作辅助证据。
3. 目标入口/环境：默认装备验收入口是 Assets/Scenes/EquipmentSystemDemo.unity 的 EquipmentSystemDemoCharacter。移动/实战场景只在用户明确要求时作为补充入口。
4. 验收口径：写清动作、方向、帧、装备组合、是否允许基础动画自带武器，以及是否需要上传截图站。

任一项没锁定时，只能继续定位或补证据，不得先改。

关键真相源

• 帧数据：Assets/GameData/EquipmentSystem/FrameData/人类帧数据.asset
• 生成 UV：Assets/GameData/EquipmentSystem/GeneratedUV/Human/*_BodyUV.png、*_HeadUV.png
• 工作台目录：Assets/GameData/EquipmentSystem/Data/Workbench/换装工作台目录.asset
• 默认外观：Assets/GameData/EquipmentSystem/Appearance/基础人形外观.asset
• 装备资产：Assets/GameData/EquipmentSystem/Equip/Visual/*.asset
• 运行时渲染：Assets/Scripts/Presentation/EquipmentSystem/Runtime/EquipmentRenderer.cs
• 类型配置：Assets/Scripts/Presentation/EquipmentSystem/Data/Appearance/EquipTypeConfig.cs
• Shader：Assets/Scripts/Presentation/EquipmentSystem/Shaders/EquipmentUV.shader
• 装备测试场景：Assets/Scenes/EquipmentSystemDemo.unity

层级含义

现实对象	配置/代码含义	渲染来源
服装、裤子、披风、背包	身体/躯干装备层	Body UV Map + 装备 Sprite
头盔、帽子、面罩、护目镜	头部装备层	Head UV Map + 装备 Sprite
手套	左右手颜色替换	帧数据里的手部蒙版 + Color 装备
鞋子	左右脚颜色替换	帧数据里的脚部蒙版 + Color 装备
眼睛、眼部装饰	角色外观层	帧数据眼睛蒙版 + CharacterAppearance
武器、盾牌	独立武器槽	武器锚点和武器序列，不属于 Body/Head UV

帧编辑器与 UV 流程

1. 先锁定动作和方向，例如 Idle、Walk、Attack，以及 SE/SW/NE/NW。
2. 在帧编辑器中按现实部位涂色：头部、身体、左右手、左右脚、左右眼。
3. 对头部和身体执行扩展，让装备层覆盖需要跟随动作的像素区域。
4. 设置或核对眼睛和手的位置；眼睛只在正面方向显示，背面方向不显示不是失败。
5. 生成对应动作的 BodyUV 和 HeadUV，保留 .meta 和 GUID，不新建替代资源顶包。
6. 资源层检查通过后，再进 Unity PlayMode 做端到端截图；不要用 UV 预览图或离线合成图替代最终验收。

Attack 特例

• Attack 基础动画可能自带武器像素；这不是装备武器。
• 排查 Attack 的服装、帽子、眼睛、手套错位时，不装备武器/盾牌，不修改 长矛.asset、战斧.asset 等武器资产。
• 只有用户明确说“武器装备位置错误”时，才进入武器槽、锚点和武器序列排查。
• 截图前必须确认实际 Sprite 是 Attack，例如 Minifantasy_CreaturesHumanAttack_*；requestedAnimation=Attack 但 Sprite 仍是 Idle 时，不能当作 Attack 端到端证据。
• 选择 Attack 验收帧时，优先选能同时看到身体、头部和至少前向手部的帧；挥击幅度大的帧可作为补充，不一定适合检查手套。

运行时验收

1. 用 EquipmentSystemDemo 或用户指定的装备测试入口，不要默认拿当前 PlayMode 场景当目标。
2. 通过真实 EquipmentRenderer + EquipmentUV.shader 渲染，不用离线像素合成冒充。
3. 使用工作台控制器或等价正式组件设置角色、动作、方向和装备。
4. 非武器层验收时显式保持 Weapon / Shield 槽为空；记录主手/副手装备槽状态。
5. 至少覆盖代表性 Idle 与 Attack；方向问题要覆盖 SE/SW/NE/NW。
6. 记录每张截图的场景、动作、方向、Sprite 名、装备槽数量、武器槽是否为空。
7. 截图不得黑屏、裁边、加载中或来自错误场景。

图片核验与发布

• 读取本地截图前先使用 .codex/skills/safe-image-reading/SKILL.md 的预算门禁。
• 端到端证据放在 test-results/evidence-image-validation/<e2e-id>/，同时保留原始截图和轻量总览图。
• AI 图面核验只读轻量总览或关键裁图，不反复读取原 atlas 或大图。
• 用户要求上传服务器时，先使用 artifact-preview-publisher；只发布已经核验通过的最终图。
• 候选图、失败图、离线合成图、黑图和错误场景截图不得发布为 passed。

禁止行为

• 不得把离线合成图、UV 预览图或辅助标注图说成端到端证据。
• 不得因为 Attack 画面里有武器，就默认修改武器装备资产。
• 不得把当前打开场景、旧截图或上一次 PlayMode 状态当作本轮目标入口。
• 不得覆盖正确装备资产、场景或 .meta；资源错误需要撤回时只做最小手工修正，不用 git 回滚。
• 不得写 fallback 0、占位图或临时 Sprite 到正式装备链路冒充修复。
• 不得声称“修好”或“通过”，除非已有新鲜 PlayMode 运行时截图或等价真实证据。

完成前检查

• 问题对象、真相来源、目标入口、验收口径都已写清。
• 相关资源 diff 只包含本轮目标文件；武器资产没有无关差异。
• Attack 验收图的实际 Sprite 名是 Attack。
• Weapon / Shield 槽状态符合本轮目标。
• 身体、头部、眼睛、手脚的表现结论来自真实运行时截图。
• 如果上传截图站，公开详情页、API、图片 URL 和文件 hash 均已核验。