

video-scaffold · 功能说明
花时间正式出片之前,我能先确认分镜、词轴和画面是否对得上,找出缺词、文字越界、字抢在念到之前、动画没放完就退场这些问题,再听着旁白看动画。图文页可以先只读排出每页起止,或只出几张收尾关键帧;分镜路线有按词跳转的有声预览;独立网页作品有能拖进度、随时刷新的实时播放器,还能只出一小段来检查。第四套工具 docfilm 不靠浏览器检查:先用镜头单检查和一张“每个镜头开头、动作做完、结尾各一格”的联系表过目;拼整片之前,再从实际排版和动作记录导出全片文字时间表,查两层字叠在一起、片尾卡和字幕同屏、结尾淡黑、停留太短、出安全区或出卡出画等问题,有错默认不拼画面,只能一条一条写理由放行。每期用哪套工具或几套混用,按这一期画面和声音怎样做最好来定。
当前情况:四套工具的检查和预览都在源码里;最终转场、混音和成片仍需实际观看,这次网页核对没有打开任何预览。docfilm 的文字时间表关卡 10 月 28 日起才合进主线,这次只读了源码和说明,没有跑过,不能说已实测通过。
项目源码:私有仓库

video-scaffold · 功能说明
花时间正式出片之前,我能先确认分镜、词轴和画面是否对得上,找出缺词、文字越界、字抢在念到之前、动画没放完就退场这些问题,再听着旁白看动画。图文页可以先只读排出每页起止,或只出几张收尾关键帧;分镜路线有按词跳转的有声预览;独立网页作品有能拖进度、随时刷新的实时播放器,还能只出一小段来检查。第四套工具 docfilm 不靠浏览器检查:先用镜头单检查和一张“每个镜头开头、动作做完、结尾各一格”的联系表过目;拼整片之前,再从实际排版和动作记录导出全片文字时间表,查两层字叠在一起、片尾卡和字幕同屏、结尾淡黑、停留太短、出安全区或出卡出画等问题,有错默认不拼画面,只能一条一条写理由放行。每期用哪套工具或几套混用,按这一期画面和声音怎样做最好来定。
当前情况:四套工具的检查和预览都在源码里;最终转场、混音和成片仍需实际观看,这次网页核对没有打开任何预览。docfilm 的文字时间表关卡 10 月 28 日起才合进主线,这次只读了源码和说明,没有跑过,不能说已实测通过。
项目源码:私有仓库


用途与实际影响
静态看画面很难判断动画节奏,单元测试也看不出信息层级是否舒服;直接做完整视频又太慢。搭建检查、浏览器布局检查、关键帧和有声预览一起,形成一个低成本的人工关口。docfilm 的长片一段要渲好几分钟,叠字、片尾压字幕、日期配错这类错误如果等成片出来才看见,返工就得重渲;所以它在拼画面之前用排版时记下的真实文字框和出现时刻算一遍,几秒钟就能报出来,不用为检查再渲一遍画面。
我可以说:“先把这一期每页的起止排出来,再给我每页收尾的关键帧;有字抢在念到之前、或者标题越界的,都别出整片。”系统先交回时间表、关键帧和问题清单,长时间出片仍等确认。
做 docfilm 时可以说:“镜头单写完了,先出联系表给我看,合片前把文字时间表也查一遍。”系统给出每镜三格的联系表和检查提醒;合片前的文字检查报出“片尾卡出现时字幕还没退”这类错误就不拼画面。确实是设计要的,也只能对这一条写明理由放行。
得到每页时间表、关键帧或集中预览,以及问题清单。可以边听旁白边跳到重点词修改画面;这一步通过后仍需出片、合成并观看最终成片。docfilm 另得到一份分镜联系表、全片文字时间表(JSON 和能用表格软件打开的 CSV)和逐条列出问题、原因和出现次数的检查报告;报告写“查不了”的层不算查过。

