> 译文仅供阅读便利。具有规范效力的是英文原文。

# 模型遍历与保留位置

**元宇宙规范**

**文档编号：** MU-V2-ARCH-017  
**标题：** 元模型架构标准 - 无损遍历与保留位置  
**文档类别：** 规范性  
**版本：** 2.0（草案）  
**状态：** 工作草案  
**规范性引用：** MMAS-Core、MMAS-Package、Versioning、Validation、Data-Mastership  
**说明性引用：** Traceability、AI-Agent-Guide、Repository-Structure  
**版权：** © Orkestron.AI  
**许可：** Apache-2.0

---

# 1. 目的

[MMAS-Package](MMAS-Package.md) 定义了元模型仓库中*每样东西放在哪里*。本文档定义仅靠布局无法给出的两项保证：

1. **无损遍历。**读者（人或人工智能代理）必须能够逐个 bundle、逐层地走遍整个模型，**恰好一次地访问每个文件**，知道**每个文件是什么含义**，并**证明没有任何遗漏**。
2. **保留位置。**凡不属于语义定义的内容（原始来源数据、正典来源文本、生成的制品、操作说明）都必须存放在含义预先约定的保留位置，使读者永远无需猜测某个文件是什么。

再加上声明*每个数据集的真相归谁所有*的 [Data-Mastership](Data-Mastership.md)，这就让元模型完全可被机器读取：无所遗失、无所歧义、无所不明来路。

---

# 2. 适用范围

本规范适用于：

- 元模型仓库与语义分发包；
- 仓库、bundle 与层三级的清单；
- 模型仓库中所含的全部文件，无一例外；
- 遍历器：任何枚举模型内容的工具或代理。

它不重新定义对象、关系、事件、契约或投影的语义；它治理的是承载它们的文件如何被找到、排序与分类。

---

# 3. 设计原则

- **唯一入口。**每次遍历都从同一个地方开始；不存在关于「从哪儿开始」的口口相传。
- **声明的顺序。**阅读顺序是数据而不是惯例：清单声明它，遍历器遵循它。
- **完全分类。**每个文件都被分类。凡是无法从清单与本规范判定其含义的文件，都是缺陷，而不是奇趣。
- **含义随结构而行。**每个被枚举的单位都带有声明的含义；读者不该为了弄清一个文件是哪一类东西而不得不打开它。
- **手写、采集与生成的内容绝不混放。**它们的生命周期规则不同，因而所在位置也不同。

---

# 4. 入口点

合规的仓库必须能够从其根目录中恰好两个文件开始阅读：

1. **`BOOTSTRAP.md`** - 操作说明：如何阅读这个模型、按什么顺序、用什么工具，以及代理在这里被期望做什么、不做什么。遍历器应当先读它。`BOOTSTRAP.md` 可以把扩展说明（代理提示词、上手指引、检查清单）委托给 `bootstrap/` 目录。bootstrap 内容不得定义语义；它只解释，从不声明。
2. **`manifest.yaml`** - [MMAS-Package](MMAS-Package.md) §5 所定义的机器入口点，本文档以遍历声明（§5）与排除清单（§7）对其加以扩展。

若 `BOOTSTRAP.md` 缺失，遍历器仅凭清单继续；清单缺失则使该仓库不合规。

已经使用生态专属入口文件（例如 `README.md`、`AGENTS.md` 或 `CLAUDE.md`）的仓库，应当把它做成指向 `BOOTSTRAP.md` 与 `manifest.yaml` 的薄指针，而不是第二个真相来源。

---

# 5. 遍历声明

遍历顺序自上而下声明：

- **仓库清单**必须声明按阅读顺序排列的 bundle 列表（`bundles:`）。
- 每份 **bundle 清单**（`bundle.yaml`）必须声明该 bundle 单一的语义职责，以及其各层的有序列表。
- 每份**层清单**（`layer.yaml`）必须枚举该层的内容：文件或 glob 模式，各自带有一个**种类**（§8）与一句话的**含义**。

