OpenMontage 的目录与 README 架构图对不上：五个 tools 子目录没写进去

2026-08-09

看一个大仓库，多数人第一步是照着 README 里那张目录树建立心智地图。OpenMontage 的 README 也给了这么一张图，画得挺清楚：tools/ 下挂七个子目录，skills/ 下挂四个，旁边配着 pipeline_defs/、schemas/、styles/、remotion-composer/、lib/、tests/。

问题是，把这张图当账本用会漏东西。我们把它和实读的目录逐层对了一遍，差在几个很具体的地方。

先把两份清单摆在一起

README 架构图这一段的原文是这样的：

OpenMontage/
├── tools/              # 100+ Python tools (the agent's hands)
│   ├── video/          # 13 video gen tools + compose, stitch, trim
│   ├── audio/          # 4 TTS providers + Suno/ElevenLabs music, mixing, enhancement
│   ├── graphics/       # 9 image/graphics generation tools + diagrams, code snippets, math
│   ├── enhancement/    # Upscale, bg remove, face enhance, color grade
│   ├── analysis/       # Transcription, scene detect, frame sampling
│   ├── avatar/         # Talking head, lip sync
│   └── subtitle/       # SRT/VTT generation
│
├── pipeline_defs/      # YAML pipeline manifests (the agent's playbook)
├── skills/             # Markdown skill files (the agent's knowledge)
│   ├── pipelines/      # Per-pipeline stage director skills
│   ├── creative/       # Creative technique skills
│   ├── core/           # Core tool skills
│   └── meta/           # Reviewer, checkpoint protocol
│
├── schemas/            # 15 JSON Schemas (contract validation)
├── styles/             # Visual style playbooks (YAML)
├── remotion-composer/  # React/Remotion video composition engine
├── lib/                # Core infrastructure (config, checkpoints, pipeline loader)
└── tests/              # Contract tests, QA integration tests, eval harness

我们实读 tools/ 目录，列出来是这些：

_comfyui/  _kling/  analysis/  audio/  avatar/  capture/  character/
enhancement/  graphics/  publishers/  subtitle/  video/
base_tool.py  cost_tracker.py  google_credentials.py  tool_registry.py

两份一比，README 那七个（video、audio、graphics、enhancement、analysis、avatar、subtitle）都在，但实际目录里另有五个架构图没有列出来：capture/、character/、publishers/、_comfyui/、_kling/。也就是说，README 的架构图是简化过的版本，不是完整目录快照。

需要说清楚的是，这五个目录里的实现我们一行都没有读过，这里只能指出「它们存在」，不能替它们描述职责。按名字猜内容正是这类文章最容易出事的地方，我们不猜。

架构图里还有四个直接躺在 tools/ 根下的 Python 文件同样没进图：base_tool.py、cost_tracker.py、google_credentials.py、tool_registry.py。这几个名字对读代码的人价值不低——README 讲的贡献方式是，新增工具就在 tools/ 相应子目录下建一个 Python 文件、继承 BaseTool 并实现工具契约，然后 registry 自动发现它，不需要手动注册；需要使用指导时再补一个 skill 文件。工具是被自动发现的，那么目录内容随时会长，架构图是不是最新的，本来就是一件需要每次核对的事。

`character/` 这条能三处对上

五个漏网目录里，character/ 有一条可以交叉印证的线索，值得单独说。

仓库里有一条名为 character-animation 的流水线：skills/pipelines/ 的 12 个子目录里有它，pipeline_defs/ 里也有对应的 manifest。而 schemas/artifacts/ 下有四个 schema 的名字正好指向同一件事：character_design、character_qa_report、pose_library、rig_plan。加上 tools/character/ 这个目录，同一条能力在工具层、流水线层和契约层三处都留下了实体。

这里同样只到名字为止：这四个 schema 的内部字段我们一个都没有读过，skills/pipelines/character-animation/ 里的 skill 正文也没读，所以「这条流水线具体怎么跑」不在本文能讲的范围里。能说的是结构上的事实——它不是一个只出现在某个角落的孤立目录。

根目录也有两处差集

把视线从 tools/ 抬到仓库顶层，实读结果是这些：

AGENTS.md  AGENT_GUIDE.md  CLAUDE.md  CODEX.md  CONTRIBUTING.md  COPILOT.md  CURSOR.md
LICENSE  Makefile  PROJECT_CONTEXT.md  PROMPT_GALLERY.md  README.md  README_zh-CN.md
assets/  backlot/  config.yaml  diagram.png  docs/  ink-theater/  lib/  pipeline_defs/
remotion-composer/  render-demo.sh  render_demo.py  requirements-dev.txt  requirements-gpu.txt
requirements.txt  schemas/  scripts/  setup.py  skills/  styles/  tests/  tools/

架构图列出的那几个（pipeline_defs/、skills/、schemas/、styles/、remotion-composer/、lib/、tests/）确实都在。架构图里没写、但根目录确实存在的两个目录是 backlot/ 和 ink-theater/。后者与 README 的 Style Playbooks 一节里提到的手绘涂鸦动画路线同名，skills/creative/ink-theater.md 这个文件也存在。这两个目录的内部实现我们没有读过，不展开。

