两条命令查清你到底有什么：OpenMontage registry 的三个方法

2026-08-09

翻 OpenMontage 的 README 时最容易产生的错觉，是把 provider 表当成能力清单。视频那张表 15 行、图像那张 11 行、TTS 5 行，看完感觉手里握着一整个素材工厂。可这些表描述的是「这个项目对接过谁」，不是「你现在能调谁」。中间隔着 .env 里填了几行、有没有 GPU、Node 装到几版这些很实在的东西。

README 自己也没打算让你靠读表解决这个问题。在给 agent 的最短上手路径那一节里，第 3 步原文写的是「查真实的能力边界」，给的办法是跑命令。

那两条命令

README 原文照抄如下：

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))"

上面两条命令照抄自仓库文档，我们没有运行过，实际输出以你本地跑出来的为准。

从这两行的调用形式能读出的硬事实只有一件：tools/tool_registry.py 里有一个 registry 对象，它提供 discover()、support_envelope()、provider_menu() 三个方法。注意两条命令的共同前半段——都是先 discover()，再取结果。也就是说发现动作是显式的一步，不是导入模块就自动完成的。

需要先划一条边界：tools/tool_registry.py 的代码我们没有读过，所以这三个方法各自返回什么结构、里面有哪些字段、怎么判定一个工具算不算「可用」，本文一概不写。能写的只有调用形式，以及文档对它们的定位。

先跑哪一条：文档给了排序

AGENT_GUIDE.md 的 Mandatory Preflight 一节里，这两条命令带着注释出现，注释原文分别是：

# Full menu — grouped available/unavailable per capability.

# Raw envelope — every tool's full contract. Slow/firehose; use for debugging only.

这两句注释把使用顺序说得很清楚。provider_menu() 是按能力分组、把可用与不可用摆在一起看的那份菜单，日常用它；support_envelope() 是每个工具的完整契约，原文自己就标了慢、输出量大（firehose 这个词是文档用的），只在调试时跑。

这一点值得先记下来，因为 README 那节把两条命令并排列出，看起来像是「都跑一遍」。真要按顺序说，先跑第二条那个 menu，第一条留到你怀疑某个具体工具的声明有问题时再说。

为什么必须查，而不是数表

把事实卡里几个可核对的计数摆在一起，就知道读表读不出答案。

README 的视频生成表 15 行，按 Type 一列数下来是 8 个 Cloud API、4 个 Local GPU（含标为 Local GPU / Modal 的 LTX-Video）、3 个 Stock。这三类各自带着不同的前置条件：8 个标 Cloud API 的走云端服务，4 个标 Local GPU 的要有显卡，3 个 Stock 里 Pexels 和 Pixabay 在 README 的 .env 段里各占一行密钥。整张表里只有 Wikimedia Commons 同时出现在 README 的零密钥能力表里（在那张表中与 Archive.org、NASA 并列为开放素材来源）。

而 .env 那段，README 顶上原文就写了 every key is optional。我们数了那段示例，一共 13 个密钥变量，外加一个可选的 KLING_API_BASE_URL 端点（它的值留空，注释说默认是新加坡端点）。那 13 个密钥变量的值统一写成 your-key 这样的占位符。换句话说，同一个仓库，两个人 clone 下来跑出来的能力集合可以完全不同——差别不在代码，在这 13 行你填了几行。

这就是那两条命令要回答的问题：15 减去你没配的那些，还剩几个。这个减法只有 registry 能做，README 做不了。

同样的道理也解释了 AGENT_GUIDE.md 的 What Not To Do 里那条硬规矩：不要硬编码 provider 名、API key 名或安装 URL，要从 registry 的 install_instructions 和 dependencies 字段读。这两个字段名是文档里点名的，它们的具体内容我们没有读过。

AGENT_GUIDE.md 里有两个标题级的事实：一个是 ## Mandatory Preflight，一个是它下面的 ### Provider Menu (Mandatory at Preflight)。两处都带 Mandatory。配套的 What Not To Do 条款里，也明确写了不要在 preflight 时跳过 Provider Menu，理由是用户必须看到他有什么以及他还能解锁什么。

同一批条款里还有一条关于呈现方式的：不要孤立地呈现单个不可用工具，要永远展示完整能力图景，用 X of Y providers configured for this capability. 这种说法。这句模板其实就是 provider menu 那份分组结果的口头版本——分子是你配好的，分母是项目对接过的。

