四个前置条件与 `make setup`：从 clone 到出片的路径

2026-08-09

大多数项目的 Quick Start 是「装依赖 → 跑起来」，OpenMontage 的 Quick Start 读起来也像这样：四个前置条件，三条命令，然后开始说话。真正容易被跳过的是第四个前置条件——它不是一个环境依赖，而是一件你得先有的东西。

先把身份锚点摆一下：calesthio/OpenMontage，截至 2026-08-09，仓库 star 46362、fork 5758、open issues 218，许可是 AGPL-3.0，主语言 Python。star 数只说明它被收藏过多少次，不说明装起来顺不顺利，本文不拿它推导任何结论。

四个前置条件，第四项才是分水岭

README 的 Prerequisites 一共四项：

Python 3.10+
FFmpeg（README 给的获取方式是 brew install ffmpeg / sudo apt install ffmpeg / 或去 ffmpeg.org）
Node.js 18+
一个 AI 编码助手：Claude Code、Cursor、Copilot、Windsurf 或 Codex

前三项是常规的运行时依赖，不用多说：Python 跑工具层，FFmpeg 管编码与后期（README 的零密钥能力表里，FFmpeg 对应的是编码、字幕烧入、音频混合、调色），Node 那一侧对应 React 合成引擎所在的 remotion-composer/——README 的架构图把这个目录标为 “React/Remotion video composition engine”。

Node 这一项这里要插一句可核实的差异。Prerequisites 写的是 Node.js 18+，但 README 后面那张运行时表里，Remotion 一行标的是 “Local (Node.js)“，HyperFrames 一行标的是 “Local (Node.js ≥ 22)“——只有 HyperFrames 写了具体的版本下限。也就是说，按最低前置条件把 Node 18 装上，未必够得着 HyperFrames 那一行自己标注的下限。这两处都是 README 自己的文本，我们只陈述差异，不推断该以哪一处为准，也不断言 Node 18 就一定跑不起 HyperFrames——我们没有跑过。实际影响在于：OpenMontage 会在提案阶段在 Remotion 与 HyperFrames 之间选一个并锁进 render_runtime，如果你的需求偏动态图形、有可能被分到 HTML/GSAP 那条路，Node 版本这一项值得装之前先看一眼，而不是等到渲染那一步再回头查。

第四项才是这个项目和别的视频工具分道扬镳的地方。它不是「推荐你配一个，效率更高」，而是流程本身就跑在 agent 上。README 给 agent 的最短上手路径第 2 条说得很直白：不要即兴发挥制作流程——OpenMontage 是流水线驱动的，真活要走 pipeline_defs/、skills/pipelines/ 下的阶段导演 skill，以及通过 registry 做工具发现。第 1 条是先读契约（先 AGENT_GUIDE.md，再 PROJECT_CONTEXT.md），第 4 条是把每个视频请求都当成一个流水线选择问题：先挑对流水线，再读 manifest，再读阶段 skill，最后才用工具。

也就是说，如果你手上没有一个能读文件、能跑代码的 AI 编码助手，前三项依赖装得再干净，这条路径也是断的。README 为五个平台各给了配置文件：

平台	配置文件
Claude Code	`CLAUDE.md`
Cursor	`CURSOR.md` + `.cursor/rules/`
GitHub Copilot	`COPILOT.md` + `.github/copilot-instructions.md`
Codex	`CODEX.md`
Windsurf	`.windsurfrules`

这张表放在安装篇里的意义在于：这些文件不是可选装饰，它们全部指向共享的 AGENT_GUIDE.md（操作指南与 agent 契约）和 PROJECT_CONTEXT.md（架构参考）。clone 下来之后你不需要额外做什么，但你得知道，你的助手能不能读到这份契约，决定了后面所有流程约束是否有机会生效。这里补一句实话：契约是写给模型看的文本，是指令而不是工程保障，写了「必须先读 skill」不等于模型一定会读。

`make setup`：三条命令，以及没有 make 的时候

README 给的标准路径就三行：

git clone https://github.com/calesthio/OpenMontage.git
cd OpenMontage
make setup

装完之后不需要再敲命令，直接在 AI 编码助手里打开这个项目，用自然语言说你要什么。README 给的两个入口示例，一个是纯生成路线：

"Make a 60-second animated explainer about how neural networks learn"

一个是真实素材路线：

"Make a 75-second documentary montage about city life in the rain. Use real footage only, no narration, elegiac tone, with music."

注意第二条里的 use real footage only 不是修辞，README 把「用真实动态素材」和「给静态图加动效」明确区分开来了，走哪条路要在 prompt 里说清楚。

没有 make 的机器，README 另给了手动串。两个系统写法不同，别混着抄。

macOS/Linux：

python3 -m venv .venv && source .venv/bin/activate && python -m pip install -r requirements.txt && cd remotion-composer && npm install && cd .. && python -m pip install piper-tts && cp .env.example .env

Windows PowerShell：

py -3 -m venv .venv; .\.venv\Scripts\Activate.ps1; python -m pip install -r requirements.txt; cd remotion-composer; npm install; cd ..; python -m pip install piper-tts; Copy-Item .env.example .env

Windows 侧有一条 README 单独记下来的已知问题：如果 npm install 报 ERR_INVALID_ARG_TYPE，改用 npx --yes npm install。这条值得先记住——报错发生在 cd remotion-composer 之后那一步，也就是 React 合成引擎的依赖安装，卡在这里会让你误以为整个安装失败了。以上安装串照抄自 README，我们没有执行过任何一条，实际以你本地的报错为准。

