主题手绘视频

交付可播放成片、封面、字幕、口播稿和检查记录。默认简体中文（language 可改，如 en：语音识别、字幕断行与语速门禁随之切换）、1280×1920（2:3）、30fps；用户的语言、尺寸、画风、声音和复用要求优先。片长随内容和实际配音变化，不固定页数、布局或每页秒数。

先读依赖路由，再按需读取内置指南。主体内容由模型设计；脚本只执行已确定的素材与时间线，并用客观指标拦截错误。只有主题、故事、正文、附件全部缺失时才暂停索要；其余偏好都有默认值，不构成阻碍。宿主无法生成图片时停止并告诉用户，不能静默降级成纯文字视频。

流程

开场单独设计。 写口播前读取黄金5秒开场，从六种方法中按内容选主策略，写入 design.json.opening_hook；封面、首句和第一笔共同传达继续看的理由。配音后按真实时间戳核对成片0–5秒（含1秒封面），分镜优先画出承载钩子的关键对象或关系，编排后单独预览开头及其正文衔接，终审核对承诺兑现。build 实测"第一个有效画面"（屏幕至少1%被画上内容）出现的时刻：超过3秒警告，超过4秒拒绝，确属有意的慢开场在 opening_hook.slow_open_reason 写明理由。完整步骤见该指南；已锁定的原稿或录音先优化画面与编排，不擅自改词。写完口播与 design.json 后、配音锁定后各运行一次 director_lint.py JOB：它按 2026 年的留存实践检查开场、长清单的分组与再钩、结尾与 AI 腔、音效克制，以及长清单的层级（地图、章节页、进度条、编号标题）和每页的表现形式（对比用表格、过程用流程图、等待用泳道……，见创作与分镜的“层级”和“表现形式”）。3.0 起它还看每页观众实际看到的：插画墨迹压进标题文字框（超过2%报错）、翻页后超过1秒只有白纸、整页只有字或一大片平涂、同一种表现形式连用超过3页或占大多数页；标题里已写出的数字不再要求配计数器，“以后”“半年前”这类时间词不当作对比。

