

video-scaffold · 功能说明
我可以分多次完成一条视频:已确认的旁白、时间轴和合格的出片片段不必每次重做。但脚本、音频、画面、素材或设置变了,系统能指出旧结果已经不属于当前版本;清理分两种:分镜路线要明确说了才清,只把认识的可再生文件移进回收站,脚本、时间轴、画面源和成品都留下;docfilm 出片全部通过后自动直接删掉能重渲的段和中间文件,不进回收站,报告、联系表和比帧证据留下。独立网页作品另有自己的断点缓存和声音母带,已审定的图文页画面还有防止被改坏的比对。docfilm 的一条命令出片(release)另有一套按版本滚动的复用:每段按时间窗、镜头、素材、字幕、信息层、设置和画面代码记指纹,下一版从本期分段和这部片最近一次成功出片里找指纹相同的段直接用;失败的尝试留在检查目录可以接着做,新版全部通过后才清掉上一版的段缓存。它只是本期目录里的文件,不是另起的后台服务。
当前情况:错误复用旧产物的问题已修复;分镜路线的清理改成移进回收站,不再永久删除;docfilm 出片后的自动清理直接删除,只碰能重渲的文件。这次网页核对没有运行任何恢复路径。docfilm 的滚动复用北京时间 10 月 29 日才合进主线,这次只读了源码和说明,没有跑过,不能说已实测通过。
项目源码:私有仓库

video-scaffold · 功能说明
我可以分多次完成一条视频:已确认的旁白、时间轴和合格的出片片段不必每次重做。但脚本、音频、画面、素材或设置变了,系统能指出旧结果已经不属于当前版本;清理分两种:分镜路线要明确说了才清,只把认识的可再生文件移进回收站,脚本、时间轴、画面源和成品都留下;docfilm 出片全部通过后自动直接删掉能重渲的段和中间文件,不进回收站,报告、联系表和比帧证据留下。独立网页作品另有自己的断点缓存和声音母带,已审定的图文页画面还有防止被改坏的比对。docfilm 的一条命令出片(release)另有一套按版本滚动的复用:每段按时间窗、镜头、素材、字幕、信息层、设置和画面代码记指纹,下一版从本期分段和这部片最近一次成功出片里找指纹相同的段直接用;失败的尝试留在检查目录可以接着做,新版全部通过后才清掉上一版的段缓存。它只是本期目录里的文件,不是另起的后台服务。
当前情况:错误复用旧产物的问题已修复;分镜路线的清理改成移进回收站,不再永久删除;docfilm 出片后的自动清理直接删除,只碰能重渲的文件。这次网页核对没有运行任何恢复路径。docfilm 的滚动复用北京时间 10 月 29 日才合进主线,这次只读了源码和说明,没有跑过,不能说已实测通过。
项目源码:私有仓库


用途与实际影响
只靠“文件存在”复用会静默混入旧内容;完全不复用又要把网络、识别和长时间出片全部重来。最小身份文件记录输入设置与 SHA-256,不保存正文和密钥,也能把真正相同和只是同名分开。docfilm 的长片一版要返工好几轮,每轮都整片重渲太慢;但新版直接拿旧版的段,又怕新写入改到旧版本的文件。所以它按指纹认段,用硬链接省空间,写之前先断开链接。
我可以说:“明天接着做:没变的旁白继续用,第二页换图后重出;清理今天的临时片段,但保留时间轴和画面。”这是分镜路线的清理:系统只把能重建的东西移进回收站,留下继续制作所需的材料;回收失败就整次停下并列出残留。
做 docfilm 时我可以说:“v3 只改了第 12 镜的标签,出片吧。”程序在本期分段和 v2 的成功出片里找指纹没变的段直接用,只重渲画面真的变了的那一段;中途某一步失败,就用同一条命令重试,已渲好的段不白做。全部通过后,上一版的段缓存和这次的中间文件自动删掉,不用我确认,也不进回收站。
没变的旁白、时间轴和画面片段可以继续用;变化的部分标明重做。分镜路线清理前可以先看清单,脚本、画面源和最终成品留下,被清理的也还在回收站里。docfilm 每次出片的清单写明输入指纹、框架版本和源码摘要,哪些段沿用、哪些重渲;成功后只留最近一版的段缓存,帧日志、报告、联系表和比帧证据留下;自动删掉的段不在回收站里,要用时按镜头单重渲。同一成片的检查目录只留最近五次,更早的连报告一起删。

