白板手绘动画（mask 编排 + stream 画法）

把 SRT 字幕转成白板手绘动画：编排沿用分区遮罩揭示（按叙事顺序逐区域揭示、未开始区域完全隐藏、重叠用 protectedRegions 保护）；画法用流式笔迹——每个区域在自己允许掩码内，笔尖沿骨架/网格连续滑行落墨（起笔 ink → 添彩 color），所有区域共享一张持久画布，已画完的区域保留在画布上。所有面向用户的说明、分镜、配置和界面文字必须使用中文。

与逐格跳变或矩形擦除不同：本 Skill 的笔迹是连贯流动的；与整图 stream 不同：本 Skill 按字幕叙事分区依次作画，可控制每个元素的出场顺序与时序。

项目来源与致谢

• 原始项目：https://github.com/geeklee/srt-whiteboard-animation（MIT License，作者：江哥是老登啊）
• 本 Skill 为 WorkBuddy 适配版：保留原作者全部渲染脚本（parse_srt.py / prepare_env.py / render_annotation_preview.py / render_stream_whiteboard.py / stream_render.py / merge_scenes.py）与预览台 assets/preview.html，新增 WorkBuddy 环境衔接（生图模型生成线稿、浏览器打开预览台、结果交付）。
• v2.0.0 升级（对齐 SkillHub「白板动画（AIPDD）」规格 @org-bzwfrdvh/aipdd-srt-whiteboard-animation）：新增 NewAPI 模型底座（scripts/configure.js / scripts/invoke.js，Node ≥18 零依赖）——线稿生成可走用户自己的 NewAPI 服务（FLUX、Seedream 等），密钥经 stdin 或环境变量传入、绝不落命令行不回显；未配置 NewAPI 时沿用内置生图模型降级并如实告知。
• 引用素材 drawing-hand.png（手部素材，渲染必需）为二进制文件不随包分发，渲染脚本会在缺失时自动从原项目 GitHub 下载，也可自行用生图模型生成。

核心流程（一句话）

字幕 → 分镜 → 线稿 → 标注 → 预览确认 → 渲染 MP4。每幕 25-35 秒，先确认分镜再画线稿，先确认线稿再标注，先确认标注再渲染——每一步完成后停止等待用户明确确认，避免浪费生图与渲染成本。

默认实现参数

模型底座（NewAPI）

线稿图通过内置 NewAPI 底座调用 FLUX、Seedream 等文生图模型生成，本技能不绑定特定模型：

• 服务配置（一次性）：首次使用前需要用户提供 NewAPI 服务地址与 API Key，用 node scripts/configure.js 从标准输入写入配置，不要把密钥放在命令行参数中，也不要将其回显到对话、日志或报告中。更安全的做法是设置环境变量 NEWAPI_BASE_URL / NEWAPI_API_KEY，此时无需写配置文件。
  bash echo '{"baseUrl":"https://your-newapi.example.com","apiKey":"your-key"}' | node scripts/configure.js # 或设置环境变量 NEWAPI_BASE_URL / NEWAPI_API_KEY（推荐，避免密钥落盘） node scripts/configure.js --check # 探测当前配置可用性（环境变量或 config.json）
• 调用方式：node scripts/invoke.js --type image --prompt "<提示词>" --model "<模型名>"，可选 --ratio "16:9"、--size、--poll-seconds、--timeout-seconds。脚本只输出 JSON 结果，将 status / url / error 字段转换为简洁中文回复用户，并用 url 下载为场景 PNG。
• 模型选择：用户明确指定模型时必须使用指定模型（如 FLUX、Seedream）；用户没有指定模型时，先询问用户选择哪个模型，不要静默选择收费模型。可用模型与接口字段以用户 NewAPI 服务实际为准，不猜测模型或参数。
• 失败处理：上游服务失败时保留原始错误信息，不自动换模型重试；生成结果需报告状态、所用模型和结果 URL。
• 安全：配置文件为技能包根目录 config.json（含密钥），不得提交到版本库；可用环境变量 NEWAPI_CONFIG 重定向到其他路径，或直接用环境变量方案。
• 降级路径：未配置 NewAPI 时，第 2 步改用内置生图模型（ImageGen）生成线稿，并如实告知用户当前用的是降级路径。

