三层知识架构：723 个 md 文件是怎么分层的

2026-08-09

把 OpenMontage 的仓库目录整个翻一遍，最直观的感受不是代码多，是 Markdown 多。全仓库 .md 文件我们实读数出来是 1084 个。这个体量下，「这个项目怎么组织知识」不是架构洁癖，是你能不能找到东西的问题。

README 给的答案是三层。这篇就把这三层拆开数一遍。

三层各回答一个问题

README 里这段分层写得很短，原文照抄是这样：

Layer 1: tools/ + pipeline_defs/     "What exists" — executable capabilities + orchestration
Layer 2: skills/                     "How to use it" — OpenMontage conventions and quality bars
Layer 3: .agents/skills/             "How it works" — external technology knowledge packs

三个引号里的短语是分层的全部要点：Layer 1 回答有什么，是可执行的能力加编排；Layer 2 回答在 OpenMontage 里该怎么用，是这个项目自己的约定和质量标准；Layer 3 回答这项外部技术本身是怎么回事，是技术知识包。

README 配的解释是：agent 读 Layer 1 知道有什么可用，读 Layer 2 知道 OpenMontage 希望怎么用，需要深度技术知识时读 Layer 3；每个工具都会声明它依赖哪些 Layer 3 skill。

这个划分为什么必须存在，得回到项目的职责边界。AGENT_GUIDE.md 原文写的是 Python = tools + persistence，并且明写 Python 代码里没有编排逻辑、创意决策、评审逻辑或 checkpoint 策略。既然这些东西不在代码里，它们就必须落在文本里；文本一多，就得分层。Rule Zero 那节的收尾金句说的也是同一件事：The intelligence is in the skills, not in improvised code.

723 是怎么数出来的，以及数不出来的部分

我们实读目录：skills/ 下 156 个 .md，.agents/ 下 567 个 .md，相加 723 个。README 自称的说法是 “700+ agent skill and production-knowledge files”，两者对得上。

需要说清楚两件事，免得这个数字被误用。

第一，723 只覆盖 Layer 2 和 Layer 3。Layer 1 的主体是 Python 文件和 YAML manifest，不在这个计数里。全仓库 1084 个 .md 减去这 723 个，还剩 361 个散在仓库其它位置，我们没有逐一归类。

第二，.agents/ 那 567 个是整个 .agents/ 目录的 .md 计数，而 README 的分层写的是 .agents/skills/。我们按目录数出来的就是这个数，怎么在子目录间分布没有再拆。这些 Layer 3 skill 的正文我们一份都没有读过，本文不会描述任何一份里写了什么。

Layer 1：有什么

Layer 1 是 tools/ 加 pipeline_defs/。

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。非 __init__.py 的 Python 文件实读为 130 个。

两个数字先摆清楚：README 架构图给 tools/ 标的注释是 “100+ Python tools”（README 自称），我们实读非 __init__.py 的 Python 文件是 130 个——文件数不等于工具数，这两个口径不是一回事，别互相换算。

真正可核实的差异在目录清单上：那张架构图只列了 video / audio / graphics / enhancement / analysis / avatar / subtitle 七个子目录，capture/、character/、publishers/、_comfyui/、_kling/ 这五个实际存在的目录不在图里。同一张图里 schemas/ 那行标的 “15 JSON Schemas” 也和实读计数不一致，那处本批另有一篇专门讲。以仓库当前状态为准，这些差异我不去推断原因，也不拿它评价项目。

pipeline_defs/ 放的是流水线 manifest，YAML 格式。它归在 Layer 1 而不是 Layer 2，是因为它属于「编排」而不是「怎么用」——manifest 描述的是这条流水线有哪些阶段、用哪些工具、有哪些评审标准和成功闸。

Layer 2：这个项目希望你怎么用

Layer 2 就是 skills/ 这 156 个 .md，实读分四个分区。

skills/core/ 6 个，对应核心工具：color-grading.md、ffmpeg.md、hyperframes.md、remotion.md、subtitle-sync.md、whisperx.md。

skills/meta/ 11 个，是流程侧的东西：animation-runtime-selector.md、bespoke-composition.md、capability-extension.md、checkpoint-protocol.md、creative-intake.md、onboarding.md、reviewer.md、skill-creator.md、taste-direction.md、video-reference-analyst.md、voice-performance-director.md。

skills/creative/ 实读列出 29 个 .md 加一个 prompting/ 子目录，覆盖的主题从 storytelling.md、typography.md、sound-design.md 这类创作技法，到 image-gen-usage.md、upscale-usage.md、lip-sync-usage.md 这类工具用法。

skills/pipelines/ 是 12 个子目录，一条流水线一个：animation、avatar-spokesperson、character-animation、cinematic、clip-factory、documentary-montage、explainer、hybrid、localization-dub、podcast-repurpose、screen-demo、talking-head。另有一份 skills/INDEX.md。

按数算一下：6 + 11 + 29 + 1 = 47，剩下的 109 个 .md 落在 skills/pipelines/ 的 12 个子目录和 creative/prompting/ 这两处，我们没有把它们再拆开数，所以这 109 个在两处之间怎么分我不下结论。能确定的是，逐个列得出名字的通用技法只占 Layer 2 的小头，大头在按子目录组织的那部分里。这和 Rule Zero 的要求是对上的——它要求逐阶段执行时，在该阶段做任何工作之前先读 skills/pipelines/<pipeline>/<stage>-director.md，一条流水线一个子目录、一个阶段一份导演 skill，本来就是会摊开成很多文件的写法。