用途与实际影响
只靠“文件存在”复用会静默混入旧内容;完全不复用又要把网络、识别和长时间出片全部重来。最小身份文件记录输入设置与 SHA-256,不保存正文和密钥,也能把真正相同和只是同名分开。docfilm 的长片一版要返工好几轮,每轮都整片重渲太慢;但新版直接拿旧版的段,又怕新写入改到旧版本的文件。所以它按指纹认段,用硬链接省空间,写之前先断开链接。
我可以说:“明天接着做:没变的旁白继续用,第二页换图后重出;清理今天的临时片段,但保留时间轴和画面。”这是分镜路线的清理:系统只把能重建的东西移进回收站,留下继续制作所需的材料;回收失败就整次停下并列出残留。
做 docfilm 时我可以说:“v3 只改了第 12 镜的标签,出片吧。”程序在本期分段和 v2 的成功出片里找指纹没变的段直接用,只重渲画面真的变了的那一段;中途某一步失败,就用同一条命令重试,已渲好的段不白做。全部通过后,上一版的段缓存和这次的中间文件自动删掉,不用我确认,也不进回收站。
没变的旁白、时间轴和画面片段可以继续用;变化的部分标明重做。分镜路线清理前可以先看清单,脚本、画面源和最终成品留下,被清理的也还在回收站里。docfilm 每次出片的清单写明输入指纹、框架版本和源码摘要,哪些段沿用、哪些重渲;成功后只留最近一版的段缓存,帧日志、报告、联系表和比帧证据留下;自动删掉的段不在回收站里,要用时按镜头单重渲。同一成片的检查目录只留最近五次,更早的连报告一起删。

旧文件的来源和内容仍与当前工程一致,才复用或接着做。
来源说明缺失或内容变动时,指出哪一层过期;旁白先等本人确认,画面只重做可再生的片段。docfilm 出片后的自动清理有文件删不掉时,只记一条提醒,已经成功的出片不改成失败。
必要素材丢失、旧错误片段没法确认已移进回收站、或新结果没完整写出时停止,不把半成品登记为可复用;分镜路线的清理在新电脑缺回收助手时明确报不可用,不去下载别的脚本,也不永久删除。

旧文件的来源和内容仍与当前工程一致,才复用或接着做。
来源说明缺失或内容变动时,指出哪一层过期;旁白先等本人确认,画面只重做可再生的片段。docfilm 出片后的自动清理有文件删不掉时,只记一条提醒,已经成功的出片不改成失败。
必要素材丢失、旧错误片段没法确认已移进回收站、或新结果没完整写出时停止,不把半成品登记为可复用;分镜路线的清理在新电脑缺回收助手时明确报不可用,不去下载别的脚本,也不永久删除。

视频工程中断或内容变动时,直接重跑对应阶段;想清理时先用 cleanup --dry-run 看清单,再明确执行清理(这是分镜路线的清理,进回收站;docfilm 出片后的清理是自动的,不用跑这条,也不进回收站)。docfilm:出片失败后原样重跑同一条 python -m docfilm.release <分段表.json> --tag <版本> … 就能续上;想先知道哪些段沿用、哪些要重渲,用只读的 python -X utf8 -m docfilm.assemble plan <分段表.json>。
- 要继续的工程与中断或修改的位置
- 是否明确重做声音,或清理可再生文件
- docfilm 另要本期分段表和同一出片目录(上一版成功出片的清单在那里)


视频工程中断或内容变动时,直接重跑对应阶段;想清理时先用 cleanup --dry-run 看清单,再明确执行清理(这是分镜路线的清理,进回收站;docfilm 出片后的清理是自动的,不用跑这条,也不进回收站)。docfilm:出片失败后原样重跑同一条 python -m docfilm.release <分段表.json> --tag <版本> … 就能续上;想先知道哪些段沿用、哪些要重渲,用只读的 python -X utf8 -m docfilm.assemble plan <分段表.json>。
- 要继续的工程与中断或修改的位置
- 是否明确重做声音,或清理可再生文件
- docfilm 另要本期分段表和同一出片目录(上一版成功出片的清单在那里)