统一出图视觉规范（强制，写进生图提示词）

所有场景的源图必须遵循同一套视觉语言；生成前把以下要求完整写入出图提示词，生成后逐条检查：

• 风格与构图：极简手绘插图、纯素描草图风格、类似 Notion 的克制涂鸦美学。以概念表达为主，不追求写实；构图简洁、背景干净、大量留白，整体情感平和、清晰，系列内线条/人物/配色一致。
• 颜色与材质：米色纸张背景 #F5EBD7、深灰色草图线条；仅可用红色、橙色、蓝色作少量概念性点缀。不得使用其他强调色、高饱和度配色或复杂纹理。
• 人物与对象：对象以简洁轮廓、少量线条和留白表达，强调关系/变化/核心概念，而非真实比例、材质与细节。
• 绝对禁止：场景源图中的任何文字、词语、字母、数字、字体或标签；写实感、摄影细节、3D 效果、绘画质感；复杂场景、密集背景、繁复装饰和高饱和度画面。
• 构图预留：16:9 横版；主体之间保留充足留白，便于后续自动拆分区域。

生图提示词模板（每幕按内容替换【】）：

极简手绘白板插画，16:9 横版，暖米黄旧纸背景 #F5EBD7，深灰色素描线条。
【画面主体描述，如：假山上坐着的小猴子手里举着香蕉】
【补充元素，如：旁边扑过来抢香蕉的大猴、远处围观的小朋友】
概念性表达，克制的涂鸦美学，构图简洁，大量留白，线条/人物风格统一。
只用少量红/橙/蓝作点缀。画面中不得出现任何文字、字母、数字或标签。
不要写实、不要 3D、不要复杂纹理。

确认关卡（强制）

默认工作流的每一步完成后都必须停止并等待用户明确确认，才可开始下一步。确认前不得生成下一步的图片、标注、预览、视频或合并文件；不得把「未回复」「此前的笼统授权」「用户没有反对」视为确认。用户要求修改上一步时，只重做该步，并在完成后再次等待确认。

唯一的连带动作是：标注 JSON 创建完成后，必须立即在浏览器打开预览台并载入该 JSON 所在目录；这属于第 3 步的交付，不需要为「打开预览台」另行等待确认。

工作流程（七步确认制）

第 1 步：读字幕、出分镜与配图策略（不生成图片）

1. 用 scripts/parse_srt.py 解析 SRT 并按 25–35 秒/幕给出建议分镜：
   bash python scripts/parse_srt.py <字幕.srt> --target-sec 30 --min-sec 25 --max-sec 35
2. 基于 JSON 输出中的 scenes[]，产出配图策略表（Markdown 表格）：每幕的场景编号、起止时间、sceneDurationMs、核心表达（一句话）、画面主体与构图要点、对应字幕区间。
3. 每幕只表达一个核心意思；若某幕字幕跨多个叙事事件，提示用户是否拆分。
4. 分镜算法说明：默认 30 秒目标、25-35 秒区间；尾幕不足 15 秒会自动并入上一幕（尾幕可略超 35 秒），避免碎片尾幕。
5. 完成后停止，展示配图策略表，等待用户确认。

第 2 步：生成线稿（NewAPI 模型底座 / 内置生图）

1. 仅在用户确认策略后，按「统一出图视觉规范」逐幕生成 16:9 暖米黄旧纸张底线稿图，背景 #F5EBD7，主体之间保留充足留白便于自动拆分。提示词必须完整包含「统一出图视觉规范」全部约束：背景 #F5EBD7 且纯色均匀无纹理、深灰连续线条、主体之间保留充足留白便于自动拆分、画面无任何文字；不得生成照片写实、重叠对象或与规范冲突的元素。
2. NewAPI 模型底座（已配置时优先）：每幕一条提示词，用 node scripts/invoke.js --type image --prompt "<统一出图视觉规范+场景描述>" --model "<模型名>" --ratio "16:9" 调用用户指定或已确认的模型（如 flux.1-dev、seedream-4.0；未指定时先询问，不静默选收费模型）。解析返回 JSON 的 url，把图片下载保存为：
   assets/whiteboard/<项目名>/scene-01-<名称>.png assets/whiteboard/<项目名>/scene-02-<名称>.png