README 把这串命令列为「没有 make 时」的路径，所以对着它读，也就大致知道 make setup 那一行替你做了哪几件事：建虚拟环境、装 Python 依赖、装 remotion-composer 的 npm 依赖、装 piper-tts、把 .env.example 复制成 .env。最后那一步经常被当成可跳过的收尾，但 .env 是后面所有 provider 密钥的落点。README 在 .env 段的原话是 every key is optional——一个都不加也能往下走，加了哪个解锁哪一类能力则是另一件事，本批另有一篇专门逐个密钥拆。密钥相关的写法请自行结合环境评估，正文里不要粘贴任何真实值，占位一律写成 your-key 这类形式。

装完之后，README 说会发生什么

从「装好」到「出片」中间那一段，README 是这样描述的：agent 用实时网络搜索调研你的主题、生成 AI 图片、写脚本并带语音指导做旁白、自动找免版税背景音乐、烧入词级字幕、渲染最终视频。在你看到任何东西之前，系统会跑一次多点自检——ffprobe 校验、抽帧、音量分析、交付承诺核验和字幕检查。每一次 provider 选择都会在 7 个维度上打分并留下可审计的决策日志。每一个创意决策都要经过你批准。

这条链里的最后一项，是安装阶段少数能提前钉一个源码锚点的地方。README 说的那 7 个维度和权重是 task fit 30%、output quality 20%、control features 15%、reliability 15%、cost efficiency 10%、latency 5%、continuity 5%；lib/scoring.py 第 38-44 行的加权求和里，这七项系数是 0.30 / 0.20 / 0.15 / 0.15 / 0.10 / 0.05 / 0.05，与 README 的说法逐项一致，相加正好 1.00。这至少说明这一条不是只写在 README 里的措辞，代码里有对应的常数。光看权重也能读出这套评分的取向：任务匹配度一项就占 30%，和输出质量加起来占了一半，而成本效率只有 10%、延迟与连续性各 5%。评分引擎本身本批另有专篇细拆，这里只是提醒你，装完之后你会反复看到「provider 打分」这个词，它背后是有具体系数的。

这一段必须原样当成 README 的描述来读。我们没有跑过 make setup，没有渲染过任何一条视频，也没有调用过其中任何一个 provider API，所以上面这条链里的每一环实际表现如何，本文一个字都不评价。需要展开的是它给你的心理预期：这不是一条敲完命令就等成片的流水线，中间有明确的人工闸口，你会被叫住好几次。README 里那块本地看板 Backlot 就是配合这些闸口的界面，它给了几张截图——我们只见过截图的存在，没有运行过它，本文不描述它长什么样、好不好用，Backlot 本身本批另有专篇。

怎么确认自己装对了

README 给的自查办法很务实：不要看文档猜，去问 registry。两条命令：

python -c "from tools.tool_registry import registry; import json; registry.discover(); print(json.dumps(registry.support_envelope(), indent=2))"
python -c "from tools.tool_registry import registry; import json; registry.discover(); print(json.dumps(registry.provider_menu(), indent=2))"

前一条问的是「当前这套环境的能力边界是什么」，后一条问的是「每类能力下现在有哪些 provider 可用」。它们的价值在安装阶段尤其明显：文档描述的是项目理论上支持什么，registry 输出的是你这台机器此刻支持什么，两者不一致时以后者为准。

另外还有一条不需要 API 密钥的契约测试：

make test-contracts

以及跑全部测试的 make test。以上命令均照抄自仓库文档，我们没有运行过，实际输出以你本地跑出来的为准。

上手之前先摆平的三件事

第一，成本数字不是你的预算。 README 列了 5 段演示视频，其中四段标了项目方自己给出的总成本——“THE LAST BANANA” $1.33、“The Library at Alexandria” $0.02、“VOID — Neural Interface” $0.69、“Afternoon in Candyland” $0.15；示例 prompt 那节也标了两档区间：配了图像/视频 provider 的 ~$0.15–$1.50，完整配置的 ~$1–$3。这些全部是项目方在 README 中自行标注的金额，我们没有验证过，也不能拿来推算你自己做一条要花多少钱。你的题材、时长、重试次数、选到哪个 provider 都会变。

第二，本地 LLM 是计划，不是能力。 README 明写通过 Ollama 和 LM Studio 支持本地 LLM 是 “Coming soon”。如果你的前提是「不能把内容送到云端 LLM」，那按 README 当前的口径，这条路还没到能用的时候。

第三，项目状态要如实计入预期。 仓库里有流水线的 manifest 自标 stability: beta；README 结尾作者自述 “OpenMontage is built nights and weekends”，是业余时间做的项目。许可这一条也提前说一句：它用的是 AGPL-3.0，和常见的 MIT、Apache-2.0 不是一类，你打算拿它做什么、能做到哪一步，请以官方 LICENSE 原文为准——我们没有读过 LICENSE 正文，这里只指路。

把这三件事和四个前置条件放在一起看，安装这一步的门槛其实不在依赖装不装得上，而在你是不是接受这套「agent 当编排器、你在闸口上按确认」的工作方式。接受了，make setup 就是三条命令的事；不接受，装好了也用不起来。

本文依据 OpenMontage 官方仓库（github.com/calesthio/OpenMontage）的 README、 AGENT_GUIDE.md、config.yaml、pipeline_defs/ 与 lib/ 下的治理模块整理，核对日 2026-08-09。本文内容为仓库源码与文档口径，我们没有安装或运行过该系统，也没有调用过其中任何一个 provider API，文中出现的成本数字均为项目方在 README 中自行标注的金额，非我们的实测结果。该项目以 AGPL-3.0 发布，部分流水线在 manifest 中自标 stability: beta，请以仓库最新内容为准。许可条款请以官方 LICENSE 原文为准，本文不构成法律意见。安全相关做法请结合自身环境评估，本文不构成安全方案建议。