这里保留实现、关键条件、精确入口、历史记录和验证结果。
陈旧复用的根因已修复;分镜路线的清理改为回收站,网页作品缓存与母带复用已在源码中,本次未运行(内容截止北京时间 2026-10-11 14:00,提交 cc41e514);docfilm 出片的分段指纹与滚动复用按北京时间 10 月 31 日 14:19 最后一次提交 3c1c117 的源码和说明核对(11 月 4 日),这次也没有运行


artifact_identity.py提供 SHA-256、容错读取、同目录原子 JSON 写入和输出哈希回验,没有数据库、服务或监视进程;新增 Python 代码指纹,只改注释、排版、docstring 不会让媒体过期,实际代码变化仍会过期;同一轮内的文件哈希只在内存里复用,大小、时间或身份变了就重读,结束即丢弃。
audio_NN.identity.json绑定有效脚本文本、Fish 端点/模型/声线/格式、尾静音和 MP3 输出。
timing_NN.identity.json绑定音频、已确认文案、实际词轴来源与输出;Fish 原生时间和 ChineseASR 对齐明确区分,旧有效 Whisper 身份只用于兼容读取。
durations.json.identity.json绑定数字顺序的音频名称与哈希以及时长表输出;workflow 读取时再次核对。
- 出片身份覆盖画面、素材、背景、时长、画布、转场、效果、编码和分段边界,逐段回验输出 SHA;来源变化按实际影响作废片段,成功片段保留到明确清理。旧输出没有代码指纹时可能重建可再生画面,但不会因此重新配音。
- docfilm 每段按实际渲染窗(含前后把手)记指纹:时间窗、窗里的镜头和已解析的时间锚点、用到的素材内容(含原件图和打码框)、字幕和角标、逐帧实际叠上的信息层、全片设置、画面代码及依赖版本;渲染成功才在视频旁写
.fingerprint.json,build遇到缺少或不匹配的指纹就要求先重渲。

这里保留实现、关键条件、精确入口、历史记录和验证结果。
陈旧复用的根因已修复;分镜路线的清理改为回收站,网页作品缓存与母带复用已在源码中,本次未运行(内容截止北京时间 2026-10-11 14:00,提交 cc41e514);docfilm 出片的分段指纹与滚动复用按北京时间 10 月 31 日 14:19 最后一次提交 3c1c117 的源码和说明核对(11 月 4 日),这次也没有运行


artifact_identity.py提供 SHA-256、容错读取、同目录原子 JSON 写入和输出哈希回验,没有数据库、服务或监视进程;新增 Python 代码指纹,只改注释、排版、docstring 不会让媒体过期,实际代码变化仍会过期;同一轮内的文件哈希只在内存里复用,大小、时间或身份变了就重读,结束即丢弃。
audio_NN.identity.json绑定有效脚本文本、Fish 端点/模型/声线/格式、尾静音和 MP3 输出。
timing_NN.identity.json绑定音频、已确认文案、实际词轴来源与输出;Fish 原生时间和 ChineseASR 对齐明确区分,旧有效 Whisper 身份只用于兼容读取。
durations.json.identity.json绑定数字顺序的音频名称与哈希以及时长表输出;workflow 读取时再次核对。
- 出片身份覆盖画面、素材、背景、时长、画布、转场、效果、编码和分段边界,逐段回验输出 SHA;来源变化按实际影响作废片段,成功片段保留到明确清理。旧输出没有代码指纹时可能重建可再生画面,但不会因此重新配音。
- docfilm 每段按实际渲染窗(含前后把手)记指纹:时间窗、窗里的镜头和已解析的时间锚点、用到的素材内容(含原件图和打码框)、字幕和角标、逐帧实际叠上的信息层、全片设置、画面代码及依赖版本;渲染成功才在视频旁写
.fingerprint.json,build遇到缺少或不匹配的指纹就要求先重渲。