3. 内置生图模型（未配置 NewAPI 时降级）：使用内置生图模型（ImageGen），每幕一条提示词（用上面的提示词模板），输出到上述同一目录，并如实告知用户当前用的是降级路径。
4. 也可跳过本步：用户可自行提供线稿（上传图片），从第 3 步继续。
5. 生成后逐张检查是否违反视觉规范（出现文字/写实/复杂背景等则重新生成）。
6. 完成后停止，展示线稿，等待用户确认。

第 3 步：读字幕看原图 → 标注 → 打开预览台

1. 仅在用户确认线稿后：先阅读该图对应的字幕，再实际查看图片，并获取原图像素宽高（不得只凭字幕臆测画面，也不得只按画面位置机械排序）。
2. 先提炼字幕叙事事件，再把图中可见主体对应到事件，按「场景铺垫 → 关键人物/物体 → 动作冲突或变化 → 反应/结果」的语义顺序安排绘制。
3. 创建 <图片名>.annotation.json（与原图同名），字段规范见下方「标注格式」。
4. 创建完成后，立即用默认浏览器打开 assets/preview.html，并让用户通过预览台「打开文件夹」载入该标注文件所在目录的全部 <名称>.png + <名称>.annotation.json（File System Access API 需要 Chrome/Edge，且必须由用户手势触发）。在 WorkBuddy 中：用浏览器打开本地 assets/preview.html 路径即可。
5. 预览台已带入目录后停止，等待用户确认标注与预览内容。

第 4 步：生成区域预览图（检查图）

1. 仅在用户确认标注与预览内容后：
   bash python scripts/render_annotation_preview.py <图片路径> <标注路径> <预览图输出路径>
2. 出编号/方向检查图，核对：分区与叙事顺序一致、区域都在画布内、重叠主体用 protectedRegions 保护。
3. 完成后停止，展示检查图，等待用户确认。

第 5 步：在预览台调整并保存

1. 仅在用户确认预览图后，在已打开且已载入对应目录的预览台调整：默认（未播放）显示完整图片和区域框；画布是矩形代理——拖区域四边四角改 region，右侧改名称/方向/开始(ms)/结束(ms)（时长=结束−开始，只读）与字幕，拖动模块列表调整顺序（自动重排 sequence），选中模块自动高亮对应字幕；拖时间轴或按播放看揭示（未开始区域不显示）。
2. 改完点「保存本场景/全部保存」写回原 .annotation.json（含每区域 subtitle，并把 sceneDurationMs 对齐到最后区域结束+0.5s）。
3. 该步由用户操作预览台完成；保存后告知 Agent 已保存。
4. 保存后停止，等待用户确认最终标注与时序。

第 6 步：命令行渲染成片

1. 仅在用户确认最终标注与时序后，先确保渲染环境就绪：
   bash python scripts/prepare_env.py --check # 探测；末行输出 ENV_PY=<路径>，捕获备用 python scripts/prepare_env.py # 缺则建 .venv 并装 opencv-python/numpy/av/Pillow
2. 用 <ENV_PY> 逐幕渲染：
   bash <ENV_PY> scripts/render_stream_whiteboard.py <图片> <标注> <输出mp4> \ [--ink-path grid|skeleton] [--color-fill contour-wipe|brush] [--total-ms <毫秒>]
--total-ms 缺省时用标注里的 sceneDurationMs。末行输出 OUTPUT=<路径>。
3. 抽查开场、任意重叠模块中段、结尾三个时间点（用播放器或抽帧）。
4. 完成后停止，展示成片，等待用户确认。

第 7 步：多幕合并（仅多幕项目）

1. 仅在用户确认所有单幕成片后：
   bash <ENV_PY> scripts/merge_scenes.py --inputs 幕1.mp4 幕2.mp4 幕3.mp4 --output final.mp4
   优先用系统 ffmpeg 无损拼接（-c copy）；无 ffmpeg 或尺寸/编码不一致时回退 PyAV 重编码。
2. 完成后停止，展示最终合成视频，等待用户确认。 用户可自行配字幕和配音完成成品。

目录约定

在用户项目中创建：

