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

# MMAS-Interchange - 元宇宙交换格式（MUIF）

**元宇宙规范**

**文档编号：** MU-V2-ARCH-009  
**标题：** 元宇宙交换格式（MUIF）与语义指纹  
**文档类别：** 规范性  
**版本：** 2.0（草案）  
**状态：** 工作草案  
**规范性引用：** [MMAS-Core](../02-architecture/MMAS-Core.md)、[Versioning](../02-architecture/Versioning.md)、[Naming-Conventions](../02-architecture/Naming-Conventions.md)、RFC 8785（JSON Canonicalization Scheme）、RFC 2119  
**说明性引用：** [Validation](../02-architecture/Validation.md)、[MMAS-Package](../02-architecture/MMAS-Package.md)、[Extension-Model](../02-architecture/Extension-Model.md)  
**版权：** © Orkestron.AI  
**许可：** Apache-2.0

---

# 1. 目的

本文档定义**元宇宙交换格式（MUIF）** - 元模型正典的、机器可读的序列化形式 - 以及用于计算可复现**语义指纹**的确切**规范化算法**。

MUIF 是 [MMAS-Core](../02-architecture/MMAS-Core.md) 所定义抽象模型的具体面貌。它是校验、打包、迁移、联邦前置检查与工具链所依赖的基础制品：没有唯一的正典形态，整部规范所引用的语义指纹就无法在不同实现之间复现，「人工智能原生」与「机器可读」也只会停留在主张而非事实。

---

# 2. 适用范围

本文档规定：

- MUIF 文档模型及其序列化（JSON，允许 YAML）；
- 各原语与清单的 JSON Schema 定义；
- **语义**内容与**非语义**内容的划分；
- 规范化算法与语义指纹。

它不定义传输（见 [MUFP](../03-federation/MUFP.md)），也不定义打包与签名（见 [MMAS-Package](../02-architecture/MMAS-Package.md)）。

---

# 3. MUIF 文档模型

MUIF 文档编码的是 MMAS 的**组合层级**：

```text
Meta-Model (manifest)
  ├── Bundles ── Layers
  ├── Objects ── Properties
  ├── Relationships
  ├── Events
  ├── Contracts
  └── Projections
```

入口点是一份**清单**。每个原语都携带 `muifType` 判别符（`Object`、`Relationship`、`Event`、`Contract`、`Projection`）。

规范性的 JSON Schema（Draft 2020-12）位于 [`/schemas`](../schemas/)：

| 模式 | 原语 |
|--------|-----------|
| `manifest.schema.json` | 元模型包入口点 |
| `object.schema.json` | 对象 |
| `relationship.schema.json` | 关系 |
| `event.schema.json` | 事件 |
| `contract.schema.json` | 契约 |
| `projection.schema.json` | 投影 |
| `common.schema.json` | 共享定义（CSN、标识符、溯源，等等） |

MUIF 文档必须通过 `manifest.schema.json`（它引用其余各模式）的校验。

---

# 4. 序列化

- 正典序列化是 **JSON**（RFC 8259），UTF-8。
- **YAML** 1.2 可以用于撰写；它必须能无损转换为 JSON 模型。语义指纹是在 JSON 模型之上定义的，因此选择 JSON 还是 YAML 都不得影响指纹。
- 标识符与正典语义名称遵循 [Naming-Conventions](../02-architecture/Naming-Conventions.md)。

---

# 5. 语义内容与非语义内容

语义指纹只在**语义内核**之上计算。以下内容属**非语义**，必须排除在规范化之外：

- 对象键：`displayName`、`description`、`documentation`、`comment`、`label`、`labels`、`ui`、`assertedAt`、`assertionTime`、`generatedAt`、`lastModified`、`fingerprint`、`examples`、`$schema`、`$comment`；
- 任何以 `_` 或 `x-ui` 开头的键。

