ograf.json 规范

文件结构

建议将 project.json 和 index.html 直接放在 ZIP 根目录，资源使用相对路径。上传接口也兼容单一顶层目录。Skill 打包通常使用 .ograf 扩展名，网站下载使用 .og.zip；两者都是 ZIP 压缩包。仅有 .ograf.json 不能替代网站上传所需的两个入口文件。

title.ograf / title-a1b2c3d4.og.zip
├── project.json
├── index.html
├── title-a1b2c3d4.ograf.json  (export)
└── assets/  (optional)

project.json 字段

这是 Skill 推荐的可移植基线。网站上传接口目前检查 project.json 为合法 JSON 对象，并执行包与文件扫描；上传通过不代表字段、播放行为与视觉效果全部正确。

标题动画的 project.json 示例

{
  "format": "ograf",
  "formatVersion": 1,
  "name": "标题淡入",
  "description": "透明背景的标题淡入动画",
  "version": "1.0.0",
  "resolution": "1920x1080",
  "fps": 30,
  "duration": 3,
  "supportsLandscape": true,
  "supportsPortrait": false,
  "data": {
    "title": "你好，OGRAF",
    "color": "#ffffff",
    "fontSize": 96
  },
  "schema": {
    "type": "object",
    "properties": {
      "title": {
        "type": "string",
        "title": "标题",
        "default": "你好，OGRAF"
      },
      "color": {
        "type": "string",
        "title": "颜色",
        "format": "color",
        "default": "#ffffff"
      },
      "fontSize": {
        "type": "number",
        "title": "字号",
        "minimum": 24,
        "maximum": 200,
        "default": 96
      }
    }
  },
  "renderRequirements": {
    "resolution": {
      "width": 1920,
      "height": 1080
    },
    "frameRate": 30,
    "accessToPublicInternet": false
  }
}

可编辑参数 schema

每个参数使用 type、title、description 和 default；数值可增加 minimum / maximum，选项可使用 enum。data 中的值应与字段类型一致，首次创建时与 default 保持一致。

.ograf.json 下载清单

网站下载 HTML 包时，保留原始 project.json、index.html 和资源，并保存当前参数。生成或更新一个 .ograf.json 清单：schema.properties 描述参数，schema.default 保存本次下载的配置，字段 default 同步更新。文件名带随机 8 位十六进制 ID，例如 title-a1b2c3d4.ograf.json，以减少达芬奇复用旧缓存的问题。

{
  "name": "标题淡入",
  "schema": {
    "type": "object",
    "properties": {
      "title": {
        "type": "string",
        "title": "标题",
        "default": "你好，OGRAF"
      },
      "color": {
        "type": "string",
        "title": "颜色",
        "format": "color",
        "default": "#ffffff"
      },
      "fontSize": {
        "type": "number",
        "title": "字号",
        "minimum": 24,
        "maximum": 200,
        "default": 96
      }
    },
    "default": {
      "title": "你好，OGRAF",
      "color": "#ffffff",
      "fontSize": 96
    }
  }
}

下例是网站 HTML 包的配置清单，不是所有桌面 OGRAF 宿主的完整入口规范。已有桌面包可能还需要 main 等字段，导出时应保留原有宿主入口。

HTML 播放协议

达芬奇组件由 main.js 导出 HTMLElement 子类，.ograf.json 的 main 指向该入口。可见动画舞台必须直接挂到 document.body；load({renderCharacteristics}) 提供的 resolution.width/height 是画布尺寸，优先于宿主盒子或浏览器视口。横屏宿主仍为 1920×1080 时，传入的 1080×1920 竖屏画布不能被缩进旧横屏盒子。只有宿主与画布比例一致时才等比缩放预览。卸载时清理舞台、监听器和动画任务。网站 index.html 使用同一实现，在 sandbox="allow-scripts" 的 iframe 中通过 window.postMessage 通信；不依赖 allow-same-origin 或 parent.document。

// Host → graphic
{ type: 'ograf:update', data: { title: 'Hello, OGRAF' } }
{ type: 'ograf:start' }
{ type: 'ograf:stop' }

// Graphic → host
parent.postMessage({ type: 'ograf:ready' }, '*');
parent.postMessage({ type: 'ograf:ended' }, '*');
parent.postMessage({ type: 'ograf:error', error: 'Playback failed' }, '*');

向宿主发送 parent.postMessage(message, "*")，以支持不透明源 iframe。动画接收时校验 event.source === parent；宿主校验消息来自目标 iframe.contentWindow。重复更新应得到同一画面，停止或重播时清除旧任务。用户文本用 textContent 写入。

资源与上传限制

允许 HTML、JS/MJS、CSS、JSON、PNG/JPEG/GIF/WebP/SVG/AVIF、WOFF/WOFF2/TTF/OTF、TXT/MD。脚本、样式、字体和图片均使用包内相对路径；不允许外链、网络请求、动态执行代码或访问 Cookie、存储等敏感 API。不允许路径穿越、绝对路径、重复条目、符号链接与损坏的 ZIP。服务端按实际解压内容扫描，静态扫描不等于完整安全保证。1 KiB = 1024 字节。

发布前检查

1. 本地校验通过，包内入口文件与相对资源路径完整。
2. 实际预览检查标题、颜色、字号及参数即时更新。
3. 播放、停止、连续重播和结束通知正常，无残留动画任务。
4. 透明背景、设计分辨率和声明的横竖屏效果正确。
5. 通过 Skill 上传草稿并完成社区发布，再核对公开预览和下载包。