模板创作契约

构建保留可编辑结构、通过当前导入规则，并能安全生成会话归属副本的 Design 与 Video 模板。

iPolloWork 模板是可复现的起点，不是截图，也不是保存的一段聊天回复。模板包必须告诉导入器它包含什么，告诉目标编辑器哪些内容可以安全编辑，并在变为新的会话归属项目时保持自包含。

模板契约一个归档包、三类消费者、一个事实来源

导入器校验包，编辑器使用声明的 surface 与变量，会话生成自己的副本。

创作源

创作者维护什么

静态项目

HTML、CSS、JavaScript 与本地资产在版本控制中维护，并只使用相对路径。

Manifest

声明身份、版本、分类、surface、入口、许可证与编辑契约。

导入边界

导入器接受什么

.ipwt 归档包

以 `manifest.json` 作为根文件的 ZIP 包，不能有不安全路径或可执行 payload。

校验

检查 schema、category/surface/entry 兼容性、大小限制和允许的文件类型。

会话产物

用户实际编辑什么

新会话副本

使用模板会生成一个独立的、会话归属的项目。

规范记录

会话记录让侧栏、编辑器与 Agent 指令使用同一个模板身份。

选择正确的编辑 surface

模板类型	Manifest 值	入口契约	面向编辑器的契约
网站、应用、演示文稿、海报、卡片、报告或文章	设计分类及 `surface: "design"`	按惯例使用静态 `entry.html`	语义 HTML、CSS token、稳定选择器、相对资产
HyperFrames 视频	`category: "video"` 与 `surface: "video"`	包根目录的 `index.html`	有效合成结构与 `data-composition-variables`

当前 v1 manifest 对两类模板都使用 kind: "design"，由 surface 选择编辑器。视频包必须同时使用 video 分类、video surface 和根目录 index.html。导入器会拒绝不匹配组合，因为 Design 项目与 HyperFrames 合成有不同的运行时契约。

把 Design 模板写成结构化文档

Design 模板是普通的可编辑网页项目。使用自包含 HTML 入口、语义 landmark、编辑器或 Agent 需要时的稳定 ID、响应式 CSS，以及能让修改安全的 token 化值。将页面布局压平成一张图片的模板不是可编辑的 Design 源码。

Design 编辑契约将持久结构与用户应改变的值分开

好的模板暴露少量具名的修改面，同时保留底层文档结构。

01结构
使用语义 HTML 描述页面、段落、数据区域与可复用组件。
02Token 化
将可复用视觉值保留在声明的 token 样式表中，优先使用 `--ipw-*` 自定义属性。
03暴露
声明 `designSystem.variables` 作为受支持编辑控件，并按用户决策分组。
04验证
打开新的会话副本，在修改后同时检查常规尺寸与窄屏布局。

示例创作约定：

<link rel="stylesheet" href="design-tokens.css" />
<h1 data-ipw-text="hero.title">Make the signal visible.</h1>
<article data-ipw-card>...</article>

这些属性是让创作工具与 Agent 更容易定位内容的约定；核心要求仍是一个真实、结构化且可编辑的项目。建议使用 16:9 SVG 或 PNG 作为封面，使 Template Market 卡片清晰。

把 Video 模板写成一个隔离合成

Video 模板是 HyperFrames 项目。活动项目位于会话的 video/<session-id>/index.html；Video 模板必须在包根目录保留可播放的 index.html，以便 materializer 创建会话归属项目。不要在模板中启动第二个预览服务——嵌入式预览由 iPolloWork 负责。

<html data-composition-variables='[
  {"id":"title","type":"string","label":"Title","default":"Product Reveal"},
  {"id":"accent","type":"color","label":"Accent","default":"#3a9fca"}
]'>
  <body>
    <div id="root" data-composition-id="main" data-start="0" data-width="1920" data-height="1080" data-duration="6">
      <section id="scene-main" class="clip" data-start="0" data-duration="6" data-track-index="1" style="color: var(--accent)">
        <h1 id="title" data-var-text="title">Product Reveal</h1>
      </section>
    </div>
  </body>
</html>

每个视频变量都需要 id、type、label 和 default；enum 还需要 options。标量变量会成为合成根节点的 CSS 变量，data-var-text 与 data-var-src 提供直接绑定。导入前，运行内置视频模板相同的结构检查：

npx --yes hyperframes@0.7.52 check . --strict --at-transitions

防御性打包

导入器接受静态 HTML、CSS、JavaScript、JSON、图像、字体、文本、Markdown、LICENSE 和 NOTICE 文件。它会拒绝符号链接、可执行文件、绝对路径、.. 路径穿越和重复路径。当前限制为压缩包 50 MB、解压后 200 MB、1,000 个文件以及每文件 25 MB。

使用小写且语义明确的 ID，如 acme.growth-brief；本地包不能使用保留的 ipollowork.* 命名空间。语义版本号应有意义：演进包时更新版本，真正不同的模板则使用新的 ID。

能发现真实失败的发布检查

从干净源目录构建，并只引用相对资产路径。
检查归档根目录：manifest.json 不能嵌套在额外文件夹中。
确认 category、surface 与 entry 兼容。
将 .ipwt 导入 Template Market 并选择 Use。
验证新创建的会话，而不是库条目。
对 Design，修改每个声明的 editable group，并检查窄屏。
对 Video，运行 HyperFrames 校验、预览完整时长，并操作每个声明变量。
将源代码保留在版本控制中；.ipwt 仅是分发产物。

有关具体 manifest 与归档结构请阅读 包格式，然后再阅读 Design 模板 或 Video 模板。