Python 只提供工具和持久化：编排逻辑为什么不写在代码里

2026-08-09

在一个视频制作项目里找编排逻辑，正常的找法是搜关键词：搜 stage、搜 pipeline.run、搜状态机。在 OpenMontage 里这么找会扑空，而且不是因为命名风格特别，是因为那部分东西根本不在 Python 里。

README 用一句话把这条分界线划出来了：Python provides tools and persistence.（Python 提供工具与持久化。）这篇就只讲这一句话——它到底划走了什么，留下了什么，以及你要改这个系统的行为时该去动哪个文件。

先看这条线的另一半写着什么

AGENT_GUIDE.md 里的 “What OpenMontage Is” 一节说得比 README 更直接。它把 OpenMontage 定义成一个指令驱动的视频制作系统，AI agent 就是智能本身：agent 读指令（流水线 manifest + 阶段导演 skill + meta skill），用工具驱动流水线。然后是那句明写的否定——Python 代码里没有编排逻辑、创意决策、评审逻辑或 checkpoint 策略，这些决策由 agent 在指令引导下做出。

配套的循环是 5 步：选一条流水线 → 跑 preflight → 从 registry 发现真实工具 → 向用户呈现概念、工具计划、制作计划和成本 → 带 checkpoint 逐阶段执行。

注意这 5 步里的动词分布。「选」「呈现」是判断，「发现」「checkpoint」是执行。前者在文本里，后者在 Python 里。README 那张流程图也是同一个切法：agent 读 manifest（YAML）、读阶段导演 skill（Markdown）、调 Python 工具、用 reviewer skill 自审、把状态 checkpoint 成 JSON、交给你批准、过合成前的校验闸、渲染、渲染后再自审。整条链上 Python 出现在「调工具」「checkpoint」「渲染」三处，剩下每一个「判断这样行不行」的位置都是 agent 读文本自己做的。

而 README 对决策留痕的说法是：每个决策都会被记录，含考虑过的备选项、置信度分数和每次选择背后的理由；checkpoint 出来的 JSON 是可恢复的，带决策日志和成本快照。

被搬走的那一半，体积在文本里

搬走之后总得有地方放。README 把知识分成三层：Layer 1 是 tools/ 加 pipeline_defs/，回答「有什么」；Layer 2 是 skills/，回答「OpenMontage 希望你怎么用」；Layer 3 是 .agents/skills/，回答「这项外部技术本身是怎么回事」。

我们实读目录数出来的量级是这样的：skills/ 下 156 个 .md，.agents/ 下 567 个 .md，相加 723 个，和 README 自称的 “700+ agent skill and production-knowledge files” 对得上；全仓库 .md 文件共 1084 个。作为对照，tools/ 下非 __init__.py 的 Python 文件实读为 130 个。

一个视频项目里 Markdown 文件数量是 Python 文件的好几倍——这不是文档写得勤快，这是架构的直接结果。既然评审标准、质量闸、每个阶段怎么做都不许写进代码，它们就只能以文本形式存在。skills/ 内部分四类也印证这一点：core/ 6 个是核心工具知识，meta/ 11 个里有 reviewer.md 和 checkpoint-protocol.md，creative/ 是创意技法，pipelines/ 下 12 个子目录一条流水线一套阶段导演 skill。评审协议和 checkpoint 协议都躺在 meta/ 里，是 Markdown，不是类。

需要说明的是，除了本文明确引用的几节，这些 skill 文件的正文我们都没有读过，这里只按文件名和目录说明它覆盖了哪些主题。

留在 Python 这一侧的是什么

反过来看更清楚。lib/ 被 README 标为 Core infrastructure，实读的文件名清单里有 checkpoint.py、config_model.py、env_loader.py、paths.py、pipeline_loader.py、events.py、corpus.py、media_profiles.py，也有 scoring.py、slideshow_risk.py、delivery_promise.py、variation_checker.py、verify_scene_pacing.py 这些名字带判定意味的模块。

把这份清单和上面那句「Python 里没有编排逻辑」放在一起读，能看出这条线其实划得挺细：能被写成确定性计算的判定留在 Python，需要看着素材做取舍的判定留给 agent。 README 给 lib/ 那行的注释是 Core infrastructure (config, checkpoints, pipeline loader)：manifest 的装载与状态的落盘在 Python 这边，但 manifest 里写什么、该选哪条、什么时候该停下来问人，按 AGENT_GUIDE.md 的分工都不归代码管。这几个文件的具体实现我们没有读过（scoring.py、slideshow_risk.py、delivery_promise.py 的内部数值本批另有专篇细讲），这里只按文件名说明它们在这条分界线上的位置。