需要重申边界：以上全是文件名清单。这些 skill 的正文我们没有读过，这里只按文件名说明它覆盖了哪些主题。

三层是靠什么串起来的

分层本身不产生行为，把三层接上的是 Rule Zero 那五个步骤，以及工具上的一个字段。

先看步骤。AGENT_GUIDE.md 里 Rule Zero 那节的加粗原文是 Every video production request MUST go through the pipeline system. No exceptions.，它要求 agent 依次做五件事：确定流水线（把请求匹配到 pipeline_defs/ 里的某一条，不清楚就问用户）、读 pipeline_defs/<pipeline>.yaml 这份 manifest、跑 preflight 通过 registry 发现可用工具并展示能力菜单、逐阶段执行且在每个阶段动手之前先读阶段导演 skill、调任何带 agent_skills 字段的工具前先读被引用的 Layer 3 skill。

把这五步按层归一下就很清楚：第 1、2、3 步全在 Layer 1——匹配流水线、读 manifest、从 registry 发现真实工具，问的都是「有什么」；第 4 步进 Layer 2，问「这个阶段在 OpenMontage 里该怎么做」；第 5 步才下到 Layer 3，问「这项外部技术本身怎么回事」。AGENT_GUIDE.md 另一节 “What OpenMontage Is” 给的核心循环也是同一个次序：选一条流水线 → 跑 preflight → 从 registry 发现真实工具 → 向用户呈现概念、工具计划、制作计划和成本 → 带 checkpoint 逐阶段执行。

换句话说，三层不是三个平行的资料库，是一条由粗到细、按需下沉的读取顺序。上面那层没确定，下面那层根本不知道该读哪一份。

再看那个字段。README 的分层解释里写「每个工具都声明它依赖哪些 Layer 3 skill」，落到契约里就是 Rule Zero 的第 5 步：使用任何带 agent_skills 字段的工具前，先读 .agents/skills/ 里被引用的 skill。原文说这些 skill 里有 provider 专属的提示词指导、参数优化和质量技法，能显著改善输出。AGENT_GUIDE.md 的 Do NOT 里也有对应的一条：不要在没读 Layer 3 skill 的情况下调生成类工具；文件最后的 What Not To Do 一节又写了一遍，并补了一句「查工具的 agent_skills 字段，读被引用的 skill，然后用那份指导来写 prompt」。同一件事在一份 714 行的契约里出现三次，可见它在这套设计里的位置。

除此之外，AGENT_GUIDE.md 里还有一节叫 Layer Map 的章节，下面挂着一个子标题 Layer 3 skills, by category。这两个标题本身就说明契约里有一份分层地图和一份按类目组织的 Layer 3 清单——正文我们没有读过，不展开。

一处可核查的落点：`paths` 段里没有 `.agents`

架构主张容易漂亮，所以我习惯回到配置文件看有没有硬痕迹。根目录 config.yaml 的最后一段是这样五个键：

paths:
  pipeline_dir: pipeline
  library_dir: library
  styles_dir: styles
  skills_dir: skills
  output_dir: output

Layer 2 在这里有名字——skills_dir: skills。pipeline_dir 的值是 pipeline，和 checkpoint 段里的 storage_dir: pipeline 是同一个值，但配置文件本身没有写这两个键是什么关系，我不替它补；能确认的是 Layer 1 的 pipeline_defs/ 和 tools/ 在这五个键里都没有对应项，Layer 3 的 .agents/ 同样不在。

这只是配置文件的实际内容，我不推断为什么这么设计。但对你有一个直接的操作含义：想通过配置改路径这条路，只在 skills_dir 这一层可用，其余几层的位置在这份配置里改不到。

你要改东西时该动哪一层

分层最实际的用处，是把「我想扩点功能」翻译成「我该改哪个目录」。README 给的贡献路径正好落在两层上。

加一个新工具（Layer 1）：在 tools/ 相应子目录下建一个 Python 文件，继承 BaseTool 并实现工具契约，registry 会自动发现它、不需要手动注册；如果这个工具需要使用指导，再补一个 skill 文件——补的这一份就落到 Layer 2 了。

加一条新流水线（Layer 1 + Layer 2）：在 pipeline_defs/ 建一个 YAML manifest，在 skills/pipelines/<your-pipeline>/ 建阶段导演 skill，然后引用既有工具或按需新增。

反过来推也成立：你只是想改「同一批工具下产出应该长什么样」，那是 Layer 2 的事，不必碰 Python；你想加一种仓库还不支持的外部技术能力，那绕不开 Layer 1。README 还指向 docs/ARCHITECTURE.md 作为完整技术参考，我们没有读过它的内容，只知道有这么一份。

最后一句限定

这套三层结构是文本组织方式加写给模型看的约束，不是自动生效的工程保障。契约写了「调工具前必须先读 Layer 3 skill」，不等于装好之后模型每次都会读；能不能落地，取决于你用的 agent 和它当时的上下文。这一点在你评估「723 个 md 到底值多少」时，值得先扣在前面。

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