1. 讲清因果。 确定受众、要解决的问题、机制、必要反例与行动，写入 design.json。改编文章先读全文，保留限定、署名与来源；时效或有争议的事实核实一手资料。用户给了稿子就改错不改意：只修事实错误和不顺口处，保留作者观点与有意的简化，篇幅增长不超过约20%，改动记入 script_changes。详见创作与分镜。
2. 开始时给可选项（原生，不弹网页）。 先问配置类型：模型推理（默认）或主动选择。模型推理：按内容写 options/defaults.json（默认比例 2:3、风格 inferred、pen-only、默认声、无广告水印），脚本直接完成。主动选择：用宿主原生选项或终端数字菜单逐项问 比例 → 风格（文字列表，无预览）→ 声音 → 字幕；每项最多60秒。风格列表不约束模型推理。揭示画风只能由用户明确接受（reveal_accepted）。广告/水印默认不加。详见可选制作设置。
3. 旁白先行，按段落生成。 先写完整口播稿，再按语义段落（每段不超过约100字，只在句末切）逐段生成；每段通过噪声门禁（嗡声、底噪、削波）才保留，不通过换种子重试；拼成母带时用实测停顿，并自动生成 alignment.json，不手写时间戳。本地 VoxCPM2 或 VoiceStudio 是主力；火山豆包、Gemini TTS 只在用户自己配置了密钥时作为选项。用户自带录音用 align.py 对齐。读法和写法分开：narration.say（全片）和句子的 say（单句）把字幕里的写法映射到配音读法，如 {"Grok": "格罗克", "70万": "七十万"}；字幕照原文显示，配音、识别核对和字幕计时都按读法（本地 VoxCPM2 不规范化数字，阿拉伯数字一律给读法）。配音前先跑 voxcpm_voice.py JOB --probe-terms：把每个英文词、数字放进它所在的小句单独试读两个种子，读不准的给出 say 建议（work/term-probe/report.json），不要等整段配音失败六次才发现。默认只在手写文字时加一层与笔尖同步的柔和笔声，描线和上色静音（audio.foley:false 关闭，{"scope":"all"} 让画画也发声），章节转场有一声很轻的合成纸声（普通转场静音、点睛音效默认关闭，audio.sfx:false 全关），背景音乐由导演按情绪决定：讲读、故事类片子可用一条内置合成纯器乐床 builtin:<情绪>（写 director_reason），全片一条到底、转场不断；用户自己的音乐须用户提供；构建自动循环接续、淡入淡出并随旁白压低（见声音与收尾）。详见连续旁白、声音与依赖、VoxCPM2 要点。
4. 分镜先算预算，再生图。 导演先在 design.json 写入 presentation.mode（picture_book / focus_diagram / dense_infographic / accumulating_board / step_sequence / narrative_comic）及 reason——这是密度导演，不是用户选项：儿童绘本单页少内容，知识科普/黑板报单页多内容或板书累积。板书模式先规划整页 boards 的区域位置、作用和 visual，再生图；同一块板必须在一张物理页面按阅读顺序逐项补齐，不每句话清场。再按句设计镜头，写 storyboard.json（同步 presentation）；密集信息图和板书每镜写 composition：布局、焦点 visual、至少两个辅助元素及其解释作用；同一幅图内的场景部位也可作为辅助元素，不用装饰凑数。运行 storyboard_lint.py JOB --budget，脚本按 mode 调整 hold、视觉数、每镜 hero 上限与画完停留。图按可用时间设计；约 3 倍人速画完就停。v3 引擎像人一样先起形、按模块由简到繁描线、擦掉起形、再按马克笔上色，默认画法（起形 + 马克笔上色）实测最短约每秒 3.9 笔；按部位上色、不起形或调高 speed 会更快，--budget 按每张图的实际画法给出 strokes_per_second，网页动效的视觉不占笔的时间。笔画和时长在长边不超过 720 px 的规划尺寸上计算（drawing.plan_side 可改），更大的图按显示尺寸清晰重渲染，所以图画大不会画得更慢，主图应画大：竖屏主图宽度通常占安全区的70%以上。用 layout_plan.py fit 取平台安全区内的版式落位（头部标题区、主图区、辅助区，避开顶部标签、底部账号/描述区和右侧按钮列），用 layout_plan.py probe JOB 图 --width W 实测该尺寸最少要画几秒，再决定图幅与窗口。笔忙占比受 mode 约束且不超过70%；已完成图片的静态阅读时间另行实测至少30%，不含片头空白和结尾静音，任意单幅停留不足1秒均警告。长片按章节推进，用 plan_status.py 找下一个镜头。
5. 出图：可画、可认、可分部位。 每次生图或改图前都执行美术指导（见下节）。先写 drawing-plan.json（主体、部位、顺序、identity_cues）并运行出图前检查。逐笔绘制的插画默认线稿先行：先出纯黑线稿，用 image_gate.py JOB 线稿 --plate 在上色前卡住预算（超了就让模型看图点名擦掉细节，编辑线稿），再以线稿为输入做上色编辑，line_first.py 配准后得到源图和 outline_mask，笔画的就是线稿里的每一条线（见线稿先行）。逐笔绘制的图要连续干净的墨线、部位交界闭合、平涂不加纹理线，复杂度符合档位，见可绘制约定。先做一张代表图，核对主体、构图和部位可分性，再扩展同片素材；新主题重新设计，修订本片或用户明确复用时保留已通过的图。常用道具、人物姿势、图标先查本机素材库 asset_library.py find --tags …，合适就 use 进本片（复用后仍要在本片里看图，把记录从 pending_review 改成 pass 并写证据）；本片新出且通过审核的通用素材可 add 进库。封面 AI 只出主视觉，准确标题用可编辑文字图层合成。出图后先运行 image_gate.py JOB 图 --visual <id>（几秒）：透明窟窿、光晕、线稿和规划尺寸下的绘制时长，不过就把它给出的 prompt_fix 加进提示词重新生成，不要带着问题往下做。再依次：看图填写叙事核对（咬伤、断裂、接触、得失等必须真实可见）；drawing_contract.py JOB --thumbnails 缩略图1秒内叫得出名字；lineart_gate.py 线稿门槛；part_grid.py JOB 图 出带 0.05 网格、物体框和色块编号的图，部位照着写方框 "box": [左, 上, 右, 下]（按绘制顺序，exclude_boxes 让给后画的部位），色块会整块归给占它最多的部位，不用描轮廓；region_marks.py 仍可看编号叠图。所有生成图执行 clean_image.py 隐私清理。line_first 的人物在 drawing-plan 里写 colours（skin/hair/clothing），上色提示词逐人写明；build 会实测头部肤色和躯干衣色。生图前用 storyboard_lint.py --budget 看两条预警：窗口装不下一个人、按常见图量会超出模式的笔忙上限。
6. 编排与代表段。 按运行格式写 job.json：动作带 visual，一个镜头通常是跨句的 visual_group，from_beat 让元素在对应句开始时起笔；镜头和转场逐镜设计，读运镜、转场与动效目录。镜头：命名运镜（推、拉、横移、hop、甩、砸入等），zoom 1–3 倍；页面素材按最大倍数生成，推近仍然清晰，适合"逐个推近讲解、最后拉远看全图"的大画板。转场共 22 种，选 1–2 种做全片招牌（翻页、板擦），其余用轻转场。元素可加 motion（强调、待机、退场、部位木偶）。页面可加网页动效层 overlays：大字、手绘图表、地图路线、形状接力、物理道具、转动的立体物件、手写公式；画板上的动效层出现时笔尖会描它一遍。元素和画板动效层可设视差 depth，镜头可用 dolly_zoom（希区柯克变焦）。只改镜头、转场、动效或位置时，已画好的素材从缓存复用，重建只需几秒。可画箭头 arrow、柱状图 bar_chart（只用真实数据）与滚动数字 counter。没写的部分由自动导演 direction 补上（自动推近不会把插画推进屏幕层标题，推不开就退回；笔在屏幕层卡片上写字的页保持静止镜头）；build 按密度规则提示镜头过度。build 同时报告最长无变化时长（竖屏超过8秒警告，画笔、镜头移动和强调动作都算变化）。中文按标准笔顺书写（GB2312 内汉字），其余字符按字形描线。字幕按字幕设计，收尾按声音与收尾。封面固定1秒：前0.5秒静止，后0.5秒渐隐进正在画的第一页，旁白在渐隐开始时（0.5秒）开口（cover.voice_overlap，0–0.5）。开场与每页的标题用 glyph_in（整字逐个出现），不用自上而下刷出的 mask_up；翻页后标题随页面到达（at: 0），进度条从第二页起 enter: "settled"，不让新页空着白纸。最后一句说完后，成图停留 ending.settle_seconds（默认2.5秒）再结束。先渲染覆盖文字、插画、上色、字幕与转场的代表段，其中至少一幅插画从头画到尾，按播放尺寸看，再渲染整片（默认多进程并行，11分钟竖屏约2.5分钟）。构建报告的 storyboard.composition.pages 给出实际图片与内容范围，排除近白/透明留白、字幕及底纹；主体太小先放大或补充相关场景，不靠多写标题填空。刻意留白需在该页每镜的 composition.negative_space_reason 写明讲解作用。判断标准是“像不像正在画”：先看画面怎样形成（笔尖带出线条、先轮廓后上色、没有整块显现、方向顺手），再看成图是否好看；出现碎线、飞白、灰斑就先改图，不要先批量出图。
7. 核对后交付。 build 先在旁白上检查字幕同步和字幕避让（插画像素不得压进字幕区），不等渲染后才发现；同时做取景检查：正在写、正在画的元素和板上动效出场时必须在画面里、不压字幕，否则自动让镜头等笔写完、补取景或拉远，修不了的写进警告，按警告改版式或时间；verify 对成片做工程检查、声音门禁与字幕同步复核；再按质量检查看画面与内容。连续播放和听音在 review.json 单独记录（continuous_playback、listening），没做就写 not_done 和原因，回执会把它列为未完成，不并进“通过”；不把解码、ASR 或文件存在说成观感保证。finalize 只接受与当前视频匹配的检查记录。用户拒绝成片时运行 handdraw_video.py reject JOB --reason "用户原话"：回执改为“用户已拒绝，需要返工”，这一版视频不能再 finalize。交付时告知：默认有笔声和转场音效、未加背景音乐；成片已写入 AI 生成隐式标识，发布时仍须在平台声明“AI 生成”。

