用途与实际影响
这项功能怎样使用
为什么需要它
旧项目残留会把素材、标题和输出混进新一期;环境缺一环又可能在长渲染时才暴露。初始化只复制通用能力,doctor 只回答机器是否具备当前条件,二者把“项目干净”和“环境能跑”分别验证。
举个实际例子
我可以说:“在 D:\Videos\my-next-video 建一个新项目,别带上一期脚本;先确认这台电脑能不能跑。”目标目录已有内容时会直接停止,不为省事覆盖旧文件。
最后我会得到什么
得到一份不带旧作品内容的新工程和所需文件夹;环境检查会告诉我缺什么,但这时还没有旁白或视频。
正常时
空白工程创建完整,当前能检查的本机依赖已有结果;真实配音和渲染按需要另验。
发现问题时
显卡正被其他重活占用时,只有明确选择的本地探针或制作步骤报告忙碌,普通状态检查不抢资源。
入口不可用或证据不足时
目标目录不空或必要工具缺失时停止并点名问题,不覆盖旧文件或自动调用收费服务。
从哪里开始
在 video-scaffold 源目录使用 run.ps1 init 指定空目标目录,进入新项目后运行 run.ps1 doctor;真实外部配音探针另选 doctor-live。
需要准备什么
- 新工程的空目录
- 视频主题或用途(初始化后再提供也可)
从开始到拿到结果
- 1
复制干净工程
init 只建立通用文件和目录,不代写标题、旁白或镜头。
- 2
检查本机
doctor 给出依赖和缺口;需要真实 Fish 响应时才另做 doctor-live。
- 3
决定能否开工
环境缺项先修复;维护 test 是代码回归,不是每次做片前的产品步骤。
技术实现与依据
这里保留实现、关键条件、精确入口、历史记录和验证结果。
空项目初始化与静态诊断已实现;真实本地和云端探针单独运行关键规则与设计选择
test 验维护代码,doctor 看静态环境,status/plan 看本期工程;三者不是每次都必须执行的全套检查。
doctor 不发 Fish 请求;doctor-live 才是实际网络探针。
环境 Ready 不能替代脚本、画面、成片和人工观看。
本模块用到的名词
- bootstrap(项目初始化)
- 把通用工具复制成一份新的独立工作区,不含上一期的业务内容。
- doctor(环境体检)
- 只检查当前环境能力,不生产视频,也不证明内容完成。
- BUSY(资源正忙)
- 编码器存在,但显卡当时没有足够资源;释放已有工作后可重试,不能当缺依赖。
专业定义
新项目不夹带上一期内容;先测代码,再测本机环境。
解决什么
防止复制旧视频污染新项目,也防止因为一个命令返回绿色就把尚未制作的内容称为完成。
当前怎样实现
- init_project.py 拒绝非空目标,先暂存完整通用模板再交到新目录,不复制已生成音频、成片、密钥或 .video-machine.json。
- 旧 build_v2.py 与定制封面已退出活动源树;通用 scene_base.html、cover_base.html 与隔离演示入口保留,不清理用户旧工程。
- run.ps1 按 VIDEO_PYTHON、项目 .venv、机器适配、py -3.11、系统 python 解析解释器,再统一进入 pipeline.workflow。
- doctor 只检查 Python 包、FFmpeg/ffprobe、背景/模板文件、已登记 GPU 协调及 ChineseASR 适配;不启浏览器/GPU,不读取私钥文件、不发网络请求。
- doctor-local 承担明确本地探针;doctor-live 才调用 Fish 并消耗额度。smoke/demo 的 CPU H.264 是显式隔离测试,不是生产 NVENC 失败后的自动降级。
执行流程
- 1
选择一个空目标目录。
- 2
复制通用源并创建工作目录与被忽略的密钥占位文件。
- 3
维护变更时运行 test;开始普通制作不强制重跑整套回归。
- 4
运行 doctor,读取本机环境结果。
- 5
只有需要真实 Fish 证据时再单独运行 doctor-live。
边界
- 初始化不替人确定标题、脚本、素材或场景。
- 本轮没有执行 doctor-live,不声称 Fish 当前真实响应。
- 项目依赖可按正式入口安装,但付费、账号和重型下载不是浏览页面时自动执行的动作。
失败与恢复
- 目标目录已有内容
- 拒绝覆盖,要求换空目录或先由人处理现有内容。
- NVENC 显存压力
- 返回 BUSY 和显存信息,不把它改写成永久不支持。
- 明确配音时 Fish 配置缺失
- TTS 或明确配置探针失败,不打印密钥、不换声线或服务;静态 doctor 不读取密钥,也不假报账户可用。
真实入口
E:\Projects\Archives\video-scaffold\init_project.py通用文件复制、空目录和拒绝覆盖
E:\Projects\Archives\video-scaffold\run.ps1统一 Python 与阶段入口
E:\Projects\Archives\video-scaffold\pipeline\doctor.py本机与可选网络体检
E:\Projects\Archives\video-scaffold\tests\test_workflow_readiness.py初始化与 doctor 回归
如何验证
- 2026-09-03 历史源仓库 33/33,本轮未重新运行。
- 2026-09-03 历史新初始化工程 33/33;当前源码新增隔离 smoke 与 Windows/Linux CI,入口存在不等于本轮执行。
- 2026-09-18 13:02 UTC 静态 doctor 10 PASS、1 UNKNOWN(未验证);没有运行 doctor-local 或 doctor-live。
与其他模块的关系
本模块只决定项目和环境能否开始;旁白模块拥有外部配音和词级时间,后续模块才形成画面与交付。
