包格式

.ipwt 文件是 ZIP 压缩包。manifest.json 必须直接位于压缩包根目录，不要把所有文件再包进一层父目录。

归档契约模板包在变成新项目之前要通过三道检查

包结构、manifest 兼容性和会话 materialization 都必须成功。

01根目录布局
将 `manifest.json`、声明入口和所有相对资产直接放在归档树中。
02校验
导入器检查身份、文件安全、大小限制以及 category/surface/entry 兼容性。
03安装
通过校验的归档会作为可复用源进入个人 Template Market 库。
04生成副本
使用模板会创建独立会话归属副本，而不是编辑库中模板包。

acme-growth-brief.ipwt
├── manifest.json
├── cover.svg
├── entry.html
├── design-tokens.css
└── assets/
    └── chart.png

视频模板使用 index.html 替代 entry.html。

Manifest

每个模板包都使用版本化 manifest。v1 的 kind 保持为 "design"，由 surface 决定模板在哪个编辑器中打开。

{
  "schemaVersion": 1,
  "id": "acme.growth-brief",
  "version": "1.0.0",
  "kind": "design",
  "category": "report",
  "style": "editorial",
  "tags": ["growth", "weekly"],
  "surface": "design",
  "title": "Growth Brief",
  "description": "A concise weekly operating report for product and growth teams.",
  "cover": "cover.svg",
  "entry": "entry.html",
  "designSystem": {
    "tokenVersion": 1,
    "tokens": "design-tokens.css",
    "editableGroups": ["theme", "background", "typography", "components"],
    "variables": [
      { "id": "--ipw-color-primary", "label": "Primary", "type": "color", "group": "theme" }
    ]
  },
  "minimumAppVersion": "0.17.20"
}

校验规则

id 使用小写，并至少包含一个 . 或 -。
本地包不能使用保留的 ipollowork.* 命名空间。
版本使用语义化版本，例如 1.2.0。
视频包必须设置 category: "video"、surface: "video"，并使用 index.html。
只使用相对文件路径。导入器会拒绝符号链接、可执行文件、绝对路径、路径穿越和重复路径。
当前导入器接受 HTML、CSS、JavaScript、JSON、图像、字体、文本、Markdown、LICENSE 和 NOTICE 文件。

当前限制为：压缩包 50 MB，解压后 200 MB，最多 1,000 个文件，单文件最大 25 MB。

保持编辑契约

对于 Design 模板，designSystem.tokens 应指向包含所声明 --ipw-* 变量的样式表。editableGroups 与 variables 只能描述作者确实已经保证可安全修改的值。变量 ID 必须存在于 token 样式表中；不要把页面中其他位置硬编码的值伪装成可编辑变量。

对于 Video 模板，应将 HyperFrames 合成保留在根目录 index.html，并定义非空 data-composition-variables 数组。视频变量是 Video Studio 的编辑契约；普通 Design 包不应为了共享一个色彩 token 而加入视频运行时。

将校验失败视为设计反馈

失败	通常意味着	正确处理
缺少根 manifest	从错误父目录创建了 ZIP。	重新打包，使文件位于归档根目录。
category、surface 或 entry 无效	混用了 Design 与 Video 契约。	选择目标编辑器，并匹配其必需入口。
路径或文件被拒绝	包中存在不可移植或不安全产物。	移除可执行文件、链接、路径穿越、重复或绝对路径内容。
变量不可用	Manifest 元数据与可编辑源不匹配。	添加声明 token/binding，或从契约中移除它。

创建归档前请阅读 模板创作契约，其中解释了每个编辑器在导入后真正需要什么。

创建压缩包

在包含 manifest.json 的目录运行：

zip -r acme-growth-brief.ipwt manifest.json cover.svg entry.html design-tokens.css assets

请将模板源码保存在版本控制中。.ipwt 是分发产物，而不是唯一的模板来源。

Manifest

校验规则

保持编辑契约

将校验失败视为设计反馈

创建压缩包

本页目录