构建和渲染会拒绝：未锁定旁白与时间戳、缺少 storyboard 或其检查失败、绘制窗口短于图像的 minimum_seconds、线稿门槛失败、部位不匹配或整人单块、声音门禁失败、检查记录过期。模型修正对应层后继续；偏好未选不触发这些门槛。脚本只核对结构、哈希、像素与声学指标，不能替代模型看图判断和真人试听。

制作工具包（片子只写数据）

新片不在 work/ 写脚本：口播 inputs/script.json（读法用 narration.say / 句子 say），出图 design/image-specs.json，画面 design/film.json，封面 design/cover.json；格式见制作工具包。

• art_pipeline.py JOB prompts | gen 名… [--edit] | record 名 "证据" | sync-minimums | review 笔记.json：简报自带本页绘制预算（口播秒数×70%×每秒约3.5笔）并要求按 2:3 竖屏构图，线稿先行、三张并行；已审核的图不改写提示词。
• codex_image.py：宿主没有生图工具时经 Codex CLI 出图（参考图先补边到所要画幅，只取本线程的图）。
• film_kit.py plan | measure | compile | at JOB …（如 film_kit.py at JOB p03b4 短语）：时刻都用口播提示 "@p03b4:短语"；页头默认随页面出现（glyph_in）；之后跑 storyboard_lint.py、director_lint.py。
• cover.py JOB：底图加可编辑文字图层，字体经 fonts.py 选。