用途与实际影响
静态看画面很难判断动画节奏,单元测试也看不出信息层级是否舒服;直接做完整视频又太慢。搭建检查、浏览器布局检查、关键帧和有声预览一起,形成一个低成本的人工关口。docfilm 的长片一段要渲好几分钟,叠字、片尾压字幕、日期配错这类错误如果等成片出来才看见,返工就得重渲;所以它在拼画面之前用排版时记下的真实文字框和出现时刻算一遍,几秒钟就能报出来,不用为检查再渲一遍画面。
我可以说:“先把这一期每页的起止排出来,再给我每页收尾的关键帧;有字抢在念到之前、或者标题越界的,都别出整片。”系统先交回时间表、关键帧和问题清单,长时间出片仍等确认。
做 docfilm 时可以说:“镜头单写完了,先出联系表给我看,合片前把文字时间表也查一遍。”系统给出每镜三格的联系表和检查提醒;合片前的文字检查报出“片尾卡出现时字幕还没退”这类错误就不拼画面。确实是设计要的,也只能对这一条写明理由放行。
得到每页时间表、关键帧或集中预览,以及问题清单。可以边听旁白边跳到重点词修改画面;这一步通过后仍需出片、合成并观看最终成片。docfilm 另得到一份分镜联系表、全片文字时间表(JSON 和能用表格软件打开的 CSV)和逐条列出问题、原因和出现次数的检查报告;报告写“查不了”的层不算查过。

缺页、踩点、文字时序和可确定的越界都已处理,人也看过关键帧或预览,才进入正式出片。docfilm 是镜头单检查没有报错、联系表看过,文字时间表没有未放行的错误;pass 只代表已描述文字框的那些层。
字比念到早、动画没放完就退场会被拦下;静止太久只提示。画面是否拥挤或好看仍要在动态预览里判断,改完重新搭建再看。docfilm 的文字检查报错时默认不拼画面:改镜头单重新生成,或对确实要保留的那一条写问题编号和非空理由放行,放行后问题和理由仍留在报告里;没有一次放行全部或用配置关掉检查的办法。“今天”“现在”这类相对时间词、淡入淡出时的擦边只提醒不挡。
浏览器、字体、图片没就绪或页面脚本出错时检查直接失败;缺背景时临时预览可能继续,但正式出片不能开始。docfilm 遇到没报文字框的旧自绘层、没给原件正文框或缺事件表,报告明确写“查不了”,只提醒、不猜边框,也不为补这个事实去启动识字(OCR);没声明片尾卡时单独提醒查不了片尾和末字幕。

缺页、踩点、文字时序和可确定的越界都已处理,人也看过关键帧或预览,才进入正式出片。docfilm 是镜头单检查没有报错、联系表看过,文字时间表没有未放行的错误;pass 只代表已描述文字框的那些层。
字比念到早、动画没放完就退场会被拦下;静止太久只提示。画面是否拥挤或好看仍要在动态预览里判断,改完重新搭建再看。docfilm 的文字检查报错时默认不拼画面:改镜头单重新生成,或对确实要保留的那一条写问题编号和非空理由放行,放行后问题和理由仍留在报告里;没有一次放行全部或用配置关掉检查的办法。“今天”“现在”这类相对时间词、淡入淡出时的擦边只提醒不挡。
浏览器、字体、图片没就绪或页面脚本出错时检查直接失败;缺背景时临时预览可能继续,但正式出片不能开始。docfilm 遇到没报文字框的旧自绘层、没给原件正文框或缺事件表,报告明确写“查不了”,只提醒、不猜边框,也不为补这个事实去启动识字(OCR);没声明片尾卡时单独提醒查不了片尾和末字幕。

图文页:python -m pipeline.pages <表.json> plan 排出每页起止并做文字时序检查,stills [秒数] 出关键帧。分镜路线:保存片段后运行 run.ps1 build、lint、preview。独立网页作品:webfilm/ 打开实时播放器,stills --at … 出关键帧,render --start … --end … 只出一段。图文页的 plan 加 --all 能一次把所有页的错列全;stills 加 --sheet 另出按时间排好的 3×4 小样表。docfilm:python -X utf8 docfilm/ 检查镜头单(平时不出片;用了清水印的原件时会写识字图片和缓存,并调用本机文字识别),board <镜头单.json> 出分镜联系表;python -X utf8 -m docfilm.timeline_check <分段表.json> 不渲染、只跑文字关卡(不占显卡,但会导出文字表和报告),assemble build 合片前也会自动跑。
- 要检查的分镜表、工程或网页作品
- 听看后需要修改的画面或节奏
- docfilm 另要镜头单、生成好的分段表,以及(需要查日期时)本期的事件表