- 清理名单:_concat.txt、_audio_list.txt、_main_audio.mp3/.wav、_render_identity.json、规范的分片文件及其身份;默认保留词轴和场景 HTML,可显式选择清理对应可再生项。原件、未知文件和最终成品不动,失败列出残留并整次失败。这是分镜路线
cleanup的名单,docfilm 的自动清理见本屏最后一条。
- 回收助手:Windows 用已审核的 PowerShell 回收脚本,
VIDEO_RECYCLE_TOOL显式指定的绝对路径优先,未配置时只兼容基座现有的回收工具;显式路径无效不自动回退。助手必须返回“已回收”且原路径消失才算成功,超时报告“不确定”、不自动重试;Linux/macOS 用 Send2Trash。
- 独立网页作品:
.webfilm-cache保存完整成功的段(每段最长 2 秒),损坏就重建;.mp4.wav声音母带在同一作品、动作、画幅和 Chrome 且字节核验有效时复用,源码或素材变了就过期。同源母带复用是本期成果复用,不是云缓存或共享数据库,也不承诺两次独立冷启动的浮点音频逐位一样。
- 已审定画面保护:共用版式变化时可用 page_compare 逐字节对照整页和元素 SVG,认不出的记“无法比较”;已审定元素按 hold_check/preserve_svg 兼容,不能暗改已通过的画面。比对器现在可扫描任意影片的分镜表目录,也可只列已通过的表。
- docfilm 出片滚动复用:上一版默认取同一出片目录里同一镜头单、结论为通过的最近一份出片清单;本期分段和它保留的段里,同编号且指纹相同、视频完好的段先硬链接,跨盘才复制,写入前先断开链接,不会改到旧版本的文件。新版全部通过后,直接删除(unlink,不走回收站)本次检查目录的合并中间文件和下一版用不上的段,以及上一版检查目录里有脚本的段和合并中间文件;外部插入视频不动,路径不在检查目录里就报错不删。同一成片的检查目录只保留最近五次自动命名的,更早的整目录删除(rmtree),认不出的其他文件不清理。删除失败写进 warnings 和 cleanup.errors,不把已成功的出片改成失败。清单另记输入哈希、框架提交和源码摘要。


- 清理名单:_concat.txt、_audio_list.txt、_main_audio.mp3/.wav、_render_identity.json、规范的分片文件及其身份;默认保留词轴和场景 HTML,可显式选择清理对应可再生项。原件、未知文件和最终成品不动,失败列出残留并整次失败。这是分镜路线
cleanup的名单,docfilm 的自动清理见本屏最后一条。
- 回收助手:Windows 用已审核的 PowerShell 回收脚本,
VIDEO_RECYCLE_TOOL显式指定的绝对路径优先,未配置时只兼容基座现有的回收工具;显式路径无效不自动回退。助手必须返回“已回收”且原路径消失才算成功,超时报告“不确定”、不自动重试;Linux/macOS 用 Send2Trash。
- 独立网页作品:
.webfilm-cache保存完整成功的段(每段最长 2 秒),损坏就重建;.mp4.wav声音母带在同一作品、动作、画幅和 Chrome 且字节核验有效时复用,源码或素材变了就过期。同源母带复用是本期成果复用,不是云缓存或共享数据库,也不承诺两次独立冷启动的浮点音频逐位一样。
- 已审定画面保护:共用版式变化时可用 page_compare 逐字节对照整页和元素 SVG,认不出的记“无法比较”;已审定元素按 hold_check/preserve_svg 兼容,不能暗改已通过的画面。比对器现在可扫描任意影片的分镜表目录,也可只列已通过的表。
- docfilm 出片滚动复用:上一版默认取同一出片目录里同一镜头单、结论为通过的最近一份出片清单;本期分段和它保留的段里,同编号且指纹相同、视频完好的段先硬链接,跨盘才复制,写入前先断开链接,不会改到旧版本的文件。新版全部通过后,直接删除(unlink,不走回收站)本次检查目录的合并中间文件和下一版用不上的段,以及上一版检查目录里有脚本的段和合并中间文件;外部插入视频不动,路径不在检查目录里就报错不删。同一成片的检查目录只保留最近五次自动命名的,更早的整目录删除(rmtree),认不出的其他文件不清理。删除失败写进 warnings 和 cleanup.errors,不把已成功的出片改成失败。清单另记输入哈希、框架提交和源码摘要。





| 名词 | 意思 |
|---|---|
| identity(产物身份) | 回答“这份输出由哪组输入和设置产生”,不是用户身份或权限系统。 |
| SHA-256(字节摘要) | 检测文件是否发生字节变化;同摘要不能证明内容语义正确或真实。 |
| atomic write(原子写入) | 先写同目录临时文件再替换,避免崩溃留下半份 JSON 被误当有效记录。 |

