Python自动化：把重复劳动变成可审计工具¶
Python不是完成微电影的前置条件。只有当你已经能手工完成一项工作，并且重复操作开始造成漏项、错名、覆盖或费用浪费时，自动化才有意义。本篇面向第一次写生产脚本的读者：重点不是语法竞赛，而是怎样让脚本在失败时不破坏素材，在成功时留下足够证据。
旧版课程的练习保存在archive/course-2026.08-interactive/source/advanced/python/和80课快照中。本篇只吸收仍稳定的工程原则，不恢复关卡、进度或强制提交证据。
一、先判断什么值得自动化¶
适合自动化的任务通常同时满足三个条件：输入结构稳定、输出能明确检查、人工重复已经产生实际成本。例如检查八份视频提示是否与八个镜头ID对应、读取媒体时长和分辨率、生成候选文件清单、验证必填字段、把同一组安全参数写入工作流副本。它们有清楚的“对或不对”，也允许保留原文件。
不适合自动化的任务包括批准角色表演、判断剪辑是否有情绪递进、决定版权风险是否可接受，以及在主题尚不清楚时批量生成提示词。这些任务包含作者责任或上下文判断。脚本可以整理候选和暴露冲突，却不能把“运行无报错”伪装成创作批准。
把任何自动化需求先写成四句话：它读取什么；它绝不修改什么；它产生什么；人怎样验证结果。若第四句只能写“相信脚本”，需求还不够成熟。
二、从数据契约开始，而不是从循环开始¶
初学者常见做法是先写一个遍历文件夹的循环，遇到字段再临时处理。更可靠的顺序是先定义数据契约：每一行代表什么，哪些字段必填，ID怎样命名，状态允许哪些值，路径相对于哪里，空白是未知还是错误。
以镜头表为例，shot_id应是稳定身份，镜头标题可以修改；status只能取计划、候选、批准、放弃等受控值；prompt_path应指向项目内文件；approved不能由“文件存在”自动推导。契约的价值是把模糊约定变成可检查边界。CSV、JSON和YAML只是承载方式，真正重要的是字段语义。
读取数据后先规范化，再验证，再行动。规范化只处理无争议差异，例如去除字段两端空格、把空字符串转成统一空值；验证报告重复ID、未知状态和不存在路径；只有验证通过后，脚本才允许生成派生文件。不要在同一个步骤里一边猜测修复、一边覆盖来源表。
三、可靠命令行程序的四层结构¶
一个小工具也应分成四层。入口层负责接收参数和显示帮助；读取层把文件转成内存数据；规则层产生错误、警告或结果；写出层在获得明确授权后生成文件。分层不是为了炫技，而是让规则层可以在不碰真实文件的测试中运行。
错误、警告和信息要区分。错误表示继续行动可能产生错误结果，例如镜头ID重复；警告表示可以继续但必须人工判断，例如许可状态仍未知；信息只是说明统计值。命令退出码也要诚实：校验失败返回非零，纯警告可以按项目政策决定是否阻塞。这样脚本才能被Git钩子或持续集成可靠调用。
所有会写文件的命令至少提供预览能力。预览应列出将创建、修改、跳过的具体目标，并且不改变磁盘。真正执行时写入新路径或临时文件，完成验证后再原子替换；不要逐行改写唯一源文件。若目标已存在，默认拒绝覆盖，除非用户给出明确参数且脚本先建立可恢复副本。
四、路径、编码与Windows环境¶
Windows路径可以包含空格、中文和不同盘符。脚本内部应使用pathlib.Path表达路径，不用字符串手工拼接斜杠。相对路径必须绑定一个明确根目录，通常是Git仓库根或项目清单所在目录，而不是“当前碰巧打开的终端位置”。解析后还要确认目标仍位于允许根目录内，防止清单中的..把写入带到项目外。
教材Markdown、CSV和JSON统一使用UTF-8。读取时明确编码，写CSV时处理换行规则。遇到乱码不要用“忽略错误”让内容静默丢失；先确认来源编码并做一次可追溯转换。对人名、对白和提示词，替换不可解码字符可能改变创作内容，应该直接停止并报告文件与位置。
本地命令环境：Windows PowerShell。
执行环境：Windows PowerShell
python scripts/book.py validate
python scripts/validate_project.py .\demo\echo-cabin
代码块只是当前项目入口示例。真正迁移到原创片时，先用帮助信息确认参数，不从聊天记录盲贴带删除、覆盖或付费调用的命令。
五、日志要回答决定，而不是倾倒终端¶
一份生产日志至少包含运行时间、工具版本、输入身份、关键参数、输出位置、结果摘要和退出状态。付费生成还要记录任务标识、尝试次数和预算消耗。日志不应保存密钥、完整授权头、私人声纹或与任务无关的环境变量。
日志分为给人看的摘要和给程序读的结构化记录。摘要回答“发生了什么、下一步是什么”；结构化记录允许以后按镜头、模型版本或错误类型统计。不要把数千行第三方输出直接提交仓库。可以保留原始日志在本机受控目录，再在项目中记录摘要和指向它的非敏感标识。
脚本输出“成功”必须有含义。对媒体任务，成功至少可能分为请求被接受、远端任务完成、文件下载完毕、文件可解码、技术规格通过和人工采用。把这些状态压成一个布尔值会制造假完成。最安全的做法是让每个阶段独立记录时间、证据和失败原因。
六、HTTP、异步任务与有限重试¶
调用远程服务时，网络请求成功不等于创作任务成功。HTTP响应可能只返回任务ID；脚本还要在有限时间内查询状态，识别失败、取消和超时，再下载输出并验证。轮询应逐渐放慢，设总时限，并允许用户中断。无限循环会持续占用资源，也可能掩盖服务端已经无法恢复的错误。
重试只适合暂时性故障，例如短暂断网或明确的限流响应。输入非法、余额不足、模型不支持当前模式等确定性错误不应自动重试。每次重试都必须有上限，并记录原因。对付费生成，尝试上限和费用上限缺一不可；技术上的三次请求可能在业务上仍然不可接受。
密钥只从受控凭据机制或环境变量读取，不写入脚本、Markdown、工作流JSON和截图。错误消息中也要遮蔽令牌。若准备把日志提交Git，先搜索常见密钥格式和授权字段；发现泄露时，删除文件历史并不等于密钥安全，仍应立即轮换凭据。
七、媒体探测与“文件存在”陷阱¶
视频文件出现在输出目录，只能证明路径存在。可靠检查还包括大小非零、容器可读取、时长与计划接近、分辨率和帧率合理、音轨是否存在，以及抽帧或实际播放。生成中断可能留下同名空文件，下载页面也可能被错误保存为视频扩展名。
技术探测适合用工具读取元数据，但人工观看仍不可替代。一个文件可以编码完全合法，却有黑帧、身份漂移、音画错位或错误内容。脚本应报告“技术检查通过”，不写“镜头通过”。同理，计算SHA256证明以后读到的是同一组字节，不证明文件符合叙事意图或许可要求。
批量重命名媒体时，先生成旧名—新名映射表并检查重复目标。执行后重新读取目录，与映射逐项核对。不要依赖资源管理器按时间排序推测哪一个文件属于哪次生成；让任务ID、镜头ID和版本号进入文件名或旁车清单。
八、幂等、断点续作与恢复¶
幂等意味着同一命令重复运行不会不断制造新副作用。校验天然应幂等；生成索引可以先在内存中产生完整内容，再只在内容改变时替换；下载器遇到已存在文件应核对校验和，而不是无条件覆盖。付费生成通常不幂等，因此必须使用任务标识或本地账本避免重启脚本后重复提交。
长任务把状态写入独立清单：哪些输入尚未处理，哪些已提交，哪些已完成，哪些下载并核验。程序崩溃后从最后一个有证据的阶段恢复，不能只看循环计数。状态写入也要安全，先写临时文件并完成解析验证，再替换正式清单。
恢复测试要主动进行。复制一份小型测试项目，在中途人为终止，再重新运行；观察是否重复付费、覆盖文件或把半成品标成完成。只有在失败演练中仍能解释每个状态，工具才具备进入正式制作的条件。
九、测试不是证明“永远正确”¶
规则层至少测试正常输入、边界输入和恶意或损坏输入。镜头表测试应覆盖重复ID、空路径、越界路径、未知状态和UTF-8内容。文件写入测试使用临时目录，绝不对真实项目做破坏性试验。外部API用伪响应测试任务成功、失败、超时和限流，避免每次测试都产生费用。
自动测试证明的是已写下的规则在这些样例中按预期运行。它不能证明规则本身完整，也不能替代实际媒体检查。每次真实故障都应先保存一个最小复现样例，再修代码并增加回归测试；否则同类错误很可能在下一次重构中回来。
十、《回声舱》的最小自动化路线¶
第一步只做只读校验：八个镜头是否都有对应提示，图片与视频模式是否匹配，引用路径是否存在，媒体状态是否诚实。第二步生成章节索引和媒体报告等可丢弃派生物。第三步才考虑把批准工作流复制为任务副本并补丁参数。任何脚本都不得自行把镜头状态改为批准。
一次合格运行的摘要可以写成：“读取8个镜头；8份图片提示与8份视频提示ID一致；发现7项明确待生成资产；没有写入项目；退出码为0，警告需要人工处理。”这比“检查成功”更有教学价值，因为读者知道检查覆盖了什么、没覆盖什么。
原创片迁移练习：挑一个你已经手工做过三次的操作，写出数据契约、预览输出、失败分类和恢复办法。暂时不要编程。若纸面流程仍无法说明输入、输出和停止条件，继续手工澄清；若能说明，再实现最小只读版本，并用临时项目测试。自动化的成熟标志不是代码最长，而是错误更早出现、修改更小、结果更容易复核。
本篇检查表¶
- 输入、输出、不可修改对象和人工验证是否写清。
- 路径是否限制在预期根目录，编码是否明确。
- 写入是否支持预览、拒绝默认覆盖并可恢复。
- 网络任务是否有超时、有限重试和预算上限。
- 日志是否区分提交、完成、下载、技术通过和人工采用。
- 密钥与私人数据是否不会进入源码、日志和Git。
- 媒体是否做元数据、实际读取与人工观看三层检查。
- 中断重启是否不会重复付费或误报完成。
- 测试是否只操作临时目录并覆盖失败路径。
- 自动化是否仍把创作批准与权利判断留给人。