用途
video2dsprite 用于把一张已获用户确认的角色主图（master still）扩展成该角色的整套动画精灵图。主图确定身份与几何，视频模型提供运动，确定性工具负责把它整理成引擎可用的资源。资料明确说明：视频并不承诺比序列图更小、更无缝或更便宜。
适用场景：为角色或生物做动画，每个动作都来自同一张已确认主图，一个动作一段片段；从已接受的主图获得流畅运动，如 idle 呼吸、走、跑、攻击、施法、头发、披风、生物；把提供的片段变成透明、已注册、可循环的帧和引擎视频。
不适用场景：FX、图标或道具图集应使用 generate2dsprite；静帧场景内的水、火或雾应使用 generate2dmap；只需要 API 或 CLI 调用应使用 generate2dmedia；用户明确要求代码绘制动画应使用 codeart2d。
主要能力
- 能力检查：运行 forge_doctor.py 查看已配置的 API 密钥、本地就绪状态与解析顺序；video2dsprite.py doctor 检查 ffmpeg（5.1+，VP9 alpha 往返）。
- 美术来源：主图来自 generate2dsprite 或用户；运动为图像转视频，每个动作一段。API 路线包括 xAI Grok Imagine Video（XAI_API_KEY）、BytePlus Seedance（ARK_API_KEY）、fal.ai（FAL_KEY：Kling v3、Veo 3.1、Luma Ray 3.2、MiniMax H3、Wan 3.0、Vidu Q3、LTX）。本地路线为自有图像转视频工具或用户的 Grok CLI（ACP 模式，无法固定末帧）。也可使用用户提供的片段。
- 整套精灵集：sprite_set.py 以一张已确认主图输入，输出每个动作一段图像转视频片段，并完成抠像、门控、注册、裁剪、收尾与打包。默认动作 idle、walk、run、attack、jump、hurt；默认 HD 收尾，像素为可选。
- 单片段流水线：key-plan、prepare_i2v_input.py prepare、route_media.py video、register_clip.py qc/apply、video2dsprite.py triage/process/clean、gait_loop.py select/measure-stride、retime.py、finish_frames.py、engine_export.py package/verify、validate_animation.py。
- 收尾：HD 默认，像素为按需选项；支持颜色锁定（--colour-lock）、角色阵容检查（lineup）、调色板构建（palette build）。
使用方式
从用户项目根目录以单行命令运行各工具，输入输出保持在项目内。每个动词写入新的 --output-dir，拒绝已存在的目录，检查通过后才发布（--strict 在残留时报错）。成功打印一行 JSON；错误打印 error: ... 并退出 1；用法错误退出 2。需要 Python 3.10+、numpy、Pillow 和 ffmpeg 5.1+。--help 列出所有标志。
整套流程：先 plan 生成 set_plan.json 并检查每个动作的提示词，再 run 执行；可重复运行以续跑，不会重复生成。之后 review 并逐帧查看 -sheet.png、-final.png 和 lineup；用 approve 接受或 retake 拒绝并附修复条款，最后 report 列出路线、take、QC 数字、循环、时序与包路径。
单片段流程：key-plan 生成关键计划；prepare 准备输入与提示词；route_media.py video 生成；register_clip.py qc 与 triage 接受 take；process 或 clean 抠像；register_clip.py apply 注册；gait_loop.py select 或 retime.py 做循环或重定时；finish_frames.py 收尾；engine_export.py package 打包并 verify；validate_animation.py 校验。
适用场景与限制
运动与几何规则：一个片段一个动作，游戏负责位移、命中时机、伤害与状态变化；每个片段一个固定变换，绝不按自身 alpha 边界裁剪或缩放帧；同一角色所有动作共享一个身体高度，取自主图静止姿势，绝不放大已完成的精灵；循环用 gait_loop.py select 选择而非仅凭肉眼，走不乒乓，攻击不靠倒放恢复；抠像结论引用 matte report 的数字并保持 needs-visual-review。
验收顺序：先 package，再 verify，最后 validate_animation.py。交付 animation.json（3.0，保留所有 2.0 键；整毫秒 durationsMs、精确 fpsRational）、QA、poster、PNG 回退与所需传输格式。几何保持源单位（sourceSize、sourceAnchor、sourceRect）。Packed H.264 左侧存 RGB、右侧存 alpha，不是透明 MP4。需在游戏尺度检查面部与轮廓稳定性、接触、明暗背景上的移动 alpha 边缘、循环接缝与可读性；在声称 alpha 或帧率前需验证真实 iPhone 播放。
宿主说明：Codex 无原生图像转视频工具，route_media.py 走 xAI API 或 Grok CLI，用 view_image 查看审阅图；Claude Code 无媒体工具，route_media.py 走路线，用 Read 查看审阅 PNG 与接触表，用 Bash 运行工具，<skill-dir> 为 ${CLAUDE_SKILL_DIR}；Grok 的原生 image_to_video 工具即自有工具，同一 grok 可执行文件是其他宿主的“Grok (local CLI)”路线。
资料未提供具体收费、价格、平台支持范围或效果保证。