sprite-gen

精灵图生成

生成入口：制作精灵图、制作图像，或将静态图动画化为视频。现有的生成、提取和导出工具负责执行操作；用户选择结果和提供方。若要重复背景、投射阴影、检查动作或合成场景，请直接使用下方独立的路线处理现有素材。

从这里开始处理每个生成请求

若要生成独立视频片段，请阅读 video 并使用 sprite-gen video。 这条路线适用于任何 Agent 引擎，并会交付经过验证的 MP4 和报告。 对于精灵图或普通图像，请使用下方指南。

阅读 user-workflow，然后运行相应的只读指南：

$SPRITE_GEN_ROOT/.venv/bin/sprite-gen workflow --kind sprite
$SPRITE_GEN_ROOT/.venv/bin/sprite-gen workflow --kind image

传入请求中已明确说明的选项。指南会检查访问权限，将明确指定的选项与已保存的默认值合并，并仅返回尚缺的问题。遵循指南的开始和结束阶段。务必将已确定的提供方显式传递给生成工具。交付检查通过的文件后，再提供整理视图；只有在用户同意时才保存默认值。完整的对话和设置约定由链接文档负责，不在各个流水线文档中重复。

侧视图朝向

确保侧视图静态图、画布布局和动作提示词朝向一致。 video-set 会在画布布局前各检查一次每个侧视图输入，并将请求的 --facing 同时用于画布和片段提示词。默认只记录观察结果； 绝不会更改请求的方向。图像校正需要明确选择启用。

命令选项	值和默认值	行为
gen --facing	preserve（默认）、right、left	使用 --ref 时，显式指定方向会增加提示词要求，并检查生成的静态图。
gen --facing-fix	none（默认）、mirror、regen	记录观察结果，不进行校正；可选择启用镜像处理观测到的相反朝向，或重新生成一次并复查。若重新生成的静态图仍朝向相反，则会进行镜像处理。
video --direction	side、front、back、front_diagonal、back_diagonal；默认未设置	side 会启用朝向检查并添加匹配的提示词要求；其他值会跳过检查。两个斜向视图均为向右转的四分之三视图（VIEW_TEXT）；在其中行走或奔跑时，拍摄画面会固定在最后一帧（pins_last_frame）。
video --facing、video-set --facing	right（默认）、left	必需的侧视方向。
video --facing-fix、video-set --facing-fix	none（默认）、mirror	记录观察结果；可选择在副本中镜像处理观测到的相反朝向。默认启用批量侧视图检查。

生成和动作提示词会请求指定方向，但无法保证模型遵从。 即使置信度很高，检测器也可能出错：选择 mirror 或 regen 前，请先检查静态图。 生成报告会在 extra.facing 中记录方向、模型、请求的方向、模型报告的置信度和校正信息；视频报告及批次条目则使用 facing。final_direction 是观察结果或基于观察结果得出的值，并非独立验证；final_direction_source 用于标明其来源。若检查结果不确定或失败，系统会记录 unknown 及原因，并继续处理而不进行校正；正面朝向的观察结果也会保持不变。镜像处理无法保留左右配饰的佩戴方向。

执行路线

任务	入口	规范
GPT 图像精灵	prepare, gen-set --provider codex, extract、合成和 QA	atlas-workflow
独立视频 / 为静止图像添加动画、固定最后一帧、参考图像	video（--image、--last-frame、--reference）	video
续接或编辑现有片段	video-extend, video-edit	video
Grok 视频精灵	video-set	video-pipeline
普通图像生成或编辑	gen --provider codex 或 gen --provider grok（订阅路线）	gen
无法登录时进行图像生成（服务器、容器、SaaS）	gen --provider openai — 使用 OPENAI_API_KEY 的服务器 / SaaS 路线，按次计费，绝不会作为默认路线或回退路线	gen
基础锚点和方向锚点	anchor	directional-anchor-workflow
筛选视图或现有图像候选项	curation, unpack-atlas --pngs-dir	curation
统一背景移除或导入图集	cutout, slice-sheet	sheet-slicing
调色板替换	sprite-gen recolor-palette, sprite-gen recolor	recolor
骨架图层合成	sprite-gen compose-layers	layer-tracks
待机呼吸效果	筛选选项，由合成步骤烘焙	breathing
引擎导出	export-aseprite, export-pngs	engine-export
背景方案或重复平铺图块	使用现有的 gen / cutout，然后可选用 background-tile	asset-tools
独立投影	shadow	asset-tools
重复姿势、足部接触和步幅测量	inspect-motion	asset-tools
可选的场景布置、灯光、摄像机和渲染	scene-render, scene-inspect	scene
默认设置	defaults show, defaults save, defaults clear	user-workflow

背景移除、提取、对齐和导出应使用现有的自动化流水线阶段。不要让用户逐个选择脚本。对于直接的工具请求，运行对应工具即可；不需要询问无关的生成问题。图像精灵应保留逐行流水线和组件提取流程。一次性网格生成和固定单元格裁切并非替代精灵生成的路线。

对于攻击循环覆盖率、观察到的一次性返回结果和结构化循环失败报告，请遵循 video-pipeline。

场景创建使用已完成的素材，且为可选步骤。素材元数据负责帧、原生时长和锚点；场景规范负责位置、缩放、播放速率、平面、摄像机和灯光。只有在明确声明同一只脚接触地面且脚部 ROI 独立隔离时，才能测量步幅；接触状态未知时，应标记为未验证。仅应用针对所选确切素材且具有明确场景方向的已验证报告。绝不要根据最底部的轮廓推断行走方向、反转帧，或更改源素材来让场景正常运行。

执行解释器

SPRITE_GEN_ROOT 是已安装仓库的绝对路径。使用 $SPRITE_GEN_ROOT/.venv/bin/sprite-gen 或 $SPRITE_GEN_ROOT/.venv/bin/python；不要假设 shell 已激活。禁止回退：创建缺失的 venv 或报告故障，绝不要使用任意全局 Python。缺少 NumPy 的解释器会在导入软件包时失败。设置和诊断请参阅：解释器。

用于行走和跑步循环的 RIFE

video-loop 使用 RIFE 中间帧修复行走或跑步循环中的跳跃帧，video-set 则为一个方向组设置一个循环长度。每台机器只需安装一次：$SPRITE_GEN_ROOT/.venv/bin/sprite-gen rife install（将固定版本的 rife-ncnn-vulkan 20221029 和模型 rife-v4.6 安装到用户数据目录，并通过 SHA-256 校验，最后生成一帧检查帧；没有 GPU 的 Linux 系统需要先安装 libvulkan1 mesa-vulkan-drivers）。如果未安装，所有循环仍会按拍摄原样剪切，并会注明这一点：在标准错误输出中显示一行 warning:，循环报告中显示 jump_repair.applied: false，set.report.json 中显示 cycle_align.<state>.applied: false 和 warnings。发生这种情况时，请告知用户哪些循环未修复，并提供安装选项；安装后，重新剪切这些循环并运行 video-cycle-align。如果未安装 RIFE，video-loop --repair on 和 video-cycle-align 会直接失败。循环修复。

合约与高级工具

运行合约负责数值请求、运行布局、原子发布和精选导出。架构说明了领域所有权。文档索引列出了所有专门功能和 QA 流程。sprite-gen --help 根据软件包目录生成命令映射。在将结果作为流水线输出呈现时，绝不要用临时裁剪脚本替代规范提取。