枚举可以**集中进行而非逐层进行**：若某仓库的文件名按约定携带种类（例如 `{kind}-{id}-{memo}.md`），它可以在仓库清单中一次性声明分类，形式是一组有序的匹配规则（`kind_rules`）：每条规则把一个 glob 模式映射到一个种类与一个来源（§9）；首条匹配的规则胜出。在这类规则中，占位符 `{prefix}` 表示文件名中第一个分隔符之前的片段，因此像 `kind: "object/{prefix}"` 这样的一条规则就能分类整套命名约定。就覆盖检查（§7）而言，集中规则等价于逐层枚举；没有任何规则匹配到的文件，无论哪种方式都是孤儿。

排序规则：

- bundle 必须排成这样的顺序：某个 bundle 出现在它所依赖的每一个 bundle **之后**（基础在先）。bundle 之间的循环依赖不合规。
- bundle 内部的各层必须以同样方式排序。
- 允许前向引用（某文件提到遍历中稍后才定义的概念），但*声明*顺序必须仍然是依赖在先，好让一次顺序通读能在概念被大量使用之前先读到它的定义。

依次按声明顺序访问 bundle、然后是层、然后是被枚举文件的遍历器，执行的就是**正典遍历**。两个遍历器对同一仓库版本执行正典遍历时，必须以相同顺序访问相同的文件。

---

# 6. 保留位置

除 [MMAS-Package](MMAS-Package.md) §4 的结构性目录（`bundles/`、`imports/`、`mappings/`、`schemas/`、`examples/`、`diagrams/`、`docs/`、`tools/`）之外，本文档保留以下位置。每一处都有固定的默认含义；遍历器可以直接依赖它而无需额外声明。

| 位置 | 含义 | 生命周期 |
|----------|---------|-----------|
| `BOOTSTRAP.md`、`bootstrap/` | 面向读者与代理的操作说明：如何阅读、更新与校验这个模型 | 手写 |
| `canon/` | 本模型视为基准真相的正典来源文本：学说、已采纳的决定、规范性输入、来源规范 | 手写或采纳；版本化；从不生成 |
| `raw/` | 来自外部系统的未加工捕获：导出、转储、逐字记录、抓取结果 | 采集；**绝不**手工编辑 |
| `artifacts/` | 派生的、可重新生成的产出：编译后的视图、渲染的文档、计算出的索引、报表 | 生成；**绝不**手写 |
| `sources.yaml` | 数据主控登记表：每个数据集的记录系统（见 [Data-Mastership](Data-Mastership.md)） | 手写 |

规则：

- **`canon/`** 存放模型所*论及*或所*受约束*的文本，前提是这些文本必须随模型一同流转。层必须引用 canon 文件而不是转述它们；若某条层内陈述与某段 canon 文本冲突，在该模型之内以 canon 文本为准。
- **`raw/`** 必须组织为 `raw/<来源系统>/<数据集>/...`。每个数据集目录都必须带有溯源附属文件（`_provenance.yaml`：来源系统、范围、抽取时间、抽取工具、记录条数）。原始内容是证据；手工订正会毁掉它的证据价值，属于不合规。订正应在来源系统中进行（随后重新采集），或在语义层中以带注记的偏差形式进行。
- **`artifacts/`** 中的条目必须声明其生成器与输入（一个附属文件或一行文件头即可）。合规仓库可以把 `artifacts/` 整个删掉再重建；若做不到，说明有东西放错了地方。
- 仓库不应当为这些用途另造平行位置（`_raw/`、`generated/`、`sources/` 之类）。凡存在历史遗留布局，清单必须把它们映射到这些保留含义上。

---

# 7. 完整性规则（不落下任何文件）

仓库中的每个文件都必须恰好落入三类之一：

1. **被枚举** - 与某份层清单的内容声明（§5）相匹配，或是 MMAS-Package §4 中带有既定角色的结构性目录；
2. **保留位置** - 位于 §6 的某个保留位置之下，继承其默认含义；
3. **被排除** - 与清单的排除列表（`exclude:`）相匹配，该列表列出没有语义内容的基础设施文件（版本控制内部文件、CI 配置、编辑器设置、构建缓存）。

**覆盖检查**：遍历器必须能够把仓库的完整递归文件清单与这三类的并集加以比对。不属于任何一类的文件（「孤儿」）与同时属于多于一类的文件（「歧义」）都是校验失败。覆盖检查是 [Validation](Validation.md) 中**结构校验（V1）**的一部分。