图文页:python -m pipeline.pages <表.json> plan 排出每页起止并做文字时序检查,stills [秒数] 出关键帧。分镜路线:保存片段后运行 run.ps1 build、lint、preview。独立网页作品:webfilm/ 打开实时播放器,stills --at … 出关键帧,render --start … --end … 只出一段。图文页的 plan 加 --all 能一次把所有页的错列全;stills 加 --sheet 另出按时间排好的 3×4 小样表。docfilm:python -X utf8 docfilm/ 检查镜头单(平时不出片;用了清水印的原件时会写识字图片和缓存,并调用本机文字识别),board <镜头单.json> 出分镜联系表;python -X utf8 -m docfilm.timeline_check <分段表.json> 不渲染、只跑文字关卡(不占显卡,但会导出文字表和报告),assemble build 合片前也会自动跑。
- 要检查的分镜表、工程或网页作品
- 听看后需要修改的画面或节奏
- docfilm 另要镜头单、生成好的分段表,以及(需要查日期时)本期的事件表


这里保留实现、关键条件、精确入口、历史记录和验证结果。
图文页时间表与关键帧(含 plan --all 和 stills --sheet)、分镜搭建与布局阻断、有声预览、网页作品实时预览与局部出片已在源码中;本次未运行(内容核对到北京时间 2026-10-22 01:25 的最后一次提交 626774f,10 月 22 日 06:47 读);docfilm 的镜头单检查、分镜联系表和文字时间表关卡按北京时间 10 月 31 日 14:19 最后一次提交 3c1c117 的源码和说明核对(11 月 4 日),这次也没有运行


workflow.stage_build全链保留 01、04、100 等真实稀疏编号,脚本、片段、词轴与时长必须一一对应,不按数量相等猜配对;任何未解析的触发词都使整个阶段失败。
lint.py用 Playwright 采样 0 秒、末帧,以及每个动画的开始、中点和结束,并收集去重后的元素边界;浏览器、字体、图片或运行时没就绪、或脚本出错就失败。完全出画布的元素或被切到的文字算硬错误;图片或形状部分出血、偏离安全区通常是软提示。容差:硬错误 3 像素,软提示 8 像素。
- 图文页
plan只读返回每页起止、元素和成片秒数,同时做逐字和退场检查,不生成背景、不抽录屏帧;录音缓存缺失或失效时只提示先 align,贴屏合成未生成时用同分辨率场景原图代替检查布局(不代表合成通过)。plan --all逐页收集构建错误,一次列出页号、say 摘要、起止秒和错误原文,有错返回非零;表本身或词轴加载失败仍直接报错。不加 --all 沿用原行为。
stills输出指定秒数或每页收尾的关键帧,它会生成素材和画面并进入出片排队,所以不是只读;stills --sheet [秒 ...]另在work/输出按时间排序的小样表,每张 3 列 × 4 行、每格 640×360、上方 24 像素标签栏写序号和秒数,整表 1920×1536。启用录音或整句字幕写法的表,stills 抽帧烧录字幕;旧表保持原抽帧方式。用了 redact 的页,plan 和 stills 都在 work/redactions/ 生成打码前后对照图并列出路径。sheets/ sNN.png
- 图文页拒绝“字早于念到”和“动画没放完就退场”,重现前文原话也要求原话已完整念过,静止超过 3.5 秒提示。已明确审定的元素可用
hold_check:"warn"只提示,配preserve_svg:true保留实际 SVG 字节,检查只用验证副本。
preview.py优先从真实 4K 背景抽一帧,为每场建独立格子;背景不存在时用纯色后备,不伪装真实背景验收。预览绑定音频与真实词轴,可拖动、按词定位、切场和暂停;改踩点只导出新片段。不加--open只生成文件,--open/serve 才通过受控本机端口打开。

这里保留实现、关键条件、精确入口、历史记录和验证结果。
图文页时间表与关键帧(含 plan --all 和 stills --sheet)、分镜搭建与布局阻断、有声预览、网页作品实时预览与局部出片已在源码中;本次未运行(内容核对到北京时间 2026-10-22 01:25 的最后一次提交 626774f,10 月 22 日 06:47 读);docfilm 的镜头单检查、分镜联系表和文字时间表关卡按北京时间 10 月 31 日 14:19 最后一次提交 3c1c117 的源码和说明核对(11 月 4 日),这次也没有运行