另外一条对搜到旧教程的人特别有用：不要使用已删除的旧名称 tts_cloud、tts_engine、video_gen。如果你手里的资料里出现这三个名字，那份资料对不上仓库当前状态；具体该用什么名字，还是回去跑 menu。

需要说明的是，这些都是写给模型看的约束文本，是指令不是工程保障。契约里写了 preflight 必须跑，不等于装好之后你的 agent 一定会跑；能不能落地取决于你用的 agent 和它当时的上下文。

计数口径：几处对不上的地方

查能力这件事上，还有一层麻烦是数字本身的口径。

README 的 TTS 表列了 5 行——ElevenLabs、Google TTS、Kling Official TTS、OpenAI TTS、Piper。而 README 架构图里 tools/audio/ 那行写的是 4 TTS providers。两处写的不一样，以仓库当前状态为准，我们不推断哪个是对的。

视频那边的差异性质不同：表是 15 行 provider，架构图里 tools/video/ 标的是 13 video gen tools + compose, stitch, trim。这两个数一个在数 provider，一个在数 tool，本来就不是同一个口径。所以你在别处看到「OpenMontage 支持多少个视频 provider」这类说法时，先问清楚数的是哪一种。

这两处正好反过来印证了前面的结论：文档里的数字有多个口径，你机器上的答案只有一个来源，就是 registry 跑出来的那份。

能力查询查不出的东西

有三类情况，跑完命令也解决不了，得提前知道。

一是运行时的版本门槛。 README 的 Prerequisites 写的是 Node.js 18+，而 Composition & Rendering 表里，Remotion 标的是 Local (Node.js)，HyperFrames 标的是 Local (Node.js ≥ 22)——只有 HyperFrames 写了具体的版本下限。按最低前置条件装好的环境，可能达不到 HyperFrames 标注的这个下限。这是两处 README 文本之间可核实的不一致，我们不据此断言 HyperFrames 一定跑不起来——我们没有实测过。

顺带一提运行时这件事的治理规则，README 原文写在那张表后面：运行时在提案阶段被选定（render_runtime），并通过 edit_decisions 锁定，在运行时之间静默切换是一次治理违规。完整决策矩阵在 skills/core/hyperframes.md，那个文件我们没有读过，不展开。

二是「计划」不是「能力」。 README 明写通过 Ollama 和 LM Studio 支持本地 LLM 是 Coming soon。你在能力查询里找不到它，不说明你配错了，说明 README 把它写成了计划。

三是零密钥路径不在减法里。 前面那个「15 减去你没配的」的算法只适用于需要密钥的那部分。README 有一节专讲零密钥能获得什么：Piper TTS 做旁白，Archive.org、NASA、Wikimedia Commons 提供开放素材，Remotion 与 HyperFrames 两套合成运行时，FFmpeg 做后期，以及内置的词级时间戳字幕。所以 menu 里云端 provider 一栏全空，不等于什么都做不了。这条路径本批另有一篇专门讲，这里不重复。

你自己加了工具之后

README 的 Contributing 一节给了加新工具的步骤，其中两步是硬契约：继承 BaseTool 并实现工具契约、registry 自动发现它不需要手动注册。对应文件是 tools/base_tool.py 和 tools/tool_registry.py。

「自动发现」这四个字意味着，你写完工具之后的验证方式和前面完全一样——跑那条 menu 命令，看你的工具有没有出现在该出现的能力分组里。没出现就是契约没实现对，这比翻自己的代码快。

还有一条不需要密钥的检查：

make test-contracts

README 把它标为契约测试、不需要 API 密钥。同样照抄自文档，我们没有运行过。

一句话的操作顺序

clone 下来之后，别急着描述你想要的视频。先跑 provider menu 看清手里有什么，需要细看某个工具的契约时再跑 envelope（记住文档自己标了它慢、输出量大）；对照 .env 那 13 行决定要不要补密钥；确认 Node 版本能不能覆盖你打算用的运行时。这几步做完，再去和 agent 谈需求，你至少知道它答应你的事情有没有底。

本文依据 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，请以仓库最新内容为准。安全相关做法请结合自身环境评估，本文不构成安全方案建议。