理由：更改人可读标签、描述、记录时间戳或自我声明的指纹，都不得改变模型的含义，因而也不得改变它的指纹。每份模式都在其描述中把这类字段标注为 **NON-SEMANTIC**。

---

# 6. 规范化算法

给定一份 MUIF 文档，正典形态按如下步骤产生。

1. **解析**该文档为抽象值（对象 / 数组 / 字符串 / 数字 / 布尔 / null）。
2. **投影到语义内核。**递归移除每一个非语义键（第 5 节）。移除取值为 `null`、空对象或空数组的键 - *缺席*与*为空*被视为等价。
3. **规范化取值。**
   - 字符串必须规范化为 Unicode **NFC**。
   - **对象键**必须按 Unicode 码位升序（序数）排序。
   - **数组必须按集合处理**：先对每个元素作规范化，再按其正典字符串的序数比较对元素排序。（v1.0 的核心模型不使用顺序有意义的序列；未来的修订可以引入显式的有序数组标记 - 见未来方向。）
   - 整数必须以最短十进制形式输出，不带前导零，也不带前导 `+`。其他数字遵循 RFC 8785（JSON Canonicalization Scheme）的数字格式。
4. **序列化**规范化后的树为正典 JSON：UTF-8、键已排序、无无关空白、字符串转义按 RFC 8785。
5. **散列。**对正典 JSON 的 UTF-8 字节计算 `SHA-256`。

**语义指纹**为：

```text
sha256:<lowercase-hex-of-the-sha256-digest>
```

两份语义内核相同的 MUIF 文档必须得出相同的指纹，无论序列化格式、键序、集合数组的元素顺序、空白与非语义字段如何。

---

# 7. 完整示例

参考示例 [`/examples/minimal-person`](../examples/minimal-person/) 以两种差别很大的序列化包含了同一个模型（`person.muif.json`，以及刻意重排并添加了额外非语义字段的 `person.variant.json`）。两者产出的指纹完全相同：

```text
sha256:a628b2afb96dc673f7e2f9161569e573fc70892d10a6997fad7aaa14b04a639d
```

这一点由参考工具 [`mu-fingerprint`](../tools/) 加以验证：

```text
mu-fingerprint examples/minimal-person/person.muif.json
mu-fingerprint examples/minimal-person/person.variant.json
# → identical sha256:a628b2af...b04a639d
```

---

# 8. 合规

当满足以下条件时，文档即**符合 MUIF**：

- 它通过 `manifest.schema.json` 及其所引用模式的校验；
- 每个原语都声明了自己的 `muifType`、`id` 与必填字段；
- 当它在 `metaModel.fingerprint` 中自我声明语义指纹时，该值等于第 6 节规范化算法所计算出的值。

元模型必须能够以 MUIF 交换，才能主张 **A4 已校验**或更高级别的 MMAS 合规（见 [MMAS-Conformance](../02-architecture/MMAS-Conformance.md)）。

---

# 9. 架构不变量

- 语义指纹必须只在语义内核之上计算。
- 指纹必须与序列化、键序、集合顺序、空白与非语义字段无关。
- 含义的改变必须改变指纹；格式或标签的改变不得改变它。
- `metaModel.fingerprint` 必须被排除在它自身的计算之外。

---

# 未来方向

- 对全部数字形态**完整遵循 RFC 8785**，并为规范化提供一套合规测试向量（用以充实语义测试套件）。
- 为数组顺序确实具有语义意义的少数情形提供**有序数组标记**。
- **签名的 MUIF / SDP**：在正典字节之上的分离式签名，从而支撑语义分发包（见 [MMAS-Package](../02-architecture/MMAS-Package.md)）。
- 一份正式的 **MMAS 元模型**（文法），由它生成各模式。

---

# 结语

> 无论怎样写下来，一个模型的含义都是同一个。MUIF 把这一点变得精确：一种正典形态、一枚指纹 - 这样两个系统在交换任何一条事实之前，就能确认彼此谈论的正是同一个含义。