workflow.stage_build全链保留 01、04、100 等真实稀疏编号,脚本、片段、词轴与时长必须一一对应,不按数量相等猜配对;任何未解析的触发词都使整个阶段失败。
lint.py用 Playwright 采样 0 秒、末帧,以及每个动画的开始、中点和结束,并收集去重后的元素边界;浏览器、字体、图片或运行时没就绪、或脚本出错就失败。完全出画布的元素或被切到的文字算硬错误;图片或形状部分出血、偏离安全区通常是软提示。容差:硬错误 3 像素,软提示 8 像素。
- 图文页
plan只读返回每页起止、元素和成片秒数,同时做逐字和退场检查,不生成背景、不抽录屏帧;录音缓存缺失或失效时只提示先 align,贴屏合成未生成时用同分辨率场景原图代替检查布局(不代表合成通过)。plan --all逐页收集构建错误,一次列出页号、say 摘要、起止秒和错误原文,有错返回非零;表本身或词轴加载失败仍直接报错。不加 --all 沿用原行为。
stills输出指定秒数或每页收尾的关键帧,它会生成素材和画面并进入出片排队,所以不是只读;stills --sheet [秒 ...]另在work/输出按时间排序的小样表,每张 3 列 × 4 行、每格 640×360、上方 24 像素标签栏写序号和秒数,整表 1920×1536。启用录音或整句字幕写法的表,stills 抽帧烧录字幕;旧表保持原抽帧方式。用了 redact 的页,plan 和 stills 都在 work/redactions/ 生成打码前后对照图并列出路径。sheets/ sNN.png
- 图文页拒绝“字早于念到”和“动画没放完就退场”,重现前文原话也要求原话已完整念过,静止超过 3.5 秒提示。已明确审定的元素可用
hold_check:"warn"只提示,配preserve_svg:true保留实际 SVG 字节,检查只用验证副本。
preview.py优先从真实 4K 背景抽一帧,为每场建独立格子;背景不存在时用纯色后备,不伪装真实背景验收。预览绑定音频与真实词轴,可拖动、按词定位、切场和暂停;改踩点只导出新片段。不加--open只生成文件,--open/serve 才通过受控本机端口打开。

- 网页作品
preview有播放、重播、拖进度和刷新作品;--narration <已有音频>让作品和声音共用一个时钟,不调用配音;--no-open只返回本地预览地址,Ctrl+C 停止。
- 网页作品
stills --at …给原画幅 PNG、带秒数的拼图和来源记录;render --start … --end …只出原作品绝对时间里的一段,起止必须落在 60fps 的帧边界,片段是“含起点、不含终点”;互动脚本会先重放前段动作,所以仍需相应时间。
pipeline.page_compare snapshot/为已审定画面生成整页和元素片段,逐字节列差异,认不出的元素记“无法比较”。现在默认扫描任意影片目录里的分镜表,也可只列出已通过的表;本次只核对了实现,没有实际比较。compare
- docfilm
shotlist check检查锚点、素材登记与打码框、时间顺序和信息层排不排得下,多样性和“字不在文稿里”只作提醒;board给每个镜头在开头、动作做完、结尾各出一张定格拼成联系表。check不能一概当成不写文件的入口:原件写了clean: "watermark"时,它会创建识字图片和缓存、调用 LocalOCR。这是编译阶段只看选定原件的条件检查,和 filmcheck 对成片跑的 OCR 是两回事;release 的 filmcheck 默认只跑 visual、audio,成片 OCR 要另跑。
- docfilm 文字时间表关卡(
docfilm.timeline_check,assemble build合片前自动跑)从框架字幕、HUD、通话和短信卡、卡片出字、放大条等实际排版读文字框,运动文字按每个成片帧的实际位置比。默认检查:两层文字完全显示时任意一帧相交就报错;插入段和片尾卡占屏时不能有字幕;全片结尾必须淡黑且至少 0.5 秒;放大条、标签、卡片完整停留至少 1.5 秒(重点放大条 2.5 秒);普通文字留 5% 安全区,文字不能出卡出画;系列配置可要求顶栏日期在事件表里、不是出片当天,并拦不该上屏的字。每次在成片旁的检查目录导出文字时间表 JSON、CSV 和检查结果,只保留最近五次,所以单跑它虽然不渲染、不占显卡,也不是不写文件。
- 放行用
--waive-text 问题ID=理由(单独检查时叫--waive),一次只认当前报告里的一个错误编号、理由不能为空;编号按规则、镜号、层名和实际文字算,改无关字幕或重排时间不会让放行失效,改了相关文字就要重新核对。同一问题重复出现时保留每次的时间和证据,并记出现次数;拼错、过期或拿提醒当错误放行都会被拒绝。成片已存在且没加--force时,build 在关卡前就拒绝运行,不动旧成片和旧清单。


