桌宠资产构建器
把素材变成宿主能加载的桌宠资产。核心是规格驱动：一切从 config/pet-spec.schema.json 派生，每步只做可验证的增量。
不可突破的硬约束
以下五条由宿主代码决定，不可协商、不可扩展、不可绕过：
- 图集固定 1536×1872，8 列 × 9 行，单帧 192×208。 宿主按固定行数切分，第十行不会被播放。
- 每行帧数必须精确等于契约值
[6,8,8,4,5,8,6,6,6]。 多一帧少一帧都是缺陷：第 1/2/5 行少画会闪空（宿主恒播满帧），其余行多画浪费体积（宿主会截断）。 - 契约数组是编译期内联字面量，素材无法影响它。 因此不存在"通过调整素材规避宿主行为"的手段。
- 禁止使用色键抠像。 边缘混合像素会被推向键色补色形成品红边，紫色系角色与键色直接冲突。须用连通背景抠像。
- 不得声称养成层台词已生效。 该字段当前无业务读取方，声明不影响行为。
一、能力分派
先判断用户手里有什么素材，再选能力。跳过这一步直接生图是最常见的失败原因。
| 用户给的 | 能力 | 步骤 |
|---|---|---|
| 一张图 | CAP-01 生成 | 身份母版 → 逐行生成 → 抠像 → 切帧 → 拼装 → 校验 |
| 多帧素材/GIF | CAP-02 转换 | ingest.py 抽帧归一化 → 映射契约 → 校验 |
| 已有图集 | CAP-03 修复 | validate_atlas.py 定位问题行 → 定点重生成 → 复校 |
| 只有文字描述 | CAP-04 构思 | 先出角色设定与色板，用户确认后再进 CAP-01 |
| 要加新动作 | CAP-05 扩行 | 不可行，见「拒绝规则」R-01 |
能力说明
CAP-01 素材生成。 身份母版必须先经用户确认——母版错了九行全错。逐行生成，每行一次生成完整动作序列，禁止把各帧当独立任务。
CAP-02 素材转换。 scripts/ingest.py 负责抠像、抽帧、归一化。GIF 帧数与契约不匹配时的分配规则见 references/asset-pipeline.md。
CAP-03 素材修复。 先跑校验器定位问题行，只重生成问题行，不动其余。
CAP-04 角色构思。 输出角色设定与色板供确认。本阶段不产出图集。
CAP-05 扩行。 不可行，仅做说明。
二、标准流程
前置：python scripts/preflight.py 环境自检，不通过则停止
↓
① 入口路由：判断素材形态，选定能力
↓
② 【阻断点】身份母版确认 —— 用户必须确认，不可跳过
↓
③ 逐行生成，一次一行
每行完成即跑：python scripts/validate_atlas.py <图集> --row-check
↓
④ 抠像与归一化：python scripts/ingest.py
↓
⑤ 拼装图集（8 列 × 9 行）
↓
⑥ 全量校验：python scripts/validate_atlas.py
↓
⑦ 生成清单：python scripts/build_manifest.py
↓
⑧ 投递 + 交付说明（必含 3 条，见下）
阻断点
身份母版确认是全流程最重要的阻断点。 母版错了九行全错，必须在此停下等用户确认。
三、素材优先级
宿主无任务时在 idle / waving / jumping 间每 6.5 秒随机轮播，这三行是用户实际观看的视觉主体。任务态四行由宿主状态驱动，命中即播。
working > waiting > review > failed > idle > jumping > waving
任务态优先于待机态；待机三行同权重（同一轮播池、等概率），不可将 waving 压至末位。
四、抠像规范
禁用色键。 采用连通背景抠像，只去与图像边缘连通的背景，角色内部同色区域必须保留。
# 抠像参数：--background-only 只去连通背景，--feather 边缘羽化，--min-region 去孤立噪点
python scripts/ingest.py --input raw.png --output clean.png --mode cutout
⚠️ 必须用 preflight 确认的解释器。 缺少 scipy 时连通背景能力会静默退化为全局色键——行为改变但退出码仍为 0，自动化管线无法察觉。
五、校验
python scripts/validate_atlas.py assets/spritesheet.webp \
--manifest assets/pet.json \
--json report.json --md report.md
校验器的能力边界
校验器仅逐项报告可测量的客观数值，输出固定含 conclusion_scope: per_check_only。
| 类别 | 项数 | 处理 |
|---|---|---|
| 可机器判定 | 13 | 自动给结论 |
| 可测不判定 | 4 | 只报数值，可接受性人工确认 |
| 不可判定 | 5 | 本工具不作任何结论 |
不可判定项：身份一致性、情绪表达、动作自然度、角色性格契合、宿主可加载性。
⚠️ 身份一致性校验的固有限制：占空比是一维标量，把二维图像压成单个数字，两个视觉上完全不同的角色只要占空比相近指标就相同。发色、瞳色、服装突变时校验器会判通过。 这类问题必须人工盲测。
六、交付说明必备项
每次交付必须包含以下三条，缺一不可：
- 宿主缺陷告知 — 设置页缩略图取契约首个全 1 行，显示拖拽姿态。不影响桌面动画，严重度中低。
- 未验证解码告知 — 素材全过不等于宿主可加载。须在设置面板点刷新列表确认真实解码。
- 校验结论边界 — 机器只判客观数值，身份一致性等需用户肉眼确认。
七、拒绝规则
强拒（宿主做不到）
| 用户诉求 | 回应 |
|---|---|
| 加第 10 行、睡觉、吃东西、跑 | 契约固定九行，第十行不被播放 |
| 多方向朝向、16 方向 look | 契约无朝向行 |
| 桌宠联网对话、云同步、自动更新 | 宿主无网络与模型能力 |
| 番茄钟、心情值、开机自启 | 宿主无定时器与状态存储 |
| 去除水印 | 不做 |
告知后由用户拍板（有代价但可达）
用户要求照内置素材那样做时：内置样本中 3 只帧数不合契约，会导致播放闪空或体积浪费。风格可以照，帧数不能照。
- 第 1/2/5 行缺帧 → 强拒，这三行少画必然闪空，无合理创作意图
- 其余行多画 → 告知并建议，不强拒（宿主会截断，用户看不到多余帧）
若用户仍坚持保留某行缺陷，须在交付说明中写明：「已按要求保留第 X 行缺 N 帧，播放时会出现空白闪烁，这是已知缺陷」。
八、文件索引
| 路径 | 用途 |
|---|---|
config/pet-spec.schema.json |
唯一机器可读事实源，改契约只改这里 |
scripts/preflight.py |
环境自检，含连通背景能力实测 |
scripts/ingest.py |
抠像、抽帧、归一化 |
scripts/validate_atlas.py |
25 项校验 |
scripts/build_manifest.py |
清单生成与字段校验 |
references/contract.md |
契约说明与全部约束 |
references/asset-pipeline.md |
素材处理与分配规则 |
references/art-bible.md |
视觉身份规范 |
references/interaction.md |
三组驱动机制与台词设计 |
references/boundary.md |
完整拒绝规则 |
assets/templates/ |
逐行提示词模板 |
assets/regression/ |
回归素材（自制，非内置样本） |
九、向后兼容
契约版本独立于技能版本，记录在 pet-spec.schema.json 的 contract_version 字段。
宿主若调整契约数组，全部素材逻辑将失效。 每次执行前应比对宿主内置契约与本包内置版本，不一致即告警并要求人工确认。
