游戏 UI 雪碧图拆分与 PNG 打包
把组件拆解阶段生成的整张雪碧图进一步切成独立透明 PNG，并打包成可下载 ZIP。不要把“生成组件清单”误当成“已经完成像素级切图”。
前置条件
读取：
- 已批准的组件拆解结果
contracts/style-contract.yamlcontracts/component-contract.yamlcontracts/asset-manifest.yamlcontracts/sprite-contract.yaml（存在时）
输入雪碧图必须是实际存在的图片文件。若只有提示词或组件列表，先完成组件图生成。
最终单元素 PNG 必须去掉全部文字，包括标题、按钮文案、数字标签、占位文字、水印和说明编号。文字不是组件图形的一部分。
适用输入
- 透明背景雪碧图：优先按 Alpha 通道识别。
- 纯色或近似纯色背景：采样四周背景色并移除。
- 同一张图上的按钮、图标、卡片、装饰、特效和角色。
不适合：
- 元素互相遮挡或粘连严重的完整 UI 页面。
- 带复杂场景背景且元素没有间隔的合成图。
- 需要恢复被遮挡像素的素材。
遇到这些情况，应重新生成留有间距的组件雪碧图，而不是强行切割。
输入雪碧图规范
组件生图时优先要求：
- 所有元素完整、互不接触、四周留白。
- 统一纯色背景或透明背景。
- 不要文字、编号、水印和说明线。
- 阴影不要跨越到相邻组件。
- 相似状态按固定顺序排列，但不绘制网格线。
- 不要把一个组件拆散成多个远离的碎片。
自动拆分
执行：
bashpython3 scripts/split_sprite_sheet.py <source.png> \ --output-dir <project>/assets/sprites/<pack-id>/items \ --zip <project>/packages/<pack-id>-png.zip \ --mode auto \ --prefix <pack-id>
默认行为：
- 输入有透明通道时按 Alpha 检测。
- 输入不透明时采样边缘背景色。
- 合并距离较近的像素区域。
- 过滤过小噪点。
- 每个元素增加安全边距。
- 导出独立透明 PNG。
- 生成
sprite-manifest.yaml。 - 生成包含 manifest 和全部 PNG 的 ZIP。
语义 mapping
自动序号不能作为最终资产名。准备按检测顺序排列的 YAML：
yamlitems: - semantic_name: shop-buy-button-normal component_id: shop-buy-button category: button state: normal slice: {type: 9-slice, margins: [36, 36, 28, 28]}
执行时增加：
bash--mapping mappings/shop-components.yaml
工具会用 semantic_name 作为 PNG 文件名，并把组件 ID、分类、状态与 slice 写入 manifest。命名和切图方式分别遵循组件技能的语义命名规范与切图规则。
自动切割不会自动识别或修复文字。源雪碧图仍有文字时，先执行以下任一操作，再开始切割：
- 优先重新生成无文字雪碧图。
- 无法重生时，对文字区域做蒙版修复或内容填充，补回底板纹理。
- 修复后重新检查，不能只把文字裁掉而留下透明洞、色块或残影。
不得把含文字的切片标记为批准。
参数调整
元素被拆得太碎：
bash--connect-gap 6
多个元素被粘成一张：
bash--connect-gap 0
背景残留：
bash--mode background --background-tolerance 16
浅色组件被误删：
bash--background-tolerance 8
小图标被过滤：
bash--min-area 16
需要更多裁切留白：
bash--padding 8
重新输出时显式使用 --force，不得静默覆盖已批准包。
项目契约
将结果写入 contracts/sprite-contract.yaml：
- 源雪碧图与源页面
- 检测模式和阈值
- 输出目录和 ZIP 路径
- 单元素 ID、路径、原图坐标、尺寸和透明状态
- 人工检查状态
在 asset-manifest.yaml 至少登记：
- 原始雪碧图：
kind: sprite-sheet - 最终压缩包：
kind: package
单元素明细由 sprite-contract.yaml 管理，避免大型组件包让全局 manifest 失控。
人工验收
自动切图后逐项检查：
- 每个文件只包含一个完整元素。
- 元素没有被裁断。
- 相邻元素没有粘连。
- 阴影、发光和半透明边缘完整。
- 背景已透明，无白边、色边和脏点。
- 不含标题、按钮文案、数字标签、水印或文字残影。
- 文件名、坐标和尺寸与 manifest 一致。
- ZIP 可以解压，包含全部 PNG 和 manifest。
误切时先调整阈值重新生成；仍无法解决时，在 sprite-contract.yaml 记录人工裁切框，不要把错误结果标记为批准。
文件命名
text<pack-id>-001.png <pack-id>-002.png <pack-id>-003.png ... <pack-id>-png.zip
确定组件语义后可重命名为：
textbutton-primary-default.png nav-home-selected.png currency-gold.png effect-crescent-glow.png
重命名后同步更新 manifest，不能只改文件名。
完成定义
- 原始雪碧图可追踪
- 每个元素是独立透明 PNG
- 自动坐标和实际尺寸已记录
- 人工验收通过
review.text_free: true- ZIP 包存在且可解压
- 最终 PNG 使用语义名称并关联 component ID
- 项目严格校验通过
quickstart.md记录解压和使用方式
需要继续生成 Atlas 和引擎 JSON 时，调用 game-ui-asset-pipeline。
