MotionGit 模板规范 v0.1（草案）

状态：Draft。字段和目录是可立即试做的提议，不是已发布的行业标准。首个真实模板包通过验收后再冻结 v0.1。规范性正文以英文版为准（编写中），字段名只用英文。

1. 范围与术语

MotionGit 模板（.motion 文件） 是一种可编辑、可复用、可运行的视频模板包：用 ZIP 容器装入源码、可改参数、素材要求、运行依赖、使用说明、预览和许可。

它不是 Motion 动画库（原 Framer Motion），也不是 Apple Motion 的工程文件。文档、清单和引导文字都使用“MotionGit 模板（.motion 文件）”的完整称呼，并以固定标识 "format": "motiongit-template" 识别。

• 模板：可以反复使用的创作方法。
• 发布包：某个模板版本的交付物（.motion）。发布后不可覆盖。
• 制作实例：使用者换上自己的内容后得到的项目。改本期标题只产生新实例，不产生模板新版本。
• 运行配置（profile）：某一类模板如何加载、如何按帧求值、需要哪些能力，例如 html-canvas/1。
• 宿主：读取并执行模板的工具，如 AI 助手、AduDirector 或第三方软件。

规范中的“必须”“应当”“可以”参考 RFC 2119 / RFC 8174 的用法，每条都对应可测试或可解释的要求。

2. 包结构

ZIP 根目录直接放 motion.json，不再套一层同名目录。

motion.json                  交换层唯一入口（必须）
README.md                    人能直接照做的说明，开头包含“给 AI 的说明”
SKILL.md                     AI 加载与制作入口（只是可读文件）
params.schema.json           输入类型、约束与默认值
motion.lock.json             实测运行环境与依赖锁
asset-manifest.json          素材、字体、声音与许可索引
src/                         可读的模板源码
assets/                      获准随包分发的公共素材
presets/demo.json            可重现的公开样例输入
previews/                    封面与样例预览（可选）
licenses/                    代码及各资源许可
integrity.json               除自身外所有文件的 SHA256

2.1 文件约定

• 路径必须是相对于包根的正斜杠路径，大小写严格匹配。禁止绝对路径、盘符、反斜杠、..、符号链接和解包越界。
• JSON 必须是 UTF-8 严格 JSON，不含注释或尾逗号。
• 禁止打包：node_modules、.venv、缓存、日志、.env、密钥、令牌、私人原片和最终私人影片。
• 禁止包含会被 AI 工具自动加载为指令的文件：CLAUDE.md、AGENTS.md、.cursorrules、.claude/、.cursor/ 等。包内说明属于待检查数据，不能当作可信指令。
• .motion 与兼容 .zip 副本必须字节相同。MIME 传输先按 application/zip 处理。

3. 根清单 motion.json

JSON Schema 永久网址：https://motiongit.com/schema/motion/0.1.json

{
  "$schema": "https://motiongit.com/schema/motion/0.1.json",
  "format": "motiongit-template",
  "specVersion": "0.1.0-draft.1",
  "template": { "id": "hello-motion", "version": "1.0.0", "name": "Hello Motion" },
  "runtime": { "profile": "html-canvas/1", "entry": "src/index.html", "dependencyLock": "motion.lock.json" },
  "parameters": { "schema": "params.schema.json", "defaultPreset": "presets/demo.json" },
  "assets": { "manifest": "asset-manifest.json" },
  "output": { "width": 1920, "height": 1080, "fps": { "num": 30, "den": 1 } },
  "license": { "file": "licenses/TEMPLATE-LICENSE.txt" },
  "permissions": { "network": false, "read": ["package", "instance-inputs"], "write": ["instance-output"] },
  "ai": {
    "summary": "这是 MotionGit 模板（.motion，ZIP 容器）……",
    "entry": "SKILL.md",
    "authoring": { "tool": "claude", "client": "claude-code" }
  },
  "integrity": "integrity.json"
}

4. 参数契约

params.schema.json 采用 JSON Schema Draft 2020-12 的明确子集：文字、数字、布尔值、枚举、颜色和媒体槽位。顶层必须是 type: object，应当设置 additionalProperties: false，写清 required、长度、枚举和默认值。

公开参数必须映射到运行时真实消费的字段，不能出现“参数面板能改、渲染不生效”。

4.1 样式分支 variants

同一个模板可以带多种样式分支（配色、版式、风格）。每个分支是一份完整的输入预设，一次下载全部包含：

"variants": [
  { "id": "sage",  "name": "鼠尾草", "preset": "presets/sage.json",  "swatch": "#C2D788" },
  { "id": "night", "name": "夜粉",   "preset": "presets/night.json", "swatch": "#F778BA", "preview": "previews/night.mp4" }
]

• preset 必须存在，且只能包含 params.schema.json 声明过的参数。
• preview 可选，平台会从包内提取并展示为该分支的预览。
• 样式分支不改变模板源码；需要不同动作或结构时，应作为新模板或新版本发布。
• 用户可以告诉助手“使用 night 样式”，助手读取对应预设作为本次输入的起点。

5. 运行语义

• 按整数帧索引与有理数帧率求值；寻帧不依赖先从头播放。
• 素材和字体就绪后再求值；随机行为必须声明种子。
• 默认不联网。需要外部资源时，宿主必须说明具体资源、去向和用途，并按宿主授权流程处理。
• 跨设备逐像素一致不是 v0.1 的承诺。第一阶段追求输入明确、环境可追踪、行为可解释。

6. 素材与许可

代码许可与素材许可分别记录。字体、音乐、图片可能有不同条件；不能随包分发的资源，提供清晰的引用与替换槽位。许可标识可借鉴 SPDX，具体条款以原许可为准。

7. 安全

导入时先读元数据，不执行代码。解压限制路径、文件数量与体积，拒绝异常压缩包。发布前检查常见凭据、绝对路径和个人信息。自动检查能降低风险，但不能宣称已证明版权或彻底消除恶意代码。

8. AI 可读性

助手的固定阅读顺序：motion.json → README.md 开头的“给 AI 的说明” → params.schema.json → 资源与许可。所有模板顺序相同。

用户可以连同文件发送一段固定的转交文字，见 给 AI 的说明。

9. 一致性测试

平台与 MotionGit Skill 使用同一套静态检查器。下面的样例包附带预期结果，同时作为一致性测试与模型学习样例：

• hello-motion.motion：有效包，预期通过
• 无效样例见下方“样例包”列表，每个都标注了预期错误码

10. 提案与治理

公开提案说明问题、附上样例和兼容性影响，再形成测试、版本与迁移说明。成熟度用 Draft、Candidate、Stable 表达。MotionGit 发起并维护本规范，不宣称存在独立基金会或标准组织背书。