创建白板视频
把一次视频制作保存为带 project.json 的项目。将 Skill 安装目录只作为共享程序来源；把文案、图片、音频、预览、成片、项目专用画笔副本、虚拟环境、缓存和临时文件统一写入用户确认的项目目录。
选择入口
- 收到文章或口播稿：初始化
text项目并生成初始语义分镜。 - 收到 SRT：按时间聚合成场景，同时保留场景内相对字幕时间。
- 收到已有图片：先建立项目和分镜，再把图片附加到对应场景。
- 收到已有
project.json：先运行status和validate，只继续未完成或失败的阶段。 - 仅想快速验证效果：允许整图单区域标注；明确说明这只是烟雾测试，不代表最终叙事编排。
选择绘制策略
场景图确认后选择一种策略，不把两套流程混用：
diagonal-scan（默认）：整幕作为单一区域，从左上向右下推进；每条笔触从左下画向右上。轮廓和铺色必须复用同一组采样点及换行顺序，不做人物抠图，不生成或审批曲线蒙版。适合水彩插画、复杂背景和用户希望整图逐步完成的场景。semantic-stream：按“背景 → 人物/物体 → 动作 → 结果”分层出现。仅在用户明确需要对象分阶段绘制时使用；人物和物体必须生成并确认像素级 Alpha 蒙版。
若用户未指定，先制作一段 diagonal-scan 烟雾测试供确认；未经确认，不批量渲染全片。
0. 确认统一保存目录
正式准备环境、生成分镜或制作任何素材前，先让用户选择最终的视频项目根目录。即使用户已给出路径，也要展示解析后的完整绝对路径，并询问“是否确认将本项目的素材、临时文件、运行环境和成片全部保存到这里”。只有用户明确确认后才能继续；不得默认使用当前目录、系统临时目录、桌面或 Skill 安装目录。
确认后，项目结构统一为：
text<项目根目录>/ ├── project.json ├── source/ audio/ scenes/ previews/ output/ └── .whiteboard-video/ ├── .venv/ ├── cache/pip/ ├── tmp/ └── assets/drawing-hand.png
共享的 Skill 脚本和系统级 FFmpeg 不复制进项目；第三方图片生成服务或客户端自身的内部缓存也不受本 Skill 控制。生成或下载到外部临时位置的图片、音频必须先复制进 scenes/ 或 audio/，再附加到项目；其余由本工作流创建或复制的文件必须留在项目根目录内。
继续旧项目时，先展示现有 project.json 所在目录并取得确认，再本地化其运行目录和画笔：
powershell<ENV_PY> <SKILL_ROOT>/scripts/video_project.py localize-storage <project.json> --user-confirmed-project-dir
准备运行环境
先确定本文件所在目录为 SKILL_ROOT。使用用户刚确认的绝对路径运行：
powershellpython <SKILL_ROOT>/scripts/prepare_env.py --project-dir <已确认的项目根目录> --user-confirmed-project-dir
读取输出中的 PROJECT_ROOT、RUNTIME_ROOT、CACHE_DIR、TEMP_DIR 与末行 ENV_PY。后续所有脚本都使用该解释器。脚本会把虚拟环境、pip 缓存和临时目录固定在项目的 .whiteboard-video/ 中，并拒绝项目外的虚拟环境路径。
工作流
1. 初始化并规划
powershell<ENV_PY> <SKILL_ROOT>/scripts/video_project.py init <已确认的项目根目录> --source <文案.md或字幕.srt> --ratio 16:9 --user-confirmed-project-dir <ENV_PY> <SKILL_ROOT>/scripts/video_project.py plan <项目目录>/project.json
检查并改写 scenes[].narration 与 visualPrompt。按语义而不是固定字数切分；短视频通常每幕 5–12 秒，知识讲解通常 10–20 秒，复杂画面可到 30 秒。未经用户确认分镜，不批量生成图片。
详细字段见 references/project-schema.md。
2. 准备音频并确认字幕方式
如果用户已有最终旁白或 SRT，把它们附加到项目：
powershell<ENV_PY> <SKILL_ROOT>/scripts/video_project.py audio <project.json> --narration <旁白.wav> --subtitles <字幕.srt>
audio 命令会把一条内含多句话的字幕按句子拆开，按字数比例重新分配原时间段，并写入 *.sentences.srt。每次只显示一句；自动去掉句末句号，保留问号和感叹号。最终项目引用拆句后的字幕，同时保留 subtitlesSource 指向原 SRT。
向用户展示代表性字幕文本并说明内置字幕样式，然后必须让用户明确选择一种交付方式；不要默认烧录：
powershell# 直接烧录进画面 <ENV_PY> <SKILL_ROOT>/scripts/video_project.py approve-subtitles <project.json> --mode burn-in --user-confirmed # 不烧录，随成片导出 output/final.srt，便于后期添加 <ENV_PY> <SKILL_ROOT>/scripts/video_project.py approve-subtitles <project.json> --mode sidecar --user-confirmed # 成片和交付目录都不带字幕 <ENV_PY> <SKILL_ROOT>/scripts/video_project.py approve-subtitles <project.json> --mode none --user-confirmed
字幕文件变化后确认自动失效。finalize 在字幕方式未确认时必须停止。
先锁定旁白，再决定场景时长。没有旁白服务或录音时，只交付图片和标注预览，不声称已经完成配音。V1 可合成单条旁白，并按用户选择烧录、旁挂或省略字幕；背景音乐只记录在清单中，暂不自动混音。
3. 生成或附加场景图
遵守 references/visual-style.md。缺少场景图时，使用可用的图像生成能力逐幕生成，并保持同一画幅、纸张颜色、线条和角色外观。要求内容铺满完整画布，禁止为了字幕在底部或其他方向预留空白条；字幕是否存在由后续确认决定。每幕只表达一个核心动作，画面内不生成文字、标签或水印。
图片生成因网络、额度或服务错误中断时，保留已完成图片并继续剧本、旁白、字幕、标注预览等准备工作。把未完成场景保持为 planned，列出缺失项；未经用户明确同意，不用占位图、重复图或代码备用图补齐，也不运行 approve-render、render 或 finalize。确需临时图验证布局时用 attach --provisional，该状态会在脚本层阻止渲染确认。
把通过检查的图片附加到场景：
powershell<ENV_PY> <SKILL_ROOT>/scripts/video_project.py attach <project.json> --scene scene-01 --image <scene-01.png>
该命令会生成整图单区域标注，可直接用于 diagonal-scan。保持一个覆盖完整画布的 structure 元素并使用 maskMode: none；不运行 refine-masks 或 approve-masks。
只有选择 semantic-stream 时，才把标注拆成“场景铺垫 → 关键人物/物体 → 动作变化 → 反应/结果”。矩形只用于圈定对象搜索范围和时序，禁止充当擦除区。拆分完成后生成像素级透明 PNG 蒙版：
powershell<ENV_PY> <SKILL_ROOT>/scripts/video_project.py refine-masks <project.json> --scene scene-01 --edge-padding 2
人物、动物、物体、动作与结果区域必须使用 maskMode: raster 和 maskImage；蒙版 Alpha 边缘要逐像素贴合可见内容。粗多边形、矩形和 auto 内容检测只作旧项目兼容，不能通过正式渲染校验。环境结构使用 maskMode: none。标注格式见 references/annotation-schema.md。
自动生成蒙版后必须查看标注预览；如果蒙版粘连到家具或漏掉浅色衣物，先缩紧 region 或手工修正透明 PNG，再重新预览。单张合成图无法凭空还原人物背后的真实背景。默认在 Alpha 轮廓内保留纸色，等待对象被画出；如果用户要求轮廓内也保持自然背景，素材阶段必须另备一张无人物的干净背景层，不用模糊或自动补洞冒充真实背景。
4. 预览和校验
powershell<ENV_PY> <SKILL_ROOT>/scripts/video_project.py preview <project.json> --scene scene-01 <ENV_PY> <SKILL_ROOT>/scripts/video_project.py validate <project.json> --render-ready
diagonal-scan 不检查绿色人物蒙版；检查整图是否铺满画布，并先渲染一段短预览，确认轮廓和铺色都沿左下→右上的同一路径、扫描顺序从左上推进到右下、换行时没有跨线连笔。
semantic-stream 需要可视化编辑时打开 assets/annotation-editor.html，选择场景文件夹。选中人物后点击“开始修边”，绿色区域就是实际 Alpha 蒙版；用“补入人物/擦除背景”画笔沿曲线修正并保存 PNG。不要把搜索矩形当作蒙版。禁止在缺少细腻蒙版、校验失败、区域越界、时间重叠或画布尺寸不一致时继续正式渲染。
只有 semantic-stream 才逐幕把绿色曲线预览交给用户。用户明确确认轮廓足够细腻后，记录与蒙版文件 SHA-256 绑定的许可：
powershell<ENV_PY> <SKILL_ROOT>/scripts/video_project.py approve-masks <project.json> --scene scene-01 --user-confirmed
蒙版 PNG 变化后确认自动失效，validate --render-ready 必须阻止继续。
5. 渲染场景
所有图片和标注通过检查后，先把素材预览交给用户。只有用户明确说可以生成视频时，才记录一次与当前素材指纹绑定的许可：
powershell<ENV_PY> <SKILL_ROOT>/scripts/video_project.py approve-render <project.json> --user-confirmed
缺图、缺标注时该命令失败；确认后图片、标注、音频、字幕或视频参数发生变化，许可自动失效，必须重新请用户确认。
初始化时把 Skill 内置的 assets/drawing-hand.png 复制为项目专用的 .whiteboard-video/assets/drawing-hand.png；渲染只读取项目副本，画笔位置跟随当前真实落墨路径。素材缺失或不可读时必须停止，不得静默切换为程序化笔头。
默认使用已确认的整图斜向扫描。diagonal 必须同时传给轮廓和铺色；脚本会拒绝只设置其中一个：
powershell<ENV_PY> <SKILL_ROOT>/scripts/video_project.py render <project.json> --ink-path diagonal --color-fill diagonal --pointer hand --pause auto
仅在用户选择 semantic-stream 时使用网格笔迹；清晰细线稿再尝试 skeleton：
powershell<ENV_PY> <SKILL_ROOT>/scripts/video_project.py render <project.json> --ink-path grid --pointer hand --pause auto
只重渲染一幕时重复使用 --scene scene-02。--pointer pen 作为兼容别名也使用同一固定素材；--pointer none 仅用于技术诊断，不用于正式视频。保持所有场景的画幅、FPS 和渲染参数一致。
6. 合成并质检
powershell<ENV_PY> <SKILL_ROOT>/scripts/video_project.py finalize <project.json> <ENV_PY> <SKILL_ROOT>/scripts/video_project.py qa <project.json>
finalize 同时检查渲染许可和独立的字幕方式确认；任一未确认或指纹失效时必须停止。
按 references/quality-checklist.md 检查首帧、中段、末帧、时长、音画和未开始区域。出现提前露线、手部漂移、字幕遮挡或时长偏差时，只修复对应场景后重新合成。
交付
交付以下结果并明确未完成项：
project.json- 每幕源图、标注和 MP4
output/final.mp4output/qa-report.json与首中末帧- 用户选择
sidecar时交付output/final.srt - 如未配置旁白、字幕或背景音乐，逐项说明
实现来源
本项目由 Weikezi-AI 独立维护。修改渲染核心时同时运行项目测试和真实 MP4 烟雾测试。