排除列表是一项声明，而不是垃圾场：排除某个文件，就是断言它**不承载模型含义**。为了通过覆盖检查而排除语义内容，属于不合规。

---

# 8. 文件种类

每个被枚举的文件都必须带有一个种类。基础词汇表：

`object` · `relationship` · `event` · `contract` · `projection` · `canon` · `raw` · `artifact` · `mapping` · `import` · `schema` · `example` · `diagram` · `doc` · `tool` · `bootstrap` · `manifest`

种类回答的是「这个文件*在模型中*是什么」，而不是「它是什么格式」。一个 CSV 可以是 `raw`（导出）、`artifact`（计算出的索引）或 `object`（定义表）；决定读者如何对待它的是种类，而不是扩展名。生态可以用子种类（`object/policy`、`doc/adr`）细化该词汇表，但必须保留基础种类作为前缀。子种类可以借助 §5 的 `{prefix}` 占位符，从已声明的命名约定中机械地推导出来。

---

# 9. 手写、采集、生成

与种类正交，每个文件都恰有一个**来源**：

- **手写** - 由人，或由充当作者的代理写成；就地编辑；像代码一样接受评审。
- **采集** - 由流水线从外部系统捕获；通过重新采集来替换；绝不就地编辑。
- **生成** - 从本仓库中的其他文件计算得出；通过重新生成来替换；绝不就地编辑。

对于保留目录（§6），来源由位置隐含；其他地方则必须在层清单中声明。就地编辑采集或生成的文件属于不合规：该修的地方在来源系统或生成器那里。

正是这一区分让主控（见 [Data-Mastership](Data-Mastership.md)）在实践中可被强制执行：文件的来源立刻告诉读者，*这一份*副本是否有可能成为真相。

---

# 10. 正典遍历（说明性）

合规的遍历器：

1. 读取 `BOOTSTRAP.md`（背景、约束、本地约定）。
2. 读取 `manifest.yaml`：身份、版本、bundle 顺序、排除列表。
3. 读取 `sources.yaml`：哪些数据集由此处主控，哪些是镜像（连同新鲜度）。
4. 按声明或引用访问 `canon/`，使基准真相在解释之前先被载入。
5. 按声明顺序遍历各 bundle；在每个之内按声明顺序遍历各层；在每层之内遍历被枚举文件，先读种类与含义，再读内容。
6. 当某层引用 `imports/` 与 `mappings/` 时予以解析。
7. 把 `raw/` 当作证据（查阅，而非照搬），把 `artifacts/` 当作可丢弃的视图。
8. 执行覆盖检查（§7），报告孤儿、歧义与陈旧镜像。

当每个文件都有着落、每个数据集的权威都已知时，遍历即告完成。

---

# 11. 人工智能原生要求

合规的仓库必须让人工智能代理在没有带外知识的情况下能够：

- 找到入口点与操作说明；
- 以确定性的顺序枚举全部内容；
- 就任何文件说出它的种类、来源与一句话含义；
- 证明覆盖：说出它没有读的每个文件及其原因（被排除、生成的、原始证据）；
- 分清它可以编辑什么（手写的、处于模型主控之下）与绝不可编辑什么（采集的、生成的、由外部主控的）。

无法满足最后一条的代理，应当拒绝对该模型执行写操作。

---

# 12. 架构不变量

遍历与布局必须保留：

- 语义身份与所有权；
- 采集与生成内容的溯源；
- 唯一入口点这一性质；
- 正典遍历的确定性；
- 宪法合规。

布局与遍历绝不得重新定义语义含义；它们只是让含义变得可及。

---

# 13. 未来方向

参考遍历器（`mu-walk`）是现有工具的自然搭档：它会执行正典遍历，输出机器可读的遍历报告（文件、种类、来源、覆盖结果、镜像新鲜度），并充当本文档的可执行定义。遍历报告还可以成为语义分发包的一部分，让消费方在信任某个包之前先核验其完整性。

---

# 结语

一个元模型的可信程度，取决于读者能否确知自己已经看完了它的全部，并理解了每一部分是什么。

本标准把这种能力从勤勉变成契约：一个入口点、一份声明的顺序、对文件的完全分类、为说明、canon、原始证据与派生制品预留的位置，以及一项使无声遗失成为不可能的覆盖检查。