- 网页作品
preview有播放、重播、拖进度和刷新作品;--narration <已有音频>让作品和声音共用一个时钟,不调用配音;--no-open只返回本地预览地址,Ctrl+C 停止。
- 网页作品
stills --at …给原画幅 PNG、带秒数的拼图和来源记录;render --start … --end …只出原作品绝对时间里的一段,起止必须落在 60fps 的帧边界,片段是“含起点、不含终点”;互动脚本会先重放前段动作,所以仍需相应时间。
pipeline.page_compare snapshot/为已审定画面生成整页和元素片段,逐字节列差异,认不出的元素记“无法比较”。现在默认扫描任意影片目录里的分镜表,也可只列出已通过的表;本次只核对了实现,没有实际比较。compare
- docfilm
shotlist check检查锚点、素材登记与打码框、时间顺序和信息层排不排得下,多样性和“字不在文稿里”只作提醒;board给每个镜头在开头、动作做完、结尾各出一张定格拼成联系表。check不能一概当成不写文件的入口:原件写了clean: "watermark"时,它会创建识字图片和缓存、调用 LocalOCR。这是编译阶段只看选定原件的条件检查,和 filmcheck 对成片跑的 OCR 是两回事;release 的 filmcheck 默认只跑 visual、audio,成片 OCR 要另跑。
- docfilm 文字时间表关卡(
docfilm.timeline_check,assemble build合片前自动跑)从框架字幕、HUD、通话和短信卡、卡片出字、放大条等实际排版读文字框,运动文字按每个成片帧的实际位置比。默认检查:两层文字完全显示时任意一帧相交就报错;插入段和片尾卡占屏时不能有字幕;全片结尾必须淡黑且至少 0.5 秒;放大条、标签、卡片完整停留至少 1.5 秒(重点放大条 2.5 秒);普通文字留 5% 安全区,文字不能出卡出画;系列配置可要求顶栏日期在事件表里、不是出片当天,并拦不该上屏的字。每次在成片旁的检查目录导出文字时间表 JSON、CSV 和检查结果,只保留最近五次,所以单跑它虽然不渲染、不占显卡,也不是不写文件。
- 放行用
--waive-text 问题ID=理由(单独检查时叫--waive),一次只认当前报告里的一个错误编号、理由不能为空;编号按规则、镜号、层名和实际文字算,改无关字幕或重排时间不会让放行失效,改了相关文字就要重新核对。同一问题重复出现时保留每次的时间和证据,并记出现次数;拼错、过期或拿提醒当错误放行都会被拒绝。成片已存在且没加--force时,build 在关卡前就拒绝运行,不动旧成片和旧清单。



| 名词 | 意思 |
|---|---|
| HARD finding(硬错误) | 采样时刻发现完全出画布的元素、被切到的文字,或运行时检查失败;必须修好才能继续。 |
| preview(动态预览) | 浏览器里的有声审阅入口,支持时间控制和词语定位;不是最终合成视频,也不替代完整混音与转场验收。 |
| stable frame(稳定检查帧) | 布局检查取的确定时刻:0 秒、末帧和每个动画的开始、中点、结束;它们仍不能覆盖每一帧和全部审美问题。 |

先在几秒到几分钟内看全画面,别等长时间出片后才发现硬错误。
解决什么
防止低成本就能发现的问题拖到昂贵的出片之后,也防止把预览页或一段局部片段误当最终成片。



先在几秒到几分钟内看全画面,别等长时间出片后才发现硬错误。
解决什么
防止低成本就能发现的问题拖到昂贵的出片之后,也防止把预览页或一段局部片段误当最终成片。