tools/ 那一侧的契约更简单。README 给的「加一个新工具」是 4 步：在 tools/ 相应子目录下建一个 Python 文件、继承 BaseTool 并实现工具契约、registry 自动发现它（不需要手动注册）、若工具需要使用指导再加一个 skill 文件。「加一条新流水线」是 3 步：在 pipeline_defs/ 建一个 YAML manifest、在 skills/pipelines/<your-pipeline>/ 建阶段导演 skill、引用既有工具或按需新增。

这两组步骤放一起看，本文的题目就有答案了：加能力要写 Python，加流程不用写 Python。 而且注意第四步——新工具的「使用指导」是另一个文件，Python 文件里只放怎么调用，不放什么时候该调用。

持久化那一半落在 config.yaml 里也能查到。checkpoint 段只有两行：

checkpoint:
  policy: guided                 # guided | manual_all | auto_noncreative
  storage_dir: pipeline          # relative to project root

默认策略是 guided，另两个可选值是 manual_all 和 auto_noncreative，状态写在项目根下的 pipeline 目录。策略只有三个枚举值，具体每个创意闸停不停、怎么向你呈现，是协议文本的事。同一份配置里输出默认值也是硬编码的一小段——mp4 容器、libx264、aac、1920x1080、30 fps、CRF 23，这些属于典型的「能确定就确定下来」的部分。

这种切法要你付出什么

好处是 README 自己说的：所有创意决策、编排逻辑、评审标准和质量标准都活在可读的指令文件里，你可以检查它们、改它们。想知道某个阶段凭什么判定通过，去读那个 -director.md，不用读代码。

代价有三处，值得在上手前认清楚。

第一，规则是写给模型看的提示词，不是工程保障。 AGENT_GUIDE.md 的 Rule Zero 加粗写着 Every video production request MUST go through the pipeline system. No exceptions.，配套的 Do NOT 也很具体：不许写临时 Python 脚本直接调工具、不许跳过流水线直奔 API 调用、不许没读阶段导演 skill 就开始生成素材、不许绕过 preflight / checkpoint / review。但既然没有代码编排器，这些 MUST 和 Do NOT 就没有一个 Python 层去强制执行——它们是指令，能不能落地取决于你用的 agent 和它当时的上下文。契约里连 “Present Both Composition Runtimes (HARD RULE)” 这种标题都写成硬规则了，恰恰说明它需要靠文本反复强调。

第二，行为的可复现性和你的 agent 绑定。 代码编排器的好处是同样输入走同样分支；指令驱动的系统里，同一条流水线在不同 agent、不同上下文长度下的执行未必一致。这不是缺陷指控，是这种架构的固有属性，AGENT_GUIDE.md 那 714 行、46 个标题的篇幅本身就是在对冲这件事。

第三，你得真的去读文本。 这套设计把可审查性交给了你。如果你的用法是「让 agent 自己看着办」，那么 723 个 skill 文件对你的实际价值，和它们对一个愿意逐条读契约的人的价值，不是一回事。

几处可核查的边界

顺着这条分界线看，仓库里有几处前后写法不一致，值得如实记下来，不做延伸。

config.yaml 的 LLM provider 注释里已经列了 ollama，而 README 明写通过 Ollama 和 LM Studio 支持本地 LLM 是 “Coming soon”。同一件事，配置注释与 README 两处口径不一致，以仓库当前状态为准——哪一处更准确，我们不推断，也不据此说它「其实已经能用」。

README 的架构目录树里 tools/ 下只挂了 video / audio / graphics / enhancement / analysis / avatar / subtitle 七个子目录，我们实读还有 capture/、character/、publishers/、_comfyui/、_kling/；同一张图里 schemas/ 那行标的是 “15 JSON Schemas”，和我们实读目录数出来的数量对不上。这两处差异本批另有专篇细说，这里只陈述事实：README 的架构图是简化过的，两处写的不一样，以仓库当前状态为准，我不推断原因，也不拿它评价项目。

最后提两件与本文主题相关的边界事实。README 列了 5 段演示视频，其中 4 段标了金额（另一段没标），这些金额是项目方在 README 中自行标注的成本，不是我们验证过的数据，也不能拿来推算你自己做一条要花多少钱；config.yaml 的预算段默认是 warn 模式而不是 cap，单次动作审批阈值写的是 single_action_approval_usd: 0.50，把这几行读明白也不等于「配好就不会超支」——按这套架构的分工，这些字段是阈值与提示，真正停不停仍然落在人工审批那一环，具体行为取决于你的 agent 怎么执行契约。至于许可，OpenMontage 用的是 AGPL-3.0，和常见的 MIT、Apache-2.0 不是一类，你打算怎么用，请以官方 LICENSE 原文为准。

本文依据 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 原文为准，本文不构成法律意见。安全相关做法请结合自身环境评估，本文不构成安全方案建议。