| name | whiteboard-stream-animation |
| description | 将文章、分镜或现有彩色图片制作成流式笔迹白板动画视频：没有源图时先输出配图策略、经用户确认后生成统一风格源图；有源图时直接渲染。笔尖沿连续轨迹滑行落墨，分起笔(线稿)、添彩(还原原色)、凝视(停留)三段，带手部/笔尖覆盖，输出 MP4。与逐格跳变的做法不同，本 skill 的笔迹是连贯流动的。当用户说"流式手绘"、"笔迹动画"、"白板流式动画"、"把图片画成视频"、"手绘笔迹"时触发。 |
流式笔迹动画生成器
将文章或分镜生成的统一风格源图，或用户直接提供的一张彩色图片，渲染成白板手绘动画。核心特征：笔尖沿一条连续的笔迹滑行，边走边落墨，而不是一格一格地跳变揭墨。
动画分三段：
- 起笔 (ink) — 笔尖沿墨迹流铺下黑白线稿
- 添彩 (color) — 笔尖沿同一条轨迹回头，用原色墨刷把画面点亮，还原为原图
- 凝视 (gaze) — 收笔后停留若干秒，展示完整原图
支持单图模式与队列(批量)模式两种。
前置生图模式：从文章或分镜生成源图
当用户提供文章、口播稿或分镜，但尚未提供可渲染图片时，必须先完成本阶段，再进入下方的单图或队列模式。所有面向用户的说明、配图策略和文件名说明使用中文。
统一出图视觉规范（强制）
所有场景的源图必须遵循同一套视觉语言；在生成图片前，将以下要求完整写入出图提示词，并在生成后检查是否满足：
- 风格与构图： 极简手绘插图、纯素描草图风格、类似 Notion 的克制涂鸦美学。以概念表达为主，不追求写实；构图简洁、背景干净、大量留白，整体情感平和、清晰，系列内的线条、人物和配色保持一致。
- 颜色与材质： 使用米色纸张背景
#F5EBD7、深灰色草图线条；仅可用橙色 #FFA500 作为少量概念性点缀色。不得使用其他强调色、高饱和度配色或复杂纹理。
- 人物与对象： 人物统一使用无脸圆形头的人像；对象以简洁轮廓、少量线条和留白表达，强调关系、变化或核心概念，而非真实比例、材质与细节。
- 绝对禁止： 任何文字、词语、字母、数字、字体或标签；写实感、摄影细节、3D 效果、绘画质感；复杂场景、密集背景、繁复装饰和高饱和度画面。
工作流程
- 阅读文章或分镜，先输出配图策略，不生成图片。每幕只表达一个核心意思，建议每张图承载 25–35 秒口播；策略应包含场景编号、核心表达、画面主体与对应口播段落。
- 等待用户确认配图策略。未确认前不得生成图片，也不得开始渲染视频。
- 确认后，按“统一出图视觉规范”逐幕生成 16:9 暖米黄色旧纸张底线稿图。背景使用
#F5EBD7，主体之间保留充足留白，便于自动拆分；不得生成文字、复杂照片、重叠对象或与该规范冲突的视觉元素。
- 实际查看每张生成图，确认其无文字、主体清晰、留白充分且整组风格一致。发现不符合规范时先重新生成该图。
- 将通过检查的图片保存到用户项目的
assets/whiteboard/<项目名>/；单图进入单图模式，多幕图片连同对应时长进入队列模式。
建议命名：scene-01-<名称>.png、scene-02-<名称>.png。生成的线稿图是后续流式笔迹渲染的唯一源图；不得在渲染时以未检查的草稿图替代。
多幕场景默认进入队列模式；若用户希望把各幕串成一条完整视频，用队列模式的 --merge（详见下方队列模式第三步）。
模式判定
- 用户提供单个图片路径 → 单图模式
- 用户提供多张图片路径 + 对应时长（两个数组）→ 队列模式
- 只要各幕的独立视频 → 队列默认行为
- 要把各幕串成一条完整视频 → 队列模式加
--merge（单片仍保留，另出一个合并总视频）
- 用户提供文章、口播稿或分镜，且未提供图片 → 前置生图模式；用户确认配图策略并完成生图检查后，按生成图片数量转入单图或队列模式
单图模式工作流
第一步：准备环境
先用 --check 探测环境是否就绪：
python <skill目录>/scripts/prepare_env.py --check
- 成功（退出码 0）：末行输出
ENV_PY=<解释器路径>，捕获该路径供后续步骤使用，直接进入第二步
- 失败（退出码 1）：执行完整安装：
python <skill目录>/scripts/prepare_env.py
安装脚本会在 skill 目录下建立 .venv 虚拟环境并补齐缺失依赖（opencv-python、numpy、av(PyAV，用于纯 pip 的 H.264 转码)），末行同样输出 ENV_PY=<路径>。
第二步：确认输入图片
从用户请求中取图片路径并确认文件存在。支持格式：PNG、JPG、JPEG、BMP、TIFF。白色或浅色背景的图效果最好。
第三步：确定参数
可选参数都有合理默认值：
| 参数 | 标志 | 默认值 | 说明 |
|---|
| 图片路径 | 位置参数（必填） | — | 输入彩色图片 |
| 输出目录 | --out-dir | ./out | 视频输出目录 |
| 总时长 | --total-ms | 10000 | 视频总时长（毫秒） |
| 关闭覆盖 | --bare-tip | 默认开启手部覆盖 | 不叠加笔尖/手部 |
| 自定义笔尖 | --pen-image | 内置 drawing-hand.png | 替换手部素材 |
| 上色风格 | --color-fill | contour-wipe | 添彩阶段画法：contour-wipe 轮廓感知自上而下扫描（默认）；brush 沿笔画轨迹刷 |
| 停顿节奏 | --pause | heavy | 起笔段换笔呼吸：heavy 明显（默认）；auto 按密度自动分档；off 关闭；light 少量 |
| 笔迹路径 | --ink-path | grid | 起笔段笔迹：grid 网格格中心插值（默认）；skeleton 骨架级像素追踪（更精准贴合线条） |
第四步：运行渲染脚本
用第一步拿到的 ENV_PY 运行：
<ENV_PY> <skill目录>/scripts/stream_render.py <图片路径> [--out-dir <目录>] [--total-ms <毫秒>] [其它可选参数]
默认配置已是最优组合（grid 笔迹 + contour-wipe 上色 + heavy 停顿），通常只需指定图片路径和时长：
<ENV_PY> <skill目录>/scripts/stream_render.py /path/to/photo.png --out-dir ./out --total-ms 12000
第五步：返回结果
脚本会把最终视频路径打印到 stdout（末行形如 OUTPUT=<路径>），把该路径告知用户。输出文件命名格式：stream_YYYYMMDD_HHMMSS_h264.mp4。
队列(批量)模式工作流
当用户提供图片路径数组 + 对应时长数组时使用。
第一步：准备环境
与单图模式相同，先跑 prepare_env.py 取 ENV_PY。
第二步：校验输入
从用户请求中获取：
- 图片路径数组（必填）
- 时长数组（毫秒，必填，与图片一一对应）
必须满足：两数组长度相同；每张图都存在；每个时长为正整数。
第三步：运行队列渲染脚本
<ENV_PY> <skill目录>/scripts/queue_render.py \
--images /p/img1.png /p/img2.png /p/img3.png \
--durations 10000 15000 8000 \
[--out-dir ./out] [--bare-tip] [--pen-image <路径>] [--fail-fast] \
[--merge] [--merged-name <文件名>]
--fail-fast 可选：某个任务失败立即中止整批；不加则失败不阻塞后续。--merge 可选：全部渲染完后，把各成功片段按输入顺序硬切合并为一条总视频；单片仍保留，另在输出目录生成合并视频。合并优先走系统 ffmpeg 无损拼接（-c copy，不重编码）；片段尺寸不一致或无 ffmpeg 时自动重编码（ffmpeg filter 或 PyAV）。默认文件名 merged_YYYYMMDD_HHMMSS.mp4，可用 --merged-name 指定。
- 提示：要无损合并，各幕应统一 16:9、同一渲染参数（默认即满足）；尺寸混用会触发重编码并缩放补边到第一段尺寸。
脚本内部串行调用 stream_render.py，逐个打印进度；开启 --merge 时末行输出 MERGED=<合并视频路径>。
第四步：返回结果
告知用户：生成总数、成功/失败数、输出目录；若有失败则列出失败图片。开启 --merge 时，额外告知合并视频路径（脚本末行 MERGED=）。
三种模式与常用组合
三个独立维度控制动画风格，各有默认值，默认组合已是推荐配置：
| 维度 | 标志 | 选项 | 默认 | 说明 |
|---|
| 笔迹路径 | --ink-path | grid / skeleton | grid | 起笔段笔尖轨迹：grid 沿网格格中心插值（块状感、稳定）；skeleton 沿骨架像素追踪（细线条、精准贴合原图、交叉点无碎笔画） |
| 上色风格 | --color-fill | contour-wipe / brush | contour-wipe | 添彩段画法：contour-wipe 颜色自上而下沿轮廓蔓延（涂色覆盖感）；brush 沿笔画轨迹逐点刷原色（手绘涂色感） |
| 停顿节奏 | --pause | heavy / auto / light / off | heavy | 起笔段换笔呼吸：heavy 明显停顿；auto 按密度自动；light 少量；off 关闭 |
常用组合
<ENV_PY> <skill目录>/scripts/stream_render.py photo.png --total-ms 12000
<ENV_PY> <skill目录>/scripts/stream_render.py photo.png --ink-path skeleton --color-fill contour-wipe --pause heavy
<ENV_PY> <skill目录>/scripts/stream_render.py photo.png --pause off --color-fill brush
<ENV_PY> <skill目录>/scripts/stream_render.py photo.png --ink-path skeleton
提示：skeleton 笔迹对线稿清晰的图（插画、简笔画）效果最好；照片或背景复杂的图用默认 grid 更稳定。
进阶调参（通常不需要）
stream_render.py 还接受几个覆盖默认值的旋钮：--fps（帧率，默认 60）、--grid-edge（网格边长，默认 10）、--brush-radius（墨刷半径，默认 40，仅 brush 模式）。仅当用户明确要调整画质/体积时使用。
contour-wipe 上色模式（默认）另有几个旋钮：--wipe-decay（阻力场向下衰减系数，默认 0.86，越小越快越过轮廓）、--wipe-delay-ratio（轮廓处前沿扣减比例×h，默认 0.04，越大轮廓处停留越久）、--wipe-blocks（笔尖横向来回趟数，默认 18）。
skeleton 笔迹模式的碎片过滤阈值固定为 8 个采样点（骨架笔画短于此即丢弃），无对应 CLI 参数，如需调整改 Config.skeleton_min_points。
起笔段停顿由 --pause 控制（默认 heavy 明显停顿）。若改 --pause auto 则按"每格帧数"自动分三档——内容稀疏时多停顿、密集时不停顿。
故障排除
ModuleNotFoundError：重跑 prepare_env.py 补依赖。无法读取图片：确认路径正确、文件非损坏；带中文/空格的路径建议加引号。- 没有 H.264 输出、只有 mp4v：系统 ffmpeg 与 PyAV 都不可用时才会发生，脚本保留原始 mp4v 编码并给出 warning。正常情况下
prepare_env.py 已装好 PyAV，无系统 ffmpeg 也能得到 H.264；若仍是 mp4v，重跑 prepare_env.py 确认 av 安装成功，或安装系统 ffmpeg（体积更优）。
- 队列模式单个任务失败：默认不影响后续任务，最终汇总会列出失败项；如需遇错即止，加
--fail-fast。