- 布局检查主要阻断可确定的越界和文字时序问题,不自动判断全部美感。
- 全出血图片等软提示要结合设计意图,不机械判失败。
- plan --all、stills --sheet、录音和整句字幕的烧录抽帧都是 10 月 21 日新加的,只在自动测试里跑过,没有新的人审或出片成功证据。打码对照图含原图,只供核对,不能当已打码素材。
- 这次网页核对没有打开任何预览、没有观察动效,也没有重新出关键帧;本期影片已审定是制作记录,不是这次预览的结果。页面比较器现在可扫描任意影片目录,本次没有实际运行,不把没识别到的元素写成相同。
- docfilm 文字关卡的 pass 只覆盖报了文字框的层:原件照片和生成图片里的字要创作方给文字层或正文框,框架不会替它识字;只给日期白名单也推断不了“这个日期配的是不是这件事”,仍要人对着文字时间表核对。它是 10 月 28 日起才合进主线的,这次只读源码和说明,没有在真实片子上跑过;自动检查通过也不替代主持观看和本人审定。
--waive-text 问题ID=理由,没有批量放行。
- 布局检查主要阻断可确定的越界和文字时序问题,不自动判断全部美感。
- 全出血图片等软提示要结合设计意图,不机械判失败。
- plan --all、stills --sheet、录音和整句字幕的烧录抽帧都是 10 月 21 日新加的,只在自动测试里跑过,没有新的人审或出片成功证据。打码对照图含原图,只供核对,不能当已打码素材。
- 这次网页核对没有打开任何预览、没有观察动效,也没有重新出关键帧;本期影片已审定是制作记录,不是这次预览的结果。页面比较器现在可扫描任意影片目录,本次没有实际运行,不把没识别到的元素写成相同。
- docfilm 文字关卡的 pass 只覆盖报了文字框的层:原件照片和生成图片里的字要创作方给文字层或正文框,框架不会替它识字;只给日期白名单也推断不了“这个日期配的是不是这件事”,仍要人对着文字时间表核对。它是 10 月 28 日起才合进主线的,这次只读源码和说明,没有在真实片子上跑过;自动检查通过也不替代主持观看和本人审定。
--waive-text 问题ID=理由,没有批量放行。
- 阶段前置关系与编号/cue 阻断
- 真实浏览器布局检查
- 全场景动态预览
- 图文页一次列全错(plan --all)与小样表(stills --sheet)
- 回归覆盖页次数字顺序、预览时长配对和浏览器失败阻断;plan --all 和小样表另有 test_pages_tools.py;626774f 源码共有 267 个测试定义(全项目),这次没有运行。
- 2026-09-18 21:02 的静态 doctor 没有启动浏览器;源码里的隔离 smoke 覆盖真实 HTTP、有声控制与片段导出,之后没有重新运行。
- 独立网页作品 2026-10-04 的 73.2 秒彩排有它自己的回执(不是正式发布、未经人耳试听);这次只重读了回执,没有重播。
场景制作给出可检查的输入;本模块决定是否值得开始正式出片,出片模块仍要独立核对帧数与续作身份。

- 阶段前置关系与编号/cue 阻断
- 真实浏览器布局检查
- 全场景动态预览
- 图文页一次列全错(plan --all)与小样表(stills --sheet)
- 回归覆盖页次数字顺序、预览时长配对和浏览器失败阻断;plan --all 和小样表另有 test_pages_tools.py;626774f 源码共有 267 个测试定义(全项目),这次没有运行。
- 2026-09-18 21:02 的静态 doctor 没有启动浏览器;源码里的隔离 smoke 覆盖真实 HTTP、有声控制与片段导出,之后没有重新运行。
- 独立网页作品 2026-10-04 的 73.2 秒彩排有它自己的回执(不是正式发布、未经人耳试听);这次只重读了回执,没有重播。
场景制作给出可检查的输入;本模块决定是否值得开始正式出片,出片模块仍要独立核对帧数与续作身份。
复制 AI 续作说明
项目:把编号、踩点和越界问题拦在长渲染之前;仓库:页面未提供仓库地址;范围:整个项目;目标:(这里写这次要做的事)。先读项目的 AGENTS.md 和说明,按现行规则做。
把“目标”换成这次要做的事,整段复制给 AI。







