简体中文

Omeria 专用格式说明

本文面向 Omeria 2 工程内部开发者，说明 .omeria 专用包格式的结构、读写流程与 API 约定。该实现位于 saveFor.swift，提供 SwiftUI FileDocument 读写与无 UI 的保存服务层 OmeriaSaveService。外部集成须遵守《Omeria 文件格式使用与授权条款》。

1. 格式概览

.omeria 是包格式（文件夹打包，非单一二进制），核心包括两部分：

manifest.json：笔记元信息与页面清单（唯一可信源）。
pages/：按顺序存放每页 PKDrawing 的二进制数据，文件名为零填充递增序号（0001.drawing、0002.drawing…）。

UTType 标识为：

				
					ExampleNote.omeria/
├─ manifest.json
└─ pages/
   ├─ 0001.drawing
   ├─ 0002.drawing
   └─ …

				
					{
  "version": 1,
  "id": "f2b3c2e4-8a1d-47a3-9c0b-ecb7e9910ab9",
  "title": "海边的素描",
  "updatedAt": "2025-11-01T16:42:00Z",
  "canvasStyle": "plain",
  "pageCount": 3,
  "pages": [
    { "file": "pages/0001.drawing" },
    { "file": "pages/0002.drawing" },
    { "file": "pages/0003.drawing" }
  ]
}

该清单确保笔记的可验证性和内部引用的一致性。

三、设计理念

.omeria 格式并非单纯的绘图容器，而是 Omeria 笔记系统的结构化载体。

它承载的不仅是视觉数据，还包括笔记在结构视图中的身份信息和画布风格设定。

这一设计允许用户：

在不同设备上以完全一致的视觉与逻辑结构打开笔记；
使用 iCloud 同步或导出功能在多个平台间安全迁移；
通过格式签名校验，防止外部软件对笔记进行破坏性修改。

四、兼容性与安全性

.omeria 文件仅能通过 Omeria 官方应用或获得 PersonaHome 授权的组件打开。
外部应用可在获得授权后读取文件内容，用于预览或索引，但不得自行写入、修改或生成新的 .omeria 文件。
未经授权的软件写入或转换的文件将被视为无效数据，可能无法在 Omeria 应用中正常加载。

PersonaHome 会持续更新文件签名与校验机制，以确保笔记数据的安全性与一致性。

五、开放性与授权政策

PersonaHome 公开 .omeria 文件的结构文档，鼓励开发者和研究者了解其技术理念，以促进更好的互通与合作。

但文件格式本身受版权法保护，属于 PersonaHome 的专有资产。

允许的行为：研究格式、阅读官方文档、通过授权 API 打开 .omeria 文件。
禁止的行为：逆向工程、模拟写入器、未经授权生成或修改 .omeria 文件。

六、未来发展

PersonaHome 将在后续版本中扩展 .omeria 格式以支持：

多媒体附件（音频、图片、语音标记）；
版本历史记录与协作标识；
数据签名验证机制，以确保跨端安全传输。

所有演进版本都将保持对旧版格式的兼容性，确保用户笔记的长期可读性与安全。

七、版权声明

.omeria 文件格式及其文档的所有知识产权均归 PersonaHome 所有。

任何未经许可的再发布、修改或商用行为均可能构成侵权。

使用 .omeria 格式即表示您已阅读并同意相关授权条款。