opf

Open Presentation Format (OPF) 是一种可移植、人类可读的 JSON 文档格式，用于幻灯片演示文稿。本仓库是该格式规范、JSON Schemas、目录预设、示例、生成的开发人员类型、本地验证工具以及未来渲染/编辑/转换工具包规划文档的权威所在地。它在 npm 上以 @openpresentation/opf 发布，目前处于预稳定阶段（0.x 版本，在 1.0 版本之前的次要版本之间预计会有破坏性变更），采用 MIT 许可证。 动力：.pptx 是一个 XML 压缩包，人类难以进行 diff 对比，模型难以可靠地读写，git 也难以进行有意义的跟踪，导致每次更改看起来都像二进制块。OPF 是纯 JSON —— 在编辑器中可读，模型无需通过示例猜测 Schema 即可写入，并且可以与其他工作一起在版本控制中进行跟踪。其明确目标是让 LLM 参与演示文稿的创作（叙事结构、框架、数据分析、图表建议、修订），而不是与标记标签作斗争。 约定与命名：完整的演示文稿 OPF 文档是名为 *.opf.json（例如 board-review.opf.json）的 JSON 文件。项目建议不要使用纯 *.opf 扩展名，因为它已被其他文档和项目格式占用。第三方工具可以使用 Open Presentation Format 名称及其 Schemas、目录、包和本地工具来读取、写入、验证、渲染、转换和描述支持情况，而无需采用特定产品的品牌。 JavaScript/TypeScript 包的功能：它从 spec/ 导出规范的 Schemas 和捆绑的目录记录；一个用于包可寻址规范内容的类型化原始规范文件清单；以 Presentation 为顶层类型的生成 TypeScript 类型；以及针对 OPF JSON 和目录记录的本地验证。验证将返回有效性及建议性警告（例如未知的目录 ID）。该包提供针对 Schemas、目录、规范文件、验证器和类型的聚焦子路径导入，引擎或解析器可以直接导入原始 JSON Schemas。该包还公开了纯组合几何结构，以便下游库共享布局行为。它明确不执行 .pptx 的渲染或解析，不使用 AI 生成内容，不获取远程目录，不调用托管 API，也不提供托管服务。 本地工具：一个可安装的 MIT 许可证 CLI 可以在本地创建、验证、编辑和检查 OPF 文件，例如创建带有标题的演示文稿、验证文件或就地应用补丁。CLI 0.5.0 命令可为 AI Agent 在项目中安装六项 OPF 技能，使用本地副本，保留现有指令且拒绝覆盖自定义技能，并提供文档化的目标和预发布测试。文档涵盖了 Agent 技能、LLM 创作、动态组合和本地生态系统验证。 仓库布局亮点：顶层 Presentation 文档的规范 JSON Schema；关于文档模型、内容形状、目录解析和验证哲学的概念介绍；设计优先级算法（幻灯片设计、演示文稿设计、解析的主题、引擎默认值）；面向作者的顶层字段、Schema 定义、配套目录 Schemas 以及包括图表和表格在内的幻灯片/区域内容负载的参考资料；技术固定装置指南和面向场景的画廊示例；关于浏览器画布、字体加载和当前保真度限制的实时编辑器笔记；以及维护者发布运行手册。对于选择通过 HTTP 暴露 OPF 的下游服务，存在一个可选的参考 OpenAPI 合约，但 OpenPresentation 不托管该 API。 生态系统边界：渲染、编辑和转换功能位于独立的 MIT 兄弟仓库中 —— opf-render（OPF 转 SVG/PNG/PDF）、opf-editor（无头编辑器原语及可选 UI 组件）和 opf-pptx（纯本地 PPTX 导入/导出）。这些仅提供开源原语；下游应用程序负责托管、身份验证、存储、协作、队列、预览、分析、支持和工作流 UX。未来的 Python 和 Go 包预计将遵循相同的本地优先边界，公开 Schemas、模型、目录、验证和包可寻址资产，无需网络调用或隐藏的遥测。可通过 pptx.gallery 引用人类可浏览的目录预设，如布局、主题、颜色和字体方案、图表类型、叙事、受众、目的、语气、语言和社会平台。