所有生图必须先经过美术指导

每次调用生图或图片编辑工具前，完整读取并应用 dependencies/sweety-image-art-direction/GUIDE.md；这是用户对本项目的明确授权，不受它独立使用时“仅手动触发”的限制。封面、正文、角色、道具、新手部、候选、变体、局部修改和返工全部适用。库内画风保留完整配方；独立推理和自定义画风只用各自的风格说明。

先把本图简报（含分镜给出的绘制秒数和复杂度档位）与完整提示词存进任务目录，在美术记录登记 brief_file、prompt_file，运行 python scripts/art_direction.py bind-evidence <记录路径> 绑定哈希，再调用图像工具；禁止先出图再补记录。生成后实际看图，记录清理后哈希和视觉结论。缺记录、哈希失配、未通过看图或图片被替换，构建、渲染和交付都会停止。复用已验收且字节不变的素材可沿用原记录。

字幕唯一性是交付硬门槛

同一句旁白同一时刻只显示一份字幕：画面烘焙、字幕事件、MP4 字幕轨、网页 <track> 和播放器自动加载的字幕文件不能叠加。只从无字幕素材和独立字幕层重新合成；编辑用字幕只放 outputs/editing/。交付检查 MP4 无额外字幕轨、同目录无 SRT/ASS/VTT，并实际看解码画面的长句、换句和片尾，出现双字幕直接判 FAIL。

声音

目录有六款：逼真男声、逼真女声（原片参考，只在本机个人声音库，需先导入）和四款随包的合成声音——磁性解说男声（默认）、儒雅青年、温柔知性女声、悬疑故事解说。本机个人库里已验收的主力音色优先，用户本次的明确选择最优先。用户可添加任意数量的自定义声音：本人录音声明 consent: self，他人声音须获授权并声明 consent: authorized；参考在导入和每次使用时都要过门禁。不克隆公众人物、主播或平台音色，不用合成试听冒充原片音色。来源与授权见声音来源。不自动购买服务、下载模型、改全局引擎或交付无声片。

手部和广告

六款手臂：navy 深蓝袖马克笔、diamond-woman 碎钻长甲、child-pencil 儿童彩铅、waner-brush 上官婉儿灵感毛笔、teacher-pen 白衬衫中性笔、cardigan-fountain 针织袖钢笔；另有 pen-only：navy 同一支笔去掉手臂（角度、笔尖、尺度不变）。模型按内容选默认，锚点在 assets/hands/catalog.json。手臂按笔尖到手腕校准，裁切边留在画外。

hand.pen_text 只在笔杆加广告，最多16个字符，默认空，保持用户原文。watermark.text 生成低不透明度的文字水印，默认空：渲染时每页从四角和左右边缘的位置里挑墨迹最少的一处（插画、上色、文字和动效都算墨迹，不进字幕区），换位置时随翻页淡出淡入；最好的位置仍压墨超过6%时 verify 判失败，把该页的一角空出来（layout_plan.py zones 列出 watermark_corners）。watermark.position 可固定为某一角，legacy 恢复旧的浮动位置。参数见可选制作设置。

运行与边界

首次使用运行 scripts/setup.sh 安装依赖（macOS、Linux；Codex 与 Claude Code 均可）。scripts/handdraw_video.py 提供 doctor / build / render / verify / finalize / reject；doctor 列出可用的配音后端、字体覆盖和渲染条件，缺什么报告什么。任务数据放独立目录，不写入安装目录。手部、画风预览和合成声音随包分发；原片录音与个人声音库只存本机。

质量优先：工程门槛保证顺序与完整性，模型仍要审查语义分区、画风和叙事。真实手写自然度、情感和学习效果须分别评价。不承诺任意主题一次稳定生成，不发布视频、不开通服务、不改全局模型配置。