还有一个根目录条目值得注意：docs/。架构图里没有它，但 README 正文另外指了三份参考——docs/ARCHITECTURE.md（README 称之为完整技术参考，525 行）、docs/PROVIDERS.md（README 称之为完整 provider 指南，含配置、定价、免费额度）和根目录的 AGENT_GUIDE.md（agent 契约）。docs/ 实读还有 PR_REVIEW_GUIDE.md、SPONSORS.md、apple-silicon-mps.md、comfyui-adapter-plan.md，以及 images/、stage-gates/ 两个子目录。前两份技术文档的正文我们没有读过，这里只是指路：如果你需要的是完整目录级的技术参考，README 的架构图本来也不是它该承担的角色。

顺带一提 lib/：架构图给它的注释是 “Core infrastructure (config, checkpoints, pipeline loader)“，实读列出的是 19 个 Python 文件（含 __init__.py）加一个 providers/ 子目录。其中 scoring.py、slideshow_risk.py、delivery_promise.py 是本批我们读过内容的三个（分别对应 provider 评分、幻灯片风险和交付承诺，各有专篇细讲）；其余像 checkpoint.py、pipeline_loader.py、config_model.py、corpus.py、events.py 这些，我们只按文件名提及，没读实现。一个注释里的三个词，底下是十几个模块加一个子包——这也是简化图和实际目录之间的常见落差。

数字侧：哪些对得上，哪些对不上

目录之外，架构图和 README 正文里还有一批计数说法。我们逐条数了一遍，结果分成两半。

对不上的：

架构图里 schemas/ 那行标的是 “15 JSON Schemas”。我们实读 schemas/ 目录，数出 24 个 .json 文件。两者不一致，以仓库当前状态为准。这 24 个文件的名录另有专篇在讲，本文不铺开。
架构图里 tools/audio/ 那行的注释写的是 “4 TTS providers”，而 README 正文的 TTS 表格是 5 行、自称 5 个 provider。这两处出自同一份 README，写的不一样。TTS 那张表本身有专篇细拆，这里之所以要提，是因为它同样是这张架构图注释里的一个计数，属于本文核查的对象。
架构图给 tools/ 的整体注释是 “100+ Python tools”。我们能数的是文件：tools/ 下非 __init__.py 的 Python 文件实读为 130 个。文件数不等于工具数，所以这一条我们判定不了吻合与否，只报文件数。

对得上的：

README 自称 “700+ agent skill and production-knowledge files”。我们实读 skills/ 下 156 个 .md、.agents/ 下 567 个 .md，相加 723，与这个说法吻合（全仓库 .md 共 1084 个）。
README 自称 “12 production pipelines”。skills/pipelines/ 实读 12 个子目录；pipeline_defs/ 有 13 个 YAML，去掉 framework-smoke 后是 12。吻合。
架构图给 skills/ 挂的四个子目录 pipelines/ / creative/ / core/ / meta/，实读都在，分别是 12 个子目录 / 29 个 .md 加一个 prompting/ 子目录 / 6 个 / 11 个，另有一份 skills/INDEX.md。

顺带把 README 贡献说明的另一半也放在这里：加一条新流水线是三步——在 pipeline_defs/ 建一个 YAML manifest、在 skills/pipelines/<your-pipeline>/ 建阶段导演 skill、引用既有工具或按需新增。这三步落下去，pipeline_defs/ 的 YAML 数和 skills/pipelines/ 的子目录数就会一起变。所以上面每一个计数都只是核对日那一刻的快照，你真要用，就在自己手上那份仓库里重数一遍。至于 README 的数字和实读结果为什么对不上，我们不推断。

顺便把架构图里那行 “Core tool skills” 落到具体文件：skills/core/ 实读 6 个 .md，分别是 color-grading.md、ffmpeg.md、hyperframes.md、remotion.md、subtitle-sync.md、whisperx.md。这些文件的正文我们没有读过，列出来只是说明这一格覆盖了哪几个主题。

按事实说到这里就该停：以上全部是我们数出来的客观结果，我们不推断作者为什么没同步，也不拿这些差异去评价这个项目的质量或可信度。

一个值得记住的区分

把这批核查结果并排看，会浮出一条挺清晰的分界：对不上的基本都是「计数类描述」——多少个 schema、多少个 TTS provider、多少个工具；而治理侧的具体数值，文档和代码是逐项吻合的。

三个例子：README 讲的 7 维评分权重 30/20/15/15/10/5/5，与 lib/scoring.py 第 38-44 行的实现逐项一致，七项相加正好 1.00；README 讲的预算默认值（总额 $10、单次动作审批阈值 $0.50、observe/warn/cap 三种模式），与根目录 config.yaml 的 budget 段逐项一致；README 讲的幻灯片风险 6 维分析，在 lib/slideshow_risk.py 的模块 docstring 里不但是 6 维，还给出了更具体的判定门槛（< 2.0 强、< 3.0 可接受、< 4.0 需修改、≥ 4.0 失败）。

对使用者的实际意义只有一句：架构图当地图看，目录清单当账本看。 你要判断某个能力在不在，去数目录、去让 registry 自己报；你要引用某个治理阈值，去翻 config.yaml 和 lib/ 里对应的模块。两件事用两套依据，别互相代替。

顺带说一句本文的边界：上面所有目录清单和计数都是我们在核对日读文件系统数出来的，我们没有安装或运行过这个系统。仓库还在更新，工具又是被 registry 自动发现的，你今天 clone 下来数出的数字与本文不同是完全正常的——真正的口径永远是你手上那份仓库。

本文依据 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，请以仓库最新内容为准。