可继续不等于盲目沿用;先证明旧文件仍属于当前输入。
解决什么
在保留断点续作价值的同时,消除脚本、音频和画面更新后仍使用同名旧产物的假成功,也避免清理时误删唯一的原件。



可继续不等于盲目沿用;先证明旧文件仍属于当前输入。
解决什么
在保留断点续作价值的同时,消除脚本、音频和画面更新后仍使用同名旧产物的假成功,也避免清理时误删唯一的原件。

- 身份文件不包含配音密钥或完整脚本文本,只保存摘要和公开配置字段。
- 分镜和图文页的复用不新增后台进程、共享缓存或跨项目服务;网页作品的缓存只在本期输出目录。
- 分镜路线的清理是显式动作,只处理已知可再生物,可先 dry-run;整期脚本、图片、声音和成片不算可再生缓存。旧定制 reset/archive 仍是退役状态,由每期新内容目录、新版本文件和现有恢复入口代替。
- docfilm 的段缓存清理是出片成功后的自动一步,删的是检查目录里能按镜头单重渲的段和中间文件,不走回收站;段指纹管不到本期扩展代码自己另读的文件,改了那些文件要用
render-part手动重渲用到它的段。滚动复用北京时间 10 月 29 日才合进主线,这次只读源码和说明,没有真实续作或清理的运行记录。
--initial(--changes 照样要给),或用 --previous <上版_清单.json> 指定。
- 身份文件不包含配音密钥或完整脚本文本,只保存摘要和公开配置字段。
- 分镜和图文页的复用不新增后台进程、共享缓存或跨项目服务;网页作品的缓存只在本期输出目录。
- 分镜路线的清理是显式动作,只处理已知可再生物,可先 dry-run;整期脚本、图片、声音和成片不算可再生缓存。旧定制 reset/archive 仍是退役状态,由每期新内容目录、新版本文件和现有恢复入口代替。
- docfilm 的段缓存清理是出片成功后的自动一步,删的是检查目录里能按镜头单重渲的段和中间文件,不走回收站;段指纹管不到本期扩展代码自己另读的文件,改了那些文件要用
render-part手动重渲用到它的段。滚动复用北京时间 10 月 29 日才合进主线,这次只读源码和说明,没有真实续作或清理的运行记录。
--initial(--changes 照样要给),或用 --previous <上版_清单.json> 指定。
- 共享最小身份函数
- 后续阶段的时长身份门
- 场景/素材/背景/配置续作身份
- 可再生临时物清理
- 2026-09-03 历史 33 项回归覆盖当时的配音、词轴、时长及出片身份,新初始化项目 33/33,之后未重新运行;cc41e514 源码共有 216 个测试定义,这次没有运行。
- 2026-09-03 的独立实现审查曾补出素材缺口并复核;这个历史结论不替代当前完整视频或所有恢复路径的实际验收。回收助手的真实运行、比对器在本期的无差异结果,这次都没有取得。
- 网页作品 2026-10-04 彩排中 1200 帧、母带和 MP4 一致的回执只覆盖那台机器那段样片,这次只重读、没有重播。
这是贯穿旁白、时间轴与出片的恢复边界;它不新增产品阶段,只保证各阶段的复用和清理不会改变当前视频内容。

- 共享最小身份函数
- 后续阶段的时长身份门
- 场景/素材/背景/配置续作身份
- 可再生临时物清理
- 2026-09-03 历史 33 项回归覆盖当时的配音、词轴、时长及出片身份,新初始化项目 33/33,之后未重新运行;cc41e514 源码共有 216 个测试定义,这次没有运行。
- 2026-09-03 的独立实现审查曾补出素材缺口并复核;这个历史结论不替代当前完整视频或所有恢复路径的实际验收。回收助手的真实运行、比对器在本期的无差异结果,这次都没有取得。
- 网页作品 2026-10-04 彩排中 1200 帧、母带和 MP4 一致的回执只覆盖那台机器那段样片,这次只重读、没有重播。
这是贯穿旁白、时间轴与出片的恢复边界;它不新增产品阶段,只保证各阶段的复用和清理不会改变当前视频内容。
复制 AI 续作说明
项目:旧产物只有身份匹配才复用,清理也只删可再生部分;仓库:页面未提供仓库地址;范围:整个项目;目标:(这里写这次要做的事)。先读项目的 AGENTS.md 和说明,按现行规则做。
把“目标”换成这次要做的事,整段复制给 AI。







