OpenMontage 部署到 WorkBuddy

把 OpenMontage 从零装到可用，直到端到端渲染出片。

部署完成后日常使用走 openmontage skill（那个管 pipeline 调用）。本 skill 只管「装」。

何时用本 skill

• 用户要部署 / 安装 / 重装 OpenMontage
• 换机器、换环境，需要重新配一套
• OpenMontage 已装但报「无 ffmpeg / 渲染 blocked」
• 排查部署期的环境问题

不适用：已经装好了、只是要做视频 → 用 openmontage skill。

三条铁律（先记住，能省几小时）

1. 不要用 git clone —— 本机 git 缺 remote-https 助手，必失败。改用 curl 拉 tarball + tar 解压。
2. ffmpeg 的 PATH 问题靠 sitecustomize.py 解决，不是靠设环境变量 —— WorkBuddy 的 PowerShell 工具每轮都是新进程，PATH 不继承。必须在 venv 的 site-packages 里放启动钩子。
3. 所有 OpenMontage python 命令的 cwd 必须是源码根目录 —— 否则 ModuleNotFoundError: tools。

完整流程

详细步骤（含每步的验收条件、命令、绕行方案）见
references/deployment-runbook.md —— 部署时先完整读它，按顺序执行。

十个阶段概览：

两个自带脚本

scripts/patch_ffmpeg_path.py —— 修 ffmpeg 检测

向 venv 的 site-packages/sitecustomize.py 写入 PATH 补丁，让 ffmpeg 在所有 Python 子进程里可达。

& "<root>\.venv\Scripts\python.exe" `
  "C:\Users\Administrator\.workbuddy\skills\deploy-openmontage\scripts\patch_ffmpeg_path.py" `
  <root>\.venv [ffmpeg_bin_dir]

• 会自动备份原 sitecustomize.py 为 .bak
• 写完立即用同一 venv 探针验证
• 幂等，可重复跑
• 第二个参数省略时默认取 <home>\.workbuddy\binaries\ffmpeg\bin

什么时候跑：第 5 步必跑；之后若 verify_deployment.py 报 ffmpeg 不可见，也跑这个。

scripts/verify_deployment.py —— 健康检查

一条命令判断部署是否可用，退出码 0 = 健康。

& "<root>\.venv\Scripts\python.exe" `
  "C:\Users\Administrator\.workbuddy\skills\deploy-openmontage\scripts\verify_deployment.py" `
  <root>

检查 5 组：
1. 目录结构（源码根 / venv / remotion-composer / pipeline_defs / sitecustomize 补丁）
2. 关键依赖导入（tools.tool_registry / lib.checkpoint）
3. ffmpeg + ffprobe 可达性（从 Python 子进程视角，这才是真实判断）
4. 渲染引擎清单（ffmpeg / remotion / hyperframes）
5. 能力族概览（capabilities / setup_offers / runtime_warnings）

健康的预期值：

{"ffmpeg": true, "remotion": true, "hyperframes": false}

hyperframes: false 属正常 —— 不影响 Remotion + FFmpeg 主路径。相关的 runtime_warnings 要原样告知用户，但不必惊慌。

环境约束速查（本机特性）

另外：本机没有 make。文档里的 make xxx 需手工翻译成等价命令。

排错

遇到问题先查 references/troubleshooting.md —— 按症状组织，覆盖：

• A 组 ffmpeg：检测不到 / winget 装不上 / apad 挂死 / -shortest 截尾
• B 组 代码依赖：ModuleNotFoundError: tools / git clone 失败 / 无 make / Piper 无中文音色
• C 组 Windows 环境：PS stdout 不回传 / *> 重定向乱码 / UnboundLocalError
• D 组 生成代码与打包：sitecustomize.py 语法错误静默失效 / skill-creator 打包编码崩溃
• E 组 渲染产物：HeroTitle 整条变色 / KPIGrid 出 NaN / stat_card 盖住渐变
• F 组：快速自检清单

如果要改本 skill 的脚本

改完必须实测，尤其是生成代码的脚本。本 skill 就踩过两次：

1. patch_ffmpeg_path.py 生成的补丁带语法错误。原因是把 Windows 路径塞进非 raw 字符串，\U（来自 \Users）被当成 Unicode 转义。当时 shutil.which("ffmpeg") 仍返回 None，看起来像补丁没生效，实际是补丁根本没加载成功。现已加 compile() 前置校验 + 占位符残留断言。
2. skill-creator 的 package_skill.py 在中文 Windows 上编码崩溃。官方脚本 read_text() 未指定 encoding，走 cp936。已用 scripts/package_skill_utf8.py 包装绕过。

改脚本后的验证流程：

# 1) 重新执行补丁，确认语法校验通过且探针非 None
& "<root>\.venv\Scripts\python.exe" "...\scripts\patch_ffmpeg_path.py" <root>\.venv

# 2) 全新进程探针，stderr 不得出现 "sitecustomize"
& "<root>\.venv\Scripts\python.exe" -c "import shutil; print(shutil.which('ffmpeg'))" 2>&1

# 3) 完整健康检查，退出码须为 0
& "<root>\.venv\Scripts\python.exe" "...\scripts\verify_deployment.py" <root>

改完记得重新打包：

& "C:\Users\Administrator\.workbuddy\binaries\python\versions\3.13.12\python.exe" `
  "C:\Users\Administrator\.workbuddy\skills\deploy-openmontage\scripts\package_skill_utf8.py" `
  "C:\Users\Administrator\.workbuddy\skills\deploy-openmontage" E:\wk

部署完成后

部署成功的标志：

1. verify_deployment.py 退出码 0
2. render_demo.py world-in-numbers 产出可播的 1080p MP4

之后把注意力转到 openmontage skill —— 那里有 pipeline 调用入口（Rule Zero）和日常使用的全部坑。

注意事项

• <root>\.venv\Lib\site-packages\sitecustomize.py 不可删除。删了 ffmpeg 立刻检测不到，渲染 blocked。
• 修 .env 时注意它是明文集中管理，不要提交到任何仓库（.gitignore 已含）。
• AGPL-3.0 许可：内部/个人使用无约束；对外提供网络服务会触发传染，商业闭源集成前需评估。
• 换机器部署时，本 runbook 同样适用 —— 只需把路径里的 E:\wk\OpenMontage 换成目标位置。