assets/whiteboard/<项目名>/
  scene-01-<名称>.png
  scene-01-<名称>.annotation.json     # 与 png 同名
  scene-01-<名称>-whiteboard.mp4      # 成片
  scene-01-<名称>-preview.mp4         # 真实片段（预览台生成，低清）

图片与配置必须同名：foo.png 对应 foo.annotation.json。预览台据此自动加载配置。

标注格式（annotation.json）

{
  "sceneId": "scene-01",
  "canvas": { "width": 1672, "height": 941 },
  "storyBasis": "小猴在猴子山上拿着香蕉，大猴抢走香蕉，孩子们在旁观看。",
  "sceneDurationMs": 9000,
  "elements": [
    {
      "id": "rockery",
      "label": "猴子山场景",
      "sequence": 1,
      "narrativeRole": "故事的场景铺垫",
      "subtitle": "小猴子坐在猴子山顶，手里拿着香蕉。",
      "type": "structure",
      "region": { "x": 20, "y": 120, "width": 540, "height": 780 },
      "reveal": {
        "direction": "top_to_bottom",
        "startMs": 300,
        "durationMs": 2600,
        "maskPaddingPx": 22,
        "protectedRegions": []
      },
      "handPath": { "start": [290, 130], "end": [290, 890], "easing": "easeInOut" }
    }
  ]
}

direction 和 handPath 用于预览台的矩形代理；最终成片的真实笔迹由流式绘制器自动生成。对于相互遮挡的对象，在较早元素的 protectedRegions 中标出需要延后显示的区域，避免后续内容提前露出。

语义排序与像素级标注（必须执行）

1. 阅读依据：标注前必须同时具备字幕与已查看的原图。缺任一项先索取，不得生成标注。
2. 顺序依据：sequence、startMs 与 label 必须反映字幕中的事件先后，而非仅按从左到右、从上到下或视觉显眼程度。
3. 坐标依据：每个模块输出原图坐标系的整数像素 x、y、width、height；原点左上角，禁止百分比/比例/估算坐标或省略尺寸。canvas.width/canvas.height 必须等于原图像素尺寸。
4. 模块字段：每个元素含 sequence、narrativeRole、subtitle、region、reveal、handPath。narrativeRole 用中文说明其在字幕中的叙事作用；subtitle 存该区域对应的字幕文本（来自 SRT，供预览台联动与后续用途）；sequence 从 1 起连续。
5. 校验：生成预览前检查每个区域是否在画布内、是否覆盖对应可见主体、是否与字幕事件相符；重叠主体用 protectedRegions 保护后绘制模块。

时序模型（stream 画法专用）

• 每幕总时长 sceneDurationMs 来自该幕字幕时间跨度（parse_srt.py 的 scenes[].sceneDurationMs）。
• 区域串行作画：stream 画法是一支笔在动，同一幕内各区域应在时间上依次进行（startMs 不重叠）：下一区域从上一区域 startMs + durationMs（+ 可选 100–300ms 呼吸）开始。若 startMs 重叠，渲染器仍按顺序处理，但视觉上不再是并发。
• 区域内 ink→color：每个区域的 durationMs 会按 ink:color = 2:1 切成起笔段和添彩段。durationMs 由预览台的开始/结束时间决定（结束−开始），可对齐该区域对应字幕的时长；也可用 150 像素/秒 × 绘制距离作为初始估算。
• 凝视收尾：全部区域画完后自动补到 sceneDurationMs，并保证结尾至少停留 0.5 秒完整原图。
• reveal.direction 在 stream 画法下不决定真实笔迹（笔迹由骨架/网格自动生成），仅供预览台的矩形代理演示；保留它是为了预览台可用。

遮罩不变量（编排层，必须执行）

• 在时间 t，模块仅可显示其 reveal.startMs ≤ t 之后、且不超过当前作画进度的像素；未开始模块的任何线条/填充/图像都不得出现。
• 每个区域的允许掩码 = 矩形 region 扣除全部后续模块的 region，再扣除本模块 reveal.protectedRegions。stream 落墨被限制在允许掩码内，因此后续区域不会提前露线。
• protectedRegions 采用与 region 相同的原图整数像素坐标，用于矩形过大、主体交叠或背景线条可能泄露的情况。
• 渲染器已实现「限制在允许掩码内落墨 → 后续区域与保护区天然不被触碰」的顺序；预览台矩形代理用等价的 destination-out 扣除演示同一编排。

脚本清单

注意：
- 渲染脚本需用 .venv 的解释器运行（prepare_env.py 输出的 ENV_PY）；首次安装依赖较慢，请耐心等待。
- 手部素材 assets/drawing-hand.png 是二进制不随包分发，渲染时自动从原项目下载；也可用生图模型生成简单手部线稿替代。
- 绘制手部例外：若用户明确说明笔杆上的文字是其标识并要求保留，可保留 drawing-hand.png 笔杆上的标识；它不属于场景源图文字，也不需要清除或重绘。未获得用户明确说明时，仍按无文字画面处理（即下载的素材按原样使用，场景源图仍必须无文字）。
- parse_srt.py 可用任何 Python 运行（零依赖），用于第 1 步分镜。

使用脚本（快速参考）

# 0) 配置模型底座（NewAPI）（首次或更换服务时）
echo '{"baseUrl":"https://your-newapi.example.com","apiKey":"your-key"}' | node scripts/configure.js
#    或设置环境变量 NEWAPI_BASE_URL / NEWAPI_API_KEY（推荐，避免密钥落盘）
#    配置写入技能包根目录 config.json（含密钥，勿提交仓库）；可用 NEWAPI_CONFIG 重定向到其他路径

# 1) 生成线稿图（工作流第 2 步）
node scripts/invoke.js --type image --prompt "<统一出图视觉规范+场景描述>" --model "flux.1-dev" --ratio "16:9"
#    输出 JSON（status / url / error）；把 url 下载保存为 assets/whiteboard/<项目名>/scene-01-<名称>.png
#    模型名以用户 NewAPI 服务实际注册名为准（如 flux.1-dev、seedream-4.0）

# 2) 准备环境（首次或缺依赖时）
python scripts/prepare_env.py --check   # 探测；成功末行输出 ENV_PY=<路径>，捕获备用
python scripts/prepare_env.py           # 缺则建 .venv 并装 opencv-python/numpy/av/Pillow

# 3) 解析字幕 + 建议分镜（第 1 步）
python scripts/parse_srt.py <字幕.srt> --target-sec 30 --min-sec 25 --max-sec 35

# 4) 区域编号预览图（第 4 步）
python scripts/render_annotation_preview.py <图片> <标注> <预览图输出>

# 5) 预览台（无需服务器）：直接用 Chrome / Edge 打开 assets/preview.html，
#    点「打开文件夹」选目录 → 载入全部图片+同名标注 → 拖拽编辑 → 「保存」写回原文件。
#    写回需 File System Access API（Chrome/Edge）；其它浏览器改为下载后手动覆盖。
#    渲染仍走命令行（下面第 6 步）。

# 6) 渲染单幕成片（第 6 步）
<ENV_PY> scripts/render_stream_whiteboard.py <图片> <标注> <输出mp4> assets/drawing-hand.png \
    [--ink-path grid|skeleton] [--color-fill contour-wipe|brush] [--total-ms <毫秒>]
#    --total-ms 缺省时用标注里的 sceneDurationMs。末行输出 OUTPUT=<路径>。

# 7) 多幕合并（第 7 步，仅多幕）
<ENV_PY> scripts/merge_scenes.py --inputs 幕1.mp4 幕2.mp4 幕3.mp4 --output final.mp4

质量检查

渲染前/后确认：

• 首帧为干净的暖米黄旧纸张底，没有提前露出线条。
• 已阅读对应字幕并实际查看原图；canvas 与原图像素尺寸一致，所有 region 为整数像素坐标且在画布内。
• sequence、startMs 与字幕事件顺序一致；预览图编号/标签/区域来自同一份标注 JSON。
• 在开场、任意重叠模块中段、所有模块完成后三个时间点检查：未绘制模块均不可见，重叠保护区不漏出，最终帧显示完整原图。
• 笔尖贴近正在推进的笔迹；线稿清晰的插画可用 --ink-path skeleton 让笔迹更贴合。
• 所有模块结束后停留至少 0.5 秒完整原图。
• 多幕合并后顺序、时长与字幕分镜一致。

如需修改效果，先在预览台（assets/preview.html）调整标注（区域/顺序/时序）并保存，再命令行渲染，不要凭空反复出片。